@jimhoyd/urlcode 0.4.2 → 0.4.7

package/docs/CODEBASE-AUDIT-2026-09-20.md

@@ -1,284 +0,0 @@
-<!-- trust-model-prose: historical-file -->
-<!-- This report quotes the defective wording it is reporting -- including the
-     pre-trusted-default claims in finding 4 -- so the prose gate would read the
-     quotations as the guidance itself. The file is a dated review of one
-     commit and is not edited as the defects are fixed. -->
-
-# Codebase, tooling and documentation audit — 2026-09-20
-
-Reviewed commit: `bca8ac7` (core 0.4.0-alpha.2, auth 0.1.0-alpha.5,
-admin 0.1.0-alpha.4, UI 0.1.0-alpha.6). Local environment: macOS,
-Node 26.8.2. Date is UTC. This report records findings; it does not change
-runtime behavior or remove supported features.
-
-The trusted default is implemented correctly in the dispatch paths inspected:
-only a route declaring `sandbox: true` enters the QuickJS pool. Ordinary
-project functions and middleware run in Node. Host access by trusted code is
-intentional, not an audit finding. Binding grants scope injected context;
-they do not confine trusted code's independent filesystem, environment or
-network access. Opt-in sandbox isolation and provider refusals remain necessary.
-
-## Scope and method
-
-Inventoried 966 tracked files. Reviewed the implemented specification,
-contribution/security instructions, runtime activation/dispatch, module loading,
-TypeScript authoring, inspection/manifests/diffs, extension hooks, workspace
-contracts, package/build/check scripts, CI/release configuration, starter,
-example/recipe coverage and documentation indexes. Used targeted source review,
-the complete local verification suite and synthetic reproductions. This is a
-repository-wide engineering audit, not a claim that every line or execution
-path received independent security review.
-
-Scanned tracked non-archive/non-spike Markdown for local links and YAML fences:
-64 YAML fences, 49 route/project-shaped candidates. Added only an omitted
-format version or the documented route wrapper for schema checks. Classified
-partial illustrations separately from complete examples. Semantic constraints,
-external services and prose fragments require more than schema validation.
-
-Searched existing repository issues before filing. Five new issues and new
-evidence on existing issue 168 retain all actionable findings below.
-
-## Findings, ordered by practical impact
-
-### 1. Inspection hides middleware execution-mode changes — P2
-
-[Issue 199](https://github.com/jimhoyd-com/urlcode/issues/199).
-
-For a `respond` route with `middleware: [mw.mjs]`, switching `sandbox` from
-true to false produces identical manifest route records and an empty route
-diff. This changes execution from QuickJS to full Node without appearing in
-those review surfaces. The overall manifest digest can change; it does not
-explain the change to reviewers.
-
-`src/explain.ts` adds sandbox information only inside the function-handler
-case. `src/manifest.ts` carries that handler object forward, while
-`src/readiness.ts` and `src/route-diff.ts` omit execution mode from inventory.
-Context already exposes it at route level.
-
-Reproduction: create the same middleware/native route in both modes, call
-`buildManifest`, obtain `createRuntime(...).testPlan()`, then call `diffRoutes`.
-Observed diff: `{"added":[],"removed":[],"changed":[]}`. Add route-level
-execution mode/reason to explain, manifest and inventory, with compatibility
-handling for older inventory files and regressions for both handler kinds.
-
-### 2. Auth/admin hook reactivation serves stale entry code — P2
-
-[Issue 198](https://github.com/jimhoyd-com/urlcode/issues/198).
-
-Both `packages/auth/src/lifecycle-hooks.ts` and
-`packages/admin/src/admin-hooks.ts` import an unchanged file URL. Loading a
-hook, editing its entry file, then loading it again in the same process returns
-the old hook. A synthetic decision changed on disk from allow/v1 to deny/v2;
-both loaders still returned allow/v1 after reactivation.
-
-Native trusted routes already give entry modules a new URL per activation.
-Apply an explicit hook reload policy and test it, or clearly require process
-restart for hook changes. This reproduction exercised the loaders directly,
-not the end-to-end development watcher and account flow. Transitive Node module
-caching is a separate, already documented limitation. Keep trusted execution
-as the default and reject unsupported sandbox hooks explicitly.
-
-### 3. TypeScript authoring rejects valid mixed-trust module reuse — P2
-
-[Issue 197](https://github.com/jimhoyd-com/urlcode/issues/197).
-
-`src/typescript-authoring.ts:34` assigns each source one trust mode and rejects
-reuse from a different mode. Two routes sharing a pure `f.ts`, one trusted and
-one sandboxed, fail with “Module is imported by both a sandboxed and a trusted
-route”. The equivalent JavaScript project activates and both routes return
-200/ok. Shared transitive helpers have the same restriction.
-
-Separate emission deduplication from sandbox reachability validation. A helper
-reachable by a sandboxed route must still satisfy all sandbox import/source
-budgets; trusted execution must not be downgraded or unnecessarily restricted.
-Also reconcile the documented unlimited trusted source size with the builder's
-16 MiB per-file authoring cap.
-
-### 4. Live guidance still contradicts trust by default — P2
-
-[Issue 196](https://github.com/jimhoyd-com/urlcode/issues/196).
-
-- `docs/yaml/functions.md:57` denies Node/npm/network/filesystem APIs immediately
-  after an ordinary trusted route example.
-- `docs/yaml/middleware.md:26` describes a mandatory shared sandbox.
-- `docs/MIDDLEWARE.md:49` applies guest clone/body restrictions without scoping
-  them to sandboxed execution. Reproduced: trusted middleware reads a native
-  response body and returns its uppercase text; the sandboxed version rejects
-  that operation.
-- `docs/SPECIFICATION.md` says `.js` ESM behavior is independent of package
-  settings. Reproduced: ESM `f.js` under `type: commonjs` fails trusted activation
-  and works in the sandbox. Ordinary Node resolution is the intended default;
-  the documentation should explain `.mjs` and package type accurately.
-- `README.md` and `docs/FRAMEWORK.md` overstate binding grants as the only way
-  secrets reach code. Scope that statement to injected bindings.
-- `docs/READINESS.md` calls the activated runtime isolated; the first test in
-  `test/typescript-authoring.test.ts` claims QuickJS execution but omits sandbox.
-
-The prose guards pass this revision despite these contradictions. Strengthen
-specific regression fixtures and fix the guidance; do not impose old sandbox
-restrictions on trusted code to make the prose true.
-
-The POST/body-based sandbox advisory is a related cleanup candidate. It is
-non-blocking and documented, but suggests isolation from request shape rather
-than evidence about code trust. Review whether to remove or reword it while
-retaining explicit `sandboxReason` information. This is a recommendation, not
-a discovered isolation failure.
-
-### 5. Copyable documentation examples fail validation — P2
-
-[New evidence on issue 168](https://github.com/jimhoyd-com/urlcode/issues/168#issuecomment-5747024306).
-
-- `docs/yaml/policies.md:18` uses `page.source`; the field is `page.file`.
-- `docs/policies/compression.md:35` uses `secret: api-key`, rejected by the
-  external binding-name grammar; an identifier such as `api_key` is admitted.
-- `docs/AI-AUTHORING.md:249` omits the leading slash on `webhooks/stripe`.
-  This also illustrates why schema checks alone cannot replace semantic route
-  validation. The same section still lists the retired `link` handler.
-
-The first two are complete fenced projects and fail `validateDocument`.
-The partial profile illustration in `docs/POLICIES.md:169` was excluded from
-findings because it deliberately omits a handler. Add classified executable
-snippets: complete projects, context-dependent fragments and intentionally
-invalid examples. Existing cookbook tests do not validate every prose example.
-
-### 6. Monorepo ownership, navigation and release prose need cleanup — P3
-
-[Issue 200](https://github.com/jimhoyd-com/urlcode/issues/200).
-
-- Package AGENTS files still direct findings to former package repositories.
-- Framework/status pages retain former source homes, old alpha combinations,
-  private cross-repository credential instructions and peer-pin language.
-- Two admin README links target nonexistent package-local release workflows.
-- Documentation navigation duplicates cookbook entries with conflicting 25/40
-  counts; llms.txt repeats semantics and TypeScript entries.
-- Hook comments claim core lacks a sandbox primitive although SandboxPool is
-  exported. The packages still explicitly reject sandboxed hooks; update the
-  reason and tracked work rather than claiming they already support them.
-
-Use local links and one canonical version/ownership inventory for live material;
-keep dated release evidence clearly historical. Consolidate the duplicate
-SQLite preflight predicates through development tooling without removing auth's
-runtime gate. Shorten repeated issue-history narration in implementation comments
-where a contract explanation and issue link are sufficient.
-
-Do not remove the supported UI primitive fallback, opt-in sandbox path, provider
-compatibility refusals, licenses or regression fixtures. No dead production module
-was established with enough evidence to recommend deleting it in this audit.
-
-## Verification evidence
-
-The final sequential `npm run verify` passed, including lint, strict typecheck,
-syntax/JSON/catalog checks, generated-document checks, workspace links, release
-checks, build, core tests and all workspace suites:
-
-| Suite | Passed | Skipped | Failed/cancelled |
-|---|---:|---:|---:|
-| Core | 518 | 1 | 0 |
-| UI | 57 | 0 | 0 |
-| Auth | 207 | 0 | 0 |
-| Admin | 68 | 0 | 0 |
-| Workspace scaffold integration | 1 | 0 | 0 |
-
-Total: 851 passed, one intentional HTTPS-deployment test skip. The integration
-test checks scaffold composition; it is not a live provider deployment.
-
-`npm run test:package` passed installation of the packed archive and
-starter/cookbook/authoring-consumer checks. Separate CLI HTTP fixture runs passed
-for the starter, assets, cookbook, Vercel, AWS, Cloudflare, conditions (with its
-documented public origin) and prerender source. The cookbook count audit passed
-with 40 routes. Extension, fake-egress, monitoring, provider-conformance and
-tunnel examples are also exercised by their dedicated core tests.
-
-`npm audit --omit=dev --json`
-reported zero known runtime advisories at audit time. Neither substitutes for
-source review or establishes absence of unknown vulnerabilities.
-
-The initial restricted-environment run could not run local HTTP tests. A first
-unrestricted run had five test-file cancellations; those files passed alone.
-An overlapping build also caused transient missing-declaration errors in a
-workspace run. The final sequential full run passed without cancellations.
-These intermediate results are not reported as confirmed product defects.
-
-## Remaining evidence boundaries
-
-No provider account was deployed, no release published, no production system
-probed, and no container/Windows/Linux/Node 22 or 24 run was performed locally.
-Live email/OIDC/passkey services, accessibility/browser/device assessment,
-operational recovery/soak evidence and independent sandbox review remain separate.
-Existing issues 58, 173, 174 and 185 already retain relevant acceptance,
-model-benchmark, schema-discovery and release/CI-evidence work; this audit does
-not close those gates.
-
-## Follow-up: dead-code reachability
-
-[Issue 203](https://github.com/jimhoyd-com/urlcode/issues/203) records a dedicated
-unused-code pass requested after the initial audit. Runtime source remains the
-same as the reviewed revision; the intervening commit only added this report.
-
-A conservative relative-reference graph rooted at package exports and CLI entry
-points reached all 157 tracked production TypeScript modules. Every direct
-runtime dependency has a production source reference, and every root script
-has a named reference elsewhere in the repository. No whole production file,
-runtime dependency or root script was established as removable.
-
-A TypeScript symbol/reference pass excluded 501 symbols exposed by public
-package entrypoints. Candidates were then checked with repository-wide search
-and manual inspection, including local uses, CLI imports, namespace dispatch,
-worker URLs and dynamically loaded agent-list code. The confirmed small removals
-are:
-
-| Declaration/plumbing | Evidence | Proposed cleanup |
-|---|---|---|
-| `src/capability-query.ts:47`, `capabilityNameList()` | Declaration only; no caller or public entry export | Delete the unused wrapper |
-| `src/catalog.ts:39`, `metadataFiles` | Declaration only; no reader or public entry export | Delete the unused constant |
-| `src/trusted-functions.ts`, `log` option/property | Assigned but never read | Remove this unused executor plumbing, preserving runtime observer/logging behavior |
-| `src/mcp-authoring.ts:57`, `expandHandler(path, handler)` | `path` is never read | Remove the argument and update callers |
-| `src/policies/cache.ts:201`, `revalidate(state, req, result)` | `state` is never read | Remove the argument and update callers |
-
-Several live implementation helpers are unnecessarily exported: admin's
-`activeKit`, core's `routeState`, `forbiddenHeaders`, `normalizeRoute`,
-`manifestFileName`, and local scaffold/render/name helpers in `init-with.ts`.
-These are candidates for removing export modifiers, not deleting their bodies.
-Check declaration dependencies before changing exported types.
-
-An additional TypeScript check with `--noUnusedLocals --noUnusedParameters`
-reported six unused parameters: the two production helpers above and four test
-callbacks. It reported no unused local declarations. This stricter exploratory
-check is separate from the normal passing typecheck.
-
-Public APIs with no internal callers, types used in public signatures, registry
-policy hooks, dynamic imports, supported UI fallback rendering and opt-in sandbox
-execution are not dead code. This reachability analysis does not prove that
-every branch executes. No production code was removed by this follow-up.
-
-## Follow-up: unnecessary files and distribution weight
-
-[File-level evidence on issue 200](https://github.com/jimhoyd-com/urlcode/issues/200#issuecomment-5747116642).
-
-One package-local script is obsolete: `packages/admin/scripts/peer-revisions.mjs`.
-It has no workflow/package-script caller and reads the deleted admin `peers.json`;
-executing it fails with ENOENT. Its only other named reference is historical
-monorepo prose. Remove it; workspace linking replaced its cross-repository
-revision-output mechanism. The earlier root-script scan did not cover this
-package-local leftover.
-
-The three package `CODE_OF_CONDUCT.md` files are byte-identical to the root copy
-(1,062 bytes each). Consolidate their links to the root policy before deleting
-the duplicates. Package governance also repeats repository-wide controls and
-can link to the root while retaining any package-specific information. Package
-licenses and attribution notices serve a different purpose and must stay.
-
-A dry-run npm package inventory includes 11 archived documentation files
-(179,666 bytes) and six design-spike files (184,792 bytes): about 356 KiB
-uncompressed combined. The audit report also ships because package.json includes
-all of docs. Consider excluding maintainer/history/design records from npm
-while retaining them in Git and keeping their references navigable. These
-figures are content sizes, not estimates of compressed download savings.
-
-The duplicate Claude plugin skills are intentional, checked distribution copies;
-cookbook/recipe copies make each project independently usable; upstream UI
-snapshots preserve attribution/provenance; the benchmark baseline is consumed
-by its gate. None is established as unwanted. No tracked build output,
-node_modules, tarballs, logs, backup files or TypeScript build-info files were
-found. Ignored local dependencies/build products are regenerable development
-output, not tracked repository clutter. No files were deleted in this audit.

package/docs/COMPLIANCE.md

@@ -1,239 +0,0 @@
-# Compliance rules
-
-A compliance rule is a standards-referenced check over what a project declares
-and what the runtime knows about it: the parsed YAML, the route inventory and
-policy table from `testPlan()`, the effective policy per route, the public
-origin and the logging settings the operator states for the deployment. The
-runtime ships three built-in profiles; an operator adds, overrides or disables
-rules with code kept outside the project, the same trust boundary as
-[plugins](PLUGINS.md) and the `--policy` binding grant; `urlcode audit` prints
-every finding with the reference it rests on and sets the exit code.
-
-## What it is and is not
-
-- It checks **declared configuration and runtime facts**. No rule sends a
-  request, reads a binding, runs guest code or inspects a running deployment.
-  `oshp/hsts-origin` cannot know your TLS terminator; it knows the origin you
-  declared with `--origin`, so declare it truthfully.
-- A passing run is **not a certification**, an audit opinion or evidence that
-  a deployment is secure or lawful. It says the declared configuration matches
-  a rule set whose references are listed beside each finding. Deployment,
-  soak and recovery proof live in [release readiness](RELEASE-READINESS.md).
-- Rules never change behavior. The runtime serves the same responses whether a
-  finding exists or not; a rule set is an operator's review checklist in code.
-- The built-in rules only check what the runtime can see. Anything a rule
-  cannot verify (an undeclared log level, an unknown origin) is reported as an
-  `info` finding saying so, never assumed to pass.
-
-## The rule contract
-
-```js
-export const rules = [{
-  id: 'acme/redirect-hosts',        // ^[a-z][a-z0-9-]{0,31}/[a-z][a-z0-9-]{0,63}$, unique per run
-  title: 'Redirects only leave for approved hosts',
-  standard: { name: 'ACME link policy', reference: 'https://example.com/policies/links', section: 'Outbound' },
-  severity: 'high',                 // high | medium | low | info
-  appliesTo: 'route',               // project | route
-  check(context) { return []; },    // findings[]; may be async
-}];
-```
-
-`standard.reference` is a URL, an RFC number (`RFC 9110`) or a path under
-`docs/`. `check` returns an array of findings (an empty array, `undefined`,
-a single finding or an array); a thrown error fails the run with the rule
-named, so a rule cannot silently pass by crashing.
-
-A **project** rule runs once with:
-
-| Field | Value |
-|---|---|
-| `document` | The parsed and validated `urlcode.yaml` (includes are merged into `routes`) |
-| `routes` | Route configuration by pattern, as written in YAML |
-| `plan` | `testPlan()`: `inventory[]` (`path`, `handler`, `methods`, `middleware`, `policies`, `state`), `policies` (the per-route describe map) |
-| `policies` | `effectivePolicies(document, route)` by pattern: the merged configuration of every policy on each route |
-| `origin` | The declared public origin, or `null` |
-| `target` | `node` unless the caller states another |
-| `host` | `{ requestLog }` as declared for the deployment; `null` where undeclared |
-
-A **route** rule runs once per inventory entry and additionally receives
-`route` (the inventory entry), `config` (that route's YAML), `policy` (the
-runtime's describe map for the route: `security.emits`, `agents.deny[].revision`,
-`cache.cacheControl`, …) and `effective` (the merged policy configuration).
-
-A **finding** is `{ rule, severity, route?, message, remediation, standard }`.
-`severity` defaults to the rule's own; a check may lower or raise it for one
-finding (the privacy rules report an undeclared setting as `info`). The
-runtime fills `rule` and `standard` and the route pattern for route rules.
-
-## Built-in profiles
-
-`strict` contains every `baseline` rule plus its own; `privacy` stands alone;
-`none` runs only operator rules. Check derivations reference the runtime's
-own code: the security profile tables in `src/policies/security.ts`, the
-cache and compression secrets handling in `src/policies/cache.ts` and
-`src/policies/compression.ts`, the `no-store` default in
-`src/http-response.ts`, the 16 KiB header cap in `src/http-policy.ts`.
-
-### `baseline`
-
-| Rule | Standard | Severity | Checks | Remediation |
-|---|---|---|---|---|
-| `oshp/security-headers` | [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/) | medium | Every active route has an effective `policies.security` | Declare `policies.security: { headers: oshp }` on the project or the route |
-| `oshp/hsts-origin` | OWASP Secure Headers Project, Strict-Transport-Security | low | When any active route's security profile emits HSTS, the declared origin is `https:`; the runtime emits HSTS only then | Serve behind TLS and declare `--origin https://…` |
-| `breach/secrets-compression` | [BREACH](https://www.breachattack.com/) | high | No route binding `secrets` sets `policies.compression.allowWithSecrets` | Remove `allowWithSecrets` (the runtime then skips compression on secret routes) |
-| `rfc9111/secrets-no-store` | [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111) §5.2.2.5, §5.2.2.7 | medium | A route binding `secrets` declares no cache strategy, Cache-Control or handler `cacheControl` other than `no-store`/`private` | Use `no-store` or `private` on secret routes |
-| `rfc9111/cache-control-declared` | RFC 9111 §5.2 | low | `respond` and `redirect` routes declare a `Cache-Control` header or a cache policy; asset handlers declare `cacheControl` (otherwise the runtime defaults `no-store` / assets `no-cache`) | State the intent in `response.headers`, the handler or `policies.cache` |
-| `rfc6585/throttle-functions` | [RFC 6585](https://www.rfc-editor.org/rfc/rfc6585) §4 | medium | Every active function or middleware route has an effective `policies.throttle` | Declare a throttle on the route or the project |
-| `rfc9309/robots` | [RFC 9309](https://www.rfc-editor.org/rfc/rfc9309) | low | Some active route declares `policies.agents`, or an active `/robots.txt` `respond` route exists | Add a `/robots.txt` route or an agents deny list |
-| `rfc9110/expired-routes` | [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110) §15.5.11 | info | Lists routes past `expires` that still answer 410 | Remove them once the 410 window has served its purpose |
-
-### `strict` (baseline plus)
-
-| Rule | Standard | Severity | Checks | Remediation |
-|---|---|---|---|---|
-| `oshp/csp` | OWASP Secure Headers Project, Content-Security-Policy | medium | Every active route emits `Content-Security-Policy` (security profile minus `unset`, plus `set`, or a YAML response header) | Use the `oshp` profile or set the header |
-| `rfc6585/throttle-all` | RFC 6585 §4 | medium | Every active non-function route has an effective throttle (function routes are covered by `throttle-functions`) | Declare `policies.throttle` at the project level |
-| `agents/lists-pinned` | [Bundled agent lists](policies/agents.md) | low | Every agents deny/allow list is a bundled list that carries an upstream revision; project `.json` list files report `revision: project` | Prefer bundled lists or record the revision a list was built from |
-| `rfc9110/redirect-https` | RFC 9110 §15.4 | medium | No active `redirect.url` starts with `http:` | Redirect to https |
-| `http/header-budget` | RFC 9110 §5.4 | low | YAML `response.headers` bytes plus the security profile's static bytes stay at or under 8192, half the runtime's 16 KiB response header cap | Trim headers or the security set |
-
-### `privacy`
-
-These rules check deployment settings, so `audit` takes `--request-log` to
-declare the level the deployment uses (the audit process itself always logs
-nothing); embedders pass `host` themselves. The references are the runtime's
-own [logging guarantees](MONITORING.md): records carry no URL, query, header,
-body or binding, and `detailed` adds only the method and route pattern.
-
-| Rule | Standard | Severity | Checks | Remediation |
-|---|---|---|---|---|
-| `privacy/request-log-minimal` | [Monitoring](MONITORING.md), Log records | medium (`info` when undeclared) | `host.requestLog` is `minimal` | Use the default log unless per-route rates are required |
-| `privacy/detailed-log-parameters` | [Monitoring](MONITORING.md), Log records | low | With `detailed` logging, no active route takes parameters (records name the pattern and method, never values) | Keep `minimal` on parameterised deployments |
-
-## Writing custom rules
-
-[`examples/compliance/rules.mjs`](../examples/compliance/rules.mjs) is a
-complete operator module; it runs against the cookbook:
-
-```sh
-node src/cli.ts audit --project examples/cookbook \
-  --compliance baseline --compliance-rules "$PWD/examples/compliance/rules.mjs" --compliance-warn
-```
-
-A module exports up to three names:
-
-```js
-export const rules = [ /* rules to add; an id already in the profile is an error */ ];
-export const disable = ['rfc9110/expired-routes'];               // remove built-in or added rules by id
-export const override = { 'oshp/security-headers': { severity: 'high' } }; // shallow-merge fields of an existing rule
-```
-
-Order is fixed: profile rules, then `rules` added, then `override` applied,
-then `disable` removed, then `--compliance-ignore`. The result is validated
-as one set, so an override cannot produce an invalid rule.
-
-The module must be an absolute path to an `.mjs`/`.js` file **outside** the
-audited project, checked the way `--policy` is (`realpath` of both, the file
-may not resolve inside the project root). It is imported as trusted operator
-code with the host's privileges, the same standing as a plugin: a project
-cannot ship its own rule set and grade itself. Rules read the context they
-are given; a rule that reaches for the filesystem or the network is a plugin
-in the wrong place.
-
-## CLI
-
-```
-urlcode audit [--project dir] [--compliance baseline|strict|privacy|none]
-              [--compliance-rules /absolute/rules.mjs] [--compliance-ignore id,id]
-              [--compliance-warn] [--origin https://links.example] [--request-log minimal|detailed]
-```
-
-Without any compliance flag the audit report is unchanged apart from
-`compliance: null`. With one, the report gains a `compliance` section:
-
-```json
-{ "profile": "baseline", "rules": 9, "ruleIds": ["oshp/security-headers", "…"], "ignored": [],
-  "findings": [{ "rule": "rfc6585/throttle-functions", "severity": "medium", "route": "/hello/{name}",
-                 "message": "…", "remediation": "…", "standard": { "name": "RFC 6585 …", "reference": "…", "section": "…" } }],
-  "counts": { "high": 0, "medium": 4, "low": 11, "info": 1 }, "pass": true,
-  "evidence": { "routes": 21, "active": 19, "policies": ["agents", "cache", "security", "throttle"],
-                "files": ["urlcode.yaml", "routes/code.yaml"], "origin": null, "target": "node",
-                "host": { "requestLog": "minimal" },
-                "scope": "declared configuration and runtime facts; not a deployment or certification" } }
-```
-
-`--compliance-rules` alone implies `--compliance baseline`. `--origin` and
-`--request-log` describe the deployment under review and are echoed in
-`evidence`. Findings are sorted by severity, rule and route.
-
-### Exit codes
-
-| Condition | Exit |
-|---|---|
-| Readiness failed (`ready: false`) | 1, as before |
-| A `high` finding and no `--compliance-warn` | 1 |
-| `--compliance-warn`: findings are printed, `pass` is still `false` | 0 unless readiness failed |
-| Unknown profile, rules file inside the project, malformed rule or ignore id | 1 with an `error` event on stderr |
-
-## Programmatic API
-
-```js
-import { runCompliance, builtinProfiles, validateRules, resolveRules, loadComplianceRules } from '@jimhoyd/urlcode/compliance';
-import { createRuntime } from '@jimhoyd/urlcode';
-
-const runtime = await createRuntime('./site');
-const report = await runCompliance(runtime, {
-  profile: 'strict',                                  // baseline | strict | privacy | none
-  rules: [], override: {}, disable: [],               // as a rules module would export them
-  ignore: ['rfc9110/expired-routes'],
-  origin: 'https://links.example',
-  host: { requestLog: 'minimal' }, // what the deployment is configured with
-});
-await runtime.close();
-```
-
-The declarations ship with the package: `ComplianceRule` (with `ProjectRule`
-and `RouteRule`, and `ProjectContext`/`RouteContext` for what `check`
-receives), `RawFinding` and `Finding`, `ComplianceOptions`, `ComplianceReport`
-and `ComplianceProfileName` are all exported from `@jimhoyd/urlcode/compliance`, so a
-rules module written in TypeScript is checked against the same contract the
-runtime validates at load time:
-
-```ts
-import type { ComplianceRule, ComplianceReport } from '@jimhoyd/urlcode/compliance';
-import { runCompliance } from '@jimhoyd/urlcode/compliance';
-
-export const rules: ComplianceRule[] = [{
-  id: 'acme/redirect-hosts',
-  title: 'Redirects only leave for approved hosts',
-  standard: { name: 'ACME link policy', reference: 'https://example.com/policies/links', section: 'Outbound' },
-  severity: 'high',
-  appliesTo: 'route',
-  check(context) {
-    if (context.config.redirect?.url.startsWith('https://acme.example/')) return [];
-    return [{ message: `${context.route.path} redirects outside the approved hosts`, remediation: 'Point the redirect at an approved host' }];
-  },
-}];
-const report: ComplianceReport = await runCompliance(runtime, { profile: 'strict', rules });
-```
-
-`runCompliance` accepts a started server from `startServer` or a runtime from
-`createRuntime`; it re-reads the YAML from the runtime's `root` and takes the
-plan from `testPlan()`, so rules see what the runtime compiled.
-`auditProject(app, { compliance })` runs the same and attaches the report
-under `compliance`. `builtinProfiles` maps profile names to their frozen rule
-arrays for reuse or inspection; `validateRules` checks a rule array;
-`resolveRules` builds the final set from a profile and operator additions.
-
-## Extending with a plugin-style workflow
-
-Keep rule modules where you keep plugins: in the operator application, under
-version control, reviewed like code, outside every audited project. A shared
-module can export rules that read the same policy tables a plugin's
-`onActivate(runtime)` sees through `testPlan()`, so one review of "what does
-this runtime enforce" serves both. Compose organisation rules on top of a
-built-in profile with `override` for stricter severities and `disable` for
-rules that a documented decision replaces, and run `urlcode audit
---compliance strict --compliance-rules …` in CI with the exit code as the
-gate. Record the report beside the readiness and benchmark evidence for the
-revision; a report proves what was declared at that commit, nothing more.