@arki/dot 0.1.4 → 0.2.0

package/dist/test-harness.d.ts

@@ -25,7 +25,7 @@
  *   });
  */
 import type { DotApp, DotAppBuilder } from './define-app.js';
-import type { AnyPip, EmptyShape, ServiceRecord } from './pip-contract.js';
+import type { AnyPip, EmptyShape, Pip, ServiceRecord, Token } from './pip-contract.js';
 export type TestAppOptions = {
     /** App name used in the manifest. Defaults to `'test-app'`. */
     name?: string;
@@ -42,4 +42,78 @@ export declare function testApp<TServices extends ServiceRecord = EmptyShape>(pi
  * calling `app.dispose()` when finished.
  */
 export declare function bootTestApp<TServices extends ServiceRecord = EmptyShape>(pips?: readonly AnyPip[], options?: TestAppOptions): Promise<DotApp<TServices>>;
+/**
+ * Rest-tuple guard for {@link TestPipBuilder.boot} — the same trick the app
+ * builder's `UseGuard` uses. While any need is still unprovided, `boot()`
+ * demands an impossible second argument, so the call site fails with
+ * "Expected 2 arguments, but got 1" and the error payload names the
+ * missing wire keys and their types.
+ */
+type TestPipBootGuard<TRemaining extends ServiceRecord> = keyof TRemaining extends never ? readonly [] : readonly [
+    needs: {
+        readonly 'DOT-TEST: pip needs still unprovided — call .provide() for each': {
+            readonly [K in keyof TRemaining]: TRemaining[K];
+        };
+    }
+];
+/**
+ * Typed unit-test builder for a single pip — see {@link testPip}.
+ *
+ * `TRemaining` tracks the wire keys not yet covered by `.provide()`;
+ * `TServices` accumulates what the booted app will expose (the fakes plus
+ * the pip's own provides).
+ */
+export type TestPipBuilder<TRemaining extends ServiceRecord, TServices extends ServiceRecord> = {
+    /**
+     * Satisfy one need directly with a fake. Token form — the token names
+     * the wire key and carries the type:
+     *
+     * ```ts
+     * testPip(reports).provide(Db, fakeDb)
+     * ```
+     */
+    provide<K extends keyof TRemaining & string, T extends TRemaining[K]>(token: Token<T, K>, value: T): TestPipBuilder<Omit<TRemaining, K>, TServices & Readonly<Record<K, T>>>;
+    /**
+     * Satisfy one need directly with a fake. Key form — for anonymous
+     * `service<T>()` needs, where the wire key is the property name:
+     *
+     * ```ts
+     * testPip(billing).provide('db', fakeDb)
+     * ```
+     */
+    provide<K extends keyof TRemaining & string>(key: K, value: TRemaining[K]): TestPipBuilder<Omit<TRemaining, K>, TServices & Readonly<Record<K, TRemaining[K]>>>;
+    /** Boot the pip against the provided fakes. Compile error until every need is provided. */
+    boot(...guard: TestPipBootGuard<TRemaining>): Promise<DotApp<TServices>>;
+    /** Boot + start. Same guard as {@link TestPipBuilder.boot}. */
+    start(...guard: TestPipBootGuard<TRemaining>): Promise<DotApp<TServices>>;
+};
+/**
+ * Unit-test a single pip with **typed overrides** — the compile-checked
+ * counterpart to {@link testApp}'s erased arrays.
+ *
+ * Each `.provide()` satisfies one of the pip's needs directly (no real
+ * provider pip, no dependency chain) and removes it from the builder's
+ * remaining-needs type. `boot()` only compiles once every need is covered,
+ * and a fake of the wrong shape fails at the `.provide()` call site:
+ *
+ * ```ts
+ * import { testPip } from '@arki/dot/test-harness';
+ *
+ * const app = await testPip(catalog)
+ *   .provide(Db, fakeDb)          // token need
+ *   .provide('cache', fakeKv)     // anonymous need — wire key is the alias
+ *   .boot();
+ *
+ * expect(app.services.catalog.list()).toEqual([]);
+ * await app.dispose();
+ * ```
+ *
+ * `service.lazy<T>()` needs accept either a plain `T` fake (the kernel
+ * lifts it) or a `Lazy<T>` handle (`lazyOf(value)` is handy here).
+ * Lifecycle semantics are the real kernel's — the fakes are published by a
+ * synthetic first pip, so reverse-order teardown and lazy auto-dispose
+ * behave exactly as in production.
+ */
+export declare function testPip<TNeeds extends ServiceRecord, TProvides extends ServiceRecord>(pip: Pip<TNeeds, TProvides>, options?: TestAppOptions): TestPipBuilder<TNeeds, TProvides>;
+export {};
 //# sourceMappingURL=test-harness.d.ts.map

package/dist/test-harness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-harness.d.ts","sourceRoot":"","sources":["../src/test-harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAG3E,MAAM,MAAM,cAAc,GAAG;IAC3B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC5C,CAAC;AAWF;;;GAGG;AACH,wBAAgB,OAAO,CAAC,SAAS,SAAS,aAAa,GAAG,UAAU,EAClE,IAAI,GAAE,SAAS,MAAM,EAAO,EAC5B,OAAO,GAAE,cAAmB,GAC3B,aAAa,CAAC,SAAS,CAAC,CAM1B;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,SAAS,SAAS,aAAa,GAAG,UAAU,EAC5E,IAAI,GAAE,SAAS,MAAM,EAAO,EAC5B,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAE5B"}
+{"version":3,"file":"test-harness.d.ts","sourceRoot":"","sources":["../src/test-harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAGvF,MAAM,MAAM,cAAc,GAAG;IAC3B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC5C,CAAC;AAWF;;;GAGG;AACH,wBAAgB,OAAO,CAAC,SAAS,SAAS,aAAa,GAAG,UAAU,EAClE,IAAI,GAAE,SAAS,MAAM,EAAO,EAC5B,OAAO,GAAE,cAAmB,GAC3B,aAAa,CAAC,SAAS,CAAC,CAM1B;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,SAAS,SAAS,aAAa,GAAG,UAAU,EAC5E,IAAI,GAAE,SAAS,MAAM,EAAO,EAC5B,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAE5B;AAED;;;;;;GAMG;AACH,KAAK,gBAAgB,CAAC,UAAU,SAAS,aAAa,IAAI,MAAM,UAAU,SAAS,KAAK,GACpF,SAAS,EAAE,GACX,SAAS;IACP,KAAK,EAAE;QACL,QAAQ,CAAC,iEAAiE,EAAE;YAC1E,QAAQ,EAAE,CAAC,IAAI,MAAM,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC;SAChD,CAAC;KACH;CACF,CAAC;AAEN;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,CAAC,UAAU,SAAS,aAAa,EAAE,SAAS,SAAS,aAAa,IAAI;IAC9F;;;;;;;OAOG;IACH,OAAO,CAAC,CAAC,SAAS,MAAM,UAAU,GAAG,MAAM,EAAE,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAClE,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAClB,KAAK,EAAE,CAAC,GACP,cAAc,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3E;;;;;;;OAOG;IACH,OAAO,CAAC,CAAC,SAAS,MAAM,UAAU,GAAG,MAAM,EACzC,GAAG,EAAE,CAAC,EACN,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,GACnB,cAAc,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvF,2FAA2F;IAC3F,IAAI,CAAC,GAAG,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IACzE,+DAA+D;IAC/D,KAAK,CAAC,GAAG,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;CAC3E,CAAC;AASF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,OAAO,CAAC,MAAM,SAAS,aAAa,EAAE,SAAS,SAAS,aAAa,EACnF,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EAC3B,OAAO,GAAE,cAAmB,GAC3B,cAAc,CAAC,MAAM,EAAE,SAAS,CAAC,CAInC"}

package/dist/test-harness.js

@@ -43,4 +43,75 @@ export function testApp(pips = [], options = {}) {
 export async function bootTestApp(pips = [], options = {}) {
     return testApp(pips, options).boot();
 }
+/**
+ * Unit-test a single pip with **typed overrides** — the compile-checked
+ * counterpart to {@link testApp}'s erased arrays.
+ *
+ * Each `.provide()` satisfies one of the pip's needs directly (no real
+ * provider pip, no dependency chain) and removes it from the builder's
+ * remaining-needs type. `boot()` only compiles once every need is covered,
+ * and a fake of the wrong shape fails at the `.provide()` call site:
+ *
+ * ```ts
+ * import { testPip } from '@arki/dot/test-harness';
+ *
+ * const app = await testPip(catalog)
+ *   .provide(Db, fakeDb)          // token need
+ *   .provide('cache', fakeKv)     // anonymous need — wire key is the alias
+ *   .boot();
+ *
+ * expect(app.services.catalog.list()).toEqual([]);
+ * await app.dispose();
+ * ```
+ *
+ * `service.lazy<T>()` needs accept either a plain `T` fake (the kernel
+ * lifts it) or a `Lazy<T>` handle (`lazyOf(value)` is handy here).
+ * Lifecycle semantics are the real kernel's — the fakes are published by a
+ * synthetic first pip, so reverse-order teardown and lazy auto-dispose
+ * behave exactly as in production.
+ */
+export function testPip(pip, options = {}) {
+    // Erasure seam — same boundary as `makeBuilder` in define-app.ts: the
+    // runtime impl is untyped, the type parameters do all the guarding.
+    return makeTestPipBuilder({ pip: pip, fakes: {}, options });
+}
+/**
+ * Erased implementation behind {@link testPip}. Mirrors `makeBuilder` in
+ * `define-app.ts`: the runtime is untyped, the single cast at the return
+ * is the seam, and the type parameters do all the guarding.
+ */
+function makeTestPipBuilder(state) {
+    const bootApp = async () => {
+        const pips = [];
+        if (Object.keys(state.fakes).length > 0) {
+            const fakes = { ...state.fakes };
+            pips.push({
+                name: `test:fakes(${state.pip.name})`,
+                needs: {},
+                renames: {},
+                hooks: { boot: () => fakes },
+            });
+        }
+        pips.push(state.pip);
+        return testApp(pips, {
+            name: state.options.name ?? `test:${state.pip.name}`,
+            ...(state.options.config === undefined ? {} : { config: state.options.config }),
+        }).boot();
+    };
+    const impl = {
+        provide(tokenOrKey, value) {
+            const key = typeof tokenOrKey === 'string' ? tokenOrKey : tokenOrKey.key;
+            return makeTestPipBuilder({ ...state, fakes: { ...state.fakes, [key]: value } });
+        },
+        async boot(..._guard) {
+            return bootApp();
+        },
+        async start(..._guard) {
+            const app = await bootApp();
+            await app.start();
+            return app;
+        },
+    };
+    return impl;
+}
 //# sourceMappingURL=test-harness.js.map

package/dist/test-harness.js.map

@@ -1 +1 @@
-{"version":3,"file":"test-harness.js","sourceRoot":"","sources":["../src/test-harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAkB5C;;;GAGG;AACH,MAAM,UAAU,OAAO,CACrB,OAA0B,EAAE,EAC5B,UAA0B,EAAE;IAE5B,IAAI,OAAO,GAAY,SAAS,CAAC,OAAO,CAAC,IAAI,IAAI,UAAU,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzF,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,OAAO,GAAI,OAAwB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,OAAmC,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAA0B,EAAE,EAC5B,UAA0B,EAAE;IAE5B,OAAO,OAAO,CAAY,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;AAClD,CAAC"}
+{"version":3,"file":"test-harness.js","sourceRoot":"","sources":["../src/test-harness.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arki/dot",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "TypeScript-first application composition framework for the ARKI package family — lifecycle-aware pips, deterministic boot order, manifest/diagnostics envelopes, and an agent-native CLI. A DOT app is the sum of its pips.",
   "license": "MIT",
   "repository": {

package/src/cli/index.ts

@@ -33,6 +33,7 @@ import { runNew } from './new.js';
 import { probeObservability } from './observability-probe.js';
 import { renderDoctor } from './render-doctor.js';
 import { renderExplain } from './render-explain.js';
+import { renderGraph } from './render-graph.js';
 
 const debugCli = createDebugLogger('arki:dot:cli');
 
@@ -57,6 +58,10 @@ Common options:
   --app <path>           Path to the app entry file (default: discovers
                          ./dot.config.ts, ./src/app.ts, or ./app.ts)
   --cwd <dir>            Working directory (default: current)
+  --graph                Emit the pip graph as Mermaid flowchart source
+                         instead of the standard output. explain shows
+                         declaration (= boot) order; doctor shows the
+                         wiring observed during boot. Composes with --json.
 
 \`doctor\` options:
   --observability        Also probe whether an OpenTelemetry SDK is
@@ -89,6 +94,8 @@ export type CliArgs = {
   force?: boolean;
   /** `--observability` (only honored by `doctor`). */
   observability?: boolean;
+  /** `--graph` (honored by `explain` and `doctor`). */
+  graph?: boolean;
 };
 
 /**
@@ -152,6 +159,7 @@ export function parseArgs(argv: readonly string[]): CliArgs {
         'dry-run': { type: 'boolean', default: false },
         force: { type: 'boolean', default: false },
         observability: { type: 'boolean', default: false },
+        graph: { type: 'boolean', default: false },
       },
     });
   } catch (err) {
@@ -174,6 +182,7 @@ export function parseArgs(argv: readonly string[]): CliArgs {
     'dry-run'?: boolean;
     force?: boolean;
     observability?: boolean;
+    graph?: boolean;
   };
 
   if (values.help) command = 'help';
@@ -205,6 +214,7 @@ export function parseArgs(argv: readonly string[]): CliArgs {
     dryRun: values['dry-run'] ?? false,
     force: values.force ?? false,
     observability: values.observability ?? false,
+    graph: values.graph ?? false,
   };
 }
 
@@ -220,7 +230,7 @@ async function loadApp(args: CliArgs): Promise<DiscoveredApp> {
  */
 export async function runExplain(
   discovered: DiscoveredApp,
-  opts: { json: boolean; out?: (line: string) => void; now?: () => Date },
+  opts: { json: boolean; graph?: boolean; out?: (line: string) => void; now?: () => Date },
 ): Promise<DotCliEnvelope<unknown>> {
   let configured: DotApp<Record<string, unknown>> | DotAppConfigured<Record<string, unknown>>;
   try {
@@ -236,6 +246,12 @@ export async function runExplain(
     throw wrapLifecycleError(err, 'configure');
   }
 
+  if (opts.graph === true) {
+    return renderGraph(
+      { manifest: configured.manifest, command: 'explain' },
+      { json: opts.json, out: opts.out, now: opts.now },
+    );
+  }
   return renderExplain({ manifest: configured.manifest }, { json: opts.json, out: opts.out, now: opts.now });
 }
 
@@ -249,6 +265,8 @@ type DoctorRunOptions = {
    * present. Default `false`.
    */
   observability?: boolean;
+  /** When `true`, emit the pip graph (Mermaid) instead of diagnostics. */
+  graph?: boolean;
 };
 
 /**
@@ -268,6 +286,12 @@ export async function runDoctor(
   // Already-booted app: just read diagnostics, don't touch lifecycle.
   if (!guards.isDotAppBuilder(discovered) && !guards.isDotAppConfigured(discovered)) {
     const app = discovered as DotApp<Record<string, unknown>>;
+    if (opts.graph === true) {
+      return renderGraph(
+        { manifest: app.manifest, command: 'doctor' },
+        { json: opts.json, out: opts.out, now: opts.now },
+      );
+    }
     const diagnostics = applyObservabilityProbe(app.diagnostics, opts.observability ?? false);
     return renderDoctor({ diagnostics }, { json: opts.json, out: opts.out, now: opts.now });
   }
@@ -297,6 +321,16 @@ export async function runDoctor(
   }
 
   try {
+    if (opts.graph === true) {
+      // Post-boot manifest carries the observed wiring edges; after a boot
+      // failure it carries the edges recorded up to the failing pip.
+      const manifest = bootedApp ? bootedApp.manifest : configured.manifest;
+      const graphEnvelope = renderGraph(
+        { manifest, command: 'doctor' },
+        { json: opts.json, out: opts.out, now: opts.now },
+      );
+      return bootThrew ? { ...graphEnvelope, status: 'failure' } : graphEnvelope;
+    }
     const rawDiagnostics = bootedApp ? bootedApp.diagnostics : configured.diagnostics;
     const diagnostics = applyObservabilityProbe(rawDiagnostics, opts.observability ?? false);
     const envelope = renderDoctor({ diagnostics }, { json: opts.json, out: opts.out, now: opts.now });
@@ -450,7 +484,7 @@ export async function main(options: MainOptions): Promise<number> {
 
   try {
     const discovered = await loadApp(args);
-    const opts = { json: args.json, out: stdout, now: nowFactory };
+    const opts = { json: args.json, graph: args.graph, out: stdout, now: nowFactory };
     let envelope: DotCliEnvelope<unknown>;
 
     if (args.command === 'explain') {

package/src/cli/render-graph.ts

@@ -0,0 +1,88 @@
+/**
+ * Renderer for `dot explain --graph` / `dot doctor --graph`.
+ *
+ * Emits the app's pip 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 numbering makes that visible); the edges are the manifest's
+ * **observed** dependency edges, recorded by the kernel when a pip'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.
+ */
+
+import type { DotAppManifest } from '../manifest.js';
+import type { DotCliEnvelope, RenderOptions } from './render-explain.js';
+
+/** Envelope payload for graph output. */
+export type GraphData = {
+  format: 'mermaid';
+  /** Mermaid `flowchart` source. */
+  source: string;
+};
+
+/** Escape a pip name for use inside a quoted Mermaid node label. */
+function escapeLabel(name: string): string {
+  return name.replaceAll('"', '#quot;');
+}
+
+/**
+ * Build Mermaid `flowchart` source from a manifest. Deterministic: node
+ * ids follow declaration order, edges follow manifest order.
+ */
+export function buildMermaidGraph(manifest: DotAppManifest): string {
+  const lines: string[] = ['flowchart TD'];
+  const idByPip = new Map<string, string>();
+
+  for (const [index, pip] of manifest.pips.entries()) {
+    const id = `p${index.toString()}`;
+    idByPip.set(pip.name, id);
+    const order = (index + 1).toString();
+    const version = pip.version === undefined ? '' : `@${pip.version}`;
+    lines.push(`  ${id}["${order} · ${escapeLabel(pip.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
+    // than emit invalid Mermaid.
+    if (from === undefined || to === undefined) continue;
+    lines.push(`  ${from} -->|${edge.kind}| ${to}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Render the graph output. Plain mode prints raw Mermaid source (pipe it
+ * straight into a markdown code fence); `--json` wraps it in the standard
+ * CLI envelope under `data.source`.
+ */
+export function renderGraph(
+  source: { manifest: DotAppManifest; command: 'explain' | 'doctor' },
+  opts: RenderOptions,
+): DotCliEnvelope<GraphData> {
+  const mermaid = buildMermaidGraph(source.manifest);
+  const nowFactory = opts.now ?? (() => new Date());
+  const envelope: DotCliEnvelope<GraphData> = {
+    status: 'success',
+    command: source.command,
+    generatedAt: nowFactory().toISOString(),
+    data: { format: 'mermaid', source: mermaid },
+    errors: [],
+  };
+
+  const out =
+    opts.out ??
+    ((line: string) => {
+      process.stdout.write(line);
+    });
+  if (opts.json) {
+    out(`${JSON.stringify(envelope, null, 2)}\n`);
+  } else {
+    out(mermaid);
+  }
+  return envelope;
+}

package/src/define-app.ts

@@ -176,6 +176,7 @@ type BuilderState = {
   pips: AnyPip[];
   config?: Readonly<Record<string, unknown>>;
   observers?: readonly DotLifecycleObserver[];
+  hookTimeoutMs?: number;
 };
 
 /**
@@ -204,6 +205,16 @@ export function defineApp(
      * `configured.subscribe(...)` or `app.subscribe(...)`.
      */
     observers?: readonly DotLifecycleObserver[];
+    /**
+     * 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
+     * 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:
+     * no watchdog.
+     */
+    hookTimeoutMs?: number;
   } = {},
 ): DotAppBuilder<EmptyShape> {
   const state: BuilderState = {
@@ -212,6 +223,7 @@ export function defineApp(
     pips: [],
     config: options.config,
     observers: options.observers,
+    hookTimeoutMs: options.hookTimeoutMs,
   };
   return makeBuilder<EmptyShape>(state);
 }
@@ -223,6 +235,7 @@ function buildImpl(state: BuilderState): DotAppImpl {
     pips: state.pips,
     config: state.config,
     observers: state.observers,
+    hookTimeoutMs: state.hookTimeoutMs,
   });
 }
 

package/src/index.ts

@@ -80,8 +80,11 @@ export type {
 export { renderTimeline } from './timeline.js';
 export type { RenderTimelineOptions } from './timeline.js';
 
-export { testApp, bootTestApp } from './test-harness.js';
-export type { TestAppOptions } from './test-harness.js';
+export { testApp, bootTestApp, testPip } from './test-harness.js';
+export type { TestAppOptions, TestPipBuilder } from './test-harness.js';
+
+export { hookSignals } from './signals.js';
+export type { HookSignalsOptions, SignalTarget } from './signals.js';
 
 // Task 9b: CLI envelope type is exported so adapter packages can produce the
 // same shape from related tooling (release-tooling, pip scaffolds, etc.).