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

package/docs/CAPACITY.md

@@ -13,16 +13,56 @@ lookup after path parsing). Parameter candidates are grouped by segment count
 and scanned in specificity order; matching is O(P × L) in the worst case for P
 candidates and L segments. Static mount prefixes are scanned longest first.
 
-Plain redirects, declared responses, stored-link lookups and assets do not enter
-the sandbox. Stored links use a separate bounded database pools. A
-function or any attached middleware occupies one shared worker slot for its
-whole chain. Workers are shared by all programmable routes in that snapshot;
-there is no per-route fairness or reserved capacity. Awaiting guest timers still
-occupies the slot. A fresh guest and module initialization are part of each call.
+Plain redirects, declared responses and assets do not enter
+the sandbox or the trusted executor.
+
+`function`/`middleware` routes have **two distinct capacity models**, chosen
+per route by `sandbox` (docs/SPIKE-DEFAULT-TRUST-MODEL.md):
+
+- **`sandbox: true` (the isolated worker pool, unchanged from every earlier
+  release):** a function or any attached middleware occupies one shared
+  worker slot for its whole chain. Workers are shared by all `sandbox: true`
+  routes in that snapshot; there is no per-route fairness or reserved
+  capacity. Awaiting guest timers still occupies the slot. A fresh guest and
+  module initialization are part of each call. See "Enforced limits and
+  defaults" below for the numbers (2 workers, 5 s deadline, 32 MiB heap).
+- **`sandbox` false/absent (the trusted default):** the call runs in-process,
+  on the same event loop as everything else the server does — ordinary Node
+  concurrency, not a fixed worker-slot ceiling. There is no separate pool to
+  exhaust and no per-invocation heap/module reset: it is bounded by the same
+  `--max-in-flight` HTTP admission cap (default 64) that bounds every other
+  request, not by a `workers` count. A trusted call's declared `timeoutMs`
+  races the call's own promise rather than forcibly terminating a worker
+  thread — see "Trusted-path deadlines" below for what that does and does not
+  protect against.
+
+  This was architectural reasoning, not a measurement, until the run below:
+  see "Measured: sandboxed vs trusted dispatch" for the actual comparison.
 
 Node's main event loop remains a shared bottleneck for HTTP parsing, logging and
-native responses. Sandboxing contains application code authority and bounds
-individual execution; it does not make all host resources immune to exhaustion.
+native responses. The sandbox contains a `sandbox: true` route's application
+code authority and bounds its individual execution; the trusted default does
+not attempt to, by design. Neither mode makes all host resources immune to
+exhaustion.
+
+### Trusted-path deadlines
+
+A sandboxed worker's deadline is enforced by an interrupt handler the WASM
+engine checks between guest operations, backed by an independent outer
+termination that kills the worker thread if the guest never yields — the
+worker (and its slot) can be forcibly reclaimed even from a stuck call. A
+trusted, in-process call has no such mechanism available: `timeoutMs` starts
+a race between the call's promise and a timer, so a call that never resolves
+(an unresolved promise, an awaited operation that never completes) is
+answered with a 504 on schedule, but a call that blocks the event loop
+*synchronously* (an infinite `while` loop, a huge synchronous computation)
+is not preempted — it keeps running, delays that timer's own firing, and
+holds up every other request on the same process until it returns control to
+the event loop or the process is restarted. This is a real, documented
+difference from the sandboxed path's guarantee, not an oversight: Node has no
+supported way to interrupt another turn of the same thread's event loop from
+inside it. A route whose trusted code cannot be trusted to yield promptly is
+exactly the kind of route `sandbox: true` exists for.
 
 ## Enforced limits and defaults
 
@@ -39,15 +79,17 @@ individual execution; it does not make all host resources immune to exhaustion.
 | Requests per socket | 1,000 | Connection recycling; not a requests-per-second limit |
 | Header / request receipt / keep-alive timeouts | 10 s / 15 s / 5 s | These are not an overall end-to-end response deadline |
 | Request body | 1 MiB default | Buffered; route maxBytes can tighten to 0–1 MiB |
