omkit 0.8.16 → 0.8.17

package/README.md

@@ -132,6 +132,8 @@ Resolution happens **inside** the run, so a prompt and its answer land on the ru
 
 An action can `attach` a value — a port, a client, a page — that downstream actions receive by awaiting `activity.ref`. Not a file descriptor scraped from a log: a typed runtime handoff, so steps chain without globals or string-parsing. The first `attach` wins; later ones are ignored. Unlike `.result`, `.ref` **rejects** on failure or cancellation — a consumer waiting on a capability that never arrives fails instead of hanging — and an action that publishes nothing still resolves its `.ref` with `undefined` on success, so awaiting it never wedges.
 
+The handle `.ref` resolves is a thin, shallow wrapper over the attached value: every reader gets the same one, methods run bound to the real object (private fields work), and each public method call another action makes on it is recorded in the run — who called, from which line, how long it took — so the report can show it. Return values are not wrapped, and recording stops after 500 calls per handle.
+
 ```ts
 const server = action("server")
   .ref<number>() // this action publishes a port
@@ -189,7 +191,7 @@ Every action's output, events, asserts, snapshots, and lifecycle land on **one t
 - `raw.jsonl` — every entry, machine-readable.
 - `main.log` + one `.log` per action — the human-readable timelines.
 - `events.log` / `asserts.log` / `snapshots.log` / `artifacts.log` — cross-cutting rollups.
-- `report.html` — the whole run as one self-contained page: a timeline of every action with its events, a flow graph of the tree, per-action details, logs, assertions, the run's snapshots and images, each action's source (the `<>` button next to a block), and an Errors tab that collects failures, failed assertions and error output, and can highlight the actions they came from in every graph. Everything is inlined (data, base64 images, d3), so it opens straight from disk and survives being zipped or attached.
+- `report.html` — the whole run as one self-contained page: a timeline of every action with its events, a flow graph of the tree, per-action details, logs, assertions, the run's snapshots and images, each action's source (the `<>` button next to a block), an Errors tab that collects failures, failed assertions and error output, and can highlight the actions they came from in every graph, and the links between actions: who waited on whose event (`once`), who cancelled whom, and the calls made on another action's `.ref`. Everything is inlined (data, base64 images, d3), so it opens straight from disk and survives being zipped or attached.
 
 `ctx` also gives each action `assert(cond, msg)` (tallies into the run's verdict), `snapshot(name, value)` (captures JSON state to the run folder), and `artifact(name, file, opts?)` (labels a file the action wrote — name, optional description, MIME inferred from the extension — and returns its absolute path) — so a run is an inspectable artifact, not just an exit code. Write the files you label under `ctx.artifactsFolder`, the run's own output folder.
 

package/dist/core/ActionRun.d.ts

@@ -72,6 +72,8 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
     private attached;
     private observed;
     private refObserved;
+    /** The traced handle every `.ref` reader shares (see {@link traceHandle}); made on first read. */
+    private tracedRef;
     private cancelLogged;
     private armedExec;
     private armedArgs;
@@ -123,4 +125,6 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
      */
     private lifecycle;
     private log;
+    /** A cross-node interaction, on this (the targeted) node's log; `source` is the link's op. */
+    private link;
 }

package/dist/core/ActionRun.js

@@ -2,6 +2,9 @@ import { defer } from "../foundation/Deferred.js";
 import { events } from "../foundation/events.js";
 import { CancelledError } from "../foundation/CancelledError.js";
 import { renderValue } from "../foundation/format.js";
+import { callerSite } from "../foundation/callsite.js";
+import { currentNode } from "./context.js";
+import { traceHandle, REF_CALL_CAP } from "./refTrace.js";
 import { createProc } from "../system/proc.js";
 import { FolderCache } from "../system/fs/FolderCache.js";
 /**
@@ -45,6 +48,8 @@ export class ActionRun {
     attached = false;
     observed = false;
     refObserved = false;
+    /** The traced handle every `.ref` reader shares (see {@link traceHandle}); made on first read. */
+    tracedRef;
     cancelLogged = false;
     // The armed body + args, set at launch and run once by `commit()` on a microtask — the
     // window during which `withCache` may still wrap the body. `committed` closes that window.
@@ -108,7 +113,23 @@ export class ActionRun {
     /** The attached handle; rejects on failure/cancel. */
     get ref() {
         this.refObserved = true;
-        return this.handle.promise;
+        // One traced handle for every reader — identity holds across reads, and each method call
+        // another node makes on it is recorded here as a `ref` link.
+        if (!this.tracedRef) {
+            this.tracedRef = this.handle.promise.then((h) => traceHandle(h, {
+                call: (c) => this.link(`${c.key}() ← ${c.from} · ${c.ms}ms${c.outcome === "failed" ? " · failed" : ""}`, {
+                    op: "ref",
+                    from: c.from,
+                    ...(c.site ? { site: c.site } : {}),
+                    key: c.key,
+                    ms: c.ms,
+                    outcome: c.outcome,
+                }),
+                capped: () => this.log("info", "ref", `ref calls past ${REF_CALL_CAP} are not recorded`),
+            }));
+            void this.tracedRef.catch(() => { });
+        }
+        return this.tracedRef;
     }
     on(key, handler) {
         // A late `on("error")` (e.g. attached after an `await`, once the body has already
@@ -119,9 +140,29 @@ export class ActionRun {
         this.emitter.listen(key, handler);
     }
     once(key) {
+        // Who waits, from where — recorded on this node as a `once` link when the wait ends.
+        const from = currentNode.getStore();
+        const site = callerSite();
+        const t0 = Date.now();
+        const note = (outcome) => {
+            if (!from || from.id === this.id)
+                return;
+            const ms = Date.now() - t0;
+            this.link(`${String(key)} ← ${from.id} · ${outcome} after ${ms}ms`, {
+                op: "once",
+                from: from.id,
+                ...(site ? { site } : {}),
+                key: String(key),
+                ms,
+                outcome,
+            });
+        };
         // `done` is the outcome itself — identical to `.result` (resolve the value, reject on failure).
-        if (key === "done")
-            return this.result;
+        if (key === "done") {
+            const outcome = this.result;
+            outcome.then(() => note("fired"), () => note("failed"));
+            return outcome;
+        }
         // Awaiting an event observes the activity: resolve the payload when it fires, but if the
         // activity settles first, resolve `undefined` on success and **reject** on failure/cancel —
         // so an event gate surfaces a failure instead of hanging (or, for `error`, hand back the error).
@@ -130,16 +171,21 @@ export class ActionRun {
             let done = false;
             const win = () => (done ? false : (done = true));
             this.emitter.listenOnce(key, (p) => {
-                if (win())
-                    resolve(p);
+                if (!win())
+                    return;
+                note("fired");
+                resolve(p);
             });
             this.settled.promise.then(() => {
-                if (win())
-                    resolve(undefined);
+                if (!win())
+                    return;
+                note("ended");
+                resolve(undefined);
             }, (error) => {
                 if (!win())
                     return;
                 // Awaiting the `error` event hands back the error; any other gate rejects on failure.
+                note(key === "error" ? "fired" : "failed");
                 if (key === "error")
                     resolve(error);
                 else
@@ -165,6 +211,16 @@ export class ActionRun {
         return this;
     }
     cancel() {
+        // A cancel from another node is a link: who stopped this one, and from where.
+        const from = currentNode.getStore();
+        if (from && from.id !== this.id && this.parentId !== null && this.status === "running") {
+            const site = callerSite();
+            this.link(`by ${from.id}${site ? ` @ ${site}` : ""}`, {
+                op: "cancel",
+                from: from.id,
+                ...(site ? { site } : {}),
+            });
+        }
         this.noteCancelled(); // a direct cancel of this activity
         this.controller.abort();
     }
@@ -335,6 +391,17 @@ export class ActionRun {
     log(level, source, message) {
         this.store.append({ nodeId: this.id, path: this.path, level, source, message });
     }
+    /** A cross-node interaction, on this (the targeted) node's log; `source` is the link's op. */
+    link(message, link) {
+        this.store.append({
+            nodeId: this.id,
+            path: this.path,
+            level: "link",
+            source: link.op,
+            message,
+            link,
+        });
+    }
 }
 const messageOf = (error) => error instanceof Error ? (error.stack ?? error.message) : String(error);
 const firstLine = (message) => message.split("\n", 1)[0] ?? message;

package/dist/core/refTrace.d.ts

@@ -0,0 +1,22 @@
+/** Calls recorded per handle; past this the trace goes quiet, so a polling loop can't flood the log. */
+export declare const REF_CALL_CAP = 500;
+/** One method call on a traced handle, as {@link traceHandle} reports it. */
+export interface RefCall {
+    /** The calling node's id. */
+    readonly from: string;
+    readonly site: string | undefined;
+    readonly key: string;
+    readonly ms: number;
+    readonly outcome: "ok" | "failed";
+}
+/**
+ * Wrap an attached handle so each public method call on it is reported — who called (the
+ * ambient node), from where, how long it took, and whether it threw. Shallow by design: what
+ * a method returns is handed back untraced. Methods run bound to the real object, so private
+ * fields keep working; symbol, `_`-prefixed and {@link QUIET} members pass through unrecorded.
+ * A primitive or nullish handle is returned as is.
+ */
+export declare const traceHandle: <H>(handle: H, report: {
+    call: (call: RefCall) => void;
+    capped: () => void;
+}) => H;

package/dist/core/refTrace.js

@@ -0,0 +1,71 @@
+import { callerSite } from "../foundation/callsite.js";
+import { currentNode } from "./context.js";
+/** Calls recorded per handle; past this the trace goes quiet, so a polling loop can't flood the log. */
+export const REF_CALL_CAP = 500;
+/** Members never recorded: promise/serialization/inspection plumbing, not the caller's intent. */
+const QUIET = new Set([
+    "then",
+    "catch",
+    "finally",
+    "toJSON",
+    "toString",
+    "valueOf",
+    "inspect",
+    "constructor",
+]);
+/**
+ * Wrap an attached handle so each public method call on it is reported — who called (the
+ * ambient node), from where, how long it took, and whether it threw. Shallow by design: what
+ * a method returns is handed back untraced. Methods run bound to the real object, so private
+ * fields keep working; symbol, `_`-prefixed and {@link QUIET} members pass through unrecorded.
+ * A primitive or nullish handle is returned as is.
+ */
+export const traceHandle = (handle, report) => {
+    if (handle === null || (typeof handle !== "object" && typeof handle !== "function"))
+        return handle;
+    const cache = new Map();
+    let count = 0;
+    return new Proxy(handle, {
+        get(target, prop) {
+            const value = Reflect.get(target, prop, target);
+            if (typeof value !== "function")
+                return value;
+            // a non-configurable, read-only property must come back as itself (a Proxy invariant)
+            const own = Reflect.getOwnPropertyDescriptor(target, prop);
+            if (own && !own.configurable && !own.writable)
+                return value;
+            const hit = cache.get(prop);
+            if (hit && hit.orig === value)
+                return hit.fn;
+            const name = String(prop);
+            const quiet = typeof prop === "symbol" || name.startsWith("_") || QUIET.has(name);
+            const method = value;
+            const fn = (...args) => {
+                const from = currentNode.getStore()?.id;
+                if (quiet || !from || count >= REF_CALL_CAP)
+                    return method.apply(target, args);
+                if (++count === REF_CALL_CAP)
+                    report.capped();
+                const site = callerSite();
+                const t0 = Date.now();
+                const done = (outcome) => report.call({ from, site, key: name, ms: Date.now() - t0, outcome });
+                let out;
+                try {
+                    out = method.apply(target, args);
+                }
+                catch (error) {
+                    done("failed");
+                    throw error;
+                }
+                if (out !== null && typeof out?.then === "function") {
+                    out.then(() => done("ok"), () => done("failed"));
+                }
+                else
+                    done("ok");
+                return out;
+            };
+            cache.set(prop, { orig: value, fn });
+            return fn;
+        },
+    });
+};

package/dist/foundation/LogEntry.d.ts

@@ -13,11 +13,31 @@ export interface LogEntry {
     readonly nodeId: string;
     /** The owning node's execution path (`main/chromePage_9f3c`). */
     readonly path: string;
-    /** `info` | `error` | `event` | `assert` | `snapshot` | `artifact` | `tag` | `child` | `run`. */
+    /** `info` | `error` | `event` | `assert` | `snapshot` | `artifact` | `tag` | `child` | `run` | `link`. */
     readonly level: string;
     /** Finer origin within the node (proc name, `event`, `run`, …). */
     readonly source: string;
     readonly message: string;
+    /** Set on `level: "link"` entries — the other side of a cross-node interaction. */
+    readonly link?: LogLink;
+}
+/**
+ * A cross-node interaction, recorded on the node it targets: another node waited on one of
+ * its events (`once`), cancelled it (`cancel`), or called a method on its attached handle
+ * (`ref`). The entry's `ts` is when the interaction ended, so a timed one spans `ts - ms … ts`.
+ */
+export interface LogLink {
+    readonly op: "once" | "cancel" | "ref";
+    /** The calling node's id. */
+    readonly from: string;
+    /** `file:line` of the call, when the stack had one. */
+    readonly site?: string;
+    /** The awaited event key (`once`) or the called method (`ref`). */
+    readonly key?: string;
+    /** How long the wait or call lasted (`once`, `ref`). */
+    readonly ms?: number;
+    /** How it ended — `fired` | `ended` | `failed` for a once, `ok` | `failed` for a ref call. */
+    readonly outcome?: string;
 }
 /** What an appender supplies; the store stamps `sequence` and `ts`. */
 export type LogInput = Omit<LogEntry, "sequence" | "ts">;

package/dist/output/writers/report/report.css

@@ -147,10 +147,11 @@ button { font: inherit; color: inherit; }
 .row .label .tcall { font-size: 11.5px; }
 .row .label .sep, .row .l2 .sep { color: var(--text-3); }
 .row .l2 { font-size: 11px; color: var(--text-2); font-variant-numeric: tabular-nums; }
-.row .l2 .st { display: inline-flex; align-items: center; gap: 4px; flex: none; }
+.row .l2 .meta { display: inline-flex; align-items: center; gap: 6px; flex: none; margin-left: auto; padding-right: 4px; }
+.row .l2 .st { display: inline-flex; align-items: center; gap: 4px; }
 .row .l2 .dot { width: 7px; height: 7px; }
 .row .l2 .du { flex: none; }
-.row .l2 .chips { flex: 0 1 auto; flex-wrap: nowrap; overflow: hidden; margin-left: 2px; }
+.row .l2 .chips { flex: 0 1 auto; flex-wrap: nowrap; overflow: hidden; }
 .row .l2 .chip { flex: 0 1 auto; min-width: 24px; font-size: 10px; line-height: 14px; }
 .row .l2 .chip.more { flex: none; }
 .row .twist { width: 16px; height: 16px; flex: none; display: grid; place-items: center; color: var(--text-3); border: 0; background: none; padding: 0; cursor: pointer; }
@@ -471,6 +472,18 @@ a.icon-btn { text-decoration: none; }
 #app.hl-on .flow-card.err-path rect.box { stroke: var(--fail); stroke-width: 1.2; stroke-dasharray: 4 3; }
 #app.hl-on .tree .row.err { background: rgba(239, 68, 68, 0.1); }
 .chart g.r, .flow-card, .tree .row { transition: opacity 0.15s; }
+/* cross-node links: waits (dashed), ref calls (solid), connectors between rows / cards */
+.xl-span { stroke-width: 3; stroke-linecap: round; cursor: pointer; }
+.xl-span.once { stroke-width: 2.5; stroke-dasharray: 4 3; stroke-linecap: butt; }
+.xl-wire { fill: none; stroke-width: 1.4; stroke-dasharray: 3 3; opacity: 0.85; cursor: pointer; }
+.xl-span:hover { stroke-width: 4.5; }
+.xl-hit { fill: none; stroke: transparent; stroke-width: 10; cursor: pointer; }
+#xl-arrow path { fill: var(--text-2); }
+.flow-xlink { cursor: pointer; }
+.flow-xlink path { fill: none; stroke-width: 1.4; stroke-dasharray: 4 4; opacity: 0.8; }
+.flow-xlink path.hit { stroke: transparent; stroke-width: 12; stroke-dasharray: none; }
+.flow-xlink:hover path:not(.hit) { stroke-width: 2.6; opacity: 1; }
+.flow-xlink text { font-size: 10.5px; fill: var(--text-2); stroke: var(--panel); stroke-width: 3px; paint-order: stroke; }
 
 @media (max-width: 1100px) {
   .bottom { grid-template-columns: minmax(0, 1fr); }

package/dist/output/writers/report/report.js

@@ -63,6 +63,7 @@
     cancel: { color: "--cancel", icon: "stop", label: "Cancelled" },
     lifecycle: { color: "--c1", icon: "play", label: "Lifecycle" },
     run: { color: "--text-3", icon: "root", label: "Run" },
+    link: { color: "--text-3", icon: "flow", label: "Link" },
   };
 
   // ── formatting ───────────────────────────────────────────
@@ -156,7 +157,7 @@
       items.push(item);
       if (item.node) {
         item.node.entries.push(item);
-        if (kind !== "info" && kind !== "lifecycle") item.node.marks.push(item);
+        if (kind !== "info" && kind !== "lifecycle" && kind !== "link") item.node.marks.push(item);
       } else runEntries.push(item);
     }
 
@@ -186,6 +187,15 @@
       }
     }
 
+    // cross-node interactions, recorded on their target: who waited on, cancelled, or called into whom
+    const links = [];
+    for (const it of items) {
+      const l = it.kind === "link" && it.node && it.e.link;
+      const from = l && byId.get(l.from);
+      if (!from) continue;
+      links.push({ item: it, op: l.op, from, to: it.node, t: it.t, t0: it.t - (l.ms || 0), key: l.key || "", ms: l.ms, outcome: l.outcome || "", site: l.site || "" });
+    }
+
     const asserts = items.filter((i) => i.kind === "pass" || i.kind === "fail");
     const errors = collectErrors(items, nodes, run, tEnd - t0);
     const errorsBy = new Map();
@@ -209,6 +219,7 @@
       byId,
       root: nodes[0],
       items,
+      links,
       runEntries,
       gallery,
       asserts,
@@ -270,6 +281,7 @@
     return String(s).split("\n")[0];
   }
   function kindOf(e) {
+    if (e.level === "link") return "link";
     if (e.level === "assert") return e.message.startsWith("⊭") ? "fail" : "pass";
     if (e.level === "snapshot") return "snapshot";
     if (e.level === "artifact") return "artifact";
@@ -476,7 +488,7 @@
             <span class="l1"><span class="label">${labelHtml(n)}</span>${
               model.errorsBy.get(n) ? `<span class="errbadge" title="${model.errorsBy.get(n)} error${model.errorsBy.get(n) > 1 ? "s" : ""}">${model.errorsBy.get(n)}</span>` : ""
             }</span>
-            <span class="l2"><span class="st"><span class="dot ${n.status}"></span>${esc(n.status)}</span><span class="sep">·</span><span class="du">${fmtDur(n.duration)}</span>${tags}</span>
+            <span class="l2">${tags}<span class="meta"><span class="st"><span class="dot ${n.status}"></span>${esc(n.status)}</span><span class="sep">·</span><span class="du">${fmtDur(n.duration)}</span></span></span>
           </span>
         </div>
       </div>`;
