@k2b/cloud 0.22.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -30,7 +30,7 @@
     "./server/*": "./src/server/*",
     "./browser": "./src/server/api-client.ts",
     "./browser/app-approval": "./src/browser/app-approval.ts",
-    "./browser/live": "./src/browser/live-websocket.ts",
+    "./browser/live": "./src/browser/live.ts",
     "./browser/mermaid": "./src/browser/mermaid.ts",
     "./browser/reload": "./src/browser/reload.ts",
     "./browser/notifications": "./src/browser/notifications.ts",
@@ -74,6 +74,7 @@
     "./contracts": "./src/contracts/index.ts",
     "./contracts/notifications": "./src/contracts/notification-types.ts",
     "./contracts/*": "./src/contracts/*",
+    "./events": "./src/events/index.ts",
     "./workflows": "./src/workflows/index.ts",
     "./workflows/ai": "./src/workflows/ai/index.ts",
     "./workflows/editor": "./src/workflows/editor.ts",
@@ -98,7 +99,7 @@
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.12.1",
     "@k2b/ssr": "0.14.0",
-    "@k2b/ui": "0.12.0",
+    "@k2b/ui": "0.14.0",
     "@k2b/stdlib": "0.27.0",
     "@k2b/sync": "7.0.0",
     "@nats-io/jetstream": "3.4.0",

package/scripts/README.md

@@ -2,7 +2,7 @@
 
 - `build.ts` — production build for one Cloud app (`APP_ID`); used by the Dockerfiles and `bun run build` targets.
 - `preload.ts` — dev-mode preload that registers the SSR plugin and builds CSS before app code loads.
-- `build-pdf-renderer.ts` — packages the PDF decoder and native assets for bundles that import PDF vision.
+- `build-canvas-workers.ts` — packages the isolated canvas workers (PDF pages, mobile app icons) and the native canvas for bundles that start them.
 - `app-favicon.ts` — generates app favicons from Tabler icons; imported by `build.ts` and `preload.ts`.
 - `browser-performance.ts` — bundles the web-vitals browser asset for core; imported by `build.ts` and `preload.ts`.
 - `runtime-recovery-acceptance.ts` — shared-runtime recovery acceptance on disposable Docker containers: `bun packages/cloud/scripts/runtime-recovery-acceptance.ts` (also `bun run test:runtime-recovery`).

package/scripts/build-canvas-workers.ts

@@ -0,0 +1,58 @@
+import { cp, mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+
+/** 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",
+    entry: "src/services/branding/icon-render-worker.ts",
+    output: "icon-worker.js",
+    packages: [],
+  },
+] as const;
+
+/**
+ * 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`.
+ */
+export async function buildCanvasWorkers(dist: string, bundledInputs: readonly string[]) {
+  const workers = CANVAS_WORKERS.filter((worker) => bundledInputs.some((path) => path.endsWith(worker.reachedBy)));
+  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,
+    });
+    if (!build.success) throw new Error(`Canvas 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());
+    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 (!nativePackages) throw new Error("Canvas workers need an installed native canvas binary for the build platform.");
+  }
+}

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 { buildPdfRenderer } from "./build-pdf-renderer";
+import { buildCanvasWorkers } from "./build-canvas-workers";
 
 const appId = process.env.APP_ID;
 if (!appId) throw new Error("APP_ID env var required");
@@ -132,7 +132,8 @@ try {
       __CLOUD_VERSION__: JSON.stringify(version),
       __CLOUD_RELEASE__: JSON.stringify(release),
       __CLOUD_SYNC_VERSION__: JSON.stringify(syncVersion),
-      __CLOUD_PDF_RENDER_WORKER__: JSON.stringify("./pdf-render/worker.js"),
+      __CLOUD_PDF_RENDER_WORKER__: JSON.stringify("./canvas/pdf-worker.js"),
+      __CLOUD_ICON_RENDER_WORKER__: JSON.stringify("./canvas/icon-worker.js"),
       __CLOUD_APP_ASSETS__: JSON.stringify("./assets/"),
       __CLOUD_CLI_PLUGINS__: JSON.stringify("./cli/"),
     },
@@ -145,9 +146,7 @@ if (!server.success) {
   for (const m of server.logs) console.error(m);
   throw new Error("Server bundle failed");
 }
-if (Object.keys(server.metafile?.inputs ?? {}).some((path) => path.endsWith("/ai/pdf-render.ts"))) {
-  await buildPdfRenderer(dist);
-}
+await buildCanvasWorkers(dist, Object.keys(server.metafile?.inputs ?? {}));
 
 // 2. Per-app Tailwind stylesheet.
 const appCss = resolve(appDir, "src/styles/app.css");

package/src/_internal/canvas-worker.ts

@@ -0,0 +1,24 @@
+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
+ * 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) =>
+  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
+    // markers otherwise grow with the host's cores, and RLIMIT_DATA also counts
+    // each thread's stack and allocator memory.
+    env: {
+      PATH: process.env.PATH,
+      LANG: "C.UTF-8",
+      UV_THREADPOOL_SIZE: "2",
+      TOKIO_WORKER_THREADS: "2",
+      BUN_JSC_numberOfGCMarkers: "2",
+    },
+  });

package/src/_internal/capabilities.ts

@@ -10,12 +10,14 @@ import {
   type CapabilityActionManifest,
   type CapabilityActionReviewResult,
   CapabilityActionReviewSchema,
+  type CapabilityCommandDefinition,
   type CapabilityCommandManifest,
   CapabilityCommandManifestSchema,
   type CapabilityDefinitions,
   type CapabilityError,
   CapabilityErrorSchema,
   type CapabilityExecutionContext,
+  type CapabilityFileProviderDeclaration,
   CapabilityIdempotencyKeySchema,
   type CapabilityInvocationResult,
   CapabilityLocalIdSchema,
@@ -26,15 +28,97 @@ import {
   type CapabilityPresentationTranslation,
   type CapabilityQueryDefinition,
   type CapabilityQueryManifest,
+  type CapabilityResourceTypeDefinition,
+  type CapabilitySearchTagDefinition,
+  type CapabilityStreamDefinition,
+  type CapabilityUniversalSearchDefinition,
   capabilityResultSchema,
   UniversalSearchDataSchema,
   UniversalSearchInputSchema,
 } from "../contracts/capabilities";
+import { fileProviderIssues } from "../contracts/file-provider";
 import { canonicalLocale, localeFallbackChain, normalizeLocale } from "../shared/locale";
 
 type JsonSchema = Record<string, unknown>;
 const MAX_CAPABILITY_MANIFEST_BYTES = 256 * 1024;
 
+/**
+ * The producer side of the shared manifest shape: an app registers exactly the fields and entries its
+ * release defines. Readers use `CapabilityManifestSchema`, which ignores what a newer release added.
+ */
+const StrictCapabilityManifestSchema = CapabilityManifestSchema.out.strict();
+
+/**
+ * Every declaration field this release defines, per kind. The compiler rejects any other field instead
+ * of dropping it: a declaration written for a newer release may restrict how an entry runs. Each list
+ * is typed as the complete key set, so a new declaration field does not compile until it is listed.
+ */
+type DefinedFields<T> = Readonly<Record<keyof T, true>>;
+const DECLARATION_FIELDS = {
+  protocolVersion: true,
+  presentation: true,
+  types: true,
+  queries: true,
+  actions: true,
+  commands: true,
+  fileProvider: true,
+} satisfies DefinedFields<CapabilityDefinitions>;
+const FILE_PROVIDER_FIELDS = { list: true, read: true, save: true } satisfies DefinedFields<CapabilityFileProviderDeclaration>;
+const TYPE_FIELDS = { title: true, description: true, icon: true, reader: true } satisfies DefinedFields<CapabilityResourceTypeDefinition>;
+const QUERY_FIELDS = {
+  title: true,
+  description: true,
+  input: true,
+  data: true,
+  openWorld: true,
+  stream: true,
+  universalSearch: true,
+  run: true,
+} satisfies DefinedFields<CapabilityQueryDefinition>;
+const ACTION_FIELDS = {
+  title: true,
+  description: true,
+  input: true,
+  data: true,
+  destructive: true,
+  openWorld: true,
+  stream: true,
+  idempotency: true,
+  approval: true,
+  review: true,
+  run: true,
+} satisfies DefinedFields<CapabilityActionDefinition>;
+const COMMAND_FIELDS = {
+  title: true,
+  description: true,
+  icon: true,
+  keywords: true,
+  input: true,
+  path: true,
+} satisfies DefinedFields<CapabilityCommandDefinition>;
+const UNIVERSAL_SEARCH_FIELDS = { tags: true, scopeTypes: true } satisfies DefinedFields<CapabilityUniversalSearchDefinition>;
+const SEARCH_TAG_FIELDS = {
+  tag: true,
+  title: true,
+  description: true,
+  aliases: true,
+} satisfies DefinedFields<CapabilitySearchTagDefinition>;
+const READ_STREAM_FIELDS = { direction: true, maxBytes: true, read: true } satisfies DefinedFields<
+  Extract<CapabilityStreamDefinition, { direction: "read" }>
+>;
+const WRITE_STREAM_FIELDS = { direction: true, maxBytes: true, write: true, status: true, abort: true } satisfies DefinedFields<
+  Extract<CapabilityStreamDefinition, { direction: "write" }>
+>;
+
+const assertDefinedFields = (definition: object, fields: object, label: string): void => {
+  const field = Object.keys(definition).find((key) => !Object.hasOwn(fields, key));
+  if (field) throw new Error(`${label} contains unsupported field "${field}"`);
+};
+
+const assertDefinedStreamFields = (stream: CapabilityStreamDefinition | undefined, label: string): void => {
+  if (stream) assertDefinedFields(stream, stream.direction === "write" ? WRITE_STREAM_FIELDS : READ_STREAM_FIELDS, `${label} stream`);
+};
+
 export type CompiledCapabilityQuery = {
   definition: CapabilityQueryDefinition;
   manifest: CapabilityQueryManifest;
@@ -194,6 +278,7 @@ const compileOperationPresentation = (
   value: unknown,
   operation: CapabilityQueryManifest | CapabilityActionManifest | CapabilityCommandManifest,
   label: string,
+  strict = true,
 ): CapabilityOperationPresentationTranslation => {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
   const translation = value as Record<string, unknown>;
@@ -201,7 +286,7 @@ const compileOperationPresentation = (
     "path" in operation ? ["title", "description", "input"] : ["title", "description", "input", "data", "searchTags"],
   );
   const extra = Object.keys(translation).find((key) => !allowed.has(key));
-  if (extra) throw new Error(`${label} contains unsupported field "${extra}"`);
+  if (strict && extra) throw new Error(`${label} contains unsupported field "${extra}"`);
   if (translation.title !== undefined) {
     if (typeof translation.title !== "string") throw new Error(`${label}.title must be text`);
     assertText(translation.title, `${label}.title`, 120);
@@ -211,12 +296,14 @@ const compileOperationPresentation = (
     assertText(translation.description, `${label}.description`, 1000);
   }
   let searchTags: CapabilityOperationPresentationTranslation["searchTags"];
-  if (translation.searchTags !== undefined) {
-    if (!("universalSearch" in operation) || !operation.universalSearch) throw new Error(`${label}.searchTags requires Universal Search`);
+  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.
+  if (translation.searchTags !== undefined && (strict || universalSearch)) {
+    if (!universalSearch) throw new Error(`${label}.searchTags requires Universal Search`);
     if (!translation.searchTags || typeof translation.searchTags !== "object" || Array.isArray(translation.searchTags)) {
       throw new Error(`${label}.searchTags must be an object`);
     }
-    const tags = new Map(operation.universalSearch.tags.map((tag) => [tag.tag, tag]));
+    const tags = new Map(universalSearch.tags.map((tag) => [tag.tag, tag]));
     searchTags = Object.fromEntries(
       Object.entries(translation.searchTags as Record<string, unknown>).map(([tag, presentation]) => {
         if (!tags.has(tag)) throw new Error(`${label}.searchTags references unknown stable tag "${tag}"`);
@@ -225,7 +312,7 @@ const compileOperationPresentation = (
         }
         const copy = presentation as Record<string, unknown>;
         const extraField = Object.keys(copy).find((key) => key !== "title" && key !== "description");
-        if (extraField) throw new Error(`${label}.searchTags.${tag} contains unsupported field "${extraField}"`);
+        if (strict && extraField) throw new Error(`${label}.searchTags.${tag} contains unsupported field "${extraField}"`);
         if (copy.title !== undefined) {
           if (typeof copy.title !== "string") throw new Error(`${label}.searchTags.${tag}.title must be text`);
           assertText(copy.title, `${label}.searchTags.${tag}.title`, 120);
@@ -252,11 +339,21 @@ const compileOperationPresentation = (
   };
 };
 
-export const compileCapabilityPresentation = (manifest: CapabilityManifest, value: unknown): CapabilityPresentationCatalog | undefined => {
+/**
+ * Compiles human presentation for one manifest. A producer must declare exactly what its release
+ * supports. A reader of a registered manifest ignores fields from a newer release and skips the
+ * entry translations it cannot apply, such as those of left-out entries; presentation never grants access.
+ */
+export const compileCapabilityPresentation = (
+  manifest: CapabilityManifest,
+  value: unknown,
+  mode: "producer" | "reader" = "producer",
+): CapabilityPresentationCatalog | undefined => {
+  const strict = mode === "producer";
   if (value === undefined) return undefined;
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Capability presentation must be an object");
   const catalog = value as Record<string, unknown>;
-  if (Object.keys(catalog).some((key) => key !== "baseLocale" && key !== "translations")) {
+  if (strict && Object.keys(catalog).some((key) => key !== "baseLocale" && key !== "translations")) {
     throw new Error("Capability presentation contains unsupported fields");
   }
   const baseLocale = typeof catalog.baseLocale === "string" ? canonicalLocale(catalog.baseLocale) : undefined;
@@ -279,7 +376,7 @@ export const compileCapabilityPresentation = (manifest: CapabilityManifest, valu
     }
     const raw = rawTranslation as Record<string, unknown>;
     const extra = Object.keys(raw).find((key) => key !== "types" && key !== "queries" && key !== "actions" && key !== "commands");
-    if (extra) throw new Error(`Capability presentation translation ${canonical} contains unsupported field "${extra}"`);
+    if (strict && extra) throw new Error(`Capability presentation translation ${canonical} contains unsupported field "${extra}"`);
     const compileGroup = <T>(
       group: unknown,
       definitions: ReadonlyMap<string, T>,
@@ -289,10 +386,18 @@ export const compileCapabilityPresentation = (manifest: CapabilityManifest, valu
       if (group === undefined) return undefined;
       if (!group || typeof group !== "object" || Array.isArray(group)) throw new Error(`${kind} translations must be an object`);
       return Object.fromEntries(
-        Object.entries(group as Record<string, unknown>).map(([localId, entry]) => {
+        Object.entries(group as Record<string, unknown>).flatMap(([localId, entry]) => {
           const definition = definitions.get(localId);
-          if (!definition) throw new Error(`${kind} translation references unknown localId "${localId}"`);
-          return [localId, compile(entry, definition, `${kind} ${localId}`)];
+          if (!definition) {
+            if (strict) throw new Error(`${kind} translation references unknown localId "${localId}"`);
+            return [];
+          }
+          try {
+            return [[localId, compile(entry, definition, `${kind} ${localId}`)]];
+          } catch (error) {
+            if (strict) throw error;
+            return [];
+          }
         }),
       ) as Readonly<Record<string, never>>;
     };
@@ -300,7 +405,7 @@ export const compileCapabilityPresentation = (manifest: CapabilityManifest, valu
       if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new Error(`${label} must be an object`);
       const copy = entry as Record<string, unknown>;
       const extraField = Object.keys(copy).find((key) => key !== "title" && key !== "description");
-      if (extraField) throw new Error(`${label} contains unsupported field "${extraField}"`);
+      if (strict && extraField) throw new Error(`${label} contains unsupported field "${extraField}"`);
       if (copy.title !== undefined) {
         if (typeof copy.title !== "string") throw new Error(`${label}.title must be text`);
         assertText(copy.title, `${label}.title`, 120);
@@ -314,9 +419,11 @@ export const compileCapabilityPresentation = (manifest: CapabilityManifest, valu
         ...(copy.description ? { description: String(copy.description).trim() } : {}),
       };
     });
-    const translatedQueries = compileGroup(raw.queries, queries, "Query", compileOperationPresentation);
-    const translatedActions = compileGroup(raw.actions, actions, "Action", compileOperationPresentation);
-    const translatedCommands = compileGroup(raw.commands, commands, "Command", compileOperationPresentation);
+    const operationPresentation = (entry: unknown, operation: Parameters<typeof compileOperationPresentation>[1], label: string) =>
+      compileOperationPresentation(entry, operation, label, strict);
+    const translatedQueries = compileGroup(raw.queries, queries, "Query", operationPresentation);
+    const translatedActions = compileGroup(raw.actions, actions, "Action", operationPresentation);
+    const translatedCommands = compileGroup(raw.commands, commands, "Command", operationPresentation);
     translations[canonical] = {
       ...(translatedTypes ? { types: translatedTypes } : {}),
       ...(translatedQueries ? { queries: translatedQueries } : {}),
@@ -394,8 +501,10 @@ const assertLocalId = (localId: string, label: string): void => {
 
 const normalizeSearchTags = (definition: CapabilityQueryDefinition, label: string) => {
   if (!definition.universalSearch) return undefined;
+  assertDefinedFields(definition.universalSearch, UNIVERSAL_SEARCH_FIELDS, `${label} universalSearch`);
   const seen = new Set<string>();
   const tags = definition.universalSearch.tags.map((tag) => {
+    assertDefinedFields(tag, SEARCH_TAG_FIELDS, `${label} search tag ${tag.tag}`);
     assertText(tag.tag, `${label} search tag`, 64);
     assertText(tag.title, `${label} search tag title`, 120);
     assertText(tag.description, `${label} search tag description`, 500);
@@ -445,6 +554,8 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
   if (definitions.protocolVersion !== CAPABILITY_PROTOCOL_VERSION) {
     throw new Error(`Unsupported capability protocol version ${String(definitions.protocolVersion)}`);
   }
+  assertDefinedFields(definitions, DECLARATION_FIELDS, "Capability declaration");
+  if (definitions.fileProvider) assertDefinedFields(definitions.fileProvider, FILE_PROVIDER_FIELDS, "fileProvider");
 
   const localIds = new Set<string>();
   const registerLocalId = (localId: string, kind: string): void => {
@@ -457,6 +568,7 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
     .sort(([left], [right]) => left.localeCompare(right))
     .map(([localId, definition]) => {
       registerLocalId(localId, "Resource type");
+      assertDefinedFields(definition, TYPE_FIELDS, `Resource type ${localId}`);
       assertText(definition.title, `Resource type ${localId} title`, 120);
       assertText(definition.description, `Resource type ${localId} description`, 500);
       return {
@@ -473,6 +585,8 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
   for (const [localId, definition] of Object.entries(definitions.queries ?? {}).sort(([left], [right]) => left.localeCompare(right))) {
     registerLocalId(localId, "Query");
     const label = `Query ${localId}`;
+    assertDefinedFields(definition, QUERY_FIELDS, label);
+    assertDefinedStreamFields(definition.stream, label);
     if (
       definition.stream &&
       ((definition.stream.direction === "write" && !("idempotency" in definition)) || definition.stream.maxBytes <= 0)
@@ -521,6 +635,8 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
   for (const [localId, definition] of Object.entries(definitions.actions ?? {}).sort(([left], [right]) => left.localeCompare(right))) {
     registerLocalId(localId, "Action");
     const label = `Action ${localId}`;
+    assertDefinedFields(definition, ACTION_FIELDS, label);
+    assertDefinedStreamFields(definition.stream, label);
     // 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
@@ -582,6 +698,7 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
     .sort(([a], [b]) => a.localeCompare(b))
     .map(([localId, definition]) => {
       registerLocalId(localId, "Command");
+      assertDefinedFields(definition, COMMAND_FIELDS, `Command ${localId}`);
       const inputSchema = projectSchema(definition.input, `Command ${localId} input`, "input");
       assertClosedObjectInput(inputSchema, `Command ${localId} input`);
       return CapabilityCommandManifestSchema.parse({
@@ -595,6 +712,7 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
       });
     });
 
+  const fileProvider = definitions.fileProvider;
   const manifestBase = {
     protocolVersion: CAPABILITY_PROTOCOL_VERSION,
     appId,
@@ -602,11 +720,23 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
     queries: [...queries.values()].map((entry) => entry.manifest),
     actions: [...actions.values()].map((entry) => entry.manifest),
     commands,
+    // 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 } : {}) } }
+      : {}),
   };
-  const manifest = CapabilityManifestSchema.parse({
+  const manifest = StrictCapabilityManifestSchema.parse({
     ...manifestBase,
     manifestHash: capabilityHash(manifestBase),
   });
+  const providerIssues = fileProviderIssues(manifest);
+  if (providerIssues.length > 0) {
+    throw new Error(
+      `fileProvider does not match the file-provider contract:\n- ${providerIssues
+        .map((issue) => `${issue.function} (${issue.localId}) ${issue.path}: ${issue.message}`)
+        .join("\n- ")}`,
+    );
+  }
   const manifestBytes = new TextEncoder().encode(JSON.stringify(manifest)).byteLength;
   if (manifestBytes > MAX_CAPABILITY_MANIFEST_BYTES) {
     throw new Error(`Capability manifest exceeds the ${MAX_CAPABILITY_MANIFEST_BYTES}-byte registry limit`);
@@ -719,77 +849,102 @@ export const resolveCapabilityManifestPresentation = (
             }
           : operation;
       }),
+      ...(current.fileProvider ? { fileProvider: current.fileProvider } : {}),
     };
     current = CapabilityManifestSchema.parse({ ...manifestBase, manifestHash: capabilityHash(manifestBase) });
   }
   return current;
 };
 
-/** Validates an untrusted live manifest and recomputes every integrity hash. */
-export const parseCapabilityManifest = (value: unknown, expectedAppId: string): CapabilityManifest => {
-  const manifest = CapabilityManifestSchema.parse(value);
-  if (manifest.appId !== expectedAppId) throw new Error(`manifest appId must be ${expectedAppId}`);
+const passes = (check: () => void): boolean => {
+  try {
+    check();
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** Checks what the manifest schema cannot: that this release can call the operation as described. */
+const assertUsableOperation = (operation: CapabilityQueryManifest | CapabilityActionManifest): void => {
+  try {
+    z.fromJSONSchema(structuredClone(operation.inputSchema));
+    z.fromJSONSchema(structuredClone(operation.dataSchema));
+  } catch (error) {
+    throw new Error(
+      `Operation ${operation.localId} contains unsupported JSON Schema: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  assertClosedObjectInput(operation.inputSchema, `Operation ${operation.localId} input`);
+  if (operation.stream?.direction === "write" && (!("idempotency" in operation) || operation.idempotency !== "required")) {
+    throw new Error(`Operation ${operation.localId} write streams require an idempotent Action`);
+  }
+  const expectedSchemaHash = capabilityHash({
+    inputSchema: operation.inputSchema,
+    dataSchema: operation.dataSchema,
+    ...(operation.stream ? { stream: operation.stream } : {}),
+  });
+  if (operation.schemaHash !== expectedSchemaHash) throw new Error(`Operation ${operation.localId} schemaHash does not match its schemas`);
+  if ("universalSearch" in operation && operation.universalSearch) {
+    const expectedInput = projectSchema(UniversalSearchInputSchema, "Universal Search input", "input");
+    const expectedData = projectSchema(UniversalSearchDataSchema, "Universal Search data", "output");
+    if (
+      capabilityHash(operation.inputSchema) !== capabilityHash(expectedInput) ||
+      capabilityHash(operation.dataSchema) !== capabilityHash(expectedData)
+    ) {
+      throw new Error(`Operation ${operation.localId} advertises Universal Search with non-canonical schemas`);
+    }
+  }
+};
 
