@loopover/engine 1.0.0

package/dist/calibration-dashboard.js

@@ -0,0 +1,65 @@
+import { DOCUMENTED_CALIBRATION_BASELINE, } from "./phase7-calibration-loop.js";
+/** A whole-number percentage, or an em dash when there is no signal yet. */
+function formatPercent(value) {
+    return value === null ? "—" : `${Math.round(value * 100)}%`;
+}
+/** A signed percentage-point delta (e.g. "+6pts" / "-4pts"), or an em dash when unknown. */
+function formatDeltaPoints(value) {
+    if (value === null)
+        return "—";
+    const points = Math.round(value * 100);
+    return `${points >= 0 ? "+" : ""}${points}pts`;
+}
+function sourceRow(label, metric) {
+    return {
+        label,
+        value: formatPercent(metric.accuracy),
+        detail: `n=${metric.sampleSize} · ${metric.fresh ? "fresh" : "stale"}`,
+    };
+}
+/** Classify the overall calibration state for the dashboard's headline banner. */
+export function resolveCalibrationDashboardStatus(result) {
+    if (!result.enabled)
+        return "disabled";
+    if (result.combinedAccuracy === null)
+        return "insufficient_signal";
+    return result.combinedAccuracy >= result.baselineAccuracy ? "on_track" : "below_baseline";
+}
+/**
+ * Project a computed {@link Phase7CalibrationLoopResult} into a read-only dashboard view. Pure and deterministic;
+ * adds no computation of its own. `holdReasons` are surfaced verbatim so an operator can see why an autonomy
+ * increase is (or isn't) permitted.
+ */
+export function buildCalibrationDashboardView(result) {
+    const status = resolveCalibrationDashboardStatus(result);
+    const rows = [
+        {
+            label: "Combined accuracy",
+            value: formatPercent(result.combinedAccuracy),
+            detail: `baseline ${formatPercent(result.baselineAccuracy)}`,
+        },
+        {
+            label: "Delta from baseline",
+            value: formatDeltaPoints(result.deltaFromBaseline),
+            detail: `documented baseline ${formatPercent(DOCUMENTED_CALIBRATION_BASELINE)}`,
+        },
+        sourceRow("Historical replay", result.bySource.historical_replay),
+        sourceRow("PR outcome", result.bySource.pr_outcome),
+        {
+            label: "Replay harness",
+            value: result.replayHarnessStatus,
+            detail: result.replayHarnessHold ? "hold" : "ok",
+        },
+        {
+            label: "Autonomy increase",
+            value: result.autonomyIncreasePermitted ? "permitted" : "held",
+            detail: result.replayRunDue ? "replay run due" : "up to date",
+        },
+    ];
+    const headline = status === "disabled"
+        ? "Calibration loop disabled"
+        : status === "insufficient_signal"
+            ? "Insufficient signal to score calibration yet"
+            : `${formatPercent(result.combinedAccuracy)} combined (${formatDeltaPoints(result.deltaFromBaseline)} vs baseline)`;
+    return { status, headline, rows, holdReasons: [...result.holdReasons] };
+}

package/dist/calibration-trend.d.ts

@@ -0,0 +1,40 @@
+import { type Phase7CalibrationLoopResult } from "./phase7-calibration-loop.js";
+/** One accumulated point in the calibration history: when it was computed and its combined accuracy. */
+export type CalibrationTrendSnapshot = {
+    observedAt: string;
+    combinedAccuracy: number | null;
+    baselineAccuracy: number;
+};
+export type CalibrationTrendDirection = "improving" | "degrading" | "flat" | "insufficient";
+/** One rendered point on the trend line: a data-bearing snapshot with its delta vs the baseline. */
+export type CalibrationTrendPoint = {
+    observedAt: string;
+    combinedAccuracy: number;
+    /** Whole percentage-point delta vs that snapshot's baseline (e.g. +6 / -4). */
+    deltaFromBaseline: number;
+    aboveBaseline: boolean;
+};
+/** The read-only trend projection of a calibration-snapshot series. */
+export type CalibrationTrendView = {
+    direction: CalibrationTrendDirection;
+    headline: string;
+    /** Unicode sparkline of the data points' combined accuracy, normalized across the window. */
+    sparkline: string;
+    points: readonly CalibrationTrendPoint[];
+    latestAccuracy: number | null;
+    /** Latest minus earliest combined accuracy, in whole percentage points; null with < 2 data points. */
+    changeOverWindow: number | null;
+    /** Snapshots that carry a combined accuracy (an install still warming up contributes none). */
+    sampleCount: number;
+    baselineAccuracy: number;
+};
+/** Derive a trend snapshot from a computed calibration-loop result observed at a given time. */
+export declare function calibrationSnapshotFromResult(result: Phase7CalibrationLoopResult, observedAt: string): CalibrationTrendSnapshot;
+/**
+ * Project an accumulated series of calibration snapshots into a read-only trend view. Pure and
+ * deterministic. Snapshots without a combined accuracy (an install still warming up) are dropped from the
+ * trend line; if fewer than two data points remain, the view reports an explicit "insufficient" state
+ * instead of a misleading flat line. `baselineAccuracy` is taken from the most recent snapshot (or the
+ * documented default when there is no history yet).
+ */
+export declare function buildCalibrationTrendView(snapshots: readonly CalibrationTrendSnapshot[]): CalibrationTrendView;

package/dist/calibration-trend.js

@@ -0,0 +1,60 @@
+import { DOCUMENTED_CALIBRATION_BASELINE } from "./phase7-calibration-loop.js";
+const SPARK_TICKS = "▁▂▃▄▅▆▇█";
+/** Derive a trend snapshot from a computed calibration-loop result observed at a given time. */
+export function calibrationSnapshotFromResult(result, observedAt) {
+    return { observedAt, combinedAccuracy: result.combinedAccuracy, baselineAccuracy: result.baselineAccuracy };
+}
+function percentPoints(value) {
+    return Math.round(value * 100);
+}
+function formatPercent(value) {
+    return `${percentPoints(value)}%`;
+}
+function formatDeltaPoints(points) {
+    return `${points >= 0 ? "+" : ""}${points}pts`;
+}
+/** Map data-point accuracies onto sparkline ticks, normalized across the window's own min..max. */
+function sparkline(values) {
+    if (values.length === 0)
+        return "";
+    const min = Math.min(...values);
+    const span = Math.max(...values) - min;
+    return values
+        .map((v) => SPARK_TICKS[span === 0 ? 0 : Math.round(((v - min) / span) * (SPARK_TICKS.length - 1))])
+        .join("");
+}
+/**
+ * Project an accumulated series of calibration snapshots into a read-only trend view. Pure and
+ * deterministic. Snapshots without a combined accuracy (an install still warming up) are dropped from the
+ * trend line; if fewer than two data points remain, the view reports an explicit "insufficient" state
+ * instead of a misleading flat line. `baselineAccuracy` is taken from the most recent snapshot (or the
+ * documented default when there is no history yet).
+ */
+export function buildCalibrationTrendView(snapshots) {
+    const baselineAccuracy = snapshots.length === 0 ? DOCUMENTED_CALIBRATION_BASELINE : snapshots[snapshots.length - 1].baselineAccuracy;
+    const points = snapshots
+        .filter((s) => s.combinedAccuracy !== null)
+        .map((s) => ({
+        observedAt: s.observedAt,
+        combinedAccuracy: s.combinedAccuracy,
+        deltaFromBaseline: percentPoints(s.combinedAccuracy - s.baselineAccuracy),
+        aboveBaseline: s.combinedAccuracy >= s.baselineAccuracy,
+    }));
+    const sampleCount = points.length;
+    const spark = sparkline(points.map((p) => p.combinedAccuracy));
+    const latestAccuracy = sampleCount === 0 ? null : points[sampleCount - 1].combinedAccuracy;
+    if (sampleCount < 2) {
+        const headline = sampleCount === 0
+            ? "No calibration history yet"
+            : `Insufficient history: 1 snapshot (${formatPercent(points[0].combinedAccuracy)})`;
+        return { direction: "insufficient", headline, sparkline: spark, points, latestAccuracy, changeOverWindow: null, sampleCount, baselineAccuracy };
+    }
+    const earliest = points[0].combinedAccuracy;
+    const latest = points[sampleCount - 1].combinedAccuracy;
+    const changeOverWindow = percentPoints(latest - earliest);
+    const direction = changeOverWindow > 0 ? "improving" : changeOverWindow < 0 ? "degrading" : "flat";
+    const headline = direction === "flat"
+        ? `Flat at ${formatPercent(latest)} over ${sampleCount} snapshots`
+        : `${direction === "improving" ? "Improving" : "Degrading"}: ${formatPercent(earliest)} → ${formatPercent(latest)} over ${sampleCount} snapshots (${formatDeltaPoints(changeOverWindow)})`;
+    return { direction, headline, sparkline: spark, points, latestAccuracy, changeOverWindow, sampleCount, baselineAccuracy };
+}

