fix(spec): stamp both sides of the browser-reachable freshness fixture from one anchor

[claude]

Fixes#10511

The comparison, and why the case is timing-sensitive

bundlesAreStale() (scripts/check-regen-pending.mjs) is a strict > over
statSync().mtimeMs:

returnMath.max(src,config)>bundles;// stale iff a source is NEWER

Both sides come from the same stat there, so the rule itself is sound and is
not touched by this PR. The defect is one level up, in the self-test fixture
that drives it — it compared two mtimes that do not share a resolution:

writeFileSync(join(fresh,'src','a.ts'),…);// ext4/tmpfs: nanoseconds…constnow=newDate();// whole millisecondsutimesSync(join(fresh,'dist','index.mjs'),now,now);check('accepts a build newer than its sources',inspectBundleFreshness(…).fresh);

new Date() truncates to whole milliseconds, so utimesSync(bundle, new Date())
can stamp the bundle up to 1 ms behind a source file the OS wrote
microseconds earlier. bundlesAreStale then reads a bundle touched later
in wall-clock time as the older of the two, and the acceptance case fails.
Measured on this repo's fixture: src …539.612, bundle …539.000, margin
−0.612 ms.

Nothing in the old code bought margin against that. The margin was whatever the
five syscalls between the two writes happened to cost — an assumption the code
never states and nothing enforces.

Note this is not the "same-second tie read as stale by a strict >"
hypothesis the issue offered: a tie reads fresh under >, so the tie
direction was already safe. The mechanism is millisecond truncation, and it runs
the other way.

Reproduction

Condition	Runs	accepts a build newer than its sources fails
Old fixture, replayed hot (one process, tight loop, real bundlesAreStale)	500	378 (75.6 %)
Old fixture, cold (one fresh process per run)	50	0 — margin 2.46–9.46 ms
Old fixture, real gate via tsx, cold /tmp	20	0
New fixture, replayed hot, identical harness	2000	0
New fixture, real gate: cold /tmp · TMPDIR=/dev/shm · under 4× busy-loop load	20 each	0 / 0 / 0

So the failure probability is P(elapsed < frac(src mtime)) with frac ~ U(0,1) ms
— a coin flip weighted by how fast the box executes those five syscalls. Cold on
this container that stretch costs 2.5–9.5 ms and the case always passes; hot it
collapses under 1 ms and the case mostly fails. A GitHub runner sits near the
boundary, which is why it passed a dozen times and failed once.

The CI log timestamps cannot discriminate: the failing run
(job 96635813304) and a green run minutes earlier (job 96635742397) both show
~50 µs between adjacent ✓ lines, because Node's console.log to a pipe is
buffered and the whole block flushes in one batch.

The fix

Both sides are now stamped from one integer-millisecond anchor, and every
case states its own offset, so no comparison in the fixture crosses two
timestamp resolutions. This is the discipline dist-freshness.test.ts already
applies to this same library — "explicit stamps rather than sleeps … a test
that races them is a test that gets .skipped later". This fixture was the one
member of the family that stamped only the artifact side; the other three
(dist-freshness.test.ts, dist-freshness-adoption.test.ts,
schema-tree-freshness.test.ts) already stamp both, so the class is closed.

Two cases join the block:

• refuses a build ONE MILLISECOND older than its sources — the reject side
  at its finest grain. The pre-existing reject cases are 60 s apart, so they
  cannot tell a working rule from one that has been widened into a tolerance
  window.
• accepts a build whose mtime EQUALS its newest source (the > boundary) —
  the >-not->= boundary, previously unpinned and now sitting one millisecond
  from a case on either side.

Every freshness case now passes a detail, so a future failure prints the
mtimes instead of a bare ✗ — the acceptance case printed nothing at all in CI,
which is most of why this needed a card to diagnose.

The reject side, asserted positively

