@k2b/cloud 0.6.0-rc.0 → 0.7.0

package/src/config/env.ts

@@ -7,18 +7,20 @@ const str = (key: string, fallback: string = ""): string => process.env[key] ??
 
 const optional = (key: string): string | undefined => process.env[key]?.trim() || undefined;
 
-const int = (key: string, fallback: number): number => {
-  const value = process.env[key];
-  const parsed = parseInt(value ?? "", 10);
-  return isNaN(parsed) ? fallback : parsed;
-};
-
 const bool = (key: string, fallback: boolean): boolean => {
   const value = process.env[key]?.trim().toLowerCase();
   if (!value) return fallback;
   return value === "true" || value === "1";
 };
 
+const syncReplicas = (): 1 | 3 | 5 => {
+  const value = str("SYNC_REPLICAS", "3").trim();
+  if (value === "1") return 1;
+  if (value === "3") return 3;
+  if (value === "5") return 5;
+  throw new Error("SYNC_REPLICAS must be 1, 3, or 5");
+};
+
 const list = (key: string): string[] =>
   (process.env[key] ?? "")
     .split(",")
@@ -28,10 +30,9 @@ const list = (key: string): string[] =>
 export const env = {
   // Application (infrastructure — not changeable at runtime)
   APP_SECRET: str("APP_SECRET"),
-  PORT: int("PORT", 3000),
   IS_DEVELOPMENT: process.env.NODE_ENV === "development",
 
-  // Admin login (local emergency access — token-based, no IPA required)
+  // Admin login (temporary first access or recovery — Core only, no IPA required)
   ADMIN_LOGIN_TOKEN: str("ADMIN_LOGIN_TOKEN"),
 
   // NATS / @k2b/sync (Postgres and Redis are read by Bun from DATABASE_URL / REDIS_URL)
@@ -39,6 +40,8 @@ export const env = {
   NATS_SERVERS: list("NATS_SERVERS"),
   /** Sync namespace shared by every app of one Cloud installation (e.g. `dev`, `prod`). Required. */
   SYNC_NAMESPACE: str("SYNC_NAMESPACE"),
+  /** Persistent stream replica count; consistent across the installation. */
+  SYNC_REPLICAS: syncReplicas(),
   /** Path to a mounted NATS `.creds` file (JWT + NKey). Unset = server-side no-auth. */
   NATS_CREDS_FILE: optional("NATS_CREDS_FILE"),
   /** Path to a mounted CA certificate; enables TLS with that CA. Unset = plain TCP. */

package/src/contracts/app.ts

@@ -1,5 +1,5 @@
 import type { Sync } from "@k2b/sync";
-import type { HelpManifest } from "../shared/help";
+import type { AppRegistryHelpSummary } from "./registry";
 import type { Role } from "./shared";
 import type { DashboardWidgetPresentation } from "./widgets";
 
@@ -14,6 +14,18 @@ export type LegalLink = {
   icon?: string;
 };
 
+/** Static page links for the global search UI, ranked after resource results.
+ * These declare navigation only; they do not create capabilities or readers.
+ */
+export type AppSearchLink = {
+  label: string;
+  /** Optional plain-text context shown with the result and its preview. */
+  description?: string;
+  href: string;
+  icon?: string;
+  keywords?: readonly string[];
+};
+
 export type AppAppearanceColor = `#${string}`;
 
 export type AppAppearance = {
@@ -35,6 +47,8 @@ export type AppAdminNavigationLink = {
 };
 
 export type AppAdminNavigationGroup = {
+  /** Contribute links to the platform AI section instead of a separate group. */
+  section?: "ai";
   /** Stable key used only to localize this presentation group. */
   id?: string;
   label: string;
@@ -50,10 +64,14 @@ export type AppPresentationTranslation = {
   adminLinks?: Readonly<Record<string, string>>;
   /** Legal-link labels keyed by their stable same-origin href. */
   legalLinks?: Readonly<Record<string, string>>;
+  /** Search-link labels keyed by their stable same-origin href. */
+  searchLinks?: Readonly<Record<string, string>>;
+  /** Search-link descriptions keyed by their stable same-origin href. */
+  searchLinkDescriptions?: Readonly<Record<string, string>>;
 };
 
 export type AppPresentationCatalog = {
-  /** Locale of the complete `name`, `description`, `adminNav`, and `legalLinks` declaration. */
+  /** Locale of the complete `name`, `description`, `adminNav`, `legalLinks`, and `searchLinks` declaration. */
   baseLocale: string;
   /** Partial presentation overlays with exact -> ancestor -> base fallback. */
   translations: Readonly<Record<string, AppPresentationTranslation>>;
@@ -87,6 +105,8 @@ export type AppMeta = {
    * contributes its own (e.g. settings → terms/privacy/imprint, faq → FAQ).
    */
   legalLinks?: LegalLink[];
+  /** Static search destinations, visible when the app is in the user's navigation catalog. */
+  searchLinks?: readonly AppSearchLink[];
   /**
    * Dashboard widget endpoints this app exposes. Each entry references an
    * HTTP endpoint that returns a `WidgetResponse` (see `contracts/widgets.ts`).
@@ -111,7 +131,7 @@ export type WidgetEndpoint = {
 };
 
 export type RuntimeAppMeta = AppMeta & {
-  help?: HelpManifest;
+  help?: AppRegistryHelpSummary;
   searchTags?: string[];
   searchHelp?: string;
   searchTagHelp?: AppSearchTagHelpEntry[];

package/src/contracts/capabilities.ts

@@ -1,7 +1,10 @@
+import { CapabilityStreamSchema, CapabilityStreamPolicySchema, type CapabilityStream, type CapabilityStreamDefinition } from "./capability-streams";
+export * from "./capability-streams";
 import { z } from "zod";
+import { CommandPathSchema } from "./commands";
 import type { AccessSubject, RequestActor, User } from "./shared";
 
-export const CAPABILITY_PROTOCOL_VERSION = 1 as const;
+export const CAPABILITY_PROTOCOL_VERSION = 2 as const;
 export const CAPABILITY_MAX_REQUEST_BYTES = 256 * 1024;
 export const CAPABILITY_MAX_RESULT_BYTES = 256 * 1024;
 export const CAPABILITY_MAX_CATALOG_BYTES = 2 * 1024 * 1024;
@@ -14,6 +17,8 @@ export const CAPABILITY_FRAMEWORK_ERROR_CODES = {
   idempotencyKeyRequired: "IDEMPOTENCY_KEY_REQUIRED",
   idempotencyKeyNotAllowed: "IDEMPOTENCY_KEY_NOT_ALLOWED",
   idempotencyConflict: "IDEMPOTENCY_CONFLICT",
+  idempotencyInProgress: "IDEMPOTENCY_IN_PROGRESS",
+  idempotencyUncertain: "IDEMPOTENCY_UNCERTAIN",
   deadlineExceeded: "DEADLINE_EXCEEDED",
   actionOutcomeUnknown: "ACTION_OUTCOME_UNKNOWN",
   requestCancelled: "REQUEST_CANCELLED",
@@ -32,6 +37,17 @@ export const capabilityIdempotencyConflict = (
   ...(details ? { details } : {}),
 });
 
+/**
+ * Cloud surface a capability invocation came from. The dispatcher resolves it
+ * once, records it on the execution row, and forwards it to the owning app.
+ */
+export const CAPABILITY_ORIGINS = ["assistant", "mcp", "http", "app"] as const;
+export type CapabilityOrigin = (typeof CAPABILITY_ORIGINS)[number];
+export const CapabilityOriginSchema = z.enum(CAPABILITY_ORIGINS);
+
+/** Transports the resolved origin from the Cloud dispatcher to the app endpoint. */
+export const CAPABILITY_ORIGIN_HEADER = "x-cloud-capability-origin";
+
 export const CapabilityIdempotencyKeySchema = z
   .string()
   .trim()
@@ -94,10 +110,13 @@ const CapabilityActionReviewDetailSchema = z
     label: z.string().min(1).max(120),
     value: z.string().max(10_000),
     display: z.enum(["inline", "block"]).optional(),
-    format: z.enum(["date", "date-time"]).optional(),
+    format: z.enum(["date", "date-time", "markdown"]).optional(),
   })
   .strict()
   .superRefine((detail, context) => {
+    if (detail.format === "markdown" && detail.display !== "block") {
+      context.addIssue({ code: "custom", path: ["display"], message: "Markdown review details require block display" });
+    }
     const schema =
       detail.format === "date" ? CapabilityReviewDateSchema : detail.format === "date-time" ? CapabilityReviewDateTimeSchema : null;
     if (schema?.safeParse(detail.value).success === false) {
@@ -175,6 +194,7 @@ export const capabilityDataAtPath = (data: unknown, path: readonly string[]): un
 
 export type CapabilityResult<T> = {
   data: T;
+  stream?: CapabilityStream;
   /** Provider-authored, user-facing summary of the successful result. Render as escaped plain text. */
   summary?: string;
   refs?: CloudResourceReference[];
@@ -190,6 +210,7 @@ export const capabilityResultSchema = <T extends z.ZodType>(
   z
     .object({
       data,
+      stream: CapabilityStreamSchema.optional(),
       summary: z.string().trim().min(1).max(500).optional(),
       refs: z.array(CloudResourceReferenceSchema).max(100).optional(),
       page: CapabilityPageSchema.optional(),
@@ -264,6 +285,9 @@ export const UniversalSearchInputSchema = z
   .object({
     query: z.string().max(500).describe("User-entered search text. Empty text is allowed when a facet narrows the query."),
     tags: z.array(z.string().min(1).max(64)).max(20).describe("Canonical search facets supported by this query."),
+    scope: CloudResourceRefSchema.optional().describe(
+      "Optional resource containing the search results; must be an explicitly supported scope type.",
+    ),
     limit: z.number().int().min(1).max(100).describe("Maximum number of results to return."),
   })
   .strict();
@@ -285,6 +309,14 @@ export type CapabilityExecutionContext = {
    * error codes and data must not depend on it.
    */
   locale: string;
+  /**
+   * Correlation id of the originating Cloud request. Write it into the app's
+   * own audit rows so a capability execution record and the app's domain trail
+   * can be joined without sharing payloads.
+   */
+  requestId: string;
+  /** Cloud surface that invoked this capability. */
+  origin: CapabilityOrigin;
   signal: AbortSignal;
 };
 
@@ -304,6 +336,8 @@ export type CapabilitySearchTagDefinition = {
 
 export type CapabilityUniversalSearchDefinition = {
   tags: readonly CapabilitySearchTagDefinition[];
+  /** Local resource types whose contents this Query can search. */
+  scopeTypes?: readonly string[];
 };
 
 export type CapabilitySchemaPresentation = Readonly<Record<string, string>>;
@@ -323,6 +357,7 @@ export type CapabilityPresentationTranslation = {
   types?: Readonly<Record<string, { title?: string; description?: string }>>;
   queries?: Readonly<Record<string, CapabilityOperationPresentationTranslation>>;
   actions?: Readonly<Record<string, CapabilityOperationPresentationTranslation>>;
+  commands?: Readonly<Record<string, Pick<CapabilityOperationPresentationTranslation, "title" | "description" | "input">>>;
 };
 
 export type CapabilityPresentationCatalog = {
@@ -338,6 +373,7 @@ export type CapabilityQueryDefinition<Input extends z.ZodType = z.ZodType<any>,
   input: Input;
   data: Data;
   openWorld: boolean;
+  stream?: CapabilityStreamDefinition;
   universalSearch?: CapabilityUniversalSearchDefinition;
   run: (
     input: z.output<Input>,
@@ -346,7 +382,7 @@ export type CapabilityQueryDefinition<Input extends z.ZodType = z.ZodType<any>,
 };
 
 export type CapabilityIdempotencyPolicy = "none" | "required";
-export type CapabilityActionApprovalPolicy = "rememberable";
+export type CapabilityActionApprovalPolicy = "rememberable" | "none";
 
 export type CapabilityActionDefinition<Input extends z.ZodType = z.ZodType<any>, Data extends z.ZodType = z.ZodType<any>> = {
   title: string;
@@ -355,6 +391,7 @@ export type CapabilityActionDefinition<Input extends z.ZodType = z.ZodType<any>,
   data: Data;
   destructive: boolean;
   openWorld: boolean;
+  stream?: CapabilityStreamDefinition;
   idempotency: CapabilityIdempotencyPolicy;
   approval?: CapabilityActionApprovalPolicy;
   review?: (
@@ -367,6 +404,29 @@ export type CapabilityActionDefinition<Input extends z.ZodType = z.ZodType<any>,
   ) => CapabilityInvocationResult<z.output<Data>> | Promise<CapabilityInvocationResult<z.output<Data>>>;
 };
 
+/** A declarative UI entry. Resolution never executes application code or writes domain data. */
+export type CapabilityCommandDefinition = {
+  title: string;
+  description: string;
+  icon?: string;
+  keywords?: readonly string[];
+  input: z.ZodType;
+  path: string;
+};
+
+export const CapabilityCommandManifestSchema = z
+  .object({
+    localId: CapabilityLocalIdSchema,
+    title: z.string().min(1).max(120),
+    description: z.string().min(1).max(1000),
+    icon: z.string().min(1).max(120).optional(),
+    keywords: z.array(z.string().min(1).max(120)).max(30),
+    inputSchema: z.record(z.string(), z.unknown()),
+    path: CommandPathSchema,
+  })
+  .strict();
+export type CapabilityCommandManifest = z.infer<typeof CapabilityCommandManifestSchema>;
+
 type CapabilityDefinitionCatalog<T> = Readonly<Record<string, T>>;
 
 export type CapabilityDefinitions = {
@@ -375,6 +435,7 @@ export type CapabilityDefinitions = {
   types?: CapabilityDefinitionCatalog<CapabilityResourceTypeDefinition>;
   queries?: CapabilityDefinitionCatalog<CapabilityQueryDefinition>;
   actions?: CapabilityDefinitionCatalog<CapabilityActionDefinition>;
+  commands?: CapabilityDefinitionCatalog<CapabilityCommandDefinition>;
 };
 
 /**
@@ -409,6 +470,7 @@ const CapabilityOperationManifestBaseSchema = z
     description: z.string().min(1).max(1000),
     inputSchema: z.record(z.string(), z.unknown()),
     dataSchema: z.record(z.string(), z.unknown()),
+    stream: CapabilityStreamPolicySchema.optional(),
     schemaHash: z.string().regex(/^[a-f0-9]{64}$/),
   })
   .strict();
@@ -416,7 +478,7 @@ const CapabilityOperationManifestBaseSchema = z
 export const CapabilityQueryManifestSchema = CapabilityOperationManifestBaseSchema.extend({
   openWorld: z.boolean(),
   universalSearch: z
-    .object({ tags: z.array(CapabilitySearchTagManifestSchema).max(100) })
+    .object({ tags: z.array(CapabilitySearchTagManifestSchema).max(100), scopeTypes: z.array(CapabilityLocalIdSchema).max(100).optional() })
     .strict()
     .optional(),
 }).strict();
@@ -425,7 +487,7 @@ export const CapabilityActionManifestSchema = CapabilityOperationManifestBaseSch
   destructive: z.boolean(),
   openWorld: z.boolean(),
   idempotency: z.enum(["none", "required"]),
-  approval: z.literal("rememberable").optional(),
+  approval: z.enum(["rememberable", "none"]).optional(),
   review: z.literal(true).optional(),
 }).strict();
 
@@ -443,6 +505,7 @@ export const CapabilityManifestSchema = z
     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();
 

package/src/contracts/capability-streams.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import type { CapabilityExecutionContext, CapabilityResult } from "./capabilities";
+
+/** One binary payload. Provider IDs are limited to 2 KiB UTF-8; Core seals them into opaque references, never URLs. */
+export const CapabilityStreamSchema = z
+  .object({
+    id: z.string().min(1).max(8192),
+    direction: z.enum(["read", "write"]),
+    name: z.string().min(1).max(255).optional(),
+    mediaType: z
+      .string()
+      .min(1)
+      .max(255)
+      .regex(/^[\x20-\x7e]+$/),
+    size: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    expiresAt: z.iso.datetime(),
+  })
+  .strict();
+export type CapabilityStream = z.infer<typeof CapabilityStreamSchema>;
+export const CapabilityStreamPolicySchema = z
+  .object({
+    direction: z.enum(["read", "write"]),
+    maxBytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  })
+  .strict();
+export const CapabilityStreamStatusSchema = z.discriminatedUnion("state", [
+  z.object({ state: z.literal("open") }).strict(),
+  z.object({ state: z.literal("aborted") }).strict(),
+  z.object({ state: z.literal("completed"), result: z.unknown() }).strict(),
+]);
+export type CapabilityStreamStatus = z.infer<typeof CapabilityStreamStatusSchema>;
+export type CapabilityStreamDefinition = z.infer<typeof CapabilityStreamPolicySchema> &
+  (
+    | { direction: "read"; read: (stream: CapabilityStream, context: CapabilityExecutionContext) => Promise<Response> }
+    | {
+        direction: "write";
+        /** Consume completely, then publish. Must reconcile retries using stream.id. */
+        write: (
+          stream: CapabilityStream,
+          body: ReadableStream<Uint8Array>,
+          context: CapabilityExecutionContext,
+        ) => Promise<CapabilityResult<unknown>>;
+        status: (stream: CapabilityStream, context: CapabilityExecutionContext) => Promise<CapabilityStreamStatus>;
+        abort: (stream: CapabilityStream, context: CapabilityExecutionContext) => Promise<void>;
+      }
+  );

package/src/contracts/commands.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+
+/** Commands carry small public references/options, never document bodies or secrets. */
+export const COMMAND_MAX_URL_LENGTH = 8192;
+export const CommandPathSchema = z
+  .string()
+  .max(2000)
+  .refine((value) => {
+    if (!value.startsWith("/") || /[\\\u0000-\u0020]/u.test(value)) return false;
+    try {
+      return new URL(value, "https://cloud.invalid").origin === "https://cloud.invalid";
+    } catch {
+      return false;
+    }
+  }, "Expected a Cloud path");
+
+export const CommandOptionsSchema = z.object({ returnTo: CommandPathSchema.optional() }).strict();
+export type CommandOptions = z.infer<typeof CommandOptionsSchema>;
+export const CommandRequestSchema = CommandOptionsSchema.extend({ input: z.unknown() }).strict();
+export const CommandLinkSchema = z.object({ href: z.url().max(COMMAND_MAX_URL_LENGTH) }).strict();
+
+export const commandPath = (path: string, command: string, input: unknown, options: CommandOptions = {}): string => {
+  const url = new URL(CommandPathSchema.parse(path), "https://cloud.invalid");
+  url.searchParams.set("command", command);
+  url.searchParams.set("commandInput", JSON.stringify(input));
+  const parsed = CommandOptionsSchema.parse(options);
+  if (parsed.returnTo) url.searchParams.set("commandReturn", parsed.returnTo);
+  else url.searchParams.delete("commandReturn");
+  const result = `${url.pathname}${url.search}${url.hash}`;
+  if (result.length > COMMAND_MAX_URL_LENGTH) throw new Error("Command link is too large");
+  return result;
+};
+
+export const readCommand = (url: URL) => {
+  const id = url.searchParams.get("command");
+  if (!id) return null;
+  const raw = url.searchParams.get("commandInput") ?? "{}";
+  if (url.href.length > COMMAND_MAX_URL_LENGTH) throw new Error("Command link is too large");
+  return {
+    id,
+    input: JSON.parse(raw) as unknown,
+    options: CommandOptionsSchema.parse({ returnTo: url.searchParams.get("commandReturn") ?? undefined }),
+  };
+};
+
+export const clearCommand = (url: URL): string => {
+  for (const key of ["command", "commandInput", "commandReturn"]) url.searchParams.delete(key);
+  return `${url.pathname}${url.search}${url.hash}`;
+};

package/src/contracts/index.ts

@@ -2,7 +2,6 @@ export * from "./account-categories";
 export * from "./announcements";
 export * from "./app";
 export * from "./capabilities";
-export * from "./notification-live";
 export * from "./notification-types";
 export * from "./posix";
 export * from "./profile";
@@ -12,3 +11,9 @@ export * from "./shared";
 export * from "./user-notifications";
 export * from "./widgets";
 export * from "./app-approval";
+
+// Core app bar administration and shared shortcut values.
+export { RailAccessSchema, RailAdminInputSchema, RailAdminSchema, type RailAdminEntry, type RailAdminState } from "./rail-admin";
+export type { RailShortcut } from "./rail-preferences";
+
+export * from "./commands";

package/src/contracts/rail-admin.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { RAIL_PREFERENCES_MAX_BYTES, RailShortcutSchema } from "./rail-preferences";
+import { AccessEntrySchema } from "./shared";
+
+export const RailAccessSchema = AccessEntrySchema.extend({
+  principal: z.discriminatedUnion("type", [
+    z.object({ type: z.literal("authenticated") }).strict(),
+    z.object({ type: z.literal("user"), userId: z.uuid() }).strict(),
+    z.object({ type: z.literal("group"), groupId: z.uuid() }).strict(),
+  ]),
+  permission: z.literal("read"),
+});
+export const RailAdminEntrySchema = z.object({ shortcut: RailShortcutSchema, access: z.array(RailAccessSchema) }).strict();
+const revision = z.number().int().nonnegative().max(2_147_483_647);
+export const RailAdminSchema = z.object({ revision, entries: z.array(RailAdminEntrySchema) }).strict();
+/** Strip presentation metadata from editor drafts before sending or persisting grants. */
+export const RailAdminInputSchema = z
+  .object({
+    revision,
+    entries: z.array(
+      z
+        .object({
+          shortcut: RailShortcutSchema,
+          access: z.array(RailAccessSchema.pick({ principal: true, permission: true })),
+        })
+        .strict(),
+    ),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (new TextEncoder().encode(JSON.stringify(value)).byteLength > RAIL_PREFERENCES_MAX_BYTES)
+      ctx.addIssue({ code: "custom", message: "Global app bar configuration exceeds 16 KiB" });
+    if (new Set(value.entries.map((entry) => entry.shortcut.id)).size !== value.entries.length)
+      ctx.addIssue({ code: "custom", message: "Shortcut IDs must be unique" });
+  });
+export type RailAdminInput = z.infer<typeof RailAdminInputSchema>;
+export type RailAdminState = z.infer<typeof RailAdminSchema>;
+export type RailAdminEntry = z.infer<typeof RailAdminEntrySchema>;

package/src/contracts/rail-preferences.ts

@@ -51,3 +51,19 @@ export const RailPreferencesSchema = z
   });
 export type RailPreferences = z.infer<typeof RailPreferencesSchema>;
 export const defaultRailPreferences = (): RailPreferences => ({ revision: 0, visibility: {}, shortcuts: [] });
+
+/** Managed entries are separate from the writable personal API contract. */
+export type RailSnapshot = RailPreferences & { managedShortcuts?: RailShortcut[] };
+export const RailSnapshotSchema = z
+  .object({
+    revision: z.number(),
+    visibility: z.record(z.string(), z.boolean()),
+    shortcuts: z.array(RailShortcutSchema),
+    managedShortcuts: z.array(RailShortcutSchema).optional(),
+  })
+  .strict()
+  .superRefine(({ managedShortcuts, ...personal }, ctx) => {
+    if (!RailPreferencesSchema.safeParse(personal).success) ctx.addIssue({ code: "custom", message: "Invalid personal app bar settings" });
+    if (new TextEncoder().encode(JSON.stringify(managedShortcuts ?? [])).byteLength > RAIL_PREFERENCES_MAX_BYTES)
+      ctx.addIssue({ code: "custom", message: "Managed shortcuts exceed the 16 KiB page budget" });
+  });

package/src/contracts/registry.ts

@@ -1,5 +1,4 @@
-import type { HelpManifest } from "../shared/help";
-import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPresentationCatalog } from "./app";
+import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPresentationCatalog, AppSearchLink } from "./app";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "./capabilities";
 import type { Role } from "./shared";
 import type { DashboardWidgetPresentation } from "./widgets";
@@ -36,31 +35,7 @@ export type CapabilityRegistryEntry = {
   presentation?: CapabilityPresentationCatalog;
 };
 
-export type AppRegistryHelpSummary = HelpManifest;
-
-export type HelpRegistryDocument = {
-  id: string;
-  title: string;
-  icon?: string;
-  description?: string;
-  order: number;
-  markdown: string;
-  /** Precomputed by the app. Older registry entries may omit it during rolling upgrades. */
-  searchText?: string;
-};
-
-/** Full Markdown lives separately so normal app discovery stays small. */
-export type HelpRegistryEntry = {
-  appId: string;
-  appName: string;
-  appIcon: string;
-  manifestHash: string;
-  /** Base language that owns the complete logical article set. Absent on legacy registrations. */
-  baseLocale?: string;
-  /** Partial localized article variants stored in the same bounded logical registration. */
-  documentsByLocale?: Readonly<Record<string, readonly HelpRegistryDocument[]>>;
-  documents: readonly HelpRegistryDocument[];
-};
+export type AppRegistryHelpSummary = { manifestHash: string; pageBase: string; baseLocale: string };
 
 export type AppRegistryLegalLink = {
   label: string;
@@ -102,6 +77,7 @@ export type AppRegistryEntry = {
   capabilities?: AppRegistryCapabilitySummary;
   help?: AppRegistryHelpSummary;
   legalLinks?: AppRegistryLegalLink[];
+  searchLinks?: readonly AppSearchLink[];
   widgets?: AppRegistryWidget[];
   /** Setting keys declared by this app. Used by admin tooling to avoid treating live app-owned settings as legacy. */
   settingKeys?: readonly string[];

package/src/contracts/settings-types.ts

@@ -43,7 +43,7 @@ type StringLikeKind = "string" | "text" | "email" | "url" | "secret" | "image" |
 export type AppSettingDef =
   | (CommonDef & { kind: StringLikeKind; default: string; placeholder?: string; templateVars?: readonly string[] })
   | (CommonDef & { kind: "boolean"; default: boolean })
-  | (CommonDef & { kind: "number"; default: number; min?: number; max?: number; placeholder?: string })
+  | (CommonDef & { kind: "number"; default: number; min?: number; max?: number; integer?: boolean; placeholder?: string })
   | (CommonDef & { kind: "enum"; default: string; options: ReadonlyArray<SettingOption> })
   | (CommonDef & { kind: "string_list"; default: readonly string[]; placeholder?: string })
   | (CommonDef & { kind: "number_list"; default: readonly number[]; placeholder?: string });

package/src/contracts/shared.ts

@@ -288,12 +288,16 @@ export const AccountActivityListResponseSchema = z.object({
 });
 export type AccountActivityListResponse = z.infer<typeof AccountActivityListResponseSchema>;
 
+export const AuthenticatedPrincipalSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("user").describe("One user account."), userId: z.uuid().describe("Exact user ID returned by the Accounts directory.") }),
+  z.object({ type: z.literal("group").describe("Members of one group."), groupId: z.uuid().describe("Exact group ID returned by the Accounts directory.") }),
+  z.object({ type: z.literal("service_account").describe("One service account."), serviceAccountId: z.uuid().describe("Exact service account ID returned by the Accounts directory.") }),
+  z.object({ type: z.literal("authenticated").describe("Every authenticated identity; no directory ID is needed.") }),
+]);
+
 export const PrincipalSchema = z.discriminatedUnion("type", [
-  z.object({ type: z.literal("user"), userId: z.uuid() }),
-  z.object({ type: z.literal("group"), groupId: z.uuid() }),
-  z.object({ type: z.literal("service_account"), serviceAccountId: z.uuid() }),
-  z.object({ type: z.literal("authenticated") }),
-  z.object({ type: z.literal("public") }),
+  ...AuthenticatedPrincipalSchema.options,
+  z.object({ type: z.literal("public").describe("Public access where supported by the resource; no directory ID is needed.") }),
 ]);
 export type Principal = z.infer<typeof PrincipalSchema>;
 

package/src/contracts/web-vitals.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+
+/** One metric plus six server phases and bounded routing metadata. */
+export const WEB_VITALS_MAX_BYTES = 4096;
+export const WebVitalsReportSchema = z
+  .object({
+    appId: z
+      .string()
+      .min(1)
+      .max(64)
+      .regex(/^[a-z0-9-]+$/),
+    routeTemplate: z
+      .string()
+      .min(1)
+      .max(200)
+      .regex(/^\/[a-zA-Z0-9_/:.*-]*$/),
+    id: z.string().min(1).max(100),
+    name: z.enum(["LCP", "INP", "CLS"]),
+    value: z.number().nonnegative(),
+    navigationType: z.string().max(32),
+    serverTiming: z.partialRecord(
+      z.enum(["auth", "settings", "runtime", "ssr_data", "ssr_finalize", "ssr_render"]),
+      z.number().nonnegative(),
+    ),
+  })
+  .strict();
+export type WebVitalsReport = z.infer<typeof WebVitalsReportSchema>;

package/src/desktop/solid.tsx

@@ -1,4 +1,4 @@
-import { deserialize, serialize } from "seroval";
+import { deserialize as deserializeProps, serialize as serializeProps } from "seroval";
 import type { Component, JSX, ParentProps } from "solid-js";
 import { children, createContext, createEffect, createMemo, createSignal, For, onCleanup, onMount, Show, useContext } from "solid-js";
 import { Dynamic, Portal } from "solid-js/web";
@@ -47,7 +47,7 @@ export const defineDesktopWindows = <Definitions extends Record<string, DesktopW
       ({
         kind: desktopWindowDescriptorKind,
         name,
-        props: serialize(props ?? {}),
+        props: serializeProps(props ?? {}),
       }) satisfies DesktopWindowDescriptor as unknown as JSX.Element;
   }
 
@@ -73,7 +73,7 @@ export function DesktopWindowHost<Definitions extends Record<string, DesktopWind
   const windowProps = createMemo(() => {
     const current = descriptor();
     if (!current) return {};
-    return deserialize<Record<string, unknown>>(current.props);
+    return deserializeProps<Record<string, unknown>>(current.props);
   });
 
   return createMemo(() => {

package/src/index.ts

@@ -16,15 +16,11 @@ export {
   APP_REGISTRY_PREFIX,
   APP_REGISTRY_TTL_MS,
   CAPABILITY_REGISTRY_CONFIG,
-  HELP_REGISTRY_CONFIG,
   appRegistry,
   capabilityRegistry,
   getApp,
-  getHelp,
-  helpRegistry,
   listApps,
   listAppsDetailed,
-  listHelp,
   listLegalLinks,
   listWidgets,
   readAppRegistrySnapshot,

package/src/server/index.ts

@@ -9,6 +9,7 @@ export { DEFAULT_LOCALE, getLocale, LOCALE_COOKIE, LOCALE_HEADER, locale, prefer
 export type {
   AuthContext,
   InvocationProvenance,
+  InvocationExpectation,
   RateLimitConfig,
   RateLimitRouteOverride,
   RequestActor,
@@ -25,6 +26,7 @@ export {
   openApiMeta,
   rateLimit,
   rejectReservedWorkloadCredential,
+  requireInvocation,
   requestLogger,
   requiresAdmin,
   requiresAuth,
@@ -56,6 +58,7 @@ export type {
   ServiceErrorCode,
 } from "./services";
 export {
+  accessRevision,
   buildAccessPrincipalCondition,
   buildAccessPrincipalTierConditions,
   createAccess,