@dudousxd/nestjs-durable-core 0.82.0 → 0.83.0

package/dist/index.d.cts

@@ -2877,8 +2877,8 @@ interface WorkflowCtx<A extends SearchAttributes = SearchAttributes> {
      *
      * 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
+     * write — an invalid merge throws a `SchemaValidationError` (code `schema_validation`, never
+     * retried) naming the workflow, with 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.
@@ -3827,7 +3827,10 @@ declare function liveHandoff<C extends {
     seq: number;
     name: string;
 }>(runId: string, checkpoints: readonly C[]): C | undefined;
-/** The route a failure takes: the one for its exact code, else the catch-all, else none. */
+/**
+ * The route a failure takes: the one for its exact code, else (for an `invalid_input` /
+ * `invalid_output` failure) a `schema_validation` route, else the catch-all, else none.
+ */
 declare function routeFor(routes: OnErrorRoute[] | undefined, error: StepError): OnErrorRoute | undefined;
 /** Reject two routes for one code, or two catch-alls — ambiguous config, caught at registration. */
 declare function assertRoutes(workflow: string, routes: OnErrorRoute[]): void;
@@ -4847,6 +4850,8 @@ declare class WorkflowEngine {
      * between this call and `drain()` (other hooks, the HTTP server closing) never is. Calls add up.
      */
     beginDrain(spentMs?: number): void;
+    /** True once {@link beginDrain} (or {@link drain}) has been called. */
+    isDraining(): boolean;
     /**
      * Graceful shutdown: stop picking up new runs (recovery/timer become no-ops) and wait for
      * in-flight executions to settle, up to `timeoutMs`. Call from your app's shutdown hook so a
@@ -5966,6 +5971,44 @@ declare class FatalError extends Error {
     readonly retryable = false;
     constructor(message: string, code?: string, details?: unknown);
 }
+/** One schema issue in JSON-safe form: its message and the path segments, as strings. */
+interface SchemaIssue {
+    message: string;
+    path: string[];
+}
+/**
+ * The code a {@link SchemaValidationError} carries: `invalid_input` for an input schema (a
+ * workflow's or a step's), `invalid_output` for an output schema, `schema_validation` for anything
+ * else (a typed `searchAttributes` write). The same codes `@adonis-agora/durable` uses.
+ */
+type SchemaValidationCode = 'invalid_input' | 'invalid_output' | 'schema_validation';
+/**
+ * Thrown when a value fails a schema the app declared: `@Workflow({ input, output })`,
+ * `@Step({ input, output })`, or the workflow's typed `searchAttributes`. A {@link FatalError}, so it
+ * is NOT retried — retrying cannot fix a value that doesn't match its schema. Its `code` says which
+ * schema rejected the value ({@link SchemaValidationCode}). `issues` (also `details.issues`, so it
+ * survives the transport to the run's error and an onError handler's input) lists every issue with
+ * a JSON-safe `path`. Route one code with `onError: [{ code: 'invalid_input', workflow }]`, or all
+ * three with `onError: [{ code: SchemaValidationError, workflow }]`: its `static code`,
+ * `schema_validation`, also catches an `invalid_input` or `invalid_output` no route of its own
+ * matches. Same class, codes, message and `details` as `@adonis-agora/durable`.
+ */
+declare class SchemaValidationError extends FatalError {
+    static readonly code = "schema_validation";
+    readonly issues: SchemaIssue[];
+    /**
+     * @param label What was validated, e.g. `workflow "checkout" input`; the message is
+     *   `invalid <label>: <path>: <message>; …`.
+     * @param summary Overrides the `<path>: <message>; …` part, for issues whose messages already
+     *   name their field (class-validator's `orderId must be a string`).
+     */
+    constructor(label: string, issues: ReadonlyArray<{
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | {
+            readonly key: PropertyKey;
+        }> | undefined;
+    }>, code?: SchemaValidationCode, summary?: string);
+}
 /**
  * Thrown by `start` when a run would exceed its concurrency quota: `active` runs sharing the quota
  * `key` are already in flight (in the quota's counted statuses) and the `limit` is `limit`. Nothing
@@ -6634,11 +6677,20 @@ type Subscribable = {
  */
 declare function collectMetrics(engine: Subscribable): MetricsCollector;
 
-interface ScheduledWorkflow {
+/**
+ * A recurring start of `workflow`, fired on a fixed interval or a cron.
+ *
+ * `workflow` is a registered name or a `@Workflow` class. A class types `input` against its `run`;
+ * annotate the schedule to get that check, as in
+ * `const nightly: ScheduledWorkflow<typeof ReportWorkflow> = { workflow: ReportWorkflow, … }`.
+ */
+interface ScheduledWorkflow<W extends WorkflowRef = WorkflowRef> {
     /** Stable key identifying this schedule — part of the deterministic run id. */
     key: string;
-    workflow: string;
-    input?: unknown;
+    /** The workflow to start: a registered name (any runtime) or a `@Workflow` class. */
+    workflow: W;
+    /** The input every run starts with — typed against `run` when `workflow` is a class. */
+    input?: WorkflowInputOf<W>;
     /** Start one run every `everyMs`. Mutually exclusive with `cron`. */
     everyMs?: number;
     /**
@@ -6676,6 +6728,16 @@ interface ScheduledWorkflow {
     backfill?: {
         maxCatchup: number;
     };
+    /**
+     * The namespace this schedule's runs are stamped with, overriding the ticking engine's own. Opt-in;
+     * absent = the run gets the namespace of whichever engine fired it.
+     *
+     * The run id is a time bucket, so the instance that wins the race to fire a window decides which
+     * namespace (worker pool) the run lands in. When the workflow can only run in one pool — its steps
+     * need a capability only that pool's workers have — pin it here, so whoever fires the window, the
+     * run is stamped for (and only picked up by) that pool.
+     */
+    namespace?: string;
 }
 /** Injectable dispatch-path effects (kept out of the deterministic run-id logic). Defaults to real
  *  `Math.random` + `setTimeout`; overridden in tests so jitter is deterministic and instant. */
@@ -6697,14 +6759,23 @@ declare function prevCronFireMs(expr: string, nowMs: number, timezone?: string):
  * schedule is next due.
  */
 declare function nextCronFireMs(expr: string, afterMs: number, timezone?: string): number;
+/**
+ * The deterministic, idempotent run id for a schedule at `nowMs` — its current fire window
+ * (`sched:<key>:<bucket>`, the bucket being a fixed-interval index or the cron fire time). Pass the
+ * same `ScheduledWorkflow` you registered to look a window's run up, e.g.
+ * `engine.getRun(scheduleRunIdAt(dailyReport, Date.now()))`, rather than rebuilding the id by hand.
+ */
+declare function scheduleRunIdAt(s: ScheduledWorkflow, nowMs: number): string;
 /**
  * Start each schedule's current-window run. The run id is the time bucket (a fixed-interval index,
  * or the cron fire time) and `engine.start` is idempotent, so firing this on an interval — or
  * racing two instances on the same tick — starts **each window exactly once**. Wire it to a
- * `setInterval`, the durable timer poller, or `@nestjs/schedule`. Returns the run ids for the
- * current windows.
+ * `setInterval`, the durable timer poller, or `@nestjs/schedule`. Returns the run ids this call
+ * started: a window that already has a run is not started or returned again, and once this process
+ * has seen a window's run exist, later calls in that window skip it without a store read or a
+ * jitter sleep.
  */
-declare function runSchedules(engine: Pick<WorkflowEngine, 'start' | 'getRun'>, schedules: readonly ScheduledWorkflow[], nowMs: number, opts?: RunSchedulesOptions): Promise<string[]>;
+declare function runSchedules(engine: Pick<WorkflowEngine, 'start' | 'getRun'> & Partial<Pick<WorkflowEngine, 'isDraining'>>, schedules: readonly ScheduledWorkflow[], nowMs: number, opts?: RunSchedulesOptions): Promise<string[]>;
 
 /**
  * A {@link StepLogger} that appends to `events`, stamping each line with `now()`. Shared by the
@@ -7117,4 +7188,4 @@ declare function singletonAdmissionDenialPatch(runs: WorkflowRun[], runId: strin
     updatedAt: Date;
 } | undefined;
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CHILD_EDGE_PREFIXES, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type CheckpointAggregatingStore, type CheckpointNameKind, type CheckpointQuery, type CheckpointStat, type ChildCallOptions, type ChildWait, CodecStateStore, type CodecStateStoreOptions, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DEFAULT_STALLED_AFTER_MS, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, ENTITY_WORKFLOW, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, type EntityWorkflowHost, EventAccumulators, type EventBatchConfig, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, type FindStalledRunsOptions, GatherError, type GatherItemFailure, type GroupHealth, HANDOFF_SEQ_BASE, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type ListStalledRunsOptions, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type OnErrorInput, type OnErrorRoute, type OwnedLeaseReclaim, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, RUN_HISTORY_FIXTURE_VERSION, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDetailOptions, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, SINGLETON_ACTIVE_STATUSES, SINGLETON_ADMITTED_TAG, SINGLETON_RESERVED_TAGS, SINGLETON_TRACKED_TAG, STATE_STORE, STATE_STORE_CANONICAL, SUMMARY_CHILD_LIMIT, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, type Settled, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StalePendingStep, type StalledRunInfo, 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 StepScope, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, aggregatesCheckpoints, announcementsOf, applyAttributeQuery, assertConcurrency, assertRoutes, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, legacySingletonHolders, listSignalWaitersOfRuns, liveHandoff, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, queryCheckpointsOf, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, retiredHandoffName, routeFor, runDetailEtag, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduledRunId, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantGroup, useDurableExecution, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CHILD_EDGE_PREFIXES, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type CheckpointAggregatingStore, type CheckpointNameKind, type CheckpointQuery, type CheckpointStat, type ChildCallOptions, type ChildWait, CodecStateStore, type CodecStateStoreOptions, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DEFAULT_STALLED_AFTER_MS, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, ENTITY_WORKFLOW, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, type EntityWorkflowHost, EventAccumulators, type EventBatchConfig, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, type FindStalledRunsOptions, GatherError, type GatherItemFailure, type GroupHealth, HANDOFF_SEQ_BASE, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type ListStalledRunsOptions, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type OnErrorInput, type OnErrorRoute, type OwnedLeaseReclaim, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, RUN_HISTORY_FIXTURE_VERSION, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDetailOptions, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, SINGLETON_ACTIVE_STATUSES, SINGLETON_ADMITTED_TAG, SINGLETON_RESERVED_TAGS, SINGLETON_TRACKED_TAG, STATE_STORE, STATE_STORE_CANONICAL, SUMMARY_CHILD_LIMIT, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduledWorkflow, type SchemaIssue, type SchemaValidationCode, SchemaValidationError, type SearchAttributes, type SearchAttributesSchema, type Settled, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StalePendingStep, type StalledRunInfo, 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 StepScope, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, aggregatesCheckpoints, announcementsOf, applyAttributeQuery, assertConcurrency, assertRoutes, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, legacySingletonHolders, listSignalWaitersOfRuns, liveHandoff, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, queryCheckpointsOf, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, retiredHandoffName, routeFor, runDetailEtag, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduleRunIdAt, scheduledRunId, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantGroup, useDurableExecution, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };

package/dist/index.d.ts

@@ -2877,8 +2877,8 @@ interface WorkflowCtx<A extends SearchAttributes = SearchAttributes> {
      *
      * 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
+     * write — an invalid merge throws a `SchemaValidationError` (code `schema_validation`, never
+     * retried) naming the workflow, with 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.
@@ -3827,7 +3827,10 @@ declare function liveHandoff<C extends {
     seq: number;
     name: string;
 }>(runId: string, checkpoints: readonly C[]): C | undefined;
-/** The route a failure takes: the one for its exact code, else the catch-all, else none. */
+/**
+ * The route a failure takes: the one for its exact code, else (for an `invalid_input` /
+ * `invalid_output` failure) a `schema_validation` route, else the catch-all, else none.
+ */
 declare function routeFor(routes: OnErrorRoute[] | undefined, error: StepError): OnErrorRoute | undefined;
 /** Reject two routes for one code, or two catch-alls — ambiguous config, caught at registration. */
 declare function assertRoutes(workflow: string, routes: OnErrorRoute[]): void;
@@ -4847,6 +4850,8 @@ declare class WorkflowEngine {
      * between this call and `drain()` (other hooks, the HTTP server closing) never is. Calls add up.
      */
     beginDrain(spentMs?: number): void;
+    /** True once {@link beginDrain} (or {@link drain}) has been called. */
+    isDraining(): boolean;
     /**
      * Graceful shutdown: stop picking up new runs (recovery/timer become no-ops) and wait for
      * in-flight executions to settle, up to `timeoutMs`. Call from your app's shutdown hook so a
@@ -5966,6 +5971,44 @@ declare class FatalError extends Error {
     readonly retryable = false;
     constructor(message: string, code?: string, details?: unknown);
 }
+/** One schema issue in JSON-safe form: its message and the path segments, as strings. */
+interface SchemaIssue {
+    message: string;
+    path: string[];
+}
+/**
+ * The code a {@link SchemaValidationError} carries: `invalid_input` for an input schema (a
+ * workflow's or a step's), `invalid_output` for an output schema, `schema_validation` for anything
+ * else (a typed `searchAttributes` write). The same codes `@adonis-agora/durable` uses.
+ */
+type SchemaValidationCode = 'invalid_input' | 'invalid_output' | 'schema_validation';
+/**
+ * Thrown when a value fails a schema the app declared: `@Workflow({ input, output })`,
+ * `@Step({ input, output })`, or the workflow's typed `searchAttributes`. A {@link FatalError}, so it
+ * is NOT retried — retrying cannot fix a value that doesn't match its schema. Its `code` says which
+ * schema rejected the value ({@link SchemaValidationCode}). `issues` (also `details.issues`, so it
+ * survives the transport to the run's error and an onError handler's input) lists every issue with
+ * a JSON-safe `path`. Route one code with `onError: [{ code: 'invalid_input', workflow }]`, or all
+ * three with `onError: [{ code: SchemaValidationError, workflow }]`: its `static code`,
+ * `schema_validation`, also catches an `invalid_input` or `invalid_output` no route of its own
+ * matches. Same class, codes, message and `details` as `@adonis-agora/durable`.
+ */
+declare class SchemaValidationError extends FatalError {
+    static readonly code = "schema_validation";
+    readonly issues: SchemaIssue[];
+    /**
+     * @param label What was validated, e.g. `workflow "checkout" input`; the message is
+     *   `invalid <label>: <path>: <message>; …`.
+     * @param summary Overrides the `<path>: <message>; …` part, for issues whose messages already
+     *   name their field (class-validator's `orderId must be a string`).
+     */
+    constructor(label: string, issues: ReadonlyArray<{
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | {
+            readonly key: PropertyKey;
+        }> | undefined;
+    }>, code?: SchemaValidationCode, summary?: string);
+}
 /**
  * Thrown by `start` when a run would exceed its concurrency quota: `active` runs sharing the quota
  * `key` are already in flight (in the quota's counted statuses) and the `limit` is `limit`. Nothing
@@ -6634,11 +6677,20 @@ type Subscribable = {
  */
 declare function collectMetrics(engine: Subscribable): MetricsCollector;
 
-interface ScheduledWorkflow {
+/**
+ * A recurring start of `workflow`, fired on a fixed interval or a cron.
+ *
+ * `workflow` is a registered name or a `@Workflow` class. A class types `input` against its `run`;
+ * annotate the schedule to get that check, as in
+ * `const nightly: ScheduledWorkflow<typeof ReportWorkflow> = { workflow: ReportWorkflow, … }`.
+ */
+interface ScheduledWorkflow<W extends WorkflowRef = WorkflowRef> {
     /** Stable key identifying this schedule — part of the deterministic run id. */
     key: string;
-    workflow: string;
-    input?: unknown;
+    /** The workflow to start: a registered name (any runtime) or a `@Workflow` class. */
+    workflow: W;
+    /** The input every run starts with — typed against `run` when `workflow` is a class. */
+    input?: WorkflowInputOf<W>;
     /** Start one run every `everyMs`. Mutually exclusive with `cron`. */
     everyMs?: number;
     /**
@@ -6676,6 +6728,16 @@ interface ScheduledWorkflow {
     backfill?: {
         maxCatchup: number;
     };
+    /**
+     * The namespace this schedule's runs are stamped with, overriding the ticking engine's own. Opt-in;
+     * absent = the run gets the namespace of whichever engine fired it.
+     *
+     * The run id is a time bucket, so the instance that wins the race to fire a window decides which
+     * namespace (worker pool) the run lands in. When the workflow can only run in one pool — its steps
+     * need a capability only that pool's workers have — pin it here, so whoever fires the window, the
+     * run is stamped for (and only picked up by) that pool.
+     */
+    namespace?: string;
 }
 /** Injectable dispatch-path effects (kept out of the deterministic run-id logic). Defaults to real
  *  `Math.random` + `setTimeout`; overridden in tests so jitter is deterministic and instant. */
@@ -6697,14 +6759,23 @@ declare function prevCronFireMs(expr: string, nowMs: number, timezone?: string):
  * schedule is next due.
  */
 declare function nextCronFireMs(expr: string, afterMs: number, timezone?: string): number;
+/**
+ * The deterministic, idempotent run id for a schedule at `nowMs` — its current fire window
+ * (`sched:<key>:<bucket>`, the bucket being a fixed-interval index or the cron fire time). Pass the
+ * same `ScheduledWorkflow` you registered to look a window's run up, e.g.
+ * `engine.getRun(scheduleRunIdAt(dailyReport, Date.now()))`, rather than rebuilding the id by hand.
+ */
+declare function scheduleRunIdAt(s: ScheduledWorkflow, nowMs: number): string;
 /**
  * Start each schedule's current-window run. The run id is the time bucket (a fixed-interval index,
  * or the cron fire time) and `engine.start` is idempotent, so firing this on an interval — or
  * racing two instances on the same tick — starts **each window exactly once**. Wire it to a
- * `setInterval`, the durable timer poller, or `@nestjs/schedule`. Returns the run ids for the
- * current windows.
+ * `setInterval`, the durable timer poller, or `@nestjs/schedule`. Returns the run ids this call
+ * started: a window that already has a run is not started or returned again, and once this process
+ * has seen a window's run exist, later calls in that window skip it without a store read or a
+ * jitter sleep.
  */
-declare function runSchedules(engine: Pick<WorkflowEngine, 'start' | 'getRun'>, schedules: readonly ScheduledWorkflow[], nowMs: number, opts?: RunSchedulesOptions): Promise<string[]>;
+declare function runSchedules(engine: Pick<WorkflowEngine, 'start' | 'getRun'> & Partial<Pick<WorkflowEngine, 'isDraining'>>, schedules: readonly ScheduledWorkflow[], nowMs: number, opts?: RunSchedulesOptions): Promise<string[]>;
 
 /**
  * A {@link StepLogger} that appends to `events`, stamping each line with `now()`. Shared by the
@@ -7117,4 +7188,4 @@ declare function singletonAdmissionDenialPatch(runs: WorkflowRun[], runId: strin
     updatedAt: Date;
 } | undefined;
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CHILD_EDGE_PREFIXES, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type CheckpointAggregatingStore, type CheckpointNameKind, type CheckpointQuery, type CheckpointStat, type ChildCallOptions, type ChildWait, CodecStateStore, type CodecStateStoreOptions, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DEFAULT_STALLED_AFTER_MS, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, ENTITY_WORKFLOW, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, type EntityWorkflowHost, EventAccumulators, type EventBatchConfig, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, type FindStalledRunsOptions, GatherError, type GatherItemFailure, type GroupHealth, HANDOFF_SEQ_BASE, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type ListStalledRunsOptions, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type OnErrorInput, type OnErrorRoute, type OwnedLeaseReclaim, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, RUN_HISTORY_FIXTURE_VERSION, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDetailOptions, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, SINGLETON_ACTIVE_STATUSES, SINGLETON_ADMITTED_TAG, SINGLETON_RESERVED_TAGS, SINGLETON_TRACKED_TAG, STATE_STORE, STATE_STORE_CANONICAL, SUMMARY_CHILD_LIMIT, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, type Settled, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StalePendingStep, type StalledRunInfo, 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 StepScope, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, aggregatesCheckpoints, announcementsOf, applyAttributeQuery, assertConcurrency, assertRoutes, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, legacySingletonHolders, listSignalWaitersOfRuns, liveHandoff, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, queryCheckpointsOf, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, retiredHandoffName, routeFor, runDetailEtag, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduledRunId, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantGroup, useDurableExecution, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CHILD_EDGE_PREFIXES, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type CheckpointAggregatingStore, type CheckpointNameKind, type CheckpointQuery, type CheckpointStat, type ChildCallOptions, type ChildWait, CodecStateStore, type CodecStateStoreOptions, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DEFAULT_STALLED_AFTER_MS, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, ENTITY_WORKFLOW, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, type EntityWorkflowHost, EventAccumulators, type EventBatchConfig, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, type FindStalledRunsOptions, GatherError, type GatherItemFailure, type GroupHealth, HANDOFF_SEQ_BASE, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type ListStalledRunsOptions, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type OnErrorInput, type OnErrorRoute, type OwnedLeaseReclaim, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, RUN_HISTORY_FIXTURE_VERSION, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDetailOptions, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, SINGLETON_ACTIVE_STATUSES, SINGLETON_ADMITTED_TAG, SINGLETON_RESERVED_TAGS, SINGLETON_TRACKED_TAG, STATE_STORE, STATE_STORE_CANONICAL, SUMMARY_CHILD_LIMIT, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduledWorkflow, type SchemaIssue, type SchemaValidationCode, SchemaValidationError, type SearchAttributes, type SearchAttributesSchema, type Settled, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StalePendingStep, type StalledRunInfo, 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 StepScope, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, aggregatesCheckpoints, announcementsOf, applyAttributeQuery, assertConcurrency, assertRoutes, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, legacySingletonHolders, listSignalWaitersOfRuns, liveHandoff, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, queryCheckpointsOf, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, retiredHandoffName, routeFor, runDetailEtag, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduleRunIdAt, scheduledRunId, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantGroup, useDurableExecution, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };

package/dist/index.js

@@ -277,6 +277,31 @@ var FatalError = class extends Error {
     this.details = details;
   }
 };
+var SchemaValidationError = class extends FatalError {
+  static {
+    __name(this, "SchemaValidationError");
+  }
+  static code = "schema_validation";
+  issues;
+  /**
+  * @param label What was validated, e.g. `workflow "checkout" input`; the message is
+  *   `invalid <label>: <path>: <message>; …`.
+  * @param summary Overrides the `<path>: <message>; …` part, for issues whose messages already
+  *   name their field (class-validator's `orderId must be a string`).
+  */
+  constructor(label, issues, code = "schema_validation", summary) {
+    const normalized = issues.map((issue) => ({
+      message: issue.message,
+      path: (issue.path ?? []).map((segment) => String(typeof segment === "object" && segment !== null ? segment.key : segment))
+    }));
+    const text = summary ?? normalized.map((issue) => issue.path.length > 0 ? `${issue.path.join(".")}: ${issue.message}` : issue.message).join("; ");
+    super(`invalid ${label}: ${text}`, code, {
+      issues: normalized
+    });
+    this.name = "SchemaValidationError";
+    this.issues = normalized;
+  }
+};
 var ConcurrencyLimitError = class extends Error {
   static {
     __name(this, "ConcurrencyLimitError");
@@ -2008,9 +2033,14 @@ function liveHandoff(runId, checkpoints) {
   return live;
 }
 __name(liveHandoff, "liveHandoff");
+var SCHEMA_VALIDATION_CODES = /* @__PURE__ */ new Set([
+  "invalid_input",
+  "invalid_output"
+]);
 function routeFor(routes, error2) {
   if (!routes?.length || error2.code && UNROUTABLE_CODES.has(error2.code)) return void 0;
-  return (error2.code ? routes.find((r) => r.code === error2.code) : void 0) ?? routes.find((r) => r.code === void 0);
+  const { code } = error2;
+  return (code ? routes.find((r) => r.code === code) : void 0) ?? (code && SCHEMA_VALIDATION_CODES.has(code) ? routes.find((r) => r.code === "schema_validation") : void 0) ?? routes.find((r) => r.code === void 0);
 }
 __name(routeFor, "routeFor");
 function assertRoutes(workflow, routes) {
@@ -2282,9 +2312,13 @@ __name(scheduleRunIdsAt, "scheduleRunIdsAt");
 async function runSchedules(engine, schedules, nowMs, opts) {
   const random = opts?.random ?? Math.random;
   const sleep = opts?.sleep ?? defaultSleep;
+  const settled = settledIdsFor(engine);
   const ids = [];
   for (const s of schedules) {
+    if (engine.isDraining?.()) break;
     if (s.paused) continue;
+    const candidates = scheduleRunIdsAt(s, nowMs).filter((id) => !settled.get(s.key)?.has(id));
+    if (candidates.length === 0) continue;
     if (s.overlap === "skip" && s.everyMs) {
       const prevBucket = Math.floor(nowMs / s.everyMs) - 1;
       if (prevBucket >= 0) {
@@ -2293,14 +2327,44 @@ async function runSchedules(engine, schedules, nowMs, opts) {
       }
     }
     if (s.jitter && s.jitter > 0) await sleep(Math.floor(random() * s.jitter));
-    for (const runId of scheduleRunIdsAt(s, nowMs)) {
-      await engine.start(s.workflow, s.input, runId);
+    for (const runId of candidates) {
+      if (engine.isDraining?.()) break;
+      const existing = await engine.getRun(runId);
+      remember(settled, s.key, runId);
+      if (existing) continue;
+      await engine.start(workflowName(s.workflow), s.input, runId, {
+        namespace: s.namespace
+      });
       ids.push(runId);
     }
   }
   return ids;
 }
 __name(runSchedules, "runSchedules");
+var settledRunIds = /* @__PURE__ */ new WeakMap();
+function settledIdsFor(engine) {
+  let memo = settledRunIds.get(engine);
+  if (memo === void 0) {
+    memo = /* @__PURE__ */ new Map();
+    settledRunIds.set(engine, memo);
+  }
+  return memo;
+}
+__name(settledIdsFor, "settledIdsFor");
+function remember(memo, key, runId) {
+  const seen = memo.get(key);
+  if (seen === void 0) {
+    memo.set(key, /* @__PURE__ */ new Set([
+      runId
+    ]));
+    return;
+  }
+  seen.add(runId);
+  if (seen.size > 64) memo.set(key, /* @__PURE__ */ new Set([
+    runId
+  ]));
+}
+__name(remember, "remember");
 
 // src/schedules.ts
 var ScheduleAlreadyExistsError = class extends Error {
@@ -3099,11 +3163,6 @@ function normalizeChildOptions(options) {
   } : options ?? {};
 }
 __name(normalizeChildOptions, "normalizeChildOptions");
-function formatIssuePath(path) {
-  if (!path || path.length === 0) return "(root)";
-  return path.map((segment) => String(typeof segment === "object" ? segment.key : segment)).join(".");
-}
-__name(formatIssuePath, "formatIssuePath");
 function resolveStepPolicy(config, opts) {
   const policy = {};
   const retries = opts?.retries ?? config?.retries;
@@ -3935,11 +3994,7 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
         throw new Error(`workflow "${workflow}": ctx.upsertSearchAttributes schema validation must be synchronous (the searchAttributes schema's \`~standard.validate\` returned a Promise) \u2014 replay-determinism requires a sync validator; drop any async refinement from the schema passed to @Workflow({ searchAttributes }).`);
       }
       if (result.issues) {
-        const offendingKeys = [
-          ...new Set(result.issues.map((issue) => formatIssuePath(issue.path)))
-        ];
-        const details = result.issues.map((issue) => `${formatIssuePath(issue.path)}: ${issue.message}`).join("; ");
-        throw new Error(`workflow "${workflow}": ctx.upsertSearchAttributes rejected by its searchAttributes schema \u2014 offending key(s) ${offendingKeys.join(", ")} \u2014 ${details}`);
+        throw new SchemaValidationError(`workflow "${workflow}" ctx.upsertSearchAttributes`, result.issues);
       }
     }
     await host.upsertSearchAttributes(runId, attrs);
@@ -5145,6 +5200,10 @@ var WorkflowEngine = class {
       for (const rearm of this.drainRearms) rearm();
     }
   }
+  /** True once {@link beginDrain} (or {@link drain}) has been called. */
+  isDraining() {
+    return this.draining;
+  }
   /**
   * Graceful shutdown: stop picking up new runs (recovery/timer become no-ops) and wait for
   * in-flight executions to settle, up to `timeoutMs`. Call from your app's shutdown hook so a
@@ -10735,6 +10794,7 @@ export {
   ScheduleAlreadyExistsError,
   ScheduleClient,
   ScheduleNotFoundError,
+  SchemaValidationError,
   SignalTimeoutError,
   SingletonQueueFullError,
   TERMINAL_RUN_STATUSES,
@@ -10846,6 +10906,7 @@ export {
   runStepHandler,
   runValueFacetsFromRuns,
   sanitizeQueueToken,
+  scheduleRunIdAt,
   scheduledRunId,
   singletonAdmissionDenialPatch,
   singletonAdmissionTags,