@arki/dot 0.3.0 → 0.4.0

package/src/kernel/otel.ts

@@ -1,7 +1,7 @@
 /**
  * OpenTelemetry instrumentation for the DOT kernel.
  *
- * DOT is OTel-first: every lifecycle phase and every per-pip hook
+ * DOT is OTel-first: every lifecycle phase and every per-plugin 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"
@@ -15,11 +15,11 @@
  *   - 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
+ *   - Hook span:  `dot.plugin.<hook>` — one child span per plugin's hook
+ *     execution. The plugin name lives on `dot.plugin.name`, not in the span
+ *     name, so backends can aggregate by hook across plugins.
+ *   - Attributes (`dot.app.name`, `dot.plugin.name`, `dot.plugin.version`,
+ *     `dot.hook`, `dot.plugin.order`) follow the OTel convention of
  *     namespacing under the library's prefix.
  *
  * @see packages/dot/docs/principles.md — principle 3 (deterministic) +
@@ -41,16 +41,16 @@ export const tracer = trace.getTracer(INSTRUMENTATION_NAME, INSTRUMENTATION_VERS
 export const meter = metrics.getMeter(INSTRUMENTATION_NAME, INSTRUMENTATION_VERSION);
 
 /**
- * Histogram recording per-pip per-hook execution duration in milliseconds.
+ * Histogram recording per-plugin per-hook execution duration in milliseconds.
  *
  * Attributes:
  *   - `dot.app.name` — app name
- *   - `dot.pip.name` — pip name
+ *   - `dot.plugin.name` — plugin 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.',
+export const hookDurationHistogram = meter.createHistogram('dot.plugin.hook.duration', {
+  description: 'Wall-clock duration of a single plugin lifecycle hook execution.',
   unit: 'ms',
 });
 
@@ -95,44 +95,44 @@ function stringifyForSpan(value: unknown): string {
 }
 
 /**
- * Wrap a single pip-hook execution in a child span and record its
+ * Wrap a single plugin-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)
+ *     ├── dot.plugin.boot   (dot.plugin.name=env, dot.hook=boot)
+ *     ├── dot.plugin.boot   (dot.plugin.name=db,  dot.hook=boot)
+ *     └── dot.plugin.boot   (dot.plugin.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>(
+export function withPluginHookSpan<R>(
   opts: {
     readonly appName: string;
-    readonly pipName: string;
-    readonly pipVersion?: string;
+    readonly pluginName: string;
+    readonly pluginVersion?: string;
     readonly hook: DotLifecycleHook;
     readonly order: number;
     /**
-     * Optional pip-scoped logger. When present, the helper threads the
+     * Optional plugin-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
+     * plugin'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}`, {
+  const span = tracer.startSpan(`dot.plugin.${opts.hook}`, {
     attributes: attrs({
       'dot.app.name': opts.appName,
-      'dot.pip.name': opts.pipName,
-      'dot.pip.version': opts.pipVersion,
+      'dot.plugin.name': opts.pluginName,
+      'dot.plugin.version': opts.pluginVersion,
       'dot.hook': opts.hook,
-      'dot.pip.order': opts.order,
+      'dot.plugin.order': opts.order,
     }),
   });
   if (opts.logger) {
@@ -145,7 +145,7 @@ export function withPipHookSpan<R>(
     const durationMs = performance.now() - started;
     hookDurationHistogram.record(durationMs, {
       'dot.app.name': opts.appName,
-      'dot.pip.name': opts.pipName,
+      'dot.plugin.name': opts.pluginName,
       'dot.hook': opts.hook,
       'dot.status': status,
     });
@@ -183,7 +183,7 @@ export function withPipHookSpan<R>(
 
 /**
  * Wrap an entire app-level phase (`configure`/`boot`/`start`/`stop`/`dispose`)
- * in an active span. Children created by {@link withPipHookSpan} inherit
+ * in an active span. Children created by {@link withPluginHookSpan} inherit
  * this span as their parent via async-context.
  *
  * The callback's return value (sync or Promise) is propagated unchanged
@@ -194,7 +194,7 @@ export function withPhaseSpan<R>(
     readonly appName: string;
     readonly appVersion?: string;
     readonly phase: DotLifecycleHook;
-    readonly pipCount: number;
+    readonly pluginCount: number;
     /**
      * Optional phase-scoped logger. When present, the helper threads
      * the span's `traceId` + `spanId` onto the logger before invoking
@@ -213,7 +213,7 @@ export function withPhaseSpan<R>(
         'dot.app.name': opts.appName,
         'dot.app.version': opts.appVersion,
         'dot.app.phase': opts.phase,
-        'dot.app.pip.count': opts.pipCount,
+        'dot.app.plugin.count': opts.pluginCount,
       }),
     },
     (span): R => {

package/src/lifecycle-observer.ts

@@ -2,7 +2,7 @@
  * 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
+ * emitted by {@link withPhaseSpan} / {@link withPluginHookSpan}. 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,
@@ -24,7 +24,7 @@ import type { DotLifecycleHook } from './lifecycle.js';
  * observer. Discriminated by `kind`:
  *
  *   - `'phase'`     — boundary of a top-level lifecycle phase
- *   - `'pip-hook'`  — boundary of a single pip's hook execution
+ *   - `'plugin-hook'`  — boundary of a single plugin's hook execution
  *
  * Status discriminates the boundary itself:
  *
@@ -35,7 +35,7 @@ import type { DotLifecycleHook } from './lifecycle.js';
  * `starting` events never carry `durationMs` / `error`. `completed` events
  * carry `durationMs`. `failed` events carry both `durationMs` and `error`.
  */
-export type DotLifecycleEvent = DotPhaseLifecycleEvent | DotPipHookLifecycleEvent;
+export type DotLifecycleEvent = DotPhaseLifecycleEvent | DotPluginHookLifecycleEvent;
 
 /** Possible event statuses. See {@link DotLifecycleEvent}. */
 export type DotLifecycleEventStatus = 'starting' | 'completed' | 'failed';
@@ -56,14 +56,14 @@ export type DotPhaseLifecycleEvent = {
   readonly timestamp: number;
 };
 
-/** Boundary of a single pip's hook execution. */
-export type DotPipHookLifecycleEvent = {
-  readonly kind: 'pip-hook';
+/** Boundary of a single plugin's hook execution. */
+export type DotPluginHookLifecycleEvent = {
+  readonly kind: 'plugin-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). */
+  /** The plugin whose hook is being executed. */
+  readonly plugin: string;
+  /** Topological order of the plugin within the phase (0-based). */
   readonly order: number;
   readonly status: DotLifecycleEventStatus;
   readonly appName: string;
@@ -91,7 +91,7 @@ export type DotPipHookLifecycleEvent = {
  * const app = await defineApp('my-app', {
  *   observers: [(event) => events.push(event)],
  * })
- *   .use(myPip)
+ *   .use(myPlugin)
  *   .boot();
  *
  * // events now contains the full configure + boot event stream.

package/src/lifecycle.ts

@@ -20,7 +20,7 @@ export type DotLifecycleHook = 'configure' | 'boot' | 'start' | 'stop' | 'dispos
 
 /**
  * The complete set of lifecycle hooks in execution order.
- * `stop` and `dispose` run in reverse declaration order across pips, but the
+ * `stop` and `dispose` run in reverse declaration order across plugins, but the
  * sequence of hooks themselves is always `configure -> boot -> start -> stop -> dispose`.
  */
 export const DOT_LIFECYCLE_HOOKS: readonly DotLifecycleHook[] = [
@@ -68,16 +68,20 @@ export const DotLifecycleErrorCode = {
   // 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. */
+  /** Plugin registered twice. */
+  DuplicatePlugin: 'DOT_LIFECYCLE_E011',
+  /** A plugin's `needs` entry has no provider among earlier-booted plugins. */
   UnsatisfiedNeed: 'DOT_LIFECYCLE_E012',
-  /** A pip published a wire key that an earlier pip already provides. */
+  /** A plugin published a wire key that an earlier plugin already provides. */
   ServiceCollision: 'DOT_LIFECYCLE_E013',
   /** A needs alias, publish key, or rename target uses the reserved `$` prefix. */
   ReservedServiceKey: 'DOT_LIFECYCLE_E014',
   /** A lifecycle hook exceeded the app's `hookTimeoutMs` watchdog. */
   HookTimeout: 'DOT_LIFECYCLE_E015',
+  /** Two actions in the same binding use the same id. */
+  DuplicateAction: 'DOT_LIFECYCLE_E016',
+  /** Action metadata is not JSON-round-trip safe. */
+  ActionMetaNotJson: 'DOT_LIFECYCLE_E017',
 } as const;
 
 export type DotLifecycleErrorCodeValue = (typeof DotLifecycleErrorCode)[keyof typeof DotLifecycleErrorCode];
@@ -88,38 +92,38 @@ export type DotLifecycleErrorCodeValue = (typeof DotLifecycleErrorCode)[keyof ty
  * Carries:
  *  - `code`     — stable machine-readable error code (see {@link DotLifecycleErrorCode}).
  *  - `phase`    — which hook (or pseudo-hook) failed.
- *  - `pip`   — which pip name, when applicable.
+ *  - `plugin`   — which plugin name, when applicable.
  *  - `cause`    — original error if wrapped from a hook throw.
- *  - `failures` — for aggregate errors (stop/dispose), the per-pip failures.
+ *  - `failures` — for aggregate errors (stop/dispose), the per-plugin failures.
  */
 export class DotLifecycleError extends Error {
   readonly code: DotLifecycleErrorCodeValue;
   readonly phase: DotLifecycleHook;
-  readonly pip?: string;
+  readonly plugin?: string;
   override readonly cause?: unknown;
-  readonly failures?: readonly DotLifecyclePipFailure[];
+  readonly failures?: readonly DotLifecyclePluginFailure[];
 
   constructor(args: {
     code: DotLifecycleErrorCodeValue;
     phase: DotLifecycleHook;
     message: string;
-    pip?: string;
+    plugin?: string;
     cause?: unknown;
-    failures?: readonly DotLifecyclePipFailure[];
+    failures?: readonly DotLifecyclePluginFailure[];
   }) {
     super(args.message);
     this.name = 'DotLifecycleError';
     this.code = args.code;
     this.phase = args.phase;
-    this.pip = args.pip;
+    this.plugin = args.plugin;
     this.cause = args.cause;
     this.failures = args.failures;
   }
 }
 
-/** Single pip failure inside an aggregate lifecycle error (stop/dispose). */
-export type DotLifecyclePipFailure = {
-  pip: string;
+/** Single plugin failure inside an aggregate lifecycle error (stop/dispose). */
+export type DotLifecyclePluginFailure = {
+  plugin: string;
   phase: DotLifecycleHook;
   error: unknown;
 };

package/src/manifest.ts

@@ -2,24 +2,96 @@
  * 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
+ * plugins are registered, what actions/services/projections 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.
+ * CONTRACT: `DotAppManifest` always exposes the same six top-level arrays
+ * (`plugins`, `actions`, `services`, `lifecycle`, `dependencies`,
+ * `projections`). Consumers MUST NOT see an omitted array — empty is empty,
+ * but never missing.
  */
 
 import type { DotLifecycleHook } from './lifecycle.js';
 
+/** JSON-serializable value — the manifest's currency. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+/** JSON-serializable object used for adapter-owned manifest metadata. */
+export type JsonObject = { [key: string]: JsonValue };
+
+function jsonRoundTrip(value: unknown): unknown {
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(value);
+  } catch (error) {
+    throw new TypeError('Value must be JSON-serializable manifest data.', { cause: error });
+  }
+  if (serialized === undefined) {
+    throw new TypeError('Value must be a JSON-serializable object.');
+  }
+  return JSON.parse(serialized) as unknown;
+}
+
+function isJsonPrimitive(value: unknown): value is string | number | boolean | null {
+  return value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number';
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value) as unknown;
+  return prototype === Object.prototype || prototype === null;
+}
+
+function isJsonValue(value: unknown): value is JsonValue {
+  if (isJsonPrimitive(value)) return typeof value !== 'number' || Number.isFinite(value);
+  if (Array.isArray(value)) return value.every(isJsonValue);
+  if (!isPlainObject(value)) return false;
+  return Object.values(value).every(isJsonValue);
+}
+
+function isJsonObject(value: unknown): value is JsonObject {
+  return isPlainObject(value) && Object.values(value).every(isJsonValue);
+}
+
+function jsonDeepEqual(left: unknown, right: unknown): boolean {
+  if (isJsonPrimitive(left) || isJsonPrimitive(right)) return Object.is(left, right);
+  if (Array.isArray(left) || Array.isArray(right)) {
+    if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) return false;
+    return left.every((value, index) => jsonDeepEqual(value, right[index]));
+  }
+  if (!isPlainObject(left) || !isPlainObject(right)) return false;
+  const leftEntries = Object.entries(left);
+  const rightEntries = Object.entries(right);
+  if (leftEntries.length !== rightEntries.length) return false;
+  for (const [key, value] of leftEntries) {
+    if (!Object.hasOwn(right, key) || !jsonDeepEqual(value, right[key])) return false;
+  }
+  return true;
+}
+
+/**
+ * Validate and narrow unknown adapter data into manifest JSON metadata.
+ *
+ * The check intentionally compares the original value against a
+ * JSON.stringify/parse round trip. Dates, functions, undefined fields, NaN,
+ * Infinity, class instances, and cycles fail instead of being silently
+ * coerced in `dot explain --json`.
+ */
+export function toJsonObject(value: unknown): JsonObject {
+  const parsed = jsonRoundTrip(value);
+  if (!isJsonObject(parsed) || !jsonDeepEqual(value, parsed)) {
+    throw new TypeError('Value must be a JSON-serializable object without lossy coercions.');
+  }
+  return parsed;
+}
+
 /**
- * Kind of service that a pip can publish.
+ * Kind of service that a plugin 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.
+ * is the escape hatch for plugin-defined service kinds — use it whenever a
+ * plugin publishes something that does not fit a reserved shape.
  */
 export type ServiceKind =
   | 'env'
@@ -33,79 +105,85 @@ export type ServiceKind =
   | '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. */
+/** Kind of dependency edge between two plugins. */
 export type DependencyEdgeKind = 'requires' | 'provides' | 'uses';
 
+/** Direction of a boundary interaction, viewed from the app. */
+export type ActionDirection = 'in' | 'out';
+
+/** Something the app does at a boundary — universal, serializable, tiny. */
+export type ActionManifest = {
+  /** Stable identifier, e.g. `orders.list` or `orders.created.consume`. */
+  id: string;
+  plugin: string;
+  /** Adapter-owned binding name: `http`, `queue`, `cli`, `cron`, etc. */
+  binding: string;
+  /** `in` = world invokes/feeds the app; `out` = app emits. */
+  direction: ActionDirection;
+  /** Display-only address printed by `dot explain`. */
+  address?: string;
+  /** Human summary rendered into explain output and projected documents. */
+  summary?: string;
+  /** Adapter-owned, JSON-serializable detail. Opaque to the kernel. */
+  meta?: Readonly<JsonObject>;
+  /** Optional adapter-owned identifier+version for the meta layout. */
+  metaSchema?: string;
+};
+
+/** Registered projection renderer for an adapter-owned document format. */
+export type ProjectionManifest = {
+  /** Document format key matched by `dot explain --as <format>`. */
+  format: string;
+  /** Binding this projection primarily renders. Informational. */
+  binding: string;
+  /** Import specifier for the projection module. */
+  module: string;
+  /** Plugin that registered this projection. */
+  plugin: string;
+};
+
 /**
  * Top-level manifest describing the static shape of a DOT app.
  *
- * Always carries the five arrays — never omits any of them.
+ * Always carries the six arrays — never omits any of them.
  */
 export type DotAppManifest = {
+  /** Manifest schema version. 2 = actions/projections era. */
+  manifestVersion: 2;
   app: {
     name: string;
     version?: string;
   };
-  pips: PipManifest[];
-  routes: RouteManifest[];
+  plugins: PluginManifest[];
+  actions: ActionManifest[];
   services: ServiceManifest[];
   lifecycle: LifecycleManifest[];
   dependencies: DependencyEdge[];
+  projections: ProjectionManifest[];
 };
 
-/** Single pip's declarative metadata. */
-export type PipManifest = {
+/** Single plugin's declarative metadata. */
+export type PluginManifest = {
   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;
-  /** Human summary, rendered into docs/OpenAPI output. */
-  description?: string;
-  /**
-   * JSON Schema for the request inputs, keyed by location. Adapters
-   * convert their validation schemas (e.g. zod) at `configure` time so the
-   * manifest stays plain serializable data — `dot explain --openapi`
-   * renders straight from here without booting.
-   */
-  input?: {
-    readonly query?: Readonly<Record<string, unknown>>;
-    readonly body?: Readonly<Record<string, unknown>>;
-  };
-  /** JSON Schema for the success response (or per-event schema when `streaming`). */
-  output?: Readonly<Record<string, unknown>>;
-  /**
-   * The response is an open stream (e.g. `text/event-stream`) rather than
-   * a single JSON document.
-   */
-  streaming?: boolean;
-};
-
-/** Single service published by a pip. */
+/** Single service published by a plugin. */
 export type ServiceManifest = {
   name: string;
-  pip: string;
+  plugin: string;
   kind: ServiceKind;
 };
 
-/** Which lifecycle hooks a pip participates in. */
+/** Which lifecycle hooks a plugin participates in. */
 export type LifecycleManifest = {
-  pip: string;
+  plugin: string;
   hooks: readonly DotLifecycleHook[];
 };
 
-/** Directed edge in the pip dependency graph. */
+/** Directed edge in the plugin dependency graph. */
 export type DependencyEdge = {
   from: string;
   to: string;