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

package/docs/STATIC.md

@@ -0,0 +1,105 @@
+# Deploying to static hosting (S3 + CloudFront)
+
+The `static` target is the bottom rung of the [capability
+ladder](FRAMEWORK.md#the-ladder):
+the same `urlcode.yaml` a self-hosted server or a serverless adapter runs, with
+no server process at all. `urlcode build --target static` compiles a project
+ahead of time into plain files and two small JSON manifests meant for an S3
+bucket served through CloudFront — nothing here executes a request.
+
+```sh
+urlcode build --target static --project . --out dist --origin https://links.example
+```
+
+## Declarative routes only, and less than that
+
+This target serves **redirects**, **declared responses** (`respond:`) and
+static files (`page`, `static`, `download`) — no path parameters, no query
+passthrough or mapping, both GET and HEAD required, `respond.status: 200` only, and no `enabled: false` or `expires`
+(there is no server to answer a disabled or expired route with 404/410, so the
+build refuses one instead of silently serving it forever). Everything else is
+refused **at build time**, with the route pattern and the reason named:
+
+| Handler / feature | Why it is refused |
+| --- | --- |
+| `function`, `middleware` | no server, so no dynamic or sandboxed execution |
+| `extension`, `policies.extensions` | no server, so no operator extension registry |
+| `proxy`, `signals` | no server, so no bounded or fire-and-forget egress |
+| `conditional`, `match` (`conditions`) | no server, so no request-time condition matching |
+| `parameters`, `request.body` | no server, so no request-time validation |
+| `response.headers` | no server, so no per-request headers; set them as S3 object metadata or a CloudFront response headers policy instead |
+| `env`, `secrets` (`bindings`) | no server, so no per-request binding resolution |
+| every `policies.*` | no server, so no runtime policy enforcement |
+| a redirect with a `{parameter}` in its path | S3's per-object redirect is keyed to one exact object, not a pattern |
+| a redirect with `query.pass`/`query.map` | S3's per-object redirect cannot compute a target per request |
+| a redirect with a `status` other than 301 | S3's per-object website redirect always answers 301 |
+| a route not admitting both GET and HEAD, or admitting other methods | the output cannot enforce a different method set |
+| `respond.status` other than 200 | an uploaded response object cannot preserve a custom HTTP status |
+| a route with `enabled: false` or `expires` | no server to answer a disabled/expired route; remove the route instead |
+
+Run `urlcode capabilities --target static` for the full catalog.
+
+## What the build emits
+
+`--out` (default `dist/static`) receives:
+
+- `objects/<key>` — the actual files to upload, one per served route. A `page`
+  or `download` route becomes one file; a `static` mount becomes one file per
+  entry in its directory. Object keys match the S3 convention: the route
+  pattern with its leading `/` stripped, and `/` itself becomes `index.html`
+  (matching a bucket's own "Index document" setting). A redirect route also
+  gets a zero-byte placeholder object at its key, so it exists to carry
+  metadata.
+- `objects.json` — `{ format, objects: [{ key, contentType, cacheControl?,
+  contentDisposition? }] }`. Plain file upload loses this metadata (S3 does not
+  reliably infer content type or cache headers from an extension-less key), so
+  a deploy step reads this file and sets each object's own `Content-Type`,
+  `Cache-Control` and `Content-Disposition` from it, for example with
+  `aws s3 cp --content-type ... --cache-control ...` per entry, or an
+  equivalent `aws s3 sync` post-processing step.
+- `redirects.json` — `{ format, redirects: [{ key, location, status: 301 }] }`.
+  Each entry is applied as the S3 object's
+  [website redirect location](https://docs.aws.amazon.com/AmazonS3/latest/userguide/how-to-page-redirect.html)
+  metadata (`x-amz-website-redirect-location`), for example
+  `aws s3api put-object --website-redirect-location <location> --bucket ... --key <key>`.
+  S3 always answers a request for that key with a 301 to `location`
+  regardless of the object's own content — this is why a declared `status`
+  other than 301 is refused rather than silently downgraded.
+- `manifest.json` — the same project-level semantic manifest every target
+  writes (see [tooling](TOOLING.md)).
+
+None of these are edited by hand, and `dist/` belongs in `.gitignore`. This
+target ships no runtime import (there is nothing to run), so there is no
+`@jimhoyd/urlcode/static` entry point — the build output is the deployment.
+
+## What this is not: GitHub Pages
+
+**This target's claimed support is S3 + CloudFront, not GitHub Pages.**
+GitHub Pages has no per-object redirect metadata and no server-side rewrite
+layer, so a `redirect` route compiled the way this target compiles it (S3
+object metadata) has no equivalent there — the only options are a
+meta-refresh/JavaScript page (visibly a redirect, not an HTTP one: search
+engines, curl and anything that does not run JavaScript sees the source page,
+not a 3xx) or a static 404-page trick, both lower fidelity than what every
+other target in this project does for the same route. Rather than claim a
+portability promise this platform cannot keep, GitHub Pages is out of scope
+for this target. If you need Pages, treat it as a distinct target with its own
+explicit fidelity caveat, not a rename of this one.
+
+## Verification status
+
+This target has local build tests only (`test/static.test.ts`): the compiled
+object layout, the redirect manifest, and every refusal above. **It has not
+been deployed to S3 or fronted by CloudFront.** Bucket policy, CloudFront
+caching behavior, TLS/domain setup and the exact `aws s3` invocations above are
+unverified until a real deployment exercises them.
+
+
+## Building pages with middleware
+
+Use [prerendering](PRERENDER.md) to execute functions and native middleware at
+build time, then export the generated native page routes with this target.
+Trusted Node execution is the build default; `sandbox: true` retains its
+restricted imports and resource limits. Neither mode adds a request-time server
+to the static output. Authentication, request-dependent headers and other
+per-request middleware cannot be baked into a public file safely.

package/docs/TOOLING.md

@@ -76,7 +76,7 @@ network. Keys always appear in this order:
 - `urlcode` (package version) and `schema` (`"1"`).
 - `project`: entry file, route count, handlers used with counts, extensions
   declared, policies in effect at the top level and the number of routes each
-  policy applies to, requested env and secret binding names, `dynamicLinks`,
+  policy applies to, requested env and secret binding names,
   `site` keys, and `files` (include, function and middleware paths). With
   `--host-file`, `host` counts the operator module's extensions and plugins
   without activating them.
@@ -113,13 +113,17 @@ checks. Build output remains an explicit separate build API/CLI operation.
 
 The package root also exports existing operator-invoked workflow APIs:
 `buildCloudflare(project, options)` compiles and writes a Cloudflare artifact;
-`runProjectTests(project, options)` starts the local runtime, executes request
-fixtures and closes it; `scaffoldProject(project, {dryRun})` creates missing
-placeholders while preserving existing files; `initProject(destination)` creates
-the standard starter; and `addRedirect(project, destination, alias?)` updates
-project YAML under the authoring lock. `CloudflareBuildOptions`,
-`CloudflareBuildReport`, `ProjectTestOptions`, `ProjectTestResult`, `ScaffoldReport`
-and `ScaffoldUnresolved` describe these existing operations.
+`buildStatic(project, options)` compiles redirects and static files into plain
+objects and redirect metadata for S3 + CloudFront (see [static
+hosting](STATIC.md)); `runProjectTests(project, options)` starts the local
+runtime, executes request fixtures and closes it; `scaffoldProject(project,
+{dryRun})` creates missing placeholders while preserving existing files;
+`initProject(destination)` creates the standard starter; and
+`addRedirect(project, destination, alias?)` updates project YAML under the
+authoring lock. `CloudflareBuildOptions`, `CloudflareBuildReport`,
+`StaticBuildOptions`, `StaticBuildReport`, `ProjectTestOptions`,
+`ProjectTestResult`, `ScaffoldReport` and `ScaffoldUnresolved` describe these
+existing operations.
 
 These SDK functions have explicit write or execution effects and are available
 to trusted callers only. Project tests use normal runtime activation, grants and
@@ -133,8 +137,8 @@ assistant file-write, guest-execution, deployment or network authority.
 
 `urlcode explain [/route] [--project DIR] [--target T] [--host-file F] [--json]`
 prints what `explainRoute` returns: one route in detail, or without a path a
-one-line-per-route table (methods, handler, state, middleware count, policies,
-cache outcome and target support). `--target` narrows the support columns to
+one-line-per-route table (methods, handler, state, execution mode, middleware
+count, policies, cache outcome and target support). `--target` narrows the support columns to
 one deployment target; `--host-file` supplies the operator registry so
 extension requirements show their provider. An unknown route exits 1 and names
 the nearest patterns. Everything comes from the compiled configuration: no
@@ -144,13 +148,14 @@ request is evaluated, no function runs and no binding is read.
 `schemaVersion`, the `urlcode` version, the entry file and its includes, the
 `revision` (the same digest `inspectExtensionRevision` returns, so an operator
 pin can be checked against it), the config `configVersion`, every route (path,
-methods, handler, state, middleware, inputs, policy names, extension
+methods, handler, state, execution mode (`sandbox`, with `sandboxReason` when
+the route declares one), middleware, inputs, policy names, extension
 requirements, cache outcome, binding names, egress origins, capabilities and
 per-target support), the union of capabilities used, extension declarations
 (version, configuration keys, mounts and protected routes), recipe provenance
 (from a `recipe.yaml` beside the entry file when one exists), external
 requirements (environment and secret names, proxy and signal origins,
-extensions, link-store collections, dynamic links), the function and middleware
+extensions), the function and middleware
 modules with the routes that use them, and per-target compatibility. Without
 `--json` a short summary prints. The manifest is deterministic: the same
 project produces the same bytes. `urlcode build` writes the same document as

package/docs/TUNNELS.md

@@ -65,9 +65,6 @@ scanners that find it within minutes.
 - The runtime has **no authentication and no rate limiting**. Put access control
   in the tunnel: ngrok's OAuth, OIDC or basic auth; Cloudflare Access; a
   Tailscale ACL.
-- **Never tunnel the link-management API.** It is a separate listener bound to
-  loopback on purpose, holding credentials that can rewrite live links. Tunnel
-  the application port only.
 - Prefer `serve` with a fixed snapshot, a project containing no real secrets,
   and a tunnel you shut down when finished.
 

package/docs/TYPESCRIPT-AUTHORING.md

@@ -1,8 +1,16 @@
 # Build-time TypeScript guests
 
 TypeScript guest authoring is a separate build step. Serving still accepts only
-JavaScript ES modules and executes them exclusively in QuickJS/WebAssembly.
-The build never imports application modules into Node or runs application code.
+JavaScript ES modules. The build never imports application modules into Node
+or runs application code, and it is `sandbox`-aware per route
+(docs/SPIKE-DEFAULT-TRUST-MODEL.md): a route that declares `sandbox: true` is
+transpiled under the sandbox's own module rules (relative imports only, no
+dynamic import/bare specifiers, the module/size limits below), exactly as
+before; a trusted (non-`sandbox: true`) route is transpiled without those
+import/size restrictions, since it will run with full Node access — bare/npm
+imports, dynamic `import()`, `import.meta` — once served. Both modes still
+diagnose only syntax, not semantics, and neither imports application code into
+the build process in a way that executes it.
 
 ```sh
 urlcode recipes add typescript --out ./hello-source
@@ -29,17 +37,29 @@ The trusted pinned TypeScript compiler transpiles ES2022/ES modules with fixed
 settings. It does not read `tsconfig.json`, package scripts, plugins, compiler
 transformers, dependency packages, Node declarations or ambient environment
 files. It diagnoses syntax errors, but does **not** perform semantic type
-checking. Type-only relative imports are erased without reading their targets.
-Bare/npm imports (including static type-only imports), CommonJS import/export
-syntax, dynamic runtime imports, `import.meta`, import attributes and imports
-outside the project are refused. No import extension inference occurs.
+checking, in either mode. CommonJS import/export syntax and imports outside
+the project are always refused. Type-only relative imports are erased without
+reading their targets.
 
-The source graph is limited to 128 modules, 1 MiB per source and 4 MiB aggregate.
-The emitted graph must pass the runtime's own source parser and byte limits
-before publication. This does not execute the modules or replace normal route,
-policy, binding or sandbox validation at activation. Unsupported host/browser
-APIs remain unavailable in QuickJS, even if TypeScript accepts their names.
-Run `urlcode validate --local` and project tests on the output.
+For a `sandbox: true` route, bare/npm imports (including static type-only
+imports), dynamic runtime imports, `import.meta` and import attributes are
+refused, and the source graph is limited to 128 modules, 1 MiB per source and
+4 MiB aggregate; the emitted graph must also pass the runtime's own sandboxed
+source parser and byte limits before publication. For a trusted route, none of
+that applies: bare/npm specifiers, dynamic `import()`, `import.meta` and
+import attributes pass through unchanged (resolved by Node at serve time, not
+by this build), and there is no module-count or aggregate-size ceiling — only
+a generous 16 MiB per-source read cap that bounds authoring-time memory. A
+module may be shared by trusted and sandboxed routes: it is emitted once, and
+every module reachable from a `sandbox: true` route is still validated under
+the sandbox rules and budgets above, which does not disqualify the trusted
+route that also imports it. In both modes,
+no import extension inference occurs — relative imports of project modules
+still need an explicit `.ts`/`.js`/`.mjs` extension to be rewritten and
+followed. This does not execute the modules or replace normal route, policy,
+binding or sandbox validation at activation. Unsupported host/browser APIs
+remain unavailable in QuickJS, even if TypeScript accepts their names. Run
+`urlcode validate --local` and project tests on the output.
 
 Includes are flattened into a duplicate-checked entry document. Only referenced
 modules, page/download assets, static trees, site favicon/llms files and the

package/docs/TYPESCRIPT.md

@@ -16,7 +16,7 @@ beside them, and `dist/BUILD-MANIFEST.json` with a SHA-256 per emitted file.
 | Import | Runtime | Declarations |
 |---|---|---|
 | `urlcode` | `dist/index.js` | `dist/types/index.d.ts` |
-| `@jimhoyd/urlcode/plugins`, `@jimhoyd/urlcode/policies`, `@jimhoyd/urlcode/observability`, `@jimhoyd/urlcode/compliance`, `@jimhoyd/urlcode/prerender`, `@jimhoyd/urlcode/extensions` | `dist/<name>.js` | `dist/types/<name>.d.ts` |
+| `@jimhoyd/urlcode/plugins`, `@jimhoyd/urlcode/policies`, `@jimhoyd/urlcode/observability`, `@jimhoyd/urlcode/compliance`, `@jimhoyd/urlcode/prerender`, `@jimhoyd/urlcode/extensions`, `@jimhoyd/urlcode/sandbox` | `dist/<name>.js` | `dist/types/<name>.d.ts` |
 | `@jimhoyd/urlcode/aws`, `@jimhoyd/urlcode/vercel`, `@jimhoyd/urlcode/cloudflare` | `dist/<name>.js` | `dist/types/<name>.d.ts` |
 | `@jimhoyd/urlcode/schema` | `schemas/urlcode.schema.json` | — |
 
@@ -36,9 +36,7 @@ release cannot ship a declaration that does not resolve.
 ## The main exported types
 
 - `urlcode`: `Runtime`, `RuntimeOptions`, `RuntimeRequest`, `RequestTrace`,
-  `Server`, `ServerOptions`, `HostPlugin`, `Observer`, `TestPlan`, `LinkStore`,
-  `LinkRow`, `LinkStoreOptions`, `LinkReader`, `LinkStoreBinding`, `LinkApi`,
-  `LinkApiOptions`, `LinkEvent`, `LinkObserverOptions`.
+  `Server`, `ServerOptions`, `HostPlugin`, `Observer`, `TestPlan`.
 - `@jimhoyd/urlcode/plugins`: `Plugin`, `PluginRuntime`, `PolicyRequest`,
   `HandlerResult`, `HeaderPair`, `TargetName`. See [plugins](PLUGINS.md).
 - `@jimhoyd/urlcode/policies`: `PolicyModule`, `PolicyRegistry`, `PolicyRequest`,
@@ -54,6 +52,29 @@ release cannot ship a declaration that does not resolve.
 - `@jimhoyd/urlcode/aws`, `@jimhoyd/urlcode/vercel`, `@jimhoyd/urlcode/cloudflare`: `LambdaEvent`,
   `LambdaHandler`, `LambdaHandlerOptions`; `VercelHandler`,
   `VercelHandlerOptions`; `Artifact`, `WorkerRoute`, `Validators`.
+- `@jimhoyd/urlcode/sandbox`: `SandboxPool`, `SandboxEntry`, `SandboxTarget`,
+  `SandboxInvocation`, `SandboxPoolOptions`, `functionFile`. The public
+  sandboxed-execution primitive: the same QuickJS/worker-thread engine that
+  already backs a `sandbox: true` `function`/`middleware` route
+  (`FunctionPool`, internally), generalized to an explicit list of
+  `{source, export}` entries instead of anything route/YAML-shaped, for an
+  extension package that needs to run a project-supplied hook through real
+  isolation when the project's own config declares `sandbox: true` on it
+  (see [EXTENSIONS.md](EXTENSIONS.md#project-level-lifecycle-hooks) and
+  [FUNCTION-SECURITY.md](FUNCTION-SECURITY.md)). There is no trusted-mode
+  export here: a hook that does not declare `sandbox: true` is ordinary
+  project code the extension `import()`s directly via
+  `ExtensionActivation.root`, no primitive required.
+
+  ```ts
+  import { SandboxPool, functionFile } from '@jimhoyd/urlcode/sandbox';
+
+  const source = await functionFile(root, hookConfig.source); // root: ExtensionActivation.root
+  const entries = [{ source, export: hookConfig.export ?? 'default' }];
+  const pool = await new SandboxPool(entries, { root, workers: 1 }).start();
+  const result = await pool.execute({ entry: entries[0] }, request, context, undefined);
+  await pool.close();
+  ```
 
 ```ts
 import { startServer, type ServerOptions, type Observer } from '@jimhoyd/urlcode';

package/docs/VERCEL.md

@@ -5,8 +5,8 @@ The Vercel adapter runs a URLCode project as a Node function. The same
 that is the point of the project format.
 
 **This adapter serves native handlers only:** redirects, validated responses,
-pages, static assets and downloads. Isolated functions, middleware and stored
-live links are refused at activation, not per request, so a deployment cannot
+pages, static assets and downloads. `function` and `middleware` routes are
+refused at activation, trusted or sandboxed alike, not per request, so a deployment cannot
 half-work. See [what is not supported](#what-this-adapter-does-not-do).
 
 A working project is in [`examples/vercel/`](../examples/vercel/).
@@ -71,9 +71,8 @@ and want it in generated URLs.
 
 | Not supported | Why |
 |---|---|
-| Isolated functions | Every cold start would spawn worker threads and load the WASM engine. Correctness is not the issue; predictable latency is, and it is unmeasured. |
-| Middleware | Runs in the same sandbox as functions. |
-| Stored live links | SQLite needs a durable writable file. A serverless filesystem is ephemeral and per-instance, so records would silently diverge between instances. |
+| `function` routes | They need the self-hosted Node lifecycle; a `sandbox: true` route would additionally spawn worker threads and load the WASM engine on every cold start. Correctness is not the issue; predictable latency is, and it is unmeasured. |
+| Middleware | Runs in the same execution mode as the route's function, and is refused with it. |
 | `urlcode serve` operational endpoints | `/_urlcode/health` and `/_urlcode/ready` describe a long-lived process. Use Vercel's own observability. |
 
 Each refusal happens at activation with a message naming the route, so you find

package/docs/VERSION-ALIGNMENT.md

@@ -0,0 +1,46 @@
+# Package and channel alignment
+
+The package manifests and root lockfile are the version authority. Read live
+registry and Git tag state with `npm run release:status`; do not maintain a
+second table of changing version numbers in documentation.
+
+| Package | Manifest | Version owner | Release tag |
+| --- | --- | --- | --- |
+| `@jimhoyd/urlcode` | `package.json` | Explicit core release PR | `v<version>` |
+| `@jimhoyd/urlcode-ui` | `packages/ui/package.json` | Changesets | `@jimhoyd/urlcode-ui@<version>` |
+| `@jimhoyd/urlcode-auth` | `packages/auth/package.json` | Changesets | `@jimhoyd/urlcode-auth@<version>` |
+| `@jimhoyd/urlcode-admin` | `packages/admin/package.json` | Changesets | `@jimhoyd/urlcode-admin@<version>` |
+
+Development uses workspace source. Auth and admin's `file:../..` development
+links resolve core to this checkout, enforced by `check-workspace-links.ts`.
+Core never imports extension packages. Release verification instead installs the
+published lower bound of each declared peer range and checks resolution. A peer
+floor rises when code requires a newly introduced API, not just because a sibling
+published another version. Preserve the declared upper bound during Changesets
+versioning; `.changeset/config.json` limits unnecessary peer rewrites.
+
+Publishable workspace changes carry Changesets; the release PR applies them and
+updates versions, changelogs and the lockfile together. Core stays an explicit
+entry in that PR until a separately reviewed workspace migration. Its CLI banner
+must match its manifest. `npm run release:check` rejects stale lockfile versions.
+Unreleased source changes do not require moving a published tag or pretending a
+new package has already shipped.
+
+Alpha releases publish under `alpha`; they never automatically move npm
+`latest`. Core's historical `latest` remains the stable 0.3.0 baseline until an
+explicit stable release decision. Extensions have historical alpha versions on
+`latest`; subsequent alpha publication does not keep that channel in lockstep.
+Different channel values alone are not drift. Test the install combination you
+recommend against peer ranges; a bare install may select an older channel.
+`release:status` reports each declared peer floor and whether its current
+`latest` and `alpha` satisfy the range.
+
+The standalone `urlcode-template` is an external exact-version consumer: after a
+runtime release, update its dependency and starter through its own reviewed PR.
+It is not automatically released by the monorepo coordinator. The retired
+`urlcode-docs`, `urlcode-middleware`, `urlcode-dynamic-link` and `urlcode-short`
+repositories are not release targets.
+
+See [the development pipeline](DEVELOPMENT-PIPELINE.md) for preparation,
+publication order, immutable retries and credential scope, and
+[release security](RELEASE-SECURITY.md) for provenance and limitations.

package/docs/YAML-GUIDE.md

@@ -37,7 +37,6 @@ Each page holds the recipes for one task; the section numbers continue across pa
 | [Pages, static folders and downloads](yaml/assets.md) | 10. Pages, static folders, downloads and MIME |
 | [Enable, disable and expire](yaml/conditions.md) | 11. Enable, disable and expire |
 | [Bindings, split files and tests](yaml/organization.md) | 12. Environment and secret references; 13. Split files and folders; 14. Assert inputs and outputs |
-| [Live short-link records](yaml/links.md) | 15. Live short-link records |
 | [Policies and profiles](yaml/policies.md) | 16. Hardened profile and per-route overrides |
 | [Site conventions](yaml/site.md) | 17. Site conventions |
 
@@ -56,5 +55,3 @@ Each page holds the recipes for one task; the section numbers continue across pa
 | Automatic hot updates in `serve` | Deploy/restart or use the embedding reload API deliberately |
 | “All examples are production-ready” | Validate your security, load and deployment requirements separately |
 
-Live-link recipes require `dynamicLinks: true` in the entry `urlcode.yaml`; see
-[live short-link records](yaml/links.md) and [dynamic-link opt-in](DYNAMIC-LINKS.md#explicit-project-opt-in).

package/docs/YAML-REFERENCE.md

@@ -20,6 +20,8 @@ schema-valid combinations activate successfully.
 | `routes.*.methods` | array | no | default: ["GET","HEAD"]; minItems: 1; uniqueItems: true |
 | `routes.*.methods[]` | string | no | enum: ["GET","HEAD","POST","PUT","PATCH","DELETE","OPTIONS"] |
 | `routes.*.enabled` | boolean | no | — |
+| `routes.*.sandbox` | boolean | no | default: false |
+| `routes.*.sandboxReason` | string | no | maxLength: 500 |
 | `routes.*.expires` | string | no | — |
 | `routes.*.description` | string | no | maxLength: 1024 |
 | `routes.*.parameters` | array | no | maxItems: 64 |
@@ -113,11 +115,6 @@ schema-valid combinations activate successfully.
 | `routes.*.middleware[] (option 2)` | object | no | unknown keys rejected |
 | `routes.*.middleware[] (option 2).source` | string | yes | maxLength: 1024 |
 | `routes.*.middleware[] (option 2).export` | string | no | pattern: "^[A-Za-z_][A-Za-z0-9_]*$" |
-| `routes.*.link` | object | no | unknown keys rejected |
-| `routes.*.link.collection` | string | yes | pattern: "^[A-Za-z][A-Za-z0-9_-]{0,63}$" |
-| `routes.*.link.code` | object | yes | unknown keys rejected |
-| `routes.*.link.code.from` | constant | yes | const: "path" |
-| `routes.*.link.code.name` | string | yes | pattern: "^[A-Za-z_][A-Za-z0-9_]*$" |
 | `routes.*.policies` | object | no | unknown keys rejected |
 | `routes.*.policies.profile` | string | no | pattern: "^[a-z][a-z0-9-]{0,63}$" |
 | `routes.*.policies.throttle` | one of the shapes below | no | — |
@@ -268,9 +265,22 @@ schema-valid combinations activate successfully.
 | `routes.*.auth (option 2).verified` | boolean | no | — |
 | `routes.*.auth (option 2).freshWithinSeconds` | integer | no | minimum: 1; maximum: 3600 |
 | `routes.*.auth (option 2).onDeny` | number / string | no | enum: [401,403,404,"sign-in"] |
+| `routes.*.cache` | object | no | unknown keys rejected |
+| `routes.*.cache.strategy` | string | no | enum: ["no-store","revalidate","public","immutable","swr","sie","micro","cdn-only","private"] |
+| `routes.*.cache.maxAge` | integer | no | minimum: 0; maximum: 31536000 |
+| `routes.*.cache.staleWhileRevalidate` | integer | no | minimum: 0; maximum: 31536000 |
+| `routes.*.cache.staleIfError` | integer | no | minimum: 0; maximum: 31536000 |
+| `routes.*.cache.cdnMaxAge` | integer | no | minimum: 0; maximum: 31536000 |
+| `routes.*.cache.originTtl` | integer | no | minimum: 0; maximum: 86400 |
+| `routes.*.cache.vary` | array | no | maxItems: 8; uniqueItems: true |
+| `routes.*.cache.vary[]` | string | no | minLength: 1; maxLength: 128 |
+| `routes.*.cache.statuses` | array | no | maxItems: 16; uniqueItems: true |
+| `routes.*.cache.statuses[]` | integer | no | minimum: 200; maximum: 599 |
+| `routes.*.cache.maxBytes` | integer | no | minimum: 0; maximum: 16777216 |
+| `routes.*.cache.maxEntries` | integer | no | minimum: 1; maximum: 1000000 |
+| `routes.*.cache.force` | boolean | no | default: false |
 | `includes` | array | no | maxItems: 256; uniqueItems: true |
 | `includes[]` | string | no | maxLength: 1024 |
-| `dynamicLinks` | boolean | no | default: false |
 | `policies` | object | no | unknown keys rejected |
 | `policies.profile` | string | no | pattern: "^[a-z][a-z0-9-]{0,63}$" |
 | `policies.throttle` | one of the shapes below | no | — |

package/docs/archive/2026-09-19/EXTENSION-IMPLEMENTATION.md

@@ -0,0 +1,68 @@
+# 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 -->
+
+# Extension implementation sequence
+
+PR #54 records the auth, admin, UI and extension direction. Implementation is
+incremental; the spikes are proposals, not the implemented project schema.
+The implemented specification remains authoritative. This sequence incorporates
+the architectural review rather than treating contradictory spike examples as
+requirements.
+
+## Invariants
+
+- Operators explicitly install trusted host extensions; project YAML never loads
+  host modules or chooses packages. Application code remains isolated in WASM.
+- Authentication credentials stay in host processing. Guest Request headers and
+  header-derived parameters must not expose operator-declared credential headers,
+  including on public routes receiving a session cookie.
+- Session and one-time-token changes have explicit concurrency semantics. Define
+  atomic operations before selecting a database abstraction; multi-record
+  operations cannot rely on a same-collection transaction promise.
+- Passwords and bearer credentials use appropriate hashes. TOTP requires protected
+  recoverable key material and an operator key rotation/backup contract.
+- Authentication forms and submission destinations belong to trusted extension
+  code. Project styling does not imply permission to replace security controls.
+- Administrative authorization is enforced by the API, including subject-level
+  restrictions, self-promotion and last-administrator protections.
+- Unsupported target capabilities fail explicitly. Live provider deployment
+  testing remains deferred and non-blocking; local tests do not prove deployment.
+
+## Delivery order
+
+1. **Credential boundary:** add an explicit host-plugin declaration for headers
+   withheld from guest requests and parameter resolution. Preserve originals for
+   host authentication, cache decisions and policy processing. Test functions,
+   middleware and routes without an authentication requirement.
+2. **Extension registration:** explicit operator registry, versioned configuration
+   validation, route ownership/collision rules and capability reporting. No
+   automatic project host-file execution. Define policy ordering before adding
+   an auth policy.
+3. **Session slice:** one supported login method, trusted login/logout forms,
+   protected page and JSON routes, session lookup/revocation, CSRF and no-store
+   behavior. Evaluate a maintained authentication implementation behind an
+   adapter before writing protocol engines. Define durable atomic store methods
+   and test concurrent redemption, expiry and interrupted operations.
+4. **Administrative API and CLI:** user lookup and session revocation first;
+   audit records and narrowly scoped permissions. Add role/recovery operations
+   only with object-level rules and concurrency tests.
+5. **UI and console:** extract components from real auth/admin flows; choose a
+   constrained renderer and asset ownership model; verify keyboard and assistive
+   technology behavior as well as automated accessibility checks.
+6. **Additional methods and targets:** passkeys, OIDC, MFA, recovery and imports
+   each receive state-machine, abuse-budget and portability tests. Preserve
+   verification of existing credential formats across target migrations.
+
+## Status
+
+PR #54 is merged. The first implementation adds the operator-only
+`Plugin.credentialHeaders` boundary, documented in [Plugins](../../PLUGINS.md).
+The remaining items are pending; none of this document declares end-user auth,
+admin routes, extension YAML, or a generic project store available today.

package/docs/{MANAGEMENT-SECURITY.md → archive/2026-09-19/MANAGEMENT-SECURITY.md}

@@ -1,5 +1,25 @@
+# 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 -->
+
 # Private management and durable mutation audit
 
+> **Retired.** This page describes the management API and mutation audit of
+> core's native link store. That store, its `urlcode links` CLI and this
+> management listener were removed from core when `link` was extracted, and the
+> `urlcode-dynamic-link` package that received them has since been retired and
+> unpublished. Nothing in the current runtime exposes this surface. The page is
+> kept because the security reasoning — loopback-only binding, operator-owned
+> credential policy, transactional mutation audit — is referenced by
+> [security audit](../../SECURITY-AUDIT.md) and applies to any component that
+> reintroduces a management listener.
+
 Management binds only `127.0.0.1` or `::1`. Use an authenticated private tunnel
 (e.g. SSH/VPN with loopback forwarding); never publish its port through a public
 proxy or container port mapping. This is operator management, not an end-user

package/docs/{NEXT-PHASE-PLAN.md → archive/2026-09-19/NEXT-PHASE-PLAN.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 -->
+
 # Next-phase implementation status
 
 Repository review and source implementation, 2026-09-17. Phase A established
@@ -5,6 +15,13 @@ the capability catalog; the subsequent source work implements the bounded
 Phase B–D features below. This describes the source additions after `0.3.0` that ship in
 `0.4.0-alpha.1`, not a claim that provider deployments have been verified.
 
+> **Update:** this document describes the `0.4.0-alpha.1` source work as it
+> stood on 2026-09-17, when every `function`/`middleware` route was sandboxed.
+> The default changed in `0.4.0-alpha.2`: those routes now run trusted and
+> unsandboxed in the host process unless the route declares `sandbox: true`,
+> which gives it exactly the QuickJS/WASM execution described below. See
+> [SPIKE-DEFAULT-TRUST-MODEL.md](../../SPIKE-DEFAULT-TRUST-MODEL.md).
+
 ## Implementation and evidence
 
 | Phase | Implemented source | Evidence and remaining limits |
@@ -21,10 +38,10 @@ Phase B–D features below. This describes the source additions after `0.3.0` th
 | D: TypeScript guests | Fixed trusted build-time compiler, bounded relative graph, rewritten JavaScript imports, referenced-asset snapshot and safe new output | Transpilation is not type checking; no tsconfig/plugins/package execution or dotenv copying; runtime remains QuickJS JavaScript only |
 | D: consolidated SDK/MCP | Inspection, semantic validation, path explanation, compatibility, conversion previews and recipe discovery; operator-rooted stdio MCP | Read-only tooling; no arbitrary path, credential, guest execution or write authority; not a remote authenticated service |
 
-See [interchange](INTERCHANGE.md), [provider evidence](PROVIDER-VERIFICATION.md),
-[egress](EGRESS.md), [conditions](CONDITIONS.md), [recipes](RECIPES.md),
-[bulk measurements](BULK.md), [TypeScript authoring](TYPESCRIPT-AUTHORING.md), and
-[tooling/MCP](TOOLING.md) for the executable interfaces and exact restrictions.
+See [interchange](../../INTERCHANGE.md), [provider evidence](../../PROVIDER-VERIFICATION.md),
+[egress](../../EGRESS.md), [conditions](../../CONDITIONS.md), [recipes](../../RECIPES.md),
+[bulk measurements](../../BULK.md), [TypeScript authoring](../../TYPESCRIPT-AUTHORING.md), and
+[tooling/MCP](../../TOOLING.md) for the executable interfaces and exact restrictions.
 
 ## Preserved architecture
 
@@ -36,10 +53,11 @@ binding resolution and activation and distinguishes implementation support from
 actual deployment evidence. Unknown or unsupported targets fail closed.
 
 Project YAML describes route behavior. Provider infrastructure and outbound
-origin grants stay in operator configuration. Functions remain untrusted
-QuickJS/WASM guests with no host-code fallback. Existing explicit external
-bindings and new egress grants remain pinned to the exact configuration/source
-revision. Compilation and conversion do not resolve credentials or manufacture
+origin grants stay in operator configuration. Through `0.4.0-alpha.1`,
+functions remained untrusted QuickJS/WASM guests with no host-code fallback
+(see the update note above). <!-- trust-model-prose: historical -->
+Existing explicit external bindings and new egress grants remain pinned to the
+exact configuration/source revision. Compilation and conversion do not resolve credentials or manufacture
 grants. File authors publish new projects without overwriting unrelated work.
 
 The five policy modules remain the authority for their target-sensitive