fix(automation): bind flow triggers on cold boot, not just after HMR reload

Record-triggered flows silently never fired after a fresh process start. The
boot-time flow pull reads ql.registry.listItems('flow'), which is EMPTY for
flows defined inline in an app manifest (registerApp stores the app under type
'app' and never promotes its inline flows to standalone registry 'flow'
items). Those flows live only in the metadata service, and the sole path that
reads it — the 'metadata:reloaded' re-sync — fires only on a dev HMR reload,
never on a cold boot or in production. So after any real restart, no flow
bound its trigger and record-change automations did not fire until an
unrelated src edit triggered an HMR reload.

Bind flows from the metadata service once at 'kernel:ready' (after every
plugin's init/start, when the metadata service is fully populated), reusing
the idempotent resyncFlowsFromMetadata(). Regression test boots a kernel with
an inline-app record-triggered flow and asserts it is bound after bootstrap()
with no metadata:reloaded fired — fails on the pre-fix code.

Found dogfooding a Studio-built automation end-to-end on a clean instance:
record hooks fired but flows never did; 0 flows bound at boot while the
metadata service held 20.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

.changeset/automation-bind-flows-cold-boot.md

@@ -0,0 +1,26 @@
+---
+"@objectstack/service-automation": patch
+---
+
+fix(automation): bind flow triggers on a cold boot, not just after an HMR reload
+
+Record-triggered (and other trigger-typed) flows silently never fired on a
+fresh process start. The automation service's boot-time flow pull reads
+`ql.registry.listItems('flow')`, which is **empty for flows defined inline in
+an app manifest** — `registry.registerApp()` stores the app under type `'app'`
+and never promotes its inline flows to standalone registry `'flow'` items.
+Those flows live only in the metadata service (which flattens them), and the
+one path that reads it — the `metadata:reloaded` re-sync — fires solely on a
+dev HMR reload, never on a cold boot (or in production).
+
+Net effect: after any real restart, no flow bound its trigger, so
+record-change automations did not fire until an unrelated source edit happened
+to trigger an HMR reload that ran the re-sync.
+
+Fix: bind flows from the metadata service once at `kernel:ready` — after every
+plugin has finished `init()`/`start()` and the metadata service is fully
+populated. This reuses the existing `resyncFlowsFromMetadata()` (idempotent
+with the boot pull, so it is safe whichever source held the flow). Added a
+regression test that boots the kernel with an inline-app record-triggered flow
+and asserts it is bound after `bootstrap()` alone — with no `metadata:reloaded`
+ever fired — which fails on the pre-fix code.

packages/services/service-automation/src/flow-cold-boot-bind.test.ts

@@ -0,0 +1,127 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// Regression: a record-triggered flow must bind on a COLD boot.
+//
+// Flows defined inline in an app manifest live only in the metadata service —
+// registerApp stores the app under type 'app' and never promotes its inline
+// flows to standalone registry 'flow' items, so the automation boot pull
+// (`ql.registry.listItems('flow')`) sees ZERO of them. The metadata-based
+// re-sync that DOES see them fires only on 'metadata:reloaded', which never
+// fires on a fresh boot (or in production). The bug: record-triggered
+// automations silently never bound on a cold start, so they never fired until
+// an unrelated src edit happened to trigger an HMR reload.
+//
+// The fix binds flows from the metadata service at 'kernel:ready'. This proves
+// the flow is bound after bootstrap() alone — with NO 'metadata:reloaded' ever
+// fired, and NO objectql registry present (mirroring the empty boot pull).
+
+import { describe, it, expect } from 'vitest';
+import { LiteKernel } from '@objectstack/core';
+import { AutomationEngine } from './engine.js';
+import { AutomationServicePlugin } from './plugin.js';
+import type { FlowTrigger, FlowTriggerBinding } from './engine.js';
+import type { AutomationContext } from '@objectstack/spec/contracts';
+
+const flush = () => new Promise<void>((r) => setTimeout(r, 0));
+
+/** A record-after-update triggered flow, the shape the metadata service serves. */
+function recordTriggeredFlow(name: string, object: string) {
+    return {
+        name,
+        label: name,
+        type: 'autolaunched',
+        nodes: [
+            {
+                id: 'start',
+                type: 'start',
+                label: 'Start',
+                config: { objectName: object, triggerType: 'record-after-update', condition: 'status == "done"' },
+            },
+            { id: 'end', type: 'end', label: 'End' },
+        ],
+        edges: [{ id: 'e1', source: 'start', target: 'end' }],
+    };
+}
+
+/** A recording FlowTrigger of type 'record_change' (stands in for the real one). */
+function recordingRecordChangeTrigger() {
+    const bound = new Map<string, (ctx: AutomationContext) => Promise<void>>();
+    const trigger: FlowTrigger = {
+        type: 'record_change',
+        start(binding: FlowTriggerBinding, cb: (ctx: AutomationContext) => Promise<void>) {
+            bound.set(binding.flowName, cb);
+        },
+        stop(flowName: string) {
+            bound.delete(flowName);
+        },
+    };
+    return {
+        trigger,
+        has: (n: string) => bound.has(n),
+        fire: async (n: string) => {
+            await bound.get(n)?.({ event: 'record_change', params: { flowName: n } } as AutomationContext);
+        },
+    };
+}
+
+/** Only the `list('flow')` the metadata re-sync reads — no objectql registry. */
+function fakeMetadataService(flows: unknown[]) {
+    return {
+        async list(type: string) {
+            return type === 'flow' ? flows : [];
+        },
+    };
+}
+
+/**
+ * Boot with a metadata service that HAS the flow but NO objectql registry, so
+ * the boot pull is empty — exactly the inline-app-flow cold-boot scenario. The
+ * recording record-change trigger is registered during init (before
+ * kernel:ready), the way the real RecordChangeTriggerPlugin registers its
+ * trigger, so the kernel:ready bind can find it.
+ */
+async function bootKernel(flows: unknown[], rec: ReturnType<typeof recordingRecordChangeTrigger>) {
+    const kernel = new LiteKernel({ logger: { level: 'silent' } } as never);
+    kernel.use(new AutomationServicePlugin());
+    const harness = {
+        name: 'test.harness',
+        type: 'standard' as const,
+        version: '1.0.0',
+        dependencies: [] as string[],
+        async init(ctx: any) {
+            ctx.registerService('metadata', fakeMetadataService(flows));
+            // AutomationServicePlugin.init() ran first (registered above), so the
+            // engine service exists; register the trigger before kernel:ready.
+            ctx.getService('automation').registerTrigger(rec.trigger);
+        },
+        async start() {},
+    };
+    kernel.use(harness as never);
+    await kernel.bootstrap();
+    return kernel;
+}
+
+describe('record-triggered flow binds on cold boot (kernel:ready sync)', () => {
+    it('binds an inline-app record flow after bootstrap() with no metadata:reloaded', async () => {
+        const rec = recordingRecordChangeTrigger();
+        const kernel = await bootKernel([recordTriggeredFlow('notify_on_done', 'task')], rec);
+        await flush();
+
+        // The core fix: the flow is bound to its record-change trigger after a
+        // plain cold boot — no 'metadata:reloaded' was ever fired.
+        expect(rec.has('notify_on_done'), 'record-triggered flow bound at kernel:ready').toBe(true);
+
+        const engine = kernel.getService<AutomationEngine>('automation');
+        expect(engine.getActiveTriggerBindings().map((b) => b.flowName)).toContain('notify_on_done');
+
+        await kernel.shutdown();
+    });
+
+    it('does not bind when the metadata service serves no flows', async () => {
+        const rec = recordingRecordChangeTrigger();
+        const kernel = await bootKernel([], rec);
+        await flush();
+        expect(rec.has('notify_on_done')).toBe(false);
+        await kernel.shutdown();
+    });
+});

packages/services/service-automation/src/plugin.ts

@@ -239,6 +239,26 @@ export class AutomationServicePlugin implements Plugin {
             await this.resyncFlowsFromMetadata(ctx);
         });
 
