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

package/docs/OBSERVABILITY.md

@@ -33,16 +33,12 @@ named.
 | `reload` | `status` `ok`/`rejected`; `version` string and `routes` integer on `ok` | `app.reload()` or the development watcher swapped, or refused to swap, the snapshot. |
 | `watch` | `status` `failed` | The development watcher could not fingerprint the project. |
 | `function_worker` | `status` `started`/`restarting`, `slot` integer; `attempt` and `delayMs` integers on `restarting` | A function worker became ready or is scheduled for replacement. |
-| `link_store_worker` | `status` `started`/`restarting`, `readOnly` boolean; `attempt` and `delayMs` on `restarting` | The same for a link-store connection. |
 | `signal` | `outcome` (`accepted`, `delivered`, `failed`, `dropped`), positive `count` | Best-effort webhook totals; no destination, request data or secrets. |
-| `link_observer` | `status` `failed`/`dropped`/`closed`; `reason` `timeout`/`error` on `failed`; `dropped` integer on `dropped`; `queued`, `delivered`, `dropped`, `failed`, `timedOut`, `closed` on `closed` | Only with `linkEvents`: the link collector failed, the queue shed events, or the channel drained at shutdown. |
-| `link_request` | `requestId`, `collection`, `route`, `code` (only with `includeCode`), `method`, `status`, `outcome`, `durationMs` | Delivered to the `linkEvents.observe` function only, after the response is over. It never reaches the log or observers; its `outcome` is counted in the metrics. |
 | `logs_dropped` | `count` integer | The JSON logger shed records because stdout was not writable. Written by the logger itself, so observers do not see it. |
 | `observer` | `status` `failed`, `name` string | An observer hook threw or rejected. Written to the default log only, never to observers. |
 | `throttle` | `route`, `outcome` `allowed`/`exceeded`, `remaining` integer | A throttle decision. `allowed` is logged only in `mode: report`; enforce mode logs refusals. |
 | `agents` | `route`, `list` string, `outcome` `denied`/`reported` | A User-Agent matched a list. The list name is logged, never the header. |
 | `cache` | `route`, `outcome` `hit`/`stale`/`miss`/`store` | A cache lookup or store. |
-| `management_request` | `timestamp`, `requestId`, `collection`, `action`, `authenticated`, `principal`, `status`, `outcome`, `durationMs` | The link-management API (`startLinkApi`), which has its own logger; `principal` is the operator-configured principal id. |
 | `listening` | `address`, `port`, `mode`, `origin` | Printed once by the CLI at startup, not emitted by the server. |
 
 Every event carries `event` (its name). Numbers are JSON numbers, never
@@ -51,11 +47,10 @@ strings.
 ### Privacy guarantees
 
 No event, snapshot or exposition carries a request URL, path, query string,
-header, body, client address, User-Agent string, binding, secret, stored link
-destination or user exception text. `route` is always a configured pattern
+header, body, client address, User-Agent string, binding, secret or user
+exception text. `route` is always a configured pattern
 from reviewed YAML. `requestId` is server-generated unless
-`--trust-request-id` accepts one from a trusted proxy. `code` in
-`link_request` is redacted unless the operator sets `includeCode`. An observer
+`--trust-request-id` accepts one from a trusted proxy. An observer
 that logs should keep the same rule; nothing in an event lets it break it.
 
 ## Observers
@@ -98,12 +93,12 @@ call. A hook that throws or returns a rejecting promise is isolated: the
 request is unaffected, the next observer still runs, `observers.errors` in
 the snapshot increments and one `observer` record goes to the default log.
 Nothing is retried; an observer that needs delivery guarantees owns its own
