@dudousxd/nestjs-durable-core 0.49.4 → 0.50.0

package/dist/index.d.cts

@@ -161,6 +161,74 @@ declare class InMemoryAdmissionBackend implements AdmissionBackend {
     release(queue: string, _slotId: string): Promise<void>;
 }
 
+/**
+ * Vendored subset of the Standard Schema spec (https://standardschema.dev) — the `~standard`
+ * property protocol implemented by zod 3.24+, valibot, arktype, and others. Vendored (rather than
+ * taken as a dependency) so core stays dependency-free at runtime: this file is types only, erased
+ * entirely by the build. Source: https://github.com/standard-schema/standard-schema (MIT, Colin
+ * McDonnell) — trimmed to the `StandardSchemaV1` shape this package actually consumes (drops the
+ * sibling `StandardTypedV1`/`StandardJSONSchemaV1` specs the upstream package also exports).
+ *
+ * Used to type `@Workflow({ searchAttributes })` (see `WorkflowMeta.searchAttributes` in
+ * `@dudousxd/nestjs-durable` and `SearchAttributesSchema`/`InferSearchAttributes` in `interfaces.ts`)
+ * so a workflow can declare its search-attribute shape with whatever schema library it already uses,
+ * without core taking a hard dependency on any of them.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** A falsy value for `issues` indicates success. */
+        readonly issues?: undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}
+
 /**
  * Cross-package step-name stamp. The `@Step` decorator (`@dudousxd/nestjs-durable`) writes a
  * method's derived routing name under this key; core's `ctx.step` reads it (via {@link stepNameOf})
@@ -337,8 +405,10 @@ interface WorkflowRun {
  * store-backed gateway from the run's signal waiters (`listSignalWaiters`, ONE bulk scan), so the
  * dashboard can NAME the wait in a list row without fetching each run's timeline. `on` is derived from
  * the waiter token's prefix (see `classifyWaiterToken`): `wh:<runId>:<seq>` ⇒ `webhook`, `child:<id>`
- * ⇒ `child`, `event:<name>:…` ⇒ `signal` (name decoded), anything else ⇒ `signal` (the token IS the
- * signal name).
+ * ⇒ `child`, `bp:<runId>:<seq>` ⇒ `breakpoint` (a `ctx.breakpoint` DOES register a signal waiter —
+ * same machinery, `engine.continue` resumes it — so it's classified here, not left to fall through to
+ * the generic `signal` case with the raw token as its ugly display name), `event:<name>:…` ⇒ `signal`
+ * (name decoded), anything else ⇒ `signal` (the token IS the signal name).
  *
  * Deliberately EVENT-only (no timer/step): `wakeAt` alone can't tell a real `ctx.sleep` from the
  * reconcile-fallback `wakeAt` an event/step suspend now carries, and the store exposes no cheap bulk
@@ -347,8 +417,13 @@ interface WorkflowRun {
  * The detail view (which has the timeline) still distinguishes sleep vs in-flight step precisely.
  */
 interface RunWaiting {
-    on: 'signal' | 'webhook' | 'child';
-    /** The token/name the run is parked on — the signal name, webhook token, or awaited child id. */
+    on: 'signal' | 'webhook' | 'child' | 'breakpoint';
+    /**
+     * The token/name the run is parked on — the signal name, webhook token, or awaited child id. For a
+     * breakpoint this is always the literal `'breakpoint'`: the real label (if any) lives on the pending
+     * `breakpoint`/`breakpoint:<label>` checkpoint, which the detail view's timeline already shows —
+     * naming it here would need an extra per-run checkpoint read, defeating the bulk waiter scan.
+     */
     name: string;
 }
 type StepKind = 'local' | 'remote' | 'sleep' | 'signal';
@@ -618,6 +693,38 @@ interface RetentionPolicy {
 }
 /** Typed, queryable per-run data — exact values for `eq`/`ne`, numbers/strings for range ops. */
 type SearchAttributes = Record<string, string | number | boolean>;
