@lostgradient/weft 0.2.1 → 0.4.0

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

@@ -9,7 +9,8 @@ import type { Duration } from './retry-retention.ts';
 import type { SearchAttributeHandle, SearchAttributeSchema, SearchAttributeValue, SearchAttributeValueForDefinition } from './search-attributes.ts';
 import type { WorkflowStateNamespace } from './state.ts';
 import type { ActivityArgsFor, ActivityMap, ActivityResultFor, QueryMap, QueryShape, SignalMap, SignalPayload, UpdateMap, UpdatePayload } from './workflow-builder-helpers.ts';
-import type { ChildWorkflowOptions, ChildWorkflowTarget, WorkflowMapOptions, WorkflowOperation, WorkflowPipeStage, WorkflowPipeStageDefinition, WorkflowReduceInput, WorkflowReduceOptions } from './workflow-function.ts';
+import type { AwaitChildWorkflowOptions, ChildWorkflowHandle, ChildWorkflowOptions, ChildWorkflowTarget, DetachedChildWorkflowOptions, WorkflowMapOptions, WorkflowOperation, WorkflowPipeStage, WorkflowPipeStageDefinition, WorkflowReduceInput, WorkflowReduceOptions } from './workflow-function.ts';
+import type { WorkflowLogger } from './workflow-log.ts';
 export type WorkflowOperationResult<TOperation> = TOperation extends Generator<unknown, infer TResult, unknown> ? TResult : never;
 export type WorkflowOperationTupleResult<TOperations extends readonly WorkflowOperation<unknown>[]> = {
     -readonly [TIndex in keyof TOperations]: WorkflowOperationResult<TOperations[TIndex]>;
@@ -51,8 +52,14 @@ export type RunAllResult<TBranches extends Record<string, WorkflowRunAllBranch>>
  * void engine;
  * ```
  */
-export interface WorkflowContext<TActivities extends ActivityMap = {}, TSignals extends SignalMap = {}, TUpdates extends UpdateMap = {}, TQueries extends QueryMap = {}, TSearchAttributes extends SearchAttributeSchema = {}> {
+export interface WorkflowContext<TActivities extends ActivityMap = {}, TSignals extends SignalMap = {}, TUpdates extends UpdateMap = {}, TQueries extends QueryMap = {}, TSearchAttributes extends SearchAttributeSchema = {}, TServices = unknown> {
     readonly workflowId: WorkflowId;
+    /**
+     * The registered workflow type name for this run (the `name` field from
+     * `workflow({ name: '...' })`). Useful for logging and self-inspection
+     * without capturing the name at the workflow definition site.
+     */
+    readonly workflowType: string;
     readonly signal: AbortSignal;
     readonly executionTimeRemaining: number;
     readonly startedAt: number;
@@ -63,15 +70,16 @@ export interface WorkflowContext<TActivities extends ActivityMap = {}, TSignals
      * clients, tool registries). The value is **never checkpointed**: it is held
      * only in engine memory for this run, and on a fresh-process recovery it is
      * re-provided by the engine's `resolveWorkflowServices` resolver before the
-     * generator advances. `undefined` when no services were supplied (and not yet
-     * re-provided on recovery). Inline execution mode only — passing `services`
-     * under `workflowExecutionMode: 'worker'` throws at `engine.start()`, since a
+     * generator advances. `undefined` only when no services were supplied; a
+     * services-marked run fails before resume if the fresh engine cannot
+     * re-provide them. Inline execution mode only — passing `services` under
+     * `workflowExecutionMode: 'worker'` throws at `engine.start()`, since a
      * non-serializable value cannot cross to a Worker.
      *
-     * Typed `unknown`: narrow or cast at the call site
-     * (`const { db } = ctx.services as MyServices`). A threaded generic is a
-     * deliberate follow-on, not part of this surface yet. Optional so existing
-     * structural `WorkflowContext` implementors are not source-broken.
+     * Typed by the workflow definition when the builder declares
+     * `.services<MyServices>()`, and `unknown` otherwise. Optional so existing
+     * structural `WorkflowContext` implementors are not source-broken and so
+     * workflows still handle no-services launches explicitly.
      *
      * Separate child *workflows* started from within a workflow (`ctx.startChild()`)
      * do **not** inherit the parent's `services` — each run is its own workflow with
@@ -81,7 +89,21 @@ export interface WorkflowContext<TActivities extends ActivityMap = {}, TSignals
      * replay (same `workflowId`) and therefore does carry the run's `services`
      * across.
      */
-    readonly services?: unknown;
+    readonly services?: TServices;
+    /**
+     * Structured logger scoped to this run, auto-carrying `workflowId` and
+     * `workflowType`. Replay-safe in both inline and worker execution modes: log
+     * calls in the already-committed replay window are suppressed so a recovered
+     * run does not re-emit logs. See {@link WorkflowLogger} for the full contract
+     * (method set, the after-last-step caveat, and parallel-branch semantics).
+     *
+     * Optional on the interface so existing structural `WorkflowContext`
+     * implementors (test stubs and the like) are not source-broken — the same
+     * precedent as {@link WorkflowContext.services}. The engine always populates it
+     * at runtime, so within a real workflow body `ctx.log` is always present; the
+     * `?` only affects callers typed against the bare interface (use `ctx.log?.`).
+     */
+    readonly log?: WorkflowLogger;
     run<TName extends keyof TActivities & string>(name: TName, ...rest: ActivityArgsFor<TActivities[TName]>): WorkflowOperation<ActivityResultFor<TActivities[TName]>>;
     run<TName extends keyof TActivities & string>(name: TName, ...rest: [...ActivityArgsFor<TActivities[TName]>, ActivityCallOptions]): WorkflowOperation<ActivityResultFor<TActivities[TName]>>;
     run<TName extends string>(name: UnknownNameWhenRegistryHasNoKnownNames<TName, keyof TActivities & string>, input?: unknown, options?: ActivityCallOptions): WorkflowOperation<unknown>;
@@ -107,6 +129,47 @@ export interface WorkflowContext<TActivities extends ActivityMap = {}, TSignals
         payload: T;
         respond: (result: unknown) => void;
     }>;
+    /**
+     * Wait until `predicate` returns `true`, re-evaluated by the engine each time
+     * the workflow is driven forward — when an `onUpdate` handler mutates
+     * workflow-local state, or when the optional `timeout` elapses. This is the
+     * condition-variable primitive (Temporal's `condition()`): a `waitUntil` whose
+     * predicate reads state mutated by `onUpdate` handlers re-checks in-process
+     * without polling. (Weft signals are pull-only via `ctx.waitForSignal`; they
+     * run no state-mutating handler, so signal delivery does not re-drive a
+     * `waitUntil` — use `onUpdate` to push state a predicate observes.)
+     *
+     * The predicate must be PURE — it may read only checkpoint-restored
+     * workflow-local state (`ctx.state`, locals, search attributes) and must not
+     * perform I/O, generate randomness, or read wall-clock time. It is a
+     * non-serializable closure (like `ctx.memo`'s function), held in-process and
+     * never checkpointed. Once the wait outcome has been checkpointed, replay
+     * returns the cached outcome and does not re-invoke the predicate. A predicate
+     * that throws fails the workflow at the `yield* ctx.waitUntil` call site (like
+     * a throwing activity), so the workflow body can `try`/`catch` it.
+     *
+     * Inline execution only — worker execution does not expose this operation (it
+     * is omitted from the worker context type), because the predicate closure
+     * cannot cross to a worker process. It also cannot be a branch of `ctx.race`,
+     * `ctx.all`, or `ctx.speculate`; used there it throws an actionable error.
+     *
+     * Without `timeout` it resolves `void` once the predicate is met (waits
+     * forever). With `timeout` it resolves `true` when the predicate was met or
+     * `false` when the deadline elapsed first; if both happen on the same tick the
+     * predicate wins (resolves `true`). `timeout` is milliseconds (`number`) or a
+     * duration string (`'30s'`, `'5m'` — see {@link Duration}).
+     */
+    waitUntil(predicate: () => boolean): WorkflowOperation<void>;
+    waitUntil(predicate: () => boolean, timeout: Duration): WorkflowOperation<boolean>;
+    /**
+     * Pin a named workflow patch to a deterministic numeric version. The first
+     * execution stores `maxSupported` under `version:${changeId}` in checkpoint
+     * locals; replay and recovery return that stored value so in-flight workflows
+     * can keep taking their original branch while new runs pin the newer version.
+     * Raise `minSupported` only after every in-flight run pinned below that version
+     * has completed.
+     */
+    getVersion(changeId: string, minSupported: number, maxSupported: number): WorkflowOperation<number>;
     review(options: HumanReviewOptions): WorkflowOperation<HumanReviewResult>;
     all<const TOperations extends readonly WorkflowOperation<unknown>[]>(operations: TOperations): WorkflowOperation<WorkflowOperationTupleResult<TOperations>>;
     race<const TOperations extends readonly WorkflowOperation<unknown>[]>(operations: TOperations): WorkflowOperation<WorkflowOperationTupleResult<TOperations>[number]>;
@@ -123,7 +186,9 @@ export interface WorkflowContext<TActivities extends ActivityMap = {}, TSignals
      * durable activity pipeline and is not replayed after engine restart.
      */
     saga<TFinalOutput = unknown>(steps: ErasedSagaStep[]): WorkflowOperation<TFinalOutput>;
-    startChild<TResult = unknown>(workflowType: string, input: unknown, options?: ChildWorkflowOptions): WorkflowOperation<TResult>;
+    startChild<TResult = unknown>(workflowType: string, input: unknown, options: DetachedChildWorkflowOptions): WorkflowOperation<ChildWorkflowHandle<TResult>>;
+    startChild<TResult = unknown>(workflowType: string, input: unknown, options?: AwaitChildWorkflowOptions): WorkflowOperation<TResult>;
+    startChild<TResult = unknown>(workflowType: string, input: unknown, options?: ChildWorkflowOptions): WorkflowOperation<TResult | ChildWorkflowHandle<TResult>>;
     pipe<TInput, TOutput>(stages: [WorkflowPipeStageDefinition<TInput, TOutput>], input: TInput): WorkflowOperation<TOutput>;
     pipe<TInput, TIntermediate, TOutput>(stages: [
         WorkflowPipeStageDefinition<TInput, TIntermediate>,
@@ -170,10 +235,27 @@ export interface WorkflowContext<TActivities extends ActivityMap = {}, TSignals
      *
      * **Best-effort only**: handlers run outside the durable effect log and are
      * not retried. Side effects in handlers are not replay-safe, and registered
-     * handlers are not restored after an engine restart.
+     * handlers are not restored after an engine restart. A hard cancel or an
+     * engine crash that evicts the workflow before the handler runs loses it.
+     *
+     * **Prefer a durable `finalizer` for resource teardown.** To tear down a paid
+     * external resource (a sandbox, a leased VM) so it is destroyed even across a
+     * hard cancel or a crash, record the resource with
+     * {@link WorkflowContext.setFinalizerState} and declare a definition-level
+     * `finalizer` activity — the engine drives it durably post-terminal. `onCancel`
+     * remains the right tool for in-process, best-effort cleanup (releasing an
+     * in-memory lock, flushing a buffer) where durability is not required.
+     * Registering a `finalizer` works in both inline and worker mode; only the
+     * in-generator `ctx.setFinalizerState` call requires inline execution (see
+     * `setFinalizerState`).
      *
-     * **Worker-pool mode**: this method throws when the engine uses a remote
-     * worker pool so teardown does not silently drop.
+     * **Inline-only**: `onCancel` is in-process host wiring available only under
+     * inline execution. A handler annotated `(ctx: WorkflowContext)` type-checks the
+     * call (the static type declares it), but at runtime in worker mode the
+     * generator's `ctx` is a reduced worker-side context that does not carry
+     * `onCancel`, so the call fails with a `TypeError` rather than silently dropping
+     * teardown. (Inside a `ctx.speculate()` branch the method is present but its
+     * engine callback is unset, so it throws a descriptive guard error instead.)
      *
      * @example
      * ```ts
@@ -189,5 +271,66 @@ export interface WorkflowContext<TActivities extends ActivityMap = {}, TSignals
      * ```
      */
     onCancel(handler: () => Promise<void> | void): void;
+    /**
+     * Durably record the payload the engine passes to this workflow's
+     * definition-level `finalizer` activity when it drives teardown after a
+     * `cancelled` or `timed-out` terminal (issue #446).
+     *
+     * Call this immediately after acquiring a paid external resource, passing
+     * whatever the finalizer needs to destroy it (e.g. a sandbox id). The value is
+     * durably staged — as a pending atomic side-effect committed with the next
+     * checkpoint or the terminal transition, fenced under lease ownership — so the
+     * finalizer can run even across a hard cancel or an engine crash. Recording is
+     * the engine's signal that there is something to tear down: if the workflow
+     * never calls this, the engine skips the finalizer entirely. Recording `null`
+     * is different — it still counts as recorded, so the finalizer runs with a
+     * `null` payload. The value is last-write-wins, so a later call replaces the
+     * earlier one — record the id of the resource that is currently live.
+     *
+     * **The finalizer runs at least once and must be idempotent.** The engine
+     * drives it with bounded retries and re-drives a stale claim after a crash, so
+     * the same payload can reach the finalizer more than once (the same contract as
+     * keying a destroy by `sandboxId`). Make the teardown safe to repeat —
+     * destroying an already-destroyed resource must succeed (or no-op), not throw.
+     *
+     * Calling this after the workflow is already terminalizing is a no-op (a
+     * development warning is logged); finalizer state is recordable only while the
+     * workflow is live.
+     *
+     * **Inline-only caveat**: this method is durable host wiring, available only
+     * under inline execution — but its absence surfaces differently per path:
+     *
+     * - *Inline, top level*: the engine wires up the callback this method delegates
+     *   to, so it records state.
+     * - *Inside a `ctx.speculate()` branch*: the branch reuses the same
+     *   {@link WorkflowContext}, so `setFinalizerState` exists, but the engine
+     *   leaves its callback unset for speculation, so the call throws a descriptive
+     *   guard error rather than recording state.
+     * - *Worker execution mode*: the generator's runtime `ctx` is a reduced
+     *   worker-side context that does not carry `setFinalizerState` at all. A
+     *   handler annotated `(ctx: WorkflowContext)` still type-checks the call (the
+     *   static type declares the method), but at runtime the method is absent on the
+     *   worker context value, so the call fails with a `TypeError`.
+     *
+     * A workflow that must record finalizer state therefore has to run in inline
+     * execution mode. Durable finalizer *registration* works in worker mode since
+     * #564; only the in-generator `setFinalizerState` call requires inline execution.
+     * For in-process, best-effort cleanup that does not need to survive a crash, use
+     * {@link WorkflowContext.onCancel}.
+     *
+     * @example
+     * ```ts
+     * import { workflow, type WorkflowContext } from '@lostgradient/weft';
+     *
+     * const provision = workflow({ name: 'provision' })
+     *   .execute(async function* (ctx: WorkflowContext) {
+     *     const sandbox = yield* ctx.run(createSandbox);
+     *     ctx.setFinalizerState({ sandboxId: sandbox.id });
+     *     yield* ctx.run(doWork, sandbox.id);
+     *   });
+     * void provision;
+     * ```
+     */
+    setFinalizerState(value: unknown): void;
 }
 export {};

package/dist/core/types/workflow-definition.d.ts

@@ -2,20 +2,21 @@
  * The `WorkflowDefinition` type — the runtime shape produced by
  * `workflow({ name }).execute(fn)`. Carries the workflow name, the generator
  * handler, and the colocated metadata the engine reads at registration time
- * (version, schemas, retention, search attributes, migration, domain
- * constraints, tags, description).
+ * (version, schemas, retention, search attributes, domain constraints, tags,
+ * description).
  */
 import type { ConstraintDefinition } from '../constraint.ts';
 import type { DefinitionSchema } from './definition-schema.ts';
 import type { RetentionPolicy } from './retry-retention.ts';
 import type { SearchAttributeSchema } from './search-attributes.ts';
+import type { WorkflowConcurrencyOptions } from './workflow-concurrency.ts';
 import type { WorkflowFunction } from './workflow-function.ts';
+import type { AnyActivityDefinition } from './workflow-registries.ts';
 /**
  * Named workflow definition returned by {@link workflow}. The runtime object
  * carries the workflow name, the generator handler, and optional metadata
- * (version, schemas, retention policy, search-attribute schema, checkpoint
- * migration, and domain constraints) that the engine reads at registration
- * time.
+ * (version, schemas, retention policy, workflow concurrency, search-attribute
+ * schema, and domain constraints) that the engine reads at registration time.
  *
  * @example
  * ```ts
@@ -27,12 +28,12 @@ import type { WorkflowFunction } from './workflow-function.ts';
  *   });
  * ```
  */
-export interface WorkflowDefinition<TInput = unknown, TOutput = unknown, TName extends string = string> {
+export interface WorkflowDefinition<TInput = unknown, TOutput = unknown, TName extends string = string, TServices = unknown> {
     /** Wire-safe workflow name; the registry key. */
     name: TName;
     /** Workflow generator function executed by the engine. */
-    handler: WorkflowFunction<TInput, TOutput>;
-    /** Version recorded with workflow state and used for checkpoint migration. */
+    handler: WorkflowFunction<TInput, TOutput, TServices>;
+    /** Version recorded with workflow state and checked during recovery. */
     version?: string;
     /** User-facing description for catalog, code generation, and tool surfaces. */
     description?: string;
@@ -42,12 +43,12 @@ export interface WorkflowDefinition<TInput = unknown, TOutput = unknown, TName e
     inputSchema?: DefinitionSchema<unknown, TInput>;
     /** Optional output schema metadata for introspection; registration validates metadata shape only. */
     outputSchema?: DefinitionSchema<unknown, TOutput>;
-    /** Optional checkpoint migration from a prior workflow version. */
-    migrate?: (checkpoint: unknown, fromVersion: string) => unknown;
     /** Search-attribute schema used to validate indexed workflow metadata. */
     searchAttributes?: SearchAttributeSchema;
     /** Retention policy for terminal workflow records. */
     retention?: RetentionPolicy;
+    /** Start admission policy for this workflow type. */
+    concurrency?: WorkflowConcurrencyOptions<TInput>;
     /**
      * Domain constraints evaluated at every checkpoint commit. When a constraint's
      * `check` returns false, the engine dispatches a `ConstraintViolatedEvent`
@@ -58,4 +59,46 @@ export interface WorkflowDefinition<TInput = unknown, TOutput = unknown, TName e
      * (`workerExecution` option) will silently skip constraint evaluation.
      */
     constraints?: ConstraintDefinition[];
+    /**
+     * Declares a definition-level teardown activity for durable, replay-safe
+     * cancellation cleanup (issue #446) — for example destroying a paid sandbox
+     * when a workflow is cancelled or times out.
+     *
+     * After a `cancelled` or `timed-out` terminal, the engine drives this finalizer
+     * to durable completion, passing the value recorded by
+     * {@link WorkflowContext.setFinalizerState} as its input. That teardown survives
+     * a hard cancel and an engine crash: the engine schedules it durably, claims it
+     * before running, retries failures with backoff, re-drives a stale claim after
+     * recovery, and records a durable dead-letter once the attempt budget is
+     * exhausted. The engine skips the finalizer entirely when the workflow never
+     * recorded any finalizer state, and `completed`/`failed` workflows never run it
+     * (only `cancelled`/`timed-out`).
+     *
+     * **The finalizer runs at least once and must be idempotent.** Bounded retries
+     * and crash-recovery re-drive mean the same payload can reach it more than once,
+     * so destroying an already-destroyed resource must succeed (or no-op) rather
+     * than throw — the same contract as keying a destroy by `sandboxId`.
+     *
+     * A `finalizer` is trusted host code. **Registration** works in both inline and
+     * worker execution modes, and the teardown **runs on the engine host** regardless
+     * of execution mode (and regardless of whether `activityExecution` is configured):
+     * worker execution mode isolates only the workflow generator in a Web Worker.
+     *
+     * Durable teardown, however, only fires when the workflow staged finalizer state
+     * via {@link WorkflowContext.setFinalizerState} before terminating — and that
+     * call works only under inline execution. A handler annotated
+     * `(ctx: WorkflowContext)` type-checks the call in any generator (the static type
+     * declares the method), but at runtime in worker mode the generator's `ctx` is a
+     * reduced worker-side context that does not carry `setFinalizerState` at all, so
+     * the call fails with a `TypeError`; and there is no host-side API to stage the
+     * state on the workflow's behalf. So a worker-mode workflow that needs durable
+     * finalizer teardown must run **inline** to record its state; registering a
+     * `finalizer` on a worker-mode engine no longer throws, but a worker generator
+     * cannot drive it. The inline-only alternatives are `ctx.onCancel`
+     * (in-process, best-effort cleanup that need not survive a crash) and `ctx.saga`
+     * (multi-step ordered rollback) — both are unavailable in worker mode, where
+     * teardown must happen in the workflow body (a `ctx.run` destroy step in a
+     * `try/finally`).
+     */
+    finalizer?: AnyActivityDefinition;
 }

package/dist/core/types/workflow-function.d.ts

@@ -28,7 +28,7 @@ export type { WorkflowDefinition } from './workflow-definition.ts';
  * void engine;
  * ```
  */
-export type WorkflowFunction<TInput = unknown, TOutput = unknown> = (context: WorkflowContext, input: TInput) => AsyncGenerator<unknown, TOutput, unknown>;
+export type WorkflowFunction<TInput = unknown, TOutput = unknown, TServices = unknown> = (context: WorkflowContext<{}, {}, {}, {}, {}, TServices>, input: TInput) => AsyncGenerator<unknown, TOutput, unknown>;
 /**
  * Simplified context for step-based ("progressive disclosure") workflows.
  * Instead of yielding operations via a generator, write a plain `async`
@@ -54,6 +54,23 @@ export type WorkflowFunction<TInput = unknown, TOutput = unknown> = (context: Wo
 export interface StepWorkflowContext {
     readonly workflowId: string;
     readonly signal: AbortSignal;
+    /**
+     * Run `fn` as a durable step. Each call routes through the same machinery as
+     * `ctx.run(...)`: the engine assigns a positional replay slot, persists the
+     * result to the checkpoint, and on crash recovery returns the stored result
+     * without re-running `fn`. `name` is the durable activity label (timeline and
+     * diagnostics only) — replay is keyed by position, not by name.
+     *
+     * Because durability is positional, you must `await` each step before
+     * starting the next: steps must be queued in a deterministic order so the
+     * original run and a recovered run agree on which slot is which. Firing steps
+     * concurrently (so a continuation enqueues further steps in completion order)
+     * can return a wrong cached value after a crash. For parallelism, durable
+     * timers, or signals, use the generator API instead.
+     *
+     * Requires `workflowExecutionMode: 'inline'` (the default); the worker
+     * execution strategy has no step machinery and throws an actionable error.
+     */
     step<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
 }
 /**
@@ -141,17 +158,92 @@ export type WorkflowOperation<TResult> = Generator<unknown, TResult, unknown>;
  */
 export type ChildWorkflowTarget<TInput = unknown, TOutput = unknown> = string | WorkflowFunction<TInput, TOutput> | StepWorkflowFunction<TInput, TOutput>;
 /**
- * Options passed to child workflow invocations within `ctx.pipe`, `ctx.map`,
- * or `ctx.reduce`. Currently accepts an optional `id` to control the child
- * workflow ID.
+ * How a direct `ctx.startChild()` call relates the child workflow to the parent.
+ *
+ * - `'await'` is the default and preserves the original behavior: the parent
+ *   waits for the child result.
+ * - `'abandon'` starts the child and returns a serializable child handle
+ *   reference immediately. The child does not inherit the parent's execution
+ *   state owner.
+ * - `'request-cancel'` starts the child and returns a serializable child handle
+ *   reference immediately. If the parent is cancelled in the same engine
+ *   process, Weft requests cancellation of the child.
+ *
+ * @example
+ * ```ts
+ * import type { ChildWorkflowParentClosePolicy } from '@lostgradient/weft';
+ *
+ * const policy: ChildWorkflowParentClosePolicy = 'abandon';
+ * void policy;
+ * ```
+ */
+export type ChildWorkflowParentClosePolicy = 'await' | 'abandon' | 'request-cancel';
+declare const childWorkflowResultType: unique symbol;
+/**
+ * Serializable reference returned by detached `ctx.startChild()` policies.
+ * It intentionally contains only durable data that can be checkpointed. Use
+ * `engine.getHandle(reference.id)` outside the workflow body to observe status,
+ * signal the child, or await its result.
+ *
+ * @example
+ * ```ts
+ * import type { ChildWorkflowHandle } from '@lostgradient/weft';
+ *
+ * const child: ChildWorkflowHandle<{ receiptId: string }> = { id: 'payment-child' };
+ * const workflowId: string = child.id;
+ * void workflowId;
+ * ```
+ */
+export type ChildWorkflowHandle<TResult = unknown> = {
+    readonly id: string;
+    readonly [childWorkflowResultType]?: TResult;
+};
+/**
+ * Options for child workflow calls that wait for the child result.
+ *
+ * @example
+ * ```ts
+ * import type { AwaitChildWorkflowOptions } from '@lostgradient/weft';
+ *
+ * const options: AwaitChildWorkflowOptions = {
+ *   id: 'payment-child',
+ *   parentClosePolicy: 'await',
+ * };
+ * void options;
+ * ```
  */
