Skip to content

ADR-001: Governed Semantic Objects as the Business Index Source of Truth

Status: Accepted for the first Business Index SOSA implementation cycle
Date: 2026-07-20

Context

Business Index currently retrieves semantically similar text chunks. This is a useful baseline but cannot preserve business-concept identity, evidence-backed relationships, interpretation history, or governed corrections.

SOSA is independent architecture IP. Business Index must implement SOSA without copying or redefining the framework inside the product repository.

Decision

Business Index will treat a governed Semantic Object as its primary unit of business knowledge. Source files, extracted text, chunks, embeddings, prompts, and model responses are supporting inputs or derived representations.

The product will use four persistence boundaries:

  1. Source record: stable source asset identity plus immutable content versions and addressable evidence spans.
  2. Meaning record: durable Semantic Object identity plus immutable object versions and aliases.
  3. Connection record: typed, directional relationship versions with their own evidence and epistemic state.
  4. Derived index: lexical and vector representations that may be deleted or rebuilt without changing durable meaning.

Local model output enters as an unreviewed candidate. A normalization boundary accepts only the five product object types and the documented relationship types. The persistence layer validates evidence before it creates an object version or relationship.

Automatic identity resolution is intentionally conservative. A Client may reuse one exact normalized canonical label or evidenced alias match. Projects, Decisions, Commitments, and Problems also require an existing relationship to a resolved neighbouring object before reuse. No match creates a new object. Context-free or multiple matches create an auditable duplicate candidate and do not silently merge identities.

Consequences

  • Re-ingestion can replace disposable chunks while retaining governed history.
  • Embedding or model replacement rebuilds representations, not object identity.
  • Query results can distinguish source facts, Semantic Objects, relationships, inferences, and generated summaries.
  • Storage and ingestion become more complex because evidence and versions are first-class records.
  • Extracted candidates remain uncertain until user confirmation; confidence is never a substitute for epistemic state.

Recovery and rollback

Migration 002_sosa_core.sql is additive. If application rollback is needed, the previous application version can continue using the original source, chunk, and chat tables. The new governed tables should be retained so no audit history is lost. A later destructive removal requires an explicit backup and a separate authorized migration; it is not part of this decision.