package/dist/contributor-fit.d.ts

@@ -0,0 +1,24 @@
+export type ContributorFit = "strong" | "neutral" | "weak";
+export type ContributorFitCheck = {
+    fit: ContributorFit;
+    reasons: string[];
+};
+export type ContributorFitProfile = {
+    login: string;
+    registeredRepoActivity: {
+        pullRequests: number;
+        mergedPullRequests: number;
+        reposTouched: readonly string[];
+    };
+    trustSignals: {
+        level: "new" | "emerging" | "established";
+        unlinkedOpenPullRequests: number;
+    };
+};
+/**
+ * A profile with no prior activity on the target repo is `neutral` (a first attempt is not evidence
+ * of poor fit). With prior activity, a personal burden signal (unlinked open PRs, or a `new` profile
+ * with a low merge ratio) reads `weak`; established trust with a clean queue and a high merge ratio
+ * reads `strong`; anything between reads `neutral`.
+ */
+export declare function classifyContributorFit(profile: ContributorFitProfile, targetRepoFullName: string): ContributorFitCheck;

package/dist/contributor-fit.js

@@ -0,0 +1,50 @@
+// Contributor fit sub-check (#2312): pure classifier over an already-computed contributor profile
+// that answers whether THIS contributor's own track record fits a target repo. No IO, no fetching.
+/**
+ * A profile with no prior activity on the target repo is `neutral` (a first attempt is not evidence
+ * of poor fit). With prior activity, a personal burden signal (unlinked open PRs, or a `new` profile
+ * with a low merge ratio) reads `weak`; established trust with a clean queue and a high merge ratio
+ * reads `strong`; anything between reads `neutral`.
+ */
+export function classifyContributorFit(profile, targetRepoFullName) {
+    const { reposTouched, pullRequests, mergedPullRequests } = profile.registeredRepoActivity;
+    const target = targetRepoFullName.toLowerCase();
+    if (!reposTouched.some((repo) => repo.toLowerCase() === target)) {
+        return {
+            fit: "neutral",
+            reasons: [`No prior activity on ${targetRepoFullName}; a first attempt is not evidence of poor fit.`],
+        };
+    }
+    const reasons = [];
+    const mergeRatio = pullRequests > 0 ? mergedPullRequests / pullRequests : 1;
+    const unlinked = profile.trustSignals.unlinkedOpenPullRequests;
+    const level = profile.trustSignals.level;
+    const hasUnlinkedBurden = unlinked > 0;
+    const hasNewProfileBurden = level === "new" && pullRequests > 0 && mergeRatio < 0.5;
+    if (hasUnlinkedBurden)
+        reasons.push(`${unlinked} unlinked open pull request(s)`);
+    if (hasNewProfileBurden) {
+        reasons.push(`new profile with low merge ratio (${mergedPullRequests}/${pullRequests})`);
+    }
+    const cleanQueue = unlinked === 0;
+    const strongMerge = pullRequests > 0 && mergeRatio >= 0.8;
+    if (level === "established")
+        reasons.push("trust level is 'established'");
+    if (cleanQueue)
+        reasons.push("no unlinked open pull requests");
+    if (strongMerge)
+        reasons.push(`strong merge ratio (${mergedPullRequests}/${pullRequests})`);
+    const burdened = hasUnlinkedBurden || hasNewProfileBurden;
+    const proven = level === "established" && cleanQueue && strongMerge;
+    let fit;
+    if (burdened) {
+        fit = "weak";
+    }
+    else if (proven) {
+        fit = "strong";
+    }
+    else {
+        fit = "neutral";
+    }
+    return { fit, reasons };
+}

package/dist/discovery-index-contract.d.ts

