@telora/factory 0.4.5

package/dist/watchdogs.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Operational watchdogs for execution unit health monitoring.
+ *
+ * Three watchdogs run during each checkBuilding() poll cycle:
+ *   1. Assignment timeout -- units stuck in 'assigned' state too long
+ *   2. Work unit dispatch timeout -- dispatched work units not completing
+ *   3. Signal silence -- running units with no stdout activity
+ *
+ * Each watchdog creates an escalation when its threshold is breached.
+ * Timeout values come from the blueprint (nullable), falling back to
+ * compile-time defaults.
+ */
+import type { FactoryInstanceState } from './types.js';
+import { createFactoryEscalation } from './queries/escalations.js';
+import { updateExecutionUnit } from './queries/execution-units.js';
+/** 5 minutes -- how long a unit can stay in 'assigned' before escalation. */
+export declare const DEFAULT_ASSIGNMENT_TIMEOUT_MS: number;
+/** 30 minutes -- how long a dispatched work unit can run before escalation. */
+export declare const DEFAULT_WORK_UNIT_TIMEOUT_MS: number;
+/** 10 minutes -- how long without stdout before escalation. */
+export declare const DEFAULT_SIGNAL_SILENCE_TIMEOUT_MS: number;
+export interface WatchdogResult {
+    assignmentTimeouts: number;
+    dispatchTimeouts: number;
+    signalSilenceAlerts: number;
+}
+/** Injectable dependencies for testing. */
+export interface WatchdogDeps {
+    createEscalation: typeof createFactoryEscalation;
+    updateUnit: typeof updateExecutionUnit;
+}
+export declare function runWatchdogs(state: FactoryInstanceState, now?: Date, deps?: WatchdogDeps): Promise<WatchdogResult>;
+//# sourceMappingURL=watchdogs.d.ts.map

package/dist/watchdogs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchdogs.d.ts","sourceRoot":"","sources":["../src/watchdogs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAQnE,6EAA6E;AAC7E,eAAO,MAAM,6BAA6B,QAAgB,CAAC;AAE3D,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,QAAiB,CAAC;AAE3D,+DAA+D;AAC/D,eAAO,MAAM,iCAAiC,QAAiB,CAAC;AAMhE,MAAM,WAAW,cAAc;IAC7B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,gBAAgB,EAAE,OAAO,uBAAuB,CAAC;IACjD,UAAU,EAAE,OAAO,mBAAmB,CAAC;CACxC;AAiBD,wBAAsB,YAAY,CAChC,KAAK,EAAE,oBAAoB,EAC3B,GAAG,GAAE,IAAiB,EACtB,IAAI,GAAE,YAA0B,GAC/B,OAAO,CAAC,cAAc,CAAC,CAczB"}

package/dist/watchdogs.js

