@@ -0,0 +1,27 @@
+---
+'@objectstack/objectql': patch
+---
+
+fix(objectql)!: a code package's action is stored as its `ActionSchema` parse, so `requiresFeature` takes effect on bound actions
+
+Clause-②: no (narrowing) — `SchemaRegistry.registerItem`, and with it `ObjectQL.registerApp` and every door that registers a code package's items, now refuses with `422 INVALID_METADATA` an `action` body that does not satisfy `ActionSchema`. Before, it registered that body as written. Nothing is widened.
+
+Metadata-protocol: none (`ActionSchema` is unchanged and no key is added, retired or re-shaped; every body the registry now refuses already fails the same schema at `defineStack`, `os validate` and the metadata save door)
+
+<!-- adr-0087: not-required (no-migration-prescription) No metadata moves: `ActionSchema` is byte-unchanged, and no spec key, authorable spelling, stored row or stored shape is added, removed, renamed or re-shaped, so there is nothing for `objectstack migrate meta` to rewrite and no old-to-new mapping to record. What changes is one runtime door converging on the existing contract: the schema registry now stores a code package's action as its parse and refuses one that does not parse. Every body it refuses was already off-contract, and refused by the authoring doors, before this change. The remedy is a correction of that body against the issues the refusal lists, not a conversion between two contract versions. The other categories are closed on facts: the package publishes (not unpublished); no ADR-0087 id is named or touched (not registered or already-registered); and nothing exported is removed or narrowed (not runtime-interface-only, type-surface-only or runtime-export-retired). -->
+
+The schema registry now parses every `action` item a code package registers through `ActionSchema` before storing it. The stored item is the parsed body. Before this, an action that reached the registry without a parse was stored as authored. Examples are a programmatic `registerApp`, a nested plugin's manifest, a `strict: false` stack, and a raw plugin manifest. Such an action was then attached to its target object unparsed. Its `requiresFeature` (and `requiresMembershipReach`) was never lowered into `visible`, so the declared gate did nothing. A platform object's own actions were already lowered.
+
+What the parse does to such an action, as with any parsed action:
+
+- it lowers `requiresFeature` / `requiresMembershipReach` into `visible`;
+- it fills schema defaults;
+- it wraps a CEL string shorthand in `{ dialect, source }`.
+
+An action a strict `defineStack` already parsed is stored unchanged.
+
+**BREAKING** for a package that registers an action body `ActionSchema` does not accept.
+
+- **Before.** The registry stored such a body as written, and served it with any declared gate inert.
+- **Now.** Registration is refused with `INVALID_METADATA` (422). The error names the action and its package, and `issues[]` gives the path and message of each failure. The registration that carried it fails.
+- **Fix.** Correct the action as `issues[]` describes. An action that passes `os validate`, or a strict `defineStack`, is unaffected.
@@ -18,18 +18,23 @@
 import { describe, it, expect, afterEach, vi } from 'vitest';
 import { ObjectKernel, type PluginContext } from '@objectstack/core';
 import { defineStack } from '@objectstack/spec';
+import { ObjectSchema } from '@objectstack/spec/data';
 import { ObjectQL } from './engine.js';
 import { ObjectQLPlugin } from './plugin.js';
 import { FIND_BOUND_ACTION_COLLISIONS, SchemaRegistry } from './registry.js';
 
-/** The package that OWNS the target object, with an action of its own. */
+/**
+ * The package that OWNS the target object, with an action of its own — authored
+ * as an object is (`ObjectSchema.create`), so its action is the parse of what
+ * was written, as a bound action's registered copy is (#25649).
+ */
 const OWNER = {
     id: 'com.test.owner', name: 'owner',
-    objects: [{
+    objects: [ObjectSchema.create({
         name: 'bc_org', label: 'Org',
         fields: { name: { name: 'name', type: 'text', label: 'Name' } },
         actions: [{ name: 'rename', label: 'Rename', type: 'url', target: 'https://example.com/own', locations: ['record_header'] }],
-    }],
+    } as any)],
 };
 
 /** Another package binding an action of the same NAME to the owner's object — a different declaration. */
