Skip to content

docs(miner): discovery-plane-operator-guide.md doesn't reference the now-shipped discovery-index contract #5938

Description

@JSONbored

Context

packages/loopover-miner/docs/discovery-plane-operator-guide.md tells its reader up front:

Placeholder scope: the concrete env var names, HTTP paths, and telemetry event types below are
provisional until the sibling contract/telemetry/client issues land. When those ship, update this file
to match the real symbols — do not treat the TBD names as stable API yet.

Issue What it defines
#4300 Public-data-only discovery-index API contract (request/response shapes)
#4301 Anonymized telemetry event schema for the optional hosted plane
#4302 Client-side soft-claim coordination request builder

All three issues are now CLOSED/shipped, and the modules they describe are real, tested code:

Grepping discovery-plane-operator-guide.md for discovery-index-contract or DiscoveryIndex returns zero
hits — the guide never mentions any of this shipped, real, stable-since-#4300 contract, even though the
guide's own placeholder-scope table explicitly promised to "update this file to match the real symbols" once
#4300 landed. An operator reading this guide today has no way to discover that the request/response shape
is already real, tested, and documented elsewhere — only that "names TBD."

What is still genuinely unshipped, and must not be overclaimed by this fix: the actual opt-in env vars
this guide documents (LOOPOVER_MINER_DISCOVERY_PLANE, LOOPOVER_MINER_DISCOVERY_INDEX_URL,
LOOPOVER_MINER_DISCOVERY_TELEMETRY) do not exist anywhere in packages/loopover-miner/lib/ (confirmed via
grep — zero hits). That wiring is blocked on #4250 (the hosted discovery-index server itself, still OPEN,
maintainer-only), not on #4300/#4301/#4302. So the "names TBD, no client wiring yet" caveat is still
accurate for the env var layer — only the contract/telemetry/soft-claim type layer has actually shipped
and deserves an updated cross-reference.

Requirements

Deliverables

  • packages/loopover-miner/docs/discovery-plane-operator-guide.md: cross-reference added to
    discovery-index-contract.md / discovery-index-contract.ts, discovery-soft-claim.ts, and
    miner-telemetry.ts for the now-shipped contract/telemetry/soft-claim types.
  • Same file: placeholder-scope table updated to distinguish "shipped (contract shape)" from "still
    blocked on feat(discovery-plane): stand up the hosted discovery-index server #4250 (opt-in wiring)" rather than treating all four issues as equally unshipped.
  • No change to the "names TBD" framing for the actual env var names — verify via grep that none of
    LOOPOVER_MINER_DISCOVERY_PLANE, LOOPOVER_MINER_DISCOVERY_INDEX_URL, LOOPOVER_MINER_DISCOVERY_TELEMETRY
    exist in packages/loopover-miner/lib/ before and after this change — if a future contributor's own repo
    state shows they now exist, that's grounds to revisit this doc further, not silently assume so here.

Test Coverage Requirements

Docs-only change (packages/loopover-miner/docs/**, outside src/**), not gated by Codecov patch coverage.
No new automated test is required, but the PR description should show the grep commands used to verify (a)
the shipped module/exports exist and are cited correctly, and (b) the env vars genuinely remain unimplemented
in lib/, so a reviewer can confirm the claims without re-deriving them.

Expected Outcome

An operator reading discovery-plane-operator-guide.md can find the real, shipped, tested contract type
definitions this guide is building toward, while still correctly understanding that the operator-facing
opt-in mechanism itself isn't implemented yet.

Links & Resources

Metadata

Metadata

Assignees

No one assigned

    Labels

    gittensor:bugGittensor-scored bug fix — scores a 0.05x multiplier.help wantedExtra attention is needed

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions