@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/sandbox.ts

@@ -0,0 +1,1209 @@
+// QuickJS evaluator for bundled realm.ts modules.
+//
+// Walker dispatches on string kinds ("node.tab", "input.text",
+// "host.port", etc.). Inputs carry their typed metadata in `meta`
+// (`meta.title`, `meta.placeholder`, etc.); enum keeps `values` on the
+// record so the sandbox can surface them to the UI.
+//
+// validateFetchData reads `node.responseSchema` directly: each
+// `r.remote.fetchUrl(...).schema(...)` stores the live Zod schema as a
+// non-enumerable property on the record, reachable from inside QuickJS
+// where the schema's parse runs.
+
+// Both eval paths (getDesiredState + the gate) run on the *asyncified* QuickJS
+// variant — the sync one can't suspend for the gate's async `stableSecret`, and
+// pulling in both variants makes a production build collide their identically
+// named `emscripten-module.wasm` assets (only one survives, breaking whichever
+// loader resolves the wrong build). Importing the single async variant directly
+// keeps the sync variant out of the bundle entirely. getDesiredState never
+// registers a host fn, so its sync `evalCode` runs without ever suspending — no
+// asyncify cost on that path.
+import { newQuickJSAsyncWASMModuleFromVariant } from "quickjs-emscripten-core";
+import { z } from "zod";
+import { RealmCompileError } from "./errors.ts";
+import type { HomeApp, RequestManifest } from "./resolve.ts";
+import type { Grant } from "./grants.ts";
+import { hardenedJsonParse } from "./safe-json.ts";
+import { sha256Hex } from "./generator/hash.ts";
+
+// Interrupt handler that bounds an eval by the work *this VM* performs, not by
+// wall-clock or process CPU. QuickJS calls it on loop back-edges and function
+// entry, only while this VM executes bytecode, so counting its own invocations
+// measures this eval's own progress and nothing else:
+//   - immune to scheduler starvation (a busy box stretches wall time but not
+//     tick count); and
+//   - immune to sibling evals/threads — unlike `process.cpuUsage()`, which is
+//     process-global and sums every concurrent eval's CPU into each one's
+//     budget, tripping unrelated evals under `deno test --parallel`.
+// A runaway burns ticks without bound and trips; a bounded eval does a fixed
+// amount of work and stays under the ceiling on any machine. Host suspends (the
+// gate's `await stableSecret`) execute no bytecode, so they accrue no ticks.
+function workBudget(maxTicks: number) {
+  let ticks = 0;
+  return () => ++ticks > maxTicks;
+}
+
+// Per-VM work ceilings (interrupt-handler ticks). The handler fires coarsely:
+// a heavy *legit* eval measures ~6 ticks and the cold gate bundle-load ~4,
+// while a runaway loop accrues ~13k ticks/sec. So these ceilings sit thousands
+// of × above any real eval yet still kill a runaway in ~1-2s. EVAL bounds one
+// eval; COLD is the gate's one-time bundle+shim load, kept higher purely for
+// headroom.
+const EVAL_TICK_BUDGET = 20_000;
+const COLD_EVAL_TICK_BUDGET = 100_000;
+
+/**
+ * Run a one-shot QuickJS eval against a bundled realm.ts module and return
+ * whatever JSON the snippet computes. Warms a throwaway sync VM (no host fns →
+ * plain `evalCode`), runs the snippet against the resident `__app`, and disposes
+ * — the cold path, one VM per call, no pooling. The bundle must assign its
+ * exports to `__realm_module__`; the snippet stringifies its result.
+ */
+async function runInSandbox(bundledCode: string, snippet: string): Promise<unknown> {
+  const vm = await createVmInstance({ bundle: bundledCode });
+  try {
+    return await vm.call(snippet);
+  } finally {
+    await vm.dispose();
+  }
+}
+
+export interface ConfigFieldLeaf {
+  type: "text" | "secret" | "number" | "boolean" | "enum";
+  label?: string;
+  placeholder?: string | number;
+  default?: unknown;
+  description?: string;
+  optional?: boolean;
+  /** For enum fields: the allowed values. */
+  values?: string[];
+  /** Numeric-input bounds (`r.input.number().min/max`), rendered as
+   * `<input>` min/max. `step` is `1` when the author called `.int()`. */
+  min?: number;
+  max?: number;
+  step?: number;
+}
+
+export interface ConfigContainerNode {
+  type: "tab" | "section";
+  optional?: boolean;
+  /** Author's `.title(...)`, if set. The renderer falls back to the key. */
+  title?: string;
+  /** Author's `.describe(...)`, if set. */
+  description?: string;
+  fields: Record<string, ConfigField>;
+}
+
+/**
+ * Placeholder node marking where a permission leaf sits in the authoring
+ * tree. Preserves declaration order so the UI can render config + perms
+ * interleaved per the source, not grouped by kind. The renderer looks up
+ * the actual metadata in `permissionsFlat[path]`.
+ */
+export interface ConfigPermissionRef {
+  type: "permission";
+  path: string;
+}
+
+export type ConfigField = ConfigFieldLeaf | ConfigContainerNode | ConfigPermissionRef;
+
+export type ConfigFieldTree = Record<string, ConfigField>;
+
+/**
+ * Permission record as it crosses the QuickJS boundary: kind tag,
+ * grant data, and meta. Anything non-enumerable (fetchUrl's live Zod
+ * schema, chain methods) drops out via JSON.stringify.
+ */
+export interface SerializablePermission {
+  kind: Grant["kind"];
+  data: unknown;
+  meta: Record<string, unknown>;
+}
+
+/**
+ * Identifier of one ui surface declared on the app's `ui:` block.
+ * Iframe bundling iterates these to know what entries to generate.
+ */
+export interface SurfaceDescriptor {
+  kind: "page" | "widget";
+  key: string;
+}
+
+/**
+ * Probe `__app.name` from a bundled realm.ts. Reads the shared
+ * `extractAppMeta` probe, so asking for the name costs nothing once any
+ * other extract has run against this bundle. The dev server needs it
+ * before compile runs to pick the docker-compose project name.
+ */
+export async function extractAppName(bundledCode: string): Promise<string> {
+  const { name } = await extractAppMeta(bundledCode);
+  if (typeof name !== "string" || name.length === 0) {
+    throw new RealmCompileError({
+      kind: "validation",
+      path: ["name"],
+      message: "createApp({ name }) is required",
+    });
+  }
+  return name;
+}
+
+/**
+ * Probe `__app.kind`. Set by the `createApp` / `createSystemApp` factory,
+ * so always present as `"single"` or `"system"`.
+ */
+export async function extractAppKind(bundledCode: string): Promise<"single" | "system"> {
+  const { kind } = await extractAppMeta(bundledCode);
+  if (kind === "single" || kind === "system") return kind;
+  throw new RealmCompileError({
+    kind: "validation",
+    path: ["kind"],
+    message: `expected "single" or "system", got ${JSON.stringify(kind)}`,
+  });
+}
+
+/**
+ * Probe `__app.ui.pages` and `__app.ui.widgets` and emit the surface
+ * keys without invoking any render fn or evaluating the app's config.
+ * Runs entirely inside QuickJS so render closures (which can't cross
+ * the boundary) stay on the inside.
+ */
+export async function extractUiSurfaceKeys(bundledCode: string): Promise<SurfaceDescriptor[]> {
+  const snippet = `
+    (function() {
+      var ui = __app.ui;
+      var out = [];
+      if (!ui || typeof ui !== "object") {
+        return JSON.stringify(out);
+      }
+      function collect(record, kind) {
+        if (!record || typeof record !== "object") return;
+        var keys = Object.keys(record);
+        for (var i = 0; i < keys.length; i++) {
+          out.push({ kind: kind, key: keys[i] });
+        }
+      }
+      collect(ui.pages, "page");
+      collect(ui.widgets, "widget");
+      return JSON.stringify(out);
+    })();
+  `;
+  const result = (await runInSandbox(bundledCode, snippet)) as SurfaceDescriptor[];
+  return result;
+}
+
+interface ExtractedSchema {
+  /**
+   * Tree mirroring the configSchema in declared order. Tabs and
+   * sections are container nodes; config leaves carry their metadata
+   * inline; permission leaves appear as `{type: "permission", path}`
+   * markers whose metadata lives in `permissionsFlat`.
+   */
+  configFields: ConfigFieldTree;
+  /**
+   * Dotted-path → permission record (kind + data + meta). Functions and
+   * non-enumerable properties (e.g. `remote.fetchUrl`'s live Zod schema)
+   * drop naturally on the way through.
+   */
+  permissionsFlat: Record<string, SerializablePermission>;
+  /**
+   * Dotted paths of every `r.input.secret` field. Used by
+   * `replaceSecrets` to swap plaintext for structured markers before the
+   * sandbox runs.
+   */
+  secretPaths: string[];
+}
+
+/**
+ * Walk `__app.configSchema` and emit configFields + permissionsFlat +
+ * secretPaths in a single pass. Handles the two authoring modes:
+ *   - All top-level entries are `r.tab(...)` → tabbed UI, nested paths.
+ *   - No top-level entries are tabs → flat leaves, top-level paths.
+ *
+ * Runs entirely inside QuickJS so live functions (chain methods) and
+ * non-enumerable references (the Zod schema on fetchUrl) are filtered
+ * before crossing the host boundary.
+ */
+export async function extractSchema(bundledCode: string): Promise<ExtractedSchema> {
+  const { configFields, permissionsFlat, secretPaths } = await extractAppMeta(bundledCode);
+  assertOneSilo(permissionsFlat);
+  return { configFields, permissionsFlat, secretPaths };
+}
+
+/**
+ * One `host.silo()` per app. Opening this up later is additive; closing it
+ * later would break whatever had started relying on two.
+ */
+function assertOneSilo(permissionsFlat: Record<string, SerializablePermission>): void {
+  const paths = Object.entries(permissionsFlat)
+    .filter(([, p]) => p.kind === "host.silo")
+    .map(([path]) => path);
+  if (paths.length < 2) return;
+  throw new RealmCompileError({
+    kind: "validation",
+    path: [paths[1]!],
+    message: `an app may join one Silo, but ${paths.length} are declared (${paths.join(", ")})`,
+  });
+}
+
+/**
+ * Everything a single VM boot can read off a bundled realm.ts: the two
+ * scalar probes (`name`, `kind`) plus the full configSchema walk.
+ */
+interface AppMeta extends ExtractedSchema {
+  /** Raw `__app.name`; `extractAppName` validates it. */
+  name: unknown;
+  /** Raw `__app.kind`; `extractAppKind` validates it. */
+  kind: unknown;
+}
+
+// Memoized because a miss costs a whole QuickJS runtime plus a re-parse of the
+// ~600KB bundle (~150ms), and the callers ask repeatedly for the same bundle:
+// one `POST /api/apps/preview` probes name + kind + schema in analyzeSource and
+// schema AGAIN in graph.ts's prepare(), and one recomputeAndDiff() probes per
+// app for the capability gate and then per app PER WORKER inside evalApps —
+// ~90 boots of blocking WASM at ~18 apps × 2 workers.
+//
+// Keyed by a digest of the bundle, not the bundle itself. `bundle()` reads from
+// an on-disk cache and so hands back a fresh ~610KB string per call, which as a
+// key would both rehash 610KB per lookup and pin every bundle ever probed in the
+// heap. Hashing costs ~0.35ms against the ~150ms it saves. A rejected probe is
+// evicted so a transient eval failure isn't pinned.
+//
+// Uncapped, with nothing sweeping it. A cap below the app count would evict
+// every entry before it is reused — a recompute probes every installed app —
+// taking the hit rate to zero. Entries are a digest plus a config-schema tree,
+// a few KB, so a thousand apps is single-digit MB; it grows on churn with
+// nothing to reclaim it, against a process that restarts on upgrade.
+const metaCache = new Map<string, Promise<AppMeta>>();
+
+async function extractAppMeta(bundledCode: string): Promise<AppMeta> {
+  const key = await sha256Hex(bundledCode);
+  const hit = metaCache.get(key);
+  if (hit) return await hit;
+  const p = extractAppMetaUncached(bundledCode);
+  metaCache.set(key, p);
+  p.catch(() => metaCache.delete(key));
+  return await p;
+}
+
+async function extractAppMetaUncached(bundledCode: string): Promise<AppMeta> {
+  const snippet = `
+    (function() {
+      var tabs = __app.configSchema;
+      var configFields = {};
+      var permissionsFlat = {};
+      var secretPaths = [];
+
+      function walk(node, path, name, parentFields) {
+        if (!node || typeof node !== "object") return;
+        var kind = node.kind;
+        if (typeof kind !== "string") return;
+        var meta = node.meta || {};
+
+        if (kind === "node.tab" || kind === "node.section") {
+          var specific = kind === "node.tab" ? "tab" : "section";
+          var container = { type: specific, fields: {} };
+          if (meta.isOptional) container.optional = true;
+          if (meta.title) container.title = meta.title;
+          if (meta.description) container.description = meta.description;
+          var children = node.children;
+          if (children && typeof children === "object") {
+            var keys = Object.keys(children);
+            for (var i = 0; i < keys.length; i++) {
+              var key = keys[i];
+              var childPath = path ? path + "." + key : key;
+              walk(children[key], childPath, key, container.fields);
+            }
+          }
+          if (parentFields) parentFields[name] = container;
+          return;
+        }
+
+        if (kind.indexOf("input.") === 0) {
+          var specific = kind.slice("input.".length);
+          var entry = { type: specific };
+          if (meta.title) entry.label = meta.title;
+          if (meta.placeholder !== undefined) entry.placeholder = meta.placeholder;
+          if (meta.prefill !== undefined) entry["default"] = meta.prefill;
+          if (meta.description) entry.description = meta.description;
+          if (meta.isOptional) entry.optional = true;
+          if (specific === "enum" && node.values) entry.values = node.values.slice();
+          if (specific === "number") {
+            if (meta.int) entry.step = 1;
+            if (meta.min !== undefined) entry.min = meta.min;
+            if (meta.max !== undefined) entry.max = meta.max;
+          }
+          if (specific === "secret") secretPaths.push(path);
+          if (parentFields) parentFields[name] = entry;
+          return;
+        }
+
+        // Permission leaves (host.* / peers.* / remote.*). Strip
+        // function fields (chain methods, etc.) and non-enumerable
+        // refs (fetchUrl's live Zod schema). Object.keys() already
+        // skips non-enumerable, and the function filter handles the
+        // chain methods.
+        var serial = {};
+        var nodeKeys = Object.keys(node);
+        for (var j = 0; j < nodeKeys.length; j++) {
+          var k = nodeKeys[j];
+          var v = node[k];
+          if (typeof v === "function") continue;
+          serial[k] = v;
+        }
+        permissionsFlat[path] = serial;
+        if (parentFields) parentFields[name] = { type: "permission", path: path };
+      }
+
+      // A non-object configSchema yields empty trees, but name/kind are
+      // still read below — the two probes must not depend on the app
+      // having a schema at all.
+      if (tabs && typeof tabs === "object") {
+        var topKeys = Object.keys(tabs);
+        for (var i = 0; i < topKeys.length; i++) {
+          var k = topKeys[i];
+          walk(tabs[k], k, k, configFields);
+        }
+      }
+
+      return JSON.stringify({
+        name: __app.name,
+        kind: __app.kind,
+        configFields: configFields,
+        permissionsFlat: permissionsFlat,
+        secretPaths: secretPaths,
+      });
+    })();
+  `;
+  return (await runInSandbox(bundledCode, snippet)) as AppMeta;
+}
+
+/**
+ * Validate raw JSON data against the live Zod schema declared on a
+ * `remote.fetchUrl` permission. Runs the schema's parse inside QuickJS
+ * so untrusted validation code can't escape.
+ *
+ * The schema doesn't cross the QuickJS boundary: `r.remote.fetchUrl`
+ * stores the live Zod object as a non-enumerable property on the record,
+ * which JSON.stringify drops on the way out but stays reachable when
+ * we re-enter the sandbox here.
+ */
+export async function validateFetchData(
+  bundledCode: string,
+  permissionPath: string,
+  rawJson: string,
+): Promise<unknown> {
+  const snippet = [
+    `var __path = ${JSON.stringify(permissionPath)};`,
+    `var __tabs = __app.configSchema || {};`,
+    `// Navigate the typed tree by dotted path. createApp rejects keys`,
+    `// containing "." so the split is unambiguous.`,
+    `var __segments = __path.split(".");`,
+    `var __node = __tabs[__segments[0]];`,
+    `for (var __i = 1; __i < __segments.length; __i++) {`,
+    `  if (!__node) break;`,
+    `  if (__node.children) __node = __node.children[__segments[__i]];`,
+    `  else __node = __node[__segments[__i]];`,
+    `}`,
+    `if (!__node || !__node.responseSchema || typeof __node.responseSchema.parse !== "function")`,
+    `  throw new Error("No Zod schema on permission " + __path);`,
+    // String embedded into the QuickJS-side script: this JSON.parse runs
+    // inside the sandbox boundary, not the host, and feeds the app's own
+    // responseSchema.parse below.
+    `var __rawData = JSON.parse(${JSON.stringify(rawJson)});`,
+    `JSON.stringify(__node.responseSchema.parse(__rawData));`,
+  ].join("\n");
+  return runInSandbox(bundledCode, snippet);
+}
+
+/** Per-install preview context threaded to `getDesiredState`; null = persistent. */
+interface PreviewArg {
+  previewKey: string;
+}
+
+/** Identity of one memoized eval; `null` in its place skips the cache. */
+interface ExecuteCacheKey {
+  /** Digest of the app's source. See `executeCache` for why it's the source. */
+  bundleId: string;
+  /** Slug of the worker this eval resolved against. */
+  workerId: string;
+}
+
+/**
+ * Execute `app.evaluate({ config, appId, preview })` against a bundled
+ * realm.ts module. `data` is the unified config tree (config fields + resolved
+ * permission values, already merged by the caller). Per-worker context lands
+ * inside `data` under any granted `host.management()` path, not as a separate
+ * arg. `preview` is `null` for a normal install and `{ previewKey }` when the
+ * app is stamped as a template's preview child.
+ *
+ * `cache` keys the memo (see `executeCache`); `null` skips it, for a throwaway
+ * appId whose entry could never be read again.
+ */
+export async function execute(
+  bundledCode: string,
+  data: Record<string, unknown>,
+  appId: string,
+  cache: ExecuteCacheKey | null,
+  preview?: PreviewArg | null,
+): Promise<HomeApp> {
+  const slot = cache === null ? "" : `${appId}\0${preview?.previewKey ?? ""}\0${cache.workerId}`;
+  const inputKey = JSON.stringify(data);
+  if (cache !== null) {
+    const hit = executeCache.get(slot);
+    if (hit && hit.inputKey === inputKey && hit.bundleId === cache.bundleId) {
+      return structuredClone(await hit.result);
+    }
+  }
+
+  const snippet = [
+    `globalThis.__realm_deferred_fns = [];`,
+    `var __config = ${JSON.stringify(data)};`,
+    `var __appId = ${JSON.stringify(appId)};`,
+    `var __preview = ${JSON.stringify(preview ?? null)};`,
+    "JSON.stringify(__app.evaluate({ config: __config, appId: __appId, preview: __preview }));",
+  ].join("\n");
+  const result = runInSandbox(bundledCode, snippet) as Promise<HomeApp>;
+
+  // Uncached callers own the only reference, so they skip the defensive clone.
+  if (cache === null) return await result;
+
+  executeCache.set(slot, { bundleId: cache.bundleId, inputKey, result });
+  result.catch(() => executeCache.delete(slot));
+  return structuredClone(await result);
+}
+
+/**
+ * Drop every cached eval whose app no longer exists, returning how many went.
+ *
+ * This bounds `executeCache` in place of a cap. Size tracks apps × workers by
+ * construction, so a cap could only ever fire on garbage, and a FIFO one would
+ * evict by age rather than liveness — exactly the wrong order. Home just read
+ * the app table, so it knows the real answer.
+ *
+ * Called from `recomputeAndDiff`, which fires on every event that can orphan a
+ * slot. A removed worker's entries wait for their apps to go; workers churn far
+ * more rarely than apps.
+ */
+export function sweepExecuteCache(liveAppIds: ReadonlySet<string>): number {
+  let dropped = 0;
+  for (const slot of executeCache.keys()) {
+    // A preview child's own row id is the appId half, so previews are swept by
+    // their own liveness, not the parent's.
+    const appId = slot.slice(0, slot.indexOf("\0"));
+    if (!liveAppIds.has(appId)) {
+      executeCache.delete(slot);
+      dropped++;
+    }
+  }
+  return dropped;
+}
+
+// Memoized because `recomputeAndDiff` re-evaluates EVERY app on any change, and
+// an install / config edit / grant change each fire one — building up to N apps
+// costs O(N²) evals at ~100ms of blocking WASM apiece.
+//
+// SLOT: one per (app, preview child, worker), NOT one entry per input state. A
+// recompute scans every app once per worker, so one slot per thing scanned hits
+// on every step of that scan. Input-keying would make the scan touch N distinct
+// keys and evict each before reuse — the FIFO worst case, 0% hits past the cap.
+// The worker is in the slot for the same reason: an app with a granted
+// `host.management()` resolves a different `workerId` per worker, so one shared
+// slot has w1 and w2 overwriting each other every pass, killing the cache for
+// exactly the system apps that run everywhere.
+//
+// INVALIDATION: `inputKey` + `bundleId`. `data` is the app's fully-resolved
+// input, so a world that genuinely moved re-evals while an unrelated app's
+// install hits — no need to classify which permission kinds are worker-
+// dependent. `bundleId` is a digest of the SOURCE, so an updated app misses
+// without the entry retaining the ~600KB bundle to compare against.
+//
+// Eval output is assumed deterministic: `stateHashCache` in apps-recompute.ts
+// hashes it to decide whether a worker changed, so an app returning different
+// output for identical inputs would reconcile-loop with or without this cache.
+//
+// Callers get a structuredClone, never the cached instance — HomeApp flows on
+// through resolveRefs, build-wire and the gate registry, and sharing it would
+// turn any in-place edit into a cross-app bug. Well under a millisecond against
+// a ~100ms VM boot.
+//
+// Unbounded by design; `sweepExecuteCache` is what bounds it.
+const executeCache = new Map<
+  string,
+  { bundleId: string; inputKey: string; result: Promise<HomeApp> }
+>();
+
+/**
+ * Second-shot for deferred markers. Re-runs the bundle in a fresh
+ * QuickJS VM and invokes each registered apply() callback with its
+ * resolved input. The caller has already merged the same data tree both
+ * passes see, so apply() callbacks observe the same `config.management`
+ * etc. across both runs.
+ */
+export async function executeDeferred(
+  bundledCode: string,
+  data: Record<string, unknown>,
+  appId: string,
+  items: Array<{ id: number; input: unknown }>,
+  preview?: PreviewArg | null,
+): Promise<string[]> {
+  const snippet = [
+    `globalThis.__realm_deferred_fns = [];`,
+    `var __config = ${JSON.stringify(data)};`,
+    `var __appId = ${JSON.stringify(appId)};`,
+    `var __preview = ${JSON.stringify(preview ?? null)};`,
+    `__app.evaluate({ config: __config, appId: __appId, preview: __preview });`,
+    `var __items = ${JSON.stringify(items)};`,
+    `var __fns = globalThis.__realm_deferred_fns || [];`,
+    `var __out = [];`,
+    `for (var __i = 0; __i < __items.length; __i++) {`,
+    `  var __it = __items[__i];`,
+    `  var __fn = __fns[__it.id];`,
+    `  if (typeof __fn !== "function") {`,
+    `    throw new Error("apply() fn #" + __it.id + " not registered");`,
+    `  }`,
+    `  var __res = __fn(__it.input);`,
+    `  if (typeof __res !== "string") {`,
+    `    throw new Error("apply() fn #" + __it.id + " must return a string, got " + typeof __res);`,
+    `  }`,
+    `  __out.push(__res);`,
+    `}`,
+    `JSON.stringify(__out);`,
+  ].join("\n");
+  return (await runInSandbox(bundledCode, snippet)) as string[];
+}
+
+/**
+ * Run `app.info({ services })` against a bundled realm.ts module and return
+ * its raw dict — values are strings, `null`, or `{__realmRef}` markers the
+ * caller resolves post-eval with `resolveRefs`. `services` is plain data; no
+ * host fn enters the VM. `undefined`-valued keys drop in-VM. Returns `null`
+ * when the app declares no `info`.
+ */
+export async function executeInfo(
+  bundledCode: string,
+  services: Record<string, string | null>,
+): Promise<Record<string, unknown> | null> {
+  const snippet = [
+    `var __services = ${JSON.stringify(services)};`,
+    `(function () {`,
+    `  if (typeof __app.info !== "function") return JSON.stringify(null);`,
+    `  var out = __app.info({ services: __services });`,
+    `  if (!out || typeof out !== "object") return JSON.stringify(null);`,
+    `  var cleaned = {};`,
+    `  var keys = Object.keys(out);`,
+    `  for (var i = 0; i < keys.length; i++) {`,
+    `    var k = keys[i];`,
+    `    var v = out[k];`,
+    `    if (v === undefined) continue;`,
+    `    cleaned[k] = v;`,
+    `  }`,
+    `  return JSON.stringify(cleaned);`,
+    `})();`,
+  ].join("\n");
+  return (await runInSandbox(bundledCode, snippet)) as Record<string, unknown> | null;
+}
+
+// ---- anonymous gate (verifyAnonymousRequest) -------------------------------
+//
+// Unlike getDesiredState / getTrustedHeaders, the gate is live logic over a
+// real request, so it executes per call rather than being sampled to data. It
+// runs in the *asyncified* QuickJS variant: secret derivation is async
+// (crypto.subtle), and `newAsyncifiedFunction` lets the guest call
+// `stableSecret(name)` synchronously while the host awaits underneath.
+// REALM_SECRET never enters the VM — Home injects only a `deriveSecret(name)`
+// capability already bound to this app's id.
+
+/** The original request as the gate sees it: method, URL, headers — no body. */
+export interface GateRequest {
+  method: string;
+  url: string;
+  /** Header name → value. Names match case-insensitively inside the VM. */
+  headers: Record<string, string>;
+}
+
+export const gateResultSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("allow") }),
+  z.object({ kind: z.literal("deny") }),
+  z.object({
+    kind: z.literal("respond"),
+    status: z.number(),
+    headers: z.record(z.string(), z.string()),
+    body: z.string().nullable(),
+  }),
+]);
+export type GateResult = z.infer<typeof gateResultSchema>;
+
+// Bare QuickJS has no Request/Response/Headers/URL. Define minimal versions on
+// the VM global before the gate runs so the documented Web-standard surface
+// (`request.headers.get`, `new URL(request.url)`, `new Response(...)`) works.
+const GATE_SHIM = `
+  function __Headers(init) {
+    this._m = {};
+    if (init) for (var k in init) {
+      if (Object.prototype.hasOwnProperty.call(init, k)) this._m[String(k).toLowerCase()] = init[k];
+    }
+  }
+  __Headers.prototype.get = function (name) {
+    var v = this._m[String(name).toLowerCase()];
+    return v === undefined ? null : v;
+  };
+  __Headers.prototype.has = function (name) {
+    return Object.prototype.hasOwnProperty.call(this._m, String(name).toLowerCase());
+  };
+  function __Request(data) {
+    this.method = data.method;
+    this.url = data.url;
+    this.headers = new __Headers(data.headers);
+  }
+  function __Response(body, init) {
+    init = init || {};
+    this.status = init.status === undefined ? 200 : init.status;
+    var h = init.headers || {};
+    if (h instanceof __Headers) h = h._m;
+    this.headers = h;
+    this.body = body == null ? null : String(body);
+    this.__isResponse = true;
+  }
+  function __URL(input) {
+    var s = String(input);
+    var proto = "", host = "", rest = s;
+    var schemeEnd = s.indexOf("://");
+    if (schemeEnd >= 0) {
+      proto = s.slice(0, schemeEnd + 1);
+      rest = s.slice(schemeEnd + 3);
+      var slash = rest.indexOf("/");
+      if (slash >= 0) { host = rest.slice(0, slash); rest = rest.slice(slash); }
+      else { host = rest; rest = ""; }
+    }
+    var hash = "", search = "", pathname = rest || "/";
+    var hi = pathname.indexOf("#");
+    if (hi >= 0) { hash = pathname.slice(hi); pathname = pathname.slice(0, hi); }
+    var qi = pathname.indexOf("?");
+    if (qi >= 0) { search = pathname.slice(qi); pathname = pathname.slice(0, qi); }
+    if (pathname === "") pathname = "/";
+    this.protocol = proto; this.host = host; this.pathname = pathname;
+    this.search = search; this.hash = hash;
+    var params = {};
+    if (search.length > 1) {
+      var pairs = search.slice(1).split("&");
+      for (var i = 0; i < pairs.length; i++) {
+        if (!pairs[i]) continue;
+        var eq = pairs[i].indexOf("=");
+        var key = eq >= 0 ? pairs[i].slice(0, eq) : pairs[i];
+        var val = eq >= 0 ? pairs[i].slice(eq + 1) : "";
+        key = decodeURIComponent(key.split("+").join(" "));
+        val = decodeURIComponent(val.split("+").join(" "));
+        if (!Object.prototype.hasOwnProperty.call(params, key)) params[key] = val;
+      }
+    }
+    this.searchParams = {
+      get: function (k) { return Object.prototype.hasOwnProperty.call(params, k) ? params[k] : null; },
+      has: function (k) { return Object.prototype.hasOwnProperty.call(params, k); }
+    };
+  }
+  globalThis.Headers = __Headers;
+  globalThis.Request = __Request;
+  globalThis.Response = __Response;
+  globalThis.URL = __URL;
+`;
+
+// Per-request snippet. The bundle, the shim, and the stableSecret host fn are
+// already loaded on the warm context — this only ships the request data and
+// the gate call.
+function gateCallSnippet(request: GateRequest): string {
+  return [
+    `var __requestData = ${JSON.stringify(request)};`,
+    `(function () {`,
+    `  if (typeof __app.verifyAnonymousRequest !== "function") return JSON.stringify({ kind: "deny" });`,
+    `  var request = new Request(__requestData);`,
+    `  var stableSecret = function (name) { return __realm_stableSecret(name); };`,
+    `  var verdict = __app.verifyAnonymousRequest(request, stableSecret);`,
+    `  if (verdict === true) return JSON.stringify({ kind: "allow" });`,
+    `  if (verdict && verdict.__isResponse) {`,
+    `    var __status = verdict.status;`,
+    `    if (typeof __status !== "number" || !(__status >= 200 && __status <= 599)) {`,
+    `      return JSON.stringify({ kind: "deny" });`, // malformed status → fail closed
+    `    }`,
+    `    var __headers = {};`,
+    `    var __src = verdict.headers || {};`,
+    `    for (var __k in __src) {`,
+    `      if (Object.prototype.hasOwnProperty.call(__src, __k)) __headers[__k] = String(__src[__k]);`,
+    `    }`,
+    `    return JSON.stringify({`,
+    `      kind: "respond",`,
+    `      status: __status,`,
+    `      headers: __headers,`,
+    `      body: verdict.body == null ? null : String(verdict.body)`,
+    `    });`,
+    `  }`,
+    `  return JSON.stringify({ kind: "deny" });`,
+    `})();`,
+  ].join("\n");
+}
+
+/** A warm VM handle handed to callers: it only calls in — the pool owns disposal.
+ *  Internal until slice 2 exports `getVm` for the cold sites. */
+interface VmHandle {
+  /** Eval a snippet against the resident `__app`, returning parsed JSON. Serialized. */
+  call(snippet: string): Promise<unknown>;
+}
+
+/** Internal per-VM lifecycle the pool manages (and the one-shot `runGate` uses). */
+interface VmInstance {
+  call(snippet: string): Promise<unknown>;
+  /** Current QuickJS heap in bytes (`computeMemoryUsage().memory_used_size`). */
+  memoryUsageBytes(): number;
+  /** Drain any in-flight call on the still-live context, then free it. Idempotent. */
+  dispose(): Promise<void>;
+}
+
+let asyncModulePromise: ReturnType<typeof newQuickJSAsyncWASMModuleFromVariant> | null = null;
+
+// Memoize the async WASM module load (shared by runInSandbox + the gate), but
+// never cache a rejection: a transient load failure must not permanently wedge
+// every gate into deny. Clear the slot on failure so the next call retries.
+function loadAsyncModule(): ReturnType<typeof newQuickJSAsyncWASMModuleFromVariant> {
+  if (!asyncModulePromise) {
+    // Dynamic import (the variant's documented form) so only the asyncify
+    // variant enters the bundle - the sync variant never does, so a prod build
+    // can't collide their identically named wasm. Deno resolves the package as
+    // CJS, nesting the variant at `.default.default`; the loader's smartUnwrap
+    // and PromisedDefault both handle that.
+    const pending = newQuickJSAsyncWASMModuleFromVariant(
+      import("@jitl/quickjs-wasmfile-release-asyncify"),
+    );
+    pending.catch(() => {
+      if (asyncModulePromise === pending) asyncModulePromise = null;
+    });
+    asyncModulePromise = pending;
+  }
+  return asyncModulePromise;
+}
+
+/**
+ * Evaluate a bundle (+ optional preamble) once into a fresh context, then reuse
+ * it for every `call(snippet)`. Re-evaluating the whole bundle (zod + SDK + app)
+ * is ~150ms; a warm instance pays that once and each call is just the snippet.
+ * Calls are serialized: one asyncified context can't run two evals at once.
+ *
+ * `hostFns` are bound as asyncified host functions before the bundle runs — the
+ * guest calls `name(arg)` synchronously while the host awaits underneath, so the
+ * seed / REALM_SECRET stay host-side. Their presence picks the eval mode: a VM
+ * with host fns must suspend (the gate's `stableSecret`), so it uses
+ * `evalCodeAsync`; a host-fn-free VM (widget prefill) runs plain synchronous
+ * `evalCode` and pays no asyncify cost, on the same async build.
+ */
+async function createVmInstance(opts: {
+  bundle: string;
+  preamble?: string;
+  hostFns?: Record<string, (arg: string) => Promise<string>>;
+}): Promise<VmInstance> {
+  const QuickJS = await loadAsyncModule();
+  const suspends = Object.keys(opts.hostFns ?? {}).length > 0;
+
+  // Creation and disposal differ by mode, and the two must match:
+  //  - Sync VMs (no host fns: the cold extracts + widget prefill) own their
+  //    runtime explicitly so dispose() can call `runtime.dispose()` and RECLAIM
+  //    the WASM heap. The shorthand `QuickJS.newContext()` + `context.dispose()`
+  //    does NOT reclaim the runtime in quickjs-emscripten 0.32: every
+  //    create/dispose leaks ~5MB, which over a control plane's recompute
+  //    bursts climbs into gigabytes until `WebAssembly.Memory.grow()` fails
+  //    and every eval OOMs.
+  //  - Asyncify VMs (host fns: the gate's `stableSecret`) must use
+  //    `QuickJS.newContext()`, whose single `vm.dispose()` frees the host fn's
+  //    runtime-scoped HostRef in the right order; disposing an explicit runtime
+  //    there double-frees the HostRef and throws. These are warm-pooled and
+  //    disposed rarely, so the (unreclaimed) heap doesn't accumulate.
+  const runtime = suspends ? null : QuickJS.newRuntime();
+  const vm = runtime ? runtime.newContext() : QuickJS.newContext();
+  vm.runtime.setMemoryLimit(32 * 1024 * 1024); // 32 MB
+  for (const [name, fn] of Object.entries(opts.hostFns ?? {})) {
+    const hostFn = vm.newAsyncifiedFunction(name, async (argHandle) =>
+      vm.newString(await fn(vm.getString(argHandle))),
+    );
+    vm.setProp(vm.global, name, hostFn);
+    hostFn.dispose();
+  }
+
+  // Eval the bundle + preamble once; `__app` and any shimmed globals persist on
+  // the context for every later call(). Generous budget — this is the heavy step.
+  vm.runtime.setInterruptHandler(workBudget(COLD_EVAL_TICK_BUDGET));
+  const code = [opts.bundle, "", "var __app = __realm_module__.default;", opts.preamble ?? ""].join(
+    "\n",
+  );
+  const init = suspends ? await vm.evalCodeAsync(code) : vm.evalCode(code);
+  if (init.error) {
+    const err = vm.dump(init.error);
+    init.error.dispose();
+    vm.dispose();
+    runtime?.dispose();
+    throw new RealmCompileError({
+      kind: "eval",
+      message: typeof err === "string" ? err : JSON.stringify(err),
+    });
+  }
+  (init as unknown as { value: Parameters<typeof vm.dump>[0] }).value.dispose();
+
+  // One context can't run two asyncified evals concurrently — chain calls.
+  let queue: Promise<unknown> = Promise.resolve();
+  let disposing = false;
+
+  async function runOne(snippet: string): Promise<unknown> {
+    vm.runtime.setInterruptHandler(workBudget(EVAL_TICK_BUDGET));
+    const result = suspends ? await vm.evalCodeAsync(snippet) : vm.evalCode(snippet);
+    if (result.error) {
+      const err = vm.dump(result.error);
+      result.error.dispose();
+      throw new RealmCompileError({
+        kind: "eval",
+        message: typeof err === "string" ? err : JSON.stringify(err),
+      });
+    }
+    const handle = (result as unknown as { value: Parameters<typeof vm.dump>[0] }).value;
+    const json = vm.dump(handle);
+    handle.dispose();
+    if (typeof json !== "string") {
+      throw new Error(`Expected JSON string from sandbox, got ${typeof json}`);
+    }
+    return hardenedJsonParse(json);
+  }
+
+  return {
+    call(snippet) {
+      // Refuse once teardown has started — don't enqueue onto a context about to
+      // be freed; the caller fails closed.
+      if (disposing) return Promise.reject(new Error("vm is disposing"));
+      const result = queue.then(() => runOne(snippet));
+      queue = result.catch(() => {});
+      return result;
+    },
+    memoryUsageBytes() {
+      const handle = vm.runtime.computeMemoryUsage();
+      const used = (vm.dump(handle) as { memory_used_size?: number }).memory_used_size ?? 0;
+      handle.dispose();
+      return used;
+    },
+    async dispose() {
+      if (disposing) return; // idempotent — the pool may evict + invalidate
+      disposing = true;
+      // Let an in-flight call finish on the still-live VM before freeing it: a
+      // dispose mid-call (an eviction during a suspended host fn) would otherwise
+      // resume the asyncified eval into a freed context and hang.
+      await queue.catch(() => {});
+      vm.dispose();
+      runtime?.dispose();
+    },
+  };
+}
+
+// ---- warm VM pool ----------------------------------------------------------
+//
+// One module-level pool of warm contexts, keyed `${purpose}:${id}` (e.g.
+// `gate:${appId}:${bundleHash}`). The single door: callers get a VM via `getVm`
+// and never spin a context themselves. The bundle version is folded into the
+// key, so a changed bundle is simply a new key — the stale entry idles out
+// rather than needing explicit invalidation.
+//
+// Retention is lazy: each `getVm` sweeps entries idle past WARM_TTL_MS, and a
+// count cap evicts the least-recently-used beyond MAX_WARM. No timer, so nothing
+// to leak; an idle VM only lingers while the pool is completely quiet, which is
+// exactly when nothing is under memory pressure.
+//
+// getVm stays internal until a second caller lands; only the gate wrapper
+// below uses it.
+
+const WARM_TTL_MS = 10 * 60 * 1000;
+/** Backstop, not a target — a control plane gates a handful of apps. ~2.4MB each. */
+const MAX_WARM = 64;
+
+interface PoolEntry {
+  key: string;
+  instance: Promise<VmInstance>;
+  /** The settled instance, set when `instance` resolves — lets `snapshot()`
+   * read heap synchronously and tell a warm entry from a still-warming one. */
+  resolved: VmInstance | null;
+  lastUsedAt: number;
+  seq: number;
+  disposing: boolean;
+}
+
+const pool = new Map<string, PoolEntry>();
+let poolSeq = 0;
+
+interface GetVmOpts {
+  /** `${purpose}:${id}` — one warm VM per key, never shared across purposes. */
+  key: string;
+  /** The compiled app; evaluated once when the key is first warmed. */
+  bundle: string;
+  /** Code eval'd once after the bundle (e.g. the gate's Request/Response shim). */
+  preamble?: string;
+  /** Async host fns bound before the bundle runs; keeps secrets host-side. */
+  hostFns?: Record<string, (arg: string) => Promise<string>>;
+}
+
+/**
+ * The warm VM for `key`, created on first use and reused after. The handle only
+ * calls in — the pool owns the lifecycle (idle-TTL + LRU), so callers never
+ * dispose. A creation failure clears the slot so the next call re-warms rather
+ * than caching a rejection.
+ */
+function getVm(opts: GetVmOpts): VmHandle {
+  sweepIdle();
+  const existing = pool.get(opts.key);
+  if (existing) {
+    existing.lastUsedAt = Date.now();
+    existing.seq = ++poolSeq;
+    return { call: (snippet) => existing.instance.then((i) => i.call(snippet)) };
+  }
+
+  const entry: PoolEntry = {
+    key: opts.key,
+    lastUsedAt: Date.now(),
+    seq: ++poolSeq,
+    disposing: false,
+    resolved: null,
+    instance: createVmInstance({
+      bundle: opts.bundle,
+      preamble: opts.preamble,
+      hostFns: opts.hostFns,
+    }),
+  };
+  entry.instance.then(
+    (i) => {
+      entry.resolved = i;
+    },
+    () => {
+      if (pool.get(entry.key) === entry) pool.delete(entry.key);
+    },
+  );
+  pool.set(entry.key, entry);
+  evictExcess();
+  return { call: (snippet) => entry.instance.then((i) => i.call(snippet)) };
+}
+
+function disposeEntry(entry: PoolEntry): void {
+  if (entry.disposing) return;
+  entry.disposing = true;
+  pool.delete(entry.key);
+  void entry.instance.then((i) => i.dispose()).catch(() => {});
+}
+
+function sweepIdle(): void {
+  const now = Date.now();
+  for (const entry of pool.values()) {
+    if (now - entry.lastUsedAt > WARM_TTL_MS) disposeEntry(entry);
+  }
+}
+
+function evictExcess(): void {
+  if (pool.size <= MAX_WARM) return;
+  const live = [...pool.values()].filter((e) => !e.disposing).sort((a, b) => a.seq - b.seq);
+  for (const entry of live.slice(0, live.length - MAX_WARM)) disposeEntry(entry);
+}
+
+/**
+ * Dispose every warm VM, draining in-flight calls first. For process shutdown
+ * and test teardown — production reuse relies on the lazy sweep, not this.
+ */
+export async function disposeAllVms(): Promise<void> {
+  await Promise.all(
+    [...pool.values()].map((entry) => {
+      if (entry.disposing) return Promise.resolve();
+      entry.disposing = true;
+      pool.delete(entry.key);
+      return entry.instance.then((i) => i.dispose()).catch(() => {});
+    }),
+  );
+}
+
+// ---- pool snapshot (admin diagnostics) -------------------------------------
+
+/** One warm (or still-warming) context, flattened for the admin VM-pool view. */
+export interface VmPoolEntrySnapshot {
+  /** `gate` or `prefill` — the key's first segment. */
+  purpose: string;
+  /** App id — the key's second segment (nameSchema-safe, so never a `:`). */
+  appId: string;
+  /** Bundle hash — the key's remainder (hex, so never a `:`). */
+  bundleId: string;
+  /** `warm` once the instance promise resolved; `warming` while still evaluating. */
+  state: "warm" | "warming";
+  /** Current QuickJS heap in bytes, or `null` if it couldn't be measured. */
+  heapBytes: number | null;
+  /** Epoch ms of the most recent `getVm` for this key. */
+  lastUsedAt: number;
+}
+
+/** In-process view of the warm VM pool for the admin diagnostics page. */
+export interface VmPoolSnapshot {
+  entries: VmPoolEntrySnapshot[];
+  /** LRU cap (`MAX_WARM`). */
+  maxWarm: number;
+  /** Idle TTL in ms (`WARM_TTL_MS`). */
+  ttlMs: number;
+  /** Sum of every measurable `heapBytes`. */
+  totalHeapBytes: number;
+}
+
+/**
+ * Read-only snapshot of the warm VM pool. Splits each key into
+ * purpose/appId/bundleId (on the first two colons — appId and bundleId hold
+ * none), reads heap synchronously off the resolved instance (a still-warming
+ * entry reports `warming` with no heap), and totals the cap + TTL + heap.
+ * Best-effort: an asyncified gate VM suspended mid-call can't be measured, so
+ * its `heapBytes` comes back `null`.
+ */
+export function snapshot(): VmPoolSnapshot {
+  const entries: VmPoolEntrySnapshot[] = [];
+  let totalHeapBytes = 0;
+  for (const entry of pool.values()) {
+    if (entry.disposing) continue;
+    const firstColon = entry.key.indexOf(":");
+    const secondColon = entry.key.indexOf(":", firstColon + 1);
+    let heapBytes: number | null = null;
+    if (entry.resolved) {
+      try {
+        heapBytes = entry.resolved.memoryUsageBytes();
+        totalHeapBytes += heapBytes;
+      } catch {
+        heapBytes = null;
+      }
+    }
+    entries.push({
+      purpose: entry.key.slice(0, firstColon),
+      appId: entry.key.slice(firstColon + 1, secondColon),
+      bundleId: entry.key.slice(secondColon + 1),
+      state: entry.resolved ? "warm" : "warming",
+      heapBytes,
+      lastUsedAt: entry.lastUsedAt,
+    });
+  }
+  return { entries, maxWarm: MAX_WARM, ttlMs: WARM_TTL_MS, totalHeapBytes };
+}
+
+// ---- gate wrapper ----------------------------------------------------------
+
+/**
+ * Run one app's anonymous gate against a request, reusing its warm VM. The key
+ * folds in `bundleId` (Home's bundle hash) so a redeploy transparently warms a
+ * fresh context. `deriveSecret` is Home's app-scoped `deriveAppPassword`. Throws
+ * on an eval error / malformed verdict, which the caller treats as deny (fail
+ * closed); a gate that returns a bad status denies in-snippet.
+ */
+export async function runAppGate(opts: {
+  appId: string;
+  bundleId: string;
+  bundle: string;
+  request: GateRequest;
+  deriveSecret: (name: string) => Promise<string>;
+}): Promise<GateResult> {
+  const vm = getVm({
+    key: `gate:${opts.appId}:${opts.bundleId}`,
+    bundle: opts.bundle,
+    preamble: GATE_SHIM,
+    hostFns: { __realm_stableSecret: opts.deriveSecret },
+  });
+  return gateResultSchema.parse(await vm.call(gateCallSnippet(opts.request)));
+}
+
+/** One-shot gate: warm a throwaway VM, run once, dispose. Tests / rare callers. */
+export async function runGate(
+  bundledCode: string,
+  request: GateRequest,
+  deriveSecret: (name: string) => Promise<string>,
+): Promise<GateResult> {
+  const vm = await createVmInstance({
+    bundle: bundledCode,
+    preamble: GATE_SHIM,
+    hostFns: { __realm_stableSecret: deriveSecret },
+  });
+  try {
+    return gateResultSchema.parse(await vm.call(gateCallSnippet(request)));
+  } finally {
+    await vm.dispose();
+  }
+}
+
+// ---- widget prefill (loader request stitching) -----------------------------
+
+// Run every loader's request(seedState, config) inside the VM and collect the
+// descriptors. `seedState` is the surface's `stateSchema.parse({})` — the exact
+// seed the iframe runtime mounts with — so a descriptor produced here matches
+// the query key the runtime later builds from `request(state, config)`, and the
+// prefilled data seeds cleanly with no first-paint refetch. A loader whose
+// request is null (or throws) on the seed is lazy for this config → omitted.
+function stitchSnippet(collection: "pages" | "widgets", key: string, config: unknown): string {
+  return [
+    `var __config = ${JSON.stringify(config ?? null)};`,
+    `if (__config == null) __config = {};`, // mirror the runtime's `opts.config ?? {}`
+    `(function () {`,
+    `  var ui = __app.ui;`,
+    `  var surface = ui && ui.${collection} && ui.${collection}[${JSON.stringify(key)}];`,
+    `  if (!surface) return JSON.stringify({});`,
+    `  var seedState = {};`,
+    `  if (surface.stateSchema && typeof surface.stateSchema.safeParse === "function") {`,
+    `    var __p = surface.stateSchema.safeParse({});`,
+    `    seedState = __p.success ? __p.data : {};`,
+    `  }`,
+    `  var out = {};`,
+    `  var loaders = surface.loaders || {};`,
+    `  var names = Object.keys(loaders);`,
+    `  for (var i = 0; i < names.length; i++) {`,
+    `    var loader = loaders[names[i]];`,
+    `    if (!loader || typeof loader.request !== "function") continue;`,
+    `    var req;`,
+    `    try { req = loader.request(seedState, __config); } catch (e) { req = null; }`,
+    `    out[names[i]] = req == null ? null : req;`,
+    `  }`,
+    `  return JSON.stringify(out);`,
+    `})();`,
+  ].join("\n");
+}
+
+/**
+ * Stitch every loader's request for one surface against the real per-instance
+ * `config`, reusing a warm sync VM keyed `prefill:${appId}:${bundleId}`. Returns
+ * a map of loader name → request descriptor (eager) or `null` (lazy). Home runs
+ * this at shell-render time so its server-side prefill uses the placement's real
+ * config; the returned descriptors match what the iframe runtime computes on
+ * mount.
+ */
+export async function stitchLoaderRequests(opts: {
+  appId: string;
+  bundleId: string;
+  bundle: string;
+  kind: "page" | "widget";
+  key: string;
+  config: unknown;
+}): Promise<Record<string, RequestManifest | null>> {
+  const vm = getVm({ key: `prefill:${opts.appId}:${opts.bundleId}`, bundle: opts.bundle });
+  const collection = opts.kind === "widget" ? "widgets" : "pages";
+  const result = await vm.call(stitchSnippet(collection, opts.key, opts.config));
+  return (result ?? {}) as Record<string, RequestManifest | null>;
+}
+
+/**
+ * Build a nested object by placing each flat-path value at its dotted
+ * location. Used to recompose resolved permission values into the shape
+ * `getDesiredState` expects (mirroring the tabs tree).
+ *
+ *   nestByPaths({ "a.b": 1, "a.c": 2 }) → { a: { b: 1, c: 2 } }
+ */
+export function nestByPaths(flat: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [path, value] of Object.entries(flat)) {
+    const segments = path.split(".");
+    let cursor = out;
+    for (let i = 0; i < segments.length - 1; i++) {
+      const seg = segments[i]!;
+      const next = cursor[seg];
+      if (!next || typeof next !== "object" || Array.isArray(next)) {
+        cursor[seg] = {};
+      }
+      cursor = cursor[seg] as Record<string, unknown>;
+    }
+    cursor[segments[segments.length - 1]!] = value;
+  }
+  return out;
+}