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

package/docs/CI.md

@@ -1,5 +1,9 @@
 # Checking a project on GitHub
 
+For this repository's own PR checks and releases, see the
+[development pipeline](DEVELOPMENT-PIPELINE.md). This page describes the action
+used by applications built with URLCode.
+
 `jimhoyd-com/urlcode/action` is a composite GitHub Action for a URLCode
 *project*: a repository with a `urlcode.yaml`. It runs the same local checks
 you run by hand and, on pull requests, keeps one comment up to date with the
@@ -81,8 +85,9 @@ On `pull_request` events the action fetches the base commit, checks it out into
 a temporary git worktree, runs `urlcode routes` there and on the head with the
 head's runtime, and renders `routes --compare` as Markdown: one table each for
 added, removed and changed routes, or "No route changes". A changed route lists
-each differing field (handler, methods, state, middleware count, policies,
-generated marker or policy description) with its before and after value.
+each differing field (handler, methods, state, `sandbox`, `sandboxReason`,
+middleware count, policies, generated marker or policy description) with its
+before and after value.
 
 `action/comment.mjs` then finds the pull request's comments for the marker
 `<!-- urlcode-route-diff project="<project>" -->` and updates that comment,
@@ -135,7 +140,7 @@ urlcode routes --project . --compare /tmp/base.json --format markdown
 
 Or `make validate`, `make test` and `make audit ARGS='--expect-routes 2'`
 from the starter Makefile. The runtime repository exercises the action on
