@arki/dot 0.1.0

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

@@ -0,0 +1,43 @@
+/**
+ * Renderers for `dot explain`.
+ *
+ * Reads a configured (or booted) app's `manifest` and emits one of:
+ *   - JSON envelope to stdout (when --json)
+ *   - human-readable plain text to stdout (default)
+ *
+ * The JSON envelope shape matches the broader release-tooling envelope so
+ * agents can parse the output identically across CLI surfaces.
+ */
+import type { DiagnosticIssue } from '../diagnostics.js';
+import type { DotAppManifest } from '../manifest.js';
+export type DotCliEnvelopeStatus = 'success' | 'failure' | 'warning';
+export type DotCliEnvelope<T = unknown> = {
+    status: DotCliEnvelopeStatus;
+    command: string;
+    generatedAt: string;
+    data: T;
+    errors: DiagnosticIssue[];
+};
+export type ExplainSource = {
+    /** The static manifest produced by configure (or read off a booted app). */
+    manifest: DotAppManifest;
+};
+export type RenderOptions = {
+    /** Set to true to emit JSON to stdout; otherwise pretty text. */
+    json: boolean;
+    /** Override clock for deterministic test output. */
+    now?: () => Date;
+    /** Override stdout sink. Defaults to `process.stdout.write`. */
+    out?: (line: string) => void;
+};
+/**
+ * Build the envelope without writing anything. Useful for tests that need
+ * to assert shape and for embedding the CLI logic from other tools.
+ */
+export declare function buildExplainEnvelope(source: ExplainSource, opts: RenderOptions): DotCliEnvelope<DotAppManifest>;
+/**
+ * Render the explain output. Returns the envelope so callers can act on it
+ * (e.g. set the process exit code based on `status`).
+ */
+export declare function renderExplain(source: ExplainSource, opts: RenderOptions): DotCliEnvelope<DotAppManifest>;
+//# sourceMappingURL=render-explain.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"render-explain.d.ts","sourceRoot":"","sources":["../../src/cli/render-explain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAErE,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,OAAO,IAAI;IACxC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,CAAC,CAAC;IACR,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,4EAA4E;IAC5E,QAAQ,EAAE,cAAc,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,gEAAgE;IAChE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B,CAAC;AAWF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa,GAAG,cAAc,CAAC,cAAc,CAAC,CAQ/G;AAsFD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa,GAAG,cAAc,CAAC,cAAc,CAAC,CAWxG"}

package/dist/cli/render-explain.js

