@k2b/cloud 0.6.0-rc.0

package/src/_internal/heartbeat.ts

@@ -0,0 +1,167 @@
+/** Keep an app discoverable even when the ephemeral registry is recreated. */
+
+import { APP_REGISTRY_TTL_MS } from "./registry";
+
+const HEARTBEAT_INTERVAL_MS = 60_000;
+const HEARTBEAT_WRITE_TIMEOUT_MS = 10_000;
+const HEARTBEAT_RETRY_MS = 5_000;
+const HEARTBEAT_STALE_MARGIN_MS = 15_000;
+
+/** The subset of a @k2b/sync `Ephemeral<T>` the heartbeat needs. */
+type HeartbeatRegistry<T> = {
+  upsert: (input: { key: string; value: T }) => Promise<unknown>;
+  /** Renews the lease; false when the key is absent. */
+  touch: (input: { key: string }) => Promise<boolean>;
+  delete: (input: { key: string }) => Promise<unknown>;
+};
+
+type HeartbeatOptions<T> = {
+  registry: HeartbeatRegistry<T>;
+  key?: string;
+  intervalMs?: number;
+  retryMs?: number;
+  staleAfterMs?: number;
+  writeTimeoutMs?: number;
+  onError?: (error: unknown) => void;
+  onStale?: (error: unknown) => void;
+};
+
+export const createHeartbeat = <T>(appId: string, entry: T, options: HeartbeatOptions<T>) => {
+  const intervalMs = options.intervalMs ?? HEARTBEAT_INTERVAL_MS;
+  const retryMs = options.retryMs ?? Math.min(HEARTBEAT_RETRY_MS, intervalMs);
+  const staleAfterMs = options.staleAfterMs ?? APP_REGISTRY_TTL_MS - HEARTBEAT_STALE_MARGIN_MS;
+  const writeTimeoutMs = options.writeTimeoutMs ?? HEARTBEAT_WRITE_TIMEOUT_MS;
+  const registry = options.registry;
+  const onError = options.onError ?? ((error: unknown) => console.error(`[app:${appId}] Registry heartbeat failed`, error));
+  const onStale = options.onStale;
+
+  if (![intervalMs, retryMs, staleAfterMs, writeTimeoutMs].every((value) => Number.isFinite(value) && value > 0)) {
+    throw new RangeError("Heartbeat timings must be positive finite numbers");
+  }
+
+  let timer: Timer | null = null;
+  let inFlight: Promise<void> | null = null;
+  let running = false;
+  let lastSuccessAt = 0;
+  let staleReported = false;
+  const key = options.key ?? `apps/${appId}`;
+
+  const noteSuccess = (): void => {
+    if (!running) return;
+    lastSuccessAt = Date.now();
+    staleReported = false;
+  };
+
+  const register = async (): Promise<void> => {
+    await registry.upsert({ key, value: entry });
+    noteSuccess();
+  };
+
+  const refresh = async (): Promise<void> => {
+    // Touch renews the existing entry (and emits a registry invalidation).
+    // Avoid rebuilding the manifest here. A missing entry is repaired
+    // immediately, preserving restart-free registry recovery.
+    const touched = await registry.touch({ key });
+    if (!touched) await registry.upsert({ key, value: entry });
+    noteSuccess();
+  };
+
+  const writeWithTimeout = async (write: Promise<void>): Promise<void> => {
+    let timer: Timer | null = null;
+    let timedOut = false;
+    void write
+      .then(async () => {
+        // A write that completed after its timeout must not resurrect a stopped app.
+        if (timedOut && !running) await registry.delete({ key }).catch(() => false);
+      })
+      .catch(() => undefined);
+    try {
+      await Promise.race([
+        write,
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(() => {
+            timedOut = true;
+            reject(new Error(`Registry write timed out after ${writeTimeoutMs}ms`));
+          }, writeTimeoutMs);
+        }),
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  };
+
+  const refreshWithTimeout = (): Promise<void> => writeWithTimeout(refresh());
+
+  const reportError = (error: unknown): void => {
+    try {
+      onError(error);
+    } catch {
+      // Error reporting must never stop future registration attempts.
+    }
+    if (!staleReported && lastSuccessAt > 0 && Date.now() - lastSuccessAt >= staleAfterMs) {
+      staleReported = true;
+      try {
+        onStale?.(error);
+      } catch {
+        // A failed stale callback must not disable heartbeat recovery.
+      }
+    }
+  };
+
+  const schedule = (delayMs: number) => {
+    if (!running || timer) return;
+    timer = setTimeout(() => {
+      timer = null;
+      if (!running) return;
+
+      let nextDelayMs = intervalMs;
+      const operation = refreshWithTimeout();
+      inFlight = operation;
+      void operation
+        .catch((error) => {
+          nextDelayMs = retryMs;
+          reportError(error);
+        })
+        .finally(() => {
+          if (inFlight === operation) inFlight = null;
+          schedule(nextDelayMs);
+        });
+    }, delayMs);
+  };
+
+  return {
+    start: async () => {
+      if (running) {
+        await inFlight;
+        return;
+      }
+      running = true;
+      const operation = writeWithTimeout(register());
+      inFlight = operation;
+      try {
+        await operation;
+      } catch (error) {
+        running = false;
+        throw error;
+      } finally {
+        if (inFlight === operation) inFlight = null;
+      }
+      schedule(intervalMs);
+    },
+    stop: async () => {
+      if (!running) return;
+      running = false;
+      if (timer) clearTimeout(timer);
+      timer = null;
+
+      try {
+        await inFlight;
+      } catch {
+        // Recurring heartbeat failures are already reported above. Removal is
+        // still required so a stopped app cannot remain discoverable.
+      }
+      inFlight = null;
+      await registry.delete({ key });
+    },
+  };
+};

package/src/_internal/help-catalog.ts

@@ -0,0 +1,241 @@
+import type { AppRegistryEntry, HelpRegistryDocument, HelpRegistryEntry } from "../contracts/registry";
+import { helpLocaleChain } from "../shared/help";
+import { markdownToPlainText } from "../shared/markdown";
+import { getApp, getHelp, listApps, listHelp } from "./registry";
+
+export const HELP_SEARCH_MAX_LIMIT = 25;
+export const HELP_READ_MAX_CHARS = 7_000;
+
+export type HelpCatalogDocument = {
+  appId: string;
+  appName: string;
+  appIcon?: string;
+  manifestHash: string;
+  locale: string;
+  documentId: string;
+  title: string;
+  description?: string;
+  order: number;
+  markdown: string;
+  searchText: string;
+};
+
+export type HelpCatalogItem = Omit<HelpCatalogDocument, "appIcon" | "manifestHash" | "order" | "markdown" | "searchText"> & {
+  kind: "help";
+};
+
+export type HelpCatalogRead = HelpCatalogItem & {
+  markdown: string;
+  truncated: boolean;
+};
+
+export type HelpCatalogDependencies = {
+  listApps?: () => Promise<AppRegistryEntry[]>;
+  listHelp?: () => Promise<HelpRegistryEntry[]>;
+};
+
+export type AppHelpDependencies = {
+  getApp?: (appId: string) => Promise<AppRegistryEntry | null>;
+  getHelp?: (appId: string) => Promise<HelpRegistryEntry | null>;
+};
+
+export type ResolvedAppHelp =
+  | { status: "available"; app: AppRegistryEntry; help: HelpRegistryEntry }
+  | { status: "missing" }
+  | { status: "stale" };
+
+const normalizeSearchText = (value: string): string =>
+  value
+    .normalize("NFKD")
+    .replace(/\p{M}/gu, "")
+    .toLocaleLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim();
+
+const searchTerms = (value: string): string[] =>
+  Array.from(
+    new Set(
+      normalizeSearchText(value)
+        .split(" ")
+        .filter((term) => term.length > 0),
+    ),
+  );
+
+export const resolveAppHelp = async (appId: string, dependencies: AppHelpDependencies = {}): Promise<ResolvedAppHelp> => {
+  const [app, help] = await Promise.all([(dependencies.getApp ?? getApp)(appId), (dependencies.getHelp ?? getHelp)(appId)]);
+  if (!app?.help || !help) return { status: "missing" };
+  if (app.help.manifestHash !== help.manifestHash) return { status: "stale" };
+  return { status: "available", app, help };
+};
+
+export const loadCurrentHelp = async (dependencies: HelpCatalogDependencies = {}): Promise<HelpRegistryEntry[]> => {
+  const [apps, entries] = await Promise.all([(dependencies.listApps ?? listApps)(), (dependencies.listHelp ?? listHelp)()]);
+  const manifestHashes = new Map(apps.flatMap((app) => (app.help ? [[app.id, app.help.manifestHash] as const] : [])));
+  return entries.filter((entry) => manifestHashes.get(entry.appId) === entry.manifestHash);
+};
+
+const resolveRegistryDocuments = (
+  entry: HelpRegistryEntry,
+  requestedLocale: string,
+): { locale: string; documents: HelpRegistryDocument[] } => {
+  const baseLocale = entry.baseLocale ?? "en";
+  const variants = entry.documentsByLocale ?? {};
+  const chain = helpLocaleChain(requestedLocale, baseLocale);
+  const locale = chain.find((candidate) => candidate === baseLocale || variants[candidate] !== undefined) ?? baseLocale;
+  const byId = new Map(entry.documents.map((document) => [document.id, document]));
+  for (const candidate of [...chain.slice(0, chain.indexOf(baseLocale)), baseLocale].reverse()) {
+    if (candidate === baseLocale) continue;
+    for (const document of variants[candidate] ?? []) byId.set(document.id, { ...byId.get(document.id), ...document });
+  }
+  return { locale, documents: entry.documents.map((document) => byId.get(document.id) ?? document) };
+};
+
+export const createHelpCatalog = (entries: readonly HelpRegistryEntry[], requestedLocale = "en"): HelpCatalogDocument[] =>
+  entries
+    .flatMap((entry) => {
+      const resolved = resolveRegistryDocuments(entry, requestedLocale);
+      return resolved.documents.map((document) => ({
+        appId: entry.appId,
+        appName: entry.appName,
+        appIcon: entry.appIcon,
+        manifestHash: entry.manifestHash,
+        locale: resolved.locale,
+        documentId: document.id,
+        title: document.title,
+        description: document.description,
+        order: document.order,
+        markdown: document.markdown,
+        searchText: document.searchText ?? markdownToPlainText(document.markdown),
+      }));
+    })
+    .sort(
+      (left, right) => left.appId.localeCompare(right.appId) || left.order - right.order || left.documentId.localeCompare(right.documentId),
+    );
+
+export const loadHelpCatalog = async (dependencies: HelpCatalogDependencies = {}, requestedLocale = "en"): Promise<HelpCatalogDocument[]> =>
+  createHelpCatalog(await loadCurrentHelp(dependencies), requestedLocale);
+
+const catalogItem = (document: HelpCatalogDocument): HelpCatalogItem => ({
+  appId: document.appId,
+  appName: document.appName,
+  kind: "help",
+  locale: document.locale,
+  documentId: document.documentId,
+  title: document.title,
+  description: document.description,
+});
+
+const searchScore = (document: HelpCatalogDocument, query: string): number => {
+  const phrase = normalizeSearchText(query);
+  const terms = searchTerms(query);
+  if (!phrase || terms.length === 0) return 0;
+
+  const app = normalizeSearchText(`${document.appId} ${document.appName}`);
+  const identity = normalizeSearchText(`${document.documentId} ${document.title}`);
+  const description = normalizeSearchText(document.description ?? "");
+  const body = normalizeSearchText(document.searchText);
+  let score = 0;
+  if (identity === phrase) score += 80;
+  else if (identity.includes(phrase)) score += 40;
+  if (app.includes(phrase)) score += 30;
+  if (description.includes(phrase)) score += 20;
+  if (body.includes(phrase)) score += 10;
+  for (const term of terms) {
+    if (identity.includes(term)) score += 8;
+    if (app.includes(term)) score += 6;
+    if (description.includes(term)) score += 4;
+    if (body.includes(term)) score += 1;
+  }
+  return score;
+};
+
+export const searchHelpCatalog = (
+  catalog: readonly HelpCatalogDocument[],
+  input: { query: string; appId?: string; limit?: number },
+): HelpCatalogItem[] => {
+  const limit = Math.max(1, Math.min(Math.floor(input.limit ?? 10), HELP_SEARCH_MAX_LIMIT));
+  return catalog
+    .filter((document) => !input.appId || document.appId === input.appId)
+    .map((document) => ({ document, score: searchScore(document, input.query) }))
+    .filter(({ score }) => score > 0)
+    .sort(
+      (left, right) =>
+        right.score - left.score ||
+        left.document.appId.localeCompare(right.document.appId) ||
+        left.document.documentId.localeCompare(right.document.documentId),
+    )
+    .slice(0, limit)
+    .map(({ document }) => catalogItem(document));
+};
+
+export const findHelpDocument = (catalog: readonly HelpCatalogDocument[], appId: string, documentId: string): HelpCatalogDocument | null =>
+  catalog.find((document) => document.appId === appId && document.documentId === documentId) ?? null;
+
+const splitSections = (markdown: string): string[] => {
+  const starts = [
+    0,
+    ...Array.from(markdown.matchAll(/^##\s+/gm)).flatMap((match) =>
+      typeof match.index === "number" && match.index > 0 ? [match.index] : [],
+    ),
+  ];
+  return starts.map((start, index) => markdown.slice(start, starts[index + 1] ?? markdown.length).trim()).filter(Boolean);
+};
+
+const boundedExcerpt = (markdown: string, terms: readonly string[]): string => {
+  if (markdown.length <= HELP_READ_MAX_CHARS) return markdown;
+  const marker = "[…]";
+  const budget = HELP_READ_MAX_CHARS - marker.length * 2 - 4;
+  const lower = markdown.toLocaleLowerCase();
+  const anchors = terms.map((term) => lower.indexOf(term)).filter((index) => index >= 0);
+  const anchor = anchors.length > 0 ? Math.min(...anchors) : 0;
+  const start = Math.max(0, Math.min(markdown.length - budget, anchor - Math.floor(budget / 3)));
+  const body = markdown.slice(start, start + budget).trim();
+  return `${start > 0 ? `${marker}\n\n` : ""}${body}${start + budget < markdown.length ? `\n\n${marker}` : ""}`;
+};
+
+const selectMarkdown = (markdown: string, query?: string): { markdown: string; truncated: boolean } => {
+  if (markdown.length <= HELP_READ_MAX_CHARS) return { markdown, truncated: false };
+  const terms = searchTerms(query ?? "");
+  const phrase = normalizeSearchText(query ?? "");
+  const ranked = splitSections(markdown)
+    .map((section, index) => {
+      const text = normalizeSearchText(markdownToPlainText(section));
+      const score = (phrase && text.includes(phrase) ? 10 : 0) + terms.filter((term) => text.includes(term)).length;
+      return { section, index, score };
+    })
+    .filter(({ score }) => score > 0)
+    .sort((left, right) => right.score - left.score || left.index - right.index);
+
+  if (ranked.length === 0) return { markdown: boundedExcerpt(markdown, terms), truncated: true };
+
+  let excerpt = "";
+  for (const { section } of ranked) {
+    const candidate = excerpt ? `${excerpt}\n\n${section}` : section;
+    if (candidate.length <= HELP_READ_MAX_CHARS) excerpt = candidate;
+    else if (!excerpt) excerpt = boundedExcerpt(section, terms);
+  }
+  return { markdown: excerpt || boundedExcerpt(markdown, terms), truncated: true };
+};
+
+export const readHelpCatalog = (
+  catalog: readonly HelpCatalogDocument[],
+  input: { appId: string; documentId: string; query?: string },
+): HelpCatalogRead | null => {
+  const document = findHelpDocument(catalog, input.appId, input.documentId);
+  if (!document) return null;
+  const selected = selectMarkdown(document.markdown, input.query);
+  return { ...catalogItem(document), ...selected };
+};
+
+export const helpResourceUri = (appId: string, documentId: string): string =>
+  `cloud://help/${encodeURIComponent(appId)}/${encodeURIComponent(documentId)}`;
+
+export const parseHelpResourceUri = (uri: string): { appId: string; documentId: string } | null => {
+  const match = /^cloud:\/\/help\/([^/]+)\/([^/]+)$/.exec(uri);
+  if (!match?.[1] || !match[2]) return null;
+  try {
+    return { appId: decodeURIComponent(match[1]), documentId: decodeURIComponent(match[2]) };
+  } catch {
+    return null;
+  }
+};

package/src/_internal/help.ts

@@ -0,0 +1,95 @@
+import { createHash } from "node:crypto";
+import type { AppRegistryHelpSummary, HelpRegistryEntry } from "../contracts/registry";
+import type { HelpDefinition } from "../server/help";
+import type { HelpDocumentManifest } from "../shared/help";
+
+export const HELP_REGISTRY_MAX_BYTES = 512 * 1024;
+export const HELP_DOCUMENT_MAX_BYTES = 128 * 1024;
+
+export type CompiledHelp = {
+  summary: AppRegistryHelpSummary;
+  registryEntry: HelpRegistryEntry;
+};
+
+const serializedBytes = (value: unknown): number => new TextEncoder().encode(JSON.stringify(value)).byteLength;
+
+const helpHash = (value: unknown): string => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+
+const omitSearchText = (documents: readonly HelpRegistryEntry["documents"][number][]) =>
+  documents.map(({ searchText: _searchText, ...document }) => document);
+
+const normalizedBasePath = (basePath: string | undefined): string => {
+  const value = basePath?.replace(/\/$/, "") ?? "";
+  return value || "";
+};
+
+export const compileHelp = (input: {
+  appId: string;
+  appName: string;
+  appIcon: string;
+  basePath?: string;
+  definition: HelpDefinition;
+}): CompiledHelp => {
+  const appId = encodeURIComponent(input.appId);
+  const pageBase = `${normalizedBasePath(input.basePath)}/help`;
+  const searchUrl = `/api/help/v1/${appId}/search`;
+  const compileDocuments = (source: readonly (typeof input.definition.documents)[number][]) =>
+    source.map(({ id, title, icon, description, order, markdown, searchText }) => {
+      const markdownBytes = new TextEncoder().encode(markdown).byteLength;
+      if (markdownBytes > HELP_DOCUMENT_MAX_BYTES) {
+        throw new Error(`Help document "${id}" exceeds the ${HELP_DOCUMENT_MAX_BYTES}-byte limit`);
+      }
+      return { id, title, icon, description, order, markdown, searchText };
+    });
+  const baseLocale = input.definition.baseLocale ?? "en";
+  const documents = compileDocuments(input.definition.documents);
+  const documentsByLocale = Object.fromEntries(
+    Object.entries(input.definition.documentsByLocale ?? {})
+      .filter(([locale]) => locale !== baseLocale)
+      .map(([locale, localized]) => [locale, compileDocuments(localized)]),
+  );
+  const manifestHash = helpHash({ appId: input.appId, baseLocale, documents, documentsByLocale });
+  const toManifest = (source: readonly (typeof documents)[number][]) =>
+    source.map<HelpDocumentManifest>(({ id, title, icon, description, order }) => ({
+      id,
+      title,
+      icon,
+      description,
+      order,
+      searchUrl,
+      url: `/api/help/v1/${appId}/documents/${encodeURIComponent(id)}`,
+    }));
+  const manifest = toManifest(documents);
+  const manifestByLocale = Object.fromEntries(
+    Object.entries(documentsByLocale).map(([locale, localized]) => [locale, toManifest(localized)]),
+  );
+  let registryEntry: HelpRegistryEntry = {
+    appId: input.appId,
+    appName: input.appName,
+    appIcon: input.appIcon,
+    manifestHash,
+    baseLocale,
+    documentsByLocale,
+    documents,
+  };
+  let bytes = serializedBytes(registryEntry);
+  if (bytes > HELP_REGISTRY_MAX_BYTES) {
+    registryEntry = {
+      ...registryEntry,
+      documents: omitSearchText(registryEntry.documents),
+      documentsByLocale: registryEntry.documentsByLocale
+        ? Object.fromEntries(
+            Object.entries(registryEntry.documentsByLocale).map(([locale, localized]) => [locale, omitSearchText(localized)]),
+          )
+        : undefined,
+    };
+    bytes = serializedBytes(registryEntry);
+  }
+  if (bytes > HELP_REGISTRY_MAX_BYTES) {
+    throw new Error(`Help corpus exceeds the ${HELP_REGISTRY_MAX_BYTES}-byte registry limit`);
+  }
+  return {
+    summary: { manifestHash, pageBase, baseLocale, documentsByLocale: manifestByLocale, documents: manifest },
+    registryEntry,
+  };
+};

package/src/_internal/nats-connection.ts

@@ -0,0 +1,34 @@
+/**
+ * NATS connection for @k2b/sync — one connection per app process, created by
+ * the app lifecycle. Configuration comes from `env` (NATS_* variables); sync
+ * itself reads no ENV and loads no credentials.
+ */
+import { readFileSync } from "node:fs";
+import { connect, credsAuthenticator, type NatsConnection } from "@nats-io/transport-node";
+import { env } from "../config/env";
+
+export type ConnectNatsOptions = {
+  /** Connection name shown in NATS monitoring (`connz`), e.g. `cloud-<appId>-<instanceId>`. */
+  name: string;
+};
+
+export const connectNats = async ({ name }: ConnectNatsOptions): Promise<NatsConnection> => {
+  if (env.NATS_SERVERS.length === 0) {
+    throw new Error(
+      `NATS_SERVERS is not set (connection "${name}"). @k2b/sync needs a comma-separated list of ` +
+        "nats://host:port bootstrap servers, e.g. NATS_SERVERS=nats://ipa_nats_1:4222,nats://ipa_nats_2:4222.",
+    );
+  }
+
+  return connect({
+    servers: env.NATS_SERVERS,
+    name,
+    ignoreClusterUpdates: env.NATS_IGNORE_CLUSTER_UPDATES,
+    // Keep reconnecting for the life of the process: sync work resumes when the cluster is back.
+    reconnect: true,
+    maxReconnectAttempts: -1,
+    reconnectTimeWait: 2_000,
+    ...(env.NATS_CREDS_FILE ? { authenticator: credsAuthenticator(readFileSync(env.NATS_CREDS_FILE)) } : {}),
+    ...(env.NATS_TLS_CA_FILE ? { tls: { caFile: env.NATS_TLS_CA_FILE } } : {}),
+  });
+};

package/src/_internal/page-responses.ts

@@ -0,0 +1,40 @@
+import type { HtmlFn } from "@k2b/ssr";
+import type { Context } from "hono";
+import type { ClientErrorStatusCode, ServerErrorStatusCode } from "hono/utils/http-status";
+import { getLocale } from "../server/locale";
+import { createLoginRedirectUrl } from "../shared/redirect";
+import type { PageOptions } from "./define-app";
+
+export type PageErrorOptions = {
+  title?: string;
+  description?: string;
+  action?: { label: string; href: string; icon?: string };
+  /** Keep standalone/public pages outside the Cloud navigation shell. */
+  layout?: "cloud" | "minimal";
+};
+
+export type PageErrorStatus = ClientErrorStatusCode | ServerErrorStatusCode;
+
+/** Explicit document responses, bound to the owning application's SSR template. */
+export const createPageResponses = (html: HtmlFn<PageOptions>) => {
+  const error = async (c: Context, status: PageErrorStatus, options: PageErrorOptions = {}): Promise<Response> => {
+    // Auth middleware may reject before ssr() initializes page metadata.
+    c.set("page", { lang: getLocale(c) });
+    c.header("Cache-Control", "private, no-store");
+    // Load JSX only after the application's SSR plugin has been installed.
+    const { renderPageError } = await import("../ssr/PageError");
+    const response = await html(renderPageError(c, status, options), c.get("page"));
+    return c.newResponse(response.body, { status, headers: response.headers });
+  };
+
+  const access = {
+    onReject: (c: Context, reason: "unauthenticated" | "forbidden") => {
+      c.header("Cache-Control", "private, no-store");
+      // Account policies can reject a resolved non-user actor as unauthenticated.
+      // A browser page must not send that actor into a login/return loop.
+      return reason === "unauthenticated" && !c.get("actor") ? createLoginRedirectUrl(c.req.url) : error(c, 403);
+    },
+  };
+
+  return { access, error };
+};

package/src/_internal/process-sync.ts

@@ -0,0 +1,117 @@
+/**
+ * The one @k2b/sync instance of this process.
+ *
+ * `defineApp().start()` (and the gateway router, which has no `defineApp`)
+ * call `startProcessSync()`: connect NATS, create the instance, bind it here,
+ * and wait for `ready()`. Everything else reaches it lazily through
+ * `app.sync`, `lifecycleContext.sync`, `lazySync()`, or `getProcessSync()`;
+ * nothing touches sync during module evaluation.
+ */
+import { hostname } from "node:os";
+import { createSync, type Sync } from "@k2b/sync";
+import { env } from "../config/env";
+import { flushSyncTraceEvents, observeSyncEvent } from "../services/logging/trace";
+import { connectNats } from "./nats-connection";
+
+let current: Sync | undefined;
+let starting = false;
+
+/** Bind the process instance. `startProcessSync()` does this; tests may bind their own. */
+export const bindProcessSync = (sync: Sync): void => {
+  if (current) throw new Error("A Sync instance is already bound to this process");
+  current = sync;
+};
+
+export const unbindProcessSync = (): void => {
+  current = undefined;
+};
+
+export const getProcessSync = (): Sync => {
+  if (!current) {
+    throw new Error(
+      "Sync is not available before app.start() has connected NATS. Declare primitives with " +
+        "lazySync((sync) => sync.job(...)) and use them from lifecycle.start() or request handlers.",
+    );
+  }
+  return current;
+};
+
+/**
+ * Memoize a sync primitive per process instance so it can be declared at
+ * module scope without any I/O at import time:
+ *
+ *   const emails = lazySync((sync) => sync.job<Email>({ id: "emails" }));
+ *   await emails().submit({ key, input });
+ *
+ * The factory runs on first use with the bound instance; a different bound
+ * instance (tests) gets its own handle.
+ */
+export const lazySync = <T>(create: (sync: Sync) => T): (() => T) => {
+  const handles = new WeakMap<Sync, T>();
+  return () => {
+    const sync = getProcessSync();
+    const existing = handles.get(sync);
+    if (existing !== undefined) return existing;
+    const created = create(sync);
+    handles.set(sync, created);
+    return created;
+  };
+};
+
+export type ProcessSync = {
+  sync: Sync;
+  /** Drains sync work, then the NATS connection, and unbinds the instance. */
+  stop: () => Promise<void>;
+};
+
+/** Connect NATS, create and bind the process Sync instance, and wait until it is ready. */
+export const startProcessSync = async ({ application }: { application: string }): Promise<ProcessSync> => {
+  if (!env.SYNC_NAMESPACE.trim()) {
+    throw new Error(
+      `SYNC_NAMESPACE is not set (application "${application}"). Every process of one Cloud installation ` +
+        "must share the same @k2b/sync namespace.",
+    );
+  }
+  if (current || starting) throw new Error("A Sync instance is already starting or bound to this process");
+  starting = true;
+  try {
+    const connection = await connectNats({ name: `${application}@${hostname()}` });
+    let sync: Sync | undefined;
+    try {
+      sync = createSync({
+        connection,
+        namespace: env.SYNC_NAMESPACE,
+        application,
+        defaults: { replicas: 3 },
+        observe: (event) => observeSyncEvent(event, application),
+      });
+      bindProcessSync(sync);
+      await sync.ready();
+    } catch (error) {
+      if (current === sync) unbindProcessSync();
+      await flushSyncTraceEvents();
+      await connection.close();
+      throw error;
+    }
+    const active = sync;
+    let stopPromise: Promise<void> | undefined;
+    return {
+      sync: active,
+      stop: () =>
+        (stopPromise ??= (async () => {
+          try {
+            await active.drain();
+          } finally {
+            try {
+              await flushSyncTraceEvents();
+            } finally {
+              if (current === active) unbindProcessSync();
+              await connection.drain();
+            }
+          }
+        })()),
+    };
+  } finally {
+    starting = false;
+  }
+};