@graphrefly/graphrefly 0.45.0 → 0.47.0

package/dist/chunk-7EGRP2VX.js

@@ -0,0 +1,76 @@
+// src/base/sources/event/cron.ts
+import { node, wallClockNs } from "@graphrefly/pure-ts/core";
+function sourceOpts(opts) {
+  return { describeKind: "producer", ...opts };
+}
+function parseField(field, min, max) {
+  const result = /* @__PURE__ */ new Set();
+  for (const part of field.split(",")) {
+    const [range, stepStr] = part.split("/");
+    const step = stepStr ? Number.parseInt(stepStr, 10) : 1;
+    if (Number.isNaN(step) || step < 1) throw new Error(`Invalid cron step: ${part}`);
+    let start;
+    let end;
+    if (range === "*") {
+      start = min;
+      end = max;
+    } else if (range.includes("-")) {
+      const [a, b] = range.split("-");
+      start = Number.parseInt(a, 10);
+      end = Number.parseInt(b, 10);
+    } else {
+      start = Number.parseInt(range, 10);
+      end = start;
+    }
+    if (Number.isNaN(start) || Number.isNaN(end)) throw new Error(`Invalid cron field: ${field}`);
+    if (start < min || end > max)
+      throw new Error(`Cron field out of range: ${field} (${min}-${max})`);
+    if (start > end) throw new Error(`Invalid cron range: ${start}-${end} in ${field}`);
+    for (let i = start; i <= end; i += step) result.add(i);
+  }
+  return result;
+}
+function parseCron(expr) {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) throw new Error(`Invalid cron: expected 5 fields, got ${parts.length}`);
+  return {
+    minutes: parseField(parts[0], 0, 59),
+    hours: parseField(parts[1], 0, 23),
+    daysOfMonth: parseField(parts[2], 1, 31),
+    months: parseField(parts[3], 1, 12),
+    daysOfWeek: parseField(parts[4], 0, 6)
+  };
+}
+function matchesCron(schedule, date) {
+  return schedule.minutes.has(date.getMinutes()) && schedule.hours.has(date.getHours()) && schedule.daysOfMonth.has(date.getDate()) && schedule.months.has(date.getMonth() + 1) && schedule.daysOfWeek.has(date.getDay());
+}
+function fromCron(expr, opts) {
+  const schedule = parseCron(expr);
+  const { tickMs: tickOpt, output, ...rest } = opts ?? {};
+  const tickMs = tickOpt ?? 6e4;
+  const emitDate = output === "date";
+  return node(
+    (_data, a) => {
+      let lastFiredKey = -1;
+      const check = () => {
+        const now = /* @__PURE__ */ new Date();
+        const key = now.getFullYear() * 1e8 + (now.getMonth() + 1) * 1e6 + now.getDate() * 1e4 + now.getHours() * 100 + now.getMinutes();
+        if (key !== lastFiredKey && matchesCron(schedule, now)) {
+          lastFiredKey = key;
+          a.emit(emitDate ? now : wallClockNs());
+        }
+      };
+      check();
+      const id = setInterval(check, tickMs);
+      return () => clearInterval(id);
+    },
+    { ...sourceOpts(rest), name: rest.name ?? `cron:${expr}` }
+  );
+}
+
+export {
+  parseCron,
+  matchesCron,
+  fromCron
+};
+//# sourceMappingURL=chunk-7EGRP2VX.js.map

package/dist/chunk-7EGRP2VX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/base/sources/event/cron.ts"],"sourcesContent":["/**\n * Cron-based reactive sources and schedule types.\n *\n * Merged from extra/cron.ts + extra/sources/event.ts (fromCron) during cleave A2.\n * `fromCron` relocated here from `dom.ts` (post-cleave /qa A1): it uses zero DOM\n * APIs (only `setInterval` + `new Date()`), so it belongs on the universal\n * `event/index.ts` barrel, not the browser-only `dom.ts` subpath.\n */\n\nimport { type Node, type NodeOptions, node, wallClockNs } from \"@graphrefly/pure-ts/core\";\n\ntype ExtraOpts = Omit<NodeOptions, \"describeKind\">;\n\nfunction sourceOpts<T = unknown>(opts?: ExtraOpts): NodeOptions<T> {\n\treturn { describeKind: \"producer\", ...opts } as NodeOptions<T>;\n}\n\n/** Options for {@link fromCron}. */\nexport type FromCronOptions = ExtraOpts & {\n\t/** Polling interval in ms. Default `60_000`. */\n\ttickMs?: number;\n\t/** Output format: `\"timestamp_ns\"` (default) emits wall-clock nanoseconds; `\"date\"` emits a `Date` object. */\n\toutput?: \"timestamp_ns\" | \"date\";\n};\n\n/**\n * Minimal 5-field cron parser and matcher (minute hour day-of-month month day-of-week).\n * Ported from callbag-recharge `extra/cron.ts` for `fromCron` (roadmap §2.3).\n */\nexport interface CronSchedule {\n\tminutes: Set<number>;\n\thours: Set<number>;\n\tdaysOfMonth: Set<number>;\n\tmonths: Set<number>;\n\tdaysOfWeek: Set<number>;\n}\n\nfunction parseField(field: string, min: number, max: number): Set<number> {\n\tconst result = new Set<number>();\n\tfor (const part of field.split(\",\")) {\n\t\tconst [range, stepStr] = part.split(\"/\");\n\t\tconst step = stepStr ? Number.parseInt(stepStr, 10) : 1;\n\t\tif (Number.isNaN(step) || step < 1) throw new Error(`Invalid cron step: ${part}`);\n\t\tlet start: number;\n\t\tlet end: number;\n\t\tif (range === \"*\") {\n\t\t\tstart = min;\n\t\t\tend = max;\n\t\t} else if (range.includes(\"-\")) {\n\t\t\tconst [a, b] = range.split(\"-\");\n\t\t\tstart = Number.parseInt(a, 10);\n\t\t\tend = Number.parseInt(b, 10);\n\t\t} else {\n\t\t\tstart = Number.parseInt(range, 10);\n\t\t\tend = start;\n\t\t}\n\t\tif (Number.isNaN(start) || Number.isNaN(end)) throw new Error(`Invalid cron field: ${field}`);\n\t\tif (start < min || end > max)\n\t\t\tthrow new Error(`Cron field out of range: ${field} (${min}-${max})`);\n\t\tif (start > end) throw new Error(`Invalid cron range: ${start}-${end} in ${field}`);\n\t\tfor (let i = start; i <= end; i += step) result.add(i);\n\t}\n\treturn result;\n}\n\n/**\n * Parses a standard 5-field cron expression into a {@link CronSchedule}.\n *\n * Supports `*`, ranges (`1-5`), steps (`*\\/5`, `0-30/10`), and comma-separated\n * lists. Fields are: minute (0–59), hour (0–23), day-of-month (1–31),\n * month (1–12), day-of-week (0–6, Sunday = 0).\n *\n * @param expr - Five-field whitespace-separated cron string (e.g. `\"0 9 * * 1-5\"`).\n * @returns Parsed {@link CronSchedule} with one `Set<number>` per field.\n * @throws Error when the expression does not have exactly 5 fields, contains\n *   out-of-range values, or uses an invalid step.\n *\n * @example\n * ```ts\n * import { parseCron } from \"@graphrefly/graphrefly-ts\";\n *\n * const sched = parseCron(\"0 9 * * 1-5\"); // weekdays at 09:00\n * sched.hours;      // Set { 9 }\n * sched.daysOfWeek; // Set { 1, 2, 3, 4, 5 }\n * ```\n */\nexport function parseCron(expr: string): CronSchedule {\n\tconst parts = expr.trim().split(/\\s+/);\n\tif (parts.length !== 5) throw new Error(`Invalid cron: expected 5 fields, got ${parts.length}`);\n\treturn {\n\t\tminutes: parseField(parts[0], 0, 59),\n\t\thours: parseField(parts[1], 0, 23),\n\t\tdaysOfMonth: parseField(parts[2], 1, 31),\n\t\tmonths: parseField(parts[3], 1, 12),\n\t\tdaysOfWeek: parseField(parts[4], 0, 6),\n\t};\n}\n\n/**\n * Returns `true` if `date` satisfies every field of `schedule`.\n *\n * @param schedule - Parsed schedule from {@link parseCron}.\n * @param date - Moment to test (local time via `getMinutes`, `getHours`, etc.).\n * @returns `true` when all five cron fields match the given date.\n *\n * @example\n * ```ts\n * import { parseCron, matchesCron } from \"@graphrefly/graphrefly-ts\";\n *\n * const sched = parseCron(\"30 8 * * 1\"); // Mondays at 08:30\n * const monday = new Date(\"2026-03-30T08:30:00\"); // a Monday\n * matchesCron(sched, monday); // true\n * ```\n */\nexport function matchesCron(schedule: CronSchedule, date: Date): boolean {\n\treturn (\n\t\tschedule.minutes.has(date.getMinutes()) &&\n\t\tschedule.hours.has(date.getHours()) &&\n\t\tschedule.daysOfMonth.has(date.getDate()) &&\n\t\tschedule.months.has(date.getMonth() + 1) &&\n\t\tschedule.daysOfWeek.has(date.getDay())\n\t);\n}\n\n/**\n * Polls on an interval; when the current minute matches a 5-field cron expression, emits once (see {@link parseCron}).\n *\n * @param expr - Cron string (`min hour dom month dow`).\n * @param opts - Producer options plus `tickMs` (default `60_000`) and `output` (`timestamp_ns` default, or `date` for `Date` values).\n * @returns `Node<number>` (nanosecond timestamp) or `Node<Date>` when `output: \"date\"`.\n *\n * @example\n * ```ts\n * import { fromCron } from \"@graphrefly/graphrefly\";\n *\n * fromCron(\"0 9 * * 1\");\n * ```\n *\n * @category extra\n */\nexport function fromCron(expr: string, opts?: FromCronOptions & { output: \"date\" }): Node<Date>;\nexport function fromCron(expr: string, opts?: FromCronOptions): Node<number>;\nexport function fromCron(expr: string, opts?: FromCronOptions): Node<number | Date> {\n\tconst schedule: CronSchedule = parseCron(expr);\n\tconst { tickMs: tickOpt, output, ...rest } = opts ?? {};\n\tconst tickMs = tickOpt ?? 60_000;\n\tconst emitDate = output === \"date\";\n\treturn node<number | Date>(\n\t\t(_data, a) => {\n\t\t\tlet lastFiredKey = -1;\n\t\t\tconst check = () => {\n\t\t\t\tconst now = new Date();\n\t\t\t\tconst key =\n\t\t\t\t\tnow.getFullYear() * 100_000_000 +\n\t\t\t\t\t(now.getMonth() + 1) * 1_000_000 +\n\t\t\t\t\tnow.getDate() * 10_000 +\n\t\t\t\t\tnow.getHours() * 100 +\n\t\t\t\t\tnow.getMinutes();\n\t\t\t\tif (key !== lastFiredKey && matchesCron(schedule, now)) {\n\t\t\t\t\tlastFiredKey = key;\n\t\t\t\t\ta.emit(emitDate ? now : wallClockNs());\n\t\t\t\t}\n\t\t\t};\n\t\t\tcheck();\n\t\t\tconst id = setInterval(check, tickMs);\n\t\t\treturn () => clearInterval(id);\n\t\t},\n\t\t{ ...sourceOpts(rest), name: rest.name ?? `cron:${expr}` },\n\t);\n}\n"],"mappings":";AASA,SAAsC,MAAM,mBAAmB;AAI/D,SAAS,WAAwB,MAAkC;AAClE,SAAO,EAAE,cAAc,YAAY,GAAG,KAAK;AAC5C;AAsBA,SAAS,WAAW,OAAe,KAAa,KAA0B;AACzE,QAAM,SAAS,oBAAI,IAAY;AAC/B,aAAW,QAAQ,MAAM,MAAM,GAAG,GAAG;AACpC,UAAM,CAAC,OAAO,OAAO,IAAI,KAAK,MAAM,GAAG;AACvC,UAAM,OAAO,UAAU,OAAO,SAAS,SAAS,EAAE,IAAI;AACtD,QAAI,OAAO,MAAM,IAAI,KAAK,OAAO,EAAG,OAAM,IAAI,MAAM,sBAAsB,IAAI,EAAE;AAChF,QAAI;AACJ,QAAI;AACJ,QAAI,UAAU,KAAK;AAClB,cAAQ;AACR,YAAM;AAAA,IACP,WAAW,MAAM,SAAS,GAAG,GAAG;AAC/B,YAAM,CAAC,GAAG,CAAC,IAAI,MAAM,MAAM,GAAG;AAC9B,cAAQ,OAAO,SAAS,GAAG,EAAE;AAC7B,YAAM,OAAO,SAAS,GAAG,EAAE;AAAA,IAC5B,OAAO;AACN,cAAQ,OAAO,SAAS,OAAO,EAAE;AACjC,YAAM;AAAA,IACP;AACA,QAAI,OAAO,MAAM,KAAK,KAAK,OAAO,MAAM,GAAG,EAAG,OAAM,IAAI,MAAM,uBAAuB,KAAK,EAAE;AAC5F,QAAI,QAAQ,OAAO,MAAM;AACxB,YAAM,IAAI,MAAM,4BAA4B,KAAK,KAAK,GAAG,IAAI,GAAG,GAAG;AACpE,QAAI,QAAQ,IAAK,OAAM,IAAI,MAAM,uBAAuB,KAAK,IAAI,GAAG,OAAO,KAAK,EAAE;AAClF,aAAS,IAAI,OAAO,KAAK,KAAK,KAAK,KAAM,QAAO,IAAI,CAAC;AAAA,EACtD;AACA,SAAO;AACR;AAuBO,SAAS,UAAU,MAA4B;AACrD,QAAM,QAAQ,KAAK,KAAK,EAAE,MAAM,KAAK;AACrC,MAAI,MAAM,WAAW,EAAG,OAAM,IAAI,MAAM,wCAAwC,MAAM,MAAM,EAAE;AAC9F,SAAO;AAAA,IACN,SAAS,WAAW,MAAM,CAAC,GAAG,GAAG,EAAE;AAAA,IACnC,OAAO,WAAW,MAAM,CAAC,GAAG,GAAG,EAAE;AAAA,IACjC,aAAa,WAAW,MAAM,CAAC,GAAG,GAAG,EAAE;AAAA,IACvC,QAAQ,WAAW,MAAM,CAAC,GAAG,GAAG,EAAE;AAAA,IAClC,YAAY,WAAW,MAAM,CAAC,GAAG,GAAG,CAAC;AAAA,EACtC;AACD;AAkBO,SAAS,YAAY,UAAwB,MAAqB;AACxE,SACC,SAAS,QAAQ,IAAI,KAAK,WAAW,CAAC,KACtC,SAAS,MAAM,IAAI,KAAK,SAAS,CAAC,KAClC,SAAS,YAAY,IAAI,KAAK,QAAQ,CAAC,KACvC,SAAS,OAAO,IAAI,KAAK,SAAS,IAAI,CAAC,KACvC,SAAS,WAAW,IAAI,KAAK,OAAO,CAAC;AAEvC;AAoBO,SAAS,SAAS,MAAc,MAA6C;AACnF,QAAM,WAAyB,UAAU,IAAI;AAC7C,QAAM,EAAE,QAAQ,SAAS,QAAQ,GAAG,KAAK,IAAI,QAAQ,CAAC;AACtD,QAAM,SAAS,WAAW;AAC1B,QAAM,WAAW,WAAW;AAC5B,SAAO;AAAA,IACN,CAAC,OAAO,MAAM;AACb,UAAI,eAAe;AACnB,YAAM,QAAQ,MAAM;AACnB,cAAM,MAAM,oBAAI,KAAK;AACrB,cAAM,MACL,IAAI,YAAY,IAAI,OACnB,IAAI,SAAS,IAAI,KAAK,MACvB,IAAI,QAAQ,IAAI,MAChB,IAAI,SAAS,IAAI,MACjB,IAAI,WAAW;AAChB,YAAI,QAAQ,gBAAgB,YAAY,UAAU,GAAG,GAAG;AACvD,yBAAe;AACf,YAAE,KAAK,WAAW,MAAM,YAAY,CAAC;AAAA,QACtC;AAAA,MACD;AACA,YAAM;AACN,YAAM,KAAK,YAAY,OAAO,MAAM;AACpC,aAAO,MAAM,cAAc,EAAE;AAAA,IAC9B;AAAA,IACA,EAAE,GAAG,WAAW,IAAI,GAAG,MAAM,KAAK,QAAQ,QAAQ,IAAI,GAAG;AAAA,EAC1D;AACD;","names":[]}

package/dist/chunk-A7KV5UK4.js

@@ -0,0 +1,150 @@
+import {
+  forEach
+} from "./chunk-DKNHAICT.js";
+
+// src/base/composition/distill.ts
+import { batch, factoryTag, node } from "@graphrefly/pure-ts/core";
+import {
+  fromAny,
+  reactiveMap,
+  switchMap,
+  withLatestFrom
+} from "@graphrefly/pure-ts/extra";
+function isNodeLike(value) {
+  return typeof value === "object" && value !== null && "cache" in value && typeof value.subscribe === "function";
+}
+function keepalive(node2) {
+  node2.subscribe(() => void 0);
+}
+function mapFromSnapshot(snapshot) {
+  if (snapshot instanceof Map) return snapshot;
+  return /* @__PURE__ */ new Map();
+}
+function applyExtraction(store, extraction) {
+  if (!Array.isArray(extraction.upsert)) {
+    throw new TypeError("distill extraction requires upsert: Array<{ key, value }>");
+  }
+  batch(() => {
+    for (const { key, value } of extraction.upsert) {
+      store.set(key, value);
+    }
+    for (const key of extraction.remove ?? []) {
+      store.delete(key);
+    }
+  });
+}
+function distill(source, extractFn, opts) {
+  const sourceNode = fromAny(source);
+  const store = reactiveMap(opts.mapOptions ?? {});
+  const budget = opts.budget ?? 2e3;
+  const hasContext = opts.context !== void 0 && opts.context !== null;
+  const contextNode = hasContext ? fromAny(opts.context) : node([], { initial: null });
+  const extractionStream = fromAny(
+    extractFn(sourceNode, store.entries)
+  );
+  forEach(extractionStream, (extraction) => {
+    applyExtraction(store, extraction);
+  });
+  if (opts.evict) {
+    const verdictUnsubs = /* @__PURE__ */ new Map();
+    const evictionKeys = node(
+      [store.entries],
+      (batchData, actions, ctx) => {
+        const batch0 = batchData[0];
+        const snapshot = batch0 != null && batch0.length > 0 ? batch0.at(-1) : ctx.prevData[0];
+        const out = [];
+        const entries = mapFromSnapshot(snapshot);
+        for (const key of verdictUnsubs.keys()) {
+          if (!entries.has(key)) {
+            verdictUnsubs.get(key)();
+            verdictUnsubs.delete(key);
+          }
+        }
+        for (const [key, mem] of entries) {
+          const verdict = opts.evict(key, mem);
+          if (isNodeLike(verdict)) {
+            if (!verdictUnsubs.has(key)) {
+              const unsub = forEach(verdict, (val) => {
+                if (val === true && store.has(key)) {
+                  store.delete(key);
+                }
+              });
+              verdictUnsubs.set(key, unsub);
+            }
+            continue;
+          }
+          if (typeof verdict === "boolean") {
+            if (verdict) out.push(key);
+            continue;
+          }
+          throw new TypeError("distill evict() must return boolean or Node<boolean>");
+        }
+        actions.emit(out);
+      },
+      { describeKind: "derived" }
+    );
+    forEach(evictionKeys, (keys) => {
+      for (const key of keys) store.delete(key);
+    });
+  }
+  const hasConsolidateTrigger = opts.consolidateTrigger !== void 0 && opts.consolidateTrigger !== null;
+  if (opts.consolidate && hasConsolidateTrigger) {
+    const consolidateTriggerNode = fromAny(opts.consolidateTrigger);
+    const consolidatePaired = withLatestFrom(
+      consolidateTriggerNode,
+      store.entries
+    );
+    const consolidationStream = switchMap(
+      consolidatePaired,
+      ([, entries]) => opts.consolidate(mapFromSnapshot(entries))
+    );
+    forEach(consolidationStream, (extraction) => {
+      applyExtraction(store, extraction);
+    });
+  }
+  const compact = node(
+    [store.entries, contextNode],
+    (batchData, actions, ctx) => {
+      const data = batchData.map(
+        (batch2, i) => batch2 != null && batch2.length > 0 ? batch2.at(-1) : ctx.prevData[i]
+      );
+      const snapshot = data[0];
+      const context = data[1];
+      const map = mapFromSnapshot(snapshot);
+      const entries = [...map.entries()].map(([key, value]) => ({
+        key,
+        value,
+        score: opts.score(value, context),
+        cost: opts.cost(value)
+      }));
+      entries.sort((a, b) => b.score - a.score);
+      const packed = [];
+      let remaining = budget;
+      for (const item of entries) {
+        if (item.cost <= remaining) {
+          packed.push({ key: item.key, value: item.value, score: item.score });
+          remaining -= item.cost;
+        }
+      }
+      actions.emit(packed);
+    },
+    { describeKind: "derived", meta: { ...factoryTag("distill", { budget }) } }
+  );
+  const size = node(
+    [store.entries],
+    (batchData, actions, ctx) => {
+      const batch0 = batchData[0];
+      const snapshot = batch0 != null && batch0.length > 0 ? batch0.at(-1) : ctx.prevData[0];
+      actions.emit(mapFromSnapshot(snapshot).size);
+    },
+    { describeKind: "derived" }
+  );
+  keepalive(compact);
+  keepalive(size);
+  return { store, compact, size };
+}
+
+export {
+  distill
+};
+//# sourceMappingURL=chunk-A7KV5UK4.js.map

package/dist/chunk-A7KV5UK4.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/base/composition/distill.ts"],"sourcesContent":["/**\n * Budget-constrained reactive memory composition (roadmap §3.2b).\n *\n * Moved to base/composition/distill.ts during cleave A2.\n */\n\nimport { batch, factoryTag, type Node, node } from \"@graphrefly/pure-ts/core\";\nimport {\n\tfromAny,\n\ttype NodeInput,\n\ttype ReactiveMapBundle,\n\ttype ReactiveMapOptions,\n\treactiveMap,\n\tswitchMap,\n\twithLatestFrom,\n} from \"@graphrefly/pure-ts/extra\";\nimport { forEach } from \"../sources/async.js\";\n\nfunction isNodeLike<T>(value: unknown): value is Node<T> {\n\treturn (\n\t\ttypeof value === \"object\" &&\n\t\tvalue !== null &&\n\t\t\"cache\" in (value as Node<T>) &&\n\t\ttypeof (value as Node<T>).subscribe === \"function\"\n\t);\n}\n\nexport type Extraction<TMem> = {\n\tupsert: Array<{ key: string; value: TMem }>;\n\tremove?: string[];\n};\n\nexport type DistillOptions<TMem> = {\n\tscore: (mem: TMem, context: unknown) => number;\n\tcost: (mem: TMem) => number;\n\tbudget?: number;\n\tevict?: (key: string, mem: TMem) => boolean | Node<boolean>;\n\tconsolidate?: (entries: ReadonlyMap<string, TMem>) => NodeInput<Extraction<TMem>>;\n\tconsolidateTrigger?: NodeInput<unknown>;\n\tcontext?: NodeInput<unknown>;\n\tmapOptions?: ReactiveMapOptions<string, TMem>;\n};\n\nexport type DistillBundle<TMem> = {\n\tstore: ReactiveMapBundle<string, TMem>;\n\tcompact: Node<Array<{ key: string; value: TMem; score: number }>>;\n\tsize: Node<number>;\n};\n\nfunction keepalive(node: Node): void {\n\tnode.subscribe(() => undefined);\n}\n\n/**\n * Defensive snapshot → ReadonlyMap coercion (D2 /qa lock, Tier 9.1).\n *\n * `ReactiveMapBundle.entries` always emits a real `Map` on the live emit\n * path. The non-Map case happens on snapshot **restore**: the default\n * `JsonGraphCodec` serializes a `Map` to `null`/`{}`/`[]` depending on the\n * codec configuration, and `Graph.restore` writes that decoded value back\n * to the cache. A naive `(snapshot as ReadonlyMap) ?? new Map()` would\n * pass a plain object through and then `.entries()` / `.size` access would\n * silently yield wrong results (or throw). The runtime `instanceof Map`\n * check below restores the safety net the previous `mapFromSnapshot` helper\n * provided before its initial deletion in Tier 10.1.\n */\nfunction mapFromSnapshot<TMem>(snapshot: unknown): ReadonlyMap<string, TMem> {\n\tif (snapshot instanceof Map) return snapshot as ReadonlyMap<string, TMem>;\n\treturn new Map<string, TMem>();\n}\n\nfunction applyExtraction<TMem>(\n\tstore: ReactiveMapBundle<string, TMem>,\n\textraction: Extraction<TMem>,\n): void {\n\tif (!Array.isArray(extraction.upsert)) {\n\t\tthrow new TypeError(\"distill extraction requires upsert: Array<{ key, value }>\");\n\t}\n\tbatch(() => {\n\t\tfor (const { key, value } of extraction.upsert) {\n\t\t\tstore.set(key, value);\n\t\t}\n\t\tfor (const key of extraction.remove ?? []) {\n\t\t\tstore.delete(key);\n\t\t}\n\t});\n}\n\n/**\n * Budget-constrained reactive memory composition.\n *\n * **Tier 1.5.4 (Session A.5 lock, 2026-04-27):** `extractFn` receives the\n * source and existing-store as `Node`s. Distill calls `extractFn` ONCE at\n * wiring time and consumes the returned stream of extractions. The user\n * controls reactive composition — wrap with `switchMap` for cancel-on-new-input,\n * `mergeMap` for parallel, `derived` for sync transforms. See COMPOSITION-GUIDE\n * §40 for the recipe.\n */\nexport function distill<TRaw, TMem>(\n\tsource: NodeInput<TRaw>,\n\textractFn: (\n\t\traw: Node<TRaw>,\n\t\texisting: Node<ReadonlyMap<string, TMem>>,\n\t) => NodeInput<Extraction<TMem>>,\n\topts: DistillOptions<TMem>,\n): DistillBundle<TMem> {\n\tconst sourceNode = fromAny(source);\n\tconst store = reactiveMap<string, TMem>(opts.mapOptions ?? {});\n\tconst budget = opts.budget ?? 2000;\n\tconst hasContext = opts.context !== undefined && opts.context !== null;\n\tconst contextNode = hasContext ? fromAny(opts.context) : node<unknown>([], { initial: null });\n\n\t// `latestStore` (formerly a §28 closure-mirror) is no longer needed —\n\t// Phase 10.5 (`withLatestFrom` flipped to `partial: false`) fixed the\n\t// W1 initial-pair drop. `consolidate` now uses\n\t// `withLatestFrom(trigger, store.entries)` below to pair each trigger\n\t// with the latest store snapshot via a real reactive edge (visible in\n\t// `describe()`). The `mapFromSnapshot` transform runs inside the\n\t// switchMap fn body.\n\n\t// Tier 1.5.4: one-shot wire. User's `extractFn` returns the reactive\n\t// extraction stream — distill just `forEach`s and applies. No internal\n\t// switchMap; user picks the cancellation / queueing semantics.\n\tconst extractionStream = fromAny(\n\t\textractFn(sourceNode, store.entries as Node<ReadonlyMap<string, TMem>>),\n\t);\n\tforEach(extractionStream, (extraction) => {\n\t\tapplyExtraction(store, extraction);\n\t});\n\n\tif (opts.evict) {\n\t\t// Track active verdict-node subscriptions so we can react to Node<boolean> changes.\n\t\tconst verdictUnsubs = new Map<string, () => void>();\n\n\t\tconst evictionKeys = node<string[]>(\n\t\t\t[store.entries],\n\t\t\t(batchData, actions, ctx) => {\n\t\t\t\tconst batch0 = batchData[0];\n\t\t\t\tconst snapshot = batch0 != null && batch0.length > 0 ? batch0.at(-1) : ctx.prevData[0];\n\t\t\t\tconst out: string[] = [];\n\t\t\t\tconst entries = mapFromSnapshot<TMem>(snapshot);\n\t\t\t\t// Clean up verdict subscriptions for removed keys.\n\t\t\t\tfor (const key of verdictUnsubs.keys()) {\n\t\t\t\t\tif (!entries.has(key)) {\n\t\t\t\t\t\tverdictUnsubs.get(key)!();\n\t\t\t\t\t\tverdictUnsubs.delete(key);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tfor (const [key, mem] of entries) {\n\t\t\t\t\tconst verdict = opts.evict!(key, mem);\n\t\t\t\t\tif (isNodeLike<boolean>(verdict)) {\n\t\t\t\t\t\t// Subscribe if not already — push-on-subscribe fires with\n\t\t\t\t\t\t// the verdict's current value on first subscribe, so an\n\t\t\t\t\t\t// already-true verdict deletes via the callback without\n\t\t\t\t\t\t// needing a `verdict.cache` read (closes P3 audit #3).\n\t\t\t\t\t\t// Future transitions to `true` flow through the same path.\n\t\t\t\t\t\tif (!verdictUnsubs.has(key)) {\n\t\t\t\t\t\t\tconst unsub = forEach(verdict, (val) => {\n\t\t\t\t\t\t\t\tif (val === true && store.has(key)) {\n\t\t\t\t\t\t\t\t\tstore.delete(key);\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tverdictUnsubs.set(key, unsub);\n\t\t\t\t\t\t}\n\t\t\t\t\t\tcontinue;\n\t\t\t\t\t}\n\t\t\t\t\tif (typeof verdict === \"boolean\") {\n\t\t\t\t\t\tif (verdict) out.push(key);\n\t\t\t\t\t\tcontinue;\n\t\t\t\t\t}\n\t\t\t\t\tthrow new TypeError(\"distill evict() must return boolean or Node<boolean>\");\n\t\t\t\t}\n\t\t\t\tactions.emit(out);\n\t\t\t},\n\t\t\t{ describeKind: \"derived\" },\n\t\t);\n\t\tforEach(evictionKeys, (keys) => {\n\t\t\tfor (const key of keys) store.delete(key);\n\t\t});\n\t}\n\n\tconst hasConsolidateTrigger =\n\t\topts.consolidateTrigger !== undefined && opts.consolidateTrigger !== null;\n\tif (opts.consolidate && hasConsolidateTrigger) {\n\t\tconst consolidateTriggerNode = fromAny(opts.consolidateTrigger);\n\t\tconst consolidatePaired = withLatestFrom(\n\t\t\tconsolidateTriggerNode,\n\t\t\tstore.entries as Node<unknown>,\n\t\t);\n\t\tconst consolidationStream = switchMap(consolidatePaired, ([, entries]) =>\n\t\t\topts.consolidate!(mapFromSnapshot<TMem>(entries)),\n\t\t);\n\t\tforEach(consolidationStream, (extraction) => {\n\t\t\tapplyExtraction(store, extraction);\n\t\t});\n\t}\n\n\tconst compact = node<Array<{ key: string; value: TMem; score: number }>>(\n\t\t[store.entries, contextNode],\n\t\t(batchData, actions, ctx) => {\n\t\t\tconst data = batchData.map((batch, i) =>\n\t\t\t\tbatch != null && batch.length > 0 ? batch.at(-1) : ctx.prevData[i],\n\t\t\t);\n\t\t\tconst snapshot = data[0];\n\t\t\tconst context = data[1];\n\t\t\tconst map = mapFromSnapshot<TMem>(snapshot);\n\t\t\tconst entries = [...map.entries()].map(([key, value]) => ({\n\t\t\t\tkey,\n\t\t\t\tvalue,\n\t\t\t\tscore: opts.score(value, context),\n\t\t\t\tcost: opts.cost(value),\n\t\t\t}));\n\t\t\tentries.sort((a, b) => b.score - a.score);\n\n\t\t\tconst packed: Array<{ key: string; value: TMem; score: number }> = [];\n\t\t\tlet remaining = budget;\n\t\t\tfor (const item of entries) {\n\t\t\t\tif (item.cost <= remaining) {\n\t\t\t\t\tpacked.push({ key: item.key, value: item.value, score: item.score });\n\t\t\t\t\tremaining -= item.cost;\n\t\t\t\t}\n\t\t\t}\n\t\t\tactions.emit(packed);\n\t\t},\n\t\t{ describeKind: \"derived\", meta: { ...factoryTag(\"distill\", { budget }) } },\n\t);\n\n\tconst size = node<number>(\n\t\t[store.entries],\n\t\t(batchData, actions, ctx) => {\n\t\t\tconst batch0 = batchData[0];\n\t\t\tconst snapshot = batch0 != null && batch0.length > 0 ? batch0.at(-1) : ctx.prevData[0];\n\t\t\tactions.emit(mapFromSnapshot<TMem>(snapshot).size);\n\t\t},\n\t\t{ describeKind: \"derived\" },\n\t);\n\tkeepalive(compact);\n\tkeepalive(size);\n\n\treturn { store, compact, size };\n}\n"],"mappings":"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","names":["node","batch"]}

package/dist/chunk-APY2SS5X.js

@@ -0,0 +1,156 @@
+import {
+  sugiyamaLayout
+} from "./chunk-DMSNO6ZB.js";
+
+// src/utils/topology-view/index.ts
+import { Graph } from "@graphrefly/pure-ts/graph";
+
+// src/utils/topology-view/_internal.ts
+var MIN_W = 3;
+var MAX_W = 24;
+var NODE_H = 1;
+var LAYER_GAP = 4;
+var NODE_GAP = 1;
+function widthOf(id) {
+  const local = id.includes("::") ? id.split("::").pop() ?? id : id;
+  return Math.max(MIN_W, Math.min(MAX_W, local.length + 2));
+}
+function heightOf(_id) {
+  return NODE_H;
+}
+function defaultLayout(spec, direction = "LR") {
+  const ids = Object.keys(spec.nodes).sort();
+  const edges = spec.edges.map((e) => ({ from: e.from, to: e.to }));
+  if (ids.length === 0) {
+    return { boxes: [], edges: [] };
+  }
+  const result = sugiyamaLayout({
+    nodes: ids,
+    edges,
+    widthCells: widthOf,
+    heightCells: heightOf,
+    layerGap: LAYER_GAP,
+    nodeGap: NODE_GAP,
+    direction
+  });
+  const boxes = result.boxes.map((b) => ({
+    id: b.id,
+    x: b.x,
+    y: b.y,
+    w: b.w,
+    h: b.h,
+    meta: spec.nodes[b.id]?.meta
+  }));
+  const seenPerTo = /* @__PURE__ */ new Map();
+  const edgeOut = result.edges.map((e) => {
+    const toDeps = spec.nodes[e.to]?.deps ?? [];
+    const cursorKey = `${e.to}::${e.from}`;
+    const startFrom = seenPerTo.get(cursorKey) ?? 0;
+    const depIndex = toDeps.indexOf(e.from, startFrom);
+    seenPerTo.set(cursorKey, depIndex >= 0 ? depIndex + 1 : startFrom);
+    const points = e.points.map((p) => [p.x, p.y]);
+    return {
+      from: e.from,
+      to: e.to,
+      depIndex: depIndex >= 0 ? depIndex : -1,
+      points
+    };
+  });
+  return { boxes, edges: edgeOut };
+}
+
+// src/utils/topology-view/index.ts
+var TOPOLOGY_TYPES = /* @__PURE__ */ new Set([
+  "node-added",
+  "node-removed",
+  "mount",
+  "unmount"
+]);
+function isTopologyChange(c) {
+  return TOPOLOGY_TYPES.has(c.type);
+}
+var TopologyViewGraph = class extends Graph {
+  target;
+  layout;
+  frame;
+  constructor(opts) {
+    const name = opts.name ?? "topology-view";
+    super(name, opts.graphOptions);
+    this.target = opts.graph;
+    this.layout = opts.layout ?? ((spec) => defaultLayout(spec, "LR"));
+    const changeset = this.target.observe({
+      changeset: true,
+      changesetName: "target-changeset"
+    });
+    this.add(changeset, { name: "changeset" });
+    const seedLayout = this._computeLayout();
+    const layoutNode = this.derived(
+      "layout",
+      ["changeset"],
+      (data, _ctx) => {
+        const batch0 = data[0];
+        if (batch0 == null || batch0.length === 0) {
+          return [];
+        }
+        let topologyHit = false;
+        for (const c of batch0) {
+          if (isTopologyChange(c)) {
+            topologyHit = true;
+            break;
+          }
+        }
+        if (!topologyHit) {
+          return [];
+        }
+        return [this._computeLayout()];
+      },
+      { initial: seedLayout, partial: true }
+    );
+    void layoutNode;
+    this.frame = this.derived(
+      "frame",
+      ["layout", "changeset"],
+      (data, ctx) => {
+        const layoutBatch = data[0];
+        const changesetBatch = data[1];
+        const layout = layoutBatch != null && layoutBatch.length > 0 ? layoutBatch.at(-1) : ctx.prevData[0];
+        if (layout == null) {
+          return [];
+        }
+        const changes = [];
+        if (changesetBatch != null) {
+          for (const c of changesetBatch) changes.push(c);
+        }
+        return [
+          {
+            boxes: layout.boxes,
+            edges: layout.edges,
+            changes
+          }
+        ];
+      },
+      {
+        initial: { boxes: seedLayout.boxes, edges: seedLayout.edges, changes: [] },
+        partial: true
+      }
+    );
+  }
+  _computeLayout() {
+    if (this.target.destroyed) {
+      return { boxes: [], edges: [] };
+    }
+    const spec = this.target.describe();
+    return this.layout(spec);
+  }
+};
+function topologyView(opts) {
+  const view = new TopologyViewGraph(opts);
+  view.tagFactory("topologyView");
+  return view;
+}
+
+export {
+  TopologyViewGraph,
+  topologyView
+};
+//# sourceMappingURL=chunk-APY2SS5X.js.map

package/dist/chunk-APY2SS5X.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/topology-view/index.ts","../src/utils/topology-view/_internal.ts"],"sourcesContent":["/**\n * `topologyView({ graph, layout? }): TopologyViewGraph` — D3 of the\n * three-layer view (`docs/optimizations.md` line \"D — Three-layer view\").\n *\n * Composes a target {@link Graph} with a pluggable layered-DAG layout into a\n * live {@link LayoutFrame} stream:\n *\n * ```text\n * target graph\n *   └─ observe({ changeset: true })  →  Node<GraphChange>\n *        └─ filter(topology)         →  recompute layout\n *        └─ each change              →  merge into a LayoutFrame\n * ```\n *\n * **Initial frame** is delivered on subscribe (push-on-subscribe per spec\n * §2.2) — the layout is seeded from `graph.describe()` at construction. A\n * consumer that wants deltas only can `pipe(skip(1))` from the output node.\n *\n * **Pluggable layout** — pass `opts.layout` to swap in `dagre`, `elk`, or\n * any layered-DAG library. The default is a minimal Sugiyama in\n * `_internal.ts` (matches the library's \"no deps, browser-safe\" ethos).\n *\n * **No timers** — animation is driven by the changeset's batch boundaries.\n * Each batch IS a frame; CSS transitions handle visual fade.\n *\n * @module\n */\n\nimport type { Node } from \"@graphrefly/pure-ts/core\";\nimport { Graph, type GraphChange, type GraphOptions } from \"@graphrefly/pure-ts/graph\";\nimport { defaultLayout } from \"./_internal.js\";\nimport type { LayoutFn, LayoutFrame } from \"./types.js\";\n\nexport type {\n\tLayoutBox,\n\tLayoutEdge,\n\tLayoutFn,\n\tLayoutFrame,\n} from \"./types.js\";\n\n/** Topology variants from {@link GraphChange} that invalidate layout. */\nconst TOPOLOGY_TYPES = new Set<GraphChange[\"type\"]>([\n\t\"node-added\",\n\t\"node-removed\",\n\t\"mount\",\n\t\"unmount\",\n]);\n\nfunction isTopologyChange(c: GraphChange): boolean {\n\treturn TOPOLOGY_TYPES.has(c.type);\n}\n\n/** Options for {@link topologyView}. */\nexport interface TopologyViewOptions {\n\t/** The target graph to observe. */\n\treadonly graph: Graph;\n\t/**\n\t * Pluggable layout function. Defaults to the bundled Sugiyama layout.\n\t * Adapt `dagre` / `elk` / etc. by wrapping their output in the\n\t * {@link LayoutFn} shape.\n\t */\n\treadonly layout?: LayoutFn;\n\t/** Optional name for the {@link TopologyViewGraph}. Defaults to `\"topology-view\"`. */\n\treadonly name?: string;\n\t/**\n\t * Forward extra options to the underlying {@link Graph} constructor\n\t * (e.g. `versioning`, `traceCapacity`).\n\t */\n\treadonly graphOptions?: GraphOptions;\n}\n\n/**\n * Live topology view — a {@link Graph} subclass that exposes a single\n * output node {@link TopologyViewGraph.frame} emitting {@link LayoutFrame}s.\n */\nexport class TopologyViewGraph extends Graph {\n\treadonly target: Graph;\n\treadonly layout: LayoutFn;\n\treadonly frame: Node<LayoutFrame>;\n\n\tconstructor(opts: TopologyViewOptions) {\n\t\tconst name = opts.name ?? \"topology-view\";\n\t\tsuper(name, opts.graphOptions);\n\t\tthis.target = opts.graph;\n\t\tthis.layout = opts.layout ?? ((spec) => defaultLayout(spec, \"LR\"));\n\n\t\t// 1. Source node — discrete GraphChange events from the target graph.\n\t\t//    Every change (data + topology + batch boundaries) flows here.\n\t\tconst changeset = this.target.observe({\n\t\t\tchangeset: true,\n\t\t\tchangesetName: \"target-changeset\",\n\t\t});\n\t\tthis.add(changeset, { name: \"changeset\" });\n\n\t\t// 2. Layout — recomputes only on topology changes. Reads\n\t\t//    `target.describe()` inside the fn body — this is a method call on\n\t\t//    the stored Graph reference, NOT a `.cache` read of another\n\t\t//    reactive node, so it does not violate spec §5.12. Initial value\n\t\t//    is seeded from the construction-time describe so the first\n\t\t//    push-on-subscribe delivers a valid frame before any change\n\t\t//    arrives. `partial: true` opts out of the first-run gate (§2.7) —\n\t\t//    the seeded `initial` is correct from construction; we don't need\n\t\t//    to wait for the upstream changeset to deliver its first DATA.\n\t\tconst seedLayout = this._computeLayout();\n\t\tconst layoutNode = this.derived<Pick<LayoutFrame, \"boxes\" | \"edges\">>(\n\t\t\t\"layout\",\n\t\t\t[\"changeset\"],\n\t\t\t(data, _ctx) => {\n\t\t\t\tconst batch0 = data[0];\n\t\t\t\tif (batch0 == null || batch0.length === 0) {\n\t\t\t\t\t// No changeset DATA this wave (or this is the seed activation\n\t\t\t\t\t// before changeset has fired). Settle as RESOLVED — caller\n\t\t\t\t\t// will read `prevData[0]` if it needs the current layout.\n\t\t\t\t\treturn [];\n\t\t\t\t}\n\t\t\t\tlet topologyHit = false;\n\t\t\t\tfor (const c of batch0 as readonly GraphChange[]) {\n\t\t\t\t\tif (isTopologyChange(c)) {\n\t\t\t\t\t\ttopologyHit = true;\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tif (!topologyHit) {\n\t\t\t\t\t// Data-only wave: keep layout unchanged. The cached layout\n\t\t\t\t\t// (from `initial` or a prior emit) is still valid.\n\t\t\t\t\treturn [];\n\t\t\t\t}\n\t\t\t\treturn [this._computeLayout()];\n\t\t\t},\n\t\t\t{ initial: seedLayout, partial: true },\n\t\t);\n\t\tvoid layoutNode;\n\n\t\t// 3. Frame — merges latest layout with the per-wave changes from the\n\t\t//    changeset. Two deps: layout (slow-moving — re-emits only on\n\t\t//    topology) and changeset (fast-moving — re-emits per change event).\n\t\t//    The fn collapses each wave into one LayoutFrame.\n\t\t//\n\t\t//    `partial: true` opts out of the first-run gate so that a\n\t\t//    data-only wave (where the layout dep settles RESOLVED but\n\t\t//    changeset emits DATA) still triggers fn — without it, frame\n\t\t//    would never run for data events because layout settled RESOLVED\n\t\t//    and `_depSettledAsResolved` does NOT exit the sentinel state on\n\t\t//    a dep, leaving the gate closed indefinitely.\n\t\tthis.frame = this.derived<LayoutFrame>(\n\t\t\t\"frame\",\n\t\t\t[\"layout\", \"changeset\"],\n\t\t\t(data, ctx) => {\n\t\t\t\tconst layoutBatch = data[0];\n\t\t\t\tconst changesetBatch = data[1];\n\t\t\t\tconst layout =\n\t\t\t\t\tlayoutBatch != null && layoutBatch.length > 0\n\t\t\t\t\t\t? (layoutBatch.at(-1) as Pick<LayoutFrame, \"boxes\" | \"edges\">)\n\t\t\t\t\t\t: (ctx.prevData[0] as Pick<LayoutFrame, \"boxes\" | \"edges\"> | undefined);\n\t\t\t\tif (layout == null) {\n\t\t\t\t\t// No layout yet — defer (skip emit). With `initial:` on\n\t\t\t\t\t// `layout`, this should never happen on the activation\n\t\t\t\t\t// wave, but guard for the edge case.\n\t\t\t\t\treturn [];\n\t\t\t\t}\n\t\t\t\tconst changes: GraphChange[] = [];\n\t\t\t\tif (changesetBatch != null) {\n\t\t\t\t\tfor (const c of changesetBatch) changes.push(c as GraphChange);\n\t\t\t\t}\n\t\t\t\treturn [\n\t\t\t\t\t{\n\t\t\t\t\t\tboxes: layout.boxes,\n\t\t\t\t\t\tedges: layout.edges,\n\t\t\t\t\t\tchanges,\n\t\t\t\t\t},\n\t\t\t\t];\n\t\t\t},\n\t\t\t{\n\t\t\t\tinitial: { boxes: seedLayout.boxes, edges: seedLayout.edges, changes: [] },\n\t\t\t\tpartial: true,\n\t\t\t},\n\t\t);\n\n\t\t// No external keepalive — the chain `frame → layout → changeset` is\n\t\t// activated by external subscribers on `frame`. When the last consumer\n\t\t// unsubscribes, the chain tears down and releases the target observe\n\t\t// handle. Producer-bound lifecycle, no leaks.\n\t}\n\n\tprivate _computeLayout(): Pick<LayoutFrame, \"boxes\" | \"edges\"> {\n\t\t// /qa F-5: short-circuit if the target was destroyed. `target.describe()`\n\t\t// on a destroyed graph returns empty topology silently — without this\n\t\t// guard, frame consumers would see a degraded layout (empty boxes /\n\t\t// edges) with no signal that the underlying graph is gone. The COMPLETE\n\t\t// propagation is handled by the changeset stream's teardown variant\n\t\t// flowing through `frame`.\n\t\tif (this.target.destroyed) {\n\t\t\treturn { boxes: [], edges: [] };\n\t\t}\n\t\tconst spec = this.target.describe();\n\t\treturn this.layout(spec);\n\t}\n}\n\n/**\n * Factory wrapper — `topologyView({ graph, layout? })`.\n */\nexport function topologyView(opts: TopologyViewOptions): TopologyViewGraph {\n\tconst view = new TopologyViewGraph(opts);\n\tview.tagFactory(\"topologyView\");\n\treturn view;\n}\n","/**\n * Default layout for `topologyView` — wraps the bundled Sugiyama-style layered\n * DAG layout from `extra/render/_layout-sugiyama.ts`.\n *\n * The library ships zero deps and is browser-safe by default; the bundled\n * layout matches that ethos. Users wanting production-quality layout can swap\n * in `dagre`, `elk`, etc. by passing `opts.layout` to {@link topologyView}.\n *\n * Direction-agnostic (defaults to `\"LR\"`). Per-node label sizing is\n * conservative: 1 cell tall, label-length-derived width capped at 24 cells.\n *\n * @module\n */\n\nimport type { GraphDescribeOutput } from \"@graphrefly/pure-ts/graph\";\nimport {\n\ttype LayoutDirection,\n\ttype LayoutEdgePoint,\n\tsugiyamaLayout,\n} from \"../../base/render/_layout-sugiyama.js\";\nimport type { LayoutFn, LayoutFrame } from \"./types.js\";\n\nconst MIN_W = 3;\nconst MAX_W = 24;\nconst NODE_H = 1;\nconst LAYER_GAP = 4;\nconst NODE_GAP = 1;\n\n/**\n * Best-effort label-width estimate (cells). Caller can override by providing\n * its own {@link LayoutFn}; this default treats every visible character as\n * one cell. Local-segment is preferred over qualified path so the label\n * stays compact on cells with deep mounts.\n */\nfunction widthOf(id: string): number {\n\tconst local = id.includes(\"::\") ? (id.split(\"::\").pop() ?? id) : id;\n\treturn Math.max(MIN_W, Math.min(MAX_W, local.length + 2));\n}\n\nfunction heightOf(_id: string): number {\n\treturn NODE_H;\n}\n\n/**\n * Default layered-DAG layout for `topologyView`. Pure fn over a describe\n * snapshot; deterministic for a given input ordering.\n */\nexport function defaultLayout(\n\tspec: GraphDescribeOutput,\n\tdirection: LayoutDirection = \"LR\",\n): Pick<LayoutFrame, \"boxes\" | \"edges\"> {\n\tconst ids = Object.keys(spec.nodes).sort();\n\tconst edges = spec.edges.map((e) => ({ from: e.from, to: e.to }));\n\tif (ids.length === 0) {\n\t\treturn { boxes: [], edges: [] };\n\t}\n\tconst result = sugiyamaLayout({\n\t\tnodes: ids,\n\t\tedges,\n\t\twidthCells: widthOf,\n\t\theightCells: heightOf,\n\t\tlayerGap: LAYER_GAP,\n\t\tnodeGap: NODE_GAP,\n\t\tdirection,\n\t});\n\n\t// Map back to the public LayoutFrame shape, attaching per-node meta from\n\t// the describe snapshot for downstream renderers (kind/factory/domain).\n\tconst boxes = result.boxes.map((b) => ({\n\t\tid: b.id,\n\t\tx: b.x,\n\t\ty: b.y,\n\t\tw: b.w,\n\t\th: b.h,\n\t\tmeta: spec.nodes[b.id]?.meta,\n\t}));\n\n\t// Build a quick \"to → ordered deps\" lookup for `depIndex` attribution. The\n\t// describe snapshot's `nodes[id].deps` is the positional dep array; the\n\t// edge's depIndex is the position of `from` in `to`'s deps.\n\t//\n\t// /qa F-22: when the same upstream appears multiple times in `to.deps`\n\t// (diamond / duplicate-dep patterns), each (from, to) edge gets a distinct\n\t// depIndex via a per-`to` running cursor over occurrences in `toDeps`.\n\tconst seenPerTo = new Map<string, number>();\n\tconst edgeOut = result.edges.map((e) => {\n\t\tconst toDeps = spec.nodes[e.to]?.deps ?? [];\n\t\tconst cursorKey = `${e.to}::${e.from}`;\n\t\tconst startFrom = seenPerTo.get(cursorKey) ?? 0;\n\t\tconst depIndex = toDeps.indexOf(e.from, startFrom);\n\t\tseenPerTo.set(cursorKey, depIndex >= 0 ? depIndex + 1 : startFrom);\n\t\tconst points = e.points.map((p: LayoutEdgePoint) => [p.x, p.y] as const);\n\t\treturn {\n\t\t\tfrom: e.from,\n\t\t\tto: e.to,\n\t\t\tdepIndex: depIndex >= 0 ? depIndex : -1,\n\t\t\tpoints: points as ReadonlyArray<readonly [number, number]>,\n\t\t};\n\t});\n\n\treturn { boxes, edges: edgeOut };\n}\n\n/** Adapter — narrows `defaultLayout` to the {@link LayoutFn} signature. */\nexport const defaultLayoutFn: LayoutFn = (spec) => defaultLayout(spec, \"LR\");\n"],"mappings":"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","names":[]}

package/dist/chunk-AZDQPQ3V.js

@@ -0,0 +1,66 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __decoratorStart = (base) => [, , , __create(base?.[__knownSymbol("metadata")] ?? null)];
+var __decoratorStrings = ["class", "method", "getter", "setter", "accessor", "field", "value", "get", "set"];
+var __expectFn = (fn) => fn !== void 0 && typeof fn !== "function" ? __typeError("Function expected") : fn;
+var __decoratorContext = (kind, name, done, metadata, fns) => ({ kind: __decoratorStrings[kind], name, metadata, addInitializer: (fn) => done._ ? __typeError("Already initialized") : fns.push(__expectFn(fn || null)) });
+var __decoratorMetadata = (array, target) => __defNormalProp(target, __knownSymbol("metadata"), array[3]);
+var __runInitializers = (array, flags, self, value) => {
+  for (var i = 0, fns = array[flags >> 1], n = fns && fns.length; i < n; i++) flags & 1 ? fns[i].call(self) : value = fns[i].call(self, value);
+  return value;
+};
+var __decorateElement = (array, flags, name, decorators, target, extra) => {
+  var fn, it, done, ctx, access, k = flags & 7, s = !!(flags & 8), p = !!(flags & 16);
+  var j = k > 3 ? array.length + 1 : k ? s ? 1 : 2 : 0, key = __decoratorStrings[k + 5];
+  var initializers = k > 3 && (array[j - 1] = []), extraInitializers = array[j] || (array[j] = []);
+  var desc = k && (!p && !s && (target = target.prototype), k < 5 && (k > 3 || !p) && __getOwnPropDesc(k < 4 ? target : { get [name]() {
+    return __privateGet(this, extra);
+  }, set [name](x) {
+    return __privateSet(this, extra, x);
+  } }, name));
+  k ? p && k < 4 && __name(extra, (k > 2 ? "set " : k > 1 ? "get " : "") + name) : __name(target, name);
+  for (var i = decorators.length - 1; i >= 0; i--) {
+    ctx = __decoratorContext(k, name, done = {}, array[3], extraInitializers);
+    if (k) {
+      ctx.static = s, ctx.private = p, access = ctx.access = { has: p ? (x) => __privateIn(target, x) : (x) => name in x };
+      if (k ^ 3) access.get = p ? (x) => (k ^ 1 ? __privateGet : __privateMethod)(x, target, k ^ 4 ? extra : desc.get) : (x) => x[name];
+      if (k > 2) access.set = p ? (x, y) => __privateSet(x, target, y, k ^ 4 ? extra : desc.set) : (x, y) => x[name] = y;
+    }
+    it = (0, decorators[i])(k ? k < 4 ? p ? extra : desc[key] : k > 4 ? void 0 : { get: desc.get, set: desc.set } : target, ctx), done._ = 1;
+    if (k ^ 4 || it === void 0) __expectFn(it) && (k > 4 ? initializers.unshift(it) : k ? p ? extra = it : desc[key] = it : target = it);
+    else if (typeof it !== "object" || it === null) __typeError("Object expected");
+    else __expectFn(fn = it.get) && (desc.get = fn), __expectFn(fn = it.set) && (desc.set = fn), __expectFn(fn = it.init) && initializers.unshift(fn);
+  }
+  return k || __decoratorMetadata(array, target), desc && __defProp(target, name, desc), p ? k ^ 4 ? extra : desc : target;
+};
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateIn = (member, obj) => Object(obj) !== obj ? __typeError('Cannot use the "in" operator on this value') : member.has(obj);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+
+export {
+  __require,
+  __export,
+  __decoratorStart,
+  __runInitializers,
+  __decorateElement
+};
+//# sourceMappingURL=chunk-AZDQPQ3V.js.map

