@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/ROADMAP.md

@@ -1,7 +1,8 @@
 # Public roadmap
 
 URLCode is a portable runtime for programmable URL behavior, not a URL
-shortener. Live links are one handler in the broader project contract. The
+shortener. Stored short links are an operator-installed extension, not a core
+handler. The
 [project direction](docs/PROJECT-DIRECTION.md) explains how application
 projects and provider adapters fit without redefining or restricting the free
 runtime.
@@ -11,6 +12,121 @@ separate late phase. The stable 0.1 self-hosted release covers much of M0/M1 plu
 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](docs/SPIKE-DEFAULT-TRUST-MODEL.md) for
+the maintainer's decision and rationale, and
+[docs/FUNCTION-SECURITY.md](docs/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](docs/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](docs/FRAMEWORK.md) describes how the four
+packages compose, and [next steps](docs/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](docs/CAPABILITIES.md) and the
+[next-phase review and implementation status](docs/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](docs/CONDITIONS.md), [egress](docs/EGRESS.md),
+[interchange](docs/INTERCHANGE.md) and
+[provider verification](docs/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](docs/RECIPES.md), [bulk evidence](docs/BULK.md),
+[TypeScript authoring](docs/TYPESCRIPT-AUTHORING.md) and
+[SDK/MCP](docs/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
@@ -57,9 +173,10 @@ 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: isolated functions, middleware and stored live links are
-refused at activation, because every cold start would pay worker and WASM
-startup and a serverless filesystem cannot hold a durable link store. The
+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
@@ -78,7 +195,7 @@ generation, so it gets a compiler rather than an adapter: `urlcode build
 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, stored links, assets and
+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.
@@ -119,18 +236,25 @@ does not cover.
 
 ## Hardening checkpoint — alpha.8
 
-Bound HTTP admission and inactive sockets, drain accepted link writes on shutdown,
-reject invalid store metadata, and correct management defaults/method responses.
+Bound HTTP admission and inactive sockets, and correct management
+defaults/method responses.
 The [readiness register](docs/RELEASE-READINESS.md) distinguishes tested safeguards
 from deployment and stable-release gates. Feature breadth does not imply stability.
 
-## Live short links — alpha.8
+## 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 become visible without YAML
-changes/reloads; versioned writes prevent silent lost updates. No guest storage
-or network access is added. Same-host only; distributed storage, general state,
-user accounts and provider adapters remain open. See [dynamic links](docs/DYNAMIC-LINKS.md).
+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 are
+moving to a future `urlcode-dynamic-link` extension package (mount-based, like
+`auth`/`admin`, not yet published). A project that used `link`/`dynamicLinks`
+needs that extension once it ships; there is no in-core replacement or
+deprecation shim.
 
 ## Middleware — alpha.7
 
@@ -167,17 +291,21 @@ 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](docs/ASSETS.md).
-Bulk tools, templates and signals remain open; M2 is not complete.
+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](docs/FUNCTION-SECURITY.md). Full Fetch/Node
 API compatibility and network integrations were not part of that alpha and
-remain outside the 0.1 contract.
+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](docs/SPIKE-DEFAULT-TRUST-MODEL.md)).
 
 ## Earlier implementation checkpoint — 0.1.0-alpha.1
 
@@ -190,7 +318,7 @@ CI and a non-root container build are included. See the [contract](docs/SPECIFIC
 and [operations guide](docs/OPERATIONS.md) for exact support and evidence limits.
 
 Still open in the early contract: host namespaces, stable identity beyond paths,
-TypeScript support, fuller parameter vocabulary and capability/artifact planning.
+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.
 

package/SECURITY.md

@@ -1,13 +1,28 @@
 # Security
 
-Application functions are **untrusted by default**. Alpha.2 replaces direct Node
-execution with QuickJS/WebAssembly isolation. Worker threads alone are not the
-security boundary. There is no unrestricted host-execution fallback.
-
-Guests have no Node, filesystem, shell, network or ambient process-environment
-access. Each invocation gets fresh state and bounded resources. Imports stay
-inside a snapshotted project module graph. Binding grants come from operator
-policy outside the project and are pinned to the configuration/code revision.
+Project `function`/`middleware` code is **trusted and unsandboxed by default**:
+it runs directly in the host process, exactly like any other project code,
+with full Node, filesystem and network access (docs/SPIKE-DEFAULT-TRUST-MODEL.md).
+A route opts into isolation explicitly with `sandbox: true`, which dispatches
+that route through the QuickJS/WebAssembly worker pool instead — unchanged
+from the isolation this project has always provided, still the boundary to
+reach for when a route's code specifically warrants it (input from a source
+the project doesn't fully trust, a contribution nobody has reviewed, logic
+handling an especially sensitive secret).
+
+A `sandbox: true` guest has no Node, filesystem, shell, network or ambient
+process-environment access. Each invocation gets fresh state and bounded
+resources. Imports stay inside a snapshotted project module graph. Binding
+grants — for a trusted route as much as a sandboxed one — come from operator
+policy outside the project and are pinned to the configuration/code revision;
+trusting a route's code by default does not grant it any `env`/`secrets` it
+was not explicitly declared and pinned to receive. This is a claim about what
+URLCode injects into `context.env`/`context.secrets` for a route, not an
+access-control boundary on trusted code itself: a trusted (non-`sandbox`)
+route runs with full Node access by design, so its own code can read
+`process.env`, the filesystem or the network independently of anything the
+binding grant declared or withheld. The grant only governs what URLCode hands
+that code through `context`; it is not a restriction the code is confined to.
 See the [security model and policy instructions](docs/FUNCTION-SECURITY.md).
 
 The host/runtime and sandbox engine still require patching, independent review
@@ -16,6 +31,13 @@ execution platform. Authorized inputs/secrets can be exposed
 by code receiving them; grant the minimum required authority. Do not deploy
 older snapshots for untrusted functions; review and upgrade to the current revision.
 
+Declarative proxy and signal handlers run in a separate bounded host transport;
+they do not grant guest networking. They require per-route, per-purpose HTTPS
+origin grants pinned to the project revision. Every connection checks public
+addresses and pins DNS, refuses redirects, filters headers and limits resources.
+See [egress semantics and limitations](docs/EGRESS.md). Build-time TypeScript
+transpilation and read-only MCP do not execute project code in the host.
+
 ## Report a vulnerability privately
 
 Use [GitHub private vulnerability reporting](https://github.com/jimhoyd-com/urlcode/security/advisories/new).
@@ -36,5 +58,5 @@ Bind loopback by default; protect public deployments with HTTPS, rate limits,
 network controls and restricted operational endpoints. See [operations](docs/OPERATIONS.md).
 
 See the [internal security reviews](docs/SECURITY-AUDIT.md) — most recently
-2026-09-17 — for fixed findings and remaining gates. Use a current reviewed commit: the shared 0.2.0
+2026-09-17 — for fixed findings and remaining gates. Use a current reviewed commit: the shared 0.3.0
 version label alone does not identify which hardening patches are present.

package/dist/BUILD-MANIFEST.json

@@ -1,60 +1,85 @@
 {
-  "node": "v26.8.2",
+  "node": "v26.9.0",
   "files": {
-    "dist/adapters.js": "40e5c2d0ff4be8b11752418f063a9e79e29e31b6a64c92a19a514f182268133c",
-    "dist/agent-lists.js": "fa1e87b928bf7178d7e910584018ef330a164be834156a8728f8d33ed7353211",
+    "dist/adapters.js": "a7153ec52f2ed7e0cdd8ed7d433504815f402ec53b2b1c3d38d0cf0e2fcf6509",
+    "dist/agent-lists.js": "35ab484198897501d011cb6cc00b5a6787192e19df29c97646e8c118fcc19eef",
+    "dist/agents-guide.js": "a76e9818ec995a349085a53e8badd3ef49734275557b50bc7dcbe995ce3d0e9f",
     "dist/assets.js": "0833b093d2fe457ce68281110dc07d47914992753607741c13b339d92c76cf5c",
-    "dist/authoring.js": "99c3fe70df840ccc2a57b887b6b5886998a1155e848c3b6804a89bd1e257b05b",
-    "dist/aws.js": "1384e417de68404b5f1f35ee8a9148271b6efa0965a64e458d7bbda0234cc564",
-    "dist/build-cloudflare.js": "65af88384795bd7a4e2374c2cd9e5be174e3ffd4142f705723a3f5115a28eb27",
-    "dist/cli.js": "4cb9a0a6d85ac4b101b72cd71dbdb3ca17c8ab1d064986f9923e4a5254b8b7a9",
-    "dist/client-address.js": "292b86165def33247b05ef619e15245b70765522c8d9dc0ca4fac6e22e531de8",
+    "dist/authoring-files.js": "ad32814f9ae9c549c6247396f982aa700d13a293cc0a589609eccc68f8965550",
+    "dist/authoring.js": "ec5240e8686c124f4601229b45f89ce112d9eeb9d35e3059fe55e93056c45209",
+    "dist/aws.js": "7d8e3a97b4f6dbefbd68da058f05192469d1efcaed5458b284863ebe462e060e",
+    "dist/build-cloudflare.js": "af4f49ad45287d7c4105bb84b1592b5b8e76c930f7159505338298f7c5fd5651",
+    "dist/build-static.js": "a2d2fcef3099805392da9140096d9843226bfb582dc046acf9a77f37b8a0d528",
+    "dist/bulk.js": "aac88d422bd9a7a341a421fb4e29ff5580b28d39250b7f1f5315ba20ae92da8a",
+    "dist/capabilities.js": "28dba05b3851b8b12b3c1b809af87b732f84d601c737afe9225abe429886e691",
+    "dist/capability-query.js": "ba148b27c6a60f8c895f13f26468b16c18ae0a5cddea26b602965c8efbba90ae",
+    "dist/catalog.js": "ab1c01c9296cc277d2bd4fd682aeb053656a7d9f91c61974f4b78feea0211de8",
+    "dist/cli.js": "f6097c246c6b9006df58e3463648013ec8837ab3296a8c294809313503be167a",
+    "dist/client-address.js": "9d0d01466aab23124330605c5a0e0f981f87c897858acfad909f546a63df165b",
     "dist/cloudflare.js": "17b43b0a6b6a0ef8a893415c989e4ae3976d97cc966adbf897b785f9adc472e3",
-    "dist/compliance-rules/baseline.js": "6746ed9717fcbc414d4892ec54afca74496dcc725f2c80d417e382c190294811",
-    "dist/compliance-rules/privacy.js": "fe8330fd4c5068645e5c41db389fd190d7423e822397bf3938ca48d275bd449c",
-    "dist/compliance-rules/shared.js": "595a7ee3a5af8c52197c5c9cbf09f4289a234e52b7a198afdd498be9be8d28a1",
-    "dist/compliance-rules/strict.js": "937b55f4574eb5ca9f238b1a9658b089d006372328da35a329e4359719e6c3d0",
-    "dist/compliance.js": "e956dc89b0b729fed7031297b8d7554141110334e670edf5cedc3d052a8fb3e4",
+    "dist/compliance-rules/baseline.js": "6296dea6bcb9f9bb80ed6ed5ab2f456e7f74e6de2be5d2d98ca8c983fb4df3ab",
+    "dist/compliance-rules/privacy.js": "4cfb1c07d7df698c362dfc8761cd3bba893769e92d7fb0a3901e1c2d25e801f1",
+    "dist/compliance-rules/shared.js": "86fd6db6a93375689acc64975cbc394ce9452dea21ae5941e743f99822515995",
+    "dist/compliance-rules/strict.js": "73ee13c2f893acf20cc3d44bf054e58c1474dec52eafe0cf2ce7f4eb96a3bc53",
+    "dist/compliance.js": "29a18da3cefea94802ac7d817d1ab4e3674abd5c3ac4ef893cb8b01c6a23fb61",
+    "dist/conditions.js": "ff25e97da550a3bdd80af55522045669438aa31a77d2bc83ad602bcefdee0475",
     "dist/config-worker.js": "bc2170d60c35f8d5de227cbfc4c5067dc61d7cbc5b98aed88e68a11797072da5",
-    "dist/config.js": "d0e0d100f3f97d3cefd17d898dddea463773092569a7cd7c3384bd547847659f",
+    "dist/config.js": "0cd82b4c407848f9c66e804a6dd4bf9a8a8503264e51584456578073e0f01921",
+    "dist/context.js": "549a53e4738b9c20a1ec55614027f758026fb5860bf4ac962ce22d7029e48df0",
+    "dist/ecosystem-cli.js": "1e71bacd53d6fa8c7857cfcce3c3012ce054771a434b78d1f39e892e32642edd",
+    "dist/egress.js": "2ae29fe2cb4590fd2f715abe6817db47fed2f50dd31f37946ecf42eafbb0dd9e",
     "dist/errors.js": "a908e66496afebbdd632a8c159a6e14d23f8f38798a0b4342ca122f2511c6cde",
-    "dist/function-sources.js": "48b470fbdcef2ad2c83e61a6476d5499210d0937b72518ae01fb2b9225b0e16b",
-    "dist/function-worker.js": "3f5bad4f1b5cb812924c2dcc73ece6f816cf6aac26cd471fd1030dcfbf009c3b",
-    "dist/functions.js": "6b1e5d4a3f8db17d4e5df261b98ed15f5f0c5e5507a6fc0f472e9f94ed2b6090",
-    "dist/guest-api.js": "bc2501496a6ef9fd20dddb606fbc6fd557d534dd075e7ad38406248b230013ed",
+    "dist/examples.js": "89ae2b764a688fe52acfb9b94d3d262d7742401ebd0ef10c9ebfc76edfa5631c",
+    "dist/explain-cli.js": "dd342b21a96fc97a11488ac3528793ba0f5d4744b74a1d99085e142c4737b69a",
+    "dist/explain.js": "9450d2699cbe65e5c078c443ba7a6cba95c748e75d455e05264083b3c93c92a2",
+    "dist/extensions.js": "fed2b394466a7d406f9edeaedb71d9da81e50e3150eb7d01f2e7659104afeac7",
+    "dist/function-sources.js": "16fad4abc81c7ee07b6cbcef2d23a9fc50e97a17cb4dde1db53469bbb555c96f",
+    "dist/function-worker.js": "35771790ada4e1b36d447d4967a5e6cf0b543f32944e4c904f5fbf8998e824a5",
+    "dist/functions.js": "0f09d1bd27eb655ceb5900a4a5e2b760d2028b02cb637a6a89a4eb5940828008",
+    "dist/guest-api.js": "49aec9ed72733ad119e63bcfcee18158dcc8ceb951e1823b8947f6407ff24afc",
     "dist/header-validation.js": "465181dbb08ff05f52defdd29fda025c0c64589bf319fa87fa6d3ab4b68216d5",
     "dist/http-policy.js": "4cb187642269078ddf3460a3f1813dc57878a616a6f8132ef8f8d3b4b91ebb56",
     "dist/http-response.js": "5fc3bb9eb932a3fd2fbc72c361416a5f1439b8bf45b2be37baca1c6446abf40c",
-    "dist/index.js": "648878ef26cb3a8eb075a5ddd4d044022afe6cf5e5e38d1bd6ea418b82791371",
-    "dist/link-api.js": "0d1f2fb5ef8cd6fda7b071d3e08c53eb4b1c01d4003167af2f400949b70dea4f",
-    "dist/link-cli.js": "5f45e62a6b935112cabfcd12691a5ebc01d9c87f92e4befb655380d9e752323b",
-    "dist/link-events.js": "502a6038a538fa43094a9ba9c7546f504b4a1832a1377f26ca8cb69c2326670e",
-    "dist/link-records.js": "ef67a58cd107db0c3ac1c0ffd7b32817553606cf69bb3002da4ca0138c272f69",
-    "dist/link-store-worker.js": "0080452bbada2154b923449cd14596579bde94ad5f8dab94ecc84aa0d59c089b",
-    "dist/link-store.js": "526cdbe1b917cc7a74fb6edbbf13717d823ace5b5d6a5f89bc91438056a10b37",
+    "dist/index.js": "7e9f6ec8a125e2dfd4230b2ecd17ac513c0153d778a57bbcee7a1a9cd9681f81",
+    "dist/init-with.js": "8371f568867ebdc6ab8e9aa762234ae2aa015865f46aa901254528e20d69b791",
+    "dist/interchange-cli.js": "35bd70ba8077af5c3e39404ff0e5d28707632090a59a90645141252449fd3f04",
+    "dist/interchange.js": "26789420af33344d9a08c00fe6b2708aa71994224df527b3075295be2151611e",
     "dist/logging.js": "8ec57fea26983aa071b05fe15d680d6550b03488101163ed9666da674118cf31",
-    "dist/management-policy.js": "ad573627de0e9f9b5368d701966468f391f53d64d2a82bfd8083bca412b01721",
-    "dist/match.js": "a0935ee5a3c68d85c268abbdcecd30a7ebd68e37bbecb68136479b1f94fc3705",
-    "dist/observability.js": "28a446ad867329e58cbccb9215a343a390e8599dad6a31c1db0e702d3df67e27",
-    "dist/plugins.js": "c228ec42cd727f259193fe905ae247f9fba34f695dd1364d8e3ee6683262da7c",
-    "dist/policies/agents.js": "761920214db2ada60733743541f134928ba1d2f0bc763660bd0d1112a725c887",
-    "dist/policies/cache.js": "ef16d7e592526c29f865b2693faa2c8afbea41c6526687563dffcb13a77fc1f7",
-    "dist/policies/compression.js": "d342c6db4a9bee63b62b35654dde28fa163bfd82510bb85331bb9b072f856781",
-    "dist/policies/security.js": "119fb37bd0e994ddabf3feacbc52d481c8e8c65b0ac6b71c8d3533b8c3e2cedb",
+    "dist/manifest.js": "977f0f1cbe4466f7fbd9f2a0745e016cb9ebae640bc264fba04b4d02f4dbaca9",
+    "dist/match.js": "53ebcc2cda529a8d07fb83f8cb69a1446036ffc1641af3c4bd45a55851bded28",
+    "dist/mcp-authoring.js": "5030f52ef9c7ebc7b97305fcce687eb0a0d6164e34fda87f8278135a1e6f3d65",
+    "dist/mcp.js": "e2d70f63481dc40aae60f7c27128e6a09ec370b69fd68aee8890bcc990f4f304",
+    "dist/observability.js": "f4b1ab496f051fe3ef2ed36b2b2e469c63a8940700e2df852e6ff2d9cccdd5ae",
+    "dist/operator-host.js": "e3dac9d43a83beb775202b4ab9eeeba7ac63cebfc5dcc669be38d825be587bd0",
+    "dist/plugins.js": "a61aa933cd9e1b41020b86fae78aa3a7f45f5313124aa11b50cb57898722385e",
+    "dist/policies/agents.js": "c1dbc1e90339f472eeeb2372f7f4637f59a5d210797ea680ac8120a02aa20c10",
+    "dist/policies/cache.js": "03f79b91694bb78a98de4473384e5110e1ae1c3c83d46f929495d03af04d9da1",
+    "dist/policies/compression.js": "800f3ae3b1a4c1fe58c3d9908364ea9d78f655ff50c7f7589f584378e7f194b0",
+    "dist/policies/security.js": "2b3bfdf82140156fea4b162adc28ee43ccd85c402fb200680dbb8d8706417420",
     "dist/policies/throttle.js": "bbb0cb1c24cf70d0a1ac32fc0618efb6c44e5b5d42564842f9c585ff7e501603",
-    "dist/policies.js": "e3f48ad730d1d7b1435bff2f2bd7091e24a0c46dd0e1393d53337d64e3a7d83d",
-    "dist/policy.js": "280f94593c9e376726e2b3d34f4c1e9817802d67134bd6a2d1afe466244b3fdc",
-    "dist/prerender.js": "f568e2773be6fe67b547739f609c0287f429451ab31187f48ffe4560df3f877b",
-    "dist/project-tests.js": "91aa9c22d9f40efb0c5318b7a05b4aee753fc1ab591fe90e8d94f24fa60697f5",
-    "dist/readiness.js": "64eedecc9405db253e2bd39819c7f5640c6017f13cf23d2a193656dda095ca45",
-    "dist/router.js": "a102132362177bb8690bde11ce2b6ea9719a79601a25165d5d36dc736b1b888b",
-    "dist/runtime.js": "1d22cdb83703e0fc15da63d28b02fbd419051894063cb2fde5072b186c98ec62",
-    "dist/scaffold.js": "9dd30112e070ec554bd7cae1ca0a8b03642632be57411ba76a72972f4ba49b3e",
-    "dist/server.js": "d8c78d1695b3c11328f3f983281fba78c2aca6a66cf755b39ecf4ec2ec4b6f29",
-    "dist/site.js": "f34b023c9bcd403d38b8a2bf4d8ba184e0ff00cbd98405b49c68747466d995cd",
-    "dist/sqlite-version.js": "a3a08d99064bd0f35847e288027e00a516efdd61c675bfbbe7726e3aa900f0d1",
-    "dist/types.js": "96650efc60f2400b7b1a6622798f0f42d43f451fa5bf18a93d06482feb2e0283",
-    "dist/vercel.js": "76092b83e4d80e29541589682e00237701a3d3f096a8045fa2cf104b6d1b6725",
-    "dist/scripts/operational-drills.js": "b7e9448279c59ee9de62023055a9ff5c7a60bcceed4c33d023edc612f5575af9"
+    "dist/policies.js": "23fa019b7bf1cdedcc5f7772d2f157e4b381a554bce9e84594c2be4a0f8f76b8",
+    "dist/policy.js": "33c527008fafe4af18243ba668d069517c20659150f9f1d1a5a1d076e8724f89",
+    "dist/prerender.js": "0386ea2411e00b9563b5349133f1d723947b01f837fa92d4c61a699c9cfb5cdb",
+    "dist/project-tests.js": "445eaa139d2f1a2534369cfdeef081ef518de03218a467e7c5c2059caf840270",
+    "dist/provider-verification.js": "ffcf9f05e8cb5f71ea46a97e279e8a613fdfdf9435ab02bd57af11e2680a9107",
+    "dist/proxy.js": "34107e59ac0dbbea090efa3cf5badf3226c5302ba25e8f8ff9b2b5596ed80e50",
+    "dist/readiness.js": "6ce69a005d7c45cf0ef97fa5eaba34279d43ebf28124eca18359d9db4f599808",
+    "dist/recipes.js": "11853f23e63c3c65c5bed03a278cde0349d28c9fa23266c9907a2df318bb5fc3",
+    "dist/route-diff.js": "eebac076a886ddfb2bf5b97ea09d81f888e7bb0063d482eddb8e5fef9acea107",
+    "dist/router.js": "cf831025d5ed6778d1d6a0e541177799794e76766c82084ded81d3e87317ca1e",
+    "dist/runtime.js": "0470dcab0774d2da3336e9ce76a4853757bf96081e52bd741f6b44c1bdd4161f",
+    "dist/sandbox.js": "c88c5aa5dd95b4f55f1ba62da7969ad66dbd97c30f72e5b5f2817a2098ac1c65",
+    "dist/scaffold.js": "3ef243aceca7ddf2780aa2c8c04ae17edd07682d3a418fd5d65ba00f5c762f14",
+    "dist/schema-query.js": "bfd1844acd8d54ac361115191fcfbaf828a67e223b9ec6e9c22f158761af149b",
+    "dist/server.js": "d878bc8f0d6a05f8fd25997cace3150e2ff4d44ee9c8f4b5530e29601e164be1",
+    "dist/signals.js": "b55e54efc8fb6703e08f2a1e808ec8e011bda67738db8ceadf1b248f695795be",
+    "dist/site.js": "c40a06a6f9e2d6d3bea94727783c115fed4309bb0190787f58434eed64cbde84",
+    "dist/tooling.js": "7409db98422325cd4181d073d645ea57debca0e54cb151123474b85f4d4ed7dc",
+    "dist/trusted-functions.js": "befd256848be786f97e372c6af0e05ac08a0c93baed38bf2470ea49bc00dd3e4",
+    "dist/types.js": "a1213d033b6a347c63e94685ab9056d8cd7a301d9c83150142afe0f3ab2c6536",
+    "dist/typescript-authoring.js": "27829098603029ab565174e540fb1d5ef68c1a923272b7186f64a362f5244872",
+    "dist/vercel.js": "a0da20c095d0c7fa8f579ed4dd5951e7a34191f8a72a57c5e782c9eab39f6f08",
+    "dist/verify-deployment.js": "0c2e68f3cf258a364728c801411df5284343bc01b75a64fe275ff84e397e998b",
+    "dist/scripts/operational-drills.js": "c26c406d28013cc554b25a5b6bf8baf4e71d5e67e50d866fae546f538a192317"
   }
 }

package/dist/adapters.js

@@ -1,19 +1,12 @@
+                                                        
 import { createRuntime } from './runtime.js';
                                                                         
 import { validatePolicy } from './policy.js';
 import { ConfigError } from './errors.js';
-                                             
 
 /** The subset of process.env a hosted adapter reads. */
                                                              
-                                                                                                          
-
-// Handlers a stateless per-request invocation cannot honour. Functions and
-// middleware need worker threads and the WASM engine on every cold start;
-// stored links need a durable writable file that instances share. Adapters
-// refuse them identically, so a project's supported surface does not depend on
-// which provider is serving it.
-const unsupported                                     = { function:'isolated functions', link:'stored live links' };
+                                                                                                                                                                
 
 export function readPolicyFromEnvironment(environment             )                             {
   if (!environment.URLCODE_POLICY) return undefined;
@@ -27,20 +20,8 @@ export function readPolicyFromEnvironment(environment             )
 
 // Activates a project for a native-handler-only host, refusing the whole
 // deployment rather than letting individual routes fail at request time.
-export async function activateNativeOnly(project        , environment             , { target = 'node', plugins }                    = {})                   {
-  const runtime = await createRuntime(project, { permissions: readPolicyFromEnvironment(environment), environment, target, plugins });
-  const refused = runtime.testPlan().inventory.flatMap(route => {
-    const reason = route.handler === undefined ? undefined : unsupported[route.handler];
-    return [
-      ...(reason ? [`${route.path} uses ${reason}`] : []),
-      ...(route.middleware ? [`${route.path} declares middleware`] : []),
-    ];
-  });
-  if (refused.length) {
-    await runtime.close();
-    throw new ConfigError(`This adapter serves native handlers only: ${refused.join('; ')}`);
-  }
-  return runtime;
+export async function activateNativeOnly(project        , environment             , { target, plugins, extensions, origin }                   )                   {
+  return createRuntime(project, { permissions: readPolicyFromEnvironment(environment), environment, target, plugins, extensions, origin });
 }
 
 // Caches a successful activation for the life of the instance. A failure is not

package/dist/agent-lists.js

@@ -10,7 +10,7 @@ import { isListFile, isBundled, validatePattern } from './policies/agents.js';
 //
 // A list file is the schema data/agents/*.json uses: either an array of
 // entries or `{ entries: [...] }`, each entry `{ name?, pattern, ... }`.
-export const MAX_LIST_ENTRIES = 4096;
+const MAX_LIST_ENTRIES = 4096;
 
 function listPath(root        , reference        , routePattern        )         {
   assert(isListFile(reference) && !isAbsolute(reference), `${routePattern}: policies.agents list ${JSON.stringify(reference)} must be a project-relative path ending in .json`);

package/dist/agents-guide.js

@@ -0,0 +1,113 @@
+import { getCapabilities } from './capabilities.js';
+                                                        
+import { registry } from './policies.js';
+import { generatedPaths } from './site.js';
+import { assert } from './errors.js';
+
+/** Where the packaged agent skill lives, relative to the installed @jimhoyd/urlcode package. */
+export const skillPath = 'skills/urlcode/SKILL.md';
+/** The MCP registration file `urlcode init` writes beside the project (Claude Code and Codex read this shape). */
+export const mcpConfigFile = '.mcp.json';
+/**
+ * Renders `.mcp.json` registering the read-only `urlcode mcp` server for the project at `project`, relative
+ * to the file. `--allow-authoring` is deliberately absent: the operator adds it by hand when they want it.
+ */
+export function renderMcpConfig(project = '.')         {
+  assert(/^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(project) && !project.split('/').includes('..'), 'MCP project path must be a relative path without ..');
+  return JSON.stringify({ mcpServers: { urlcode: { command: 'urlcode', args: ['mcp', '--project', project] } } }, null, 2) + '\n';
+}
+const handlerNames                            = ['redirect','respond','page','static','download','function','proxy','conditional','extension'];
+
+/**
+ * The application-level AGENTS.md written by `urlcode init`. Built from the
+ * installed runtime's capability catalog, so it names only the handlers,
+ * policies and site keys this version implements. Under 80 lines by design.
+ */
+export function renderAgentsGuide({ routes }                    )         {
+  assert(Number.isInteger(routes) && routes >= 0 && routes <= 100000, 'Route count must be a non-negative integer');
+  const catalog = getCapabilities('self-hosted');
+  const native = new Set(catalog.capabilities.filter(row => row.targets['self-hosted']?.support === 'native').map(row => row.capability));
+  const handlers = handlerNames.filter(name => native.has(name));
+  const policies = Object.keys(registry).filter(name => native.has(`policies.${name}`                  ));
+  const site = Object.entries(generatedPaths).map(([key, path]) => `\`${key}\` (${path})`);
+  return `# Working on this project
+
+This project uses URLCode: URL behavior is declared in \`urlcode.yaml\`, and the
+installed \`@jimhoyd/urlcode\` runtime serves it. There is no framework code to
+write for routing, validation, middleware wiring, policies, static serving or
+authentication; the runtime provides them. Read this file before changing anything.
+
+## Before writing code
+
+1. Inspect \`urlcode.yaml\` first, then every file its \`includes\` list names,
+   the referenced functions, middleware and \`tests/requests.json\`. Preserve the
+   existing organization and every route you were not asked to change.
+2. Run \`urlcode capabilities\` to see what this runtime version implements and
+   which targets support it; \`urlcode capabilities --target NAME\` before
+   promising any provider deployment.
+3. Run \`urlcode recipes list\` and \`urlcode recipes show NAME\` before writing a
+   route from scratch. If a recipe covers the need, add it with
+   \`urlcode recipes add NAME --out DIR\` and adapt the copy.
+4. Use URLCode's highest-level declarative features whenever possible. Generate custom code only when the framework cannot express the requirement. Check supported extensions and recipes first; explain any capability gap.
+
+## Ask the runtime through MCP first
+
+When present, \`${mcpConfigFile}\` registers the read-only \`urlcode mcp\` server. When it is
+available, prefer its tools over reading documents: \`get_context\`,
+\`get_capability\`, \`get_schema\`, \`search_recipes\`, \`explain\`, \`get_manifest\`.
+The CLI equivalents are the fallback: \`urlcode context\`, \`urlcode capabilities NAME\`,
+\`urlcode schema PATH\`, \`urlcode recipes search TEXT\`, \`urlcode explain PATH\`,
+\`urlcode manifest\`. \`--allow-authoring\` is an operator opt-in; never add it yourself.
+
+## What the runtime provides (this version)
+
+- Handlers, exactly one per route: ${handlers.map(name => `\`${name}\``).join(', ')}.
+- Ordered \`middleware\` around any handler, declared in YAML, trusted by default.
+- Validated inputs: \`parameters\`, \`request.body\` and \`methods\` on the route;
+  functions receive validated \`args\`, never raw user input.
+- Policies, host-enforced and off by default: ${policies.map(name => `\`${name}\``).join(', ')}.
+- Site conventions under \`site\`, each generating one native route: ${site.join(', ')}.
+- Bindings: named \`env\` and \`secrets\` references resolved by the operator, never values in YAML.
+
+Never recreate any of these in a function; a missing one is a report, not an
+invitation to reimplement it.
+
+## Functions and middleware are trusted by default; sandbox is opt-in
+
+A route's \`function\`/\`middleware\` code runs trusted, in-process, with full
+Node/filesystem/\`fetch\` access, receiving only the declared/granted \`args\`
+and \`env\`/\`secrets\`. Add \`sandbox: true\` when code warrants isolation
+(untrusted input, an unreviewed contribution, an especially sensitive
+secret): that route then gets a text/JSON subset only, no Node/filesystem/
+outside imports — use \`proxy\`/a binding instead, and say why in \`description\`.
+
+## Checks that count as evidence
+
+\`\`\`sh
+urlcode validate --local
+urlcode test
+urlcode audit --expect-routes ${routes}
+\`\`\`
+
+Run all three after every change, updating the route count deliberately and
+adding \`tests/requests.json\` fixtures for every new route (positive/negative,
+every active method, HEAD). No global install: use \`node /path/to/urlcode/src/cli.ts\`.
+
+## Rules
+
+- Report unsupported requirements instead of inventing fields. The schema is
+  exact; a field the validator rejects does not exist. Say what is missing.
+- Never create or approve operator grants. Request a named binding in YAML and
+  stop; the operator grants it outside this project, pinned to the revision.
+- Secrets stay out of the project: no keys, tokens or credentials in YAML,
+  functions, fixtures, \`.env\` files that are not ignored, or commit messages.
+- Protect a route with \`auth: true\`/\`auth: { role: admin }\` where an \`auth\`
+  extension is declared; \`cache\` likewise expands to \`policies.cache\`.
+- Validation, tests and the audit are the evidence. Local checks are not a
+  deployment, a soak test or a security review; do not claim otherwise.
+
+The installed package ships an agent skill with the same loop at
+\`${skillPath}\` inside \`@jimhoyd/urlcode\` (for example
+\`node_modules/@jimhoyd/urlcode/${skillPath}\`).
+`;
+}