@ultimat3/core 1.0.0

package/src/error-codes.ts

@@ -0,0 +1,131 @@
+// Single responsibility: the framework-wide error-code registry (code -> title + docs).
+// One source of truth so the CLI, the dev overlay and `--json` render identical text.
+// The cycle with ./errors is intentional and safe: nothing here touches UltimateError at
+// module-evaluation time.
+
+import { UltimateError } from './errors';
+
+export interface ErrorCodeDescriptor {
+  readonly title: string;
+  readonly docs: string;
+}
+
+export interface ErrorCodeDeclaration {
+  readonly title: string;
+  readonly docs?: string | undefined;
+}
+
+export interface ErrorCodeEntry extends ErrorCodeDescriptor {
+  readonly code: string;
+}
+
+export const ERROR_DOCS_BASE = 'https://ultimate.dev/errors/';
+
+export function errorDocsUrl(code: string): string {
+  return `${ERROR_DOCS_BASE}${code}`;
+}
+
+/** Codes owned by `@ultimat3/core`. Every other package calls `registerErrorCodes()`. */
+const CORE_CODE_TITLES = {
+  X_ABORTED: 'operation aborted',
+  X_CONFIG_INVALID: 'app.config.ts is invalid',
+  X_CURSOR_INVALID: 'pagination cursor is malformed, tampered with or from another query',
+  X_CURSOR_SECRET_DEV: 'cursors are signed with the shipped development key',
+  X_DRAINING: 'process is draining and refuses new work',
+  X_ENV_MISSING: 'required environment variables are missing or invalid',
+  X_ERROR_CODE_DUPLICATE: 'error code registered twice',
+  X_ID_INVALID: 'value is not a valid id',
+  X_IMAGE_DECODE_FAILED: 'image bytes are malformed, truncated or internally inconsistent',
+  X_IMAGE_TOO_LARGE: 'image exceeds the pipeline pixel ceiling',
+  X_IMAGE_UNSUPPORTED: 'the built-in image pipeline cannot read or write this format',
+  X_INTERNAL: 'unexpected internal framework error',
+  X_INVARIANT: 'invariant violated',
+  X_NO_CONTEXT: 'no request context is active',
+  X_NOT_IMPLEMENTED: 'this driver does not implement the requested feature',
+  X_REGISTRAR_CONFLICT: 'two different registrars are loaded for one primitive kind',
+  X_REGISTRAR_MISSING: 'no registrar is loaded for a primitive kind',
+  X_ROLE_INVALID: 'ROLE is not a known runtime role',
+  X_SERVICE_DUPLICATE: 'a service name is registered twice',
+  X_SERVICE_MISSING: 'service is not registered on the request context',
+  X_SHUTDOWN_TIMEOUT: 'graceful shutdown exceeded its deadline',
+  X_UNREACHABLE: 'unreachable branch was reached',
+} as const;
+
+export type CoreErrorCode = keyof typeof CORE_CODE_TITLES;
+
+function descriptor(code: string, declaration: ErrorCodeDeclaration): ErrorCodeDescriptor {
+  return Object.freeze({ title: declaration.title, docs: declaration.docs ?? errorDocsUrl(code) });
+}
+
+export const CORE_ERROR_CODES: Readonly<Record<CoreErrorCode, ErrorCodeDescriptor>> = Object.freeze(
+  Object.fromEntries(
+    Object.entries(CORE_CODE_TITLES).map(([code, title]) => [code, descriptor(code, { title })]),
+  ) as Record<CoreErrorCode, ErrorCodeDescriptor>,
+);
+
+const registry = new Map<string, ErrorCodeDescriptor>(Object.entries(CORE_ERROR_CODES));
+
+/**
+ * Register a package's codes. Throws `X_ERROR_CODE_DUPLICATE` on collision so two packages
+ * can never disagree about what a code means.
+ */
+export function registerErrorCodes(codes: Readonly<Record<string, ErrorCodeDeclaration>>): void {
+  const duplicates: string[] = [];
+  for (const code of Object.keys(codes)) {
+    if (registry.has(code)) duplicates.push(code);
+  }
+  if (duplicates.length > 0) {
+    throw new UltimateError({
+      code: 'X_ERROR_CODE_DUPLICATE',
+      cause: `already registered: ${duplicates.join(', ')}`,
+      fix: `rename the colliding code(s) in the registering package's src/errors.ts`,
+      meta: { duplicates },
+    });
+  }
+  for (const [code, declaration] of Object.entries(codes)) {
+    registry.set(code, descriptor(code, declaration));
+  }
+}
+
+/** `X_DB_DRIFT` -> `db drift`. Deterministic fallback so an unknown code still renders. */
+function humanize(code: string): string {
+  return code.replace(/^X_/, '').toLowerCase().replaceAll('_', ' ');
+}
+
+export function describeErrorCode(code: string): ErrorCodeDescriptor {
+  const known = registry.get(code);
+  if (known !== undefined) return known;
+  return descriptor(code, { title: humanize(code) });
+}
+
+export function hasErrorCode(code: string): boolean {
+  return registry.has(code);
+}
+
+/** Sorted, stable — the CLI prints this for `x errors --json`. */
+export function listErrorCodes(): readonly ErrorCodeEntry[] {
+  return [...registry.entries()]
+    .map(([code, value]) => ({ code, title: value.title, docs: value.docs }))
+    .sort((a, b) => (a.code < b.code ? -1 : a.code > b.code ? 1 : 0));
+}
+
+/** Test-only: drop everything a package registered, keeping core's codes. */
+export function resetErrorCodes(): void {
+  registry.clear();
+  for (const [code, value] of Object.entries(CORE_ERROR_CODES)) registry.set(code, value);
+}
+
+/**
+ * Test-only: capture the registry and get the undo back. Every package registers its codes once,
+ * at import time, and bun shares one process across test files — so a file that resets the
+ * registry permanently strips the titles of every package imported before it, and their errors
+ * render the humanised fallback (`X_DB_DRIFT: db drift`) for the rest of the run. Returning the
+ * restore rather than a value is deliberate: there is nothing to hand back to the wrong registry.
+ */
+export function errorCodeSnapshot(): () => void {
+  const saved = new Map(registry);
+  return () => {
+    registry.clear();
+    for (const [code, value] of saved) registry.set(code, value);
+  };
+}

package/src/errors.ts

@@ -0,0 +1,159 @@
+// Single responsibility: `UltimateError` — the one error type every Ultimate package throws.
+// Stable code + cause + exact fix command, rendered identically in the terminal, the browser
+// overlay and `--json`. Never throw a bare Error anywhere in the framework.
+
+import { describeErrorCode } from './error-codes';
+
+/**
+ * Structural brand. `instanceof` is unreliable across duplicated module instances and across
+ * tier-0 packages that may not import each other (`@ultimat3/schema` cannot import
+ * `@ultimat3/core`), so the guard is duck-typed on a well-known symbol instead.
+ */
+export const ULTIMATE_ERROR_BRAND: unique symbol = Symbol.for('ultimate.error');
+
+export interface UltimateErrorInit {
+  /** `SCREAMING_SNAKE`, prefixed `X_`. Must exist in the code registry to get a title. */
+  readonly code: string;
+  /** What actually happened, concrete and specific. Never a generic sentence. */
+  readonly cause: string;
+  /** The exact command or edit that fixes it. */
+  readonly fix: string;
+  readonly docs?: string | undefined;
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+  /** The underlying thrown value, when this error wraps one. */
+  readonly sourceError?: unknown;
+}
+
+export interface UltimateErrorJSON {
+  readonly code: string;
+  readonly title: string;
+  readonly cause: string;
+  readonly fix: string;
+  readonly docs: string;
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+  readonly stack?: string | undefined;
+}
+
+export interface FormatErrorOptions {
+  /** Append a 4th `docs:` line. Off by default — the contract's rendering is 3 lines. */
+  readonly docs?: boolean | undefined;
+}
+
+export class UltimateError extends Error {
+  readonly [ULTIMATE_ERROR_BRAND] = true;
+  override readonly name: string = 'UltimateError';
+  readonly code: string;
+  readonly title: string;
+  /** Set by `Error`'s `cause` option; always a human-readable string in Ultimate. */
+  declare readonly cause: string;
+  readonly fix: string;
+  readonly docs: string;
+  readonly meta: Readonly<Record<string, unknown>> | undefined;
+  readonly sourceError: unknown;
+
+  constructor(init: UltimateErrorInit) {
+    const described = describeErrorCode(init.code);
+    // `message` carries the cause because it is the ONLY field a runtime prints when an
+    // error escapes uncaught — a worker log, a CI transcript, a stack trace. A message of
+    // just `code: title` tells an operator which rule fired but not which row, column or
+    // value, which is the opposite of "errors are instructions". `format()` still renders
+    // the canonical 3 lines from the fields, so the two never disagree.
+    super(`${init.code}: ${described.title} — ${init.cause}`, { cause: init.cause });
+    this.code = init.code;
+    this.title = described.title;
+    this.fix = init.fix;
+    this.docs = init.docs ?? described.docs;
+    this.meta = init.meta;
+    this.sourceError = init.sourceError;
+  }
+
+  /**
+   * The canonical 3-line terminal rendering:
+   *
+   * ```text
+   * X_DB_DRIFT: schema differs from migrations
+   *   cause: table "posts" has column "publish_at" not present in any migration
+   *   fix:   x db gen "add publish_at"
+   * ```
+   */
+  format(options?: FormatErrorOptions): string {
+    const lines = [`${this.code}: ${this.title}`, `  cause: ${this.cause}`, `  fix:   ${this.fix}`];
+    if (options?.docs === true) lines.push(`  docs:  ${this.docs}`);
+    return lines.join('\n');
+  }
+
+  toJSON(): UltimateErrorJSON {
+    return {
+      code: this.code,
+      title: this.title,
+      cause: this.cause,
+      fix: this.fix,
+      docs: this.docs,
+      meta: this.meta,
+      stack: this.stack,
+    };
+  }
+}
+
+export function isUltimateError(value: unknown): value is UltimateError {
+  return typeof value === 'object' && value !== null && ULTIMATE_ERROR_BRAND in value;
+}
+
+/** Init for a subclass that owns its code. */
+export type CodedErrorInit = Omit<UltimateErrorInit, 'code'>;
+
+export class ConfigInvalidError extends UltimateError {
+  static readonly code = 'X_CONFIG_INVALID';
+  override readonly name = 'ConfigInvalidError';
+  constructor(init: CodedErrorInit) {
+    super({ ...init, code: ConfigInvalidError.code });
+  }
+}
+
+export class EnvMissingError extends UltimateError {
+  static readonly code = 'X_ENV_MISSING';
+  override readonly name = 'EnvMissingError';
+  constructor(init: CodedErrorInit) {
+    super({ ...init, code: EnvMissingError.code });
+  }
+}
+
+export class NotImplementedError extends UltimateError {
+  static readonly code = 'X_NOT_IMPLEMENTED';
+  override readonly name = 'NotImplementedError';
+  constructor(init: CodedErrorInit) {
+    super({ ...init, code: NotImplementedError.code });
+  }
+}
+
+export class InternalError extends UltimateError {
+  static readonly code = 'X_INTERNAL';
+  override readonly name = 'InternalError';
+  constructor(init: CodedErrorInit) {
+    super({ ...init, code: InternalError.code });
+  }
+}
+
+/** The blessed shape for an unimplemented remote driver. Always carries a real fix line. */
+export function notImplemented(feature: string, fix: string): never {
+  throw new NotImplementedError({ cause: `${feature} is not implemented by this driver`, fix });
+}
+
+/** Normalise anything caught into an `UltimateError` without losing the original. */
+export function toUltimateError(value: unknown, fix?: string): UltimateError {
+  if (isUltimateError(value)) return value;
+  const cause =
+    value instanceof Error
+      ? `${value.name}: ${value.message}`
+      : `non-error value thrown: ${String(value)}`;
+  return new InternalError({
+    cause,
+    fix: fix ?? 'fix the underlying failure named in cause, then re-run',
+    sourceError: value,
+  });
+}
+
+/** Render any caught value with the 3-line contract, so CLI output never varies. */
+export function formatError(value: unknown, options?: FormatErrorOptions): string {
+  return toUltimateError(value).format(options);
+}

package/src/ids.ts

@@ -0,0 +1,132 @@
+// Single responsibility: identifier generation. UUIDv7 is the framework default because
+// database indexes, cursors and log sorting all want time-ordered keys.
+
+import { type Clock, systemClock } from './clock';
+import { UltimateError } from './errors';
+
+/** Nominal typing without a runtime cost. `Brand<string, 'post'>` never mixes with `'user'`. */
+export type Brand<T, K extends string> = T & { readonly __brand: K };
+
+/** A branded UUIDv7 for entity `K`. */
+export type Id<K extends string> = Brand<string, K>;
+
+const HEX = '0123456789abcdef';
+/** Exactly 64 URL-safe characters, so `byte & 63` is unbiased and never lands out of range. */
+const NANO_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+/** 12-bit counter lives in `rand_a`, seeded low so ~3k ids/ms fit before it overflows. */
+const COUNTER_SEED_MASK = 0x3ff;
+const COUNTER_MAX = 0xfff;
+
+let lastEpochMs = -1;
+let counter = 0;
+
+function randomBytes(length: number): Uint8Array {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  return bytes;
+}
+
+export function randomHex(byteLength: number): string {
+  const bytes = randomBytes(byteLength);
+  let out = '';
+  for (const byte of bytes) {
+    out += HEX[byte >> 4];
+    out += HEX[byte & 0x0f];
+  }
+  return out;
+}
+
+/**
+ * UUIDv7 per RFC 9562: 48-bit unix ms, version 7, 12-bit monotonic counter, 62 random bits.
+ * Strictly increasing lexicographically even within the same millisecond, and never goes
+ * backwards when the wall clock does.
+ */
+export function uuid(clock: Clock = systemClock): string {
+  let epochMs = clock.now().getTime();
+  if (epochMs < lastEpochMs) epochMs = lastEpochMs;
+
+  if (epochMs === lastEpochMs) {
+    counter += 1;
+    if (counter > COUNTER_MAX) {
+      epochMs += 1;
+      counter = randomBytes(2)[0]! & COUNTER_SEED_MASK;
+    }
+  } else {
+    counter = randomBytes(2)[0]! & COUNTER_SEED_MASK;
+  }
+  lastEpochMs = epochMs;
+
+  const timeHex = epochMs.toString(16).padStart(12, '0').slice(-12);
+  const randA = counter.toString(16).padStart(3, '0');
+  const tail = randomHex(8);
+  // Force the RFC variant bits (0b10) into the first nibble of `rand_b`.
+  const variantNibble = HEX[(Number.parseInt(tail[0]!, 16) & 0x3) | 0x8]!;
+
+  return [
+    timeHex.slice(0, 8),
+    timeHex.slice(8, 12),
+    `7${randA}`,
+    `${variantNibble}${tail.slice(1, 4)}`,
+    tail.slice(4, 16).padEnd(12, '0'),
+  ].join('-');
+}
+
+export function isUuid(value: unknown): boolean {
+  return typeof value === 'string' && UUID_RE.test(value);
+}
+
+/** Recover the generation instant from a v7 id — cheap debugging and cursor windows. */
+export function uuidTimestamp(id: string): Date {
+  if (!isUuid(id)) {
+    throw new UltimateError({
+      code: 'X_ID_INVALID',
+      cause: `"${id}" is not a UUIDv7`,
+      fix: 'generate ids with uuid() from @ultimat3/core',
+      meta: { id },
+    });
+  }
+  return new Date(Number.parseInt(id.slice(0, 8) + id.slice(9, 13), 16));
+}
+
+/** URL-safe random id. Not sortable — use it for tokens and slugs, never primary keys. */
+export function nanoid(length = 21): string {
+  const bytes = randomBytes(length);
+  let out = '';
+  for (const byte of bytes) out += NANO_ALPHABET[byte & 63] as string;
+  return out;
+}
+
+/** `typedId<'post'>()` — a UUIDv7 branded so it cannot be passed where a user id is wanted. */
+export function typedId<K extends string>(clock: Clock = systemClock): Id<K> {
+  return uuid(clock) as Id<K>;
+}
+
+/** Validate an untrusted string into a branded id. Throws `X_ID_INVALID`. */
+export function parseId<K extends string>(kind: K, value: unknown): Id<K> {
+  if (!isUuid(value)) {
+    throw new UltimateError({
+      code: 'X_ID_INVALID',
+      cause: `expected a ${kind} UUIDv7, received ${JSON.stringify(value)}`,
+      fix: `pass an id produced by typedId<'${kind}'>()`,
+      meta: { kind, value },
+    });
+  }
+  return value as Id<K>;
+}
+
+/** W3C trace-context ids: 16 bytes / 8 bytes of hex. */
+export function traceId(): string {
+  return randomHex(16);
+}
+
+export function spanId(): string {
+  return randomHex(8);
+}
+
+/** Test-only: reset the monotonic counter so a frozen clock produces a fresh sequence. */
+export function resetIdCounter(): void {
+  lastEpochMs = -1;
+  counter = 0;
+}

package/src/image/color.ts

@@ -0,0 +1,34 @@
+// Single responsibility: the framework's ONE colour grammar — hex or `transparent`, nothing else.
+// It is a parser over strings with no knowledge of pixels, so it lives beside the resampler rather
+// than inside it; and it stays deliberately tiny because a second accepted spelling is a second
+// thing an agent has to guess right, for a padding colour nobody looks at twice.
+
+import { imageUnsupported } from './errors';
+
+const COLOR_FIX =
+  "pass '#rgb', '#rgba', '#rrggbb', '#rrggbbaa' or 'transparent' — hex or transparent, " +
+  'there are no named colours';
+
+const HEX = /^#[0-9a-f]+$/;
+/** '#rgb', '#rgba', '#rrggbb', '#rrggbbaa' — the whole grammar, hash included. */
+const HEX_LENGTHS: readonly number[] = [4, 5, 7, 9];
+
+/** Hex or `transparent`, nothing else — one way to write a colour is one thing to get wrong. */
+export function parseColor(value: string): readonly [number, number, number, number] {
+  const text = value.toLowerCase();
+  if (text === 'transparent') return [0, 0, 0, 0];
+  if (!HEX.test(text) || !HEX_LENGTHS.includes(text.length)) {
+    throw imageUnsupported(`'${value}' is not a colour this pipeline understands`, COLOR_FIX, {
+      value,
+    });
+  }
+  const hex = text.slice(1);
+  const short = hex.length < 6;
+  const size = short ? 1 : 2;
+  const channel = (index: number): number => {
+    const part = hex.slice(index * size, index * size + size);
+    return Number.parseInt(short ? part + part : part, 16);
+  };
+  const opaque = hex.length === 3 || hex.length === 6;
+  return [channel(0), channel(1), channel(2), opaque ? 255 : channel(3)];
+}

package/src/image/errors.ts

@@ -0,0 +1,58 @@
+// Single responsibility: the three failure modes of the image pipeline, as coded errors.
+// Every one names the format AND a runnable way forward, because an agent that hits
+// "unsupported" needs to know which format to ask for instead, not that it lost.
+
+import { UltimateError } from '../errors';
+
+export class ImageUnsupportedError extends UltimateError {
+  static readonly code = 'X_IMAGE_UNSUPPORTED';
+  override readonly name = 'ImageUnsupportedError';
+  constructor(cause: string, fix: string, meta?: Readonly<Record<string, unknown>>) {
+    super({ code: ImageUnsupportedError.code, cause, fix, meta });
+  }
+}
+
+export class ImageDecodeFailedError extends UltimateError {
+  static readonly code = 'X_IMAGE_DECODE_FAILED';
+  override readonly name = 'ImageDecodeFailedError';
+  constructor(cause: string, fix: string, meta?: Readonly<Record<string, unknown>>) {
+    super({ code: ImageDecodeFailedError.code, cause, fix, meta });
+  }
+}
+
+export class ImageTooLargeError extends UltimateError {
+  static readonly code = 'X_IMAGE_TOO_LARGE';
+  override readonly name = 'ImageTooLargeError';
+  constructor(cause: string, fix: string, meta?: Readonly<Record<string, unknown>>) {
+    super({ code: ImageTooLargeError.code, cause, fix, meta });
+  }
+}
+
+/** A format or a coding feature the built-in pipeline does not implement. */
+export const imageUnsupported = (
+  cause: string,
+  fix: string,
+  meta?: Readonly<Record<string, unknown>>,
+): ImageUnsupportedError => new ImageUnsupportedError(cause, fix, meta);
+
+/** Malformed, truncated or internally inconsistent bytes. Never a silent black image. */
+export const imageDecodeFailed = (
+  cause: string,
+  meta?: Readonly<Record<string, unknown>>,
+): ImageDecodeFailedError =>
+  new ImageDecodeFailedError(
+    cause,
+    'check the file is a complete, uncorrupted image: `file <path>` then re-export it',
+    meta,
+  );
+
+/** The decompression-bomb guard: pixel count is checked from the header, before allocation. */
+export const imageTooLarge = (
+  cause: string,
+  meta?: Readonly<Record<string, unknown>>,
+): ImageTooLargeError =>
+  new ImageTooLargeError(
+    cause,
+    'downscale the source before it reaches the pipeline, or raise MAX_IMAGE_PIXELS deliberately',
+    meta,
+  );