feat(spec)!: the fifteen system/ duration keys carry their unit in the key name [#14478 stack 4/6]

[os-sales]

Part of #14478
Stack card 4/6 — issue #15679, system/: the fifteen remaining duration keys carry their unit in the key name.

Stacked on card 3/6. Base branch is claude/issue-15678-kernel-duration-unit-in-key-name at 8f2b8f389f44862bfa7ca899a3cc4a580d5f0afb, not main. Review the diff against that branch.

Clause-②: yes — this changes contract accept/reject behaviour on the published spec surface.

What the gate says

Re-derived on this branch's own head before any edit, and again on the tip. The gate's verbatim verdict lines:

Before (base 8f2b8f389):

✗ check:duration-unit-keys — 22 offender(s) among 215 duration-shaped numeric key(s) in 805 source file(s) (6 declared `EpochMs` instant(s), 11 declared `externalVocabulary` mirror(s)):

After (tip 45a35896c):

✗ check:duration-unit-keys — 7 offender(s) among 215 duration-shaped numeric key(s) in 828 source file(s) (6 declared `EpochMs` instant(s), 11 declared `externalVocabulary` mirror(s)):

src/system/** goes 15 → 0 and the whole tree falls 22 → 7. The seven that remain are card 5/6's entire population and no src/system/ row is among them: ai/conversation.zod.ts duration, data/driver-nosql.zod.ts timeout, data/driver/memory.zod.ts autoSaveInterval, data/driver/turso.zod.ts timeout, integration/connector.zod.ts monitoringWindow and interval, ui/dashboard.zod.ts refreshInterval. Exit 1 is by design until card 6/6 declares the population empty.

The source-file count rises 805 → 828 because this PR adds exactly 23 files under packages/spec/src/migrations/entries/ (15 retired-key entries + 8 semantic entries). The 215 duration-shaped-key denominator is unchanged, as a pure rename must leave it.

The population was 15, not the 14 the card's table lists

The card's table subtracted card 1/6's intended exemptions and so omitted AccessControlConfig.maxAge. Card 1/6's dev demoted that key rather than marking it, and the gate on this base agrees: it reports 15 src/system/ rows, object-storage.zod.ts:261 maxAge among them.

FROM → TO

key	replacement	unit
CacheTier.ttl	ttlSeconds	seconds
CacheAvalanchePrevention.circuitBreaker.resetTimeout	resetTimeoutSeconds	seconds
CollaborationSessionConfig.idleTimeout	idleTimeoutMs	milliseconds
CollaborationSessionConfig.snapshot.interval	intervalMs	milliseconds
FailoverConfig.healthCheckInterval	healthCheckIntervalSeconds	seconds
MetricAggregationConfig.window.size	durationSeconds	seconds
ServiceLevelIndicator.window.size	durationSeconds	seconds
ServiceLevelObjective.period.duration	durationSeconds	seconds
AccessControlConfig.maxAge	maxAgeSeconds	seconds
StorageConnection.timeout	timeoutMs	milliseconds
RegistryUpstream.syncInterval	syncIntervalSeconds	seconds
RegistryUpstream.timeout	timeoutMs	milliseconds
RegistryConfig.cache.ttl	ttlSeconds	seconds
Span.duration	durationMs	milliseconds
QueueConfig.rateLimit.duration	durationMs	milliseconds

Every value, default and bound is unchanged. Every old spelling is a retiredKey() tombstone, so it fails tsc at the authoring site and fails the parse with the rename prescription rather than a bare unrecognized-key error. No prescription carries an internal issue id — those live only in // and /** */ comments, per check:doc-authoring.

The two size keys get an honest name, not the mechanical one

The gate prints sizeSeconds for MetricAggregationConfig.window.size and ServiceLevelIndicator.window.size. This PR renames both to durationSeconds instead, and says so in the prescription so the next author does not read the departure as a slip.

Two reasons, in order of weight:

1. size is byte/row-count vocabulary everywhere else in this spec. CacheTier.maxSize is megabytes, RegistryConfig.cache.maxSize is bytes, and MetricExportConfig.batch.size on the very same file is a record count. sizeSeconds would have kept the misleading half of the name and bolted a unit onto it — a reader still has to decide whether the number is a quantity of data measured per second or a length of time.
2. The parent key is already window, so the card's suggested windowSeconds would read window.windowSeconds.

durationSeconds names what the number is, and the file supplied its own precedent one schema down: ServiceLevelObjective.period.duration already called a period length a duration. After the rename all three read alike. A pin asserts the prescription contains the sentence explaining the choice.

The maxAge asymmetry is preserved, deliberately

AccessControlConfig.maxAge (bucket CORS) is renamed. Its twin shared/CorsConfig.maxAge (HTTP CORS) keeps its bare name under its externalVocabulary marker, and this PR does not touch it.

The demotion card 1/6 made is right on the schema's own evidence: every bucket-CORS standard the value is forwarded to already spells the unit — S3 MaxAgeSeconds, GCS maxAgeSeconds, Azure MaxAgeInSeconds — so marking that key would have exempted a deviation from the cited standard rather than a mirror of it. The Fetch response header the twin mirrors, Access-Control-Max-Age, genuinely carries no unit token.

⚠️ No gate can catch the twin being renamed along with this one — the marker exempts it either way. A pin test in object-storage.test.ts asserts CorsConfig.maxAge survives, and is the only guard.

Dispositions — eight semantic entries, no D2 conversion

Decided per key from the schema's actual producer rather than defaulted, and this card's answer is uniform. stack.zod.ts declares no cache, collaboration, disasterRecovery, metrics, objectStorage, registry, tracing or worker root — I read its collection list rather than assuming — and none of the twelve declaring defs is a registered metadata kind stored as a sys_metadata row, so the conversion chain has no seam that would see one. They are host configuration, call arguments and runtime-emitted measurements.

All fifteen are registered by exact key in RETIRED_KEYS_BY_MAJOR[18], nested spellings included (system/CacheAvalanchePrevention:circuitBreaker.resetTimeout, system/RegistryConfig:cache.ttl, and so on). The registry diff is 394 insertions, 0 deletions — no other card's tombstone was disturbed.

Readers moved in the same PR

Grepped by TYPE across every workspace package, then each hit read rather than rewritten. No package outside @objectstack/spec imports any of the twelve declaring types, so the readers are: the eight src/system/*.test.ts suites, the regenerated content/docs/references/system/*.mdx, and the authorable-surface/ + authorable-defaults/ ratchets. No liveness ledger, form, i18n bundle or skills/** page names any of these keys — checked, not assumed.

Keys deliberately left alone, each with a pin

FailoverConfig.dns.ttl (declared externalVocabulary mirror, RFC 1035 §4.1.3) · CacheAvalanchePrevention.lockout.lockTimeoutMs (already correct, and milliseconds where its resetTimeoutSeconds sibling is seconds) · MetricExportConfig.batch.size and QueueConfig.rateLimit.max (counts, not durations) · the error-budget burn-rate window and the OpenTelemetry exporter timeout (their describes name no unit, so both are outside the gate's population) · FileMetadata.size (bytes) · MetricDefinition.summary.maxAge and MetricExportConfig.interval (different keys that a name-based sweep would have caught). Pin tests assert each, so a later sweep cannot read this card as "every duration-shaped number on these files".

Verification

Everything below is a measurement; nothing is recalled.

run	result
pnpm --filter @objectstack/spec test	473 files / 12815 tests passed, 0 failed
pnpm --filter @objectstack/spec typecheck	green (tsc --noEmit, check:scripts-typecheck, check:test-typecheck — 54 files / 261 errors / 145 pinned signatures held, unchanged)
pnpm --filter @objectstack/spec check:generated	15 of 15 artifacts green
pnpm check:doc-authoring	exit 0 — 831 pinned sites across 231 files
pnpm check:adr-0087-registration	exit 0 — 5 declared-breaking changesets, each carrying a disposition
check:skill-examples	exit 0 — 257 prose examples type-check (@objectstack/client-react built first)
check:yaml-examples · check:variant-docs · check:empty-state	exit 0
check:exported-any · check:dual-source-exports · check:entry-nameability	exit 0
check:error-code-provenance · check:error-code-casing · check:nul-bytes	exit 0
check:doc-anchors · check:docs-single-h1 · check:docs-image-tag · check:docs-redirects · check:doc-frontmatter	exit 0
check:test-source-alias · check:cross-package-test-inputs · check:type-check-coverage	exit 0
check:declared-population-live · check:stack-collection-maps · check:spec-parsed-alias	exit 0
check:empty-changeset · check:changeset-no-major · check:published-files	exit 0
check:duration-unit-keys	exit 1 by design — the 7 rows above belong to card 5/6

Every exit code was captured before any pipe (cmd > log 2>&1; EXIT=$?), and every verdict quoted is the gate's own printed line. The full suite and check:generated were re-run on the final commit 45a35896c; git rev-parse --short HEAD at that run is the sha quoted above.

Reverse verification — two legs, predictions written before running

Both legs mutate packages/spec/src/system/cache.zod.ts, prove the mutation landed by counting the removed and injected markers on disk (never by an exit code), and restore via git checkout HEAD -- path verified by both a blob-hash match against the HEAD blob and an empty git diff HEAD. The script carries a trap ... EXIT INT TERM restore with absolute paths.

No dist rebuild leg is needed here, and the reason is checked rather than assumed: the gate walks packages/spec/src/ as source text (SRC_ROOT = join(pkgRoot, 'src')), and cache.test.ts imports ./cache.zod relatively. Neither subject resolves through the package's exports into dist/.

Leg A — revert the rename entirely (key back to ttl, tombstone removed).
Predicted: gate 7 → 8 with a new row naming src/system/cache.zod.ts ttl; cache.test.ts red on 2 CacheTier cases.
Observed: gate 8 offender(s), the new row src/system/cache.zod.ts:70 ttl — as predicted. Tests: 4 failures, not 2. ⚠️ My prediction under-counted: I forgot the two pre-existing CacheTierSchema fixtures this PR had already moved onto ttlSeconds, which the revert also breaks. Direction and the two named cases were right, the magnitude was wrong, and it is reported as measured rather than as predicted.

Leg B — keep the rename, delete only the tombstone.
Predicted: gate stays at 7 (it reads the key name, not the tombstone); cache.test.ts red on exactly 1 case — REFUSES the retired CacheTier.ttl — because ttl is then silently stripped instead of refused.
Observed: gate 7 offender(s) with no cache.zod.ts row, and exactly 1 failure, that case. Prediction met exactly.

Leg B is the load-bearing one: it shows the refusal pins catch a silent strip that the headline gate is blind to by construction, which is the failure mode the tombstones exist for.

Two inherited reds — not from this PR

check:llms-txt and check:quick-reference-counts are red on this branch with three findings:

packages/spec/llms.txt:94  [count] domain `shared` declares 13 schemas; src/shared/ holds 14
packages/spec/llms.txt:80  [count] heading declares 207 schemas; packages/spec/src/ holds 208
content/docs/getting-started/quick-reference.mdx:209  [total] section "Shared Protocol" declares "of 8 schemas" but content/docs/references/shared/ publishes 9 page(s)

Confirmed inherited by measurement, not by assertion: I ran both gates in a throwaway detached worktree at the base commit 8f2b8f389 and diffed the output against this head's, with repo paths normalised. Both are byte-identical. They trace to card 1/6 and are already fixed on its branch; they clear when the stack integrates in order. Repairing them here would be another card's diff.

Narrowing declared

Heavy CI does not run on a stacked PR (lint.yml and ci.yml both declare pull_request: branches: [main]), so the gate family above was run by hand. scripts/pm/dispatch-gates.mjs derives its change set three-dot against origin/main, which for a card stacked four deep is the whole stack's 268 paths and therefore the whole stack's ~180 families — the other cards' obligations, not this one's. I narrowed to the families that read this card's own diff surface, which is exactly seven directories: content/docs/references/system/, packages/spec/authorable-surface/, packages/spec/authorable-defaults/, packages/spec/src/migrations/ and its two entries/ subdirectories, packages/spec/src/system/, plus one .changeset/ file. The narrowing is a measurement of the diff, not a judgement about which gates matter.

Not touched

api/, kernel/, data/ui/ai/integration (card 5/6), the gate's declared population (card 6/6), any other PR's diff, and content/docs/releases/.

🤖 Generated with Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 5 package(s): @objectstack/cli, @objectstack/driver-memory, @objectstack/platform-objects, @objectstack/service-datasource, @objectstack/spec, touching 78 documentable anchor(s). ⚠️ 33 changed file(s) yielded no anchor (packages/spec/authorable-defaults/data.json, packages/spec/authorable-defaults/integration.json, packages/spec/authorable-defaults/system.json, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

14 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/connectors.mdx (via billing_api (literal, a string literal in fixture))
• content/docs/automation/flows.mdx (via durationMs (literal, a string literal on a changed line), timeoutMs (literal, a string literal in apply))
• content/docs/automation/hook-bodies.mdx (via timeoutMs (literal, a string literal in apply))
• content/docs/automation/jobs.mdx (via timeoutMs (literal, a string literal in apply))
• content/docs/automation/webhooks.mdx (via timeoutMs (literal, a string literal in apply))
• content/docs/deployment/environment-variables.mdx (via timeoutMs (literal, a string literal in apply))
• content/docs/getting-started/quick-reference.mdx (via DashboardSchema (symbol, a top-level const))
• content/docs/kernel/contracts/metadata-service.mdx (via sales_overview (literal, a string literal in fixture))
• content/docs/protocol/kernel/i18n-standard.mdx (via sales_overview (literal, a string literal in fixture))
• content/docs/protocol/objectui/actions.mdx (via sales_overview (literal, a string literal in fixture))
• content/docs/protocol/objectui/concept.mdx (via sales_overview (literal, a string literal in fixture))
• content/docs/protocol/objectui/index.mdx (via sales_overview (literal, a string literal in fixture))
• content/docs/ui/apps.mdx (via sales_overview (literal, a string literal in fixture))
• content/docs/ui/dashboards.mdx (via refreshIntervalSeconds (literal, a string literal in DashboardSchema; a string literal in apply; a string literal in dashboard; a string literal in sections; a string literal in summary), sales_overview (literal, a string literal in fixture))

⛔ 3 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v15.mdx (via DashboardSchema (symbol, a top-level const))
• content/docs/releases/v16.mdx (via timeoutMs (literal, a string literal in apply), os explain (command, read off packages/cli/src/commands/explain.ts))
• content/docs/releases/v17.mdx (via ConnectorTriggerSchema (symbol, a top-level const), durationMs (literal, a string literal on a changed line), timeoutMs (literal, a string literal in apply))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 33 changed file(s) yielded no anchor (packages/spec/authorable-defaults/data.json, packages/spec/authorable-defaults/integration.json, packages/spec/authorable-defaults/system.json, …) — pages documenting those are invisible to this run
• 13 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 61 of 219 client-bound route-ledger rows — the other 158 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 158: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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 74ddc0d6d090903deafdfa4df2abbe50a6f4301d → packageMentionDocs.

Which tree this was computed on

This run read content/docs from e7d832b7312f46f3332466e1576f94976a7d78f2 — the merge of head 9509c6d67b54c85fe545ebf495d2595f60c169c4 into base 74ddc0d6d090903deafdfa4df2abbe50a6f4301d, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older claude/issue-14478-duration-unit-in-key-name holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

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

node scripts/docs-audit/affected-docs.mjs --json 74ddc0d6d090903deafdfa4df2abbe50a6f4301d

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 74ddc0d6d090903deafdfa4df2abbe50a6f4301d → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-zhuang]

Contract review (clause ②) PASS at head 45a35896 — director seat, session_01TezFG8ZMrNH6n5VTNpPpdH, 2026-09-05T22:5xZ. Verdict (15 renames incl. maxAge, durationSeconds over the mechanical name, the CORS twin preserved with its pin, eight semantic entries and no D2, readers confined to spec): objectstack#15679 comment 5555234121. needs:contract-review removed from this PR and the card in the same stroke. Not governed on its own (0 of 51), but the stack lands in order under the domain:spec seat with stack 0 human-merged — no ready flip / auto-merge from this seat.

Implemented-by: session_01G4138K1EG7kQ81FNba5Kp4
Reviewed-by: session_01TezFG8ZMrNH6n5VTNpPpdH

---

Generated by Claude Code