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

package/.claude/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/.claude/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/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude plugins published from the URLCode repository.",
-    "version": "0.4.0-alpha.1"
+    "version": "0.4.0-alpha.2"
   },
   "plugins": [
     {

package/README.md

@@ -1,8 +1,8 @@
 # URLCode
 
 **A portable runtime for programmable URL behavior, and the framework that grows
-from it.** Declare an application's public URL surface in YAML, add isolated
-JavaScript only where declarative handlers are not enough, and run the same
+from it.** Declare an application's public URL surface in YAML, add JavaScript
+only where declarative handlers are not enough, and run the same
 project locally, in a container, on your own infrastructure or on a provider
 adapter. When the project gets serious, add accounts and an administration
 console as operator-installed extensions instead of building them again.
@@ -26,16 +26,22 @@ infrastructure for AI-built software, not a framework for building AI models.
 
 A project is a `urlcode.yaml` with `version: "1"`. Each route has exactly one
 handler: `redirect`, `respond`, `page`, `static`, `download`, `function`,
-`link`, `proxy`, `conditional` or an `extension` mount, with optional ordered
+`proxy`, `conditional` or an `extension` mount, with optional ordered
 `middleware`. The runtime validates the whole project before serving it,
 compiles it once, and refuses anything a target cannot enforce with the route
-named. Functions run in a QuickJS/WebAssembly sandbox with a fresh heap per
-call and no Node, filesystem or network; secrets reach them only through
-operator grants pinned to the project revision.
-
-URLCode is not a URL shortener: short links are one handler. It is not a
-general Node web framework: guest code cannot reach the host. It is not a
-provider configuration format: infrastructure settings stay out of route YAML.
+named. Functions and middleware run trusted, in-process, with full Node
+access by default; a route opts into an isolated QuickJS/WebAssembly sandbox
+with a fresh heap per call and no Node, filesystem or network by declaring
+`sandbox: true`. Either way, secrets reach them only through operator grants
+pinned to the project revision.
+
+URLCode is not a URL shortener: stored short links are an operator-installed
+extension, not core's job. It is not a
+general Node web framework: routing, validation, middleware wiring and
+policies are declared in YAML, not hand-wired; isolating a specific route's
+code from the host is an explicit `sandbox: true` opt-in, not something every
+route gets by writing a handler. It is not a provider configuration format:
+infrastructure settings stay out of route YAML.
 See [project direction](docs/PROJECT-DIRECTION.md).
 
 ## The framework
@@ -47,10 +53,20 @@ an AI agent must follow are in [the framework](docs/FRAMEWORK.md).
 
 | Package | Adds | Status |
 |---|---|---|
-| [urlcode](https://github.com/jimhoyd-com/urlcode) (this repository) | Runtime, CLI, policies, live links, provider adapters, extension contract | `0.4.0-alpha.1` (alpha) on top of the `0.3.0` release, Apache-2.0 |
-| [urlcode-ui](https://github.com/jimhoyd-com/urlcode-ui) | Shared presentation: escaped templates, shadcn/ui partials, themes, translations | `0.1.0-alpha.1` on npm, alpha: review pending |
-| [urlcode-auth](https://github.com/jimhoyd-com/urlcode-auth) | Accounts: password, passkeys, OIDC, email codes, TOTP, sessions, roles, account page | `0.1.0-alpha.1` on npm, alpha: review pending |
-| [urlcode-admin](https://github.com/jimhoyd-com/urlcode-admin) | Administration: users, sessions, roles, audit, approvals, cases, impersonation | `0.1.0-alpha.1` on npm, alpha: review pending |
+| [urlcode](https://github.com/jimhoyd-com/urlcode) (this repository) | Runtime, CLI, policies, provider adapters, extension contract | `0.4.0-alpha.2` (alpha) on top of the `0.3.0` release, Apache-2.0 |
+| [urlcode-ui](https://github.com/jimhoyd-com/urlcode-ui) | Shared presentation: escaped templates, shadcn/ui partials, themes, translations | `0.1.0-alpha.5` on npm, alpha: review pending |
+| [urlcode-auth](https://github.com/jimhoyd-com/urlcode-auth) | Accounts: password, passkeys, OIDC, email codes, TOTP, sessions, roles, account page | `0.1.0-alpha.3` on npm, alpha: review pending |
+| [urlcode-admin](https://github.com/jimhoyd-com/urlcode-admin) | Administration: users, sessions, roles, audit, approvals, cases, impersonation | `0.1.0-alpha.3` on npm, alpha: review pending |
+| [urlcode-dynamic-link](https://github.com/jimhoyd-com/urlcode-dynamic-link) | Stored short links: the mount-based successor to core's removed `link` handler | `0.1.0-alpha.2` on npm, alpha: review pending |
+| [urlcode-middleware](https://github.com/jimhoyd-com/urlcode-middleware) | Per-route middleware through the extension seam, alongside core's native array | `0.1.0-alpha.2` on npm, alpha: review pending |
+| [urlcode-short](https://github.com/jimhoyd-com/urlcode-short) | A complete link shortener assembled from the packages above | `0.1.0-alpha.2` on npm, alpha: review pending |
+
+Every version in this table is the one published to npm under the `alpha`
+dist-tag, and they are released together in the order core → ui → auth →
+admin → dynamic-link/middleware → short. The authoritative cross-repository
+register, including each package's declared peer ranges and the rules that
+keep them consistent, is
+[docs/VERSION-ALIGNMENT.md](docs/VERSION-ALIGNMENT.md).
 
 ```yaml
 version: "1"
@@ -74,23 +90,26 @@ it. Cross-repository acceptance is tracked in
 
 ## Status
 
-`0.4.0-alpha.1` is the current release of the extension contract and the
-agent tooling, on top of the `0.3.0` self-hosted release. It adds the
-extension contract, capabilities and provider conformance, strict redirect
-interchange, bulk import, recipes and search, TypeScript guest authoring,
-conditions, bounded proxy and signals, and the MCP read and authoring modes;
-use the schema and docs from the runtime revision you run.
+`0.4.0-alpha.2` is the current release of the extension contract and the
+agent tooling, on top of the `0.3.0` self-hosted release. `0.4.0-alpha.1`
+added the extension contract, capabilities and provider conformance, strict
+redirect interchange, bulk import, recipes and search, TypeScript guest
+authoring, conditions, bounded proxy and signals, and the MCP read and
+authoring modes. `0.4.0-alpha.2` then made `function` and `middleware` routes
+run trusted and unsandboxed by default, with `sandbox: true` as a per-route
+opt-in, and removed the native `link:`/`dynamicLinks:` YAML shape. That is a
+behaviour change for existing projects with no YAML edit; read
+[the roadmap entry](ROADMAP.md) before upgrading. Use the schema and docs from
+the runtime revision you run.
 The [roadmap](ROADMAP.md) separates implemented from planned, and
 [release readiness](docs/RELEASE-READINESS.md) records what is proven and
 what is not: provider deployments, soak and independent security review
 remain open.
 
-Live-link storage uses separate bounded reader/writer pools. It requires a Node
-build containing a patched SQLite version — 3.51.3 or newer, 3.50.7, or 3.44.6 —
-which some current releases on a supported Node line do not carry. Run
-`urlcode doctor` and check `liveLinks` before relying on it; everything else
-runs on any supported Node.
-See [pool controls and scaling limits](docs/DYNAMIC-LINKS.md#separate-reader-and-writer-pools).
+Stored short links have moved out of core into
+[urlcode-dynamic-link](https://github.com/jimhoyd-com/urlcode-dynamic-link)
+(mount-based, like `auth`/`admin`, published on npm); core no longer has a
+native `link` handler.
 
 URLCode is free and open-source software licensed under the
 [Apache License 2.0](LICENSE). Commercial use, modification, redistribution and
@@ -123,42 +142,36 @@ npm ci
 npm run dev
 ```
 
-Live stored-link routes require **`dynamicLinks: true`** in the entry `urlcode.yaml`;
-the starter explicitly sets false. Ordinary functions and parameterized redirects
-do not need it. [Live-link setup](docs/DYNAMIC-LINKS.md).
-
 ## Built with URLCode
 
-[urlcode-shortener](https://github.com/jimhoyd-com/urlcode-shortener) is a
-standalone, account-free demo built on URLCode's public runtime and storage APIs.
+[urlcode-short](https://github.com/jimhoyd-com/urlcode-short) is a
+standalone, account-free demo built on URLCode's public runtime. It predates
+this repository's removal of the native link-store API from core; its
+retrospective should be read alongside that change, not as current guidance.
 It combines short links that expire after one hour or less, QR downloads, and a
-shadcn/ui + Tailwind frontend. URLCode handles the page/assets and stored-link
-redirects; the application adds anonymous creation and its own limits.
+shadcn/ui + Tailwind frontend. URLCode handles the page/assets and routing; the
+application adds anonymous creation, stored-link storage and its own limits.
 
-Read its [build retrospective](https://github.com/jimhoyd-com/urlcode-shortener/blob/main/docs/BUILD-RETROSPECTIVE.md)
+Read its [build retrospective](https://github.com/jimhoyd-com/urlcode-short/blob/main/docs/BUILD-RETROSPECTIVE.md)
 for what the runtime supplied, what the application still needed, and proposed
 improvements. The demo's license, hosting and production validation remain open;
 it does not change URLCode's Apache-2.0 license or guest isolation model.
 
-[urlcode-docs](https://github.com/jimhoyd-com/urlcode-docs) demonstrates URLCode
-hosting a static documentation site with shadcn/ui and Tailwind. It syncs this
-repository’s Markdown and examples at a pinned revision, applies templates through
-sandboxed middleware during the build, and serves the output through native
-page/static/download routes. This repository remains the documentation source of
-truth. See the [docs-site retrospective](https://github.com/jimhoyd-com/urlcode-docs/blob/main/docs/BUILD-RETROSPECTIVE.md)
-for reuse, integration work and upstream improvements. Hosting and a public domain
-are not yet selected; the original site-code license is pending.
+`urlcode-docs` demonstrates URLCode hosting a static documentation site with
+shadcn/ui and Tailwind: content authored directly in that repository, applying
+templates through its own sandbox-opted-in (`sandbox: true`) middleware during
+the build, served through native page/static/download routes. That repository
+is currently private, so it isn't publicly browsable yet. Hosting and a public
+domain are not yet selected; the original site-code license is pending.
 
 ## Start from YAML
 
 Already wrote `urlcode.yaml`? Run `urlcode scaffold --project ./my-links --dry-run`,
 then remove `--dry-run` to create missing modules, pages and directories. Existing
 files are preserved; code placeholders return 501 until implemented.
-[Scaffolding guide](docs/SCAFFOLDING.md).
-Live-link storage and the auth extension need a Node build whose SQLite is
-3.51.3 or newer, 3.50.7 or 3.44.6. `urlcode doctor` reports `liveLinks`;
-everything else runs on any supported Node (22.13+ installed, 22.18+ to run
-the TypeScript source).
+[Scaffolding guide](docs/SCAFFOLDING.md). Node 22.13+ installed, 22.18+ to run
+the TypeScript source; the separate `urlcode-auth` extension may have its own
+SQLite build requirement, unverified from this repository.
 
 ## Try it
 
@@ -204,9 +217,6 @@ and [middleware](docs/MIDDLEWARE.md).
 
 - **Pages, files, downloads:** `page`, `static`, `download` with MIME detection,
   ETags, ranges and safety limits. [Assets](docs/ASSETS.md).
-- **Live short links:** a `link` route on an optional SQLite store; create,
-  update and delete without reloads through the CLI or the private management
-  API. [Dynamic links](docs/DYNAMIC-LINKS.md).
 - **HTTP:** methods, validated path/query/header inputs, body limits, response
   headers and cookies. [HTTP](docs/HTTP.md).
 - **Policies and site conventions:** throttle, agents, security headers,
@@ -227,11 +237,13 @@ and [middleware](docs/MIDDLEWARE.md).
 Self-hosted Node process or container first. `@jimhoyd/urlcode/vercel` and
 `@jimhoyd/urlcode/aws` serve declarative projects as native handlers;
 `urlcode build --target cloudflare` compiles redirects and declared responses
-into a Worker. Each target refuses at activation or build time what it cannot
+into a Worker; `urlcode build --target static` compiles redirects and static
+files into plain objects and redirect metadata for S3 + CloudFront, with no
+server at all. Each target refuses at activation or build time what it cannot
 run, with the route named. None has been exercised on its provider yet; the
 adapters have local conformance tests only. [Operations](docs/OPERATIONS.md),
 [capabilities](docs/CAPABILITIES.md), [Vercel](docs/VERCEL.md), [AWS](docs/AWS.md),
-[Cloudflare](docs/CLOUDFLARE.md).
+[Cloudflare](docs/CLOUDFLARE.md), [static hosting](docs/STATIC.md).
 
 ## For AI agents
 
@@ -244,10 +256,11 @@ inspection, validation and conversion previews over stdio, and
 
 ## Documentation
 
-Full documentation lives in
-[urlcode-docs](https://github.com/jimhoyd-com/urlcode-docs). It is authored
-there directly, not generated from this repository, and it is where new guides,
-references and recipes belong.
+Full documentation is authored in a separate `urlcode-docs` repository, where
+new guides, references and recipes belong — but that repository is currently
+private, so its content isn't publicly browsable yet. Until it's made public,
+the practical reference is this README and [`docs/`](docs/README.md) in this
+repository.
 
 `docs/` in this repository is contributor and maintainer material — local
 development, CI, the release process, reviews and the generated field
@@ -256,11 +269,11 @@ reference. Reader-facing pages still under `docs/` are being migrated.
 ## Built with URLCode
 
 [urlcode-short](https://github.com/jimhoyd-com/urlcode-short), an
-account-free short-link demo with a shadcn/ui front end, and
-[urlcode-docs](https://github.com/jimhoyd-com/urlcode-docs), a static
-documentation site rendered through sandboxed middleware at build time. Both are
-ordinary consumers of the public runtime; their retrospectives list what the
-runtime supplied and what they still had to build.
+account-free short-link demo with a shadcn/ui front end, and `urlcode-docs`, a
+static documentation site rendered through its own sandbox-opted-in middleware
+at build time (currently a private repository). Both are ordinary consumers of
+the public runtime; urlcode-short's retrospective lists what the runtime
+supplied and what it still had to build.
 
 ## License and contributing
 

package/ROADMAP.md

@@ -1,7 +1,8 @@
 # Public roadmap
 
 URLCode is a portable runtime for programmable URL behavior, not a URL
-shortener. Live links are one handler in the broader project contract. The
+shortener. Stored short links are an operator-installed extension, not a core
+handler. The
 [project direction](docs/PROJECT-DIRECTION.md) explains how application
 projects and provider adapters fit without redefining or restricting the free
 runtime.
@@ -11,7 +12,37 @@ separate late phase. The stable 0.1 self-hosted release covers much of M0/M1 plu
 process/container packaging and benchmarks. Provider adapters and the remaining
 production-readiness gates remain open.
 
-## 0.4.0-alpha.1 — current alpha
+## 0.4.0-alpha.2 — current alpha
+
+`0.4.0-alpha.2` is a behavior-changing release on top of `0.4.0-alpha.1`:
+**`function` and `middleware` routes now run trusted and unsandboxed by
+default** — in the host process, with full Node/filesystem/network access,
+exactly like any other project code — instead of always dispatching through
+the QuickJS/WebAssembly worker pool. Sandboxing is now an explicit per-route
+opt-in via `sandbox: true`; a route that declares it gets exactly the
+isolation every earlier alpha provided, unchanged. See
+[docs/SPIKE-DEFAULT-TRUST-MODEL.md](docs/SPIKE-DEFAULT-TRUST-MODEL.md) for
+the maintainer's decision and rationale, and
+[docs/FUNCTION-SECURITY.md](docs/FUNCTION-SECURITY.md) for the resulting
+contract of both execution modes.
+
+**This changes existing projects with no YAML edit.** Every `function`/
+`middleware` route that does not declare `sandbox` — which, before this
+release, meant every such route in every existing project — now runs trusted
+instead of sandboxed the moment the runtime is upgraded to `0.4.0-alpha.2` or
+later. Binding grants (`env`/`secrets`) are unaffected: a route still
+receives only what it declares and an operator policy pins to the project
+revision, whether trusted or sandboxed. Review which of your project's
+`function`/`middleware` routes handle input or code you would not otherwise
+trust with full Node/filesystem/network access, and add `sandbox: true` to
+those specifically (docs/AI-AUTHORING.md's "Deciding when a route needs
+`sandbox: true`") before upgrading a project that relies on the old,
+always-sandboxed behavior. An operator policy pinned to a project's revision
+is invalidated by this upgrade regardless of whether the project's own YAML
+changed, since the project hash includes the trust-model-affecting change;
+re-derive and re-approve it (`urlcode permissions`) after upgrading.
+
+## 0.4.0-alpha.1
 
 `0.4.0-alpha.1` is the first alpha of the extension contract and the agent
 tooling on top of the `0.3.0` self-hosted release. It carries: the
@@ -86,8 +117,10 @@ signals. See [conditions](docs/CONDITIONS.md), [egress](docs/EGRESS.md),
 
 Bundled Git-owned recipes, safe bulk imports into route includes, build-time
 TypeScript guest transpilation, read-only inspection APIs and optional stdio
-MCP tooling are available. The runtime still executes only JavaScript inside
-QuickJS/WASM; TypeScript authoring does not add host execution. Bulk benchmarks
+MCP tooling are available. The runtime still executes only JavaScript, and
+TypeScript authoring adds no execution mode: transpilation happens at build
+time, is not type checking, and a `sandbox: true` route's emitted JavaScript
+runs inside QuickJS/WASM exactly as before. Bulk benchmarks
 successfully cover 1,000, 10,000 and 100,000 routes without relaxing parser
 limits. See [recipes](docs/RECIPES.md), [bulk evidence](docs/BULK.md),
 [TypeScript authoring](docs/TYPESCRIPT-AUTHORING.md) and
@@ -140,9 +173,10 @@ deployment returns byte-identical status, body and headers to the self-hosted
 server. Bindings arrive through a `URLCODE_POLICY` environment variable holding
 the same revision-pinned grant document the operator policy file carries.
 
-Native handlers only: isolated functions, middleware and stored live links are
-refused at activation, because every cold start would pay worker and WASM
-startup and a serverless filesystem cannot hold a durable link store. The
+Native handlers only: `function` and `middleware` routes are refused at
+activation, trusted or sandboxed alike, because they need the self-hosted Node
+lifecycle and a sandboxed one would pay worker and WASM startup on every cold
+start. The
 `@jimhoyd/urlcode/aws` does the same for a Lambda Function URL or API Gateway HTTP API.
 Payload format 2.0 only: format 1.0 supplies an already-decoded path and query,
 and this runtime rejects ambiguous encoding deliberately, so rebuilding a target
@@ -161,7 +195,7 @@ generation, so it gets a compiler rather than an adapter: `urlcode build
 validators, and `@jimhoyd/urlcode/cloudflare` serves them with the same matching, request
 policy and response policy as every other host. Declarative routes only —
 redirects and declared responses with parameters, defaults, validation, response
-headers, `enabled` and `expires`. Functions, middleware, stored links, assets and
+headers, `enabled` and `expires`. Functions, middleware, assets and
 bindings are refused at build time with the route named, so an unsupported
 project fails the build instead of the deployment. Bindings are refused even as
 literals, because a build artifact must never carry a secret.
@@ -202,18 +236,25 @@ does not cover.
 
 ## Hardening checkpoint — alpha.8
 
-Bound HTTP admission and inactive sockets, drain accepted link writes on shutdown,
-reject invalid store metadata, and correct management defaults/method responses.
+Bound HTTP admission and inactive sockets, and correct management
+defaults/method responses.
 The [readiness register](docs/RELEASE-READINESS.md) distinguishes tested safeguards
 from deployment and stable-release gates. Feature breadth does not imply stability.
 
-## Live short links — alpha.8
+## Live short links — alpha.8 (removed from core, superseded)
 
 Implemented an optional native `link` handler, local SQLite persistence, CLI CRUD
-and a separate authenticated management API. Links become visible without YAML
-changes/reloads; versioned writes prevent silent lost updates. No guest storage
-or network access is added. Same-host only; distributed storage, general state,
-user accounts and provider adapters remain open. See [dynamic links](docs/DYNAMIC-LINKS.md).
+and a separate authenticated management API. Links became visible without YAML
+changes/reloads; versioned writes prevented silent lost updates. No guest storage
+or network access was added. Same-host only; distributed storage, general state,
+user accounts and provider adapters remained open.
+
+This native `link` handler, its SQLite store, CLI and management API were
+removed from core in the layering work that followed: stored short links are
+moving to a future `urlcode-dynamic-link` extension package (mount-based, like
+`auth`/`admin`, not yet published). A project that used `link`/`dynamicLinks`
+needs that extension once it ships; there is no in-core replacement or
+deprecation shim.
 
 ## Middleware — alpha.7
 
@@ -254,13 +295,17 @@ Bulk tools, recipes and best-effort signals were added in the unreleased next-ph
 
 ## Security correction — 0.1.0-alpha.2
 
+<!-- trust-model-prose: historical -->
 All function code is untrusted. Node host execution has been replaced by
 QuickJS/WebAssembly isolation with fresh invocation state, no ambient host or
 network APIs, bounded resources, restricted module graphs and revision-pinned
 operator binding policy. This protection is part of the free product. See the
 [security model](docs/FUNCTION-SECURITY.md). Full Fetch/Node
 API compatibility and network integrations were not part of that alpha and
-remain outside the 0.1 contract.
+remain outside the 0.1 contract. That default was superseded in
+`0.4.0-alpha.2`, which made this isolation the per-route `sandbox: true`
+opt-in instead (see
+[docs/SPIKE-DEFAULT-TRUST-MODEL.md](docs/SPIKE-DEFAULT-TRUST-MODEL.md)).
 
 ## Earlier implementation checkpoint — 0.1.0-alpha.1
 

package/SECURITY.md

@@ -1,13 +1,28 @@
 # Security
 
-Application functions are **untrusted by default**. Alpha.2 replaces direct Node
-execution with QuickJS/WebAssembly isolation. Worker threads alone are not the
-security boundary. There is no unrestricted host-execution fallback.
-
-Guests have no Node, filesystem, shell, network or ambient process-environment
-access. Each invocation gets fresh state and bounded resources. Imports stay
-inside a snapshotted project module graph. Binding grants come from operator
-policy outside the project and are pinned to the configuration/code revision.
+Project `function`/`middleware` code is **trusted and unsandboxed by default**:
+it runs directly in the host process, exactly like any other project code,
+with full Node, filesystem and network access (docs/SPIKE-DEFAULT-TRUST-MODEL.md).
+A route opts into isolation explicitly with `sandbox: true`, which dispatches
+that route through the QuickJS/WebAssembly worker pool instead — unchanged
+from the isolation this project has always provided, still the boundary to
+reach for when a route's code specifically warrants it (input from a source
+the project doesn't fully trust, a contribution nobody has reviewed, logic
+handling an especially sensitive secret).
+
+A `sandbox: true` guest has no Node, filesystem, shell, network or ambient
+process-environment access. Each invocation gets fresh state and bounded
+resources. Imports stay inside a snapshotted project module graph. Binding
+grants — for a trusted route as much as a sandboxed one — come from operator
+policy outside the project and are pinned to the configuration/code revision;
+trusting a route's code by default does not grant it any `env`/`secrets` it
+was not explicitly declared and pinned to receive. This is a claim about what
+URLCode injects into `context.env`/`context.secrets` for a route, not an
+access-control boundary on trusted code itself: a trusted (non-`sandbox`)
+route runs with full Node access by design, so its own code can read
+`process.env`, the filesystem or the network independently of anything the
+binding grant declared or withheld. The grant only governs what URLCode hands
+that code through `context`; it is not a restriction the code is confined to.
 See the [security model and policy instructions](docs/FUNCTION-SECURITY.md).
 
 The host/runtime and sandbox engine still require patching, independent review