package/dist/chunk-AZDQPQ3V.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-BU3SEFA5.js

@@ -0,0 +1,90 @@
+import {
+  firstValueFrom
+} from "./chunk-O3MT7DYI.js";
+
+// src/base/composition/single-from-any.ts
+import { COMPLETE, ERROR } from "@graphrefly/pure-ts/core";
+import { fromAny } from "@graphrefly/pure-ts/extra";
+function singleFromAny(factory, opts = {}) {
+  const keyFn = opts.keyFn ?? ((k) => String(k));
+  const inFlight = /* @__PURE__ */ new Map();
+  return (key) => {
+    const k = keyFn(key);
+    const existing = inFlight.get(k);
+    if (existing) return existing;
+    const input = factory(key);
+    let rawPromise;
+    if (input != null && typeof input.then === "function") {
+      rawPromise = Promise.resolve(input);
+    } else if (input != null && typeof input === "object" && "subscribe" in input && "cache" in input) {
+      rawPromise = firstValueFrom(input);
+    } else if (input != null && typeof input === "object" && Symbol.asyncIterator in input) {
+      rawPromise = (async () => {
+        const iter = input[Symbol.asyncIterator]();
+        try {
+          const { value, done } = await iter.next();
+          if (done) throw new Error("singleFromAny: factory returned empty async iterable");
+          return value;
+        } finally {
+          await iter.return?.();
+        }
+      })();
+    } else if (input != null && typeof input === "object" && Symbol.iterator in input) {
+      rawPromise = (async () => {
+        const iter = input[Symbol.iterator]();
+        try {
+          const { value, done } = iter.next();
+          if (done) throw new Error("singleFromAny: factory returned empty iterable");
+          return value;
+        } finally {
+          iter.return?.();
+        }
+      })();
+    } else {
+      rawPromise = Promise.resolve(input);
+    }
+    let tracked;
+    const cleanup = () => {
+      if (inFlight.get(k) === tracked) inFlight.delete(k);
+    };
+    tracked = rawPromise.then(
+      (v) => {
+        cleanup();
+        return v;
+      },
+      (e) => {
+        cleanup();
+        throw e;
+      }
+    );
+    inFlight.set(k, tracked);
+    return tracked;
+  };
+}
+function singleNodeFromAny(factory, opts = {}) {
+  const keyFn = opts.keyFn ?? ((k) => String(k));
+  const inFlight = /* @__PURE__ */ new Map();
+  return (key) => {
+    const k = keyFn(key);
+    const existing = inFlight.get(k);
+    if (existing) return existing;
+    const node = fromAny(factory(key));
+    inFlight.set(k, node);
+    const unsub = node.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (m[0] === ERROR || m[0] === COMPLETE) {
+          if (inFlight.get(k) === node) inFlight.delete(k);
+          unsub();
+          return;
+        }
+      }
+    });
+    return node;
+  };
+}
+
+export {
+  singleFromAny,
+  singleNodeFromAny
+};
+//# sourceMappingURL=chunk-BU3SEFA5.js.map

