fix(wallet-toolbox): wire live-sync chain preflight and ProcessSyncChunkResult.error

[sirdeggen]

Addresses #541 and #542 by wiring the existing public surfaces. This is not an API deletion.

Reworked after maintainer review (CHANGES_REQUESTED): WERR_NETWORK_CHAIN and ProcessSyncChunkResult.error stay public. Live syncToWriter / syncFromReader now compare reader and writer TableSettings.chain before any chunk moves and throw WERR_NETWORK_CHAIN on mismatch. Custom writers may set ProcessSyncChunkResult.error; both live-sync loops throw that error and stop. First-party providers still throw. Deserializer and instanceof JSON round-trip coverage remain.

Merged onto current origin/main including #1029 (6493d5f29). Conflicts were changelog and release notes only; live-sync source did not conflict. Unpublished candidate remains 2.14.7.

Program and scope

• Tracker or issue: fix(wallet-toolbox): WERR_NETWORK_CHAIN is defined and deserialized but never thrown #541, fix(wallet-toolbox): ProcessSyncChunkResult.error is declared but never set or read #542
• Program gate(s) advanced: none
• Why this change is needed: the public error class and result field existed but live sync did not throw or honor them.
• Explicitly out of scope: removing public exports, changing BRC-38 import or ChainTracks ingest errors (they still throw generic Error), and executing manual/funded suites
• Exact head SHA reviewed: e9280ff14157f038f584d2a362409006a86c5561

Impact

• No public package source or manifest changed
• Public package source or manifest changed; affected packages are listed below
• Infrastructure source, dependency, image, or deployment configuration changed
• Public API, exports, types, runtime targets, or browser/mobile behavior changed
• Security-sensitive boundary changed
• Documentation or examples changed

Affected packages/services and intended patch versions (publication occurs only
through the release workflow after approval):

• @bsv/wallet-toolbox 2.14.7 (unpublished candidate vs published 2.14.5; releaseType remains patch; no version bump)
• @bsv/wallet-toolbox-client and @bsv/wallet-toolbox-mobile share the same source

Verification

• Local commands and results after this merge:
  • pnpm --filter @bsv/wallet-toolbox exec jest --testPathPatterns='WalletError.test|liveSyncGuards.test|liveSyncManager.test' --no-coverage — 3 suites, 35 passed
  • pnpm docs:packages:check — passed
  • pnpm health:check — passed (existing maintenance reminders only)
• Hosted CI run: https://github.com/bsv-blockchain/ts-stack/actions/runs/38276831958 on exact head e9280ff14157f038f584d2a362409006a86c5561. 39 successful checks including Build, lint, and policy, build-and-test (24.x), wallet-toolbox coverage, packed-consumer, browser/mobile, Mutation quality, and merge-gate. Expected skips only.
• Conformance evidence: hosted Conformance Vectors and ts-runner succeeded
• Coverage delta: hosted wallet-toolbox coverage succeeded
• Lint/typecheck delta: hosted CI / Build, lint, and policy succeeded
• Browser/mobile/packed-consumer evidence: hosted wallet browser, wallet mobile, browser packages, and package-artifacts succeeded
• Performance or bundle-size delta: none expected
• I self-reviewed the complete diff for correctness, security,
  compatibility, public API, artifacts, dependencies, docs, and operations
• All applicable checks are terminal and successful on the exact head; any
  scope-based skip is expected and validated by the merge gate

Security and dependencies

• No dependency or lockfile change relative to current main
• Changelog, runtime relevance, peer compatibility, transitive graph, and
  audit results were reviewed
• CodeQL/negative tests cover any changed trust boundary
• The exact-head CodeQL analysis has no new alert
• The exact-head repository quality gate reports zero new Sonar findings
  (including accepted or false-positive issue states) and zero unreviewed hotspots;
  Sonar's aggregate Quality Gate passed verdict alone is not merge evidence
• No new override, advisory dismissal, quality suppression, or skipped test
• Any temporary exception is registered with owner, evidence, review date,
  and removal condition
• Workflow permissions and lifecycle-script behavior remain least privilege

Release and operations

• No npm publication was performed from a workstation or from this PR
• Required npm patch bumps are included or intentionally deferred by the
  controlling program
• Image/SBOM/provenance/deployment/rollback impact is documented (none)
• Documentation, changelog, migration, and operational guidance are current

Decision

Public surfaces are retained and wired. Hosted CI is green on this merge head. Keep as draft for maintainer re-review (prior CHANGES_REQUESTED still stands). Do not merge.

  

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[ty-everett]

Maintainer review: retain this as draft and redesign it compatibly. WERR_NETWORK_CHAIN is exported through the public sdk namespace and SDK subpath; removing it breaks consumer imports, instanceof checks and typed JSON round trips. ProcessSyncChunkResult.error is also a public declaration. Internal non-use and the artifact checker’s selected export list do not establish absence of external consumers. Keep/deprecate these surfaces, retain round-trip coverage, and address #541 with an explicit live-sync chain preflight and #542 with documented, tested custom-provider failure handling. Do not close those issues through an API deletion in this maintenance release. A deliberate removal would need an approved major-version migration. Current main has also advanced substantially, so final acceptance must be rerun after the compatible revision.

[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