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

package/llms.txt

@@ -1,20 +1,31 @@
 # URLCode
 
 > A portable runtime for programmable URL behavior, and the framework that grows
-> from it: routes in YAML, isolated functions, live links, then accounts and
-> administration as operator-installed extensions. Stable project format
-> `version: "1"`. Core is Apache-2.0; `0.4.0-alpha.1` is the current alpha on top of
+> from it: routes in YAML, functions and middleware, then accounts, administration and
+> stored links as operator-installed extensions. Stable project format
+> `version: "1"`. Core is Apache-2.0; this revision is `0.4.0-alpha.2`, which makes
+> `function`/`middleware` routes trusted by default with `sandbox: true` as the
+> per-route opt-in; `0.4.0-alpha.1` is the newest alpha published to npm, on top of
 > the `0.3.0` release. The auth, admin and ui extension packages are on npm as
-> `0.1.0-alpha.1`, source-complete, review pending.
+> `0.1.0-alpha.x`, source-complete, review pending.
 
 Use the schema and docs from the runtime revision you run. Do not assume Node
-or fetch in functions, regex routes, database access, global middleware, YAML
-interpolation, or packages named in YAML. Secrets need external revision-pinned
+or fetch inside a `sandbox: true` function, regex routes, database access,
+global middleware, YAML interpolation, or packages named in YAML. Secrets need external revision-pinned
 grants. Unsupported features fail with the route named; nothing degrades silently.
 
 Agents that explicitly want the complete consolidated reference in one fetch should read
 [llms-full.txt](llms-full.txt), generated from the documents below (about 50k tokens, estimated).
 
