fix(spec): validate theme / analytics_cube at the /meta write door via UNREGISTERED_KIND_SCHEMAS (#10194) (#10440)

* fix(spec): bind theme / analytics_cube in UNREGISTERED_KIND_SCHEMAS (#10194)

Same SHAPE-check-only treatment #6245 gave webhook/connector/sharing_rule:
no MetadataTypeSchema member, no DEFAULT_METADATA_TYPE_REGISTRY entry, no
capability or authorization change — only a 422 where PUT /meta/theme/:name
and PUT /meta/analytics_cube/:name currently store any JSON as success:true.

Both schemas gain ...MetadataProtectionFields (the sharing_rule precedent:
strict schemas at the overlay door must declare the ADR-0010 stamp or 422
the runtime's own envelope). The map's closing invariant (entry === the
stack collection's element schema) is now pinned for all five entries.

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

* test: mirror the #6245 house pins for theme / analytics_cube; changeset (#10194)

- protocol-meta.test.ts: valid+invalid pair per new kind; the schema-less
  fall-through control specimen moves theme -> rag_pipeline (the webhook
  precedent: the old specimen body is spec-INVALID and now 422s, and
  rag_pipeline is the only URL-map kind left that resolves no schema).
- metadata-protocol fixtures: theme probe bodies made spec-valid (the door
  under test is authorization/advertisement, not the shape check).
- changeset: minor @objectstack/spec, following #6245's landed grading.

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

* test(runtime): spec-valid theme probe bodies in the two door-under-test controls (#10194)

Same fixture-triage class as the metadata-protocol/objectql sites: these
controls measure the arity door and the #7894 permission verdict, not the
shape check, so their probe bodies must parse under ThemeSchema now that
theme resolves a schema through UNREGISTERED_KIND_SCHEMAS. Repo-wide sweep
(type-keyed and URL-path spellings, theme + analytics_cube) finds no other
site in this class.

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

---------

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

Author: Jack Q

.changeset/meta-bind-theme-analytics-cube.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/spec": minor
+---
+
+fix(spec): `theme` / `analytics_cube` are validated at the `/meta` write door (#10194)
+
+The two doors #6245 left open, closed the same way. Both are declared,
+authorable stack collections with real `.strict()` schemas —
+`defineStack({ themes })` validates with `ThemeSchema`,
+`defineStack({ analyticsCubes })` with `CubeSchema` — yet neither was bound in
+`UNREGISTERED_KIND_SCHEMAS`, so `getMetadataTypeSchema()` answered `undefined`
+and `saveMetaItem` took its documented "unregistered type → store without
+validation" branch: a body the stack door strictly refuses was stored,
+unvalidated and badged `success: true`, through the metadata door. For `theme`
+that is the console's own styling surface — a malformed one failed at render
+rather than at write, with nothing at the write point to say so.
+
+**FROM** `PUT /meta/theme/:name` / `PUT /meta/analytics_cube/:name` with any
+JSON → `200 { success: true }`, stored unvalidated.
+**TO** a malformed body → `422 INVALID_METADATA` with structured `issues[]`,
+the same envelope every other kind already returned. A well-formed body is
+accepted exactly as before.
+
+Each entry binds the **same schema its stack collection is validated against**
+(`ThemeSchema` at `stack.zod.ts` `themes:`, `CubeSchema` at `analyticsCubes:`),
+and that closing invariant is now pinned by identity for all five map entries.
+
+**No new capability surface.** Shape validation only: no `MetadataTypeSchema`
+member, no `DEFAULT_METADATA_TYPE_REGISTRY` entry, so every authorization
+verdict keeps taking the identical "no static entry ⇒ synthesised
+`allowRuntimeCreate: true`" branch. The write *door* is unchanged; only the
+422 is new. #2657's B/C decision on whether these should become kinds is
+untouched and unprejudged. `rag_pipeline` is deliberately not bound — it has
+no stack collection to take a schema from (#6242 row 2).
+
+Graded **minor**, following #6245's landed precedent for the identical change
+(itself following #5271): a write that previously returned 200 can now return
+422. Nothing well-formed changes behaviour, but a caller relying on the API
+accepting malformed bodies will see the difference.
+
+**One schema change rides along per kind, and it is load-bearing.**
+`Theme` and `Cube` now declare the ADR-0010 protection envelope (`_lock`,
+`_lockReason`, `_lockSource`, `_lockDocsUrl`, `_packageId`, `_packageVersion`,
+`_provenance`) — the sharing_rule precedent from #6245: both metadata load
+paths call `applyProtection` on **every** type, and these shapes are
+`.strict()`, so binding the door without the spread would have aimed the new
+422 at the runtime's own stamp instead of at malformed author input. Additive
+and internal-only — no authored field changes.

content/docs/references/data/analytics.mdx

@@ -80,6 +80,13 @@ const result = AggregationMetricType.parse(data);
 | **joins** | `Record<string, { name: string; relationship: Enum<'one_to_one' \| 'one_to_many' \| 'many_to_one'>; sql: string }>` | optional |  |
 | **refreshKey** | `{ every?: string; sql?: string }` | optional |  |
 | **public** | `boolean` | optional (default: `false`) |  |
+| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
+| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
+| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). |
+| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package \| org \| env-forced). |
+| **_packageId** | `string` | optional | Owning package machine id. |
+| **_packageVersion** | `string` | optional | Owning package version. |
+| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
 
 
 ---

content/docs/references/ui/theme.mdx

@@ -105,6 +105,13 @@ const result = BorderRadiusSchema.parse(data);
 | **zIndex** | `never` | optional | [REMOVED] `theme.zIndex` was removed in @objectstack/spec 17.0.0 (#5021, ADR-0049 D2) — the engine emitted `--z-base` … `--z-tooltip` and nothing read one, so an overlay you "lifted" still stacked by document order. Delete the key; if your own CSS reads those variables, declare them under `customVars` (`{ "z-modal": "1050" }` emits exactly the same `--z-modal`). Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand. |
 | **customVars** | `Record<string, string>` | optional | Custom CSS variables (key-value pairs) |
 | **extends** | `string` | optional | Base theme to extend from |
+| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
+| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
+| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). |
+| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package \| org \| env-forced). |
+| **_packageId** | `string` | optional | Owning package machine id. |
+| **_packageVersion** | `string` | optional | Owning package version. |
+| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
 
 
 ---

packages/metadata-protocol/src/protocol.code-only-types.test.ts

@@ -396,10 +396,14 @@ describe('code-only metadata types are refused on every kernel (#5086)', () => {
             // `getMetaTypes()` synthesises those with allowRuntimeCreate:true;
             // the write gate must keep agreeing with what it advertises.
             const { protocol, rows } = makeProtocol(undefined);
+            // [#10194] `theme` resolves a schema through UNREGISTERED_KIND_SCHEMAS
+            // now, so the probe body must be spec-valid — the door under test
+            // (authorization) is unchanged, but a malformed body would 422
+            // before proving anything about it.
             const result = await protocol.saveMetaItem({
                 type: 'theme',
                 name: 'rc3_probe_theme',
-                item: { name: 'rc3_probe_theme', label: 'Probe', tokens: {} },
+                item: { name: 'rc3_probe_theme', label: 'Probe', colors: { primary: '#3b82f6' } },
             });
             expect(result.success).toBe(true);
             expect(metaRows(rows).length).toBe(1);
@@ -493,7 +497,8 @@ describe('code-only metadata types are refused on every kernel (#5086)', () => {
             },
             {
                 type: 'theme', // no static registry entry (plugin-registered)
-                item: { name: 'rc3_receipt_view', label: 'Receipt', tokens: {} },
+                // [#10194] spec-valid body — theme resolves a schema now.
+                item: { name: 'rc3_receipt_view', label: 'Receipt', colors: { primary: '#3b82f6' } },
             },
         ];
 

packages/metadata-protocol/src/protocol.meta-types-mint-door-agreement.test.ts

@@ -155,7 +155,11 @@ const SAMPLE: Array<{
         type: 'theme',
         klass: 'url-map-only',
         creatable: true,
-        item: { name: 'probe_theme', label: 'Probe', tokens: {} },
+        // [#10194] spec-valid body — `theme` resolves a schema through
+        // UNREGISTERED_KIND_SCHEMAS now, and the "behaves as advertised" case
+        // drives this body through a real write, so a malformed one would
+        // 422 and misread the ADVERTISEMENT door this suite measures.
+        item: { name: 'probe_theme', label: 'Probe', colors: { primary: '#3b82f6' } },
     },
     { type: 'policy', klass: 'withdrawn', creatable: false, item: { name: 'probe_policy', label: 'Probe' } },
     { type: 'data', klass: 'withdrawn', creatable: false, item: { name: 'probe_data', label: 'Probe' } },

packages/metadata-protocol/src/protocol.unrecognised-meta-type.test.ts

@@ -203,7 +203,8 @@ describe('#8421 — the traffic that must keep working', () => {
         {
             type: 'theme',
             why: 'PLUGIN kind — no static registry entry at all',
-            item: { name: 'probe_item', label: 'Probe', tokens: {} },
+            // [#10194] spec-valid body — theme resolves a schema now.
+            item: { name: 'probe_item', label: 'Probe', colors: { primary: '#3b82f6' } },
         },
     ];
 
@@ -224,10 +225,12 @@ describe('#8421 — the traffic that must keep working', () => {
         // consults the static contract instead, so the first create of a
         // plugin kind is untouched.
         const { protocol, rows } = makeProtocol();
+        // [#10194] spec-valid body — theme resolves a schema now, and this
+        // control measures the STATIC-contract door, not the shape check.
         const result = await protocol.saveMetaItem({
             type: 'theme',
             name: 'dark',
-            item: { name: 'dark', label: 'Dark', tokens: {} },
+            item: { name: 'dark', label: 'Dark', colors: { primary: '#3b82f6' } },
         });
         expect(result.success).toBe(true);
         expect(metaRows(rows)[0]!.type).toBe('theme');

packages/objectql/src/metadata-validation-sweep.test.ts

@@ -13,8 +13,10 @@
  *   2. A deliberately broken payload (missing required field) →
  *      expect `invalid_metadata` + status 422 + structured `issues[]`.
  *
- * Types without a Zod schema in the central registry (plugin-only types like
- * `theme`/`webhook`) are still expected to pass through unvalidated — that is
+ * Types without a Zod schema in the central registry (today only
+ * `rag_pipeline` among the URL-map kinds — `theme`/`webhook` and their
+ * siblings all resolve schemas via `UNREGISTERED_KIND_SCHEMAS` since
+ * #6245/#10194) are still expected to pass through unvalidated — that is
  * the documented fall-through, not a regression. We pin it explicitly so any
  * future coverage gap is visible in the report.
  *

packages/objectql/src/protocol-meta.test.ts

@@ -1544,22 +1544,30 @@ describe('ObjectStackProtocolImplementation - Metadata Persistence', () => {
         // old specimen: its body (`events`, an alias of `triggers`, plus the
         // non-enum trigger `'x.created'`) is spec-INVALID and now 422s. Kept
         // here it would have flipped this test red for a reason that has
-        // nothing to do with what it proves. `theme` and `policy` still carry
-        // the branch — neither resolves a schema. Each newly-bound type's own
+        // nothing to do with what it proves.
+        //
+        // [#10194] `theme` left it by exactly the webhook rule: it gained a
+        // SCHEMA (not a registry entry), and the old specimen body
+        // (`tokens: {}` — an alias of `customVars`, with the required `colors`
+        // missing) is spec-INVALID and now 422s. `analytics_cube` was bound in
+        // the same change. Of the six URL-map-only kinds, `rag_pipeline` is
+        // now the ONLY one that resolves no schema (it has no stack collection
+        // to take one from — #6242 row 2), so it carries the pure
+        // no-schema fall-through control below. Each newly-bound type's own
         // behaviour, door and 422 both, is pinned in the tests below.
         // ───────────────────────────────────────────────────────────────
 
         it('accepts brand-new plugin-registered type (no static registry entry)', async () => {
             mockEngine.findOne.mockResolvedValue(null);
 
-            const themeResult = await scoped.saveMetaItem({
-                type: 'theme',
-                name: 'my_theme',
-                item: { name: 'my_theme', label: 'Test', tokens: {} },
+            const result = await scoped.saveMetaItem({
+                type: 'rag_pipeline',
+                name: 'my_pipeline',
+                item: { name: 'my_pipeline', label: 'Test' },
                 organizationId: 'org_alpha',
             });
 
-            expect(themeResult.success).toBe(true);
+            expect(result.success).toBe(true);
         });
 
         it('[#8421] CHANGED BEHAVIOUR — `policy` is no longer one of them', async () => {
@@ -1739,6 +1747,91 @@ describe('ObjectStackProtocolImplementation - Metadata Persistence', () => {
             });
         });
 
+        // ───────────────────────────────────────────────────────────────
+        // [#10194] `theme` / `analytics_cube` — the two doors #6245 left
+        // open, closed the same way and pinned the same way: the write door
+        // is UNCHANGED (no-static-entry authorization fall-through, verdict
+        // byte-identical), the shape check is new. Both halves per type, so a
+        // change that quietly CLOSED the door fails the "accepts" half.
+        // ───────────────────────────────────────────────────────────────
+
+        it('accepts a spec-valid `theme` item (write door unchanged by the schema binding)', async () => {
+            mockEngine.findOne.mockResolvedValue(null);
+
+            const result = await scoped.saveMetaItem({
+                type: 'theme',
+                name: 'my_theme',
+                item: {
+                    name: 'my_theme',
+                    label: 'My Theme',
+                    colors: { primary: '#3b82f6' },
+                },
+                organizationId: 'org_alpha',
+            });
+
+            expect(result.success).toBe(true);
+        });
+
+        it('refuses a spec-INVALID `theme` item with 422 instead of storing it unvalidated', async () => {
+            mockEngine.findOne.mockResolvedValue(null);
+
+            // The exact body the old "plugin-registered types" case above used
+            // to save with `success: true`: `tokens` is an ALIAS of
+            // `customVars` (so the strict surface names the real key), and the
+            // required `colors` block is missing. Stored verbatim, this is the
+            // theme that fails at RENDER — the console's own styling surface —
+            // with nothing at the write point to say so.
+            await expect(
+                scoped.saveMetaItem({
+                    type: 'theme',
+                    name: 'my_theme',
+                    item: { name: 'my_theme', label: 'Test', tokens: {} },
+                    organizationId: 'org_alpha',
+                }),
+            ).rejects.toMatchObject({
+                code: 'INVALID_METADATA',
+                status: 422,
+            });
+        });
+
+        it('accepts a spec-valid `analytics_cube` item (write door unchanged by the schema binding)', async () => {
+            mockEngine.findOne.mockResolvedValue(null);
+
+            const result = await scoped.saveMetaItem({
+                type: 'analytics_cube',
+                name: 'orders',
+                item: {
+                    name: 'orders',
+                    sql: 'orders',
+                    measures: { count: { name: 'count', label: 'Count', type: 'count', sql: '*' } },
+                    dimensions: { stage: { name: 'stage', label: 'Stage', type: 'string', sql: 'stage' } },
+                },
+                organizationId: 'org_alpha',
+            });
+
+            expect(result.success).toBe(true);
+        });
+
+        it('refuses a spec-INVALID `analytics_cube` item with 422 instead of storing it unvalidated', async () => {
+            mockEngine.findOne.mockResolvedValue(null);
+
+            // `table` is an ALIAS of `sql`, and the required `measures` /
+            // `dimensions` records are missing — the same body `defineStack({
+            // analyticsCubes })` strictly refuses. Stored verbatim, this cube
+            // registers as a semantic layer with no semantics.
+            await expect(
+                scoped.saveMetaItem({
+                    type: 'analytics_cube',
+                    name: 'orders',
+                    item: { name: 'orders', table: 'orders' },
+                    organizationId: 'org_alpha',
+                }),
+            ).rejects.toMatchObject({
+                code: 'INVALID_METADATA',
+                status: 422,
+            });
+        });
+
         // ───────────────────────────────────────────────────────────────
         // [#5488, overturning #5271's pins] `api` — the write door is now
         // CLOSED, and it closes in front of the shape check.

packages/runtime/src/meta-compound-arity-mint-door.test.ts

@@ -254,8 +254,12 @@ describe('#8421 — the compound `/meta` arity is not a metadata-type claim', ()
     it('CONTROL — a recognised type at the simple arity is unaffected', async () => {
         const { engine, dispatcher } = makeStack();
 
+        // [#10194] spec-valid body — `theme` resolves a schema through
+        // UNREGISTERED_KIND_SCHEMAS now, and this control measures the ARITY
+        // door, so a malformed body would 422 and misread it.
         const res = responseOf(await dispatcher.handleMetadata(
-            '/theme/midnight', ctx(), 'PUT', { name: 'midnight', label: 'Midnight' },
+            '/theme/midnight', ctx(), 'PUT',
+            { name: 'midnight', label: 'Midnight', colors: { primary: '#3b82f6' } },
         ));
 
         expect(res.status).toBe(200);

packages/runtime/src/meta-field-overlay-lock.test.ts

@@ -697,16 +697,21 @@ describe('#7743 — PUT /meta/field/<object>.<field> honours the registry overla
         const { engine, dispatcher } = makeStack();
 
         // `theme` has no `DEFAULT_METADATA_TYPE_REGISTRY` entry at all.
+        // [#10194] spec-valid bodies — `theme` resolves a schema through
+        // UNREGISTERED_KIND_SCHEMAS now, and this control measures the #7894
+        // PERMISSION verdict, so a malformed body would 422 and misread it.
         const singular = responseOf(await dispatcher.handleMetadata(
-            '/theme/midnight', ctx(), 'PUT', { name: 'midnight', label: 'Midnight' },
+            '/theme/midnight', ctx(), 'PUT',
+            { name: 'midnight', label: 'Midnight', colors: { primary: '#3b82f6' } },
         ));
         expect(singular.status).toBe(200);
         expect(metaRow(engine, 'theme', 'midnight')).toBeDefined();
 
         // …and via its plural spelling, which the URL map carries from the
         // manifest map's limb — still one namespace, the singular one.
         const plural = responseOf(await dispatcher.handleMetadata(
-            '/themes/twilight', ctx(), 'PUT', { name: 'twilight', label: 'Twilight' },
+            '/themes/twilight', ctx(), 'PUT',
+            { name: 'twilight', label: 'Twilight', colors: { primary: '#3b82f6' } },
         ));
         expect(plural.status).toBe(200);
         expect(metaRow(engine, 'theme', 'twilight')).toBeDefined();