fix(objectql): the action-governance audit resolves declarations through the router's rungs (#14421)

The boot inventory built its declaration set from object-embedded `actions[]`
plus the metadata service's `action` rows, while `resolveRouteActionDeclaration`
resolves through a third source between those two: the engine registry's
standalone `action` items. On the in-process boot the metadata plane holds no
`action` rows, so every object-less `defineAction` was reported as a registered
handler with no declaration, "REFUSED at dispatch ... there is no opt-out", in
the same boot in which the router resolved it at that rung and dispatched it.

`ObjectQLPlugin` — the one caller holding the engine — now injects that rung,
and the audit judges the answer with the router's own ownership test. The
warning stops asserting a dispatch outcome it never performed: it names the
sources it read, says it did not dispatch, and sends an author whose action IS
declared to the real bug rather than to deleting a working registration. The
file docblock's "the inventory can never disagree with the router" invariant is
corrected to the one that now holds. `declared script actions with NO handler`
is unchanged in wording and in population.


Claude-Session: https://claude.ai/code/session_0112hMx9hjJ9BgB28X97DS68

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

Author: os-musk

.changeset/action-governance-registry-rung.md

@@ -0,0 +1,24 @@
+---
+'@objectstack/objectql': patch
+---
+
+Startup `[action-governance]` resolves declarations through the same rungs the router does
+
+The boot inventory built its declaration set from object-embedded `actions[]` plus the
+metadata service's `action` rows. `resolveRouteActionDeclaration` resolves through a third
+source between those two — the engine registry's standalone `action` items,
+`registry.getItem('action', name)`, accepted when the item owns the route. On the in-process
+boot (`new AppPlugin(...)` then `kernel.bootstrap()`), where the metadata plane holds no
+`action` rows at all, every object-less `defineAction` was therefore reported as a
+"registered handler with NO declaration — REFUSED at dispatch (ADR-0110 D3) and there is no
+opt-out" in the same boot in which the router resolved it at that rung and dispatched it.
+Both remedies the message offered were wrong for that shape: the action was already declared
+with `defineAction`, and dropping the registration would have broken a working endpoint under
+a green `pnpm validate`.
+
+The registry rung is now injected into the audit by `ObjectQLPlugin` — the one caller holding
+the engine, because objectql cannot import the router — and judged by the same ownership test
+the router applies. The warning also stops asserting a dispatch outcome it never checked: it
+names the three sources it read, says it did not dispatch, and points an author whose action
+IS declared at the real bug instead of at deleting the registration. The other finding in the
+block, `declared script actions with NO handler`, is unchanged in wording and in population.

packages/objectql/src/action-governance.test.ts

@@ -10,6 +10,18 @@
  * fingerprint-suppressed across `metadata:reloaded` re-runs, and that a
  * failing declaration source degrades to a debug line instead of throwing —
  * a diagnostic must never be the reason a kernel fails to boot.
+ *
+ * The second describe block pins the router's registry rung. The measured
+ * defect: on the in-process boot (`new AppPlugin(...)` then
+ * `kernel.bootstrap()`), `meta.loadMany('action')` answers `[]` while
+ * `registry.getItem('action', name)` answers the declaration, so every
+ * object-LESS `defineAction` was named as a "registered handler with NO
+ * declaration ... REFUSED at dispatch" in the same boot in which the router
+ * resolved it at rung 2 and dispatched it. Pinned here: the two boots (the
+ * registry holds it, the plane does not), both call forms (object-bound and
+ * object-less), a positive control that must stay reported, the ownership
+ * test that keeps the rung from clearing a foreign declaration, and the
+ * second warning holding its exact wording while the first changes.
  */
 
 import { describe, it, expect, vi } from 'vitest';
@@ -120,3 +132,169 @@ describe('runActionGovernanceInventory (ADR-0110 D5)', () => {
         );
     });
 });
