Composable knowledge framework and trust architecture

Date: 2026-10-12 · Status: accepted architectural direction; runtime not implemented here Baseline: 3ceddd0 · Owner: Rômulo Febasi

Product

Operational memory for agents, with governed changes, preserved history, and explicit integrity checks.

Synapse is an independently usable knowledge dependency for agents, Soma and other clients. It complements Notion, Jira, Confluence, Obsidian, documentation repositories, Git and MCP. Bridges may use QMD, Mem0 or Zep for retrieval/memory with transparent trust mapping. No claim to replace those tools or prove the truth of all prose.

Keep the existing edge -> core -> data rule. Provide optimized, budgeted source-linked queries and governed proposals. A dashboard can use a bundled/installed binary via direct argv/JSON; HTTP/FFI is not necessary initially. This design does not create a running API or install a model.

Existing state and gaps

Existing audit/version schemas remain readable. A new design does not retroactively attest old events or automatically promote all workspaces to strict assurance.

Components

flowchart TB
  Sources["Documentation<br/>and API sources"] --> Acquisition["Optional source<br/>adapters"]
  Acquisition --> Revision["Revision and<br/>access filter"]
  Revision --> Candidates["Candidate facts<br/>and changes"]
  Candidates --> Retrieval["Scoped retrieval"]
  Retrieval --> Decision["Optional typed<br/>decision provider"]
  Decision --> Proposals["Reviewable proposals"]
  Candidates --> Exact["Deterministic checks"]
  Exact --> Proposals
  Proposals --> Gate["Authority and<br/>acceptance gate"]
  Gate --> Transition["Durable transition<br/>and receipt"]
  Transition --> Markdown["Markdown content"]
  Markdown --> Index["Disposable index"]
  Transition --> Verify["Profile-aware<br/>verifier"]
  Verify --> Witness["Optional independent<br/>witness"]
  Client["Soma or<br/>another agent"] --> Query["CLI JSON or MCP"]
  Query --> Retrieval
  Query --> Proposals
  classDef edge fill:#ede9fe,stroke:#7c3aed,color:#2e1065,stroke-width:1.5px
  classDef core fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e,stroke-width:1.5px
  classDef governance fill:#fef3c7,stroke:#d97706,color:#78350f,stroke-width:1.5px
  classDef storage fill:#f1f5f9,stroke:#64748b,color:#0f172a,stroke-width:1.5px
  class Sources,Acquisition,Decision,Client,Query,Witness edge
  class Revision,Candidates,Retrieval,Exact,Verify core
  class Proposals,Gate,Transition governance
  class Markdown,Index storage

SourceAdapter performs acquisition at an edge; DecisionProvider performs optional judgment at an edge; core consumes typed data and deterministic policies. Never put network I/O/model runtime/identity login into pure core. RetrievalProvider/KnowledgeClient adapters declare their evidence/trust capabilities; foreign memory output is not automatically a Synapse-authenticated fact.

Query and proposal contract

A KnowledgeQuery specifies workspace/project/source scope, authorized principal/policy evidence when shared, purpose, query, API/version/environment/time filters, token/latency budget and requested assurance. Local owner access and shared access are distinct modes.

A KnowledgeResult returns bounded passages/facts, source/ref/revision/content digest, observation/valid times, freshness, confidence class, retrieval score, applicable verified coverage, omitted/unavailable reasons and optional grounded summary citations. A score does not establish truth or policy authority. No invented citations; insufficient evidence produces abstention.

ACL must constrain candidate retrieval before ranking/model calls and output; do not retrieve everything then merely hide the final text. Cache includes source/ACL/policy/model revisions and is invalidated on changes. For remote-source data, offline use requires an explicit bounded lease; otherwise unavailable. Source deletion/access loss triggers policy-governed restriction/redaction of cached passages. Receipts preserve evidence commitments under retention but do not override current document access.

A KnowledgeProposal includes a stable idempotency key, candidate changes, source digests/expected revisions, run/context reference and decision diagnostics. Only approved changes pass current authority checks. Client APIs expose proposal/review/receipt states; raw transcript persistence is not the default. Reference documents remain canonical in their own tools.

