@elie-laloum/outpost 7.0.0 → 8.0.0

package/dist/domain/workflow/loop-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-runner.js","sourceRoot":"","sources":["../../../src/domain/workflow/loop-runner.ts"],"names":[],"mappings":"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","sourcesContent":["import { checkpointValue } from \"./checkpoint-value.ts\";\nimport { LoopTaskExhausted } from \"./loop-task.ts\";\nimport { validateLoopCheck } from \"./loop-validation.ts\";\nimport type { Task, WorkflowExecutionState } from \"../workflow.types.ts\";\nimport type {\n  LoopDefinition,\n  LoopRoundRecord,\n  LoopTaskContext,\n} from \"./loop-task.types.ts\";\n\nexport async function runLoopTask(\n  item: Task,\n  definition: LoopDefinition,\n  runtime: WorkflowExecutionState,\n): Promise<unknown> {\n  const state = runtime.record(item);\n  let rounds = state.rounds ?? Object.freeze([]);\n  async function save(entry: LoopRoundRecord): Promise<void> {\n    rounds = Object.freeze([\n      ...rounds.filter((value) => value.round !== entry.round),\n      Object.freeze(entry),\n    ]);\n    state.rounds = rounds;\n    runtime.emit({\n      type: \"loop\",\n      key: item.key,\n      attempt: state.attempts,\n      round: entry.round,\n      phase: entry.phase,\n    });\n    await runtime.persist();\n  }\n  while (true) {\n    runtime.signal.throwIfAborted();\n    const last = rounds.at(-1);\n    if (last?.check?.done)\n      return last.output?.kind === \"json\" ? last.output.value : undefined;\n    if (last?.phase === \"complete\" && last.round === definition.maxRounds)\n      throw new LoopTaskExhausted(\n        item.key,\n        definition.maxRounds,\n        last.check?.done === false ? last.check.feedback : \"\",\n      );\n    const entry: LoopRoundRecord =\n      last && last.phase !== \"complete\"\n        ? last\n        : { round: rounds.length + 1, phase: \"attempt\" };\n    runtime.accounting.admit();\n    state.attempts++;\n    runtime.emit({ type: \"attempt\", key: item.key, attempt: state.attempts });\n    await save(entry);\n    const deadline = new AbortController();\n    const timer =\n      item.timeoutMs === undefined\n        ? undefined\n        : setTimeout(\n            () => deadline.abort(new Error(`${item.key} timed out`)),\n            item.timeoutMs,\n          );\n    const signal = AbortSignal.any([runtime.signal, deadline.signal]);\n    const base = runtime.context(item, state.attempts, signal);\n    const context = (phase: LoopTaskContext[\"phase\"]): LoopTaskContext => ({\n      ...base,\n      round: entry.round,\n      phase,\n      idempotencyKey: `${base.idempotencyKey}:round:${entry.round}:${phase}`,\n    });\n    try {\n      signal.throwIfAborted();\n      let result: unknown =\n        entry.output?.kind === \"json\"\n          ? structuredClone(entry.output.value)\n          : undefined;\n      if (entry.phase === \"attempt\") {\n        const previous = rounds.at(-2)?.check;\n        result = await definition.attempt(\n          context(\"attempt\"),\n          previous?.done === false ? previous.feedback : undefined,\n        );\n        signal.throwIfAborted();\n        const output = runtime.options.checkpoint\n          ? checkpointValue(result)\n          : undefined;\n        await save({\n          round: entry.round,\n          phase: \"check\",\n          ...(output ? { output } : {}),\n        });\n      }\n      signal.throwIfAborted();\n      const checked = await definition.check(context(\"check\"), result);\n      signal.throwIfAborted();\n      validateLoopCheck(checked);\n      const check = Object.freeze(\n        checked.done\n          ? { done: true as const }\n          : { done: false as const, feedback: checked.feedback },\n      );\n      await save({\n        ...rounds.at(-1)!,\n        phase: \"complete\",\n        check,\n        ...(runtime.options.checkpoint\n          ? { output: checkpointValue(result) }\n          : {}),\n      });\n      signal.throwIfAborted();\n      if (check.done) return result;\n    } finally {\n      runtime.closeAttempt(item);\n      clearTimeout(timer);\n    }\n  }\n}\n"]}

package/dist/domain/workflow/loop-task.d.ts

@@ -0,0 +1,10 @@
+import type { Task } from "../workflow.types.ts";
+import type { LoopDefinition, LoopTaskOptions } from "./loop-task.types.ts";
+export declare class LoopTaskExhausted extends Error {
+    readonly key: string;
+    readonly maxRounds: number;
+    readonly feedback: string;
+    constructor(key: string, maxRounds: number, feedback: string);
+}
+export declare function loopTask<T>(options: LoopTaskOptions<T>): Task<T>;
+export declare function loopDefinition(item: Task): LoopDefinition | undefined;

package/dist/domain/workflow/loop-task.js

@@ -0,0 +1,39 @@
+import { task } from "./task.js";
+const definitions = new WeakMap();
+export class LoopTaskExhausted extends Error {
+    key;
+    maxRounds;
+    feedback;
+    constructor(key, maxRounds, feedback) {
+        super(`Loop task ${key} exhausted its ${maxRounds} rounds`);
+        this.name = "LoopTaskExhausted";
+        this.key = key;
+        this.maxRounds = maxRounds;
+        this.feedback = feedback;
+    }
+}
+export function loopTask(options) {
+    if (!Number.isSafeInteger(options.maxRounds) || options.maxRounds < 1)
+        throw new Error("maxRounds must be a positive safe integer");
+    if (typeof options.attempt !== "function" ||
+        typeof options.check !== "function")
+        throw new Error("loopTask requires attempt and check callbacks");
+    const { maxRounds, attempt, check, ...base } = options;
+    const item = task({
+        ...base,
+        perform() {
+            throw new Error("loopTask must be executed by a workflow");
+        },
+    });
+    definitions.set(item, Object.freeze({
+        maxRounds,
+        attempt,
+        // The task's paired callbacks share T; checkpoint versions bind restored outputs to that contract.
+        check: (context, result) => check(context, result),
+    }));
+    return item;
+}
+export function loopDefinition(item) {
+    return definitions.get(item);
+}
+//# sourceMappingURL=loop-task.js.map

