@dudousxd/nestjs-durable-core 0.77.0 → 0.78.0

package/dist/index.d.ts

@@ -474,6 +474,198 @@ declare class WorkflowBlocked extends Error {
  */
 declare function planDispatch(requires: string[], liveDescriptors: readonly (RawWorkerDescriptor | WorkerDescriptor)[], cp: WorkerDescriptor, token: string): DispatchPlan;
 
+/**
+ * A parallel fan (a `ctx.all`, a step fan, a polyglot `gather`) reduced to what a detail view needs
+ * to draw it: one node, its progress and its failures. A run detail with a 40,000-item fan otherwise
+ * carries every member — megabytes of JSON, and one rendered row (or fetched child) per member.
+ */
+interface FanSummary {
+    /** The fan's `parallelGroup`. */
+    group: string;
+    /** The members' common step name, or `child runs` for a fan of child workflows. */
+    label: string;
+    firstSeq: number;
+    lastSeq: number;
+    /** Members started so far: steps, or child runs (a folded checkpoint counts as the children it stands for). */
+    size: number;
+    /**
+     * The fan's declared size, when its group carries it. More than `size` while waves are still to
+     * be sent (`concurrency`), and for good when a failFast fan stopped early.
+     */
+    total?: number | undefined;
+    /** `total - size`: members never started yet — or never to start, once the run has finished. */
+    notStarted?: number | undefined;
+    /** The fan stops at its first failure. */
+    failFast: boolean;
+    /** Members by status. A child that failed counts as `failed`, though its checkpoint is `completed`. */
+    counts: Partial<Record<StepCheckpoint['status'], number>>;
+    startedAt?: Date | undefined;
+    finishedAt?: Date | undefined;
+    /** The first {@link FAN_SUMMARY_FAILURES} failed members, so a failure shows without paging. */
+    failures: StepCheckpoint[];
+}
+/** A page of one fan's members, in seq order. */
+interface FanPage {
+    items: StepCheckpoint[];
+    /** Members matching the query, across all pages. */
+    total: number;
+}
+interface FanPageQuery {
+    offset?: number | undefined;
+    limit?: number | undefined;
+    /** Only failed members (a failed step, or a child that failed). */
+    failedOnly?: boolean | undefined;
+}
+declare const FAN_SUMMARY_FAILURES = 20;
+/** The most children a summarized detail lists by id; `childCount` carries the rest. */
+declare const SUMMARY_CHILD_LIMIT = 200;
+/** A failed member: a failed step, or a child whose completion reports `ok: false`. */
+declare function isFailedMember(cp: StepCheckpoint): boolean;
+/** Summarize one fan's members (in seq order). */
+declare function summarizeFan(group: string, members: StepCheckpoint[]): FanSummary;
+/**
+ * Split a run's timeline into the checkpoints a detail view lists one by one and the fans it draws as
+ * one node each: every `parallelGroup` with more than `over` members, or declared wider than that,
+ * becomes a {@link FanSummary}, and its members leave the timeline. Smaller groups and ungrouped steps stay as they are.
+ */
+declare function summarizeTimeline(timeline: StepCheckpoint[], over: number): {
+    timeline: StepCheckpoint[];
+    fans: FanSummary[];
+};
+/** One page of a fan's members out of a run's timeline. */
+declare function pageFan(timeline: StepCheckpoint[], group: string, query: FanPageQuery): FanPage;
+
+/** A run as returned by the gateway's list — the durable run plus an optional {@link RunWaiting}
+ *  descriptor the control plane resolves (what a suspended run is parked on), so the dashboard can
+ *  name the wait in a list row without fetching each run's timeline. Additive: `waiting` is absent
+ *  on a non-parked run and on gateways/versions that don't compute it. */
+type RunListItem = WorkflowRun & {
+    waiting?: RunWaiting | undefined;
+};
+/** Which durable topology a gateway speaks for — surfaced in the dashboard so an operator can tell a
+ *  control plane from a tenant at a glance (the store-backed gateway is the operator; the proxy is a
+ *  tenant). Cheap, synchronous, local knowledge — no round-trip. */
+interface DurableTopology {
+    role: 'control-plane' | 'tenant';
+    /** The tenant's isolation partition name; set only when `role` is 'tenant'. */
+    tenant?: string;
+}
+/** 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). With {@link RunDetailOptions.summarizeFansOver}, the
+     * members of a summarized fan are left out — see {@link fans}.
+     */
+    timeline: StepCheckpoint[];
+    /** Ids of runs this run spawned (parent→children tree). Capped when summarized — see {@link childCount}. */
+    children: string[];
+    /** The fans drawn as one node each, when the detail was asked to summarize them. */
+    fans?: FanSummary[] | undefined;
+    /** How many children the run has, when `children` lists only the first of them. */
+    childCount?: number | undefined;
+}
+/** How to shape a {@link RunDetail}. */
+interface RunDetailOptions {
+    /**
+     * Summarize every fan with more than this many members into a {@link FanSummary} instead of
+     * listing them, and cap `children`. Unset returns the full timeline, as before. A view of a run
+     * with a wide fan should set it: the full detail of a 40k-member fan is megabytes.
+     */
+    summarizeFansOver?: number | undefined;
+}
+/**
+ * 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
+ * a `ProxyRunGateway` that round-trips over the transport. Deliberately smaller than the full dashboard
+ * (no metrics/bulk/update/signal) — those stay control-plane-only. `workerHealth` IS on the port: the
+ * operator answers it scoped to the requester's own groups, so a tenant's Workers panel works too.
+ *
+ * Declared as an **abstract class** rather than an interface so it doubles as its own NestJS DI token
+ * (the idiomatic inject-by-type pattern): providers bind `{ provide: RunGateway, useClass/useFactory }`
+ * and consumers inject `constructor(private readonly gateway: RunGateway)` with no string/symbol token.
+ * `StoreRunGateway`/`ProxyRunGateway` `implements RunGateway`; abstract methods carry no body, so the
+ * emitted runtime class is an empty, non-instantiable shell used only as the token.
+ */
+declare abstract class RunGateway {
+    /** This deployment's durable role (control plane vs tenant) — synchronous local metadata. */
+    abstract topology(): DurableTopology;
+    abstract getRunDetail(runId: string, options?: RunDetailOptions): Promise<RunDetail | null>;
+    /**
+     * One page of a fan's members, for a view that drew the fan from its {@link FanSummary}. Optional:
+     * a gateway without it serves summarized details whose fans cannot be expanded.
+     */
+    getFanMembers?(runId: string, group: string, query: FanPageQuery): Promise<FanPage | null>;
+    /**
+     * The run alone, without its timeline. Optional: a caller that only needs the run (an ownership
+     * check) falls back to {@link getRunDetail}, which reads every checkpoint.
+     */
+    getRun?(runId: string): Promise<WorkflowRun | null>;
+    /** List runs, each optionally carrying a {@link RunWaiting} descriptor (what a suspended run is
+     *  parked on). The store-backed gateway resolves `waiting`; a proxy relays whatever the control
+     *  plane sent. */
+    abstract listRuns(query: RunQuery): Promise<RunListItem[]>;
+    /**
+     * Counts of the runs matching `query`, grouped by `(status, origin)` — what a console's status and
+     * origin chips display. Separate from {@link listRuns} precisely so the list can be PAGINATED: the
+     * page bounds what is rendered, these counts stay whole-set exact. Zero-count cells are absent.
+     */
+    abstract runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
+    /**
+     * The distinct values of one filter axis over the runs matching `query`, with counts — what fills a
+     * console's tenant/tag/attribute pickers. On the port (not control-plane-only) because the pickers
+     * belong to the same panel as {@link listRuns}: a tenant that can list its runs has to be able to
+     * see what it may filter them by, or its console offers a blank dropdown.
+     *
+     * Returns `[]` when the underlying store does not implement the enumeration — an empty picker with
+     * free-text entry still standing, not an error.
+     */
+    abstract runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
+    /**
+     * 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`.
+     */
+    abstract 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. */
+    abstract workerHealth(): Promise<GroupHealth[]>;
+    abstract cancel(runId: string, opts?: {
+        compensate?: boolean;
+    }): Promise<RunResult | null>;
+    abstract retry(runId: string): Promise<RunResult | null>;
+    abstract continue(runId: string): Promise<RunResult | null>;
+    /** Re-dispatch every remote step of a run stuck `pending` — the operator recovery for a LOST step
+     *  dispatch (crashed worker / dropped job) that no automatic path re-drives. Returns the run's status
+     *  plus how many steps were re-dispatched, or null if the run is unknown. */
+    abstract redispatchPending(runId: string): Promise<(RunResult & {
+        redispatched: number;
+    }) | null>;
+    abstract retryWithInput(runId: string, input: unknown): Promise<{
+        runId: string;
+    } | null>;
+    /** Live lifecycle events for one run; returns an unsubscribe fn. Framework-agnostic (no rxjs). */
+    abstract subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => 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
@@ -1569,6 +1761,12 @@ interface RunRequest {
 type RunRequestKind = {
     kind: 'getRunDetail';
     runId: string;
+    options?: RunDetailOptions | undefined;
+} | {
+    kind: 'getFanMembers';
+    runId: string;
+    group: string;
+    query: FanPageQuery;
 } | {
     kind: 'listRuns';
     query: RunQuery;
@@ -5007,6 +5205,8 @@ declare class RemoteStepError extends Error {
     readonly stepError?: StepError | undefined;
     constructor(stepError?: StepError);
 }
+/** The child run ids a parent's {@link CHILD_EDGE_PREFIXES} checkpoints point at (others are skipped). */
+declare function childIdsOf(checkpoints: StepCheckpoint[]): string[];
 
 /**
  * What the class-first statics need from whoever registered the workflow class: the engine, or a
@@ -5437,111 +5637,6 @@ declare function mergeRunValueFacetRows(rows: readonly {
  */
 declare function runValueFacetsFromRuns(runs: readonly WorkflowRun[], axis: RunValueAxis, opts?: RunValueFacetOptions): RunValueFacetRow[];
 
-/** A run as returned by the gateway's list — the durable run plus an optional {@link RunWaiting}
- *  descriptor the control plane resolves (what a suspended run is parked on), so the dashboard can
- *  name the wait in a list row without fetching each run's timeline. Additive: `waiting` is absent
- *  on a non-parked run and on gateways/versions that don't compute it. */
-type RunListItem = WorkflowRun & {
-    waiting?: RunWaiting | undefined;
-};
-/** Which durable topology a gateway speaks for — surfaced in the dashboard so an operator can tell a
- *  control plane from a tenant at a glance (the store-backed gateway is the operator; the proxy is a
- *  tenant). Cheap, synchronous, local knowledge — no round-trip. */
-interface DurableTopology {
-    role: 'control-plane' | 'tenant';
-    /** The tenant's isolation partition name; set only when `role` is 'tenant'. */
-    tenant?: string;
-}
-/** 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). */
-    timeline: StepCheckpoint[];
-    /** 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
- * a `ProxyRunGateway` that round-trips over the transport. Deliberately smaller than the full dashboard
- * (no metrics/bulk/update/signal) — those stay control-plane-only. `workerHealth` IS on the port: the
- * operator answers it scoped to the requester's own groups, so a tenant's Workers panel works too.
- *
- * Declared as an **abstract class** rather than an interface so it doubles as its own NestJS DI token
- * (the idiomatic inject-by-type pattern): providers bind `{ provide: RunGateway, useClass/useFactory }`
- * and consumers inject `constructor(private readonly gateway: RunGateway)` with no string/symbol token.
- * `StoreRunGateway`/`ProxyRunGateway` `implements RunGateway`; abstract methods carry no body, so the
- * emitted runtime class is an empty, non-instantiable shell used only as the token.
- */
-declare abstract class RunGateway {
-    /** This deployment's durable role (control plane vs tenant) — synchronous local metadata. */
-    abstract topology(): DurableTopology;
-    abstract getRunDetail(runId: string): Promise<RunDetail | null>;
-    /** List runs, each optionally carrying a {@link RunWaiting} descriptor (what a suspended run is
-     *  parked on). The store-backed gateway resolves `waiting`; a proxy relays whatever the control
-     *  plane sent. */
-    abstract listRuns(query: RunQuery): Promise<RunListItem[]>;
-    /**
-     * Counts of the runs matching `query`, grouped by `(status, origin)` — what a console's status and
-     * origin chips display. Separate from {@link listRuns} precisely so the list can be PAGINATED: the
-     * page bounds what is rendered, these counts stay whole-set exact. Zero-count cells are absent.
-     */
-    abstract runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
-    /**
-     * The distinct values of one filter axis over the runs matching `query`, with counts — what fills a
-     * console's tenant/tag/attribute pickers. On the port (not control-plane-only) because the pickers
-     * belong to the same panel as {@link listRuns}: a tenant that can list its runs has to be able to
-     * see what it may filter them by, or its console offers a blank dropdown.
-     *
-     * Returns `[]` when the underlying store does not implement the enumeration — an empty picker with
-     * free-text entry still standing, not an error.
-     */
-    abstract runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
-    /**
-     * 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`.
-     */
-    abstract 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. */
-    abstract workerHealth(): Promise<GroupHealth[]>;
-    abstract cancel(runId: string, opts?: {
-        compensate?: boolean;
-    }): Promise<RunResult | null>;
-    abstract retry(runId: string): Promise<RunResult | null>;
-    abstract continue(runId: string): Promise<RunResult | null>;
-    /** Re-dispatch every remote step of a run stuck `pending` — the operator recovery for a LOST step
-     *  dispatch (crashed worker / dropped job) that no automatic path re-drives. Returns the run's status
-     *  plus how many steps were re-dispatched, or null if the run is unknown. */
-    abstract redispatchPending(runId: string): Promise<(RunResult & {
-        redispatched: number;
-    }) | null>;
-    abstract retryWithInput(runId: string, input: unknown): Promise<{
-        runId: string;
-    } | null>;
-    /** Live lifecycle events for one run; returns an unsubscribe fn. Framework-agnostic (no rxjs). */
-    abstract subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
-}
-
 /**
  * Resolve WHAT a suspended run is parked on from the token of the {@link SignalWaiter} it registered.
  * The token prefix carries the kind — no extra store lookup and no new persisted field. Used by the
@@ -6200,4 +6295,4 @@ declare function singletonAdmissionDenialPatch(runs: WorkflowRun[], runId: strin
     updatedAt: Date;
 } | undefined;
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllStepsOptions, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type ChildCallOptions, type ChildWait, CodecStateStore, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, 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, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, type FanJoin, type FanWait, FatalError, GatherError, type GroupHealth, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, 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 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, STATE_STORE, STATE_STORE_CANONICAL, 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, 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 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, announcementsOf, applyAttributeQuery, assertConcurrency, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, error, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, listSignalWaitersOfRuns, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, parentRunIdOf, parseDuration, partitionOfToken, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduledRunId, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, tenantGroup, useDurableExecution, warn, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllStepsOptions, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type ChildCallOptions, type ChildWait, CodecStateStore, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, 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, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, GatherError, type GroupHealth, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, 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, 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, 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 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, announcementsOf, applyAttributeQuery, assertConcurrency, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, error, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, listSignalWaitersOfRuns, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, pageFan, parentRunIdOf, parseDuration, partitionOfToken, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduledRunId, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeTimeline, tenantGroup, useDurableExecution, warn, workflowName };

package/dist/index.js

@@ -1083,8 +1083,9 @@ function allChildId(runId, firstSeq, index, wave) {
   return `${allBase(runId, firstSeq, wave)}${index}`;
 }
 __name(allChildId, "allChildId");
-function allGroup(firstSeq, mode) {
-  return mode === "failFast" ? `all:${firstSeq}:failFast` : `all:${firstSeq}`;
+function allGroup(firstSeq, size, mode) {
+  const group = `all:${firstSeq}:n${size}`;
+  return mode === "failFast" ? `${group}:failFast` : group;
 }
 __name(allGroup, "allGroup");
 function stepFanGroup(firstSeq, size, mode) {
@@ -1093,14 +1094,26 @@ function stepFanGroup(firstSeq, size, mode) {
 }
 __name(stepFanGroup, "stepFanGroup");
 function parseStepFanGroup(group) {
-  const m = group ? /^steps:(\d+):(\d+)(?::failFast)?$/.exec(group) : null;
-  if (!m) return void 0;
+  const fan = parseFanGroup(group);
+  if (fan?.kind !== "steps" || fan.size === void 0) return void 0;
   return {
-    firstSeq: Number(m[1]),
-    size: Number(m[2])
+    firstSeq: fan.firstSeq,
+    size: fan.size
   };
 }
 __name(parseStepFanGroup, "parseStepFanGroup");
+function parseFanGroup(group) {
+  const m = group ? /^(all|steps):(\d+)(?::n?(\d+))?(:failFast)?$/.exec(group) : null;
+  if (!m) return void 0;
+  if (m[1] === "steps" && m[3] === void 0) return void 0;
+  return {
+    kind: m[1],
+    firstSeq: Number(m[2]),
+    size: m[3] === void 0 ? void 0 : Number(m[3]),
+    failFast: m[4] !== void 0
+  };
+}
+__name(parseFanGroup, "parseFanGroup");
 function allWait(runId, firstSeq, wave) {
   const base = allBase(runId, firstSeq, wave);
   return {
@@ -1150,7 +1163,7 @@ function parentRunIdOf(runId) {
   return ENGINE_CHILD_ID.exec(runId)?.[1];
 }
 __name(parentRunIdOf, "parentRunIdOf");
-var GROUP = /^all:(\d+)(:failFast)?$/;
+var GROUP = /^all:(\d+)(?::n\d+)?(:failFast)?$/;
 var REST = /^(?:w(\d+)\.)?\d+$/;
 function fanOfWaiter(waiter) {
   const group = waiter.parallelGroup ? GROUP.exec(waiter.parallelGroup) : null;
@@ -3150,7 +3163,7 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
     const waves = allWaves(inputs.length, opts?.concurrency);
     const positions = inputs.map(() => pos.next());
     const firstSeq = positions[0];
-    const group = allGroup(firstSeq, mode);
+    const group = allGroup(firstSeq, inputs.length, mode);
     const waveOf = /* @__PURE__ */ __name((i) => waves ? Math.floor(i / waves.waveSize) : void 0, "waveOf");
     const id = /* @__PURE__ */ __name((i) => allChildId(runId, firstSeq, i, waveOf(i)), "id");
     const { checkpoints: existing, folded } = await readFan(positions, [
@@ -7935,6 +7948,110 @@ var RunGateway = class {
   }
 };
 
+// src/run-detail-summary.ts
+var FAN_SUMMARY_FAILURES = 20;
+var SUMMARY_CHILD_LIMIT = 200;
+var FAN_PAGE_MAX = 500;
+function foldedCount(cp) {
+  if (!cp.name.startsWith(FOLDED_PREFIX)) return void 0;
+  const values = cp.output?.values;
+  return Array.isArray(values) ? values.length : 0;
+}
+__name(foldedCount, "foldedCount");
+function isFailedMember(cp) {
+  if (cp.status === "failed") return true;
+  if (!cp.name.startsWith("signal:child:") || cp.status !== "completed") return false;
+  return cp.output?.ok === false;
+}
+__name(isFailedMember, "isFailedMember");
+function fanLabel(members) {
+  if (members.some((cp) => cp.name.startsWith("signal:child:") || foldedCount(cp) !== void 0)) {
+    return "child runs";
+  }
+  const first = members[0]?.name ?? "";
+  return members.every((cp) => cp.name === first) ? first : "steps";
+}
+__name(fanLabel, "fanLabel");
+function summarizeFan(group, members) {
+  const counts = {};
+  const failures = [];
+  let size = 0;
+  let startedAt;
+  let finishedAt;
+  let firstSeq = Number.POSITIVE_INFINITY;
+  let lastSeq = Number.NEGATIVE_INFINITY;
+  for (const cp of members) {
+    firstSeq = Math.min(firstSeq, cp.seq);
+    lastSeq = Math.max(lastSeq, cp.seq);
+    const folded = foldedCount(cp);
+    const n = folded ?? 1;
+    size += n;
+    const status = isFailedMember(cp) ? "failed" : cp.status;
+    counts[status] = (counts[status] ?? 0) + n;
+    if (status === "failed" && failures.length < FAN_SUMMARY_FAILURES) failures.push(cp);
+    if (cp.status !== "pending" && cp.status !== "running") {
+      if (!startedAt || cp.startedAt < startedAt) startedAt = cp.startedAt;
+      if (!finishedAt || cp.finishedAt > finishedAt) finishedAt = cp.finishedAt;
+    } else if (!startedAt || cp.enqueuedAt < startedAt) {
+      startedAt = cp.enqueuedAt;
+    }
+  }
+  const parsed = parseFanGroup(group);
+  const total = parsed?.size;
+  return {
+    group,
+    label: fanLabel(members),
+    firstSeq,
+    lastSeq,
+    size,
+    total,
+    notStarted: total === void 0 ? void 0 : Math.max(0, total - size),
+    failFast: parsed?.failFast ?? false,
+    counts,
+    startedAt,
+    finishedAt,
+    failures
+  };
+}
+__name(summarizeFan, "summarizeFan");
+function summarizeTimeline(timeline, over) {
+  const byGroup = /* @__PURE__ */ new Map();
+  for (const cp of timeline) {
+    if (cp.parallelGroup === void 0) continue;
+    const members = byGroup.get(cp.parallelGroup);
+    if (members) members.push(cp);
+    else byGroup.set(cp.parallelGroup, [
+      cp
+    ]);
+  }
+  const summarized = /* @__PURE__ */ new Set();
+  const fans = [];
+  for (const [group, members] of byGroup) {
+    if (members.length <= over && (parseFanGroup(group)?.size ?? 0) <= over) continue;
+    summarized.add(group);
+    fans.push(summarizeFan(group, members));
+  }
+  if (fans.length === 0) return {
+    timeline,
+    fans
+  };
+  return {
+    timeline: timeline.filter((cp) => cp.parallelGroup === void 0 || !summarized.has(cp.parallelGroup)),
+    fans: fans.sort((a, b) => a.firstSeq - b.firstSeq)
+  };
+}
+__name(summarizeTimeline, "summarizeTimeline");
+function pageFan(timeline, group, query) {
+  const matching = timeline.filter((cp) => cp.parallelGroup === group && (!query.failedOnly || isFailedMember(cp)));
+  const offset = query.offset !== void 0 && Number.isFinite(query.offset) ? Math.max(0, Math.floor(query.offset)) : 0;
+  const limit = query.limit !== void 0 && Number.isFinite(query.limit) ? Math.min(FAN_PAGE_MAX, Math.max(1, Math.floor(query.limit))) : 100;
+  return {
+    items: matching.slice(offset, offset + limit),
+    total: matching.length
+  };
+}
+__name(pageFan, "pageFan");
+
 // src/codec-state-store.ts
 var CodecStateStore = class {
   static {
@@ -8940,6 +9057,7 @@ export {
   EVENT_TOKEN_PREFIX,
   Entities,
   EventAccumulators,
+  FAN_SUMMARY_FAILURES,
   FatalError,
   GatherError,
   InMemoryAdmissionBackend,
@@ -8961,6 +9079,7 @@ export {
   SINGLETON_ADMITTED_TAG,
   STATE_STORE,
   STATE_STORE_CANONICAL,
+  SUMMARY_CHILD_LIMIT,
   ScheduleAlreadyExistsError,
   ScheduleClient,
   ScheduleNotFoundError,
@@ -8987,6 +9106,7 @@ export {
   buildWorkflowDirectory,
   canRoute,
   capableWorkers,
+  childIdsOf,
   classifyWaiterToken,
   clearDurableExecutionWrappers,
   clearTerminalSingletonAdmission,
@@ -9015,6 +9135,7 @@ export {
   info,
   isEngineMintedTag,
   isEventToken,
+  isFailedMember,
   isLegacyDescriptor,
   isNonEmptyRunScope,
   isWorkflowControlFlowSignal,
@@ -9029,6 +9150,7 @@ export {
   normalizeAttributeRows,
   normalizeDescriptor,
   observedAnnouncements,
+  pageFan,
   parentRunIdOf,
   parseDuration,
   partitionOfToken,
@@ -9058,6 +9180,8 @@ export {
   sub,
   subEvent,
   subProcess,
+  summarizeFan,
+  summarizeTimeline,
   tenantGroup,
   useDurableExecution,
   warn,