@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

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,192 @@
+# 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
+urlcode capabilities --target static
+```
+
+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`, `extension`, `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 (no artifact lowering yet) and by `static` (no server to match a
+request against). `extension`/`policies.extensions` report per-extension
+support from the registered extension's own declared `targets` when a
+`--host-file` is supplied; without one they report `conditional`/`unknown`
+rather than a blanket answer. See [egress](EGRESS.md) and
+[conditions](CONDITIONS.md).
+
+| Support | Meaning |
+| --- | --- |
+| native | Implemented by the local runtime or Node adapter |
+| compiled | Implemented by the Cloudflare or static-hosting compiler and its runtime/build output |
+| 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,
+Cloudflare and static 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; `static` has
+no server at all, so it refuses every capability that needs one (parameters,
+request bodies, response headers, bindings, every `policies.*`) in addition to
+`function`/`middleware`. See [Cloudflare](CLOUDFLARE.md), [AWS](AWS.md),
+[Vercel](VERCEL.md) and [static hosting](STATIC.md) for transport and fidelity
+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. `analyzeProjectCapabilities`/`analyzeCompiledCapabilities` take an
+optional resolved extension registration set (the same shape `--host-file`
+loads); pass it to get per-extension `refused`/`native` from that extension's
+own `targets` instead of the generic `conditional`/`unknown` answer.
+`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 + trusted or isolated function dispatch, 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.
@@ -13,16 +13,56 @@ lookup after path parsing). Parameter candidates are grouped by segment count
 and scanned in specificity order; matching is O(P × L) in the worst case for P
 candidates and L segments. Static mount prefixes are scanned longest first.
 
-Plain redirects, declared responses, stored-link lookups and assets do not enter
-the sandbox. Stored links use a separate bounded database pools. A
-function or any attached middleware occupies one shared worker slot for its
-whole chain. Workers are shared by all programmable routes in that snapshot;
-there is no per-route fairness or reserved capacity. Awaiting guest timers still
-occupies the slot. A fresh guest and module initialization are part of each call.
+Plain redirects, declared responses and assets do not enter
+the sandbox or the trusted executor.
+
+`function`/`middleware` routes have **two distinct capacity models**, chosen
+per route by `sandbox` (docs/SPIKE-DEFAULT-TRUST-MODEL.md):
+
+- **`sandbox: true` (the isolated worker pool, unchanged from every earlier
+  release):** a function or any attached middleware occupies one shared
+  worker slot for its whole chain. Workers are shared by all `sandbox: true`
+  routes in that snapshot; there is no per-route fairness or reserved
+  capacity. Awaiting guest timers still occupies the slot. A fresh guest and
+  module initialization are part of each call. See "Enforced limits and
+  defaults" below for the numbers (2 workers, 5 s deadline, 32 MiB heap).
+- **`sandbox` false/absent (the trusted default):** the call runs in-process,
+  on the same event loop as everything else the server does — ordinary Node
+  concurrency, not a fixed worker-slot ceiling. There is no separate pool to
+  exhaust and no per-invocation heap/module reset: it is bounded by the same
+  `--max-in-flight` HTTP admission cap (default 64) that bounds every other
+  request, not by a `workers` count. A trusted call's declared `timeoutMs`
+  races the call's own promise rather than forcibly terminating a worker
+  thread — see "Trusted-path deadlines" below for what that does and does not
+  protect against.
+
+  This was architectural reasoning, not a measurement, until the run below:
+  see "Measured: sandboxed vs trusted dispatch" for the actual comparison.
 
 Node's main event loop remains a shared bottleneck for HTTP parsing, logging and
-native responses. Sandboxing contains application code authority and bounds
-individual execution; it does not make all host resources immune to exhaustion.
+native responses. The sandbox contains a `sandbox: true` route's application
+code authority and bounds its individual execution; the trusted default does
+not attempt to, by design. Neither mode makes all host resources immune to
+exhaustion.
+
+### Trusted-path deadlines
+
+A sandboxed worker's deadline is enforced by an interrupt handler the WASM
+engine checks between guest operations, backed by an independent outer
+termination that kills the worker thread if the guest never yields — the
+worker (and its slot) can be forcibly reclaimed even from a stuck call. A
+trusted, in-process call has no such mechanism available: `timeoutMs` starts
+a race between the call's promise and a timer, so a call that never resolves
+(an unresolved promise, an awaited operation that never completes) is
+answered with a 504 on schedule, but a call that blocks the event loop
+*synchronously* (an infinite `while` loop, a huge synchronous computation)
+is not preempted — it keeps running, delays that timer's own firing, and
+holds up every other request on the same process until it returns control to
+the event loop or the process is restarted. This is a real, documented
+difference from the sandboxed path's guarantee, not an oversight: Node has no
+supported way to interrupt another turn of the same thread's event loop from
+inside it. A route whose trusted code cannot be trusted to yield promptly is
+exactly the kind of route `sandbox: true` exists for.
 
 ## Enforced limits and defaults
 
@@ -39,15 +79,17 @@ individual execution; it does not make all host resources immune to exhaustion.
 | Requests per socket | 1,000 | Connection recycling; not a requests-per-second limit |
 | Header / request receipt / keep-alive timeouts | 10 s / 15 s / 5 s | These are not an overall end-to-end response deadline |
 | Request body | 1 MiB default | Buffered; route maxBytes can tighten to 0–1 MiB |
-| Sandbox concurrency | 2 workers, no queue | Shared per snapshot; full pool returns 503 |
-| Execution deadline | 5 s default | Entire middleware + handler invocation; timeout returns 504 |
-| Guest heap / stack | 32 MiB / 512 KiB | Fresh per invocation; not a bound on total process RSS |
-| Outer worker old-generation V8 budget | 128 MiB | Separate from WASM/host/native allocations |
-| Function response | 1 MiB default, 16 KiB / 256 header pairs | Buffered text/JSON; YAML headers also bounded |
-| Middleware | 16 entries per route | One shared slot/deadline, not 16 independent workers |
-| Function sources | 128 modules, 1 MiB/module, 4 MiB total | Project snapshot, including middleware dependencies |
-| Worker startup | 5 s deadline | Failure rejects activation; no untrusted host fallback |
-| Worker replacement | Up to 3 exits/minute per slot trigger replacement | Further churn leaves the slot unavailable until reload/restart |
+| Sandbox concurrency (`sandbox: true` only) | 2 workers, no queue | Shared per `sandbox: true` snapshot; full pool returns 503 |
+| Sandbox execution deadline (`sandbox: true` only) | 5 s default | Entire middleware + handler invocation; forcibly terminates the worker; timeout returns 504 |
+| Trusted concurrency (`sandbox` false/absent, the default) | Ordinary Node concurrency | Bounded by `--max-in-flight` (default 64), not a worker count; no separate pool to exhaust |
+| Trusted execution deadline (`sandbox` false/absent) | 5 s default (same `timeoutMs` knob) | Races the call's promise; cannot preempt synchronous event-loop-blocking code (see "Trusted-path deadlines" above); timeout returns 504 |
+| Guest heap / stack (`sandbox: true` only) | 32 MiB / 512 KiB | Fresh per invocation; not a bound on total process RSS |
+| Outer worker old-generation V8 budget (`sandbox: true` only) | 128 MiB | Separate from WASM/host/native allocations |
+| Function response | 1 MiB default, 16 KiB / 256 header pairs | Buffered text/JSON; YAML headers also bounded; applies to both execution modes |
+| Middleware | 16 entries per route | One shared slot/deadline (`sandbox: true`) or one in-process call (trusted), not 16 independent workers either way |
+| Function sources (`sandbox: true` only) | 128 modules, 1 MiB/module, 4 MiB total | Sandboxed snapshot, including middleware dependencies; a trusted route's own source is hashed for grant pinning but not bundled or budget-limited this way (see docs/FUNCTION-SECURITY.md) |
+| Worker startup (`sandbox: true` only) | 5 s deadline | Failure rejects activation; no untrusted host fallback |
+| Worker replacement (`sandbox: true` only) | Up to 3 exits/minute per slot trigger replacement | Further churn leaves the slot unavailable until reload/restart |
 | Assets | 16 MiB/file, 64 MiB unique contents | Buffered immutable snapshots; 10,000 static entries, depth 20 |
 | Logger buffering | Drop at 1 MiB stdout buffering | Reports logs_dropped when output recovers |
 