@@ -503,7 +515,21 @@
         .on("mouseleave", () => moveCursor(null));
       chartSvg.append("g").attr("class", "grid");
       chartSvg.append("g").attr("class", "links");
+      chartSvg
+        .append("defs")
+        .append("marker")
+        .attr("id", "xl-arrow")
+        .attr("viewBox", "0 0 10 10")
+        .attr("refX", 9)
+        .attr("refY", 5)
+        .attr("markerWidth", 6)
+        .attr("markerHeight", 6)
+        .attr("orient", "auto")
+        .append("path")
+        .attr("d", "M0,1 L10,5 L0,9 z");
       chartSvg.append("g").attr("class", "rows");
+      // over the rows: their hover targets would otherwise swallow the link strips
+      chartSvg.append("g").attr("class", "xlinks");
       chartSvg.append("line").attr("class", "pin").attr("stroke", css("--accent")).attr("stroke-width", 1.5).attr("y1", 0).attr("y2", H);
       chartSvg.append("line").attr("class", "cursor").attr("y1", 0).attr("y2", H).attr("visibility", "hidden");
       chartSvg.call(chartZoom).call(chartZoom.transform, state.zoom);
@@ -619,11 +645,98 @@
       g.select("g.marks").each(function (n) {
         drawMarks(d3.select(this), n, x);
       });
