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

package/docs/{USABILITY-REVIEW.md → archive/2026-09-19/USABILITY-REVIEW.md}

@@ -1,3 +1,13 @@
+# Historical record
+
+Archived 2026-09-19. This records an earlier implementation or proposal, not
+current instructions. See the [current roadmap](../../../ROADMAP.md),
+[current contract](../../SPECIFICATION.md) and [open decisions](../../OPEN-DECISIONS.md).
+Remaining acceptance work is not declared complete by archiving this record.
+
+<!-- trust-model-prose: historical-file -->
+<!-- guidance-claims: ignore-file -->
+
 # Usability review: URLCode against the tools people reach for instead
 
 Status: an honest assessment written 2026-09-18 against the source in the four
@@ -10,12 +20,12 @@ that would matter most. It does not change any contract by itself.
 > execution mode. Where the table below credits functions and middleware with
 > isolation, that now describes a route declaring `sandbox: true`; the default
 > is trusted, in-process execution with full Node, npm and filesystem access.
-> See [SPIKE-DEFAULT-TRUST-MODEL.md](SPIKE-DEFAULT-TRUST-MODEL.md).
+> See [SPIKE-DEFAULT-TRUST-MODEL.md](../../SPIKE-DEFAULT-TRUST-MODEL.md).
 
 ## 1. Who the competitors are, by rung
 
 URLCode is not one product; it competes with a different tool on each rung
