fyflow-orchestration 0.9.0 → 0.9.1

package/AGENTS.md

@@ -477,6 +477,16 @@ once per item* is a fact about your document rather than about your run. **Measu
 obstacle** — a size measurement is about 0.03% of what it would warn about at arity 1000.
 `spec/flow-definition.md` section 3 carries the whole verdict and the measurements.
 
+**Finding what a reference names costs its ANSWER** — from 0.9.1
+([ADR 0124](doc/decisions/0124-a-reference-read-costs-its-answer.md), `spec/flow-definition.md` v0.46). A branch task
+may read any earlier task of its own `map` instance by id — one step back or several, where `"."` reaches only its
+predecessor — and the read takes that one output, however many instances the map has: the driver files a node's outputs
+by the branch-path prefix its readers share. In 0.9.0 every read searched every output of the node it names, so such a
+map cost O(items²) (the driver alone at 8,000 items: 22 s in 0.9.0, 0.22 s from 0.9.1, node 24). **A read never costs
+less than its answer**: `["n"]` from a reader outside every region `n` is in — a SIBLING map's reader — is handed every
+output of `n`, so two maps of `n` and `m` instances compose `n·m` entries. That is the answer's price, the cliff above by
+another road, and the remedy is the same.
+
 ### `"$payload"` — what reached the RUN, from any node
 
 **`"$payload"` names the value the run was STARTED with** — `start(flow, payload)`'s `payload` — on any node that may
@@ -1743,7 +1753,8 @@ need the state; step only where you hold a short one. Both return exactly what t
 **The driver's own work per settlement does not grow with the run either** — `RN-R13` v0.30, from 0.9.0
 ([ADR 0121](doc/decisions/0121-the-driver-keeps-a-per-task-view-of-its-log.md)): every question it asks of its log about
 ONE task — a settlement's effective outcome, whether a task is parked, what is in flight, what a `needs` can reach — reads
-that task's records alone, where 0.8.0 scanned the whole log (a 16,000-item `map` driven on a scheduler double: 999 ms in
+that task's records alone (and from 0.9.1 a `needs` read takes the outputs it is handed rather than searching its node's —
+`RN-R13` v0.32, [ADR 0124](doc/decisions/0124-a-reference-read-costs-its-answer.md)), where 0.8.0 scanned the whole log (a 16,000-item `map` driven on a scheduler double: 999 ms in
 0.8.0, 229 ms from 0.9.0, node 24). `snapshot()`, `foldInputs()` and `checkpoint()` still hand you a copy of the whole run,
 O(run) a call: read them when you need the run, not after every event.
 

package/README.md

@@ -17,7 +17,7 @@ worker returned, routing can **fan out** into parallel branches, and a **join**
 The scheduler runs tasks; this library decides **which task runs next**. `fyflow-scheduler` has no
 dependency graph of its own, so sequence, decision, fan-out and join live here.
 
-Published on npm as `fyflow-orchestration` and on JSR as `@fyflow/orchestration`. The manifests read `0.9.0`.
+Published on npm as `fyflow-orchestration` and on JSR as `@fyflow/orchestration`. The manifests read `0.9.1`.
 
 ## Install
 

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

@@ -136,14 +136,14 @@ function sharedRegionDepth(regions, a, b) {
 }
 function outputIsVisible(regions, readerId, readerPath, targetId, targetPath) {
   const depth = sharedRegionDepth(regions, readerId, targetId);
-  if (depth === 0) return true;
-  const xs = readerPath === "-" ? [] : readerPath.split(".");
-  const ys = targetPath === "-" ? [] : targetPath.split(".");
-  for (let i = 0; i < depth; i++) {
-    if (xs[i] === void 0 || ys[i] === void 0) return false;
-    if (xs[i] !== ys[i]) return false;
-  }
-  return true;
+  const key = visibilityKey(readerPath, depth);
+  return key !== null && key === visibilityKey(targetPath, depth);
+}
+function visibilityKey(path, depth) {
+  if (depth === 0) return "";
+  const segs = path === "-" ? [] : path.split(".");
+  if (segs.length < depth) return null;
+  return segs.length === depth ? path : segs.slice(0, depth).join(".");
 }
 function branchIndexOf(regions, nodeId) {
   const r = innermostRegionOf(regions, nodeId);
@@ -2993,6 +2993,18 @@ function describeElement(e) {
   }
   return s.length > 160 ? `${s.slice(0, 157)}...` : s;
 }
