fix(anchor): one transactional writer for identity.json, + witness-key delegation preimage

[c-1k]

Three pre-existing defects in the anchoring identity path, plus the first piece of the Rekor witness-key work. All three bugs are live on master today.

The fixes (commit 1)

identity.json had no single writer. bumpAnchorHighWater and recordRotatedIdentity each did an unserialized read → spread → write:

1. A stale write could roll back lastAnchorSeq. That is the anchoring-monotonicity invariant — re-minting an occupied position in an append-only external store is permanent, unrewritable fork evidence. The same race could silently drop keyHistory entries, stranding records whose signing key nothing could name.
2. The temp filename was identity.json.tmp-<pid>, shared between two writers in one process, so one could rename a file the other was still writing and publish a torn identity that still parses as JSON.
3. The rename was never made durable. The bytes were fsync'd but the containing directory was not, so "persisted before we act on it" was false across a crash.

Every mutation now goes through updateAnchorIdentity: take the emitter's advisory lock, re-read under the lock, merge, write atomically. heldLock is an explicit parameter rather than inferred — inferring it would let a caller that forgot to lock ride on an unrelated component's lock, and that failure is invisible.

Behaviour change worth flagging in review: usertrust anchor resume now fails with "locked by an in-flight emission" if an emission is running, where it previously wrote regardless. Fail-closed, but operator-facing.

What the tests do and do not prove (commit 2)

Five tests, each mutation-verified. Removing the lock fails two of them.

Recorded honestly in the code: two of the five survive deleting mergeIdentity's monotonic max and its key-history union outright. That is structural, not an oversight — mutate() is handed a copy re-read under the lock, so no current caller can produce a stale proposal and the merge is a no-op on every existing path. The live protection is the re-read, not the merge. The merge stays as defence in depth for a caller that computes a proposal from an earlier capture, and is documented at the function as currently unreachable. A guard nobody can reach is not evidence.

Delegation preimage (commit 3)

The bytes a witness-key delegation is signed over, mirrored byte-identically into packages/verify because the verifier must recompute it without importing core.

Every variable-length field carries a u32be byte-length prefix. Without them two different delegations share one preimage, so one root signature authorizes both — reachable rather than theoretical, since vaultId is only ever validated as a non-empty string, never as a UUID.

The open-ended sentinel is 2^53-1, not the 2^64-1 the u64 encoding suggests: 2^64-1 is not representable as a JS number and would fail this codebase's own Number.isSafeInteger validation, so what was signed and what is stored would differ.

packages/verify LOC tripwire raised 9900 → 10200 in the test (the authority) and AGENTS.md together, with the accounting its comment requires. Assertions 4 and 5 — imports are node:*/relative, dependencies is {} — re-verified and still passing.

Verification

• npm run typecheck clean
• Full suite 4378 passed, 0 failed, 14 skipped (the documented openclaw-contract skips, proven in their own CI job)
• biome check clean
• Mirror parity assertion passing

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1ee65614db

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Acquire the lock before appending the resumed record

When anchor resume overlaps an emitter, this function appends and fsyncs the supplied record before bumpAnchorHighWater(..., false) attempts the advisory lock and throws. The command therefore reports failure after mutating the mirror, a retry is rejected because the mirror already contains the sequence, and the concurrent emitter was free to append based on its own stale tail. Acquire the lock before reading, validating, and appending the mirror, then bump the high-water while that same lock is held.

AGENTS.md reference: AGENTS.md:L662-L670

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Keep the rotation lock through the identity update

In the CLI rotation path (packages/core/src/cli/anchor.ts lines 581-609), the cross-signed rotation is durably appended and its emitter lock is released before this nonblocking lock acquisition. If a scheduler or another CLI emission holds the lock at that moment, this throws with the mirror already switched to the successor while identity.json still names the old key; subsequent use of the old signer is rejected by the epoch guard, and rerunning rotation cannot repair the missing identity transition. The rotation append and identity update need one lock scope, or this update must retry without losing the minted successor.

