first commit

docs/api-stack/api/api-plugin-sse/src/registry/service-registry.md

@@ -0,0 +1,60 @@
+# service-registry
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+TypeScript module augmentation declaring the `sseService` slot on the `@suaveplan/api-plugin/service-registry` `ServiceRegistry` interface. Importing this module for its side effects makes `ctx.getService("sseService")` return `SseService | undefined` with no cast at the call site — the package root barrel imports it automatically so every consumer of `@suaveplan/api-plugin-sse` gets the typed slot.
+
+## Features
+
+- Side-effect-only augmentation — exports an empty `type` so the file participates in the module graph without contributing runtime code.
+- Mirrors the host's `app` slot declaration so the plugin can run in isolation against a stand-alone Hono instance (TypeScript merges duplicate declarations safely).
+- Co-located with the plugin's types so a single import path establishes the augmentation.
+- Excluded from coverage / docs gates because it carries no executable code.
+
+## Usage: Basic
+
+```ts
+// Importing the package barrel surfaces the augmentation automatically.
+import "@suaveplan/api-plugin-sse";
+
+// Now every ctx.getService("sseService") call is typed.
+function handle(ctx: PluginContext) {
+    const sse = ctx.getService("sseService");
+    sse?.broadcast("c", { data: 1 });
+}
+```
+
+## Usage: Advanced
+
+```ts
+// Explicit augmentation import — useful when consuming a single subpath
+// without pulling the whole barrel.
+import "@suaveplan/api-plugin-sse/registry/service-registry";
+import type { SseService } from "@suaveplan/api-plugin-sse/services/service";
+
+declare const ctx: PluginContext;
+const sse: SseService | undefined = ctx.getService("sseService");
+```
+
+## API Reference
+
+- No exported values. The module augments:
+
+  ```ts
+  declare module "@suaveplan/api-plugin/service-registry" {
+      interface ServiceRegistry {
+          sseService: SseService;
+          app: Hono;
+      }
+  }
+  ```
+
+## Implementation Notes
+
+- This file does NOT export `type` aliases or values — it exists solely for module-augmentation side effects. The `export type {}` at the end keeps TypeScript happy with isolated modules.
+- The `app` re-declaration is intentional and harmless. `@suaveplan/api` declares the same slot; TypeScript merges duplicate interface declarations and the two contribute identical types.
+- Excluded from coverage in `vitest.config.ts` (`src/registry/service-registry.ts`) because there is no runtime to cover; type-level conformance is asserted in the `api-plugin-sse.spec-conformance.test.ts` suite via `expectTypeOf`.