stack/docs/compaction-refresh/governance/charter-BUILD-BRIEF.md

Compaction-Refresh Mechanism — BUILD BRIEF (Mos → MS-LEAD)

Status: STAGED — do NOT dispatch until PR #826 (#824 skill-CLI bridge) MERGES. Mos routes this to MS-LEAD at #824 land. PLAN phase COMPLETE + RATIFIED; this is the BUILD-execution brief. Routed by: Mos (main orchestrator). Owner: MS-LEAD (mosaic-100). Runtime scope M1: Claude + Pi.

1. AUTHORITY (sha256-pinned — build AGAINST these, do not re-derive)

Artifact	Path	SHA-256
Ratification record (SSOT)	~/agent-work/reviews/compaction-refresh-SPEC-RATIFICATION.md	bac58319c9c4028b5b40e1129e0033cdb5a6b7b02033c25f06f4cb77d7779c67
Ratified SPEC v5	~/agent-work/reviews/compaction-refresh-SPEC-v5.md	a6d07ade835758e8488ca10d3b0631caf0beb93ea3a6733631f151b0c2f01433
sol FINAL red-team (GO)	~/agent-work/reviews/compaction-refresh-SPEC-v5-redteam-sol.md	3da326a4ea91767b731e128a93b13194e8002358101e30de3fcb8ca2f8f54faa

The coder MUST verify these hashes before building. The in-context working spec is DERIVED and compaction-fragile — the sha256'd records above are the recovery SSOT (durable-authority discipline).

2. TARGET & SCOPE