-| Sandbox concurrency | 2 workers, no queue | Shared per snapshot; full pool returns 503 |
-| Execution deadline | 5 s default | Entire middleware + handler invocation; timeout returns 504 |
-| Guest heap / stack | 32 MiB / 512 KiB | Fresh per invocation; not a bound on total process RSS |
-| Outer worker old-generation V8 budget | 128 MiB | Separate from WASM/host/native allocations |
-| Function response | 1 MiB default, 16 KiB / 256 header pairs | Buffered text/JSON; YAML headers also bounded |
-| Middleware | 16 entries per route | One shared slot/deadline, not 16 independent workers |
-| Function sources | 128 modules, 1 MiB/module, 4 MiB total | Project snapshot, including middleware dependencies |
-| Worker startup | 5 s deadline | Failure rejects activation; no untrusted host fallback |
-| Worker replacement | Up to 3 exits/minute per slot trigger replacement | Further churn leaves the slot unavailable until reload/restart |
+| Sandbox concurrency (`sandbox: true` only) | 2 workers, no queue | Shared per `sandbox: true` snapshot; full pool returns 503 |
+| Sandbox execution deadline (`sandbox: true` only) | 5 s default | Entire middleware + handler invocation; forcibly terminates the worker; timeout returns 504 |
+| Trusted concurrency (`sandbox` false/absent, the default) | Ordinary Node concurrency | Bounded by `--max-in-flight` (default 64), not a worker count; no separate pool to exhaust |
+| Trusted execution deadline (`sandbox` false/absent) | 5 s default (same `timeoutMs` knob) | Races the call's promise; cannot preempt synchronous event-loop-blocking code (see "Trusted-path deadlines" above); timeout returns 504 |
+| Guest heap / stack (`sandbox: true` only) | 32 MiB / 512 KiB | Fresh per invocation; not a bound on total process RSS |
+| Outer worker old-generation V8 budget (`sandbox: true` only) | 128 MiB | Separate from WASM/host/native allocations |
+| Function response | 1 MiB default, 16 KiB / 256 header pairs | Buffered text/JSON; YAML headers also bounded; applies to both execution modes |
+| Middleware | 16 entries per route | One shared slot/deadline (`sandbox: true`) or one in-process call (trusted), not 16 independent workers either way |
+| Function sources (`sandbox: true` only) | 128 modules, 1 MiB/module, 4 MiB total | Sandboxed snapshot, including middleware dependencies; a trusted route's own source is hashed for grant pinning but not bundled or budget-limited this way (see docs/FUNCTION-SECURITY.md) |
+| Worker startup (`sandbox: true` only) | 5 s deadline | Failure rejects activation; no untrusted host fallback |
+| Worker replacement (`sandbox: true` only) | Up to 3 exits/minute per slot trigger replacement | Further churn leaves the slot unavailable until reload/restart |
 | Assets | 16 MiB/file, 64 MiB unique contents | Buffered immutable snapshots; 10,000 static entries, depth 20 |
 | Logger buffering | Drop at 1 MiB stdout buffering | Reports logs_dropped when output recovers |
 
@@ -71,8 +113,70 @@ increasing a timeout also increases how long an attacker can occupy capacity.
 The CLI uses defaults. Keep settings identical across replicas unless testing a
 controlled rollout. See [operations](OPERATIONS.md).
 
+## Measured: sandboxed vs trusted dispatch
+
+The claim above — that the trusted path has "no fixed worker-slot ceiling"
+and scales as ordinary Node concurrency instead — was written as
+architectural reasoning when the trusted-by-default execution model shipped
+(docs/SPIKE-DEFAULT-TRUST-MODEL.md), not backed by a benchmark run. This is
+that run: `benchmarks/sandbox-vs-trusted.ts`
+(`npm run benchmark:sandbox-vs-trusted`), same 20 ms handler source on both a
+`sandbox: true` route and a trusted route in the same server, default
+settings (`workers: 2`, `maxInFlightRequests: 64`, `timeoutMs: 5000`), 2,000
+requests per concurrency level after a 20-request warmup, keep-alive
+connections. Raw output:
+[benchmarks/results/2026-09-19-sandbox-vs-trusted.json](../benchmarks/results/2026-09-19-sandbox-vs-trusted.json).
+
+One development machine: Intel Xeon @ 2.10 GHz, 4 vCPUs, 16 GiB RAM, Linux
+x64, Node v22.22.2, 2026-09-19. This is one machine's numbers, not a
+universal claim — re-run on deployment hardware before sizing anything.
+
+| Concurrency | Sandboxed req/s (successful) | Sandboxed shed | Sandboxed p95 | Trusted req/s (successful) | Trusted shed | Trusted p95 |
+|---:|---:|---:|---:|---:|---:|---:|
+| 1 | 39 | 0 / 2000 | 26.9 ms | 47 | 0 / 2000 | 21.5 ms |
+| 2 | 80 | 0 / 2000 | 26.5 ms | 95 | 0 / 2000 | 21.7 ms |
+| 8 | 80 | 1,912 / 2000 | 30.2 ms | 379 | 0 / 2000 | 22.1 ms |
+| 32 | 80 | 1,936 / 2000 | 43.5 ms | 1,465 | 0 / 2000 | 23.5 ms |
+| 128 | 80 | 1,950 / 2000 | 70.0 ms | 2,615 | 521 / 2000 | 80.6 ms |
+
+"Sandboxed req/s" and "shed" are separate columns for a reason: throughput
+computed over successful responses only is flat at ~80 req/s from
+concurrency 2 upward because the 2-worker ceiling admits at most two
+in-flight calls at a time and returns 503 immediately for the rest, exactly
+as "Enforced limits and defaults" describes (no queue). The ceiling is
+visible starting at concurrency 8 in this run (already >95% shed) and only
+gets worse as concurrency rises — 2 concurrent in-flight sandboxed calls is
+the practical limit regardless of how much load is offered.
+
+The trusted path has no such wall: it scales with offered concurrency —
+379 req/s at 8, 1,465 req/s at 32, both with zero shedding — until offered
+concurrency (128) exceeds the `--max-in-flight` admission cap (64), at which
+point it starts shedding too (521/2000, p95 rises to 80.6 ms) but keeps
+substantially higher successful throughput (2,615 req/s) than the sandboxed
+path ever reaches at any concurrency tested. This confirms the architectural
+prediction rather than contradicting it: the trusted path's ceiling is the
+admission cap, not a fixed worker count, and it sits far above the sandboxed
+path's 2-worker ceiling in this run. It is still a real ceiling — raising
+`--max-in-flight` moves it, it does not remove it — and it is shared with
+every other route on the process, per "Native routes and mixed traffic"
+below.
+
+Caveats specific to this run: one handler shape (a 20 ms guest/host timer,
+chosen to make both ceilings visible rather than to represent any particular
+application), one machine, one process with both route types present
+(so CPU contention between them is part of the trusted numbers, not
+excluded), and no TLS, proxy or production logging in the path. Re-run with
+your own handler's actual latency profile before sizing a deployment; see
+"Establish a deployment budget" below.
+
 ## A useful theoretical model
 
