1.7 KiB
The runtime contract is two-tier, with api-reference.md authoritative
Context. Before the TypeScript migration and module extraction, we need to
pin what "the contract" is so refactoring cannot silently change observable
behavior. The four verbs (build/search/query/attune) are only the entry
surface; agents actually depend on the return shapes of the sandbox helpers
(search, overview, memories, …), which are already documented in
references/api-reference.md and relied on by every example in
references/query-patterns.md. Current behavior is good and there is no reason to
change it during migration.
Decision. Freeze the contract in two tiers. Tier 1 (hard freeze, golden
tests): the four-verb CLI I/O envelope (file/args → pretty JSON on stdout,
{error, stack} error envelope, exit codes) and the sandbox contract (sql()
read-only enforcement, attune exposing only remember/forget, the set of
globals/helpers available inside query/attune). Tier 2 (locked to
api-reference.md): each helper's documented return shape — not frozen forever,
but never allowed to drift silently; contract tests assert the live shape matches
references/api-reference.md, so changing a helper forces a doc change plus a
deliberate version bump. references/api-reference.md is therefore promoted from
description to authoritative contract, and Phase 1 becomes "make it authoritative
and enforce it," not "write a new contract doc."
Consequences. Behavior is preserved across the TS/module refactor by construction: the golden and contract tests fail if any observable shape moves. The cost is that helper shapes can no longer be reshaped casually mid-migration.