-every pull request against `examples/cookbook` (`.github/workflows/ci.yml`,
+full-lane pull requests against `examples/cookbook` (`.github/workflows/ci.yml`,
 job `action`) with the packed tarball as `runtime`, and `test/action.test.ts`
 checks that `action.yml` is a composite action with the inputs above and that
 every third-party action it or the starter workflow uses is pinned to a

package/docs/CLOUDFLARE.md

@@ -21,8 +21,7 @@ route pattern and the reason named:
 
 | Handler | Why it is refused |
 | --- | --- |
-| `function`, `middleware` | need worker threads and the QuickJS WASM engine |
-| `link` | needs a durable writable store the platform does not provide here |
+| `function`, `middleware` | need the self-hosted Node lifecycle, and worker threads and the QuickJS WASM engine when a route declares `sandbox: true` |
 | `page`, `static`, `download` | need a platform static-asset binding, not an inline copy |
 | `env`, `secrets` | would have to be baked into the artifact |
 

package/docs/CODEBASE-AUDIT-2026-09-20.md

@@ -0,0 +1,278 @@
+# Codebase, tooling and documentation audit — 2026-09-20
+
+Reviewed commit: `bca8ac7` (core 0.4.0-alpha.2, auth 0.1.0-alpha.5,
+admin 0.1.0-alpha.4, UI 0.1.0-alpha.6). Local environment: macOS,
+Node 26.8.2. Date is UTC. This report records findings; it does not change
+runtime behavior or remove supported features.
+
+The trusted default is implemented correctly in the dispatch paths inspected:
+only a route declaring `sandbox: true` enters the QuickJS pool. Ordinary
+project functions and middleware run in Node. Host access by trusted code is
+intentional, not an audit finding. Binding grants scope injected context;
+they do not confine trusted code's independent filesystem, environment or
+network access. Opt-in sandbox isolation and provider refusals remain necessary.
+
+## Scope and method
+
+Inventoried 966 tracked files. Reviewed the implemented specification,
+contribution/security instructions, runtime activation/dispatch, module loading,
+TypeScript authoring, inspection/manifests/diffs, extension hooks, workspace
+contracts, package/build/check scripts, CI/release configuration, starter,
+example/recipe coverage and documentation indexes. Used targeted source review,
+the complete local verification suite and synthetic reproductions. This is a
+repository-wide engineering audit, not a claim that every line or execution
+path received independent security review.
+
+Scanned tracked non-archive/non-spike Markdown for local links and YAML fences:
+64 YAML fences, 49 route/project-shaped candidates. Added only an omitted
+format version or the documented route wrapper for schema checks. Classified
+partial illustrations separately from complete examples. Semantic constraints,
+external services and prose fragments require more than schema validation.
+
+Searched existing repository issues before filing. Five new issues and new
+evidence on existing issue 168 retain all actionable findings below.
+
+## Findings, ordered by practical impact
+
+### 1. Inspection hides middleware execution-mode changes — P2
+
+[Issue 199](https://github.com/jimhoyd-com/urlcode/issues/199).
+
+For a `respond` route with `middleware: [mw.mjs]`, switching `sandbox` from
+true to false produces identical manifest route records and an empty route
+diff. This changes execution from QuickJS to full Node without appearing in
+those review surfaces. The overall manifest digest can change; it does not
+explain the change to reviewers.
+
+`src/explain.ts` adds sandbox information only inside the function-handler
+case. `src/manifest.ts` carries that handler object forward, while
+`src/readiness.ts` and `src/route-diff.ts` omit execution mode from inventory.
+Context already exposes it at route level.
+
+Reproduction: create the same middleware/native route in both modes, call
+`buildManifest`, obtain `createRuntime(...).testPlan()`, then call `diffRoutes`.
+Observed diff: `{"added":[],"removed":[],"changed":[]}`. Add route-level
+execution mode/reason to explain, manifest and inventory, with compatibility
+handling for older inventory files and regressions for both handler kinds.
+
+### 2. Auth/admin hook reactivation serves stale entry code — P2
+
+[Issue 198](https://github.com/jimhoyd-com/urlcode/issues/198).
+
+Both `packages/auth/src/lifecycle-hooks.ts` and
+`packages/admin/src/admin-hooks.ts` import an unchanged file URL. Loading a
+hook, editing its entry file, then loading it again in the same process returns
+the old hook. A synthetic decision changed on disk from allow/v1 to deny/v2;
+both loaders still returned allow/v1 after reactivation.
+
+Native trusted routes already give entry modules a new URL per activation.
+Apply an explicit hook reload policy and test it, or clearly require process
+restart for hook changes. This reproduction exercised the loaders directly,
+not the end-to-end development watcher and account flow. Transitive Node module
+caching is a separate, already documented limitation. Keep trusted execution
+as the default and reject unsupported sandbox hooks explicitly.
+
+### 3. TypeScript authoring rejects valid mixed-trust module reuse — P2
+
+[Issue 197](https://github.com/jimhoyd-com/urlcode/issues/197).
+
+`src/typescript-authoring.ts:34` assigns each source one trust mode and rejects
+reuse from a different mode. Two routes sharing a pure `f.ts`, one trusted and
+one sandboxed, fail with “Module is imported by both a sandboxed and a trusted
+route”. The equivalent JavaScript project activates and both routes return
+200/ok. Shared transitive helpers have the same restriction.
+
+Separate emission deduplication from sandbox reachability validation. A helper
+reachable by a sandboxed route must still satisfy all sandbox import/source
+budgets; trusted execution must not be downgraded or unnecessarily restricted.
+Also reconcile the documented unlimited trusted source size with the builder's
+16 MiB per-file authoring cap.
+
+### 4. Live guidance still contradicts trust by default — P2
+
+[Issue 196](https://github.com/jimhoyd-com/urlcode/issues/196).
+
+- `docs/yaml/functions.md:57` denies Node/npm/network/filesystem APIs immediately
+  after an ordinary trusted route example.
+- `docs/yaml/middleware.md:26` describes a mandatory shared sandbox.
+- `docs/MIDDLEWARE.md:49` applies guest clone/body restrictions without scoping
+  them to sandboxed execution. Reproduced: trusted middleware reads a native
+  response body and returns its uppercase text; the sandboxed version rejects
+  that operation.
+- `docs/SPECIFICATION.md` says `.js` ESM behavior is independent of package
+  settings. Reproduced: ESM `f.js` under `type: commonjs` fails trusted activation
+  and works in the sandbox. Ordinary Node resolution is the intended default;
+  the documentation should explain `.mjs` and package type accurately.
+- `README.md` and `docs/FRAMEWORK.md` overstate binding grants as the only way
+  secrets reach code. Scope that statement to injected bindings.
+- `docs/READINESS.md` calls the activated runtime isolated; the first test in
+  `test/typescript-authoring.test.ts` claims QuickJS execution but omits sandbox.
+
+The prose guards pass this revision despite these contradictions. Strengthen
+specific regression fixtures and fix the guidance; do not impose old sandbox
+restrictions on trusted code to make the prose true.
+
+The POST/body-based sandbox advisory is a related cleanup candidate. It is
+non-blocking and documented, but suggests isolation from request shape rather
+than evidence about code trust. Review whether to remove or reword it while
+retaining explicit `sandboxReason` information. This is a recommendation, not
+a discovered isolation failure.
+
+### 5. Copyable documentation examples fail validation — P2
+
+[New evidence on issue 168](https://github.com/jimhoyd-com/urlcode/issues/168#issuecomment-5747024306).
+
+- `docs/yaml/policies.md:18` uses `page.source`; the field is `page.file`.
+- `docs/policies/compression.md:35` uses `secret: api-key`, rejected by the
+  external binding-name grammar; an identifier such as `api_key` is admitted.
+- `docs/AI-AUTHORING.md:249` omits the leading slash on `webhooks/stripe`.
+  This also illustrates why schema checks alone cannot replace semantic route
+  validation. The same section still lists the retired `link` handler.
+
+The first two are complete fenced projects and fail `validateDocument`.
+The partial profile illustration in `docs/POLICIES.md:169` was excluded from
+findings because it deliberately omits a handler. Add classified executable
+snippets: complete projects, context-dependent fragments and intentionally
+invalid examples. Existing cookbook tests do not validate every prose example.
+
+### 6. Monorepo ownership, navigation and release prose need cleanup — P3
+
+[Issue 200](https://github.com/jimhoyd-com/urlcode/issues/200).
+
+- Package AGENTS files still direct findings to former package repositories.
+- Framework/status pages retain former source homes, old alpha combinations,
+  private cross-repository credential instructions and peer-pin language.
+- Two admin README links target nonexistent package-local release workflows.
+- Documentation navigation duplicates cookbook entries with conflicting 25/40
+  counts; llms.txt repeats semantics and TypeScript entries.
+- Hook comments claim core lacks a sandbox primitive although SandboxPool is
+  exported. The packages still explicitly reject sandboxed hooks; update the
+  reason and tracked work rather than claiming they already support them.
+
+Use local links and one canonical version/ownership inventory for live material;
+keep dated release evidence clearly historical. Consolidate the duplicate
+SQLite preflight predicates through development tooling without removing auth's
+runtime gate. Shorten repeated issue-history narration in implementation comments
+where a contract explanation and issue link are sufficient.
+
+Do not remove the supported UI primitive fallback, opt-in sandbox path, provider
+compatibility refusals, licenses or regression fixtures. No dead production module
+was established with enough evidence to recommend deleting it in this audit.
+
+## Verification evidence
+
+The final sequential `npm run verify` passed, including lint, strict typecheck,
+syntax/JSON/catalog checks, generated-document checks, workspace links, release
+checks, build, core tests and all workspace suites:
+
+| Suite | Passed | Skipped | Failed/cancelled |
+|---|---:|---:|---:|
+| Core | 518 | 1 | 0 |
+| UI | 57 | 0 | 0 |
+| Auth | 207 | 0 | 0 |
+| Admin | 68 | 0 | 0 |
+| Workspace scaffold integration | 1 | 0 | 0 |
+
+Total: 851 passed, one intentional HTTPS-deployment test skip. The integration
+test checks scaffold composition; it is not a live provider deployment.
+
+`npm run test:package` passed installation of the packed archive and
+starter/cookbook/authoring-consumer checks. Separate CLI HTTP fixture runs passed
+for the starter, assets, cookbook, Vercel, AWS, Cloudflare, conditions (with its
+documented public origin) and prerender source. The cookbook count audit passed
+with 40 routes. Extension, fake-egress, monitoring, provider-conformance and
+tunnel examples are also exercised by their dedicated core tests.
+
+`npm audit --omit=dev --json`
+reported zero known runtime advisories at audit time. Neither substitutes for
+source review or establishes absence of unknown vulnerabilities.
+
+The initial restricted-environment run could not run local HTTP tests. A first
+unrestricted run had five test-file cancellations; those files passed alone.
+An overlapping build also caused transient missing-declaration errors in a
+workspace run. The final sequential full run passed without cancellations.
+These intermediate results are not reported as confirmed product defects.
+
+## Remaining evidence boundaries
+
+No provider account was deployed, no release published, no production system
+probed, and no container/Windows/Linux/Node 22 or 24 run was performed locally.
+Live email/OIDC/passkey services, accessibility/browser/device assessment,
+operational recovery/soak evidence and independent sandbox review remain separate.
+Existing issues 58, 173, 174 and 185 already retain relevant acceptance,
+model-benchmark, schema-discovery and release/CI-evidence work; this audit does
+not close those gates.
+
+## Follow-up: dead-code reachability
+
+[Issue 203](https://github.com/jimhoyd-com/urlcode/issues/203) records a dedicated
+unused-code pass requested after the initial audit. Runtime source remains the
+same as the reviewed revision; the intervening commit only added this report.
+
+A conservative relative-reference graph rooted at package exports and CLI entry
+points reached all 157 tracked production TypeScript modules. Every direct
+runtime dependency has a production source reference, and every root script
+has a named reference elsewhere in the repository. No whole production file,
+runtime dependency or root script was established as removable.
+
+A TypeScript symbol/reference pass excluded 501 symbols exposed by public
+package entrypoints. Candidates were then checked with repository-wide search
+and manual inspection, including local uses, CLI imports, namespace dispatch,
+worker URLs and dynamically loaded agent-list code. The confirmed small removals
+are:
+
+| Declaration/plumbing | Evidence | Proposed cleanup |
+|---|---|---|
+| `src/capability-query.ts:47`, `capabilityNameList()` | Declaration only; no caller or public entry export | Delete the unused wrapper |
+| `src/catalog.ts:39`, `metadataFiles` | Declaration only; no reader or public entry export | Delete the unused constant |
+| `src/trusted-functions.ts`, `log` option/property | Assigned but never read | Remove this unused executor plumbing, preserving runtime observer/logging behavior |
+| `src/mcp-authoring.ts:57`, `expandHandler(path, handler)` | `path` is never read | Remove the argument and update callers |
+| `src/policies/cache.ts:201`, `revalidate(state, req, result)` | `state` is never read | Remove the argument and update callers |
+
+Several live implementation helpers are unnecessarily exported: admin's
+`activeKit`, core's `routeState`, `forbiddenHeaders`, `normalizeRoute`,
+`manifestFileName`, and local scaffold/render/name helpers in `init-with.ts`.
+These are candidates for removing export modifiers, not deleting their bodies.
+Check declaration dependencies before changing exported types.
+
+An additional TypeScript check with `--noUnusedLocals --noUnusedParameters`
+reported six unused parameters: the two production helpers above and four test
+callbacks. It reported no unused local declarations. This stricter exploratory
+check is separate from the normal passing typecheck.
+
+Public APIs with no internal callers, types used in public signatures, registry
+policy hooks, dynamic imports, supported UI fallback rendering and opt-in sandbox
+execution are not dead code. This reachability analysis does not prove that
+every branch executes. No production code was removed by this follow-up.
+
+## Follow-up: unnecessary files and distribution weight
+
+[File-level evidence on issue 200](https://github.com/jimhoyd-com/urlcode/issues/200#issuecomment-5747116642).
+
+One package-local script is obsolete: `packages/admin/scripts/peer-revisions.mjs`.
+It has no workflow/package-script caller and reads the deleted admin `peers.json`;
+executing it fails with ENOENT. Its only other named reference is historical
+monorepo prose. Remove it; workspace linking replaced its cross-repository
+revision-output mechanism. The earlier root-script scan did not cover this
+package-local leftover.
+
+The three package `CODE_OF_CONDUCT.md` files are byte-identical to the root copy
+(1,062 bytes each). Consolidate their links to the root policy before deleting
+the duplicates. Package governance also repeats repository-wide controls and
+can link to the root while retaining any package-specific information. Package
+licenses and attribution notices serve a different purpose and must stay.
+
+A dry-run npm package inventory includes 11 archived documentation files
+(179,666 bytes) and six design-spike files (184,792 bytes): about 356 KiB
+uncompressed combined. The audit report also ships because package.json includes
+all of docs. Consider excluding maintainer/history/design records from npm
+while retaining them in Git and keeping their references navigable. These
+figures are content sizes, not estimates of compressed download savings.
+
+The duplicate Claude plugin skills are intentional, checked distribution copies;
+cookbook/recipe copies make each project independently usable; upstream UI
+snapshots preserve attribution/provenance; the benchmark baseline is consumed
+by its gate. None is established as unwanted. No tracked build output,
+node_modules, tarballs, logs, backup files or TypeScript build-info files were
+found. Ignored local dependencies/build products are regenerable development
+output, not tracked repository clutter. No files were deleted in this audit.

package/docs/COMPLIANCE.md

@@ -49,11 +49,11 @@ A **project** rule runs once with:
 |---|---|
 | `document` | The parsed and validated `urlcode.yaml` (includes are merged into `routes`) |
 | `routes` | Route configuration by pattern, as written in YAML |
-| `plan` | `testPlan()`: `inventory[]` (`path`, `handler`, `methods`, `middleware`, `policies`, `state`), `policies` (the per-route describe map), `dynamicLinks` |
+| `plan` | `testPlan()`: `inventory[]` (`path`, `handler`, `methods`, `middleware`, `policies`, `state`), `policies` (the per-route describe map) |
 | `policies` | `effectivePolicies(document, route)` by pattern: the merged configuration of every policy on each route |
 | `origin` | The declared public origin, or `null` |
 | `target` | `node` unless the caller states another |
-| `host` | `{ requestLog, linkEvents, includeCode }` as declared for the deployment; `null` where undeclared |
+| `host` | `{ requestLog }` as declared for the deployment; `null` where undeclared |
 
 A **route** rule runs once per inventory entry and additionally receives
 `route` (the inventory entry), `config` (that route's YAML), `policy` (the
@@ -86,7 +86,6 @@ cache and compression secrets handling in `src/policies/cache.ts` and
 | `rfc6585/throttle-functions` | [RFC 6585](https://www.rfc-editor.org/rfc/rfc6585) §4 | medium | Every active function or middleware route has an effective `policies.throttle` | Declare a throttle on the route or the project |
 | `rfc9309/robots` | [RFC 9309](https://www.rfc-editor.org/rfc/rfc9309) | low | Some active route declares `policies.agents`, or an active `/robots.txt` `respond` route exists | Add a `/robots.txt` route or an agents deny list |
 | `rfc9110/expired-routes` | [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110) §15.5.11 | info | Lists routes past `expires` that still answer 410 | Remove them once the 410 window has served its purpose |
-| `ops/management-private` | [Management security](MANAGEMENT-SECURITY.md) | info | Reminder when `dynamicLinks: true`: the management API and `/_urlcode` probes belong on a private bind | Run `links api` privately with an auth file; keep probes internal |
 
 ### `strict` (baseline plus)
 
@@ -102,15 +101,13 @@ cache and compression secrets handling in `src/policies/cache.ts` and
 
 These rules check deployment settings, so `audit` takes `--request-log` to
 declare the level the deployment uses (the audit process itself always logs
-nothing). The CLI cannot enable link events, so it declares `linkEvents:
-false`; embedders pass `host` themselves. The references are the runtime's
+nothing); embedders pass `host` themselves. The references are the runtime's
 own [logging guarantees](MONITORING.md): records carry no URL, query, header,
 body or binding, and `detailed` adds only the method and route pattern.
 
 | Rule | Standard | Severity | Checks | Remediation |
 |---|---|---|---|---|
 | `privacy/request-log-minimal` | [Monitoring](MONITORING.md), Log records | medium (`info` when undeclared) | `host.requestLog` is `minimal` | Use the default log unless per-route rates are required |
-| `privacy/link-events-off` | [Monitoring](MONITORING.md), The link event channel | medium; `high` with `includeCode` (`info` when undeclared and `dynamicLinks` is on) | The link event channel is off, or on without `includeCode` | Enable it only for a declared purpose; never disclose codes |
 | `privacy/detailed-log-parameters` | [Monitoring](MONITORING.md), Log records | low | With `detailed` logging, no active route takes parameters (records name the pattern and method, never values) | Keep `minimal` on parameterised deployments |
 
 ## Writing custom rules
@@ -159,9 +156,9 @@ Without any compliance flag the audit report is unchanged apart from
   "findings": [{ "rule": "rfc6585/throttle-functions", "severity": "medium", "route": "/hello/{name}",
                  "message": "…", "remediation": "…", "standard": { "name": "RFC 6585 …", "reference": "…", "section": "…" } }],
   "counts": { "high": 0, "medium": 4, "low": 11, "info": 1 }, "pass": true,
-  "evidence": { "routes": 21, "active": 19, "dynamicLinks": false, "policies": ["agents", "cache", "security", "throttle"],
+  "evidence": { "routes": 21, "active": 19, "policies": ["agents", "cache", "security", "throttle"],
                 "files": ["urlcode.yaml", "routes/code.yaml"], "origin": null, "target": "node",
-                "host": { "requestLog": "minimal", "linkEvents": false, "includeCode": null },
+                "host": { "requestLog": "minimal" },
                 "scope": "declared configuration and runtime facts; not a deployment or certification" } }
 ```
 
@@ -190,7 +187,7 @@ const report = await runCompliance(runtime, {
   rules: [], override: {}, disable: [],               // as a rules module would export them
   ignore: ['rfc9110/expired-routes'],
   origin: 'https://links.example',
-  host: { requestLog: 'minimal', linkEvents: false }, // what the deployment is configured with
+  host: { requestLog: 'minimal' }, // what the deployment is configured with
 });
 await runtime.close();
 ```

package/docs/DEPLOYMENT-CHECKS.md

@@ -19,7 +19,7 @@ URLs for; defaults to the target), `--expect-routes N`, `--expect-metrics`
 (per request, 100-120000, default 10000), `--fail-on high|medium|low|info|none`
 (default `high`), the `audit` compliance flags (`--compliance`,
 `--compliance-rules`, `--compliance-ignore`, `--compliance-warn`), and the
-usual `--policy` and `--link-store` bindings the local snapshot needs to start.
+usual `--policy` binding the local snapshot needs to start.
 
 ## What it verifies
 

package/docs/DEVELOPMENT-PIPELINE.md

@@ -0,0 +1,181 @@
+# Development and release pipeline
+
+The repository uses npm workspaces, independent package versions, and Changesets
+for UI, auth and admin. Core remains at the repository root and is explicitly
+included in the shared release inventory. Moving it is not required to use the
+same release checks and coordinator.
+
+## Pull requests
+
+Every PR starts `verify`. A complete Git diff selects one of two lanes:
+
+- **Prose:** root project Markdown, `docs/**/*.md`, `llms.txt` and
+  `llms-full.txt` changes run guidance/generated-resource checks, runtime audit,
+  and the required container job. CodeQL retains its repository policy.
+- **Full:** all other changes, mixed changes, empty/unavailable diffs and main
+  pushes run static checks once and core and workspace suites separately. Both
+  suites retain Linux on Node 22/24/26. Main adds Windows/macOS on Node 24.
+  PRs add those platform legs for runtime, CLI, SQLite, fixture, dependency,
+  workflow and unknown changes; known UI presentation-only changes omit them. Package, action,
+  cookbook, reproducibility and operational checks retain their coverage.
+
+The prose allowlist is deliberately narrow. Package documentation, skills,
+starters, examples, schemas, manifests and workflow changes select full checks.
+A rename from source into docs also selects full checks. No required workflow
+uses `paths-ignore`.
+
+`verify-complete` accepts only the results specified by the successful plan.
+Failed, canceled, missing or unexpectedly skipped work fails the gate. Required
+check names (`verify-complete`, `container`) and CodeQL enforcement are preserved.
+The repository ruleset currently does not require a branch to be up to date;
+release publication separately requires verification of the exact main commit.
+
+```sh
+npm run check:docs                 # prose checks without the runtime suite
+npm run ci:plan -- BASE_SHA HEAD_SHA
+npm run ci:report -- RUN_ID         # read GitHub job/step durations
+npm run ci:history -- 100 2026-09-19 # group historical timing samples
+npm run verify                    # full local validation remains available
+npm run test:package              # builds and installs a real archive
+```
+
+CI uses `test:package:built` only after building in that same job. Core tests and
+workspace tests run in separate jobs to shorten their serial critical path;
+this increases job setup overhead and needs monitoring for runner queue pressure.
+After building all three extensions, the workspace job also runs the real
+`init --with auth,admin,ui` scaffold integration. Missing workspace outputs fail
+instead of silently skipping an absent external checkout.
+The [audit](CI-RELEASE-AUDIT-2026-09-19.md) records the previous timings.
+The [follow-up measurements](CI-FOLLOWUP-2026-09-19.md) record the first compact
+main result and explain why the new lanes still need 20 organic runs each.
+
+## Version and release ownership
+
+A feature PR records release intent in a Changeset for a changed workspace
+package. Review dependency/peer changes explicitly. Keep pre-mode enabled until
+an explicit decision to leave alpha. Do not force all packages to one version.
+Core version bumps remain explicit in the release PR, including its CLI banner.
+`release:check` verifies every manifest against its lockfile entry and checks the
+alpha-mode policy. Existing CLI tests catch core banner/version disagreement.
+
+A release PR collects version/changelog and lockfile changes together. Ordinary
+unreleased development does not move existing version tags or npm versions.
+Use the exact release commit after its full platform checks have passed. Routine
+main builds use five OS/Node combinations per suite (ten jobs total), rather
+than the full nine per suite (eighteen). Nightly runs at 07:17 UTC and manual
+runs retain all three operating systems on all three Node versions. Before a
+release, run `gh workflow run ci.yml --ref main` and wait for that exact commit's
+full run to succeed. A successful compact main run alone cannot authorize a
+release. Main pushes do not cancel scheduled/manual verification.
+
+Inspect release state:
+
+```sh
+npm run release:status   # registry channels, peer compatibility, remote tag SHAs
+npm run release:plan     # read-only JSON inventory, including root core
+npm run release:run      # read-only ordered proposal at HEAD
+```
+
+All three commands require network access; none publish. `release:run` selects
+unpublished manifest versions and releases already tagged at HEAD (for resuming
+partial completion). Its order is core, UI, auth, admin, skipping other already
+published versions. Plan fields come from package manifests, not copied versions
+in another config file.
+
+Once the release itself is authorized, from a clean checkout of that exact SHA:
+
+```sh
+npm run release:run -- --execute
+```
+
+This opt-in command creates missing tags through GitHub, refuses an existing tag
+at a different commit, and waits for each package's tag-triggered release before
+starting the next. It stops on failure or missing npm publication. Do not push
+all release tags at once: publication workflows share one concurrency group and
+GitHub may replace pending runs. The coordinator intentionally starts one at a
+time. It never merges a PR, bypasses checks, force-pushes or publishes locally.
+
+The coordinator needs `gh` authentication with repository Contents write and
+Actions read; reading checks also needs Checks read. It is intended for an
+authorized maintainer session or a repository-scoped GitHub App. A fine-grained
+PAT can serve a short-lived maintainer script with those permissions, but must
+have no ruleset bypass. The workflow `GITHUB_TOKEN` should not be used to create
+these trigger tags: its push events do not start another ordinary push workflow.
+For long-lived automation prefer a GitHub App; do not add a bypass to `main`.
+[GitHub App guidance](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/deciding-when-to-build-a-github-app)
+
+## Publication and recovery
+
+The four workflow filenames remain unchanged because npm trusted publishing
+names them. They call shared helpers for identity, preflight, peer installation,
+retry handling and publication. npm authentication remains OIDC; no npm token
+is introduced. Core candidate and release share `prepare-core-release.sh`.
+For an authorized release, first dispatch the manual `candidate.yml` workflow on
+the selected main commit. It extends the core candidate with UI/auth/admin
+archives and verifies all four together in an isolated temporary consumer:
+peer compatibility, installed versions, public imports and real scaffold
+composition. Its signed `train.json` records the proposed archives and integrity.
+A candidate does not publish, validate live providers or prove registry OIDC;
+release workflows still prepare and retain their own immutable retry artifacts.
+Extensions share `prepare-extension-release.sh` and test published peer floors.
+Auth/admin build in the workspace for packaging, then build and run their suites
+in a temporary copy outside the monorepo against exact registry peer floors.
+This preserves #184’s isolation fix; npm `--prefix` is not an isolation boundary.
+
+Preflight checks the checkout SHA, main ancestry, a successful exact-SHA full
+`ci.yml` nightly or explicit manual run, CodeQL, remote tag SHA, npm
+channel monotonicity and published peer floors. When a full run was canceled,
+run `verify` manually at the selected tag/ref, then rerun the failed release;
+never substitute another commit's passing run or move the tag.
+
+Prepared artifacts are retained for 90 days before publication. A rerun of the
+same workflow run restores those original bytes and skips preparation. npm
+versions already present must have identical SHA-512 integrity; existing GitHub
+assets must match byte for byte. Different bytes stop the release. An absent or
+expired artifact requires reconstruction that still passes these comparisons;
+if it cannot, diagnose and create a new version rather than overwrite history.
+
+GitHub release classification follows the manifest's prerelease status. New
+GitHub releases use `--latest=false`; stable latest promotion is a separate
+maintainer decision, avoiding accidental promotion by a package-level release.
+GHCR updates the derived channel (`alpha` for alphas, `latest` for stable) and
+preserves existing version images only when their source label matches. An
+existing image/channel without the required labels fails closed and needs a
+reviewed migration; this change does not silently relabel old images.
+
+Partial npm/GitHub/GHCR success is possible; those systems cannot be updated
+atomically. Rerun the original failed run, check its summary and then rerun the
+coordinator. A changed source commit requires a new version and tag. Failed
+OIDC configuration needs correction on npm, not tag deletion. A green dry run
+cannot prove registry-side OIDC trust; each package's first authorized publish
+must verify it.
+
+Historical tags, GitHub release flags and npm channels are not retroactively
+rewritten by these scripts. Use `release:status` to inspect them. The active [Immutable release tags rule](https://github.com/jimhoyd-com/urlcode/rules/23712319)
+prohibits update/deletion of `v*` and `@jimhoyd/urlcode-*@*` tags, permits
+creation, and has no bypass actors. Its reviewed configuration is tracked in
+`.github/rulesets/release-tags.json`. Main protection is unchanged.
+
+During the September 19 alignment, GitHub releases `v0.4.0-alpha.1` and
+`v0.4.0-alpha.2` were explicitly marked as prereleases and GitHub latest was
+restored to `v0.3.0`, matching npm. Their tags and artifact bytes were unchanged.
+Further performance and release-train validation is tracked in
+[issue #185](https://github.com/jimhoyd-com/urlcode/issues/185).
+
+### Windows fixture cleanup
+
+Auth/admin tests register resources with their package-local `test/cleanup.ts`.
+Cleanup runs in reverse acquisition order: close servers and SQLite services
+before deleting temporary directories, including services reopened by a test.
+Every registered callback is attempted even if another closer throws, and the
+combined error fails the test. Register each closer as soon as its resource opens.
+The suites use a five-minute test-file timeout so a stuck fixture is diagnosed
+before the CI job limit. Node applies this limit to whole test files too; the
+large auth-core file legitimately exceeds two minutes on Windows Node 22.
+Windows regression coverage runs on Node 24 for platform-sensitive PRs and
+main; nightly/manual runs cover Node 22/24/26.
+
+Failed auth service initialization also waits for its SQLite worker to terminate
+before rejecting. Callers can clean up or retry after a rejected open without
+racing a remaining database handle; configuration identity failures still fail
+closed with the same error code.