@arki/dot 0.3.0 → 0.4.0

package/src/kernel/app-instance.ts

@@ -9,56 +9,61 @@ import { Logger } from '@arki/log';
 import { createDebugLogger } from '@arki/log/debug';
 
 import type {
+  ActionDiagnostic,
   DiagnosticIssue,
   DotDiagnosticsSnapshot,
   LifecycleDiagnostic,
-  PipDiagnostic,
-  RouteDiagnostic,
+  PluginDiagnostic,
   ServiceDiagnostic,
 } from '../diagnostics.js';
 import type { DotLifecycleEvent, DotLifecycleObserver } from '../lifecycle-observer.js';
-import type { DotLifecycleHook, DotLifecyclePipFailure, DotLifecycleState } from '../lifecycle.js';
+import type { DotLifecycleHook, DotLifecyclePluginFailure, DotLifecycleState } from '../lifecycle.js';
 import type {
+  ActionManifest,
   DependencyEdge,
   DotAppManifest,
+  JsonObject,
   LifecycleManifest,
-  PipManifest,
-  RouteManifest,
+  PluginManifest,
+  ProjectionManifest,
   ServiceManifest,
 } from '../manifest.js';
-import type { AnyPip, DotConfigureContext, Lazy, ServiceRecord } from '../pip-contract.js';
+import type { AnyPlugin, DotConfigureContext, Lazy, ServiceRecord } from '../plugin-contract.js';
 import { DotLifecycleError, DotLifecycleErrorCode } from '../lifecycle.js';
-import { isLazy, isLazyWitness, lazyOf } from '../pip-contract.js';
-import { withPhaseSpan, withPipHookSpan } from './otel.js';
+import { toJsonObject } from '../manifest.js';
+import { isLazy, isLazyWitness, lazyOf } from '../plugin-contract.js';
+import { withPhaseSpan, withPluginHookSpan } from './otel.js';
 
 const debugKernel = createDebugLogger('arki:dot:kernel');
 
 const DOCS_BASE = 'https://docs.arki.dev/dot/diagnostics';
 
-/** Per-pip mutable bookkeeping. */
-type PipRecord = {
-  pip: AnyPip;
+/** Per-plugin mutable bookkeeping. */
+type PluginRecord = {
+  plugin: AnyPlugin;
   /** Declaration order (0-based) — v2 boot order IS declaration order. */
   order: number;
-  /** Routes registered during `configure`. */
-  routes: RouteManifest[];
+  /** Actions declared statically or registered during `configure`. */
+  actions: ActionManifest[];
+  /** Projection renderers registered during `configure`. */
+  projections: ProjectionManifest[];
   /** Services declared during `configure`. */
   services: ServiceManifest[];
-  /** Lifecycle hooks the pip participates in. */
+  /** Lifecycle hooks the plugin participates in. */
   hooks: Set<DotLifecycleHook>;
   /** Provides capability strings declared during `configure`, joined with published wire keys. */
   provides: Set<string>;
   /**
-   * Services published by this pip, keyed by LOCAL publish keys (pre-rename).
-   * The pip's own stop/dispose contexts read these; the app-facing service
+   * Services published by this plugin, keyed by LOCAL publish keys (pre-rename).
+   * The plugin's own stop/dispose contexts read these; the app-facing service
    * map uses the renamed wire keys.
    */
   publishedServices: ServiceRecord;
-  /** Whether the pip's `boot` hook completed successfully. */
+  /** Whether the plugin's `boot` hook completed successfully. */
   booted: boolean;
-  /** Whether the pip's `start` hook completed successfully. */
+  /** Whether the plugin's `start` hook completed successfully. */
   started: boolean;
-  /** Diagnostic issues collected for this pip. */
+  /** Diagnostic issues collected for this plugin. */
   issues: DiagnosticIssue[];
   /** Per-hook diagnostic entries. */
   lifecycleDiagnostics: LifecycleDiagnostic[];
@@ -75,7 +80,7 @@ function wireKeyOf(witness: object, alias: string): string {
 function makeIssue(args: {
   code: string;
   severity?: 'info' | 'warning' | 'error';
-  pip?: string;
+  plugin?: string;
   message: string;
   remediation: string;
   docsAnchor: string;
@@ -84,7 +89,7 @@ function makeIssue(args: {
   return {
     code: args.code,
     severity: args.severity ?? 'error',
-    pip: args.pip,
+    plugin: args.plugin,
     message: args.message,
     remediation: args.remediation,
     docsUrl: `${DOCS_BASE}#${args.docsAnchor}`,
@@ -95,7 +100,7 @@ function makeIssue(args: {
 export type DotAppInternalConfig = {
   appName: string;
   appVersion?: string;
-  pips: readonly AnyPip[];
+  plugins: readonly AnyPlugin[];
   /** Runtime config bag passed to every `boot` hook. */
   config?: Readonly<Record<string, unknown>>;
   /**
@@ -117,9 +122,9 @@ export class DotAppImpl {
   readonly #appVersion: string | undefined;
   readonly #config: Readonly<Record<string, unknown>>;
 
-  /** Pips in declaration order — v2 boot order IS declaration order. */
-  readonly #ordered: readonly AnyPip[];
-  readonly #records: Map<string, PipRecord>;
+  /** Plugins in declaration order — v2 boot order IS declaration order. */
+  readonly #ordered: readonly AnyPlugin[];
+  readonly #records: Map<string, PluginRecord>;
 
   /** Macro-state of the app. */
   #state: DotLifecycleState = 'defined';
@@ -130,10 +135,10 @@ export class DotAppImpl {
   /** Manifest finalised after `configure`. */
   #manifest: DotAppManifest;
 
-  /** Wire-keyed services map — populated as pips boot. */
+  /** Wire-keyed services map — populated as plugins boot. */
   readonly #serviceMap = new Map<string, unknown>();
 
-  /** Which pip provided each wire key — feeds dependency edges + collisions. */
+  /** Which plugin provided each wire key — feeds dependency edges + collisions. */
   readonly #providerByWireKey = new Map<string, string>();
 
   /** Dependency edges observed during boot (consumer → provider). */
@@ -167,7 +172,7 @@ export class DotAppImpl {
    * Structured lifecycle logger. One per app instance; named so consumers
    * can elevate it to DEBUG via `DEBUG=arki:dot:lifecycle` without
    * touching unrelated namespaces. Every line carries the app name plus
-   * any phase/pip attributes from the call site. The span helpers
+   * any phase/plugin attributes from the call site. The span helpers
    * (see `./otel.ts`) thread the active span's `traceId`+`spanId` onto
    * forked instances of this logger, so every log record is groupable
    * with its trace in any OTel-compatible backend.
@@ -192,50 +197,51 @@ export class DotAppImpl {
 
     // Declaration order is boot order in v2. Duplicate names are surfaced at
     // construction (the `configure` phase pseudo-time).
-    debugKernel('[%s] registering %d pip(s) in declaration order', this.#appName, config.pips.length);
-    this.#ordered = [...config.pips];
+    debugKernel('[%s] registering %d plugin(s) in declaration order', this.#appName, config.plugins.length);
+    this.#ordered = [...config.plugins];
 
     this.#records = new Map();
-    for (const [order, pip] of this.#ordered.entries()) {
-      if (this.#records.has(pip.name)) {
+    for (const [order, plugin] of this.#ordered.entries()) {
+      if (this.#records.has(plugin.name)) {
         throw new DotLifecycleError({
-          code: DotLifecycleErrorCode.DuplicatePip,
+          code: DotLifecycleErrorCode.DuplicatePlugin,
           phase: 'configure',
-          pip: pip.name,
-          message: `Pip "${pip.name}" is registered twice`,
+          plugin: plugin.name,
+          message: `Plugin "${plugin.name}" is registered twice`,
         });
       }
-      // `$` is the kernel context namespace ($app/$pip/$config). The pip()
+      // `$` is the kernel context namespace ($app/$plugin/$config). The plugin()
       // constraint bans these at compile time; this is the runtime backstop
-      // for erased pips and rename() targets, which types cannot see.
-      for (const alias of Object.keys(pip.needs)) {
+      // for erased plugins and rename() targets, which types cannot see.
+      for (const alias of Object.keys(plugin.needs)) {
         if (alias.startsWith('$')) {
           throw new DotLifecycleError({
             code: DotLifecycleErrorCode.ReservedServiceKey,
             phase: 'configure',
-            pip: pip.name,
+            plugin: plugin.name,
             message:
-              `Pip "${pip.name}" declares needs alias "${alias}" — the "$" prefix is reserved ` +
-              `for kernel context keys ($app, $pip, $config). Rename the alias.`,
+              `Plugin "${plugin.name}" declares needs alias "${alias}" — the "$" prefix is reserved ` +
+              `for kernel context keys ($app, $plugin, $config). Rename the alias.`,
           });
         }
       }
-      for (const [localKey, wireKey] of Object.entries(pip.renames)) {
+      for (const [localKey, wireKey] of Object.entries(plugin.renames)) {
         if (wireKey.startsWith('$')) {
           throw new DotLifecycleError({
             code: DotLifecycleErrorCode.ReservedServiceKey,
             phase: 'configure',
-            pip: pip.name,
+            plugin: plugin.name,
             message:
-              `Pip "${pip.name}" renames "${localKey}" to "${wireKey}" — the "$" prefix is ` +
-              `reserved for kernel context keys ($app, $pip, $config). Pick a different wire key.`,
+              `Plugin "${plugin.name}" renames "${localKey}" to "${wireKey}" — the "$" prefix is ` +
+              `reserved for kernel context keys ($app, $plugin, $config). Pick a different wire key.`,
           });
         }
       }
-      this.#records.set(pip.name, {
-        pip,
+      this.#records.set(plugin.name, {
+        plugin,
         order,
-        routes: [],
+        actions: [],
+        projections: [],
         services: [],
         hooks: new Set<DotLifecycleHook>(),
         provides: new Set<string>(),
@@ -300,16 +306,16 @@ export class DotAppImpl {
    */
   #emitHook(
     phase: DotLifecycleHook,
-    pip: string,
+    plugin: string,
     order: number,
     status: 'starting' | 'completed' | 'failed',
     opts?: { durationMs?: number; error?: unknown },
   ): void {
     if (this.#observers.size === 0) return;
     const event = {
-      kind: 'pip-hook' as const,
+      kind: 'plugin-hook' as const,
       phase,
-      pip,
+      plugin,
       order,
       status,
       appName: this.#appName,
@@ -320,6 +326,96 @@ export class DotAppImpl {
     this.#emit(event);
   }
 
+  #registerAction(record: PluginRecord, action: Omit<ActionManifest, 'plugin'>): void {
+    let meta: Readonly<JsonObject> | undefined;
+    if (action.meta !== undefined) {
+      try {
+        meta = toJsonObject(action.meta);
+      } catch (error) {
+        const issue = makeIssue({
+          code: DotLifecycleErrorCode.ActionMetaNotJson,
+          plugin: record.plugin.name,
+          message:
+            `action "${action.id}" for binding "${action.binding}" has metadata that is not JSON-round-trip safe: ` +
+            stringifyError(error),
+          remediation:
+            'Only put JSON-serializable data in action meta. Convert Dates to strings, remove functions/undefined fields, and avoid NaN/Infinity.',
+          docsAnchor: 'action-meta-not-json',
+          metadata: { actionId: action.id, binding: action.binding },
+        });
+        record.issues.push(issue);
+      }
+    }
+
+    const stamped: ActionManifest = {
+      id: action.id,
+      plugin: record.plugin.name,
+      binding: action.binding,
+      direction: action.direction,
+      ...(action.address === undefined ? {} : { address: action.address }),
+      ...(action.summary === undefined ? {} : { summary: action.summary }),
+      ...(meta === undefined ? {} : { meta }),
+      ...(action.metaSchema === undefined ? {} : { metaSchema: action.metaSchema }),
+    };
+
+    for (const existingRecord of this.#records.values()) {
+      const duplicate = existingRecord.actions.find(
+        existing => existing.binding === stamped.binding && existing.id === stamped.id,
+      );
+      if (duplicate === undefined) continue;
+      const issue = makeIssue({
+        code: DotLifecycleErrorCode.DuplicateAction,
+        plugin: record.plugin.name,
+        message: `action "${stamped.id}" is registered more than once for binding "${stamped.binding}".`,
+        remediation:
+          'Action ids must be unique within a binding. Rename one action or move one of them to a different binding.',
+        docsAnchor: 'duplicate-action',
+        metadata: { binding: stamped.binding, id: stamped.id, firstPlugin: duplicate.plugin },
+      });
+      record.issues.push(issue);
+      break;
+    }
+
+    record.actions.push(stamped);
+  }
+
+  #registerProjection(record: PluginRecord, projection: Omit<ProjectionManifest, 'plugin'>): void {
+    record.projections.push({ ...projection, plugin: record.plugin.name });
+  }
+
+  #registerRouteShim(
+    record: PluginRecord,
+    route: Parameters<DotConfigureContext['registerRoute']>[0],
+  ): void {
+    const meta: JsonObject = {};
+    if (route.method !== undefined) meta['method'] = route.method;
+    if (route.path !== undefined) meta['path'] = route.path;
+    if (route.input !== undefined) {
+      const input: JsonObject = {};
+      if (route.input.query !== undefined) input['query'] = route.input.query;
+      if (route.input.body !== undefined) input['body'] = route.input.body;
+      if (Object.keys(input).length > 0) meta['input'] = input;
+    }
+    if (route.output !== undefined) meta['output'] = route.output;
+    if (route.streaming !== undefined) meta['streaming'] = route.streaming;
+
+    this.#registerAction(record, {
+      id: route.id,
+      binding: route.transport,
+      direction: 'in',
+      ...(route.path === undefined ? {} : { address: `${route.method ?? 'GET'} ${route.path}` }),
+      ...(route.description === undefined ? {} : { summary: route.description }),
+      ...(Object.keys(meta).length === 0 ? {} : { meta }),
+    });
+  }
+
+  #actionFromSource(source: AnyPlugin['actions'][number]): Omit<ActionManifest, 'plugin'> {
+    if (hasToDotAction(source)) {
+      return source.toDotAction();
+    }
+    return source;
+  }
+
   /**
    * Wrap a sync phase body with starting/completed/failed observer events.
    * `configure` is the only sync phase in the kernel today — keep the
@@ -424,14 +520,14 @@ export class DotAppImpl {
     }
 
     const phaseLogger = this.#logger.withAttribute('dot.app.phase', 'configure');
-    phaseLogger.debug('configure: starting', { 'dot.app.pip.count': this.#ordered.length });
+    phaseLogger.debug('configure: starting', { 'dot.app.plugin.count': this.#ordered.length });
 
     this.#withPhaseEmit('configure', () => {
       withPhaseSpan(
         {
           appName: this.#appName,
           phase: 'configure',
-          pipCount: this.#ordered.length,
+          pluginCount: this.#ordered.length,
           logger: phaseLogger,
         },
         () => this.#runConfigureInner(phaseLogger),
@@ -445,24 +541,57 @@ export class DotAppImpl {
    * intricate error-handling readable.
    */
   #runConfigureInner(phaseLogger: Logger): void {
-    for (const pip of this.#ordered) {
-      const record = this.#records.get(pip.name)!;
-      const pipLogger = phaseLogger.withAttribute('dot.pip.name', pip.name);
-      if (!pip.hooks.configure) {
-        pipLogger.debug('configure: skipped (no hook)');
+    for (const plugin of this.#ordered) {
+      const record = this.#records.get(plugin.name)!;
+      const pluginLogger = phaseLogger.withAttribute('dot.plugin.name', plugin.name);
+      const declaredStarted = performance.now();
+      try {
+        for (const source of plugin.actions) this.#registerAction(record, this.#actionFromSource(source));
+      } catch (error) {
+        const durationMs = performance.now() - declaredStarted;
+        const issue = makeIssue({
+          code: DotLifecycleErrorCode.ConfigureFailed,
+          plugin: plugin.name,
+          message: `action declaration threw for plugin "${plugin.name}": ${stringifyError(error)}`,
+          remediation: `Fix the action declarations of "${plugin.name}". Declarative actions must be static and synchronous.`,
+          docsAnchor: 'configure-failed',
+        });
+        record.issues.push(issue);
+        record.lifecycleDiagnostics.push({
+          plugin: plugin.name,
+          hook: 'configure',
+          state: 'failed',
+          order: record.order,
+          durationMs,
+          issues: [issue],
+        });
+        this.#emitHook('configure', plugin.name, record.order, 'failed', { durationMs, error });
+        this.#state = 'failed';
+        this.#manifest = this.#buildManifest();
+        throw new DotLifecycleError({
+          code: DotLifecycleErrorCode.ConfigureFailed,
+          phase: 'configure',
+          plugin: plugin.name,
+          message: issue.message,
+          cause: error,
+        });
+      }
+
+      if (!plugin.hooks.configure) {
+        pluginLogger.debug('configure: skipped (no hook)');
         continue;
       }
       record.hooks.add('configure');
 
       const ctx: DotConfigureContext = {
-        pipName: pip.name,
+        pluginName: plugin.name,
         appName: this.#appName,
         registerService: (name, kind) => {
-          record.services.push({ name, pip: pip.name, kind });
-        },
-        registerRoute: route => {
-          record.routes.push({ ...route, pip: pip.name });
+          record.services.push({ name, plugin: plugin.name, kind });
         },
+        registerAction: action => this.#registerAction(record, action),
+        registerProjection: projection => this.#registerProjection(record, projection),
+        registerRoute: route => this.#registerRouteShim(record, route),
         registerLifecycleHook: hook => {
           record.hooks.add(hook);
         },
@@ -472,45 +601,45 @@ export class DotAppImpl {
       };
 
       const started = performance.now();
-      this.#emitHook('configure', pip.name, record.order, 'starting');
+      this.#emitHook('configure', plugin.name, record.order, 'starting');
       let returned: unknown;
       try {
-        returned = withPipHookSpan(
+        returned = withPluginHookSpan(
           {
             appName: this.#appName,
-            pipName: pip.name,
-            pipVersion: pip.version,
+            pluginName: plugin.name,
+            pluginVersion: plugin.version,
             hook: 'configure',
             order: record.order,
-            logger: pipLogger,
+            logger: pluginLogger,
           },
-          () => pip.hooks.configure!(ctx),
+          () => plugin.hooks.configure!(ctx),
         );
       } catch (error) {
         const durationMs = performance.now() - started;
         const issue = makeIssue({
           code: DotLifecycleErrorCode.ConfigureFailed,
-          pip: pip.name,
-          message: `configure hook threw for pip "${pip.name}": ${stringifyError(error)}`,
-          remediation: `Fix the error in the configure() hook of "${pip.name}". configure() is for synchronous registration only — avoid throwing on declarative work.`,
+          plugin: plugin.name,
+          message: `configure hook threw for plugin "${plugin.name}": ${stringifyError(error)}`,
+          remediation: `Fix the error in the configure() hook of "${plugin.name}". configure() is for synchronous registration only — avoid throwing on declarative work.`,
           docsAnchor: 'configure-failed',
         });
         record.issues.push(issue);
         record.lifecycleDiagnostics.push({
-          pip: pip.name,
+          plugin: plugin.name,
           hook: 'configure',
           state: 'failed',
           order: record.order,
           durationMs,
           issues: [issue],
         });
-        this.#emitHook('configure', pip.name, record.order, 'failed', { durationMs, error });
+        this.#emitHook('configure', plugin.name, record.order, 'failed', { durationMs, error });
         this.#state = 'failed';
         this.#manifest = this.#buildManifest();
         throw new DotLifecycleError({
           code: DotLifecycleErrorCode.ConfigureFailed,
           phase: 'configure',
-          pip: pip.name,
+          plugin: plugin.name,
           message: issue.message,
           cause: error,
         });
@@ -520,21 +649,21 @@ export class DotAppImpl {
         const durationMs = performance.now() - started;
         const issue = makeIssue({
           code: DotLifecycleErrorCode.ConfigureAsync,
-          pip: pip.name,
-          message: `configure hook of pip "${pip.name}" returned a Promise. configure must be synchronous.`,
+          plugin: plugin.name,
+          message: `configure hook of plugin "${plugin.name}" returned a Promise. configure must be synchronous.`,
           remediation: 'Move async work to the boot() hook. configure() is for synchronous registration only.',
           docsAnchor: 'configure-async',
         });
         record.issues.push(issue);
         record.lifecycleDiagnostics.push({
-          pip: pip.name,
+          plugin: plugin.name,
           hook: 'configure',
           state: 'failed',
           order: record.order,
           durationMs,
           issues: [issue],
         });
-        this.#emitHook('configure', pip.name, record.order, 'failed', {
+        this.#emitHook('configure', plugin.name, record.order, 'failed', {
           durationMs,
           error: new Error(issue.message),
         });
@@ -543,38 +672,38 @@ export class DotAppImpl {
         throw new DotLifecycleError({
           code: DotLifecycleErrorCode.ConfigureAsync,
           phase: 'configure',
-          pip: pip.name,
+          plugin: plugin.name,
           message: issue.message,
         });
       }
 
       const durationMs = performance.now() - started;
       record.lifecycleDiagnostics.push({
-        pip: pip.name,
+        plugin: plugin.name,
         hook: 'configure',
         state: 'configured',
         order: record.order,
         durationMs,
         issues: [],
       });
-      this.#emitHook('configure', pip.name, record.order, 'completed', { durationMs });
-      pipLogger.debug('configure: done', { 'dot.pip.duration.ms': durationMs });
+      this.#emitHook('configure', plugin.name, record.order, 'completed', { durationMs });
+      pluginLogger.debug('configure: done', { 'dot.plugin.duration.ms': durationMs });
     }
 
     // Also declare lifecycle-hook participation for non-configure hooks present
-    // on the pip object, so the manifest reflects them.
-    for (const pip of this.#ordered) {
-      const record = this.#records.get(pip.name)!;
-      if (pip.hooks.boot) record.hooks.add('boot');
-      if (pip.hooks.start) record.hooks.add('start');
-      if (pip.hooks.stop) record.hooks.add('stop');
-      if (pip.hooks.dispose) record.hooks.add('dispose');
+    // on the plugin object, so the manifest reflects them.
+    for (const plugin of this.#ordered) {
+      const record = this.#records.get(plugin.name)!;
+      if (plugin.hooks.boot) record.hooks.add('boot');
+      if (plugin.hooks.start) record.hooks.add('start');
+      if (plugin.hooks.stop) record.hooks.add('stop');
+      if (plugin.hooks.dispose) record.hooks.add('dispose');
     }
 
     this.#configured = true;
     this.#state = 'configured';
     this.#manifest = this.#buildManifest();
-    phaseLogger.debug('configure: complete', { 'dot.app.pip.count': this.#ordered.length });
+    phaseLogger.debug('configure: complete', { 'dot.app.plugin.count': this.#ordered.length });
   }
 
   /**
@@ -617,14 +746,14 @@ export class DotAppImpl {
     }
 
     const phaseLogger = this.#logger.withAttribute('dot.app.phase', 'boot');
-    phaseLogger.debug('boot: starting', { 'dot.app.pip.count': this.#ordered.length });
+    phaseLogger.debug('boot: starting', { 'dot.app.plugin.count': this.#ordered.length });
 
     return this.#withPhaseEmitAsync('boot', () =>
       withPhaseSpan(
         {
           appName: this.#appName,
           phase: 'boot',
-          pipCount: this.#ordered.length,
+          pluginCount: this.#ordered.length,
           logger: phaseLogger,
         },
         () => this.#runBootInner(phaseLogger),
@@ -633,34 +762,34 @@ export class DotAppImpl {
   }
 
   /**
-   * Resolve a pip's needs into a hook context (alias-keyed), joined with
-   * the `$`-prefixed kernel keys and — for post-boot hooks — the pip's own
+   * Resolve a plugin's needs into a hook context (alias-keyed), joined with
+   * the `$`-prefixed kernel keys and — for post-boot hooks — the plugin's own
    * published services (local keys).
    *
    * @throws {DotLifecycleError} `DOT_LIFECYCLE_E012` when a need has no
-   *   provider among earlier-booted pips. Teardown hooks can never hit
+   *   provider among earlier-booted plugins. Teardown hooks can never hit
    *   this: the service map only grows, and reverse-order teardown keeps
    *   providers alive until their consumers are done.
    */
-  #buildHookCtx(record: PipRecord, phase: DotLifecycleHook, includeOwnProvides: boolean): Record<string, unknown> {
+  #buildHookCtx(record: PluginRecord, phase: DotLifecycleHook, includeOwnProvides: boolean): Record<string, unknown> {
     const ctx: Record<string, unknown> = {
       $app: this.#appName,
-      $pip: record.pip.name,
+      $plugin: record.plugin.name,
       $config: this.#config,
     };
-    for (const [alias, witness] of Object.entries(record.pip.needs)) {
+    for (const [alias, witness] of Object.entries(record.plugin.needs)) {
       const wireKey = wireKeyOf(witness, alias);
       if (!this.#serviceMap.has(wireKey)) {
         throw new DotLifecycleError({
           code: DotLifecycleErrorCode.UnsatisfiedNeed,
           phase,
-          pip: record.pip.name,
+          plugin: record.plugin.name,
           message:
-            `Pip "${record.pip.name}" needs service "${wireKey}" but no earlier pip provides it. ` +
-            `Register a provider with .use() before this pip. Services flow strictly forward — ` +
-            `if a later pip provides "${wireKey}", move that provider earlier; if two pips need ` +
+            `Plugin "${record.plugin.name}" needs service "${wireKey}" but no earlier plugin provides it. ` +
+            `Register a provider with .use() before this plugin. Services flow strictly forward — ` +
+            `if a later plugin provides "${wireKey}", move that provider earlier; if two plugins need ` +
             `each other's services, that is a cycle: merge them or extract the shared piece into ` +
-            `a third pip both consume.`,
+            `a third plugin both consume.`,
         });
       }
       const value = this.#serviceMap.get(wireKey);
@@ -671,8 +800,8 @@ export class DotAppImpl {
       // the underlying value's lifecycle stays with its provider.
       ctx[alias] = isLazyWitness(witness) && !isLazy(value) ? lazyOf(value) : value;
       const provider = this.#providerByWireKey.get(wireKey);
-      if (provider !== undefined && !this.#wiringEdges.some(e => e.from === record.pip.name && e.to === provider)) {
-        this.#wiringEdges.push({ from: record.pip.name, to: provider, kind: 'requires' });
+      if (provider !== undefined && !this.#wiringEdges.some(e => e.from === record.plugin.name && e.to === provider)) {
+        this.#wiringEdges.push({ from: record.plugin.name, to: provider, kind: 'requires' });
       }
     }
     if (includeOwnProvides) {
@@ -684,13 +813,13 @@ export class DotAppImpl {
   /**
    * Race one hook invocation against the app's `hookTimeoutMs` watchdog.
    * No budget configured → plain pass-through. On timeout the returned
-   * promise rejects with `DOT_LIFECYCLE_E015` naming the pip and hook,
+   * promise rejects with `DOT_LIFECYCLE_E015` naming the plugin and hook,
    * and the call site's existing catch path applies the phase's normal
    * failure rules (boot rollback, start cascade, teardown aggregation).
    * The hook's own promise cannot be cancelled — the watchdog makes a
    * hang visible and bounded; it does not kill the hung work.
    */
-  async #withHookBudget<T>(pipName: string, hook: DotLifecycleHook, run: () => Promise<T> | T): Promise<T> {
+  async #withHookBudget<T>(pluginName: string, hook: DotLifecycleHook, run: () => Promise<T> | T): Promise<T> {
     const budget = this.#hookTimeoutMs;
     if (budget === undefined) return run();
     let timer: ReturnType<typeof setTimeout> | undefined;
@@ -700,9 +829,9 @@ export class DotAppImpl {
           new DotLifecycleError({
             code: DotLifecycleErrorCode.HookTimeout,
             phase: hook,
-            pip: pipName,
+            plugin: pluginName,
             message:
-              `${hook} hook of pip "${pipName}" exceeded the ${budget.toString()}ms hookTimeoutMs watchdog. ` +
+              `${hook} hook of plugin "${pluginName}" exceeded the ${budget.toString()}ms hookTimeoutMs watchdog. ` +
               `The kernel treats the hook as failed and applies its normal rollback/aggregation rules, but ` +
               `cannot cancel the hook's promise — find the hang (a missing await? a connection that never ` +
               `settles?) or raise the budget in defineApp(name, { hookTimeoutMs }).`,
@@ -725,11 +854,11 @@ export class DotAppImpl {
    * partial failure — stays unindented.
    */
   async #runBootInner(phaseLogger: Logger): Promise<void> {
-    const bootedRecords: PipRecord[] = [];
+    const bootedRecords: PluginRecord[] = [];
 
     /** Shared failure path: mark diagnostics, roll back, throw. */
     const fail = async (args: {
-      record: PipRecord;
+      record: PluginRecord;
       code: (typeof DotLifecycleErrorCode)[keyof typeof DotLifecycleErrorCode];
       message: string;
       remediation: string;
@@ -737,30 +866,30 @@ export class DotAppImpl {
       durationMs: number;
       cause?: unknown;
       /** Records to dispose (reverse order applied here). */
-      rollback: readonly PipRecord[];
+      rollback: readonly PluginRecord[];
     }): Promise<never> => {
       const issue = makeIssue({
         code: args.code,
-        pip: args.record.pip.name,
+        plugin: args.record.plugin.name,
         message: args.message,
         remediation: args.remediation,
         docsAnchor: args.docsAnchor,
       });
       args.record.issues.push(issue);
       args.record.lifecycleDiagnostics.push({
-        pip: args.record.pip.name,
+        plugin: args.record.plugin.name,
         hook: 'boot',
         state: 'failed',
         order: args.record.order,
         durationMs: args.durationMs,
         issues: [issue],
       });
-      this.#emitHook('boot', args.record.pip.name, args.record.order, 'failed', {
+      this.#emitHook('boot', args.record.plugin.name, args.record.order, 'failed', {
         durationMs: args.durationMs,
         error: args.cause ?? new Error(args.message),
       });
-      phaseLogger.error('boot: FAILED — rolling back already-booted pips', {
-        'dot.pip.name': args.record.pip.name,
+      phaseLogger.error('boot: FAILED — rolling back already-booted plugins', {
+        'dot.plugin.name': args.record.plugin.name,
         'dot.app.rollback.count': args.rollback.length,
       });
       const disposeFailures = await this.#runDisposeForRecords(reverseRecords(args.rollback), phaseLogger);
@@ -769,19 +898,19 @@ export class DotAppImpl {
       throw new DotLifecycleError({
         code: args.code,
         phase: 'boot',
-        pip: args.record.pip.name,
+        plugin: args.record.plugin.name,
         message: args.message,
         cause: args.cause,
         failures: disposeFailures.length > 0 ? disposeFailures : undefined,
       });
     };
 
-    for (const pip of this.#ordered) {
-      const record = this.#records.get(pip.name)!;
-      const pipLogger = phaseLogger.withAttribute('dot.pip.name', pip.name);
+    for (const plugin of this.#ordered) {
+      const record = this.#records.get(plugin.name)!;
+      const pluginLogger = phaseLogger.withAttribute('dot.plugin.name', plugin.name);
       const started = performance.now();
 
-      // Resolve needs BEFORE invoking the hook — a pip with needs but no
+      // Resolve needs BEFORE invoking the hook — a plugin with needs but no
       // boot hook still fails fast when its wiring is unsatisfied.
       let ctx: Record<string, unknown>;
       try {
@@ -793,40 +922,40 @@ export class DotAppImpl {
           code: DotLifecycleErrorCode.UnsatisfiedNeed,
           message,
           remediation:
-            `Add a provider for the missing service with .use() before "${pip.name}", or rename an ` +
-            `existing provider's keys to match. If a later pip provides it, reorder — services flow ` +
-            `strictly forward. Mutual needs between two pips are a cycle: merge them or extract the ` +
-            `shared piece into a third pip both consume.`,
+            `Add a provider for the missing service with .use() before "${plugin.name}", or rename an ` +
+            `existing provider's keys to match. If a later plugin provides it, reorder — services flow ` +
+            `strictly forward. Mutual needs between two plugins are a cycle: merge them or extract the ` +
+            `shared piece into a third plugin both consume.`,
           docsAnchor: 'unsatisfied-need',
           durationMs: performance.now() - started,
           rollback: bootedRecords,
         });
       }
 
-      if (!pip.hooks.boot) {
+      if (!plugin.hooks.boot) {
         record.booted = true;
         bootedRecords.push(record);
-        pipLogger.debug('boot: skipped (no hook)');
+        pluginLogger.debug('boot: skipped (no hook)');
         continue;
       }
       record.hooks.add('boot');
 
-      this.#emitHook('boot', pip.name, record.order, 'starting');
+      this.#emitHook('boot', plugin.name, record.order, 'starting');
       let result: ServiceRecord | void;
       try {
-        result = await this.#withHookBudget(pip.name, 'boot', () =>
-          withPipHookSpan(
+        result = await this.#withHookBudget(plugin.name, 'boot', () =>
+          withPluginHookSpan(
             {
               appName: this.#appName,
-              pipName: pip.name,
-              pipVersion: pip.version,
+              pluginName: plugin.name,
+              pluginVersion: plugin.version,
               hook: 'boot',
               order: record.order,
-              logger: pipLogger,
+              logger: pluginLogger,
             },
             // Erasure boundary: hooks are stored as `(ctx: never) => ...`;
             // the kernel is the one caller allowed to cross it.
-            () => pip.hooks.boot!(ctx as never),
+            () => plugin.hooks.boot!(ctx as never),
           ),
         );
       } catch (error) {
@@ -836,10 +965,10 @@ export class DotAppImpl {
           code: timedOut ? DotLifecycleErrorCode.HookTimeout : DotLifecycleErrorCode.BootFailed,
           message: timedOut
             ? error.message
-            : `boot hook threw for pip "${pip.name}": ${stringifyError(error)}`,
+            : `boot hook threw for plugin "${plugin.name}": ${stringifyError(error)}`,
           remediation: timedOut
-            ? `Find the hang in the boot() hook of "${pip.name}" — a missing await or a connection that never settles — or raise defineApp's hookTimeoutMs.`
-            : `Fix the error in the boot() hook of "${pip.name}". If boot opens partial resources before throwing, clean them up locally — DOT only disposes pips whose boot completed.`,
+            ? `Find the hang in the boot() hook of "${plugin.name}" — a missing await or a connection that never settles — or raise defineApp's hookTimeoutMs.`
+            : `Fix the error in the boot() hook of "${plugin.name}". If boot opens partial resources before throwing, clean them up locally — DOT only disposes plugins whose boot completed.`,
           docsAnchor: timedOut ? 'hook-timeout' : 'boot-failed',
           durationMs: performance.now() - started,
           cause: error,
@@ -852,18 +981,18 @@ export class DotAppImpl {
       record.booted = true;
 
       for (const [localKey, value] of Object.entries(publishedServices)) {
-        const wireKey = pip.renames[localKey] ?? localKey;
+        const wireKey = plugin.renames[localKey] ?? localKey;
         if (localKey.startsWith('$') || wireKey.startsWith('$')) {
-          // The pip() constraint bans this at compile time; erased pips can
-          // still reach here. A `$` publish would shadow $app/$pip/$config
-          // in the pip's own post-boot hook contexts.
+          // The plugin() constraint bans this at compile time; erased plugins can
+          // still reach here. A `$` publish would shadow $app/$plugin/$config
+          // in the plugin's own post-boot hook contexts.
           return fail({
             record,
             code: DotLifecycleErrorCode.ReservedServiceKey,
             message:
-              `Pip "${pip.name}" publishes service "${wireKey}" — the "$" prefix is reserved ` +
-              `for kernel context keys ($app, $pip, $config).`,
-            remediation: `Rename the "${wireKey}" key returned from the boot() hook of "${pip.name}" — "$"-prefixed keys would shadow the kernel context.`,
+              `Plugin "${plugin.name}" publishes service "${wireKey}" — the "$" prefix is reserved ` +
+              `for kernel context keys ($app, $plugin, $config).`,
+            remediation: `Rename the "${wireKey}" key returned from the boot() hook of "${plugin.name}" — "$"-prefixed keys would shadow the kernel context.`,
             docsAnchor: 'reserved-service-key',
             durationMs: performance.now() - started,
             rollback: [...bootedRecords, record],
@@ -871,19 +1000,19 @@ export class DotAppImpl {
         }
         if (this.#serviceMap.has(wireKey)) {
           const owner = this.#providerByWireKey.get(wireKey) ?? 'unknown';
-          // The current pip HAS booted — include it in the rollback.
+          // The current plugin HAS booted — include it in the rollback.
           return fail({
             record,
             code: DotLifecycleErrorCode.ServiceCollision,
-            message: `Pip "${pip.name}" publishes service "${wireKey}" which pip "${owner}" already provides.`,
-            remediation: `Mount one of the two with rename(pip, { '${wireKey}': '<newKey>' }) to keep both instances, or remove the duplicate provider.`,
+            message: `Plugin "${plugin.name}" publishes service "${wireKey}" which plugin "${owner}" already provides.`,
+            remediation: `Mount one of the two with rename(plugin, { '${wireKey}': '<newKey>' }) to keep both instances, or remove the duplicate provider.`,
             docsAnchor: 'service-collision',
             durationMs: performance.now() - started,
             rollback: [...bootedRecords, record],
           });
         }
         this.#serviceMap.set(wireKey, value);
-        this.#providerByWireKey.set(wireKey, pip.name);
+        this.#providerByWireKey.set(wireKey, plugin.name);
         this.#aggregatedServices[wireKey] = value;
         record.provides.add(wireKey);
       }
@@ -891,23 +1020,23 @@ export class DotAppImpl {
 
       const durationMs = performance.now() - started;
       record.lifecycleDiagnostics.push({
-        pip: pip.name,
+        plugin: plugin.name,
         hook: 'boot',
         state: 'booted',
         order: record.order,
         durationMs,
         issues: [],
       });
-      this.#emitHook('boot', pip.name, record.order, 'completed', { durationMs });
-      pipLogger.debug('boot: done', {
-        'dot.pip.duration.ms': durationMs,
-        'dot.pip.services.published': Object.keys(publishedServices).length,
+      this.#emitHook('boot', plugin.name, record.order, 'completed', { durationMs });
+      pluginLogger.debug('boot: done', {
+        'dot.plugin.duration.ms': durationMs,
+        'dot.plugin.services.published': Object.keys(publishedServices).length,
       });
     }
 
     this.#state = 'booted';
     this.#manifest = this.#buildManifest();
-    phaseLogger.debug('boot: complete', { 'dot.app.pip.count': this.#ordered.length });
+    phaseLogger.debug('boot: complete', { 'dot.app.plugin.count': this.#ordered.length });
   }
 
   /** Public start(). Boots first if needed. Idempotent + concurrent-safe. */
@@ -933,14 +1062,14 @@ export class DotAppImpl {
     }
     // From booted or stopped, run start hooks.
     const phaseLogger = this.#logger.withAttribute('dot.app.phase', 'start');
-    phaseLogger.debug('start: starting', { 'dot.app.pip.count': this.#ordered.length });
+    phaseLogger.debug('start: starting', { 'dot.app.plugin.count': this.#ordered.length });
 
     return this.#withPhaseEmitAsync('start', () =>
       withPhaseSpan(
         {
           appName: this.#appName,
           phase: 'start',
-          pipCount: this.#ordered.length,
+          pluginCount: this.#ordered.length,
           logger: phaseLogger,
         },
         () => this.#runStartInner(phaseLogger),
@@ -953,12 +1082,12 @@ export class DotAppImpl {
    * stays thin and the rollback-cascade error path stays readable.
    */
   async #runStartInner(phaseLogger: Logger): Promise<void> {
-    const startedRecords: PipRecord[] = [];
-    for (const pip of this.#ordered) {
-      const record = this.#records.get(pip.name)!;
-      const pipLogger = phaseLogger.withAttribute('dot.pip.name', pip.name);
-      if (!pip.hooks.start) {
-        pipLogger.debug('start: skipped (no hook)');
+    const startedRecords: PluginRecord[] = [];
+    for (const plugin of this.#ordered) {
+      const record = this.#records.get(plugin.name)!;
+      const pluginLogger = phaseLogger.withAttribute('dot.plugin.name', plugin.name);
+      if (!plugin.hooks.start) {
+        pluginLogger.debug('start: skipped (no hook)');
         continue;
       }
       record.hooks.add('start');
@@ -966,19 +1095,19 @@ export class DotAppImpl {
       const ctx = this.#buildHookCtx(record, 'start', true);
 
       const startedAt = performance.now();
-      this.#emitHook('start', pip.name, record.order, 'starting');
+      this.#emitHook('start', plugin.name, record.order, 'starting');
       try {
-        await this.#withHookBudget(pip.name, 'start', () =>
-          withPipHookSpan(
+        await this.#withHookBudget(plugin.name, 'start', () =>
+          withPluginHookSpan(
             {
               appName: this.#appName,
-              pipName: pip.name,
-              pipVersion: pip.version,
+              pluginName: plugin.name,
+              pluginVersion: plugin.version,
               hook: 'start',
               order: record.order,
-              logger: pipLogger,
+              logger: pluginLogger,
             },
-            () => pip.hooks.start!(ctx as never),
+            () => plugin.hooks.start!(ctx as never),
           ),
         );
       } catch (error) {
@@ -986,27 +1115,27 @@ export class DotAppImpl {
         const timedOut = error instanceof DotLifecycleError && error.code === DotLifecycleErrorCode.HookTimeout;
         const issue = makeIssue({
           code: timedOut ? DotLifecycleErrorCode.HookTimeout : DotLifecycleErrorCode.StartFailed,
-          pip: pip.name,
+          plugin: plugin.name,
           message: timedOut
             ? error.message
-            : `start hook threw for pip "${pip.name}": ${stringifyError(error)}`,
+            : `start hook threw for plugin "${plugin.name}": ${stringifyError(error)}`,
           remediation: timedOut
-            ? `Find the hang in the start() hook of "${pip.name}" — or raise defineApp's hookTimeoutMs. DOT rolls back as for any start failure.`
-            : `Fix the error in the start() hook of "${pip.name}". DOT will stop all already-started pips and dispose all booted pips in reverse order.`,
+            ? `Find the hang in the start() hook of "${plugin.name}" — or raise defineApp's hookTimeoutMs. DOT rolls back as for any start failure.`
+            : `Fix the error in the start() hook of "${plugin.name}". DOT will stop all already-started plugins and dispose all booted plugins in reverse order.`,
           docsAnchor: timedOut ? 'hook-timeout' : 'start-failed',
         });
         record.issues.push(issue);
         record.lifecycleDiagnostics.push({
-          pip: pip.name,
+          plugin: plugin.name,
           hook: 'start',
           state: 'failed',
           order: record.order,
           durationMs,
           issues: [issue],
         });
-        this.#emitHook('start', pip.name, record.order, 'failed', { durationMs, error });
+        this.#emitHook('start', plugin.name, record.order, 'failed', { durationMs, error });
 
-        pipLogger.error('start: FAILED — rolling back', {
+        pluginLogger.error('start: FAILED — rolling back', {
           'dot.app.rollback.started.count': startedRecords.length,
         });
         const stopFailures = await this.#runStopForRecords(reverseRecords(startedRecords), phaseLogger);
@@ -1018,7 +1147,7 @@ export class DotAppImpl {
         throw new DotLifecycleError({
           code: timedOut ? DotLifecycleErrorCode.HookTimeout : DotLifecycleErrorCode.StartFailed,
           phase: 'start',
-          pip: pip.name,
+          plugin: plugin.name,
           message: issue.message,
           cause: error,
           failures: failures.length > 0 ? failures : undefined,
@@ -1029,20 +1158,20 @@ export class DotAppImpl {
       startedRecords.push(record);
       const durationMs = performance.now() - startedAt;
       record.lifecycleDiagnostics.push({
-        pip: pip.name,
+        plugin: plugin.name,
         hook: 'start',
         state: 'started',
         order: record.order,
         durationMs,
         issues: [],
       });
-      this.#emitHook('start', pip.name, record.order, 'completed', { durationMs });
-      pipLogger.debug('start: done', { 'dot.pip.duration.ms': durationMs });
+      this.#emitHook('start', plugin.name, record.order, 'completed', { durationMs });
+      pluginLogger.debug('start: done', { 'dot.plugin.duration.ms': durationMs });
     }
 
     this.#state = 'started';
     this.#manifest = this.#buildManifest();
-    phaseLogger.debug('start: complete', { 'dot.app.pip.count': this.#ordered.length });
+    phaseLogger.debug('start: complete', { 'dot.app.plugin.count': this.#ordered.length });
   }
 
   /** Public stop(). Idempotent + concurrent-safe. */
@@ -1071,14 +1200,14 @@ export class DotAppImpl {
 
   async #runStop(): Promise<void> {
     const phaseLogger = this.#logger.withAttribute('dot.app.phase', 'stop');
-    phaseLogger.debug('stop: starting', { 'dot.app.pip.count': this.#ordered.length });
+    phaseLogger.debug('stop: starting', { 'dot.app.plugin.count': this.#ordered.length });
 
     return this.#withPhaseEmitAsync('stop', () =>
       withPhaseSpan(
         {
           appName: this.#appName,
           phase: 'stop',
-          pipCount: this.#ordered.length,
+          pluginCount: this.#ordered.length,
           logger: phaseLogger,
         },
         async () => {
@@ -1091,73 +1220,73 @@ export class DotAppImpl {
             throw new DotLifecycleError({
               code: DotLifecycleErrorCode.StopFailed,
               phase: 'stop',
-              message: `${failures.length} pip(s) failed during stop`,
+              message: `${failures.length} plugin(s) failed during stop`,
               failures,
             });
           }
-          phaseLogger.debug('stop: complete', { 'dot.app.pip.count': this.#ordered.length });
+          phaseLogger.debug('stop: complete', { 'dot.app.plugin.count': this.#ordered.length });
         },
       ),
     );
   }
 
-  async #runStopForRecords(records: readonly PipRecord[], phaseLogger: Logger): Promise<DotLifecyclePipFailure[]> {
-    const failures: DotLifecyclePipFailure[] = [];
+  async #runStopForRecords(records: readonly PluginRecord[], phaseLogger: Logger): Promise<DotLifecyclePluginFailure[]> {
+    const failures: DotLifecyclePluginFailure[] = [];
     for (const record of records) {
-      if (!record.pip.hooks.stop) continue;
-      const pipLogger = phaseLogger.withAttribute('dot.pip.name', record.pip.name);
+      if (!record.plugin.hooks.stop) continue;
+      const pluginLogger = phaseLogger.withAttribute('dot.plugin.name', record.plugin.name);
       record.hooks.add('stop');
       const ctx = this.#buildHookCtx(record, 'stop', true);
       const startedAt = performance.now();
-      this.#emitHook('stop', record.pip.name, record.order, 'starting');
+      this.#emitHook('stop', record.plugin.name, record.order, 'starting');
       try {
-        await this.#withHookBudget(record.pip.name, 'stop', () =>
-          withPipHookSpan(
+        await this.#withHookBudget(record.plugin.name, 'stop', () =>
+          withPluginHookSpan(
             {
               appName: this.#appName,
-              pipName: record.pip.name,
-              pipVersion: record.pip.version,
+              pluginName: record.plugin.name,
+              pluginVersion: record.plugin.version,
               hook: 'stop',
               order: record.order,
-              logger: pipLogger,
+              logger: pluginLogger,
             },
-            () => record.pip.hooks.stop!(ctx as never),
+            () => record.plugin.hooks.stop!(ctx as never),
           ),
         );
         record.started = false;
         const durationMs = performance.now() - startedAt;
         record.lifecycleDiagnostics.push({
-          pip: record.pip.name,
+          plugin: record.plugin.name,
           hook: 'stop',
           state: 'stopped',
           order: record.order,
           durationMs,
           issues: [],
         });
-        this.#emitHook('stop', record.pip.name, record.order, 'completed', { durationMs });
-        pipLogger.debug('stop: done', { 'dot.pip.duration.ms': durationMs });
+        this.#emitHook('stop', record.plugin.name, record.order, 'completed', { durationMs });
+        pluginLogger.debug('stop: done', { 'dot.plugin.duration.ms': durationMs });
       } catch (error) {
         const durationMs = performance.now() - startedAt;
         const issue = makeIssue({
           code: DotLifecycleErrorCode.StopFailed,
-          pip: record.pip.name,
-          message: `stop hook threw for pip "${record.pip.name}": ${stringifyError(error)}`,
-          remediation: `Fix the error in the stop() hook of "${record.pip.name}". Stop continues through individual failures and reports an aggregate error.`,
+          plugin: record.plugin.name,
+          message: `stop hook threw for plugin "${record.plugin.name}": ${stringifyError(error)}`,
+          remediation: `Fix the error in the stop() hook of "${record.plugin.name}". Stop continues through individual failures and reports an aggregate error.`,
           docsAnchor: 'stop-failed',
         });
         record.issues.push(issue);
         record.lifecycleDiagnostics.push({
-          pip: record.pip.name,
+          plugin: record.plugin.name,
           hook: 'stop',
           state: 'failed',
           order: record.order,
           durationMs,
           issues: [issue],
         });
-        this.#emitHook('stop', record.pip.name, record.order, 'failed', { durationMs, error });
-        failures.push({ pip: record.pip.name, phase: 'stop', error });
-        pipLogger.error('stop: failed (continuing)', {
-          'dot.pip.error.message': stringifyError(error),
+        this.#emitHook('stop', record.plugin.name, record.order, 'failed', { durationMs, error });
+        failures.push({ plugin: record.plugin.name, phase: 'stop', error });
+        pluginLogger.error('stop: failed (continuing)', {
+          'dot.plugin.error.message': stringifyError(error),
         });
       }
     }
@@ -1181,14 +1310,14 @@ export class DotAppImpl {
 
   async #runDispose(): Promise<void> {
     const phaseLogger = this.#logger.withAttribute('dot.app.phase', 'dispose');
-    phaseLogger.debug('dispose: starting', { 'dot.app.pip.count': this.#ordered.length });
+    phaseLogger.debug('dispose: starting', { 'dot.app.plugin.count': this.#ordered.length });
 
     return this.#withPhaseEmitAsync('dispose', () =>
       withPhaseSpan(
         {
           appName: this.#appName,
           phase: 'dispose',
-          pipCount: this.#ordered.length,
+          pluginCount: this.#ordered.length,
           logger: phaseLogger,
         },
         () => this.#runDisposeInner(phaseLogger),
@@ -1221,7 +1350,7 @@ export class DotAppImpl {
         throw new DotLifecycleError({
           code: DotLifecycleErrorCode.DisposeFailed,
           phase: 'dispose',
-          message: `${failures.length} pip(s) failed during stop+dispose cascade`,
+          message: `${failures.length} plugin(s) failed during stop+dispose cascade`,
           failures,
         });
       }
@@ -1229,7 +1358,7 @@ export class DotAppImpl {
       return;
     }
 
-    // From booted/stopped/configured/defined: only dispose booted pips.
+    // From booted/stopped/configured/defined: only dispose booted plugins.
     if (this.#state === 'failed') {
       // Already cleaned up at the failure site — mark disposed.
       this.#state = 'disposed';
@@ -1247,15 +1376,15 @@ export class DotAppImpl {
       throw new DotLifecycleError({
         code: DotLifecycleErrorCode.DisposeFailed,
         phase: 'dispose',
-        message: `${failures.length} pip(s) failed during dispose`,
+        message: `${failures.length} plugin(s) failed during dispose`,
         failures,
       });
     }
-    phaseLogger.debug('dispose: complete', { 'dot.app.pip.count': this.#ordered.length });
+    phaseLogger.debug('dispose: complete', { 'dot.app.plugin.count': this.#ordered.length });
   }
 
-  async #runDisposeForRecords(records: readonly PipRecord[], phaseLogger: Logger): Promise<DotLifecyclePipFailure[]> {
-    const failures: DotLifecyclePipFailure[] = [];
+  async #runDisposeForRecords(records: readonly PluginRecord[], phaseLogger: Logger): Promise<DotLifecyclePluginFailure[]> {
+    const failures: DotLifecyclePluginFailure[] = [];
 
     // A lazy handle can be published under several keys — a `service.lazy`
     // consumer republishing its provider's handle passes it through by
@@ -1263,8 +1392,8 @@ export class DotAppImpl {
     // (declaration order): dispose runs in reverse, so cleaning the handle
     // with a republisher would kill it before the original provider's own
     // dispose hook gets to use it. `records` arrives reversed, so plain
-    // overwrite leaves the earliest-declared pip as each handle's owner.
-    const ownerOf = new Map<Lazy<unknown>, PipRecord>();
+    // overwrite leaves the earliest-declared plugin as each handle's owner.
+    const ownerOf = new Map<Lazy<unknown>, PluginRecord>();
     for (const record of records) {
       for (const value of Object.values(record.publishedServices)) {
         if (isLazy(value)) ownerOf.set(value, record);
@@ -1281,16 +1410,16 @@ export class DotAppImpl {
           return true;
         },
       );
-      const hasHook = record.pip.hooks.dispose !== undefined;
+      const hasHook = record.plugin.hooks.dispose !== undefined;
       if (!hasHook && lazyPublishes.length === 0) {
         record.booted = false;
         continue;
       }
-      const pipLogger = phaseLogger.withAttribute('dot.pip.name', record.pip.name);
+      const pluginLogger = phaseLogger.withAttribute('dot.plugin.name', record.plugin.name);
       if (hasHook) {
-        await this.#runDisposeHook(record, pipLogger, failures);
+        await this.#runDisposeHook(record, pluginLogger, failures);
       }
-      // Auto-dispose lazy service handles AFTER the pip's own dispose hook
+      // Auto-dispose lazy service handles AFTER the plugin's own dispose hook
       // (the hook may still use them). Never-initialized handles no-op.
       for (const [serviceKey, handle] of lazyPublishes) {
         try {
@@ -1298,16 +1427,16 @@ export class DotAppImpl {
         } catch (error) {
           const issue = makeIssue({
             code: DotLifecycleErrorCode.DisposeFailed,
-            pip: record.pip.name,
-            message: `lazy service "${serviceKey}" cleanup threw for pip "${record.pip.name}": ${stringifyError(error)}`,
+            plugin: record.plugin.name,
+            message: `lazy service "${serviceKey}" cleanup threw for plugin "${record.plugin.name}": ${stringifyError(error)}`,
             remediation: `Fix the error in the dispose callback passed to lazy(...) for service "${serviceKey}". Dispose continues through individual failures and reports an aggregate error.`,
             docsAnchor: 'dispose-failed',
           });
           record.issues.push(issue);
-          failures.push({ pip: record.pip.name, phase: 'dispose', error });
-          pipLogger.error('dispose: lazy service cleanup failed (continuing)', {
-            'dot.pip.service.key': serviceKey,
-            'dot.pip.error.message': stringifyError(error),
+          failures.push({ plugin: record.plugin.name, phase: 'dispose', error });
+          pluginLogger.error('dispose: lazy service cleanup failed (continuing)', {
+            'dot.plugin.service.key': serviceKey,
+            'dot.plugin.error.message': stringifyError(error),
           });
         }
       }
@@ -1318,60 +1447,60 @@ export class DotAppImpl {
     return failures;
   }
 
-  /** Run a single pip's dispose hook with spans/events/diagnostics. */
-  async #runDisposeHook(record: PipRecord, pipLogger: Logger, failures: DotLifecyclePipFailure[]): Promise<void> {
+  /** Run a single plugin's dispose hook with spans/events/diagnostics. */
+  async #runDisposeHook(record: PluginRecord, pluginLogger: Logger, failures: DotLifecyclePluginFailure[]): Promise<void> {
       record.hooks.add('dispose');
       const ctx = this.#buildHookCtx(record, 'dispose', true);
       const startedAt = performance.now();
-      this.#emitHook('dispose', record.pip.name, record.order, 'starting');
+      this.#emitHook('dispose', record.plugin.name, record.order, 'starting');
       try {
-        await this.#withHookBudget(record.pip.name, 'dispose', () =>
-          withPipHookSpan(
+        await this.#withHookBudget(record.plugin.name, 'dispose', () =>
+          withPluginHookSpan(
             {
               appName: this.#appName,
-              pipName: record.pip.name,
-              pipVersion: record.pip.version,
+              pluginName: record.plugin.name,
+              pluginVersion: record.plugin.version,
               hook: 'dispose',
               order: record.order,
-              logger: pipLogger,
+              logger: pluginLogger,
             },
-            () => record.pip.hooks.dispose!(ctx as never),
+            () => record.plugin.hooks.dispose!(ctx as never),
           ),
         );
         record.booted = false;
         const durationMs = performance.now() - startedAt;
         record.lifecycleDiagnostics.push({
-          pip: record.pip.name,
+          plugin: record.plugin.name,
           hook: 'dispose',
           state: 'disposed',
           order: record.order,
           durationMs,
           issues: [],
         });
-        this.#emitHook('dispose', record.pip.name, record.order, 'completed', { durationMs });
-        pipLogger.debug('dispose: done', { 'dot.pip.duration.ms': durationMs });
+        this.#emitHook('dispose', record.plugin.name, record.order, 'completed', { durationMs });
+        pluginLogger.debug('dispose: done', { 'dot.plugin.duration.ms': durationMs });
       } catch (error) {
         const durationMs = performance.now() - startedAt;
         const issue = makeIssue({
           code: DotLifecycleErrorCode.DisposeFailed,
-          pip: record.pip.name,
-          message: `dispose hook threw for pip "${record.pip.name}": ${stringifyError(error)}`,
-          remediation: `Fix the error in the dispose() hook of "${record.pip.name}". Dispose continues through individual failures and reports an aggregate error.`,
+          plugin: record.plugin.name,
+          message: `dispose hook threw for plugin "${record.plugin.name}": ${stringifyError(error)}`,
+          remediation: `Fix the error in the dispose() hook of "${record.plugin.name}". Dispose continues through individual failures and reports an aggregate error.`,
           docsAnchor: 'dispose-failed',
         });
         record.issues.push(issue);
         record.lifecycleDiagnostics.push({
-          pip: record.pip.name,
+          plugin: record.plugin.name,
           hook: 'dispose',
           state: 'failed',
           order: record.order,
           durationMs,
           issues: [issue],
         });
-        this.#emitHook('dispose', record.pip.name, record.order, 'failed', { durationMs, error });
-        failures.push({ pip: record.pip.name, phase: 'dispose', error });
-        pipLogger.error('dispose: failed (continuing)', {
-          'dot.pip.error.message': stringifyError(error),
+        this.#emitHook('dispose', record.plugin.name, record.order, 'failed', { durationMs, error });
+        failures.push({ plugin: record.plugin.name, phase: 'dispose', error });
+        pluginLogger.error('dispose: failed (continuing)', {
+          'dot.plugin.error.message': stringifyError(error),
         });
       }
   }
@@ -1388,67 +1517,72 @@ export class DotAppImpl {
   }
 
   #buildManifest(): DotAppManifest {
-    const pips: PipManifest[] = [];
-    const routes: RouteManifest[] = [];
+    const plugins: PluginManifest[] = [];
+    const actions: ActionManifest[] = [];
     const services: ServiceManifest[] = [];
     const lifecycle: LifecycleManifest[] = [];
-    // Edges are observed at boot time: consumer pip → the pip whose
-    // published wire key satisfied its need. Before boot, the per-pip
+    const projections: ProjectionManifest[] = [];
+    // Edges are observed at boot time: consumer plugin → the plugin whose
+    // published wire key satisfied its need. Before boot, the per-plugin
     // `dependencies` array (wire-key strings) is the declarative view.
     const dependencies: DependencyEdge[] = this.#wiringEdges.map(e => ({ ...e }));
 
-    for (const pip of this.#ordered) {
-      const record = this.#records.get(pip.name)!;
-      const needWireKeys = Object.entries(pip.needs).map(([alias, witness]) => wireKeyOf(witness, alias));
-      pips.push({
-        name: pip.name,
-        version: pip.version,
+    for (const plugin of this.#ordered) {
+      const record = this.#records.get(plugin.name)!;
+      const needWireKeys = Object.entries(plugin.needs).map(([alias, witness]) => wireKeyOf(witness, alias));
+      plugins.push({
+        name: plugin.name,
+        version: plugin.version,
         dependencies: needWireKeys,
         provides: [...record.provides],
       });
-      routes.push(...record.routes);
+      actions.push(...record.actions);
       services.push(...record.services);
+      projections.push(...record.projections);
       lifecycle.push({
-        pip: pip.name,
+        plugin: plugin.name,
         hooks: [...record.hooks],
       });
     }
 
     return {
+      manifestVersion: 2,
       app: {
         name: this.#appName,
         version: this.#appVersion,
       },
-      pips,
-      routes,
+      plugins,
+      actions,
       services,
       lifecycle,
       dependencies,
+      projections,
     };
   }
 
   #buildDiagnostics(): DotDiagnosticsSnapshot {
-    const pipDiagnostics: PipDiagnostic[] = [];
-    const routeDiagnostics: RouteDiagnostic[] = [];
+    const pluginDiagnostics: PluginDiagnostic[] = [];
+    const actionDiagnostics: ActionDiagnostic[] = [];
     const serviceDiagnostics: ServiceDiagnostic[] = [];
     const lifecycleDiagnostics: LifecycleDiagnostic[] = [];
     const issues: DiagnosticIssue[] = [];
 
-    for (const pip of this.#ordered) {
-      const record = this.#records.get(pip.name)!;
-      // Per-pip status: failed if any issue with severity error exists, ok otherwise.
+    for (const plugin of this.#ordered) {
+      const record = this.#records.get(plugin.name)!;
+      // Per-plugin status: failed if any issue with severity error exists, ok otherwise.
       const hasError = record.issues.some(i => i.severity === 'error');
-      const status: PipDiagnostic['status'] = hasError ? 'failed' : 'ok';
-      pipDiagnostics.push({
-        pip: pip.name,
+      const status: PluginDiagnostic['status'] = hasError ? 'failed' : 'ok';
+      pluginDiagnostics.push({
+        plugin: plugin.name,
         status,
         issues: [...record.issues],
       });
 
-      for (const route of record.routes) {
-        routeDiagnostics.push({
-          id: route.id,
-          pip: pip.name,
+      for (const action of record.actions) {
+        actionDiagnostics.push({
+          id: action.id,
+          plugin: plugin.name,
+          binding: action.binding,
           status: hasError ? 'failed' : 'ok',
           issues: [],
         });
@@ -1456,7 +1590,7 @@ export class DotAppImpl {
       for (const svc of record.services) {
         serviceDiagnostics.push({
           service: svc.name,
-          pip: pip.name,
+          plugin: plugin.name,
           status: hasError
             ? 'failed'
             : record.booted || this.#state === 'defined' || this.#state === 'configured'
@@ -1470,13 +1604,14 @@ export class DotAppImpl {
     }
 
     return {
+      snapshotVersion: 2,
       generatedAt: new Date().toISOString(),
       app: {
         name: this.#appName,
         state: this.#state,
       },
-      pips: pipDiagnostics,
-      routes: routeDiagnostics,
+      plugins: pluginDiagnostics,
+      actions: actionDiagnostics,
       services: serviceDiagnostics,
       lifecycle: lifecycleDiagnostics,
       issues,
@@ -1503,12 +1638,23 @@ function stringifyError(error: unknown): string {
   }
 }
 
-function reverseRecords(records: readonly PipRecord[]): readonly PipRecord[] {
+function reverseRecords(records: readonly PluginRecord[]): readonly PluginRecord[] {
   // eslint-disable-next-line unicorn/no-array-reverse -- lib target is ES2022, toReversed is ES2023.
   return [...records].reverse();
 }
 
-/** Re-export `ServiceKind` and `RouteTransport` for the kernel's internal use. */
+function hasToDotAction(
+  source: AnyPlugin['actions'][number],
+): source is { toDotAction(): Omit<ActionManifest, 'plugin'> } {
+  return (
+    typeof source === 'object' &&
+    source !== null &&
+    'toDotAction' in source &&
+    typeof source.toDotAction === 'function'
+  );
+}
+
+/** Re-export `ServiceKind` for the kernel's internal use. */
 
-export { type RouteTransport, type ServiceKind } from '../manifest.js';
-export { type Pip } from '../pip-contract.js';
+export { type ServiceKind } from '../manifest.js';
+export { type Plugin } from '../plugin-contract.js';