• Framework-native packages/mosaic/… in mosaicstack/stack. NOT jarvis-brain. NOT ~/.config/mosaic/ directly (that tree is WIPED on framework upgrade — durable home is SOURCE).
• M1 = Claude + Pi orchestrators only. Codex/other runtimes = scope-note only.
• Hard dependency (now satisfied at dispatch): the mosaic skill register/list + install/upgrade symlink auto-sync (#824 / PR #826) — so the durable mosaic-context-refresh skill ships REACHABLE (auto-symlinked into ~/.claude/skills/). Do not dispatch before #826 merges.

3. DELIVERABLES (locked architecture — from the ratification record; do NOT redesign)

1. Authenticated external lease broker bound to kernel SO_PEERCRED (pid, starttime, runtime_generation) — the only unforgeable identity on a same-uid tmux fleet. Broker MINTS the logical session_id at first peercred contact (NEVER caller-asserted). Distinct-principal / protected socket.
2. Whole mutator-class gate (not per-wrapper): no consequential mutator succeeds without a valid VERIFIED lease. Revoke-first / promote-last.
3. Compaction observers → revoke: Claude PreCompact + SessionStart(matcher=compact); Pi session_before_compact/context equivalents. Any runtime_generation bump (reload/resume/fork, same PID included) auto-revokes the prior incarnation.
4. Verbatim-hashed normative fragments: B_payload (exact fragments + deterministic metadata) and H_payload = SHA256(domain_sep ‖ length_framed(B_payload)) — NO self-reference (byte-identical across the Claude and Pi builders).
5. Receipt-challenge protocol (promotion prerequisite, NOT the safety mechanism): broker mints a single-use receipt_challenge per cycle bound to (session_id, runtime_generation, compaction_epoch, request_epoch, H_source, H_payload, schema_version). COMPUTE = broker (observes latest-assistant message, computes the binding incl H(latest-assistant-message)); COPY = model (verbatim copy of challenge + H_payload — an LLM cannot hash its own output; T29). Observed in the EXACT latest assistant message (Claude: latest assistant entry + pending challenge, NO transcript grep; Pi: message_end, NOT after_provider_response). Single-use, consumed before the tool batch. Broker transition order (mandatory): revoke → build B_payload/H_payload → PENDING_DELIVERY(mint unique challenge) → deliver → observe exact receipt → evidence commit → consume challenge → promote VERIFIED (last).
6. Constrained recovery command = the single ungated mutator; the mosaic-context-refresh skill is its wrapper (uses a newly-minted challenge + identical protocol; cannot replay normal-path receipt). Durable skill lands here, symlink-reachable via #824.
7. T-C server-side line = branch protection (the irreducible guarantee; client gate is window-narrowing only). If ops-config rather than code, DOCUMENT the required posture explicitly.

4. BINDING BUILD CONDITIONS R1–R6 (MANDATORY — verbatim from ratification record)

• R1 (honesty): state that the receipt detects ABSENT or PREFIX-TRUNCATED terminal token, but a MIDDLE-DROP preserving the tail is a T-C contract violation, NOT receipt-detectable (covered by server-side). No over-claim.
• R2 (atomicity): evidence-commit → consume-challenge → promote-VERIFIED is ONE atomic broker transaction; a crash leaves neither VERIFIED-with-live-challenge nor consumed-with-ambiguous-promote; recovery mints a NEW challenge, never reuses.
• R3 (parsing): exact single current-cycle receipt parse — no unbounded grep; reject quoted/tool-output receipts, wrong generation/epoch, unknown/stale challenge, multiple receipts.
• R4 (Gate0 = BUILD-ADMISSION GATE): see §5 — runtime evidence BEFORE build admission; a failed Gate0 item RETURNS the design to planner review, it is NOT waived by the GO.
• R5 (TTL): 300 s MAX lease TTL + soak-tighten; soak may only SHORTEN, never lengthen. Mos-accepted.
• R6 (receipt semantics): receipt = T-A delivery/liveness ONLY, never obedience/safety/residency. Permanent invariant.

5. R4 GATE0 — RUNTIME EVIDENCE BEFORE BUILD ADMISSION (WI-0, do this FIRST)

Structure the build like gitwatch: WI-0 is a Gate0 runtime-evidence probe; no feature build admitted until every item produces POSITIVE runtime evidence (not a design assertion). A failed item RETURNS to planner — do not paper over:

• Launcher exec/parent topology + supported-hook ancestry (D1); broker authenticates the launcher chain, rejects sibling-substitution.
• Pi lifecycle: last-position invariant (last-or-closed), per-tool nonce → tool-call-id map (D5).
• Same-PID runtime_generation bump on reload/resume/fork revokes prior lease (D4).
• Broker socket authenticity posture (protected / distinct-principal); SO_PEERCRED returns the true (pid, starttime).
• Source-invalidation fail-closed (missing/oversize/hash-mismatch fragment → no promotion).
• Claude additionalContext + Pi context inject atomically (A-v5-1) — the transport assumption T27 rests on; verify or class the gap T-C.

6. ACCEPTANCE TESTS (red-first TDD)

Carry all v4 ACs + T12b; add T24–T30: T24 hash-construction no-self-reference byte-identical across builders · T25 replay rejected · T26 transcript-stale-match cannot promote · T27 partial-delivery (prefix-trunc/tail-only/middle-drop/malformed) none promote · T28 single-use (no renew/reopen) · T29 model copies not computes · T30 dual-hook-miss matches AMENDED threat table within+after TTL. Acceptance = full green suite + Gate0 evidence pack.

7. REVIEW & MERGE DISCIPLINE

• This IS an Opus-SECREV-mandatory surface — UNLIKE #824 (local same-uid FS). The broker is an authentication/identity/authorization mechanism (peercred binding, session_id minting, mutator-class gating, receipt protocol). Security review = Opus-SECREV, no GPT/terra substitute on the broker/gate/receipt/socket surfaces. Functional/non-security parts may take GPT review.
• Author ≠ reviewer, independent review, no self-merge, exact-head RoR (reviewed-SHA=merged-SHA), closes #<issue> close-keyword, full 40-char head. Never edit tests to pass / never force-merge red / never --no-verify.
• Mos merges (per ratification record) after Opus-SECREV + independent review pass + green suite + Gate0 pack. Decompose into work-items (WI-0 Gate0 first); likely a milestone, not one monolithic PR.

8. SEQUENCING

#826 (#824 bridge) MERGES → Mos routes this brief → MS-LEAD decomposes (WI-0 Gate0 first) → build M1 (Claude+Pi) → Gate0 evidence pack (failed item → planner) → Opus-SECREV + independent review → Mos merges → durable mosaic-context-refresh skill lands symlink-reachable → jarvis-brain CLAUDE.md mandate PR aligns to the shipped receipt/hash contract. Interim skill + CLAUDE.md mandate stay LIVE until the mechanism ships.