@@ -0,0 +1,127 @@
+/**
+ * Renderers for `dot explain`.
+ *
+ * Reads a configured (or booted) app's `manifest` and emits one of:
+ *   - JSON envelope to stdout (when --json)
+ *   - human-readable plain text to stdout (default)
+ *
+ * The JSON envelope shape matches the broader release-tooling envelope so
+ * agents can parse the output identically across CLI surfaces.
+ */
+const defaultOut = (line) => {
+    process.stdout.write(line);
+};
+function nowIso(opts) {
+    const factory = opts.now ?? (() => new Date());
+    return factory().toISOString();
+}
+/**
+ * Build the envelope without writing anything. Useful for tests that need
+ * to assert shape and for embedding the CLI logic from other tools.
+ */
+export function buildExplainEnvelope(source, opts) {
+    return {
+        status: 'success',
+        command: 'explain',
+        generatedAt: nowIso(opts),
+        data: source.manifest,
+        errors: [],
+    };
+}
+function pad(s, width) {
+    return s.length >= width ? s : s + ' '.repeat(width - s.length);
+}
+function renderTextManifest(manifest) {
+    const lines = [];
+    const title = `App: ${manifest.app.name}${manifest.app.version ? `@${manifest.app.version}` : ''}`;
+    lines.push(title);
+    lines.push('='.repeat(title.length));
+    lines.push('');
+    // Pips
+    lines.push(`Pips (${manifest.pips.length})`);
+    if (manifest.pips.length === 0) {
+        lines.push('  (none)');
+    }
+    else {
+        const widthName = Math.max(6, ...manifest.pips.map(p => p.name.length));
+        lines.push(`  ${pad('NAME', widthName)}  VERSION  DEPENDENCIES`);
+        for (const p of manifest.pips) {
+            const version = p.version ?? '-';
+            const deps = p.dependencies.length > 0 ? p.dependencies.join(', ') : '-';
+            lines.push(`  ${pad(p.name, widthName)}  ${pad(version, 7)}  ${deps}`);
+        }
+    }
+    lines.push('');
+    // Services
+    lines.push(`Services (${manifest.services.length})`);
+    if (manifest.services.length === 0) {
+        lines.push('  (none)');
+    }
+    else {
+        const widthName = Math.max(4, ...manifest.services.map(s => s.name.length));
+        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('');
+    // Routes
+    lines.push(`Routes (${manifest.routes.length})`);
+    if (manifest.routes.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}`);
+        }
+    }
+    lines.push('');
+    // Dependencies
+    lines.push(`Dependencies (${manifest.dependencies.length})`);
+    if (manifest.dependencies.length === 0) {
+        lines.push('  (none)');
+    }
+    else {
+        for (const d of manifest.dependencies) {
+            lines.push(`  ${d.from} --[${d.kind}]--> ${d.to}`);
+        }
+    }
+    lines.push('');
+    // Lifecycle
+    lines.push(`Lifecycle hooks (${manifest.lifecycle.length})`);
+    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`);
+        for (const l of manifest.lifecycle) {
+            const hooks = l.hooks.length > 0 ? l.hooks.join(', ') : '-';
+            lines.push(`  ${pad(l.pip, widthPip)}  ${hooks}`);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Render the explain output. Returns the envelope so callers can act on it
+ * (e.g. set the process exit code based on `status`).
+ */
+export function renderExplain(source, opts) {
+    const envelope = buildExplainEnvelope(source, opts);
+    const out = opts.out ?? defaultOut;
+    if (opts.json) {
+        out(`${JSON.stringify(envelope, null, 2)}\n`);
+    }
+    else {
+        out(`${renderTextManifest(source.manifest)}\n`);
+    }
+    return envelope;
+}
+//# sourceMappingURL=render-explain.js.map

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

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

package/dist/define-app.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Public entry point for the new DOT kernel.
+ *
+ * `defineApp(name)` returns a `DotAppBuilder` that accumulates pips via
+ * `.use(pip)`, then transitions through the 5-hook lifecycle:
+ *
+ *   defineApp -> use* -> configure() -> boot() -> start() -> stop() -> dispose()
+ *
+ * Most callers don't need to call `configure()` explicitly — `boot()` runs it
+ * implicitly. `boot()` is also implicit when starting from `defined` via
+ * `start()`.
+ *
+ * See `./lifecycle.ts` for hook semantics, failure ordering, idempotency rules.
+ */
+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 { DotPip } from './pip-contract.js';
+/**
+ * Public DotApp surface. The internal `DotAppImpl` implements this; consumers
+ * see only these members.
+ */
+export type DotApp<TServices extends Record<string, unknown>> = {
+    /** App name (passed to `defineApp`). */
+    readonly name: string;
+    /** Current lifecycle state. */
+    readonly state: DotLifecycleState;
+    /**
+     * Services published by booted pips, merged into a single record.
+     * Empty before `boot()` succeeds.
+     */
+    readonly services: TServices;
+    /** Declarative manifest — describes the static shape of the app. */
+    readonly manifest: DotAppManifest;
+    /** Point-in-time diagnostics snapshot. Re-computed on every access. */
+    readonly diagnostics: DotDiagnosticsSnapshot;
+    /**
+     * Start active work. Boots first if app is `defined` or `configured`.
+     * Idempotent while `started`. Throws if app is `failed` or `disposed`.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop active work. Keeps booted resources for later cleanup.
+     * Idempotent while not `started`.
+     */
+    stop(): Promise<void>;
+    /**
+     * Release booted resources. Runs stop() first if `started`.
+     * Idempotent while `disposed`.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Register an in-process lifecycle observer. Returns an unsubscribe
+     * function. Observers added here see events from this point onward —
+     * pass observers through `defineApp(name, { observers })` to catch
+     * `configure`-phase events too.
+     */
+    subscribe(observer: DotLifecycleObserver): () => void;
+    /**
+     * Render the recorded lifecycle as an ASCII waterfall. Reads from
+     * the current `diagnostics` snapshot — call after `boot()` /
+     * `dispose()` / a failure to see the full picture.
+     */
+    timeline(): string;
+};
+/**
+ * Intermediate type after `configure()` but before `boot()`.
+ * Exposes the manifest and diagnostics already, but no `services` yet.
+ */
+export type DotAppConfigured<TServices extends Record<string, unknown>> = {
+    readonly name: string;
+    readonly state: DotLifecycleState;
+    readonly manifest: DotAppManifest;
+    readonly diagnostics: DotDiagnosticsSnapshot;
+    /** Continue the lifecycle. */
+    boot(): Promise<DotApp<TServices>>;
+    start(): Promise<DotApp<TServices>>;
+    /** See {@link DotApp.subscribe}. */
+    subscribe(observer: DotLifecycleObserver): () => void;
+    /** See {@link DotApp.timeline}. */
+    timeline(): string;
+};
+/**
+ * Builder produced by `defineApp(name)`.
+ *
+ * `.use(pip)` is type-tracking: services published by the pip are
+ * merged into `TServices` for the next builder.
+ */
+export type DotAppBuilder<TServices extends Record<string, unknown>> = {
+    /** Register a pip. Returns a new builder with merged services. */
+    use<TNew extends Record<string, unknown>>(pip: DotPip<TNew>): DotAppBuilder<TServices & TNew>;
+    /** Run the configure phase synchronously. Throws on configure failure. */
+    configure(): DotAppConfigured<TServices>;
+    /** Run configure + boot. Throws on configure or boot failure. */
+    boot(): Promise<DotApp<TServices>>;
+    /** Convenience: configure + boot + start. */
+    start(): Promise<DotApp<TServices>>;
+};
+/**
+ * Create a new DOT app builder.
+ *
+ * @example
+ * const app = await defineApp('my-app')
+ *   .use(dbPip)
+ *   .use(authPip)
+ *   .boot();
+ *
+ * await app.start();
+ * console.log(app.manifest);
+ * // ...
+ * await app.dispose();
+ */
+export declare function defineApp<TServices extends Record<string, unknown> = Record<string, never>>(name: string, options?: {
+    version?: string;
+    config?: Readonly<Record<string, unknown>>;
+    /**
+     * In-process lifecycle observers, registered before the first phase
+     * fires. Required if you want to see `configure`-phase events — after
+     * configure runs, observers can be added post-hoc via
+     * `configured.subscribe(...)` or `app.subscribe(...)`.
+     */
+    observers?: readonly DotLifecycleObserver[];
+}): DotAppBuilder<TServices>;
+//# sourceMappingURL=define-app.d.ts.map

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

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

package/dist/define-app.js

@@ -0,0 +1,126 @@
+/**
+ * Public entry point for the new DOT kernel.
+ *
+ * `defineApp(name)` returns a `DotAppBuilder` that accumulates pips via
+ * `.use(pip)`, then transitions through the 5-hook lifecycle:
+ *
+ *   defineApp -> use* -> configure() -> boot() -> start() -> stop() -> dispose()
+ *
+ * Most callers don't need to call `configure()` explicitly — `boot()` runs it
+ * implicitly. `boot()` is also implicit when starting from `defined` via
+ * `start()`.
+ *
+ * See `./lifecycle.ts` for hook semantics, failure ordering, idempotency rules.
+ */
+import { DotAppImpl } from './kernel/app-instance.js';
+import { renderTimeline } from './timeline.js';
+/**
+ * Create a new DOT app builder.
+ *
+ * @example
+ * const app = await defineApp('my-app')
+ *   .use(dbPip)
+ *   .use(authPip)
+ *   .boot();
+ *
+ * await app.start();
+ * console.log(app.manifest);
+ * // ...
+ * await app.dispose();
+ */
+export function defineApp(name, options = {}) {
+    const state = {
+        appName: name,
+        appVersion: options.version,
+        pips: [],
+        config: options.config,
+        observers: options.observers,
+    };
+    return makeBuilder(state);
+}
+function buildImpl(state) {
+    return new DotAppImpl({
+        appName: state.appName,
+        appVersion: state.appVersion,
+        pips: state.pips,
+        config: state.config,
+        observers: state.observers,
+    });
+}
+function makeBuilder(state) {
+    return {
+        use(pip) {
+            const nextState = {
+                ...state,
+                pips: [...state.pips, pip],
+            };
+            return makeBuilder(nextState);
+        },
+        configure() {
+            const impl = buildImpl(state);
+            impl.runConfigure();
+            return wrapConfigured(impl);
+        },
+        async boot() {
+            const impl = buildImpl(state);
+            await impl.boot();
+            return wrapApp(impl);
+        },
+        async start() {
+            const impl = buildImpl(state);
+            await impl.start();
+            return wrapApp(impl);
+        },
+    };
+}
+function wrapApp(impl) {
+    return {
+        get name() {
+            return impl.name;
+        },
+        get state() {
+            return impl.state;
+        },
+        get services() {
+            return impl.services;
+        },
+        get manifest() {
+            return impl.manifest;
+        },
+        get diagnostics() {
+            return impl.diagnostics;
+        },
+        start: () => impl.start(),
+        stop: () => impl.stop(),
+        dispose: () => impl.dispose(),
+        subscribe: observer => impl.subscribe(observer),
+        timeline: () => renderTimeline(impl.diagnostics),
+    };
+}
+function wrapConfigured(impl) {
+    return {
+        get name() {
+            return impl.name;
+        },
+        get state() {
+            return impl.state;
+        },
+        get manifest() {
+            return impl.manifest;
+        },
+        get diagnostics() {
+            return impl.diagnostics;
+        },
+        async boot() {
+            await impl.boot();
+            return wrapApp(impl);
+        },
+        async start() {
+            await impl.start();
+            return wrapApp(impl);
+        },
+        subscribe: observer => impl.subscribe(observer),
+        timeline: () => renderTimeline(impl.diagnostics),
+    };
+}
+//# sourceMappingURL=define-app.js.map

package/dist/define-app.js.map

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

package/dist/dependency-graph.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Topological sort + cycle detection for pip dependencies.
+ *
+ * Internal to the kernel. Tests must reach it through `defineApp(...)`, never
+ * directly.
+ */
+import type { AnyDotPip } from './pip-contract.js';
+/**
+ * Sort pips so that every pip appears after the pips it depends on.
+ *
+ * @throws {DotLifecycleError}
+ *   - `DOT_LIFECYCLE_E009` if the dependency graph contains a cycle.
+ *   - `DOT_LIFECYCLE_E010` if a declared dependency isn't registered.
+ *   - `DOT_LIFECYCLE_E011` if the same pip name appears twice.
+ */
+export declare function topologicalSort(pips: readonly AnyDotPip[]): readonly AnyDotPip[];
+/** Reverse a sorted pip array — used for `stop` and `dispose` ordering. */
+export declare function reverseTopologicalSort(pips: readonly AnyDotPip[]): readonly AnyDotPip[];
+/** Build the list of dependency edges for the manifest. */
+export declare function buildDependencyEdges(pips: readonly AnyDotPip[]): readonly {
+    from: string;
+    to: string;
+    kind: 'requires';
+}[];
+//# sourceMappingURL=dependency-graph.d.ts.map

package/dist/dependency-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../src/dependency-graph.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAInD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,SAAS,EAAE,CA4DhF;AAED,2EAA2E;AAC3E,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,SAAS,EAAE,CAGvF;AAED,2DAA2D;AAC3D,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,SAAS,EAAE,GACzB,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,EAAE,CAQ3D"}

package/dist/dependency-graph.js

@@ -0,0 +1,86 @@
+/**
+ * Topological sort + cycle detection for pip dependencies.
+ *
+ * Internal to the kernel. Tests must reach it through `defineApp(...)`, never
+ * directly.
+ */
+import { DotLifecycleError, DotLifecycleErrorCode } from './lifecycle.js';
+import { pipDependencies } from './pip-contract.js';
+/**
+ * Sort pips so that every pip appears after the pips it depends on.
+ *
+ * @throws {DotLifecycleError}
+ *   - `DOT_LIFECYCLE_E009` if the dependency graph contains a cycle.
+ *   - `DOT_LIFECYCLE_E010` if a declared dependency isn't registered.
+ *   - `DOT_LIFECYCLE_E011` if the same pip name appears twice.
+ */
+export function topologicalSort(pips) {
+    const byName = new Map();
+    for (const pip of pips) {
+        if (byName.has(pip.name)) {
+            throw new DotLifecycleError({
+                code: DotLifecycleErrorCode.DuplicatePip,
+                phase: 'configure',
+                pip: pip.name,
+                message: `Pip "${pip.name}" is registered twice`,
+            });
+        }
+        byName.set(pip.name, pip);
+    }
+    const sorted = [];
+    const permanent = new Set();
+    const temporary = new Set();
+    const stack = [];
+    const visit = (name) => {
+        if (permanent.has(name))
+            return;
+        if (temporary.has(name)) {
+            const cyclePath = [...stack.slice(stack.indexOf(name)), name].join(' -> ');
+            throw new DotLifecycleError({
+                code: DotLifecycleErrorCode.DependencyCycle,
+                phase: 'configure',
+                pip: name,
+                message: `Dependency cycle detected: ${cyclePath}`,
+            });
+        }
+        const pip = byName.get(name);
+        if (!pip) {
+            throw new DotLifecycleError({
+                code: DotLifecycleErrorCode.MissingDependency,
+                phase: 'configure',
+                pip: name,
+                message: `Pip "${name}" is required as a dependency but is not registered`,
+            });
+        }
+        temporary.add(name);
+        stack.push(name);
+        for (const dep of pipDependencies(pip)) {
+            visit(dep);
+        }
+        stack.pop();
+        // eslint-disable-next-line drizzle/enforce-delete-with-where -- `temporary` is a JS Set, not a Drizzle query.
+        temporary.delete(name);
+        permanent.add(name);
+        sorted.push(pip);
+    };
+    for (const name of byName.keys()) {
+        visit(name);
+    }
+    return sorted;
+}
+/** Reverse a sorted pip array — used for `stop` and `dispose` ordering. */
+export function reverseTopologicalSort(pips) {
+    // eslint-disable-next-line unicorn/no-array-reverse -- lib target is ES2022, toReversed is ES2023.
+    return [...pips].reverse();
+}
+/** Build the list of dependency edges for the manifest. */
+export function buildDependencyEdges(pips) {
+    const edges = [];
+    for (const pip of pips) {
+        for (const dep of pipDependencies(pip)) {
+            edges.push({ from: pip.name, to: dep, kind: 'requires' });
+        }
+    }
+    return edges;
+}
+//# sourceMappingURL=dependency-graph.js.map

package/dist/dependency-graph.js.map

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

package/dist/diagnostics.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Diagnostics types for the DOT kernel.
+ *
+ * Where the manifest describes the static shape of an app, a
+ * `DotDiagnosticsSnapshot` is a point-in-time observability record: the
+ * lifecycle state of the app and every pip, plus structured issues with
+ * remediation guidance.
+ *
+ * CONTRACT: `DotDiagnosticsSnapshot` always exposes the same five arrays
+ * (`pips`, `routes`, `services`, `lifecycle`, `issues`). Consumers must
+ * never see an omitted array — empty is empty, but never missing.
+ * This is the "5 arrays" contract referenced by the kernel spec.
+ */
+import type { DotLifecycleHook, DotLifecycleState } from './lifecycle.js';
+/** Severity of a single diagnostic issue. */
+export type DiagnosticSeverity = 'info' | 'warning' | 'error';
+/** Status of a pip/route/service/lifecycle entry. */
+export type DiagnosticStatus = 'ok' | 'degraded' | 'failed' | 'skipped' | 'missing';
+/**
+ * Single point-in-time diagnostic snapshot of a DotApp.
+ *
+ * Five top-level arrays — pips, routes, services, lifecycle, issues —
+ * are guaranteed to be present even when empty.
+ */
+export type DotDiagnosticsSnapshot = {
+    /** ISO-8601 timestamp at which the snapshot was generated. */
+    generatedAt: string;
+    app: {
+        name: string;
+        state: DotLifecycleState;
+    };
+    pips: PipDiagnostic[];
+    routes: RouteDiagnostic[];
+    services: ServiceDiagnostic[];
+    lifecycle: LifecycleDiagnostic[];
+    issues: DiagnosticIssue[];
+};
+export type PipDiagnostic = {
+    pip: string;
+    status: Extract<DiagnosticStatus, 'ok' | 'degraded' | 'failed' | 'skipped'>;
+    issues: DiagnosticIssue[];
+};
+export type RouteDiagnostic = {
+    id: string;
+    pip: string;
+    status: Extract<DiagnosticStatus, 'ok' | 'degraded' | 'failed'>;
+    issues: DiagnosticIssue[];
+};
+export type ServiceDiagnostic = {
+    service: string;
+    pip: string;
+    status: Extract<DiagnosticStatus, 'ok' | 'degraded' | 'failed' | 'missing'>;
+    issues: DiagnosticIssue[];
+};
+export type LifecycleDiagnostic = {
+    pip: string;
+    hook: DotLifecycleHook;
+    state: DotLifecycleState;
+    /** 0-based topological order of this pip within the hook pass. */
+    order: number;
+    /** Wall-clock duration of the hook call, in milliseconds. */
+    durationMs?: number;
+    issues: DiagnosticIssue[];
+};
+/**
+ * Single structured issue surfaced by the kernel or by a pip.
+ *
+ * `code`, `message`, `remediation` and `docsUrl` are required so that issues
+ * are always actionable — never just "something went wrong".
+ */
+export type DiagnosticIssue = {
+    /** Stable machine-readable code, e.g. `DOT_LIFECYCLE_E003`. */
+    code: string;
+    severity: DiagnosticSeverity;
+    pip?: string;
+    message: string;
+    /** Human-readable remediation: what the developer should do. */
+    remediation: string;
+    /** Link to the relevant docs page for this issue. */
+    docsUrl: string;
+    metadata?: Record<string, unknown>;
+};
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAE1E,6CAA6C;AAC7C,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAE9D,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAEpF;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE;QACH,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,iBAAiB,CAAC;KAC1B,CAAC;IACF,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,SAAS,EAAE,mBAAmB,EAAE,CAAC;IACjC,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC,gBAAgB,EAAE,IAAI,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC,CAAC;IAC5E,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC,gBAAgB,EAAE,IAAI,GAAG,UAAU,GAAG,QAAQ,CAAC,CAAC;IAChE,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC,gBAAgB,EAAE,IAAI,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC,CAAC;IAC5E,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,iBAAiB,CAAC;IACzB,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC"}