@arki/dot 0.1.2 → 0.1.4

package/README.md

@@ -3,26 +3,31 @@
 > TypeScript-first application composition framework for the ARKI package family.
 
 `@arki/dot` is the kernel that wires **pips**, lifecycle hooks, dependency
-graphs, and diagnostics into a deterministic application boot. It gives library
-authors a stable contract for declaring how their package participates in an
-app, and gives app developers a single place to wire those packages together.
+injection, and diagnostics into a deterministic application boot. It gives
+library authors a stable contract for declaring how their package
+participates in an app, and gives app developers a single place to wire
+those packages together — with the type checker verifying the wiring before
+anything runs.
 
 ## What is a pip?
 
 A **pip** is the unit a DOT app is built from — one self-describing,
 lifecycle-aware piece of an application. Each pip:
 
-- declares a **name**, **version**, and the kinds of **services it provides**;
+- declares a **name**, **version**, and the services it **needs** as a shape
+  of type witnesses;
+- **provides** services by returning them from its `boot` hook — provides
+  are *inferred from the return type*, never declared separately;
 - runs a **5-hook lifecycle** — `configure` → `boot` → `start` → `stop` → `dispose`;
-- **publishes typed services** to a shared, type-safe registry that later pips
-  can read from;
-- **composes deterministically** — pips boot in declaration order and dispose
-  in reverse.
+- **publishes typed services** to a shared, type-safe registry that later
+  pips can read from;
+- **composes deterministically** — pips boot in declaration order and
+  dispose in reverse.
 
 The name comes from the small dots on dice, dominoes, and music notation:
-each pip is one small mark, and the *combination* of pips is what gives the app
-its value. Two pips on a die make a value of two; six pips make six. The pips
-**are** the app — not optional add-ons to a hidden core.
+each pip is one small mark, and the *combination* of pips is what gives the
+app its value. Two pips on a die make a value of two; six pips make six. The
+pips **are** the app — not optional add-ons to a hidden core.
 
 ```ts
 import { defineApp } from '@arki/dot';
@@ -61,6 +66,19 @@ bun add @arki/dot
 ```ts
 import { defineApp, pip, service } from '@arki/dot';
 
