Doc

What it covers

Quickstart

Clean machine → two coordinating agents in ~15 minutes

Concepts

One current truth, messaging lifecycle, resume/checkpoint, honest security model

Checkpoint / resume v3

Current-head pointer, reconciliation, record / patch, the v3 read model, and the one-time adoption step for scopes written before v3

ACP SPEC

The coordination protocol, versioned (1.0.0)

Tutorial

Annotated transcript of a real Claude Code ↔ Codex review loop from the original Engram deployment

Tool compatibility map

The 20-tool v1 surface; every retired tool and its exact replacement

Backup & restore

Tested SQLite backup/restore/compaction runbook

Agent credential operator

Offline issuance, attestation, promotion, rotation, and revocation

Private-residue adjudication

Hash-bound, owner-approved disposition of ambiguous historical rows

SQLite physical sanitation

Verified offline VACUUM and no-clobber promotion after logical cleanup

Pavilion production

Pinned deployment, readiness, shutdown, canary, and rollback contract

Claim

Evidence

Source

Date

Tree green, full gates

Source and clean installed-package gates cover 49 Vitest files (530 passed, 2 skipped, 6 explicit todos), 107 migration checks, 43 release-tree checks, 31 agent-kit checks, zero production npm audit findings, registry validation, and an isolated Docker start/readiness/MCP/WebSocket/graceful-shutdown canary.

.github/workflows/ci.yml, tests/, src/migrations/, clients/agent-kit/tests/test-setup.sh, scripts/verify-hythe-release-tree.test.mjs, scripts/verify-packed-consumer.mjs

2026-08-14

Compaction identity fails closed

Startup and post-compaction hooks reject missing, conflicting, or invalid identity; the bridge binds acting tools and message-resource recipients to the configured exact lane before any HTTP request.

clients/agent-kit/tests/test-setup.sh, tests/contract-bridge-identity.test.ts

2026-08-13

Exact mailboxes stay isolated

Houston/Hythe, case variants, display metadata, legacy identity history, cross-tenant poisoning, suffix handles, lifecycle changes, supersession, HTTP, and ENG-4 authorship have negative isolation coverage.

tests/contract-message-identity-isolation.test.ts, tests/contract-eng4-p0.test.ts

2026-08-13

Private message bodies stay out of shared graph surfaces

Historical, oversized, malformed, alias-linked, relation-linked, imported, exported, searched, graphed, logged, and restored payload paths are covered; hidden children do not leak through counts.

tests/contract-message-payload-isolation.test.ts, tests/contract-data-payload-isolation.test.ts, tests/contract-log-confidentiality.test.ts

2026-08-13

Cleanup is offline and fail-closed

Migration 007, owner-approved adjudication, and physical sanitation are dry-run/plan-first, bind execution to reviewed database and decision evidence, require verified no-clobber artifacts, refuse unresolved custody, and preserve rollback state.

src/migrations/007-private-message-residue.mjs, src/migrations/private-message-residue-adjudication.mjs, src/migrations/vacuum-sanitized-database.mjs, docs/

2026-08-14

Per-agent authority is server-derived

The base key proves deployment/tenant access; a separate protected-file hya1 credential proves the exact agent. Required mode rejects stripped proof, mismatched identity, insufficient scope, revoked credentials, and stale WebSocket sessions.

src/agent-auth/, tests/contract-agent-auth-foundation.test.ts, tests/contract-agent-auth-server.test.ts, tests/contract-agent-key-client.test.ts

2026-08-14

Install and discovery surfaces agree

CLI and registry surfaces require an exact lane identity and expose only a protected per-agent key-file path plus an explicit authorization mode; tools and resource templates served through HTTP match the stdio bridge path.

tests/contract-cli.test.ts, tests/contract-agent-key-client.test.ts, tests/contract-mcp-resources-http.test.ts, scripts/verify-hythe-release-tree.test.mjs

2026-08-14

Current head is explicit, never guessed

The pointer advances only from the pointed head; stale parents branch without becoming current; a pointer at a non-live snapshot fails closed; snapshot rows are immutable by trigger. 33 contract tests.

tests/contract-eng4-h1-head-pointer.test.ts

2026-09-03

Versions and coverage are exact and verified

Every ledger tuple gets exactly one disposition; the startup backfill is all-or-nothing and idempotent; a bidirectional parity verifier fails closed on any missing, extra or mismatched row. 32 contract tests.

tests/contract-eng4-h2-version-foundation.test.ts

2026-09-03

Reconciliation is CAS-bound and causal

Exact live-head set and pointer are compare-and-set; every non-survivor head is retired (never deleted); divergent values resolve only by bound accept, reject or lineage reject; the record is payload-bound and re-verified on replay and read. 34 contract tests.

tests/contract-eng4-h3-reconcile.test.ts

2026-09-04

The v3 read model promotes only proven values

currentFacts / openLoops come only from verified versions on the accepted lineage with provenance; everything else is accounted as divergent or legacy with closed coverage. 29 contract tests.

tests/contract-eng4-h4-read-model.test.ts

2026-09-04

record / patch cannot promote stale state

Only the pointed head is admitted (conflict otherwise); state is materialized from the hash-verified payload; each payload is read once per call; snapshot resources serve exactly the verified bytes. 21 contract tests, four review rounds.

tests/contract-eng4-h5-record-patch.test.ts

2026-09-04

Express 5 keeps the HTTP contract

A bodiless or wrong-content-type request is handled like an empty JSON body on every parsed route, never a framework 500; production audit reports zero findings.

tests/contract-express5-body-contract.test.ts, .github/workflows/ci.yml run 33878587010

2026-09-04

Production migration verified on a copy first

The v3 schema and backfill were exercised against a copy of the production database on the production host before cutover; the live cutover took 17 s with row counts identical to the verified cold backup.

docs/PAVILION-PRODUCTION.md; operator log engram-prod/releases/hythe-74a324c-cutover-20260905T005551Z.log on the host

2026-09-05