@jimhoyd/urlcode 0.3.0

package/docs/BEST-PRACTICES.md

@@ -0,0 +1,267 @@
+# Organization and readability
+
+These are conventions for URLCode applications, not extra schema requirements.
+Choose the smallest structure that makes a route easy to find, understand and
+test. Preserve an existing project's conventions unless there is a clear reason
+to change them. See [file composition](ORGANIZATION.md) for enforced rules and
+[the YAML guide](YAML-GUIDE.md) for supported features.
+
+## Start small, split by responsibility
+
+The default starter's two routes do not need a framework or many abstraction
+layers. A small project can keep all definitions in `urlcode.yaml`:
+
+```text
+my-links/
+  urlcode.yaml
+  functions/
+    welcome.mjs
+  middleware/
+    response-headers.mjs
+  public/
+    guide.txt
+  tests/
+    requests.json
+  README.md
+```
+
+Create only the folders you use. When navigation or ownership becomes difficult,
+group by feature, audience or campaign, rather than creating one YAML file per
+short link. There is no universal file-size threshold; split when a reviewer can
+no longer follow the changes comfortably. Thousands of redirects usually belong
+in a few meaningful collections, not thousands of include entries.
+
+For a growing application, colocating feature-specific code is often clearer:
+
+```text
+my-links/
+  urlcode.yaml
+  features/
+    welcome/
+      routes.yaml
+      welcome.mjs
+      greeting.mjs
+    campaigns/
+      routes.yaml
+  middleware/
+    response-headers.mjs
+  public/
+    guide.txt
+  tests/
+    requests.json
+  README.md
+```
+
+The root remains a short explicit table of contents:
+
+```yaml
+version: "1"
+includes:
+  - features/welcome/routes.yaml
+  - features/campaigns/routes.yaml
+routes: {}
+```
+
+Each included file has its own `version: "1"` and `routes`. Do not add recursive
+includes, glob patterns or inherited defaults. Folder names never change public
+URLs. Keep the two styles available: folders by file type for small apps, or by
+feature when it improves ownership. Neither requires forking the runtime.
+
+## Make a route readable from top to bottom
+
+Use two spaces, no tabs, and one consistent key order. A useful order is:
+`description`, lifecycle (`enabled`/`expires`), `methods`, `parameters`,
+`request`, bindings (`env`/`secrets`), `middleware`, the handler, then `response`.
+This is visual organization, not an execution-order declaration.
+
+Use block style for nested behavior. Short scalar lists such as `[GET, HEAD]`
+and small leaf schemas such as `{type: string}` can stay inline. Omit ordinary
+defaults unless making them explicit clarifies a decision. Quote timestamps and
+numeric-looking header values. Avoid unrelated reformatting when changing a route.
+
+Example `features/welcome/routes.yaml`:
+
+```yaml
+version: "1"
+routes:
+  /welcome/{name}:
+    description: A personalized welcome message with a consistent response header
+    parameters:
+      - name: name
+        in: path
+        required: true
+        schema:
+          type: string
+          minLength: 1
+          maxLength: 80
+    middleware:
+      - source: middleware/response-headers.mjs
+    function:
+      source: features/welcome/welcome.mjs
+      args:
+        name: {from: path, name: name}
+    response:
+      headers:
+        Cache-Control: no-store
+```
+
+Example `features/campaigns/routes.yaml`:
+
+```yaml
+version: "1"
+routes:
+  /guide:
+    # Keep this temporary so a campaign destination can change later.
+    redirect:
+      url: https://example.com/guide
+```
+
+Use comments for the reason behind a choice, migration notes or a business rule.
+Do not narrate obvious syntax or include secrets, private customer details or
+stale deployment instructions. `description` is useful authoring metadata; do
+not invent `owner`, `tags` or other unsupported YAML fields. Record ownership in
+the README or repository tooling instead.
+
+Order routes consistently within each collection, such as alphabetically or by
+business flow. Do not rely on file order for precedence: exact routes win before
+parameter routes, then static mounts. Avoid ambiguous overlaps; see [routing](ROUTING.md).
+
+## Keep handlers short and name their job
+
+Name files for behavior (`welcome.mjs`, `select-destination.mjs`) rather than
+`utils2.mjs` or `handler-final.mjs`. Name exports clearly even when using a default
+export. Use descriptive variables and early returns for error cases. Separate
+business transformations from Request/Response handling when that improves clarity.
+Do not extract a one-line helper merely to create more files.
+
+`features/welcome/welcome.mjs`:
+
+```js
+import {formatGreeting} from './greeting.mjs';
+
+export default function welcome(request, {args}) {
+  return Response.json({message: formatGreeting(args.name)});
+}
+```
+
+`features/welcome/greeting.mjs`:
+
+```js
+export function formatGreeting(name) {
+  return `Hello, ${name}!`;
+}
+```
+
+YAML `source` paths are project-root relative. JavaScript imports are relative to
+the importing module. Explicit `.mjs` filenames make that distinction clear.
+Only relative project JavaScript imports are supported; do not introduce npm,
+Node, remote imports or a transpilation requirement accidentally. There is a
+project-wide module/source budget; excessive fragmentation has a real limit.
+
+Use validated `args` and `inputs` instead of parsing query strings again. Return
+JSON through `Response.json`; escape user data explicitly when producing HTML.
+For dynamic redirects, map a validated enum to known destinations rather than
+accepting any user-controlled URL. Keep modules free of top-level work other than
+simple definitions: initialization runs during validation and fresh invocations.
+
+Prefer pure helpers with explicit inputs and outputs. Module globals are not a
+cache, database, session store or rate limiter: guest state resets per request.
+Review [sandbox constraints](FUNCTION-SECURITY.md) before choosing dependencies.
+
+## Middleware should have one clear responsibility
+
+`middleware/response-headers.mjs`:
+
+```js
+export default async function responseHeaders(request, context, next) {
+  const response = await next();
+  response.headers.set('x-app', 'my-links');
+  return response;
+}
+```
+
+Use middleware for reusable behavior around a handler, not to conceal the entire
+application flow. Prefer YAML headers for fixed route-specific headers; this
+example demonstrates a shared wrapper, but native YAML avoids sandbox overhead
+when no custom code is needed. Keep middleware order explicit in each route.
+
+Always return a Response. Call `await next()` once when continuing, or return
+an early Response when intentionally stopping. Do not launch unawaited work or
+assume background tasks will survive. A body read consumes the request body;
+if downstream code needs parsed data, agree on a documented `context.state` field.
+Use specific field names to avoid collisions among middleware.
+
+Catch only errors you can handle meaningfully. Do not turn every failure into a
+200 response or include secrets in errors. Keep native body/status/header
+preservation rules visible in code review. All middleware share the route's
+bindings and execution budget; splitting modules does not create privilege
+separation. See [middleware semantics](MIDDLEWARE.md).
+
+## Organize tests around observable behavior
+
+Keep runnable HTTP assertions in `tests/requests.json`, currently the single file
+read by the CLI. Group adjacent cases by route: ordinary success, HEAD, boundary
+inputs, invalid input, wrong method and relevant early responses. Add meaningful
+body/header checks instead of relying only on status codes.
+
+For the two-route feature layout above:
+
+```json
+[
+  {"path":"/welcome/Ada","status":200,"expectBody":"{\"message\":\"Hello, Ada!\"}","expectHeaders":{"x-app":"my-links"}},
+  {"path":"/welcome/Ada","method":"HEAD","status":200,"expectBody":"","expectHeaders":{"x-app":"my-links"}},
+  {"path":"/welcome/Ada","method":"POST","status":405,"expectHeaders":{"allow":"GET, HEAD"}},
+  {"path":"/guide","status":302,"expectHeaders":{"location":"https://example.com/guide"}},
+  {"path":"/guide","method":"HEAD","status":302,"expectBody":"","expectHeaders":{"location":"https://example.com/guide"}}
+]
+```
+
+Additional ordinary JavaScript unit tests for pure helpers are your project's
+choice. Unit tests alone do not verify sandbox compatibility: always exercise
+HTTP behavior through URLCode too. Keep large fixture generation explicit and
+deterministic if you add your own tooling; nested test directories and JSON
+fragments are not automatically discovered or merged by URLCode.
+
+Assert observable contracts, not incidental timings or internal variable names.
+Avoid checking generated request IDs, current Date values or performance numbers
+as fixed functional outputs. Test cache/range semantics with controlled assets.
+Update expected route counts deliberately when adding or removing a route.
+
+## Keep configuration, code, assets and operations separate
+
+- Git owns behavior and reviewed code. Keep the runtime as a pinned dependency;
+  upgrading it should not regenerate or overwrite application files.
+- Publish only intentionally public files in `public/`. File filters cannot
+  recognize every secret. A harmless filename is not proof of public content.
+- Put local secrets in ignored `.env.local`; production values come from the
+  operator. Keep operator grants outside the application checkout. Never use
+  YAML anchors, shell expansion or generated credentials for convenience.
+- Deployment limits, TLS, DNS, DDoS filters and worker tuning belong to operations,
+  not invented route fields. Document them separately from portable behavior.
+- Use [stored links](DYNAMIC-LINKS.md) for live short-code records instead of a
+  Git/YAML edit per record. General session/application storage remains future work.
+
+## Refactor without changing the public contract
+
+Move one feature at a time. Update explicit includes and project-root source/asset
+paths, then check relative JavaScript imports. Keep public route paths, methods,
+headers and bodies stable unless the change is intentional. Avoid mixing URL
+renames, dependency upgrades and folder rearrangement in one review.
+
+Run validate, HTTP tests and the expected-count audit before and after moving
+files. Re-review operator grants: code/config changes invalidate the digest even
+when intended behavior is unchanged. A successful dev reload is not a production
+deployment. Record activation/rollback steps in the project README.
+
+## A useful project README
+
+Document how to install the pinned runtime, start locally, run tests/audit, and
+activate a release. Include a small folder map, the owner of each major feature,
+public route behavior and required external binding names (never values). State
+supported Node/runtime versions and link to matching URLCode docs. Explain any
+middleware ordering or surprising defaults that a new maintainer might miss.
+
+For AI-generated changes, require the assistant to follow existing conventions,
+keep diffs focused, add response assertions and report checks actually run. Reject
+invented YAML keys, hidden side effects and unnecessary abstractions. The
+[AI authoring guide](AI-AUTHORING.md) provides a reusable prompt and capability list.

package/docs/CAPACITY.md

@@ -0,0 +1,208 @@
+# Capacity, concurrency and system limits
+
+These are 0.2.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.
+
+## What happens for each request
+
+A single Node process accepts HTTP, parses/validates inputs, matches a compiled
+route and builds the response. Exact routes use a Map lookup (expected O(1)
+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.
+
+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.
+
+## Enforced limits and defaults
+
+| Resource | Current behavior | Scope / configuration |
+|---|---|---|
+| Routes | 100,000 combined | Per project snapshot; schema/loader cap |
+| Parameter routes | 1,000 | Per snapshot; not 1,000 concurrent requests |
+| Included files / YAML size | 256 / 32 MiB per file / 64 MiB aggregate | Parser worker: 256 MiB old heap, 10 s deadline, two concurrent loads per isolate |
+| Route path | 2,048 characters, 32 segments | Configured path; no regex or greedy parameters |
+| Request target / headers | 8,192 characters / 16 KiB headers | Target is checked as a JS string; HTTP header limit is bytes |
+| HTTP connections | 1,024 | Per server; includes keep-alive sockets, not worker slots or users |
+| In-flight application requests | 64 default, no queue; excess gets 503 | From body receipt through response finish/disconnect; health probes exempt |
+| Socket inactivity | 15 s | Destroys inactive sockets, including stalled response writers; not an absolute response deadline |
+| 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 |
+| 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 |
+
+The 1,024-connection cap is not a global memory bound, fairness policy or DDoS
+protection. At the default admission/body limits, accepted uploads can buffer up to
+64 MiB of payload before copies and other allocations. Slow readers can hold
+sockets/response memory until completion/disconnect or the 15-second inactivity
+timeout. A peer that continues making progress can stay connected longer. Use
+proxy admission limits, timeouts and OS/container limits.
+
+The CLI and the embedding JS API accept `--workers`/`workers` (1–32),
+`--function-timeout-ms`/`timeoutMs` (10–60,000), `--max-response-bytes`/`maxBytes`
+(response limit, 1–16 MiB), `--max-body-bytes`/`maxBodyBytes` (request limit, 1–16 MiB),
+`--max-in-flight`/`maxInFlightRequests` (1–1,024; default 64) and
+`--max-in-flight-health`/`maxInFlightHealthRequests` (1–1,024; default 16). Measure the effect with
+[load testing](LOAD-TESTING.md) rather than guessing; `shedResponses` names the
+limit that bound. These are
+operator choices on `startServer`, not supported YAML fields or CLI flags.
+Route body policy still cannot exceed 1 MiB. More workers consume memory and CPU;
+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).
+
+## A useful theoretical model
+
+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:
+
+```text
+worker-limited throughput <= W / S
+mean offered worker load A = lambda * S
+```
+
+This ignores CPU contention, event-loop work, garbage collection, worker failures
+and network overhead. It is an upper bound under simplified assumptions, not a
+recommended arrival rate. With the default W=2:
+
+| Mean slot time S | Idealized ceiling W/S |
+|---|---:|
+| 5 ms | 400 requests/s |
+| 50 ms | 40 requests/s |
+| 500 ms | 4 requests/s |
+| 5 s | 0.4 requests/s (at the timeout boundary; not useful successful capacity) |
+
+No queue means requests are rejected when both slots are occupied, even if the
+average arrival rate is below the ceiling. Under a simplified independent
+Poisson-arrival loss model, Erlang B gives blocking probability:
+
+```text
+B(W,A) = (A^W / W!) / sum(k=0..W, A^k / k!)
+```
+
+For W=2 and S=50 ms, an offered 20 requests/s gives A=1 and B=20%. That is a
+model illustration, not a measured URLCode result. Bursts, correlated traffic and
+CPU-dependent service times can differ substantially. Measure rejection rate as
+well as latency; fast 503 responses must not count as successful throughput.
+An upstream bounded queue may smooth bursts but adds latency and memory; it is
+not included in this runtime. Unbounded queues just move the failure.
+
+Little's law, L=lambda*R, describes average in-flight work for a stable system
+using admitted/completed throughput and mean residence time. It does not turn
+1,024 sockets into 1,024 execution slots or predict tail latency. CPU and bandwidth
+put separate ceilings on throughput. For CPU-bound work, adding workers beyond
+available cores cannot produce linear scaling. Bandwidth must also carry asset
+bytes, response headers, TLS and protocol overhead.
+
+## Native routes and mixed traffic
+
+For native-only traffic, the Node event loop, network, buffers and logging dominate;
+the W/S sandbox model does not apply. Function saturation does not itself consume
+native route worker slots. However all routes share the server/event loop and
+host resources, so a flood can still degrade ordinary redirects and health checks.
+A single expensive function can starve other functions. For stronger isolation,
+use separate processes/containers and proxy routing; there is no per-route pool
+configuration in YAML today.
+
+Horizontal replicas can add capacity if balanced well and supplied identical
+runtime/application revisions and bindings. Scaling is not perfectly linear,
+and capacity falls during failures/rollouts. Rate limits must account for all
+replicas. In-memory counters in middleware reset per request and cannot implement
+a shared rate limiter or durable application state.
+
+Optional [policies](POLICIES.md) keep their state per runtime instance, and
+their memory bounds are per instance too: the `throttle` counter table is one
+LRU table per runtime capped by the largest declared `maxKeys` (default
+100,000 keys), and the `cache` policy's origin cache is bounded by its
+`maxEntries` and `maxBytes` per route and by 64 MiB of bodies across the
+whole runtime; the `compression` policy holds up to 64 MiB of precompressed
+asset variants per runtime, the same figure as the asset snapshot itself, so
+a fully policied instance can hold three such budgets. Neither is shared between replicas or
+serverless instances, so a client budget across N replicas is up to N times
+the declared quota and a cached response is computed once per replica. Both
+tables are dropped on a snapshot reload. Sharing state across instances is a
+[plugin](PLUGINS.md) concern.
+
+## Memory, startup and reload
+
+A practical memory budget includes the Node baseline, parsed YAML/compiled route
+objects, asset snapshots, source copies in workers, WASM heaps, active request
+and response buffers, sockets, logs and transient garbage collection allocations.
+These are not all covered by worker heap limits. Production needs measured peak
+RSS with an OS/container ceiling, plus headroom.
+
+Reload constructs a complete new snapshot while the old one serves/drains. Old
+and new assets and worker pools can overlap; repeated reloads with in-flight calls
+can retain multiple generations. Host route compilation and snapshot transfer can delay the shared event
+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.
+
+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).
+That short benchmark uses 5,000 measured requests and does not exercise all routes
+in the larger datasets; client/server share a process, logs are off, and no TLS
+or production proxy is involved. No NGINX performance ratio has been measured.
+
+## Establish a deployment budget
+
+1. Pin runtime, app, dependency locks and image; record CPU, RAM, Node, proxy/TLS
+   settings, workers, timeouts and logging. Select representative input/body sizes.
+2. Measure native redirects, parameter hits/misses, functions, middleware and
+   assets separately, then use the expected mixed workload and hot-route skew.
+3. Use a separate load generator for deployment tests. Increase offered rate and
+   concurrency gradually; record successful throughput, all status counts,
+   p50/p95/p99, CPU, peak RSS, sockets, restarts and network bytes.
+4. Include bursts, slow clients, saturation, invalid inputs and one failed replica.
+   Sustain tests long enough to observe memory/GC behavior and stable plateaus.
+5. Choose admission limits below the measured failure knee with explicit spare
+   capacity for a replica loss. Verify the service recovers after load stops.
+6. Record the accepted load, error and latency budgets and repeat after changes.
+
+The built-in local benchmark is a quick correctness-aware signal, not the above
+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
+snapshots and overlapping runtimes all consume memory. Worker V8 limits do not cap
+external buffers or aggregate process RSS. Enforce container/process limits and
+operator-controlled activation; see [review scope](SANDBOX-REVIEW.md).

package/docs/CLOUDFLARE.md

@@ -0,0 +1,110 @@
+# Deploying to Cloudflare Workers
+
+Cloudflare Workers is not a Node host. There is no `worker_threads`, no
+filesystem, and code generation at runtime is forbidden. So this target does not
+adapt the runtime the way [Vercel](VERCEL.md) and [AWS](AWS.md) do — it
+**compiles the project ahead of time** and ships a Worker that reads the result.
+
+```sh
+urlcode build --target cloudflare --project . --out dist
+npx wrangler deploy
+```
+
+A working project is in [`examples/cloudflare/`](../examples/cloudflare/).
+
+## Declarative routes only
+
+This target serves **redirects** and **declared responses** (`respond:`), with
+path, query and header parameters, defaults, validation, response headers,
+`enabled` and `expires`. Everything else is refused **at build time**, with the
+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 |
+| `page`, `static`, `download` | need a platform static-asset binding, not an inline copy |
+| `env`, `secrets` | would have to be baked into the artifact |
+
+Generated [site conventions](SITE.md) follow the same table: `robots`,
+`sitemap` and `securityTxt` are `respond` routes and compile into the artifact
+(pass `--origin` to `build` for the absolute URLs they contain); `favicon` and
+`llms` are `page` routes and are refused.
+
+A build artifact is a file that gets copied, cached and committed by mistake, so
+it never carries a secret. That is why `env` and `secrets` are refused even when
+the value is a literal in the YAML.
+
+Refusing at build time rather than at runtime is the point: a project that
+cannot be served fails `urlcode build`, so it never reaches a deployment.
+
+## What the build emits
+
+`--out` receives three generated files. None of them are edited by hand, and
+`dist/` belongs in `.gitignore`:
+
+- `artifact.js` — the compiled routes. **This is an internal build output, not a
+  published contract.** Its `format` may change in any release, and the runtime
+  refuses a format it does not recognise rather than guessing. Always rebuild
+  with the same version of URLCode that the Worker imports.
+- `validators.js` — the parameter schemas, precompiled by Ajv into standalone ES
+  modules. The platform forbids runtime code generation, so a validator cannot
+  be compiled on the Worker; it has to be compiled by the build.
+- `index.js` — the Worker entry, which is three lines over
+  `createFetchHandler` from `@jimhoyd/urlcode/cloudflare`. That import resolves to the
+  package's built `dist/cloudflare.js` (and its declarations, for a TypeScript
+  Worker); the artifact never depends on the TypeScript sources or on type
+  stripping.
+
+Ajv's standalone output hardcodes a CommonJS `require` for its runtime helpers
+even in ESM mode, which an ES module cannot evaluate. The build inlines each
+helper from the installed Ajv — the real function, not a copy that could drift —
+and fails if it meets a `require` it does not recognise, rather than emitting a
+Worker that cannot start.
+
+`wrangler.toml` needs no `nodejs_compat` flag. The runtime and the generated
+validators use Web standards only.
+
+## Portability, and where it stops
+
+The Worker shares its route matching, request policy and response policy with
+the self-hosted server: `src/match.ts`, `src/http-policy.ts` and
+`src/http-response.ts` are the same modules, with no Node imports. Two checks
+keep it that way: an ESLint rule forbids `node:` imports in the modules that
+ship to the Worker, and `scripts/check.ts` (part of `npm run verify`) walks the
+import closure of `src/cloudflare.ts` and fails on any `node:` specifier that
+is not an `import type`. `test/cloudflare.test.ts` builds a project, runs the same project on the
+self-hosted server, and asserts both return the same status, body and headers
+(everything but the per-request identifier) — including the example in this
+repository, replayed through the compiled Worker.
+
+[Policies](POLICIES.md) follow the same rule: `agents` and `security` are
+compiled into the artifact with project list files embedded as entries,
+`compression` is delegated to the edge, and `throttle` and `cache` are refused
+at build time with the route named. The artifact also carries the project-level
+`security` policy, so the Worker's own 404 and thrown-error responses get the
+same security headers the self-hosted server gives them.
+
+Two differences are real and deliberate:
+
+- **Duplicate request headers.** The platform joins repeated headers into one
+  value before the Worker runs, so per-header counts do not exist. The
+  self-hosted server rejects a duplicated scalar header parameter with 400. Here
+  that check cannot fire: the parameter sees the joined value (`a, b`) and is
+  validated against its schema like any other. A constrained schema still
+  rejects it; an unconstrained `type: string` accepts it where the self-hosted
+  server would not. Constrain header parameters you care about. The duplicate
+  `Content-Type` check on a declared request body is unavailable for the same
+  reason; a joined value fails the media-type check instead.
+- **The request target.** The self-hosted server inspects the request line
+  verbatim. The Worker only ever sees a parsed `Request`, so the target is
+  reconstructed from `URL`, and a malformed target the self-hosted server would
+  refuse may have been normalised or rejected by the platform before this code
+  runs. Path traversal, control characters, over-long targets and ambiguous `%`
+  sequences that do survive are still refused by the shared `parseTarget`.
+
+**This has never been deployed to Cloudflare.** Everything above is verified
+against the runtime's own test suite and a local build, not against the
+platform. A first real deployment is the next thing that would change that, and
+until it happens, treat compatibility with a specific `compatibility_date` and
+with Wrangler's bundler as unproven.