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

package/ROADMAP.md

@@ -1,376 +1,61 @@
-# 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](docs/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](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
-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](docs/PERFORMANCE.md)). Contributors need Node
-22.18+ to run the source directly; installed packages still run on 22.13+.
-See [TypeScript](docs/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](docs/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](docs/POLICIES.md) and [plugins](docs/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](docs/VERCEL.md) and
-[AWS](docs/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](docs/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](docs/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](docs/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](docs/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](docs/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 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
-
-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](docs/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](docs/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](docs/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](docs/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](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. 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
-
-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](docs/SPECIFICATION.md)
-and [operations guide](docs/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](docs/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.
+# Roadmap
+
+URLCode lets people and agents describe URL behavior in YAML and write application
+code only where the framework cannot express it. The free Apache-2.0 runtime
+stays useful on its own. [Project direction](docs/PROJECT-DIRECTION.md) owns the
+principles; [the specification](docs/SPECIFICATION.md) owns implemented behavior.
+
+## What works now
+
+The source at `db375bf` provides declarative routing, responses, assets, policies,
+conditions, proxy/signals, trusted Node functions and middleware, and opt-in
+`sandbox: true` isolation. Target support differs: use `urlcode capabilities`
+before promising a deployment. Stored short links have no supported package.
+
+Auth, admin, UI and middleware are separate optional packages. Auth/admin already
+render through the shared UI kit when configured. Core includes scaffolding,
+searchable recipes/examples, compact context, schema queries, a semantic manifest,
+and MCP inspection with separately enabled authoring. These are implemented,
+not future phases. See [the framework](docs/FRAMEWORK.md).
+
+## Next work
+
+Monorepo work is starting now. Move middleware in as a separate package before
+folding it into core; coordinate the guidance cleanup with that migration.
+
+1. **Make the existing product coherent.** Keep docs, examples, generated LLM
+   resources, installed skills and the standalone template consistent with their
+   runtime version. Resolve the [open decisions](docs/OPEN-DECISIONS.md).
+   [Issue 168](https://github.com/jimhoyd-com/urlcode/issues/168) tracks checking
+   schema-invalid documentation examples beyond the existing prose checks.
+   [Issue 174](https://github.com/jimhoyd-com/urlcode/issues/174) retains the
+   extension-schema retrieval proposal.
+2. **Measure the agent experience.** The benchmark harness and authoring evals
+   exist, but the committed baseline is a stub, not a real-model measurement.
+   [Issue 173](https://github.com/jimhoyd-com/urlcode/issues/173) tracks the
+   measurement. Run the existing tasks, retain the raw results and use observed friction to
+   choose improvements. See [the benchmark](benchmarks/agent/README.md) and
+   [the broader experiment proposal](docs/SPIKE-AI-FRAMEWORK-BENCHMARK.md).
+3. **Close release evidence gaps.** Browser/device coverage, accessibility,
+   independent security review, deployed recovery/soak tests and real provider
+   verification remain distinct from source implementation and local tests.
+   [Issue 58](https://github.com/jimhoyd-com/urlcode/issues/58) and
+   [release readiness](docs/RELEASE-READINESS.md) retain those gates. Live
+   Google/Apple/SES checks remain explicitly deferred.
+4. **After the monorepo move, consolidate middleware into core.** Move the
+   existing middleware package first, preserving behavior.
+   [issue 172](https://github.com/jimhoyd-com/urlcode/issues/172) tracks the later consolidation
+   and consumer migration; package retirement is not part of the initial move. Static targets continue rejecting
+   request-time middleware.
+5. **Choose expansion from evidence.** Collections, a business application suite,
+   and per-route Lambda compilation are proposals,
+   not available features. Decide scope before implementing them.
+
+## Records and ownership
+
+Track actionable defects and feature gaps in the owning repository's issues.
+This page explains sequence; package contracts explain behavior; dated evidence
+states what was actually tested. Completed and superseded plans live in the
+[archive](docs/archive/README.md), including the previous release chronology
+and detailed phase plan. Archiving an implementation plan does not close its
+remaining operational acceptance gates.

package/dist/BUILD-MANIFEST.json

@@ -3,18 +3,18 @@
   "files": {
     "dist/adapters.js": "a7153ec52f2ed7e0cdd8ed7d433504815f402ec53b2b1c3d38d0cf0e2fcf6509",
     "dist/agent-lists.js": "35ab484198897501d011cb6cc00b5a6787192e19df29c97646e8c118fcc19eef",
-    "dist/agents-guide.js": "a76e9818ec995a349085a53e8badd3ef49734275557b50bc7dcbe995ce3d0e9f",
+    "dist/agents-guide.js": "0b19909aee3f8a1039c34c43ff58116ec1bc3f1875e3dbc34b3b01655273201c",
     "dist/assets.js": "0833b093d2fe457ce68281110dc07d47914992753607741c13b339d92c76cf5c",
     "dist/authoring-files.js": "ad32814f9ae9c549c6247396f982aa700d13a293cc0a589609eccc68f8965550",
     "dist/authoring.js": "ec5240e8686c124f4601229b45f89ce112d9eeb9d35e3059fe55e93056c45209",
     "dist/aws.js": "7d8e3a97b4f6dbefbd68da058f05192469d1efcaed5458b284863ebe462e060e",
     "dist/build-cloudflare.js": "af4f49ad45287d7c4105bb84b1592b5b8e76c930f7159505338298f7c5fd5651",
-    "dist/build-static.js": "a2d2fcef3099805392da9140096d9843226bfb582dc046acf9a77f37b8a0d528",
+    "dist/build-static.js": "fe01ef4fcc66d83d8be7a787538b55974e84fd3d7c89e26f0a2f1a152762d565",
     "dist/bulk.js": "aac88d422bd9a7a341a421fb4e29ff5580b28d39250b7f1f5315ba20ae92da8a",
     "dist/capabilities.js": "28dba05b3851b8b12b3c1b809af87b732f84d601c737afe9225abe429886e691",
     "dist/capability-query.js": "ba148b27c6a60f8c895f13f26468b16c18ae0a5cddea26b602965c8efbba90ae",
     "dist/catalog.js": "ab1c01c9296cc277d2bd4fd682aeb053656a7d9f91c61974f4b78feea0211de8",
-    "dist/cli.js": "f6097c246c6b9006df58e3463648013ec8837ab3296a8c294809313503be167a",
+    "dist/cli.js": "ff3e583bd43044bdc06122e33c6137f400f677967ebff1ab49900b517682531c",
     "dist/client-address.js": "9d0d01466aab23124330605c5a0e0f981f87c897858acfad909f546a63df165b",
     "dist/cloudflare.js": "17b43b0a6b6a0ef8a893415c989e4ae3976d97cc966adbf897b785f9adc472e3",
     "dist/compliance-rules/baseline.js": "6296dea6bcb9f9bb80ed6ed5ab2f456e7f74e6de2be5d2d98ca8c983fb4df3ab",
@@ -30,9 +30,9 @@
     "dist/egress.js": "2ae29fe2cb4590fd2f715abe6817db47fed2f50dd31f37946ecf42eafbb0dd9e",
     "dist/errors.js": "a908e66496afebbdd632a8c159a6e14d23f8f38798a0b4342ca122f2511c6cde",
     "dist/examples.js": "89ae2b764a688fe52acfb9b94d3d262d7742401ebd0ef10c9ebfc76edfa5631c",
-    "dist/explain-cli.js": "dd342b21a96fc97a11488ac3528793ba0f5d4744b74a1d99085e142c4737b69a",
-    "dist/explain.js": "9450d2699cbe65e5c078c443ba7a6cba95c748e75d455e05264083b3c93c92a2",
-    "dist/extensions.js": "fed2b394466a7d406f9edeaedb71d9da81e50e3150eb7d01f2e7659104afeac7",
+    "dist/explain-cli.js": "f0f8f3b5046430d03c6abb629b38651c9c734b03456040735ce9d7e582b2bcd5",
+    "dist/explain.js": "dff1ed9a1bd818906ea867f4fb6d4601397943f9bdc4fceccf1809a365f95168",
+    "dist/extensions.js": "0506ec6289fa0582399d8c6d27727ffeb629bd442264248c921c63cc5b46ff01",
     "dist/function-sources.js": "16fad4abc81c7ee07b6cbcef2d23a9fc50e97a17cb4dde1db53469bbb555c96f",
     "dist/function-worker.js": "35771790ada4e1b36d447d4967a5e6cf0b543f32944e4c904f5fbf8998e824a5",
     "dist/functions.js": "0f09d1bd27eb655ceb5900a4a5e2b760d2028b02cb637a6a89a4eb5940828008",
@@ -45,10 +45,10 @@
     "dist/interchange-cli.js": "35bd70ba8077af5c3e39404ff0e5d28707632090a59a90645141252449fd3f04",
     "dist/interchange.js": "26789420af33344d9a08c00fe6b2708aa71994224df527b3075295be2151611e",
     "dist/logging.js": "8ec57fea26983aa071b05fe15d680d6550b03488101163ed9666da674118cf31",
-    "dist/manifest.js": "977f0f1cbe4466f7fbd9f2a0745e016cb9ebae640bc264fba04b4d02f4dbaca9",
+    "dist/manifest.js": "aa450ff88d44b184ed1ad3331d1f81005a844a9f971e9e12dfa039952839bc75",
     "dist/match.js": "53ebcc2cda529a8d07fb83f8cb69a1446036ffc1641af3c4bd45a55851bded28",
-    "dist/mcp-authoring.js": "5030f52ef9c7ebc7b97305fcce687eb0a0d6164e34fda87f8278135a1e6f3d65",
-    "dist/mcp.js": "e2d70f63481dc40aae60f7c27128e6a09ec370b69fd68aee8890bcc990f4f304",
+    "dist/mcp-authoring.js": "4987b0ba08999309e07aea1b8bb31f4600cec22d79998e6982e56f765070587a",
+    "dist/mcp.js": "fa44f5f9e0bc4ca9790d1d1eb461147673c1539cf1704a4daae9bad30e4120eb",
     "dist/observability.js": "f4b1ab496f051fe3ef2ed36b2b2e469c63a8940700e2df852e6ff2d9cccdd5ae",
     "dist/operator-host.js": "e3dac9d43a83beb775202b4ab9eeeba7ac63cebfc5dcc669be38d825be587bd0",
     "dist/plugins.js": "a61aa933cd9e1b41020b86fae78aa3a7f45f5313124aa11b50cb57898722385e",
@@ -57,15 +57,15 @@
     "dist/policies/compression.js": "800f3ae3b1a4c1fe58c3d9908364ea9d78f655ff50c7f7589f584378e7f194b0",
     "dist/policies/security.js": "2b3bfdf82140156fea4b162adc28ee43ccd85c402fb200680dbb8d8706417420",
     "dist/policies/throttle.js": "bbb0cb1c24cf70d0a1ac32fc0618efb6c44e5b5d42564842f9c585ff7e501603",
-    "dist/policies.js": "23fa019b7bf1cdedcc5f7772d2f157e4b381a554bce9e84594c2be4a0f8f76b8",
+    "dist/policies.js": "3750a7032ec7326aa544f4808683ad9eb91d4f2c5afe79904420cd8a355710a9",
     "dist/policy.js": "33c527008fafe4af18243ba668d069517c20659150f9f1d1a5a1d076e8724f89",
-    "dist/prerender.js": "0386ea2411e00b9563b5349133f1d723947b01f837fa92d4c61a699c9cfb5cdb",
+    "dist/prerender.js": "6210999e848ab86c87f265943960ef63716896da7a40e248221a6a30425c56b8",
     "dist/project-tests.js": "445eaa139d2f1a2534369cfdeef081ef518de03218a467e7c5c2059caf840270",
     "dist/provider-verification.js": "ffcf9f05e8cb5f71ea46a97e279e8a613fdfdf9435ab02bd57af11e2680a9107",
     "dist/proxy.js": "34107e59ac0dbbea090efa3cf5badf3226c5302ba25e8f8ff9b2b5596ed80e50",
-    "dist/readiness.js": "6ce69a005d7c45cf0ef97fa5eaba34279d43ebf28124eca18359d9db4f599808",
+    "dist/readiness.js": "90b54bc0cf60dd155d05789a1aad767bd67483d5fa6064ae8b1143f8cf9e06b2",
     "dist/recipes.js": "11853f23e63c3c65c5bed03a278cde0349d28c9fa23266c9907a2df318bb5fc3",
-    "dist/route-diff.js": "eebac076a886ddfb2bf5b97ea09d81f888e7bb0063d482eddb8e5fef9acea107",
+    "dist/route-diff.js": "8d71d50d332ffaaed588656bd32aa36763260d1ad87bb62d7ea1c8fb23383969",
     "dist/router.js": "cf831025d5ed6778d1d6a0e541177799794e76766c82084ded81d3e87317ca1e",
     "dist/runtime.js": "0470dcab0774d2da3336e9ce76a4853757bf96081e52bd741f6b44c1bdd4161f",
     "dist/sandbox.js": "c88c5aa5dd95b4f55f1ba62da7969ad66dbd97c30f72e5b5f2817a2098ac1c65",
@@ -76,8 +76,8 @@
     "dist/site.js": "c40a06a6f9e2d6d3bea94727783c115fed4309bb0190787f58434eed64cbde84",
     "dist/tooling.js": "7409db98422325cd4181d073d645ea57debca0e54cb151123474b85f4d4ed7dc",
     "dist/trusted-functions.js": "befd256848be786f97e372c6af0e05ac08a0c93baed38bf2470ea49bc00dd3e4",
-    "dist/types.js": "a1213d033b6a347c63e94685ab9056d8cd7a301d9c83150142afe0f3ab2c6536",
-    "dist/typescript-authoring.js": "27829098603029ab565174e540fb1d5ef68c1a923272b7186f64a362f5244872",
+    "dist/types.js": "2fe7664dbb5695ec72114197abde72de4031df9c3b211740eacefa68e9b21844",
+    "dist/typescript-authoring.js": "2e98498a15bdbb76f36fbee84afb7c42ca95bbf80a2e6dd4040147f3b1642a29",
     "dist/vercel.js": "a0da20c095d0c7fa8f579ed4dd5951e7a34191f8a72a57c5e782c9eab39f6f08",
     "dist/verify-deployment.js": "0c2e68f3cf258a364728c801411df5284343bc01b75a64fe275ff84e397e998b",
     "dist/scripts/operational-drills.js": "c26c406d28013cc554b25a5b6bf8baf4e71d5e67e50d866fae546f538a192317"

package/dist/agents-guide.js

@@ -74,12 +74,12 @@ 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\`.
+A route's \`function\`/\`middleware\` runs trusted, in-process, with full
+Node/filesystem/\`fetch\` access, given only declared \`args\`/\`env\`/\`secrets\`. Add
+\`sandbox: true\` when that code warrants isolation (unreviewed code, a sensitive
+secret, complex logic) — not merely for untrusted input, which both modes share.
+A \`sandbox: true\` route gets a text/JSON subset only: use \`proxy\`/a binding, and
+say why in \`sandboxReason\`.
 
 ## Checks that count as evidence
 

package/dist/build-static.js

@@ -61,6 +61,8 @@ export async function buildStatic(project        , { out = 'dist/static', origin
     assert(route.enabled !== false, `${route.pattern}: static hosting has no server to answer a disabled route with 404; remove the route instead of disabling it`);
     assert(route.expiresAt === undefined, `${route.pattern}: static hosting has no server to answer an expired route with 410; remove the route when it expires`);
     assert(route.methods.every(method => defaultMethods.has(method)), `${route.pattern}: static hosting only ever answers GET/HEAD; this target refuses declared methods ${route.methods.join(', ')}`);
+    assert(defaultMethods.size === route.methods.length && [...defaultMethods].every(method => route.methods.includes(method)), `${route.pattern}: static hosting cannot preserve a GET-only or HEAD-only method restriction; declare both GET and HEAD`);
+    if (route.reply) assert(route.reply.status === 200, `${route.pattern}: static hosting serves response objects with status 200; declared status ${route.reply.status} cannot be preserved`);
     if (route.redirect) {
       assert(!route.names.length, `${route.pattern}: static hosting cannot redirect a path pattern; only an exact literal path can carry an S3 per-object redirect`);
       const query = route.redirect.query;

package/dist/cli.js

@@ -27,7 +27,7 @@ import { loadComplianceRules, profileNames as complianceProfiles } from './compl
 import { parseRouteSnapshot, diffRoutes, renderRouteDiff } from './route-diff.js';
 import { readFile } from 'node:fs/promises';
 
-const usage = `URLCode 0.4.0-alpha.2 — local/self-hosted runtime
+const usage = `URLCode 0.4.0-alpha.3 — local/self-hosted runtime
   urlcode init <directory> [--with auth,admin]  # --with: layered site from installed @jimhoyd/urlcode-<name> packages
   urlcode scaffold [--project directory] [--dry-run]
   urlcode validate [--project directory] [--local] [--origin https://links.example]  # origin: absolute URLs in site.* files
@@ -74,7 +74,7 @@ const usage = `URLCode 0.4.0-alpha.2 — local/self-hosted runtime
     # compact facts for an authoring agent from the compiled project; --stats compares estimated tokens with the docs
   urlcode doctor
   serve/dev/validate/test/routes/audit/benchmark/explain/context/extensions/mcp: --host-file /absolute/operator/host.mjs (trusted code outside project)
-Dev loads .env.local and watches; serve does neither. Functions run in WASM isolation; external bindings require --policy outside the project.
+Dev loads .env.local and watches; serve does neither. Functions run trusted and in-process by default; a route declaring sandbox: true runs in WASM isolation. External bindings require --policy outside the project.
 `;
 const print = (value         )          => process.stdout.write(typeof value === 'string' ? value : JSON.stringify(value) + '\n');
 const options = {
@@ -286,7 +286,7 @@ try {
           print(result); if (result.failed) process.exitCode = 1; break;
         }
         case 'doctor':
-          print({ node:process.version, platform:process.platform, architecture:process.arch, runtime:'node-process', functionSandbox:'quickjs-wasm', network:false, filesystem:false, guestNetwork:false, hostEgress:'revision-pinned-origin-grants', tooling:['recipes','examples','bulk-import','build-typescript','mcp','verify-provider'], providers:[], capabilityTargets:getCapabilities().targets, policies:Object.keys(policyRegistry), license:'Apache-2.0' }); break;
+          print({ node:process.version, platform:process.platform, architecture:process.arch, runtime:'node-process', functionDefault:'trusted-in-process', sandboxEngine:'quickjs-wasm', trustedFilesystem:true, trustedNetwork:true, sandboxedFilesystem:false, sandboxedNetwork:false, hostEgress:'revision-pinned-origin-grants', tooling:['recipes','examples','bulk-import','build-typescript','mcp','verify-provider'], providers:[], capabilityTargets:getCapabilities().targets, policies:Object.keys(policyRegistry), license:'Apache-2.0' }); break;
         case 'dev': case 'serve': {
           const port = Number(values.port);
           if (!/^\d+$/.test(values.port) || !Number.isInteger(port) || port < 0 || port > 65535) throw new ConfigError('Invalid port');

package/dist/explain-cli.js

@@ -12,7 +12,7 @@ const targetsOf=(target                 )                   =>target===undefined
 function summary(explanation                 ,targets                   )        {
   const handler=explanation.handler,detail=handler.kind==='function'?`${handler.source          }#${handler.export          }`:handler.kind==='redirect'?`${handler.status          } ${handler.url          }`:handler.kind==='extension'?handler.name          :handler.kind==='page'||handler.kind==='download'?handler.file          :handler.kind==='static'?handler.directory          :handler.kind==='proxy'?handler.url          :handler.kind==='respond'?String(handler.status):'';
   const support=targets.map(target=>explanation.targets[target].compatible?target:`${target}:refused`).join(',');
-  return [explanation.path,explanation.methods.join(','),`${handler.kind}${detail?` ${detail}`:''}`,explanation.state,String(explanation.middleware.length),explanation.policies.names.join(',')||'-',explanation.cache.outcome,support].join('\t');
+  return [explanation.path,explanation.methods.join(','),`${handler.kind}${detail?` ${detail}`:''}`,explanation.state,explanation.sandbox?'sandboxed':'trusted',String(explanation.middleware.length),explanation.policies.names.join(',')||'-',explanation.cache.outcome,support].join('\t');
 }
 function detail(explanation                 ,targets                   )        {
   const lines         =[`route: ${explanation.path}`];
@@ -20,6 +20,8 @@ function detail(explanation                 ,targets                   )
   if(explanation.generated)lines.push(`generated: site.${explanation.generated}`);
   lines.push(`state: ${explanation.state}${explanation.expires?` (expires ${explanation.expires})`:''}`,`methods: ${explanation.methods.join(', ')}`,`handler: ${JSON.stringify(explanation.handler)}`);
   lines.push(`middleware: ${explanation.middleware.length?explanation.middleware.map(item=>`${item.source}#${item.export}`).join(' -> '):'none'}`);
+  // Route-level, so it is printed for a native handler with middleware too.
+  lines.push(`execution: ${explanation.sandbox?'sandboxed (QuickJS)':'trusted (in-process)'}${explanation.sandboxReason?`; ${explanation.sandboxReason}`:''}`);
   lines.push(`inputs: ${explanation.inputs.parameters.length?explanation.inputs.parameters.map(p=>`${p.in}:${p.name}${p.required?'':'?'}`).join(', '):'none'}${explanation.inputs.body?`; body ${JSON.stringify(explanation.inputs.body)}`:''}`);
   lines.push(`policies: ${explanation.policies.names.length?explanation.policies.names.join(', '):'none'}`);
   for(const [name,entry] of Object.entries(explanation.policies.inventory))lines.push(`  ${name}: ${JSON.stringify(entry)}`);
@@ -52,7 +54,7 @@ export async function runExplainCommand(command                     ,route
   if(route===undefined){
     const report=await explainProject(options.project,base);
     if(options.json){print(report);return 0;}
-    print(table([['route','methods','handler','state','mw','policies','cache','targets'],...report.routes.map(item=>summary(item,targets).split('\t'))]));return 0;
+    print(table([['route','methods','handler','state','execution','mw','policies','cache','targets'],...report.routes.map(item=>summary(item,targets).split('\t'))]));return 0;
   }
   if(!route.startsWith('/'))throw new ConfigError('Provide an absolute route path such as /docs');
   const explanation=await explainRoute(options.project,route,base);