@msm-core/jobs 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog — @msm-core/jobs
+
+All notable changes are documented here. Follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [0.6.0] — 2026-06-30
+
+Durability hardening from the 2026-06 SDK audit (the two `jobs` criticals + two highs).
+Every fix ships with a reproduction test.
+
+### Fixed
+
+- **(C1) Exactly-once is now crash-safe.** The default step idempotency key embedded the
+  job `version`, which the claim increments on every delivery — so a crash *between*
+  `insertStep` and `finalizeStep` made a re-delivery compute a **different** key, miss the
+  already-recorded step, and **re-run the side effect** (reproduced: `execCount=2`). The key
+  is now stable per logical step (`${jobId}:step:${currentStep}`, independent of version and
+  trigger reason). To make recovery correct rather than merely de-duplicated, each step now
+  records the exact transition it decided (`JobStepRecord.finalize`), and a re-delivery that
+  finds an un-finalized step **re-applies that transition** to advance the job — without
+  re-running the side effect. New tests: `engine.test.ts › crash-safety`.
+- **(H4) A transient infra error no longer force-fails a healthy job.** The step body was
+  wrapped in one broad `try/catch` that routed *any* throw — including a `finalizeStep`,
+  `enqueue`, or token-issue blip — into `markFailed`, permanently failing an otherwise-healthy
+  job (sometimes after its side effect had already landed). Failure handling is now scoped:
+  only a throw from the workflow resolver or the step's own `stepExecutor.execute` fails the
+  job; infra throws **propagate** so the queue retries the tick (the stable key above makes the
+  retry safe). New tests cover both the transient-insert and the genuine-step-failure paths.
+- **(H3) The mission scheduler no longer double-spawns.** `countActiveByMission → createJob →
+  markTriggered` was an unguarded read-modify-write; two concurrent ticks could both pass the
+  concurrency check and both spawn, overrunning `maxConcurrentJobs`. Each mission's spawn is now
+  wrapped in a per-mission `LockPort` single-flight (`jobs:mission_spawn:<tenant>:<mission>`),
+  supplied automatically by `createJobEngine`. New tests: `mission-approval.test.ts`.
+
+### Added
+
+- **Resume-token crypto test suite (C2).** The JWT signing, the HS256 allow-list, the
+  tenant/job/event binding, one-time-use replay rejection (409), and the fail-closed
+  replay-unavailable path (503) had **zero** behavioral coverage (every prior test stubbed
+  `claimOnce → true`). New `resume-token.test.ts` (13 cases) exercises round-trip, replay,
+  tamper, wrong-secret, **alg-swap (HS512) and alg:none rejection**, expiry, binding mismatch,
+  and the 503 path — with a real in-memory `NoncePort`.
+- `JobStepRecord.finalize?` — the durable transition a step decided (see C1). Optional and
+  backward-compatible: steps written by ≤0.5.0 simply fall through to the legacy skip path.
+- `MissionSchedulerDeps.lock?` + `spawnLockTtlMs?` for the H3 single-flight.
+- `package.json` `repository` field (npm provenance / source links).
+
+### Upgrade notes
+
+- **Idempotency key format changed.** Jobs that are *mid-step at the moment of upgrade* recorded
+  their step under the old key format; the new code computes a different key for that one
+  in-flight transition and may re-execute it once. For at-most-once-sensitive workflows, drain
+  the queue (or quiesce in-flight jobs) before deploying. Jobs created after the upgrade are
+  unaffected.
+- No port/signature breaking changes. `JobStepRecord` gained an **optional** field; Mongo
+  adapters should persist and return `finalize` to get crash-recovery (omitting it preserves
+  ≤0.5.0 behavior — no re-execution protection across a crash, but no errors).
+
+---
+
+## [0.5.0] — prior
+
+Initial durable engine extracted from kader: CAS claim/finalize, idempotent `insertStep`,
+inline-resume + delayed/scan reconciler modes, cron missions with quiet-hours/cooldown/overlap,
+HITL approval engine, resume tokens, P2-8 tenant/day cost ceiling.

package/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2026 MSM / UTS. All rights reserved.
+
+PROPRIETARY AND CONFIDENTIAL
+
+This package (@msm-core/jobs) and its contents (the "Software") are the proprietary and
+confidential property of MSM / UTS ("the Owner").
+
+No license, right, or permission is granted to any party to use, copy, modify,
+merge, publish, distribute, sublicense, sell, or create derivative works of the
+Software, in whole or in part, except under a separate written agreement signed
+by the Owner.
+
+This package is published to the public npm registry solely to enable
+installation as a runtime dependency. Such publication is NOT a grant of any
+license to its source. The package is "UNLICENSED" (proprietary) as declared in
+its manifest. Reproducing, reverse engineering, or redistributing it is not
+permitted.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.

package/dist/approval/engine.d.ts

@@ -27,4 +27,3 @@ export interface ApprovalEngine extends ApprovalCreatorPort {
     expireStale(asOf?: Date): Promise<number>;
 }
 export declare function createApprovalEngine(deps: ApprovalEngineDeps): ApprovalEngine;
-//# sourceMappingURL=engine.d.ts.map

package/dist/approval/engine.js

@@ -143,4 +143,3 @@ export function createApprovalEngine(deps) {
     }
     return { create, resolve, expireStale };
 }
-//# sourceMappingURL=engine.js.map

package/dist/approval/policy.d.ts

@@ -5,4 +5,3 @@ export declare const DEFAULT_JOB_APPROVAL_POLICY: JobApprovalPolicy;
 export declare function isJobApprovalPolicy(value: unknown): value is JobApprovalPolicy;
 export declare function parseJobApprovalPolicy(value: unknown, fallback?: JobApprovalPolicy): JobApprovalPolicy;
 export declare function resolveJobApprovalTimeoutOutcome(policy: JobApprovalPolicy): JobApprovalTimeoutOutcome;
-//# sourceMappingURL=policy.d.ts.map

package/dist/approval/policy.js

@@ -19,4 +19,3 @@ export function resolveJobApprovalTimeoutOutcome(policy) {
         return "save_draft_remind_owner_next_day";
     return "notify_owner_paused";
 }
-//# sourceMappingURL=policy.js.map

package/dist/config.d.ts

@@ -37,4 +37,3 @@ export interface OrchestratorRunConfig {
     inlineResumeMaxDelayMs: number;
 }
 export declare function resolveRunConfig(config: JobEngineConfig): OrchestratorRunConfig;
-//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -15,4 +15,3 @@ export function resolveRunConfig(config) {
         inlineResumeMaxDelayMs: Math.max(0, config.inlineResumeMaxDelayMs),
     };
 }
-//# sourceMappingURL=config.js.map

package/dist/enums.d.ts

@@ -3,7 +3,7 @@ export type JobStatus = (typeof JOB_STATUSES)[number];
 export declare const TERMINAL_JOB_STATUSES: readonly ["completed", "failed", "cancelled"];
 export type TerminalJobStatus = (typeof TERMINAL_JOB_STATUSES)[number];
 export declare const RUNNABLE_JOB_STATUSES: readonly ["queued", "running"];
-export declare const JOB_STEP_TYPES: readonly ["run_interaction_task", "wait_time", "wait_event", "task_handoff", "notify_owner", "notify_customer", "complete", "fail"];
+export declare const JOB_STEP_TYPES: readonly ["run_interaction_task", "wait_time", "wait_event", "task_handoff", "connector_action", "notify_owner", "notify_customer", "complete", "fail"];
 export type JobStepType = (typeof JOB_STEP_TYPES)[number];
 export declare const JOB_STEP_STATUSES: readonly ["running", "completed", "failed", "skipped"];
 export type JobStepStatus = (typeof JOB_STEP_STATUSES)[number];
@@ -13,4 +13,3 @@ export declare const MISSION_RUN_STATUSES: readonly ["started", "completed", "sk
 export type MissionRunStatus = (typeof MISSION_RUN_STATUSES)[number];
 export declare function isTerminalJobStatus(status: string): status is TerminalJobStatus;
 export declare function isRunnableJobStatus(status: string): boolean;
-//# sourceMappingURL=enums.d.ts.map

package/dist/enums.js

@@ -19,6 +19,7 @@ export const JOB_STEP_TYPES = [
     "wait_time",
     "wait_event",
     "task_handoff",
+    "connector_action",
     "notify_owner",
     "notify_customer",
     "complete",
@@ -33,4 +34,3 @@ export function isTerminalJobStatus(status) {
 export function isRunnableJobStatus(status) {
     return RUNNABLE_JOB_STATUSES.includes(status);
 }
-//# sourceMappingURL=enums.js.map

package/dist/index.d.ts

@@ -46,7 +46,7 @@ export { DEFAULT_JOB_ENGINE_CONFIG };
 export type { JobEngineConfig, OrchestrateJobStepInput };
 export type { ResumeTokenService };
 export { createResumeTokenService, ResumeTokenError, type IssuedResumeToken, type ConsumedResumeToken, } from "./resume-token.js";
-export { createWorkflowRegistry, BUILTIN_JOB_BASIC } from "./workflow/registry.js";
+export { createWorkflowRegistry, BUILTIN_JOB_BASIC, BUILTIN_CONNECTOR_WRITE } from "./workflow/registry.js";
 export type { WaitingTimeReconcileResult } from "./reconciler.js";
 export { createMissionScheduler, type MissionScheduler } from "./mission/scheduler.js";
 export { isMissionCronDueAt, isWithinQuietHours, matchesCronField, parseDurationToMs, } from "./mission/cron.js";
@@ -56,4 +56,3 @@ export { JOB_STATUSES, TERMINAL_JOB_STATUSES, RUNNABLE_JOB_STATUSES, JOB_STEP_TY
 export type { JobBudget, JobWaitEvent, JobSnapshot, JobStepRecord, JobStepToolCall, CreateJobInput, JobOpsEventInput, WorkflowResolution, WorkflowContext, WorkflowSequenceStep, WorkflowDefinition, } from "./types.js";
 export { JOB_APPROVAL_POLICIES, DEFAULT_JOB_APPROVAL_POLICY, isJobApprovalPolicy, parseJobApprovalPolicy, resolveJobApprovalTimeoutOutcome, type JobApprovalPolicy, type JobApprovalTimeoutOutcome, } from "./approval/policy.js";
 export * from "./port.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -59,6 +59,7 @@ export function createJobEngine(deps) {
             ops: deps.ops,
             clock: deps.clock,
             genMissionRunId: deps.genMissionRunId ?? (() => `mrun_${randomUUID()}`),
+            lock: deps.lock, // H3: per-mission single-flight so concurrent ticks can't double-spawn
         })
         : undefined;
     return {
@@ -72,7 +73,7 @@ export function createJobEngine(deps) {
 // ── Public surface ──
 export { DEFAULT_JOB_ENGINE_CONFIG };
 export { createResumeTokenService, ResumeTokenError, } from "./resume-token.js";
-export { createWorkflowRegistry, BUILTIN_JOB_BASIC } from "./workflow/registry.js";
+export { createWorkflowRegistry, BUILTIN_JOB_BASIC, BUILTIN_CONNECTOR_WRITE } from "./workflow/registry.js";
 // S2 — missions + approval
 export { createMissionScheduler } from "./mission/scheduler.js";
 export { isMissionCronDueAt, isWithinQuietHours, matchesCronField, parseDurationToMs, } from "./mission/cron.js";
@@ -82,4 +83,3 @@ export { JOB_STATUSES, TERMINAL_JOB_STATUSES, RUNNABLE_JOB_STATUSES, JOB_STEP_TY
 export { JOB_APPROVAL_POLICIES, DEFAULT_JOB_APPROVAL_POLICY, isJobApprovalPolicy, parseJobApprovalPolicy, resolveJobApprovalTimeoutOutcome, } from "./approval/policy.js";
 // Ports + the typed atomic-failure error
 export * from "./port.js";
-//# sourceMappingURL=index.js.map

package/dist/mission/cron.d.ts

@@ -20,4 +20,3 @@ export declare function isMissionCronDueAt(params: {
     now: Date;
     lastTriggeredAt?: Date | null;
 }): boolean;
-//# sourceMappingURL=cron.d.ts.map

package/dist/mission/cron.js

@@ -172,4 +172,3 @@ export function isMissionCronDueAt(params) {
         return dayOfMonthMatches || dayOfWeekMatches;
     return dayOfMonthMatches && dayOfWeekMatches;
 }
-//# sourceMappingURL=cron.js.map

package/dist/mission/scheduler.d.ts

@@ -1,4 +1,4 @@
-import type { ClockPort, JobOpsPort, JobStore, MissionStore } from "../port.js";
+import type { ClockPort, JobOpsPort, JobStore, LockPort, MissionStore } from "../port.js";
 import type { MissionSchedulerTickResult } from "../types.js";
 export interface MissionSchedulerDeps {
     missionStore: MissionStore;
@@ -6,9 +6,18 @@ export interface MissionSchedulerDeps {
     ops: JobOpsPort;
     clock: ClockPort;
     genMissionRunId: () => string;
+    /**
+     * Per-mission single-flight lock. Without it, two concurrent scheduler ticks can
+     * BOTH pass the `countActiveByMission` concurrency check and BOTH spawn a job
+     * (overrunning `maxConcurrentJobs`). The assembled engine (createJobEngine)
+     * supplies this automatically; it is optional only so the scheduler can be unit
+     * tested in isolation. Auto-expiring (no release), so a crashed tick frees it.
+     */
+    lock?: LockPort;
+    /** TTL for the per-mission spawn lock (default 30s — outlasts one spawn, then frees). */
+    spawnLockTtlMs?: number;
 }
 export interface MissionScheduler {
     processSchedulerTick(now?: Date): Promise<MissionSchedulerTickResult>;
 }
 export declare function createMissionScheduler(deps: MissionSchedulerDeps): MissionScheduler;
-//# sourceMappingURL=scheduler.d.ts.map

package/dist/mission/scheduler.js

@@ -74,6 +74,28 @@ export function createMissionScheduler(deps) {
                 result.skipped += 1;
                 continue;
             }
+            // SINGLE-FLIGHT (H3): the concurrency check → spawn → markTriggered sequence
+            // below is a read-modify-write that two concurrent ticks would both pass,
+            // double-spawning past maxConcurrentJobs. Hold a per-mission lock across it.
+            // (lastTriggeredAt/cron-due already de-dupe SEQUENTIAL ticks; this guards the
+            // SIMULTANEOUS case where neither tick has stamped lastTriggeredAt yet.)
+            if (deps.lock) {
+                const lockKey = `jobs:mission_spawn:${mission.tenantId}:${mission.missionId}`;
+                const acquired = await deps.lock.acquire(lockKey, Math.max(5_000, deps.spawnLockTtlMs ?? 30_000));
+                if (!acquired) {
+                    ops.record({
+                        jobId: `mission:${mission.missionId}`,
+                        tenantId: mission.tenantId,
+                        missionId: mission.missionId,
+                        source: "mission_scheduler",
+                        eventType: "mission.scheduler.run.lock_contended",
+                        status: "skipped",
+                        employeeId: mission.employeeId,
+                        metadata: { reason: "concurrent_tick_holds_spawn_lock" },
+                    });
+                    continue;
+                }
+            }
             const activeJobs = await jobStore.countActiveByMission(mission.tenantId, mission.missionId, ACTIVE_JOB_STATUSES);
             const maxConcurrentJobs = Math.max(1, mission.safety?.maxConcurrentJobs || 1);
             if (activeJobs >= maxConcurrentJobs) {
@@ -182,4 +204,3 @@ export function createMissionScheduler(deps) {
     }
     return { processSchedulerTick };
 }
-//# sourceMappingURL=scheduler.js.map

package/dist/orchestrator.d.ts

@@ -24,4 +24,3 @@ export interface Orchestrator {
     orchestrateJobStep(input: OrchestrateJobStepInput): Promise<void>;
 }
 export declare function createOrchestrator(deps: OrchestratorDeps): Orchestrator;
-//# sourceMappingURL=orchestrator.d.ts.map