@arki/dot 0.1.0

package/dist/lifecycle.js

@@ -0,0 +1,78 @@
+/**
+ * Lifecycle primitives for the DOT kernel.
+ *
+ * The kernel uses a 5-hook lifecycle that runs in dependency order:
+ *
+ *  - `configure` — synchronous registration of metadata, routes, services
+ *  - `boot`       — async open of resources, publishes services into `app.services`
+ *  - `start`      — async start of active work (workers, schedulers, listeners)
+ *  - `stop`       — async stop of active work, runs in reverse-topological order
+ *  - `dispose`    — async release of booted resources, runs in reverse-topological order
+ *
+ * Hook semantics, failure ordering, and idempotency rules are documented on the
+ * public `DotApp` interface in `./define-app.ts`.
+ */
+/**
+ * The complete set of lifecycle hooks in topological execution order.
+ * `stop` and `dispose` run in reverse-topological order across pips, but the
+ * sequence of hooks themselves is always `configure -> boot -> start -> stop -> dispose`.
+ */
+export const DOT_LIFECYCLE_HOOKS = [
+    'configure',
+    'boot',
+    'start',
+    'stop',
+    'dispose',
+];
+/** Stable error codes for lifecycle failures. */
+export const DotLifecycleErrorCode = {
+    /** A `configure` hook attempted async work (returned a Promise). */
+    ConfigureAsync: 'DOT_LIFECYCLE_E001',
+    /** A `configure` hook threw. */
+    ConfigureFailed: 'DOT_LIFECYCLE_E002',
+    /** A `boot` hook threw. */
+    BootFailed: 'DOT_LIFECYCLE_E003',
+    /** A `start` hook threw. */
+    StartFailed: 'DOT_LIFECYCLE_E004',
+    /** One or more `stop` hooks threw — aggregate. */
+    StopFailed: 'DOT_LIFECYCLE_E005',
+    /** One or more `dispose` hooks threw — aggregate. */
+    DisposeFailed: 'DOT_LIFECYCLE_E006',
+    /** Caller tried to reuse the app after dispose. */
+    ReuseAfterDispose: 'DOT_LIFECYCLE_E007',
+    /** Caller tried to reuse the app after a failed lifecycle. */
+    ReuseAfterFailure: 'DOT_LIFECYCLE_E008',
+    /** Dependency graph contains a cycle. */
+    DependencyCycle: 'DOT_LIFECYCLE_E009',
+    /** Pip declared a dependency that isn't registered. */
+    MissingDependency: 'DOT_LIFECYCLE_E010',
+    /** Pip registered twice. */
+    DuplicatePip: 'DOT_LIFECYCLE_E011',
+};
+/**
+ * Structured error thrown for any lifecycle failure or misuse.
+ *
+ * Carries:
+ *  - `code`     — stable machine-readable error code (see {@link DotLifecycleErrorCode}).
+ *  - `phase`    — which hook (or pseudo-hook) failed.
+ *  - `pip`   — which pip name, when applicable.
+ *  - `cause`    — original error if wrapped from a hook throw.
+ *  - `failures` — for aggregate errors (stop/dispose), the per-pip failures.
+ */
+export class DotLifecycleError extends Error {
+    code;
+    phase;
+    pip;
+    cause;
+    failures;
+    constructor(args) {
+        super(args.message);
+        this.name = 'DotLifecycleError';
+        this.code = args.code;
+        this.phase = args.phase;
+        this.pip = args.pip;
+        this.cause = args.cause;
+        this.failures = args.failures;
+    }
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAgC;IAC9D,WAAW;IACX,MAAM;IACN,OAAO;IACP,MAAM;IACN,SAAS;CACD,CAAC;AAiBX,iDAAiD;AACjD,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,oEAAoE;IACpE,cAAc,EAAE,oBAAoB;IACpC,gCAAgC;IAChC,eAAe,EAAE,oBAAoB;IACrC,2BAA2B;IAC3B,UAAU,EAAE,oBAAoB;IAChC,4BAA4B;IAC5B,WAAW,EAAE,oBAAoB;IACjC,kDAAkD;IAClD,UAAU,EAAE,oBAAoB;IAChC,qDAAqD;IACrD,aAAa,EAAE,oBAAoB;IACnC,mDAAmD;IACnD,iBAAiB,EAAE,oBAAoB;IACvC,8DAA8D;IAC9D,iBAAiB,EAAE,oBAAoB;IACvC,yCAAyC;IACzC,eAAe,EAAE,oBAAoB;IACrC,uDAAuD;IACvD,iBAAiB,EAAE,oBAAoB;IACvC,4BAA4B;IAC5B,YAAY,EAAE,oBAAoB;CAC1B,CAAC;AAIX;;;;;;;;;GASG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,IAAI,CAA6B;IACjC,KAAK,CAAmB;IACxB,GAAG,CAAU;IACJ,KAAK,CAAW;IACzB,QAAQ,CAAqC;IAEtD,YAAY,IAOX;QACC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACpB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAChC,CAAC;CACF"}

package/dist/manifest.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Manifest types for the DOT kernel.
+ *
+ * A `DotAppManifest` is the static, declarative description of an app: which
+ * pips are registered, what routes/services they contribute, and how they
+ * depend on each other. It is built up during the `configure` phase from
+ * registration calls and finalised once `configure` completes.
+ *
+ * CONTRACT: `DotAppManifest` always exposes the same five top-level arrays
+ * (`pips`, `routes`, `services`, `lifecycle`, `dependencies`). Consumers
+ * MUST NOT see an omitted array — empty is empty, but never missing.
+ * This shape is referenced by Task 7's scorecard.
+ */
+import type { DotLifecycleHook } from './lifecycle.js';
+/**
+ * Kind of service that a pip can publish.
+ *
+ * Well-known kinds map 1:1 to the canonical `@arki/*` adapters. `custom`
+ * is the escape hatch for pip-defined service kinds — use it whenever a
+ * pip publishes something that does not fit a reserved shape.
+ */
+export type ServiceKind = 'env' | 'db' | 'kv' | 'queue' | 'auth' | 'email' | 'logger' | 'event-store' | 'message-bus' | 'custom';
+/** Transport that a route is exposed under. */
+export type RouteTransport = 'http' | 'orpc' | 'trpc' | 'rpc' | 'custom';
+/** Kind of dependency edge between two pips. */
+export type DependencyEdgeKind = 'requires' | 'provides' | 'uses';
+/**
+ * Top-level manifest describing the static shape of a DOT app.
+ *
+ * Always carries the five arrays — never omits any of them.
+ */
+export type DotAppManifest = {
+    app: {
+        name: string;
+        version?: string;
+    };
+    pips: PipManifest[];
+    routes: RouteManifest[];
+    services: ServiceManifest[];
+    lifecycle: LifecycleManifest[];
+    dependencies: DependencyEdge[];
+};
+/** Single pip's declarative metadata. */
+export type PipManifest = {
+    name: string;
+    version?: string;
+    dependencies: readonly string[];
+    provides: readonly string[];
+};
+/** Single route exposed by a pip. */
+export type RouteManifest = {
+    id: string;
+    pip: string;
+    method?: string;
+    path?: string;
+    transport: RouteTransport;
+};
+/** Single service published by a pip. */
+export type ServiceManifest = {
+    name: string;
+    pip: string;
+    kind: ServiceKind;
+};
+/** Which lifecycle hooks a pip participates in. */
+export type LifecycleManifest = {
+    pip: string;
+    hooks: readonly DotLifecycleHook[];
+};
+/** Directed edge in the pip dependency graph. */
+export type DependencyEdge = {
+    from: string;
+    to: string;
+    kind: DependencyEdgeKind;
+};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GACnB,KAAK,GACL,IAAI,GACJ,IAAI,GACJ,OAAO,GACP,MAAM,GACN,OAAO,GACP,QAAQ,GACR,aAAa,GACb,aAAa,GACb,QAAQ,CAAC;AAEb,+CAA+C;AAC/C,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEzE,gDAAgD;AAChD,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;AAElE;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,GAAG,EAAE;QACH,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,YAAY,EAAE,cAAc,EAAE,CAAC;CAChC,CAAC;AAEF,yCAAyC;AACzC,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B,CAAC;AAEF,qCAAqC;AACrC,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,cAAc,CAAC;CAC3B,CAAC;AAEF,yCAAyC;AACzC,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,WAAW,CAAC;CACnB,CAAC;AAEF,mDAAmD;AACnD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACpC,CAAC;AAEF,iDAAiD;AACjD,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,kBAAkB,CAAC;CAC1B,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,14 @@
+/**
+ * Manifest types for the DOT kernel.
+ *
+ * A `DotAppManifest` is the static, declarative description of an app: which
+ * pips are registered, what routes/services they contribute, and how they
+ * depend on each other. It is built up during the `configure` phase from
+ * registration calls and finalised once `configure` completes.
+ *
+ * CONTRACT: `DotAppManifest` always exposes the same five top-level arrays
+ * (`pips`, `routes`, `services`, `lifecycle`, `dependencies`). Consumers
+ * MUST NOT see an omitted array — empty is empty, but never missing.
+ * This shape is referenced by Task 7's scorecard.
+ */
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/pip-contract.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Public pip contract for the DOT kernel.
+ *
+ * A `DotPip` is a plain object with a name, optional dependency list, and
+ * up to five lifecycle hooks. The kernel calls each hook in dependency order
+ * (or reverse-dependency order for `stop`/`dispose`).
+ *
+ * Design constraints:
+ *
+ *  - `configure` is SYNC. Returning a Promise is an error — the kernel will
+ *    throw {@link DotLifecycleError} with code `DOT_LIFECYCLE_E001`.
+ *  - `boot` may publish services into the app; downstream pips see them via
+ *    {@link DotBootContext.services}.
+ *  - `stop` and `dispose` continue through individual pip failures and
+ *    report an aggregate error.
+ */
+import type { DotLifecycleHook } from './lifecycle.js';
+import type { DependencyEdgeKind, RouteTransport, ServiceKind } from './manifest.js';
+/**
+ * Aggregate registration record produced during the `configure` phase.
+ *
+ * The kernel exposes one of these to each pip via {@link DotConfigureContext}
+ * and uses the merged result to build the final `DotAppManifest`.
+ */
+export type DotManifestContribution = {
+    /** Services this pip publishes. */
+    services?: readonly {
+        name: string;
+        kind: ServiceKind;
+    }[];
+    /** Routes this pip exposes. */
+    routes?: readonly {
+        id: string;
+        method?: string;
+        path?: string;
+        transport: RouteTransport;
+    }[];
+    /** Additional `provides` capability strings (joined with the pip's `provides`). */
+    provides?: readonly string[];
+    /** Additional dependency edges. */
+    dependencies?: readonly {
+        to: string;
+        kind?: DependencyEdgeKind;
+    }[];
+};
+/** Context provided to a `manifest` callback. */
+export type DotManifestContext<TServices extends Record<string, unknown>> = {
+    pipName: string;
+    /** Services published by dependencies that have already booted (read-only). */
+    services: Readonly<Partial<TServices>>;
+};
+/** Context provided to a `configure` hook. */
+export type DotConfigureContext = {
+    pipName: string;
+    /** App name. */
+    appName: string;
+    /**
+     * Register a service this pip publishes.
+     * Registration is metadata-only — the actual service instance is returned
+     * from the `boot` hook in `DotBootResult.services`.
+     */
+    registerService(name: string, kind: ServiceKind): void;
+    /** Register a route this pip exposes. */
+    registerRoute(route: {
+        id: string;
+        method?: string;
+        path?: string;
+        transport: RouteTransport;
+    }): void;
+    /** Mark the pip as participating in a lifecycle hook. */
+    registerLifecycleHook(hook: DotLifecycleHook): void;
+    /** Append `provides` capability strings. */
+    declareProvides(...capabilities: string[]): void;
+    /** Append an extra dependency edge (alongside `pip.dependencies`). */
+    declareDependency(to: string, kind?: DependencyEdgeKind): void;
+};
+/** Context provided to a `boot` hook. */
+export type DotBootContext = {
+    pipName: string;
+    appName: string;
+    /**
+     * Services published by prior-booted pips, keyed by service name.
+     * Use this for dependency injection between pips.
+     */
+    services: ReadonlyMap<string, unknown>;
+    /** Read-only configuration bag. */
+    config: Readonly<Record<string, unknown>>;
+};
+/** Context provided to a `start` hook. */
+export type DotStartContext<TServices extends Record<string, unknown>> = {
+    pipName: string;
+    appName: string;
+    services: TServices;
+};
+/** Context provided to a `stop` hook. */
+export type DotStopContext<TServices extends Record<string, unknown>> = {
+    pipName: string;
+    appName: string;
+    services: TServices;
+};
+/** Context provided to a `dispose` hook. */
+export type DotDisposeContext<TServices extends Record<string, unknown>> = {
+    pipName: string;
+    appName: string;
+    services: TServices;
+};
+/** Return value of a `boot` hook. */
+export type DotBootResult<TServices extends Record<string, unknown>> = {
+    /** Services this pip publishes — added to `app.services` and visible to dependent pips. */
+    services?: TServices;
+};
+/**
+ * The DOT pip contract.
+ *
+ * Default `TServices` is `Record<string, never>` so pips that don't publish
+ * services don't have to specify a type argument. Default `TManifest` is the
+ * full contribution shape.
+ */
+export type DotPip<TServices extends Record<string, unknown> = Record<string, never>, TManifest extends DotManifestContribution = DotManifestContribution> = {
+    /** Unique identifier for this pip within the app. */
+    name: string;
+    /** Optional semantic version string. */
+    version?: string;
+    /**
+     * Names of pips this one depends on.
+     * The kernel ensures dependencies are configured/booted/started first, and
+     * stopped/disposed last.
+     */
+    dependencies?: readonly string[];
+    /** Capability strings this pip advertises (for `dependencies` resolution by capability). */
+    provides?: readonly string[];
+    /**
+     * Optional static or callback-form manifest contribution. The kernel merges
+     * this into the final manifest after `configure` runs.
+     */
+    manifest?: TManifest | ((ctx: DotManifestContext<TServices>) => TManifest);
+    /**
+     * SYNC registration hook. Declare metadata, register routes/services/jobs.
+     * MUST NOT perform IO, MUST NOT return a Promise.
+     */
+    configure?: (ctx: DotConfigureContext) => void;
+    /** Async open-resources hook. Returns published services for DI. */
+    boot?: (ctx: DotBootContext) => Promise<DotBootResult<TServices>> | DotBootResult<TServices>;
+    /** Async begin-active-work hook. Runs after every pip's `boot` succeeds. */
+    start?: (ctx: DotStartContext<TServices>) => Promise<void> | void;
+    /** Async halt-active-work hook. Runs in reverse-topological order. */
+    stop?: (ctx: DotStopContext<TServices>) => Promise<void> | void;
+    /** Async release-resources hook. Runs in reverse-topological order. */
+    dispose?: (ctx: DotDisposeContext<TServices>) => Promise<void> | void;
+};
+/**
+ * Type-narrowing helper for pip authors.
+ *
+ * @example
+ * export const myPip = defineDotPip<{ db: MyDb }>({
+ *   name: 'my-pip',
+ *   async boot() {
+ *     const db = await openDb();
+ *     return { services: { db } };
+ *   },
+ *   async dispose({ services }) {
+ *     await services.db.close();
+ *   },
+ * });
+ */
+export declare function defineDotPip<TServices extends Record<string, unknown> = Record<string, never>>(pip: DotPip<TServices>): DotPip<TServices>;
+/** Internal type alias used by the kernel to erase pip service generics. */
+export type AnyDotPip = DotPip<Record<string, unknown>, DotManifestContribution>;
+/** Internal helper: extract the `provides` field from a pip (always returns an array). */
+export declare function pipProvides(pip: AnyDotPip): readonly string[];
+/** Internal helper: extract the `dependencies` field from a pip (always returns an array). */
+export declare function pipDependencies(pip: AnyDotPip): readonly string[];
+/**
+ * Stable error thrown by DOT pip adapters.
+ *
+ * Adapters MUST throw `DotPipError` (not raw `Error`) when surfacing a
+ * misconfiguration, missing-input, or other fail-fast condition. Consumers
+ * and coding agents can then match on a stable `code`, follow `docsUrl`,
+ * and apply `remediation` without parsing the message.
+ *
+ * Codes are per-adapter. Recommended prefix is `<PKG>_PIP_E<NNN>` (e.g.
+ * `KV_PIP_E001`, `DB_PIP_E001`). The kernel does not own the code
+ * namespace — each adapter defines its own constants and links them in
+ * its README.
+ *
+ * @see packages/dot/docs/principles.md — principle 1.3 ("errors are part
+ * of the API") and principle 4 ("agent-discoverable everywhere").
+ *
+ * @example
+ * ```ts
+ * import { DotPipError } from '@arki/dot/pip';
+ *
+ * const KV_PIP_ERROR_CODES = { urlNotConfigured: 'KV_PIP_E001' } as const;
+ *
+ * throw new DotPipError({
+ *   code: KV_PIP_ERROR_CODES.urlNotConfigured,
+ *   message: '[kv] KV URL is not configured.',
+ *   remediation: 'Pass options.url to kv(...) or set KV_URL in the environment.',
+ *   docsUrl: 'https://arki.dev/dot/errors/kv-pip-e001',
+ * });
+ * ```
+ */
+export declare class DotPipError extends Error {
+    /** Stable error code, e.g. `KV_PIP_E001`. */
+    readonly code: string;
+    /** One-sentence guidance on how to fix the underlying problem. */
+    readonly remediation: string;
+    /** URL of the documentation page that explains this error. */
+    readonly docsUrl: string;
+    constructor(args: {
+        readonly code: string;
+        readonly message: string;
+        readonly remediation: string;
+        readonly docsUrl: string;
+    });
+}
+/** Re-exported for downstream typing. */
+export { type DotAppManifest, type PipManifest } from './manifest.js';
+//# sourceMappingURL=pip-contract.d.ts.map

package/dist/pip-contract.d.ts.map

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

package/dist/pip-contract.js

@@ -0,0 +1,90 @@
+/**
+ * Public pip contract for the DOT kernel.
+ *
+ * A `DotPip` is a plain object with a name, optional dependency list, and
+ * up to five lifecycle hooks. The kernel calls each hook in dependency order
+ * (or reverse-dependency order for `stop`/`dispose`).
+ *
+ * Design constraints:
+ *
+ *  - `configure` is SYNC. Returning a Promise is an error — the kernel will
+ *    throw {@link DotLifecycleError} with code `DOT_LIFECYCLE_E001`.
+ *  - `boot` may publish services into the app; downstream pips see them via
+ *    {@link DotBootContext.services}.
+ *  - `stop` and `dispose` continue through individual pip failures and
+ *    report an aggregate error.
+ */
+/**
+ * Type-narrowing helper for pip authors.
+ *
+ * @example
+ * export const myPip = defineDotPip<{ db: MyDb }>({
+ *   name: 'my-pip',
+ *   async boot() {
+ *     const db = await openDb();
+ *     return { services: { db } };
+ *   },
+ *   async dispose({ services }) {
+ *     await services.db.close();
+ *   },
+ * });
+ */
+export function defineDotPip(pip) {
+    return pip;
+}
+/** Internal helper: extract the `provides` field from a pip (always returns an array). */
+export function pipProvides(pip) {
+    return pip.provides ?? [];
+}
+/** Internal helper: extract the `dependencies` field from a pip (always returns an array). */
+export function pipDependencies(pip) {
+    return pip.dependencies ?? [];
+}
+/**
+ * Stable error thrown by DOT pip adapters.
+ *
+ * Adapters MUST throw `DotPipError` (not raw `Error`) when surfacing a
+ * misconfiguration, missing-input, or other fail-fast condition. Consumers
+ * and coding agents can then match on a stable `code`, follow `docsUrl`,
+ * and apply `remediation` without parsing the message.
+ *
+ * Codes are per-adapter. Recommended prefix is `<PKG>_PIP_E<NNN>` (e.g.
+ * `KV_PIP_E001`, `DB_PIP_E001`). The kernel does not own the code
+ * namespace — each adapter defines its own constants and links them in
+ * its README.
+ *
+ * @see packages/dot/docs/principles.md — principle 1.3 ("errors are part
+ * of the API") and principle 4 ("agent-discoverable everywhere").
+ *
+ * @example
+ * ```ts
+ * import { DotPipError } from '@arki/dot/pip';
+ *
+ * const KV_PIP_ERROR_CODES = { urlNotConfigured: 'KV_PIP_E001' } as const;
+ *
+ * throw new DotPipError({
+ *   code: KV_PIP_ERROR_CODES.urlNotConfigured,
+ *   message: '[kv] KV URL is not configured.',
+ *   remediation: 'Pass options.url to kv(...) or set KV_URL in the environment.',
+ *   docsUrl: 'https://arki.dev/dot/errors/kv-pip-e001',
+ * });
+ * ```
+ */
+export class DotPipError extends Error {
+    /** Stable error code, e.g. `KV_PIP_E001`. */
+    code;
+    /** One-sentence guidance on how to fix the underlying problem. */
+    remediation;
+    /** URL of the documentation page that explains this error. */
+    docsUrl;
+    constructor(args) {
+        super(args.message);
+        this.name = 'DotPipError';
+        this.code = args.code;
+        this.remediation = args.remediation;
+        this.docsUrl = args.docsUrl;
+    }
+}
+/** Re-exported for downstream typing. */
+export {} from './manifest.js';
+//# sourceMappingURL=pip-contract.js.map

package/dist/pip-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pip-contract.js","sourceRoot":"","sources":["../src/pip-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAsJH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAsB;IAEtB,OAAO,GAAG,CAAC;AACb,CAAC;AAKD,0FAA0F;AAC1F,MAAM,UAAU,WAAW,CAAC,GAAc;IACxC,OAAO,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC;AAC5B,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,eAAe,CAAC,GAAc;IAC5C,OAAO,GAAG,CAAC,YAAY,IAAI,EAAE,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,6CAA6C;IACpC,IAAI,CAAS;IACtB,kEAAkE;IACzD,WAAW,CAAS;IAC7B,8DAA8D;IACrD,OAAO,CAAS;IAEzB,YAAY,IAKX;QACC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC9B,CAAC;CACF;AAED,yCAAyC;AAEzC,OAAO,EAAyC,MAAM,eAAe,CAAC"}

package/dist/pip.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Narrow public surface for pip authors.
+ *
+ * Exposes the new-kernel pip contract and the entry points a pip
+ * author needs to author + test pips — `defineDotPip`, `defineApp`,
+ * `testApp` / `bootTestApp`, plus lifecycle / manifest / diagnostics types.
+ *
+ * Does NOT re-export the legacy `Dot` / `createDot` builder or the legacy
+ * auth/db/event-sourcing modules. Adapter packages (e.g. `@arki/env/dot`,
+ * `@arki/kv/dot`, `@arki/db/dot`) import from this subpath so their
+ * `*.d.ts` graphs do not pull in the legacy surface — keeping their
+ * compile times tight and decoupling adapters from the legacy retirement
+ * schedule (Task 12).
+ *
+ * @example
+ * ```ts
+ * import { defineDotPip, type DotPip } from '@arki/dot/pip';
+ * ```
+ */
+export { defineDotPip, DotPipError } from './pip-contract.js';
+export type { AnyDotPip, DotPip, DotBootContext, DotBootResult, DotConfigureContext, DotDisposeContext, DotManifestContext, DotManifestContribution, DotStartContext, DotStopContext, } from './pip-contract.js';
+export { defineApp } from './define-app.js';
+export type { DotApp, DotAppBuilder, DotAppConfigured } from './define-app.js';
+export { testApp, bootTestApp } from './test-harness.js';
+export type { TestAppOptions } from './test-harness.js';
+export type { DotLifecycleHook, DotLifecycleState, DotLifecyclePipFailure, DotLifecycleErrorCodeValue, } from './lifecycle.js';
+export { DotLifecycleError, DotLifecycleErrorCode, DOT_LIFECYCLE_HOOKS } from './lifecycle.js';
+export type { DotAppManifest, PipManifest, RouteManifest, ServiceManifest, LifecycleManifest, DependencyEdge, DependencyEdgeKind, ServiceKind, RouteTransport, } from './manifest.js';
+export type { DotDiagnosticsSnapshot, PipDiagnostic, RouteDiagnostic, ServiceDiagnostic, LifecycleDiagnostic, DiagnosticIssue, DiagnosticSeverity, DiagnosticStatus, } from './diagnostics.js';
+export type { DotLifecycleEvent, DotLifecycleEventStatus, DotLifecycleObserver, DotPhaseLifecycleEvent, DotPipHookLifecycleEvent, } from './lifecycle-observer.js';
+export { renderTimeline } from './timeline.js';
+export type { RenderTimelineOptions } from './timeline.js';
+//# sourceMappingURL=pip.d.ts.map

package/dist/pip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pip.d.ts","sourceRoot":"","sources":["../src/pip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC9D,YAAY,EACV,SAAS,EACT,MAAM,EACN,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE/E,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACzD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE/F,YAAY,EACV,cAAc,EACd,WAAW,EACX,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,cAAc,GACf,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,sBAAsB,EACtB,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}

