@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/docs/RESILIENCE.md

@@ -1,9 +1,11 @@
 # DDoS, overload and recovery playbook
 
 This is an operator plan for the current self-hosted release, not a claim of built-in DDoS
-protection, managed failover or tested high availability. URLCode's sandbox and
-resource limits reduce some failure modes; they cannot protect a saturated
-network link. Keep the public origin behind your existing protected ingress.
+protection, managed failover or tested high availability. URLCode's resource
+limits — the HTTP admission cap either way, plus the worker pool's own
+deadline/queue-less ceiling for a `sandbox: true` route — reduce some failure
+modes; they cannot protect a saturated network link. Keep the public origin
+behind your existing protected ingress.
 
 ## Defense responsibilities
 
@@ -11,8 +13,8 @@ network link. Keep the public origin behind your existing protected ingress.
 |---|---|---|
 | Upstream network | Hosting/CDN DDoS mitigation and an escalation contact; protect bandwidth before it reaches the origin | No network-level mitigation service |
 | Edge/proxy | TLS, per-client and aggregate request/connection budgets, header/body/time limits; restrict direct origin access | Private bind default; no automatic TLS/WAF. Optional per-instance [`throttle` and `agents` policies](POLICIES.md) as a second layer behind the edge, with `--trusted-proxies` naming the hops allowed to set `X-Forwarded-For` |
-| Application | Validate inputs, bound expensive work, authenticate sensitive operations | Strict route/body validation; sandbox deadlines and no execution queue |
-| Process/container | CPU/RAM/PID limits, restart backoff, least privilege, read-only reviewed app | Worker isolation, bounded worker replacement, health and request logs |
+| Application | Validate inputs, bound expensive work, authenticate sensitive operations | Strict route/body validation; a `sandbox: true` route gets worker deadlines and no execution queue, a trusted (default) route shares the HTTP admission cap with no worker ceiling |
+| Process/container | CPU/RAM/PID limits, restart backoff, least privilege, read-only reviewed app | Worker isolation for `sandbox: true` routes, bounded worker replacement, health and request logs |
 | Release/recovery | Known-good artifacts, candidate verification, traffic switching, rollback drills | Local validation/tests/audit; explicit snapshot reload; no orchestration |
 
 NGINX provides request-rate controls and connection controls keyed by values such
@@ -30,7 +32,8 @@ forwarded headers to construct its public URL; set `--origin` explicitly.
 
 The optional [`throttle` policy](policies/throttle.md) adds a per-client budget
 inside the runtime, and the [`agents` policy](policies/agents.md) refuses listed
-User-Agents before a body is read or the sandbox starts. Both are a second
+User-Agents before a body is read or the function/middleware call starts,
+trusted or sandboxed. Both are a second
 layer behind the edge, not a replacement for it: counters are per instance,
 the socket and admission limits still apply first, and a flood still costs
 connections. The client identity is the socket peer unless
@@ -50,8 +53,8 @@ is not implemented; adding a reverse proxy does not bypass runtime execution.
 | Failure or traffic pattern | Current consequence | Mitigation / recovery |
 |---|---|---|
 | High-rate ordinary requests | Event-loop, logging, bandwidth or socket exhaustion | Filter/rate-limit upstream; scale only within measured resource/cost budgets |
-| Flood of functions or middleware | Two default worker slots fill; further calls receive 503 | Bound programmable traffic before the origin; isolate heavy workloads |
-| Infinite/slow application code | Shared invocation deadline returns 504; worker terminated/replaced | Identify bad release/route with protected diagnostics; roll back or block route at ingress |
+| Flood of functions or middleware | Two default worker slots fill for `sandbox: true` routes; further calls receive 503. Trusted (default) routes shed load through the in-flight admission cap instead | Bound programmable traffic before the origin; isolate heavy workloads |
+| Infinite/slow application code | Shared invocation deadline returns 504; a `sandbox: true` worker is terminated/replaced, while a trusted route blocking the event loop synchronously cannot be preempted ([capacity](CAPACITY.md)) | Identify bad release/route with protected diagnostics; roll back or block route at ingress |
 | Guest invalid response or failure | Generic 502 | Compare with last deployment; run fixture on a private candidate |
 | Repeated worker exits | Replacement backs off (250 ms doubling to 30 s) and keeps retrying; readiness stays 503 until every slot serves | Contain the cause; load is shed meanwhile. Replacement never stops, because a guest deadline is reachable from ordinary request input and must not disable functions until an operator restarts |
 | Large/slow requests | 64 admitted application requests, body/header limits and receipt timeouts; copies still consume memory | Smaller proxy/body budgets and connection admission limits |
