@loomwork/ui-hydration 0.0.0-stage → 0.1.0

package/src/dataProvider.ts

@@ -0,0 +1,141 @@
+import { TypedFailure } from "@loomwork/core";
+import type { TransientInvokeOptions } from "@loomwork/effect-runtime";
+import { MCP_INVOKE_TOOL_ID } from "@loomwork/plugin-mcp";
+import { DEFAULT_STEP_KIND, STEP_KIND_PATTERN } from "@loomwork/ui-core";
+import type { TransientInvoker } from "./invoker";
+
+// ── The data plane: a step's KIND names the DataProvider that runs it (U3) ───────
+// A provider's graph steps used to be MCP tool calls and nothing else, so a loom app whose data
+// lives in a loom tool, a read model or an A2A peer had to wrap it as an MCP server to bind a
+// widget. A step now names a KIND (`step.kind`, absent = MCP); hydration looks the kind up in a
+// `DataProviderRegistry` the HOST builds at composition time — there is no runtime plugin system,
+// no discovery, no registering after the first load. MCP is the first registered kind and the
+// default, and behaves byte-for-byte as before.
+//
+// What a kind supplies (`DataProvider.invoke`) is ONE call: run `target` with `args`, THROUGH the
+// transient invoker hydration was given — which is what keeps the read path log-free and keeps
+// the invoker's own authorisation, budget and per-principal identity (`opts.principal`) in force.
+// A kind never gets a handle on the runtime, only the invoker. Everything else — waves, templates,
+// params, reshaping, output checks, caching, finding vocabulary — is the kind-independent part and
+// stays in `executeProvider`.
+//
+// THE PIN IS THE CONTRACT. Every step carries `toolSchemaHash` (required, non-empty): the kind's
+// fingerprint of the target's input contract, taken when the step was authored. `invoke` MUST
+// compare it with the target's current pin and, on a mismatch, throw
+// `TypedFailure("schemaDrift", { observedHash })` BEFORE running the target. That is what makes
+// drift detectable, repairable (`remapOperation` re-pins from `observedHash`) and what lets
+// `inputDrift: "report-and-proceed"` retry once with the observed pin. A kind that cannot say what
+// its target's contract currently is must not be registered: there is no "unpinned" kind. (MCP
+// delegates the comparison to `mcp.invoke`, which verifies it per call; `loomEffectProvider` keeps
+// the pins in a host-declared table.) `checkDataProviderConformance` asserts exactly this.
+
+/** One call a kind is asked to make. */
+export interface DataProviderCall {
+  readonly stepId: string;
+  /** The step's `toolName`: the target's id WITHIN this kind. */
+  readonly target: string;
+  /** The step's arguments, after params, time tokens, templates and the host's hook. */
+  readonly args: Record<string, unknown>;
+  /** The step's `toolSchemaHash`, or the observed pin on the one drift retry. */
+  readonly expectedPin: string;
+}
+
+export interface DataProvider {
+  /** The kind id steps name. Lower-case/digits/`-`; never `"mcp"` unless it IS the MCP provider. */
+  readonly kind: string;
+  /**
+   * Run the call and return the raw output. Contract: throw `TypedFailure("schemaDrift",
+   * { observedHash })` when `expectedPin` is not the target's current pin, before running it; any
+   * other `TypedFailure` becomes a `tool-<channel>` finding, anything else `tool-failed`. All
+   * calls MUST go through `invoker` with `opts` (it carries the signal and the principal).
+   */
+  invoke(
+    call: DataProviderCall,
+    invoker: TransientInvoker,
+    opts: TransientInvokeOptions
+  ): Promise<unknown>;
+}
+
+/** The kinds a host composed, by id. Immutable once built. */
+export interface DataProviderRegistry {
+  has(kind: string): boolean;
+  get(kind: string): DataProvider | undefined;
+  /** Registered kind ids, sorted. */
+  kinds(): readonly string[];
+}
+
+/**
+ * Build a registry. Refuses a malformed or duplicate kind id: two providers for one kind would
+ * make what a stored experience means depend on registration order.
+ */
+export function defineDataProviders(providers: readonly DataProvider[]): DataProviderRegistry {
+  const byKind = new Map<string, DataProvider>();
+  for (const p of providers) {
+    if (typeof p.kind !== "string" || !STEP_KIND_PATTERN.test(p.kind))
+      throw new TypeError(`defineDataProviders: "${String(p.kind)}" is not a valid kind id`);
+    if (byKind.has(p.kind))
+      throw new TypeError(`defineDataProviders: kind "${p.kind}" is registered twice`);
+    byKind.set(p.kind, p);
+  }
+  const sorted = Object.freeze([...byKind.keys()].sort());
+  return {
+    has: (kind) => byKind.has(kind),
+    get: (kind) => byKind.get(kind),
+    kinds: () => sorted,
+  };
+}
+
+/** The MCP kind: `mcp.invoke` with the pin as `expectedSchemaHash` (the plugin verifies it per call). */
+export const mcpProvider: DataProvider = Object.freeze<DataProvider>({
+  kind: DEFAULT_STEP_KIND,
+  invoke: (call, invoker, opts) =>
+    invoker.invokeTransient(
+      MCP_INVOKE_TOOL_ID,
+      { toolName: call.target, args: call.args, expectedSchemaHash: call.expectedPin },
+      opts
+    ),
+});
+
+/** What `executeProvider` uses when the host registers nothing: MCP only — the behaviour before kinds. */
+export const DEFAULT_DATA_PROVIDERS: DataProviderRegistry = defineDataProviders([mcpProvider]);
+
+/**
+ * Assert the one rule every kind must keep: a wrong pin is `schemaDrift` carrying the observed
+ * pin, and the right pin runs the target. Run it in a kind's own test suite against a target the
+ * kind serves (`target`, with its current `pin`) and a recording invoker. Returns a list of
+ * violations (empty = conformant); never throws for a violation. A wrong pin must ALSO not reach
+ * the target (a direct call to `target` through the invoker is counted). This is a TEST HELPER: `defineDataProviders`
+ * cannot enforce the rule at registration, so a kind that skips this suite is unchecked.
+ */
+export async function checkDataProviderConformance(
+  provider: DataProvider,
+  fixture: { target: string; pin: string; invoker: TransientInvoker }
+): Promise<string[]> {
+  const problems: string[] = [];
+  let reached = 0;
+  const counting: TransientInvoker = {
+    invokeTransient: (...a) => {
+      // Only a call to the target's OWN id counts: the MCP kind reaches `mcp.invoke`, whose pin
+      // check lives inside that effect (and is MCP's own conformance, not this kit's).
+      if (a[0] === fixture.target) reached++;
+      return fixture.invoker.invokeTransient(...a);
+    },
+  };
+  const base = { stepId: "conformance", target: fixture.target, args: {} };
+  try {
+    await provider.invoke({ ...base, expectedPin: `${fixture.pin}-stale` }, counting, {});
+    problems.push("a stale pin did not fail");
+  } catch (e) {
+    if (!(e instanceof TypedFailure && e.channel === "schemaDrift"))
+      problems.push("a stale pin failed, but not as TypedFailure(schemaDrift)");
+    else if ((e.payload as { observedHash?: string } | undefined)?.observedHash !== fixture.pin)
+      problems.push("schemaDrift did not carry the target's current pin as observedHash");
+  }
+  if (reached > 0) problems.push("a stale pin reached the target before failing");
+  try {
+    await provider.invoke({ ...base, expectedPin: fixture.pin }, fixture.invoker, {});
+  } catch (e) {
+    problems.push(`the current pin did not run the target: ${e instanceof Error ? e.message : e}`);
+  }
+  return problems;
+}

package/src/index.ts

@@ -0,0 +1,86 @@
+export {
+  HYDRATION_PROJECTION_ID,
+  HYDRATION_PROJECTION_VERSION,
+  HYDRATION_SET_EVENT,
+  HydrationAudienceMismatchError,
+  HydrationScopeError,
+  HydrationStore,
+  hydrationProjection,
+  isReservedHandle,
+} from "./projection";
+export type {
+  HandleSlice,
+  HandleState,
+  HandleStatus,
+  HydrationScope,
+  HydrationState,
+} from "./projection";
+export type { TransientInvoker } from "./invoker";
+export { limitInvoker, memoInvoker, signalInvoker } from "./invokers";
+export { defineReshapers, jsonPathSelect, outputShapeHashOf } from "./reshape";
+export type { ReshapeFailureKind, ReshapeResult, Reshaper, ReshaperRegistry } from "./reshape";
+export { DEFAULT_TIME_RANGE, checkParams } from "./params";
+export { ContentRefConfigError } from "./contentRefs";
+export type { ContentRefParamGate } from "./contentRefs";
+export type {
+  ArgumentHook,
+  ArgumentHookContext,
+  LoadParams,
+} from "./params";
+export {
+  DEFAULT_DATA_PROVIDERS,
+  checkDataProviderConformance,
+  defineDataProviders,
+  mcpProvider,
+} from "./dataProvider";
+export type { DataProvider, DataProviderCall, DataProviderRegistry } from "./dataProvider";
+export {
+  LOOM_EFFECT_KIND,
+  TARGET_FAILED,
+  TARGET_UNREGISTERED,
+  effectPin,
+  loomEffectProvider,
+} from "./loomEffectProvider";
+export type {
+  EffectEntry,
+  EffectInputSchema,
+  LoomEffectProviderOptions,
+} from "./loomEffectProvider";
+export { executeProvider } from "./provider";
+export { stepReferences, terminalSteps, topoWaves } from "./plan";
+export type { DriftRecord, ExecuteOptions, InputDriftMode, ProviderOutcome } from "./provider";
+export { DEFAULT_CACHE_MAX_ENTRIES, HydrationCache } from "./cache";
+export type { CacheVariant, HydrationCacheOptions } from "./cache";
+export type { HandleLoadResult } from "./scheduler";
+export { HydrationController } from "./controller";
+export type { ControllerOptions, DriftReport } from "./controller";
+export {
+  DEFAULT_MAX_BATCH,
+  DEFAULT_MAX_CONCURRENT_CALLS,
+  SplitHydrationController,
+  createServeSurface,
+  handleInventory,
+  publicFinding,
+  serveHandle,
+  serveHandles,
+} from "./split/index";
+export type {
+  HandleInventory,
+  HandleLoadRequest,
+  HandleLoader,
+  HandleRef,
+  InventoryOptions,
+  RevisionFn,
+  ServeOptions,
+  ServeSurface,
+  SplitControllerOptions,
+} from "./split/index";
+export { SCHEMA_REPAIRED, remapOperation } from "./repair";
+export type { SchemaRepairedPayload } from "./repair";
+export { connectConversation, publishChat } from "./chatSource";
+export type {
+  ConversationConnection,
+  ConversationConnectionOptions,
+  EventSourceLike,
+  FetchResponseLike,
+} from "./chatSource";