+/**
+ * A Standard Schema (https://standardschema.dev — implemented by zod 3.24+, valibot, arktype, …)
+ * whose validated OUTPUT is search-attribute-shaped: flat `string`/`number`/`boolean` values only.
+ * Declared via `@Workflow({ searchAttributes })`, this makes `ctx.upsertSearchAttributes` reject any
+ * write whose merged result doesn't conform. The `Output extends SearchAttributes` bound is enforced
+ * structurally at the declaration site — a schema whose inferred output has a nested object/array
+ * value (e.g. `z.object({ meta: z.object({ ... }) })`) fails to satisfy this type, so it's a
+ * compile-time error to declare it as a `searchAttributes` schema, not a runtime surprise.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ *
+ * const orderAttrs = z.object({
+ *   tier: z.enum(['free', 'pro']),
+ *   amount: z.number(),
+ *   rushOrder: z.boolean().optional(),
+ * });
+ *
+ * @Workflow({ name: 'checkout', searchAttributes: orderAttrs })
+ * class CheckoutWorkflow {
+ *   async run(ctx: WorkflowCtx<InferSearchAttributes<typeof orderAttrs>>, input: CheckoutInput) {
+ *     await ctx.upsertSearchAttributes({ tier: input.tier, amount: input.total });
+ *   }
+ * }
+ * ```
+ */
+type SearchAttributesSchema<A extends SearchAttributes = SearchAttributes> = StandardSchemaV1<unknown, A>;
+/** Infer the validated OUTPUT shape of a {@link SearchAttributesSchema} — the typed attributes a
+ *  workflow declares via `@Workflow({ searchAttributes })`. Feed it straight into `WorkflowCtx<A>`:
+ *  `WorkflowCtx<InferSearchAttributes<typeof mySchema>>`. */
+type InferSearchAttributes<S extends StandardSchemaV1<unknown, SearchAttributes>> = StandardSchemaV1.InferOutput<S>;
 type AttributeOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
 /** One predicate over a run's {@link SearchAttributes}; a {@link RunQuery} ANDs them all. */
 interface AttributeFilter {
@@ -733,6 +840,9 @@ type RunRequestKind = {
 } | {
     kind: 'redispatch';
     runId: string;
+} | {
+    kind: 'waitingFor';
+    runIds: string[];
 };
 /** The control plane's answer to a {@link RunRequest}, correlated by `requestId`. */
 interface RunReply {
@@ -1323,8 +1433,13 @@ type UndoOf<H> = H extends (input: infer I, ...rest: never[]) => infer R ? StepU
 /**
  * The context handed to a workflow function. Every interaction with the outside world goes
  * through it so the engine can checkpoint — the workflow body itself stays deterministic.
+ *
+ * Generic over `A`, the run's {@link SearchAttributes} shape — narrows {@link upsertSearchAttributes}
+ * when a workflow declares a `@Workflow({ searchAttributes })` schema (pass
+ * `WorkflowCtx<InferSearchAttributes<typeof mySchema>>` as the `run` method's ctx type). Defaults to
+ * the untyped `SearchAttributes`, so every existing `WorkflowCtx` usage is unaffected.
  */
-interface WorkflowCtx {
+interface WorkflowCtx<A extends SearchAttributes = SearchAttributes> {
     readonly runId: string;
     /**
      * Run a durable step — always dispatched, always engine-scheduled: the ONE step primitive (no
@@ -1531,8 +1646,16 @@ interface WorkflowCtx {
      * write, not one per turn. Use this instead of injecting the {@link StateStore} to mutate the run
      * you're executing (`@Inject(state-store)` + `store.updateRun(ctx.runId, …)` becomes
      * `ctx.upsertSearchAttributes(…)`).
+     *
+     * When the workflow declares a `@Workflow({ searchAttributes })` schema, the MERGED result (this
+     * run's existing `searchAttributes` shallow-merged with `attrs`) is validated against it before the
+     * write — an invalid merge throws, naming the workflow, the offending key(s), and the schema's
+     * issues. Validation runs once, on the same first-run-only position as the write itself (skipped
+     * entirely on replay, so it's never a source of nondeterminism); it must be synchronous — a schema
+     * whose `validate` returns a `Promise` throws instead of being awaited. No schema declared ⇒
+     * unchanged, unvalidated behavior.
      */
-    upsertSearchAttributes(attrs: SearchAttributes): Promise<void>;
+    upsertSearchAttributes(attrs: Partial<A>): Promise<void>;
     /**
      * Run a checkpointed step **in-process** — the escape hatch from the always-dispatched {@link step}
      * for work that must run inline in the workflow body. Like `step`, its result is a durable checkpoint
@@ -2009,6 +2132,8 @@ declare class WorkflowEngine {
         singleton?: SingletonConfig | undefined;
         executionTimeout?: string | number | undefined;
         validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
+        /** Typed/validated `searchAttributes` shape — see `RegisteredWorkflow.searchAttributesSchema`. */
+        searchAttributesSchema?: SearchAttributesSchema | undefined;
         onEvent?: string[] | undefined;
         eventBatch?: EventBatchConfig | undefined;
         /** Worker group to DISPATCH this workflow's turns to (uniform dispatch). Requires `executor`.
@@ -2832,7 +2957,9 @@ interface DurableTopology {
     /** The tenant's isolation partition name; set only when `role` is 'tenant'. */
     tenant?: string;
 }
-/** A run + its timeline + child ids — the detail view. Mirrors the dashboard's `RunDetail`. */
+/** A run + its timeline + child ids — the detail view. Single source of truth: the dashboard server
+ *  re-exports this instead of re-declaring it, and the dashboard client derives its wire mirror from
+ *  it via {@link WireDates} instead of hand-mirroring field by field. */
 interface RunDetail {
     run: WorkflowRun;
     /** Steps in execution order (local + remote). */
@@ -2840,6 +2967,17 @@ interface RunDetail {
     /** Ids of runs this run spawned (parent→children tree). */
     children: string[];
 }
+/**
+ * Maps every `Date` (and `Date | undefined`) field of `T` to its ISO-string wire form — the shape a
+ * JSON response actually carries once dates cross the wire (`JSON.stringify` already does this
+ * coercion; this just types it). Homomorphic: each field keeps its own optional modifier, so a
+ * required `Date` becomes a required `string` and an optional one stays optional. Lets a consumer
+ * derive its own wire-facing client type from a core server type (e.g. the dashboard's SPA `WorkflowRun`/
+ * `StepCheckpoint`/`RunDetail`) instead of hand-mirroring it field by field and drifting.
+ */
+type WireDates<T> = {
+    [K in keyof T]: T[K] extends Date ? string : T[K] extends Date | undefined ? string | undefined : T[K];
+};
 /**
  * The bounded read/control/stream surface a consumer (e.g. a controller) needs, satisfied by BOTH
  * topologies: the control plane binds a store-backed impl (reuses `DashboardService`); a tenant binds
@@ -2855,6 +2993,17 @@ interface RunGateway {
      *  parked on). The store-backed gateway resolves `waiting`; a proxy relays whatever the control
      *  plane sent. */
     listRuns(query: RunQuery): Promise<RunListItem[]>;
+    /**
+     * Bulk-resolve {@link RunWaiting} for an arbitrary set of run ids — for a consumer with its OWN
+     * filtered/paginated run listing (so it isn't just `listRuns` under another name) that needs to know
+     * which of ITS runs are parked on a breakpoint (or any other event wait) without re-deriving the bulk
+     * waiter scan itself or reaching for raw SQL against `durable_step_checkpoints`. A `Record` (not a
+     * `Map`) because `ProxyRunGateway` serialises the reply over the transport as plain JSON. Entries are
+     * present ONLY for runs currently waiting — an unknown id, a non-suspended id, and a suspended id
+     * parked on something non-event (a bare `ctx.sleep`, an in-flight step) are simply absent, same as a
+     * `listRuns` row with no `waiting`.
+     */
+    waitingFor(runIds: string[]): Promise<Record<string, RunWaiting>>;
     /** Per-group worker health (queue backlog + live worker heartbeats). On the control plane this is
      *  every group; over a tenant proxy the operator scopes it to the tenant's own groups. */
     workerHealth(): Promise<GroupHealth[]>;
@@ -2881,6 +3030,11 @@ interface RunGateway {
  * The token prefix carries the kind — no extra store lookup and no new persisted field. Used by the
  * store-backed run gateway to stamp {@link RunWaiting} onto each listed run so the dashboard can name
  * the wait in a row without fetching that run's timeline.
+ *
+ * `ctx.breakpoint` reuses the signal-waiter machinery (`engine.continue` resumes it via `signal()`
+ * like any other), so without this case it would fall through to the generic `signal` branch with the
+ * raw `bp:<runId>:<seq>` token as its display name — a real bug. Named `'breakpoint'` here instead;
+ * the token carries no separate label to recover cheaply (see {@link RunWaiting.name}).
  */
 declare function classifyWaiterToken(token: string): RunWaiting;
 /**
@@ -3128,6 +3282,35 @@ declare function attributeColumnFor(filter: AttributeFilter): 'numValue' | 'strV
 /** The literal a side-table predicate compares against (booleans → `"true"`/`"false"` strings). */
 declare function attributeOperand(filter: AttributeFilter): string | number;
 
+/**
+ * Read a run's `searchAttributes` through a {@link SearchAttributesSchema}, typed to the schema's
+ * inferred output. **Safe-parse semantics, deliberately lenient** — unlike
+ * `ctx.upsertSearchAttributes` (which is strict: an invalid merge throws), a failed validation here
+ * returns `{}` rather than throwing. This is intentional: `run.searchAttributes` may predate the
+ * schema (an older deploy wrote it under a looser or absent schema, or a run started before this
+ * workflow ever declared one), and a dashboard/read path crashing on old history is worse than it
+ * quietly reporting no typed attributes for that run. Write-time enforcement is what keeps NEW writes
+ * conformant; this is the read-side counterpart for consuming them.
+ *
+ * The schema's `validate` must be synchronous (matching the write-side constraint in
+ * `ctx.upsertSearchAttributes`) — one returning a `Promise` throws with a clear error rather than
+ * being silently awaited or silently treated as a failure.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { readSearchAttributes } from '@dudousxd/nestjs-durable-core';
+ *
+ * const orderAttrs = z.object({ tier: z.enum(['free', 'pro']), amount: z.number() });
+ *
+ * const run = await store.getRun(runId);
+ * const attrs = readSearchAttributes(orderAttrs, run ?? {}); // { tier: 'pro', amount: 42 } | {}
+ * ```
+ */
+declare function readSearchAttributes<S extends SearchAttributesSchema>(schema: S, run: {
+    searchAttributes?: SearchAttributes | undefined;
+}): InferSearchAttributes<S>;
+
 /**
  * Compute the worker group a tenant's run dispatches to. Mirrors the transport's
  * default-is-bare rule (see {@link TransportPool.useNamespace}'s `'default'` no-op): a
@@ -3275,4 +3458,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, StandardSchemaV1, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, readSearchAttributes, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };

package/dist/index.d.ts

@@ -161,6 +161,74 @@ declare class InMemoryAdmissionBackend implements AdmissionBackend {
     release(queue: string, _slotId: string): Promise<void>;
 }
 
+/**
+ * Vendored subset of the Standard Schema spec (https://standardschema.dev) — the `~standard`
+ * property protocol implemented by zod 3.24+, valibot, arktype, and others. Vendored (rather than
+ * taken as a dependency) so core stays dependency-free at runtime: this file is types only, erased
+ * entirely by the build. Source: https://github.com/standard-schema/standard-schema (MIT, Colin
+ * McDonnell) — trimmed to the `StandardSchemaV1` shape this package actually consumes (drops the
+ * sibling `StandardTypedV1`/`StandardJSONSchemaV1` specs the upstream package also exports).
+ *
+ * Used to type `@Workflow({ searchAttributes })` (see `WorkflowMeta.searchAttributes` in
+ * `@dudousxd/nestjs-durable` and `SearchAttributesSchema`/`InferSearchAttributes` in `interfaces.ts`)
+ * so a workflow can declare its search-attribute shape with whatever schema library it already uses,
+ * without core taking a hard dependency on any of them.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** A falsy value for `issues` indicates success. */
+        readonly issues?: undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}
+
 /**
  * Cross-package step-name stamp. The `@Step` decorator (`@dudousxd/nestjs-durable`) writes a
  * method's derived routing name under this key; core's `ctx.step` reads it (via {@link stepNameOf})
@@ -337,8 +405,10 @@ interface WorkflowRun {
  * store-backed gateway from the run's signal waiters (`listSignalWaiters`, ONE bulk scan), so the
  * dashboard can NAME the wait in a list row without fetching each run's timeline. `on` is derived from
  * the waiter token's prefix (see `classifyWaiterToken`): `wh:<runId>:<seq>` ⇒ `webhook`, `child:<id>`
- * ⇒ `child`, `event:<name>:…` ⇒ `signal` (name decoded), anything else ⇒ `signal` (the token IS the
- * signal name).
+ * ⇒ `child`, `bp:<runId>:<seq>` ⇒ `breakpoint` (a `ctx.breakpoint` DOES register a signal waiter —
+ * same machinery, `engine.continue` resumes it — so it's classified here, not left to fall through to
+ * the generic `signal` case with the raw token as its ugly display name), `event:<name>:…` ⇒ `signal`
+ * (name decoded), anything else ⇒ `signal` (the token IS the signal name).
  *
  * Deliberately EVENT-only (no timer/step): `wakeAt` alone can't tell a real `ctx.sleep` from the
  * reconcile-fallback `wakeAt` an event/step suspend now carries, and the store exposes no cheap bulk
@@ -347,8 +417,13 @@ interface WorkflowRun {
  * The detail view (which has the timeline) still distinguishes sleep vs in-flight step precisely.
  */
 interface RunWaiting {
-    on: 'signal' | 'webhook' | 'child';
-    /** The token/name the run is parked on — the signal name, webhook token, or awaited child id. */
+    on: 'signal' | 'webhook' | 'child' | 'breakpoint';
+    /**
+     * The token/name the run is parked on — the signal name, webhook token, or awaited child id. For a
+     * breakpoint this is always the literal `'breakpoint'`: the real label (if any) lives on the pending
+     * `breakpoint`/`breakpoint:<label>` checkpoint, which the detail view's timeline already shows —
+     * naming it here would need an extra per-run checkpoint read, defeating the bulk waiter scan.
+     */
     name: string;
 }
 type StepKind = 'local' | 'remote' | 'sleep' | 'signal';
@@ -618,6 +693,38 @@ interface RetentionPolicy {
 }
 /** Typed, queryable per-run data — exact values for `eq`/`ne`, numbers/strings for range ops. */
 type SearchAttributes = Record<string, string | number | boolean>;
+/**
+ * A Standard Schema (https://standardschema.dev — implemented by zod 3.24+, valibot, arktype, …)
+ * whose validated OUTPUT is search-attribute-shaped: flat `string`/`number`/`boolean` values only.
+ * Declared via `@Workflow({ searchAttributes })`, this makes `ctx.upsertSearchAttributes` reject any
+ * write whose merged result doesn't conform. The `Output extends SearchAttributes` bound is enforced
+ * structurally at the declaration site — a schema whose inferred output has a nested object/array
+ * value (e.g. `z.object({ meta: z.object({ ... }) })`) fails to satisfy this type, so it's a
+ * compile-time error to declare it as a `searchAttributes` schema, not a runtime surprise.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ *
+ * const orderAttrs = z.object({
+ *   tier: z.enum(['free', 'pro']),
+ *   amount: z.number(),
+ *   rushOrder: z.boolean().optional(),
+ * });
+ *
+ * @Workflow({ name: 'checkout', searchAttributes: orderAttrs })
+ * class CheckoutWorkflow {
+ *   async run(ctx: WorkflowCtx<InferSearchAttributes<typeof orderAttrs>>, input: CheckoutInput) {
+ *     await ctx.upsertSearchAttributes({ tier: input.tier, amount: input.total });
+ *   }
+ * }
+ * ```
+ */
+type SearchAttributesSchema<A extends SearchAttributes = SearchAttributes> = StandardSchemaV1<unknown, A>;
+/** Infer the validated OUTPUT shape of a {@link SearchAttributesSchema} — the typed attributes a
+ *  workflow declares via `@Workflow({ searchAttributes })`. Feed it straight into `WorkflowCtx<A>`:
+ *  `WorkflowCtx<InferSearchAttributes<typeof mySchema>>`. */
+type InferSearchAttributes<S extends StandardSchemaV1<unknown, SearchAttributes>> = StandardSchemaV1.InferOutput<S>;
 type AttributeOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
 /** One predicate over a run's {@link SearchAttributes}; a {@link RunQuery} ANDs them all. */
 interface AttributeFilter {
@@ -733,6 +840,9 @@ type RunRequestKind = {
 } | {
     kind: 'redispatch';
     runId: string;
+} | {
+    kind: 'waitingFor';
+    runIds: string[];
 };
 /** The control plane's answer to a {@link RunRequest}, correlated by `requestId`. */
 interface RunReply {
@@ -1323,8 +1433,13 @@ type UndoOf<H> = H extends (input: infer I, ...rest: never[]) => infer R ? StepU
 /**
  * The context handed to a workflow function. Every interaction with the outside world goes
  * through it so the engine can checkpoint — the workflow body itself stays deterministic.
+ *
+ * Generic over `A`, the run's {@link SearchAttributes} shape — narrows {@link upsertSearchAttributes}
+ * when a workflow declares a `@Workflow({ searchAttributes })` schema (pass
+ * `WorkflowCtx<InferSearchAttributes<typeof mySchema>>` as the `run` method's ctx type). Defaults to
+ * the untyped `SearchAttributes`, so every existing `WorkflowCtx` usage is unaffected.
  */
-interface WorkflowCtx {
+interface WorkflowCtx<A extends SearchAttributes = SearchAttributes> {
     readonly runId: string;
     /**
      * Run a durable step — always dispatched, always engine-scheduled: the ONE step primitive (no
@@ -1531,8 +1646,16 @@ interface WorkflowCtx {
      * write, not one per turn. Use this instead of injecting the {@link StateStore} to mutate the run
      * you're executing (`@Inject(state-store)` + `store.updateRun(ctx.runId, …)` becomes
      * `ctx.upsertSearchAttributes(…)`).
+     *
+     * When the workflow declares a `@Workflow({ searchAttributes })` schema, the MERGED result (this
+     * run's existing `searchAttributes` shallow-merged with `attrs`) is validated against it before the
+     * write — an invalid merge throws, naming the workflow, the offending key(s), and the schema's
+     * issues. Validation runs once, on the same first-run-only position as the write itself (skipped
+     * entirely on replay, so it's never a source of nondeterminism); it must be synchronous — a schema
+     * whose `validate` returns a `Promise` throws instead of being awaited. No schema declared ⇒
+     * unchanged, unvalidated behavior.
      */
-    upsertSearchAttributes(attrs: SearchAttributes): Promise<void>;
+    upsertSearchAttributes(attrs: Partial<A>): Promise<void>;
     /**
      * Run a checkpointed step **in-process** — the escape hatch from the always-dispatched {@link step}
      * for work that must run inline in the workflow body. Like `step`, its result is a durable checkpoint
@@ -2009,6 +2132,8 @@ declare class WorkflowEngine {
         singleton?: SingletonConfig | undefined;
         executionTimeout?: string | number | undefined;
         validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
+        /** Typed/validated `searchAttributes` shape — see `RegisteredWorkflow.searchAttributesSchema`. */
+        searchAttributesSchema?: SearchAttributesSchema | undefined;
         onEvent?: string[] | undefined;
         eventBatch?: EventBatchConfig | undefined;
         /** Worker group to DISPATCH this workflow's turns to (uniform dispatch). Requires `executor`.
@@ -2832,7 +2957,9 @@ interface DurableTopology {
     /** The tenant's isolation partition name; set only when `role` is 'tenant'. */
     tenant?: string;
 }
-/** A run + its timeline + child ids — the detail view. Mirrors the dashboard's `RunDetail`. */
+/** A run + its timeline + child ids — the detail view. Single source of truth: the dashboard server
+ *  re-exports this instead of re-declaring it, and the dashboard client derives its wire mirror from
+ *  it via {@link WireDates} instead of hand-mirroring field by field. */
 interface RunDetail {
     run: WorkflowRun;
     /** Steps in execution order (local + remote). */
@@ -2840,6 +2967,17 @@ interface RunDetail {
     /** Ids of runs this run spawned (parent→children tree). */
     children: string[];
 }
+/**
+ * Maps every `Date` (and `Date | undefined`) field of `T` to its ISO-string wire form — the shape a
+ * JSON response actually carries once dates cross the wire (`JSON.stringify` already does this
+ * coercion; this just types it). Homomorphic: each field keeps its own optional modifier, so a
+ * required `Date` becomes a required `string` and an optional one stays optional. Lets a consumer
+ * derive its own wire-facing client type from a core server type (e.g. the dashboard's SPA `WorkflowRun`/
+ * `StepCheckpoint`/`RunDetail`) instead of hand-mirroring it field by field and drifting.
+ */
+type WireDates<T> = {
+    [K in keyof T]: T[K] extends Date ? string : T[K] extends Date | undefined ? string | undefined : T[K];
+};
 /**
  * The bounded read/control/stream surface a consumer (e.g. a controller) needs, satisfied by BOTH
  * topologies: the control plane binds a store-backed impl (reuses `DashboardService`); a tenant binds
@@ -2855,6 +2993,17 @@ interface RunGateway {
      *  parked on). The store-backed gateway resolves `waiting`; a proxy relays whatever the control
      *  plane sent. */
     listRuns(query: RunQuery): Promise<RunListItem[]>;
+    /**
+     * Bulk-resolve {@link RunWaiting} for an arbitrary set of run ids — for a consumer with its OWN
+     * filtered/paginated run listing (so it isn't just `listRuns` under another name) that needs to know
+     * which of ITS runs are parked on a breakpoint (or any other event wait) without re-deriving the bulk
+     * waiter scan itself or reaching for raw SQL against `durable_step_checkpoints`. A `Record` (not a
+     * `Map`) because `ProxyRunGateway` serialises the reply over the transport as plain JSON. Entries are
+     * present ONLY for runs currently waiting — an unknown id, a non-suspended id, and a suspended id
+     * parked on something non-event (a bare `ctx.sleep`, an in-flight step) are simply absent, same as a
+     * `listRuns` row with no `waiting`.
+     */
+    waitingFor(runIds: string[]): Promise<Record<string, RunWaiting>>;
     /** Per-group worker health (queue backlog + live worker heartbeats). On the control plane this is
      *  every group; over a tenant proxy the operator scopes it to the tenant's own groups. */
     workerHealth(): Promise<GroupHealth[]>;
@@ -2881,6 +3030,11 @@ interface RunGateway {
  * The token prefix carries the kind — no extra store lookup and no new persisted field. Used by the
  * store-backed run gateway to stamp {@link RunWaiting} onto each listed run so the dashboard can name
  * the wait in a row without fetching that run's timeline.
+ *
+ * `ctx.breakpoint` reuses the signal-waiter machinery (`engine.continue` resumes it via `signal()`
+ * like any other), so without this case it would fall through to the generic `signal` branch with the
+ * raw `bp:<runId>:<seq>` token as its display name — a real bug. Named `'breakpoint'` here instead;
+ * the token carries no separate label to recover cheaply (see {@link RunWaiting.name}).
  */
 declare function classifyWaiterToken(token: string): RunWaiting;
 /**
@@ -3128,6 +3282,35 @@ declare function attributeColumnFor(filter: AttributeFilter): 'numValue' | 'strV
 /** The literal a side-table predicate compares against (booleans → `"true"`/`"false"` strings). */
 declare function attributeOperand(filter: AttributeFilter): string | number;
 
+/**
+ * Read a run's `searchAttributes` through a {@link SearchAttributesSchema}, typed to the schema's
+ * inferred output. **Safe-parse semantics, deliberately lenient** — unlike
+ * `ctx.upsertSearchAttributes` (which is strict: an invalid merge throws), a failed validation here
+ * returns `{}` rather than throwing. This is intentional: `run.searchAttributes` may predate the
+ * schema (an older deploy wrote it under a looser or absent schema, or a run started before this
+ * workflow ever declared one), and a dashboard/read path crashing on old history is worse than it
+ * quietly reporting no typed attributes for that run. Write-time enforcement is what keeps NEW writes
+ * conformant; this is the read-side counterpart for consuming them.
+ *
+ * The schema's `validate` must be synchronous (matching the write-side constraint in
+ * `ctx.upsertSearchAttributes`) — one returning a `Promise` throws with a clear error rather than
+ * being silently awaited or silently treated as a failure.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { readSearchAttributes } from '@dudousxd/nestjs-durable-core';
+ *
+ * const orderAttrs = z.object({ tier: z.enum(['free', 'pro']), amount: z.number() });
+ *
+ * const run = await store.getRun(runId);
+ * const attrs = readSearchAttributes(orderAttrs, run ?? {}); // { tier: 'pro', amount: 42 } | {}
+ * ```
+ */
+declare function readSearchAttributes<S extends SearchAttributesSchema>(schema: S, run: {
+    searchAttributes?: SearchAttributes | undefined;
+}): InferSearchAttributes<S>;
+
 /**
  * Compute the worker group a tenant's run dispatches to. Mirrors the transport's
  * default-is-bare rule (see {@link TransportPool.useNamespace}'s `'default'` no-op): a
@@ -3275,4 +3458,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, StandardSchemaV1, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, readSearchAttributes, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };