fix(objectql,runtime,metadata-protocol): execute authored (Studio) hook bodies — wire default bodyRunner + live rebind (#2588)

A hook authored at runtime (protocol.saveMetaItem / publish-drafts) loaded
into the registry but its L1/L2 body never executed — on publish AND after a
full restart. Two gaps compounded:

1. No bodyRunner on the metadata-service bind path: bindHooksToEngine skips
   body-hooks without a runner, and engine.setDefaultBodyRunner was never
   called anywhere. AppPlugin.init now installs the QuickJS-sandboxed hook
   body runner as the engine default (same runner defineStack hooks already
   use), so runner-less bind paths execute bodies. Opt-out:
   OS_DISABLE_AUTHORED_HOOKS=1 keeps runtime-authored bodies inert.

2. The bind set never saw authored rows: env-scoped kernels have no
   DatabaseLoader, so metadataService.loadMany('hook') misses sys_metadata
   rows entirely — the hook was never even bound-and-skipped. ObjectQLPlugin
   now re-binds runtime-authored hooks from the rows themselves at
   kernel:ready (cold boot), on metadata:reloaded (dev artifact reload,
   package publish), and on every hook mutation via the new server-side
   protocol.onMetadataMutation listener (saveMetaItem / publishMetaItem /
   deleteMetaItem notify after persistence) — so direct saves, publishes,
   edits, and deletes all take effect without a restart.

Double-execution guard: package-artifact hooks (bound by AppPlugin under
app:<id> with an explicit runner) are excluded from the metadata-service
bind via registry.getArtifactItem — previously their string-handler variants
were latently double-bound, and a default runner would have made body hooks
run twice per event. Deleting the last authored hook explicitly unregisters
the package set (bindHooksToEngine early-returns on an empty list before its
unregister step). Resyncs are serialized so overlapping mutations cannot
land an older snapshot last.

Verified end-to-end on a fresh showcase instance: authored beforeUpdate hook
mutates input after live save, after draft+publish-drafts, and after a full
restart; deletes stop it firing; the defineStack control hook still runs.

Closes #2588

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

Author: claude

.changeset/hook-bodyrunner-metadata-service.md

@@ -0,0 +1,28 @@
+---
+'@objectstack/objectql': patch
+'@objectstack/metadata-protocol': patch
+'@objectstack/runtime': patch
+---
+
+Runtime-authored (Studio) hooks now execute their `body` (#2588).
+
+Previously a hook authored at runtime (saved via `protocol.saveMetaItem` /
+`publish-drafts`) loaded into the registry but its L1/L2 `body` never ran — the
+metadata-service bind path passed no `bodyRunner` and the engine's
+`_defaultBodyRunner` fallback was never installed, so the binder silently
+skipped the body. Now:
+
+- `AppPlugin` installs the QuickJS-sandboxed hook body runner as the engine
+  default at boot (`engine.setDefaultBodyRunner`), so bind paths without an
+  explicit runner can execute bodies. Opt out with
+  `OS_DISABLE_AUTHORED_HOOKS=1` to keep runtime-authored hook bodies inert.
+- `ObjectQLPlugin` re-binds runtime-authored hooks from their `sys_metadata`
+  rows at `kernel:ready` (cold boot — env-scoped kernels never surfaced these
+  rows before), on `metadata:reloaded`, and on every hook mutation through the
+  new `protocol.onMetadataMutation` listener — so saves, publishes, edits, and
+  deletes take effect live, without a restart. Package-artifact hooks are
+  excluded from this bind path (AppPlugin already binds them with an explicit
+  runner) so they no longer risk double execution.
+- `@objectstack/metadata-protocol` gains a server-side
+  `onMetadataMutation(listener)` API: `saveMetaItem` / `publishMetaItem` /
+  `deleteMetaItem` notify subscribers after persistence succeeds.

packages/metadata-protocol/src/mutation-listeners.test.ts

@@ -0,0 +1,66 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Metadata-mutation listener contract (#2588).
+ *
+ * `onMetadataMutation` is the post-persistence notification every authoring
+ * surface funnels through (saveMetaItem / publishMetaItem / deleteMetaItem
+ * all emit). Runtime consumers — first: ObjectQLPlugin's authored-hook
+ * rebind — subscribe to it instead of each HTTP surface hand-announcing.
+ * The end-to-end emit points are exercised by the runtime integration flow;
+ * these tests pin the listener contract itself.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { ObjectStackProtocolImplementation } from './protocol.js';
+import type { MetadataMutationEvent } from './protocol.js';
+
+function makeProtocol() {
+  // The listener plumbing never touches the engine.
+  return new ObjectStackProtocolImplementation({} as any);
+}
+
+const evt = (over: Partial<MetadataMutationEvent> = {}): MetadataMutationEvent => ({
+  type: 'hook',
+  name: 'rebind_probe_hook',
+  state: 'active',
+  organizationId: null,
+  ...over,
+});
+
+describe('ObjectStackProtocolImplementation.onMetadataMutation', () => {
+  it('notifies subscribed listeners with the event', () => {
+    const p = makeProtocol();
+    const seen: MetadataMutationEvent[] = [];
+    p.onMetadataMutation((e) => seen.push(e));
+
+    (p as any).emitMetadataMutation(evt());
+    (p as any).emitMetadataMutation(evt({ state: 'deleted' }));
+
+    expect(seen.map((e) => e.state)).toEqual(['active', 'deleted']);
+    expect(seen[0].type).toBe('hook');
+    expect(seen[0].name).toBe('rebind_probe_hook');
+  });
+
+  it('returns an unsubscribe function that stops delivery', () => {
+    const p = makeProtocol();
+    const listener = vi.fn();
+    const unsubscribe = p.onMetadataMutation(listener);
+
+    (p as any).emitMetadataMutation(evt());
+    unsubscribe();
+    (p as any).emitMetadataMutation(evt());
+
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it('isolates a throwing listener — remaining listeners still run', () => {
+    const p = makeProtocol();
+    const after = vi.fn();
+    p.onMetadataMutation(() => { throw new Error('boom'); });
+    p.onMetadataMutation(after);
+
+    expect(() => (p as any).emitMetadataMutation(evt())).not.toThrow();
+    expect(after).toHaveBeenCalledTimes(1);
+  });
+});

packages/metadata-protocol/src/protocol.ts

@@ -719,6 +719,20 @@ export type PublishMaterializer = (args: {
     actor: string;
 }) => Promise<PublishMaterializeResult>;
 
+/**
+ * Post-persistence metadata-mutation notification (#2588). Emitted by
+ * `saveMetaItem` / `publishMetaItem` / `deleteMetaItem` AFTER the write
+ * landed. `type` is the singular metadata type name. Subscribe via
+ * {@link ObjectStackProtocolImplementation.onMetadataMutation}.
+ */
+export interface MetadataMutationEvent {
+    type: string;
+    name: string;
+    /** Resulting lifecycle state of the row the mutation produced. */
+    state: 'active' | 'draft' | 'deleted';
+    organizationId?: string | null;
+}
+
 export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     private engine: MetadataHostEngine;
     private getServicesRegistry?: () => Map<string, any>;
@@ -778,6 +792,50 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         this.publishMaterializers.set(singular, materializer);
     }
 
+    /**
+     * Runtime-mutation listeners (#2588). Every metadata mutation that lands
+     * through this protocol — `saveMetaItem` (draft AND direct-active saves),
+     * `publishMetaItem` (per-item and package publish-drafts), and
+     * `deleteMetaItem` — notifies these listeners AFTER persistence succeeds.
+     *
+     * This is the ONE choke point every authoring surface funnels through
+     * (rest-server, http-dispatcher, AI builders, direct protocol callers),
+     * so boot-cached runtime consumers can re-sync on authoring without each
+     * HTTP surface hand-announcing. First consumer: ObjectQLPlugin re-binds
+     * runtime-authored hooks when a `hook` row changes.
+     *
+     * Server-side extension only — NOT part of the ObjectStackProtocol wire
+     * contract (same status as `loadMetaFromDb`).
+     */
+    private metadataMutationListeners: Array<(evt: MetadataMutationEvent) => void> = [];
+
+    /** Subscribe to post-persistence metadata mutations. Returns an unsubscribe fn. */
+    onMetadataMutation(listener: (evt: MetadataMutationEvent) => void): () => void {
+        this.metadataMutationListeners.push(listener);
+        return () => {
+            const i = this.metadataMutationListeners.indexOf(listener);
+            if (i >= 0) this.metadataMutationListeners.splice(i, 1);
+        };
+    }
+
+    /**
+     * Notify mutation listeners (best-effort, synchronous fan-out). A
+     * listener failure must never fail the write it observes — the row is
+     * already persisted — so each listener is isolated in its own try/catch.
+     */
+    private emitMetadataMutation(evt: MetadataMutationEvent): void {
+        for (const listener of this.metadataMutationListeners) {
+            try {
+                listener(evt);
+            } catch (e) {
+                console.warn(
+                    `[Protocol] metadata-mutation listener failed for ${evt.type}/${evt.name}: `
+                    + `${e instanceof Error ? e.message : String(e)}`,
+                );
+            }
+        }
+    }
+
     /**
      * Lazily obtain a SysMetadataRepository for the given organization.
      * Env-wide overlays (organizationId == null) share a singleton under
@@ -3905,6 +3963,12 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                     source: 'protocol.saveMetaItem',
                     note: mode === 'draft' ? 'draft' : 'active',
                 });
+                this.emitMetadataMutation({
+                    type: singularTypeForRepo,
+                    name: request.name,
+                    state: mode === 'draft' ? 'draft' : 'active',
+                    organizationId: orgId,
+                });
                 return {
                     success: true,
                     version: result.version,
@@ -3996,6 +4060,12 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                 await this.engine.insert('sys_metadata', row);
             }
 
+            this.emitMetadataMutation({
+                type: PLURAL_TO_SINGULAR[request.type] ?? request.type,
+                name: request.name,
+                state: 'active',
+                organizationId: orgId,
+            });
             return {
                 success: true,
                 message: orgId
@@ -4192,6 +4262,12 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                     };
                 }
             }
+            this.emitMetadataMutation({
+                type: singularType,
+                name: request.name,
+                state: 'active',
+                organizationId: orgId,
+            });
             return response;
         } catch (err: any) {
             if (err instanceof ConflictError) {
@@ -5434,6 +5510,12 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                     note: targetState,
                 });
 
+                this.emitMetadataMutation({
+                    type: singularTypeForRepo,
+                    name: request.name,
+                    state: 'deleted',
+                    organizationId: orgId,
+                });
                 return {
                     success: true,
                     reset: true,

packages/objectql/src/hook-binder.test.ts

@@ -95,6 +95,51 @@ describe('bindHooksToEngine', () => {
     expect(calls).toEqual(['v2']);
   });
 
+  it('skips body-hooks when no bodyRunner is supplied and no default is installed', () => {
+    const engine = makeEngine();
+    const hook: Hook = {
+      name: 'body-no-runner', object: 'account', events: ['beforeInsert'], priority: 100,
+      body: { language: 'js', source: "ctx.input.x = 1;" },
+    } as unknown as Hook;
+    const result = bindHooksToEngine(engine, [hook], { packageId: 'p' });
+    expect(result.registered).toBe(0);
+    expect(result.skipped).toBe(1);
+    expect(result.errors[0]?.reason).toMatch(/no bodyRunner/);
+  });
+
+  it('falls back to the engine default bodyRunner via engine.bindHooks (#2588)', async () => {
+    const engine = makeEngine();
+    const calls: string[] = [];
+    // Fake runner — the real QuickJS bridge lives in @objectstack/runtime;
+    // here we only verify the engine-level fallback plumbing.
+    engine.setDefaultBodyRunner((hook: Hook) => async () => {
+      calls.push(hook.name);
+    });
+    const hook: Hook = {
+      name: 'body-default-runner', object: 'account', events: ['beforeInsert'], priority: 100,
+      body: { language: 'js', source: "ctx.input.x = 1;" },
+    } as unknown as Hook;
+    engine.bindHooks([hook], { packageId: 'metadata-service' });
+    await engine.triggerHooks('beforeInsert', makeCtx());
+    expect(calls).toEqual(['body-default-runner']);
+  });
+
+  it('explicit bodyRunner wins over the engine default', async () => {
+    const engine = makeEngine();
+    const calls: string[] = [];
+    engine.setDefaultBodyRunner(() => async () => { calls.push('default'); });
+    const hook: Hook = {
+      name: 'body-explicit', object: 'account', events: ['beforeInsert'], priority: 100,
+      body: { language: 'js', source: "ctx.input.x = 1;" },
+    } as unknown as Hook;
+    engine.bindHooks([hook], {
+      packageId: 'app:x',
+      bodyRunner: () => async () => { calls.push('explicit'); },
+    });
+    await engine.triggerHooks('beforeInsert', makeCtx());
+    expect(calls).toEqual(['explicit']);
+  });
+
   it('keeps hooks bound under different packageIds isolated', async () => {
     const engine = makeEngine();
     const calls: string[] = [];