@arki/dot 0.1.0 → 0.1.1

package/dist/pip-contract.js

@@ -1,44 +1,202 @@
 /**
- * Public pip contract for the DOT kernel.
+ * Public pip contract for the DOT kernel (v2).
  *
- * 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`).
+ * A pip declares what it **needs** as a shape of type witnesses and
+ * publishes what it **provides** from its `boot` hook. The kernel wires
+ * services by key, injects them into hook contexts under the pip's local
+ * aliases, and fails loudly (coded errors) on unsatisfied needs or key
+ * collisions.
  *
  * 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.
+ *  - `configure` is SYNC. Returning a Promise is an error — the kernel
+ *    throws {@link DotLifecycleError} with code `DOT_LIFECYCLE_E001`.
+ *  - Declaration order IS boot order. The app builder's type-level guard
+ *    makes out-of-order composition a compile error; the kernel re-validates
+ *    at runtime for erased/dynamic composition.
+ *  - `stop` and `dispose` run in reverse declaration order and continue
+ *    through individual pip failures, reporting an aggregate error.
  */
 /**
- * Type-narrowing helper for pip authors.
+ * Create an app-local (anonymous) service witness for a `needs` shape.
+ *
+ * `service.lazy<T>()` creates a lifting witness instead — the hook context
+ * delivers a `Lazy<T>` handle whether the provider is eager or lazy.
+ */
+export const service = Object.assign(() => ({}), { lazy: () => ({ lazy: true }) });
+/** Internal (kernel) check: is this witness a lazy-lifting one? */
+export function isLazyWitness(witness) {
+    return 'lazy' in witness && witness.lazy === true;
+}
+/**
+ * Create a token. Curried so `T` is explicit while `K` is inferred as a
+ * literal: `const Db = token<DbHandle>()('arki.db')`.
+ */
+export function token() {
+    return (key) => ({
+        key,
+        instance(name) {
+            // Safe by construction: the runtime string is exactly the template type.
+            return token()(`${key}#${name}`);
+        },
+    });
+}
+/**
+ * Publish a value under a token's wire key. Returns a record typed by the
+ * token's literal key, so `boot: () => provide(Db, handle)` infers
+ * `TProvides = { 'arki.db': DbHandle }`.
+ */
+export function provide(tok, value) {
+    // Safe by construction: the computed key is exactly `tok.key: K`.
+    return { [tok.key]: value };
+}
+/** Runtime brand for lazy service handles (kernel detects these for auto-dispose). */
+export const LazyTag = Symbol('dot.lazy');
+/**
+ * Create a lazy service handle. See {@link Lazy} for semantics.
+ *
+ * @param init - Opens the resource. Runs at most once concurrently; a
+ *   rejected attempt is not cached, so a later `get()` retries.
+ * @param options.dispose - Cleanup for the initialized value. Skipped when
+ *   the handle was never initialized.
+ */
+export function lazy(init, options = {}) {
+    let state = { status: 'idle' };
+    return {
+        [LazyTag]: true,
+        get() {
+            if (state.status === 'ready')
+                return Promise.resolve(state.value);
+            if (state.status === 'pending')
+                return state.promise;
+            if (state.status === 'disposed') {
+                return Promise.reject(new Error('Lazy service handle is disposed — the app has shut down.'));
+            }
+            const promise = Promise.resolve()
+                .then(init)
+                .then(value => {
+                state = { status: 'ready', value };
+                return value;
+            }, (error) => {
+                // Failed initialization is not cached — allow retry.
+                state = { status: 'idle' };
+                throw error;
+            });
+            state = { status: 'pending', promise };
+            return promise;
+        },
+        get initialized() {
+            return state.status === 'ready';
+        },
+        peek() {
+            return state.status === 'ready' ? state.value : undefined;
+        },
+        async dispose() {
+            if (state.status === 'pending') {
+                try {
+                    await state.promise;
+                }
+                catch {
+                    // Failed init: nothing to clean up.
+                }
+            }
+            if (state.status === 'ready') {
+                const { value } = state;
+                state = { status: 'disposed' };
+                await options.dispose?.(value);
+                return;
+            }
+            state = { status: 'disposed' };
+        },
+    };
+}
+/** Type guard: is this published value a lazy service handle? */
+export function isLazy(value) {
+    return typeof value === 'object' && value !== null && LazyTag in value;
+}
+/**
+ * Wrap an already-available value in a pre-initialized `Lazy<T>` handle.
+ * Used by the kernel to lift eager provides for `service.lazy` consumers;
+ * also handy for handing fakes to lazy-consuming pips in tests. The handle
+ * has no cleanup of its own — the underlying value's lifecycle belongs to
+ * whoever created it.
+ */
+export function lazyOf(value) {
+    let disposed = false;
+    return {
+        [LazyTag]: true,
+        get: () => disposed
+            ? Promise.reject(new Error('Lazy service handle is disposed — the app has shut down.'))
+            : Promise.resolve(value),
+        get initialized() {
+            return !disposed;
+        },
+        peek: () => (disposed ? undefined : value),
+        async dispose() {
+            disposed = true;
+        },
+    };
+}
+/**
+ * Author a DOT pip.
+ *
+ * - `TShape` is inferred from the `needs` object literal.
+ * - `TProvides` is inferred from `boot`'s return type — no generic argument.
+ * - `boot({ db, log, $app })` destructures typed services under the local
+ *   aliases declared in `needs`, plus the `$`-prefixed kernel keys.
+ * - `start` / `stop` / `dispose` additionally receive the pip's own
+ *   provides. Reverse-order teardown guarantees needs are still alive in
+ *   `dispose`.
  *
  * @example
- * export const myPip = defineDotPip<{ db: MyDb }>({
- *   name: 'my-pip',
- *   async boot() {
- *     const db = await openDb();
- *     return { services: { db } };
+ * ```ts
+ * export const billing = pip({
+ *   name: 'billing',
+ *   needs: { db: service<Db>(), log: service<Logger>() },
+ *   async boot({ db, log }) {
+ *     return { billing: new BillingService(db, log) };
  *   },
- *   async dispose({ services }) {
- *     await services.db.close();
+ *   async dispose({ billing }) {
+ *     await billing.flush();
  *   },
  * });
+ * ```
  */