Source revision and shared knowledge lifecycle

observed -> analyzed -> proposed -> reviewed -> accepted -> superseded is separate from the acquisition state (available, deleted, access_lost, fetch_failed). Content observed upstream is evidence until accepted as operational knowledge.

SourceRef: connector/source IDs, document/revision ID, URI, digest, observed time, access policy reference and optional API/version/environment identity. A candidate binds concrete source versions; a patch uses expected-upstream-revision to prevent stale write-back. Store secret handles only at the edge.

Deduplicate revision events and reconcile gaps after webhook/poll loss. Start with Git/Markdown and one remote source, then add Notion/Jira/Confluence/Obsidian adapters. File import/export is not continuous source synchronization. ADR-043 agent composition remains available; optional source workers amend its blanket exclusion of native acquisition.

Example: an authentication contract changes on Payments API v2. consumes/depends_on edges identify impacted project/squad records. Generate source-linked updates and documentation patches for authorized consumers; suppress unauthorized existence/impact details. Preserve old valid versions instead of declaring v1/prod/staging notes mutually contradictory. Maintainer acceptance, upstream publication and consumer acknowledgment are different recorded actions.

Probabilistic decisions and small models

Pipeline: ACL/scope filter -> bounded hybrid candidates -> exact structural/date/version rules -> pairwise NLI/typed decisions -> abstention/review -> authorized acceptance. Candidate recall bounds the entire system: an unseen conflicting note cannot be classified.

Use typed relations (contradiction, entails, independent, temporal_change, insufficient_context), source evidence spans, provider/model version, rubric/schema digest and uncertainty. A native NLI model outputs contradiction/entailment/neutral; richer business labels require explicit context/rule composition. Dates/counts/permissions stay in code. ML diagnostics stay outside deterministic invariants.

Jev is a useful optional hosted decision provider with Choice/Score/Noul. Do not assume small parameter count, local weights, perfect correctness or offline execution. Benchmark it against a permissively licensed local NLI candidate and rules+retrieval. Model selection/default changes require EN/PT evidence, resource/license/runtime checks, egress policy and fallback. Details: research protocol.

Authenticated transitions

Current Markdown is content; a sealed journal proves a governed mutation suffix. Journal records bind complete managed-file before/after inventories, content-image references, proposal/context/rule digests, actor/device, sequence/parents and schema/canonicalization. Cover deletions/renames and composite type+entity identities. Explicitly list unmanaged/excluded paths.

Hashes without retained payloads do not reconstruct history. Maintain retrievable pre/post images under encryption/retention policy. Canonical encodings use domain separation and exact types with test vectors. Existing signatures are not silently reinterpreted under new canonicalization.

%%{init: {'sequence': {'actorMargin': 20, 'width': 110}}}%%
sequenceDiagram
  participant Client
  participant Gate as Policy and<br/>identity gate
  participant Tx as Durable<br/>coordinator
  participant Store as Markdown<br/>and index
  participant Evidence as Journal<br/>and receipt
  Client->>Gate: Proposal with<br/>expected state
  Gate->>Gate: Check current scope<br/>and authority
  Gate->>Tx: Authorized transition
  Tx->>Tx: Lock and<br/>durable prepare
  Tx->>Store: Apply checked postimage<br/>and projection
  Tx->>Evidence: Persist signed<br/>transition receipt
  Tx->>Tx: Durable commit marker
  Tx-->>Client: Committed transition id

The coordinator recovers a prepared mutation after crash or quarantines mismatched state; acknowledge only after durable commit. Index rebuild remains independent. Direct Markdown edits are allowed as user content changes but become Unattested drift until reconciled; reindex cannot erase that fact. A missing/new managed file also changes the manifest.

Migrate through an owner-acknowledged baseline and explicitly limited coverage start. Never manufacture old authorship. Concurrent writers reference accepted parents and reject stale preconditions; divergent changes require review, not last-write-wins. Run crash tests around all filesystem/index/journal/receipt boundaries before claiming atomic acceptance.

Receipts, reports and assurance

Semantic diagnostics appear separately as assessed/unknown; no model confidence creates a deterministic Pass. Missing optional ML does not invalidate storage integrity, but a required semantic-review procedure can stop acceptance until reviewed. Report current data integrity, historical transitions, signer identity, authority evidence, witness consistency and exclusions separately.

Define a versioned v2 report/extension with baseline/head, covered range, required/available/failed checks, pinned policy and evidence references. Readers retain the v1 contract. A basic zero exit code cannot appear in Soma/CI as all guarantees verified. Stored receipts replace INV-8 Skip only when implemented.

Receipt verification uses trusted roots/bindings, not merely the embedded public key. Pin historical trust/witness snapshots; distinguish revocation now, compromise-at-time, and authority for a new approval. Standard in-toto/DSSE packaging is useful after the native evidence is real; C2PA is not a required MVP dependency.

Identity and independent witnessing

OIDC authenticates (issuer,sub) online; device proof-of-possession binds that subject to a signing key. The external authority grants workspace/project actions and exports signed roster/binding evidence. Private keys and bearer/refresh/ID tokens never enter the knowledge store or public witness. Synapse core verifies exported typed evidence offline without implementing an IdP.

Offline proposals can be prepared using a cached snapshot; shared acceptance requires fresh server revalidation. An offline verifier states revocation freshness and cannot know unseen updates. Verify genuine SSHSIG signatures through existing SYN-261; detecting gpgsig remains posture only.

Start with existing git/ed25519 plus an independently retained signed witness. Hash/Merkle/append-only concepts from blockchains are useful without operating a blockchain. Public anchoring must disclose metadata/low-entropy digest inference risk; commit only a deliberately privacy-preserving checkpoint envelope. No document, prompt, key or token is placed on-chain. Public Sigstore is optional; private knowledge may prefer a private witness. Witnesses must compare/retain checkpoints to expose equivocation.

Delivery and verification gates

1. Clarify product/current guarantee boundaries and versioned embedding contract (existing SYN-321).
2. Implement sealed transitions and crash-safe migration; then persisted receipts/strict profiles.
3. In parallel as an independent spike, evaluate typed decisions; ship only measured local/hosted options.
4. Add device/subject binding and real signature/authority enforcement before strict-team acceptance.
5. Add source-revision/impact semantics and one adapter; integrate the Soma pilot.

Scope-preserving tests: legacy/v2 readers, canonical vectors, create/update/delete/rename, unauthorized/direct edits, journal truncation/fork, crash recovery, wrong signer, absent receipt, stale/revoked authority, source ACL loss, stale patches, EN/PT diagnostics and model failure.

No runtime tests are executed for this documentation change. Future implementation uses the repository gates (cargo fmt --check, cargo clippy --all-targets --all-features -- -D warnings, cargo nextest run --all-features, doctests/docs and cargo deny check on dependency changes). A new model/runtime or transport requires a corresponding ADR and measured budget.

ADRs and deduplicated work

• ADR-049: consumption/source evolution.
• ADR-050: probabilistic diagnostic boundary.
• ADR-051: transition coverage and witness.
• ADR-052: strict assurance.
• ADR-053: identity/authority.
• architecture: https://github.com/romulofebasi/synapse/issues/307
• decisions: https://github.com/romulofebasi/synapse/issues/308
• transitions: https://github.com/romulofebasi/synapse/issues/309
• assurance: https://github.com/romulofebasi/synapse/issues/310
• identity: https://github.com/romulofebasi/synapse/issues/311
• sources: https://github.com/romulofebasi/synapse/issues/312

Reuse: SYN-321 #306, SYN-320 #305, SYN-319 #304, SYN-261 #249, SYN-231 #222, SYN-206 #96, SYN-318 #303. No duplicate team/connector/SSHSIG/envelope issue is created.

Primary references

• OIDC Core
• Merkle inclusion/consistency
• Canonical JSON
• Sigstore bundle
• TypeSafe decisions
• Companion Soma design