Merge origin/main into claude/issue-4640-revoke-delete-signature

Author: claude

.changeset/converge-activation-event-schema.md

@@ -0,0 +1,77 @@
+---
+"@objectstack/spec": major
+---
+
+feat(spec)!: 双源 C5 收敛 — `ActivationEventSchema` 归 `./kernel` 结构化形状,`./studio` re-export (#4653)
+
+`ActivationEventSchema` 这个名字过去在两个入口解析到**两份不同的声明**,插件作者拿到哪套校验取决于他从哪个子路径 import(#4411 陷阱):
+
+| 入口 | 声明 | 作者写的样子 |
+|:--|:--|:--|
+| `@objectstack/spec/kernel` | `z.object({ type: z.enum([...]), pattern: z.string() })` | `{ type: 'onCommand', pattern: 'my.cmd' }` |
+| `@objectstack/spec/studio` | `z.string()` | `'onCommand:my.cmd'` |
+
+两侧都在作者面上(kernel 侧嵌在 `DynamicLoadRequest.activationEvents`,studio 侧嵌在 `StudioPluginManifest.activationEvents`,后者正是 `defineStudioPlugin` 的入参),所以没有"死侧"可删。v17 统一到**结构化形状**:`./studio` 现在 re-export `./kernel` 的那一份声明,平台只剩一套激活词表。
+
+**为什么是结构化的那一侧赢。** 字符串那一侧更眼熟(照搬 VS Code),但它什么都不校验:`z.string()` 接受 `''`、`'banana'`,以及真正要命的 `'onMetadatType:flow'` —— 这个文件文档里列的词表(`*`、`onMetadataType:`、`onCommand:`、`onView:`)只活在散文里,拼错永远静默通过。结构化形状用 enum 在**创作时**就把触发器类型钉死,这才是声明它的意义。
+
+## FROM → TO
+
+`activationEvents` 的每一项从字符串变成对象。冒号前的段成为 `type`,冒号后的段成为 `pattern`:
+
+```ts
+// FROM (v16 及以前,@objectstack/spec/studio)
+defineStudioPlugin({
+  id: 'objectstack.flow-designer',
+  name: 'Flow Designer',
+  activationEvents: ['onMetadataType:flow'],
+});
+
+// TO (v17+)
+defineStudioPlugin({
+  id: 'objectstack.flow-designer',
+  name: 'Flow Designer',
+  activationEvents: [{ type: 'onMetadataType', pattern: 'flow' }],
+});
+```
+
+逐条对照:
+
+| FROM | TO |
+|:--|:--|
+| `'*'` | `{ type: 'onStartup', pattern: '*' }` |
+| `'onMetadataType:flow'` | `{ type: 'onMetadataType', pattern: 'flow' }` |
+| `'onCommand:myPlugin.doSomething'` | `{ type: 'onCommand', pattern: 'myPlugin.doSomething' }` |
+| `'onView:myPlugin.myPanel'` | `{ type: 'onView', pattern: 'myPlugin.myPanel' }` |
+
+`StudioPluginManifest.activationEvents` 的默认值随之从 `['*']` 变为 `[{ type: 'onStartup', pattern: '*' }]`。`'*'` 没有拿到独立的 `type`:它一直就是"立即激活",而 kernel 侧的 `onStartup` 本来就是这个意思,再加一个枚举值只会造出两个同义词。
+
+## 词表 = 两侧并集,没有能力被静默拿掉
+
+enum 取**两侧 v17 前词表的并集**,共 9 个值:
+
+| 值 | 来源 |
+|:--|:--|
+| `onCommand` | kernel enum + studio 文档 `onCommand:myPlugin.doSomething` |
+| `onRoute` | kernel enum |
+| `onObject` | kernel enum |
+| `onEvent` | kernel enum |
+| `onService` | kernel enum |
+| `onSchedule` | kernel enum |
+| `onStartup` | kernel enum;同时是 studio `'*'` 的落点 |
+| `onMetadataType` | studio 文档/测试 `onMetadataType:object` —— kernel 原本没有 |
+| `onView` | studio 文档/测试 `onView:myPlugin.myPanel` —— kernel 原本没有 |
+
+**未采纳**:cloud-v1 未发布的 marketplace runtime 里的 `priority`、`onInstall`、`onWebhook`。四仓无人读它们,而新增一个 declared-but-unenforced 的键正是 ADR-0049 在清的债 —— 等真有执行点再单独提。
+
+## 迁移是手工的,但失败是响亮的
+
+**没有随附 ADR-0087 conversion,因为写不出能跑到的那一个。** conversion 层(`applyConversions`)接在 `normalizeStackInput` 上,只走 stack 树;而 `StudioPluginManifestSchema` 和 `DynamicLoadRequestSchema` 都是**根 schema**,没有任何父 schema 嵌入它们(前者由 `defineStudioPlugin` 直接 parse,后者是运行时请求载荷),都不在 stack 里。伪造一个永远不会命中的 conversion 只会制造"已自动迁移"的假象。
+
+手工迁移步骤:按上表把每个字符串改写成 `{ type, pattern }`。**漏改会在 parse 处响亮失败** —— `StudioPluginManifestSchema` 是 `strictObject`,字符串遇到对象 schema 直接抛错,不存在静默吞掉或强制转换。
+
+## 其它影响
+
+- `@objectstack/spec/studio` 现在**额外导出** `ActivationEvent` 类型(此前只有 schema),与 `./kernel` 指向同一份声明。
+- `ActivationEventSchema` 从 `dual-source-exports.baseline.json` 移除,基线 22 → 21。
+- 零可作者化 key 消失、零 tombstone:kernel 的 `ActivationEvent:type` / `:pattern` 原样存活,`studio/ActivationEvent` 侧新增 2 个 key(字符串没有 key,对象有),属 `gen:schema` 允许的**新增**。

.changeset/retire-managed-by-system-bucket.md

@@ -0,0 +1,59 @@
+---
+"@objectstack/spec": minor
+"@objectstack/platform-objects": minor
+"@objectstack/plugin-security": minor
+"@objectstack/plugin-approvals": minor
+"@objectstack/plugin-hono-server": minor
+"@objectstack/service-messaging": minor
+---
+
+feat(spec)!: retire the overloaded `managedBy: 'system'` bucket — the residue becomes `system-data` (#3355)
+
+**FROM → TO: `managedBy: 'system'` → `managedBy: 'system-data'`.** One-line fix:
+rename the value. Nothing else about the object changes. `os migrate meta --from 16`
+rewrites it for you; stored metadata is CONVERTED by the ADR-0087 entry
+`object-managed-by-system-to-system-data`, never silently reinterpreted.
+
+ADR-0103 split the overloaded `system` bucket in v16, and it split it
+**additively**: the 20 engine-owned objects moved to the new explicit
+`engine-owned`, while the 8 admin/user-writable ones — the RBAC link tables
+(`sys_user_position`, `sys_user_permission_set`, `sys_position_permission_set`),
+`sys_user_preference`, `sys_approval_delegation`, and the three messaging config
+grids — stayed behind on `system`. That was the right move for a v16 that could
+not break authors, but it left the enum in a state where the surviving value
+names the half that had already moved out: `system` sitting on precisely the
+objects a user writes.
+
+That is not a cosmetic complaint. An author choosing between `system` and
+`engine-owned` had nothing in the vocabulary to choose *on*, so the bucket was
+re-overloadable by anyone reading the name in good faith — a model author most
+of all, since "system table" reads as "the engine owns this" in every other
+codebase. `system-data` states both boundaries explicitly: the **schema** is the
+platform's (versus `platform`, which is tenant-modelled), the **data** is the
+admin's or the user's (versus `engine-owned`, where the engine owns both).
+
+Because v16 already drained the engine side, the conversion is a **one-to-one
+mechanical value rename** with no judgement call — by construction every
+remaining `system` declaration is writable platform data.
+
+**One deliberate consequence — the affordance default flips.** `system` defaulted
+LOCKED and each of the 8 objects re-opened its writes with a
+`userActions: { create: true, edit: true, delete: true }` block. `system-data`
+defaults **WRITABLE** (full CRUD), because a bucket that exists to say "the data
+is yours" should not make every member ask for it back. Those blocks are now
+redundant and have been deleted from the 8 platform objects; keep `userActions`
+only to **NARROW**. If you converted an object that carried no `userActions`, it
+gains the generic affordances — the honest reading of the bucket it moved into.
+
+**No enforcement moves.** The engine write guard, the `DelegatedAdminGate`, RLS
+and permission sets all adjudicate off resolved affordances and the principal,
+never off the bucket name. `system-data` simply joins `platform` / `config` as a
+bucket the fail-closed guard does not cover, because a writable default has
+nothing to close on. The 8 objects passed that guard before (via `userActions`)
+and pass it now (via the bucket default), for the same resolved-affordance
+reason.
+
+`'system'` is **retired from the load path**: the enum rejects it with a
+prescription naming `system-data` and the one-line fix. Absorbing it silently at
+load would leave every author still writing the name this rename exists to
+unteach.

content/docs/data-modeling/objects.mdx

@@ -215,8 +215,8 @@ indexes: [
 | Property | Type | Description |
 | :--- | :--- | :--- |
 | `isSystem` | `boolean` | System object, protected from deletion (default: `false`) |
-| `managedBy` | `enum` | Lifecycle bucket that sets the default CRUD affordances and write policy — `'platform'` (default), `'config'`, `'system'`, `'engine-owned'`, `'append-only'`, `'better-auth'`. See [Lifecycle bucket](#lifecycle-bucket-managedby) below. |
-| `userActions` | `object` | Per-object override of the CRUD affordances the `managedBy` default implies — `{ create?, edit?, delete?, import?, exportCsv? }`. This is what makes a `system`/`append-only` object admin/user-writable. See [Lifecycle bucket](#lifecycle-bucket-managedby). |
+| `managedBy` | `enum` | Lifecycle bucket that sets the default CRUD affordances and write policy — `'platform'` (default), `'config'`, `'system-data'`, `'engine-owned'`, `'append-only'`, `'better-auth'`. See [Lifecycle bucket](#lifecycle-bucket-managedby) below. |
+| `userActions` | `object` | Per-object override of the CRUD affordances the `managedBy` default implies — `{ create?, edit?, delete?, import?, exportCsv? }`. This is what NARROWS a `system-data` object, or opens a verb on an `engine-owned`/`append-only` one. See [Lifecycle bucket](#lifecycle-bucket-managedby). |
 | `sharingModel` | `enum` | Org-Wide Default record visibility (ADR-0055/0056/0090). Canonical four only: `'private'`, `'public_read'`, `'public_read_write'`, `'controlled_by_parent'` (detail visibility derived from its master). The legacy aliases (`'read'`, `'read_write'`, `'full'`) were removed from the enum (ADR-0090 D4) — authoring rejects them. Unset on a custom object resolves to `'private'` (ADR-0090 D1) |
 | `ownership` | `enum` | Record-ownership model: `'user'` (default — injects the reassignable `owner_id` lookup, engaging owner-scoped RLS, "My" views and owner reports), `'org'`, or `'none'` (no per-record owner — Dataverse-style catalog / junction tables, skips `owner_id`). Distinct from the package `own`/`extend` contribution kind. |
 | `validations` | `ValidationRule[]` | Object-level validation rules (see [Validation](/docs/data-modeling/validation)) |
@@ -233,44 +233,58 @@ bare bucket string.
 | :--- | :--- |
 | `platform` | **Default.** User-owned business data — full New / Import / Edit / Delete. |
 | `config` | Admin-authored configuration — New / Edit / Delete, no CSV import. |
-| `system` | Platform-defined schema holding **admin/user-writable data** (RBAC link tables, preferences, messaging config). Locked by default; each object opens its writes via `userActions`. |
+| `system-data` | Platform-defined schema holding **admin/user-writable data** (RBAC link tables, preferences, messaging config). Full CRUD by default; narrow it with `userActions`. |
 | `engine-owned` | Runtime rows a platform service owns end to end — generic CRUD hidden, exposed `['get', 'list']` only, **no user writes ever**. |
 | `append-only` | Immutable audit trail — View + Export only. |
 | `better-auth` | Identity tables owned by the better-auth driver — generic user-context CRUD is suppressed; mutations flow through the auth API (sign-in, invite, reset). |
 
-**`engine-owned` vs. writable `system` objects (ADR-0103).** Two buckets share
-the same locked default matrix but say different things:
+**`engine-owned` vs. `system-data` (ADR-0103, #3355).** Both hold a
+platform-defined schema no tenant may model; they differ on who owns the *rows*:
 
 - **`engine-owned`** — jobs, notifications, approval runtime rows,
   `sys_record_share`, `sys_automation_run`, the metadata store, `sys_secret`,
   audit trails — written only by their owning service under a system context,
-  never through the generic `/data` API. A fail-closed guard
-  (`assertEngineOwnedWriteAllowed`) rejects user-context generic writes to them.
-- **`system`** — platform-defined schema holding admin/user-writable *data*: the
-  RBAC link tables, `sys_user_preference`, `sys_approval_delegation`, the
-  messaging config grids. These declare `userActions` to open the writes they
-  legitimately take:
+  never through the generic `/data` API. Locked by default, and a fail-closed
+  guard (`assertEngineOwnedWriteAllowed`) rejects user-context generic writes.
+- **`system-data`** — the schema is the platform's, the *data* is the admin's or
+  the user's: the RBAC link tables, `sys_user_preference`,
+  `sys_approval_delegation`, the messaging config grids. Full CRUD by default,
+  and no write guard covers the bucket — a writable default has nothing to fail
+  closed on:
 
 ```typescript
 export const SysUserPreference = ObjectSchema.create({
   name: 'sys_user_preference',
-  managedBy: 'system',
-  // Affordance only — RLS / delegated administration is the actual authz.
-  userActions: { create: true, edit: true, delete: true },
+  // Full CRUD by default — no `userActions` needed. RLS / delegated
+  // administration is the actual authz.
+  managedBy: 'system-data',
   // …
 });
 ```
 
-The same override works on `append-only`. `userActions` is an *affordance*
-declaration; the real authorization for these rows is still enforced by RLS,
-delegated administration, and permission sets.
+Pick between them on the *data*, not the table name: if no user ever writes a
+row through the generic API, it is `engine-owned`. Declaring `system-data` on an
+object whose resolved affordances grant no create, edit or delete is a
+contradiction, and `ObjectSchema.create()` refuses it.
+
+`userActions` NARROWS `system-data` (an editable-only grid: `{ create: false,
+delete: false }`) and OPENS a verb on `append-only`. Either way it is an
+*affordance* declaration; the real authorization for these rows is still
+enforced by RLS, delegated administration, and permission sets.
+
+<Callout type="info">
+**Upgrading from v16.** `managedBy: 'system'` was retired in protocol 17 —
+rename it to `'system-data'`, or run `os migrate meta --from 16`. Because the
+new bucket defaults to full CRUD, a `userActions` block that existed only to
+re-open create/edit/delete is now redundant and can be deleted.
+</Callout>
 
 <Callout type="warn">
 A managed object may not advertise `enable.apiMethods` verbs its resolved
 affordances forbid — the registry strips the contradiction at registration
-(`reconcileManagedApiMethods`, ADR-0049). To expose a generic write verb on a
-`system`/`append-only` object, declare the matching `userActions` rather than
-listing the verb in `apiMethods`.
+(`reconcileManagedApiMethods`, ADR-0049). To expose a generic write verb on an
+`engine-owned`/`append-only` object, declare the matching `userActions` rather
+than listing the verb in `apiMethods`.
 </Callout>
 
 ## Naming Conventions

content/docs/plugins/development.mdx

@@ -384,7 +384,7 @@ export const manifest = defineStudioPlugin({
   name: 'Flow Designer',
   version: '2.0.0',
   description: 'Visual flow builder for automation workflows',
-  activationEvents: ['onMetadataType:flow'],
+  activationEvents: [{ type: 'onMetadataType', pattern: 'flow' }],
 
   contributes: {
     metadataViewers: [{

content/docs/references/data/object.mdx

@@ -115,7 +115,7 @@ const result = ApiMethod.parse(data);
 | **description** | `string` | optional | Developer documentation / description |
 | **icon** | `string` | optional | Icon name (Lucide/Material) for UI representation |
 | **isSystem** | `boolean` | optional | Is system object (protected from deletion; defaults its org-wide sharing to public when no sharingModel is set — plugin-sharing) |
-| **managedBy** | `Enum<'platform' \| 'config' \| 'system' \| 'engine-owned' \| 'append-only' \| 'better-auth'>` | optional | Lifecycle bucket — platform (user CRUD) \| config (admin authored) \| system (engine-managed schema, writable via userActions) \| engine-owned (engine owns the lifecycle, no user writes) \| append-only (audit) \| better-auth (identity). UI clients honour the resolved affordance matrix. |
+| **managedBy** | `Enum<'platform' \| 'config' \| 'system-data' \| 'engine-owned' \| 'append-only' \| 'better-auth'>` | optional | Lifecycle bucket — platform (user CRUD) \| config (admin authored) \| system-data (platform-defined schema, admin/user-writable data) \| engine-owned (engine owns the lifecycle, no user writes) \| append-only (audit) \| better-auth (identity). UI clients honour the resolved affordance matrix. |
 | **ownership** | `Enum<'user' \| 'org' \| 'none'>` | optional | Record-ownership model: user (default — injects reassignable owner_id) \| org \| none (no per-record owner, skips owner_id). Distinct from the package own/extend contribution kind. |
 | **userActions** | `{ create?: boolean; import?: boolean; edit?: boolean \| { enabled?: boolean; visibleWhen?: string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; disabledWhen?: string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } }; delete?: boolean \| { enabled?: boolean; visibleWhen?: string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; disabledWhen?: string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } }; … }` | optional | Per-object override of the resolved CRUD affordance matrix. |
 | **systemFields** | `'false' \| { tenant?: boolean; audit?: boolean }` | optional | Opt out of, or selectively disable, registry-level system-field auto-injection. |

content/docs/references/kernel/plugin-runtime.mdx

@@ -38,13 +38,27 @@ This protocol enables:
 ## TypeScript Usage
 
 ```typescript
-import { DynamicLoadRequestSchema, DynamicPluginOperationSchema, DynamicPluginResultSchema, DynamicUnloadRequestSchema, PluginSourceSchema } from '@objectstack/spec/kernel';
-import type { DynamicLoadRequest, DynamicPluginOperation, DynamicPluginResult, DynamicUnloadRequest, PluginSource } from '@objectstack/spec/kernel';
+import { ActivationEventSchema, DynamicLoadRequestSchema, DynamicPluginOperationSchema, DynamicPluginResultSchema, DynamicUnloadRequestSchema, PluginSourceSchema } from '@objectstack/spec/kernel';
+import type { ActivationEvent, DynamicLoadRequest, DynamicPluginOperation, DynamicPluginResult, DynamicUnloadRequest, PluginSource } from '@objectstack/spec/kernel';
 
 // Validate data
-const result = DynamicLoadRequestSchema.parse(data);
+const result = ActivationEventSchema.parse(data);
 ```
 
+---
+
+## ActivationEvent
+
+Lazy activation trigger for a dynamic plugin
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **type** | `Enum<'onCommand' \| 'onRoute' \| 'onObject' \| 'onEvent' \| 'onService' \| 'onSchedule' \| 'onStartup' \| 'onMetadataType' \| 'onView'>` | ✅ | Trigger type for lazy activation |
+| **pattern** | `string` | ✅ | Match pattern for the activation trigger |
+
+
 ---
 
 ## DynamicLoadRequest
@@ -57,7 +71,7 @@ Request to dynamically load a plugin at runtime
 | :--- | :--- | :--- | :--- |
 | **pluginId** | `string` | ✅ | Unique plugin identifier |
 | **source** | `{ type: Enum<'npm' \| 'local' \| 'url' \| 'registry' \| 'git'>; location: string; version?: string; integrity?: string }` | ✅ | Plugin source location for dynamic resolution |
-| **activationEvents** | `{ type: Enum<'onCommand' \| 'onRoute' \| 'onObject' \| 'onEvent' \| 'onService' \| 'onSchedule' \| 'onStartup'>; pattern: string }[]` | optional | Lazy activation triggers; if omitted plugin starts immediately |
+| **activationEvents** | `{ type: Enum<'onCommand' \| 'onRoute' \| 'onObject' \| 'onEvent' \| 'onService' \| 'onSchedule' \| 'onStartup' \| 'onMetadataType' \| 'onView'>; pattern: string }[]` | optional | Lazy activation triggers; if omitted plugin starts immediately |
 | **config** | `Record<string, any>` | optional | Runtime configuration overrides |
 | **priority** | `integer` | ✅ | Loading priority (lower is higher) |
 | **sandbox** | `boolean` | ✅ | Run in an isolated sandbox |