@k2b/cloud 0.23.0 → 0.24.0

package/src/contracts/capabilities.ts

@@ -436,6 +436,9 @@ export type CapabilityCommandManifest = z.infer<typeof CapabilityCommandManifest
 
 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 CapabilityDefinitions = {
   protocolVersion: typeof CAPABILITY_PROTOCOL_VERSION;
   presentation?: CapabilityPresentationCatalog;
@@ -443,6 +446,7 @@ export type CapabilityDefinitions = {
   queries?: CapabilityDefinitionCatalog<CapabilityQueryDefinition>;
   actions?: CapabilityDefinitionCatalog<CapabilityActionDefinition>;
   commands?: CapabilityDefinitionCatalog<CapabilityCommandDefinition>;
+  fileProvider?: CapabilityFileProviderDeclaration;
 };
 
 /**
@@ -504,17 +508,81 @@ export const CapabilityAppIdSchema = z
   .max(80)
   .regex(/^[a-z][a-z0-9-]*$/);
 
-export const CapabilityManifestSchema = z
-  .object({
+const MAX_MANIFEST_ENTRIES = 200;
+
+export const CapabilityFileProviderManifestSchema = z
+  .object({ list: CapabilityLocalIdSchema, read: CapabilityLocalIdSchema, save: CapabilityLocalIdSchema.optional() })
+  .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.
+  if (!Array.isArray(values) || values.length > MAX_MANIFEST_ENTRIES) return null;
+  return values.flatMap((value) => {
+    const parsed = entry.safeParse(value);
+    return parsed.success ? [parsed.data] : [];
+  });
+};
+
+/**
+ * Reads what this release understands from a manifest that a newer release may have produced.
+ *
+ * - Unknown top-level fields are ignored. A newer release may therefore only add something at the top
+ *   level; anything that restricts an existing entry belongs inside that entry.
+ * - An entry with a field or value from a newer release is left out rather than stripped: its unknown
+ *   part may change how the entry runs or who may use it, so guessing could widen access.
+ * - Entries that depend on an entry that is not there follow it: a Query scoped to a missing type is
+ *   left out, and a type whose reader is missing keeps no reader.
+ * - A file provider with a field from a newer release is left out. Whether its operations are still
+ *   there and match the contract is `fileProviderIssues`' job, which Core and consumers run.
+ *
+ * Every other entry stays available.
+ */
+const readableManifest = (value: unknown): unknown => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  const sent = value as Record<string, unknown>;
+  const types = readEntries(sent.types, CapabilityResourceTypeManifestSchema);
+  const queries = readEntries(sent.queries, CapabilityQueryManifestSchema);
+  const actions = readEntries(sent.actions, CapabilityActionManifestSchema);
+  const commands = readEntries(sent.commands, CapabilityCommandManifestSchema);
+  if (!types || !queries || !actions || !commands) 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));
+  const { fileProvider: sentProvider, ...rest } = sent;
+  const provider = CapabilityFileProviderManifestSchema.safeParse(sentProvider);
+  return {
+    ...rest,
+    ...(provider.success ? { fileProvider: provider.data } : {}),
+    types: types.map((type) => {
+      if (!type.reader || queryIds.has(type.reader)) return type;
+      const { reader: _missing, ...withoutReader } = type;
+      return withoutReader;
+    }),
+    queries: readableQueries,
+    actions,
+    commands,
+  };
+};
+
+/**
+ * Reads a manifest from any Cloud release with the same protocol version (see `readableManifest`).
+ * Producers stay strict: `app.start()` registers exactly the manifest its release defines.
+ */
+export const CapabilityManifestSchema = z.preprocess(
+  readableManifest,
+  z.object({
     protocolVersion: z.literal(CAPABILITY_PROTOCOL_VERSION),
     appId: CapabilityAppIdSchema,
     manifestHash: z.string().regex(/^[a-f0-9]{64}$/),
-    types: z.array(CapabilityResourceTypeManifestSchema).max(200),
-    queries: z.array(CapabilityQueryManifestSchema).max(200),
-    actions: z.array(CapabilityActionManifestSchema).max(200),
-    commands: z.array(CapabilityCommandManifestSchema).max(200),
-  })
-  .strict();
+    types: z.array(CapabilityResourceTypeManifestSchema).max(MAX_MANIFEST_ENTRIES),
+    queries: z.array(CapabilityQueryManifestSchema).max(MAX_MANIFEST_ENTRIES),
+    actions: z.array(CapabilityActionManifestSchema).max(MAX_MANIFEST_ENTRIES),
+    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(),
+  }),
+);
 
 export type CapabilityResourceTypeManifest = z.infer<typeof CapabilityResourceTypeManifestSchema>;
 export type CapabilityQueryManifest = z.infer<typeof CapabilityQueryManifestSchema>;
@@ -533,22 +601,19 @@ export const resolveCapabilityResourceReader = (manifest: CapabilityManifest, re
   return manifest.queries.find((candidate) => candidate.localId === type.reader) ?? null;
 };
 
-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,
-  })
-  .strict();
+/** Like the manifest, catalog entries, pages, and their pagination ignore fields that a newer Cloud release added. */
+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,
+});
 
-export const CapabilityCatalogSchema = z
-  .object({
-    protocolVersion: z.literal(CAPABILITY_PROTOCOL_VERSION),
-    apps: z.array(CapabilityCatalogAppSchema).max(25),
-    page: CapabilityPageSchema,
-  })
-  .strict();
+export const CapabilityCatalogSchema = z.object({
+  protocolVersion: z.literal(CAPABILITY_PROTOCOL_VERSION),
+  apps: z.array(CapabilityCatalogAppSchema).max(25),
+  page: z.discriminatedUnion("hasMore", [CapabilityPageSchema.options[0].strip(), CapabilityPageSchema.options[1].strip()]),
+});
 
 export type CapabilityCatalog = z.infer<typeof CapabilityCatalogSchema>;

package/src/contracts/capability-compatibility.ts

@@ -8,6 +8,8 @@ import type { CapabilityActionManifest, CapabilityQueryManifest } from "./capabi
 export type CapabilityContract = {
   kind: "query" | "action";
   idempotency?: "required";
+  /** The binary stream direction the operation must declare. Without it, streaming operations do not match. */
+  stream?: "read" | "write";
   input: z.ZodType;
   data: z.ZodType;
 };
@@ -102,6 +104,20 @@ const patternMatches = (pattern: string, value: string): boolean => {
   }
 };
 
+type Bound = { value: number; exclusive: boolean };
+const lowerBound = (schema: Json): Bound | null =>
+  typeof schema.exclusiveMinimum === "number"
+    ? { value: schema.exclusiveMinimum, exclusive: true }
+    : typeof schema.minimum === "number"
+      ? { value: schema.minimum, exclusive: false }
+      : null;
+const upperBound = (schema: Json): Bound | null =>
+  typeof schema.exclusiveMaximum === "number"
+    ? { value: schema.exclusiveMaximum, exclusive: true }
+    : typeof schema.maximum === "number"
+      ? { value: schema.maximum, exclusive: false }
+      : null;
+
 /** Checks one literal value against a provider or contract schema. Unknown keywords never pass. */
 const valueIssue = (value: unknown, sup: Side, depth: number): string | null => {
   const resolved = deref(sup, depth);
@@ -126,22 +142,15 @@ const valueIssue = (value: unknown, sup: Side, depth: number): string | null =>
     if (typeof schema.maxLength === "number" && value.length > schema.maxLength) return "value is too long";
     if (typeof schema.pattern === "string" && !patternMatches(schema.pattern, value)) return "value does not match the pattern";
   }
+  if (typeof value === "number") {
+    const lower = lowerBound(schema);
+    const upper = upperBound(schema);
+    if (lower && (lower.exclusive ? value <= lower.value : value < lower.value)) return `value ${value} is out of range`;
+    if (upper && (upper.exclusive ? value >= upper.value : value > upper.value)) return `value ${value} is out of range`;
+  }
   return null;
 };
 
-type Bound = { value: number; exclusive: boolean };
-const lowerBound = (schema: Json): Bound | null =>
-  typeof schema.exclusiveMinimum === "number"
-    ? { value: schema.exclusiveMinimum, exclusive: true }
-    : typeof schema.minimum === "number"
-      ? { value: schema.minimum, exclusive: false }
-      : null;
-const upperBound = (schema: Json): Bound | null =>
-  typeof schema.exclusiveMaximum === "number"
-    ? { value: schema.exclusiveMaximum, exclusive: true }
-    : typeof schema.maximum === "number"
-      ? { value: schema.maximum, exclusive: false }
-      : null;
 const withinLower = (sub: Bound | null, sup: Bound | null): boolean =>
   !sup || (sub !== null && (sub.value > sup.value || (sub.value === sup.value && (sub.exclusive || !sup.exclusive))));
 const withinUpper = (sub: Bound | null, sup: Bound | null): boolean =>
@@ -356,7 +365,12 @@ export const capabilityContractIssues = (
     return [{ code: "kind", path: "$", message: `Expected ${contract.kind === "query" ? "a Query" : "an Action"}` }];
   }
   const issues: CapabilityContractIssue[] = [];
-  if (candidate.operation.stream) issues.push({ code: "stream", path: "$", message: "Streaming capabilities are not supported" });
+  const direction = candidate.operation.stream?.direction;
+  if (contract.stream && direction !== contract.stream) {
+    issues.push({ code: "stream", path: "$", message: `Expected a ${contract.stream} stream` });
+  } else if (!contract.stream && direction) {
+    issues.push({ code: "stream", path: "$", message: "Streaming capabilities are not supported" });
+  }
   if (contract.idempotency === "required" && candidate.kind === "action" && candidate.operation.idempotency !== "required") {
     issues.push({ code: "idempotency", path: "$", message: "The Action must require an idempotency key" });
   }

package/src/contracts/file-provider.ts

