@k2b/cloud 0.6.0 → 0.8.0

package/src/browser/search-bridge.ts

@@ -0,0 +1,102 @@
+import type { CloudResourceRef } from "../contracts";
+
+export type SearchScope = { label: string; icon?: string } & (
+  | { ref: CloudResourceRef; appId?: never; tag?: never }
+  | { appId: string; tag?: string; ref?: never }
+);
+export type GlobalSearchOptions = { scope?: SearchScope; query?: string };
+export type SearchNavigationTarget = { href: string; ref?: CloudResourceRef };
+type OpenRequest = { options: GlobalSearchOptions; accepted: boolean };
+type NavigationRequest = { target: SearchNavigationTarget; handled?: Promise<boolean> };
+
+declare global {
+  interface WindowEventMap {
+    "cloud.search.open": CustomEvent<OpenRequest>;
+    "cloud.search.navigate": CustomEvent<NavigationRequest>;
+  }
+}
+
+const READY = "cloud.search.ready";
+const CANCEL_OPEN = "cloud.search.cancel-open";
+const REPLACE_HOST = "cloud.search.replace-host";
+const REPLACE_NAVIGATION = "cloud.search.replace-navigation";
+
+/** One pending request per document, shared through events even across separate bundles. */
+export const requestGlobalSearch = (options: GlobalSearchOptions): Promise<void> => {
+  window.dispatchEvent(new Event(CANCEL_OPEN));
+  return new Promise((resolve, reject) => {
+    const detail: OpenRequest = { options, accepted: false };
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const cleanup = () => {
+      clearTimeout(timer);
+      window.removeEventListener(READY, attempt);
+      window.removeEventListener(CANCEL_OPEN, cancel);
+      window.removeEventListener("pagehide", cancel);
+    };
+    const cancel = () => {
+      cleanup();
+      resolve();
+    };
+    const attempt = () => {
+      window.dispatchEvent(new CustomEvent("cloud.search.open", { detail }));
+      if (detail.accepted) cancel();
+    };
+    window.addEventListener(READY, attempt);
+    window.addEventListener(CANCEL_OPEN, cancel);
+    window.addEventListener("pagehide", cancel);
+    // Bound the wait for hydration; never keep an invisible request indefinitely.
+    timer = setTimeout(() => {
+      cleanup();
+      reject(new Error("Search host unavailable"));
+    }, 8_000);
+    attempt();
+  });
+};
+
+export const registerGlobalSearchHost = (open: (options: GlobalSearchOptions) => void, dispose?: () => void): (() => void) => {
+  window.dispatchEvent(new Event(REPLACE_HOST));
+  const listener = (event: CustomEvent<OpenRequest>) => {
+    if (event.detail.accepted) return;
+    open(event.detail.options);
+    event.detail.accepted = true;
+  };
+  let active = true;
+  const cleanup = () => {
+    if (!active) return;
+    active = false;
+    dispose?.();
+    window.removeEventListener("cloud.search.open", listener);
+    window.removeEventListener(REPLACE_HOST, cleanup);
+  };
+  window.addEventListener("cloud.search.open", listener);
+  window.addEventListener(REPLACE_HOST, cleanup);
+  window.dispatchEvent(new Event(READY));
+  return cleanup;
+};
+
+export const registerSearchNavigation = (handler: (target: SearchNavigationTarget) => boolean | Promise<boolean>): (() => void) => {
+  window.dispatchEvent(new Event(REPLACE_NAVIGATION));
+  let active = true;
+  const listener = (event: CustomEvent<NavigationRequest>) => {
+    if (event.detail.handled) return;
+    event.detail.handled = Promise.resolve().then(async () => {
+      if (!active) return true; // An unmounted page must not start a late navigation.
+      const handled = await handler(event.detail.target);
+      return !active || handled;
+    });
+  };
+  const cleanup = () => {
+    active = false;
+    window.removeEventListener("cloud.search.navigate", listener);
+    window.removeEventListener(REPLACE_NAVIGATION, cleanup);
+  };
+  window.addEventListener("cloud.search.navigate", listener);
+  window.addEventListener(REPLACE_NAVIGATION, cleanup);
+  return cleanup;
+};
+
+export const requestSearchNavigation = async (target: SearchNavigationTarget): Promise<boolean> => {
+  const detail: NavigationRequest = { target };
+  window.dispatchEvent(new CustomEvent("cloud.search.navigate", { detail }));
+  return (await detail.handled) ?? false;
+};

