fyflow-orchestration 0.9.1 → 0.10.0

package/dist/browser/chunks/{chunk-I3KDEOLB.js → chunk-NA6QQAZ2.js}

@@ -2764,6 +2764,74 @@ function isTerminalEvent(e) {
   return TERMINAL_EVENTS.includes(e.type);
 }
 
+// src/fold/policies.ts
+var arrivalCount = {
+  id: "arrival-count",
+  // **`region` is deliberately unread.** It was the source of `need` and is now
+  // the source of nothing: `branches` cannot answer *how many branches did this
+  // region open* for a map, and a policy that read it for a fanout and counted for
+  // a map would be branching on the node kind — which it cannot see
+  // ([Q159](../../doc/questions/q159.md)) and, per that row, should not.
+  open: () => ({ need: 0, arrived: [] }),
+  step: (s, e) => {
+    if (e.type === "branch.opened") return { ...s, need: s.need + 1 };
+    if (e.type !== "branch.arrived" || s.arrived.includes(e.branchPath)) return s;
+    return { ...s, arrived: [...s.arrived, e.branchPath] };
+  },
+  // **`s.need > 0` is a PIN, not a refinement**, and it is exactly `JP-R8`'s own
+  // *"having been positive"* argument in the policy that argument was denied to.
+  // A bare `arrived.length >= need` is true at `0 >= 0`, so without it `open`
+  // itself reports `satisfied` — and at a map of zero items this policy would fire
+  // a join **no branch ever reached**, which is character for character what
+  // [ADR 0025](../../doc/decisions/0025-the-zero-arrival-join-is-reportable-and-arrival-counting-is-not-repaired.md)
+  // REFUSED `JP-R7`'s variant for. It is vacuous on every `fanout` region, because
+  // `FD-V9`'s floor puts `need` at 2 or more.
+  status: (s) => s.need > 0 && s.arrived.length >= s.need ? "satisfied" : "waiting",
+  // Never `unsatisfiable`: this policy has no way to know a join can never fire,
+  // which is precisely the argument Q4 states as a testable claim. **At a map of
+  // zero items it says `waiting`, exactly as the other two do** — the region is
+  // reported dead by the FOLD (`RN-R10`, via the `regionEntered` input) rather
+  // than by any policy, which is `spec/join-policy.md` section 5's own case.
+  describe: (s) => ({ need: s.need, arrived: [...s.arrived] })
+};
+var liveToken = {
+  id: "live-token",
+  open: () => ({ live: 0, positive: false }),
+  step: (s, e) => {
+    if (e.type === "branch.opened") return { live: s.live + 1, positive: true };
+    if (e.type === "branch.arrived" || e.type === "branch.exited" || e.type === "branch.lost") {
+      return { ...s, live: s.live - 1 };
+    }
+    return s;
+  },
+  status: (s) => s.positive && s.live === 0 ? "satisfied" : "waiting",
+  // NOT requiring an arrival before reporting `satisfied`, and NOT returning
+  // `unsatisfiable` on zero-with-no-arrivals. That is JP-R8's third policy, and
+  // it is the one that would hand live-token a graceful answer arrival-count is
+  // structurally denied — which is the asymmetry JP-R8 exists to forbid.
+  describe: (s) => ({ live: s.live, positive: s.positive })
+};
+var liveTokenRequiringArrival = {
+  id: "live-token-requiring-arrival",
+  open: () => ({ live: 0, positive: false, arrived: 0 }),
+  step: (s, e) => {
+    if (e.type === "branch.opened") return { ...s, live: s.live + 1, positive: true };
+    if (e.type === "branch.arrived") return { ...s, live: s.live - 1, arrived: s.arrived + 1 };
+    if (e.type === "branch.exited" || e.type === "branch.lost") return { ...s, live: s.live - 1 };
+    return s;
+  },
+  status: (s) => {
+    if (!s.positive || s.live !== 0) return "waiting";
+    return s.arrived > 0 ? "satisfied" : "unsatisfiable";
+  },
+  describe: (s) => ({ live: s.live, positive: s.positive, arrived: s.arrived })
+};
+var POLICIES = {
+  "arrival-count": arrivalCount,
+  "live-token": liveToken,
+  "live-token-requiring-arrival": liveTokenRequiringArrival
+};
+
 // src/driver/driver.ts
 import { FyflowTask } from "fyflow-scheduler";
 var InvalidDefinition = class _InvalidDefinition extends Error {
@@ -2879,6 +2947,12 @@ var ResumeRefused = class extends Error {
   }
 };
 function resumeRefusal(definition, checkpoint, runId) {
+  const header = headerRefusal(definition, checkpoint, runId);
+  if (header !== null) return header;
+  const cp = checkpoint;
+  return haltRefusal(cp.events);
+}
+function headerRefusal(definition, checkpoint, runId) {
   const cp = checkpoint;
   const h = typeof cp === "object" && cp !== null ? cp.header : void 0;
   if (typeof h !== "object" || h === null || !Array.isArray(cp.events)) {
@@ -2916,24 +2990,27 @@ function resumeRefusal(definition, checkpoint, runId) {
       `ResumeRefused (flow): the checkpoint is of flow ${JSON.stringify(h.flowId)} version ${JSON.stringify(h.version)}, and this driver runs "${definition.flowId}" version ${definition.version}. There is no migration (P23 decision 7): a checkpoint resumes against the definition that produced it, and a changed flow is a new version.`
     );
   }
-  const at = cp.events.findIndex((e) => {
+  return null;
+}
+function haltRefusal(events) {
+  const at = events.findIndex((e) => {
     const k = e?.kind;
     return k === "halted" || k === "stopped";
   });
   if (at >= 0) {
-    const e = cp.events[at];
+    const e = events[at];
     return new ResumeRefused(
       "halted",
       at,
       `ResumeRefused (halted): the stored run was HALTED by a refusal \u2014 its element at position ${at} is \`${String(e.kind)}\`${e.kind === "stopped" ? " (the name 0.7.0 wrote for `halted`, ADR 0102)" : ""} (${JSON.stringify(e.reason)}). A halted run is not resumable (P23 decision 10): the refusal that halted it would halt it again, and the one class whose cause never reached the log \u2014 a result OR-R6 refused \u2014 cannot be regenerated at all.`
     );
   }
-  const c = cp.events.findIndex((e) => {
+  const c = events.findIndex((e) => {
     const x = e;
     return x?.kind === "cancelRequested" || x?.kind === "outcome" && x.record?.terminalState === "cancelled";
   });
   if (c >= 0) {
-    const e = cp.events[c];
+    const e = events[c];
     const what = e?.kind === "cancelRequested" ? `the request of ${JSON.stringify(e.actor)} to cancel it (\`cancelRequested\`)` : `the settlement of ${JSON.stringify(e?.record?.taskId)} as \`cancelled\``;
     return new ResumeRefused(
       "cancelled",
@@ -2993,6 +3070,25 @@ function describeElement(e) {
   }
   return s.length > 160 ? `${s.slice(0, 157)}...` : s;
 }
+function deepFreeze(root) {
+  const stack = [root];
+  while (stack.length > 0) {
+    const v = stack.pop();
+    if (v === null || typeof v !== "object" || ArrayBuffer.isView(v) || v instanceof RegExp || Object.isFrozen(v)) continue;
+    Object.freeze(v);
+    const proto = Object.getPrototypeOf(v);
+    if (!Array.isArray(v) && proto !== Object.prototype && proto !== null) continue;
+    for (const k of Object.keys(v)) {
+      const x = v[k];
+      if (x !== null && typeof x === "object") stack.push(x);
+    }
+  }
+}
+function sharedCopy(v) {
+  const copy = cloneValue(v);
+  deepFreeze(copy);
+  return copy;
+}
 var NO_OUTPUTS = Object.freeze([]);
 function groupPosition(group, path) {
   let lo = 0;
@@ -3005,6 +3101,15 @@ function groupPosition(group, path) {
   }
   return lo;
 }
+var InputCut = class extends Error {
+};
+var DEAF_SCHEDULER = {
+  addTask() {
+    throw new Error("a reading hands nothing to a scheduler (RN-R45, ADR 0128) \u2014 this is a defect in the driver");
+  },
+  addEventListener() {
+  }
+};
 var UndispatchedTask = class extends Error {
   constructor(message, options) {
     super(message, options);
@@ -3144,7 +3249,7 @@ var Fifo = class {
     for (let i = this.head; i < this.items.length; i += 1) yield this.items[i];
   }
 };
-var Driver = class {
+var Driver = class _Driver {
   /**
    * `OR-R7` — nothing outside the inbound API writes to run state. Private, and
    * `snapshot()` is the only way out: a public `readonly` array still accepts
@@ -3276,7 +3381,8 @@ var Driver = class {
    *   - **`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
@@ -3698,7 +3804,7 @@ var Driver = class {
         const worker = type?.worker === void 0 ? void 0 : this.workers.get(type.worker);
         const schema = worker?.inputSchema;
         if (schema === void 0) continue;
-        const received = this.compose(n, value, EMPTY_INDICES, payload, () => value);
+        const received = this.compose(n, value, EMPTY_INDICES, () => cloneValue(payload), () => value);
         const fs = findings(schema, received);
         if (fs.length) {
           throw new BoundaryRefused(
@@ -3795,7 +3901,7 @@ var Driver = class {
     const entryPayload = structuredClone(checkpoint.header.entryPayload);
     this.header = { format: CHECKPOINT_FORMAT, runId: this.runId, flowId: this.def.flowId, version: this.def.version, entryPayload };
     this.started = true;
-    const replay = { stored, feeding: -1, held: /* @__PURE__ */ new Map() };
+    const replay = { stored, feeding: -1, held: /* @__PURE__ */ new Map(), reading: null };
     this.replay = replay;
     try {
       this.replayStored(stored);
@@ -3860,6 +3966,7 @@ var Driver = class {
       if (!isFed(e)) continue;
       if (this.inputs.length !== i) throw this.diverged(this.inputs.length, "the replay produced nothing there");
       replay.feeding = i;
+      if (replay.reading !== null) replay.reading.fed += 1;
       this.feed(() => this.feedOne(e, i));
     }
     if (this.inputs.length < stored.length) throw this.diverged(this.inputs.length, "the replay ended before it");
@@ -3913,12 +4020,15 @@ var Driver = class {
     this.appendResolution(cloneRecord(record), nodeId, branchPath);
     this.advance(runId, nodeId, branchPath);
   }
-  /** 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.
+   */
   feed(step2) {
     try {
       step2();
     } catch (e) {
-      if (e instanceof ResumeRefused) throw e;
+      if (e instanceof ResumeRefused || e instanceof InputCut) throw e;
       this.failRun(e);
     }
   }
@@ -3931,6 +4041,119 @@ var Driver = class {
       `ResumeRefused (diverged): replaying run "${this.runId}" does not reproduce the stored element at position ${at} \u2014 stored ${describeElement(stored[at])}, replayed ${describeElement(this.inputs[at])} (${why}). P23 decision 9: a stored run the replay cannot regenerate \u2014 a predicate, a definition or an entry payload that is not what produced it \u2014 is refused rather than resumed on a different road. Nothing was handed to the scheduler.`
     );
   }
+  /**
+   * **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.
+   */
+  offer(r, input, own3) {
+    if (r.branchPath !== null && input.branchPath !== r.branchPath) return;
+    const stored = this.replay.stored.length;
+    if (own3 === null) {
+      if (this.inputs.length < stored) r.pending = { at: this.inputs.length, input };
+      return;
+    }
+    if (own3 < stored) this.take(r, input);
+  }
+  /** **An offer taken** — kept, and for a target with a path the replay ends HERE: nothing after it is replayed (`InputCut`). */
+  take(r, input) {
+    r.found.push(input);
+    if (r.branchPath !== null) throw new InputCut();
+  }
+  /**
+   * **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.
+   */
+  static read(flow, options, run, target) {
+    const refused = headerRefusal(flow, run);
+    if (refused !== null) {
+      return { answer: { ok: false, reason: refused.reason, index: null, message: `a reading refuses this header as a resume does \u2014 ${refused.message}` }, driver: null };
+    }
+    const header = run.header;
+    try {
+      assertRunId(header.runId);
+    } catch (e) {
+      return { answer: { ok: false, reason: "format", index: null, message: `the stored header's runId is not a run id (ID-R2): ${e instanceof Error ? e.message : String(e)}` }, driver: null };
+    }
+    const t = readTarget(flow, header.runId, target);
+    if ("ok" in t) return { answer: t, driver: null };
+    const { predicates, workers, nodeTypes, pools, groups, languages, gateTypes, joinPolicy, defaultRetryPolicy, validateBoundaries } = options;
+    const driver = new _Driver(flow, {
+      runId: header.runId,
+      scheduler: DEAF_SCHEDULER,
+      predicates,
+      ...workers !== void 0 ? { workers } : {},
+      ...nodeTypes !== void 0 ? { nodeTypes } : {},
+      ...pools !== void 0 ? { pools } : {},
+      ...groups !== void 0 ? { groups } : {},
+      ...languages !== void 0 ? { languages } : {},
+      ...gateTypes !== void 0 ? { gateTypes } : {},
+      joinPolicy: joinPolicy ?? liveToken,
+      ...defaultRetryPolicy !== void 0 ? { defaultRetryPolicy } : {},
+      ...validateBoundaries !== void 0 ? { validateBoundaries } : {}
+    });
+    return { answer: driver.readStep(run, t), driver };
+  }
+  /**
+   * **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.
+   */
+  readStep(run, t) {
+    const events = run.events;
+    let end = events.length;
+    for (let i = 0; i < events.length; i += 1) {
+      const e = events[i];
+      if (typeof e !== "object" || e === null) {
+        return { ok: false, reason: "format", index: null, message: `the stored element at position ${i} is ${JSON.stringify(e) ?? String(e)}, which is not a fold input (RN-R14, RN-R17)` };
+      }
+      const k = e.kind;
+      if (k === "halted" || k === "stopped" || k === "cancelRequested") {
+        end = i;
+        break;
+      }
+    }
+    let entryPayload;
+    try {
+      entryPayload = structuredClone(run.header.entryPayload);
+    } catch (e) {
+      return { ok: false, reason: "format", index: null, message: `the stored header's entry payload does not clone (RN-R15, RN-R17): ${e instanceof Error ? e.message : String(e)}` };
+    }
+    this.header = { format: CHECKPOINT_FORMAT, runId: this.runId, flowId: this.def.flowId, version: this.def.version, entryPayload };
+    this.started = true;
+    const reading = { nodeId: t.nodeId, branchPath: t.branchPath, pending: null, found: [], fed: 0, elements: 0 };
+    this.replay = { stored: end === events.length ? events : events.slice(0, end), feeding: -1, held: /* @__PURE__ */ new Map(), reading };
+    try {
+      this.replayStored(this.replay.stored);
+    } catch (e) {
+      if (e instanceof InputCut) return { ok: true, inputs: [...reading.found] };
+      if (e instanceof ResumeRefused) return { ok: false, reason: "diverged", index: e.index, message: e.message };
+      throw e;
+    }
+    if (reading.found.length > 0) return { ok: true, inputs: [...reading.found] };
+    const where = t.branchPath === null ? `node "${t.nodeId}" on any branch path` : `node "${t.nodeId}" at branch path "${t.branchPath}"`;
+    return {
+      ok: false,
+      reason: "not-reached",
+      index: end,
+      message: `the replay handed ${where} nothing within the ${end} stored element(s) a reading verifies` + (end < events.length ? ` \u2014 the prefix ends at position ${end}, \`${String(events[end].kind)}\`, after which a halted driver composes nothing more (RN-R45)` : "") + "."
+    };
+  }
   /**
    * **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
@@ -4804,7 +5027,12 @@ var Driver = class {
     if (this.shut()) return;
     const node = this.graph.byId.get(nodeId);
     if (!node) return;
-    const received = this.compose(node, payload, itemIndices, this.runPayload(), () => this.itemOf(node.id, itemIndices));
+    const received = this.compose(node, payload, itemIndices, () => this.sharedPayload(), () => this.itemOf(node.id, itemIndices));
+    const reading = this.replay?.reading ?? null;
+    if (reading !== null && node.kind !== "task" && node.id === reading.nodeId) {
+      const path = node.kind === "join" || node.kind === "end" ? fromBranch : this.pathOf(node.id, itemIndices);
+      this.offer(reading, { nodeId: node.id, kind: node.kind, branchPath: path, handed: node.kind === "join" ? "arrival" : "received", value: received }, null);
+    }
     switch (node.kind) {
       case "task":
         return this.dispatch(runId, node, received, itemIndices);
@@ -5112,7 +5340,8 @@ var Driver = class {
    * 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`
@@ -5140,7 +5369,7 @@ var Driver = class {
    * node or an edge that declares a `needs` asks, and a run that declares none never builds it.
    */
   outputs() {
-    const c = this.outputsCache ??= { at: 0, byNode: /* @__PURE__ */ new Map(), tasks: /* @__PURE__ */ new Map(), orders: /* @__PURE__ */ new Map(), index: /* @__PURE__ */ new Map(), depths: /* @__PURE__ */ new Map(), examined: 0 };
+    const c = this.cache();
     for (; c.at < this.log.length; c.at += 1) {
       const r = this.log[c.at];
       let t = c.tasks.get(r.taskId);
@@ -5160,6 +5389,23 @@ var Driver = class {
     }
     return c.byNode;
   }
+  /**
+   * 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).
+   */
+  cache() {
+    return this.outputsCache ??= {
+      at: 0,
+      byNode: /* @__PURE__ */ new Map(),
+      tasks: /* @__PURE__ */ new Map(),
+      orders: /* @__PURE__ */ new Map(),
+      index: /* @__PURE__ */ new Map(),
+      depths: /* @__PURE__ */ new Map(),
+      examined: 0,
+      payload: null,
+      copies: 0
+    };
+  }
   /**
    * **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
@@ -5174,6 +5420,10 @@ var Driver = class {
    * 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).
    */
   place(c, t, eff) {
     const list = c.byNode.get(t.nodeId);
@@ -5288,7 +5538,8 @@ var Driver = class {
   /**
    * 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
@@ -5324,7 +5575,7 @@ var Driver = class {
         continue;
       }
       if (t.form === "payload") {
-        out[key] = cloneValue(runPayload);
+        out[key] = runPayload();
         continue;
       }
       if (t.form === "item") {
@@ -5343,7 +5594,7 @@ var Driver = class {
    *
    * **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
@@ -5363,15 +5614,38 @@ var Driver = class {
         `node "${atNodeId}" at branch path "${here}" declares \`${site}[${JSON.stringify(key)}]\` naming "${t.node}", and no output of that node is on this path. \`FD-V27\` checked that this node is reachable FROM it and \`FD-V29\` that it must have RUN, which is everything the graph can say; whether any of its outputs is on YOUR path is a statement about this run \u2014 a reader inside a region whose indices do not line up with the target\`s, or a join policy that fired before that node settled. FD-R3.`
       );
     }
-    this.outputsCache.examined += t.form === "all" ? visible.length : 1;
-    return t.form === "all" ? visible.map((e) => cloneValue(e.result)) : cloneValue(visible[0].result);
+    const c = this.outputsCache;
+    c.examined += t.form === "all" ? visible.length : 1;
+    return t.form === "all" ? visible.map((e) => this.sharedOf(c, e)) : this.sharedOf(c, visible[0]);
+  }
+  /** **An output entry's shared copy**, made at its first read and kept on the entry (`OutputEntry.shared`) — counted. */
+  sharedOf(c, e) {
+    if (!("shared" in e)) {
+      e.shared = sharedCopy(e.result);
+      c.copies += 1;
+    }
+    return e.shared;
+  }
+  /**
+   * **`"$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.
+   */
+  sharedPayload() {
+    const c = this.cache();
+    if (c.payload === null) {
+      c.payload = { value: sharedCopy(this.runPayload()) };
+      c.copies += 1;
+    }
+    return c.payload.value;
   }
   /**
    * **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.
    */
   runPayload() {
     return this.header?.entryPayload;
@@ -5407,8 +5681,8 @@ var Driver = class {
    * 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.
    */
@@ -5421,7 +5695,7 @@ var Driver = class {
     for (const [key, ref] of Object.entries(needs)) {
       const t = referenceTarget(ref);
       if (t.form === "payload") {
-        out[key] = cloneValue(this.runPayload());
+        out[key] = this.sharedPayload();
         continue;
       }
       if (t.form === "item") {
@@ -5452,7 +5726,7 @@ var Driver = class {
     }
     this.dispatched.add(taskId);
     if (this.replay === null) this.unhanded.add(taskId);
-    this.append({ kind: "dispatched", taskId });
+    const dispatchedAt = this.append({ kind: "dispatched", taskId });
     const type = this.nodeTypes.get(node.type);
     const retryPolicy = node.retryPolicy ?? type.retryPolicy ?? this.opts.defaultRetryPolicy;
     const config = {
@@ -5464,7 +5738,11 @@ var Driver = class {
       ...node.workerGroups !== void 0 ? { workerGroups: node.workerGroups } : {}
     };
     if (this.replay !== null) {
-      this.replay.held.set(taskId, config);
+      const reading = this.replay.reading;
+      if (reading === null) this.replay.held.set(taskId, config);
+      else if (node.id === reading.nodeId) {
+        this.offer(reading, { nodeId: node.id, kind: "task", branchPath: this.pathOf(node.id, itemIndices), handed: "envelope", value: config.payload }, dispatchedAt);
+      }
       return;
     }
     if ((this.paused || this.pauseHeld.size > 0) && !this.shut()) {
@@ -5826,6 +6104,15 @@ var Driver = class {
     if (replay !== null && seq < replay.stored.length) {
       const same = isFed(input) ? replay.feeding === seq && input.kind === replay.stored[seq]?.kind : sameData(input, replay.stored[seq]);
       if (!same) throw this.diverged(seq, "a different element there");
+      const r = replay.reading;
+      if (r !== null) {
+        r.elements += 1;
+        if (r.pending !== null && r.pending.at === seq) {
+          const taken = r.pending.input;
+          r.pending = null;
+          this.take(r, taken);
+        }
+      }
     }
     if (this.opts.onFoldInput && this.delivers(seq)) this.opts.onFoldInput(freezeInput(input), seq);
     return seq;
@@ -5909,7 +6196,7 @@ var Driver = class {
       return;
     }
     this.firedAdd(region.fanoutId, rp);
-    this.append({
+    const firedAt = this.append({
       kind: "joinSettled",
       regionId: region.fanoutId,
       regionPath: rp,
@@ -5919,6 +6206,10 @@ var Driver = class {
     if (this.shut()) return;
     const collected = collectArrivals(this.arrivals.get(region.fanoutId)?.get(rp));
     this.releaseArrivals(region.fanoutId, rp);
+    const reading = this.replay?.reading ?? null;
+    if (reading !== null && region.joinId === reading.nodeId) {
+      this.offer(reading, { nodeId: region.joinId, kind: "join", branchPath: rp, handed: "collection", value: collected }, firedAt);
+    }
     const join = this.graph.byId.get(region.joinId);
     if (!join || join.kind !== "join") return;
     const edge = join.edges?.[0];
@@ -6053,6 +6344,46 @@ var Driver = class {
     return this.effectiveOutcomeOf(taskId)?.terminalState ?? null;
   }
 };
+function readTarget(flow, runId, target) {
+  const unknown = (why) => ({ ok: false, reason: "unknown", index: null, message: `the target names nothing this run can have: ${why} (RN-R45)` });
+  const t = target;
+  const nodes = flow.nodes;
+  if (typeof t?.taskId === "string") {
+    let parts;
+    try {
+      parts = parseTaskId(t.taskId);
+    } catch (e) {
+      return unknown(`task id ${JSON.stringify(t.taskId)} does not parse \u2014 ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (parts.runId !== runId) return unknown(`task id ${JSON.stringify(t.taskId)} is of run "${parts.runId}", and this run is "${runId}"`);
+    if (parts.attempt !== 0) return unknown(`task id ${JSON.stringify(t.taskId)} carries attempt ${parts.attempt}, and a run mints attempt 0`);
+    const node = nodes.find((n) => n.id === parts.nodeId);
+    if (node === void 0 || node.kind !== "task" && node.kind !== "ask") {
+      return unknown(`task id ${JSON.stringify(t.taskId)} names ${node === void 0 ? "no node of the definition" : `a ${node.kind}, which has no task id`}`);
+    }
+    return { nodeId: parts.nodeId, branchPath: parts.branchPath };
+  }
+  if (typeof t?.nodeId === "string") {
+    const nodeId = t.nodeId;
+    if (!nodes.some((n) => n.id === nodeId)) return unknown(`the definition has no node "${nodeId}"`);
+    if (t.branchPath === void 0) return { nodeId, branchPath: null };
+    const path = t.branchPath;
+    let ok = typeof path === "string";
+    if (ok) {
+      try {
+        parseTaskId(`${runId}:${nodeId}:${path}:0`);
+      } catch {
+        ok = false;
+      }
+    }
+    if (!ok) return unknown(`branch path ${JSON.stringify(path) ?? String(path)} is not spec/task-id.md's grammar ("-", or dot-separated non-negative integers)`);
+    return { nodeId, branchPath: path };
+  }
+  return unknown("a target is { taskId } or { nodeId, branchPath? }");
+}
+function inputOf(flow, options, run, target) {
+  return Driver.read(flow, options, run, target).answer;
+}
 
 // src/fold/accumulator.ts
 var Suspended = class {
@@ -6564,74 +6895,6 @@ function nodeOf(s, taskId) {
   return s.nodes[taskId] ?? null;
 }
 
-// src/fold/policies.ts
-var arrivalCount = {
-  id: "arrival-count",
-  // **`region` is deliberately unread.** It was the source of `need` and is now
-  // the source of nothing: `branches` cannot answer *how many branches did this
-  // region open* for a map, and a policy that read it for a fanout and counted for
-  // a map would be branching on the node kind — which it cannot see
-  // ([Q159](../../doc/questions/q159.md)) and, per that row, should not.
-  open: () => ({ need: 0, arrived: [] }),
-  step: (s, e) => {
-    if (e.type === "branch.opened") return { ...s, need: s.need + 1 };
-    if (e.type !== "branch.arrived" || s.arrived.includes(e.branchPath)) return s;
-    return { ...s, arrived: [...s.arrived, e.branchPath] };
-  },
-  // **`s.need > 0` is a PIN, not a refinement**, and it is exactly `JP-R8`'s own
-  // *"having been positive"* argument in the policy that argument was denied to.
-  // A bare `arrived.length >= need` is true at `0 >= 0`, so without it `open`
-  // itself reports `satisfied` — and at a map of zero items this policy would fire
-  // a join **no branch ever reached**, which is character for character what
-  // [ADR 0025](../../doc/decisions/0025-the-zero-arrival-join-is-reportable-and-arrival-counting-is-not-repaired.md)
-  // REFUSED `JP-R7`'s variant for. It is vacuous on every `fanout` region, because
-  // `FD-V9`'s floor puts `need` at 2 or more.
-  status: (s) => s.need > 0 && s.arrived.length >= s.need ? "satisfied" : "waiting",
-  // Never `unsatisfiable`: this policy has no way to know a join can never fire,
-  // which is precisely the argument Q4 states as a testable claim. **At a map of
-  // zero items it says `waiting`, exactly as the other two do** — the region is
-  // reported dead by the FOLD (`RN-R10`, via the `regionEntered` input) rather
-  // than by any policy, which is `spec/join-policy.md` section 5's own case.
-  describe: (s) => ({ need: s.need, arrived: [...s.arrived] })
-};
-var liveToken = {
-  id: "live-token",
-  open: () => ({ live: 0, positive: false }),
-  step: (s, e) => {
-    if (e.type === "branch.opened") return { live: s.live + 1, positive: true };
-    if (e.type === "branch.arrived" || e.type === "branch.exited" || e.type === "branch.lost") {
-      return { ...s, live: s.live - 1 };
-    }
-    return s;
-  },
-  status: (s) => s.positive && s.live === 0 ? "satisfied" : "waiting",
-  // NOT requiring an arrival before reporting `satisfied`, and NOT returning
-  // `unsatisfiable` on zero-with-no-arrivals. That is JP-R8's third policy, and
-  // it is the one that would hand live-token a graceful answer arrival-count is
-  // structurally denied — which is the asymmetry JP-R8 exists to forbid.
-  describe: (s) => ({ live: s.live, positive: s.positive })
-};
-var liveTokenRequiringArrival = {
-  id: "live-token-requiring-arrival",
-  open: () => ({ live: 0, positive: false, arrived: 0 }),
-  step: (s, e) => {
-    if (e.type === "branch.opened") return { ...s, live: s.live + 1, positive: true };
-    if (e.type === "branch.arrived") return { ...s, live: s.live - 1, arrived: s.arrived + 1 };
-    if (e.type === "branch.exited" || e.type === "branch.lost") return { ...s, live: s.live - 1 };
-    return s;
-  },
-  status: (s) => {
-    if (!s.positive || s.live !== 0) return "waiting";
-    return s.arrived > 0 ? "satisfied" : "unsatisfiable";
-  },
-  describe: (s) => ({ live: s.live, positive: s.positive, arrived: s.arrived })
-};
-var POLICIES = {
-  "arrival-count": arrivalCount,
-  "live-token": liveToken,
-  "live-token-requiring-arrival": liveTokenRequiringArrival
-};
-
 export {
   PREDICATE_OPS,
   PREDICATE_ROOTS,
@@ -6753,6 +7016,10 @@ export {
   selectEdge,
   TERMINAL_EVENTS,
   isTerminalEvent,
+  arrivalCount,
+  liveToken,
+  liveTokenRequiringArrival,
+  POLICIES,
   InvalidDefinition,
   DuplicateTaskId,
   UnresolvedMapArity,
@@ -6768,15 +7035,12 @@ export {
   UndispatchedTask,
   MissingJoinPolicy,
   Driver,
+  inputOf,
   Accumulator,
   emptyState,
   step,
   fold,
   foldLog,
   isTerminal,
-  nodeOf,
-  arrivalCount,
-  liveToken,
-  liveTokenRequiringArrival,
-  POLICIES
+  nodeOf
 };