suaveplan/openspec/archive/2026-05-26-foundation-fix-gap-1-pipeline-router/proposal.md

foundation-fix-gap-1-pipeline-router

Summary

Close foundation-coherence Gap #1: @suaveplan/api-router-hono's HonoRouter did not satisfy @suaveplan/api-host's PipelineRouter contract. The two match() shapes diverged (RouteMatch vs PipelineRoute), forcing every host-pipeline consumer to hand-roll a shim — the E2E foundation-stack server's createFixtureRouter() was the canonical example. This change adds a second, additive facet to HonoRouter (registerPipelineRoute / matchPipeline / unregisterPipelinePlugin / listPipelineRoutes) that produces values structurally assignable to the host's PipelineRoute interface, and ships a canonical runPipelineRouterConformance(factory) test harness in @suaveplan/api-host/testing so every concrete adapter has a single contract to pass.

Motivation

Empirically the gap caused two failure modes:

1. Hand-rolled shims in every consumer — the E2E foundation-stack server's createFixtureRouter() was 80 lines of router logic that should have lived inside api-router-hono. Every new host-pipeline consumer was on track to write the same shim.
2. No conformance suite — api-router-hono passes runRouterConformance against the abstract Router, but no harness existed for the host's PipelineRouter surface. Adapter drift would only surface during a real E2E run.

The fix is additive — the existing abstract-Router surface is preserved verbatim; the pipeline facet lives next to it as a parallel metadata sidecar. No breaking changes to existing consumers.

Scope

• @suaveplan/api-router-hono:
  • new src/pipeline/ feature module (PipelineRouteTable, HonoPipelineRoute, HonoPipelineRegistration, HonoPipelineRouteOptions, HonoPipelineHandler).
  • HonoRouter gains registerPipelineRoute, unregisterPipelineRoute, unregisterPipelinePlugin, listPipelineRoutes, matchPipeline.
  • new error code ROUTER_HONO.PIPELINE_ROUTE_COLLISION.
  • new subpath export ./pipeline.
  • dev-dep on @suaveplan/api-host (testing-only).
  • vite config emits index.js per subpath (closes a pre-existing ./adapter resolution bug).
• @suaveplan/api-host:
  • ./testing subpath populated with runPipelineRouterConformance(factory) + PipelineRouterConformanceFactory / PipelineRouteRegistration types.
  • vite config switched to multi-entry so the dist actually emits testing/testing.js (closes a pre-existing dead-export bug).
• e2e/foundation-stack:
  • drop hand-rolled createFixtureRouter body; replace with the real HonoRouter pipeline facet.

Verification

• Unit + integration: bunx turbo lint typecheck test build --filter=@suaveplan/api-router-hono --filter=@suaveplan/api-host → green; 75 unit tests across api-router-hono, 252 across api-host.
• Coverage: api-router-hono 100/100/100/100 on every touched module (adapter, pipeline, error-codes).
• E2E: cd e2e/foundation-stack && bunx playwright test — all 10 test groups pass (livez/readyz, plugin routes, tenant resolver, domain error envelope, 404 envelope, secrets, admin plugins/details, admin capabilities, rate-limit, idempotency).

Out of scope

• Migrating api-router-worker-bridge to the pipeline facet — that adapter will adopt the same harness in a follow-up.
• Wiring the HonoRouter pipeline facet into the host's LifecycleDriver.mount-routes op — currently consumers register manually; threading through the lifecycle is a follow-up change.