@@ -0,0 +1,74 @@
+export declare const DISCOVERY_INDEX_CONTRACT_VERSION = 1;
+/** Query scope for a discovery-index request: which repos/orgs/search-terms to fan out over, plus pagination. */
+export type DiscoveryIndexQuery = {
+    /** Canonical `owner/repo` targets. */
+    repos: readonly string[];
+    /** Bare `owner` (org/user) targets — every open issue across the owner's repos. */
+    orgs: readonly string[];
+    /** Free-text GitHub issue-search terms. */
+    searchTerms: readonly string[];
+    /** Page size, clamped to [1, 200]. Default 50. */
+    limit: number;
+    /** Opaque forward pagination cursor from a previous response's `nextCursor`, or null for the first page. */
+    cursor: string | null;
+};
+export type DiscoveryIndexRequest = {
+    contractVersion: number;
+    query: DiscoveryIndexQuery;
+};
+export type DiscoveryIndexAiPolicySource = "AI-USAGE.md" | "CONTRIBUTING.md" | "none";
+/** One metadata-only candidate issue. Field-for-field compatible with opportunity-ranker.js `normalizeCandidate`
+ *  output, so `rankCandidateIssues` consumes hosted results exactly like a local fan-out. Public-safe by contract:
+ *  no scores/rewards/wallet/hotkey/source fields ever appear here (see {@link DISCOVERY_INDEX_FORBIDDEN_FIELDS}). */
+export type DiscoveryIndexCandidate = {
+    owner: string;
+    repo: string;
+    repoFullName: string;
+    issueNumber: number;
+    title: string;
+    labels: readonly string[];
+    commentsCount: number;
+    createdAt: string | null;
+    updatedAt: string | null;
+    htmlUrl: string | null;
+    aiPolicyAllowed: boolean;
+    aiPolicySource: DiscoveryIndexAiPolicySource;
+};
+export type DiscoveryIndexResponse = {
+    contractVersion: number;
+    candidates: readonly DiscoveryIndexCandidate[];
+    /** Forward cursor for the next page, or null when the result set is exhausted. */
+    nextCursor: string | null;
+};
+export type ParsedDiscoveryIndexRequest = {
+    request: DiscoveryIndexRequest;
+    warnings: string[];
+};
+export type ParsedDiscoveryIndexResponse = {
+    response: DiscoveryIndexResponse;
+    warnings: string[];
+};
+/** Field-name fragments that must NEVER cross the public discovery boundary (Phase 1 acceptance:
+ *  cross-repo-discovery-phase1.md:13-14,54). A candidate carrying any of these is rejected, not silently trimmed,
+ *  so a misbehaving server can't smuggle raw economic/identity/source data past the contract. */
+export declare const DISCOVERY_INDEX_FORBIDDEN_FIELDS: readonly string[];
+/** Owner/repo names of forbidden-field violations present on a raw candidate object (own enumerable keys whose
+ *  lower-cased name contains a forbidden fragment). Empty array = public-safe. */
+export declare function discoveryIndexBoundaryViolations(raw: unknown): string[];
+/**
+ * Tolerantly normalize a raw discovery-index request into a canonical {@link DiscoveryIndexRequest}. Never throws:
+ * unknown fields are ignored, malformed scope entries are skipped, and the page limit is clamped, accumulating
+ * warnings. A non-object raw yields an empty query.
+ */
+export declare function normalizeDiscoveryIndexRequest(raw: unknown): ParsedDiscoveryIndexRequest;
+/**
+ * Normalize one raw candidate into a public-safe {@link DiscoveryIndexCandidate}, mirroring opportunity-ranker.js
+ * `normalizeCandidate`. Returns null when required fields are missing/invalid OR when the raw object carries any
+ * forbidden boundary field (a public-safety rejection, not a silent trim).
+ */
+export declare function normalizeDiscoveryIndexCandidate(raw: unknown): DiscoveryIndexCandidate | null;
+/**
+ * Tolerantly normalize a raw discovery-index response: keep only valid, public-safe candidates (invalid or
+ * boundary-violating entries are dropped with a warning), and carry a forward cursor. Never throws.
+ */
+export declare function normalizeDiscoveryIndexResponse(raw: unknown): ParsedDiscoveryIndexResponse;

package/dist/discovery-index-contract.js

