@k2b/cloud 0.19.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -93,23 +93,23 @@
     "@firecrawl/anydoc": "0.2.4",
     "@napi-rs/canvas": "1.0.9",
     "pdfjs-dist": "6.3.289",
-    "@hono/standard-validator": "0.2.2",
-    "@simplewebauthn/server": "14.0.2",
-    "@tabler/icons": "3.47.0",
+    "@simplewebauthn/server": "14.0.3",
+    "@tabler/icons": "3.48.0",
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.12.1",
     "@k2b/ssr": "0.14.0",
-    "@k2b/ui": "0.9.0",
-    "@k2b/stdlib": "0.26.0",
-    "@k2b/sync": "6.5.0",
+    "@k2b/ui": "0.10.0",
+    "@k2b/stdlib": "0.27.0",
+    "@k2b/sync": "7.0.0",
+    "@nats-io/jetstream": "3.4.0",
     "@nats-io/transport-node": "3.4.0",
-    "@modelcontextprotocol/sdk": "1.30.0",
+    "@modelcontextprotocol/sdk": "1.30.1",
     "bun-plugin-tailwind": "0.1.2",
-    "hono-openapi": "1.3.1",
+    "hono-openapi": "1.3.3",
     "jose": "6.2.12",
-    "katex": "0.18.7",
+    "katex": "0.18.9",
     "liquidjs": "10.29.0",
-    "marked": "17.0.6",
+    "marked": "18.0.14",
     "mermaid": "12.0.0",
     "nodemailer": "10.0.10",
     "postcss": "8.5.28",
@@ -129,10 +129,10 @@
     "@babel/preset-typescript": "8.0.1",
     "@types/bun": "1.4.2",
     "babel-preset-solid": "1.9.15",
-    "hono": "4.13.8",
-    "playwright": "1.62.0",
+    "hono": "4.13.9",
+    "playwright": "1.63.0",
     "solid-js": "1.9.15",
