fyflow-orchestration 0.9.1 → 0.11.0

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-I3KDEOLB.js";
+} from "../chunks/chunk-5CVSWDCB.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/index.d.ts

@@ -3,6 +3,7 @@ export * from "./src/definition/regions.js";
 export * from "./src/definition/validate.js";
 export * from "./src/definition/schema.js";
 export * from "./src/definition/registry.js";
+export * from "./src/definition/definition-schema.js";
 export * from "./src/definition/witness.js";
 export * from "./src/definition/wiring.js";
 export * from "./src/definition/assist.js";

package/dist/types/src/definition/definition-schema.d.ts

@@ -0,0 +1,23 @@
+import { type Registry } from './types.js';
+/**
+ * **What `definitionSchema()` returns** — a plain, JSON-serialisable JSON Schema draft 2020-12 document, owned by the
+ * caller: a new value on every call, so mutating one changes no other.
+ */
+export type DefinitionSchema = {
+    $schema: string;
+} & Record<string, unknown>;
+/**
+ * **A flow definition's shape as a JSON Schema, draft 2020-12** — P43 (a1), ADR 0132; the registry form W211's. A
+ * plain object, a NEW one on every call, JSON-serialisable.
+ *
+ * - **No argument: the STATIC shape.** It carries every rule a node, an edge or a value decides by its own shape and
+ *   names `validateDefinition` as the authority for the rest; what it refuses, `validateDefinition` refuses under
+ *   EVERY registry.
+ * - **A registry: the shape SPECIALISED to it** (`spec/flow-definition.md` section 1, v0.51). The registry is first held
+ *   to `checkRegistry` — the check `new Driver` runs over the registry it is handed — and one that check refuses THROWS
+ *   that refusal, never specialised. Then the static shape gains what the registry decides of ONE node: a task's
+ *   `type`, `pool`, `settings`, a transform-only type's `transform`, `workerGroups`, `transform.lang`, a predicate
+ *   name, a gate's `type`, `settings` and — for a STATIC gate type — `route` (`specialise`, below). What it refuses,
+ *   `validateDefinition(flow, registry)` refuses against THAT registry.
+ */
+export declare function definitionSchema(registry?: Registry): DefinitionSchema;

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

@@ -38,10 +38,11 @@ export type TerminalState = 'done' | 'failed' | 'user_action' | 'cancelled';
  * | `"$payload"` | **the value the RUN entered with** — what `start()` was handed, from any node and any edge (v0.44, [ADR 0117](../../doc/decisions/0117-a-reference-may-name-what-reached-the-run.md)). Always there, so no `?` and no array form. `$` is outside `FD-V16`'s charset, and the whole `$` prefix is reserved: `"$item"` — a map instance's item — is W191's, and any other `$` spelling is `FD-V26` |
  * | `"score"` | that node's output **on this node's own branch path**. Exactly one, or the run stops (`FD-R3`) |
  * | `["score"]` | that node's outputs as an **array**, in ascending segment-wise-numeric `branchPath` order. Legal only where the reader is outside a region containing the named node (`FD-V28`) |
+ * | `"score!error"` | **that node's ERROR** rather than its result, on either form and with `?` last (`["score!error?"]`): the effective outcome's `error` string, `null` where it succeeded — v0.49, [ADR 0131](../../doc/decisions/0131-a-reference-may-name-a-nodes-error.md). Aimed as `"score"` is; `!` is outside `FD-V16`'s charset |
  *
  * **The array form uses JSON's own array syntax rather than a sigil**, so the
  * grammar invents tokens only for what has no node id: `"."`, the `?` modifier
