@k2b/cloud 0.22.0 → 0.24.0

package/src/browser/live-connection.ts

@@ -0,0 +1,211 @@
+import { type LiveServerMessage, LiveServerMessageSchema } from "../events/live-protocol";
+import { createLiveWebSocket, type LiveWebSocket } from "./live-websocket";
+
+export type LiveSubscriptionHandlers<T> = {
+  /** The cursor the server-rendered state belongs to; `null` starts at the current position. */
+  cursor: string | null;
+  /** Validates one event's data. A failure reloads the state through `resync`. */
+  parse: (data: unknown) => T;
+  /** Applies events in order. Idempotent: reconnects and retries can repeat an event. */
+  apply: (events: { data: T; cursor: string }[]) => Promise<void>;
+  /** Loads the canonical state again; events after it follow. */
+  resync: () => Promise<void>;
+  /** The subscription ended because its resource is gone or no longer readable. */
+  revoked?: (code: "not_found" | "access_denied") => void;
+  /** Live updates stopped: the session ended, or `apply` or `resync` kept failing. Never called after `close()`. */
+  unavailable: () => void;
+};
+
+export type LiveSubscription = { close: () => void };
+
+export type LiveConnection = {
+  subscribe: <T>(channel: string, scope: unknown, handlers: LiveSubscriptionHandlers<T>) => LiveSubscription;
+};
+
+type Subscriber = {
+  frame: () => unknown;
+  confirmed: boolean;
+  receive: (message: LiveServerMessage) => void;
+  end: () => void;
+};
+
+type Shared = { socket: LiveWebSocket; subscribers: Map<string, Subscriber>; next: number };
+
+const RETRY_DELAYS_MS = [1_000, 3_000, 9_000];
+const MAX_BATCH = 100;
+/** Events that may wait for `apply`; more collapse into one `resync`, which covers them. */
+const MAX_WAITING = 10 * MAX_BATCH;
+
+/** One socket per URL and page, shared by every subscription on it. */
+const shared = new Map<string, Shared>();
+
+const parseMessage = (raw: string): LiveServerMessage | null => {
+  try {
+    const parsed = LiveServerMessageSchema.safeParse(JSON.parse(raw));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+};
+
+const connect = (url: string, activity: "visible" | "always"): Shared => {
+  const subscribers = new Map<string, Subscriber>();
+  const socket = createLiveWebSocket<LiveServerMessage>({
+    url,
+    activity,
+    parse: parseMessage,
+    onOpen: (controls) => {
+      for (const subscriber of subscribers.values()) {
+        subscriber.confirmed = false;
+        controls.send(subscriber.frame());
+      }
+    },
+    onMessage: (message) => {
+      if (message.t === "progress") {
+        for (const subscriber of subscribers.values()) if (subscriber.confirmed) subscriber.receive(message);
+        return;
+      }
+      if (message.t !== "error") subscribers.get(message.id)?.receive(message);
+    },
+    onFatal: () => {
+      if (shared.get(url)?.socket === socket) shared.delete(url);
+      for (const subscriber of [...subscribers.values()]) subscriber.end();
+    },
+  });
+  return { socket, subscribers, next: 0 };
+};
+
+type Work<T> = { kind: "events"; events: { data: T; cursor: string }[] } | { kind: "mark" | "resync"; cursor: string };
+
+/**
+ * Subscribes to channels of an application's live socket (`/api/<app>/live`).
+ * Each subscription applies its events serially and moves its cursor only after
+ * `apply` resolved or at a server mark, so a reconnect resumes exactly there.
+ * Only `resync` reloads state; a returning tab replays what it missed.
+ */
+export const liveConnection = (url: string, options: { activity?: "visible" | "always" } = {}): LiveConnection => ({
+  subscribe: <T>(channel: string, scope: unknown, handlers: LiveSubscriptionHandlers<T>): LiveSubscription => {
+    let connection = shared.get(url);
+    if (!connection) {
+      connection = connect(url, options.activity ?? "visible");
+      shared.set(url, connection);
+    }
+    const { socket, subscribers } = connection;
+    const id = String(++connection.next);
+    let cursor = handlers.cursor;
+    /** The cursor of a `resync` that has not finished: a reconnect resumes after it. */
+    let resyncAt: string | null = null;
+    let ended = false;
+    let running = false;
+    const work: Work<T>[] = [];
+
+    const attempt = async (run: () => Promise<void>): Promise<boolean> => {
+      for (let tries = 0; ; tries++) {
+        try {
+          await run();
+          return true;
+        } catch {
+          const delay = RETRY_DELAYS_MS[tries];
+          if (delay === undefined || ended) return false;
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          if (ended) return false;
+        }
+      }
+    };
+
+    const drain = async () => {
+      if (running) return;
+      running = true;
+      try {
+        while (work.length > 0 && !ended) {
+          const item = work.shift() as Work<T>;
+          if (item.kind === "mark") {
+            cursor = item.cursor;
+            continue;
+          }
+          const applied = item.kind === "events" ? await attempt(() => handlers.apply(item.events)) : await attempt(handlers.resync);
+          if (!applied) {
+            // A closed subscription reports nothing: its owner ended it.
+            if (ended) return;
+            stop();
+            handlers.unavailable();
+            return;
+          }
+          cursor = item.kind === "events" ? (item.events.at(-1)?.cursor ?? cursor) : item.cursor;
+          if (item.kind === "resync" && resyncAt === item.cursor) resyncAt = null;
+        }
+      } finally {
+        running = false;
+      }
+    };
+
+    /** Work queued before a resync is covered by the reloaded state. */
+    const resync = (at: string) => {
+      work.length = 0;
+      work.push({ kind: "resync", cursor: at });
+      resyncAt = at;
+    };
+
+    const waiting = () => work.reduce((count, item) => count + (item.kind === "events" ? item.events.length : 0), 0);
+
+    const subscriber: Subscriber = {
+      frame: () => {
+        const after = resyncAt ?? cursor;
+        return { t: "sub", id, channel, scope, ...(after ? { after } : {}) };
+      },
+      confirmed: false,
+      receive: (message) => {
+        if (ended) return;
+        if (message.t === "revoked") {
+          stop();
+          handlers.revoked?.(message.code);
+          return;
+        }
+        if (message.t === "ready" || message.t === "progress") {
+          subscriber.confirmed = true;
+          work.push({ kind: "mark", cursor: message.cursor });
+        } else if (message.t === "resync") {
+          subscriber.confirmed = true;
+          resync(message.cursor);
+        } else if (message.t === "event") {
+          let data: T;
+          try {
+            data = handlers.parse(message.data);
+          } catch {
+            resync(message.cursor);
+            void drain();
+            return;
+          }
+          const last = work.at(-1);
+          if (waiting() >= MAX_WAITING) resync(message.cursor);
+          else if (last?.kind === "events" && last.events.length < MAX_BATCH) last.events.push({ data, cursor: message.cursor });
+          else work.push({ kind: "events", events: [{ data, cursor: message.cursor }] });
+        }
+        void drain();
+      },
+      end: () => {
+        if (ended) return;
+        stop();
+        handlers.unavailable();
+      },
+    };
+
+    const stop = () => {
+      if (ended) return;
+      ended = true;
+      work.length = 0;
+      if (subscribers.get(id) !== subscriber) return;
+      subscribers.delete(id);
+      socket.send({ t: "unsub", id });
+      if (subscribers.size === 0 && shared.get(url) === connection) {
+        shared.delete(url);
+        socket.dispose();
+      }
+    };
+
+    subscribers.set(id, subscriber);
+    if (subscribers.size === 1) socket.connect();
+    else socket.send(subscriber.frame());
+    return { close: stop };
+  },
+});

package/src/browser/live-websocket.ts

@@ -13,6 +13,13 @@ export type LiveWebSocketClose = {
 
 export type LiveWebSocketControls = {
   markApplied: (cursor: string | null | undefined) => void;
+  /**
+   * The cursor the current connection subscribed from: the last applied cursor
+   * when the socket opened. A server that confirms exactly this cursor resumes
+   * the stream after it, so the page needs no snapshot refresh. Any other
+   * cursor means events between the two were skipped.
+   */
+  subscribedCursor: () => string | null;
   /** Forget an expired cursor before resubscribing from a fresh snapshot. */
   resetCursor: () => void;
   send: (message: unknown) => boolean;
@@ -23,7 +30,8 @@ export type LiveWebSocketOptions<TMessage> = {
   url: string | (() => string);
   initialCursor?: string | null;
   activity?: LiveWebSocketActivity;
-  subscribe: (cursor: string | null) => unknown;
+  /** The subscription sent when a socket opens; omit it when `onOpen` sends the subscriptions. */
+  subscribe?: (cursor: string | null) => unknown;
   parse: (raw: string) => TMessage | null;
   onOpen?: (controls: LiveWebSocketControls) => void;
   onMessage: (message: TMessage, controls: LiveWebSocketControls) => void;
@@ -62,12 +70,13 @@ const DEFAULT_RECONNECT = {
  */
 const CONNECT_TIMEOUT_MS = DEFAULT_RECONNECT.maxDelayMs;
 
-const defaultCloseError = ({ code, reason }: LiveWebSocketClose): LiveWebSocketError | null => {
-  if (code === 1008) return { code: reason || "access_denied", message: "Live access changed or expired." };
-  if (code === 1011) return { code: reason || "internal_error", message: "Live updates failed." };
-  if (code === 1013) return { code: reason || "backpressure", message: "Live updates are overloaded." };
-  return null;
-};
+/**
+ * Only a policy close (`1008`) ends live updates by default. Every other close,
+ * including `1011` (internal error) and `1013` (try again later), reconnects
+ * with backoff; the new subscription checks access again.
+ */
+const defaultCloseError = ({ code, reason }: LiveWebSocketClose): LiveWebSocketError | null =>
+  code === 1008 ? { code: reason || "access_denied", message: "Live access changed or expired." } : null;
 
 const socketUrl = (raw: string): string => {
   const url = new URL(raw, window.location.origin);
@@ -96,6 +105,7 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
   let connectStartedAt = 0;
   let reconnectAttempt = 0;
   let lastAppliedCursor = options.initialCursor ?? null;
+  let subscribedCursor = lastAppliedCursor;
   let started = false;
   let disposed = false;
   let terminated = false;
@@ -165,6 +175,7 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
 
   const controls: LiveWebSocketControls = {
     markApplied,
+    subscribedCursor: () => subscribedCursor,
     resetCursor,
     send,
     terminate: fatal,
@@ -210,6 +221,9 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
     }
     socket = next;
     connectStartedAt = Date.now();
+    // When the server first answered. A server can accept a subscription and fail right after, often with an error
+    // frame, so the backoff starts over only once the connection stayed up for the longest delay after that.
+    let answeredAt: number | null = null;
     connectTimer = setTimeout(() => {
       connectTimer = null;
       if (next.readyState === WebSocket.CONNECTING) abandonAttempt(next);
@@ -219,7 +233,9 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
       if (socket !== next || disposed || terminated) return;
       clearConnectDeadline();
       try {
-        if (!send(options.subscribe(lastAppliedCursor))) throw new Error("Live WebSocket subscription could not be sent");
+        subscribedCursor = lastAppliedCursor;
+        if (options.subscribe && !send(options.subscribe(subscribedCursor)))
+          throw new Error("Live WebSocket subscription could not be sent");
         setStatus("open");
         options.onOpen?.(controls);
       } catch (error) {
@@ -232,8 +248,8 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
       try {
         const message = options.parse(event.data);
         if (message) {
+          answeredAt ??= Date.now();
           options.onMessage(message, controls);
-          reconnectAttempt = 0;
         }
       } catch (error) {
         fatal(
@@ -249,8 +265,12 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
       clearConnectDeadline();
       if (disposed || terminated) return;
       const closeError = classifyClose({ code: event.code, reason: event.reason.trim() });
-      if (closeError) fatal(closeError, { code: event.code, reason: event.reason });
-      else scheduleReconnect();
+      if (closeError) {
+        fatal(closeError, { code: event.code, reason: event.reason });
+        return;
+      }
+      if (answeredAt !== null && Date.now() - answeredAt >= reconnect.maxDelayMs) reconnectAttempt = 0;
+      scheduleReconnect();
     };
 
     next.onerror = () => {

package/src/browser/live.ts

@@ -0,0 +1,2 @@
+export * from "./live-connection";
+export * from "./live-websocket";

package/src/browser/resource-search-messages.ts

@@ -12,7 +12,15 @@ export const resourceSearchMessages = i18n.define({
       commandHint: "Choose an action, or type > next time.",
       searchFailed: "Search is currently unavailable. Try again.",
       navigationFailed: "Could not open this result. Try again.",
-      partialFailure: "Some search sources are unavailable. Results may be incomplete.",
+      stillSearching: ({ apps, count }: { apps: string; count: number }) =>
+        count === 1 ? `${apps} is still searching…` : `${apps} are still searching…`,
+      moreApps: ({ count }: { count: number }) => `${count} more`,
+      appTimedOut: ({ app }: { app: string }) => `${app} did not respond in time`,
+      appUnavailable: ({ app }: { app: string }) => `${app} is not available right now`,
+      appNoMatches: ({ app, query }: { app: string; query: string }) =>
+        query ? `${app}: no matches for “${query}”` : `${app}: no matches`,
+      searchDone: ({ count }: { count: number }) =>
+        i18n.plural(count, "en", { one: `Search complete, ${count} result`, other: `Search complete, ${count} results` }),
       searchPlaceholder: "Search Cloud…",
       scopedSearchPlaceholder: "Search…",
       searchCloudResources: "Search Cloud resources",
@@ -54,7 +62,12 @@ export const resourceSearchMessages = i18n.define({
       commandHint: "Wähle eine Aktion – beim nächsten Mal geht auch >.",
       searchFailed: "Suche gerade nicht erreichbar. Versuche es erneut.",
       navigationFailed: "Der Treffer konnte nicht geöffnet werden. Versuche es erneut.",
-      partialFailure: "Einige Suchquellen sind nicht erreichbar. Ergebnisse können unvollständig sein.",
+      stillSearching: ({ apps, count }) => (count === 1 ? `${apps} sucht noch …` : `${apps} suchen noch …`),
+      moreApps: ({ count }) => `${count} weitere`,
+      appTimedOut: ({ app }) => `${app} hat nicht rechtzeitig geantwortet`,
+      appUnavailable: ({ app }) => `${app} ist gerade nicht erreichbar`,
+      appNoMatches: ({ app, query }) => (query ? `${app}: keine Treffer für „${query}“` : `${app}: keine Treffer`),
+      searchDone: ({ count }) => `Suche abgeschlossen, ${count} Treffer`,
       searchPlaceholder: "Cloud durchsuchen…",
       scopedSearchPlaceholder: "Durchsuchen…",
       searchCloudResources: "Cloud-Inhalte durchsuchen",

package/src/browser/search-stream.ts

@@ -0,0 +1,151 @@
+import type { SearchApp, SearchItem, SearchProviderStatus, SearchResponse, SearchStreamLine } from "../api/search/schemas";
+import { LOCALE_HEADER } from "../shared/locale";
+
+/** Kept local so the browser bundle does not load the server-side search schemas. */
+const STREAM_CONTENT_TYPE = "application/x-ndjson";
+
+export type SearchAppStatus = SearchProviderStatus | "searching";
+
+/** Rows one provider line added. A retried app adds a block of its own at the end. */
+export type SearchBlock = { appId: string; items: SearchItem[] };
+
+/**
+ * One streamed search as the browser shows it. Blocks only ever grow at the end, so nothing already visible moves;
+ * `status` says for every app named in `start` whether it is still searching and how it finished.
+ */
+export type SearchRun = {
+  apps: SearchApp[];
+  providers: string[];
+  status: Record<string, SearchAppStatus>;
+  blocks: SearchBlock[];
+  unsupportedTags: string[];
+  /** The stream has ended; a retried app may still search afterwards. */
+  done: boolean;
+  /** The request failed before any app was named. */
+  failed: boolean;
+};
+
+export const emptySearchRun = (): SearchRun => ({
+  apps: [],
+  providers: [],
+  status: {},
+  blocks: [],
+  unsupportedTags: [],
+  done: false,
+  failed: false,
+});
+
+const itemKey = (item: SearchItem) => `${item.ref.type}\u0000${item.ref.id}`;
+
+export const applySearchLine = (run: SearchRun, line: SearchStreamLine): SearchRun => {
+  if (line.type === "start")
+    return {
+      ...run,
+      apps: line.apps,
+      providers: line.providers,
+      status: Object.fromEntries(line.providers.map((appId) => [appId, "searching" as const])),
+      unsupportedTags: line.unsupportedTags ?? [],
+    };
+  if (line.type === "done") return { ...run, done: true };
+  // Only an app that is searching takes a line, which bounds the lines a run accepts.
+  if (run.status[line.provider] !== "searching") return run;
+  const shown = new Set(run.blocks.flatMap((block) => block.items.map(itemKey)));
+  const items = line.results.filter((item) => !shown.has(itemKey(item)));
+  return {
+    ...run,
+    status: { ...run.status, [line.provider]: line.status },
+    blocks: items.length ? [...run.blocks, { appId: line.provider, items }] : run.blocks,
+  };
+};
+
+/**
+ * The request failed or the stream broke off. Once apps were named, the rows that arrived stay and every app still
+ * searching has failed on its own, with its own retry; before that, the search failed as a whole.
+ */
+export const breakSearchRun = (run: SearchRun): SearchRun =>
+  run.providers.length
+    ? {
+        ...run,
+        done: true,
+        status: Object.fromEntries(Object.entries(run.status).map(([appId, status]) => [appId, status === "searching" ? "error" : status])),
+      }
+    : { ...run, failed: true };
+
+/** Marks an app as searching again before its retry starts. */
+export const retrySearchApp = (run: SearchRun, appId: string): SearchRun => ({
+  ...run,
+  status: { ...run.status, [appId]: "searching" },
+});
+
+export const searchingApps = (run: SearchRun) => run.providers.filter((appId) => run.status[appId] === "searching");
+export const failedSearchApps = (run: SearchRun) =>
+  run.providers.flatMap((appId) => {
+    const status = run.status[appId];
+    return status === "timeout" || status === "error" ? [{ appId, status }] : [];
+  });
+/** Every app has answered: only now may an empty run say that nothing was found. */
+export const searchFinished = (run: SearchRun) => (run.done || run.failed) && searchingApps(run).length === 0;
+
+/** An older Core answers with merged JSON; it becomes the same lines, without per-app timing. */
+const linesFromResponse = (body: SearchResponse): SearchStreamLine[] => {
+  const failed = body.failedApps ?? [];
+  const found = [...new Set(body.items.map((item) => item.appId))];
+  return [
+    {
+      type: "start",
+      query: body.query,
+      apps: body.apps,
+      providers: [...new Set([...found, ...failed])],
+      ...(body.unsupportedTags ? { unsupportedTags: body.unsupportedTags } : {}),
+    },
+    ...found.map((appId): SearchStreamLine => {
+      const results = body.items.filter((item) => item.appId === appId);
+      return { type: "provider", provider: appId, status: failed.includes(appId) ? "error" : "ok", results, ms: 0 };
+    }),
+    ...failed
+      .filter((appId) => !found.includes(appId))
+      .map((appId): SearchStreamLine => ({ type: "provider", provider: appId, status: "error", results: [], ms: 0 })),
+    { type: "done", status: failed.length ? "partial" : "complete", count: body.items.length },
+  ];
+};
+
+/**
+ * Runs one search against `/api/search` and hands over each line as it arrives. Aborting `signal` ends the request,
+ * and with it every provider the server still waits for. Rejects when the request fails or the stream breaks off.
+ */
+export const streamCloudResourceSearch = async (
+  url: string,
+  options: { signal: AbortSignal; locale: string; onLine: (line: SearchStreamLine) => void },
+): Promise<void> => {
+  const response = await fetch(url, {
+    signal: options.signal,
+    headers: { accept: STREAM_CONTENT_TYPE, [LOCALE_HEADER]: options.locale },
+  });
+  if (!response.ok) throw new Error(`Search failed with ${response.status}`);
+  if (!response.headers.get("content-type")?.startsWith(STREAM_CONTENT_TYPE)) {
+    const body: SearchResponse = await response.json();
+    for (const line of linesFromResponse(body)) options.onLine(line);
+    return;
+  }
+  if (!response.body) throw new Error("Search returned no body");
+  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+  let buffer = "";
+  let closed = false;
+  while (!closed) {
+    const chunk = await reader.read();
+    if (chunk.done) break;
+    buffer += chunk.value;
+    let end = buffer.indexOf("\n");
+    while (end >= 0) {
+      const text = buffer.slice(0, end).trim();
+      buffer = buffer.slice(end + 1);
+      if (text) {
+        const line: SearchStreamLine = JSON.parse(text);
+        options.onLine(line);
+        if (line.type === "done") closed = true;
+      }
+      end = buffer.indexOf("\n");
+    }
+  }
+  if (!closed) throw new Error("Search stream ended early");
+};

package/src/contracts/app.ts

@@ -88,6 +88,14 @@ export type AppCliModule = {
 /** `cld` modules keyed by module name, the command `cld <name>`. */
 export type AppCliModules = Readonly<Record<string, AppCliModule>>;
 
+/** An application's part of the mobile app (preview). */
+export type AppPwaPart = {
+  /** Always `/pwa/<app id>`. */
+  href: string;
+  /** Coarse visibility in the mobile app, like `nav.requiresRoles`. Routes and services still authorize. */
+  requiresRoles?: Role[];
+};
+
 export type AppMeta = {
   id: string;
   name: string;
@@ -118,6 +126,8 @@ export type AppMeta = {
   legalLinks?: LegalLink[];
   /** Static search destinations, visible when the app is in the user's navigation catalog. */
   searchLinks?: readonly AppSearchLink[];
+  /** The app's pages in the installable mobile app (preview), at `href` = `/pwa/<id>`. */
+  pwa?: AppPwaPart;
   /**
    * Dashboard widget endpoints this app exposes. Each entry references an
    * HTTP endpoint that returns a `WidgetResponse` (see `contracts/widgets.ts`).

package/src/contracts/capabilities.ts

@@ -436,6 +436,9 @@ export type CapabilityCommandManifest = z.infer<typeof CapabilityCommandManifest
 
 type CapabilityDefinitionCatalog<T> = Readonly<Record<string, T>>;
 
+/** Offers files to other apps: local IDs of the list Query, the read Query, and the optional save Action. */
+export type CapabilityFileProviderDeclaration = { list: string; read: string; save?: string };
+
 export type CapabilityDefinitions = {
   protocolVersion: typeof CAPABILITY_PROTOCOL_VERSION;
   presentation?: CapabilityPresentationCatalog;
@@ -443,6 +446,7 @@ export type CapabilityDefinitions = {
   queries?: CapabilityDefinitionCatalog<CapabilityQueryDefinition>;
   actions?: CapabilityDefinitionCatalog<CapabilityActionDefinition>;
   commands?: CapabilityDefinitionCatalog<CapabilityCommandDefinition>;
+  fileProvider?: CapabilityFileProviderDeclaration;
 };
 
 /**
@@ -504,17 +508,81 @@ export const CapabilityAppIdSchema = z
   .max(80)
   .regex(/^[a-z][a-z0-9-]*$/);
 
-export const CapabilityManifestSchema = z
-  .object({
+const MAX_MANIFEST_ENTRIES = 200;
+
+export const CapabilityFileProviderManifestSchema = z
+  .object({ list: CapabilityLocalIdSchema, read: CapabilityLocalIdSchema, save: CapabilityLocalIdSchema.optional() })
+  .strict();
+
+/** Keeps the sent entries this release reads completely. */
+const readEntries = <T extends z.ZodType>(values: unknown, entry: T): z.output<T>[] | null => {
+  // Not a bounded list: leave the value to the manifest schema, which rejects it.
+  if (!Array.isArray(values) || values.length > MAX_MANIFEST_ENTRIES) return null;
+  return values.flatMap((value) => {
+    const parsed = entry.safeParse(value);
+    return parsed.success ? [parsed.data] : [];
+  });
+};
+
+/**
+ * Reads what this release understands from a manifest that a newer release may have produced.
+ *
+ * - Unknown top-level fields are ignored. A newer release may therefore only add something at the top
+ *   level; anything that restricts an existing entry belongs inside that entry.
+ * - An entry with a field or value from a newer release is left out rather than stripped: its unknown
+ *   part may change how the entry runs or who may use it, so guessing could widen access.
+ * - Entries that depend on an entry that is not there follow it: a Query scoped to a missing type is
+ *   left out, and a type whose reader is missing keeps no reader.
+ * - A file provider with a field from a newer release is left out. Whether its operations are still
+ *   there and match the contract is `fileProviderIssues`' job, which Core and consumers run.
+ *
+ * Every other entry stays available.
+ */
+const readableManifest = (value: unknown): unknown => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  const sent = value as Record<string, unknown>;
+  const types = readEntries(sent.types, CapabilityResourceTypeManifestSchema);
+  const queries = readEntries(sent.queries, CapabilityQueryManifestSchema);
+  const actions = readEntries(sent.actions, CapabilityActionManifestSchema);
+  const commands = readEntries(sent.commands, CapabilityCommandManifestSchema);
+  if (!types || !queries || !actions || !commands) return value;
+  const typeIds = new Set(types.map((type) => type.localId));
+  const readableQueries = queries.filter((query) => query.universalSearch?.scopeTypes?.every((type) => typeIds.has(type)) ?? true);
+  const queryIds = new Set(readableQueries.map((query) => query.localId));
+  const { fileProvider: sentProvider, ...rest } = sent;
+  const provider = CapabilityFileProviderManifestSchema.safeParse(sentProvider);
+  return {
+    ...rest,
+    ...(provider.success ? { fileProvider: provider.data } : {}),
+    types: types.map((type) => {
+      if (!type.reader || queryIds.has(type.reader)) return type;
+      const { reader: _missing, ...withoutReader } = type;
+      return withoutReader;
+    }),
+    queries: readableQueries,
+    actions,
+    commands,
+  };
+};
+
+/**
+ * Reads a manifest from any Cloud release with the same protocol version (see `readableManifest`).
+ * Producers stay strict: `app.start()` registers exactly the manifest its release defines.
+ */
+export const CapabilityManifestSchema = z.preprocess(
+  readableManifest,
+  z.object({
     protocolVersion: z.literal(CAPABILITY_PROTOCOL_VERSION),
     appId: CapabilityAppIdSchema,
     manifestHash: z.string().regex(/^[a-f0-9]{64}$/),
-    types: z.array(CapabilityResourceTypeManifestSchema).max(200),
-    queries: z.array(CapabilityQueryManifestSchema).max(200),
-    actions: z.array(CapabilityActionManifestSchema).max(200),
-    commands: z.array(CapabilityCommandManifestSchema).max(200),
-  })
-  .strict();
+    types: z.array(CapabilityResourceTypeManifestSchema).max(MAX_MANIFEST_ENTRIES),
+    queries: z.array(CapabilityQueryManifestSchema).max(MAX_MANIFEST_ENTRIES),
+    actions: z.array(CapabilityActionManifestSchema).max(MAX_MANIFEST_ENTRIES),
+    commands: z.array(CapabilityCommandManifestSchema).max(MAX_MANIFEST_ENTRIES),
+    // Optional without a default: a manifest without a provider keeps the shape and hash of earlier releases.
+    fileProvider: CapabilityFileProviderManifestSchema.optional(),
+  }),
+);
 
 export type CapabilityResourceTypeManifest = z.infer<typeof CapabilityResourceTypeManifestSchema>;
 export type CapabilityQueryManifest = z.infer<typeof CapabilityQueryManifestSchema>;
@@ -533,22 +601,19 @@ export const resolveCapabilityResourceReader = (manifest: CapabilityManifest, re
   return manifest.queries.find((candidate) => candidate.localId === type.reader) ?? null;
 };
 
-export const CapabilityCatalogAppSchema = z
-  .object({
-    appId: CapabilityAppIdSchema,
-    appName: z.string().min(1).max(200),
-    appIcon: z.string().min(1).max(120),
-    appDescription: z.string().max(1000),
-    manifest: CapabilityManifestSchema,
-  })
-  .strict();
+/** Like the manifest, catalog entries, pages, and their pagination ignore fields that a newer Cloud release added. */
+export const CapabilityCatalogAppSchema = z.object({
+  appId: CapabilityAppIdSchema,
+  appName: z.string().min(1).max(200),
+  appIcon: z.string().min(1).max(120),
+  appDescription: z.string().max(1000),
+  manifest: CapabilityManifestSchema,
+});
 
-export const CapabilityCatalogSchema = z
-  .object({
-    protocolVersion: z.literal(CAPABILITY_PROTOCOL_VERSION),
-    apps: z.array(CapabilityCatalogAppSchema).max(25),
-    page: CapabilityPageSchema,
-  })
-  .strict();
+export const CapabilityCatalogSchema = z.object({
+  protocolVersion: z.literal(CAPABILITY_PROTOCOL_VERSION),
+  apps: z.array(CapabilityCatalogAppSchema).max(25),
+  page: z.discriminatedUnion("hasMore", [CapabilityPageSchema.options[0].strip(), CapabilityPageSchema.options[1].strip()]),
+});
 
 export type CapabilityCatalog = z.infer<typeof CapabilityCatalogSchema>;