@ultimat3/core 21.0.0 → 22.1.0

package/src/lifecycle.ts

@@ -7,6 +7,7 @@ import { UltimateError } from './errors';
 import { finiteCount } from './finite-option';
 import { settleWithin } from './lifecycle-deadline';
 import { lifecycleDrained } from './lifecycle-errors';
+import { defaultReadinessGraceMs, readinessGraceIssue } from './lifecycle-grace';
 import { type LogFields, type Logger, logger as rootLogger } from './logger';
 
 export type HealthState = 'starting' | 'ready' | 'draining' | 'stopped';
@@ -54,6 +55,15 @@ export interface LifecycleOptions {
    * Screened where it is assigned: a whole number of milliseconds, 0 or more. `0` is "drain now".
    */
   readonly deadlineMs?: number | undefined;
+  /**
+   * How long `/readyz` answers 503 BEFORE the `accept` phase closes the listener — the time the
+   * endpoints controller and the ingress need to stop routing here. Closing on the flip itself left
+   * endpoints pointing at a closed socket, and a POST in that window got a 502. Added to
+   * `deadlineMs`, never taken from it. Unset: `defaultReadinessGraceMs()` of the process env at
+   * drain time — 0 in development/test, 5000 everywhere else, including a process naming no env.
+   * A whole number from 0 to 60000; 0 is no grace.
+   */
+  readonly readinessGraceMs?: number | undefined;
   readonly clock?: Clock | undefined;
   readonly logger?: Logger | undefined;
 }