- * (v0.13), and — v0.44 — the `$` prefix. *(This read *"exactly one invented token"*
+ * (v0.13), — v0.44 — the `$` prefix, and — v0.49 — the `!error` part. *(This read *"exactly one invented token"*
  * until v0.13 and stayed so until W190.)* A `string` covers every token, so the
  * TYPE does not move; `referenceTarget`'s parse does.
  */

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

@@ -19,6 +19,19 @@
  */
 import type { Finding, FlowDefinition, GateType, GateTypes, JsonSchema, StaticGateType, LanguageAdapter, Languages, NodeTypeEntry, NodeTypes, Pools, Registry, WorkerEntry, Workers } from './types.js';
 export { readKeyPath } from './condition.js';
+declare const KINDS: readonly ["task", "fanout", "map", "join", "end", "gate", "ask"];
+/**
+ * **`FD-V16`'s charset — a flow's and a node's id** ([spec/task-id.md](../../spec/task-id.md)'s) — v0.50 (W210,
+ * [ADR 0132](../../doc/decisions/0132-a-definitions-shape-is-a-schema-built-from-the-validator.md)), so
+ * `definitionSchema()` builds its `pattern` from the validator's expression. **A COPY** — `compile()` on it, or a
+ * consumer's edit, moves no verdict (W210's conformity reader, S2: the live object did).
+ */
+declare const ID_RE_COPY: RegExp;
+/** **The seven node kinds `FD-V24` admits** — v0.50 (W210, ADR 0132), for `definitionSchema()`'s `kind` enum; a FROZEN copy. */
+declare const KINDS_COPY: readonly (typeof KINDS)[number][];
+export { ID_RE_COPY as ID_RE, KINDS_COPY as KINDS };
+/** **The terminal states an edge's `on` may name** (`FD-V18`) — a copy of the validator's own list, v0.50 (W210, ADR 0132). */
+export declare const ROUTABLE_STATES: readonly string[];
 /**
  * **The six keys a `task` declares that an `ask` REFUSES, each by `FD-V47` and by nothing else** — v0.42, W179,
  * P35 stop-and-ask (a) and decision 6. Every one is read by a task's WORKER or its scheduler task — a type and its
@@ -49,6 +62,17 @@ export declare const TASK_KEYS_DECLARED: readonly string[];
  * P16 decision 3's silent-key hole one row over.
  */
 export declare const NODE_KEYS_DECLARED: Readonly<Record<string, readonly string[]>>;
+/**
+ * **The REQUIRED half of each kind's keys, the edge's and the document's** — `FD-V23`'s three lists, copied, v0.50
+ * (W210, [ADR 0132](../../doc/decisions/0132-a-definitions-shape-is-a-schema-built-from-the-validator.md)):
+ * `definitionSchema()` reads its `required` from these, so a key the validator starts requiring is one the schema
+ * requires, and a key it stops requiring one the schema stops requiring. Every document key is required.
+ */
+export declare const NODE_KEYS_REQUIRED: Readonly<Record<string, readonly string[]>>;
+/** The edge's required keys — `FD-V23`'s *an edge without `to`*, copied (v0.50, W210). */
+export declare const EDGE_KEYS_REQUIRED: readonly string[];
+/** The document's keys, every one required (`FD-V23`) and none other declared (`FD-V17`) — copied, v0.50 (W210). */
+export declare const DOC_KEYS_DECLARED: readonly string[];
 /**
  * **The two keys a `retryPolicy` carries, and no others** — `FD-V30`. The scheduler's own
  * constructor at 0.5.2 destructures exactly these; a key beside them is a typo the scheduler
@@ -324,6 +348,12 @@ export declare function settingsProblem(schema: JsonSchema | undefined, defaults
  * reads `conditional`. A `"."` may not carry one — it resolves to the edge's own
  * value, which is always there — and the remainder after the suffix is stripped must
  * still be an id, so `"?"`, `"n??"` and `".?"` are all `null` with no extra clause.
+ *
+ * **And since v0.49 the `!error` PART** — [ADR 0131](../../doc/decisions/0131-a-reference-may-name-a-nodes-error.md),
+ * P43 (c1): `"n!error"` names node `n`'s ERROR rather than its result, in both forms and with `?` (`"n!error?"`,
+ * `["n!error"]`, `["n!error?"]`). It is a fourth field, `part`, beside `form` and `conditional` and orthogonal to both —
+ * **present only on that form** — because it changes WHAT is read of the outputs and never which outputs are named:
+ * `FD-V27`-`FD-V29` aim it as the plain reference and the driver resolves it through the same index (P43 decision 5).
  */
 export declare function referenceTarget(ref: unknown): {
     form: 'self';
@@ -337,11 +367,20 @@ export declare function referenceTarget(ref: unknown): {
     form: 'item';
     node: null;
     conditional: false;
-} | {
+} | AimedReference | null;
+/**
+ * **A reference that AIMS at a node** — `"n"` or `["n"]`, either with `?`, and since v0.49 either naming the node's ERROR
+ * (`"n!error"`, `["n!error?"]`, …) — [ADR 0131](../../doc/decisions/0131-a-reference-may-name-a-nodes-error.md), P43 (c1).
+ * **`part` is PRESENT only on the error form**, so every spelling before v0.49 parses to the object it parsed to (P43
+ * prediction 3), and a reader that does not ask for `part` reads the error form as the node it aims at — which is what
+ * `FD-V27`-`FD-V29` are meant to do (P43 decision 5) and what a RESOLVER must not (`resolveReference`, the wiring check).
+ */
+export type AimedReference = {
     form: 'one' | 'all';
     node: string;
     conditional: boolean;
-} | null;
+    part?: 'error';
+};
 export declare function validateDefinition(doc: FlowDefinition, registry: Registry): Finding[];
 /** Convenience: the rule ids violated, deduplicated and sorted. */
 export declare function violatedRules(findings: Finding[]): string[];

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

@@ -127,7 +127,17 @@ export interface WiringVerdict {
     /** The relation's own reason, in the words `fact-3-controls.log` prints. */
     why: string;
     sample?: WiringSample;
+    /**
+     * **Why a `transform-fails` verdict failed — present on that kind and ABSENT on every other** (v0.48,
+     * [W208](../../doc/work-items/w208-a-transforms-cause-and-when-an-ask-was-asked.md), P43 (d1), decision 6): `'threw'` where the transform did not produce a result — the language's worker half failing to import, having
+     * no default export, its `compile` throwing or its `evaluate` throwing, alike — and `'schema'` where it produced one
+     * and the consumer's `inputSchema` refused it. `why` says the same in words and is unmoved; this says it as data.
+     * Additive in 0.11.0: `VerdictKind`, `VERDICT_KINDS` and every count are unmoved.
+     */
+    cause?: TransformFailureCause;
 }
+/** What a `transform-fails` verdict's {@link WiringVerdict.cause} names: the transform threw, or its result failed the consumer's schema. */
+export type TransformFailureCause = 'threw' | 'schema';
 export interface WiringReport {
     flowId: string;
     verdicts: WiringVerdict[];

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,9 +1834,14 @@ 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
+     * was just read. An entry is `{ path, result, error }` with `result` the record's own object (`RN-R13`) and `error` its string or `null` (v0.49, ADR 0131); a node's list is kept
      * in its tasks' FIRST-RECORD order, the order the rebuild grouped them in.
      *
      * **`!eff` — a suspended node contributes no entry.** The first record of a `user_action` task has none, and its
@@ -1747,6 +1853,10 @@ 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;
     /**
@@ -1777,7 +1887,8 @@ export declare class Driver {
     /**
      * 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
@@ -1808,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
@@ -1819,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;
     /**
@@ -1850,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.
      */
@@ -2153,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/fold/run-state.d.ts

@@ -124,6 +124,14 @@ export interface NodeRun {
      * additive: a consumer building a `NodeRun` literal is unaffected.
      */
     input?: unknown;
+    /**
+     * **WHEN an ask was asked** — `RN-R36`, v0.35,
+     * [ADR 0130](../../doc/decisions/0130-a-regenerated-asked-element-keeps-the-stored-runs-time.md), W208, P43 (e1): its
+     * `asked` element's `observedAt`, KEPT after the answer as {@link NodeRun.input} is. **Present only on an ask's node, and
+     * only where its element carried one** — an element written before 0.11.0 carries none, so its entry has none. OPTIONAL
+     * and additive.
+     */
+    askedAt?: number;
 }
 export interface RegionRun {
     /** Branch paths opened, in the order the driver emitted them (`JP-R5`). */
@@ -351,11 +359,20 @@ export type FoldInput = {
  * (`RN-R19`): the replay re-enters the ask and compares the input it composes with the stored one (`RN-R20`). **The
  * first kind whose payload is a value of ANY shape**, so it is deep-copied on the way out (`freezeInput`, `RN-R17`).
  * **A new kind, BREAKING in 0.8.0 for a consumer switching on `kind` exhaustively** (P35 decision 8).
+ *
+ * **`observedAt` — WHEN the ask was asked** (v0.35, `RN-R37`,
+ * [ADR 0130](../../doc/decisions/0130-a-regenerated-asked-element-keeps-the-stored-runs-time.md), W208, P43 (e1)): the
+ * driver's injected `now` where the branch entered the ask — the clock an outcome record's `observedAt` is read from.
+ * **A replay KEEPS the stored run's** (`RN-R19`): within the stored prefix the regenerated element takes the stored
+ * element's `observedAt`, or carries none where the stored one carries none, so it compares equal (`RN-R20`); past the
+ * stored tail it is `now()`. **OPTIONAL**: an element written before 0.11.0 has none, and a consumer building one
+ * literally is unaffected. `CHECKPOINT_FORMAT` does not move.
  */
  | {
     kind: 'asked';
     taskId: string;
     input: unknown;
+    observedAt?: number;
 } | {
     kind: 'pathEnded';
     reason: 'end' | 'no-eligible-edge';

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.1",
+  "version": "0.11.0",
   "description": "Flow orchestration over fyflow-scheduler: sequence, decision, fan-out and join",
   "keywords": [
     "workflow",
@@ -124,6 +124,7 @@
   },
   "license": "MIT",
   "devDependencies": {
+    "@cfworker/json-schema": "4.1.1",
     "@types/node": "^24.13.3",
     "esbuild": "^0.25.12",
     "fyflow-scheduler": "0.6.0",