@@ -0,0 +1,184 @@
+// Discovery-index API contract (#4300). The typed request/response shape a miner uses to query the OPTIONAL hosted
+// discovery-index service (the server side is #4250, maintainer-only, explicitly blocked on this contract). The
+// plane exists to mitigate the rate-limit incident (#1936): one shared GitHub-metadata crawler across the fleet
+// instead of every miner independently hammering the same repos' search/listing endpoints.
+//
+// This module is schema/shape ONLY — no server, no deployed endpoint, no client HTTP. It stays inside the Phase 1
+// boundary (packages/gittensory-miner/docs/cross-repo-discovery-phase1.md): metadata-only, GET/list/search-only,
+// and NO raw scores / rewards / wallet / hotkey data / source contents crossing the public boundary. The response
+// candidate shape deliberately maps onto opportunity-ranker.js's `normalizeCandidate` fields so a miner can swap a
+// local fan-out for a hosted query without the ranker changing. Tolerant-parser convention, mirroring
+// miner-goal-spec.ts / fleet-run-manifest.ts: every field optional, malformed input degrades to a documented
+// default with a warning rather than throwing.
+export const DISCOVERY_INDEX_CONTRACT_VERSION = 1;
+const MAX_QUERY_ITEMS = 200;
+const MAX_PAGE_LIMIT = 200;
+const DEFAULT_PAGE_LIMIT = 50;
+/** Field-name fragments that must NEVER cross the public discovery boundary (Phase 1 acceptance:
+ *  cross-repo-discovery-phase1.md:13-14,54). A candidate carrying any of these is rejected, not silently trimmed,
+ *  so a misbehaving server can't smuggle raw economic/identity/source data past the contract. */
+export const DISCOVERY_INDEX_FORBIDDEN_FIELDS = Object.freeze([
+    "score",
+    "reward",
+    "wallet",
+    "hotkey",
+    "coldkey",
+    "mnemonic",
+    "payout",
+    "ranking",
+    "rawtrust",
+    "trustscore",
+    "sourcecontent",
+    "diff",
+    "patch",
+]);
+/** Owner/repo names of forbidden-field violations present on a raw candidate object (own enumerable keys whose
+ *  lower-cased name contains a forbidden fragment). Empty array = public-safe. */
+export function discoveryIndexBoundaryViolations(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return [];
+    const violations = [];
+    for (const key of Object.keys(raw)) {
+        const lower = key.toLowerCase();
+        if (DISCOVERY_INDEX_FORBIDDEN_FIELDS.some((fragment) => lower.includes(fragment)))
+            violations.push(key);
+    }
+    return violations;
+}
+function normalizeStringList(value, transform) {
+    if (!Array.isArray(value))
+        return [];
+    const result = [];
+    const seen = new Set();
+    for (const entry of value) {
+        if (typeof entry !== "string")
+            continue;
+        if (result.length >= MAX_QUERY_ITEMS)
+            break;
+        const normalized = transform(entry);
+        if (normalized === null || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        result.push(normalized);
+    }
+    return result;
+}
+/** `owner/repo` with exactly one slash and non-empty halves; anything else → null (mirrors normalizeCandidate). */
+function normalizeRepoFullName(value) {
+    const [owner, repo, extra] = value.trim().split("/");
+    if (!owner || !repo || extra !== undefined)
+        return null;
+    return `${owner}/${repo}`;
+}
+function normalizeOwner(value) {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.includes("/"))
+        return null;
+    return trimmed;
+}
+function normalizeSearchTerm(value) {
+    const trimmed = value.trim();
+    return trimmed || null;
+}
+function clampLimit(value, warnings) {
+    if (value === undefined || value === null)
+        return DEFAULT_PAGE_LIMIT;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        warnings.push(`DiscoveryIndexRequest "limit" must be a number; falling back to ${DEFAULT_PAGE_LIMIT}.`);
+        return DEFAULT_PAGE_LIMIT;
+    }
+    const floored = Math.floor(value);
+    if (floored < 1)
+        return 1;
+    if (floored > MAX_PAGE_LIMIT)
+        return MAX_PAGE_LIMIT;
+    return floored;
+}
+function normalizeAiPolicySource(value) {
+    return value === "AI-USAGE.md" || value === "CONTRIBUTING.md" ? value : "none";
+}
+/**
+ * Tolerantly normalize a raw discovery-index request into a canonical {@link DiscoveryIndexRequest}. Never throws:
+ * unknown fields are ignored, malformed scope entries are skipped, and the page limit is clamped, accumulating
+ * warnings. A non-object raw yields an empty query.
+ */
+export function normalizeDiscoveryIndexRequest(raw) {
+    const warnings = [];
+    const record = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : null;
+    if (!record) {
+        warnings.push("DiscoveryIndexRequest must be a mapping; falling back to an empty query.");
+    }
+    const source = record ?? {};
+    const query = {
+        repos: normalizeStringList(source.repos, normalizeRepoFullName),
+        orgs: normalizeStringList(source.orgs, normalizeOwner),
+        searchTerms: normalizeStringList(source.searchTerms, normalizeSearchTerm),
+        limit: clampLimit(source.limit, warnings),
+        cursor: typeof source.cursor === "string" && source.cursor.trim() ? source.cursor : null,
+    };
+    return { request: { contractVersion: DISCOVERY_INDEX_CONTRACT_VERSION, query }, warnings };
+}
+/**
+ * Normalize one raw candidate into a public-safe {@link DiscoveryIndexCandidate}, mirroring opportunity-ranker.js
+ * `normalizeCandidate`. Returns null when required fields are missing/invalid OR when the raw object carries any
+ * forbidden boundary field (a public-safety rejection, not a silent trim).
+ */
+export function normalizeDiscoveryIndexCandidate(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    if (discoveryIndexBoundaryViolations(raw).length > 0)
+        return null;
+    const candidate = raw;
+    const repoFullName = typeof candidate.repoFullName === "string" ? candidate.repoFullName : "";
+    const canonical = normalizeRepoFullName(repoFullName);
+    const issueNumber = candidate.issueNumber;
+    const title = typeof candidate.title === "string" ? candidate.title.trim() : "";
+    if (canonical === null)
+        return null;
+    if (typeof issueNumber !== "number" || !Number.isInteger(issueNumber) || issueNumber <= 0 || !title)
+        return null;
+    // `canonical` is guaranteed `owner/repo` with exactly one slash, so slice yields two non-empty strings.
+    const slashIndex = canonical.indexOf("/");
+    const owner = canonical.slice(0, slashIndex);
+    const repo = canonical.slice(slashIndex + 1);
+    const labels = Array.isArray(candidate.labels)
+        ? candidate.labels.filter((label) => typeof label === "string" && label.trim() !== "").map((label) => label.trim())
+        : [];
+    return {
+        owner,
+        repo,
+        repoFullName: canonical,
+        issueNumber,
+        title,
+        labels,
+        commentsCount: typeof candidate.commentsCount === "number" && Number.isFinite(candidate.commentsCount) ? candidate.commentsCount : 0,
+        createdAt: typeof candidate.createdAt === "string" ? candidate.createdAt : null,
+        updatedAt: typeof candidate.updatedAt === "string" ? candidate.updatedAt : null,
+        htmlUrl: typeof candidate.htmlUrl === "string" ? candidate.htmlUrl : null,
+        aiPolicyAllowed: candidate.aiPolicyAllowed !== false,
+        aiPolicySource: normalizeAiPolicySource(candidate.aiPolicySource),
+    };
+}
+/**
+ * Tolerantly normalize a raw discovery-index response: keep only valid, public-safe candidates (invalid or
+ * boundary-violating entries are dropped with a warning), and carry a forward cursor. Never throws.
+ */
+export function normalizeDiscoveryIndexResponse(raw) {
+    const warnings = [];
+    const record = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : null;
+    if (!record) {
+        warnings.push("DiscoveryIndexResponse must be a mapping; falling back to an empty candidate list.");
+    }
+    const rawCandidates = record && Array.isArray(record.candidates) ? record.candidates : [];
+    const candidates = [];
+    for (const entry of rawCandidates) {
+        const normalized = normalizeDiscoveryIndexCandidate(entry);
+        if (normalized === null) {
+            warnings.push("DiscoveryIndexResponse dropped an invalid or boundary-violating candidate.");
+            continue;
+        }
+        candidates.push(normalized);
+    }
+    const nextCursor = record && typeof record.nextCursor === "string" && record.nextCursor.trim() ? record.nextCursor : null;
+    return { response: { contractVersion: DISCOVERY_INDEX_CONTRACT_VERSION, candidates, nextCursor }, warnings };
+}

