@ultimat3/core 1.0.0

package/src/lifecycle.ts

@@ -0,0 +1,242 @@
+// Single responsibility: process lifecycle and graceful drain. Every role runs the same three
+// phases on SIGTERM — stop accepting, finish in-flight, close resources — under one deadline,
+// and reports the same /healthz + /readyz state.
+
+import { type Clock, systemClock } from './clock';
+import { 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;
+  /** Monotonic ms after which hooks are abandoned. */
+  readonly deadlineAt: number;
+}
+
+export type ShutdownHook = (reason: ShutdownReason) => void | Promise<void>;
+
+export interface OnShutdownOptions {
+  readonly phase?: ShutdownPhase | undefined;
+}
+
+export interface LifecycleOptions {
+  readonly deadlineMs?: number | 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;
+}
+
+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;
+}
+
+interface Registration {
+  readonly name: string;
+  readonly phase: ShutdownPhase;
+  readonly hook: ShutdownHook;
+}
+
+const DEFAULT_DEADLINE_MS = 25_000;
+
+let deadlineMs = DEFAULT_DEADLINE_MS;
+let clock: Clock = systemClock;
+let log: Logger = rootLogger;
+let state: HealthState = 'starting';
+let startedAtMono = clock.monotonic();
+let inflight = 0;
+let registrations: Registration[] = [];
+let drainPromise: Promise<void> | undefined;
+let idleWaiters: (() => void)[] = [];
+
+export function configureLifecycle(options: LifecycleOptions): void {
+  if (options.deadlineMs !== undefined) deadlineMs = options.deadlineMs;
+  if (options.clock !== undefined) {
+    clock = options.clock;
+    startedAtMono = clock.monotonic();
+  }
+  if (options.logger !== undefined) log = options.logger;
+}
+
+export function lifecycleState(): HealthState {
+  return state;
+}
+
+export function markReady(): void {
+  if (state === 'starting') state = 'ready';
+}
+
+export function inflightCount(): number {
+  return inflight;
+}
+
+/** Register a drain hook. Returns an unregister function. */
+export function onShutdown(
+  name: string,
+  hook: ShutdownHook,
+  options?: OnShutdownOptions,
+): () => void {
+  const registration: Registration = { name, phase: options?.phase ?? 'close', hook };
+  registrations.push(registration);
+  return () => {
+    registrations = registrations.filter((candidate) => candidate !== registration);
+  };
+}
+
+/**
+ * Mark a unit of work in flight. Call the returned function when it completes — drain waits
+ * for the count to reach zero before closing resources.
+ */
+export function beginWork(): () => void {
+  inflight += 1;
+  let done = false;
+  return () => {
+    if (done) return;
+    done = true;
+    inflight -= 1;
+    if (inflight === 0) {
+      const waiters = idleWaiters;
+      idleWaiters = [];
+      for (const waiter of waiters) waiter();
+    }
+  };
+}
+
+/** True when new work must be refused — the HTTP layer answers 503 while this holds. */
+export function isDraining(): boolean {
+  return state === 'draining' || state === 'stopped';
+}
+
+function waitForIdle(timeoutMs: number): Promise<boolean> {
+  if (inflight === 0) return Promise.resolve(true);
+  return new Promise<boolean>((resolve) => {
+    const timer = setTimeout(() => resolve(false), timeoutMs);
+    idleWaiters.push(() => {
+      clearTimeout(timer);
+      resolve(true);
+    });
+  });
+}
+
+async function runPhase(phase: ShutdownPhase, reason: ShutdownReason): Promise<void> {
+  for (const registration of registrations.filter((entry) => entry.phase === phase)) {
+    try {
+      await registration.hook(reason);
+    } catch (thrown) {
+      log.error('shutdown hook failed', {
+        hook: registration.name,
+        phase,
+        error: thrown,
+      });
+    }
+  }
+}
+
+/** Idempotent: concurrent signals join the same drain. */
+export function drain(signal = 'manual'): Promise<void> {
+  if (drainPromise !== undefined) return drainPromise;
+  state = 'draining';
+  const reason: ShutdownReason = { signal, deadlineAt: clock.monotonic() + deadlineMs };
+
+  drainPromise = (async () => {
+    log.info('draining', { signal, deadlineMs, inflight });
+    await runPhase('accept', reason);
+
+    const remaining = Math.max(0, reason.deadlineAt - clock.monotonic());
+    const idle = await waitForIdle(remaining);
+    if (!idle) {
+      log.warn('X_SHUTDOWN_TIMEOUT', {
+        code: 'X_SHUTDOWN_TIMEOUT',
+        cause: `${inflight} in-flight operations still running after ${deadlineMs}ms`,
+        fix: 'raise configureLifecycle({ deadlineMs }) or shorten the slow handler',
+      });
+    }
+
+    await runPhase('inflight', reason);
+    await runPhase('close', reason);
+    state = 'stopped';
+    log.info('stopped', { signal });
+  })();
+
+  return drainPromise;
+}
+
+export interface SignalHandlerOptions {
+  readonly signals?: readonly ProcessSignal[] | undefined;
+  /** Call `process.exit()` once drained. Off in tests. */
+  readonly exit?: boolean | undefined;
+}
+
+/** Install SIGTERM/SIGINT handling. Returns an uninstall function. */
+export function installSignalHandlers(options?: SignalHandlerOptions): () => void {
+  const signals: readonly ProcessSignal[] = options?.signals ?? ['SIGTERM', 'SIGINT'];
+  const handlers = new Map<ProcessSignal, () => void>();
+
+  for (const signal of signals) {
+    const handler = (): void => {
+      void drain(signal).then(() => {
+        if (options?.exit === true) process.exit(0);
+      });
+    };
+    handlers.set(signal, handler);
+    process.on(signal, handler);
+  }
+
+  return () => {
+    for (const [signal, handler] of handlers) process.off(signal, handler);
+  };
+}
+
+export function healthReport(): HealthReport {
+  return {
+    state,
+    ready: state === 'ready',
+    uptimeMs: Math.round(clock.monotonic() - startedAtMono),
+    inflight,
+    buildId: process.env['BUILD_ID'] ?? 'dev',
+  };
+}
+
+/** Liveness: the process exists and is not wedged. Stays 200 while draining. */
+export function healthzPayload(): HealthPayload {
+  const body = healthReport();
+  const ok = state !== 'stopped';
+  return { ok, status: ok ? 200 : 503, body };
+}
+
+/** Readiness: may this instance receive traffic? 503 while starting or draining. */
+export function readyzPayload(): HealthPayload {
+  const body = healthReport();
+  const ok = state === 'ready';
+  return { ok, status: ok ? 200 : 503, body };
+}
+
+/** Test-only: forget all hooks and return to `starting`. */
+export function resetLifecycle(): void {
+  deadlineMs = DEFAULT_DEADLINE_MS;
+  clock = systemClock;
+  log = rootLogger;
+  state = 'starting';
+  startedAtMono = clock.monotonic();
+  inflight = 0;
+  registrations = [];
+  drainPromise = undefined;
+  idleWaiters = [];
+}

