@jimhoyd/urlcode 0.4.0-alpha.1 → 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
@@ -6,10 +16,16 @@ benchmark. Its purpose is to name the friction a first-time user or an AI
 agent meets, compare it with what competing tools do, and rank the changes
 that would matter most. It does not change any contract by itself.
 
+> **Update:** written the day before `0.4.0-alpha.2` reversed the default
+> 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).
+
 ## 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 |
 |---|---|---|---|
@@ -81,7 +97,7 @@ whether it touches a contract.
    "add accounts" row except the revision pin existed because they were
    unpublished. This was a decision, not code; the repositories already had
    the release checks. No contract change. Done 2026-09-18: all three are on
-   npm as `0.1.0-alpha.1` (review still pending, issue 58).
+   npm as `0.1.0-alpha.x` (review still pending, issue 58).
 2. **`urlcode init --with auth,admin,ui`.** Delegate to each installed
    package's existing scaffold; write one host file and one README. No contract
    change; a CLI addition in core that calls into optional peers.

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

@@ -17,6 +17,19 @@ routes:
       cache: { strategy: swr, maxAge: 30, staleWhileRevalidate: 300, vary: [Accept-Language] }
 ```
 
+A route may also write `cache` directly, next to `function` or `middleware`,
+instead of nesting it under `policies`. The compiler expands it to
+`policies.cache` before anything else reads the project ([policies](../POLICIES.md)),
+so it is pure sugar over the form above and is refused alongside a direct
+`policies.cache` on the same route:
+
+```yaml
+routes:
+  /feed:
+    function: { source: feed.mjs }
+    cache: { strategy: swr, maxAge: 30 }   # same as policies: { cache: {...} }
+```
+
 ## Strategies
 
 | `strategy` | Emitted headers | Origin memory cache | Typical use |

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

@@ -3,7 +3,7 @@ description: Pages, a static directory, a download and one function next to them
 tags: [assets, static, page, download, html, files, cache, snapshot, function]
 complexity: intermediate
 capabilities: [bindings, download, enabled, function, methods, page, parameters, redirect, static]
-targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
 routes: 5
 files: [urlcode.yaml, functions/hello.mjs, public/about.html, public/guide.txt, public/assets/example.txt, tests/requests.json, README.md]
 tests:
@@ -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/aws/example.yaml

@@ -3,7 +3,7 @@ description: Native-handler project served by an AWS Lambda Function URL through
 tags: [aws, lambda, serverless, deploy, adapter, native, page, static, redirect, respond, sam]
 complexity: intermediate
 capabilities: [enabled, methods, page, parameters, redirect, respond, static]
-targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: refused}
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: refused, static: refused}
 routes: 5
 services:
   - name: AWS Lambda

package/examples/cloudflare/example.yaml

@@ -3,7 +3,7 @@ description: Declarative redirect and respond project compiled into a Cloudflare
 tags: [cloudflare, workers, wrangler, compile, deploy, serverless, redirect, respond, native]
 complexity: intermediate
 capabilities: [enabled, methods, parameters, redirect, respond, response.headers]
-targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible}
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible, static: refused}
 routes: 4
 services:
   - name: Cloudflare Workers

package/examples/conditions/example.yaml

@@ -3,7 +3,7 @@ description: Exact query, header, cookie, host and method conditions choosing be
 tags: [conditions, conditional, match, query, header, cookie, host, method, redirect, respond, disjoint]
 complexity: intermediate
 capabilities: [conditional, conditions, enabled, methods, redirect, respond]
-targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: refused}
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: refused, static: refused}
 routes: 4
 grants:
   - kind: origin

package/examples/cookbook/example.yaml

@@ -3,7 +3,7 @@ description: Forty runnable routes covering every handler, middleware, inputs, b
 tags: [cookbook, reference, routes, handlers, middleware, policies, site, includes, parameters, cookies, methods, expiry, assets, everything]
 complexity: advanced
 capabilities: [bindings, download, enabled, expires, function, methods, middleware, page, parameters, policies.agents, policies.cache, policies.security, policies.throttle, redirect, request.body, respond, response.headers, static]
-targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
 routes: 40
 files: [urlcode.yaml, routes/code.yaml, routes/redirects.yaml, routes/responses.yaml, routes/files.yaml, routes/policies.yaml, routes/middleware.yaml, route-index.json, tests/requests.json, README.md]
 tests:

package/examples/cookbook/middleware/bucket.mjs

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

package/examples/cookbook/middleware/locale.mjs

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

package/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/egress/example.yaml

@@ -3,7 +3,7 @@ description: A bounded HTTPS proxy route and a route with a best-effort signal,
 tags: [egress, proxy, signals, outbound, https, grant, policy, operator, webhook]
 complexity: advanced
 capabilities: [enabled, methods, parameters, proxy, respond, signals]
-targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
 routes: 2
 grants:
   - kind: proxy

package/examples/extensions/example.yaml

@@ -3,7 +3,7 @@ description: Two declared operator extensions, one mount and two protected route
 tags: [extensions, auth, operator, mount, protected, policies.extensions, registry, revision]
 complexity: advanced
 capabilities: [enabled, extension, methods, policies.extensions, respond]
-targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: refused}
+targets: {self-hosted: conditional, aws: conditional, vercel: conditional, cloudflare: refused, static: refused}
 routes: 3
 services:
   - name: operator registry

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 executes a QuickJS/WASM guest 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/example.yaml

@@ -3,7 +3,7 @@ description: Pages rendered by a function and a template middleware, then preren
 tags: [prerender, build, static, pages, template, function, middleware, html, render]
 complexity: advanced
 capabilities: [enabled, function, methods, middleware]
-targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
 routes: 3
 files: [urlcode.yaml, functions/page.mjs, middleware/template.mjs, prerender.mjs, tests/requests.json, README.md]
 tests:

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/examples/provider-conformance/example.yaml

@@ -3,7 +3,7 @@ description: Synthetic redirect and respond fixture deployed to a disposable env
 tags: [provider, conformance, verify, deployment, fixture, aws, vercel, cloudflare, self-hosted, probes]
 complexity: intermediate
 capabilities: [enabled, methods, parameters, redirect, request.body, respond, response.headers]
-targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible}
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible, static: refused}
 routes: 5
 files: [urlcode.yaml, README.md]
 tests:

package/examples/vercel/example.yaml

@@ -3,7 +3,7 @@ description: Native-handler project deployed as a Vercel Node function through t
 tags: [vercel, serverless, deploy, adapter, native, page, static, redirect, respond]
 complexity: intermediate
 capabilities: [enabled, methods, page, parameters, redirect, respond, static]
-targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: refused}
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: refused, static: refused}
 routes: 5
 services:
   - name: Vercel