@@ -0,0 +1,170 @@
+/**
+ * Operational watchdogs for execution unit health monitoring.
+ *
+ * Three watchdogs run during each checkBuilding() poll cycle:
+ *   1. Assignment timeout -- units stuck in 'assigned' state too long
+ *   2. Work unit dispatch timeout -- dispatched work units not completing
+ *   3. Signal silence -- running units with no stdout activity
+ *
+ * Each watchdog creates an escalation when its threshold is breached.
+ * Timeout values come from the blueprint (nullable), falling back to
+ * compile-time defaults.
+ */
+import { createFactoryEscalation } from './queries/escalations.js';
+import { updateExecutionUnit } from './queries/execution-units.js';
+const LOG_PREFIX = '[watchdog]';
+// ============================================================================
+// Default timeouts (used when blueprint columns are NULL)
+// ============================================================================
+/** 5 minutes -- how long a unit can stay in 'assigned' before escalation. */
+export const DEFAULT_ASSIGNMENT_TIMEOUT_MS = 5 * 60 * 1000;
+/** 30 minutes -- how long a dispatched work unit can run before escalation. */
+export const DEFAULT_WORK_UNIT_TIMEOUT_MS = 30 * 60 * 1000;
+/** 10 minutes -- how long without stdout before escalation. */
+export const DEFAULT_SIGNAL_SILENCE_TIMEOUT_MS = 10 * 60 * 1000;
+// ============================================================================
+// Watchdog runner
+// ============================================================================
+/**
+ * Run all watchdog checks for a factory instance.
+ *
+ * Called from checkBuilding() on each poll cycle. Returns counts of
+ * how many escalations were created.
+ */
+const defaultDeps = {
+    createEscalation: createFactoryEscalation,
+    updateUnit: updateExecutionUnit,
+};
+export async function runWatchdogs(state, now = new Date(), deps = defaultDeps) {
+    const result = {
+        assignmentTimeouts: 0,
+        dispatchTimeouts: 0,
+        signalSilenceAlerts: 0,
+    };
+    const bp = state.blueprint;
+    result.assignmentTimeouts = await checkAssignmentTimeouts(state, bp, now, deps);
+    result.dispatchTimeouts = await checkDispatchTimeouts(state, bp, now, deps);
+    result.signalSilenceAlerts = await checkSignalSilence(state, bp, now, deps);
+    return result;
+}
+// ============================================================================
+// Individual watchdogs
+// ============================================================================
+/**
+ * Check for execution units stuck in 'assigned' state beyond the timeout.
+ *
+ * When a unit is assigned by the scheduler but never transitions to 'running'
+ * (e.g., session spawn failed silently), this watchdog catches it, creates an
+ * escalation, and resets the unit to 'idle' so the scheduler can retry.
+ */
+async function checkAssignmentTimeouts(state, blueprint, now, deps) {
+    const timeoutMs = blueprint.unitAssignmentTimeoutMs ?? DEFAULT_ASSIGNMENT_TIMEOUT_MS;
+    let count = 0;
+    for (const unit of state.executionUnits.values()) {
+        if (unit.status !== 'assigned' || !unit.assignedAt)
+            continue;
+        const elapsed = now.getTime() - unit.assignedAt.getTime();
+        if (elapsed < timeoutMs)
+            continue;
+        console.warn(`${LOG_PREFIX} Unit ${unit.slotIndex} stuck in assigned state for ${Math.round(elapsed / 1000)}s ` +
+            `(timeout: ${timeoutMs}ms) -- resetting to idle`);
+        try {
+            await deps.createEscalation(state.instanceId, 'assignment_timeout', `Execution unit slot ${unit.slotIndex} (${unit.unitId}) was assigned to strategy ` +
+                `${unit.assignedStrategyId ?? 'unknown'} for ${Math.round(elapsed / 1000)}s without ` +
+                `transitioning to running. Reset to idle.`);
+        }
+        catch (err) {
+            console.error(`${LOG_PREFIX} Failed to create escalation for unit ${unit.unitId}: ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Reset unit to idle in DB and in-memory
+        try {
+            await deps.updateUnit(unit.unitId, {
+                status: 'idle',
+                assignedStrategyId: null,
+                assignedAt: null,
+                claudeSessionId: null,
+            });
+        }
+        catch (err) {
+            console.error(`${LOG_PREFIX} Failed to reset unit ${unit.unitId}: ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+        unit.status = 'idle';
+        unit.assignedStrategyId = null;
+        unit.assignedAt = null;
+        unit.claudeSessionId = null;
+        count++;
+    }
+    return count;
+}
+/**
+ * Check for dispatched work units that have not completed within the timeout.
+ *
+ * Unlike assignment timeout, this does NOT auto-reset the work unit. It
+ * creates an escalation and lets the escalation handler decide how to proceed.
+ */
+async function checkDispatchTimeouts(state, blueprint, now, deps) {
+    const timeoutMs = blueprint.workUnitTimeoutMs ?? DEFAULT_WORK_UNIT_TIMEOUT_MS;
+    let count = 0;
+    for (const unit of state.executionUnits.values()) {
+        if (unit.status !== 'running' || !unit.dispatchedAt)
+            continue;
+        const elapsed = now.getTime() - unit.dispatchedAt.getTime();
+        if (elapsed < timeoutMs)
+            continue;
+        console.warn(`${LOG_PREFIX} Unit ${unit.slotIndex} dispatched work unit running for ${Math.round(elapsed / 1000)}s ` +
+            `(timeout: ${timeoutMs}ms) -- creating escalation`);
+        try {
+            await deps.createEscalation(state.instanceId, 'work_unit_timeout', `Execution unit slot ${unit.slotIndex} (${unit.unitId}) has been executing dispatched ` +
+                `work for ${Math.round(elapsed / 1000)}s (strategy: ${unit.assignedStrategyId ?? 'unknown'}). ` +
+                `Timeout threshold: ${timeoutMs}ms.`);
+        }
+        catch (err) {
+            console.error(`${LOG_PREFIX} Failed to create escalation for dispatch timeout on unit ${unit.unitId}: ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Clear dispatchedAt and pending set so we don't re-escalate next cycle
+        unit.dispatchedAt = null;
+        unit.dispatchedWorkUnitIds.clear();
+        count++;
+    }
+    return count;
+}
+/**
+ * Check for running units with no stdout activity beyond the threshold.
+ *
+ * Catches sessions that are alive but stuck (infinite loops, API hangs).
+ * Creates an escalation but does not terminate the session.
+ */
+async function checkSignalSilence(state, blueprint, now, deps) {
+    const timeoutMs = blueprint.signalSilenceTimeoutMs ?? DEFAULT_SIGNAL_SILENCE_TIMEOUT_MS;
+    let count = 0;
+    for (const unit of state.executionUnits.values()) {
+        if (unit.status !== 'running' || !unit.pid)
+            continue;
+        // Use lastActivityAt if available, fall back to startedAt
+        const lastActivity = unit.lastActivityAt ?? unit.startedAt;
+        if (!lastActivity)
+            continue;
+        const elapsed = now.getTime() - lastActivity.getTime();
+        if (elapsed < timeoutMs)
+            continue;
+        console.warn(`${LOG_PREFIX} Unit ${unit.slotIndex} has no stdout activity for ${Math.round(elapsed / 1000)}s ` +
+            `(timeout: ${timeoutMs}ms) -- creating escalation`);
+        try {
+            await deps.createEscalation(state.instanceId, 'signal_silence', `Execution unit slot ${unit.slotIndex} (${unit.unitId}, pid ${unit.pid}) has produced ` +
+                `no stdout activity for ${Math.round(elapsed / 1000)}s (strategy: ` +
+                `${unit.assignedStrategyId ?? 'unknown'}). Session may be stuck.`);
+        }
+        catch (err) {
+            console.error(`${LOG_PREFIX} Failed to create escalation for signal silence on unit ${unit.unitId}: ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Update lastActivityAt to now so we don't re-escalate next cycle
+        unit.lastActivityAt = now;
+        count++;
+    }
+    return count;
+}
+//# sourceMappingURL=watchdogs.js.map

package/dist/watchdogs.js.map

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

package/dist/work-unit-scheduler.d.ts

@@ -0,0 +1,34 @@
+/**
+ * DAG scheduling and dependency resolution for factory work units.
+ *
+ * Pure functions that determine which work units are ready to execute
+ * based on intra-plan dependencies and cross-strategy blocking.
+ *
+ * Extracted from execution.ts for focused module boundaries.
+ */
+import type { FactoryWorkUnit } from './types.js';
+/**
+ * Map from strategyId to the list of strategy IDs it depends on.
+ * Used to enforce cross-strategy dependency blocking at the work unit level.
+ */
+export type StrategyDependencyMap = Map<string, string[]>;
+/**
+ * Map of strategy ID -> execution status. When provided to findReadyWorkUnits,
+ * cross-strategy blocking uses the strategy's execution status (which reflects
+ * gate results) instead of checking individual work unit statuses.
+ */
+export type StrategyStatusMap = Map<string, string>;
+/**
+ * Find work units that are ready to be executed.
+ *
+ * A work unit is "ready" when:
+ *   - Its status is 'pending' or 'ready', AND
+ *   - Every ID in its `blockedBy` array corresponds to a work unit
+ *     whose status is 'completed', AND
+ *   - If the work unit has a strategyId and strategyDependencies are provided,
+ *     ALL work units in all dependency strategies must be 'completed'.
+ *
+ * This is a pure function -- it operates only on the provided arrays.
+ */
+export declare function findReadyWorkUnits(workUnits: FactoryWorkUnit[], strategyDependencies?: StrategyDependencyMap, strategyStatuses?: StrategyStatusMap): FactoryWorkUnit[];
+//# sourceMappingURL=work-unit-scheduler.d.ts.map

package/dist/work-unit-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-unit-scheduler.d.ts","sourceRoot":"","sources":["../src/work-unit-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,eAAe,EAEhB,MAAM,YAAY,CAAC;AAMpB;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAE1D;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAMpD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,eAAe,EAAE,EAC5B,oBAAoB,CAAC,EAAE,qBAAqB,EAC5C,gBAAgB,CAAC,EAAE,iBAAiB,GACnC,eAAe,EAAE,CAoEnB"}

package/dist/work-unit-scheduler.js

@@ -0,0 +1,91 @@
+/**
+ * DAG scheduling and dependency resolution for factory work units.
+ *
+ * Pure functions that determine which work units are ready to execute
+ * based on intra-plan dependencies and cross-strategy blocking.
+ *
+ * Extracted from execution.ts for focused module boundaries.
+ */
+// ============================================================================
+// Ready work unit finder
+// ============================================================================
+/**
+ * Find work units that are ready to be executed.
+ *
+ * A work unit is "ready" when:
+ *   - Its status is 'pending' or 'ready', AND
+ *   - Every ID in its `blockedBy` array corresponds to a work unit
+ *     whose status is 'completed', AND
+ *   - If the work unit has a strategyId and strategyDependencies are provided,
+ *     ALL work units in all dependency strategies must be 'completed'.
+ *
+ * This is a pure function -- it operates only on the provided arrays.
+ */
+export function findReadyWorkUnits(workUnits, strategyDependencies, strategyStatuses) {
+    // Build a lookup of work unit status by ID for O(1) dependency checks.
+    const statusById = new Map();
+    for (const unit of workUnits) {
+        statusById.set(unit.id, unit.status);
+    }
+    // Build a lookup of strategy completeness: strategyId -> all completed?
+    // When strategyStatuses is provided, use the strategy's execution status
+    // (which reflects gate results). Otherwise, fall back to checking if all
+    // work units in the strategy have status 'completed'.
+    let strategyComplete = null;
+    if (strategyDependencies && strategyDependencies.size > 0) {
+        strategyComplete = new Map();
+        if (strategyStatuses) {
+            // Use strategy execution status -- downstream only unblocks after gates pass
+            for (const [sid] of strategyDependencies) {
+                strategyComplete.set(sid, strategyStatuses.get(sid) === 'completed');
+            }
+        }
+        else {
+            // Fallback: check work unit statuses directly
+            const unitsByStrategy = new Map();
+            for (const unit of workUnits) {
+                if (unit.strategyId) {
+                    const list = unitsByStrategy.get(unit.strategyId);
+                    if (list) {
+                        list.push(unit);
+                    }
+                    else {
+                        unitsByStrategy.set(unit.strategyId, [unit]);
+                    }
+                }
+            }
+            for (const [sid, units] of unitsByStrategy) {
+                strategyComplete.set(sid, units.every((u) => u.status === 'completed'));
+            }
+        }
+    }
+    return workUnits.filter((unit) => {
+        // Only consider units that are waiting to be picked up
+        if (unit.status !== 'pending' && unit.status !== 'ready') {
+            return false;
+        }
+        // All intra-plan dependencies must be completed.
+        // If a blockedBy ID doesn't exist in the work units list (phantom planning
+        // ID that was never mapped to a real UUID), treat it as satisfied -- blocking
+        // on a non-existent unit would stall the factory permanently.
+        const intraReady = unit.blockedBy.every((depId) => {
+            const depStatus = statusById.get(depId);
+            if (depStatus === undefined)
+                return true; // phantom dep -- skip
+            return depStatus === 'completed';
+        });
+        if (!intraReady)
+            return false;
+        // Cross-strategy dependency check
+        if (unit.strategyId && strategyDependencies && strategyComplete) {
+            const depStrategies = strategyDependencies.get(unit.strategyId);
+            if (depStrategies && depStrategies.length > 0) {
+                const allDepsComplete = depStrategies.every((depSid) => strategyComplete.get(depSid) === true);
+                if (!allDepsComplete)
+                    return false;
+            }
+        }
+        return true;
+    });
+}
+//# sourceMappingURL=work-unit-scheduler.js.map

package/dist/work-unit-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-unit-scheduler.js","sourceRoot":"","sources":["../src/work-unit-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAwBH,+EAA+E;AAC/E,yBAAyB;AACzB,+EAA+E;AAE/E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAA4B,EAC5B,oBAA4C,EAC5C,gBAAoC;IAEpC,uEAAuE;IACvE,MAAM,UAAU,GAAG,IAAI,GAAG,EAA0B,CAAC;IACrD,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,wEAAwE;IACxE,yEAAyE;IACzE,yEAAyE;IACzE,sDAAsD;IACtD,IAAI,gBAAgB,GAAgC,IAAI,CAAC;IACzD,IAAI,oBAAoB,IAAI,oBAAoB,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QAC1D,gBAAgB,GAAG,IAAI,GAAG,EAAmB,CAAC;QAC9C,IAAI,gBAAgB,EAAE,CAAC;YACrB,6EAA6E;YAC7E,KAAK,MAAM,CAAC,GAAG,CAAC,IAAI,oBAAoB,EAAE,CAAC;gBACzC,gBAAgB,CAAC,GAAG,CAAC,GAAG,EAAE,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,WAAW,CAAC,CAAC;YACvE,CAAC;QACH,CAAC;aAAM,CAAC;YACN,8CAA8C;YAC9C,MAAM,eAAe,GAAG,IAAI,GAAG,EAA6B,CAAC;YAC7D,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;gBAC7B,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;oBACpB,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;oBAClD,IAAI,IAAI,EAAE,CAAC;wBACT,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBAClB,CAAC;yBAAM,CAAC;wBACN,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;oBAC/C,CAAC;gBACH,CAAC;YACH,CAAC;YACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,eAAe,EAAE,CAAC;gBAC3C,gBAAgB,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC;YAC1E,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;QAC/B,uDAAuD;QACvD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;YACzD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,iDAAiD;QACjD,2EAA2E;QAC3E,8EAA8E;QAC9E,8DAA8D;QAC9D,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YAChD,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACxC,IAAI,SAAS,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC,CAAC,sBAAsB;YAChE,OAAO,SAAS,KAAK,WAAW,CAAC;QACnC,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,UAAU;YAAE,OAAO,KAAK,CAAC;QAE9B,kCAAkC;QAClC,IAAI,IAAI,CAAC,UAAU,IAAI,oBAAoB,IAAI,gBAAgB,EAAE,CAAC;YAChE,MAAM,aAAa,GAAG,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAChE,IAAI,aAAa,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC9C,MAAM,eAAe,GAAG,aAAa,CAAC,KAAK,CACzC,CAAC,MAAM,EAAE,EAAE,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,CAClD,CAAC;gBACF,IAAI,CAAC,eAAe;oBAAE,OAAO,KAAK,CAAC;YACrC,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/workflow-transition.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Workflow transition orchestrator for the factory engine.
+ *
+ * Provides a high-level API for transitioning factory entities through
+ * workflow-governed state changes. Each transition:
+ * 1. Resolves the entity's workflow (cached per instance)
+ * 2. Finds the transition from current stage to target stage
+ * 3. Fetches and evaluates guards
+ * 4. Executes triggers
+ * 5. Updates the entity's current_workflow_stage_id
+ * 6. Records audit trail
+ *
+ * Falls back gracefully when no workflow is assigned (direct status update).
+ */
+import type { ResolvedFactoryWorkflow, WorkflowTransition, TransitionGuardResult, EvaluationContext, TriggerExecutionTarget, FactoryTemplateContext } from './types.js';
+/**
+ * Resolve and cache a factory workflow by entity type.
+ * Returns null if no workflow exists for this entity type.
+ * Cached entries expire after CACHE_TTL_MS (5 minutes).
+ */
+export declare function getOrResolveWorkflow(entityType: string): Promise<ResolvedFactoryWorkflow | null>;
+/**
+ * Clear the workflow cache (for testing or hot-reload).
+ */
+export declare function clearWorkflowCache(): void;
+/**
+ * Find the transition between two stages by name within a workflow.
+ * Returns null if no such transition exists.
+ */
+export declare function findTransition(workflow: ResolvedFactoryWorkflow, fromStageName: string, toStageName: string): WorkflowTransition | null;
+/**
+ * Get the stage name for a given stage ID.
+ */
+export declare function getStageName(workflow: ResolvedFactoryWorkflow, stageId: string): string | null;
+/**
+ * Evaluate all guards at a workflow transition.
+ * Fetches guards from the DB, evaluates conditions, collects triggers.
+ */
+export declare function evaluateTransitionGuards(organizationId: string, entityType: string, entityId: string, transition: WorkflowTransition, ctx: EvaluationContext): Promise<TransitionGuardResult>;
+/**
+ * Execute triggers from a guard evaluation result.
+ * Factory-specific: handles inject_prompt, manage_context, set_field, notify.
+ * Skips spawn_agent, create_issue, block_transition (daemon-only).
+ */
+export declare function executeFactoryTriggers(triggersToExecute: TransitionGuardResult['triggers_to_execute'], target: TriggerExecutionTarget | null, factoryCtx?: FactoryTemplateContext | null): Promise<void>;
+export interface TransitionResult {
+    /** Whether the transition was allowed (guards passed). */
+    allowed: boolean;
+    /** The new workflow stage ID (null if no workflow or blocked). */
+    newStageId: string | null;
+    /** The new stage name. */
+    newStageName: string | null;
+    /** Guard evaluation result (null if no guards). */
+    guardResult: TransitionGuardResult | null;
+    /** Whether a workflow was found. */
+    hasWorkflow: boolean;
+    /** Whether the transition was rejected due to a stale stage (concurrent modification). */
+    stale?: boolean;
+}
+/**
+ * Attempt a workflow-governed transition for a factory entity.
+ *
+ * This is the main entry point for the factory engine. It:
+ * 1. Optionally checks expectedStageId for optimistic locking (concurrent transition protection)
+ * 2. Finds the transition in the resolved workflow
+ * 3. Evaluates guards
+ * 4. Executes triggers (if guards pass)
+ * 5. Returns whether the transition is allowed and the new stage ID
+ *
+ * The caller is responsible for:
+ * - Updating the entity's status and current_workflow_stage_id in the DB
+ *   using WHERE current_workflow_stage_id = expectedStageId for optimistic locking
+ * - Updating in-memory state
+ * - Retrying on stale result (re-read entity state and re-attempt)
+ *
+ * @param workflow Resolved workflow (from instance state cache)
+ * @param currentStageName Current stage name (e.g. 'pending', 'building')
+ * @param targetStageName Target stage name (e.g. 'planning', 'completed')
+ * @param organizationId Organization ID for audit trail
+ * @param entityType Entity type for audit trail (e.g. 'factory_instance')
+ * @param entityId Entity UUID for audit trail
+ * @param ctx Evaluation context with factory state data
+ * @param target Optional trigger execution target for active sessions
+ * @param factoryCtx Optional factory template context for prompt interpolation
+ * @param expectedStageId Optional expected current stage ID for optimistic locking.
+ *   When provided, the transition is rejected with stale=true if the entity's
+ *   current stage doesn't match, preventing race conditions from concurrent transitions.
+ */
+export declare function attemptTransition(workflow: ResolvedFactoryWorkflow | null, currentStageName: string, targetStageName: string, organizationId: string, entityType: string, entityId: string, ctx: EvaluationContext, target?: TriggerExecutionTarget | null, factoryCtx?: FactoryTemplateContext | null, expectedStageId?: string | null): Promise<TransitionResult>;
+//# sourceMappingURL=workflow-transition.d.ts.map

package/dist/workflow-transition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-transition.d.ts","sourceRoot":"","sources":["../src/workflow-transition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,uBAAuB,EACvB,kBAAkB,EAGlB,qBAAqB,EAErB,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,EAEvB,MAAM,YAAY,CAAC;AAuBpB;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAezC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAMD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,uBAAuB,EACjC,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,GAClB,kBAAkB,GAAG,IAAI,CAS3B;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,uBAAuB,EACjC,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,IAAI,CAEf;AAMD;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,kBAAkB,EAC9B,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,qBAAqB,CAAC,CA4FhC;AAMD;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,iBAAiB,EAAE,qBAAqB,CAAC,qBAAqB,CAAC,EAC/D,MAAM,EAAE,sBAAsB,GAAG,IAAI,EACrC,UAAU,CAAC,EAAE,sBAAsB,GAAG,IAAI,GACzC,OAAO,CAAC,IAAI,CAAC,CA4Ef;AAMD,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,kEAAkE;IAClE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,0BAA0B;IAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,mDAAmD;IACnD,WAAW,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC1C,oCAAoC;IACpC,WAAW,EAAE,OAAO,CAAC;IACrB,0FAA0F;IAC1F,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,uBAAuB,GAAG,IAAI,EACxC,gBAAgB,EAAE,MAAM,EACxB,eAAe,EAAE,MAAM,EACvB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,iBAAiB,EACtB,MAAM,CAAC,EAAE,sBAAsB,GAAG,IAAI,EACtC,UAAU,CAAC,EAAE,sBAAsB,GAAG,IAAI,EAC1C,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CAiF3B"}