package/dist/chunk-BU3SEFA5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/base/composition/single-from-any.ts"],"sourcesContent":["/**\n * `singleFromAny` — keyed promise/Node de-duplication (\"singleflight\").\n *\n * Given a `factory: (key) => NodeInput<T>`, returns a callable that dedupes\n * concurrent invocations sharing the same key — all callers with the same\n * key while a request is in-flight receive the same `Promise<T>`. Once the\n * underlying source settles (DATA, ERROR, or COMPLETE), the cache entry is\n * cleared so the next call re-invokes the factory.\n *\n * This is the classic \"singleflight\" pattern from Go, generalised over the\n * library's `NodeInput<T>` bridge so callers can pass Promise-returning\n * factories, Node-returning factories, or plain value factories with\n * identical semantics.\n *\n * Use cases:\n * - `withReplayCache` cache-miss thundering-herd dedup\n * - Shared HTTP fetches keyed by URL\n * - Expensive compute keyed by request fingerprint\n *\n * @example\n * ```ts\n * const fetchUser = singleFromAny<string, User>((id) => fetch(`/users/${id}`).then(r => r.json()));\n * // Two concurrent callers with id=\"42\" → one underlying fetch, two Promises resolving to the same User.\n * const [a, b] = await Promise.all([fetchUser(\"42\"), fetchUser(\"42\")]);\n * ```\n *\n * @category extra\n */\n\nimport type { Node } from \"@graphrefly/pure-ts/core\";\nimport { COMPLETE, ERROR } from \"@graphrefly/pure-ts/core\";\n// Import directly from the source sub-files (rather than the `./sources.js`\n// barrel) so the `single-from-any` module is NOT part of any cycle that runs\n// through `extra/sources/index.ts` — eager re-exports through the barrel were\n// observed to leave `firstValueFrom` / `keepalive` unresolved during nested\n// import chains under vite-node.\nimport { fromAny, type NodeInput } from \"@graphrefly/pure-ts/extra\";\nimport { firstValueFrom } from \"../sources/settled.js\";\n\nexport interface SingleFromAnyOptions<K> {\n\t/**\n\t * Convert a typed key into a cache-string. Defaults to `String(key)`, which\n\t * works for primitive keys; callers with object keys should provide a\n\t * stable serializer (e.g., canonical JSON).\n\t */\n\tkeyFn?: (key: K) => string;\n}\n\n/**\n * Dedupe concurrent `factory(key)` invocations. Returns a bound callable.\n *\n * @param factory - Produces a `NodeInput<T>` for each unique key.\n * @param opts - Optional key-stringification.\n * @returns A function `(key: K) => Promise<T>` whose inflight results are shared per key.\n */\nexport function singleFromAny<K, T>(\n\tfactory: (key: K) => NodeInput<T>,\n\topts: SingleFromAnyOptions<K> = {},\n): (key: K) => Promise<T> {\n\tconst keyFn = opts.keyFn ?? ((k: K) => String(k));\n\tconst inFlight = new Map<string, Promise<T>>();\n\n\treturn (key: K): Promise<T> => {\n\t\tconst k = keyFn(key);\n\t\tconst existing = inFlight.get(k);\n\t\tif (existing) return existing;\n\n\t\tconst input = factory(key);\n\n\t\t// Resolve the NodeInput to a Promise<T>. Different input shapes need\n\t\t// different bridges — Promise/Node/AsyncIterable/Iterable/plain value.\n\t\tlet rawPromise: Promise<T>;\n\t\tif (input != null && typeof (input as PromiseLike<T>).then === \"function\") {\n\t\t\trawPromise = Promise.resolve(input as PromiseLike<T>);\n\t\t} else if (\n\t\t\tinput != null &&\n\t\t\ttypeof input === \"object\" &&\n\t\t\t\"subscribe\" in (input as object) &&\n\t\t\t\"cache\" in (input as object)\n\t\t) {\n\t\t\t// Node: bridge via firstValueFrom.\n\t\t\trawPromise = firstValueFrom(input as Node<T>);\n\t\t} else if (\n\t\t\tinput != null &&\n\t\t\ttypeof input === \"object\" &&\n\t\t\tSymbol.asyncIterator in (input as object)\n\t\t) {\n\t\t\t// AsyncIterable — take the first value, then close the iterator so\n\t\t\t// any owned resources (HTTP body, subscription, timer) are released.\n\t\t\trawPromise = (async () => {\n\t\t\t\tconst iter = (input as AsyncIterable<T>)[Symbol.asyncIterator]();\n\t\t\t\ttry {\n\t\t\t\t\tconst { value, done } = await iter.next();\n\t\t\t\t\tif (done) throw new Error(\"singleFromAny: factory returned empty async iterable\");\n\t\t\t\t\treturn value as T;\n\t\t\t\t} finally {\n\t\t\t\t\tawait iter.return?.();\n\t\t\t\t}\n\t\t\t})();\n\t\t} else if (input != null && typeof input === \"object\" && Symbol.iterator in (input as object)) {\n\t\t\t// Iterable — take the first value, close the iterator.\n\t\t\trawPromise = (async () => {\n\t\t\t\tconst iter = (input as Iterable<T>)[Symbol.iterator]();\n\t\t\t\ttry {\n\t\t\t\t\tconst { value, done } = iter.next();\n\t\t\t\t\tif (done) throw new Error(\"singleFromAny: factory returned empty iterable\");\n\t\t\t\t\treturn value as T;\n\t\t\t\t} finally {\n\t\t\t\t\titer.return?.();\n\t\t\t\t}\n\t\t\t})();\n\t\t} else {\n\t\t\t// Plain value.\n\t\t\trawPromise = Promise.resolve(input as T);\n\t\t}\n\n\t\t// Install the cache entry BEFORE attaching `.finally`. Otherwise a\n\t\t// sync-resolved Promise's finally microtask could run before the\n\t\t// `inFlight.set` below, leaving a stale entry installed afterwards.\n\t\t// We wrap in a holder whose reference we capture *before* chaining.\n\t\tlet tracked!: Promise<T>;\n\t\tconst cleanup = (): void => {\n\t\t\tif (inFlight.get(k) === tracked) inFlight.delete(k);\n\t\t};\n\t\ttracked = rawPromise.then(\n\t\t\t(v) => {\n\t\t\t\tcleanup();\n\t\t\t\treturn v;\n\t\t\t},\n\t\t\t(e) => {\n\t\t\t\tcleanup();\n\t\t\t\tthrow e;\n\t\t\t},\n\t\t);\n\t\tinFlight.set(k, tracked);\n\t\treturn tracked;\n\t};\n}\n\n/**\n * Reactive variant: returns a bound callable that hands out `Node<T>` values.\n * All concurrent callers with the same key during an in-flight source share\n * the same Node. When the underlying source **terminally** settles (ERROR\n * or COMPLETE), the Node is removed from the cache so the next call\n * re-invokes `factory`. DATA is NOT terminal — callers subscribing after\n * the first DATA still receive the shared Node (and push-on-subscribe per\n * the spec's cached-DATA contract).\n *\n * Use when downstream wants reactive subscription (not a one-shot Promise).\n *\n * @category extra\n */\nexport function singleNodeFromAny<K, T>(\n\tfactory: (key: K) => NodeInput<T>,\n\topts: SingleFromAnyOptions<K> = {},\n): (key: K) => Node<T> {\n\tconst keyFn = opts.keyFn ?? ((k: K) => String(k));\n\tconst inFlight = new Map<string, Node<T>>();\n\n\treturn (key: K): Node<T> => {\n\t\tconst k = keyFn(key);\n\t\tconst existing = inFlight.get(k);\n\t\tif (existing) return existing;\n\n\t\tconst node = fromAny(factory(key));\n\t\tinFlight.set(k, node);\n\n\t\t// Evict on terminal settle only — ERROR or COMPLETE. DATA is a value\n\t\t// emission, not a lifecycle transition; multi-emitting Nodes should\n\t\t// continue to share across subscribers after the first value.\n\t\tconst unsub = node.subscribe((msgs) => {\n\t\t\tfor (const m of msgs) {\n\t\t\t\tif (m[0] === ERROR || m[0] === COMPLETE) {\n\t\t\t\t\tif (inFlight.get(k) === node) inFlight.delete(k);\n\t\t\t\t\tunsub();\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t}\n\t\t});\n\t\treturn node;\n\t};\n}\n"],"mappings":";;;;;AA8BA,SAAS,UAAU,aAAa;AAMhC,SAAS,eAA+B;AAmBjC,SAAS,cACf,SACA,OAAgC,CAAC,GACR;AACzB,QAAM,QAAQ,KAAK,UAAU,CAAC,MAAS,OAAO,CAAC;AAC/C,QAAM,WAAW,oBAAI,IAAwB;AAE7C,SAAO,CAAC,QAAuB;AAC9B,UAAM,IAAI,MAAM,GAAG;AACnB,UAAM,WAAW,SAAS,IAAI,CAAC;AAC/B,QAAI,SAAU,QAAO;AAErB,UAAM,QAAQ,QAAQ,GAAG;AAIzB,QAAI;AACJ,QAAI,SAAS,QAAQ,OAAQ,MAAyB,SAAS,YAAY;AAC1E,mBAAa,QAAQ,QAAQ,KAAuB;AAAA,IACrD,WACC,SAAS,QACT,OAAO,UAAU,YACjB,eAAgB,SAChB,WAAY,OACX;AAED,mBAAa,eAAe,KAAgB;AAAA,IAC7C,WACC,SAAS,QACT,OAAO,UAAU,YACjB,OAAO,iBAAkB,OACxB;AAGD,oBAAc,YAAY;AACzB,cAAM,OAAQ,MAA2B,OAAO,aAAa,EAAE;AAC/D,YAAI;AACH,gBAAM,EAAE,OAAO,KAAK,IAAI,MAAM,KAAK,KAAK;AACxC,cAAI,KAAM,OAAM,IAAI,MAAM,sDAAsD;AAChF,iBAAO;AAAA,QACR,UAAE;AACD,gBAAM,KAAK,SAAS;AAAA,QACrB;AAAA,MACD,GAAG;AAAA,IACJ,WAAW,SAAS,QAAQ,OAAO,UAAU,YAAY,OAAO,YAAa,OAAkB;AAE9F,oBAAc,YAAY;AACzB,cAAM,OAAQ,MAAsB,OAAO,QAAQ,EAAE;AACrD,YAAI;AACH,gBAAM,EAAE,OAAO,KAAK,IAAI,KAAK,KAAK;AAClC,cAAI,KAAM,OAAM,IAAI,MAAM,gDAAgD;AAC1E,iBAAO;AAAA,QACR,UAAE;AACD,eAAK,SAAS;AAAA,QACf;AAAA,MACD,GAAG;AAAA,IACJ,OAAO;AAEN,mBAAa,QAAQ,QAAQ,KAAU;AAAA,IACxC;AAMA,QAAI;AACJ,UAAM,UAAU,MAAY;AAC3B,UAAI,SAAS,IAAI,CAAC,MAAM,QAAS,UAAS,OAAO,CAAC;AAAA,IACnD;AACA,cAAU,WAAW;AAAA,MACpB,CAAC,MAAM;AACN,gBAAQ;AACR,eAAO;AAAA,MACR;AAAA,MACA,CAAC,MAAM;AACN,gBAAQ;AACR,cAAM;AAAA,MACP;AAAA,IACD;AACA,aAAS,IAAI,GAAG,OAAO;AACvB,WAAO;AAAA,EACR;AACD;AAeO,SAAS,kBACf,SACA,OAAgC,CAAC,GACX;AACtB,QAAM,QAAQ,KAAK,UAAU,CAAC,MAAS,OAAO,CAAC;AAC/C,QAAM,WAAW,oBAAI,IAAqB;AAE1C,SAAO,CAAC,QAAoB;AAC3B,UAAM,IAAI,MAAM,GAAG;AACnB,UAAM,WAAW,SAAS,IAAI,CAAC;AAC/B,QAAI,SAAU,QAAO;AAErB,UAAM,OAAO,QAAQ,QAAQ,GAAG,CAAC;AACjC,aAAS,IAAI,GAAG,IAAI;AAKpB,UAAM,QAAQ,KAAK,UAAU,CAAC,SAAS;AACtC,iBAAW,KAAK,MAAM;AACrB,YAAI,EAAE,CAAC,MAAM,SAAS,EAAE,CAAC,MAAM,UAAU;AACxC,cAAI,SAAS,IAAI,CAAC,MAAM,KAAM,UAAS,OAAO,CAAC;AAC/C,gBAAM;AACN;AAAA,QACD;AAAA,MACD;AAAA,IACD,CAAC;AACD,WAAO;AAAA,EACR;AACD;","names":[]}