AGENTS.md reference: AGENTS.md:L662-L670

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Reject delegation indexes outside the u32 range

A delegationIndex such as 4294967296 is a positive safe integer and passes this guard, but the later Buffer.writeUInt32BE throws ERR_OUT_OF_RANGE. Thus malformed, untrusted delegation data can escape a function explicitly intended to return null rather than throw; cap the index at 0xffffffff and mirror the guard in the standalone verifier.

AGENTS.md reference: AGENTS.md:L1002-L1008

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Propagate real directory-fsync failures

On supported POSIX systems this catch also swallows genuine fsyncSync failures such as EIO, not only platforms that cannot open or sync directories. The caller then proceeds as though the identity rename were durable, so a crash can lose a reported high-water or key rotation and leave the mirror ahead of identity.json; ignore only the specific unsupported-platform errors and propagate storage failures.

AGENTS.md reference: AGENTS.md:L662-L670

Useful? React with 👍 / 👎.

[c-1k]

Added: G5 — report the absence of witnessing (commit 4)

Scope note: this branch now carries a fourth commit that is a feature, not a bug fix. Prioritised over the remaining Rekor wire work after the assessment below; happy to split it into its own PR if reviewers prefer the bug fixes isolated.

The defect

A vault that had never been witnessed verified byte-identically to one that had, and reported ANCHORED_VERIFIED while doing it. verifySuppliedRekorReceipts returns null when no receipts are supplied, so rekorFailed stayed false and the verdict was untouched. Nothing anywhere said "this evidence was never present."

That is how the Rekor sink stayed non-functional without a single verdict noticing, and it is independent of whether the transparency-log path ever works — which is why it lands ahead of the wire fix.

What changed

anchoring.witnessLog, always present — unlike the optional rekor block. An absent field is how the absence stayed invisible.

The fold is over anchors, not receipts. Folding over receipts lets an anchor with no receipt contribute nothing and disappear, so nine covered anchors beside one unwitnessed one read as fully verified. Every anchor contributes exactly one outcome. An empty fold is UNKNOWN, not VERIFIED — zero anchors makes "all anchors covered" trivially true. A failing receipt outranks a passing one for the same anchor.

exitCodeForAnchored gains requireWitness, opt-in exactly like the two existing flags, so default exit codes are unchanged. It fails closed when witnessLog is absent entirely.

Reachability, stated rather than implied

Only WITNESS_VERIFIED, WITNESS_UNKNOWN and WITNESS_INVALID can currently be produced. ABSENT, UNPROVEN and PARTIAL need the emission-time sink declaration that distinguishes "should have been witnessed" from "never claimed to be", which is not built. They are declared because they are the spec's lattice and marked unimplemented in the code so nobody reads the type as the feature.

Verification

Mutation-verified, four valid mutants:

Mutant	Caught by
Fold over receipts instead of anchors	4 tests
Empty fold reads as VERIFIED	1 test
Passing receipt beats a failing one	1 test
requireWitness fails open when field absent	1 test

Full suite 4388 passed, 0 failed. Typecheck and biome clean.

The differential suite caught the packages/verify omission immediately — the parity contract working as intended, since a standalone verifier that under-reports witness state is exactly the divergence it exists to prevent.

[c-1k]

Codex Review (local CLI, max effort) — REQUEST CHANGES

Certifying round, first Codex read of these 4 commits. Max effort was a deliberate per-round choice, not a default.

Review gate: request changes. I found four high-severity and three medium-severity defects.

Findings

1. High — delegation preimage is not injective over accepted vault IDs.
   anchor-verify.ts:373, mirrored in verify.

   vaultId: "\uD800" and vaultId: "\uD801" are distinct, non-empty JSON strings, but Buffer.from(..., "utf8") replaces both lone surrogates with efbfbd. The resulting delegation preimages are identical, so one root signature authorizes two different delegations.

