@ultimat3/core 1.2.0 → 2.0.0

package/src/telemetry.ts

@@ -5,8 +5,10 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { type Clock, systemClock } from './clock';
 import { tryUseContext } from './context';
+import { renderThrowable } from './error-render';
 import { isUltimateError } from './errors';
-import { spanId as newSpanId, traceId as newTraceId } from './ids';
+import { isSpanId, isTraceId, spanId as newSpanId, traceId as newTraceId } from './ids';
+import { defaultSampler, resetDefaultSampler, type Sampler } from './sampler';
 
 export type SpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer';
 
@@ -87,6 +89,8 @@ export interface TelemetryOptions {
   readonly serviceName?: string | undefined;
   readonly serviceVersion?: string | undefined;
   readonly enabled?: boolean | undefined;
+  /** Defaults to `defaultSampler()`: honour the parent, else the ratio the env asks for. */
+  readonly sampler?: Sampler | undefined;
 }
 
 export const noopExporter: SpanExporter = Object.freeze({
@@ -100,7 +104,7 @@ export interface MemoryExporter extends SpanExporter {
   reset(): void;
 }
 
-/** For tests and for `x trace --json`. */
+/** For tests, and for reading back what a run traced with no collector on the box. */
 export function memoryExporter(): MemoryExporter {
   const spans: ReadableSpan[] = [];
   return {
@@ -119,12 +123,14 @@ const activeSpan = new AsyncLocalStorage<Span>();
 let exporter: SpanExporter = noopExporter;
 let clock: Clock = systemClock;
 let enabled = true;
+let sampler: Sampler | undefined;
 let resource: SpanResource = Object.freeze({ serviceName: 'ultimate', serviceVersion: '0.0.1' });
 
 export function configureTelemetry(options: TelemetryOptions): void {
   if (options.exporter !== undefined) exporter = options.exporter;
   if (options.clock !== undefined) clock = options.clock;
   if (options.enabled !== undefined) enabled = options.enabled;
+  if (options.sampler !== undefined) sampler = options.sampler;
   if (options.serviceName !== undefined || options.serviceVersion !== undefined) {
     resource = Object.freeze({
       serviceName: options.serviceName ?? resource.serviceName,
@@ -137,6 +143,13 @@ export function resetTelemetry(): void {
   exporter = noopExporter;
   clock = systemClock;
   enabled = true;
+  sampler = undefined;
+  resetDefaultSampler();
+}
+
+/** The sampler in force: whatever `configureTelemetry` was given, else the env's. */
+export function currentSampler(): Sampler {
+  return sampler ?? defaultSampler();
 }
 
 /**
@@ -162,12 +175,16 @@ export function currentSpanContext(): SpanContext | undefined {
 
 export function startSpan(name: string, options?: StartSpanOptions): Span {
   const parent = options?.parent ?? currentSpanContext();
+  const attributes: Record<string, AttributeValue> = { ...(options?.attributes ?? {}) };
+  // The bit is decided ONCE, here, and every child of this span inherits it through `parent` —
+  // 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.
   const context: SpanContext = {
     traceId: parent?.traceId ?? newTraceId(),
     spanId: newSpanId(),
-    traceFlags: parent?.traceFlags ?? 1,
+    traceFlags: currentSampler().shouldSample(name, parent, attributes) ? 1 : 0,
   };
-  const attributes: Record<string, AttributeValue> = { ...(options?.attributes ?? {}) };
   const events: SpanEvent[] = [];
   const startedAt = clock.now().getTime();
   const startedMono = clock.monotonic();
@@ -198,7 +215,12 @@ export function startSpan(name: string, options?: StartSpanOptions): Span {
     },
     recordError(error) {
       const code = isUltimateError(error) ? error.code : 'X_INTERNAL';
-      const message = error instanceof Error ? error.message : String(error);
+      // `renderThrowable`, never `error instanceof Error ? error.message : String(error)`: both
+      // halves are property reads on a value the framework did not build, and this runs inside
+      // `withSpan`'s catch — around `cache.invalidate`, `db.<verb>` and every HTTP and job span.
+      // A throw here substitutes the tracer's own TypeError for the caller's real failure and
+      // leaves the span it was annotating unended.
+      const message = renderThrowable(error);
       events.push({
         name: 'exception',
         at: clock.now().getTime(),
@@ -215,6 +237,10 @@ export function startSpan(name: string, options?: StartSpanOptions): Span {
       if (ended) return;
       ended = true;
       if (!enabled) return;
+      // The whole point of propagating a sampling bit is that somebody obeys it. A span still
+      // exists, still parents its children and still carries the decision onward in
+      // `traceparent`; it is simply not exported.
+      if ((context.traceFlags & 1) === 0) return;
       const endedAt = clock.now().getTime();
       const parentSpanId = parent === undefined || parent.spanId === '' ? undefined : parent.spanId;
       exporter.export({
@@ -272,8 +298,13 @@ export function withSpanContext<T>(context: SpanContext, name: string, fn: (span
 
 const TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
 
+/**
+ * Round-trips with `traceId()` / `spanId()` from `ids.ts` and with nothing else. A context whose
+ * `traceId` came from `uuid()` renders a 36-character dashed header here that `parseTraceparent`
+ * — and every OTLP collector — rejects, so mint the pair with those two generators.
+ */
 export function traceparent(context: SpanContext): string {
-  const flags = context.traceFlags.toString(16).padStart(2, '0');
+  const flags = (context.traceFlags & 0xff).toString(16).padStart(2, '0');
   return `00-${context.traceId}-${context.spanId}-${flags}`;
 }
 
@@ -281,11 +312,12 @@ export function parseTraceparent(header: string | null | undefined): SpanContext
   if (header === null || header === undefined) return undefined;
   const match = TRACEPARENT_RE.exec(header.trim());
   if (match === null) return undefined;
-  return {
-    traceId: match[1] as string,
-    spanId: match[2] as string,
-    traceFlags: Number.parseInt(match[3] as string, 16),
-  };
+  const traceId = match[1] as string;
+  const spanId = match[2] as string;
+  // `ids.ts` owns what a valid id is, so the all-zero rejection the spec requires lives in one
+  // place instead of being a second regex here that drifts from the generator's.
+  if (!isTraceId(traceId) || !isSpanId(spanId)) return undefined;
+  return { traceId, spanId, traceFlags: Number.parseInt(match[3] as string, 16) };
 }
 
 function isPromiseLike(value: unknown): value is PromiseLike<unknown> {

package/src/timing-safe-equal.ts

@@ -0,0 +1,18 @@
+// Single responsibility: a string comparison whose duration does not depend on where two secrets
+// first differ. `@ultimat3/auth` and `@ultimat3/storage` both compared a signature or a hashed
+// token this way and, being tier 1+ packages that both sit below `@ultimat3/core`, neither is the
+// other's dependency — so the one copy lives here, at the tier both can reach.
+
+/**
+ * Length is compared first and non-constant-time on purpose: every secret this compares is a
+ * fixed-width hash, token or signature, so the length carries no information, and the XOR
+ * accumulator below is what has to be branch-free.
+ */
+export function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let index = 0; index < a.length; index += 1) {
+    diff |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  }
+  return diff === 0;
+}

package/src/type-pins.ts

@@ -0,0 +1,93 @@
+// Compile-time pins for the actor-facts seam and the config surface. Source, not a `.test.ts`,
+// on purpose:
+// `tsconfig.json` excludes `src/**/*.test.ts`, so `tsc -b` never reads a test file and a
+// type-level assertion written there can never fail. This module emits nothing and exports
+// nothing anybody imports — a regression is a build error, the only enforcement that counts.
+
+import type { Actor, ActorFactMap, FactKeysOf, FactMapOf } from './actor';
+import type { AppConfigInput, DatabaseConfig } from './config';
+
+/** Fails to compile when `T` is anything but `true`. The whole mechanism. */
+type Assert<T extends true> = T;
+
+interface Viewer {
+  readonly friendIds: ReadonlySet<string>;
+}
+
+/**
+ * A stand-in for what an app augments `ActorFacts` with. Declared locally rather than by
+ * augmenting the real interface: augmenting it HERE would declare `viewer` for every app that
+ * imports the framework, and a pin that changes the product it pins is not a pin.
+ */
+interface SampleFacts {
+  readonly viewer: Viewer;
+}
+
+type SampleMap = FactMapOf<SampleFacts>;
+
+/** A declared fact reads back as its own type — never `unknown`, never a bag. */
+type _FactIsTyped = Assert<[NonNullable<SampleMap['viewer']>] extends [Viewer] ? true : false>;
+
+type _FactIsNotUnknown = Assert<[unknown] extends [SampleMap['viewer']] ? false : true>;
+
+/**
+ * The denial rule, as a type. Every fact is independently absent because nothing can prove one
+ * was resolved — a job runner, a test and an MCP token exchange all mint actors too. A predicate
+ * therefore has to branch on `undefined`, so an absent fact cannot silently read as a satisfied
+ * one.
+ */
+type _AbsentFactIsRepresentable = Assert<undefined extends SampleMap['viewer'] ? true : false>;
+
+/** A typo is a build error rather than a fact that is forever absent. */
+type _UnknownFactIsNotAKey = Assert<'viewr' extends keyof SampleMap ? false : true>;
+
+/** The phantom that keeps the empty interface from being `{}` is never itself a fact. */
+type _PhantomIsNotAFactKey = Assert<'__ultimate' extends FactKeysOf<SampleFacts> ? false : true>;
+
+/** An actor that resolved nothing is still an actor: every key is optional, always. */
+type _NoFactsIsALegalFactMap = Assert<Record<string, never> extends SampleMap ? true : false>;
+
+type _ActorFactMapAcceptsNothing = Assert<
+  Record<string, never> extends ActorFactMap ? true : false
+>;
+
+/**
+ * The seam is additive: an actor literal written before it existed still is one. `facts` is
+ * optional for that reason and not only for the denial rule — a required member would have been
+ * a breaking change to a tier-0 type every package depends on.
+ */
+type _ActorWithoutFactsIsStillAnActor = Assert<
+  [
+    {
+      readonly kind: 'user';
+      readonly id: string;
+      readonly roles: readonly string[];
+      readonly scopes: readonly string[];
+    },
+  ] extends [Actor]
+    ? true
+    : false
+>;
+
+/**
+ * The three `config.database` fields deleted 2026-08 must stay deleted. Each produced neither a
+ * build error nor a runtime effect, which is the worst state a config field can be in: an SRE set
+ * `poolSize: 3`, redeployed, and nothing changed. Re-adding one silently restores that, so the
+ * pin is here rather than in a `.test.ts` — a `@ts-expect-error` in an excluded file asserts
+ * nothing.
+ *
+ * `DATABASE_POOL_MAX` is the pool knob that works, `DATABASE_URL` is read as a literal by
+ * `@ultimat3/db`'s `client.ts`, and nothing emits `SET search_path`.
+ */
+type DeadDatabaseField = 'urlEnv' | 'poolSize' | 'schema';
+
+type _DatabaseConfigCarriesNoDeadField = Assert<
+  Extract<keyof DatabaseConfig, DeadDatabaseField> extends never ? true : false
+>;
+
+/** And the input side with it — `Input<DatabaseConfig>` is what an `app.config.ts` writes. */
+type _DatabaseInputCarriesNoDeadField = Assert<
+  Extract<keyof NonNullable<AppConfigInput['database']>, DeadDatabaseField> extends never
+    ? true
+    : false
+>;

package/src/version.ts

@@ -3,11 +3,12 @@
 // manifest is `private` and carries no `version`, and after `npm install` a walk above the package
 // lands in `node_modules/` where there is no manifest at all. Both mistakes fail silently.
 
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 // Bun has no path-join primitive; `import.meta.dir` is the module's own directory in both the
 // checked-out `src/` layout and the published `dist/` one, each exactly one level below the
 // package root.
 import { resolve } from 'node:path';
+import { renderCauseValue } from './error-render';
 import { UltimateError } from './errors';
 
 const SEMVER = /^\d+\.\d+\.\d+(?:[-+][\w.-]+)*$/;
@@ -15,10 +16,22 @@ const SEMVER = /^\d+\.\d+\.\d+(?:[-+][\w.-]+)*$/;
 /** `@ultimat3/core`'s own manifest — the only file that can answer what version shipped. */
 export const VERSION_MANIFEST = resolve(import.meta.dir, '..', 'package.json');
 
+/**
+ * The bundler define that carries the version into a build with no manifest to read.
+ * `x build --target binary` passes it (`binaryArgs` in `@ultimat3/cli`); the name is declared here
+ * so the flag that writes it and the read below cannot drift.
+ */
+export const VERSION_DEFINE = 'ULTIMATE_FRAMEWORK_VERSION';
+
+// Replaced with a string literal by `bun build --define ULTIMATE_FRAMEWORK_VERSION='"1.2.3"'`, and
+// declared by nothing at runtime — which is why the read is `typeof`-guarded. An unbundled process
+// must see `undefined` here, not a `ReferenceError`.
+declare const ULTIMATE_FRAMEWORK_VERSION: string | undefined;
+
 /**
  * A package with no readable version is a broken publish, not a runtime condition to degrade
  * through: an `undefined` version poisons the MCP handshake and every dependency a scaffold pins,
- * and does it quietly. Fail at import, where the fix is a release-script change.
+ * and does it quietly. Fail where the fix is a release-script change.
  */
 export function readPackageVersion(manifestPath: string): string {
   const raw: unknown = JSON.parse(readFileSync(manifestPath, 'utf-8'));
@@ -27,11 +40,47 @@ export function readPackageVersion(manifestPath: string): string {
   if (typeof version !== 'string' || !SEMVER.test(version)) {
     throw new UltimateError({
       code: 'X_INVARIANT',
-      cause: `${manifestPath} has no valid semver "version" field (found ${JSON.stringify(version)})`,
+      cause: `${manifestPath} has no valid semver "version" field (found ${renderCauseValue(version)})`,
       fix: `set a semver "version" in ${manifestPath}, then re-run: bun run verify`,
     });
   }
   return version;
 }
 
-export const FRAMEWORK_VERSION: string = readPackageVersion(VERSION_MANIFEST);
+/**
+ * Manifest first, build define second, throw last.
+ *
+ * A single-file executable carries no `package.json`, so a *missing* manifest is the one absence
+ * that is not a broken publish — it falls through to the define. A manifest that exists and
+ * declares no semver still throws, because that is the broken publish `readPackageVersion` was
+ * written for, and a define must not paper over it. Pure and exported so the compiled-binary case
+ * is a unit test rather than a `bun build --compile` nobody runs.
+ */
+export function resolveVersion(manifestPath: string, defined: string | undefined): string {
+  if (existsSync(manifestPath)) return readPackageVersion(manifestPath);
+  if (defined !== undefined && SEMVER.test(defined)) return defined;
+  throw new UltimateError({
+    code: 'X_INVARIANT',
+    cause: `no manifest at ${manifestPath} and no valid ${VERSION_DEFINE} define (found ${JSON.stringify(defined)}) — only the builder that passes the define produces a bootable binary`,
+    fix: `x build --target binary`,
+  });
+}
+
+let resolved: string | undefined;
+
+/**
+ * The framework's version, resolved on first call and cached for every call after.
+ *
+ * Lazy is the whole point. As a module-scope constant the read ran before `main` in every process
+ * that imported core, so `x build --target binary` produced an artifact that threw at import
+ * before any role started — the artifact compiled and could never boot.
+ */
+export function frameworkVersion(): string {
+  if (resolved === undefined) {
+    resolved = resolveVersion(
+      VERSION_MANIFEST,
+      typeof ULTIMATE_FRAMEWORK_VERSION === 'string' ? ULTIMATE_FRAMEWORK_VERSION : undefined,
+    );
+  }
+  return resolved;
+}