+const assertUsableCommand = (command: CapabilityCommandManifest): void => {
+  z.fromJSONSchema(structuredClone(command.inputSchema));
+  assertClosedObjectInput(command.inputSchema, `Command ${command.localId} input`);
+};
+
+/**
+ * Validates an untrusted live manifest and recomputes every integrity hash.
+ *
+ * The manifest as a whole must be intact: the app id, unique local IDs, and the manifest hash. That
+ * hash is checked against what the app sent, including everything ignored here, and stays the
+ * manifest's identity: the app's registry summary still matches, so the app is not treated as changed
+ * and a manifest without newer fields keeps its hash.
+ *
+ * Entries read like every reader reads them (`CapabilityManifestSchema`). An operation or Command this
+ * release cannot use as described, for example because it cannot read its JSON Schema, is left out the
+ * same way, together with what depends on it, and a Type whose reader Query does not take a single `id`
+ * keeps no reader. The app's other entries stay available.
+ */
+export const parseCapabilityManifest = (value: unknown, expectedAppId: string): CapabilityManifest => {
+  const sent = CapabilityManifestSchema.parse(value);
+  if (sent.appId !== expectedAppId) throw new Error(`manifest appId must be ${expectedAppId}`);
   const localIds = new Set<string>();
-  const registerLocalId = (localId: string, kind: string): void => {
+  for (const { localId } of [...sent.types, ...sent.queries, ...sent.actions, ...sent.commands]) {
     if (localIds.has(localId)) throw new Error(`localId ${localId} is declared more than once across Types, Queries, and Actions`);
     localIds.add(localId);
-    assertLocalId(localId, kind);
-  };
-  for (const type of manifest.types) registerLocalId(type.localId, "Resource type");
-  for (const operation of [...manifest.queries, ...manifest.actions]) {
-    registerLocalId(operation.localId, "Operation");
-    const inputSchema = structuredClone(operation.inputSchema);
-    const dataSchema = structuredClone(operation.dataSchema);
-    try {
-      z.fromJSONSchema(inputSchema);
-      z.fromJSONSchema(dataSchema);
-    } catch (error) {
-      throw new Error(
-        `Operation ${operation.localId} contains unsupported JSON Schema: ${error instanceof Error ? error.message : String(error)}`,
-      );
-    }
-    assertClosedObjectInput(inputSchema, `Operation ${operation.localId} input`);
-    if (operation.stream?.direction === "write" && (!("idempotency" in operation) || operation.idempotency !== "required")) {
-      throw new Error(`Operation ${operation.localId} write streams require an idempotent Action`);
-    }
-    const expectedSchemaHash = capabilityHash({
-      inputSchema: operation.inputSchema,
-      dataSchema: operation.dataSchema,
-      ...(operation.stream ? { stream: operation.stream } : {}),
-    });
-    if (operation.schemaHash !== expectedSchemaHash)
-      throw new Error(`Operation ${operation.localId} schemaHash does not match its schemas`);
-    if ("universalSearch" in operation && operation.universalSearch) {
-      for (const type of operation.universalSearch.scopeTypes ?? []) {
-        if (!manifest.types.some((entry) => entry.localId === type)) throw new Error(`Unknown search scope type ${type}`);
-      }
-      const expectedInput = projectSchema(UniversalSearchInputSchema, "Universal Search input", "input");
-      const expectedData = projectSchema(UniversalSearchDataSchema, "Universal Search data", "output");
-      if (
-        capabilityHash(operation.inputSchema) !== capabilityHash(expectedInput) ||
-        capabilityHash(operation.dataSchema) !== capabilityHash(expectedData)
-      ) {
-        throw new Error(`Operation ${operation.localId} advertises Universal Search with non-canonical schemas`);
-      }
-    }
-  }
-  for (const command of manifest.commands) {
-    registerLocalId(command.localId, "Command");
-    z.fromJSONSchema(structuredClone(command.inputSchema));
-    assertClosedObjectInput(command.inputSchema, `Command ${command.localId} input`);
-  }
-  const queries = new Map(manifest.queries.map((query) => [query.localId, query]));
-  for (const type of manifest.types) {
-    if (!type.reader) continue;
-    const reader = queries.get(type.reader);
-    if (!reader) throw new Error(`Resource type ${type.localId} reader ${type.reader} must name an existing Query`);
-    assertCanonicalReaderInput(reader.inputSchema, `Resource type ${type.localId} reader ${type.reader} input`);
   }
+  // The schema accepted `value`, so it is an object; hash all of it, not only what this release read.
+  const { manifestHash: _sentHash, ...sentBase } = value as Record<string, unknown>;
+  if (sent.manifestHash !== capabilityHash(sentBase)) throw new Error("manifestHash does not match the manifest");
 
-  const { manifestHash: _manifestHash, ...manifestBase } = manifest;
-  if (manifest.manifestHash !== capabilityHash(manifestBase)) throw new Error("manifestHash does not match the manifest");
-  return manifest;
+  // Reading the usable entries again leaves out what depends on an entry left out here.
+  const manifest = CapabilityManifestSchema.parse({
+    ...sent,
+    queries: sent.queries.filter((query) => passes(() => assertUsableOperation(query))),
+    actions: sent.actions.filter((action) => passes(() => assertUsableOperation(action))),
+    commands: sent.commands.filter((command) => passes(() => assertUsableCommand(command))),
+  });
+  const queries = new Map(manifest.queries.map((query) => [query.localId, query]));
+  return {
+    ...manifest,
+    types: manifest.types.map((type) => {
+      const reader = type.reader === undefined ? undefined : queries.get(type.reader);
+      if (!reader || passes(() => assertCanonicalReaderInput(reader.inputSchema, `Resource type ${type.localId} reader input`)))
+        return type;
+      const { reader: _unusable, ...withoutReader } = type;
+      return withoutReader;
+    }),
+  };
 };
 
 const schemaSemantics = (value: unknown): unknown => {