+        // ── Cold-boot bind from the METADATA SERVICE ──────────────────────────
+        // The boot pull above reads `ql.registry.listItems('flow')`, which is
+        // EMPTY for flows defined inline in an app manifest: registerApp stores
+        // the app under type 'app' and never promotes its inline flows to
+        // standalone registry 'flow' items. Those flows DO live in the metadata
+        // service (it flattens app flows into the 'flow' collection), but the
+        // only path that reads it — the 'metadata:reloaded' re-sync above —
+        // fires solely on a dev HMR reload, NOT on a fresh boot (and never in
+        // production). The net effect was that record-triggered flows silently
+        // never bound on a cold start, so their automations never fired until an
+        // unrelated src edit happened to trigger an HMR reload.
+        //
+        // Bind from the metadata service once at kernel:ready — after every
+        // plugin has finished init()/start() and the metadata service is fully
+        // populated. resyncFlowsFromMetadata() is idempotent with the boot pull
+        // (registerFlow re-binds), so it is safe whichever source held the flow.
+        ctx.hook('kernel:ready', async () => {
+            await this.resyncFlowsFromMetadata(ctx);
+        });
+
         // ADR-0019 follow-up: re-arm auto-resume timers for runs that were
         // suspended at a timer-`wait` node when the process went down. Must run
         // *after* the flow pull above — resume() needs the flow definitions