-of [the ladder](FRAMEWORK.md#the-ladder).
+of [the ladder](../../FRAMEWORK.md#the-ladder).
 
 | Rung | What people use today | Where URLCode is better | Where it is worse today |
 |---|---|---|---|

package/docs/archive/README.md

@@ -0,0 +1,27 @@
+# Historical records
+
+These documents retain earlier reasoning and evidence. They are not authoring
+instructions or an active backlog. Read [the current roadmap](../../ROADMAP.md),
+[open decisions](../OPEN-DECISIONS.md) and [implemented contract](../SPECIFICATION.md)
+first. An old example can describe a removed feature or an earlier trust model.
+
+Archived on 2026-09-19 after checking the current code:
+
+| Record | Why archived | Current owner of remaining work |
+|---|---|---|
+| [Monorepo spike](2026-09-19/SPIKE-MONOREPO.md) | The migration it proposed is complete: ui, auth and admin are workspace packages and all three have been released from this repository | [Development pipeline](../DEVELOPMENT-PIPELINE.md) and [release security](../RELEASE-SECURITY.md) |
+| [Previous roadmap](2026-09-19/ROADMAP.md) | Release chronology mixed with current planning | Current roadmap and release readiness |
+| [Detailed phases](2026-09-19/NEXT-STEPS.md) | Most authoring/tooling/UI work delivered; repeated stale backlog | Current roadmap, issues and open decisions |
+| [Previous decisions](2026-09-19/OPEN-DECISIONS.md) | Mixed settled releases, obsolete repository counts and live questions | Current open decisions |
+| [Next-phase implementation](2026-09-19/NEXT-PHASE-PLAN.md) | Delivered source snapshot for alpha.1 | Specification and provider evidence |
+| [Extension delivery sequence](2026-09-19/EXTENSION-IMPLEMENTATION.md) | Registration, auth/admin and UI now implemented | Package status files and core issue 58 |
+| [Policy/extension exploration](2026-09-19/SPIKE-EXTENSIONS.md) | Main design delivered; obsolete link APIs | Policies, plugins and extensions guides |
+| [Extension model review](2026-09-19/SPIKE-EXTENSION-MODEL.md) | Historical design rationale | Current extension contract |
+| [Usability review](2026-09-19/USABILITY-REVIEW.md) | Predates trusted execution and retired packages | New benchmark observations |
+| [Management security](2026-09-19/MANAGEMENT-SECURITY.md) | Describes the removed core link-management API | No current core replacement |
+
+Open proposals stay outside the archive with their status stated at the top.
+The accepted trust-by-default decision remains directly linked from the current
+security contract; its `SPIKE-` filename is retained for existing references.
+Security audits and operational evidence remain available: “implemented” never
+means their unperformed review, deployment or recovery work is complete.

package/docs/policies/agents.md

@@ -65,7 +65,7 @@ Matching is string matching. A client can claim any `User-Agent`, and the
 genuine search crawlers publish the way to check a claim (reverse DNS for
 Googlebot, bingbot and Applebot; the IETF `web-bot-auth` HTTP Message
 Signature drafts for newer agents). That verification needs network calls and
-vendor data, so it belongs in a [host plugin](../SPIKE-EXTENSIONS.md) that
+vendor data, so it belongs in a [host plugin](../archive/2026-09-19/SPIKE-EXTENSIONS.md) that
 runs after this policy, not in the runtime.
 
 ## Bundled lists

package/docs/policies/compression.md

@@ -1,8 +1,9 @@
 # Compression policy
 
 `policies.compression` negotiates a content coding (RFC 9110 §12.5.3) on the
-host, outside the sandbox, for every result a route produces: `respond`
-bodies, function results, asset responses, cache hits and early denials.
+host, outside function/middleware execution — trusted or sandboxed alike — for
+every result a route produces: `respond` bodies, function results, asset
+responses, cache hits and early denials.
 It runs last in the response phase, after the cache store and the security
 headers, so every header it reads is final. Asset snapshots are compressed
 once at load and served by reference (the NGINX `gzip_static` / Caddy

package/docs/policies/security.md

@@ -1,7 +1,8 @@
 # Security headers policy
 
-`policies.security` adds response security headers on the host, outside the
-sandbox, to every result a route produces: redirects, `respond` bodies,
+`policies.security` adds response security headers on the host, outside
+function/middleware execution -- trusted or sandboxed alike -- to every result
+a route produces: redirects, `respond` bodies,
 function results, asset responses, cache hits and early denials from the
 `agents` and `throttle` policies. Values are the OWASP Secure Headers
 Project best-practice recommendations (OSHP 2024 best practices,

package/examples/assets/example.yaml

@@ -14,4 +14,4 @@ tests:
     - node src/cli.ts audit --project examples/assets --expect-routes 5
 behavior:
   - native page, static and download routes serve snapshotted files with explicit caching
-  - one sandboxed function shows the two kinds of route side by side
+  - one trusted function shows the two kinds of route side by side

package/examples/cookbook/route-index.json

@@ -367,7 +367,7 @@
         "bindings",
         "auth"
       ],
-      "description": "HTTP Basic authentication decoded inside the guest"
+      "description": "HTTP Basic authentication decoded in trusted middleware"
     },
     {
       "path": "/cors/data",

package/examples/cookbook/routes/middleware.yaml

@@ -12,7 +12,7 @@ routes:
         export: bearer
     respond: {json: {private: true}}
   /admin/panel:
-    description: HTTP Basic authentication decoded inside the guest
+    description: HTTP Basic authentication decoded in trusted middleware
     env:
       ADMIN_USER: {value: admin}
       ADMIN_PASSWORD: {value: cookbook-password}

package/examples/prerender/README.md

@@ -1,8 +1,15 @@
 # Prerender a dynamic project into a native static one
 
 Three pages rendered by a function and one shared template middleware, then
-rendered once at build time into a project that serves the same bytes with
-native `page` routes and no sandbox on the request path.
+rendered once at build time into a project that serves the same bytes with no
+code on the request path at all.
+
+The source routes run trusted and in-process, which is the default for
+`function`/`middleware` and the right choice here: the page code is reviewed
+first-party code that reads nothing but the literal arguments in
+`urlcode.yaml`. Prerendering does not depend on that — a route declaring
+`sandbox: true` prerenders the same way — and either way the generated project
+runs no code at all.
 
 From the runtime checkout:
 
@@ -15,17 +22,18 @@ node src/cli.ts audit --project /absolute/out --expect-routes 3
 ```
 
 The same three URLs answer identically before and after. The difference is what
-runs to serve them: the source project runs function and middleware code per
-request, the generated project reads a prevalidated byte buffer.
+runs to serve them: the source project executes the function and its middleware
+per request, the generated project reads a prevalidated byte buffer and runs no
+project code at all.
 
 | | Source project | Generated project |
 |---|---|---|
 | Handlers | 3 × `function` | 3 × `page` |
 | Middleware | shared template | none |
-| Guest execution per request | yes | none |
+| Project code per request | function + middleware | none |
 | Content | reviewed literals in YAML | rendered HTML files |
 
-`prerender.mjs` is operator build tooling that runs in Node, not guest code. The
+`prerender.mjs` is operator build tooling, not a route handler. The
 orchestration lives in the runtime's build helper:
 
 ```js

package/examples/prerender/functions/page.mjs

@@ -1,6 +1,8 @@
 // One page's content, supplied as reviewed literal arguments in urlcode.yaml.
-// This runs in the QuickJS/WASM sandbox with no filesystem, network or host
-// code, at build time exactly as it would at request time.
+// This runs trusted and in-process -- the default for a function route -- at
+// build time exactly as it would at request time. It reads nothing but its
+// own args, so there is nothing here for `sandbox: true` to isolate; adding it
+// would cost worker-pool capacity for no gain.
 export function page(request, {args}) {
   return new Response(args.body, {headers: {'content-type': 'text/html; charset=utf-8'}});
 }

package/examples/prerender/middleware/template.mjs

@@ -22,7 +22,7 @@ export async function template(request, context, next) {
 <h1>${title}</h1>
 ${content}
 </main>
-<footer>Prerendered at build time. No guest code runs to serve this page.</footer>
+<footer>Prerendered at build time. No project code runs to serve this page.</footer>
 </body>
 </html>
 `, {status: response.status, headers: {'content-type': 'text/html; charset=utf-8'}});

package/examples/prerender/prerender.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // Prerender recipe: render this project's function/middleware routes once, at
 // build time, into a native page project that serves the same bytes with no
-// guest execution on the request path.
+// project code on the request path.
 //
 // The orchestration that is easy to get wrong — runtime lifecycle, response
 // validation, budgets, byte fidelity and output-path safety — lives in the

package/examples/prerender/urlcode.yaml

@@ -2,6 +2,10 @@ version: "1"
 # The dynamic source of the site. Every page is a function response wrapped by
 # one shared template middleware, so `dev` serves it live while you edit. The
 # prerender recipe renders these routes once and emits a native page project.
+# No route declares `sandbox: true`: this is reviewed first-party code taking
+# literal arguments from this file, which is the trusted default's case, not an
+# exception to it (docs/AI-AUTHORING.md, "Deciding when a route needs
+# `sandbox: true`").
 routes:
   /:
     description: Home page rendered by a function and the shared template
@@ -16,7 +20,7 @@ routes:
         body: |
           <p>This page is generated by a function and wrapped by shared template
           middleware. Running the prerender recipe turns it into a native page
-          route that serves the same bytes with no sandbox on the request path.</p>
+          route that serves the same bytes with no code on the request path.</p>
           <ul>
             <li><a href="/guide">Guide</a></li>
             <li><a href="/about">About</a></li>
@@ -32,9 +36,9 @@ routes:
       args:
         title: Guide
         body: |
-          <p>Content is reviewed literal input in YAML. Guest code never reads the
-          filesystem, so a larger site generates this project from host-prepared
-          content before rendering.</p>
+          <p>Content is reviewed literal input in YAML rather than anything this
+          code goes and reads, so a larger site generates this project from
+          host-prepared content before rendering.</p>
   /about:
     description: A third page proving the template is shared, not copied
     middleware:

package/llms-full.txt

@@ -1,5 +1,5 @@
 <!-- Generated by scripts/build-llms-full.ts (npm run docs:llms). Do not edit; edit the source documents. -->
-<!-- Consolidated URLCode authoring reference: 15 documents, about 47,012 tokens (estimate: characters / 4). -->
+<!-- Consolidated URLCode authoring reference: 15 documents, about 48,160 tokens (estimate: characters / 4). -->
 
 # URLCode
 
@@ -100,9 +100,9 @@ Each rung's YAML is valid on every rung above it.
    project copy, template and stylesheet overrides for kit-rendered pages.
 
 Stored short links previously sat here as a native `link` route; that handler
-was removed from core. A future `urlcode-dynamic-link` package (not yet
-published, so this one line is the exception to "nothing is roadmap" above)
-is expected to own them the same way `auth`/`admin` own their mounts.
+was removed from core. A `urlcode-dynamic-link` package owned them the same way
+`auth`/`admin` own their mounts, but it has been retired and unpublished; no
+package occupies this rung today.
 
 Rungs 1 to 3 need only the core package. Rungs 4 to 6 need the extension
 packages, installed from npm as `0.1.0-alpha.x` prereleases, and a Node host
@@ -118,9 +118,9 @@ npm install @jimhoyd/urlcode @jimhoyd/urlcode-ui @jimhoyd/urlcode-auth @jimhoyd/
 urlcode init my-site --with auth,admin
 ```
 
-Installing from npm is the normal path; the extension repositories'
-`pack-sources.mjs` still builds local tarballs from a reviewed checkout for
-operators who install only source they have read. Three files make an extended
+Installing from npm is the normal path; `scripts/pack-sources.mjs` still builds
+local tarballs from a reviewed checkout for operators who install only source
+they have read — one revision now covers core and every extension. Three files make an extended
 project. Nothing else is discovered by convention.
 
 ```
@@ -152,7 +152,8 @@ routes:
         auth: {}
 ```
 
-The operator host wires the packages, once, in code the project cannot reach:
+The operator host explicitly registers the packages. Registration is an
+activation boundary; it does not isolate trusted application code from the host:
 
 ```js
 import { createUiExtension } from '@jimhoyd/urlcode-ui/host';
@@ -172,12 +173,12 @@ export default {
 };
 ```
 
-Auth and admin pages currently render through the shared primitives and a
-`presentation` (catalogue and `--ui-*` theme variables). The `ui` extension
-serves the template kit and its assets for pages an extension renders through
-`ui.kit`; moving the auth and admin screens onto the kit is a listed remaining
-item in the ui repository, so today one `presentation` restyles them and the
-`ui` block is optional.
+Auth and admin already render their screens through `ui.kit` when the host
+supplies the UI extension; their package-owned templates and catalogues must be
+registered with that kit. Without it, both retain shared primitive rendering
+through `presentation`. The example above uses that primitive fallback. The UI
+block is optional, and a migration to the kit is not unfinished framework work.
+See each package README for its complete kit registration example.
 
 ```sh
 urlcode serve --project /absolute/site --host-file /absolute/operator/host.mjs --origin https://site.example
@@ -199,7 +200,8 @@ or mounts changes the revision and needs an explicit operator reapproval.
 These are the facts that keep generated projects valid. The full matrix is in
 [AI authoring](https://github.com/jimhoyd-com/urlcode/blob/main/docs/AI-AUTHORING.md); this is the short list.
 
-- **YAML never names code, packages, databases or credentials.** Extensions are
+- **Extension YAML names logical extensions, not host packages or credentials.**
+  Function and middleware `source` fields do name project modules. Extensions are
   logical names; the host file chooses the implementation. There is no
   `--extension` flag, no `import` in YAML, no interpolation.
 - **One handler per route.** `redirect`, `respond`, `page`, `static`, `download`,
@@ -210,13 +212,15 @@ These are the facts that keep generated projects valid. The full matrix is in
   It runs in-process with full Node access unless the route declares
   `sandbox: true`, which isolates it to a text/JSON `Request`/`Response`
   subset, validated `args` and granted `env`, with no `fetch`, Node,
-  filesystem or timers. Either way, `args`/`env`/`secrets` are exactly what
+  filesystem or general network access; bounded timers are available. Either way, `args`/`env`/`secrets` are exactly what
   the route declares and an operator grants — trust changes where code runs,
   not what it is handed. See docs/SPIKE-DEFAULT-TRUST-MODEL.md and
   docs/FUNCTION-SECURITY.md.
 - **Authentication is host processing.** Do not build login forms, session
-  cookies or password checks in functions. Declare `policies.extensions.auth`
-  on the route; the runtime withholds `Cookie` and `Authorization` from guests.
+  cookies or password checks in functions. With the auth extension declared,
+  prefer `auth: true` or `auth: {role: admin}`; these expand to
+  `policies.extensions.auth`. The runtime filters credential headers passed to
+  application handlers. This is not a security boundary against trusted Node code.
 - **Everything is validated before it runs.** `urlcode validate --local`,
   `urlcode test`, `urlcode audit --expect-routes N`. Unsupported features fail
   with the route named; nothing degrades silently.
@@ -238,7 +242,7 @@ These are the facts that keep generated projects valid. The full matrix is in
 | Add accounts | [auth README](https://github.com/jimhoyd-com/urlcode-auth#readme), [auth security](https://github.com/jimhoyd-com/urlcode-auth/blob/main/SECURITY.md) |
 | Add administration | [admin README](https://github.com/jimhoyd-com/urlcode-admin#readme) |
 | Restyle every page | [ui README](https://github.com/jimhoyd-com/urlcode-ui#readme), [ui contract](https://github.com/jimhoyd-com/urlcode-ui/blob/main/CONTRACT.md) |
-| Write an extension | [extensions](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md), [extension model review](https://github.com/jimhoyd-com/urlcode/blob/main/docs/SPIKE-EXTENSION-MODEL.md) |
+| Write an extension | [extensions](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md), [extension model review](https://github.com/jimhoyd-com/urlcode/blob/main/docs/archive/2026-09-19/SPIKE-EXTENSION-MODEL.md) |
 | Run it | [operations](https://github.com/jimhoyd-com/urlcode/blob/main/docs/OPERATIONS.md), [install](https://github.com/jimhoyd-com/urlcode/blob/main/docs/INSTALL.md), [deployment checks](https://github.com/jimhoyd-com/urlcode/blob/main/docs/DEPLOYMENT-CHECKS.md) |
 
 ---
@@ -353,7 +357,7 @@ The benchmark operates locally; it is not a load test of an external deployment.
 | Parameter validation and JSON body syntax checks | Full OpenAPI or JSON Schema validation of request bodies |
 | Local test/audit/benchmark | Route-local YAML tests, managed monitoring, production load certification |
 | Local/self-hosted runtime; limited AWS/Vercel/Cloudflare implementations with local tests | Verified provider deployments or full cross-provider parity |
-| File authoring and snapshot reload | General guest storage broker; stored short links (moving to a future `urlcode-dynamic-link` extension package, not yet published) |
+| File authoring and snapshot reload | General guest storage broker; stored short links (no supported package; the `urlcode-dynamic-link` extension was retired) |
 | Optional host `policies` (`throttle`, `agents`, `security`, `compression`, `cache`) and reusable `profiles` | Plugins named in YAML, shared multi-instance counters, CORS, verified-bot checks |
 | Optional top-level `site` (`robots`, `sitemap`, `favicon`, `securityTxt`, `llms`) generating native routes | Per-route `noindex` field, sitemap index files, `humans.txt`, signed `security.txt` |
 
@@ -487,9 +491,12 @@ Put that justification where tooling can see it, not only in a source
 comment: an optional `sandboxReason` string on the route (up to 500
 characters, `schemas/urlcode.schema.json`) records why a route needs
 isolation, or why it is safe to trust, regardless of whether `sandbox` is
-`true` or `false`. `urlcode explain`/`context` surface it next to the
-route's `sandbox` boolean, so the trust decision has a reviewable trail
-without reading every route's source file:
+`true` or `false`. `urlcode explain`/`context`, the manifest and the
+`routes` inventory all surface it next to the route's `sandbox` boolean —
+per route, not per handler, so a native handler that runs `middleware`
+reports its execution mode too, and `routes --compare` shows a flip between
+trusted and sandboxed execution as a changed route. The trust decision has a
+reviewable trail without reading every route's source file:
 
 ```yaml
 routes:
@@ -570,8 +577,9 @@ trust (adding `sandbox: true` without saying why, or relying on the trusted
 default for code that plainly needed isolation) to work around them.
 
 There is no native `link` handler or `dynamicLinks` project flag; both were
-removed. Report a request for live stored links as a gap pending the future
-`urlcode-dynamic-link` extension package rather than inventing a `link` field.
+removed. The `urlcode-dynamic-link` extension package that briefly owned them
+has been retired and unpublished, so there is no supported replacement. Report a
+request for live stored links as a gap rather than inventing a `link` field.
 
 See [capabilities and normalized route representation](https://github.com/jimhoyd-com/urlcode/blob/main/docs/CAPABILITIES.md) for the target catalog,
 programmatic compatibility analysis and provider verification limits.
@@ -1255,10 +1263,10 @@ keys preserve repeated values. Headers are forwarded only through explicit maps.
 ### Stored links
 
 Core has no native `link` handler or `dynamicLinks` project flag; both were
-removed. Stored short links are moving to a future `urlcode-dynamic-link`
-extension package (mount-based, like `auth`/`admin`), not yet published. A
-project needing them declares an `extension` mount once that package exists;
-there is no in-core replacement or deprecation shim for `link`/`dynamicLinks`.
+removed. The `urlcode-dynamic-link` extension package that replaced them has
+been retired and unpublished, so a project needing stored short links owns that
+storage itself; there is no in-core replacement or deprecation shim for
+`link`/`dynamicLinks`.
 
 ### Functions
 
@@ -1426,7 +1434,9 @@ are local Git-owned examples; they grant no capabilities. [Build-time TypeScript
 is separate from runtime execution.
 
 The [tooling SDK and optional local MCP](https://github.com/jimhoyd-com/urlcode/blob/main/docs/TOOLING.md) inspect and validate without
-executing handlers or reading binding values. [Provider conformance](https://github.com/jimhoyd-com/urlcode/blob/main/docs/PROVIDER-VERIFICATION.md)
+executing handlers or reading binding values. MCP defaults to inspection; the
+explicit `--allow-authoring` option enables bounded project writes, separately
+from host-file loading and grants. [Provider conformance](https://github.com/jimhoyd-com/urlcode/blob/main/docs/PROVIDER-VERIFICATION.md)
 distinguishes local adapter replay from actual deployment observations; no real
 provider deployment is implied by CI. [Proxy and signal egress](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EGRESS.md) requires
 external revision-pinned operator grants and bounded host-owned transport;
@@ -1539,10 +1549,9 @@ any per-visitor session record. Git owns route behavior and code; user-created r
 their own persistence, backup and export lifecycle.
 
 Core has no native handler for this today: the `link` handler that implemented
-it was removed. Stored short links are moving to a future
-`urlcode-dynamic-link` extension package (mount-based, like `auth`/`admin`,
-not yet published); a project needing them declares an `extension` mount once
-that package exists.
+it was removed. The `urlcode-dynamic-link` extension package that replaced it
+has been retired and unpublished, so a project needing stored short links owns
+that storage itself.
 
 Functions still cannot access databases, the filesystem or network directly.
 General application state and realtime sessions remain future work.
@@ -1790,7 +1799,8 @@ Source: https://github.com/jimhoyd-com/urlcode/blob/main/docs/ASSETS.md
 
 Native file handlers are implemented in 0.1.0-alpha.3. They work in the local
 Node runtime and self-hosted process/container. Provider adapters remain planned.
-They do not run user functions or expose filesystem APIs to sandboxed code.
+They do not run user functions or expose filesystem APIs to guest code, trusted
+or sandboxed.
 
 ```yaml
 version: "1"
@@ -1902,9 +1912,10 @@ Source: https://github.com/jimhoyd-com/urlcode/blob/main/docs/POLICIES.md
 Policies are host-enforced behavior declared in YAML around a route: a
 per-client request budget, a User-Agent deny list, a security-header profile,
 content-coding negotiation and an HTTP caching strategy. They run in the host
-process, outside the sandbox, so they can see the client address, keep counters
-across requests and touch the transport, which route middleware by design
-cannot ([middleware](https://github.com/jimhoyd-com/urlcode/blob/main/docs/MIDDLEWARE.md), [function security](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FUNCTION-SECURITY.md)).
+process, outside function/middleware execution — trusted or sandboxed alike —
+so they can see the client address, keep counters across requests and touch
+the transport, which route middleware by design cannot
+([middleware](https://github.com/jimhoyd-com/urlcode/blob/main/docs/MIDDLEWARE.md), [function security](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FUNCTION-SECURITY.md)).
 
 Everything here is optional and off by default. A project with no `policies`
 key and no `profiles` key behaves exactly as before: no policy module is
@@ -1919,7 +1930,7 @@ compiled and the request path is unchanged. Each policy has its own page:
 | `cache` | [cache](https://github.com/jimhoyd-com/urlcode/blob/main/docs/policies/cache.md) | Named strategies from RFC 9111/5861/8246/9213 plus an origin memory cache |
 
 The design and the reasoning behind each choice are in the
-[extensions spike](https://github.com/jimhoyd-com/urlcode/blob/main/docs/SPIKE-EXTENSIONS.md). Operators who need behavior the
+[extensions spike](https://github.com/jimhoyd-com/urlcode/blob/main/docs/archive/2026-09-19/SPIKE-EXTENSIONS.md). Operators who need behavior the
 declarative block cannot express pass host [plugins](https://github.com/jimhoyd-com/urlcode/blob/main/docs/PLUGINS.md) in code; plugins
 are never named in YAML.
 
@@ -1941,7 +1952,14 @@ routes:
 `policies` at the top level sets project defaults; `routes.<path>.policies`
 adjusts them for one route. Two route-level short forms exist. `auth`
 expands to `policies.extensions.auth` when the project declares an auth
-[extension](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md). `cache: {strategy, maxAge, ...}` expands to
+[extension](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md), carrying the same keys minus `required`;
+`required: false` documents the intent and emits no policy. It accepts
+`required`, `role`, `permission`, `verified`, `freshWithinSeconds` and
+`onDeny` and nothing else — `role` is singular, and there is no `roles`. Like
+`cache` below, it is refused rather than silently ignored in three cases: when
+the project declares no `extensions.auth`, when the route also sets
+`policies.extensions.auth` (use one form), and when the route sets
+`policies.extensions: false`. `cache: {strategy, maxAge, ...}` expands to
 `policies.cache` the same way — the compiler merges it into that route's
 `policies` before anything else reads the project, so `routes`, `audit` and
 `explain` see only the expanded long form, and it is refused alongside a
@@ -2477,10 +2495,11 @@ and admin implementations live in `urlcode-auth` and `urlcode-admin`; the runtim
 supplies only the generic integration contract. No project file can import a host
 extension or choose its npm package.
 
-Stored short links are moving out of core this way too: a future
-`urlcode-dynamic-link` package (mount-based, like `auth`/`admin`, not yet
-published) will own the durable link store, its CLI and management API. Core
-no longer has a native `link` handler or a `dynamicLinks` project flag.
+Stored short links moved out of core this way too: a `urlcode-dynamic-link`
+package (mount-based, like `auth`/`admin`) owned the durable link store, its CLI
+and management API. That package has since been retired and unpublished, so no
+supported stored-link extension ships today. Core no longer has a native `link`
+handler or a `dynamicLinks` project flag.
 
 A project declares versioned configuration and exclusive route mounts:
 
@@ -2727,7 +2746,16 @@ each half of a hook's `sandbox: true` opt-in has its own answer:
   or provided: this is ordinary first-party project code, and the
   extension's own `activate()` already has `ExtensionActivation.root` to
   resolve the hook's `source` against and can `import()` it directly, the
-  same way any trusted `function`/`middleware` route does.
+  same way any trusted `function`/`middleware` route does. Do that import
+  with a per-activation cache-busting query, the way core's own trusted
+  route activation does (`src/trusted-functions.ts`): Node's ESM loader
+  caches a resolved module forever by URL, so a plain `import()` of the
+  unchanged file URL makes a second activation in the same process keep
+  serving the hook code that was on disk at the first one
+  (jimhoyd-com/urlcode#198). Only the hook's **entry** module is refreshed
+  this way — modules the hook itself imports stay on Node's module cache,
+  the same limitation the trusted route path has, so a change to a hook's
+  own dependency still needs a process restart.
 - **Sandboxed (`sandbox: true`).** `@jimhoyd/urlcode/sandbox` exports
   `SandboxPool`, the same QuickJS/worker-thread engine that backs a
   sandboxed `function`/`middleware` route — the identical module-allowlist
@@ -2914,6 +2942,35 @@ API is all it has, so its binding grant *is* effectively its whole reach into
 the environment. Trusted code's reach is not bounded that way; treat the
 grant as scoping `context`, not as scoping the process.
 
+### Migrating to the trusted default
+
+If you are upgrading a project from a release before this change shipped:
+**every existing `function` and `middleware` route silently changes execution
+mode**, from sandboxed to trusted, unless it already has (or you add)
+`sandbox: true`. This is a real behavior change on upgrade, not a
+documentation update — a route that used to run with no filesystem or network
+access will, after the upgrade, run with full Node access unless you opt it
+back into the sandbox.
+
+Before upgrading:
+
+- List every `function` and `middleware` route in the project.
+- For each one, decide whether you fully trust that code to run in-process
+  with full Node/filesystem/network access — the same trust you would extend
+  to any other code you deploy to that server.
+- Add `sandbox: true` explicitly to any route whose code you do not fully
+  trust, that processes input from a source you don't control, or that handles
+  a secret binding you want isolated — before you upgrade, not after.
+- Routes you do want running trusted need no change; that is now the default.
+
+The change moves the sandbox from an unconditional guarantee to an explicit,
+per-route choice, mainly for performance: the previous blanket sandbox capped
+concurrency at two workers with no queue shared across every function route on
+the server, which does not scale to real concurrent traffic. It also brings
+first-party code in line with how the rest of the Node ecosystem treats
+deployed application code. The sandbox itself is unchanged for routes that opt
+into it; only the default for routes that declare neither option has changed.
+
 ### What "sandboxed" (`sandbox: true`) still guarantees
 
 - Function sources are parsed/snapshotted without importing them into Node.
@@ -2990,6 +3047,21 @@ it is handed *through `context`*. It does not change what the code can go get
 on its own once it is running; see "binding grants are unaffected" above for
 that distinction.
 
+### Trusted code, not trusted requests
+
+"Trusted" describes the code's authorship — first-party project code you
+reviewed and deployed — not the requests it handles. Every request, in either
+mode, still carries client-controlled path, query, header and body data that is
+exactly as adversarial as it always was. Running trusted means that code
+executes with full Node access if it mishandles that input; it does not mean
+the input itself became safe to trust. Declare `parameters` and `request.body`
+validation in YAML, check `args` and any other request data again inside
+function/middleware code, and implement your own authentication and
+authorization — no route, sandboxed or trusted, adds automatic auth.
+`sandbox: true` narrows what a bug or an unreviewed dependency in the *code*
+can do with that same request data; it is not a substitute for validating or
+authenticating the request itself.
+
 ### Granting selected bindings
 
 An application may request a named binding in YAML, but only an operator can

package/llms.txt

@@ -67,10 +67,11 @@ fields or bypass target limits or operator grants. See [the design principle](do
 
 ## Extensions (accounts, administration, presentation)
 - [Extensions](docs/EXTENSIONS.md): `extensions.<name>` blocks, `extension` mounts, `policies.extensions`, the operator host file, `@jimhoyd/urlcode/extensions`. Project-level lifecycle hooks run trusted via plain `import()`, or sandboxed via `@jimhoyd/urlcode/sandbox`'s `SandboxPool`.
-- [urlcode-auth](https://github.com/jimhoyd-com/urlcode-auth): npm: @jimhoyd/urlcode-auth; accounts, sessions, MFA, roles, account page; its own llms.txt.
-- [urlcode-admin](https://github.com/jimhoyd-com/urlcode-admin): npm: @jimhoyd/urlcode-admin; users, sessions, roles, audit, cases; its own llms.txt.
-- [urlcode-ui](https://github.com/jimhoyd-com/urlcode-ui): npm: @jimhoyd/urlcode-ui; escaped templates, shadcn/ui partials, themes, translations; its own llms.txt.
-- urlcode-dynamic-link (planned, not yet published): stored short links move here as a mount-based extension; core no longer has a native `link` handler.
+- [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