@loomwork/ui-hydration 0.0.0-stage → 0.1.1

package/src/repair.ts

@@ -0,0 +1,70 @@
+import type { Finding, Operation, ProviderSpec } from "@loomwork/ui-core";
+import type { DriftRecord } from "./provider";
+
+// ── Crossing the determinism boundary ─────────────────────────────────────────
+// Hydration REPORTS drift; it never repairs. The app runs a durable loom execution that applies
+// the operation built here (via core's `apply`, so the artifact's lineage records it), emits
+// SCHEMA_REPAIRED with this payload, and re-seals. Input drift (a tool's input schema moved) is a
+// pin move and can be remapped mechanically; output drift (the reshaped value's shape changed)
+// means the reshaping is wrong for the data and needs the planner — that is a different slice.
+
+export const SCHEMA_REPAIRED = "SCHEMA_REPAIRED";
+
+export interface SchemaRepairedPayload {
+  readonly experienceId: string;
+  readonly versionHash: string;
+  readonly handle: string;
+  readonly drift: readonly DriftRecord[];
+  readonly op: Operation;
+}
+
+export function remapOperation(
+  spec: ProviderSpec,
+  drift: readonly DriftRecord[]
+): { ok: true; op: Operation } | { ok: false; finding: Finding } {
+  if (drift.length === 0)
+    return {
+      ok: false,
+      finding: { code: "repair-mismatch", severity: "error", message: "no drift to repair" },
+    };
+  if (drift.some((d) => d.kind === "output"))
+    return {
+      ok: false,
+      finding: {
+        code: "repair-needs-planner",
+        severity: "error",
+        message: `provider "${spec.handle}": output shape drifted; remapping a pin cannot fix a reshaping that no longer matches the data`,
+      },
+    };
+  const steps = new Map(spec.executionGraph.map((s) => [s.stepId, s] as const));
+  for (const d of drift) {
+    if (d.handle !== spec.handle)
+      return {
+        ok: false,
+        finding: {
+          code: "repair-mismatch",
+          severity: "error",
+          message: `drift for "${d.handle}" applied to provider "${spec.handle}"`,
+        },
+      };
+    if (d.stepId === undefined || !steps.has(d.stepId))
+      return {
+        ok: false,
+        finding: {
+          code: "repair-mismatch",
+          severity: "error",
+          message: `drift names step "${d.stepId ?? "?"}", which provider "${spec.handle}" does not have`,
+        },
+      };
+  }
+  const observedByStep = new Map(drift.map((d) => [d.stepId as string, d.observed]));
+  const executionGraph = spec.executionGraph.map((s) =>
+    observedByStep.has(s.stepId)
+      ? { ...s, toolSchemaHash: observedByStep.get(s.stepId) as string }
+      : s
+  );
+  return {
+    ok: true,
+    op: { type: "remapProvider", handle: spec.handle, spec: { ...spec, executionGraph } },
+  };
+}

package/src/reshape.ts