@@ -111,6 +121,8 @@ interface Registration {
 const DEFAULT_DEADLINE_MS = 25_000;
 
 let deadlineMs = DEFAULT_DEADLINE_MS;
+/** `undefined` means "the environment's default", read when a drain starts, not at import. */
+let graceMs: number | undefined;
 let clock: Clock = systemClock;
 let log: Logger = rootLogger;
 let state: HealthState = 'starting';
@@ -131,6 +143,18 @@ export function configureLifecycle(options: LifecycleOptions): void {
   if (options.deadlineMs !== undefined) {
     deadlineMs = finiteCount('configureLifecycle', 'deadlineMs', options.deadlineMs, 0);
   }
+  if (options.readinessGraceMs !== undefined) {
+    const issue = readinessGraceIssue(options.readinessGraceMs);
+    if (issue !== undefined) {
+      throw new UltimateError({
+        code: 'X_CONFIG_INVALID',
+        cause: issue,
+        fix: 'pass configureLifecycle({ readinessGraceMs: 5_000 }) — or set drain: { readinessGraceMs: 5_000 } in app.config.ts',
+        meta: { key: 'drain.readinessGraceMs' },
+      });
+    }
+    graceMs = options.readinessGraceMs;
+  }
   if (options.clock !== undefined) {
     clock = options.clock;
     startedAtMono = clock.monotonic();
@@ -316,6 +340,11 @@ export function drainDeadlineMs(): number {
   return deadlineMs;
 }
 
+/** The grace the next drain will wait out — configured, else the environment's default. */
+export function readinessGraceMs(): number {
+  return graceMs ?? defaultReadinessGraceMs();
+}
+
 /**
  * What is left of that budget. Read per hook, not per phase: the deadline bounds the WHOLE drain,
  * so a hook that spent it leaves nothing for the ones behind it — which is what
@@ -354,10 +383,20 @@ async function runPhase(phase: ShutdownPhase, reason: ShutdownReason): Promise<v
   }
 }
 
-/** The three phases, in order, under one budget. Never rejects — `drain()` depends on that. */
-async function runDrain(signal: string, reason: ShutdownReason): Promise<void> {
+/**
+ * The three phases, in order, under one budget. Never rejects — `drain()` depends on that.
+ *
+ * The readiness grace runs FIRST and OUTSIDE the budget: `state` is already `draining`, so
+ * `/readyz` answers 503 while the listener still accepts what was routed here before the flip.
+ * The deadline starts after it, so a chart's `terminationGracePeriodSeconds` must exceed
+ * `readinessGraceMs + deadlineMs`.
+ */
+async function runDrain(signal: string): Promise<void> {
   try {
-    report('info', 'draining', { signal, deadlineMs, inflight });
+    const grace = readinessGraceMs();
+    report('info', 'draining', { signal, deadlineMs, readinessGraceMs: grace, inflight });
+    if (grace > 0) await Bun.sleep(grace);
+    const reason: ShutdownReason = { signal, deadlineAt: systemClock.monotonic() + deadlineMs };
     await runPhase('accept', reason);
 
     // Real monotonic, like `deadlineAt` itself: `waitForIdle` sleeps on a real `setTimeout`, and
@@ -401,7 +440,6 @@ async function runDrain(signal: string, reason: ShutdownReason): Promise<void> {
 export function drain(signal = 'manual'): Promise<void> {
   if (drainPromise !== undefined) return drainPromise;
   state = 'draining';
-  const reason: ShutdownReason = { signal, deadlineAt: systemClock.monotonic() + deadlineMs };
   let published!: () => void;
   drainPromise = new Promise<void>((resolve) => {
     published = resolve;
@@ -409,41 +447,10 @@ export function drain(signal = 'manual'): Promise<void> {
   // Both settle paths, for the reason `installSignalHandlers` gives below: `runDrain` cannot
   // reject today — that is its `try/finally`, not luck — and a rejected memo would re-reject for
   // every later caller and end the process the drain was trying to end cleanly.
-  void runDrain(signal, reason).then(published, published);
+  void runDrain(signal).then(published, published);
   return drainPromise;
 }
 
-export interface SignalHandlerOptions {
-  readonly signals?: readonly ProcessSignal[] | undefined;
-  /** Call `process.exit()` once drained. Off in tests. */
-  readonly exit?: boolean | undefined;
-}
-
-/** Install SIGTERM/SIGINT handling. Returns an uninstall function. */
-export function installSignalHandlers(options?: SignalHandlerOptions): () => void {
-  const signals: readonly ProcessSignal[] = options?.signals ?? ['SIGTERM', 'SIGINT'];
-  const handlers = new Map<ProcessSignal, () => void>();
-
-  for (const signal of signals) {
-    const handler = (): void => {
-      // Attached on BOTH settle paths, for the reason `settleWithin` gives: an unhandled rejection
-      // ends the process before the drain does, and the exit is what the kubelet is waiting for.
-      // `drain()` cannot reject today — that is the `try/finally` above, not luck — and this is
-      // the one line that keeps it true when someone changes the body.
-      const done = (): void => {
-        if (options?.exit === true) process.exit(0);
-      };
-      void drain(signal).then(done, done);
-    };
-    handlers.set(signal, handler);
-    process.on(signal, handler);
-  }
-
-  return () => {
-    for (const [signal, handler] of handlers) process.off(signal, handler);
-  };
-}
-
 export function healthReport(): HealthReport {
   const checks = readinessChecks();
   return {
@@ -479,6 +486,7 @@ export function readyzPayload(): HealthPayload {
 /** Test-only: forget all hooks and return to `starting`. */
 export function resetLifecycle(): void {
   deadlineMs = DEFAULT_DEADLINE_MS;
+  graceMs = undefined;
   clock = systemClock;
   log = rootLogger;
   state = 'starting';

package/src/logger.ts

@@ -304,6 +304,22 @@ function resolveLevel(declared: LogLevel): LogLevel {
   return declared;
 }
 
+/** The keys a line owns. A caller field spelled like one is renamed, never allowed to replace it. */
+const RESERVED_KEYS: ReadonlySet<string> = new Set(['ts', 'level', 'msg']);
+
+/**
+ * The caller's fields with any reserved key moved to `field.<key>`. Spread after `level`, a field
+ * `{ level: 'debug' }` turned an `error` line into a `debug` one, so a level-filtered alert never
+ * saw it. Renamed rather than dropped: the value is still evidence.
+ */
+function unreserved(fields: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(fields)) {
+    out[RESERVED_KEYS.has(key) ? `field.${key}` : key] = value;
+  }
+  return out;
+}
+
 export function createLogger(options?: LoggerOptions): Logger {
   const level = options?.level === undefined ? envLevel() : resolveLevel(options.level);
   const bound = options?.fields ?? {};
@@ -313,13 +329,16 @@ export function createLogger(options?: LoggerOptions): Logger {
 
   function emit(lineLevel: LogLevel, message: string, fields?: LogFields): void {
     if (LEVEL_WEIGHT[lineLevel] < threshold) return;
+    const caller = {
+      ...redactFields(bound),
+      ...redactFields(contextFields() ?? {}),
+      ...redactFields(fields ?? {}),
+    };
     const line = {
       ts: timestamp(clock),
       level: lineLevel,
       msg: message,
-      ...redactFields(bound),
-      ...redactFields(contextFields() ?? {}),
-      ...redactFields(fields ?? {}),
+      ...unreserved(caller),
     };
     writer(renderLine(line, lineLevel, message, line.ts), lineLevel);
   }

package/src/measurement-actor.ts

@@ -0,0 +1,52 @@
+// The actor a route is rendered AS when the render exists only to be weighed — `x build`'s budget
+// measurement, whose document is discarded. The default holds every permission and no app facts;
+// a page that reads the app's own facts (`useActor()` over `actorFact`) failed `X_ACTOR_UNRESOLVED`
+// under it, so the app declares its own here, from `app.config.ts`, with no import of the CLI.
+
+import type { Actor } from './actor';
+import { serviceActor } from './actor';
+import { assert } from './assert';
+
+/** The id every trace and log line under a default measurement render carries. */
+export const MEASUREMENT_ACTOR_ID = 'x-build-measure';
+
+/** What an app declares: the actor its authed pages render as while they are weighed. */
+export type MeasurementActorFactory = () => Actor | Promise<Actor>;
+
+let declared: MeasurementActorFactory | undefined;
+
+/**
+ * Declare the measurement actor. Called at module scope in `app.config.ts`, the one file every
+ * build imports. The LAST declaration wins, because `x dev` re-imports that file on a save and a
+ * refusal there would be a reload that fails over a line nobody changed.
+ *
+ * Only a render that is WEIGHED AND DISCARDED uses it — never a published `site/` artifact, whose
+ * `load` must keep failing the build rather than render this actor's rows into a file for everyone.
+ */
+export function defineMeasurementActor(factory: MeasurementActorFactory): void {
+  declared = factory;
+}
+
+/**
+ * `kind: 'service'` and `'*'`: weighing bytes needs no data authority, and an app's own
+ * `requireMember()` has nothing to resolve for a service actor, which is the honest answer.
+ */
+const defaultMeasurementActor = (): Actor =>
+  serviceActor({ id: MEASUREMENT_ACTOR_ID, permissions: ['*'] });
+
+/** The declared actor, or the framework's default. The build's ONE reader. */
+export async function measurementActor(): Promise<Actor> {
+  if (declared === undefined) return defaultMeasurementActor();
+  const actor: Actor | undefined = await declared();
+  assert(
+    typeof actor === 'object' && actor !== null && typeof actor.id === 'string',
+    'the factory handed to defineMeasurementActor() answered no actor',
+    'return one from it in app.config.ts: defineMeasurementActor(() => userActor({ id: "measure", roles: ["member"] }))',
+  );
+  return actor;
+}
+
+/** Back to the default. For a test, and for nothing else. */
+export function resetMeasurementActor(): void {
+  declared = undefined;
+}

package/src/metrics-text.ts

@@ -9,7 +9,15 @@ export const METRICS_PATH = '/metrics';
 
 export const METRICS_CONTENT_TYPE = 'text/plain; version=0.0.4; charset=utf-8';
 
-/** The exposition format escapes exactly these three, and nothing else. */
+/**
+ * HELP's two escapes, and only those: the exposition format defines `\\` and `\n` for a docstring.
+ * `\"` is a label-value escape — in HELP a parser keeps it as a literal backslash before the quote.
+ */
+function escapeHelp(value: string): string {
+  return value.replaceAll('\\', '\\\\').replaceAll('\n', '\\n');
+}
+
+/** A label VALUE escapes exactly these three, and nothing else. */
 function escapeLabel(value: string): string {
   return value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\n', '\\n');
 }
@@ -60,7 +68,7 @@ function histogramLines(name: string, point: HistogramPoint): readonly string[]
 function metricLines(metric: ReadableMetric): readonly string[] {
   const { name, kind, description, unit } = metric.descriptor;
   const help = unit === '1' || unit === '' ? description : `${description} (${unit})`;
-  const lines = [`# HELP ${name} ${escapeLabel(help)}`, `# TYPE ${name} ${kind}`];
+  const lines = [`# HELP ${name} ${escapeHelp(help)}`, `# TYPE ${name} ${kind}`];
   for (const point of metric.points) {
     if (kind === 'histogram' && isHistogramPoint(point)) {
       lines.push(...histogramLines(name, point));

package/src/metrics.ts

@@ -391,11 +391,10 @@ export function counter(name: string, options?: InstrumentOptions): Counter {
 export function gauge(name: string, options?: GaugeOptions): Gauge {
   const instrument = declare(name, 'gauge', options ?? {});
   return {
-    // The screen runs BEFORE the series is resolved, the order `counter.add` already had: a
-    // refused value must cost nothing, and `seriesFor` is not a read — it MINTS a series, one of
-    // a bounded number, keeps it for the life of the process and can trip the cardinality
-    // ceiling. `a.b += finite(…)` evaluates the reference first, so the two cannot be folded
-    // back into one expression.
+    // The screen runs BEFORE the series is resolved, as in `counter.add`: a refused value must
+    // cost nothing, and `seriesFor` MINTS a series — bounded in number, kept for the process's
+    // life, able to trip the cardinality ceiling. `a.b += finite(…)` evaluates the reference
+    // first, so the two cannot be folded into one expression.
     record(value, attributes = {}): void {
       if (!enabled) return;
       const observed = finite(name, value);
@@ -443,6 +442,10 @@ function pointsOf(instrument: Instrument): readonly MetricPoint[] {
       return [];
     }
   }
+  // Declared counter, no sample: 0, not absent (`rate()` needs a series) — until one exists.
+  const unsampled =
+    enabled && instrument.descriptor.kind === 'counter' && instrument.series.size === 0;
+  if (unsampled) return [{ attributes: {}, value: 0 }];
   return [...instrument.series.values()].map((series) =>
     instrument.descriptor.kind === 'histogram'
       ? {

package/src/otlp-metric-exporter.ts

@@ -122,7 +122,33 @@ export function otlpMetricExporter(options: OtlpMetricExporterOptions = {}): Otl
   const timeoutMs = assertFiniteOtlpBound('timeoutMs', options.timeoutMs ?? 10_000);
   const send = options.fetch ?? globalThis.fetch;
   let startedAtMs = options.startedAtMs;
-  let inflight: Promise<void> = Promise.resolve();
+  /** The ONE POST in flight, and the one body waiting behind it — never a chain. */
+  let sending: Promise<void> | undefined;
+  let waiting: string | undefined;
+
+  /**
+   * One snapshot in flight and at most one waiting. Each export used to chain a POST behind the
+   * last, so a stalled collector held every snapshot taken while it stalled. Snapshots are
+   * CUMULATIVE, so the newest supersedes every older one still waiting — dropping those loses no
+   * count — and sending strictly one at a time keeps a counter from arriving out of order and
+   * reading as a reset. `postOtlp` never rejects; the `then` pair keeps that true for this loop.
+   */
+  const pump = (): Promise<void> => {
+    if (sending !== undefined) return sending;
+    const body = waiting;
+    waiting = undefined;
+    if (body === undefined) return Promise.resolve();
+    sending = postOtlp({ url, headers, body, timeoutMs, fetch: send })
+      .then(
+        () => undefined,
+        () => undefined,
+      )
+      .then(() => {
+        sending = undefined;
+        if (waiting !== undefined) void pump();
+      });
+    return sending;
+  };
 
   return {
     export(collection: MetricCollection): void {
@@ -143,18 +169,19 @@ export function otlpMetricExporter(options: OtlpMetricExporterOptions = {}): Otl
         });
         return;
       }
-      // Chained, so a slow collector cannot make two snapshots arrive out of order and turn a
-      // cumulative counter into an apparent reset. Chained on a SETTLED shadow, for the reason
-      // `otlp-span-exporter.ts` spells out: a chain that carries a rejection forward stops calling
-      // `postOtlp` for the life of the process, in silence.
-      const settled = inflight.then(
-        () => undefined,
-        () => undefined,
-      );
-      inflight = settled.then(() => postOtlp({ url, headers, body, timeoutMs, fetch: send }));
+      waiting = body;
+      void pump();
     },
-    flush(): Promise<void> {
-      return inflight;
+    async flush(): Promise<void> {
+      // The one in flight, then the one that was waiting behind it — which that settle started.
+      // Bounded, so a timer exporting while this waits cannot keep a shutdown here forever.
+      for (
+        let round = 0;
+        round < 3 && (sending !== undefined || waiting !== undefined);
+        round += 1
+      ) {
+        await pump();
+      }
     },
   };
 }

package/src/otlp-span-exporter.ts

@@ -136,14 +136,15 @@ export function otlpSpanExporter(options: OtlpSpanExporterOptions = {}): OtlpSpa
   );
   const send = options.fetch ?? globalThis.fetch;
   const queue: ReadableSpan[] = [];
-  let inflight: Promise<void> = Promise.resolve();
+  /** The ONE batch in flight, or `undefined`. Never a chain: see `pump`. */
+  let sending: Promise<void> | undefined;
 
   const post = (batch: readonly ReadableSpan[]): Promise<void> => {
     const first = batch[0];
     if (first === undefined) return Promise.resolve();
     let body: string;
     try {
-      // The one synchronous throw on this path, and the only way `inflight` can reject at all:
+      // The one synchronous throw on this path, and the only way a send could reject at all:
       // `AttributeValue` is a compile-time claim, so an attribute the app spelled as an object, a
       // bigint or a cycle reaches `anyValue`'s `value.map(...)` as a TypeError. Dropped with a
       // line, the same degradation `postOtlp` already applies to a collector that is down —
@@ -160,25 +161,47 @@ export function otlpSpanExporter(options: OtlpSpanExporterOptions = {}): OtlpSpa
     return postOtlp({ url, headers, body, timeoutMs, fetch: send });
   };
 
-  const drainQueue = (): Promise<void> => {
-    const batch = queue.splice(0, queue.length);
-    // Chained, not concurrent: a collector reordering batches from one process turns a parent's
-    // span arriving after its child into a broken trace on the read side. Chained on a SETTLED
-    // shadow, because a chain that carries a rejection forward is poisoned for the life of the
-    // process: `post` is never called again while the queue keeps emptying, so every later span is
-    // dropped in silence and every timer tick mints a fresh unhandled rejection — which Bun ends
-    // the process on. Same shape as `offline-queue.ts`'s drain chain.
-    const settled = inflight.then(
+  /**
+   * At most ONE batch in flight, and at most `maxBatchSize` spans in it. The queue used to be
+   * moved wholesale into a promise chain behind the previous POST, so a stalled collector held
+   * every span ever exported — 100k with `maxQueueSize: 2048` — and the bound was a bound on the
+   * queue, not on memory. Now spans WAIT IN the queue while a POST is unsettled, where drop-oldest
+   * applies, and what is held is `maxQueueSize` plus one batch. One at a time also keeps batches
+   * in order, so a parent span never arrives after its child. A POST cannot reject (`postOtlp`
+   * degrades to a log line) and `post` catches its own serialisation throw, so nothing here can
+   * poison the next send.
+   */
+  const pump = (): Promise<void> => {
+    if (sending !== undefined) return sending;
+    const batch = queue.splice(0, maxBatchSize);
+    if (batch.length === 0) return Promise.resolve();
+    const current = post(batch).then(
       () => undefined,
       () => undefined,
     );
-    inflight = settled.then(() => post(batch));
-    return inflight;
+    sending = current.then(() => {
+      sending = undefined;
+      // A full batch waiting behind a slow POST goes next without waiting for the timer.
+      if (queue.length >= maxBatchSize) void pump();
+    });
+    return sending;
+  };
+
+  /** Everything queued NOW, batch by batch. Bounded, so a busy exporter cannot keep it looping. */
+  const drainQueue = async (): Promise<void> => {
+    let rounds = Math.ceil(queue.length / maxBatchSize) + 1;
+    while (rounds > 0) {
+      rounds -= 1;
+      await pump();
+      if (queue.length === 0 && sending === undefined) return;
+    }
   };
 
   // Unref'd, so a pending flush never holds a draining process open — `shutdown()` is what
   // decides the last batch leaves, exactly as `startMetricExport` defers to the drain hook.
-  const timer = setInterval(() => void drainQueue(), flushIntervalMs);
+  // `pump`, never `drainQueue`: while a POST is stalled `pump` answers the send already in flight
+  // and allocates nothing, where a drain per tick would park one more waiter per interval.
+  const timer = setInterval(() => void pump(), flushIntervalMs);
   timer.unref();
 
   return {
@@ -187,7 +210,7 @@ export function otlpSpanExporter(options: OtlpSpanExporterOptions = {}): OtlpSpa
       // the spans an operator wants during an incident are the ones happening now.
       if (queue.length >= maxQueueSize) queue.shift();
       queue.push(span);
-      if (queue.length >= maxBatchSize) void drainQueue();
+      if (queue.length >= maxBatchSize) void pump();
     },
     flush(): Promise<void> {
       return drainQueue();

package/src/same-origin.ts

@@ -0,0 +1,51 @@
+// Single responsibility: the one rule for "did this request carrying an AMBIENT credential come
+// from this app?" — `@ultimat3/http`'s CSRF check asks it of an unsafe write, and
+// `@ultimat3/realtime`'s sync node of a websocket upgrade. One rule, so a sibling origin cannot be
+// let in by one surface and refused by the other.
+
+/** The complete `Sec-Fetch-Site` vocabulary. Anything else was written by a non-browser. */
+const KNOWN_SITES = new Set(['same-origin', 'same-site', 'cross-site', 'none']);
+
+export interface OriginEvidence {
+  /** The origins this app is reached on. More than one when the scheme is not knowable here. */
+  readonly selfOrigins: readonly string[];
+  readonly origin: string | null;
+  readonly secFetchSite: string | null;
+  /** An EXACT allowance for a sibling origin — never a wildcard, never a suffix match. */
+  readonly listed: (origin: string) => boolean;
+  /** Where the operator adds an origin, named in the refusal: `http.cors.origins`, `SYNC_ORIGINS`. */
+  readonly listName: string;
+}
+
+export type OriginVerdict =
+  | { readonly ok: true }
+  /** Why it was refused, in terms the caller can act on. Never echoes a header verbatim. */
+  | { readonly ok: false; readonly reason: string };
+
+/**
+ * `sec-fetch-site` first because it is the browser's own answer and cannot be set by script;
+ * `Origin` second, so an app that lists a sibling origin keeps working. `same-site` is NOT proof:
+ * a sibling subdomain is same-site, and a `SameSite=Lax` cookie rides its requests. A request with
+ * neither header is refused — "we could not tell" is the case this exists for.
+ */
+export function proveSameOrigin(evidence: OriginEvidence): OriginVerdict {
+  const site = evidence.secFetchSite;
+  if (site === 'same-origin' || site === 'none') return { ok: true };
+  const origin = evidence.origin;
+  if (origin !== null && evidence.selfOrigins.includes(origin)) return { ok: true };
+  if (origin !== null && evidence.listed(origin)) return { ok: true };
+  // Only the four values a browser can send are quoted back. Anything else is a client that
+  // wrote the header itself, and echoing what it wrote is how a rejected value reaches the log
+  // store and the response body.
+  if (site !== null) {
+    const known = KNOWN_SITES.has(site) ? site : 'a value no browser sends';
+    return { ok: false, reason: `the request reported sec-fetch-site: ${known}` };
+  }
+  return {
+    ok: false,
+    reason:
+      origin === null
+        ? 'the request carried neither sec-fetch-site nor origin, so it cannot be shown to be same-origin'
+        : `the origin it declares is not this app and is not listed in ${evidence.listName}`,
+  };
+}

package/src/secrets-store.ts

@@ -6,9 +6,11 @@
 // `node:fs` sync, by necessity twice over: Bun.write takes no mode, and a world-readable master key
 // is the whole failure this file exists to prevent — and `installSecrets()` runs once, at boot,
 // before the process is serving anything, so there is nothing for an async read to overlap with.
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+// `renameSync` because Bun has no atomic-replace primitive, and `rmSync` to clear the temp file.
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 // Bun exposes no path-join primitive.
 import { join } from 'node:path';
+import { isUltimateError } from './errors';
 import type { SecretValues } from './secrets';
 import { masterKeyId, openSecrets, parseMasterKey, sealSecrets } from './secrets';
 import { SecretsFileMissingError, SecretsKeyMissingError } from './secrets-errors';
@@ -36,6 +38,38 @@ type EnvRecord = Record<string, string | undefined>;
 export const secretsPath = (root: string): string => join(root, SECRETS_FILE);
 export const masterKeyPath = (root: string): string => join(root, SECRETS_KEY_FILE);
 export const secretsFileExists = (root: string): boolean => existsSync(secretsPath(root));
+/**
+ * Where `x secrets rotate` STAGES a new key before sealing the committed file with it; the rename
+ * that makes it live comes last. One spelling, here, for the CLI and the runtime alike.
+ */
+export const stagedMasterKeyPath = (root: string): string => `${masterKeyPath(root)}.next`;
+
+/**
+ * The committed file, opened with `key` — or, when that key no longer opens it and a rotation left
+ * a staged key, with the staged one. A crash between the seal and the rename leaves exactly that
+ * state, and a process booting then could not read its own secrets. READ-ONLY: finishing the
+ * rotation (the rename) is `x secrets`'s recovery, never a booting process's — two replicas racing
+ * a rename is how a key gets lost. An env key is never second-guessed: the platform owns it.
+ */
+async function openWithStaged(
+  root: string,
+  key: MasterKeyRef,
+): Promise<{ readonly values: SecretValues; readonly key: MasterKeyRef }> {
+  try {
+    return { values: await readSecretsFile(root, key), key };
+  } catch (error) {
+    const staged = stagedMasterKeyPath(root);
+    const mismatch = isUltimateError(error) && error.code === 'X_SECRETS_KEY_MISMATCH';
+    if (!mismatch || key.source !== 'file' || !existsSync(staged)) throw error;
+    const candidate: MasterKeyRef = {
+      hex: readFileSync(staged, 'utf-8').trim(),
+      source: 'file',
+      at: staged,
+    };
+    // The staged key's own mismatch when neither opens it — the file's problem, not the key's.
+    return { values: await readSecretsFile(root, candidate), key: candidate };
+  }
+}
 
 /**
  * Env var first, key file second. That order is what makes one image run everywhere: a container
@@ -83,10 +117,23 @@ export async function writeSecretsFile(
   return path;
 }
 
-/** Write the master key at 0600. Callers must have made the ignore rule true first. */
+/**
+ * Write the master key at 0600. Callers must have made the ignore rule true first.
+ *
+ * Through a fresh temp file renamed over the target, never a write in place: `mode` applies only
+ * when a write CREATES the file, so rotating over a key that was 0644 left the new key 0644. The
+ * rename is also atomic — a reader sees the old key or the new one, never half of either.
+ */
 export function writeMasterKeyFile(root: string, keyHex: string): string {
   const path = masterKeyPath(root);
-  writeFileSync(path, `${keyHex}\n`, { encoding: 'utf-8', mode: SECRETS_KEY_MODE });
+  const temp = `${path}.${crypto.randomUUID()}.tmp`;
+  try {
+    writeFileSync(temp, `${keyHex}\n`, { encoding: 'utf-8', mode: SECRETS_KEY_MODE, flag: 'wx' });
+    renameSync(temp, path);
+  } catch (error) {
+    rmSync(temp, { force: true });
+    throw error;
+  }
   return path;
 }
 
@@ -149,8 +196,7 @@ export async function installSecrets(
       skipped: [],
     };
   }
-  const key = requireMasterKey(root, env);
-  const values = await readSecretsFile(root, key);
+  const { values, key } = await openWithStaged(root, requireMasterKey(root, env));
   const installed: string[] = [];
   const skipped: string[] = [];
   for (const [name, value] of Object.entries(values)) {

package/src/source-mask.ts

@@ -27,11 +27,41 @@ export function endOfLiteral(text: string, from: number): number {
   for (let i = from + 1; i < text.length; i += 1) {
     if (text[i] === '\\') i += 1;
     else if (text[i] === quote) return i + 1;
+    else if (spansLines && text[i] === '$' && text[i + 1] === '{')
+      i = endOfInterpolation(text, i + 2) - 1;
     else if (!spansLines && text[i] === '\n') return from + 1;
   }
   return spansLines ? text.length : from + 1;
 }
 
+/**
+ * Index just past the `}` closing a template's `${` whose body starts at `from`. The body is CODE:
+ * braces nest, and a string or a template inside it is skipped whole — a nested template's backtick
+ * read as the outer one's close desynced every literal after it, and `scripts/guards-doc.ts` lost
+ * every `code:` below the nesting to the gate. Comments in the body are skipped the same way.
+ */
+function endOfInterpolation(text: string, from: number): number {
+  let depth = 1;
+  let i = from;
+  while (i < text.length) {
+    const ch = text[i] as string;
+    if (ch === '/' && (text[i + 1] === '/' || text[i + 1] === '*')) {
+      const line = text[i + 1] === '/';
+      const end = line ? text.indexOf('\n', i) : text.indexOf('*/', i + 2);
+      i = end === -1 ? text.length : line ? end : end + 2;
+    } else if (QUOTES.has(ch)) i = endOfLiteral(text, i);
+    else if (ch === '{') {
+      depth += 1;
+      i += 1;
+    } else if (ch === '}') {
+      depth -= 1;
+      i += 1;
+      if (depth === 0) return i;
+    } else i += 1;
+  }
+  return text.length;
+}
+
 /**
  * Whether the `/` at `at` opens a regex rather than divides — the call no scanner without a parser
  * avoids. A regex cannot follow what ends an expression: an identifier that is not one of the words

package/src/type-pins.ts

@@ -132,6 +132,15 @@ type _RealtimeConfigCarriesNoDeadField = Assert<
   Extract<keyof RealtimeConfig, DeadRealtimeField> extends never ? true : false
 >;
 
+/**
+ * `'redis'` accepted, built by nothing, and booted whichever bus `NATS_URL` chose — removed in
+ * 22.0.0 when `selectTransport` began building what `transport` says. Re-adding it to the union is
+ * a type that promises a bus the framework does not have.
+ */
+type _RealtimeTransportHasNoRedis = Assert<
+  'redis' extends RealtimeConfig['transport'] ? false : true
+>;
+
 /** And the input side with it — `Input<RealtimeConfig>` is what an `app.config.ts` writes. */
 type _RealtimeInputCarriesNoDeadField = Assert<
   Extract<keyof NonNullable<AppConfigInput['realtime']>, DeadRealtimeField> extends never