package/src/listeners.ts

@@ -0,0 +1,80 @@
+// Single responsibility: the sockets this process is currently listening on. A request to one of
+// them is the process calling itself, not egress — which is how a sealed test network can let a
+// booted server reach its own port without an allowlist entry per kernel-assigned port.
+
+import { assert } from './assert';
+
+interface Listener {
+  readonly origin: string;
+  count: number;
+}
+
+/**
+ * Every spelling of "this machine". A wildcard bind is reachable over loopback, so it collapses
+ * to the same key: a server on `0.0.0.0:3000` answers `http://localhost:3000`.
+ */
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '0.0.0.0', '[::1]', '[::]']);
+
+const listeners = new Map<string, Listener>();
+
+const portOf = (url: URL): string => {
+  if (url.port !== '') return url.port;
+  return url.protocol === 'https:' || url.protocol === 'wss:' ? '443' : '80';
+};
+
+/** Identity is host+port, not the origin string: the same socket has several valid spellings. */
+const keyOf = (url: URL): string => {
+  const host = url.hostname.toLowerCase();
+  return `${LOOPBACK_HOSTS.has(host) ? 'loopback' : host}:${portOf(url)}`;
+};
+
+const parseUrl = (url: string): URL | undefined => {
+  try {
+    return new URL(url);
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Announce a socket this process just opened; call the returned release when it closes. Releasing
+ * twice is a no-op, so a manual `stop()` and a SIGTERM drain may both call it. Refcounted, so two
+ * servers on one origin do not un-announce each other.
+ */
+export function markListening(origin: string): () => void {
+  const url = parseUrl(origin);
+  assert(
+    url !== undefined,
+    `not a URL: ${origin}`,
+    'pass the server origin, e.g. markListening(server.url.origin)',
+  );
+  const key = keyOf(url);
+  const existing = listeners.get(key);
+  if (existing === undefined) listeners.set(key, { origin: url.origin, count: 1 });
+  else existing.count += 1;
+
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    const entry = listeners.get(key);
+    if (entry === undefined) return;
+    entry.count -= 1;
+    if (entry.count <= 0) listeners.delete(key);
+  };
+}
+
+/** The origins this process is serving right now, in announce order. */
+export const listeningOrigins = (): readonly string[] =>
+  [...listeners.values()].map((listener) => listener.origin);
+
+/** True when the URL points at a socket this process opened — same port, any loopback spelling. */
+export function isSelfOrigin(url: string): boolean {
+  const parsed = parseUrl(url);
+  return parsed !== undefined && listeners.has(keyOf(parsed));
+}
+
+/** Test-only: forget every announced socket. */
+export function resetListeners(): void {
+  listeners.clear();
+}

package/src/logger.ts

@@ -0,0 +1,146 @@
+// Single responsibility: structured JSON logging. One line per event, machine-readable by
+// default because the primary reader is an agent tailing `x logs --json`.
+
+import { type Clock, systemClock } from './clock';
+import { isUltimateError } from './errors';
+
+export const LOG_LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'fatal', 'silent'] as const;
+
+export type LogLevel = (typeof LOG_LEVELS)[number];
+
+const LEVEL_WEIGHT: Readonly<Record<LogLevel, number>> = Object.freeze({
+  trace: 10,
+  debug: 20,
+  info: 30,
+  warn: 40,
+  error: 50,
+  fatal: 60,
+  silent: 100,
+});
+
+export interface LogFields {
+  readonly [key: string]: unknown;
+}
+
+export interface Logger {
+  readonly level: LogLevel;
+  trace(message: string, fields?: LogFields): void;
+  debug(message: string, fields?: LogFields): void;
+  info(message: string, fields?: LogFields): void;
+  warn(message: string, fields?: LogFields): void;
+  error(message: string, fields?: LogFields): void;
+  fatal(message: string, fields?: LogFields): void;
+  /** Bind fields onto every subsequent line. Child fields win over parent fields. */
+  child(fields: LogFields): Logger;
+  withLevel(level: LogLevel): Logger;
+}
+
+export interface LoggerOptions {
+  readonly level?: LogLevel | undefined;
+  readonly fields?: LogFields | undefined;
+  readonly clock?: Clock | undefined;
+  /** Receives one complete JSON line (no trailing newline). Defaults to stdout/stderr. */
+  readonly writer?: ((line: string, level: LogLevel) => void) | undefined;
+}
+
+export const REDACTED = '[redacted]';
+
+const redactedKeys = new Set<string>([
+  'password',
+  'token',
+  'secret',
+  'authorization',
+  'cookie',
+  'apiKey',
+  'accessToken',
+  'refreshToken',
+]);
+
+/** Mark keys as secret everywhere. `defineEnv()` calls this for every `secret: true` var. */
+export function redactKeys(keys: Iterable<string>): void {
+  for (const key of keys) redactedKeys.add(key.toLowerCase());
+}
+
+export function isRedactedKey(key: string): boolean {
+  return redactedKeys.has(key.toLowerCase());
+}
+
+/**
+ * Fields injected into every line — set once by `context.ts` so `requestId`/`traceId` appear
+ * without threading the context into every call site.
+ */
+let contextFields: () => LogFields | undefined = () => undefined;
+
+export function setLoggerContextFields(provider: () => LogFields | undefined): void {
+  contextFields = provider;
+}
+
+function defaultWriter(line: string, level: LogLevel): void {
+  const stream = LEVEL_WEIGHT[level] >= LEVEL_WEIGHT.error ? process.stderr : process.stdout;
+  stream.write(`${line}\n`);
+}
+
+function serialiseValue(value: unknown, depth: number): unknown {
+  if (value === null || typeof value !== 'object') return value;
+  if (value instanceof Date) return value.toISOString();
+  if (isUltimateError(value)) return value.toJSON();
+  if (value instanceof Error) return { name: value.name, message: value.message };
+  if (depth >= 6) return '[depth-limit]';
+  if (Array.isArray(value)) return value.map((item) => serialiseValue(item, depth + 1));
+  const out: Record<string, unknown> = {};
+  for (const [key, nested] of Object.entries(value as Record<string, unknown>)) {
+    out[key] = isRedactedKey(key) ? REDACTED : serialiseValue(nested, depth + 1);
+  }
+  return out;
+}
+
+function redactFields(fields: LogFields): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(fields)) {
+    out[key] = isRedactedKey(key) ? REDACTED : serialiseValue(value, 0);
+  }
+  return out;
+}
+
+function envLevel(): LogLevel {
+  const raw = process.env['LOG_LEVEL'];
+  return raw !== undefined && (LOG_LEVELS as readonly string[]).includes(raw)
+    ? (raw as LogLevel)
+    : 'info';
+}
+
+export function createLogger(options?: LoggerOptions): Logger {
+  const level = options?.level ?? envLevel();
+  const bound = options?.fields ?? {};
+  const clock = options?.clock ?? systemClock;
+  const writer = options?.writer ?? defaultWriter;
+  const threshold = LEVEL_WEIGHT[level];
+
+  function emit(lineLevel: LogLevel, message: string, fields?: LogFields): void {
+    if (LEVEL_WEIGHT[lineLevel] < threshold) return;
+    const line = {
+      ts: clock.now().toISOString(),
+      level: lineLevel,
+      msg: message,
+      ...redactFields(bound),
+      ...redactFields(contextFields() ?? {}),
+      ...redactFields(fields ?? {}),
+    };
+    writer(JSON.stringify(line), lineLevel);
+  }
+
+  return {
+    level,
+    trace: (message, fields) => emit('trace', message, fields),
+    debug: (message, fields) => emit('debug', message, fields),
+    info: (message, fields) => emit('info', message, fields),
+    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 }),
+  };
+}
+
+/** The process-wide logger. Prefer `ctx.logger` inside a request — it carries the ids. */
+export const logger: Logger = createLogger();

package/src/registrar.ts

@@ -0,0 +1,94 @@
+// Hands a module of primitives to the package that owns them, without a sideways import:
+// `defineApi` in `@ultimat3/action` cannot import `@ultimat3/query`'s `registerQueries` on
+// the same tier, so each owner announces its registrar here at import time and callers ask
+// by kind. Same shape as `defineService` and `registerErrorCodes`.
+
+import { UltimateError } from './errors';
+
+/**
+ * The eight primitives — the framework's whole vocabulary. A registrar exists only for the
+ * kinds registered by module.
+ *
+ * The runtime list is the source and the type derives from it, so the two cannot drift apart.
+ * A ninth entry is a design error, not a feature: a new capability arrives as a FACTORY over an
+ * existing primitive — `llm()` returns an `action` — never as a new kind of thing. That rule is
+ * only real if something fails when it is broken, so `registrar.test.ts` pins this set.
+ */
+export const PRIMITIVE_KINDS = [
+  'action',
+  'entity',
+  'job',
+  'mutator',
+  'policy',
+  'query',
+  'route',
+  'task',
+] as const;
+
+export type PrimitiveKind = (typeof PRIMITIVE_KINDS)[number];
+
+/**
+ * What a registrar hands back: the primitives it actually took, each carrying the name
+ * registration stamped on it. Returning the registered set — rather than nothing — is what lets
+ * a caller build its API map from what registered instead of from what a module exported.
+ */
+export interface RegisteredPrimitive {
+  readonly kind: PrimitiveKind;
+  readonly name: string;
+}
+
+/** `registerActions` / `registerQueries`: export names become primitive names. */
+export type ModuleRegistrar = (
+  module: Readonly<Record<string, unknown>>,
+) => readonly RegisteredPrimitive[];
+
+const registrars = new Map<PrimitiveKind, ModuleRegistrar>();
+
+/**
+ * Announce the registrar for `kind`, once per process. Re-announcing the same function is a
+ * no-op (a module re-evaluated under a different specifier); announcing a *different* one
+ * means two copies of the owning package are loaded, each with its own registry — half the
+ * primitives would register into a table nothing else reads.
+ */
+export function registerPrimitiveRegistrar(kind: PrimitiveKind, registrar: ModuleRegistrar): void {
+  const existing = registrars.get(kind);
+  if (existing !== undefined && existing !== registrar) {
+    throw new UltimateError({
+      code: 'X_REGISTRAR_CONFLICT',
+      cause: `two different ${kind} registrars are loaded, so ${kind} primitives would split across two registries`,
+      // One command, because a `fix:` is pasted verbatim: collapsing every range on the package
+      // to one resolved version is the repair. `bun pm why @ultimat3/<kind>` names the dependents
+      // when a range genuinely disagrees and the update cannot converge on its own.
+      fix: `bun update @ultimat3/${kind}`,
+      meta: { kind },
+    });
+  }
+  registrars.set(kind, registrar);
+}
+
+export function hasPrimitiveRegistrar(kind: PrimitiveKind): boolean {
+  return registrars.has(kind);
+}
+
+/**
+ * The registrar for `kind`. Throws rather than returning `undefined`: a caller that skipped a
+ * missing registrar would drop every primitive of that kind silently, which is exactly the
+ * failure this seam exists to make impossible.
+ */
+export function primitiveRegistrar(kind: PrimitiveKind): ModuleRegistrar {
+  const registrar = registrars.get(kind);
+  if (registrar === undefined) {
+    throw new UltimateError({
+      code: 'X_REGISTRAR_MISSING',
+      cause: `no ${kind} registrar is loaded, so ${kind} primitives cannot be registered`,
+      fix: `bun add @ultimat3/${kind}`,
+      meta: { kind },
+    });
+  }
+  return registrar;
+}
+
+/** Test-only. Production announces once at import and never withdraws. */
+export function resetPrimitiveRegistrars(): void {
+  registrars.clear();
+}

package/src/result.ts

@@ -0,0 +1,78 @@
+// Single responsibility: `Result<T, E>` for boundaries where throwing is wrong —
+// validation seams, driver probes, CLI commands that must render `--json` either way.
+
+import { toUltimateError, type UltimateError } from './errors';
+
+export interface Ok<T> {
+  readonly ok: true;
+  readonly value: T;
+}
+
+export interface Err<E> {
+  readonly ok: false;
+  readonly error: E;
+}
+
+export type Result<T, E = UltimateError> = Ok<T> | Err<E>;
+
+export function ok<T>(value: T): Ok<T> {
+  return { ok: true, value };
+}
+
+export function err<E>(error: E): Err<E> {
+  return { ok: false, error };
+}
+
+export function isOk<T, E>(result: Result<T, E>): result is Ok<T> {
+  return result.ok;
+}
+
+export function isErr<T, E>(result: Result<T, E>): result is Err<E> {
+  return !result.ok;
+}
+
+export function map<T, E, U>(result: Result<T, E>, fn: (value: T) => U): Result<U, E> {
+  return result.ok ? ok(fn(result.value)) : result;
+}
+
+export function mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F> {
+  return result.ok ? result : err(fn(result.error));
+}
+
+export function unwrapOr<T, E>(result: Result<T, E>, fallback: T): T {
+  return result.ok ? result.value : fallback;
+}
+
+/** Throws the contained error — use only where a throw is genuinely correct. */
+export function unwrap<T, E>(result: Result<T, E>): T {
+  if (result.ok) return result.value;
+  throw toUltimateError(result.error);
+}
+
+export function tryCatch<T>(fn: () => Promise<T>): Promise<Result<T, UltimateError>>;
+export function tryCatch<T>(fn: () => T): Result<T, UltimateError>;
+export function tryCatch<T>(
+  fn: () => T | Promise<T>,
+): Result<T, UltimateError> | Promise<Result<T, UltimateError>> {
+  try {
+    const value = fn();
+    if (isPromiseLike(value)) {
+      return value.then(
+        (resolved) => ok(resolved),
+        (reason: unknown) => err(toUltimateError(reason)),
+      );
+    }
+    return ok(value);
+  } catch (thrown) {
+    return err(toUltimateError(thrown));
+  }
+}
+
+function isPromiseLike<T>(value: T | Promise<T>): value is Promise<T> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'then' in value &&
+    typeof (value as { then: unknown }).then === 'function'
+  );
+}