@msm-core/jobs 0.1.0

package/dist/orchestrator.js

@@ -0,0 +1,408 @@
+// Job orchestrator — executes deterministic workflow steps with CAS + idempotency
+// protection, in a bounded burst. Ported from kader's job-orchestrator.service.ts:
+// every Mongo/BullMQ call is replaced by a port call, and a StepExecutorPort runs the
+// real side-effecting work (e.g. an agent turn) for `run_interaction_task` — the one
+// capability kader's deterministic version lacked.
+import { isTerminalJobStatus, isRunnableJobStatus } from "./enums.js";
+import { DuplicateStepError } from "./port.js";
+import { resolveRunConfig } from "./config.js";
+const QUEUE_NAME = "jobs";
+function isDuplicateKeyError(error) {
+    return error instanceof DuplicateStepError;
+}
+export function createOrchestrator(deps) {
+    const { jobStore, queue, ops, clock, registry, stepExecutor, resumeToken, config } = deps;
+    const runConfig = resolveRunConfig(config);
+    function buildIdempotencyKey(input, version, currentStep) {
+        if (input.idempotencyKey)
+            return input.idempotencyKey;
+        const reason = input.reason || "queue";
+        return `${input.jobId}:${version}:${currentStep}:${reason}`;
+    }
+    async function enqueueBurstContinuation(input) {
+        const continuation = await jobStore.getJob(input.jobId, input.tenantId);
+        if (!continuation)
+            return;
+        if (!isRunnableJobStatus(continuation.status))
+            return;
+        await queue.enqueue({
+            jobId: input.jobId,
+            tenantId: input.tenantId,
+            reason: "burst_continue",
+            dedupeKey: `${continuation.currentStep}:burst`,
+        });
+        ops.record({
+            jobId: input.jobId,
+            tenantId: input.tenantId,
+            missionId: continuation.missionId,
+            source: "job_orchestrator",
+            eventType: "job.burst.continue_enqueued",
+            status: continuation.status,
+            queueName: QUEUE_NAME,
+            employeeId: continuation.employeeId,
+            correlationId: continuation.correlationId,
+            metadata: { currentStep: continuation.currentStep },
+        });
+    }
+    async function orchestrateJobStep(input) {
+        let stepsExecuted = 0;
+        while (stepsExecuted < runConfig.maxStepsPerTick) {
+            const snapshot = await jobStore.getJob(input.jobId, input.tenantId);
+            if (!snapshot)
+                return;
+            const now = clock.now();
+            const dueTimeResume = snapshot.status === "waiting_time" &&
+                snapshot.resumeAt !== null &&
+                snapshot.resumeAt.getTime() <= now.getTime();
+            // A tick is actionable when the job is already runnable, OR it is a waiting_time job
+            // whose resumeAt has passed — in which case we promote it to running here (the
+            // reconciler / delayed tick only re-enqueues; the CAS promotion lives in the engine
+            // so a resumed time-wait actually advances rather than being skipped as non-runnable).
+            if (!isRunnableJobStatus(snapshot.status) && !dueTimeResume)
+                return;
+            const claimed = await jobStore.claim({
+                jobId: input.jobId,
+                tenantId: input.tenantId,
+                expectedVersion: snapshot.version,
+                statusIn: dueTimeResume ? ["waiting_time"] : ["queued", "running"],
+                set: { status: "running", resumeAt: null, startedAt: snapshot.startedAt ?? now },
+            });
+            if (!claimed)
+                return; // CAS claim lost — another worker owns this tick.
+            const idempotencyKey = buildIdempotencyKey(input, claimed.version, claimed.currentStep);
+            const existingStep = await jobStore.findStepByIdempotencyKey(input.jobId, input.tenantId, idempotencyKey);
+            if (existingStep) {
+                const restoredStatus = claimed.waitEvent
+                    ? "waiting_event"
+                    : claimed.resumeAt
+                        ? "waiting_time"
+                        : claimed.completedAt
+                            ? "completed"
+                            : "queued";
+                if (claimed.status === "running") {
+                    await jobStore.finalizeStep({
+                        jobId: input.jobId,
+                        tenantId: input.tenantId,
+                        expectedVersion: claimed.version,
+                        set: { status: restoredStatus },
+                    });
+                }
+                ops.record({
+                    jobId: input.jobId,
+                    tenantId: input.tenantId,
+                    missionId: claimed.missionId,
+                    source: "job_orchestrator",
+                    eventType: "job.step.duplicate_skipped",
+                    status: claimed.status,
+                    queueName: QUEUE_NAME,
+                    employeeId: claimed.employeeId,
+                    correlationId: claimed.correlationId,
+                    metadata: { idempotencyKey, restoredStatus },
+                });
+                return;
+            }
+            const stepStartedAt = clock.now();
+            const stepNumber = claimed.currentStep + 1;
+            ops.record({
+                jobId: input.jobId,
+                tenantId: input.tenantId,
+                missionId: claimed.missionId,
+                source: "job_orchestrator",
+                eventType: "job.step.started",
+                status: "running",
+                queueName: QUEUE_NAME,
+                employeeId: claimed.employeeId,
+                correlationId: claimed.correlationId,
+                metadata: { stepNumber, reason: input.reason || "queue", idempotencyKey },
+            });
+            try {
+                const resolution = registry.resolveStep({
+                    workflowType: claimed.workflowType,
+                    workflowVersion: claimed.workflowVersion,
+                    budget: claimed.budget,
+                    state: claimed.state,
+                    stepNumber,
+                    reason: input.reason || "queue",
+                    now: stepStartedAt,
+                });
+                // Run the real side-effecting work (agent turn for run_interaction_task; {} for
+                // pure transitions). Throwing here fails the step via the catch below.
+                const execResult = await stepExecutor.execute({
+                    stepType: resolution.stepType,
+                    triggeredBy: resolution.triggeredBy,
+                    job: claimed,
+                    resolution,
+                    stepNumber,
+                });
+                const stepEndedAt = clock.now();
+                const durationMs = stepEndedAt.getTime() - stepStartedAt.getTime();
+                const mergedOutput = { ...(resolution.output ?? {}), ...(execResult.output ?? {}) };
+                const mergedStatePatch = {
+                    ...(resolution.statePatch ?? {}),
+                    ...(execResult.statePatch ?? {}),
+                };
+                const step = {
+                    stepId: deps.genStepId(),
+                    jobId: input.jobId,
+                    tenantId: input.tenantId,
+                    stepNumber,
+                    stepType: resolution.stepType,
+                    status: "completed",
+                    triggeredBy: resolution.triggeredBy,
+                    startedAt: stepStartedAt,
+                    endedAt: stepEndedAt,
+                    durationMs,
+                    toolCalls: [],
+                    output: mergedOutput,
+                    error: null,
+                    nextStep: null,
+                    transitionReason: resolution.transitionReason,
+                    idempotencyKey,
+                };
+                await jobStore.insertStep(step);
+                const nextStatus = resolution.nextStatus;
+                const nextResumeAt = nextStatus === "waiting_time"
+                    ? new Date(clock.now().getTime() + (resolution.resumeDelayMs ?? config.defaultWaitMs))
+                    : null;
+                const waitEventName = resolution.waitEventName || "job.resume";
+                const issuedWaitEventToken = nextStatus === "waiting_event"
+                    ? resumeToken.issue({
+                        jobId: input.jobId,
+                        tenantId: input.tenantId,
+                        eventName: waitEventName,
+                    })
+                    : null;
+                const nextWaitEvent = nextStatus === "waiting_event"
+                    ? { eventName: waitEventName, token: issuedWaitEventToken?.token ?? null }
+                    : null;
+                const nextState = { ...(claimed.state ?? {}), ...mergedStatePatch };
+                const finalized = await jobStore.finalizeStep({
+                    jobId: input.jobId,
+                    tenantId: input.tenantId,
+                    expectedVersion: claimed.version,
+                    set: {
+                        currentStep: stepNumber,
+                        status: nextStatus,
+                        resumeAt: nextResumeAt,
+                        waitEvent: nextWaitEvent,
+                        state: nextState,
+                        completedAt: isTerminalJobStatus(nextStatus) ? clock.now() : null,
+                    },
+                    incCounters: { totalStepsExecuted: 1, attempt: 1 },
+                });
+                if (!finalized)
+                    return; // CAS finalize lost.
+                stepsExecuted += 1;
+                ops.record({
+                    jobId: input.jobId,
+                    tenantId: input.tenantId,
+                    missionId: finalized.missionId,
+                    source: "job_orchestrator",
+                    eventType: "job.step.completed",
+                    status: finalized.status,
+                    queueName: QUEUE_NAME,
+                    employeeId: finalized.employeeId,
+                    correlationId: finalized.correlationId,
+                    metadata: {
+                        stepNumber,
+                        stepType: resolution.stepType,
+                        transitionReason: resolution.transitionReason,
+                        durationMs,
+                        idempotencyKey,
+                        stepsExecutedThisTick: stepsExecuted,
+                        maxStepsPerTick: runConfig.maxStepsPerTick,
+                    },
+                });
+                if (nextStatus === "completed") {
+                    ops.record({
+                        jobId: input.jobId,
+                        tenantId: input.tenantId,
+                        missionId: finalized.missionId,
+                        source: "job_orchestrator",
+                        eventType: "job.completed",
+                        status: finalized.status,
+                        queueName: QUEUE_NAME,
+                        employeeId: finalized.employeeId,
+                        correlationId: finalized.correlationId,
+                    });
+                    return;
+                }
+                if (nextStatus === "failed") {
+                    ops.record({
+                        jobId: input.jobId,
+                        tenantId: input.tenantId,
+                        missionId: finalized.missionId,
+                        source: "job_orchestrator",
+                        eventType: "job.failed",
+                        status: finalized.status,
+                        queueName: QUEUE_NAME,
+                        employeeId: finalized.employeeId,
+                        correlationId: finalized.correlationId,
+                    });
+                    return;
+                }
+                if (nextStatus === "waiting_event") {
+                    ops.record({
+                        jobId: input.jobId,
+                        tenantId: input.tenantId,
+                        missionId: finalized.missionId,
+                        source: "job_orchestrator",
+                        eventType: "job.waiting_event",
+                        status: finalized.status,
+                        queueName: QUEUE_NAME,
+                        employeeId: finalized.employeeId,
+                        correlationId: finalized.correlationId,
+                        metadata: {
+                            stepNumber,
+                            waitEventName: nextWaitEvent?.eventName ?? null,
+                            resumeTokenExpiresAt: issuedWaitEventToken?.expiresAt ?? null,
+                        },
+                    });
+                    return;
+                }
+                if (nextStatus === "awaiting_approval") {
+                    await handleAwaitingApproval(finalized, resolution, stepNumber, input);
+                    return;
+                }
+                if (nextStatus !== "waiting_time")
+                    return;
+                ops.record({
+                    jobId: input.jobId,
+                    tenantId: input.tenantId,
+                    missionId: finalized.missionId,
+                    source: "job_orchestrator",
+                    eventType: "job.waiting_time",
+                    status: finalized.status,
+                    queueName: QUEUE_NAME,
+                    employeeId: finalized.employeeId,
+                    correlationId: finalized.correlationId,
+                    metadata: {
+                        stepNumber,
+                        transitionReason: resolution.transitionReason,
+                        resumeAt: nextResumeAt?.toISOString(),
+                        resumeMode: config.resumeMode,
+                    },
+                });
+                const resumeDelayMs = nextResumeAt
+                    ? Math.max(1, nextResumeAt.getTime() - clock.now().getTime())
+                    : config.defaultWaitMs;
+                const canInlineContinue = stepsExecuted < runConfig.maxStepsPerTick &&
+                    resumeDelayMs <= runConfig.inlineResumeMaxDelayMs;
+                if (canInlineContinue) {
+                    const inlined = await jobStore.claim({
+                        jobId: input.jobId,
+                        tenantId: input.tenantId,
+                        expectedVersion: finalized.version,
+                        statusIn: ["waiting_time"],
+                        set: { status: "queued", resumeAt: null },
+                    });
+                    if (!inlined)
+                        return;
+                    ops.record({
+                        jobId: input.jobId,
+                        tenantId: input.tenantId,
+                        missionId: inlined.missionId,
+                        source: "job_orchestrator",
+                        eventType: "job.waiting_time.inline_continued",
+                        status: inlined.status,
+                        queueName: QUEUE_NAME,
+                        employeeId: inlined.employeeId,
+                        correlationId: inlined.correlationId,
+                        metadata: { stepNumber, resumeDelayMs, inlineResumeMaxDelayMs: runConfig.inlineResumeMaxDelayMs },
+                    });
+                    continue;
+                }
+                if (config.resumeMode === "scan_only")
+                    return;
+                await queue.enqueue({
+                    jobId: input.jobId,
+                    tenantId: input.tenantId,
+                    reason: "waiting_time_resume",
+                    delayMs: resumeDelayMs,
+                    dedupeKey: `${stepNumber}:${idempotencyKey}`,
+                });
+                return;
+            }
+            catch (error) {
+                if (isDuplicateKeyError(error)) {
+                    ops.record({
+                        jobId: input.jobId,
+                        tenantId: input.tenantId,
+                        missionId: claimed.missionId,
+                        source: "job_orchestrator",
+                        eventType: "job.step.duplicate_skipped",
+                        status: claimed.status,
+                        queueName: QUEUE_NAME,
+                        employeeId: claimed.employeeId,
+                        correlationId: claimed.correlationId,
+                        metadata: { idempotencyKey },
+                    });
+                    return;
+                }
+                await jobStore.markFailed({ jobId: input.jobId, tenantId: input.tenantId });
+                ops.record({
+                    jobId: input.jobId,
+                    tenantId: input.tenantId,
+                    missionId: claimed.missionId,
+                    source: "job_orchestrator",
+                    eventType: "job.failed",
+                    status: "failed",
+                    queueName: QUEUE_NAME,
+                    employeeId: claimed.employeeId,
+                    correlationId: claimed.correlationId,
+                    metadata: { error: error.message },
+                });
+                throw error;
+            }
+        }
+        await enqueueBurstContinuation(input);
+    }
+    async function handleAwaitingApproval(finalized, resolution, stepNumber, input) {
+        let approvalId = null;
+        let approvalExpiresAt = null;
+        if (deps.approvalCreator) {
+            const createInput = {
+                tenantId: input.tenantId,
+                employeeId: finalized.employeeId,
+                jobId: finalized.jobId,
+                stepNumber,
+                jobVersion: finalized.version,
+                workflowType: finalized.workflowType,
+                stepType: resolution.stepType,
+                transitionReason: resolution.transitionReason,
+                reasoning: `Approval required at job step ${stepNumber} for ${resolution.stepType}`,
+                approvalPolicy: resolution.approvalPolicy ?? "internal_operational",
+                metadata: {
+                    timeoutOutcome: resolution.approvalTimeoutOutcome ?? null,
+                    orchestratorReason: input.reason || "queue",
+                },
+            };
+            if (resolution.approvalTimeoutMs !== undefined) {
+                createInput.approvalTimeoutMs = resolution.approvalTimeoutMs;
+            }
+            const approval = await deps.approvalCreator.create(createInput);
+            approvalId = approval.approvalId;
+            approvalExpiresAt = approval.expiresAt;
+        }
+        ops.record({
+            jobId: input.jobId,
+            tenantId: input.tenantId,
+            missionId: finalized.missionId,
+            source: "job_orchestrator",
+            eventType: "job.approval.awaiting",
+            status: finalized.status,
+            queueName: QUEUE_NAME,
+            employeeId: finalized.employeeId,
+            correlationId: finalized.correlationId,
+            metadata: {
+                stepNumber,
+                approvalId,
+                approvalPolicy: resolution.approvalPolicy ?? "internal_operational",
+                timeoutOutcome: resolution.approvalTimeoutOutcome ?? null,
+                approvalExpiresAt: approvalExpiresAt?.toISOString() ?? null,
+            },
+        });
+    }
+    return { orchestrateJobStep };
+}
+//# sourceMappingURL=orchestrator.js.map