@@ -0,0 +1,193 @@
+import { TypedFailure } from "@loomwork/core";
+import type { TransientInvokeOptions } from "@loomwork/effect-runtime";
+import { type SANDBOX_ERRORS, SANDBOX_TOOL_ID } from "@loomwork/plugin-sandbox";
+import type { Finding, ProviderSpec } from "@loomwork/ui-core";
+import type { TransientInvoker } from "./invoker";
+import { type ReshapeFailureKind, type ReshapeResult, jsonPathSelect } from "./select";
+
+// ── Reshaping ─────────────────────────────────────────────────────────────────
+// `QuickJS`: a content-addressed script runs in loom's sandbox (the effect-local middleware,
+// limits and typed channels apply; nothing is logged). `JSONPath`: the scriptRef IS the path,
+// selected inline — see the ProviderSpec.reshaping comment in core for the convention. `Named`:
+// the scriptRef names a reshaper the HOST registered (`defineReshapers`); it runs in-process as
+// host code, trusted like the host, with no sandbox hop. Each engine has its own branch: an
+// engine this function does not know is never sent to the sandbox by default.
+
+/** A channel loom's sandbox declares (`SANDBOX_ERRORS`) — a rename there fails to compile here. */
+type SandboxChannel = keyof typeof SANDBOX_ERRORS;
+
+/**
+ * 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: SandboxChannel = "scriptError";
+const LIMIT_EXCEEDED: SandboxChannel = "limitExceeded";
+
+/** A sandbox `TypedFailure` → the output-caused kind it proves, if any. Channel + payload only. */
+function sandboxFailureKind(e: TypedFailure): ReshapeFailureKind | undefined {
+  if (e.channel === SCRIPT_ERROR) return "script-error";
+  if (e.channel !== LIMIT_EXCEEDED) return undefined;
+  const kind = (e.payload as { kind?: unknown } | null | undefined)?.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 host-registered reshaper: the raw terminal output in, the widget's value out. */
+export type Reshaper = (input: unknown) => unknown | Promise<unknown>;
+
+/** Where `Named` reshaping looks a name up. Injected — hydration registers nothing itself. */
+export interface ReshaperRegistry {
+  get(name: string): Reshaper | undefined;
+}
+
+/**
+ * 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.
+ */
+export function defineReshapers(entries: Readonly<Record<string, Reshaper>>): ReshaperRegistry {
+  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: unknown): unknown {
+  try {
+    return structuredClone(raw);
+  } catch {
+    throw new Error("input is not cloneable");
+  }
+}
+
+async function runNamed(
+  name: string,
+  raw: unknown,
+  registry: ReshaperRegistry | undefined
+): Promise<ReshapeResult> {
+  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: unknown;
+  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.)
+ */
+export function safeStringify(v: unknown): string {
+  try {
+    return JSON.stringify(v) ?? String(v);
+  } catch {
+    return "[unserializable payload]";
+  }
+}
+
+export async function reshape(
+  reshaping: ProviderSpec["reshaping"],
+  raw: unknown,
+  ctx: {
+    invoker: TransientInvoker;
+    signal?: AbortSignal;
+    principal?: TransientInvokeOptions["principal"];
+    reshapers?: ReshaperRegistry;
+  }
+): Promise<ReshapeResult> {
+  if (reshaping.engine === "JSONPath") return jsonPathSelect(raw, reshaping.scriptRef);
+  if (reshaping.engine === "Named") return runNamed(reshaping.scriptRef, raw, ctx.reshapers);
+  try {
+    const value = await ctx.invoker.invokeTransient(
+      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 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),
+      },
+    };
+  }
+}
+
+export { outputShapeHashOf } from "./shape";
+export { jsonPathSelect } from "./select";
+export type { ReshapeFailureKind, ReshapeResult } from "./select";

package/src/restricted.ts

@@ -0,0 +1,69 @@
+import {
+  type Audience,
+  type Finding,
+  type HandleUse,
+  type Viewer,
+  effectiveViewer,
+  isBroadcast,
+  mayView,
+} from "@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".
+ */
+export const restrictedFinding = (): Finding => ({
+  code: "restricted",
+  severity: "error",
+  message: "this data is restricted for the current viewer",
+});
+
+/** The advisory for classified handles with no viewer supplied (they are all refused). */
+export const viewerNotSuppliedFinding = (): Finding => ({
+  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)",
+});
+
+/** Split an inventory into the handles a viewer may load and the ones it may not. */
+export function partitionByViewer(
+  uses: readonly HandleUse[],
+  viewer: Viewer | undefined
+): { allowed: HandleUse[]; restricted: HandleUse[]; advisory: Finding[] } {
+  const allowed: HandleUse[] = [];
+  const restricted: HandleUse[] = [];
+  for (const use of uses) (mayView(viewer, use.sensitivity) ? allowed : restricted).push(use);
+  const classified = uses.some((u) => u.sensitivity !== undefined);
+  return {
+    allowed,
+    restricted,
+    advisory: classified && viewer === undefined ? [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.
+ */
+export function snapshotViewer(
+  viewer: Viewer | undefined,
+  audience?: Audience
+): Viewer | undefined {
+  if (isBroadcast(audience)) return effectiveViewer(undefined, audience);
+  if (viewer === undefined) return undefined;
+  try {
+    const clearance = viewer.clearance;
+    return clearance === undefined ? {} : { clearance };
+  } catch {
+    return {};
+  }
+}

package/src/scheduler.ts

@@ -0,0 +1,284 @@
+import type { Finding, Priority } from "@loomwork/ui-core";
+import type { HydrationStore } from "./projection";
+
+// ── Handle scheduling, independent of WHERE a handle is loaded ────────────────
+// What both controllers share: each handle loaded once per QUESTION (a job's fingerprint), at its
+// priority — P0 now, P1 collected in a batching window, P2 held until the surface says the widget
+// is visible — superseded loads aborted and their late results dropped, and nothing ever leaking
+// a rejection (`start` publishes its own failures as an `error` status). HOW a job loads is the
+// owner's `run`: in-process through `executeProvider`, or across a trust boundary through a
+// `HandleLoader`. Jobs started together share one GROUP (the in-process controller's pass, which
+// fixes the clock and memoizes identical steps across the handles in it). Clock and timers are
+// injected: scheduling is a pure function of the calls made.
+//
+// A re-queued P2 (its question changed, or it was invalidated) goes back to waiting for the
+// surface's NEXT `markVisible`: invalidating must not fetch data for something off-screen, so a
+// surface re-reports visibility for widgets it still shows.
+
+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 const defaultTimer: TimerFn = (fn, ms) => {
+  const t = setTimeout(fn, ms);
+  return () => clearTimeout(t);
+};
+
+/** NUL: cannot occur in a handle or a hash, so joined fingerprints never collide. */
+export const KEY_SEP = String.fromCharCode(0);
+
+export const disposedFinding = (what: string): Finding => ({
+  code: "disposed",
+  severity: "error",
+  message: `the hydration controller is disposed; ${what} does nothing`,
+});
+
+export const tooDeep = (experienceId: string, max: number): Finding => ({
+  code: "tree-too-deep",
+  severity: "error",
+  message: `experience "${experienceId}" exceeds MAX_TREE_DEPTH (${max})`,
+});
+
+export class HandleScheduler<J extends ScheduledJob, G, R extends HandleLoadResult> {
+  private readonly inflight = new Map<string, AbortController>();
+  /**
+   * 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 = new Map<string, J>();
+  private cancelBatch: (() => void) | undefined;
+  private readonly lazy = new Map<string, J>();
+  /** handle → fingerprint of the job it was last STARTED with. Pruned with the handle. */
+  private readonly loaded = new Map<string, string>();
+  private disposed = false;
+
+  constructor(
+    private readonly store: HydrationStore,
+    private readonly hooks: SchedulerHooks<J, G, R>,
+    private readonly setTimer: TimerFn = defaultTimer,
+    private readonly batchWindowMs = 50
+  ) {}
+
+  get isDisposed(): boolean {
+    return this.disposed;
+  }
+
+  /** Schedule by priority; a job whose question is already answered (or being answered) is skipped. */
+  schedule(jobs: readonly J[]): void {
+    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: ReadonlySet<string>): void {
+    const drop = new Set<string>();
+    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: readonly J[]): void {
+    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: string): void {
+    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(): string[] {
+    return [...this.inflight.keys()].sort();
+  }
+
+  /** Terminal: every in-flight or queued load ends on an error status, and nothing schedules again. */
+  dispose(): void {
+    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. */
+  private lazyGroup(): () => G {
+    let made: { readonly group: G } | undefined;
+    return () => {
+      if (made === undefined) made = { group: this.hooks.newGroup() };
+      return made.group;
+    };
+  }
+
+  private scheduleOne(job: J, group: () => G): void {
+    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);
+  }
+
+  private async start(job: J, group: G): Promise<void> {
+    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.
+      }
+    }
+  }
+}

package/src/select.ts

@@ -0,0 +1,59 @@
+import type { Finding } from "@loomwork/ui-core";
+import { resolvePath } from "./plan";
+
+// Pure reshaping pieces (no sandbox, no MCP): `@loomwork/ui-hydration/client` exports them so a planner
+// can dry-run a JSONPath binding without the server plane. `reshape.ts` re-exports them.
+
+/**
+ * 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 function jsonPathSelect(value: unknown, path: string): ReshapeResult {
+  if (path === "" || path === "$") return { ok: true, value };
+  const out = resolvePath(value, path);
+  if (out === undefined)
+    return {
+      ok: false,
+      failureKind: "selects-nothing",
+      finding: {
+        code: "reshape-failed",
+        severity: "error",
+        message: `JSONPath "${path}" selects nothing from the tool output`,
+      },
+    };
+  return { ok: true, value: out };
+}