@jimhoyd/urlcode 0.3.0

package/docs/OPERATIONS.md

@@ -0,0 +1,207 @@
+# Running URLCode yourself
+
+This is the stable 0.1 self-hosted runtime. Its deliberately bounded feature set
+is not a claim of suitability for every production workload. Deploy only workloads
+whose requirements fit the [implemented contract](SPECIFICATION.md).
+Provider adapters, automatic TLS/DNS management, distributed rate limits,
+metrics exporters and durable event delivery are not included.
+
+## Process deployment
+
+Install a reviewed URLCode commit with Node 22.13+ and `npm ci --omit=dev`.
+Keep the runtime separate from an application checkout pinned to its own commit.
+Functions support only relative project JavaScript modules; do not install or
+execute an untrusted application’s package scripts as part of serving it. Validate using
+the same injected environment as the serving process:
+
+```sh
+node /opt/urlcode/dist/cli.js validate --project /srv/my-links
+node /opt/urlcode/dist/cli.js serve --project /srv/my-links \
+  --host 127.0.0.1 --port 3000 --origin https://links.example.com
+```
+
+`--origin` defines the public URL seen by functions; proxy Host/X-Forwarded-*
+headers are intentionally not trusted. Use a process supervisor that restarts on
+failure and sends SIGTERM for shutdown. Shutdown stops accepting requests, gives
+HTTP connections up to 10 seconds, and drains bounded in-flight functions.
+
+Serve a read-only application tree where practical. The operator-owned runtime
+account must be able to read application files/dependencies. Authoring happens
+in development/CI, not by modifying a running replica's filesystem.
+
+## Container deployment
+
+The supplied image packages the runtime; it does not copy your application or
+local secret files. Build from the reviewed runtime checkout:
+
+```sh
+docker build -t urlcode:0.2.0 .
+docker run --rm --name my-links \
+  --read-only --cap-drop ALL --security-opt no-new-privileges \
+  --memory 512m --cpus 1 --pids-limit 128 \
+  -p 127.0.0.1:3000:3000 \
+  -v "$PWD/starters/default:/project:ro" \
+  urlcode:0.2.0
+```
+
+Replace the example mount with your app. The image uses the unprivileged `node`
+user; ensure mounted config/functions are readable by it. Only operator-owned components such as the optional link store can use writable
+mounts. Sandboxed application functions cannot access mounted files or installed
+Node packages. The resource values above illustrate
+container limits, not a sizing recommendation; large configuration compilation
+can need more memory. Measure your workload. Tag/redeploy immutable image digests
+in real operation rather than treating a mutable tag as a rollback identity.
+
+## Domains, HTTPS and exposure
+
+Point your domain's DNS at the reverse proxy/load balancer you operate, terminate
+HTTPS there, and forward to the loopback/private URLCode port. Use a tested proxy
+such as your existing Caddy/nginx/load-balancer setup for certificates, connection
+limits and rate limiting. No certificate automation is supplied by URLCode yet.
+Keep direct backend access private. Restrict `/_urlcode/*` endpoints to operators
+at the proxy; they are unauthenticated and reveal route count/config digest.
+
+If functions perform sensitive actions, implement authentication and authorization
+in the application. A short URL is not automatically an access-control mechanism.
+Functions are untrusted and isolated in WASM by default. Keep separate deployment
+processes/containers and narrowly scoped credentials as additional boundaries.
+Do not expose a public code-upload/multi-tenant service on the basis of the self-hosted release alone
+without separate security review and stronger service-level containment.
+
+## Secrets and rotation
+
+`dev`, `test`, `routes`, `audit`, `benchmark` and `validate --local` read
+`.env.local`. Authoring and
+permissions inspection do not read credentials or execute functions. `serve` and
+ordinary `validate` use process environment only. Resolve logical names from
+your own secret store/supervisor and inject them at startup; direct provider
+secret-store integrations remain future work. Bindings also require an external,
+revision-pinned operator policy; see [setup](FUNCTION-SECURITY.md). Do not place secret values in
+command-line arguments, route YAML, image layers or Git.
+
+Check tracked files as well as ignore rules. Docker builds use an explicit
+allowlist; npm artifacts include runtime/schema/starter/docs files only. Do not
+build an application image by blindly copying its entire development directory.
+Rotate a credential by replacing its injected value and restarting/redeploying;
+production does not watch or refresh secret values automatically.
+
+## Health, logs and limits
+
+- `GET /_urlcode/health`: process liveness.
+- `GET /_urlcode/ready`: 200 when the active snapshot and all function workers
+  are available and configured link-store readers are healthy; 503 while a worker/store
+  is unavailable. Busy workers alone do not
+  mark readiness down. A failed worker or store connection is replaced with
+  exponential backoff (250 ms doubling to a 30-second ceiling) and readiness
+  reports 503 until every slot is serving again. Replacement does not stop, so a
+  request-triggered deadline cannot disable functions until an operator restarts;
+  a cause that keeps recurring keeps the instance shedding load and needs an
+  operator. Alert on sustained `function_worker`/`link_store_worker` restart events.
+- Probes are answered from their own admission budget (16 by default,
+  `--max-in-flight-health`), so they stay available while the application is
+  saturated without being an unmetered endpoint. They are unauthenticated and
+  report the configuration digest and route count: keep them on an internal
+  interface or restrict them at the ingress.
+- Request logs: JSON request ID, status and duration. No URLs, query strings,
+  headers, bodies, bindings or user exception text. `--request-log detailed` adds
+  the request method and the matched route pattern (`/u/{id}`, or `null` when
+  nothing matched). Both come from the reviewed configuration, never from
+  request-supplied path, parameter or query text, which is what makes per-route
+  error rates and latency available without logging user data.
+- Request IDs are generated per request and returned in `x-request-id`. An
+  inbound `x-request-id` is ignored unless `--trust-request-id` is set, which is
+  only correct when a trusted proxy sets the header and strips client-supplied
+  copies; untrusted values are still rejected unless they are a single header of
+  at most 128 characters from `[A-Za-z0-9_.:-]`. Forward stdout to your log
+  system and alert on sustained 5xx and latency. The default logger drops records
+  when stdout buffering reaches 1 MiB and reports the dropped count when output
+  recovers; alert on `logs_dropped`. Function console output is
+  suppressed; app-specific diagnostics are not yet a first-class feature.
+  Synchronous and asynchronous sink failures are contained; a failed sink drops
+  subsequent output and needs operator recovery. Collectors own rotation/retention.
+- HTTP: 8,192-character target, 16 KiB headers, 1 MiB buffered body, 15-second request
+  receipt timeout, 10-second header timeout, 5-second keep-alive, 1,000 requests
+  per socket and 1,024 active connections. At most 64 application requests are
+  admitted through response completion; excess requests receive 503. Health probes
+  remain available under admission saturation. A 15-second socket inactivity
+  timeout closes stalled readers/writers. Proxy timeouts/rate limits still matter.
+- Functions: 2 concurrent workers (`--workers`), no queue, 5-second deadline
+  (`--function-timeout-ms`), 1 MiB buffered response (`--max-response-bytes`) and
+  16 KiB response headers. Saturation 503; timeout 504; error 502.
+  QuickJS guests have a 32 MiB heap and 512 KiB stack budget and no network or
+  host capabilities. Outer workers have additional V8 limits. Total process/WASM
+  memory still needs deployment-level limits; do not equate guest budget with RSS.
+
+`urlcode serve`/`dev` and the JavaScript server API both configure workers,
+deadlines and byte limits: `--workers`, `--function-timeout-ms`,
+`--max-response-bytes`, `--max-body-bytes`, `--max-in-flight` and
+`--max-in-flight-health`. Set them on the container command line; these are
+deployment controls, not portable route behavior. Horizontal replicas
+must use identical application/config versions and secret bindings. In-memory
+function state is reset after every invocation, not durable/shared application state.
+General application storage needs a future explicit capability broker; no
+storage/network access is exposed to the guest. The optional native
+[link store](DYNAMIC-LINKS.md) supports live short-link records on one host.
+
+The health version combines route-definition and asset-representation digests;
+it does not identify the complete function/runtime release. Record runtime commit,
+application commit, dependency locks and image digest in your deployment system.
+
+## Optional dynamic-link deployment
+
+Keep SQLite and management tokens outside the application, in a private durable
+local directory. Initialize through `links init/create`, bind public serving with
+`--link-store`, and expose management on a separate private listener. Restrict
+its token to your trusted backend; apply ingress limits and backups. Public
+serving opens read-only pools; management has a separate writer and read pool.
+Budget connections across processes and monitor writer health separately. See
+[dynamic-link operations](DYNAMIC-LINKS.md). Multiple host replicas must not share
+this file over a network filesystem; no distributed adapter is included yet.
+
+## Deployment and rollback procedure
+
+1. Build a candidate from pinned runtime/application revisions and lockfiles.
+2. Validate its config/bindings and run local HTTP tests without external redirects.
+3. Start it on an alternate private port/container. Check readiness and representative
+   redirect/function behavior through the intended proxy configuration.
+4. Switch proxy traffic after checks pass. Drain the previous instance before stopping.
+5. If checks or observed behavior fail, route traffic back to the retained previous
+   instance/image and its compatible secret bindings.
+
+This is an operator procedure, not an implemented deployment control plane.
+Rollback cannot undo a function's external side effects or migrate an app's
+state automatically. Plan those independently. Keep Git definitions backed up;
+back up any app-owned persistent state separately. YAML routes require no database; dynamic link records require separate backups.
+
+## Capacity and incident planning
+
+See [capacity and concurrency](CAPACITY.md) for hard limits, worker occupancy,
+no-queue rejection, memory/reload budgets and theoretical sizing. See
+[DDoS and recovery](RESILIENCE.md) for ingress responsibilities, incident response,
+rollback/restore procedures, recovery objectives and drills.
+
+See the [release-readiness register](RELEASE-READINESS.md) for evidence and open gates.
+
+## Remaining production validation
+
+Before approving a production deployment: run sustained soak/load tests on its
+hardware, obtain independent security review, exercise failure/restart and
+upgrade/rollback, establish a clear support/reporting policy, and add the needed
+operational metrics. Provider adapters remain separate roadmap work. See
+[roadmap](../ROADMAP.md). No claim of high
+availability, zero downtime or provider portability beyond the Node process
+adapter is made by the current release.
+
+## Security review
+
+The [2026-09-16 internal audit](SECURITY-AUDIT.md) records fixes, regression evidence
+and remaining security/operational gates. This is not an independent assessment.
+
+## Management hardening baseline
+
+Management is now restricted to literal loopback addresses. Prefer `--auth-file`
+for individual expiring, revocable credentials with collection/action scopes.
+Every successful built-in store mutation has an atomic, durable SQLite audit row;
+HTTP request logs remain best effort. See [management security](MANAGEMENT-SECURITY.md)
+for policy examples, compatibility, archival and rollback requirements, and
+[operational proof](OPERATIONAL-PROOF.md) for executable recovery drills.

