@k2b/cloud 0.38.0 → 0.40.0

package/README.md

@@ -83,6 +83,14 @@ Application setup, public contracts, and deployment guidance:
 - **[Create the first application](https://github.com/k2b-dev/cloud/blob/main/docs-site/docs/en/build/getting-started.md)** — standalone project setup and a verified API endpoint
 - **[github.com/k2b-dev/cloud](https://github.com/k2b-dev/cloud)** — the platform monorepo (gateway, core, all platform apps)
 
+## Security
+
+Report a vulnerability privately through
+[GitHub Security Advisories](https://github.com/k2b-dev/cloud/security/advisories/new),
+never in a public issue. Security fixes appear in this package's changelog,
+and a published advisory names the first patched version. See the
+[security policy](https://github.com/k2b-dev/cloud/blob/main/SECURITY.md).
+
 ## License
 
 GNU Affero General Public License v3.0 or later.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -34,14 +34,17 @@
     "./browser/app-badges": "./src/browser/app-badges.ts",
     "./browser/live": "./src/browser/live.ts",
     "./browser/mermaid": "./src/browser/mermaid.ts",
+    "./browser/hints": "./src/browser/hints.ts",
     "./browser/reload": "./src/browser/reload.ts",
     "./browser/notifications": "./src/browser/notifications.ts",
     "./browser/resource-clipboard": "./src/browser/resource-clipboard.ts",
     "./browser/commands": "./src/browser/commands.ts",
+    "./browser/panel": "./src/browser/panel.ts",
     "./browser/search": "./src/browser/search.ts",
     "./browser/widgets": "./src/browser/widgets.ts",
     "./browser/testing": "./src/browser/testing.ts",
     "./browser/resource-picker": "./src/browser/resource-picker.tsx",
+    "./browser/composer-insert": "./src/browser/composer-insert.ts",
     "./browser/files": "./src/browser/files.tsx",
     "./capabilities": "./src/capabilities/client.ts",
     "./capabilities/server": "./src/capabilities/server.ts",
@@ -54,6 +57,7 @@
     "./cli/capabilities": "./src/cli/capabilities.ts",
     "./cli/admin": "./src/cli/admin/index.ts",
     "./shared": "./src/shared/index.ts",
+    "./shared-text": "./src/shared-text/index.ts",
     "./services": "./src/services/index.ts",
     "./services/image-metadata": "./src/services/image-metadata.ts",
     "./services/document-extraction": "./src/services/document-extraction.ts",
@@ -103,13 +107,14 @@
     "@firecrawl/anydoc": "0.2.4",
     "@napi-rs/canvas": "1.0.9",
     "pdfjs-dist": "6.3.289",
+    "sharp": "0.35.4",
     "@simplewebauthn/server": "14.0.3",
     "@tabler/icons": "3.48.0",
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.18.0",
-    "@k2b/ssr": "0.17.0",
-    "@k2b/ui": "0.28.0",
-    "@k2b/stdlib": "0.29.0",
+    "@k2b/ssr": "0.18.0",
+    "@k2b/ui": "0.30.0",
+    "@k2b/stdlib": "0.30.0",
     "@k2b/sync": "7.0.0",
     "@nats-io/jetstream": "3.4.0",
     "@nats-io/transport-node": "3.4.0",
@@ -122,6 +127,7 @@
     "liquidjs": "10.29.0",
     "marked": "18.0.14",
     "mermaid": "12.0.0",
+    "mmdb-lib": "3.0.3",
     "nodemailer": "10.0.10",
     "postcss": "8.5.28",
     "reflect-metadata": "0.2.2",
@@ -131,6 +137,7 @@
     "web-push": "3.6.7",
     "web-vitals": "6.2.2",
     "yaml": "2.9.1",
+    "yjs": "13.6.33",
     "hash-wasm": "4.12.0",
     "@types/sanitize-html": "2.16.1",
     "@types/web-push": "3.6.4"
@@ -141,7 +148,7 @@
     "@types/bun": "1.4.2",
     "babel-preset-solid": "1.9.15",
     "hono": "4.13.9",
-    "playwright": "1.63.0",
+    "playwright": "1.64.1",
     "solid-js": "1.9.15",
     "typescript": "7.0.2",
     "zod": "4.6.5"

package/scripts/build-canvas-workers.ts

@@ -1,58 +1,138 @@
-import { cp, mkdir } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { cp, mkdir, realpath } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
+import { readImageRecords } from "../src/services/pdf/image-protocol";
 
-/** Isolated native canvas workers, each packaged only when the server bundle reaches the module that starts it. */
 const CANVAS_WORKERS = [
-  { reachedBy: "/ai/pdf-render.ts", entry: "src/ai/pdf-render-worker.ts", output: "pdf-worker.js", packages: ["pdfjs-dist"] },
   {
-    reachedBy: "/services/branding/app-icons.ts",
+    define: "__CLOUD_PDF_RENDER_WORKER__",
+    entry: "src/ai/pdf-render-worker.ts",
+    output: "pdf-worker.js",
+    packages: ["@napi-rs/canvas", "pdfjs-dist"],
+  },
+  {
+    define: "__CLOUD_ICON_RENDER_WORKER__",
     entry: "src/services/branding/icon-render-worker.ts",
     output: "icon-worker.js",
-    packages: [],
+    packages: ["@napi-rs/canvas"],
   },
+  { define: "__CLOUD_PDF_IMAGE_WORKER__", entry: "src/services/pdf/image-worker.ts", output: "image-worker.js", packages: ["sharp"] },
 ] as const;
 
+/** Server bundle defines: each caller starts its worker from `canvas/` next to `server.js`. */
+export const CANVAS_WORKER_DEFINES = Object.fromEntries(
+  CANVAS_WORKERS.map((worker) => [worker.define, JSON.stringify(`./canvas/${worker.output}`)]),
+);
+
+const Manifest = z.object({
+  version: z.string(),
+  dependencies: z.record(z.string(), z.string()).default({}),
+  optionalDependencies: z.record(z.string(), z.string()).default({}),
+  os: z.array(z.string()).optional(),
+  cpu: z.array(z.string()).optional(),
+  libc: z.array(z.string()).optional(),
+});
+const matches = (values: string[] | undefined, target: string) =>
+  !values || (!values.includes(`!${target}`) && (values.every((value) => value.startsWith("!")) || values.includes(target)));
+
 /**
- * Writes `dist/canvas/<worker>.js` for every canvas worker the bundle needs, with one copy of `@napi-rs/canvas`, its
- * installed platform binary and the workers' other packages in `dist/canvas/node_modules`.
+ * Bundle each reached native worker with only its runtime packages external. Copy their real dependency closures flat,
+ * dereferenced and filtered by OS, CPU and libc; reject version collisions and missing native binaries. Smoke-test sharp
+ * in the packaged subprocess so the build proves that its native closure loads on this architecture.
  */
-export async function buildCanvasWorkers(dist: string, bundledInputs: readonly string[]) {
-  const workers = CANVAS_WORKERS.filter((worker) => bundledInputs.some((path) => path.endsWith(worker.reachedBy)));
+export async function buildCanvasWorkers(dist: string, serverCode: string) {
+  // A worker ships only when the server code still contains its path, which only the code that starts it carries.
+  // Metafile inputs also list tree-shaken modules, and a retained module binding contributes bytes without its caller.
+  const workers = CANVAS_WORKERS.filter((worker) => serverCode.includes(`./canvas/${worker.output}`));
   if (workers.length === 0) return;
   const framework = resolve(dirname(fileURLToPath(import.meta.url)), "..");
   const out = resolve(dist, "canvas");
   await mkdir(out, { recursive: true });
-  const external = ["@napi-rs/canvas", ...workers.flatMap((worker) => worker.packages)];
   for (const worker of workers) {
     const build = await Bun.build({
       entrypoints: [resolve(framework, worker.entry)],
       target: "bun",
       outdir: out,
       naming: worker.output,
-      external,
+      external: [...worker.packages],
     });
-    if (!build.success) throw new Error(`Canvas worker ${worker.output} build failed: ${build.logs.join("\n")}`);
+    if (!build.success) throw new Error(`Native worker ${worker.output} build failed: ${build.logs.join("\n")}`);
   }
-  for (const name of external) {
-    const source = dirname(Bun.resolveSync(`${name}/package.json`, framework));
-    await cp(source, resolve(out, "node_modules", name), { recursive: true, dereference: true });
-    if (name !== "@napi-rs/canvas") continue;
-    const manifest = z
-      .object({ optionalDependencies: z.record(z.string(), z.string()) })
-      .parse(await Bun.file(resolve(source, "package.json")).json());
+  const libc = z.object({ header: z.object({ glibcVersionRuntime: z.string().optional() }) }).parse(process.report.getReport()).header
+    .glibcVersionRuntime
+    ? "glibc"
+    : "musl";
+  const copied = new Map<string, string>();
+  const copyPackage = async (name: string, dependent: string, optional = false): Promise<boolean> => {
+    let source: string;
+    try {
+      source = await realpath(dirname(Bun.resolveSync(`${name}/package.json`, dependent)));
+    } catch (error) {
+      if (optional) return false;
+      throw error;
+    }
+    const manifest = Manifest.parse(await Bun.file(resolve(source, "package.json")).json());
+    if (!matches(manifest.os, process.platform) || !matches(manifest.cpu, process.arch) || !matches(manifest.libc, libc)) {
+      if (optional) return false;
+      throw new Error(`Native worker dependency ${name} does not support the build platform.`);
+    }
+    const existing = copied.get(name);
+    if (existing) {
+      if (existing !== manifest.version)
+        throw new Error(`Native worker dependency collision: ${name} ${existing} and ${manifest.version}.`);
+      return true;
+    }
+    copied.set(name, manifest.version);
+    await cp(source, resolve(out, "node_modules", name), {
+      recursive: true,
+      dereference: true,
+      filter: (path) => basename(path) !== "node_modules",
+    });
+    for (const dependency of Object.keys(manifest.dependencies)) {
+      if (dependency in manifest.optionalDependencies) continue;
+      await copyPackage(dependency, source);
+    }
     let nativePackages = 0;
     for (const dependency of Object.keys(manifest.optionalDependencies)) {
-      let location: string;
-      try {
-        location = dirname(Bun.resolveSync(`${dependency}/package.json`, source));
-      } catch {
-        continue;
-      } // Only the installed target-platform binary is needed.
-      await cp(location, resolve(out, "node_modules", dependency), { recursive: true, dereference: true });
-      nativePackages++;
+      if (await copyPackage(dependency, source, true)) {
+        if (
+          (name === "sharp" && dependency.startsWith("@img/sharp-") && !dependency.startsWith("@img/sharp-libvips-")) ||
+          (name === "@napi-rs/canvas" && dependency.startsWith("@napi-rs/canvas-"))
+        )
+          nativePackages++;
+      }
+    }
+    if ((name === "sharp" || name === "@napi-rs/canvas") && !nativePackages) {
+      throw new Error(`Native workers need an installed ${name} binary for the build platform.`);
+    }
+    return true;
+  };
+  for (const name of new Set(workers.flatMap((worker) => [...worker.packages]))) await copyPackage(name, framework);
+  if (workers.some((worker) => worker.output === "image-worker.js")) await smokeImageWorker(resolve(out, "image-worker.js"));
+}
+
+async function smokeImageWorker(entry: string) {
+  // A fixed 2x2 RGBA PNG; the build process never loads sharp.
+  const png = Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAEUlEQVR4nGP4z8DQAMIMMAYAOOgF/REzMMkAAAAASUVORK5CYII=", "base64");
+  const child = Bun.spawn([process.execPath, "--no-env-file", entry], {
+    stdin: new Blob([
+      `${JSON.stringify({ bytes: png.byteLength, boxes: [{ width: 2, height: 2 }], maxBytes: 4096, timeoutMs: 10_000 })}\n`,
+      png,
+    ]),
+    stdout: "pipe",
+    stderr: "ignore",
+    env: { PATH: process.env.PATH },
+  });
+  const timer = setTimeout(() => child.kill("SIGKILL"), 15_000);
+  try {
+    const result = await readImageRecords(child.stdout, { boxes: [{ width: 2, height: 2 }], maxBytes: 4096 });
+    if ((await child.exited) !== 0 || !result.ok || result.variants.length !== 1 || !result.variants[0]) {
+      throw new Error("Packaged image worker could not convert its PNG: sharp's native dependency closure is incomplete or unusable.");
     }
-    if (!nativePackages) throw new Error("Canvas workers need an installed native canvas binary for the build platform.");
+  } finally {
+    clearTimeout(timer);
+    child.kill("SIGKILL");
+    await child.exited;
   }
 }

package/scripts/build.ts

@@ -35,7 +35,7 @@ import tailwind from "bun-plugin-tailwind";
 import type { AppCliModules } from "../src/contracts/app";
 import { writeAppFavicon } from "./app-favicon";
 import { buildBrowserPerformance } from "./browser-performance";
-import { buildCanvasWorkers } from "./build-canvas-workers";
+import { buildCanvasWorkers, CANVAS_WORKER_DEFINES } from "./build-canvas-workers";
 
 const appId = process.env.APP_ID;
 if (!appId) throw new Error("APP_ID env var required");
@@ -127,13 +127,11 @@ try {
     naming: "server.js",
     target: "bun",
     minify: true,
-    metafile: true,
     define: {
       __CLOUD_VERSION__: JSON.stringify(version),
       __CLOUD_RELEASE__: JSON.stringify(release),
       __CLOUD_SYNC_VERSION__: JSON.stringify(syncVersion),
-      __CLOUD_PDF_RENDER_WORKER__: JSON.stringify("./canvas/pdf-worker.js"),
-      __CLOUD_ICON_RENDER_WORKER__: JSON.stringify("./canvas/icon-worker.js"),
+      ...CANVAS_WORKER_DEFINES,
       __CLOUD_APP_ASSETS__: JSON.stringify("./assets/"),
       __CLOUD_CLI_PLUGINS__: JSON.stringify("./cli/"),
     },
@@ -146,7 +144,7 @@ if (!server.success) {
   for (const m of server.logs) console.error(m);
   throw new Error("Server bundle failed");
 }
-await buildCanvasWorkers(dist, Object.keys(server.metafile?.inputs ?? {}));
+await buildCanvasWorkers(dist, await Bun.file(resolve(dist, "server.js")).text());
 
 // 2. Per-app Tailwind stylesheet.
 const appCss = resolve(appDir, "src/styles/app.css");

package/src/_internal/app-favicon.ts

@@ -1,2 +1,4 @@
-export const appFaviconHref = (appId: string, version: number): string =>
-  appId === "core" ? "/branding/favicon" : `/public/${appId}/favicon.svg?v=${version}`;
+export const appFaviconHref = (appId: string, version: string | number | undefined): string =>
+  appId === "core"
+    ? "/branding/favicon"
+    : `/public/${appId}/favicon.svg${version === undefined ? "" : `?v=${encodeURIComponent(version)}`}`;

package/src/_internal/app-path.ts

@@ -0,0 +1,25 @@
+/** An absolute path on the current origin: one leading slash, no backslash or whitespace. */
+export const SAME_ORIGIN_PATH = /^\/(?![\/\\])[^\\\s]*$/;
+
+/** A route as the gateway reads it: trimmed and without empty segments, so `//pwa/x/` is `/pwa/x`. */
+export const canonicalRoute = (route: string): string => {
+  const trimmed = route.trim();
+  return trimmed.startsWith("/") ? `/${trimmed.split("/").filter(Boolean).join("/")}` : trimmed;
+};
+
+/**
+ * Whether an application path stays below one of the app's own `routes`. It is
+ * checked on the path the browser actually requests, after dot segments, and
+ * never starts with `//`, which a URL resolver reads as another host.
+ */
+export const isOwnAppPath = (href: string, routes: readonly string[]): boolean => {
+  if (!SAME_ORIGIN_PATH.test(href)) return false;
+  const path = new URL(href, "https://cloud.invalid").pathname;
+  return (
+    !path.startsWith("//") &&
+    routes.some((route) => {
+      const prefix = canonicalRoute(route);
+      return prefix === "/" || path === prefix || path.startsWith(`${prefix}/`);
+    })
+  );
+};

package/src/_internal/app-presentation.ts

@@ -92,7 +92,11 @@ export const compileAppPresentation = (app: AppMeta, catalog: AppPresentationCat
     if (!canonical) throw new Error(`App presentation locale ${JSON.stringify(locale)} is not a valid BCP 47 locale`);
     if (canonical === baseLocale) throw new Error(`App presentation translations must not repeat base locale ${baseLocale}`);
     if (translations[canonical]) throw new Error(`App presentation locale ${canonical} is duplicated after canonicalization`);
+    if (translation.panelLabel !== undefined && !app.panel) {
+      throw new Error(`${canonical}.panelLabel contains unknown key "panel"`);
+    }
     translations[canonical] = {
+      ...(translation.panelLabel !== undefined ? { panelLabel: text(translation.panelLabel, `${canonical}.panelLabel`) } : {}),
       ...(translation.name !== undefined ? { name: text(translation.name, `${canonical}.name`) } : {}),
       ...(translation.description !== undefined
         ? { description: text(translation.description, `${canonical}.description`, MAX_DESCRIPTION) }

package/src/_internal/canvas-worker.ts

@@ -1,24 +1,26 @@
 import { fileURLToPath } from "node:url";
 
 /**
- * Starts a native canvas worker (PDF pages, app icons) in a process of its own. RLIMIT_DATA bounds the decoder heap
+ * Starts a native worker (PDF pages, app icons, print images) in a process of its own. RLIMIT_DATA bounds the decoder heap
  * and native writable mappings on Linux. Positional arguments keep paths out of shell code; no elevated privileges.
  * The caller owns the deadline and kills the process on abort.
  */
-export const spawnCanvasWorker = (worker: URL, name: string, input: string) =>
+export const spawnCanvasWorker = (worker: URL, name: string, input: string | Blob) =>
   Bun.spawn(["/bin/sh", "-c", 'ulimit -d 524288 || exit 70; exec "$@"', name, process.execPath, "--no-env-file", fileURLToPath(worker)], {
     stdin: new Blob([input]),
     stdout: "pipe",
     stderr: "ignore",
     // No application credentials or configuration reach the decoder, only fixed
-    // thread pool sizes: the Bun work pool, canvas tokio runtime, and JSC GC
+    // runtime settings: the Bun work pool, canvas tokio runtime, and JSC GC
     // markers otherwise grow with the host's cores, and RLIMIT_DATA also counts
     // each thread's stack and allocator memory.
+    // Bun's allocator otherwise commits whole arenas up front, which RLIMIT_DATA counts as used.
     env: {
       PATH: process.env.PATH,
       LANG: "C.UTF-8",
       UV_THREADPOOL_SIZE: "2",
       TOKIO_WORKER_THREADS: "2",
       BUN_JSC_numberOfGCMarkers: "2",
+      MIMALLOC_ARENA_EAGER_COMMIT: "0",
     },
   });

package/src/_internal/capabilities.ts

@@ -1,4 +1,7 @@
-import { createHash } from "node:crypto";
+import { capabilityHash, projectSchema, stableJsonValue } from "./capability-schemas";
+
+export { capabilityHash } from "./capability-schemas";
+
 import { isServiceError, type Result, type ServiceError } from "@k2b/stdlib";
 import { z } from "zod";
 import {
@@ -8,8 +11,8 @@ import {
   CAPABILITY_PROTOCOL_VERSION,
   type CapabilityActionDefinition,
   type CapabilityActionManifest,
+  CapabilityActionPolicySchema,
   type CapabilityActionReviewResult,
-  CapabilityActionReviewSchema,
   type CapabilityActionSentences,
   type CapabilityCommandDefinition,
   type CapabilityCommandManifest,
@@ -33,12 +36,14 @@ import {
   type CapabilitySearchTagDefinition,
   type CapabilityStreamDefinition,
   type CapabilityUniversalSearchDefinition,
+  capabilityActionPolicy,
   capabilityResultSchema,
   UniversalSearchDataSchema,
   UniversalSearchInputSchema,
 } from "../contracts/capabilities";
 import { fileProviderIssues } from "../contracts/file-provider";
 import { canonicalLocale, localeFallbackChain, normalizeLocale } from "../shared/locale";
+import { capabilityActionReceiptIssues, capabilityActionReviewIssues, capabilityQueryChecksActionOutcome } from "./capability-reviews";
 import {
   CAPABILITY_SENTENCE_KEYS,
   CAPABILITY_SENTENCE_MAX_CHARS,
@@ -94,6 +99,7 @@ const ACTION_FIELDS = {
   stream: true,
   idempotency: true,
   approval: true,
+  policy: true,
   review: true,
   run: true,
 } satisfies DefinedFields<CapabilityActionDefinition>;
@@ -221,21 +227,6 @@ export const serializeCapabilityProviderResult = (
   return { body: JSON.stringify(fallback), status: options.nonIdempotentAction ? 502 : 500 };
 };
 
-const stableJsonValue = (value: unknown): unknown => {
-  if (Array.isArray(value)) return value.map(stableJsonValue);
-  if (typeof value !== "object" || value === null) return value;
-  return Object.fromEntries(
-    Object.entries(value as Record<string, unknown>)
-      .sort(([left], [right]) => left.localeCompare(right))
-      .map(([key, entry]) => [key, stableJsonValue(entry)]),
-  );
-};
-
-export const capabilityHash = (value: unknown): string =>
-  createHash("sha256")
-    .update(JSON.stringify(stableJsonValue(value)))
-    .digest("hex");
-
 const assertText = (value: string, label: string, max: number): void => {
   if (!value.trim()) throw new Error(`${label} is required`);
   if (value.length > max) throw new Error(`${label} must be at most ${max} characters`);
@@ -338,12 +329,12 @@ const compileOperationPresentation = (
   operation: CapabilityQueryManifest | CapabilityActionManifest | CapabilityCommandManifest,
   label: string,
   strict = true,
-): CapabilityOperationPresentationTranslation => {
+): CapabilityOperationPresentationTranslation & { keywords?: readonly string[] } => {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
   const translation = value as Record<string, unknown>;
   const allowed = new Set(
     "path" in operation
-      ? ["title", "description", "input"]
+      ? ["title", "description", "input", "keywords"]
       : ["title", "description", "input", "data", "searchTags", ...(isAction(operation) ? ["sentences"] : [])],
   );
   const extra = Object.keys(translation).find((key) => !allowed.has(key));
@@ -356,6 +347,10 @@ const compileOperationPresentation = (
     if (typeof translation.description !== "string") throw new Error(`${label}.description must be text`);
     assertText(translation.description, `${label}.description`, 1000);
   }
+  const keywords =
+    "path" in operation && translation.keywords !== undefined
+      ? CapabilityCommandManifestSchema.shape.keywords.parse(translation.keywords)
+      : undefined;
   let searchTags: CapabilityOperationPresentationTranslation["searchTags"];
   const universalSearch = "universalSearch" in operation ? operation.universalSearch : undefined;
   // A reader skips search-tag copy for an operation without Universal Search instead of losing its other copy.
@@ -398,6 +393,7 @@ const compileOperationPresentation = (
   return {
     ...(typeof translation.title === "string" ? { title: translation.title.trim() } : {}),
     ...(typeof translation.description === "string" ? { description: translation.description.trim() } : {}),
+    ...(keywords ? { keywords } : {}),
     ...(input ? { input } : {}),
     ...(data ? { data } : {}),
     ...(searchTags ? { searchTags } : {}),
@@ -517,17 +513,6 @@ export const compileCapabilityPresentation = (
   return { baseLocale, ...(sentences && Object.keys(sentences).length > 0 ? { sentences } : {}), translations };
 };
 
-const projectSchema = (schema: z.ZodType, label: string, io: "input" | "output"): JsonSchema => {
-  try {
-    const projected = z.toJSONSchema(schema, { io }) as JsonSchema;
-    z.fromJSONSchema(projected);
-    return projected;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`${label} is not JSON-Schema-round-trippable: ${message}`);
-  }
-};
-
 const assertPropertyDescriptions = (schema: unknown, label: string, path: readonly string[] = []): void => {
   if (!schema || typeof schema !== "object" || Array.isArray(schema)) return;
   const value = schema as Record<string, unknown>;
@@ -720,6 +705,20 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
     const label = `Action ${localId}`;
     assertDefinedFields(definition, ACTION_FIELDS, label);
     assertDefinedStreamFields(definition.stream, label);
+    if (definition.policy !== undefined) {
+      const parsedPolicy = CapabilityActionPolicySchema.safeParse(definition.policy);
+      if (!parsedPolicy.success) throw new Error(`${label} has invalid policy: ${parsedPolicy.error.message}`);
+      if (definition.approval !== undefined) throw new Error(`${label} policy and approval are mutually exclusive`);
+      if (!definition.review) throw new Error(`${label} policy requires review()`);
+      if ("silent" in parsedPolicy.data && (definition.destructive || definition.openWorld))
+        throw new Error(`${label} destructive or open-world policy must ask`);
+      if (
+        "ask" in parsedPolicy.data &&
+        (parsedPolicy.data.ask === "sends" || parsedPolicy.data.ask === "deletes") &&
+        definition.idempotency !== "required"
+      )
+        throw new Error(`${label} sends or deletes policy requires idempotency: "required"`);
+    }
     // Declaration rule, documented in docs/platform/capabilities.md:
     // destructive means irreversible or externally visible. An irreversible or
     // open-world effect must always be reviewable and safely repeatable, and
@@ -767,7 +766,13 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
       destructive: definition.destructive,
       openWorld: definition.openWorld,
       idempotency: definition.idempotency,
-      ...(definition.approval ? { approval: definition.approval } : {}),
+      ...(definition.policy
+        ? "silent" in definition.policy
+          ? { approval: "rememberable" as const }
+          : {}
+        : definition.approval
+          ? { approval: definition.approval }
+          : {}),
       ...(definition.review ? { review: true as const } : {}),
     } satisfies CapabilityActionManifest;
     actions.set(localId, {
@@ -795,6 +800,9 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
       });
     });
 
+  const policies = Object.fromEntries(
+    [...actions].flatMap(([localId, action]) => (action.definition.policy ? [[localId, action.definition.policy]] : [])),
+  );
   const fileProvider = definitions.fileProvider;
   const manifestBase = {
     protocolVersion: CAPABILITY_PROTOCOL_VERSION,
@@ -803,6 +811,7 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
     queries: [...queries.values()].map((entry) => entry.manifest),
     actions: [...actions.values()].map((entry) => entry.manifest),
     commands,
+    ...(Object.keys(policies).length ? { policies } : {}),
     // Omitted when unused so manifests without a provider keep their earlier hash.
     ...(fileProvider
       ? { fileProvider: { list: fileProvider.list, read: fileProvider.read, ...(fileProvider.save ? { save: fileProvider.save } : {}) } }
@@ -954,6 +963,7 @@ export const resolveCapabilityManifestPresentation = (
               title: copy.title ?? operation.title,
               description: copy.description ?? operation.description,
               inputSchema: applySchemaPresentation(operation.inputSchema, copy.input),
+              keywords: copy.keywords ? [...copy.keywords] : operation.keywords,
             }
           : operation;
       }),
@@ -970,6 +980,7 @@ export const resolveCapabilityManifestPresentation = (
           : operation;
       }),
       ...(current.fileProvider ? { fileProvider: current.fileProvider } : {}),
+      ...(current.policies ? { policies: current.policies } : {}),
     };
     current = CapabilityManifestSchema.parse({ ...manifestBase, manifestHash: capabilityHash(manifestBase) });
   }
@@ -1213,6 +1224,15 @@ const resultRefs = (result: unknown): Array<{ type: string; id: string }> => {
   }>;
 };
 
+const compiledReviewContext = (compiled: CompiledCapabilities, localId: string) => ({
+  policy: capabilityActionPolicy(compiled.manifest, localId),
+  approval: compiled.actions.get(localId)?.manifest.approval,
+  queries: compiled.manifest.queries,
+  validateQueryInput: (query: CapabilityQueryManifest, input: Record<string, unknown>) =>
+    compiled.queries.get(query.localId)?.definition.input.safeParse(input).success === true,
+  ...(compiled.presentation ? { locales: [compiled.presentation.baseLocale, ...Object.keys(compiled.presentation.translations)] } : {}),
+});
+
 export const validateCapabilityResult = (
   compiled: CompiledCapabilities,
   operation: CompiledCapabilityQuery | CompiledCapabilityAction,
@@ -1220,12 +1240,25 @@ export const validateCapabilityResult = (
   onInvalidResult?: (error: unknown) => void,
 ): Result<unknown, ServiceError> => {
   const parsed = operation.resultSchema.safeParse(result);
-  if (!parsed.success) {
+  const field = (value: unknown, key: string): unknown =>
+    value !== null && typeof value === "object" ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
+  const receipt = field(result, "receipt");
+  const links = field(result, "links");
+  const receiptIssues =
+    receipt === undefined
+      ? []
+      : "idempotency" in operation.manifest
+        ? capabilityActionReceiptIssues(receipt, links)
+        : ["Queries cannot return a receipt"];
+  const nestedReceipt = field(field(result, "data"), "receipt");
+  if (!("idempotency" in operation.manifest) && nestedReceipt !== undefined && capabilityQueryChecksActionOutcome(operation.manifest))
+    receiptIssues.push(...capabilityActionReceiptIssues(nestedReceipt, links));
+  if (!parsed.success || receiptIssues.length > 0) {
     try {
       onInvalidResult?.(
         new Error(
           `Capability ${operation.manifest.localId} returned data outside its registered schema: ${JSON.stringify(
-            parsed.error.issues.map(({ code, path, message }) => ({ code, path, message })),
+            parsed.success ? receiptIssues : parsed.error.issues.map(({ code, path, message }) => ({ code, path, message })),
           )}`,
         ),
       );
@@ -1468,27 +1501,18 @@ export const reviewCompiledCapability = async (params: {
     if (!reviewed.ok) {
       return normalizeProviderError(reviewed.error, "Capability review returned an invalid error", params.onUnexpectedError);
     }
-    const parsed = CapabilityActionReviewSchema.safeParse(reviewed.data);
-    // A rememberable Action may leave out its scope for arguments that should ask every time; any other Action has none.
-    const approvalScopeIsValid =
-      parsed.success && (operation.manifest.approval === "rememberable" || parsed.data.approvalScope === undefined);
-    if (!parsed.success || !approvalScopeIsValid) {
+    const issues = capabilityActionReviewIssues(reviewed.data, compiledReviewContext(params.compiled, params.localId));
+    if (issues.length > 0) {
       try {
         params.onUnexpectedError?.(
-          new Error(
-            parsed.success
-              ? `Capability ${operation.manifest.localId} review returned an approval scope inconsistent with its manifest`
-              : `Capability ${operation.manifest.localId} review returned data outside its registered schema: ${JSON.stringify(
-                  parsed.error.issues.map(({ code, path, message }) => ({ code, path, message })),
-                )}`,
-          ),
+          new Error(`Capability ${operation.manifest.localId} review returned an invalid result: ${issues.join("; ")}`),
         );
       } catch {
-        // Observability must not change the public failure contract.
+        /* Observability must not change the public failure contract. */
       }
     }
-    return parsed.success && approvalScopeIsValid
-      ? { ok: true, data: parsed.data }
+    return issues.length === 0
+      ? { ok: true, data: reviewed.data }
       : {
           ok: false,
           error: {