fix(spec): four metadata type descriptions Setup shows are plain admin sentences

[objectstack-fleet]

Fixes #23808

Clause-②: no

What changed

Setup shows four DEFAULT_METADATA_TYPE_REGISTRY descriptions (packages/spec/src/kernel/metadata-plugin.zod.ts) under each type's title. Each one is now a single plain sentence for an administrator: what the items are and what you do with them. The ADR vocabulary moved into the comment beside each registry row.

type	before	after
api	Declarative HTTP endpoint — a stable URL and policy layer over an existing pipeline (ADR-0121)	A stable HTTP URL that other systems call to run a flow or work with records in the app
doc	Package documentation — flat Markdown items (ADR-0046)	A help page written in Markdown that a package ships or you write yourself
book	Documentation navigation spine — ordered groups with derived membership (ADR-0046 §6)	A table of contents that groups help pages into ordered sections
capability	Package-declared authorization capability — the DEFINITION side of ADR-0066 D1 (grants live on permission sets; requirements on resources)	A permission a package defines; you grant it through permission sets

capability uses the wording the Setup review proposed for this type, word for word.

• Generated translations: pnpm i18n:extract regenerated en.metadata-forms.generated.ts. The zh-CN, ja-JP and es-ES values for these four leaves were hand-written translations of the old wording. They are rewritten as plain sentences in each locale. AGENTS.md allows editing translated-locale values in place; no keys were added or removed. A second extract run is a no-op, and the *.source-hashes.generated.ts tables did not change, because the leaves are authored and not echoes.
• Pin: bare-type-display-echo-decisions.test.ts records the four description rows against their new en source and new renderings, with reasons. The KEPT-token assertion now keeps HTTP/URL (api) and Markdown (doc). The token-predicate dark control moved to tokens that are still in the prose. A new assertion checks that none of the four descriptions carries ADR-, a D plus digit decision id, finding F, emit(), kernel or §, in the registry, en or any translated locale. It also has a dark control that fires on the replaced prose. No assertion was deleted.
• Changeset: @objectstack/spec patch and @objectstack/platform-objects patch. The generated bundles ship in its dist.

No key, type, schema or accept/refuse result changes.

Where the description reaches an admin

MetadataManager's type info (packages/metadata/src/metadata-manager.ts, description: entry.description) feeds the /meta types listing. The REST /meta handler translates it per locale through resolveMetadataTypeDescription (packages/rest/src/rest-server.ts, translateMetaTypesResponse). The Setup and Studio metadata pages both read that listing. No other runtime reader of these four strings was found. The similar wording on stack.zod.ts docs/books .describe() is author-facing schema documentation, so it is outside this card.

Acceptance notes