-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 ?? [];
+export function pip(def) {
+    return {
+        name: def.name,
+        ...(def.version === undefined ? {} : { version: def.version }),
+        needs: def.needs ?? {},
+        renames: {},
+        hooks: {
+            ...(def.configure === undefined ? {} : { configure: def.configure }),
+            ...(def.boot === undefined ? {} : { boot: def.boot }),
+            ...(def.start === undefined ? {} : { start: def.start }),
+            ...(def.stop === undefined ? {} : { stop: def.stop }),
+            ...(def.dispose === undefined ? {} : { dispose: def.dispose }),
+        },
+    };
 }
-/** Internal helper: extract the `dependencies` field from a pip (always returns an array). */
-export function pipDependencies(pip) {
-    return pip.dependencies ?? [];
+/**
+ * Mount-time rename. `rename(dbPip, { db: 'reportsDb' }, 'reports-db')`
+ * publishes the same service under a different wire key, retyped
+ * accordingly — the way to mount a second instance of an adapter without
+ * a key collision. Renames compose: renaming an already-renamed key
+ * rewrites the earlier entry.
+ */
+export function rename(p, map, newName) {
+    const renames = { ...p.renames };
+    for (const [wireKey, next] of Object.entries(map)) {
+        if (typeof next !== 'string')
+            continue;
+        // If `wireKey` is itself the *result* of an earlier rename, rewrite that
+        // entry (compose); otherwise it is a local publish key.
+        const localKey = Object.entries(renames).find(([, w]) => w === wireKey)?.[0] ?? wireKey;
+        renames[localKey] = next;
+    }
+    // Phantom-only cast: runtime fields are unchanged except `renames`/`name`;
+    // only the [ProvidesSym] carrier retypes.
+    return { ...p, name: newName ?? p.name, renames };
 }
 /**
  * Stable error thrown by DOT pip adapters.
@@ -55,20 +213,6 @@ export function pipDependencies(pip) {
  *
  * @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`. */

package/dist/pip-contract.js.map

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

package/dist/pip.d.ts

@@ -1,24 +1,21 @@
 /**
  * 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.
+ * Exposes the pip contract and the entry points a pip author needs to
+ * author + test pips — `pip`, `service`, `token`, `provide`, `rename`,
+ * `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).
+ * Adapter packages (e.g. `@arki/env/dot`, `@arki/kv/dot`, `@arki/db/dot`)
+ * import from this subpath so their `*.d.ts` graphs stay tight.
  *
  * @example
  * ```ts
- * import { defineDotPip, type DotPip } from '@arki/dot/pip';
+ * import { pip, service, type Pip } 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 { isLazy, lazy, lazyOf, pip, provide, rename, service, token, DotPipError } from './pip-contract.js';
+export type { AnyPip, CtxOf, DotConfigureContext, EmptyShape, KernelCtx, Lazy, LazyService, NeedsShape, Pip, PipNeeds, PipProvides, RenamedProvides, Service, ServiceRecord, Token, WireNeeds, } 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';

package/dist/pip.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"pip.d.ts","sourceRoot":"","sources":["../src/pip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC5G,YAAY,EACV,MAAM,EACN,KAAK,EACL,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,IAAI,EACJ,WAAW,EACX,UAAU,EACV,GAAG,EACH,QAAQ,EACR,WAAW,EACX,eAAe,EACf,OAAO,EACP,aAAa,EACb,KAAK,EACL,SAAS,GACV,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

@@ -1,23 +1,20 @@
 /**
  * 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.
+ * Exposes the pip contract and the entry points a pip author needs to
+ * author + test pips — `pip`, `service`, `token`, `provide`, `rename`,
+ * `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).
+ * Adapter packages (e.g. `@arki/env/dot`, `@arki/kv/dot`, `@arki/db/dot`)
+ * import from this subpath so their `*.d.ts` graphs stay tight.
  *
  * @example
  * ```ts
- * import { defineDotPip, type DotPip } from '@arki/dot/pip';
+ * import { pip, service, type Pip } from '@arki/dot/pip';
  * ```
  */
-export { defineDotPip, DotPipError } from './pip-contract.js';
+export { isLazy, lazy, lazyOf, pip, provide, rename, service, token, 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';

package/dist/pip.js.map

@@ -1 +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"}
+{"version":3,"file":"pip.js","sourceRoot":"","sources":["../src/pip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAoB5G,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"}

package/dist/test-harness.d.ts

@@ -5,38 +5,41 @@
  * lifecycle behaviour, registration, and service publishing without dragging
  * in concrete framework dependencies.
  *
+ * NOTE: `testApp` takes an erased pip array, so the compile-time wiring
+ * guard does not apply here — the kernel's runtime validation (unsatisfied
+ * needs, collisions) still does. Use `defineApp(...).use(...)` chains in
+ * tests that should exercise the type-level guard.
+ *
  * @example
- *   import { testApp, defineDotPip } from '@arki/dot';
+ *   import { testApp, pip } from '@arki/dot';
  *
- *   const myPip = defineDotPip<{ counter: { value: number } }>({
+ *   const myPip = pip({
  *     name: 'counter',
- *     async boot() {
- *       return { services: { counter: { value: 0 } } };
- *     },
+ *     boot: () => ({ counter: { value: 0 } }),
  *   });
  *
  *   it('publishes a counter service', async () => {
- *     const app = await testApp([myPip]).boot();
+ *     const app = await bootTestApp<{ counter: { value: number } }>([myPip]);
  *     expect(app.services.counter.value).toBe(0);
  *     await app.dispose();
  *   });
  */
 import type { DotApp, DotAppBuilder } from './define-app.js';
-import type { AnyDotPip, DotPip } from './pip-contract.js';
+import type { AnyPip, EmptyShape, ServiceRecord } from './pip-contract.js';
 export type TestAppOptions = {
     /** App name used in the manifest. Defaults to `'test-app'`. */
     name?: string;
-    /** Runtime config bag passed to every boot hook. */
+    /** Runtime config bag exposed to hooks as `$config`. */
     config?: Readonly<Record<string, unknown>>;
 };
 /**
  * Build a DOT app builder pre-populated with the given pips, ready to
  * `.configure()`, `.boot()` or `.start()` from a test.
  */
-export declare function testApp<TServices extends Record<string, unknown> = Record<string, never>>(pips?: readonly DotPip<never>[] | readonly DotPip<Record<string, never>>[] | readonly AnyDotPip[], options?: TestAppOptions): DotAppBuilder<TServices>;
+export declare function testApp<TServices extends ServiceRecord = EmptyShape>(pips?: readonly AnyPip[], options?: TestAppOptions): DotAppBuilder<TServices>;
 /**
  * Convenience: build, boot, return the running app. Caller is responsible for
  * calling `app.dispose()` when finished.
  */
-export declare function bootTestApp<TServices extends Record<string, unknown> = Record<string, never>>(pips?: readonly DotPip<never>[] | readonly DotPip<Record<string, never>>[] | readonly AnyDotPip[], options?: TestAppOptions): Promise<DotApp<TServices>>;
+export declare function bootTestApp<TServices extends ServiceRecord = EmptyShape>(pips?: readonly AnyPip[], options?: TestAppOptions): Promise<DotApp<TServices>>;
 //# 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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3D,MAAM,MAAM,cAAc,GAAG;IAC3B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC5C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,OAAO,CAAC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAGvF,IAAI,GAAE,SAAS,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,SAAS,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,EAAE,GAAG,SAAS,SAAS,EAAO,EACrG,OAAO,GAAE,cAAmB,GAC3B,aAAa,CAAC,SAAS,CAAC,CAM1B;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EACjG,IAAI,GAAE,SAAS,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,SAAS,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,EAAE,GAAG,SAAS,SAAS,EAAO,EACrG,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,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"}

package/dist/test-harness.js

@@ -5,18 +5,21 @@
  * lifecycle behaviour, registration, and service publishing without dragging
  * in concrete framework dependencies.
  *
+ * NOTE: `testApp` takes an erased pip array, so the compile-time wiring
+ * guard does not apply here — the kernel's runtime validation (unsatisfied
+ * needs, collisions) still does. Use `defineApp(...).use(...)` chains in
+ * tests that should exercise the type-level guard.
+ *
  * @example
- *   import { testApp, defineDotPip } from '@arki/dot';
+ *   import { testApp, pip } from '@arki/dot';
  *
- *   const myPip = defineDotPip<{ counter: { value: number } }>({
+ *   const myPip = pip({
  *     name: 'counter',
- *     async boot() {
- *       return { services: { counter: { value: 0 } } };
- *     },
+ *     boot: () => ({ counter: { value: 0 } }),
  *   });
  *
  *   it('publishes a counter service', async () => {
- *     const app = await testApp([myPip]).boot();
+ *     const app = await bootTestApp<{ counter: { value: number } }>([myPip]);
  *     expect(app.services.counter.value).toBe(0);
  *     await app.dispose();
  *   });
@@ -26,13 +29,10 @@ import { defineApp } from './define-app.js';
  * Build a DOT app builder pre-populated with the given pips, ready to
  * `.configure()`, `.boot()` or `.start()` from a test.
  */
-export function testApp(
-// Accept any pip shape — tests routinely mix services types. Internally
-// we erase to `AnyDotPip` for the kernel.
-pips = [], options = {}) {
+export function testApp(pips = [], options = {}) {
     let builder = defineApp(options.name ?? 'test-app', { config: options.config });
-    for (const pip of pips) {
-        builder = builder.use(pip);
+    for (const p of pips) {
+        builder = builder.use(p);
     }
     return builder;
 }

package/dist/test-harness.js.map

@@ -1 +1 @@
-{"version":3,"file":"test-harness.js","sourceRoot":"","sources":["../src/test-harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAS5C;;;GAGG;AACH,MAAM,UAAU,OAAO;AACrB,wEAAwE;AACxE,0CAA0C;AAC1C,OAAmG,EAAE,EACrG,UAA0B,EAAE;IAE5B,IAAI,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,IAAI,UAAU,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAChF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,GAAsC,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,OAAmC,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAmG,EAAE,EACrG,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":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arki/dot",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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/templates/app-minimal/AGENTS.md.tmpl

@@ -36,8 +36,8 @@ command exits zero.
   app reads belong here.
 - Don't reach into `@arki/dot` internals (anything under
   `@arki/dot/kernel`, `@arki/dot/legacy`, or `dist/` subpaths). Use the
-  public `defineApp` / `defineDotPip` API from `@arki/dot` and the
-  `defineDotPip` symbol from `@arki/dot/pip`.
+  public `defineApp` / `pip` API from `@arki/dot` and the
+  `pip` / `service` / `rename` symbols from `@arki/dot/pip`.
 
 ## DOT artifact locations