@arki/dot 0.2.0 → 0.4.0

package/dist/cli/render-openapi.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Renderer for `dot explain --openapi`.
+ *
+ * Emits an OpenAPI 3.1 document straight from `manifest.routes` — no boot
+ * required. Adapters (e.g. `@arki/http`'s `registerRoutes`) convert their
+ * validation schemas to JSON Schema at `configure` time and register them
+ * via `ctx.registerRoute`, so the manifest already carries everything the
+ * document needs: methods, paths, per-location input schemas, output
+ * schemas, and the `streaming` flag for `text/event-stream` responses.
+ *
+ * Deterministic: paths and operations follow manifest registration order
+ * (which follows pip declaration order). Only `transport: 'http'` routes
+ * are rendered — rpc mounts have their own schema story.
+ */
+import type { DotAppManifest } from '../manifest.js';
+import type { DotCliEnvelope, RenderOptions } from './render-explain.js';
+/** Envelope payload for OpenAPI output. */
+export type OpenApiData = {
+    format: 'openapi';
+    /** OpenAPI 3.1 document. */
+    document: Record<string, unknown>;
+};
+/**
+ * Build an OpenAPI 3.1 document from a manifest. First registration wins
+ * on a method+path collision — collisions are an app bug the serving
+ * adapter rejects at boot; the document renderer stays total.
+ */
+export declare function buildOpenApiDocument(manifest: DotAppManifest): Record<string, unknown>;
+/**
+ * Render the OpenAPI output. Plain mode prints the document as JSON
+ * (pipe it into a file or a swagger viewer); `--json` wraps it in the
+ * standard CLI envelope under `data.document`.
+ */
+export declare function renderOpenApi(source: {
+    manifest: DotAppManifest;
+    command: 'explain';
+}, opts: RenderOptions): DotCliEnvelope<OpenApiData>;
+//# sourceMappingURL=render-openapi.d.ts.map

package/dist/cli/render-openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-openapi.d.ts","sourceRoot":"","sources":["../../src/cli/render-openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzE,2CAA2C;AAC3C,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,SAAS,CAAC;IAClB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC;AAmEF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmBtF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE;IAAE,QAAQ,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,SAAS,CAAA;CAAE,EACxD,IAAI,EAAE,aAAa,GAClB,cAAc,CAAC,WAAW,CAAC,CAsB7B"}

package/dist/cli/render-openapi.js

@@ -0,0 +1,131 @@
+/**
+ * Renderer for `dot explain --openapi`.
+ *
+ * Emits an OpenAPI 3.1 document straight from `manifest.routes` — no boot
+ * required. Adapters (e.g. `@arki/http`'s `registerRoutes`) convert their
+ * validation schemas to JSON Schema at `configure` time and register them
+ * via `ctx.registerRoute`, so the manifest already carries everything the
+ * document needs: methods, paths, per-location input schemas, output
+ * schemas, and the `streaming` flag for `text/event-stream` responses.
+ *
+ * Deterministic: paths and operations follow manifest registration order
+ * (which follows pip declaration order). Only `transport: 'http'` routes
+ * are rendered — rpc mounts have their own schema story.
+ */
+function openApiPath(path) {
+    return path.replaceAll(/:(\w+)/g, '{$1}');
+}
+function pathParamNames(path) {
+    return [...path.matchAll(/:(\w+)/g)]
+        .map(match => match[1])
+        .filter((name) => name !== undefined);
+}
+function buildOperation(route) {
+    const parameters = pathParamNames(route.path ?? '').map(name => ({
+        name,
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+    }));
+    const querySchema = route.input?.query;
+    if (querySchema !== undefined) {
+        const properties = (querySchema['properties'] ?? {});
+        const required = new Set(querySchema['required']);
+        for (const [name, propertySchema] of Object.entries(properties)) {
+            parameters.push({ name, in: 'query', required: required.has(name), schema: propertySchema });
+        }
+    }
+    const operation = {
+        operationId: route.id,
+        tags: [route.pip],
+    };
+    if (route.description !== undefined)
+        operation['summary'] = route.description;
+    if (parameters.length > 0)
+        operation['parameters'] = parameters;
+    const bodySchema = route.input?.body;
+    if (bodySchema !== undefined) {
+        operation['requestBody'] = {
+            required: true,
+            content: { 'application/json': { schema: bodySchema } },
+        };
+    }
+    if (route.streaming === true) {
+        operation['responses'] = {
+            '200': {
+                description: 'event stream',
+                content: {
+                    'text/event-stream': route.output === undefined ? {} : { schema: route.output },
+                },
+            },
+        };
+    }
+    else if (route.output === undefined) {
+        operation['responses'] = { '200': { description: 'success' } };
+    }
+    else {
+        operation['responses'] = {
+            '200': {
+                description: 'success',
+                content: { 'application/json': { schema: route.output } },
+            },
+        };
+    }
+    return operation;
+}
+/**
+ * Build an OpenAPI 3.1 document from a manifest. First registration wins
+ * on a method+path collision — collisions are an app bug the serving
+ * adapter rejects at boot; the document renderer stays total.
+ */
+export function buildOpenApiDocument(manifest) {
+    const paths = {};
+    for (const route of manifest.routes) {
+        if (route.transport !== 'http')
+            continue;
+        if (route.path === undefined)
+            continue;
+        const path = openApiPath(route.path);
+        const method = (route.method ?? 'GET').toLowerCase();
+        const entry = (paths[path] ??= {});
+        if (entry[method] !== undefined)
+            continue;
+        entry[method] = buildOperation(route);
+    }
+    return {
+        openapi: '3.1.0',
+        info: {
+            title: manifest.app.name,
+            version: manifest.app.version ?? '0.0.0',
+        },
+        paths,
+    };
+}
+/**
+ * Render the OpenAPI output. Plain mode prints the document as JSON
+ * (pipe it into a file or a swagger viewer); `--json` wraps it in the
+ * standard CLI envelope under `data.document`.
+ */
+export function renderOpenApi(source, opts) {
+    const document = buildOpenApiDocument(source.manifest);
+    const nowFactory = opts.now ?? (() => new Date());
+    const envelope = {
+        status: 'success',
+        command: source.command,
+        generatedAt: nowFactory().toISOString(),
+        data: { format: 'openapi', document },
+        errors: [],
+    };
+    const out = opts.out ??
+        ((line) => {
+            process.stdout.write(line);
+        });
+    if (opts.json) {
+        out(`${JSON.stringify(envelope, null, 2)}\n`);
+    }
+    else {
+        out(`${JSON.stringify(document, null, 2)}\n`);
+    }
+    return envelope;
+}
+//# sourceMappingURL=render-openapi.js.map

package/dist/cli/render-openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-openapi.js","sourceRoot":"","sources":["../../src/cli/render-openapi.ts"],"names":[],"mappings":"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"}

package/dist/cli/render-projection.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 type { DotAppManifest, JsonValue } from '../manifest.js';
+import type { DotCliEnvelope, RenderOptions } from './render-explain.js';
+export type ProjectionData = {
+    format: string;
+    document: JsonValue;
+};
+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;
+};
+/**
+ * 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 declare function renderProjection(source: ProjectionSource, opts: RenderOptions): Promise<DotCliEnvelope<ProjectionData>>;
+//# sourceMappingURL=render-projection.d.ts.map

package/dist/cli/render-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-projection.d.ts","sourceRoot":"","sources":["../../src/cli/render-projection.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAsB,MAAM,gBAAgB,CAAC;AACpF,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzE,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,SAAS,CAAC;CACrB,CAAC;AAMF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,SAAS,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAgKF;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC,CAqCzC"}

package/dist/cli/render-projection.js

@@ -0,0 +1,202 @@
+/**
+ * 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 { DotCliError, DotCliErrorCode } from './error-codes.js';
+const defaultOut = (line) => {
+    process.stdout.write(line);
+};
+function nowIso(opts) {
+    const factory = opts.now ?? (() => new Date());
+    return factory().toISOString();
+}
+function isJsonPrimitive(value) {
+    return value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number';
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function isJsonValue(value) {
+    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, right) {
+    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) {
+    let serialized;
+    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);
+    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, format) {
+    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() {
+    const candidate = globalThis.Bun;
+    if (typeof candidate !== 'object' || candidate === null)
+        return undefined;
+    const resolveSync = candidate.resolveSync;
+    if (typeof resolveSync !== 'function')
+        return undefined;
+    return { resolveSync: (specifier, from) => resolveSync.call(candidate, specifier, from) };
+}
+function importSpecifierFor(resolved) {
+    if (resolved.startsWith('file:'))
+        return resolved;
+    if (isAbsolute(resolved))
+        return pathToFileURL(resolved).href;
+    return resolved;
+}
+function resolveProjectionSpecifier(specifier, appFilePath) {
+    const fromDir = dirname(appFilePath);
+    const bun = getBunResolver();
+    if (bun !== undefined)
+        return bun.resolveSync(specifier, fromDir);
+    return createRequire(appFilePath).resolve(specifier);
+}
+async function loadProjectionModule(specifier, appFilePath, registeringPlugin) {
+    let resolved;
+    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;
+    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.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, 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, opts) {
+    const projection = selectProjection(source.manifest, source.format);
+    const specifier = source.module ?? projection.module;
+    const { module } = await loadProjectionModule(specifier, source.appFilePath, projection.plugin);
+    let document;
+    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 = {
+        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;
+}
+//# sourceMappingURL=render-projection.js.map

package/dist/cli/render-projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-projection.js","sourceRoot":"","sources":["../../src/cli/render-projection.ts"],"names":[],"mappings":"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"}

package/dist/define-app.d.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
@@ -22,7 +22,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 { EmptyShape, Pip, ServiceRecord } from './pip-contract.js';
+import type { AnyPlugin, EmptyShape, Plugin, ServiceRecord } from './plugin-contract.js';
 type MissingKeys<TAvail, TNeeds> = {
     readonly [K in Exclude<keyof TNeeds, keyof TAvail>]: TNeeds[K];
 };
@@ -33,27 +33,53 @@ 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.
  */
 export type UseGuard<TAvail extends ServiceRecord, TNeeds extends ServiceRecord, TProvides extends ServiceRecord> = [TAvail] extends [TNeeds] ? [keyof TAvail & keyof TProvides] extends [never] ? [] : [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 DotApp surface. The internal `DotAppImpl` implements this; consumers
  * see only these members.
@@ -64,7 +90,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;
@@ -121,16 +147,22 @@ 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>, ...guard: UseGuard<TAvail, TNeeds, NormalizeProvides<TProvides>>): DotAppBuilder<TAvail & NormalizeProvides<TProvides>>;
+    use<TNeeds extends ServiceRecord, TProvides extends ServiceRecord>(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. */
@@ -143,8 +175,8 @@ export type DotAppBuilder<TAvail extends ServiceRecord> = {
  *
  * @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();
@@ -165,7 +197,7 @@ export declare function defineApp(name: string, options?: {
     /**
      * 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:

package/dist/define-app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-app.d.ts","sourceRoot":"","sources":["../src/define-app.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"define-app.d.ts","sourceRoot":"","sources":["../src/define-app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAQzF,KAAK,WAAW,CAAC,MAAM,EAAE,MAAM,IAAI;IACjC,QAAQ,EAAE,CAAC,IAAI,OAAO,CAAC,MAAM,MAAM,EAAE,MAAM,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;CAC/D,CAAC;AAEF,KAAK,cAAc,CAAC,MAAM,EAAE,MAAM,IAAI;IACpC,QAAQ,EAAE,CAAC,IAAI,MAAM,MAAM,GAAG,MAAM,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,GAAG;QACtF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;QAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;KAC5B;CACF,CAAC;AAEF,KAAK,UAAU,CAAC,MAAM,SAAS,aAAa,EAAE,MAAM,SAAS,aAAa,IAAI;IAC5E,QAAQ,CAAC,uDAAuD,EAAE;QAChE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC9C,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACrD,CAAC;CACH,CAAC;AAEF,KAAK,cAAc,CAAC,MAAM,EAAE,SAAS,IAAI;IACvC,QAAQ,CAAC,gEAAgE,EAAE,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC;CAC3G,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,CAAC,EAAE,SAAS,aAAa,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,UAAU,GAAG,EAAE,CAAC;AAEjG;;;;GAIG;AACH,MAAM,MAAM,QAAQ,CAClB,MAAM,SAAS,aAAa,EAC5B,MAAM,SAAS,aAAa,EAC5B,SAAS,SAAS,aAAa,IAC7B,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,GACzB,CAAC,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,GAC9C,EAAE,GACF,CAAC,KAAK,EAAE,cAAc,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,GAC5C,CAAC,KAAK,EAAE,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAExC,KAAK,WAAW,CAAC,MAAM,SAAS,aAAa,EAAE,QAAQ,SAAS,SAAS,SAAS,EAAE,IAAI,QAAQ,SAAS,SAAS;IAChH,MAAM,IAAI;IACV,GAAG,MAAM,IAAI;CACd,GACG,IAAI,SAAS,MAAM,CAAC,MAAM,MAAM,EAAE,MAAM,SAAS,CAAC,GAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,GAC/D,WAAW,CAAC,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC,CAAC,GACvF;IACE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,0EAA0E,EAAE,QAAQ,CAC3F,MAAM,EACN,MAAM,EACN,iBAAiB,CAAC,SAAS,CAAC,CAC7B,CAAC,CAAC,CAAC,CAAC;KACN,CAAC;CACH,GACH;IACE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,kCAAkC,EAAE,IAAI,CAAC;KACnD,CAAC;CACH,GACH;IACE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB,CAAC;AAEN,MAAM,MAAM,WAAW,CAAC,MAAM,SAAS,aAAa,EAAE,QAAQ,SAAS,SAAS,SAAS,EAAE,IAAI,WAAW,CACxG,MAAM,EACN,QAAQ,CACT,CAAC,OAAO,CAAC,CAAC;AAEX,KAAK,gBAAgB,CAAC,QAAQ,SAAS,SAAS,SAAS,EAAE,IAAI,MAAM,SAAS,QAAQ,CAAC,QAAQ,CAAC,GAC5F;IACE,KAAK,EAAE;QACL,QAAQ,CAAC,4FAA4F,EAAE,QAAQ,CAAC;KACjH;CACF,GACD,EAAE,CAAC;AAEP,MAAM,MAAM,WAAW,CAAC,MAAM,SAAS,aAAa,EAAE,QAAQ,SAAS,SAAS,SAAS,EAAE,IAAI;IAC7F,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,OAAO,CAAC;CACvC,SAAS,CAAC,KAAK,CAAC,GACb,gBAAgB,CAAC,QAAQ,CAAC,GAC1B,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AAMpD;;;GAGG;AACH,MAAM,MAAM,MAAM,CAAC,SAAS,SAAS,aAAa,IAAI;IACpD,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;OAGG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI,CAAC;IACtD;;;;OAIG;IACH,QAAQ,IAAI,MAAM,CAAC;CACpB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAAC,SAAS,SAAS,aAAa,IAAI;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C,8BAA8B;IAC9B,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IACnC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IACpC,oCAAoC;IACpC,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI,CAAC;IACtD,mCAAmC;IACnC,QAAQ,IAAI,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,SAAS,aAAa,IAAI;IACxD;;;OAGG;IACH,GAAG,CAAC,MAAM,SAAS,aAAa,EAAE,SAAS,SAAS,aAAa,EAC/D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EACjC,GAAG,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC,GAC/D,aAAa,CAAC,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC,CAAC;IACxD;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,QAAQ,SAAS,SAAS,SAAS,EAAE,EAChD,OAAO,EAAE,QAAQ,EACjB,GAAG,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,GACtC,aAAa,CAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChD,0EAA0E;IAC1E,SAAS,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACtC,iEAAiE;IACjE,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAChC,6CAA6C;IAC7C,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;CAClC,CAAC;AAWF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3C;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC5C;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACnB,GACL,aAAa,CAAC,UAAU,CAAC,CAU3B"}