@k2b/cloud 0.42.0 → 0.44.0

package/src/contracts/pwa-location.ts

@@ -0,0 +1,38 @@
+import { PWA_AUTH_PATH, PWA_SCOPE } from "./pwa-paths";
+
+const appTarget = (to: string | undefined): URL | undefined => {
+  if (!to || to.length > 2048 || !to.startsWith(PWA_SCOPE) || to.includes("//") || to.includes("\\")) return undefined;
+  const url = new URL(to, "http://launch.invalid");
+  // Judge the path the browser will request: dot segments and escapes are resolved by then.
+  let path: string;
+  try {
+    path = decodeURIComponent(url.pathname);
+  } catch {
+    return undefined;
+  }
+  const inside = (value: string) => value.startsWith(PWA_SCOPE) && value !== PWA_AUTH_PATH && !value.startsWith(`${PWA_AUTH_PATH}/`);
+  if (url.origin !== "http://launch.invalid" || !inside(url.pathname) || !inside(path) || path.includes("//")) return undefined;
+  return url;
+};
+
+/**
+ * A path inside the app to return to after the launch bounce; anything else becomes `/pwa/`.
+ * The `pwa_launch` marker lets the page stop instead of bouncing again.
+ */
+export const launchTarget = (to: string | undefined): string => {
+  const url = appTarget(to);
+  if (!url) return `${PWA_SCOPE}?pwa_launch=1`;
+  url.searchParams.set("pwa_launch", "1");
+  return url.pathname + url.search;
+};
+
+/** A remembered page, without launch markers or welcome/error states. */
+export const rememberedPwaAddress = (to: string | undefined): string | undefined => {
+  if (to?.includes("#")) return undefined;
+  const url = appTarget(to);
+  if (!url || (url.pathname === PWA_SCOPE && url.searchParams.has("pwa")) || decodeURIComponent(url.pathname) === `${PWA_SCOPE}offline`)
+    return undefined;
+  url.searchParams.delete("pwa_launch");
+  if (url.pathname === PWA_SCOPE) url.searchParams.delete("launch");
+  return url.pathname + url.search;
+};

package/src/contracts/pwa.ts

@@ -17,11 +17,14 @@ export const PWA_MANIFEST_PATH = "/pwa/manifest.webmanifest";
  */
 export const PWA_CANVAS_COLORS = { light: "#fafafa", dark: "#090d12" } as const;
 
-/** Cookie names. Only `pwa_session` reaches every application; the others use Core-only paths. */
+/** Cookie names. The session and last address reach parts; device and pairing secrets use Core-only paths. */
 export const PWA_COOKIES = {
   session: "pwa_session",
+  lastAddress: "pwa_last_address",
   device: "pwa_device",
   pairing: "pwa_pairing",
+  /** Set by the launch when the device's pairing has ended; the next page deletes the app's drafts and the marker. */
+  ended: "pwa_ended",
 } as const;
 
 export const PWA_LIMITS = {
@@ -87,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"]);
@@ -143,9 +146,27 @@ 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.object({ renewed: z.boolean(), otherAccount: Account.optional() }).strict();
+export const PwaRenewResultSchema = z
+  .object({ renewed: z.boolean(), otherAccount: Account.optional(), builds: z.record(z.string(), z.string()) })
+  .strict();
 export const PwaRenameSchema = z.object({ name: z.string().trim().min(1).max(PWA_LIMITS.nameMaxLength) }).strict();

package/src/contracts/registry.ts

@@ -1,6 +1,7 @@
 import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPanel, AppPresentationCatalog, AppSearchLink } from "./app";
 import type { AppAccessRule } from "./app-access";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "./capabilities";
+import type { AppInstallable } from "./installable";
 import type { PlatformPermission } from "./outgoing-mail";
 import type { Role } from "./shared";
 import type { DashboardWidgetPresentation, DashboardWidgetSize, WidgetSettingsDeclaration } from "./widgets";
