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

package/docs/OPEN-DECISIONS.md

@@ -0,0 +1,184 @@
+# Decisions to align
+
+Reviewed 2026-09-19 against core `db375bf` and the current public package sources.
+This is the maintainer's decision list, not a second implementation backlog.
+The [roadmap](../ROADMAP.md) gives sequence and the [archive](archive/README.md)
+keeps earlier discussions. Recommendations below are not accepted decisions.
+
+## Principles already settled, in plain language
+
+- **Describe first, code only when needed.** Use a supported YAML feature or
+  extension before writing plumbing. Custom application code is still welcome.
+- **Your application code runs like normal Node code.** Functions and middleware
+  are trusted by default. `sandbox: true` deliberately restricts a route's whole
+  function/middleware chain. Request data still needs validation in either mode.
+- **A grant controls what URLCode supplies, not what trusted code can access.**
+  Trusted code can independently read the host environment, files and network.
+  Opt-in sandboxing retains its existing isolation and revision-pinned grants.
+- **Portable does not mean every host supports every feature.** Keep infrastructure
+  out of route YAML and reject unsupported targets before activation.
+- **Core works alone; optional packages add accounts, admin and presentation.**
+  Core never imports those implementations. Shared UI belongs in `urlcode-ui`.
+- **Documentation stays beside the owning code.** Core guides live here;
+  extension contracts and implementation status live in their repositories.
+  `urlcode-docs` is deleted. `urlcode-short` and `urlcode-dynamic-link` are retired.
+- **Passing tests proves the tested behavior.** It does not prove deployment,
+  accessibility, hostile tenant isolation or independent security assessment.
+- **Keep the free runtime useful.** Apache-2.0 remains unchanged; no mandatory
+  hosted account, paid capability gate or provider lock-in belongs in core.
+
+## Decisions still needed
+
+| Decision | What the code says today | Recommendation and consequence |
+|---|---|---|
+| Where does work status live? | Several old plans repeated issues and continued calling delivered work unfinished. | Issues for actionable status, this short roadmap for sequence, archive for completed proposals. Preserve evidence gaps when archiving. |
+| Expand into business applications now? | No collection handler or proposed business suite is implemented; the model-backed benchmark evidence is missing. | Measure existing tasks and record repeated application plumbing before selecting a collection/CMS/forms project. Retired short-link products stay retired. [Proposal](SPIKE-BUSINESS-SUITE.md). |
+| Which provider execution model next? | AWS/Vercel still reject function/middleware despite the trusted default. | Decide demand first, then compare one Node deployment per project against one Lambda per route. Do not promise either today. [Proposal](SPIKE-LAMBDA-COMPILE.md). |
+| Fold extension schemas into retrieved context? | `urlcode extensions` and the MCP `get_extensions` query return the registered configuration and policy schemas, but `src/context.ts:113` reports `extensions` as names only, so an author writing `extensions.<name>.config` or `policies.extensions.<name>` must run the separate operator-authorized query first. | Decide from retrieval and task evidence, not preference: the existing small-task harness can measure whether folding schemas into bounded context improves authoring. Keep the token budget bounded and never auto-load a project-selected host file. This is a discovery improvement, not a defect in the existing query. |
+| Retire the UI primitive fallback? | Auth and admin use the kit when supplied, and retain tested primitive rendering without it. | Keep both until an explicit compatibility/deprecation decision; adoption is already implemented. |
+
+The broader [AI benchmark proposal](SPIKE-AI-FRAMEWORK-BENCHMARK.md) also needs a
+chosen application, model-run budget and execution authorization. The existing
+small-task harness can supply evidence without committing to that larger study.
+
+## Closed questions removed from the active list
+
+- Publishing convention is recorded in [version alignment](VERSION-ALIGNMENT.md):
+  publishable manifests on main, releases through reviewed tags/workflows.
+- Core `0.4.0-alpha.2` and current extension releases exist; publishing that
+  already-shipped version is not a next step.
+- Auth/admin kit adoption and shared form helpers are implemented in their code.
+- The template pins `0.4.0-alpha.2`. Its skill differences were read against that
+  pin: omitted handlers and advice about the removed management API are stale,
+  not intentional older-version behavior.
+- The guidance checks run through `npm run check` inside `verify`; a regex check
+  is not a schema validator for every example. Extending its coverage is tracked
+  separately, not a reason to weaken review or bypass required checks.
+
+## Accepted: per-package release tags
+
+**Decided 2026-09-19.** Workspace packages under `packages/` release on
+Changesets' own `<package name>@<version>` form — for example
+`@jimhoyd/urlcode-ui@0.1.0-alpha.6`. Core keeps bare `v*`.
+
+**The problem.** Core and all three extensions arrived here triggering on
+`tags: ['v*']`, and their alpha tags overlap outright: ui shipped
+`v0.1.0-alpha.2` through `-alpha.5`, admin `v0.1.0-alpha.1` and `-alpha.3`,
+auth `v0.1.0-alpha.1` through `-alpha.3`. Across four repositories that was
+fine. In one repository a single bare tag push starts more than one release
+workflow. Each one fails closed on its own tag-matches-manifest check, so
+nothing can mis-publish — but "two workflows race and one errors on every
+release" is not a release process, and the failure is confusing rather than
+informative.
+
+**Why Changesets' form rather than a prefix like `ui-v0.1.0-alpha.6`.** Both
+work and both are valid ref names. The deciding factor is that Changesets is
+already the chosen release flow, and `changeset tag` emits the
+`<name>@<version>` form natively. Picking anything else means writing and
+maintaining a translation layer between the tool that computes the version and
+the tag that triggers the publish — new code whose only job is to disagree
+with a default. The spike chose Changesets partly because it is "cheap and
+low-risk for an agent or a human to generate correctly"; hand-rolling the tag
+shape undercuts exactly that.
+
+**Why the two schemes cannot collide.** A scoped package name begins with `@`,
+and GitHub's `v*` filter requires a leading `v`, so no tag can match both.
+Verified rather than assumed, including that `*` does not match `/` in a filter
+pattern, so `@jimhoyd/urlcode-ui@*` matches the version segment only.
+
+**Core's asymmetry is forced, not preferred.** Under layout A core is the
+repository root rather than a workspace member, so Changesets does not manage
+it and `changeset version` will not bump it. Core therefore keeps the tag
+scheme and release workflow it already had.
+
+[`scripts/check-release-tags.ts`](../scripts/check-release-tags.ts) enforces
+this in `npm run check`: it rejects a workspace package workflow that does not
+trigger on its own `<name>@*`, rejects any workflow other than core's claiming
+`v*`, and independently asserts that no two filters can match the same tag. The
+reasoning above is the kind of prose that rots as soon as `auth` and `admin`
+arrive, which is the whole argument this repository makes for enforcing checks
+over documented intent.
+
+## Done: the monorepo migration is complete
+
+**Closed 2026-09-19.** `urlcode-ui`, `urlcode-auth` and `urlcode-admin` are
+workspace packages under `packages/`, and all three have been released from
+this repository — `@jimhoyd/urlcode-ui@0.1.0-alpha.6`,
+`@jimhoyd/urlcode-auth@0.1.0-alpha.6`, `@jimhoyd/urlcode-admin@0.1.0-alpha.4`,
+each on `alpha` with `latest` deliberately held behind. Core's dist-tags are
+unchanged. The three source repositories are gone; their history survives only
+as verified `git bundle`s, because the repository allows squash merges only and
+the imported commits did not survive onto `main`.
+
+The operational runbook is [DEVELOPMENT-PIPELINE.md](DEVELOPMENT-PIPELINE.md)
+and [RELEASE-SECURITY.md](RELEASE-SECURITY.md). The plan itself is archived at
+[archive/2026-09-19/SPIKE-MONOREPO.md](archive/2026-09-19/SPIKE-MONOREPO.md),
+whose closing note records what the plan got wrong — chiefly that its
+strongest argument, the reach of the enforcing checks, only became true after
+both checkers were changed to discover workspace packages.
+
+The section below is kept for the middleware decision it records, which is
+still the reason there is no `packages/middleware`.
+
+## Accepted: monorepo first — middleware withdrawn rather than consolidated
+
+The maintainer confirmed that monorepo work is starting now. The earlier
+recommendation to keep repositories separate for now is superseded.
+
+**Reversed 2026-09-19: the middleware half of this decision no longer applies.**
+This section used to say "move middleware into the monorepo as its own package
+first, preserving its existing API and behavior," and explicitly: "do not
+unpublish or retire the middleware package as part of the initial move."
+That instruction was overtaken. `@jimhoyd/urlcode-middleware` has been
+**unpublished** from npm at `0.1.0-alpha.2` and `jimhoyd-com/urlcode-middleware`
+**deleted** — the package was withdrawn outright instead of migrated, so there
+is no `packages/middleware` to create and no subsequent fold-into-core step.
+The reversal is recorded here rather than deleted because the instruction it
+replaces was explicit, and a reader who remembers it should be able to see that
+it was changed deliberately and not simply forgotten.
+
+Nothing was lost in capability terms: per-route middleware is **native to
+core** via the `middleware:` array ([MIDDLEWARE.md](MIDDLEWARE.md)), and the
+deleted package only ever offered the same behavior through the extension
+seam. Trust remains the default and explicit sandbox choices keep their
+meaning. The generic extension wrapping hook (`ExtensionInstance.middleware`,
+`RuntimeExtension.cacheSensitive`) stays in core's contract for other
+extensions — it is no longer exercised by any shipped package, which is worth
+knowing before it is assumed to be covered. Static targets continue rejecting
+request-time middleware because there is no server to run it.
+
+Migration scope is therefore **core, auth, admin and UI**. Template and the
+distribution tap stay outside that package move. The observed stale peer pins
+and checkout-limited guidance checks strengthen the case for shared
+verification: carry those checks across the new package paths, since merely
+moving files does not prove every generated skill is covered. The cleanup PRs
+that superseded the earlier zero-open-PR survey have since merged, and a fresh
+survey again reports zero open pull requests across all four in-scope
+repositories — re-run it per repository immediately before that repository
+moves rather than trusting this line.
+
+The [archived monorepo plan](archive/2026-09-19/SPIKE-MONOREPO.md) records
+migration context.
+[Issue 172](https://github.com/jimhoyd-com/urlcode/issues/172), which tracked
+"consolidate middleware into core after moving it into the monorepo," is
+**moot and still open** — there is nothing left to consolidate. It should be
+closed with a pointer to this section. Migration starting is not a claim that
+it has landed.
+
+## Source review baseline
+
+| Repository | Reviewed commit | Code checked |
+|---|---|---|
+| core | `db375bf` | Runtime dispatch, schema normalization, capabilities, static compiler, prerender, MCP and resource generators |
+| auth | `71957dd` | Lifecycle hooks, UI rendering and shared helper imports |
+| admin | `f3b4882` | UI rendering, auth-service integration and shared helper imports |
+| UI | `0e96f7f` | Shared forms, kit/host exports and copied core contract |
+| ~~middleware~~ | `f201f4b` | Extension wrapping, per-entry sandbox dispatch and scaffolding — **repository deleted 2026-09-19; this baseline is unreachable except through the local `urlcode-middleware.bundle`** |
+| template | `4e09e50` | Exact core pin, generated guide and both vendored skills |
+
+The Homebrew tap (`73eaaef`) still selects stable core `0.3.0`; its old trust
+behavior belongs to that pin and must not be rewritten as alpha.2 behavior.
+The other organization tap and Scoop bucket contain Gitroll, not URLCode.
+The deleted documentation repository is historical context, not a second source
+of current contracts; its former GitHub links no longer resolve. This review is targeted source inspection, not an audit of
+every execution path or an independent security assessment.

package/docs/OPERATIONAL-PROOF.md

@@ -1,22 +1,21 @@
 # Operational evidence and deployment acceptance
 
-`node scripts/operational-drills.ts` creates and deletes its own temporary project
-and store. It runs mixed real HTTP requests against native redirects, isolated
-functions and live links while updating records; asserts responses; rejects a bad
-reload; activates and rolls back a configuration; then closes all users of the
-store, explicitly verifies a successful WAL checkpoint, and restores a copied database. It checks integrity, record/version and
-latest durable audit revision. `URLCODE_SOAK_SECONDS=60` selects a longer run
-(1–3600 seconds, default 5). Output is JSON with request count, batch p99 duration,
-RSS and restore time. Batch latency is not per-request p99 or a capacity promise.
-CI runs the short drill on all six supported Node/OS combinations.
+`node scripts/operational-drills.ts` creates and deletes its own temporary
+project. It runs mixed real HTTP requests against native redirects and
+`function` routes; asserts responses; rejects a bad reload; and activates and
+rolls back a configuration. `URLCODE_SOAK_SECONDS=60` selects a longer run
+(1–3600 seconds, default 5). Output is JSON with request count, batch p99
+duration and RSS. Batch latency is not per-request p99 or a capacity promise.
+CI's `verify` job runs the short drill across a 3-Node (22/24/26) × 3-OS
+(Linux/macOS/Windows) matrix, nine combinations, but only on a push to `main`.
+A pull request runs the same drill across all three Node versions on Linux
+only (3 of the 9 combinations); the macOS/Windows legs only run once a PR
+merges, per `.github/workflows/ci.yml`'s matrix.
 
-The container job additionally uses `--disk-full-dir /state` on a disposable
-16 MiB tmpfs. It reserves recovery space, writes until a real volume exhaustion
-failure, checks available disk space, releases the reserve, proves a subsequent
-mutation succeeds, and checks integrity and equal committed link/audit counts.
-Never point this option at production storage: it intentionally consumes up to
-84 MiB of writes in a newly created temporary child directory. The CI mount is
-nonpersistent. An I/O device failure or power cut is a different failure mode.
+Core has no durable store of its own, so this drill has no backup/restore or
+disk-exhaustion exercise: an extension package owning durable state is
+responsible for its own persistence proof. No such package ships today — the
+`urlcode-dynamic-link` package that did has been retired.
 
 ## Required proof on the intended deployment
 
@@ -27,19 +26,16 @@ substitute for it. The deployment owner must record:
 
 | Exercise | Acceptance evidence |
 |---|---|
-| Soak | At least 24 hours at expected peak and burst load through actual TLS/ingress; native/function/live-link mix, slow clients, response correctness, p50/p95/p99, throughput, error/rejection rate, RSS plateau, CPU, FD and disk/WAL growth. Define numerical SLOs before starting |
-| Restore | Restore a consistent backup onto a separate host/volume. Reconcile collection counts, latest committed revisions and audit journal; measure RPO/RTO against agreed targets. Test encrypted backup access and credential recovery |
-| Logical export/restore | Run `links export` against a store under write load, restore it with `links import` onto a separate store, and reconcile record counts and every field. Prove the export's digest verifies, that a truncated stream is rejected, and that stale management ETags are discarded because the restore reassigns versions. An export carries no audit journal, so pair it with a file backup |
-| Kill/restart | Kill server and writer with outstanding reads/writes. Reconcile uncertain mutations by version/request ID, run integrity checks, restore readiness, and prove no duplicate successful conditional writes |
-| Disk/log exhaustion | Fill the actual disposable staging storage type and log destination. Verify bounded 503s, audit/mutation atomicity, alert delivery through an independent sink, reserve-space recovery and readiness after recovery |
-| Rollback | Deploy candidate by exact digest beside last-good, run route assertions, switch ingress, drain, then switch back. Verify configuration/policy compatibility and audit continuity; never downgrade to an unaudited writer |
-| Monitoring | Deliver test alerts for missing logs, sustained errors, pool rejection/failure, low disk, restart storms, backup age and failed readiness to a named on-call owner |
+| Soak | At least 24 hours at expected peak and burst load through actual TLS/ingress; native/function mix, slow clients, response correctness, p50/p95/p99, throughput, error/rejection rate, RSS plateau, CPU and FD growth. Define numerical SLOs before starting |
+| Kill/restart | Kill the server with outstanding requests. Reconcile uncertain mutations by request ID, restore readiness, and prove no duplicate side effects from application code |
+| Rollback | Deploy candidate by exact digest beside last-good, run route assertions, switch ingress, drain, then switch back. Verify configuration/policy compatibility |
+| Monitoring | Deliver test alerts for missing logs, sustained errors, pool rejection/failure, low disk, restart storms and failed readiness to a named on-call owner |
+
+If your deployment adds a durable-state extension, add that extension's own
+backup/restore, logical export/import and disk/log exhaustion exercises to
+this table; core's proof above does not cover them.
 
 Record date, operator, source/app/policy/image digests, topology, hardware/limits,
-commands, duration, synthetic dataset size, raw metrics/log locations, result,
-RPO/RTO and unresolved findings. A reviewer signs the acceptance record; a blank
-record is not a pass. Do not copy only the main file of a live WAL database.
-The executable local drill uses a fully quiesced, explicitly checkpointed database intentionally. A last
-read-only connection can leave WAL frames even after every connection closes;
-closing alone is insufficient proof that the main database file is a full backup. For a
-live-backup system, prove its SQLite-consistent snapshot method separately.
+commands, duration, synthetic dataset size, raw metrics/log locations, result
+and unresolved findings. A reviewer signs the acceptance record; a blank
+record is not a pass.

package/docs/OPERATIONS.md

@@ -45,8 +45,10 @@ docker run --rm --name my-links \
 ```
 
 Replace the example mount with your app. The image uses the unprivileged `node`
-user; ensure mounted config/functions are readable by it. Only operator-owned components such as the optional link store can use writable
-mounts. Sandboxed application functions cannot access mounted files or installed
+user; ensure mounted config/functions are readable by it. Core has no writable
+mount of its own; a future mount-based extension (like `auth`/`admin`, see
+[extensions](EXTENSIONS.md)) is the place for operator-owned writable state.
+Sandboxed application functions cannot access mounted files or installed
 Node packages. The resource values above illustrate
 container limits, not a sizing recommendation; large configuration compilation
 can need more memory. Measure your workload. Tag/redeploy immutable image digests
@@ -63,7 +65,10 @@ at the proxy; they are unauthenticated and reveal route count/config digest.
 
 If functions perform sensitive actions, implement authentication and authorization
 in the application. A short URL is not automatically an access-control mechanism.
-Functions are untrusted and isolated in WASM by default. Keep separate deployment
+Functions and middleware run trusted and unsandboxed by default, in the host
+process with full Node, filesystem and network access; a route that declares
+`sandbox: true` runs isolated in QuickJS/WebAssembly instead (see
+[function security](FUNCTION-SECURITY.md)). Keep separate deployment
 processes/containers and narrowly scoped credentials as additional boundaries.
 Do not expose a public code-upload/multi-tenant service on the basis of the self-hosted release alone
 without separate security review and stronger service-level containment.
@@ -89,14 +94,14 @@ production does not watch or refresh secret values automatically.
 
 - `GET /_urlcode/health`: process liveness.
 - `GET /_urlcode/ready`: 200 when the active snapshot and all function workers
-  are available and configured link-store readers are healthy; 503 while a worker/store
+  are available; 503 while a worker
   is unavailable. Busy workers alone do not
-  mark readiness down. A failed worker or store connection is replaced with
+  mark readiness down. A failed worker is replaced with
   exponential backoff (250 ms doubling to a 30-second ceiling) and readiness
   reports 503 until every slot is serving again. Replacement does not stop, so a
   request-triggered deadline cannot disable functions until an operator restarts;
   a cause that keeps recurring keeps the instance shedding load and needs an
-  operator. Alert on sustained `function_worker`/`link_store_worker` restart events.
+  operator. Alert on sustained `function_worker` restart events.
 - Probes are answered from their own admission budget (16 by default,
   `--max-in-flight-health`), so they stay available while the application is
   saturated without being an unmetered endpoint. They are unauthenticated and
@@ -125,11 +130,15 @@ production does not watch or refresh secret values automatically.
   admitted through response completion; excess requests receive 503. Health probes
   remain available under admission saturation. A 15-second socket inactivity
   timeout closes stalled readers/writers. Proxy timeouts/rate limits still matter.
-- Functions: 2 concurrent workers (`--workers`), no queue, 5-second deadline
-  (`--function-timeout-ms`), 1 MiB buffered response (`--max-response-bytes`) and
-  16 KiB response headers. Saturation 503; timeout 504; error 502.
+- Functions: a `sandbox: true` route gets 2 concurrent workers (`--workers`),
+  no queue and a 5-second deadline (`--function-timeout-ms`); a trusted route
+  (`sandbox` false or absent, the default) shares the in-flight admission cap
+  instead of a worker pool and races the same deadline. Either mode buffers
+  1 MiB of response (`--max-response-bytes`) and 16 KiB response headers.
+  Saturation 503; timeout 504; error 502.
   QuickJS guests have a 32 MiB heap and 512 KiB stack budget and no network or
-  host capabilities. Outer workers have additional V8 limits. Total process/WASM
+  host capabilities; a trusted route has neither budget and full Node access.
+  Outer workers have additional V8 limits. Total process/WASM
   memory still needs deployment-level limits; do not equate guest budget with RSS.
 
 `urlcode serve`/`dev` and the JavaScript server API both configure workers,
@@ -140,24 +149,14 @@ deployment controls, not portable route behavior. Horizontal replicas
 must use identical application/config versions and secret bindings. In-memory
 function state is reset after every invocation, not durable/shared application state.
 General application storage needs a future explicit capability broker; no
-storage/network access is exposed to the guest. The optional native
-[link store](DYNAMIC-LINKS.md) supports live short-link records on one host.
+storage/network access is exposed to the guest. Core no longer has a native
+link store, and the `urlcode-dynamic-link` extension package that replaced it
+has been retired and unpublished.
 
 The health version combines route-definition and asset-representation digests;
 it does not identify the complete function/runtime release. Record runtime commit,
 application commit, dependency locks and image digest in your deployment system.
 
-## Optional dynamic-link deployment
-
-Keep SQLite and management tokens outside the application, in a private durable
-local directory. Initialize through `links init/create`, bind public serving with
-`--link-store`, and expose management on a separate private listener. Restrict
-its token to your trusted backend; apply ingress limits and backups. Public
-serving opens read-only pools; management has a separate writer and read pool.
-Budget connections across processes and monitor writer health separately. See
-[dynamic-link operations](DYNAMIC-LINKS.md). Multiple host replicas must not share
-this file over a network filesystem; no distributed adapter is included yet.
-
 ## Deployment and rollback procedure
 
 1. Build a candidate from pinned runtime/application revisions and lockfiles.
@@ -174,7 +173,7 @@ this file over a network filesystem; no distributed adapter is included yet.
 This is an operator procedure, not an implemented deployment control plane.
 Rollback cannot undo a function's external side effects or migrate an app's
 state automatically. Plan those independently. Keep Git definitions backed up;
-back up any app-owned persistent state separately. YAML routes require no database; dynamic link records require separate backups.
+back up any app-owned persistent state separately. YAML routes require no database.
 
 ## Capacity and incident planning
 
@@ -200,11 +199,3 @@ adapter is made by the current release.
 The [2026-09-16 internal audit](SECURITY-AUDIT.md) records fixes, regression evidence
 and remaining security/operational gates. This is not an independent assessment.
 
-## Management hardening baseline
-
-Management is now restricted to literal loopback addresses. Prefer `--auth-file`
-for individual expiring, revocable credentials with collection/action scopes.
-Every successful built-in store mutation has an atomic, durable SQLite audit row;
-HTTP request logs remain best effort. See [management security](MANAGEMENT-SECURITY.md)
-for policy examples, compatibility, archival and rollback requirements, and
-[operational proof](OPERATIONAL-PROOF.md) for executable recovery drills.

package/docs/POLICIES.md

@@ -3,9 +3,10 @@
 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](MIDDLEWARE.md), [function security](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](MIDDLEWARE.md), [function security](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
@@ -20,7 +21,7 @@ compiled and the request path is unchanged. Each policy has its own page:
 | `cache` | [cache](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](SPIKE-EXTENSIONS.md). Operators who need behavior the
+[extensions spike](archive/2026-09-19/SPIKE-EXTENSIONS.md). Operators who need behavior the
 declarative block cannot express pass host [plugins](PLUGINS.md) in code; plugins
 are never named in YAML.
 
@@ -40,11 +41,29 @@ routes:
 ```
 
 `policies` at the top level sets project defaults; `routes.<path>.policies`
-adjusts them for one route. One route-level short form exists: `auth`, which
+adjusts them for one route. Two route-level short forms exist. `auth`
 expands to `policies.extensions.auth` when the project declares an auth
-[extension](EXTENSIONS.md). The pattern is reserved for `cache`: a route-level
-`cache: {strategy, maxAge}` may later expand to `policies.cache` the same way,
-but it is not implemented, and `policies.cache` is the only cache form today. Both accept the same keys: `profile` plus one entry
+[extension](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
+direct `policies.cache` on the same route (use one form):
+
+```yaml
+routes:
+  /feed:
+    function: { source: functions/feed.mjs }
+    cache: { strategy: swr, maxAge: 30 }   # expands to policies: { cache: {...} }
+```
+
+Both accept the same keys: `profile` plus one entry
 per policy, each either an object or `false`. Unknown keys fail validation, as
 everywhere in the project format. The
 [field reference](YAML-REFERENCE.md) lists every accepted field with its

package/docs/PRERENDER.md

@@ -2,8 +2,10 @@
 
 Render a project's function and middleware routes once, at build time, into a
 project whose routes are all native `page` handlers. The published site answers
-from prevalidated byte buffers: no guest code runs to serve a request, so the
-sandbox, its deadline and its memory budget are not on the request path at all.
+from prevalidated byte buffers: no guest code runs to serve a request at all,
+so whatever execution mode the source routes used — trusted by default, or
+isolated QuickJS/WASM where a route declares `sandbox: true` — along with its
+deadline and memory budget where sandboxed, is not on the request path.
 
 The shared orchestration ships as a build helper, `@jimhoyd/urlcode/prerender`, and the
 runnable recipe is [`examples/prerender`](../examples/prerender/README.md), which
@@ -14,7 +16,7 @@ and no capability.
 ## Why render ahead of time
 
 A function response body is readable by middleware through `text()`. A native
-`page`, `static`, `download`, `redirect`, `respond` or `link` body is not — that
+`page`, `static`, `download`, `redirect` or `respond` body is not — that
 opacity is a deliberate contract, not a gap, and it is what keeps native file
 serving free of guest code. See [middleware](MIDDLEWARE.md).
 
@@ -24,7 +26,7 @@ and publish the result:
 
 ```
 function + template middleware  ──render once──▶  HTML file  ──▶  page route
-        (sandbox, build time)                                   (no sandbox)
+   (trusted or sandboxed, build time)                        (no guest code)
 ```
 
 The alternative — reading Markdown through `next().text()` on a native route —
@@ -111,9 +113,11 @@ specifically:
   instead of hanging on its worker threads.
 
 The helper is operator build tooling. It runs in Node with normal filesystem
-access because it is not guest code; nothing here gives the sandbox a filesystem,
-and no host-code fallback is introduced. It is a separate package export from the
-runtime for that reason. Review it as you review any deployment tooling.
+access because it is not guest code; it does not itself widen a source route's
+declared execution mode — a route with `sandbox: true` still renders isolated,
+with no filesystem, and no host-code fallback is introduced for it. It is a
+separate package export from the runtime for that reason. Review it as you
+review any deployment tooling.
 
 ## Assembling a site
 
@@ -165,7 +169,7 @@ service and redirect; provider asset adapters are not implemented.
 
 The first two rows above are the sandbox's snapshot budgets: at most 127 guest
 modules and 4 MiB of module source in one snapshot. They are deliberate — part
-of what [function security](FUNCTION-SECURITY.md) promises about untrusted guest
+of what [function security](FUNCTION-SECURITY.md) promises about sandboxed guest
 code — and the render step does not relax them for trusted generated content.
 Serving a project that crosses either still fails at startup, naming the module
 that crossed it:
@@ -196,8 +200,9 @@ Two consequences worth knowing:
   and their imports exceed the budgets cannot be split, and fails with the
   collector's message. That is a route to make smaller, not a pass to add.
 
-The [urlcode-docs showcase](https://github.com/jimhoyd-com/urlcode-docs) renders
-62 documentation pages this way.
+The `urlcode-docs` site rendered 62 documentation pages this way. That
+repository has since been deleted, so no link is given; the runnable
+version of the same pattern is [`examples/prerender`](../examples/prerender/README.md).
 
 ## Larger sites: generating the source project
 
@@ -219,9 +224,8 @@ things to hold onto:
   interpolates, but content injected as raw HTML is published as written. Whatever
   produces that HTML owns its safety.
 
-The [urlcode-docs showcase](https://github.com/jimhoyd-com/urlcode-docs) builds
-its site this way. That is a working integration, not a deployment or performance
-claim.
+The `urlcode-docs` site built itself this way before that repository was
+retired. It was a working integration, not a deployment or performance claim.
 
 ## What this is not
 
@@ -231,3 +235,11 @@ native bodies readable. Not a template engine — the template is ordinary
 middleware you write. Not a CLI command: prerendering is a step inside a build
 that already runs JavaScript, so the helper is a library. Content compilation,
 sanitization, search, asset assembly and deployment stay in the application.
+
+
+Trusted build-time functions and middleware use ordinary Node imports, including
+npm packages and dynamic imports. The pass planner applies source-graph budgets
+only to `sandbox: true` routes; it does not parse trusted modules as sandbox
+code. Page-count and output-byte budgets still apply to both modes. After
+rendering, emit native page/file routes without middleware, then use the static
+build target. Static hosting cannot execute middleware on incoming requests.

package/docs/PROJECT-DIRECTION.md

@@ -6,12 +6,31 @@ under. It describes intent and
 boundaries, not a delivery schedule; the [roadmap](../ROADMAP.md) owns sequence
 and the [readiness register](RELEASE-READINESS.md) owns what is proven.
 
+## Design principle: declarative-first
+
+> Use URLCode's highest-level declarative features whenever possible. Generate custom code only when the framework cannot express the requirement.
+
+This is the default for human authors, coding agents, examples and framework
+changes. Before writing application code, check the installed version's declarative
+primitives, YAML configuration, policies, supported extensions and reusable recipes
+or templates. Prefer the highest-level supported abstraction that satisfies the
+requirement; do not recreate framework behavior in a lower-level handler.
+
+Custom functions or middleware remain valid for application-specific behavior the
+framework cannot express. Keep that code focused, explain the missing capability,
+and report reusable gaps to the owning repository. Never invent YAML fields or
+bypass target limits, sandbox isolation or operator grants to avoid custom code.
+
 ## What URLCode is
 
 A portable runtime for programmable URL behavior. A project declares its public
-URL surface in YAML, adds isolated JavaScript only where declarative handlers are
+URL surface in YAML, adds JavaScript only where declarative handlers are
 not enough, and runs the same definition locally, in a container, or on operator
-infrastructure. The project format is deliberately bounded so a runtime can
+infrastructure. That JavaScript runs trusted, in the host process, like any
+other project code, unless the project isolates a specific route with
+`sandbox: true` (docs/SPIKE-DEFAULT-TRUST-MODEL.md) — a judgment call the
+project makes per route, not a default the runtime imposes on all guest code.
+The project format is deliberately bounded so a runtime can
 validate it, inspect it, test it and eventually carry it across hosting providers.
 
 Git owns route definitions and code. Operators own credentials, storage and
@@ -19,12 +38,18 @@ capability grants. Application data stays in the operator's systems.
 
 ## What URLCode is not
 
-- **Not a URL shortener.** Short links are one handler beside redirects,
-  validated responses, request functions, middleware, pages, static assets and
-  downloads. The [live-link store](DYNAMIC-LINKS.md) is optional and single-host.
-- **Not a general Node web framework.** Guest code runs inside WASM isolation
-  with no ambient filesystem, network or Node APIs. Behavior that cannot be
-  expressed in the bounded contract is rejected rather than emulated.
+- **Not a URL shortener.** Core is redirects, validated responses, request
+  functions, middleware, pages, static assets and downloads. Stored short
+  links are not a core handler; the `urlcode-dynamic-link` extension package
+  that owned them has been retired and unpublished.
+- **Not a general Node web framework.** There is no framework code to write
+  for routing, validation, middleware wiring or policies — those are declared
+  in YAML and enforced by the runtime. Function/middleware code that needs
+  isolation from the host (untrusted input, an unreviewed contribution, a
+  particularly sensitive secret) opts into `sandbox: true`, which runs it
+  inside WASM isolation with no ambient filesystem, network or Node APIs.
+  Behavior that cannot be expressed in the bounded contract of a sandboxed
+  route is rejected rather than emulated.
 - **Not a hosting account system.** There is no end-user identity, billing or
   public account surface. Management is a private operator API.
 - **Not a provider configuration format.** Provider infrastructure settings do
@@ -54,7 +79,7 @@ and the database owns the machinery. One level up, a route should read
 
 ```yaml
 /admin:
-  auth: { required: true, roles: [admin] }
+  auth: { role: admin }
   function: { source: functions/admin.mjs }
 ```
 
@@ -79,7 +104,7 @@ lines an agent generated, how many are the idea and how many are plumbing. A
 traditional build might be 2,900 lines of business logic inside 18,400; the
 same application on URLCode should be the same 2,900 inside a few thousand.
 Until a reproducible benchmark shows that ratio, the thesis is a hypothesis,
-and [next steps](NEXT-STEPS.md) puts the benchmark before the features.
+and [the roadmap](../ROADMAP.md) puts the benchmark before the features.
 
 ## License
 

package/docs/READINESS.md

@@ -17,14 +17,18 @@ printed, and no remote load-test target is accepted.
 
 ## Inventory and count reconciliation
 
-`routes` reports each configured route's pattern, handler, exact allowed methods
+`routes` reports each configured route's pattern, handler, exact allowed methods,
+execution mode (`sandbox`, with `sandboxReason` when the route declares one)
 and active/disabled/expired state. It includes routes from YAML includes. A
 parameter pattern is one route; its possible URLs are not a finite route count.
 A static mount is one route, even when it contains many files.
 
 `routes --compare previous.json` diffs the current inventory against a saved
 `routes` report: added, removed and changed routes (handler, methods, state,
-middleware count, policies, generated marker and the policy description). It
+execution mode and its reason, middleware count, policies, generated marker and
+the policy description). A route that flips between trusted and sandboxed
+execution is a change, including when its handler is native and only its
+middleware runs project code. It
 prints JSON, or Markdown tables with `--format markdown`, and always exits 0;
 it reports, it does not judge. The [GitHub action](CI.md) posts this diff on
 pull requests.