@lostgradient/weft 0.3.0 → 0.5.0

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

@@ -39,7 +39,7 @@ import type { WorkflowDefinition, WorkflowOperation } from './workflow-function.
  * void job;
  * ```
  */
-export type WorkflowGenerator<TInput, TOutput, TActivities extends ActivityMap, TSignals extends SignalMap, TUpdates extends UpdateMap, TQueries extends QueryMap, TSearchAttributes extends SearchAttributeSchema> = (context: WorkflowContextOf<TActivities, TSignals, TUpdates, TQueries, TSearchAttributes>, input: TInput) => AsyncGenerator<unknown, TOutput, unknown>;
+export type WorkflowGenerator<TInput, TOutput, TActivities extends ActivityMap, TSignals extends SignalMap, TUpdates extends UpdateMap, TQueries extends QueryMap, TSearchAttributes extends SearchAttributeSchema, TServices = unknown> = (context: WorkflowContextOf<TActivities, TSignals, TUpdates, TQueries, TSearchAttributes, TServices>, input: TInput) => AsyncGenerator<unknown, TOutput, unknown>;
 /**
  * Convenience alias for the workflow-scoped `WorkflowContext` projection. The
  * underlying `WorkflowContext` interface accepts the same five generic
@@ -53,7 +53,7 @@ export type WorkflowGenerator<TInput, TOutput, TActivities extends ActivityMap,
  * callable overloads match instead. This permissive path is current API — it is
  * how untyped, ad-hoc-name authoring is supported, not a compatibility shim.
  */
-export type WorkflowContextOf<TActivities extends ActivityMap = ActivityMap, TSignals extends SignalMap = SignalMap, TUpdates extends UpdateMap = UpdateMap, TQueries extends QueryMap = QueryMap, TSearchAttributes extends SearchAttributeSchema = SearchAttributeSchema> = WorkflowContext<TActivities, TSignals, TUpdates, TQueries, TSearchAttributes>;
+export type WorkflowContextOf<TActivities extends ActivityMap = ActivityMap, TSignals extends SignalMap = SignalMap, TUpdates extends UpdateMap = UpdateMap, TQueries extends QueryMap = QueryMap, TSearchAttributes extends SearchAttributeSchema = SearchAttributeSchema, TServices = unknown> = WorkflowContext<TActivities, TSignals, TUpdates, TQueries, TSearchAttributes, TServices>;
 /**
  * Tracks which `WorkflowBuilder` chain methods have already been called. Each
  * call flips its flag from `false` to `true`; the method's type becomes `never`
@@ -82,6 +82,7 @@ export interface BuilderState {
     readonly updates: boolean;
     readonly queries: boolean;
     readonly searchAttributes: boolean;
+    readonly services?: boolean | undefined;
 }
 /**
  * Initial builder state — every chain method is still available. A fresh
@@ -102,6 +103,7 @@ export interface InitialBuilderState {
     readonly updates: false;
     readonly queries: false;
     readonly searchAttributes: false;
+    readonly services?: false | undefined;
 }
 /**
  * Flip one builder-state flag from `false` to `true`. Each chain method on
@@ -118,7 +120,9 @@ export interface InitialBuilderState {
  * void _check;
  * ```
  */
