@k2b/cloud 0.43.0 → 0.44.0

package/src/contracts/app-details.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { PlatformPermissionSchema } from "./outgoing-mail";
+import { RoleSchema } from "./shared";
+
+/** Match the administrative event API's maximum page size. Totals make truncation visible. */
+export const APP_DETAILS_LIST_LIMIT = 100;
+export const APP_DETAILS_FAILED_LIMIT = 5;
+export const APP_SUBSCRIPTION_NEW_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+
+const count = z.number().int().nonnegative();
+const deliveryCounts = z.object({ pending: count, retrying: count, done: count, failed: count, cancelled: count });
+
+export const AppDetailsSchema = z.object({
+  app: z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().nullable(),
+    icon: z.string().nullable(),
+    accent: z.templateLiteral(["#", z.string()]).nullable(),
+    online: z.boolean(),
+  }),
+  access: z.object({
+    /** Null means Core has no current access declaration for an offline app. */
+    kind: z.enum(["grants", "signedIn", "noGuests", "roles", "resources", "legacy"]).nullable(),
+    roles: z.array(RoleSchema),
+    grantCount: count.nullable(),
+    platformPermissions: z.array(PlatformPermissionSchema),
+  }),
+  sends: z
+    .array(
+      z.object({
+        type: z.string(),
+        version: z.number().int().positive(),
+        title: z.string(),
+        description: z.string(),
+        subject: z.string(),
+        place: z.string().nullable(),
+        automation: z.boolean(),
+        subscriberCount: count,
+      }),
+    )
+    .max(APP_DETAILS_LIST_LIMIT),
+  hears: z
+    .array(
+      z.object({
+        subscriptionId: z.string(),
+        eventType: z.string(),
+        version: z.number().int().positive(),
+        publisherAppId: z.string(),
+        title: z.string().nullable(),
+        state: z.enum(["active", "blocked", "cancelled"]),
+        reason: z.string().nullable(),
+        firstSeenAt: z.iso.datetime(),
+        isNew: z.boolean(),
+        counts: deliveryCounts,
+        failedDeliveries: z
+          .array(
+            z.object({
+              id: z.uuid(),
+              eventId: z.uuid(),
+              code: z.string().nullable(),
+              lastError: z.string().max(1000).nullable(),
+              attempts: count,
+              lastAttemptAt: z.iso.datetime().nullable(),
+            }),
+          )
+          .max(APP_DETAILS_FAILED_LIMIT),
+      }),
+    )
+    .max(APP_DETAILS_LIST_LIMIT),
+  notifications: z
+    .array(
+      z.object({
+        id: z.string(),
+        kind: z.string(),
+        label: z.string(),
+        description: z.string(),
+        recipientKind: z.enum(["user", "email"]),
+        requiredChannels: z.array(z.string()),
+        recommendedChannels: z.array(z.string()),
+        excludedChannels: z.array(z.string()),
+        excludedReason: z.string().nullable(),
+      }),
+    )
+    .max(APP_DETAILS_LIST_LIMIT),
+  totals: z.object({ sends: count, hears: count, notifications: count }),
+});
+
+export type AppDetails = z.infer<typeof AppDetailsSchema>;

