feat: add scorer-kit

[ovitrif]

Context

This PR moves the offline scorer-file tooling previously introduced via synonymdev/ldk-node#79 into the scorer repo as scorer-kit and extends it for local/operator workflows around serialized LDK ChannelLiquidities files.

The tool can inspect scorer binaries, decode them to JSON, compare two snapshots, validate bytes, derive selected-channel allowlists, and write new scorer binaries. It uses the scorer diagnostics/merge/filter API from the stacked rust-lightning PR synonymdev/rust-lightning#3 via an aliased dependency, so the existing scorer node/prober dependency graph remains on its current LDK crate set.

What Changed

• Adds src/bin/scorer-kit.rs with inspect, decode, compare, merge, node-scids, and validate subcommands.
• Adds policy-driven duplicate handling for merge: richer-history, prefer-first, prefer-last, combine, and newer.
• Adds selected-channel overlay support via --overlay-scid / --overlay-scids-file: the first input remains the baseline, later inputs are filtered to explicitly listed short-channel-ids before merge policy is applied.
• Adds node-scids for deriving an overlay SCID allowlist from a serialized LDK NetworkGraph, one or more node pubkeys, and an optional incoming scorer-file intersection.
• Allows node-scids --invoice <bolt11> to recover the target pubkey from an invoice when a direct node pubkey is not already available.
• Adds merge audit reports with duplicate decisions, overlay filter counts, and summary counts.
• Moves tracked decoded JSON scorer snapshots to data/scores/ with sanitized source-z / source-b labels.
• Adds data/scores/merged.bin as the selected overlay scorer candidate, plus merged.decoded.json and merged.report.json.
• Documents common scorer-kit flows in the README.

Current Sample Result

Using the current two source samples, the broad richer-history merge produced a 16,609-entry scorer file. The audit report recorded 1,184 duplicate short-channel-id decisions: 389 kept from the existing input, 795 replaced by the incoming input, and 0 combined.

That broad merge remains useful for analysis, but the safer production-style workflow is now the selected overlay path: start with source-z as the baseline, pass source-b as the incoming overlay, use --policy prefer-last, and provide an explicit SCID allowlist with --overlay-scids-file.

The tracked selected overlay candidate uses a 20-SCID allowlist, reduced the incoming file to 5 score entries before merge, replaced 3 overlapping entries, preserved the rest of the baseline, and added 2 unique incoming entries. The serialized candidate is committed as data/scores/merged.bin, with merged.decoded.json and merged.report.json alongside it.

Notes

Scorer binaries are keyed by short-channel-id and do not contain node pubkeys. Node-level selection therefore needs a serialized LDK network graph, an invoice payee, or another external channel map to produce the SCID allowlist before running scorer-kit merge.

Test Plan

• cargo check --bin scorer-kit
• cargo test --bin scorer-kit (8 scorer-kit unit tests)
• cargo test
• scorer-kit node-scids --help
• scorer-kit validate data/scores/merged.bin
• scorer-kit validate <source-z.bin> <source-b.bin>
• scorer-kit inspect <source-z.bin> --label source-z --top 5
• scorer-kit inspect <source-b.bin> --label source-b --top 5
• scorer-kit compare <source-z.bin> <source-b.bin> --left-label source-z --right-label source-b
• scorer-kit merge <source-z.bin> <source-b.bin> --label source-z --label source-b --output target/scorer-kit/merged.bin --report data/scores/merged-richer-history.report.json --policy richer-history
• scorer-kit merge <source-z.bin> <source-b.bin> --label source-z --label source-b --policy prefer-last --overlay-scid <unique-scid> --output target/scorer-kit/merged-one-overlay.bin --report target/scorer-kit/merged-one-overlay.report.json
• scorer-kit merge <source-z.bin> <source-b.bin> --label source-z --label source-b --policy prefer-last --overlay-scid <overlapping-scid> --output target/scorer-kit/merged-one-overlap.bin --report target/scorer-kit/merged-one-overlap.report.json
• scorer-kit merge <source-z.bin> <source-b.bin> --label source-z --label source-b --policy prefer-last --overlay-scids-file <20-scid-allowlist> --output target/scorer-kit/selected-node.bin --report target/scorer-kit/selected-node.report.json
• sensitive term scan over staged files and PR body