Initial Commit

packages/api-stack/api/api-plugin-audit/src/services/registry-augmentation.md

@@ -0,0 +1,52 @@
+# services/registry-augmentation
+
+## Purpose
+
+Declares the `auditService` slot on `@suaveplan/api-plugin/service-registry`'s `ServiceRegistry` interface via TypeScript module augmentation. Importing this module for its side effects (which the package root barrel does automatically) is sufficient — every consumer of `@suaveplan/api-plugin-audit` gets typed `ctx.getService("auditService")` access with the return type narrowed to `AuditService | undefined`, no casts.
+
+The file also cumulatively re-declares the host-side `app` slot so the audit plugin's `onInit(ctx)` resolves `ctx.getService("app")` to `Hono` even when the consumer has not explicitly imported `@suaveplan/api`'s registry-augmentation. TypeScript merges duplicate declarations across modules, so the cumulative augmentation is safe.
+
+## Features
+
+- TypeScript module augmentation — zero runtime cost.
+- Cumulative — does not collide with `@suaveplan/api-plugin-auth`'s or `@suaveplan/api`'s own augmentations.
+- Side-effect imported by the package barrel so consumers do not need an explicit subpath import.
+
+## Usage: Basic
+
+```ts
+// In your app entry:
+import "@suaveplan/api-plugin-audit"; // side-effect: registers ServiceRegistry slot
+
+// In a sibling plugin's onInit:
+const audit = ctx.getService("auditService"); // typed as AuditService | undefined
+await audit?.log({
+    type: "user.created",
+    severity: "info",
+    actor: { userId: "u1" },
+});
+```
+
+## Usage: Advanced
+
+```ts
+// In a custom test harness that constructs PluginContext directly:
+import "@suaveplan/api-plugin-audit/services/audit-service"; // also surfaces the augmentation
+import { createPluginContext } from "@suaveplan/api-plugin";
+
+const ctx = createPluginContext({
+    /* ... */
+});
+const audit = ctx.getService("auditService"); // AuditService | undefined
+```
+
+## API Reference
+
+This file has no runtime exports; it contributes a single TypeScript `declare module "@suaveplan/api-plugin/service-registry"` block adding:
+
+- `auditService: AuditService`
+- `app: Hono`
+
+## Implementation Notes
+
+The augmentation must live in a module that is reachable from the consumer's TypeScript program (either via a direct import or via a transitive dependency that pulls it in). Importing the package barrel of `@suaveplan/api-plugin-audit` covers the common case. If the augmentation is missing at compile time, `ctx.getService("auditService")` types as `never` per the `ServiceRegistry` defaults and fails the build with `Argument of type '"auditService"' is not assignable…`. That failure is the intended UX — it tells the operator the plugin barrel was not loaded.