package/src/contracts/app-events.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { CapabilityAppIdSchema, CapabilityQualifiedIdSchema, CloudResourceRefSchema } from "./capabilities";
+
+/** Maximum PostgreSQL jsonb-text size of the complete envelope, including separator spaces. */
+export const APP_EVENT_MAX_BYTES = 4096;
+
+export const AppEventEnvelopeSchema = z
+  .object({
+    id: z.uuid(),
+    type: CapabilityQualifiedIdSchema,
+    version: z.number().int().positive(),
+    source: CapabilityAppIdSchema,
+    time: z.iso.datetime({ offset: true }),
+    subject: CloudResourceRefSchema,
+    place: CloudResourceRefSchema.optional(),
+    cause: z
+      .object({ requestId: z.string().min(1).max(256) })
+      .strict()
+      .optional(),
+    data: z.json(),
+  })
+  .strict();
+
+export type AppEventEnvelope<Data = unknown> = Omit<z.infer<typeof AppEventEnvelopeSchema>, "data"> & { data: Data };
+
+/** Delivery runs as the subscribing service, without a user's request authority. */
+export type AppEventDeliveryContext = {
+  subscriptionId: string;
+  eventId: string;
+  attempt: number;
+  signal: AbortSignal;
+};
+
+export type AppEventDefinition<Schema extends z.ZodType = z.ZodType> = {
+  version: number;
+  title: string;
+  description: string;
+  subject: string;
+  place?: string;
+  schema: Schema;
+  automation?: false;
+};
+
+export type AppEventSubscriptionDefinition<Schema extends z.ZodType = z.ZodType> = {
+  version: number;
+  schema: Schema;
+  run(envelope: AppEventEnvelope<z.output<Schema>>, context: AppEventDeliveryContext): unknown | Promise<unknown>;
+};
+
+export const appEventSubscriptionId = (subscriber: string, type: string, version: number): string =>
+  `${CapabilityAppIdSchema.parse(subscriber)}:${CapabilityQualifiedIdSchema.parse(type)}@${z.number().int().positive().parse(version)}`;

package/src/contracts/app.ts

@@ -50,9 +50,16 @@ export type AppAdminNavigationLink = {
   icon: string;
 };
 
+/** Platform admin areas an app can contribute to with `adminNav[].section`. */
+export const APP_ADMIN_AREAS = ["ai", "observability"] as const;
+export type AppAdminArea = (typeof APP_ADMIN_AREAS)[number];
+
 export type AppAdminNavigationGroup = {
-  /** Contribute links to the platform AI section instead of a separate group. */
-  section?: "ai";
+  /**
+   * Contribute links to a platform admin area instead of a separate group. The admin sidebar shows the area as one
+   * entry; the owner renders the area's columns itself. `"ai"` is the AI area, `"observability"` the Observability area.
+   */
+  section?: AppAdminArea;
   /** Stable key used only to localize this presentation group. */
   id?: string;
   label: string;
@@ -109,6 +116,10 @@ export type AppPwaPart = {
   href: string;
   /** Coarse visibility in the mobile app, like `nav.requiresRoles`. Routes and services still authorize. */
   requiresRoles?: Role[];
+  /** Same-origin path of a `GET` route returning an `AppNavBadge`, counted beside the part in the app's sidebar. */
+  badge?: string;
+  /** Same-origin path of a `GET` route returning a `PwaPartSummary`, the line under the part on the app's Start. */
+  summary?: string;
 };
 
 /** One same-origin panel page contributed by an application. Routes and services still authorize. */
@@ -127,6 +138,8 @@ export type AppMeta = {
   access?: AppAccessRule;
   platformPermissions?: readonly PlatformPermission[];
   id: string;
+  /** Shared object-store package; omitted means the app ID. */
+  package?: string;
   name: string;
   icon: string;
   description: string;
@@ -180,12 +193,15 @@ export type AppMeta = {
 
 /**
  * Response of an app's `nav.badge` route: how many items wait for the signed-in
- * person. A positive safe integer shows a count on the app's icon in the rail
- * and the app grid (above 99 as "99+"); `0`, a non-200 response, or anything
- * else shows none.
+ * person. A positive safe integer shows a count on the app's icon in the rail,
+ * the phone bar, and the app grid (above 99 as "99+"); `0`, a non-200
+ * response, or anything else shows none.
  */
 export type AppNavBadge = { count: number };
 
+/** What a part says about itself on the Cloud app's Start: a line in the reader's locale and the count behind it. */
+export type PwaPartSummary = AppNavBadge & { text: string };
+
 /** A widget endpoint and its board presentation; the handler owns resource authorization. */
 export type WidgetEndpoint = {
   /** Unique-within-the-app id, e.g. "open-requests". */

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(
@@ -793,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 = {
@@ -855,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>>;
@@ -956,13 +989,27 @@ export type CapabilityDefinitions = {
   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({
@@ -970,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();
@@ -1033,6 +1081,41 @@ export const CapabilityCalendarSourceManifestSchema = z
   })
   .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.
@@ -1059,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 => {
@@ -1069,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));
@@ -1092,11 +1180,25 @@ const readableManifest = (value: unknown): unknown => {
     policies[action.localId] = policy;
     return true;
   });
-  const { calendarSource: sentCalendarSource, 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) => {
@@ -1108,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 } : {}),
   };
 };
 
@@ -1129,6 +1241,12 @@ export const CapabilityManifestSchema = z.preprocess(
     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(),
   }),
 );
 
@@ -1153,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/index.ts

@@ -2,6 +2,7 @@ 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";
@@ -27,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/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/pwa.ts

@@ -90,7 +90,7 @@ const Code = z.string().regex(/^\d{6}$/);
 
 export const PwaPlatformSchema = z.enum(["ios", "android", "other"]);
 export type PwaPlatform = z.infer<typeof PwaPlatformSchema>;
-export const PwaPairingStateSchema = z.enum(["pending", "claimed", "confirmed", "completed", "cancelled"]);
+export const PwaPairingStateSchema = z.enum(["pending", "claimed", "awaiting_device", "confirmed", "completed", "rejected", "cancelled"]);
 export type PwaPairingState = z.infer<typeof PwaPairingStateSchema>;
 /** States of `/pwa/` the launch bounce leads to when it cannot renew. */
 export const PwaLaunchStateSchema = z.enum(["new", "ended", "blocked", "unavailable"]);
@@ -146,8 +146,24 @@ export const PwaDeviceListSchema = z.object({ items: z.array(PwaDeviceViewSchema
 export const PwaClaimSchema = z.object({ secret: z.string().regex(SECRET_PATTERN), platform: PwaPlatformSchema }).strict();
 const Account = z.object({ name: z.string() }).strict();
 export const PwaClaimResultSchema = z.object({ code: Code, account: Account, expiresAt: DateTime }).strict();
+export const PwaDeviceDecisionSchema = z
+  .object({
+    confirmationToken: z.string().regex(SECRET_PATTERN),
+    decision: z.enum(["confirm", "reject"]),
+  })
+  .strict();
 export const PwaCompleteResultSchema = z.discriminatedUnion("state", [
   z.object({ state: z.literal("paired") }).strict(),
+  z.object({ state: z.literal("rejected") }).strict(),
+  z
+    .object({
+      state: z.literal("confirmation_required"),
+      account: Account,
+      administrator: Account,
+      confirmationToken: z.string().regex(SECRET_PATTERN),
+      expiresAt: DateTime,
+    })
+    .strict(),
   z.object({ state: z.literal("waiting"), code: Code, account: Account, expiresAt: DateTime }).strict(),
 ]);
 export const PwaRenewResultSchema = z

package/src/contracts/registry.ts

@@ -25,6 +25,10 @@ export type AppRegistryNav = {
 export type AppRegistryPwaPart = {
   href: string;
   requiresRoles?: Role[];
+  /** Count route for the part's sidebar entry; older readers ignore it. */
+  badge?: string;
+  /** Summary route for the part's line on Start; older readers ignore it. */
+  summary?: string;
 };
 
 export type AppRegistryCapabilitySummary = {
@@ -82,6 +86,8 @@ export type AppRegistryEntry = {
   access?: AppAccessRule;
   platformPermissions?: readonly PlatformPermission[];
   id: string;
+  /** Shared object-store package; omitted means the app ID. */
+  package?: string;
   name: string;
   icon: string;
   description: string;