-    "typescript": "5.9.3",
+    "typescript": "7.0.2",
     "zod": "4.6.5"
   },
   "peerDependencies": {

package/scripts/build.ts

@@ -32,6 +32,7 @@ import { promisify } from "node:util";
 import { brotliCompress, gzip, constants as zlibConstants } from "node:zlib";
 import { Glob } from "bun";
 import tailwind from "bun-plugin-tailwind";
+import type { AppCliModules } from "../src/contracts/app";
 import { writeAppFavicon } from "./app-favicon";
 import { buildBrowserPerformance } from "./browser-performance";
 import { buildPdfRenderer } from "./build-pdf-renderer";
@@ -181,7 +182,8 @@ if (existsSync(appAssets)) {
 // `cld` plugins: one self-contained module bundle plus references per module.
 // Imported after the app config so the framework sees the APP_DIR set above.
 const { buildCliPlugin, writeCliPlugin } = await import("../src/_internal/cli-plugins");
-for (const [name, declaration] of Object.entries(app?.meta.cli ?? {})) {
+const cliModules: AppCliModules = app?.meta.cli ?? {};
+for (const [name, declaration] of Object.entries(cliModules)) {
   const plugin = await buildCliPlugin({ appDir, appId, name, declaration, version });
   await writeCliPlugin(resolve(dist, "cli", name), plugin);
 }

package/scripts/sync-recovery-smoke.ts

@@ -68,10 +68,7 @@ Run "prepare", restart the application fleet while NATS stays up, then run "reco
   check(phase === "prepare" || phase === "recover", "Pass prepare or recover");
   const namespace = options.namespace?.trim() ?? "";
   check(/^cloud-recovery-smoke-[A-Za-z0-9_-]{6,60}$/.test(namespace), "Pass a unique --namespace cloud-recovery-smoke-<suffix>");
-  const servers = (env.NATS_SERVERS ?? "nats://127.0.0.1:4222")
-    .split(",")
-    .map((value) => value.trim())
-    .filter(Boolean);
+  const servers = env.NATS_SERVERS.length ? env.NATS_SERVERS : ["nats://127.0.0.1:4222"];
   const connection = await connect({ servers, name: `${APPLICATION}-${phase}`, ignoreClusterUpdates: true });
   const sync = createSync({ connection, namespace, application: APPLICATION, defaults: { replicas: env.SYNC_REPLICAS } });
   const job = sync.job<{ preparedAt: string }>({

package/src/_internal/define-app.ts

@@ -48,6 +48,7 @@ import { requireInvocation } from "../server/middleware/invocation";
 import { matchedRouteTemplate, routeTemplate } from "../server/middleware/route-template";
 import { runtime as runtimeMiddleware } from "../server/middleware/runtime";
 import { preloadLayoutAnnouncements, settings as settingsMiddleware } from "../server/middleware/settings";
+import { validationErrorResponse } from "../server/middleware/validator";
 import {
   capabilityInvocationOperation,
   searchInvocationOperation,
@@ -72,6 +73,7 @@ import { readBoundedJson } from "./bounded-json";
 import { appRuntimeMetadata } from "./build-metadata";
 import { compileCapabilities, invokeCompiledCapability, reviewCompiledCapability, serializeCapabilityProviderResult } from "./capabilities";
 import { cliPluginRoutePrefixes, createCliPluginRoutes, validateAppCliModules } from "./cli-plugins";
+import { FONT_PRELOAD_LINKS } from "./font-preloads";
 import { createHeartbeat } from "./heartbeat";
 import { compileHelp } from "./help";
 import { createPageResponses } from "./page-responses";
@@ -355,6 +357,7 @@ export const defineApp = <
     <link rel="icon" href="${appFaviconHref(opts.id, v)}">
     <style data-cloud-css-layers>@layer properties, theme, base, components, utilities;</style>
     <link rel="preload" href="/public/tabler-icons.woff2" as="font" type="font/woff2" crossorigin>
+    ${FONT_PRELOAD_LINKS}
     <link rel="stylesheet" href="/public/fonts.css?v=${v}">
     <link rel="stylesheet" href="/public/tabler-icons.css?v=${v}">
     <link rel="stylesheet" href="/public/${opts.id}/app.css?v=${v}">
@@ -774,6 +777,7 @@ export const defineApp = <
       if (advertiseOpenapi) {
         const apiPrefix = opts.openapi!.replace(/\/openapi\.json$/, "") || "/";
         const spec = await generateSpecs(startOpts.openapi!, {
+          defaultValidationErrorResponse: validationErrorResponse,
           documentation: {
             info: {
               title: meta.name,

package/src/_internal/font-preloads.ts

@@ -0,0 +1,25 @@
+/// <reference path="../types/k2b-ui-fonts.d.ts" />
+import plexPreset from "@k2b/ui/fonts/plex.css" with { type: "text" };
+
+/**
+ * Preload tags for the IBM Plex Sans faces that every page sets in its first
+ * frame: Latin text at 400, 500 (buttons, labels) and 600 (headings).
+ *
+ * The preset declares its faces with `font-display: swap`. Without a preload
+ * the browser requests a face only when layout needs it, paints the fallback
+ * font and re-wraps the text once Plex arrives. That moves every box after the
+ * first changed line, and on a vertically centered page such as sign-in the
+ * whole form. Preloaded, the faces download next to the render-blocking
+ * stylesheets and the first frame already uses them.
+ *
+ * Core serves the faces under `/public/fonts/` with the preset's
+ * content-hashed file names (`packages/core/scripts/font-assets.ts`). The
+ * preset is bundled as text, so production servers need no `node_modules`.
+ */
+export const FONT_PRELOAD_LINKS = ["400", "500", "600"]
+  .map((weight) => {
+    const file = new RegExp(`url\\(\\./fonts/(ibm-plex-sans-latin-${weight}-normal-[0-9a-f]+\\.woff2)\\)`).exec(plexPreset)?.[1];
+    if (!file) throw new Error(`The @k2b/ui Plex preset has no Latin IBM Plex Sans ${weight} face`);
+    return `<link rel="preload" href="/public/fonts/${file}" as="font" type="font/woff2" crossorigin>`;
+  })
+  .join("\n    ");

package/src/_internal/nats-connection.ts

@@ -12,15 +12,9 @@ export type ConnectNatsOptions = {
   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({
+/** Dial `NATS_SERVERS` once. `startProcessSync()` requires the list and retries while NATS does not answer. */
+export const connectNats = async ({ name }: ConnectNatsOptions): Promise<NatsConnection> =>
+  connect({
     servers: env.NATS_SERVERS,
     name,
     ignoreClusterUpdates: env.NATS_IGNORE_CLUSTER_UPDATES,
@@ -31,4 +25,3 @@ export const connectNats = async ({ name }: ConnectNatsOptions): Promise<NatsCon
     ...(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/process-sync.ts

@@ -8,10 +8,14 @@
  * nothing touches sync during module evaluation.
  */
 import { hostname } from "node:os";
-import { createSync, type Sync } from "@k2b/sync";
+import { createSync, type Sync, SyncError } from "@k2b/sync";
+import { expBackoff } from "@k2b/sync/retry";
+import type { NatsConnection } from "@nats-io/transport-node";
 import { env } from "../config/env";
+import { logger } from "../services/logging";
 import { flushSyncTraceEvents, observeSyncEvent } from "../services/logging/trace";
 import { connectNats } from "./nats-connection";
+import { withSyncBudgets } from "./sync-budget";
 
 let current: Sync | undefined;
 let starting = false;
@@ -64,7 +68,94 @@ export type ProcessSync = {
   stop: () => Promise<void>;
 };
 
-/** Connect NATS, create and bind the process Sync instance, and wait until it is ready. */
+/**
+ * How long a starting process waits for NATS and JetStream. After a host or
+ * stack restart, NATS nodes come up in any order and JetStream must recover
+ * its streams and elect a leader before its API answers; five minutes covers
+ * that. A process that still gets no answer exits instead of staying alive
+ * without readiness, so Docker or Kubernetes restarts it and the outage shows
+ * up as restarts.
+ */
+const NATS_STARTUP_BUDGET_MS = 5 * 60_000;
+// About 1 s, doubling to 20 s, each ±50 % so processes that restarted together spread their retries.
+const NATS_STARTUP_BACKOFF = { baseMs: 1_000, maxMs: 20_000, jitter: 0.5 };
+
+const errorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+/**
+ * Run `attempt` until it succeeds, with exponential backoff and jitter. A
+ * `SyncError` describes the server or the declarations (unsupported version,
+ * JetStream disabled, drift), which waiting does not change, so it fails at
+ * once. Every other failure (refused or unresolved address, timeout, JetStream
+ * without a leader) is logged and retried until `budgetMs` is spent; then the
+ * process exits with status 1.
+ */
+export const waitForNats = async <T>(
+  attempt: () => Promise<T>,
+  { application, budgetMs = NATS_STARTUP_BUDGET_MS }: { application: string; budgetMs?: number },
+): Promise<T> => {
+  const log = logger("sync");
+  const deadline = Date.now() + budgetMs;
+  for (let attempts = 1; ; attempts++) {
+    try {
+      const result = await attempt();
+      if (attempts > 1) log.info("NATS and JetStream answered", { application, attempts });
+      return result;
+    } catch (error) {
+      if (error instanceof SyncError) throw error;
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) {
+        log.error("NATS and JetStream did not answer within the startup budget; exiting so the process is restarted", {
+          application,
+          attempts,
+          budgetMs,
+          error: errorMessage(error),
+        });
+        process.exit(1);
+      }
+      const retryInMs = Math.min(remainingMs, expBackoff(attempts, NATS_STARTUP_BACKOFF));
+      log.warn("NATS or JetStream is not ready; retrying", { application, attempt: attempts, retryInMs, error: errorMessage(error) });
+      await Bun.sleep(retryInMs);
+    }
+  }
+};
+
+/** One start attempt: connect, bind a new Sync instance, and wait for `ready()`; release both when it fails. */
+const connectReadySync = async (application: string): Promise<{ sync: Sync; connection: NatsConnection }> => {
+  const connection = await connectNats({ name: `${application}@${hostname()}` });
+  let sync: Sync | undefined;
+  try {
+    sync = withSyncBudgets(
+      createSync({
+        connection,
+        namespace: env.SYNC_NAMESPACE,
+        application,
+        defaults: { replicas: env.SYNC_REPLICAS },
+        observe: (event) => observeSyncEvent(event, application),
+      }),
+      { connection, namespace: env.SYNC_NAMESPACE },
+    );
+    bindProcessSync(sync);
+    await sync.ready();
+    return { sync, connection };
+  } catch (error) {
+    if (current === sync) unbindProcessSync();
+    await flushSyncTraceEvents();
+    await connection.close();
+    throw error;
+  }
+};
+
+/**
+ * Connect NATS, create and bind the process Sync instance, and wait until it is
+ * ready. Existing streams of its jobs, queues, and topics take the byte
+ * limits they declare before first use (see `sync-budget.ts`).
+ *
+ * While NATS or JetStream does not answer, it retries with a fresh connection
+ * and instance (see `waitForNats`), and exits the process once
+ * `NATS_STARTUP_BUDGET_MS` is spent. Callers are process entry points; nothing
+ * serves readiness before this returns.
+ */
 export const startProcessSync = async ({ application }: { application: string }): Promise<ProcessSync> => {
   if (!env.SYNC_NAMESPACE.trim()) {
     throw new Error(
@@ -72,28 +163,16 @@ export const startProcessSync = async ({ application }: { application: string })
         "must share the same @k2b/sync namespace.",
     );
   }
+  if (env.NATS_SERVERS.length === 0) {
+    throw new Error(
+      `NATS_SERVERS is not set (application "${application}"). @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.",
+    );
+  }
   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: env.SYNC_REPLICAS },
-        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;
+    const { sync: active, connection } = await waitForNats(() => connectReadySync(application), { application });
     let stopPromise: Promise<void> | undefined;
     return {
       sync: active,

package/src/_internal/status-preserving-ssr.ts

@@ -28,6 +28,9 @@ type SsrHandler<E extends Env, T extends object> = (context: Context<E & PageEnv
  * (such as the request locale for `<html lang>`) are present on every SSR
  * page without per-route plumbing. Redirects and other passthrough Responses
  * skip it.
+ *
+ * Rendered documents default to `Cache-Control: private, no-store` unless the
+ * handler or a middleware already chose a policy.
  */
 export const createStatusPreservingSsrHandler = <T extends object>(
   html: HtmlFn<T>,
@@ -55,7 +58,12 @@ export const createStatusPreservingSsrHandler = <T extends object>(
       response.headers.forEach((value, key) => {
         headers[key] = value;
       });
-      return context.newResponse(response.body, status as StatusCode, headers);
+      const document = context.newResponse(response.body, status as StatusCode, headers);
+      // A rendered document carries the signed-in user's state. Without an
+      // explicit policy, a browser may show it again on Back from its HTTP
+      // cache, even after sign-out. Handlers that set their own policy keep it.
+      if (!document.headers.has("Cache-Control")) document.headers.set("Cache-Control", "private, no-store");
+      return document;
     });
   };
 };

package/src/_internal/sync-budget.ts

@@ -0,0 +1,306 @@
+/**
+ * Brings existing JetStream streams to the byte limits that the Sync jobs,
+ * queues, and topics of one Cloud process declare.
+ *
+ * JetStream reserves a stream's whole `max_bytes` on every replica as soon as
+ * the stream exists. @k2b/sync 7 declares small limits: a job or queue without
+ * `retention` holds 256 messages at its payload limit, and `deadLetterRetention`
+ * sizes dead letters apart from the work or event stream. Sync never
+ * reconfigures an existing stream, though. A stream created with other limits,
+ * such as the 1 GiB that Sync 6 gave every job and queue without `retention`,
+ * fails the declaration with `ResourceDriftError` on `max_bytes`.
+ *
+ * Before a job, queue, or topic is first used, this module therefore changes
+ * the byte limit of such a stream in place: both streams of a job or queue,
+ * and the dead-letter stream of a topic. A stream that holds more than its new
+ * limit would lose its oldest messages; it keeps its limit instead:
+ *
+ * - a job or queue is declared with the stream's current limit, so its work
+ *   stays usable, and a later start applies the new limit;
+ * - a topic is declared synchronously, before its streams can be inspected,
+ *   so its declaration keeps reporting the drift until the stream holds less.
+ */
+import {
+  type DeadLetterStore,
+  type Job,
+  type JobConfig,
+  type Queue,
+  type QueueConfig,
+  ResourceDriftError,
+  type Sync,
+  type Topic,
+  type TopicConfig,
+} from "@k2b/sync";
+import { jetstreamManager, RetentionPolicy, type StreamInfo } from "@nats-io/jetstream";
+import type { NatsConnection } from "@nats-io/transport-node";
+import { logger } from "../services/logging";
+
+/** Sync 7's limits for a job or queue declared without `retention`, which @k2b/sync does not export. */
+const SYNC_PAYLOAD_BYTES = 128 * 1024;
+const SYNC_DEAD_LETTER_HEADROOM_BYTES = 4096;
+const SYNC_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Byte limit Sync 7 gives a job or queue without `retention`: 256 messages at its payload limit, at most 1 GiB. */
+export const syncDefaultMaxBytes = (maxPayloadBytes = SYNC_PAYLOAD_BYTES): number =>
+  Math.min(1024 ** 3, 256 * (maxPayloadBytes + SYNC_DEAD_LETTER_HEADROOM_BYTES));
+
+const log = logger("sync:budget");
+
+type Kind = "job" | "queue" | "topic";
+type Limits = { work: number; deadLetters: number };
+
+/** Memoizes a promise, forgetting a rejection so the next call retries. */
+const once = <T>(create: () => Promise<T>): (() => Promise<T>) => {
+  let pending: Promise<T> | undefined;
+  return () =>
+    (pending ??= create().catch((error: unknown) => {
+      pending = undefined;
+      throw error;
+    }));
+};
+
+/** The stream and declared byte limit when Sync refused a declaration only for an existing stream's byte limit. */
+const byteLimitDrift = (error: unknown): { stream: string; maxBytes: number } | undefined => {
+  if (!(error instanceof ResourceDriftError) || error.differences.length !== 1) return undefined;
+  const [difference] = error.differences;
+  if (difference?.field !== "max_bytes" || typeof difference.declared !== "number") return undefined;
+  return { stream: error.resource, maxBytes: difference.declared };
+};
+
+/** Byte limits a job or queue declares for its work and dead-letter streams. */
+const declaredLimits = (config: QueueConfig | JobConfig): Limits => {
+  const work = config.retention?.maxBytes ?? syncDefaultMaxBytes(config.maxPayloadBytes);
+  return { work, deadLetters: config.deadLetterRetention?.maxBytes ?? work };
+};
+
+/** The declaration with the given limits, or unchanged when they are its own. */
+const withLimits = <Config extends QueueConfig | JobConfig>(config: Config, target: Limits, limits: Limits): Config =>
+  limits.work === target.work && limits.deadLetters === target.deadLetters
+    ? config
+    : {
+        ...config,
+        retention: { maxAgeMs: SYNC_MAX_AGE_MS, ...config.retention, maxBytes: limits.work },
+        deadLetterRetention: { ...config.deadLetterRetention, maxBytes: limits.deadLetters },
+      };
+
+const createStreamLimits = (connection: NatsConnection, namespace: string) => {
+  const manager = once(() => jetstreamManager(connection));
+
+  /**
+   * Work and dead-letter streams per job and queue of this namespace as they
+   * are now. Concurrent callers share one listing; a later call lists again,
+   * so streams that another process created or changed since are seen.
+   */
+  let listing: Promise<Map<string, StreamInfo[]>> | undefined;
+  const list = () =>
+    (listing ??= (async () => {
+      const jsm = await manager();
+      const streams = new Map<string, StreamInfo[]>();
+      for await (const info of jsm.streams.list()) {
+        const metadata = info.config.metadata;
+        const kind = metadata?.["sync.kind"];
+        if (metadata?.["sync.namespace"] !== namespace || metadata["sync.managed"] !== "true") continue;
+        // A job's coalescing claims live in a KV bucket without a byte limit.
+        if ((kind !== "job" && kind !== "queue") || info.config.name.startsWith("KV_")) continue;
+        const key = `${kind}:${metadata["sync.id"]}`;
+        streams.set(key, [...(streams.get(key) ?? []), info]);
+      }
+      return streams;
+    })().finally(() => {
+      listing = undefined;
+    }));
+
+  /**
+   * Limits a job or queue declares: its own, except for an existing stream
+   * that holds more than its new limit, which keeps its current limit.
+   */
+  const keep = async (kind: Kind, id: string, target: Limits): Promise<Limits> => {
+    const streams = (await list()).get(`${kind}:${id}`) ?? [];
+    const kept = (info: StreamInfo | undefined, maxBytes: number): number => {
+      if (!info || info.config.max_bytes === maxBytes || info.state.bytes <= maxBytes) return maxBytes;
+      log.warn("Kept the byte limit of a Sync stream that holds more than its new limit", {
+        kind,
+        id,
+        stream: info.config.name,
+        limit: info.config.max_bytes,
+        target: maxBytes,
+        held: info.state.bytes,
+      });
+      return info.config.max_bytes;
+    };
+    return {
+      work: kept(
+        streams.find((info) => info.config.retention === RetentionPolicy.Workqueue),
+        target.work,
+      ),
+      deadLetters: kept(
+        streams.find((info) => info.config.retention !== RetentionPolicy.Workqueue),
+        target.deadLetters,
+      ),
+    };
+  };
+
+  /** Streams reported as too full to lower; a topic retries on every use, but logs once. */
+  const reported = new Set<string>();
+
+  /**
+   * Provisions a declaration. Each existing stream whose byte limit differs
+   * from the declared one gets the declared limit if it holds no more; then
+   * the declaration is tried again. Each stream is changed at most once. Of a
+   * topic, only the dead-letter stream, whose subjects end in `.dlq.>`, is
+   * changed: its event stream keeps Sync's drift check, so applications that
+   * declare one topic differently still fail instead of overwriting each
+   * other's limit.
+   */
+  const adopt = async (kind: Kind, id: string, ready: () => Promise<void>): Promise<void> => {
+    const changed = new Set<string>();
+    for (;;) {
+      try {
+        return await ready();
+      } catch (error) {
+        const drift = byteLimitDrift(error);
+        if (!drift || changed.has(drift.stream)) throw error;
+        changed.add(drift.stream);
+        const jsm = await manager();
+        const info = await jsm.streams.info(drift.stream);
+        if (kind === "topic" && !info.config.subjects.some((subject) => subject.endsWith(".dlq.>"))) throw error;
+        if (info.state.bytes > drift.maxBytes) {
+          if (reported.has(drift.stream)) throw error;
+          reported.add(drift.stream);
+          log.warn("Kept the byte limit of a Sync stream that holds more than its new limit", {
+            kind,
+            id,
+            stream: drift.stream,
+            limit: info.config.max_bytes,
+            target: drift.maxBytes,
+            held: info.state.bytes,
+          });
+          throw error;
+        }
+        await jsm.streams.update(drift.stream, { max_bytes: drift.maxBytes });
+        log.info("Changed the byte limit of a Sync stream", {
+          kind,
+          id,
+          stream: drift.stream,
+          from: info.config.max_bytes,
+          to: drift.maxBytes,
+        });
+      }
+    }
+  };
+
+  return { keep, adopt };
+};
+
+const deferDeadLetters = <T>(resolve: () => Promise<{ deadLetters: DeadLetterStore<T> }>): DeadLetterStore<T> => ({
+  page: async (options) => (await resolve()).deadLetters.page(options),
+  get: async (input) => (await resolve()).deadLetters.get(input),
+  list: async (options) => (await resolve()).deadLetters.list(options),
+  requeue: async (input) => (await resolve()).deadLetters.requeue(input),
+  delete: async (input) => (await resolve()).deadLetters.delete(input),
+});
+
+const deferJob = <Input>(resolve: () => Promise<Job<Input>>): Job<Input> => ({
+  ready: async () => (await resolve()).ready(),
+  submit: async (job) => (await resolve()).submit(job),
+  submitMany: async (jobs, options) => (await resolve()).submitMany(jobs, options),
+  submitBatch: async (jobs) => (await resolve()).submitBatch(jobs),
+  pause: async (options) => (await resolve()).pause(options),
+  resume: async () => (await resolve()).resume(),
+  process: async (options, handler) => (await resolve()).process(options, handler),
+  deadLetters: deferDeadLetters(resolve),
+});
+
+const deferQueue = <T>(resolve: () => Promise<Queue<T>>): Queue<T> => ({
+  ready: async () => (await resolve()).ready(),
+  send: async (message) => (await resolve()).send(message),
+  sendBatch: async (messages) => (await resolve()).sendBatch(messages),
+  pause: async (options) => (await resolve()).pause(options),
+  resume: async () => (await resolve()).resume(),
+  process: async (options, handler) => (await resolve()).process(options, handler),
+  reader: async (options) => (await resolve()).reader(options),
+  deadLetters: deferDeadLetters(resolve),
+});
+
+/** A declared topic whose every provisioning use waits until `ready` has adopted its streams. */
+const deferTopic = <T>(topic: Topic<T>, ready: () => Promise<void>): Topic<T> => {
+  const whenReady = <Result>(use: () => Promise<Result>): Promise<Result> => ready().then(use);
+  const iterateWhenReady = async function* <Event>(open: () => AsyncIterable<Event>): AsyncIterable<Event> {
+    await ready();
+    yield* open();
+  };
+  return {
+    ready,
+    publish: (input) => whenReady(() => topic.publish(input)),
+    publishBatch: (input) => whenReady(() => topic.publishBatch(input)),
+    hub: (options) => {
+      const hub = topic.hub(options);
+      return { subscribe: (subscription) => iterateWhenReady(() => hub.subscribe(subscription)), close: () => hub.close() };
+    },
+    cursorSequence: (cursor) => topic.cursorSequence(cursor),
+    cursorAt: (sequence) => topic.cursorAt(sequence),
+    pauseConsumer: (input) => whenReady(() => topic.pauseConsumer(input)),
+    resumeConsumer: (input) => whenReady(() => topic.resumeConsumer(input)),
+    latestCursor: (options) => whenReady(() => topic.latestCursor(options)),
+    head: () => whenReady(() => topic.head()),
+    live: (options) => iterateWhenReady(() => topic.live(options)),
+    replay: (options) => iterateWhenReady(() => topic.replay(options)),
+    follow: (options) => iterateWhenReady(() => topic.follow(options)),
+    destroy: () => topic.destroy(),
+    process: (options, handler) => whenReady(() => topic.process(options, handler)),
+    deadLetters: {
+      list: (options) => whenReady(() => topic.deadLetters.list(options)),
+      get: (input) => whenReady(() => topic.deadLetters.get(input)),
+      delete: (input) => whenReady(() => topic.deadLetters.delete(input)),
+      replay: (input) => whenReady(() => topic.deadLetters.replay(input)),
+    },
+  };
+};
+
+/**
+ * The process Sync whose jobs, queues, and topics adopt the byte limits of
+ * their existing streams before first use. A job or queue is declared to Sync
+ * on its first use or on `ready()`; a topic is declared at once. Every other
+ * primitive is Sync's own.
+ */
+export const withSyncBudgets = (sync: Sync, { connection, namespace }: { connection: NatsConnection; namespace: string }): Sync => {
+  const { keep, adopt } = createStreamLimits(connection, namespace);
+  /** Every job, queue, and topic declared so far, so `ready()` provisions them like Sync does. */
+  const declared = new Map<string, () => Promise<unknown>>();
+
+  const declareWork = <Config extends QueueConfig | JobConfig, Handle extends { ready(): Promise<void> }>(
+    kind: "job" | "queue",
+    config: Config,
+    create: (config: Config) => Handle,
+  ): (() => Promise<Handle>) => {
+    // Declared once: Sync refuses a second declaration with other limits, so a
+    // failed first use retries provisioning with the limits chosen first.
+    const declaration = once(async () => {
+      const target = declaredLimits(config);
+      return create(withLimits(config, target, await keep(kind, config.id, target)));
+    });
+    const resolve = once(async () => {
+      const handle = await declaration();
+      await adopt(kind, config.id, () => handle.ready());
+      return handle;
+    });
+    declared.set(`${kind}:${config.id}`, resolve);
+    return resolve;
+  };
+
+  return {
+    ...sync,
+    ready: async () => {
+      await Promise.all([...declared.values()].map((resolve) => resolve()));
+      await sync.ready();
+    },
+    job: <Input>(config: JobConfig) => deferJob(declareWork("job", config, (declaration) => sync.job<Input>(declaration))),
+    queue: <T>(config: QueueConfig) => deferQueue(declareWork("queue", config, (declaration) => sync.queue<T>(declaration))),
+    topic: <T>(config: TopicConfig) => {
+      const topic = sync.topic<T>(config);
+      const ready = once(() => adopt("topic", config.id, () => topic.ready()));
+      declared.set(`topic:${config.id}`, ready);
+      return deferTopic(topic, ready);
+    },
+  };
+};