omkit 0.8.15 → 0.8.17

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">;