@k2b/cloud 0.6.0-rc.0 → 0.7.0

package/src/_internal/capabilities.ts

@@ -11,6 +11,8 @@ import {
   type CapabilityActionReviewResult,
   CapabilityActionReviewSchema,
   type CapabilityDefinitions,
+  type CapabilityCommandManifest,
+  CapabilityCommandManifestSchema,
   type CapabilityError,
   CapabilityErrorSchema,
   type CapabilityExecutionContext,
@@ -190,12 +192,14 @@ const compileSchemaPresentation = (
 
 const compileOperationPresentation = (
   value: unknown,
-  operation: CapabilityQueryManifest | CapabilityActionManifest,
+  operation: CapabilityQueryManifest | CapabilityActionManifest | CapabilityCommandManifest,
   label: string,
 ): CapabilityOperationPresentationTranslation => {
   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(["title", "description", "input", "data", "searchTags"]);
+  const allowed = new Set(
+    "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 (translation.title !== undefined) {
@@ -238,7 +242,7 @@ const compileOperationPresentation = (
     );
   }
   const input = compileSchemaPresentation(translation.input, operation.inputSchema, `${label}.input`);
-  const data = compileSchemaPresentation(translation.data, operation.dataSchema, `${label}.data`);
+  const data = "dataSchema" in operation ? compileSchemaPresentation(translation.data, operation.dataSchema, `${label}.data`) : undefined;
   return {
     ...(typeof translation.title === "string" ? { title: translation.title.trim() } : {}),
     ...(typeof translation.description === "string" ? { description: translation.description.trim() } : {}),
@@ -263,6 +267,7 @@ export const compileCapabilityPresentation = (manifest: CapabilityManifest, valu
   const types = new Map(manifest.types.map((type) => [type.localId, type]));
   const queries = new Map(manifest.queries.map((operation) => [operation.localId, operation]));
   const actions = new Map(manifest.actions.map((operation) => [operation.localId, operation]));
+  const commands = new Map(manifest.commands.map((operation) => [operation.localId, operation]));
   const translations: Record<string, CapabilityPresentationTranslation> = {};
   for (const [locale, rawTranslation] of Object.entries(catalog.translations as Record<string, unknown>)) {
     const canonical = canonicalLocale(locale);
@@ -273,7 +278,7 @@ export const compileCapabilityPresentation = (manifest: CapabilityManifest, valu
       throw new Error(`Capability presentation translation ${canonical} must be an object`);
     }
     const raw = rawTranslation as Record<string, unknown>;
-    const extra = Object.keys(raw).find((key) => key !== "types" && key !== "queries" && key !== "actions");
+    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}"`);
     const compileGroup = <T>(
       group: unknown,
@@ -311,10 +316,12 @@ export const compileCapabilityPresentation = (manifest: CapabilityManifest, valu
     });
     const translatedQueries = compileGroup(raw.queries, queries, "Query", compileOperationPresentation);
     const translatedActions = compileGroup(raw.actions, actions, "Action", compileOperationPresentation);
+    const translatedCommands = compileGroup(raw.commands, commands, "Command", compileOperationPresentation);
     translations[canonical] = {
       ...(translatedTypes ? { types: translatedTypes } : {}),
       ...(translatedQueries ? { queries: translatedQueries } : {}),
       ...(translatedActions ? { actions: translatedActions } : {}),
+      ...(translatedCommands ? { commands: translatedCommands } : {}),
     };
   }
   return { baseLocale, translations };
@@ -406,7 +413,7 @@ const normalizeSearchTags = (definition: CapabilityQueryDefinition, label: strin
       ...(aliases.length > 0 ? { aliases } : {}),
     };
   });
-  return { tags };
+  return { tags, ...(definition.universalSearch.scopeTypes ? { scopeTypes: [...new Set(definition.universalSearch.scopeTypes)] } : {}) };
 };
 
 const compileOperationSchemas = (definition: CapabilityQueryDefinition | CapabilityActionDefinition, label: string) => {
@@ -426,7 +433,7 @@ const compileOperationSchemas = (definition: CapabilityQueryDefinition | Capabil
     inputSchema,
     dataSchema,
     resultZodSchema,
-    schemaHash: capabilityHash({ inputSchema, dataSchema }),
+    schemaHash: capabilityHash({ inputSchema, dataSchema, ...(definition.stream ? { stream: { direction: definition.stream.direction, maxBytes: definition.stream.maxBytes } } : {}) }),
   };
 };
 
@@ -462,6 +469,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}`;
+    if (definition.stream && ((definition.stream.direction === "write" && !("idempotency" in definition)) || definition.stream.maxBytes <= 0)) throw new Error(`${label}: write streams require an Action and a positive byte budget`);
+    if (definition.stream?.direction === "write" && "idempotency" in definition && definition.idempotency !== "required") throw new Error(`${label}: write streams require idempotency`);
     const schemas = compileOperationSchemas(definition, label);
     if (definition.universalSearch) {
       const expectedInput = projectSchema(UniversalSearchInputSchema, "Universal Search input", "input");
@@ -480,9 +489,13 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
       inputSchema: schemas.inputSchema,
       dataSchema: schemas.dataSchema,
       schemaHash: schemas.schemaHash,
+      ...(definition.stream ? { stream: { direction: definition.stream.direction, maxBytes: definition.stream.maxBytes } } : {}),
       openWorld: definition.openWorld,
       universalSearch: normalizeSearchTags(definition, label),
     } satisfies CapabilityQueryManifest;
+    for (const type of manifest.universalSearch?.scopeTypes ?? []) {
+      if (!typeIds.has(qualifiedId(appId, type))) throw new Error(`${label} declares an unknown search scope type ${type}`);
+    }
     queries.set(localId, {
       definition,
       manifest,
@@ -499,12 +512,36 @@ 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}`;
+    // 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
+    // must never be approved once and then replayed silently.
+    if (definition.destructive && !definition.review) {
+      throw new Error(`${label} is destructive and must declare review()`);
+    }
+    if (definition.destructive && definition.idempotency !== "required") {
+      throw new Error(`${label} is destructive and must declare idempotency: "required"`);
+    }
+    if (definition.openWorld && !definition.review) {
+      throw new Error(`${label} is open-world and must declare review()`);
+    }
+    if (definition.openWorld && definition.idempotency !== "required") {
+      throw new Error(`${label} is open-world and must declare idempotency: "required"`);
+    }
     if (definition.approval === "rememberable" && definition.openWorld) {
       throw new Error(`${label} cannot remember approval for an open-world effect`);
     }
+    if (definition.approval === "rememberable" && definition.destructive) {
+      throw new Error(`${label} cannot remember approval for a destructive effect`);
+    }
+    if (definition.approval === "none" && (definition.destructive || definition.openWorld)) {
+      throw new Error(`${label} cannot skip approval for destructive or open-world effects`);
+    }
     if (definition.approval === "rememberable" && !definition.review) {
       throw new Error(`${label} must provide a review before approval can be remembered`);
     }
+    if (definition.stream && ((definition.stream.direction === "write" && !("idempotency" in definition)) || definition.stream.maxBytes <= 0)) throw new Error(`${label}: write streams require an Action and a positive byte budget`);
+    if (definition.stream?.direction === "write" && "idempotency" in definition && definition.idempotency !== "required") throw new Error(`${label}: write streams require idempotency`);
     const schemas = compileOperationSchemas(definition, label);
     const manifest = {
       localId,
@@ -513,6 +550,7 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
       inputSchema: schemas.inputSchema,
       dataSchema: schemas.dataSchema,
       schemaHash: schemas.schemaHash,
+      ...(definition.stream ? { stream: { direction: definition.stream.direction, maxBytes: definition.stream.maxBytes } } : {}),
       destructive: definition.destructive,
       openWorld: definition.openWorld,
       idempotency: definition.idempotency,
@@ -526,12 +564,30 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
     });
   }
 
+  const commands = Object.entries(definitions.commands ?? {})
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([localId, definition]) => {
+      registerLocalId(localId, "Command");
+      const inputSchema = projectSchema(definition.input, `Command ${localId} input`, "input");
+      assertClosedObjectInput(inputSchema, `Command ${localId} input`);
+      return CapabilityCommandManifestSchema.parse({
+        localId,
+        title: definition.title.trim(),
+        description: definition.description.trim(),
+        icon: definition.icon,
+        keywords: [...(definition.keywords ?? [])],
+        inputSchema,
+        path: definition.path,
+      });
+    });
+
   const manifestBase = {
     protocolVersion: CAPABILITY_PROTOCOL_VERSION,
     appId,
     types,
     queries: [...queries.values()].map((entry) => entry.manifest),
     actions: [...actions.values()].map((entry) => entry.manifest),
+    commands,
   };
   const manifest = CapabilityManifestSchema.parse({
     ...manifestBase,
@@ -614,6 +670,7 @@ export const resolveCapabilityManifestPresentation = (
           ...(operation.universalSearch
             ? {
                 universalSearch: {
+                  ...operation.universalSearch,
                   tags: operation.universalSearch.tags.map((tag) => {
                     const tagCopy = copy.searchTags?.[tag.tag];
                     return tagCopy
@@ -625,6 +682,17 @@ export const resolveCapabilityManifestPresentation = (
             : {}),
         };
       }),
+      commands: current.commands.map((operation) => {
+        const copy = translation.commands?.[operation.localId];
+        return copy
+          ? {
+              ...operation,
+              title: copy.title ?? operation.title,
+              description: copy.description ?? operation.description,
+              inputSchema: applySchemaPresentation(operation.inputSchema, copy.input),
+            }
+          : operation;
+      }),
       actions: current.actions.map((operation) => {
         const copy = translation.actions?.[operation.localId];
         return copy
@@ -668,10 +736,19 @@ export const parseCapabilityManifest = (value: unknown, expectedAppId: string):
       );
     }
     assertClosedObjectInput(inputSchema, `Operation ${operation.localId} input`);
-    const expectedSchemaHash = capabilityHash({ inputSchema: operation.inputSchema, dataSchema: operation.dataSchema });
+    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 (
@@ -682,6 +759,11 @@ export const parseCapabilityManifest = (value: unknown, expectedAppId: string):
       }
     }
   }
+  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;
@@ -787,6 +869,12 @@ export const capabilityManifestEvolutionIssues = (previous: CapabilityManifest,
     else if (type.reader && current.reader !== type.reader) issues.push(`Type ${type.localId} reader changed`);
   }
 
+  const nextCommands = new Map(next.commands.map((command) => [command.localId, command]));
+  for (const command of previous.commands) {
+    const current = nextCommands.get(command.localId);
+    if (!current) issues.push(`Command ${command.localId} was removed`);
+    else issues.push(...schemaEvolutionIssues(command.inputSchema, current.inputSchema, `Command ${command.localId} input`, "input"));
+  }
   const nextQueries = new Map(next.queries.map((operation) => [operation.localId, operation]));
   const nextActions = new Map(next.actions.map((operation) => [operation.localId, operation]));
   for (const operation of previous.queries) {
@@ -982,11 +1070,24 @@ export const invokeCompiledCapability = async (params: {
       },
     };
   }
+  if ("universalSearch" in operation.manifest && operation.manifest.universalSearch) {
+    const search = UniversalSearchInputSchema.parse(input.data);
+    if (
+      search.scope &&
+      !(operation.manifest.universalSearch.scopeTypes ?? []).some(
+        (type) => qualifiedId(params.compiled.manifest.appId, type) === search.scope!.type,
+      )
+    )
+      return { ok: false, error: { code: "VALIDATION_FAILED", message: "Unsupported search scope", status: 400 } };
+  }
   try {
     const invoked = await operation.definition.run(input.data, context);
     if (!invoked.ok) {
       return normalizeProviderError(invoked.error, "Capability returned an invalid error", params.onUnexpectedError);
     }
+    const stream = invoked.data.stream;
+    if (stream && (Buffer.byteLength(stream.id) > 2048 || !operation.definition.stream || stream.direction !== operation.definition.stream.direction || stream.size > operation.definition.stream.maxBytes || Date.parse(stream.expiresAt) <= Date.now() || Date.parse(stream.expiresAt) > Date.now() + 86_400_000))
+      return invalidProviderError("Stream is outside its declared policy or 24 hour lifetime");
     const validated = validateCapabilityResult(params.compiled, operation, invoked.data, params.onUnexpectedError);
     return validated.ok
       ? ({

package/src/_internal/capability-streams.ts

@@ -0,0 +1,81 @@
+import { isServiceError } from "@k2b/stdlib";
+import { exactStream } from "../capabilities/stream-body";
+import type { CapabilityExecutionContext } from "../contracts/capabilities";
+import {
+  CAPABILITY_MAX_RESULT_BYTES,
+  CapabilityStreamSchema,
+  CapabilityStreamStatusSchema,
+  capabilityResultSchema,
+} from "../contracts/capabilities";
+import type { CompiledCapabilities } from "./capabilities";
+
+const failure = (status: number, code: string, message: string) => Response.json({ code, message }, { status });
+export async function invokeCapabilityStream(params: {
+  compiled: CompiledCapabilities;
+  kind: "queries" | "actions";
+  localId: string;
+  verb: string;
+  request: Request;
+  context: CapabilityExecutionContext;
+}): Promise<Response> {
+  const operation = params.compiled[params.kind].get(params.localId);
+  const definition = operation?.definition.stream;
+  if (!operation || !definition) return failure(404, "STREAM_NOT_FOUND", "Stream operation not found");
+  const offer = params.request.headers.get("x-cloud-stream-offer");
+  if (!offer || offer.length > 24000) return failure(400, "STREAM_INVALID", "Invalid stream offer");
+  const receipt = (value: unknown) => {
+    const parsed = capabilityResultSchema(operation.definition.data).parse(value);
+    if (parsed.stream) throw new Error("Stream receipts cannot issue another stream");
+    return parsed;
+  };
+  try {
+    const stream = CapabilityStreamSchema.parse(JSON.parse(Buffer.from(offer, "base64url").toString()));
+    if (stream.direction !== definition.direction || stream.size > definition.maxBytes || Date.parse(stream.expiresAt) <= Date.now())
+      return failure(410, "STREAM_EXPIRED", "Stream expired or outside its byte budget");
+    if (definition.direction === "read") {
+      if (params.verb !== "read") return failure(403, "STREAM_DENIED", "Read-only stream");
+      const response = await definition.read(stream, params.context);
+      if (!response.ok || !response.body) {
+        await response.body?.cancel();
+        return failure(502, "STREAM_FAILED", "Source could not be read");
+      }
+      return new Response(exactStream(response.body, stream.size), {
+        headers: { "content-type": stream.mediaType, "cache-control": "no-store" },
+      });
+    }
+    let result: unknown;
+    if (params.verb === "write") {
+      const body = exactStream(
+        params.request.body ??
+          new ReadableStream({
+            start(c) {
+              c.close();
+            },
+          }),
+        stream.size,
+      );
+      try {
+        const value = await definition.write(stream, body, params.context);
+        result = receipt(value);
+      } finally {
+        if (!body.locked) await body.cancel().catch(() => undefined);
+      }
+    } else if (params.verb === "status") {
+      const status = CapabilityStreamStatusSchema.parse(await definition.status(stream, params.context));
+      if (status.state === "completed") receipt(status.result);
+      result = status;
+    } else if (params.verb === "abort") {
+      await definition.abort(stream, params.context);
+      const status = CapabilityStreamStatusSchema.parse(await definition.status(stream, params.context));
+      if (status.state === "completed") receipt(status.result);
+      result = status;
+    } else return failure(400, "STREAM_INVALID", "Unknown stream operation");
+    const json = JSON.stringify(result);
+    if (Buffer.byteLength(json) > CAPABILITY_MAX_RESULT_BYTES)
+      return failure(502, "STREAM_FAILED", "Stream receipt is too large; inspect status before retrying");
+    return new Response(json, { headers: { "content-type": "application/json", "cache-control": "no-store" } });
+  } catch (error) {
+    if (isServiceError(error)) return failure(error.status, error.code, error.message);
+    return failure(409, "STREAM_FAILED", "Transfer failed; inspect status before retrying a write");
+  }
+}

package/src/_internal/define-app.ts

@@ -1,3 +1,7 @@
+import { invokeCapabilityStream } from "./capability-streams";
+import { registerHelp } from "../services/help";
+import { preloadLayoutHelp } from "../ssr/help";
+import { bindProcessApplicationId, clearProcessApplicationId } from "./process-identity";
 /**
  * defineApp() — The single entry point for every cloud app.
  *
@@ -5,6 +9,8 @@
  * Returns `{ ssr, plugin, config, meta, start }`.
  */
 
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import type { SsrConfig } from "@k2b/ssr";
 import { createConfig as createSsrConfig } from "@k2b/ssr";
 import { routes } from "@k2b/ssr/hono";
@@ -18,10 +24,17 @@ import type {
   AppLifecycle,
   AppMeta,
   AppPresentationCatalog,
+  AppSearchLink,
   CloudLifecycleContext,
   WidgetEndpoint,
 } from "../contracts/app";
-import { CAPABILITY_FRAMEWORK_ERROR_CODES, CAPABILITY_MAX_REQUEST_BYTES, type CapabilityDefinitions } from "../contracts/capabilities";
+import {
+  CAPABILITY_FRAMEWORK_ERROR_CODES,
+  CAPABILITY_MAX_REQUEST_BYTES,
+  CAPABILITY_ORIGIN_HEADER,
+  type CapabilityDefinitions,
+  CapabilityOriginSchema,
+} from "../contracts/capabilities";
 import { type BoundNotificationMap, bindNotificationDefinitions, type NotificationDefinitionMap } from "../contracts/notification-types";
 import type { AppRegistryEntry } from "../contracts/registry";
 import type { AppSettingsMap, KindToType } from "../contracts/settings-types";
@@ -30,18 +43,19 @@ import type { HelpDefinition } from "../server/help";
 import { getLocale, resolveLocale } from "../server/locale";
 import { type AuthContext, auth } from "../server/middleware/auth";
 import { requireInvocation } from "../server/middleware/invocation";
-import { routeTemplate } from "../server/middleware/route-template";
+import { matchedRouteTemplate, routeTemplate } from "../server/middleware/route-template";
 import { runtime as runtimeMiddleware } from "../server/middleware/runtime";
-import { settings as settingsMiddleware } from "../server/middleware/settings";
+import { preloadLayoutAnnouncements, settings as settingsMiddleware } from "../server/middleware/settings";
 import {
   capabilityInvocationOperation,
   searchInvocationOperation,
   syncInvocationOperation,
   widgetInvocationOperation,
 } from "../services/identity/invocation-operations";
+import { normalizeInvocationRequestId } from "../services/identity/invocation-token";
 import { logger } from "../services/logging";
 import { startNotificationDefinitionRegistration } from "../services/notifications/catalog";
-import { railPreferences } from "../services/rail-preferences";
+import { readRailSnapshot } from "../services/rail-snapshot";
 import { get, loadCache as loadSettingsCache, set } from "../services/settings";
 import { createSettingsAPI, type SettingsAPI } from "../services/settings/api";
 import { registerSettings, toLegacySettingDefs } from "../services/settings/defaults";
@@ -59,11 +73,13 @@ import { createHeartbeat } from "./heartbeat";
 import { compileHelp } from "./help";
 import { createPageResponses } from "./page-responses";
 import { getProcessSync, startProcessSync } from "./process-sync";
+import { configurePostgresApplicationName } from "./postgres-application-name";
 import { APP_READINESS_PATH, appReadinessResponse } from "./readiness";
-import { appRegistry, type CapabilityRegistryRecord, capabilityRegistry, helpRegistry } from "./registry";
+import { appRegistry, type CapabilityRegistryRecord, capabilityRegistry } from "./registry";
 import { ensureRuntimeWatcher, getCurrentRuntime, stopRuntimeWatcher } from "./runtime-watcher";
 import { servePublicAsset } from "./static-assets";
 import { createStatusPreservingSsrHandler } from "./status-preserving-ssr";
+import { WEB_VITALS_ASSET_HREF } from "./web-vitals-asset";
 
 /** Cache-busting version stamp — changes on every server start / rebuild. */
 const v = Date.now();
@@ -76,6 +92,8 @@ export type PageOptions = {
   lang?: string;
 };
 
+type ResolvedPageOptions = PageOptions & { performanceRoute?: string };
+
 // ── Public types ────────────────────────────────────────────────────────────
 
 /**
@@ -103,6 +121,7 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
   adminHref?: string;
   /** Multi-link admin navigation contributed by this app. */
   adminNav?: ReadonlyArray<{
+    section?: "ai";
     id?: string;
     label: string;
     links: ReadonlyArray<{ label: string; href: string; icon: string }>;
@@ -136,6 +155,8 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
    * always open in a new tab from the login footer.
    */
   legalLinks?: ReadonlyArray<{ label: string; href: string; icon?: string }>;
+  /** Static destinations for the global search UI; no capabilities are created. */
+  searchLinks?: readonly AppSearchLink[];
   /**
    * Dashboard widget endpoints this app exposes. Each entry references an
    * HTTP path on this app that returns a `WidgetResponse`. The dashboard
@@ -177,9 +198,10 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
    */
   openapi?: string;
   /**
-   * Project root used by the SSR plugin to discover island/client files.
+   * Project root used for SSR component IDs and development assets.
    * Defaults to `process.cwd()`. Override only if you run the entrypoint
-   * from a directory other than the project root.
+   * from a directory other than the project root. Discovery uses APP_DIR/src
+   * (or appRoot/src) plus the installed Cloud framework source.
    */
   appRoot?: string;
 };
@@ -280,6 +302,7 @@ export const defineApp = <
 >(
   opts: AppOptions<S, N, AppId>,
 ): AppDefinition<S, N, AppId> => {
+  configurePostgresApplicationName(opts.id);
   const isDevelopment = process.env.NODE_ENV === "development";
   const notifications = bindNotificationDefinitions(opts.id, opts.notifications);
 
@@ -293,12 +316,14 @@ export const defineApp = <
   }
 
   // ── 1. SSR config ─────────────────────────────────────────────────────
-  const { config, plugin, html } = createSsrConfig<PageOptions>({
+  const rootDir = opts.appRoot ?? process.cwd();
+  const { config, plugin, html } = createSsrConfig<ResolvedPageOptions>({
     dev: isDevelopment,
     verbose: true,
-    rootDir: opts.appRoot ?? process.cwd(),
+    rootDir,
+    componentRoots: [resolve(process.env.APP_DIR ?? rootDir, "src"), fileURLToPath(new URL("../", import.meta.url))],
     basePath: opts.basePath,
-    template: ({ body, scripts, title, description, theme, lang }) => {
+    template: ({ body, scripts, title, description, theme, lang, performanceRoute }) => {
       const themeFixed = theme !== undefined;
       return `<!DOCTYPE html>
 <html lang="${normalizeLocale(lang)}" class="${theme ?? "light"}"${themeFixed ? " data-theme-fixed" : ""}>
@@ -321,6 +346,7 @@ export const defineApp = <
     ${body}
   </body>
   ${scripts}
+  ${performanceRoute ? `<script type="module" src="${WEB_VITALS_ASSET_HREF}" data-cloud-web-vitals data-app-id="${escapeHtml(opts.id)}" data-route-template="${escapeHtml(performanceRoute)}"></script>` : ""}
 </html>`;
     },
   });
@@ -336,10 +362,16 @@ export const defineApp = <
   // `getDateConfig` share one canonical `getLocale(c)` that page handlers
   // cannot override.
   const ssr = Object.assign(
-    createStatusPreservingSsrHandler<PageOptions>(html, async (c) => {
+    createStatusPreservingSsrHandler<ResolvedPageOptions>(html, async (c) => {
       c.get("page").lang = getLocale(c);
       const user = c.get("user");
-      if (user) c.set("railPreferences", await railPreferences.get(user.id));
+      c.get("page").performanceRoute =
+        user && c.get("settings")?.observability?.web_vitals?.enabled === true ? (matchedRouteTemplate(c) ?? undefined) : undefined;
+      await Promise.all([
+        preloadLayoutAnnouncements(c),
+        preloadLayoutHelp(c),
+        user ? readRailSnapshot(user).then((snapshot) => c.set("railPreferences", snapshot)) : undefined,
+      ]);
     }),
     createPageResponses(html),
   );
@@ -354,6 +386,7 @@ export const defineApp = <
     adminHref: opts.adminHref,
     adminNav: opts.adminNav?.map(
       (group): AppAdminNavigationGroup => ({
+        ...(group.section ? { section: group.section } : {}),
         id: group.id,
         label: group.label,
         links: group.links.map((link) => ({ ...link })),
@@ -362,6 +395,7 @@ export const defineApp = <
     routes: [...opts.routes],
     nav: opts.nav,
     legalLinks: opts.legalLinks ? [...opts.legalLinks] : undefined,
+    searchLinks: opts.searchLinks?.map((link) => ({ ...link, keywords: link.keywords ? [...link.keywords] : undefined })),
     widgets: opts.widgets ? opts.widgets.map((w) => ({ ...w })) : undefined,
     settingKeys: opts.settings ? Object.keys(opts.settings) : undefined,
     openapi: opts.openapi,
@@ -400,6 +434,8 @@ export const defineApp = <
         }
       })());
     try {
+      bindProcessApplicationId(meta.id);
+      cleanup.unshift(clearProcessApplicationId);
       const startedAt = Date.now();
 
       // OpenAPI advertised in the registry only when there's a router to
@@ -410,8 +446,6 @@ export const defineApp = <
       const compiledHelp = startOpts.help
         ? compileHelp({
             appId: meta.id,
-            appName: meta.name,
-            appIcon: meta.icon,
             basePath: opts.basePath,
             definition: startOpts.help,
           })
@@ -441,6 +475,7 @@ export const defineApp = <
               }
             : undefined,
         adminNav: meta.adminNav?.map((group) => ({
+          ...(group.section ? { section: group.section } : {}),
           id: group.id,
           label: group.label,
           links: group.links.map((link) => ({ ...link })),
@@ -453,6 +488,7 @@ export const defineApp = <
           : undefined,
         help: compiledHelp?.summary,
         legalLinks: meta.legalLinks ? meta.legalLinks.map((l) => ({ ...l })) : undefined,
+        searchLinks: meta.searchLinks,
         widgets: meta.widgets ? meta.widgets.map((w) => ({ ...w })) : undefined,
         settingKeys: meta.settingKeys ? [...meta.settingKeys] : undefined,
         openapi: advertiseOpenapi ? opts.openapi : undefined,
@@ -461,6 +497,7 @@ export const defineApp = <
       // Heartbeat
       const heartbeat = createHeartbeat(meta.id, entry, {
         registry: appRegistry(),
+        beforeWrite: compiledHelp ? () => registerHelp(compiledHelp.corpus) : undefined,
         onError: (error) =>
           log.error("Registry heartbeat failed", {
             appId: meta.id,
@@ -499,27 +536,6 @@ export const defineApp = <
             },
           })
         : undefined;
-      const helpHeartbeat = compiledHelp
-        ? createHeartbeat(meta.id, compiledHelp.registryEntry, {
-            key: `help/${meta.id}`,
-            registry: helpRegistry(),
-            onError: (error) =>
-              log.error("Help registry heartbeat failed", {
-                appId: meta.id,
-                error: error instanceof Error ? error.message : String(error),
-              }),
-            onStale: (error) => {
-              log.error("Help registry lease expired; restarting", {
-                appId: meta.id,
-                error: error instanceof Error ? error.message : String(error),
-              });
-              process.exit(1);
-            },
-          })
-        : undefined;
-      cleanup.push(async () => {
-        await helpHeartbeat?.stop();
-      });
       cleanup.push(async () => {
         await capabilityHeartbeat?.stop();
       });
@@ -614,6 +630,8 @@ export const defineApp = <
               user,
               idempotencyKey,
               locale: requestLocale,
+              requestId: normalizeInvocationRequestId(c.req.header("x-request-id")) ?? crypto.randomUUID(),
+              origin: CapabilityOriginSchema.catch("http").parse(c.req.header(CAPABILITY_ORIGIN_HEADER)),
               signal: c.req.raw.signal,
             },
             onUnexpectedError: (error: unknown) =>
@@ -654,6 +672,15 @@ export const defineApp = <
               schemaHash: operation.manifest.schemaHash,
             };
           });
+        for (const kind of ["queries", "actions"] as const) {
+          server.post(`/api/_internal/capabilities/v1/streams/${kind}/:capabilityId/:verb`, capabilityAuth(kind), auth.requireOAuthScope(kind === "queries" ? "read" : "write", "admin"), async c => {
+            const actor = c.get("actor");
+            return invokeCapabilityStream({ compiled: compiledCapabilities, kind, localId: c.req.param("capabilityId") ?? "", verb: c.req.param("verb") ?? "", request: c.req.raw,
+              context: { actor, accessSubject: c.get("accessSubject"), user: actor.kind === "user" ? actor.user : actor.delegatedUser,
+                locale: resolveLocale(c.req.raw.headers, await get<string>("app.locale")),
+                requestId: normalizeInvocationRequestId(c.req.header("x-request-id")) ?? crypto.randomUUID(), origin: CapabilityOriginSchema.catch("http").parse(c.req.header(CAPABILITY_ORIGIN_HEADER)), signal: c.req.raw.signal } });
+          });
+        }
         const capabilityReadScope = auth.requireOAuthScope("read", "admin");
         const capabilityWriteScope = auth.requireOAuthScope("write", "admin");
         server.post("/api/_internal/capabilities/v1/queries/:capabilityId", capabilityAuth("queries"), capabilityReadScope, (c) =>
@@ -759,7 +786,6 @@ export const defineApp = <
 
       // Only advertise after setup, workers, and their declared resources are ready.
       // Publish supporting entries first; the app entry makes them discoverable.
-      await helpHeartbeat?.start();
       await capabilityHeartbeat?.start();
       await heartbeat.start();
       log.info(`Registered "${meta.id}"`, { baseUrl });

package/src/_internal/heartbeat.ts

@@ -18,6 +18,8 @@ type HeartbeatRegistry<T> = {
 type HeartbeatOptions<T> = {
   registry: HeartbeatRegistry<T>;
   key?: string;
+  /** Publish dependent data before advertising or renewing the app. */
+  beforeWrite?: () => Promise<void>;
   intervalMs?: number;
   retryMs?: number;
   staleAfterMs?: number;
@@ -53,6 +55,7 @@ export const createHeartbeat = <T>(appId: string, entry: T, options: HeartbeatOp
   };
 
   const register = async (): Promise<void> => {
+    await options.beforeWrite?.();
     await registry.upsert({ key, value: entry });
     noteSuccess();
   };
@@ -61,6 +64,7 @@ export const createHeartbeat = <T>(appId: string, entry: T, options: HeartbeatOp
     // Touch renews the existing entry (and emits a registry invalidation).
     // Avoid rebuilding the manifest here. A missing entry is repaired
     // immediately, preserving restart-free registry recovery.
+    await options.beforeWrite?.();
     const touched = await registry.touch({ key });
     if (!touched) await registry.upsert({ key, value: entry });
     noteSuccess();