package/dist/domain/workflow/loop-task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-task.js","sourceRoot":"","sources":["../../../src/domain/workflow/loop-task.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAIjC,MAAM,WAAW,GAAG,IAAI,OAAO,EAAwB,CAAC;AAExD,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,GAAG,CAAS;IACZ,SAAS,CAAS;IAClB,QAAQ,CAAS;IAE1B,YAAY,GAAW,EAAE,SAAiB,EAAE,QAAgB;QAC1D,KAAK,CAAC,aAAa,GAAG,kBAAkB,SAAS,SAAS,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,UAAU,QAAQ,CAAI,OAA2B;IACrD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,SAAS,GAAG,CAAC;QACnE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,IACE,OAAO,OAAO,CAAC,OAAO,KAAK,UAAU;QACrC,OAAO,OAAO,CAAC,KAAK,KAAK,UAAU;QAEnC,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IACvD,MAAM,IAAI,GAAG,IAAI,CAAI;QACnB,GAAG,IAAI;QACP,OAAO;YACL,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QAC7D,CAAC;KACF,CAAC,CAAC;IACH,WAAW,CAAC,GAAG,CACb,IAAI,EACJ,MAAM,CAAC,MAAM,CAAiB;QAC5B,SAAS;QACT,OAAO;QACP,mGAAmG;QACnG,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,MAAW,CAAC;KACxD,CAAC,CACH,CAAC;IACF,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAU;IACvC,OAAO,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC","sourcesContent":["import { task } from \"./task.ts\";\nimport type { Task } from \"../workflow.types.ts\";\nimport type { LoopDefinition, LoopTaskOptions } from \"./loop-task.types.ts\";\n\nconst definitions = new WeakMap<Task, LoopDefinition>();\n\nexport class LoopTaskExhausted extends Error {\n  readonly key: string;\n  readonly maxRounds: number;\n  readonly feedback: string;\n\n  constructor(key: string, maxRounds: number, feedback: string) {\n    super(`Loop task ${key} exhausted its ${maxRounds} rounds`);\n    this.name = \"LoopTaskExhausted\";\n    this.key = key;\n    this.maxRounds = maxRounds;\n    this.feedback = feedback;\n  }\n}\n\nexport function loopTask<T>(options: LoopTaskOptions<T>): Task<T> {\n  if (!Number.isSafeInteger(options.maxRounds) || options.maxRounds < 1)\n    throw new Error(\"maxRounds must be a positive safe integer\");\n  if (\n    typeof options.attempt !== \"function\" ||\n    typeof options.check !== \"function\"\n  )\n    throw new Error(\"loopTask requires attempt and check callbacks\");\n  const { maxRounds, attempt, check, ...base } = options;\n  const item = task<T>({\n    ...base,\n    perform() {\n      throw new Error(\"loopTask must be executed by a workflow\");\n    },\n  });\n  definitions.set(\n    item,\n    Object.freeze<LoopDefinition>({\n      maxRounds,\n      attempt,\n      // The task's paired callbacks share T; checkpoint versions bind restored outputs to that contract.\n      check: (context, result) => check(context, result as T),\n    }),\n  );\n  return item;\n}\n\nexport function loopDefinition(item: Task): LoopDefinition | undefined {\n  return definitions.get(item);\n}\n"]}

package/dist/domain/workflow/loop-task.types.d.ts

@@ -0,0 +1,28 @@
+import type { TaskContext, TaskOptions } from "../workflow.types.ts";
+import type { WorkflowCheckpointValue } from "./checkpoint.types.ts";
+export type LoopCheckResult = {
+    readonly done: true;
+} | {
+    readonly done: false;
+    readonly feedback: string;
+};
+export interface LoopTaskContext extends TaskContext {
+    readonly round: number;
+    readonly phase: "attempt" | "check";
+}
+export interface LoopTaskOptions<T> extends Pick<TaskOptions<T>, "key" | "after" | "condition" | "timeoutMs" | "cache"> {
+    readonly maxRounds: number;
+    readonly attempt: (context: LoopTaskContext, feedback: string | undefined) => T | Promise<T>;
+    readonly check: (context: LoopTaskContext, result: T) => LoopCheckResult | Promise<LoopCheckResult>;
+}
+export interface LoopRoundRecord {
+    readonly round: number;
+    readonly phase: "attempt" | "check" | "complete";
+    readonly output?: WorkflowCheckpointValue;
+    readonly check?: LoopCheckResult;
+}
+export interface LoopDefinition {
+    readonly maxRounds: number;
+    readonly attempt: (context: LoopTaskContext, feedback: string | undefined) => unknown | Promise<unknown>;
+    readonly check: (context: LoopTaskContext, result: unknown) => LoopCheckResult | Promise<LoopCheckResult>;
+}

package/dist/domain/workflow/loop-task.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=loop-task.types.js.map

package/dist/domain/workflow/loop-task.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-task.types.js","sourceRoot":"","sources":["../../../src/domain/workflow/loop-task.types.ts"],"names":[],"mappings":"","sourcesContent":["import type { TaskContext, TaskOptions } from \"../workflow.types.ts\";\nimport type { WorkflowCheckpointValue } from \"./checkpoint.types.ts\";\n\nexport type LoopCheckResult =\n  { readonly done: true } | { readonly done: false; readonly feedback: string };\n\nexport interface LoopTaskContext extends TaskContext {\n  readonly round: number;\n  readonly phase: \"attempt\" | \"check\";\n}\n\nexport interface LoopTaskOptions<T> extends Pick<\n  TaskOptions<T>,\n  \"key\" | \"after\" | \"condition\" | \"timeoutMs\" | \"cache\"\n> {\n  readonly maxRounds: number;\n  readonly attempt: (\n    context: LoopTaskContext,\n    feedback: string | undefined,\n  ) => T | Promise<T>;\n  readonly check: (\n    context: LoopTaskContext,\n    result: T,\n  ) => LoopCheckResult | Promise<LoopCheckResult>;\n}\n\nexport interface LoopRoundRecord {\n  readonly round: number;\n  readonly phase: \"attempt\" | \"check\" | \"complete\";\n  readonly output?: WorkflowCheckpointValue;\n  readonly check?: LoopCheckResult;\n}\n\nexport interface LoopDefinition {\n  readonly maxRounds: number;\n  readonly attempt: (\n    context: LoopTaskContext,\n    feedback: string | undefined,\n  ) => unknown | Promise<unknown>;\n  readonly check: (\n    context: LoopTaskContext,\n    result: unknown,\n  ) => LoopCheckResult | Promise<LoopCheckResult>;\n}\n"]}

package/dist/domain/workflow/loop-validation.d.ts

@@ -0,0 +1,4 @@
+import type { Task } from "../workflow.types.ts";
+import type { LoopCheckResult } from "./loop-task.types.ts";
+export declare function validateLoopCheck(value: unknown): asserts value is LoopCheckResult;
+export declare function validateLoopRecord(record: Record<string, unknown>, item: Task): void;

package/dist/domain/workflow/loop-validation.js