package/src/browser/search-commands.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import type { SearchItem } from "../api/search/schemas";
+import { listCapabilityCatalog } from "../capabilities/client";
+import { LOCALE_HEADER } from "../shared/locale";
+import type { ContextAwareCommand } from "./command-bridge";
+
+export type PaletteCommand = ContextAwareCommand & { appName?: string; keywords?: readonly string[]; context?: boolean };
+export const loadSearchCommands = async (locale: string, signal: AbortSignal): Promise<PaletteCommand[]> => {
+  const commands: PaletteCommand[] = [];
+  let cursor: string | undefined;
+  do {
+    const result = await listCapabilityCatalog({ limit: 25, cursor, signal, headers: { [LOCALE_HEADER]: locale } });
+    if (!result.ok) throw new Error(result.error.message);
+    for (const app of result.data.apps) {
+      for (const command of app.manifest.commands) {
+        // Only Commands with a valid empty invocation are globally discoverable.
+        const input = z.fromJSONSchema(structuredClone(command.inputSchema)).safeParse({});
+        if (!input.success) continue;
+        const id = `${app.appId}.${command.localId}`;
+        commands.push({
+          id,
+          title: command.title,
+          description: command.description,
+          icon: command.icon ?? app.appIcon,
+          keywords: command.keywords,
+          appName: app.appName,
+          action: { command: id, input: input.data },
+        });
+      }
+    }
+    const next = result.data.page.hasMore ? result.data.page.nextCursor : undefined;
+    if (next && cursor && next <= cursor) throw new Error("Invalid Command catalog cursor");
+    cursor = next;
+  } while (cursor);
+  return commands;
+};
+export const commandSearchItem = (command: PaletteCommand, group: string): SearchItem => ({
+  ref: { type: "cloud.command", id: command.id },
+  href: "",
+  readable: false,
+  appId: command.context ? "cloud.context" : "cloud.commands",
+  appName: group,
+  appIcon: "ti ti-command",
+  title: command.title,
+  icon: command.icon ?? "ti ti-command",
+  preview: command.description,
+});
+export const matchingCommands = (commands: readonly PaletteCommand[], query: string, all: boolean): PaletteCommand[] => {
+  const normalized = query.toLocaleLowerCase().trim();
+  const matches = commands.filter((command) =>
+    !normalized
+      ? all || (command.context && !command.id.startsWith("cloud."))
+      : [command.title, command.description, command.appName, ...(command.keywords ?? [])]
+          .join(" ")
+          .toLocaleLowerCase()
+          .includes(normalized),
+  );
+  return !normalized && !all ? matches.slice(0, 3) : matches;
+};

package/src/browser/search.ts

@@ -0,0 +1,13 @@
+import { toast } from "@k2b/ui";
+import { resourceSearchMessages } from "./resource-search-messages";
+import { type GlobalSearchOptions, requestGlobalSearch } from "./search-bridge";
+
+export type { GlobalSearchOptions, SearchNavigationTarget, SearchScope } from "./search-bridge";
+export { registerSearchNavigation } from "./search-bridge";
+
+/** Open the Cloud layout's search, optionally within one removable context. */
+export const openGlobalSearch = (options: GlobalSearchOptions = {}): void => {
+  void requestGlobalSearch(options).catch(() => {
+    toast.error(resourceSearchMessages.resolve([document.documentElement.lang || "en"]).t.searchFailed);
+  });
+};

package/src/browser/spotlight-position.ts

