@plumbus/core 0.2.9 → 0.3.0

package/dist/worker/bootstrap.js

@@ -2,15 +2,90 @@
 // Separate process that starts background workers:
 // outbox dispatcher, event delivery worker, flow step executor,
 // flow scheduler. Handles graceful shutdown.
+import { sql } from 'drizzle-orm';
 import { createAuditService } from '../audit/service.js';
 import { createOutboxDispatcher } from '../events/dispatcher.js';
 import { createEventEmitter } from '../events/emitter.js';
 import { createIdempotencyService } from '../events/idempotency.js';
 import { createEventWorker } from '../events/worker.js';
 import { createExecutionContext } from '../execution/context-factory.js';
-import { createFlowEngine } from '../flows/engine.js';
+import { createFlowEngine, generateWorkerId } from '../flows/engine.js';
+import { FlowStatus } from '../flows/state-machine.js';
 import { createFlowScheduler } from '../flows/scheduler.js';
 import { createFlowTriggerHandler } from '../flows/triggers.js';
+// ── Error description helper ──
+// Drizzle wraps the underlying driver error in `cause`, and its own `message`
+// is just the literal SQL with a "Failed query:" prefix. Without the cause
+// the worker logs hide the actual Postgres failure (missing column, broken
+// constraint, etc.), which makes operational issues — especially schema drift
+// after an `@plumbus/core` upgrade — extremely hard to diagnose.
+//
+// We pull out fields that postgres-js exposes on its error objects (code,
+// detail, hint, position, where, schema, table, column, constraint, routine)
+// in addition to the cause's own message, and surface them as a structured
+// log payload alongside the original error message.
+function describeError(err) {
+    if (!(err instanceof Error)) {
+        return { error: String(err) };
+    }
+    const out = { error: err.message };
+    const cause = err.cause;
+    if (cause instanceof Error) {
+        out.causeMessage = cause.message;
+        const pgFields = [
+            'code',
+            'detail',
+            'hint',
+            'position',
+            'where',
+            'schema',
+            'table',
+            'column',
+            'constraint',
+            'routine',
+            'severity',
+        ];
+        const pg = {};
+        for (const k of pgFields) {
+            const v = cause[k];
+            if (v !== undefined && v !== null && v !== '')
+                pg[k] = v;
+        }
+        if (Object.keys(pg).length > 0)
+            out.pg = pg;
+    }
+    else if (cause !== undefined) {
+        out.cause = String(cause);
+    }
+    return out;
+}
+// ── Lease-column preflight ──
+//
+// 0.3.0 added `lease_owner` and `lease_expires_at` columns to flow_executions
+// to support lease-based claiming across workers. If a consumer upgrades
+// `@plumbus/core` but forgets to run `plumbus migrate generate` +
+// `plumbus migrate apply`, the first claim-cycle UPDATE fails with PG error
+// 42703 (undefined_column) deep inside drizzle, producing logs that don't
+// point at the real fix. This probe runs one cheap `LIMIT 0` SELECT against
+// those columns and rethrows a clear, actionable error when they're missing.
+//
+// Exported for direct testing.
+export async function assertFlowLeaseColumns(db) {
+    try {
+        await db.execute(sql `SELECT lease_owner, lease_expires_at FROM flow_executions LIMIT 0`);
+    }
+    catch (err) {
+        const cause = err instanceof Error ? err.cause : undefined;
+        const pgCode = cause && typeof cause === 'object' && 'code' in cause
+            ? cause.code
+            : undefined;
+        if (pgCode === '42703') {
+            throw new Error('Plumbus 0.3.0 requires new columns on flow_executions (lease_owner, lease_expires_at).\n' +
+                'Run `plumbus migrate generate` then `plumbus migrate apply` before starting workers.');
+        }
+        throw err;
+    }
+}
 /** Create and configure a worker pool with all background processes */
 export function createWorkerPool(poolConfig) {
     const { db, queue, consumers, flows, stepDeps, audit, outboxPollIntervalMs = 1000, schedulerPollIntervalMs = 60_000, flowPollIntervalMs = 1000, enableDispatcher = true, enableEventWorker = true, enableScheduler = true, enableFlowRunner = true, } = poolConfig;
@@ -42,6 +117,11 @@ export function createWorkerPool(poolConfig) {
         audit,
         queue,
         onFlowError: poolConfig.onFlowError,
+        workerId: generateWorkerId(),
+        flowLeaseDurationMs: poolConfig.flowLeaseDurationMs,
+        flowHeartbeatIntervalMs: poolConfig.flowHeartbeatIntervalMs,
+        flowClaimBatchSize: poolConfig.flowClaimBatchSize,
+        logger,
         createDataService: createDataService ? (auth) => createDataService(auth) : undefined,
         createEventService: eventRegistry
             ? (auth) => createEventEmitter({
@@ -79,14 +159,12 @@ export function createWorkerPool(poolConfig) {
     };
     const scheduler = enableScheduler ? createFlowScheduler(schedulerConfig) : null;
     let flowRunnerTimer = null;
-    let flowRunnerPolling = false;
     async function runFlowCycle() {
-        if (!enableFlowRunner || flowRunnerPolling)
+        if (!enableFlowRunner)
             return;
-        flowRunnerPolling = true;
         try {
-            const runnable = await flowEngine.listRunnable(50);
-            if (runnable.length === 0)
+            const claimed = await flowEngine.claimNext();
+            if (claimed.length === 0)
                 return;
             const systemAuth = {
                 userId: 'system-flow-runner',
@@ -115,20 +193,75 @@ export function createWorkerPool(poolConfig) {
                 logger,
                 config: poolConfig.config,
             });
-            for (const executionId of runnable) {
+            for (const row of claimed) {
                 try {
-                    await flowEngine.runNext(executionId, baseCtx);
+                    // Drain consecutive in-flow steps in a single tick.
+                    //
+                    // Why: claimNext() acquires a lease (status='running',
+                    // lease_expires_at = now()+leaseDurationMs) for the whole flow
+                    // execution row. runNext() runs ONE step and, on normal
+                    // advancement (next sequential step, parallel completion, or
+                    // conditional branch), updates currentStep but intentionally
+                    // leaves status='running' and the lease intact. If we returned
+                    // here after a single step, the row would sit idle until the
+                    // lease expired (default 5 min) before claimNext() picked it up
+                    // again — producing multi-minute "no errors, no progress" gaps
+                    // between successive steps of the same flow execution.
+                    //
+                    // Looping while status === Running means the worker that holds
+                    // the lease keeps running steps until the flow either Waits
+                    // (event/delay), Completes, Fails, or is Cancelled. Heartbeats
+                    // inside runNext extend the lease while a step is executing;
+                    // between steps the lease is still valid because we never
+                    // released it. A hard cap (`maxStepsPerCycle`) bounds the loop
+                    // so a runaway conditional/loop in a flow can't monopolise the
+                    // worker forever — when the cap is hit we break, the lease will
+                    // expire normally and another claim cycle (or the same worker)
+                    // will pick the row up.
+                    const maxStepsPerCycle = 1000;
+                    let stepsRun = 0;
+                    while (stepsRun < maxStepsPerCycle) {
+                        const result = await flowEngine.runNext(row.id, baseCtx);
+                        stepsRun += 1;
+                        if (result.status !== FlowStatus.Running) {
+                            break;
+                        }
+                    }
+                    if (stepsRun >= maxStepsPerCycle) {
+                        logger.warn('Flow drain hit maxStepsPerCycle; releasing for next cycle', {
+                            executionId: row.id,
+                            workerId: flowEngine.workerId,
+                            stepsRun,
+                            maxStepsPerCycle,
+                        });
+                    }
                 }
                 catch (err) {
                     logger.error('Flow execution run failed', {
-                        executionId,
-                        error: err instanceof Error ? err.message : String(err),
+                        executionId: row.id,
+                        workerId: flowEngine.workerId,
+                        ...describeError(err),
                     });
+                    // Finalize the row as failed so the next poll cycle doesn't re-claim
+                    // it via the `status='running' AND lease_expires_at < now()`
+                    // crash-recovery branch in claimNext and spin forever. The engine
+                    // method is idempotent and guards on status, so this is safe even
+                    // if the row was concurrently finalized by cancel() or a peer worker.
+                    try {
+                        await flowEngine.markFailedFromRunner(row.id, err);
+                    }
+                    catch (finalizeErr) {
+                        logger.error('Failed to finalize flow execution after run error', {
+                            executionId: row.id,
+                            workerId: flowEngine.workerId,
+                            ...describeError(finalizeErr),
+                        });
+                    }
                 }
             }
         }
-        finally {
-            flowRunnerPolling = false;
+        catch (err) {
+            logger.error('Flow claim cycle failed', describeError(err));
         }
     }
     let running = false;
@@ -136,6 +269,14 @@ export function createWorkerPool(poolConfig) {
         async start() {
             if (running)
                 return;
+            // Schema preflight: 0.3.0 added `lease_owner` and `lease_expires_at`
+            // to flow_executions. Consumers who upgrade `@plumbus/core` but skip
+            // `plumbus migrate apply` would otherwise hit a cryptic UPDATE error
+            // on the first claim cycle. Probe the columns once at startup and
+            // emit an actionable error instead.
+            if (enableFlowRunner) {
+                await assertFlowLeaseColumns(db);
+            }
             running = true;
             // Sync flow schedules to DB
             if (scheduler) {

package/dist/worker/bootstrap.js.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/worker/bootstrap.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,mDAAmD;AACnD,gEAAgE;AAChE,6CAA6C;AAG7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAGzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAIpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAEzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AA4DhE,uEAAuE;AACvE,MAAM,UAAU,gBAAgB,CAAC,UAA4B;IAC3D,MAAM,EACJ,EAAE,EACF,KAAK,EACL,SAAS,EACT,KAAK,EACL,QAAQ,EACR,KAAK,EACL,oBAAoB,GAAG,IAAI,EAC3B,uBAAuB,GAAG,MAAM,EAChC,kBAAkB,GAAG,IAAI,EACzB,gBAAgB,GAAG,IAAI,EACvB,iBAAiB,GAAG,IAAI,EACxB,eAAe,GAAG,IAAI,EACtB,gBAAgB,GAAG,IAAI,GACxB,GAAG,UAAU,CAAC;IAEf,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,IAAI,kBAAkB,EAAE,CAAC;IACzD,MAAM,aAAa,GAAG,UAAU,CAAC,aAAa,CAAC;IAE/C,uCAAuC;IACvC,MAAM,WAAW,GAAG,wBAAwB,CAAC,EAAE,CAAC,CAAC;IAEjD,oBAAoB;IACpB,MAAM,gBAAgB,GAAqB;QACzC,EAAE;QACF,KAAK;QACL,cAAc,EAAE,oBAAoB;KACrC,CAAC;IACF,MAAM,UAAU,GAAG,gBAAgB,CAAC,CAAC,CAAC,sBAAsB,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAEtF,wBAAwB;IACxB,MAAM,iBAAiB,GAAiB;QACtC,EAAE;QACF,KAAK;QACL,SAAS;QACT,WAAW;KACZ,CAAC;IACF,MAAM,WAAW,GAAG,iBAAiB,CAAC,CAAC,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAEpF,0BAA0B;IAC1B,MAAM,EAAE,iBAAiB,EAAE,GAAG,UAAU,CAAC;IACzC,MAAM,gBAAgB,GAAqB;QACzC,EAAE;QACF,QAAQ,EAAE,KAAK;QACf,QAAQ;QACR,KAAK;QACL,KAAK;QACL,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,iBAAiB,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;QACpF,kBAAkB,EAAE,aAAa;YAC/B,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CACP,kBAAkB,CAAC;gBACjB,EAAE;gBACF,IAAI;gBACJ,QAAQ,EAAE,aAAa;gBACvB,KAAK,EAAE,KAAK,IAAI,kBAAkB,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;aACjD,CAAC;YACN,CAAC,CAAC,SAAS;KACd,CAAC;IACF,MAAM,UAAU,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,CAAC;IAEtD,oEAAoE;IACpE,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAU,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC;YACxB,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IACD,IAAI,iBAAiB,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,cAAc,GAAG,wBAAwB,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;QACzF,SAAS,CAAC,QAAQ,CAAC;YACjB,EAAE,EAAE,sBAAsB;YAC1B,UAAU,EAAE,CAAC,GAAG,iBAAiB,CAAC;YAClC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;gBAC1B,MAAM,cAAc,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;YAC7C,CAAC;SACF,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,wCAAwC,iBAAiB,CAAC,IAAI,cAAc,CAAC,CAAC;IAC5F,CAAC;IAED,MAAM,eAAe,GAAoB;QACvC,EAAE;QACF,QAAQ,EAAE,KAAK;QACf,MAAM,EAAE,UAAU;QAClB,cAAc,EAAE,uBAAuB;KACxC,CAAC;IACF,MAAM,SAAS,GAAG,eAAe,CAAC,CAAC,CAAC,mBAAmB,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAChF,IAAI,eAAe,GAA0C,IAAI,CAAC;IAClE,IAAI,iBAAiB,GAAG,KAAK,CAAC;IAE9B,KAAK,UAAU,YAAY;QACzB,IAAI,CAAC,gBAAgB,IAAI,iBAAiB;YAAE,OAAO;QACnD,iBAAiB,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;YACnD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO;YAElC,MAAM,UAAU,GAAG;gBACjB,MAAM,EAAE,oBAAoB;gBAC5B,KAAK,EAAE,CAAC,QAAQ,CAAC;gBACjB,MAAM,EAAE,EAAE;gBACV,QAAQ,EAAE,QAAQ;aACnB,CAAC;YAEF,MAAM,WAAW,GAAG,KAAK,IAAI,kBAAkB,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;YAC1E,MAAM,WAAW,GAAG,UAAU,CAAC,iBAAiB;gBAC9C,CAAC,CAAC,UAAU,CAAC,iBAAiB,EAAE;gBAChC,CAAC,CAAE,EAAkB,CAAC;YACxB,MAAM,YAAY,GAAG,aAAa;gBAChC,CAAC,CAAC,kBAAkB,CAAC;oBACjB,EAAE;oBACF,IAAI,EAAE,UAAU;oBAChB,QAAQ,EAAE,aAAa;oBACvB,KAAK,EAAE,WAAW;iBACnB,CAAC;gBACJ,CAAC,CAAC,SAAS,CAAC;YAEd,MAAM,OAAO,GAAG,sBAAsB,CAAC;gBACrC,IAAI,EAAE,UAAU;gBAChB,IAAI,EAAE,WAAW;gBACjB,MAAM,EAAE,YAAY;gBACpB,EAAE,EAAE,UAAU,CAAC,SAAS;gBACxB,KAAK,EAAE,WAAW;gBAClB,MAAM;gBACN,MAAM,EAAE,UAAU,CAAC,MAA4C;aAChE,CAAC,CAAC;YAEH,KAAK,MAAM,WAAW,IAAI,QAAQ,EAAE,CAAC;gBACnC,IAAI,CAAC;oBACH,MAAM,UAAU,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;gBACjD,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,CAAC,KAAK,CAAC,2BAA2B,EAAE;wBACxC,WAAW;wBACX,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;qBACxD,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,iBAAiB,GAAG,KAAK,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,OAAO;QACL,KAAK,CAAC,KAAK;YACT,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YAEf,4BAA4B;YAC5B,IAAI,SAAS,EAAE,CAAC;gBACd,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,aAAa,EAAE,CAAC;gBAC/C,MAAM,CAAC,IAAI,CAAC,UAAU,MAAM,iBAAiB,CAAC,CAAC;gBAC/C,SAAS,CAAC,KAAK,EAAE,CAAC;gBAClB,MAAM,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;YACxC,CAAC;YAED,IAAI,gBAAgB,EAAE,CAAC;gBACrB,eAAe,GAAG,WAAW,CAAC,GAAG,EAAE;oBACjC,KAAK,YAAY,EAAE,CAAC;gBACtB,CAAC,EAAE,kBAAkB,CAAC,CAAC;gBACvB,KAAK,YAAY,EAAE,CAAC;gBACpB,MAAM,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC;YAC/C,CAAC;YAED,IAAI,UAAU,EAAE,CAAC;gBACf,UAAU,CAAC,KAAK,EAAE,CAAC;gBACnB,MAAM,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;YAC3C,CAAC;YAED,IAAI,WAAW,EAAE,CAAC;gBAChB,WAAW,CAAC,KAAK,EAAE,CAAC;gBACpB,MAAM,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC;YAC/C,CAAC;YAED,MAAM,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;QACrC,CAAC;QAED,KAAK,CAAC,IAAI;YACR,IAAI,CAAC,OAAO;gBAAE,OAAO;YACrB,MAAM,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;YAE5C,wDAAwD;YACxD,IAAI,SAAS,EAAE,CAAC;gBACd,SAAS,CAAC,IAAI,EAAE,CAAC;gBACjB,MAAM,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;YACxC,CAAC;YAED,IAAI,eAAe,EAAE,CAAC;gBACpB,aAAa,CAAC,eAAe,CAAC,CAAC;gBAC/B,eAAe,GAAG,IAAI,CAAC;gBACvB,MAAM,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC;YAC/C,CAAC;YAED,IAAI,UAAU,EAAE,CAAC;gBACf,UAAU,CAAC,IAAI,EAAE,CAAC;gBAClB,MAAM,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;YAC3C,CAAC;YAED,IAAI,WAAW,EAAE,CAAC;gBAChB,WAAW,CAAC,IAAI,EAAE,CAAC;gBACnB,MAAM,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC;YAC/C,CAAC;YAED,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;YACpB,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YAE5B,OAAO,GAAG,KAAK,CAAC;YAChB,MAAM,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;QACrC,CAAC;QAED,IAAI,SAAS;YACX,OAAO,OAAO,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,sBAAsB;AAEtB,SAAS,kBAAkB;IACzB,MAAM,MAAM,GAAG,kBAAkB,CAAC;IAClC,OAAO;QACL,KAAK,CAAC,OAAO,EAAE,QAAQ;YACrB,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,IAAI,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClF,CAAC;QACD,IAAI,CAAC,OAAO,EAAE,QAAQ;YACpB,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,CAAC,OAAO,EAAE,QAAQ;YACpB,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACjF,CAAC;QACD,KAAK,CAAC,OAAO,EAAE,QAAQ;YACrB,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,IAAI,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClF,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/worker/bootstrap.ts"],"names":[],"mappings":"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"}

package/instructions/framework.md

@@ -2,6 +2,13 @@
 
 Plumbus is an AI-native, contract-driven TypeScript application framework. You build applications by composing five primitives — **Entities**, **Capabilities**, **Flows**, **Events**, and **Prompts** — through a controlled execution context (`ctx`).
 
+## Non-Negotiable Guardrails
+
+- Plumbus primitives are the application architecture, not optional helpers.
+- **Capabilities are the only entry point for business logic.** If behavior does not belong in a capability directly, it should be orchestrated by a flow, emitted as an event, modeled as an entity, or wrapped in a prompt.
+- Use framework extension points and `ctx.*` subsystems before inventing custom controllers, service layers, job runners, event buses, or direct infrastructure integrations.
+- If the correct primitive is unclear, stop and ask which Plumbus extension point should own the behavior.
+
 ## Core Abstractions
 
 | Primitive | Purpose | Defined with |

package/instructions/guardrails.md

@@ -0,0 +1,39 @@
+# Agent Guardrails
+
+These rules are mandatory when an AI agent works on a Plumbus application.
+
+## Framework-First Architecture
+
+- Plumbus is the application architecture, not a helper library.
+- All business logic must be implemented through Plumbus primitives: `defineCapability()`, `defineFlow()`, `defineEntity()`, `defineEvent()`, `definePrompt()`, and translations where relevant.
+- If a task seems to require code outside those primitives, stop and ask which Plumbus extension point should be used.
+
+## Non-Negotiable Boundaries
+
+- **Do not** implement business logic in ad hoc API routes, controllers, services, cron files, queues, or background workers when the behavior belongs in a capability, flow, event handler, or prompt.
+- **Do not** bypass `ctx.*` subsystems with direct database clients, custom event buses, raw auth checks, or bespoke AI integration layers unless the framework explicitly documents that extension point.
+- **Do not** import framework internals. Use the public SDK surface only.
+- **Do not** edit generated files in `.plumbus/generated/`.
+- **Do not** install framework-provided dependencies directly in the consumer app.
+
+## Escalation Rule
+
+- When the requirements are unclear, ask which primitive should own the behavior instead of inventing a clean-room architecture.
+- Prefer asking for clarification over adding code that works technically but does not follow the framework contract.
+
+## Git Safety
+
+Read-only git inspection is allowed: `git status`, `git diff`, `git log`, `git show`.
+
+The following actions require explicit user approval because they can discard work or rewrite history:
+
+- `git checkout` when used to restore or overwrite files
+- `git restore`
+- `git reset` of any kind
+- `git clean`
+- `git revert` across user work you did not author
+- `git push --force` or `git push --force-with-lease`
+- deleting branches or tags
+- any command that overwrites, discards, or rewrites existing work
+
+If there is any doubt about whether a git command is destructive, stop and ask first.

package/instructions/patterns.md

@@ -1,5 +1,13 @@
 # Patterns & Conventions
 
+## Framework Boundaries
+
+These rules are non-negotiable. They are architecture constraints, not style preferences.
+
+- **Business logic belongs in Plumbus primitives.** Start with a capability, then compose flows, events, prompts, and entities around it.
+- **Ask before bypassing the framework.** If the task appears to need custom routes, services, jobs, or infrastructure layers, stop and clarify the intended extension point.
+- **Generated code is not an edit surface.** Treat `.plumbus/generated/` as read-only.
+
 ## Naming Conventions
 
 | Element | Convention | Example |
@@ -44,8 +52,10 @@ app/prompts/<name>.prompt.ts
 ## Don'ts
 
 - **Don't** access the database directly — always use `ctx.data.<Entity>`.
+- **Don't** implement business logic in ad hoc controllers, service classes, raw API routes, cron scripts, or queue handlers when a capability or flow should own it.
 - **Don't** emit events outside of capabilities — the outbox pattern requires a capability transaction.
 - **Don't** bypass `ctx.auth` checks — the framework evaluates access policies before your handler runs.
+- **Don't** bypass `ctx.*` subsystems with custom infrastructure layers unless the framework explicitly documents that extension point.
 - **Don't** mutate the `ctx` object — it is scoped and controlled by the framework.
 - **Don't** import framework internals — use only the public SDK surface (`defineCapability`, `defineFlow`, etc.).
 - **Don't** store secrets in code — use `ctx.config` and environment variables.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumbus/core",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "Plumbus framework core — types, SDK, runtime, CLI, test utilities",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,7 +55,8 @@
     "postgres": "^3.4.8",
     "tsx": "^4.19.0",
     "vitest": "^3.0.0",
-    "zod": "^3.24.0"
+    "zod": "^3.24.0",
+    "zod-to-json-schema": "^3.25.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.6",