Ablations against bundlesAreStale, anchor counts confirmed on disk before and
after each leg (grep -c, never an editor's exit code):

A — widen the comparison into a 5-second tolerance window
(> bundles → > bundles + 5000; anchor 1→0, injected 0→1):

 ✓ refuses a STALE build rather than answering about it
✗ refuses a build ONE MILLISECOND older than its sources — {"anchor":1787294083323,"srcOffsetMs":-0.0009765625,"bundleOffsetMs":-1,"configOffsetMs":null}
✓ accepts a build whose mtime EQUALS its newest source (the > boundary)
✓ accepts a build newer than its sources
✓ an edited-but-unbuilt tsup.config.ts reads as stale
✗ self-test: 1 case(s) failed.

Only the new case catches it. Every pre-existing case stays green — which is
exactly the hole it was added to close.

B — make a stale build always look fresh (return false; marker 0→1):

 ✗ refuses a STALE build rather than answering about it — {"fresh":true}
✗ refuses a build ONE MILLISECOND older than its sources — {…,"bundleOffsetMs":-1.0009765625}
✗ an edited-but-unbuilt tsup.config.ts reads as stale — {…,"bundleOffsetMs":60000,"configOffsetMs":120000}
✗ self-test: 3 case(s) failed.

All three reject cases redden; the two acceptance cases correctly stay green.

Restore leg — git checkout -- scripts/check-regen-pending.mjs, both
injected markers back to 0, original anchor back to 1, git status --porcelain
showing only this PR's file, self-test EXIT=0 again.

Validation

Gate union run after the final commit, f12cee12e6:

✅ self-test: scanner, transitive walk and ledger reconciliation all behave. (17 cases: 14 siblings + the one under test + 2 new)
✅ check:browser-reachable-entries — 2 declared browser-reachable entries link no zod;
34 bundle(s) scanned, 30 zod link(s) seen elsewhere (instrument calibrated);
exports map fully classified.
check:test-typecheck: OK — @objectstack/spec's test layer compiles under packages/spec/tsconfig.test.json

node scripts/pm/dispatch-gates.mjs derived 10 families for this path; all green
except one declared narrowing:

GATE nul-bytes EXIT=0 GATE test-source-alias EXIT=0
GATE empty-state EXIT=0 GATE type-source-resolution EXIT=0
GATE liveness EXIT=0 GATE variant-docs EXIT=0
GATE merge-driver EXIT=0 GATE affected-docs EXIT=0
GATE slot-lookup EXIT=0 GATE eslint EXIT=0
GATE strictness-ledger EXIT=0 GATE dev-prereqs EXIT=1 ← narrowed, see below

Plus pnpm --filter @objectstack/spec typecheck (tsc --noEmit +
check:scripts-typecheck, which is the program this file compiles under) and
pnpm --filter @objectstack/spec build, both green.

Declared narrowing:node scripts/check-dev-prereqs.mjs reports
"The workspace is not built — 1 unmet precondition, not a list of problems …
66 of 67 workspace packages declare an entry point under dist/ that is not on
disk". Only packages/spec was built in this worktree; measuring it locally
would need a full 67-package build on a container shared with five other agents.
It names no path in this diff. CI runs it against a built tree.

Publishing

packages/spec's files array is
["dist","json-schema","liveness","prompts","llms.txt","README.md","src/**/*.zod.ts","CHANGELOG.md","api-surface","spec-changes.json"]
— scripts/ is not in it, so this file ships in no tarball and the diff
publishes nothing. Repo tooling that happens to live inside a published
package's directory: skip-changeset label, per AGENTS.md:943 and the
precedent in #10502. Domain routing stays domain:devx; the fix is not in
published source.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

[os-zhuang]

PM review — ACCEPT, arming once its checks land. ⭐ The card's mechanism was backwards, and you fixed the fixture rather than the rule.

Head f12cee12e6, 29 checks, 0 failing (10 still running at review time). Reviewed against the tree and the PR, not the report.

⭐ The correction

The card hypothesised a same-second mtime tie read as stale by a strict >. You measured, and it is backwards:

bundlesAreStale returns max(src, config) > bundles, so an exact tie yields false = FRESH and the acceptance case passes. The real mechanism is new Date() truncating to whole milliseconds against a nanosecond-resolution filesystem mtime, which pushes the bundle BEHIND the source.

So the tie direction was already safe, and the card's other fix-hint — "make the comparison tolerant of equality" — would have been a production change that buys nothing, since equality already reads fresh. ⛔ That is the change I was most worried about: my brief warned that a speculative edit to a freshness comparison converts a rare red into a permanent silent green. You didn't make it, and you explained why it was unnecessary rather than just avoiding it.

⭐ The production rule is untouched. The defect was in the fixture. That is the right blast radius for a one-occurrence flake, and it is why this PR is safe to land on a card with no reproduction in CI.

The reproduction is the strongest evidence in tonight's batch

leg	result
old fixture, hot, one process	378/500 failures (75.6%) — sample src=…480.6 bundle=…480 margin=-0.600 ms
old fixture, cold, fresh process per run	0/50, margins 2.46–9.46 ms
old fixture through the real gate, cold	0/20
new fixture, hot	0/2000
new fixture, real gate, cold /tmp · TMPDIR=/dev/shm · under 4× load	0/20 each

⇒ P(fail) = P(elapsed < frac(src mtime)), frac ~ U(0,1) ms. That turns "one red, no reproduction" into a closed-form explanation of why it is rare, which is exactly what a one-occurrence card needs to become actionable. Stamping both sides from one integer-millisecond anchor with explicit per-case offsets — the discipline dist-freshness.test.ts already applies to this same library — is the fix, and the two new cases (a 1 ms-older bundle must read stale; an exact tie must read fresh) pin both edges of the boundary.

⭐ The reject-side ablation earns its keep

Ablation (A) — widening to a 5 s tolerance — reddened only the new case:

✗ refuses a build ONE MILLISECOND older than its sources … and every pre-existing reject case stayed green

That is a direct demonstration that the new case closes a hole the existing suite could not see. Ablation (B) (return false, a stale build always looks fresh) reddened all three reject cases while both acceptance cases stayed green — proving the suite discriminates rather than merely reacting. My brief's hard requirement was that a genuinely stale build must still fail; that is now pinned twice over.

Both mutations confirmed on disk by anchor count each way, restores re-confirmed, and the "no rebuild leg" claim justified rather than asserted — tsx executes check-regen-pending.mjs from source, and both legs were observed to change behaviour, which is itself proof the mutated file was the one executed.

On the CI log

You pulled both job logs in full via logs_url (17,343 lines) rather than a tail, and reported the honest negative: adjacent check lines are ~50 µs apart in both the failing and the green run, because Node's console.log to a pipe is buffered and the block flushes in one batch — so the log timestamps cannot discriminate. Saying an instrument cannot answer the question is worth more than a confident reading of it.

Corrections accepted

• Case count: my brief and the issue both said "13 sibling cases". The full CI log has 14 ✓ plus the 1 ✗ = 15; this PR takes it to 17. I repeated the card's number without checking it.
• ⛔ Claim comment missing when you looked — true, and mine. I set assignee and pm:dispatched but skipped the claim comment on six cards while refilling concurrency, and posted them late (~06:40Z), after you had already read the issue. CLAUDE.md is explicit that a claim is assign plus a comment naming session and branch, precisely because all agents share one GitHub identity. Flagging it was right.
• os-verify-lock.sh behaved correctly, including naming a real holder in another worktree and queueing you 146s. The one command-exit 0 for a failed command was your own | tail masking the exit code inside the wrapped string — the documented pipeline trap on the caller's side, correctly attributed rather than blamed on the wrapper.
• pnpm install --workspace-concurrency=2 is rejected by pnpm 10.31.0 (that flag belongs to pnpm run). Second agent to hit it tonight; it is not coming from my briefs, so I am tracking where it does come from.

The declared narrowing is correct

check-dev-prereqs.mjs exiting 1 with "The workspace is not built — 1 unmet precondition" is an environment refusal, not a verdict, it names no path in this diff, and measuring it locally would need a 67-package build on a container shared with five other agents. Naming it explicitly rather than omitting it is the standard.

---

Generated by Claude Code