@@ -0,0 +1,158 @@
+import { z } from "zod";
+import type { CapabilityManifest } from "./capabilities";
+import { type CapabilityContract, type CapabilityContractIssue, capabilityContractIssues } from "./capability-compatibility";
+
+/**
+ * Provider-neutral file-provider contract.
+ *
+ * An application offers files to other applications by declaring
+ * `fileProvider: { list, read, save? }` in `defineCapabilities`. Each entry
+ * names one of its own Queries or Actions; the schemas below are the minimum
+ * both sides share. Identifiers and cursors are opaque provider strings, and
+ * the provider authorizes every call with the caller's own access.
+ */
+
+// Bounds follow the shared provider page: 100 entries, 3 tags of 40 characters.
+const ProviderIdSchema = z.string().min(1).max(2048);
+const CursorSchema = z.string().min(1).max(16384);
+const TimestampSchema = z.string().datetime({ offset: true });
+
+/** One display chip. Tags describe an entry; they are not a filter or a permission. */
+export const FileProviderTagSchema = z
+  .object({
+    label: z.string().min(1).max(40),
+    tone: z.enum(["neutral", "info", "success", "warning", "danger"]).optional(),
+  })
+  .strict();
+
+export const FileProviderListInputSchema = z
+  .object({
+    parent: ProviderIdSchema.optional().describe("Folder ID returned by this provider; omit for the provider root."),
+    query: z.string().max(200).optional().describe("Optional name filter inside the folder."),
+    cursor: CursorSchema.optional().describe("Opaque cursor returned by the previous page; keep parent, query, and limit unchanged."),
+    limit: z.number().int().min(1).max(100).default(50).describe("Maximum number of entries to return."),
+  })
+  .strict();
+
+const entryFacts = {
+  id: ProviderIdSchema,
+  name: z.string().min(1).max(255),
+  updatedAt: TimestampSchema.optional(),
+  icon: z.string().min(1).max(120).optional(),
+  tags: z.array(FileProviderTagSchema).max(3).optional(),
+};
+
+export const FileProviderEntrySchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("folder"), ...entryFacts }).loose(),
+  z
+    .object({
+      kind: z.literal("file"),
+      ...entryFacts,
+      size: z.number().int().min(0),
+      mediaType: z.string().min(1).max(255).optional(),
+    })
+    .loose(),
+]);
+
+/** One folder page. Folders may be virtual; pages may be short or empty and still continue while `next` is set. */
+export const FileProviderListDataSchema = z
+  .object({
+    writable: z.boolean(),
+    items: z.array(FileProviderEntrySchema).max(100),
+    next: CursorSchema.nullable(),
+  })
+  .loose();
+
+export const FileProviderReadInputSchema = z
+  .object({ id: ProviderIdSchema.describe("File ID returned by this provider's list.") })
+  .strict();
+export const FileProviderReadDataSchema = z.object({}).loose();
+
+/** A single file name: no path separators, control characters, `.` or `..`. */
+const FileNameSchema = z
+  .string()
+  .min(1)
+  .max(255)
+  .regex(/^(?!\.{1,2}$)[^/\\\u0000-\u001f\u007f]+$/);
+
+export const FileProviderSaveInputSchema = z
+  .object({
+    parent: ProviderIdSchema.describe("Writable folder ID returned by this provider's list."),
+    name: FileNameSchema.describe("Name of the new file."),
+    mediaType: z
+      .string()
+      .min(1)
+      .max(255)
+      .regex(/^[\x20-\x7e]+$/)
+      .describe("Media type of the content."),
+    size: z.number().int().min(0).describe("Exact byte count of the content."),
+  })
+  .strict();
+
+/** `file` is present once the write stream completed; the call that opens the stream has no file yet. */
+export const FileProviderSaveDataSchema = z
+  .object({
+    file: z
+      .object({ id: ProviderIdSchema, name: z.string().min(1).max(255), size: z.number().int().min(0) })
+      .loose()
+      .optional(),
+  })
+  .loose();
+
+/**
+ * The error code `save` answers, with status `409`, when the name already
+ * exists in the folder. Consumers ask for another name only on this code;
+ * every other failure keeps its own code, even with status `409`.
+ */
+export const FILE_PROVIDER_NAME_CONFLICT = "FILE_NAME_CONFLICT";
+
+/**
+ * The three file-provider functions. `read` streams the file's bytes, `save`
+ * is an idempotent Action with a write stream that only creates files: an
+ * existing name fails with `FILE_PROVIDER_NAME_CONFLICT`.
+ */
+export const fileProvider = {
+  list: { kind: "query", input: FileProviderListInputSchema, data: FileProviderListDataSchema },
+  read: { kind: "query", input: FileProviderReadInputSchema, data: FileProviderReadDataSchema, stream: "read" },
+  save: {
+    kind: "action",
+    idempotency: "required",
+    input: FileProviderSaveInputSchema,
+    data: FileProviderSaveDataSchema,
+    stream: "write",
+  },
+} as const satisfies Record<string, CapabilityContract>;
+
+export type FileProviderFunction = keyof typeof fileProvider;
+export const FILE_PROVIDER_FUNCTIONS = ["list", "read", "save"] as const satisfies readonly FileProviderFunction[];
+
+export type FileProviderTag = z.output<typeof FileProviderTagSchema>;
+export type FileProviderEntry = z.output<typeof FileProviderEntrySchema>;
+export type FileProviderListData = z.output<typeof FileProviderListDataSchema>;
+export type FileProviderSaveData = z.output<typeof FileProviderSaveDataSchema>;
+
+export type FileProviderIssue = CapabilityContractIssue & { function: FileProviderFunction; localId: string };
+
+/**
+ * Explains why a manifest's `fileProvider` declaration cannot serve the
+ * contract. Apps run it at start and fail; Core runs it when it reads a live
+ * manifest and ignores an invalid declaration. An empty list means valid or
+ * not declared.
+ */
+export const fileProviderIssues = (manifest: CapabilityManifest): FileProviderIssue[] => {
+  const declaration = manifest.fileProvider;
+  if (!declaration) return [];
+  return FILE_PROVIDER_FUNCTIONS.flatMap((name) => {
+    const localId = declaration[name];
+    if (localId === undefined) return [];
+    const contract = fileProvider[name];
+    const query = manifest.queries.find((operation) => operation.localId === localId);
+    const action = manifest.actions.find((operation) => operation.localId === localId);
+    const issues = query
+      ? capabilityContractIssues(contract, { kind: "query", operation: query })
+      : action
+        ? capabilityContractIssues(contract, { kind: "action", operation: action })
+        : [{ code: "kind" as const, path: "$", message: `No Query or Action named ${localId}` }];
+    return issues.map((issue) => ({ ...issue, function: name, localId }));
+  });
+};

