fyflow-orchestration 0.9.0 → 0.10.0

package/dist/node/index.js

@@ -99,6 +99,7 @@ import {
   groupsNamedBy,
   innermostMapOf,
   innermostRegionOf,
+  inputOf,
   isDerivation,
   isSuspended,
   isTerminal,
@@ -141,9 +142,10 @@ import {
   transformShapeProblem,
   validateDefinition,
   violatedRules,
+  visibilityKey,
   witness,
   workersOf
-} from "./chunks/chunk-3U4UZC34.js";
+} from "./chunks/chunk-NA6QQAZ2.js";
 
 // src/definition/assist.ts
 var TYPES = ["object", "array", "string", "number", "integer", "boolean", "null"];
@@ -391,6 +393,7 @@ export {
   groupsNamedBy,
   innermostMapOf,
   innermostRegionOf,
+  inputOf,
   isDerivation,
   isSuspended,
   isTerminal,
@@ -440,6 +443,7 @@ export {
   tsTypeOf,
   validateDefinition,
   violatedRules,
+  visibilityKey,
   witness,
   workersOf
 };

package/dist/node/scheduler/index.js

@@ -11,6 +11,7 @@ import {
   derivePool,
   emptyState,
   groupsNamedBy,
+  inputOf,
   isDerivation,
   isTerminal,
   languagesOf,
@@ -25,7 +26,7 @@ import {
   retryPolicyProblem,
   validateDefinition,
   workersOf
-} from "../chunks/chunk-3U4UZC34.js";
+} from "../chunks/chunk-NA6QQAZ2.js";
 
 // src/scheduler/bootstrap.ts
 import { WorkerManager } from "fyflow-scheduler";
@@ -350,6 +351,12 @@ function createRuntime(document, code = {}, options = {}) {
         return p;
       }
     } : view;
+    const reading = {
+      ...registry,
+      joinPolicy: startOptions.joinPolicy ?? liveToken,
+      ...options.defaultRetryPolicy !== void 0 ? { defaultRetryPolicy: options.defaultRetryPolicy } : {},
+      ...options.validateBoundaries !== void 0 ? { validateBoundaries: options.validateBoundaries } : {}
+    };
     const driver = new Driver(flow, {
       runId,
       scheduler: scheduler2,
@@ -408,7 +415,11 @@ function createRuntime(document, code = {}, options = {}) {
         catchUp();
         const entry = acc.entry(taskId);
         return entry === void 0 ? null : freezeDeep(entry);
-      }
+      },
+      // **`RN-R45` — the reading, over this run's own events** (W205, P42 decision 7): the export, handed the options this
+      // function built the run's driver with — `registry`, its `joinPolicy`, and the two runtime-wide ones — so a reading
+      // builds the driver `start` built. The live driver is only READ (`checkpoint()`, a copy).
+      inputOf: (target) => inputOf(flow, reading, driver.checkpoint(), target)
     };
   }
 }

package/dist/types/src/definition/regions.d.ts

