@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/docs/BULK.md

@@ -0,0 +1,79 @@
+# Bulk redirect projects
+
+Bulk import converts CSV, JSON or YAML redirect rows into an ordinary Git-owned
+URLCode project. It delegates semantics and row diagnostics to the strict
+[redirect interchange](INTERCHANGE.md) converter. Only literal paths and
+absolute HTTP(S) redirect destinations are accepted; unsupported behavior and
+duplicate paths fail rather than being discarded or overwritten.
+
+```sh
+urlcode bulk-import csv redirects.csv --out ./imported --dry-run
+urlcode bulk-import csv redirects.csv --out ./imported
+urlcode validate --local --project ./imported
+```
+
+CSV requires the header `path,url,status`; status can be empty for 302. JSON and
+YAML are arrays of `{path, url, status?}` rows. Input is limited to 32 MiB and
+100,000 routes. This command is for data import, not arbitrary provider config.
+Use explicit provider interchange commands when migrating provider files.
+
+The SDK provides
+`importBulkProject(text, format, output, {dryRun, source})`. `format` is `csv`,
+`json` or `yaml`. The report includes `ok`, `routeCount`, source/row diagnostics,
+a SHA-256 fingerprint of the exact input text, and a bounded output-file plan.
+Invalid input returns `ok: false` without writing files. Filesystem/output
+refusals throw. `source` is a caller-supplied provenance label, not a file to read.
+
+Routes are sorted by literal path and divided into include files with at most
+1,000 routes each. At 100,000 routes this produces 100 include files. The entry
+`urlcode.yaml` holds the include list and empty `routes`. `provenance.json`
+records the source label, input fingerprint, counts and each shard's first/last
+path. It does not embed the original input or claim exact source line mappings
+for successful output rows; retain the original file in version control if that
+traceability is needed. Invalid row diagnostics preserve their source positions.
+
+Dry-run performs conversion and output planning without writing the requested
+destination. Import requires a new output directory under an existing parent;
+there is no implicit merge or overwrite mode. As with recipes, dependencies are
+written first and a rename publishes the completed entry YAML last. Failed
+writes clean up the directory created by that invocation. Source data is never
+interpreted as shell code. The caller must control the output parent while
+publishing.
+
+## Local scale evidence
+
+Run each dataset in a fresh process, sequentially, without concurrent builds:
+
+```sh
+node benchmarks/bulk.ts 1000
+node benchmarks/bulk.ts 10000
+node benchmarks/bulk.ts 100000
+```
+
+Observed on 2026-09-17 against the final integrated next-phase working tree,
+with the merged TypeScript 6.0.3 dependency lock, Node v26.8.2, macOS arm64,
+Apple M4 Pro and 48 GiB system memory. These measurements include the final
+capability, revision-pin and egress activation paths. Synthetic routes redirect `/rN` to `https://example.com/items/N`.
+Conversion includes input validation, semantic compilation and sharded output
+publication; activation uses the normal `createRuntime` loader and compiler.
+Lookup measures 5,000 `Runtime.handle` requests at concurrency one after 100
+warm-up requests, validating each status and Location. It excludes socket/TLS
+transport. Memory is sampled process RSS/heap after phases, not peak memory or
+an isolated worker measurement.
+
+| Routes | Includes | Conversion ms | Activation ms | RSS after activation MiB | Heap MiB | Lookup p95 ms |
+| ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| 1,000 | 1 | 56 | 139 | 180 | 27 | 0.002292 |
+| 10,000 | 10 | 272 | 373 | 288 | 46 | 0.002916 |
+| 100,000 | 100 | 5,530 | 8,838 | 537 | 214 | 0.003791 |
+
+All three sequential fresh-process datasets activated and returned the expected
+redirects. These are single observations, not a repeated-run statistical study;
+background host load can change startup and memory measurements. Unlike the
+previous single-document 100,000-route routing benchmark, the sharded project
+fits the existing configuration worker's 256 MiB heap and 10-second deadline.
+No loader, route-count, compiler deadline or runtime safety limit was increased.
+This local result does not establish cross-platform capacity, provider
+performance, peak-memory bounds, concurrency/soak behavior or production SLOs.
+The benchmark reports failure phase and error if a limit is reached on another
+machine; it does not retry with relaxed limits.