+var NO_OUTPUTS = Object.freeze([]);
+function groupPosition(group, path) {
+  let lo = 0;
+  let hi = group.length;
+  if (hi === 0 || compareBranchPaths(group[hi - 1].path, path) < 0) return hi;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    if (compareBranchPaths(group[mid].path, path) < 0) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
 var UndispatchedTask = class extends Error {
   constructor(message, options) {
     super(message, options);
@@ -5128,7 +5140,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() };
+    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 };
     for (; c.at < this.log.length; c.at += 1) {
       const r = this.log[c.at];
       let t = c.tasks.get(r.taskId);
@@ -5171,6 +5183,7 @@ var Driver = class {
       const at = list.indexOf(t.entry);
       list.splice(at, 1);
       orders.splice(at, 1);
+      this.reindex(c, t.nodeId, t.entry, null);
       t.entry = null;
       if (list.length === 0) {
         c.byNode.delete(t.nodeId);
@@ -5181,10 +5194,12 @@ var Driver = class {
     const entry = { path: t.path, result: eff.result };
     if (t.entry !== null && list !== void 0) {
       list[list.indexOf(t.entry)] = entry;
+      this.reindex(c, t.nodeId, t.entry, entry);
       t.entry = entry;
       return;
     }
     t.entry = entry;
+    this.reindex(c, t.nodeId, null, entry);
     if (list === void 0 || orders === void 0) {
       c.byNode.set(t.nodeId, [entry]);
       c.orders.set(t.nodeId, [t.order]);
@@ -5195,6 +5210,81 @@ var Driver = class {
     list.splice(i, 0, entry);
     orders.splice(i, 0, t.order);
   }
+  /**
+   * **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.
+   */
+  reindex(c, nodeId, was, now) {
+    const byDepth = c.index.get(nodeId);
+    if (byDepth === void 0) return;
+    const path = (now ?? was).path;
+    for (const [depth, groups] of byDepth) {
+      const key = visibilityKey(path, depth);
+      if (key === null) continue;
+      c.examined += 1;
+      const group = groups.get(key);
+      if (was !== null) {
+        const at = groupPosition(group, path);
+        if (now !== null) group[at] = now;
+        else if (group.length === 1) groups.delete(key);
+        else group.splice(at, 1);
+      } else if (group === void 0) {
+        groups.set(key, [now]);
+      } else {
+        group.splice(groupPosition(group, path), 0, now);
+      }
+    }
+  }
+  /**
+   * **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`.
+   */
+  groupsOf(c, nodeId, depth) {
+    let byDepth = c.index.get(nodeId);
+    if (byDepth === void 0) c.index.set(nodeId, byDepth = /* @__PURE__ */ new Map());
+    let groups = byDepth.get(depth);
+    if (groups !== void 0) return groups;
+    groups = /* @__PURE__ */ new Map();
+    for (const e of c.byNode.get(nodeId) ?? NO_OUTPUTS) {
+      c.examined += 1;
+      const key = visibilityKey(e.path, depth);
+      if (key === null) continue;
+      const group = groups.get(key);
+      if (group === void 0) groups.set(key, [e]);
+      else group.push(e);
+    }
+    for (const group of groups.values()) if (group.length > 1) group.sort((x, y) => compareBranchPaths(x.path, y.path));
+    byDepth.set(depth, groups);
+    return groups;
+  }
+  /** The depth `reader` and `target` share — `sharedRegionDepth`, a graph fact, asked once per pair. */
+  depthOf(c, reader, target) {
+    let byTarget = c.depths.get(reader);
+    if (byTarget === void 0) c.depths.set(reader, byTarget = /* @__PURE__ */ new Map());
+    let depth = byTarget.get(target);
+    if (depth === void 0) byTarget.set(target, depth = sharedRegionDepth(this.regions, reader, target));
+    return depth;
+  }
+  /**
+   * **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.
+   */
+  visibleOutputs(atNodeId, here, nodeId) {
+    this.outputs();
+    const c = this.outputsCache;
+    const depth = this.depthOf(c, atNodeId, nodeId);
+    const key = visibilityKey(here, depth);
+    if (key === null) return NO_OUTPUTS;
+    return this.groupsOf(c, nodeId, depth).get(key) ?? NO_OUTPUTS;
+  }
   /**
    * 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
@@ -5225,7 +5315,7 @@ var Driver = class {
   compose(node, edgeValue, itemIndices, runPayload, item) {
     const needs = node.needs;
     if (!needs) return edgeValue;
-    let lookup = null;
+    let here = null;
     const out = {};
     for (const [key, ref] of Object.entries(needs)) {
       const t = referenceTarget(ref);
@@ -5241,8 +5331,8 @@ var Driver = class {
         out[key] = cloneValue(item());
         continue;
       }
-      lookup ??= { here: this.pathOf(node.id, itemIndices), produced: this.outputs() };
-      const v = this.resolveReference(node.id, lookup.here, lookup.produced, key, t, "needs");
+      here ??= this.pathOf(node.id, itemIndices);
+      const v = this.resolveReference(node.id, here, key, t, "needs");
       if (v !== ABSENT) out[key] = v;
     }
     return out;
@@ -5263,8 +5353,8 @@ var Driver = class {
    *
    * @throws UnresolvedReference — `FD-R3`.
    */
-  resolveReference(atNodeId, here, produced, key, t, site) {
-    const visible = (produced.get(t.node) ?? []).filter((e) => outputIsVisible(this.regions, atNodeId, here, t.node, e.path)).sort((x, y) => compareBranchPaths(x.path, y.path));
+  resolveReference(atNodeId, here, key, t, site) {
+    const visible = this.visibleOutputs(atNodeId, here, t.node);
     if (visible.length === 0 && t.conditional) {
       return t.form === "all" ? [] : ABSENT;
     }
@@ -5273,6 +5363,7 @@ 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);
   }
   /**
@@ -5325,7 +5416,7 @@ var Driver = class {
     const needs = edge.needs;
     if (!needs) return EMPTY_NEEDS;
     const here = this.pathOf(node.id, itemIndices);
-    const produced = this.outputs();
+    this.outputs();
     const out = {};
     for (const [key, ref] of Object.entries(needs)) {
       const t = referenceTarget(ref);
@@ -5340,7 +5431,7 @@ var Driver = class {
       if (t.form === "self") {
         throw new Error(`node "${node.id}"'s edge declares needs[${JSON.stringify(key)}] = ${JSON.stringify(ref)}, which FD-V26 refuses on an edge`);
       }
-      const v = this.resolveReference(node.id, here, produced, key, t, "edge needs");
+      const v = this.resolveReference(node.id, here, key, t, "edge needs");
       if (v !== ABSENT) out[key] = v;
     }
     return Object.freeze(out);
@@ -6556,6 +6647,7 @@ export {
   innermostMapOf,
   sharedRegionDepth,
   outputIsVisible,
+  visibilityKey,
   branchIndexOf,
   certainlySettled,
   SCHEMA_KEYWORDS,

package/dist/browser/index.js

@@ -141,9 +141,10 @@ import {
   transformShapeProblem,
   validateDefinition,
   violatedRules,
+  visibilityKey,
   witness,
   workersOf
-} from "./chunks/chunk-3U4UZC34.js";
+} from "./chunks/chunk-I3KDEOLB.js";
 
 // src/definition/assist.ts
 var TYPES = ["object", "array", "string", "number", "integer", "boolean", "null"];
@@ -440,6 +441,7 @@ export {
   tsTypeOf,
   validateDefinition,
   violatedRules,
+  visibilityKey,
   witness,
   workersOf
 };

package/dist/browser/scheduler/index.js

@@ -25,7 +25,7 @@ import {
   retryPolicyProblem,
   validateDefinition,
   workersOf
-} from "../chunks/chunk-3U4UZC34.js";
+} from "../chunks/chunk-I3KDEOLB.js";
 
 // src/scheduler/bootstrap.ts
 import { WorkerManager } from "fyflow-scheduler";

package/dist/node/chunks/{chunk-3U4UZC34.js → chunk-I3KDEOLB.js}

@@ -136,14 +136,14 @@ function sharedRegionDepth(regions, a, b) {
 }
 function outputIsVisible(regions, readerId, readerPath, targetId, targetPath) {
   const depth = sharedRegionDepth(regions, readerId, targetId);
-  if (depth === 0) return true;
-  const xs = readerPath === "-" ? [] : readerPath.split(".");
-  const ys = targetPath === "-" ? [] : targetPath.split(".");
-  for (let i = 0; i < depth; i++) {
-    if (xs[i] === void 0 || ys[i] === void 0) return false;
-    if (xs[i] !== ys[i]) return false;
-  }
-  return true;
+  const key = visibilityKey(readerPath, depth);
+  return key !== null && key === visibilityKey(targetPath, depth);
+}
+function visibilityKey(path, depth) {
+  if (depth === 0) return "";
+  const segs = path === "-" ? [] : path.split(".");
+  if (segs.length < depth) return null;
+  return segs.length === depth ? path : segs.slice(0, depth).join(".");
 }
 function branchIndexOf(regions, nodeId) {
   const r = innermostRegionOf(regions, nodeId);
@@ -2993,6 +2993,18 @@ function describeElement(e) {
   }
   return s.length > 160 ? `${s.slice(0, 157)}...` : s;
 }
+var NO_OUTPUTS = Object.freeze([]);
+function groupPosition(group, path) {
+  let lo = 0;
+  let hi = group.length;
+  if (hi === 0 || compareBranchPaths(group[hi - 1].path, path) < 0) return hi;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    if (compareBranchPaths(group[mid].path, path) < 0) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
 var UndispatchedTask = class extends Error {
   constructor(message, options) {
     super(message, options);
@@ -5128,7 +5140,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() };
+    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 };
     for (; c.at < this.log.length; c.at += 1) {
       const r = this.log[c.at];
       let t = c.tasks.get(r.taskId);
@@ -5171,6 +5183,7 @@ var Driver = class {
       const at = list.indexOf(t.entry);
       list.splice(at, 1);
       orders.splice(at, 1);
+      this.reindex(c, t.nodeId, t.entry, null);
       t.entry = null;
       if (list.length === 0) {
         c.byNode.delete(t.nodeId);
@@ -5181,10 +5194,12 @@ var Driver = class {
     const entry = { path: t.path, result: eff.result };
     if (t.entry !== null && list !== void 0) {
       list[list.indexOf(t.entry)] = entry;
+      this.reindex(c, t.nodeId, t.entry, entry);
       t.entry = entry;
       return;
     }
     t.entry = entry;
+    this.reindex(c, t.nodeId, null, entry);
     if (list === void 0 || orders === void 0) {
       c.byNode.set(t.nodeId, [entry]);
       c.orders.set(t.nodeId, [t.order]);
@@ -5195,6 +5210,81 @@ var Driver = class {
     list.splice(i, 0, entry);
     orders.splice(i, 0, t.order);
   }
+  /**
+   * **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.
+   */
+  reindex(c, nodeId, was, now) {
+    const byDepth = c.index.get(nodeId);
+    if (byDepth === void 0) return;
+    const path = (now ?? was).path;
+    for (const [depth, groups] of byDepth) {
+      const key = visibilityKey(path, depth);
+      if (key === null) continue;
+      c.examined += 1;
+      const group = groups.get(key);
+      if (was !== null) {
+        const at = groupPosition(group, path);
+        if (now !== null) group[at] = now;
+        else if (group.length === 1) groups.delete(key);
+        else group.splice(at, 1);
+      } else if (group === void 0) {
+        groups.set(key, [now]);
+      } else {
+        group.splice(groupPosition(group, path), 0, now);
+      }
+    }
+  }
+  /**
+   * **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`.
+   */
+  groupsOf(c, nodeId, depth) {
+    let byDepth = c.index.get(nodeId);
+    if (byDepth === void 0) c.index.set(nodeId, byDepth = /* @__PURE__ */ new Map());
+    let groups = byDepth.get(depth);
+    if (groups !== void 0) return groups;
+    groups = /* @__PURE__ */ new Map();
+    for (const e of c.byNode.get(nodeId) ?? NO_OUTPUTS) {
+      c.examined += 1;
+      const key = visibilityKey(e.path, depth);
+      if (key === null) continue;
+      const group = groups.get(key);
+      if (group === void 0) groups.set(key, [e]);
+      else group.push(e);
+    }
+    for (const group of groups.values()) if (group.length > 1) group.sort((x, y) => compareBranchPaths(x.path, y.path));
+    byDepth.set(depth, groups);
+    return groups;
+  }
+  /** The depth `reader` and `target` share — `sharedRegionDepth`, a graph fact, asked once per pair. */
+  depthOf(c, reader, target) {
+    let byTarget = c.depths.get(reader);
+    if (byTarget === void 0) c.depths.set(reader, byTarget = /* @__PURE__ */ new Map());
+    let depth = byTarget.get(target);
+    if (depth === void 0) byTarget.set(target, depth = sharedRegionDepth(this.regions, reader, target));
+    return depth;
+  }
+  /**
+   * **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.
+   */
+  visibleOutputs(atNodeId, here, nodeId) {
+    this.outputs();
+    const c = this.outputsCache;
+    const depth = this.depthOf(c, atNodeId, nodeId);
+    const key = visibilityKey(here, depth);
+    if (key === null) return NO_OUTPUTS;
+    return this.groupsOf(c, nodeId, depth).get(key) ?? NO_OUTPUTS;
+  }
   /**
    * 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
@@ -5225,7 +5315,7 @@ var Driver = class {
   compose(node, edgeValue, itemIndices, runPayload, item) {
     const needs = node.needs;
     if (!needs) return edgeValue;
-    let lookup = null;
+    let here = null;
     const out = {};
     for (const [key, ref] of Object.entries(needs)) {
       const t = referenceTarget(ref);
@@ -5241,8 +5331,8 @@ var Driver = class {
         out[key] = cloneValue(item());
         continue;
       }
-      lookup ??= { here: this.pathOf(node.id, itemIndices), produced: this.outputs() };
-      const v = this.resolveReference(node.id, lookup.here, lookup.produced, key, t, "needs");
+      here ??= this.pathOf(node.id, itemIndices);
+      const v = this.resolveReference(node.id, here, key, t, "needs");
       if (v !== ABSENT) out[key] = v;
     }
     return out;
@@ -5263,8 +5353,8 @@ var Driver = class {
    *
    * @throws UnresolvedReference — `FD-R3`.
    */
-  resolveReference(atNodeId, here, produced, key, t, site) {
-    const visible = (produced.get(t.node) ?? []).filter((e) => outputIsVisible(this.regions, atNodeId, here, t.node, e.path)).sort((x, y) => compareBranchPaths(x.path, y.path));
+  resolveReference(atNodeId, here, key, t, site) {
+    const visible = this.visibleOutputs(atNodeId, here, t.node);
     if (visible.length === 0 && t.conditional) {
       return t.form === "all" ? [] : ABSENT;
     }
@@ -5273,6 +5363,7 @@ 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);
   }
   /**
@@ -5325,7 +5416,7 @@ var Driver = class {
     const needs = edge.needs;
     if (!needs) return EMPTY_NEEDS;
     const here = this.pathOf(node.id, itemIndices);
-    const produced = this.outputs();
+    this.outputs();
     const out = {};
     for (const [key, ref] of Object.entries(needs)) {
       const t = referenceTarget(ref);
@@ -5340,7 +5431,7 @@ var Driver = class {
       if (t.form === "self") {
         throw new Error(`node "${node.id}"'s edge declares needs[${JSON.stringify(key)}] = ${JSON.stringify(ref)}, which FD-V26 refuses on an edge`);
       }
-      const v = this.resolveReference(node.id, here, produced, key, t, "edge needs");
+      const v = this.resolveReference(node.id, here, key, t, "edge needs");
       if (v !== ABSENT) out[key] = v;
     }
     return Object.freeze(out);
@@ -6556,6 +6647,7 @@ export {
   innermostMapOf,
   sharedRegionDepth,
   outputIsVisible,
+  visibilityKey,
   branchIndexOf,
   certainlySettled,
   SCHEMA_KEYWORDS,

package/dist/node/index.js

@@ -141,9 +141,10 @@ import {
   transformShapeProblem,
   validateDefinition,
   violatedRules,
+  visibilityKey,
   witness,
   workersOf
-} from "./chunks/chunk-3U4UZC34.js";
+} from "./chunks/chunk-I3KDEOLB.js";
 
 // src/definition/assist.ts
 var TYPES = ["object", "array", "string", "number", "integer", "boolean", "null"];
@@ -440,6 +441,7 @@ export {
   tsTypeOf,
   validateDefinition,
   violatedRules,
+  visibilityKey,
   witness,
   workersOf
 };

package/dist/node/scheduler/index.js

@@ -25,7 +25,7 @@ import {
   retryPolicyProblem,
   validateDefinition,
   workersOf
-} from "../chunks/chunk-3U4UZC34.js";
+} from "../chunks/chunk-I3KDEOLB.js";
 
 // src/scheduler/bootstrap.ts
 import { WorkerManager } from "fyflow-scheduler";

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

@@ -1749,6 +1749,31 @@ export declare class Driver {
      * none (W195's conformity reader, C4; `test/driver/log-view.test.ts` drives it and the resolution that places it again).
      */
     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

package/package.json

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