@lostgradient/weft 0.2.0

package/dist/core/concurrency.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Durable concurrency primitives — a counting semaphore and a mutex built on
+ * top of the compare-and-swap state slots exposed by `ctx.state.*` and
+ * `engine.state.*`.
+ *
+ * Workflows frequently need to serialize access to a shared resource: only one
+ * workflow may charge a customer at a time, at most three may hit a
+ * rate-limited API concurrently, and so on. The building block already exists —
+ * {@link AtomicState} gives you a single CAS-backed state slot — but reusing it
+ * correctly (with FIFO fairness and a lease that frees the lock if a holder
+ * crashes) is fiddly. {@link DurableSemaphore} and {@link DurableMutex} package
+ * that algorithm so you do not have to hand-roll it.
+ *
+ * The primitives store a single {@link LockRecord} in one CAS slot. Each
+ * `acquire`/`release` is a CAS transaction over that record, so every mutation
+ * is durable, replay-safe, and recovered automatically after a crash. The
+ * primitive never reads the wall clock itself: callers pass a deterministic
+ * `now` (captured durably, e.g. via a clock activity) so the lease arithmetic
+ * replays identically. A holder whose lease has expired is reclaimed by the
+ * next contender, which is what prevents a crashed holder from deadlocking the
+ * lock forever.
+ *
+ * @module core/concurrency
+ */
+import { type AcquireAttempt, type LockRecord } from './concurrency-lock-record.ts';
+export { initialLockRecord, reduceAcquire, reduceRelease, reduceRenew, } from './concurrency-lock-record.ts';
+export type { AcquireAttempt, LockHolder, LockRecord } from './concurrency-lock-record.ts';
+/**
+ * Minimal CAS state-slot surface shared by the durable `ctx.state.*` handles
+ * (whose methods are workflow operations) and the admin `engine.state.*`
+ * handles (whose methods are promises). `RUpdate` is the result of `update`
+ * and `RGet` the result of `get`; both are a `Promise` for {@link AtomicState}
+ * and a workflow-operation generator for `ctx.state.*`. They are decoupled
+ * because `get` may resolve to `T | undefined` while `update` resolves to `T`.
+ * Both {@link AtomicState} and the durable `ctx.state.*` handles satisfy this
+ * structurally, so the same primitive drives both flavours.
+ *
+ * @example
+ * ```ts
+ * import { AtomicState, type CasSlot, type LockRecord } from '@lostgradient/weft';
+ * import { MemoryStorage } from '@lostgradient/weft/storage/memory';
+ *
+ * // AtomicState satisfies CasSlot structurally (its methods return promises).
+ * const slot: CasSlot<LockRecord, Promise<LockRecord>, Promise<LockRecord | undefined>> =
+ *   new AtomicState<LockRecord>(new MemoryStorage(), 'state:workflow-scope:default:lock');
+ * void slot;
+ * ```
+ */
+export interface CasSlot<T, RUpdate, RGet = RUpdate> {
+    get(): RGet;
+    update(updater: (current: T | undefined) => T): RUpdate;
+}
+/**
+ * Options for {@link DurableSemaphore} and {@link DurableMutex}.
+ *
+ * @example
+ * ```ts
+ * import { DurableSemaphore, type DurableSemaphoreOptions } from '@lostgradient/weft';
+ *
+ * const options: DurableSemaphoreOptions = { permits: 3, leaseMs: 60_000 };
+ * const semaphore = new DurableSemaphore(options);
+ * void semaphore;
+ * ```
+ */
+export interface DurableSemaphoreOptions {
+    /**
+     * Number of permits. At most this many holders may hold the lock at once.
+     * Defaults to `1` (a mutex).
+     */
+    permits?: number;
+    /**
+     * Default lease duration in milliseconds applied to an acquired permit when
+     * an explicit `leaseMs` is not supplied to `tryAcquire`. A permit whose lease
+     * expires may be reclaimed by another contender, which is what frees the lock
+     * when a holder crashes without releasing. Defaults to `30_000`.
+     */
+    leaseMs?: number;
+}
+/**
+ * A durable counting semaphore: at most `permits` holders may hold the lock at
+ * once. Built entirely on a single compare-and-swap state slot, so it works
+ * inside workflows (via `ctx.state.*`) and from admin code (via
+ * `engine.state.*`).
+ *
+ * The semaphore is intentionally non-blocking at the slot level: `tryAcquire`
+ * performs one CAS transaction and reports whether the permit was granted. The
+ * caller decides how to wait between attempts — inside a workflow you
+ * `yield* ctx.sleep(...)` between retries so the wait is durable and
+ * replay-safe.
+ *
+ * Fairness is FIFO: a contender enqueues itself and only acquires once it
+ * reaches the head of the waiter queue and a permit is free. Each granted
+ * permit carries a lease; an expired lease is reclaimed by the next contender,
+ * so a crashed holder cannot deadlock the lock forever.
+ *
+ * @example
+ * ```ts
+ * import { DurableSemaphore } from '@lostgradient/weft';
+ * import { AtomicState } from '@lostgradient/weft';
+ * import { MemoryStorage } from '@lostgradient/weft/storage/memory';
+ *
+ * const storage = new MemoryStorage();
+ * const slot = new AtomicState<import('@lostgradient/weft').LockRecord>(
+ *   storage,
+ *   'state:workflow-scope:default:rate-limit:lock',
+ *   { initial: { holders: [], waiters: [] } },
+ * );
+ * const semaphore = new DurableSemaphore({ permits: 3, leaseMs: 60_000 });
+ * const attempt = await semaphore.tryAcquire(slot, { holderId: 'worker-1', now: Date.now() });
+ * if (attempt.acquired) {
+ *   try {
+ *     // ...use the shared resource...
+ *   } finally {
+ *     await semaphore.release(slot, { holderId: 'worker-1', now: Date.now() });
+ *   }
+ * }
+ * ```
+ */
+export declare class DurableSemaphore {
+    readonly permits: number;
+    readonly leaseMs: number;
+    constructor(options?: DurableSemaphoreOptions);
+    /**
+     * Attempt to acquire a permit with a single CAS transaction. Returns whether
+     * the permit was granted and the caller's FIFO queue position when it was
+     * not. The caller is registered in the waiter queue on a failed attempt so a
+     * subsequent retry preserves FIFO order.
+     *
+     * `RUpdate` is the slot's `update` return type — a `Promise` for
+     * {@link AtomicState} or a workflow-operation generator for `ctx.state.*`.
+     */
+    tryAcquire<RUpdate>(slot: CasSlot<LockRecord, RUpdate>, options: {
+        holderId: string;
+        now: number;
+        leaseMs?: number;
+    }): AcquireWithSlot<RUpdate>;
+    /**
+     * Release a held permit with a single CAS transaction. Idempotent: releasing
+     * a permit the caller does not hold simply removes any stale waiter entry.
+     */
+    release<RUpdate>(slot: CasSlot<LockRecord, RUpdate>, options: {
+        holderId: string;
+        now: number;
+    }): RUpdate;
+    /**
+     * Extend the lease on a held permit. Long-running holders renew before their
+     * lease expires so a contender does not reclaim a still-active permit.
+     * Resolves/returns `false` when the caller is not currently a holder.
+     */
+    renew<RUpdate>(slot: CasSlot<LockRecord, RUpdate>, options: {
+        holderId: string;
+        now: number;
+        leaseMs?: number;
+    }): RenewWithSlot<RUpdate>;
+    /**
+     * Read the current record without mutating it. `RGet` is the slot's `get`
+     * return type — a `Promise<LockRecord | undefined>` for {@link AtomicState}
+     * or a workflow-operation generator for `ctx.state.*`.
+     */
+    inspect<RGet>(slot: CasSlot<LockRecord, unknown, RGet>): RGet;
+}
+/**
+ * A durable mutual-exclusion lock: a {@link DurableSemaphore} with exactly one
+ * permit, so at most one holder at a time. Acquire it with `tryAcquire` and
+ * `yield* ctx.sleep(...)` between retries to wait durably for release.
+ *
+ * @example
+ * ```ts
+ * import { DurableMutex } from '@lostgradient/weft';
+ * import { workflow, type WorkflowContext, type LockRecord } from '@lostgradient/weft';
+ *
+ * const transfer = workflow({ name: 'transfer' }).execute(async function* (ctx: WorkflowContext) {
+ *   const slot = ctx.state.workflow<LockRecord>('account-42:lock', {
+ *     initial: { holders: [], waiters: [] },
+ *   });
+ *   const mutex = new DurableMutex({ leaseMs: 60_000 });
+ *   const now = yield* ctx.run(() => Date.now());
+ *   yield* mutex.tryAcquire(slot, { holderId: ctx.workflowId, now });
+ *   try {
+ *     // ...critical section...
+ *   } finally {
+ *     const releaseNow = yield* ctx.run(() => Date.now());
+ *     yield* mutex.release(slot, { holderId: ctx.workflowId, now: releaseNow });
+ *   }
+ * });
+ * void transfer;
+ * ```
+ */
+export declare class DurableMutex extends DurableSemaphore {
+    constructor(options?: Omit<DurableSemaphoreOptions, 'permits'>);
+}
+/**
+ * Result of {@link DurableSemaphore.tryAcquire}, mirroring the slot's flavour:
+ * a `Promise<AcquireAttempt>` when the slot's `update` returns a promise (an
+ * {@link AtomicState}), or a workflow-operation generator otherwise.
+ *
+ * @example
+ * ```ts
+ * import type { AcquireAttempt, AcquireWithSlot } from '@lostgradient/weft';
+ *
+ * type PromiseResult = AcquireWithSlot<Promise<unknown>>; // Promise<AcquireAttempt>
+ * const result: PromiseResult = Promise.resolve<AcquireAttempt>({ acquired: true, position: -1 });
+ * void result;
+ * ```
+ */
+export type AcquireWithSlot<R> = R extends Promise<unknown> ? Promise<AcquireAttempt> : Generator<unknown, AcquireAttempt, unknown>;
+/**
+ * Result of {@link DurableSemaphore.renew}, mirroring the slot's flavour: a
+ * `Promise<boolean>` for an {@link AtomicState} slot, or a workflow-operation
+ * generator that yields to a `boolean` for a `ctx.state.*` slot.
+ *
+ * @example
+ * ```ts
+ * import type { RenewWithSlot } from '@lostgradient/weft';
+ *
+ * type PromiseResult = RenewWithSlot<Promise<unknown>>; // Promise<boolean>
+ * const result: PromiseResult = Promise.resolve(true);
+ * void result;
+ * ```
+ */
+export type RenewWithSlot<R> = R extends Promise<unknown> ? Promise<boolean> : Generator<unknown, boolean, unknown>;

