@ultimat3/core 23.0.0 → 25.0.0

package/src/measurement-actor.ts

@@ -30,6 +30,9 @@ export function defineMeasurementActor(factory: MeasurementActorFactory): void {
 /**
  * `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.
+ * No org and no roles, so a page whose policy names a role or whose `load` reads a tenant-scoped
+ * entity is refused under it — the `budgets` step's `X_BUDGET_UNMEASURED` names this actor, the
+ * refusal and `defineMeasurementActor()` for exactly that page.
  */
 const defaultMeasurementActor = (): Actor =>
   serviceActor({ id: MEASUREMENT_ACTOR_ID, permissions: ['*'] });
@@ -41,11 +44,23 @@ export async function measurementActor(): Promise<Actor> {
   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"] }))',
+    // Placeholders, not `roles: ["member"]`: the actor exists to pass the app's OWN gates, and a
+    // literal role here is one a `dev`-gated console refuses too (#675).
+    'return one from it in app.config.ts: defineMeasurementActor(() => userActor({ id: "measure", orgId: "<an org your dev seed creates>", roles: ["<the role your gated pages require>"] }))',
   );
   return actor;
 }
 
+/**
+ * The factory declared now, or `undefined` for the default — read, never called. The test
+ * preload's file boundary snapshots it beside the other process registries: `app.config.ts`
+ * declares at module scope, ONCE per process, so a file that imported an app's config left every
+ * later file measuring as that app's actor (`prerender-actor.test.ts`, denied X_FORBIDDEN).
+ */
+export function declaredMeasurementActor(): MeasurementActorFactory | undefined {
+  return declared;
+}
+
 /** Back to the default. For a test, and for nothing else. */
 export function resetMeasurementActor(): void {
   declared = undefined;

package/src/metric-errors.ts

@@ -0,0 +1,32 @@
+// Single responsibility: the two coded refusals a metric VALUE or a series CEILING earns, and the
+// finiteness screen every recording path runs first. The name grammar's refusal is
+// `metric-names.ts`'s; `metrics.ts` re-exports all three, so callers keep one import path.
+
+import { type CodedErrorInit, UltimateError } from './errors';
+
+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 });
+  }
+}
+
+export 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;
+}

package/src/metric-registry.ts

@@ -0,0 +1,151 @@
+// Single responsibility: the instrument registry — one declaration per metric name, its shape
+// refused at declaration (bounds, ceiling, a conflicting redeclaration) rather than at the first
+// recording. `metric-series.ts` stores points under an instrument; `metrics.ts` is the public seam.
+
+import { MetricCardinalityError } from './metric-errors';
+import { assertMetricName, MetricNameInvalidError } from './metric-names';
+import type {
+  GaugeOptions,
+  HistogramOptions,
+  MetricAttributes,
+  MetricDescriptor,
+  MetricKind,
+} from './metrics-types';
+
+/**
+ * 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;
+
+/** 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 interface Series {
+  readonly attributes: MetricAttributes;
+  value: number;
+  count: number;
+  min: number;
+  max: number;
+  buckets: number[];
+}
+
+export 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;
+}
+
+export const instruments = new Map<string, Instrument>();
+
+/**
+ * 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 },
+  });
+}
+
+export function declare(
+  name: string,
+  kind: MetricKind,
+  options: GaugeOptions & HistogramOptions,
+): Instrument {
+  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]);

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/nearest-name.ts

@@ -27,7 +27,16 @@ const distance = (a: string, b: string): number => {
 const MAX_EDITS = 3;
 
 /**
- * The nearest candidate within `MAX_EDITS`, or `undefined` when nothing is close enough. Ties keep
+ * The cutoff for one pair: `MAX_EDITS`, but never as many edits as the longer name has
+ * characters. A fixed 3 is a typo in `migrate` and a different word in `db` — replacing ALL of a
+ * one- or two-letter input costs at most its length, so `nearestName('a', ['db', 'gen'])`
+ * answered `db` with nothing typed in common.
+ */
+const cutoff = (input: string, candidate: string): number =>
+  Math.min(MAX_EDITS, Math.max(input.length, candidate.length) - 1);
+
+/**
+ * The nearest candidate within its cutoff, or `undefined` when nothing is close enough. Ties keep
  * the FIRST candidate, which is the order the caller declared them in — `definePermissions([...])`
  * and a `CommandSpec` list are both authored orders, and a stable answer is what lets a test pin one.
  */
@@ -36,7 +45,7 @@ export const nearestName = (input: string, candidates: readonly string[]): strin
   let bestScore = MAX_EDITS + 1;
   for (const candidate of candidates) {
     const score = distance(input, candidate);
-    if (score < bestScore) {
+    if (score < bestScore && score <= cutoff(input, candidate)) {
       best = candidate;
       bestScore = score;
     }

package/src/otlp-metric-exporter.ts

@@ -118,7 +118,7 @@ export interface OtlpMetricExporter extends MetricExporter {
  */
 export function otlpMetricExporter(options: OtlpMetricExporterOptions = {}): OtlpMetricExporter {
   const url = otlpEndpoint('metrics', options.endpoint);
-  const headers = otlpHeaders(options.headers);
+  const headers = otlpHeaders(options.headers, process.env, 'metrics');
   const timeoutMs = assertFiniteOtlpBound('timeoutMs', options.timeoutMs ?? 10_000);
   const send = options.fetch ?? globalThis.fetch;
   let startedAtMs = options.startedAtMs;

package/src/otlp-span-exporter.ts

@@ -126,7 +126,7 @@ export interface OtlpSpanExporter extends SpanExporter {
  */
 export function otlpSpanExporter(options: OtlpSpanExporterOptions = {}): OtlpSpanExporter {
   const url = otlpEndpoint('traces', options.endpoint);
-  const headers = otlpHeaders(options.headers);
+  const headers = otlpHeaders(options.headers, process.env, 'traces');
   const maxBatchSize = assertFiniteOtlpBound('maxBatchSize', options.maxBatchSize ?? 512);
   const maxQueueSize = assertFiniteOtlpBound('maxQueueSize', options.maxQueueSize ?? 2048);
   const timeoutMs = assertFiniteOtlpBound('timeoutMs', options.timeoutMs ?? 10_000);