@loomwork/ui-hydration 0.0.0-stage → 0.1.0

package/dist/reshape.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonPathSelect = exports.outputShapeHashOf = void 0;
+exports.defineReshapers = defineReshapers;
+exports.safeStringify = safeStringify;
+exports.reshape = reshape;
+const core_1 = require("@loomwork/core");
+const plugin_sandbox_1 = require("@loomwork/plugin-sandbox");
+const select_1 = require("./select");
+/**
+ * The channel loom's sandbox completes on when the SCRIPT itself threw on its input (its own
+ * exception, a SyntaxError, a ReferenceError for a global the VM lacks). Recognised by channel
+ * only: its payload (`{ name?, message }`) is script-authored, UNTRUSTED text — it can echo the
+ * raw output — so it is never read, and never copied into a finding message.
+ */
+const SCRIPT_ERROR = "scriptError";
+const LIMIT_EXCEEDED = "limitExceeded";
+/** A sandbox `TypedFailure` → the output-caused kind it proves, if any. Channel + payload only. */
+function sandboxFailureKind(e) {
+    if (e.channel === SCRIPT_ERROR)
+        return "script-error";
+    if (e.channel !== LIMIT_EXCEEDED)
+        return undefined;
+    const kind = e.payload?.kind;
+    if (kind === "cpu")
+        return "limit-cpu";
+    if (kind === "memory")
+        return "limit-memory";
+    if (kind === "output")
+        return "limit-output";
+    return undefined; // wallClock (host-load dependent) or an unknown kind
+}
+/**
+ * A registry over a plain record. Map-backed, so only the record's OWN entries are registered —
+ * `"constructor"` or `"__proto__"` never resolve to something on a prototype.
+ */
+function defineReshapers(entries) {
+    const byName = new Map(Object.entries(entries));
+    return { get: (name) => byName.get(name) };
+}
+/**
+ * A Named reshaper runs in-process, trusted like host code — but the RAW terminal output is also
+ * read by callers after `reshape` returns (output-shape hashing, drift sampling): a reshaper that
+ * mutates its input in place must never corrupt what those later readers see, so it gets a copy,
+ * never the original reference. A raw value `structuredClone` cannot represent anywhere in its
+ * tree (a function; `structuredClone` throws) is REFUSED rather than handed to the reshaper live
+ * — that would let the reshaper corrupt what later readers see, exactly what the copy exists to
+ * prevent. (A class instance is not this case: `structuredClone` clones it fine, it just drops
+ * the prototype, so the copy is a plain object with the same own properties.) Throws; `runNamed`
+ * turns that into a `reshape-failed` finding before the reshaper ever runs.
+ */
+function cloneForReshaper(raw) {
+    try {
+        return structuredClone(raw);
+    }
+    catch {
+        throw new Error("input is not cloneable");
+    }
+}
+async function runNamed(name, raw, registry) {
+    const fn = registry?.get(name);
+    if (fn === undefined)
+        return {
+            ok: false,
+            finding: {
+                code: "reshape-unregistered",
+                severity: "error",
+                message: registry === undefined
+                    ? `reshaper "${name}" is Named, but no reshaper registry was supplied`
+                    : `no reshaper is registered under "${name}"`,
+            },
+        };
+    let cloned;
+    try {
+        cloned = cloneForReshaper(raw);
+    }
+    catch (err) {
+        // The OUTPUT is the cause: it holds a value that cannot be copied, so the reshaper never runs.
+        return {
+            ok: false,
+            failureKind: "uncloneable-output",
+            finding: {
+                code: "reshape-failed",
+                severity: "error",
+                message: `reshaper "${name}": ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
+    }
+    try {
+        return { ok: true, value: await fn(cloned) };
+    }
+    catch (err) {
+        // Host code threw: not proven output-caused, so no kind — a plain error, not drift.
+        return {
+            ok: false,
+            finding: {
+                code: "reshape-failed",
+                severity: "error",
+                message: `reshaper "${name}" failed: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
+    }
+}
+/**
+ * A finding MESSAGE must never be the thing that throws. A `TypedFailure` payload is authored by
+ * a tool server or a sandbox script — it can be cyclic, or carry a bigint, and `JSON.stringify`
+ * throws on both. Losing the payload text is a far better outcome than losing the finding.
+ * (Not exported from the package index: it exists for this package's message building.)
+ */
+function safeStringify(v) {
+    try {
+        return JSON.stringify(v) ?? String(v);
+    }
+    catch {
+        return "[unserializable payload]";
+    }
+}
+async function reshape(reshaping, raw, ctx) {
+    if (reshaping.engine === "JSONPath")
+        return (0, select_1.jsonPathSelect)(raw, reshaping.scriptRef);
+    if (reshaping.engine === "Named")
+        return runNamed(reshaping.scriptRef, raw, ctx.reshapers);
+    try {
+        const value = await ctx.invoker.invokeTransient(plugin_sandbox_1.SANDBOX_TOOL_ID, { scriptRef: { __loomContent: reshaping.scriptRef }, input: raw }, {
+            label: "loom-ui.reshape",
+            ...(ctx.signal && { signal: ctx.signal }),
+            ...(ctx.principal && { principal: ctx.principal }),
+        });
+        return { ok: true, value };
+    }
+    catch (err) {
+        if (err instanceof core_1.TypedFailure) {
+            const failureKind = sandboxFailureKind(err);
+            return {
+                ok: false,
+                ...(failureKind !== undefined && { failureKind }),
+                finding: {
+                    code: `reshape-${err.channel}`,
+                    severity: "error",
+                    // A `scriptError` payload is script-authored text that can echo the raw output
+                    // (possibly sensitive, untrusted): fixed text only, never its `name` or `message` —
+                    // no finding, handle status or log hook ever carries it. The raw output travels only
+                    // as the tainted drift sample. Other channels' payloads are loom-authored.
+                    message: failureKind === "script-error"
+                        ? `reshape script ${reshaping.scriptRef} failed on the output (script-error)`
+                        : `sandbox ${err.channel}: ${safeStringify(err.payload)}`,
+                },
+            };
+        }
+        return {
+            ok: false,
+            finding: {
+                code: "reshape-failed",
+                severity: "error",
+                message: err instanceof Error ? err.message : String(err),
+            },
+        };
+    }
+}
+var shape_1 = require("./shape");
+Object.defineProperty(exports, "outputShapeHashOf", { enumerable: true, get: function () { return shape_1.outputShapeHashOf; } });
+var select_2 = require("./select");
+Object.defineProperty(exports, "jsonPathSelect", { enumerable: true, get: function () { return select_2.jsonPathSelect; } });
+//# sourceMappingURL=reshape.js.map

package/dist/reshape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reshape.js","sourceRoot":"","sources":["../src/reshape.ts"],"names":[],"mappings":"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"}

package/dist/restricted.d.ts

@@ -0,0 +1,21 @@
+import { type Audience, type Finding, type HandleUse, type Viewer } from "@loomwork/ui-core";
+/**
+ * What the store (and so the viewer) is told about a refused handle. A fixed text: it names no
+ * handle, class, tool or argument, so refusing leaks nothing beyond "this is restricted".
+ */
+export declare const restrictedFinding: () => Finding;
+/** The advisory for classified handles with no viewer supplied (they are all refused). */
+export declare const viewerNotSuppliedFinding: () => Finding;
+/** Split an inventory into the handles a viewer may load and the ones it may not. */
+export declare function partitionByViewer(uses: readonly HandleUse[], viewer: Viewer | undefined): {
+    allowed: HandleUse[];
+    restricted: HandleUse[];
+    advisory: Finding[];
+};
+/**
+ * A copy of the viewer holding only a clearance read once; a throwing getter reads as none. For a
+ * broadcast `audience` the result is the audience's viewer (no clearance, whoever asked: the
+ * viewer is not even read), so a handle compile withheld for the audience is refused here too.
+ */
+export declare function snapshotViewer(viewer: Viewer | undefined, audience?: Audience): Viewer | undefined;
+//# sourceMappingURL=restricted.d.ts.map

package/dist/restricted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restricted.d.ts","sourceRoot":"","sources":["../src/restricted.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,MAAM,EAIZ,MAAM,mBAAmB,CAAC;AAS3B;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAAO,OAInC,CAAC;AAEH,0FAA0F;AAC1F,eAAO,MAAM,wBAAwB,QAAO,OAK1C,CAAC;AAEH,qFAAqF;AACrF,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,SAAS,EAAE,EAC1B,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB;IAAE,OAAO,EAAE,SAAS,EAAE,CAAC;IAAC,UAAU,EAAE,SAAS,EAAE,CAAC;IAAC,QAAQ,EAAE,OAAO,EAAE,CAAA;CAAE,CAUxE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,QAAQ,CAAC,EAAE,QAAQ,GAClB,MAAM,GAAG,SAAS,CASpB"}

package/dist/restricted.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.viewerNotSuppliedFinding = exports.restrictedFinding = void 0;
+exports.partitionByViewer = partitionByViewer;
+exports.snapshotViewer = snapshotViewer;
+const ui_core_1 = require("@loomwork/ui-core");
+// ── Viewer enforcement at the data boundary ───────────────────────────────────
+// Hydration is where data actually flows, so it is the second place a binding's `sensitivity`
+// is enforced (the first is `compile`, which redacts the node). A handle whose strictest class the
+// viewer may not see is never planned, never invoked, never cached, never served: its provider
+// is not called at all. FAIL-CLOSED: no viewer is a viewer with no clearance; unclassified handles
+// are unaffected either way. See `@loomwork/ui-core`'s `viewer.ts`.
+/**
+ * What the store (and so the viewer) is told about a refused handle. A fixed text: it names no
+ * handle, class, tool or argument, so refusing leaks nothing beyond "this is restricted".
+ */
+const restrictedFinding = () => ({
+    code: "restricted",
+    severity: "error",
+    message: "this data is restricted for the current viewer",
+});
+exports.restrictedFinding = restrictedFinding;
+/** The advisory for classified handles with no viewer supplied (they are all refused). */
+const viewerNotSuppliedFinding = () => ({
+    code: "viewer-not-supplied",
+    severity: "warn",
+    message: "the experience binds classified handles and no viewer was supplied: they are refused (no viewer is the most restrictive viewer)",
+});
+exports.viewerNotSuppliedFinding = viewerNotSuppliedFinding;
+/** Split an inventory into the handles a viewer may load and the ones it may not. */
+function partitionByViewer(uses, viewer) {
+    const allowed = [];
+    const restricted = [];
+    for (const use of uses)
+        ((0, ui_core_1.mayView)(viewer, use.sensitivity) ? allowed : restricted).push(use);
+    const classified = uses.some((u) => u.sensitivity !== undefined);
+    return {
+        allowed,
+        restricted,
+        advisory: classified && viewer === undefined ? [(0, exports.viewerNotSuppliedFinding)()] : [],
+    };
+}
+/**
+ * A copy of the viewer holding only a clearance read once; a throwing getter reads as none. For a
+ * broadcast `audience` the result is the audience's viewer (no clearance, whoever asked: the
+ * viewer is not even read), so a handle compile withheld for the audience is refused here too.
+ */
+function snapshotViewer(viewer, audience) {
+    if ((0, ui_core_1.isBroadcast)(audience))
+        return (0, ui_core_1.effectiveViewer)(undefined, audience);
+    if (viewer === undefined)
+        return undefined;
+    try {
+        const clearance = viewer.clearance;
+        return clearance === undefined ? {} : { clearance };
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=restricted.js.map

package/dist/restricted.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restricted.js","sourceRoot":"","sources":["../src/restricted.ts"],"names":[],"mappings":";;;AAoCA,8CAaC;AAOD,wCAYC;AApED,+CAQ2B;AAE3B,iFAAiF;AACjF,8FAA8F;AAC9F,mGAAmG;AACnG,+FAA+F;AAC/F,mGAAmG;AACnG,oEAAoE;AAEpE;;;GAGG;AACI,MAAM,iBAAiB,GAAG,GAAY,EAAE,CAAC,CAAC;IAC/C,IAAI,EAAE,YAAY;IAClB,QAAQ,EAAE,OAAO;IACjB,OAAO,EAAE,gDAAgD;CAC1D,CAAC,CAAC;AAJU,QAAA,iBAAiB,qBAI3B;AAEH,0FAA0F;AACnF,MAAM,wBAAwB,GAAG,GAAY,EAAE,CAAC,CAAC;IACtD,IAAI,EAAE,qBAAqB;IAC3B,QAAQ,EAAE,MAAM;IAChB,OAAO,EACL,iIAAiI;CACpI,CAAC,CAAC;AALU,QAAA,wBAAwB,4BAKlC;AAEH,qFAAqF;AACrF,SAAgB,iBAAiB,CAC/B,IAA0B,EAC1B,MAA0B;IAE1B,MAAM,OAAO,GAAgB,EAAE,CAAC;IAChC,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,KAAK,MAAM,GAAG,IAAI,IAAI;QAAE,CAAC,IAAA,iBAAO,EAAC,MAAM,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5F,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC;IACjE,OAAO;QACL,OAAO;QACP,UAAU;QACV,QAAQ,EAAE,UAAU,IAAI,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,IAAA,gCAAwB,GAAE,CAAC,CAAC,CAAC,CAAC,EAAE;KACjF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAC5B,MAA0B,EAC1B,QAAmB;IAEnB,IAAI,IAAA,qBAAW,EAAC,QAAQ,CAAC;QAAE,OAAO,IAAA,yBAAe,EAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACvE,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QACnC,OAAO,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/scheduler.d.ts

@@ -0,0 +1,82 @@
+import type { Finding, Priority } from "@loomwork/ui-core";
+import type { HydrationStore } from "./projection";
+export interface ScheduledJob {
+    readonly handle: string;
+    readonly priority: Priority;
+    /** The identity of the question. Same fingerprint + a live status = already asked; no re-run. */
+    readonly fingerprint: string;
+}
+/** What a load publishes. Serializable: it is also what a `HandleLoader` returns across a boundary. */
+export type HandleLoadResult = {
+    readonly state: "ready";
+    readonly value: unknown;
+    readonly finding?: Finding;
+} | {
+    readonly state: "stale" | "error";
+    readonly finding: Finding;
+}
+/** Delivered, and the upstream has no such row (`upstream-empty`): no value (loom ADR 0100). */
+ | {
+    readonly state: "empty";
+    readonly finding: Finding;
+};
+export interface SchedulerHooks<J extends ScheduledJob, G, R extends HandleLoadResult> {
+    newGroup(): G;
+    run(job: J, signal: AbortSignal, group: G): Promise<R>;
+    /** A value that needs no load (a cache hit): published `ready` at once. */
+    cached?(job: J): {
+        readonly value: unknown;
+    } | undefined;
+    /** The result is current (not superseded, not aborted) and about to be published. */
+    commit?(job: J, result: R): void;
+    /**
+     * The result was published. A throw here is swallowed: the handle keeps the status just
+     * published (the load is no longer in flight, so it is not moved to an error status) and
+     * nothing rejects.
+     */
+    published?(job: J, result: R): void;
+}
+export type TimerFn = (fn: () => void, ms: number) => () => void;
+export declare const defaultTimer: TimerFn;
+/** NUL: cannot occur in a handle or a hash, so joined fingerprints never collide. */
+export declare const KEY_SEP: string;
+export declare const disposedFinding: (what: string) => Finding;
+export declare const tooDeep: (experienceId: string, max: number) => Finding;
+export declare class HandleScheduler<J extends ScheduledJob, G, R extends HandleLoadResult> {
+    private readonly store;
+    private readonly hooks;
+    private readonly setTimer;
+    private readonly batchWindowMs;
+    private readonly inflight;
+    /**
+     * P1 jobs waiting for the batch timer, ONE per handle: a question changed inside the window
+     * replaces the queued one (the old one would otherwise start first and wedge the new one).
+     */
+    private pending;
+    private cancelBatch;
+    private readonly lazy;
+    /** handle → fingerprint of the job it was last STARTED with. Pruned with the handle. */
+    private readonly loaded;
+    private disposed;
+    constructor(store: HydrationStore, hooks: SchedulerHooks<J, G, R>, setTimer?: TimerFn, batchWindowMs?: number);
+    get isDisposed(): boolean;
+    /** Schedule by priority; a job whose question is already answered (or being answered) is skipped. */
+    schedule(jobs: readonly J[]): void;
+    /** Keep only these handles: abort, dequeue, forget and unpublish every other one. */
+    retain(keep: ReadonlySet<string>): void;
+    /**
+     * Ask again even if already asked: each in-flight load is superseded and a fresh one starts at
+     * once (one group). A lazy job stays lazy — its status untouched, its last value on screen.
+     */
+    reload(jobs: readonly J[]): void;
+    /** The surface reports a lazy (P2) widget entered the viewport. */
+    markVisible(handle: string): void;
+    inFlight(): string[];
+    /** Terminal: every in-flight or queued load ends on an error status, and nothing schedules again. */
+    dispose(): void;
+    /** A group made on first use, then shared: a call that starts nothing makes none. */
+    private lazyGroup;
+    private scheduleOne;
+    private start;
+}
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"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"}

package/dist/scheduler.js

@@ -0,0 +1,254 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HandleScheduler = exports.tooDeep = exports.disposedFinding = exports.KEY_SEP = exports.defaultTimer = void 0;
+const defaultTimer = (fn, ms) => {
+    const t = setTimeout(fn, ms);
+    return () => clearTimeout(t);
+};
+exports.defaultTimer = defaultTimer;
+/** NUL: cannot occur in a handle or a hash, so joined fingerprints never collide. */
+exports.KEY_SEP = String.fromCharCode(0);
+const disposedFinding = (what) => ({
+    code: "disposed",
+    severity: "error",
+    message: `the hydration controller is disposed; ${what} does nothing`,
+});
+exports.disposedFinding = disposedFinding;
+const tooDeep = (experienceId, max) => ({
+    code: "tree-too-deep",
+    severity: "error",
+    message: `experience "${experienceId}" exceeds MAX_TREE_DEPTH (${max})`,
+});
+exports.tooDeep = tooDeep;
+class HandleScheduler {
+    store;
+    hooks;
+    setTimer;
+    batchWindowMs;
+    inflight = new Map();
+    /**
+     * P1 jobs waiting for the batch timer, ONE per handle: a question changed inside the window
+     * replaces the queued one (the old one would otherwise start first and wedge the new one).
+     */
+    pending = new Map();
+    cancelBatch;
+    lazy = new Map();
+    /** handle → fingerprint of the job it was last STARTED with. Pruned with the handle. */
+    loaded = new Map();
+    disposed = false;
+    constructor(store, hooks, setTimer = exports.defaultTimer, batchWindowMs = 50) {
+        this.store = store;
+        this.hooks = hooks;
+        this.setTimer = setTimer;
+        this.batchWindowMs = batchWindowMs;
+    }
+    get isDisposed() {
+        return this.disposed;
+    }
+    /** Schedule by priority; a job whose question is already answered (or being answered) is skipped. */
+    schedule(jobs) {
+        if (this.disposed)
+            return;
+        // One group for every job this call starts now (a P1 batch and a markVisible get their own).
+        const now = this.lazyGroup();
+        for (const job of jobs)
+            this.scheduleOne(job, now);
+    }
+    /** Keep only these handles: abort, dequeue, forget and unpublish every other one. */
+    retain(keep) {
+        const drop = new Set();
+        for (const handle of [
+            ...this.inflight.keys(),
+            ...this.lazy.keys(),
+            ...this.pending.keys(),
+            ...this.store.handles(),
+        ])
+            if (!keep.has(handle))
+                drop.add(handle);
+        if (drop.size === 0)
+            return;
+        for (const handle of drop) {
+            this.inflight.get(handle)?.abort();
+            this.inflight.delete(handle);
+            this.lazy.delete(handle);
+            this.pending.delete(handle);
+            this.loaded.delete(handle);
+            if (this.store.status(handle) !== undefined)
+                this.store.remove(handle);
+        }
+    }
+    /**
+     * Ask again even if already asked: each in-flight load is superseded and a fresh one starts at
+     * once (one group). A lazy job stays lazy — its status untouched, its last value on screen.
+     */
+    reload(jobs) {
+        if (this.disposed)
+            return;
+        const group = this.lazyGroup();
+        for (const job of jobs) {
+            this.inflight.get(job.handle)?.abort();
+            this.inflight.delete(job.handle);
+            this.pending.delete(job.handle); // started below (or re-queued lazy): not a second time
+            if (job.priority === "P2") {
+                this.lazy.set(job.handle, job);
+                continue;
+            }
+            this.start(job, group()).catch(() => { });
+        }
+    }
+    /** The surface reports a lazy (P2) widget entered the viewport. */
+    markVisible(handle) {
+        if (this.disposed)
+            return;
+        const job = this.lazy.get(handle);
+        if (!job)
+            return;
+        this.lazy.delete(handle);
+        this.start(job, this.hooks.newGroup()).catch(() => { });
+    }
+    inFlight() {
+        return [...this.inflight.keys()].sort();
+    }
+    /** Terminal: every in-flight or queued load ends on an error status, and nothing schedules again. */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        for (const [handle, ac] of this.inflight) {
+            ac.abort();
+            // The widget must not sit on a spinner forever because its controller went away.
+            this.store.setStatus(handle, {
+                state: "error",
+                finding: {
+                    code: "disposed",
+                    severity: "error",
+                    message: `hydration for "${handle}" was disposed while in flight`,
+                },
+            });
+        }
+        this.inflight.clear();
+        this.cancelBatch?.();
+        this.cancelBatch = undefined;
+        for (const job of this.pending.values()) {
+            // Already published `pending`; leaving it there would spin the widget forever waiting on a
+            // batch timer that just got cancelled. Lazy jobs were never published: nothing to terminate.
+            this.store.setStatus(job.handle, {
+                state: "error",
+                finding: {
+                    code: "disposed",
+                    severity: "error",
+                    message: `hydration for "${job.handle}" was disposed while queued`,
+                },
+            });
+        }
+        this.pending.clear();
+        this.lazy.clear();
+        this.loaded.clear();
+    }
+    /** A group made on first use, then shared: a call that starts nothing makes none. */
+    lazyGroup() {
+        let made;
+        return () => {
+            if (made === undefined)
+                made = { group: this.hooks.newGroup() };
+            return made.group;
+        };
+    }
+    scheduleOne(job, group) {
+        const st = this.store.status(job.handle)?.state;
+        if (this.loaded.get(job.handle) === job.fingerprint) {
+            // Same question, already asked: loading, loaded (an `empty` answer is an answer), or
+            // drifted-and-awaiting-repair.
+            if (st === "ready" || st === "pending" || st === "stale" || st === "empty")
+                return;
+        }
+        else {
+            // A different question for this handle: whatever is in flight answers the OLD one.
+            this.inflight.get(job.handle)?.abort();
+            this.inflight.delete(job.handle);
+        }
+        // A job queued for the batch answers the old question (or the old priority): this one owns it.
+        this.pending.delete(job.handle);
+        if (job.priority === "P2") {
+            this.lazy.set(job.handle, job);
+            return;
+        }
+        this.lazy.delete(job.handle); // promoted out of P2: the lazy entry has a new owner
+        if (job.priority === "P0") {
+            this.start(job, group()).catch(() => { });
+            return;
+        }
+        this.store.setStatus(job.handle, { state: "pending" });
+        // Keyed by handle: a changed question REPLACES the queued one rather than queueing behind it.
+        this.pending.set(job.handle, job);
+        this.cancelBatch ??= this.setTimer(() => {
+            this.cancelBatch = undefined;
+            const batch = [...this.pending.values()];
+            this.pending.clear();
+            if (batch.length === 0)
+                return;
+            const g = this.hooks.newGroup();
+            for (const j of batch)
+                this.start(j, g).catch(() => { });
+        }, this.batchWindowMs);
+    }
+    async start(job, group) {
+        const { handle } = job;
+        if (this.disposed)
+            return;
+        this.loaded.set(handle, job.fingerprint);
+        const cached = this.hooks.cached?.(job);
+        if (cached) {
+            this.inflight.delete(handle);
+            this.store.setValue(handle, cached.value, { state: "ready" });
+            return;
+        }
+        if (this.inflight.has(handle))
+            return;
+        const ac = new AbortController();
+        this.inflight.set(handle, ac);
+        try {
+            this.store.setStatus(handle, { state: "pending" });
+            const result = await this.hooks.run(job, ac.signal, group);
+            if (this.inflight.get(handle) !== ac || ac.signal.aborted)
+                return; // superseded or aborted
+            this.inflight.delete(handle);
+            this.hooks.commit?.(job, result);
+            if (result.state === "ready")
+                this.store.setValue(handle, result.value, {
+                    state: "ready",
+                    ...(result.finding && { finding: result.finding }),
+                });
+            else
+                this.store.setStatus(handle, { state: result.state, finding: result.finding });
+            this.hooks.published?.(job, result);
+        }
+        catch (e) {
+            // `run` is total by construction — but a loader or invoker that rejects with a value whose
+            // message getter throws, a store subscriber that throws synchronously on ANY publish here
+            // (including the first `pending`), or any future defect must land on the widget as an error
+            // status, never as an unhandled rejection that takes the host process down.
+            if (this.inflight.get(handle) !== ac || ac.signal.aborted)
+                return;
+            this.inflight.delete(handle);
+            try {
+                // The publish below can re-trigger the very subscriber whose throw got us here. A second
+                // throw must not escape: `inflight` is already cleaned up, which is the invariant
+                // `dispose`/`retain`/`inFlight` depend on.
+                this.store.setStatus(handle, {
+                    state: "error",
+                    finding: {
+                        code: "hydration-internal",
+                        severity: "error",
+                        message: e instanceof Error ? e.message : String(e),
+                    },
+                });
+            }
+            catch {
+                // Ignored — see comment above.
+            }
+        }
+    }
+}
+exports.HandleScheduler = HandleScheduler;
+//# sourceMappingURL=scheduler.js.map

package/dist/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"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"}

package/dist/select.d.ts

@@ -0,0 +1,34 @@
+import type { Finding } from "@loomwork/ui-core";
+/**
+ * Why a reshaping failed, when the tool OUTPUT demonstrably caused it — the failures a re-authored
+ * binding can repair. Typed from the failure's channel and payload, never from message text:
+ *
+ * - `script-error`: the sandbox reports the script threw on this input (a `TypedFailure` on loom's
+ *   `scriptError` channel, `SANDBOX_ERRORS.scriptError`).
+ * - `selects-nothing`: a JSONPath selects nothing from the output.
+ * - `uncloneable-output`: the output holds a value `structuredClone` cannot copy (a function, say),
+ *   so a Named reshaper is never handed it. Recorded WITHOUT a sample: such a value is not a data
+ *   observation a planner can author against.
+ * - `limit-cpu`, `limit-memory`, `limit-output`: a deterministic resource limit the script hit on
+ *   this input. `limit-cpu` is measured against the host's instruction-count `interruptBudget`,
+ *   not time — deterministic for a given budget, so LOWERING the budget surfaces as output drift.
+ *
+ * Anything else has no kind and is not drift. That includes a `wallClock` limit (host-load
+ * dependent — on a loaded host a script can trip `wallClock` before `cpu`, and then no drift is
+ * reported that time), a Named reshaper's own throw (host code: a host bug or its own I/O is not
+ * proven output-caused, and must never get the host's reshaper replaced by a model-authored
+ * binding), a missing script, an unregistered reshaper, an untyped throw (transport, worker pool,
+ * integrity), an authorization or quota denial, and an abort.
+ */
+export type ReshapeFailureKind = "script-error" | "selects-nothing" | "uncloneable-output" | "limit-cpu" | "limit-memory" | "limit-output";
+export type ReshapeResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    finding: Finding;
+    /** Set only when the output demonstrably caused the failure (see `ReshapeFailureKind`). */
+    failureKind?: ReshapeFailureKind;
+};
+export declare function jsonPathSelect(value: unknown, path: string): ReshapeResult;
+//# sourceMappingURL=select.d.ts.map