From 23d6eb0389ccf046aa11aa4e354ee2ef2f8abd2c Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 04:12:04 +0000 Subject: [PATCH 1/5] fix(spec): four metadata type descriptions read in Setup are plain admin sentences Claude-Session: https://claude.ai/code/session_014SHyy7c7ipsMkzJ3J9mdL9 Co-authored-by: Claude --- .../spec/src/kernel/metadata-plugin.zod.ts | 22 +++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/packages/spec/src/kernel/metadata-plugin.zod.ts b/packages/spec/src/kernel/metadata-plugin.zod.ts index 980d32ae3d1..de838a12735 100644 --- a/packages/spec/src/kernel/metadata-plugin.zod.ts +++ b/packages/spec/src/kernel/metadata-plugin.zod.ts @@ -1128,7 +1128,12 @@ export const DEFAULT_METADATA_TYPE_REGISTRY: MetadataTypeRegistryEntryParsed[] = // run at publish (stack schema, `publishPackage`, `publishPackageDrafts`) and // again at load (`buildEndpointIndex`). This entry adds a SHAPE check in // front of them, never a second opinion about servability. - { type: 'api', label: 'API Endpoint', description: 'Declarative HTTP endpoint — a stable URL and policy layer over an existing pipeline (ADR-0121)', filePatterns: ['**/*.api.ts', '**/*.api.yml', '**/*.api.json'], supportsOverlay: false, allowEnvironmentOverlay: false, allowRuntimeCreate: false, supportsVersioning: false, executionPinned: false, loadOrder: 92, domain: 'system' }, + // + // `description` is admin-facing copy (Setup reads it through the generated + // metadata-forms translations), so it stays in plain words; the design it + // summarises — a declarative endpoint, a stable URL and policy layer over an + // existing pipeline — is ADR-0121. + { type: 'api', label: 'API Endpoint', description: 'A stable HTTP URL that other systems call to reach flows, scripts and data in the app', filePatterns: ['**/*.api.ts', '**/*.api.yml', '**/*.api.json'], supportsOverlay: false, allowEnvironmentOverlay: false, allowRuntimeCreate: false, supportsVersioning: false, executionPinned: false, loadOrder: 92, domain: 'system' }, { type: 'translation', label: 'Translation', filePatterns: ['**/*.translation.ts', '**/*.translation.yml', '**/*.translation.json'], supportsOverlay: true, allowEnvironmentOverlay: true, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 90, domain: 'system' }, { type: 'email_template', label: 'Email Template', filePatterns: ['**/*.email-template.ts', '**/*.email-template.yml', '**/*.email-template.json'], supportsOverlay: true, allowEnvironmentOverlay: true, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 85, domain: 'system' }, // ADR-0046: package documentation. Inert data — no runtime behavior, no @@ -1136,7 +1141,9 @@ export const DEFAULT_METADATA_TYPE_REGISTRY: MetadataTypeRegistryEntryParsed[] = // Runtime-creatable so AI/authors can draft docs via saveMetaItem // (ADR-0033). Collected from flat `src/docs/*.md` by the CLI; the kernel // never parses `content`. loadOrder is last: nothing references docs. - { type: 'doc', label: 'Documentation', description: 'Package documentation — flat Markdown items (ADR-0046)', filePatterns: ['**/docs/*.md'], supportsOverlay: false, allowEnvironmentOverlay: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 99, domain: 'system' }, + // `description` is admin-facing copy: plain words, the ADR-0046 vocabulary + // (flat Markdown items) stays in this comment. + { type: 'doc', label: 'Documentation', description: 'A help page written in Markdown that a package ships for its users to read', filePatterns: ['**/docs/*.md'], supportsOverlay: false, allowEnvironmentOverlay: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 99, domain: 'system' }, // Navigation spine over docs (ADR-0046 §6): ordered groups, membership derived // by rule. Overlay-mergeable at read (`supportsOverlay: true`); runtime- // creatable for AI/authors. loadOrder last (references docs). @@ -1150,7 +1157,10 @@ export const DEFAULT_METADATA_TYPE_REGISTRY: MetadataTypeRegistryEntryParsed[] = // Zero live org-scoped book overlay rows in-repo at rollback. Studio's // drag-edit of a PACKAGED book now answers `403 not_overridable`; // authoring a BRAND-NEW book keeps working (`allowRuntimeCreate`). - { type: 'book', label: 'Documentation Book', description: 'Documentation navigation spine — ordered groups with derived membership (ADR-0046 §6)', filePatterns: ['**/*.book.ts'], supportsOverlay: true, allowEnvironmentOverlay: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 99, domain: 'system' }, + // + // `description` is admin-facing copy: plain words, the ADR-0046 §6 + // vocabulary (navigation spine, ordered groups, derived membership) stays here. + { type: 'book', label: 'Documentation Book', description: 'A table of contents that groups the help pages of a package into ordered sections', filePatterns: ['**/*.book.ts'], supportsOverlay: true, allowEnvironmentOverlay: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 99, domain: 'system' }, // Security Protocol // @@ -1207,7 +1217,11 @@ export const DEFAULT_METADATA_TYPE_REGISTRY: MetadataTypeRegistryEntryParsed[] = // declaration would let it re-scope `org` → `platform`. // `loadOrder: 12` — before `permission`/`position` (15), so a set's // `systemPermissions` resolves against capabilities that already exist. - { type: 'capability', label: 'Capability', description: 'Package-declared authorization capability — the DEFINITION side of ADR-0066 D1 (grants live on permission sets; requirements on resources)', filePatterns: ['**/*.capability.ts', '**/*.capability.yml'], supportsOverlay: false, allowEnvironmentOverlay: false, allowRuntimeCreate: false, supportsVersioning: false, executionPinned: false, loadOrder: 12, domain: 'security' }, + // + // `description` is admin-facing copy in plain words. In ADR terms this is the + // DEFINITION side of ADR-0066 D1: grants live on permission sets, + // requirements on resources. + { type: 'capability', label: 'Capability', description: 'A permission a package defines; you grant it through permission sets', filePatterns: ['**/*.capability.ts', '**/*.capability.yml'], supportsOverlay: false, allowEnvironmentOverlay: false, allowRuntimeCreate: false, supportsVersioning: false, executionPinned: false, loadOrder: 12, domain: 'security' }, // AI Protocol // `agent`: executionPinned — long-running conversations must stick to the From 30b41533f50a7a675ee48959dcdc515ff0b29be8 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 04:15:53 +0000 Subject: [PATCH 2/5] test(platform-objects): bare-type ledger records the plain-copy type descriptions Claude-Session: https://claude.ai/code/session_014SHyy7c7ipsMkzJ3J9mdL9 Co-authored-by: Claude --- .../bare-type-display-echo-decisions.test.ts | 63 +++++++++++++------ 1 file changed, 44 insertions(+), 19 deletions(-) diff --git a/packages/platform-objects/src/apps/translations/bare-type-display-echo-decisions.test.ts b/packages/platform-objects/src/apps/translations/bare-type-display-echo-decisions.test.ts index 157c0e46a85..221a5e0cf06 100644 --- a/packages/platform-objects/src/apps/translations/bare-type-display-echo-decisions.test.ts +++ b/packages/platform-objects/src/apps/translations/bare-type-display-echo-decisions.test.ts @@ -132,6 +132,12 @@ // makes one of them false reds this file — round 6 raised the bar from // "checked" to "pinned" and this round keeps it there. // +// ⚠️ Since rewritten (#23808): the `api`, `doc`, `book` and `capability` +// descriptions are now plain admin copy, with their ADR vocabulary moved to the +// comments beside the registry rows. "pipeline" and "ordered groups" no longer +// appear in that prose; their schema readings stay pinned below because they +// are still true, and the four rows record the new renderings. +// // ## ⭐ THE SAME ENGLISH STEM IN THREE POSITIONS, DECIDED TWO WAYS // // `capability.label` is the third position in this catalog for the word round 6 @@ -306,10 +312,10 @@ const DECISIONS: readonly Decision[] = [ scope: 'type', key: 'api', prop: 'description', - en: 'Declarative HTTP endpoint — a stable URL and policy layer over an existing pipeline (ADR-0121)', + en: 'A stable HTTP URL that other systems call to reach flows, scripts and data in the app', verdict: ALL_TRANSLATE, reason: - '⭐ "pipeline" READS LIKE AN ApiEndpointSchema.type AND IS NOT ONE — asserted below: the schema accepts type "proxy" and refuses type "pipeline" (flow/script/object_operation/proxy), so the word is prose and is rendered 管道 / パイプライン / pipeline. "policy" takes the sense this catalog already separates and round 6 recorded: 策略 for a configured strategy (hook.fields.retryPolicy.label 重试策略), NOT 政策 which is reserved for a published document (sys_oauth_application.fields.policy.label 隐私政策); ja ポリシー, es política. "layer" takes sys_view_definition.description (软件包层 / パッケージレイヤー / La capa de paquete) — ⚠️ zh renders it 层 and ja レイヤー there, but this leaf\'s ja reads 層 in the compound ポリシー層 because the twin\'s レイヤー is itself attached to a katakana head; the reading is recorded rather than silently harmonised. ⭐ `HTTP`, `URL` and `ADR-0121` are KEPT VERBATIM in all three — machine tokens by the rule that kept 256 and N in round 6, asserted by the token guard below. ⚠️ em-dash convention copied: zh folds to —— with no spaces (hook.sections.legacy_handler.description 函数名引用——已废弃), ja and es keep a spaced —.', + 'REWRITTEN AS PLAIN ADMIN COPY: the registry description is what Setup shows, so it says what the item is and who uses it, and the ADR-0121 vocabulary (declarative endpoint, policy layer, pipeline) moved to the comment beside the registry row. "flows, scripts and data" names what ApiEndpointSchema.type can target (flow/script/object_operation; proxy is the rare fourth) in words an admin reads. ⇒ 其他系统调用的稳定 HTTP URL，用于访问应用的流程、脚本和数据 / 他のシステムがアプリのフロー、スクリプト、データにアクセスするために呼び出す固定の HTTP URL / URL HTTP estable a la que llaman otros sistemas para acceder a los flujos, scripts y datos de la aplicación. ⭐ `HTTP` and `URL` stay machine tokens in all three, asserted by the token guard below. ⚠️ No second person in zh/ja/es: the catalog carries no 你的/您的, so "the app" is rendered 应用 / アプリ / la aplicación.', }, { scope: 'type', @@ -324,10 +330,10 @@ const DECISIONS: readonly Decision[] = [ scope: 'type', key: 'doc', prop: 'description', - en: 'Package documentation — flat Markdown items (ADR-0046)', + en: 'A help page written in Markdown that a package ships for its users to read', verdict: ALL_TRANSLATE, reason: - '⭐⭐ ONE OF THE TWO ROWS WHERE THE #19430 NEAR-MISS IS REAL. `package` IS a legal MetadataProvenanceSchema value and DocSchema really does accept `_provenance: "package"` while refusing a rendered one — both asserted below, so the trap is proved to exist before it is cleared. It is CLEARED three ways, each asserted: the key is `_provenance`, which the loader sets and no form asks for (a doc parses without it, and the whole en metadata-forms catalog names no `_`-prefixed key); `doc` is BARE, so this string labels no input at all; and where this catalog DOES render a leaf whose stored value is literally `package` it renders the display and keeps the value (sys_metadata.fields.managed_by.options.package is 包 / パッケージ / Paquete). ⇒ rendered. "flat" takes position.sections.position.description (扁平的 / フラットな / plano); "items" takes app.sections.navigation.description (侧边栏菜单项 / サイドバー項目 / Elementos de barra lateral). ⇒ 软件包文档——扁平的 Markdown 文档项（ADR-0046） / パッケージのドキュメント — フラットな Markdown 項目（ADR-0046） / Documentación del paquete — elementos Markdown planos (ADR-0046). ⚠️ zh answers "package" two ways in this catalog — 包 inside compounds (包 ID, 包版本) and 软件包 in running prose (软件包层) — and this is prose, so it takes 软件包. ⭐ `Markdown` is KEPT as a format proper noun in all three, the same treatment the catalog gives HTML in sys_email_template.fields.body_text.help; asserted by the token guard.', + 'REWRITTEN AS PLAIN ADMIN COPY: "flat Markdown items (ADR-0046)" became what an admin meets, a help page, and the ADR reference moved to the comment beside the registry row. `package` is still rendered as the noun, by the near-miss clearing asserted below (zh prose takes 软件包, as in 软件包层). ⇒ 软件包随附的 Markdown 帮助页面，供用户阅读 / パッケージに同梱される、ユーザー向けの Markdown ヘルプページ / Página de ayuda en Markdown que un paquete incluye para que la lean sus usuarios. ⭐ `Markdown` is KEPT as a format proper noun in all three; asserted by the token guard.', }, { scope: 'type', @@ -342,10 +348,10 @@ const DECISIONS: readonly Decision[] = [ scope: 'type', key: 'book', prop: 'description', - en: 'Documentation navigation spine — ordered groups with derived membership (ADR-0046 §6)', + en: 'A table of contents that groups the help pages of a package into ordered sections', verdict: ALL_TRANSLATE, reason: - '`groups` IS A KEY, NOT AN ENUM VALUE — asserted below by the rule round 6 used to clear timeoutMs: BookSchema.groups takes an ARRAY (it refuses the string "ordered"), so no rendered word can land in it. "navigation" takes app.sections.navigation.label (导航 / ナビゲーション / Navegación); "ordered" takes report.fields.order.label (排序 / 並び順 / Orden); "derived" takes dataset.fields.measures.derived.label (派生自 / 派生元 / Derivada de). "spine" and "membership" have no authored twin and the row says so: spine is rendered 主干 / 骨格 / Columna vertebral and membership 成员 / メンバーシップ / pertenencia. ⇒ 文档导航主干——有序分组，成员由派生确定（ADR-0046 §6） / ドキュメントナビゲーションの骨格 — 順序付きグループと派生されたメンバーシップ（ADR-0046 §6） / Columna vertebral de navegación de la documentación — grupos ordenados con pertenencia derivada (ADR-0046 §6). ⭐ `ADR-0046` AND `§6` are both kept verbatim — the section mark is part of the citation and is asserted as its own token, because dropping it is the kind of loss no census can see.', + 'REWRITTEN AS PLAIN ADMIN COPY: "navigation spine — ordered groups with derived membership (ADR-0046 §6)" became a table of contents, and the ADR-0046 §6 vocabulary moved to the comment beside the registry row. "help pages" is the same phrase the doc row now uses, so the two types read as a pair in every locale. "sections" is prose, not BookSchema.groups (a key that takes an array, asserted below). ⇒ 将软件包的帮助页面按顺序分节组织的目录 / パッケージのヘルプページを順序付きのセクションにまとめた目次 / Índice que organiza las páginas de ayuda de un paquete en secciones ordenadas. No machine token is kept: the ADR citation and its §6 are exactly what this rewrite removed, asserted by the plain-copy guard below.', }, { scope: 'type', @@ -360,10 +366,10 @@ const DECISIONS: readonly Decision[] = [ scope: 'type', key: 'capability', prop: 'description', - en: 'Package-declared authorization capability — the DEFINITION side of ADR-0066 D1 (grants live on permission sets; requirements on resources)', + en: 'A permission a package defines; you grant it through permission sets', verdict: ALL_TRANSLATE, reason: - 'THE SECOND REAL `package` NEAR-MISS, cleared exactly as the doc row above and asserted separately on CapabilityDeclarationSchema rather than inherited — the two schemas splice the same protection mixin but that is a fact to assert, not to assume. ⭐ The clause "grants live on permission sets" has a STRUCTURAL authored twin one panel away: position.sections.position.description renders "Capability lives on permission sets" as 能力在权限集上 / 能力は権限セットに / La capacidad reside en los permission sets, and this row copies the frame while substituting 授予 / 付与 / las concesiones for "grants". "authorization" takes sys_oauth_application._actions.enable_oauth_application.description (授权 / 認可 / la autorización) — ⚠️ ja answers this word two ways and the row picks deliberately: 認可 (authz, that leaf) over 認証 (authn, sys_device_code.description), because ADR-0066 is about what a principal MAY do. "resources" takes sys_organization._actions.leave_organization.confirmText (资源 / リソース / recursos). ⇒ 软件包声明的授权能力——ADR-0066 D1 的定义侧（授予在权限集上；要求在资源上） / パッケージが宣言する認可ケイパビリティ — ADR-0066 D1 の定義側（付与は権限セットに、要件はリソースに） / Capacidad de autorización declarada por el paquete — el lado de la DEFINICIÓN de ADR-0066 D1 (las concesiones residen en los conjuntos de permisos; los requisitos, en los recursos). ⚠️ es answers "permission sets" two ways — conjuntos de permisos (permission.sections.identity.description) and the English permission sets (position.sections.position.description) — and this row takes the Spanish one, because the leaf it is describing IS the permission domain\'s own definition side. ⭐ `ADR-0066` and `D1` are kept verbatim and asserted; the en\'s uppercase DEFINITION is carried as case in es and as plain text in zh/ja, which have no case to carry it with.', + 'REWRITTEN AS PLAIN ADMIN COPY, in the voice the Setup review gave verbatim for this type. "the DEFINITION side of ADR-0066 D1" moved to the comment beside the registry row. "permission sets" takes the type label permission.label (权限集 / 権限セット / Conjunto de permisos, plural conjuntos de permisos); "grant" takes 授予 / 付与 / conceder, the verbs this catalog already uses for permission grants. zh/ja/es use an impersonal second clause, since the catalog carries no second person. ⇒ 软件包定义的一项权限；通过权限集授予 / パッケージが定義する権限。権限セットを通じて付与します / Permiso que define un paquete; se concede mediante conjuntos de permisos. No machine token is kept: ADR-0066 and D1 are exactly what this rewrite removed, asserted by the plain-copy guard below.', }, ]; @@ -659,10 +665,8 @@ describe('#19403 round 7 — the #19430 discipline, asserted AT THE SCHEMA', () it('the machine tokens the ledger decided to KEEP are still verbatim in every locale', () => { const KEPT: ReadonlyArray = [ ['api', 'label', ['API']], - ['api', 'description', ['HTTP', 'URL', 'ADR-0121']], - ['doc', 'description', ['Markdown', 'ADR-0046']], - ['book', 'description', ['ADR-0046', '§6']], - ['capability', 'description', ['ADR-0066', 'D1']], + ['api', 'description', ['HTTP', 'URL']], + ['doc', 'description', ['Markdown']], ]; for (const [type, prop, tokens] of KEPT) { for (const [locale, forms] of TRANSLATED_LOCALES) { @@ -677,18 +681,39 @@ describe('#19403 round 7 — the #19430 discipline, asserted AT THE SCHEMA', () it('⭐ the token predicate can say NO — and a bare `includes` could not', () => { // Dark. Without this the assertion above could be a guard that is true of - // every string. `§6` must not be found as `§7`, and `D1` must not be found - // inside `ADR-0121`'s digits. - const zhBook = (zhCNMetadataForms as Record).book.description as string; - expect(carriesToken(zhBook, '§6')).toBe(true); - expect(carriesToken(zhBook, '§7')).toBe(false); + // every string. `Markdown` must not be found as `Mark`, and `URL` must not + // be found as `UR`. + const jaDoc = (jaJPMetadataForms as Record).doc.description as string; + expect(carriesToken(jaDoc, 'Markdown')).toBe(true); + expect(jaDoc.includes('Mark'), 'substring containment says YES').toBe(true); + expect(carriesToken(jaDoc, 'Mark'), 'the word-boundary predicate says NO').toBe(false); const zhApi = (zhCNMetadataForms as Record).api.description as string; expect(zhApi.includes('D1'), 'substring says nothing here').toBe(false); - expect(carriesToken(zhApi, 'ADR-0121')).toBe(true); - expect(carriesToken(zhApi, 'ADR-012')).toBe(false); + expect(carriesToken(zhApi, 'HTTP')).toBe(true); + expect(carriesToken(zhApi, 'HTT')).toBe(false); expect(carriesToken(zhApi, 'URL')).toBe(true); expect(carriesToken(zhApi, 'UR')).toBe(false); }); + + it('the four descriptions Setup shows are plain copy — no ADR vocabulary in any locale', () => { + // The admin-facing half of the registry rows: ADR numbers, decision ids, + // finding ids, `emit()` and `kernel` live in the comments beside the rows, + // never in the string Setup renders. Checked in `en` AND every translated + // locale, because a translation made from the old source would carry them. + const ADR_VOCABULARY = /ADR-|\bD\d|finding F|emit\(\)|kernel|§/; + const PLAIN = ['api', 'doc', 'book', 'capability']; + for (const type of PLAIN) { + expect(registryEntry(type)?.description, `registry ${type}.description`).not.toMatch(ADR_VOCABULARY); + for (const [locale, forms] of [['en', enMetadataForms], ...TRANSLATED_LOCALES] as const) { + const text = (forms as Record)[type]?.description as string; + expect(typeof text, `${locale} ${type}.description`).toBe('string'); + expect(text, `${locale} ${type}.description`).not.toMatch(ADR_VOCABULARY); + } + } + // Dark: the same pattern fires on the prose this rewrite replaced. + expect('Documentation navigation spine (ADR-0046 §6)').toMatch(ADR_VOCABULARY); + expect('the DEFINITION side of ADR-0066 D1').toMatch(ADR_VOCABULARY); + }); }); describe('#19403 round 7 — the provenance table agrees these leaves are now authored', () => { From b625ac4c79d3253bec6c6759470deec6a661e065 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 04:24:13 +0000 Subject: [PATCH 3/5] chore(platform-objects): regenerate metadata-forms translations for the plain type descriptions Claude-Session: https://claude.ai/code/session_014SHyy7c7ipsMkzJ3J9mdL9 Co-authored-by: Claude --- .changeset/23808-type-descriptions-plain.md | 18 ++++++++++++++++++ .../en.metadata-forms.generated.ts | 8 ++++---- .../es-ES.metadata-forms.generated.ts | 8 ++++---- .../ja-JP.metadata-forms.generated.ts | 8 ++++---- .../zh-CN.metadata-forms.generated.ts | 8 ++++---- 5 files changed, 34 insertions(+), 16 deletions(-) create mode 100644 .changeset/23808-type-descriptions-plain.md diff --git a/.changeset/23808-type-descriptions-plain.md b/.changeset/23808-type-descriptions-plain.md new file mode 100644 index 00000000000..d7c11e78625 --- /dev/null +++ b/.changeset/23808-type-descriptions-plain.md @@ -0,0 +1,18 @@ +--- +'@objectstack/spec': patch +'@objectstack/platform-objects': patch +--- + +Clause-②: no + +The `description` of four metadata types in `DEFAULT_METADATA_TYPE_REGISTRY`, which Setup shows under the +type's title, is now one plain sentence for an administrator instead of ADR vocabulary: + +- `api`: "A stable HTTP URL that other systems call to reach flows, scripts and data in the app" +- `doc`: "A help page written in Markdown that a package ships for its users to read" +- `book`: "A table of contents that groups the help pages of a package into ordered sections" +- `capability`: "A permission a package defines; you grant it through permission sets" + +The ADR references (ADR-0121, ADR-0046, ADR-0046 §6, ADR-0066 D1) moved to the comments beside the +registry rows. The generated metadata-forms translations carry the new sentences in en, zh-CN, ja-JP +and es-ES. No key, type or accept/refuse result changes. diff --git a/packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts b/packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts index 8cc4ebb15ec..c6195656395 100644 --- a/packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts +++ b/packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts @@ -2202,7 +2202,7 @@ export const enMetadataForms: NonNullable = { }, api: { label: "API Endpoint", - description: "Declarative HTTP endpoint — a stable URL and policy layer over an existing pipeline (ADR-0121)" + description: "A stable HTTP URL that other systems call to reach flows, scripts and data in the app" }, translation: { label: "Translation" @@ -2282,11 +2282,11 @@ export const enMetadataForms: NonNullable = { }, doc: { label: "Documentation", - description: "Package documentation — flat Markdown items (ADR-0046)" + description: "A help page written in Markdown that a package ships for its users to read" }, book: { label: "Documentation Book", - description: "Documentation navigation spine — ordered groups with derived membership (ADR-0046 §6)" + description: "A table of contents that groups the help pages of a package into ordered sections" }, permission: { label: "Permission Set", @@ -2390,7 +2390,7 @@ export const enMetadataForms: NonNullable = { }, capability: { label: "Capability", - description: "Package-declared authorization capability — the DEFINITION side of ADR-0066 D1 (grants live on permission sets; requirements on resources)" + description: "A permission a package defines; you grant it through permission sets" }, agent: { label: "AI Agent", diff --git a/packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts b/packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts index e6c06e5c690..413157adc05 100644 --- a/packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts +++ b/packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts @@ -2202,7 +2202,7 @@ export const esESMetadataForms: NonNullable = }, api: { label: "Endpoint API", - description: "Endpoint HTTP declarativo — una URL estable y una capa de política sobre un pipeline existente (ADR-0121)" + description: "URL HTTP estable a la que llaman otros sistemas para acceder a los flujos, scripts y datos de la aplicación" }, translation: { label: "Traducción" @@ -2282,11 +2282,11 @@ export const esESMetadataForms: NonNullable = }, doc: { label: "Documentación", - description: "Documentación del paquete — elementos Markdown planos (ADR-0046)" + description: "Página de ayuda en Markdown que un paquete incluye para que la lean sus usuarios" }, book: { label: "Libro de documentación", - description: "Columna vertebral de navegación de la documentación — grupos ordenados con pertenencia derivada (ADR-0046 §6)" + description: "Índice que organiza las páginas de ayuda de un paquete en secciones ordenadas" }, permission: { label: "Conjunto de permisos", @@ -2390,7 +2390,7 @@ export const esESMetadataForms: NonNullable = }, capability: { label: "Capacidad", - description: "Capacidad de autorización declarada por el paquete — el lado de la DEFINICIÓN de ADR-0066 D1 (las concesiones residen en los conjuntos de permisos; los requisitos, en los recursos)" + description: "Permiso que define un paquete; se concede mediante conjuntos de permisos" }, agent: { label: "Agente de IA", diff --git a/packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts b/packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts index 018c1341696..f09118708d1 100644 --- a/packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts +++ b/packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts @@ -2202,7 +2202,7 @@ export const jaJPMetadataForms: NonNullable = }, api: { label: "API エンドポイント", - description: "宣言的な HTTP エンドポイント — 既存のパイプラインの上に安定した URL とポリシー層を提供（ADR-0121）" + description: "他のシステムがアプリのフロー、スクリプト、データにアクセスするために呼び出す固定の HTTP URL" }, translation: { label: "翻訳" @@ -2282,11 +2282,11 @@ export const jaJPMetadataForms: NonNullable = }, doc: { label: "ドキュメント", - description: "パッケージのドキュメント — フラットな Markdown 項目（ADR-0046）" + description: "パッケージに同梱される、ユーザー向けの Markdown ヘルプページ" }, book: { label: "ドキュメントブック", - description: "ドキュメントナビゲーションの骨格 — 順序付きグループと派生されたメンバーシップ（ADR-0046 §6）" + description: "パッケージのヘルプページを順序付きのセクションにまとめた目次" }, permission: { label: "権限セット", @@ -2390,7 +2390,7 @@ export const jaJPMetadataForms: NonNullable = }, capability: { label: "ケイパビリティ", - description: "パッケージが宣言する認可ケイパビリティ — ADR-0066 D1 の定義側（付与は権限セットに、要件はリソースに）" + description: "パッケージが定義する権限。権限セットを通じて付与します" }, agent: { label: "AI エージェント", diff --git a/packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts b/packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts index 77df4c29041..5632006f080 100644 --- a/packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts +++ b/packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts @@ -2202,7 +2202,7 @@ export const zhCNMetadataForms: NonNullable = }, api: { label: "API 端点", - description: "声明式 HTTP 端点——在既有管道之上提供稳定的 URL 与策略层（ADR-0121）" + description: "其他系统调用的稳定 HTTP URL，用于访问应用的流程、脚本和数据" }, translation: { label: "翻译" @@ -2282,11 +2282,11 @@ export const zhCNMetadataForms: NonNullable = }, doc: { label: "文档", - description: "软件包文档——扁平的 Markdown 文档项（ADR-0046）" + description: "软件包随附的 Markdown 帮助页面，供用户阅读" }, book: { label: "文档手册", - description: "文档导航主干——有序分组，成员由派生确定（ADR-0046 §6）" + description: "将软件包的帮助页面按顺序分节组织的目录" }, permission: { label: "权限集", @@ -2390,7 +2390,7 @@ export const zhCNMetadataForms: NonNullable = }, capability: { label: "能力", - description: "软件包声明的授权能力——ADR-0066 D1 的定义侧（授予在权限集上；要求在资源上）" + description: "软件包定义的一项权限；通过权限集授予" }, agent: { label: "AI 代理", From 28f8993c5209b1ae2918b063523e4da8a103086e Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 05:20:01 +0000 Subject: [PATCH 4/5] fix(spec): api, doc and book descriptions say only what the code does api names the two endpoint types that execute (flow, object operation); doc and book drop the package-only clause, since both are runtime-creatable. Claude-Session: https://claude.ai/code/session_014SHyy7c7ipsMkzJ3J9mdL9 Co-authored-by: Claude --- .changeset/23808-type-descriptions-plain.md | 6 +++--- .../bare-type-display-echo-decisions.test.ts | 12 ++++++------ .../translations/es-ES.metadata-forms.generated.ts | 6 +++--- .../translations/ja-JP.metadata-forms.generated.ts | 6 +++--- .../translations/zh-CN.metadata-forms.generated.ts | 6 +++--- packages/spec/src/kernel/metadata-plugin.zod.ts | 6 +++--- 6 files changed, 21 insertions(+), 21 deletions(-) diff --git a/.changeset/23808-type-descriptions-plain.md b/.changeset/23808-type-descriptions-plain.md index d7c11e78625..444d3fa52d3 100644 --- a/.changeset/23808-type-descriptions-plain.md +++ b/.changeset/23808-type-descriptions-plain.md @@ -8,9 +8,9 @@ Clause-②: no The `description` of four metadata types in `DEFAULT_METADATA_TYPE_REGISTRY`, which Setup shows under the type's title, is now one plain sentence for an administrator instead of ADR vocabulary: -- `api`: "A stable HTTP URL that other systems call to reach flows, scripts and data in the app" -- `doc`: "A help page written in Markdown that a package ships for its users to read" -- `book`: "A table of contents that groups the help pages of a package into ordered sections" +- `api`: "A stable HTTP URL that other systems call to run a flow or work with records in the app" +- `doc`: "A help page written in Markdown that a package ships or you write yourself" +- `book`: "A table of contents that groups help pages into ordered sections" - `capability`: "A permission a package defines; you grant it through permission sets" The ADR references (ADR-0121, ADR-0046, ADR-0046 §6, ADR-0066 D1) moved to the comments beside the diff --git a/packages/platform-objects/src/apps/translations/bare-type-display-echo-decisions.test.ts b/packages/platform-objects/src/apps/translations/bare-type-display-echo-decisions.test.ts index 221a5e0cf06..ea453d84b68 100644 --- a/packages/platform-objects/src/apps/translations/bare-type-display-echo-decisions.test.ts +++ b/packages/platform-objects/src/apps/translations/bare-type-display-echo-decisions.test.ts @@ -312,10 +312,10 @@ const DECISIONS: readonly Decision[] = [ scope: 'type', key: 'api', prop: 'description', - en: 'A stable HTTP URL that other systems call to reach flows, scripts and data in the app', + en: 'A stable HTTP URL that other systems call to run a flow or work with records in the app', verdict: ALL_TRANSLATE, reason: - 'REWRITTEN AS PLAIN ADMIN COPY: the registry description is what Setup shows, so it says what the item is and who uses it, and the ADR-0121 vocabulary (declarative endpoint, policy layer, pipeline) moved to the comment beside the registry row. "flows, scripts and data" names what ApiEndpointSchema.type can target (flow/script/object_operation; proxy is the rare fourth) in words an admin reads. ⇒ 其他系统调用的稳定 HTTP URL，用于访问应用的流程、脚本和数据 / 他のシステムがアプリのフロー、スクリプト、データにアクセスするために呼び出す固定の HTTP URL / URL HTTP estable a la que llaman otros sistemas para acceder a los flujos, scripts y datos de la aplicación. ⭐ `HTTP` and `URL` stay machine tokens in all three, asserted by the token guard below. ⚠️ No second person in zh/ja/es: the catalog carries no 你的/您的, so "the app" is rendered 应用 / アプリ / la aplicación.', + 'REWRITTEN AS PLAIN ADMIN COPY: the registry description is what Setup shows, so it says what the item is and who uses it, and the ADR-0121 vocabulary (declarative endpoint, policy layer, pipeline) moved to the comment beside the registry row. It names only what EXECUTES: ApiEndpointSchema.type says only `flow` and `object_operation` run, while `script` and `proxy` are rejected at publish, so "run a flow or work with records" is the whole servable set in an admin\'s words. "records" takes the catalog\'s record noun (记录 / レコード / registros). ⇒ 其他系统调用的稳定 HTTP URL，用于运行流程或操作应用中的记录 / 他のシステムが呼び出す固定の HTTP URL。フローを実行したり、アプリのレコードを操作したりします / URL HTTP estable a la que llaman otros sistemas para ejecutar un flujo o trabajar con los registros de la aplicación. ⭐ `HTTP` and `URL` stay machine tokens in all three, asserted by the token guard below. ⚠️ No second person in zh/ja/es: the catalog carries no 你的/您的.', }, { scope: 'type', @@ -330,10 +330,10 @@ const DECISIONS: readonly Decision[] = [ scope: 'type', key: 'doc', prop: 'description', - en: 'A help page written in Markdown that a package ships for its users to read', + en: 'A help page written in Markdown that a package ships or you write yourself', verdict: ALL_TRANSLATE, reason: - 'REWRITTEN AS PLAIN ADMIN COPY: "flat Markdown items (ADR-0046)" became what an admin meets, a help page, and the ADR reference moved to the comment beside the registry row. `package` is still rendered as the noun, by the near-miss clearing asserted below (zh prose takes 软件包, as in 软件包层). ⇒ 软件包随附的 Markdown 帮助页面，供用户阅读 / パッケージに同梱される、ユーザー向けの Markdown ヘルプページ / Página de ayuda en Markdown que un paquete incluye para que la lean sus usuarios. ⭐ `Markdown` is KEPT as a format proper noun in all three; asserted by the token guard.', + 'REWRITTEN AS PLAIN ADMIN COPY: "flat Markdown items (ADR-0046)" became what an admin meets, a help page, and the ADR reference moved to the comment beside the registry row. Both origins are named because the registry row is `allowRuntimeCreate: true`: a doc can be shipped by a package or drafted in place through saveMetaItem. `package` is still rendered as the noun, by the near-miss clearing asserted below (zh prose takes 软件包). zh/ja/es carry the second origin impersonally (自行编写 / 自分で作成 / redactada directamente). ⇒ 以 Markdown 编写的帮助页面，可由软件包随附，也可自行编写 / Markdown で書かれたヘルプページ。パッケージに同梱されるほか、自分で作成することもできます / Página de ayuda en Markdown, incluida en un paquete o redactada directamente. ⭐ `Markdown` is KEPT as a format proper noun in all three; asserted by the token guard.', }, { scope: 'type', @@ -348,10 +348,10 @@ const DECISIONS: readonly Decision[] = [ scope: 'type', key: 'book', prop: 'description', - en: 'A table of contents that groups the help pages of a package into ordered sections', + en: 'A table of contents that groups help pages into ordered sections', verdict: ALL_TRANSLATE, reason: - 'REWRITTEN AS PLAIN ADMIN COPY: "navigation spine — ordered groups with derived membership (ADR-0046 §6)" became a table of contents, and the ADR-0046 §6 vocabulary moved to the comment beside the registry row. "help pages" is the same phrase the doc row now uses, so the two types read as a pair in every locale. "sections" is prose, not BookSchema.groups (a key that takes an array, asserted below). ⇒ 将软件包的帮助页面按顺序分节组织的目录 / パッケージのヘルプページを順序付きのセクションにまとめた目次 / Índice que organiza las páginas de ayuda de un paquete en secciones ordenadas. No machine token is kept: the ADR citation and its §6 are exactly what this rewrite removed, asserted by the plain-copy guard below.', + 'REWRITTEN AS PLAIN ADMIN COPY: "navigation spine — ordered groups with derived membership (ADR-0046 §6)" became a table of contents, and the ADR-0046 §6 vocabulary moved to the comment beside the registry row. No package clause: the row is `allowRuntimeCreate: true` and a brand-new book can be authored in place. "help pages" is the doc row\'s own phrase, so the two types read as a pair in every locale. "sections" is prose, not BookSchema.groups (a key that takes an array, asserted below). ⇒ 将帮助页面按顺序分节组织的目录 / ヘルプページを順序付きのセクションにまとめた目次 / Índice que organiza las páginas de ayuda en secciones ordenadas. No machine token is kept: the ADR citation and its §6 are exactly what this rewrite removed, asserted by the plain-copy guard below.', }, { scope: 'type', diff --git a/packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts b/packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts index 413157adc05..a4b4dbcfb57 100644 --- a/packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts +++ b/packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts @@ -2202,7 +2202,7 @@ export const esESMetadataForms: NonNullable = }, api: { label: "Endpoint API", - description: "URL HTTP estable a la que llaman otros sistemas para acceder a los flujos, scripts y datos de la aplicación" + description: "URL HTTP estable a la que llaman otros sistemas para ejecutar un flujo o trabajar con los registros de la aplicación" }, translation: { label: "Traducción" @@ -2282,11 +2282,11 @@ export const esESMetadataForms: NonNullable = }, doc: { label: "Documentación", - description: "Página de ayuda en Markdown que un paquete incluye para que la lean sus usuarios" + description: "Página de ayuda en Markdown, incluida en un paquete o redactada directamente" }, book: { label: "Libro de documentación", - description: "Índice que organiza las páginas de ayuda de un paquete en secciones ordenadas" + description: "Índice que organiza las páginas de ayuda en secciones ordenadas" }, permission: { label: "Conjunto de permisos", diff --git a/packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts b/packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts index f09118708d1..b4d88e329a7 100644 --- a/packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts +++ b/packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts @@ -2202,7 +2202,7 @@ export const jaJPMetadataForms: NonNullable = }, api: { label: "API エンドポイント", - description: "他のシステムがアプリのフロー、スクリプト、データにアクセスするために呼び出す固定の HTTP URL" + description: "他のシステムが呼び出す固定の HTTP URL。フローを実行したり、アプリのレコードを操作したりします" }, translation: { label: "翻訳" @@ -2282,11 +2282,11 @@ export const jaJPMetadataForms: NonNullable = }, doc: { label: "ドキュメント", - description: "パッケージに同梱される、ユーザー向けの Markdown ヘルプページ" + description: "Markdown で書かれたヘルプページ。パッケージに同梱されるほか、自分で作成することもできます" }, book: { label: "ドキュメントブック", - description: "パッケージのヘルプページを順序付きのセクションにまとめた目次" + description: "ヘルプページを順序付きのセクションにまとめた目次" }, permission: { label: "権限セット", diff --git a/packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts b/packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts index 5632006f080..77a49aaead7 100644 --- a/packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts +++ b/packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts @@ -2202,7 +2202,7 @@ export const zhCNMetadataForms: NonNullable = }, api: { label: "API 端点", - description: "其他系统调用的稳定 HTTP URL，用于访问应用的流程、脚本和数据" + description: "其他系统调用的稳定 HTTP URL，用于运行流程或操作应用中的记录" }, translation: { label: "翻译" @@ -2282,11 +2282,11 @@ export const zhCNMetadataForms: NonNullable = }, doc: { label: "文档", - description: "软件包随附的 Markdown 帮助页面，供用户阅读" + description: "以 Markdown 编写的帮助页面，可由软件包随附，也可自行编写" }, book: { label: "文档手册", - description: "将软件包的帮助页面按顺序分节组织的目录" + description: "将帮助页面按顺序分节组织的目录" }, permission: { label: "权限集", diff --git a/packages/spec/src/kernel/metadata-plugin.zod.ts b/packages/spec/src/kernel/metadata-plugin.zod.ts index de838a12735..28732ed60ba 100644 --- a/packages/spec/src/kernel/metadata-plugin.zod.ts +++ b/packages/spec/src/kernel/metadata-plugin.zod.ts @@ -1133,7 +1133,7 @@ export const DEFAULT_METADATA_TYPE_REGISTRY: MetadataTypeRegistryEntryParsed[] = // metadata-forms translations), so it stays in plain words; the design it // summarises — a declarative endpoint, a stable URL and policy layer over an // existing pipeline — is ADR-0121. - { type: 'api', label: 'API Endpoint', description: 'A stable HTTP URL that other systems call to reach flows, scripts and data in the app', filePatterns: ['**/*.api.ts', '**/*.api.yml', '**/*.api.json'], supportsOverlay: false, allowEnvironmentOverlay: false, allowRuntimeCreate: false, supportsVersioning: false, executionPinned: false, loadOrder: 92, domain: 'system' }, + { type: 'api', label: 'API Endpoint', description: 'A stable HTTP URL that other systems call to run a flow or work with records in the app', filePatterns: ['**/*.api.ts', '**/*.api.yml', '**/*.api.json'], supportsOverlay: false, allowEnvironmentOverlay: false, allowRuntimeCreate: false, supportsVersioning: false, executionPinned: false, loadOrder: 92, domain: 'system' }, { type: 'translation', label: 'Translation', filePatterns: ['**/*.translation.ts', '**/*.translation.yml', '**/*.translation.json'], supportsOverlay: true, allowEnvironmentOverlay: true, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 90, domain: 'system' }, { type: 'email_template', label: 'Email Template', filePatterns: ['**/*.email-template.ts', '**/*.email-template.yml', '**/*.email-template.json'], supportsOverlay: true, allowEnvironmentOverlay: true, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 85, domain: 'system' }, // ADR-0046: package documentation. Inert data — no runtime behavior, no @@ -1143,7 +1143,7 @@ export const DEFAULT_METADATA_TYPE_REGISTRY: MetadataTypeRegistryEntryParsed[] = // never parses `content`. loadOrder is last: nothing references docs. // `description` is admin-facing copy: plain words, the ADR-0046 vocabulary // (flat Markdown items) stays in this comment. - { type: 'doc', label: 'Documentation', description: 'A help page written in Markdown that a package ships for its users to read', filePatterns: ['**/docs/*.md'], supportsOverlay: false, allowEnvironmentOverlay: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 99, domain: 'system' }, + { type: 'doc', label: 'Documentation', description: 'A help page written in Markdown that a package ships or you write yourself', filePatterns: ['**/docs/*.md'], supportsOverlay: false, allowEnvironmentOverlay: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 99, domain: 'system' }, // Navigation spine over docs (ADR-0046 §6): ordered groups, membership derived // by rule. Overlay-mergeable at read (`supportsOverlay: true`); runtime- // creatable for AI/authors. loadOrder last (references docs). @@ -1160,7 +1160,7 @@ export const DEFAULT_METADATA_TYPE_REGISTRY: MetadataTypeRegistryEntryParsed[] = // // `description` is admin-facing copy: plain words, the ADR-0046 §6 // vocabulary (navigation spine, ordered groups, derived membership) stays here. - { type: 'book', label: 'Documentation Book', description: 'A table of contents that groups the help pages of a package into ordered sections', filePatterns: ['**/*.book.ts'], supportsOverlay: true, allowEnvironmentOverlay: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 99, domain: 'system' }, + { type: 'book', label: 'Documentation Book', description: 'A table of contents that groups help pages into ordered sections', filePatterns: ['**/*.book.ts'], supportsOverlay: true, allowEnvironmentOverlay: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 99, domain: 'system' }, // Security Protocol // From a8dd6f769f1d43381c6076654baff8eb8352d4ac Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 05:30:36 +0000 Subject: [PATCH 5/5] chore(platform-objects): regenerate en metadata-forms for the corrected descriptions Claude-Session: https://claude.ai/code/session_014SHyy7c7ipsMkzJ3J9mdL9 Co-authored-by: Claude --- .../src/apps/translations/en.metadata-forms.generated.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts b/packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts index c6195656395..195727e98a6 100644 --- a/packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts +++ b/packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts @@ -2202,7 +2202,7 @@ export const enMetadataForms: NonNullable = { }, api: { label: "API Endpoint", - description: "A stable HTTP URL that other systems call to reach flows, scripts and data in the app" + description: "A stable HTTP URL that other systems call to run a flow or work with records in the app" }, translation: { label: "Translation" @@ -2282,11 +2282,11 @@ export const enMetadataForms: NonNullable = { }, doc: { label: "Documentation", - description: "A help page written in Markdown that a package ships for its users to read" + description: "A help page written in Markdown that a package ships or you write yourself" }, book: { label: "Documentation Book", - description: "A table of contents that groups the help pages of a package into ordered sections" + description: "A table of contents that groups help pages into ordered sections" }, permission: { label: "Permission Set",