@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/docs/POLICIES.md

@@ -40,7 +40,22 @@ routes:
 ```
 
 `policies` at the top level sets project defaults; `routes.<path>.policies`
-adjusts them for one route. Both accept the same keys: `profile` plus one entry
+adjusts them for one route. Two route-level short forms exist. `auth`
+expands to `policies.extensions.auth` when the project declares an auth
+[extension](EXTENSIONS.md). `cache: {strategy, maxAge, ...}` expands to
+`policies.cache` the same way — the compiler merges it into that route's
+`policies` before anything else reads the project, so `routes`, `audit` and
+`explain` see only the expanded long form, and it is refused alongside a
+direct `policies.cache` on the same route (use one form):
+
+```yaml
+routes:
+  /feed:
+    function: { source: functions/feed.mjs }
+    cache: { strategy: swr, maxAge: 30 }   # expands to policies: { cache: {...} }
+```
+
+Both accept the same keys: `profile` plus one entry
 per policy, each either an object or `false`. Unknown keys fail validation, as
 everywhere in the project format. The
 [field reference](YAML-REFERENCE.md) lists every accepted field with its
@@ -178,312 +193,11 @@ When any policy is declared anywhere in the project, every route is compiled
 against the effective table; a route with nothing effective simply has empty
 chains. When none is declared, no policy code runs.
 
-## The built-in `hardened` profile
-
-`policies.profile: hardened` expands to the following and nothing else, so it
-can be read in one place and overridden key by key. This is
-`builtinProfiles.hardened` in `src/policies.ts`:
-
-```yaml
-policies:
-  security: { headers: oshp }
-  agents: { deny: [ai-crawlers], status: 403 }
-  throttle: { quota: 120, window: 60, partition: client, status: 429 }
-  compression: { encodings: [br, gzip], minBytes: 1024 }
-  cache: { strategy: revalidate }
-```
-
-The numbers are starting points chosen to be safe for a single small instance;
-they are not tuned for any workload and not a security assessment of your
-deployment. Note what the profile implies per target: on Vercel and AWS it
-refuses activation as written, because `throttle.partition: client` is
-refused there; set `throttle: false` (or `partition: route`) at the project
-or route level. `compression` is delegated to the platform. On Cloudflare
-only `agents` and `security` survive and `compression` is delegated, so the
-profile must also drop `throttle` and `cache` there.
-There is no `strict` profile: anything stricter is a per-project decision.
-
-## The policy contract in TypeScript
-
-The policies are modules of one shape, `PolicyModule<Config, State>` in
-`src/types.ts`: `targets`, `compile`, `onRequest`, `onResponse`, optional
-`onError`, `describe` and `close`. `@jimhoyd/urlcode/policies` exports that type with
-`PolicyRequest`, `PolicyContext`, `PolicyChain`, `PolicyShared` and
-`PolicyRegistry` (the five built-ins keyed by name), and the declarations ship
-with the package. A per-policy configuration is typed as the YAML it accepts,
-and a `profiles` layer may hold a partial one:
-
-```ts
-import { registry, targets, type PolicyRegistry, type PolicyRequest } from '@jimhoyd/urlcode/policies';
-
-const throttle: PolicyRegistry['throttle'] = registry.throttle;   // PolicyModule<ThrottleConfig, ThrottleState>
-const support = throttle.targets({ quota: 120, window: 60, partition: 'client', status: 429 });  // per-target support for this config
-console.log(support.vercel, support.cloudflare);
-function inspect(request: PolicyRequest): void { console.log(request.route, request.client, targets); }
-```
+## Further pages
 
-The registry is read-only: a project cannot add a policy from YAML, and an
-operator adds behavior through [plugins](PLUGINS.md), not by editing it.
-
-## Supplying your own patterns
-
-The runtime ships mechanisms and one named profile, not an opinion about who
-should be blocked. Ways to express your own:
-
-- **Custom profiles.** Define any number under `profiles` and select one per
-  project or per route. Profiles are plain data and travel with the YAML.
-- **Per-route overrides.** Any key can be tightened, replaced or set to
-  `false` on a route.
-- **Own agent lists.** `agents.deny` and `agents.allow` accept bundled list
-  names and project-relative `.json` files in the same schema, so a list you
-  do not want to redistribute stays yours. `denyPatterns`/`allowPatterns`
-  take a bounded, linear-time pattern subset. See [agents](policies/agents.md).
-- **Header by header.** `security.set` adds or overrides a header and wins over
-  the profile, YAML `response.headers` and handler output; `security.unset`
-  drops one the profile would emit. Headers the runtime or a handler owns
-  (`content-type`, `cache-control`, `set-cookie`, `etag`, `location`, and the
-  rest listed in `src/policies/security.ts`) cannot be `set`.
-  See [security](policies/security.md).
-- **Explicit cache fields.** A strategy sets defaults; `maxAge`,
-  `staleWhileRevalidate`, `staleIfError`, `cdnMaxAge`, `originTtl`, `vary`,
-  `statuses`, `maxBytes` and `maxEntries` override what it implies.
-  See [cache](policies/cache.md).
-- **Plugins.** Verified-bot checks, shared-store throttling, purge endpoints
-  and anything vendor-specific are host code an operator passes in;
-  see [plugins](PLUGINS.md).
-
-## Client identity and `--trusted-proxies`
-
-`throttle` partitions by `client`. On the self-hosted server the client is the
-socket peer unless `urlcode serve --trusted-proxies 10.0.0.0/8,fd00::/8`
-names the addresses allowed to speak for a client. Then `X-Forwarded-For` is
-walked from the right, skipping trusted hops, and the first untrusted address is
-the client; a chain made only of trusted proxies yields its leftmost entry, and
-a malformed entry is skipped. A forwarded header from a peer
-outside the trusted set is ignored, as is a request carrying more than one
-`X-Forwarded-For` field. Ranges are IPv4 or IPv6 CIDRs (at most 256);
-IPv4-mapped IPv6 peers match IPv4 ranges. `startServer({ trustedProxies })`
-takes the same list.
-
-A request whose client cannot be resolved (an adapter without a peer, an
-embedding caller that passes none) shares one bucket rather than being exempt,
-so a misconfigured proxy fails closed. The throttle summary in
-`testPlan().policies` records this as `unresolvedClient: "shared key"`. The runtime still
-never trusts forwarded headers for its public origin; set `--origin`
-explicitly, as [resilience](RESILIENCE.md) already requires.
-
-## What `routes` and `audit` report
-
-`urlcode routes` prints the inventory with a `policies` array per route naming
-the policies effective on it (`testPlan().inventory[].policies`) and the full
-`policies` map. The embedding API and a plugin's `onActivate` see
-`testPlan().policies`, a map from route pattern to each policy's summary with
-its `target` value (`native`, `compiled` or `delegated`), the per-route
-capability table the portability rule calls for. `urlcode audit` prints the
-same table under `policies` and, with `--compliance`, checks the declared
-configuration against standards-referenced rules; see
-[compliance](COMPLIANCE.md). `urlcode doctor` lists the policy names this
-runtime knows.
-
-## Logging
-
-Policies log through the runtime's request log with one-line events:
-`{ event: 'throttle', route, outcome: 'exceeded' | 'allowed', remaining }`,
-`{ event: 'agents', route, list, outcome: 'denied' | 'reported' }` and the
-cache events described on the [cache page](policies/cache.md). Events name the
-configured route pattern and the list or strategy, never a client address, a
-User-Agent string or request text. A logging failure never changes a response.
-
-## Hardened configuration guidance
-
-Advice, not defaults, condensed from the spike's section 6.
-
-1. **Network and edge first.** Volumetric protection, TLS termination and
-   per-client connection budgets stay with the provider or the reverse proxy.
-   Runtime policies are a second layer, never the first.
-2. **Ingress to origin.** Bind privately; allow only the proxy's addresses;
-   pass `--trusted-proxies` so `client` partitioning sees the real peer.
-3. **Request policies.** Agents before throttle: denials are cheaper than
-   counting. Start throttle in `mode: report` for a release to see real
-   quotas in the headers and logs, then switch to `enforce`.
-4. **Allow before deny.** Keep an explicit allow for the crawlers you need
-   indexed; a broad deny without one is the common self-inflicted outage.
-5. **Route contract.** Exact methods, `request.body` limits and `expires` on
-   campaign routes still do most of the work.
-6. **Response policies.** Security headers on every route; compression only
-   on listed types and never on secret-bearing responses (the BREACH class of
-   attack, which is why compression is skipped where a route declares secrets
-   unless `allowWithSecrets` says otherwise); caching only with a strategy
-   whose semantics you can state, `immutable` only on content-hashed paths,
-   `no-store` everywhere else.
-7. **Lists as pinned data.** Bundled agent lists ship with the release, so a
-   rollback rolls the list back too.
-8. **Read the table.** Check `urlcode routes` on each target you deploy to;
-   the same YAML is refused where it cannot be enforced, and that is the
-   point.
-
-## Interoperability
-
-Every pair of policies, and every policy against the runtime's own responses,
-was reviewed by reading the code and by exercising a server. The rules below
-are the ones the current code enforces; where a combination misbehaves, the
-rule says so and names what to do instead.
-
-### Cannot coexist
-
-Hard conflicts: the runtime refuses activation, or the combination produces
-a wrong answer today.
-
-- **Origin cache and conditional or range requests.** A request carrying
-  `If-None-Match`, `If-Modified-Since`, `If-Match`, `If-Unmodified-Since` or
-  `Range` is never answered from the origin cache: a stored entry is a full
-  `200` representation and the handler owns validators and ranges, so such
-  requests always reach it and get the handler's `304`, `412` or `206`.
-  Unconditional requests are served from the entry.
-- **`security.unset` and a route that switches profile.** `unset` is
-  validated against the profile in effect on that route. A project-level
-  `unset` merges into a route that names a profile without that header
-  (`headers: off`, or `oshp-no-csp` with `unset: [Content-Security-Policy]`)
-  and activation fails with `unset names "...", which the off profile does
-  not emit`. Write `unset: []` on that route: a route key replaces the whole
-  array.
-- **`security.set` of `Cache-Control`, `Content-Encoding`, `ETag`,
-  `Content-Type`, `Set-Cookie`, `Location` and the other reserved names** is
-  refused at activation (`is owned by the runtime or handler`). `Vary`,
-  `RateLimit`, `RateLimit-Policy`, `Retry-After` and `Age` are reserved for
-  the same reason: the cache and throttle policies own them, and a `set` of
-  any of the five is refused at activation with the route named. Declare
-  `vary` on the cache policy instead.
-- **`agents.denyEmpty`, `throttle` and the generated probes.** `urlcode
-  audit`, `urlcode test` and `urlcode benchmark` send generated probes as
-  `Mozilla/5.0 (compatible; RouteProbe/0.1)`,
-  so `denyEmpty` does not fail them; a deny pattern that matches that string
-  would. A tight `throttle` fails an audit once the probes exceed `quota`
-  (the audit runs from one address, so a `static` tree with more files than
-  the quota trips it): keep the quota at least the number of generated cases
-  or run the audit in `mode: report`.
-- **`hardened` on Vercel and AWS** is refused as written, because
-  `throttle.partition: client` cannot be honoured there; **on Cloudflare**
-  the build refuses `throttle` and `cache`. Override the offending keys with
-  `false` or `partition: route` as the profile section above describes.
-- **`compression.encodings: [zstd]` on a Node without `zlib.zstdCompressSync`**
-  fails activation with the route named rather than serving identity.
-
-### Coexist with defined precedence
-
-Pairs that work, with the rule the code applies.
-
-- **Request order is `agents`, `throttle`, cache lookup.** A denied agent is
-  never counted and never looked up; a throttled request is never looked up.
-  An agent on an `allow` list passes `agents` and is still throttled. An
-  `agents` denial and a `throttle` refusal both pass through the cache
-  policy's response hook (they carry no flight, so nothing is stored) and
-  pick up its declared `vary` names, then security headers, then
-  `Vary: Accept-Encoding` from compression; their bodies are below `minBytes`
-  so they are never encoded.
-- **Cache hit and the response phase.** A hit skips only the cache's own
-  response hook: it still carries the client's `RateLimit` headers (the
-  request was counted), the security profile, and is compressed on the way
-  out. Stored entries are the handler's bytes and headers after YAML
-  `response.headers` and the cache policy ran, before throttle, security and
-  compression: bodies are stored uncompressed and encoded again on every hit,
-  and a `RateLimit` value is never stored. A cache hit on an asset serves the
-  same snapshot buffer, so a precompressed variant is used for `GET` and
-  reported at the variant's length for `HEAD`, exactly as when uncached.
-- **Cache `Vary` and compression `Vary`.** The cache merges its declared
-  `vary` names first; compression appends `Accept-Encoding` without
-  duplicating it and leaves a `Vary: *` alone. The origin key uses only the
-  cache's names: because bodies are stored uncompressed, `Accept-Encoding` is
-  not part of the key and need not be.
-- **ETags across `cache` and `compression`.** `revalidate` keeps a handler or
-  asset `ETag` and computes a strong SHA-256 tag for a `200` without one.
-  Compression then weakens a dynamically encoded body's tag (`W/"..."`) and
-  suffixes a precompressed asset's (`"...-gz"`). Revalidation works in every
-  combination: the cache's `304` compares weakly, the asset handler compares
-  weakly against the identity tag, and compression answers `304` for a
-  suffixed tag it produced. The `304` that `revalidate` produces keeps
-  `Content-Type`, so compression adds `Vary: Accept-Encoding` to it as it
-  does to the asset handler's own `304`.
-- **Who owns `Cache-Control`.** YAML `response.headers` first, then an asset
-  handler's `cacheControl` when the cache policy is only inherited, then a
-  handler's `private` or `no-store`, then the strategy; `security.set` cannot
-  name it. A `no-store` or `private` handler answer is never stored whatever
-  the strategy says.
-- **Security headers and everything else.** Profile headers fill gaps only:
-  YAML `response.headers`, function, asset, redirect and early-denial headers
-  keep their values. `set` overrides all of them. `Strict-Transport-Security`
-  needs an `https` origin. The profile is applied on cache hits and on early
-  denials (including a plugin short-circuit), on the self-hosted server and
-  in the Worker alike.
-- **Compression and secrets or cookies.** A route with `secrets` or a
-  response with `Set-Cookie` is sent as identity (still with `Vary`) unless
-  `allowWithSecrets: true`. A route with `secrets` also never enters the
-  origin cache, so the two policies agree on what a secret-bearing route is.
-- **Throttle and the 405.** The request phase runs before the method check,
-  so a request that ends as `405` was counted, and the `405` passes through
-  the response phase: it carries the `RateLimit` headers, the security
-  profile and plugin `onResponse` rewrites. Nothing stores it.
-- **Plugins and policies.** `onRequest` runs before every policy; a
-  short-circuit result skips `agents`, `throttle` and the cache lookup
-  (nothing is counted, matched or stored) and skips the cache store and the
-  throttle headers, then receives security headers and compression, then
-  every plugin's `onResponse`. On a thrown error the policies' `onError`
-  hooks run first (in the order the policies were declared) and then plugin
-  `onError` hooks in reverse. Only the cache policy has an error hook today
-  and it never returns a fallback (`stale-if-error` is header-only); if a
-  future policy did, that fallback would pass through the response phase and
-  every plugin `onResponse`, and plugin `onError` would not run for that
-  request.
-- **Reload.** Every reload builds a new runtime with fresh shared state:
-  throttle counters start empty and the origin cache and precompressed
-  variants are rebuilt; a client mid-window gets a fresh budget. The plugin
-  objects are the ones the operator passed and persist across reloads:
-  `onActivate` runs for the new runtime before `onClose` runs for the old,
-  so a plugin's own state (a shared-store connection, a `WeakMap`) survives a
-  reload unless its `onClose` discards it. A plugin whose `onActivate`
-  throws makes the reload fail and the old runtime keeps serving.
-- **Merge edge cases.** A route `profile` that lacks a key the project layer
-  had leaves that key in force (layers merge, they do not replace); `false`
-  at the project level followed by an object at the route level re-enables
-  the policy with the route's object alone, so it must be complete
-  (`throttle` needs `quota` and `window`); a custom profile named like a
-  built-in shadows it everywhere.
-- **Memory bounds add up.** Per runtime: 64 MiB of asset snapshot, up to
-  64 MiB of precompressed variants, up to 64 MiB of origin-cache bodies (a
-  stored asset references the snapshot buffer rather than copying it, but
-  is counted against the cache budget), and the throttle table at the
-  largest `maxKeys` (100,000 keys by default). Two routes serving the same
-  file compress it separately and both count. During a reload both
-  generations exist at once. [Capacity](CAPACITY.md) states the asset,
-  throttle and cache figures; the precompressed budget belongs in that table
-  too.
-- **Cloudflare.** The artifact carries the effective `agents` and `security`
-  configuration per route, with the entries of any project list file
-  embedded under the reference as written in YAML (no filesystem path); a
-  route-level `agents: false` leaves the artifact without that key. The
-  Worker runs `agents` on the request and `security` on the response, so an
-  early denial carries the profile exactly as on the self-hosted server.
-
-### Not covered by policies
-
-- **Every error the runtime throws** (404 for no match, disabled route or
-  missing link, 410, 400/413/415 from body checks, 502/503/504 from the
-  sandbox or a link store) bypasses the response phase: no `Vary`, no
-  `RateLimit`, no compression, no plugin `onResponse`, on every target.
-  What they do get is the `security` policy: the matched route's effective
-  profile when the error came after routing (so a route with
-  `security: false` answers its 410 bare), otherwise the project-level
-  profile, including a host-side error such as an oversized body or shed
-  admission and the Worker's own 404. The runtime's fixed headers
-  (`Content-Type`, `Cache-Control: no-store`, `Content-Length`,
-  `X-Request-Id`, `X-Content-Type-Options`) can never be replaced by it.
-  Plugins keep `onError` for observation; a policy error hook may answer with
-  a fallback, and none does today.
-- **The audit's probes** share one address and one `User-Agent`, so they do
-  not exercise `agents` or `throttle` the way real traffic does;
-  the policy table in `testPlan().policies` is the audit's evidence for
-  those two.
-- **`stale-if-error` at the origin**: header-only, as the
-  [cache page](policies/cache.md) states.
-- **Cross-instance state**: counters and the cache are per runtime on every
-  target; a shared budget or a shared cache is a plugin.
+| Page | Sections |
+|---|---|
+| [The built-in `hardened` profile and hardening guidance](policies/hardened.md) | The built-in `hardened` profile; Hardened configuration guidance |
+| [The policy contract and your own patterns](policies/contract.md) | The policy contract in TypeScript; Supplying your own patterns |
+| [Client identity, inventory and logging](policies/operations.md) | Client identity and `--trusted-proxies`; What `routes` and `audit` report; Logging |
+| [Interoperability between policies](policies/interoperability.md) | Interoperability |

package/docs/PRERENDER.md

@@ -14,7 +14,7 @@ and no capability.
 ## Why render ahead of time
 
 A function response body is readable by middleware through `text()`. A native
-`page`, `static`, `download`, `redirect`, `respond` or `link` body is not — that
+`page`, `static`, `download`, `redirect` or `respond` body is not — that
 opacity is a deliberate contract, not a gap, and it is what keeps native file
 serving free of guest code. See [middleware](MIDDLEWARE.md).
 
@@ -145,6 +145,8 @@ directory inside the serving project, keeping the render source outside it.
 
 | Limit | Value | Where |
 |---|---|---|
+| Function modules per snapshot | 127 | source project; the render splits into passes |
+| Function module source bytes | 1 MiB each, 4 MiB total per snapshot | source project; the render splits into passes |
 | Function/middleware response body | 1 MiB default (`--max-response-bytes`) | render step |
 | Rendered page bytes | 512 KiB (`maxPageBytes`) | helper |
 | Rendered pages, total bytes | 500, 32 MiB (`maxPages`, `maxTotalBytes`) | helper |
@@ -159,6 +161,44 @@ snapshots. A large site is bounded by the generated project's memory, not by the
 render step. For collections beyond these budgets, publish to an external asset
 service and redirect; provider asset adapters are not implemented.
 
+## Function budgets
+
+The first two rows above are the sandbox's snapshot budgets: at most 127 guest
+modules and 4 MiB of module source in one snapshot. They are deliberate — part
+of what [function security](FUNCTION-SECURITY.md) promises about sandboxed guest
+code — and the render step does not relax them for trusted generated content.
+Serving a project that crosses either still fails at startup, naming the module
+that crossed it:
+
+```
+ConfigError: Function source limit exceeded: /pages/reference.mjs (12841 bytes)
+    brings the snapshot to 4196103 bytes, over the total limit of 4194304 bytes
+```
+
+`prerenderPages` does not inherit that as a page ceiling. Before rendering it
+measures each route's module closure, reading sources only, and packs the routes
+into **passes** that each stay inside the budgets. It then builds one runtime per
+pass, holding only that pass's snapshot, and renders that pass's pages. A render
+that needs more than one pass logs `{event: 'prerender-passes', passes}`.
+
+Nothing about the contract changes: all passes render before anything is
+written, into one output directory that must not already exist, so a failure in
+the last pass leaves no partial artifact — the same atomicity a single pass has.
+Output filenames are checked for collision across passes, and `maxPages`,
+`maxTotalBytes` and the returned fixtures count the whole render, not a pass.
+
+Two consequences worth knowing:
+
+- **A module shared by every page is paid for in every pass.** A template
+  middleware is counted once per pass, not once per render, so it costs bytes
+  against each pass's budget.
+- **One route must still fit one snapshot.** A single route whose own modules
+  and their imports exceed the budgets cannot be split, and fails with the
+  collector's message. That is a route to make smaller, not a pass to add.
+
+The [urlcode-docs showcase](https://github.com/jimhoyd-com/urlcode-docs) renders
+62 documentation pages this way.
+
 ## Larger sites: generating the source project
 
 The example keeps page content as reviewed literal `args` in YAML, which stays

package/docs/PROJECT-DIRECTION.md

@@ -6,12 +6,31 @@ under. It describes intent and
 boundaries, not a delivery schedule; the [roadmap](../ROADMAP.md) owns sequence
 and the [readiness register](RELEASE-READINESS.md) owns what is proven.
 
+## Design principle: declarative-first
+
+> Use URLCode's highest-level declarative features whenever possible. Generate custom code only when the framework cannot express the requirement.
+
+This is the default for human authors, coding agents, examples and framework
+changes. Before writing application code, check the installed version's declarative
+primitives, YAML configuration, policies, supported extensions and reusable recipes
+or templates. Prefer the highest-level supported abstraction that satisfies the
+requirement; do not recreate framework behavior in a lower-level handler.
+
+Custom functions or middleware remain valid for application-specific behavior the
+framework cannot express. Keep that code focused, explain the missing capability,
+and report reusable gaps to the owning repository. Never invent YAML fields or
+bypass target limits, sandbox isolation or operator grants to avoid custom code.
+
 ## What URLCode is
 
 A portable runtime for programmable URL behavior. A project declares its public
-URL surface in YAML, adds isolated JavaScript only where declarative handlers are
+URL surface in YAML, adds JavaScript only where declarative handlers are
 not enough, and runs the same definition locally, in a container, or on operator
-infrastructure. The project format is deliberately bounded so a runtime can
+infrastructure. That JavaScript runs trusted, in the host process, like any
+other project code, unless the project isolates a specific route with
+`sandbox: true` (docs/SPIKE-DEFAULT-TRUST-MODEL.md) — a judgment call the
+project makes per route, not a default the runtime imposes on all guest code.
+The project format is deliberately bounded so a runtime can
 validate it, inspect it, test it and eventually carry it across hosting providers.
 
 Git owns route definitions and code. Operators own credentials, storage and
@@ -19,12 +38,18 @@ capability grants. Application data stays in the operator's systems.
 
 ## What URLCode is not
 
-- **Not a URL shortener.** Short links are one handler beside redirects,
-  validated responses, request functions, middleware, pages, static assets and
-  downloads. The [live-link store](DYNAMIC-LINKS.md) is optional and single-host.
-- **Not a general Node web framework.** Guest code runs inside WASM isolation
-  with no ambient filesystem, network or Node APIs. Behavior that cannot be
-  expressed in the bounded contract is rejected rather than emulated.
+- **Not a URL shortener.** Core is redirects, validated responses, request
+  functions, middleware, pages, static assets and downloads. Stored short
+  links are moving to a future `urlcode-dynamic-link` extension package
+  (mount-based, like `auth`/`admin`, not yet published), not a core handler.
+- **Not a general Node web framework.** There is no framework code to write
+  for routing, validation, middleware wiring or policies — those are declared
+  in YAML and enforced by the runtime. Function/middleware code that needs
+  isolation from the host (untrusted input, an unreviewed contribution, a
+  particularly sensitive secret) opts into `sandbox: true`, which runs it
+  inside WASM isolation with no ambient filesystem, network or Node APIs.
+  Behavior that cannot be expressed in the bounded contract of a sandboxed
+  route is rejected rather than emulated.
 - **Not a hosting account system.** There is no end-user identity, billing or
   public account surface. Management is a private operator API.
 - **Not a provider configuration format.** Provider infrastructure settings do
@@ -39,6 +64,48 @@ private fork or privileged capability. If an application needs something the
 runtime cannot express, that is a gap in the public contract to close in the
 open, not a reason for a special path. See the [roadmap](../ROADMAP.md).
 
+## Why: your AI should build your application, not your framework
+
+Coding agents are good at infrastructure, so they build it every time: routing,
+sessions, validation, middleware, security headers, static serving, redirects,
+webhooks, admin plumbing, deployment glue, tests. The application the person
+asked for arrives last, and the person then owns twenty thousand lines instead
+of two thousand. Cheap generation makes unnecessary code cheap to create and
+expensive to keep.
+
+URLCode's answer is the one databases gave a generation ago. Nobody asks a
+model to write B-tree traversal; it writes `SELECT * FROM customers WHERE id = ?`
+and the database owns the machinery. One level up, a route should read
+
+```yaml
+/admin:
+  auth: { role: admin }
+  function: { source: functions/admin.mjs }
+```
+
+and the runtime should own how. The agent describes what; URLCode owns how.
+YAML is not the innovation and neither is the runtime. The innovation is a
+small, deterministic vocabulary that is optimized for two readers at once: the
+person who opens `urlcode.yaml`, and the agent that writes it.
+
+Three tests keep this from becoming a YAML replacement for every framework:
+
+- **The boundary test.** Is an agent repeatedly generating this code across
+  unrelated projects? If yes, it is a candidate primitive, policy, recipe or
+  extension. If no, it stays application code.
+- **The feature test.** Does this reduce what the agent has to know, generate,
+  debug or maintain? If yes, it belongs on the roadmap. A feature that exists
+  because other web frameworks have it does not.
+- **The evidence test.** The framework grows from measured repetition, not
+  from a list of things applications might need.
+
+The metric that matters is the **application-specific code ratio**: of the
+lines an agent generated, how many are the idea and how many are plumbing. A
+traditional build might be 2,900 lines of business logic inside 18,400; the
+same application on URLCode should be the same 2,900 inside a few thousand.
+Until a reproducible benchmark shows that ratio, the thesis is a hypothesis,
+and [next steps](NEXT-STEPS.md) puts the benchmark before the features.
+
 ## License
 
 The runtime is free and open-source software under the

package/docs/PROVIDER-VERIFICATION.md

@@ -0,0 +1,84 @@
+# Provider conformance and deployment evidence
+
+The synthetic project in [`examples/provider-conformance`](../examples/provider-conformance)
+exercises the common declarative runtime subset: redirect status/location, dropped
+incoming queries, validated mapped queries, encoded path components, constant
+responses, HEAD, method refusal, request-body limits and missing routes. It has
+no bindings, function code, customer data or provider infrastructure configuration.
+
+`test/provider-verification.test.ts` replays the same 12 versioned cases through
+an actual local self-hosted HTTP server, a local Vercel Node handler, AWS payload
+v2 and a freshly built Cloudflare artifact. This establishes local adapter
+behavior only. It does not exercise provider ingress, deployment configuration,
+TLS termination, production DNS, scaling or provider accounts.
+
+## Record a deployment observation
+
+First deploy the synthetic fixture into a disposable environment you own using
+the [AWS](AWS.md), [Vercel](VERCEL.md) or [Cloudflare](CLOUDFLARE.md) adapter. Do not point this runner at a
+third-party service or an unrelated production application: it sends three POST
+requests to fixture paths, whose declared behavior has no side effects.
+
+```js
+import { verifyProviderDeployment } from '@jimhoyd/urlcode';
+const evidence = await verifyProviderDeployment(
+  'vercel',
+  'https://your-owned-fixture.example',
+  { timeoutMs: 3000, gitCommit: 'your-commit-id', release: 'your-release-id' }
+);
+console.log(JSON.stringify(evidence, null, 2));
+if (!evidence.pass) process.exitCode = 1;
+```
+
+The CLI form is `urlcode verify-provider --target vercel --origin https://owned-fixture.example [--timeout-ms 3000] [--release label] [--git-commit sha]`, where `--release` and `--git-commit` are the caller-supplied labels recorded in the report and `--timeout-ms` is the per-request deadline.
+
+Targets are `self-hosted`, `aws`, `vercel` and `cloudflare`. The caller must supply
+an HTTPS origin without credentials, path, query or fragment. TLS verification
+is mandatory. The runner does not provision resources, read credentials, follow
+redirects or fetch redirect destinations. Every request has an absolute deadline
+(default 3 seconds, configurable 50–10,000 ms); the suite has a 60-second deadline.
+Responses stop at 64 KiB and headers at 16 KiB. It sends at most 12 requests,
+sequentially, using identity encoding. Timeout, oversized body and TLS failures
+produce failed findings. Reports include no arbitrary response body/header data.
+
+`runProviderConformance(target, transport, options)` supports local adapter
+replays through an explicit callback. The transport receives an AbortSignal;
+callbacks must honor it to release their own resources. The runner can bound
+waiting for a custom callback, but cannot terminate arbitrary caller code.
+Its report always says `evidence: "local-adapter"` and
+`providerVerification: "unverified"`.
+
+## Evidence interpretation
+
+Reports have `schemaVersion: 1`, `fixtureVersion: 1`, target, origin, timestamp,
+a fixture-case SHA-256, caller-supplied release/Git labels, request count, overall
+`pass` and a finding for every case. Findings report expected/observed status
+and which assertion failed. The case digest identifies probe expectations;
+it is not an artifact or deployed configuration digest.
+
+Live HTTP reports say `evidence: "deployment-http"` and
+`providerVerification: "observed"`, including failed attempts. **Observed does
+not mean passing**: inspect `pass` and every finding. Target/provider identity,
+ownership and release labels are caller assertions, not independent attestation.
+Save reports alongside a Git revision and deployment identity in the operator's
+release records; review origins and labels before publishing them.
+
+No real AWS, Vercel or Cloudflare deployment evidence is checked in. Provider
+provisioning and deployment verification remain pending operator-owned accounts
+and explicit deployment URLs. CI passing must never be reported as an actual
+provider deployment result, independent security review, or soak/recovery proof.
+
+## Remaining transport differences
+
+AWS payload v2 coalesces repeated header values; its adapter conservatively
+interprets comma-separated non-cookie headers as repeats. Vercel's local Node
+adapter can observe raw header counts; real ingress may normalize first.
+Cloudflare's Fetch interface can expose already-coalesced values and normalized
+URLs. Encoded slashes, malformed URL syntax, repeated scalar headers and multiple
+Set-Cookie delivery require target-specific edge checks beyond this common suite.
+The local adapter regression suites retain those implementation-level checks.
+
+This fixture intentionally has no policy settings. A passing common-subset
+report does not establish compression, distributed throttling, caching, agent
+policy updates or project-specific guarantees. Use project-specific deployment
+verification and production operational checks in addition to this small suite.

package/docs/READINESS.md

@@ -22,6 +22,13 @@ and active/disabled/expired state. It includes routes from YAML includes. A
 parameter pattern is one route; its possible URLs are not a finite route count.
 A static mount is one route, even when it contains many files.
 
+`routes --compare previous.json` diffs the current inventory against a saved
+`routes` report: added, removed and changed routes (handler, methods, state,
+middleware count, policies, generated marker and the policy description). It
+prints JSON, or Markdown tables with `--format markdown`, and always exits 0;
+it reports, it does not judge. The [GitHub action](CI.md) posts this diff on
+pull requests.
+
 `audit --expect-routes N` compares N with the total configured count. Its summary
 separately counts active, disabled and expired routes and groups by handler.
 A mismatch exits nonzero. Keep N reviewed in your application CI so accidentally
@@ -117,7 +124,20 @@ The runtime suite covers many generic protocol/security/reload cases. Apps must
 supply their own business and boundary fixtures. Automated remote destination
 health, redirect-chain/loop analysis, DNS/TLS checks, sustained soak/load profiles,
 coverage by function branch and historical performance comparison remain planned.
-Run the local audit in CI now; do not label a passing local audit “production certified.”
+Run the local audit in CI now (the [project action](CI.md) wires validate, test,
+audit and the route diff into GitHub pull requests); do not label a passing local
+audit “production certified.”
+Once a candidate is deployed, `urlcode verify-deployment --target` compares its
+responses with this project; see [deployment checks](DEPLOYMENT-CHECKS.md).
+
+Before writing fixtures, `urlcode explain /route` shows what the compiled
+configuration will do for a path: effective methods, the handler, the middleware
+chain, validated inputs, the policies in effect and the cache outcome, so a
+fixture asserts declared behavior rather than a guess. `urlcode manifest --json`
+(also written by `build` as `manifest.json`) lists every route, the capabilities
+in use, external requirements and per-target support with the revision digest,
+which is the document to attach to a release review. Both read the
+configuration only; they are not evidence that a deployment serves it.
 
 Routes with middleware need explicit request fixtures with meaningful response
 assertions for every active method. Audit cannot infer their behavior from the