+## Declarative-first default
+
+> Use URLCode's highest-level declarative features whenever possible. Generate custom code only when the framework cannot express the requirement.
+
+Check the installed version's primitives, YAML configuration, policies, supported
+extensions and recipes/templates before writing a custom function or middleware.
+Keep necessary custom code focused and report the capability gap; never invent
+fields or bypass target limits or operator grants. See [the design principle](docs/PROJECT-DIRECTION.md#design-principle-declarative-first).
+
 ## Authoring
 - [AI authoring contract](docs/AI-AUTHORING.md): workflow, capability matrix, checks.
 - [Authoring skill](.claude/skills/urlcode-authoring/SKILL.md): loadable authoring skill shipped with this revision; see [distribution](docs/AI-AUTHORING.md#agent-skills).
@@ -24,12 +35,11 @@ Agents that explicitly want the complete consolidated reference in one fetch sho
 - [Field reference](docs/YAML-REFERENCE.md): generated exhaustive field inventory.
 - [Semantics](docs/SPECIFICATION.md): validation, defaults and sandbox API.
 - [Runnable cookbook](examples/cookbook/README.md): 25 routes with HTTP fixtures.
-- [Dynamic links](docs/DYNAMIC-LINKS.md): optional SQLite, live mutations, management API and limits.
 - [Route matching](docs/ROUTING.md): precedence, non-greedy parameters, updates.
 - [Middleware](docs/MIDDLEWARE.md): next(), state, ordering and native body limits.
 - [Policies](docs/POLICIES.md): optional host-enforced `policies`/`profiles` keys, all off by default: `throttle`, `agents`, `security`, `compression`, `cache`; merge rules and per-target support.
 - [Plugins](docs/PLUGINS.md): host hook API operators pass in code; never named in YAML.
-- [TypeScript](docs/TYPESCRIPT.md): the package ships declarations for every export (`urlcode`, `@jimhoyd/urlcode/plugins`, `@jimhoyd/urlcode/policies`, `@jimhoyd/urlcode/observability`, `@jimhoyd/urlcode/compliance`, `@jimhoyd/urlcode/prerender`, `@jimhoyd/urlcode/aws`, `@jimhoyd/urlcode/vercel`, `@jimhoyd/urlcode/cloudflare`); the runtime source is TypeScript, `dist/` is its stripped JavaScript.
+- [TypeScript](docs/TYPESCRIPT.md): the package ships declarations for every export (`urlcode`, `@jimhoyd/urlcode/plugins`, `@jimhoyd/urlcode/policies`, `@jimhoyd/urlcode/observability`, `@jimhoyd/urlcode/compliance`, `@jimhoyd/urlcode/prerender`, `@jimhoyd/urlcode/sandbox`, `@jimhoyd/urlcode/aws`, `@jimhoyd/urlcode/vercel`, `@jimhoyd/urlcode/cloudflare`); the runtime source is TypeScript, `dist/` is its stripped JavaScript.
 - [HTTP](docs/HTTP.md): methods, request bodies and response headers.
 - [Assets](docs/ASSETS.md): pages, MIME, downloads, cache and ranges.
 - [Site conventions](docs/SITE.md): optional top-level `site` key, all off by default: `robots`, `sitemap`, `favicon`, `securityTxt`, `llms` generate native routes; declared routes win; absolute URLs need `--origin`.
@@ -46,10 +56,9 @@ Agents that explicitly want the complete consolidated reference in one fetch sho
 ## Routes and handlers
 - [Routing](docs/ROUTING.md): exact and `{param}` paths, precedence, `/*` only on static and extension mounts.
 - [HTTP](docs/HTTP.md): methods, validated inputs, bodies, response headers, cookies.
-- [Function security](docs/FUNCTION-SECURITY.md): QuickJS/WASM sandbox, Request/Response subset, operator grants.
+- [Function security](docs/FUNCTION-SECURITY.md): trusted and unsandboxed by default, `sandbox: true` QuickJS/WASM opt-in, Request/Response subset, operator grants.
 - [Middleware](docs/MIDDLEWARE.md) and [examples](docs/MIDDLEWARE-EXAMPLES.md): `next()`, state, ordering; also `urlcode recipes add middleware`.
 - [Assets](docs/ASSETS.md): pages, static, downloads, MIME, ranges. [Prerender](docs/PRERENDER.md): render once, no request-time code.
-- [Dynamic links](docs/DYNAMIC-LINKS.md): `link` handler, SQLite store, CLI, private management API.
 - [Conditions](docs/CONDITIONS.md): exact predicates, disjoint redirect/respond cases, no-store.
 - [Egress](docs/EGRESS.md): bounded HTTPS proxy and best-effort signals behind operator grants; self-hosted only.
 - [Policies](docs/POLICIES.md): `throttle`, `agents`, `security`, `compression`, `cache`; all off unless declared. [Site](docs/SITE.md): robots, sitemap, favicon, security.txt, llms.txt.
@@ -57,19 +66,21 @@ Agents that explicitly want the complete consolidated reference in one fetch sho
 - [Interchange](docs/INTERCHANGE.md), [bulk import](docs/BULK.md), [recipes](docs/RECIPES.md) (`urlcode recipes search`, `examples search`), [TypeScript guests](docs/TYPESCRIPT-AUTHORING.md).
 
 ## Extensions (accounts, administration, presentation)
-- [Extensions](docs/EXTENSIONS.md): `extensions.<name>` blocks, `extension` mounts, `policies.extensions`, the operator host file, `@jimhoyd/urlcode/extensions`.
+- [Extensions](docs/EXTENSIONS.md): `extensions.<name>` blocks, `extension` mounts, `policies.extensions`, the operator host file, `@jimhoyd/urlcode/extensions`. Project-level lifecycle hooks run trusted via plain `import()`, or sandboxed via `@jimhoyd/urlcode/sandbox`'s `SandboxPool`.
 - [urlcode-auth](https://github.com/jimhoyd-com/urlcode-auth): npm: @jimhoyd/urlcode-auth; accounts, sessions, MFA, roles, account page; its own llms.txt.
 - [urlcode-admin](https://github.com/jimhoyd-com/urlcode-admin): npm: @jimhoyd/urlcode-admin; users, sessions, roles, audit, cases; its own llms.txt.
 - [urlcode-ui](https://github.com/jimhoyd-com/urlcode-ui): npm: @jimhoyd/urlcode-ui; escaped templates, shadcn/ui partials, themes, translations; its own llms.txt.
+- urlcode-dynamic-link (planned, not yet published): stored short links move here as a mount-based extension; core no longer has a native `link` handler.
 - [Plugins](docs/PLUGINS.md): host hook API in operator code, never named in YAML.
 
 ## Tooling and API
 - [Tooling SDK and MCP](docs/TOOLING.md): `urlcode mcp`, read-only inspection, validation, conversion previews.
-- [TypeScript](docs/TYPESCRIPT.md): declarations for `@jimhoyd/urlcode` and its `/plugins`, `/policies`, `/observability`, `/compliance`, `/prerender`, `/extensions`, `/aws`, `/vercel`, `/cloudflare` entries.
+- [TypeScript](docs/TYPESCRIPT.md): declarations for `@jimhoyd/urlcode` and its `/plugins`, `/policies`, `/observability`, `/compliance`, `/prerender`, `/extensions`, `/sandbox`, `/aws`, `/vercel`, `/cloudflare` entries.
 - [Capabilities](docs/CAPABILITIES.md): per-target support; `urlcode capabilities --target NAME`.
 
 ## Operations
 - [Operations](docs/OPERATIONS.md), [install](docs/INSTALL.md), [deployment checks](docs/DEPLOYMENT-CHECKS.md), [CI action](docs/CI.md).
 - [Readiness](docs/READINESS.md), [capacity](docs/CAPACITY.md), [performance](docs/PERFORMANCE.md), [resilience](docs/RESILIENCE.md), [observability](docs/OBSERVABILITY.md).
 - [Vercel](docs/VERCEL.md), [AWS](docs/AWS.md), [Cloudflare](docs/CLOUDFLARE.md): adapters with local conformance tests; no provider deployment verified yet.
+- [Static hosting](docs/STATIC.md): `urlcode build --target static` compiles redirects/pages/static/downloads to S3 + CloudFront objects and redirect metadata; no server, so function/middleware/extension/proxy/signals/conditions/parameters/bindings/policies are all refused; GitHub Pages is explicitly out of scope.
 - [Release readiness](docs/RELEASE-READINESS.md), [roadmap](ROADMAP.md): what is proven, what is planned.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jimhoyd/urlcode",
-  "version": "0.4.0-alpha.1",
+  "version": "0.4.0-alpha.2",
   "description": "Portable runtime for programmable URL behavior",
   "type": "module",
   "license": "Apache-2.0",
@@ -69,6 +69,11 @@
       "development": "./src/extensions.ts",
       "default": "./dist/extensions.js"
     },
+    "./sandbox": {
+      "types": "./dist/types/sandbox.d.ts",
+      "development": "./src/sandbox.ts",
+      "default": "./dist/sandbox.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -96,7 +101,7 @@
     "typecheck": "tsc -p tsconfig.json",
     "test": "node --conditions=development --test test/*.test.ts",
     "lint": "eslint .",
-    "check": "node scripts/check.ts && node scripts/generate-yaml-reference.ts --check && node scripts/build-llms-full.ts --check && node scripts/build-cookbook-index.ts --check && node scripts/generate-claude-plugin.ts --check",
+    "check": "node scripts/check.ts && node scripts/check-trust-model-prose.ts && node scripts/check-guidance-claims.ts && node scripts/generate-yaml-reference.ts --check && node scripts/build-llms-full.ts --check && node scripts/build-cookbook-index.ts --check && node scripts/generate-claude-plugin.ts --check",
     "verify": "npm run lint && npm run typecheck && npm run check && npm run build && npm test",
     "benchmark": "node benchmarks/routing.ts",
     "test:package": "npm run build && node scripts/package-smoke.ts",
@@ -113,7 +118,9 @@
     "docs:plugin": "node scripts/generate-claude-plugin.ts",
     "docs:llms": "node scripts/build-llms-full.ts",
     "docs:cookbook-index": "node scripts/build-cookbook-index.ts",
+    "check:downstream-skills": "node scripts/check-downstream-skill-drift.ts",
     "benchmark:bulk": "node benchmarks/bulk.ts",
+    "benchmark:sandbox-vs-trusted": "node benchmarks/sandbox-vs-trusted.ts",
     "benchmark:agent": "node benchmarks/agent/run.ts",
     "sync:agents": "node scripts/sync-agent-lists.ts"
   },
@@ -138,7 +145,7 @@
     "globals": "17.12.0",
     "typescript-eslint": "8.70.0"
   },
-  "homepage": "https://github.com/jimhoyd-com/urlcode-docs",
+  "homepage": "https://github.com/jimhoyd-com/urlcode#readme",
   "bugs": {
     "url": "https://github.com/jimhoyd-com/urlcode/issues"
   }

package/packaging/claude-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "urlcode",
   "description": "Authoring and operating URLCode projects: the implemented YAML contract, capability limits, deployment and verification commands for the pinned runtime revision.",
-  "version": "0.4.0-alpha.1",
+  "version": "0.4.0-alpha.2",
   "author": {
     "name": "jimhoyd-com",
     "url": "https://github.com/jimhoyd-com"

package/packaging/claude-plugin/skills/urlcode-authoring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: urlcode-authoring
-description: Author or modify a URLCode project — write and edit urlcode.yaml routes, function and middleware modules, pages, static assets, downloads and stored links, then validate and test them. Use whenever a urlcode.yaml file is present or referenced, when the user mentions URLCode, @jimhoyd/urlcode, urlcode routes/handlers/policies/site keys, or asks for redirects, short links or request functions in a URLCode project. Loads the implemented capability matrix so unsupported features are reported as gaps instead of invented.
+description: Author or modify a URLCode project — write and edit urlcode.yaml routes, function and middleware modules, pages, static assets and downloads, then validate and test them. Use whenever a urlcode.yaml file is present or referenced, when the user mentions URLCode, @jimhoyd/urlcode, urlcode routes/handlers/policies/site keys, or asks for redirects or request functions in a URLCode project. Loads the implemented capability matrix so unsupported features are reported as gaps instead of invented.
 ---
 
 # Authoring URLCode projects
@@ -11,6 +11,15 @@ validates. Features outside that contract do not silently degrade — they fail
 validation. So the cost of guessing is a broken project, and the whole job here
 is to author only what the pinned revision implements and then prove it.
 
+## Declarative-first default
+
+> Use URLCode's highest-level declarative features whenever possible. Generate custom code only when the framework cannot express the requirement.
+
+Check the installed version's primitives, YAML configuration, policies, supported
+extensions and recipes/templates before writing a custom function or middleware.
+Keep necessary custom code focused and report the capability gap; never invent
+fields or bypass target limits or operator grants. See `docs/PROJECT-DIRECTION.md` in the installed runtime.
+
 ## Read the contract before writing YAML
 
 Documentation, schema and runtime must come from the **same revision**. Read from
@@ -35,8 +44,9 @@ checkout you are working in — never from memory of another version.
   tests and the pinned runtime version. Preserve the user's organization,
   naming and unrelated routes.
 - Choose exactly one handler per route — `function`, `redirect`, `respond`,
-  `page`, `static`, `download` or `link` — plus optional ordered middleware.
-  Prefer a native handler when code is unnecessary.
+  `page`, `static`, `download`, `conditional`, `proxy` or an `extension` mount
+  — plus optional ordered middleware. Prefer a native handler when code is
+  unnecessary.
 - Declare each path placeholder as a required string. Paths match whole
   segments: no regex, no greedy captures, no wildcard handlers.
 - Bind typed inputs through `args` or context. There is no `${...}`
@@ -56,8 +66,14 @@ mistakes that recur:
 - No YAML anchors, aliases, template interpolation or remote includes.
 - No recursive includes or glob discovery; includes are explicit.
 - No regex, optional or greedy route segments, and no host-based routing.
-- The sandbox is text/JSON `Request`/`Response` only: **no** `fetch`, Node or
-  npm APIs, filesystem, WebSocket, streaming or crypto API.
+- `function`/`middleware` routes run trusted and unsandboxed by default: full
+  Node, npm, filesystem and `fetch` access, in-process, like any other project
+  code. `sandbox: true` opts a route into isolation — reach for it when that
+  route's own code warrants it (untrusted input, an unreviewed contribution, a
+  particularly sensitive secret), not reflexively on every route. A
+  `sandbox: true` route gets a text/JSON `Request`/`Response` sandbox only:
+  **no** `fetch`, Node or npm APIs, filesystem, WebSocket, streaming or crypto
+  API.
 - No global middleware, Express compatibility or automatic auth.
 - `policies` accepts only `throttle`, `agents`, `security`, `compression` and
   `cache`, every key off unless declared; `hardened` is the only built-in
@@ -68,9 +84,9 @@ mistakes that recur:
   only and off unless declared; a declared route at the same path wins. Its
   generated routes count toward `--expect-routes`, and `site.sitemap` needs
   `--origin` on every command that activates the project.
-- `dynamicLinks: true` belongs in the entry `urlcode.yaml` only, and only for
-  live `link` handlers — not for includes, and not for parameterized redirects
-  or functions.
+- There is no native `link` handler or `dynamicLinks` project flag. Stored
+  short links are moving to a future `urlcode-dynamic-link` extension package,
+  not yet published; report that as a gap, never invent a `link` field.
 - Infrastructure (proxy ranges, storage URLs, vendor rule identifiers) is an
   operator flag, never route YAML.
 

package/packaging/claude-plugin/skills/urlcode-operations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: urlcode-operations
-description: Deploy, verify, monitor and operate a URLCode project — process/container deployment, release readiness, verifying a live deployment against the project, capacity/audit/benchmark, observability, DDoS/overload resilience, and private management (grants, live-link credentials). Use when the user asks to deploy, check readiness, verify a running deployment, size/benchmark a project, monitor it, plan for overload, or manage live links/bindings. Reports operational limits and unimplemented capabilities as gaps instead of inventing mitigations.
+description: Deploy, verify, monitor and operate a URLCode project — process/container deployment, release readiness, verifying a live deployment against the project, capacity/audit/benchmark, observability, DDoS/overload resilience, and operator binding grants. Use when the user asks to deploy, check readiness, verify a running deployment, size/benchmark a project, monitor it, plan for overload, or manage bindings. Reports operational limits and unimplemented capabilities as gaps instead of inventing mitigations.
 ---
 
 # Operating a URLCode deployment
@@ -30,9 +30,7 @@ another version.
    overload and DDoS; what layer each defense belongs to.
 6. `docs/MONITORING.md` and `docs/OBSERVABILITY.md` — health/ready probes,
    logs, metrics format, what is and is not exported.
-7. `docs/MANAGEMENT-SECURITY.md` — the private management API: credential
-   policy shape, scope, loopback-only binding.
-8. `docs/POLICIES.md` and `docs/FUNCTION-SECURITY.md` — per-target policy
+7. `docs/POLICIES.md` and `docs/FUNCTION-SECURITY.md` — per-target policy
    support and the operator binding-grant process, needed whenever a
    deployment or verification step touches either.
 
@@ -71,8 +69,8 @@ urlcode verify-deployment --project ./my-links --target https://links.example \
 Run the actual commands and report actual results, never "should work" or
 "should be reachable". `verify-deployment` needs a real target; do not
 simulate its output. In a runtime checkout, substitute `node src/cli.ts` for
-`urlcode`. Pass `--policy`/`--link-store` where a snapshot needs bindings
-already reviewed by the operator.
+`urlcode`. Pass `--policy` where a snapshot needs bindings already reviewed
+by the operator.
 
 ## Hard limits — report these as gaps, never invent around them
 
@@ -84,12 +82,9 @@ already reviewed by the operator.
 - `verify-deployment` has no infrastructure access, uses no credential,
   follows no redirect and offers no `--insecure`. It cannot check anything a
   read-only HTTP probe cannot observe.
-- The private management API binds only `127.0.0.1`/`::1`; it is never meant
-  to be exposed through a public proxy or container port mapping, and browser
-  Origin requests are rejected regardless.
-- A management credentials policy is operator-owned, outside the application,
-  never in YAML or Git, at most 64 KiB, mode 600, at most 128 credentials with
-  explicit collection/action allowlists — no wildcards.
+- Core has no durable store and no private management API of its own; stored
+  short links are moving to a future `urlcode-dynamic-link` extension
+  package, not yet published.
 - Sandbox concurrency, worker slots and execution deadlines are shared across
   every programmable route in a snapshot; there is no per-route fairness or
   reserved capacity, and awaiting a guest timer still occupies a slot.
@@ -102,10 +97,9 @@ responsibility that covers it instead of inventing a flag.
 
 ## Boundaries
 
-- Never generate or approve an operator binding grant, or a management
-  credentials policy, on the user's behalf. Both are the operator's own
-  reviewed decision; produce the shape and let them fill in and store the
-  real secret.
+- Never generate or approve an operator binding grant on the user's behalf.
+  That is the operator's own reviewed decision; produce the shape and let
+  them fill in and store the real secret.
 - Keep every credential, token and policy file out of source, examples and
   Git. A synthetic example value is fine; a real one is never committed.
 - Do not deploy, expose a service, rotate a credential, or run

package/recipes/authenticated-json-api/recipe.yaml

@@ -3,7 +3,7 @@ description: JSON endpoint protected by the operator-installed auth extension th
 tags: [auth, authenticated, protected, signed-in, bearer, json, api, function, extension, "401", private]
 complexity: advanced
 capabilities: [enabled, extension, function, methods, policies.extensions]
-targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+targets: {self-hosted: conditional, aws: refused, vercel: refused, cloudflare: refused, static: refused}
 routes: 1
 services:
   - name: auth extension

package/recipes/contact-form/recipe.yaml

@@ -3,7 +3,7 @@ description: Validate a JSON contact message in the sandbox and notify an operat
 tags: [contact, form, message, email, post, json, validation, signal, notify, hook, egress, "422"]
 complexity: intermediate
 capabilities: [enabled, function, methods, request.body, response.headers, signals]
-targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
 routes: 1
 services:
   - name: hook endpoint

package/recipes/cors-api/recipe.yaml

@@ -3,7 +3,7 @@ description: JSON endpoint for one allowed browser origin; middleware answers pr
 tags: [cors, preflight, options, browser, origin, api, json, middleware, access-control, vary]
 complexity: intermediate
 capabilities: [enabled, function, methods, middleware, response.headers]
-targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
 routes: 1
 inputs:
   - name: allowedOrigins

package/recipes/health-page/recipe.yaml

@@ -3,7 +3,7 @@ description: Plain-text liveness and JSON readiness answers served natively with
 tags: [health, status, readiness, liveness, uptime, probe, monitoring, respond, native, json]
 complexity: starter
 capabilities: [enabled, methods, respond, response.headers]
-targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible}
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible, static: refused}
 routes: 2
 inputs:
   - name: service

package/recipes/json-api/recipe.yaml

@@ -3,7 +3,7 @@ description: Bounded JSON request body echoed back by a sandboxed function.
 tags: [json, api, post, echo, function, body, validation, sandbox]
 complexity: starter
 capabilities: [enabled, function, methods, request.body]
-targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
 routes: 1
 inputs:
   - name: handler

package/recipes/middleware/middleware/bucket.mjs

@@ -1,5 +1,9 @@
 // Sticky A/B bucketing through a cookie, as on Vercel or Cloudflare edge examples.
 // Bucket b gets a different destination; everyone keeps their bucket for a week.
+// `Response.redirect()`'s headers are immutable (per the Fetch standard a
+// trusted route's real `Response` enforces this, unlike the sandbox's guest
+// API), so build that branch's headers up front instead of mutating the
+// result afterward.
 function cookie(request, name) {
   for (const part of (request.headers.get('cookie') || '').split(';')) {
     const [key, ...rest] = part.trim().split('=');
@@ -12,8 +16,14 @@ export default async function bucket(request, context, next) {
   const fresh = assigned !== 'a' && assigned !== 'b';
   if (fresh) assigned = Math.random() < 0.5 ? 'a' : 'b';
   context.state.bucket = assigned;
-  const response = assigned === 'b' ? Response.redirect(context.env.VARIANT_URL, 302) : await next();
+  const setCookie = 'bucket=' + assigned + '; Path=/; Max-Age=604800; SameSite=Lax';
+  if (assigned === 'b') {
+    const headers = new Headers({ location: context.env.VARIANT_URL, vary: 'cookie' });
+    if (fresh) headers.append('set-cookie', setCookie);
+    return new Response(null, { status: 302, headers });
+  }
+  const response = await next();
   response.headers.set('vary', 'cookie');
-  if (fresh) response.headers.append('set-cookie', 'bucket=' + assigned + '; Path=/; Max-Age=604800; SameSite=Lax');
+  if (fresh) response.headers.append('set-cookie', setCookie);
   return response;
 }

package/recipes/middleware/middleware/locale.mjs

@@ -1,5 +1,8 @@
 // Language redirect from Accept-Language, like Next.js i18n middleware. Only
 // languages listed in LOCALES are chosen; the native redirect is the default.
+// `Response.redirect()`'s headers are immutable (a trusted route's real
+// `Response` enforces the Fetch standard here, unlike the sandbox's guest
+// API), so that branch builds its own `Response` with headers up front.
 export default async function locale(request, context, next) {
   const supported = (context.env.LOCALES || '').split(/\s+/).filter(Boolean);
   const ranked = (request.headers.get('accept-language') || '').split(',').map((part, index) => {
@@ -8,9 +11,10 @@ export default async function locale(request, context, next) {
     return {lang: tag.trim().toLowerCase().split('-')[0], q: q ? Number(q.slice(2)) || 0 : 1, index};
   }).filter(p => p.q > 0).sort((a, b) => b.q - a.q || a.index - b.index);
   const chosen = ranked.find(p => supported.includes(p.lang))?.lang;
-  const response = chosen && chosen !== supported[0]
-    ? Response.redirect(context.env.SITE + '/' + chosen + '/welcome', 302)
-    : await next();
+  if (chosen && chosen !== supported[0]) {
+    return new Response(null, { status: 302, headers: { location: context.env.SITE + '/' + chosen + '/welcome', vary: 'accept-language' } });
+  }
+  const response = await next();
   response.headers.set('vary', 'accept-language');
   return response;
 }

package/recipes/middleware/recipe.yaml

@@ -3,7 +3,7 @@ description: Fourteen reusable middleware patterns around fifteen routes, mirror
 tags: [middleware, auth, bearer, basic, cors, tracing, request-id, errors, etag, caching, maintenance, negotiation, locale, referer, method-override, envelope, validation, debug, bucket, experiment]
 complexity: advanced
 capabilities: [bindings, download, enabled, function, methods, middleware, parameters, redirect, request.body, respond]
-targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
 routes: 15
 inputs:
   - name: credentials

package/recipes/protected-download/recipe.yaml

@@ -3,7 +3,7 @@ description: Native attachment download that only the operator-installed auth ex
 tags: [download, attachment, protected, auth, authenticated, file, private, extension, content-disposition, "401"]
 complexity: advanced
 capabilities: [download, enabled, extension, methods, policies.extensions]
-targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: refused}
+targets: {self-hosted: conditional, aws: conditional, vercel: conditional, cloudflare: refused, static: refused}
 routes: 1
 services:
   - name: auth extension

package/recipes/redirect/recipe.yaml

@@ -3,7 +3,7 @@ description: Permanent redirect that forwards only an allowlisted query key.
 tags: [redirect, permanent, "301", query, passthrough, documentation, native]
 complexity: starter
 capabilities: [enabled, methods, redirect]
-targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible}
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible, static: compatible}
 routes: 1
 inputs:
   - name: destination

package/recipes/static-plus-api/recipe.yaml

@@ -3,7 +3,7 @@ description: A native static site (home page and an assets directory) next to on
 tags: [static, site, page, html, assets, css, api, json, function, cache-control, website]
 complexity: intermediate
 capabilities: [enabled, function, methods, page, response.headers, static]
-targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
 routes: 3
 inputs:
   - name: pages

package/recipes/typescript/README.md

@@ -4,4 +4,5 @@ Run `urlcode build-typescript --project . --out ../hello-built` with a new outpu
 directory, then `urlcode validate --local --project ../hello-built` and
 `urlcode serve --project ../hello-built`. GET `/hello` returns JSON.
 TypeScript is transpiled ahead of time. The runtime executes only the emitted
-JavaScript in QuickJS/WASM. The build does not type-check or read tsconfig.json.
+JavaScript, in QuickJS/WASM for a `sandbox: true` route and in-process for a
+trusted one. The build does not type-check or read tsconfig.json.

package/recipes/typescript/recipe.yaml

@@ -3,7 +3,7 @@ description: Typed guest function transpiled ahead of time; only the emitted Jav
 tags: [typescript, function, build, typed, compile, sandbox]
 complexity: intermediate
 capabilities: [enabled, function, methods]
-targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
 routes: 1
 inputs:
   - name: handler

package/recipes/webhook-receiver/README.md

@@ -5,7 +5,11 @@ Run `urlcode validate --local --project .`, `urlcode test --project .` and
 
 `POST /webhook` accepts at most 64 KiB of `application/json`. The runtime
 rejects other methods (405), other content types (415), oversized bodies (413)
-and malformed JSON (400) before the sandbox runs. The function then requires an
+and malformed JSON (400) before the sandbox runs. The route declares
+`sandbox: true`: functions/middleware run trusted by default, but a
+third-party sender's payload is exactly the input a project doesn't fully
+trust, so this recipe isolates parsing it (docs/FUNCTION-SECURITY.md). The
+function then requires an
 `X-Webhook-Event` header and a JSON object carrying a string `id`, and answers
 `202 {"received":true,...}`.
 

package/recipes/webhook-receiver/recipe.yaml

@@ -3,7 +3,7 @@ description: Accept a bounded JSON event that names its type in a header, check
 tags: [webhook, receiver, event, post, json, body, "202", callback, ingest, function]
 complexity: starter
 capabilities: [enabled, function, methods, request.body, response.headers]
-targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
 routes: 1
 inputs:
   - name: shape check
@@ -24,3 +24,4 @@ behavior:
   - a missing event header answers 400; a body that is not an object with a string id answers 422
   - other methods 405, other content types 415, oversized bodies 413 and malformed JSON 400 before the sandbox runs
   - the guest has no crypto or network API, so signatures are not verified here; put signed webhooks behind an operator extension or trusted host
+  - "the route declares sandbox: true, isolating the third-party payload from the trusted-by-default execution every other function/middleware route gets"

package/recipes/webhook-receiver/urlcode.yaml

@@ -11,6 +11,13 @@ routes:
         format: json
     function:
       source: functions/receive.mjs
+    # A third-party sender's payload is exactly the kind of input this
+    # project does not fully trust (docs/AI-AUTHORING.md, "Deciding when a
+    # route needs sandbox: true"), even after body/content-type validation:
+    # isolate parsing it from the rest of the process.
+    sandbox: true
+    sandboxReason: >-
+      Third-party webhook payload; isolate parsing it even after body/content-type validation.
     response:
       headers:
         Cache-Control: no-store

package/schemas/recipe.schema.json

@@ -45,12 +45,13 @@
       "description": "Derived: the capability preflight verdict per target. compatible means no issue; otherwise the strongest issue (refused, unknown, conditional).",
       "type": "object",
       "additionalProperties": false,
-      "required": ["self-hosted", "aws", "vercel", "cloudflare"],
+      "required": ["self-hosted", "aws", "vercel", "cloudflare", "static"],
       "properties": {
         "self-hosted": {"$ref": "#/$defs/verdict"},
         "aws": {"$ref": "#/$defs/verdict"},
         "vercel": {"$ref": "#/$defs/verdict"},
-        "cloudflare": {"$ref": "#/$defs/verdict"}
+        "cloudflare": {"$ref": "#/$defs/verdict"},
+        "static": {"$ref": "#/$defs/verdict"}
       }
     },
     "routes": {
@@ -81,7 +82,7 @@
         "additionalProperties": false,
         "required": ["kind", "description"],
         "properties": {
-          "kind": {"enum": ["extension", "signals", "proxy", "env", "secret", "link-store", "origin"]},
+          "kind": {"enum": ["extension", "signals", "proxy", "env", "secret", "origin"]},
           "description": {"type": "string", "minLength": 1, "maxLength": 300}
         }
       }

package/schemas/urlcode.schema.json

@@ -22,11 +22,6 @@
       "uniqueItems": true,
       "maxItems": 256
     },
-    "dynamicLinks": {
-      "type": "boolean",
-      "default": false,
-      "description": "Entry-point opt-in for live stored-link routes. Does not enable guest storage or management access."
-    },
     "policies": {
       "$ref": "#/$defs/policies"
     },
@@ -346,6 +341,16 @@
         "enabled": {
           "type": "boolean"
         },
+        "sandbox": {
+          "type": "boolean",
+          "default": false,
+          "description": "Run this route's function/middleware in the isolated QuickJS/WASM worker pool instead of the trusted, in-process default. false or absent (the default) means trusted, unsandboxed, direct host-process execution."
+        },
+        "sandboxReason": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Optional justification for this route's sandbox decision, whether sandbox is true or false: why it needs isolation, or why it is safe to trust. Never inferred or enforced; surfaced verbatim by explain/context/manifest."
+        },
         "expires": {
           "type": "string"
         },
@@ -882,37 +887,6 @@
             ]
           }
         },
-        "link": {
-          "type": "object",
-          "properties": {
-            "collection": {
-              "type": "string",
-              "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,63}$"
-            },
-            "code": {
-              "type": "object",
-              "properties": {
-                "from": {
-                  "const": "path"
-                },
-                "name": {
-                  "type": "string",
-                  "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
-                }
-              },
-              "required": [
-                "from",
-                "name"
-              ],
-              "additionalProperties": false
-            }
-          },
-          "required": [
-            "collection",
-            "code"
-          ],
-          "additionalProperties": false
-        },
         "policies": {
           "$ref": "#/$defs/policies"
         },
@@ -964,6 +938,10 @@
               "$ref": "#/$defs/routeAuth"
             }
           ]
+        },
+        "cache": {
+          "description": "Short form for policies.cache: the same object, expanded to policies.cache before anything else reads the project. Refused alongside policies.cache; use one form.",
+          "$ref": "#/$defs/policyCache"
         }
       },
       "required": [],
@@ -999,11 +977,6 @@
             "respond"
           ]
         },
-        {
-          "required": [
-            "link"
-          ]
-        },
         {
           "required": [
             "conditional"