package/dist/discovery-soft-claim.d.ts

@@ -0,0 +1,35 @@
+/** The three local claim-ledger statuses (claim-ledger.js `CLAIM_STATUSES`). */
+export type SoftClaimStatus = "active" | "released" | "expired";
+/** Outbound coordination actions: announce a claim, or announce that a prior claim is released. */
+export type SoftClaimAction = "claim" | "release";
+/** The local claim-ledger record shape (claim-ledger.js `rowToClaim`) this builder reads from. */
+export type SoftClaimRecord = {
+    repoFullName: string;
+    issueNumber: number;
+    claimedAt: string;
+    status: SoftClaimStatus;
+    note?: string | null;
+};
+/** Optional caller context. Reserved for future public-safe, anonymized coordination metadata. */
+export type SoftClaimRequestContext = {
+    instanceId?: string;
+};
+/** The public-safe soft-claim coordination request payload targeting the discovery-index contract. */
+export type SoftClaimRequest = {
+    contractVersion: number;
+    action: SoftClaimAction;
+    repoFullName: string;
+    issueNumber: number;
+    claimedAt: string;
+    note: string | null;
+    instanceId: string | null;
+};
+/** `active` announces a `claim`; `released`/`expired` announce a `release`. */
+export declare function softClaimActionForStatus(status: SoftClaimStatus): SoftClaimAction;
+/**
+ * Build a public-safe soft-claim coordination request from a local claim-ledger record. Pure and network-free.
+ * Returns null when the claim is missing/invalid or carries an unknown status (only the three claim-ledger
+ * statuses map to a request). Only the fixed set of known fields is copied onto the request, so the payload stays
+ * metadata-only by construction.
+ */
+export declare function buildSoftClaimRequest(claim: unknown, _context?: SoftClaimRequestContext): SoftClaimRequest | null;

