This guide describes the current source tree. A published executable can implement an older contract; inspect its version and release notes before integrating a newer surface. The ADR index records the decisions and the limits of each implementation slice.
Runtime topology
| Layer | Responsibility | Dependency rule |
|---|---|---|
| Edges | CLI parsing, MCP transport, host/source/model adapters | Call typed core use cases; keep credentials and transport concerns outside core |
| Core | Retrieval, proposals, review, source decisions and verification | Share behavior across CLI and MCP; no clap, rmcp or direct transport dependencies |
| Data | Markdown store, SQLite index, configuration and evidence metadata | Provide persistence primitives used by the core |
Every read or write supported by an edge must bind to the corresponding shared core
operation. An interface-specific approval rule is a drift defect. Synchronous SQLite work
runs through spawn_blocking at the MCP boundary; other CLI commands do not need a
long-running server.
Knowledge lifecycle
The knowledge process contract is a bounded CLI/MCP interface for hosts such as Soma. It returns source-cited passages with raw whole-file digests, accepted head, source manifest and explicit omissions. Hosts pin the actual executable and enforce stdout limits, cancellation and hard deadlines independently of the core budget.
Knowledge proposals always queue. An operator reviews the exact payload, then acceptance rechecks source head, manifest, original source revisions, policy and review digest. An MCP caller may describe, query, propose and review; it cannot invoke local operator acceptance. Other write tools retain their own documented proposal and safe-application policy rules. Read content and model confidence never grant permission.
Content, projection and operational state
| State | Role | Preservation requirement |
|---|---|---|
| User Markdown | Current knowledge content and typed frontmatter | Keep in the user’s selected Git/backup workflow |
| SQLite search projection | FTS, links, tags and optional vectors | Rebuild derived retrieval data with syn reindex |
| Operational queue | Pending payloads, context and review guards | Retain separately; Markdown cannot reconstruct lost pending rows |
| Governed source metadata | Accepted transitions, retained images, original receipts and seals | Preserve with the governed workspace; missing evidence reduces or fails coverage |
| Independently selected trust and witnesses | Verifier roots, pins and observed checkpoints | Keep independently of the artifacts they are meant to constrain |
yaml_serde handles frontmatter with ordered mappings
(ADR-054). Serialization preserves the
supported field semantics and order; it does not preserve every original YAML comment or
quoting choice. Entity identity is (type, id), so project/alfa and api/alfa may coexist.
Slugs follow the documented ASCII kebab-case rules. Explicit rename operations update
supported references through one workspace transaction.
The index materializes relationships such as project membership, API ownership and task scope. Every SQLite connection enables foreign keys. Reindexing repairs the derived projection; it cannot manufacture lost review context or erase a governed source mismatch.
Durable source transactions
The transaction protocol is documented in ADR-056, extended by ADR-057, ADR-058 and ADR-065.
| Stage | Durable decision and recovery behavior |
|---|---|
| Acquire | Take the cooperative writer lease and recover any preceding intent |
| Prepare | Stage writes/deletes, retain preimages and fsync a versioned prepare document |
| Install | Install the prepared source while retaining recovery material |
| Commit | Commit index changes and an exact prepare-digest marker in the same SQLite transaction |
| Publish evidence | Publish the retained original receipt, source record, shared seal where required, and accepted head |
| Recover | A matching committed marker rolls forward; an absent marker restores preimages; unexpected content fails closed |
Repeated recovery reuses the original committed bytes. It does not request a new signature or reinterpret historical approval as current permission. Changed database incarnation, path escapes and unexpected external edits preserve evidence and refuse unsafe repair.
The writer lease is advisory. External editors and raw filesystem readers can observe a short installation window. Unix directory fsync provides the documented power-loss ordering; other platforms have a narrower durability claim. A privileged disk owner, complete disk loss and dishonest hardware require independently retained evidence and backups.
Source history and verification
An explicitly acknowledged baseline starts the governed Markdown suffix. Unknown preceding history remains unknown. In an opted-in workspace, mutations require current content to match the accepted manifest; external changes need explicit reconciliation.
Source images are retained as private plaintext metadata. Manual retention, filesystem permissions and encryption policy matter: hashes provide no confidentiality. Attachments, keys, arbitrary non-Markdown files and excluded directories are outside the documented Markdown evidence scope.
| Verification facet | What it can establish | What it cannot establish alone |
|---|---|---|
syn verify | Named projection, history and supported structured invariants | Universal truth, complete receipt coverage or authenticated team authority |
| Source manifests and transitions | Selected raw bytes and causal ordering from the acknowledged baseline | Unknown pre-baseline history or independent non-rewrite evidence |
| Stored receipt signatures | Integrity of available original receipt bytes | A trusted employee/device identity from an embedded key alone |
| Strict-local assurance | Required selected source, receipt, trust and witness inputs | Current organizational permission |
| Strict-team assurance | Required original shared evidence with independently selected roots, lifecycle observations and witness coverage | Permission for a new publication or every natural-language claim |
A successful historical check has a different purpose from a current operation permit. Missing, unsigned, stale or skipped inputs remain visible. Complete strict profiles deny required gaps instead of silently downgrading them. See provability, ADR-066 and ADR-067.
Retrieval and optional models
Hybrid retrieval combines FTS5/BM25, optional vector search and graph-neighborhood signals
through reciprocal rank fusion. A model-ready local binary can use the configured semantic
backends; without consented model assets, retrieval degrades to supported lexical/graph
paths without downloading a model implicitly. --semantic and --no-vector select the
documented search modes.
The default semantic stack uses local embeddings and entity recognition. Optional network providers require explicit configuration. Insertion-time enrichment can add supported vectors and link proposals, subject to the native transaction and proposal rules. The model guide explains downloads, cache and provider choices.
The bounded host knowledge query intentionally uses scoped lexical retrieval and does
not start model inference. General contradiction assessment is a separate experimental
advisory port. Exact diagnostics check selected fields, intervals and reference classes;
probabilistic output cannot change those results, source or authority. The current grouped
experiment failed its recall gate, so it establishes no default semantic-consistency model.
See ADR-062,
ADR-068 and the
measured experiment.
Hosts, source adapters and shared authority
A local-owner workflow remains account-free. A host such as Soma can add account, workspace, project and device authority without sending private signing keys or bearer credentials to Synapse. The native shared bridge requires fresh scoped public host evidence; the local knowledge contract rejects shared authority rather than falling back to local privilege.
Shared candidates freeze exact source bytes before independent review. Publication resumes an explicitly selected candidate and requires fresh current admission. Historical seals remain historical evidence after their operation lease expires. Supported shared built-in mutations, offline provisional notes and the remaining adoption-pilot boundary are described in SHARED_SOURCE.md.
Current external source adapters read Git/Markdown and optional GitHub. Every passage or impact projection rechecks upstream revision and access; there is no stale remote-body cache fallback. A change produces bounded review candidates and metadata lineage. Native local annotations preserve exact upstream citations, while shared source-derived acceptance and all upstream write-back remain disabled in this slice. Notion, Jira and Confluence adapters are planned integrations. See source adapters and source evolution.
Code map and maintenance
| Concern | Entry point |
|---|---|
| CLI and MCP | src/cli.rs, src/cli/, src/mcp/ |
| Bounded host knowledge contract | src/core/knowledge/ |
| Governed source and shared bridge | src/core/governed_state.rs, src/core/shared_source.rs, src/core/source_candidates.rs |
| Durable persistence | src/store/transaction.rs, src/store/transaction/prepare.rs, src/store/governed_state.rs |
| Exact diagnostics and verification | src/core/exact_contradictions.rs, src/core/verify/ |
| Retrieval and models | src/core/search/, src/core/embeddings/ |
| Portable public authority contracts | crates/synapse-evidence/ |
The current source exposes 42 MCP tools; consult MCP.md for the actual surface. Do not infer a packaged release’s tool count from the source-tree documentation. Module size thresholds and review rules remain in ADR-015. Update diagrams when a responsibility, arrow or trust boundary changes, using the visual asset notes.