@@ -309,6 +309,18 @@ export declare function sharedRegionDepth(regions: RegionSets[], a: string, b: s
  *   own, so for an edge's `needs` this is the node the edge hangs on (`FD-C3`).
  */
 export declare function outputIsVisible(regions: RegionSets[], readerId: string, readerPath: string, targetId: string, targetPath: string): boolean;
+/**
+ * **The key an output is filed under for a reader that shares `depth` regions with it** — the first `depth` SEGMENTS of
+ * its branch path, joined, or `null` for a path with fewer (`-` has none) — W199,
+ * [ADR 0124](../../doc/decisions/0124-a-reference-read-costs-its-answer.md). An output is visible to a reader exactly
+ * when the two have the SAME key at their shared depth ({@link outputIsVisible}), so the driver files a node's outputs
+ * under it once and a read takes its group, where it searched every output (Q735).
+ *
+ * **Segment-wise and never by string** (ADR 0044 rule 3): a segment holds no `.`, so two keys of `depth` segments are
+ * equal exactly when their segments are — `1` and `10` stay distinct, and `1.0` at depth 1 is `1`. At depth 0 every path
+ * has the one key `''`.
+ */
+export declare function visibilityKey(path: string, depth: number): string | null;
 /**
  * Which region a node belongs to, and via which branch — the value the task id's
  * `branchPath` segment is derived from (`spec/task-id.md` section 1).

package/dist/types/src/driver/driver.d.ts

@@ -12,7 +12,7 @@
  * driver turns out to need a second copy of run truth, that is a finding about the
  * spec rather than a thing to build.
  */
-import type { Finding, FlowDefinition, GateTypes, Languages, NodeTypes, Pools, TerminalState, Workers } from '../definition/types.js';
+import type { Finding, FlowDefinition, FlowNode, GateTypes, Languages, NodeTypes, Pools, TerminalState, Workers } from '../definition/types.js';
 import { type SchemaFinding } from '../definition/schema.js';
 import { type LogRecord, type OutcomeRecord } from './log.js';
 import { type PredicateRegistry } from './routing.js';
@@ -377,6 +377,68 @@ export declare class ResumeRefused extends Error {
  * function, two callers, so the two cannot refuse different checkpoints.
  */
 export declare function resumeRefusal(definition: FlowDefinition, checkpoint: unknown, runId?: string): ResumeRefused | null;
+/**
+ * **What a reading asks about** — `RN-R45`, P42 decision 2 and stop-and-ask (c1). A node id and a branch path, for ANY node
+ * kind the definition has; a node id ALONE, which asks for every path the run reached it on (decision 4); or a task id —
+ * a task's or an ask's — which names both, as `spec/task-id.md` mints it (attempt `0`).
+ */
+export type InputTarget = {
+    readonly taskId: string;
+} | {
+    readonly nodeId: string;
+    readonly branchPath?: string;
+};
+/**
+ * **Which value a node was handed** — `RN-R45`, P42 decision 3: a task's `envelope` (`{ settings, input, transform? }`,
+ * `FD-C5`, `FD-C6` — what `dispatch` built for `createTask`, before any transform); the value `enter` composed for an ask,
+ * a gate, a fanout, a map or an end (`received`); and for a JOIN, an `arrival` at an arriving branch's path — what that
+ * branch carried in, a LATE arrival after an early firing included — or the `collection` it handed on when it fired, at
+ * its opener's path.
+ */
+export type HandedAs = 'envelope' | 'received' | 'arrival' | 'collection';
+/** **One thing a node was handed, on one branch path** — `RN-R45`. */
+export interface NodeInput {
+    readonly nodeId: string;
+    readonly kind: FlowNode['kind'];
+    /** The branch path it was handed on — a task's and an ask's the one their id carries; a join's arrival the arriving branch's. */
+    readonly branchPath: string;
+    readonly handed: HandedAs;
+    /**
+     * The value, AS THE READING'S DRIVER BUILT IT: not copied again and not frozen beyond what the composition already
+     * froze — a value a `needs` reference composed is that driver's shared frozen copy (ADR 0126), the rest is the caller's
+     * own. It reaches nothing a live run holds: the reading's driver is its own and is dropped when the reading returns.
+     */
+    readonly value: unknown;
+}
+/**
+ * **Why a reading has no answer** — `RN-R45`, P42 decision 5. Returned, never thrown.
+ *
+ * | reason | when | `index` |
+ * |---|---|---|
+ * | `format` | the run is not `{ header, events[] }`, its `header.format` is not {@link CHECKPOINT_FORMAT}, its header's three fields are not format 1's types, its `runId` is not a run id (`ID-R2`), or its entry payload does not clone — `resumeRefusal`'s header half, the one function | `null` |
+ * | `flow` | `header.flowId` or `header.version` is not the definition's — no migration | `null` |
+ * | `unknown` | the target cannot name anything in this run: a node id the definition lacks, a branch path that is not `spec/task-id.md`'s grammar, or a task id that does not parse, names another run, an attempt other than `0`, or a node that is neither a task nor an ask | `null` |
+ * | `not-reached` | the replay did not hand the target anything within the stored prefix a reading verifies — which ends at the first `halted`, `stopped` or `cancelRequested` element, or at the stored events' end | the prefix's length |
+ * | `diverged` | the replay produced something other than a stored element BEFORE it reached the target — `RN-R20`'s refusal, by its position | that position |
+ */
+export type InputRefusalReason = 'format' | 'flow' | 'unknown' | 'not-reached' | 'diverged';
+/** **What a reading returns** — every answer for its target, in the order the replay reached them, or why there is none. */
+export type InputReading = {
+    readonly ok: true;
+    readonly inputs: readonly NodeInput[];
+} | {
+    readonly ok: false;
+    readonly reason: InputRefusalReason;
+    readonly index: number | null;
+    readonly message: string;
+};
+/**
+ * **What a reading builds its driver from** — the `DriverOptions` a run's routing reads, and nothing else (`RN-R45`, P42
+ * decision 1): the registry's members — `runtime.registry` IS this minus `joinPolicy` — and the three options a runtime
+ * adds. **No callback, no scheduler, no `createTask`, no run id**: a member not named here is not read, so a reading cannot
+ * call a consumer. `joinPolicy` omitted is `liveToken`, as `runtime.start` and `runtime.resume` default it.
+ */
+export type InputOfOptions = Pick<DriverOptions, 'predicates' | 'workers' | 'nodeTypes' | 'pools' | 'groups' | 'languages' | 'gateTypes' | 'joinPolicy' | 'defaultRetryPolicy' | 'validateBoundaries'>;
 /**
  * A settlement carrying THIS driver's run id for a task it never dispatched —
  * `ID-R4`, and the inbound counterpart of `ID-R1`
@@ -1054,7 +1116,8 @@ export declare class Driver {
      *   - **`held`** — map id → the instance's branch path → its item. Written by the MAP ARM, where the instance opens —
      *     by a run and by a resume's replay alike, so a replay REBUILDS it (`RN-R19`; P38's brief: *taken at rest*, never by
      *     a caller's call) — **BY REFERENCE to the element the map received** (the driver's own: an edge-hop clone, or a
-     *     `needs` composition's per-key copy), and as its OWN copy only where `kept` says that element is the caller's
+     *     `needs` composition's value — since W202 an element of a reference's SHARED copy, which this keeps alive while held),
+     *     and as its OWN copy only where `kept` says that element is the caller's
      *     (P35 (f)'s reason for `asked.input`). Every READ clones (`JP-R11`), so no node receives the held object.
      *     **Released when NOTHING of that instance may still be entered** — its own branch terminal (`branch.arrived`,
      *     `branch.lost` or `branch.exited`, `JP-R5`: one per opened branch) AND no branch of a region NESTED in it still live
@@ -1397,10 +1460,47 @@ export declare class Driver {
     private replayStored;
     /** One fed element — a settlement, a resolution, an earlier resume, a stop, a pause, an unpause or an attempt — at stored position `i`. */
     private feedOne;
-    /** The listener's boundary, for the replay: a refusal routing raises stops the run (`OR-R10`); a refused resume passes through. */
+    /**
+     * The listener's boundary, for the replay: a refusal routing raises stops the run (`OR-R10`); a refused resume passes
+     * through — and so does a reading's cut (`InputCut`, W205), which is no refusal and halts nothing.
+     */
     private feed;
     /** `RN-R20`'s refusal, naming the position and both elements there. */
     private diverged;
+    /**
+     * **A cut site offers what a node was handed** (`RN-R45`, W205). An offer for another path is dropped. `own` is the
+     * position of the node's OWN element where it is already appended — a task's `dispatched`, a join's firing — and `null`
+     * where it is the NEXT append, which `append` confirms (`Reading.pending`). Either way it is TAKEN only at a STORED
+     * position, so a composition whose element lies past the prefix the reading verifies is never answered.
+     */
+    private offer;
+    /** **An offer taken** — kept, and for a target with a path the replay ends HERE: nothing after it is replayed (`InputCut`). */
+    private take;
+    /**
+     * **A READING — what a node was handed, by replaying the run to that node's composition** — `RN-R45`, W205,
+     * [ADR 0128](../../doc/decisions/0128-what-a-node-was-handed-is-read-by-replaying-the-run-to-its-composition.md), P42
+     * decisions 1-7. The export {@link inputOf} and `RunHandle.inputOf` are this and nothing else. In order:
+     *
+     *   1. **The header**, refused by `resumeRefusal`'s own header half (`format`, `flow`) — never its halt half.
+     *   2. **The target**, refused `unknown` where it cannot name anything in this run.
+     *   3. **A driver built exactly as `runtime.resume` builds one** (`RN-R25`) — the definition, the registry's members, a
+     *      `joinPolicy` defaulting to `liveToken` — with NO callback and a scheduler that is handed nothing (`DEAF_SCHEDULER`).
+     *   4. **The replay** (`readStep`) over the stored PREFIX it can verify, the cut armed: it stops at the target's
+     *      composition and returns what it found.
+     *
+     * Private and STATIC, so the export and the handle reach one road, and a test reaches the reading's own driver — its
+     * count — by a cast (ADR 0121 rule 7): `driver` is `null` where a refusal came before one was built.
+     */
+    private static read;
+    /**
+     * **The reading's replay** — `resume()`'s first half (`resumeStep` to `replayStored`) with the cut armed, and nothing of
+     * its second: no in-flight set, no `resumed`, nothing handed on. **The prefix it verifies ENDS at the first `halted`,
+     * `stopped` or `cancelRequested` element** (P42 decision 5): after one a halted driver composes nothing more, whether the
+     * replay regenerates it (a predicate's throw) or cannot (a consumer's callback, a refused result, an owner's call) —
+     * what follows is `not-reached`, never `diverged` (P42 retro (a1) corrected the reason). Everything
+     * before is compared as `RN-R20` compares it.
+     */
+    private readStep;
     /**
      * **What is IN FLIGHT: dispatched, and no settlement in the log** — `RN-R21`, in dispatch order. A
      * `user_action` settlement IS a settlement: a parked task is waiting on a person, not on a worker, and
@@ -1705,7 +1805,8 @@ export declare class Driver {
      * described **today** before this method existed, and this adds **no retention**.
      * *(Q19 is RESOLVED since W53 —
      * [ADR 0046](../../doc/decisions/0046-a-run-retains-what-its-tasks-returned-and-a-region-releases-its-collection-when-its-join-becomes-terminal.md)
-     * — and `RN-R13` names `outputsCache` by id: it holds results **by reference only**,
+     * — and `RN-R13` names `outputsCache` by id: it holds results **by reference** — and since W202 (ADR 0126) one shared
+     * COPY per output a reference has read, the one thing in it that is not the log's object,
      * asserted by IDENTITY at ladder L2 rather than by a byte count, because a
      * reachability SET cannot tell an alias from a copy. W53's readers found that
      * from both ends — the rule's stated test returned a third name on a `needs`
@@ -1733,6 +1834,11 @@ export declare class Driver {
      * node or an edge that declares a `needs` asks, and a run that declares none never builds it.
      */
     private outputs;
+    /**
+     * The projection, made empty on first need and NOT caught up — `outputs()` catches it up; a `"$payload"` read, which
+     * reads no output, only needs somewhere to keep its shared copy (W202).
+     */
+    private cache;
     /**
      * **One task's entry, made what its effective outcome now says** — `outputs()`'s catch-up, for a task one of whose records
      * was just read. An entry is `{ path, result }` with `result` the record's own object (`RN-R13`); a node's list is kept
@@ -1747,12 +1853,42 @@ export declare class Driver {
      * that LOSES its effective outcome is removed — **reachable**: `ID-R4` asks only whether a settlement's id was dispatched,
      * so a settlement event repeated for a settled task is appended, and a `done` then a `user_action` leaves the task with
      * none (W195's conformity reader, C4; `test/driver/log-view.test.ts` drives it and the resolution that places it again).
+     *
+     * **Both a replacement and a removal let go of the entry OBJECT, and with it the entry's shared copy** (W202, ADR 0126,
+     * `OutputEntry.shared`): a replaced output's next read makes a new copy of the new result, and a removed one's copy is
+     * held nowhere — `RN-R13`'s v0.33 term, released with what it belongs to (ADR 0046).
      */
     private place;
+    /**
+     * **One entry's change carried into every index built for its node** — W199, ADR 0124: called by `place` at each of
+     * its cases (a first entry, an append, an insertion at a first-record position, a replacement in place, a removal), so
+     * the index is caught up exactly when `byNode` is and can say nothing `byNode` does not. `was` is the entry leaving
+     * (`null` for an insertion), `now` the one arriving (`null` for a removal); a replacement keeps its path, so its
+     * position. A group is ordered by PATH, not by first record, so where `byNode` inserted mid-list the group finds its own
+     * place by a binary search. An entry with fewer than `depth` segments is visible to no reader at that depth and is filed
+     * nowhere.
+     */
+    private reindex;
+    /**
+     * **A node's outputs grouped for readers at `depth`** — built on the first read at that depth from the node's current
+     * entries (each one examined), each group sorted ONCE, and from then on kept by `reindex`.
+     */
+    private groupsOf;
+    /** The depth `reader` and `target` share — `sharedRegionDepth`, a graph fact, asked once per pair. */
+    private depthOf;
+    /**
+     * **The outputs of `nodeId` visible to `atNodeId` at `here`, in `compareBranchPaths` order** — W199, ADR 0124: ADR
+     * 0044's predicate answered by a LOOKUP. The predicate is `visibilityKey(here, d) === visibilityKey(path, d)` at the depth
+     * `d` the two share (`outputIsVisible`), so the visible outputs are exactly the group filed under the reader's key: what
+     * the filter over every output and the sort of its survivors returned until W199, found in the cost of its answer.
+     * **The index's own list, never handed out** — the caller maps it to copies.
+     */
+    private visibleOutputs;
     /**
      * The projection above, CAUGHT UP to `at` — `RN-R13` v0.30, ADR 0121 (W195). **Not run state and not a second copy of
      * it**: `byNode`'s entries hold each result BY REFERENCE (the log record's own object) — so it is a holder of results and
-     * never a copy — `tasks` is one slot per task id
+     * not a copy of them; since W202 an entry a reference has read also holds its ONE shared copy (`OutputEntry.shared`,
+     * `RN-R13` v0.33), and `payload` the run's payload's — `tasks` is one slot per task id
      * read — its node, its path, its first-record position and its current entry — and `orders` the same positions, per
      * node, parallel to its list. Everything here is the merge `effectiveOutcome` computed from the task's own records at the moment they were
      * read, and `at` says which records have been; so there is nothing here that could disagree with the log. `ADR 0014`'s
@@ -1783,7 +1919,7 @@ export declare class Driver {
      *
      * **Extracted by [W42](../../doc/work-items/w42-what-a-decision-sees.md) rather
      * than copied.** An EDGE's `needs` resolves by exactly these rules — same grammar,
-     * same visibility predicate, same order, same per-key copy — and the ONE difference
+     * same visibility predicate, same order, same shared copy (since W202, ADR 0126) — and the ONE difference
      * is that an edge has no `"."` form, which is a property of the caller rather than
      * of this expression. *Two callers, one resolution, so a change to what a reference
      * means cannot mean two different things to a worker and to a predicate*, which is
@@ -1794,12 +1930,21 @@ export declare class Driver {
      * @throws UnresolvedReference — `FD-R3`.
      */
     private resolveReference;
+    /** **An output entry's shared copy**, made at its first read and kept on the entry (`OutputEntry.shared`) — counted. */
+    private sharedOf;
+    /**
+     * **`"$payload"`'s value in a run: the run's ONE shared copy** — W202, ADR 0126, P41 decision 2: `sharedCopy` of the
+     * header's `entryPayload` (`runPayload()`), made at the first `"$payload"` read of the run — or of a resume, whose driver
+     * is a new one — and handed to every reader at both sites. Counted once. `FD-R4` does not come here: it composes from
+     * the caller's own value, before a header exists, and keeps its clone.
+     */
+    private sharedPayload;
     /**
      * **The value the run ENTERED with — the header's copy** (`RN-R15`, P38 fact 4 and (f)): taken at `start()` from the
      * caller's payload, or on a resume from the stored header, and held for the life of the run. What a `"$payload"`
      * reference composes from, in both doors; `FD-R4` hands the caller's own value instead, because it runs before the
-     * header exists. Read only where a node or an edge composes the token — a run declaring none never clones it
-     * (P38 decision 2). The header is set before the first `enter` in both doors, so `null` here is not a run.
+     * header exists. Read only where a node or an edge composes the token — a run declaring none never copies it
+     * (P38 decision 2); since v0.47 read ONCE, by `sharedPayload`, whose one shared copy every reader is handed. The header is set before the first `enter` in both doors, so `null` here is not a run.
      */
     private runPayload;
     /**
@@ -1825,8 +1970,8 @@ export declare class Driver {
      * received anyway* is `ctx.outcome`, which it already has. So there is no
      * `edgeValue` parameter here and none is derivable — see the call site. **A
      * `"$payload"` key needs none either** (v0.44, ADR 0117): it is not derived from what
-     * the NODE received but read from the run's header, `runPayload()` above, its own
-     * copy per key per read.
+     * the NODE received but read from the run's header — since v0.47 the run's ONE shared
+     * copy of it, `sharedPayload()` above, the object a worker's `"$payload"` key is handed (ADR 0126).
      *
      * @throws UnresolvedReference — `FD-R3`, from the same expression a node's does.
      */
@@ -2128,3 +2273,33 @@ export declare class Driver {
     effectiveOutcomeOf(taskId: string): OutcomeRecord | null;
     terminalStateOf(taskId: string): TerminalState | null;
 }
+/**
+ * **What a node was HANDED, read after the fact by replaying the run to that node's composition** — `RN-R45`, W205,
+ * [ADR 0128](../../doc/decisions/0128-what-a-node-was-handed-is-read-by-replaying-the-run-to-its-composition.md), P42
+ * (a1)-(d1) and decisions 1-6. `run` is a run's stored header and events — `driver.checkpoint()`, or what a store appended
+ * (`RN-R14`, `RN-R18`); `options` the registry and options the run's driver was built with (`runtime.registry`, plus its
+ * `joinPolicy` where it was not `liveToken`).
+ *
+ * **It IS the driver's composition, not a second one**: a driver built for the stored run, deaf — no callback, nothing
+ * handed to a scheduler — replays the stored events through `enter`, `compose` and `dispatch` exactly as a resume does and
+ * stops at the target's composition. So an answer is EXACT, and it costs the run's prefix up to the target — O(run) at
+ * worst, never O(the answer) — and a reading re-runs the run's predicates and gate types, as a resume does (ADR 0002 rule
+ * 4, Q9: an impure one diverges, or answers what its re-run computes).
+ *
+ * | target | kind | `inputs` |
+ * |---|---|---|
+ * | `{ taskId }`, or `{ nodeId, branchPath }` | a task | ONE `envelope`: `{ settings, input, transform? }` — its one dispatch's, retries and a resolution included; BEFORE its transform (ADR 0051) |
+ * | the same | an ask | ONE `received` — equal to its `asked` element's `input` |
+ * | `{ nodeId, branchPath }` | a gate, fanout, map or end | ONE `received` — what `enter` composed for it on that path |
+ * | `{ nodeId, branchPath }` | a join, at an ARRIVING branch's path | ONE `arrival` — what that branch carried in, a late arrival included |
+ * | `{ nodeId, branchPath }` | a join, at its OPENER's path | ONE `collection` — what it handed on when it fired |
+ * | `{ nodeId }` | any | EVERY one of the above the replay reached, in the order it reached them — one replay to the stored end |
+ *
+ * A path target answers the FIRST composition on its path: an end shared by two sibling regions can be reached twice on one
+ * path (`end` is exempt from `FD-V19`), and only the node id alone lists both.
+ *
+ * **Never throws for the run or the target** — `InputReading`'s refusals; it throws what `new Driver` throws for a
+ * definition or a registry that cannot run (`InvalidDefinition`, `MissingJoinPolicy`, a `RegistryError`), as a resume does.
+ * **What it does not detect**: a definition or a registry changed AFTER the target — the cut verifies the prefix it replays.
+ */
+export declare function inputOf(flow: FlowDefinition, options: InputOfOptions, run: Checkpoint, target: InputTarget): InputReading;

package/dist/types/src/scheduler/runtime.d.ts

@@ -64,7 +64,7 @@
 import { FyflowScheduler } from 'fyflow-scheduler';
 import type { ResourceGroup, WorkerManager } from 'fyflow-scheduler';
 import { Driver } from '../driver/driver.js';
-import type { Checkpoint, CheckpointHeader, DriverOptions, RunStopOptions } from '../driver/driver.js';
+import type { Checkpoint, CheckpointHeader, DriverOptions, InputReading, InputTarget, RunStopOptions } from '../driver/driver.js';
 import type { NodeRun, RunOutcome, RunState } from '../fold/run-state.js';
 import type { Finding, FlowDefinition, JsonSchema, RegistryCode, RegistryDocument, ResolvedPool, ResolvedRegistry, RetryPolicy, TaskNode } from '../definition/types.js';
 import type { PoolFactory } from './bootstrap.js';
@@ -361,6 +361,22 @@ export interface RunHandle {
      * materialising the rest (`RN-R44`); the first read of an entry freezes it once, O(the entry). `null` for a task the run never dispatched or asked, whatever the id names (`toString` included).
      */
     node(taskId: string): NodeRun | null;
+    /**
+     * **What a node of this run was HANDED, read by replaying the run so far to that node's composition** — `RN-R45`, W205,
+     * [ADR 0128](../../doc/decisions/0128-what-a-node-was-handed-is-read-by-replaying-the-run-to-its-composition.md), P42
+     * decision 7: the root export {@link inputOf} over THIS run's own `driver.checkpoint()`, with the registry, `joinPolicy`
+     * and options this runtime built the run's driver with — one function, so a live answer and a stored one cannot differ.
+     * A task's answer is its dispatch's envelope `{ settings, input, transform? }`; an ask's, a gate's, a fanout's, a map's
+     * and an end's what reached it; a join's an arrival at an arriving branch's path or its collection at its opener's; a
+     * node id ALONE every path the run reached it on. A target not yet reached is `not-reached`.
+     *
+     * **Synchronous, O(the run's prefix), never cached**: each call copies the run's events (`checkpoint()`) and replays them
+     * on a driver of its own, deaf — nothing is appended to this run, nothing handed to a scheduler, no callback called, and
+     * no object of this run's reachable through an answer. Read it at a quiescent point (`RN-R12`); mid-step it reads the
+     * prefix appended so far. On a released run (`done` settled) it answers from what the run delivered. **BREAKING in
+     * 0.10.0 for code that BUILDS a `RunHandle`** (P42 decision 9) — a new member, as `state` was in 0.9.0.
+     */
+    inputOf(target: InputTarget): InputReading;
 }
 export interface Runtime {
     /** **Exactly the object this runtime hands its own drivers** (decision 14) — spread it into `new Driver(…)` beside a `runId`, a `scheduler` and a `joinPolicy` and you have built what `start` builds. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fyflow-orchestration",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Flow orchestration over fyflow-scheduler: sequence, decision, fan-out and join",
   "keywords": [
     "workflow",