@jimhoyd/urlcode 0.4.2 → 0.4.6

package/docs/COMPOSING-A-SITE.md

@@ -1,287 +0,0 @@
-# Composing a site from ui, auth and admin
-
-One command produces a site that already has accounts, an administration
-console and a presentation kit wired together:
-
-```sh
-npm install @jimhoyd/urlcode @jimhoyd/urlcode-ui @jimhoyd/urlcode-auth @jimhoyd/urlcode-admin
-urlcode init site --with ui,auth,admin
-```
-
-This page is the map of what you may then change, and with which tool. It
-covers three different activities that are easy to confuse:
-
-| You want to | Use | Code? |
-|---|---|---|
-| Change what an extension is configured to do | the `config` block in `app/urlcode.yaml` | none |
-| Change how its screens look or read | files under `<site>/ui/` | none (templates are data) |
-| Run your own logic at one of its lifecycle points | a project function named from that `config` | first-party project JavaScript |
-| Add a capability none of the three provides | a new extension package | TypeScript against the runtime contract |
-
-Work down that list, not up. The [declarative-first
-principle](PROJECT-DIRECTION.md#design-principle-declarative-first) applies
-here as much as it does to routes: reach for the next row only when the one
-above it cannot express the requirement.
-
-## What `--with ui,auth,admin` generates
-
-- `site/app/` — the route project: `urlcode.yaml` with an `extensions` block
-  per package, and `routes/extensions.yaml` holding `/assets/ui/*`,
-  `/account/*`, `/private` and `/admin/*`.
-- `site/host.mjs` — the operator host module, the one place that holds code.
-  It builds the kit with `createUiExtension`, passes the returned object into
-  `authExtension` and `adminExtension`, and lists `ui.registration` first.
-- `site/ui/` — `copy/`, `templates/` and `extra.css`, the project's
-  presentation overrides, beside the host and **outside** `app/`.
-- `site/operator-service.mjs`, `site/data/` — auth's operator service and its
-  private key material, mode `0600`.
-- `site/README.md` — the merged next steps, environment table and the project
-  revision to review and pin.
-
-Nothing about that wiring is manual any more. The generated host registers
-`authCatalogue` as a copy source and both `authUiTemplates` and
-`adminUiTemplates` as template namespaces, because auth and admin render only
-through the kit and refuse to activate without their own templates present.
-
-### Supported combinations
-
-`--with` order is the activation order, and the kit must be active before
-anything that renders through it.
-
-| `--with` | Result |
-|---|---|
-| `ui` | Kit only; the host wires no peer catalogue or templates. |
-| `ui,auth` | Accounts on `/account/*`, rendered through the kit. |
-| `ui,auth,admin` | The full composition above. |
-| `auth` or `auth,admin` | Refused: the scaffold names the missing `ui`. |
-| `auth,admin,ui` | Refused: `ui` must come before the extensions it renders. |
-| `admin` without `auth` | Refused: admin reuses auth's service, CSRF key and revision. |
-
-Every refusal happens before anything is written, and leaves no directory
-behind. There is no auth-without-ui or admin-without-ui configuration in this
-revision: the UI primitive fallback was retired, so the kit is the only render
-path (see [OPEN-DECISIONS.md](OPEN-DECISIONS.md)).
-
-## Declarative configuration
-
-Each package owns one `extensions.<name>` block. The block itself is core
-schema (`version` plus `config`); what may go inside `config` is the
-package's own JSON Schema, which you can print rather than guess:
-
-```sh
-urlcode extensions --project ./site/app --host-file "$PWD/site/host.mjs" --json
-```
-
-The same report is the MCP tool `get_extensions`, and it is the authoritative
-answer for both the configuration schema and the per-route policy schema. The
-generated site starts from something like this:
-
-```yaml
-version: "1"
-extensions:
-  ui:
-    version: "1"
-    config:
-      theme:
-        name: My Site
-      languages: [en]
-      copy: ui/copy
-      templates: ui/templates
-      stylesheet: ui/extra.css
-  auth:
-    version: "1"
-    config:
-      registration: "off"
-  admin:
-    version: "1"
-    config: {}
-```
-
-Routes mount an extension, and policies require one:
-
-```yaml
-routes:
-  /assets/ui/*:
-    extension: ui
-    methods: [GET, HEAD]
-  /account/*:
-    extension: auth
-    methods: [GET, HEAD, POST]
-  /admin/*:
-    extension: admin
-    methods: [GET, HEAD, POST]
-  /private:
-    respond:
-      text: Signed in
-    policies:
-      extensions:
-        auth: {}
-```
-
-See [EXTENSIONS.md](EXTENSIONS.md) for the `auth` route short form, extension
-middleware, and the host-file trust boundary.
-
-## Presentation overrides
-
-The `ui` config's `copy`, `templates` and `stylesheet` paths point at the
-project's own directories. Nothing here forks a package.
-
-| Override | File | Effect |
-|---|---|---|
-| Wording and translation | `ui/copy/<locale>.json` | Replaces catalogue ids, including ids the auth and admin packages own. Listed in `languages`. |
-| A whole screen | `ui/templates/<name>.html` | Shadows a kit or extension template of that name, for example `ui/templates/auth/sign-in.html` or `ui/templates/admin/dashboard.html`. |
-| Styling | `ui/extra.css` | Appended after the kit stylesheet; `{file, replace: true}` replaces it instead. |
-| Colours, logo, favicon, radius, font | the `theme` block | Declarative; no file needed. |
-
-A template is data in the kit's own language. It cannot add a script, change
-what a form validates, or change what a page sends in headers — so an override
-cannot weaken the screen it restyles. Stylesheets containing `@import`,
-`script`, `javascript:` or `expression(` are refused.
-
-Names, coverage and what the runtime will actually load:
-
-```sh
-npx urlcode-ui list --project ./site --extensions @jimhoyd/urlcode-auth,@jimhoyd/urlcode-admin
-npx urlcode-ui doctor --project ./site --extensions @jimhoyd/urlcode-auth,@jimhoyd/urlcode-admin --copy ui/copy --templates ui/templates --stylesheet ui/extra.css
-npx urlcode-ui eject auth/sign-in --out ./site/ui/templates --project ./site --extensions @jimhoyd/urlcode-auth
-npx urlcode-ui copy --missing fr --project ./site --extensions @jimhoyd/urlcode-auth --copy ui/copy --languages en,fr
-```
-
-`eject` copies the shipped source so an override starts from what ships and
-never overwrites an existing file. `ui/` lives outside `app/`, so editing copy
-or templates does **not** change the project revision and does not require
-re-pinning `PROJECT_SHA256`.
-
-**Name the packages that ship the other namespaces.** `urlcode-ui` is this
-kit alone until `--extensions` names them. Each package is resolved from
-`--project` with Node package resolution and imported for the namespace it
-exports; one that is not installed there is skipped with a note, so the
-command still runs. The site's `host.mjs` is never read: it builds services
-and reads secrets at its top level, and a read-only `list` or `doctor` must
-not run it. With the packages named:
-
-- `list` shows the `auth/*` and `admin/*` names beside the kit's own, each
-  with its origin, and `eject auth/sign-in` copies the shipped source.
-- `doctor` reports an `expected` view model for an extension template, so its
-  `behind` flag tells you when an override of one has fallen behind what
-  ships. Its `extensions` field names the namespaces the report covers, so a
-  report built without a peer is visible as such.
-- `preview auth/sign-in` renders the extension's own sample view model.
-- `copy --missing` skeletons cover the auth ids the account screens use.
-  Admin-owned `adminUi.*` ids are deliberately not offered: admin composes
-  its catalogue onto the kit's presentation rather than registering it there,
-  and those translations do not currently reach the console
-  ([#227](https://github.com/jimhoyd-com/urlcode/issues/227)).
-
-`urlcode init <directory> --with ui,auth,admin` writes these commands into the
-generated README with the flag already set. `@jimhoyd/urlcode-ui` depends on
-neither peer; the operator names them.
-
-Overrides of extension templates and of extension-owned catalogue ids reach
-the rendered screens, which is what the regression test below asserts.
-
-## Project functions: lifecycle hooks
-
-A hook is your own function, named from the extension's `config`, that the
-extension calls at a lifecycle point it defines. It uses the same source shape
-a `function` route uses — a bare path, or `{source, export}` — resolved
-relative to the route project.
-
-```yaml
-extensions:
-  auth:
-    version: "1"
-    config:
-      registration: open
-      hooks:
-        beforeRegister:
-          source: ./hooks/registration-rule.mjs
-          export: default
-        onSignUp: ./hooks/on-signup.mjs
-```
-
-`hooks` remains each package's own config, but core supplies the reference
-schema, trusted loader and machine-readable hook contract. `get_extensions`
-reports those contracts, so an agent can discover accepted names, purpose and
-input/output shapes without guessing from prose.
-
-Hooks are first-party project code and run **trusted and in-process**, the
-same default `function` and `middleware` routes have
-([FUNCTION-SECURITY.md](FUNCTION-SECURITY.md)). Extension hook contract v1 is
-trusted-only; `sandbox: true` is rejected loudly at activation.
-
-### `@jimhoyd/urlcode-ui`
-
-| Hook | Input | Returns | Called |
-|---|---|---|---|
-| `transformView` | `{template, view}` | the view object to render | Synchronously before each public `ui.kit.render()` or `ui.kit.page()` call. Use it only when theme, copy, templates and CSS cannot express the change. |
-
-For example, `transformView: ./hooks/ui-view.mjs` can add project-computed
-navigation or labels to an auth/admin view without editing either package.
-
-### `@jimhoyd/urlcode-auth`
-
-| Hook | Input | Returns | Called |
-|---|---|---|---|
-| `beforeRegister` | `{email, profile?}` | `{allow: boolean, reason?}` | Before an account is created, on `POST /account/register` and on `POST /account/signup/begin`. |
-| `onSignUp` | `{accountId, email}` | ignored | After a genuinely new account is created — on `/account/register`, and on `/account/signup/complete` only when that completion created an account rather than signing an existing one in. |
-| `onDelete` | `{accountId, email}` | ignored | After the account owner's own deletion is scheduled. Not on an administrator-initiated deletion, and not on the background purge when the grace period ends. |
-
-### `@jimhoyd/urlcode-admin`
-
-| Hook | Input | Returns | Called |
-|---|---|---|---|
-| `beforeRoleChange` | `{accountId, currentRoles, requestedRoles, actorId, reason}` | `{allow: boolean, reason?}` | Before roles are applied, after the administrator's permission check. A veto means the auth service is never asked. |
-| `onRegistrationApproved` | `{requestId, accountId, email, actorId, reason}` | ignored | After a registration request is approved. |
-| `onAccountStatusChanged` | `{accountId, status, actorId, reason}` | ignored | After an account is locked or unlocked. |
-
-### Verdicts and failure
-
-- **A veto is explicit.** A pre-action hook allows only by returning
-  `allow: true`. `allow: false`, or no verdict at all, rejects the operation
-  with `403` and the hook's own `reason`, or a generic message when it gave
-  none. Nothing is written. A hook that *throws* has not returned a verdict:
-  the operation is still refused, but as a generic `500`, so return a verdict
-  rather than throwing when you mean to deny.
-- **Broken hooks fail at activation, not at the first request.** A missing
-  module, a source path escaping the project, an export that is not a
-  function, or `sandbox: true` all throw while the extension activates, naming
-  the hook. The site does not start.
-- **A post-action hook cannot undo anything.** `onSignUp`,
-  `onDelete`, `onRegistrationApproved` and `onAccountStatusChanged` run after
-  the operation has committed. Throwing from one replaces the success response
-  with a `500` while the account, approval or status change stands. There is
-  no retry and no rollback. Keep them non-throwing: catch your own errors and
-  queue the work instead of failing the request.
-- **A hook's message is not a channel to the browser.** Only a pre-action
-  `reason` is shown. An uncaught error surfaces as a generic failure.
-- **An edited hook needs a restart.** Activation re-imports the hook's entry
-  module, so a reload picks up an edit to that file — but modules it imports
-  stay on Node's module cache, exactly as for trusted route functions.
-
-## TypeScript: implementing a new extension
-
-Only write an extension when a capability is genuinely absent — not to
-customize one of the three above. An extension is an operator-installed
-package whose host object core activates; it is named in `host.mjs`, never
-in YAML. The contract, the activation inputs, `ExtensionActivation.root`,
-credential headers and the `projectSha256` pin are in
-[EXTENSIONS.md](EXTENSIONS.md) and [TYPESCRIPT.md](TYPESCRIPT.md); the
-`scaffold` export that makes a package work with `init --with` is in
-[EXTENSIONS.md](EXTENSIONS.md#scaffolding-with-init---with).
-
-If its screens should be themeable the same way auth's and admin's are, it
-also exports a template namespace (and, if it ships English wording, a
-catalogue) for a host to pass to `createUiExtension`. That is what makes
-`ui/templates/<yourname>/<screen>.html` work in a consumer project without a
-fork.
-
-## What this page does not claim
-
-The composition, the refusals and the override path are exercised by
-`test/workspace-scaffold.integration.ts`, which runs `init --with` against the
-built packages, drops a template and a copy catalogue into the generated
-`ui/` directory and asserts both reach a rendered auth screen and a rendered
-admin screen. That runs in-process against the generated host: no HTTP
-listener, TLS proxy, browser or deployed site is exercised, and no published
-npm tarball is checked against this checkout.

package/docs/CONDITIONS.md

@@ -1,74 +0,0 @@
-# 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/CONTAINER-PROMOTION.md

@@ -1,74 +0,0 @@
-# Container image promotion (design, issue #233)
-
-Status: design plus an inert helper. Nothing described under "Proposed" is
-implemented, and no workflow was changed. This does not authorize enabling
-`PUBLISH_CONTAINER`, publishing, or changing any existing tag. The point is
-supply-chain integrity (tested bytes are shipped bytes), not speed: the sampled
-CI image build took about 12 seconds, so build caching is deliberately out of scope.
-
-## Current behavior (read from the workflows at 67a6996)
-
-- `ci.yml` job `container` (a required check) runs `docker build -t urlcode:test .`
-  and smoke-tests it. That image is discarded; no digest is recorded.
-- `candidate.yml` builds and signs the npm archives, SBOM and manifests. It builds no
-  image. `manifest.json` and the exact-file-set check in `validateCandidate` know nothing
-  about images.
-- `release.yml`, only when `vars.PUBLISH_CONTAINER == 'true'`, runs a fresh
-  `docker build` of the tagged commit with `revision`/`version` labels and pushes
-  `:VERSION` and the channel tag.
-- On retry, if `:VERSION` already exists it is accepted after checking only the
-  `revision` label. A label is asserted by whoever built the image, so a differently
-  built image with the same label passes. Bytes are not compared.
-- Channel monotonicity is enforced by reading the `version` label of the existing
-  channel tag (semver `gte`). That guard is sound and should be kept.
-- A rebuild is not byte-reproducible (it runs `npm ci`, embeds timestamps), so the image
-  the release publishes is never the image CI tested, even for the same commit.
-
-Not verified: live GHCR contents, package visibility/permissions, whether
-`PUBLISH_CONTAINER` is set, and whether any image was ever pushed.
-
-## Proposed path (not implemented)
-
-1. Candidate build. In `candidate.yml`, build the image once from the exact commit
-   (`docker buildx build --output type=oci,dest=candidate/image.oci.tar` with the
-   revision/version labels), run the same three smoke tests as `ci.yml` against that
-   archive, and record `image: { digest, sourceCommit, version }` in `manifest.json`.
-   Add `image.oci.tar` to the attested subjects so the existing `attestation verify` and
-   the manifest SHA-256 pinned in the annotated tag cover the image as well.
-2. Manifest schema. Add the archive to the expected file set in `validateCandidate`
-   and validate the record with `candidateImage()` from `scripts/release-image.ts`.
-   Because the tag pins the manifest hash, the digest is immutable once tagged.
-3. Promotion. `release.yml` verifies the bundle (already done by `restore`), then copies
-   the archive to the registry preserving the manifest digest (`skopeo copy` or
-   `crane push` of the OCI layout; not `docker load` then `docker push`, which can
-   change digests under some storage drivers) and pushes `:VERSION` and the channel tag
-   as pointers to that digest. It never runs `docker build`.
-4. Retry identity. If `:VERSION` exists, resolve its digest with
-   `docker buildx imagetools inspect` and require `assertPromotedImage()` to pass. A
-   rebuilt image with matching labels but different bytes is refused. Channel tags keep
-   the existing `assertChannel` check via `assertImageChannel()`.
-5. Attestation. Optionally attest the image digest with `actions/attest` using
-   `push-to-registry`; this needs `packages: write` and its GHCR behavior is unverified.
-6. Self-hosting. The `Dockerfile` and `docker build` remain the documented way to build
-   from source. CI's `container` check stays as is to preserve the required check name.
-
-## What the inert helper proves
-
-`scripts/release-image.ts` and `test/release-image.test.ts` are pure functions and unit
-tests. They pin the invariant (promoted digest equals tested digest; labels match;
-channel never regresses; a same-label different-bytes image is rejected). No workflow
-imports them, so the release path is unchanged.
-
-## Could not establish
-
-- Whether GHCR preserves the OCI digest through `skopeo`/`crane` from the runner, and
-  whether the org's package settings permit it.
-- Behavior of image attestation and OIDC for GHCR.
-- Whether a candidate-built OCI archive fits comfortably within the artifact size and
-  90-day retention model; recovery from GitHub release assets would need the archive
-  attached there too.
-- Any real run: none was dispatched.
-
-A first implementation should be a separate reviewed PR that lands the candidate-side
-build behind an operator-controlled input, and leaves the publisher change until one
-candidate has been produced and inspected.

package/docs/DEPLOYMENT-CHECKS.md

@@ -1,108 +0,0 @@
-# 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` binding 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).