@jimhoyd/urlcode 0.4.2 → 0.4.6

package/docs/ASSETS.md

@@ -1,107 +0,0 @@
-# Pages, static files and downloads
-
-Native file handlers are implemented in 0.1.0-alpha.3. They work in the local
-Node runtime and self-hosted process/container. Provider adapters remain planned.
-They do not run user functions or expose filesystem APIs to guest code, trusted
-or sandboxed.
-
-```yaml
-version: "1"
-routes:
-  /about:
-    page:
-      file: public/about.html
-  /assets/*:
-    static:
-      directory: public/assets
-      index: index.html
-      cacheControl: public, max-age=3600
-  /guide:
-    download:
-      file: public/guide.pdf
-      filename: getting-started.pdf
-      contentType: application/pdf
-```
-
-Create all files/directories before validation or startup. Paths are relative to
-the project root. `page` sends one file inline; `download` sends one file as an
-attachment; `static` publishes a dedicated directory tree. There is no remote
-fetch/proxy, directory listing, automatic trailing-slash redirect, framework
-server, SPA fallback or runtime template evaluation. Use prebuilt assets;
-[prerendering](PRERENDER.md) is the tested recipe for building them from
-function and middleware routes.
-
-## Complete handler options
-
-| Handler | Required | Optional |
-|---|---|---|
-| `page` | `file` | `contentType`, `cacheControl` |
-| `download` | `file` | `filename`, `contentType`, `cacheControl` |
-| `static` | `directory` | `index`, `contentType`, `cacheControl` |
-
-`index` is opt-in, a plain `.html` basename such as `index.html`, served only
-when the requested path ends in `/`. A mount `/assets/*` matches `/assets/` and
-its descendants, not `/assets`. Missing files return 404. Exact routes precede
-parameterized routes; mounts follow, longest prefix first. No fallback between
-mounts. Asset routes accept only GET/HEAD (both default); normal enabled/expiry
-and declared input validation still apply. Choose exactly one handler per route.
-
-MIME detection uses the filename extension through `mime-types`; it does not
-sniff file bytes. Unknown extensions use `application/octet-stream`. An explicit
-`contentType` is a MIME essence such as `text/plain` (no parameters). Known text
-charsets are added automatically. On a static mount an override applies to all
-its files; normally leave it unset for mixed assets. Responses use `nosniff`.
-Download names default to the source basename. Unicode names use a standards-based
-Content-Disposition attachment header with UTF-8 encoding and fallback filename.
-Path separators and control characters in names are rejected.
-
-Allowed `cacheControl` values in this release:
-
-- `no-cache` (default): clients may store but must revalidate.
-- `no-store`: clients should not store the response.
-- `public, max-age=3600`: one-hour public caching.
-- `public, max-age=31536000, immutable`: only for content-versioned URLs you never overwrite.
-
-Strong content/representation ETags and Last-Modified are emitted. If-Match and
-If-Unmodified-Since enforce preconditions (412); If-None-Match and
-If-Modified-Since permit 304. ETag conditions take precedence over date conditions.
-HEAD returns metadata and the full Content-Length with no body. GET supports a
-single byte range, including suffix/open-ended ranges (206); unsatisfiable ranges
-return 416 with `Content-Range: bytes */size`. Multiple, malformed or unsupported
-ranges are ignored and return the full 200 response. If-Range works with an exact
-strong ETag; dates and mismatches return the full representation. Range is ignored
-for HEAD and evaluated after preconditions.
-
-## Publishing boundary and resource limits
-
-Assets are an explicit publication surface. Review the files before running an
-untrusted project; no filename filter can identify every secret. Keep a dedicated
-public directory. Asset declarations reject absolute paths, traversal, dot/hidden
-segments, symlinks (including internal ones), hardlinked files and nonregular
-files. Static trees skip hidden entries, `node_modules`, `urlcode.yaml/yml`,
-`package.json`, `package-lock.json` and `.pem/.key/.p12/.pfx/.env` files. Explicit
-references to those names fail. Do not put credentials or private data under
-innocent filenames in a public directory. HTML/JavaScript assets are active browser
-content; only publish reviewed content on an origin that you control.
-
-Startup validates and snapshots bytes in memory: **16 MiB per file, 64 MiB total
-unique file contents, 10,000 traversed static entries and 20 directory levels**.
-These are implementation resource budgets. This is
-bounded buffered serving, not arbitrary-size streaming. For larger collections
-use an external asset service and redirect, pending provider asset adapters.
-Reload can temporarily hold both old and new snapshots; allow memory headroom.
-
-Requests never open asset paths. Files changed after activation stay unchanged
-until a valid reload/restart, preventing request-time path substitution. Keep the
-deployment tree operator-owned and stable during compilation; protection against
-another host process racing directory changes is not a filesystem sandbox.
-`dev` watches declared asset metadata and applies additions, edits and deletions
-through validated reloads. A missing required file or invalid tree keeps the last
-good snapshot. `serve` is fixed until restart. Function grants remain pinned to
-configuration/source, not asset bytes; an asset-only edit does not authorize new
-code or new bindings. Asset changes do update the health version and ETags.
-
-The runnable [asset example](../examples/assets/urlcode.yaml) includes page,
-static and download routes with local HTTP assertions. HTTP semantics follow
-[RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html); MIME mappings use
-[mime-types](https://github.com/jshttp/mime-types).

package/docs/AUTH-BACKUP.md

@@ -1,32 +0,0 @@
-# Auth backup and restore platform guarantees
-
-`createBackup({database,destination,projectRoot})` and
-`restoreBackup({backup,destination,projectRoot})` use SQLite's online backup API
-in a bounded worker. They include committed WAL pages, validate integrity and
-foreign keys, and publish to a new path without overwriting an existing file.
-Both source and destination must remain outside the served project. See the
-[auth operator commands](../packages/auth/README.md#operations-and-recovery).
-
-The completed snapshot is flushed through a writable file handle before it is
-linked into its destination. Windows requires write access for this flush;
-opening the snapshot read-only fails with `EPERM`. File flush errors fail the
-operation rather than being ignored.
-
-On POSIX systems the containing directory is also flushed after publication.
-Node's filesystem API does not provide the equivalent directory-handle flush
-used here on Windows, so Windows does not receive that extra directory-entry
-crash-durability guarantee. A successful Windows backup verifies and flushes
-file contents; it is not proof that the new filename survives abrupt power
-loss. Verify the backup exists and perform an isolated restore rehearsal before
-depending on it. CI does not simulate power loss.
-
-POSIX directory/file modes are checked where supported. Windows operators must
-restrict the operator data and backup directories with filesystem ACLs; POSIX
-mode bits cannot establish Windows privacy. Keep encryption and CSRF keys and
-reviewed configuration separately backed up. Restore to an isolated new path,
-and review restored sessions and revocation state before reopening traffic.
-
-A failed auth service initialization waits for its SQLite worker to terminate
-before rejecting. After a configuration rejection, callers can retry or clean up
-the database without racing that failed opener's file handle. Configuration
-identity checks and their error codes are unchanged.

package/docs/AWS.md

@@ -1,86 +0,0 @@
-# Deploying to AWS Lambda
-
-The AWS adapter runs a URLCode project as a Lambda function behind a **Function
-URL** or an **API Gateway HTTP API**. The same `urlcode.yaml` that runs locally
-or in a container serves the deployment.
-
-**This adapter serves native handlers only** — redirects, validated responses,
-pages, static assets and downloads — for the same reasons as
-[the Vercel adapter](VERCEL.md): `function` and `middleware` routes need the
-self-hosted Node lifecycle, and a `sandbox: true` route would pay worker and
-WASM startup on every cold start. Both are refused at activation with the route
-named, never per request, trusted or sandboxed alike.
-
-That refusal is a settled position, not a gap awaiting an adapter: per-route
-Lambda compilation was considered and declined
-([the decision](OPEN-DECISIONS.md#accepted-one-node-deployment-per-project),
-[the analysis behind it](archive/2026-09-19/SPIKE-LAMBDA-COMPILE.md)). A project that uses
-`function` or `middleware` deploys instead as one trusted Node process — a
-container or a VM running the project as it runs locally — which supports every
-route type today. That process can run on AWS: ECS, EC2 and App Runner all
-serve it. The decision is about the execution model, not about avoiding AWS.
-
-A working project is in [`examples/aws/`](../examples/aws/).
-
-## Set it up
-
-```js
-// handler.mjs
-import { createLambdaHandler } from '@jimhoyd/urlcode/aws';
-
-export const handler = createLambdaHandler({ project: process.env.LAMBDA_TASK_ROOT });
-```
-
-The deployment package must contain every file the project reads: the entry
-YAML, any `includes`, and every page, download and static directory. They are
-read at activation, so a missing one fails the deployment rather than one route.
-Node 22.13 or newer.
-
-## Payload format 2.0 only
-
-Function URLs and API Gateway **HTTP APIs** send payload format 2.0, which
-carries `rawPath` and `rawQueryString` — the request as it arrived.
-
-A **REST API** sends format 1.0, which supplies the path and query already
-decoded. The original bytes cannot be recovered from them, and this runtime
-rejects ambiguous encoding deliberately: rebuilding a target from decoded parts
-would either re-encode differently than the client sent or quietly accept what
-the runtime refuses. Rather than guess, the adapter refuses a 1.0 event and says
-why. Front the function with an HTTP API, or run the container image with
-`urlcode serve`.
-
-## Bindings and origin
-
-`URLCODE_POLICY` carries the same grant document the operator policy file holds,
-validated identically including the `projectSha256` pin — see
-[the Vercel guide](VERCEL.md#bindings), which describes the same mechanism.
-Store it in the function's environment, or fetch it from Secrets Manager and set
-it before the handler is created.
-
-`URLCODE_PUBLIC_HOST` sets the public hostname for generated URLs. Lambda has no
-platform variable naming your domain, so unlike Vercel there is nothing to infer
-from: set it when a custom domain or an API Gateway stage prefix is in play.
-Forwarded headers stay untrusted.
-
-## Limits worth knowing before you deploy
-
-| Limit | Consequence |
-|---|---|
-| Lambda response payload is 6 MB | A larger asset cannot be returned. The runtime allows 16 MB per asset, so a project valid self-hosted can exceed what Lambda can send. Keep large files in object storage and redirect to them. |
-| Response bodies are base64-encoded | Guessing whether a body is text is how binary assets get corrupted, so every response is encoded. Base64 inflates by about a third, against that 6 MB ceiling. |
-| Each execution environment activates independently | Parsing, asset snapshotting and route compilation happen per cold start, and the [capacity limits](CAPACITY.md) apply per instance: a 64 MiB snapshot is 64 MiB in every concurrent one. |
-| No reload | A deployment serves the revision it was packaged from. Ship a change by deploying. |
-| No `/_urlcode/health` or `/_urlcode/ready` | Those describe a long-lived process. Use Lambda's own metrics; the [monitoring recipes](MONITORING.md) that parse stdout records need adapting for CloudWatch, though the record fields are the same. |
-
-## Verification status
-
-The adapter is tested against the self-hosted runtime for identical status, body
-and headers across redirects, parameters, responses, pages, static files and
-misses; for format 1.0 and malformed events being refused; for base64 request
-bodies and route body policy; for cookies arriving and leaving through the
-format 2.0 array; and for the policy pin.
-
-**It has not been deployed to AWS.** The tests drive the real handler with real
-payload format 2.0 events, but no invocation on Lambda has happened. Treat
-package contents, cold-start latency, API Gateway's own header handling and the
-6 MB ceiling as unverified until you deploy the example and see it work.

package/docs/BEST-PRACTICES.md

@@ -1,276 +0,0 @@
-# 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
-regardless of trust mode. If a route declares `sandbox: true`, review
-[sandbox constraints](FUNCTION-SECURITY.md) before choosing dependencies —
-trusted (default) routes have ordinary Node module access instead.
-
-## 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 any
-function/middleware invocation overhead when no custom code is needed —
-including the extra cost of `sandbox: true` where that is declared. 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 runtime compatibility — including the
-guest API restrictions of a route declaring `sandbox: true` — or HTTP framing:
-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.
-- Live short-code records need durable storage core does not have. The
-  `urlcode-dynamic-link` extension provided it and has been retired; its
-  published `0.1.0-alpha.1` pins core `0.4.0-alpha.1` exactly and so cannot be
-  installed beside `0.4.0-alpha.2`. Treat stored short links as unsupported
-  until that work lands somewhere else. 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/BULK.md

@@ -1,79 +0,0 @@
-# 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.