Skip to content

feat(miner-discovery-plane): add client-side soft-claim coordination request builder #4302

Description

@JSONbored

Depends on the discovery-index API contract (sibling Phase 6 issue) for its request shape — file both, but the contract should land first or alongside.

packages/gittensory-miner/lib/claim-ledger.js already implements soft-claims, but its header comment is explicit about the boundary this issue extends past: "The database only lives on this machine; this module never uploads, syncs, or phones home" (claim-ledger.js:8-9), and "sibling miners claiming the same issue are resolved elsewhere via isDuplicateClusterWinnerByClaim from @jsonbored/gittensory-engine (#3355)" (claim-ledger.js:81-83) — that adjudication function resolves collisions after the fact, by observing which PR/comment publicly landed first; it has no way to know about another miner's claim before both have already started work. This issue is the piece that closes that gap: a pure, client-side builder that turns a local claim (already recorded via claimIssue/recordClaim in claim-ledger.js) into the request payload a miner would send to the hosted discovery-index (sibling issue) to softly announce/reserve an issue across the fleet before starting, reducing collisions instead of only detecting them afterward.

Scoped as a "request builder," not a network client: this issue produces a typed, pure function that reads the local claim-ledger shape and returns a request payload matching the discovery-index contract — it does not need to perform the actual HTTP call (that's for whichever issue wires the hosted plane's client into the miner runtime, likely downstream of #4250 actually existing).

Deliverables

  • A pure buildSoftClaimRequest(claim, context)-style function (in @jsonbored/gittensory-engine, consistent with the discovery-index contract's location) that maps a local claim record's shape (packages/gittensory-miner/lib/claim-ledger.js's rowToClaim output, :59-68: repoFullName, issueNumber, claimedAt, status, note) onto the discovery-index contract's soft-claim request shape.
  • No network call inside this function — pure input/output, unit-testable without a server.
  • Handle the local ledger's three claim statuses (active, released, expired, claim-ledger.js:12) explicitly — only an active claim should ever produce an outbound "claim" request; released/expired claims should either be rejected by the builder or produce an explicit "release" request variant, whichever the discovery-index contract defines.
  • Unit tests under test/unit/, following test/unit/miner-claim-ledger.test.ts's existing fixtures for claim shapes.

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    gittensor:featureGittensor-scored feature linked to a feature issue — scores a 0.25x multiplier.help wantedExtra attention is needed

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions