From 79e564be3a93bec35321197c07d627e83e7eaf4b Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 18 Sep 2026 11:08:03 +0000 Subject: [PATCH] docs(spec): name the second publisher a duration-unit marker changes The two exemption markers this gate reads ride z.toJSONSchema into packages/spec/json-schema/, which this package's files[] ships and which carries zero tracked files -- a gitignored build artifact, so no diff can show that it moved. The file already states that a marker reaches the published JSON schema; what it did not state is that the published artifact has no tracked representation, so the declaration a marking owes covers two publishers: the rendered reference page and the published JSON Schema. Comment-only; no declaration, schema or accept set is touched. Claude-Session: https://claude.ai/code/session_01JbZnqu8bt6YqfJsr9vaFb3 Co-authored-by: Claude --- .../spec/scripts/check-duration-unit-keys.ts | 20 ++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/packages/spec/scripts/check-duration-unit-keys.ts b/packages/spec/scripts/check-duration-unit-keys.ts index 668beea68a8..368db88c988 100644 --- a/packages/spec/scripts/check-duration-unit-keys.ts +++ b/packages/spec/scripts/check-duration-unit-keys.ts @@ -409,7 +409,8 @@ const DURATION_ROOT_MODULE = 'src/shared/duration.zod.ts'; * The `.meta()` key that declares exemption class (ii). A key carrying it * mirrors a name fixed by an external standard, so the RENAME is waived — never * the contradiction check, and never the requirement that the describe still - * state the unit. + * state the unit. What marking a key owes the PUBLISHED surfaces is stated once + * for both markers, on {@link DIMENSIONLESS_META_KEY} below. */ const EXTERNAL_VOCABULARY_META_KEY = 'externalVocabulary'; @@ -427,6 +428,23 @@ const EXTERNAL_VOCABULARY_META_KEY = 'externalVocabulary'; * lying: a dimensionless key whose NAME carries a unit token still fails * `name-unit-contradicts-prose`, because "this number counts events" and "this * number is a span of milliseconds" cannot both be true of one key. + * + * ⚠️ MARKING A KEY EDITS A PUBLISHED ARTIFACT THAT HAS NO TRACKED BYTES, so a + * marking declares itself to TWO publishers rather than one. Either marker + * reaches `packages/spec/json-schema/` down the `z.toJSONSchema` channel + * exemption class 2 names above, and this package's `files[]` ships that + * directory — but it is a gitignored build artifact carrying ZERO tracked files + * (measured on this repo at `2767af8e83`: 0 tracked paths under `json-schema/`, + * against 17 under `api-surface/` by the same `git ls-tree`), so no diff can + * show that it moved. The gap is the ARTIFACT, not the edit: the marking line + * is visible, and this package's `files[]` ships its `.zod.ts` sources too, so + * on a spec key that line is a published file in its own right; the rendered + * note moves visibly as well, because `content/docs/references/**` is tracked. + * ⛔ Those visible halves are the trap — they make the publishing story read as + * fully told, while "nothing else published moved" is not a reading about + * `json-schema/` at all, which cannot move in a diff. So the first card that + * really marks a key declares BOTH publishers: the rendered reference page AND + * the published JSON Schema (#18687). */ const DIMENSIONLESS_META_KEY = 'dimensionless';