docs(spec): name the second publisher a duration-unit marker changes

[os-bill]

Fixes #18687

Clause-②: no

What this is

Option A of the card — a docblock paragraph on the two .meta() exemption-marker readers in packages/spec/scripts/check-duration-unit-keys.ts. Option B (a changeset-gate criterion) is deliberately NOT implemented here: the card itself says that one has to be measured first, so this PR carries the measurement instead of a rule. Option C is untouched.

Comment-only. No declaration, schema, accept set or generator behaviour is touched — one file, 19 insertions, 1 deletion.

What the file already said, and what it did not

On the base tree the file already states, in assertion position, that a declared unit rides into the published JSON schema (:183-184, :389-390), and that the marker rides z.toJSONSchema verbatim so the reference page prints it (:176-179). All three are correct today and are left untouched; the new paragraph cross-references the channel rather than restating it.

What is new — and it is the whole of this card — is the half none of them states:

1. packages/spec/json-schema/ is published content: it is on this package's files[]. It also carries zero tracked files — it is a gitignored build artifact (.gitignore:63). Measured at 2767af8e83: 0 tracked paths under packages/spec/json-schema/, against 17 under packages/spec/api-surface/ by the same git ls-tree.
2. So the marker's arrival there is a change to published package content that has no diff of its own: there is no tracked byte of that directory for a review, a git diff or any diff-reading gate to see move.
3. So the first card that really marks a key owes its declaration to two publishers: the rendered reference page AND the published JSON Schema.

The paragraph is hung on DIMENSIONLESS_META_KEY, whose docblock is already the one that speaks for both markers ("It sits beside EXTERNAL_VOCABULARY_META_KEY in this reader on purpose. Both are declarations ON THE SCHEMA…"), plus a one-line pointer to it from EXTERNAL_VOCABULARY_META_KEY so a reader arriving at the first marker is routed to it.

One correction to the card's framing, measured

The card says such a change produces "not one line of git diff". Measured on this tree that is too strong, so the note is written to the measured shape instead:

• the marking edit is visible, and in packages/spec a marked *.zod.ts file is itself on files[] — so on a spec key that line is a published file in its own right;
• content/docs/references/** is tracked (224 generated pages) and both markers render into it ((unit per …) / (dimensionless — counts …)), so that publisher moves visibly as well.

The gap is the artifact, not the edit. Those two visible halves are precisely what makes the invisible third read as already accounted for — which is why the note is worth writing at all.

Direct evidence for the claim

After pnpm --filter @objectstack/spec build on this branch:

• packages/spec/json-schema/ materialises as 1532 generated JSON files, and git status --ignored=matching reports the directory as ignored — zero tracked.
• The marker values are in that output verbatim, e.g. "externalVocabulary": "HTTP Cache-Control \max-age` (RFC 9111 §5.2.2.1)"` — LIT control, the channel really does publish.
• A fabricated marker name reads 0 hits in the same output — DARK control.

Changeset: skip-changeset, measured rather than assumed

The card's subject is exactly "the reason for skip-changeset still reads correct", so this one is measured file by file rather than asserted.

Diff at 79e564be3a vs merge base 2767af8e83 — one file:

file	on packages/spec files[]?
packages/spec/scripts/check-duration-unit-keys.ts	NO — matches none of the 11 entries (dist, json-schema, liveness, prompts, llms.txt, README.md, src/**/*.zod.ts, CHANGELOG.md, api-surface, api-surface-declarations, spec-changes.json); package is not private

Second, empirical leg against a real build: the sentence this PR adds appears 0 times across dist/, json-schema/, api-surface/, liveness/ and prompts/; the positive control — a genuinely published string — appears 18 times in dist/ and 8 times in json-schema/. Zero files on files[] moved, so skip-changeset holds, and it holds by measurement, not by the habit this card is about.

The measurement option B owes (readings only — no rule is landed)

Criterion measured: a diff whose ADDED lines introduce a .meta({ MARKER }) key position requires a non-skip-changeset. A false positive is a commit the criterion fires on that touches no file on a files[].