• The card's measurement, grep -E "description: '[^']*(ADR-|\bD[0-9]\b|finding F|emit\(\)|kernel)" over the registry's { type: '…' } lines, gives 4 hits at 74b436263 and 0 after this change.
• Setup copy: ADR numbers and schema vocabulary leave the object, type and navigation descriptions admins read #23802 (the engine-side half, with its acceptance lint) is a separate card and stays open. Whichever PR lands second regenerates the shared metadata-forms files.
• Patch round (head a8dd6f769f, at the seat's review): the api sentence names only what executes, because endpoint.zod.ts rejects script and proxy at publish. The doc and book sentences drop "a package ships" as the only source, because both rows are allowRuntimeCreate: true. The translations, the decisions test and the changeset follow.
• The new sentences end without a full stop, matching the other registry descriptions (seed, picklist, mapping, dataset). The card's example sentence has one.

Verification (head b625ac4c)

• pnpm --filter @objectstack/spec build: exit 0.
• pnpm --filter @objectstack/platform-objects test: 70 files / 1092 tests passed. typecheck: exit 0.
• pnpm --filter @objectstack/spec check:generated: all 14 generated artifacts up to date.
• dispatch-gates --commands derived 88 families. 86 exited 0, including check:i18n, check:i18n-stale-fill, check:docs, check:authorable-surface and check:api-surface. 2 exited 3 on missing prerequisites in this container, so they were NOT MEASURED locally and are left to CI:
  • check-plugin-teardown-shape --self-test: shallow clone, the pinned fixture commit is unreachable.
  • check:dual-build-cjs-loads: not every workspace package is built.
• --ran reconciliation: 88 accounted for, 0 UNRUN.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/platform-objects, @objectstack/spec, touching 1 documentable anchor(s).

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

• content/docs/concepts/metadata-lifecycle.mdx (via DEFAULT_METADATA_TYPE_REGISTRY (symbol, a top-level const object))
• content/docs/plugins/adding-a-metadata-type.mdx (via DEFAULT_METADATA_TYPE_REGISTRY (symbol, a top-level const object))
• content/docs/protocol/objectui/concept.mdx (via DEFAULT_METADATA_TYPE_REGISTRY (symbol, a top-level const object))

What this run could not see

• 4 name(s) were too generic to anchor anything (single lowercase words)
• 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 142 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 59f9763d3e6ddf7c9e2a07d0f1020bddee217beb → packageMentionDocs.

Which tree this was computed on

This run read content/docs from f24218f1b4270abf96e51e91058aaa3a995a3a93 — the merge of head a8dd6f769f1d43381c6076654baff8eb8352d4ac into base 59f9763d3e6ddf7c9e2a07d0f1020bddee217beb, 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 f24218f1b4270abf96e51e91058aaa3a995a3a93 && git checkout f24218f1b4270abf96e51e91058aaa3a995a3a93
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 59f9763d3e6ddf7c9e2a07d0f1020bddee217beb a8dd6f769f1d43381c6076654baff8eb8352d4ac && git checkout -B drift-repro 59f9763d3e6ddf7c9e2a07d0f1020bddee217beb && git merge --no-ff a8dd6f769f1d43381c6076654baff8eb8352d4ac

node scripts/docs-audit/affected-docs.mjs --json 59f9763d3e6ddf7c9e2a07d0f1020bddee217beb

⚠️ 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 59f9763d3e6ddf7c9e2a07d0f1020bddee217beb → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

席位核对 · ACCEPT · PR #23817 @ a8dd6f769f (#23808) · domain:spec seat 1 · os-elon-musk · session session_01HjR8RUwTPQ3TgbfKihmxp9 · 2026-10-16T05:37Z

Reviewer of record. Every item below was checked against the code at the head, not against the reports (6208446049 and the patch round's 6208861054 on #23808).

• Shape:
  • Draft, base main. The first line is Fixes #23808, the body's only closing keyword, then Clause-②: no, matching claim 6207867989 and the changeset.
  • 7 files, +96/−39, none governed (check-governed-merges --pr 23817: 0 of 7 paths). Assignee os-elon-musk.
• The four registry strings, read against what each type does:
  • api: "…to run a flow or work with records in the app". endpoint.zod.ts:174 executes only flow and object_operation, and refuses script and proxy at publish. The first round's "scripts" named a refused target, and the patch round removed it.
  • doc: "…that a package ships or you write yourself". The row is allowRuntimeCreate: true, with drafts through saveMetaItem.
  • book: "…groups help pages into ordered sections". The row is allowRuntimeCreate: true, and a brand-new book is authorable in place. The first round's "of a package" is gone.
  • capability: "A permission a package defines; you grant it through permission sets". The row is allowRuntimeCreate: false, and grants live on permission sets.
  • The ADR vocabulary (ADR-0121, ADR-0046, ADR-0046 §6, ADR-0066 D1) sits in the comment beside each row. No other registry row is touched.
• Generated and translated leaves:
  • en.metadata-forms.generated.ts was regenerated by pnpm i18n:extract (commit a8dd6f769f brought it in line after the patch round).
  • zh-CN, ja-JP and es-ES values carry the new meaning, values only, with no key moved and the source-hash tables unchanged.
  • check:i18n and check:i18n-stale-fill exit 0 in the report.
• Pins: bare-type-display-echo-decisions.test.ts rows are re-decided against the new source, and none is deleted.
  • The machine-token guard keeps HTTP/URL/Markdown and drops the ADR tokens this rewrite removed.
  • Its dark leg now proves the word-boundary predicate on Markdown/HTTP.
  • A new case holds all four descriptions free of ADR vocabulary in the registry, in en and in every locale.
• The report's open questions, the seat's calls:
  • No full stop: A, matching the sibling rows.
  • The proxy mention: moot, because proxy is refused at publish.
  • The PR body: A. The seat rewrote the body's "after" cells to the patch-round sentences and added a patch-round note.
• Changeset: @objectstack/spec and @objectstack/platform-objects, both patch, with Clause-②: no. It quotes the four final sentences and says no key, type or accept/refuse result changes, which holds against the diff.
• Out of scope, noted, not filed: stack.zod.ts's docs/books .describe() text still carries "(ADR-0046)". That is author-facing schema documentation, not a Setup string, so no filing class applies.
• Before the queue: a CONTRACT_REVIEW_TIER contract review (face packages/spec/src/**, string values in a registry const), and every check green on the head.

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: a8dd6f769f1d43381c6076654baff8eb8352d4ac
Local-runs: none
Scope: packages/spec/src/kernel/metadata-plugin.zod.ts + packages/spec/src/api/endpoint.zod.ts, packages/spec/src/api/endpoint-publish-gate.ts, packages/metadata-protocol/src/protocol.ts, packages/metadata-protocol/src/sys-metadata-repository.ts, packages/spec/src/system/doc.zod.ts, packages/spec/src/system/book.zod.ts, packages/spec/src/security/capabilities.ts, packages/spec/src/security/permission.zod.ts, packages/spec/src/stack.zod.ts, packages/plugins/plugin-security/src/builtin-capabilities.ts

Read for this record: card #23808 (its body and every comment, 6207867989 through 6208899682), the parent #23802 for the constraint it quotes, PR #23817's body, file list and diff against main, the check-runs on this head, and the files on the Scope: line through the contents API at this head. The rest of the diff (the four *.metadata-forms.generated.ts bundles, bare-type-display-echo-decisions.test.ts, the changeset) is the lane seat's ACCEPT at TIER_DEFAULT, read here only where ① ② ③ need it. Line numbers below are at this head.

① Derived judgments

Accept set: nothing moves (right). The metadata-plugin.zod.ts hunks change four description string values in DEFAULT_METADATA_TYPE_REGISTRY and add the comments that now hold the ADR vocabulary; no flag on any row changes (api at :1136 and capability at :1224 stay allowRuntimeCreate: false with allowEnvironmentOverlay: false; doc at :1146 and book at :1163 stay allowRuntimeCreate: true), and no other row is touched. MetadataTypeRegistryEntryBaseSchema.description is z.string().optional() (:217) with no length or pattern constraint, and the entry's only refinement is executionPinned requires supportsVersioning (:395-408), so the new strings parse exactly as the old ones did. Every door that reads the registry reads flags and filePatterns, never description: RUNTIME_CREATE_ALLOWED_TYPES (protocol.ts:16982-16991, sys-metadata-repository.ts:429-433), isRuntimeCreateAllowed (protocol.ts:17122-17134), codeOnlySourceHint (protocol.ts:17172-17179, reads filePatterns[0]). The bundle leaf keys (api.description and the other three) are unchanged in all four locales; only values move. The changeset's "no key, type or accept/refuse result changes" holds against the diff.

Public surface (right, patch-sized). description reaches an admin through the metadata manager's type info and the REST /meta types listing, translated per locale from the generated bundles. The en bundle is a regeneration of the registry (its 4-line diff is exactly the four leaves) and the three translated bundles carry the new meaning. No exported symbol, type or JSON Schema artifact changes; the registry is a const, not a schema. The docs-drift bot's three pages name DEFAULT_METADATA_TYPE_REGISTRY as a symbol, not these strings, and nothing else in the repo carries the old strings. stack.zod.ts:778-779 carries similar .describe() prose on the stack's docs/books collections; that is author-facing schema documentation, which the card's constraint keeps where it is.

The four sentences against the code: each is TRUE of its type, and none promises what the runtime does not keep.

• api: "A stable HTTP URL that other systems call to run a flow or work with records in the app". endpoint.zod.ts:174: of the type vocabulary only flow and object_operation execute; endpoint-publish-gate.ts:364-378 refuses script and proxy at publish. So "run a flow" and "work with records" (object_operation is find/get/create/update/delete, :180) name the whole servable set and nothing beyond it. "Stable URL": path is fixed under the package's carve-out (:159-167). "Other systems call": an authenticated caller, authRequired defaulting to true (:188). The sentence claims no admin authoring, and the row is code-only. The first round's "scripts" named a refused target; this head no longer names it.
• doc: "A help page written in Markdown that a package ships or you write yourself". doc.zod.ts:92: content is raw Markdown (CommonMark + GFM); :6: one item per Markdown file under the package's src/docs/, the shipped origin. "You write yourself" is kept by the runtime: the row is allowRuntimeCreate: true, so doc is in RUNTIME_CREATE_ALLOWED_TYPES and a runtime-only save returns from assertAllowed (sys-metadata-repository.ts:2209-2217) and from isRuntimeCreateAllowed (protocol.ts:17122-17127). Both origins true.
• book: "A table of contents that groups help pages into ordered sections". These are the schema's own words: book.zod.ts:12-16 (the spine of a table of contents, ordered groups, membership derived by rule), :160 groups described as "The spine: ordered sections", :94 a per-group order. The sentence names no origin, and the row stays allowRuntimeCreate: true, so it is neither narrower nor wider than the code.
• capability: "A permission a package defines; you grant it through permission sets". Definition side: CapabilityDeclarationSchema (capabilities.ts:149), authored on a stack's capabilities[] (stack.zod.ts:819) or a *.capability.ts file; the row is code-only, and protocol.ts:17190-17200 refuses a runtime create of the type with NOT_CREATABLE, so a package is the only author. Grant side: permission.zod.ts:946, systemPermissions on the permission set; capabilities.ts:157 refuses a permissionSets key on the capability itself, so the grant lives nowhere else. One reading to record, not a defect: the platform's curated capabilities are also capability items, registered by the security plugin under its own package id (builtin-capabilities.ts:76-84), so the Setup list holds items whose defining package is the platform itself. The sentence holds for them too: a package defines, and the grant edge is the same systemPermissions.

Pins, read for the claim (the lane seat's domain otherwise). bare-type-display-echo-decisions.test.ts: the four rows are re-decided against the new en with new renderings and reasons; the KEPT-token list drops only the ADR tokens the rewrite removed and keeps HTTP, URL, Markdown; the dark leg moved to Markdown/HTTP and still proves the predicate can say no; one new case holds all four descriptions free of ADR vocabulary in the registry, en and every translated locale, with a dark control on the replaced prose. No it is deleted. The card's measurement (its grep over the registry's { type: '…' } lines) gives 0 hits at this head, 4 before.

② Semver level

.changeset/23808-type-descriptions-plain.md: @objectstack/spec patch and @objectstack/platform-objects patch, Clause-②: no, no (widening) or (narrowing) arm. Right for a diff that changes string values of a registry const and the generated bundles that ship in platform-objects's dist, with no key, type, schema or accept/refuse move. The changeset quotes the four sentences exactly as the registry carries them. Clause-②: no agrees across the claim (6207867989), the PR body (its third line) and the changeset. Nothing else published is touched; the test file does not ship. Check Changeset is green on this head.

③ Boundary flags

The dev's reports are 6208446049 (first round) and 6208861054 (patch round) on #23808.

• Full stop or none: A, no full stop. Checked against the sibling rows at this head: seed :871, picklist :887, mapping :888 and dataset :928 all end without one. Answered.
• Mention proxy in the api sentence: moot. proxy is refused at publish (endpoint-publish-gate.ts:364-378), and the patch-round sentence names only what executes. Answered.
• Rewrite the PR body's "after" cells: A, done. The body's table carries the three patch-round sentences and a patch-round note under Acceptance notes, as the PR reads now. Answered; nothing left for the seat.
• Out of scope, noted, not filed: stack.zod.ts:778-779 docs/books .describe() still cite ADR-0046. Author-facing schema documentation, which the card's constraint (docblocks and ADR links in code stay) covers; agreed, no filing class. The shallow clone that could not reach the teardown-shape fixture commit is container environment; Lint · scoped · tooling self-tests is green on this head.
• Deviations: the worktree naming and the detached shared checkout are container-local; the stray /build2.pid sits outside the repo and the diff is exactly 7 files; origin/main was not merged in and the PR is mergeable: true; test:repo not run locally is CI's Test Core.
• Gate verdicts on this head at the reading stamped below. Green: every Lint job (Lint & Repo Gates, CI/release/engine, ESLint, PM dispatch-gates, docs and code guards, repo and tooling gates, the three scoped jobs), Type Check source gates, consumer gates and debt ledger, Build Core, Spec property liveness, Check Changeset, Governed Surface Queue Guard, Dogfood Regression Gate, Check Documentation Links, and the four claim and path guards. In progress: Test Core (1/6 to 6/6) and Type Check · workspace. Skipped as not reached by this diff: Console Pin Gate, Dogfood Verify CLI, Temporal Conformance, Build Docs, Packed-tarball smoke. This record is the contract-tier half of the landing condition; the queue still needs every check green.

Implemented-by: claude/issue-23808-type-descriptions-plain
Reviewed-by: session_01HjR8RUwTPQ3TgbfKihmxp9

VERDICT: PASS

_{read 2026-10-16T05:48Z: card #23808 and #23802, PR #23817's body, file list, diff and check-runs, and the cited code at the head sha.}

---

Generated by Claude Code