WI-2 Scratchpad — Whole mutator-class gate

Issue: Gitea #829
Branch: feat/829-mutator-gate
Base HEAD: 8ec67a1126adb0dcd4c3a2bf5525f3e239c0b201
Role: sol author/build lane only; terra code review and Opus security review are coordinator-owned.

Mission prompt

Implement BUILD-BRIEF Deliverable 2 as a framework-native whole mutator-class gate under packages/mosaic/, building against the merged WI-1 lease broker. No consequential mutator may succeed while UNVERIFIED after a compaction observer fires or after TTL. Carry the T-B compromised-tool acceptance criteria. Enforce revoke-first and promote-last structurally. A receipt is only a promotion prerequisite; the mutator-class gate remains the safety mechanism. M1 is Claude + Pi only.

Authority verification

Verified exact SHA-256 before design/code:

BUILD-BRIEF: 89fdbc27ed0e5050dc7b52f3ef2ddaea691edf17fd89d51b15e26fb5ed47171b
SPEC-v5: a6d07ade835758e8488ca10d3b0631caf0beb93ea3a6733631f151b0c2f01433
Ratification: bac58319c9c4028b5b40e1129e0033cdb5a6b7b02033c25f06f4cb77d7779c67
sol final red-team: 3da326a4ea91767b731e128a93b13194e8002358101e30de3fcb8ca2f8f54faa

Carried authority chain also verified/read for the locked T-B gate contract: SPEC-v4 a5e9c261…, v4 sol 1e76ee59…, SPEC-v3 e0830ba0…, v3 sol 9f321ade….

Plan

RED real-socket acceptance tests for default-deny whole classes, T-B raw-tool bypass, observer/TTL revocation, and structural revoke-first/promote-last.
Extend the merged WI-1 broker as the sole lease authority; authenticate every transition through existing peercred/ancestry/session logic and consume WI-1 single-use cycle tokens atomically before promotion.
Add one broker-backed runtime gate executable and wire it across all Claude PreToolUse tools and Pi tool_call; unknown/custom tools deny by default.
Add proportional protocol/security/operations documentation and requirements-to-evidence mapping.
Run focused coverage, package/full suites, lint/typecheck/format, then queue-guard, push, open an unmerged PR with closes #829, and hand off the exact head.

Risks and bounds

Receipt parsing/builders and compaction observers are later WIs; WI-2 exposes the promotion prerequisite boundary but does not treat a receipt as safety authority.
Broker restart intentionally loses volatile VERIFIED leases and therefore restarts UNVERIFIED; persistent WI-1 identity/token state remains unchanged.
The gate is whole-class and does not parse shell command strings. T-C extension/hook absence and same-UID broker replacement remain outside the client guarantee and server branch protection remains the backstop.
Initial lease TTL is capped at ratified 300 seconds; callers may only shorten it.
Working budget assumption: 35K tokens; reduce documentation/refactor breadth before touching locked scope if pressure rises.

Progress and verification

RED #1: all 5 initial real-socket contract tests failed on WI-1 with UNKNOWN_ACTION or missing adapter behavior.
RED #2: register-before-exec runtime test failed because launch-runtime.py did not exist.
GREEN: broker-owned volatile lease state, 300-second maximum monotonic TTL, WI-1 token-backed promotion, all-tools runtime gate, Claude/Pi wiring, and register-before-exec launcher delivered without changing WI-1 peercred/ancestry authority.
Focused broker + gate acceptance: 43/43 GREEN.
Instrumented Python coverage: 88% total — daemon 89%, register/exec launcher 86%, runtime gate 86%.
Full repository suite: 43/43 Turbo tasks GREEN; @mosaicstack/mosaic 72/72 files and 1,377/1,377 tests GREEN.
Root typecheck: 42/42; lint: 23/23; format check and git diff --check: GREEN.
No author self-review was run. Exact-head terra CODE and Opus SECREV remain coordinator-owned gates.

Acceptance mapping

Acceptance criterion	Evidence
No consequential mutator succeeds while UNVERIFIED after observer revoke or TTL	`observer revocation and monotonic TTL expiry deny the next mutator` real-socket acceptance test
T-B compromised-tool bypass is covered by the whole gate	`T-B raw and custom mutator tools are default-denied without shell parsing` across Claude/Pi built-ins, raw Bash class, MCP/custom/unknown tools
Revoke-first / promote-last is structural	`revoke-first and promote-last structurally bracket mutator authority`; direct promotion rejected, pending remains denied, token consumption commits before VERIFIED
Consume WI-1 auth/lease substrate	All transitions and decisions traverse merged peercred/ancestry authentication; promotion consumes the exact WI-1 CSPRNG cycle token
M1 Claude + Pi	Claude `.*` PreToolUse and Pi `tool_call` invoke the same broker gate; register-before-exec test proves broker-minted parent identity reaches runtime descendants

Locked discipline

Re-verify and read the four authority artifacts before design or code.
RED-first tests must cover unverified mutation refusal, T-B compromised-tool refusal, and revoke-first/promote-last ordering.
Consume WI-1 VERIFIED-lease state; do not re-derive kernel identity, ancestry, sessions, or token authentication.
Minimum 85% new-code coverage; full suite, lint, typecheck, and format checks green.
Build only: no self-review and no merge. Open a PR containing closes #829, report its exact 40-character head, then exit.

5.3 KiB Raw Blame History