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

package/docs/README.md

@@ -1,12 +1,14 @@
 # URLCode documentation
 
-> **Public documentation has moved to
-> [urlcode-docs](https://github.com/jimhoyd-com/urlcode-docs).** That repository
-> is the documentation home and is authored directly — this tree is no longer
-> mirrored into it. New reader-facing pages belong in urlcode-docs; `docs/` here
-> keeps contributor and maintainer material (local development, CI, release
+> **Public documentation is authored in a separate `urlcode-docs` repository,
+> not generated from this tree.** New reader-facing pages belong there; `docs/`
+> here keeps contributor and maintainer material (local development, CI, release
 > process, reviews, spikes, plans and the generated field reference). The
 > reader-facing pages still listed below are being migrated.
+>
+> `urlcode-docs` is currently private, so it isn't publicly browsable yet —
+> until it is, this file and this repository's README are the practical
+> reference.
 
 Start with [the framework](FRAMEWORK.md): the four packages, the ladder from
 redirects to a full application, the composition contract and the rules an AI
@@ -24,18 +26,16 @@ boundary and the license. Use documentation pinned to your runtime revision;
 | Let an AI build routes | [AI authoring guide](AI-AUTHORING.md), [llms.txt](../llms.txt) |
 | Load authoring/operations rules into an agent | [Authoring skill](../.claude/skills/urlcode-authoring/SKILL.md), [operations skill](../.claude/skills/urlcode-operations/SKILL.md), [how they are distributed](AI-AUTHORING.md#agent-skills) |
 | Run examples | [25-route cookbook](../examples/cookbook/README.md), [prerender recipe](../examples/prerender/README.md), [small starter](STARTERS.md) |
-| Explore a standalone application | [URLCode Shortener demo](https://github.com/jimhoyd-com/urlcode-shortener), [build retrospective](https://github.com/jimhoyd-com/urlcode-shortener/blob/main/docs/BUILD-RETROSPECTIVE.md) |
-| Explore a static docs-site integration | [URLCode Docs project](https://github.com/jimhoyd-com/urlcode-docs), [build retrospective](https://github.com/jimhoyd-com/urlcode-docs/blob/main/docs/BUILD-RETROSPECTIVE.md) — synced from this repository, which remains the source of truth |
-| Create/update short links live | [Dynamic links, storage and management API](DYNAMIC-LINKS.md) |
+| Explore a standalone application | [URLCode Short demo](https://github.com/jimhoyd-com/urlcode-short), [build retrospective](https://github.com/jimhoyd-com/urlcode-short/blob/main/docs/BUILD-RETROSPECTIVE.md) |
+| Explore a static docs-site integration | URLCode Docs project (private repository; not yet publicly browsable) |
 | Understand exact behavior | [Specification](SPECIFICATION.md), [routing](ROUTING.md), [HTTP](HTTP.md) |
 | Run examples | [40-route cookbook](../examples/cookbook/README.md), [prerender recipe](../examples/prerender/README.md), [small starter](STARTERS.md) |
 | Let an AI build routes | [The framework](FRAMEWORK.md), [AI authoring guide](AI-AUTHORING.md), [llms.txt](../llms.txt), [SDK and read-only MCP](TOOLING.md) |
 | Reuse code around routes | [Middleware](MIDDLEWARE.md), [middleware examples](MIDDLEWARE-EXAMPLES.md) |
-| Handle secrets and untrusted code | [Function security](FUNCTION-SECURITY.md) |
+| Handle secrets and decide what to sandbox | [Function security](FUNCTION-SECURITY.md) |
 | Author guest functions in TypeScript | [Build-time guest transpilation](TYPESCRIPT-AUTHORING.md) |
 | Serve pages, files and downloads | [Assets](ASSETS.md) |
 | Publish a site with no request-time guest code | [Prerendering helper and recipe](PRERENDER.md) |
-| Create and update short links live | [Dynamic links, storage and management API](DYNAMIC-LINKS.md) |
 | Select response branches | [Exact conditions](CONDITIONS.md) |
 | Proxy an API or emit a webhook | [Bounded egress and operator grants](EGRESS.md) |
 | Throttle, block agents, set security headers, compress or cache | [Policies](POLICIES.md): [throttle](policies/throttle.md), [agents](policies/agents.md), [security](policies/security.md), [compression](policies/compression.md), [cache](policies/cache.md) |
@@ -55,6 +55,7 @@ boundary and the license. Use documentation pinned to your runtime revision;
 | Manage users, sessions, roles and audit | [urlcode-admin](https://github.com/jimhoyd-com/urlcode-admin#readme) |
 | Restyle every extension page and translate copy | [urlcode-ui](https://github.com/jimhoyd-com/urlcode-ui#readme), [ui contract](https://github.com/jimhoyd-com/urlcode-ui/blob/main/CONTRACT.md) |
 | Write or install a versioned extension | [Extensions](EXTENSIONS.md), [example fixture](../examples/extensions/README.md) |
+| Know which core version an extension package supports, and how it says so | [Core version alignment](VERSION-ALIGNMENT.md) |
 | Add host behavior in operator code | [Plugins](PLUGINS.md) |
 | Use the API from TypeScript | [TypeScript: shipped declarations, exports, build and fidelity](TYPESCRIPT.md) |
 
@@ -81,7 +82,6 @@ boundary and the license. Use documentation pinned to your runtime revision;
 | Watch a deployment | [Monitoring](MONITORING.md), [observability](OBSERVABILITY.md) |
 | Estimate concurrency and memory | [Capacity and limits](CAPACITY.md), [measurements](PERFORMANCE.md), [load testing](LOAD-TESTING.md) |
 | Prepare for overload, DDoS and recovery | [Resilience playbook](RESILIENCE.md) |
-| Manage private credentials and audit | [Management security](MANAGEMENT-SECURITY.md) |
 
 ## Evidence, reviews and design records
 
@@ -93,12 +93,14 @@ has not, and why the design is the way it is.
 | [Release readiness](RELEASE-READINESS.md) | Verified safeguards, open gates, supported scope |
 | [Usability review](USABILITY-REVIEW.md) | Where the framework is easier or harder than the tools it replaces, and ranked changes |
 | [Next steps](NEXT-STEPS.md) | The phased plan: agent discovery, context compression, retrieval, the ladder, benchmarks and the remaining proof gaps |
+| [AI-first framework benchmark spike](SPIKE-AI-FRAMEWORK-BENCHMARK.md) | Proposed research-first, independent-agent application and runtime benchmark with a verified issue/improvement loop |
 | [Next-phase implementation status](NEXT-PHASE-PLAN.md) | Source additions after 0.3.0 shipped in 0.4.0-alpha.1, and their evidence limits |
 | [Security review](SECURITY-AUDIT.md) | Internal findings and fixes; not an independent test |
 | [Standards audit](STANDARDS.md) | How the runtime conforms to the RFCs it touches |
 | [Sandbox review package](SANDBOX-REVIEW.md) | What an independent reviewer needs; assessment not yet performed |
 | [Operational drills](OPERATIONAL-PROOF.md) | Deployment acceptance drills CI runs |
 | [Release security](RELEASE-SECURITY.md) | Candidate signing and publication process |
+| [Core version alignment](VERSION-ALIGNMENT.md) | The supported core floor for each downstream repository, how it is declared, and the publish-then-raise-then-regenerate order |
 | [Extension model review](SPIKE-EXTENSION-MODEL.md) | Why extensions are shaped this way, with framework precedents |
 | [Extensions spike](SPIKE-EXTENSIONS.md) | The design behind policies and plugins; implemented |
 | [Lambda compile spike](SPIKE-LAMBDA-COMPILE.md) | Proposal: per-route Lambdas for functions; not implemented |

package/docs/RELEASE-READINESS.md

@@ -1,42 +1,59 @@
 # Release readiness
 
-Status: `0.4.0-alpha.1` alpha of the extension contract and agent tooling on
-top of the `0.3.0` self-hosted release. Production approval remains specific to
+Status: `0.4.0-alpha.2` (`package.json`) alpha of the extension contract and
+agent tooling on top of the `0.3.0` self-hosted release; `0.4.0-alpha.1` is the
+most recent alpha actually published; the npm dist-tags for `@jimhoyd/urlcode`
+were `latest` = `0.3.0` and `alpha` = `0.4.0-alpha.1` when checked against the
+registry on 2026-09-19, so the repository's `0.4.0-alpha.2` is unpublished (see
+"Packaging" below). Production approval remains specific to
 the workload and deployment environment.
 This register describes the current public runtime, not future promises.
 Use the contract and docs from the same pinned commit as your installed runtime.
 
 ## What is aligned
 
-- One portable YAML project, explicit includes, one handler per route (redirect, respond, page, static, download, function, link, proxy, conditional or extension),
+- One portable YAML project, explicit includes, one handler per route (redirect, respond, page, static, download, function, proxy, conditional or extension),
   per-route middleware and consistent request/response validation.
 - One starter with a function route first and an ordinary redirect second.
   Clone urlcode-template or use `urlcode init`; neither requires a database.
 - Native handlers avoid user-code execution unless middleware is attached.
-- Live links are mutable records behind a declared route. Git owns definitions;
-  an optional external SQLite store owns records. This is single-host storage.
-- Untrusted functions run in isolated QuickJS/WASM with no ambient filesystem,
-  network or Node APIs. Host bindings require external revision-pinned approval.
+- Functions/middleware run trusted and unsandboxed by default (in-process,
+  full Node access); `sandbox: true` opts a route into isolated QuickJS/WASM
+  with no ambient filesystem, network or Node APIs (docs/SPIKE-DEFAULT-TRUST-MODEL.md).
+  Host bindings require external revision-pinned approval either way.
 - The runtime is released under Apache-2.0.
 
 ## Regression evidence
 
 `npm run verify` is the lint, syntax/schema-reference and unit/HTTP regression gate.
 `npm run test:package` installs the packed artifact and exercises initialized apps,
-route audits, bounded benchmarks, assets and live links. CI runs Node 22/24/26 on
-Linux/macOS/Windows and tests the container under resource restrictions.
+route audits, bounded benchmarks and assets. On a push to `main`, CI runs Node
+22/24/26 on Linux/macOS/Windows (nine combinations) and tests the container
+under resource restrictions; a pull request runs the same Node versions on
+Linux only (`.github/workflows/ci.yml`'s matrix), with the macOS/Windows legs
+deferred to the post-merge run.
 
 | Area | Covered behavior | Practical limit |
 |---|---|---|
 | Routing and HTTP | Exact/parameter/static precedence, methods, inputs, assets, middleware and response assertions | Stable 0.1 contract; unsupported semantics reject rather than emulate |
-| Isolation | Sandbox capability/permission boundaries, deadlines, memory and invalid outputs | Not an independent security assessment or multi-tenant service certification |
-| Overload | Function/store queue caps; HTTP admission saturation, separate bounded probe budget, health availability and recovery after upload completion/disconnect | 64 application requests default; no fairness, upstream DDoS protection or end-to-end deadline |
-| Worker replacement | Repeated guest deadlines shed load and the pool returns to service after backoff, rather than latching off for the life of the process | Store-connection replacement shares this logic but its failure branch has no automated test; a crash there is covered by reasoning and review only |
-| Persistence | Committed writes visible to independent readers; concurrent CAS, restart and abrupt writer exit | SQLite on one host; no distributed availability |
-| Shutdown | Full accepted store queue drains; new work rejects; repeated close shares completion | Existing deadlines can still fail; uncertain writes must be reconciled |
-| Management | Token boundaries, body limits, origin rejection, conditional mutations, endpoint-specific Allow headers | Private operator API, not public end-user account management |
-| Activation/recovery | Invalid reload retains last-good snapshot; corrupt revision metadata rejects activation | No deployment orchestration or automatic database repair |
-| Packaging | Packed installation and starter examples tested; sensitive files excluded | No published npm/Homebrew release or provider adapter guarantee |
+| Isolation | `sandbox: true` capability/permission boundaries, deadlines, memory and invalid outputs; the trusted default's grant scoping | Not an independent security assessment or multi-tenant service certification; trusted-route code safety is the project's own call |
+| Overload | Function pool queue caps; HTTP admission saturation, separate bounded probe budget, health availability and recovery after upload completion/disconnect | 64 application requests default; no fairness, upstream DDoS protection or end-to-end deadline |
+| Worker replacement | Repeated guest deadlines shed load and the pool returns to service after backoff, rather than latching off for the life of the process | Bounded by the configured worker count; no cross-process load balancing |
+| Shutdown | New work rejects; repeated close shares completion | Existing deadlines can still fail during shutdown |
+| Activation/recovery | Invalid reload retains last-good snapshot; corrupt revision metadata rejects activation | No deployment orchestration |
+| Packaging | Packed installation and starter examples tested; sensitive files excluded | `0.3.0` and `0.4.0-alpha.1` are published to npm as `@jimhoyd/urlcode` (`latest` and `alpha` dist-tags respectively; dist-tags verified against the npm registry on 2026-09-19, when the repository stood at the unpublished `0.4.0-alpha.2`). Published extension packages on the same date: `@jimhoyd/urlcode-auth@0.1.0-alpha.2`, `@jimhoyd/urlcode-admin@0.1.0-alpha.2`, `@jimhoyd/urlcode-ui@0.1.0-alpha.4`, `@jimhoyd/urlcode-short@0.1.0-alpha.1`, `@jimhoyd/urlcode-dynamic-link@0.1.0-alpha.1`, `@jimhoyd/urlcode-middleware@0.1.0-alpha.1`. Observed in passing: auth's dist-tags are split — `alpha` points at `0.1.0-alpha.2` while `latest` still points at `0.1.0-alpha.1`, so a plain `npm install @jimhoyd/urlcode-auth` resolves the older alpha. GitHub Releases attach a Homebrew formula (`urlcode.rb`) for manual copy into a tap, not an automated Homebrew Core/tap publish. No provider adapter guarantee. |
+
+`npm run check:downstream-skills` is a manual, advisory report worth running
+before a release: it diffs core's `.claude/skills/` copies against copies
+vendored by downstream repositories (currently `urlcode-template`) when that
+repository is cloned as a sibling checkout, and prints how many lines differ
+per skill. It never fails and never asserts which side is correct -- a
+downstream repo commonly pins an older published core version, and
+divergence from core's current `main` can be the *correct* reflection of
+that pin rather than staleness (see issue #155). It is not part of `check`
+or `verify` because it depends on an out-of-repo sibling checkout that
+normal CI does not have; it is a prompt to review the diff against the
+downstream pin, not a pass/fail gate.
 
 `npm audit --omit=dev` now runs in CI and fails the build on any runtime advisory;
 development-only advisories are reported without blocking. Dependabot proposes npm,
@@ -50,22 +67,20 @@ These remain open. Record workload, runtime/app/image revisions, environment,
 commands, results and owner for each exercise; do not convert a passing local
 benchmark into a universal throughput claim.
 
-1. Independent review of host/sandbox boundaries and authenticated management.
+1. Independent review of host/sandbox boundaries.
 2. Sustained load and soak on intended hardware, through the actual TLS/proxy
    path: successful throughput, tail latency, 503/504 rate, RSS and recovery.
    `urlcode benchmark --target` measures a running deployment through its real
    path and separates shed responses from transport errors; see
    [load testing](LOAD-TESTING.md). The tool is GET/HEAD only and caps at 300
    seconds, so it does not by itself close this gate.
-   Include mixed native/function/live-link workloads and slow peers.
-3. A real backup/restore drill on a separate host/volume, with record/version
-   reconciliation and measured recovery time/data loss. Keep SQLite WAL files
-   consistent; copying a live main database file alone is not a backup.
-4. Kill/restart, resource exhaustion, disk-full and rolling deployment/rollback
-   exercises with the chosen supervisor, ingress and persistent storage.
-5. Alerting and ownership for sustained errors, latency, readiness, dropped logs,
+   Include mixed native/function workloads and slow peers.
+3. Kill/restart, resource exhaustion and rolling deployment/rollback
+   exercises with the chosen supervisor and ingress. A future durable-state
+   extension needs its own backup/restore drill; core has no durable store.
+4. Alerting and ownership for sustained errors, latency, readiness, dropped logs,
    disk space, restarts and backups. Pick service objectives for the actual app.
-6. Stable-release support commitments before packaging/public reuse claims.
+5. Stable-release support commitments before packaging/public reuse claims.
    Private security reporting and the current support baseline are documented in
    SECURITY.md.
 
@@ -88,9 +103,14 @@ independent assessment or real deployment exercises.
 ## Hardening follow-up
 
 Implemented: bounded YAML workers and aggregate source budgets, cooperative route
-compilation deadline, loopback-only management, scoped/expiring/revocable operator
-credentials, atomic SQLite mutation audits, executable local/CI operational drills,
-and a main-only candidate signing/SBOM workflow.
+compilation deadline, scoped/expiring/revocable operator credentials for host
+bindings, executable local/CI operational drills, and a main-only candidate
+signing/SBOM workflow. The loopback-only management API and its atomic SQLite
+mutation audits were part of the `link`/`dynamicLinks` store that PR #126
+removed from core; that functionality, and its hardening, now belongs to the
+`urlcode-dynamic-link` extension (docs/EXTENSIONS.md), published on npm as
+`@jimhoyd/urlcode-dynamic-link@0.1.0-alpha.1` as of 2026-09-19, not this
+runtime.
 
 Still required: [independent review](SANDBOX-REVIEW.md), [actual deployment proof](OPERATIONAL-PROOF.md),
 and publication/support arrangements. The Apache-2.0 license and the 0.3.0 self-hosted

package/docs/RELEASE-SECURITY.md

@@ -90,6 +90,92 @@ The SBOM describes npm dependencies; it is not a complete OS/container SBOM. Hos
 runners and action runtimes remain platform-controlled. Digest pins improve supply
 chain integrity but do not prove byte-for-byte reproducibility or engine safety.
 Signing verification must be demonstrated on a successful main workflow run before
-claiming a candidate has been signed. Workflow definition alone is not that evidence:
-`release.yml` has never been executed, so no release has yet been produced or signed
-by it, and the npm and GHCR publication paths are unproven until a real tag runs.
+claiming a candidate has been signed. Workflow definition alone is not that evidence.
+`release.yml` ran successfully for the first time publishing `v0.4.0-alpha.1`
+(2026-09-18), after the fixes below; treat any repository whose workflow has not
+had a real successful tagged run the same way this one was treated before that.
+
+## What broke on every first release, and why
+
+Four repositories (core, ui, auth, admin) each cut their first tagged release in
+the same session. Every one hit a subset of the same bugs, because each
+`release.yml` was written and reviewed but never actually run end-to-end against
+a real tag before. None of this is repository-specific; check for all of it
+before trusting an unexercised release workflow:
+
+- **`npm ci` on the bare runner's root-owned npm.** A build that runs entirely
+  inside a pinned Docker image never calls `actions/setup-node`, so a later
+  `npm install --global npm@11.5.1` (needed for the trusted-publishing floor)
+  hits the runner's preinstalled, root-owned npm and fails `EACCES`. Add
+  `actions/setup-node` before any step that installs global npm packages, even
+  if the main build never touches the runner's own Node.
+- **The floor check must run after the pin, not before.** A guard asserting
+  "npm ≥ 11.5.1" is useless directly after `setup-node` with `node-version: '22'`,
+  which bundles npm ~10.9.x — it can never pass. The floor only means something
+  once the publish step's own `npm install --global npm@11.5.1` has actually run.
+- **`npm publish` refuses an unqualified prerelease.** `You must specify a tag
+  using --tag when publishing a prerelease version.` npm's safety default is
+  `latest`; a prerelease must derive an explicit dist-tag from its version
+  (`0.1.0-alpha.1` → `alpha`, anything without a `-` → `latest`) and pass
+  `--tag`. This path is only exercised by a package's *first* prerelease, so it
+  silently sat broken in every repository until each hit it for the first time.
+- **`npm pack --pack-destination candidate` needs `candidate/` to exist first.**
+  npm does not create the destination directory; `mkdir -p candidate` first.
+- **A private repository's unauthenticated `git fetch origin main` cannot work.**
+  If checkout uses `persist-credentials: false` (correct, for a step that
+  should not need write access) and the repo is private, `git fetch` fails
+  `could not read Username for 'https://github.com'` before ever reaching the
+  version check. Compare the tag against main through the GitHub API instead
+  (`gh api repos/OWNER/REPO/compare/main...SHA --jq .status`, expecting
+  `identical` or `behind`) — it needs no credentials and stays read-only. Public
+  repositories can keep the plain fetch; it works there.
+- **`--conditions=development` in `npm run verify`'s test script resolves peers
+  to source that a real npm install never ships.** The regular CI job symlinks
+  sibling checkouts in place of `node_modules`, so `./src/*.ts` exists and the
+  flag is correct there. A release installs real published tarballs of its
+  peers, which only ever ship `dist/`, so the same flag makes every import of a
+  peer fail `ERR_MODULE_NOT_FOUND`. Drop the flag for the release-workflow test
+  invocation specifically (run `node scripts/check-sqlite.mjs` explicitly first,
+  since bypassing `npm test` skips that pretest hook), and audit any test file
+  that separately hardcodes the flag in a spawned child process — it has to be
+  fixed the same way, independently, wherever it appears.
+- **A peer-install command with the wrong flag combination is a silent no-op.**
+  `npm install --no-save --no-package-lock --ignore-scripts --legacy-peer-deps
+  <peer>@<version>` installed *nothing*, with no error, when the target package
+  names already appear in `peerDependencies` — `npm ci` earlier reports "added N
+  packages" as if it worked. Confirm the install actually happened
+  (`ls node_modules/@scope/*/package.json` and print each version) rather than
+  trusting the exit code; `--no-save --ignore-scripts <specs>` (no
+  `--no-package-lock`, no `--legacy-peer-deps`) is the version that works, paired
+  with `git diff --exit-code -- package.json package-lock.json` to prove nothing
+  was recorded as a dependency.
+- **A version published from an unbuilt checkout is burned forever.** npm never
+  allows a version to be replaced. `@jimhoyd/urlcode-auth@0.1.0-alpha.1` reached
+  the registry from something other than the CI workflow (a manual `npm
+  publish` run before `npm run build` had produced `dist/`), so the published
+  tarball contained only metadata files and no code. Every consumer's typecheck
+  failed with `Cannot find module '@jimhoyd/urlcode-auth'` — a real, correct
+  failure, not a bug in the consumer. The only fix is bumping to a new version
+  and publishing that instead; nothing can repair or unpublish the bad one.
+  **Never run `npm publish` by hand outside the release workflow** — the
+  workflow is the only place that reliably builds before packing.
+- **`ENEEDAUTH` on `npm publish` under trusted publishing usually means the
+  registry-side configuration doesn't exist or doesn't permit direct publish
+  yet**, not a workflow bug. Trusted publishing needs an entry under the
+  package's npm settings ("Trusted Publisher") naming the exact GitHub
+  org/repo and workflow filename, with no environment set unless the workflow
+  declares one; recent npm UI changes default new configurations to
+  "stage publish" only; "allow npm publish" (direct publish, which is what
+  this project's workflows do) must be explicitly enabled too. A wrong
+  org/repo/workflow match tends to surface as a 404, not `ENEEDAUTH`;
+  `ENEEDAUTH` is the signature of no matching configuration existing at all.
+- **Publish order matters and is easy to get backwards.** Extension packages
+  declare `@jimhoyd/urlcode >=X <Y` as a peer range; publish core before ui,
+  auth or admin, or their own release-workflow peer-install step has nothing
+  real to resolve against.
+
+None of the above is exotic; all nine bugs were found by actually running each
+workflow against a real tag, one release at a time, and reading the actual
+failure rather than guessing from the workflow source. Treat "the workflow file
+looks right" and "the workflow has actually published successfully once" as two
+different, unrelated claims.

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 |