package/dist/pip.js

@@ -0,0 +1,25 @@
+/**
+ * Narrow public surface for pip authors.
+ *
+ * Exposes the new-kernel pip contract and the entry points a pip
+ * author needs to author + test pips — `defineDotPip`, `defineApp`,
+ * `testApp` / `bootTestApp`, plus lifecycle / manifest / diagnostics types.
+ *
+ * Does NOT re-export the legacy `Dot` / `createDot` builder or the legacy
+ * auth/db/event-sourcing modules. Adapter packages (e.g. `@arki/env/dot`,
+ * `@arki/kv/dot`, `@arki/db/dot`) import from this subpath so their
+ * `*.d.ts` graphs do not pull in the legacy surface — keeping their
+ * compile times tight and decoupling adapters from the legacy retirement
+ * schedule (Task 12).
+ *
+ * @example
+ * ```ts
+ * import { defineDotPip, type DotPip } from '@arki/dot/pip';
+ * ```
+ */
+export { defineDotPip, DotPipError } from './pip-contract.js';
+export { defineApp } from './define-app.js';
+export { testApp, bootTestApp } from './test-harness.js';
+export { DotLifecycleError, DotLifecycleErrorCode, DOT_LIFECYCLE_HOOKS } from './lifecycle.js';
+export { renderTimeline } from './timeline.js';
+//# sourceMappingURL=pip.js.map

package/dist/pip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pip.js","sourceRoot":"","sources":["../src/pip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAc9D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AASzD,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAiC/F,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}