package/docs/CAPABILITIES.md

@@ -0,0 +1,179 @@
+# Capabilities and normalized route representation
+
+URLCode is a portable runtime for programmable URL behavior: **URL behavior as
+code**. YAML describes behavior; operators supply infrastructure and authority.
+
+## Inspect target support
+
+```sh
+urlcode capabilities
+urlcode capabilities --target self-hosted
+urlcode capabilities --target cloudflare --json
+urlcode capabilities --target aws
+urlcode capabilities --target vercel
+```
+
+This command needs no project or credentials. `node` is an alias for
+`self-hosted`, matching the existing embedding API. Unknown target names fail.
+JSON has `format: 1`, target deployment evidence and capability rows.
+`doctor` also reports `capabilityTargets`; its `providers` list remains empty
+because no provider deployment has been verified. Canonical
+names follow the schema (`respond`, `link`, `policies.security`), not marketing
+synonyms. `proxy` and `signals` are self-hosted capabilities requiring external
+revision-pinned origin grants. `conditions` (`match`) and `conditional` (disjoint
+cases) are supported by self-hosted/AWS/Vercel and refused by Cloudflare until
+artifact lowering exists. See [egress](EGRESS.md) and [conditions](CONDITIONS.md).
+
+| Support | Meaning |
+| --- | --- |
+| native | Implemented by the local runtime or Node adapter |
+| compiled | Implemented by the Cloudflare compiler and artifact runtime |
+| conditional | Depends on configuration; inspect the actual project |
+| delegated | Existing policy contract relies on provider behavior |
+| refused | No implementation that this target can activate |
+| unknown | No support evidence; fail closed during project analysis |
+
+`native` and `compiled` describe local implementation tests. AWS, Vercel and
+Cloudflare deployment evidence remains **unverified**. This is not a blanket
+exact-portability promise. Cloudflare coalesces duplicate headers and receives a
+normalized Request target; AWS accepts payload v2 only. See [Cloudflare](CLOUDFLARE.md),
+[AWS](AWS.md) and [Vercel](VERCEL.md) for transport limits. Compression is
+explicitly delegated, not verified equivalent to operator-selected settings.
+Route throttle counters and caches remain per instance. No supported entry
+bypasses semantic validation, required operator grants or deployment prerequisites.
+
+## One capability or one schema fragment
+
+```sh
+urlcode capabilities redirect
+urlcode capabilities policies.throttle --json
+urlcode schema route
+urlcode schema policies.cache --json
+urlcode schema site.sitemap --yaml
+```
+
+`urlcode capabilities <name>` prints one catalog entry: its kind (handler,
+policy, routing, request, binding, egress, middleware or project), a summary,
+the resolved schema fragment(s), constraints, the operator grants the capability
+needs at activation, support per target, the targets that refuse it, and the
+bundled recipes and cookbook routes that use it. Names are the catalog names
+(`redirect`, `bindings`, `policies.cache`); an unknown name fails with exit 1
+and lists the valid names. `--target` applies to the full catalog only.
+
+`urlcode schema <path>` prints only that fragment of
+`schemas/urlcode.schema.json` with local `$ref`s resolved inline. Paths are
+top-level document keys (`routes`, `policies`, `site`, `extensions`), `route`,
+or a route property (`redirect`, `middleware`, `match`, `env`), optionally
+followed by nested property names (`policies.cache`, `request.body`,
+`site.sitemap`). Resolution is bounded and cycle-safe; where a nested object is
+its own path (`route` inside `routes`, `policies` inside `route`) it is
+summarized with a `$comment` naming that path so every fragment stays under
+16 KiB. Fragments describe shape only: they carry no defaults, validation
+result or operator authority, and the full schema remains the contract.
+
+Both commands read bundled package data and need no project, credentials or
+network. The SDK exposes them as `getCapability(name)` and
+`getSchemaFragment(path)`; the MCP server as `get_capability` and `get_schema`
+(see [tooling](TOOLING.md)). Grant descriptions name the operator flag or policy
+involved, never binding values.
+
+## Programmatic analysis
+
+The main package exports `getCapabilities`, `routeCapabilities`,
+`analyzeProjectCapabilities`, `analyzeCompiledCapabilities`,
+`assertTargetCompatibility`, `normalizeCapabilityTarget` and their report types.
+
+```js
+import { loadDocument, analyzeProjectCapabilities,
+  assertTargetCompatibility } from '@jimhoyd/urlcode';
+
+const loaded = await loadDocument('./project');
+const report = analyzeProjectCapabilities(loaded, 'cloudflare');
+console.log(report.issues); // path, capability, support, reason; never binding values
+assertTargetCompatibility(report);
+```
+
+This low-level example examines declared routes. Runtime activation and builds
+first expand `site` conventions using the operator origin, then analyze all
+routes including generated ones. A report is a compatibility preflight, **not**
+a substitute for compilation/validation. Disabled and expired routes are still
+checked; project `dynamicLinks: true` is a requirement even with no link route.
+`compatible` means there are no refused, unknown or unresolved conditional
+requirements. Explicit delegation and transport limitations still apply.
+
+Requirements include effective inherited/profile policies after route overrides
+and `false` removals. Policy modules' existing `targets(config)` functions remain
+the source of policy decisions. The catalog says serverless throttle is
+conditional; a project report resolves `partition: route` to native and the
+client partitions to refused. Reports contain paths and capability facts, not
+sources, destinations, binding names/values, code, validator closures or assets.
+
+Build/activation refusals aggregate all incompatible requirements and name each
+route, capability, target and reason before any artifact files are written.
+Unsupported bindings on Cloudflare fail before credentials are resolved.
+
+## Existing IR, formalized
+
+The implementation already has a useful internal representation:
+
+```text
+strict YAML + schema validation + includes
+  → site expansion
+  → shared capability preflight (declarations, no credentials)
+  → semantic route compilation
+  → CompiledRouteTable / CompiledRoute
+  → capability analysis / target lowering
+  → host assets + policy chains + isolated function pool, or Worker artifact
+```
+
+`CompiledRoute` in `src/types.ts` extends shared `MatchableRoute` with validated
+parameters, normalized HTTP replies/headers, resolved bindings and source
+references. `CompiledRouteTable` indexes literal paths, parameter buckets and
+static mounts. `router.ts` owns precedence, collision checks, default methods,
+input/reference validation and normalization. `match.ts` supplies portable
+request-time matching to both runtime and Worker. No second parser or competing
+route IR is introduced.
+
+`routeCapabilities` is a value-free projection used for both declaration
+preflight and compiled analysis. Preflight deliberately precedes full semantic
+validation to report unsupported features before reading missing assets or
+resolving secrets; it cannot authorize or validate a project. Normal compilation
+and policy validation still run. AWS/Vercel consume the shared runtime IR;
+Cloudflare additionally analyzes the compiled table before serializing its
+allowlisted artifact fields and standalone validators.
+
+The compiled table is internal, mutable during activation and **not serializable
+as an interchange contract**: bindings contain resolved secrets, validators are
+functions, assets contain bytes and policy chains own host state. The existing
+Cloudflare artifact is a separate versioned lowering, not a replacement IR.
+[Interchange](INTERCHANGE.md) projects a validated literal-redirect subset and
+explicitly reports unsupported semantics; it never dumps compiled routes.
+The next-phase schema extends this same IR with normalized condition cases,
+proxy headers and signal definitions. Resolved egress headers are private runtime
+state and must never be serialized. Capability analysis itself adds no authority
+and does not run in the request path.
+
+See the [repository review and incremental plan](NEXT-PHASE-PLAN.md) for the
+implementation status. Provider deployment tests, independent security review and
+operational soak/recovery proof are separate work.
+
+## Local performance check
+
+2026-09-17, Node 26.8.2, macOS arm64, Apple M4 Pro, 48 GiB RAM.
+`npm run benchmark -- <count>` runs 5,000 loopback requests at concurrency 16.
+Single runs against baseline `1a00294` and this change, not a statistical study:
+
+| Routes | Startup ms before / after | RSS MiB before / after | Heap MiB before / after | Requests/s before / after | p95 ms before / after |
+| --- | --- | --- | --- | --- | --- |
+| 1,000 | 135 / 138 | 183 / 182 | 29 / 34 | 24,645 / 24,701 | 1.18 / 1.23 |
+| 10,000 | 312 / 303 | 211 / 207 | 55 / 63 | 6,762 / 6,829 | 4.08 / 4.09 |
+
+Both baseline and updated 100,000-route runs failed with `Configuration worker
+resource limit or failure` before route compilation. The worker's existing
+resource bounds are unchanged; the configured 100k route ceiling is not evidence
+that every 100k YAML document fits those bounds. Bulk-scale remediation and
+repeatable memory profiling were subsequent work at Phase A. The new
+[bulk sharding benchmark](BULK.md) successfully activates 100,000 routes within
+the unchanged worker limits. Capability analysis adds
+linear activation work and temporary report allocations; no request-time checks
+were added. These measurements are not provider, soak or capacity certification.

package/docs/CAPACITY.md

@@ -1,6 +1,6 @@
 # Capacity, concurrency and system limits
 
-These are 0.2.0 implementation limits and planning models, not a throughput
+These are 0.3.0 implementation limits and planning models, not a throughput
 SLA. Route count, connections, in-flight requests and sandbox concurrency are
 four different quantities. Always measure the actual application on deployment
 hardware with the intended proxy, TLS, logging and limits enabled.

package/docs/CI.md

@@ -0,0 +1,142 @@
+# Checking a project on GitHub
+
+`jimhoyd-com/urlcode/action` is a composite GitHub Action for a URLCode
+*project*: a repository with a `urlcode.yaml`. It runs the same local checks
+you run by hand and, on pull requests, keeps one comment up to date with the
+route-inventory diff against the base branch. It needs no cloud credentials;
+the only token it touches is the workflow's own `GITHUB_TOKEN`.
+
+The starter ships it as `.github/workflows/urlcode.yml` (`urlcode init` copies
+it; the [template repository](https://github.com/jimhoyd-com/urlcode-template)
+carries the same file):
+
+```yaml
+name: urlcode
+on:
+  push:
+  pull_request:
+permissions:
+  contents: read
+  pull-requests: write # the sticky route-diff comment; drop it to only log the diff
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: jimhoyd-com/urlcode/action@main # pin a release tag or commit
+        with:
+          expect-routes: 2
+```
+
+The action lives at `action/action.yml` in the runtime repository, so the
+reference is `jimhoyd-com/urlcode/action@<ref>`. Pin `<ref>` the way you pin
+the runtime: a release tag or a commit SHA, not `main`, once the project is
+past its first commit.
+
+## What it runs
+
+| Step | Command | Fails the job when |
+|---|---|---|
+| Install | `npm ci` in the project (see below) | Dependencies do not install |
+| Validate | `urlcode validate --project <project>` | The YAML, includes, functions or bindings do not load |
+| Test | `urlcode test --project <project>` | A `tests/requests.json` fixture fails |
+| Audit | `urlcode audit --project <project> --expect-routes N --compliance <profile>` | Count mismatch, failed generated check, uncovered active route/method, or a `high` compliance finding without `compliance-warn` |
+| Route diff | `urlcode routes --compare base.json --format markdown` | Never; it reports |
+
+Every command is the CLI documented in [readiness](READINESS.md) and
+[compliance](COMPLIANCE.md); the action adds no check of its own. `--origin`
+is passed to validate, test and audit when set. Steps run with `bash`, so the
+action works on the Linux, macOS and Windows runners.
+
+The project's runtime comes from the project. With a `package.json` the action
+runs `npm ci` (or `npm install` without a lockfile) and uses the
+`@jimhoyd/urlcode` that resolves from there, hoisted or not. A project without
+`package.json`, such as a fresh `urlcode init`, gets the `runtime` input
+installed into a private prefix under the runner's temp directory:
+`@jimhoyd/urlcode` (the latest release) by default, or a version
+(`@jimhoyd/urlcode@0.3.0`) or an absolute tarball path.
+
+## Inputs
+
+| Input | Default | Meaning |
+|---|---|---|
+| `project` | `.` | Directory containing `urlcode.yaml`, relative to the workspace |
+| `node-version` | `26` | Passed to `actions/setup-node` |
+| `runtime` | `@jimhoyd/urlcode` | npm spec installed when the project has no `package.json` |
+| `expect-routes` | empty | `audit --expect-routes N`; empty skips the count check |
+| `compliance` | `baseline` | `baseline`, `strict`, `privacy` or `none` |
+| `compliance-rules` | empty | Absolute path to an operator rules module outside the project |
+| `compliance-warn` | `false` | Report findings without failing (`--compliance-warn`) |
+| `origin` | empty | Public origin of the deployment under review |
+| `route-diff` | `true` | Post the route diff on pull requests |
+
+Output `route-diff` is the path of the Markdown diff on a pull request, empty
+otherwise, for a later step that wants to upload or reuse it.
+
+## The sticky comment
+
+On `pull_request` events the action fetches the base commit, checks it out into
+a temporary git worktree, runs `urlcode routes` there and on the head with the
+head's runtime, and renders `routes --compare` as Markdown: one table each for
+added, removed and changed routes, or "No route changes". A changed route lists
+each differing field (handler, methods, state, middleware count, policies,
+generated marker or policy description) with its before and after value.
+
+`action/comment.mjs` then finds the pull request's comments for the marker
+`<!-- urlcode-route-diff project="<project>" -->` and updates that comment,
+or creates it on the first run. The key is the project directory, so a
+repository with several projects gets one comment per project and never a
+pile of stale ones. Updating comments needs `pull-requests: write`; on a
+fork's pull request or without that permission the API answers 403 or 404 and
+the step logs a notice and exits 0, leaving the diff in the job log. The same
+happens when the base commit is not reachable or its YAML does not load with
+the head runtime. The diff is generic: only the action knows about GitHub.
+
+## Custom compliance rules
+
+Write a rules module as [compliance](COMPLIANCE.md#writing-custom-rules)
+describes and keep it outside the audited project, because it runs as trusted
+host code. In a repository with the project at the root, put it in a sibling
+directory and pass the absolute path:
+
+```yaml
+      - uses: jimhoyd-com/urlcode/action@main
+        with:
+          expect-routes: 25
+          compliance: strict
+          compliance-rules: ${{ github.workspace }}/ci/rules.mjs
+          compliance-warn: true
+```
+
+`ci/rules.mjs` is inside the checkout but not inside the project only when
+`project` is a subdirectory; with `project: .` keep the rules in a second
+checkout or under `${{ runner.temp }}`. `compliance-rules` alone implies
+`compliance: baseline`; `compliance: none` without rules skips the compliance
+section entirely.
+
+## Exit codes
+
+The job fails when any of validate, test or audit exits nonzero; the
+[audit exit codes](COMPLIANCE.md#exit-codes) apply unchanged. The route diff
+and the comment never fail the job. A failing install (missing `@jimhoyd/urlcode`
+dependency, unavailable `runtime` spec) fails the job before any check runs.
+
+## The same checks locally
+
+```sh
+urlcode validate --project .
+urlcode test --project .
+urlcode audit --project . --expect-routes 2 --compliance baseline
+git stash && urlcode routes --project . > /tmp/base.json && git stash pop
+urlcode routes --project . --compare /tmp/base.json --format markdown
+```
+
+Or `make validate`, `make test` and `make audit ARGS='--expect-routes 2'`
+from the starter Makefile. The runtime repository exercises the action on
+every pull request against `examples/cookbook` (`.github/workflows/ci.yml`,
+job `action`) with the packed tarball as `runtime`, and `test/action.test.ts`
+checks that `action.yml` is a composite action with the inputs above and that
+every third-party action it or the starter workflow uses is pinned to a
+commit.

package/docs/CONDITIONS.md

@@ -0,0 +1,74 @@
+# Conditional routing
+
+Conditions are exact string comparisons over a bounded, portable input subset.
+A route's `match` is a conjunction: every declared query/header/cookie, host and
+method must match. A mismatch returns 404 without trying a less-specific path.
+Path precedence is unchanged; matching conditions is not authorization.
+
+```yaml
+version: "1"
+routes:
+  /beta:
+    match:
+      headers: {x-beta-user: "true"}
+    redirect: {url: https://beta.example.com}
+  /campaign:
+    conditional:
+      cases:
+        - match: {query: {source: newsletter}}
+          redirect: {url: https://example.com/newsletter}
+        - match: {query: {source: partner}}
+          redirect: {url: https://example.com/partner}
+      fallback:
+        respond: {text: "Choose a campaign"}
+```
+
+Use `conditional.cases` for multiple definitions at one path; duplicate YAML keys
+remain errors. Each case has a nonempty match and exactly one redirect/respond
+handler. The optional fallback has one of those handlers and no condition. No
+nested cases or case-local middleware/bindings/policies. Shared parameters,
+methods, response headers, middleware and policies belong to the route. A missing
+fallback returns 404. Up to 16 cases per route; pairs must be provably disjoint:
+at least one shared field must require different values. Ambiguous cases fail
+activation instead of relying on order. Cases are considered before fallback.
+
+Conditions admit query/header/cookie maps with 1–16 entries, names up to 128
+characters and values up to 1,024. Header names normalize to lowercase; duplicate
+case-insensitive names fail validation. Query strings are decoded once, have no
+type conversion or default substitution, and duplicate examined values return
+400. Examined duplicate header/cookie values return 400 when transport counts
+are available. Cookies compare unquoted wire values, without percent decoding;
+the Cookie header is bounded to 8 KiB. Missing values do not match empty strings.
+Standard authentication and transport headers cannot be predicates. There are no regex, numeric,
+geography, device, wildcard or arbitrary-code predicates.
+
+`match.host` compares the canonical authority of the **operator-configured public
+origin**, not client Host or forwarded headers. Configure the origin to use host
+conditions; one runtime does not infer multiple trusted public hosts. Methods are
+uppercase existing HTTP method tokens. A top-level match is checked before the
+route's method/handler execution; it may mask a method rejection with 404.
+
+Conditional results force `Cache-Control: no-store`; provider-specific CDN and
+surrogate cache directives cannot enable caching. Cache policies must be
+disabled or use no-store. This prevents one header/cookie branch from populating
+a shared origin or downstream cache. Route conditions and case coverage require
+explicit request fixtures; generated probes do not imply branch coverage.
+
+Self-hosted, AWS and Vercel execute the shared matcher. Node-adapter tests are
+local, not provider-deployment evidence; provider header coalescing limits still
+apply. Cloudflare refuses conditions until an artifact lowering and conformance
+tests exist. `urlcode capabilities` reports these distinctions. Operator plugins
+remain trusted host code; conditions add no guest authority.
+
+The [executable conditions project](../examples/conditions) includes explicit
+branch, fallback, duplicate and trusted-origin requests. Run:
+
+```sh
+urlcode test --project examples/conditions --origin https://conditions.example.test
+```
+
+Host names are canonical ASCII authorities (maximum 255 characters), with an
+optional nondefault port. IPv6 literals and IDN Unicode host spellings are not
+part of this initial condition syntax. Raw query comparisons remain separate
+from typed route inputs: a parameter default does not make an absent condition
+match, while all shared parameter validation still runs before a case handler.

package/docs/DEPLOYMENT-CHECKS.md

@@ -0,0 +1,108 @@
+# Verify a running deployment against the project
+
+`urlcode verify-deployment` answers one question: does the deployment behind
+`--target` behave the way this project declares? It starts the local snapshot
+(as `validate` does), sends a bounded set of HTTP requests to the target and
+compares what came back with what the snapshot says should come back. It reads
+responses only. It has no infrastructure access, uses no credential, follows no
+redirect and offers no `--insecure`.
+
+```bash
+urlcode verify-deployment --project ../my-links --target https://links.example
+urlcode verify-deployment --project ../my-links --target https://links.example \
+  --expect-routes 12 --compliance baseline --fail-on medium --timeout-ms 5000
+```
+
+Options: `--origin` (the public origin the local snapshot generates absolute
+URLs for; defaults to the target), `--expect-routes N`, `--expect-metrics`
+(the operator chose to expose `/_urlcode/metrics` publicly), `--timeout-ms`
+(per request, 100-120000, default 10000), `--fail-on high|medium|low|info|none`
+(default `high`), the `audit` compliance flags (`--compliance`,
+`--compliance-rules`, `--compliance-ignore`, `--compliance-warn`), and the
+usual `--policy` and `--link-store` bindings the local snapshot needs to start.
+
+## What it verifies
+
+Every check yields findings `{check, severity, route?, message, expected?,
+observed?}`. The report carries `checks` (assertions evaluated), `requests`
+(HTTP requests sent), `findings`, `counts` by severity, `notes` (what was
+deliberately not verified, such as compression delegated to a platform) and
+`pass`.
+
+| Check | What is compared | Severity |
+|---|---|---|
+| `probes` | `/_urlcode/health` and `/_urlcode/ready` answer 200 with `{status, version, routes}`; the deployed `version` equals the local snapshot's; the deployed route count equals the local count and `--expect-routes`; `/_urlcode/metrics` answers 404 unless `--expect-metrics` | high (metrics expected but absent: medium) |
+| `fixtures` | `tests/requests.json` and the generated native cases, sent exactly as `urlcode test --target` would: status, expected headers and expected body | high |
+| `security` | Per active literal route: every header of the effective security profile (`oshp`, `oshp-no-csp`, `set`, `unset`) with its exact value; a YAML `response.headers` value wins on a success, as it does in the runtime | high |
+| `cache` | `Cache-Control` (and `CDN-Cache-Control`) equal the strategy's emitted value; skipped where YAML or an asset handler owns the header and on function routes, whose handlers may answer `private` | medium |
+| `compression` | A second request with the declared `Accept-Encoding` on a response that is compressible (type, size at or above `minBytes`, no `no-transform`, no cookie, no secrets) carries `Content-Encoding`; on a delegated target it is noted, not checked | medium |
+| `agents` | A `User-Agent` from the denied bundled list answers the configured status on every route with an enforcing agents policy; project list files and bare patterns are not probed | high |
+| `throttle` | `RateLimit-Policy` carries the declared quota and window where the throttle is native | medium |
+| `site` | Generated `robots.txt`, `sitemap.xml`, `favicon`, `security.txt` and `llms.txt` answer 200 with the expected content type; `robots.txt` and `security.txt` bodies equal the generated file (a `Sitemap:` line missing means the deployment was started without `--origin`) | medium |
+| `methods` | A route that does not declare GET answers GET with 405 and `Allow`; a route with explicit `methods` answers OPTIONS with 405 and `Allow` | medium |
+| `head` | On a `respond` route, HEAD answers 200 with GET's `Content-Length` and no body | medium |
+| `errors` | An unmatched path (`/_urlcode-verify-<random>`) answers the runtime's 404 (`nosniff`, `no-store`) with the project-level security headers, which is also how a CDN error page or a different application shows itself | high |
+| `transport` | On an https target, `Strict-Transport-Security` is present wherever the profile emits it (the deployment must have been started with `--origin https://...`); a certificate Node rejects, a refused connection or a timeout on the health probe ends the run; a redirect whose destination is plain `http:` is reported | high (http: destination: low) |
+
+Bounds: fixtures plus generated cases, one to four requests per active literal
+route (GET, then HEAD, OPTIONS, an encoded GET or a denied User-Agent where the
+route calls for it), four probes. Concurrency is four for the route checks;
+fixtures run one at a time, as `test` does. A run refuses to start above 10000
+requests. Bodies are read up to 1 MiB and appear in the report only as the
+first 200 bytes of a failing assertion. Requests count against the
+deployment's throttle quotas: a quota smaller than the run turns later probes
+into refusals, which the report shows as fixture and header findings.
+
+## What it cannot verify
+
+- Anything not visible in a response: process settings, worker counts,
+  request logging, binding files, the proxy or CDN configuration, certificates
+  beyond Node's default chain and host-name check, DNS.
+- Routes with parameters, middleware or required inputs, except through the
+  fixtures the project supplies; the generated cases never invent business
+  data. Function bodies are verified only where a fixture asserts them.
+- Agents policies built from project list files or bare patterns, compression
+  delegated to a platform, throttle refusals (the run never exhausts a quota
+  on purpose) and cache hits (the origin cache is invisible from outside).
+- That the deployment stays this way: the report is a snapshot of one run.
+
+A passing report says the target answered like the local snapshot during the
+run. It is not a security assessment, a load test or a certification.
+
+## Exit codes
+
+`0` when no finding is at or above `--fail-on` (default `high`) and, when
+`--compliance` was given, the compliance report passes or `--compliance-warn`
+was set. `1` otherwise, and for an unreachable target, a rejected certificate,
+a target that is not a bare HTTP(S) origin, or invalid options. The report is
+printed as one JSON line after one `{"event":"finding",...}` line per finding.
+
+## How it complements audit, compliance and benchmark
+
+| Command | Runs against | Answers |
+|---|---|---|
+| `urlcode audit` | a local snapshot | are every route and method covered by passing checks, and do the counts reconcile |
+| `urlcode audit --compliance` | declared configuration | does the configuration meet the rule set |
+| `urlcode benchmark --target` | the deployment | how fast does it answer the workload |
+| `urlcode verify-deployment` | the deployment | does it answer the way the project declares |
+
+`audit` proves the project; `verify-deployment` proves the deployment is that
+project. Neither replaces the [operational drills](OPERATIONAL-PROOF.md).
+
+## A rollout gate
+
+```bash
+set -e
+urlcode audit --project . --expect-routes 12 --compliance baseline
+# deploy the candidate to the staging origin, then:
+urlcode verify-deployment --project . --target https://staging.links.example \
+  --expect-routes 12 --fail-on medium
+urlcode benchmark --project . --target https://staging.links.example --requests 500 --max-p95-ms 50
+# switch traffic, then verify the production origin the same way:
+urlcode verify-deployment --project . --target https://links.example --expect-routes 12
+```
+
+A version mismatch after the switch means traffic reaches a different
+snapshot: an old instance still serving, a cache in front of the origin, or a
+project revision that was never deployed. Roll back per
+[Operations](OPERATIONS.md#deployment-and-rollback-procedure).