chore: enforce stack documentation and package coherence

[ty-everett]

Purpose

Advance the non-QA documentation, release-operations, package-boundary, and Sonar new-code program in #324 with enforced, source-derived facts rather than another point-in-time audit.

This is intentionally a broad coherence wave: current package, runtime, conformance, documentation, security, and release claims now agree, and CI prevents the same drift from returning.

What changes

Generated facts and documentation governance

• Generate docs/reference/stack-facts.md from the governed 37-project inventory, 30 public package manifests, seven standalone infrastructure manifests, and conformance metadata.
• Generate deterministic conformance/PARITY_MATRIX.json classifications and validate 74 files / 6,650 vectors.
• Enforce the README contract for all 30 public packages, exactly one current package page per public package, package-page version/source correctness, freshness deadlines, and private/public registry boundaries.
• Add missing pages for create-bsv-app, @bsv/auth, @bsv/verifast, @bsv/wallet-toolbox-client, and @bsv/wallet-toolbox-mobile.
• Replace stale pre-consolidation links in current-facing docs while retaining clearly historical links in changelogs and archived audits.
• Rewrite current documentation maintenance, versioning, dependency, conformance, package-profile, reliability, security, release, rollback, and incident guidance.

Executable consumer documentation

• Add eight compiled examples covering 21 exact first-party package tarballs.
• Resolve each example's transitive workspace: runtime closure, pack those exact sources once, install in a clean temporary consumer with lifecycle scripts disabled, and compile with strict native TypeScript 7 and skipLibCheck: false.
• Run this check in CI and npm release preflight.

Package/declaration correctness

• Align WindowCWISubstrate declarations with canonical WalletInterface types; delegated implementation and wire behavior are unchanged.
• Publish @types/express for the six public packages whose declarations expose Express types; governance rejects missing type/runtime pairs.
• Make artifact checks automatically pack the exact transitive first-party runtime closure so coordinated unpublished patch candidates cannot fall back to stale registry versions.
• A clean Linux build exposed two implicit Express assumptions in Wallet Storage. Header access now safely narrows string | string[], and authenticated RPC identity is validated explicitly. Missing/empty/unknown identity fails closed; ordinary authenticated requests and wire results are unchanged.
• Candidate source versions: @bsv/sdk 2.2.1, @bsv/paymail 2.4.3, @bsv/auth-express-middleware 2.1.3, @bsv/payment-express-middleware 2.1.2, @bsv/overlay-express 2.4.3, @bsv/wallet-relay 0.2.3, and wallet toolbox/core/client/mobile 2.4.5.

Sonar new-code remediation

Superseded exact heads exposed nine Sonar findings in total. All were treated as actionable and removed rather than dismissed:

• replace two default string sorts with explicit comparators;
• replace the documentation-fence backtracking regex with a bounded line parser;
• replace the declaration-dependency regex with simple bounded parsing;
• split declaration policy validation to reduce cognitive complexity;
• remove nested template literals; and
• adopt String.raw for intentional backslashes; and
• use RegExp.exec() instead of String.match() for the final bounded example identifier check.

The superseded failed Sonar result is not merge evidence. The exact reviewed head reports zero open new-code issues and zero security hotspots.

Public-service and deployed-impact assessment

• No package is published and no service or image is deployed by this PR.
• Overlay, Wallet Storage, WAB, Message Box, and Wallet Relay remain public and cross-domain by default. No CORS, CSP, route, persistence, network, or deployment configuration changes are made; optional allowlists remain explicit operator policy and hosting/fallback URLs do not silently become allowlists.
• Wallet Storage only changes behavior when its authentication middleware contract is violated: it now fails closed with an unauthorized error rather than relying on an unsafe implicit property.
• The only other runtime-visible change is replacing an obsolete Overlay source-repository link with the consolidated package directory.
• Source patch versions remain candidates until a separately authorized release workflow publishes and verifies them.
• Deferred fuzzing/testing/QA remains out of this wave and scheduled after remaining non-QA work.

Validation

Exact reviewed head: 443011429507eb4d2306f210963f42d7dcb4b9c1 (tree 540edf37564ef5e0320c2ee4abfd49a15af4d4b4).

• full workspace build passed;
• forced clean Wallet Toolbox build against newly linked Express 5 declarations passed;
• all 30 public package artifact/clean-consumer checks passed;
• full 36-project test workspace passed serially; a parallel run had one resource-contention exit 139 without an assertion failure and the affected payment suite then passed 39/39 in isolation;
• SDK: 146 suites / 5,744 tests passed;
• Wallet Storage boundary: 4 suites / 36 tests passed, including missing-auth fail-closed coverage;
• the focused RPC boundary suite passes 7/7 and covers every changed executable line, including invalid authentication variants, explicit identity-mismatch rejection, multi-value trace headers, and absent optional identity claims;
• the exact Codecov comparison covers 21/21 changed executable lines (100%), with zero misses or partials;
• Overlay Express: 13 suites / 285 tests passed;
• formatting and warning-free lint passed for all governed projects;
• typecheck passed for all 36 non-root projects;
• repository health: 58 tests, 37 projects, 30 public packages, zero contract findings, 11 active governed exceptions, zero control errors;
• generated facts/doc policy: 30 public READMEs, 40 package pages, 87 freshness records, zero findings;
• conformance: 74 files / 6,650 vectors, zero metadata errors;
• compiled documentation: eight examples / 21 exact tarballs passed after the bounded-parser rewrite;
• documentation build: 106 routes prerendered and 111 built HTML files link-checked;
• dependency audit: no known vulnerabilities;
• cross-package version references and git diff --check passed.

Superseded CI iterations caught a no-install generator dependency, clean Express 5 assumptions, nine Sonar findings, and two partially covered authentication branches. All were reproduced or inspected, fixed, and covered. The exact reviewed head passed all 64 reported checks, including 56 CI jobs, both CodeQL languages, Codegen, Conformance, Sonar, Socket, and the merge gate. A prior-head Message Box image build timed out against Docker Hub after its build, lint, and 95 tests passed; the failed-job rerun completed the image build, vulnerability scan, and merge gate, and the final exact head then passed Message Box without retry.

Deliberate exclusions

• No SonarCloud administration change.
• No npm publication, tag, container build, deployment, DNS, or secret change.
• Draft PR fix(wallet-toolbox): derive ChainTracks from Arcade host, drop babbage defaults #306 remains excluded.
• Deferred QA/fuzzing remains preserved on codex/stack-wide-fuzzing and is not merged here.

Closes no tracker item until this exact head and resulting main are green and recorded in #324.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[ty-everett]

Admin exact-head review complete for 4430114 (tree 540edf37564ef5e0320c2ee4abfd49a15af4d4b4). GitHub does not permit the PR author to submit a formal APPROVE review, so this records the substantive sign-off before an admin merge. Deployment-impact review found no route, wire, persistence, CORS/CSP, image, manifest, or release change; public services remain public/configurable by default. Wallet Storage fails closed only when authentication is absent, invalid, or mismatched, with explicit regressions. All 64 reported checks pass; exact Codecov is 21/21 changed lines (100%, zero misses/partials); Sonar is 0 issues/0 hotspots; CodeQL, dependency review, Socket, artifacts, docs, conformance, coverage, mutation, browser/mobile, infrastructure image scans, and merge gate pass. No review threads remain.