Fix shared overlay lookup recovery and failure reporting

[BraydenLangley]

Program and scope

• Tracker: repeated overlay lookup failures in GlobalKVStore and other SDK consumers.
• Program gates advanced: shared lookup recovery, explicit failure reporting, browser persistence and consumer validation.
• Why this change is needed: the previous resolver could exclude a recovered host indefinitely because of persisted cooldown state. First-response discovery and incomplete empty aggregates could then hide available data. Fresh instances and storage resets treated the symptoms.
• Scope: move the fix into the standard LookupResolver, so query, queryDetailed, query$ and queryReliable share recovery, bounded fresh discovery, deadlines, cancellation and scoped advisory reputation for every overlay service. Keep service-specific proof validation and KV write/UI helpers in the optional KV entrypoint.
• Out of scope: publication/deployment, production consumer upgrades, a new authority/currentness protocol, cross-device write uniqueness and a durable pending-write journal.
• Exact head SHA reviewed: 1cd0182f7b941613507bb5855d3fee028039cd4c.

Impact

• Public package source or manifest changed: @bsv/sdk, proposed 3.0.0, plus compatible patch releases for its 31 first-party peer consumers. Exact versions are listed in the generated package migration table.
• Public API, types and browser behavior changed.
• Security-sensitive response and persistence boundaries changed.
• Documentation and examples changed.

query() now throws retryable LookupUnavailableError for incomplete empty results. Detailed and progressive calls expose completion evidence. Every selected host remains eligible during cooldown; discovery is refreshed per operation. Defaults are a 5-second total budget, 2-second host budget, 32 hosts and bounded responses. These default-contract changes require a major release and coordinated consumer adoption. See the migration guide.

Verification

• Local commands: pnpm health:check, pnpm lint, pnpm format:check, pnpm typecheck; SDK coverage/property, packed artifacts and browser recovery; wallet browser/mobile contracts; docs tests/build; conformance and security audit. All passed. Workspace package, browser and dependent test runs also passed; builds were completed before consuming their artifacts.
• Regression coverage reproduces poisoned cooldowns, clock rollback, delayed/retired discovery, empty-plus-healthy peers, hung hosts, cancellation and failure-versus-absence behavior. KV fault injection adds actual BEEF/signature/proof validation, stale tips and index-delayed writes.
• Real Chromium: exact packed UMD, four service names, five outage/recovery cycles, two concurrent tabs and 20 reloads per run; ten consecutive runs passed (200 reloads). Recovery succeeds with old poisoned storage preserved and active v4 penalties; concurrent service updates survive. Repeated runs exposed stale localStorage reads despite Web Locks; the final implementation uses IndexedDB read/write transactions and a 50 ms advisory refresh bound. Independent-reader, same-key concurrency, abort, corrupt-database and unavailable-storage tests cover that boundary.
• SDK: 166 suites / 6,051 tests passed after the transactional persistence and bundle refactor; coverage passed: statements 94.77%, branches 87.23%, functions 95.70%, lines 95.59%. Changed-code coverage is 93.64% (1,252/1,337 points; required 90%) with added public read/write/UI contract tests. Fully covered changed lines measure 91.43% (747/817), using the separate Codecov calculation; malformed state, off-query signed outputs and malformed wire values have negative coverage. Four targeted recurrence mutations were detected; restored suites passed.
• Packed consumers: ESM/CJS/declarations and Vite/esbuild/UMD contracts; unchanged bundle budgets. Metanet Docs and Gloss preview integrations passed 185 and 4 tests respectively, plus their builds, against the locally packed SDK 3 runtime; the latest transactional runtime was extracted into both preview dependency trees before testing.
• Hosted CI: the final-head CI run passed all 60 applicable jobs, with three expected scope-based skips accepted by the merge gate. All mutation targets, functional tests, packed/browser/mobile contracts and aggregate coverage passed. Separate CodeQL, Conformance and Codecov patch checks also pass on this head; Codecov reports 91.43%. The PR remains draft for the author's review.
• Complete diff self-review finished.
• All applicable checks are terminal and successful on the exact head.

Security and dependencies

• Dependency necessity, runtime/peer compatibility and audit results reviewed.
• Negative tests cover changed trust boundaries.
• Final exact-head CodeQL has no new alert.
• Final exact-head repository gate reports zero new Sonar findings and unreviewed hotspots.
• No new advisory dismissal, quality suppression or skipped test.
• Temporary dependency substitution has an owner, evidence, review date and removal condition.
• Workflow permissions and lifecycle-script policy remain unchanged.