@@ -24,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 = {
@@ -81,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;
@@ -105,6 +112,7 @@ export type AppRegistryEntry = {
   searchLinks?: readonly AppSearchLink[];
   /** The app's part of the mobile app (preview); `href` is `/pwa/<id>`. Older readers ignore it. */
   pwa?: AppRegistryPwaPart;
+  installable?: AppInstallable;
   /** Optional panel declaration; older readers ignore it. */
   panel?: AppPanel;
   widgets?: AppRegistryWidget[];

package/src/contracts/resource-clipboard.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { type CloudResourceRef, CloudResourceRefSchema } from "./capabilities";
+import { cloudResourceHref } from "./resource-href";
 
 export const CLOUD_RESOURCE_CLIPBOARD_MIME_TYPE = "application/vnd.k2b.cloud-resource-ref+json";
 export const CLOUD_RESOURCE_CLIPBOARD_WEB_FORMAT = `web ${CLOUD_RESOURCE_CLIPBOARD_MIME_TYPE}`;
@@ -31,3 +32,37 @@ export const parseCloudResourceClipboard = (value: string, cloudUrl: string): Cl
     return null;
   }
 };
+
+/** Longest permalink a consumer accepts, like `CloudResourceHrefSchema`. */
+const CLOUD_RESOURCE_URL_MAX_LENGTH = 8_192;
+const CLOUD_RESOURCE_PATH = /^\/open\/([^/]+)\/~([^/]+)$/;
+
+/** The absolute permalink of a resource: the text form people copy, paste, and open. */
+export const formatCloudResourceUrl = (ref: CloudResourceRef, cloudUrl: string): string =>
+  new URL(cloudResourceHref(CloudResourceRefSchema.parse(ref)), cloudUrl).href;
+
+/**
+ * Reads a resource from its permalink on this Cloud, absolute or root-relative. Anything else, such as another
+ * installation's link, an app page, or a query or fragment, returns `null`.
+ */
+export const parseCloudResourceUrl = (value: string, cloudUrl: string): CloudResourceRef | null => {
+  const text = value.trim();
+  if (text.length === 0 || text.length > CLOUD_RESOURCE_URL_MAX_LENGTH) return null;
+  let url: URL;
+  try {
+    url = text.startsWith("/") && !text.startsWith("//") ? new URL(text, cloudUrl) : new URL(text);
+  } catch {
+    return null;
+  }
+  if (url.origin !== cloudUrl || url.search || url.hash) return null;
+  const match = CLOUD_RESOURCE_PATH.exec(url.pathname);
+  if (!match?.[1] || !match[2]) return null;
+  let id: string;
+  try {
+    id = decodeURIComponent(match[2]);
+  } catch {
+    return null;
+  }
+  const ref = CloudResourceRefSchema.safeParse({ type: match[1], id });
+  return ref.success ? ref.data : null;
+};

package/src/contracts/resource-pages.ts