-queue, like the [link event channel](MONITORING.md#the-link-event-channel).
+queue.
 
 `onMetrics` receives a fresh snapshot every `metricsIntervalMs`
 (`startServer` option, `0` off by default, 1 s to 1 h) and once at `close()`.
-`onClose` runs in reverse order after the runtime and the link channel have
-drained. `app.observers` lists the `{ name, version }` pairs.
+`onClose` runs in reverse order after the runtime has closed.
+`app.observers` lists the `{ name, version }` pairs.
 
 `createRuntime(project, { observers })` takes the same array for embedding
 without the server: the runtime's own sink and counters are then yours, and
@@ -124,7 +119,7 @@ and capped at 10 000 keys.
 
 | Field | Type | Meaning |
 |---|---|---|
-| `version` | gauge | Snapshot shape version, currently `1`. |
+| `version` | gauge | Snapshot shape version, currently `2`. |
 | `uptimeSeconds`, `rssBytes` | gauge | Process facts. |
 | `requests.total`, `requests.byStatusClass.{2xx,3xx,4xx,5xx}` | counter | Application responses, including shed 503s. |
 | `requests.inFlight` | gauge | Requests holding application admission now. |
@@ -135,13 +130,10 @@ and capped at 10 000 keys.
 | `watch.failed` | counter | Development watcher failures. |
 | `functionWorkers.started`, `functionWorkers.restarts` | counter | Worker starts and scheduled replacements. |
 | `functionWorkers.healthySlots`, `functionWorkers.slots` | gauge | Ready slots and configured slots of the serving runtime. |
-| `linkStoreWorkers.started`, `linkStoreWorkers.restarts` | counter | The same for link-store connections. |
 | `policies.throttle.{allowed,exceeded}` | counter | Throttle decisions (see the catalogue for what enforce mode logs). |
 | `policies.agents.{denied,reported}` | counter | Agents decisions. |
 | `policies.cache.{hit,stale,miss,store}` | counter | Cache outcomes. |
-| `linkRequests.{completed,aborted,missing,disabled,expired,invalid_code,invalid_record,unavailable}` | counter | Dynamic link outcomes, counted whether or not `linkEvents` is set. |
 | `signals.{accepted,delivered,failed,dropped}` | counter | Best-effort webhook outcomes; exposed as `signals_total` with outcome labels. |
-| `linkObserver.failed`, `linkObserver.dropped` | counter | Link collector failures and dropped events. |
 | `logsDropped` | counter | Records the JSON logger shed. |
 | `observers.errors` | counter | Observer hooks that threw or rejected. |
 
@@ -171,7 +163,6 @@ urlcode_function_worker_restarts_total 0
 urlcode_function_worker_healthy_slots 2
 urlcode_throttle_total{outcome="exceeded"} 14
 urlcode_cache_total{outcome="hit"} 511
-urlcode_link_requests_total{outcome="completed"} 0
 urlcode_logs_dropped_total 0
 urlcode_observer_errors_total 0
 urlcode_uptime_seconds 86400

package/docs/OPEN-DECISIONS.md

@@ -0,0 +1,212 @@
+# Open decisions
+
+Status: written 2026-09-19 from a review of the nine repositories. Every item
+here is a maintainer decision that documentation cannot make. Each states what
+is actually true today, what the options are, what it costs to leave open, and
+a recommendation. Nothing here is committed scope; the
+[roadmap](../ROADMAP.md) owns sequence and the
+[readiness register](RELEASE-READINESS.md) owns what is proven.
+
+This page exists because several documented positions have drifted apart from
+each other and from the source. The drift is not the decisions themselves — it
+is that they were never recorded in one place where the next contributor, human
+or agent, would look.
+
+## 1. Publish `0.4.0-alpha.2` — decided
+
+**Decided 2026-09-19: publish `alpha.2`.** The recommendation below was taken
+rather than walking back a correct declaration. The alignment is prepared
+across all nine repositories and the order is recorded in
+[the version register](VERSIONS.md); what remains is merging and tagging.
+
+The second hazard was taken with it: `@jimhoyd/urlcode-auth` moves `latest`
+up to `0.1.0-alpha.2` so that a plain `npm install` no longer resolves a build
+older than the floor `@jimhoyd/urlcode-admin` declares. That is a registry
+operation (`npm dist-tag add`), not a source change, and it is listed in the
+release steps.
+
+The original entry, for the record:
+
+> **Today:** the repository source is `0.4.0-alpha.2`. The npm dist-tags are
+> `latest = 0.3.0` and `alpha = 0.4.0-alpha.1`. `alpha.2` carries the
+> trusted-by-default execution change ([the decision](SPIKE-DEFAULT-TRUST-MODEL.md)).
+>
+> **Why it blocks other things:** `@jimhoyd/urlcode-middleware@0.1.0-alpha.1` is
+> published with `peerDependencies: { "@jimhoyd/urlcode": ">=0.4.0-alpha.2" }`.
+> No published core version satisfies that range, so a registry install of that
+> package cannot resolve its peer. The range is correct; the publication order
+> was not.
+>
+> **Recommendation:** publish `alpha.2`. It is the only option that does not
+> require walking back a correct declaration.
+
+## 2. Consolidate the repositories, or commit to the split
+
+**Today:** nine repositories. [The monorepo spike](SPIKE-MONOREPO.md) is
+complete, its layout is marked decided (option A), its migration mechanics and
+sequencing are written, and it has three open questions for the maintainer. It
+has been neither accepted nor rejected. It was drafted for four repositories;
+`urlcode-dynamic-link`, `urlcode-middleware` and `urlcode-short` have appeared
+since.
+
+**Cost of leaving it open:** the migration gets larger with every repository
+added, and the coordination work the spike describes — pinning reviewed peer
+revisions by hand, chasing prose across repositories when a contract changes —
+is paid again on every contract change in the meantime.
+
+**Recommendation:** decide before the next structural change, in either
+direction. A recorded "no, and here is what we do instead about cross-repo
+drift" closes this as well as a yes does.
+
+## 3. One way to attach middleware, or two
+
+**Today:** core has the native `routes.<path>.middleware[]` array.
+`urlcode-middleware` provides the same capability through the extension seam
+and states that core's native array "keeps working unchanged".
+[The layering spike](SPIKE-CORE-LAYERING.md) proposed *extracting* middleware
+to narrow core to YAML plus `function`; what exists is an addition alongside it.
+
+**Why this is a principle question:** the
+[extension model review](SPIKE-EXTENSION-MODEL.md) rejected an earlier design
+for exactly this reason — two ways to protect a route would drift apart — and
+resolved it by removing one. The same test applies here.
+
+**Options:** deprecate the native array on a stated timeline and complete the
+extraction; or keep both and document precisely when each is correct, treating
+the extension as a bounded variant rather than a successor.
+
+**Recommendation:** decide explicitly and write the answer into both
+repositories. Either is defensible; leaving both undescribed is not.
+
+## 4. Where the backlog lives
+
+**Today:** [next steps](NEXT-STEPS.md) holds roughly thirty tracked items
+across nine phases. The repository has one open issue (#58). `AGENTS.md`
+instructs contributors and agents to file what they find as issues on the
+owning repository.
+
+**The contradiction:** the instruction points at the issue tracker; the actual
+plan is a Markdown file that no tracker reflects. A plan document also has no
+state, so items stay written as future work after they ship — which is how
+route-level `auth` came to be described as an invented field in merged agent
+guidance (see item 7).
+
+**Options:** move the phase items into issues and keep the document as the
+narrative that links them; or keep the document as the system of record and
+amend `AGENTS.md` to say so.
+
+**Recommendation:** issues for items, document for sequence. It is the only
+arrangement where "done" is recorded automatically.
+
+## 5. Gate the business suite on evidence
+
+**Today:** [the business suite spike](SPIKE-BUSINESS-SUITE.md) proposes seven
+applications. [Project direction](PROJECT-DIRECTION.md) states the evidence
+test: the framework grows from measured repetition, not from a list of things
+applications might need. Phase 6 of [next steps](NEXT-STEPS.md) says candidate
+areas are built only when the repetition log shows them repeating. The
+repetition log does not exist yet, and the Phase 0 agent benchmark has not been
+run.
+
+**Recommendation:** record on the spike itself that it is gated behind the
+benchmark and the repetition log, or amend the evidence test. Holding both
+positions unannotated makes the stated principle decorative.
+
+## 6. Finish the documentation move, or describe the split
+
+**Today:** `AGENTS.md` states that urlcode-docs is the documentation home and
+the only place readers are sent, that new reader-facing pages go there, and
+that pages still under `docs/` here are being migrated. Roughly forty
+reader-facing pages remain in this repository, several duplicated in
+urlcode-docs.
+
+**Observed consequence:** the same fact drifts between copies. The public
+documentation site carried the correct trusted-by-default contract while
+`docs/OPERATIONS.md` in this repository still described functions as untrusted
+and isolated by default. <!-- trust-model-prose: historical -->
+
+**Options:** finish the migration against a dated list; or state which pages
+stay here permanently and why, and add a check that fails when a new
+reader-facing page appears beside them.
+
+## 7. A review window, and a check that does not need one
+
+**Today:** [governance](../GOVERNANCE.md) records one maintainer, a required
+approval count of zero, and that "an independent human review is not yet
+guaranteed". Pull requests and CI are mandatory; a second pair of eyes is not.
+
+**What that permitted, concretely:** on 2026-09-19, three coordinated pull
+requests (urlcode#158, urlcode-template#6, urlcode-docs#17) opened and merged
+within nine minutes. They recorded a genuine improvement — the declarative-first
+principle, propagated to every copy in one change — and alongside it the
+statement that agents must "never invent an `auth` field". Route-level `auth` is
+implemented: it is defined in `schemas/urlcode.schema.json` as a short form
+expanding to `policies.extensions.auth`, expanded in `src/config.ts`, typed in
+`src/types.ts`, and asserted in `test/recipes.test.ts`. The guidance now
+instructs agents away from a supported declarative short form and toward the
+lower-level policy form — the opposite of the principle the same change
+introduced — in the generated project guide, the bundled starter, both
+authoring skills, the packaged plugin skill and the two generated `llms` files.
+
+Nothing failed. Lint, typecheck, generated-resource checks, the package smoke
+test and 501 tests all passed, because no check compares what the guidance
+claims against what the schema implements.
+
+**The check, now implemented.** `scripts/check-guidance-claims.ts` runs inside
+`npm run check` and exits non-zero on a contradiction between agent-facing
+guidance and the schema, so this class of error fails CI instead of depending on
+a reviewer's attention:
+
+- Inputs: the agent-facing surfaces — `src/agents-guide.ts`,
+  `starters/default/AGENTS.md`, `skills/urlcode/SKILL.md`,
+  `.claude/skills/*/SKILL.md`, `packaging/claude-plugin/skills/*/SKILL.md`,
+  `llms.txt`, `llms-full.txt`, `docs/AI-AUTHORING.md`.
+- Assertion one: every YAML field named as valid in those files resolves in
+  `schemas/urlcode.schema.json`. A guidance file may not teach a field the
+  schema does not accept.
+- Assertion two, the one that would have caught this: no field that the schema
+  *does* define is described as unsupported, invented or nonexistent. Match the
+  negative phrasings deliberately ("never invent", "does not exist",
+  "unsupported field") within a short window of a schema-resolvable field name.
+- Assertion three: handlers listed as available match the capability catalog,
+  so a removed handler (`link`, extracted to `urlcode-dynamic-link` in
+  `f7dbe54`) cannot linger in generated guidance.
+- Exits non-zero on violation, with a documented `<!-- guidance-claims: ignore -->`
+  marker for text that is deliberately about another version. Verified against
+  both regressions: reintroducing the "never invent an `auth` field" sentence
+  fails the check, and adding the removed `link` handler to the inventory line
+  fails it.
+
+What remains a decision: whether `npm run check` membership is enough, or the
+check should also be named in the repository's required status checks so it
+cannot be bypassed.
+
+**Recommendation:** the check is in; keep it required. It is the part that does
+not depend on a person being available. Whether to
+also raise the required approval count is a separate call, and
+[governance](../GOVERNANCE.md) already states the condition — when the trusted
+maintainer team grows.
+
+## 8. One publishing convention
+
+**Today:** `urlcode-dynamic-link` and `urlcode-middleware` keep
+`"private": true` on their main branch and drop it in the release commit;
+`urlcode-auth`, `urlcode-admin` and `urlcode-ui` do not. All are published.
+Both practices are defensible; having both means the flag no longer indicates
+publication state.
+
+**Recommendation:** pick one and state it where release process is documented.
+
+## 9. Adjudicate the vendored skill drift
+
+**Today:** `npm run check:downstream-skills` reports that `urlcode-template`'s
+vendored authoring and operations skills differ from core's current `main` by
+79 and 91 lines. The report is advisory by design and never fails, because a
+downstream repository can correctly pin an older published core version
+([issue 155](https://github.com/jimhoyd-com/urlcode/issues/155)).
+
+**What is missing:** the judgment the report defers. No one has read the two
+diffs and recorded which side is right for the template's `0.4.0-alpha.1` pin.
+
+**Recommendation:** review both diffs once, record the verdict, and re-run the
+report when the template repins.

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: a future extension package owning durable state
+(such as the planned `urlcode-dynamic-link`) is responsible for its own
+persistence proof once it exists.
 
 ## 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. Stored short links are moving
+to a future `urlcode-dynamic-link` extension package, not yet published; core
+no longer has a native link store.
 
 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

@@ -40,11 +40,22 @@ 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). `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

@@ -14,7 +14,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).
 
@@ -165,7 +165,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:

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 moving to a future `urlcode-dynamic-link` extension package
+  (mount-based, like `auth`/`admin`, not yet published), not a core handler.
+- **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 }
 ```