@jimhoyd/urlcode 0.4.0-alpha.2 → 0.4.0-alpha.3

package/docs/archive/2026-09-19/ROADMAP.md

@@ -0,0 +1,386 @@
+# Historical record
+
+Archived 2026-09-19. This records an earlier implementation or proposal, not
+current instructions. See the [current roadmap](../../../ROADMAP.md),
+[current contract](../../SPECIFICATION.md) and [open decisions](../../OPEN-DECISIONS.md).
+Remaining acceptance work is not declared complete by archiving this record.
+
+<!-- trust-model-prose: historical-file -->
+<!-- guidance-claims: ignore-file -->
+
+# Public roadmap
+
+URLCode is a portable runtime for programmable URL behavior, not a URL
+shortener. Stored short links are an operator-installed extension, not a core
+handler. The
+[project direction](../../PROJECT-DIRECTION.md) explains how application
+projects and provider adapters fit without redefining or restricting the free
+runtime.
+
+This is the public delivery sequence. Tests accompany every feature, not a
+separate late phase. The stable 0.1 self-hosted release covers much of M0/M1 plus initial
+process/container packaging and benchmarks. Provider adapters and the remaining
+production-readiness gates remain open.
+
+## 0.4.0-alpha.2 — current alpha
+
+`0.4.0-alpha.2` is a behavior-changing release on top of `0.4.0-alpha.1`:
+**`function` and `middleware` routes now run trusted and unsandboxed by
+default** — in the host process, with full Node/filesystem/network access,
+exactly like any other project code — instead of always dispatching through
+the QuickJS/WebAssembly worker pool. Sandboxing is now an explicit per-route
+opt-in via `sandbox: true`; a route that declares it gets exactly the
+isolation every earlier alpha provided, unchanged. See
+[docs/SPIKE-DEFAULT-TRUST-MODEL.md](../../SPIKE-DEFAULT-TRUST-MODEL.md) for
+the maintainer's decision and rationale, and
+[docs/FUNCTION-SECURITY.md](../../FUNCTION-SECURITY.md) for the resulting
+contract of both execution modes.
+
+**This changes existing projects with no YAML edit.** Every `function`/
+`middleware` route that does not declare `sandbox` — which, before this
+release, meant every such route in every existing project — now runs trusted
+instead of sandboxed the moment the runtime is upgraded to `0.4.0-alpha.2` or
+later. Binding grants (`env`/`secrets`) are unaffected: a route still
+receives only what it declares and an operator policy pins to the project
+revision, whether trusted or sandboxed. Review which of your project's
+`function`/`middleware` routes handle input or code you would not otherwise
+trust with full Node/filesystem/network access, and add `sandbox: true` to
+those specifically (docs/AI-AUTHORING.md's "Deciding when a route needs
+`sandbox: true`") before upgrading a project that relies on the old,
+always-sandboxed behavior. An operator policy pinned to a project's revision
+is invalidated by this upgrade regardless of whether the project's own YAML
+changed, since the project hash includes the trust-model-affecting change;
+re-derive and re-approve it (`urlcode permissions`) after upgrading.
+
+## 0.4.0-alpha.1
+
+`0.4.0-alpha.1` is the first alpha of the extension contract and the agent
+tooling on top of the `0.3.0` self-hosted release. It carries: the
+revision-pinned extension contract, capabilities and provider conformance,
+strict redirect interchange, bulk import, recipes and search, TypeScript
+guests, conditions, bounded proxy and signals, MCP read and authoring modes,
+the `context`, `explain`, `manifest` and `schema` queries, short forms,
+route-level auth, `init --with`, the agent benchmark harness, `llms-full`,
+and the generated `AGENTS.md` and skill. It is an alpha: provider
+deployments, soak and independent security review remain open. The
+extension packages declare `@jimhoyd/urlcode >=0.4.0-alpha.1 <0.5.0` and
+are published after core.
+
+## Extensions: accounts, administration and presentation — implemented, unreleased
+
+The runtime now carries a generic, revision-pinned extension contract
+(`@jimhoyd/urlcode/extensions`, [extensions](../../EXTENSIONS.md)): a project
+declares versioned `extensions.<name>` blocks, exclusive `extension` mounts and
+`policies.extensions` requirements; the operator supplies the implementations
+in a host file loaded with `--host-file`, outside the project. Guest requests
+never see `Cookie`, `Authorization` or declared credential headers. Cloudflare
+refuses extensions until its artifact format can run them.
+
+The implementations live in their own repositories, each with an
+implementation-status file that is the authoritative feature list:
+[urlcode-auth](https://github.com/jimhoyd-com/urlcode-auth) (accounts, sessions,
+MFA, roles, account page, operator CLI), [urlcode-admin](https://github.com/jimhoyd-com/urlcode-admin)
+(users, sessions, roles, audit, approvals, cases, impersonation) and
+[urlcode-ui](https://github.com/jimhoyd-com/urlcode-ui) (escaped templates,
+partials, themes, translations). All three are Apache-2.0 and published to
+npm as `0.1.0-alpha.1` while first-release acceptance is reviewed; see
+[issue 58](https://github.com/jimhoyd-com/urlcode/issues/58) for what remains:
+browser and device WebAuthn coverage, accessibility assessment, soak, backup
+and recovery drills on a deployment, live provider senders and independent
+security review. [The framework](../../FRAMEWORK.md) describes how the four
+packages compose, and [next steps](NEXT-STEPS.md) is the phased plan to
+close the remaining gaps.
+
+## Capability foundation — implemented, unreleased
+
+`urlcode capabilities [--target self-hosted|cloudflare|aws|vercel] [--json]`
+and the public capability API centralize target support for handlers, bindings
+and effective policies. Runtime activation and Cloudflare builds use the shared
+preflight; unknown targets fail closed and unsupported requirements identify the
+route and capability before resources or artifacts are created. The existing
+compiled route IR is documented, not replaced. Configuration-dependent and
+delegated behavior remain explicit; all provider deployments remain unverified.
+See [capabilities](../../CAPABILITIES.md) and the
+[next-phase review and implementation status](NEXT-PHASE-PLAN.md).
+
+## Portability and URL behavior — implemented, unreleased
+
+Strict redirect interchange supports CSV/JSON/YAML, Netlify and Cloudflare
+`_redirects`, a bounded Netlify TOML subset and Vercel redirects. Conversion
+reports refuse unsupported semantics; provider differences require explicit
+acknowledgment and are never called lossless. A synthetic conformance fixture
+and bounded HTTPS runner distinguish local adapter tests from observed
+provider deployments. Actual Cloudflare/AWS/Vercel deployment evidence remains
+pending; this does not complete M4.
+
+Exact query/header/cookie/origin/method conditions and disjoint conditional
+redirect/response cases run in the self-hosted, AWS and Vercel runtimes.
+Cloudflare refuses these until its compiler can preserve their semantics.
+Self-hosted proxy and webhook signals use explicit revision-pinned operator
+origin grants, connection-pinned public DNS and bounded transport. Signals
+have no durable delivery or retry guarantee. Other targets refuse proxy and
+signals. See [conditions](../../CONDITIONS.md), [egress](../../EGRESS.md),
+[interchange](../../INTERCHANGE.md) and
+[provider verification](../../PROVIDER-VERIFICATION.md).
+
+## Developer ecosystem — implemented, unreleased
+
+Bundled Git-owned recipes, safe bulk imports into route includes, build-time
+TypeScript guest transpilation, read-only inspection APIs and optional stdio
+MCP tooling are available. The runtime still executes only JavaScript, and
+TypeScript authoring adds no execution mode: transpilation happens at build
+time, is not type checking, and a `sandbox: true` route's emitted JavaScript
+runs inside QuickJS/WASM exactly as before. Bulk benchmarks
+successfully cover 1,000, 10,000 and 100,000 routes without relaxing parser
+limits. See [recipes](../../RECIPES.md), [bulk evidence](../../BULK.md),
+[TypeScript authoring](../../TYPESCRIPT-AUTHORING.md) and
+[SDK/MCP](../../TOOLING.md). These features do not supply durable signals,
+protected downloads, a remote marketplace or provider deployment proof.
+
+## TypeScript source and shipped declarations — implemented, unreleased
+
+The runtime, scripts, tests and benchmarks are TypeScript under a strict
+configuration, checked by `npm run typecheck` inside `npm run verify`. The
+package ships `dist/`: Node's own type stripping of the source with the
+specifier extension rewritten, so it is the same JavaScript line for line,
+plus `.d.ts` declarations for every export (`urlcode`, `@jimhoyd/urlcode/plugins`,
+`@jimhoyd/urlcode/policies`, `@jimhoyd/urlcode/observability`, `@jimhoyd/urlcode/compliance`,
+`@jimhoyd/urlcode/prerender` and the three provider entries). `dist` is never
+committed; the build runs in the digest-pinned release container, its hashes
+are recorded in the manifest, and a CI job builds twice and diffs the trees.
+Measured cold start, throughput and memory of `dist/` equal the previous
+JavaScript (see [performance](../../PERFORMANCE.md)). Contributors need Node
+22.18+ to run the source directly; installed packages still run on 22.13+.
+See [TypeScript](../../TYPESCRIPT.md).
+
+## Host policies and plugins — implemented, unreleased
+
+A `policies` block in YAML, reusable `profiles` and an operator plugin API
+close the gaps the [extensions spike](SPIKE-EXTENSIONS.md) ranked
+highest: no cross-cutting behavior, no per-client throttle, no bot policy, no
+security-header preset, no compression and no response cache. Five policies
+(`throttle`, `agents`, `security`, `compression`, `cache`) run in the host
+process after route match and before the route contract, all off by default,
+with a per-target table that refuses at activation what a target cannot
+enforce: the serverless adapters take `agents`, `security`, `cache` and
+route-partitioned `throttle`; the Cloudflare build compiles `agents` and
+`security` into the artifact and refuses the rest with the route named.
+`--trusted-proxies` names the hops allowed to set `X-Forwarded-For` for client
+identity. Plugins are host code passed to `startServer` and the adapters on
+the same hook seam the policies use; nothing in YAML names one. See
+[policies](../../POLICIES.md) and [plugins](../../PLUGINS.md).
+
+This checkpoint is on a branch and not in a published release. An
+interoperability review of the five policies together, the spike's `report`
+mode headers on every target and the audit's policy table remain open, and no
+deployment has exercised a policy on a provider.
+
+## Provider adapters — Vercel and AWS Lambda native handlers
+
+`@jimhoyd/urlcode/vercel` serves a project as a Vercel Node function, reusing the
+runtime's transport-agnostic handle() and a shared response writer, so a
+deployment returns byte-identical status, body and headers to the self-hosted
+server. Bindings arrive through a `URLCODE_POLICY` environment variable holding
+the same revision-pinned grant document the operator policy file carries.
+
+Native handlers only: `function` and `middleware` routes are refused at
+activation, trusted or sandboxed alike, because they need the self-hosted Node
+lifecycle and a sandboxed one would pay worker and WASM startup on every cold
+start. The
+`@jimhoyd/urlcode/aws` does the same for a Lambda Function URL or API Gateway HTTP API.
+Payload format 2.0 only: format 1.0 supplies an already-decoded path and query,
+and this runtime rejects ambiguous encoding deliberately, so rebuilding a target
+from decoded parts would misrepresent the request. Response policy, including
+content length, now lives in one place shared by every host rather than partly
+relying on Node's implicit behaviour.
+
+Neither adapter has been deployed; see the [Vercel](../../VERCEL.md) and
+[AWS](../../AWS.md) guides, which state what stays unverified as a result.
+
+## Provider targets — Cloudflare Workers
+
+Cloudflare Workers has no worker threads, no filesystem and no runtime code
+generation, so it gets a compiler rather than an adapter: `urlcode build
+--target cloudflare` emits a Worker, the compiled routes and Ajv standalone
+validators, and `@jimhoyd/urlcode/cloudflare` serves them with the same matching, request
+policy and response policy as every other host. Declarative routes only —
+redirects and declared responses with parameters, defaults, validation, response
+headers, `enabled` and `expires`. Functions, middleware, assets and
+bindings are refused at build time with the route named, so an unsupported
+project fails the build instead of the deployment. Bindings are refused even as
+literals, because a build artifact must never carry a secret.
+
+Making this possible moved request-time matching into `src/match.ts` and header
+validation into `src/header-validation.ts`, both free of Node imports, so one
+implementation now serves the Node server, the serverless adapters and the
+Worker. `test/header-validation.test.ts` compares the header rules against
+`node:http` across the full character range, because disagreeing there is header
+injection, and `test/cloudflare.test.ts` asserts the Worker and the self-hosted
+server return the same status, body and headers for the same project.
+
+This has not been deployed to Cloudflare; see the
+[Cloudflare guide](../../CLOUDFLARE.md) for the two request-level differences the
+platform imposes and what stays unverified.
+
+## Installation and publication — 0.1.0
+
+Added a tag-driven release workflow that reuses the audited candidate build path,
+publishes a GitHub release with the signed tarball, SBOM, manifest, `SHA256SUMS`
+and a rendered Homebrew formula, and optionally publishes to npm (with
+provenance) and GHCR behind repository variables. Added a checksum-verifying
+`install.sh`, a Homebrew formula template rendered only from measured bytes, and
+an [installation guide](../../INSTALL.md) covering npm, Homebrew, the script, the
+container and provenance verification.
+
+0.1.0 was released from this pipeline: the GitHub release carries the signed
+tarball, SBOM, manifest, `SHA256SUMS` and Homebrew formula, and an install from
+the published release was verified end to end. npm and GHCR publication stay
+opt-in and remain unproven until enabled, so the Homebrew formula's registry URL
+does not resolve yet.
+
+Added tunnel and [monitoring](../../MONITORING.md) recipes, and extended
+`urlcode benchmark` to measure a running deployment through its real path with
+warm-up and shed/transport separation; see [load testing](../../LOAD-TESTING.md).
+M3's remaining gap is sustained soak and slow-peer behaviour, which that tool
+does not cover.
+
+## Hardening checkpoint — alpha.8
+
+Bound HTTP admission and inactive sockets, and correct management
+defaults/method responses.
+The [readiness register](../../RELEASE-READINESS.md) distinguishes tested safeguards
+from deployment and stable-release gates. Feature breadth does not imply stability.
+
+## Live short links — alpha.8 (removed from core, superseded)
+
+Implemented an optional native `link` handler, local SQLite persistence, CLI CRUD
+and a separate authenticated management API. Links became visible without YAML
+changes/reloads; versioned writes prevented silent lost updates. No guest storage
+or network access was added. Same-host only; distributed storage, general state,
+user accounts and provider adapters remained open.
+
+This native `link` handler, its SQLite store, CLI and management API were
+removed from core in the layering work that followed. Stored short links moved
+to a separate `urlcode-dynamic-link` extension package (mount-based, like
+`auth`/`admin`), which was retired and unpublished in September 2026 without a
+successor. A project that used `link`/`dynamicLinks` now owns that storage
+itself; there is no in-core replacement and no deprecation shim.
+
+## Middleware — alpha.7
+
+Implemented route-local ordered `next()` middleware around every handler, early
+responses, request-local state and shared sandbox deadlines. Plain native routes
+retain their fast path. Native bodies stay opaque; middleware coverage requires
+explicit assertions. See [middleware](../../MIDDLEWARE.md).
+
+## One starter — alpha.6
+
+`urlcode init <directory>` always creates the same function-plus-redirect project.
+There is no template selector. The public urlcode-template repository mirrors
+those examples with a pinned npm dependency. Richer asset examples remain under
+examples/assets. Historical starter branches are not maintained.
+
+## Route readiness and local project benchmarks — alpha.5
+
+Implemented route inventory, expected-count checks, active route/method coverage,
+generated native probes plus explicit fixtures, and bounded assertion-aware local
+benchmarks. [Readiness](../../READINESS.md) documents the gate and remaining deployment,
+soak, remote-destination and business-coverage work. This does not complete M3/M4.
+
+## HTTP configuration and standalone starter — 0.1.0-alpha.4
+
+Implemented bounded request body/media-type/JSON checks, literal response headers
+and separate Set-Cookie values, and native text/JSON responses. See [HTTP](../../HTTP.md)
+for precise scope; automatic CORS, multipart, streaming and other listed features
+remain open. The public [urlcode-template](https://github.com/jimhoyd-com/urlcode-template)
+provides two routes with a pinned runtime dependency and cross-platform CI.
+
+## Native assets — 0.1.0-alpha.3
+
+Implemented the page/static/download portion of M2: project-contained asset
+snapshots, automatic MIME types, attachment names, HEAD, cache validators and
+single byte ranges. Dedicated public directories, symlink/hardlink rejection and
+bounded memory are part of the contract. [Asset guide](../../ASSETS.md).
+Bulk tools, recipes and best-effort signals were added in the unreleased next-phase work above; they were not part of alpha.3.
+
+## Security correction — 0.1.0-alpha.2
+
+<!-- trust-model-prose: historical -->
+All function code is untrusted. Node host execution has been replaced by
+QuickJS/WebAssembly isolation with fresh invocation state, no ambient host or
+network APIs, bounded resources, restricted module graphs and revision-pinned
+operator binding policy. This protection is part of the free product. See the
+[security model](../../FUNCTION-SECURITY.md). Full Fetch/Node
+API compatibility and network integrations were not part of that alpha and
+remain outside the 0.1 contract. That default was superseded in
+`0.4.0-alpha.2`, which made this isolation the per-route `sandbox: true`
+opt-in instead (see
+[docs/SPIKE-DEFAULT-TRUST-MODEL.md](../../SPIKE-DEFAULT-TRUST-MODEL.md)).
+
+## Earlier implementation checkpoint — 0.1.0-alpha.1
+
+Implemented: versioned strict YAML/JSON Schema subset, explicit file composition,
+redirect/parameter semantics, JavaScript Request/Response functions with bounded
+workers, scoped binding context, init/add/validate/dev/serve/test/doctor, indexed
+snapshots, last-good reloads, graceful shutdown, health/readiness, safe request
+logs, two runnable starters, ESLint and unit/HTTP/package tests. Cross-platform
+CI and a non-root container build are included. See the [contract](../../SPECIFICATION.md)
+and [operations guide](../../OPERATIONS.md) for exact support and evidence limits.
+
+Still open in the early contract: host namespaces, stable identity beyond paths,
+fuller parameter vocabulary. Build-time TypeScript authoring and capability planning are now implemented in the unreleased work above.
+No claims of complete M0/M1 or stable production readiness. M2–M4 work continues
+in the order below; a few independently useful operational foundations shipped early.
+
+
+| Milestone | Scope | Completion evidence |
+|---|---|---|
+| M0 — contract/build loop | YAML schema, matching/input semantics, function API, composition, runtime/packaging prototype, CI | Fixture validates; invalid definitions fail; verification runs |
+| M1 — local alpha | CLI, aliases, redirects, parameters, custom functions, env/secrets, indexed routes and reload | Redirect plus function tested locally without accounts/DB; invalid reload preserves working version |
+| M2 — bulk/reusable behavior | CSV/YAML/JSON, safe bulk edits/checks, templates, best-effort async signals, simple pages/static/downloads | 10k-route example, local side-effect tests, safe file serving, benchmark datasets |
+| M3 — self-hosted beta | Process/container deployment, domain/TLS guide, packages/Homebrew, ngrok, monitoring and load tools | Install, test, deploy, observe and roll back a real project |
+| M4 — provider public release | Cloudflare/AWS/Vercel adapters, provider conversion, capability/limit checks and stable docs | Baseline redirect/parameter/function fixtures on each advertised initial target; additional capability gaps explicit |
+| M5 — advanced public features | Bounded proxies, protected/one-time downloads, durable signals/state, broader catalog and API/SDK/MCP | Feature-specific guarantees, tests and portable capability reports |
+
+The first provider-capable public release is M4; the 0.1 self-hosted release is
+useful within its documented scope. A marketplace and advanced stateful
+features are not prerequisites. No web UI/TUI or framework-hosting platform.
+Netlify starts as redirect interchange after the initial provider adapters.
+
+## Launch and stabilize the free version
+
+Stability means repeatable installs/upgrades, dependable routing/functions,
+working deployment and rollback, useful diagnostics, and serious recurring
+issues from actual users addressed. Feedback begins with usable alphas, but the
+free version is not stable until that evidence exists; do not invent a calendar
+deadline or adoption-count threshold.
+
+Keep the architectural direction: reusable runtime/compiler, provider adapters,
+separate configuration and secrets, versioned artifacts, Git-owned definitions
+and observable behavior. Avoid assumptions that would force users to rewrite
+projects later. No artificial restrictions in the free version; it is licensed
+under Apache-2.0.
+
+## Starter delivery
+
+The [starter plan](../../STARTERS.md) makes both Git clone and CLI initialization
+release requirements: one function-plus-redirect starter in M1, bulk-growth examples in
+M2, and the business foundation with self-host tooling in M3. Provider recipes
+follow tested M4 adapters. All use the same runtime and portable project format.
+
+## Quality gates
+
+- Same fixtures pass on the local reference and each claimed runtime adapter.
+  A static exporter alone is not a complete function-capable adapter.
+- Pure redirects avoid Lambda/per-route user functions; generated shared routing
+  is allowed where native provider rules cannot preserve behavior.
+- CSV exports report unsupported nested content instead of silently losing it.
+- 1k/10k/100k datasets measure compile/reload, memory, latency and throughput.
+- Default tests run against local HTTP/fake services; ngrok is optional.
+- Load tests use bounded owned targets and do not follow third-party redirects.
+- Invalid reload preserves working config; secret values stay out of artifacts.
+- Installation claims match tested OS/architecture packages.
+
+Implementation runtime, exact schema/function API, first adapter order and package
+format are decided through early prototypes. Do not invent performance targets
+or advertise all providers before they pass tests.

package/docs/{SPIKE-EXTENSION-MODEL.md → archive/2026-09-19/SPIKE-EXTENSION-MODEL.md}

@@ -1,3 +1,13 @@
+# Historical record
+
+Archived 2026-09-19. This records an earlier implementation or proposal, not
+current instructions. See the [current roadmap](../../../ROADMAP.md),
+[current contract](../../SPECIFICATION.md) and [open decisions](../../OPEN-DECISIONS.md).
+Remaining acceptance work is not declared complete by archiving this record.
+
+<!-- trust-model-prose: historical-file -->
+<!-- guidance-claims: ignore-file -->
+
 # Review: the extension model, its precedents and its alignment
 
 Status: review of the [auth](https://github.com/jimhoyd-com/urlcode-auth/blob/main/docs/SPIKE-AUTH.md), [admin](https://github.com/jimhoyd-com/urlcode-admin/blob/main/docs/SPIKE-ADMIN.md) and

package/docs/{SPIKE-EXTENSIONS.md → archive/2026-09-19/SPIKE-EXTENSIONS.md}

@@ -1,19 +1,30 @@
+# Historical record
+
+Archived 2026-09-19. This records an earlier implementation or proposal, not
+current instructions. See the [current roadmap](../../../ROADMAP.md),
+[current contract](../../SPECIFICATION.md) and [open decisions](../../OPEN-DECISIONS.md).
+Remaining acceptance work is not declared complete by archiving this record.
+
+<!-- trust-model-prose: historical-file -->
+<!-- guidance-claims: ignore-file -->
+
 # Spike: plugins, adapters and optional runtime features
 
 > Status update: the host hook seam, the plugin API and the five policies of
-> section 5 are implemented; [policies](POLICIES.md) and [plugins](PLUGINS.md)
+> section 5 are implemented; [policies](../../POLICIES.md) and [plugins](../../PLUGINS.md)
 > describe the shipped behavior, which takes precedence where this text differs.
 >
 > Also stale: the embedding-API row below (`openLinkStore`, `startLinkApi`)
 > and the `link` mentions in the gaps table describe core from before `link`
-> was extracted. Core has no native `link`/`LinkStore` API any more; it now
-> lives in [`urlcode-dynamic-link`](https://github.com/jimhoyd-com/urlcode-dynamic-link).
+> was extracted. Core has no native `link`/`LinkStore` API any more, and the
+> `urlcode-dynamic-link` package it was extracted into has since been retired,
+> unpublished and deleted (September 2026).
 
 Status: exploratory. Nothing here is committed scope; it records what the
 runtime has today, how comparable tools expose the same needs, which gaps
 matter for real deployments, and a proposed shape for closing them without
-breaking the [project boundary](PROJECT-DIRECTION.md). The
-[roadmap](../ROADMAP.md) owns sequence; the [specification](SPECIFICATION.md)
+breaking the [project boundary](../../PROJECT-DIRECTION.md). The
+[roadmap](ROADMAP.md) owns sequence; the [specification](../../SPECIFICATION.md)
 owns what is implemented.
 
 Every feature below is **optional and off by default**. A `version: "1"`
@@ -63,10 +74,10 @@ delegating them to the provider.
 
 The docs are consistent that these belong at ingress, not in route YAML:
 rate limiting, WAF, TLS, DDoS mitigation, forwarded-header trust
-([resilience](RESILIENCE.md), [capacity](CAPACITY.md)). Compression, CORS,
+([resilience](../../RESILIENCE.md), [capacity](../../CAPACITY.md)). Compression, CORS,
 content negotiation and streaming are listed as explicitly outside the
-[HTTP contract](HTTP.md). Caching is declarative and limited to a fixed
-`cacheControl` vocabulary on asset handlers ([assets](ASSETS.md)).
+[HTTP contract](../../HTTP.md). Caching is declarative and limited to a fixed
+`cacheControl` vocabulary on asset handlers ([assets](../../ASSETS.md)).
 
 ## 2. How comparable tools do it
 
@@ -78,7 +89,7 @@ content negotiation and streaming are listed as explicitly outside the
 | Injection / hardening | `helmet`, `express-validator` | `@fastify/helmet`, schema validation built-in | `secureHeaders`, `validator` | Built-in header directives | Header directives | Managed WAF rulesets | Header injection prevented at runtime; body JSON syntax check; **no** security-header preset, no schema body validation |
 | Compression | `compression` | `@fastify/compress` | `hono/compress` | `encode gzip zstd` | `gzip on; brotli` | Automatic at edge | None; identity only |
 | Caching | `apicache`, CDN | `@fastify/caching` | `hono/cache` | `cache` (plugin) | `proxy_cache` | Edge cache + `Cache-Control`, ISR | Asset `cacheControl` vocabulary; no response cache |
-| Templates | `res.render()`, view engines | `@fastify/view` | `hono/jsx`, `html` helper | `templates` directive | SSI | Framework-owned | None at request time; build-time [prerender](PRERENDER.md) only |
+| Templates | `res.render()`, view engines | `@fastify/view` | `hono/jsx`, `html` helper | `templates` directive | SSI | Framework-owned | None at request time; build-time [prerender](../../PRERENDER.md) only |
 | Adapters | `serverless-http`, `@vendia`, `@hono/node-server` | `@fastify/aws-lambda` | First-party adapters for every runtime | n/a | n/a | n/a | Vercel, AWS, Cloudflare; native handlers only |
 
 Three patterns recur and are worth borrowing:
@@ -111,12 +122,12 @@ Ranked by how often a self-hosted operator hits it before the first deploy.
 | G9 | Adapters refuse functions/middleware/links | Documented and deliberate, but it means any feature built as guest middleware is also refused on serverless | Design constraint |
 | G10 | No JSON Schema body validation | `request.body.format: json` checks syntax only | Low |
 | G11 | No CORS preflight helper | Documented gap | Low |
-| G12 | No SPA fallback for client-routed apps | [Assets](ASSETS.md) rules it out beside directory listing and trailing-slash redirects; a host plugin cannot supply it either, because an unmatched path throws 404 before the request object or any plugin hook exists | Low |
+| G12 | No SPA fallback for client-routed apps | [Assets](../../ASSETS.md) rules it out beside directory listing and trailing-slash redirects; a host plugin cannot supply it either, because an unmatched path throws 404 before the request object or any plugin hook exists | Low |
 
 ## 4. Design constraints these must respect
 
-From [AGENTS.md](../AGENTS.md), [project direction](PROJECT-DIRECTION.md)
-and [function security](FUNCTION-SECURITY.md):
+From [AGENTS.md](../../../AGENTS.md), [project direction](../../PROJECT-DIRECTION.md)
+and [function security](../../FUNCTION-SECURITY.md):
 
 - Route YAML describes **behavior**, not infrastructure. A throttle budget is
   behavior ("this route allows 10 requests per minute per client"); a Redis
@@ -356,7 +367,7 @@ Rules:
 ### 5.6 Templates
 
 Request-time templating conflicts with the opaque-native-body rule, and the
-[prerender](PRERENDER.md) helper already handles the static case. Two
+[prerender](../../PRERENDER.md) helper already handles the static case. Two
 bounded options fit the boundary:
 
 1. **Build-time only (recommended first).** Promote prerender into a CLI
@@ -401,7 +412,7 @@ not offered: anything stricter is a per-project decision.
 
 1. **Network and edge.** Volumetric protection, TLS termination and
    per-client connection budgets stay with the hosting provider or the
-   reverse proxy, as [resilience](RESILIENCE.md) already states. Runtime
+   reverse proxy, as [resilience](../../RESILIENCE.md) already states. Runtime
    policies are a second layer, never the first.
 2. **Ingress to origin.** Bind privately; allow only the proxy's addresses;
    pass `--trusted-proxies` so `client` partitioning uses the real peer.