@ultimat3/core 24.0.0 → 25.0.0

package/src/metric-series.ts

@@ -0,0 +1,94 @@
+// Single responsibility: one series per label set under an instrument — its stable key, and the
+// cardinality ceiling past which every new label set folds into one overflow series, reported once.
+
+import { logger } from './logger';
+import { MetricCardinalityError } from './metric-errors';
+import { assertLabelNames } from './metric-names';
+import type { Instrument, Series } from './metric-registry';
+import type { MetricAttributes } from './metrics-types';
+
+/**
+ * The label the folded series carries. OTel's own cardinality-limit spelling, deliberately NOT
+ * `__overflow`: Prometheus treats `__`-prefixed labels as internal and strips them during
+ * relabeling, so an overflow series named that way would merge back into the unlabelled series
+ * and the drop would be invisible in exactly the place it has to be visible.
+ */
+export const OVERFLOW_ATTRIBUTE = 'otel_metric_overflow';
+
+const OVERFLOW_ATTRIBUTES: MetricAttributes = Object.freeze({ [OVERFLOW_ATTRIBUTE]: true });
+
+/**
+ * Stable series key: attribute order must not create a second series for one label set, and no
+ * label set may spell another one's key.
+ *
+ * `JSON.stringify` over the sorted pairs, because a DELIMITER cannot carry the second property:
+ * the key was the pairs joined by control characters (U+0000 inside a pair, U+0001 between them),
+ * and a value holding those bytes IS another set's key — `{ a: 'b\u0001c\u0000d' }` was
+ * `{ a: 'b', c: 'd' }`, so the point landed on whichever series arrived first and was exported
+ * under labels the caller never passed. Attribute values are app data. Quoting is the only total
+ * answer and is not slower: 644 ns/op against the join's 709, on a 3-label set. `String(value)`
+ * stays, so `1` and `'1'` are still one series rather than two rows an exporter renders alike.
+ */
+function seriesKey(attributes: MetricAttributes): string {
+  const entries = Object.entries(attributes);
+  if (entries.length === 0) return '';
+  return JSON.stringify(
+    entries.sort(([a], [b]) => (a < b ? -1 : 1)).map(([key, value]) => [key, String(value)]),
+  );
+}
+
+/**
+ * Reported through the logger rather than thrown: the call site is `orderCounter.add(1, …)` deep
+ * inside a request, and killing that request would turn a metrics bug into a user-visible outage
+ * — which is the same trade `finite()` does NOT make, because a NaN is a caller bug at one call
+ * site while this is a design bug the whole instrument shares.
+ */
+function reportOverflow(instrument: Instrument): void {
+  if (instrument.overflowed) return;
+  instrument.overflowed = true;
+  const { name, kind } = instrument.descriptor;
+  const error = new MetricCardinalityError({
+    cause: `${name} reached its ceiling of ${instrument.maxSeries} label set(s); every further label set folds into one ${OVERFLOW_ATTRIBUTE}="true" series`,
+    fix: `drop the unbounded label from the ${name} call site (an id, a path, an email is never a label), or raise it deliberately: ${kind}('${name}', { maxSeries: ${instrument.maxSeries * 2} })`,
+    meta: { metric: name, maxSeries: instrument.maxSeries },
+  });
+  logger.error(error.format(), { code: error.code, metric: name });
+}
+
+function createSeries(instrument: Instrument, key: string, attributes: MetricAttributes): Series {
+  const created: Series = {
+    attributes,
+    value: 0,
+    count: 0,
+    min: Number.POSITIVE_INFINITY,
+    max: Number.NEGATIVE_INFINITY,
+    buckets: new Array<number>(instrument.bounds.length + 1).fill(0),
+  };
+  instrument.series.set(key, created);
+  return created;
+}
+
+const OVERFLOW_KEY = seriesKey(OVERFLOW_ATTRIBUTES);
+
+export function seriesFor(instrument: Instrument, attributes: MetricAttributes): Series {
+  const key = seriesKey(attributes);
+  const found = instrument.series.get(key);
+  if (found !== undefined) return found;
+  // On the MISS, ahead of the ceiling — never inside `createSeries`, which the overflow branch
+  // below returns without reaching. A screen that ran only where a series is BORN was a screen
+  // that depended on load: `bad"key` threw on a fresh process and was swallowed on a busy one,
+  // once the instrument had filled up, which is exactly when an unparseable label is likeliest to
+  // arrive. A hit needs no check — a key in the map passed this on the way in.
+  assertLabelNames(instrument.descriptor.name, attributes);
+  if (instrument.series.size >= instrument.maxSeries) {
+    reportOverflow(instrument);
+    // Created directly rather than through this function again: the overflow series is the ONE
+    // allocation the ceiling does not apply to, and routing it back through the check is an
+    // infinite recursion the first time the cap is hit.
+    return (
+      instrument.series.get(OVERFLOW_KEY) ??
+      createSeries(instrument, OVERFLOW_KEY, OVERFLOW_ATTRIBUTES)
+    );
+  }
+  return createSeries(instrument, key, attributes);
+}

