feat(spec)!: 双源 C2 收敛 — MetadataEvent / MetadataBulkRegisterRequest 归 ./api,./kernel 侧死删 (#4587) (#4603)

* feat(spec)!: resolve the MetadataEvent/MetadataBulkRegisterRequest dual source — ./kernel copies removed, ./api keeps the bare names (#4587)

The three #4535-C2 baseline rows were the #4411 trap on the kernel metadata
family: MetadataEvent(Schema) and MetadataBulkRegisterRequestSchema each had
a second, different declaration in ./kernel, and which shape a consumer got
depended only on the import path.

Import-statement-level scan across framework, cloud and objectui:

- ./kernel copies: zero importers outside their own unit test in all three
  repos. The kernel MetadataEvent lifecycle vocabulary
  (metadata.registered/.../exported) has NO producer anywhere; the kernel
  bulk-register per-item `namespace` field matches no enforced write path
  (IMetadataService.bulkRegister and MetadataManager.bulkRegister both take
  {type,name,data} items only).
- ./api MetadataEvent is the live realtime contract: MetadataManager
  publishes metadata.{type}.{created|deleted} events and
  @objectstack/client / client-react subscribe against the type.
- ./api MetadataBulkRegisterRequestSchema is the POST /api/meta/bulk/register
  contract whose item shape matches the runtime.

Disposal (route 1, dead-side delete, v17 major window): both kernel copies
removed; ./api is the sole owner of the bare names. Name continuity for the
kernel-only type alias: `MetadataBulkRegisterRequest` (z.input) is now
exported from ./api beside its schema, per the family convention and the
#4570 docs-import concern. Compile-time pin (typeof import conditional type,
#4581 pattern) keeps the bare names out of ./kernel; new events.test.ts
covers the surviving ./api declarations.

dual-source-exports.baseline.json: exactly the 3 named rows removed
(31 -> 28). json-schema.manifest: kernel/MetadataEvent and
kernel/MetadataBulkRegisterRequest retired deliberately; their 11
authorable-surface rows hand-deleted per the #4458/#4568/#4581 precedent
(plugin TS types, schema bodies deleted — no silent-strip path, misuse fails
at the import site at compile time). Changeset: @objectstack/spec major with
FROM -> TO migration lines.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M9uWvoEp9CoLzYjNExj9sL

* chore(spec): regenerate api-surface + reference docs for #4587 (check:generated --fix, 2 proved stale)

api-surface.json: ./kernel loses MetadataEvent(type)/MetadataEventSchema and
MetadataBulkRegisterRequest(type)/MetadataBulkRegisterRequestSchema; ./api
gains the MetadataBulkRegisterRequest type alias beside its schema.
Reference docs: the api/metadata-plugin.mdx page (which documented the
removed kernel pair under the api section and advertised a then-nonexistent
./api type import) is no longer emitted; api/events.mdx now documents
MetadataEvent, api/metadata.mdx documents MetadataBulkRegisterRequest, and
kernel/metadata-plugin.mdx drops the removed schemas.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M9uWvoEp9CoLzYjNExj9sL

* chore(spec): regenerate reference docs after merging main's import-surface gate (#4595)

The merge brought in build-docs' new import-surface ratchet. This PR's
MetadataBulkRegisterRequest type alias on ./api closes the gap the fresh
baseline had accepted, so its line is deleted (shrink-only ratchet).

---------

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

Author: os-zhuang

.changeset/metadata-event-dual-source-kernel-side.md

@@ -0,0 +1,55 @@
+---
+"@objectstack/spec": major
+---
+
+feat(spec)!: `@objectstack/spec/kernel` no longer exports `MetadataEvent(Schema)` / `MetadataBulkRegisterRequest(Schema)` — the bare names belong to `./api` alone (#4587)
+
+The names `MetadataEvent` / `MetadataEventSchema` /
+`MetadataBulkRegisterRequestSchema` resolved to **two different declarations**
+depending on the import path (`./api` vs `./kernel`) — the #4411 dual-source
+trap. Resolution (three-repo, import-statement-level consumer scan: framework,
+cloud, objectui — the `./kernel` copies had zero importers outside their own
+unit test):
+
+- **Removed** `MetadataEventSchema` / `MetadataEvent` from
+  `@objectstack/spec/kernel`. This was a lifecycle-event envelope
+  (`event: 'metadata.registered' | … | 'metadata.exported'`, plus
+  `actor`/`payload`/`namespace`) that **nothing ever emitted or consumed** —
+  the vocabulary appears in no producer in any of the three repos. The live
+  contract is `./api`'s `MetadataEvent(Schema)`
+  (`type: 'metadata.{type}.{created|updated|deleted}'`, with `id` / `definition`
+  / `userId`): `MetadataManager` publishes those events to the realtime
+  service and `@objectstack/client` / `@objectstack/client-react` subscribe to
+  them.
+  - FROM `import { MetadataEvent } from '@objectstack/spec/kernel'` →
+    TO `import type { MetadataEvent } from '@objectstack/spec/api'`.
+    **Shape change**: the api event has `id` (uuid), `type`
+    (`metadata.{type}.{created|updated|deleted}`), `definition`, `userId`; the
+    removed kernel shape's `event` / `actor` / `payload` / `namespace` fields
+    do not exist there. If you needed runtime *watch* events, that contract is
+    `MetadataWatchEvent` in `@objectstack/spec/system`; repository change-log
+    events are `MetadataEvent` from `@objectstack/metadata-core` (ADR-0008) —
+    a third, unrelated declaration that is not part of `@objectstack/spec`.
+- **Removed** `MetadataBulkRegisterRequestSchema` /
+  `MetadataBulkRegisterRequest` from `@objectstack/spec/kernel`. It was a dead
+  near-duplicate of the REST contract that also diverged from the enforced
+  write path: its per-item `namespace` field exists neither in
+  `IMetadataService.bulkRegister` (contracts) nor in
+  `MetadataManager.bulkRegister`, and `namespace` is deprecated platform-wide.
+  - FROM `import { MetadataBulkRegisterRequestSchema, MetadataBulkRegisterRequest } from '@objectstack/spec/kernel'` →
+    TO `import { MetadataBulkRegisterRequestSchema, type MetadataBulkRegisterRequest } from '@objectstack/spec/api'`
+    (the `POST /api/meta/bulk/register` contract; the type export is new on
+    `./api` in this release). **Shape change**: items are strictly
+    `{ type, name, data }` — a per-item `namespace` no longer parses into the
+    accepted shape. `MetadataBulkRegisterRequest` is the authoring-side type
+    (`z.input`): `continueOnError` / `validate` stay optional and carry
+    defaults, as before.
+- `@objectstack/spec/api`'s `MetadataEvent(Schema)` and
+  `MetadataBulkRegisterRequestSchema` are **unchanged** and are now the sole
+  owners of the bare names. Imports from `./api` need no migration.
+- `@objectstack/spec/kernel`'s `MetadataBulkResultSchema` /
+  `MetadataBulkResult` are **unchanged** — only the bulk *register request*
+  pair moved.
+
+`dual-source-exports.baseline.json` shrinks by exactly these 3 rows (31 → 28,
+#4535 C2).

content/docs/references/api/events.mdx

@@ -26,8 +26,8 @@ Examples:
 ## TypeScript Usage
 
 ```typescript
-import { DataEventSchema, DataEventType, MetadataEventType } from '@objectstack/spec/api';
-import type { DataEvent, DataEventType, MetadataEventType } from '@objectstack/spec/api';
+import { DataEventSchema, DataEventType, MetadataEventSchema, MetadataEventType } from '@objectstack/spec/api';
+import type { DataEvent, DataEventType, MetadataEvent, MetadataEventType } from '@objectstack/spec/api';
 
 // Validate data
 const result = DataEventSchema.parse(data);
@@ -64,6 +64,24 @@ const result = DataEventSchema.parse(data);
 * `data.field.changed`
 
 
+---
+
+## MetadataEvent
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **id** | `string` | ✅ | Unique event identifier |
+| **type** | `Enum<'metadata.object.created' \| 'metadata.object.updated' \| 'metadata.object.deleted' \| 'metadata.field.created' \| 'metadata.field.updated' \| 'metadata.field.deleted' \| 'metadata.view.created' \| 'metadata.view.updated' \| 'metadata.view.deleted' \| 'metadata.app.created' \| 'metadata.app.updated' \| 'metadata.app.deleted' \| 'metadata.agent.created' \| 'metadata.agent.updated' \| 'metadata.agent.deleted' \| 'metadata.tool.created' \| 'metadata.tool.updated' \| 'metadata.tool.deleted' \| 'metadata.flow.created' \| 'metadata.flow.updated' \| 'metadata.flow.deleted' \| 'metadata.action.created' \| 'metadata.action.updated' \| 'metadata.action.deleted' \| 'metadata.workflow.created' \| 'metadata.workflow.updated' \| 'metadata.workflow.deleted' \| 'metadata.dashboard.created' \| 'metadata.dashboard.updated' \| 'metadata.dashboard.deleted' \| 'metadata.report.created' \| 'metadata.report.updated' \| 'metadata.report.deleted' \| 'metadata.role.created' \| 'metadata.role.updated' \| 'metadata.role.deleted' \| 'metadata.permission.created' \| 'metadata.permission.updated' \| 'metadata.permission.deleted'>` | ✅ | Event type |
+| **metadataType** | `string` | ✅ | Metadata type (object, view, agent, etc.) |
+| **name** | `string` | ✅ | Metadata item name |
+| **packageId** | `string` | optional | Package ID |
+| **definition** | `any` | optional | Full definition (create/update only) |
+| **userId** | `string` | optional | User who triggered the event |
+| **timestamp** | `string` | ✅ | Event timestamp |
+
+
 ---
 
 ## MetadataEventType

content/docs/references/api/meta.json

@@ -32,7 +32,6 @@
     "export",
     "identity",
     "metadata",
-    "metadata-plugin",
     "notification",
     "package-api",
     "package-registry",

content/docs/references/api/metadata-plugin.mdx

@@ -50,8 +50,8 @@ the entire platform, including Hono, Next.js, and NestJS adapters.
 ## TypeScript Usage
 
 ```typescript
-import { AppDefinitionResponseSchema, ConceptListResponseSchema, MetadataBulkResponseSchema, MetadataBulkUnregisterRequestSchema, MetadataDeleteResponseSchema, MetadataDependenciesResponseSchema, MetadataDependentsResponseSchema, MetadataEffectiveResponseSchema, MetadataExistsResponseSchema, MetadataExportRequestSchema, MetadataExportResponseSchema, MetadataImportRequestSchema, MetadataImportResponseSchema, MetadataItemResponseSchema, MetadataListResponseSchema, MetadataNamesResponseSchema, MetadataOverlayResponseSchema, MetadataOverlaySaveRequestSchema, MetadataQueryRequestSchema, MetadataQueryResponseSchema, MetadataRegisterRequestSchema, MetadataTypeInfoResponseSchema, MetadataTypesResponseSchema, MetadataValidateRequestSchema, MetadataValidateResponseSchema, ObjectDefinitionResponseSchema } from '@objectstack/spec/api';
-import type { AppDefinitionResponse, ConceptListResponse, MetadataBulkResponse, MetadataDeleteResponse, MetadataDependenciesResponse, MetadataDependentsResponse, MetadataEffectiveResponse, MetadataExistsResponse, MetadataExportResponse, MetadataImportResponse, MetadataItemResponse, MetadataListResponse, MetadataNamesResponse, MetadataOverlayResponse, MetadataQueryResponse, MetadataRegisterRequest, MetadataTypeInfoResponse, MetadataTypesResponse, MetadataValidateResponse, ObjectDefinitionResponse } from '@objectstack/spec/api';
+import { AppDefinitionResponseSchema, ConceptListResponseSchema, MetadataBulkRegisterRequestSchema, MetadataBulkResponseSchema, MetadataBulkUnregisterRequestSchema, MetadataDeleteResponseSchema, MetadataDependenciesResponseSchema, MetadataDependentsResponseSchema, MetadataEffectiveResponseSchema, MetadataExistsResponseSchema, MetadataExportRequestSchema, MetadataExportResponseSchema, MetadataImportRequestSchema, MetadataImportResponseSchema, MetadataItemResponseSchema, MetadataListResponseSchema, MetadataNamesResponseSchema, MetadataOverlayResponseSchema, MetadataOverlaySaveRequestSchema, MetadataQueryRequestSchema, MetadataQueryResponseSchema, MetadataRegisterRequestSchema, MetadataTypeInfoResponseSchema, MetadataTypesResponseSchema, MetadataValidateRequestSchema, MetadataValidateResponseSchema, ObjectDefinitionResponseSchema } from '@objectstack/spec/api';
+import type { AppDefinitionResponse, ConceptListResponse, MetadataBulkRegisterRequest, MetadataBulkResponse, MetadataDeleteResponse, MetadataDependenciesResponse, MetadataDependentsResponse, MetadataEffectiveResponse, MetadataExistsResponse, MetadataExportResponse, MetadataImportResponse, MetadataItemResponse, MetadataListResponse, MetadataNamesResponse, MetadataOverlayResponse, MetadataQueryResponse, MetadataRegisterRequest, MetadataTypeInfoResponse, MetadataTypesResponse, MetadataValidateResponse, ObjectDefinitionResponse } from '@objectstack/spec/api';
 
 // Validate data
 const result = AppDefinitionResponseSchema.parse(data);
@@ -85,6 +85,19 @@ const result = AppDefinitionResponseSchema.parse(data);
 | **data** | `{ name: string; label: string; icon?: string; description?: string }[]` | ✅ | List of available concepts (Objects, Apps, Flows) |
 
 
+---
+
+## MetadataBulkRegisterRequest
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **items** | `{ type: string; name: string; data: Record<string, any> }[]` | ✅ | Items to register |
+| **continueOnError** | `boolean` | ✅ | Continue on individual failure |
+| **validate** | `boolean` | ✅ | Validate before registering |
+
+
 ---
 
 ## MetadataBulkResponse

content/docs/references/api/metadata.mdx

@@ -72,26 +72,13 @@ cohesive plugin that "takes over" the entire platform's metadata management:
 ## TypeScript Usage
 
 ```typescript
-import { MetadataBulkRegisterRequestSchema, MetadataBulkResultSchema, MetadataDependencySchema, MetadataEventSchema, MetadataPluginConfigSchema, MetadataPluginManifestSchema, MetadataQuerySchema, MetadataQueryResultSchema, MetadataTypeSchema, MetadataTypeRegistryEntrySchema, MetadataValidationResultSchema } from '@objectstack/spec/kernel';
-import type { MetadataBulkRegisterRequest, MetadataBulkResult, MetadataDependency, MetadataEvent, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel';
+import { MetadataBulkResultSchema, MetadataDependencySchema, MetadataPluginConfigSchema, MetadataPluginManifestSchema, MetadataQuerySchema, MetadataQueryResultSchema, MetadataTypeSchema, MetadataTypeRegistryEntrySchema, MetadataValidationResultSchema } from '@objectstack/spec/kernel';
+import type { MetadataBulkResult, MetadataDependency, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel';
 
 // Validate data
-const result = MetadataBulkRegisterRequestSchema.parse(data);
+const result = MetadataBulkResultSchema.parse(data);
 ```
 
----
-
-## MetadataBulkRegisterRequest
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **items** | `{ type: string; name: string; data: Record<string, any>; namespace?: string }[]` | ✅ | Items to register |
-| **continueOnError** | `boolean` | ✅ | Continue if individual item fails |
-| **validate** | `boolean` | ✅ | Validate before register |
-
-
 ---
 
 ## MetadataBulkResult
@@ -121,24 +108,6 @@ const result = MetadataBulkRegisterRequestSchema.parse(data);
 | **kind** | `Enum<'reference' \| 'extends' \| 'includes' \| 'triggers'>` | ✅ | How the dependency is formed |
 
 
----
-
-## MetadataEvent
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **event** | `Enum<'metadata.registered' \| 'metadata.updated' \| 'metadata.unregistered' \| 'metadata.validated' \| 'metadata.deployed' \| 'metadata.overlay.applied' \| 'metadata.overlay.removed' \| 'metadata.imported' \| 'metadata.exported'>` | ✅ | Event type |
-| **metadataType** | `Enum<'object' \| 'field' \| 'hook' \| 'seed' \| 'mapping' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'position' \| 'agent' \| 'tool' \| 'skill'>` | ✅ | Metadata type |
-| **name** | `string` | ✅ | Metadata item name |
-| **namespace** | `string` | optional | Namespace |
-| **packageId** | `string` | optional | Owning package ID |
-| **timestamp** | `string` | ✅ | Event timestamp |
-| **actor** | `string` | optional | User or system that triggered the event |
-| **payload** | `Record<string, any>` | optional | Event-specific payload |
-
-
 ---
 
 ## MetadataPluginConfig

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

@@ -1620,8 +1620,6 @@
     "MergeResultSchema (const)",
     "MergeStrategyConfig (type)",
     "MergeStrategyConfigSchema (const)",
-    "MetadataBulkRegisterRequest (type)",
-    "MetadataBulkRegisterRequestSchema (const)",
     "MetadataBulkResult (type)",
     "MetadataBulkResultSchema (const)",
     "MetadataCategory (type)",
@@ -1636,8 +1634,6 @@
     "MetadataDependencySchema (const)",
     "MetadataDiffItem (type)",
     "MetadataDiffItemSchema (const)",
-    "MetadataEvent (type)",
-    "MetadataEventSchema (const)",
     "MetadataFallbackStrategy (type)",
     "MetadataFallbackStrategySchema (const)",
     "MetadataLock (type)",
@@ -2855,6 +2851,7 @@
     "MarkNotificationsReadRequestSchema (const)",
     "MarkNotificationsReadResponse (type)",
     "MarkNotificationsReadResponseSchema (const)",
+    "MetadataBulkRegisterRequest (type)",
     "MetadataBulkRegisterRequestSchema (const)",
     "MetadataBulkResponse (type)",
     "MetadataBulkResponseSchema (const)",

packages/spec/api-surface.json

@@ -4639,9 +4639,6 @@
     "kernel/MergeStrategyConfig:alwaysKeepCustom",
     "kernel/MergeStrategyConfig:autoResolveNonConflicting",
     "kernel/MergeStrategyConfig:defaultStrategy",
-    "kernel/MetadataBulkRegisterRequest:continueOnError",
-    "kernel/MetadataBulkRegisterRequest:items",
-    "kernel/MetadataBulkRegisterRequest:validate",
     "kernel/MetadataBulkResult:errors",
     "kernel/MetadataBulkResult:failed",
     "kernel/MetadataBulkResult:succeeded",
@@ -4657,14 +4654,6 @@
     "kernel/MetadataDiffItem:previousName",
     "kernel/MetadataDiffItem:summary",
     "kernel/MetadataDiffItem:type",
-    "kernel/MetadataEvent:actor",
-    "kernel/MetadataEvent:event",
-    "kernel/MetadataEvent:metadataType",
-    "kernel/MetadataEvent:name",
-    "kernel/MetadataEvent:namespace",
-    "kernel/MetadataEvent:packageId",
-    "kernel/MetadataEvent:payload",
-    "kernel/MetadataEvent:timestamp",
     "kernel/MetadataManagerConfig:cache",
     "kernel/MetadataManagerConfig:datasource",
     "kernel/MetadataManagerConfig:fallback",

packages/spec/authorable-surface.json

@@ -11,7 +11,6 @@
     "api/Discovery — no type export",
     "api/GetAnalyticsMetaRequest — no type export",
     "api/HttpFindQueryParams — no type export",
-    "api/MetadataBulkRegisterRequest — no type export",
     "api/MetadataBulkUnregisterRequest — no type export",
     "api/MetadataExportRequest — no type export",
     "api/MetadataImportRequest — no type export",

packages/spec/docs-import-surface.baseline.json

@@ -15,9 +15,6 @@
     "FieldMappingSchema — [./data (const)] ≠ [./integration (const)] ≠ [./shared (const)]",
     "HttpMethod — [./api, ./shared (type)] ≠ [./ui (type)]",
     "HttpRequest — [./shared (type)] ≠ [./ui (type)]",
-    "MetadataBulkRegisterRequestSchema — [./api (const)] ≠ [./kernel (const)]",
-    "MetadataEvent — [./api (type)] ≠ [./kernel (type)]",
-    "MetadataEventSchema — [./api (const)] ≠ [./kernel (const)]",
     "Notification — [./api (type)] ≠ [./ui (type)]",
     "NotificationConfig — [./system (type)] ≠ [./ui (type)]",
     "NotificationConfigSchema — [./system (const)] ≠ [./ui (const)]",