docs(plugin-webhooks): sys_webhook text says a row is an authored subscription and a declared webhook is not a row (#27787)

domain:server#2 · os-sales · session_01L6bhgUCizoYWQVJWjhdR6F

<!-- claude-projects-attribution: {"github_login":"os-sales"} -->
_Requested by **Sales** · [project
thread](https://claude.ai/code/project/chan_01D5bWFY3rFzgJcytD5gD4Uu?thread=cmsg_01D5bWFY3rFzgJcytD5gD4UuPMZ8BHWtPf6nBTp51qSM64)_

Fixes #27607

Clause-②: no
Metadata-protocol: none
Skills-docs: none — text-only description change; no authorable key,
value or meaning moves

domain:server#2 · os-sales · session_01L6bhgUCizoYWQVJWjhdR6F

## 维护者速读

- 改了什么：`sys_webhook` 对象说明、`managed_by` 与 `customized`
两个字段的帮助文字改写为现行模型：数据行是组织在 Studio 或 API 中编写的订阅；代码中声明的 webhook
从元数据注册表读取，不写入任何行。英文翻译由生成器重写，zh-CN / ja-JP / es-ES 三条译文同步重译。
- 为什么改：旧文字仍说声明的 webhook「启动时物化为数据行」，而 ADR-0131 D2 已退役该启动种入器，Setup/Studio
用户读到的是错误说明。
- 风险与回滚：仅文字，无行为、字段或选项变化；回滚即 revert 本 PR。
- 先看：`packages/plugins/plugin-webhooks/src/sys-webhook.object.ts`（对象
description 与两个字段
description）、`packages/plugins/plugin-webhooks/src/translations/zh-CN.objects.generated.ts`（重译三条）、`.changeset/27607-sys-webhook-text.md`。
- 两分钟验证：`node scripts/check-i18n-bundles.mjs --filter=webhooks`（需先 build
CLI），预期 `in sync`；`git grep -n "materialized into rows on boot"`
在源码与翻译中零命中。
- 需要你做的：无，席位落地。

## What changes

- `sys_webhook.description`: a row is an outbound subscription an
organization authors in the Studio editor or through the API; a webhook
declared with `defineStack({ webhooks })` / `defineWebhook()` is read
from the metadata registry and writes no row here (ADR-0131 D2, anchored
in a code comment beside the text). The file's top docblock was already
correct and is unchanged.
- `managed_by` field description: `admin` = created in Setup or through
the API; `package` = a copy the retired 18.0 boot seeder wrote, which
nothing writes now; `platform` = reserved. The enum values are
unchanged. Measured: no writer sets `managed_by: 'package'` or
`'platform'` on a `sys_webhook` row on this tree (the seeder
`bootstrapDeclaredWebhooks` is retired; `isSeededProvenance` only reads
the values).
- `customized` field description (bounded in-place fix, same file, same
defect class): it said "boot seeding will no longer overwrite the row",
the same retired model. It now says the ownership ceremony reads it (an
edited copy under a declared name is kept as a clone, a pristine one
deleted), matching `webhook-provenance.ts`.
- Translations: `en.objects.generated.ts` regenerated by `node
scripts/check-i18n-bundles.mjs --write --filter=webhooks` (no other
package's bundle was written). The generator's merge keeps an existing
translated value even when its source changes, so the zh-CN, ja-JP and
es-ES strings for these three texts were re-translated by hand
(AGENTS.md allows editing translated-locale values; no key added or
dropped), then the generator was re-run and kept them. No source-hash
entry covers these leaves.
- Changeset: `@objectstack/plugin-webhooks` patch.

## Tests

Text-only: no new behaviour test; no existing test or snapshot pins the
old sentences.

<details><summary>plugin-webhooks test + typecheck (head
2b0c160)</summary>

```
Test Files  24 passed (24)
     Tests  252 passed (252)
TEST=0 TC=0
```

</details>

## Acceptance notes

- No other copy of the retired sentence in `content/docs/**` or other
packages; `packages/plugins/plugin-webhooks/CHANGELOG.md` mentions
`managed_by: 'package'` rows in released entries, which describe their
own release and are release-owned.
- No open PR touches `packages/plugins/plugin-webhooks/**` (read across
the 34 open PRs), so no merge-tree probe applies.

## Verification

<details><summary>Gates (head 2b0c160)</summary>

- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack`: 55 commands, all run; 54 exit 0.
- `pnpm check:dual-build-cjs-loads` exit 3, PREREQUISITE NOT MET (needs
a full workspace build; only the CLI and plugin closures were built) —
NOT MEASURED locally, CI runs it.
- `--ran` reconciliation: 55 derived, 54 run, 1 NOT-MEASURED, 0 UNRUN.
- `node scripts/check-i18n-bundles.mjs` exit 0: all bundles in sync, 10
packages.
- `eslint --no-inline-config packages/plugins/plugin-webhooks` exit 0.

</details>

---
_Generated by [Claude
Code](https://claude.ai/code/session_01L6bhgUCizoYWQVJWjhdR6F)_

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01L6bhgUCizoYWQVJWjhdR6F

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/27607-sys-webhook-text.md

@@ -0,0 +1,12 @@
+---
+'@objectstack/plugin-webhooks': patch
+---
+
+docs(plugin-webhooks): the `sys_webhook` object says a row is a webhook an organization authors, and that a declared webhook is not a row
+
+Clause-②: no
+Metadata-protocol: none
+
+The `sys_webhook` object description shown in Setup and Studio said a webhook declared in code with `defineStack({ webhooks })` / `defineWebhook()` was "materialized into rows on boot". That boot seeder is retired: a declared webhook is read from the metadata registry and writes no `sys_webhook` row. The description now says a row is a subscription authored in the Studio editor or through the API, and that a declared webhook is read from the registry.
+
+The help text of two system fields is corrected the same way. `managed_by`: `package` names a copy the retired 18.0 boot seeder wrote, which nothing writes now, and `platform` is reserved. `customized`: it is read by the ownership ceremony (an edited copy under a declared name is kept as a clone, a pristine one deleted), not by a boot seeder. The English bundle is regenerated, and the zh-CN, ja-JP and es-ES strings for these three texts are re-translated. No behaviour, field or option changes.

packages/plugins/plugin-webhooks/src/sys-webhook.object.ts

@@ -53,7 +53,10 @@ export const SysWebhook = ObjectSchema.create({
   // create/edit/delete so admins can at least toggle `active` and edit
   // simple URL/method fields without round-tripping through code.
   userActions: { create: true, edit: true, delete: true, import: false },
-  description: 'Outbound HTTP webhook subscription. Declared in code via defineStack({ webhooks }) / defineWebhook() (materialized into rows on boot) or authored directly in the Studio editor; dispatched by the webhook auto-enqueuer onto the shared HTTP outbox.',
+  // [ADR-0131 D2] A row is an organization's own subscription; a declared
+  // webhook is read from the metadata registry (`declared-webhooks.ts`) and
+  // writes no row. The description says so to every Setup/Studio reader.
+  description: 'Outbound HTTP webhook subscription authored by an organization in the Studio editor or through the API. A webhook declared in code via defineStack({ webhooks }) / defineWebhook() is read from the metadata registry and writes no row here. Both are dispatched by the webhook auto-enqueuer onto the shared HTTP outbox.',
   displayNameField: 'name',
   nameField: 'name', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{label}',
@@ -283,8 +286,9 @@ export const SysWebhook = ObjectSchema.create({
         readonly: true,
         defaultValue: 'admin',
         description:
-          'Record provenance: platform = framework built-in / package = app/package-declared ' +
-          '(boot-seeded from defineStack webhooks) / admin = created in Setup.',
+          'Record provenance: admin = created in Setup or through the API / package = a copy of a ' +
+          'code-declared webhook that the retired 18.0 boot seeder wrote (nothing writes one now: a ' +
+          'declared webhook is read from the metadata registry and is not a row) / platform = reserved.',
         group: 'System',
       },
     ),
@@ -295,8 +299,9 @@ export const SysWebhook = ObjectSchema.create({
       readonly: true,
       defaultValue: false,
       description:
-        'Set when an admin edits a package-declared webhook; boot seeding will no longer ' +
-        'overwrite the row (a deactivated noisy webhook survives redeploys). Meaningless on admin rows.',
+        'Set when an admin edits a package row (a copy the retired 18.0 boot seeder wrote). The ' +
+        'ownership ceremony reads it: an edited copy under a declared name is kept as a clone, a ' +
+        'pristine one is deleted. Meaningless on admin rows.',
       group: 'System',
     }),
 

packages/plugins/plugin-webhooks/src/translations/en.objects.generated.ts

@@ -18,7 +18,7 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
   sys_webhook: {
     label: "Webhook",
     pluralLabel: "Webhooks",
-    description: "Outbound HTTP webhook subscription. Declared in code via defineStack({ webhooks }) / defineWebhook() (materialized into rows on boot) or authored directly in the Studio editor; dispatched by the webhook auto-enqueuer onto the shared HTTP outbox.",
+    description: "Outbound HTTP webhook subscription authored by an organization in the Studio editor or through the API. A webhook declared in code via defineStack({ webhooks }) / defineWebhook() is read from the metadata registry and writes no row here. Both are dispatched by the webhook auto-enqueuer onto the shared HTTP outbox.",
     fields: {
       id: {
         label: "Webhook ID"
@@ -81,7 +81,7 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
       },
       managed_by: {
         label: "Managed By",
-        help: "Record provenance: platform = framework built-in / package = app/package-declared (boot-seeded from defineStack webhooks) / admin = created in Setup.",
+        help: "Record provenance: admin = created in Setup or through the API / package = a copy of a code-declared webhook that the retired 18.0 boot seeder wrote (nothing writes one now: a declared webhook is read from the metadata registry and is not a row) / platform = reserved.",
         options: {
           platform: "platform",
           package: "package",
@@ -90,7 +90,7 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
       },
       customized: {
         label: "Customized",
-        help: "Set when an admin edits a package-declared webhook; boot seeding will no longer overwrite the row (a deactivated noisy webhook survives redeploys). Meaningless on admin rows."
+        help: "Set when an admin edits a package row (a copy the retired 18.0 boot seeder wrote). The ownership ceremony reads it: an edited copy under a declared name is kept as a clone, a pristine one is deleted. Meaningless on admin rows."
       },
       created_at: {
         label: "Created At"

packages/plugins/plugin-webhooks/src/translations/es-ES.objects.generated.ts

@@ -18,7 +18,7 @@ export const esESObjects: NonNullable<TranslationData['objects']> = {
   sys_webhook: {
     label: "Webhook",
     pluralLabel: "Webhooks",
-    description: "Suscripción saliente de Webhook HTTP. Se declara en código mediante defineStack({ webhooks }) / defineWebhook() (materializada en filas al arrancar) o se crea directamente con el editor de Studio; el encolador automático de webhooks la despacha al outbox HTTP compartido.",
+    description: "Suscripción saliente de Webhook HTTP creada por una organización con el editor de Studio o mediante la API. Un webhook declarado en código mediante defineStack({ webhooks }) / defineWebhook() se lee del registro de metadatos y no escribe ninguna fila aquí. Ambos los despacha el encolador automático de webhooks al outbox HTTP compartido.",
     fields: {
       id: {
         label: "ID de webhook"
@@ -81,7 +81,7 @@ export const esESObjects: NonNullable<TranslationData['objects']> = {
       },
       managed_by: {
         label: "Gestionado por",
-        help: "Procedencia del registro: platform = integrado en el framework / package = declarado por app o paquete (sembrado al arrancar desde los webhooks de defineStack) / admin = creado en Setup.",
+        help: "Procedencia del registro: admin = creado en Setup o mediante la API / package = una copia de un webhook declarado en código que escribió el sembrador de arranque retirado de la 18.0 (ya nada la escribe: un webhook declarado se lee del registro de metadatos y no es una fila) / platform = reservado.",
         options: {
           platform: "Plataforma",
           package: "Paquete",
@@ -90,7 +90,7 @@ export const esESObjects: NonNullable<TranslationData['objects']> = {
       },
       customized: {
         label: "Personalizado",
-        help: "Se establece cuando un administrador edita un webhook declarado por un paquete; a partir de entonces el sembrado de arranque deja de sobrescribir la fila (un webhook ruidoso desactivado sobrevive a los redespliegues). Sin sentido en filas admin."
+        help: "Se establece cuando un administrador edita una fila package (una copia que escribió el sembrador de arranque retirado de la 18.0). La lee la ceremonia de propiedad: una copia editada bajo un nombre declarado se conserva como clon y una intacta se elimina. Sin sentido en filas admin."
       },
       created_at: {
         label: "Creado el"

packages/plugins/plugin-webhooks/src/translations/ja-JP.objects.generated.ts

@@ -18,7 +18,7 @@ export const jaJPObjects: NonNullable<TranslationData['objects']> = {
   sys_webhook: {
     label: "ウェブフック",
     pluralLabel: "ウェブフック",
-    description: "送信 HTTP Webhook サブスクリプション。コードでは defineStack({ webhooks }) / defineWebhook() で宣言する（起動時に行として実体化）か、スタジオエディタで直接作成します。Webhook 自動エンキューアが共有 HTTP アウトボックスへディスパッチします。",
+    description: "送信 HTTP Webhook サブスクリプション。組織がスタジオエディタまたは API で作成します。コードで defineStack({ webhooks }) / defineWebhook() により宣言した Webhook はメタデータレジストリから読み取られ、ここに行を書き込みません。どちらも Webhook 自動エンキューアが共有 HTTP アウトボックスへディスパッチします。",
     fields: {
       id: {
         label: "Webhook ID"
@@ -81,7 +81,7 @@ export const jaJPObjects: NonNullable<TranslationData['objects']> = {
       },
       managed_by: {
         label: "管理元",
-        help: "レコードの出所: platform = フレームワーク組み込み / package = アプリ・パッケージ宣言（defineStack の webhooks から起動時シード）/ admin = Setup で作成。",
+        help: "レコードの出所: admin = Setup または API で作成 / package = 廃止された 18.0 の起動時シーダーが書き込んだ、コード宣言 webhook のコピー（現在は何も書き込みません。宣言された webhook はメタデータレジストリから読み取られ、行ではありません）/ platform = 予約済み。",
         options: {
           platform: "プラットフォーム",
           package: "パッケージ",
@@ -90,7 +90,7 @@ export const jaJPObjects: NonNullable<TranslationData['objects']> = {
       },
       customized: {
         label: "カスタマイズ済み",
-        help: "管理者がパッケージ宣言の webhook を編集すると設定されます。以後、起動時シードはこの行を上書きしません（無効化したノイジーな webhook は再デプロイ後も保持）。admin 行では意味を持ちません。"
+        help: "管理者が package 行（廃止された 18.0 の起動時シーダーが書き込んだコピー）を編集すると設定されます。所有権セレモニーがこれを読み取り、宣言名の下で編集されたコピーはクローンとして保持し、未編集のコピーは削除します。admin 行では意味を持ちません。"
       },
       created_at: {
         label: "作成日時"

packages/plugins/plugin-webhooks/src/translations/zh-CN.objects.generated.ts

@@ -18,7 +18,7 @@ export const zhCNObjects: NonNullable<TranslationData['objects']> = {
   sys_webhook: {
     label: "Webhook",
     pluralLabel: "Webhook",
-    description: "外发 HTTP Webhook 订阅。可在代码中通过 defineStack({ webhooks }) / defineWebhook() 声明（启动时物化为数据行），或直接在 Studio 编辑器中编写；由 Webhook 自动入队器分发到共享的 HTTP 发件箱。",
+    description: "外发 HTTP Webhook 订阅，由组织在 Studio 编辑器中或通过 API 编写。在代码中通过 defineStack({ webhooks }) / defineWebhook() 声明的 Webhook 从元数据注册表读取，不会在此写入数据行。两者均由 Webhook 自动入队器分发到共享的 HTTP 发件箱。",
     fields: {
       id: {
         label: "Webhook ID"
@@ -81,7 +81,7 @@ export const zhCNObjects: NonNullable<TranslationData['objects']> = {
       },
       managed_by: {
         label: "管理来源",
-        help: "记录来源：platform = 框架内置 / package = 应用包声明（由 defineStack 的 webhooks 在启动时种入）/ admin = 在 Setup 中创建。",
+        help: "记录来源：admin = 在 Setup 中或通过 API 创建 / package = 已退役的 18.0 启动种入器写入的代码声明 Webhook 副本（如今不再写入：声明的 Webhook 从元数据注册表读取，不是数据行）/ platform = 保留。",
         options: {
           platform: "平台",
           package: "包",
@@ -90,7 +90,7 @@ export const zhCNObjects: NonNullable<TranslationData['objects']> = {
       },
       customized: {
         label: "已定制",
-        help: "当管理员编辑应用包声明的 webhook 时置位；此后启动种入不再覆盖该行（被停用的嘈杂 webhook 可跨重新部署保留）。对 admin 来源的记录无意义。"
+        help: "当管理员编辑 package 行（已退役的 18.0 启动种入器写入的副本）时置位。所有权仪式读取它：声明名称下被编辑过的副本保留为克隆，未改动的副本被删除。对 admin 来源的记录无意义。"
       },
       created_at: {
         label: "创建时间"