package/src/contracts/index.ts

@@ -6,6 +6,7 @@ export * from "./capabilities";
 export * from "./capability-compatibility";
 export * from "./commands";
 export * from "./contact-directory";
+export * from "./file-provider";
 export * from "./notification-types";
 export * from "./posix";
 export * from "./profile";

package/src/events/live-engine.ts

@@ -164,6 +164,8 @@ export const createLiveEngine = (input: { appId: string; topic: () => LiveTopic;
   const inbox: Entry[] = [];
   let draining = false;
   let room: (() => void) | null = null;
+  /** Sequence of the latest access update the follower read, already while it waits in the inbox or is checked. */
+  let lastAccess = 0;
 
   const cursorAt = (seq: number) => input.topic().cursorAt(seq);
   const frame = {
@@ -450,6 +452,7 @@ export const createLiveEngine = (input: { appId: string; topic: () => LiveTopic;
       return { ...base, key: null, data: undefined, resync: false, access: false, bytes: 64 };
     }
     const { k, d, r, a } = parsed.data;
+    if (a === true) lastAccess = event.sequence;
     const data = d === undefined ? undefined : JSON.stringify(d);
     return { ...base, key: k, data, resync: r === true, access: a === true, bytes: (data?.length ?? 0) + k.length + 64 };
   };
@@ -679,6 +682,7 @@ export const createLiveEngine = (input: { appId: string; topic: () => LiveTopic;
     const scope = channel.scope.safeParse(request.scope);
     if (!scope.success) return violation(conn, "invalid_scope");
     await whenStarted();
+    const accessBefore = lastAccess;
     const keys = await channel.keys(scope.data, conn.viewer);
     const readable = keys === null ? [] : await readableKeys(request.channel, followed(request.channel, keys), conn.viewer);
     // Not found and not readable look the same.
@@ -692,13 +696,13 @@ export const createLiveEngine = (input: { appId: string; topic: () => LiveTopic;
     // the replay covers everything up to it, live delivery everything after it.
     const position = Math.max(head, ring.at(-1)?.seq ?? 0);
     const oldest = ring[0]?.seq ?? position + 1;
-    // A collection cannot tell which keys it had before: an access update of a key it follows now,
-    // missed while it was away, may have added that key.
-    const missedAccess =
-      channel.collection === true &&
-      after !== null &&
-      ring.some((entry) => entry.access && entry.seq > after && entry.seq <= position && readable.includes(entry.key as string));
-    const resync = request.after !== undefined && (after === null || after < oldest - 1 || recreated || missedAccess);
+    // A collection cannot tell which keys it had at its cursor: any access update it missed may have
+    // added one of its keys now or removed one it had then, and only `resync` drops a removed one.
+    const missedAccess = channel.collection === true && after !== null && lastAccess > after;
+    // An access update read while `keys()` and `authorize` answered may postdate their answers,
+    // which must not release a replay of what followed it.
+    const accessMeanwhile = lastAccess !== accessBefore;
+    const resync = request.after !== undefined && (after === null || after < oldest - 1 || recreated || missedAccess || accessMeanwhile);
     const sub: Subscription = {
       id: request.id,
       conn,

package/src/events/live.ts

@@ -61,13 +61,14 @@ export const liveOutbox = (appId: string, publish: (row: LiveOutboxRow) => Promi
     where: { kind: "live", app_id: appId },
     orderBy: "ordering_key",
     sequence: "seq",
-    onDelivered: "delete",
     reconcileIntervalMs: RECONCILE_INTERVAL_MS,
     publish,
   });
 
 /** Applications whose live updates this process defines, with the wake of their running dispatcher. */
 const dispatchers = new Map<string, (() => void) | null>();
+/** Applications whose live socket this process mounts; only the started application may be among them. */
+const served = new Set<string>();
 /** Live sockets served by this process; they close when the application stops. */
 const engines = new Set<LiveEngine>();
 /** Set when the application stops delivery: its engines stay stopped until delivery starts again. */
@@ -89,26 +90,27 @@ const logStaleRows = async (appId: string): Promise<void> => {
 };
 
 /**
- * Publishes the rows of the live definitions in this process. `app.start()`
- * calls it with the started application's ID; it does nothing without a
- * definition, and fails when a definition names another application or Core
- * has not created the outbox yet.
+ * Publishes the rows of the started application's live definitions. `app.start()`
+ * calls it with the started application's ID. A definition of another
+ * application only reads that application's cursor, and its rows are published
+ * by that application. It does nothing without a definition of the started
+ * application, and fails when this process mounts the socket of another
+ * application or Core has not created the outbox yet.
  */
-export const startLiveOutbox = async (startedAppId: string): Promise<(() => Promise<void>) | null> => {
-  const appIds = [...dispatchers.keys()];
-  if (appIds.length === 0) return null;
-  const foreign = appIds.filter((appId) => appId !== startedAppId);
+export const startLiveOutbox = async (appId: string): Promise<(() => Promise<void>) | null> => {
+  const foreign = [...served].filter((other) => other !== appId);
   if (foreign.length > 0) {
     throw new Error(
-      `defineLive() names "${foreign.join('", "')}", but this process starts "${startedAppId}". Use the ID from the application's declaration.`,
+      `This process mounts the live socket of "${foreign.join('", "')}", but starts "${appId}". Use the ID from the application's declaration.`,
     );
   }
+  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(
-      `"${appIds.join('", "')}" writes live updates to events.outbox, which does not exist. Update Cloud Core first: its migration creates the outbox.`,
+      `"${appId}" writes live updates to events.outbox, which does not exist. Update Cloud Core first: its migration creates the outbox.`,
     );
   }
   // Delivery starts again: the engines stopped before give way to new ones.
@@ -116,26 +118,21 @@ export const startLiveOutbox = async (startedAppId: string): Promise<(() => Prom
     engines.clear();
     stopped = false;
   }
-  const stops = appIds.map((appId) => {
-    const topic = liveTopics()(appId);
-    const outbox = liveOutbox(appId, (row) => topic.publish({ data: row.payload, orderingKey: row.ordering_key, idempotencyKey: row.id }));
-    outbox.start();
-    dispatchers.set(appId, () => void outbox.notify());
-    const staleCheck = setInterval(() => {
-      logStaleRows(appId).catch((error) =>
-        log.warn("Live outbox check failed", { appId, error: error instanceof Error ? error.message : String(error) }),
-      );
-    }, STALE_CHECK_INTERVAL_MS);
-    staleCheck.unref();
-    return async () => {
-      clearInterval(staleCheck);
-      dispatchers.set(appId, null);
-      await outbox.stop();
-    };
-  });
+  const topic = liveTopics()(appId);
+  const outbox = liveOutbox(appId, (row) => topic.publish({ data: row.payload, orderingKey: row.ordering_key, idempotencyKey: row.id }));
+  outbox.start();
+  dispatchers.set(appId, () => void outbox.notify());
+  const staleCheck = setInterval(() => {
+    logStaleRows(appId).catch((error) =>
+      log.warn("Live outbox check failed", { appId, error: error instanceof Error ? error.message : String(error) }),
+    );
+  }, STALE_CHECK_INTERVAL_MS);
+  staleCheck.unref();
   return async () => {
     stopLiveEngines();
-    await Promise.all(stops.map((stop) => stop()));
+    clearInterval(staleCheck);
+    dispatchers.set(appId, null);
+    await outbox.stop();
   };
 };
 
@@ -215,8 +212,9 @@ const refusalOf = async (c: Context<AuthContext>): Promise<Refusal | null> => {
  * Live updates of one application: hints, optionally with data, for its own
  * open tabs. Define them once at module scope; `app.start()` then publishes the
  * rows that `publish()` writes, and `routes()` serves them to browsers.
- * `appId` is required and must be the ID that the process starts; it is never
- * derived from the process.
+ * `appId` is required and is never derived from the process. Another
+ * application's process may hold the definition to read its `cursor()` or
+ * write updates; only the application itself publishes and serves them.
  */
 export const defineLive = <const Event extends z.ZodType>(definition: { appId: string; event: Event }) => {
   const { appId, event } = definition;
@@ -250,7 +248,8 @@ export const defineLive = <const Event extends z.ZodType>(definition: { appId: s
     /** The topic head. Read it before loading the snapshot it belongs to. */
     cursor: (): Promise<string> => liveTopics()(appId).head(),
     /**
-     * The live socket with these channels. Mount it once, at `/api/<app>/live`.
+     * The live socket with these channels. Mount it once, at `/api/<app>/live`,
+     * in the application's own process: `app.start()` of another application fails.
      * It authenticates like any API request; a session needs the Cloud origin
      * and an OAuth token the `read` scope. A refused socket receives `error`
      * and closes with 1008. Channels are passed here, not to
@@ -258,6 +257,7 @@ export const defineLive = <const Event extends z.ZodType>(definition: { appId: s
      * themselves publish updates.
      */
     routes: <const Scopes extends Record<string, z.ZodType>>(channels: { [Name in keyof Scopes]: LiveChannel<Scopes[Name]> }) => {
+      served.add(appId);
       let engine: LiveEngine | null = null;
       const serve = (): LiveEngine => {
         if (engine && engines.has(engine)) return engine;

package/src/server/help.ts

@@ -35,7 +35,7 @@ export type HelpCollection = {
 
 type ParsedHelpDocument = Omit<HelpDefinitionDocument, "order"> & { order?: number };
 
-const parseSource = (source: string): ParsedHelpDocument => {
+const parseSource = (source: string, locale: string): ParsedHelpDocument => {
   const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(source);
   if (!match) throw new Error("Help documents require YAML frontmatter wrapped in --- markers");
 
@@ -46,7 +46,7 @@ const parseSource = (source: string): ParsedHelpDocument => {
   return {
     ...metadata,
     markdown,
-    html: renderHelpMarkdown(markdown),
+    html: renderHelpMarkdown(markdown, locale),
     searchText: markdownToPlainText(markdown),
   };
 };
@@ -65,7 +65,7 @@ const parseDocuments = (
   baseById?: ReadonlyMap<string, HelpDefinitionDocument>,
 ): readonly HelpDefinitionDocument[] => {
   const documents = sources
-    .map(parseSource)
+    .map((source) => parseSource(source, locale))
     .map((document): HelpDefinitionDocument => {
       const base = baseById?.get(document.id);
       if (!baseById) return { ...document, order: document.order ?? 100 };

package/src/services/index.ts

@@ -197,7 +197,7 @@ export type {
 export { latestTopicCursor } from "./topic-cursor";
 export { readAccountCategoryPolicy, isAccountCategoryAllowed } from "./account-category-policy";
 export { AppApprovalError, appApproval, type AppDeviceAdministrator, type AppDeviceEnrollmentNotice } from "./app-approval";
-export { PwaError, pwaDevices, type PwaDeviceAdministrator } from "./pwa-devices";
+export { PwaError, pwaDevices, type PwaDeviceAdministrator, type PwaDevicePairedNotice } from "./pwa-devices";
 export { legalConsent } from "./legal-consent";
 
 /** Core-owned app bar administration; service methods enforce administrator access. */