package/src/metrics.ts

@@ -5,9 +5,10 @@
 import { assert } from './assert';
 import { type Clock, systemClock } from './clock';
 import { renderThrowable } from './error-render';
-import { type CodedErrorInit, UltimateError } from './errors';
 import { logger } from './logger';
-import { assertLabelNames, assertMetricName, MetricNameInvalidError } from './metric-names';
+import { finite, MetricValueInvalidError } from './metric-errors';
+import { declare, type Instrument, instruments } from './metric-registry';
+import { seriesFor } from './metric-series';
 import type {
   Counter,
   Gauge,
@@ -15,19 +16,19 @@ import type {
   Histogram,
   HistogramOptions,
   InstrumentOptions,
-  MetricAttributes,
   MetricCollection,
-  MetricDescriptor,
   MetricExporter,
-  MetricKind,
   MetricPoint,
 } from './metrics-types';
 import { serviceResource } from './telemetry';
 
-// The data model and the identifier grammar are modules of their own; the public surface is
-// unchanged, so nothing that imports a metric type or the name error from here learns a second
-// path.
+// The data model, the identifier grammar, the refusals, the registry and the series store are
+// modules of their own; the public surface is unchanged, so nothing that imports a metric type, a
+// constant or an error from here learns a second path.
+export { MetricCardinalityError, MetricValueInvalidError } from './metric-errors';
 export { MetricNameInvalidError } from './metric-names';
+export { DEFAULT_HISTOGRAM_BOUNDS, DEFAULT_MAX_SERIES } from './metric-registry';
+export { OVERFLOW_ATTRIBUTE } from './metric-series';
 export type {
   Counter,
   Gauge,
@@ -46,44 +47,6 @@ export type {
   ReadableMetric,
 } from './metrics-types';
 
-export class MetricValueInvalidError extends UltimateError {
-  static readonly code = 'X_METRIC_VALUE_INVALID';
-  override readonly name = 'MetricValueInvalidError';
-  constructor(init: CodedErrorInit) {
-    super({ ...init, code: MetricValueInvalidError.code });
-  }
-}
-
-export class MetricCardinalityError extends UltimateError {
-  static readonly code = 'X_METRIC_CARDINALITY';
-  override readonly name = 'MetricCardinalityError';
-  constructor(init: CodedErrorInit) {
-    super({ ...init, code: MetricCardinalityError.code });
-  }
-}
-
-/**
- * The per-instrument series ceiling. 2000 is roomy for a bounded label set — every route pattern
- * times every status class times every method — and small enough that the process notices an
- * unbounded one long before the scrape body does.
- */
-export const DEFAULT_MAX_SERIES = 2000;
-
-/**
- * The label the folded series carries. OTel's own cardinality-limit spelling, deliberately NOT
- * `__overflow`: Prometheus treats `__`-prefixed labels as internal and strips them during
- * relabeling, so an overflow series named that way would merge back into the unlabelled series
- * and the drop would be invisible in exactly the place it has to be visible.
- */
-export const OVERFLOW_ATTRIBUTE = 'otel_metric_overflow';
-
-const OVERFLOW_ATTRIBUTES: MetricAttributes = Object.freeze({ [OVERFLOW_ATTRIBUTE]: true });
-
-/** OTel's default explicit bucket boundaries for a duration histogram, in seconds. */
-export const DEFAULT_HISTOGRAM_BOUNDS: readonly number[] = Object.freeze([
-  0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10,
-]);
-
 export const noopMetricExporter: MetricExporter = Object.freeze({
   export(): void {
     // Intentionally empty: instruments are always live, and free until an exporter is configured.
@@ -115,29 +78,6 @@ export interface MetricsOptions {
   readonly enabled?: boolean | undefined;
 }
 
-interface Series {
-  readonly attributes: MetricAttributes;
-  value: number;
-  count: number;
-  min: number;
-  max: number;
-  buckets: number[];
-}
-
-interface Instrument {
-  readonly descriptor: MetricDescriptor;
-  readonly series: Map<string, Series>;
-  readonly bounds: readonly number[];
-  readonly observe: (() => number) | undefined;
-  readonly maxSeries: number;
-  /** Reported once. A cardinality blow-up is one bug, not one log line per call. */
-  overflowed: boolean;
-  /** Reported once, for the same reason: a scrape every 15s must not become a log every 15s. */
-  observeFailed: boolean;
-}
-
-const instruments = new Map<string, Instrument>();
-
 let exporter: MetricExporter = noopMetricExporter;
 let clock: Clock = systemClock;
 let enabled = true;
@@ -164,154 +104,6 @@ export function resetMetrics(): void {
   }
 }
 
-/**
- * Stable series key: attribute order must not create a second series for one label set, and no
- * label set may spell another one's key.
- *
- * `JSON.stringify` over the sorted pairs, because a DELIMITER cannot carry the second property:
- * the key was the pairs joined by control characters (U+0000 inside a pair, U+0001 between them),
- * and a value holding those bytes IS another set's key — `{ a: 'b\u0001c\u0000d' }` was
- * `{ a: 'b', c: 'd' }`, so the point landed on whichever series arrived first and was exported
- * under labels the caller never passed. Attribute values are app data. Quoting is the only total
- * answer and is not slower: 644 ns/op against the join's 709, on a 3-label set. `String(value)`
- * stays, so `1` and `'1'` are still one series rather than two rows an exporter renders alike.
- */
-function seriesKey(attributes: MetricAttributes): string {
-  const entries = Object.entries(attributes);
-  if (entries.length === 0) return '';
-  return JSON.stringify(
-    entries.sort(([a], [b]) => (a < b ? -1 : 1)).map(([key, value]) => [key, String(value)]),
-  );
-}
-
-function finite(name: string, value: number): number {
-  if (!Number.isFinite(value)) {
-    throw new MetricValueInvalidError({
-      cause: `${name} was given ${String(value)}, which is not a finite number`,
-      fix: `guard the value at the call site: Number.isFinite(v) before recording into ${name}`,
-      meta: { metric: name, received: String(value) },
-    });
-  }
-  return value;
-}
-
-/**
- * Bounds are strictly ascending finite numbers, refused at DECLARATION like `maxSeries` beside it.
- * `record` takes the first bound an observation fits, and the exposition format emits one
- * cumulative `le` series per bound in array order — so `[1, 0.5, 5]` both counted observations
- * into a bucket that was not theirs and rendered a non-monotonic `le` series that Prometheus and
- * OpenMetrics each reject. Two wrong numbers, neither visible from the other, and nothing at the
- * call site to notice: the observations themselves were all valid.
- */
-function assertBounds(name: string, bounds: readonly number[] | undefined): void {
-  if (bounds === undefined) return;
-  const bad = bounds.findIndex((bound, index) => {
-    const previous = index === 0 ? Number.NEGATIVE_INFINITY : (bounds[index - 1] as number);
-    return !Number.isFinite(bound) || bound <= previous;
-  });
-  if (bad === -1) return;
-  const repaired = [...new Set(bounds.filter((bound) => Number.isFinite(bound)))].sort(
-    (left, right) => left - right,
-  );
-  throw new MetricNameInvalidError({
-    cause: `${name} declared bounds [${bounds.map((bound) => String(bound)).join(', ')}], which are not strictly ascending finite numbers — [${String(bad)}] is ${String(bounds[bad])}`,
-    fix: `sort the bounds and drop the duplicates: histogram('${name}', { bounds: [${repaired.join(', ')}] })`,
-    meta: { metric: name, bounds: bounds.map((bound) => String(bound)), at: bad },
-  });
-}
-
-function declare(name: string, kind: MetricKind, options: GaugeOptions & HistogramOptions) {
-  assertMetricName(name);
-  assertBounds(name, options.bounds);
-  const existing = instruments.get(name);
-  if (existing !== undefined) {
-    if (existing.descriptor.kind !== kind) {
-      throw new MetricNameInvalidError({
-        cause: `"${name}" is already declared as a ${existing.descriptor.kind}, redeclared as a ${kind}`,
-        fix: `rename one of the two instruments named "${name}" — one metric name, one kind`,
-        meta: { name, declared: existing.descriptor.kind, requested: kind },
-      });
-    }
-    assertSameDeclaration(name, existing, options);
-    return existing;
-  }
-  const maxSeries = options.maxSeries ?? DEFAULT_MAX_SERIES;
-  if (!Number.isInteger(maxSeries) || maxSeries < 1) {
-    throw new MetricCardinalityError({
-      cause: `${name} declared maxSeries ${String(maxSeries)}, which is not a positive integer`,
-      fix: `pass a positive integer: counter('${name}', { maxSeries: ${DEFAULT_MAX_SERIES} })`,
-      meta: { metric: name, maxSeries: String(maxSeries) },
-    });
-  }
-  const instrument: Instrument = {
-    descriptor: {
-      name,
-      kind,
-      unit: options.unit ?? '1',
-      description: options.description ?? '',
-    },
-    series: new Map<string, Series>(),
-    bounds: options.bounds ?? DEFAULT_HISTOGRAM_BOUNDS,
-    observe: options.observe,
-    maxSeries,
-    overflowed: false,
-    observeFailed: false,
-  };
-  instruments.set(name, instrument);
-  return instrument;
-}
-
-/**
- * A second declaration that STATES a different shape is refused. The first declaration wins, so a
- * second `histogram(name, { bounds })` recorded into buckets another module chose and a second
- * `gauge(name, { observe })` was collected through the first module's observer — silently, in both
- * cases, which is the whole failure. An OMITTED option is not a conflict: `gauge(name)` is how a
- * module takes a handle on an instrument someone else declared, and `maxSeries` keeps its shipped
- * first-declaration-wins rule because it decides a ceiling rather than what gets recorded.
- */
-function assertSameDeclaration(
-  name: string,
-  existing: Instrument,
-  options: GaugeOptions & HistogramOptions,
-): void {
-  const { bounds, observe } = options;
-  if (bounds !== undefined && !sameBounds(existing.bounds, bounds)) {
-    throw new MetricNameInvalidError({
-      cause: `"${name}" is already declared with bounds [${existing.bounds.join(', ')}] and is redeclared with [${bounds.join(', ')}]; the first declaration wins, so the second set would never be used`,
-      fix: `declare "${name}" once and export the handle — import it where you record — or give the second instrument its own name`,
-      meta: { name, declared: existing.bounds.join(','), requested: bounds.join(',') },
-    });
-  }
-  if (observe !== undefined && observe !== existing.observe) {
-    throw new MetricNameInvalidError({
-      cause: `"${name}" is already declared with an observe() callback and is redeclared with a different one; the first declaration wins, so the second callback would never be read`,
-      fix: `declare "${name}" once and export the handle — import it where you read — or give the second gauge its own name`,
-      meta: { name },
-    });
-  }
-}
-
-const sameBounds = (left: readonly number[], right: readonly number[]): boolean =>
-  left.length === right.length && left.every((bound, index) => bound === right[index]);
-
-/**
- * Reported through the logger rather than thrown: the call site is `orderCounter.add(1, …)` deep
- * inside a request, and killing that request would turn a metrics bug into a user-visible outage
- * — which is the same trade `finite()` does NOT make, because a NaN is a caller bug at one call
- * site while this is a design bug the whole instrument shares.
- */
-function reportOverflow(instrument: Instrument): void {
-  if (instrument.overflowed) return;
-  instrument.overflowed = true;
-  const { name, kind } = instrument.descriptor;
-  const error = new MetricCardinalityError({
-    cause: `${name} reached its ceiling of ${instrument.maxSeries} label set(s); every further label set folds into one ${OVERFLOW_ATTRIBUTE}="true" series`,
-    fix: `drop the unbounded label from the ${name} call site (an id, a path, an email is never a label), or raise it deliberately: ${kind}('${name}', { maxSeries: ${instrument.maxSeries * 2} })`,
-    meta: { metric: name, maxSeries: instrument.maxSeries },
-  });
-  logger.error(error.format(), { code: error.code, metric: name });
-}
-
 /**
  * Reported through the logger for `reportOverflow`'s reason and once for the same one — a scrape
  * runs on a timer, so a permanently broken observer would otherwise write a log line every
@@ -332,44 +124,6 @@ function reportObserveFailure(instrument: Instrument, thrown: unknown): void {
   logger.error(error.format(), { code: error.code, metric: name });
 }
 
-function createSeries(instrument: Instrument, key: string, attributes: MetricAttributes): Series {
-  const created: Series = {
-    attributes,
-    value: 0,
-    count: 0,
-    min: Number.POSITIVE_INFINITY,
-    max: Number.NEGATIVE_INFINITY,
-    buckets: new Array<number>(instrument.bounds.length + 1).fill(0),
-  };
-  instrument.series.set(key, created);
-  return created;
-}
-
-const OVERFLOW_KEY = seriesKey(OVERFLOW_ATTRIBUTES);
-
-function seriesFor(instrument: Instrument, attributes: MetricAttributes): Series {
-  const key = seriesKey(attributes);
-  const found = instrument.series.get(key);
-  if (found !== undefined) return found;
-  // On the MISS, ahead of the ceiling — never inside `createSeries`, which the overflow branch
-  // below returns without reaching. A screen that ran only where a series is BORN was a screen
-  // that depended on load: `bad"key` threw on a fresh process and was swallowed on a busy one,
-  // once the instrument had filled up, which is exactly when an unparseable label is likeliest to
-  // arrive. A hit needs no check — a key in the map passed this on the way in.
-  assertLabelNames(instrument.descriptor.name, attributes);
-  if (instrument.series.size >= instrument.maxSeries) {
-    reportOverflow(instrument);
-    // Created directly rather than through this function again: the overflow series is the ONE
-    // allocation the ceiling does not apply to, and routing it back through the check is an
-    // infinite recursion the first time the cap is hit.
-    return (
-      instrument.series.get(OVERFLOW_KEY) ??
-      createSeries(instrument, OVERFLOW_KEY, OVERFLOW_ATTRIBUTES)
-    );
-  }
-  return createSeries(instrument, key, attributes);
-}
-
 /** Monotonic sum. A negative `add` is a bug in the caller, never a silent decrement. */
 export function counter(name: string, options?: InstrumentOptions): Counter {
   const instrument = declare(name, 'counter', options ?? {});

package/src/page.ts

@@ -10,7 +10,7 @@
 // The client seam's own functions, for the hooks a browser island calls: the one transport, the
 // URL rule, the principal-supersession reader, and the small helpers realtime's browser half uses.
 // Each reaches no titles table — `page-bundle.test.ts` builds all of them together to prove it.
-export { invariant } from './assert';
+export { assertCoded } from './assert';
 export type { AsyncState } from './async-state';
 export type { JitterMode, Random } from './backoff';
 export { backoffDelay } from './backoff';
@@ -32,7 +32,7 @@ export type { UltimateErrorInit } from './errors';
 export { isUltimateError, UltimateError } from './errors';
 export { finiteCount, finiteOption } from './finite-option';
 export { isSuperseded } from './generation-fence';
-export { uuid } from './ids';
+export { uuidV7 } from './ids';
 export { isJsonObject } from './json-object';
 export type { OutboxDrainMessage } from './outbox-drain';
 export { OUTBOX_DRAIN_MESSAGE } from './outbox-drain';
@@ -54,5 +54,7 @@ export type { RecordEnvelope, RecordRows } from './record-envelope';
 export { decodeRecordEnvelope, RECORDS_HEADER } from './record-envelope';
 export type { PageClient, RecordSink } from './record-sink';
 export { pageClient } from './record-sink';
+// The key the theme boot script reads and the toggle island writes.
+export { THEME_STORAGE_KEY } from './theme-storage';
 // A write's public name, so the page's store can recognise the `records` frame its own write made.
 export { isWriteDigest, WRITE_DIGEST_LENGTH, writeDigest } from './write-digest';

package/src/registrar.ts

@@ -84,6 +84,7 @@ export const PRIMITIVE_FACTORIES = Object.freeze<readonly PrimitiveFactory[]>(
       { factory: 'exportRows', pkg: '@ultimat3/jobs', kind: 'job' },
       { factory: 'purge', pkg: '@ultimat3/jobs', kind: 'job' },
       { factory: 'webhook', pkg: '@ultimat3/jobs', kind: 'job' },
+      { factory: 'mcpConfirmations', pkg: '@ultimat3/mcp', kind: 'action' },
       { factory: 'notifier', pkg: '@ultimat3/notify', kind: 'job' },
       { factory: 'scrape', pkg: '@ultimat3/scraping', kind: 'job' },
     ] satisfies readonly PrimitiveFactory[]

package/src/retry.ts

@@ -3,7 +3,13 @@
 // nothing in the tree consulted it before deciding to try again, so four packages each shipped
 // their own loop and only `@ultimat3/jobs`' asked the classification at all.
 
-import { type BackoffCurve, backoffDelay, type JitterMode, type Random } from './backoff';
+import {
+  type BackoffCurve,
+  backoffDelay,
+  type JitterMode,
+  jitterStatedDelay,
+  type Random,
+} from './backoff';
 import { systemClock } from './clock';
 import { classifyThrown, type ErrorRetry, statedDelayMs } from './error-retry';
 import { finiteCount, finiteOption } from './finite-option';
@@ -13,7 +19,11 @@ export interface RetryPolicy {
   readonly attempts: number;
   /** The first delay, in ms. */
   readonly base: number;
-  /** Ceiling for any single delay, in ms — a `retry-after` the responder named included. */
+  /**
+   * Ceiling for any single delay, in ms. A `retry-after` the responder named is clamped to it
+   * too, and then gets its spread on top — at most half again, so a burst told one delay does
+   * not wake together (`jitterStatedDelay`).
+   */
   readonly max: number;
   /**
    * Required, unlike `backoffDelay`'s, and that is the point: a retry loop with no jitter is the
@@ -92,9 +102,19 @@ export function retryDecision(
   const stated = classification === 'retry-after' ? statedDelayMs(error) : undefined;
   return {
     retry: true,
-    // Clamped by the policy's own ceiling, which is what `max` is for: a responder naming a day is
-    // still a responder this deployment has not agreed to wait a day for.
-    delayMs: stated === undefined ? computed : Math.min(stated, policy.max),
+    // The stated delay is a FLOOR plus a spread (`jitterStatedDelay`), never the bare number: a
+    // shedding server tells a whole burst `Retry-After: 1`, and waiting exactly that replays the
+    // burst in lockstep every second. The floor is clamped by the policy's own ceiling, which is
+    // what `max` is for — a responder naming a day is still a responder this deployment has not
+    // agreed to wait a day for — and the spread on top is at most half of it.
+    // `jitter: 'none'` is honoured here too — the caller's one decision, for a test or a printable
+    // schedule — and only that mode gets the bare floor.
+    delayMs:
+      stated === undefined
+        ? computed
+        : policy.jitter === 'none'
+          ? Math.min(stated, policy.max)
+          : jitterStatedDelay(Math.min(stated, policy.max), policy.max, random),
     attempt,
     nextAttempt: attempt + 1,
     classification,

package/src/secrets-key-file.ts

@@ -0,0 +1,139 @@
+// Single responsibility: writing a master-key file that only its owner can read, on every platform,
+// and renaming one over another without losing to a reader that holds it open. POSIX gets the first
+// from the create mode. Windows ignores the mode — the file inherits the profile directory's ACL —
+// so there the temp file's ACL is cut to the current account BEFORE the rename makes it live.
+
+// why: `node:fs` sync — Bun.write takes no mode and has no atomic rename; both run once, at a CLI
+// command or at boot, before anything is served, so there is nothing for an async call to overlap.
+import { renameSync, rmSync, writeFileSync } from 'node:fs';
+import { backoffDelay } from './backoff';
+import { renderCauseValue, stringField } from './error-render';
+import { UltimateError } from './errors';
+
+/** How long `icacls` or `whoami` may take before the write is refused as a failed ACL. */
+const ACL_TIMEOUT_MS = 10_000;
+
+/** Owner read/write — the mode every key file is CREATED with. */
+export const OWNER_ONLY_MODE = 0o600;
+
+/**
+ * Tries for a rename over a file another process holds open. Windows refuses that rename with
+ * EPERM or EBUSY rather than replacing the name the way POSIX does — an editor, an indexer or an
+ * antivirus scan holding `.secrets.key` for a moment — so a short, bounded retry outlasts the
+ * holder; a holder that never lets go is still an error, after ~150 ms rather than never.
+ */
+export const RENAME_ATTEMPTS = 5;
+const isHeldOpen = (code: string | undefined): boolean => code === 'EPERM' || code === 'EBUSY';
+
+/** Every effect, injectable: the Windows branch is proven on Linux with a fake. */
+export interface KeyFileIo {
+  readonly platform: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly writeExclusive: (path: string, text: string, mode: number) => void;
+  readonly rename: (from: string, to: string) => void;
+  readonly remove: (path: string) => void;
+  readonly runAcl: (argv: readonly string[]) => { exitCode: number; output: string };
+  readonly username: () => string;
+  readonly sleep: (ms: number) => void;
+}
+
+/** Built per call, never at import: the barrel reaches this module from browser bundles too. */
+const systemIo = (): KeyFileIo => ({
+  platform: process.platform,
+  env: process.env,
+  // `wx`: the mode applies only when a write CREATES the file, so never write into a leftover.
+  writeExclusive: (path, text, mode) =>
+    writeFileSync(path, text, { encoding: 'utf-8', mode, flag: 'wx' }),
+  rename: renameSync,
+  remove: (path) => rmSync(path, { force: true }),
+  runAcl: (argv) => {
+    // Bounded: icacls on one local file answers in milliseconds; a hang must not hold the boot.
+    const ran = Bun.spawnSync([...argv], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+      timeout: ACL_TIMEOUT_MS,
+    });
+    return {
+      exitCode: ran.exitCode,
+      output: `${ran.stdout.toString()}${ran.stderr.toString()}`.trim(),
+    };
+  },
+  // `whoami` prints `DOMAIN\user`, the form icacls resolves. Never `node:os`'s `userInfo`: the
+  // browser polyfill lacks it, and the barrel reaches this module from every island's bundle.
+  username: () =>
+    Bun.spawnSync(['whoami'], { stdout: 'pipe', timeout: ACL_TIMEOUT_MS }).stdout.toString().trim(),
+  sleep: (ms) => Bun.sleepSync(ms),
+});
+
+/** The account the key is granted to: `DOMAIN\user` where Windows names both. */
+export function aclPrincipal(
+  env: Readonly<Record<string, string | undefined>>,
+  username: () => string,
+): string {
+  const user = env['USERNAME'];
+  const domain = env['USERDOMAIN'];
+  if (user !== undefined && user !== '') {
+    return domain !== undefined && domain !== '' ? `${domain}\\${user}` : user;
+  }
+  return username();
+}
+
+/**
+ * `/inheritance:r` drops every ACE the directory handed down; `/grant:r` REPLACES any explicit one
+ * for the principal with full control. What is left is one entry: the account that wrote the key.
+ */
+export function ownerOnlyAclArgv(path: string, principal: string): readonly string[] {
+  return ['icacls', path, '/inheritance:r', '/grant:r', `${principal}:F`];
+}
+
+/** icacls refused, so the key was never written: no file is better than a readable one. */
+export class SecretsKeyAclError extends UltimateError {
+  constructor(input: { path: string; principal: string; exitCode: number; output: string }) {
+    super({
+      code: 'X_SECRETS_KEY_ACL_FAILED',
+      cause: `icacls could not restrict ${renderCauseValue(input.path)} to ${renderCauseValue(input.principal)} (exit ${input.exitCode}: ${renderCauseValue(input.output)}), so the key was not written — on Windows a file's mode does not keep other accounts out, its ACL does`,
+      fix: 'x doctor --json   # on Windows: where.exe icacls must resolve (C:\\Windows\\System32) and whoami names the account the key is granted to — or keep no key file and set ULTIMATE_SECRETS_KEY instead',
+      meta: { path: input.path, exitCode: input.exitCode },
+    });
+  }
+}
+
+/** On win32, cut `path`'s ACL to the current account. A no-op elsewhere: the mode did it. */
+export function restrictToOwner(path: string, io: KeyFileIo = systemIo()): void {
+  if (io.platform !== 'win32') return;
+  const principal = aclPrincipal(io.env, io.username);
+  const ran = io.runAcl(ownerOnlyAclArgv(path, principal));
+  if (ran.exitCode !== 0) {
+    throw new SecretsKeyAclError({ path, principal, exitCode: ran.exitCode, output: ran.output });
+  }
+}
+
+/** `rename(from, to)`, retried on EPERM/EBUSY only, `RENAME_ATTEMPTS` tries in all. */
+export function renameOver(from: string, to: string, io: KeyFileIo = systemIo()): void {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      io.rename(from, to);
+      return;
+    } catch (error) {
+      if (attempt >= RENAME_ATTEMPTS || !isHeldOpen(stringField(error, 'code'))) throw error;
+      io.sleep(backoffDelay({ attempt, base: 10, max: 160 }));
+    }
+  }
+}
+
+/**
+ * Write `text` to `path`, readable by its owner alone, atomically: a fresh temp file created at
+ * 0600 (and ACL-restricted on Windows) is renamed over the target, so a reader sees the old file or
+ * the new one, and rotating over a key that was world-readable never leaves the new key so.
+ */
+export function writeOwnerOnlyFile(path: string, text: string, io: KeyFileIo = systemIo()): void {
+  const temp = `${path}.${crypto.randomUUID()}.tmp`;
+  try {
+    io.writeExclusive(temp, text, OWNER_ONLY_MODE);
+    restrictToOwner(temp, io);
+    renameOver(temp, path, io);
+  } catch (error) {
+    io.remove(temp);
+    throw error;
+  }
+}