Skip to content

docs(spec): record why element:text's content is not a PageTranslation.components key - #15216

Merged
os-justin merged 2 commits into
mainfrom
claude/issue-14412-content-exclusion-sentence
Sep 4, 2026
Merged

os-justin merged 2 commits into
mainfrom
claude/issue-14412-content-exclusion-sentence

Conversation

@os-justin

Copy link
Copy Markdown
Collaborator

Fixes #14412

Executes the maintainer ruling recorded on the card by the director seat (comment 5518061415, 2026-09-02, verbatim reply 「同意」 to decision batch #13, item 3). Operative sentences, verbatim:

element:text's content does not join PageTranslation.components. … The schema comment in packages/spec/src/system/translation.zod.ts gains the sentence that was missing: content is excluded on purpose, beside help and subtitle, citing #10926. Option B (add the key and a precedence rule for the two routes) is not taken.

Execution: domain:spec lane, S (one comment sentence; no zod change; no changeset beyond what the changeset-presence gate demands). Clause-② no.

The premise, re-verified at the branch point before editing

The card is a census, so the census was re-measured against origin/main at 919beca rather than taken from the body. All four faces hold; one line number in the dispatch had drifted and was relocated by content.

Claim Verified Where
The per-component face is five keys — title description label placeholder emptyText yes translation.zod.ts:927-931
Its comment names two deliberate exclusions, help and subtitle, each with a reason yes :878-888
The submitLabel retirement note states the precedent yes :867-876
content is neither named nor excluded on this face yes the only four content hits in the file are at :486 :511 :519 :550, all prose in the retired-key conversion region
element:text declares content: I18nLabelSchema yes ui/component.zod.ts:1819, inside ElementTextPropsSchema opened at :1802 — the dispatch cited :1784, which had drifted

So the card's own second option was the live one: what is missing is the sentence, not the key. premise_still_valid: true.

The change

One bullet added to the exclusion list, in the register of its two neighbours, and the list's lead-in updated from two to three so the count stays true:

The bullet also records, in one sentence, the thing the card raised that the earlier rulings had not weighed — that inline locale maps are invisible to os i18n extract and check:i18n-coverage — and points it at #14749, where the director seat carried it. That question is domain:cli and is deliberately untouched here.

This satisfies the third facet of the card's own analysis: an author who looks for a bundle key for the one string element:text renders now finds a decision with a reason, not an absence that reads like an oversight.

Comment only. No key was added to the face, no describe() changed, no resolver touched — translatePage resolves exactly what it resolved before, and bundles, extractor output and existing page definitions are unaffected.

Why a changeset rather than the skip-changeset label

The ruling defers this to the presence gate, and the gate has no path filter — it fails any PR that adds no changeset and carries no label. The label is reserved for a diff that publishes nothing from any released package, and this diff does publish, measured two ways:

  • packages/spec is not private (@objectstack/spec@17.2.0) and its files array includes src/**/*.zod.ts. npm pack --dry-run --json lists src/system/translation.zod.ts among the 2087 files in the tarball, so the edited comment ships to consumers verbatim.
  • The comment text also lands in the built bundle — dist/browser/index.js, dist/browser/index.mjs, dist/browser/system/index.js and others (36 dist files carry it; 0 of them are .d.ts, so the type surface is unchanged).

Hence a patch changeset for @objectstack/spec. Not breaking, so no ADR-0087 disposition marker is required.

Gates

Derived from the actual changed paths after the last commit with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, which read the change set from the merge base itself (2 paths, committed 2 / working tree 0 / untracked 0) and returned 47 families. All results below are pinned to head 3bf408ba, with a clean working tree, and every exit code was captured before any pipe.

Green (exit 0):

  • pnpm --filter @objectstack/spec build — check-dts-emitted: 34/34 declared declaration file(s) present
  • pnpm --filter @objectstack/spec check:generated — ✓ All 15 generated artifacts are up to date. Nothing regenerated: this JSDoc block is not copied into content/docs/references/, so check:docs needed no --fix and the PR carries no generated follower.
  • pnpm --filter @objectstack/spec typecheck — including check:scripts-typecheck and check:test-typecheck (54 file(s) / 261 error(s) / 145 pinned signature(s) held, unchanged)
  • pnpm --filter @objectstack/spec test — Test Files 469 passed (469), Tests 12542 passed (12542)
  • The eight spec source audits check:generated deliberately does not run: check:browser-reachable-entries, check:dual-source-exports, check:empty-state, check:entry-nameability, check:exported-any, check:llms-txt, check:variant-docs, check:yaml-examples
  • pnpm check:doc-authoring, check:nul-bytes, check:changeset-gate-self-tests, check:cross-package-test-inputs, check:logger-receiver-detach, check:merge-driver, check:objectui-changeset, check:page-declaration-shape, check:pm-half-states, check:published-files, check:slot-lookup, check:spec-parsed-alias, check:test-source-alias, check:type-source-resolution
  • pnpm --filter @objectstack/lint check:doc-formula-expressions
  • node scripts/ gates and their self-tests: check-adr-0087-registration, check-changeset-no-major, check-ci-filter-parity, check-comment-mask-adoption, check-dev-prereqs, check-empty-changeset, check-keyed-text-bounds, check-plugin-teardown-shape (47 cases pass), check-system-context-census, check-undeclared-dep-imports, scripts/docs-audit/check-affected-docs, scripts/docs-audit/check-drift-comment, scripts/pm/release-rehearsal-clone --self-test
  • pnpm lint — the repo-wide eslint . --no-inline-config, run whole rather than narrowed, exit 0

Not measured, declared rather than counted as passes:

  • pnpm check:dual-build-cjs-loads exits 3 — Run pnpm build first. ⛔ This is NOT a pass: nothing was measured. Its prerequisite is a built tree for 76 packages, which no comment-only diff can affect and which CI builds anyway.

Two gates needed a prerequisite met before they said anything, and both were met and re-run rather than reported from their first reading: check:doc-formula-expressions exited 3 twice (@objectstack/formula, then @objectstack/lint, unbuilt) and passed after both were built; check-plugin-teardown-shape --self-test could not reach its pinned fixture commit in this shallow checkout, and passed after that one commit was fetched.

Scope

Comment plus changeset, nothing else — git diff --name-only against the merge base is exactly packages/spec/src/system/translation.zod.ts and .changeset/spec-text-content-exclusion-recorded.md, matching the claimed file surface with no deviation. Clause-② no: no accept/reject behaviour changes and no public surface widens. The extraction and coverage visibility of inline I18nLabel maps stays out of scope here; it is #14749's, in the domain:cli lane, and is referenced but not addressed by this PR.


🤖 Generated with Claude Code

https://claude.ai/code/session_01H2oQebDDxYKfWZusyd8GXk


Generated by Claude Code

…ponent translation face

`PageTranslation.components` names its deliberate exclusions with reasons —
`help` because no component declares it, `subtitle` because `page:header` is
addressed by page name. `content` was neither named nor excluded, so an author
looking for a bundle key for the one string `element:text` renders found an
absence that reads exactly like an oversight.

It is not one. `element:text` declares `content: I18nLabelSchema`
(`ui/component.zod.ts`), localizable at its own authoring site, so adding it to
this face would be the face widening the `submitLabel` retirement declined for
the identical shape (#10926). Written down beside the other two, citing that
precedent, and pointing the separate extraction/coverage question at #14749.

Comment only: no schema key, no `describe()`, no resolver change.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2oQebDDxYKfWZusyd8GXk
`@objectstack/spec` publishes `src/**/*.zod.ts` in its npm `files`, so the
edited comment ships in the tarball verbatim (and the text also lands in
`dist/browser/**`). The diff therefore publishes from a released package, which
is exactly what `skip-changeset` is NOT for.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2oQebDDxYKfWZusyd8GXk
@github-actions github-actions Bot added the size/s label Sep 4, 2026
@github-actions

github-actions Bot commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see
  • the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 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 — 128 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 50d6c924bb7cacbc934e8386d8523f1be40cc040 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 4671943a6c7816a85120819a6912f892420083c6 — the merge of head 3bf408ba6eed46fa6bed61dd6d4a40225f76535b into base 50d6c924bb7cacbc934e8386d8523f1be40cc040, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main 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 4671943a6c7816a85120819a6912f892420083c6 && git checkout 4671943a6c7816a85120819a6912f892420083c6
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 50d6c924bb7cacbc934e8386d8523f1be40cc040 3bf408ba6eed46fa6bed61dd6d4a40225f76535b && git checkout -B drift-repro 50d6c924bb7cacbc934e8386d8523f1be40cc040 && git merge --no-ff 3bf408ba6eed46fa6bed61dd6d4a40225f76535b

node scripts/docs-audit/affected-docs.mjs --json 50d6c924bb7cacbc934e8386d8523f1be40cc040

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

@github-actions github-actions Bot added documentation Improvements or additions to documentation protocol:system tooling labels Sep 4, 2026
@os-justin
os-justin marked this pull request as ready for review September 4, 2026 06:40
@os-justin
os-justin enabled auto-merge September 4, 2026 06:40
@os-justin
os-justin added this pull request to the merge queue Sep 4, 2026
Merged via the queue into main with commit 1c6f7b4 Sep 4, 2026
36 checks passed
@os-justin
os-justin deleted the claude/issue-14412-content-exclusion-sentence branch September 4, 2026 07:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation protocol:system size/s tooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

PageTranslation.components has no key for element:text's content — the one string that element renders cannot be addressed by a bundle

2 participants