footprintjs 10.0.1 → 10.2.0

package/dist/esm/lib/builder/FlowChartBuilder.d.ts

@@ -11,10 +11,11 @@
  * The execute() convenience method is intentionally omitted —
  * it belongs in the runner layer (Phase 5).
  */
-import type { ParallelForEachConfig, RetryPolicy, ScopeFactory } from '../engine/types.js';
+import type { ParallelForEachConfig, RetryPolicy, ScopeFactory, StageTouches } from '../engine/types.js';
 import type { PausableHandler } from '../pause/types.js';
 import type { TypedScope } from '../reactive/types.js';
 import { type RunnableFlowChart } from '../runner/RunnableChart.js';
+import type { RetryLoopOptions } from './retryLoop.js';
 import type { StructureEdgeKind, StructureRecorder } from './structure/StructureRecorder.js';
 import { StructureRecorderDispatcher } from './structure/StructureRecorderDispatcher.js';
 import { type TypedStageFunction } from './typedFlowChart.js';
@@ -35,6 +36,7 @@ export declare class DeciderList<TOut = any, TScope = any> {
     options?: {
         readonly loopTo?: string;
         readonly retry?: RetryPolicy;
+        readonly touches?: StageTouches;
         readonly tags?: readonly string[];
     }): DeciderList<TOut, TScope>;
     /**
@@ -54,6 +56,7 @@ export declare class DeciderList<TOut = any, TScope = any> {
     options?: {
         readonly loopTo?: string;
         readonly retry?: RetryPolicy;
+        readonly touches?: StageTouches;
         readonly tags?: readonly string[];
     }): DeciderList<TOut, TScope>;
     addSubFlowChartBranch(id: string, subflow: FlowChart<any, any>, mountName?: string, options?: SubflowMountOptions): DeciderList<TOut, TScope>;
@@ -107,6 +110,7 @@ export declare class SelectorFnList<TOut = any, TScope = any> {
      *  `{ tags }` puts declared tags on it (see `FlowChartBuilder.tag`). */
     options?: {
         readonly retry?: RetryPolicy;
+        readonly touches?: StageTouches;
         readonly tags?: readonly string[];
     }): SelectorFnList<TOut, TScope>;
     /**
@@ -122,6 +126,7 @@ export declare class SelectorFnList<TOut = any, TScope = any> {
      *  contract); `{ tags }` puts declared tags on it. */
     options?: {
         readonly retry?: RetryPolicy;
+        readonly touches?: StageTouches;
         readonly tags?: readonly string[];
     }): SelectorFnList<TOut, TScope>;
     addSubFlowChartBranch(id: string, subflow: FlowChart<any, any>, mountName?: string, options?: SubflowMountOptions): SelectorFnList<TOut, TScope>;
