fix(devx): the json-schema tree freshness rule can be answered — a generation stamp acquits a tree whose sources were re-checked-out unchanged (#16175)

[claude]

Closes #16175

Clause-②: no

scripts/check-regen-pending.mjs exports three freshness predicates over the same
"the newest artifact mtime is older than the newest source mtime" comparison, and all three share one blind spot: git merge,
git checkout and git worktree add re-check-out a source file with identical bytes and bump its
mtime, the build that follows correctly does not run (turbo's cache hashes content), and the rule then
refuses an artifact that is exactly current.

What each predicate could actually read — measured first, on a built tree at the merge base

The card says the two unfixed siblings "need different evidence, and one of them has no evidence to read
at all". Measured before writing anything, by calling each predicate and each stamp reader against the
real packages/spec after a clean build and then after touch packages/spec/src/data/query.zod.ts with
git status empty:

predicate	evidence file on disk	reader verdict	after the touch
distIsStale	dist/.build-input-hash-dts PRESENT	match	false — acquitted
bundlesAreStale	dist/.build-input-hash PRESENT	match	false — acquitted
schemaTreeIsStale	none	no reader exists	true — the false refusal

⚠️ One premise of the card body is stale, and triage had already recorded it. The card's table marks
bundlesAreStale "not fixed". It was fixed by PR #16240 (6971170791), and triage's pm:retriage
answer says so in as many words: 「已落地的一半(bundlesAreStale,PR #16240,697117079)⛔ 不在范围内;
本卡剩下的只有 schemaTreeIsStale 这一支。」 Measured on origin/main at the merge base — the
predicate ends return buildStamp(specDir).state !== 'match'; — so this PR carries only the schema half,
which is exactly the file surface triage declared. bundlesAreStale is still exercised here as a control.

The evidence given to the one that could read nothing, and where it comes from

⛔ Neither dist/ stamp could stand in, and reaching for one would be #7122's rejected direction
relocated rather than relaxed: both are written at the END of the build, whereas gen:schema is its
FIRST step and is also run standalone (this rule's own refusal message says so) and again by
check:authorable-surface. A dist/ stamp is evidence about dist/, and in the standalone case there
would be none at all.

So the evidence is new. packages/spec/scripts/build-schemas.ts writes
json-schema/.build-input-hash-schema as the last thing it does, over the digest of the inputs that
generation consumed — computed by the same buildInputHash the readers use, so the two cannot drift.

Why that write point is sound, and why one is enough:

• the script rebuilds the whole tree unconditionally, before the --check / --update-base fork, so
  one write point covers gen:schema, check:authorable-surface and gen:authorable-surface-base;
• it sits after every ratchet that can exit 1, and clearOwnedOutputs removes the previous stamp at
  the top of every run — so a stamp exists only for a run that emitted the tree beside it and reached
  the end. A generation that died halfway leaves none;
• json-schema/ is a turbo build output, gitignored, cleared by this generator and no other, so the
  stamp lives and dies with the tree it speaks for. That is the same argument --stamp makes for writing
  inside dist/.

⭐ It may only ACQUIT. Absent, unreadable, or not 64 hex characters is unstamped — no evidence — and
leaves the mtime refusal exactly where it stood (#4690). Nothing that passes today can start failing, and
mtimes remain the only instrument that convicts.

The digest's input set widens in the same commit, which is why this is one PR and not two: the
generators live under packages/spec/scripts/, which was in none of the previous input sets (src/**,
PACKAGE_BUILD_CONFIG, turbo's globalDependencies). An edited generator kept a digest that had not
moved, so a stamp written by the OLD generator would acquit a tree the new one emits differently. A
superset can only ever WITHHOLD an acquittal, never grant one, so the two dist/ stamps become strictly
more honest too.

Acceptance, measured

1 — the false refusal is gone. After a clean build, touch on three sources with git status empty:
all three predicates false, all three stamps match. End to end, the gate the card names:

BEFORE   pnpm --filter @objectstack/spec check:docs   exit 1
           packages/spec/json-schema is older than packages/spec/src.
AFTER    pnpm --filter @objectstack/spec check:docs   exit 0
           222 generated files in sync with packages/spec        (no rebuild)

⭐ 2 — positive control. A genuine byte-level source change (appended line; blob
341bb947 → 42c300d1, git status shows M) still convicts all three:
distIsStale/schemaTreeIsStale/bundlesAreStale all true, all three stamps mismatch. Without this
row, a predicate that stopped refusing and a predicate that went blind read identically. Restored by
git checkout HEAD --, verified by blob hash equality.

3 — ablation. The acquittal line removed from schemaTreeIsStale (on-disk landing proved by an
occurrence count 1 → 0 and a changed blob hash; restored under a trap and verified back to the HEAD blob):
acceptance 1 reverts to schemaTreeIsStale = true while its two siblings stay false — the differential
isolates the change to this predicate alone. No build/dist leg applies: check-regen-pending.mjs is a
root script the probe imports by path, resolved through no package exports.

Declared file surface — and where I went past it

Triage declared three implementation sites. All three, and nothing else on that axis:

• scripts/build-input-hash.mjs — widened input set, SCHEMA_STAMP_BASENAME, inspectSchemaStamp, writeSchemaStamp
• scripts/check-regen-pending.mjs — schemaTreeIsStale wired; schemaStamp / recordSchemaStamp wrappers · scripts/check-regen-pending.d.mts follows (check:declaration-mirrors green)
• packages/spec/scripts/build-schemas.ts — one write point at the end of generation

⚠️ Touching packages/spec is the cross-domain exception triage authorized (precedent PR #16240); the
domain:spec seat carries the notification duty from this declaration.

⚠️ Beyond it, and why — reported rather than assumed. Five further files, none of them a second
implementation site:

1. packages/spec/scripts/schema-tree-freshness.test.ts and
   packages/spec/scripts/build-schemas-check-mode.test.ts — tests, required by triage in its own
   words (「照已落地那一半的做法用消融证明单向性」). The second is the only place that can notice the write
   point going missing: without it the rule degrades to unstamped, which is the conservative verdict, so
   every gate stays green and the only symptom is the false refusal quietly returning.
2. packages/spec/scripts/def-key-collisions.test.ts — mechanically forced. Both suites spawn the real
   generator out of a copied scripts/ in a flat tmpdir; its new repo-root import walks off the top of the
   filesystem from there, and the spawn dies with MODULE_NOT_FOUND before any assertion runs. Both
   fixtures now sit at the repo's own depth with the root scripts symlinked beside them, so they keep
   running the production import graph instead of a reduced one.
3. packages/spec/vitest.repo-tests.json — a gate named it. Both suites now genuinely read outside
   their package; check:cross-package-test-inputs refused until they were declared.
4. scripts/check-dev-prereqs.mjs and packages/spec/scripts/lib/json-schema-out-dir.ts — comment-only,
   and both are reverse-read hits (below).

Reverse-read — which existing sentence does this make false

Scanned before pushing; both hits fixed in place, zeros reported as zeros.

Made false, fixed:

• scripts/check-dev-prereqs.mjs — "THE INPUT SET, and why each part is in it" enumerates the digest's
  inputs and is that gate's stated authority on them. The widening makes the list incomplete. One bullet added.
• packages/spec/scripts/lib/json-schema-out-dir.ts — "gen:schema emits (category)/(Name).json plus the
  bundled objectstack.json" reads as exhaustive and no longer is. Corrected, with the one thing a future
  reader could get actively wrong stated: ⛔ the stamp may never get a FOREIGN_JSON_SCHEMA_ARTIFACTS
  entry — exempting it from the sweep would leave a stamp acquitting a tree nobody emitted.
• scripts/check-regen-pending.d.mts header ("five functions"), scripts/build-input-hash.mjs header
  ("the two stamps") and inspectStamp's docblock ("ONE of the two stamps") — all updated with the edit.

Zeros — read and unaffected:

• packages/spec/scripts/lib/dist-freshness.ts — cites schemaTreeIsStale as precedent for guarding in
  the generator rather than its callers. Still true; that is exactly what this write point does.
• packages/spec/scripts/lib/json-schema-out-dir.ts module title — "the one output directory two
  generators write into". Still two: the stamp is gen:schema's own output, not a third writer.
• check-generated.ts's readsSchemaTree ordering rules, schema-closure.ts's empty-category rule,
  regen-artifacts.mjs's packages/spec/json-schema/** row — none says anything this changes. (That last
  row's .gitignore:61 line number is drift that predates this branch — the pattern is at :63; noted,
  not filed, no PR or reader is routed through it.)

Tests re-judged in place, never deleted

All six original cases in schema-tree-freshness.test.ts still assert exactly what they were written to
assert, because none of those sandboxes carries a stamp — and that is now the property being pinned:
no stamp is unstamped, unstamped is no evidence, and no evidence leaves the mtime verdict standing. The
re-judgement is recorded in the file header and on the false-green case itself. Six new cases supply the
evidence and pin what it may and may not do: acquittal on match; refusal held on mismatch; refusal held
on a non-digest stamp; a missing tree stays stale however good the stamp; a mismatched stamp may not
overturn a verdict of fresh; and the stamp is invisible to both sides of the mtime rule, so it cannot vouch
for itself.

Changeset — measured, not defaulted

skip-changeset would have been wrong. json-schema is in @objectstack/spec's published files[], so
the stamp travels in the tarball — npm pack --dry-run --json, on the built tree:

STAMP FILES IN TARBALL: dist/.build-input-hash, dist/.build-input-hash-dts, json-schema/.build-input-hash-schema
positive control (json-schema/ ships): json-schema/.build-input-hash-schema, json-schema/ai/Agent.json, …

One 65-byte file joins the published package; no export, schema key, registry entry or runtime behaviour
moves. @objectstack/spec: patch.

Verification

dispatch-gates --ran reconciliation on the final commit (git rev-parse --short HEAD = 7d1292f393):
87 derived, 84 run, 3 NOT MEASURED, 0 unrun.

• pnpm --filter @objectstack/spec build — green (all three stamps written, identical digest, which also
  cross-checks the new writer against --stamp's)
• pnpm --filter @objectstack/spec typecheck — green (tsc, check:scripts-typecheck, check:test-typecheck)
• pnpm --filter @objectstack/spec test — 470 passed, 1 skipped (471 files) · test:repo — 29 files, 503 passed
• spec gates green: check:authorable-surface, check:docs, check:generated (15/15 artifacts current),
  check:browser-reachable-entries
• root gates green: check:declaration-mirrors (+self-test), check:merge-driver, check:nul-bytes,
  check:cross-package-test-inputs, check:published-files, check-dev-prereqs --self-test,
  check:self-test-wired, check:scripts-symbol-anchors, check:type-check-coverage,
  check:test-source-alias, check:tier-file-adoption, changeset gates, and the rest of the derived 84
• ⊘ NOT MEASURED (3+1), left to CI: check:dual-build-cjs-loads, check:lean-entry-closure and
  check:type-check-debt each exit 3 — PREREQUISITE NOT MET, they read a whole-repo dist/ this
  container has not built (Build Core owns that run). check:pm-dispatch-gates exceeded the container's
  foreground cap at 560s (exit 124) — a checker-health self-test for a file this diff does not touch.
  ⛔ None of the four is a pass or a failure.

A measured cost, reported rather than buried: because the digest now covers packages/spec/scripts/**,
editing anything there — including a script test — moves the digest and makes check:browser-reachable-entries,
check:generated and the boot gate demand a rebuild first. Observed twice during this run. It is the same
ergonomics that src/**/*.test.ts already carries (those are in the digest today), and the alternative — a
rule deciding which files under scripts/ are "really" inputs — decides wrong the day someone extracts a
helper, in the acquitting direction. Triage's stop condition was 大量无关包的 boot gate 失效; measured,
AMPLIFIERS = ['packages/spec'], so exactly one package stamps and the blast radius is that one package.

Draft, not armed.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/spec/vitest.repo-tests.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/spec/vitest.repo-tests.json) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 136 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 15805ea32b8c3bf46196de7664435ed25268e156 → packageMentionDocs.

[baozhoutao]

PM 复核:收下,已 undraft + 武装。 你开篇那条更正是对的 —— 而错的是本席的简报,第六次。

⭐⭐ 0. 简报把卡面一张陈旧的表原样转述了,而分诊早就不这么说

本席的派单写着「两个兄弟谓词需要与 #14985 所供不同的证据」,并把 bundlesAreStale 当成未修。

实测(origin/main,scripts/check-regen-pending.mjs):

:354 export function bundlesAreStale(specDir = SPEC_DIR) {
       …mtime 比较…
:368   return buildStamp(specDir).state !== 'match';   ← 赦免腿已经在了

⇒ bundlesAreStale 已由 PR #16240 修好,卡面那张表是陈旧的。而分诊在 pm:retriage 的答复里声明的文件面本来就只写了 schemaTreeIsStale 一支:

scripts/check-regen-pending.mjs —— schemaTreeIsStale 接线;scripts/check-regen-pending.d.mts 随 check:declaration-mirrors 机械同步。

⇒ 本席的简报与分诊自己声明的文件面相矛盾。你按分诊的文件面交付、并把卡面的陈旧处更正出来,是对的。

⚠️ 顺带记一次本席自己的近失手:第一次读 bundlesAreStale 只打印了 9 行,赦免腿在第 15 行、被窗口切掉了,差点据此发出一条「你只交了一半」的错误异议。⭐ 一个窗口不是一次阅读 —— 救我的是先把整个函数打完再下判断。本班第 9 次。

1. 给「什么都读不到的那一个」造的证据 —— 这是本卡的真难点,你解对了

卡面写明两个兄弟「需要不同的证据,而其中一个根本没有证据可读」。你没有拿 dist/ 的任何一个 stamp 顶替,理由写得很硬:

• 两个 dist/ stamp 都写在构建末尾,而 gen:schema 是构建的第一步,还会被 check:authorable-surface 单独调用 ⇒ 一个 dist/ stamp 是关于 dist/ 的证据,而单独调用的那条路径根本不会有证据。

于是让生成器自己在末尾写 json-schema/.build-input-hash-schema,并且四个性质都对上:写点在所有能 exit 1 的 ratchet 之后;clearOwnedOutputs 在每轮开头清掉上一个 stamp ⇒ 只有「产出了旁边那棵树并且跑到了终点」的运行才留下 stamp;json-schema/ 是 turbo 产物、被 gitignore、只由这个生成器清 ⇒ stamp 与它的主体同生共死。

⭐ 而最要紧的是那条单向性质:stamp 只能赦免,永不能定罪 —— 未盖章/不匹配都让 mtime 的拒绝原样成立。你还把它钉成了一条断言(「a mismatched stamp may not overturn a verdict of fresh」)。⛔ 没有这条,一个 stamp 机制就从「减少假红」滑成「制造假绿」,而假绿是没人会发现的那个方向。

写者与读者一致那条交叉核对(全量构建后三个 stamp 持有同一个摘要 0308b7c65a…,一个由生成器写、两个由 check-dev-prereqs --stamp 写)是对的收尾。

2. 钉子就地重判 —— 形状正确

六条原用例逐字保留并重判:它们仍然断言当初要断言的东西,恰恰因为那些沙箱里没有 stamp —— 而「没有 stamp = 未盖章 = 没有证据 = mtime 判决原样成立」正是它们现在钉住的性质。⛔ 一条没删。六条新用例里,「stamp 对 mtime 规则的两边都不可见,所以它不能为自己作证」这条是很多人想不到要钉的。

3. changeset 判 patch 而非 skip —— ⭐ 量对了一件不显然的事

json-schema 在 @objectstack/spec 的 files[] 里(本席核过:['dist','json-schema','liveness',…])⇒ 那个 65 字节的 stamp 会进已发布的 tarball。你用 npm pack --dry-run --json 在构建后的树上直接列出来看,还带了 json-schema/ai/Agent.json 当阳性对照证明这棵树确实会发。⛔ 默认 skip 在这里是错的,而它错得完全不显眼。

(分诊其实也写了这一条;你独立量到同一个结论,比引用它更有力。)

4. 越出声明文件面的每一处都申报了,没有默认

四类,各有理由:分诊自己要求的测试;一处机械强制(两个 suite 从扁平 tmpdir 里 spawn 真生成器,新的仓根 import 会走出文件系统顶端、在任何断言之前 MODULE_NOT_FOUND);一处被门禁点名(check:cross-package-test-inputs 在两个 suite 声明为 repo test 之前拒绝放行);两处只改注释的反向读命中。

⭐ 其中 json-schema-out-dir.ts 那条你不只改对了,还把下一个人最可能弄错的事写了下来:那个 stamp 永远不可以拿到 FOREIGN_JSON_SCHEMA_ARTIFACTS 条目 —— 把它豁免出清扫,就会留下一个为没人产出过的树作证的 stamp。那是把单向性质反过来用的那条路。

5. 代价报出来了,没埋掉

摘要覆盖到 packages/spec/scripts/** 之后,改那里的任何东西(包括脚本测试)都会让三个门禁先要一次重建 —— 你观察到两次、都在重建后消解,并指出 src/**/*.test.ts 今天已经是同样的人机工学。而分诊给的停止条件是「widening 会弄坏一大票无关包的 boot gate」:你量了 AMPLIFIERS = ['packages/spec'] ⇒ 恰好一个包盖章,爆炸半径就是它 ⇒ 停止条件不成立,所以没走路线 C。⭐ 一个被量过并判定不成立的停止条件,和一个没人去看的停止条件,是两回事。

你拒绝「定一条规则判断 scripts/ 下哪些文件『真的是』生成器输入」也是对的,理由正确:那条规则会在有人抽出一个 helper 的那天判错,而且是朝赦免的方向判错。

6. trailer —— 处置正确

两个带错误拼写的 commit 未推送(你先核了 origin 的 ref 仍在 base),于是 soft-reset 回记录在案的 base 并用 model-free 对重提一次,单次推送是 fast-forward。⛔ 没有改写任何已共享的历史、没有 force-push、没有 amend 任何已推的东西。这正是那条规则的分界线所在。

---

Generated by Claude Code