@@ -120,8 +123,8 @@ Choose RTO (acceptable recovery time) and RPO (acceptable data loss) per deploym
 URLCode does not promise values. A stateless YAML deployment can be recreated
 from retained immutable artifacts, subject to recovery of DNS/ingress and secret
 access. Log loss is possible under pressure and has a separate retention target.
-Stored live-link records and future app-owned state need their own backups and restore
-verification; Git route configuration does not back up runtime data.
+Future app-owned or extension-owned durable state needs its own backups and
+restore verification; Git route configuration does not back up runtime data.
 
 A rollback needs the previous app/runtime and its matching policy and compatible
 secret bindings. The health version combines configuration and asset digests;
@@ -153,8 +156,6 @@ admission/fairness, production metrics/exporters, dedicated slow-reader protecti
 provider-level mitigation validation and sustained failure/soak testing. These are
 free-runtime/operator requirements.
 
-For optional live links, protect the separate management listener and token, bound
-its traffic, and back up the SQLite store with the documented closed-store or
-SQLite-aware procedure. Store worker failure returns 503; stop the cause before
-reloading/restarting. An uncertain mutation may have committed. See
-[dynamic-link recovery](DYNAMIC-LINKS.md).
+Core has no durable store of its own to recover; a future durable-state
+extension (such as the planned `urlcode-dynamic-link`) is responsible for its
+own management listener, backup and recovery procedure once it exists.

package/docs/ROUTING.md

@@ -1,4 +1,4 @@
-# Route matching and new links
+# Route matching
 
 ## Supported path patterns
 
@@ -49,7 +49,7 @@ route returning 405, 404, 410 or 400 does not fall through to another route.
 Likewise, a missing file in the longest selected static mount does not fall back
 to a shorter mount. See [HTTP](HTTP.md) and [the contract](SPECIFICATION.md).
 