@@ -0,0 +1,62 @@
+import { checkpointValue } from "./checkpoint-value.js";
+import { loopDefinition } from "./loop-task.js";
+function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function validateLoopCheck(value) {
+    if (!object(value) ||
+        typeof value.done !== "boolean" ||
+        (!value.done && typeof value.feedback !== "string"))
+        throw new Error("Loop check must return { done: true } or { done: false, feedback: string }");
+}
+export function validateLoopRecord(record, item) {
+    const definition = loopDefinition(item);
+    const invalid = () => new Error("Invalid or incompatible workflow loop checkpoint");
+    if (record.rounds === undefined) {
+        if (definition && (record.attempts !== 0 || record.status === "done"))
+            throw invalid();
+        return;
+    }
+    if (!definition ||
+        !Array.isArray(record.rounds) ||
+        record.rounds.length === 0 ||
+        record.rounds.length > definition.maxRounds ||
+        record.rounds.length > Number(record.attempts))
+        throw invalid();
+    for (const [index, entry] of record.rounds.entries()) {
+        if (!object(entry) ||
+            entry.round !== index + 1 ||
+            !["attempt", "check", "complete"].includes(String(entry.phase)))
+            throw invalid();
+        const final = index === record.rounds.length - 1;
+        if (!final && entry.phase !== "complete")
+            throw invalid();
+        if (entry.phase === "attempt") {
+            if (entry.output !== undefined || entry.check !== undefined)
+                throw invalid();
+            continue;
+        }
+        if (!object(entry.output) ||
+            !["undefined", "json"].includes(String(entry.output.kind)))
+            throw invalid();
+        if (entry.output.kind === "json") {
+            if (!Object.hasOwn(entry.output, "value") ||
+                entry.output.value === undefined)
+                throw invalid();
+            checkpointValue(entry.output.value);
+        }
+        if (entry.phase === "check") {
+            if (entry.check !== undefined)
+                throw invalid();
+            continue;
+        }
+        validateLoopCheck(entry.check);
+        if (entry.check.done && !final)
+            throw invalid();
+    }
+    const last = record.rounds.at(-1);
+    if (record.status === "done" &&
+        (!object(last) || !object(last.check) || last.check.done !== true))
+        throw invalid();
+}
+//# sourceMappingURL=loop-validation.js.map

package/dist/domain/workflow/loop-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-validation.js","sourceRoot":"","sources":["../../../src/domain/workflow/loop-validation.ts"],"names":[],"mappings":"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","sourcesContent":["import { checkpointValue } from \"./checkpoint-value.ts\";\nimport { loopDefinition } from \"./loop-task.ts\";\nimport type { Task } from \"../workflow.types.ts\";\nimport type { LoopCheckResult } from \"./loop-task.types.ts\";\n\nfunction object(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nexport function validateLoopCheck(\n  value: unknown,\n): asserts value is LoopCheckResult {\n  if (\n    !object(value) ||\n    typeof value.done !== \"boolean\" ||\n    (!value.done && typeof value.feedback !== \"string\")\n  )\n    throw new Error(\n      \"Loop check must return { done: true } or { done: false, feedback: string }\",\n    );\n}\n\nexport function validateLoopRecord(\n  record: Record<string, unknown>,\n  item: Task,\n): void {\n  const definition = loopDefinition(item);\n  const invalid = () =>\n    new Error(\"Invalid or incompatible workflow loop checkpoint\");\n  if (record.rounds === undefined) {\n    if (definition && (record.attempts !== 0 || record.status === \"done\"))\n      throw invalid();\n    return;\n  }\n  if (\n    !definition ||\n    !Array.isArray(record.rounds) ||\n    record.rounds.length === 0 ||\n    record.rounds.length > definition.maxRounds ||\n    record.rounds.length > Number(record.attempts)\n  )\n    throw invalid();\n  for (const [index, entry] of record.rounds.entries()) {\n    if (\n      !object(entry) ||\n      entry.round !== index + 1 ||\n      ![\"attempt\", \"check\", \"complete\"].includes(String(entry.phase))\n    )\n      throw invalid();\n    const final = index === record.rounds.length - 1;\n    if (!final && entry.phase !== \"complete\") throw invalid();\n    if (entry.phase === \"attempt\") {\n      if (entry.output !== undefined || entry.check !== undefined)\n        throw invalid();\n      continue;\n    }\n    if (\n      !object(entry.output) ||\n      ![\"undefined\", \"json\"].includes(String(entry.output.kind))\n    )\n      throw invalid();\n    if (entry.output.kind === \"json\") {\n      if (\n        !Object.hasOwn(entry.output, \"value\") ||\n        entry.output.value === undefined\n      )\n        throw invalid();\n      checkpointValue(entry.output.value);\n    }\n    if (entry.phase === \"check\") {\n      if (entry.check !== undefined) throw invalid();\n      continue;\n    }\n    validateLoopCheck(entry.check);\n    if (entry.check.done && !final) throw invalid();\n  }\n  const last: unknown = record.rounds.at(-1);\n  if (\n    record.status === \"done\" &&\n    (!object(last) || !object(last.check) || last.check.done !== true)\n  )\n    throw invalid();\n}\n"]}

package/dist/domain/workflow/quota-pause.d.ts

@@ -0,0 +1,7 @@
+import type { Task, WorkflowExecutionState } from "../workflow.types.ts";
+import type { WorkflowQuotaPolicy } from "./quota-pause.types.ts";
+export declare function validateQuotaPolicy(policy: WorkflowQuotaPolicy): void;
+export declare function quotaResumes(runtime: WorkflowExecutionState): Set<Task>;
+export declare function pauseForQuota(item: Task, runtime: WorkflowExecutionState, error: unknown): Promise<boolean>;
+/** Waits for a paused task's reset when allowed; false leaves the task paused. */
+export declare function awaitQuotaReset(item: Task, runtime: WorkflowExecutionState, resuming: boolean): Promise<boolean>;

package/dist/domain/workflow/quota-pause.js

@@ -0,0 +1,83 @@
+import { recoveryDetails } from "../errors.js";
+import { quotaFault } from "../quota.js";
+import { waitForRetry } from "./retry.js";
+export function validateQuotaPolicy(policy) {
+    if (policy.action !== "pause")
+        throw new Error("onQuota.action must be pause");
+    const wait = policy.maxWaitMs;
+    if (wait !== undefined && (!Number.isSafeInteger(wait) || wait < 0))
+        throw new Error("onQuota.maxWaitMs must be a nonnegative safe integer");
+}
+/** Milliseconds before a paused task may run again, or undefined to stay paused. */
+function resumeDelay(pause, maxWaitMs, now) {
+    if (pause.resetAt === undefined)
+        return 0;
+    const delay = Math.max(0, Date.parse(pause.resetAt) - now);
+    return delay <= maxWaitMs ? delay : undefined;
+}
+export function quotaResumes(runtime) {
+    const maxWaitMs = runtime.options.onQuota?.maxWaitMs ?? 0;
+    const now = Date.now();
+    const resumes = new Set();
+    for (const [item, record] of runtime.records)
+        if (record.status === "paused" &&
+            record.quota &&
+            resumeDelay(record.quota, maxWaitMs, now) !== undefined)
+            resumes.add(item);
+    return resumes;
+}
+export async function pauseForQuota(item, runtime, error) {
+    const fault = runtime.options.onQuota ? quotaFault(error) : undefined;
+    if (!fault || runtime.signal.aborted)
+        return false;
+    const state = runtime.record(item);
+    const recovery = recoveryDetails(error);
+    const captured = typeof recovery?.transcript === "string" ||
+        (fault.conversation !== undefined &&
+            recovery?.conversation === fault.conversation);
+    state.quota = Object.freeze({
+        requestedAt: new Date().toISOString(),
+        message: fault.message,
+        ...(fault.resetAt === undefined ? {} : { resetAt: fault.resetAt }),
+        ...(captured && fault.conversation
+            ? { conversation: fault.conversation }
+            : {}),
+        ...(typeof recovery?.branch === "string" && recovery.branch
+            ? { branch: recovery.branch }
+            : {}),
+    });
+    runtime.finish(item, "paused");
+    await runtime.persist();
+    return true;
+}
+/** Waits for a paused task's reset when allowed; false leaves the task paused. */
+export async function awaitQuotaReset(item, runtime, resuming) {
+    const state = runtime.record(item);
+    const pause = state.quota;
+    const maxWaitMs = runtime.options.onQuota?.maxWaitMs ?? 0;
+    const now = Date.now();
+    const future = pause.resetAt !== undefined && Date.parse(pause.resetAt) > now;
+    const delay = resuming || future ? resumeDelay(pause, maxWaitMs, now) : undefined;
+    runtime.emit({
+        type: "quota",
+        key: item.key,
+        attempt: state.attempts,
+        status: delay === undefined ? "paused" : "waiting",
+        ...(pause.resetAt === undefined ? {} : { resetAt: pause.resetAt }),
+        ...(delay ? { delayMs: delay } : {}),
+    });
+    if (delay === undefined)
+        return false;
+    try {
+        await waitForRetry(delay, runtime.signal);
+    }
+    catch (error) {
+        if (runtime.signal.aborted)
+            return false;
+        throw error;
+    }
+    runtime.quotaResumes.set(item, pause);
+    delete state.quota;
+    return true;
+}
+//# sourceMappingURL=quota-pause.js.map

package/dist/domain/workflow/quota-pause.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-pause.js","sourceRoot":"","sources":["../../../src/domain/workflow/quota-pause.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAO1C,MAAM,UAAU,mBAAmB,CAAC,MAA2B;IAC7D,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO;QAC3B,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC;IAC9B,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;AAC5E,CAAC;AAED,oFAAoF;AACpF,SAAS,WAAW,CAClB,KAAyB,EACzB,SAAiB,EACjB,GAAW;IAEX,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC;IAC3D,OAAO,KAAK,IAAI,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAA+B;IAC1D,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,IAAI,CAAC,CAAC;IAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAQ,CAAC;IAChC,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO;QAC1C,IACE,MAAM,CAAC,MAAM,KAAK,QAAQ;YAC1B,MAAM,CAAC,KAAK;YACZ,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,CAAC,KAAK,SAAS;YAEvD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAU,EACV,OAA+B,EAC/B,KAAc;IAEd,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACtE,IAAI,CAAC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IACnD,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACxC,MAAM,QAAQ,GACZ,OAAO,QAAQ,EAAE,UAAU,KAAK,QAAQ;QACxC,CAAC,KAAK,CAAC,YAAY,KAAK,SAAS;YAC/B,QAAQ,EAAE,YAAY,KAAK,KAAK,CAAC,YAAY,CAAC,CAAC;IACnD,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC;QAC1B,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACrC,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;QAClE,GAAG,CAAC,QAAQ,IAAI,KAAK,CAAC,YAAY;YAChC,CAAC,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE;YACtC,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,OAAO,QAAQ,EAAE,MAAM,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM;YACzD,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE;YAC7B,CAAC,CAAC,EAAE,CAAC;KACR,CAAC,CAAC;IACH,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC/B,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;IACxB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,kFAAkF;AAClF,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAU,EACV,OAA+B,EAC/B,QAAiB;IAEjB,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAM,CAAC;IAC3B,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,IAAI,CAAC,CAAC;IAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,GAAG,CAAC;IAC9E,MAAM,KAAK,GACT,QAAQ,IAAI,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACtE,OAAO,CAAC,IAAI,CAAC;QACX,IAAI,EAAE,OAAO;QACb,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,OAAO,EAAE,KAAK,CAAC,QAAQ;QACvB,MAAM,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;QAClD,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;QAClE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACrC,CAAC,CAAC;IACH,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,IAAI,CAAC;QACH,MAAM,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,OAAO,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QACzC,MAAM,KAAK,CAAC;IACd,CAAC;IACD,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACtC,OAAO,KAAK,CAAC,KAAK,CAAC;IACnB,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["import { recoveryDetails } from \"../errors.ts\";\nimport { quotaFault } from \"../quota.ts\";\nimport { waitForRetry } from \"./retry.ts\";\nimport type { Task, WorkflowExecutionState } from \"../workflow.types.ts\";\nimport type {\n  WorkflowQuotaPause,\n  WorkflowQuotaPolicy,\n} from \"./quota-pause.types.ts\";\n\nexport function validateQuotaPolicy(policy: WorkflowQuotaPolicy): void {\n  if (policy.action !== \"pause\")\n    throw new Error(\"onQuota.action must be pause\");\n  const wait = policy.maxWaitMs;\n  if (wait !== undefined && (!Number.isSafeInteger(wait) || wait < 0))\n    throw new Error(\"onQuota.maxWaitMs must be a nonnegative safe integer\");\n}\n\n/** Milliseconds before a paused task may run again, or undefined to stay paused. */\nfunction resumeDelay(\n  pause: WorkflowQuotaPause,\n  maxWaitMs: number,\n  now: number,\n): number | undefined {\n  if (pause.resetAt === undefined) return 0;\n  const delay = Math.max(0, Date.parse(pause.resetAt) - now);\n  return delay <= maxWaitMs ? delay : undefined;\n}\n\nexport function quotaResumes(runtime: WorkflowExecutionState): Set<Task> {\n  const maxWaitMs = runtime.options.onQuota?.maxWaitMs ?? 0;\n  const now = Date.now();\n  const resumes = new Set<Task>();\n  for (const [item, record] of runtime.records)\n    if (\n      record.status === \"paused\" &&\n      record.quota &&\n      resumeDelay(record.quota, maxWaitMs, now) !== undefined\n    )\n      resumes.add(item);\n  return resumes;\n}\n\nexport async function pauseForQuota(\n  item: Task,\n  runtime: WorkflowExecutionState,\n  error: unknown,\n): Promise<boolean> {\n  const fault = runtime.options.onQuota ? quotaFault(error) : undefined;\n  if (!fault || runtime.signal.aborted) return false;\n  const state = runtime.record(item);\n  const recovery = recoveryDetails(error);\n  const captured =\n    typeof recovery?.transcript === \"string\" ||\n    (fault.conversation !== undefined &&\n      recovery?.conversation === fault.conversation);\n  state.quota = Object.freeze({\n    requestedAt: new Date().toISOString(),\n    message: fault.message,\n    ...(fault.resetAt === undefined ? {} : { resetAt: fault.resetAt }),\n    ...(captured && fault.conversation\n      ? { conversation: fault.conversation }\n      : {}),\n    ...(typeof recovery?.branch === \"string\" && recovery.branch\n      ? { branch: recovery.branch }\n      : {}),\n  });\n  runtime.finish(item, \"paused\");\n  await runtime.persist();\n  return true;\n}\n\n/** Waits for a paused task's reset when allowed; false leaves the task paused. */\nexport async function awaitQuotaReset(\n  item: Task,\n  runtime: WorkflowExecutionState,\n  resuming: boolean,\n): Promise<boolean> {\n  const state = runtime.record(item);\n  const pause = state.quota!;\n  const maxWaitMs = runtime.options.onQuota?.maxWaitMs ?? 0;\n  const now = Date.now();\n  const future = pause.resetAt !== undefined && Date.parse(pause.resetAt) > now;\n  const delay =\n    resuming || future ? resumeDelay(pause, maxWaitMs, now) : undefined;\n  runtime.emit({\n    type: \"quota\",\n    key: item.key,\n    attempt: state.attempts,\n    status: delay === undefined ? \"paused\" : \"waiting\",\n    ...(pause.resetAt === undefined ? {} : { resetAt: pause.resetAt }),\n    ...(delay ? { delayMs: delay } : {}),\n  });\n  if (delay === undefined) return false;\n  try {\n    await waitForRetry(delay, runtime.signal);\n  } catch (error) {\n    if (runtime.signal.aborted) return false;\n    throw error;\n  }\n  runtime.quotaResumes.set(item, pause);\n  delete state.quota;\n  return true;\n}\n"]}

package/dist/domain/workflow/quota-pause.types.d.ts

@@ -0,0 +1,14 @@
+export interface WorkflowQuotaPolicy {
+    readonly action: "pause";
+    /** Longest in-process wait for a known reset; later resets pause durably. */
+    readonly maxWaitMs?: number;
+}
+export interface WorkflowQuotaPause {
+    readonly requestedAt: string;
+    readonly message: string;
+    readonly resetAt?: string;
+    /** Captured conversation of the interrupted attempt, portable to a new sandbox. */
+    readonly conversation?: string;
+    /** Retained work branch of the interrupted attempt. */
+    readonly branch?: string;
+}

package/dist/domain/workflow/quota-pause.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=quota-pause.types.js.map

package/dist/domain/workflow/quota-pause.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-pause.types.js","sourceRoot":"","sources":["../../../src/domain/workflow/quota-pause.types.ts"],"names":[],"mappings":"","sourcesContent":["export interface WorkflowQuotaPolicy {\n  readonly action: \"pause\";\n  /** Longest in-process wait for a known reset; later resets pause durably. */\n  readonly maxWaitMs?: number;\n}\n\nexport interface WorkflowQuotaPause {\n  readonly requestedAt: string;\n  readonly message: string;\n  readonly resetAt?: string;\n  /** Captured conversation of the interrupted attempt, portable to a new sandbox. */\n  readonly conversation?: string;\n  /** Retained work branch of the interrupted attempt. */\n  readonly branch?: string;\n}\n"]}

package/dist/domain/workflow/quota-validation.d.ts

@@ -0,0 +1,2 @@
+import type { Task } from "../workflow.types.ts";
+export declare function validateQuotaRecord(record: Record<string, unknown>, item: Task): void;

package/dist/domain/workflow/quota-validation.js

@@ -0,0 +1,30 @@
+function timestamp(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+export function validateQuotaRecord(record, item) {
+    const pause = record.quota;
+    if (pause === undefined)
+        return;
+    const invalid = () => new Error("Invalid workflow checkpoint quota record");
+    if (item.gate ||
+        record.status !== "paused" ||
+        record.attempts === 0 ||
+        pause === null ||
+        typeof pause !== "object" ||
+        Array.isArray(pause))
+        throw invalid();
+    const fields = pause;
+    if (Object.keys(fields).some((key) => ![
+        "requestedAt",
+        "message",
+        "resetAt",
+        "conversation",
+        "branch",
+    ].includes(key)) ||
+        !timestamp(fields.requestedAt) ||
+        typeof fields.message !== "string" ||
+        (fields.resetAt !== undefined && !timestamp(fields.resetAt)) ||
+        [fields.conversation, fields.branch].some((value) => value !== undefined && (typeof value !== "string" || !value)))
+        throw invalid();
+}
+//# sourceMappingURL=quota-validation.js.map

package/dist/domain/workflow/quota-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-validation.js","sourceRoot":"","sources":["../../../src/domain/workflow/quota-validation.ts"],"names":[],"mappings":"AAEA,SAAS,SAAS,CAAC,KAAc;IAC/B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,MAA+B,EAC/B,IAAU;IAEV,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC3B,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO;IAChC,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC5E,IACE,IAAI,CAAC,IAAI;QACT,MAAM,CAAC,MAAM,KAAK,QAAQ;QAC1B,MAAM,CAAC,QAAQ,KAAK,CAAC;QACrB,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAEpB,MAAM,OAAO,EAAE,CAAC;IAClB,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,IACE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CACtB,CAAC,GAAG,EAAE,EAAE,CACN,CAAC;QACC,aAAa;QACb,SAAS;QACT,SAAS;QACT,cAAc;QACd,QAAQ;KACT,CAAC,QAAQ,CAAC,GAAG,CAAC,CAClB;QACD,CAAC,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC;QAC9B,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;QAClC,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC5D,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CACvC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,CACxE;QAED,MAAM,OAAO,EAAE,CAAC;AACpB,CAAC","sourcesContent":["import type { Task } from \"../workflow.types.ts\";\n\nfunction timestamp(value: unknown): boolean {\n  return typeof value === \"string\" && Number.isFinite(Date.parse(value));\n}\n\nexport function validateQuotaRecord(\n  record: Record<string, unknown>,\n  item: Task,\n): void {\n  const pause = record.quota;\n  if (pause === undefined) return;\n  const invalid = () => new Error(\"Invalid workflow checkpoint quota record\");\n  if (\n    item.gate ||\n    record.status !== \"paused\" ||\n    record.attempts === 0 ||\n    pause === null ||\n    typeof pause !== \"object\" ||\n    Array.isArray(pause)\n  )\n    throw invalid();\n  const fields = pause as Record<string, unknown>;\n  if (\n    Object.keys(fields).some(\n      (key) =>\n        ![\n          \"requestedAt\",\n          \"message\",\n          \"resetAt\",\n          \"conversation\",\n          \"branch\",\n        ].includes(key),\n    ) ||\n    !timestamp(fields.requestedAt) ||\n    typeof fields.message !== \"string\" ||\n    (fields.resetAt !== undefined && !timestamp(fields.resetAt)) ||\n    [fields.conversation, fields.branch].some(\n      (value) => value !== undefined && (typeof value !== \"string\" || !value),\n    )\n  )\n    throw invalid();\n}\n"]}

package/dist/domain/workflow/task-cache-entry.d.ts

@@ -0,0 +1,3 @@
+import type { TaskCacheEntry } from "./task-cache.types.ts";
+export declare function taskCacheFingerprint(workflow: string, task: string, version: string, key: unknown): string;
+export declare function validateTaskCacheEntry(value: unknown, fingerprint: string): asserts value is TaskCacheEntry;

package/dist/domain/workflow/task-cache-entry.js

@@ -0,0 +1,57 @@
+import { createHash } from "node:crypto";
+import { checkpointValue } from "./checkpoint-value.js";
+import { taskCacheFormat } from "./task-cache.constants.js";
+function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+    const fields = Object.entries(value);
+    return `{${fields
+        .sort(([left], [right]) => (left < right ? -1 : 1))
+        .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`)
+        .join(",")}}`;
+}
+export function taskCacheFingerprint(workflow, task, version, key) {
+    let parts;
+    try {
+        parts = checkpointValue(key);
+    }
+    catch {
+        throw new Error("Task cache key must be a lossless JSON value");
+    }
+    if (parts.kind !== "json")
+        throw new Error("Task cache key must be a lossless JSON value");
+    return createHash("sha256")
+        .update(canonicalJson({
+        format: taskCacheFormat,
+        workflow,
+        task,
+        version,
+        key: parts.value,
+    }))
+        .digest("hex");
+}
+export function validateTaskCacheEntry(value, fingerprint) {
+    const invalid = () => new Error("Invalid task cache entry");
+    if (!object(value) ||
+        value.format !== taskCacheFormat ||
+        value.fingerprint !== fingerprint ||
+        typeof value.workflow !== "string" ||
+        typeof value.task !== "string" ||
+        typeof value.version !== "string" ||
+        typeof value.createdAt !== "string" ||
+        !Number.isFinite(Date.parse(value.createdAt)) ||
+        !object(value.value))
+        throw invalid();
+    const output = value.value;
+    if (output.kind === "undefined" && !Object.hasOwn(output, "value"))
+        return;
+    if (output.kind !== "json" || output.value === undefined)
+        throw invalid();
+    checkpointValue(output.value);
+}
+//# sourceMappingURL=task-cache-entry.js.map

package/dist/domain/workflow/task-cache-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-cache-entry.js","sourceRoot":"","sources":["../../../src/domain/workflow/task-cache-entry.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { checkpointValue } from \"./checkpoint-value.ts\";\nimport { taskCacheFormat } from \"./task-cache.constants.ts\";\nimport type { WorkflowJson } from \"./checkpoint.types.ts\";\nimport type { TaskCacheEntry } from \"./task-cache.types.ts\";\n\nfunction object(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction canonicalJson(value: WorkflowJson): string {\n  if (value === null || typeof value !== \"object\") return JSON.stringify(value);\n  if (Array.isArray(value))\n    return `[${value.map((item: WorkflowJson) => canonicalJson(item)).join(\",\")}]`;\n  const fields = Object.entries(value as Record<string, WorkflowJson>);\n  return `{${fields\n    .sort(([left], [right]) => (left < right ? -1 : 1))\n    .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`)\n    .join(\",\")}}`;\n}\n\nexport function taskCacheFingerprint(\n  workflow: string,\n  task: string,\n  version: string,\n  key: unknown,\n): string {\n  let parts;\n  try {\n    parts = checkpointValue(key);\n  } catch {\n    throw new Error(\"Task cache key must be a lossless JSON value\");\n  }\n  if (parts.kind !== \"json\")\n    throw new Error(\"Task cache key must be a lossless JSON value\");\n  return createHash(\"sha256\")\n    .update(\n      canonicalJson({\n        format: taskCacheFormat,\n        workflow,\n        task,\n        version,\n        key: parts.value,\n      }),\n    )\n    .digest(\"hex\");\n}\n\nexport function validateTaskCacheEntry(\n  value: unknown,\n  fingerprint: string,\n): asserts value is TaskCacheEntry {\n  const invalid = () => new Error(\"Invalid task cache entry\");\n  if (\n    !object(value) ||\n    value.format !== taskCacheFormat ||\n    value.fingerprint !== fingerprint ||\n    typeof value.workflow !== \"string\" ||\n    typeof value.task !== \"string\" ||\n    typeof value.version !== \"string\" ||\n    typeof value.createdAt !== \"string\" ||\n    !Number.isFinite(Date.parse(value.createdAt)) ||\n    !object(value.value)\n  )\n    throw invalid();\n  const output = value.value;\n  if (output.kind === \"undefined\" && !Object.hasOwn(output, \"value\")) return;\n  if (output.kind !== \"json\" || output.value === undefined) throw invalid();\n  checkpointValue(output.value);\n}\n"]}

package/dist/domain/workflow/task-cache.constants.d.ts

@@ -0,0 +1,3 @@
+import type { TaskCacheMode } from "./task-cache.types.ts";
+export declare const taskCacheFormat = 1;
+export declare const taskCacheModes: readonly TaskCacheMode[];

package/dist/domain/workflow/task-cache.constants.js

@@ -0,0 +1,3 @@
+export const taskCacheFormat = 1;
+export const taskCacheModes = ["reuse", "refresh"];
+//# sourceMappingURL=task-cache.constants.js.map

package/dist/domain/workflow/task-cache.constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-cache.constants.js","sourceRoot":"","sources":["../../../src/domain/workflow/task-cache.constants.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AACjC,MAAM,CAAC,MAAM,cAAc,GAA6B,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC","sourcesContent":["import type { TaskCacheMode } from \"./task-cache.types.ts\";\n\nexport const taskCacheFormat = 1;\nexport const taskCacheModes: readonly TaskCacheMode[] = [\"reuse\", \"refresh\"];\n"]}

package/dist/domain/workflow/task-cache.d.ts

@@ -0,0 +1,6 @@
+import type { Task, WorkflowExecutionState } from "../workflow.types.ts";
+import type { TaskCacheLookup, TaskCacheOptions } from "./task-cache.types.ts";
+export declare function validateTaskCache(options: TaskCacheOptions): void;
+/** Key errors fail the task; store and entry errors only degrade to a miss. */
+export declare function lookupTaskCache(item: Task, cache: TaskCacheOptions, runtime: WorkflowExecutionState): Promise<TaskCacheLookup>;
+export declare function storeTaskCache(item: Task, cache: TaskCacheOptions, runtime: WorkflowExecutionState, fingerprint: string, value: unknown): Promise<void>;

package/dist/domain/workflow/task-cache.js

@@ -0,0 +1,92 @@
+import { checkpointValue } from "./checkpoint-value.js";
+import { taskCacheFormat, taskCacheModes } from "./task-cache.constants.js";
+import { taskCacheFingerprint, validateTaskCacheEntry, } from "./task-cache-entry.js";
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function notify(item, runtime, cache, error) {
+    runtime.emit({
+        type: "cache",
+        key: item.key,
+        cache,
+        ...(error === undefined ? {} : { error: message(error) }),
+    });
+}
+export function validateTaskCache(options) {
+    if (!options ||
+        typeof options !== "object" ||
+        typeof options.store?.read !== "function" ||
+        typeof options.store.write !== "function" ||
+        typeof options.key !== "function")
+        throw new Error("Task cache requires a store and a key function");
+    if (typeof options.version !== "string" || !options.version.trim())
+        throw new Error("Task cache version must not be empty");
+    if (options.maxAgeMs !== undefined &&
+        (!Number.isSafeInteger(options.maxAgeMs) || options.maxAgeMs < 1))
+        throw new Error("cache.maxAgeMs must be a positive integer");
+    if (options.mode !== undefined && !taskCacheModes.includes(options.mode))
+        throw new Error("cache.mode must be reuse or refresh");
+}
+/** Key errors fail the task; store and entry errors only degrade to a miss. */
+export async function lookupTaskCache(item, cache, runtime) {
+    const { signal } = runtime;
+    const key = await cache.key(runtime.context(item, 0, signal));
+    signal.throwIfAborted();
+    const fingerprint = taskCacheFingerprint(runtime.workflow, item.key, cache.version, key);
+    if (cache.mode === "refresh") {
+        notify(item, runtime, "miss");
+        return { hit: false, fingerprint };
+    }
+    try {
+        const entry = await cache.store.read(fingerprint, { signal });
+        signal.throwIfAborted();
+        if (entry === undefined) {
+            notify(item, runtime, "miss");
+            return { hit: false, fingerprint };
+        }
+        validateTaskCacheEntry(entry, fingerprint);
+        if (cache.maxAgeMs !== undefined &&
+            Date.now() - Date.parse(entry.createdAt) > cache.maxAgeMs) {
+            notify(item, runtime, "miss");
+            return { hit: false, fingerprint };
+        }
+        notify(item, runtime, "hit");
+        return {
+            hit: true,
+            value: entry.value.kind === "json"
+                ? structuredClone(entry.value.value)
+                : undefined,
+        };
+    }
+    catch (error) {
+        signal.throwIfAborted();
+        notify(item, runtime, "failed", error);
+        return { hit: false, fingerprint };
+    }
+}
+export async function storeTaskCache(item, cache, runtime, fingerprint, value) {
+    let output;
+    try {
+        output = checkpointValue(value);
+    }
+    catch (error) {
+        throw new Error(`Cached task results must be lossless JSON values or undefined: ${message(error)}`);
+    }
+    try {
+        await cache.store.write(Object.freeze({
+            format: taskCacheFormat,
+            fingerprint,
+            workflow: runtime.workflow,
+            task: item.key,
+            version: cache.version,
+            createdAt: new Date().toISOString(),
+            value: output,
+        }), { signal: runtime.signal });
+        notify(item, runtime, "stored");
+    }
+    catch (error) {
+        runtime.signal.throwIfAborted();
+        notify(item, runtime, "failed", error);
+    }
+}
+//# sourceMappingURL=task-cache.js.map

