The surface lock can be rewritten in place, so a silent surface change is still shippable

[serge-ivo]

The surface lock proves a change was noticed, not that the version moved

1d5cb24 (#573 AC2) added a fingerprint over the published tool surface, keyed by
MCP_SERVER_VERSION, in workers/mcp/src/conformance.test.ts. It works — it caught #574's
0.1.2 bump on first contact, unstaged.

Its stated limit, written into the code by its author rather than discovered later:

this makes a surface change impossible to ship silently, but does not mechanically prove the
version moved — the entry can be edited in place.

Concretely: change the tool surface, then edit SURFACE_LOCK["0.1.1"] to the new hash instead of
adding SURFACE_LOCK["0.1.2"]. Every gate stays green and the version never moves. The lock is
keyed by version specifically so that rewrite reads in a diff as what it is — that is a review
defence, not a mechanical one, and this repo has recorded what happens when the only defence is
someone reading carefully.

The precedent that already exists here

scripts/check-migrations.mjs --require-history (ci.yml:63) solves the same problem for
migrations: it is not enough that the file is well-formed, its history must show it was added
rather than rewritten. The same arm applied here would assert that a commit changing the surface
hash also adds a new SURFACE_LOCK entry rather than mutating an existing one.

Why it is worth doing rather than accepting

A silent surface change is the failure #573 was filed for, and the observed consequence was real:
the ChatGPT connector served a stale unannotated tool list because nothing signalled a change.
An in-place lock edit reproduces exactly that state while passing CI. The gap is narrower than
before — it now requires someone to actively rewrite a line rather than simply not think about
it — but "narrower" is the whole claim, and it should be stated rather than assumed closed.

Acceptance criteria

1. A commit that changes the published surface hash and mutates an existing SURFACE_LOCK
   entry instead of adding one fails CI.
2. A commit that adds a new entry passes.
3. A commit touching neither is unaffected and costs nothing measurable.
4. Modelled on check-migrations.mjs --require-history's approach to the same question — read it
   first and say where this legitimately differs, rather than copying its shape by default.
5. Per ADR 0002 the success line states its denominator, and the input set is asserted rather
   than assumed.
6. Demonstrated red on a deliberate in-place rewrite.

Verified vs inferred

• Verified: the limitation is quoted from 1d5cb24's own header; the lock is keyed by
  MCP_SERVER_VERSION (conformance.test.ts:483-484); check-migrations.mjs --require-history
  runs at ci.yml:63; the guard caught A ticket's reasoning can be written over MCP and never read back #574's bump.
• Inferred: nothing. That an in-place edit passes follows from the lock being a keyed lookup,
  but it is not yet demonstrated — AC6 exists to demonstrate it, and if it turns out some
  other arm already catches it, that is the better finding and this issue should close.

[serge-ivo]

Landed as 6000b97. CI green, and the new step is visible in the run: Surface lock is append-only (#576): success.

AC6 first — it is not caught elsewhere, and here is the measurement

The issue was right to ask before building. It is not caught. Reproduced end to end on 1d5cb24:

1. Appended one sentence to SERVER_INSTRUCTIONS in tool-metadata.ts — a real change to what a connecting client receives. conformance.test.ts went red with computed: sha256:d15d6331….
2. Rewrote SURFACE_LOCK["0.1.2"] to that hash instead of adding ["0.1.3"]. Version left at 0.1.2.
3. Ran the entire gate list.

gate	result
check-agents-allowlist, check-qa-config, check-file-size, check-migrations --require-history, check-design-tokens, check-bare-catch, check-test-isolation	all OK
pnpm docs:drift · pnpm docs:build · biome --error-on-warnings · mcp tsc	all OK
pnpm vitest run (8,7xx tests)	OK

Twelve gates, all green, version frozen. Nothing in this repo compares SERVER_INSTRUCTIONS to anything, so the exact state #573 was filed about is reachable through a passing build. The inferred claim in the issue is now verified.

AC4 — where this legitimately differs from check-migrations.mjs --require-history

Same kind of question and the git mechanism is borrowed deliberately. Four things differ, and copying its shape would have got each of them wrong:

1. The unit of immutability is an ENTRY, not a file. A migration must never change once applied, so that guard compares whole-file DDL. surface-lock.ts is supposed to change — every bump adds a line — so freezing the file would forbid the one act it exists for. This compares a parsed version → hash map and permits exactly one transition: additions.
2. A set diff, not a text diff. Follows from (1), and it is what keeps the per-entry comment editable — the same allowance check-migrations makes by stripping comments, for the reason 0080's header records: a wrong idea written in a comment gets read back out and believed, so correcting it must stay legal.
3. No --follow, no per-file walk. That guard resolves an introducing commit for each of ~110 migrations. This reads the revisions of one path — measured at 0.1s, so AC3's "costs nothing measurable" is a property of the shape rather than a hope.
4. There is an external witness, and it is deliberately not consulted. A migration's "already shipped" is only knowable from history. A version's is published on the MCP registry, which really does hold 0.1.0/0.1.1/0.1.2. Calling it from CI would make a required gate depend on a third party being up, and a guard that goes red for someone else's outage gets deleted. Git history is the offline proxy; the registry is what to check by hand when an entry is genuinely disputed.

Not different: --require-history means the same thing — refuse to skip on a shallow clone, so the check cannot quietly become a no-op.

One design point beyond the precedent: every past revision is compared, not just the previous one. HEAD vs HEAD~ would only ever catch the most recent rewrite; an entry corrupted three commits ago would read as settled fact from the fourth commit onward.

AC1–3, 5 — demonstrated

• AC1 (rewrite fails): rewriting 0.1.2 in place → red, naming both hashes and the commit that recorded it (recorded in 1d5cb24 as sha256:fa4b1a42…, now reads sha256:d15d6331…).
• AC2 (addition passes): adding 0.1.3 → ✓ Surface lock: 3 entry(ies) (0.1.1, 0.1.2, 0.1.3) unchanged across 1 revision(s).
• AC3: 0.1s, one git log plus one git show per revision of a two-entry file.
• AC5: success line names the entries and the revision count. The input set is asserted at four points, each failing rather than passing — the file must exist; the export must parse (null and an empty Map are deliberately different answers, since collapsing them is how a parser retires itself silently); at least one revision must parse, or the check compared nothing and says so; and --require-history turns a shallow clone into a failure.

KNOWN_REWRITES is the escape hatch in the shape this repo already uses (KNOWN_DUPLICATES, PINS): each entry carries its reason, and a dead entry — naming a version that is not in fact rewritten — fails, because dead config in a guard is how the guard stops being believed. Empty today, which is the honest state.

Ten unit arms in scripts/lib/surface-lock.test.mjs cover shapes the repo must never contain: a renamed export, a nested object that a lazy regex would truncate into a false deletion, and a rewrite disguised by a legitimate addition in the same commit.