package/dist/discovery-soft-claim.js

@@ -0,0 +1,50 @@
+import { DISCOVERY_INDEX_CONTRACT_VERSION } from "./discovery-index-contract.js";
+/** `active` announces a `claim`; `released`/`expired` announce a `release`. */
+export function softClaimActionForStatus(status) {
+    return status === "active" ? "claim" : "release";
+}
+/** `owner/repo` with exactly one slash and non-empty halves; anything else → null (mirrors the discovery-index
+ *  contract / claim-ledger repo validation). */
+function normalizeRepoFullName(value) {
+    if (typeof value !== "string")
+        return null;
+    const [owner, repo, extra] = value.trim().split("/");
+    if (!owner || !repo || extra !== undefined)
+        return null;
+    return `${owner}/${repo}`;
+}
+function isSoftClaimStatus(value) {
+    return value === "active" || value === "released" || value === "expired";
+}
+/**
+ * Build a public-safe soft-claim coordination request from a local claim-ledger record. Pure and network-free.
+ * Returns null when the claim is missing/invalid or carries an unknown status (only the three claim-ledger
+ * statuses map to a request). Only the fixed set of known fields is copied onto the request, so the payload stays
+ * metadata-only by construction.
+ */
+export function buildSoftClaimRequest(claim, _context = {}) {
+    if (!claim || typeof claim !== "object" || Array.isArray(claim))
+        return null;
+    const record = claim;
+    const repoFullName = normalizeRepoFullName(record.repoFullName);
+    if (repoFullName === null)
+        return null;
+    const issueNumber = record.issueNumber;
+    if (typeof issueNumber !== "number" || !Number.isInteger(issueNumber) || issueNumber <= 0)
+        return null;
+    if (typeof record.claimedAt !== "string" || record.claimedAt.trim() === "")
+        return null;
+    if (!isSoftClaimStatus(record.status))
+        return null;
+    return {
+        contractVersion: DISCOVERY_INDEX_CONTRACT_VERSION,
+        action: softClaimActionForStatus(record.status),
+        repoFullName,
+        issueNumber,
+        claimedAt: record.claimedAt,
+        // Local claim-ledger notes and caller instance IDs may contain operator prose or private identifiers. The hosted
+        // discovery plane only receives fixed public metadata, so keep both fields empty.
+        note: null,
+        instanceId: null,
+    };
+}

