@k2b/cloud 0.42.0 → 0.44.0

package/src/contracts/capabilities.ts

@@ -4,11 +4,13 @@ import {
   CapabilityStreamPolicySchema,
   CapabilityStreamSchema,
 } from "./capability-streams";
+import { RESOURCE_PAGE_MAX_LENGTH, RESOURCE_PAGES_PER_TYPE, resourcePageIssue } from "./resource-pages";
 
 export * from "./capability-streams";
 
 import { z } from "zod";
 import type { RequestAuthority } from "../server/middleware/auth";
+import type { AppEventDefinition, AppEventSubscriptionDefinition } from "./app-events";
 import { CommandPathSchema } from "./commands";
 import type { AccessSubject, RequestActor, User } from "./shared";
 
@@ -56,6 +58,10 @@ export const CAPABILITY_ORIGINS = ["assistant", "mcp", "http", "app"] as const;
 export type CapabilityOrigin = (typeof CAPABILITY_ORIGINS)[number];
 export const CapabilityOriginSchema = z.enum(CAPABILITY_ORIGINS);
 
+/** Visible content provenance. It is metadata, never an authorization input. */
+export const CapabilityViaSchema = z.enum(["assistant", "mcp"]).nullable();
+export type CapabilityVia = z.infer<typeof CapabilityViaSchema>;
+
 /** Transports the resolved origin from the Cloud dispatcher to the app endpoint. */
 export const CAPABILITY_ORIGIN_HEADER = "x-cloud-capability-origin";
 
@@ -97,6 +103,20 @@ export const CloudResourceReferenceSchema = CloudResourceRefSchema.extend({
   title: z.string().min(1).max(500).optional().describe("Optional current user-facing resource label."),
   preview: z.string().max(2000).optional().describe("Optional short plain-text context for the resource."),
   icon: z.string().min(1).max(120).optional().describe("Optional presentation icon for the resource."),
+  context: z
+    .string()
+    .min(1)
+    .max(200)
+    .optional()
+    .describe(
+      "One line in the caller's locale that says what and where the resource is and its most useful fact, for example 'Task in IT planning · due 30 Oct'.",
+    ),
+  status: z
+    .string()
+    .min(1)
+    .max(60)
+    .optional()
+    .describe("The resource's current state as a short label in the caller's locale, for example 'Open' or 'Done'."),
 }).strict();
 
 export type CloudResourceReference = z.infer<typeof CloudResourceReferenceSchema>;
@@ -660,7 +680,7 @@ const resultSchema = <T extends z.ZodType>(
       stream: CapabilityStreamSchema.optional(),
       summary: z.string().trim().min(1).max(500).optional(),
       refs: z
-        .array(options.consumer ? LinkedCloudResourceReferenceSchema : CloudResourceReferenceSchema)
+        .array(options.consumer ? LinkedCloudResourceReferenceSchema.strip() : CloudResourceReferenceSchema)
         .max(100)
         .optional(),
       page: CapabilityPageSchema.optional(),
@@ -727,6 +747,8 @@ export const CloudResourceViewSchema = z
     title: z.string().min(1).max(500).describe("Primary result label."),
     preview: z.string().max(2000).optional().describe("Short plain-text result preview."),
     icon: z.string().min(1).max(120).optional().describe("Optional presentation icon."),
+    context: CloudResourceReferenceSchema.shape.context,
+    status: CloudResourceReferenceSchema.shape.status,
     priority: z.number().int().min(0).max(9).optional().describe("App-local relevance hint from zero to nine."),
     metadata: z
       .array(
@@ -763,6 +785,11 @@ export const UniversalSearchDataSchema = z.array(CloudResourceViewSchema).max(10
 export type UniversalSearchData = z.infer<typeof UniversalSearchDataSchema>;
 
 export type CapabilityExecutionContext = {
+  /** One read-only cross-app dependency under this invocation, through Core. */
+  query?: <T extends z.ZodType>(
+    invocation: { appId: string; capabilityId: string; input: unknown; signal?: AbortSignal },
+    dataSchema: T,
+  ) => Promise<import("../capabilities/types").CapabilityClientResult<z.output<T>>>;
   /**
    * Resolved request authority, supplied by the framework for execution, review
    * and streams. Optional for existing in-process callers; authority-aware
@@ -788,15 +815,25 @@ export type CapabilityExecutionContext = {
   requestId: string;
   /** Cloud surface that invoked this capability. */
   origin: CapabilityOrigin;
+  /** Framework-derived visible provenance; absent only in manually constructed contexts. */
+  via?: CapabilityVia;
   /** Caller cancellation or shared dispatch deadline; forward it to expensive work. */
   signal: AbortSignal;
 };
 
+/** Colours a consumer may give a resource type's icon, the same palette as `@k2b/ui` cards. */
+export const CAPABILITY_RESOURCE_COLORS = ["blue", "emerald", "violet", "orange", "red", "amber", "zinc", "cyan", "rose"] as const;
+export type CapabilityResourceColor = (typeof CAPABILITY_RESOURCE_COLORS)[number];
+
 export type CapabilityResourceTypeDefinition = {
   title: string;
   description: string;
   icon?: string;
+  /** One colour per kind of resource, so a card or list shows at a glance what it stands for. */
+  color?: CapabilityResourceColor;
   reader?: string;
+  /** Root-relative pages recognized when a person pastes a Cloud link. Requires a reader. */
+  pages?: readonly string[];
 };
 
 export type CapabilitySearchTagDefinition = {
@@ -850,6 +887,7 @@ export type CapabilityOperationPresentationTranslation = {
 };
 
 export type CapabilityPresentationTranslation = {
+  events?: Readonly<Record<string, { title?: string; description?: string }>>;
   types?: Readonly<Record<string, { title?: string; description?: string }>>;
   queries?: Readonly<Record<string, CapabilityOperationPresentationTranslation>>;
   actions?: Readonly<Record<string, CapabilityOperationPresentationTranslation>>;
@@ -940,6 +978,8 @@ 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 CapabilityCalendarSourceDeclaration = { calendars: string; events: string; update?: string; move?: string; delete?: string };
+
 export type CapabilityDefinitions = {
   protocolVersion: typeof CAPABILITY_PROTOCOL_VERSION;
   presentation?: CapabilityPresentationCatalog;
@@ -948,13 +988,28 @@ export type CapabilityDefinitions = {
   actions?: CapabilityDefinitionCatalog<CapabilityActionDefinition>;
   commands?: CapabilityDefinitionCatalog<CapabilityCommandDefinition>;
   fileProvider?: CapabilityFileProviderDeclaration;
+  calendarSource?: CapabilityCalendarSourceDeclaration;
+  events?: CapabilityDefinitionCatalog<AppEventDefinition>;
+  subscribes?: CapabilityDefinitionCatalog<AppEventSubscriptionDefinition>;
 };
 
 /**
  * Declares one app's public capability surface. Runtime compilation happens
  * in defineApp.start(), where the app id is available for namespacing.
  */
-export const defineCapabilities = <const T extends CapabilityDefinitions>(definitions: T): T => definitions;
+export function defineCapabilities<
+  const Schemas extends Readonly<Record<string, z.ZodType>>,
+  const Definitions extends Omit<CapabilityDefinitions, "subscribes">,
+>(
+  definitions: Definitions & { subscribes: { readonly [Key in keyof Schemas]: AppEventSubscriptionDefinition<Schemas[Key]> } },
+): Definitions & { subscribes: { readonly [Key in keyof Schemas]: AppEventSubscriptionDefinition<Schemas[Key]> } };
+export function defineCapabilities<const Definitions extends Omit<CapabilityDefinitions, "subscribes">>(
+  definitions: Definitions & { subscribes?: never },
+): Definitions;
+export function defineCapabilities<const Definitions extends CapabilityDefinitions>(definitions: Definitions): Definitions;
+export function defineCapabilities(definitions: CapabilityDefinitions): CapabilityDefinitions {
+  return definitions;
+}
 
 export const CapabilityResourceTypeManifestSchema = z
   .object({
@@ -962,6 +1017,7 @@ export const CapabilityResourceTypeManifestSchema = z
     title: z.string().min(1).max(120),
     description: z.string().min(1).max(500),
     icon: z.string().min(1).max(120).optional(),
+    color: z.enum(CAPABILITY_RESOURCE_COLORS).optional(),
     reader: CapabilityLocalIdSchema.optional(),
   })
   .strict();
@@ -1015,6 +1071,51 @@ export const CapabilityFileProviderManifestSchema = z
   .object({ list: CapabilityLocalIdSchema, read: CapabilityLocalIdSchema, save: CapabilityLocalIdSchema.optional() })
   .strict();
 
+export const CapabilityCalendarSourceManifestSchema = z
+  .object({
+    calendars: CapabilityLocalIdSchema,
+    events: CapabilityLocalIdSchema,
+    update: CapabilityLocalIdSchema.optional(),
+    move: CapabilityLocalIdSchema.optional(),
+    delete: CapabilityLocalIdSchema.optional(),
+  })
+  .strict();
+
+export const CapabilityEventManifestSchema = z
+  .object({
+    localId: CapabilityLocalIdSchema,
+    version: z.number().int().positive(),
+    title: z.string().trim().min(1).max(120),
+    description: z.string().trim().min(1).max(1000),
+    subject: CapabilityLocalIdSchema,
+    place: CapabilityLocalIdSchema.optional(),
+    dataSchema: z.record(z.string(), z.unknown()),
+    schemaHash: z.string().regex(/^[a-f0-9]{64}$/),
+    automation: z.literal(false).optional(),
+  })
+  .strict();
+export type CapabilityEventManifest = z.infer<typeof CapabilityEventManifestSchema>;
+
+export const CapabilitySubscriptionManifestSchema = z
+  .object({
+    type: CapabilityQualifiedIdSchema,
+    version: z.number().int().positive(),
+    dataSchema: z.record(z.string(), z.unknown()),
+    schemaHash: z.string().regex(/^[a-f0-9]{64}$/),
+  })
+  .strict();
+export type CapabilitySubscriptionManifest = z.infer<typeof CapabilitySubscriptionManifestSchema>;
+export const CapabilityResourcePageManifestSchema = z
+  .object({
+    type: CapabilityLocalIdSchema,
+    path: z
+      .string()
+      .min(1)
+      .max(RESOURCE_PAGE_MAX_LENGTH)
+      .refine((path) => !resourcePageIssue(path), "Invalid resource page pattern"),
+  })
+  .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.
@@ -1041,6 +1142,8 @@ const readEntries = <T extends z.ZodType>(values: unknown, entry: T): z.output<T
  * - An unreadable policy or one inconsistent with derived approval, review, or effect flags leaves
  *   out its Action. Policies for unknown Actions are dropped.
  *
+ * Resource pages live at the top level so older releases keep the Type and reader. Unreadable
+ * pages and pages without a readable Type/reader are omitted; live prefix ownership is checked separately.
  * Every other entry stays available.
  */
 const readableManifest = (value: unknown): unknown => {
@@ -1051,6 +1154,9 @@ const readableManifest = (value: unknown): unknown => {
   const actions = readEntries(sent.actions, CapabilityActionManifestSchema);
   const commands = readEntries(sent.commands, CapabilityCommandManifestSchema);
   if (!types || !queries || !actions || !commands) return value;
+  const events = sent.events === undefined ? undefined : readEntries(sent.events, CapabilityEventManifestSchema);
+  const subscribes = sent.subscribes === undefined ? undefined : readEntries(sent.subscribes, CapabilitySubscriptionManifestSchema);
+  if (events === null || subscribes === null) 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));
@@ -1074,11 +1180,27 @@ const readableManifest = (value: unknown): unknown => {
     policies[action.localId] = policy;
     return true;
   });
-  const { fileProvider: sentProvider, policies: _policies, ...rest } = sent;
+  const { calendarSource: sentCalendarSource, fileProvider: sentProvider, policies: _policies, resourcePages: sentPages, ...rest } = sent;
   const provider = CapabilityFileProviderManifestSchema.safeParse(sentProvider);
+  const calendar = CapabilityCalendarSourceManifestSchema.safeParse(sentCalendarSource);
+  const pageCounts = new Map<string, number>();
+  const resourcePages =
+    Array.isArray(sentPages) && sentPages.length <= MAX_MANIFEST_ENTRIES * RESOURCE_PAGES_PER_TYPE
+      ? sentPages.flatMap((value) => {
+          const page = CapabilityResourcePageManifestSchema.safeParse(value);
+          if (!page.success) return [];
+          const type = types.find((type) => type.localId === page.data.type);
+          const count = pageCounts.get(page.data.type) ?? 0;
+          if (!type?.reader || !queryIds.has(type.reader) || count >= RESOURCE_PAGES_PER_TYPE) return [];
+          pageCounts.set(page.data.type, count + 1);
+          return [page.data];
+        })
+      : [];
   return {
     ...rest,
+    ...(sentPages !== undefined ? { resourcePages } : {}),
     ...(provider.success ? { fileProvider: provider.data } : {}),
+    ...(calendar.success ? { calendarSource: calendar.data } : {}),
     types: types.map((type) => {
       if (!type.reader || queryIds.has(type.reader)) return type;
       const { reader: _missing, ...withoutReader } = type;
@@ -1088,6 +1210,16 @@ const readableManifest = (value: unknown): unknown => {
     actions: readableActions,
     ...(sentPolicies !== undefined ? { policies } : {}),
     commands,
+    ...(events
+      ? {
+          events: events.filter(
+            (event) =>
+              typeIds.has(event.subject) &&
+              (!event.place || types.some((type) => type.localId === event.place && type.reader && queryIds.has(type.reader))),
+          ),
+        }
+      : {}),
+    ...(subscribes ? { subscribes } : {}),
   };
 };
 
@@ -1107,7 +1239,14 @@ export const CapabilityManifestSchema = z.preprocess(
     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(),
+    calendarSource: CapabilityCalendarSourceManifestSchema.optional(),
     policies: z.record(CapabilityLocalIdSchema, CapabilityActionPolicySchema).optional(),
+    events: z.array(CapabilityEventManifestSchema).max(MAX_MANIFEST_ENTRIES).optional(),
+    subscribes: z.array(CapabilitySubscriptionManifestSchema).max(MAX_MANIFEST_ENTRIES).optional(),
+    resourcePages: z
+      .array(CapabilityResourcePageManifestSchema)
+      .max(MAX_MANIFEST_ENTRIES * RESOURCE_PAGES_PER_TYPE)
+      .optional(),
   }),
 );
 
@@ -1132,12 +1271,34 @@ export const resolveCapabilityResourceReader = (manifest: CapabilityManifest, re
 };
 
 /** Like the manifest, catalog entries, pages, and their pagination ignore fields that a newer Cloud release added. */
+export const CapabilityEventCatalogEntrySchema = z.object({
+  type: CapabilityQualifiedIdSchema,
+  version: z.number().int().positive(),
+  title: z.string().min(1).max(120),
+  description: z.string().min(1).max(1000),
+  subject: CapabilityQualifiedIdSchema,
+  place: CapabilityQualifiedIdSchema.nullable(),
+  automation: z.boolean(),
+  dataSchema: z.record(z.string(), z.unknown()),
+  subscribers: z.array(
+    z.object({
+      appId: CapabilityAppIdSchema,
+      subscriptionId: z.string(),
+      state: z.enum(["active", "blocked", "cancelled"]),
+      reason: z.string().nullable(),
+      firstSeenAt: z.iso.datetime({ offset: true }).optional(),
+    }),
+  ),
+});
+export type CapabilityEventCatalogEntry = z.infer<typeof CapabilityEventCatalogEntrySchema>;
+
 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,
+  events: z.array(CapabilityEventCatalogEntrySchema).max(MAX_MANIFEST_ENTRIES).optional(),
 });
 
 export const CapabilityCatalogSchema = z.object({

package/src/contracts/geo-admin.ts

@@ -55,6 +55,8 @@ export type GeoAdminUsage = {
   shares: Array<{ group: GeoUsageGroup; credits: number }>;
   /** Access subjects whose use today reached the per-person daily limit. */
   peopleAtLimit: number;
+  /** Routing estimates exceeded this month; details are in the audit view. */
+  routeCostOverruns: number;
   timezone: string;
 };
 

package/src/contracts/geo-route.ts

@@ -2,14 +2,6 @@ import { z } from "zod";
 import { GEO_MAX_POLYLINE_CHARS, GeoAddressSchema, GeoGeocodeInputSchema, GeoPointSchema, GeoProvenanceSchema } from "./geo";
 
 export const GEO_ROUTE_MAX_STOPS = 26;
-export const GeoRouteDistanceAllowanceSchema = z
-  .number()
-  .int()
-  .min(1)
-  .max(1_000_000_000)
-  .describe(
-    "Reference distance allowance in meters per leg; defaults to 500000. The whole chain reserves at this allowance. This is not a guaranteed provider bill ceiling. A larger actual route is charged and stops the chain.",
-  );
 const stopId = z.string().min(1).max(100).describe("Stable stop ID, unique within this route.");
 export const GeoRouteOptionsSchema = z
   .object({
@@ -46,7 +38,6 @@ export const GeoRouteLegOptionsSchema = z
   .strict();
 export const GeoRoutePlanSchema = z
   .object({
-    distanceAllowanceMeters: GeoRouteDistanceAllowanceSchema.optional(),
     stops: z.array(GeoRouteStopSchema).min(2).max(GEO_ROUTE_MAX_STOPS).describe("2–26 stops in travel order, with unique IDs."),
     options: GeoRouteOptionsSchema.optional().describe("Default options for the route."),
     legOptions: z
@@ -72,7 +63,6 @@ export const GeoRouteLegSchema = z
   .strict();
 export const GeoRouteSchema = z
   .object({
-    distanceAllowanceMeters: GeoRouteDistanceAllowanceSchema,
     stops: z.array(GeoRouteResolvedStopSchema).min(2).max(GEO_ROUTE_MAX_STOPS).describe("Resolved stops in current travel order."),
     options: GeoRouteOptionsSchema.describe("Travel options; mode and avoid override only supplied fields."),
     legs: z.array(GeoRouteLegSchema).min(1).max(25).describe("Independent stopover legs in travel order."),
@@ -122,7 +112,6 @@ export const GeoRouteUpdateInputSchema = z
   .object({
     route: GeoRouteSchema,
     changes: GeoRouteChangesSchema.describe("One stateless route edit to preview."),
-    distanceAllowanceMeters: GeoRouteDistanceAllowanceSchema.optional(),
   })
   .strict();
 export const GeoRouteUpdateDataSchema = z

package/src/contracts/geo.ts

@@ -188,12 +188,24 @@ export const GeoErrorDetailsSchema = z.discriminatedUnion("code", [
   z
     .object({
       code: z.literal("GEO_COST_OVERRUN"),
-      distanceAllowanceMeters: z.number().positive(),
+      adminHint: z.string().optional(),
+      estimatedDistanceMeters: z.number().nonnegative(),
+      reservedCredits: z.number().nonnegative(),
+      actualCredits: z.number().nonnegative(),
       actualDistanceMeters: z.number().nonnegative(),
       costs: GeoCostsSchema,
     })
     .strict(),
-  z.object({ code: z.literal("GEO_BUDGET_EXHAUSTED"), scope: z.enum(["person", "cloud"]), resetsAt: z.iso.datetime() }).strict(),
+  z
+    .object({
+      code: z.literal("GEO_BUDGET_EXHAUSTED"),
+      scope: z.enum(["person", "cloud"]),
+      resetsAt: z.iso.datetime(),
+      requiredCredits: z.number().nonnegative().optional(),
+      availableCredits: z.number().optional(),
+      shortfallCredits: z.number().nonnegative().optional(),
+    })
+    .strict(),
   z.object({ code: z.literal("GEO_BUSY"), retryAfterSeconds: z.number().positive(), costs: GeoCostsSchema.optional() }).strict(),
   z
     .object({

package/src/contracts/index.ts

@@ -2,6 +2,10 @@ export * from "./account-categories";
 export * from "./announcements";
 export * from "./app";
 export * from "./app-approval";
+export * from "./app-details";
+export * from "./avatar";
+export * from "./calendar-source";
+export * from "./calendar-view";
 export * from "./capabilities";
 export * from "./capability-compatibility";
 export * from "./commands";
@@ -12,6 +16,7 @@ export * from "./geo-admin";
 export * from "./geo-map";
 export * from "./geo-route";
 export * from "./geoip";
+export * from "./installable";
 export * from "./notification-types";
 export * from "./outgoing-mail";
 export * from "./panel-context";
@@ -23,6 +28,7 @@ export { RailAccessSchema, type RailAdminEntry, RailAdminInputSchema, RailAdminS
 export type { RailShortcut } from "./rail-preferences";
 export * from "./registry";
 export * from "./resource-clipboard";
+export { type ResolvedCloudResourceUrl, ResolvedCloudResourceUrlSchema } from "./resource-resolution";
 export * from "./seen-hints";
 export * from "./shared";
 export * from "./user-notifications";

package/src/contracts/installable.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+
+/** One independently installable surface, separate from the Cloud mobile app's `pwa` parts. */
+export const AppInstallableSchema = z.strictObject({
+  path: z.string(),
+  name: z.string().trim().min(1),
+  shortName: z.string().trim().min(1),
+  icon: z.string().regex(/^ti ti-[a-z0-9]+(?:-[a-z0-9]+)*$/),
+  themeColor: z.strictObject({
+    light: z.string().regex(/^#[0-9a-f]{6}$/i),
+    dark: z.string().regex(/^#[0-9a-f]{6}$/i),
+  }),
+  display: z.literal("standalone"),
+});
+export type AppInstallable = z.infer<typeof AppInstallableSchema>;
+
+/** No decoding or URL normalization: declarations must already be canonical. */
+export const isInstallablePath = (appId: string, path: string): boolean =>
+  /^[a-z][a-z0-9-]*$/.test(appId) &&
+  path.startsWith(`/app/${appId}/`) &&
+  /^\/app\/[a-z][a-z0-9-]*\/(?:[a-z0-9][a-z0-9-]*\/)+$/.test(path) &&
+  !path.split("/").slice(3).includes("help");
+
+export const installableContains = (scope: string, path: string): boolean => path === scope.slice(0, -1) || path.startsWith(scope);
+
+/** Root and /app are routing fallbacks, not evidence that an app owns a surface. */
+export const validateInstallable = (appId: string, routes: readonly string[], value: unknown): AppInstallable | null => {
+  const parsed = AppInstallableSchema.safeParse(value);
+  if (!parsed.success || !isInstallablePath(appId, parsed.data.path)) return null;
+  const ownRoot = `/app/${appId}`;
+  const covered = routes.some((route) => {
+    const prefix = route.replace(/\/$/, "");
+    return (
+      /^\/app\/[a-z][a-z0-9-]*(?:\/[a-z0-9][a-z0-9-]*)*$/.test(prefix) &&
+      (prefix === ownRoot || prefix.startsWith(`${ownRoot}/`)) &&
+      installableContains(`${prefix}/`, parsed.data.path)
+    );
+  });
+  return covered ? parsed.data : null;
+};

package/src/contracts/notification-types.ts

@@ -37,6 +37,8 @@ export type NotificationPresentation = {
   group?: string;
   /** Non-negative safe integer for the app badge; zero clears it. Browser-only. */
   badge?: number;
+  /** `false` shows or replaces the browser notification without sound or vibration. Defaults to `true`. Browser-only. */
+  alert?: boolean;
   /** Same-origin absolute path. Validated again before persistence and navigation. */
   targetHref?: `/${string}`;
 };
@@ -55,15 +57,18 @@ export type NotificationRenderContext = {
 export type NotificationDeliveryPolicy = {
   recommended?: readonly NotificationChannelId[];
   required?: readonly NotificationChannelId[];
+  /** Channels this kind never prepares for delivery, even when a saved preference selects them. */
+  excluded?: readonly NotificationChannelId[];
 };
 
 export type NotificationDefinitionPresentationTranslation = {
   label?: string;
   description?: string;
+  excludedReason?: string;
 };
 
 export type NotificationDefinitionPresentationCatalog = {
-  /** Locale of the complete `label` and `description` declaration. */
+  /** Locale of the base label, description, and optional excluded reason. */
   baseLocale: string;
   /** Partial presentation overlays with exact -> ancestor -> base fallback. */
   translations: Readonly<Record<string, NotificationDefinitionPresentationTranslation>>;
@@ -73,6 +78,8 @@ export type NotificationDefinitionInput<R extends NotificationRecipientKind, S e
   recipient: R;
   label: string;
   description: string;
+  /** Explanation shown beside excluded channels; required when delivery.excluded is non-empty. */
+  excludedReason?: string;
   presentation?: NotificationDefinitionPresentationCatalog;
   data: S;
   delivery?: NotificationDeliveryPolicy;
@@ -92,6 +99,7 @@ type AnyNotificationDefinition = Readonly<{
   recipient: NotificationRecipientKind;
   label: string;
   description: string;
+  excludedReason?: string;
   presentation?: NotificationDefinitionPresentationCatalog;
   data: ZodType;
   delivery?: NotificationDeliveryPolicy;
@@ -165,6 +173,9 @@ const compileDefinitionPresentation = (
       ...(translation.description !== undefined
         ? { description: requiredPresentationText(translation.description, `${canonical}.description`) }
         : {}),
+      ...(translation.excludedReason !== undefined
+        ? { excludedReason: requiredPresentationText(translation.excludedReason, `${canonical}.excludedReason`) }
+        : {}),
     });
   }
   return Object.freeze({ baseLocale, translations: Object.freeze(translations) });
@@ -174,20 +185,23 @@ export const resolveNotificationDefinitionPresentation = (
   definition: {
     label: string;
     description: string;
+    excludedReason?: string;
     presentation?: NotificationDefinitionPresentationCatalog | null;
   },
   requestedLocale?: string | null,
-): { label: string; description: string } => {
+): { label: string; description: string; excludedReason?: string } => {
   const catalog = definition.presentation;
-  if (!catalog || !requestedLocale) return { label: definition.label, description: definition.description };
+  const base = {
+    label: definition.label,
+    description: definition.description,
+    ...(definition.excludedReason !== undefined ? { excludedReason: definition.excludedReason } : {}),
+  };
+  if (!catalog || !requestedLocale) return base;
   const translations = new Map(Object.entries(catalog.translations));
   return localeFallbackChain(requestedLocale, catalog.baseLocale)
     .filter((locale) => locale !== catalog.baseLocale)
     .reverse()
-    .reduce((resolved, locale) => ({ ...resolved, ...translations.get(locale) }), {
-      label: definition.label,
-      description: definition.description,
-    });
+    .reduce((resolved, locale) => ({ ...resolved, ...translations.get(locale) }), base);
 };
 
 export const notification = <const R extends NotificationRecipientKind, const S extends ZodType>(
@@ -200,13 +214,20 @@ export const notification = <const R extends NotificationRecipientKind, const S
 
   const recommended = [...(input.delivery?.recommended ?? [])];
   const required = [...(input.delivery?.required ?? [])];
-  if (hasDuplicates(recommended) || hasDuplicates(required)) {
+  const excluded = [...(input.delivery?.excluded ?? [])];
+  const excludedReason = input.excludedReason === undefined ? undefined : requiredPresentationText(input.excludedReason, "excludedReason");
+  if (excluded.length > 0 && !excludedReason) throw new Error(`Notification "${label}" excludedReason is required for excluded channels`);
+  if (hasDuplicates(recommended) || hasDuplicates(required) || hasDuplicates(excluded)) {
     throw new Error(`Notification "${label}" contains duplicate delivery channels`);
   }
   const overlappingChannel = recommended.find((channel) => required.includes(channel));
   if (overlappingChannel) {
     throw new Error(`Notification "${label}" cannot recommend and require the "${overlappingChannel}" channel`);
   }
+  const excludedOverlap = excluded.find((channel) => recommended.includes(channel) || required.includes(channel));
+  if (excludedOverlap) {
+    throw new Error(`Notification "${label}" cannot exclude the recommended or required "${excludedOverlap}" channel`);
+  }
   if (input.recipient === "email" && !required.includes("email")) {
     throw new Error(`Email-recipient notification "${label}" must require the email channel`);
   }
@@ -216,8 +237,14 @@ export const notification = <const R extends NotificationRecipientKind, const S
     ...input,
     label,
     description,
+    ...(excludedReason !== undefined ? { excludedReason } : {}),
     ...(presentation ? { presentation } : {}),
-    delivery: Object.freeze({ recommended: Object.freeze(recommended), required: Object.freeze(required) }),
+    delivery: Object.freeze({
+      recommended: Object.freeze(recommended),
+      required: Object.freeze(required),
+      // Only kinds that exclude a channel carry the field, so every other definition keeps its shape.
+      ...(excluded.length > 0 ? { excluded: Object.freeze(excluded) } : {}),
+    }),
     [notificationDefinitionMarker]: true,
   };
   return Object.freeze(definition);

package/src/contracts/profile.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { AVATAR_KINDS, PersonAvatarSchema, RobotAvatarSchema } from "./avatar";
 
 /**
  * Schemas for account profile / password / request inputs. Live in core
@@ -55,6 +56,37 @@ export const UpdateAvatarResponseSchema = z.object({
 });
 export type UpdateAvatarResponse = z.infer<typeof UpdateAvatarResponseSchema>;
 
+/**
+ * One save of the profile picture dialog: store and show a photo or a built avatar, or switch to a stored picture.
+ * The photo stays stored while another kind shows; only the active picture is served.
+ */
+export const SaveAvatarSchema = z.union([
+  z.object({ dataUrl: AvatarDataUrlSchema }).strict(),
+  z.object({ built: PersonAvatarSchema }).strict(),
+  z.object({ use: z.enum(AVATAR_KINDS) }).strict(),
+]);
+export type SaveAvatar = z.infer<typeof SaveAvatarSchema>;
+
+/** A service account always shows a picture, so it switches only between its photo and its robot. */
+export const SaveServiceAccountAvatarSchema = z.union([
+  z.object({ dataUrl: AvatarDataUrlSchema }).strict(),
+  z.object({ built: RobotAvatarSchema }).strict(),
+  z.object({ use: z.enum(["photo", "built"]) }).strict(),
+]);
+export type SaveServiceAccountAvatar = z.infer<typeof SaveServiceAccountAvatarSchema>;
+
+export const AvatarStateSchema = z.object({
+  kind: z.enum(AVATAR_KINDS),
+  built: z.union([PersonAvatarSchema, RobotAvatarSchema]).nullable(),
+  hasPhoto: z.boolean(),
+  /** The stored photo as a data URL, also while another kind shows; only the account holder or an administrator reads it. */
+  photo: AvatarDataUrlSchema.nullable(),
+  avatarHash: z.string().nullable(),
+});
+export type AvatarStateResponse = z.infer<typeof AvatarStateSchema>;
+
+export const SaveAvatarResponseSchema = AvatarStateSchema.extend({ message: z.string() });
+
 export const ChangePasswordSchema = z
   .object({
     currentPassword: z.string().min(1),

package/src/contracts/pwa-builds.ts

@@ -0,0 +1,14 @@
+import type { AppRegistryEntry } from "./registry";
+
+/** Unnamed development builds do not identify a release. */
+export const pwaBuild = (runtime: { release: string; version?: string } | undefined): string | undefined =>
+  runtime && !["", "development", "local"].includes(runtime.release) ? `${runtime.version ?? ""}:${runtime.release}` : undefined;
+
+/** Only page owners and Core's shared assets can change a mobile document. */
+export const pwaBuilds = (apps: readonly AppRegistryEntry[]): Record<string, string> =>
+  Object.fromEntries(
+    apps.flatMap((app) => {
+      const build = pwaBuild(app.runtime);
+      return build && (app.id === "core" || app.id === "pwa" || app.pwa) ? [[app.id, build]] : [];
+    }),
+  );