@@ -41,7 +46,7 @@ const TWIN = {
 /** Another package carrying the owner's declaration itself, bound by `objectName` — one declaration, two packages. */
 const CARRIER = {
     id: 'com.test.carrier', name: 'carrier',
-    actions: [{ ...OWNER.objects[0].actions[0], objectName: 'bc_org' }],
+    actions: [{ ...OWNER.objects[0].actions![0], objectName: 'bc_org' }],
 };
 
 /** A package that brings an unrelated object — the late-artifact control. */
 
@@ -20,6 +20,7 @@ import { describe, it, expect, afterEach } from 'vitest';
 import { ObjectKernel, type PluginContext } from '@objectstack/core';
 import { ObjectStackProtocolImplementation } from '@objectstack/metadata-protocol';
 import { defineStack } from '@objectstack/spec';
+import { ObjectSchema } from '@objectstack/spec/data';
 import { ObjectQL } from './engine.js';
 import { ObjectQLPlugin } from './plugin.js';
 import { describeUnboundActionTargets } from './registry.js';
@@ -351,3 +352,80 @@ describe('the bound-action boot audit', () => {
         expect(err?.message).toContain("action 'b' (a registration with no package) is bound to object 'y'");
     });
 });
+
+// ── The parse a bound action is stored as ─────────────────────────────────
+
+/**
+ * [#25649] A package's bound action is stored as its `ActionSchema` parse, so
+ * a declared `requiresFeature` is lowered into `visible` exactly as on a
+ * platform object's own action (`ObjectSchema.create` parses those where they
+ * are authored). Before, the registry stored the item as the package wrote it:
+ * served with `requiresFeature` riding along raw and its `visible` the bare
+ * predicate — a feature gate no reader enforces.
+ */
+describe('a bound action is served as its ActionSchema parse', () => {
+    /** One declaration, carried both by the owner's object and by a binder package. */
+    const GATED = {
+        label: 'Change slug', type: 'url' as const, target: 'https://example.com/slug',
+        locations: ['record_header' as const], visible: "record.name != ''",
+        requiresFeature: 'multiOrgEnabled' as const,
+    };
+    const LOWERED = { dialect: 'cel', source: "(record.name != '') && features.multiOrgEnabled != false" };
+
+    /** The owner's object as a platform object is authored: parsed by `ObjectSchema.create`. */
+    const platformOwner = () => ({
+        id: 'com.test.owner', name: 'owner',
+        objects: [ObjectSchema.create({
+            name: 'ba_org', label: 'Org',
+            fields: { name: { name: 'name', type: 'text', label: 'Name' } },
+            actions: [{ name: 'own_gated', ...GATED }],
+        } as any)],
+    });
+    const gatedBinder = (action: Record<string, unknown>) => ({ id: 'com.test.binder', name: 'binder', actions: [action] });
+    const servedAction = async (protocol: ObjectStackProtocolImplementation, name: string) => {
+        const served: any = await protocol.getMetaItem({ type: 'object', name: 'ba_org' } as any);
+        return (served.item.actions as any[]).find((a) => a?.name === name);
+    };
+
+    it('GET /meta/object/<target> serves the bound action with `requiresFeature` lowered into `visible`', async () => {
+        const { engine, protocol } = await hostWith([platformOwner(), gatedBinder({ name: 'change_slug', objectName: 'ba_org', ...GATED })]);
+        const bound = await servedAction(protocol, 'change_slug');
+        expect(bound.visible).toEqual(LOWERED);
+        expect(bound).not.toHaveProperty('requiresFeature');
+        // The same lowering the platform object's own action, of the same declaration, is served with.
+        expect(bound.visible).toEqual((await servedAction(protocol, 'own_gated')).visible);
+        // One parsed body: the attachment is the very item the router's rung 2 resolves.
+        expect(engine.registry.getObject('ba_org')?.actions?.find((a: any) => a.name === 'change_slug'))
+            .toBe(engine.registry.getItem('action', 'change_slug'));
+    });
+
+    it('a bound action with no `visible` of its own is served the gate alone', async () => {
+        const { requiresFeature, label, type, target, locations } = GATED;
+        const { protocol } = await hostWith([platformOwner(), gatedBinder({ name: 'change_slug', objectName: 'ba_org', label, type, target, locations, requiresFeature })]);
+        const bound = await servedAction(protocol, 'change_slug');
+        expect(bound.visible).toEqual({ dialect: 'cel', source: 'features.multiOrgEnabled != false' });
+        expect(bound).not.toHaveProperty('requiresFeature');
+    });
+
+    it('control: the platform object\'s own action is served as `ObjectSchema.create` produced it', async () => {
+        const owner = platformOwner();
+        const authored = structuredClone(owner.objects[0].actions!.find((a: any) => a.name === 'own_gated'))!;
+        const { protocol } = await hostWith([owner, gatedBinder({ name: 'change_slug', objectName: 'ba_org', ...GATED })]);
+        expect(await servedAction(protocol, 'own_gated')).toEqual(authored);
+        expect(authored.visible).toEqual(LOWERED);
+    });
+
+    it('a bound action that does not parse is refused loudly, naming the action and its package — never stored', async () => {
+        const host = await hostWith([platformOwner()]);
+        const err: any = (() => {
+            try { host.engine.registerApp(gatedBinder({ name: 'change_slug', objectName: 'ba_org', ...GATED, visible: false })); }
+            catch (e) { return e; }
+            return undefined;
+        })();
+        expect(err).toMatchObject({ code: 'INVALID_METADATA', status: 422 });
+        expect(err.message).toContain("Action 'change_slug' of package 'com.test.binder' does not satisfy the action contract");
+        expect(err.issues).toEqual(expect.arrayContaining([expect.objectContaining({ path: 'requiresFeature' })]));
+        expect(host.engine.registry.getItem('action', 'change_slug')).toBeUndefined();
+        expect(actionNames(host.engine.registry.getObject('ba_org'))).toEqual(['own_gated']);
+    });
+});
@@ -196,7 +196,11 @@ describe('the two registration seams enumerate ONE collection list (#7049)', ()
 
   it.each(CANDIDATES)('registers `%s` identically from a manifest and from a nested plugin', (plural) => {
     const singular = pluralToSingular(plural);
-    const item = { name: `probe_${plural}`, label: `Probe ${plural}` };
+    // [#25649] An action is stored as its `ActionSchema` parse, so the probe
+    // carries the one thing a `script` default needs beyond a name and label.
+    const item = plural === 'actions'
+        ? { name: `probe_${plural}`, label: `Probe ${plural}`, type: 'url', target: 'https://example.com/probe' }
+        : { name: `probe_${plural}`, label: `Probe ${plural}` };
 
     const direct = new ObjectQL();
     direct.registerApp({ id: PKG, name: 'billing', [plural]: [item] });
 
@@ -235,7 +235,12 @@ async function seed(protocol: any, registry: SchemaRegistry) {
     // [#24210] One item of every declared type, as a code package ships it:
     // the registry layer, stamped with the package that registered it.
     for (const type of BY_NAME_TYPES) {
-      registry.registerItem(type, { name: shippedName(type, pkg), label: 'Shipped' } as any, 'name', pkg);
+      // [#25649] A package's action is stored as its `ActionSchema` parse, so it
+      // is shipped as a declaration that parses.
+      const body = type === 'action'
+        ? { name: shippedName(type, pkg), label: 'Shipped', type: 'url', target: 'https://example.com/shipped' }
+        : { name: shippedName(type, pkg), label: 'Shipped' };
+      registry.registerItem(type, body as any, 'name', pkg);
     }
   }
 }
 
@@ -73,7 +73,7 @@ describe('registry path stamps the package version it is handed', () => {
     const ql = new ObjectQL();
     ql.registerApp({
       ...manifest('2.0.0'),
-      actions: [{ name: 'hc_convert', label: 'Convert', type: 'script' }],
+      actions: [{ name: 'hc_convert', label: 'Convert', type: 'script', target: 'hc_convert_lead' }],
       plugins: [{ name: 'hc_notes', objects: [{ name: 'hc_note', label: 'Note', sharingModel: 'private', fields: { body: { name: 'body', type: 'text', label: 'Body' } } }] }],
     });
 
 
@@ -453,19 +453,21 @@ describe('SchemaRegistry', () => {
     // Generic Metadata Tests (Non-Object)
     // ==========================================
     describe('Generic Metadata', () => {
+        // [#25649] `report`, not `action`: a package's action is no longer a
+        // generic item — it is stored as its `ActionSchema` parse.
         it('should register and retrieve generic items', () => {
-            const item = { name: 'test_action', type: 'custom' };
-            registry.registerItem('action', item, 'name', 'com.pkg');
+            const item = { name: 'test_report', type: 'custom' };
+            registry.registerItem('report', item, 'name', 'com.pkg');
 
-            const retrieved = registry.getItem('action', 'test_action');
+            const retrieved = registry.getItem('report', 'test_report');
             expect(retrieved).toEqual(item);
         });
 
         it('should list items by type with package filter', () => {
-            registry.registerItem('action', { name: 'a1' }, 'name', 'com.pkg1');
-            registry.registerItem('action', { name: 'a2' }, 'name', 'com.pkg2');
+            registry.registerItem('report', { name: 'a1' }, 'name', 'com.pkg1');
+            registry.registerItem('report', { name: 'a2' }, 'name', 'com.pkg2');
 
-            const filtered = registry.listItems('action', 'com.pkg1');
+            const filtered = registry.listItems('report', 'com.pkg1');
             expect(filtered).toHaveLength(1);
         });
     });
 
@@ -47,7 +47,7 @@ import { postureEnforcesWall } from '@objectstack/spec/security';
 import { provisionSearchCompanion, SEARCH_COMPANION_FIELD } from './search-companion.js';
 import { ObjectStackManifest, ManifestSchema, InstalledPackage, InstalledPackageSchema, InstalledPackageSourceSchema, type InstalledPackageSource, checkFieldCompleteness } from '@objectstack/spec/kernel';
 import { DEFAULT_FLOW_FUNCTION_EFFECT } from '@objectstack/spec/automation';
-import { AppSchema } from '@objectstack/spec/ui';
+import { AppSchema, ActionSchema } from '@objectstack/spec/ui';
 import { applyProtection } from '@objectstack/spec/shared';
 // [ADR-0130 D1] The ONE derivation of the key a package is installed under
 // (`id || name`). The install gate's co-ownership set must name packages by the
@@ -153,6 +153,71 @@ export function describeUnboundActionTargets(
   return err;
 }
 
+/**
+ * [#25649] The refusal of a code package's `action` that does not satisfy
+ * `ActionSchema` — the `INVALID_METADATA` envelope (ADR-0112) the unbound-target
+ * refusal above answers, with `issues[]` locating each failure.
+ */
+interface PackageActionSchemaError extends Error {
+  code: 'INVALID_METADATA';
+  status: 422;
+  httpStatus: 422;
+  issues: Array<{ path: string; message: string; code: string }>;
+}
+
+/**
+ * [#25649] A code package's `action` item, as its `ActionSchema` parse — the
+ * body {@link SchemaRegistry.registerItem} stores — or the loud refusal of one
+ * that does not parse.
+ *
+ * Why the stored item has to BE the parse: `ActionSchema` is not only a judge,
+ * it is a producer. Its transform lowers `requiresMembershipReach` and
+ * `requiresFeature` into the CEL `visible` predicate and deletes the two keys,
+ * and nothing downstream reads either key raw — so an action stored as authored
+ * carries both gates declared and inert. A platform object's actions are parsed
+ * where they are authored (`ObjectSchema.create`), and a strict `defineStack`
+ * parses a stack's actions; a programmatic `registerApp`, a nested plugin's
+ * manifest, a `strict: false` stack or a raw plugin manifest reached this store
+ * with no parse at all, and {@link SchemaRegistry.attachBoundActions} served
+ * what it found. Parsing at this seam, once, means every reader — the bound
+ * attachment, the router's rung 2, `GET /meta/action` — holds the one parsed
+ * body, by reference.
+ *
+ * The parse is idempotent over its own output (a lowered action carries no
+ * `requiresFeature` left to lower), so an action a strict `defineStack` already
+ * parsed is stored deep-equal to what it arrived as. Besides the lowering, the
+ * parse fills the schema's defaults (`type`, `refreshAfter`, …), turns a
+ * CEL-string shorthand into its `{ dialect, source }` envelope, and refuses an
+ * undeclared key; the ADR-0010 envelope (`_packageId`, `_packageVersion`,
+ * `_provenance`, `_lock`) is declared on the schema and passes through.
+ *
+ * Refused rather than stored unparsed: an action that fails the parse would be
+ * served with whatever gates it declares never taking effect, and `defineStack`
+ * and `os validate` refuse the same declaration at authoring time.
+ */
+function parsePackageAction(item: unknown, name: string, packageId: string): unknown {
+  const parsed = ActionSchema.safeParse(item);
+  if (parsed.success) return parsed.data;
+  const issues = parsed.error.issues.map((issue) => ({
+    path: issue.path.map(String).join('.'),
+    message: issue.message,
+    code: issue.code,
+  }));
+  const err = new Error(
+    `Action '${name}' of package '${packageId}' does not satisfy the action contract (ActionSchema): `
+    + issues.map((issue) => (issue.path ? `${issue.path}: ${issue.message}` : issue.message)).join('; ')
+    + '. Every action a package ships is stored as its schema parse — the parse that lowers '
+    + '`requiresFeature` and `requiresMembershipReach` into `visible` — so an action that does not parse '
+    + 'is refused rather than served with its declared gates inert. Correct the declaration; `defineStack` '
+    + 'and `os validate` report the same issues.',
+  ) as PackageActionSchemaError;
+  err.code = 'INVALID_METADATA';
+  err.status = 422;
+  err.httpStatus = 422;
+  err.issues = issues;
+  throw err;
+}
+
 /**
  * [#24472] The key {@link SchemaRegistry}'s bound-action collision audit is
  * carried under. A symbol, and ⛔ deliberately NOT re-exported from the package
@@ -5160,6 +5225,18 @@ export class SchemaRegistry {
     // package envelope. Every other caller gets the id alone.
     applyProtection(item as any, { packageId });
 
+    // [#25649] A code package's action is stored as its `ActionSchema` parse —
+    // `requiresFeature` / `requiresMembershipReach` lowered into `visible` —
+    // or refused before anything below stores it ({@link parsePackageAction}).
+    // After `applyProtection`, so the envelope the parse passes through is the
+    // one this call stamped, and `isCodeArtifactBody` reads the stamped
+    // provenance. ⛔ A registration with no `packageId` is the bare slot —
+    // `sys_metadata` hydration, the metadata write-through — and is never
+    // judged here: a stored row is parsed at the metadata save door.
+    if (type === 'action' && packageId && isCodeArtifactBody(item)) {
+      item = parsePackageAction(item, baseName, packageId) as T;
+    }
+
     // A picklist's own values must not repeat any value its extensions
     // already add — refused before anything is stored, like the extension
     // side ({@link registerPicklistExtension}). Every resolved object depends
 
@@ -581,7 +581,9 @@ function actionPackageOf(prefix: string) {
         type: 'script',
         operation: 'update',
         patch: { name: 'done' },
-        ...(exposed ? { ai: { exposed: true, description: `${name} for the test` } } : {}),
+        // [#25649] A package's top-level action is stored as its `ActionSchema`
+        // parse, which holds an AI-exposed action's `description` to 40 characters.
+        ...(exposed ? { ai: { exposed: true, description: `${name}: marks the record done, for the MCP discovery test` } } : {}),
         ...extra,
     });
     return {
Original file line number	Diff line number	Diff line change
`@@ -235,7 +235,12 @@ async function seed(protocol: any, registry: SchemaRegistry) {`
`235`	`235`	`// [#24210] One item of every declared type, as a code package ships it:`
`236`	`236`	`// the registry layer, stamped with the package that registered it.`
`237`	`237`	`for (const type of BY_NAME_TYPES) {`
`238`		`- registry.registerItem(type, { name: shippedName(type, pkg), label: 'Shipped' } as any, 'name', pkg);`
	`238`	+ // [#25649] A package's action is stored as its `ActionSchema` parse, so it
	`239`	`+ // is shipped as a declaration that parses.`
	`240`	`+ const body = type === 'action'`
	`241`	`+ ? { name: shippedName(type, pkg), label: 'Shipped', type: 'url', target: 'https://example.com/shipped' }`
	`242`	`+ : { name: shippedName(type, pkg), label: 'Shipped' };`
	`243`	`+ registry.registerItem(type, body as any, 'name', pkg);`
`239`	`244`	`}`
`240`	`245`	`}`
`241`	`246`	`}`