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

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.

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/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.