@lostgradient/weft 0.2.0 → 0.2.1

package/dist/core/context/index.d.ts

@@ -27,6 +27,7 @@ export declare class Context implements WorkflowContext {
     readonly signal: AbortSignal;
     constructor(options: ContextOptions);
     get executionTimeRemaining(): number;
+    get services(): unknown;
     get stepIndex(): number;
     get nestingDepth(): number;
     get accumulatedResults(): Map<number, unknown>;

package/dist/core/context/index.js

@@ -37,6 +37,9 @@ export class Context {
       return 1 / 0;
     return Math.max(0, internals.deadline - internals.getNow());
   }
+  get services() {
+    return getInternals(this).services;
+  }
   get stepIndex() {
     return getInternals(this).stepIndex;
   }

package/dist/core/context/internals.d.ts

@@ -25,6 +25,7 @@ export interface ContextInternals {
     executionStateOwnerId: string;
     resolveWorkflowType: ((target: string | Function) => string) | undefined;
     registerCancelHandler: ((handler: () => Promise<void> | void) => () => void) | undefined;
+    services: unknown;
 }
 export declare function initializeInternals(context: Context, options: ContextOptions, initialSessionState: Record<string, unknown> | undefined): void;
 export declare function getInternals(context: Context): ContextInternals;

package/dist/core/context/internals.js

@@ -24,7 +24,8 @@ export function initializeInternals(context, options, initialSessionState) {
     nestingDepth: options.nestingDepth ?? 0,
     executionStateOwnerId: options.executionStateOwnerId ?? options.workflowId,
     resolveWorkflowType: options.resolveWorkflowType,
-    registerCancelHandler: options.registerCancelHandler
+    registerCancelHandler: options.registerCancelHandler,
+    services: options.services
   };
   INTERNALS.set(context, internals);
 }

package/dist/core/context/speculative-child.js

@@ -16,6 +16,8 @@ function assignOptionalContextOptions(options, internals) {
     options.sleepReferenceTime = internals.sleepReferenceTime;
   if (internals.resolveWorkflowType !== void 0)
     options.resolveWorkflowType = internals.resolveWorkflowType;
+  if (internals.services !== void 0)
+    options.services = internals.services;
 }
 function createSpeculativeChildOptions(parent, internals) {
   const options = {

package/dist/core/context/types.d.ts

@@ -178,4 +178,10 @@ export interface ContextOptions {
      * it is not persisted or restored after engine restart.
      */
     registerCancelHandler?: (handler: () => Promise<void> | void) => () => void;
+    /**
+     * Host-supplied, per-run capabilities exposed as `ctx.services`. Never
+     * checkpointed; held only for this run and re-provided on recovery via the
+     * engine's `resolveWorkflowServices` resolver.
+     */
+    services?: unknown;
 }

package/dist/core/engine/bulk-operations-purge.js

@@ -178,6 +178,7 @@ function buildBaseWorkflowDeleteKeys(state) {
     KEYS.checkpoint(state.id),
     KEYS.workflowHeaders(state.id),
     KEYS.terminalCleanupNeeded(state.id),
+    KEYS.workflowHasServices(state.id),
     KEYS.attribute(state.id),
     KEYS.terminalWorkflow(state.updatedAt, state.id)
   ]);

package/dist/core/engine/callback-creators-bundles.js

@@ -102,7 +102,8 @@ export function createTimeOperationCallbacks(engine) {
     parseStartOptionDuration: (value, fieldName) => parseStartOptionDuration(getInternals(engine), value, fieldName, createLifecycleCallbacks(engine)),
     runDeferredTerminalCleanup: (workflowId, timerId) => runDeferredTerminalCleanup(getInternals(engine), workflowId, timerId, createTerminationCallbacks(engine)),
     handleScheduleTimer: (entry) => handleScheduleTimerForEngine(engine, entry),
-    timeout: (workflowId) => engine.timeout(workflowId)
+    timeout: (workflowId) => engine.timeout(workflowId),
+    handleCleanupError: (source, error, workflowId) => createTerminationCallbacks(engine).handleCleanupError(source, error, workflowId)
   };
 }
 export function createUpdateCallbacks(engine) {

package/dist/core/engine/callback-creators-core.js

@@ -74,7 +74,8 @@ export function createLifecycleCallbacks(engine) {
     hasLocalCheckpointOwnership: (workflowId, workflowStatus) => hasLocalCheckpointOwnership(getInternals(engine), workflowId, workflowStatus),
     handleCleanupError: (source, error, workflowId) => createTerminationCallbacks(engine).handleCleanupError(source, error, workflowId),
     swallowPromiseRejection: (promise) => swallowPromiseRejection(promise),
-    enforceHistoryCircuitBreaker: (workflowId) => terminateWorkflow(getInternals(engine), workflowId, "timed-out", createTerminationCallbacks(engine), HISTORY_CIRCUIT_BREAKER_REASON)
+    enforceHistoryCircuitBreaker: (workflowId) => terminateWorkflow(getInternals(engine), workflowId, "timed-out", createTerminationCallbacks(engine), HISTORY_CIRCUIT_BREAKER_REASON),
+    failWorkflowForUnavailableServices: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine), "system")
   };
 }
 export function createTerminationCallbacksWith(engine, handleScheduledWorkflowTerminal) {

package/dist/core/engine/construction.d.ts

@@ -54,6 +54,7 @@ export declare function createExecutionStrategyBundle(parameters: {
     getComposedWorkflowInterceptor?: () => ComposedWorkflowInterceptor | null;
     resolveWorkflowType: (target: string | Function) => string;
     registerCancelHandler?: (workflowId: string, handler: () => Promise<void> | void) => () => void;
+    getWorkflowServices?: (workflowId: string) => unknown;
 }): ExecutionStrategyBundle;
 export declare function createActivityWorkerDispatcher(activityExecution: EngineConstructorOptions['activityExecution']): ActivityWorkerDispatcher | null;
 export declare function createAlertManagerForEngine(engine: EventTarget, alerts: EngineOptions['alerts'] | undefined, getNow: () => number): AlertManager | null;

package/dist/core/engine/construction.js

@@ -107,6 +107,7 @@ export function resolveEngineOptions(storage, options, getNow) {
   return {
     storage,
     getNow,
+    resolveWorkflowServices: options?.resolveWorkflowServices ?? null,
     ...resolveBooleanDefaults(options),
     ...resolveNumericDefaults(options),
     ...resolveRetentionFields(options),
@@ -169,7 +170,8 @@ export function createExecutionStrategyBundle(parameters) {
     getRegistration,
     getComposedWorkflowInterceptor,
     resolveWorkflowType,
-    registerCancelHandler
+    registerCancelHandler,
+    getWorkflowServices
   } = parameters, workerExecutionConfiguration = normalizeWorkerExecutionConfiguration(options);
   if (workerExecutionConfiguration.mode === "worker") {
     const pool = new WorkerPool({
@@ -195,7 +197,8 @@ export function createExecutionStrategyBundle(parameters) {
     maxNestingDepth,
     development,
     resolveWorkflowType,
-    ...registerCancelHandler !== void 0 && { registerCancelHandler }
+    ...registerCancelHandler !== void 0 && { registerCancelHandler },
+    ...getWorkflowServices !== void 0 && { getWorkflowServices }
   });
   return { strategy: inlineStrategy, inlineStrategy };
 }

package/dist/core/engine/engine-internal-types.d.ts

@@ -30,6 +30,11 @@ export interface ResolvedOptions {
     archiveAdapter: ArchiveAdapter | null;
     payloadSizePolicy: NormalizedPayloadSizePolicy;
     getNow: () => number;
+    /**
+     * Re-provides the non-serialized per-run `services` value on recovery; `null`
+     * when the engine was created without `resolveWorkflowServices`.
+     */
+    resolveWorkflowServices: EngineOptions['resolveWorkflowServices'] | null;
 }
 export interface WorkflowResultWaiter {
     promise: Promise<unknown>;

package/dist/core/engine/index.d.ts

@@ -230,6 +230,32 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     getStreamChunks(workflowId: string, key: string, options?: {
         after?: number;
     }): Promise<StoredStreamChunk[]>;
+    /**
+     * Read a value a workflow offloaded with `ctx.offload(key, ...)` back out of
+     * storage by `workflowId` + `key`.
+     *
+     * This is the external, post-completion reader for offloaded artifacts — the
+     * missing sibling of {@link getStreamChunks} and {@link getEvents}. Offloaded
+     * values survive normal completion (`completeWorkflow`/`failWorkflow` preserve
+     * them) so a consumer can read a finished workflow's offloaded output after
+     * `handle.result()` resolves. They are swept only when a workflow is
+     * terminated, cancelled, or times out.
+     *
+     * @returns The decoded offload value, or `null` when no value is stored under
+     *   that key (key was never written, workflow ID unknown, or artifact swept).
+     *
+     * @example
+     * ```ts
+     * import { Engine } from '@lostgradient/weft';
+     *
+     * async function readReport(engine: Engine, workflowId: string): Promise<unknown> {
+     *   // `null` when the workflow offloaded nothing under this key, or after a
+     *   // terminated workflow swept its output artifacts.
+     *   return engine.getOffload(workflowId, 'report');
+     * }
+     * ```
+     */
+    getOffload(workflowId: string, key: string): Promise<unknown>;
     fork(sourceWorkflowId: string, options?: ForkOptions): Promise<WorkflowHandle>;
     resume(workflowId: string): Promise<WorkflowHandle>;
     /**

package/dist/core/engine/index.js

@@ -90,6 +90,7 @@ import {
   removeTags as removeWorkflowTags,
   setAttributes as setWorkflowAttributes
 } from "./listing.js";
+import { getOffloadFromInternals } from "./operations-data.js";
 import { getStreamChunksFromInternals } from "./operations-stream.js";
 import {
   handleTimerFired as handleTimerFiredFromInternals
@@ -213,7 +214,8 @@ export class Engine extends EventTarget {
       getRegistration: getInternals(this).registrations.get.bind(getInternals(this).registrations),
       getComposedWorkflowInterceptor: () => getComposedWorkflowInterceptor(getInternals(this)),
       resolveWorkflowType: this.#resolveWorkflowTypeTarget.bind(this),
-      registerCancelHandler: (workflowId, handler) => registerCancelHandler(getInternals(this), workflowId, handler)
+      registerCancelHandler: (workflowId, handler) => registerCancelHandler(getInternals(this), workflowId, handler),
+      getWorkflowServices: (workflowId) => getInternals(this).workflowServices.get(workflowId)
     });
     getInternals(this).storage = storage;
     getInternals(this).abortController = new AbortController;
@@ -261,6 +263,7 @@ export class Engine extends EventTarget {
     if (queuedInlineWorkflowStartChannel !== null)
       queuedInlineWorkflowStartChannel.port1.onmessage = createQueuedInlineWorkflowStartHandler(weakEngine, queuedInlineWorkflowStartChannel);
     getInternals(this).heartbeatDetails = new Map;
+    getInternals(this).workflowServices = new Map;
     getInternals(this).pendingAsyncActivities = new Map;
     getInternals(this).pendingStarts = new Set;
     getInternals(this).pendingScheduleCreations = new Set;
@@ -496,6 +499,9 @@ export class Engine extends EventTarget {
   async getStreamChunks(workflowId, key, options) {
     return getStreamChunksFromInternals(getInternals(this), workflowId, key, options);
   }
+  async getOffload(workflowId, key) {
+    return getOffloadFromInternals(getInternals(this), workflowId, key);
+  }
   async fork(sourceWorkflowId, options) {
     return forkFromLifecycle(getInternals(this), sourceWorkflowId, options, this.#createLifecycleCallbacks());
   }

package/dist/core/engine/internals.d.ts

@@ -108,6 +108,14 @@ export interface EngineInternals {
     workflowHeaders: Map<string, Map<string, string>>;
     workflowStateWriteChains: Map<string, Promise<void>>;
     heartbeatDetails: Map<string, unknown>;
+    /**
+     * Per-run, non-serialized `services` value exposed to the workflow body as
+     * `ctx.services`. Set at `engine.start({ services })` and re-provided on
+     * recovery by `resolveWorkflowServices`. Never checkpointed — held only in
+     * engine memory, keyed by workflowId, and cleared on terminal cleanup (the
+     * same lifecycle as {@link heartbeatDetails}).
+     */
+    workflowServices: Map<string, unknown>;
     /**
      * Activities that called `ctx.completeAsync()` and are awaiting out-of-band
      * completion via `engine.completeAsyncActivity` / `failAsyncActivity`, keyed

package/dist/core/engine/lifecycle/recovered-services.d.ts

@@ -0,0 +1,45 @@
+import type { WorkflowState } from '../../types.ts';
+import type { EngineInternals } from '../internals.ts';
+/**
+ * Re-provide a recovered inline workflow's non-serialized `services` before its
+ * generator is driven forward, and decide whether execution should proceed.
+ *
+ * Both recovery entry points use this: `resumeWorkflowFromStorage` (for a run
+ * left `running`) and the delayed-start timer handler (for a `startAfter`/
+ * `startAt` run that crashed `pending` before its timer fired). On a fresh
+ * process the in-memory `workflowServices` map is empty, so without this a
+ * recovered run that originally had services would silently execute with
+ * `ctx.services === undefined`.
+ *
+ * The resolver is only consulted for runs launched WITH services, detected by
+ * the durable `KEYS.workflowHasServices` marker. A run that never had services
+ * has no marker and proceeds without touching the resolver — so a fail-closed
+ * resolver does not fail healthy no-services runs.
+ *
+ * Returns `false` to proceed (services available, none expected, or no resolver
+ * is configured). Returns `true` to STOP — the run was terminally
+ * failed (services unavailable), or the terminal commit faulted and the run was
+ * left for a later boot to retry. Either way the generator must not advance:
+ * driving it without services would crash the body and that throw would escape
+ * into the recovery loop, aborting sibling runs.
+ *
+ * Worker mode skips this (services are inline-only, rejected at `engine.start()`).
+ * A resolver throw is treated as `unavailable` with the error as the reason,
+ * for the same sibling-isolation reason.
+ *
+ * @param failRun - Terminally fails just this run with `reason`. Supplied by the
+ *   caller because the two entry points reach the termination machinery through
+ *   different callback bundles. It receives the canonical terminal error built
+ *   by {@link unavailableServicesError}, so both recovery paths fail the run
+ *   with an identical message and (via `failWorkflow`'s default) the `system`
+ *   failure category.
+ * @param onCommitError - Records a fail-warn when `failRun` itself throws, so the
+ *   swallowed terminal-commit fault is still observable.
+ */
+export declare function reprovideRecoveredServices(internals: EngineInternals, state: WorkflowState, failRun: (workflowId: string, error: Error) => Promise<void>, onCommitError: (source: string, error: unknown, workflowId: string) => void): Promise<boolean>;
+/**
+ * The canonical terminal error for a recovered run whose services could not be
+ * re-provided. Shared by both recovery paths so they fail with an identical
+ * message (the failure category is `system`, the default for `failWorkflow`).
+ */
+export declare function unavailableServicesError(workflowId: string, reason: string): Error;

package/dist/core/engine/lifecycle/recovered-services.js

@@ -0,0 +1,34 @@
+import { KEYS } from "../../../storage/interface.js";
+export async function reprovideRecoveredServices(internals, state, failRun, onCommitError) {
+  const resolver = internals.options.resolveWorkflowServices;
+  if (internals.inlineStrategy === null || !resolver)
+    return !1;
+  if (internals.workflowServices.has(state.id))
+    return !1;
+  if (await internals.storage.get(KEYS.workflowHasServices(state.id)) === null)
+    return !1;
+  let reason;
+  try {
+    const resolution = await resolver({
+      workflowId: state.id,
+      workflowType: state.type,
+      input: state.input
+    });
+    if (resolution.status === "available") {
+      internals.workflowServices.set(state.id, resolution.services);
+      return !1;
+    }
+    reason = resolution.reason;
+  } catch (error) {
+    reason = error instanceof Error ? error.message : String(error);
+  }
+  try {
+    await failRun(state.id, unavailableServicesError(state.id, reason));
+  } catch (error) {
+    onCommitError("reprovideRecoveredServices", error, state.id);
+  }
+  return !0;
+}
+export function unavailableServicesError(workflowId, reason) {
+  return Error(`Recovered workflow "${workflowId}" services unavailable: ${reason}`);
+}

package/dist/core/engine/lifecycle/resume.js

@@ -10,12 +10,16 @@ import { loadWorkflowState } from "../storage-io.js";
 import { getComposedWorkflowInterceptor } from "../strategy-helpers.js";
 import { decodeWorkflowState } from "../validation.js";
 import { prepareResumeState } from "./persist.js";
+import { reprovideRecoveredServices } from "./recovered-services.js";
 import {
   enforceHistoryPolicyBeforeReplay,
   loadTerminalCleanupTrackedState,
   loadWorkflowStartHeaders,
   setWorkflowStartHeaders
 } from "./shared.js";
+async function prepareRecoveredServicesOrFail(internals, state, callbacks) {
+  return reprovideRecoveredServices(internals, state, callbacks.failWorkflowForUnavailableServices, callbacks.handleCleanupError);
+}
 function assertResumeNotTerminating(internals, workflowId) {
   if (internals.terminalizingWorkflows.has(workflowId))
     throw Error(`Cannot resume workflow "${workflowId}": termination is in progress`);
@@ -57,7 +61,8 @@ function relaunchInlineWorkflowAfterResume(internals, latestState, args) {
     sleepReferenceTime: resumeCheckpoint.createdAt,
     ...latestState.executionDeadline !== void 0 && {
       deadline: latestState.executionDeadline
-    }
+    },
+    services: internals.workflowServices.get(workflowId)
   });
   setContextWorkflowInterceptor(context, getComposedWorkflowInterceptor(internals));
   if (internals.options.development)
@@ -117,6 +122,8 @@ export async function resumeWorkflowFromStorage(internals, workflowId, dispatchR
     return callbacks.getHandle(workflowId);
   const workflowStartHeaders = await loadWorkflowStartHeaders(internals, workflowId, callbacks);
   await loadTerminalCleanupTrackedState(internals, workflowId, callbacks);
+  if (await prepareRecoveredServicesOrFail(internals, state, callbacks))
+    return callbacks.getHandle(workflowId);
   const handle = callbacks.getHandle(workflowId);
   await callbacks.runSerializedWorkflowStateWrite(workflowId, () => performSerializedResume(internals, {
     workflowId,

package/dist/core/engine/lifecycle/shared.d.ts

@@ -48,6 +48,14 @@ export type LifecycleCallbacks = {
      * history is terminated without being replayed.
      */
     enforceHistoryCircuitBreaker: (workflowId: string) => Promise<void>;
+    /**
+     * Force a recovered workflow to a terminal `failed` state because its
+     * non-serialized `services` could not be re-provided (the engine's
+     * `resolveWorkflowServices` reported `unavailable`). Fails just this run with
+     * a `system` failure category; the engine and other recovered runs continue.
+     * `error` is the canonical {@link unavailableServicesError}.
+     */
+    failWorkflowForUnavailableServices: (workflowId: string, error: Error) => Promise<void>;
 };
 /**
  * Pre-replay history circuit breaker. Called at every restore-from-checkpoint

package/dist/core/engine/lifecycle/start-batch.js

@@ -19,18 +19,7 @@ export function buildStartBatchOperations(_internals, workflowId, state, checkpo
     ...visibilityIndexOperations,
     ...buildWorkflowTagIndexOperations(workflowId, void 0, state.tags),
     ...buildInitialSearchAttributeOperations(_internals, workflowId, registration, options?.searchAttributes, callbacks),
-    ...workflowStartHeaders && workflowStartHeaders.size > 0 ? [
-      {
-        type: "put",
-        key: KEYS.workflowHeaders(workflowId),
-        value: encodeWorkflowStartHeaders(workflowStartHeaders)
-      },
-      {
-        type: "put",
-        key: KEYS.terminalCleanupNeeded(workflowId),
-        value: EMPTY_STORAGE_VALUE
-      }
-    ] : [],
+    ...buildPerRunScratchOperations(workflowId, options, workflowStartHeaders),
     ...additionalOperations ?? []
   ];
   if (executionDeadline !== void 0)
@@ -44,6 +33,28 @@ export function buildStartBatchOperations(_internals, workflowId, state, checkpo
     operations.push(...buildTimerBatchOperations(delayedStartTimer));
   return operations;
 }
+function buildPerRunScratchOperations(workflowId, options, workflowStartHeaders) {
+  const hasHeaders = workflowStartHeaders !== void 0 && workflowStartHeaders.size > 0, hasServices = options?.services !== void 0, operations = [];
+  if (hasHeaders)
+    operations.push({
+      type: "put",
+      key: KEYS.workflowHeaders(workflowId),
+      value: encodeWorkflowStartHeaders(workflowStartHeaders)
+    });
+  if (hasServices)
+    operations.push({
+      type: "put",
+      key: KEYS.workflowHasServices(workflowId),
+      value: EMPTY_STORAGE_VALUE
+    });
+  if (hasHeaders || hasServices)
+    operations.push({
+      type: "put",
+      key: KEYS.terminalCleanupNeeded(workflowId),
+      value: EMPTY_STORAGE_VALUE
+    });
+  return operations;
+}
 export function buildInitialSearchAttributeOperations(_internals, workflowId, registration, searchAttributes, callbacks) {
   if (!searchAttributes || Object.keys(searchAttributes).length === 0)
     return [];

package/dist/core/engine/lifecycle/start.js

@@ -51,11 +51,18 @@ function rollbackTransientStartState(internals, workflowId) {
   internals.checkpoints.delete(workflowId);
   internals.workflowHeaders.delete(workflowId);
   internals.workflowVersionTuples.delete(workflowId);
+  internals.workflowServices.delete(workflowId);
+  internals.workflowsNeedingTerminalCleanup.delete(workflowId);
+}
+function assertServicesSupportedForMode(internals, options) {
+  if (options?.services !== void 0 && internals.inlineStrategy === null)
+    throw Error('options.services is only supported in inline execution mode; it cannot be serialized to a Worker. Remove services or use workflowExecutionMode: "inline".');
 }
 export async function startWorkflow(internals, type, input, options, additionalStartOperations, callbacks) {
   const registration = internals.registrations.get(type);
   if (!registration)
     throw new WorkflowNotRegisteredError(type);
+  assertServicesSupportedForMode(internals, options);
   const preparation = prepareStartWorkflow(internals, options, callbacks), { workflowId, callerProvidedId, parentHeaders, executionStateOwnerId, delayedStartTimer } = preparation;
   if (internals.pendingStarts.has(workflowId))
     throw new WorkflowAlreadyExistsError(workflowId);
@@ -73,6 +80,10 @@ export async function startWorkflow(internals, type, input, options, additionalS
     internals.workflowVersionTuples.set(workflowId, versionTuple);
     const startOperations = buildStartBatchOperations(internals, workflowId, state, checkpoint, registration, options, state.executionDeadline, delayedStartTimer, persistedWorkflowStartHeaders, additionalStartOperations, callbacks);
     await persistStartBatch(internals, startOperations);
+    if (options?.services !== void 0) {
+      internals.workflowServices.set(workflowId, options.services);
+      internals.workflowsNeedingTerminalCleanup.add(workflowId);
+    }
     const handle = createWorkflowHandle(internals, workflowId, callbacks);
     if (!delayedStartTimer)
       beginWorkflowExecution(internals, workflowId, type, input, checkpoint, state.executionDeadline, state.executionStateOwnerId ?? workflowId, registration, callbacks);

package/dist/core/engine/operations-data.d.ts

@@ -19,5 +19,21 @@ export type DataOperationCallbacks = {
 export declare function processMemoOperation(_internals: EngineInternals, workflowId: string, operation: MemoOperation, callbacks: DataOperationCallbacks): Promise<void>;
 export declare function processOffloadOperation(internals: EngineInternals, workflowId: string, operation: OffloadOperation, callbacks: DataOperationCallbacks): Promise<void>;
 export declare function processLoadOperation(internals: EngineInternals, workflowId: string, operation: LoadOperation, callbacks: DataOperationCallbacks): Promise<void>;
+/**
+ * Read an offloaded value back out of storage by `workflowId` + `key`, decoding
+ * it with the same codec {@link processOffloadOperation} wrote it with.
+ *
+ * This is the post-completion sibling of the in-workflow `ctx.load()` read
+ * (see {@link processLoadOperation}): `ctx.load()` is restricted to the running
+ * workflow's own offloads and throws on a miss, whereas this external reader
+ * lets a consumer read a *terminal* workflow's offloaded output after
+ * `handle.result()` resolves — the artifact survives normal completion
+ * (`completeWorkflow`/`failWorkflow` preserve `offload:` keys) and is swept only
+ * when the workflow is terminated/cancelled.
+ *
+ * @returns The decoded offload value, or `null` when no value is stored under
+ *   that key (either the key was never written, or the artifact was swept).
+ */
+export declare function getOffloadFromInternals(internals: EngineInternals, workflowId: string, key: string): Promise<unknown>;
 export declare function processArchiveOperation(internals: EngineInternals, workflowId: string, operation: ArchiveOperation, callbacks: DataOperationCallbacks): Promise<void>;
 export {};

package/dist/core/engine/operations-data.js

@@ -30,6 +30,12 @@ export async function processLoadOperation(internals, workflowId, operation, cal
     return decode(raw);
   });
 }
+export async function getOffloadFromInternals(internals, workflowId, key) {
+  const raw = await internals.storage.get(KEYS.offload(workflowId, key));
+  if (raw === null)
+    return null;
+  return decode(raw);
+}
 export async function processArchiveOperation(internals, workflowId, operation, callbacks) {
   return callbacks.runOperationWithResult(workflowId, operation, async () => {
     await internals.storage.put(KEYS.archive(workflowId, operation.key), encode(operation.data));

package/dist/core/engine/operations-time.d.ts

@@ -19,10 +19,11 @@ export type TimeOperationCallbacks = {
     runDeferredTerminalCleanup: (workflowId: string, timerId: string) => Promise<void>;
     handleScheduleTimer: (entry: TimerEntry) => Promise<void>;
     timeout: (workflowId: string) => Promise<void>;
+    handleCleanupError: (source: string, error: unknown, workflowId: string) => void;
 };
 export declare function createDelayedStartTimerEntry(_internals: EngineInternals, workflowId: string, scheduledStartAt: number, options: StartOptions | undefined, callbacks: Pick<TimeOperationCallbacks, 'parseStartOptionDuration'>): TimerEntry;
 export declare function processSleepOperation(internals: EngineInternals, workflowId: string, operation: SleepOperation, callbacks: Pick<TimeOperationCallbacks, 'completeOperation' | 'loadWorkflowState'>): Promise<void>;
 export declare function registerSleepResolver(internals: EngineInternals, workflowId: string, operationId: string, resolve: () => void): void;
-export declare function startDelayedWorkflow(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'beginWorkflowExecution' | 'failWorkflow' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runSerializedWorkflowStateWrite' | 'setWorkflowStartHeaders' | 'workflowVersionTupleFromState'>): Promise<void>;
-export declare function handleTimerFired(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'failWorkflow' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runDeferredTerminalCleanup' | 'runSerializedWorkflowStateWrite' | 'handleScheduleTimer' | 'setWorkflowStartHeaders' | 'timeout' | 'beginWorkflowExecution' | 'workflowVersionTupleFromState'>): Promise<void>;
+export declare function startDelayedWorkflow(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'beginWorkflowExecution' | 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runSerializedWorkflowStateWrite' | 'setWorkflowStartHeaders' | 'workflowVersionTupleFromState'>): Promise<void>;
+export declare function handleTimerFired(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runDeferredTerminalCleanup' | 'runSerializedWorkflowStateWrite' | 'handleScheduleTimer' | 'setWorkflowStartHeaders' | 'timeout' | 'beginWorkflowExecution' | 'workflowVersionTupleFromState'>): Promise<void>;
 export {};

package/dist/core/engine/operations-time.js

@@ -1,7 +1,8 @@
-import { KEYS } from "../../storage/interface.js";
+import { KEYS, storageHas } from "../../storage/interface.js";
 import { deserializeCheckpoint } from "../checkpoint.js";
 import { encode } from "../codec.js";
 import { buildTimerBatchOperations, normalizeStorageTimestamp } from "../scheduler.js";
+import { reprovideRecoveredServices } from "./lifecycle/recovered-services.js";
 import { buildWorkflowVisibilityIndexTransition } from "./workflow-indexes.js";
 export function createDelayedStartTimerEntry(_internals, workflowId, scheduledStartAt, options, callbacks) {
   return {
@@ -85,6 +86,10 @@ export async function startDelayedWorkflow(internals, entry, callbacks) {
   });
   if (!runningState)
     return;
+  if (await reprovideRecoveredServices(internals, runningState, (workflowId, error) => callbacks.failWorkflow(workflowId, error), callbacks.handleCleanupError))
+    return;
+  if (await storageHas(internals.storage, KEYS.terminalCleanupNeeded(entry.workflowId)))
+    internals.workflowsNeedingTerminalCleanup.add(entry.workflowId);
   internals.checkpoints.set(entry.workflowId, checkpoint);
   internals.workflowVersionTuples.set(entry.workflowId, callbacks.workflowVersionTupleFromState(runningState));
   callbacks.setWorkflowStartHeaders(entry.workflowId, await callbacks.loadWorkflowStartHeaders(entry.workflowId));

package/dist/core/engine/termination/cleanup.js

@@ -71,6 +71,7 @@ export function cleanupWaiters(internals, workflowId, callbacks) {
   cleanupReviewEscalations(internals, workflowId, callbacks);
   internals.workflowNestingDepths.delete(workflowId);
   internals.workflowHeaders.delete(workflowId);
+  internals.workflowServices.delete(workflowId);
   internals.workflowTypeByWorkflowId.delete(workflowId);
 }
 export async function cleanupWorkflowStorage(internals, workflowId, includeOutputArtifacts) {
@@ -86,6 +87,7 @@ export async function cleanupWorkflowStorage(internals, workflowId, includeOutpu
     prefixes.push(`offload:${encodedWorkflowId}:`, `blob:${encodedWorkflowId}:`);
   await internals.storage.delete(KEYS.workflowHeaders(workflowId));
   await internals.storage.delete(KEYS.signalSequence(workflowId));
+  await internals.storage.delete(KEYS.workflowHasServices(workflowId));
   if (internals.storage.deletePrefix) {
     for (const prefix of prefixes)
       await internals.storage.deletePrefix(prefix);

package/dist/core/inline-execution-strategy.d.ts

@@ -25,6 +25,11 @@ export interface InlineExecutionDependencies {
     development?: boolean;
     getComposedWorkflowInterceptor?: () => ComposedWorkflowInterceptor | null;
     registerCancelHandler?: (workflowId: string, handler: () => Promise<void> | void) => () => void;
+    /**
+     * Look up the non-serialized per-run `services` value for a workflow, exposed
+     * to the body as `ctx.services`. Returns `undefined` when none was supplied.
+     */
+    getWorkflowServices?: (workflowId: string) => unknown;
 }
 type InlineStartWorkflowParameters = {
     workflowId: string;

package/dist/core/inline-execution-strategy.js

@@ -25,7 +25,8 @@ function createInlineContextOptions(dependencies, registration, parameters, work
     ...parameters.deadline !== void 0 && { deadline: parameters.deadline },
     ...registerCancelHandler !== void 0 && {
       registerCancelHandler: (handler) => registerCancelHandler(parameters.workflowId, handler)
-    }
+    },
+    services: dependencies.getWorkflowServices?.(parameters.workflowId)
   };
 }