first commit

docs/api-stack/api/api-router-hono/README.md

@@ -0,0 +1,62 @@
+# @suaveplan/api-router-hono — concrete Hono router adapter for the @suaveplan/api plugin system. Implements the abstract Router contract from @suaveplan/api-router on top of a Hono instance, including the HonoBlueGreenSlot atomic-flip primitive and bidirectional Middleware <-> Hono MiddlewareHandler adapters. Passes runRouterConformance.
+
+Stage-4 concrete Hono router adapter for `@suaveplan/api`. Implements the abstract `Router` contract from `@suaveplan/api-router` on top of a Hono `Hono` instance and provides the matching `BlueGreenSlot` implementation for hot-reload.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [adapter](./src/adapter/adapter.md) — `HonoRouter` is The concrete `Router` adapter for the API plugin system. It implements every public method…
+  - [adapter](./src/adapter/adapter.md) — `HonoRouter` is The concrete `Router` adapter for the API plugin system. It implements every public method…
+- [blue-green-slot](./src/blue-green-slot/blue-green-slot.md) — `HonoBlueGreenSlot` is the per-plugin atomic flip primitive backing hot-reload for a Hono-backed `Router`. It holds at…
+  - [blue-green-slot](./src/blue-green-slot/blue-green-slot.md) — `HonoBlueGreenSlot` is the per-plugin atomic flip primitive backing hot-reload for a Hono-backed `Router`. It holds at…
+- [error-codes](./src/error-codes/error-codes.md) — This module defines the canonical, frozen error-code namespace `ROUTER_HONO.*` shared by every production path inside `…
+  - [error-codes](./src/error-codes/error-codes.md) — This module defines the canonical, frozen error-code namespace `ROUTER_HONO.*` shared by every production path inside `…
+- [middleware-adapter](./src/middleware-adapter/middleware-adapter.md) — This module bidirectionally bridges the onion-model `Middleware` type from `@suaveplan/api-router` and Hono's n…
+  - [middleware-adapter](./src/middleware-adapter/middleware-adapter.md) — This module bidirectionally bridges the onion-model `Middleware` type from `@suaveplan/api-router` and Hono's n…
+- [pipeline](./src/pipeline/pipeline.md) — `@suaveplan/api-host`'s request pipeline drives its routing through a `PipelineRouter`-shaped seam — `match(method, url…
+  - [pipeline](./src/pipeline/pipeline.md) — `@suaveplan/api-host`'s request pipeline drives its routing through a `PipelineRouter`-shaped seam — `match(method, url…
+<!-- end:auto-docs -->
+
+## What it ships
+
+- `HonoRouter` / `createHonoRouter()` — concrete `Router` adapter that subclasses the abstract base, mirrors every verb registration onto a private Hono app, and exposes `getHonoApp()` for ops integrations.
+- `HonoBlueGreenSlot` — `BlueGreenSlot` impl with atomic flip, in-flight counter, AbortSignal-aware `dispose(timeoutMs)`.
+- `toHonoMiddleware` / `fromHonoMiddleware` — bidirectional bridge between the onion-model `Middleware` and Hono's `MiddlewareHandler`.
+- `ROUTER_HONO_CODES` / `RouterHonoError` — stable error-code registry (`ROUTER_HONO.HONO_INTERNAL_ERROR`, `ROUTER_HONO.INVALID_HONO_PEER`).
+
+## Conformance
+
+The package passes `runRouterConformance` from `@suaveplan/api-router/testing` — see `tests/conformance.test.ts`. Adding new behaviours requires re-running the harness against the adapter.
+
+## Modules
+
+- [`src/adapter/adapter.md`](./src/adapter/adapter.md) — adapter façade + factory.
+- [`src/blue-green-slot/blue-green-slot.md`](./src/blue-green-slot/blue-green-slot.md) — hot-reload primitive.
+- [`src/middleware-adapter/middleware-adapter.md`](./src/middleware-adapter/middleware-adapter.md) — middleware bridge.
+- [`src/error-codes/error-codes.md`](./src/error-codes/error-codes.md) — error registry.
+
+## Usage
+
+```ts
+import { createHonoRouter, HonoBlueGreenSlot } from "@suaveplan/api-router-hono";
+
+const router = createHonoRouter({ plugin: "billing" });
+router.get("/invoices/:id", () => null);
+
+const slot = new HonoBlueGreenSlot("billing", () => "v1");
+slot.setShadow(() => "v2");
+const draining = slot.flip();
+await slot.dispose(draining.slotId, { timeoutMs: 1_000 });
+```
+
+## Dependencies
+
+- `@suaveplan/api-router` — abstract contract + conformance harness.
+- `@suaveplan/api-types` — `OtelSpanLike`, `TenantId`, `Principal`.
+- `@suaveplan/error` — `SuaveplanError` + `defineCodes`.
+- `hono` (peer ≥4.0.0) — wire-side dispatch.
+
+## Version
+
+`0.1.0` — initial Stage-4 ship. Graduates to `1.0.0` when the plugin system as a whole is declared production-ready.
+