package/docs/ORGANIZATION.md

@@ -0,0 +1,135 @@
+# Organize routes your way
+
+`urlcode.yaml` is the project entry point. The rest of the folder structure is
+yours. Use one file for a few links or split routes by feature, team, campaign,
+customer or another useful grouping. Folder names do not create URL prefixes.
+Explicit file composition is already implemented; no new runtime mode is needed.
+
+## One file
+
+```yaml
+# urlcode.yaml
+version: "1"
+routes:
+  /go:
+    redirect:
+      url: https://example.com
+```
+
+## Multiple files and nested folders
+
+The public [urlcode-template](https://github.com/jimhoyd-com/urlcode-template)
+contains a function route and a redirect, organized like this:
+
+```text
+urlcode.yaml
+routes/
+  functions.yaml
+  marketing/
+    links.yaml
+functions/
+  hello.mjs
+tests/
+  requests.json
+```
+
+Entry point:
+
+```yaml
+# urlcode.yaml
+version: "1"
+includes:
+  - routes/functions.yaml
+  - routes/marketing/links.yaml
+routes: {}
+```
+
+Function route:
+
+```yaml
+# routes/functions.yaml
+version: "1"
+routes:
+  /hello:
+    function:
+      source: functions/hello.mjs
+```
+
+Function source for this short example:
+
+```js
+// functions/hello.mjs
+export default function hello() {
+  return Response.json({ message: "Hello!" });
+}
+```
+
+Redirect route:
+
+```yaml
+# routes/marketing/links.yaml
+version: "1"
+routes:
+  /go:
+    redirect:
+      url: https://example.com
+```
+
+These produce `/hello` and `/go`, not `/routes/hello` or `/marketing/go`. The
+actual template adds a validated `{name}` input to the function example. You can
+also colocate code with a feature, for example `features/support/routes.yaml`
+and `features/support/hello.mjs`; use `source: features/support/hello.mjs`.
+
+## Mix inline and included routes
+
+Keep a few common routes in the entry point while splitting larger groups:
+
+```yaml
+version: "1"
+includes:
+  - routes/functions.yaml
+  - routes/marketing/links.yaml
+routes:
+  /status:
+    respond:
+      json: {ok: true}
+```
+
+With the example files above, the combined project has three routes. Update your
+reviewed `--expect-routes` count when adding/removing a route. Simply moving a
+route between files does not change the count or its URL.
+
+## Composition rules
+
+- All file references are relative to the project root containing `urlcode.yaml`,
+  including `includes`, function `source`, and asset `file`/`directory` references.
+  They are never relative to the included YAML file.
+- Each file declares `version: "1"` and `routes`. The entry point uses `routes: {}`
+  when all routes live in includes. `.yaml` and `.yml` work.
+- Includes list explicit files, including paths through nested folders. There is
+  no directory auto-discovery, glob expansion or remote configuration download.
+- Put all includes in `urlcode.yaml`; included files cannot include other files.
+- Duplicate files or route paths fail validation. Include order does not provide
+  overrides or change route-matching precedence.
+- References must stay inside the project. Missing files and escaping symlinks
+  fail validation. Do not use secret files as configuration.
+- Current limits: 256 included files, 32 MiB per YAML file, 64 MiB aggregate YAML and 100,000 total routes. Parser-worker and compilation limits also apply; see [capacity](CAPACITY.md).
+  These limits apply to the combined project, not separately per folder.
+
+`dev` reloads changes to ordinary project YAML files and keeps the last valid
+snapshot if a change is invalid. Configuration in hidden/build/dependency
+folders or behind symlink targets is outside the normal watcher: use ordinary
+source folders or restart after such changes. File grouping does not weaken
+function isolation or operator binding requirements.
+
+`validate`, `routes`, `test`, `audit` and `benchmark` all use the same merged
+project. To move files safely: edit the include list and any changed project-root
+references, validate, then run the audit with the same expected count. Paths
+inside a moved route file need no change when their target files remain in place.
+See the [implemented contract](SPECIFICATION.md) and [readiness guide](READINESS.md).
+
+See [route matching and new links](ROUTING.md) for parameter/wildcard semantics,
+priority rules and activation of newly added definitions.
+
+For layout choices, naming, readable YAML/functions, middleware responsibilities
+and safe refactoring, see [organization and readability practices](BEST-PRACTICES.md).

package/docs/PERFORMANCE.md

@@ -0,0 +1,72 @@
+# Performance checks
+
+Run from the runtime checkout:
+
+```sh
+npm run benchmark -- 1000
+npm run benchmark -- 10000
+npm run benchmark -- 100000
+```
+
+Each invocation generates a temporary literal-redirect collection, measures
+YAML load/compile/server startup, warms up 100 requests, then runs 5,000 real
+loopback HTTP requests with 16 keep-alive connections. It verifies every status
+and destination, never follows redirects, cleans up its process/files and
+prints JSON with hardware/runtime, startup, memory, throughput and latency.
+
+Initial local measurements on 2026-09-16: Apple M4 Pro, 48 GiB RAM, macOS arm64,
+Node 26.8.2. These are short development runs on a shared machine, not an SLA,
+sizing recommendation, soak result or comparison against other products.
+
+| Routes | Startup | RSS after startup | Redirect requests/s | p95 latency |
+|---|---:|---:|---:|---:|
+| 1,000 | 29 ms | 86 MiB | 29,398 | 0.87 ms |
+| 10,000 | 168 ms | 186 MiB | 28,458 | 0.85 ms |
+| 100,000 (after parser fix) | 1,431 ms | 621 MiB | 28,563 | 0.85 ms |
+
+These runs use the improved parser; the original 100,000-route startup took
+42,493 ms. A string-key-only duplicate check reduced that to
+1,431 ms while retaining duplicate rejection tests. Parser transient allocation
+still contributes significantly to RSS; 100k startup exceeds the illustrative
+512 MiB container limit. Do not size from routing data alone.
+
+Before a stable production release, repeat on supported Node 22/24/26 deployment
+hardware, measure long-running memory/reloads and tail latency under sustained
+traffic, include mixed parameter/function workloads and overload/recovery, and
+set regression budgets from repeatable evidence. Worker concurrency and slow
+upstream services need separate tests; literal redirect throughput does not
+predict function throughput. Runtime logs were disabled for these measurements.
+
+The 5,000 measured requests do not exercise every route in the larger datasets.
+Client and server share a process; these runs exclude TLS/proxy overhead and
+production logging. No NGINX comparison has been measured. Use the
+[capacity model](CAPACITY.md) and [recovery drills](RESILIENCE.md) when designing
+a deployment benchmark; do not extrapolate native redirect RPS to middleware.
+
+## TypeScript conversion, 2026-09-17
+
+The runtime source became TypeScript, shipped as `dist/`: Node's own type
+stripping with the specifier extension rewritten, so `dist/x.js` is
+byte-equivalent to `src/x.ts` with the types removed (same lines, same
+columns; no bundling, minification or syntax transform). The published
+package therefore runs the same JavaScript it ran before. Measured on the same
+machine (Intel Xeon 2.80 GHz, 16 GiB, Linux, Node 22.22.2), a plain-JavaScript
+worktree of the pre-conversion commit against `dist/cli.js`, three alternating
+runs each, medians of medians:
+
+| Check | Before (JavaScript source) | After (`dist/`) |
+|---|---:|---:|
+| CLI cold start, `validate --project starters/default` (20 spawns) | 798.6 ms | 797.8 ms |
+| CLI cold start, `routes --project starters/default` | 795.1 ms | 770.9 ms |
+| CLI cold start, `--help` | 331.0 ms | 328.4 ms |
+| `npm run benchmark -- 1000` requests/s (6 runs) | 4,640–4,927 | 4,657–4,914 |
+| `npm run benchmark -- 1000` p95 | 5.77–6.00 ms | 5.65–5.96 ms |
+| `npm run benchmark -- 1000` RSS after startup | 95–100 MiB | 95–100 MiB |
+| `cli benchmark --project starters/default` (function route) | 1,188 req/s, p95 3.50 ms | 1,265 req/s, p95 3.28 ms |
+
+Every difference is inside run-to-run spread; the gates (cold start within 2 %,
+throughput within noise, RSS within 5 MiB) were met. Running the `.ts` source
+directly (`node src/cli.ts`, the developer loop) costs about +190 ms of cold
+start and +35 MiB RSS for the stripping itself; that mode never ships.
+Container time-to-ready was not measured here (no Docker in that environment);
+CI's readiness loop covers it.

package/docs/PLUGINS.md

@@ -0,0 +1,234 @@
+# Host plugins
+
+A plugin is host code an operator passes to the runtime in JavaScript or
+TypeScript. It sees
+every request after the route is matched and before the handler runs, may
+answer it outright, and sees every response before it is written. The
+declarative [policies](POLICIES.md) are implemented on the same hook names,
+so first-party and operator behavior share one code path and one test seam.
+
+Plugins are not part of the project format. Nothing in YAML names a plugin or
+an npm package; the operator application passes them to `startServer`,
+`createRuntime`, `createVercelHandler` or `createLambdaHandler`. A project stays
+portable while an operator can still add a shared-store limiter, a verified-bot
+check or a purge endpoint. Plugins run in the host process with the host's
+privileges: they are the operator's trust boundary, not the project's, and the
+runtime does not sandbox, review or limit what a plugin does with a request.
+Treat a plugin like any other dependency of the operator application.
+
+## Passing plugins
+
+```js
+import { startServer } from '@jimhoyd/urlcode';
+
+await startServer({
+  project: './site',
+  trustedProxies: ['10.0.0.0/8'],
+  plugins: [auditPlugin],
+});
+```
+
+`createRuntime(project, { plugins })` takes the same array for embedding
+without the HTTP server. `createVercelHandler({ plugins })` and
+`createLambdaHandler({ plugins })` pass it through to the adapter's runtime
+with the target set to `vercel` or `aws`. The Cloudflare build takes no
+plugins: the Worker carries only compiled policies. `runtime.plugins` lists
+the activated `{ name, version }` pairs.
+
+## Plugin shape
+
+```js
+const auditPlugin = {
+  name: 'audit',                 // ^[a-z][a-z0-9-]{0,63}$, unique per runtime
+  version: '1.0.0',              // any string up to 64 characters
+  targets: ['node', 'vercel'],   // subset of node, vercel, aws, cloudflare
+  async onActivate(runtime) {},                    // may throw to refuse activation
+  async onRequest(request) {},                     // return a result to short-circuit
+  async onResponse(request, result) { return result; }, // return the result to send
+  onError(request, error) {},                      // observe a thrown error
+  async onClose() {},                              // release resources
+};
+```
+
+The package ships declarations for this contract: `Plugin` and
+`PluginRuntime` (what `onActivate` receives) from `@jimhoyd/urlcode/plugins`, with
+`PolicyRequest`, `HandlerResult`, `HeaderPair`, `TargetName` and `TestPlan`
+re-exported beside them, and `HostPlugin` (the same type) from `urlcode`. The
+same plugin in TypeScript:
+
+```ts
+import type { Plugin, PolicyRequest, HandlerResult } from '@jimhoyd/urlcode/plugins';
+
+const auditPlugin: Plugin = {
+  name: 'audit',
+  version: '1.0.0',
+  targets: ['node', 'vercel'],
+  onRequest(request: PolicyRequest): HandlerResult | undefined {
+    if (request.path === '/deny') return { status: 451, headers: [], body: new Uint8Array(0) };
+    return undefined;
+  },
+  onResponse(request, result) { return { ...result, headers: [...result.headers, ['x-plugin', 'seen']] }; },
+};
+```
+
+Validation happens at activation, before any request: at most 32 plugins,
+each an object with a kebab-case `name` no other plugin uses, a `version`
+string and a `targets` array of known target names; every declared hook must
+be a function and at least one must be present. A plugin whose `targets` does
+not include the runtime's target is refused with
+`Plugin "name" does not support the vercel target`, mirroring how adapters
+refuse routes, so the same operator application fails fast where a plugin's
+assumptions do not hold.
+
+`onActivate(runtime)` receives `{ testPlan(), version, root, target }`.
+`testPlan()` returns the route inventory (`inventory[].policies` names the
+effective policies per route) and `policies`, the per-route policy summaries
+with their `target` value, so a plugin can inspect what it is joining and
+throw to refuse. Hooks may be async; the runtime awaits them.
+
+## The request object
+
+Every request hook receives the same object the policies see, built once per
+request by `policyRequest` in `src/policies.ts`:
+
+| Field | Value |
+|---|---|
+| `method` | Request method, upper case |
+| `target` | Raw request target (path plus query string) as received |
+| `path` | Parsed path |
+| `params` | Route parameter values by name |
+| `query` | Parsed query as `URLSearchParams` |
+| `headers` | Request `Headers` |
+| `headerCounts` | Occurrences per header name, lower case, so a duplicated scalar header can be detected (empty on Cloudflare, where the platform joins repeats) |
+| `client` | Client address as the host resolved it through `--trusted-proxies` or the platform's connection address, or `null` when none could be resolved. Never a raw forwarded header |
+| `origin` | Public origin the runtime was told (`--origin`, `URLCODE_ORIGIN` or the platform's), used for HSTS and absolute URLs |
+| `route` | The matched route's configured pattern, never request text |
+| `secrets` | `true` when the route declares secret bindings |
+
+The object identity is stable for the life of the request, so a plugin may key
+a `WeakMap` on it to carry state from `onRequest` to `onResponse`. Nothing on
+it reaches the guest: there is no sandbox handle, no deadline, no `env` or
+`secrets` values and no binding. A plugin cannot extend or shorten a function's
+deadline, read or write guest state, or obtain a binding the operator policy
+did not grant to the route.
+
+## Results
+
+A result is what the runtime writes:
+
+```js
+{ status: 429, headers: [['content-type', 'text/plain; charset=utf-8'], ['retry-after', '30']], body: Buffer.from('Too many requests\n') }
+```
+
+`headers` is an array of `[name, value]` pairs; `body` is a `Buffer`
+(a `Uint8Array` on Cloudflare). `onRequest` returns such a result to answer the
+request without running the handler, or `undefined` to continue. `onResponse`
+returns the result to send; returning `undefined` keeps the one it was given.
+Replace rather than mutate. Every result still passes through the shared
+response writer on the way out: the status must be an integer from 200 to 599,
+header names and values are validated (an invalid one fails the request as a
+function's would), hop-by-hop headers and `Content-Length` are dropped and
+recomputed, `X-Request-Id` and `X-Content-Type-Options: nosniff` are added, and
+`Cache-Control: no-store` is added when the result carries no `Cache-Control`.
+HEAD and 204/205/304 results are sent without a body.
+
+## Ordering
+
+Plugins wrap everything else. On the request side the first plugin in the
+array runs first, then the second, then the policies (`agents`, `throttle`,
+`cache`), then the route contract and the handler. On the response side the
+policies run, then plugins in reverse: the first plugin sees the request first
+and the response last, the standard onion. A short-circuit from any
+`onRequest` skips the remaining plugins, every policy request hook and the
+handler, and goes straight to the response side; the response hooks of
+policies with a request phase are skipped for it (nothing is cached, no
+rate-limit headers), security headers and compression still apply, and every
+plugin's `onResponse` still runs.
+
+`onError` hooks run in reverse order for an error the runtime throws after
+the request object exists (404 for a disabled route is thrown before it; a
+405 is an ordinary result and reaches `onResponse`). They observe only: a
+throw inside `onError` is swallowed and the outcome stands. A policy's error
+hook may answer with a fallback instead; when one does, plugin `onError`
+hooks do not run and plugin `onResponse` hooks see the fallback (no
+first-party policy returns one today). `onClose` runs in reverse order when
+the runtime closes, after the policies have released their state; a throw
+there is ignored.
+
+On a reload the same plugin objects are activated again: `onActivate` runs
+for the new runtime before `onClose` runs for the retired one, so plugin
+state persists unless `onClose` discards it. An `onActivate` that throws
+rejects the reload and the old runtime keeps serving.
+
+## What a plugin cannot do
+
+- Reach inside the guest, extend a deadline or see bindings: the request
+  object carries none of those, and there is no other handle.
+- Change a project's routes or policies after activation; `onActivate` can
+  refuse, not rewrite.
+- Be selected from YAML. A project cannot require a plugin, and a plugin's
+  presence does not change how the project validates.
+- Change a thrown error's status or body from `onError`.
+- Run on Cloudflare: the Worker carries compiled policies only.
+
+## Sketches
+
+Both examples are sketches, not shipped code: they omit error handling,
+configuration and the store or verifier they depend on.
+
+### Shared-store throttle
+
+The built-in `throttle` keeps counters per instance. Across replicas an
+operator needs a shared store; a plugin keys it on the resolved client and the
+route pattern, both of which the request object already carries.
+
+```js
+// Sketch. `store.increment(key, windowSeconds)` is a fixed-window counter
+// in a shared store and returns the count after increment.
+export function sharedThrottle({ store, quota, window }) {
+  return {
+    name: 'shared-throttle', version: '0.1.0', targets: ['node', 'vercel', 'aws'],
+    async onRequest(req) {
+      const key = `${req.route}|${req.client ?? 'shared'}`;
+      const used = await store.increment(key, window);
+      if (used <= quota) return undefined;
+      return {
+        status: 429,
+        headers: [['content-type', 'text/plain; charset=utf-8'], ['cache-control', 'no-store'], ['retry-after', String(window)]],
+        body: Buffer.from('Too many requests\n'),
+      };
+    },
+  };
+}
+```
+
+Combine it with `policies.throttle: false` on the routes it covers, or keep
+the built-in policy as a per-instance ceiling underneath it.
+
+### Verified-bot allow
+
+The `agents` policy matches strings only. Verifying that a request claiming to
+be a search crawler really comes from one (reverse DNS as the major engines
+document, or an HTTP Message Signature per the web-bot-auth drafts) needs a
+network lookup and a cache, so it is a plugin. The sketch answers 403 to a
+claimed crawler whose address does not verify and lets everything else
+continue to the `agents` policy.
+
+```js
+// Sketch. `verify(address)` resolves the address back to the crawler's
+// documented domains and caches the answer; it is not part of the runtime.
+export function verifiedBots({ verify, claims = /Googlebot|bingbot/i }) {
+  return {
+    name: 'verified-bots', version: '0.1.0', targets: ['node'],
+    async onRequest(req) {
+      const agent = req.headers.get('user-agent') || '';
+      if (!claims.test(agent) || !req.client) return undefined;
+      if (await verify(req.client)) return undefined;
+      return { status: 403, headers: [['content-type', 'text/plain; charset=utf-8'], ['cache-control', 'no-store']], body: Buffer.from('Forbidden\n') };
+    },
+  };
+}
+```
+
+A plugin that logs should follow the policies' rule: record the route pattern
+and the outcome, not the client address or the User-Agent string.