@@ -0,0 +1,208 @@
+import type { DialogRender } from "@k2b/ui";
+
+export type SpotlightPosition = { x: number; y: number };
+const STORAGE_KEY = "cloud.spotlight.position.v1";
+const MARGIN = 12;
+const SNAP_DISTANCE = 24;
+
+export const readSpotlightPosition = (value: string | null): SpotlightPosition | null => {
+  try {
+    const position: unknown = JSON.parse(value ?? "null");
+    if (!position || typeof position !== "object" || !("x" in position) || !("y" in position)) return null;
+    const { x, y } = position;
+    if (typeof x !== "number" || typeof y !== "number" || !Number.isFinite(x) || !Number.isFinite(y)) return null;
+    return { x: Math.max(0, Math.min(1, x)), y: Math.max(0, Math.min(1, y)) };
+  } catch {
+    return null;
+  }
+};
+
+/** Cloud owns the desktop policy and persistence; the UI host owns modality and focus. */
+export const attachSpotlightPosition = (
+  host: HTMLElement,
+  context: Parameters<DialogRender<void>>[1],
+  messages: () => { homeHint: string; releaseHint: string },
+) => {
+  const { dialog } = context;
+  const desktop = window.matchMedia("(min-width: 64rem) and (hover: hover) and (pointer: fine)");
+  const enabled = () => desktop.matches && navigator.maxTouchPoints === 0;
+  const active = () => host.parentElement?.style.display !== "none" && dialog.classList.contains("cloud-search-dialog");
+  let stored: SpotlightPosition | null = null;
+  try {
+    stored = readSpotlightPosition(window.localStorage.getItem(STORAGE_KEY));
+  } catch {
+    /* Storage can be disabled; dragging still works for this opening. */
+  }
+  let anchor = { x: 0, y: 0 };
+  let bounds = { x: 0, y: 0 };
+  let position: SpotlightPosition | null = null;
+  let drag: {
+    id: number;
+    start: SpotlightPosition;
+    origin: SpotlightPosition;
+    previous: SpotlightPosition | null;
+    handle: HTMLElement;
+  } | null = null;
+
+  const home = document.createElement("div");
+  home.className = "cloud-global-search__home";
+  home.setAttribute("aria-hidden", "true");
+  const icon = document.createElement("i");
+  icon.className = "ti ti-search";
+  const hint = document.createElement("span");
+  const content = document.createElement("div");
+  content.append(icon, hint);
+  home.append(content);
+  host.append(home);
+  const clamp = (point: SpotlightPosition) => {
+    const rect = dialog.getBoundingClientRect();
+    return {
+      x: Math.max(MARGIN, Math.min(window.innerWidth - rect.width - MARGIN, point.x)),
+      y: Math.max(MARGIN, Math.min(window.innerHeight - rect.height - MARGIN, point.y)),
+    };
+  };
+  const renderPosition = () => {
+    if (!active()) return;
+    // Preserve the preferred point when growing upward to keep the panel on screen.
+    context.setPosition(position ? clamp(position) : null);
+    const rect = dialog.getBoundingClientRect();
+    home.style.left = `${anchor.x - rect.x - dialog.clientLeft}px`;
+    home.style.top = `${anchor.y - rect.y - dialog.clientTop}px`;
+    home.style.width = `${rect.width}px`;
+    home.style.height = `${rect.height}px`;
+    const ready = Math.hypot(rect.x - anchor.x, rect.y - anchor.y) <= SNAP_DISTANCE;
+    home.dataset.ready = String(ready);
+    icon.className = ready ? "ti ti-check" : "ti ti-search";
+    hint.textContent = ready ? messages().releaseHint : messages().homeHint;
+  };
+  const apply = (next: SpotlightPosition | null) => {
+    position = next;
+    context.setModal(next === null);
+    renderPosition();
+  };
+  const persist = () => {
+    stored = position
+      ? {
+          x: bounds.x ? (position.x - MARGIN) / bounds.x : 0,
+          y: bounds.y ? (position.y - MARGIN) / bounds.y : 0,
+        }
+      : null;
+    try {
+      if (stored) window.localStorage.setItem(STORAGE_KEY, JSON.stringify(stored));
+      else window.localStorage.removeItem(STORAGE_KEY);
+    } catch {
+      /* No persistence when storage is unavailable. */
+    }
+  };
+  const layout = () => {
+    if (!active()) return;
+    context.setPosition(null);
+    const rect = dialog.getBoundingClientRect();
+    anchor = { x: rect.x, y: rect.y };
+    // Vertical persistence describes the preferred top edge, independent of result height.
+    bounds = { x: Math.max(0, window.innerWidth - rect.width - 2 * MARGIN), y: Math.max(0, window.innerHeight - 2 * MARGIN) };
+    host.dataset.movable = String(enabled());
+    apply(enabled() && stored ? { x: MARGIN + stored.x * bounds.x, y: MARGIN + stored.y * bounds.y } : null);
+  };
+  const finish = () => {
+    if (!drag) return;
+    const handle = drag.handle;
+    const id = drag.id;
+    drag = null;
+    if (handle.hasPointerCapture(id)) handle.releasePointerCapture(id);
+    delete host.dataset.dragging;
+    persist();
+  };
+  const down = (event: PointerEvent) => {
+    const handle = event.target;
+    if (
+      !enabled() ||
+      !active() ||
+      event.pointerType !== "mouse" ||
+      event.button !== 0 ||
+      !(handle instanceof HTMLElement) ||
+      !handle.hasAttribute("data-search-grip")
+    )
+      return;
+    event.preventDefault();
+    const rect = dialog.getBoundingClientRect();
+    drag = {
+      id: event.pointerId,
+      start: { x: event.clientX, y: event.clientY },
+      origin: { x: rect.x, y: rect.y },
+      previous: position,
+      handle,
+    };
+    handle.setPointerCapture(event.pointerId);
+  };
+  const move = (event: PointerEvent) => {
+    if (!drag || event.pointerId !== drag.id) return;
+    const dx = event.clientX - drag.start.x;
+    const dy = event.clientY - drag.start.y;
+    if (!host.dataset.dragging && Math.hypot(dx, dy) < 3) return;
+    host.dataset.dragging = "true";
+    const next = clamp({ x: drag.origin.x + dx, y: drag.origin.y + dy });
+    apply(next);
+    // Switching native modality releases capture. Retain the same drag across that switch.
+    if (!drag.handle.hasPointerCapture(event.pointerId)) drag.handle.setPointerCapture(event.pointerId);
+  };
+  const up = (event: PointerEvent) => {
+    if (event.pointerId !== drag?.id) return;
+    if (host.dataset.dragging && home.dataset.ready === "true") apply(null);
+    finish();
+  };
+  const cancel = () => {
+    if (!drag) return;
+    apply(drag.previous);
+    finish();
+  };
+  const escape = (event: KeyboardEvent) => {
+    if (event.key !== "Escape" || !drag) return;
+    event.preventDefault();
+    event.stopPropagation();
+    cancel();
+  };
+  const resize = () => {
+    finish();
+    layout();
+  };
+  const reset = () => {
+    cancel();
+    apply(null);
+    persist();
+  };
+  host.addEventListener("pointerdown", down);
+  const doubleClick = (event: MouseEvent) => {
+    if (event.target instanceof HTMLElement && event.target.hasAttribute("data-search-grip")) reset();
+  };
+  host.addEventListener("dblclick", doubleClick);
+  window.addEventListener("pointermove", move);
+  window.addEventListener("pointerup", up);
+  window.addEventListener("pointercancel", cancel);
+  window.addEventListener("blur", finish);
+  window.addEventListener("keydown", escape, true);
+  window.addEventListener("resize", resize);
+  desktop.addEventListener("change", resize);
+  // Mount happens before the native dialog is shown by the host.
+  const frame = requestAnimationFrame(layout);
+  const observer = new MutationObserver(layout);
+  observer.observe(dialog, { attributes: true, attributeFilter: ["class"] });
+  const sizeObserver = new ResizeObserver(renderPosition);
+  sizeObserver.observe(dialog);
+  return () => {
+    cancelAnimationFrame(frame);
+    observer.disconnect();
+    sizeObserver.disconnect();
+    home.remove();
+    finish();
+    host.removeEventListener("pointerdown", down);
+    host.removeEventListener("dblclick", doubleClick);
+    window.removeEventListener("pointermove", move);
+    window.removeEventListener("pointerup", up);
+    window.removeEventListener("pointercancel", cancel);
+    window.removeEventListener("blur", finish);
+    window.removeEventListener("keydown", escape, true);
+    window.removeEventListener("resize", resize);
+    desktop.removeEventListener("change", resize);
+  };
+};

package/src/browser/testing.ts

@@ -0,0 +1,6 @@
+/** Browser-only test probes. Mount and dispose application islands through their public APIs. */
+
+export { readWorkspaceNavigation } from "../ssr/workspace-navigation";
+export { collectContextAwareCommands } from "./command-bridge";
+export { contextCommandsWithShortcuts } from "./command-shortcuts";
+export { registerGlobalSearchHost } from "./search-bridge";

package/src/browser/web-vitals.ts

@@ -0,0 +1,25 @@
+import { type Metric, onCLS, onINP, onLCP } from "web-vitals";
+
+const script = document.querySelector<HTMLScriptElement>("script[data-cloud-web-vitals]");
+const appId = script?.dataset.appId;
+const routeTemplate = script?.dataset.routeTemplate;
+
+if (appId && routeTemplate) {
+  const report = ({ name, value, id, navigationType }: Metric) => {
+    const entry = performance.getEntriesByType("navigation")[0];
+    const serverTiming: Record<string, number> = {};
+    const timings =
+      typeof PerformanceNavigationTiming !== "undefined" && entry instanceof PerformanceNavigationTiming ? entry.serverTiming : [];
+    for (const timing of timings) {
+      if (["auth", "settings", "runtime", "ssr_data", "ssr_finalize", "ssr_render"].includes(timing.name)) {
+        serverTiming[timing.name] = (serverTiming[timing.name] ?? 0) + timing.duration;
+      }
+    }
+    // Never serialize Metric.entries: they can contain page text, elements and private URLs.
+    const body = JSON.stringify({ appId, routeTemplate, name, value, id, navigationType, serverTiming });
+    navigator.sendBeacon("/api/me/web-vitals", new Blob([body], { type: "application/json" }));
+  };
+  onLCP(report);
+  onINP(report);
+  onCLS(report);
+}

package/src/capabilities/claims.ts

@@ -0,0 +1,179 @@
+import { sql } from "bun";
+import { logger } from "../services/logging";
+
+const log = logger("capabilities:claims");
+
+/**
+ * Platform-owned idempotency claims for capability Actions.
+ *
+ * Every Action that declares `idempotency: "required"` is claimed here before
+ * the dispatcher forwards it, and resolved once the outcome is known. Apps own
+ * no claim code: retry safety is the same contract for built-in and
+ * third-party capabilities.
+ */
+export type CapabilityClaimScope = {
+  appId: string;
+  /** Fully qualified capability name, such as `grids.record_create`. */
+  capability: string;
+  /** Acting principal as `user:<id>`, `service_account:<id>`, or `anonymous`. */
+  principal: string;
+  /** Caller-supplied Idempotency-Key, hashed before storage. */
+  keyHash: string;
+};
+
+export type CapabilityClaimState = "in_flight" | "succeeded" | "uncertain";
+
+export type CapabilityClaimOutcome =
+  /** The caller owns this claim and must resolve it after forwarding. */
+  | { state: "claimed" }
+  /** A definitive earlier success for the same input; return this response verbatim. */
+  | { state: "replay"; status: number; body: unknown }
+  /** An earlier success whose response exceeded the retained body cap. */
+  | { state: "not_retained" }
+  /** Same key, different input. */
+  | { state: "conflict" }
+  /** A concurrent attempt still holds the claim. */
+  | { state: "in_flight" }
+  /** An earlier attempt left the outcome unknown; the caller must verify with a Query. */
+  | { state: "uncertain" };
+
+/**
+ * A retry window long enough to cover a human or agent noticing a lost
+ * response and repeating the call, without keeping response bodies around as
+ * de-facto durable app data. Twenty-four hours is the common industry contract
+ * and there is deliberately no operator setting for it.
+ */
+export const CAPABILITY_CLAIM_RETENTION_HOURS = 24;
+
+/**
+ * Responses larger than this are not retained. A replay then reports that the
+ * result is gone rather than returning a partial or fabricated body; the
+ * caller must read the current state with a Query.
+ */
+export const CAPABILITY_CLAIM_MAX_BODY_BYTES = 256 * 1024;
+
+/** Stable JSON with sorted object keys, so equal inputs hash equally whatever order the caller sent. */
+const canonicalJson = (value: unknown): string => {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, item]) => item !== undefined)
+    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+  return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
+};
+
+const sha256 = (value: string): string => new Bun.CryptoHasher("sha256").update(value).digest("hex");
+
+/** Hash of the validated capability input. Two calls with the same key must carry the same hash. */
+export const capabilityRequestHash = (input: unknown): string => sha256(canonicalJson(input));
+
+export const capabilityIdempotencyKeyHash = (key: string): string => sha256(key);
+
+type ClaimRow = { state: CapabilityClaimState; request_hash: string; response_status: number | null; response_body: unknown };
+
+/**
+ * Claim the scope before forwarding. Inserts `in_flight`; on conflict it reads
+ * the existing row and never re-forwards a call whose outcome is already known
+ * or still unknown.
+ */
+export const claimCapabilityIdempotency = async (scope: CapabilityClaimScope, requestHash: string): Promise<CapabilityClaimOutcome> => {
+  const [inserted] = await sql<{ inserted: boolean }[]>`
+    INSERT INTO capabilities.idempotency_claims (app_id, capability, principal, key_hash, request_hash, state)
+    VALUES (${scope.appId}, ${scope.capability}, ${scope.principal}, ${scope.keyHash}, ${requestHash}, 'in_flight')
+    ON CONFLICT (app_id, capability, principal, key_hash) DO NOTHING
+    RETURNING true AS inserted
+  `;
+  if (inserted) return { state: "claimed" };
+
+  const [existing] = await sql<ClaimRow[]>`
+    SELECT state, request_hash, response_status, response_body
+    FROM capabilities.idempotency_claims
+    WHERE app_id = ${scope.appId} AND capability = ${scope.capability}
+      AND principal = ${scope.principal} AND key_hash = ${scope.keyHash}
+  `;
+  // The row can disappear between the insert and the read when a concurrent
+  // attempt releases a definitive failure. Retrying the claim once is safe.
+  if (!existing) {
+    const [second] = await sql<{ inserted: boolean }[]>`
+      INSERT INTO capabilities.idempotency_claims (app_id, capability, principal, key_hash, request_hash, state)
+      VALUES (${scope.appId}, ${scope.capability}, ${scope.principal}, ${scope.keyHash}, ${requestHash}, 'in_flight')
+      ON CONFLICT (app_id, capability, principal, key_hash) DO NOTHING
+      RETURNING true AS inserted
+    `;
+    return second ? { state: "claimed" } : { state: "in_flight" };
+  }
+  if (existing.request_hash !== requestHash) return { state: "conflict" };
+  if (existing.state === "in_flight") return { state: "in_flight" };
+  if (existing.state === "uncertain") return { state: "uncertain" };
+  if (existing.response_status === null) return { state: "not_retained" };
+  return { state: "replay", status: existing.response_status, body: existing.response_body };
+};
+
+/** Records a definitive success so a later retry replays it instead of acting twice. */
+export const completeCapabilityClaim = async (scope: CapabilityClaimScope, status: number, body: unknown): Promise<void> => {
+  let serialized: string | null = null;
+  try {
+    const encoded = JSON.stringify(body);
+    if (encoded !== undefined && new TextEncoder().encode(encoded).byteLength <= CAPABILITY_CLAIM_MAX_BODY_BYTES) serialized = encoded;
+  } catch {
+    serialized = null;
+  }
+  await sql`
+    UPDATE capabilities.idempotency_claims
+    SET state = 'succeeded',
+        response_status = ${serialized === null ? null : status},
+        response_body = ${serialized}::text::jsonb,
+        updated_at = now()
+    WHERE app_id = ${scope.appId} AND capability = ${scope.capability}
+      AND principal = ${scope.principal} AND key_hash = ${scope.keyHash}
+  `;
+};
+
+/** Releases a claim whose failure proves nothing happened, so a corrected retry can run. */
+export const releaseCapabilityClaim = async (scope: CapabilityClaimScope): Promise<void> => {
+  await sql`
+    DELETE FROM capabilities.idempotency_claims
+    WHERE app_id = ${scope.appId} AND capability = ${scope.capability}
+      AND principal = ${scope.principal} AND key_hash = ${scope.keyHash}
+      AND state = 'in_flight'
+  `;
+};
+
+/** Freezes a claim whose request left the dispatcher without a usable answer. Never deleted by a retry. */
+export const markCapabilityClaimUncertain = async (scope: CapabilityClaimScope): Promise<void> => {
+  await sql`
+    UPDATE capabilities.idempotency_claims
+    SET state = 'uncertain', updated_at = now()
+    WHERE app_id = ${scope.appId} AND capability = ${scope.capability}
+      AND principal = ${scope.principal} AND key_hash = ${scope.keyHash}
+      AND state = 'in_flight'
+  `;
+};
+
+/** Resolving a claim must never fail the call it describes; the outcome is already decided. */
+export const resolveCapabilityClaim = async (resolve: Promise<void>, scope: CapabilityClaimScope): Promise<void> =>
+  resolve.catch((error: unknown) => {
+    log.error("Capability idempotency claim could not be resolved", {
+      capability: scope.capability,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  });
+
+const PRUNE_BATCH_SIZE = 5_000;
+
+/** Deletes expired claims in bounded batches, alongside the execution retention sweep. */
+export const pruneCapabilityIdempotencyClaims = async (olderThan: Date): Promise<number> => {
+  let total = 0;
+  let deleted: number;
+  do {
+    const result = await sql`
+      WITH expired AS (
+        SELECT ctid FROM capabilities.idempotency_claims WHERE created_at < ${olderThan} LIMIT ${PRUNE_BATCH_SIZE}
+      )
+      DELETE FROM capabilities.idempotency_claims claim USING expired WHERE claim.ctid = expired.ctid
+    `;
+    deleted = result.count;
+    total += deleted;
+  } while (deleted === PRUNE_BATCH_SIZE);
+  return total;
+};

package/src/capabilities/client.ts

@@ -147,3 +147,37 @@ export const reviewCapabilityAction = async <TInput = unknown>(
     return unavailable(cause, undefined, clientLocale(options.headers));
   }
 };
+
+/** Resolve an interactive entry; this never runs a domain mutation. */
+export const resolveCommand = async (
+  command: string,
+  input: unknown = {},
+  commandOptions: import("../contracts/commands").CommandOptions = {},
+  options: CapabilityHttpOptions & { signal?: AbortSignal } = {},
+): Promise<import("./types").CapabilityResultState<{ href: string }>> => {
+  const { CommandRequestSchema, CommandLinkSchema } = await import("../contracts/commands");
+  const separator = command.indexOf(".");
+  if (separator < 1) throw new Error("Expected a qualified Command id");
+  const appId = command.slice(0, separator);
+  const localId = command.slice(separator + 1);
+  const body = CommandRequestSchema.parse({ input, ...commandOptions });
+  const headers = new Headers(options.headers);
+  headers.set("content-type", "application/json");
+  try {
+    const response = await (options.fetch ?? globalThis.fetch)(
+      requestUrl(options.baseUrl ?? "/api", `/capabilities/v1/commands/${encodeURIComponent(appId)}/${encodeURIComponent(localId)}`),
+      {
+        method: "POST",
+        headers,
+        credentials: "same-origin",
+        body: JSON.stringify(body),
+        signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(15_000)]) : AbortSignal.timeout(15_000),
+      },
+    );
+    return await readCapabilityResponse(response, CommandLinkSchema);
+  } catch (cause) {
+    return unavailable(cause, undefined, clientLocale(options.headers));
+  }
+};
+
+export { type CapabilityStreamVerb, transferCapabilityStream } from "./streams";

package/src/capabilities/command-link.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import type { CapabilityCommandManifest } from "../contracts/capabilities";
+import { CommandLinkSchema, type CommandOptions, commandPath } from "../contracts/commands";
+import { publicCloudOrigin } from "../shared/app-url";
+
+export const resolveCommandLink = (
+  appId: string,
+  command: CapabilityCommandManifest,
+  input: unknown,
+  options: CommandOptions,
+  appUrl: string,
+) => {
+  const parsed = z.fromJSONSchema(structuredClone(command.inputSchema)).parse(input);
+  const path = commandPath(command.path, `${appId}.${command.localId}`, parsed, options);
+  return CommandLinkSchema.parse({ href: new URL(path, publicCloudOrigin(appUrl)).href });
+};