+      drawLinks(x, index);
 
       chartSvg.select("line.pin").attr("x1", state.pin != null ? x(state.pin) : -10).attr("x2", state.pin != null ? x(state.pin) : -10);
       if (app.classList.contains("hl-on") || state.errHl) applyHl();
     }
 
+    /** The visible row standing in for `n`: its own, or its nearest expanded ancestor's. */
+    function rowIndexOf(n, index) {
+      for (let p = n; p; p = p.parent) if (index.has(p.id)) return index.get(p.id);
+      return -1;
+    }
+    /**
+     * Cross-node links on the timeline. A strip under the caller's bar holds its waits
+     * (`once`, dashed) and its calls on another action's ref (solid), in the target's colour;
+     * a dashed connector joins the two rows where a wait ended (target → waiter) and where a
+     * cancel landed (canceller → target).
+     */
+    function drawLinks(x, index) {
+      const STRIP_Y = BAR_Y + BAR_H + 3;
+      const spans = [];
+      const wires = [];
+      for (const l of model.links) {
+        const fi = rowIndexOf(l.from, index);
+        const ti = rowIndexOf(l.to, index);
+        if (fi < 0) continue;
+        if (l.op !== "cancel") spans.push({ l, fi });
+        if (l.op !== "ref" && ti >= 0 && ti !== fi) wires.push({ l, fi, ti });
+      }
+      const layer = chartSvg.select(".xlinks");
+      layer
+        .selectAll("line.xl-span")
+        .data(spans)
+        .join("line")
+        .attr("class", (d) => `xl-span ${d.l.op}`)
+        .attr("x1", (d) => x(d.l.t0))
+        .attr("x2", (d) => Math.max(x(d.l.t), x(d.l.t0) + 2))
+        .attr("y1", (d) => d.fi * ROW_H + STRIP_Y)
+        .attr("y2", (d) => d.fi * ROW_H + STRIP_Y)
+        .attr("stroke", (d) => colorOf(d.l.to))
+        .call(bindLink);
+      const wirePath = (d) => {
+        const px = x(d.l.t);
+        const fy = d.fi * ROW_H + STRIP_Y;
+        const ty = d.ti * ROW_H + BAR_Y + BAR_H / 2;
+        const [y1, y2] = d.l.op === "once" ? [ty, fy] : [fy, ty];
+        return `M${px},${y1} C${px + 10},${(2 * y1 + y2) / 3} ${px + 10},${(y1 + 2 * y2) / 3} ${px},${y2}`;
+      };
+      layer
+        .selectAll("path.xl-wire")
+        .data(wires)
+        .join("path")
+        .attr("class", (d) => `xl-wire ${d.l.op}`)
+        .attr("d", wirePath)
+        .attr("stroke", (d) => (d.l.op === "cancel" ? css("--cancel") : colorOf(d.l.to)))
+        .attr("marker-end", "url(#xl-arrow)");
+      // a wide transparent twin over each wire, so a 1px dashed line is easy to hover
+      layer.selectAll("path.xl-hit").data(wires).join("path").attr("class", "xl-hit").attr("d", wirePath).call(bindLink);
+    }
+    function bindLink(sel) {
+      sel
+        .on("click", (ev, d) => {
+          ev.stopPropagation();
+          setPin(d.l.t);
+          select(d.l.from.id, "links");
+        })
+        .on("mouseenter", (ev, d) => showTip(ev, linkTip(d.l), true))
+        .on("mousemove", (ev) => moveTip(ev))
+        .on("mouseleave", hideTip);
+    }
+    /** A link in words: who did what to whom, how it ended, and the line that did it. */
+    function linkTip(l, count) {
+      const from = esc(displayName(l.from));
+      const to = esc(displayName(l.to));
+      const title = l.op === "once" ? `once · ${esc(l.key)}` : l.op === "cancel" ? "cancel" : `ref · ${esc(l.key)}()`;
+      const what =
+        l.op === "once"
+          ? `<b>${from}</b> waited for <b>${esc(l.key)}</b> on <b>${to}</b>`
+          : l.op === "cancel"
+            ? `<b>${from}</b> cancelled <b>${to}</b>`
+            : `<b>${from}</b> called <b>${esc(l.key)}()</b> on <b>${to}</b>'s ref`;
+      const meta = [
+        count > 1 ? `×${count}` : "",
+        l.outcome ? esc(l.outcome) : "",
+        l.ms != null ? (l.op === "once" ? `after ${fmtDur(l.ms)}` : fmtDur(l.ms)) : "",
+        fmtRel(l.t),
+      ].filter(Boolean);
+      const line = (/:(\d+)$/.exec(l.site) || [])[1];
+      return `<div class="tt">${title}</div><div class="summary">${what}</div>
+        <div class="tmeta">${meta.join('<span class="sep">·</span>')}</div>
+        ${l.site ? `<div class="mono small" style="margin-top:6px">${esc(relOf(l.site))}${line ? ":" + line : ""}</div>` : ""}`;
+    }
+
     function drawMarks(g, n, x) {
       const cy = BAR_Y + BAR_H / 2;
       // cluster marks closer than 4px so a chatty node draws a readable line of dots
@@ -852,6 +965,70 @@
       }
 
       const nodes = [...pos.keys()].map((id) => model.byId.get(id));
