One record per contract: dissolve ref/, and make server/spec/v1.md true

[fujibee]

Affects existing users only as documentation. No behaviour change: every code edit in this branch is a comment. Nothing that runs changes, and the shipped driver capability strings are deliberately untouched (see below). Everything else is docs/ and server/spec/. This is the "something broken is repaired" kind — a reader following these documents was being sent to a removed model, a dead path, or a numbered plan that no longer means anything.

What was wrong

One contract had four records, and the one with the authoritative filename was the dead one.

record	what it claimed
server/spec/v1.md	SUPERSEDED — do not build to this document
docs/design/remote-sync.md	named by v1.md as "normative today" for the model
docs/spec/ref/stage-1-remote-sync.md	named by v1.md as "normative today" for the sync contract — from inside ref/, whose README says do not cite one as the reason something is the way it is
scripts/internal/remote-sync.mjs:1472	"errorBody() … is the definition, since server/spec/v1.md is marked SUPERSEDED"

superseded is an ADR mechanism. CONTRIBUTING.md:52 states it: a later ADR supersedes an earlier one, and ADRs are immutable history. Specs get edited. Marking a spec superseded instead of correcting it is what let the implementation become the definition by default.

server/spec/v1.md

Rewritten from the implementation rather than patched paragraph by paragraph.

• Endpoints. It declared eight. POST /v1/pairing/exchange and POST /v1/credentials/<id>/revoke do not exist anywhere in server/src; four that the server does register were absent. It now lists the ten server/src/app.ts registers. Cross-checked by extracting both sets and diffing: 0 difference.
• Authorization. It required Authorization: Bearer on everything but health, in eleven places. The server's only mention of that header is redacting it from logs. The reason there is no credential — reaching the server is the permission, the network is the trust boundary — now sits where a reader meets it, along with the two things that rest on it: a repeat POST /v1/connect writing nothing, and the requirement not to expose a server to a network whose reachability you would not treat as authorization.
• The pairing and per-device-credential section (112 lines) described a removed model. Replaced by the four registration and lookup endpoints, written from connectSchema, connectTeam, resolveTeamsByName and getTeamSnapshot — including 409 team-already-exists and why a credential-free route depends on it writing nothing at all.
• Error table. Six codes belonged to the removed model (401 unauthenticated, 401 invalid-pairing-token, 403 forbidden, 403 credential-scope-violation, 409 pairing-token-consumed, 410 pairing-token-expired); three the server emits were missing (team-already-exists, cipher-profile-mismatch, team-name-match-limit-exceeded). It is now the set derived from every ProtocolError construction, and says explicitly what it does not cover, so 502/503/504 stop looking protocol-defined.
• The forward-pointers naming two other documents "normative today" are gone. The two links that remain say what each document is for and state that neither restates the endpoint shapes.

ref/ is dissolved

ref/README.md — one blob copied into three directories — said "Nobody is building toward anything in a ref/ directory" and "Do not implement from a document under ref/. Do not cite one as the reason something is the way it is." Eleven documents lived there and were cited 34 times from outside, including from scripts/key.sh, scripts/remote-sync.sh, scripts/drivers/storage/sqlite-sync.sh and server/spec/v1.md. Making the distinction visible from the path did not stop anyone citing them.

Promoted nine, each measured against the implementation first:

document	evidence it describes shipped code
docs/spec/stage-1-remote-sync.md	all five storage_sync_* operations implemented; stage1-resync advertised by sqlite and not by jsonl, exactly as the spec's "optional capability" says
docs/spec/age-v1-profile.md	age-v1 102 occurrences, X25519 8; its conformance vectors already sat outside ref/
docs/spec/read-state-synchronization.md	read-state implemented and tested
docs/spec/retention-gap-resynchronization.md	resync-required in remote-sync.mjs, storage.ts, errors.ts, plus three test files
docs/spec/server-opaque-envelope.md	key_id / cipher / blob in protocol.ts, storage.ts, 001_initial.sql
docs/adr/0005-remote-sync-contract.md	three of five decisions matched as written; see below
docs/adr/0006-composite-read-state-frontier.md	frontier 45 occurrences
docs/adr/0007-stable-member-and-roster-identity.md	member_id 321 occurrences
docs/design/adaptive-sync-catchup-v1.md	implemented in remote-sync.mjs:2876-3135, which cites this document by name in three comments; 23 lines of tests

