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
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
Context
packages/loopover-miner/docs/discovery-plane-operator-guide.mdtells its reader up front:All three issues are now
CLOSED/shipped, and the modules they describe are real, tested code:packages/loopover-engine/src/discovery-index-contract.ts— exportsDiscoveryIndexQuery,DiscoveryIndexResponse,DiscoveryIndexCandidate,discoveryIndexBoundaryViolations,normalizeDiscoveryIndexRequest,normalizeDiscoveryIndexCandidate,normalizeDiscoveryIndexResponse,DISCOVERY_INDEX_FORBIDDEN_FIELDS,DISCOVERY_INDEX_CONTRACT_VERSION— with its own operator-facing doc atpackages/loopover-miner/docs/discovery-index-contract.md.packages/loopover-engine/src/discovery-soft-claim.ts(feat(miner-discovery-plane): add client-side soft-claim coordination request builder #4302's deliverable).packages/loopover-engine/src/miner-telemetry.ts(feat(miner-discovery-plane): add anonymized telemetry event schema for the optional hosted plane #4301's deliverable).Grepping
discovery-plane-operator-guide.mdfordiscovery-index-contractorDiscoveryIndexreturns zerohits — 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 inpackages/loopover-miner/lib/(confirmed viagrep — 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 stillaccurate for the env var layer — only the contract/telemetry/soft-claim type layer has actually shipped
and deserves an updated cross-reference.
Requirements
discovery-plane-operator-guide.md's "Opt-in mechanism" section (or theplaceholder-scope callout at the top) to
discovery-index-contract.mdand the real shipped module paths,making clear that the request/response shape (
DiscoveryIndexQuery/DiscoveryIndexResponse/DiscoveryIndexCandidate) is now real, tested, and stable atDISCOVERY_INDEX_CONTRACT_VERSION1.preserve the existing caveat that opt-in wiring (
LOOPOVER_MINER_DISCOVERY_PLANEand siblings) remainsunimplemented pending feat(discovery-plane): stand up the hosted discovery-index server #4250, since that part is still true.
landed module instead of only the closed issue), while feat(discovery-plane): stand up the hosted discovery-index server #4250 (still open) stays framed as the actual
blocker for the operator-facing opt-in mechanism.
Deliverables
packages/loopover-miner/docs/discovery-plane-operator-guide.md: cross-reference added todiscovery-index-contract.md/discovery-index-contract.ts,discovery-soft-claim.ts, andminer-telemetry.tsfor the now-shipped contract/telemetry/soft-claim types.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.
LOOPOVER_MINER_DISCOVERY_PLANE,LOOPOVER_MINER_DISCOVERY_INDEX_URL,LOOPOVER_MINER_DISCOVERY_TELEMETRYexist in
packages/loopover-miner/lib/before and after this change — if a future contributor's own repostate 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/**, outsidesrc/**), 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.mdcan find the real, shipped, tested contract typedefinitions this guide is building toward, while still correctly understanding that the operator-facing
opt-in mechanism itself isn't implemented yet.
Links & Resources
packages/loopover-miner/docs/discovery-index-contract.mdandpackages/loopover-engine/src/discovery-index-contract.ts— the real, shipped contract.packages/loopover-engine/src/discovery-soft-claim.ts,packages/loopover-engine/src/miner-telemetry.ts—the other two shipped modules.
should reflect accurately.