+type Db = { query(sql: string): Promise<unknown[]> };
+
+const dbPip = pip({
+  name: 'database',
+  async boot() {
+    const db = await openDb(process.env.DATABASE_URL);
+    return { db };                    // ← this IS the provides declaration
+  },
+  async dispose({ db }) {
+    await db.close();
+  },
+});
+
 const billingPip = pip({
   name: 'billing',
   version: '1.0.0',
@@ -94,6 +112,319 @@ await app.stop();
 await app.dispose();
 ```
 
+There is no registry to configure, no decorators, no reflection. The `needs`
+shape is the injection contract; the `boot` return type is the provision
+contract; the builder's type-level guard connects the two.
+
+## Dependency injection
+
+### Needs are witnesses, provides are inferred
+
+`service<T>()` creates a phantom **type witness** — a runtime no-op that
+carries `T` at the type level. The property name you give it is your local
+alias *and* (for anonymous witnesses) the wire key:
+
+```ts
+const search = pip({
+  name: 'search',
+  needs: {
+    db: service<Db>(),                 // wire key 'db', local alias 'db'
+    log: service<Logger>(),            // wire key 'log'
+  },
+  async boot({ db, log, $app }) {      // $app/$pip/$config: kernel context
+    log.info(`indexing for ${$app}`);
+    return { search: await buildIndex(db) };
+  },
+});
+```
+
+`start`, `stop`, and `dispose` additionally receive the pip's **own
+provides** — and because teardown runs in reverse declaration order, a pip's
+needs are still alive in its `dispose`:
+
+```ts
+async dispose({ search, db }) {        // own provide + still-live need
+  await search.flush(db);
+},
+```
+
+### Wrong wiring does not compile
+
+Declaration order IS boot order. The `.use()` guard makes unsatisfied needs,
+type mismatches, and key collisions **compile errors at the call site**:
+
+```ts
+defineApp('shop')
+  .use(billing)      // ❌ "Expected 2 arguments, but got 1."
+  .use(database);    //    billing's `db` need has no earlier provider
+
+defineApp('shop')
+  .use(database)
+  .use(database2);   // ❌ collision: two providers of wire key 'db'
+```
+
+Reordering the first example — or `rename`-ing one provider in the second —
+makes both compile. The kernel re-validates at runtime with coded errors
+(`E012` unsatisfied need, `E013` collision, `E014` reserved key) for
+erased/dynamic composition, with full rollback of already-booted pips.
+
+There is no dependency graph to debug and **cycles are unrepresentable**:
+services flow strictly forward through the `.use()` chain. If two pips need
+each other's services, that's a design smell the type system surfaces
+immediately — merge them, or extract the shared piece into a third pip both
+consume.
+
+### Tokens — cross-package service contracts
+
+An anonymous `service<T>()` couples consumer and provider by property name.
+When a contract spans packages, a **token** owns the wire key and the local
+alias becomes free choice:
+
+```ts
+// The package that owns the contract exports the token:
+export const Db = token<NodePgDatabase<Schema>>()('arki.db');
+
+// A provider publishes under the token's key:
+const database = pip({
+  name: 'database',
+  async boot() {
+    return provide(Db, await connect());   // → { 'arki.db': NodePgDatabase }
+  },
+});
+
+// Any consumer, any package, any local alias:
+const reports = pip({
+  name: 'reports',
+  needs: { warehouse: Db },                // wire key 'arki.db', alias yours
+  async boot({ warehouse }) { /* ... */ },
+});
+```
+
+### Multi-instance with `rename`
+
+Mounting an adapter twice would collide on its wire keys — loudly, at
+compile time. `rename` is the multi-instance primitive, and
+`Token.instance()` derives the matching contract:
+
+```ts
+const ReportsDb = Db.instance('reports');  // token for key 'arki.db#reports'
+
+const app = await defineApp('shop')
+  .use(database({ url: PRIMARY_URL }))
+  .use(rename(
+    database({ url: REPLICA_URL }),
+    { 'arki.db': ReportsDb.key },          // republish under the derived key
+    'reports-db',                          // distinct pip name
+  ))
+  .use(pip({
+    name: 'analytics',
+    needs: { primary: Db, replica: ReportsDb },
+    async boot({ primary, replica }) { /* two live instances, both typed */ },
+  }))
+  .boot();
+```
+
+Renames compose left-to-right and are applied at publish time — collision
+checks see the final keys.
+
+### Lazy services
+
+`lazy(init, { dispose })` publishes a **handle** instead of an open
+resource. Initialization runs on first `get()` (memoized, single-flight;
+failed attempts retry). Never-touched handles never initialize — and the
+kernel auto-disposes initialized ones during teardown, *after* the
+publishing pip's own `dispose` hook, even if that pip has none:
+
+```ts
+const search = pip({
+  name: 'search',
+  async boot() {
+    return {
+      search: lazy(() => connectToElastic(), {
+        dispose: client => client.close(),
+      }),
+    };
+  },
+});
+```
+
+Consumers that shouldn't care whether a provider is eager or lazy declare a
+**lifting witness** — `service.lazy<T>()` always delivers a `Lazy<T>`
+handle, wrapping eager provides and passing lazy ones through by identity:
+
+```ts
+const suggestions = pip({
+  name: 'suggestions',
+  needs: { search: service.lazy<SearchClient>() },
+  async start({ search }) {
+    const client = await search.get();     // first access initializes
+    /* ... */
+  },
+});
+```
+
+Swapping the search provider between eager and lazy is invisible to every
+consumer — the wiring guard accepts both shapes against the same witness.
+
+### Kernel context — the reserved `$` namespace
+
+Every service-carrying hook context includes `$app` (app name), `$pip` (pip
+name), and `$config` (the `defineApp(name, { config })` bag). The `$` prefix
+is enforced as reserved: `pip()` rejects `$`-prefixed needs aliases and
+publish keys at compile time, and the kernel re-validates at runtime
+(`DOT_LIFECYCLE_E014`) — kernel keys can never be shadowed.
+
+## A complex setup
+
+A distilled commerce platform showing everything above working together.
+(The package's stress-test suite boots a 28-pip version of this and asserts
+exact boot/teardown ordering.)
+
+```ts
+import { defineApp, lazy, pip, provide, rename, service, token } from '@arki/dot';
+
+// ── contracts.ts — tokens owned by their respective packages ─────────
+export const Env = token<AppEnv>()('shop.env');
+export const Db = token<DbHandle>()('shop.db');
+export const ReportsDb = Db.instance('reports');
+export const Cache = token<CacheHandle>()('shop.cache');
+export const Bus = token<MessageBus>()('shop.bus');
+
+// ── infrastructure pips ───────────────────────────────────────────────
+const env = pip({
+  name: 'env',
+  boot: ({ $config }) => provide(Env, parseEnv($config)),
+});
+
+const telemetry = pip({
+  name: 'telemetry',
+  needs: { env: Env },
+  boot: ({ env }) => ({ metrics: makeMetrics(env.OTEL_ENDPOINT) }),
+  dispose: ({ metrics }) => metrics.flush(),
+});
+
+const database = (url: string) =>
+  pip({
+    name: 'database',
+    needs: { metrics: service<Metrics>() },
+    async boot({ metrics }) {
+      return provide(Db, await connectPg(url, { metrics }));
+    },
+    async dispose(ctx) {
+      await ctx[Db.key].end();       // own provide, published under the token key
+    },
+  });
+
+const cache = pip({
+  name: 'cache',
+  needs: { env: Env },
+  boot: ({ env }) => provide(Cache, connectRedis(env.REDIS_URL)),
+  dispose: async ctx => ctx[Cache.key].quit(),
+});
+
+const searchCluster = pip({
+  name: 'search-cluster',
+  needs: { env: Env },
+  boot: ({ env }) => ({
+    // Expensive external cluster — only opens if something get()s it.
+    search: lazy(() => connectElastic(env.ELASTIC_URL), {
+      dispose: client => client.close(),
+    }),
+  }),
+});
+
+const bus = pip({
+  name: 'bus',
+  boot: () => provide(Bus, makeInMemoryBus()),
+});
+
+// ── domain pips ───────────────────────────────────────────────────────
+const catalog = pip({
+  name: 'catalog',
+  needs: {
+    db: Db,
+    cache: Cache,
+    search: service.lazy<SearchClient>(),   // eager or lazy provider — same code
+  },
+  boot: ({ db, cache, search }) => ({
+    catalog: makeCatalog({ db, cache, search }),
+  }),
+});
+
+const checkout = pip({
+  name: 'checkout',
+  needs: { db: Db, bus: Bus, catalog: service<Catalog>() },
+  boot: ({ db, bus, catalog }) => ({
+    checkout: makeCheckout({ db, bus, catalog }),
+  }),
+});
+
+const reporting = pip({
+  name: 'reporting',
+  needs: { replica: ReportsDb, catalog: service<Catalog>() },
+  boot: ({ replica, catalog }) => ({ reporting: makeReporting(replica, catalog) }),
+});
+
+// ── process pips — real work happens in start/stop ───────────────────
+const outboxWorker = pip({
+  name: 'outbox-worker',
+  needs: { db: Db, bus: Bus },
+  boot: ({ db, bus }) => ({ outbox: makeOutbox(db, bus) }),
+  start: ({ outbox }) => outbox.startPolling(),
+  stop: ({ outbox }) => outbox.drain(),      // stop processing, keep resources
+});
+
+const http = pip({
+  name: 'http',
+  needs: {
+    env: Env,
+    catalog: service<Catalog>(),
+    checkout: service<Checkout>(),
+    reporting: service<Reporting>(),
+  },
+  async boot({ env, catalog, checkout, reporting }) {
+    return { server: buildServer({ port: env.PORT, catalog, checkout, reporting }) };
+  },
+  start: ({ server }) => server.listen(),
+  stop: ({ server }) => server.close(),
+});
+
+// ── composition — the order IS the architecture ──────────────────────
+const app = await defineApp('shop', { config: process.env })
+  .use(env)
+  .use(telemetry)
+  .use(database(PRIMARY_URL))
+  .use(rename(database(REPLICA_URL), { 'shop.db': ReportsDb.key }, 'reports-db'))
+  .use(cache)
+  .use(searchCluster)
+  .use(bus)
+  .use(catalog)
+  .use(checkout)
+  .use(reporting)
+  .use(outboxWorker)
+  .use(http)
+  .start();
+
+// SIGTERM → dispose() cascades stop() first, tears down in exact reverse:
+// http, outbox (drained), reporting, checkout, catalog, bus,
+// search cluster (only if it ever initialized), cache, reports-db,
+// primary db, telemetry, env.
+process.on('SIGTERM', () => void app.dispose());
+```
+
+What the type checker is holding for you in that chain:
+
+- move `.use(catalog)` above `.use(cache)` → compile error at that line;
+- delete `.use(bus)` → compile errors at `checkout` and `outboxWorker`;
+- mount the second `database(...)` without `rename` → collision error;
+- change `makeCatalog` to return something that isn't a `Catalog` →
+  every consumer's `.use()` flags the mismatch.
+
+Concurrent lifecycle calls are safe: transitions are serialized on one
+queue, same-phase calls coalesce onto one in-flight promise, and a
+`dispose()` racing a slow `start()` always runs after it — the app ends
+`disposed`, never resurrected.
+
 ## Pip authoring
 
 `pip(config)` accepts a `needs` shape plus five lifecycle hooks. Hook
@@ -106,7 +437,7 @@ contexts carry the needed services (typed, under your local aliases) and
 | `boot`      | Open connections; the returned record is what the pip provides.     |
 | `start`     | Begin processing (workers, subscribers, schedulers).                |
 | `stop`      | Stop processing in reverse declaration order.                       |
-| `dispose`   | Free resources after `stop`.                                        |
+| `dispose`   | Free resources after `stop`; lazy handles auto-clean afterwards.    |
 
 Wiring is compile-time checked: `.use(pip)` fails to typecheck when the
 pip's needs aren't satisfied by earlier `.use()` calls, or when its
@@ -122,7 +453,7 @@ order is boot order — same input, same order, every time.
 `defineApp(name)` returns a builder. Calling `.use(pip)` accumulates
 pips. The lifecycle then flows:
 
-```
+```text
 defined ──configure()──▶ configured ──boot()──▶ booted ──start()──▶ started
                                                                        │
                        disposed ◀──dispose()── stopped ◀──stop()───────┘
@@ -131,7 +462,19 @@ defined ──configure()──▶ configured ──boot()──▶ booted ─
 `boot()` runs `configure()` implicitly if you skipped it. `start()` runs
 `boot()` implicitly. `stop()` and `dispose()` always run in reverse
 declaration order, even when an earlier hook failed — failure isolation is
-part of the contract.
+part of the contract. A boot failure rolls back every already-booted pip
+before throwing.
+
+Runtime failures carry stable codes (`DotLifecycleError.code`):
+
+| Code                 | Meaning                                              |
+| -------------------- | ---------------------------------------------------- |
+| `DOT_LIFECYCLE_E011` | Pip registered twice.                                |
+| `DOT_LIFECYCLE_E012` | A need has no provider among earlier pips.           |
+| `DOT_LIFECYCLE_E013` | A published wire key collides with an earlier one.   |
+| `DOT_LIFECYCLE_E014` | A service key uses the reserved `$` (kernel) prefix. |
+
+(Full table including hook-failure codes: [docs/lifecycle.md](./docs/lifecycle.md).)
 
 ## CLI
 
@@ -156,7 +499,9 @@ dot explain --app ./my-app.ts --json | jq '.data.pips'
 ```
 
 The CLI emits the same envelope shape as the in-process diagnostics snapshot
-(`app.diagnostics`), so the same downstream tools can consume either.
+(`app.diagnostics`), so the same downstream tools can consume either. The
+manifest's dependency edges are **observed, not declared** — the kernel
+records which pip's published service satisfied which need during boot.
 
 ### `dot new <app-name>`
 
@@ -177,7 +522,14 @@ ship with the published tarball.
 `@arki/dot` is intentionally small: it defines the contracts (pip shape,
 lifecycle hooks, manifest schema, diagnostics envelope) and runs them. Adapters
 that bridge databases, queues, auth providers, and HTTP routers live in their
-own packages and consume `@arki/dot` as a peer dependency.
+own packages and consume `@arki/dot` as a peer dependency:
+
+```ts
+import { env } from '@arki/env/dot';
+import { db } from '@arki/db/dot';
+import { kv } from '@arki/kv/dot';
+import { eventSourcing } from '@arki/event-sourcing/dot';
+```
 
 This keeps the kernel free of optional dependencies and lets each adapter
 ship at its own cadence.
@@ -189,8 +541,8 @@ The full docs live in [`docs/`](./docs):
 - [Principles](./docs/principles.md) — **read first.** The five rules every
   API, error, and PR is measured against. Slightly playful, very precise.
 - [Quickstart](./docs/quickstart.md) — boot your first app in five minutes.
-- [Pip authoring](./docs/pip-authoring.md) — write your own `DotPip`.
-- [Lifecycle](./docs/lifecycle.md) — the 5-hook contract.
+- [Pip authoring](./docs/pip-authoring.md) — write your own pip.
+- [Lifecycle](./docs/lifecycle.md) — the 5-hook contract, idempotency, error codes.
 - [Diagnostics](./docs/diagnostics.md) — `app.manifest`, `app.diagnostics`,
   `dot explain`, `dot doctor`.
 - [Adapter authoring](./docs/adapter-authoring.md) — expose your package as

package/dist/kernel/app-instance.d.ts

@@ -49,7 +49,7 @@ export declare class DotAppImpl {
     runConfigure(): void;
     /** Public boot() — idempotent + concurrent-safe. */
     boot(): Promise<void>;
-    /** Public start(). Boots first if needed. Idempotent. */
+    /** Public start(). Boots first if needed. Idempotent + concurrent-safe. */
     start(): Promise<void>;
     /** Public stop(). Idempotent + concurrent-safe. */
     stop(): Promise<void>;

package/dist/kernel/app-instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-instance.d.ts","sourceRoot":"","sources":["../../src/kernel/app-instance.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAEV,sBAAsB,EAKvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAqB,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACxF,OAAO,KAAK,EAA4C,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACnG,OAAO,KAAK,EAEV,cAAc,EAKf,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,MAAM,EAA4C,MAAM,oBAAoB,CAAC;AAkE3F,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,sDAAsD;IACtD,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3C;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAC7C,CAAC;AAEF;;;GAGG;AACH,qBAAa,UAAU;;gBAwDT,MAAM,EAAE,oBAAoB;IAyCxC;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAuIrD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,KAAK,IAAI,iBAAiB,CAE7B;IAED,IAAI,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEtC;IAED,IAAI,QAAQ,IAAI,cAAc,CAE7B;IAED,IAAI,WAAW,IAAI,sBAAsB,CAExC;IAED;;;;OAIG;IACH,YAAY,IAAI,IAAI;IAgKpB,oDAAoD;IAC9C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA6P3B,yDAAyD;IACnD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmH5B,mDAAmD;IAC7C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkH3B,sDAAsD;IAChD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAkS/B;AA0BD,kFAAkF;AAElF,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"app-instance.d.ts","sourceRoot":"","sources":["../../src/kernel/app-instance.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAEV,sBAAsB,EAKvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAqB,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACxF,OAAO,KAAK,EAA4C,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACnG,OAAO,KAAK,EAEV,cAAc,EAKf,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,MAAM,EAA4C,MAAM,oBAAoB,CAAC;AAkE3F,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,sDAAsD;IACtD,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3C;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAC7C,CAAC;AAEF;;;GAGG;AACH,qBAAa,UAAU;;gBAmET,MAAM,EAAE,oBAAoB;IAoExC;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAuIrD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,KAAK,IAAI,iBAAiB,CAE7B;IAED,IAAI,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEtC;IAED,IAAI,QAAQ,IAAI,cAAc,CAE7B;IAED,IAAI,WAAW,IAAI,sBAAsB,CAExC;IAED;;;;OAIG;IACH,YAAY,IAAI,IAAI;IA8KpB,oDAAoD;IAC9C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiR3B,2EAA2E;IACrE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA+H5B,mDAAmD;IAC7C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoH3B,sDAAsD;IAChD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CA2T/B;AA0BD,kFAAkF;AAElF,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC"}