@@ -71,8 +113,70 @@ increasing a timeout also increases how long an attacker can occupy capacity.
 The CLI uses defaults. Keep settings identical across replicas unless testing a
 controlled rollout. See [operations](OPERATIONS.md).
 
+## Measured: sandboxed vs trusted dispatch
+
+The claim above — that the trusted path has "no fixed worker-slot ceiling"
+and scales as ordinary Node concurrency instead — was written as
+architectural reasoning when the trusted-by-default execution model shipped
+(docs/SPIKE-DEFAULT-TRUST-MODEL.md), not backed by a benchmark run. This is
+that run: `benchmarks/sandbox-vs-trusted.ts`
+(`npm run benchmark:sandbox-vs-trusted`), same 20 ms handler source on both a
+`sandbox: true` route and a trusted route in the same server, default
+settings (`workers: 2`, `maxInFlightRequests: 64`, `timeoutMs: 5000`), 2,000
+requests per concurrency level after a 20-request warmup, keep-alive
+connections. Raw output:
+[benchmarks/results/2026-09-19-sandbox-vs-trusted.json](../benchmarks/results/2026-09-19-sandbox-vs-trusted.json).
+
+One development machine: Intel Xeon @ 2.10 GHz, 4 vCPUs, 16 GiB RAM, Linux
+x64, Node v22.22.2, 2026-09-19. This is one machine's numbers, not a
+universal claim — re-run on deployment hardware before sizing anything.
+
+| Concurrency | Sandboxed req/s (successful) | Sandboxed shed | Sandboxed p95 | Trusted req/s (successful) | Trusted shed | Trusted p95 |
+|---:|---:|---:|---:|---:|---:|---:|
+| 1 | 39 | 0 / 2000 | 26.9 ms | 47 | 0 / 2000 | 21.5 ms |
+| 2 | 80 | 0 / 2000 | 26.5 ms | 95 | 0 / 2000 | 21.7 ms |
+| 8 | 80 | 1,912 / 2000 | 30.2 ms | 379 | 0 / 2000 | 22.1 ms |
+| 32 | 80 | 1,936 / 2000 | 43.5 ms | 1,465 | 0 / 2000 | 23.5 ms |
+| 128 | 80 | 1,950 / 2000 | 70.0 ms | 2,615 | 521 / 2000 | 80.6 ms |
+
+"Sandboxed req/s" and "shed" are separate columns for a reason: throughput
+computed over successful responses only is flat at ~80 req/s from
+concurrency 2 upward because the 2-worker ceiling admits at most two
+in-flight calls at a time and returns 503 immediately for the rest, exactly
+as "Enforced limits and defaults" describes (no queue). The ceiling is
+visible starting at concurrency 8 in this run (already >95% shed) and only
+gets worse as concurrency rises — 2 concurrent in-flight sandboxed calls is
+the practical limit regardless of how much load is offered.
+
+The trusted path has no such wall: it scales with offered concurrency —
+379 req/s at 8, 1,465 req/s at 32, both with zero shedding — until offered
+concurrency (128) exceeds the `--max-in-flight` admission cap (64), at which
+point it starts shedding too (521/2000, p95 rises to 80.6 ms) but keeps
+substantially higher successful throughput (2,615 req/s) than the sandboxed
+path ever reaches at any concurrency tested. This confirms the architectural
+prediction rather than contradicting it: the trusted path's ceiling is the
+admission cap, not a fixed worker count, and it sits far above the sandboxed
+path's 2-worker ceiling in this run. It is still a real ceiling — raising
+`--max-in-flight` moves it, it does not remove it — and it is shared with
+every other route on the process, per "Native routes and mixed traffic"
+below.
+
+Caveats specific to this run: one handler shape (a 20 ms guest/host timer,
+chosen to make both ceilings visible rather than to represent any particular
+application), one machine, one process with both route types present
+(so CPU contention between them is part of the trusted numbers, not
+excluded), and no TLS, proxy or production logging in the path. Re-run with
+your own handler's actual latency profile before sizing a deployment; see
+"Establish a deployment budget" below.
+
 ## A useful theoretical model
 
+This worker-slot model describes the `sandbox: true` path only. A trusted
+route has no fixed worker count to plug in as W; its ceiling is ordinary Node
+request concurrency bounded by `--max-in-flight`, not this model — see
+"Measured: sandboxed vs trusted dispatch" above for what that ceiling looks
+like in practice.
+
 Let W be worker slots, S the measured mean slot occupancy in seconds (including
 sandbox startup and cleanup effects), and lambda the offered programmable
 requests per second. An idealized worker ceiling is:
@@ -159,6 +263,13 @@ loop even though the HTTP listener is not restarted. Do not equate atomic swap
 with zero latency impact or incremental route updates. Prefer candidate replicas
 and traffic switching for production. `serve` does not watch configuration.
 
+A trusted route's own entry file is re-imported fresh on every reload (see
+[docs/FUNCTION-SECURITY.md](FUNCTION-SECURITY.md)), matching the sandboxed
+pool rebuilding its whole snapshot; a file that entry only imports is not,
+since ordinary Node module resolution — not a per-reload snapshot — governs
+it. Restart the process rather than reload after editing a trusted route's
+dependency, not just its declared `source`.
+
 Before parser-worker limits were introduced, recorded 100k-route startup RSS was about 621 MiB on one development machine,
 above the illustrative 512 MiB container example. Route limits are acceptance
 caps, not a promise that the maximum fits your deployment. See [measurements](PERFORMANCE.md).
@@ -186,20 +297,6 @@ production exercise. The readiness endpoint can stay 200 while all worker slots
 are busy. Use error/latency signals too. No universal safe RPS can be derived
 from the route count or these defaults alone. See [resilience](RESILIENCE.md).
 
-## Optional stored-link capacity
-
-Each SQLite store defaults to two read-only worker connections; writable stores
-add one writer. Independent read/write admission caps default to 32 each across
-their pool. Readers are configurable from 1–8, and caps from 1–32. Operations have
-a 5-second deadline and one-second SQLite lock wait. Public serving has no writer. The
-initial cap is 100,000 stored records across collections; this is separate from
-the YAML route count. No lookup cache is used, so visibility does not depend on
-cache invalidation. Store failures/overload return 503 and failed workers need
-reload/restart; healthy readers can continue while readiness is degraded. Management has a separate listener with 64 connections, 8 KiB
-headers and 16 KiB JSON bodies. Rate limiting remains an ingress responsibility.
-Do not extrapolate in-memory redirect benchmark numbers to database lookups;
-measure disk, writes, contention and restoration on the target host.
-
 Configuration parsing/schema validation now run in a terminated-on-deadline worker;
 route compilation still runs cooperatively on the host (10 seconds, yields every
 64 routes). Source, AST, structured-clone output, compiled routes, assets, module

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/CLOUDFLARE.md

@@ -21,8 +21,7 @@ route pattern and the reason named:
 
 | Handler | Why it is refused |
 | --- | --- |
-| `function`, `middleware` | need worker threads and the QuickJS WASM engine |
-| `link` | needs a durable writable store the platform does not provide here |
+| `function`, `middleware` | need the self-hosted Node lifecycle, and worker threads and the QuickJS WASM engine when a route declares `sandbox: true` |
 | `page`, `static`, `download` | need a platform static-asset binding, not an inline copy |
 | `env`, `secrets` | would have to be baked into the artifact |