fix(sdk): preserve empty metadata in existing wallet histories

[ty-everett]

Program and scope

• Tracker: BotBoard #590.
• Fix: listActions from existing Knex, IndexedDB and native SQLite wallets can contain empty descriptions on generated change and empty basket names on unassigned outputs. Hardened SDK result validation rejects the whole history. This patch preserves those stored strings instead of inventing metadata or requiring wallet-data rewrites.
• Scope: result display metadata only, regression/conformance evidence, and SDK 2.8.4 patch metadata. No changes to transaction creation, authorization, signatures, persistence, wire encoding, dependencies, service images or Wallet interoperability and reliability: bounded sync, proof recovery and BRC-118 payments #569.
• Exact reviewed head: cfd573e77 (full SHA on this PR).

Impact

• Public package source or manifest changed: @bsv/sdk 2.8.4 candidate.
• Security-sensitive result boundary and documentation changed.
• Public declaration shapes, exports, runtime targets and wire bytes remain compatible. Only the empty historical-description sentinel is additionally accepted; nonempty descriptions still require 5–2,000 UTF-8 bytes. Basket names retain their 300-byte ceiling. Required scripts/labels, plain own-data shapes, counts, signed net amounts, and nonnegative individual values remain checked. New-action descriptions and requested basket names remain nonempty.

Verification

• pnpm health:check, pnpm lint, pnpm format:check, pnpm typecheck, pnpm audit:security, pnpm build: pass; audit reports no known vulnerabilities.
• SDK Jest plus coverage: 210 suites / 7,407 tests pass. Overall coverage: statements 94.28%, branches 87.87%, functions 96.03%, lines 95.42%. Result validator: 96.74% lines, 100% functions. Fourteen focused regressions cover direct/HTTP JSON/binary clients, empty metadata preservation, UTF-8 limits, malformed/missing values, unchanged new-action requirements, scripts, labels and monetary bounds. The focused suite failed against the previous implementation and passes with this fix.
• Shared TS conformance: 6,491 pass / 211 unchanged governed skips. Added required historical metadata vector through direct and binary wallet clients; structural corpus validation passes.
• pnpm --filter @bsv/sdk pack:check and test:browser: pass. Exact tarball ESM/CJS, export and type-resolution checks pass. Browser raw sizes: Vite 1,093,280; esbuild 836,098; UMD 827,825 bytes, within unchanged governed limits.
• pnpm --filter @bsv/wallet-toolbox-mobile test:mobile: pass. Metro raw 2,360,501; Hermes raw 4,609,827 bytes, within unchanged limits.
• pnpm docs:build (129 HTML pages) and pnpm docs:examples (8 examples / 21 tarballs): pass.
• Additional synthetic cross-version wire checks preserve exact previously valid bytes for SDK 2.4.0, 2.5.0 and 2.7.1 in both directions. Known hardened 2.8.x processor rejections are recorded as regressions, not compatibility passes. Existing older applications do not need to change BRC100 calls.
• Complete diff self-reviewed for correctness, compatibility, security, package artifacts, documentation and release impact.
• All exact-head hosted checks are terminal and successful: CI 35961279899, including merge-gate; CodeQL 35961279893; conformance 35961279862. Scope-based skips were accepted by the repository gate.

Security and dependencies

• No dependency/lockfile update, quality suppression, override, advisory dismissal or added skip.
• Negative cases retain the surrounding security checks; this change does not relax new-action requests or grant wallet access.
• Exact-head CodeQL passed; the PR merge ref has zero open code-scanning alerts.
• Exact-head Sonar gate independently rechecked: quality OK, zero new findings and zero unreviewed hotspots.

Release and operations

• No npm publication from this workstation or PR. Publication follows reviewed main through the protected SDK-only workflow.
• Patch version, README, changelog, package documentation, migration ledger and generated facts are updated together.
• No account-data/API/wire migration. Affected hardened SDK consumers can update their dependency without rewriting calls; compatible older apps retain their existing contract. No broad service release is required for this history-only correction.
• Existing releases remain immutable. If publication needs correction, use a reviewed forward patch release.

Completion evidence

Final maintainer self-review found no blocking correctness, security, compatibility, artifact or release issue at cfd573e. No review threads are open. CI/security gates passed; protected publication and downstream release acceptance remain separate steps.

[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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[ty-everett]

Maintainer final review of cfd573e77e4d1cf35561dabdb77f293c493cf632: no blocking findings. The change admits the established empty display-metadata sentinel without converting values, expanding nonempty description limits, changing request validation, altering byte encoding, or bypassing script/value/label checks. Regression tests fail before the fix and pass after it; old 2.4.0/2.5.0/2.7.1 client/processor pairings preserve exact wire bytes in both directions. SDK coverage, consumer packaging, browser/mobile builds, conformance and documentation gates passed. Hosted CI 35961279899 is successful including merge-gate; CodeQL 35961279893 passed with no open PR-ref alerts; exact-head Sonar independently reports zero new findings and unreviewed hotspots. There are no review threads. This is the authoring maintainer's review, not an independent approval. Proceeding with the authorized maintainer integration after these gates; protected SDK-only publication remains separate, and #569 is excluded.