first commit

docs/api-stack/api/api-sse/src/capability-id/capability-id.md

@@ -0,0 +1,47 @@
+# `SseCapabilityId` + `SSE_CAPABILITY_ID`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The `"sse"` `CapabilityId` slot connects this package to the host's `CapabilityMap`. Plugin authors declare `requires: ["sse"]` in their manifest; the host narrows their `PluginContext` so `ctx.capabilities.sse` is typed as the concrete SSE broker / registry pair.
+
+`@suaveplan/api-types/capabilities` already lists `"sse"` in its closed `CapabilityId` union — this module pins that contract with a type-test so an accidental removal upstream surfaces at this package's gates rather than landing silently and breaking every downstream consumer.
+
+## Features
+
+- `SseCapabilityId` is `Extract<CapabilityId, "sse">` — narrows to the literal at type-test time so a renamed/removed entry fails compile here.
+- `SSE_CAPABILITY_ID` is a runtime `const` (`"sse"` `as const satisfies CapabilityId`) — usable in `requires: [SSE_CAPABILITY_ID] as const` declarations.
+- No module augmentation needed; api-types owns the canonical union.
+
+## Usage: Basic
+
+```ts
+import { SSE_CAPABILITY_ID } from "@suaveplan/api-sse/capability-id/capability-id";
+
+const requires = [SSE_CAPABILITY_ID] as const;
+```
+
+## Usage: Advanced
+
+```ts
+import type { SseCapabilityId } from "@suaveplan/api-sse/capability-id/capability-id";
+import type { CapabilityMap } from "@suaveplan/api-types/capabilities";
+
+type SseSlot = CapabilityMap[SseCapabilityId];
+
+function consume(slot: SseSlot) {
+    // slot is the concrete shape the host vends behind the SSE capability.
+}
+```
+
+## API Reference
+
+- `SSE_CAPABILITY_ID: "sse"` — runtime constant.
+- `type SseCapabilityId = Extract<CapabilityId, "sse">` — type-level proof that `"sse"` is a member.
+
+## Implementation Notes
+
+The spec for this package describes the contribution as "augments the `CapabilityId` union to include `"sse"`". In practice api-types already declares `"sse"` directly, so the augmentation is degenerate: this module's job is to PIN the contract via `expectTypeOf<"sse">().toMatchTypeOf<CapabilityId>()` so the slot cannot be removed without breaking the api-sse build. This guards a real failure mode — a previous wave's WS capability was silently removed from api-types and the breakage surfaced only at app-tier integration.