feat(miner-discovery-plane): define the public-data-only discovery-index API contract

[JSONbored]

The server-side counterpart to this is already filed and explicitly blocked on it: #4250 (feat(discovery-plane): stand up the hosted discovery-index server, maintainer-only) lists as its first deliverable "A deployed endpoint implementing the client-side API contract from #2353's Phase 6 discovery-plane items (blocked on that contract being defined first, if not already)." This issue IS that contract. It is scoped to the schema/shape only — request/response types, field names, pagination/versioning conventions — not a server implementation; #4250 owns actually building and hosting the service.

The point of the whole plane (per #4250's own framing) is to mitigate the rate-limit incident already fixed once for the review stack (#1936): one shared GitHub-metadata crawler across the miner fleet instead of every miner instance independently hammering the same repos' search/listing endpoints. The existing client-side, single-instance discovery pipeline is exactly what a hosted version needs to stay compatible with: packages/gittensory-miner/lib/opportunity-fanout.js already does the metadata-only GitHub search/listing fan-out per Phase 1's re-scoped design (packages/gittensory-miner/docs/cross-repo-discovery-phase1.md:9-14 — "Metadata-only... Client-driven... Deterministic... Read-only"), and packages/gittensory-miner/lib/opportunity-ranker.js's normalizeCandidate already defines the exact local candidate shape (repoFullName, issueNumber, title, labels, commentsCount, createdAt, updatedAt, htmlUrl, aiPolicyAllowed, aiPolicySource) that a hosted index's response should either match or cleanly map to/from, so a miner can swap a local fan-out for a hosted query without the ranker needing to change.

Deliverables

• A typed request/response contract (TypeScript types, likely in @jsonbored/gittensory-engine alongside the other shared shapes) for querying the hosted discovery index: request = scope (repos/orgs/search terms), response = a list of metadata-only candidate issues.
• Response shape should map cleanly onto (or directly reuse) the existing normalizeCandidate fields from packages/gittensory-miner/lib/opportunity-ranker.js:16-50, so rankCandidateIssues/rankCandidateIssuesWithSummary can consume hosted results the same way they consume local fan-out results today.
• Explicitly re-state and enforce in the type contract the Phase 1 boundary this plane must not cross: no raw scores/rewards/wallet/hotkey data, no source contents, GET/list-only semantics (cross-repo-discovery-phase1.md:50-55, Acceptance section).
• A short doc (e.g. packages/gittensory-miner/docs/discovery-index-contract.md, mirroring the existing docs/miner-goal-spec.md field-reference style) describing the contract for both sides — this repo's future server implementation (feat(discovery-plane): stand up the hosted discovery-index server #4250) and any third-party consumer.
• No server code, no deployed endpoint, no client HTTP implementation — those are feat(discovery-plane): stand up the hosted discovery-index server #4250 and this Phase's sibling "soft-claim coordination request builder" issue, respectively.

References

• feat(discovery-plane): stand up the hosted discovery-index server #4250 (feat(discovery-plane): stand up the hosted discovery-index server) — the server-side counterpart, explicitly blocked on this contract.
• chore(selfhost): beta-stable release readiness roadmap #1936 — the rate-limit incident this plane is meant to mitigate.
• packages/gittensory-miner/docs/cross-repo-discovery-phase1.md:9-14,50-55 — the metadata-only/client-driven/deterministic/read-only design principles this contract must stay inside.
• packages/gittensory-miner/lib/opportunity-ranker.js:16-50 (normalizeCandidate) — the existing local candidate shape to stay compatible with.
• packages/gittensory-miner/lib/opportunity-fanout.js — the existing client-side fan-out this hosted contract is meant to eventually complement/replace for cross-fleet queries.

[linear-code]

JSO-3287