-export type MarkBuilderState<S extends BuilderState, K extends keyof BuilderState> = {
+export type MarkBuilderState<S extends BuilderState, K extends keyof BuilderState> = K extends 'services' ? Omit<S, 'services'> & {
+    readonly services: true;
+} : {
     readonly [P in keyof S]: P extends K ? true : S[P];
 };
 declare const workflowAlreadyRegisteredBrand: unique symbol;
@@ -176,7 +180,7 @@ export interface WorkflowAlreadyRegistered<TName extends string> {
  * void welcome;
  * ```
  */
-export interface WorkflowBuilder<TName extends string, TActivities extends ActivityMap, TSignals extends SignalMap, TUpdates extends UpdateMap, TQueries extends QueryMap, TSearchAttributes extends SearchAttributeSchema, TState extends BuilderState> {
+export interface WorkflowBuilder<TName extends string, TActivities extends ActivityMap, TSignals extends SignalMap, TUpdates extends UpdateMap, TQueries extends QueryMap, TSearchAttributes extends SearchAttributeSchema, TState extends BuilderState, TServices = unknown> {
     /**
      * Declare the activity table this workflow can dispatch with
      * `ctx.run('name', input)`. The outer object key is the canonical activity
@@ -196,7 +200,7 @@ export interface WorkflowBuilder<TName extends string, TActivities extends Activ
      * void welcome;
      * ```
      */
-    activities: TState['activities'] extends true ? never : <TInput extends ActivityMapInput>(map: TInput) => WorkflowBuilder<TName, NormalizeActivities<TInput>, TSignals, TUpdates, TQueries, TSearchAttributes, MarkBuilderState<TState, 'activities'>>;
+    activities: TState['activities'] extends true ? never : <TInput extends ActivityMapInput>(map: TInput) => WorkflowBuilder<TName, NormalizeActivities<TInput>, TSignals, TUpdates, TQueries, TSearchAttributes, MarkBuilderState<TState, 'activities'>, TServices>;
     /**
      * Declare the signals this workflow accepts so `ctx.waitForSignal('name')`
      * autocompletes and types the payload. Type-safety and introspection
@@ -215,7 +219,7 @@ export interface WorkflowBuilder<TName extends string, TActivities extends Activ
      * void approval;
      * ```
      */
-    signals: TState['signals'] extends true ? never : <TInput extends SignalMap>(map: TInput) => WorkflowBuilder<TName, TActivities, TInput, TUpdates, TQueries, TSearchAttributes, MarkBuilderState<TState, 'signals'>>;
+    signals: TState['signals'] extends true ? never : <TInput extends SignalMap>(map: TInput) => WorkflowBuilder<TName, TActivities, TInput, TUpdates, TQueries, TSearchAttributes, MarkBuilderState<TState, 'signals'>, TServices>;
     /**
      * Declare the request-response update handlers this workflow accepts.
      * Type-safety and introspection metadata only — the update-dispatch path
@@ -231,7 +235,7 @@ export interface WorkflowBuilder<TName extends string, TActivities extends Activ
      * void order;
      * ```
      */
-    updates: TState['updates'] extends true ? never : <TInput extends UpdateMap>(map: TInput) => WorkflowBuilder<TName, TActivities, TSignals, TInput, TQueries, TSearchAttributes, MarkBuilderState<TState, 'updates'>>;
+    updates: TState['updates'] extends true ? never : <TInput extends UpdateMap>(map: TInput) => WorkflowBuilder<TName, TActivities, TSignals, TInput, TQueries, TSearchAttributes, MarkBuilderState<TState, 'updates'>, TServices>;
     /**
      * Declare the read-only query handlers this workflow accepts. Type-safety
      * and introspection metadata only — `.queries` does not introduce new
@@ -247,7 +251,7 @@ export interface WorkflowBuilder<TName extends string, TActivities extends Activ
      * void job;
      * ```
      */
-    queries: TState['queries'] extends true ? never : <TInput extends QueryMap>(map: TInput) => WorkflowBuilder<TName, TActivities, TSignals, TUpdates, TInput, TSearchAttributes, MarkBuilderState<TState, 'queries'>>;
+    queries: TState['queries'] extends true ? never : <TInput extends QueryMap>(map: TInput) => WorkflowBuilder<TName, TActivities, TSignals, TUpdates, TInput, TSearchAttributes, MarkBuilderState<TState, 'queries'>, TServices>;
     /**
      * Declare the search-attribute schema this workflow populates via
      * `ctx.setAttribute('key', value)`. Each entry pins the attribute's value
@@ -267,7 +271,32 @@ export interface WorkflowBuilder<TName extends string, TActivities extends Activ
      * void order;
      * ```
      */
-    searchAttributes: TState['searchAttributes'] extends true ? never : <TInput extends SearchAttributeSchema>(schema: TInput) => WorkflowBuilder<TName, TActivities, TSignals, TUpdates, TQueries, TInput, MarkBuilderState<TState, 'searchAttributes'>>;
+    searchAttributes: TState['searchAttributes'] extends true ? never : <TInput extends SearchAttributeSchema>(schema: TInput) => WorkflowBuilder<TName, TActivities, TSignals, TUpdates, TQueries, TInput, MarkBuilderState<TState, 'searchAttributes'>, TServices>;
+    /**
+     * Declare the per-run services type exposed at `ctx.services`. This is a
+     * type-only marker: services remain supplied at launch through
+     * `engine.start(type, input, { services })` and re-provided on recovery by
+     * `EngineOptions.resolveWorkflowServices`. Calling `.services` twice before
+     * `.execute()` is a type error and throws `WorkflowBuilderError` at runtime.
+     *
+     * @example
+     * ```ts
+     * import { workflow } from '@lostgradient/weft';
+     *
+     * interface Services {
+     *   repository: { load(id: string): Promise<string> };
+     * }
+     *
+     * const job = workflow({ name: 'job' })
+     *   .services<Services>()
+     *   .execute(async function* (ctx, id: string) {
+     *     const services = ctx.services;
+     *     return services === undefined ? id : yield* ctx.run(() => services.repository.load(id));
+     *   });
+     * void job;
+     * ```
+     */
+    services: TState['services'] extends true ? never : <TInput>() => WorkflowBuilder<TName, TActivities, TSignals, TUpdates, TQueries, TSearchAttributes, MarkBuilderState<TState, 'services'>, TInput>;
     /**
      * Seal the builder and produce a `BuiltWorkflowDefinition`. The generator's
      * `input` and `output` types are re-inferred from `fn`'s signature, so the
@@ -288,7 +317,7 @@ export interface WorkflowBuilder<TName extends string, TActivities extends Activ
      * void welcome;
      * ```
      */
-    execute<TInput, TOutput>(fn: WorkflowGenerator<TInput, TOutput, TActivities, TSignals, TUpdates, TQueries, TSearchAttributes>): BuiltWorkflowDefinition<TInput, Awaited<TOutput>, TName, TActivities, TSignals, TUpdates, TQueries, TSearchAttributes>;
+    execute<TInput, TOutput>(fn: WorkflowGenerator<TInput, TOutput, TActivities, TSignals, TUpdates, TQueries, TSearchAttributes, TServices>): BuiltWorkflowDefinition<TInput, Awaited<TOutput>, TName, TActivities, TSignals, TUpdates, TQueries, TSearchAttributes, TServices>;
 }
 /**
  * The `WorkflowDefinition` returned by `.execute(fn)`. Carries the normalised
@@ -319,7 +348,7 @@ export interface WorkflowBuilder<TName extends string, TActivities extends Activ
  * void built;
  * ```
  */
-export interface BuiltWorkflowDefinition<TInput, TOutput, TName extends string, TActivities extends ActivityMap, TSignals extends SignalMap, TUpdates extends UpdateMap, TQueries extends QueryMap, TSearchAttributes extends SearchAttributeSchema> extends WorkflowDefinition<TInput, TOutput, TName> {
+export interface BuiltWorkflowDefinition<TInput, TOutput, TName extends string, TActivities extends ActivityMap, TSignals extends SignalMap, TUpdates extends UpdateMap, TQueries extends QueryMap, TSearchAttributes extends SearchAttributeSchema, TServices = unknown> extends WorkflowDefinition<TInput, TOutput, TName, TServices> {
     readonly activities: Readonly<Record<string, Readonly<ActivityDefinition>>>;
     readonly signals: Readonly<Record<string, Readonly<SignalDefinition<unknown>>>>;
     readonly updates: Readonly<Record<string, Readonly<UpdateDefinition>>>;
@@ -335,6 +364,8 @@ export interface BuiltWorkflowDefinition<TInput, TOutput, TName extends string,
     readonly _queries?: TQueries;
     /** Phantom marker for the search-attribute schema. Not present at runtime. */
     readonly _searchAttributes?: TSearchAttributes;
+    /** Phantom marker for the per-run services type. Not present at runtime. */
+    readonly _services?: TServices;
 }
 /**
  * Re-exported so Phase 2 (`workflow()` runtime rewrite) and Phase 3 (engine

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

@@ -0,0 +1,39 @@
+type WorkflowConcurrencyKeyResolver<TInput> = {
+    resolve(input: TInput): string;
+}['resolve'];
+/**
+ * Workflow-level start admission policy. When present on a workflow definition,
+ * the engine admits at most `max` non-terminal runs for the same partition.
+ *
+ * @example
+ * ```ts
+ * import { workflow, type WorkflowConcurrencyOptions } from '@lostgradient/weft';
+ *
+ * type OrderInput = { customerId: string };
+ *
+ * const concurrency: WorkflowConcurrencyOptions<OrderInput> = {
+ *   max: 3,
+ *   key: (input) => input.customerId,
+ * };
+ *
+ * const processOrder = workflow({ name: 'process-order', concurrency }).execute(
+ *   async function* () {
+ *     return 'done';
+ *   },
+ * );
+ * void processOrder;
+ * ```
+ */
+export interface WorkflowConcurrencyOptions<TInput = unknown> {
+    /**
+     * Maximum number of non-terminal runs admitted for the workflow type or
+     * partition key. Excess starts are rejected immediately.
+     */
+    max: number;
+    /**
+     * Optional partition key resolver. When omitted, the limit applies to the
+     * workflow type as a whole.
+     */
+    key?: WorkflowConcurrencyKeyResolver<TInput>;
+}
+export {};

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`
@@ -158,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
@@ -193,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`:
@@ -321,7 +396,7 @@ export interface WorkflowReduceInput<TAccumulator, TItem> {
  * void engine;
  * ```
  */
-export interface WorkflowReduceOptions extends Record<string, unknown> {
+export interface WorkflowReduceOptions extends AwaitChildWorkflowOptions {
     idPrefix?: string;
 }
 /**