package/dist/orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.js","sourceRoot":"","sources":["../src/orchestrator.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,mFAAmF;AACnF,sFAAsF;AACtF,qFAAqF;AACrF,mDAAmD;AAEnD,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAUtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAG/C,OAAO,EAAE,gBAAgB,EAAwB,MAAM,aAAa,CAAC;AAGrE,MAAM,UAAU,GAAG,MAAM,CAAC;AA0B1B,SAAS,mBAAmB,CAAC,KAAc;IACzC,OAAO,KAAK,YAAY,kBAAkB,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAsB;IACvD,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC1F,MAAM,SAAS,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAE3C,SAAS,mBAAmB,CAC1B,KAA8B,EAC9B,OAAe,EACf,WAAmB;QAEnB,IAAI,KAAK,CAAC,cAAc;YAAE,OAAO,KAAK,CAAC,cAAc,CAAC;QACtD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,OAAO,CAAC;QACvC,OAAO,GAAG,KAAK,CAAC,KAAK,IAAI,OAAO,IAAI,WAAW,IAAI,MAAM,EAAE,CAAC;IAC9D,CAAC;IAED,KAAK,UAAU,wBAAwB,CAAC,KAA8B;QACpE,MAAM,YAAY,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;QACxE,IAAI,CAAC,YAAY;YAAE,OAAO;QAC1B,IAAI,CAAC,mBAAmB,CAAC,YAAY,CAAC,MAAM,CAAC;YAAE,OAAO;QAEtD,MAAM,KAAK,CAAC,OAAO,CAAC;YAClB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,MAAM,EAAE,gBAAgB;YACxB,SAAS,EAAE,GAAG,YAAY,CAAC,WAAW,QAAQ;SAC/C,CAAC,CAAC;QAEH,GAAG,CAAC,MAAM,CAAC;YACT,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,SAAS,EAAE,YAAY,CAAC,SAAS;YACjC,MAAM,EAAE,kBAAkB;YAC1B,SAAS,EAAE,6BAA6B;YACxC,MAAM,EAAE,YAAY,CAAC,MAAM;YAC3B,SAAS,EAAE,UAAU;YACrB,UAAU,EAAE,YAAY,CAAC,UAAU;YACnC,aAAa,EAAE,YAAY,CAAC,aAAa;YACzC,QAAQ,EAAE,EAAE,WAAW,EAAE,YAAY,CAAC,WAAW,EAAE;SACpD,CAAC,CAAC;IACL,CAAC;IAED,KAAK,UAAU,kBAAkB,CAAC,KAA8B;QAC9D,IAAI,aAAa,GAAG,CAAC,CAAC;QAEtB,OAAO,aAAa,GAAG,SAAS,CAAC,eAAe,EAAE,CAAC;YACjD,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;YACpE,IAAI,CAAC,QAAQ;gBAAE,OAAO;YAEtB,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;YACxB,MAAM,aAAa,GACjB,QAAQ,CAAC,MAAM,KAAK,cAAc;gBAClC,QAAQ,CAAC,QAAQ,KAAK,IAAI;gBAC1B,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;YAE/C,qFAAqF;YACrF,+EAA+E;YAC/E,oFAAoF;YACpF,uFAAuF;YACvF,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa;gBAAE,OAAO;YAEpE,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC;gBACnC,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,eAAe,EAAE,QAAQ,CAAC,OAAO;gBACjC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,SAAS,CAAC;gBAClE,GAAG,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,IAAI,GAAG,EAAE;aACjF,CAAC,CAAC;YACH,IAAI,CAAC,OAAO;gBAAE,OAAO,CAAC,kDAAkD;YAExE,MAAM,cAAc,GAAG,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;YACxF,MAAM,YAAY,GAAG,MAAM,QAAQ,CAAC,wBAAwB,CAC1D,KAAK,CAAC,KAAK,EACX,KAAK,CAAC,QAAQ,EACd,cAAc,CACf,CAAC;YAEF,IAAI,YAAY,EAAE,CAAC;gBACjB,MAAM,cAAc,GAAc,OAAO,CAAC,SAAS;oBACjD,CAAC,CAAC,eAAe;oBACjB,CAAC,CAAC,OAAO,CAAC,QAAQ;wBAChB,CAAC,CAAC,cAAc;wBAChB,CAAC,CAAC,OAAO,CAAC,WAAW;4BACnB,CAAC,CAAC,WAAW;4BACb,CAAC,CAAC,QAAQ,CAAC;gBAEjB,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;oBACjC,MAAM,QAAQ,CAAC,YAAY,CAAC;wBAC1B,KAAK,EAAE,KAAK,CAAC,KAAK;wBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;wBACxB,eAAe,EAAE,OAAO,CAAC,OAAO;wBAChC,GAAG,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE;qBAChC,CAAC,CAAC;gBACL,CAAC;gBAED,GAAG,CAAC,MAAM,CAAC;oBACT,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,SAAS,EAAE,OAAO,CAAC,SAAS;oBAC5B,MAAM,EAAE,kBAAkB;oBAC1B,SAAS,EAAE,4BAA4B;oBACvC,MAAM,EAAE,OAAO,CAAC,MAAM;oBACtB,SAAS,EAAE,UAAU;oBACrB,UAAU,EAAE,OAAO,CAAC,UAAU;oBAC9B,aAAa,EAAE,OAAO,CAAC,aAAa;oBACpC,QAAQ,EAAE,EAAE,cAAc,EAAE,cAAc,EAAE;iBAC7C,CAAC,CAAC;gBACH,OAAO;YACT,CAAC;YAED,MAAM,aAAa,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;YAClC,MAAM,UAAU,GAAG,OAAO,CAAC,WAAW,GAAG,CAAC,CAAC;YAE3C,GAAG,CAAC,MAAM,CAAC;gBACT,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,MAAM,EAAE,kBAAkB;gBAC1B,SAAS,EAAE,kBAAkB;gBAC7B,MAAM,EAAE,SAAS;gBACjB,SAAS,EAAE,UAAU;gBACrB,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,aAAa,EAAE,OAAO,CAAC,aAAa;gBACpC,QAAQ,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,OAAO,EAAE,cAAc,EAAE;aAC1E,CAAC,CAAC;YAEH,IAAI,CAAC;gBACH,MAAM,UAAU,GAAG,QAAQ,CAAC,WAAW,CAAC;oBACtC,YAAY,EAAE,OAAO,CAAC,YAAY;oBAClC,eAAe,EAAE,OAAO,CAAC,eAAe;oBACxC,MAAM,EAAE,OAAO,CAAC,MAAM;oBACtB,KAAK,EAAE,OAAO,CAAC,KAAK;oBACpB,UAAU;oBACV,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,OAAO;oBAC/B,GAAG,EAAE,aAAa;iBACnB,CAAC,CAAC;gBAEH,gFAAgF;gBAChF,uEAAuE;gBACvE,MAAM,UAAU,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC;oBAC5C,QAAQ,EAAE,UAAU,CAAC,QAAQ;oBAC7B,WAAW,EAAE,UAAU,CAAC,WAAW;oBACnC,GAAG,EAAE,OAAO;oBACZ,UAAU;oBACV,UAAU;iBACX,CAAC,CAAC;gBAEH,MAAM,WAAW,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;gBAChC,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,EAAE,GAAG,aAAa,CAAC,OAAO,EAAE,CAAC;gBAEnE,MAAM,YAAY,GAAG,EAAE,GAAG,CAAC,UAAU,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;gBACpF,MAAM,gBAAgB,GAAG;oBACvB,GAAG,CAAC,UAAU,CAAC,UAAU,IAAI,EAAE,CAAC;oBAChC,GAAG,CAAC,UAAU,CAAC,UAAU,IAAI,EAAE,CAAC;iBACjC,CAAC;gBAEF,MAAM,IAAI,GAAkB;oBAC1B,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE;oBACxB,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,UAAU;oBACV,QAAQ,EAAE,UAAU,CAAC,QAAQ;oBAC7B,MAAM,EAAE,WAAW;oBACnB,WAAW,EAAE,UAAU,CAAC,WAAW;oBACnC,SAAS,EAAE,aAAa;oBACxB,OAAO,EAAE,WAAW;oBACpB,UAAU;oBACV,SAAS,EAAE,EAAE;oBACb,MAAM,EAAE,YAAY;oBACpB,KAAK,EAAE,IAAI;oBACX,QAAQ,EAAE,IAAI;oBACd,gBAAgB,EAAE,UAAU,CAAC,gBAAgB;oBAC7C,cAAc;iBACf,CAAC;gBACF,MAAM,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;gBAEhC,MAAM,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC;gBACzC,MAAM,YAAY,GAChB,UAAU,KAAK,cAAc;oBAC3B,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,UAAU,CAAC,aAAa,IAAI,MAAM,CAAC,aAAa,CAAC,CAAC;oBACtF,CAAC,CAAC,IAAI,CAAC;gBAEX,MAAM,aAAa,GAAW,UAAU,CAAC,aAAa,IAAI,YAAY,CAAC;gBACvE,MAAM,oBAAoB,GACxB,UAAU,KAAK,eAAe;oBAC5B,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC;wBAChB,KAAK,EAAE,KAAK,CAAC,KAAK;wBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;wBACxB,SAAS,EAAE,aAAa;qBACzB,CAAC;oBACJ,CAAC,CAAC,IAAI,CAAC;gBACX,MAAM,aAAa,GACjB,UAAU,KAAK,eAAe;oBAC5B,CAAC,CAAC,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,EAAE,oBAAoB,EAAE,KAAK,IAAI,IAAI,EAAE;oBAC1E,CAAC,CAAC,IAAI,CAAC;gBAEX,MAAM,SAAS,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,GAAG,gBAAgB,EAAE,CAAC;gBAEpE,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC;oBAC5C,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,eAAe,EAAE,OAAO,CAAC,OAAO;oBAChC,GAAG,EAAE;wBACH,WAAW,EAAE,UAAU;wBACvB,MAAM,EAAE,UAAU;wBAClB,QAAQ,EAAE,YAAY;wBACtB,SAAS,EAAE,aAAa;wBACxB,KAAK,EAAE,SAAS;wBAChB,WAAW,EAAE,mBAAmB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI;qBAClE;oBACD,WAAW,EAAE,EAAE,kBAAkB,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE;iBACnD,CAAC,CAAC;gBAEH,IAAI,CAAC,SAAS;oBAAE,OAAO,CAAC,qBAAqB;gBAE7C,aAAa,IAAI,CAAC,CAAC;gBAEnB,GAAG,CAAC,MAAM,CAAC;oBACT,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,SAAS,EAAE,SAAS,CAAC,SAAS;oBAC9B,MAAM,EAAE,kBAAkB;oBAC1B,SAAS,EAAE,oBAAoB;oBAC/B,MAAM,EAAE,SAAS,CAAC,MAAM;oBACxB,SAAS,EAAE,UAAU;oBACrB,UAAU,EAAE,SAAS,CAAC,UAAU;oBAChC,aAAa,EAAE,SAAS,CAAC,aAAa;oBACtC,QAAQ,EAAE;wBACR,UAAU;wBACV,QAAQ,EAAE,UAAU,CAAC,QAAQ;wBAC7B,gBAAgB,EAAE,UAAU,CAAC,gBAAgB;wBAC7C,UAAU;wBACV,cAAc;wBACd,qBAAqB,EAAE,aAAa;wBACpC,eAAe,EAAE,SAAS,CAAC,eAAe;qBAC3C;iBACF,CAAC,CAAC;gBAEH,IAAI,UAAU,KAAK,WAAW,EAAE,CAAC;oBAC/B,GAAG,CAAC,MAAM,CAAC;wBACT,KAAK,EAAE,KAAK,CAAC,KAAK;wBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;wBACxB,SAAS,EAAE,SAAS,CAAC,SAAS;wBAC9B,MAAM,EAAE,kBAAkB;wBAC1B,SAAS,EAAE,eAAe;wBAC1B,MAAM,EAAE,SAAS,CAAC,MAAM;wBACxB,SAAS,EAAE,UAAU;wBACrB,UAAU,EAAE,SAAS,CAAC,UAAU;wBAChC,aAAa,EAAE,SAAS,CAAC,aAAa;qBACvC,CAAC,CAAC;oBACH,OAAO;gBACT,CAAC;gBAED,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;oBAC5B,GAAG,CAAC,MAAM,CAAC;wBACT,KAAK,EAAE,KAAK,CAAC,KAAK;wBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;wBACxB,SAAS,EAAE,SAAS,CAAC,SAAS;wBAC9B,MAAM,EAAE,kBAAkB;wBAC1B,SAAS,EAAE,YAAY;wBACvB,MAAM,EAAE,SAAS,CAAC,MAAM;wBACxB,SAAS,EAAE,UAAU;wBACrB,UAAU,EAAE,SAAS,CAAC,UAAU;wBAChC,aAAa,EAAE,SAAS,CAAC,aAAa;qBACvC,CAAC,CAAC;oBACH,OAAO;gBACT,CAAC;gBAED,IAAI,UAAU,KAAK,eAAe,EAAE,CAAC;oBACnC,GAAG,CAAC,MAAM,CAAC;wBACT,KAAK,EAAE,KAAK,CAAC,KAAK;wBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;wBACxB,SAAS,EAAE,SAAS,CAAC,SAAS;wBAC9B,MAAM,EAAE,kBAAkB;wBAC1B,SAAS,EAAE,mBAAmB;wBAC9B,MAAM,EAAE,SAAS,CAAC,MAAM;wBACxB,SAAS,EAAE,UAAU;wBACrB,UAAU,EAAE,SAAS,CAAC,UAAU;wBAChC,aAAa,EAAE,SAAS,CAAC,aAAa;wBACtC,QAAQ,EAAE;4BACR,UAAU;4BACV,aAAa,EAAE,aAAa,EAAE,SAAS,IAAI,IAAI;4BAC/C,oBAAoB,EAAE,oBAAoB,EAAE,SAAS,IAAI,IAAI;yBAC9D;qBACF,CAAC,CAAC;oBACH,OAAO;gBACT,CAAC;gBAED,IAAI,UAAU,KAAK,mBAAmB,EAAE,CAAC;oBACvC,MAAM,sBAAsB,CAAC,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;oBACvE,OAAO;gBACT,CAAC;gBAED,IAAI,UAAU,KAAK,cAAc;oBAAE,OAAO;gBAE1C,GAAG,CAAC,MAAM,CAAC;oBACT,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,SAAS,EAAE,SAAS,CAAC,SAAS;oBAC9B,MAAM,EAAE,kBAAkB;oBAC1B,SAAS,EAAE,kBAAkB;oBAC7B,MAAM,EAAE,SAAS,CAAC,MAAM;oBACxB,SAAS,EAAE,UAAU;oBACrB,UAAU,EAAE,SAAS,CAAC,UAAU;oBAChC,aAAa,EAAE,SAAS,CAAC,aAAa;oBACtC,QAAQ,EAAE;wBACR,UAAU;wBACV,gBAAgB,EAAE,UAAU,CAAC,gBAAgB;wBAC7C,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE;wBACrC,UAAU,EAAE,MAAM,CAAC,UAAU;qBAC9B;iBACF,CAAC,CAAC;gBAEH,MAAM,aAAa,GAAG,YAAY;oBAChC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;oBAC7D,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;gBACzB,MAAM,iBAAiB,GACrB,aAAa,GAAG,SAAS,CAAC,eAAe;oBACzC,aAAa,IAAI,SAAS,CAAC,sBAAsB,CAAC;gBAEpD,IAAI,iBAAiB,EAAE,CAAC;oBACtB,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC;wBACnC,KAAK,EAAE,KAAK,CAAC,KAAK;wBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;wBACxB,eAAe,EAAE,SAAS,CAAC,OAAO;wBAClC,QAAQ,EAAE,CAAC,cAAc,CAAC;wBAC1B,GAAG,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;qBAC1C,CAAC,CAAC;oBACH,IAAI,CAAC,OAAO;wBAAE,OAAO;oBAErB,GAAG,CAAC,MAAM,CAAC;wBACT,KAAK,EAAE,KAAK,CAAC,KAAK;wBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;wBACxB,SAAS,EAAE,OAAO,CAAC,SAAS;wBAC5B,MAAM,EAAE,kBAAkB;wBAC1B,SAAS,EAAE,mCAAmC;wBAC9C,MAAM,EAAE,OAAO,CAAC,MAAM;wBACtB,SAAS,EAAE,UAAU;wBACrB,UAAU,EAAE,OAAO,CAAC,UAAU;wBAC9B,aAAa,EAAE,OAAO,CAAC,aAAa;wBACpC,QAAQ,EAAE,EAAE,UAAU,EAAE,aAAa,EAAE,sBAAsB,EAAE,SAAS,CAAC,sBAAsB,EAAE;qBAClG,CAAC,CAAC;oBACH,SAAS;gBACX,CAAC;gBAED,IAAI,MAAM,CAAC,UAAU,KAAK,WAAW;oBAAE,OAAO;gBAE9C,MAAM,KAAK,CAAC,OAAO,CAAC;oBAClB,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,MAAM,EAAE,qBAAqB;oBAC7B,OAAO,EAAE,aAAa;oBACtB,SAAS,EAAE,GAAG,UAAU,IAAI,cAAc,EAAE;iBAC7C,CAAC,CAAC;gBACH,OAAO;YACT,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC/B,GAAG,CAAC,MAAM,CAAC;wBACT,KAAK,EAAE,KAAK,CAAC,KAAK;wBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;wBACxB,SAAS,EAAE,OAAO,CAAC,SAAS;wBAC5B,MAAM,EAAE,kBAAkB;wBAC1B,SAAS,EAAE,4BAA4B;wBACvC,MAAM,EAAE,OAAO,CAAC,MAAM;wBACtB,SAAS,EAAE,UAAU;wBACrB,UAAU,EAAE,OAAO,CAAC,UAAU;wBAC9B,aAAa,EAAE,OAAO,CAAC,aAAa;wBACpC,QAAQ,EAAE,EAAE,cAAc,EAAE;qBAC7B,CAAC,CAAC;oBACH,OAAO;gBACT,CAAC;gBAED,MAAM,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;gBAC5E,GAAG,CAAC,MAAM,CAAC;oBACT,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,SAAS,EAAE,OAAO,CAAC,SAAS;oBAC5B,MAAM,EAAE,kBAAkB;oBAC1B,SAAS,EAAE,YAAY;oBACvB,MAAM,EAAE,QAAQ;oBAChB,SAAS,EAAE,UAAU;oBACrB,UAAU,EAAE,OAAO,CAAC,UAAU;oBAC9B,aAAa,EAAE,OAAO,CAAC,aAAa;oBACpC,QAAQ,EAAE,EAAE,KAAK,EAAG,KAAe,CAAC,OAAO,EAAE;iBAC9C,CAAC,CAAC;gBACH,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;QAED,MAAM,wBAAwB,CAAC,KAAK,CAAC,CAAC;IACxC,CAAC;IAED,KAAK,UAAU,sBAAsB,CACnC,SAA0D,EAC1D,UAAuD,EACvD,UAAkB,EAClB,KAA8B;QAE9B,IAAI,UAAU,GAAkB,IAAI,CAAC;QACrC,IAAI,iBAAiB,GAAgB,IAAI,CAAC;QAE1C,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,MAAM,WAAW,GAAiD;gBAChE,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,UAAU,EAAE,SAAS,CAAC,UAAU;gBAChC,KAAK,EAAE,SAAS,CAAC,KAAK;gBACtB,UAAU;gBACV,UAAU,EAAE,SAAS,CAAC,OAAO;gBAC7B,YAAY,EAAE,SAAS,CAAC,YAAY;gBACpC,QAAQ,EAAE,UAAU,CAAC,QAAQ;gBAC7B,gBAAgB,EAAE,UAAU,CAAC,gBAAgB;gBAC7C,SAAS,EAAE,iCAAiC,UAAU,QAAQ,UAAU,CAAC,QAAQ,EAAE;gBACnF,cAAc,EAAE,UAAU,CAAC,cAAc,IAAI,sBAAsB;gBACnE,QAAQ,EAAE;oBACR,cAAc,EAAE,UAAU,CAAC,sBAAsB,IAAI,IAAI;oBACzD,kBAAkB,EAAE,KAAK,CAAC,MAAM,IAAI,OAAO;iBAC5C;aACF,CAAC;YACF,IAAI,UAAU,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;gBAC/C,WAAW,CAAC,iBAAiB,GAAG,UAAU,CAAC,iBAAiB,CAAC;YAC/D,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAChE,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC;YACjC,iBAAiB,GAAG,QAAQ,CAAC,SAAS,CAAC;QACzC,CAAC;QAED,GAAG,CAAC,MAAM,CAAC;YACT,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,SAAS,EAAE,SAAS,CAAC,SAAS;YAC9B,MAAM,EAAE,kBAAkB;YAC1B,SAAS,EAAE,uBAAuB;YAClC,MAAM,EAAE,SAAS,CAAC,MAAM;YACxB,SAAS,EAAE,UAAU;YACrB,UAAU,EAAE,SAAS,CAAC,UAAU;YAChC,aAAa,EAAE,SAAS,CAAC,aAAa;YACtC,QAAQ,EAAE;gBACR,UAAU;gBACV,UAAU;gBACV,cAAc,EAAE,UAAU,CAAC,cAAc,IAAI,sBAAsB;gBACnE,cAAc,EAAE,UAAU,CAAC,sBAAsB,IAAI,IAAI;gBACzD,iBAAiB,EAAE,iBAAiB,EAAE,WAAW,EAAE,IAAI,IAAI;aAC5D;SACF,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAChC,CAAC"}

package/dist/port.d.ts

@@ -0,0 +1,127 @@
+import type { CreateJobInput, JobOpsEventInput, JobSnapshot, JobStepRecord, WorkflowContext, WorkflowResolution } from "./types.js";
+import type { JobStatus, JobStepTriggeredBy, JobStepType } from "./enums.js";
+/** Thrown by `insertStep` when the unique idempotency key already exists. The adapter
+ *  maps Mongo duplicate-key (code 11000) onto this; the engine never sees `11000`. */
+export declare class DuplicateStepError extends Error {
+    constructor(message?: string);
+}
+export interface JobStore {
+    /** Read the current snapshot (mongo: findOne(...).lean()). */
+    getJob(jobId: string, tenantId: string): Promise<JobSnapshot | null>;
+    /** Create + persist a new job; returns its initial snapshot. */
+    createJob(input: CreateJobInput): Promise<JobSnapshot>;
+    /**
+     * CAS claim. Atomic conditional update keyed on (jobId,tenantId,expectedVersion,statusIn).
+     * Returns the NEW snapshot, or null when the version/status guard failed (claim lost).
+     * Adapter MUST implement as:
+     *   findOneAndUpdate({jobId,tenantId,version:expectedVersion,status:{$in:statusIn}},
+     *                    {$set:set, $inc:{version:1}}, {new:true}).lean()
+     */
+    claim(args: {
+        jobId: string;
+        tenantId: string;
+        expectedVersion: number;
+        statusIn: JobStatus[];
+        set: Partial<JobSnapshot>;
+    }): Promise<JobSnapshot | null>;
+    /**
+     * Version-guarded finalize (no status guard). Returns the NEW snapshot or null on
+     * lost CAS. Adapter: findOneAndUpdate({...,version:expectedVersion},
+     *   {$set:set, $inc:{version:1, ...incCounters}}, {new:true}).lean()
+     */
+    finalizeStep(args: {
+        jobId: string;
+        tenantId: string;
+        expectedVersion: number;
+        set: Partial<JobSnapshot>;
+        incCounters?: Record<string, number>;
+    }): Promise<JobSnapshot | null>;
+    /** Force the job to `failed` WITHOUT a version guard (terminal error path). */
+    markFailed(args: {
+        jobId: string;
+        tenantId: string;
+    }): Promise<void>;
+    /** Append a step. MUST throw `DuplicateStepError` when the unique key already exists. */
+    insertStep(step: JobStepRecord): Promise<void>;
+    findStepByIdempotencyKey(jobId: string, tenantId: string, idempotencyKey: string): Promise<JobStepRecord | null>;
+    /** Reconciler scan: waiting_time jobs with a non-null resumeAt <= asOf, oldest first. */
+    findDueWaitingTime(asOf: Date, limit: number): Promise<JobSnapshot[]>;
+}
+/** Enqueues an orchestrator tick (BullMQ behind this; jobId-based dedup via dedupeKey). */
+export interface QueuePort {
+    enqueue(args: {
+        jobId: string;
+        tenantId: string;
+        reason: string;
+        idempotencyKey?: string;
+        delayMs?: number;
+        dedupeKey?: string;
+    }): Promise<void>;
+}
+/** Distributed single-flight lock (Redis SET key val PX ttl NX). Auto-expires; no release. */
+export interface LockPort {
+    acquire(key: string, ttlMs: number): Promise<boolean>;
+}
+/** One-time nonce claim for resume-token replay protection (Redis SET key 1 EX ttl NX). */
+export interface NoncePort {
+    claimOnce(key: string, ttlSeconds: number): Promise<boolean>;
+}
+/** Injected clock — makes cron/reconciler/inline-resume math deterministic in tests. */
+export interface ClockPort {
+    now(): Date;
+}
+/** Fire-and-forget operational ledger sink. Implementations MUST NOT throw. */
+export interface JobOpsPort {
+    record(event: JobOpsEventInput): void;
+}
+/** Pluggable workflow definition resolver (data-driven; fed from the manifest). */
+export interface WorkflowRegistry {
+    resolveStep(ctx: WorkflowContext): WorkflowResolution;
+}
+/**
+ * Executes the side-effecting work of a step. For `run_interaction_task` this runs an
+ * actual agent turn (in platform-ai: a @msm-core/mini turn); for pure transitions
+ * (wait_time/complete/fail/wait_event) it returns {}. The returned output/statePatch
+ * are merged onto the workflow resolution's. Throwing fails the step (job → failed).
+ */
+export interface StepExecutorPort {
+    execute(args: {
+        stepType: JobStepType;
+        triggeredBy: JobStepTriggeredBy;
+        job: JobSnapshot;
+        resolution: WorkflowResolution;
+        stepNumber: number;
+    }): Promise<{
+        output?: Record<string, unknown>;
+        statePatch?: Record<string, unknown>;
+    }>;
+}
+/**
+ * Creates an HITL approval record when a step transitions to `awaiting_approval`.
+ * Optional in S1 (engine just records the transition if absent); the real approval
+ * engine plugs in here in S2.
+ */
+export interface ApprovalCreatorPort {
+    create(input: {
+        tenantId: string;
+        employeeId: string;
+        jobId: string;
+        stepNumber: number;
+        jobVersion: number;
+        workflowType: string;
+        stepType: JobStepType;
+        transitionReason: string;
+        reasoning: string;
+        approvalPolicy: string;
+        approvalTimeoutMs?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        approvalId: string;
+        expiresAt: Date | null;
+    }>;
+}
+/** Step-id generator (default: crypto.randomUUID). */
+export interface IdGeneratorPort {
+    jobStepId(): string;
+}
+//# sourceMappingURL=port.d.ts.map

package/dist/port.d.ts.map

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

package/dist/port.js

@@ -0,0 +1,17 @@
+// @msm-core/jobs — the PORTS. The engine is pure decision logic; ALL infrastructure
+// (Mongo, BullMQ, Redis, wall-clock) is injected through these interfaces, so this
+// package carries NO mongoose/bullmq/ioredis dependency.
+//
+// The two correctness-critical atomics are FIRST-CLASS, named methods — `claim` and
+// `finalizeStep` (version-guarded compare-and-set) and `insertStep` (unique-key
+// idempotency). The adapter is the single place that must get Mongo atomics right;
+// the engine catches exactly one typed failure (`DuplicateStepError`).
+/** Thrown by `insertStep` when the unique idempotency key already exists. The adapter
+ *  maps Mongo duplicate-key (code 11000) onto this; the engine never sees `11000`. */
+export class DuplicateStepError extends Error {
+    constructor(message = "Duplicate job step (idempotency key already used)") {
+        super(message);
+        this.name = "DuplicateStepError";
+    }
+}
+//# sourceMappingURL=port.js.map

package/dist/port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.js","sourceRoot":"","sources":["../src/port.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,mFAAmF;AACnF,yDAAyD;AACzD,EAAE;AACF,oFAAoF;AACpF,gFAAgF;AAChF,mFAAmF;AACnF,uEAAuE;AAYvE;sFACsF;AACtF,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAO,GAAG,mDAAmD;QACvE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/dist/reconciler.d.ts

@@ -0,0 +1,25 @@
+import type { ClockPort, JobOpsPort, JobStore, LockPort, QueuePort } from "./port.js";
+import type { JobEngineConfig } from "./config.js";
+export interface WaitingTimeReconcileResult {
+    locked: boolean;
+    scanned: number;
+    enqueued: number;
+    failed: number;
+    skippedByMode: boolean;
+    asOf: string;
+}
+export interface ReconcilerDeps {
+    jobStore: JobStore;
+    queue: QueuePort;
+    lock: LockPort;
+    ops: JobOpsPort;
+    clock: ClockPort;
+    config: JobEngineConfig;
+    /** Lock TTL — should be ~the scan interval so a crashed scanner's lock expires. */
+    lockTtlMs: number;
+}
+export interface Reconciler {
+    reconcileWaitingTimeJobs(asOf?: Date): Promise<WaitingTimeReconcileResult>;
+}
+export declare function createReconciler(deps: ReconcilerDeps): Reconciler;
+//# sourceMappingURL=reconciler.d.ts.map

package/dist/reconciler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconciler.d.ts","sourceRoot":"","sources":["../src/reconciler.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAKnD,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,OAAO,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,UAAU,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,MAAM,EAAE,eAAe,CAAC;IACxB,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,wBAAwB,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;CAC5E;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,UAAU,CA4EjE"}