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

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,22 @@ 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`.
-- [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.
+- [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](packages/auth): npm: @jimhoyd/urlcode-auth; accounts, sessions, MFA, roles, account page; its own llms.txt. Lives in this repository as a workspace package.
+- [urlcode-admin](packages/admin): npm: @jimhoyd/urlcode-admin; users, sessions, roles, audit, cases; its own llms.txt. Lives in this repository as a workspace package.
+- [urlcode-ui](packages/ui): npm: @jimhoyd/urlcode-ui; escaped templates, shadcn/ui partials, themes, translations; its own llms.txt. Lives in this repository as a workspace package, not in a separate repository.
+- urlcode-middleware (retired): per-route middleware briefly lived here as an extension-seam alternative; the package was unpublished at 0.1.0-alpha.2 and its repository deleted. This is not a gap — per-route middleware is native to core via the `middleware:` array (docs/MIDDLEWARE.md); use that.
+- urlcode-dynamic-link (retired): stored short links briefly lived here as a mount-based extension; the package was unpublished and its repository deleted. Core has no native `link` handler and no supported extension provides stored links — report them as a gap.
 - [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,8 +1,11 @@
 {
   "name": "@jimhoyd/urlcode",
-  "version": "0.4.0-alpha.1",
+  "version": "0.4.0-alpha.3",
   "description": "Portable runtime for programmable URL behavior",
   "type": "module",
+  "workspaces": [
+    "packages/*"
+  ],
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22.13.0"
@@ -69,6 +72,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,8 +104,10 @@
     "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",
-    "verify": "npm run lint && npm run typecheck && npm run check && npm run build && npm test",
+    "check": "node scripts/check.ts && node scripts/check-trust-model-prose.ts && node scripts/check-guidance-claims.ts && node scripts/check-release-tags.ts && node scripts/check-workspace-links.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 && npm run release:check",
+    "verify": "npm run lint && npm run typecheck && npm run check && npm run build && npm test && npm run verify:workspaces",
+    "workspace:styles": "npm run styles --workspace @jimhoyd/urlcode-ui",
+    "verify:workspaces": "npm run verify --workspace @jimhoyd/urlcode-ui && npm run verify --workspace @jimhoyd/urlcode-auth && npm run verify --workspace @jimhoyd/urlcode-admin && npm run test:workspace-integration",
     "benchmark": "node benchmarks/routing.ts",
     "test:package": "npm run build && node scripts/package-smoke.ts",
     "dev": "node src/cli.ts dev --project starters/default",
@@ -113,9 +123,23 @@
     "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"
+    "sync:agents": "node scripts/sync-agent-lists.ts",
+    "check:docs": "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",
+    "ci:plan": "node scripts/ci-plan.ts",
+    "test:package:built": "node scripts/package-smoke.ts",
+    "release:status": "node scripts/release.ts status",
+    "release:plan": "node scripts/release.ts plan",
+    "release:publish": "node scripts/release.ts publish",
+    "release:run": "node scripts/release-run.ts",
+    "release:peers": "node scripts/release.ts peers",
+    "release:check": "node scripts/release.ts check",
+    "ci:history": "node scripts/ci-history.ts",
+    "ci:report": "node scripts/ci-report.ts",
+    "test:workspace-integration": "node --test test/workspace-scaffold.integration.ts"
   },
   "repository": {
     "type": "git",
@@ -131,14 +155,17 @@
     "yaml": "2.9.1"
   },
   "devDependencies": {
+    "@changesets/cli": "3.0.3",
     "@eslint/js": "10.0.1",
     "@types/mime-types": "3.0.1",
     "@types/node": "26.5.1",
+    "@types/semver": "7.8.0",
     "eslint": "10.10.0",
     "globals": "17.12.0",
+    "semver": "7.8.5",
     "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.3",
   "author": {
     "name": "jimhoyd-com",
     "url": "https://github.com/jimhoyd-com"
@@ -14,6 +14,6 @@
     "routing",
     "yaml",
     "redirects",
-    "short-links"
+    "middleware"
   ]
 }

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,23 +11,27 @@ 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
 the project's installed runtime (`node_modules/@jimhoyd/urlcode/`) or the
 checkout you are working in — never from memory of another version.
 
-1. `docs/AI-AUTHORING.md` — the authoring contract and the **capability matrix**
-   of what is available versus unavailable. Read this first and in full.
-2. `schemas/urlcode.schema.json` — the exact accepted structure.
-3. `docs/YAML-REFERENCE.md` and `docs/SPECIFICATION.md` — every field, and the
-   implemented semantics, defaults and sandbox API.
-4. `docs/YAML-GUIDE.md` and `examples/cookbook/` — recipes and runnable files.
-5. `docs/ROUTING.md`, `docs/HTTP.md`, `docs/MIDDLEWARE.md`, `docs/ASSETS.md` —
-   matching precedence, methods, composition, MIME and ranges.
-6. `docs/FUNCTION-SECURITY.md` — the sandbox and operator binding policy.
-
-`llms.txt` at the repository root is a compact index of all of the above.
+Start with `urlcode context --project <dir> --budget 4000`, then retrieve the
+capability, schema fragment, recipe or example relevant to the change. Use the
+read-only MCP equivalents when available. `llms.txt` is the index; read the
+matching task guide from `docs/` when a query needs more explanation.
+`docs/SPECIFICATION.md` and `schemas/urlcode.schema.json` resolve contract
+questions. Archived plans are historical, not valid YAML guidance.
 
 ## Workflow
 
@@ -35,15 +39,16 @@ 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 `${...}`
   interpolation anywhere in the format.
 - Create every referenced module, page and asset **before** validating. All
-  paths resolve from the project root; functions and middleware use relative
-  ES-module imports only.
+  source paths resolve from the project root. Trusted modules can import Node built-ins and npm packages;
+  only `sandbox: true` modules are restricted to the relative snapshotted graph.
 - Write exact response fixtures for success and failure, covering every active
   method, middleware behavior, HEAD, and any range or cache semantics.
 - Follow `docs/BEST-PRACTICES.md` for layout and readability as the project grows.
@@ -56,11 +61,20 @@ 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 (unreviewed or third-party code, a secret whose
+  blast radius matters, complex logic), not reflexively on every route and
+  never merely because it handles request data -- that is untrusted in both
+  modes and must be validated either way. 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
+  `cache`, plus registered extension requirements under `extensions`;
+  the built-in policies are off unless declared; `hardened` is the only built-in
   profile. Check the per-target table in `docs/POLICIES.md` before declaring
   one for a serverless or Cloudflare deployment — an unsupported policy refuses
   activation rather than degrading.
@@ -68,9 +82,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, and no
+  supported extension package provides one; report stored short links 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,28 +69,25 @@ 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
 
-- No provider adapters, automatic TLS/DNS, distributed rate limiting, metrics
-  exporters or durable event delivery are included; these remain the
-  operator's own infrastructure.
+- Provider adapters exist with different capability limits; query
+  `urlcode capabilities --target NAME`. Automatic TLS/DNS, distributed rate
+  limiting, metrics exporters and durable delivery require operator infrastructure.
 - No orchestration, traffic switching or automated rollback; recovery is an
   explicit snapshot reload from a known-good artifact.
 - `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.