package/dist/duplicate-winner.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Duplicate-winner adjudication (#dup-winner). Flag-gated by GITTENSORY_DUPLICATE_WINNER.
+ *
+ * When several OPEN PRs link the same issue (a duplicate cluster), the legacy behavior gate-blocks +
+ * auto-closes EVERY sibling as a duplicate — no winner survives. With the flag ON, exactly ONE winner is
+ * spared: the earliest claimant. Sparse legacy rows that do not yet have claim timing fail closed so unknown
+ * ordering cannot arbitrarily suppress duplicate evidence. Only the LOSERS are blocked/closed; the winner
+ * still must pass CI / conflict / gate / linked-issue / slop on its OWN merits.
+ *
+ * This module is PURE — no IO, no Date, no random — so the same inputs always yield the same verdict and the
+ * caller can compute the winner ONCE per review run and thread the result boolean consistently into every
+ * surface (advisory finding, close reason, slop, panels), so they agree by construction.
+ *
+ * ELECTION ORDER: compare `linkedIssueClaimedAt`, the time gittensory first observed the PR claiming
+ * the issue. GitHub `pull_request.created_at` is intentionally not an ordering signal here: contributors can
+ * edit an old placeholder PR to add a linked issue later, so creation time would let backdated claims steal
+ * duplicate-winner credit from the PR that actually claimed the issue first. Sparse legacy rows that lack
+ * claim timing keep failing closed so unknown ordering cannot suppress duplicate evidence.
+ *
+ * INVARIANT (the caller MUST honor it): {@link openSiblingNumbers} carries OPEN-only sibling PR numbers. The
+ * existing sources already exclude closed/merged PRs. Once the winner closes (e.g. red CI), it leaves the open
+ * set and the next-earliest OPEN claimant becomes the winner on re-eval — no permanently-orphaned cluster.
+ *
+ * SECOND CONSUMER (#2278): this module is intentionally engine-hosted (not `src/`-only) because its election
+ * logic is reusable for the miner's own soft-claim adjudication — deciding which of several miners claiming
+ * the same issue proceeds. A future contributor wiring the miner's local claim ledger should import this
+ * module rather than reimplementing the election rule, so both the maintainer gate and the miner agree on
+ * exactly one winner by construction.
+ */
+export type DuplicateClaimMember = {
+    number: number;
+    linkedIssueClaimedAt?: string | null | undefined;
+    /** GitHub's true PR creation time. Retained for caller compatibility; not used for winner ordering. */
+    createdAt?: string | null | undefined;
+};
+/**
+ * True iff `prNumber` is the cluster winner: the minimum of `{prNumber} ∪ openSiblingNumbers`. An empty
+ * sibling list ⇒ the PR is alone in (or out of) the cluster ⇒ winner. A sibling list that happens to contain
+ * `prNumber` itself is harmless — the comparison is still min-based.
+ *
+ * @deprecated Use {@link isDuplicateClusterWinnerByClaim}. PR-number election is retained only for legacy
+ * compatibility callers that do not have claim timestamps.
+ */
+export declare function isDuplicateClusterWinner(prNumber: number, openSiblingNumbers: number[]): boolean;
+/**
+ * True iff `pr` is the earliest-elected claimant in the open duplicate cluster (see the module doc's
+ * "ELECTION ORDER" note). Sparse legacy rows fail closed; ties between equally-ordered members use PR number.
+ */
+export declare function isDuplicateClusterWinnerByClaim(pr: DuplicateClaimMember, openSiblings: DuplicateClaimMember[]): boolean;
+/**
+ * The winning PR number among `pr` and its open duplicate siblings, or `null` when the election is not
+ * determinable (mirrors {@link isDuplicateClusterWinnerByClaim}'s fail-closed semantics — this never guesses a
+ * specific winner when the ordering data is too sparse/ambiguous to be sure). Used only for DISPLAY (naming the
+ * winner in a loser's close comment, #dup-winner-credit) — the close/hold decision for any given PR is still
+ * driven directly by {@link isDuplicateClusterWinnerByClaim}, not by this function's return value.
+ */
+export declare function resolveDuplicateClusterWinnerNumber(pr: DuplicateClaimMember, openSiblings: DuplicateClaimMember[]): number | null;