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

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@jimhoyd/urlcode",
-  "version": "0.4.0-alpha.2",
+  "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"
@@ -101,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/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",
+    "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",
@@ -122,7 +127,19 @@
     "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",
@@ -138,11 +155,14 @@
     "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#readme",

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.2",
+  "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

@@ -26,17 +26,12 @@ Documentation, schema and runtime must come from the **same revision**. Read fro
 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
 
@@ -52,8 +47,8 @@ checkout you are working in — never from memory of another version.
 - 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.
@@ -69,14 +64,17 @@ mistakes that recur:
 - `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
+  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.
@@ -84,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.
-- 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.
+- 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

@@ -74,20 +74,20 @@ 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.
-- 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.
+- 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.
 

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

@@ -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,5 +1,5 @@
 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]
@@ -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

@@ -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/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,6 +1,6 @@
 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, static: refused}
@@ -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/protected-download/README.md

@@ -3,7 +3,7 @@
 `/downloads/report` serves `files/report.txt` as an attachment, but only after
 the operator-installed `auth` extension authorizes the request (`auth: true`,
 the short form of `policies.extensions.auth`). The file is
-served natively: no guest code runs, and the response is forced to `no-store`.
+served natively: no project code runs at all, and the response is forced to `no-store`.
 
 Like the `authenticated-json-api` recipe, this project declares the extension
 and needs an operator host file outside the project plus the canonical origin

package/recipes/protected-download/recipe.yaml

@@ -28,4 +28,4 @@ behavior:
   - GET /downloads/report without credentials answers 401
   - GET with the accepted credential answers 200, Content-Disposition attachment and Cache-Control no-store
   - HEAD mirrors both cases with an empty body
-  - no guest code runs; the file is served natively and snapshotted at activation
+  - no project code runs; the file is served natively and snapshotted at activation

package/recipes/static-plus-api/README.md

@@ -5,8 +5,8 @@ Run `urlcode validate --local --project .`, `urlcode test --project .` and
 
 `/` serves `public/index.html`, `/assets/*` serves everything under
 `public/assets` (with `index.html` for the directory itself), and `/api/info`
-is a sandboxed function returning JSON built from literal `args`. Pages and
-assets are native: no guest code runs for them, and they are snapshotted at
+is a function returning JSON built from literal `args`. Pages and
+assets are native: no project code runs for them at all, and they are snapshotted at
 activation, so new files need a reload. Edit the HTML, add files under
 `public/assets`, and change or extend `functions/info.mjs`.
 

package/recipes/static-plus-api/public/index.html

@@ -3,6 +3,6 @@
 <head><meta charset="utf-8"><title>Example site</title><link rel="stylesheet" href="/assets/site.css"></head>
 <body>
 <h1>Example site</h1>
-<p>Static pages are served natively; <a href="/api/info">/api/info</a> is a sandboxed function.</p>
+<p>Static pages are served natively; <a href="/api/info">/api/info</a> is a function route.</p>
 </body>
 </html>

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

@@ -1,5 +1,5 @@
 id: static-plus-api
-description: A native static site (home page and an assets directory) next to one sandboxed JSON endpoint.
+description: A native static site (home page and an assets directory) next to one function-backed JSON endpoint.
 tags: [static, site, page, html, assets, css, api, json, function, cache-control, website]
 complexity: intermediate
 capabilities: [enabled, function, methods, page, response.headers, static]

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

@@ -12,7 +12,7 @@ routes:
       index: index.html
       cacheControl: public, max-age=3600
   /api/info:
-    description: A small JSON endpoint next to the static site, computed in the sandbox.
+    description: A small JSON endpoint next to the static site, computed by a trusted function.
     function:
       source: functions/info.mjs
       args:

package/recipes/typescript/recipe.yaml

@@ -1,6 +1,6 @@
 id: typescript
-description: Typed guest function transpiled ahead of time; only the emitted JavaScript runs in the sandbox.
-tags: [typescript, function, build, typed, compile, sandbox]
+description: "Typed function transpiled ahead of time; only the emitted JavaScript runs: in-process for a trusted route, in QuickJS/WASM where a route declares `sandbox: true`."
+tags: [typescript, function, build, typed, compile]
 complexity: intermediate
 capabilities: [enabled, function, methods]
 targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
@@ -8,7 +8,7 @@ routes: 1
 inputs:
   - name: handler
     file: functions/hello.ts
-    description: The typed guest; keep to the Request/Response sandbox API.
+    description: "The typed handler; keep to Request/Response, and to the sandbox subset if you add `sandbox: true`."
 files: [urlcode.yaml, functions/hello.ts, tests/requests.json, README.md]
 tests:
   fixtures: tests/requests.json
@@ -18,6 +18,6 @@ tests:
     - urlcode test --project ../hello-built
     - urlcode audit --project ../hello-built --expect-routes 1
 behavior:
-  - after the build, GET /hello answers 200 JSON from the compiled guest
+  - after the build, GET /hello answers 200 JSON from the compiled module
   - the unbuilt project does not activate; .ts sources never run
   - POST answers 405

package/skills/urlcode/SKILL.md

@@ -6,7 +6,7 @@ description: Work on a URLCode project, recognized by a urlcode.yaml file with v
 # URLCode authoring loop
 
 A URLCode project declares URL behavior in YAML; the installed runtime serves
-it. Your job is to change the declaration and the minimal guest code it names,
+it. Your job is to change the declaration and the minimal application code it names,
 then prove the change with the runtime's own checks. Never reimplement what the
 runtime provides, and never invent fields.
 
@@ -68,14 +68,14 @@ need rather than reading them whole.
 2. Check supported extensions and their configuration before custom code. If a
    recipe from `recipes list` is close, `urlcode recipes add NAME --out DIR`
    and adapt the copy into the project's layout.
-3. Only then write a function or middleware: one exported handler, relative
-   ES-module imports inside the project only, inputs from validated `args`,
+3. Only then write a function or middleware: one exported handler, inputs from validated `args`,
    output as a `Response`. `function`/`middleware` routes run trusted and
    unsandboxed by default: full Node, npm, filesystem and `fetch` access, like
    any other project code. Add `sandbox: true` only when that route's own code
-   warrants isolation (untrusted input, an unreviewed contribution, a
-   particularly sensitive secret) — a `sandbox: true` route then has no
-   `fetch`, Node, npm, filesystem, WebSocket, streaming, crypto API or timers;
+   warrants isolation (unreviewed or third-party code, a secret whose blast
+   radius matters, complex logic — never merely because it handles request
+   data, which is untrusted in both modes) — a `sandbox: true` route then has no
+   `fetch`, Node, npm, filesystem, WebSocket, streaming or crypto APIs (bounded timers are supported);
    a need for those in a sandboxed route is a `proxy` route, a binding, or a
    report.
 4. Declare routing, validation, middleware chains, policies, static serving,

package/starters/default/AGENTS.md

@@ -42,12 +42,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