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

package/docs/FUNCTION-SECURITY.md

@@ -1,11 +1,75 @@
-# Untrusted function execution
-
-Application code is untrusted even when it came from your own Git repository.
-A compromised dependency, template or contribution must not inherit the URLCode
-server's authority. Alpha.2 replaces alpha.1's Node execution entirely. There
-is no `unsafe`, `trusted` or automatic host-execution fallback.
-
-## Boundaries enforced now
+# Function execution: trusted by default, sandboxed opt-in
+
+`function` and `middleware` routes run **trusted and unsandboxed by default**:
+in the host process, with full Node, filesystem and network access, exactly
+like any other project code (docs/SPIKE-DEFAULT-TRUST-MODEL.md). This is a
+deliberate, maintainer-decided reversal of alpha.2's blanket sandbox — see
+that spike document for the full rationale. It is a call the project makes,
+not a property the runtime can verify: URLCode cannot know whether your code
+is safe to trust, only whether you asked for isolation.
+
+Declare `sandbox: true` on a route when its code specifically warrants
+isolation: it processes input from a source the project doesn't fully trust
+(a third-party webhook payload, for example), it is a contribution nobody on
+the team has reviewed, or it handles a secret sensitive enough that a bug in
+that one route should not be able to reach the rest of the process or the
+filesystem. A sandboxed route runs in QuickJS inside WebAssembly, in a
+separate worker thread, with none of the host access described below — its
+guarantees are unchanged from every earlier release and are described in
+full in the rest of this document. Absence of `sandbox` (or `sandbox: false`)
+means trusted; there is no separate `unsafe`/`trusted` field to opt back into
+the old sandboxed-by-default behavior — set `sandbox: true` per route instead.
+
+**Either way, binding grants are unaffected.** Trusting a route's code by
+default does not grant it any `env`/`secrets` it was not explicitly declared
+in YAML and approved by an operator policy pinned to the project revision
+(see "Granting selected bindings" below). A trusted function only *can* do
+more with Node once it runs — it does not receive anything more than a
+sandboxed one would.
+
+This is a claim about `context`/`context.secrets` injection, not an
+access-control guarantee on trusted code. The binding grant governs only what
+URLCode hands a route through `context`; it does not restrict what trusted
+(non-`sandbox`) code can independently do, because that code has full Node
+access by design. A trusted function can read `process.env`, open files or
+make network calls on its own regardless of what its route was or was not
+granted — withholding a binding grant limits what URLCode gives the code
+through `context`, not what the code itself, running with full Node access,
+can go and get. A sandboxed route has no such independent access: the guest
+API is all it has, so its binding grant *is* effectively its whole reach into
+the environment. Trusted code's reach is not bounded that way; treat the
+grant as scoping `context`, not as scoping the process.
+
+## Migrating to the trusted default
+
+If you are upgrading a project from a release before this change shipped:
+**every existing `function` and `middleware` route silently changes execution
+mode**, from sandboxed to trusted, unless it already has (or you add)
+`sandbox: true`. This is a real behavior change on upgrade, not a
+documentation update — a route that used to run with no filesystem or network
+access will, after the upgrade, run with full Node access unless you opt it
+back into the sandbox.
+
+Before upgrading:
+
+- List every `function` and `middleware` route in the project.
+- For each one, decide whether you fully trust that code to run in-process
+  with full Node/filesystem/network access — the same trust you would extend
+  to any other code you deploy to that server.
+- Add `sandbox: true` explicitly to any route whose code you do not fully
+  trust, that processes input from a source you don't control, or that handles
+  a secret binding you want isolated — before you upgrade, not after.
+- Routes you do want running trusted need no change; that is now the default.
+
+The change moves the sandbox from an unconditional guarantee to an explicit,
+per-route choice, mainly for performance: the previous blanket sandbox capped
+concurrency at two workers with no queue shared across every function route on
+the server, which does not scale to real concurrent traffic. It also brings
+first-party code in line with how the rest of the Node ecosystem treats
+deployed application code. The sandbox itself is unchanged for routes that opt
+into it; only the default for routes that declare neither option has changed.
+
+## What "sandboxed" (`sandbox: true`) still guarantees
 
 - Function sources are parsed/snapshotted without importing them into Node.
 - Code runs in QuickJS inside WebAssembly, with no host JS functions/objects
@@ -22,9 +86,79 @@ is no `unsafe`, `trusted` or automatic host-execution fallback.
   Operator grants are exact-name, route-scoped and pinned to configuration/source.
 
 The guest API is intentionally narrower than Node or full Fetch; see the
-[implemented contract](SPECIFICATION.md). Existing functions using Node/network
-or binary/stream APIs must be rewritten for the supported profile or wait for a
-reviewed capability implementation. Redirects need none of this machinery.
+[implemented contract](SPECIFICATION.md). A function moving from trusted to
+`sandbox: true` that uses Node/network or binary/stream APIs must be rewritten
+for the supported guest profile, or stay trusted. Redirects need none of this
+machinery either way.
+
+This engine — worker spawning, the module-allowlist walk, the two-layer
+deadline, `maxBytes` and response-shape validation — is one implementation
+shared by route dispatch and by `@jimhoyd/urlcode/sandbox`'s `SandboxPool`,
+the public primitive an extension package uses to run a project-supplied hook
+through this exact isolation when the project's own config declares
+`sandbox: true` on it (see [EXTENSIONS.md](EXTENSIONS.md#project-level-lifecycle-hooks)
+and [TYPESCRIPT.md](TYPESCRIPT.md)). Every guarantee above applies identically
+through that entry point; there is no separate, weaker sandbox for extensions
+to reach for, and no "trusted" mode exported there — trusted execution needs
+no primitive at all (docs/SPIKE-DEFAULT-TRUST-MODEL.md).
+
+## What the trusted default can and can't do
+
+A trusted route (no `sandbox`, or `sandbox: false`) has none of the guest
+restrictions above:
+
+- Full Node built-ins, `process`, the filesystem, `fetch`, sockets, workers
+  and npm packages are available, exactly as in any other Node module.
+- Module resolution is ordinary Node ESM resolution: bare specifiers, dynamic
+  `import()` and node_modules all work. There is no dependency-graph allowlist
+  and no per-module/total source-size budget (function-sources.ts's
+  `MODULE_LIMIT`/`MODULE_BYTE_LIMIT`/`TOTAL_BYTE_LIMIT` apply only to what a
+  sandboxed snapshot bundles).
+- Node's own module cache is shared across invocations and across the whole
+  process; there is no fresh heap per call. Module-level state persists
+  between requests exactly like an ordinary long-running Node server, so a
+  trusted function that mutates shared/global state affects later requests
+  the way hand-written server code would.
+- There is no worker-thread deadline that force-terminates a stuck call. A
+  trusted invocation races a configurable timeout, but that race can only
+  reject the *call*; it cannot preempt code that blocks the event loop
+  synchronously. See [capacity](CAPACITY.md) for what this means for one slow
+  or hung trusted route's effect on the rest of the process.
+- A snapshot reload re-imports a trusted route's own entry file fresh (each
+  reload gets its own cache-busted module registration), so editing the
+  `source` file a route declares and reloading picks up the change, the same
+  as the sandboxed pool rebuilding from scratch. A file that entry file
+  merely *imports* is not similarly busted: Node's own module cache is
+  keyed by the resolved URL of that import statement, which this runtime
+  does not rewrite, so an edited dependency two files deep from the route
+  keeps serving its old content until the process restarts. Restructure a
+  route so the code you expect to hot-reload is the declared entry file
+  itself, or restart rather than reload after editing a trusted route's
+  dependencies. A `sandbox: true` route has no such gap: reload always
+  rebuilds its whole snapshot, dependencies included.
+
+What does **not** change with trust: `args` are still exactly the validated
+values the route declares (never raw request input), and `env`/`secrets` are
+still exactly what the route's YAML requests and an operator policy grants,
+pinned to the project revision — trust changes where code runs, not what
+it is handed *through `context`*. It does not change what the code can go get
+on its own once it is running; see "binding grants are unaffected" above for
+that distinction.
+
+## Trusted code, not trusted requests
+
+"Trusted" describes the code's authorship — first-party project code you
+reviewed and deployed — not the requests it handles. Every request, in either
+mode, still carries client-controlled path, query, header and body data that is
+exactly as adversarial as it always was. Running trusted means that code
+executes with full Node access if it mishandles that input; it does not mean
+the input itself became safe to trust. Declare `parameters` and `request.body`
+validation in YAML, check `args` and any other request data again inside
+function/middleware code, and implement your own authentication and
+authorization — no route, sandboxed or trusted, adds automatic auth.
+`sandbox: true` narrows what a bug or an unreviewed dependency in the *code*
+can do with that same request data; it is not a substitute for validating or
+authenticating the request itself.
 
 ## Granting selected bindings
 
@@ -63,26 +197,28 @@ urlcode serve --project /srv/my-links --policy /etc/urlcode/my-links-policy.json
 
 `dev`, `test` and `validate --local` use the same policy rules even for `.env.local`.
 The JavaScript API accepts an equivalent operator-supplied `permissions` object.
-Every config/module change invalidates the grant; inspect/review the new revision
-before updating the operator file. Policies are read at startup, not hot-reloaded.
-A failed development candidate leaves the previous approved snapshot running.
+Every config change invalidates the grant, and so does a module change within
+what the approval digest actually hashes: for a sandboxed route, its
+middleware/function sources and their full dependency graph; for a trusted
+route, only its own entry-file source (see the next paragraph — a trusted
+route's transitive dependencies are explicitly **not** part of that digest).
+Inspect/review the new revision before updating the operator file. Policies
+are read at startup, not hot-reloaded. A failed development candidate leaves
+the previous approved snapshot running.
 
 Granting a secret deliberately makes it available to every middleware and function
-in that route. Middleware sources and their dependencies are included in the
-approval digest; changes invalidate grants. The whole chain shares one fresh
-guest heap and one execution deadline. Code can
-include any granted data in its HTTP response. A sandbox cannot promise secrecy
-from code authorized to read a value. Minimize grants, use scoped/short-lived
-credentials and revoke/restart when needed. Other routes get none of that context.
-
-## Native live-link storage
-
-The optional `link` handler can read an explicitly operator-bound collection.
-Its database is outside the project and public serving opens it read-only. This
-is a native handler, not a guest capability: functions/middleware receive no SQL,
-filesystem handle, database path or management token. Native link data changes do
-not authorize new code or bindings. Management requires a separate operator CLI
-or token-protected listener. See [dynamic links](DYNAMIC-LINKS.md).
+in that route, trusted or sandboxed alike. A sandboxed route's middleware
+sources and their full dependency graph are included in the approval digest,
+as before; a trusted route's own entry-file source is included too, so
+changing that file's content invalidates the grant, but a change to a helper
+module it merely imports does not by itself (see function-sources.ts's
+`collectTrustedSources`) — a known, documented gap versus the sandboxed path's
+full dependency-graph hashing: a trusted route's grant scope is entry-file-only,
+not transitive. Either way, code can include any granted data
+in its HTTP response: neither the sandbox nor the trusted default promises
+secrecy from code that was explicitly authorized to read a value. Minimize
+grants, use scoped/short-lived credentials and revoke/restart when needed.
+Other routes get none of that context.
 
 ## Next capability work
 
@@ -90,9 +226,14 @@ Outbound requests need a host-owned broker with explicit destination/method
 allowlists, private/metadata/loopback-address restrictions, DNS/rebinding defenses,
 redirect revalidation, deadlines and byte/concurrency limits. Application YAML
 must not grant those permissions. Persistent state needs similarly scoped access.
-Until such brokers are implemented and tested, these capabilities are unavailable.
-Provider adapters must preserve this boundary or reject deployment; they cannot
-silently replace sandbox execution with unrestricted Node functions.
+Until such brokers are implemented and tested, these capabilities are unavailable
+to a *sandboxed* route. Provider adapters must preserve a `sandbox: true`
+route's isolation or reject deployment; they cannot silently downgrade a
+route that explicitly asked for the sandbox into unrestricted Node execution.
+(A trusted route, by contrast, already has unrestricted Node execution by
+design on the self-hosted target — see "What the trusted default can and
+can't do" above; non-Node targets refuse `function`/`middleware` entirely,
+trusted or sandboxed, since neither execution mode exists there.)
 
 ## Verification and remaining risk
 

package/docs/INSTALL.md

@@ -6,11 +6,6 @@ pick whichever fits how you already manage tools. All of them require
 TypeScript source (`dist/`, with declarations; see [TypeScript](TYPESCRIPT.md)),
 so the installed `urlcode` command runs `dist/cli.js` and needs no build tool.
 
-Live short-link storage additionally needs a Node build carrying the patched
-SQLite WAL fix. Run `urlcode doctor` after installing and check `liveLinks`;
-everything except live links works on any supported build. See
-[dynamic links](DYNAMIC-LINKS.md#node-build-requirement).
-
 ## npm
 
 ```sh

package/docs/LOAD-TESTING.md

@@ -75,8 +75,8 @@ largest one that makes a number go green.
 
 ## What a passing run does not prove
 
-- **GET and HEAD only.** Function routes with request bodies, live-link writes
-  and the management API are not exercised. `workload` states this in every report.
+- **GET and HEAD only.** Function routes with request bodies are not exercised.
+  `workload` states this in every report.
 - **Redirects are not followed**, so a redirect's destination is never loaded.
 - **One client, one host, no slow peers.** Tail latency under adversarial
   clients, connection churn or packet loss is not measured.
@@ -87,5 +87,5 @@ largest one that makes a number go green.
   runtime and application revisions, host, and command with any figure you keep.
 
 `scripts/operational-drills.ts` covers the adjacent ground — mixed
-native/function/live-link load, an invalid reload, rollback and a quiesced
-backup/restore — as a local proof, never a statement about production.
+native/function load, an invalid reload and rollback — as a local proof,
+never a statement about production.

package/docs/LOCAL-DEVELOPMENT.md

@@ -10,6 +10,9 @@ ship, together with the declarations; `dist` is never committed. Make is an opti
 shortcut layer; npm and the CLI work on Windows, macOS and Linux. No global
 package install, hosting account, database or Docker is needed for the local loop.
 
+For the repository's prose-only checks, CI selection and release helper commands,
+see [the development pipeline](DEVELOPMENT-PIPELINE.md).
+
 ## Try the runtime
 
 From the runtime checkout, `make dev` installs locked dependencies if needed and

package/docs/MIDDLEWARE.md

@@ -2,7 +2,10 @@
 
 Middleware is reusable JavaScript around any route handler. It is optional and
 route-local; plain redirects and assets retain their native fast path when no
-middleware is attached. Adding middleware requires sandbox execution.
+middleware is attached. Middleware runs trusted and unsandboxed by default,
+in-process with full Node access, the same as a `function` route; add
+`sandbox: true` on the route to run the whole chain isolated instead (see
+[trust model and sandbox opt-in](FUNCTION-SECURITY.md)).
 
 ```yaml
 version: "1"
@@ -49,37 +52,45 @@ reading one consumes it for downstream code. There is no `clone()` or streaming
 API; pass parsed data through `context.state` when needed.
 
 Function responses support the existing text/JSON guest API. To transform their
-body, read it and return a new `Response`. Native redirect/respond/link/page/static/
+body, read it and return a new `Response`. Native redirect/respond/page/static/
 download bodies are opaque and cannot be read through `text()` or `json()`.
 Returning the same native response preserves original bytes, including binary
 files, ranges and HEAD lengths. You may add headers, but cannot change its
 original status or existing native headers while preserving that body. To replace
 status, destination or content, return a new `Response` instead. Replacement
-responses follow the normal sandbox text/JSON and size limits. To wrap a shared
+responses follow the normal response size limits, and (on a `sandbox: true`
+route) the guest's text/JSON constraints. To wrap a shared
 template around file content, render it through a function at build time and
 publish the result: see [prerendering](PRERENDER.md).
 
 Route selection, enabled/expiry checks, methods and input/body validation run
 before middleware. Their errors do not pass through the chain. A missing file
-inside a selected static mount is a downstream 404 response. Stored-link lookup
-errors (missing, disabled, expired or unavailable store) precede middleware. YAML
+inside a selected static mount is a downstream 404 response. YAML
 `response.headers` apply last and override matching middleware headers. Runtime
 framing and asset metadata protections still apply.
 
-## Isolation and testing
+## Trust, isolation and testing
 
-The whole chain and handler run in one fresh QuickJS/WASM guest with one memory
-budget and one deadline. No Node, filesystem, shell, fetch or ambient environment
-is exposed. Modules can only access this route's declared dependency graphs.
-All middleware receive that route's approved bindings, so review the whole chain;
-source changes invalidate grants. See [security](FUNCTION-SECURITY.md).
+The whole chain and handler run as one unit, in one execution mode, chosen by
+the route's `sandbox` field — not a per-middleware-entry choice. By default
+(`sandbox` false/absent) that means trusted, in-process execution with full
+Node access and no fixed worker-pool ceiling. With `sandbox: true` it means
+one fresh QuickJS/WASM guest with one memory budget and one deadline: no
+Node, filesystem, shell, fetch or ambient environment, and modules limited to
+this route's declared dependency graph. Either way, all middleware on a route
+receive that route's approved bindings, so review the whole chain; source
+changes invalidate grants. See [trust model and sandbox opt-in](FUNCTION-SECURITY.md).
 
-Invalid responses and repeated `next()` calls fail with 502, exhausted capacity
-returns 503, and the shared deadline returns 504. Middleware cannot extend the
-deadline or catch the outer worker termination. Forgotten downstream work is
-still drained within that deadline.
+Invalid responses and repeated `next()` calls fail with 502, and the deadline
+returns 504 either way. A `sandbox: true` chain also sheds load with 503 when
+the shared worker pool is exhausted, and cannot extend the deadline or catch
+the outer worker termination; forgotten downstream work is still drained
+within it. A trusted chain has no worker pool to exhaust (see
+[capacity](CAPACITY.md)), but its deadline is a race against the call's own
+promise rather than a forced kill — it cannot preempt code that blocks the
+event loop synchronously.
 
 Include explicit request fixtures for middleware-wrapped routes: test success,
 early responses, validation failures and every configured method. Audit will
 report missing coverage instead of assuming native handler behavior. Benchmark
-with middleware enabled to measure its actual sandbox overhead.
+with middleware enabled to measure its actual overhead, sandboxed or trusted.

package/docs/MONITORING.md

@@ -19,7 +19,7 @@ analytics from these logs, and adding it would mean logging user data. See
 | Endpoint | Meaning | Alert when |
 |---|---|---|
 | `GET /_urlcode/health` | The process is alive and not shutting down. | It fails at all (`UrlcodeDown`). |
-| `GET /_urlcode/ready` | The active snapshot, every function worker and every configured link-store reader are available. | It fails for longer than replacement takes (`UrlcodeNotReady`). |
+| `GET /_urlcode/ready` | The active snapshot and every function worker are available. | It fails for longer than replacement takes (`UrlcodeNotReady`). |
 
 Both return `{status, version, routes}`. A third endpoint,
 `GET /_urlcode/metrics`, exists only with `startServer({ metrics: true })` and
@@ -38,27 +38,10 @@ configuration digest and route count, so keep them internal.
 | `reload` | `status` (`ok`/`rejected`); `version` and `routes` on `ok` | A `rejected` reload means the last-good snapshot is still serving and a deploy did not take effect. |
 | `watch` | `status` | Development watcher failure; not used by `serve`. |
 | `function_worker` | `status` (`started`/`restarting`), `slot`; `attempt` and `delayMs` on `restarting` | Sustained `restarting` means a function is failing on real traffic. |
-| `link_store_worker` | `status`, `readOnly`, `attempt`, `delayMs` | The same signal for link-store connections. `status: "restarting"` reports an automatic replacement with its backoff; sustained restarts mean the underlying fault is not recoverable. |
-| `link_observer` | `status` (`failed`/`dropped`/`closed`); `reason` on `failed`; `dropped` on `dropped`; the delivery totals on `closed` | Only when an operator enables `linkEvents`. The link event channel below could not keep up or its collector failed. `dropped` means click records were discarded; like `logs_dropped`, anything built on that channel is incomplete while it fires. |
 | `logs_dropped` | `count` | The logger shed records because the collector fell behind. Every other signal is unreliable while this fires. |
 | `observer` | `status` (`failed`), `name` | An in-process observer threw; the request was unaffected. Written to the log only, never to observers. Sustained failures mean the observer's own sink is broken. |
 | `throttle`, `agents`, `cache` | `route`, `outcome`; `remaining` or `list` | Policy decisions; see [policies](POLICIES.md). `throttle` logs `allowed` only in report mode. |
 | `site` | `key`, `path`, `status` (`generated`/`shadowed`); or `severity` (`info`/`warning`) and `message` | Activation records for [site conventions](SITE.md). `shadowed` means a declared route took the path; an `info`/`warning` line reports an omitted `Sitemap:` line (no `--origin`), skipped list names or a far-future `security.txt` expiry. |
-| `management_request` | `timestamp`, `requestId`, `collection`, `action`, `authenticated`, `principal`, `status`, `outcome`, `durationMs` | Operator activity on the link-management API. `status` 0 means no response headers were sent before the peer disconnected; such a request may still have committed a mutation. |
-
-### The link event channel
-
-`link_request` is **not** a stdout record. It is delivered to an `observe()`
-function the embedding operator process supplies, after the response is over, so
-it can never change, delay or fail a redirect. It carries `requestId`,
-`collection`, `route`, `method`, `status`, `outcome`
-(`completed`/`aborted`/`missing`/`disabled`/`expired`/`invalid_code`/`invalid_record`/`unavailable`)
-and `durationMs`. The short code is redacted unless `includeCode` is set, because
-a code identifies the link somebody followed.
-
-The queue is bounded: under overload it drops events and reports the count
-through `link_observer` rather than growing memory. Alert on those drops if you
-count clicks — a quiet channel and a dropping channel look identical downstream.
 
 Startup prints `listening` with the effective `origin`, which is what functions
 and absolute URLs see. Behind a proxy or tunnel this must be your public origin;
@@ -69,7 +52,7 @@ forwarded headers are deliberately not trusted. See [tunnels](TUNNELS.md).
 `startServer({ metrics: true })` serves `GET /_urlcode/metrics` in Prometheus
 text format: requests by status class and by configured route, in-flight
 gauges, shed 503s, reloads, worker restarts and healthy slots, policy
-outcomes, link outcomes, dropped logs and observer errors, all prefixed
+outcomes, dropped logs and observer errors, all prefixed
 `urlcode_`. The same numbers are available in process as `app.metrics()`. The
 endpoint shares the probes' admission budget and bind host and is off by
 default; it discloses route patterns and traffic shape, so keep it internal

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