@voyantjs/workflows-orchestrator 0.38.0 → 0.38.1

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { createHttpStepHandler, type HttpStepHandlerDeps, type HttpStepTarget, }
 export { createInMemoryRunStore } from "./in-memory-store.js";
 export { emptyJournal } from "./journal-helpers.js";
 export { type CancelArgs, cancel, type OrchestratorDeps, type ResumeArgs, type ResumeDueAlarmsArgs, resume, resumeDueAlarms, type TriggerArgs, trigger, } from "./orchestrator.js";
+export { type BuildResumeJournalInput, type BuildResumeJournalResult, type BuildSeededResumeJournalInput, buildResumeJournal, buildSeededResumeJournal, } from "./resume-run.js";
 export { type CronSpec, computeNextFire, createScheduler, manifestScheduleSources, nextCronFire, parseCron, type SchedulableDeclaration, type SchedulerDeps, type SchedulerHandle, type ScheduleSource, toMs, } from "./schedule.js";
 export * from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,kBAAkB,GACnB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,KAAK,mBAAmB,EACxB,qCAAqC,EACrC,KAAK,+BAA+B,EACpC,KAAK,wBAAwB,EAC7B,qBAAqB,EACrB,gCAAgC,GACjC,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,uBAAuB,EAAE,KAAK,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AACzF,OAAO,EACL,oBAAoB,EACpB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,UAAU,GACX,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,EACL,KAAK,UAAU,EACf,MAAM,EACN,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,MAAM,EACN,eAAe,EACf,KAAK,WAAW,EAChB,OAAO,GACR,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,KAAK,QAAQ,EACb,eAAe,EACf,eAAe,EACf,uBAAuB,EACvB,YAAY,EACZ,SAAS,EACT,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,IAAI,GACL,MAAM,eAAe,CAAA;AACtB,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,kBAAkB,GACnB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,KAAK,mBAAmB,EACxB,qCAAqC,EACrC,KAAK,+BAA+B,EACpC,KAAK,wBAAwB,EAC7B,qBAAqB,EACrB,gCAAgC,GACjC,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,uBAAuB,EAAE,KAAK,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AACzF,OAAO,EACL,oBAAoB,EACpB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,UAAU,GACX,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,EACL,KAAK,UAAU,EACf,MAAM,EACN,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,MAAM,EACN,eAAe,EACf,KAAK,WAAW,EAChB,OAAO,GACR,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,KAAK,6BAA6B,EAClC,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,KAAK,QAAQ,EACb,eAAe,EACf,eAAe,EACf,uBAAuB,EACvB,YAAY,EACZ,SAAS,EACT,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,IAAI,GACL,MAAM,eAAe,CAAA;AACtB,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -17,5 +17,6 @@ export { createHttpStepHandler, } from "./http-step-handler.js";
 export { createInMemoryRunStore } from "./in-memory-store.js";
 export { emptyJournal } from "./journal-helpers.js";
 export { cancel, resume, resumeDueAlarms, trigger, } from "./orchestrator.js";
+export { buildResumeJournal, buildSeededResumeJournal, } from "./resume-run.js";
 export { computeNextFire, createScheduler, manifestScheduleSources, nextCronFire, parseCron, toMs, } from "./schedule.js";
 export * from "./types.js";

package/dist/orchestrator.d.ts

@@ -38,6 +38,13 @@ export interface TriggerArgs {
      * run.
      */
     initialJournal?: JournalSlice;
+    /**
+     * Metadata cursor paired with `initialJournal`. Resume callers that
+     * seed a journal with an existing `metadataState` must also seed the
+     * positional cursor so replayed metadata mutations are not applied
+     * twice.
+     */
+    initialMetadataAppliedCount?: number;
     /**
      * Compute-time budget in ms, typically from `WorkflowConfig.timeout`.
      * Parked time on waitpoints does not count against this. When the

package/dist/orchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../src/orchestrator.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAGnD,OAAO,EAA2B,KAAK,YAAY,EAAoB,MAAM,YAAY,CAAA;AAEzF,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,cAAc,EACd,UAAU,EACV,WAAW,EACX,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,eAAe,EAAE,MAAM,CAAA;IACvB,KAAK,EAAE,OAAO,CAAA;IACd,UAAU,EAAE,SAAS,CAAC,YAAY,CAAC,CAAA;IACnC,WAAW,CAAC,EAAE,SAAS,CAAC,aAAa,CAAC,CAAA;IACtC,WAAW,CAAC,EAAE,UAAU,CAAA;IACxB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAA;IACvB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,cAAc,CAAC,EAAE,YAAY,CAAA;IAC7B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/C;;;OAGG;IACH,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAA;CACjD;AAED,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,KAAK,EAAE,cAAc,CAAA;IACrB,OAAO,EAAE,WAAW,CAAA;IACpB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,MAAM,CAAA;CAC3B;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CA6F3F;AA8FD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,kBAAkB,CAAA;CAC9B;AAED,wBAAsB,MAAM,CAC1B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CACN;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GAC/B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,YAAY,GAAG,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAClF,CA0CA;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAsC3B;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,wBAAsB,MAAM,CAC1B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CACN;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GAC/B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAC3E,CAqCA"}
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../src/orchestrator.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator.js

@@ -32,7 +32,7 @@ export async function trigger(args, deps) {
         input: args.input,
         journal: args.initialJournal ? cloneJournal(args.initialJournal) : emptyJournal(),
         invocationCount: 0,
-        metadataAppliedCount: 0,
+        metadataAppliedCount: args.initialMetadataAppliedCount ?? 0,
         computeTimeMs: 0,
         timeoutMs: args.timeoutMs,
         priority: args.priority,

package/dist/resume-run.d.ts

@@ -0,0 +1,23 @@
+import type { JournalSlice, RunRecord } from "./types.js";
+export interface BuildResumeJournalInput {
+    parent: RunRecord;
+    resumeFromStep?: string;
+    seedResults?: Record<string, unknown>;
+    now?: () => number;
+}
+export interface BuildResumeJournalResult {
+    resumeFromStep: string;
+    journal: JournalSlice;
+    metadataAppliedCount: number;
+}
+export interface BuildSeededResumeJournalInput {
+    parentRunId: string;
+    resumeFromStep: string;
+    seedResults: Record<string, unknown>;
+    metadataState?: Record<string, unknown>;
+    metadataAppliedCount?: number;
+    now?: () => number;
+}
+export declare function buildResumeJournal(input: BuildResumeJournalInput): BuildResumeJournalResult;
+export declare function buildSeededResumeJournal(input: BuildSeededResumeJournalInput): BuildResumeJournalResult;
+//# sourceMappingURL=resume-run.d.ts.map

package/dist/resume-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume-run.d.ts","sourceRoot":"","sources":["../src/resume-run.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAoB,MAAM,YAAY,CAAA;AAE3E,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,SAAS,CAAA;IACjB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACrC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,wBAAwB;IACvC,cAAc,EAAE,MAAM,CAAA;IACtB,OAAO,EAAE,YAAY,CAAA;IACrB,oBAAoB,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,6BAA6B;IAC5C,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;IACtB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACvC,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,wBAAwB,CAwC3F;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,6BAA6B,GACnC,wBAAwB,CAgB1B"}

package/dist/resume-run.js

@@ -0,0 +1,65 @@
+import { emptyJournal } from "./journal-helpers.js";
+export function buildResumeJournal(input) {
+    const resumeFromStep = input.resumeFromStep ?? findFirstFailedStep(input.parent);
+    if (!resumeFromStep) {
+        throw new Error(`run "${input.parent.id}" has no failed step; pass resumeFromStep explicitly to resume it`);
+    }
+    const journal = emptyJournal();
+    journal.metadataState = structuredClone(input.parent.journal.metadataState);
+    if (input.seedResults) {
+        return buildSeededResumeJournal({
+            parentRunId: input.parent.id,
+            resumeFromStep,
+            seedResults: input.seedResults,
+            metadataState: journal.metadataState,
+            metadataAppliedCount: input.parent.metadataAppliedCount,
+            now: input.now,
+        });
+    }
+    for (const [stepId, entry] of Object.entries(input.parent.journal.stepResults)) {
+        if (stepId === resumeFromStep)
+            break;
+        if (entry.status !== "ok") {
+            throw new Error(`step "${stepId}" completed before "${resumeFromStep}" but is not successful; cannot seed resume journal`);
+        }
+        journal.stepResults[stepId] = structuredClone(entry);
+    }
+    return {
+        resumeFromStep,
+        journal,
+        metadataAppliedCount: input.parent.metadataAppliedCount,
+    };
+}
+export function buildSeededResumeJournal(input) {
+    const journal = emptyJournal();
+    journal.metadataState = input.metadataState
+        ? structuredClone(input.metadataState)
+        : {};
+    const now = input.now ?? (() => Date.now());
+    let at = now();
+    for (const [stepId, output] of Object.entries(input.seedResults)) {
+        journal.stepResults[stepId] = seededStepEntry(output, at);
+        at += 1;
+    }
+    return {
+        resumeFromStep: input.resumeFromStep,
+        journal,
+        metadataAppliedCount: input.metadataAppliedCount ?? 0,
+    };
+}
+function findFirstFailedStep(parent) {
+    for (const [stepId, entry] of Object.entries(parent.journal.stepResults)) {
+        if (entry.status === "err")
+            return stepId;
+    }
+    return undefined;
+}
+function seededStepEntry(output, at) {
+    return {
+        attempt: 1,
+        status: "ok",
+        output,
+        startedAt: at,
+        finishedAt: at,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/workflows-orchestrator",
-  "version": "0.38.0",
+  "version": "0.38.1",
   "description": "Reference orchestrator core for Voyant Workflows — drives runs through the tenant step handler over the v1 wire protocol.",
   "license": "Apache-2.0",
   "repository": {
@@ -30,7 +30,7 @@
     "NOTICE"
   ],
   "dependencies": {
-    "@voyantjs/workflows": "0.38.0"
+    "@voyantjs/workflows": "0.38.1"
   },
   "devDependencies": {
     "@types/node": "^20.12.0",

package/src/index.ts

@@ -50,6 +50,13 @@ export {
   type TriggerArgs,
   trigger,
 } from "./orchestrator.js"
+export {
+  type BuildResumeJournalInput,
+  type BuildResumeJournalResult,
+  type BuildSeededResumeJournalInput,
+  buildResumeJournal,
+  buildSeededResumeJournal,
+} from "./resume-run.js"
 export {
   type CronSpec,
   computeNextFire,

package/src/orchestrator.ts

@@ -58,6 +58,13 @@ export interface TriggerArgs {
    * run.
    */
   initialJournal?: JournalSlice
+  /**
+   * Metadata cursor paired with `initialJournal`. Resume callers that
+   * seed a journal with an existing `metadataState` must also seed the
+   * positional cursor so replayed metadata mutations are not applied
+   * twice.
+   */
+  initialMetadataAppliedCount?: number
   /**
    * Compute-time budget in ms, typically from `WorkflowConfig.timeout`.
    * Parked time on waitpoints does not count against this. When the
@@ -109,7 +116,7 @@ export async function trigger(args: TriggerArgs, deps: OrchestratorDeps): Promis
     input: args.input,
     journal: args.initialJournal ? cloneJournal(args.initialJournal) : emptyJournal(),
     invocationCount: 0,
-    metadataAppliedCount: 0,
+    metadataAppliedCount: args.initialMetadataAppliedCount ?? 0,
     computeTimeMs: 0,
     timeoutMs: args.timeoutMs,
     priority: args.priority,

package/src/resume-run.ts

@@ -0,0 +1,103 @@
+import { emptyJournal } from "./journal-helpers.js"
+import type { JournalSlice, RunRecord, StepJournalEntry } from "./types.js"
+
+export interface BuildResumeJournalInput {
+  parent: RunRecord
+  resumeFromStep?: string
+  seedResults?: Record<string, unknown>
+  now?: () => number
+}
+
+export interface BuildResumeJournalResult {
+  resumeFromStep: string
+  journal: JournalSlice
+  metadataAppliedCount: number
+}
+
+export interface BuildSeededResumeJournalInput {
+  parentRunId: string
+  resumeFromStep: string
+  seedResults: Record<string, unknown>
+  metadataState?: Record<string, unknown>
+  metadataAppliedCount?: number
+  now?: () => number
+}
+
+export function buildResumeJournal(input: BuildResumeJournalInput): BuildResumeJournalResult {
+  const resumeFromStep = input.resumeFromStep ?? findFirstFailedStep(input.parent)
+  if (!resumeFromStep) {
+    throw new Error(
+      `run "${input.parent.id}" has no failed step; pass resumeFromStep explicitly to resume it`,
+    )
+  }
+
+  const journal = emptyJournal()
+  journal.metadataState = structuredClone(input.parent.journal.metadataState) as Record<
+    string,
+    unknown
+  >
+
+  if (input.seedResults) {
+    return buildSeededResumeJournal({
+      parentRunId: input.parent.id,
+      resumeFromStep,
+      seedResults: input.seedResults,
+      metadataState: journal.metadataState,
+      metadataAppliedCount: input.parent.metadataAppliedCount,
+      now: input.now,
+    })
+  }
+
+  for (const [stepId, entry] of Object.entries(input.parent.journal.stepResults)) {
+    if (stepId === resumeFromStep) break
+    if (entry.status !== "ok") {
+      throw new Error(
+        `step "${stepId}" completed before "${resumeFromStep}" but is not successful; cannot seed resume journal`,
+      )
+    }
+    journal.stepResults[stepId] = structuredClone(entry) as StepJournalEntry
+  }
+
+  return {
+    resumeFromStep,
+    journal,
+    metadataAppliedCount: input.parent.metadataAppliedCount,
+  }
+}
+
+export function buildSeededResumeJournal(
+  input: BuildSeededResumeJournalInput,
+): BuildResumeJournalResult {
+  const journal = emptyJournal()
+  journal.metadataState = input.metadataState
+    ? (structuredClone(input.metadataState) as Record<string, unknown>)
+    : {}
+  const now = input.now ?? (() => Date.now())
+  let at = now()
+  for (const [stepId, output] of Object.entries(input.seedResults)) {
+    journal.stepResults[stepId] = seededStepEntry(output, at)
+    at += 1
+  }
+  return {
+    resumeFromStep: input.resumeFromStep,
+    journal,
+    metadataAppliedCount: input.metadataAppliedCount ?? 0,
+  }
+}
+
+function findFirstFailedStep(parent: RunRecord): string | undefined {
+  for (const [stepId, entry] of Object.entries(parent.journal.stepResults)) {
+    if (entry.status === "err") return stepId
+  }
+  return undefined
+}
+
+function seededStepEntry(output: unknown, at: number): StepJournalEntry {
+  return {
+    attempt: 1,
+    status: "ok",
+    output,
+    startedAt: at,
+    finishedAt: at,
+  }
+}