StorageIdb: align filter/update semantics with Knex canon

[shruggr]

Context

Surfaced during a sync-failure investigation in yours-wallet. A user's IndexedDB held multiple accounts; Account B's output_tags_map rows leaked into Account A's outbound sync chunk and then exploded on the receiving storage (an mss1 wallet server in the 1sat-sdk monorepo) with "Result must be unique." The direct cause was a dead-code user-scope filter in StorageIdb.filterOutputTagMaps; auditing that surfaced five related divergences from the StorageKnex canon, fixed in this PR.

Full divergence audit (what matched, what drifted, severity) lives in 1sat-sdk/docs/plans/2026-04-21-storage-provider-divergences.md — happy to copy here on request.

Changes (all in src/storage/StorageIdb.ts)

1. filterOutputTagMaps user-scope filter — CRIT

The guard was if (userId !== undefined && r.txid) but TableOutputTagMap has no txid column — the check was always false and the scope filter never ran. getOutputTagMapsForUser returned rows across all users in the DB. Drop the bogus r.txid and run the sub-count against output_tags unconditionally when userId is provided. Matches Knex's WHERE EXISTS (SELECT * FROM output_tags WHERE ...) behavior.

2. filterOutputs / filterTransactions empty-array txStatus / status poisoning — HIGH

filterOutputs applied the tx-status sub-count on args.txStatus !== undefined; filterTransactions:1855 used if (args.status && !args.status.includes(...)). Since [] is truthy, an empty array caused every row to be rejected on Idb while Knex treats empty array as a no-op. Added .length > 0 guards matching Knex/StorageBunSqlite.

3. Undefined-partial silent over-match — HIGH

Knex throws Undefined binding(s) detected when a partial filter has undefined values. StorageIdb silently skipped undefined keys via per-key truthiness guards, producing unintended over-matches — especially painful in sync's EntityOutputTagMap.mergeFind path where an unmapped idMap entry quietly propagates undefined down to findOutputTagMaps({partial: {outputId: undefined, outputTagId: undefined}}) and then verifyOneOrNone throws a misleading "Result must be unique." New private assertNoUndefinedInPartial called at the top of every filter* method reproduces Knex's loud failure.

4. Truthiness guards on integer-ID / string partial fields — MED

Sweep-replaced if (args.partial.X && r.X !== args.partial.X) → if (args.partial.X !== undefined && r.X !== args.partial.X) across all filter methods (~106 replacements covering IDs, strings, date fields). Fixes silent filter skips for lockTime === 0, version === 0, empty-string description/derivationPrefix/customInstructions, etc. Fields that were already !== undefined (isDeleted, satoshis, booleans) were left alone.

5. updateIdb return count — MED

Was unconditionally return 1 even for batch updates across an array of ids. Now tracks and returns the real updated count. (updateIdbKey is single-record by composite key; its return 1 is correct and unchanged.)

6. filterProvenTxReqs user-scope r.txid guard — LOW

Same shape as finding 1. TableProvenTxReq.txid is NOT NULL in the Knex canon schema, so && r.txid is almost always truthy in practice — but IDB has no schema enforcement, and a row with empty/undefined txid would silently bypass user scoping. Knex's WHERE EXISTS (... JOIN ON txid) would exclude such rows; Idb was including them. Drop the guard.

What this does not touch

• purgeDataIdb parity vs methods/purgeData.ts — not audited in depth, flagged for follow-up.

Rebase + packaging

Rebased onto origin/master (2.1.21). Package name + version bumped to @bopen-io/wallet-toolbox@2.1.21-parity-fix.0 (and the mirrored @bopen-io/wallet-toolbox-mobile@2.1.21-parity-fix.0) for immediate publication via the @bopen-io npm org. If this PR merges, a separate commit would revert the rename for @bsv publication.

Validation

• npm run build — clean on 2.1.21 + my changes.
• npm test -- --testPathPattern="OutputTagMapTests|TxLabelMapTests|OutputTagTests|TxLabelTests|TransactionTests|OutputTests" — 61/61 passing.
• One unrelated test failure in ChaintracksStorageIdb.test.ts (WoC file-hash mismatch, network-dependent, fails on master too).

Test plan for merge

• Unit test for getOutputTagMapsForUser with a multi-user IDB returns only the requested user's maps.
• Unit test that findOutputTagMaps({partial: {outputId: undefined}}) throws WERR_INVALID_PARAMETER.
• Unit test that findTransactions({status: []}) returns rows instead of nothing.
• Unit test that findTransactions({partial: {lockTime: 0}}) filters correctly.
• Unit test that updateIdb returns actual affected-row count on a batch update.
• Integration test: build a sync chunk from a multi-account IDB; confirm only the scoped user's tag maps are included.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud