feat(spec,objectql,metadata-core)!: retire placeholder metadata kinds per ADR-0088

- spec kernel: MetadataTypeSchema + DEFAULT_METADATA_TYPE_REGISTRY drop
  trigger/router/function/service (30 → 26 kinds) with tombstone comments
  pointing at the delivered forms (hook / record_change flows;
  contributes.routes + apis:; defineStack({functions}); the plugin
  registry). external_catalog annotated RUNTIME-CREATED (ADR-0062/0088).
- plugin-structure: OPS_FILE_SUFFIX_REGEX drops the four suffixes.
- objectql: remove the dormant 'function'-kind load path (nothing ever
  produced such items; defineStack({functions}) is the one way in) and
  drop 'function' from the metadata-service sync list.
- metadata-core: lockstep enum follows.
- Tests that leaned on the retired kinds as deny-gate fixtures now use
  the remaining allowRuntimeCreate:false kind (agent, ADR-0063) and
  allowOrgOverride:false kinds (hook/validation/external_catalog); the
  registry-invariant asserts keep the retired names as reintroduction
  guards.
- Reference docs regenerated (gen:docs); ADR-0005/0010 prose updated.
- showcase KIND_COVERAGE shrinks in lockstep; external_catalog waiver is
  now a permanent, documented exclusion.
- changeset: minor for spec/objectql/metadata-core.

Verified: spec 6690 tests, objectql 773, metadata-core 80,
metadata 260, metadata-protocol 11, full turbo build (70 tasks),
showcase verify, crm 19 — all green.

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

Author: claude

.changeset/retire-placeholder-metadata-kinds.md

@@ -0,0 +1,9 @@
+---
+'@objectstack/spec': minor
+'@objectstack/objectql': minor
+'@objectstack/metadata-core': minor
+---
+
+feat(spec)!: retire the placeholder metadata kinds `trigger`, `router`, `function`, `service` (ADR-0088).
+
+The registry is the contract authors — human and AI — read to learn what can be authored, and these four kinds had no authoring surface, no loader, no schema, and no (or a dead) consumer. `MetadataTypeSchema` + `DEFAULT_METADATA_TYPE_REGISTRY` shrink 30 → 26; `OPS_FILE_SUFFIX_REGEX` drops the four suffixes; the dormant objectql load path that registered QL functions from `type: 'function'` metadata items is removed (`defineStack({ functions })` / plugin `contributes.functions` remain the delivered forms); the metadata-core lockstep enum follows. `external_catalog` stays and is now annotated RUNTIME-CREATED (ADR-0062): its lack of an authoring surface is correct design. The delivered replacements: `hook` / `record_change` flows (trigger), plugin `contributes.routes` + declarative `apis:` (router), `defineStack({ functions })` (function), the plugin/service registry (service). Persisted `sys_metadata` rows are unaffected — no production read path re-parses stored `type` values through the enum.

content/docs/references/api/metadata.mdx

@@ -314,7 +314,7 @@ Metadata query with filtering, sorting, and pagination
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **types** | `Enum<'object' \| 'field' \| 'trigger' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'router' \| 'function' \| 'service' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>[]` | optional | Filter by metadata types |
+| **types** | `Enum<'object' \| 'field' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>[]` | optional | Filter by metadata types |
 | **namespaces** | `string[]` | optional | Filter by namespaces |
 | **packageId** | `string` | optional | Filter by owning package |
 | **search** | `string` | optional | Full-text search query |
@@ -349,7 +349,7 @@ Metadata query with filtering, sorting, and pagination
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `Enum<'object' \| 'field' \| 'trigger' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'router' \| 'function' \| 'service' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>` | ✅ | Metadata type |
+| **type** | `Enum<'object' \| 'field' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>` | ✅ | Metadata type |
 | **name** | `string` | ✅ | Item name (snake_case) |
 | **data** | `Record<string, any>` | ✅ | Metadata payload |
 | **namespace** | `string` | optional | Optional namespace |

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

@@ -130,7 +130,7 @@ const result = MetadataBulkRegisterRequest.parse(data);
 | 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' \| 'trigger' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'router' \| 'function' \| 'service' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>` | ✅ | Metadata type |
+| **metadataType** | `Enum<'object' \| 'field' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>` | ✅ | Metadata type |
 | **name** | `string` | ✅ | Metadata item name |
 | **namespace** | `string` | optional | Namespace |
 | **packageId** | `string` | optional | Owning package ID |
