@plumbus/core 0.7.1 → 0.8.0-beta.1

package/dist/flows/compiled-registry.js

@@ -0,0 +1,198 @@
+// Immutable, versioned registry of compiled flow definitions.
+// Keyed by (flowDefinitionId, definitionVersion). Publishing a version
+// a second time is idempotent only when the digest matches.
+// Disk artifacts from `plumbus compile-flows` reload through
+// loadCompiledFlowRegistryFromDirectory so a new process sees the same pins.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { COMPILED_FLOW_CONTRACT_VERSION, digestCanonicalJson } from './compile-flow.js';
+/** Project-relative default used by `plumbus compile-flows` and boot load. */
+export const DEFAULT_COMPILED_FLOWS_DIRECTORY = '.plumbus/compiled-flows';
+export class CompiledFlowRegistry {
+    versions = new Map();
+    publishOrder = new Map();
+    /**
+     * Publish a compiled definition. Same version + same digest is a no-op.
+     * Same version + different digest is rejected (immutable retain-all).
+     */
+    publish(compiled) {
+        const { flowDefinitionId, definitionVersion, definitionDigest } = compiled;
+        if (!flowDefinitionId || !definitionVersion || !definitionDigest) {
+            throw new Error('Compiled flow definition is missing identity fields');
+        }
+        let byVersion = this.versions.get(flowDefinitionId);
+        if (!byVersion) {
+            byVersion = new Map();
+            this.versions.set(flowDefinitionId, byVersion);
+        }
+        const existing = byVersion.get(definitionVersion);
+        if (existing) {
+            if (existing.definitionDigest !== definitionDigest) {
+                throw new Error(`Flow definition "${flowDefinitionId}@${definitionVersion}" is immutable (digest mismatch)`);
+            }
+            return;
+        }
+        byVersion.set(definitionVersion, compiled);
+        const order = this.publishOrder.get(flowDefinitionId) ?? [];
+        order.push(definitionVersion);
+        this.publishOrder.set(flowDefinitionId, order);
+    }
+    get(flowDefinitionId, definitionVersion) {
+        return this.versions.get(flowDefinitionId)?.get(definitionVersion);
+    }
+    /** Most recently published version for this id (not semver-max). */
+    getLatest(flowDefinitionId) {
+        const latest = this.publishOrder.get(flowDefinitionId)?.at(-1);
+        return latest === undefined ? undefined : this.get(flowDefinitionId, latest);
+    }
+    listVersions(flowDefinitionId) {
+        return [...(this.publishOrder.get(flowDefinitionId) ?? [])];
+    }
+}
+function errorCode(err) {
+    if (err && typeof err === 'object' && 'code' in err && typeof err.code === 'string') {
+        return err.code;
+    }
+    return undefined;
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function readJsonFile(filePath, fileName) {
+    try {
+        return JSON.parse(readFileSync(filePath, 'utf-8'));
+    }
+    catch (err) {
+        if (err instanceof SyntaxError) {
+            throw new Error(`Compiled flow artifact is not valid JSON: ${fileName}`);
+        }
+        throw err;
+    }
+}
+/**
+ * Parse one signed artifact. Recomputes `definitionDigest` and refuses a
+ * mismatch so a tampered file cannot enter the registry.
+ */
+export function parseCompiledFlowArtifact(value, fileName = 'compiled-flow.json') {
+    if (!isRecord(value)) {
+        throw new Error(`Compiled flow artifact is missing identity fields: ${fileName}`);
+    }
+    const { contractVersion, flowDefinitionId, definitionVersion, definitionDigest, domain, name, steps, bindings, } = value;
+    if (contractVersion !== COMPILED_FLOW_CONTRACT_VERSION) {
+        throw new Error(`Compiled flow artifact contract version is not supported: ${fileName}`);
+    }
+    if (typeof flowDefinitionId !== 'string' ||
+        !flowDefinitionId ||
+        typeof definitionVersion !== 'string' ||
+        !definitionVersion ||
+        typeof definitionDigest !== 'string' ||
+        !definitionDigest ||
+        typeof domain !== 'string' ||
+        !domain ||
+        typeof name !== 'string' ||
+        !name ||
+        !Array.isArray(steps) ||
+        !Array.isArray(bindings)) {
+        throw new Error(`Compiled flow artifact is missing identity fields: ${fileName}`);
+    }
+    const { definitionDigest: storedDigest, ...unsigned } = value;
+    const computed = digestCanonicalJson(unsigned);
+    if (typeof storedDigest !== 'string' || computed !== storedDigest) {
+        throw new Error(`Compiled flow artifact digest does not match: ${flowDefinitionId}@${definitionVersion}`);
+    }
+    return value;
+}
+function listCompiledFlowJsonFiles(directory) {
+    const root = resolve(directory);
+    let names;
+    try {
+        names = readdirSync(root);
+    }
+    catch (err) {
+        if (errorCode(err) === 'ENOENT') {
+            throw new Error(`Compiled flow directory does not exist: ${directory}`);
+        }
+        if (errorCode(err) === 'ENOTDIR') {
+            throw new Error(`Compiled flow path is not a directory: ${directory}`);
+        }
+        throw err;
+    }
+    return names
+        .filter((name) => name.endsWith('.json'))
+        .filter((name) => {
+        try {
+            return statSync(join(root, name)).isFile();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort();
+}
+/**
+ * Load signed JSON from a host-owned directory (the `plumbus compile-flows`
+ * output). Each file is digest-checked; a mismatch refuses the whole load.
+ */
+export function loadCompiledFlowRegistryFromDirectory(directory) {
+    const trimmed = directory.trim();
+    if (!trimmed) {
+        throw new Error('Compiled flow directory is required');
+    }
+    const root = resolve(trimmed);
+    const fileNames = listCompiledFlowJsonFiles(root);
+    const registry = new CompiledFlowRegistry();
+    for (const fileName of fileNames) {
+        const parsed = readJsonFile(join(root, fileName), fileName);
+        registry.publish(parseCompiledFlowArtifact(parsed, fileName));
+    }
+    return registry;
+}
+/**
+ * Same as `loadCompiledFlowRegistryFromDirectory`, but a missing or empty
+ * directory is "not configured" (`undefined`) so live TypeScript flows stay
+ * on. A directory that exists with invalid JSON still throws.
+ */
+export function tryLoadCompiledFlowRegistryFromDirectory(directory) {
+    const trimmed = directory.trim();
+    if (!trimmed)
+        return undefined;
+    const root = resolve(trimmed);
+    if (!existsSync(root))
+        return undefined;
+    try {
+        if (!statSync(root).isDirectory()) {
+            throw new Error(`Compiled flow path is not a directory: ${directory}`);
+        }
+    }
+    catch (err) {
+        if (errorCode(err) === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+    const fileNames = listCompiledFlowJsonFiles(root);
+    if (fileNames.length === 0)
+        return undefined;
+    return loadCompiledFlowRegistryFromDirectory(root);
+}
+/**
+ * Prefer an explicit registry. Else load `compiledFlowsDirectory` (required
+ * when set). Else try `{cwd}/.plumbus/compiled-flows` when that tree has JSON.
+ */
+export function resolveCompiledFlowRegistry(options = {}) {
+    if (options.compiledRegistry)
+        return options.compiledRegistry;
+    if (options.compiledFlowsDirectory !== undefined) {
+        const directory = options.compiledFlowsDirectory.trim();
+        if (!directory) {
+            throw new Error('Compiled flow directory is required');
+        }
+        const fileNames = listCompiledFlowJsonFiles(resolve(directory));
+        if (fileNames.length === 0) {
+            throw new Error(`Compiled flow directory has no artifacts: ${directory}`);
+        }
+        return loadCompiledFlowRegistryFromDirectory(directory);
+    }
+    const cwd = options.cwd ?? process.cwd();
+    return tryLoadCompiledFlowRegistryFromDirectory(join(cwd, DEFAULT_COMPILED_FLOWS_DIRECTORY));
+}
+//# sourceMappingURL=compiled-registry.js.map

package/dist/flows/compiled-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiled-registry.js","sourceRoot":"","sources":["../../src/flows/compiled-registry.ts"],"names":[],"mappings":"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"}

package/dist/flows/dead-letter.d.ts

@@ -1,4 +1,14 @@
 import type { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+export interface OperatorRetryOptions {
+    actor: string;
+    reason?: string;
+}
+export interface OperatorRetryResult {
+    executionId: string;
+    flowName: string;
+    retriedBy: string;
+    retriedAt: string;
+}
 /**
  * Moves failed flow executions to the dead-letter table.
  * Call this after a flow has exhausted retries and entered Failed status.
@@ -9,4 +19,10 @@ export declare function deadLetterFlow(db: PostgresJsDatabase, executionId: stri
  * Returns the number of executions moved.
  */
 export declare function sweepFailedFlows(db: PostgresJsDatabase, limit?: number): Promise<number>;
+/**
+ * Operator recovery: reset a dead-lettered execution so it can run again.
+ * Attribution is recorded on the dead-letter row and execution state.
+ * Failed → Created is an operator exception (not a normal state-machine edge).
+ */
+export declare function retryDeadLetteredFlow(db: PostgresJsDatabase, executionId: string, opts: OperatorRetryOptions): Promise<OperatorRetryResult>;
 //# sourceMappingURL=dead-letter.d.ts.map

package/dist/flows/dead-letter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dead-letter.d.ts","sourceRoot":"","sources":["../../src/flows/dead-letter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAIlE;;;GAGG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoC/F;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,SAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB3F"}
+{"version":3,"file":"dead-letter.d.ts","sourceRoot":"","sources":["../../src/flows/dead-letter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAIlE,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoC/F;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,SAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB3F;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,kBAAkB,EACtB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,mBAAmB,CAAC,CAuE9B"}

package/dist/flows/dead-letter.js

@@ -60,4 +60,71 @@ export async function sweepFailedFlows(db, limit = 100) {
     }
     return moved;
 }
+/**
+ * Operator recovery: reset a dead-lettered execution so it can run again.
+ * Attribution is recorded on the dead-letter row and execution state.
+ * Failed → Created is an operator exception (not a normal state-machine edge).
+ */
+export async function retryDeadLetteredFlow(db, executionId, opts) {
+    if (!opts.actor?.trim()) {
+        throw new Error('Operator retry requires an actor');
+    }
+    const dlqRows = await db
+        .select()
+        .from(flowDeadLetterTable)
+        .where(eq(flowDeadLetterTable.executionId, executionId))
+        .limit(1);
+    const dlq = dlqRows[0];
+    if (!dlq) {
+        throw new Error(`Dead-letter row for execution "${executionId}" not found`);
+    }
+    const existingMeta = dlq.metadata && typeof dlq.metadata === 'object' && !Array.isArray(dlq.metadata)
+        ? dlq.metadata
+        : {};
+    if (existingMeta.retriedAt) {
+        throw new Error(`Execution "${executionId}" was already retried by ${String(existingMeta.retriedBy)}`);
+    }
+    const execRows = await db
+        .select()
+        .from(flowExecutionsTable)
+        .where(eq(flowExecutionsTable.id, executionId))
+        .limit(1);
+    const row = execRows[0];
+    if (!row)
+        throw new Error(`Flow execution "${executionId}" not found`);
+    const retriedAt = new Date().toISOString();
+    const attribution = {
+        retriedBy: opts.actor,
+        retriedAt,
+        reason: opts.reason ?? 'operator-retry',
+    };
+    const priorState = row.state && typeof row.state === 'object' && !Array.isArray(row.state)
+        ? row.state
+        : {};
+    await db
+        .update(flowExecutionsTable)
+        .set({
+        status: FlowStatus.Created,
+        retryCount: 0,
+        lastError: null,
+        completedAt: null,
+        leaseOwner: null,
+        leaseExpiresAt: null,
+        state: { ...priorState, __operatorRetry: attribution },
+        updatedAt: new Date(),
+    })
+        .where(eq(flowExecutionsTable.id, executionId));
+    await db
+        .update(flowDeadLetterTable)
+        .set({
+        metadata: { ...existingMeta, ...attribution },
+    })
+        .where(eq(flowDeadLetterTable.executionId, executionId));
+    return {
+        executionId,
+        flowName: row.flowName,
+        retriedBy: opts.actor,
+        retriedAt,
+    };
+}
 //# sourceMappingURL=dead-letter.js.map

package/dist/flows/dead-letter.js.map

@@ -1 +1 @@
-{"version":3,"file":"dead-letter.js","sourceRoot":"","sources":["../../src/flows/dead-letter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEjC,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,EAAsB,EAAE,WAAmB;IAC9E,MAAM,IAAI,GAAG,MAAM,EAAE;SAClB,MAAM,EAAE;SACR,IAAI,CAAC,mBAAmB,CAAC;SACzB,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;SAC9C,KAAK,CAAC,CAAC,CAAC,CAAC;IAEZ,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,WAAW,aAAa,CAAC,CAAC;IAEvE,IAAI,GAAG,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,4BAA4B,WAAW,kBAAkB,GAAG,CAAC,MAAM,sBAAsB,CAC1F,CAAC;IACJ,CAAC;IAED,MAAM,EAAE;SACL,MAAM,CAAC,mBAAmB,CAAC;SAC3B,MAAM,CAAC;QACN,WAAW,EAAE,GAAG,CAAC,EAAE;QACnB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,KAAK,EAAE,GAAG,CAAC,KAAY;QACvB,KAAK,EAAE,GAAG,CAAC,KAAY;QACvB,WAAW,EAAE,GAAG,CAAC,WAAkB;QACnC,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,QAAQ,EAAE;YACR,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,aAAa,EAAE,GAAG,CAAC,aAAa;YAChC,cAAc,EAAE,GAAG,CAAC,cAAc;YAClC,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,WAAW,EAAE;YACvC,QAAQ,EAAE,GAAG,CAAC,WAAW,EAAE,WAAW,EAAE;SACzC;KACF,CAAC;SACD,mBAAmB,CAAC,EAAE,MAAM,EAAE,mBAAmB,CAAC,WAAW,EAAE,CAAC,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,EAAsB,EAAE,KAAK,GAAG,GAAG;IACxE,MAAM,UAAU,GAAG,MAAM,EAAE;SACxB,MAAM,CAAC,EAAE,EAAE,EAAE,mBAAmB,CAAC,EAAE,EAAE,CAAC;SACtC,IAAI,CAAC,mBAAmB,CAAC;SACzB,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;SACxD,KAAK,CAAC,KAAK,CAAC,CAAC;IAEhB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,cAAc,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;YACjC,KAAK,EAAE,CAAC;QACV,CAAC;QAAC,MAAM,CAAC;YACP,2DAA2D;QAC7D,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"dead-letter.js","sourceRoot":"","sources":["../../src/flows/dead-letter.ts"],"names":[],"mappings":"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"}

package/dist/flows/definition-strategy.d.ts

@@ -0,0 +1,13 @@
+import { PlumbusError } from '../errors/plumbus-error.js';
+export declare const DEFINITION_STRATEGY_NOT_SUPPORTED: "definition-strategy-not-supported";
+export declare const DefinitionInFlightStrategy: {
+    readonly CompleteOnOriginal: "complete-on-original";
+    readonly StopAndRecover: "stop-and-recover";
+    readonly Migrate: "migrate";
+};
+export type DefinitionInFlightStrategy = (typeof DefinitionInFlightStrategy)[keyof typeof DefinitionInFlightStrategy];
+export declare class DefinitionStrategyNotSupportedError extends PlumbusError {
+    constructor(strategy: string);
+}
+export declare function assertSupportedDefinitionStrategy(strategy: string): asserts strategy is Exclude<DefinitionInFlightStrategy, typeof DefinitionInFlightStrategy.Migrate>;
+//# sourceMappingURL=definition-strategy.d.ts.map

package/dist/flows/definition-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition-strategy.d.ts","sourceRoot":"","sources":["../../src/flows/definition-strategy.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG1D,eAAO,MAAM,iCAAiC,EAAG,mCAA4C,CAAC;AAE9F,eAAO,MAAM,0BAA0B;;;;CAI7B,CAAC;AAEX,MAAM,MAAM,0BAA0B,GACpC,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,OAAO,0BAA0B,CAAC,CAAC;AAE/E,qBAAa,mCAAoC,SAAQ,YAAY;gBACvD,QAAQ,EAAE,MAAM;CAO7B;AAED,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,QAAQ,IAAI,OAAO,CAC5B,0BAA0B,EAC1B,OAAO,0BAA0B,CAAC,OAAO,CAC1C,CAUA"}

package/dist/flows/definition-strategy.js

@@ -0,0 +1,30 @@
+// In-flight definition strategies.
+// v1 implements complete-on-original and stop-and-recover.
+// migrate is refused with a stable error — not a silent no-op.
+import { PlumbusError } from '../errors/plumbus-error.js';
+import { ErrorCode } from '../types/enums.js';
+export const DEFINITION_STRATEGY_NOT_SUPPORTED = 'definition-strategy-not-supported';
+export const DefinitionInFlightStrategy = {
+    CompleteOnOriginal: 'complete-on-original',
+    StopAndRecover: 'stop-and-recover',
+    Migrate: 'migrate',
+};
+export class DefinitionStrategyNotSupportedError extends PlumbusError {
+    constructor(strategy) {
+        super(ErrorCode.Validation, `Definition in-flight strategy "${strategy}" is not supported`, {
+            reason: DEFINITION_STRATEGY_NOT_SUPPORTED,
+            strategy,
+        });
+        this.name = 'DefinitionStrategyNotSupportedError';
+    }
+}
+export function assertSupportedDefinitionStrategy(strategy) {
+    if (strategy === DefinitionInFlightStrategy.Migrate || strategy === 'migrate') {
+        throw new DefinitionStrategyNotSupportedError(DefinitionInFlightStrategy.Migrate);
+    }
+    if (strategy !== DefinitionInFlightStrategy.CompleteOnOriginal &&
+        strategy !== DefinitionInFlightStrategy.StopAndRecover) {
+        throw new DefinitionStrategyNotSupportedError(strategy);
+    }
+}
+//# sourceMappingURL=definition-strategy.js.map

package/dist/flows/definition-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition-strategy.js","sourceRoot":"","sources":["../../src/flows/definition-strategy.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,2DAA2D;AAC3D,+DAA+D;AAE/D,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,MAAM,CAAC,MAAM,iCAAiC,GAAG,mCAA4C,CAAC;AAE9F,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,kBAAkB,EAAE,sBAAsB;IAC1C,cAAc,EAAE,kBAAkB;IAClC,OAAO,EAAE,SAAS;CACV,CAAC;AAKX,MAAM,OAAO,mCAAoC,SAAQ,YAAY;IACnE,YAAY,QAAgB;QAC1B,KAAK,CAAC,SAAS,CAAC,UAAU,EAAE,kCAAkC,QAAQ,oBAAoB,EAAE;YAC1F,MAAM,EAAE,iCAAiC;YACzC,QAAQ;SACT,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,qCAAqC,CAAC;IACpD,CAAC;CACF;AAED,MAAM,UAAU,iCAAiC,CAC/C,QAAgB;IAKhB,IAAI,QAAQ,KAAK,0BAA0B,CAAC,OAAO,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC9E,MAAM,IAAI,mCAAmC,CAAC,0BAA0B,CAAC,OAAO,CAAC,CAAC;IACpF,CAAC;IACD,IACE,QAAQ,KAAK,0BAA0B,CAAC,kBAAkB;QAC1D,QAAQ,KAAK,0BAA0B,CAAC,cAAc,EACtD,CAAC;QACD,MAAM,IAAI,mCAAmC,CAAC,QAAQ,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC"}

package/dist/flows/engine.d.ts

@@ -1,8 +1,12 @@
 import type { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+import type { ApprovalService } from '../approvals/types.js';
 import type { EventQueue } from '../events/queue.js';
 import type { AuditService } from '../types/audit.js';
 import type { DataService, EventService, ExecutionContext, FlowExecution, LoggerService } from '../types/context.js';
 import type { AuthContext } from '../types/security.js';
+import type { DataPlaneResolver } from '../tenancy/types.js';
+import type { CompiledFlowRegistry } from './compiled-registry.js';
+import { type DefinitionInFlightStrategy as DefinitionInFlightStrategyName } from './definition-strategy.js';
 import type { FlowRegistry } from './registry.js';
 import { type StepExecutorDeps } from './step-executor.js';
 export interface FlowEngineConfig {
@@ -44,6 +48,27 @@ export interface FlowEngineConfig {
      * land in the same `[plumbus:worker]` stream as everything else.
      */
     logger?: LoggerService;
+    /**
+     * Protocol A: claim wake-ups from a spine database, then load tenant-local
+     * flow_executions / execution_state via the resolver. Omitted, the engine
+     * keeps today's single-database claim loop on `flow_executions`.
+     */
+    spineDispatch?: FlowSpineDispatchConfig;
+    /**
+     * Optional compiled-definition registry. When set,
+     * the engine consumes compiled JSON (not live TypeScript steps):
+     * `start` requires a published version and pins it on `flow_executions`.
+     * Omitted: existing live-TS `FlowRegistry` path is unchanged.
+     */
+    compiledRegistry?: CompiledFlowRegistry;
+    /** Stage 4 approval service — required for `approval-outcome` steps. */
+    approvals?: ApprovalService;
+}
+export interface FlowSpineDispatchConfig {
+    db: PostgresJsDatabase;
+    resolver: DataPlaneResolver;
+    /** Schema holding tenant durable tables. Default `core_plumbus`. */
+    coreSchema?: string;
 }
 interface FlowExecutionRow {
     id: string;
@@ -68,6 +93,8 @@ interface FlowExecutionRow {
     completedAt: Date | null;
     leaseOwner: string | null;
     leaseExpiresAt: Date | null;
+    definitionVersion: string | null;
+    definitionDigest: string | null;
 }
 /**
  * Generate a deterministic-ish worker id for the current process.
@@ -92,9 +119,19 @@ export declare function createFlowEngine(config: FlowEngineConfig): {
     listRunnable: (limit?: number) => Promise<string[]>;
     claimNext: (batchSize?: number) => Promise<FlowExecutionRow[]>;
     claimExecution: (executionId: string) => Promise<FlowExecutionRow | undefined>;
-    cancel: (executionId: string) => Promise<void>;
+    cancel: (executionId: string, opts?: {
+        actor?: string;
+        skipCompensation?: boolean;
+    }) => Promise<void>;
+    terminate: (executionId: string, opts?: {
+        actor?: string;
+    }) => Promise<void>;
     status: (executionId: string) => Promise<FlowExecution>;
     markFailedFromRunner: (executionId: string, error: unknown) => Promise<boolean>;
+    applyDefinitionStrategy: (executionId: string, strategy: string) => Promise<{
+        strategy: DefinitionInFlightStrategyName;
+        applied: true;
+    }>;
     readonly workerId: string;
 };
 /**

package/dist/flows/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/flows/engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/flows/engine.ts"],"names":[],"mappings":"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"}