-export type ChildWorkflowOptions = {
+export type AwaitChildWorkflowOptions = {
     id?: string;
+    parentClosePolicy?: 'await';
 };
+/**
+ * Options for direct child workflow calls that return a child handle reference.
+ *
+ * @example
+ * ```ts
+ * import type { DetachedChildWorkflowOptions } from '@lostgradient/weft';
+ *
+ * const options: DetachedChildWorkflowOptions = {
+ *   id: 'background-payment',
+ *   parentClosePolicy: 'request-cancel',
+ * };
+ * void options;
+ * ```
+ */
+export type DetachedChildWorkflowOptions = {
+    id?: string;
+    parentClosePolicy: Exclude<ChildWorkflowParentClosePolicy, 'await'>;
+};
+/**
+ * Options passed to direct child workflow invocations via `ctx.startChild()`.
+ * Composition operators (`ctx.pipe`, `ctx.map`, and `ctx.reduce`) are await-only
+ * and accept only {@link AwaitChildWorkflowOptions}.
+ */
+export type ChildWorkflowOptions = AwaitChildWorkflowOptions | DetachedChildWorkflowOptions;
 /**
  * A single stage in a `ctx.pipe(stages, input)` composition chain. Pairs a
- * {@link ChildWorkflowTarget} with optional {@link ChildWorkflowOptions} such
- * as a custom child workflow ID. Use the object form when you need to pass
+ * {@link ChildWorkflowTarget} with optional {@link AwaitChildWorkflowOptions}
+ * such as a custom child workflow ID. Use the object form when you need to pass
  * per-stage options; otherwise a bare {@link ChildWorkflowTarget} also works.
  *
  * @example
@@ -176,7 +268,7 @@ export type ChildWorkflowOptions = {
  */
 export interface WorkflowPipeStage<TInput = unknown, TOutput = unknown> {
     type: ChildWorkflowTarget<TInput, TOutput>;
-    options?: ChildWorkflowOptions;
+    options?: AwaitChildWorkflowOptions;
 }
 /**
  * Union of the two accepted formats for each stage passed to `ctx.pipe`:
@@ -304,7 +396,7 @@ export interface WorkflowReduceInput<TAccumulator, TItem> {
  * void engine;
  * ```
  */
-export interface WorkflowReduceOptions extends Record<string, unknown> {
+export interface WorkflowReduceOptions extends AwaitChildWorkflowOptions {
     idPrefix?: string;
 }
 /**

package/dist/core/types/workflow-log.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The `ctx.log` structured-logging surface: the {@link WorkflowLogger} exposed on
+ * the workflow context, the {@link WorkflowLogRecord} envelope it emits, and the
+ * {@link WorkflowLogLevel} severity. Split out from `workflow-context.ts` so the
+ * context module stays under the line cap and the log types can be re-exported as
+ * a cohesive cluster.
+ *
+ * @module core/types/workflow-log
+ */
+/**
+ * Severity of a {@link WorkflowLogRecord}, ordered `debug < info < warn < error`.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowLogLevel } from '@lostgradient/weft';
+ * const isError = (level: WorkflowLogLevel) => level === 'error';
+ * ```
+ */
+export type WorkflowLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * The structured record a {@link WorkflowLogger} emits for one log call. Envelope
+ * fields (`level`, `message`, `workflowId`, `workflowType`, `timestamp`) are
+ * engine-owned and always present; caller `attributes` nest under their own key so
+ * they can never shadow an envelope field. `timestamp` is wall-clock ms at emit —
+ * observability metadata, never checkpointed or replayed. Type a host sink
+ * installed via `EngineOptions.onLog` with this record.
+ *
+ * @example
+ * ```ts
+ * import { Engine, type WorkflowLogRecord } from '@lostgradient/weft';
+ * const engine = new Engine({ onLog: (r: WorkflowLogRecord) => console.log(r.level, r.message) });
+ * ```
+ */
+export interface WorkflowLogRecord {
+    readonly level: WorkflowLogLevel;
+    readonly message: string;
+    readonly workflowId: string;
+    readonly workflowType: string;
+    readonly timestamp: number;
+    readonly attributes?: Record<string, unknown>;
+}
+/**
+ * The structured logger exposed as `WorkflowContext.log`. Each method emits
+ * a {@link WorkflowLogRecord} to the current process console (`console.debug` /
+ * `console.info` / `console.warn` / `console.error`) with `workflowId`,
+ * `workflowType`, `level`, and `timestamp` auto-attached. Caller-supplied
+ * `attributes` are nested under their own key and cannot overwrite the envelope.
+ *
+ * Replay behavior: a workflow body re-executes from the start on recovery to
+ * rebuild state. Log calls in the already-committed replay window are suppressed,
+ * so a recovered run does not re-emit logs it already emitted. Suppression is
+ * per-position: a log call sitting at a step the engine has already cached is
+ * silenced; a log call at the live frontier emits. This holds in both inline and
+ * worker execution modes.
+ *
+ * Two replay caveats. A log placed *after* the last committed step re-fires on
+ * recovery, because there is no cached step to suppress it (the same caveat
+ * Temporal's workflow logger carries); likewise a workflow with no committed
+ * durable step has no replay position to suppress against, so its logs may
+ * re-emit on recovery. Logs inside `ctx.all` / `ctx.runAll` branches follow that
+ * branch's re-execution semantics.
+ *
+ * A host sink installed via `EngineOptions.onLog` receives records from BOTH execution
+ * modes: inline records directly, and worker-mode records forwarded from the worker
+ * back to the host. When no sink is installed, worker-mode records go to the worker
+ * process console (and inline records to the engine-host console). Inline log
+ * timestamps come from the engine clock; worker-mode timestamps come from the worker
+ * process wall clock.
+ *
+ * Exported so a host can also type a logger it injects through `ctx.services`
+ * (the pre-`ctx.log` pattern).
+ *
+ * @example
+ * ```ts
+ * import { workflow, type WorkflowContext, type WorkflowLogger } from '@lostgradient/weft';
+ *
+ * const myWorkflow = workflow({ name: 'my-workflow' }).execute(async function* (
+ *   ctx: WorkflowContext,
+ * ) {
+ *   ctx.log?.info('workflow started', { attempt: 1 });
+ *   ctx.log?.warn('retrying activity', { reason: 'timeout' });
+ *   // A host logger injected through `ctx.services` can reuse this type:
+ *   const { log } = (ctx.services ?? {}) as { log?: WorkflowLogger };
+ *   log?.error('activity failed', { error: 'ECONNREFUSED' });
+ * });
+ * void myWorkflow;
+ * ```
+ */
+export interface WorkflowLogger {
+    /** Emit a `debug` record. Auto-carries `workflowId`/`workflowType`; suppressed during replay. */
+    debug(message: string, attributes?: Record<string, unknown>): void;
+    /** Emit an `info` record. Auto-carries `workflowId`/`workflowType`; suppressed during replay. */
+    info(message: string, attributes?: Record<string, unknown>): void;
+    /** Emit a `warn` record. Auto-carries `workflowId`/`workflowType`; suppressed during replay. */
+    warn(message: string, attributes?: Record<string, unknown>): void;
+    /** Emit an `error` record. Auto-carries `workflowId`/`workflowType`; suppressed during replay. */
+    error(message: string, attributes?: Record<string, unknown>): void;
+}

package/dist/core/types/workflow-registries.d.ts

@@ -32,6 +32,7 @@ export interface WorkflowRegistry {
 export type WorkflowRegistryEntry = {
     input: unknown;
     output: unknown;
+    services?: unknown;
 };
 declare const defaultWorkflowRegistry: unique symbol;
 declare const defaultActivityTypes: unique symbol;
@@ -73,7 +74,7 @@ export type IsDefaultWorkflowRegistry<TRegistry extends object> = TRegistry exte
  */
 export type AnyWorkflowDefinition = {
     readonly name: string;
-    readonly handler: WorkflowFunction<never> | StepWorkflowFunction<never>;
+    readonly handler: WorkflowFunction<never, unknown, never> | StepWorkflowFunction<never>;
 };
 /**
  * Broad activity-definition constraint used by {@link Engine.create} and
@@ -100,6 +101,14 @@ export type WorkflowInput<TRegistry extends object, TName extends string> = TNam
 export type WorkflowOutput<TRegistry extends object, TName extends string> = TName extends keyof TRegistry ? TRegistry[TName] extends {
     output: infer TOutput;
 } ? TOutput : unknown : unknown;
+export type WorkflowServices<TRegistry extends object, TName extends string> = TName extends keyof TRegistry ? TRegistry[TName] extends {
+    services: infer TServices;
+} ? TServices : unknown : unknown;
+export type WorkflowServicesUnion<TRegistry extends object> = [keyof TRegistry & string] extends [
+    never
+] ? unknown : {
+    [Name in keyof TRegistry & string]: WorkflowServices<TRegistry, Name>;
+}[keyof TRegistry & string];
 export type ActivityArguments<TActivities extends object, TName extends string> = TName extends keyof TActivities ? TActivities[TName] extends () => unknown ? [] : TActivities[TName] extends (input: infer TInput) => unknown ? [input: TInput] : [input: unknown] : [input?: unknown];
 export type ActivityResult<TActivities extends object, TName extends string> = TName extends keyof TActivities ? TActivities[TName] extends (...arguments_: infer _TArguments) => infer TResult ? Awaited<TResult> : unknown : unknown;
 export type RegisteredActivityFunction<TActivities extends object, TName extends string> = TName extends keyof TActivities ? TActivities[TName] extends () => infer TResult ? () => TResult : TActivities[TName] extends (input: infer TInput) => infer TResult ? (input: TInput) => TResult : never : never;
@@ -122,16 +131,18 @@ type MergeDefinitionEntries<TUnion> = [TUnion] extends [never] ? {} : UnionToInt
  * void input;
  * ```
  */
-export type InferWorkflowEntry<TDefinition extends AnyWorkflowDefinition> = TDefinition extends WorkflowDefinition<infer TInput, infer TOutput, infer TName extends string> ? {
+export type InferWorkflowEntry<TDefinition extends AnyWorkflowDefinition> = TDefinition extends WorkflowDefinition<infer TInput, infer TOutput, infer TName extends string, infer TServices> ? {
     [Name in TName]: {
         input: TInput;
         output: TOutput;
+        services: TServices;
     };
 } : never;
-type InferWorkflowEntryForKey<TName extends string, TDefinition extends AnyWorkflowDefinition> = TDefinition extends WorkflowDefinition<infer TInput, infer TOutput> ? {
+type InferWorkflowEntryForKey<TName extends string, TDefinition extends AnyWorkflowDefinition> = TDefinition extends WorkflowDefinition<infer TInput, infer TOutput, string, infer TServices> ? {
     [Name in TName]: {
         input: TInput;
         output: TOutput;
+        services: TServices;
     };
 } : never;
 /**

package/dist/core/types/workflow-registry.d.ts

@@ -1,5 +1,6 @@
 import type { DefinitionSchema } from './definition-schema.ts';
 import type { SearchAttributeSchema } from './search-attributes.ts';
+import type { WorkflowConcurrencyOptions } from './workflow-concurrency.ts';
 /**
  * Read-only metadata exposed by the engine for a registered workflow type.
  *
@@ -28,4 +29,6 @@ export interface RegisteredWorkflowDefinition<TInput = unknown, TOutput = unknow
     outputSchema?: DefinitionSchema<unknown, TOutput>;
     /** Optional search attribute schema used for indexing and runtime validation. */
     searchAttributes?: SearchAttributeSchema;
+    /** Optional start admission policy for this workflow type. */
+    concurrency?: WorkflowConcurrencyOptions<TInput>;
 }