+      // cross-node links: one curve per (caller, target, kind), arcing out past the cards' right
+      // edges; drawn first so the cards sit on top of their ends
+      const agg = new Map();
+      for (const l of model.links) {
+        if (!pos.has(l.from.id) || !pos.has(l.to.id) || l.from === l.to) continue;
+        const k = `${l.from.id}\0${l.to.id}\0${l.op}`;
+        if (!agg.has(k)) agg.set(k, { op: l.op, from: l.from, to: l.to, list: [] });
+        agg.get(k).list.push(l);
+      }
+      const xl = flowG.append("g").attr("class", "flow-xlinks");
+      const fan = new Map(); // edges between the same two cards fan out instead of overlapping
+      for (const a of agg.values()) {
+        const f = pos.get(a.from.id);
+        const t = pos.get(a.to.id);
+        const [s, e] = a.op === "once" ? [t, f] : [f, t];
+        const pair = [a.from.id, a.to.id].sort().join("");
+        const k = fan.get(pair) || 0;
+        fan.set(pair, k + 1);
+        const off = (k % 2 ? 1 : -1) * Math.ceil(k / 2) * 10;
+        let x1, y1, x2, y2, path, lx, ly;
+        if (Math.abs(s.x - e.x) < CW) {
+          // same column: arc out past the right edges
+          x1 = s.x + CW;
+          x2 = e.x + CW;
+          y1 = s.y + CH / 2 + off;
+          y2 = e.y + CH / 2 + off;
+          const bulge = 36 + Math.min(140, Math.abs(y2 - y1) * 0.2) + Math.abs(off);
+          path = `M${x1},${y1} C${x1 + bulge},${y1} ${x2 + bulge},${y2} ${x2 + 2},${y2}`;
+          lx = (x1 + x2) / 2 + bulge * 0.75 + 4;
+          ly = (y1 + y2) / 2 + 4;
+        } else {
+          // different columns: facing sides, an S-curve between them, below the tree's own links
+          const rightward = e.x > s.x;
+          x1 = rightward ? s.x + CW : s.x;
+          x2 = rightward ? e.x : e.x + CW;
+          y1 = s.y + CH * 0.72 + off;
+          y2 = e.y + CH * 0.72 + off;
+          const mx = (x1 + x2) / 2;
+          path = `M${x1},${y1} C${mx},${y1} ${mx},${y2} ${x2 + (rightward ? -2 : 2)},${y2}`;
+          lx = mx + 4;
+          ly = (y1 + y2) / 2 - 4;
+        }
+        const keys = [...new Set(a.list.map((l) => l.key))];
+        const label =
+          a.op === "cancel" ? "cancel" : a.op === "once" ? `once ${keys.join(", ")}` : keys.length === 1 ? `${keys[0]}() ×${a.list.length}` : `ref ×${a.list.length}`;
+        const g = xl
+          .append("g")
+          .attr("class", `flow-xlink ${a.op}`)
+          .on("click", (ev) => {
+            ev.stopPropagation();
+            select(a.from.id, "links");
+          })
+          .on("mouseenter", (ev) => showTip(ev, linkTip(a.list[a.list.length - 1], a.list.length), true))
+          .on("mousemove", (ev) => moveTip(ev))
+          .on("mouseleave", hideTip);
+        g.append("path")
+          .attr("d", path)
+          .attr("stroke", a.op === "cancel" ? css("--cancel") : colorOf(a.to))
+          .attr("marker-end", "url(#flow-arrow)");
+        g.append("path").attr("class", "hit").attr("d", path);
+        // between neighbouring columns there is no room for words — the tooltip carries them
+        if (Math.abs(x2 - x1) >= 90) g.append("text").attr("x", lx).attr("y", ly).text(truncate(label, 28));
+      }
+
       const card = flowG
         .append("g")
         .selectAll("g.flow-card")
@@ -1235,8 +1412,9 @@
     function detailSections(n) {
       const errs = model.errors.filter((e) => e.node === n);
       const params = schemaFields(n.v.inputSchema);
-      const evs = n.entries.filter((i) => i.kind !== "info");
+      const evs = n.entries.filter((i) => i.kind !== "info" && i.kind !== "link");
       const logs = n.entries.filter((i) => i.kind === "info" || i.kind === "error");
+      const lks = model.links.filter((l) => l.from === n || l.to === n);
       const shots = model.gallery.filter((x) => x.node === n);
       const asserts = n.entries.filter((i) => i.kind === "pass" || i.kind === "fail");
       const logLink = `<div class="acc-file">${svgIcon("file", ' width="14" height="14"')}<a href="${esc(fileUrl(n.v.logFile))}" title="${esc(n.v.logFile)}">${esc(basename(n.v.logFile))}</a></div>`;
@@ -1277,6 +1455,13 @@
           empty: !evs.length,
           body: () => `<ul class="ev-list">${evs.map((i) => evLi(i, n)).join("")}</ul>`,
         },
+        {
+          key: "links",
+          title: "Links",
+          count: lks.length,
+          empty: !lks.length,
+          body: () => linksHtml(n, lks),
+        },
         {
           key: "logs",
           title: "Logs",
@@ -1295,6 +1480,50 @@
       ];
     }
 
