feat(start-http): the HTTP runtime, and order-api migrated onto it

[btravers]

Ships @btravstack/start-http, the first of the three deferred runtime packages, and migrates examples/order-api off its hand-rolled transport onto it. Spec and plan are included as the first commits.

The package owns a lifecycle, not a framework

CLAUDE.md had carried -http as "routing, middleware, Result → HTTP status" since the kernel shipped. Two thirds of that is now explicitly out of scope and will not ship. Routing and middleware are solved by oRPC, Hono and Express; the part examples/order-api proved genuinely hard was the lifecycle — and two of the defects found in this morning's review lived in exactly that code.

start(AppModule,{runtime: httpRuntime({port: env.PORT,needs: [PlaceOrder,FindOrder,Logger],handler: (req,res,ctx)=>rpc.handle(req,res,{context: { ctx }}),}),});

Verified compatible against the shipped type definitions, not assumed: oRPC's RPCHandler.handle, Hono's getRequestListener (notserve(), which owns its own server), and @unthrown/orpc, which sits inside a procedure and never sees the server.

The central claim

A request's unit closes when the response completes, not when the handler settles. The kernel documents "flush the response inside the unit" as one of two contracts it cannot check — break it and an 8 MB body dies with UND_ERR_SOCKET: other side closed. Tying the unit to the response's close event makes that structural: writing late is impossible, because the unit is still open until the bytes are out.

That creates a second obligation the package also takes on: every request produces exactly one completed response. A handler that resolves without writing gets a 404, one that rejects gets a 500 — otherwise the client hangs and the unit sits in flight until the drain abandons it. oRPC's matched: false is exactly that case.

Three behaviours move out of the example and into the package, each one paid for already:

• Connection: close on responses open when the drain begins.closeIdleConnections() reaches only connections idle at that instant; measured on Node 22.19, a busy one survives and node keeps serving requests down it for the whole drain window.
• The bind's synchronous throw is caught.listen validates the port itself and throws ERR_SOCKET_BAD_PORT; uncaught it becomes a Defect and bypasses the declared error channel.
• The server keeps an 'error' listener for life. Zero listeners turns a post-bind EMFILE into an unhandled 'error', which the kernel's uncaughtException handler escalates into killing the application.

examples/order-api

Loses 274 lines of transport, keeps what it exists to teach: the oRPC router, the Result → ORPCError mapping, the per-request Module.forkScope, the contract split. Its needs-gate.test-d.ts still pins start's phantom rest-tuple gate — verified by stripping the @ts-expect-error and confirming it still fails.

Two tests moved into the package rather than being duplicated, and both closed a deferred item honestly: the permanent-'error'-listener test (the vi.mock now lives in the package's fixtures, where test convention 1 isn't at stake) and the headersSent retire branch, which was recorded as unreachable through oRPC's router and is reachable here because the test supplies the handler.

Also fixed

packages/start/src/probes.spec.ts carried a vacuous-capable assertion of the same shape — created?.emit(...) passes when the capture is empty. Merged this morning in #11; fixed here, and the guard was verified to fail loudly by deliberately breaking the mock.

Gate

format, lint, typecheck, knip, build green. 185 tests across 10 workspaces; packages/start-http at 100% lines and functions, enforced. The single failure is packages/start's binds 9000 when no probe port is given — environmental (EADDRINUSE on 127.0.0.1:9000 locally, passes in CI).

Review trail, and what it caught

Eleven tasks, each implemented by a fresh agent and reviewed independently. Worth reading sceptically rather than as a warrant: nearly every Important finding was against the plan, not the implementations — devDependencies that failed knip, coverage thresholds six tasks premature, a recoverDefect swap that reintroduced the gap it was meant to close, a brief pointing at the wrong file, and a branch declared unreachable that wasn't. That last would have shipped an untested behaviour — what happens to a streamed response when the drain begins — because the limitation was copied across a boundary where it didn't apply.

One re-review cited start-temporal as a published package to justify its verdict. It doesn't exist. That verdict was independently verified before being accepted.

Deliberate, so they read as decisions rather than gaps

• hostname defaults to 0.0.0.0 — the deployment target is a pod; a laptop should set 127.0.0.1.
• An AsyncResult carrying an Errresolves, so it reaches 404, not 500. The package does not map Result → status.
• Serving.drain's signal is unused: HTTP has nothing to escalate to, unlike Temporal.
• packages/start-http/README.md's samples are compiled by nothing, unlike the kernel's — recorded in CLAUDE.md's deferred list rather than left silent.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR introduces @btravstack/start-http, an HTTP runtime package that implements the @btravstack/start runtime contract (bind, one unit per request, drain/stop semantics), and migrates examples/order-api from its bespoke transport onto this shared runtime. It also updates repo docs/specs/plans to reflect start-http as shipped and tightens one kernel test to avoid a vacuously-passing assertion.

Changes:

• Add packages/start-http with httpRuntime(...), docs, and a 100%-coverage vitest suite.
• Migrate examples/order-api to use httpRuntime + an extracted apiHandler, deleting the old hand-rolled runtime.
• Update root/package/example documentation and type-checked docs samples to reflect the shipped HTTP runtime and revised responsibilities.

Reviewed changes

Copilot reviewed 30 out of 32 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
README.md	Updates root README wording to reflect start-http shipping and handler-owned Result → HTTP mapping.
pnpm-lock.yaml	Adds workspace link entries for packages/start-http and examples/order-api dependency updates.
packages/start/src/probes.spec.ts	Prevents a vacuous pass by asserting the mocked server capture is non-empty before emitting events.
packages/start/src/docs-examples.test-d.ts	Keeps type-checked docs sample text in sync with updated README phrasing.
packages/start/README.md	Updates package README sample text consistent with the root README change.
packages/start/CLAUDE.md	Updates internal guidance to reference @btravstack/start-http instead of the old example runtime.
packages/start-http/vitest.config.ts	Adds package-local vitest config with enforced 100% line/function thresholds.
packages/start-http/tsconfig.json	Adds package tsconfig extending the shared base config.
packages/start-http/src/vitest.d.ts	Ensures @unthrown/vitest matcher types are available in the package.
packages/start-http/src/test-fixtures.ts	Adds vitest fixtures (server capture, keep-alive socket tooling, gate handlers) for runtime behavior tests.
packages/start-http/src/index.ts	Exposes httpRuntime and its public types.
packages/start-http/src/http-runtime.ts	Implements the HTTP runtime lifecycle, per-request unit binding to response completion, drain retirement behavior, and trace-id policy.
packages/start-http/src/http-runtime.spec.ts	Comprehensive runtime tests covering bind failures, post-bind errors, per-request unit lifecycle, 404/500 fallback, trace id adoption, and drain/keep-alive behavior.
packages/start-http/README.md	Documents scope, guarantees, non-goals, options, and behavior of @btravstack/start-http.
packages/start-http/package.json	Adds the new publishable package manifest, exports, scripts, and dependency metadata.
packages/start-http/LICENSE	Adds MIT license for the new package.
examples/README.md	Updates examples documentation to reflect order-api using start-http and the current gate exercise points.
examples/order-temporal/README.md	Updates cross-example Serving.info shape references to match HttpInfo.
examples/order-api/src/test-fixtures.ts	Rewires fixtures to start order-api via httpRuntime and removes transport-level keep-alive tooling moved into the package.
examples/order-api/src/orpc-runtime.ts	Deletes the previous bespoke HTTP/oRPC runtime implementation.
examples/order-api/src/needs-gate.test-d.ts	Updates needs-gate typing test to reference httpRuntime and the extracted handler.
examples/order-api/src/module.ts	Updates composition-root documentation to match the new httpRuntime needs declaration site.
examples/order-api/src/main.ts	Switches runtime boot to httpRuntime with explicit needs and the extracted apiHandler.
examples/order-api/src/index.ts	Updates exports to expose apiHandler/ApiNeeds and remove old runtime exports.
examples/order-api/src/handler.ts	Introduces apiHandler that performs per-request Module.forkScope + oRPC dispatch for use with httpRuntime.
examples/order-api/src/api.spec.ts	Renames and updates tests to reflect HttpInfo and removal of transport-specific tests migrated to start-http.
examples/order-api/README.md	Updates example docs to point to start-http for transport lifecycle concerns and focuses the example on handler/router concerns.
examples/order-api/package.json	Adds dependency on @btravstack/start-http and updates description accordingly.
docs/superpowers/specs/2026-08-12-start-http-design.md	Adds the design spec documenting scope/decisions/public surface for start-http.
docs/superpowers/plans/2026-08-12-start-http.md	Adds the implementation plan detailing tasks, constraints, and verification steps.
CLAUDE.md	Updates repo-level guidance to include start-http as shipped and adjusts related documentation/convention notes.
.changeset/start-http.md	Adds a changeset to release @btravstack/start-http as a minor version bump.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.