Scaffold miniroute routing/middleware kernel

1 files changed, 27 insertions, 0 deletions

diff --git a/docs/adr/0003-request-response-boundary.md b/docs/adr/0003-request-response-boundary.md
new file mode 100644
index 0000000..9129c0d
--- /dev/null
+++ b/docs/adr/0003-request-response-boundary.md
@@ -0,0 +1,27 @@
+# ADR 0003: Thin HTTP Contracts
+
+- Status: Accepted
+- Date: 2026-08-17
+
+## Context
+
+The kernel needs request/response types, but applications already have their
+own concrete HTTP objects (and their own security headers, session handling,
+and parsing).
+
+## Decision
+
+The kernel defines `RequestInterface` and `ResponseInterface` with only the
+surface routing needs (method, path, params) and middleware needs (headers).
+Applications implement these interfaces on their own classes.
+
+Middleware and controllers operate on the interfaces, so application code that
+needs app-specific features narrows to its concrete types.
+
+## Consequences
+
+- The kernel stays decoupled from any one app's HTTP layer.
+- Applications must implement the two interfaces (usually a small change to
+  existing Request/Response classes).
+- Middleware parameters use `RequestInterface`; concrete middleware may need
+  an `instanceof` narrowing to access app-specific request methods.