@@ -147,7 +147,7 @@ const result = MetadataBulkRegisterRequest.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **types** | `Enum<'object' \| 'field' \| 'trigger' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'router' \| 'function' \| 'service' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>[]` | optional | Filter by metadata types |
+| **types** | `Enum<'object' \| 'field' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>[]` | optional | Filter by metadata types |
 | **namespaces** | `string[]` | optional | Filter by namespaces |
 | **packageId** | `string` | optional | Filter by owning package |
 | **search** | `string` | optional | Full-text search query |
@@ -182,7 +182,6 @@ const result = MetadataBulkRegisterRequest.parse(data);
 
 * `object`
 * `field`
-* `trigger`
 * `validation`
 * `hook`
 * `seed`
@@ -198,9 +197,6 @@ const result = MetadataBulkRegisterRequest.parse(data);
 * `datasource`
 * `external_catalog`
 * `translation`
-* `router`
-* `function`
-* `service`
 * `email_template`
 * `doc`
 * `book`

content/docs/references/ui/component.mdx

@@ -346,7 +346,7 @@ Type: `string`
 | :--- | :--- | :--- | :--- |
 | **objectName** | `string` | ✅ | Related object name (e.g., "task", "opportunity") |
 | **relationshipField** | `string` | ✅ | Field on related object that points to this record (e.g., "account_id") |
-| **columns** | `string[]` | ✅ | Fields to display in the related list |
+| **columns** | `string[]` | optional | Fields to display in the related list. Optional: when omitted, columns derive from the related object's highlightFields / default list columns (a related list is just another surface that lists that object). Override chain: child highlightFields → field-level relatedListColumns → this inline list. |
 | **sort** | `string \| Object[]` | optional | Sort order for related records |
 | **limit** | `integer` | ✅ | Number of records to display initially |
 | **filter** | `Object[]` | optional | Additional filter criteria for related records |

content/docs/references/ui/view.mdx

@@ -236,7 +236,8 @@ List chart view configuration
 | **view** | `string` | optional | Name of the form view to use for details (e.g. "summary_view", "edit_form") |
 | **preventNavigation** | `boolean` | ✅ | Disable standard navigation entirely |
 | **openNewTab** | `boolean` | ✅ | Force open in new tab (applies to page mode) |
