@ultimat3/core 16.0.0 → 18.0.0

package/src/otlp.ts

@@ -2,6 +2,7 @@
 // an operator already sets, header parsing, the OTLP/JSON value encoding, and one POST that never
 // throws. A serialisation, not a vendor (axiom 7), exactly as `metrics-text.ts` is to Prometheus.
 
+import { assert } from './assert';
 import { renderThrowable } from './error-render';
 import { type CodedErrorInit, UltimateError } from './errors';
 import { logger } from './logger';
@@ -111,6 +112,29 @@ export function tryOtlpEndpoint(
 }
 
 /** The endpoint, or a coded error naming the variable to set. */
+/**
+ * A batch size, a queue bound or a millisecond budget, screened where the exporter is CONSTRUCTED.
+ *
+ * These arrive as `Number(process.env.OTEL_…)` as often as literals, and `NaN` is not nullish so
+ * `??` keeps it. What follows is never a wrong number: `setInterval(fn, NaN)` runs at 1ms in this
+ * Bun (measured, with a `TimeoutNaNWarning`), so the collector is POSTed a thousand times a
+ * second; `AbortSignal.timeout(NaN)` throws, and `postOtlp` swallows it, so every export fails
+ * with one warn line and the traces simply stop; and `queue.length >= NaN` is false, so a bound
+ * that exists to be a bound stops being one. `X_INVARIANT` rather than a fourth `X_OTLP_*` code:
+ * the three here name the endpoint, the headers and the protocol, and this is none of those.
+ *
+ * The `Finite` in the name is load-bearing: `bun run finite-bounds` recognises a repair by the
+ * shape of the CALL, so a screen named for its subject alone is invisible to the ratchet.
+ */
+export function assertFiniteOtlpBound(option: string, value: number): number {
+  assert(
+    Number.isSafeInteger(value) && value >= 1,
+    `otlp exporter option ${option} is ${String(value)}; it must be a whole number of at least 1 — a comparison against a non-finite bound is false for every value, and a timer given one runs at 1ms`,
+    `pass a whole number for ${option}, and parse an environment value before you pass it: Number(process.env.OTEL_BSP_SCHEDULE_DELAY ?? '') is NaN when the variable is unset`,
+  );
+  return value;
+}
+
 export function otlpEndpoint(
   signal: OtlpSignal,
   explicit?: string | undefined,

package/src/read-capped.ts

@@ -4,6 +4,8 @@
 // `@ultimat3/mcp` (tier 4) serves a bare `Request` that never passes through http's pipeline —
 // `await request.json()` there was governed only by Bun's 128 MiB default.
 
+import { assert } from './assert';
+
 /** What a body read produced: the bytes, or the running total at the moment it went over. */
 export type CappedBody = { readonly bytes: Uint8Array } | { readonly over: number };
 
@@ -17,6 +19,18 @@ export const readWithinLimit = async (
   body: ReadableStream<Uint8Array> | null,
   limit: number,
 ): Promise<CappedBody> => {
+  // The cap is this function's whole contract, so it is screened here and not by each caller in
+  // turn. `total > NaN` is false for every chunk, so a non-finite limit does not RAISE the ceiling
+  // — it removes it, and the payload the caller was promised would never be held in full is held
+  // in full. Both callers reach it from configuration (`@ultimat3/http`'s `bodyLimitBytes`,
+  // `@ultimat3/mcp`'s own), and `Number(process.env.…)` on an unset variable is `NaN`. Before the
+  // body is touched: a cap this wrong is the caller's bug, not the peer's, and cancelling their
+  // stream over it would be answering the wrong party.
+  assert(
+    Number.isSafeInteger(limit) && limit >= 0,
+    `readWithinLimit was given a limit of ${String(limit)}; a byte cap is a whole number of zero or more, and every comparison against a non-finite one is false, so the read is unbounded rather than capped`,
+    "pass a whole number of bytes — readWithinLimit(request.body, 1_048_576) — and parse an environment value before you pass it: Number(process.env.BODY_LIMIT_BYTES ?? '') is NaN when the variable is unset",
+  );
   if (body === null) return { bytes: new Uint8Array(0) };
   const reader = body.getReader();
   const chunks: Uint8Array[] = [];
@@ -26,15 +40,19 @@ export const readWithinLimit = async (
       const { done, value } = await reader.read();
       if (done) break;
       total += value.byteLength;
-      if (total > limit) {
-        // Cancelled rather than drained: the peer is told to stop sending, and nothing past the
-        // cap is ever held. Draining is how a rejected request still costs its full transfer.
-        await reader.cancel();
-        return { over: total };
-      }
+      // Cancelled rather than drained, in the `finally` below: the peer is told to stop sending,
+      // and nothing past the cap is ever held. Draining is how a rejected request still costs its
+      // full transfer.
+      if (total > limit) return { over: total };
       chunks.push(value);
     }
   } finally {
+    // Cancel rather than merely release — `@ultimat3/storage`'s `readWithin` is the same bounded
+    // read and states the same rule: a refused body must stop arriving, not keep filling a socket
+    // buffer nobody will read. Swallowed, because a cancellation that fails on the way out must
+    // not replace the answer this function computed: an unguarded `cancel()` turned the 413 into
+    // whatever the stream threw. A completed stream answers it as a no-op.
+    await reader.cancel().catch(() => undefined);
     reader.releaseLock();
   }
   const bytes = new Uint8Array(total);

package/src/sampler.ts

@@ -9,9 +9,20 @@ import type { SpanAttributes, SpanContext } from './telemetry';
  * The seam. `parent` is the inbound span context when there is one — an upstream that decided
  * "not sampled" has said so in `parent.traceFlags`, and a sampler that ignores it splits one
  * distributed trace into a sampled half and an unsampled half, which is worse than either.
+ *
+ * `traceId` is the id of the span being CREATED — the parent's carried forward, or the one this
+ * process just minted for a root. It is an argument of its own for the same reason OTel makes it
+ * one: a trace-id-hashing sampler has to answer for a ROOT too, where there is no parent to read
+ * the id off, and every span of one trace has to reach the same answer or the collector is handed
+ * orphans. An implementation that ignores it (`always_on`, `parentbased_*`) simply omits it.
  */
 export interface Sampler {
-  shouldSample(name: string, parent: SpanContext | undefined, attributes: SpanAttributes): boolean;
+  shouldSample(
+    name: string,
+    parent: SpanContext | undefined,
+    attributes: SpanAttributes,
+    traceId: string,
+  ): boolean;
 }
 
 export const OTEL_SAMPLER_KEY = 'OTEL_TRACES_SAMPLER';
@@ -55,13 +66,38 @@ export function parentBasedRatioSampler(
   };
 }
 
-/** `always_off` / `always_on` without the parent-based prefix ignore the inbound decision. */
+/** The 64-bit space OTel's `TraceIdRatioBased` compares the low 8 bytes of a trace id against. */
+const TRACE_ID_SPACE = 2 ** 64;
+
+const TRACE_ID_HEX = /^[0-9a-f]{32}$/;
+
+/**
+ * OTel's `TraceIdRatioBased`: the LOW 8 bytes of the trace id as a big-endian unsigned integer,
+ * against `ratio` of the 2^64 space. Answers `undefined` for anything that is not a 32-hex trace
+ * id, so the caller decides what to do with an id no hash can read rather than this silently
+ * sampling or silently dropping it.
+ */
+function traceIdSampled(traceId: string, ratio: number): boolean | undefined {
+  if (!TRACE_ID_HEX.test(traceId)) return undefined;
+  return BigInt(`0x${traceId.slice(16)}`) < BigInt(Math.floor(ratio * TRACE_ID_SPACE));
+}
+
+/**
+ * `traceidratio` — the OTel spelling that ignores the inbound decision and hashes the TRACE ID.
+ *
+ * The hash is the whole of it, and a roll is not a substitute: `startSpan` asks the sampler for
+ * every span, root and child alike, so a `random()` here re-decided per span and one trace left
+ * as a sampled half and an unsampled half — measured at 0.5, an unexported root with eight of its
+ * twenty children at the collector. Hashing the id makes the answer a function of the trace, which
+ * is what the name of this sampler means and what lets a second SERVICE agree with us unprompted.
+ * `random` survives only for an id no hash can read, and stays injectable so that path is a test.
+ */
 export function ratioSampler(ratio: number, random: () => number = Math.random): Sampler {
   return {
-    shouldSample(): boolean {
+    shouldSample(_name, _parent, _attributes, traceId): boolean {
       if (ratio >= 1) return true;
       if (ratio <= 0) return false;
-      return random() < ratio;
+      return traceIdSampled(traceId, ratio) ?? random() < ratio;
     },
   };
 }

package/src/schema-error-codes.ts

@@ -1,32 +1,33 @@
 // Single responsibility: register `@ultimat3/schema`'s error codes so their titles render for any
 // process that imports `@ultimat3/core` — not just the CLI. `@ultimat3/schema` is tier 0 alongside
-// this package, so it cannot call `registerErrorCodes()` itself (that would mean importing core,
-// a same-tier import) and this package cannot import schema to read its declarations back (same
-// reason, the other direction). The codes below are a deliberate, tested duplicate of
-// `SCHEMA_ERROR_CODES` in `packages/schema/src/errors.ts` — `schema-error-codes-pin.test.ts`, in a
-// package that may legally import both (`@ultimat3/cli`), asserts them equal so a title edited in
-// one place and not the other fails the build instead of quietly disagreeing at runtime.
+// this package and cannot call `registerErrorCodes()` itself: that would be `schema -> core`, an
+// import this package's own dependency-free promise forbids in that direction and always will.
+// The other direction is DECLARED (`core -> schema`, `scripts/lib/tiers.ts`), so the titles are
+// READ from schema rather than restated here.
+//
+// They were a hand-kept duplicate until 2026-08-27, held equal by `schema-error-codes-pin.test.ts`
+// in `@ultimat3/cli` — a tier-5 package pinning a tier-0 invariant, which nothing required to
+// exist. It is deleted with this change.
 
+import { SCHEMA_ERROR_CODES } from '@ultimat3/schema';
 import { registerErrorCodes } from './error-codes';
 import { registerErrorRetry } from './error-retry';
 
-/** Mirrors `SCHEMA_ERROR_CODES` in `packages/schema/src/errors.ts`. Keep the titles identical. */
-export const SCHEMA_ERROR_CODE_TITLES: Readonly<Record<string, string>> = Object.freeze({
-  X_VALIDATION_FAILED: 'value did not match its schema',
-  X_SCHEMA_UNSUPPORTED: 'the active schema provider cannot do this',
-  X_SCHEMA_DISCRIMINANT_INVALID: 'a discriminated union member can never be dispatched to',
-  X_SCHEMA_DEFAULT_UNSHAREABLE: 'a schema default cannot be copied per parse',
-});
+/**
+ * Schema's own declarations, projected to titles. Kept as an export because it is public API
+ * shipped since 1.0; it is now DERIVED and can no longer disagree with its source.
+ */
+export const SCHEMA_ERROR_CODE_TITLES: Readonly<Record<string, string>> = Object.freeze(
+  Object.fromEntries(
+    Object.entries(SCHEMA_ERROR_CODES).map(([code, declared]) => [code, declared.title]),
+  ),
+);
 
 // Registered here rather than in `error-codes.ts`'s `CORE_CODE_TITLES` because core does not own
 // these codes — `@ultimat3/schema` does — and `registerErrorCodes` is the one mechanism that
 // raises `X_ERROR_CODE_DUPLICATE` if a package that DOES own one of them ever tries to register it
-// too, which pins ownership even though the titles live in two files.
-registerErrorCodes(
-  Object.fromEntries(
-    Object.entries(SCHEMA_ERROR_CODE_TITLES).map(([code, title]) => [code, { title }]),
-  ),
-);
+// too, which pins ownership even though the registration happens here.
+registerErrorCodes(SCHEMA_ERROR_CODES);
 
 // And how each is RETRIED, here for the same tier reason the titles are here.
 //
@@ -41,9 +42,10 @@ registerErrorCodes(
 // `packages/scraping/src/cdp-target.ts` names the gap and says it cannot be closed from there.
 //
 // A value that does not match its schema does not match it on attempt five either.
-registerErrorRetry({
-  X_VALIDATION_FAILED: 'terminal',
-  X_SCHEMA_UNSUPPORTED: 'terminal',
-  X_SCHEMA_DISCRIMINANT_INVALID: 'terminal',
-  X_SCHEMA_DEFAULT_UNSHAREABLE: 'terminal',
-});
+//
+// DERIVED from the same set, so a code schema adds cannot arrive unclassified: the list was typed
+// out here and a fifth code would have been silently missing from it, which is precisely the
+// "unregistered reads as unclassified" failure the paragraph above describes.
+registerErrorRetry(
+  Object.fromEntries(Object.keys(SCHEMA_ERROR_CODES).map((code) => [code, 'terminal' as const])),
+);

package/src/telemetry.ts

@@ -201,10 +201,13 @@ export function startSpan(name: string, options?: StartSpanOptions): Span {
   // so one trace is sampled or not sampled as a whole. Before this, `traceFlags` was hardcoded to
   // 1 for a root and `end()` exported regardless, which made the bit a value the framework
   // forwarded and nobody obeyed.
+  // The id is resolved BEFORE the decision, because the decision may be a function of it: a
+  // `traceidratio` sampler hashes the trace id, and a root's id exists nowhere else to hash.
+  const traceId = parent?.traceId ?? newTraceId();
   const context: SpanContext = {
-    traceId: parent?.traceId ?? newTraceId(),
+    traceId,
     spanId: newSpanId(),
-    traceFlags: currentSampler().shouldSample(name, inbound, attributes) ? 1 : 0,
+    traceFlags: currentSampler().shouldSample(name, inbound, attributes, traceId) ? 1 : 0,
   };
   const events: SpanEvent[] = [];
   const startedAt = clock.now().getTime();

package/src/time-zone-name.ts

@@ -1,43 +1,14 @@
-// Single responsibility: is a string an IANA zone NAME? Tier 0's statement of the one rule
-// `@ultimat3/time` enforces everywhere above it — a zone is `Area/Location`, and `UTC` is the one
-// exception. It is stated twice because `core` is tier 0 and may not import `@ultimat3/time`;
-// `packages/time/src/zone-canonical.ts` is where the rule and its reasoning are written down.
+// Single responsibility: re-export `@ultimat3/schema`'s IANA zone-name predicate, so `app.config.ts`
+// and `t.timezone` judge a zone with ONE function.
+//
+// This file held a character-for-character copy of it until 2026-08-27 — `core` and `schema` are
+// both tier 0 and neither could import the other — kept equal by a 123-line pin test in
+// `@ultimat3/cli`, a tier-5 package pinning a tier-0 invariant that no rule required to exist.
+// `core -> schema` is now a declared edge (`scripts/lib/tiers.ts`), so the copy is gone.
+//
+// The rule itself, and why a bare `new Intl.DateTimeFormat(…)` probe is not it — ICU 78 resolves
+// `CET`, `EST`, `Japan`, `GMT` and `Zulu`, so `defaultTimeZone: 'CET'` passed validation at boot
+// and threw `X_TIMEZONE_INVALID` on the first `format` call (issue #257) — is written down in
+// `packages/schema/src/time-zone-name.ts` and in `packages/time/src/zone-canonical.ts`.
 
-/**
- * A LEADING sign is a fixed offset, which carries no DST rules. `Etc/GMT+2` keeps its `+`.
- *
- * Unobservable on ICU 78 — `+01:00` resolves to itself, so the slash rule below already refuses it,
- * and deleting this line changes no answer this package can currently produce. It stays because it
- * guards the runtime that folds an offset into `Etc/GMT-1`, which WOULD carry a slash, and because
- * `packages/time/src/zone-canonical.ts` carries the same line: two statements of one rule may not
- * differ, least of all in the half that is hard to test.
- */
-const NUMERIC_OFFSET = /^[+-]/;
-
-/**
- * Structural, and never delegated to `Intl` — the reasoning, and why a denylist is not the
- * alternative, is `packages/time/src/zone-canonical.ts`'s and is not re-derived here. What this
- * file enforces is that same rule for `app.config.ts`: an identifier is `Area/Location`, `UTC` is
- * the one legal exception, and a leading sign is an offset rather than a name.
- *
- * It exists because a bare `new Intl.DateTimeFormat(…)` probe was the second answer to that
- * question, and the two stopped agreeing: ICU 78 (Bun 1.4) resolves `CET`, `EST`, `Japan`, `GMT`,
- * `Zulu` and the whole `backward`/abbreviation family, so `defaultTimeZone: 'CET'` passed validation
- * at boot and threw `X_TIMEZONE_INVALID` on the first `format` call — a config file accepting a
- * value nothing downstream can use (issue #257).
- *
- * The judgement is made on the RESOLVED name, not the input, so a casing (`utc`) and a runtime that
- * folds an alias into its target (`Etc/UTC` → `UTC`) both answer correctly. No cache: this is read
- * once per process at config validation, never off a request header — a zone that arrives from a
- * caller goes through `@ultimat3/time`'s `canonicalTimeZone`, which is bounded and canonicalizing.
- */
-export function isIanaZoneName(value: string): boolean {
-  if (value === '' || NUMERIC_OFFSET.test(value)) return false;
-  try {
-    const resolved = new Intl.DateTimeFormat('en-US', { timeZone: value }).resolvedOptions()
-      .timeZone;
-    return resolved === 'UTC' || resolved.includes('/');
-  } catch {
-    return false;
-  }
-}
+export { isIanaZoneName } from '@ultimat3/schema';