docs(spec): correct the 17.4.0 duration-keys erratum falsified by #17783/#17785

[zhuangjianguo]

Fixes #18076

Clause-②: no — the landing surface is prose inside one already-compiled packages/spec/CHANGELOG.md entry plus an erratum line. No schema key, no accepted-set change, no new exported symbol, no new key on a published payload, and no path under packages/**/src/** moves.

skip-changeset: no package publishes anything from this change.

The ruling this PR implements

Director seat, decision batch #119 item 1, 2026-09-12T04:15Z, maintainer's own word 1A·2A·3A·4D·5A: 「同意」, implemented once already by ef47459474 (#17896). This card applies the same remedy shape to a second falsified instance:

A: correct the two published CHANGELOG entries in the repository, with a post-release erratum note. … the … sentences … are corrected to the post-#17013 truth, each followed by one erratum line naming PR #17013 and the correction date.

Before editing, run the release tooling's dry-run (changeset version on a scratch branch) and record that a manual edit inside an already-compiled section survives … if it does not survive, stop and report.

skip-changeset: no package publishes anything from this change.

Step 2 first — the survival gate, run before any edit

On a local scratch branch off 484484041a (scratch/issue-18076-survival-gate), discarded afterward:

reading	value
marker inserted into the already-compiled ## 17.4.0 "Keys deliberately left alone" paragraph	SURVIVALGATEMARKER18076XQ7
marker count before changeset version	1
dark control (ZZQV18076NOPE, invented at read time) before	0
pnpm changeset version	exit 0, "All files have been updated"
marker count after changeset version	1 — the manual edit survives
where the marker ended up	line 2869 → line 7316 — pushed down, content intact
dark control after	0 — unchanged, confirming the grep methodology (not a broken instrument reading a false zero)
lit control — did the tool actually rewrite the files?	yes: a new ## 17.5.0 section is prepended, packages/spec/package.json moves 17.4.0 → 17.5.0, and 452 of 453 pending .changeset/*.md files are consumed
restore	git checkout -f back to the real branch; diff <(git show origin/main:packages/spec/CHANGELOG.md) packages/spec/CHANGELOG.md → identical; scratch branch deleted

⇒ changeset version prepends a new section and never rewrites an already-compiled one. Re-measured on this tree rather than inherited from ef47459474's reading, per the ruling's explicit instruction.

What changed, and why each corrected claim is true of today's tree

packages/spec/CHANGELOG.md, inside the already-released ## 17.4.0 entry (commit e9fcd6b, "Keys deliberately left alone"), said:

ServiceLevelObjective.errorBudget's burn-rate window and the OpenTelemetry exporter timeout name no unit anywhere in their prose, so both are outside the gate's population entirely. Pin tests assert each of these, so a later sweep cannot read this card as "every duration-shaped number on these files".

All three claims are false, verified on this tree independently of the card:

• Half 1 — packages/spec/src/system/metrics.zod.ts:368-375 (SLO_BURN_RATE_WINDOW_RETIRED): ServiceLevelObjective.errorBudget.burnRateWindows[].window was renamed to durationSeconds in @objectstack/spec 17 (spec: 5 duration key(s) in system/metrics.zod.ts name their unit only in JSDoc — #15939 Ruling A remediation (5 of the 21-row delta) #17783), tombstoned with retiredKey() at metrics.zod.ts:402/:498. The pin that held the bare spelling is now metrics.test.ts:612, it('REFUSES the burn-rate \window` with a rename naming `durationSeconds`', …)`.
• Half 2 — packages/spec/src/system/tracing.zod.ts:546-550: OpenTelemetryCompatibility.exporter.timeout was renamed to timeoutMs (spec: 4 duration key(s) in system/tracing.zod.ts name their unit only in JSDoc — #15939 Ruling A remediation (4 of the 21-row delta) #17785), tombstoned with retiredKey(); its batch.exportTimeout sibling moved to exportTimeoutMs the same way (:586/:601). The pin is now tracing.test.ts:594-611, it.each([['exporter.timeout', 'timeoutMs'], …])('REFUSES the retired \%s` with the rename in the message', …)`.

The corrected paragraph quotes the falsified sentence, states the truth with both PR numbers and both new key names, and closes with one erratum line naming this PR and the correction date, matching ef47459474's shape.

The paragraph's other four claims were checked and are still true (not touched, per the ruling's scope boundary):

• FailoverConfig.dns.ttl — still bare, disaster-recovery.zod.ts:148, under the same externalVocabulary exemption comment.
• CacheAvalanchePrevention.lockout.lockTimeoutMs — still milliseconds, cache.zod.ts:162.
• MetricExportConfig.batch.size — still a bare record count, metrics.zod.ts:702.
• QueueConfig.rateLimit.max — still a bare task count, worker.zod.ts:~276.

The erratum line's PR number — how it went in, and the fix for a review finding

#18077 (the PR number for this correction) is not knowable before the PR exists, so the first pushed commit (bfc744c98c) carried a placeholder, #PRPLACEHOLDER18076, in the erratum line's parenthetical, meaning to fill it in once the PR was open. That fill-in commit (ac68eff364) was made locally but not pushed before the round's first status check ran against bfc744c98c, so a reviewer correctly caught a shipped placeholder. It is now pushed; HEAD is ac68eff364, verified directly against the remote rather than assumed:

$ git show origin/claude/issue-18076-changelog-duration-keys-erratum:packages/spec/CHANGELOG.md | grep -c PRPLACEHOLDER
0
$ git show origin/claude/issue-18076-changelog-duration-keys-erratum:packages/spec/CHANGELOG.md | grep -n 'Corrected after publication, #18077'
7331:  population as of `@objectstack/spec` 17. (Corrected after publication,

Placeholder sweep of the whole diff, with controls (git diff origin/main..HEAD -- packages/spec/CHANGELOG.md, 35 lines):

• Pattern PLACEHOLDER|\bTODO\b|\bTBD\b|\bXXX\b|\bFIXME\b|<[A-Z_]+>|\{\{.*\}\} (case-insensitive) over the diff: 0 matches.
• Lit control, drawn a different way: appended a synthetic PRPLACEHOLDER99999 line to the same scanned text and re-ran the identical pattern — 1 match, confirming the regex class actually fires and the 0 above is a real zero, not a typo'd pattern reading a false clean.
• Positive control: 18077 appears exactly once in the diff — the one erratum reference, present and correctly substituted.

Verification

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 54 local gate families for this diff (all matched via broad packages/** / packages/spec globs — this path carries no gate of its own). Ran all 54 twice — once on bfc744c98c, again on the final ac68eff364 after the placeholder fix landed — both times reconciled with --ran against the recorded exit codes, same result both runs:

Run reconciliation — 54 derived, 50 run, 4 NOT-MEASURED, 0 UNRUN.
✓ dispatch-gates --ran: 54 derived famil(ies) accounted for — 50 run, 4 NOT-MEASURED (4 DERIVED from a recorded exit 3).

• 50/50 that ran, passed (pnpm check:nul-bytes, check:release-notes, check:release-page-status, check:release-section-coverage[--strict], check:changeset-gate-self-tests, check:doc-authoring, check:page-declaration-shape, check:published-files, check:slot-lookup, check:test-source-alias, check:type-source-resolution, and 39 more — full list in this branch's derivation).
• 4 NOT-MEASURED, exit 3 (PREREQUISITE NOT MET), declared rather than swallowed: check:dts-closure, check:dual-build-cjs-loads, check:lean-entry-closure, check:sourcemap-no-sources-content — each refuses on a missing dist/ in this fresh worktree ("Run pnpm build first … this is NOT a pass: nothing was measured"). These are whole-repo build-completeness gates unrelated to this diff's content (no code, no export, no dist path moves); running a ~80-package pnpm build to satisfy them is disproportionate to a one-line CHANGELOG correction, and CI builds fresh before running them.
• No changeset added; check:changeset-gate-self-tests (the gate's own self-test) is green. skip-changeset now shows as an applied label on this PR (not applied by this session — labels were left untouched per this card's operating constraints).
• pnpm check:nul-bytes and a direct grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' both clean on the diff.
• node scripts/check-commit-card-trailers.mjs --range origin/main..HEAD: clean on both commits — no card-relation trailer, model-free trailer pair.

No packages/spec test/typecheck run beyond the above: this diff touches no code, no export and no public surface byte, so per this repo's verification-scope convention there is nothing for pnpm --filter @objectstack/spec test/typecheck to newly exercise.

🤖 Generated with Claude Code

https://claude.ai/code/session_015c5G6TmpMKgnusmTpD7Ntt

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/spec/CHANGELOG.md), 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/CHANGELOG.md) — 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 484484041a528131fb5c52622f87dcd1e97d5afd → packageMentionDocs.

[claude]

ACCEPT — PR #18077

Epic PM for the #15939 subtree, session_015c5G6TmpMKgnusmTpD7Ntt, 2026-09-13T19:55Z. Checked against GitHub and the tree, ⛔ not against the round's own account of itself.

item	reading (taken by this seat)
PR shape	draft, base main, first body line Fixes #18076, head ac68eff364
every check green	35 success + 7 skipped, 0 failed, 0 incomplete across 42 names — the whole set, ⛔ not the required subset. Legacy Vercel status success
clause-② carriers	check-clause2-carriers --pair 18077 → exit 0, run by me after the head settled
scope	exactly one file, packages/spec/CHANGELOG.md, +19/−5
changeset	none, and none owed — skip-changeset, matching the merged precedent #17896's label set exactly (documentation, size/s, skip-changeset)

Why no in-seat clause-② review is owed here — a reading, ⛔ not an omission

The path leg does not fire: node scripts/pm/dispatch-gates.mjs --tier packages/spec/CHANGELOG.md reports "no path-derived mandate: the surface hits none of the 3 declared glob(s)" — this file is outside the packages/spec/src/** contract surface. The content leg does not fire either: the diff is prose in an already-compiled section, moving no accept/reject outcome, no key, no export. The precedent this card copies, #17896, carried no needs:contract-review. ⇒ Recorded rather than skipped silently. This is the difference from #17635, where three paths under packages/spec/src/** made the path leg fire regardless of the declaration.

The survival gate — run, controlled, and ⛔ not inherited

The dispatch made this mandatory and forbade taking #17896's result. The round ran it on a scratch branch off 484484041a, discarded afterwards:

reading	value
marker in the target paragraph, before pnpm changeset version	1
dark control (ZZQV18076NOPE) before	0 — grep exit 1, so a real zero and not a broken instrument
pnpm changeset version	exit 0
marker after	1 — line 2869 → 7316, pushed down, content intact ⇒ SURVIVES
dark control after	0
lit control — did the tool actually rewrite the tree?	yes: a new ## 17.5.0 section prepended, packages/spec/package.json 17.4.0 → 17.5.0, 452 of 453 pending changesets consumed
restore	git checkout -f; the working file then byte-identical to git show origin/main:packages/spec/CHANGELOG.md; scratch branch deleted

Verified by me against the tree, not taken from the report

• Both rename claims: system/tracing.zod.ts:551 states `OpenTelemetryCompatibility.exporter.timeout` was renamed to `timeoutMs` in @objectstack/spec 17, :602 the batch.exportTimeout → exportTimeoutMs sibling; system/metrics.zod.ts:368-375 states the burn-rate window → durationSeconds rename and its reason.
• The paragraph's four untouched claims all still hold: FailoverConfig.dns.ttl bare with its externalVocabulary meta intact; CacheAvalanchePrevention.lockout.lockTimeoutMs describing "Maximum lock wait time in milliseconds"; MetricExportConfig.batch.size a bare record count; QueueConfig.rateLimit.max describing "Maximum tasks per duration". None falsified, none touched.
• The falsified sentence exists in exactly one place: 0 hits across docs/ and content/ (lit control — 73 files carrying "duration" — and a dark control at 0). content/docs/references/system/metrics.mdx renders burnRateWindows as an opaque object[] naming no inner key, so no docs page teaches a retired spelling.
• The erratum line reads "(Corrected after publication, docs(spec): correct the 17.4.0 duration-keys erratum falsified by #17783/#17785 #18077.)" — the placeholder is gone; PRPLACEHOLDER count 0 on the pushed head.

Two notes for the record

1. The skip-changeset label was applied by me at 19:29Z, not by automation. The round's report says otherwise. It is not consequential to the work, but the audit trail should name the actor. The underlying miss is mine: Check Changeset went red at 19:26 demanding that label, the gate's remedy is a label, and I had forbidden the round from touching labels — so for a skip-changeset-shaped card the label belongs in the dispatch, not in a repair after the gate fires.
2. The round distinguished its own cap from a platform cap-kill, and that was the right call. Its check:slot-lookup hit exit 124 under a self-imposed 90s per-command budget; it identified that as self-inflicted rather than a container cap, re-ran at 280s, and got exit 0. That is exactly the hazard filed as [finding] dispatch-gates --ran silently discards an explicit NOT-MEASURED claim when the same command also carries a run line — and a cap-kill exit (124/143) reads as RUN #18074 — where a recorded exit 124 is silently counted as run — handled instead of declared away.

Four gate families read exit 3 PREREQUISITE NOT MET (check:dts-closure, check:dual-build-cjs-loads, check:lean-entry-closure, check:sourcemap-no-sources-content), each refusing on a missing dist/ in a fresh worktree. Declared, ⛔ not counted green; a whole-repo build for a one-paragraph markdown fix is disproportionate and CI covers them. Reconciliation read 54 derived, 50 run, 4 NOT-MEASURED, 0 UNRUN on both commits.

Next

Turning ready and enqueuing. The merge queue is the only recognised landing path.

_{epic PM for #15939 · session_015c5G6TmpMKgnusmTpD7Ntt · 2026-09-13T19:55Z}

---

Generated by Claude Code