package/dist/core/concurrency.js

@@ -0,0 +1,93 @@
+import {
+  reduceAcquire,
+  reduceRelease,
+  reduceRenew
+} from "./concurrency-lock-record.js";
+export {
+  initialLockRecord,
+  reduceAcquire,
+  reduceRelease,
+  reduceRenew
+} from "./concurrency-lock-record.js";
+function assertValidPermits(permits) {
+  if (!Number.isInteger(permits) || permits < 1)
+    throw RangeError(`DurableSemaphore permits must be a positive integer, received ${permits}`);
+}
+function assertValidLease(leaseMs) {
+  if (!Number.isFinite(leaseMs) || leaseMs <= 0)
+    throw RangeError(`DurableSemaphore lease must be a positive number of milliseconds, received ${leaseMs}`);
+}
+const DEFAULT_LEASE_MS = 30000;
+
+export class DurableSemaphore {
+  permits;
+  leaseMs;
+  constructor(options = {}) {
+    const permits = options.permits ?? 1, leaseMs = options.leaseMs ?? DEFAULT_LEASE_MS;
+    assertValidPermits(permits);
+    assertValidLease(leaseMs);
+    this.permits = permits;
+    this.leaseMs = leaseMs;
+  }
+  tryAcquire(slot, options) {
+    const leaseMs = options.leaseMs ?? this.leaseMs;
+    assertValidLease(leaseMs);
+    let attempt = { acquired: !1, position: -1 };
+    const update = slot.update((current) => {
+      const reduced = reduceAcquire(current, {
+        holderId: options.holderId,
+        now: options.now,
+        leaseMs,
+        permits: this.permits
+      });
+      attempt = reduced.attempt;
+      return reduced.record;
+    });
+    return mapSlotResult(update, () => attempt);
+  }
+  release(slot, options) {
+    return slot.update((current) => reduceRelease(current, options));
+  }
+  renew(slot, options) {
+    const leaseMs = options.leaseMs ?? this.leaseMs;
+    assertValidLease(leaseMs);
+    let renewed = !1;
+    const update = slot.update((current) => {
+      const reduced = reduceRenew(current, {
+        holderId: options.holderId,
+        now: options.now,
+        leaseMs
+      });
+      renewed = reduced.renewed;
+      return reduced.record;
+    });
+    return mapSlotResult(update, () => renewed);
+  }
+  inspect(slot) {
+    return slot.get();
+  }
+}
+
+export class DurableMutex extends DurableSemaphore {
+  constructor(options = {}) {
+    super({ ...options, permits: 1 });
+  }
+}
+function isPromise(value) {
+  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+function isGenerator(value) {
+  return typeof value === "object" && value !== null && "next" in value && typeof value.next === "function";
+}
+function mapSlotResult(result, derive) {
+  if (isPromise(result))
+    return result.then(() => derive());
+  if (isGenerator(result)) {
+    const generator = result;
+    return function* () {
+      yield* generator;
+      return derive();
+    }();
+  }
+  throw TypeError("CAS slot update must return a Promise or a workflow-operation generator");
+}

package/dist/core/constraint.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Workflow constraint primitive.
+ *
+ * Constraints are domain invariants registered alongside a workflow. The
+ * engine evaluates them at every checkpoint commit. When a constraint's
+ * `check` function returns `false`, the engine dispatches a
+ * {@link ConstraintViolatedEvent} and reacts according to `onViolation`:
+ *
+ * - `'fail'`       — immediately fails the workflow; saga compensators do NOT run.
+ * - `'compensate'` — throws into the generator so an active `ctx.saga()`
+ *                    can run its compensators before the error propagates.
+ * - `'warn'`       — logs a warning and continues execution.
+ *
+ * @module core/constraint
+ */
+/**
+ * Reaction to a violated {@link ConstraintDefinition}. `'fail'` immediately
+ * fails the workflow without running saga compensators; `'compensate'`
+ * throws into the workflow generator so an active `ctx.saga()` can run its
+ * compensators in reverse before the error propagates; `'warn'` logs and
+ * continues. Returned from `onViolation` on every constraint definition.
+ *
+ * @example
+ * ```ts
+ * import type { ConstraintViolation } from '@lostgradient/weft';
+ *
+ * const policy: ConstraintViolation = 'compensate';
+ * void policy;
+ * ```
+ */
+export type ConstraintViolation = 'compensate' | 'fail' | 'warn';
+/**
+ * The minimal state snapshot passed to a constraint's `check` function.
+ *
+ * Only `id`, `type`, and `status` (`'running'`) are available — constraints
+ * are evaluated mid-execution, before the workflow has a result or final
+ * status. To inspect external state (e.g. a balance), capture it in the
+ * enclosing scope instead of relying on this parameter.
+ */
+export interface ConstraintCheckState {
+    id: string;
+    type: string;
+    status: 'running';
+}
+/**
+ * Domain invariant evaluated at every workflow checkpoint commit. Build via
+ * the {@link constraint} factory function and attach to a workflow with the
+ * builder's `.constraints(...)` step (or via `WorkflowDefinition.constraints`
+ * on a hand-rolled definition). When `check` returns `false` the engine reacts
+ * per `onViolation` and emits a {@link ConstraintViolatedEvent}.
+ *
+ * @example
+ * ```ts
+ * import { constraint, Engine, workflow, type ConstraintDefinition } from '@lostgradient/weft';
+ *
+ * let balance = 0;
+ * const positiveBalance: ConstraintDefinition = constraint({
+ *   name: 'positiveBalance',
+ *   scope: 'transaction',
+ *   check: () => balance >= 0,
+ *   onViolation: 'compensate',
+ * });
+ *
+ * const transfer = workflow({ name: 'transfer', constraints: [positiveBalance] })
+ *   .execute(async function* () { return 'done'; });
+ *
+ * const engine = new Engine();
+ * engine.register(transfer);
+ * void engine;
+ * ```
+ *
+ * **Worker execution caveat**: constraints attached to a workflow are only
+ * evaluated under the inline execution strategy. When
+ * `EngineOptions.workerExecution` is configured, constraint evaluation is
+ * silently skipped.
+ */
+export interface ConstraintDefinition {
+    name: string;
+    /** Domain label for observability (e.g. 'transaction', 'budget'). */
+    scope: string;
+    /**
+     * Return `true` when the invariant holds, `false` when it is violated.
+     *
+     * The `state` parameter is a {@link ConstraintCheckState} — always
+     * `{ id: string; type: string; status: 'running' }`. To check external
+     * state (e.g. a balance from your own closure), capture it in the
+     * enclosing scope instead:
+     *
+     * ```ts
+     * let balance = 0;
+     * const balanceCheck = constraint({
+     *   name: 'positiveBalance',
+     *   scope: 'transaction',
+     *   check: () => balance >= 0,
+     *   onViolation: 'compensate',
+     * });
+     * ```
+     *
+     * The function may be async — returning `Promise<boolean>` is supported.
+     *
+     * **Note**: Constraints are only evaluated when using the inline execution
+     * strategy. Workflows running in a Web Worker will silently skip constraint
+     * evaluation. Document this on your registration if using worker execution.
+     */
+    check: (state: ConstraintCheckState) => boolean | Promise<boolean>;
+    /**
+     * Reaction when the constraint is violated.
+     *
+     * - `'fail'`       — immediately fails the workflow without running any
+     *                    `ctx.saga()` compensators. Use this for hard invariants
+     *                    where partial rollback would be unsafe or meaningless.
+     * - `'compensate'` — throws into the workflow generator so an active
+     *                    `ctx.saga()` can catch the error, run its compensators
+     *                    in reverse, and then re-throw. Use this when you have
+     *                    compensating actions registered that need to execute.
+     * - `'warn'`       — logs a warning and continues execution.
+     */
+    onViolation: ConstraintViolation;
+}
+/**
+ * Create a constraint definition.
+ *
+ * Constraints are domain invariants evaluated at every checkpoint commit.
+ * Capture external state in the enclosing scope — the `state` parameter
+ * passed to `check` is always a minimal `{ id, type, status }` snapshot.
+ *
+ * @example
+ * ```ts
+ * import { constraint, Engine } from '@lostgradient/weft';
+ *
+ * let balance = 0;
+ *
+ * const positiveBalance = constraint({
+ *   name: 'positiveBalance',
+ *   scope: 'transaction',
+ *   check: () => balance >= 0,
+ *   onViolation: 'compensate',
+ * });
+ *
+ * const engine = new Engine();
+ * // engine.register(workflow, { constraints: [positiveBalance] });
+ * ```
+ */
+export declare function constraint(definition: ConstraintDefinition): ConstraintDefinition;

package/dist/core/constraint.js

@@ -0,0 +1,3 @@
+export function constraint(definition) {
+  return definition;
+}

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

@@ -0,0 +1,7 @@
+import type { SearchAttributeValue } from '../types.ts';
+import type { ContextInternals } from './internals.ts';
+export declare function validateAttribute(internals: ContextInternals, key: string, value: SearchAttributeValue): void;
+export declare function setAttribute(internals: ContextInternals, key: string, value: SearchAttributeValue): void;
+export declare function setAttributes(internals: ContextInternals, attributes: Record<string, SearchAttributeValue>): void;
+export declare function getAttribute<T extends SearchAttributeValue = SearchAttributeValue>(internals: ContextInternals, key: string): T | undefined;
+export declare function getAttributes(internals: ContextInternals): Readonly<Record<string, SearchAttributeValue>>;

package/dist/core/context/attributes.js

@@ -0,0 +1,29 @@
+import { validateAttributeType } from "../search-attributes.js";
+export function validateAttribute(internals, key, value) {
+  if (internals.searchAttributeSchema) {
+    if (!(key in internals.searchAttributeSchema))
+      throw Error(`Unknown search attribute "${key}". Registered attributes: ${Object.keys(internals.searchAttributeSchema).join(", ")}`);
+    validateAttributeType(key, value, internals.searchAttributeSchema[key]);
+  }
+}
+export function setAttribute(internals, key, value) {
+  validateAttribute(internals, key, value);
+  internals.searchAttributes[key] = value;
+  internals.pendingAttributeChanges ??= {};
+  internals.pendingAttributeChanges[key] = value;
+}
+export function setAttributes(internals, attributes) {
+  for (const [key, value] of Object.entries(attributes))
+    validateAttribute(internals, key, value);
+  for (const [key, value] of Object.entries(attributes)) {
+    internals.searchAttributes[key] = value;
+    internals.pendingAttributeChanges ??= {};
+    internals.pendingAttributeChanges[key] = value;
+  }
+}
+export function getAttribute(internals, key) {
+  return internals.searchAttributes[key];
+}
+export function getAttributes(internals) {
+  return { ...internals.searchAttributes };
+}

package/dist/core/context/child-workflow-pipe.d.ts

@@ -0,0 +1,18 @@
+import type { ChildWorkflowOptions, ChildWorkflowTarget, WorkflowMapOptions, WorkflowPipeStage, WorkflowReduceInput, WorkflowReduceOptions } from '../types.ts';
+import type { Context } from './index.ts';
+import type { ContextInternals } from './internals.ts';
+import type { ContextOperationRequest } from './operation-request.ts';
+export declare function normalizePipeStage(internals: ContextInternals, stage: WorkflowPipeStage | ChildWorkflowTarget): {
+    workflowType: string;
+    options: ChildWorkflowOptions | undefined;
+};
+export declare function resolveChildWorkflowTarget<TInput = unknown, TOutput = unknown>(internals: ContextInternals, target: ChildWorkflowTarget<TInput, TOutput>): string;
+export declare function resolveMapConcurrency(totalItems: number, requestedConcurrency: number | undefined): number;
+export declare function createCompositionToken(internals: ContextInternals, kind: 'map' | 'pipe' | 'reduce'): string;
+export declare function createCompositionChildWorkflowOptions(internals: ContextInternals, token: string, index: number, options?: ChildWorkflowOptions | undefined): ChildWorkflowOptions;
+export declare function createReduceChildWorkflowOptions(internals: ContextInternals, token: string, index: number, options: WorkflowReduceOptions | undefined): ChildWorkflowOptions;
+export declare function primeParallelOperations(operations: Generator<ContextOperationRequest, unknown, unknown>[]): ContextOperationRequest[];
+export declare function startChild<TResult = unknown>(context: Context, internals: ContextInternals, workflowType: string, input: unknown, options?: ChildWorkflowOptions): Generator<ContextOperationRequest, TResult, unknown>;
+export declare function pipe<TResult = unknown>(context: Context, internals: ContextInternals, stages: Array<WorkflowPipeStage | ChildWorkflowTarget>, input: unknown): Generator<ContextOperationRequest, TResult, unknown>;
+export declare function map<TItem, TResult>(context: Context, internals: ContextInternals, items: readonly TItem[], workflowType: ChildWorkflowTarget<TItem, TResult>, options?: WorkflowMapOptions): Generator<ContextOperationRequest, TResult[], unknown>;
+export declare function reduce<TItem, TAccumulator>(context: Context, internals: ContextInternals, items: readonly TItem[], workflowType: ChildWorkflowTarget<WorkflowReduceInput<TAccumulator, TItem>, TAccumulator>, initialValue: TAccumulator, options?: WorkflowReduceOptions): Generator<ContextOperationRequest, TAccumulator, unknown>;

package/dist/core/context/child-workflow-pipe.js

@@ -0,0 +1,111 @@
+import { captureCallerStack } from "./validation.js";
+export function normalizePipeStage(internals, stage) {
+  if (typeof stage === "object" && stage !== null && "type" in stage)
+    return {
+      workflowType: resolveChildWorkflowTarget(internals, stage.type),
+      options: stage.options
+    };
+  return {
+    workflowType: resolveChildWorkflowTarget(internals, stage),
+    options: void 0
+  };
+}
+export function resolveChildWorkflowTarget(internals, target) {
+  if (typeof target === "string")
+    return target;
+  if (internals.resolveWorkflowType)
+    return internals.resolveWorkflowType(target);
+  throw Error("Workflow functions used in composition operators must be registered before use. Pass the registered workflow type string or register the function on the engine first.");
+}
+export function resolveMapConcurrency(totalItems, requestedConcurrency) {
+  if (requestedConcurrency === void 0)
+    return totalItems;
+  if (!Number.isFinite(requestedConcurrency) || !Number.isInteger(requestedConcurrency) || requestedConcurrency < 1)
+    throw Error("ctx.map concurrency must be a positive integer");
+  return Math.min(requestedConcurrency, totalItems);
+}
+export function createCompositionToken(internals, kind) {
+  return `${kind}:${internals.stepIndex}`;
+}
+export function createCompositionChildWorkflowOptions(internals, token, index, options = void 0) {
+  if (options?.id !== void 0)
+    return options;
+  return {
+    ...options,
+    id: `${internals.context.workflowId}:${token}:${index}`
+  };
+}
+export function createReduceChildWorkflowOptions(internals, token, index, options) {
+  if (options === void 0)
+    return createCompositionChildWorkflowOptions(internals, token, index);
+  const { idPrefix, ...childWorkflowOptions } = options;
+  return createCompositionChildWorkflowOptions(internals, token, index, idPrefix !== void 0 ? {
+    ...childWorkflowOptions,
+    id: `${idPrefix}:${index}`
+  } : childWorkflowOptions);
+}
+export function primeParallelOperations(operations) {
+  const subOperations = [];
+  for (const generator of operations) {
+    const yielded = generator.next();
+    if (!yielded.done)
+      subOperations.push(yielded.value);
+  }
+  return subOperations;
+}
+export function* startChild(context, internals, workflowType, input, options) {
+  const step = internals.stepIndex++;
+  if (internals.accumulatedResults?.has(step)) {
+    if (internals.explainMode)
+      console.log(`[weft] ctx.startChild("${workflowType}") \u2192 Returning cached result from step ${step}`);
+    return internals.accumulatedResults.get(step);
+  }
+  if (internals.explainMode) {
+    console.log(`[weft] ctx.startChild("${workflowType}", ${JSON.stringify(input)})`);
+    console.log(`  \u2192 Creating checkpoint at step ${step}`);
+    console.log(`  \u2192 Starting child workflow of type "${workflowType}"`);
+  }
+  const operationId = crypto.randomUUID(), callerStack = captureCallerStack(), result = yield {
+    type: "child-workflow",
+    operationId,
+    workflowType,
+    input,
+    callerStack,
+    ...options !== void 0 ? { options } : {}
+  };
+  context.accumulatedResults.set(step, result);
+  return result;
+}
+export function* pipe(context, internals, stages, input) {
+  const pipelineToken = createCompositionToken(internals, "pipe");
+  let currentInput = input;
+  for (const [index, stage] of stages.entries()) {
+    const resolvedStage = normalizePipeStage(internals, stage);
+    currentInput = yield* context.startChild(resolvedStage.workflowType, currentInput, createCompositionChildWorkflowOptions(internals, pipelineToken, index, resolvedStage.options));
+  }
+  return currentInput;
+}
+export function* map(context, internals, items, workflowType, options) {
+  if (items.length === 0)
+    return [];
+  const mapToken = createCompositionToken(internals, "map"), concurrency = resolveMapConcurrency(items.length, options?.concurrency), resolvedWorkflowType = resolveChildWorkflowTarget(internals, workflowType), results = [];
+  for (let startIndex = 0;startIndex < items.length; startIndex += concurrency) {
+    const batchItems = items.slice(startIndex, startIndex + concurrency), batchResults = yield* context.all(batchItems.map((item, batchIndex) => context.startChild(resolvedWorkflowType, item, createCompositionChildWorkflowOptions(internals, mapToken, startIndex + batchIndex))));
+    for (let batchIndex = 0;batchIndex < batchResults.length; batchIndex++)
+      results[startIndex + batchIndex] = batchResults[batchIndex];
+  }
+  return results;
+}
+export function* reduce(context, internals, items, workflowType, initialValue, options) {
+  if (items.length === 0)
+    return initialValue;
+  const reduceToken = createCompositionToken(internals, "reduce"), resolvedWorkflowType = resolveChildWorkflowTarget(internals, workflowType);
+  let accumulator = initialValue;
+  for (const [index, item] of items.entries())
+    accumulator = yield* context.startChild(resolvedWorkflowType, {
+      accumulator,
+      item,
+      index
+    }, createReduceChildWorkflowOptions(internals, reduceToken, index, options));
+  return accumulator;
+}

package/dist/core/context/durable-operations.d.ts

@@ -0,0 +1,29 @@
+import type { HumanReviewOptions, HumanReviewResult } from '../review/index.ts';
+import type { Duration } from '../types.ts';
+import type { Context } from './index.ts';
+import type { ContextInternals } from './internals.ts';
+import type { ContextOperationRequest } from './operation-request.ts';
+import type { OffloadReference, StreamReference, StreamSink } from './types.ts';
+export type PreparedSleepOperation = {
+    cached: true;
+} | {
+    cached: false;
+    milliseconds: number;
+    request: ContextOperationRequest;
+    step: number;
+};
+export declare function prepareSleepOperation(internals: ContextInternals, duration: Duration): PreparedSleepOperation;
+export declare function completePreparedSleepOperation(context: Context, prepared: Exclude<PreparedSleepOperation, {
+    cached: true;
+}>): Generator<ContextOperationRequest, void, unknown>;
+export declare function sleep(context: Context, internals: ContextInternals, duration: Duration): Generator<ContextOperationRequest, void, unknown>;
+export declare function waitForSignal<T = unknown>(context: Context, internals: ContextInternals, name: string): Generator<ContextOperationRequest, T, unknown>;
+export declare function waitForUpdate<T = unknown>(context: Context, internals: ContextInternals, name: string): Generator<ContextOperationRequest, {
+    payload: T;
+    respond: (result: unknown) => void;
+}, unknown>;
+export declare function review(context: Context, internals: ContextInternals, options: HumanReviewOptions): Generator<ContextOperationRequest, HumanReviewResult, unknown>;
+export declare function offload<T>(context: Context, internals: ContextInternals, key: string, fn: () => Promise<T>): Generator<ContextOperationRequest, OffloadReference, unknown>;
+export declare function stream(context: Context, internals: ContextInternals, key: string, fn: (sink: StreamSink) => AsyncGenerator<unknown, void, unknown>): Generator<ContextOperationRequest, StreamReference, unknown>;
+export declare function load<T>(context: Context, internals: ContextInternals, reference: OffloadReference): Generator<ContextOperationRequest, T, unknown>;
+export declare function archive(context: Context, internals: ContextInternals, key: string, data: unknown): Generator<ContextOperationRequest, void, unknown>;