first commit

docs/api-stack/api/api-plugin-database/src/services/registry-augmentation.md

@@ -0,0 +1,55 @@
+# `services/registry-augmentation`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Augments the `ServiceRegistry` interface from `@suaveplan/api-plugin` to register the `db` slot typed as `@suaveplan/db`'s `DatabaseAdapter`. Module augmentation is the canonical suaveplan pattern for cross-plugin typed services: it keeps `ctx.getService("db")` strongly typed without forcing every consumer to import a plugin-specific type and without leaking the implementation through the augmentation. Downstream plugins (e.g. `api-plugin-user`, future `api-plugin-tenant`) consume the slot purely by importing this module's barrel side effect.
+
+The file is intentionally minimal: a single `declare module` block plus an empty `export {}` so module resolution treats it as a module rather than a script. Importing it from the package root barrel is a free type-only side effect at runtime.
+
+## Features
+
+- Adds `db: DatabaseAdapter` to the shared `ServiceRegistry`.
+- Zero runtime cost — pure type augmentation.
+- Re-imported via the package root barrel so consumers get the slot for free with `import "@suaveplan/api-plugin-database"`.
+
+## Usage: Basic
+
+```ts
+import "@suaveplan/api-plugin-database";
+
+declare module "@suaveplan/api-plugin/service-registry" {
+    // db is already registered by the import above.
+}
+
+const db = ctx.getService("db"); // typed as DatabaseAdapter | undefined
+```
+
+## Usage: Advanced
+
+```ts
+import "@suaveplan/api-plugin-database/services/registry-augmentation";
+import type { DatabaseAdapter } from "@suaveplan/db";
+
+async function withTx<T>(
+    ctx: PluginContext,
+    fn: (db: DatabaseAdapter) => Promise<T>
+): Promise<T> {
+    const db = ctx.getService("db");
+    if (db === undefined) throw new Error("db service not registered");
+    return db.transaction(fn);
+}
+```
+
+## API Reference
+
+No runtime exports. The file augments `ServiceRegistry["db"]` at the type level.
+
+## Implementation Notes
+
+- The augmentation imports `DatabaseAdapter` as a type-only reference. The runtime cost of importing the module is zero.
+- The plugin descriptor (in `plugin/plugin.ts`) imports this module as a side effect so consumers that pull the descriptor in get the augmentation transitively.
+- Augmenting through a single canonical file (rather than each plugin) prevents duplicate-slot drift — any future package wanting to override or extend `db` would have to do so explicitly.