@@ -286,6 +291,7 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
     }): this;
     start(name: string, fn: StageFunction<TOut, TScope> | PausableHandler<TScope>, id: string, description?: string, options?: {
         retry?: RetryPolicy;
+        touches?: StageTouches;
         tags?: readonly string[];
     }): this;
     /**
@@ -303,9 +309,12 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
     startSelector(name: string, fn: StageFunction<any, TScope>, id: string, description?: string, options?: {
         failFast?: boolean;
         retry?: RetryPolicy;
+        touches?: StageTouches;
         tags?: readonly string[];
     }): SelectorFnList<TOut, TScope>;
     addFunction(name: string, fn: StageFunction<TOut, TScope>, id: string, description?: string): this;
+    /** Compose a keyed outside operation, reconciliation, shared retry decision and wait as ordinary chart nodes. */
+    addRetryLoop<TValue = unknown>(id: string, options: RetryLoopOptions<TScope, TValue>): this;
     addStreamingFunction(name: string, fn: StageFunction<TOut, TScope>, id: string, streamId?: string, description?: string): this;
     /**
      * Add a pausable stage — can pause execution and resume later with input.
@@ -417,6 +426,7 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
      *  `{ tags }` likewise. */
     options?: {
         retry?: RetryPolicy;
+        touches?: StageTouches;
         tags?: readonly string[];
     }): DeciderList<TOut, TScope>;
     addSelectorFunction(name: string, fn: StageFunction<any, TScope>, id: string, description?: string, 
@@ -426,6 +436,7 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
     options?: {
         failFast?: boolean;
         retry?: RetryPolicy;
+        touches?: StageTouches;
         tags?: readonly string[];
     }): SelectorFnList<TOut, TScope>;
     addListOfFunction(children: SimplifiedParallelSpec<TOut, TScope>[], options?: {
@@ -489,8 +500,13 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
      * failed calls that came before the successful one left no mark anywhere —
      * an unexplained behaviour in a library whose whole point is that nothing
      * invisible happens. Declared here, every attempt is part of the record: each
-     * failed attempt fires `FlowRecorder.onStageRetry` and appears in the
-     * narrative, in order, between the attempts' own reads and writes.
+     * attempt fires `FlowRecorder.onAttempt` with its `AttemptRecord` (outcome,
+     * duration, failure category, the retry-or-stop decision), which is what
+     * feeds the narrative — one line per attempt, in order, between the
+     * attempts' own reads and writes. The stage's execution-tree node keeps the
+     * records (`attempts`, `attemptSummary`). A failed attempt that is retried
+     * also fires `FlowRecorder.onStageRetry`, which the narrative does not tell
+     * twice.
      *
      * ## What an attempt is
      *
@@ -518,6 +534,46 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
      * `retry` option instead.
      */
     retry(policy: RetryPolicy): this;
+    /**
+     * Declare that the stage you JUST added changes an outside system — a charge, an email, a write to another
+     * service (10.1, design §3.3) — and give the rule for its idempotency key.
+     *
+     * ## Why declare it
+     *
+     * A retry is safe for a read. For a charge it is safe only when the outside system can tell a retry from a new
+     * request — by an idempotency key. So the builder refuses a touching stage that may retry (`.retry({ attempts >
+     * 1 })`, in either order) without a key rule: a double charge must be impossible to write by accident. A default
+     * key made by the library was rejected — the run id changes across a resume and a caller's whole-run retry, the
+     * two places a double charge actually happens. The key must name the OPERATION: derive it from the input the rule
+     * is handed, never from model output (`({ getState }) => …` reads it from state). A
+     * keyless touching stage may not `interrupt()`: a resume re-runs it from its top. In a chart that pauses, derive
+     * keys from state (`({ getState }) => …`): the run's input does not cross a resume.
+     *
+     * ## What it changes at run time
+     *
+     * The stage always runs on the attempt runner. The key rule runs ONCE per execution, before attempt 1, and every
+     * attempt gets the key as `scope.$attempt().idempotencyKey` — pass it to the system. Every attempt record says
+     * what it did there (`effect`: `'applied'`, `'none'` when the error itself declares `effect: 'none'`, else
+     * `'unknown'`). When ANY attempt left the effect unknown — it timed out, was cut, or failed without the adapter
+     * saying nothing was sent — the stage fails with `UnknownEffectError`: reconcile with the system by the key, do
+     * not retry blindly. The spec carries the system's name (`touches`).
+     *
+     * @example
+     * ```ts
+     * flowChart<Order>('Load order', loadFn, 'load')
+     *   .addFunction('Charge card', chargeFn, 'charge')
+     *   .touches('stripe', { idempotencyKey: ({ args }) => `order-${(args as { orderId: string }).orderId}` })
+     *   .retry({ attempts: 3, timeoutMs: 20_000 })
+     * ```
+     *
+     * Applies to the CURRENT cursor, like `.retry()`; where the cursor would be ambiguous (a decider, selector,
+     * branch, or fork child), declare it in that method's own `touches` option. Refused: on a subflow mount, a
+     * parallel-for-each stage or a loop reference (no function of their own), after a mount or a fork (the cursor did
+     * not move), twice, with a system that is not a name, and with a key that is not a function.
+     */
+    touches(system: string, options?: {
+        readonly idempotencyKey?: StageTouches['idempotencyKey'];
+    }): this;
     /**
      * Put NAMES on the stage you JUST added. The first commit bundle of each
      * execution of that stage carries them (`CommitBundle.tags` — the bundle
@@ -574,11 +630,40 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
      * second declaration on the same stage.
      */
     tag(...names: readonly string[]): this;
+    /**
+     * Declare the chart's time budget: the most milliseconds a caller gives one run (design §3.2).
+     *
+     * WHY: the incident behind it — a stage retried an SDK call four times, 40 s each, past a caller's 120 s, and the
+     * record said "one stage, one error". Both numbers were declared: the policy on the stage, the budget of the
+     * caller. So `build()` checks one against the other: it REFUSES the chart when its declared policies already allow
+     * longer (`attempts × timeoutMs` plus the waits, summed along the slowest path — see `timeBudget`), and in dev mode
+     * names every stage it cannot bound (no `timeoutMs`, a function backoff with no `maxBackoffMs`, a loop, a lazy
+     * subflow, a `parallelForEach`). The spec root carries it (`budgetMs`); at run start, a deadline shorter than it is
+     * a dev-mode warning.
+     *
+     * Chart-level, so it may be declared anywhere before `build()`, once.
+     *
+     * @example
+     * ```ts
+     * flowChart<State>('Read', readFn, 'read', { retry: { attempts: 1, timeoutMs: 5_000 } })
+     *   .addFunction('Charge', chargeFn, 'charge')
+     *   .retry({ attempts: 4, timeoutMs: 40_000, backoffMs: 1_000 })
+     *   .budget(120_000)
+     *   .build(); // throws: its declared policies allow 168000 ms, over its budget by 48000 ms
+     * ```
+     */
+    budget(ms: number): this;
     loopTo(stageId: string): this;
     onStream(handler: StreamTokenHandler): this;
     onStreamStart(handler: StreamLifecycleHandler): this;
     onStreamEnd(handler: StreamLifecycleHandler): this;
     build(): RunnableFlowChart<TOut, TScope>;
+    /**
+     * The declared budget, checked (owner ruling Q2): refused when the chart's bounded part alone allows longer — a
+     * time its declared policies allow a run to take, so the budget cannot be promised; every stage it cannot bound is
+     * a dev-mode warning.
+     */
+    private _checkBudget;
     /** Override the scope factory. Rarely needed — auto-embeds TypedScope by default. */
     setScopeFactory(factory: ScopeFactory<TScope>): this;
     toSpec<TResult = SerializedPipelineStructure>(): TResult;