@jimhoyd/urlcode 0.4.2 → 0.4.6

package/docs/STANDARDS.md

@@ -1,311 +0,0 @@
-# Standards conformance audit
-
-What URLCode implements of each RFC and specification it touches or names,
-verified against the code and the test suite. The first pass was written at
-`817f0ab` (2026-09-17, Node v22.22.2); every row was re-verified against the
-source at `8d7dd01` (2026-09-18) and now cites the function or constant that
-implements the behavior rather than a line number, so a row stays checkable
-after the file around it moves. Every row also names the test that proves it;
-"untested" means no test in `test/` asserts that specific behavior. Where the
-code was not conclusive, the behavior was observed by running a server with
-the test helpers and sending raw requests over `node:net` / `node:http`; those
-rows say "probed". A row that could not be re-verified says
-"unverified at 8d7dd01" rather than guessing.
-
-Status vocabulary:
-
-- **conforms**: the implemented subset follows the standard's requirements.
-- **partial**: some of the standard is implemented and the rest is out of
-  scope or approximated; the deviation is stated with its rationale.
-- **deviates**: the runtime does something the standard forbids or requires
-  differently; listed again in the gap list at the end.
-- **not applicable**: the standard is only named, or is delegated to a
-  platform, and no code claims to implement it.
-
-## Summary
-
-| Standard | Status | Section |
-|---|---|---|
-| RFC 9110 HTTP Semantics | partial (408 on idle timeout is a SHOULD the server does not send) | [1](#1-rfc-9110-http-semantics) |
-| RFC 9111 HTTP Caching | partial | [2](#2-rfc-9111-http-caching) |
-| RFC 5861 stale-while-revalidate / stale-if-error | partial | [3](#3-rfc-5861-stale-while-revalidate-and-stale-if-error) |
-| RFC 8246 immutable | conforms | [4](#4-rfc-8246-immutable) |
-| RFC 9213 targeted cache control | conforms | [5](#5-rfc-9213-targeted-cache-control) |
-| RFC 6585 additional status codes (429, 431) | conforms | [6](#6-rfc-6585-additional-http-status-codes) |
-| RFC 9112 HTTP/1.1 message syntax | partial (asterisk-form 400) | [7](#7-rfc-9112-http11-message-syntax) |
-| RFC 3986 URI | partial (dot segments rejected, not normalized) | [8](#8-rfc-3986-uri-and-percent-encoding) |
-| RFC 7239 Forwarded | not applicable (only `X-Forwarded-For`) | [9](#9-rfc-7239-forwarded-and-x-forwarded-for) |
-| RFC 9309 robots.txt | conforms (generated by `site.robots`) | [10](#10-rfc-9309-robotstxt) |
-| RFC 6797 HSTS | conforms | [11](#11-rfc-6797-hsts) |
-| RFC 1950/1952 (deflate/gzip), RFC 7932 (br), RFC 8878 (zstd) | conforms | [12](#12-rfc-19501952-rfc-7932-rfc-8878-content-codings) |
-| RFC 6265 Set-Cookie | partial (emission only) | [13](#13-rfc-6265-set-cookie) |
-| RFC 6266 / 8187 Content-Disposition | conforms (library) | [14](#14-rfc-6266--rfc-8187-content-disposition) |
-| draft-ietf-httpapi-ratelimit-headers | conforms to the draft syntax (Internet-Draft, not an RFC) | [15](#15-ietf-httpapi-ratelimit-header-fields-internet-draft) |
-| web-bot-auth drafts | not applicable | [16](#16-web-bot-auth-drafts) |
-| OWASP Secure Headers Project | conforms to the pinned table | [17](#17-owasp-secure-headers-project) |
-| CSP Level 3 | partial (emits one obsolete directive from OSHP) | [18](#18-content-security-policy-level-3) |
-| JSON Schema 2020-12 | conforms (Ajv 8.20.0) | [19](#19-json-schema-2020-12) |
-| YAML 1.2 | conforms (JSON-compatible profile) | [20](#20-yaml-12) |
-| CIDR notation | conforms | [21](#21-cidr-notation-for---trusted-proxies) |
-
-## 1. RFC 9110 HTTP Semantics
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| §9 methods; default GET/HEAD | conforms | `src/router.ts` `methodsDefault = ['GET','HEAD']`; an explicit `methods` list replaces it when `compileRoutes` builds the route; schema enum under `methods` in `schemas/urlcode.schema.json` | `test/http.test.ts` "literal precedence, methods, HEAD, query isolation, disabled/expired and health" |
-| §15.5.6 405 with `Allow` | conforms | `Runtime.handle` in `src/runtime.ts` answers `405` with `allow: <route.methods>` after host policies ran; health probes in `startServer` (`src/server.ts`) answer `405` with `allow: GET, HEAD`; the Worker does the same in `src/cloudflare.ts` | same test (`allow === 'GET, HEAD'`); `test/policies.test.ts` "interoperability: ... 405 carries policy headers"; `test/aws.test.ts` "a Lambda response carries exactly ..." (405 on POST) |
-| §9.1 unrecognized method → 501 | partial | Node's parser refuses unknown tokens before the runtime sees them; the `clientError` handler in `startServer` writes `400`. Probed: `BREW /r` → 400. Rationale: llhttp rejects at parse time; the runtime never sees the method | untested |
-| §9.3.2 HEAD suppresses body | conforms | `prepareResponse` in `src/http-response.ts` drops the body for HEAD and for 204/205/304 (`bodyless`) | `test/http.test.ts` (HEAD `/go` body `''`); `test/http-policy.test.ts`; `test/vercel.test.ts` |
-| §8.6 `Content-Length` on HEAD MUST equal what GET would send | conforms | `prepareResponse` measures `result.contentLength ?? result.body.length` on the result's body before the body is dropped for HEAD, so a `respond`, function or middleware result reports the GET length. Assets set `contentLength` in `assetResponse` (`src/assets.ts`) and cache hits in `served` (`src/policies/cache.ts`); compression leaves a dynamic body identity on HEAD (`onResponse` in `src/policies/compression.ts`), so the identity length is stated | `test/standards.test.ts` "HEAD states the length GET would send on declared and function responses (RFC 9110 §8.6)" |
-| §15.4 redirects: 301/302/303/307/308, absolute `Location` | conforms | schema enum under `redirect.status` in `schemas/urlcode.schema.json`; `redirectLocation` in `src/match.ts` builds `Location` from `new URL(...).href`; default 302 where `Runtime.handle` builds the redirect result (`route.redirect.status || 302`), and stored links carry their own status | `test/http.test.ts` (location assertions); `test/http-policy.test.ts` "YAML response headers apply to functions and redirects" |
-| §10.2.2 `Location` reserved from YAML | conforms | `reserved` in `src/http-policy.ts` includes `location`, `allow`, `content-range`, `accept-ranges`, `etag`, `last-modified`, `content-encoding` | `test/http-policy.test.ts` "invalid response policy and contradictory declarations fail activation" |
-| §7.6.1 hop-by-hop headers never set by a handler | conforms | `forbiddenHeaders` in `src/http-response.ts` (connection, keep-alive, transfer-encoding, content-length, upgrade, trailer, proxy-authenticate, proxy-authorization, te) stripped by `prepareResponse`, refused in YAML by `compileHttp` (`reserved` in `src/http-policy.ts`), and filtered from error answers by `errorResponse` | `test/http-policy.test.ts` "invalid response policy ..." |
-| §5.6.2 field names are tokens; §5.5 no CTLs in values | conforms | `token` and `invalidValue` in `src/header-validation.ts` (`validateHeaderName`, `validateHeaderValue`), applied by `prepareResponse`, `compileHttp` and `compile` in `src/policies/security.ts` | `test/header-validation.test.ts` all three tests (compared against `node:http` over 0x00–0x11F) |
-| §8.8.3 ETag, strong vs weak | conforms | Assets: strong `"sha256(type+disposition+body)"` computed in `compileAssets` (`read`). Precompressed variants: strong tag with the `SUFFIX` coding suffix inside the quotes (`etagFor` in `src/policies/compression.ts`). Dynamically compressed bodies: handler tag weakened to `W/...` (`etagFor` with `strong = false`). `revalidate` strategy: strong SHA-256 over the body when the handler sent none (`revalidate` in `src/policies/cache.ts`) | `test/assets.test.ts` "asset conditions, byte ranges ..."; `test/policy-compression.test.ts` "page assets are precompressed once, served by reference with a suffixed strong ETag, and revalidate" and "function JSON compresses with a weak ETag ..."; `test/policy-cache.test.ts` "revalidate answers 304 ..." |
-| §8.8.2 `Last-Modified` | conforms | second-resolution IMF-fixdate from mtime (`modified` in `compileAssets`) | `test/assets.test.ts` (304 on `if-modified-since`) |
-| §13.1.1 `If-Match` strong comparison | conforms | `matches(value, weak=false)` in `assetResponse` compares the full tag, so `W/"x"` never matches; `*` matches | `test/assets.test.ts` (`if-match: W/<etag>` → 412) |
-| §13.1.2 `If-None-Match` weak comparison | conforms | `matches(value, weak=true)` in `assetResponse` strips `W/`; `*` matches; `noneMatch` in `src/policies/cache.ts` and in `src/policies/compression.ts` do the same for their own tags | `test/assets.test.ts` (`W/<etag>` → 304); `test/policy-cache.test.ts` "revalidate answers 304 ..." |
-| §13.1.3 / §13.1.4 date conditions ignored when the ETag condition is present; invalid dates ignored | conforms | `assetResponse`: `If-Unmodified-Since` is read only when `If-Match` is absent, `If-Modified-Since` only when `If-None-Match` is absent; `Date.parse` → `NaN` makes both comparisons false, i.e. the header is ignored | `test/assets.test.ts` (`if-none-match: "other"` + matching `if-modified-since` → 200) |
-| §13.2.2 evaluation order If-Match → If-Unmodified-Since → If-None-Match → If-Modified-Since → If-Range | conforms | `assetResponse` in that order; Range evaluated after preconditions and only for GET | `test/assets.test.ts` (`range` + `if-none-match` → 304; HEAD + `range` → 200 with full length) |
-| §14 Range, single byte range; §14.4 206 `Content-Range`; §15.5.17 416 with `bytes */size` | conforms | `assetResponse`: suffix and open-ended ranges, `BigInt` arithmetic, 416 with `bytes */<size>`; multiple/malformed/non-`bytes` units ignored (§14.2 "MAY ignore") | `test/assets.test.ts` "asset conditions, byte ranges, empty files and HEAD obey HTTP ordering" |
-| §13.1.5 `If-Range` | partial | `assetResponse`: only an exact strong ETag match enables the range; a date `If-Range` is treated as non-matching and the full 200 is sent. Rationale (comment above the range check, `docs/ASSETS.md`): a date validator is only usable when it is known to be strong; sending the full representation is the prescribed fallback for a non-matching validator | `test/assets.test.ts` (`if-range: "old"` → 200; `if-range: <etag>` → 206) |
-| §15.4.5 304 header set | conforms | Assets keep `Content-Type`, `ETag`, `Last-Modified`, `Cache-Control`, `Accept-Ranges` (`headers` in `assetResponse`); `Content-Length` omitted for 304 (`bodyless` in `prepareResponse`). `revalidate` keeps the `kept` set in `src/policies/cache.ts` (`etag, cache-control, cdn-cache-control, vary, last-modified, content-location, expires, date, content-type`) | `test/policy-cache.test.ts` "revalidate answers 304 ..." (checks `etag`, `cache-control`, `content-type` on the 304) |
-| §12.5.3 `Accept-Encoding` negotiation | conforms | `negotiate` in `src/policies/compression.ts`: q-weights, `*` for unnamed codings, highest weight wins, project order breaks ties; identity is sent when nothing is acceptable, including `identity;q=0` / `*;q=0` (§12.5.3 permits either identity or 415; the code chooses identity, comment above `negotiate`) | `test/policy-compression.test.ts` "negotiation follows RFC 9110 q-values with the project order as tie-break" |
-| §8.4 `Content-Encoding` | conforms | set only by `onResponse` in `src/policies/compression.ts`; reserved from YAML (`reserved` in `src/http-policy.ts`); request bodies with a non-identity `Content-Encoding` are refused with 415 by `checkRequest` | `test/policy-compression.test.ts`; `test/http-policy.test.ts` "request body policies reject size, media, encoding and malformed JSON" |
-| §12.5.5 `Vary` | conforms | `withVary` in `src/policies/compression.ts` adds or merges `Vary: Accept-Encoding` and respects `*`, also on 304/206 (`varied` is returned for those); cache strategies merge declared `vary` names (`mergeVary` in `src/policies/cache.ts`) | `test/policy-compression.test.ts` "declared text responses compress ... Vary is set once"; `test/policy-cache.test.ts` "vary headers separate keys and are emitted ..." |
-| §15 status codes used | conforms | 400 (`parseTarget` in `src/match.ts`, `checkRequest` in `src/http-policy.ts`), 404 (`Runtime.handle`, `assetResponse`), 405 (`Runtime.handle`), 410 (`Runtime.handle`, expired routes and links), 412/304/206/416 (`assetResponse`), 413 (`readBody` in `src/server.ts`, `checkRequest`), 414 (`parseTarget`), 415 (`checkRequest`), 429/503 (throttle), 431 (`clientError` in `startServer`), 502/504 (function failures, see `docs/SPECIFICATION.md` "Functions"), 503 (`startServer` admission and shutdown). Rationale for 502/504 on sandbox failures: the function pool is treated as an upstream | `test/http.test.ts`, `test/http-policy.test.ts`, `test/policy-throttle.test.ts`, `test/standards.test.ts` |
-| §15.5.9 408 on idle timeout (SHOULD) | partial | `startServer`: `server.setTimeout(15000, socket => socket.destroy())` closes without a status, and the `clientError` handler answers `ERR_HTTP_REQUEST_TIMEOUT` with `400` rather than `408`; probed: an incomplete request head is dropped after ~15 s with no response bytes. Rationale: the socket is destroyed to free the slot; the requirement is a SHOULD | untested |
-| §10.1.5 `User-Agent` | conforms | read-only matching in `onRequest` (`src/policies/agents.ts`); the header value is never logged (the list label is) | `test/policy-agents.test.ts` "a bundled deny list refuses matching agents and logs the list name, never the header" |
-| §10.2.3 `Retry-After` (delay-seconds) | conforms | `onRequest` in `src/policies/throttle.ts` writes `retry-after: <reset>` with integer seconds from `observe` | `test/policy-throttle.test.ts` "quota reached answers 429 with Retry-After and RateLimit headers" |
-| §6.4.1 `Content-Length` on every non-bodyless response | conforms | `prepareResponse`; error answers in `errorResponse` | `test/aws.test.ts` (header comparison includes `content-length`); `test/policy-compression.test.ts` (`content-length` equals encoded length) |
-
-## 2. RFC 9111 HTTP Caching
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| §5.2.2 response directives `no-store`, `no-cache`, `public`, `private`, `max-age` | conforms | the `switch (strategy)` in `compile` (`src/policies/cache.ts`): `no-store`→`no-store`, `revalidate`→`no-cache`, `public`→`public, max-age=N`, `private`→`private, max-age=N`; runtime default `cache-control: no-store` when a handler sets none (`prepareResponse`), errors always `no-store` (`errorResponse`); throttle and agents denials `no-store` (`onRequest` in each policy) | `test/policy-cache.test.ts` "each strategy emits its catalogue headers; explicit fields override what the strategy implies" |
-| §5.1 `Age` on a stored response | conforms | `served` in `src/policies/cache.ts` replaces any `Age` with `floor((now-storedAt)/1000)` | `test/policy-cache.test.ts` "swr serves fresh from the origin cache ..." |
-| §3 storing: never store `Set-Cookie`, `private`, `no-store`, secret-bearing or oversized results | conforms | `storable` in `onResponse` (`src/policies/cache.ts`); only statuses in `statuses` (`DEFAULT_STATUSES = [200,301,302,404,410]`) | `test/policy-cache.test.ts` "Set-Cookie, secret-bearing routes, handler no-store and oversized bodies are never stored" |
-| §4.1 `Vary` in the cache key | conforms | `keyFor` = route, path, query, declared `vary` header values; `mergeVary` emits `Vary` on storable statuses in `onResponse` | `test/policy-cache.test.ts` "vary headers separate keys and are emitted ..." |
-| §4.3 validation requests never served from the origin cache | conforms | `conditional` list in `src/policies/cache.ts`; `onRequest` bypasses for `If-None-Match`, `If-Modified-Since`, `If-Match`, `If-Unmodified-Since`, `Range` | `test/policies.test.ts` "interoperability: conditional requests bypass origin hits ..." |
-| §4.4 invalidation on unsafe methods | partial | only GET results are stored (`onRequest` opens a flight for GET only) and only GET/HEAD looked up; a POST to the same route does not invalidate an entry. Rationale: the store belongs to one runtime and is dropped on reload (`close` in `src/policies/cache.ts`); handlers are side-effect free by design | untested |
-| §5.2.1 request directives (`no-cache`, `max-age=0`, `no-store`) honored by a cache | **partial** | the origin memory cache ignores request `Cache-Control` and `Pragma` (`onRequest` reads only the `conditional` headers). Probed at `817f0ab`: `GET /pub` with `Cache-Control: no-cache` and with `max-age=0` both served from memory with `age: 0`; the code path is unchanged at `8d7dd01`. Rationale (module comment at the top of `src/policies/cache.ts`, `docs/policies/cache.md` "Origin memory cache"): this is the origin's own micro-cache in the NGINX `proxy_cache` sense, part of the origin server rather than a shared cache in the RFC 9111 sense; a client cannot bypass it, as it cannot bypass an origin's internal memoization | untested |
-| §4.2.4 serving stale | partial | stale served only within `stale-while-revalidate` and only once per entry (`entry.revalidating` in `onRequest`), never beyond; see §3 below | `test/policy-cache.test.ts` "swr serves fresh ... serves stale once and refreshes on the next request" |
-| `micro` strategy: `no-store` to clients, 1–5 s origin memory | conforms (origin-side) | `case 'micro'` in `compile` (`MICRO_MAX = 5`); the client-facing header is honest (`no-store`) while the origin memoizes | `test/policy-cache.test.ts` "micro caches at the origin for one second while telling clients no-store" |
-| Explicit YAML / handler `Cache-Control` beats the strategy | conforms | `yamlCacheControl` and `inheritedAsset` in `compile`; `owned` in `onResponse` | `test/policy-cache.test.ts` "vary headers ... explicit YAML cache-control wins over the strategy" and "assets keep their handler cacheControl under an inherited policy ..." |
-
-## 3. RFC 5861 stale-while-revalidate and stale-if-error
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| §3 `stale-while-revalidate=N` emitted | conforms | `case 'swr'` and `case 'sie'` in `compile` (`src/policies/cache.ts`) | `test/policy-cache.test.ts` "each strategy emits its catalogue headers" |
-| §3 background revalidation at the origin cache | partial | a policy has no handle to the handler, so a stale hit is served once and flagged (`entry.revalidating` in `onRequest`); the next request refreshes synchronously; a failed refresh clears the flag (`onError`). Documented in `docs/policies/cache.md` "`swr` at the origin" | "swr serves fresh from the origin cache, serves stale once and refreshes on the next request"; "a failed fill releases waiters to the handler and never stores" |
-| §4 `stale-if-error=N` emitted | conforms | `case 'sie'` in `compile` | "each strategy emits its catalogue headers" |
-| §4 serving stale on error at the origin | partial | header-only: `onError` only releases waiters and clears the flag; it never returns a fallback result although `Runtime.handle` would accept one (the `policy.error` loop in its catch block). Documented in `docs/policies/cache.md` "`sie` limitation" | untested (no test asserts a 5xx is *not* replaced) |
-
-## 4. RFC 8246 immutable
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| `immutable` extension emitted with a long `max-age` | conforms | `case 'immutable'` in `compile`: `public, max-age=<maxAge ?? YEAR>, immutable`; refused unless the pattern has a segment matching `hashedSegment` (8+ hex chars) or `hashedParameter` (a digest-named parameter), or `force: true` | `test/policy-cache.test.ts` "immutable is refused on unhashed paths and accepted with a hashed segment, a hash parameter or force" |
-| Asset `cacheControl: public, max-age=31536000, immutable` | conforms | allowed literal in the schema; passed through as `asset.cache` (`compileAssets`) and emitted by `assetResponse` | `test/assets.test.ts` "native page, download and static handlers ..." (cacheControl variants) |
-
-## 5. RFC 9213 targeted cache control
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| `CDN-Cache-Control` as a Structured-Field dictionary | conforms | `cdn-only` emits `Cache-Control: no-store` plus `CDN-Cache-Control: max-age=N` (`case 'cdn-only'` in `compile`, written by `onResponse` when `owned`); not in the `reserved` set of `src/http-policy.ts`, so a YAML `CDN-Cache-Control` is replaced by the strategy unless YAML also sets `cache-control` | `test/policy-cache.test.ts` "each strategy emits its catalogue headers" |
-
-## 6. RFC 6585 additional HTTP status codes
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| §4 429 Too Many Requests with an explanatory body | conforms | `bodies` and `onRequest` in `src/policies/throttle.ts`: `429`, `Too many requests\n`, `Retry-After`, `RateLimit*`; any 4xx/5xx `status` allowed with a matching short body | `test/policy-throttle.test.ts` "quota reached answers 429 ..." and "status other than 429 gets a matching short body" |
-| §5 431 Request Header Fields Too Large | conforms | `startServer` sets `maxHeaderSize: 16384`; the `clientError` handler answers `HPE_HEADER_OVERFLOW` with `431 Request Header Fields Too Large` and every other parse failure with `400 Bad Request` | `test/standards.test.ts` "oversized header fields answer 431, not 400 (RFC 6585 §5)" |
-
-## 7. RFC 9112 HTTP/1.1 message syntax
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| §3.2.1 origin-form request target | conforms | `parseTarget` in `src/match.ts` requires a leading `/`, rejects `//`, `#`, controls, `\`; length > 8192 is 414 | `test/http.test.ts` "malformed and ambiguous URL encodings fail before routing" (`//evil.example`, `/%00` ...) |
-| §3.2.2 absolute-form MUST be accepted by servers | conforms | `originForm` in `src/server.ts` strips the scheme and authority textually before `parseTarget`, so `GET http://example.test/go?x=1` routes as `/go?x=1` and a bare authority becomes `/`. The Worker and Lambda paths reconstruct an origin-form target themselves | `test/standards.test.ts` "request targets: 414 for over-long, absolute-form accepted, asterisk-form refused (RFC 9112 §3)" |
-| §3.2.4 asterisk-form for `OPTIONS *` | deviates (minor) | `parseTarget` refuses `*` (no leading `/`) → 400. No route can be `*`, so no handler could answer it anyway | same test (`OPTIONS *` → 400) |
-| §3 414 for over-long request targets | conforms | `parseTarget` throws `HttpError(414, 'URI too long')` for targets over 8192 bytes. Node's own limit (`maxHeaderSize`) answers 431 earlier for the whole head | same test (9000-byte path → 414) |
-| §3.2 missing `Host` → 400 | conforms | enforced by Node's parser; probed `GET /r HTTP/1.1` with no `Host` → 400 | untested |
-| §6.1 `Content-Length` + `Transfer-Encoding` both present → reject | conforms | Node parser; probed → 400 | untested |
-| §7 chunked request bodies | conforms | Node decodes; `readBody` in `src/server.ts` counts decoded bytes against the limit and answers 413 | `test/http.test.ts` "chunked oversized body returns 413 and server remains usable" |
-| header field limits | conforms | `maxHeaderSize: 16384`, `headersTimeout: 10000`, `requestTimeout: 15000`, `keepAliveTimeout: 5000` in `http.createServer` options, `maxRequestsPerSocket = 1000`, `maxConnections = 1024` (all in `startServer`); response headers ≤ 16 KiB / 256 pairs (`compileHttp` and `decorateResponse` in `src/http-policy.ts`) | `test/http.test.ts` "limits reject oversized requests and responses" |
-| §9.3 `Connection: close` on error answers | conforms | `writeError` in `src/http-response.ts`; the `clientError` reply in `startServer` | untested |
-| duplicate header fields | conforms | raw headers walked in `startServer` (`headerCounts`), counts passed to policy; duplicated scalar header parameters → 400 (`contextFor` in `src/match.ts`), duplicated `Content-Type` → 400 (`checkRequest`), duplicate `X-Forwarded-For` ignored (`startServer` passes it only when the count is exactly 1), duplicate `X-Request-Id` not trusted (`startServer`, `safeRequestId`) | `test/http.test.ts` "header inputs are case insensitive and duplicate scalars fail" |
-| HTTP/1.0 requests | conforms | Node answers with `Connection: close`; probed | untested |
-
-## 8. RFC 3986 URI and percent-encoding
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| §2.1 `%HH` must be two hex digits, case-insensitive | conforms | `parseTarget`: `/%(?![0-9a-f]{2})/i` → 400; probed `/r%41` → decoded to `/rA` (404, i.e. accepted and decoded) | `test/http.test.ts` "malformed and ambiguous URL encodings fail before routing" (`/%ZZ`, `/ok?q=%`) |
-| §2.2 encoded delimiters keep their encoding (`%2F` is not `/`) | conforms (stricter) | `%2F` and `%5C` in the path are refused with 400 rather than kept encoded (`parseTarget`), so an encoded slash can never span a segment. Rationale: `docs/ROUTING.md` "Encoded slashes ... are rejected" | same test (`/%2f`, `/%5c`) |
-| decode exactly once | conforms | `decodeURIComponent` once on path and once on query in `parseTarget`; `%252F` stays `%2F` after one decode and is re-encoded into the redirect by `redirectLocation` (`encodeURIComponent`) | same test (`/a%252Fb` → `.../a%252Fb`) |
-| non-UTF-8 percent sequences | stricter than RFC 3986 | `/%ff` → 400 because `decodeURIComponent` requires UTF-8 (RFC 3987/WHATWG behavior); RFC 3986 itself permits arbitrary octets | same test (`/%ff`, `/ok?q=%ff`) |
-| §5.2.4 dot segments | deviates (deliberate) | `.` and `..` segments are refused with 400 (`parseTarget`) rather than removed by `remove_dot_segments`; `%2e` decodes to `.` and is refused the same way. Rationale: `docs/SPECIFICATION.md` "Routes" — no normalization so a route key means exactly one path | same test (`/..`, `/%2e`); `test/assets.test.ts` (`/assets/../urlcode.yaml`, `/assets/%2e%2e/urlcode.yaml` → 400) |
-| §3.3 empty path segments | conforms | `//` at the start refused (`parseTarget`, network-path ambiguity); internal empty segments only match a literal route containing them; `{param}` requires a non-empty segment (`matchRoute`) | `test/http.test.ts` (`//evil.example`) |
-| §3.4 query | conforms | split on the first `?` (`parseTarget`); parsed by `URLSearchParams`, which applies `application/x-www-form-urlencoded` rules (`+` = space), a WHATWG rule RFC 3986 does not define; the validity check in `parseTarget` mirrors it | "typed inputs, defaults, arrays, mapping and passthrough" |
-| §3.5 fragment never in a request target | conforms | `#` refused (`parseTarget`) | untested directly |
-| non-ASCII octets in the target | conforms | refused by Node's parser (probed raw `GET /caf\xe9` → 400) | untested |
-| route keys | conforms | `segments` in `src/router.ts` forbids `?#%\` and whitespace/controls in route patterns; ≤ 2048 chars, ≤ 32 segments | `test/config.test.ts` "semantic validation rejects ambiguous routes and unsafe redirects" |
-| redirect URL validation | conforms | absolute `http(s)`, no userinfo, placeholders only in path segments (`compileRoutes` redirect block in `src/router.ts`); single-component `encodeURIComponent` and the 16 KiB `Location` cap in `redirectLocation` | `test/http.test.ts` (`/p/hello%20world` → `.../hello%20world`); `test/config.test.ts` |
-
-## 9. RFC 7239 Forwarded and X-Forwarded-For
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| RFC 7239 `Forwarded` field | **not applicable** (not implemented) | no code reads `Forwarded`; only `x-forwarded-for` is read (`startServer` in `src/server.ts`, the request adapter in `src/vercel.ts`). `docs/SPIKE-EXTENSIONS.md` now states "RFC 7239 `Forwarded` is not parsed" | none |
-| `X-Forwarded-For` (de-facto, no RFC) trusted only from configured proxies | conforms to common practice | `resolveClient` in `src/client-address.ts`: peer must be in `--trusted-proxies`; walk from the right skipping trusted hops; all-trusted chain → leftmost; header ignored when absent or duplicated (`startServer` requires exactly one field) | `test/policies.test.ts` "client identity trusts forwarded headers only from configured proxies" |
-| malformed entries | conforms, documented | entries that are not a bare IP are skipped and the walk continues (`resolveClient` filters `normalizeAddress` misses); `normalizeAddress` strips a trailing `:port` from IPv4 entries and the brackets from `[v6]:port`, so RFC 7239-style `203.0.113.5:1234` resolves to `203.0.113.5`. The comment above `resolveClient` and `docs/POLICIES.md` now say "a malformed entry is skipped" | `test/standards.test.ts` "forwarded entries with ports and embedded IPv4 in IPv6 ranges resolve correctly"; `test/policies.test.ts` (`'garbage, 198.51.100.1'` → `198.51.100.1`) |
-| bracketed IPv6 and IPv4-mapped peers | conforms | `normalizeAddress` strips `[...]` and `::ffff:` | same test (`::ffff:10.1.2.3` peer) |
-| HSTS / origin never derived from `X-Forwarded-Proto`/`Host` | conforms | `onResponse` in `src/policies/security.ts` reads `request.origin`, which is the operator origin (`publicOrigin` in `startServer`) | `test/policy-security.test.ts` "HSTS follows the request origin scheme" (`x-forwarded-proto: https` does not enable it) |
-
-## 10. RFC 9309 robots.txt
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| Serving `robots.txt` | conforms | `robotsRoute` in `src/site.ts` generates `/robots.txt` from `site.robots` (bundled agent lists or paths; `User-agent:` / `Disallow:` / `Allow:` groups, an optional `Sitemap:` line when the public origin is known); a hand-written `/robots.txt` route takes precedence. The runtime never reads a `robots.txt` itself; the `agents` policy enforces the same lists for clients that ignore it (`docs/policies/agents.md` "robots.txt") | `test/site.test.ts` "every site key generates a native route with the expected body, type and cache policy" and "robots lists resolve through the bundled agent lists and skip non-token names" |
-
-## 11. RFC 6797 HSTS
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| §6.1 directive syntax `max-age=...; includeSubDomains` | conforms | `oshp` table in `src/policies/security.ts`: `max-age=31536000; includeSubDomains` | `test/policy-security.test.ts` "HSTS follows the request origin scheme" |
-| §7.2 MUST NOT send STS over non-secure transport | conforms | `onResponse` in `src/policies/security.ts` skips `strict-transport-security` unless `request.origin` starts with `https:`; never inferred from forwarded headers | same test (plain origin → absent; `x-forwarded-proto` ignored; `origin: https://...` → present) |
-| Worker | conforms | scheme from the request URL (`docs/policies/security.md` "Targets") | `test/policy-security.test.ts` "the Worker emits the same security headers as the self-hosted server" |
-
-## 12. RFC 1950/1952, RFC 7932, RFC 8878 content codings
-
-| Coding | Status | Behavior | Test |
-|---|---|---|---|
-| `gzip` (RFC 1952) | conforms | `codecs.gzip` in `src/policies/compression.ts` (`zlib.gzipSync`); dynamic level 6, stored 9 | `test/policy-compression.test.ts` "declared text responses compress per Accept-Encoding ..." (round-trips with `gunzipSync`) |
-| `deflate` = zlib container (RFC 1950 over RFC 1951), as RFC 9110 §8.4.1.1 defines the coding | conforms | `codecs.deflate` (`zlib.deflateSync`) produces the zlib format, not raw deflate | untested end to end (only `decode.deflate` is defined in the test) |
-| `br` (RFC 7932) | conforms | `codecs.br` (`zlib.brotliCompressSync` with `BROTLI_PARAM_QUALITY` and `BROTLI_PARAM_SIZE_HINT`); dynamic quality 4, stored 9 | same test (`brotliDecompressSync` round-trip) |
-| `zstd` (RFC 8878) | conforms when available | `codecs.zstd` (`zlib.zstdCompressSync`, dynamic 3, stored 12); `zstdAvailable` refuses it at activation (`compile`) when Node lacks it; available on the audited Node (probed) | "zstd is honoured only when node:zlib provides it; serverless targets delegate the policy" |
-| request-body decompression | not implemented (documented) | `checkRequest` in `src/http-policy.ts` → 415 for any non-identity `Content-Encoding`; `docs/HTTP.md` "no automatic decompression" | `test/http-policy.test.ts` "request body policies reject size, media, encoding ..." |
-| BREACH mitigation (not an RFC; CVE-2013-3587) | conforms to the documented rule | `onResponse` in `src/policies/compression.ts` skips when the route holds secrets or the response sets a cookie unless `allowWithSecrets` | "function JSON compresses with a weak ETag; Set-Cookie and secrets skip unless allowWithSecrets" |
-
-## 13. RFC 6265 Set-Cookie
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| §3 one `Set-Cookie` header per cookie, never folded | conforms | `prepareResponse` collects cookies separately (`cookies`) and `writeResponse` writes them as an array; YAML `Set-Cookie` is the only list-valued header (`compileHttp`); AWS format 2.0 `cookies` array (`src/aws.ts`) | `test/http.test.ts` "function Request/Response ABI, scoped bindings, cookies ..."; `test/aws.test.ts` "cookies arrive through the format 2.0 array and leave through it" |
-| §4.1.1 cookie syntax validation | partial | only the generic header rules apply (token name, no CTLs); no attribute parsing, signing or `Cookie` request parsing (`docs/HTTP.md` "Still outside this contract") | n/a |
-| cookies vs caching/compression | conforms | responses with `Set-Cookie` are never stored (`storable` in `onResponse`, `src/policies/cache.ts`) and not compressed by default (`onResponse` in `src/policies/compression.ts`) | `test/policy-cache.test.ts` "Set-Cookie, secret-bearing routes ..."; `test/policy-compression.test.ts` |
-
-## 14. RFC 6266 / RFC 8187 Content-Disposition
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| `attachment; filename=...; filename*=UTF-8''...` | conforms | `content-disposition@3.0.0` `create()` (imported as `disposition`) in `compileAssets`; filenames with separators or controls refused just before it | `test/assets.test.ts` "native page, download and static handlers ..." (`filename*=UTF-8''r%C3%A9sum%C3%A9.bin`) and "assets reject unsafe paths ... " (`bad\r\nname`) |
-
-## 15. IETF httpapi RateLimit header fields (Internet-Draft)
-
-The vocabulary is **draft-ietf-httpapi-ratelimit-headers**, an IETF
-Internet-Draft of the HTTPAPI working group. It is not an RFC; its field
-names and syntax have changed between revisions and may change again.
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| `RateLimit-Policy` as a Structured-Field list of items with `q` and `w` parameters | conforms to the current draft syntax | `headersFor` in `src/policies/throttle.ts`: `"default";q=<quota>;w=<window>` | `test/policy-throttle.test.ts` "quota reached answers 429 with Retry-After and RateLimit headers" (`'"default";q=2;w=60'`) |
-| `RateLimit` item with `r` (remaining) and `t` (seconds to reset) | conforms | `headersFor`: `"default";r=<remaining>;t=<reset>`; `t` from the sliding-window end (`observe`) | same test (`/^"default";r=1;t=\d+$/`) |
-| present on allowed and refused responses | conforms | `onRequest` attaches the budget to `state.pending`, `onResponse` writes it; refusals carry it directly (`withHeaders` in `onRequest`) | same test; `test/policies.test.ts` "... 405 carries policy headers" |
-| `pk` (partition key) parameter | not emitted | keys are internal (`keyFor`) | n/a |
-| refused requests not counted | conforms to the draft's guidance | `onRequest`: `entry.current++` only when not exceeded (or in `report` mode) | "window slides: the previous window fades out instead of resetting at once" |
-
-## 16. web-bot-auth drafts
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| HTTP Message Signatures for bots (IETF `web-bot-auth` drafts) | **not applicable** | named in `docs/policies/agents.md` ("Matching is string matching") as host-plugin territory; no code | none |
-
-## 17. OWASP Secure Headers Project
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| OSHP "best practices" values | conforms to the pinned table | `oshp` table in `src/policies/security.ts`, pinned as `oshpRevision = 'OSHP 2024 best practices'`; docs table generated from the same exported `profiles`; `X-Content-Type-Options: nosniff` supplied by the runtime on every response (`prepareResponse`, `errorResponse`) rather than the profile. The upstream JSON could not be fetched from the audit environment (proxy 403), so the table is verified against the code and docs, not re-verified against owasp.org | `test/policy-security.test.ts` "profile tables are frozen, ordered and consistent with each other", "profile headers land on redirects, declared responses and function results; existing headers win" |
-| fill-gaps semantics; `set`/`unset` | conforms | `compile` (`unset`, `set`, `overrideKeys`) and `onResponse` in `src/policies/security.ts` | "set overrides the profile and existing headers; unset drops a profile header" |
-| applied to errors and early denials | conforms | `Runtime.errorHeaders` and `finishPolicies` in `src/runtime.ts`; `errorResponse` merges the resolved policy headers after its fixed set | `test/policies.test.ts` "error responses carry the security headers of the matched route or the project"; `test/policy-security.test.ts` "early results that skip the handler still carry the profile" |
-| `X-Frame-Options` (RFC 7034, informational) `deny` | conforms | `oshp` table entry `x-frame-options: deny` | as above |
-
-## 18. Content Security Policy Level 3
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| CSP3 serialized policy syntax | conforms | `default-src 'self'; form-action 'self'; object-src 'none'; frame-ancestors 'none'; upgrade-insecure-requests; block-all-mixed-content` (`oshp` table, `content-security-policy`) | `test/policy-security.test.ts` (value equality with the frozen table) |
-| `block-all-mixed-content` | partial | this directive is obsolete in CSP3 / the current Mixed Content specification and is ignored by current browsers; it is emitted because OSHP recommends it. Harmless, but not a Level 3 directive | n/a |
-| `upgrade-insecure-requests` | conforms | defined by the W3C Upgrade Insecure Requests specification, delivered through CSP; emitted regardless of scheme (browsers ignore it on plain HTTP) | n/a |
-| Report-only and `report-to` | conforms (operator-supplied) | any `Content-Security-Policy-Report-Only` value is passed verbatim through `set` (`docs/policies/security.md`); the runtime does not host a reporting endpoint | "set overrides the profile ..." |
-
-## 19. JSON Schema 2020-12
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| project schema dialect | conforms | `schemas/urlcode.schema.json` `$schema: https://json-schema.org/draft/2020-12/schema`; compiled by `ajv/dist/2020.js` (Ajv 8.20.0, `package.json` dependencies) as `validate` in `src/config.ts` with `strict: true`, `strictRequired: false`, `allowUnionTypes: true`, `allErrors: false` | `test/config.test.ts` "strict schema rejects unknown features and multiple handlers"; `test/policies.test.ts` "policies validate in YAML and unknown keys fail" |
-| input parameter schemas (subset: `type`, `enum`, `default`, `minLength`/`maxLength`, `minimum`/`maximum`, `items`, `maxItems`) | conforms | `inputValidator` in `src/router.ts` compiles each distinct schema with Ajv 2020 (`strict: false`, `allErrors: false` in `compileRoutes`); `default` is stripped before compiling because 2020-12 treats it as an annotation; semantic cross-checks in the `parameters` loop of `compileRoutes`; unsupported keywords (`pattern`, `format`, nested objects) are refused by the project schema, not silently ignored | `test/http.test.ts` "typed inputs, defaults, arrays, mapping and passthrough" |
-| standalone validators for the Worker | conforms | precompiled by the build into ES modules (`docs/CLOUDFLARE.md` "validators.js") | `test/cloudflare.test.ts` "the generated Worker entry and validators carry no imports the platform cannot resolve" |
-| bounded compilation | conforms | ≤ 1024 distinct schemas per snapshot (`inputValidator`) | untested |
-
-## 20. YAML 1.2
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| YAML 1.2 core schema, JSON-compatible profile | conforms | `yaml@2.9.1` (`package.json` dependencies); `parseYaml` in `src/config.ts` calls `parseDocument(text, { version: '1.2', uniqueKeys: false, strict: true })`; parser errors and warnings fail | `test/config.test.ts` "YAML rejects ambiguity and nonportable constructs" |
-| no aliases, anchors, tags, merge keys, multiple documents | conforms (deliberate subset) | `parseYaml`: the `visit` callback refuses aliases, anchors and tags; `inspect` refuses `<<` and prototype keys; multi-document rejected by the parser in strict mode; `toJS({ maxAliasCount: 0 })` | same test (`&x`/`*x`, `!custom`, `!!str`, `---`, `<<`) |
-| string keys only, unique keys | conforms | the linear duplicate check over `node.items` in `parseYaml` (comment: "Our string-only profile permits equivalent linear duplicate detection") | same test (`x: 1\nx: 2`) |
-| scalars: string, finite number, boolean, null | conforms | `parseYaml`: the scalar check in `visit` and the `Number.isFinite` check in `inspect` (`.inf`/`.nan` refused) | same test (`.inf`, `.NaN`) |
-| YAML 1.2 boolean semantics (`yes`/`no` are strings) | conforms | follows from `version: '1.2'` | untested |
-| resource bounds | conforms | `MAX_CONFIG_BYTES` (32 MiB per file), `MAX_PROJECT_CONFIG_BYTES` (64 MiB aggregate, enforced by `readConfig`), 40 nesting levels (`inspect`), and `loadDocument` runs the parse in a worker with `resourceLimits` and a `timeoutMs` deadline (`src/config.ts`) | "configuration worker deadline terminates loading and releases admission"; "configuration worker enforces aggregate source budget across includes" |
-
-## 21. CIDR notation for `--trusted-proxies`
-
-| Requirement | Status | Behavior | Test |
-|---|---|---|---|
-| `address[/prefix]` for IPv4 and IPv6 (RFC 4632 / RFC 4291 §2.3 notation) | conforms | `parseCidr` in `src/client-address.ts`; prefix defaults to the full length; prefix range checked; `compileTrustedProxies` accepts a comma-separated string or array, ≤ 256 ranges | `test/policies.test.ts` "client identity trusts forwarded headers only from configured proxies" (`10.0.0.0/8, ::1, 192.168.1.5`; `/33` refused) |
-| host bits set beyond the prefix | lenient | `10.1.2.3/8` accepted and masked at match time (`within`); probed | untested |
-| IPv4-mapped IPv6 (`::ffff:a.b.c.d`) | conforms | `toBytes` and `normalizeAddress` special-case `::ffff:` | same test (`::ffff:10.1.2.3`) |
-| other IPv4-embedded IPv6 forms (`64:ff9b::1.2.3.4`, RFC 4291 §2.2 form 3) | conforms | `toBytes` converts a trailing dotted quad into two 16-bit groups before splitting on `:` | `test/standards.test.ts` "forwarded entries with ports and embedded IPv4 in IPv6 ranges resolve correctly" (`parseCidr('64:ff9b::1.2.3.4/96')` bytes) |
-| zone identifiers (`fe80::1%eth0`) | accidental | `net.isIP` accepts them (probed → 6); `parseInt('1%eth0', 16)` in `toBytes` yields `1`, so the zone is silently ignored | untested |
-
-## Gaps, ranked
-
-Closed since the first pass (rows above flipped to conforms): HEAD
-`Content-Length` on `respond`, function and middleware results (RFC 9110
-§8.6); 431 for oversized header fields (RFC 6585 §5); absolute-form request
-targets (RFC 9112 §3.2.2); 414 for over-long targets (RFC 9112 §3);
-`X-Forwarded-For` entries with a port and the "malformed entry" wording in the
-docs; IPv4-embedded IPv6 CIDRs other than `::ffff:`.
-
-1. **408 collapsed into 400** (RFC 9110 §15.5.9; §1). Fix: in the `clientError` handler of `startServer` (`src/server.ts`) branch on `error.code === 'ERR_HTTP_REQUEST_TIMEOUT'` → `408`, keeping `Connection: close` and `Content-Length: 0`. Test: a raw-socket request head left incomplete past `headersTimeout` in `test/standards.test.ts`.
-2. **asterisk-form request target answered 400** (RFC 9112 §3.2.4; §7). Fix: in `originForm` or `startServer` answer `OPTIONS *` with 405 + `Allow`, or leave as 400 and state it. Test: `test/standards.test.ts` already asserts the current 400; flip it with the fix.
-3. **origin memory cache ignores request `Cache-Control: no-cache` / `max-age=0`** (RFC 9111 §5.2.1; §2). Either document it explicitly in `docs/policies/cache.md` "Origin memory cache" ("request cache directives are not honored: the store is part of the origin"), or add `cache-control` to the `conditional` bypass list in `src/policies/cache.ts` when it contains `no-cache` or `no-store`. Test: add a request with `cache-control: no-cache` to `test/policy-cache.test.ts` "swr serves fresh from the origin cache ..." asserting the chosen behavior.
-4. **`stale-if-error` is header-only** (RFC 5861 §4; §3): documented; `onError` in `src/policies/cache.ts` could return `served(entry, age)` when an entry exists within `staleIfError` — `Runtime.handle` already accepts a fallback from an error hook. Test: a function that throws after a first successful fill.
-5. **Untested conformance points** that hold today but have no guard: 304 omits `Content-Length` (assets and `revalidate`); `deflate` end-to-end round-trip; missing `Host` → 400; CL+TE → 400; `Connection: close` on error answers; YAML 1.2 `yes`/`no` as strings; ≤ 1024 input schemas. Each is one assertion in the test named in its row.
-6. **`block-all-mixed-content`** in the OSHP CSP (§18): obsolete but harmless; keep while the pinned OSHP revision recommends it, and note it in `docs/policies/security.md` next to the CSP paragraph.
-
-## Factual errors in existing documentation
-
-All four errors found in the first pass are corrected at `8d7dd01`:
-
-- `docs/policies/agents.md` "robots.txt" no longer carries a `respond` recipe with `headers:`; it points at `site.robots`, which generates the file.
-- `docs/policies/compression.md` "ETag and HEAD": "reports the identity length" is now true (`prepareResponse` measures the body before dropping it).
-- `docs/POLICIES.md` and the comment above `resolveClient` say "a malformed entry is skipped".
-- `docs/SPIKE-EXTENSIONS.md` says "RFC 7239 `Forwarded` is not parsed".
-
-## How to keep this current
-
-- Any change to `src/http-response.ts` (what a response *is*) must extend `test/http-policy.test.ts` "declarative text, JSON and empty responses ..." and rerun the parity tests (`test/aws.test.ts` "a Lambda response carries exactly ...", `test/cloudflare.test.ts` "the Worker runtime answers exactly ..."), then update §1 here.
-- Any change to `parseTarget` in `src/match.ts`, `originForm` in `src/server.ts` or `segments` in `src/router.ts` must extend `test/http.test.ts` "malformed and ambiguous URL encodings fail before routing" or `test/standards.test.ts`, and update §7–§8.
-- Any change to `assetResponse` in `src/assets.ts` (conditional or range logic) must extend `test/assets.test.ts` "asset conditions, byte ranges, empty files and HEAD obey HTTP ordering" and update §1 (validators, ranges).
-- A new cache strategy or directive touches the `switch (strategy)` in `compile` (`src/policies/cache.ts`) and `test/policy-cache.test.ts` "each strategy emits its catalogue headers"; update §2–§5.
-- A new content coding touches the `codecs` table in `src/policies/compression.ts` and `test/policy-compression.test.ts` (round-trip decode table at the top of the file); update §12.
-- A change to the OSHP table bumps `oshpRevision` in `src/policies/security.ts`, regenerates the docs table, and must keep `test/policy-security.test.ts` "profile tables are frozen, ordered and consistent" passing; update §17–§18.
-- A change to the RateLimit field syntax (when the draft moves) touches `headersFor` in `src/policies/throttle.ts` and the header regexes in `test/policy-throttle.test.ts`; update §15 with the draft revision.
-- A change to `--trusted-proxies` parsing touches `src/client-address.ts`, `test/policies.test.ts` "client identity trusts forwarded headers only from configured proxies" and `test/standards.test.ts`; update §9 and §21.
-- A change to the YAML profile or schema dialect touches `parseYaml` and `validate` in `src/config.ts`, `test/config.test.ts` "YAML rejects ambiguity ..." and "strict schema rejects unknown features ..."; update §19–§20.
-- When a gap above is closed, delete its row from the ranked list and flip the row status in the table; when a new standard is touched, add a section with the same four columns (requirement, status, behavior citing the symbol, test name). Cite functions and constants, not line numbers: a symbol is checkable with `grep` after the file changes around it.

package/docs/STARTERS.md

@@ -1,83 +0,0 @@
-# One starter, two examples
-
-There is one starting project: a URL that runs a function and a regular redirect.
-No `dynamic` versus `redirects` choice, and no `--template` option.
-
-With URLCode installed:
-
-```sh
-urlcode init ../my-links
-urlcode dev --project ../my-links
-urlcode audit --project ../my-links --expect-routes 2
-```
-
-Or use the public GitHub template, which includes a pinned runtime dependency:
-
-```sh
-git clone https://github.com/jimhoyd-com/urlcode-template.git my-links
-cd my-links
-npm ci
-npm run dev
-npm run audit
-```
-
-GitHub's **Use this template** button creates your own repository directly.
-These are two ways to obtain the same route examples, not two project types.
-The CLI copies app files from `starters/default` and uses the installed runtime;
-the public repository adds npm dependency/lockfile/CI for independent installation.
-Neither path forks the runtime or needs a hosting account or database.
-
-## Files and growth
-
-`urlcode.yaml` includes a function route file and a redirect file in a nested
-folder. A JavaScript function, HTTP assertions and optional Makefile are included,
-plus `.github/workflows/urlcode.yml`, which runs the [project checks action](CI.md)
-on every push and pull request once the project is on GitHub.
-See [organization](ORGANIZATION.md) for choosing your own layout. Defaults allow
-GET/HEAD and use redirect 302; add configuration only when changing behavior.
-
-`urlcode init` writes no `package.json`: the route project is route-only, and its
-runtime may be installed globally, in a parent workspace or in a container. Add
-`--manifest` to also write one pinning the runtime at exactly the version that
-generated the project, then run `npm install` in it yourself to install that
-version and produce a lockfile. The CLI never runs a package manager, and no
-upgrade command exists — a pinned version changes when you edit the manifest.
-
-Initialization refuses an existing destination. Own the app in your own repository,
-keep secrets out of Git, and upgrade the runtime separately without regenerating
-application files. Add pages, downloads, more functions and business-specific
-features to this same project. Update tests and the expected route count as it grows.
-See [readiness](READINESS.md) and [security](FUNCTION-SECURITY.md).
-
-To start an extended site instead, install the compatible core, UI, auth and
-admin set from npm in the directory you run from; the
-[framework guide](FRAMEWORK.md#the-composition-contract) provides the exact
-`0.4.1` command to use after publication. Pass UI first so its kit activates
-before auth: `urlcode init ../my-site --with ui,auth,admin` writes the same starter under `my-site/app/`, merges each package's
-routes and declarations into it, and generates one `host.mjs` and README beside
-it, plus a `package.json` pinning the runtime, those packages and their declared
-peers at the versions it just resolved, validated together against every declared
-peer range. Installing them is your explicit `npm install` in that directory.
-The contract each package fulfils is in [extensions](EXTENSIONS.md#scaffolding-with-init---with),
-with `--no-manifest` and `--pin` in [recorded versions](EXTENSIONS.md#recorded-versions).
-
-Both paths carry an `AGENTS.md` for repository-aware assistants. `urlcode init`
-generates it from the installed runtime's capability catalog (the same source as
-`urlcode capabilities`), so it names only the handlers, policies and site keys
-that version implements, plus the exact `validate`, `test` and `audit` commands
-with the starter's route count. The committed copy in `starters/default` is
-regenerated from the same function and a test keeps the two identical. The file
-points at the agent skill the package ships at `skills/urlcode/SKILL.md`.
-Both paths also write `.mcp.json`, which registers the read-only `urlcode mcp`
-server for Claude Code and Codex (`--project app` for an extended site); it is
-never overwritten and carries no `--allow-authoring` ([tooling](TOOLING.md#registering-the-server)).
-
-`examples/assets` contains a larger runnable file/page/download demonstration:
-`make dev PROJECT=examples/assets`. It is an example, not a separate init choice.
-
-The old `starter-dynamic` and `starter-redirects` branches are historical snapshots;
-use `urlcode-template` for new clones. They are no longer maintained or advertised
-as onboarding paths. Existing projects remain ordinary valid URLCode apps.
-
-The runtime is licensed under Apache-2.0. Provider adapters follow the
-[roadmap](../ROADMAP.md).

package/docs/STATIC.md

@@ -1,105 +0,0 @@
-# Deploying to static hosting (S3 + CloudFront)
-
-The `static` target is the bottom rung of the [capability
-ladder](FRAMEWORK.md#the-ladder):
-the same `urlcode.yaml` a self-hosted server or a serverless adapter runs, with
-no server process at all. `urlcode build --target static` compiles a project
-ahead of time into plain files and two small JSON manifests meant for an S3
-bucket served through CloudFront — nothing here executes a request.
-
-```sh
-urlcode build --target static --project . --out dist --origin https://links.example
-```
-
-## Declarative routes only, and less than that
-
-This target serves **redirects**, **declared responses** (`respond:`) and
-static files (`page`, `static`, `download`) — no path parameters, no query
-passthrough or mapping, both GET and HEAD required, `respond.status: 200` only, and no `enabled: false` or `expires`
-(there is no server to answer a disabled or expired route with 404/410, so the
-build refuses one instead of silently serving it forever). Everything else is
-refused **at build time**, with the route pattern and the reason named:
-
-| Handler / feature | Why it is refused |
-| --- | --- |
-| `function`, `middleware` | no server, so no dynamic or sandboxed execution |
-| `extension`, `policies.extensions` | no server, so no operator extension registry |
-| `proxy`, `signals` | no server, so no bounded or fire-and-forget egress |
-| `conditional`, `match` (`conditions`) | no server, so no request-time condition matching |
-| `parameters`, `request.body` | no server, so no request-time validation |
-| `response.headers` | no server, so no per-request headers; set them as S3 object metadata or a CloudFront response headers policy instead |
-| `env`, `secrets` (`bindings`) | no server, so no per-request binding resolution |
-| every `policies.*` | no server, so no runtime policy enforcement |
-| a redirect with a `{parameter}` in its path | S3's per-object redirect is keyed to one exact object, not a pattern |
-| a redirect with `query.pass`/`query.map` | S3's per-object redirect cannot compute a target per request |
-| a redirect with a `status` other than 301 | S3's per-object website redirect always answers 301 |
-| a route not admitting both GET and HEAD, or admitting other methods | the output cannot enforce a different method set |
-| `respond.status` other than 200 | an uploaded response object cannot preserve a custom HTTP status |
-| a route with `enabled: false` or `expires` | no server to answer a disabled/expired route; remove the route instead |
-
-Run `urlcode capabilities --target static` for the full catalog.
-
-## What the build emits
-
-`--out` (default `dist/static`) receives:
-
-- `objects/<key>` — the actual files to upload, one per served route. A `page`
-  or `download` route becomes one file; a `static` mount becomes one file per
-  entry in its directory. Object keys match the S3 convention: the route
-  pattern with its leading `/` stripped, and `/` itself becomes `index.html`
-  (matching a bucket's own "Index document" setting). A redirect route also
-  gets a zero-byte placeholder object at its key, so it exists to carry
-  metadata.
-- `objects.json` — `{ format, objects: [{ key, contentType, cacheControl?,
-  contentDisposition? }] }`. Plain file upload loses this metadata (S3 does not
-  reliably infer content type or cache headers from an extension-less key), so
-  a deploy step reads this file and sets each object's own `Content-Type`,
-  `Cache-Control` and `Content-Disposition` from it, for example with
-  `aws s3 cp --content-type ... --cache-control ...` per entry, or an
-  equivalent `aws s3 sync` post-processing step.
-- `redirects.json` — `{ format, redirects: [{ key, location, status: 301 }] }`.
-  Each entry is applied as the S3 object's
-  [website redirect location](https://docs.aws.amazon.com/AmazonS3/latest/userguide/how-to-page-redirect.html)
-  metadata (`x-amz-website-redirect-location`), for example
-  `aws s3api put-object --website-redirect-location <location> --bucket ... --key <key>`.
-  S3 always answers a request for that key with a 301 to `location`
-  regardless of the object's own content — this is why a declared `status`
-  other than 301 is refused rather than silently downgraded.
-- `manifest.json` — the same project-level semantic manifest every target
-  writes (see [tooling](TOOLING.md)).
-
-None of these are edited by hand, and `dist/` belongs in `.gitignore`. This
-target ships no runtime import (there is nothing to run), so there is no
-`@jimhoyd/urlcode/static` entry point — the build output is the deployment.
-
-## What this is not: GitHub Pages
-
-**This target's claimed support is S3 + CloudFront, not GitHub Pages.**
-GitHub Pages has no per-object redirect metadata and no server-side rewrite
-layer, so a `redirect` route compiled the way this target compiles it (S3
-object metadata) has no equivalent there — the only options are a
-meta-refresh/JavaScript page (visibly a redirect, not an HTTP one: search
-engines, curl and anything that does not run JavaScript sees the source page,
-not a 3xx) or a static 404-page trick, both lower fidelity than what every
-other target in this project does for the same route. Rather than claim a
-portability promise this platform cannot keep, GitHub Pages is out of scope
-for this target. If you need Pages, treat it as a distinct target with its own
-explicit fidelity caveat, not a rename of this one.
-
-## Verification status
-
-This target has local build tests only (`test/static.test.ts`): the compiled
-object layout, the redirect manifest, and every refusal above. **It has not
-been deployed to S3 or fronted by CloudFront.** Bucket policy, CloudFront
-caching behavior, TLS/domain setup and the exact `aws s3` invocations above are
-unverified until a real deployment exercises them.
-
-
-## Building pages with middleware
-
-Use [prerendering](PRERENDER.md) to execute functions and native middleware at
-build time, then export the generated native page routes with this target.
-Trusted Node execution is the build default; `sandbox: true` retains its
-restricted imports and resource limits. Neither mode adds a request-time server
-to the static output. Authentication, request-dependent headers and other
-per-request middleware cannot be baked into a public file safely.