Deleted two. device-pairing.md (811 lines): pair-v1 and SAS appear nowhere in the tree and key.sh has no request/approve subcommand. remote-sync-dogfood.md (177 lines): it asked to be deleted once integration/remote reached main, which 17d0ba7 did, and its runbook teaches connect --token-stdin, a flag remote.sh no longer parses — one comment is all that survives of it.

Promotion is not a move

Statuses said proposed or dogfood — the vocabulary of the directory they sat in. Left alone, the documents would have been half-promoted: authoritative location, provisional label. The specs are now current and the ADRs accepted.

Two ADRs could not be marked accepted as they stood, because they still described the pairing and per-device-credential model the server no longer has:

• 0005 — the device-credential paragraph is replaced by what a binding actually is (a local record with a revision, carrying no secret). "Onboarding cannot overstate history durability" kept its surviving claim — connect is not backfill — and lost the manifest-terminal-acknowledgement mechanism, which has no implementation. Its "key epoch" is written as key_id, the name the protocol actually uses.
• 0007 — owner boundary, lifecycle and one rejected alternative restated without credential issuance or revocation.

Editing them is what the ADR rule permits while a document is proposed and unadopted (AGENTS.md: squash while single-owner and unmerged; the supersede chain becomes mandatory only after main). Flagging it anyway, because it is the judgement call in this PR — the alternative was to ship docs/adr/ containing paragraphs I had measured to be describing a removed mechanism.

stage-1-remote-sync.md also contradicted itself — line 37 said SQLite is the Stage-1 implementation, line 229 said SQLite and JSONL both implement it. It now names both and what each advertises.

The guard, and why it is the first commit

There was no link checker. That is why docs/spec/vectors/age-v1-vectors.json has been shipping "profile_document": "../age-v1-profile.md" — a path that did not exist, because the vectors already pointed at where the profile would live after promotion.

The first commit adds the checker and is red, naming eleven pointers before anything is repaired:

• five in docs/adr/0003, which 75b8b1c moved out of docs/adr/ref/ without adjusting its relative depth — the last promotion out of ref/ broke five links and nothing noticed;
• four from the age-v1 profile to its own conformance vectors;
• the vectors' pointer back;
• (a twelfth appeared mid-PR: the new pointer v1.md makes to the promoted spec, before the move.)

Committing it red first is the positive control: the failure is in the branch history where it can be read, rather than reconstructed later from a description. A checker introduced alongside the fix is green from birth and no one has seen it fail. main never receives it red — the later commits close every pointer it names.

Both halves refuse to pass on an empty match, so a matcher that stops matching, or a renamed JSON field, reports itself rather than going quiet.

ADR 0003 keeps its decisions and loses its implementation

It named the drivers, the tools they shell out to, the releases each was phased into, and the issue numbers implementing them. None of that is the decision, and all of it dated: one phase never shipped, so the document described a plan rather than a boundary. Kept: the locked storage_* ABI, the use-case contract with its opaque driver-issued cursor, and the scope boundary that leaves the team registry and run-state outside the storage axis. The third decision had been written around one specific backend; it now states the boundary itself, which is what survives that backend being swapped.

Measured after the rewrite: driver and tool names 0, release numbers 0, issue numbers 0. The three remaining "JSONL" mentions are the interchange format, not the driver.

Status stays proposed, deliberately. The decision it records — that a storage backend is replaceable — has not been demonstrated: one driver ships, and a second one works only because core tests for it by name. Marking it accepted would assert something the tree does not yet show.

A consequences paragraph tracking a live call-site gap was removed. A decision record is not where live work is tracked, so it is filed as its own issue rather than deleted quietly.

Stage 1, 2 and 3 are gone from the prose

They were a delivery order, not a distinction a reader needs, and they ran through the normative specs and one of the filenames. A future reader had to learn a three-step plan — one step of which was never built — before learning what the documents cover.

The real split is messages versus read state, so the documents say that. docs/spec/stage-1-remote-sync.md becomes docs/spec/message-synchronization.md, pairing with the read-state-synchronization.md beside it, and both titles now name their subject. "Stage 3" was server-sent events and wake delivery; that section now states what is out of scope without implying a numbered step someone is waiting on.

The capability strings stage1-sync, stage1-resync and stage2-read-state are NOT renamed. Drivers advertise them today and an external driver may too, so changing them breaks the driver ABI rather than a document. They are explained once, where the capabilities are defined, as fixed names whose numbers carry no meaning beyond telling the three apart. Verified untouched: both capabilities= lines and all three engine-side checks are unchanged.

Stage prose remaining in docs/ and server/spec/: 0, counted with the capability identifiers excluded so the two are not confused.

Verification