package/dist/domain/workflow/task-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-cache.js","sourceRoot":"","sources":["../../../src/domain/workflow/task-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC5E,OAAO,EACL,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAQ/B,SAAS,OAAO,CAAC,KAAc;IAC7B,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,MAAM,CACb,IAAU,EACV,OAA+B,EAC/B,KAAuB,EACvB,KAAe;IAEf,OAAO,CAAC,IAAI,CAAC;QACX,IAAI,EAAE,OAAO;QACb,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,KAAK;QACL,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;KAC1D,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAyB;IACzD,IACE,CAAC,OAAO;QACR,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,OAAO,CAAC,KAAK,EAAE,IAAI,KAAK,UAAU;QACzC,OAAO,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,UAAU;QACzC,OAAO,OAAO,CAAC,GAAG,KAAK,UAAU;QAEjC,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE;QAChE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,IACE,OAAO,CAAC,QAAQ,KAAK,SAAS;QAC9B,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QAEjE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;AAC3D,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAU,EACV,KAAuB,EACvB,OAA+B;IAE/B,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAC3B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9D,MAAM,CAAC,cAAc,EAAE,CAAC;IACxB,MAAM,WAAW,GAAG,oBAAoB,CACtC,OAAO,CAAC,QAAQ,EAChB,IAAI,CAAC,GAAG,EACR,KAAK,CAAC,OAAO,EACb,GAAG,CACJ,CAAC;IACF,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAC9B,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IACrC,CAAC;IACD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QAC9D,MAAM,CAAC,cAAc,EAAE,CAAC;QACxB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YAC9B,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;QACrC,CAAC;QACD,sBAAsB,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QAC3C,IACE,KAAK,CAAC,QAAQ,KAAK,SAAS;YAC5B,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC,QAAQ,EACzD,CAAC;YACD,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YAC9B,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;QACrC,CAAC;QACD,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;QAC7B,OAAO;YACL,GAAG,EAAE,IAAI;YACT,KAAK,EACH,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM;gBACzB,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC;gBACpC,CAAC,CAAC,SAAS;SAChB,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,cAAc,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;QACvC,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IACrC,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAU,EACV,KAAuB,EACvB,OAA+B,EAC/B,WAAmB,EACnB,KAAc;IAEd,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,kEAAkE,OAAO,CAAC,KAAK,CAAC,EAAE,CACnF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,KAAK,CAAC,KAAK,CACrB,MAAM,CAAC,MAAM,CAAC;YACZ,MAAM,EAAE,eAAe;YACvB,WAAW;YACX,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,IAAI,EAAE,IAAI,CAAC,GAAG;YACd,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,KAAK,EAAE,MAAM;SACd,CAAC,EACF,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAC3B,CAAC;QACF,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;QAChC,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;AACH,CAAC","sourcesContent":["import { checkpointValue } from \"./checkpoint-value.ts\";\nimport { taskCacheFormat, taskCacheModes } from \"./task-cache.constants.ts\";\nimport {\n  taskCacheFingerprint,\n  validateTaskCacheEntry,\n} from \"./task-cache-entry.ts\";\nimport type { Task, WorkflowExecutionState } from \"../workflow.types.ts\";\nimport type {\n  TaskCacheLookup,\n  TaskCacheOptions,\n  TaskCacheOutcome,\n} from \"./task-cache.types.ts\";\n\nfunction message(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\nfunction notify(\n  item: Task,\n  runtime: WorkflowExecutionState,\n  cache: TaskCacheOutcome,\n  error?: unknown,\n): void {\n  runtime.emit({\n    type: \"cache\",\n    key: item.key,\n    cache,\n    ...(error === undefined ? {} : { error: message(error) }),\n  });\n}\n\nexport function validateTaskCache(options: TaskCacheOptions): void {\n  if (\n    !options ||\n    typeof options !== \"object\" ||\n    typeof options.store?.read !== \"function\" ||\n    typeof options.store.write !== \"function\" ||\n    typeof options.key !== \"function\"\n  )\n    throw new Error(\"Task cache requires a store and a key function\");\n  if (typeof options.version !== \"string\" || !options.version.trim())\n    throw new Error(\"Task cache version must not be empty\");\n  if (\n    options.maxAgeMs !== undefined &&\n    (!Number.isSafeInteger(options.maxAgeMs) || options.maxAgeMs < 1)\n  )\n    throw new Error(\"cache.maxAgeMs must be a positive integer\");\n  if (options.mode !== undefined && !taskCacheModes.includes(options.mode))\n    throw new Error(\"cache.mode must be reuse or refresh\");\n}\n\n/** Key errors fail the task; store and entry errors only degrade to a miss. */\nexport async function lookupTaskCache(\n  item: Task,\n  cache: TaskCacheOptions,\n  runtime: WorkflowExecutionState,\n): Promise<TaskCacheLookup> {\n  const { signal } = runtime;\n  const key = await cache.key(runtime.context(item, 0, signal));\n  signal.throwIfAborted();\n  const fingerprint = taskCacheFingerprint(\n    runtime.workflow,\n    item.key,\n    cache.version,\n    key,\n  );\n  if (cache.mode === \"refresh\") {\n    notify(item, runtime, \"miss\");\n    return { hit: false, fingerprint };\n  }\n  try {\n    const entry = await cache.store.read(fingerprint, { signal });\n    signal.throwIfAborted();\n    if (entry === undefined) {\n      notify(item, runtime, \"miss\");\n      return { hit: false, fingerprint };\n    }\n    validateTaskCacheEntry(entry, fingerprint);\n    if (\n      cache.maxAgeMs !== undefined &&\n      Date.now() - Date.parse(entry.createdAt) > cache.maxAgeMs\n    ) {\n      notify(item, runtime, \"miss\");\n      return { hit: false, fingerprint };\n    }\n    notify(item, runtime, \"hit\");\n    return {\n      hit: true,\n      value:\n        entry.value.kind === \"json\"\n          ? structuredClone(entry.value.value)\n          : undefined,\n    };\n  } catch (error) {\n    signal.throwIfAborted();\n    notify(item, runtime, \"failed\", error);\n    return { hit: false, fingerprint };\n  }\n}\n\nexport async function storeTaskCache(\n  item: Task,\n  cache: TaskCacheOptions,\n  runtime: WorkflowExecutionState,\n  fingerprint: string,\n  value: unknown,\n): Promise<void> {\n  let output;\n  try {\n    output = checkpointValue(value);\n  } catch (error) {\n    throw new Error(\n      `Cached task results must be lossless JSON values or undefined: ${message(error)}`,\n    );\n  }\n  try {\n    await cache.store.write(\n      Object.freeze({\n        format: taskCacheFormat,\n        fingerprint,\n        workflow: runtime.workflow,\n        task: item.key,\n        version: cache.version,\n        createdAt: new Date().toISOString(),\n        value: output,\n      }),\n      { signal: runtime.signal },\n    );\n    notify(item, runtime, \"stored\");\n  } catch (error) {\n    runtime.signal.throwIfAborted();\n    notify(item, runtime, \"failed\", error);\n  }\n}\n"]}

package/dist/domain/workflow/task-cache.types.d.ts

@@ -0,0 +1,35 @@
+import type { TaskContext } from "../workflow.types.ts";
+import type { WorkflowCheckpointValue, WorkflowJson } from "./checkpoint.types.ts";
+export type TaskCacheMode = "reuse" | "refresh";
+export type TaskCacheOutcome = "hit" | "miss" | "stored" | "failed";
+export interface TaskCacheEntry {
+    readonly format: 1;
+    readonly fingerprint: string;
+    readonly workflow: string;
+    readonly task: string;
+    readonly version: string;
+    readonly createdAt: string;
+    readonly value: WorkflowCheckpointValue;
+}
+export interface TaskCacheAccessOptions {
+    readonly signal?: AbortSignal;
+}
+export interface TaskCacheStore {
+    read(fingerprint: string, options?: TaskCacheAccessOptions): Promise<TaskCacheEntry | undefined>;
+    write(entry: TaskCacheEntry, options?: TaskCacheAccessOptions): Promise<void>;
+}
+export interface TaskCacheOptions {
+    readonly store: TaskCacheStore;
+    /** Change when the task implementation, agent or output contract changes. */
+    readonly version: string;
+    readonly key: (context: TaskContext) => WorkflowJson | Promise<WorkflowJson>;
+    readonly maxAgeMs?: number;
+    readonly mode?: TaskCacheMode;
+}
+export type TaskCacheLookup = {
+    readonly hit: true;
+    readonly value: unknown;
+} | {
+    readonly hit: false;
+    readonly fingerprint: string;
+};