test: move the hook probes to body-carrying hooks and pin the neither-field refusal on the real door

Claude-Session: https://claude.ai/code/session_017ErfyP2Rx7XWHJA27QjyUi
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

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

@@ -402,7 +402,10 @@ describe('code-only metadata types are refused on every kernel (#5086)', () => {
                 const result = await protocol.saveMetaItem({
                     type: 'hook',
                     name: 'rc3_probe_hook',
-                    item: { name: 'rc3_probe_hook', object: 'task', events: ['beforeUpdate'] },
+                    // [#21689] A body-carrying hook: the save door refuses a hook
+                    // with no `body` (it could never run), and this case measures
+                    // the code-only gate, not that refusal.
+                    item: { name: 'rc3_probe_hook', object: 'task', events: ['beforeUpdate'], body: { language: 'js', source: 'return;' } },
                 });
                 expect(result.success).toBe(true);
                 expect(metaRows(rows).length).toBe(1);
@@ -511,7 +514,9 @@ describe('code-only metadata types are refused on every kernel (#5086)', () => {
             },
             {
                 type: 'hook', // allowRuntimeCreate only
-                item: { name: 'rc3_receipt_view', object: 'task', events: ['beforeUpdate'] },
+                // [#21689] With a `body`: the door refuses a hook without one,
+                // and this matrix measures the receipt, not that refusal.
+                item: { name: 'rc3_receipt_view', object: 'task', events: ['beforeUpdate'], body: { language: 'js', source: 'return;' } },
             },
             {
                 type: 'webhook', // no static registry entry (plugin-registered)

packages/metadata-protocol/src/protocol.invalid-metadata-422-face-inventory.test.ts

@@ -570,3 +570,50 @@ describe('[#21658] a hook naming a function in `handler` with no `body` is refus
         expect(rows.size).toBe(0);
     });
 });
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 8. #21689 — one predicate: the `hook` door refuses every hook with no `body`
+// ═══════════════════════════════════════════════════════════════════════════
+//
+// Section 7's refusal, generalised. A hook this door stores ships with no code
+// package, so a `body` is the only code it can run: a hook with neither a
+// `body` nor a `handler` is never bound either (the binder skips it at every
+// re-sync). The door judges by one predicate — no `body` object — and section
+// 7's `handler` form is one case of it, with the same envelope. An empty
+// `handler` names no function, so it reads as no `handler`.
+
+describe('[#21689] a hook with no `body` and no function in `handler` is refused at the metadata door', () => {
+    const bare = (extra: Record<string, unknown> = {}) => ({
+        name: 'stamp_status',
+        object: 'hks_note',
+        events: ['beforeInsert'],
+        ...extra,
+    });
+
+    it.each([
+        ['publish', 'neither field', undefined, {}],
+        ['draft', 'neither field', 'draft', {}],
+        ['publish', 'an empty `handler`', undefined, { handler: '' }],
+    ] as const)('%s mode, %s — VALIDATION_ERROR / 400, naming the hook, prescribing a `body`, nothing stored', async (_label, _shape, mode, extra) => {
+        const { protocol, rows } = makeProtocol();
+        let err: any;
+        try {
+            await protocol.saveMetaItem({
+                type: 'hook',
+                name: 'stamp_status',
+                item: bare(extra),
+                writeFace: 'meta-envelope',
+                actor: 'usr_admin',
+                ...(mode ? { mode } : {}),
+            });
+        } catch (e) {
+            err = e;
+        }
+
+        expect(err).toBeInstanceOf(Error);
+        expect({ code: err.code, status: err.status }).toEqual({ code: 'VALIDATION_ERROR', status: 400 });
+        expect(err.message).toContain("'stamp_status'");
+        expect(err.message).toContain('Give it a `body`');
+        expect(rows.size).toBe(0);
+    });
+});

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

@@ -143,7 +143,10 @@ const SAMPLE: Array<{
         type: 'hook',
         klass: 'declared',
         creatable: true,
-        item: { name: 'probe_hook', object: 'task', events: ['beforeInsert'] },
+        // [#21689] With a `body`: the mint door refuses a hook without one (it
+        // could never run), which would misread the advertisement this suite
+        // measures, as a 422 from schema resolution would.
+        item: { name: 'probe_hook', object: 'task', events: ['beforeInsert'], body: { language: 'js', source: 'return;' } },
     },
     {
         // The `false` direction of class 1, and it must be present: a listing

packages/metadata-protocol/src/protocol.save-receipt-wording.test.ts

@@ -129,7 +129,9 @@ const OVERLAYLESS_PROBES: Record<string, Record<string, unknown>> = {
         sharingModel: 'private',
         fields: { name: { type: 'text', label: 'Name' } },
     },
-    hook: { name: 'rc5_acct', object: 'task', events: ['beforeUpdate'] },
+    // [#21689] With a `body`: the door refuses a hook without one before the
+    // receipt is built, as it refuses a body the schema rejects.
+    hook: { name: 'rc5_acct', object: 'task', events: ['beforeUpdate'], body: { language: 'js', source: 'return;' } },
     seed: { object: 'task', records: [] },
     action: { name: 'rc5_acct', label: 'Convert', type: 'script', objectName: 'task', target: 'convertHandler' },
     flow: {

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

@@ -215,7 +215,8 @@ describe('#8421 — the traffic that must keep working', () => {
         {
             type: 'hook',
             why: 'declared, runtime-create only',
-            item: { name: 'probe_item', object: 'task', events: ['beforeUpdate'] },
+            // [#21689] With a `body`: the door refuses a hook without one.
+            item: { name: 'probe_item', object: 'task', events: ['beforeUpdate'], body: { language: 'js', source: 'return;' } },
         },
         {
             // `theme` held this slot until commit 35ad101bc retired the themes surface

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

@@ -143,12 +143,17 @@ const FIXTURES: Record<string, Fixture> = {
         invalidatedField: 'type',
     },
     hook: {
+        // [#21689] Both carry a `body`: the save door refuses a hook with no
+        // `body` (it could never run), so a body-less `valid` would measure
+        // that refusal, and `invalid` stays `valid` minus the one field the
+        // schema must name.
         valid: {
             name: 'sweep_hook',
             object: 'sweep_account',
             events: ['beforeInsert'],
+            body: { language: 'js', source: 'return;' },
         },
-        invalid: { name: 'sweep_hook', object: 'sweep_account' },
+        invalid: { name: 'sweep_hook', object: 'sweep_account', body: { language: 'js', source: 'return;' } },
         invalidatedField: 'events',
     },
     validation: {

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

@@ -269,8 +269,11 @@ describe('overlay whitelist enforcement (shared-DB invariant)', () => {
             // `validation` left this list with the kind (#4509, ADR-0088): it is
             // no longer registered, so "runtime-creatable" no longer describes
             // it. The reintroduction guard below is what holds the line now.
-            { type: 'hook', item: { name: 'before_save', object: 'case', events: ['beforeInsert'] } },
-            { type: 'hooks', item: { name: 'before_save', object: 'case', events: ['beforeInsert'] } }, // plural
+            // [#21689] Each hook carries a `body`: the save door refuses a hook
+            // with no `body` (it could never run), and this loop measures the
+            // two-tier verdict, not that refusal.
+            { type: 'hook', item: { name: 'before_save', object: 'case', events: ['beforeInsert'], body: { language: 'js', source: 'return;' } } },
+            { type: 'hooks', item: { name: 'before_save', object: 'case', events: ['beforeInsert'], body: { language: 'js', source: 'return;' } } }, // plural
             // object reverted to allowOrgOverride:false on 2026-05-29 —
             // packaged items locked, brand-new tenant-authored items succeed.
             {
@@ -349,7 +352,8 @@ describe('overlay whitelist enforcement (shared-DB invariant)', () => {
             const result = await localProto.saveMetaItem({
                 type: 'hook',
                 name: 'my_hook',
-                item: { name: 'my_hook', object: 'case', events: ['beforeUpdate'] },
+                // [#21689] With a `body`: the door refuses a hook without one.
+                item: { name: 'my_hook', object: 'case', events: ['beforeUpdate'], body: { language: 'js', source: 'return;' } },
             });
             expect(result.success).toBe(true);
         });

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

@@ -1492,7 +1492,10 @@ describe('ObjectStackProtocolImplementation - Metadata Persistence', () => {
                 scoped.saveMetaItem({
                     type: 'hook',
                     name: 'shipped_hook',
-                    item: { name: 'shipped_hook', object: 'case', events: ['beforeInsert'] },
+                    // [#21689] A body-carrying hook, so the refusal measured is
+                    // the provenance gate's and no other gate's: the door also
+                    // refuses a hook with no `body`.
+                    item: { name: 'shipped_hook', object: 'case', events: ['beforeInsert'], body: { language: 'js', source: 'return;' } },
                     organizationId: 'org_alpha',
                 }),
             ).rejects.toMatchObject({
@@ -1507,7 +1510,8 @@ describe('ObjectStackProtocolImplementation - Metadata Persistence', () => {
             const result = await scoped.saveMetaItem({
                 type: 'hook',
                 name: 'my_user_hook',
-                item: { name: 'my_user_hook', object: 'case', events: ['beforeUpdate'] },
+                // [#21689] With a `body`: the door refuses a hook without one.
+                item: { name: 'my_user_hook', object: 'case', events: ['beforeUpdate'], body: { language: 'js', source: 'return;' } },
             });
 
             expect(result.success).toBe(true);
@@ -1529,7 +1533,8 @@ describe('ObjectStackProtocolImplementation - Metadata Persistence', () => {
             const result = await scoped.saveMetaItem({
                 type: 'hook',
                 name: 'my_user_hook',
-                item: { name: 'my_user_hook', object: 'case', events: ['beforeInsert', 'beforeUpdate'] },
+                // [#21689] With a `body`: the door refuses a hook without one.
+                item: { name: 'my_user_hook', object: 'case', events: ['beforeInsert', 'beforeUpdate'], body: { language: 'js', source: 'return;' } },
             });
 
             expect(result.success).toBe(true);

packages/runtime/src/hook-handler-package-scope.pin.test.ts

@@ -17,6 +17,15 @@
  *     so the name could only ever be refused again at bind (the binder's
  *     `metadata-service` refusal, pinned in objectql's
  *     `hook-binder-package-scope.test.ts`).
+ *   ②c the same door, the other shape with no `body` (#21689): a hook with
+ *     neither a `body` nor a `handler`, which the binder would skip at every
+ *     re-sync, is refused by the same predicate with the same envelope. One
+ *     predicate judges both shapes: a hook with no `body` object.
+ *
+ * The enumeration this file holds on the real door: a `body` hook saves (②b),
+ * a `handler`-only hook is refused (②), a hook with neither is refused (②c),
+ * and a built artifact's `handler` hook through its own door is unchanged
+ * (the X and Z controls).
  *
  * Controls, the two shapes a package's own function takes: app X's hook naming
  * X's own `functions` entry binds and runs, and app Z's hook naming a function
@@ -145,6 +154,13 @@ function refusalsOf(hook: string): any[][] {
   return engineLogger.error.mock.calls.filter((call: any[]) => call[2]?.hook === hook);
 }
 
+/** The binder's skips of `hook` (a hook with nothing to bind), as the engine logged them. */
+function skipsOf(hook: string): any[][] {
+  return engineLogger.warn.mock.calls.filter(
+    (call: any[]) => String(call[0]).includes('skipping hook') && call[1]?.hook === hook,
+  );
+}
+
 async function waitFor(predicate: () => Promise<boolean>, ms = 15_000): Promise<boolean> {
   const until = Date.now() + ms;
   while (Date.now() < until) {
@@ -248,6 +264,23 @@ describe('a hook handler name resolves inside its own package only — composed
     expect(stored.status, await stored.text()).toBe(404);
   });
 
+  it('②c the metadata door refuses a runtime-authored hook with neither a `body` nor a `handler`: VALIDATION_ERROR / 400, nothing stored', async () => {
+    // The measured `PUT`: before #21689 it answered 200, the row was served by
+    // name, and the binder skipped it at every re-sync.
+    const bareHook = await asAdmin('PUT', '/meta/hook/scope_authored_bare', {
+      name: 'scope_authored_bare',
+      object: Y_NOTE,
+      events: ['beforeInsert'],
+    });
+    const refusal: any = await bareHook.json();
+    expect({ status: bareHook.status, code: refusal?.code }, JSON.stringify(refusal))
+      .toEqual({ status: 400, code: 'VALIDATION_ERROR' });
+    expect(refusal.error).toContain("'scope_authored_bare'");
+    expect(refusal.error).toContain('Give it a `body`');
+    const stored = await asAdmin('GET', '/meta/hook/scope_authored_bare');
+    expect(stored.status, await stored.text()).toBe(404);
+  });
+
   it('②b a body hook authored through the metadata door saves, binds and runs; so does one carrying both a `body` and a `handler`', async () => {
     const bodyHook = await asAdmin('PUT', '/meta/hook/scope_authored_body', {
       name: 'scope_authored_body',
@@ -279,9 +312,11 @@ describe('a hook handler name resolves inside its own package only — composed
     expect(refusalsOf('scope_authored_both')).toEqual([]);
   }, 30_000);
 
-  it('② nothing bound: once the re-sync has run (②b), the refused hook never reached the binder', async () => {
+  it('② and ②c nothing bound: once the re-sync has run (②b), neither refused hook reached the binder', async () => {
     // There was no row for the re-sync to bind, so the binder recorded no
-    // refusal of it either: the door refused it before anything was stored.
+    // refusal or skip of either: the door refused both before anything was stored.
     expect(refusalsOf('scope_authored_cross')).toEqual([]);
+    expect(refusalsOf('scope_authored_bare')).toEqual([]);
+    expect(skipsOf('scope_authored_bare')).toEqual([]);
   });
 });