@jimhoyd/urlcode 0.4.2 → 0.4.7

package/docs/POLICIES.md

@@ -1,211 +0,0 @@
-# Policies
-
-Policies are host-enforced behavior declared in YAML around a route: a
-per-client request budget, a User-Agent deny list, a security-header profile,
-content-coding negotiation and an HTTP caching strategy. They run in the host
-process, outside function/middleware execution — trusted or sandboxed alike —
-so they can see the client address, keep counters across requests and touch
-the transport, which route middleware by design cannot
-([middleware](MIDDLEWARE.md), [function security](FUNCTION-SECURITY.md)).
-
-Everything here is optional and off by default. A project with no `policies`
-key and no `profiles` key behaves exactly as before: no policy module is
-compiled and the request path is unchanged. Each policy has its own page:
-
-| Policy | Page | What it does |
-|---|---|---|
-| `throttle` | [throttle](policies/throttle.md) | Sliding-window request budget with `RateLimit`/`RateLimit-Policy` headers, 429 and `Retry-After` |
-| `agents` | [agents](policies/agents.md) | Deny or allow by `User-Agent`, from bundled lists, project files and bounded patterns |
-| `security` | [security](policies/security.md) | OWASP Secure Headers Project response headers, with per-header `set`/`unset` |
-| `compression` | [compression](policies/compression.md) | `Accept-Encoding` negotiation; assets precompressed at snapshot time |
-| `cache` | [cache](policies/cache.md) | Named strategies from RFC 9111/5861/8246/9213 plus an origin memory cache |
-
-The design and the reasoning behind each choice are in the
-[extensions spike](archive/2026-09-19/SPIKE-EXTENSIONS.md). Operators who need behavior the
-declarative block cannot express pass host [plugins](PLUGINS.md) in code; plugins
-are never named in YAML.
-
-## Declaring policies
-
-```yaml
-version: "1"
-policies:                      # project defaults; every key optional
-  profile: hardened            # built-in, or a name under `profiles`
-  throttle: { quota: 60, window: 60 }
-routes:
-  /api/lookup/{id}:
-    function: { source: functions/lookup.mjs }
-    policies:
-      throttle: { quota: 10, window: 60 }
-      cache: false
-```
-
-`policies` at the top level sets project defaults; `routes.<path>.policies`
-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), carrying the same keys minus `required`;
-`required: false` documents the intent and emits no policy. It accepts
-`required`, `role`, `permission`, `verified`, `freshWithinSeconds` and
-`onDeny` and nothing else — `role` is singular, and there is no `roles`. Like
-`cache` below, it is refused rather than silently ignored in three cases: when
-the project declares no `extensions.auth`, when the route also sets
-`policies.extensions.auth` (use one form), and when the route sets
-`policies.extensions: false`. `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
-bounds; the [JSON Schema](../schemas/urlcode.schema.json) is the source.
-
-Values are behavior, never infrastructure: a quota is a number a proxy or CDN
-can restate, while trusted proxy ranges, storage URLs and vendor rule
-identifiers stay in operator configuration. That is what keeps a project
-portable between a laptop, a container and an adapter.
-
-## Where policies run
-
-Policies run once the route is known and before its contract is checked. A
-denied agent or an exhausted budget is answered without reading a body or
-starting the sandbox. The self-hosted pipeline:
-
-```
-socket limits → admission → body read
-  → runtime.handle(): match → enabled/expires
-    → plugins onRequest                       (outermost, first plugin first)
-    → agents → throttle → cache lookup        (request phase; may short-circuit)
-    → methods (405) → request.body checks
-    → native handler | guest chain
-    → YAML response.headers
-    → cache store → throttle headers → security → compression   (response phase)
-    → plugins onResponse                      (reverse order, first plugin last)
-    → writeResponse
-```
-
-Request order is fixed: agents first because a denial is the cheapest
-outcome, then throttle, then the cache lookup, so a denied or refused request
-neither counts against a budget nor touches the cache. Response order is the
-cache store, then the throttle's `RateLimit` headers (after the store, so a
-cached copy is never stamped with one client's remaining budget), then
-security headers, then compression last so every header it depends on is
-already final. YAML `response.headers` are applied by the runtime before the
-response phase, so an explicit header always beats a profile default.
-
-A result produced by a request-phase policy (an agent denial, a throttle
-refusal, a cache hit) skips that policy's own response hook and passes through
-the others: a hit is not stored twice but still carries the client's
-rate-limit headers, and a denial is not stored because its status is not
-cacheable. A throttle refusal carries its own `RateLimit` and `Retry-After`
-headers. A plugin short-circuit ran before any policy, so it skips the
-response hook of every policy that has a request phase; security headers and
-compression still apply to it.
-
-Two responses bypass the response phase entirely: the `405` the runtime returns
-for an undeclared method, and any error the runtime throws (404 for no match,
-410 for an expired route, 413/415 from body checks, sandbox 502/504). Those
-receive the runtime's standard headers only. Policies with an `onError` hook
-and plugin `onError` hooks observe thrown errors; they cannot change them.
-
-Adapters call `handle()` directly and delegate socket limits and admission to
-the provider; the policy order inside `handle()` is the same. The Cloudflare
-Worker runs the same request and response order with the two policies it can
-carry.
-
-## Portability and the per-target table
-
-A project is portable when a second person can run it elsewhere and get the
-same declared behavior or an explicit refusal. A target that cannot honor a
-policy refuses activation naming the route and the policy, exactly as adapters
-refuse functions and middleware; nothing degrades silently. One exception is
-stated rather than hidden: a policy the platform itself already provides is
-**delegated**, meaning accepted and dropped, and reported as such in the
-inventory, so one YAML can serve a Node host and a serverless host without
-edits. The self-hosted
-message reads `/path declares policies.throttle, which the vercel target
-cannot enforce`; the Cloudflare build reports
-`/path: policies.throttle cannot be compiled for this target`.
-
-| Policy | Self-hosted (`node`) | Vercel / AWS | Cloudflare build |
-|---|---|---|---|
-| `agents` | native | native | compiled into the artifact |
-| `security` | native | native | compiled into the artifact |
-| `throttle` | native, in-process counters | native only with `partition: route`; `client` and `client-route` refused because a client fans across instances and the budget would silently be quota × instances | refused |
-| `compression` | native | delegated: the provider compresses | delegated |
-| `cache` | native: headers plus origin memory cache | native | refused |
-
-"Compiled" means the effective configuration for every route is validated at
-build time and carried in the Worker artifact; the Worker has no filesystem and
-no Node imports, so only modules free of both qualify. The Worker's client
-identity is the platform's `cf-connecting-ip`; the serverless adapters use the
-platform-set source address (`sourceIp` on Lambda, the leftmost
-`X-Forwarded-For` entry the platform writes on Vercel). None of these read a
-forwarded header a client could have set.
-
-The cross-request state a policy keeps (throttle counters, the origin cache) is
-per runtime instance on every target, never shared between replicas or
-serverless instances. Given identical request bytes and project, every target
-answers with the same status and headers; only that state may differ.
-
-## Merge semantics
-
-The effective configuration for a route is built from four layers, each
-merged over the one below:
-
-1. the project `profile` (built-in or custom),
-2. the project `policies` keys,
-3. the route `profile`, if the route names one,
-4. the route `policies` keys.
-
-Within a layer, `false` removes a policy declared below it; an object merges
-shallowly over what is there, so a route can tighten one number without
-restating the rest. Only top-level keys of each policy merge: a route that
-writes `agents: { deny: [crawlers] }` replaces the whole `deny` array, not one
-entry of it.
-
-```yaml
-policies:
-  profile: hardened
-  throttle: { quota: 5 }          # hardened's window and partition remain
-profiles:
-  mine:
-    security: { headers: oshp-no-csp }
-routes:
-  /feed:
-    policies:
-      profile: mine                # merges over the project layer, not instead of it
-      throttle: false              # removed for this route only
-      cache: { strategy: swr, maxAge: 3 }
-```
-
-Here `/feed` ends up with `security: { headers: oshp-no-csp }`, the
-`hardened` agents and compression entries, no throttle, and the route's cache
-entry. Any other route gets `hardened` with `throttle.quota` at 5.
-
-`profiles` is a top-level map of reusable policy sets, each a `policies`
-object without a `profile` key. A custom profile whose name matches a built-in
-shadows it, so a project can redefine `hardened` and every reference to it
-resolves to the project's version. Naming an unknown profile fails validation.
-
-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.
-
-## Further pages
-
-| 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

@@ -1,245 +0,0 @@
-# Prerendering pages into a native static project
-
-Render a project's function and middleware routes once, at build time, into a
-project whose routes are all native `page` handlers. The published site answers
-from prevalidated byte buffers: no guest code runs to serve a request at all,
-so whatever execution mode the source routes used — trusted by default, or
-isolated QuickJS/WASM where a route declares `sandbox: true` — along with its
-deadline and memory budget where sandboxed, is not on the request path.
-
-The shared orchestration ships as a build helper, `@jimhoyd/urlcode/prerender`, and the
-runnable recipe is [`examples/prerender`](../examples/prerender/README.md), which
-consumes it. Both are covered by `test/prerender.test.ts`. Everything here uses
-the existing runtime: prerendering adds no field to route YAML, no CLI command
-and no capability.
-
-## Why render ahead of time
-
-A function response body is readable by middleware through `text()`. A native
-`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).
-
-So a shared template cannot be wrapped around a native file at request time. The
-answer is to apply the template while the content is still a function response,
-and publish the result:
-
-```
-function + template middleware  ──render once──▶  HTML file  ──▶  page route
-   (trusted or sandboxed, build time)                        (no guest code)
-```
-
-The alternative — reading Markdown through `next().text()` on a native route —
-is not supported and should not be attempted. Prepare content at build time.
-
-## The build helper
-
-```js
-import {prerenderPages, assertNativeProject, pageFileName} from '@jimhoyd/urlcode/prerender';
-
-const rendered = await prerenderPages('./render-source', './out/pages', {
-  origin: 'https://docs.example',   // what a page sees as its own origin
-});
-// rendered.pages  → [{path: '/guide', file: 'guide.html', bytes: 531}, …]
-// rendered.fixtures → byte-for-byte GET and empty HEAD cases, ready to extend
-// rendered.count, rendered.bytes, rendered.directory
-```
-
-`prerenderPages` owns everything that is easy to get wrong and nothing that is
-site-specific. It activates the source project, selects the active literal GET
-function routes, renders each one through its middleware, checks the status and
-content type, enforces the budgets, derives and validates a safe output filename,
-writes the files and closes the runtime — then hands back metadata. It does not
-write a project, choose response headers, copy assets or compile content: the
-caller assembles a project, or a generated include, from `pages` and `fixtures`.
-
-`assertNativeProject(project, {allow})` activates a project and proves it cannot
-execute guest code to answer a request: every route is one of the allowed native
-handlers and none carries middleware. `allow` defaults to `['page', 'static',
-'download']`, which is what a real site serves; narrow it to `['page']` for a
-page-only artifact. Run it on the **final assembled site**, not only on the
-rendered pages, so what you deploy is what was checked.
-
-| Option | Default | Meaning |
-|---|---|---|
-| `origin` | `http://localhost` | HTTP(S) origin a render sees; no path or credentials |
-| `fileName` | `pageFileName` | Route path to filename; the path and the result are both validated either way |
-| `ignoreUnrenderable` | `false` | Allow source routes this build will not render |
-| `maxPages` | 500 | Pages in one render |
-| `maxPageBytes` | 512 KiB | Bytes per rendered page |
-| `maxTotalBytes` | 32 MiB | Bytes across the whole render |
-| `log` | none | `{event: 'prerendered', path, file, bytes}` per page |
-
-## What the helper guarantees
-
-The runtime enforces its own protections when a generated project activates:
-asset declarations reject absolute paths, traversal, dot segments, symlinks,
-hardlinks and nonregular files, and static trees refuse `urlcode.yaml`,
-`package.json`, `package-lock.json`, hidden entries, `node_modules` and
-`.pem/.key/.p12/.pfx/.env` files. See [assets](ASSETS.md).
-
-Those checks fail a deployment. The helper fails the build earlier and more
-specifically:
-
-- **Filenames are validated, never trusted.** `pageFileName` maps one route path
-  to one flat name: segments joined with `~`, which cannot occur in a segment, so
-  `/a/b` (`a~b.html`) and `/a-b` (`a-b.html`) are distinct rather than a silent
-  collision, and the mapping stays injective for every accepted path. Dots,
-  underscores and mixed case are fine, so a docs URL like `/docs/ASSETS.md`
-  works. Parameters, wildcards, traversal and dot segments are rejected. A custom
-  `fileName` hook is allowed — hashing the route is a reasonable choice — but its
-  result goes through the same check: a flat name, no leading dot, not a
-  protected name, `.html`, and unique **case-insensitively**, because on macOS
-  and Windows two names differing only in case are one file.
-- **Directories may not overlap.** In either direction: a build must not write
-  into the reviewed source, nor read a source nested inside its output.
-- **Nothing is written until everything renders.** Pages are held in memory and
-  written only after the last one passes, and the pages directory must not
-  already exist — it is created, along with any missing parents, only once every
-  render has succeeded, so a failed build creates nothing at all. An existing
-  pages directory is refused with an error carrying `code: 'EEXIST'`. If your
-  artifact has a root above that directory, claiming it is yours: check it before
-  calling, and let the helper create it as a parent after the render.
-- **Every render is checked.** A non-200 status, a content type that is not
-  `text/html`, an empty body, an oversized body or an exceeded aggregate budget
-  fails the build instead of publishing a file.
-- **Bytes are preserved.** The response body is a byte array, not a string. It is
-  kept as a `Buffer` through the file and its fixture alike, so a multi-byte
-  character is never re-encoded or truncated.
-- **Skipping is explicit.** By default a source route the build would not render
-  fails it, because silently rendering a subset publishes an incomplete site that
-  looks whole. Pass `ignoreUnrenderable` when a mixed project is intended.
-- **The runtime is always closed.** In a `finally`, so a failing build exits
-  instead of hanging on its worker threads.
-
-The helper is operator build tooling. It runs in Node with normal filesystem
-access because it is not guest code; it does not itself widen a source route's
-declared execution mode — a route with `sandbox: true` still renders isolated,
-with no filesystem, and no host-code fallback is introduced for it. It is a
-separate package export from the runtime for that reason. Review it as you
-review any deployment tooling.
-
-## Assembling a site
-
-What the helper returns is deliberately not a project, because that is the part
-every site does differently. A small site writes one `page` route per file, as
-[`examples/prerender`](../examples/prerender/README.md) does in about twenty
-lines. A larger one copies the rendered pages next to its own assets, adds
-`static` and `download` routes and response security headers, keeps a committed
-entry point and writes only a generated include, then extends `fixtures` with its
-own cases before asserting the whole thing is native:
-
-```js
-const rendered = await prerenderPages(renderSource, 'project/public/pages');
-for (const page of rendered.pages)
-  config.routes[page.path] = {page: {file: `public/pages/${page.file}`}, response: {headers: security}};
-await writeFile('project/generated/routes.yaml', stringify(config));
-await writeFile('project/tests/requests.json', JSON.stringify([...rendered.fixtures, ...ownCases]));
-await assertNativeProject('project');
-```
-
-Applying your own `response.headers` is expected; the helper never chooses them
-for you and never discards them.
-
-A site that renders straight into the tree it serves, rather than into a staging
-project, needs no copy step at all — point `prerenderPages` at the pages
-directory inside the serving project, keeping the render source outside it.
-
-## Limits worth knowing before you design a site
-
-| 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 |
-| Middleware entries per route | 16 | source project |
-| Asset file size | 16 MiB | generated project |
-| Total unique asset bytes | 64 MiB | generated project |
-| Static entries traversed | 10,000 | generated project |
-| Directory depth | 20 | generated project |
-
-Startup snapshots asset bytes in memory, and a reload can briefly hold two
-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` site rendered 62 documentation pages this way. That
-repository has since been deleted, so no link is given; the runnable
-version of the same pattern is [`examples/prerender`](../examples/prerender/README.md).
-
-## Larger sites: generating the source project
-
-The example keeps page content as reviewed literal `args` in YAML, which stays
-readable and lets `dev` serve the site live. A site with hundreds of pages
-instead generates its source project from host-prepared content: the build reads
-its Markdown or data, compiles and sanitizes it in Node, writes a temporary
-project whose routes carry that HTML as literal arguments, renders it with the
-helper, and discards the temporary project.
-
-That keeps every property intact — content is still reviewed input, guest code
-still reads nothing from disk, and the published artifact is still inert. Two
-things to hold onto:
-
-- **Generated YAML is operator input.** It is written by your build, from your
-  content, and reviewed like any other deployment artifact. Route YAML never
-  gains the ability to name host code or a callback.
-- **Sanitize before rendering, not after.** The template escapes the values it
-  interpolates, but content injected as raw HTML is published as written. Whatever
-  produces that HTML owns its safety.
-
-The `urlcode-docs` site built itself this way before that repository was
-retired. It was a working integration, not a deployment or performance claim.
-
-## What this is not
-
-Not a static-site generator: no Markdown, no sanitizer, no asset pipeline, no
-incremental or watch build, no link checking, no sitemap. Not a way to make
-native bodies readable. Not a template engine — the template is ordinary
-middleware you write. Not a CLI command: prerendering is a step inside a build
-that already runs JavaScript, so the helper is a library. Content compilation,
-sanitization, search, asset assembly and deployment stay in the application.
-
-
-Trusted build-time functions and middleware use ordinary Node imports, including
-npm packages and dynamic imports. The pass planner applies source-graph budgets
-only to `sandbox: true` routes; it does not parse trusted modules as sandbox
-code. Page-count and output-byte budgets still apply to both modes. After
-rendering, emit native page/file routes without middleware, then use the static
-build target. Static hosting cannot execute middleware on incoming requests.

package/docs/PROJECT-DIRECTION.md

@@ -1,118 +0,0 @@
-# Project direction
-
-This page states the product boundary: what URLCode is, what it is not, how
-application projects relate to the runtime, and the license it is released
-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 JavaScript only where declarative handlers are
-not enough, and runs the same definition locally, in a container, or on operator
-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
-capability grants. Application data stays in the operator's systems.
-
-## What URLCode is not
-
-- **Not a URL shortener.** Core is redirects, validated responses, request
-  functions, middleware, pages, static assets and downloads. Stored short
-  links are not a core handler; the `urlcode-dynamic-link` extension package
-  that owned them has been retired and unpublished.
-- **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
-  not belong in route behavior YAML. A project must remain runnable on a laptop
-  or in a single container wherever else it is deployed.
-
-## Application projects
-
-Applications built on URLCode are ordinary consumers of the public runtime.
-They exist to prove the contract is sufficient in practice, and they get no
-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 [the roadmap](../ROADMAP.md) puts the benchmark before the features.
-
-## License
-
-The runtime is free and open-source software under the
-[Apache License 2.0](../LICENSE). Contribution terms follow from the same
-license; see [contributing](../CONTRIBUTING.md).
-
-The license covers the runtime source in this repository. It grants no rights in
-any application's own routes, content or data, and it is not a warranty or a
-production-readiness claim — those are set by the
-[readiness register](RELEASE-READINESS.md) and [security policy](../SECURITY.md).

package/docs/PROVIDER-VERIFICATION.md

@@ -1,84 +0,0 @@
-# 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.