feat(contracts): freeze MCP tool schemas + COM2 wire/attestation format (ADR-0020 complete) - #226
Merged
Merged
Conversation
…format; ADR-0020 complete The two deferred v1-freeze lanes from ADR-0020, mirroring the ABI golden discipline (#206-211): committed goldens, human-only regen, check-only gates, teeth-before-gate CI ordering. Lane C — contracts/wire/v1.golden (79 entries, guest+host twin rings): - user/wire_probe.c: compiler-measured guest ring (.abi_ents pattern) — framing, opcodes, Lamport params, CRC8 poly/init, reply-auth geometry (nonce/tag/key/body lens), FSYN/FSYP sizes+offsets, and attestation KATs PACK8-derived from SHARED macros (a hand-typed KAT would freeze the probe's copy, not the emitter's — panel blocker) - user/swarm.h + user/swarm_svc.c: the wire literals hoisted to macros and used at the emitter sites (mechanical, value-preserving; the _Static_assert ties QSUBMIT_BODY_OK to QC_RESULT_LEN) - user/fsyn.h: FSYN/FSYP frames extracted from fieldsyncd.c, self-contained, MAC_COVERED==offsetof(tag) statically asserted - scripts/qos_bridge.py: host constants hoisted (CRC8 params, attest grammar heads, reply-auth lens) and used in the live code paths — the host ring is extracted from the REAL parser, closing the guest<->host drift gap that was previously only a code comment; twin rule + a MUST_TWIN set make one-sided OR coordinated drift a red diff; host:kat:ping_frame freezes byte order + CRC span in one number - scripts/extract-wire.py: exit 1 RESERVED for diff/twin (2 for operational errors — an inverted teeth-check must not pass on a crash); QOS_WIRE_TEETH perturbs the TWINNED host magic; emit refused under teeth; header comments stripped in check Lane B — contracts/mcp/v1-tools.json (22 tools, name+inputSchema): - scripts/extract-mcp-schema.py: FastMCP list_tools introspection; recursively strips title/description inside schemas (pydantic's highest-volatility output — descriptions are deliberately NOT frozen: doc honesty fixes must stay cheap); _meta pins mcp==1.28.1 + pydantic==2.13.4 + pydantic-core==2.46.4 with an importlib version self-check (GENERATOR SKEW, rc 2, rejected by the selftest as a pass) - teeth live in the EXTRACTOR (production qos_mcp.py carries zero test code): =del mutates an existing tool's schema (changed-VALUE — the abi_probe lesson), =add appends a bogus tool - qos_mcp.py: qseeds list -> list[str] (pre-freeze fix; bare list is the most version-churn-prone schema rendering) - requirements-mcp-gate.txt + Makefile venv (WSL python is PEP-668 externally-managed) + new pinned-pip ci.yml job with pip cache .gitattributes: contracts/** text eol=lf (the ABI golden was already CRLF-smudged in Windows working trees). Verified locally (WSL): all four gates+selftests green (teeth assert rc==1 exactly AND the specific mutated marker); kernel build green; keyadmit/replyauth/qsubmit-replyauth behavioral gates green after the qos_bridge refactor; ci-smoke-latency green (0.05s, +24 boosts); full ci-smoke PASSED; abi golden gate+selftest unaffected. Follow-ups for the maintainer (recorded in the ADR): add the new job names to branch-protection required checks; optional abi-golden header retrofit. The audit_entry_t actor-reserve call remains open per the ADR. ADR-0020: all three lanes complete. Co-Authored-By: Claude Fable 5 <[email protected]>
NickFlach
added a commit
that referenced
this pull request
Jul 15, 2026
…, rebirth-proof IPC (#227) VERSION 0.5.0 -> 0.5.1; CHANGELOG [Unreleased] -> [0.5.1] with this cycle's entries appended (#219-#226: ADR-0023 IPC rebirth re-wiring, the ADR-0022 I/O-priority-boost latency epic, the ADR-0020 MCP + wire freeze lanes completing the v1 contract freeze, and the fix sweep). Co-authored-by: The Hand <[email protected]> Co-authored-by: Claude Fable 5 <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Completes ADR-0020: the two deferred v1-freeze lanes, mirroring the proven ABI-golden discipline (#206–211). Design attacked pre-implementation by a 2-lens adversarial panel (21 findings, 4 blockers — all folded in).
Lane C —
contracts/wire/v1.golden(COM2 wire + attestation)user/wire_probe.c(the.abi_entspattern): framing, opcodes, Lamport params, CRC8 poly/init, reply-auth geometry, FSYN/FSYP sizes+offsets, attestation KATs derived from shared macros — the emitters inswarm_svc.cnow use the same macros the probe measures, so the golden freezes the code path, not a transcription.qos_bridge.pyconstants (now hoisted and used in the real parser/verifier paths). The twin rule + MUST_TWIN set turn guest↔host drift — previously guarded only by a code comment — into a red diff.host:kat:ping_framefreezes byte order + CRC span in one measured number.-DSWARM_MAGIC_OVERRIDErecompile + hostQOS_WIRE_TEETHtwin-mismatch, both asserting rc==1 exactly plus the specific mutated marker (exit 1 is reserved for diffs; operational errors exit 2 — an inverted teeth-check must not pass on a crash).Lane B —
contracts/mcp/v1-tools.json(22 tools)_meta— doc honesty fixes must stay cheap; result shapes belong to the ADR's machine-readable agent docs item).title/descriptionkeys; pinsmcp==1.28.1/pydantic==2.13.4/pydantic-core==2.46.4inrequirements-mcp-gate.txtand the golden_meta, with an importlib self-check (GENERATOR SKEW, rc 2) so a wrong-environment regen cannot be committed silently.qos_mcp.pyships zero test code): changed-value AND added-name mutations both proven caught.abi-goldenjob. Selftests run before gates in both.qos_society_boot_n(qseeds: list)→list[str].Verification (local WSL)
All four gates+selftests green; kernel build green;
keyadmit/replyauth/qsubmit-replyauthbehavioral gates green after the host-constant refactor;ci-smoke-latencygreen (0.05s, +24 boosts); fullci-smokePASSED; abi golden unaffected.Follow-ups for the maintainer
wire-goldensteps' job +mcp-schemato branch-protection required checks.contracts/abi/v1.golden.audit_entry_tactor-reserve decision remains open per the ADR (deliberately untouched).🤖 Generated with Claude Code