-- 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.
+- Core has no durable store and no private management API of its own, and no
+  supported extension package provides stored short links.
+- Only `sandbox: true` routes share the sandbox worker slots and forced
+  execution deadlines. Trusted routes run in Node under HTTP admission limits;
+  their cooperative timeout cannot stop blocking JavaScript. A guest timer still
+  occupies a sandbox slot. Size both modes from `docs/CAPACITY.md`.
 - `throttle` and `agents` policy counters are per instance, not distributed;
   they are a second layer behind the edge, never a replacement for it.
 
@@ -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/README.md

@@ -1,9 +1,10 @@
 # Authenticated JSON API
 
-`/api/profile` is a sandboxed function behind `auth: true`, the route-level short
+`/api/profile` is a function behind `auth: true`, the route-level short
 form that expands to `policies.extensions.auth: {}`. The project declares the
-`auth` extension; it never chooses or loads the module that implements it. Authorization happens in trusted operator code before the guest
-runs, and the runtime withholds `Authorization` and `Cookie` from the sandbox.
+`auth` extension; it never chooses or loads the module that implements it. Authorization happens in trusted operator code before the route's function
+runs, and the host strips `Authorization` and `Cookie` before dispatch -- for
+trusted and `sandbox: true` routes alike.
 
 This recipe does not activate on its own. Every command needs an operator host
 file outside the project plus the canonical origin:

package/recipes/authenticated-json-api/functions/profile.mjs

@@ -1,5 +1,6 @@
 // The auth extension has already authorized this request. Credentials never
-// reach guest code: Authorization and Cookie are withheld from the sandbox.
+// reach this function: the host strips Authorization and Cookie before
+// dispatch, in both execution modes.
 export default function profile() {
   return Response.json({signedIn: true, profile: {name: 'Ada', plan: 'team'}});
 }

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
@@ -28,7 +28,7 @@ tests:
     - urlcode test --project . --host-file /operator/host.mjs --origin https://api.example.com
     - urlcode audit --project . --expect-routes 1 --host-file /operator/host.mjs --origin https://api.example.com
 behavior:
-  - GET /api/profile without credentials answers 401 from the extension before the guest runs
+  - GET /api/profile without credentials answers 401 from the extension before the function runs
   - GET with the credential the extension accepts answers 200 JSON with Cache-Control no-store
   - HEAD mirrors both cases with an empty body; POST answers 405
   - the project declares the extension and the requirement; it never chooses or loads the implementing module

package/recipes/contact-form/functions/contact.mjs

@@ -1,7 +1,8 @@
 // Field checks the runtime does not do: the body limit and JSON syntax are
 // enforced before this runs. The declared signal fires after a response with
 // a fixed payload (route, method, status); the message itself never leaves