stopping condition	expected	measured
ref/ directories	0	0
tracked files under any ref/ path	0	0
residual ref/ references, path and name instruments	0	0, re-measured after the review below — it was not 0 when first claimed
link checker	green	green
endpoints in v1.md vs registered in app.ts	identical	0 difference

The move invalidated 38 relative links. All were rewritten by resolving each basename against the tree, with the checker enumerating them before and confirming after — no link was fixed by hand and hoped over.

A link checker is not enough on its own: 28 further references live in prose and code — docs/security.md and docs/security.ja.md cite the age-v1 profile by path with line numbers twelve times each, and three script headers name it in comments. No markdown link checker can see those, so they were swept with a second, path-and-name instrument and rewritten too. That is why the residual-reference row above is measured with both.

Suites run locally on this head (macOS): test_doc_links, test_type_registry, test_claude_template — 26 ok, 0 not ok. test_bin_agmsg, test_remote_setup_doc, test_storage_contract in CI's xargs bats form. docs/spec/vectors/verify-age-v1-vectors.mjs exits 0. test_remote_sync_engine passes. Local form is not CI's shard form.

Destination drift re-measured at commit time: origin/main is f7de22a and the merge base is f7de22a.

CI on the current head: 22 checks, 22 completed, no failures.

Review findings addressed in this branch

A static review found three contract conflicts the rewrite had left behind, and one claim in this body that did not match the tree. All four are fixed above; they are listed because the body previously asserted a cleanliness it did not have.

• The v1 error contract contradicted itself 760 lines apart: the common-envelope paragraph assigned binding ids to 401, 429 and a team-scoped 503, and instructed servers to send Retry-After on 429, while the derived table said the reference server emits none of them. The paragraph now lists only statuses that exist, and Retry-After is attributed to an intermediary.
• docs/design/remote-sync.md was marked "Not implemented yet" although the HTTP contract now sends readers there for the rationale, and it named two deleted documents as if they were still on disk.
• docs/spec/message-synchronization.md, promoted to current, still gave the HTTP engine authentication to own and authentication material to hold — the removed credential model surviving in a document this branch promotes.
• The residual-reference claim was wrong when first written. docs/design/remote-sync.md named the deleted device-pairing.md, so the name instrument was not at 0. It is at 0 now, re-measured after that file was fixed, and the verification row says so rather than quietly reading 0.

Two findings are not addressed here and are held for a ruling. The rule permitting an unadopted ADR to be edited is bounded by whether the document reached main, not by its status — and both ADRs this branch edits already exist on main under ref/, so CONTRIBUTING.md would require superseding ADRs rather than edits. Separately, one of them is marked accepted on evidence covering a single clause: pending_remote_acceptance does not exist in the tree, there is no server-side owner model, and no roster-mutation endpoint exists for the mutation-dedupe-then-CAS contract, although its storage columns do. Both are questions about ADR discipline rather than about this rewrite, and neither is decided in this PR.

Scope

Only the records named above and the guard that keeps their pointers honest. key rotate documentation, device pairing, and the roster-mutation protocol are not addressed here.

After review

Four findings from static review are closed in this branch, and one was withdrawn.

• The guard could not see reference-style links. It matched ]( only, while the tree links its age reference as [age v1 file][age-format] with the definition further down — so breaking or deleting that definition left the check green. Extraction moved to tests/helpers/check_doc_links.py and now covers inline targets, reference definitions with a relative target, and reference uses whose label must be defined; fenced blocks and inline code spans are stripped first, because a backticked character class otherwise reads as a reference link. A case asserts this against a fixture rather than the repository, so it keeps testing the parser on a day when nothing in the tree happens to be broken. Verified both ways on the real file: repointing the definition at a missing path, and deleting it, each turn the check red.
• ADR 0007 returns to proposed. It had been marked accepted on one identifier's occurrence count. The document also decides a single-owner boundary the server has no model for, a pending_remote_acceptance gate that appears nowhere, and a roster-mutation protocol whose storage columns exist but which has no endpoint to run over. Its status line now names the three parts that are not there. ADR 0005 was re-measured against the same standard and holds.
• The v1 error contract, and two promoted documents, as described above.
• Withdrawn: that a merged ADR may not be edited. The repository owner set the boundary at status rather than at merge, and CONTRIBUTING.md now records that publicly so the next reader does not stop where this review did — in both language versions, with a test pairing them, since the rules lived in two files and nothing compared them.

The new assertions are chained so they can fail on the bash the suite also runs under; the repository's own enforceable-assertions count is back at its baseline exactly, with no line from this suite in the report.