+
+describe('runActionGovernanceInventory — the router registry rung (#14123)', () => {
+    /** `registry.getItem('action', name)`, as the plugin injects it. */
+    const registryOf = (items: Record<string, any>) => (name: string) => items[name];
+
+    const applyAction = { name: 'duly_catalog_apply', type: 'script', locations: [] };
+
+    it('clears an object-LESS declaration the registry holds and the plane does not', async () => {
+        const logger = makeLogger();
+        await runActionGovernanceInventory({
+            registered: [{ objectName: 'global', actionName: 'duly_catalog_apply' }],
+            objects: [],                              // no object embeds it
+            loadStandaloneActions: async () => [],    // in-process boot: the plane is empty
+            lookupRegistryAction: registryOf({ duly_catalog_apply: applyAction }),
+            logger,
+        });
+
+        expect(logger.warn).not.toHaveBeenCalled();
+    });
+
+    it('clears an object-BOUND declaration the registry holds and the plane does not', async () => {
+        const logger = makeLogger();
+        await runActionGovernanceInventory({
+            registered: [{ objectName: 'todo_task', actionName: 'archive_task' }],
+            objects: [{ name: 'todo_task', actions: [] }],
+            loadStandaloneActions: async () => [],
+            lookupRegistryAction: registryOf({
+                archive_task: { name: 'archive_task', objectName: 'todo_task', type: 'script' },
+            }),
+            logger,
+        });
+
+        expect(logger.warn).not.toHaveBeenCalled();
+    });
+
+    it('POSITIVE CONTROL — a handler no source declares is still named', async () => {
+        const logger = makeLogger();
+        await runActionGovernanceInventory({
+            registered: [
+                { objectName: 'global', actionName: 'duly_catalog_apply' },
+                { objectName: 'global', actionName: 'ghostProbe' },
+                { objectName: 'todo_task', actionName: 'ghostBound' },
+            ],
+            objects: [{ name: 'todo_task', actions: [] }],
+            loadStandaloneActions: async () => [],
+            lookupRegistryAction: registryOf({ duly_catalog_apply: applyAction }),
+            logger,
+        });
+
+        expect(logger.warn).toHaveBeenCalledTimes(1);
+        expect(logger.warn).toHaveBeenCalledWith(
+            expect.stringMatching(/registered handlers with NO declaration/),
+            expect.objectContaining({ count: 2, handlers: ['global:ghostProbe', 'todo_task:ghostBound'] }),
+        );
+    });
+
+    it('applies the router ownership test — a foreign object-bound item does not cover the route', async () => {
+        const logger = makeLogger();
+        await runActionGovernanceInventory({
+            registered: [{ objectName: 'todo_task', actionName: 'archive_task' }],
+            objects: [{ name: 'todo_task', actions: [] }],
+            lookupRegistryAction: registryOf({
+                archive_task: { name: 'archive_task', objectName: 'crm_lead', type: 'script' },
+            }),
+            logger,
+        });
+
+        expect(logger.warn).toHaveBeenCalledWith(
+            expect.stringMatching(/registered handlers with NO declaration/),
+            expect.objectContaining({ handlers: ['todo_task:archive_task'] }),
+        );
+    });
+
+    it('stops asserting a dispatch outcome it did not check, and names the sources it did read', async () => {
+        const logger = makeLogger();
+        await runActionGovernanceInventory({
+            registered: [{ objectName: 'global', actionName: 'ghostProbe' }],
+            objects: [],
+            logger,
+        });
+
+        const [message] = logger.warn.mock.calls[0];
+        expect(message).not.toMatch(/REFUSED at dispatch/);
+        expect(message).not.toMatch(/there is no opt-out/);
+        expect(message).not.toMatch(/drop the registration/);
+        expect(message).toMatch(/it did not dispatch/);
+        expect(message).toMatch(/object-embedded `actions\[\]`/);
+        expect(message).toMatch(/the engine registry standalone `action` items/);
+        expect(message).toMatch(/the metadata service `action` rows/);
+    });
+
+    it('leaves the OTHER warning byte-identical — a registry item is not folded into the declaration set', async () => {
+        const logger = makeLogger();
+        await runActionGovernanceInventory({
+            registered: [],
+            objects: todoObjects,
+            lookupRegistryAction: registryOf({
+                // A registry-only script declaration with no handler anywhere. It must
+                // not join `unboundDeclarations`: the router never enumerates the
+                // registry, so neither does this audit.
+                orphan_action: { name: 'orphan_action', type: 'script', target: 'orphanHandler' },
+            }),
+            logger,
+        });
+
+        expect(logger.warn).toHaveBeenCalledTimes(1);
+        expect(logger.warn).toHaveBeenCalledWith(
+            '[action-governance] declared script actions with NO handler — a button wired to '
+            + 'nothing (ADR-0078); add a `body`, or register a handler under the declared `target`',
+            { count: 1, actions: ['todo_task:complete_task'] },
+        );
+    });
+
+    it('keeps the handler when the registry lookup throws — and never throws itself', async () => {
+        const logger = makeLogger();
+        await expect(runActionGovernanceInventory({
+            registered: [{ objectName: 'global', actionName: 'duly_catalog_apply' }],
+            objects: [],
+            lookupRegistryAction: () => { throw new Error('registry unreadable'); },
+            logger,
+        })).resolves.toBeDefined();
+
+        expect(logger.warn).toHaveBeenCalledWith(
+            expect.stringMatching(/registered handlers with NO declaration/),
+            expect.objectContaining({ handlers: ['global:duly_catalog_apply'] }),
+        );
+    });
+
+    it('fingerprints the FILTERED set, so a rung-cleared boot reports and remembers nothing', async () => {
+        const logger = makeLogger();
+        const fp = await runActionGovernanceInventory({
+            registered: [{ objectName: 'global', actionName: 'duly_catalog_apply' }],
+            objects: [],
+            lookupRegistryAction: registryOf({ duly_catalog_apply: applyAction }),
+            logger,
+        });
+
+        expect(fp).toBe('');
+        expect(logger.warn).not.toHaveBeenCalled();
+
+        // The declaration disappears on a later reload: the finding is new, so it reports.
+        await runActionGovernanceInventory({
+            registered: [{ objectName: 'global', actionName: 'duly_catalog_apply' }],
+            objects: [],
+            lookupRegistryAction: registryOf({}),
+            logger,
+            lastFingerprint: fp,
+        });
+
+        expect(logger.warn).toHaveBeenCalledTimes(1);
+    });
+
+    it('is unchanged when no rung is injected — two sources, and the finding stands', async () => {
+        const logger = makeLogger();
+        await runActionGovernanceInventory({
+            registered: [{ objectName: 'global', actionName: 'duly_catalog_apply' }],
+            objects: [],
+            logger,
+        });
+
+        expect(logger.warn).toHaveBeenCalledWith(
+            expect.stringMatching(/registered handlers with NO declaration/),
+            expect.objectContaining({ handlers: ['global:duly_catalog_apply'] }),
+        );
+    });
+});