feat: response decoration api with cookie support

[markshust]

Gives Response a decoration API and first-class cookie support, and makes request-scoped singleton state explicitly clearable.

The live bug this fixes

StreamingResponse extends Response carries its payload in an SseStream with body = ''. Five middleware added headers by constructing a brand-new base Response from the previous response's getters:

// packages/security/src/Middleware/SecurityHeadersMiddleware.php — before
return new Response(
    body:       $response->body(),
    statusCode: $response->statusCode(),
    headers:    array_merge($response->headers(), $securityHeaders),
);

Any of them in front of an SSE route downgraded the StreamingResponse to a plain Response — the stream was discarded, the overridden send() never ran, and the client got an empty 200 with correct headers. SecurityHeadersMiddleware is exactly the kind of middleware apps register globally.

All six rebuild sites across five files now decorate instead, and tests/MiddlewareDecorationTest.php fails the build if the pattern reappears in any middleware.

Why Response is no longer readonly

Verified empirically on PHP 8.5.1 before committing to the design:

Approach	Result
clone $this with { ... }	Not available in 8.5.1 — parse error
readonly class + clone then assign	Fails: Cannot modify readonly property
readonly class + ReflectionProperty::setValue	Fails: same
Plain class, private non-readonly props, clone + assign	Works — preserves subclass, subclass state, original untouched

clone is required because StreamingResponse::__construct(SseStream, int) has a different signature from its parent, so new static(...) cannot reconstruct it. Immutability is now enforced by API design — private properties, no setters, with*() returns copies. json()/html()/redirect() deliberately keep new self() for the same reason.

Session cookie moves onto the Response

setcookie() is gone from the codebase. The cookie now travels on the Response, which makes it visible to middleware, assertable without superglobal fixtures, and able to reach a client under a SAPI where setcookie() is a no-op.

Three subtleties worth reviewing closely:

• session.use_cookies = 0 disables session ID reading, not just writing, so SessionMiddleware seeds the ID from the inbound request cookie itself. Without this, every request would silently start a fresh empty session.
• A tampered inbound cookie fails setId()'s validation. That value is attacker-controlled, so it is ignored in favour of a fresh session rather than surfacing as a 500.
• The cookie attaches only when the ID changed (new, regenerated, or expired-on-destroy), matching what session_start() did before. Attaching unconditionally would have silently disabled the page cache for every session-enabled app, since SessionMiddleware runs inside PageCacheMiddleware and cookie-bearing responses are never cached. tests/Integration/PageCacheSessionMiddlewareTest.php guards this.

Cross-user leaks closed

Three verified leaks that only manifest in a booted-once process, each reproduced by a failing test before being fixed:

1. Session reused the previous request's ID. save() left $this->id populated and start() fed it back to session_id(). On a singleton, an anonymous visitor following an authenticated one resumed the previous user's session.
2. SessionGuard::$cachedUser persisted across requests on a singleton guard, cleared only by the destructive logout().
3. session_set_save_handler($handler, true) ran on every start(), registering a shutdown function per request — unbounded growth in a worker.

SessionInterface and GuardInterface are byte-identical; every marko/testing fake still satisfies them unedited. ResettableInterface is implemented on the concrete classes for exactly that reason.

Also

• Cookie value object — rawurlencode()d values so a; b cannot inject a second attribute, SameSite=None without Secure throws rather than emitting a cookie browsers silently drop, and lifetime => 0 omits Expires entirely rather than sending an epoch
• Request::cookie() plus $_COOKIE capture in fromGlobals()
• Response::headerLines() — SAPI-free header emission, consumed by both send() implementations
• Page cache refuses to store cookie-bearing responses — a security boundary, since a cached Set-Cookie would be replayed to every later visitor
• ResettableInterface in core, implemented by Session, SessionGuard and ReadWriteConnection; Container::resolvedInstances() discovers them without forcing instantiation

Verification

6972 tests passing, 0 failures. PHPStan: no errors. PHPCS: clean.

Known follow-up

Container::resolvedInstances() is on the concrete Container, but Application::$container is typed ContainerInterface, so it is not reachable through the interface. Container is the only implementor, so adding it there is low-risk — but it is a BC-breaking interface change and belongs before 1.0 rather than in the follow-up worker PR. Deliberately left out of this PR's scope.

Closes #150

🤖 Generated with Claude Code