@@ -0,0 +1,140 @@
+import type { CloudResourceRef } from "./capabilities";
+
+/** Eight alternate pages per Type, within the manifest's 200-Type budget. */
+export const RESOURCE_PAGES_PER_TYPE = 8;
+/** Like other manifest route declarations, page patterns are bounded short paths. */
+export const RESOURCE_PAGE_MAX_LENGTH = 300;
+export const RESOURCE_URL_MAX_LENGTH = 8_192;
+
+type Part = { literal: string } | { capture: string };
+type Pattern = { segments: Part[]; query: [string, Part][] };
+const capture = /^:([a-zA-Z][a-zA-Z0-9_]*)$/;
+const decode = (value: string): string => decodeURIComponent(value);
+const part = (value: string): Part => {
+  const match = capture.exec(value);
+  if (match?.[1]) return { capture: match[1] };
+  if (!value || value.includes(":")) throw new Error("Captures must occupy a whole segment or query value");
+  const literal = decode(value);
+  if (!literal || literal === "." || literal === ".." || /[\\/\u0000-\u001f]/.test(literal)) throw new Error("Invalid literal segment");
+  return { literal };
+};
+
+const parsePattern = (path: string): Pattern => {
+  if (!path.startsWith("/") || path.startsWith("//") || path.length > RESOURCE_PAGE_MAX_LENGTH || /[\s#\\]/.test(path))
+    throw new Error(`Expected a root-relative page pattern of at most ${RESOURCE_PAGE_MAX_LENGTH} characters`);
+  const [pathname = "", search = "", extra] = path.split("?");
+  if (extra !== undefined) throw new Error("Page patterns may contain only one query separator");
+  const route = pathname.replace(/\/$/, "").slice(1);
+  const segments = route ? route.split("/").map(part) : [];
+  const keys = new Set<string>();
+  const query: [string, Part][] = search
+    ? search.split("&").map((entry) => {
+        const [key = "", value, extraValue] = entry.split("=");
+        if (!key || value === undefined || extraValue !== undefined) throw new Error("Expected query key=value");
+        const decodedKey = decode(key.replace(/\+/g, " "));
+        if (!decodedKey || decodedKey.includes(":") || keys.has(decodedKey)) throw new Error("Invalid or repeated query key");
+        keys.add(decodedKey);
+        return [decodedKey, part(value.replace(/\+/g, " "))];
+      })
+    : [];
+  const parts = [...segments, ...query.map(([, value]) => value)];
+  if (parts.filter((value) => "capture" in value && value.capture === "id").length !== 1)
+    throw new Error("A page pattern must contain exactly one :id capture");
+  return { segments, query };
+};
+
+/** Validates syntax and ownership; prefixes use the gateway's literal segment boundary. */
+export const resourcePageIssue = (path: string, prefixes?: readonly string[], appId?: string): string | null => {
+  try {
+    const pattern = parsePattern(path);
+    const namespace = pattern.segments[0];
+    const owner = pattern.segments[1];
+    if (
+      appId &&
+      namespace &&
+      "literal" in namespace &&
+      namespace.literal === "app" &&
+      (!owner || !("literal" in owner) || owner.literal !== appId)
+    )
+      return "Only app <id> may declare pages below /app/<id>";
+    if (
+      prefixes &&
+      !prefixes.some((prefix) => {
+        if (prefix === "/") return true;
+        if (!prefix.startsWith("/") || /[?#%\\:]/.test(prefix)) return false;
+        const segments = prefix.replace(/\/$/, "").slice(1).split("/");
+        return segments.every((value, index) => {
+          const segment = pattern.segments[index];
+          return segment && "literal" in segment && segment.literal === value;
+        });
+      })
+    )
+      return "Page pattern must lie under an application's declared route prefix";
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : "Invalid page pattern";
+  }
+};
+
+export type CloudResourcePage = { type: string; path: string; prefixes: readonly string[] };
+
+/** Required query keys outrank literal path segments. Equal best scores for different refs are ambiguous. */
+export const matchCloudResourcePage = (path: string, pages: readonly CloudResourcePage[]): CloudResourceRef | null => {
+  if (!path.startsWith("/") || path.startsWith("//") || path.length > RESOURCE_URL_MAX_LENGTH || /[\s\\]/.test(path)) return null;
+  try {
+    const url = new URL(path, "https://cloud.invalid");
+    const route = url.pathname.replace(/\/$/, "").slice(1);
+    const segments = route ? route.split("/").map(decode) : [];
+    // URLSearchParams silently repairs malformed escapes: validate before reading it.
+    decode(url.search.replace(/\+/g, " "));
+    if (segments.some((value) => !value)) return null;
+    let best: { ref: CloudResourceRef; queries: number; literals: number } | undefined;
+    let ambiguous = false;
+    for (const page of pages) {
+      if (resourcePageIssue(page.path, page.prefixes, page.type.split(".")[0])) continue;
+      const pattern = parsePattern(page.path);
+      if (segments.length !== pattern.segments.length) continue;
+      let id: string | undefined;
+      const matches = (part: Part, value: string | undefined): boolean => {
+        if (!value) return false;
+        if ("literal" in part) return part.literal === value;
+        if (part.capture === "id") id = value;
+        return true;
+      };
+      if (!pattern.segments.every((part, index) => matches(part, segments[index]))) continue;
+      if (
+        !pattern.query.every(([key, part]) => {
+          const values = url.searchParams.getAll(key);
+          return values.length === 1 && matches(part, values[0]);
+        }) ||
+        !id
+      )
+        continue;
+      const ref = { type: page.type, id };
+      const queries = pattern.query.length;
+      const literals = pattern.segments.filter((part) => "literal" in part).length;
+      if (!best || queries > best.queries || (queries === best.queries && literals > best.literals)) {
+        best = { ref, queries, literals };
+        ambiguous = false;
+      } else if (queries === best.queries && literals === best.literals && (ref.type !== best.ref.type || ref.id !== best.ref.id)) {
+        ambiguous = true;
+      }
+    }
+    return best && !ambiguous ? best.ref : null;
+  } catch {
+    return null;
+  }
+};
+
+/** No network activity: accept one local URL token and reject origin tricks before catalog lookup. */
+export const localCloudResourceUrl = (text: string, origin: string | null): URL | null => {
+  if (!text || text.length > RESOURCE_URL_MAX_LENGTH || /[\s\\\u0000-\u001f]/.test(text) || text.startsWith("//")) return null;
+  try {
+    const relative = text.startsWith("/");
+    const url = relative ? new URL(text, origin ?? "https://cloud.invalid") : new URL(text);
+    if (!/^https?:$/.test(url.protocol) || url.username || url.password || (!relative && (!origin || url.origin !== origin))) return null;
+    return url;
+  } catch {
+    return null;
+  }
+};

package/src/contracts/resource-resolution.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { CloudResourceHrefSchema, CloudResourceRefSchema } from "./capabilities";
+
+export const ResolvedCloudResourceUrlSchema = z
+  .object({
+    ref: CloudResourceRefSchema,
+    title: z.string().min(1).max(500),
+    icon: z.string().min(1).max(120).optional(),
+    href: CloudResourceHrefSchema,
+  })
+  .strict();
+
+export type ResolvedCloudResourceUrl = z.infer<typeof ResolvedCloudResourceUrlSchema>;

package/src/contracts/shared.ts

@@ -392,6 +392,8 @@ export type SettingOption = {
 export type SettingValueSource = "custom" | "env" | "default";
 
 export type SettingEntry = {
+  updatedAt?: string | null;
+  updatedBy?: { id: string; name: string } | null;
   key: string;
   label: string;
   kind: SettingKind;
@@ -443,6 +445,8 @@ export type ServiceAccountRequestActor = {
   delegatedUser: User | null;
   scopes: string[];
   credentialId?: string | null;
+  /** Public OAuth client identifier, never the bearer token. */
+  oauthClientId?: string | null;
   credentialExpiresAt?: string | null;
   delegation?: InvocationProvenance;
 };

package/src/contracts/user-notifications.ts

@@ -12,6 +12,8 @@ export const UserNotificationPreferenceSchema = z.object({
   description: z.string(),
   recommendedChannels: z.array(z.string()),
   requiredChannels: z.array(z.string()),
+  excludedChannels: z.array(z.string()),
+  excludedReason: z.string().nullable(),
   selectedChannels: z.array(z.string()),
   effectiveChannels: z.array(z.string()),
   customized: z.boolean(),

package/src/events/app-event-delivery.ts

@@ -0,0 +1,100 @@
+import type { Topic, TopicConfig } from "@k2b/sync";
+import { sql } from "bun";
+import { assertAppEventSize } from "../_internal/app-event-schemas";
+import { lazySync } from "../_internal/process-sync";
+import { type AppEventEnvelope, AppEventEnvelopeSchema } from "../contracts/app-events";
+import { logger } from "../services/logging";
+import { createPgOutbox } from "../services/outbox";
+
+/**
+ * Frozen shared stream. It only buffers events until Core has stored them, and
+ * JetStream reserves `maxBytes` on every replica: 256 MiB hold 52,428 envelopes
+ * at the 4096-byte limit plus a 1024-byte transport allowance. The shared
+ * producer budget and thin-envelope outage scenarios are in operations/app-events.
+ * Retention passing unseen events becomes a visible gap.
+ */
+export const appEventTopicConfig = () =>
+  ({
+    id: "cloud:app-events",
+    owner: "cloud",
+    retention: { maxAgeMs: 7 * 24 * 3_600_000, maxBytes: 256 * 1024 ** 2 },
+    maxPayloadBytes: 8 * 1024,
+    deadLetterRetention: { maxBytes: 1024 ** 2 },
+  }) satisfies TopicConfig;
+
+const topic = lazySync((sync) => sync.topic<AppEventEnvelope>(appEventTopicConfig()));
+export const appEventTopic = (): Topic<AppEventEnvelope> => topic();
+
+export type AppEventOutboxRow = {
+  id: string;
+  app_id: string;
+  created_at: Date | string;
+  attempts: number;
+  ordering_key: string;
+  payload: AppEventEnvelope;
+};
+
+/** The committed row owns identity, source and timestamp, including for SQL writers. */
+export const appEventFromOutbox = (row: AppEventOutboxRow): AppEventEnvelope => {
+  const envelope = AppEventEnvelopeSchema.parse({
+    ...row.payload,
+    id: row.id,
+    source: row.app_id,
+    time: new Date(row.created_at).toISOString(),
+  });
+  assertAppEventSize(envelope);
+  return envelope;
+};
+
+export const appEventOutbox = (appId: string, publish: (row: AppEventOutboxRow) => Promise<unknown>) =>
+  createPgOutbox<AppEventOutboxRow>({
+    table: "events.outbox",
+    name: `events:app:${appId}`,
+    where: { kind: "event", app_id: appId },
+    orderBy: "ordering_key",
+    sequence: "seq",
+    reconcileIntervalMs: 1_000,
+    publish,
+  });
+
+const dispatchers = new Map<string, (() => void) | null>();
+export const registerAppEventPublisher = (appId: string): void => {
+  if (!dispatchers.has(appId)) dispatchers.set(appId, null);
+};
+export const wakeAppEventDelivery = (appId: string): void => dispatchers.get(appId)?.();
+
+export const startAppEventDelivery = async (appId: string): Promise<(() => Promise<void>) | null> => {
+  if (!dispatchers.has(appId)) return null;
+  const [installed] = await sql<{ ready: boolean }[]>`
+    SELECT to_regprocedure('events.enqueue(uuid,text,text,text,jsonb,text)') IS NOT NULL AS ready
+  `;
+  if (!installed?.ready) throw new Error(`"${appId}" publishes app events: update Cloud Core first to install events.outbox`);
+  const destination = appEventTopic();
+  const outbox = appEventOutbox(appId, (row) =>
+    destination.publish({
+      data: appEventFromOutbox(row),
+      orderingKey: row.ordering_key,
+      idempotencyKey: row.id,
+    }),
+  );
+  outbox.start();
+  dispatchers.set(appId, () => void outbox.notify());
+  const log = logger("events:app");
+  const staleCheck = setInterval(() => {
+    sql<
+      { count: number }[]
+    >`SELECT COUNT(*)::int AS count FROM events.outbox WHERE kind = 'event' AND app_id = ${appId} AND created_at < now() - interval '60 seconds'`
+      .then(([row]) => {
+        if (row && row.count > 0) log.warn("App events wait to be published", { appId, count: row.count });
+      })
+      .catch((error: unknown) =>
+        log.warn("App event outbox check failed", { appId, error: error instanceof Error ? error.message : String(error) }),
+      );
+  }, 60_000);
+  staleCheck.unref();
+  return async () => {
+    clearInterval(staleCheck);
+    dispatchers.set(appId, null);
+    await outbox.stop();
+  };
+};

package/src/events/app-events.testing.ts

@@ -0,0 +1,65 @@
+import {
+  type AppEventDeliveryContext,
+  type AppEventEnvelope,
+  AppEventEnvelopeSchema,
+  appEventSubscriptionId,
+} from "../contracts/app-events";
+import type { CapabilityDefinitions } from "../contracts/capabilities";
+import {
+  type AppEventPublishInput,
+  appEventBinding,
+  bindAppEvents,
+  buildAppEventEnvelope,
+  deliverAppEvent as deliverCompiledAppEvent,
+} from "./app-events";
+
+type EventKey<T extends CapabilityDefinitions> = Extract<keyof NonNullable<T["events"]>, string>;
+
+/** Producer fixture, validated exactly like publish. A standalone test may supply its app ID explicitly. */
+export const appEventFixture = <const T extends CapabilityDefinitions, Key extends EventKey<T>>(
+  capabilities: T,
+  localName: Key,
+  input: AppEventPublishInput<T, Key>,
+  options: { id?: string; time?: string; appId?: string } = {},
+): AppEventEnvelope => {
+  if (options.appId !== undefined) bindAppEvents(options.appId, capabilities);
+  return buildAppEventEnvelope(capabilities, localName, input, {
+    id: options.id ?? "00000000-0000-4000-8000-000000000001",
+    time: options.time ?? "2026-01-01T00:00:00.000Z",
+  });
+};
+
+/** Exercises the framework's real delivery validation and the declared subscriber. */
+export const deliverAppEvent = async (
+  capabilities: CapabilityDefinitions,
+  eventType: string,
+  envelope: unknown,
+  context: Partial<AppEventDeliveryContext> & { appId?: string } = {},
+): Promise<void> => {
+  if (context.appId !== undefined) bindAppEvents(context.appId, capabilities);
+  const { appId, compiled } = appEventBinding(capabilities);
+  const parsed = AppEventEnvelopeSchema.parse(envelope);
+  if (parsed.type !== eventType) throw new Error("App event type does not match the tested subscription");
+  const subscriptionId = appEventSubscriptionId(appId, eventType, parsed.version);
+  await deliverCompiledAppEvent({
+    compiled,
+    subscriptionId,
+    envelope,
+    context: {
+      subscriptionId: context.subscriptionId ?? subscriptionId,
+      eventId: context.eventId ?? parsed.id,
+      attempt: context.attempt ?? 1,
+      signal: context.signal ?? new AbortController().signal,
+    },
+  });
+};
+
+/** Explicit app ID for standalone declarations that have no defineApp binding. */
+export const createAppEventTestHarness = (appId: string, capabilities: CapabilityDefinitions) => {
+  bindAppEvents(appId, capabilities);
+  return {
+    manifest: appEventBinding(capabilities).compiled.manifest,
+    deliver: (envelope: AppEventEnvelope, context: Partial<AppEventDeliveryContext> = {}): Promise<void> =>
+      deliverAppEvent(capabilities, envelope.type, envelope, context),
+  };
+};

package/src/events/app-events.ts

@@ -0,0 +1,134 @@
+import { isDeepStrictEqual } from "node:util";
+import type { SQL } from "bun";
+import { z } from "zod";
+import { assertAppEventSize } from "../_internal/app-event-schemas";
+import { type CompiledCapabilities, compileCapabilities } from "../_internal/capabilities";
+import { capabilityHash } from "../_internal/capability-schemas";
+import {
+  type AppEventDeliveryContext,
+  type AppEventEnvelope,
+  AppEventEnvelopeSchema,
+  appEventSubscriptionId,
+} from "../contracts/app-events";
+import { CapabilityAppIdSchema, type CapabilityDefinitions } from "../contracts/capabilities";
+import { registerAppEventPublisher, wakeAppEventDelivery } from "./app-event-delivery";
+
+type EventBinding = { appId: string; compiled: CompiledCapabilities };
+const bindings = new WeakMap<CapabilityDefinitions, EventBinding>();
+const bindingsByApp = new Map<string, EventBinding>();
+
+/** Framework hook: bind the exact declaration object when defineApp assigns its app ID. */
+export const bindAppEvents = (appId: string, definitions: CapabilityDefinitions, compiledInput?: CompiledCapabilities): void => {
+  CapabilityAppIdSchema.parse(appId);
+  const prior = bindings.get(definitions);
+  if (prior && prior.appId !== appId) throw new Error(`Capabilities are already bound to ${prior.appId}`);
+  const compiled = compiledInput ?? prior?.compiled ?? compileCapabilities(appId, definitions);
+  const binding = { appId, compiled };
+  bindings.set(definitions, binding);
+  bindingsByApp.set(appId, binding);
+  if (compiled.events.size > 0) registerAppEventPublisher(appId);
+};
+
+export const appEventBinding = (definitions: CapabilityDefinitions | string) => {
+  const binding = typeof definitions === "string" ? bindingsByApp.get(definitions) : bindings.get(definitions);
+  if (!binding)
+    throw new Error("Bind event capabilities with defineApp before publishing or testing; a test harness accepts an explicit appId");
+  return binding;
+};
+
+type EventDeclarations<T extends CapabilityDefinitions> = NonNullable<T["events"]>;
+export type AppEventPublishInput<T extends CapabilityDefinitions, Key extends keyof EventDeclarations<T>> = {
+  subject: string;
+  data: z.input<EventDeclarations<T>[Key]["schema"]>;
+  requestId?: string;
+} & (EventDeclarations<T>[Key] extends { place: string } ? { place: string } : { place?: never });
+
+/** The same declaration, JSON and byte validation for publishers and producer fixtures. */
+export const buildAppEventEnvelope = <const T extends CapabilityDefinitions, Key extends Extract<keyof EventDeclarations<T>, string>>(
+  definitions: T | string,
+  localId: Key,
+  input: AppEventPublishInput<T, Key>,
+  identity: { id: string; time: string },
+): AppEventEnvelope => {
+  const binding = appEventBinding(definitions);
+  const event = binding.compiled.events.get(localId);
+  if (!event) throw new Error(`Unknown app event ${localId}`);
+  if ((event.manifest.place !== undefined) !== (input.place !== undefined)) {
+    throw new Error(`Event ${localId} place does not match its declaration`);
+  }
+  const data = z.json().parse(input.data);
+  if (!isDeepStrictEqual(input.data, JSON.parse(JSON.stringify(data)))) {
+    throw new Error("Event data must round-trip through JSON without normalization");
+  }
+  const parsed = event.definition.schema.parse(data);
+  if (capabilityHash(parsed) !== capabilityHash(data)) throw new Error("Event schema must preserve the original JSON data");
+  const envelope = AppEventEnvelopeSchema.parse({
+    ...identity,
+    type: `${binding.appId}.${localId}`,
+    version: event.manifest.version,
+    source: binding.appId,
+    subject: { type: `${binding.appId}.${event.manifest.subject}`, id: input.subject },
+    ...(event.manifest.place !== undefined ? { place: { type: `${binding.appId}.${event.manifest.place}`, id: input.place } } : {}),
+    ...(input.requestId !== undefined ? { cause: { requestId: input.requestId } } : {}),
+    data,
+  });
+  assertAppEventSize(envelope);
+  return envelope;
+};
+
+/** Writes in the domain transaction; wake only after commit. Delivery is at least once. */
+export const appEvents = <const T extends CapabilityDefinitions>(definitions: T | string) => ({
+  publish: async <Key extends Extract<keyof EventDeclarations<T>, string>>(
+    tx: SQL,
+    localId: Key,
+    input: AppEventPublishInput<T, Key>,
+  ): Promise<AppEventEnvelope> => {
+    const envelope = buildAppEventEnvelope<T, Key>(definitions, localId, input, {
+      id: crypto.randomUUID(),
+      time: new Date().toISOString(),
+    });
+    // A full valid resource ref can exceed the existing outbox's 600-character key bound.
+    const orderingKey = capabilityHash(envelope.subject);
+    await tx`SELECT events.enqueue(${envelope.id}::uuid, ${envelope.source}, 'event', ${orderingKey}, ${JSON.stringify(envelope)}::text::jsonb)`;
+    return envelope;
+  },
+  wake: (): void => {
+    const binding = typeof definitions === "string" ? bindingsByApp.get(definitions) : bindings.get(definitions);
+    if (binding) wakeAppEventDelivery(binding.appId);
+  },
+});
+
+/** Shared by the framework route and subscription tests; validates before executing application code. */
+export const deliverAppEvent = async (params: {
+  compiled: CompiledCapabilities;
+  subscriptionId: string;
+  envelope: unknown;
+  context: AppEventDeliveryContext;
+}): Promise<void> => {
+  const envelope = AppEventEnvelopeSchema.parse(params.envelope);
+  assertAppEventSize(envelope);
+  if (
+    !envelope.type.startsWith(`${envelope.source}.`) ||
+    !envelope.subject.type.startsWith(`${envelope.source}.`) ||
+    (envelope.place && !envelope.place.type.startsWith(`${envelope.source}.`))
+  )
+    throw new Error("App event source does not match its namespaced types");
+  if (envelope.place) throw new Error("resource_events_unsupported");
+  const subscription = params.compiled.subscribes.get(envelope.type);
+  if (!subscription || subscription.manifest.version !== envelope.version) {
+    throw new Error("App event subscription not found for type and version");
+  }
+  if (params.subscriptionId !== appEventSubscriptionId(params.compiled.manifest.appId, envelope.type, envelope.version)) {
+    throw new Error("App event subscription ID mismatch");
+  }
+  if (
+    params.context.subscriptionId !== params.subscriptionId ||
+    params.context.eventId !== envelope.id ||
+    !Number.isSafeInteger(params.context.attempt) ||
+    params.context.attempt < 1
+  )
+    throw new Error("App event delivery context mismatch");
+  params.context.signal.throwIfAborted();
+  const data = subscription.definition.schema.parse(envelope.data);
+  await subscription.definition.run({ ...envelope, data }, params.context);
+};