-| **width** | `string \| number` | optional | Width of the drawer/modal (e.g. "600px", "50%") |
+| **size** | `Enum<'auto' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'>` | ✅ | [#2578] Overlay size bucket for drawer/modal detail: 'auto' (default — renderer derives from field count + viewport; AI writes nothing) or a coarse override sm/md/lg/xl/full. Prefer this over the pixel `width`; page mode ignores it. |
+| **width** | `string \| number` | optional | [DEPRECATED → size] Pixel/percent width of the drawer/modal (e.g. "600px"). A pixel width cannot be chosen at authoring time without knowing the client viewport — use the `size` bucket. |
 
 
 ---

docs/adr/0005-metadata-customization-overlay.md

@@ -53,10 +53,10 @@ derives its set from that flag — there is no parallel allowlist
 | Domain | Type | Per-org override? | Why |
 |:---|:---|:---:|:---|
 | data | `object`, `field` | ❌ | A per-org overlay would diverge the table schema; shared DB cannot honour that. |
-| data | `trigger`, `validation`, `hook` | ❌ | DB-side contracts. Per-org variants must ship as a separate package, not an overlay. |
+| data | `validation`, `hook` | ❌ | DB-side contracts. Per-org variants must ship as a separate package, not an overlay. (`trigger` retired as a kind — ADR-0088.) |
 | automation | `flow`, `workflow`, `approval` | ❌ | Carry execution side-effects (events, jobs, audit). Per-org variants are a deployment, not an overlay. |
 | security | `permission`, `profile`, `role` | ❌ | Authorization correctness; overlays would create silent privilege drift. |
-| system | `datasource`, `router`, `function`, `service` | ❌ | Wiring level; changes require code paths, not metadata. |
+| system | `datasource` | ❌ | Wiring level; changes require code paths, not metadata. (`router`/`function`/`service` retired as kinds — ADR-0088; they are code contributions.) |
 | ai | `agent`, `tool`, `skill` | ❌ | Behavioural contracts with model providers; treat like flows. |
 | **ui** | **`view`, `dashboard`, `report`** | ✅ | **Pure presentation. Safe per-org override.** |
 | ui | `page`, `app`, `action` | ❌ | Conservative default — these bind to routes and side-effects. Promote individually if a concrete need appears. |
@@ -534,7 +534,7 @@ entries derived from the prior baseline.
 
 The original ADR gates writes purely on `allowOrgOverride` (type-level).
 This proved too coarse for one category of types: those that ship
-executable code (`hook`, `trigger`, `validation`) declare
+executable code (`hook`, `validation`) declare
 `allowOrgOverride: false` AND `allowRuntimeCreate: true`. The intent —
 documented in `metadata-plugin.zod.ts` — is "users may author brand-new
 items of this type, but artifact-shipped items remain immutable".

docs/adr/0010-metadata-protection-model.md

@@ -120,8 +120,9 @@ The existing `allowOrgOverride` / `allowRuntimeCreate` flags on
 `MetadataTypeRegistryEntry` continue to express **type-wide** policy:
 
 - `allowOrgOverride: false` → no overlay write to any item of this type
-  is ever accepted from a tenant. (`datasource`, `router`, `function`,
-  `service` keep this stance because they encode deployment topology.)
+  is ever accepted from a tenant. (`datasource` keeps this stance because
+  it encodes deployment topology; the former `router`/`function`/`service`
+  kinds were retired outright — ADR-0088.)
 - `allowRuntimeCreate: false` → tenants cannot author brand-new items
   of this type at runtime.
 

examples/app-showcase/src/coverage.ts

@@ -61,12 +61,6 @@ export const KIND_COVERAGE: Record<MetadataType, KindCoverage> = {
     notes:
       'FieldSchema is authored inline on objects (the stack DSL has no standalone `fields` collection); field-zoo exhausts every field type — see the variant-level test.',
   },
-  trigger: {
-    status: 'waived',
-    reason:
-      'No declarative authoring surface: no stack collection or defineTrigger helper. Record-change triggering is demonstrated behaviorally by the record-change flows (requires: ["triggers"]).',
-    issue: ISSUE.noAuthoringSurface,
-  },
   validation: {
     status: 'demonstrated',
     files: [
@@ -102,26 +96,10 @@ export const KIND_COVERAGE: Record<MetadataType, KindCoverage> = {
   external_catalog: {
     status: 'waived',
     reason:
-      'Runtime-created via Setup → Datasources → Sync (ADR-0062); no declarative artifact an app package can ship. The showcase demos the federation flow that produces one.',
+      'PERMANENT by design (ADR-0088): a runtime-created snapshot produced by Setup → Datasources → Sync (ADR-0062). A package shipping one would be stale on arrival; the showcase demos the federation flow that produces it.',
     issue: ISSUE.noAuthoringSurface,
   },
   translation: { status: 'demonstrated', files: ['src/system/translations/index.ts'] },
-  router: {
-    status: 'waived',
-    reason:
-      'Code-only (allowRuntimeCreate: false). The code-level equivalent is the imperative HTTP mount in src/system/server/recalc-endpoint.ts.',
-    issue: ISSUE.noAuthoringSurface,
-  },
-  function: {
-    status: 'waived',
-    reason: 'Code-only (allowRuntimeCreate: false); no declarative authoring surface.',
-    issue: ISSUE.noAuthoringSurface,
-  },
-  service: {
-    status: 'waived',
-    reason: 'Code-only (allowRuntimeCreate: false); no declarative authoring surface.',
-    issue: ISSUE.noAuthoringSurface,
-  },
   email_template: { status: 'demonstrated', files: ['src/system/emails/index.ts'] },
   doc: {
     status: 'demonstrated',

packages/metadata-core/src/types.ts

@@ -19,7 +19,6 @@ import { z } from 'zod';
 export const MetadataTypeSchema = z.enum([
   'object',
   'field',
-  'trigger',
   'validation',
   'hook',
   'view',
@@ -29,6 +28,8 @@ export const MetadataTypeSchema = z.enum([
   'action',
   'flow',
   'workflow',
+  // ADR-0088: trigger/router/function/service retired (kept in lockstep
+  // with the spec kernel enum; see metadata-plugin.zod.ts).
   // ADR-0019: `approval` is a flow node, not a metadata type.
   'job',
   'agent',
@@ -45,9 +46,6 @@ export const MetadataTypeSchema = z.enum([
   'datasource',
   'cube',
   'settings',
-  'router',
-  'function',
-  'service',
   'email_template',
 ]).describe('Canonical metadata type name');
 

packages/objectql/src/overlay-precedence.test.ts

@@ -163,12 +163,14 @@ describe('overlay whitelist enforcement (shared-DB invariant)', () => {
     // After PR-10d.7 introduced `allowRuntimeCreate`, "denied" now splits
     // into two cohorts:
     //
-    //  1. Types with `allowRuntimeCreate: true` (hook/trigger/validation) —
+    //  1. Types with `allowRuntimeCreate: true` (hook/validation) —
     //     blocked only when overlaying an artifact-backed item. Brand-new
     //     (artifact-free) names succeed. Tested separately below.
     //
-    //  2. Types with `allowRuntimeCreate: false` (router/function/service) —
-    //     blocked for ANY write in project-kernel mode.
+    //  2. Types with `allowRuntimeCreate: false` — after ADR-0088 retired the
+    //     router/function/service placeholder kinds, `agent` (platform-owned,
+    //     ADR-0063) is the remaining member — blocked for ANY write in
+    //     project-kernel mode.
     //
     //     NOTE: `datasource` moved to cohort #1 with the ADR-0015 Addendum
     //     (runtime-UI-creatable datasources). Brand-new runtime datasources
@@ -181,19 +183,9 @@ describe('overlay whitelist enforcement (shared-DB invariant)', () => {
     describe('denied — must throw 403 (not_overridable or not_creatable)', () => {
         const deniedTypeWide: Array<{ type: string; reason: string; item: any }> = [
             {
-                type: 'router',
-                reason: 'API routing must be deterministic; per-org divergence creates invisible conflicts',
-                item: { name: 'case_api', path: '/api/cases' },
-            },
-            {
-                type: 'function',
-                reason: 'serverless function definitions must be deployment-only, not per-org',
-                item: { name: 'process_payment', handler: 'index.ts' },
-            },
-            {
-                type: 'service',
-                reason: 'service definitions must be deployment-only, not per-org',
-                item: { name: 'notification_service' },
+                type: 'agent',
+                reason: 'agents are platform-owned (ADR-0063); per-org agent forks are withdrawn',
+                item: { name: 'my_agent', label: 'My Agent' },
             },
         ];
 
@@ -275,16 +267,17 @@ describe('overlay whitelist enforcement (shared-DB invariant)', () => {
 
     // ── single-kernel deployments: gate disengaged ──
     describe('single-kernel mode (no environmentId) — gate bypassed', () => {
-        it('allows function overlay when environmentId is undefined (gate bypassed)', async () => {
+        it('allows agent overlay when environmentId is undefined (gate bypassed)', async () => {
             // No environmentId => not project-kernel mode => legacy "anything goes"
             // path used by control-plane bootstrap. ADR-0005 §"Whitelist".
-            // `function` is a definitively-denied type in project-kernel mode,
-            // so this case best demonstrates the bypass semantics.
+            // `agent` is a definitively-denied type in project-kernel mode
+            // (allowRuntimeCreate: false, ADR-0063), so this case best
+            // demonstrates the bypass semantics.
             const { protocol: localProto } = makeProtocol({ environmentId: undefined });
             const result = await localProto.saveMetaItem({
-                type: 'function',
-                name: 'my_fn',
-                item: { name: 'my_fn', handler: 'index.ts' },
+                type: 'agent',
+                name: 'my_agent',
+                item: { name: 'my_agent', label: 'My Agent', role: 'assistant', instructions: 'Answer questions about test data.' },
             });
             expect(result.success).toBe(true);
         });
@@ -323,6 +316,8 @@ describe('overlay whitelist enforcement (shared-DB invariant)', () => {
             expect(allowedFromRegistry.has('profile')).toBe(true);
             // Execution/wiring-layer types must NOT be in the set.
             // Accepting them as overlays would corrupt runtime semantics.
+            // (trigger/router/function/service were retired outright by
+            // ADR-0088 — the asserts double as reintroduction guards.)
             expect(allowedFromRegistry.has('trigger')).toBe(false);
             expect(allowedFromRegistry.has('validation')).toBe(false);
             expect(allowedFromRegistry.has('hook')).toBe(false);