@ultimat3/core 24.0.0 → 25.0.0

package/src/lifecycle.ts

@@ -5,98 +5,45 @@
 import { type Clock, systemClock } from './clock';
 import type { ReadinessMode } from './config-health';
 import { assertReadinessMode } from './config-health';
+import { DRAIN_DEADLINE_DEFAULT_MS } from './drain-deadline';
 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 { ReadinessCheck, ReadinessStatus } from './lifecycle-readiness';
+import type { ReadinessStatus } from './lifecycle-readiness';
+import {
+  clearReadinessChecks,
+  readinessCheckCount,
+  runReadinessChecks,
+} from './lifecycle-readiness';
+import type {
+  HealthPayload,
+  HealthReport,
+  HealthState,
+  LifecycleOptions,
+  OnShutdownOptions,
+  ShutdownHook,
+  ShutdownPhase,
+  ShutdownReason,
+} from './lifecycle-types';
 import { type LogFields, type Logger, logger as rootLogger } from './logger';
 
-export type HealthState = 'starting' | 'ready' | 'draining' | 'stopped';
-
-/** Ordered. `accept` runs first, `close` last. */
-export type ShutdownPhase = 'accept' | 'inflight' | 'close';
-
-export const SHUTDOWN_PHASES: readonly ShutdownPhase[] = ['accept', 'inflight', 'close'];
-
-/** Signals Ultimate reacts to. Narrower than `NodeJS.Signals` on purpose. */
-export type ProcessSignal = 'SIGTERM' | 'SIGINT' | 'SIGHUP' | 'SIGQUIT';
-
-export interface ShutdownReason {
-  readonly signal: string;
-  /**
-   * Real monotonic ms (`systemClock`) after which hooks are abandoned — deliberately NOT the
-   * injected clock. The budget this bounds is `terminationGracePeriodSeconds`, counted by the
-   * kubelet in real seconds, so a frozen clock must be unable to extend it: read off `clock` a
-   * test that advanced an hour of fake time handed the drain a 16-minute grace period, while
-   * `waitForIdle` went on sleeping on a real `setTimeout`. `clock` still owns `uptimeMs`.
-   */
-  readonly deadlineAt: number;
-}
-
-export type ShutdownHook = (reason: ShutdownReason) => void | Promise<void>;
-
-export interface OnShutdownOptions {
-  readonly phase?: ShutdownPhase | undefined;
-}
-
-export interface LifecycleOptions {
-  /**
-   * The whole drain's budget — the in-flight wait AND every hook, in every phase. 25s by default,
-   * and **enforced whether or not an app sets it**: `ShutdownReason.deadlineAt` was always computed
-   * and handed to every hook, so the deadline was declared by the design and only the enforcement
-   * was missing. No hook reads `deadlineAt`, which is why it has to be imposed here.
-   *
-   * The lever is a LARGER value, not the absence of one: a `worker` holding a 10-minute job wants
-   * `configureLifecycle({ deadlineMs: 600_000 })` and a `terminationGracePeriodSeconds` at least as
-   * large. Left at 25s it is abandoned and the process exits clean — the row's visibility lease
-   * lapses and another worker re-claims it, which is what at-least-once already promises. The
-   * alternative is not "the job finishes": it is the same duplicate, delivered by SIGKILL at the
-   * kubelet's grace period, with no log line naming what overran.
-   *
-   * 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;
-  /** What a failing check does to `/readyz` — see `ReadinessMode`. Default `'dependencies'`. */
-  readonly readiness?: ReadinessMode | undefined;
-  readonly clock?: Clock | undefined;
-  readonly logger?: Logger | undefined;
-}
-
-export interface HealthReport {
-  readonly state: HealthState;
-  readonly ready: boolean;
-  readonly uptimeMs: number;
-  readonly inflight: number;
-  readonly buildId: string;
-  /** Named, because "alert on check failures BY CHECK NAME" is not writable against a boolean. */
-  readonly checks: Readonly<Record<string, ReadinessStatus>>;
-  /**
-   * How many checks are registered. `checks: {}` reads identically for "every check passed" and
-   * "nobody registered one", and only the second is a `/readyz` that means no more than "the
-   * socket is bound" — which is what the chart's and compose's healthchecks route traffic on.
-   * Reported rather than enforced: an empty registry is still ready, so a role that genuinely has
-   * no dependency does not have to invent a check to boot.
-   */
-  readonly registered: number;
-}
-
-export interface HealthPayload {
-  readonly ok: boolean;
-  /** The status code the HTTP layer should return. Core stays HTTP-free; this is just data. */
-  readonly status: number;
-  readonly body: HealthReport;
-}
+// The data model and the readiness registry are modules of their own; every name stays exported
+// from here, so nothing that imports a lifecycle type or the check registry learns a second path.
+export { readinessCheckCount, registerReadinessCheck } from './lifecycle-readiness';
+export type {
+  HealthPayload,
+  HealthReport,
+  HealthState,
+  LifecycleOptions,
+  OnShutdownOptions,
+  ProcessSignal,
+  ShutdownHook,
+  ShutdownPhase,
+  ShutdownReason,
+} from './lifecycle-types';
+export { SHUTDOWN_PHASES } from './lifecycle-types';
 
 interface Registration {
   readonly name: string;
@@ -104,7 +51,8 @@ interface Registration {
   readonly hook: ShutdownHook;
 }
 
-const DEFAULT_DEADLINE_MS = 25_000;
+/** `drain.deadlineMs`'s default, owned by `drain-deadline.ts` so the config and this agree. */
+const DEFAULT_DEADLINE_MS = DRAIN_DEADLINE_DEFAULT_MS;
 
 let deadlineMs = DEFAULT_DEADLINE_MS;
 /** `undefined` means "the environment's default", read when a drain starts, not at import. */
@@ -120,15 +68,13 @@ let lifetime = 0;
 let registrations: Registration[] = [];
 let drainPromise: Promise<void> | undefined;
 let idleWaiters: (() => void)[] = [];
-const readiness = new Map<string, ReadinessCheck>();
 
 export function configureLifecycle(options: LifecycleOptions): void {
   // Screened above the write, never beside the arithmetic: `Math.max(0, deadlineAt - monotonic())`
   // PROPAGATES a NaN into `setTimeout(fn, NaN)`, i.e. 0 — measured, one in-flight operation dropped
   // and a 300ms close hook ABANDONED 111ms into a 25s budget, while `X_SHUTDOWN_TIMEOUT` rendered
   // `NaNms` and told the operator to RAISE a budget that was never a number. `min: 0` because 0 is
-  // a real budget — drain now, no grace — and `@ultimat3/http`'s `drainTimeoutMs` accepts 0 and
-  // hands it straight here, so a floor of 1 would refuse at boot what that package declares.
+  // a real budget — drain now, no grace — and `drain.deadlineMs` reaches here unchanged.
   if (options.deadlineMs !== undefined) {
     deadlineMs = finiteCount('configureLifecycle', 'deadlineMs', options.deadlineMs, 0);
   }
@@ -174,30 +120,6 @@ export function markReady(): void {
   if (state === 'starting') state = 'ready';
 }
 
-/**
- * Register a named readiness check. Returns its unregister — the same shape as `onShutdown`, and
- * owned by whoever can be started twice, for the same reason.
- */
-export function registerReadinessCheck(name: string, check: ReadinessCheck): () => void {
-  if (readiness.has(name)) {
-    throw new UltimateError({
-      code: 'X_READINESS_CHECK_DUPLICATE',
-      cause: `a readiness check named "${name}" is already registered (have: ${[...readiness.keys()].join(', ')})`,
-      fix: `name the second check for what it actually probes, e.g. registerReadinessCheck('${name}-replica', check) — or hold the unregister the first registration returned and call it first`,
-      meta: { name },
-    });
-  }
-  readiness.set(name, check);
-  return () => {
-    if (readiness.get(name) === check) readiness.delete(name);
-  };
-}
-
-/** Test-only: registered checks. A count that climbs across a start/stop cycle is a leak. */
-export function readinessCheckCount(): number {
-  return readiness.size;
-}
-
 /**
  * Every line this file emits, and the only way it emits one. `log` is an injection seam
  * (`configureLifecycle({ logger })`), so an app's `Logger` decides whether a log call can throw —
@@ -226,24 +148,13 @@ function report(level: 'info' | 'warn' | 'error', message: string, fields: LogFi
 }
 
 /**
- * Every check, run now, by name. A check that throws is `failing` — never an unhandled error.
- *
- * Built through `Object.fromEntries`, never by assigning `results[name]`: assignment to the one
- * name `__proto__` sets the PROTOTYPE instead of adding a key, so that check vanished from the
- * report, `ready` was computed over an empty object — vacuously true — and a failing check
- * answered 200. `fromEntries` defines own properties and has no such name.
+ * Every check, run now, by name. A check that throws is `failing` — never an unhandled error —
+ * and is reported through `report`, so an injected logger that throws cannot replace the answer.
  */
 export function readinessChecks(): Readonly<Record<string, ReadinessStatus>> {
-  const results: [string, ReadinessStatus][] = [];
-  for (const [name, check] of readiness) {
-    try {
-      results.push([name, check() ? 'ok' : 'failing']);
-    } catch (thrown) {
-      results.push([name, 'failing']);
-      report('warn', 'readiness check threw', { check: name, error: thrown });
-    }
-  }
-  return Object.fromEntries(results);
+  return runReadinessChecks((name, thrown) => {
+    report('warn', 'readiness check threw', { check: name, error: thrown });
+  });
 }
 
 export function inflightCount(): number {
@@ -369,7 +280,7 @@ async function runPhase(phase: ShutdownPhase, reason: ShutdownReason): Promise<v
       report('warn', 'X_SHUTDOWN_TIMEOUT', {
         code: 'X_SHUTDOWN_TIMEOUT',
         cause: `the "${registration.name}" shutdown hook (phase: ${phase}) was still running at the ${deadlineMs}ms drain deadline and has been ABANDONED — the process exits without it, so anything it had in flight may be incomplete`,
-        fix: `raise the budget past the work this hook does — configureLifecycle({ deadlineMs: 600_000 }) for a 10-minute job — and set terminationGracePeriodSeconds to at least as many seconds, or make the "${registration.name}" hook return once it has stopped accepting work rather than once it has finished`,
+        fix: `raise the budget past the work this hook does — set drain: { deadlineMs: 600_000 } in app.config.ts for a 10-minute job (configureLifecycle({ deadlineMs: 600_000 }) outside a framework boot) — and give the platform's kill timer at least as many seconds (x deploy --method helm sizes the chart's from it), or make the "${registration.name}" hook return once it has stopped accepting work rather than once it has finished`,
         hook: registration.name,
         phase,
       });
@@ -401,7 +312,7 @@ async function runDrain(signal: string): Promise<void> {
       report('warn', 'X_SHUTDOWN_TIMEOUT', {
         code: 'X_SHUTDOWN_TIMEOUT',
         cause: `${inflight} in-flight operations still running after ${deadlineMs}ms`,
-        fix: 'raise the budget past the slowest handler — configureLifecycle({ deadlineMs: 600_000 }) for a 10-minute one — and set terminationGracePeriodSeconds to at least as many seconds, or shorten the handler',
+        fix: 'raise the budget past the slowest handler — set drain: { deadlineMs: 600_000 } in app.config.ts for a 10-minute one (configureLifecycle({ deadlineMs: 600_000 }) outside a framework boot) — and give the platform kill timer at least as many seconds, or shorten the handler',
       });
     }
 
@@ -458,7 +369,7 @@ export function healthReport(mode: ReadinessMode = readinessMode): HealthReport
     inflight,
     buildId: process.env['BUILD_ID'] ?? 'dev',
     checks,
-    registered: readiness.size,
+    registered: readinessCheckCount(),
   };
 }
 
@@ -496,5 +407,5 @@ export function resetLifecycle(): void {
   registrations = [];
   drainPromise = undefined;
   idleWaiters = [];
-  readiness.clear();
+  clearReadinessChecks();
 }

package/src/locale-direction.ts

@@ -2,7 +2,7 @@
 // requests, which is why it is tier 0 rather than `@ultimat3/i18n`'s: `@ultimat3/ui`'s provider
 // reflects `dir` onto `<html>` from the locale it was handed, and reaching the i18n barrel for
 // that one function put the whole framework catalog into every browser chunk with a `UiProvider`
-// in it (issue #490). i18n re-exports these under the same names, so no caller moved.
+// in it (issue #490). Import them from `@ultimat3/core`: i18n's re-export was deleted in 25.0.0.
 
 export type Direction = 'ltr' | 'rtl';
 

package/src/logger.ts

@@ -112,6 +112,11 @@ const redactedKeys = new Set<string>([
  *   service URLs that carry `user:password@` (`databaseUrl`, `REDIS_URL`). A bare `url` does not.
  * - the one-time codes by name. Never a `code` suffix: that is the error contract's own field.
  * - a stored hash of any of them: it is what an offline guess runs against.
+ * - a bearer by its kind as the LAST word: `credentials`, `jwt`, `bearer`, `cookies`, a session's
+ *   id or key (`sessionId` IS the session), and key material by encoding (`privateKeyPem`).
+ *   `credentialId`, `jwtIssuer`, `cookieName`, `privateKeyId` name a credential, not hold one.
+ * - card verification codes (`cvv`, `cvc2`) as a suffix, and a `pin` only as the WHOLE word
+ *   behind an owner qualifier — three letters inside `spinner`, `shipping` or `pinned` are not one.
  *
  * Built from constant alternatives with no nested quantifier, so there is no input it backtracks on.
  */
@@ -127,6 +132,10 @@ const CREDENTIAL_NAME = new RegExp(
     '(?:database|db|redis|replication|nats|smtp|amqp|mongo)ur[li]s?$',
     '^totp$|totpcode$|otp$|otpcode$',
     '(?:recovery|backup|mfa)codes?(?:hash(?:es)?)?$',
+    'credentials?$|jwts?$|bearer$|cookies?$|session(?:id|key)s?$',
+    'privatekey(?:pem|der|jwk)$',
+    'cv[vc]2?$',
+    '^(?:card|atm|security|account|user|wallet)?pin(?:code|number)?(?:hash(?:es)?)?$',
   ].join('|'),
 );
 
@@ -344,7 +353,7 @@ function timestamp(clock: Clock): string {
  * `LOG_LEVEL`, and the default where there is no environment to read it from.
  *
  * A BROWSER has no `process` binding at all, and this read runs at MODULE INIT — `logger` at the
- * foot of this file is `createLogger()` evaluated when the module is. Measured on ai-maxxing's
+ * foot of this file is `structuredLogger()` evaluated when the module is. Measured on ai-maxxing's
  * session console island: `@ultimat3/realtime`'s `channel.ts` calls `logger.warn`, so the shaker
  * keeps `logger`, and the island's chunk died on `ReferenceError: process is not defined` before a
  * line of the app's own code ran — the wrapper rendered `data-x-failed="process is not defined"`
@@ -364,7 +373,7 @@ function envLevel(): LogLevel {
   const raw = typeof process === 'undefined' ? undefined : process.env['LOG_LEVEL'];
   // Unset and EMPTY are the same answer — `LOG_LEVEL=` is how a compose file spells "not set".
   if (raw === undefined || raw === '') return 'info';
-  // REFUSED, as `resolveLevel` refuses the same value from `createLogger({ level })`. It fell back
+  // REFUSED, as `resolveLevel` refuses the same value from `structuredLogger({ level })`. It fell back
   // to `info` in silence, so `LOG_LEVEL=verbose` — or `DEBUG`, the spelling half the ecosystem
   // uses — gave an operator who asked for MORE lines fewer, and nothing said the variable was the
   // reason. This runs at module init, so the refusal is the first thing the process prints.
@@ -392,7 +401,7 @@ function resolveLevel(declared: LogLevel): LogLevel {
     // level that arrived from a config file can be either — the refusal must not be replaced by
     // a `TypeError` from building its own message.
     `${renderCauseValue(declared)} is not a log level`,
-    `pass one of ${LOG_LEVELS.join(', ')} to createLogger({ level })`,
+    `pass one of ${LOG_LEVELS.join(', ')} to structuredLogger({ level })`,
   );
   return declared;
 }
@@ -413,7 +422,7 @@ function unreserved(fields: Record<string, unknown>): Record<string, unknown> {
   return out;
 }
 
-export function createLogger(options?: LoggerOptions): Logger {
+export function structuredLogger(options?: LoggerOptions): Logger {
   const level = options?.level === undefined ? envLevel() : resolveLevel(options.level);
   const bound = options?.fields ?? {};
   const clock = options?.clock ?? systemClock;
@@ -444,10 +453,10 @@ export function createLogger(options?: LoggerOptions): Logger {
     warn: (message, fields) => emit('warn', message, fields),
     error: (message, fields) => emit('error', message, fields),
     fatal: (message, fields) => emit('fatal', message, fields),
-    child: (fields) => createLogger({ level, clock, writer, fields: { ...bound, ...fields } }),
-    withLevel: (next) => createLogger({ level: next, clock, writer, fields: bound }),
+    child: (fields) => structuredLogger({ level, clock, writer, fields: { ...bound, ...fields } }),
+    withLevel: (next) => structuredLogger({ level: next, clock, writer, fields: bound }),
   };
 }
 
 /** The process-wide logger. Prefer `ctx.logger` inside a request — it carries the ids. */
-export const logger: Logger = createLogger();
+export const logger: Logger = structuredLogger();

package/src/mcp-exposure.ts

@@ -1,14 +1,71 @@
-// The one answer to "did this primitive opt into being an MCP tool?" — a literal `expose: true`.
-// Core owns it because its readers span tiers 3-5 — `action`, `query`, `mcp`, `ai`, `manifest` —
-// and this is the only tier all of them reach, the same reason `timing-safe-equal.ts` lives here.
+// The ONE declaration of a primitive's `mcp` block, and the one answer to "did this primitive opt
+// into being an MCP tool?" — a literal `expose: true`. Core owns both because the block's readers
+// span tiers 3-5 — `action`, `query`, `mcp`, `ai`, `manifest` — and this is the only tier all of
+// them reach. `ActionMcp`, `QueryMcp` and `McpExposure` each restated the block until 25.0.0.
 
 /**
- * The `mcp` block, read structurally. Each package keeps its own richer declaration —
- * `ActionMcp` carries `visibleTo`, `@ultimat3/mcp`'s `McpExposure` carries `name` — and hands it
- * here; restating the one field they share binds this to none of them.
+ * MCP's four tool hints, as the spec (2025-06-18) spells them. Hints for a client's confirmation
+ * UI — the primitive's `policy` decides every call whatever they say.
+ */
+export interface McpAnnotationHints {
+  readonly readOnlyHint?: boolean;
+  readonly destructiveHint?: boolean;
+  readonly idempotentHint?: boolean;
+  readonly openWorldHint?: boolean;
+}
+
+/** One comparison a list filter accepts. A filter key is `<field><op>`: `status_eq`. */
+export type McpListFilterOp = '_eq' | '_in' | '_gt' | '_lt' | '_cont';
+
+/**
+ * The list whitelist an MCP meta surface composes over: `filters` field → operators, sortable
+ * `sort` fields, pickable `fields`, `maxLimit`. Flat keys: the query's own `input` declares
+ * `status_eq`, `sort`, `fields`, `cursor`, `limit` and implements them; `manage_resource` refuses
+ * anything outside the whitelist before it runs.
+ */
+export interface McpListParams {
+  readonly filters?: Readonly<Record<string, readonly McpListFilterOp[]>>;
+  readonly sort?: readonly string[];
+  readonly fields?: readonly string[];
+  /** Ceiling for `limit`. `@ultimat3/mcp`'s `DEFAULT_LIST_MAX_LIMIT` when absent. */
+  readonly maxLimit?: number;
+}
+
+/**
+ * `mcp: { … }` on an `action`, a `mutator`, a `query` or an `llm()`/`agent()` factory — the block
+ * an author writes and `@ultimat3/mcp`'s `toolFrom` reads. An action's view omits `listParams`
+ * (it has no list to compose); every other field means the same on every primitive.
  */
 export interface McpExposureDeclaration {
-  readonly expose?: boolean | undefined;
+  /** Opt-in: only a literal `true` makes the primitive a tool. Silence exposes nothing. */
+  readonly expose: boolean;
+  /**
+   * Contract text, NOT UI text — deliberately outside `t()`. It becomes the OpenAPI operation
+   * `summary`, and `buildOpenApi`'s bytes are what `x verify` diffs for contract drift. Resolving
+   * it through the ambient, request-scoped translator would make `openapi.json` depend on
+   * whichever locale was active when it was generated. Two ways to describe one tool is the
+   * drift axiom 1 rejects, so there is no localised twin here.
+   */
+  readonly description?: string;
+  /**
+   * Roles that may SEE the projected tool. A CATALOG audience, never an authz rule — the `policy`
+   * still decides every call. Fail-closed where it lands: a caller whose role is not named,
+   * including one with no role at all, gets the answer an ABSENT tool gets, never `Forbidden`,
+   * which would confirm the tool exists. A plain role list, never a predicate: a declared fact
+   * stays static and serialisable. Omitted means every caller may enumerate it.
+   */
+  readonly visibleTo?: readonly string[];
+  /** The tool's display name in an MCP client's UI. Contract text, like `description`. */
+  readonly title?: string;
+  /**
+   * Overrides of the hints `@ultimat3/mcp` derives, key by key: an action derives
+   * `readOnlyHint: false`, `destructiveHint: true` and `idempotentHint` from `idempotent`; a query
+   * `readOnlyHint: true`. `annotations: { destructiveHint: false }` for a write that destroys
+   * nothing, `openWorldHint: true` for one that reaches outside the app.
+   */
+  readonly annotations?: McpAnnotationHints;
+  /** A list query's whitelist, carried to the tool for the meta surface. Never an action's. */
+  readonly listParams?: McpListParams;
 }
 
 /**
@@ -17,6 +74,9 @@ export interface McpExposureDeclaration {
  * handed to every agent that can reach the surface — and writing an action is not a request to
  * hand one out.
  *
+ * Read through `Partial<Pick<…>>` because a reader holding only a descriptor (`manifest`'s
+ * diff, a hand-built test primitive) may carry no `expose` at all, and that is the same "no".
+ *
  * Six readers decided it three ways until 2026-08: `=== true` where a tool is actually built,
  * `!== false` in the OpenAPI hint and `?? true` in the manifest fact. So an action with no `mcp`
  * block was published as a tool by the contract and refused by every surface that could have
@@ -27,6 +87,8 @@ export interface McpExposureDeclaration {
  * `expose: false` withdraws a tool. That surface says so in `mcp-tools.ts` and in
  * `wiki/Admin-Dashboard.md`. Nothing else may grow a second default.
  */
-export function isMcpExposed(declared: McpExposureDeclaration | undefined): boolean {
+export function isMcpExposed(
+  declared: Partial<Pick<McpExposureDeclaration, 'expose'>> | undefined,
+): boolean {
   return declared?.expose === true;
 }

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]);