feat(add,import): resolve --data-set-metadata to existing dataset IDs

[SgtPooki]

Closes #435.

What changed

--data-set-metadata previously had no effect on dataset selection because synapse-sdk's metadataMatches requires exact key/value equality. Migration datasets carry 4 keys (source, space-did, space-name, withIPFSIndexing); a request for source=storacha-migration alone failed to match and the SDK created a new dataset.

Both add and import now resolve --data-set-metadata locally before invoking the upload pipeline:

• Match definition: requested keys are a subset of an existing dataset's metadata.
• Match count vs --copies (default 2):
  • == copies → route to those dataset IDs, drop metadata from the upload request.
  • 0 matches → pass metadata through unchanged (current behavior creates a new dataset).
  • other → error with matched IDs and the expected count.

Resolver runs only when the caller has not pinned --data-set-ids or --provider-ids. Default flows (no --data-set-metadata) are unchanged.

How to verify

pnpm test

Live verification on calibration with migration datasets 13260 + 13261:

filecoin-pin add migration.json --data-set-metadata source=storacha-migration
# → ✓ Matched existing data sets 13260, 13261 via metadata filter
# → piece appended to both, no new dataset created

Negative path:

filecoin-pin add file.json --data-set-metadata source=does-not-exist
# → • No existing data sets matched --data-set-metadata; SDK will create a new data set with the requested metadata

[Copilot]

Pull request overview

Adds local subset-based resolution for --data-set-metadata so add/import can route uploads into existing datasets (instead of creating new ones) when the requested metadata keys are a subset of an existing dataset’s metadata.

Changes:

• Introduces resolveDataSetIdsByMetadata to resolve dataset IDs via local subset matching against the caller’s datasets.
• Updates filecoin-pin add and filecoin-pin import flows to use resolved dataSetIds (and stop forwarding user metadata) when match count equals --copies.
• Adds unit tests for the resolver and updates add/import unit test mocks to support dataset listing.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/core/data-set/resolve-by-metadata.ts	New resolver to subset-match requested metadata to existing live datasets and return IDs / ambiguity.
src/core/data-set/index.ts	Exports the new resolver from the core data-set module.
src/add/add.ts	Adds pre-upload resolution step for --data-set-metadata to dataSetIds when not pinned by IDs.
src/import/import.ts	Same resolution behavior as add, applied to CAR import.
src/test/unit/resolve-by-metadata.test.ts	Adds unit tests for resolver outcomes (no-match/matched/ambiguous).
src/test/unit/add.test.ts	Updates Synapse mock to include getClientAddress and findDataSets for resolver path.
src/test/unit/import.test.ts	Updates Synapse mock to include getClientAddress and findDataSets for resolver path.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[SgtPooki]

self review

[rvagg]

I guess this'll do for a start; I just have issue with the use of "ambiguous" here, both its inapplication and its lossy nature; I'll leave that one with you to ponder though, near enough is good enough for now