@jimhoyd/urlcode 0.4.0-alpha.2 → 0.4.1

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,28 @@
+# 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 |
+| [Lambda compile spike](2026-09-19/SPIKE-LAMBDA-COMPILE.md) | Proposal declined 2026-09-19 in favour of one Node deployment per project | Open decisions; AWS and Vercel guides |
+
+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/docs/yaml/functions.md

@@ -53,8 +53,16 @@ short form: `middleware: [middleware/headers.mjs]` means
 `middleware: [{source: middleware/headers.mjs}]`. The path must be
 project-relative, end in `.mjs` or `.js` and contain no `..` segment.
 Methods default to GET and HEAD. Function paths resolve from the project root,
-not the YAML file's directory. `.js` and `.mjs` ES modules work; TypeScript, Node
-APIs, npm imports, network access and filesystem access do not.
+not the YAML file's directory. Modules are ES modules either way: `.mjs` always
+works, while a trusted `.js` module is loaded by Node and therefore needs the
+nearest `package.json` to say `"type": "module"` (a `sandbox: true` route reads
+`.js` as ESM regardless). Serving never transpiles TypeScript; build it first
+with [TypeScript authoring](../TYPESCRIPT-AUTHORING.md). The route above
+declares no `sandbox`, so it runs trusted and in-process: Node APIs, npm
+imports, network and filesystem access are all available to it, exactly as they
+are to any other Node code in the host. Add `sandbox: true` to trade them away
+for isolation -- inside the guest none of them exist. See
+[trust model and sandbox opt-in](../FUNCTION-SECURITY.md).
 
 ## 4. Input types and constraints
 

package/docs/yaml/middleware.md

@@ -23,7 +23,9 @@ export async function decorate(request, context, next) {
 
 Entries run in declared order before the handler and reverse order afterward.
 Return a Response early to skip downstream code; call `next()` at most once.
-Up to 16 middleware entries share one sandbox/deadline and approved route
-bindings. Native bodies are opaque; preserving them requires retaining original
-status/headers. Return a new Response to replace native content or destination.
+Up to 16 middleware entries share the route's execution mode, one deadline and
+one set of approved route bindings; the mode is the route's `sandbox` field, not
+a per-entry choice. On a `sandbox: true` route native bodies are opaque;
+preserving them requires retaining original status/headers. Return a new
+Response to replace native content or destination.
 YAML response headers apply last. See [middleware](../MIDDLEWARE.md) for details.

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/middleware/envelope.mjs

@@ -1,5 +1,7 @@
-// Wrap successful JSON function responses in a stable envelope. Native bodies are
-// opaque and pass through untouched; only readable JSON is rewritten.
+// Wrap successful JSON function responses in a stable envelope. Only a JSON body
+// this chain can actually read is rewritten; everything else passes through
+// untouched -- on a `sandbox: true` route that includes every native body, which
+// the guest cannot read at all.
 export default async function envelope(request, context, next) {
   const response = await next();
   if (!response.ok || !(response.headers.get('content-type') || '').startsWith('application/json')) 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/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: