docs(response): clarify v1 scope per Gemini Code Assist feedback

Three medium-priority concerns from the review needed reconciliation
between the design doc and the v1 implementation:

1. Replacement contract: doc claimed structured replacement (status /
   body / headers from the rule's value). v1 actually returns bool
   from the evaluator and does a fixed 503 on deny. The structured
   replacement requires the evaluator to surface json.Value plus a
   discriminator and is deferred to a follow-up PR. Doc now splits
   'v1' (fixed 503) from 'deferred' (structured).

2. 503 vs 403 asymmetry: doc didn't say which deny code response-side
   uses, request-side already returns 403. v1 uses 503 on the
   response side (upstream being replaced) vs 403 on the request
   side (request rejected before upstream). Doc now states this
   explicitly as intentional.

3. Backward compat for nested input shape: doc showed
   '{request, response}' nested input which would have broken
   existing input.method / input.path refs. v1 keeps the request-side
   input flat (unchanged) and adds 'input.response.*' ONLY for the
   allow_response target rule. input.request.* is reserved for the
   v2 post-snapshot picture. Doc now shows v1 vs v2 input shapes
   separately and clarifies 'allow' policies are untouched.

Per-context state section also corrected: v1 does not snapshot
request fields. The snapshot lives behind body-aware-policies.md
(PR #6) and shows up here only when that lands.

Author: kanywst

docs/proposals/response-side-policies.md

@@ -27,7 +27,9 @@ Use cases:
 1. Implement `proxy_on_response_headers`:
    - Build an input shape reflecting response status and headers.
    - Evaluate the AST against the response target rule.
-   - On deny, replace the response (status + body + selected headers).
+   - On deny, replace the response with a fixed status (see
+     §Replacement contract for v1 behaviour and the deferred
+     structured replacement).
    - On allow, fall through.
 1. Reuse the existing AST machinery. No new node types are needed for
    v1; only a new target rule and a new input shape.
@@ -46,9 +48,9 @@ Use cases:
 
 ### Per-context state
 
-Borrow the snapshot from `body-aware-policies.md`: a per-context store
-that already holds request `:method` and `:path` so the response rule
-can reason about request → response pairs.
+Eventually we want a per-context store that already holds request
+`:method` / `:path` so the response rule can reason about
+request → response pairs (sketched in `body-aware-policies.md`):
 
 ```zig
 const ResponseContext = struct {
@@ -58,26 +60,51 @@ const ResponseContext = struct {
 };
 ```
 
+**v1 does not implement the snapshot.** The response rule sees only
+the response side. `input.request.*` becomes valid once the
+per-context plumbing lands; until then, body / response policies
+that need request context have to encode it via the host.
+
 ### Input shape
 
+v1 (this PR) ships **only** the response subtree. The request-side
+`allow` rule keeps its existing flat shape (`input.method`,
+`input.path`, `input.headers`). They are disjoint inputs because
+they target disjoint rules.
+
 ```json
+// allow_response input (this PR)
 {
-  "request": {
-    "method":  "GET",
-    "path":    "/admin/users",
-    "headers": { "...": "..." }
-  },
   "response": {
     "status":  500,
     "headers": { "server": "nginx/1.27", "...": "..." }
   }
 }
 ```
 
+The wider shape with both `input.request.*` and `input.response.*`
+visible together is the post-snapshot v2 picture and is not exposed
+yet:
+
+```json
+// v2 (deferred): both subtrees once the snapshot lands
+{
+  "request":  { "method": "GET", "path": "/admin/users", "headers": {} },
+  "response": { "status": 500, "headers": {} }
+}
+```
+
 ### Replacement contract
 
-When the response rule denies, zopa calls `proxy_send_local_response`
-with parameters drawn from the rule's `value`:
+**v1**: rule denies (returns `false` or `nil`) → zopa calls
+`proxy_send_local_response(503, ...)` with empty body / no extra
+headers. Allow falls through unchanged. The deny status code is
+**503** here (the upstream response is being replaced) vs **403**
+on the request-side `allow` path (the request is being rejected
+before it reaches upstream). The asymmetry is intentional.
+
+**Deferred**: rule returns a structured value carrying status / body
+/ headers, e.g.
 
 ```json
 {
@@ -90,14 +117,20 @@ with parameters drawn from the rule's `value`:
 }
 ```
 
-A bare boolean `false` keeps current behavior (replace with a static
-`503` and an empty body).
+This needs the evaluator to surface a `json.Value` (not a `bool`)
+to the proxy-wasm shim, plus a discriminator so the shim can tell
+"the policy returned a structured replacement" from "the policy
+returned a non-boolean truthy value (= allow)". Both changes are
+non-trivial and deferred to a follow-up PR.
 
 ## API impact
 
 - New target rule name `allow_response` joins the existing `allow`.
-- Existing `allow` policies continue to work unchanged.
-- New AST refs become valid: `input.request.*`, `input.response.*`.
+- Existing `allow` policies continue to work unchanged: same input
+  shape (`input.method` / `input.path` / `input.headers`), same
+  return contract, same 403 deny status.
+- v1 adds the `input.response.*` ref namespace under `allow_response`.
+  `input.request.*` is reserved for v2 once per-context state lands.
 
 ## Test plan