-// the sandbox, so a form store or mailer must sit behind the granted hook.
+// the signal, so a form store or mailer belongs behind the granted hook rather
+// than an ad-hoc call from here.
 const emailPattern = /^[^\s@]{1,64}@[^\s@]{1,255}$/;
 export default async function contact(request) {
   const body = await request.json();

package/recipes/contact-form/recipe.yaml

@@ -1,9 +1,9 @@
 id: contact-form
-description: Validate a JSON contact message in the sandbox and notify an operator-granted hook with a fixed signal after the response.
+description: Validate a JSON contact message in a function and notify an operator-granted hook with a fixed signal after the response.
 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
@@ -30,4 +30,4 @@ behavior:
   - POST /contact with a valid name, email and message answers 202 {"accepted":true}
   - invalid fields answer 422 with one error line per field; a non-object body answers 422
   - form-encoded bodies answer 415 and GET answers 405
-  - the signal carries route, method and status only, best effort; the message itself never leaves the sandbox
+  - the signal carries route, method and status only, best effort; the message itself is never included

package/recipes/cors-api/README.md

@@ -3,7 +3,7 @@
 Run `urlcode validate --local --project .`, `urlcode test --project .` and
 `urlcode audit --project . --expect-routes 1`.
 
-`/api/items` returns JSON from a sandboxed function. `middleware/cors.mjs` runs
+`/api/items` returns JSON from a function (trusted, the default). `middleware/cors.mjs` runs
 around it: it answers `OPTIONS` preflight itself with 204 and adds
 `Access-Control-Allow-Origin` to responses for origins in its allowlist. Other
 origins get `Vary: Origin` and no allow header, so browsers refuse them.
@@ -11,6 +11,6 @@ origins get `Vary: Origin` and no allow header, so browsers refuse them.
 Edit `allowedOrigins` in the middleware and the function body. The route must
 list `OPTIONS` in `methods`, or the runtime answers 405 before the middleware
 runs. CORS is not a host policy in this contract; middleware is the supported
-place for it, and it needs the sandbox, so serverless targets refuse this
+place for it, and middleware needs the self-hosted Node lifecycle, so serverless targets refuse this
 project. A browser-facing API that also needs credentials must add
 `Access-Control-Allow-Credentials` deliberately, never with a wildcard origin.

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
@@ -23,4 +23,4 @@ behavior:
   - OPTIONS /api/items from https://app.example.com answers 204 with Access-Control-Allow-Origin, -Methods and -Headers
   - GET from the allowed origin carries Access-Control-Allow-Origin; other origins get Vary Origin and no allow header
   - the route lists OPTIONS in methods, otherwise the runtime answers 405 before the middleware runs
-  - CORS is middleware, not a host policy, so the route needs the sandbox
+  - CORS is middleware, not a host policy, so the route needs the self-hosted Node lifecycle

package/recipes/health-page/README.md

@@ -4,7 +4,7 @@ Run `urlcode validate --local --project .`, `urlcode test --project .` and
 `urlcode audit --project . --expect-routes 2`.
 
 `/health` answers `ok` as text and `/status` answers a small JSON document. Both
-are native `respond` routes with `Cache-Control: no-store`, so no sandbox runs
+are native `respond` routes with `Cache-Control: no-store`, so no project code runs
 and every target supports them. Change `service` in `urlcode.yaml` to your
 service name.
 

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/README.md

@@ -1,6 +1,6 @@
 # JSON echo API
 
 Run `urlcode validate --local --project .` and `urlcode serve --project .`.
-POST JSON with `Content-Type: application/json` to `/echo`. The sandbox returns
+POST JSON with `Content-Type: application/json` to `/echo`. The function returns
 `{"received": ...}`. Other methods are refused. Do not submit credentials to an
 echo endpoint. This recipe grants no network or filesystem access.

package/recipes/json-api/recipe.yaml

@@ -1,9 +1,9 @@
 id: json-api
-description: Bounded JSON request body echoed back by a sandboxed function.
-tags: [json, api, post, echo, function, body, validation, sandbox]
+description: Bounded JSON request body echoed back by a function (trusted, the default).
+tags: [json, api, post, echo, function, body, validation]
 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
@@ -21,5 +21,5 @@ tests:
     - urlcode audit --project . --expect-routes 1
 behavior:
   - POST /echo with application/json answers 200 {"received":<body>}
-  - malformed JSON answers 400 and another content type 415 before the sandbox runs
+  - malformed JSON answers 400 and another content type 415 before the function runs
   - GET answers 405

package/recipes/middleware/README.md

@@ -3,14 +3,15 @@
 Fourteen reusable middleware modules on fifteen routes (`auth.mjs` serves two),
 covering what Express, Koa,
 Hono, Next.js and edge runtimes usually ship as middleware, rewritten for
-URLCode's small sandboxed guest API. Run `urlcode validate --local --project .`
+URLCode's middleware contract. These modules run trusted and in-process, the
+default; a `sandbox: true` route sees a smaller guest API instead. Run `urlcode validate --local --project .`
 and `urlcode serve --project .`, then keep the routes you need and delete the
 rest; every module is independent.
 
 | Route | Module | Pattern |
 | --- | --- | --- |
 | `/api/private` | `middleware/auth.mjs` (`bearer`) | Bearer token with constant-time comparison |
-| `/admin/panel` | `middleware/auth.mjs` (`basic`) | HTTP Basic decoded in the guest |
+| `/admin/panel` | `middleware/auth.mjs` (`basic`) | HTTP Basic decoded in trusted middleware |
 | `/cors/data` | `middleware/cors.mjs` | Origin allowlist and preflight |
 | `/traced` | `middleware/request-id.mjs` | Caller correlation id and Server-Timing |
 | `/maintenance` | `middleware/maintenance.mjs` | 503 kill switch with bypass header |
@@ -28,7 +29,10 @@ rest; every module is independent.
 Tokens, passwords and switches are literal `env` values so the recipe runs
 without grants. Before deploying, move credentials to `{secret: name}` bindings
 with an operator grant, replace the example.com destinations, and delete the
-`/inspect` route or set `DEBUG` to `false`. The guest exposes no crypto, so none
+`/inspect` route or set `DEBUG` to `false`. These modules run trusted, so
+`node:crypto` is available; the examples deliberately stay to request shaping
+and are not a security boundary. Under `sandbox: true` there is no crypto API
+at all, so none
 of these modules can verify signatures or hash passwords; treat them as request
 shaping, not as a security boundary. See the runtime's middleware documentation
-for the full list of guest limits.
+for the full list of sandboxed-route limits.

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;
 }