Window, stated: every non-merge commit reachable from origin/main at 2767af8e83 — 13175 commits; hits span 2026-01-26 … 2026-09-17. (Wider than the brief's "last N commits touching packages/spec", and repo-wide rather than spec-only, since the criterion is repo-wide.) Candidates come from git log --no-merges -G; a candidate is kept only when an added line matches, which is what separates a marking from a removal.

Broad reading — any .meta({:

reading	count
candidates from -G	43
criterion FIRES (an added line, not just a removal)	41
false positives, naive files[] membership	10 of 41 = 24.4%
false positives, src-reaches-dist tarball reading	8 of 41 = 19.5%
fired and carried no .changeset/*.md	11
DARK control — a fabricated marker name	0

7 of the 10 naive false positives have their added .meta({ under a scripts/ path — the class the card predicts must exist. They include 8ca7aafc45, which edits this gate's own self-test fixtures, and three commits editing scripts/pm/check-widening-tells.mjs.

Narrow reading — an added line matching .meta({ externalVocabulary or .meta({ dimensionless. Six commits fire in all of history:

commit	fires on	verdict
17965dfd7e	packages/spec/scripts/lib/schema-section.ts and its test	false positive
8ca7aafc45	this gate's own self-test fixtures	false positive
484484041a	this gate's own self-test fixtures	false positive
7e6337007f	packages/spec/CHANGELOG.md quoting a marker, in the release commit	fires, but nothing was marked
e9fcd6bbd4	the commit that landed the two exemptions	true positive — carried a changeset
c049e74679	two real markings under src/	true positive — carried a changeset

So the narrow criterion's false-positive rate is 3 of 6 (50%) under the naive reading, or 4 of 6 if the release commit that marks nothing is counted; and both of its true positives already carried a changeset without any rule forcing them to. These are readings for the maintainer's decision on option B — no gate, check-*.mjs or CI criterion is changed by this PR.

Verification

• check-duration-unit-keys --self-test — green before (unmodified file at 2767af8e83) and after: 104 cases across 13 batteries both times, every battery at or above its pinned floor.
• pnpm --filter @objectstack/spec build :: exit 0 (under the shared verify lock, 127s).
• pnpm --filter @objectstack/spec check:docs :: exit 0 — "224 generated files in sync with packages/spec", so zero reference pages move.
• Derived gate sweep: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack yields 53 commands; all 53 were run with exit codes captured before any pipe. 51 exit 0. Two exit 3 — check:dual-build-cjs-loads and check:lean-entry-closure — which is the code those gates use for PREREQUISITE NOT MET: both read built output of the whole package farm, which a spec-only build does not produce. Recorded as NOT MEASURED, not as green; a comment in scripts/ reaches no dist, and CI builds the farm. --ran reconciliation: 53 derived, 51 run, 2 NOT-MEASURED derived from the recorded exit 3, 0 unrun.
• Repo-wide pnpm lint (eslint . --no-inline-config) at 79e564be3a: 6858 files in eslint's own surveyed population, 0 errors, 0 warnings, exit 0. Not narrowed — the whole union was run after the final commit.
• pnpm check:nul-bytes :: exit 0, plus a direct control-character scan of the changed file: no hits.

Acceptance notes

• The card's "no git diff at all" framing is corrected above rather than repeated; the file now states the measured shape. Reported to the dispatching seat rather than filed.
• packages/spec/json-schema.manifest/ and packages/spec/authorable-surface/ (14 tracked files each) are projections of json-schema/ that record def keys and authorable keys, not .meta() markers — measured: zero occurrences of either marker name in both directories. So neither tracked projection gives the published JSON Schema a diff-visible shadow. Observation only, not filed.
• Nothing else in scope was found to file under the three filing classes.

---

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.

What this run could not see

• 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 — 0 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 37ca54a11fe55f50025900e1e6add92dfa41c153 → packageMentionDocs.