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

package/docs/README.md

@@ -1,13 +1,5 @@
 # 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
-> process, reviews, spikes, plans and the generated field reference). The
-> reader-facing pages still listed below are being migrated.
-
 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
 agent must follow. [Project direction](PROJECT-DIRECTION.md) states the
@@ -24,18 +16,14 @@ 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) |
 | 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) |
@@ -53,8 +41,10 @@ boundary and the license. Use documentation pinned to your runtime revision;
 |---|---|
 | Add accounts, sign-in and protected routes | [urlcode-auth](https://github.com/jimhoyd-com/urlcode-auth#readme) |
 | 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) |
+| Restyle every extension page and translate copy | [urlcode-ui](../packages/ui#readme), [ui contract](../packages/ui/CONTRACT.md) |
 | Write or install a versioned extension | [Extensions](EXTENSIONS.md), [example fixture](../examples/extensions/README.md) |
+| Follow implementation of the auth, admin and UI extensions | [Extension implementation sequence](archive/2026-09-19/EXTENSION-IMPLEMENTATION.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) |
 
@@ -69,11 +59,6 @@ boundary and the license. Use documentation pinned to your runtime revision;
 | Review security findings and gaps | [Internal security audit](SECURITY-AUDIT.md) |
 | Assess release readiness | [Evidence and open gates](RELEASE-READINESS.md) |
 | See unfinished work | [Roadmap](../ROADMAP.md) |
-| Read the design behind policies, plugins and templates | [Extensions spike](SPIKE-EXTENSIONS.md) |
-| Read the design for an authentication and authorization plugin | [Auth spike](SPIKE-AUTH.md) |
-| Read the design for the administration extension that manages users | [Admin spike](SPIKE-ADMIN.md) |
-| Read the design for the shared template kit every extension renders with | [UI kit spike](SPIKE-UI.md) |
-| Read the review of the extension model, its precedents and alignment | [Extension model review](SPIKE-EXTENSION-MODEL.md) |
 | Read the design for compiling function routes into per-route Lambdas | [Lambda compile spike](SPIKE-LAMBDA-COMPILE.md) |
 | Verify a running deployment matches the project | [Deployment checks](DEPLOYMENT-CHECKS.md) |
 | Inspect target support | [Capabilities and normalized representation](CAPABILITIES.md) |
@@ -81,29 +66,23 @@ 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
+## Direction and evidence
 
-These are dated records, not guides. They say what has been checked and what
-has not, and why the design is the way it is.
+Start with [principles and open decisions](OPEN-DECISIONS.md) for a plain-language
+review and [the roadmap](../ROADMAP.md) for next work. Current behavior belongs
+in the guides above and the [specification](SPECIFICATION.md).
 
-| Record | What 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 |
-| [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 |
-| [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 |
-| Auth, admin and UI spikes | Live in their repositories: [auth](https://github.com/jimhoyd-com/urlcode-auth/blob/main/docs/SPIKE-AUTH.md), [admin](https://github.com/jimhoyd-com/urlcode-admin/blob/main/docs/SPIKE-ADMIN.md), [ui](https://github.com/jimhoyd-com/urlcode-ui/blob/main/docs/SPIKE-UI.md) |
-| [Roadmap](../ROADMAP.md) | Implemented versus planned |
+- [Release readiness](RELEASE-READINESS.md), [security audit](SECURITY-AUDIT.md),
+  [sandbox review](SANDBOX-REVIEW.md) and [provider evidence](PROVIDER-VERIFICATION.md)
+  distinguish implementation from evidence still missing.
+- [Version alignment](VERSION-ALIGNMENT.md) and [release security](RELEASE-SECURITY.md)
+  describe peer compatibility and publication.
+- Open proposals: [middleware layering](SPIKE-CORE-LAYERING.md),
+  [Lambda compilation](SPIKE-LAMBDA-COMPILE.md),
+  [agent benchmark](SPIKE-AI-FRAMEWORK-BENCHMARK.md), and
+  [business suite](SPIKE-BUSINESS-SUITE.md). None is an implementation promise.
+- [Historical plans and reviews](archive/README.md) are archived separately.
 
-Examples are educational unless backed by the runnable cookbook and fixtures.
-Infrastructure limits are deployment settings, not fields to invent in route YAML.
+Examples are educational unless backed by runnable fixtures. Infrastructure
+limits are deployment settings, not fields to invent in route YAML.

package/docs/RELEASE-0.4.0-alpha.3.md

@@ -0,0 +1,50 @@
+# Coordinated 0.4.0-alpha.3 release
+
+This release prepares core, UI, auth and admin at `0.4.0-alpha.3`, as explicitly
+selected by the maintainer. The shared number identifies this tested package
+set; it does not enable permanent fixed versioning or leave the alpha channel.
+Existing versions, tags, and npm `latest` channels are preserved.
+
+## Included changes
+
+Core includes the monorepo consolidation, corrected Windows npm invocation,
+current trust-by-default authoring guidance, and support for a TypeScript module
+shared by trusted and sandboxed routes without weakening the sandbox checks.
+The CLI and MCP report the new runtime version. The runtime remains independent
+of the extension implementations.
+
+Auth includes deterministic worker cleanup on rejected initialization and
+Windows backup flushing. Auth/admin refresh a lifecycle hook's entry module on
+each activation; changes to the entry module's own imports still require restart.
+The extension changelogs record their package-specific changes.
+
+All four packages use the shared release coordinator, immutable release tags,
+exact-commit full verification, retained retry artifacts and trusted npm
+publication. The candidate rehearsal installs their tarballs together outside
+the workspace and checks peers, public imports and scaffolding.
+
+## Installation and compatibility
+
+Once publication has completed, install an exact, coordinated set in the
+consumer application's directory:
+
+```sh
+npm install --save-exact @jimhoyd/urlcode@0.4.0-alpha.3 @jimhoyd/urlcode-ui@0.4.0-alpha.3 @jimhoyd/urlcode-auth@0.4.0-alpha.3 @jimhoyd/urlcode-admin@0.4.0-alpha.3
+```
+
+Applications only need the extensions they actually use; admin requires auth
+and UI, and auth requires UI. Auth/admin peer floors for this release are
+`>=0.4.0-alpha.3 <0.5.0`. Update their dependencies together when crossing from
+the former `0.1.x` extension line. Commit the resulting lockfile and use `npm ci`
+in deployment. This release changes package peer compatibility intentionally;
+it does not imply all previously mixed versions are supported.
+
+Publication order is core, UI, auth, admin. A partial release stops before the
+next package; diagnose and rerun its original workflow without moving tags.
+The standalone template remains an exact core consumer and is updated through
+its own PR after core is published. Archived extension repositories are not
+publication targets.
+
+CI and candidate success are not independent security assessment, live-provider
+acceptance, or operational recovery proof. The intermittent Windows startup
+timeout remains tracked in #202.

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` and `@jimhoyd/urlcode-middleware@0.1.0-alpha.2` were also published on that date, then retired and unpublished later the same day; all three repositories were deleted. Middleware's withdrawal removed no capability — per-route middleware is native to core.) Observed in passing on that date: auth's dist-tags were split — `alpha` at `0.1.0-alpha.2` while `latest` lagged at `0.1.0-alpha.1`, so a plain `npm install @jimhoyd/urlcode-auth` resolved a build below admin's declared floor. That is resolved: auth and admin both read `latest` = `alpha` = `0.1.0-alpha.3`. `@jimhoyd/urlcode-ui` now carries a split of its own — `alpha` = `0.1.0-alpha.6`, `latest` = `0.1.0-alpha.5` — which is deliberate rather than drift, and safe only because admin's ui floor is exactly `>=0.1.0-alpha.5`. See [VERSION-ALIGNMENT.md](VERSION-ALIGNMENT.md). 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.
 
@@ -78,7 +93,7 @@ local recipes, TypeScript authoring, bounded self-hosted proxy/signals and read-
 MCP. Local AWS/Vercel/Cloudflare adapter tests and deployment probe tooling exist,
 but actual provider deployments remain unverified. Node process/container hosting
 remains the reference execution target. Guest networking, durable signals and
-realtime capabilities are not provided. See [implementation status](NEXT-PHASE-PLAN.md)
+realtime capabilities are not provided. See [implementation status](archive/2026-09-19/NEXT-PHASE-PLAN.md)
 and [roadmap](../ROADMAP.md); these additions do not close the operational gates above.
 
 The [internal security audit](SECURITY-AUDIT.md) records reproduced findings, fixes
@@ -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 moved to the `urlcode-dynamic-link`
+extension (docs/EXTENSIONS.md), which was retired and unpublished on
+2026-09-19. No supported stored-link package ships today, and this runtime does
+not provide one: a project needing a durable link store owns it itself.
 
 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

@@ -1,95 +1,81 @@
-# Candidate and release security process
+# Candidate and release security
 
-URLCode 0.3.0 is the Apache-2.0 self-hosted baseline; licensing is defined
-in [LICENSE](../LICENSE). Two workflows share one audited build path and differ
-only in what they do with its output:
+The [development pipeline](DEVELOPMENT-PIPELINE.md) is the operational runbook
+for CI selection, release planning, tags, publication and recovery. The
+[September 19 audit](CI-RELEASE-AUDIT-2026-09-19.md) explains the changes;
+[the prior process and failure history](archive/2026-09-19/RELEASE-SECURITY.md)
+is retained as a historical record, not current instructions.
 
-- `candidate.yml` is dispatched manually on main and retains a **signed build
-  candidate** for 30 days without publishing it. Use it to review a commit
-  before tagging it.
-- `release.yml` runs on a `v*` tag whose commit is already on main, and publishes
-  a GitHub release. Publication to npm and GHCR is opt-in per repository variable
-  (`PUBLISH_NPM`, `PUBLISH_CONTAINER`), so a release can be artifacts-only.
+The license remains Apache-2.0. A successful release is not an independent
+security assessment, hostile multi-tenant readiness claim or deployment proof.
+See [release readiness](RELEASE-READINESS.md) and [security](../SECURITY.md).
 
-Neither workflow is a statement that a release is production-ready; see
-[release readiness](RELEASE-READINESS.md).
+## Source and validation
 
-## Publishing an alpha
+A release must name the checked-out commit, already on main, with successful
+full verification of that exact SHA and CodeQL analysis. Full verification
+means a successful nightly or manual `ci.yml` run across every supported OS/Node
+combination; the compact push/PR matrix alone does not authorize publication. Package manifests,
+lockfile versions and tag names must agree. Published peer floors must exist and
+extension tests must resolve the published packages, not workspace source.
+The manual core candidate and tagged core release use the same preparation
+script with the digest-pinned Node image from Dockerfile. Locked dependencies,
+verification, runtime audit, package installation tests and local drills precede
+packing. Build commands in that container receive no GitHub token.
 
-An alpha such as `0.4.0-alpha.1` follows the same path: tag `v0.4.0-alpha.1`
-on a commit that is already on main. The release workflow publishes to npm
-only when the repository variable `PUBLISH_NPM` is `true` and the npm trusted
-publisher for this repository and `release.yml` exists; otherwise the run is
-artifacts-only (a GitHub release with the signed tarball). Publish order is
-core → ui → auth → admin, because the extension packages declare
-`@jimhoyd/urlcode >=0.4.0-alpha.1 <0.5.0` and must resolve the core alpha.
+The candidate workflow stores artifacts without publishing. A tagged release
+publishes npm only when `PUBLISH_NPM=true` and core images only when
+`PUBLISH_CONTAINER=true`. Preparation retains original artifacts for 90 days
+before publication so reruns of the same run reuse them. Manual candidates retain
+their existing 30-day retention. Keep independent last-good artifacts and
+rehearse deployment rollback; Actions retention is not an archival guarantee.
 
-1. Report vulnerabilities privately through [GitHub advisories](https://github.com/jimhoyd-com/urlcode/security/advisories/new).
-   The maintainer triages impact, confirms affected exact revisions, coordinates a
-   fix/retest privately, and publishes an advisory with upgrade guidance when safe.
-   Current reviewed main is the security support baseline; no guaranteed SLA/backports.
-2. Change dependencies through protected PRs. Review upstream provenance/advisories,
-   lockfile integrity and tests. Direct dependencies are exact, npm installs use
-   `npm ci`, CI actions use full commit SHAs, and container bases use SHA-256 digests.
-   Dependabot proposes updates; it does not authorize merging. Never silently
-   refresh dependencies during a candidate build.
-3. After protected main checks pass, a maintainer manually dispatches
-   `.github/workflows/candidate.yml` **on main**, or pushes a `v<version>` tag to
-   run `.github/workflows/release.yml`. The release workflow refuses a tag whose
-   commit is not an ancestor of main, refuses a tag that disagrees with
-   `package.json`, and refuses to build a private or unlicensed package. It reads and validates the digest-pinned Node image directly from Dockerfile,
-   installs without lifecycle scripts, verifies, package-tests and runs local drills.
-   It packs the runtime and creates a CycloneDX dependency SBOM plus a manifest
-   recording source commit, lockfile hash, engine versions and artifact hashes.
-   The package contains `dist/`, produced inside that build from the tagged
-   TypeScript sources by Node's type stripping (`scripts/build.ts`); `dist` is
-   never committed. The manifest records the Node version that stripped it, the
-   locked TypeScript version and a SHA-256 per emitted file
-   (`dist/BUILD-MANIFEST.json`), so a download can be verified by running
-   `npm run build` on the tagged commit with that Node version and comparing its
-   `dist/` file by file. The build strips types and rewrites specifier
-   extensions; it never bundles, minifies or transforms syntax, so every line of
-   `dist/x.js` is the corresponding line of `src/x.ts`. CI's `build-fidelity`
-   job builds twice and diffs the trees, so the transform is known to be
-   deterministic before a tag is cut.
-4. The pinned official `actions/attest` action signs provenance for the package,
-   SBOM and manifest using short-lived GitHub OIDC/Sigstore credentials. No long-lived
-   signing key is stored. Signing permissions exist only in this manual job; build
-   commands run in a container without passing GitHub tokens. Candidate files are
-   retained as GitHub Actions artifacts for 30 days. A release additionally attaches
-   them to the GitHub release, and publishes to npm and to GHCR when those
-   repository variables are enabled.
+## Identity and provenance
 
-   **npm publication holds no credential.** The registry is configured with a
-   trusted publisher naming this repository and `release.yml`, so the publish
-   step exchanges the job's OIDC identity for a credential that lives for the
-   length of one publish. There is no npm token in the repository's secrets to
-   leak, revoke or rotate, and a fork or another workflow cannot publish under
-   this package's name. Provenance is generated on that same identity, so
-   `--provenance` is not passed and its absence is not a downgrade.
+The four per-package workflow filenames are stable npm trusted-publisher
+identities. npm publishing uses OIDC, npm 11.5.1 and a supported Node version,
+with no long-lived npm token. Renaming a workflow or changing the repository
+requires a reviewed registry trust migration. Successful preparation does not
+prove the registry-side identity permits direct publication.
 
-   A bearer token would silently take precedence over this exchange, so the
-   publish step must reference none; `test/release.test.ts` fails if one
-   reappears in it, and checks the npm and Node floors below which the exchange
-   is not attempted at all.
-5. Download the candidate for the intended commit and verify **each file**, e.g.
-   `gh attestation verify jimhoyd-urlcode-0.3.0.tgz --repo jimhoyd-com/urlcode --signer-workflow jimhoyd-com/urlcode/.github/workflows/candidate.yml --source-ref refs/heads/main --source-digest APPROVED_COMMIT_SHA`
-   (use `release.yml` as the signer workflow for a tagged release).
-   Check the verified provenance's source commit against the approved commit, and
-   compare package/SBOM hashes with the signed manifest. A signature establishes
-   provenance, not safety, reproducible bytes or production approval. See
-   [GitHub verification](https://cli.github.com/manual/gh_attestation_verify) and
-   [the official attestation action](https://github.com/actions/attest).
-6. Before registry publication, assign patch/release ownership and retention, and
-   document version/support policy. Before claiming hostile multi-tenant or
-   deployment-specific readiness, close independent-review and deployment gates. Keep last-good verified artifacts and compatible policies;
-   rehearse rollback. Never overwrite a published artifact/version or downgrade a
-   management writer past its audit/security baseline.
+`actions/attest` signs the candidate files with GitHub OIDC/Sigstore provenance.
+Core includes its package archive, dependency SBOM, build manifest, checksums,
+and, for a release, Homebrew formula. Extensions include their archive and
+checksums. The core manifest records source SHA, lockfile hash, Node and
+TypeScript versions and emitted-file hashes. `dist/` is built, never committed.
 
-The SBOM describes npm dependencies; it is not a complete OS/container SBOM. Hosted
-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.
+Verify an artifact with `gh attestation verify <tarball> --repo
+jimhoyd-com/urlcode`, and constrain verification to the expected workflow,
+source ref and source digest for the selected release. Compare the source and
+artifact hashes to the intended release, rather than accepting any signed file.
+A signature establishes provenance, not safety or reproducibility. The npm SBOM
+is not a complete OS/container SBOM; hosted runners remain platform-controlled.
+
+## Immutability and channels
+
+Never delete/recreate or move a version tag to repair a workflow. A source fix
+requires a new version. Repeating publication of an existing npm version requires
+identical SHA-512 integrity. GitHub assets are compared and missing assets added;
+existing unequal assets are never clobbered. Transient registry errors fail
+closed rather than count as an unpublished version.
+
+Alpha versions use npm/GHCR `alpha` and GitHub prerelease classification. New
+GitHub releases are not automatically promoted to GitHub `latest`. Mutable npm
+and container channels cannot regress to an older version. Existing core image
+versions are reused only with matching source labels; unlabeled historical
+images require a reviewed migration rather than an inferred identity.
+
+The coordinator creates one package tag at a time and waits for success before
+releasing dependents. Shared publication concurrency avoids cross-version races.
+The active immutable-tag rule blocks release tag updates/deletions with no
+bypass actors; its configuration is in `.github/rulesets/release-tags.json`. No automation needs permission to bypass main checks or approve
+its own PR. A repository-scoped GitHub App is the preferred eventual automation
+identity; a narrowly scoped fine-grained PAT can support a maintainer script.
+
+## Remaining validation
+
+Keep full supported-OS/Node coverage and archive-install tests green. The actual
+publish path, OIDC trust for every package, tag protection, GHCR behavior and
+partial-failure recovery must be verified on an authorized release; local tests
+and workflow inspection cannot prove them. The release helpers do not alter
+historical npm channels, GitHub flags, tags or registry artifacts.

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 durable-state extension is
+responsible for its own management listener, backup and recovery procedure. No
+such extension ships today — `urlcode-dynamic-link` has been retired.

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,10 @@ 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. The `urlcode-dynamic-link` extension package that replaced it
+has been retired and unpublished, so a project needing stored short links owns
+that storage itself.
 
 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.