-## Adding a configured link today
+## Adding a configured redirect today
 
 ```sh
 urlcode add https://example.com/new-page --alias new-link --project ./my-links
@@ -83,13 +83,11 @@ and needs no route rebuild or service restart. The same distinction applies to
 any per-visitor session record. Git owns route behavior and code; user-created records have
 their own persistence, backup and export lifecycle.
 
-This is now implemented for short-link redirects through the optional `link`
-handler, local SQLite storage, CLI and a separate authenticated management API.
-See [dynamic links](DYNAMIC-LINKS.md) for complete YAML, setup, consistency and
-backup details. No route reload is needed for committed record changes.
+Core has no native handler for this today: the `link` handler that implemented
+it was removed. Stored short links are moving to a future
+`urlcode-dynamic-link` extension package (mount-based, like `auth`/`admin`,
+not yet published); a project needing them declares an `extension` mount once
+that package exists.
 
 Functions still cannot access databases, the filesystem or network directly.
-The native link handler performs the bounded lookup, and middleware can wrap a
-successful redirect. General application state and realtime sessions remain
-future work. SQLite is optional and supports local same-host processes; a
-multi-host deployment needs a different adapter. A cache is not the durable store.
+General application state and realtime sessions remain future work.

package/docs/SANDBOX-REVIEW.md

@@ -1,9 +1,19 @@
 # Independent sandbox review gate
 
+Scope: this gate is about the `sandbox: true` execution path only —
+`function`/`middleware` routes run trusted and unsandboxed by default
+(docs/SPIKE-DEFAULT-TRUST-MODEL.md), and a trusted route's full Node access is
+by design, not a gap this review closes. Nothing here claims to review
+arbitrary trusted project code; that trust is the project's own call, made
+per route.
+
 Status: **external assessment not performed**. Internal source review, CI, CodeQL
 and adversarial regressions are useful evidence, not an independent sign-off.
-Do not host anonymous hostile multi-tenant code before this gate is closed.
-No unrestricted Node execution fallback is permitted.
+Do not host anonymous hostile multi-tenant code in a `sandbox: true` route
+before this gate is closed, and do not run untrusted/unreviewed code in a
+trusted (non-`sandbox`) route at all — that path was never sandboxed and this
+gate does not apply to it. No unrestricted Node execution fallback is
+permitted *within a route that declared `sandbox: true`*.
 
 ## Review package
 
@@ -15,14 +25,17 @@ resource settings. Give a reviewer independent of the implementation access to:
   module graph, import denial, export validation, binding grants and message bridge.
 - `src/config.ts`, `src/config-worker.ts`, router and assets: parser/schema limits,
   file containment, activation, memory amplification and host-side compilation.
-- HTTP server, management API/policy and link-store worker: request smuggling,
-  admission, body/response framing, authorization, revocation and atomic audit.
-- `test/sandbox.test.ts`, middleware/config/links/logging/reload tests, Dockerfile,
+- HTTP server and policy: request smuggling, admission, body/response framing.
+- `test/sandbox.test.ts`, middleware/config/logging/reload tests, Dockerfile,
   protected workflows and `docs/FUNCTION-SECURITY.md`.
+- `src/runtime.ts`'s dispatch decision (`route.sandbox ? pool : trusted`) and
+  `src/trusted-functions.ts`: confirm a route that declares `sandbox: true`
+  can never be dispatched through the trusted, in-process path by any code
+  path, and that `sandbox: false`/absent never reaches `FunctionPool`.
 
 Run `npm ci --ignore-scripts`, `npm run verify`, `npm run test:package`, and
 `node scripts/operational-drills.ts`. Record the exact commands and result files.
-CI adds constrained-container and real disposable-volume exhaustion tests.
+CI adds a constrained-container test.
 Use only disposable local/staging systems with synthetic data.
 
 ## Threat model and required probes

package/docs/SCAFFOLDING.md

@@ -68,5 +68,3 @@ Scaffolding does not recursively invent dependencies imported by existing code,
 crawl HTML/CSS links, generate binary content, or implement your business logic.
 See [readiness checks](READINESS.md) and [asset behavior](ASSETS.md).
 
-Scaffolding enforces the entry-level `dynamicLinks` opt-in for `link` handlers
-and reports the effective boolean. It never enables this capability for you.

package/docs/SECURITY-AUDIT.md

@@ -1,3 +1,38 @@
+# Security review — 2026-09-18
+
+Scope: trust-model change (docs/SPIKE-DEFAULT-TRUST-MODEL.md). `function`/
+`middleware` routes now run trusted and unsandboxed by default, with
+`sandbox: true` as an explicit per-route opt-in to the isolation this document's
+earlier entries describe. This is a maintainer-decided policy reversal, not a
+finding; it is recorded here because it changes what every earlier entry's
+"guest"/"sandbox" language means going forward.
+
+**What did not change:** the `sandbox: true` execution path — QuickJS/WASM
+isolation, module-graph restriction, fresh heap per call, worker deadline —
+is byte-for-byte the same as every earlier entry describes; nothing in this
+change touched `src/functions.ts`, `src/function-worker.ts` or `src/guest-api.ts`.
+Binding grants are unaffected either way: `env`/`secrets` still reach only a
+route that explicitly declared them and an operator policy pinned to the
+project revision explicitly granted, whether that route is trusted or
+sandboxed.
+
+**What did change, and the resulting residual risk:** a `function`/
+`middleware` route with no `sandbox` field (the common case going forward, and
+every existing project's routes after an upgrade with no YAML change) now runs
+in the host process with full Node access — the isolation earlier entries'
+"remaining gaps" language assumed for *all* guest code no longer applies to
+it. The residual-risk framing in earlier entries ("before exposing hostile
+multi-tenant workloads, obtain independent review of WASM/host boundaries")
+is scoped to `sandbox: true` routes specifically; it was never a claim that
+covered a route that opts out of the sandbox, and after this change most
+routes do exactly that by default. Whether a given project's own function/
+middleware code is safe to trust with full host access is now the project's
+judgment call, not something this runtime's isolation reviews (past or
+future) can speak to. New source review of the dispatch decision itself
+(`src/runtime.ts`, `src/trusted-functions.ts`, `src/policy.ts`'s split
+grant-hashing) accompanies the change; see the pull request that introduced
+`sandbox` for its own description of what was and was not verified.
+
 # Security review — 2026-09-17
 
 Scope: follow-up source review of worker/connection replacement, probe admission,
@@ -5,6 +40,11 @@ request correlation, operational logging, dependency/release supply chain and th
 live-link Node requirement. Regression tests accompany the fixes. Internal review,
 not an independent penetration test.
 
+This is a dated record, not current guidance. The `link` handler, its SQLite
+store and the link-store/management findings below were removed from core in
+a later change; they describe the runtime as it existed on this date, not the
+current one.
+
 ## Findings fixed in this revision
 
 | Finding | Impact and evidence | Fix / regression |
@@ -100,7 +140,7 @@ repository-governance follow-up pins them and enables dependency maintenance,
 secret protection, CodeQL and private reporting; see [governance](../GOVERNANCE.md).
 CI now also gates runtime advisories with `npm audit --omit=dev`. A manual main-only
 signed candidate/SBOM workflow is now defined; see
-[release security](RELEASE-SECURITY.md). It does not publish to registries. The 0.1.0 release is licensed under
+[release security](RELEASE-SECURITY.md). A tagged release publishes to npm with provenance. The 0.1.0 release is licensed under
 Apache-2.0; the license does not close the independent-review gates.
 
 **Application responsibility:** HTML/JS assets are active browser content; choose

package/docs/SPECIFICATION.md

@@ -1,8 +1,9 @@
-# Implemented 0.1 contract
+# Implemented project contract
 
 This document and [JSON Schema](../schemas/urlcode.schema.json) describe
-0.2.0. `version: "1"` is the stable project-format contract for the 0.1 release
-line. Later planned features are rejected until implemented.
+the source contract, including unreleased additions after 0.3.0.
+`version: "1"` remains the project-format contract. Unsupported fields
+are rejected rather than interpreted as future behavior.
 
 ## Files and validation
 
@@ -29,12 +30,12 @@ deadline; individual synchronous operations are not preempted. At most 1,000 par
 Keys are absolute case-sensitive paths. Trailing slashes are significant.
 Parameters occupy whole segments, e.g. `/p/{id}`, with distinct identifier names.
 Each parameter matches exactly one nonempty segment, never across `/`; it is not
-greedy. No regex paths, host matching or dot segments. Only static directory mounts
+greedy. No regex paths, client-controlled host dispatch or dot segments. Only static directory mounts
 support a terminal `/*` wildcard with an otherwise literal path. Route keys cannot contain
 percent encoding, spaces, backslashes or query strings. Path length is limited
 to 2,048 characters and 32 segments. `/_urlcode` is reserved.
 
-One handler per route: `function`, `redirect`, `page`, `static`, `download`, `respond` or `link`.
+One handler per route: `function`, `redirect`, `page`, `static`, `download`, `respond`, `conditional`, `proxy` or an `extension` mount.
 See [asset configuration](ASSETS.md) for file handlers. Optional properties:
 
 - `methods`: unique HTTP methods; default GET and HEAD. Explicit lists are exact;
@@ -55,8 +56,8 @@ Requests decode the path once; invalid UTF-8/percent encoding, encoded slashes o
 backslashes, control characters and dot segments return 400. Query values decode
 once. Incoming query data is not automatically forwarded.
 
-See [route matching and new links](ROUTING.md) for examples, precedence, wildcard
-limits, reload behavior and the distinction between YAML routes and live link data.
+See [route matching](ROUTING.md) for examples, precedence, wildcard
+limits and reload behavior.
 
 The optional top-level `site` block (entry file only) generates native routes
 for site conventions: `robots` → `/robots.txt`, `sitemap` → `/sitemap.xml`,
@@ -67,6 +68,37 @@ path wins and the generated one is logged as shadowed. Absolute URLs come from
 the operator's `--origin`; `sitemap` refuses activation without one. See
 [site conventions](SITE.md).
 
+## Exact conditions and duplicate-path alternatives
+
+Optional route `match` conjunctively compares exact query/header/cookie strings,
+an uppercase method and the canonical authority of the operator-configured
+public origin. Host/forwarded headers never select the trusted host. A guard
+mismatch returns 404 without trying a less-specific path; route method admission
+still applies after the guard. Conditions are not authentication or authorization.
+
+The `conditional` handler puts alternatives under one existing route key:
+`cases` contains 1–16 `{match, redirect}` or `{match, respond}` entries; optional
+`fallback` contains exactly one redirect/respond handler. Duplicate YAML paths
+remain invalid. Cases must be provably disjoint: each pair needs a shared
+predicate with different required values. Cases run before fallback; no matching
+case and no fallback returns 404. Nested cases and branch-local bindings,
+middleware or policy are unsupported. Shared inputs, methods, headers,
+middleware and policies stay at route level.
+
+Each query/header/cookie map has 1–16 comparisons; names have at most 128
+characters and values 1,024. Query comparisons use decoded raw strings without
+parameter defaults/coercion. Cookies use unquoted wire values and an 8 KiB input
+limit. Missing and empty are different. Duplicate examined scalar inputs return
+400 when the transport exposes their counts. Header names normalize to lowercase;
+authentication and transport headers cannot be predicates. No regex, geo/device
+inference, wildcard or arbitrary-code conditions are supported.
+
+Conditional routing requires cache disabled or no-store and forces downstream
+no-store responses. Explicit fixtures are required for branch coverage.
+Self-hosted, AWS and Vercel use the shared matcher; Cloudflare refuses conditions
+until its artifact compiler supports them. See [conditions](CONDITIONS.md) and
+the [executable example](../examples/conditions).
+
 ## HTTP request/response configuration
 
 Routes accept `request.body` validation and `response.headers` overrides. The
@@ -125,15 +157,11 @@ keys preserve repeated values. Headers are forwarded only through explicit maps.
 
 ## Stored links
 
-The entry `urlcode.yaml` must opt in with `dynamicLinks: true` (default false).
-Included files cannot set this project-level flag. Parameterized redirects and
-functions do not require it.
-
-`link: {collection: links, code: {from: path, name: code}}` resolves a declared
-path input against an operator-bound store. GET/HEAD only. The logical collection
-is portable; file paths and store credentials are external deployment bindings.
-No general storage capability is exposed to guest code. See [dynamic links](DYNAMIC-LINKS.md)
-for validation, persistence, mutation, expiry and read-after-write behavior.
+Core has no native `link` handler or `dynamicLinks` project flag; both were
+removed. Stored short links are moving to a future `urlcode-dynamic-link`
+extension package (mount-based, like `auth`/`admin`), not yet published. A
+project needing them declares an `extension` mount once that package exists;
+there is no in-core replacement or deprecation shim for `link`/`dynamicLinks`.
 
 ## Functions
 
@@ -161,9 +189,52 @@ export default function hello(request, { args, env }) {
 }
 ```
 
+`function` also accepts a string: `function: functions/hello.mjs`. Document
+validation normalizes it to the long form above before routing, auditing,
+explaining or hashing the project: `source` is the string, `args` maps every
+`{param}` segment of the path to `{from: path, name: param}`, and each such
+parameter the route does not already declare under `parameters` (by name, with
+`in: path`) is appended as `{in: path, required: true, schema: {type: string,
+minLength: 1, maxLength: 128}}`. Declared parameters keep their own schema and
+order. The string must be a project-relative `.mjs` or `.js` path without `..`
+segments; anything else is refused with the route path named. A `middleware`
+entry may likewise be a string, normalized to `{source: <string>}`. Only the
+long form exists after loading, so `routes`, `audit`, `explain`, revision hashes
+and the field reference describe the expansion.
+
 ES modules only (`.mjs` or `.js`, independent of Node package settings).
-TypeScript is not included. `export` defaults to `default`. Functions execute
-inside QuickJS/WASM, never through Node imports. Only relative `.js`/`.mjs`
+[Build-time TypeScript authoring](TYPESCRIPT-AUTHORING.md) can produce these
+JavaScript modules in a separate output project; serving does not transpile them.
+The build never imports application code into Node, uses fixed compiler settings,
+and does not perform semantic type checking. Grants must target the built
+configuration/source revision. `export` defaults to `default`.
+
+### Trust: unsandboxed by default, `sandbox: true` opt-in
+
+A route's `function`/`middleware` chain runs one of two ways, chosen by the
+route's `sandbox` field (false or absent — the default — versus `true`; see
+[docs/SPIKE-DEFAULT-TRUST-MODEL.md](SPIKE-DEFAULT-TRUST-MODEL.md)):
+
+- **`sandbox` false/absent (trusted, the default):** the module is imported
+  directly into the host process with ordinary Node module resolution — bare
+  specifiers, `node:` builtins, npm packages and dynamic `import()` all work,
+  none of the module-graph/source-size limits below apply, and there is no
+  fresh-heap-per-call reset (module-level state persists across requests like
+  any other Node server). The handler/middleware signature and `context`
+  shape are unchanged from the sandboxed contract below; a trusted function
+  additionally has the full Fetch API, Node built-ins and the filesystem
+  available to it, not just the guest text/JSON subset. `args`/`env`/
+  `secrets` are exactly what the route declares and an operator grants,
+  identically to the sandboxed path.
+- **`sandbox: true`:** the rest of this section, unchanged from every earlier
+  release. A sandboxed route's functions and middleware execute inside
+  QuickJS/WASM, never through Node imports.
+
+The remainder of this section (module restrictions, the guest API subset,
+guest limits and deadlines) describes the `sandbox: true` path specifically,
+unless stated otherwise.
+
+Only relative `.js`/`.mjs`
 project imports are supported, with a snapshotted dependency graph. No bare/npm,
 Node built-in, remote, dynamic source imports or `import.meta`. Runtime-created
 imports remain restricted to the route's middleware and handler dependency graphs; there is no fallback.
@@ -176,7 +247,8 @@ delete/get/has/entries/getSetCookie; Response constructor with string/null body,
 Requests decode body bytes as UTF-8. Binary/streaming bodies, URL helpers,
 fetch/WebSocket, crypto and filesystem are not exposed. Promise/async and
 bounded timers (128 pending per invocation) work inside the guest. Unsupported
-APIs fail; they never execute on the host. Do not claim full browser/Node API parity.
+APIs fail; they never execute on the host. Do not claim full browser/Node API
+parity for a `sandbox: true` route; a trusted route has no such restriction.
 
 Context contains `inputs.path/query/header`, `args`, `env`, `secrets`. Arguments
 may be scalar literals, input references, `{env: alias}` or `{secret: alias}`.
@@ -192,12 +264,17 @@ Dotenv supports single-line NAME=value, paired single/double quotes, blank lines
 and full-line comments, without expansion/escapes/shell execution. Loading a
 value does not authorize exposing it to a function; the policy still applies.
 
-Every invocation has a fresh guest heap and module state. No cross-request
-counters, cached secrets or prototype mutation. QuickJS heap limit is 32 MiB,
-stack limit 512 KiB; outer worker and deployment limits are additional defenses,
-not a claim that total process RSS is capped at 32 MiB. Two workers, no queue;
-saturation returns 503. The independent 5-second deadline terminates a worker
-and returns 504. Generic failures return 502; worker replacement is bounded.
+A `sandbox: true` invocation has a fresh guest heap and module state every
+time. No cross-request counters, cached secrets or prototype mutation. QuickJS
+heap limit is 32 MiB, stack limit 512 KiB; outer worker and deployment limits
+are additional defenses, not a claim that total process RSS is capped at 32
+MiB. Two workers, no queue; saturation returns 503. The independent 5-second
+deadline terminates a worker and returns 504. Generic failures return 502;
+worker replacement is bounded. A trusted route has none of this: no fresh
+heap/module reset, no fixed worker-pool ceiling (bounded instead by ordinary
+Node concurrency and the HTTP admission cap), and its deadline races the
+call's promise rather than force-terminating a worker — see
+[capacity](CAPACITY.md) for both models side by side.
 
 HEAD invokes the handler as HEAD and suppresses body output. Code must guard
 its own application side effects when future brokered integrations are enabled.
@@ -206,11 +283,18 @@ not arbitrary Host/forwarded headers. Request/response bodies default to 1 MiB;
 response headers 16 KiB, maximum 256 pairs. Hop-by-hop headers are stripped;
 cookies are preserved individually. Default response cache policy is `no-store`.
 
-No unrestricted host execution option exists. Network integrations and persistent
-state need future explicit, tested capability brokers. Approved secrets can be
-returned by code that receives them; isolation does not automatically enforce
+A trusted (non-`sandbox`) route already has unrestricted host execution by
+design — that is the point of the default described above. For a `sandbox:
+true` route, there is no unrestricted host-execution fallback: declarative
+proxy and webhook signals use the separately granted host broker described in
+[egress](EGRESS.md), and that route's guests still have no fetch API or
+general persistent state capability. Approved secrets can be returned by code
+that receives them, in either mode; isolation does not automatically enforce
 information-flow rules on authorized inputs. Keep grants narrow and review the
-exact pinned revision. The sandbox still needs independent security review before hostile multi-tenant use.
+exact pinned revision. The `sandbox: true` path still needs independent
+security review before hostile multi-tenant use of that specific mode; that
+review's scope was never a claim about a route that opts out of the sandbox
+(see [docs/SANDBOX-REVIEW.md](SANDBOX-REVIEW.md)).
 
 ## Reload and status
 
@@ -230,3 +314,40 @@ The health `version` combines route-definition and asset-representation digests,
 not a full artifact digest
 or secret fingerprint. Production release identity should be the Git commit and
 container image digest. See [operations](OPERATIONS.md).
+
+See [capabilities and normalized route representation](CAPABILITIES.md) for the target catalog,
+programmatic compatibility analysis and provider verification limits.
+
+## Authoring, conversion and verification tools
+
+[Interchange](INTERCHANGE.md) imports and exports a strict literal redirect
+subset with source diagnostics and dry-run reports. Provider conversions refuse
+semantic differences by default; explicit acknowledgment retains warnings and
+never reports lossless behavior. [Bulk import](BULK.md) shards CSV/JSON/YAML rows
+into ordinary includes while retaining runtime resource limits. [Recipes](RECIPES.md)
+are local Git-owned examples; they grant no capabilities. [Build-time TypeScript](TYPESCRIPT-AUTHORING.md)
+is separate from runtime execution.
+
+The [tooling SDK and optional local MCP](TOOLING.md) inspect and validate without
+executing handlers or reading binding values. [Provider conformance](PROVIDER-VERIFICATION.md)
+distinguishes local adapter replay from actual deployment observations; no real
+provider deployment is implied by CI. [Proxy and signal egress](EGRESS.md) requires
+external revision-pinned operator grants and bounded host-owned transport;
+project declarations cannot grant network authority to themselves or guests.
+
+## Bounded outbound behavior
+
+The proxy handler and webhook signals require external revision-pinned origin
+grants. [Egress](EGRESS.md) specifies request and response semantics, DNS pinning,
+header filtering, size/time/concurrency limits, secret binding, signal guarantees
+and shutdown. Project declarations cannot grant network authority to themselves.
+All non-self-hosted targets refuse these capabilities.
+
+## Operator-installed extension handlers
+
+The optional `extensions` map declares version-1 extension configuration.
+`extension: name` handlers require exclusive literal `/prefix/*` mounts and
+explicit operator registration pinned to the project revision. Optional
+`policies.extensions` requirements are validated by the named extension and
+authorized before cache access. See [extension contracts](EXTENSIONS.md) for
+configuration, trust boundaries, lifecycle and target restrictions.