@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/docs/OBSERVABILITY.md

@@ -33,15 +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. |
-| `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. |
+| `signal` | `outcome` (`accepted`, `delivered`, `failed`, `dropped`), positive `count` | Best-effort webhook totals; no destination, request data or secrets. |
 | `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
@@ -50,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
@@ -97,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
@@ -123,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. |
@@ -134,12 +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. |
-| `linkObserver.failed`, `linkObserver.dropped` | counter | Link collector failures and dropped events. |
+| `signals.{accepted,delivered,failed,dropped}` | counter | Best-effort webhook outcomes; exposed as `signals_total` with outcome labels. |
 | `logsDropped` | counter | Records the JSON logger shed. |
 | `observers.errors` | counter | Observer hooks that threw or rejected. |
 
@@ -151,8 +145,8 @@ aggregation across replicas is the scraper's job.
 
 ## Prometheus exposition
 
-`startServer({ metrics: true })` serves `GET /_urlcode/metrics` as
-`text/plain; version=0.0.4`, rendered from the same snapshot by
+`startServer({ metrics: true })`, or `urlcode serve --metrics` on the command
+line, serves `GET /_urlcode/metrics` as `text/plain; version=0.0.4`, rendered from the same snapshot by
 `renderPrometheus(snapshot)`, a pure function you can also call yourself.
 Every metric is prefixed `urlcode_`; counters end in `_total`; the only labels
 are `status_class`, `route` and `outcome`.
@@ -169,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,42 +1,41 @@
 # 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
 
-Local/CI passes do not close these gates. The deployment owner must record:
+Local/CI passes do not close these gates. `urlcode verify-deployment --target`
+([deployment checks](DEPLOYMENT-CHECKS.md)) records that the deployed responses
+match the project and is the first step of the rollback drill below, not a
+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

@@ -35,18 +35,20 @@ The supplied image packages the runtime; it does not copy your application or
 local secret files. Build from the reviewed runtime checkout:
 
 ```sh
-docker build -t urlcode:0.2.0 .
+docker build -t urlcode:0.3.0 .
 docker run --rm --name my-links \
   --read-only --cap-drop ALL --security-opt no-new-privileges \
   --memory 512m --cpus 1 --pids-limit 128 \
   -p 127.0.0.1:3000:3000 \
   -v "$PWD/starters/default:/project:ro" \
-  urlcode:0.2.0
+  urlcode:0.3.0
 ```
 
 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,30 +149,23 @@ 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.
 2. Validate its config/bindings and run local HTTP tests without external redirects.
 3. Start it on an alternate private port/container. Check readiness and representative
-   redirect/function behavior through the intended proxy configuration.
+   redirect/function behavior through the intended proxy configuration:
+   `urlcode verify-deployment --project . --target https://candidate.host` compares
+   version, fixtures, policy headers and site files with the project
+   ([deployment checks](DEPLOYMENT-CHECKS.md)).
 4. Switch proxy traffic after checks pass. Drain the previous instance before stopping.
 5. If checks or observed behavior fail, route traffic back to the retained previous
    instance/image and its compatible secret bindings.
@@ -171,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
 
@@ -197,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/PLUGINS.md

@@ -42,6 +42,7 @@ const auditPlugin = {
   name: 'audit',                 // ^[a-z][a-z0-9-]{0,63}$, unique per runtime
   version: '1.0.0',              // any string up to 64 characters
   targets: ['node', 'vercel'],   // subset of node, vercel, aws, cloudflare
+  credentialHeaders: ['Cookie', 'Authorization'], // optional; withheld from guests
   async onActivate(runtime) {},                    // may throw to refuse activation
   async onRequest(request) {},                     // return a result to short-circuit
   async onResponse(request, result) { return result; }, // return the result to send
@@ -112,6 +113,42 @@ it reaches the guest: there is no sandbox handle, no deadline, no `env` or
 deadline, read or write guest state, or obtain a binding the operator policy
 did not grant to the route.
 
+## Withholding credential headers from application code
+
+An operator plugin may declare `credentialHeaders: ['Cookie', 'Authorization']`.
+Each list contains at most 64 unique HTTP header names, compared
+case-insensitively, each at most 128 characters. The runtime validates the lists
+and captures their union before activation hooks run. Later mutation of a plugin
+object does not weaken the running boundary; a reload captures a new declaration.
+No YAML key can enable, disable or override this operator setting.
+
+The union applies to every matched route in that runtime, including public
+functions and guest middleware on native routes. Before processing application
+inputs, the runtime makes a separate header copy and removes those names. Guest
+`Request.headers`, `ctx.inputs.header` and header-derived `ctx.args` receive no
+corresponding values. Header schema defaults are also omitted from the guest
+context for those names. A required protected header input without a default fails with
+`Missing required parameter`, even when the original request supplied it;
+projects should not declare credential inputs that the operator withholds.
+Native redirect query mappings also use this sanitized application context, so
+they cannot reflect a withheld header into a response visible to middleware.
+Selecting `Cookie` removes the entire header, not just one named cookie.
+
+Host request/response/error hooks, first-party policies and request-body checks
+retain the original headers. The runtime does not mutate the caller's Headers
+object. Existing applications behave exactly as before when no plugin declares
+credential headers. Plugins still need at least one lifecycle or request hook;
+a header list alone is not a complete plugin.
+
+This is a data boundary, not authentication, authorization or cache protection.
+It does not create a principal, validate a token, protect a route, or prevent
+shared caching. In particular, withholding Cookie or Authorization from guests
+does not make a personalized response safe to cache. Operators must separately
+configure the appropriate authentication and cache behavior. It also does not
+redact URL/query/body content, explicit binding grants, logs or values deliberately
+reflected by trusted host plugins. Host plugins retain full access to the request
+and remain trusted operator code.
+
 ## Results
 
 A result is what the runtime writes: