@arki/dot 0.2.0 → 0.4.0

package/src/cli/render-explain.ts

@@ -70,14 +70,14 @@ function renderTextManifest(manifest: DotAppManifest): string {
   lines.push('='.repeat(title.length));
   lines.push('');
 
-  // Pips
-  lines.push(`Pips (${manifest.pips.length})`);
-  if (manifest.pips.length === 0) {
+  // Plugins
+  lines.push(`Plugins (${manifest.plugins.length})`);
+  if (manifest.plugins.length === 0) {
     lines.push('  (none)');
   } else {
-    const widthName = Math.max(6, ...manifest.pips.map(p => p.name.length));
+    const widthName = Math.max(6, ...manifest.plugins.map(p => p.name.length));
     lines.push(`  ${pad('NAME', widthName)}  VERSION  DEPENDENCIES`);
-    for (const p of manifest.pips) {
+    for (const p of manifest.plugins) {
       const version = p.version ?? '-';
       const deps = p.dependencies.length > 0 ? p.dependencies.join(', ') : '-';
       lines.push(`  ${pad(p.name, widthName)}  ${pad(version, 7)}  ${deps}`);
@@ -94,23 +94,41 @@ function renderTextManifest(manifest: DotAppManifest): string {
     const widthKind = Math.max(4, ...manifest.services.map(s => s.kind.length));
     lines.push(`  ${pad('NAME', widthName)}  ${pad('KIND', widthKind)}  PLUGIN`);
     for (const s of manifest.services) {
-      lines.push(`  ${pad(s.name, widthName)}  ${pad(s.kind, widthKind)}  ${s.pip}`);
+      lines.push(`  ${pad(s.name, widthName)}  ${pad(s.kind, widthKind)}  ${s.plugin}`);
     }
   }
   lines.push('');
 
-  // Routes
-  lines.push(`Routes (${manifest.routes.length})`);
-  if (manifest.routes.length === 0) {
+  // Actions
+  lines.push(`Actions (${manifest.actions.length})`);
+  if (manifest.actions.length === 0) {
     lines.push('  (none)');
   } else {
-    const widthId = Math.max(2, ...manifest.routes.map(r => r.id.length));
-    const widthMethod = Math.max(6, ...manifest.routes.map(r => (r.method ?? '-').length));
-    lines.push(`  ${pad('ID', widthId)}  ${pad('METHOD', widthMethod)}  PATH/TRANSPORT  PLUGIN`);
-    for (const r of manifest.routes) {
-      const method = r.method ?? '-';
-      const target = r.path ?? `(${r.transport})`;
-      lines.push(`  ${pad(r.id, widthId)}  ${pad(method, widthMethod)}  ${pad(target, 14)}  ${r.pip}`);
+    const widthId = Math.max(2, ...manifest.actions.map(action => action.id.length));
+    const widthBinding = Math.max(7, ...manifest.actions.map(action => action.binding.length));
+    const widthAddress = Math.max(7, ...manifest.actions.map(action => (action.address ?? '-').length));
+    lines.push(`  ${pad('ID', widthId)}  ${pad('BINDING', widthBinding)}  DIR  ${pad('ADDRESS', widthAddress)}  PLUGIN`);
+    for (const action of manifest.actions) {
+      lines.push(
+        `  ${pad(action.id, widthId)}  ${pad(action.binding, widthBinding)}  ${pad(action.direction, 3)}  ${pad(action.address ?? '-', widthAddress)}  ${action.plugin}`,
+      );
+    }
+  }
+  lines.push('');
+
+  // Projections
+  lines.push(`Projections (${manifest.projections.length})`);
+  if (manifest.projections.length === 0) {
+    lines.push('  (none)');
+  } else {
+    const widthFormat = Math.max(6, ...manifest.projections.map(projection => projection.format.length));
+    const widthBinding = Math.max(7, ...manifest.projections.map(projection => projection.binding.length));
+    const widthModule = Math.max(6, ...manifest.projections.map(projection => projection.module.length));
+    lines.push(`  ${pad('FORMAT', widthFormat)}  ${pad('BINDING', widthBinding)}  ${pad('MODULE', widthModule)}  PLUGIN`);
+    for (const projection of manifest.projections) {
+      lines.push(
+        `  ${pad(projection.format, widthFormat)}  ${pad(projection.binding, widthBinding)}  ${pad(projection.module, widthModule)}  ${projection.plugin}`,
+      );
     }
   }
   lines.push('');
@@ -131,11 +149,11 @@ function renderTextManifest(manifest: DotAppManifest): string {
   if (manifest.lifecycle.length === 0) {
     lines.push('  (none)');
   } else {
-    const widthPip = Math.max(6, ...manifest.lifecycle.map(l => l.pip.length));
-    lines.push(`  ${pad('PLUGIN', widthPip)}  HOOKS`);
+    const widthPlugin = Math.max(6, ...manifest.lifecycle.map(l => l.plugin.length));
+    lines.push(`  ${pad('PLUGIN', widthPlugin)}  HOOKS`);
     for (const l of manifest.lifecycle) {
       const hooks = l.hooks.length > 0 ? l.hooks.join(', ') : '-';
-      lines.push(`  ${pad(l.pip, widthPip)}  ${hooks}`);
+      lines.push(`  ${pad(l.plugin, widthPlugin)}  ${hooks}`);
     }
   }
   lines.push('');

package/src/cli/render-graph.ts

@@ -1,12 +1,12 @@
 /**
  * Renderer for `dot explain --graph` / `dot doctor --graph`.
  *
- * Emits the app's pip graph as [Mermaid](https://mermaid.js.org) `flowchart`
+ * Emits the app's plugin graph as [Mermaid](https://mermaid.js.org) `flowchart`
  * source — paste-able into GitHub markdown, docs, and mermaid.live.
  *
- * The nodes are the pips in declaration order (which IS boot order in v2 —
+ * The nodes are the plugins in declaration order (which IS boot order in v2 —
  * the numbering makes that visible); the edges are the manifest's
- * **observed** dependency edges, recorded by the kernel when a pip's need
+ * **observed** dependency edges, recorded by the kernel when a plugin's need
  * was satisfied during boot. `explain` never boots, so its graph shows
  * declaration order with whatever edges configure-time metadata declared;
  * `doctor` boots, so its graph shows the real wiring.
@@ -22,7 +22,7 @@ export type GraphData = {
   source: string;
 };
 
-/** Escape a pip name for use inside a quoted Mermaid node label. */
+/** Escape a plugin name for use inside a quoted Mermaid node label. */
 function escapeLabel(name: string): string {
   return name.replaceAll('"', '#quot;');
 }
@@ -33,20 +33,20 @@ function escapeLabel(name: string): string {
  */
 export function buildMermaidGraph(manifest: DotAppManifest): string {
   const lines: string[] = ['flowchart TD'];
-  const idByPip = new Map<string, string>();
+  const idByPlugin = new Map<string, string>();
 
-  for (const [index, pip] of manifest.pips.entries()) {
+  for (const [index, plugin] of manifest.plugins.entries()) {
     const id = `p${index.toString()}`;
-    idByPip.set(pip.name, id);
+    idByPlugin.set(plugin.name, id);
     const order = (index + 1).toString();
-    const version = pip.version === undefined ? '' : `@${pip.version}`;
-    lines.push(`  ${id}["${order} · ${escapeLabel(pip.name)}${escapeLabel(version)}"]`);
+    const version = plugin.version === undefined ? '' : `@${plugin.version}`;
+    lines.push(`  ${id}["${order} · ${escapeLabel(plugin.name)}${escapeLabel(version)}"]`);
   }
 
   for (const edge of manifest.dependencies) {
-    const from = idByPip.get(edge.from);
-    const to = idByPip.get(edge.to);
-    // Edges referencing unknown pips would be a kernel bug — skip rather
+    const from = idByPlugin.get(edge.from);
+    const to = idByPlugin.get(edge.to);
+    // Edges referencing unknown plugins would be a kernel bug — skip rather
     // than emit invalid Mermaid.
     if (from === undefined || to === undefined) continue;
     lines.push(`  ${from} -->|${edge.kind}| ${to}`);

package/src/cli/render-projection.ts

@@ -0,0 +1,239 @@
+/**
+ * Renderer for `dot explain --as <format>`.
+ *
+ * The kernel owns selection, app-file-relative module resolution, import, and
+ * envelope printing. The adapter owns the projection module and document
+ * vocabulary.
+ */
+
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import type { DotAppManifest, JsonValue, ProjectionManifest } from '../manifest.js';
+import type { DotCliEnvelope, RenderOptions } from './render-explain.js';
+import { DotCliError, DotCliErrorCode } from './error-codes.js';
+
+export type ProjectionData = {
+  format: string;
+  document: JsonValue;
+};
+
+type ProjectionModule = {
+  project(manifest: DotAppManifest): unknown | Promise<unknown>;
+};
+
+export type ProjectionSource = {
+  manifest: DotAppManifest;
+  command: 'explain';
+  format: string;
+  /** Absolute app file path; projection specifiers resolve relative to it. */
+  appFilePath: string;
+  /** Per-invocation debug override for the selected projection module. */
+  module?: string;
+};
+
+const defaultOut = (line: string) => {
+  process.stdout.write(line);
+};
+
+function nowIso(opts: RenderOptions): string {
+  const factory = opts.now ?? (() => new Date());
+  return factory().toISOString();
+}
+
+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 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;
+}
+
+function toProjectionJsonValue(value: unknown): JsonValue {
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(value);
+  } catch (error) {
+    throw new TypeError('Projection output must be JSON-serializable.', { cause: error });
+  }
+  if (serialized === undefined) {
+    throw new TypeError('Projection output must be JSON-serializable.');
+  }
+  const parsed = JSON.parse(serialized) as unknown;
+  if (!isJsonValue(parsed) || !jsonDeepEqual(value, parsed)) {
+    throw new TypeError('Projection output must survive a JSON round trip without lossy coercions.');
+  }
+  return parsed;
+}
+
+function selectProjection(manifest: DotAppManifest, format: string): ProjectionManifest {
+  const projections = manifest.projections.filter(projection => projection.format === format);
+  if (projections.length === 0) {
+    const formats = [...new Set(manifest.projections.map(projection => projection.format))];
+    throw new DotCliError({
+      code: DotCliErrorCode.ProjectionNotFound,
+      message: `No projection is registered for format "${format}".`,
+      remediation:
+        formats.length === 0
+          ? 'Register an adapter that contributes this projection format, or remove --as.'
+          : `Use one of the registered formats (${formats.join(', ')}), or mount the adapter that provides "${format}".`,
+      metadata: { format, registeredFormats: formats },
+    });
+  }
+
+  const modules = new Set(projections.map(projection => projection.module));
+  if (modules.size > 1) {
+    throw new DotCliError({
+      code: DotCliErrorCode.ProjectionConflict,
+      message: `Multiple projection modules are registered for format "${format}".`,
+      remediation:
+        'Only one module may own a projection format. Remove one registration, or make both plugins register the same module specifier.',
+      metadata: {
+        format,
+        projections: projections.map(projection => ({ plugin: projection.plugin, module: projection.module })),
+      },
+    });
+  }
+
+  return projections[0]!;
+}
+
+function getBunResolver(): { resolveSync(specifier: string, from: string): string } | undefined {
+  const candidate = (globalThis as { Bun?: unknown }).Bun;
+  if (typeof candidate !== 'object' || candidate === null) return undefined;
+  const resolveSync = (candidate as { resolveSync?: unknown }).resolveSync;
+  if (typeof resolveSync !== 'function') return undefined;
+  return { resolveSync: (specifier, from) => resolveSync.call(candidate, specifier, from) as string };
+}
+
+function importSpecifierFor(resolved: string): string {
+  if (resolved.startsWith('file:')) return resolved;
+  if (isAbsolute(resolved)) return pathToFileURL(resolved).href;
+  return resolved;
+}
+
+function resolveProjectionSpecifier(specifier: string, appFilePath: string): string {
+  const fromDir = dirname(appFilePath);
+  const bun = getBunResolver();
+  if (bun !== undefined) return bun.resolveSync(specifier, fromDir);
+  return createRequire(appFilePath).resolve(specifier);
+}
+
+async function loadProjectionModule(
+  specifier: string,
+  appFilePath: string,
+  registeringPlugin: string,
+): Promise<{ module: ProjectionModule; resolved: string }> {
+  let resolved: string;
+  try {
+    resolved = resolveProjectionSpecifier(specifier, appFilePath);
+  } catch (error) {
+    throw new DotCliError({
+      code: DotCliErrorCode.ProjectionImportFailed,
+      message: `Failed to resolve projection module "${specifier}".`,
+      remediation:
+        'Check that the projection module is installed and that package subpath exports include a default condition. Use --module <specifier> to debug with a replacement module.',
+      metadata: { specifier, appFilePath, registeringPlugin },
+      cause: error,
+    });
+  }
+
+  let imported: unknown;
+  try {
+    imported = await import(importSpecifierFor(resolved));
+  } catch (error) {
+    throw new DotCliError({
+      code: DotCliErrorCode.ProjectionImportFailed,
+      message: `Failed to import projection module "${specifier}".`,
+      remediation:
+        'Fix the projection module export, or use --module <specifier> to debug with a replacement module.',
+      metadata: { specifier, resolved, registeringPlugin },
+      cause: error,
+    });
+  }
+
+  if (typeof imported !== 'object' || imported === null || typeof (imported as { project?: unknown }).project !== 'function') {
+    throw new DotCliError({
+      code: DotCliErrorCode.ProjectionImportFailed,
+      message: `Projection module "${specifier}" does not export project(manifest).`,
+      remediation:
+        'Export a named `project(manifest)` function from the projection module. Use --module <specifier> to test a corrected module.',
+      metadata: { specifier, resolved, registeringPlugin },
+    });
+  }
+
+  return { module: imported as ProjectionModule, resolved };
+}
+
+/**
+ * Render an adapter-owned projection. Plain mode prints strings verbatim and
+ * JSON values as pretty JSON; JSON mode wraps the document in the standard
+ * CLI envelope.
+ */
+export async function renderProjection(
+  source: ProjectionSource,
+  opts: RenderOptions,
+): Promise<DotCliEnvelope<ProjectionData>> {
+  const projection = selectProjection(source.manifest, source.format);
+  const specifier = source.module ?? projection.module;
+  const { module } = await loadProjectionModule(specifier, source.appFilePath, projection.plugin);
+
+  let document: JsonValue;
+  try {
+    document = toProjectionJsonValue(await module.project(source.manifest));
+  } catch (error) {
+    throw new DotCliError({
+      code: DotCliErrorCode.ProjectionExecutionFailed,
+      message: `Projection "${source.format}" failed while rendering.`,
+      remediation:
+        'Fix the projection project(manifest) function so it is pure and returns JSON-round-trip-safe output.',
+      metadata: { format: source.format, specifier, registeringPlugin: projection.plugin },
+      cause: error,
+    });
+  }
+
+  const envelope: DotCliEnvelope<ProjectionData> = {
+    status: 'success',
+    command: source.command,
+    generatedAt: nowIso(opts),
+    data: { format: source.format, document },
+    errors: [],
+  };
+
+  const out = opts.out ?? defaultOut;
+  if (opts.json) {
+    out(`${JSON.stringify(envelope, null, 2)}\n`);
+  } else if (typeof document === 'string') {
+    out(`${document}\n`);
+  } else {
+    out(`${JSON.stringify(document, null, 2)}\n`);
+  }
+
+  return envelope;
+}

package/src/define-app.ts

@@ -1,12 +1,12 @@
 /**
  * Public entry point for the DOT kernel (v2).
  *
- * `defineApp(name)` returns a `DotAppBuilder` that accumulates pips via
- * `.use(pip)`, then transitions through the 5-hook lifecycle:
+ * `defineApp(name)` returns a `DotAppBuilder` that accumulates plugins via
+ * `.use(plugin)`, then transitions through the 5-hook lifecycle:
  *
  *   defineApp -> use* -> configure() -> boot() -> start() -> stop() -> dispose()
  *
- * `.use()` is compile-time guarded: a pip whose `needs` are not satisfied
+ * `.use()` is compile-time guarded: a plugin whose `needs` are not satisfied
  * by services provided so far — or whose provides collide with existing
  * wire keys — fails to typecheck at the call site ("Expected 2 arguments,
  * but got 1", with the diagnostic embedded in the expected second
@@ -23,7 +23,7 @@ import type { DotDiagnosticsSnapshot } from './diagnostics.js';
 import type { DotLifecycleObserver } from './lifecycle-observer.js';
 import type { DotLifecycleState } from './lifecycle.js';
 import type { DotAppManifest } from './manifest.js';
-import type { AnyPip, EmptyShape, Pip, ServiceRecord } from './pip-contract.js';
+import type { AnyPlugin, EmptyShape, Plugin, ServiceRecord } from './plugin-contract.js';
 import { DotAppImpl } from './kernel/app-instance.js';
 import { renderTimeline } from './timeline.js';
 
@@ -43,26 +43,26 @@ type MismatchedKeys<TAvail, TNeeds> = {
 };
 
 type NeedsError<TAvail extends ServiceRecord, TNeeds extends ServiceRecord> = {
-  readonly 'DOT: pip needs services no earlier .use() provides': {
+  readonly 'DOT: plugin needs services no earlier .use() provides': {
     readonly missing: MissingKeys<TAvail, TNeeds>;
     readonly mismatched: MismatchedKeys<TAvail, TNeeds>;
   };
 };
 
 type CollisionError<TAvail, TProvides> = {
-  readonly 'DOT: pip provides wire keys already provided (use rename())': keyof TAvail & keyof TProvides;
+  readonly 'DOT: plugin provides wire keys already provided (use rename())': keyof TAvail & keyof TProvides;
 };
 
 /**
- * A pip whose `boot` always throws infers `TProvides = never`, which would
+ * A plugin whose `boot` always throws infers `TProvides = never`, which would
  * poison both the collision check (`keyof never` matches everything) and
- * the accumulated record (`TAvail & never` = `never`). Such a pip provides
+ * the accumulated record (`TAvail & never` = `never`). Such a plugin provides
  * nothing — normalize to the empty shape.
  */
-type NormalizeProvides<TP extends ServiceRecord> = [TP] extends [never] ? EmptyShape : TP;
+export type NormalizeProvides<TP extends ServiceRecord> = [TP] extends [never] ? EmptyShape : TP;
 
 /**
- * Rest-tuple guard. Satisfied → `[]` (call `.use(pip)` with one argument).
+ * Rest-tuple guard. Satisfied → `[]` (call `.use(plugin)` with one argument).
  * Violated → a required second argument of an unconstructible error type,
  * so the call site fails with the diagnostic embedded in the expected type.
  */
@@ -76,6 +76,53 @@ export type UseGuard<
     : [error: CollisionError<TAvail, TProvides>]
   : [error: NeedsError<TAvail, TNeeds>];
 
+type UseAllState<TAvail extends ServiceRecord, TPlugins extends readonly AnyPlugin[]> = TPlugins extends readonly [
+  infer Head,
+  ...infer Tail,
+]
+  ? Head extends Plugin<infer TNeeds, infer TProvides>
+    ? UseGuard<TAvail, TNeeds, NormalizeProvides<TProvides>> extends []
+      ? UseAllState<TAvail & NormalizeProvides<TProvides>, Extract<Tail, readonly AnyPlugin[]>>
+      : {
+          readonly avail: TAvail;
+          readonly error: {
+            readonly 'DOT: useAll tuple contains a plugin that cannot be used at this position': UseGuard<
+              TAvail,
+              TNeeds,
+              NormalizeProvides<TProvides>
+            >[0];
+          };
+        }
+    : {
+        readonly avail: TAvail;
+        readonly error: {
+          readonly 'DOT: useAll accepts only plugins': Head;
+        };
+      }
+  : {
+      readonly avail: TAvail;
+      readonly error: never;
+    };
+
+export type UseAllAvail<TAvail extends ServiceRecord, TPlugins extends readonly AnyPlugin[]> = UseAllState<
+  TAvail,
+  TPlugins
+>['avail'];
+
+type UseAllTupleGuard<TPlugins extends readonly AnyPlugin[]> = number extends TPlugins['length']
+  ? [
+      error: {
+        readonly 'DOT: useAll requires a tuple; add `as const` or pass plugins directly in declaration order': TPlugins;
+      },
+    ]
+  : [];
+
+export type UseAllGuard<TAvail extends ServiceRecord, TPlugins extends readonly AnyPlugin[]> = [
+  UseAllState<TAvail, TPlugins>['error'],
+] extends [never]
+  ? UseAllTupleGuard<TPlugins>
+  : [error: UseAllState<TAvail, TPlugins>['error']];
+
 /* ------------------------------------------------------------------ */
 /* Public app surface                                                  */
 /* ------------------------------------------------------------------ */
@@ -90,7 +137,7 @@ export type DotApp<TServices extends ServiceRecord> = {
   /** Current lifecycle state. */
   readonly state: DotLifecycleState;
   /**
-   * Services published by booted pips, keyed by wire key.
+   * Services published by booted plugins, keyed by wire key.
    * Empty before `boot()` succeeds.
    */
   readonly services: TServices;
@@ -149,19 +196,28 @@ export type DotAppConfigured<TServices extends ServiceRecord> = {
 /**
  * Builder produced by `defineApp(name)`.
  *
- * `.use(pip)` is type-tracking in both directions: the pip's `needs` must
+ * `.use(plugin)` is type-tracking in both directions: the plugin's `needs` must
  * be satisfied by the services accumulated so far, and its `provides`
  * merge into the accumulated record for the next `.use()`.
  */
 export type DotAppBuilder<TAvail extends ServiceRecord> = {
   /**
-   * Register a pip. Compile error when the pip's needs are unsatisfied
+   * Register a plugin. Compile error when the plugin's needs are unsatisfied
    * or its provides collide with existing wire keys.
    */
   use<TNeeds extends ServiceRecord, TProvides extends ServiceRecord>(
-    pip: Pip<TNeeds, TProvides>,
+    plugin: Plugin<TNeeds, TProvides>,
     ...guard: UseGuard<TAvail, TNeeds, NormalizeProvides<TProvides>>
   ): DotAppBuilder<TAvail & NormalizeProvides<TProvides>>;
+  /**
+   * Register a tuple of plugins in declaration order. This is type-equivalent
+   * to calling `.use()` for each item and keeps the same ordering/collision
+   * guard across the whole tuple.
+   */
+  useAll<const TPlugins extends readonly AnyPlugin[]>(
+    plugins: TPlugins,
+    ...guard: UseAllGuard<TAvail, TPlugins>
+  ): DotAppBuilder<UseAllAvail<TAvail, TPlugins>>;
   /** Run the configure phase synchronously. Throws on configure failure. */
   configure(): DotAppConfigured<TAvail>;
   /** Run configure + boot. Throws on configure or boot failure. */
@@ -173,7 +229,7 @@ export type DotAppBuilder<TAvail extends ServiceRecord> = {
 type BuilderState = {
   appName: string;
   appVersion?: string;
-  pips: AnyPip[];
+  plugins: AnyPlugin[];
   config?: Readonly<Record<string, unknown>>;
   observers?: readonly DotLifecycleObserver[];
   hookTimeoutMs?: number;
@@ -184,8 +240,8 @@ type BuilderState = {
  *
  * @example
  * const app = await defineApp('my-app')
- *   .use(dbPip)
- *   .use(billingPip)   // billing's needs must be satisfied by now
+ *   .use(dbPlugin)
+ *   .use(billingPlugin)   // billing's needs must be satisfied by now
  *   .boot();
  *
  * await app.start();
@@ -208,7 +264,7 @@ export function defineApp(
     /**
      * Watchdog budget (ms) for each async hook invocation (`boot`, `start`,
      * `stop`, `dispose` — `configure` is sync). A hook exceeding the budget
-     * fails with `DOT_LIFECYCLE_E015` naming the pip and hook, and the
+     * fails with `DOT_LIFECYCLE_E015` naming the plugin and hook, and the
      * kernel applies its normal failure rules (boot rollback, teardown
      * aggregation). The hook's promise itself cannot be cancelled — the
      * watchdog makes the hang *visible*, it does not kill it. Default:
@@ -220,7 +276,7 @@ export function defineApp(
   const state: BuilderState = {
     appName: name,
     appVersion: options.version,
-    pips: [],
+    plugins: [],
     config: options.config,
     observers: options.observers,
     hookTimeoutMs: options.hookTimeoutMs,
@@ -232,7 +288,7 @@ function buildImpl(state: BuilderState): DotAppImpl {
   return new DotAppImpl({
     appName: state.appName,
     appVersion: state.appVersion,
-    pips: state.pips,
+    plugins: state.plugins,
     config: state.config,
     observers: state.observers,
     hookTimeoutMs: state.hookTimeoutMs,
@@ -244,10 +300,17 @@ function makeBuilder<TAvail extends ServiceRecord>(state: BuilderState): DotAppB
   // at the type level); the single cast below is the same kernel boundary
   // v1 crossed in its wrapApp helper.
   const impl = {
-    use(pip: AnyPip, ..._guard: readonly unknown[]): DotAppBuilder<ServiceRecord> {
+    use(plugin: AnyPlugin, ..._guard: readonly unknown[]): DotAppBuilder<ServiceRecord> {
+      const nextState: BuilderState = {
+        ...state,
+        plugins: [...state.plugins, plugin],
+      };
+      return makeBuilder<ServiceRecord>(nextState);
+    },
+    useAll(plugins: readonly AnyPlugin[], ..._guard: readonly unknown[]): DotAppBuilder<ServiceRecord> {
       const nextState: BuilderState = {
         ...state,
-        pips: [...state.pips, pip],
+        plugins: [...state.plugins, ...plugins],
       };
       return makeBuilder<ServiceRecord>(nextState);
     },