@ultimat3/core 1.0.0

package/src/roles.ts

@@ -0,0 +1,66 @@
+// Single responsibility: the runtime role table. One image, N processes; `ROLE` selects
+// behaviour. Every role exposes /healthz + /readyz and drains on SIGTERM.
+
+import { UltimateError } from './errors';
+
+export const ROLES = ['web', 'sync', 'worker', 'scheduler', 'migrate', 'replicator'] as const;
+
+export type Role = (typeof ROLES)[number];
+
+export const DEFAULT_ROLE: Role = 'web';
+
+/** What each role scales on — machine-readable, so `x deploy` can emit sane defaults. */
+export type ScalingSignal =
+  | 'rps'
+  | 'ws-connections'
+  | 'queue-depth'
+  | 'singleton'
+  | 'run-once'
+  | 'per-database';
+
+export interface RoleInfo {
+  readonly role: Role;
+  readonly scalesOn: ScalingSignal;
+  /** Hard replica ceiling, when the role must not be scaled horizontally. */
+  readonly maxReplicas: number | null;
+  readonly stateful: boolean;
+}
+
+export const ROLE_INFO: Readonly<Record<Role, RoleInfo>> = Object.freeze({
+  web: { role: 'web', scalesOn: 'rps', maxReplicas: null, stateful: false },
+  sync: { role: 'sync', scalesOn: 'ws-connections', maxReplicas: null, stateful: false },
+  worker: { role: 'worker', scalesOn: 'queue-depth', maxReplicas: null, stateful: false },
+  scheduler: { role: 'scheduler', scalesOn: 'singleton', maxReplicas: 1, stateful: false },
+  migrate: { role: 'migrate', scalesOn: 'run-once', maxReplicas: 1, stateful: false },
+  replicator: { role: 'replicator', scalesOn: 'per-database', maxReplicas: 1, stateful: true },
+});
+
+export function isRole(value: unknown): value is Role {
+  return typeof value === 'string' && (ROLES as readonly string[]).includes(value);
+}
+
+export interface ResolveRoleOptions {
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  readonly key?: string | undefined;
+  readonly fallback?: Role | undefined;
+}
+
+/**
+ * Read the role from the environment. Unset means `web` (the common case); a set-but-unknown
+ * value is always a mistake and throws `X_ROLE_INVALID`.
+ */
+export function resolveRole(options?: ResolveRoleOptions): Role {
+  const key = options?.key ?? 'ROLE';
+  const source = options?.env ?? (process.env as Record<string, string | undefined>);
+  const raw = source[key];
+  if (raw === undefined || raw === '') return options?.fallback ?? DEFAULT_ROLE;
+  if (!isRole(raw)) {
+    throw new UltimateError({
+      code: 'X_ROLE_INVALID',
+      cause: `${key}="${raw}" is not one of ${ROLES.join(' | ')}`,
+      fix: `set ${key} to one of: ${ROLES.join(', ')}`,
+      meta: { key, received: raw, allowed: ROLES },
+    });
+  }
+  return raw;
+}

package/src/service.ts

@@ -0,0 +1,61 @@
+// Single responsibility: named service factories that `createContext` installs automatically,
+// bound to the exact ctx (actor, clock, tz) they were built for.
+//
+// A service closes over the `ctx` it was constructed with — `ctx.actor.orgId` inside it means
+// "the actor this service was built for", not "whoever is calling right now". So a factory
+// cannot be built once and cached: it has to run again every time `createContext` produces a
+// ctx with a different actor, or an impersonated call would read the wrong tenant. Registering
+// with `defineService` is what lets `createContext` do that automatically instead of every
+// caller wiring `services: { posts: postsService(ctx) }` by hand at every call site.
+
+import type { Ctx, ServiceBag } from './context';
+import { UltimateError } from './errors';
+
+export type ServiceFactory<T = unknown> = (ctx: Ctx) => T;
+
+const factories = new Map<string, ServiceFactory>();
+
+/**
+ * Register a named service factory, once per app boot — importing the module that calls this
+ * IS the registration, the same convention `registerActions` uses. Returns the factory
+ * unchanged, so `export const postsService = defineService('posts', (ctx) => ({...}))` still
+ * exports a plain callable a test can invoke directly, without going through a context at all.
+ */
+export function defineService<T>(name: string, factory: ServiceFactory<T>): ServiceFactory<T> {
+  if (factories.has(name)) {
+    throw new UltimateError({
+      code: 'X_SERVICE_DUPLICATE',
+      cause: `a service named "${name}" is already registered`,
+      fix: `rename one of the two defineService('${name}', ...) declarations`,
+      meta: { name },
+    });
+  }
+  factories.set(name, factory as ServiceFactory);
+  return factory;
+}
+
+/**
+ * Whether `name` is a registered factory. `withChildContext` uses this so an impersonated
+ * child never carries forward a parent's instance built for a different actor — only ad hoc
+ * services nobody registered (a test's hand-built mock) survive the swap unrebuilt.
+ */
+export function isManagedService(name: string): boolean {
+  return factories.has(name);
+}
+
+/**
+ * Every registered factory, called fresh against `ctx`. `ctx` carries no other registered
+ * service yet — a factory reads the ambient actor/clock/tz, never a sibling service, so
+ * factories cannot depend on one another's instances.
+ */
+export function installedServices(ctx: Ctx): ServiceBag {
+  if (factories.size === 0) return {};
+  const bag: Record<string, unknown> = {};
+  for (const [name, factory] of factories) bag[name] = factory(ctx);
+  return Object.freeze(bag);
+}
+
+/** Test-only. Production registers once at boot and never unregisters. */
+export function resetServices(): void {
+  factories.clear();
+}

package/src/telemetry.ts

@@ -0,0 +1,290 @@
+// Single responsibility: OpenTelemetry-shaped tracing that is always on. The default exporter
+// is a no-op so unconfigured apps pay nothing, and trace context is serialised explicitly
+// (`traceparent`) so a trace survives HTTP -> job -> live query.
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { type Clock, systemClock } from './clock';
+import { tryUseContext } from './context';
+import { isUltimateError } from './errors';
+import { spanId as newSpanId, traceId as newTraceId } from './ids';
+
+export type SpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer';
+
+export type AttributeValue = string | number | boolean | readonly string[] | readonly number[];
+
+export interface SpanAttributes {
+  readonly [key: string]: AttributeValue;
+}
+
+export interface SpanContext {
+  readonly traceId: string;
+  readonly spanId: string;
+  /** Bit 0 = sampled, per W3C trace-context. */
+  readonly traceFlags: number;
+}
+
+export interface SpanEvent {
+  readonly name: string;
+  readonly at: number;
+  readonly attributes: SpanAttributes;
+}
+
+export type SpanStatusCode = 'unset' | 'ok' | 'error';
+
+export interface SpanStatus {
+  readonly code: SpanStatusCode;
+  readonly message?: string | undefined;
+}
+
+export interface ReadableSpan {
+  readonly name: string;
+  readonly kind: SpanKind;
+  readonly context: SpanContext;
+  readonly parentSpanId: string | undefined;
+  /** Epoch milliseconds. */
+  readonly startedAt: number;
+  readonly endedAt: number;
+  readonly durationMs: number;
+  readonly attributes: SpanAttributes;
+  readonly events: readonly SpanEvent[];
+  readonly status: SpanStatus;
+  readonly links: readonly SpanContext[];
+  readonly resource: SpanResource;
+}
+
+export interface SpanResource {
+  readonly serviceName: string;
+  readonly serviceVersion: string;
+}
+
+export interface Span {
+  readonly name: string;
+  readonly context: SpanContext;
+  readonly ended: boolean;
+  setAttribute(key: string, value: AttributeValue): Span;
+  setAttributes(attributes: SpanAttributes): Span;
+  addEvent(name: string, attributes?: SpanAttributes): Span;
+  recordError(error: unknown): Span;
+  setStatus(code: SpanStatusCode, message?: string): Span;
+  end(): void;
+}
+
+export interface SpanExporter {
+  export(span: ReadableSpan): void;
+}
+
+export interface StartSpanOptions {
+  readonly kind?: SpanKind | undefined;
+  readonly attributes?: SpanAttributes | undefined;
+  /** Explicit parent. Falls back to the active span, then to the request context's traceId. */
+  readonly parent?: SpanContext | undefined;
+  readonly links?: readonly SpanContext[] | undefined;
+}
+
+export interface TelemetryOptions {
+  readonly exporter?: SpanExporter | undefined;
+  readonly clock?: Clock | undefined;
+  readonly serviceName?: string | undefined;
+  readonly serviceVersion?: string | undefined;
+  readonly enabled?: boolean | undefined;
+}
+
+export const noopExporter: SpanExporter = Object.freeze({
+  export(): void {
+    // Intentionally empty: tracing is always on, and free until an exporter is configured.
+  },
+});
+
+export interface MemoryExporter extends SpanExporter {
+  readonly spans: readonly ReadableSpan[];
+  reset(): void;
+}
+
+/** For tests and for `x trace --json`. */
+export function memoryExporter(): MemoryExporter {
+  const spans: ReadableSpan[] = [];
+  return {
+    spans,
+    export(span: ReadableSpan): void {
+      spans.push(span);
+    },
+    reset(): void {
+      spans.length = 0;
+    },
+  };
+}
+
+const activeSpan = new AsyncLocalStorage<Span>();
+
+let exporter: SpanExporter = noopExporter;
+let clock: Clock = systemClock;
+let enabled = true;
+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.serviceName !== undefined || options.serviceVersion !== undefined) {
+    resource = Object.freeze({
+      serviceName: options.serviceName ?? resource.serviceName,
+      serviceVersion: options.serviceVersion ?? resource.serviceVersion,
+    });
+  }
+}
+
+export function resetTelemetry(): void {
+  exporter = noopExporter;
+  clock = systemClock;
+  enabled = true;
+}
+
+export function currentSpan(): Span | undefined {
+  return activeSpan.getStore();
+}
+
+/** The trace the caller is inside: active span, else the request context, else a fresh trace. */
+export function currentSpanContext(): SpanContext | undefined {
+  const span = activeSpan.getStore();
+  if (span !== undefined) return span.context;
+  const ctx = tryUseContext();
+  if (ctx === undefined) return undefined;
+  return { traceId: ctx.traceId, spanId: '', traceFlags: 1 };
+}
+
+export function startSpan(name: string, options?: StartSpanOptions): Span {
+  const parent = options?.parent ?? currentSpanContext();
+  const context: SpanContext = {
+    traceId: parent?.traceId ?? newTraceId(),
+    spanId: newSpanId(),
+    traceFlags: parent?.traceFlags ?? 1,
+  };
+  const attributes: Record<string, AttributeValue> = { ...(options?.attributes ?? {}) };
+  const events: SpanEvent[] = [];
+  const startedAt = clock.now().getTime();
+  const startedMono = clock.monotonic();
+  let status: SpanStatus = { code: 'unset' };
+  let ended = false;
+
+  const span: Span = {
+    name,
+    context,
+    get ended(): boolean {
+      return ended;
+    },
+    setAttribute(key, value) {
+      attributes[key] = value;
+      return span;
+    },
+    setAttributes(next) {
+      for (const [key, value] of Object.entries(next)) attributes[key] = value;
+      return span;
+    },
+    addEvent(eventName, eventAttributes) {
+      events.push({
+        name: eventName,
+        at: clock.now().getTime(),
+        attributes: eventAttributes ?? {},
+      });
+      return span;
+    },
+    recordError(error) {
+      const code = isUltimateError(error) ? error.code : 'X_INTERNAL';
+      const message = error instanceof Error ? error.message : String(error);
+      events.push({
+        name: 'exception',
+        at: clock.now().getTime(),
+        attributes: { 'error.code': code, 'error.message': message },
+      });
+      status = { code: 'error', message };
+      return span;
+    },
+    setStatus(code, message) {
+      status = { code, message };
+      return span;
+    },
+    end(): void {
+      if (ended) return;
+      ended = true;
+      if (!enabled) return;
+      const endedAt = clock.now().getTime();
+      const parentSpanId = parent === undefined || parent.spanId === '' ? undefined : parent.spanId;
+      exporter.export({
+        name,
+        kind: options?.kind ?? 'internal',
+        context,
+        parentSpanId,
+        startedAt,
+        endedAt,
+        durationMs: clock.monotonic() - startedMono,
+        attributes,
+        events,
+        status,
+        links: options?.links ?? [],
+        resource,
+      });
+    },
+  };
+  return span;
+}
+
+/** Runs `fn` inside a span, ending it on return, resolve or throw. Sync and async both work. */
+export function withSpan<T>(name: string, fn: (span: Span) => T, options?: StartSpanOptions): T {
+  const span = startSpan(name, options);
+  return activeSpan.run(span, () => {
+    try {
+      const result = fn(span);
+      if (isPromiseLike(result)) {
+        return result.then(
+          (value) => {
+            span.end();
+            return value;
+          },
+          (reason: unknown) => {
+            span.recordError(reason);
+            span.end();
+            throw reason;
+          },
+        ) as unknown as T;
+      }
+      span.end();
+      return result;
+    } catch (thrown) {
+      span.recordError(thrown);
+      span.end();
+      throw thrown;
+    }
+  });
+}
+
+/** Continue an inbound trace. The HTTP, job and realtime layers all call this. */
+export function withSpanContext<T>(context: SpanContext, name: string, fn: (span: Span) => T): T {
+  return withSpan(name, fn, { parent: context });
+}
+
+const TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+
+export function traceparent(context: SpanContext): string {
+  const flags = context.traceFlags.toString(16).padStart(2, '0');
+  return `00-${context.traceId}-${context.spanId}-${flags}`;
+}
+
+export function parseTraceparent(header: string | null | undefined): SpanContext | undefined {
+  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),
+  };
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'then' in value &&
+    typeof (value as { then: unknown }).then === 'function'
+  );
+}

package/src/version.ts

@@ -0,0 +1,37 @@
+// The one version string the framework reports — MCP `serverInfo`, `x --version`, the deps a
+// scaffold pins. Read from this package's OWN package.json, never the workspace root: the root
+// 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';
+// 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 { UltimateError } from './errors';
+
+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');
+
+/**
+ * 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.
+ */
+export function readPackageVersion(manifestPath: string): string {
+  const raw: unknown = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+  const version =
+    typeof raw === 'object' && raw !== null ? (raw as { version?: unknown }).version : undefined;
+  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)})`,
+      fix: `set a semver "version" in ${manifestPath}, then re-run: bun run verify`,
+    });
+  }
+  return version;
+}
+
+export const FRAMEWORK_VERSION: string = readPackageVersion(VERSION_MANIFEST);