+    /**
+     * The details panel's links: what `n` did to other actions and what they did to it. Ref
+     * calls fold into one row per (other action, method), with a count and their total time.
+     */
+    function linksHtml(n, lks) {
+      const rows = [];
+      const refs = new Map();
+      for (const l of lks) {
+        if (l.op === "ref") {
+          const k = `${l.from.id}\0${l.to.id}\0${l.key}`;
+          if (!refs.has(k)) {
+            refs.set(k, { l, n: 0, ms: 0 });
+            rows.push(refs.get(k));
+          }
+          const r = refs.get(k);
+          r.n++;
+          r.ms += l.ms || 0;
+        } else rows.push({ l, n: 1, ms: l.ms || 0 });
+      }
+      const name = (x) => `<b>${esc(displayName(x))}</b>`;
+      return `<ul class="ev-list">${rows
+        .map(({ l, n: count, ms }) => {
+          const out = l.from === n;
+          const text =
+            l.op === "once"
+              ? out
+                ? `waited for ${esc(l.key)} on ${name(l.to)} · ${esc(l.outcome)} after ${fmtDur(ms)}`
+                : `${name(l.from)} waited for ${esc(l.key)} · ${esc(l.outcome)} after ${fmtDur(ms)}`
+              : l.op === "cancel"
+                ? out
+                  ? `cancelled ${name(l.to)}`
+                  : `cancelled by ${name(l.from)}`
+                : out
+                  ? `${name(l.to)}.${esc(l.key)}() ×${count} · ${fmtDur(ms)}`
+                  : `${name(l.from)} called ${esc(l.key)}() ×${count} · ${fmtDur(ms)}`;
+          const color = l.op === "cancel" ? css("--cancel") : colorOf(out ? l.to : l.from);
+          return `<li data-link="${model.links.indexOf(l)}" style="cursor:pointer">
+            <span class="t">${fmtRel(l.t - n.start)}</span>
+            <span class="ev-ico" style="background:${alpha(color, 0.2)};color:${color}">${svgIcon(l.op === "cancel" ? "stop" : l.op === "once" ? "pulse" : "code")}</span>
+            <span class="m">${out ? "→ " : "← "}${text}</span></li>`;
+        })
+        .join("")}</ul>`;
+    }
+
     /** A snapshot or file in the details panel: a small thumb with its name and when it landed. */
     function shotHtml(g, n) {
       const i = model.gallery.indexOf(g);
@@ -1329,6 +1558,9 @@
       root.querySelectorAll("[data-gallery]").forEach((t) =>
         t.addEventListener("click", () => openGallery(model.gallery[+t.dataset.gallery]))
       );
+      root.querySelectorAll("[data-link]").forEach((t) =>
+        t.addEventListener("click", () => setPin(model.links[+t.dataset.link].t))
+      );
       root.querySelectorAll("[data-item]").forEach((t) =>
         t.addEventListener("click", () => openItem(model.items[+t.dataset.item]))
       );
@@ -1548,7 +1780,7 @@
           ? (i) => i.kind === "info" || i.kind === "error"
           : tab === "asserts"
             ? (i) => i.kind === "pass" || i.kind === "fail"
-            : (i) => i.kind !== "info";
+            : (i) => i.kind !== "info" && !(i.kind === "link" && i.e.link && i.e.link.op === "ref");
       const rows = [];
       for (let idx = 0; idx < model.items.length; idx++) {
         const i = model.items[idx];
@@ -2089,6 +2321,8 @@
             ${legendItem("--fail", "Failure / error", "dot")}
             ${legendItem("--cancel", "Cancelled", "dash")}
             ${legendItem("--accent", "Pinned time", "line")}
+            ${legendItem("--text-2", "Waits for an event", "dash")}
+            ${legendItem("--text-2", "Call on a ref", "tick")}
           </div>
           <div class="muted" style="margin-top:12px;font-size:11px">Ctrl + wheel to zoom · drag to pan · double-click a bar to focus · ↑/↓ to step</div>
           </div>
@@ -2105,7 +2339,9 @@
     const sw =
       shape === "bar"
         ? `<span style="width:16px;height:9px;border-radius:3px;background:${c}"></span>`
-        : shape === "dash"
+        : shape === "tick"
+          ? `<span style="width:16px;height:3px;border-radius:2px;background:${c}"></span>`
+          : shape === "dash"
           ? `<span style="width:16px;height:0;border-top:2px dashed ${c}"></span>`
           : shape === "line"
             ? `<span style="width:2px;height:14px;background:${c};margin:0 7px"></span>`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.8.16",
+  "version": "0.8.17",
   "description": "A tiny runtime for developer workflows: typed actions that pass runtime capabilities and emit typed events, under one run and one shared log. The operational/runtime layer to tskb's knowledge layer.",
   "type": "module",
   "main": "./dist/index.js",