ADR-063: Versioned bounded knowledge process contract
Date: 2026-10-13 Status: Accepted Amends: ADR-049 implementation contract
Context
Existing CLI/MCP tools share core behavior but do not provide an explicit embedding handshake, stable process envelopes or a single budgeted source-revision contract. Soma needs reusable knowledge without copying its operational history into notes.
Decision
Add a version-1 request/response envelope through a CLI stdin JSON door and an MCP tool, both executing one core contract. Describe exposes actual protocol/build target and supported operations. Requests select an exact canonical workspace and acknowledged knowledge GUID; local owner scope is not remote authorization. Shared authority remains unsupported until the native source admission bridge is complete. An unsupported shared request fails instead of falling back to local.
Read uses scoped lexical retrieval without models/network, before candidate selection. Returned raw Markdown passages bind typed IDs, source paths, whole-file SHA-256, byte/line ranges, accepted head and explicit omissions. Source drift and mixed snapshots fail; basic source integrity does not prove authorship, all index semantics, independent history or model attention.
Budgets bound request/results/output bytes and elapsed core work. Optional token budgets use explicitly selected cl100k_base via a pinned offline tokenizer; counts apply to supplied passage text, not an arbitrary target model or its hidden prompt. The process client independently bounds stdout and enforces deadline/cancellation.
Proposals always queue for explicit review, including when an old auto-apply policy would allow a direct tool write. Capture links run/context/source references, an idempotency key, exact accepted head/source manifest and effective native policy. Review returns exact retained payload and metadata; the local operator CLI acceptance rechecks these preconditions inside the native source transaction. Old pending accept doors use the same guard, so switching clients cannot bypass it. Shared acceptance is denied. The MCP caller can query/propose/review but cannot mint operator acceptance; it gets local_operator_acceptance_required. This preserves the existing agent/human gate. Queue idempotency lasts while its operational index records are retained; explicit prune/index destruction is not claimed to preserve a durable request ledger.
Clients independently pin executable digest and architecture; managed release metadata additionally requires a separately selected publisher key. A hash or self-reported build/version does not establish release identity. No daemon, FFI, global MCP editing, automatic model download or latest-version upgrade is required.
Verification
Exercise scoped query/citations/omissions, real token counts and budgets, source drift/scope errors, exact proposal retries, changed request conflict, stale head, source and native policy, old-client acceptance guards and CLI/MCP parity. Soma must prove the pinned-binary read/run/review/propose/accept/reuse loop, signature and architecture checks, malformed responses and deadline/cancel behavior before the integration issues are closed.