@ultimat3/core 21.0.0 → 22.0.0

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/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/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

package/src/result.ts

@@ -1,78 +0,0 @@
-// Single responsibility: `Result<T, E>` for boundaries where throwing is wrong —
-// validation seams, driver probes, CLI commands that must render `--json` either way.
-
-import { toUltimateError, type UltimateError } from './errors';
-
-export interface Ok<T> {
-  readonly ok: true;
-  readonly value: T;
-}
-
-export interface Err<E> {
-  readonly ok: false;
-  readonly error: E;
-}
-
-export type Result<T, E = UltimateError> = Ok<T> | Err<E>;
-
-export function ok<T>(value: T): Ok<T> {
-  return { ok: true, value };
-}
-
-export function err<E>(error: E): Err<E> {
-  return { ok: false, error };
-}
-
-export function isOk<T, E>(result: Result<T, E>): result is Ok<T> {
-  return result.ok;
-}
-
-export function isErr<T, E>(result: Result<T, E>): result is Err<E> {
-  return !result.ok;
-}
-
-export function map<T, E, U>(result: Result<T, E>, fn: (value: T) => U): Result<U, E> {
-  return result.ok ? ok(fn(result.value)) : result;
-}
-
-export function mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F> {
-  return result.ok ? result : err(fn(result.error));
-}
-
-export function unwrapOr<T, E>(result: Result<T, E>, fallback: T): T {
-  return result.ok ? result.value : fallback;
-}
-
-/** Throws the contained error — use only where a throw is genuinely correct. */
-export function unwrap<T, E>(result: Result<T, E>): T {
-  if (result.ok) return result.value;
-  throw toUltimateError(result.error);
-}
-
-export function tryCatch<T>(fn: () => Promise<T>): Promise<Result<T, UltimateError>>;
-export function tryCatch<T>(fn: () => T): Result<T, UltimateError>;
-export function tryCatch<T>(
-  fn: () => T | Promise<T>,
-): Result<T, UltimateError> | Promise<Result<T, UltimateError>> {
-  try {
-    const value = fn();
-    if (isPromiseLike(value)) {
-      return value.then(
-        (resolved) => ok(resolved),
-        (reason: unknown) => err(toUltimateError(reason)),
-      );
-    }
-    return ok(value);
-  } catch (thrown) {
-    return err(toUltimateError(thrown));
-  }
-}
-
-function isPromiseLike<T>(value: T | Promise<T>): value is Promise<T> {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'then' in value &&
-    typeof (value as { then: unknown }).then === 'function'
-  );
-}