@loomwork/ui-hydration 0.0.0-stage → 0.1.0

package/dist/split/server.d.ts

@@ -0,0 +1,160 @@
+import { type Audience, type ContentRefTable, type DeclaredToolClasses, type Experience, type Finding, type ReadPolicy, type SemanticCatalog, type Surface, type UndeclaredToolPolicy, type Viewer } from "@loomwork/ui-core";
+import { type HydrationCache } from "../cache";
+import type { DriftReport } from "../controller";
+import { type ExecuteOptions } from "../provider";
+import { type HandleLoadResult } from "../scheduler";
+import type { HandleInventory, HandleLoadRequest } from "./client";
+/**
+ * Derives a handle's public revision from the provider's content fingerprint (`specFingerprint`).
+ * It must be KEYED: an unkeyed function of the fingerprint lets a client confirm a guessed provider
+ * (tool, arguments) offline. In production use an HMAC over a server secret, e.g.
+ * `createHmac("sha256", secret).update(handle + "\u0000" + fingerprint).digest("hex")`. It must be
+ * deterministic for as long as clients hold inventories (a rotated key re-asks every handle once),
+ * and it must move with the fingerprint: a per-handle constant cannot be detected here, and it
+ * defeats re-asking — a client never learns that the provider behind a handle changed.
+ */
+export type RevisionFn = (handle: string, fingerprint: string) => string;
+export interface InventoryOptions {
+    readonly revisionOf: RevisionFn;
+    /**
+     * Who the inventory is for. A handle classified above the viewer's clearance is OMITTED — not
+     * listed with a placeholder, so the client learns neither its name nor its revision. FAIL-CLOSED:
+     * absent = no clearance (one `viewer-not-supplied` warn is returned if anything is classified).
+     * Pass the same viewer to `serveHandles`, which refuses such a handle even if a client names it.
+     */
+    readonly viewer?: Viewer;
+    /**
+     * Who the surface is for (`@loomwork/ui-core` `Audience`, the value `compile` took). `"broadcast"`
+     * lists only unclassified handles, whoever the `viewer` is. Pass the same to `serveHandles`.
+     */
+    readonly audience?: Audience;
+    /**
+     * The host's DECLARED class per tool (`toolKey`), a read-time floor under every handle calling
+     * that tool (`@loomwork/ui-core` `DeclaredToolClasses`): a handle whose stored nodes carry no class
+     * is still gated as strictly as its tool is declared. Absent = only the experience's own classes.
+     */
+    readonly declaredToolClasses?: DeclaredToolClasses;
+    /**
+     * What a tool the `declaredToolClasses` table does not list reads as: `"allow"` (default) = as the
+     * experience itself says; `"deny"` = no viewer may read it (only with a table present).
+     */
+    readonly undeclared?: UndeclaredToolPolicy;
+}
+/**
+ * What a client may know about an experience's data plane: never a provider. Throws `TypeError`
+ * without a `revisionOf`, or when it returns a non-string, an empty string or the fingerprint.
+ */
+export declare function handleInventory(exp: Experience, opts: InventoryOptions): {
+    inventory: HandleInventory;
+    findings: Finding[];
+};
+/** The most requests one `serveHandles` call serves by default (`ServeOptions.maxBatch`). */
+export declare const DEFAULT_MAX_BATCH = 256;
+/**
+ * The most transient calls one `serveHandles` batch has in flight by default
+ * (`ServeOptions.maxConcurrentCalls`): the batch is client-sized, so the server bounds its fan-out.
+ */
+export declare const DEFAULT_MAX_CONCURRENT_CALLS = 32;
+export interface ServeOptions extends Omit<ExecuteOptions, "params" | "kinds" | "contentRefArgs"> {
+    /**
+     * REQUIRED (U9b): the marked content-reference argument paths per tool, derived from the offered
+     * capabilities with the planner's `contentRefArgsFrom(capabilities)` (persist it with the capability
+     * set; `parseContentRefTable` re-reads it). `"none"` is the explicit opt-out: nothing is guarded,
+     * and serving a media-bound handle then reports `media-content-refs-unguarded` (warn).
+     */
+    readonly contentRefArgs: ContentRefTable | "none";
+    /** Kinds for `"contract"` providers: the nodes binding the handle, resolved on this surface. */
+    readonly outputKinds?: {
+        readonly catalog: SemanticCatalog;
+        readonly surface: Surface;
+    };
+    readonly cache?: HydrationCache;
+    /**
+     * Who the answers are for. A handle bound by any node classified above the viewer's clearance is
+     * refused BEFORE its provider is looked up, cached or invoked, and the client is told exactly
+     * what it is told for a handle the experience does not bind (`unknown-handle`) — no oracle for
+     * which handles exist but are restricted; the full `restricted` finding goes to `onFinding`.
+     * FAIL-CLOSED: absent = no clearance. Unclassified handles are unaffected.
+     */
+    readonly viewer?: Viewer;
+    /**
+     * Who the surface is for (the value `compile` took). `"broadcast"` refuses every classified
+     * handle exactly as `unknown-handle`, even a client naming one the requesting `viewer` may read.
+     */
+    readonly audience?: Audience;
+    /**
+     * The host's DECLARED class per tool (`toolKey`), a read-time floor under every handle calling
+     * that tool (`@loomwork/ui-core` `DeclaredToolClasses`): a handle whose stored nodes carry no class
+     * is still gated as strictly as its tool is declared. Absent = only the experience's own classes.
+     */
+    readonly declaredToolClasses?: DeclaredToolClasses;
+    /**
+     * What a tool the `declaredToolClasses` table does not list reads as: `"allow"` (default) = as the
+     * experience itself says; `"deny"` = no viewer may read it (only with a table present).
+     */
+    readonly undeclared?: UndeclaredToolPolicy;
+    /** Keys a `principal`-scoped cache entry; without it such a provider is never cached. */
+    readonly principalId?: string;
+    readonly onDrift?: (report: DriftReport) => void;
+    /**
+     * Every finding a load produced, IN FULL (tool, step, script, hashes, exception text), for the
+     * server's own logs. What the client receives is only its public form (`publicFinding`). A
+     * throw here, or a rejection of the promise it returns, is swallowed: a logging hook never
+     * changes what a client is answered.
+     */
+    readonly onFinding?: (handle: string, finding: Finding) => unknown;
+    /**
+     * At most this many transient calls in flight across the whole batch. Default
+     * `DEFAULT_MAX_CONCURRENT_CALLS` (32): a client decides how many handles a batch carries, so
+     * the server bounds the upstream fan-out unless it is told otherwise. It bounds ONE batch: for
+     * a server-wide bound, wrap the invoker once in the exported `limitInvoker` and share that
+     * wrapped invoker across every batch.
+     */
+    readonly maxConcurrentCalls?: number;
+    /**
+     * A batch longer than this is refused whole (`batch-too-large`). Default `DEFAULT_MAX_BATCH`.
+     * The refusal is still one result per request, so a transport should bound request bodies.
+     */
+    readonly maxBatch?: number;
+}
+/**
+ * The public form of a finding: `severity` kept; the code kept when it is one of the fixed codes
+ * or a loom-declared channel (otherwise the generic `tool-failed` / `reshape-failed` /
+ * `load-failed` / `load-warning`); the message a template keyed by that code, naming only the
+ * (client-supplied) handle — never a node, step, tool, script, hash, argument, channel or
+ * exception text.
+ */
+export declare function publicFinding(handle: string | undefined, finding: Finding): Finding;
+/**
+ * The server half of split hydration: answer a BATCH of handle loads for `exp` in one pass — one
+ * clock read (`opts.now`, else `Date.now()` once), one step memo in front of one call cap
+ * (`maxConcurrentCalls`, default 32), so identical steps across the batch's providers run once.
+ * The memo is keyed by principal too, and one call serves one principal (`opts.principal`), so
+ * two viewers never share a call. Every failure, a malformed request included, is a result, one per request
+ * in request order (a batch that is not a list gets one `invalid-request`) — and every finding a
+ * client receives is its PUBLIC form (`publicFinding`); the full one goes to `onFinding`. Rejects
+ * with `TypeError` only for a server misconfiguration (`maxBatch`, `maxConcurrentCalls`).
+ */
+export declare function serveHandles(exp: Experience, requests: readonly HandleLoadRequest[], opts: ServeOptions): Promise<HandleLoadResult[]>;
+/**
+ * Answer ONE handle load for `exp` — a batch of one (`serveHandles`). `opts.now` should be the
+ * server's clock: relative time is resolved here, never on the client.
+ */
+export declare function serveHandle(exp: Experience, request: HandleLoadRequest, opts: ServeOptions): Promise<HandleLoadResult>;
+/**
+ * `handleInventory`, `serveHandle` and `serveHandles` with the host's {@link ReadPolicy} bound
+ * ONCE. Every call applies it, so a host that wires the policy here cannot leak by forgetting it on
+ * one call (the inventory naming a handle the loader then refuses, or the reverse). A per-call
+ * `declaredToolClasses` / `undeclared` may only ADD to it (`mergeReadPolicy`): `{}` or `undefined`
+ * cannot lower what was bound. Prefer this to the free functions, which take the policy per call
+ * and are the low-level API.
+ */
+export interface ServeSurface {
+    /** The bound policy (a copy; read-only). */
+    readonly policy: ReadPolicy;
+    readonly handleInventory: (exp: Experience, opts: InventoryOptions) => ReturnType<typeof handleInventory>;
+    readonly serveHandles: (exp: Experience, requests: readonly HandleLoadRequest[], opts: ServeOptions) => Promise<HandleLoadResult[]>;
+    readonly serveHandle: (exp: Experience, request: HandleLoadRequest, opts: ServeOptions) => Promise<HandleLoadResult>;
+}
+export declare function createServeSurface(policy?: ReadPolicy): ServeSurface;
+//# sourceMappingURL=server.d.ts.map

package/dist/split/server.d.ts.map

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

package/dist/split/server.js

@@ -0,0 +1,496 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_CONCURRENT_CALLS = exports.DEFAULT_MAX_BATCH = void 0;
+exports.handleInventory = handleInventory;
+exports.publicFinding = publicFinding;
+exports.serveHandles = serveHandles;
+exports.serveHandle = serveHandle;
+exports.createServeSurface = createServeSurface;
+const plugin_mcp_1 = require("@loomwork/plugin-mcp");
+const plugin_sandbox_1 = require("@loomwork/plugin-sandbox");
+const ui_core_1 = require("@loomwork/ui-core");
+const cache_1 = require("../cache");
+const contentRefs_1 = require("../contentRefs");
+const invokers_1 = require("../invokers");
+const params_1 = require("../params");
+const projection_1 = require("../projection");
+const provider_1 = require("../provider");
+const restricted_1 = require("../restricted");
+const scheduler_1 = require("../scheduler");
+const shared_1 = require("./shared");
+/**
+ * What a client may know about an experience's data plane: never a provider. Throws `TypeError`
+ * without a `revisionOf`, or when it returns a non-string, an empty string or the fingerprint.
+ */
+function handleInventory(exp, opts) {
+    const revisionOf = opts?.revisionOf;
+    if (typeof revisionOf !== "function")
+        throw new TypeError("handleInventory: a revisionOf (a keyed hash) is required");
+    const findings = [];
+    const handles = [];
+    if ((0, ui_core_1.treeDepth)(exp.root) > ui_core_1.MAX_TREE_DEPTH) {
+        findings.push((0, scheduler_1.tooDeep)(exp.experienceId, ui_core_1.MAX_TREE_DEPTH));
+    }
+    else {
+        const split = (0, restricted_1.partitionByViewer)((0, ui_core_1.experienceHandles)(exp, opts.declaredToolClasses, opts.undeclared), (0, restricted_1.snapshotViewer)(opts.viewer, opts.audience));
+        findings.push(...split.advisory);
+        for (const use of split.allowed) {
+            if ((0, projection_1.isReservedHandle)(use.handle)) {
+                findings.push((0, shared_1.reservedFinding)(use.handle));
+                continue;
+            }
+            const spec = Object.hasOwn(exp.providers, use.handle) ? exp.providers[use.handle] : undefined;
+            if (spec === undefined) {
+                const f = {
+                    code: "unknown-handle",
+                    severity: "error",
+                    message: `nodes ${use.nodeIds.join(", ")} bind "${use.handle}", which has no provider`,
+                };
+                findings.push(f);
+                handles.push({
+                    handle: use.handle,
+                    priority: use.priority,
+                    params: [],
+                    revision: "",
+                    finding: f,
+                });
+                continue;
+            }
+            handles.push({
+                handle: use.handle,
+                priority: use.priority,
+                params: (0, params_1.providerParams)(spec),
+                revision: publicRevision(revisionOf, use.handle, spec),
+            });
+        }
+    }
+    return {
+        inventory: { experienceId: exp.experienceId, versionHash: exp.versionHash, handles },
+        findings,
+    };
+}
+function publicRevision(revisionOf, handle, spec) {
+    const fingerprint = (0, cache_1.specFingerprint)(spec);
+    const revision = revisionOf(handle, fingerprint);
+    if (typeof revision !== "string" || revision === "")
+        throw new TypeError(`handleInventory: revisionOf returned ${revision === "" ? "an empty string" : `a ${typeof revision}`} for "${handle}"`);
+    if (revision.includes(fingerprint))
+        throw new TypeError(`handleInventory: revisionOf returned the provider fingerprint for "${handle}"; it must be keyed`);
+    return revision;
+}
+/** The most requests one `serveHandles` call serves by default (`ServeOptions.maxBatch`). */
+exports.DEFAULT_MAX_BATCH = 256;
+/**
+ * The most transient calls one `serveHandles` batch has in flight by default
+ * (`ServeOptions.maxConcurrentCalls`): the batch is client-sized, so the server bounds its fan-out.
+ */
+exports.DEFAULT_MAX_CONCURRENT_CALLS = 32;
+/**
+ * The failure channels loom itself declares (ADR 0060) — `mcp.invoke`'s and the sandbox's, derived
+ * from loom's own exports so the list cannot drift. A `tool-<channel>` / `reshape-<channel>` code
+ * is built from whatever channel the (pluggable) invoker threw, which is arbitrary text; only
+ * these are served as they are.
+ */
+const TOOL_CHANNELS = new Set(Object.keys(plugin_mcp_1.MCP_INVOKE_ERRORS));
+const RESHAPE_CHANNELS = new Set(Object.keys(plugin_sandbox_1.SANDBOX_ERRORS));
+/**
+ * Every other code a served finding may carry: the fixed codes hydration and the server mint
+ * themselves. Anything else is replaced (`load-failed` / `load-warning`) — the code is a fixed
+ * vocabulary, never text a provider or an invoker chose.
+ */
+const FIXED_CODES = new Set([
+    "tool-failed",
+    "tool-targetUnregistered",
+    "provider-kind-unregistered",
+    "reshape-failed",
+    "reshape-unregistered",
+    "schema-drift",
+    "schema-drift-proceeded",
+    "output-shape-drift",
+    "output-shape-unhashable",
+    "output-shape-unpinned",
+    "output-contract-drift",
+    "output-contract-missing",
+    "output-contract-unbound",
+    "param-not-overridable",
+    "param-templated",
+    "param-template-refused",
+    "invalid-params",
+    "invalid-time-token",
+    "argument-hook-failed",
+    "unresolved-step-reference",
+    "upstream-empty",
+    "dependency-failed",
+    "provider-failed",
+    "content-ref-refused",
+    "empty-graph",
+    "graph-cycle",
+    "aborted",
+    "invalid-request",
+    "version-mismatch",
+    "invalid-handle",
+    "unknown-handle",
+    "batch-too-large",
+    "tree-too-deep",
+    "hydration-internal",
+]);
+function publicCode(finding) {
+    const { code } = finding;
+    if (FIXED_CODES.has(code))
+        return code;
+    if (code.startsWith("tool-"))
+        return TOOL_CHANNELS.has(code.slice(5)) ? code : "tool-failed";
+    if (code.startsWith("reshape-"))
+        return RESHAPE_CHANNELS.has(code.slice(8)) ? code : "reshape-failed";
+    return finding.severity === "warn" ? "load-warning" : "load-failed";
+}
+/**
+ * What a client may be told about a finding: a fixed text keyed by its PUBLIC code. The fixed
+ * codes' own cases run FIRST, so one of them that happens to share a `tool-`/`reshape-` prefix
+ * with an allow-listed channel code (`reshape-unregistered`, a hydration-minted code, not a
+ * channel) gets its own text instead of the generic prefix fallback below.
+ */
+function publicText(code, severity) {
+    switch (code) {
+        case "schema-drift-proceeded":
+            return "input schema changed; served with the observed schema";
+        case "schema-drift":
+            return "input schema changed; waiting for a repair";
+        case "output-shape-drift":
+        case "output-shape-unhashable":
+        case "output-contract-drift":
+            return "the output no longer matches what it declares; waiting for a repair";
+        case "output-shape-unpinned":
+            return "the output is served unchecked";
+        case "output-contract-missing":
+        case "output-contract-unbound":
+            return "the output cannot be checked";
+        case "provider-kind-unregistered":
+            return "no data provider is registered for this view's source";
+        case "tool-targetUnregistered":
+            return "this view's source is not available";
+        case "reshape-unregistered":
+            return "the output could not be reshaped: the named reshaper is not registered";
+        case "upstream-empty":
+            return "no data for this view";
+        case "param-not-overridable":
+            return "a param was ignored";
+        case "invalid-params":
+        case "invalid-time-token":
+            return "the params were refused";
+        case "content-ref-refused":
+            return "a content-reference argument was refused";
+        case "aborted":
+            return "the load was aborted";
+        case "invalid-request":
+            return "the request is malformed";
+        case "version-mismatch":
+            return "the request is for another version of the experience";
+        case "invalid-handle":
+            return "the handle is reserved";
+        case "unknown-handle":
+            return "not a handle this experience binds";
+        case "batch-too-large":
+            return "the batch is too large";
+        case "tree-too-deep":
+            return "the experience cannot be served";
+        case "hydration-internal":
+            return "an internal error occurred";
+    }
+    if (code.startsWith("tool-"))
+        return "a tool call failed";
+    if (code.startsWith("reshape-"))
+        return "the output could not be reshaped";
+    return severity === "warn" ? "loaded with a warning" : "could not be loaded";
+}
+/**
+ * The public form of a finding: `severity` kept; the code kept when it is one of the fixed codes
+ * or a loom-declared channel (otherwise the generic `tool-failed` / `reshape-failed` /
+ * `load-failed` / `load-warning`); the message a template keyed by that code, naming only the
+ * (client-supplied) handle — never a node, step, tool, script, hash, argument, channel or
+ * exception text.
+ */
+function publicFinding(handle, finding) {
+    const code = publicCode(finding);
+    const text = publicText(code, finding.severity);
+    return {
+        code,
+        severity: finding.severity,
+        message: handle === undefined ? text : `handle ${JSON.stringify(handle.slice(0, 128))}: ${text}`,
+    };
+}
+/** Hands each finding to `onFinding` once, in full; a throwing hook is swallowed. */
+function reporter(opts, handle) {
+    const seen = new Set();
+    const report = (finding) => {
+        if (seen.has(finding))
+            return;
+        seen.add(finding);
+        try {
+            const ret = opts.onFinding?.(handle, finding);
+            // An async hook's rejection is its own: never an unhandled rejection in the server.
+            if (ret !== null &&
+                typeof ret === "object" &&
+                typeof ret.then === "function")
+                Promise.resolve(ret).catch(() => { });
+        }
+        catch {
+            // A logging hook must never change what the client is answered (nor, if its `then`
+            // getter throws, what the server does).
+        }
+    };
+    return Object.assign(report, {
+        silence: (finding) => {
+            seen.add(finding);
+        },
+    });
+}
+/** Report the result's finding in full, and answer the client with its public form. */
+function publicResult(handle, result, report) {
+    if (result.finding === undefined)
+        return result;
+    report(result.finding);
+    const finding = publicFinding(handle, result.finding);
+    return result.state === "ready"
+        ? { state: "ready", value: result.value, finding }
+        : { state: result.state, finding };
+}
+/**
+ * The server half of split hydration: answer a BATCH of handle loads for `exp` in one pass — one
+ * clock read (`opts.now`, else `Date.now()` once), one step memo in front of one call cap
+ * (`maxConcurrentCalls`, default 32), so identical steps across the batch's providers run once.
+ * The memo is keyed by principal too, and one call serves one principal (`opts.principal`), so
+ * two viewers never share a call. Every failure, a malformed request included, is a result, one per request
+ * in request order (a batch that is not a list gets one `invalid-request`) — and every finding a
+ * client receives is its PUBLIC form (`publicFinding`); the full one goes to `onFinding`. Rejects
+ * with `TypeError` only for a server misconfiguration (`maxBatch`, `maxConcurrentCalls`).
+ */
+async function serveHandles(exp, requests, opts) {
+    // Server configuration, not client input: a bad bound is a programming error, and loud.
+    (0, contentRefs_1.assertContentRefConfig)(opts.contentRefArgs, "serveHandles");
+    const max = opts.maxBatch ?? exports.DEFAULT_MAX_BATCH;
+    if (!Number.isInteger(max) || max < 1)
+        throw new TypeError(`serveHandles: maxBatch must be a positive integer, got ${String(max)}`);
+    const cap = opts.maxConcurrentCalls ?? exports.DEFAULT_MAX_CONCURRENT_CALLS;
+    if (!Number.isInteger(cap) || cap < 1)
+        throw new TypeError(`serveHandles: maxConcurrentCalls must be a positive integer, got ${String(cap)}`);
+    const batch = reporter(opts, "");
+    if (!Array.isArray(requests))
+        return [
+            publicResult(undefined, (0, shared_1.refuse)("invalid-request", "a batch load is a list of load requests"), batch),
+        ];
+    if (requests.length > max) {
+        const tooMany = publicResult(undefined, (0, shared_1.refuse)("batch-too-large", `a batch of ${requests.length} requests exceeds the bound of ${max}`), batch);
+        return requests.map(() => tooMany);
+    }
+    // Checked before anything walks the tree for handles or kinds.
+    if ((0, ui_core_1.treeDepth)(exp.root) > ui_core_1.MAX_TREE_DEPTH) {
+        const deep = publicResult(undefined, { state: "error", finding: (0, scheduler_1.tooDeep)(exp.experienceId, ui_core_1.MAX_TREE_DEPTH) }, batch);
+        return requests.map(() => deep);
+    }
+    let pass;
+    try {
+        pass = openPass(exp, opts);
+    }
+    catch (e) {
+        const failed = publicResult(undefined, (0, shared_1.refuse)("hydration-internal", (0, shared_1.errorMessage)(e)), batch);
+        return requests.map(() => failed);
+    }
+    return Promise.all(requests.map(async (r) => {
+        // Snapshotted ONCE, inside a guard: a hostile getter or Proxy costs this request, not the
+        // batch. `experienceId`/`versionHash`/`handle` are primitives, captured by value right here.
+        // `params`, an object, is NOT safe by the same copy — a field holding a live reference can
+        // still answer a later read differently — so `serveOne` takes its own single deep-copy-and-
+        // validate pass over it (`snapshotParams`) before anything reads a key of it twice.
+        let snapshot;
+        try {
+            snapshot =
+                r !== null && typeof r === "object"
+                    ? {
+                        experienceId: r.experienceId,
+                        versionHash: r.versionHash,
+                        handle: r.handle,
+                        params: r.params,
+                    }
+                    : null;
+        }
+        catch {
+            const report = reporter(opts, "");
+            return publicResult(undefined, (0, shared_1.refuse)("invalid-request", "the request cannot be read"), report);
+        }
+        const handle = typeof snapshot?.handle === "string" ? snapshot.handle : undefined;
+        const report = reporter(opts, handle ?? "");
+        return publicResult(handle, await serveOne(exp, snapshot, opts, pass, report), report);
+    }));
+}
+/**
+ * Answer ONE handle load for `exp` — a batch of one (`serveHandles`). `opts.now` should be the
+ * server's clock: relative time is resolved here, never on the client.
+ */
+async function serveHandle(exp, request, opts) {
+    const [result] = await serveHandles(exp, [request], opts);
+    return result ?? (0, shared_1.refuse)("hydration-internal", "no result for the request");
+}
+function openPass(exp, opts) {
+    const { outputKinds, invoker, now, signal, principal } = opts;
+    const capped = (0, invokers_1.limitInvoker)(invoker, opts.maxConcurrentCalls ?? exports.DEFAULT_MAX_CONCURRENT_CALLS);
+    const exec = {
+        // One memo per batch, in front of the cap: a memo hit never takes a slot.
+        invoker: (0, invokers_1.memoInvoker)(capped),
+        now: now ?? Date.now(),
+        ...(signal !== undefined && { signal }),
+        ...(principal !== undefined && { principal }),
+        ...(opts.concurrency !== undefined && { concurrency: opts.concurrency }),
+        ...(opts.captureSample !== undefined && { captureSample: opts.captureSample }),
+        ...(opts.argumentHook !== undefined && { argumentHook: opts.argumentHook }),
+        ...(opts.contentRefArgs !== "none" && { contentRefArgs: opts.contentRefArgs }),
+        ...(opts.acceptContentRefParam !== undefined && {
+            acceptContentRefParam: opts.acceptContentRefParam,
+        }),
+        ...(opts.inputDrift !== undefined && { inputDrift: opts.inputDrift }),
+        ...(opts.reshapers !== undefined && { reshapers: opts.reshapers }),
+        ...(opts.providers !== undefined && { providers: opts.providers }),
+        ...(outputKinds?.catalog.valueContracts !== undefined && {
+            contracts: outputKinds.catalog.valueContracts,
+        }),
+    };
+    return {
+        exec,
+        // `bound` is handle-id collection only (no class read); `restricted` below takes the table.
+        bound: new Set((0, ui_core_1.experienceHandles)(exp).map((u) => u.handle)),
+        restricted: new Set((0, restricted_1.partitionByViewer)((0, ui_core_1.experienceHandles)(exp, opts.declaredToolClasses, opts.undeclared), (0, restricted_1.snapshotViewer)(opts.viewer, opts.audience)).restricted.map((u) => u.handle)),
+        // U9: media-typed nodes mark their handle as media even with NO `outputKinds` (fail closed).
+        kinds: (0, ui_core_1.handleKindsWithMedia)(exp, outputKinds?.catalog, outputKinds?.surface),
+        mediaWithoutKinds: outputKinds === undefined && (0, ui_core_1.hasMediaTypeNodes)(exp),
+        refsUnguarded: opts.contentRefArgs === "none" && (0, ui_core_1.hasMediaTypeNodes)(exp),
+    };
+}
+async function serveOne(exp, request, opts, pass, report) {
+    try {
+        if (request === null || typeof request !== "object" || typeof request.handle !== "string")
+            return (0, shared_1.refuse)("invalid-request", "a load request names a handle");
+        if (request.experienceId !== exp.experienceId || request.versionHash !== exp.versionHash)
+            return (0, shared_1.refuse)("version-mismatch", `the request is for ${String(request.experienceId)}@${String(request.versionHash)}, not ${exp.experienceId}@${exp.versionHash}`);
+        const handle = request.handle;
+        if ((0, projection_1.isReservedHandle)(handle))
+            return { state: "error", finding: (0, shared_1.reservedFinding)(handle) };
+        // Checked first, before the provider is even looked up: a restricted handle is never loaded,
+        // cached or invoked, for any request, whatever its params.
+        if (pass.restricted.has(handle)) {
+            // The server's log gets the true reason ONCE; the client's answer is the public
+            // `unknown-handle`, which is silenced so it is not logged as a second, contradicting finding.
+            report((0, restricted_1.restrictedFinding)());
+            const answer = (0, shared_1.refuse)("unknown-handle", `"${handle}" is not a handle this experience binds`);
+            if (answer.finding !== undefined)
+                report.silence(answer.finding);
+            return answer;
+        }
+        // Only what a node binds is served: a provider no node binds is not the client's to ask for.
+        const declared = pass.bound.has(handle) && Object.hasOwn(exp.providers, handle)
+            ? exp.providers[handle]
+            : undefined;
+        if (declared === undefined)
+            return (0, shared_1.refuse)("unknown-handle", `"${handle}" is not a handle this experience binds`);
+        // U9: a handle feeding a media widget is ALWAYS contract-checked, whatever the provider
+        // declared (a shape pin passes inline bytes or a locator into a client payload and the cache).
+        const mediaBound = (pass.kinds.get(handle) ?? []).some((k) => (0, ui_core_1.isMediaKind)(k) || (0, ui_core_1.isChatKind)(k));
+        const spec = mediaBound && declared.outputCheck !== "contract"
+            ? { ...declared, outputCheck: "contract" }
+            : declared;
+        if (mediaBound && pass.mediaWithoutKinds)
+            report({
+                code: "media-output-kinds-missing",
+                severity: "warn",
+                message: "the experience has media nodes and serve has no outputKinds: media handles are contract-checked by node type, but pass outputKinds so kinds resolve through the catalogue",
+            });
+        if (mediaBound && pass.refsUnguarded)
+            report({
+                code: "media-content-refs-unguarded",
+                severity: "warn",
+                message: 'the experience has media nodes and serve runs with contentRefArgs: "none": a content-reference tool argument is not checked; derive the table with contentRefArgsFrom(capabilities)',
+            });
+        // ONE deep-copy-and-validate pass over the request's params (`snapshotParams`): the result is
+        // plain, detached data with no accessor of its own, so `relevantParams`/`pickParams` below can
+        // never re-trigger a caller-supplied getter that answered differently than the check just did.
+        const snap = (0, params_1.snapshotParams)(request.params ?? {});
+        if (!snap.ok)
+            return { state: "error", finding: snap.finding };
+        const params = (0, params_1.relevantParams)(spec, snap.params);
+        // As in-process: only a contract provider's value is answerable to a kind.
+        const kinds = spec.outputCheck === "contract" ? (pass.kinds.get(handle) ?? []) : undefined;
+        const variant = kinds === undefined
+            ? { params }
+            : {
+                params,
+                kinds,
+                ...(pass.exec.contracts !== undefined && { contracts: pass.exec.contracts }),
+            };
+        // U9b: the content-reference guard (gate included) runs BEFORE the cache is consulted: a cached
+        // value was produced for an argument some principal's gate accepted once, and serving it to another
+        // principal, or after the host revoked it, would skip the gate. A refusal is not served from the
+        // cache (the load below refuses it); a param that fills a guarded argument is cached per principal.
+        const refs = pass.exec.contentRefArgs;
+        const verdict = refs === undefined
+            ? undefined
+            : (0, contentRefs_1.inspectContentRefs)(spec, params, (0, contentRefs_1.contentRefEnv)(refs, spec, pass.exec.acceptContentRefParam, {
+                principalId: opts.principalId,
+                principal: pass.exec.principal,
+            }));
+        const cacheSpec = verdict?.paramFilled ? (0, contentRefs_1.principalScoped)(spec) : spec;
+        const hit = verdict?.refusal === undefined
+            ? opts.cache?.get(cacheSpec, opts.principalId, variant)
+            : undefined;
+        if (hit)
+            return { state: "ready", value: hit.value };
+        const outcome = await (0, provider_1.executeProvider)(spec, {
+            ...pass.exec,
+            params,
+            ...(opts.principalId !== undefined && { principalId: opts.principalId }),
+            ...(kinds !== undefined && { kinds }),
+        });
+        for (const f of outcome.findings)
+            report(f);
+        if (!outcome.ok)
+            report(outcome.finding);
+        const drift = outcome.drift ?? [];
+        // Never cache a result that proceeded past an input drift (`report-and-proceed`): the key
+        // does not carry the drift mode, so a later request served under the default (`report`)
+        // would get it as a clean `ready` — no stale, no `onDrift`, no `onFinding`.
+        if (outcome.ok && drift.length === 0)
+            opts.cache?.set(cacheSpec, opts.principalId, outcome.value, variant);
+        if (drift.length > 0)
+            opts.onDrift?.({
+                experienceId: exp.experienceId,
+                versionHash: exp.versionHash,
+                handle,
+                spec,
+                drift,
+                findings: outcome.findings,
+                // Only a PROCEEDED input drift reaches here beside a delivered answer — a value, or an
+                // `empty` one (the retried upstream answered with no rows). `empty` itself is never drift.
+                proceeded: outcome.ok || outcome.finding.code === "upstream-empty",
+            });
+        return (0, provider_1.outcomeResult)(outcome);
+    }
+    catch (e) {
+        return (0, shared_1.refuse)("hydration-internal", (0, shared_1.errorMessage)(e));
+    }
+}
+function createServeSurface(policy = {}) {
+    const bound = (0, ui_core_1.mergeReadPolicy)(policy);
+    const joined = (opts) => {
+        const m = (0, ui_core_1.mergeReadPolicy)(bound, opts);
+        return {
+            ...opts,
+            ...(m.declaredToolClasses !== undefined && { declaredToolClasses: m.declaredToolClasses }),
+            ...(m.undeclared !== undefined && { undeclared: m.undeclared }),
+        };
+    };
+    return {
+        policy: bound,
+        handleInventory: (exp, opts) => handleInventory(exp, joined(opts)),
+        serveHandles: (exp, requests, opts) => serveHandles(exp, requests, joined(opts)),
+        serveHandle: (exp, request, opts) => serveHandle(exp, request, joined(opts)),
+    };
+}
+//# sourceMappingURL=server.js.map