feat(spec)!: retire the standalone validation metadata kind (#4509, ADR-0088)

A validation rule authored as its own artifact bound to nothing and gated no
write. ValidationRuleSchema carries no object-binding key — no `object`, no
`objectName` — and all six variants are strictObject, so an author could not
supply one either. No merge step existed; the only code expecting such a key was
a reference-tracker row scanning a field the schema would have stripped.
Meanwhile the engine evaluates exactly one shape: the object's own
`validations[]`, on insert and on every matched update row.

So a rule created through the standalone door (*.validation.ts, or Studio's
Validations list) parsed, saved, reported success, and intercepted nothing —
including a state_machine rule, which ADR-0020 routes through this same
vocabulary. An author could believe they had locked down record state
transitions and have changed nothing.

Under ADR-0088 the kind fails the admission test on its first clause: a rule has
no independent lifecycle, because it only means something against an object. And
unlike the sibling disconnects in this batch it could not be bridged into one —
the shape has nowhere to name its object. Enforce-or-remove picks ENFORCE where
the feature exists and only wiring is missing (email_template), REMOVE where the
shape cannot carry the feature.

The rule VOCABULARY is untouched: ValidationRuleSchema and all six variants are
unchanged and fully live, and the engine's evaluation path is not modified. The
ledger keeps governing the schema through the gate's SPEC_ONLY_SCHEMAS override
(alongside webhook and query) — an ungoverned live schema is how the next drift
would hide.

Removed: registry entry (with its file patterns), MetadataTypeSchema member,
metadata-core lockstep enum member, schema-map entry, create seed, Studio nav
item + hand-crafted form + its four locale strings, and the dangling
reference-tracker row. Stored standalone rows are left alone — never evaluated,
so nothing changes behaviorally.

Also restamps validation.json's engine evidence lines (drifted ~220 lines) and
adds the ADR-0088 addendum recording the retirement.

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

Author: claude

.changeset/validation-kind-retired.md

@@ -0,0 +1,55 @@
+---
+"@objectstack/spec": major
+"@objectstack/metadata-core": major
+"@objectstack/metadata-protocol": minor
+"@objectstack/platform-objects": minor
+---
+
+feat(spec)!: retire the standalone `validation` metadata kind (#4509, ADR-0088)
+
+A validation rule authored as its own artifact bound to nothing and gated no
+write. `ValidationRuleSchema` carries **no object-binding key** — no `object`,
+no `objectName` — and all six variants are `strictObject`, so an author could
+not supply one either. No merge step existed. The only code that expected such a
+key was a reference-tracker row scanning a field the schema would have stripped.
+Meanwhile the engine evaluates exactly one shape: the object's own
+`validations[]` array, on insert and on every matched update row.
+
+So a rule created through the standalone door — a `*.validation.ts` file, or
+Studio's Validations list — parsed, saved, reported success, and intercepted
+nothing. Including a `state_machine` rule, which ADR-0020 routes through this
+same vocabulary: an author could believe they had locked down record state
+transitions and have changed nothing at all.
+
+Under ADR-0088 the kind fails the admission test on its first clause: a rule has
+no independent lifecycle, because it only means something against an object. And
+unlike the sibling disconnects closed in this batch, it could not be bridged into
+one — the shape has nowhere to name its object.
+
+**The rule vocabulary is untouched.** `ValidationRuleSchema` and all six
+variants are unchanged and fully live; the engine's evaluation path is not
+modified by this change. It is the *kind* that was inert, not the schema. The
+liveness ledger keeps governing it through the gate's `SPEC_ONLY_SCHEMAS`
+override (alongside `webhook` and `query`), because an ungoverned live schema is
+exactly how the next drift would hide.
+
+**Migration.** Move the rule into the owning object's `validations:` array — the
+rule body is identical, same schema, same six variants:
+
+```ts
+// before — a standalone *.validation.ts, which never ran
+export default defineValidation({ name: 'amount_positive', type: 'script', … })
+
+// after — on the object, where rules are evaluated
+ObjectSchema.create({
+  name: 'invoice',
+  validations: [{ name: 'amount_positive', type: 'script', … }],
+})
+```
+
+Removed: the registry entry (and its `*.validation.ts` / `*.validation.yml`
+patterns), the `MetadataTypeSchema` member, the metadata-core lockstep enum
+member, the schema-map entry, the create seed, Studio's Validations nav item and
+its hand-crafted form, and the dangling reference-tracker row. Standalone rows
+already in `sys_metadata` are left alone — they were never evaluated, so nothing
+changes behaviorally.

content/docs/references/api/metadata.mdx

@@ -328,7 +328,7 @@ Metadata query with filtering, sorting, and pagination
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **types** | `Enum<'object' \| 'field' \| 'validation' \| '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'>[]` | optional | Filter by metadata types |
+| **types** | `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'>[]` | 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 |
@@ -363,7 +363,7 @@ Metadata query with filtering, sorting, and pagination
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `Enum<'object' \| 'field' \| 'validation' \| '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 |
+| **type** | `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` | ✅ | 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' \| 'validation' \| '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 |
+| **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 |
@@ -183,7 +183,7 @@ const result = MetadataBulkRegisterRequest.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **types** | `Enum<'object' \| 'field' \| 'validation' \| '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'>[]` | optional | Filter by metadata types |
+| **types** | `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'>[]` | 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 |
@@ -218,7 +218,6 @@ const result = MetadataBulkRegisterRequest.parse(data);
 
 * `object`
 * `field`
-* `validation`
 * `hook`
 * `seed`
 * `mapping`
@@ -252,7 +251,7 @@ const result = MetadataBulkRegisterRequest.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `Enum<'object' \| 'field' \| 'validation' \| '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 identifier |
+| **type** | `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 identifier |
 | **label** | `string` | ✅ | Display label for the metadata type |
 | **description** | `string` | optional | Description of the metadata type |
 | **filePatterns** | `string[]` | ✅ | Glob patterns to discover files of this type |

docs/adr/0088-metadata-kind-admission-and-retirement.md

@@ -54,3 +54,48 @@ The cached remote-schema snapshot of a federated datasource (ADR-0062) has a rea
 - `OPS_FILE_SUFFIX_REGEX` drops the four suffixes: `*.trigger.ts` / `*.router.ts` / `*.function.ts` / `*.service.ts` are no longer valid OPS metadata file names.
 - The showcase's registry-driven `KIND_COVERAGE` shrinks in lockstep (its coverage test enforces exact registry membership); the four waivers disappear and `external_catalog`'s waiver becomes a permanent, documented exclusion.
 - ADR-0005 / ADR-0010 prose tables no longer list the retired kinds.
+
+## Addendum (2026-08): `validation` retired — the admission test's first clause
+
+`validation` was registered as a kind with `allowRuntimeCreate: true`, a
+`*.validation.ts` loader, and a Studio form. On the admission test above it
+nonetheless fails the **first** clause — independent lifecycle — and the failure
+is not cosmetic:
+
+- **No independent lifecycle.** A rule only means something against an object,
+  and the only shape the engine evaluates is `object.validations[]`
+  (`evaluateValidationRules` on insert and on every matched update row).
+- **No way to bind.** `ValidationRuleSchema` carries no `object` / `objectName`
+  key, and all six variants are `strictObject`, so an author could not supply
+  one either — the parse would reject it. There was no merge step, and the only
+  code that expected such a key was a reference-tracker row scanning a field
+  that could never exist.
+
+So the standalone door led nowhere: an item authored through it — including a
+`state_machine` rule, which ADR-0020 explicitly routes through this same
+vocabulary — saved cleanly, reported success, and intercepted no write. That is
+the ADR-0049 false-compliance shape, on a surface authors reasonably expect to
+gate their data.
+
+The kind is removed (registry entry, `MetadataTypeSchema` member, metadata-core
+lockstep enum, schema map entry, Studio nav item and hand-crafted form, create
+seed, and the dangling reference row). `ValidationRuleSchema` itself is
+**unchanged and fully live** — it is the kind that was inert, not the
+vocabulary. The liveness ledger keeps governing the schema through the gate's
+`SPEC_ONLY_SCHEMAS` override, alongside `webhook` and `query`, precisely because
+an ungoverned live schema is how the next drift would hide.
+
+Note the contrast with the sibling disconnects closed in the same batch (#4509).
+`email_template` had a real feature with missing wiring, so enforce-or-remove
+resolved it by **enforcing** — a materializer bridge. `validation` had a shape
+that could not carry the feature at all, so it resolves by **removing**. The
+test is not "is this dead?" but "can this be made to work as declared?".
+
+- `MetadataTypeSchema` and `DEFAULT_METADATA_TYPE_REGISTRY` shrink 26 → 25.
+- `*.validation.ts` / `*.validation.yml` are no longer metadata file patterns.
+  (`OPS_FILE_SUFFIX_REGEX` never listed them — no change there.)
+- Persisted standalone `sys_metadata` rows are left alone. They were never
+  evaluated, so nothing changes behaviorally; `migrateStoredMetadata` declines
+  them like any unregistered type.
+- **Migration for authors:** move the rule into the object's `validations:`
+  array. The rule body is unchanged — same schema, same six variants.

examples/app-showcase/src/coverage.ts

@@ -54,24 +54,19 @@ export const KIND_COVERAGE: Record<MetadataType, KindCoverage> = {
   object: {
     status: 'demonstrated',
     files: ['src/data/objects/index.ts', 'src/data/objects/field-zoo.object.ts'],
+    notes:
+      'Also carries the validation-rule surface: rules are authored inline via object `validations` (the `validation` KIND was retired in #4509 — ADR-0088 — because a standalone rule had no way to name the object it validated). Every declared rule type is write-path enforced (rule-validator dispatches all of state_machine/script/cross_field/format/json_schema/conditional — ADR-0020 "no silent no-ops", closing the #1475 gap) and each is demonstrated: state_machine (task/project), script+cross_field (project), format/json_schema/conditional (account). Field-level requiredWhen/readonlyWhen are likewise enforced and demonstrated on invoice.',
   },
   field: {
     status: 'demonstrated',
     files: ['src/data/objects/field-zoo.object.ts'],
     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.',
   },
-  validation: {
-    status: 'demonstrated',
-    files: [
-      'src/data/objects/account.object.ts',
-      'src/data/objects/task.object.ts',
-      'src/data/objects/project.object.ts',
-      'src/data/objects/invoice.object.ts',
-    ],
-    notes:
-      'Authored inline via object `validations`. Every declared rule type is now write-path enforced (rule-validator dispatches all of state_machine/script/cross_field/format/json_schema/conditional — ADR-0020 "no silent no-ops", closing the #1475 gap) and each is demonstrated: state_machine (task/project), script+cross_field (project), format/json_schema/conditional (account). Field-level requiredWhen/readonlyWhen are likewise enforced and demonstrated on invoice.',
-  },
+  // `validation` was retired as a KIND in #4509 (ADR-0088) — the coverage test
+  // fails on any entry the registry no longer knows. The rules themselves are
+  // unchanged and still demonstrated; that coverage moved onto `object`, which
+  // is where they are authored.
   hook: { status: 'demonstrated', files: ['src/data/hooks/index.ts'] },
   seed: { status: 'demonstrated', files: ['src/data/seed/index.ts'] },
   mapping: {

packages/metadata-core/src/types.ts

@@ -19,7 +19,7 @@ import { z } from 'zod';
 export const MetadataTypeSchema = z.enum([
   'object',
   'field',
-  'validation',
+  // ADR-0088 (#4509): no `validation` kind — rules are inline `object.validations[]`.
   'hook',
   'mapping',
   'view',

packages/metadata-protocol/src/protocol.ts

@@ -261,74 +261,13 @@ const HAND_CRAFTED_SCHEMAS: Record<string, Record<string, unknown>> = {
         required: ['name', 'label', 'type'],
         additionalProperties: true,
     },
-    // Validation rules live inside `object.validations[]`. The canonical
-    // ValidationRuleSchema is a discriminated union of 6 variants; the
-    // generic SchemaForm renderer treats unions as opaque JSON, so we
-    // ship a *flat* form-friendly schema covering the common base
-    // properties plus every variant-specific field as optional. Save-time
-    // validation is unaffected — the union schema is still authoritative
-    // at write time.
-    validation: {
-        type: 'object',
-        properties: {
-            // --- Base fields (all variants) ---
-            name: { type: 'string', description: 'Unique rule name (snake_case)' },
-            label: { type: 'string' },
-            description: { type: 'string' },
-            type: {
-                type: 'string',
-                enum: [
-                    'script',
-                    'state_machine',
-                    'format',
-                    'cross_field',
-                    'json_schema',
-                    'conditional',
-                ],
-                default: 'script',
-                description: 'Validation variant',
-            },
-            active: { type: 'boolean', default: true },
-            events: {
-                type: 'array',
-                items: { type: 'string', enum: ['insert', 'update'] },
-                default: ['insert', 'update'],
-            },
-            priority: { type: 'number', default: 100, minimum: 0, maximum: 9999 },
-            severity: {
-                type: 'string',
-                enum: ['error', 'warning', 'info'],
-                default: 'error',
-            },
-            message: { type: 'string' },
-            tags: { type: 'array', items: { type: 'string' } },
-            // --- Variant-specific (all optional, gated by `type`) ---
-            condition: {
-                type: 'string',
-                description: 'CEL predicate (type=script). True ⇒ validation fails.',
-            },
-            fields: {
-                type: 'array',
-                items: { type: 'string' },
-                description: 'Fields (type=cross_field).',
-            },
-            field: { type: 'string', description: 'Single field (type=state_machine / format).' },
-            transitions: {
-                type: 'object',
-                additionalProperties: { type: 'array', items: { type: 'string' } },
-                description: 'Map { OldState: [AllowedNewStates] } (type=state_machine).',
-            },
-            regex: { type: 'string', description: 'Regex (type=format).' },
-            format: {
-                type: 'string',
-                enum: ['email', 'url', 'phone', 'json'],
-                description: 'Built-in format (type=format).',
-            },
-            when: { type: 'string', description: 'Outer condition (type=conditional).' },
-        },
-        required: ['name', 'type', 'message'],
-        additionalProperties: true,
-    },
+    // ADR-0088 (#4509): the `validation` kind is retired, so its hand-crafted
+    // form goes with it. Rules are authored inside `object.validations[]` and
+    // edited on the object; there is no standalone validation editor to render
+    // a schema for. (The form was flat by necessity — ValidationRuleSchema is a
+    // 6-variant discriminated union the generic SchemaForm treats as opaque —
+    // and it had no field for the object being validated, which is precisely
+    // the gap that retired the kind: a rule saved here bound to nothing.)
 };
 
 /**
@@ -1374,7 +1313,11 @@ const REFERENCE_PATHS: Record<string, Array<{ fromType: string; paths: string[];
         { fromType: 'page', paths: ['object', 'objectName'], kind: 'page' },
         { fromType: 'report', paths: ['object', 'objectName'], kind: 'report' },
         { fromType: 'action', paths: ['object', 'objectName'], kind: 'action' },
-        { fromType: 'validation', paths: ['object', 'objectName'], kind: 'validation' },
+        // fromType 'validation' removed (#4509): it scanned `object`/`objectName`
+        // on a schema that has neither — every variant is strict, so parse would
+        // have stripped such a key anyway — and the kind is now retired
+        // (ADR-0088). Rules travel with their object, so a rule's dependency on
+        // that object needs no row: deleting the object takes them with it.
         { fromType: 'hook', paths: ['object', 'objectName'], kind: 'hook' },
         { fromType: 'object', paths: ['fields[].referenceTo', 'fields{}.referenceTo', 'fields{}.reference'], kind: 'field reference' },
     ],