feat(spec)!: the four system/logging.zod.ts duration keys carry their unit in the key name (#17782, ruling A on #15939) - #17999

📓 Docs Drift Check

8 anchor(s) derived from 1 changed package(s); no hand-written page names any of them. ⚠️ 6 changed file(s) yielded no anchor (packages/spec/authorable-defaults/system.json, packages/spec/authorable-surface/system.json, packages/spec/src/migrations/entries/retired-keys/18.system__HttpDestinationConfig__batch.flushInterval.ts, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin a3d98401307629df9d91471e7fea64497e18e174 && git checkout a3d98401307629df9d91471e7fea64497e18e174
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin c45ea8c3964f2d9b6d414d9ee7b7fd6c5ba4cf78 a5976809c2b11a90c68c5ad9f66436cba7366590 && git checkout -B drift-repro c45ea8c3964f2d9b6d414d9ee7b7fd6c5ba4cf78 && git merge --no-ff a5976809c2b11a90c68c5ad9f66436cba7366590

node scripts/docs-audit/affected-docs.mjs --json c45ea8c3964f2d9b6d414d9ee7b7fd6c5ba4cf78

Docs Drift Check answered by hand — the gap it declares is real, and it is empty here

Epic PM for #15939 · readings on origin/main @ 611795e40 (this PR's base), 2026-09-13T10:51Z.

Docs Drift reads 8 anchors, no hand-written page naming any of them. Left there, that would be over-read: the run's own caveats say so in two places, and both apply to this diff.

1. 6 of the 12 changed files yielded no anchor at all — including both ratchet JSONs and the retired-key entries — so "pages documenting them are NOT COVERED by this run".
2. The structural one: "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." That is the same class this epic tracks as its residual landing risk on finding: check:duration-unit-keys reads .describe() but not JSDoc — a duration key documenting its unit only in JSDoc never enters the population, and one card already recorded a wrong reason because of it #15939 (5652790672): a green gate cannot see a stale sentence.

So the check was done by hand rather than inferred. Hand-written docs only — content/docs with the generated references/ and the release-owned releases/ excluded:

Lit controls on that same corpus: logging 21, timeout 51, destinations 2. Dark control zzqqxx 0 — so the two zeros are readings, not an empty grep.

The single file hit is content/docs/getting-started/quick-reference.mdx:100:

| **[Logging](/docs/references/system/logging)** | logging.zod.ts | LoggingConfig | Structured logging |

An index row naming the def and the source file, and no key name on it (flushInterval / initialDelay / timeout all read 0 in that file). It stays true after the rename.

⇒ no hand-written page goes stale on this diff. The one page that renders these keys is content/docs/references/system/logging.mdx, which is generated and is regenerated in this PR (+36/−7).

Recorded rather than left implicit because this PR is the first in the #15939 epic where Docs Drift named nothing — sibling PR #17986 named six pages, five of them false positives off a generic timeoutMs string anchor and one a genuine hand-written protocol page. A quiet run and a clean surface are different facts, and only the second one is established above.

⛔ No change requested. Nothing here is a defect and nothing in this PR moves because of it.

Generated by Claude Code

The red TypeScript Type Check is on a superseded head — no fix owed, and nothing to re-run

Epic PM for #15939 · 2026-09-13T11:00Z. Recorded because the PR's check history now shows a red, and the next reader (the contract review included) should not spend a cycle on it.

What failed: the aggregator job TypeScript Type Check, run 34752812282, on head 360d095dbd. Its log is unambiguous and it is not a type error — three of its four lanes passed and the fourth was cancelled:

ok       typecheck-consumers
ok       typecheck-debt
ok       typecheck-source-gates
##[error]type-check lane `typecheck-workspace` concluded `cancelled` -- expected `success`.
check-typecheck-lanes: FAILED (1 problem(s) above).

Why the lane was cancelled: the branch head moved from 360d095dbd to 359cad806b — the dev pushed Merge remote-tracking branch 'origin/main', and that push cancelled the run in flight. The signature is visible across the whole dead head, not just this one job: of its 46 check runs, 8 are cancelled — all six Test Core shards, Lint & Repo Gates, and Type Check · workspace — with exactly one failure, the aggregator that refuses to report green when a lane it depends on has no verdict.

⇒ the aggregator behaved correctly. A cancelled lane's result is unknown, and riding green on unknown is precisely what it exists to prevent. ⛔ This is not a flake and it is not being called one.

The live head is healthy. On 359cad806b at 11:00Z: 32 check runs — 12 success, 2 skipped, 18 still in progress, 0 failures.

⇒ No fix is owed, nothing is ported, and ⛔ no job is re-run — the correct head is already under test and a re-run on a superseded commit would measure nothing. This PR stays watched until its live head is green.

⚠️ One thing the base merge does not yet include: it merged main at 611795e405, which lands just before cbcae14bca — sibling PR #17983 (#17781), merged 10:59:33Z. Not a problem to solve now (the merge queue merges against the latest main), but worth knowing when reading check:generated and the migration registry on this branch.

Generated by Claude Code

Contract review

Head-sha: a5976809c2b11a90c68c5ad9f66436cba7366590

Isolated at-tier review from a fresh worktree at the head sha (git worktree add /tmp/review-17999 a5976809c2…), origin/main at b2c51cb881, merge-base ae1b258889. Every number below was re-measured unless listed under "taken on the body's word". No dispatch order or PM verdict was read.

① Derived judgments

• HttpDestinationConfig.batch.flushInterval → flushIntervalMs (default 5000) — RIGHT. On origin/main logging.zod.ts:276-278 the JSDoc reads "Flush interval in milliseconds" and the key carries no .describe(); the chain int().positive().optional().default(5000) is byte-identical after the rename; the tombstone refuses (pin passes; ablation A below).
• HttpDestinationConfig.retry.initialDelay → initialDelayMs (default 1000) — RIGHT. origin/main :291-293, same JSDoc-only unit, same unchanged chain, tombstone refuses.
• HttpDestinationConfig.timeout → timeoutMs (default 30000) — RIGHT. origin/main :302-304, JSDoc-only unit, unchanged chain, tombstone refuses. It is the one top-level key of the four (declared at the def's own indent; system/HttpDestinationConfig:batch / :retry are the surface rows, their children are not).
• LoggingConfig.buffer.flushInterval → flushIntervalMs (default 1000) — RIGHT. origin/main :670-672 on LoggingConfigSchema (declared :575 on main), JSDoc-only unit, unchanged chain, tombstone refuses.
• Ms is the family spelling — RIGHT. Key-position counts on origin/main packages/spec/src/**/*.zod.ts: *Ms: 104, *Seconds: 40, *MS: 1, *Millis: 6 (all .ts: 293 / 77 / 3 / 9; dark control *Qqzv: 0). Every MS/Millis site listed is an external-API mirror (maxCommitTimeMS on driver-nosql, idleTimeoutMillis / connectionTimeoutMillis on datasource / driver / postgres). The body's 272 / 75 is not reproducible under any corpus definition I tried (281 / 293 / 110 depending on tests and ?), but the ordering is the same under all of them, so the conclusion stands; the number in the registered prose is a claim, not a reading.
• Tombstones on non-strict objects (ADR-0049) — RIGHT and it matters. grep -E 'strictObject|\.strict\(' on the file's code returns nothing (the four .strict() hits grep -c finds at :320/:345/:365/:753 are JSDoc prose); on a non-strict shape a bare deletion is a silent strip, so retiredKey() is exactly the route AGENTS.md prescribes.
• Two-flushInterval handling — RIGHT, no cross-wiring. The batch prescription names HttpDestinationConfig.batch.flushInterval, targets flushIntervalMs, and says LoggingConfig.buffer.flushInterval "is a different key with its own rename"; the buffer one is the mirror image. The two RETIRED_KEYS_BY_MAJOR[18] rows are system/HttpDestinationConfig:batch.flushInterval and system/LoggingConfig:buffer.flushInterval, distinct and correctly pathed. Proof beyond reading: ablation B swapped the two prescription constants between the two retiredKey() calls (:326 ↔ :759) — exactly the two flushInterval REFUSES pins failed (2 failed / 44 passed), so the pins discriminate by def, not by leaf; and the defaults are pinned separately (5000 on batch, 1000 on buffer) in the "accepts" pins. Restored byte-identical (9768a4bb…).
• Describe channel — RIGHT, inside ruling A, not an unflagged widening. Verified on origin/main: none of the four lines carries .describe( (lit control: 60 .describe( occurrences elsewhere in the same file; dark control wqxzplomb 0). Ruling A's own predicate (batch Add comprehensive test coverage for ObjectStack spec protocols - 100% coverage achieved #65, restated in the ruling) is "the gate refuses a duration key whose JSDoc names a unit its describe does not", and feat(spec): refuse a duration key whose JSDoc names a unit its describe does not #17635 must land last "into a tree it already reads as clean" — an absent describe names no unit, so adding one is required for that tree to read clean. The landed siblings fixed an existing describe (spec: 1 duration key(s) in system/tenant.zod.ts name their unit only in JSDoc — #15939 Ruling A remediation (1 of the 21-row delta) #17784 'Schema cache TTL' → '… in seconds', spec: 1 duration key(s) in kernel/plugin-security-advanced.zod.ts name their unit only in JSDoc — #15939 Ruling A remediation (1 of the 21-row delta) #17781 'Maximum execution time' → '… in milliseconds'); this card adds where none existed — same predicate, one more step. The resulting mdx rows are flagged: the changeset "Why" says "given the describe it never had", and the declaration is Clause-②: yes.
• ADR-0087 kit — RIGHT. One semantic entry logging-durations-unit-in-key (id equals the changeset marker; check-adr-0087-registration.mjs --base ae1b258889 exit 0) plus four retired-key rows. registry.ts is generated: pnpm --filter @objectstack/spec gen:migration-registry on the head tree rewrote it to the identical blob 4d7e7d2e99…. D3-not-D2, both halves verified: stack.zod.ts contains logging 0 times (lit control objects 107 lines); LoggingConfigSchema|HttpDestinationConfigSchema appear in packages/spec/src only in logging.zod.ts, logging.test.ts, registry.ts and the semantic entry — no rehydration seam.
• Ratchet — RIGHT. build-schemas.ts:850-855 reads schema.properties one level per def, so the surface is top-level only; measured: 0 dotted rows in authorable-surface/*.json (lit 7384 rows) and 0 in authorable-defaults/*.json (lit 1170). Hence exactly one key moves: system/HttpDestinationConfig:timeout → timeout [RETIRED] + timeoutMs (surface +2/−1), :timeout = 30000 → :timeoutMs = 30000 (defaults +1/−1). authorable-surface.base.json is not in the diff and still carries system/HttpDestinationConfig:timeout at :5910; only --update-base writes it (build-schemas.ts:136-140). Check (b) registration is exact-row membership across all majors (registeredRetiredKeys()), satisfied.
• Pin tests — RIGHT. it( count 34 on main → 46 at head; the diff deletes exactly four lines, all replaced in place (config.timeout → timeoutMs, batch.flushInterval input + assertion → flushIntervalMs, buffer.flushInterval → flushIntervalMs); .skip|.only|.todo 0. New pins sit under their own top-level describe('logging duration keys → *Ms …') at :514; every pre-existing describe header in the file is a bare schema name, none makes a counted claim, so none was falsified.
• Generated docs — RIGHT. content/docs/references/system/logging.mdx is the generator's output: CI job Type Check · source gates (check-run 103714730003, completed: success, 11:12:22–11:15:13Z) runs check:authorable-surface then check:docs; check:spec-changes and check:upgrade-guide exit 0 locally on the head tree.

② Semver level

minor for @objectstack/spec is RIGHT, and the changeset text matches the diff. The launch-window guard lives at scripts/check-changeset-no-major.mjs (not scripts/pm/): its header states that breaking changes ship as minor until GA and that the carriers are the **BREAKING** banner plus the ADR-0087 disposition — the changeset carries both (feat(spec)! title, **BREAKING** line, adr-0087: registered logging-durations-unit-in-key); node scripts/check-changeset-no-major.mjs --base ae1b258889 exit 0 (level axis N/A offline; CI Check Changeset success). Precedent measured in packages/spec/CHANGELOG.md under ## 17.4.0: :1804 #15678 and :2764 #15679 are both feat(spec)! at a minor, and the landed siblings' changesets (17781-…, 17784-…) are "@objectstack/spec": minor. The corrections on #15939 (5652120294) are therefore right on both halves: patch was falsified by the shape ruling A itself names, and Clause-②: yes is the mechanical floor — the rename puts new authorable spellings on a published payload and check-widening-tells --declaration no refuses the diff (exit 4). The body's table, defaults, kit and migration diff match the source. No @objectstack/core (or any consumer) changeset is owed: outside packages/spec and the generated docs, flushInterval / initialDelay / HttpDestinationConfig / LoggingConfig occur 0 times in .ts/.tsx/.mjs/.md/.mdx/.json/.yml (node_modules/dist/.turbo excluded).

③ Boundary flags

• backoffMultiplier "noted, not filed" — right call. It is z.number().positive().default(2), a ratio; the census's own docblock (check-duration-unit-keys.ts:63) names backoffMultiplier among the count-shaped names a name-only rule would misfire on; its JSDoc names no unit, so it is not a feat(spec): refuse a duration key whose JSDoc names a unit its describe does not #17635 offender either; check:duration-unit-keys on the head tree: 211 keys, zero offenders, exit 0.
• check-widening-tells --declaration no → exit 4, 4 T1 — verified, and it is the [finding] check-widening-tells fires T1 on a retiredKey() tombstone line, so every ADR-0087 key retirement reads as a clause-2 widening for the one reason the accept set shrank #17955 inversion. Re-run on git diff ae1b258889 HEAD: the four tells are :326 :351 :371 :759, each the + <key>: retiredKey(…) line. T1 is "a new key on a Zod object schema"; the [finding] check-clause2-carriers T2 fires on a replaced string property value as "a new member of a closed set", and the C5 row it raises cannot be cleared except by declaring Clause-② yes on a change that does not widen #16943 replacement budget is per change block, one removed key line buys one added; each block here removes one key line and adds two (the *Ms key and the tombstone), so the surplus reported is the tombstone — exactly [finding] check-widening-tells fires T1 on a retiredKey() tombstone line, so every ADR-0087 key retirement reads as a clause-2 widening for the one reason the accept set shrank #17955's probe A/B accounting. --declaration yes → exit 0.
• New "Nested Shape" tables — generator behaving as pinned, not drift. packages/spec/scripts/nested-shape.test.ts:239 pins "does not open a table for a shape whose keys carry no describe text" and :253 "opens a table when the ONLY described key is a tombstone"; before this diff no key under batch / retry / buffer carried a describe, now each carries two (the *Ms describe and the [REMOVED] tombstone describe), so the three tables appear by the pinned rule.
• Collision with 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 / PR feat(spec)!: the five system/metrics.zod.ts durations carry their unit in the key name (#17783) #18007 — .gitattributes half MEASURED: :142 packages/spec/authorable-surface/** merge=os-regen, :144 packages/spec/authorable-defaults/** merge=os-regen; PR feat(spec)!: the five system/metrics.zod.ts durations carry their unit in the key name (#17783) #18007's file list touches both shards (authorable-surface/system.json +4/−2, authorable-defaults/system.json +2/−2) and registry.ts, so the textual collision is real. The server-side-rebuild half is ASSERTED, not established: its only source is AGENTS.md Multi-agent §11 ("the merge queue rebuilds server-side where no custom driver runs"); neither the PR nor this review measured the queue's behaviour, and I am not claiming to. The prescribed resolution (os-regen-merge.sh, commit the merge first, then gen:schema, never a hand-merge of a sorted-set shard) is the one §11 documents.

Cross-file staleness sweep (whole tree at head, including packages/spec, skills/, .claude/, examples/, docs/, content/): no prose, tombstone, migration entry, test comment or doc sentence is made false by this diff. The only hit on either old key outside the diff's own files is packages/spec/scripts/check-duration-unit-keys.ts:56, which uses flushInterval as a generic example of a duration-shaped name — still true. The def names outside the diff appear only in index listings that name no key (content/docs/references/index.mdx:339, content/docs/getting-started/quick-reference.mdx:100, packages/spec/PROTOCOL_MAP.md:127). packages/spec/liveness/ has 0 rows for either def (lit: 70 system/ rows).

Clause ②: node scripts/pm/check-clause2-carriers.mjs --pair 17999 → exit 0 (2026-09-13T11:52:55Z, "the clause-② declaration is readable in the fixed spelling and both carriers agree"). Independently, yes is correct on the mechanical floor: new authorable spellings on a published payload plus the exit-4 tells above.

Ablation: reproduced and it proves what it claims. From the committed state, under an EXIT INT TERM restore trap, all four retiredKey( calls replaced by a marker (occurrences 4 → 0, marker 0 → 4, blob 9768a4bb… → 4f10556b…): 4 failed / 42 passed, exactly the four "REFUSES the retired spelling" pins; restored with git checkout HEAD -- to blob 9768a4bb…, git status --porcelain empty. Four is the right number: each tombstone has exactly one refusal pin, the "accepts" pins feed only the new key and so cannot see a missing tombstone, and the describe pins read .description — so four is the whole population that ablation can reach. Ablation B (above) adds the def-discrimination proof the removal ablation alone does not give.

Readings I re-measured

All in /tmp/review-17999 at a5976809c2 unless stated; origin/main = b2c51cb881 after git fetch.

• 11:49:03Z worktree created; merge-base git merge-base origin/main HEAD = ae1b258889.
• 11:50:03Z git show origin/main:packages/spec/src/system/logging.zod.ts | grep -n -B6 -A2 -E '^\s+(flushInterval|initialDelay|timeout|backoffMultiplier):' — the four keys at :278 :293 :304 :672, JSDoc "in milliseconds", no .describe(; .describe( count in file 60 (main) → 72 (head); dark control 0.
• 11:50:03Z .strict() / strictObject in the file's code: none (4 comment hits only).
• 11:50:41Z / 11:52Z *Ms: / *Seconds: / *MS: / *Millis: key-position counts (grep -rhoE '^\s*[a-zA-Z_]+SUFFIX\??:') on head and git grep … origin/main on *.zod.ts and all *.ts; the 7 MS/Millis sites listed; flushIntervalMs / initialDelayMs / timeoutMs attested 1 / 5 / 31 on main; integrations.zod.ts:149 flushIntervalMs … default(1000).
• 11:52:02Z staleness sweep, grep -rn -w over .ts .tsx .mjs .js .md .mdx .json .yml .yaml excluding node_modules/dist/.turbo/.git, both old keys and both def names; 11:56Z packages/spec with no extension filter, liveness/, skills/, .claude/, examples/.
• 11:52:55Z node scripts/pm/check-clause2-carriers.mjs --pair 17999 → exit 0.
• 11:52:59Z git diff ae1b258889 HEAD | node scripts/pm/check-widening-tells.mjs --declaration no --diff - → exit 4, tells at :326 :351 :371 :759; --declaration yes → exit 0.
• 11:53:00Z pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/system/logging.test.ts → 46 passed.
• 11:53:57–59Z gen:migration-registry → registry.ts blob unchanged 4d7e7d2e99….
• 11:54:00Z check:duration-unit-keys → exit 0, 211 keys, zero offenders.
• 11:54:10Z node scripts/check-changeset-no-major.mjs --base ae1b258889 → exit 0.
• 11:55:08–12Z ablation A (4 failed / 42 passed, restore to 9768a4bb…); 11:55:14–17Z ablation B (2 failed / 44 passed, restore to 9768a4bb…). Both under a trap, both in my own worktree, working tree clean afterwards; nothing in the shared checkout touched.
• 11:55:20Z node scripts/check-adr-0087-registration.mjs --base ae1b258889 → exit 0.
• 11:56:07Z objectui pin grep in /home/user/objectstack-ai/objectui at HEAD 53ded82bf7a4… = .objectui-sha, 6409 tracked files: flushInterval 0, initialDelay 0, HttpDestinationConfig 0, LoggingConfig 0 (git grep -o -w … | wc -l); lit useState 2304, timeout 688 (word-bounded; the body's 702 is the unbounded count); dark vqzpx9 0.
• 11:56:19Z check:spec-changes → exit 0; check:upgrade-guide → exit 0. 11:57:38Z check:objectui-pin-citations → exit 0.
• Ratchet granularity: build-schemas.ts:850-855 read; 0 dotted rows in both shard sets (lit 7384 / 1170); authorable-surface.base.json:5910 unchanged and absent from the diff; .gitattributes:142,144; PR feat(spec)!: the five system/metrics.zod.ts durations carry their unit in the key name (#17783) #18007 file list via the API; lint.yml:4653-5114 for which job runs check:authorable-surface / check:docs; check-run 103714730003 completed: success.
• Governing text read from primary sources: ruling A (5635659224), the minor correction (5652120294), the lane/clause-② ruling (5652016540), the semantic+retired-row settlement (5652296795), [finding] check-widening-tells fires T1 on a retiredKey() tombstone line, so every ADR-0087 key retirement reads as a clause-2 widening for the one reason the accept set shrank #17955, spec: 4 duration key(s) in system/logging.zod.ts name their unit only in JSDoc — #15939 Ruling A remediation (4 of the 21-row delta) #17782 body and its triage comment.

Taken on the body's word (not re-measured): the dispatch-gates.mjs reconciliation (109 families / 107 green / 2 NOT MEASURED); the full-package run (476 files / 13533 tests — CI Test Core (1/6…6/6) and Test Core all completed: success stand in for it); "15 of 15 artifacts up to date" as a whole (I ran the registry regen, check:spec-changes, check:upgrade-guide, and rely on the Type Check · source gates job for check:authorable-surface / check:docs / check:api-surface); and the row-count table across the two os-regen-merge.sh syncs (its end state is verified by the byte-identical regeneration).

Implemented-by: branch claude/issue-17782-logging-duration-units
Reviewed-by: session_015c5G6TmpMKgnusmTpD7Ntt

VERDICT: PASS

Generated by Claude Code

Carriers cleared — provenance

needs:contract-review stripped from both carriers at 2026-09-13T12:03Z: this PR and card #17782, each read back after the write.

Full acceptance, including the disposition of every review flag, is on the card: #17782 comment 5653139945.

⚠️ One correction to the record, measured and not fixed here. The 272 key-position *Ms: count in this PR's ADR-0087 semantic entry and its registry.ts mirror does not reproduce. On this PR's own head the same corpus reads 282 (278 excluding this PR's own four; 275 at the merge-base; 105 restricted to *.zod.ts; dark control 0). It is a stale reading presented as current, in text that ships in the upgrade guide.

⇒ Not blocking and deliberately not pushed: the conclusion it supports is unaffected — Ms beats Seconds 282 to 77 here, and the ordering holds under every corpus definition tried — and the at-tier review measured this and still returned PASS. Recorded so a future reader who cannot reproduce 272 finds the number that does.

⚠️ Landing order — #18007 must not enqueue until this PR is on main. Both PRs write authorable-surface/system.json and authorable-defaults/system.json. Those are merge=os-regen in .gitattributes, so a local merge defers to the driver, but the merge queue rebuilds server-side where no driver runs, and an os-regen path can merge with exit 0 and zero conflict markers while silently dropping one side's rows — the rows are a sorted set, and a dropped line is silent. This PR is the first lander and is safe. The second lander owes an explicit os-regen-merge.sh + gen:schema + an exact-name re-assertion that both cards' rows survive.

⛔ No approval is given or implied. This is a governed surface: the clause-② review clears the queue gate, it is not a review approval, and this seat neither approves nor merges.

Generated by Claude Code