package/src/invoker.ts

@@ -0,0 +1,14 @@
+import type { TransientInvokeOptions } from "@loomwork/effect-runtime";
+
+/**
+ * The one thing hydration needs from loom's runtime: a one-shot, non-durable effect call.
+ * `EffectRuntime` satisfies this structurally (ADR 0066 `invokeTransient`); tests use a fake.
+ * Keeping it an interface is what makes the read path provably log-free — there is no `ctx`.
+ */
+export interface TransientInvoker {
+  invokeTransient<TIn = unknown, TOut = unknown>(
+    toolId: string,
+    input: TIn,
+    opts?: TransientInvokeOptions
+  ): Promise<TOut>;
+}

package/src/invokers.ts

@@ -0,0 +1,348 @@
+import { canonicalJson } from "@loomwork/core";
+import type { TransientInvokeOptions } from "@loomwork/effect-runtime";
+import { MCP_INVOKE_TOOL_ID } from "@loomwork/plugin-mcp";
+import type { TransientInvoker } from "./invoker";
+
+// ── Invoker wrappers: a call cap, an owner's lifetime signal, an in-pass step memo ─
+// All are TransientInvokers wrapping a TransientInvoker, so they compose with each other and
+// with loom's EffectRuntime without either knowing the other exists. The in-process controller
+// builds ONE `limitInvoker` (the cap is controller-wide: it bounds every call it makes), ONE
+// `signalInvoker` over it bound to its own lifetime (so `dispose` cancels every upstream call at
+// once), and one `memoInvoker` PER PASS in front of both (a memo hit takes no slot). The split
+// server (`serveHandles`, split.ts) composes a memo over a cap the same way, once per batch.
+// None ever returns a promise it did not get from the inner invoker except to wait for a slot,
+// so they add no settle latency on a free slot.
+
+/**
+ * The rejection for a call abandoned because its signal aborted. Named `AbortError` (the
+ * platform's own name for a cancelled operation) so a consumer classifies it by `name` — a
+ * planner's decider must propagate a cancellation, never retry it or record it as a failed
+ * plan. A plain `Error("aborted")` is indistinguishable from a provider failure. Message kept.
+ */
+function abortError(): Error {
+  const e = new Error("aborted");
+  e.name = "AbortError";
+  return e;
+}
+
+/**
+ * At most `max` calls in flight through this invoker, across every caller. A queued call whose
+ * signal aborts leaves the queue and rejects `"aborted"` without ever reaching `inner`. FIFO: a
+ * finished call hands its slot straight to the oldest waiter.
+ */
+export function limitInvoker(inner: TransientInvoker, max: number): TransientInvoker {
+  if (!Number.isInteger(max) || max < 1)
+    throw new RangeError(`limitInvoker: the cap must be a positive integer, got ${String(max)}`);
+  let active = 0;
+  // Insertion-ordered: the first entry is the oldest waiter; add/delete are O(1).
+  const waiting = new Set<() => void>();
+  const release = (): void => {
+    const next = waiting.values().next();
+    if (next.done === true) {
+      active -= 1;
+      return;
+    }
+    waiting.delete(next.value);
+    next.value(); // the slot passes to the waiter: `active` is unchanged
+  };
+  const acquire = (signal: AbortSignal | undefined): Promise<void> | undefined => {
+    // Checked before capacity: an already-aborted caller must never take a slot (or reach
+    // `inner`) just because one happened to be free — that slot belongs to the next live caller.
+    if (signal?.aborted === true) return Promise.reject(abortError());
+    if (active < max) {
+      active += 1;
+      return undefined;
+    }
+    return new Promise<void>((resolve, reject) => {
+      const onAbort = (): void => {
+        waiting.delete(grant);
+        reject(abortError());
+      };
+      const grant = (): void => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+      };
+      waiting.add(grant);
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  };
+  const run = <TOut>(call: () => Promise<TOut>): Promise<TOut> => {
+    let p: Promise<TOut>;
+    try {
+      p = call();
+    } catch (e) {
+      release();
+      return Promise.reject(e);
+    }
+    p.then(release, release);
+    return p;
+  };
+  return {
+    invokeTransient<TIn = unknown, TOut = unknown>(
+      toolId: string,
+      input: TIn,
+      opts?: TransientInvokeOptions
+    ): Promise<TOut> {
+      const call = (): Promise<TOut> => inner.invokeTransient<TIn, TOut>(toolId, input, opts);
+      const slot = acquire(opts?.signal);
+      return slot === undefined ? run(call) : slot.then(() => run(call));
+    },
+  };
+}
+
+/** `call()`, with a synchronous throw turned into the rejected promise the contract promises. */
+function callSafely<T>(call: () => Promise<T>): Promise<T> {
+  try {
+    return call();
+  } catch (e) {
+    return Promise.reject(e);
+  }
+}
+
+/**
+ * Every call through this invoker is ALSO cancelled, synchronously, when `signal` aborts — the
+ * owner's lifetime (a controller's `dispose`), independent of any caller's own signal, which still
+ * reaches `inner` too. Once `signal` has aborted, new calls reject `"aborted"` without reaching
+ * `inner`. Leak-free on a long-lived `signal`: a call holds its listener only until it settles.
+ */
+export function signalInvoker(inner: TransientInvoker, signal: AbortSignal): TransientInvoker {
+  return {
+    invokeTransient<TIn = unknown, TOut = unknown>(
+      toolId: string,
+      input: TIn,
+      opts?: TransientInvokeOptions
+    ): Promise<TOut> {
+      const own = opts?.signal;
+      if (signal.aborted || own?.aborted === true) return Promise.reject(abortError());
+      const ac = new AbortController();
+      const abort = (): void => ac.abort();
+      signal.addEventListener("abort", abort, { once: true });
+      own?.addEventListener("abort", abort, { once: true });
+      const release = (): void => {
+        signal.removeEventListener("abort", abort);
+        own?.removeEventListener("abort", abort);
+      };
+      const p = callSafely(() =>
+        inner.invokeTransient<TIn, TOut>(toolId, input, { ...opts, signal: ac.signal })
+      );
+      p.then(release, release);
+      return p;
+    },
+  };
+}
+
+interface SharedCall {
+  readonly promise: Promise<unknown>;
+  /** Cancels the ONE upstream call `inner` is actually making — aborted only once every live
+   * caller below has aborted; never by any single caller's own signal. */
+  readonly controller: AbortController;
+  /**
+   * How many callers (leader included) have not yet aborted. Never decremented on a normal
+   * settle — once the shared call settles, `live` stops mattering: a settled entry (see
+   * `settled` below) is kept for the rest of the pass no matter what `live` says. This field
+   * exists solely to answer one question — has the LAST live caller just aborted? — which is
+   * the only time the still-in-flight upstream call should be cancelled.
+   */
+  live: number;
+  /**
+   * Set once, from a handler attached at entry-creation time (so it runs before any caller
+   * added later), the instant `promise` settles — success or failure alike. Guards
+   * `onCallerAbort`: an abort landing after the upstream has already settled, but before that
+   * settlement handler has actually RUN (a real race — `resolve()`/`reject()` marks a promise
+   * settled synchronously, while every `.then` callback, this one included, only runs on a later
+   * microtask), must never cancel or evict a call whose result already exists.
+   */
+  settled: boolean;
+}
+
+/**
+ * The shape `canonicalJson` actually understands — null/string/finite-number/boolean, and arrays
+ * or plain objects (`Object.prototype` or `null` as the prototype) built from those, recursively.
+ * `canonicalJson` does not THROW on a `Date`, `Map`, `Set` or a class instance — it silently reads
+ * `Object.keys()` on it, which for most of those is `[]`, so two calls with DIFFERENT such
+ * arguments would canonicalize to the same `"{}"` and collide on one memo key. Reject those before
+ * a key is ever computed, not after: `memoInvoker` must never be the reason a value collapses.
+ *
+ * `seen` makes this cycle-safe: a hostile or accidental circular reference is walked at most once
+ * per object (the second visit reports "not plain" rather than recursing forever), so a cyclic
+ * argument bypasses the memo instead of throwing `RangeError: Maximum call stack size exceeded`
+ * out of `invokeTransient`. Sharing one `seen` set across a whole call's plainness check is
+ * deliberately conservative: a repeated (non-cyclic) reference is also flagged "not plain" and
+ * bypasses sharing rather than being memoized — safe, since bypass just means no caching, never a
+ * wrong answer.
+ */
+function isPlainJsonValue(value: unknown, seen: WeakSet<object> = new WeakSet()): boolean {
+  if (value === null || value === undefined) return true;
+  const t = typeof value;
+  if (t === "string" || t === "boolean") return true;
+  if (t === "number") return Number.isFinite(value as number);
+  if (t !== "object") return false; // function, bigint, symbol
+  const obj = value as object;
+  if (seen.has(obj)) return false;
+  seen.add(obj);
+  if (Array.isArray(value)) return value.every((v) => isPlainJsonValue(v, seen));
+  const proto = Object.getPrototypeOf(obj);
+  if (proto !== Object.prototype && proto !== null) return false;
+  return Object.values(value as Record<string, unknown>).every((v) => isPlainJsonValue(v, seen));
+}
+
+/**
+ * One call per identical MCP step for this invoker's lifetime (a PASS): same tool, same resolved
+ * arguments, same schema pin, same call options — the canonical JSON of `[principal, every other
+ * option except signal, mcp.invoke's input]`, so key order does not matter. A joiner is
+ * served straight from the shared promise — it never calls `inner` itself, so it never passes
+ * through whatever per-call authorizer `inner` enforces. That is safe ONLY because every
+ * authorization input is part of the key: the principal, and also the stamped execution identity
+ * (`as` — an authorizer may grant by workflow), the `label` (which names the transient
+ * execution when `as` is absent) and anything else in the options. Every joiner
+ * sharing one entry was, by construction, asking with the exact inputs the leader's own (sole)
+ * call to `inner` was authorized for; an option that is not plain JSON passes through, uncached. Settled results stay (a step in a later wave is still
+ * served) and failures are shared. Other effects (a sandbox reshape) always run, uncached.
+ *
+ * Cancellation is ref-counted, not leader-owned: `inner` is called once, through an internal
+ * `AbortController` this function owns — never a caller's own signal directly — so any ONE
+ * caller's abort only ever settles that caller's OWN returned promise (a race against the shared
+ * promise). The upstream call itself is cancelled, and the entry forgotten, only once every live
+ * caller has aborted AND the call had not already settled; a caller that arrives after a real
+ * cancellation finds no entry and starts a fresh call.
+ */
+export function memoInvoker(inner: TransientInvoker): TransientInvoker {
+  const memo = new Map<string, SharedCall>();
+
+  const onCallerAbort = (key: string, hit: SharedCall): void => {
+    hit.live -= 1;
+    if (hit.live > 0) return;
+    // Deferred one microtask: `hit.settled` is set by a handler attached at entry-creation time,
+    // which — because it was attached first — runs before this check for any settlement the memo
+    // can observe, even when the abort lands in the very same synchronous turn as `hit.promise`
+    // settling. Checking `hit.settled` synchronously right here would miss exactly that race.
+    // "The memo can observe" is `hit.promise` — `inner`'s promise — not the raw upstream: behind
+    // a queued `limitInvoker` (or any wrapper that settles a few hops after its own inner call),
+    // an all-abort landing after the RAW upstream settled but before `hit.promise` does still
+    // cancels and evicts, so a later caller re-fetches. A wasted call, never a wrong answer.
+    //
+    // Both conditions below are RE-READ at that later point, not captured now, because either can
+    // change in the gap between "live just dropped to 0" and "the microtask actually runs": a
+    // fresh caller with no signal of its own can join in the very same synchronous turn (bumping
+    // `live` back above 0 before this ever executes), and the upstream can settle in that same
+    // window (flipping `settled` true). A snapshot taken at decrement time would race both ways —
+    // this is why the check happens here, once, right before the one place that acts on it.
+    //
+    // Invariant: the controller is aborted, and the entry deleted, AT MOST ONCE per entry — and
+    // only when, at the moment this specific check runs, `settled` is still false AND `live` is
+    // still <= 0 (no one re-joined). Either condition failing means someone still needs this call
+    // to keep going (or already has its answer), so it is left alone.
+    queueMicrotask(() => {
+      if (hit.settled || hit.live > 0) return;
+      // Forget the entry BEFORE aborting: `abort()` runs `inner`'s listeners synchronously, and a
+      // caller re-entering with the same key from one of them must start a fresh call, not join
+      // this dying one.
+      if (memo.get(key) === hit) memo.delete(key);
+      hit.controller.abort();
+    });
+  };
+
+  const join = <TOut>(
+    key: string,
+    hit: SharedCall,
+    signal: AbortSignal | undefined
+  ): Promise<TOut> => {
+    if (signal?.aborted === true) {
+      onCallerAbort(key, hit);
+      return Promise.reject(abortError());
+    }
+    return new Promise<TOut>((resolve, reject) => {
+      let settled = false;
+      const onAbort = (): void => {
+        if (settled) return;
+        settled = true;
+        onCallerAbort(key, hit);
+        reject(abortError());
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      hit.promise.then(
+        (v) => {
+          if (settled) return;
+          settled = true;
+          signal?.removeEventListener("abort", onAbort);
+          resolve(v as TOut);
+        },
+        (e: unknown) => {
+          if (settled) return;
+          settled = true;
+          signal?.removeEventListener("abort", onAbort);
+          reject(e);
+        }
+      );
+    });
+  };
+
+  return {
+    invokeTransient<TIn = unknown, TOut = unknown>(
+      toolId: string,
+      input: TIn,
+      opts?: TransientInvokeOptions
+    ): Promise<TOut> {
+      // Every pass-through is guarded like the leader's call: a synchronous throw from `inner`
+      // must come back as a rejected promise, never escape `invokeTransient`.
+      const passThrough = (): Promise<TOut> =>
+        callSafely(() => inner.invokeTransient<TIn, TOut>(toolId, input, opts));
+      if (toolId !== MCP_INVOKE_TOOL_ID) return passThrough();
+      // Everything in `opts` except the one field that cannot change the answer (`signal`) is
+      // part of the key: the principal, the stamped identity (`as`, which an authorizer may key
+      // grants on), the `label` (without `as`, the transient executionId is `transient:<label>`,
+      // and an authorizer may grant per execution), the budget snapshot, and any option added
+      // later. Keying on the remainder rather than a list of known fields is what keeps a joiner
+      // from being served a result authorized for a different input this function has never
+      // heard of.
+      const { signal: _signal, principal = null, ...rest } = opts ?? {};
+      let key: string;
+      try {
+        const seen = new WeakSet<object>();
+        if (
+          !isPlainJsonValue(principal, seen) ||
+          !isPlainJsonValue(rest, seen) ||
+          !isPlainJsonValue(input, seen)
+        )
+          return passThrough();
+        key = canonicalJson([principal, rest, input]);
+      } catch {
+        return passThrough();
+      }
+      const hit = memo.get(key);
+      if (hit !== undefined) {
+        hit.live += 1;
+        return join<TOut>(key, hit, opts?.signal);
+      }
+      // Mirrors limitInvoker's fast path: an already-aborted caller must never become the leader
+      // — that would call `inner`, create an entry nobody asked to keep, and (since nothing here
+      // would yet be subscribed to the resulting promise) risk an unhandled rejection.
+      if (opts?.signal?.aborted === true) return Promise.reject(abortError());
+      const controller = new AbortController();
+      let promise: Promise<TOut>;
+      try {
+        // `inner.invokeTransient` is typed to return a Promise, but a misbehaving implementation
+        // can still throw synchronously; the interface contract (and every caller of THIS
+        // function) requires a rejected promise instead, never a thrown exception. No entry is
+        // created for a call that never actually started.
+        promise = inner.invokeTransient<TIn, TOut>(toolId, input, {
+          ...opts,
+          signal: controller.signal,
+        });
+      } catch (e) {
+        return Promise.reject(e);
+      }
+      const entry: SharedCall = { promise, controller, live: 1, settled: false };
+      const onSettle = (): void => {
+        entry.settled = true;
+      };
+      // Attached at entry-creation time — before any joiner's own `.then` — so `entry.settled`
+      // is set before `onCallerAbort`'s deferred check can run (see there). Also the
+      // backstop: attaching a rejection handler here means NO path can ever leave `promise`
+      // unhandled, even if a future caller subscribes late or never at all.
+      promise.then(onSettle, onSettle);
+      memo.set(key, entry);
+      return join<TOut>(key, entry, opts?.signal);
+    },
+  };
+}