2. High — a partial anchor history passes requireWitness.
   anchor-verify.ts:664, verify.ts:771, verify.ts:822

   A lone valid anchor at anchorSeq: 10 is deliberately accepted as ANCHORED_VERIFIED with partial-history. If only that anchor has a valid Rekor receipt, the fold receives [10], returns WITNESS_VERIFIED, and requireWitness exits 0. Positions 1–9 contribute nothing despite being implied by sequence 10.

3. High — resumeAnchorMirror mutates the mirror before acquiring the lock.
   anchor.ts:1250, anchor.ts:1259

   With a live foreign lock and a valid resume record, anchors.jsonl is appended first; only afterward does the high-water update try the lock and throw. The caller sees a refusal, but state changed. A concurrent emitter that already observed the old tail can mint the same anchorSeq, creating permanent fork evidence. The new test asserts only the throw, so it misses this mutation.

4. High — same-PID stale reclaim can steal a live lock.
   anchor.ts:665, anchor.ts:713

   The owner registry is module-local and keyed by an uncanonicalized path. Two emitters referencing one vault through real and symlink paths—or running in separate Worker isolates—share a PID but not the registry entry. The second treats the first lock as stale, renames it, and enters concurrently. This permits duplicate anchor positions and stale identity writes that can lower lastAnchorSeq.

5. Medium — directory-fsync failures are reported as success.
   anchor.ts:235

   The catch treats every error as “platform unsupported,” including EIO, ENOSPC, or EDQUOT. After such an error the function returns successfully, callers act on the update, and a crash may restore the older identity/high-water. Only known unsupported-platform errors should be suppressed.

6. Medium — the shipped CLIs still hide witness absence and expose no witness gate.
   verify CLI:216, verify CLI:339, verify CLI:439

   Neither CLI parses --require-witness, passes requireWitness, nor renders witnessLog. A valid externally anchored vault with no Rekor receipts still prints Vault integrity: VERIFIED (externally anchored), emits no witness-state line, and exits 0—the human-facing silent success this commit claims to expose.

7. Medium — the “returns null, never throws” contract is false.
   anchor-verify.ts:387, anchor-verify.ts:400

   delegationIndex: 2 ** 32 is a safe positive integer and passes validation, then writeUInt32BE throws ERR_OUT_OF_RANGE. It should be bounded to 0xffffffff and return null.

Explicit category checks

• Direct heldLock annotations are correct: both true calls are inside emit; rotation/resume pass false. Findings 3–4 defeat the surrounding lock guarantee.
• No-op comparison: no correctness loss found. With JSON-parsed plain data, key-order changes cause an unnecessary write, not a false skip.
• Fold: empty input is UNKNOWN; invalid wins over covered; integration deduplicates equal sequence numbers. The missing-prefix case remains unsafe.
• requireWitness itself fails closed when witnessLog is absent, and the two existing flag branches are unchanged.
• Parity: the anchor-verify.ts mirrors match exactly under the repository filter; verify still has {} dependencies and only node:*/relative imports. Core and standalone produce the same tested outputs—including the same defects.

Focused Vitest could not start because the read-only environment blocked Vite’s .vite-temp write. Read-only runtime probes confirmed the surrogate collision, partial-history WITNESS_VERIFIED/exit 0, and delegationIndex exception.

---

Findings accepted; all seven are legitimate. Fixes to follow on this branch.

[c-1k]

Fixes for the certifying round — 5 of 7 addressed

Every finding was verified independently before fixing, not taken on the reviewer's word. Measured confirmations: lone surrogates both encode to efbfbd; Number.isSafeInteger(2**32) is true while writeUInt32BE(2**32) throws ERR_OUT_OF_RANGE; and the resume path's mirror append does precede the lock acquisition.

#	Sev	Status
F1 preimage not injective over vaultIds	High	Fixed — UTF-8 round-trip guard on every string field
F2 partial history passes requireWitness	High	Fixed — implied-but-absent anchors count as unknown
F3 resume mutates mirror before locking	High	Fixed — lock taken first; test now asserts state is unchanged
F5 dir-fsync swallows EIO/ENOSPC	Medium	Fixed — catch narrowed to genuine unsupported-platform errnos
F7 writeUInt32BE throws past u32	Medium	Fixed — bounded, returns null
F4 same-PID stale lock reclaim	High	Not fixed — pre-existing, see below
F6 CLIs hide witness absence	Medium	Not fixed — accepted, see below

F2 deserves calling out: it is the same vacuous truth this fold was written to prevent, one level up. There the missing thing was an anchor with no receipt; here it was an anchor with no record. A vault whose newest anchor is seq 10 asserts 1..9 existed, and folding over only the records in hand returned WITNESS_VERIFIED with nine anchors unaccounted for. partial-history remains legitimately accepted for anchorState — it is simply not a witness claim.

F3 also exposed a gap in my own test. It asserted only the throw, so a refusal that had already appended to the mirror passed as correct. It now asserts the mirror bytes and the high-water are unchanged.

F5 was prose ahead of code in a commit whose message calls that class out — the comment claimed "platform does not support directory fsync" while the catch swallowed everything.

Deliberately not folded in

• F4 is pre-existing in tryAcquireAnchorLock (module-local registry keyed by an uncanonicalized path) and is wider than this branch. This branch makes it more consequential by putting identity writes behind that lock, which is worth saying, but fixing lock-reclaim semantics belongs in its own change with its own tests rather than as a rider here.
• F6 is correct and is the human-facing half of G5. Neither CLI parses --require-witness nor renders witnessLog, so an operator still sees VERIFIED (externally anchored) and exit 0 with no witness line. The library surface exposes the state; the shipped commands do not yet consume it. Tracked as the next piece.

Verification

Mutation-verified, sane failure counts (a 100% failure rate would indicate a broken module, not a sensitive suite):

Mutant	Caught by
Ignore implied-missing anchors (F2)	2 tests
Drop the round-trip guard (F1)	1 test
Drop the u32 bound (F7)	1 test

Full suite 4394 passed, 0 failed. Typecheck and biome clean.

[c-1k]

F6 fixed — the witness state is now visible to an operator

This was the half that actually mattered. The library had reported the witness state since the first commit, but neither shipped CLI rendered it or parsed a gate for it — so usertrust verify still printed VERIFIED (externally anchored) and exited 0 on a vault whose transparency-log leg had never run. The silent success survived in the one place a person actually looks, which is why my earlier claim that G5 "closes" the defect was overstated for the human-facing path.

Both CLIs now:

• always print a witness line on the anchored path — including, especially, when nothing was witnessed
• accept --require-witness, opt-in exactly like the two existing strict flags, so default exit codes are unchanged
• treat --require-witness as an anchor-mode trigger, so asking for the gate can't silently do nothing

The core CLI's --json success is no longer result.valid alone. A witness gate can exit 1 while the chain is valid, so a consumer reading the body rather than $? was told the run succeeded while the process failed — a second silent success, one layer out from the one being fixed.

Verification

Mutant	Caught by
Stop printing the witness line	1 test
Drop requireWitness from the gate	2 tests
Revert --json success to result.valid	1 test

Full suite 4397 passed, 0 failed. Typecheck and biome clean.

Worth flagging honestly: the first version of the witness-line test used a fixture property that does not exist, so --anchors received no value, anchor mode never engaged, and it failed for a reason unrelated to the code under test. A test that reaches a different path than the one it names proves nothing about that path — fixed before committing.

Remaining from the certifying round

F4 only (same-PID stale lock reclaim via an uncanonicalized registry path). Pre-existing in tryAcquireAnchorLock and wider than this branch — this branch makes it more consequential by putting identity writes behind that lock, but fixing lock-reclaim semantics belongs in its own change with its own tests.

6 of 7 findings addressed.