@arki/dot 0.1.1 → 0.1.3

package/src/kernel/otel.ts

@@ -0,0 +1,265 @@
+/**
+ * OpenTelemetry instrumentation for the DOT kernel.
+ *
+ * DOT is OTel-first: every lifecycle phase and every per-pip hook
+ * automatically emits a span and a duration histogram. When no SDK is
+ * registered, the OTel API returns no-op implementations and the kernel
+ * pays zero allocation per call — the discipline that makes "OTel-first"
+ * compatible with principle 5 (zero optional dependencies in the kernel).
+ *
+ * Consumers wire the SDK however they like (`@opentelemetry/sdk-node`,
+ * `@arki/meter`, etc.); the kernel never touches the SDK directly.
+ *
+ * Span / attribute conventions:
+ *
+ *   - Phase span: `dot.app.<phase>` — one root span per `configure()` /
+ *     `boot()` / `start()` / `stop()` / `dispose()` call. Children
+ *     auto-link via async-context.
+ *   - Hook span:  `dot.pip.<hook>` — one child span per pip's hook
+ *     execution. The pip name lives on `dot.pip.name`, not in the span
+ *     name, so backends can aggregate by hook across pips.
+ *   - Attributes (`dot.app.name`, `dot.pip.name`, `dot.pip.version`,
+ *     `dot.hook`, `dot.pip.order`) follow the OTel convention of
+ *     namespacing under the library's prefix.
+ *
+ * @see packages/dot/docs/principles.md — principle 3 (deterministic) +
+ *      principle 4 (agent-discoverable).
+ */
+
+import { metrics, SpanStatusCode, trace, type Span } from '@opentelemetry/api';
+import type { Logger } from '@arki/log';
+
+import type { DotLifecycleHook } from '../lifecycle.js';
+
+const INSTRUMENTATION_NAME = '@arki/dot';
+const INSTRUMENTATION_VERSION = '0.1.0';
+
+/** OTel tracer for the DOT kernel. No-op when no SDK is registered. */
+export const tracer = trace.getTracer(INSTRUMENTATION_NAME, INSTRUMENTATION_VERSION);
+
+/** OTel meter for the DOT kernel. No-op when no SDK is registered. */
+export const meter = metrics.getMeter(INSTRUMENTATION_NAME, INSTRUMENTATION_VERSION);
+
+/**
+ * Histogram recording per-pip per-hook execution duration in milliseconds.
+ *
+ * Attributes:
+ *   - `dot.app.name` — app name
+ *   - `dot.pip.name` — pip name
+ *   - `dot.hook`     — which lifecycle hook (`configure` | `boot` | ...)
+ *   - `dot.status`   — `ok` | `failed`
+ */
+export const hookDurationHistogram = meter.createHistogram('dot.pip.hook.duration', {
+  description: 'Wall-clock duration of a single pip lifecycle hook execution.',
+  unit: 'ms',
+});
+
+/**
+ * Histogram recording per-phase (app-level) execution duration.
+ *
+ * Attributes:
+ *   - `dot.app.name`  — app name
+ *   - `dot.app.phase` — which phase (`configure` | `boot` | `start` | `stop` | `dispose`)
+ *   - `dot.status`    — `ok` | `failed`
+ */
+export const phaseDurationHistogram = meter.createHistogram('dot.app.phase.duration', {
+  description: 'Wall-clock duration of a complete app-level lifecycle phase.',
+  unit: 'ms',
+});
+
+/**
+ * Sanitize attribute values — OTel rejects `undefined` and strips out
+ * keys whose values aren't primitives or arrays of primitives. We drop
+ * `undefined` here so call sites can pass optional fields without
+ * branching.
+ */
+function attrs(
+  source: Readonly<Record<string, string | number | boolean | undefined>>,
+): Record<string, string | number | boolean> {
+  const out: Record<string, string | number | boolean> = {};
+  for (const [k, v] of Object.entries(source)) {
+    if (v !== undefined) out[k] = v;
+  }
+  return out;
+}
+
+/** Stringify any thrown value for span status / exception recording. */
+function stringifyForSpan(value: unknown): string {
+  if (value instanceof Error) return value.message;
+  if (typeof value === 'string') return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * Wrap a single pip-hook execution in a child span and record its
+ * duration in the histogram. The span auto-links to the active phase
+ * span (set by {@link withPhaseSpan}) so traces show a clean parent-child
+ * hierarchy:
+ *
+ *     dot.app.boot
+ *     ├── dot.pip.boot   (dot.pip.name=env, dot.hook=boot)
+ *     ├── dot.pip.boot   (dot.pip.name=db,  dot.hook=boot)
+ *     └── dot.pip.boot   (dot.pip.name=kv,  dot.hook=boot)
+ *
+ * Re-throws on failure after marking the span ERROR so the caller's
+ * existing error-handling path stays intact.
+ */
+export function withPipHookSpan<R>(
+  opts: {
+    readonly appName: string;
+    readonly pipName: string;
+    readonly pipVersion?: string;
+    readonly hook: DotLifecycleHook;
+    readonly order: number;
+    /**
+     * Optional pip-scoped logger. When present, the helper threads the
+     * span's `traceId` + `spanId` onto the logger via `setTraceContext`
+     * before invoking the body — every log line emitted from within the
+     * pip's hook is automatically correlated with this span in the
+     * `traceId`/`spanId` fields of `LogRecord`.
+     */
+    readonly logger?: Logger;
+  },
+  fn: (span: Span) => R,
+): R {
+  const span = tracer.startSpan(`dot.pip.${opts.hook}`, {
+    attributes: attrs({
+      'dot.app.name': opts.appName,
+      'dot.pip.name': opts.pipName,
+      'dot.pip.version': opts.pipVersion,
+      'dot.hook': opts.hook,
+      'dot.pip.order': opts.order,
+    }),
+  });
+  if (opts.logger) {
+    const sc = span.spanContext();
+    opts.logger.setTraceContext(sc.traceId, sc.spanId);
+  }
+  const started = performance.now();
+  let status: 'ok' | 'failed' = 'ok';
+  const finish = (): void => {
+    const durationMs = performance.now() - started;
+    hookDurationHistogram.record(durationMs, {
+      'dot.app.name': opts.appName,
+      'dot.pip.name': opts.pipName,
+      'dot.hook': opts.hook,
+      'dot.status': status,
+    });
+    span.end();
+  };
+  try {
+    const result = fn(span);
+    if (result instanceof Promise) {
+      return result.then(
+        v => {
+          span.setStatus({ code: SpanStatusCode.OK });
+          finish();
+          return v;
+        },
+        (e: unknown) => {
+          status = 'failed';
+          span.setStatus({ code: SpanStatusCode.ERROR, message: stringifyForSpan(e) });
+          if (e instanceof Error) span.recordException(e);
+          finish();
+          throw e;
+        },
+      ) as R;
+    }
+    span.setStatus({ code: SpanStatusCode.OK });
+    finish();
+    return result;
+  } catch (e) {
+    status = 'failed';
+    span.setStatus({ code: SpanStatusCode.ERROR, message: stringifyForSpan(e) });
+    if (e instanceof Error) span.recordException(e);
+    finish();
+    throw e;
+  }
+}
+
+/**
+ * Wrap an entire app-level phase (`configure`/`boot`/`start`/`stop`/`dispose`)
+ * in an active span. Children created by {@link withPipHookSpan} inherit
+ * this span as their parent via async-context.
+ *
+ * The callback's return value (sync or Promise) is propagated unchanged
+ * to preserve the kernel's existing control flow.
+ */
+export function withPhaseSpan<R>(
+  opts: {
+    readonly appName: string;
+    readonly appVersion?: string;
+    readonly phase: DotLifecycleHook;
+    readonly pipCount: number;
+    /**
+     * Optional phase-scoped logger. When present, the helper threads
+     * the span's `traceId` + `spanId` onto the logger before invoking
+     * the body — every log line written during the phase carries the
+     * trace context so it's groupable with the corresponding span in
+     * any OTel-compatible backend.
+     */
+    readonly logger?: Logger;
+  },
+  fn: (span: Span) => R,
+): R {
+  return tracer.startActiveSpan(
+    `dot.app.${opts.phase}`,
+    {
+      attributes: attrs({
+        'dot.app.name': opts.appName,
+        'dot.app.version': opts.appVersion,
+        'dot.app.phase': opts.phase,
+        'dot.app.pip.count': opts.pipCount,
+      }),
+    },
+    (span): R => {
+      if (opts.logger) {
+        const sc = span.spanContext();
+        opts.logger.setTraceContext(sc.traceId, sc.spanId);
+      }
+      const started = performance.now();
+      let status: 'ok' | 'failed' = 'ok';
+      const finish = (): void => {
+        const durationMs = performance.now() - started;
+        phaseDurationHistogram.record(durationMs, {
+          'dot.app.name': opts.appName,
+          'dot.app.phase': opts.phase,
+          'dot.status': status,
+        });
+        span.end();
+      };
+      try {
+        const result = fn(span);
+        if (result instanceof Promise) {
+          return result.then(
+            v => {
+              span.setStatus({ code: SpanStatusCode.OK });
+              finish();
+              return v;
+            },
+            (e: unknown) => {
+              status = 'failed';
+              span.setStatus({ code: SpanStatusCode.ERROR, message: stringifyForSpan(e) });
+              if (e instanceof Error) span.recordException(e);
+              finish();
+              throw e;
+            },
+          ) as R;
+        }
+        span.setStatus({ code: SpanStatusCode.OK });
+        finish();
+        return result;
+      } catch (e) {
+        status = 'failed';
+        span.setStatus({ code: SpanStatusCode.ERROR, message: stringifyForSpan(e) });
+        if (e instanceof Error) span.recordException(e);
+        finish();
+        throw e;
+      }
+    },
+  );
+}

package/src/lifecycle-observer.ts

@@ -0,0 +1,100 @@
+/**
+ * Lifecycle observer surface for the DOT kernel.
+ *
+ * `DotLifecycleObserver` is the in-process companion to the OTel signals
+ * emitted by {@link withPhaseSpan} / {@link withPipHookSpan}. Where OTel
+ * is the contract for cross-process tracing (consumers register an SDK
+ * and ship spans to a backend), the observer is the contract for *local*
+ * programmatic inspection — used by tests, CLI tooling, ASCII waterfalls,
+ * and ad-hoc diagnostics that don't require an SDK to be registered.
+ *
+ * Both signals are emitted from the same kernel sites; neither is layered
+ * under the other. A consumer can use one, both, or neither — the kernel
+ * pays zero allocation for the observer fan-out when no observers are
+ * registered.
+ *
+ * @see packages/dot/docs/observability.md — consumer-facing surface
+ * @see packages/dot/docs/principles.md — principle 5 (zero optional deps)
+ */
+
+import type { DotLifecycleHook } from './lifecycle.js';
+
+/**
+ * The single fan-out event type emitted by the kernel to every registered
+ * observer. Discriminated by `kind`:
+ *
+ *   - `'phase'`     — boundary of a top-level lifecycle phase
+ *   - `'pip-hook'`  — boundary of a single pip's hook execution
+ *
+ * Status discriminates the boundary itself:
+ *
+ *   - `'starting'`  — emitted *before* the work begins
+ *   - `'completed'` — emitted *after* the work finished successfully
+ *   - `'failed'`    — emitted *after* the work threw or rejected
+ *
+ * `starting` events never carry `durationMs` / `error`. `completed` events
+ * carry `durationMs`. `failed` events carry both `durationMs` and `error`.
+ */
+export type DotLifecycleEvent = DotPhaseLifecycleEvent | DotPipHookLifecycleEvent;
+
+/** Possible event statuses. See {@link DotLifecycleEvent}. */
+export type DotLifecycleEventStatus = 'starting' | 'completed' | 'failed';
+
+/** Boundary of a top-level lifecycle phase. */
+export type DotPhaseLifecycleEvent = {
+  readonly kind: 'phase';
+  /** The phase the event belongs to. */
+  readonly phase: DotLifecycleHook;
+  readonly status: DotLifecycleEventStatus;
+  /** App name (so multiplexed observers can disambiguate). */
+  readonly appName: string;
+  /** Wall-clock duration in milliseconds. Present on `completed` / `failed`. */
+  readonly durationMs?: number;
+  /** The error value, if `status === 'failed'`. */
+  readonly error?: unknown;
+  /** Wall-clock timestamp in ms-since-epoch (`Date.now()` semantics). */
+  readonly timestamp: number;
+};
+
+/** Boundary of a single pip's hook execution. */
+export type DotPipHookLifecycleEvent = {
+  readonly kind: 'pip-hook';
+  /** The phase the hook belongs to. */
+  readonly phase: DotLifecycleHook;
+  /** The pip whose hook is being executed. */
+  readonly pip: string;
+  /** Topological order of the pip within the phase (0-based). */
+  readonly order: number;
+  readonly status: DotLifecycleEventStatus;
+  readonly appName: string;
+  readonly durationMs?: number;
+  readonly error?: unknown;
+  readonly timestamp: number;
+};
+
+/**
+ * Observer function signature. Synchronous by contract — observers MUST
+ * NOT block the lifecycle. If a long-running side effect is needed
+ * (e.g. shipping events to a remote sink), the observer should buffer
+ * the event and process it on a separate cadence.
+ *
+ * Exceptions thrown by an observer are caught and dropped on the kernel
+ * floor (with a DEBUG log on `arki:dot:lifecycle`). One observer's
+ * misbehaviour can never cause another observer to miss an event, nor
+ * can it break the lifecycle.
+ *
+ * @example
+ * ```ts
+ * import { defineApp } from '@arki/dot';
+ *
+ * const events: DotLifecycleEvent[] = [];
+ * const app = await defineApp('my-app', {
+ *   observers: [(event) => events.push(event)],
+ * })
+ *   .use(myPip)
+ *   .boot();
+ *
+ * // events now contains the full configure + boot event stream.
+ * ```
+ */
+export type DotLifecycleObserver = (event: DotLifecycleEvent) => void;

package/src/lifecycle.ts

@@ -0,0 +1,123 @@
+/**
+ * Lifecycle primitives for the DOT kernel.
+ *
+ * The kernel uses a 5-hook lifecycle that runs in declaration order
+ * (providers are `.use()`d before their consumers — the app builder's
+ * type-level guard enforces this at compile time):
+ *
+ *  - `configure` — synchronous registration of metadata, routes, services
+ *  - `boot`       — async open of resources, publishes services into `app.services`
+ *  - `start`      — async start of active work (workers, schedulers, listeners)
+ *  - `stop`       — async stop of active work, runs in reverse declaration order
+ *  - `dispose`    — async release of booted resources, runs in reverse declaration order
+ *
+ * Hook semantics, failure ordering, and idempotency rules are documented on the
+ * public `DotApp` interface in `./define-app.ts`.
+ */
+
+/** Identifier of a single hook in the DOT lifecycle. */
+export type DotLifecycleHook = 'configure' | 'boot' | 'start' | 'stop' | 'dispose';
+
+/**
+ * The complete set of lifecycle hooks in execution order.
+ * `stop` and `dispose` run in reverse declaration order across pips, but the
+ * sequence of hooks themselves is always `configure -> boot -> start -> stop -> dispose`.
+ */
+export const DOT_LIFECYCLE_HOOKS: readonly DotLifecycleHook[] = [
+  'configure',
+  'boot',
+  'start',
+  'stop',
+  'dispose',
+] as const;
+
+/**
+ * Macro-states the DotApp can occupy.
+ *
+ * State transitions:
+ *
+ *   defined -> configured -> booted -> started -> stopped -> disposed
+ *                                                 |
+ *                                                 +-> disposed (skip stopped if never started)
+ *
+ *   any-of(configure|boot|start) failure -> failed
+ *
+ * `failed` and `disposed` are terminal — callers must create a new instance.
+ */
+export type DotLifecycleState = 'defined' | 'configured' | 'booted' | 'started' | 'stopped' | 'disposed' | 'failed';
+
+/** Stable error codes for lifecycle failures. */
+export const DotLifecycleErrorCode = {
+  /** A `configure` hook attempted async work (returned a Promise). */
+  ConfigureAsync: 'DOT_LIFECYCLE_E001',
+  /** A `configure` hook threw. */
+  ConfigureFailed: 'DOT_LIFECYCLE_E002',
+  /** A `boot` hook threw. */
+  BootFailed: 'DOT_LIFECYCLE_E003',
+  /** A `start` hook threw. */
+  StartFailed: 'DOT_LIFECYCLE_E004',
+  /** One or more `stop` hooks threw — aggregate. */
+  StopFailed: 'DOT_LIFECYCLE_E005',
+  /** One or more `dispose` hooks threw — aggregate. */
+  DisposeFailed: 'DOT_LIFECYCLE_E006',
+  /** Caller tried to reuse the app after dispose. */
+  ReuseAfterDispose: 'DOT_LIFECYCLE_E007',
+  /** Caller tried to reuse the app after a failed lifecycle. */
+  ReuseAfterFailure: 'DOT_LIFECYCLE_E008',
+  // E009 (DependencyCycle) and E010 (MissingDependency) are RETIRED with the
+  // v2 wiring model — declaration order is boot order, so cycles and
+  // name-based dependency declarations no longer exist. Codes are never
+  // reused for new meanings.
+  /** Pip registered twice. */
+  DuplicatePip: 'DOT_LIFECYCLE_E011',
+  /** A pip's `needs` entry has no provider among earlier-booted pips. */
+  UnsatisfiedNeed: 'DOT_LIFECYCLE_E012',
+  /** A pip published a wire key that an earlier pip already provides. */
+  ServiceCollision: 'DOT_LIFECYCLE_E013',
+  /** A needs alias, publish key, or rename target uses the reserved `$` prefix. */
+  ReservedServiceKey: 'DOT_LIFECYCLE_E014',
+} as const;
+
+export type DotLifecycleErrorCodeValue = (typeof DotLifecycleErrorCode)[keyof typeof DotLifecycleErrorCode];
+
+/**
+ * Structured error thrown for any lifecycle failure or misuse.
+ *
+ * Carries:
+ *  - `code`     — stable machine-readable error code (see {@link DotLifecycleErrorCode}).
+ *  - `phase`    — which hook (or pseudo-hook) failed.
+ *  - `pip`   — which pip name, when applicable.
+ *  - `cause`    — original error if wrapped from a hook throw.
+ *  - `failures` — for aggregate errors (stop/dispose), the per-pip failures.
+ */
+export class DotLifecycleError extends Error {
+  readonly code: DotLifecycleErrorCodeValue;
+  readonly phase: DotLifecycleHook;
+  readonly pip?: string;
+  override readonly cause?: unknown;
+  readonly failures?: readonly DotLifecyclePipFailure[];
+
+  constructor(args: {
+    code: DotLifecycleErrorCodeValue;
+    phase: DotLifecycleHook;
+    message: string;
+    pip?: string;
+    cause?: unknown;
+    failures?: readonly DotLifecyclePipFailure[];
+  }) {
+    super(args.message);
+    this.name = 'DotLifecycleError';
+    this.code = args.code;
+    this.phase = args.phase;
+    this.pip = args.pip;
+    this.cause = args.cause;
+    this.failures = args.failures;
+  }
+}
+
+/** Single pip failure inside an aggregate lifecycle error (stop/dispose). */
+export type DotLifecyclePipFailure = {
+  pip: string;
+  phase: DotLifecycleHook;
+  error: unknown;
+};

package/src/manifest.ts

@@ -0,0 +1,94 @@
+/**
+ * Manifest types for the DOT kernel.
+ *
+ * A `DotAppManifest` is the static, declarative description of an app: which
+ * pips are registered, what routes/services they contribute, and how they
+ * depend on each other. It is built up during the `configure` phase from
+ * registration calls and finalised once `configure` completes.
+ *
+ * CONTRACT: `DotAppManifest` always exposes the same five top-level arrays
+ * (`pips`, `routes`, `services`, `lifecycle`, `dependencies`). Consumers
+ * MUST NOT see an omitted array — empty is empty, but never missing.
+ * This shape is referenced by Task 7's scorecard.
+ */
+
+import type { DotLifecycleHook } from './lifecycle.js';
+
+/**
+ * Kind of service that a pip can publish.
+ *
+ * Well-known kinds map 1:1 to the canonical `@arki/*` adapters. `custom`
+ * is the escape hatch for pip-defined service kinds — use it whenever a
+ * pip publishes something that does not fit a reserved shape.
+ */
+export type ServiceKind =
+  | 'env'
+  | 'db'
+  | 'kv'
+  | 'queue'
+  | 'auth'
+  | 'email'
+  | 'logger'
+  | 'event-store'
+  | 'message-bus'
+  | 'custom';
+
+/** Transport that a route is exposed under. */
+export type RouteTransport = 'http' | 'orpc' | 'trpc' | 'rpc' | 'custom';
+
+/** Kind of dependency edge between two pips. */
+export type DependencyEdgeKind = 'requires' | 'provides' | 'uses';
+
+/**
+ * Top-level manifest describing the static shape of a DOT app.
+ *
+ * Always carries the five arrays — never omits any of them.
+ */
+export type DotAppManifest = {
+  app: {
+    name: string;
+    version?: string;
+  };
+  pips: PipManifest[];
+  routes: RouteManifest[];
+  services: ServiceManifest[];
+  lifecycle: LifecycleManifest[];
+  dependencies: DependencyEdge[];
+};
+
+/** Single pip's declarative metadata. */
+export type PipManifest = {
+  name: string;
+  version?: string;
+  dependencies: readonly string[];
+  provides: readonly string[];
+};
+
+/** Single route exposed by a pip. */
+export type RouteManifest = {
+  id: string;
+  pip: string;
+  method?: string;
+  path?: string;
+  transport: RouteTransport;
+};
+
+/** Single service published by a pip. */
+export type ServiceManifest = {
+  name: string;
+  pip: string;
+  kind: ServiceKind;
+};
+
+/** Which lifecycle hooks a pip participates in. */
+export type LifecycleManifest = {
+  pip: string;
+  hooks: readonly DotLifecycleHook[];
+};
+
+/** Directed edge in the pip dependency graph. */
+export type DependencyEdge = {
+  from: string;
+  to: string;
+  kind: DependencyEdgeKind;
+};