Dependency evidence

• Release notes and necessity: fast-uri 3.1.7 and qs 6.16.0 fix newly reported tooling advisories. toml 4.2.0 fixes recursion and prototype pollution; remark-mdx-frontmatter 5.2.0 still requires vulnerable toml 3. The scoped substitution and upstream evidence are recorded in governance/repository-health/exceptions.json.
• Runtime, build, and peer compatibility: qs stays on its compatible 6.x API; toml retains parse() and its Node >=20 requirement fits the workspace Node >=24.11 contract. Webpack's existing optional TOML peer permits 4.x. SDK tests use existing workspace puppeteer-core 25.4.0 and fake-indexeddb 6.2.5 versions as development dependencies. The latter tests transactional persistence without entering runtime bundles.
• Deduplicated lockfile: frozen pnpm 10.33.2 installation passes. One fast-uri 3.1.7, qs 6.16.0 and toml 4.2.0 version remains in the workspace graph. The final transaction-test dependency adds only the existing fake-indexeddb importer; no additional package version or override is introduced.
• Audit and CodeQL: audit passes with only the two existing patched/governed image-size exclusions; no new exclusion. Exact-head CodeQL and the Sonar zero-finding gate pass, with zero open PR alerts and no unresolved review conversations.
• Package and consumer tests: 6,051 SDK tests, real Chromium recovery, packed imports, MDX TOML/YAML/security regressions and the full docs build pass. Final SDK tarball: Metanet Docs 185 tests plus build; Gloss 4 tests plus build.
• Bundle and performance impact (Node 24.20, unchanged limits): SDK Vite 740,568 bytes, esbuild 559,132 bytes and UMD 554,165 bytes. Wallet browser Vite is 1,668,572 bytes / 391,148 gzip / 306,957 Brotli; mobile Metro is 1,716,703 bytes / 432,641 gzip / 335,703 Brotli and Hermes is 3,486,212 bytes / 1,413,552 gzip / 1,095,974 Brotli. Development-only browser/storage fixtures do not enter runtime bundles. Fake-clock recovery/deadline measurements are in the validation report.
• Affected public package versions: SDK 3.0.0 for changed default lookup contracts; 31 first-party peer consumers receive patch versions accepting SDK 3 alongside their existing SDK 2 range. The discovery-services candidate also rejects invalid punycode consistently across Node/ICU versions; its 100 tests and advertisement mutation profile (86.83%) pass on Node 24.20. Other peer-consumer runtime source is unchanged. Tooling parser fixes do not affect SDK runtime dependencies.

Release and operations

• No npm publication or deployment performed.
• SDK major version, release notes and migration guidance included.
• Documentation and rollback guidance updated; no image/deployment configuration changed.
• Production consumer pins and compatibility adapters are preserved; first-party peer ranges and candidate package versions are coordinated.

Completion evidence

• Review conversations are resolved; the CodeQL test-fixture alert is fixed.
• All final-head hosted checks are complete.
• Claims distinguish reproduced lookup recovery from service-specific authority and durability guarantees.
• One qualified maintainer approval is sufficient under repository policy.

Review entry points: design, validation, the shared resolver regressions, and KV contract tests. The PR remains draft for the author’s review.

[codecov]

Codecov Report

❌ Patch coverage is 91.43207% with 70 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/sdk/src/kvstore/ReliableKVStore.ts	86.59%	13 Missing and 13 partials ⚠️
packages/sdk/src/kvstore/ReliableGlobalKVStore.ts	90.99%	4 Missing and 6 partials ⚠️
packages/sdk/src/overlay-tools/LookupResolver.ts	94.59%	3 Missing and 7 partials ⚠️
packages/sdk/src/overlay-tools/ReliableLookup.ts	89.23%	1 Missing and 6 partials ⚠️
.../sdk/src/overlay-tools/ReliableTopicBroadcaster.ts	86.27%	3 Missing and 4 partials ⚠️
...kages/sdk/src/overlay-tools/boundLookupResponse.ts	89.65%	1 Missing and 2 partials ⚠️
packages/sdk/src/kvstore/withKVWriteLock.ts	89.47%	0 Missing and 2 partials ⚠️
...es/sdk/src/overlay-tools/ReliableHostReputation.ts	97.10%	1 Missing and 1 partial ⚠️
packages/sdk/src/kvstore/GlobalKVStore.ts	75.00%	1 Missing ⚠️
packages/sdk/src/kvstore/KVStoreReadSession.ts	97.36%	1 Missing ⚠️
... and 1 more

📢 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