+This worker-slot model describes the `sandbox: true` path only. A trusted
+route has no fixed worker count to plug in as W; its ceiling is ordinary Node
+request concurrency bounded by `--max-in-flight`, not this model — see
+"Measured: sandboxed vs trusted dispatch" above for what that ceiling looks
+like in practice.
+
 Let W be worker slots, S the measured mean slot occupancy in seconds (including
 sandbox startup and cleanup effects), and lambda the offered programmable
 requests per second. An idealized worker ceiling is:
@@ -159,6 +263,13 @@ loop even though the HTTP listener is not restarted. Do not equate atomic swap
 with zero latency impact or incremental route updates. Prefer candidate replicas
 and traffic switching for production. `serve` does not watch configuration.
 
+A trusted route's own entry file is re-imported fresh on every reload (see
+[docs/FUNCTION-SECURITY.md](FUNCTION-SECURITY.md)), matching the sandboxed
+pool rebuilding its whole snapshot; a file that entry only imports is not,
+since ordinary Node module resolution — not a per-reload snapshot — governs
+it. Restart the process rather than reload after editing a trusted route's
+dependency, not just its declared `source`.
+
 Before parser-worker limits were introduced, recorded 100k-route startup RSS was about 621 MiB on one development machine,
 above the illustrative 512 MiB container example. Route limits are acceptance
 caps, not a promise that the maximum fits your deployment. See [measurements](PERFORMANCE.md).
@@ -186,20 +297,6 @@ production exercise. The readiness endpoint can stay 200 while all worker slots
 are busy. Use error/latency signals too. No universal safe RPS can be derived
 from the route count or these defaults alone. See [resilience](RESILIENCE.md).
 
-## Optional stored-link capacity
-
-Each SQLite store defaults to two read-only worker connections; writable stores
-add one writer. Independent read/write admission caps default to 32 each across
-their pool. Readers are configurable from 1–8, and caps from 1–32. Operations have
-a 5-second deadline and one-second SQLite lock wait. Public serving has no writer. The
-initial cap is 100,000 stored records across collections; this is separate from
-the YAML route count. No lookup cache is used, so visibility does not depend on
-cache invalidation. Store failures/overload return 503 and failed workers need
-reload/restart; healthy readers can continue while readiness is degraded. Management has a separate listener with 64 connections, 8 KiB
-headers and 16 KiB JSON bodies. Rate limiting remains an ingress responsibility.
-Do not extrapolate in-memory redirect benchmark numbers to database lookups;
-measure disk, writes, contention and restoration on the target host.
-
 Configuration parsing/schema validation now run in a terminated-on-deadline worker;
 route compilation still runs cooperatively on the host (10 seconds, yields every
 64 routes). Source, AST, structured-clone output, compiled routes, assets, module

package/docs/CI-FOLLOWUP-2026-09-19.md

@@ -0,0 +1,97 @@
+# CI and release follow-up, September 19, 2026
+
+This is the evidence and disposition for [#185](https://github.com/jimhoyd-com/urlcode/issues/185),
+after the Windows fixes (#190) and matrix change (#192). It does not authorize
+publication or change required checks.
+
+## Reproducible measurements
+
+```sh
+npm run ci:history -- 100 2026-09-19 > /tmp/ci-history.json
+npm run ci:report -- 35482828280
+```
+
+The history helper reads GitHub through `gh`, with four concurrent requests at
+most. It does not dispatch new runs. Increase the limit (maximum 1,000) as more
+history accumulates. Use a date cutoff after the rollout when comparing the
+same workflow generation. It groups by event, inferred lane and exact matrix,
+reports counts and nearest-rank p50/p95, and flags groups with fewer than 20
+successful first attempts. Failures/cancellations remain visible but are excluded
+from successful-run percentiles. Reruns are excluded because run creation time
+includes the human delay before retrying. Earlier attempts are not a complete
+usage ledger. Raw job/step durations and run URLs remain in the output.
+
+Workflow elapsed time ends at the last active job's completion. Runner-minutes
+sum overlapping job execution durations: they are neither wall time nor billed
+minutes. Job-creation-to-start is an observed scheduling interval, not a guarantee
+of pure runner queue time. Workflow-creation-to-start also includes dependencies.
+Missing timestamps remain missing; they are never treated as zero.
+
+The initial 100-run sample spans September 19 04:59 UTC through September 20
+02:00 UTC. Successful first-attempt results:
+
+| Configuration | Samples | Wall p50 / p95 | Runner-minute p50 / p95 |
+| --- | ---: | --- | --- |
+| Historical combined main, 9 jobs | 20 | 8m27s / 9m04s | 49.82 / 53.62 |
+| Historical combined PR, 3 jobs | 40 | 6m12s / 8m52s | 17.28 / 24.57 |
+| Split full main, 18 jobs | 1 | 7m36s / 7m36s | 74.30 / 74.30 |
+| Split compact main, 10 jobs | 1 | 6m48s / 6m48s | 43.20 / 43.20 |
+| Split compact PR, 10 jobs | 2 | 6m38s / 7m15s | 40.23 / 43.58 |
+
+Historical groups contain changing code and workflow revisions; they are context,
+not a controlled experiment. The sample includes no classified docs-only runs.
+It cannot satisfy the 20-run acceptance criterion for the new lanes. Do not
+manufacture 20 redundant workflow runs to fill the sample.
+
+The [compact main run](https://github.com/jimhoyd-com/urlcode/actions/runs/35482828280)
+used 31.1 fewer runner-minutes than the preceding
+[full matrix main run](https://github.com/jimhoyd-com/urlcode/actions/runs/35482515877),
+an observed 41.9% reduction between two runs, not an established long-term rate.
+Its Windows core job took 377 seconds: 258 in `npm test`, 58 in package smoke,
+13 in installation. Linux Node 22 spent 300 of its 355 seconds in `npm test`.
+The next useful optimization target is the runtime suite, not removing static,
+container, audit or provenance checks. CLI subcommands are separate steps in the
+raw report. File-level profiling is still needed before choosing balanced shards;
+extra shards would add setup and runner pressure.
+
+## Changes delivered in this follow-up
+
+- A Windows validation failure exposed rejected auth initialization returning
+  before its worker terminated. The caller now awaits termination before receiving
+  the original error; a deterministic regression test proves the ordering.
+- `ci:history` makes the remaining baseline measurable without new CI jobs.
+- Auth/admin release instructions now use scoped monorepo tags and the correct
+  trusted-publisher workflow filenames. Package agent guides file issues here
+  and point documentation at root `docs/`.
+- Optional evals checks its credential before checkout/setup/install, and retains
+  artifacts for 14 days. This avoids unused setup; it does not remove the weekly
+  quality check or claim measured savings from a workflow with no prior runs.
+- The manual signed candidate builds all four tarballs and installs them together
+  in a temporary consumer outside the workspace. It verifies the peer dependency
+  tree, installed versions, public imports, and `init --with auth,admin,ui`.
+  `train.json` records package SHA-512 integrity and the source commit; the
+  candidate manifest/checksums and provenance include the extension archives.
+  Failure stops the candidate before attestation/upload. Nothing is published.
+
+The candidate validates the proposed package set, not live-provider behavior or
+registry OIDC. Per-package release workflows still prepare their own archives
+and retain their original bytes for retries; candidate archives are not silently
+substituted for published release bytes. Before a release, dispatch the candidate
+at the selected main commit, then the full verification workflow, and inspect
+both results before using the authorized coordinator.
+
+## Remaining decisions and external validation
+
+| Item | Disposition |
+| --- | --- |
+| Windows packaging/process coverage | Delivered in #190/#192; Node 24 on relevant PRs/main, all supported versions nightly/manually. |
+| 20-run baseline per new lane | Wait for organic runs, then rerun the helper with a rollout cutoff. |
+| Dependency-aware package selection | Keep conservative coverage for now. UI feeds auth/admin; auth feeds admin; core extension/CLI/scaffold changes affect the full composition. A package map must include integration, generated styles, peers and tooling, not just changed directory names. |
+| Changeset/no-release enforcement | Still open. Define explicit core release intent as well as workspace Changesets; require reviewed reasons for no-release cases before implementing a gate. Blanket source-path rules would misclassify tests/tooling and root core is not versioned by Changesets. |
+| Move core into `packages/core` | Separate migration, not a prerequisite for fast CI. Root-relative build, package files, CLI, Docker and starter paths make this higher risk than keeping the explicit root inventory. |
+| OIDC and retained-artifact retry | Needs the next explicitly authorized release. No synthetic run proves npm's trust configuration or partial publication recovery. |
+| Historical GHCR image labels/digests | Blocked on read access: anonymous registry lookup returned 403; organization package API explicitly requires `read:packages`. No labels/digests were verified and no images or publication settings changed. The repository has no `PUBLISH_CONTAINER` variable; inherited organization variables could not be inspected with this credential. |
+| Dependabot grouping / unchanged nightly reuse | No change yet. Measure update PR fanout before grouping; unchanged source can still acquire new advisory findings, so reusing old verification indiscriminately would hide them. |
+
+Keep #185 open for these acceptance items. The remaining items are not evidence
+that a publish or recovery rehearsal has already succeeded.

package/docs/CI-RELEASE-AUDIT-2026-09-19.md

@@ -0,0 +1,322 @@
+# CI and monorepo release audit — 2026-09-19
+
+Status: historical findings and recommendation. The accompanying implementation
+and current commands are documented in [the development pipeline](DEVELOPMENT-PIPELINE.md).
+The proposed helper table below records the audit design, not the installed command list. Source inspected:
+`3a3d9adf6f0ec53faa078c93dfb977aa5ac416f7`; GitHub settings, runs, tags,
+releases and npm dist-tags were read on September 19. Concurrent PRs may change
+this snapshot. This review does not authorize publishing or changing protections.
+
+## Recommendation
+
+Keep npm workspaces and Changesets, independent package versions, and the
+existing public package names. Add an explicit change classifier for CI and one
+release coordinator for all four packages. Preserve the existing required gate
+and CodeQL policy. Stop using tag pushes as the place to discover whether a
+release is buildable. Prepare and validate an immutable release plan first;
+create tags from that plan once; resume partial publication without moving them.
+
+Do this incrementally. A repository layout migration, Nx, Turborepo, remote
+caching, or fewer security assertions is not a prerequisite for faster PRs.
+
+## Measured bottleneck
+
+[PR #181](https://github.com/jimhoyd-com/urlcode/pull/181) changed only
+`AGENTS.md` (9 additions, 4 deletions). Its
+[verify run](https://github.com/jimhoyd-com/urlcode/actions/runs/35475753912)
+took **9m08s** from creation to completion.
+
+| Job | Execution time |
+| --- | ---: |
+| verify, Linux / Node 22 | 8m24s, after 39s from workflow creation to job start |
+| verify, Linux / Node 24 | 5m49s |
+| verify, Linux / Node 26 | 5m36s |
+| build-fidelity | 27s |
+| action | 25s |
+| container | 22s |
+| audit | 19s |
+| verify-complete | 2s |
+
+Within Node 22, `npm run verify` took 7m33s. Its core tests took 281.7s,
+auth tests 92.9s, admin tests 23.6s, and UI tests 2.7s. These suites run
+**serially**. Lint, typecheck and source checks took roughly 29s combined.
+Package verification subsequently took 28s; drills took 7s. This is chiefly
+execution time, not queueing, in this example.
+
+The same pattern appears in
+[PR #180's run](https://github.com/jimhoyd-com/urlcode/actions/runs/35475563183):
+8m38s overall, with Node 22 the longest job. These are sampled runs, not a
+long-term percentile study or a demonstrated performance gain.
+
+Conversely, the
+[UI alpha.6 release](https://github.com/jimhoyd-com/urlcode/actions/runs/35475220590)
+took 19m23s: approximately 11m24s before the job started, then 7m37s in the
+whole-repository verify step. Both queue pressure and unnecessarily broad
+release verification matter there; the API does not establish the queue's cause.
+
+The workflow already avoids branch-push plus PR duplication and cancels stale
+PR runs. Its three PR matrix legs repeat lint, types, generated-file checks,
+builds, every package's tests, package smoke tests and drills. Main expands this
+to nine OS/Node combinations. `test:package` builds again after `verify` has
+built; candidate/core release explicitly build before calling `verify`, which
+builds again, and then `test:package`, which builds a third time.
+
+## What the checks buy
+
+| Check | Purpose | Proposed placement |
+| --- | --- | --- |
+| Documentation and generated resources | Prevent stale references, guidance and authoring resources | Every PR; standalone fast lane for prose changes |
+| Lint and typecheck | Source and contract errors | Once per relevant change on a canonical Node version |
+| Core and extension regressions | Behavioral, integration and isolation invariants | Affected packages and downstream consumers on PRs; full validation for releases |
+| Supported Node versions | Detect runtime compatibility failures | Retain all three versions for runtime changes initially; avoid repeating static checks |
+| Windows/macOS | Path, process, filesystem and platform differences | Targeted PR coverage plus full main coverage initially |
+| Package install smoke | Prove shipped archives and declarations work | Relevant package/CLI/starter changes and releases; lightweight pack inventory for shipped-doc changes |
+| Container | Validate the shipped execution environment | Keep existing required job; early optimization can leave this cheap job alone |
+| Action smoke | Exercise the consumer-facing composite action | Runtime/action/starter/build changes |
+| Build fidelity | Detect nondeterministic emitted files and packs | Build/package/toolchain changes and releases |
+| Runtime dependency audit | Detect known advisories | Keep initially: measured cost is small; also run on a schedule and before release |
+| CodeQL | Static security analysis | Preserve current enforced policy; not the observed critical path |
+| Operational drills | Local lifecycle/recovery regression signal | Relevant runtime changes, main and release validation |
+| Real-model evals | Authoring quality regression | Existing weekly/manual workflow; no need to put it on ordinary PRs |
+
+Do not remove timeout, worker replacement, sandbox or authentication tests to
+save time. Profile and change their scheduling or fixtures while preserving the
+behavior they establish. The longest sampled core subtests included explain
+versus runtime agreement (~35s), a slim-image installer test (~21s), and sitemap
+limits (~21s). Investigate repeated CLI startups and repeated project loading;
+these measurements do not yet establish which internal operation dominates.
+Auth's ~93s warrants separate profiling, including password hashing, without
+changing production security parameters to speed up tests.
+
+## PR workflow shape
+
+Always start the workflow. A small, tested classifier compares the complete PR
+diff against its base, including renamed/deleted paths, and emits an explicit
+job plan. Missing history, unknown paths, classifier errors and workflow/shared
+toolchain changes select full verification. Do not infer safety just from a
+`.md` extension: starter, recipe and executable authoring inputs need their
+own categories. Core changes affect all consumers; UI affects auth/admin; auth
+affects admin; admin-only changes need not retest all of core.
+
+For a prose-only PR, run guidance and generated-resource checks, local link and
+reference checks, and applicable package file-inclusion assertions. Extract this
+from today's `check` rather than calling the full source/test syntax walk.
+Changes to generator code, manifests, lockfiles, schemas, executable examples or
+CI configuration must leave the prose-only lane.
+
+For code PRs, run static checks once, build required outputs/styles in dependency
+order, and schedule core/UI/auth/admin tests independently. Start by preserving
+the current Node coverage. Pilot two balanced core-test shards on the slowest
+leg, measure runner-minutes and wall time, and increase only if the gains justify
+the extra jobs. Keep the full local `npm run verify` entry point.
+
+The `verify-complete` gate must know which jobs the classifier required. It must
+reject failure, cancellation, missing results and unexpected skips; accept a
+skip only when the validated plan explicitly marks that job unnecessary. Test
+the gate's failure paths. The present gate rejects every skipped dependency, so
+adding `if:` conditions without updating its contract will break merging.
+
+Do not add workflow-level `paths-ignore` to a required workflow: GitHub documents
+that such skipped workflows can leave required checks pending. Use job selection
+inside an always-triggered workflow instead.
+[GitHub documentation](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/skip-workflow-runs)
+
+The live main ruleset requires `container` and `verify-complete`, and separately
+enforces CodeQL findings. It has no bypass actors. Its strict up-to-date setting
+is **false**, contrary to CONTRIBUTING's claim that an up-to-date branch is
+required. Preserve protections in the first implementation; reconcile that
+documentation. A later policy change needs a deliberate review, not an implicit
+side effect of renaming jobs.
+
+Windows failures are real: the
+[main run at cc582f2](https://github.com/jimhoyd-com/urlcode/actions/runs/35475923267)
+failed on `spawnSync npm.cmd EINVAL` in UI packaging. PR
+[#182](https://github.com/jimhoyd-com/urlcode/pull/182) already addresses this.
+Linux-only PR tests let this reach main. Add a focused Windows packaging/process
+smoke for relevant changes before considering a smaller main matrix. Keep the
+existing full main matrix during rollout; moving exhaustive coverage to nightly
+is a later tradeoff, and release candidates must still pass full validation.
+
+Initial goals: prose PRs under 90 seconds excluding runner queueing; ordinary
+code PRs under 5 minutes. These are targets, not measured promises. Report queue
+time separately from execution, and compare p50/p95 over at least 20 runs per
+change class before deciding the optimization succeeded.
+
+## Release and tag findings
+
+1. **Tags have actually moved across source revisions.** Release history for
+   `v0.4.0-alpha.1` records five distinct commits: `b5cd619`, `871dd87`,
+   `bb0f9e6`, `84e45ea`, then successful `8dabc7e`. The sampled history also
+   shows multiple commits for `v0.3.0`, `v0.2.0`, and `v0.1.0`. This establishes
+   reuse of tag names across commits, not who changed them or whether every
+   failed attempt published an artifact. The live ruleset inventory contained
+   only a branch ruleset, not tag protection.
+2. **An ancestor of main is not necessarily a validated release commit.** All
+   four release workflows check main ancestry, but do not require the exact
+   commit's main CI result. UI alpha.6 published from `8fa7f8b` while that
+   commit's main verify run failed on Windows. Release validation was Linux-only.
+3. **Core alphas are classified as normal GitHub releases.** Both alpha.1 and
+   alpha.2 had `prerelease: false`; GitHub's latest-release endpoint returned
+   alpha.2. Core's release creation omits the prerelease flag. npm correctly
+   separates its `alpha` channel; this is a distinct GitHub-channel defect.
+4. **Core container publication always updates `latest`.** `release.yml` tags
+   and pushes `latest` even for prereleases when `PUBLISH_CONTAINER` is enabled.
+   The code path is confirmed; this audit did not establish whether an alpha
+   actually overwrote the live GHCR tag.
+5. **Candidate and release have already diverged.** Candidate reads Dockerfile
+   into two shell variables, swallowing `AS build` into the image variable and
+   failing the digest regex. The same parse was fixed only in release. Running
+   candidate's parser locally against the current Dockerfile reproduced failure.
+   The last listed candidate successes predate this snapshot; no new candidate
+   was dispatched during this audit. Existing release tests check release's parser,
+   not both paths.
+6. **Existence is treated as sufficient for retry.** Publish steps skip an
+   existing npm version without checking its integrity against the candidate;
+   GitHub release uploads use `--clobber`. The fidelity job tests repeated packing
+   in one checkout, not equality to a prior publication. Extension builds use
+   floating Node 22 and registry-installed peers, so same-commit reproducibility
+   across days is not established. Preserve and compare the original artifact.
+7. **Concurrency is scoped to a tag.** Two different versions of one package can
+   publish concurrently; there is no shared release-train order or monotonic
+   channel guard. A late old release could update a channel after a newer one.
+8. **Changesets is only partially in charge.** Version 3.0.3 is installed and
+   pre-mode is enabled, with independent versions. Core is outside its workspace
+   package set. The tag checker checks trigger disjointness, not remote tag SHA,
+   registry integrity, missing changesets, peer compatibility or channel state.
+   PR [#183](https://github.com/jimhoyd-com/urlcode/pull/183) already tackles a
+   Changesets peer-range rewrite and stale channel documentation; build on it.
+9. **Release documentation contains competing snapshots.** VERSION-ALIGNMENT
+   still describes old repository pins, and the Changesets README says only UI
+   is covered and publishing is not wired up, despite a successful monorepo UI
+   release. RELEASE-SECURITY describes candidate/release as sharing a path that
+   has demonstrably diverged. Generate the live inventory; retain policy in prose.
+
+The actual npm channels at audit time were:
+
+| Package | `latest` | `alpha` |
+| --- | --- | --- |
+| core | 0.3.0 | 0.4.0-alpha.2 |
+| ui | 0.1.0-alpha.5 | 0.1.0-alpha.6 |
+| auth | 0.1.0-alpha.3 | 0.1.0-alpha.3 |
+| admin | 0.1.0-alpha.3 | 0.1.0-alpha.3 |
+
+Different channel values are not inherently drift. Historical extension `latest`
+values are already alphas; do not silently move them. Define channel intent,
+test the documented install combinations against peer ranges, and report
+deviations. An old core release tag also should not follow current main:
+unreleased development is normal; silently relabeling a published version is not.
+
+## One release process for four independently versioned packages
+
+Use Changesets for reviewed release intent and changelogs, with `fixed` and
+`linked` remaining empty. Require a changeset or a reviewed no-release reason
+for changes to publishable behavior. A routine feature PR need not manually
+bump versions: an accumulated release PR owns version changes, lockfile updates,
+peer-range changes and changelogs together. This replaces VERSION-ALIGNMENT's
+instruction to bump on every source-changing PR once the new flow is implemented.
+[Changesets configuration](https://github.com/changesets/changesets/blob/main/docs/config-file-options.md)
+
+Near term, keep root core where it is and include it explicitly in the common
+release inventory and plan, with its existing version update reviewed in the
+same release PR. Do not pretend `changeset version` covers it. Longer term,
+evaluate moving core to `packages/core` with a private tooling root so Changesets
+can own all four uniformly. That is a separate migration with CLI/container/
+starter/package tests, not part of the urgent CI fix. Preserve existing tag
+formats during this transition; any future new core tag format needs an explicit
+compatibility decision for install.sh, Homebrew, action consumers and old links.
+
+Proposed lifecycle:
+
+1. A protected release PR produces versions and a plan listing package name,
+   directory, version, tag, channel and dependency order. Manifests supply the
+   versions; the plan does not become a second hand-maintained version database.
+2. After merge, select and freeze its exact main SHA. Require that SHA's main
+   checks and release-specific validation; never substitute the newest passing
+   run from another commit. A canceled/missing full check must be run for the
+   selected SHA. Run without publication credentials during preparation.
+3. Build once with locked tooling, pack the proposed packages, and install the
+   actual tarballs together in a clean consumer project without development
+   export conditions. Separately test declared published peer floors. Where a
+   new floor belongs to this release, test its candidate tarball before publishing
+   and confirm registry resolution after its predecessor publishes.
+4. Sign and retain artifacts and a manifest binding source SHA, package versions,
+   dependency versions, lock hash and artifact hashes. Exercise this same prepare
+   path for a manual candidate; candidate must not be a second copied implementation.
+5. Create each expected tag once at that SHA. Refuse a remote tag at a different
+   SHA. Publish the prepared bytes in dependency order: core/UI before auth, auth
+   before admin, including only packages that need a release. Serialize publication
+   across the release train. Keep write/OIDC permissions confined to publication.
+6. On retry, reconcile each artifact with npm integrity, tags, GitHub assets and
+   container digests. Identical means complete; a mismatch stops. A registry
+   timeout is not proof a version is absent. Never clobber a different asset or
+   move a version tag. Reuse retained bytes; if unavailable, require a rebuild
+   that matches recorded hashes. A source fix needs a new version and release PR.
+7. Mark prereleases consistently on GitHub/npm/GHCR, and update mutable channels
+   only according to explicit policy with a guard against regressions. Summarize
+   partial success clearly; separate registries cannot form an atomic transaction.
+
+Protect release tag namespaces against update/deletion, with a narrowly defined
+creation path. This is a proposed strengthening, not a settings change made by
+the audit. Avoid a token-created-tag event chain: coordinate preparation and
+publication explicitly in workflow jobs/dispatch, rather than depending on
+another push workflow being triggered by a workflow-created tag.
+
+Initially retain the existing four trusted-publisher workflow filenames as thin
+wrappers around shared checked-in helpers. Consolidating to a new filename is a
+registry trust migration: verify each package's npm publisher identity and direct
+publish permission first. A dry run cannot prove the OIDC exchange works.
+[npm trusted publishing](https://docs.npmjs.com/trusted-publishers/)
+
+## Small helper surface
+
+These names describe proposed commands, not commands implemented by this audit.
+
+| Command | Contract |
+| --- | --- |
+| `npm run ci:plan -- --base SHA --head SHA` | Print change class, affected package closure, required jobs and why; deterministic and fail closed |
+| `npm run ci:report -- --run ID` | Read GitHub job/step timings, separate queue and execution, show failed checks and run links |
+| `npm run release:status` | Read manifests, Changesets state, Git tags, GitHub releases, npm versions/channels/integrity and peer compatibility; no mutations |
+| `npm run release:plan -- --sha SHA` | Produce the exact package/version/tag/channel/order plan, including root core |
+| `npm run release:prepare -- --plan FILE` | Validate, build, pack, smoke-test and write immutable artifact manifest; no publication |
+| `npm run release:publish -- --plan FILE` | CI-only mutation path; validate commit/checks/tags/artifacts, publish or resume idempotently |
+
+Use structured JSON outputs plus a short human summary. Share the version/tag/
+channel parser, manifest inventory, Docker image parser and integrity comparison
+between candidate and release. Test those contracts by execution, not only by
+regex checks that particular shell snippets exist in YAML. Add workflow syntax
+validation and fixtures for wrong tag, wrong SHA, mismatched version, prerelease,
+partial publish, existing unequal artifact, registry outage and peer-floor failure.
+
+## Rollout order and acceptance
+
+1. **Release correctness:** shared candidate parser, correct GitHub/GHCR alpha
+   handling, read-only status/preflight, immutable retry checks and exact-SHA
+   main-CI gate. Coordinate with #183; preserve the current publisher identities.
+2. **Immediate PR speed:** prose lane and tested classifier/gate. Keep existing
+   required check names, audit, CodeQL and container. Demonstrate a docs-only PR
+   finishing quickly and a deliberately failed required job blocking the gate.
+3. **Code throughput:** split static/core/workspace checks, remove redundant
+   builds, profile and shard the slow suites, add targeted Windows coverage.
+   Verify equivalent test coverage and measure queue/cost as well as latency.
+4. **Release coordination:** one Changesets release PR and package inventory,
+   one preparation path, serialized dependency-aware publication and immutable
+   reconciliation. Prove partial-failure recovery on a future authorized release.
+5. **Optional structural work:** core workspace migration and reconsideration of
+   the nine-leg main matrix after measured coverage/performance evidence.
+
+This audit made no release, tag, registry-channel or branch-protection changes.
+It inspected live evidence and reproduced the candidate parser failure locally;
+it did not execute a new full matrix, deploy containers, change npm trust, or
+prove end-to-end recovery. Passing CI is not an independent security assessment.
+
+## Implementation follow-through
+
+The user subsequently authorized implementation. The accompanying PR installs
+the conservative prose lane, separate core/workspace jobs, shared release
+helpers, live inventory and an explicit sequential tag coordinator. Root core
+remains outside Changesets; whole-train preparation before any tag and finer
+package selection are tracked in [#185](https://github.com/jimhoyd-com/urlcode/issues/185).
+The user explicitly approved the immutable-tag rule, now active as
+[23712319](https://github.com/jimhoyd-com/urlcode/rules/23712319), without bypass.
+The two historical core alpha release flags were corrected and GitHub latest
+restored to stable v0.3.0. No tags or artifact bytes were rewritten.