@loopover/engine 1.0.0

package/dist/duplicate-winner.js

@@ -0,0 +1,98 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function isDuplicateClusterWinner(prNumber, openSiblingNumbers) {
+    for (const sibling of openSiblingNumbers) {
+        if (sibling < prNumber)
+            return false;
+    }
+    return true;
+}
+/**
+ * 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 function isDuplicateClusterWinnerByClaim(pr, openSiblings) {
+    if (openSiblings.length === 0)
+        return true;
+    for (const sibling of openSiblings) {
+        if (!prPrecedesSibling(pr, sibling))
+            return false;
+    }
+    return true;
+}
+/**
+ * True iff `pr` is ordered at or ahead of `sibling` for cluster-winner purposes. Only the observed linked-issue
+ * claim time participates in the election; `createdAt` is deliberately ignored because an older PR can claim a
+ * linked issue later by editing its body.
+ */
+function prPrecedesSibling(pr, sibling) {
+    const prClaim = claimTimeMs(pr.linkedIssueClaimedAt);
+    if (prClaim === null)
+        return false;
+    const siblingClaim = claimTimeMs(sibling.linkedIssueClaimedAt);
+    if (siblingClaim === null)
+        return false;
+    if (siblingClaim < prClaim)
+        return false;
+    if (siblingClaim === prClaim && sibling.number < pr.number)
+        return false;
+    return true;
+}
+/**
+ * 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 function resolveDuplicateClusterWinnerNumber(pr, openSiblings) {
+    if (isDuplicateClusterWinnerByClaim(pr, openSiblings))
+        return pr.number;
+    for (const sibling of openSiblings) {
+        const rest = openSiblings.filter((other) => other.number !== sibling.number);
+        if (isDuplicateClusterWinnerByClaim(sibling, [pr, ...rest]))
+            return sibling.number;
+    }
+    return null;
+}
+function claimTimeMs(value) {
+    if (!value)
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}

package/dist/feasibility.d.ts

@@ -0,0 +1,27 @@
+export type FeasibilityClaimStatus = "unclaimed" | "claimed" | "solved" | "unknown";
+export type FeasibilityDuplicateClusterRisk = "none" | "low" | "medium" | "high";
+export type FeasibilityIssueStatus = "ready" | "needs_proof" | "hold" | "do_not_use" | "duplicate" | "invalid" | "missing";
+export type FeasibilityGateInput = {
+    /** Whether cached metadata resolved a target issue. Defaults to true when omitted. */
+    found?: boolean | undefined;
+    claimStatus: FeasibilityClaimStatus;
+    duplicateClusterRisk: FeasibilityDuplicateClusterRisk;
+    issueStatus: FeasibilityIssueStatus;
+};
+export type FeasibilityVerdict = "go" | "raise" | "avoid";
+export type FeasibilityGateResult = {
+    verdict: FeasibilityVerdict;
+    avoidReasons: readonly string[];
+    raiseReasons: readonly string[];
+    summary: string;
+};
+/** Pure feasibility verdict from claim, duplicate-cluster, and issue-status signals. */
+export declare function buildFeasibilityVerdict(input: FeasibilityGateInput): FeasibilityGateResult;
+/** Map a pre-start check report into the feasibility composer's input shape (parity helper for tests/callers). */
+export declare function feasibilityInputFromPreStartCheck(report: {
+    found: boolean;
+    claimStatus: FeasibilityClaimStatus;
+    duplicateClusterRisk: FeasibilityDuplicateClusterRisk;
+    issueQualityStatus?: "ready" | "needs_proof" | "hold" | "do_not_use" | undefined;
+    lifecycle?: string | undefined;
+}): FeasibilityGateInput;

package/dist/feasibility.js

@@ -0,0 +1,86 @@
+// Feasibility-gate composer (pure).
+//
+// Metadata-only verdict over the three discriminants the analyze-phase feasibility gate actually branches on:
+// claim status, duplicate-cluster risk, and issue quality/lifecycle status. Composes the same go/raise/avoid
+// decision as the pre-start check's core recommendation logic without pulling in repo records or GitHub caches.
+function collectAvoidReasons(input) {
+    // Collect every avoid trigger independently — never fold with ??/|| so two simultaneous avoid signals both surface.
+    const reasons = [];
+    if (input.claimStatus === "solved")
+        reasons.push("claim_status_solved");
+    if (input.issueStatus === "do_not_use")
+        reasons.push("issue_quality_do_not_use");
+    if (input.issueStatus === "duplicate")
+        reasons.push("issue_lifecycle_duplicate");
+    if (input.issueStatus === "invalid")
+        reasons.push("issue_lifecycle_invalid");
+    if (input.duplicateClusterRisk === "high")
+        reasons.push("duplicate_cluster_high");
+    return reasons;
+}
+function collectRaiseReasons(input, found) {
+    const reasons = [];
+    if (!found)
+        reasons.push("target_not_found");
+    if (input.duplicateClusterRisk === "medium")
+        reasons.push("duplicate_cluster_medium");
+    if (input.claimStatus === "claimed")
+        reasons.push("claim_status_claimed");
+    if (input.issueStatus === "needs_proof" || input.issueStatus === "hold")
+        reasons.push("issue_quality_uncertain");
+    if (input.issueStatus === "missing")
+        reasons.push("issue_missing");
+    return reasons;
+}
+/** Pure feasibility verdict from claim, duplicate-cluster, and issue-status signals. */
+export function buildFeasibilityVerdict(input) {
+    const found = input.found ?? true;
+    const avoidReasons = collectAvoidReasons(input);
+    if (avoidReasons.length > 0) {
+        return {
+            verdict: "avoid",
+            avoidReasons,
+            raiseReasons: [],
+            summary: `Avoid: ${avoidReasons.join(", ")}.`,
+        };
+    }
+    const raiseReasons = collectRaiseReasons(input, found);
+    if (raiseReasons.length > 0) {
+        return {
+            verdict: "raise",
+            avoidReasons: [],
+            raiseReasons,
+            summary: `Raise: ${raiseReasons.join(", ")}.`,
+        };
+    }
+    return {
+        verdict: "go",
+        avoidReasons: [],
+        raiseReasons: [],
+        summary: "Go: no blocking feasibility signal detected.",
+    };
+}
+/** Map a pre-start check report into the feasibility composer's input shape (parity helper for tests/callers). */
+export function feasibilityInputFromPreStartCheck(report) {
+    let issueStatus;
+    if (!report.found)
+        issueStatus = "missing";
+    else if (report.lifecycle === "duplicate")
+        issueStatus = "duplicate";
+    else if (report.lifecycle === "invalid")
+        issueStatus = "invalid";
+    else if (report.issueQualityStatus === "do_not_use")
+        issueStatus = "do_not_use";
+    else if (report.issueQualityStatus === "needs_proof")
+        issueStatus = "needs_proof";
+    else if (report.issueQualityStatus === "hold")
+        issueStatus = "hold";
+    else
+        issueStatus = "ready";
+    return {
+        found: report.found,
+        claimStatus: report.claimStatus,
+        duplicateClusterRisk: report.duplicateClusterRisk,
+        issueStatus,
+    };
+}

package/dist/finding-severity-calibration.d.ts

@@ -0,0 +1,116 @@
+import type { ObjectiveAnchorScore } from "./objective-anchor.js";
+import type { PairwiseCalibrationScore } from "./pairwise-calibration.js";
+export type FindingSeverityTier = "blocker" | "warning" | "advisory" | "nit";
+export type FindingSeverityCalibrationManifest = {
+    miner?: {
+        calibration?: {
+            /** Explicit maintainer opt-in. Default false. */
+            shareStructuredFindingSeverity?: unknown;
+            /** Optional weight for the structured finding-severity signal when composed into a replay score. */
+            structuredFindingSeverityWeight?: unknown;
+        } | null;
+    } | null;
+    calibration?: {
+        /** Back-compat/future-friendly alias, still explicit and default-off. */
+        shareStructuredFindingSeverity?: unknown;
+        structuredFindingSeverityWeight?: unknown;
+    } | null;
+};
+export type FindingSeverityCalibrationConfig = {
+    shareStructuredFindingSeverity: boolean;
+    structuredFindingSeverityWeight: number;
+    warnings: string[];
+};
+export type FindingSeverityTierInput = {
+    tier: FindingSeverityTier | string;
+    /** Total findings the review raised at this tier. */
+    total: number;
+    /** How many of those were subsequently confirmed (true positives). Clamped to `[0, total]`. */
+    confirmed?: number | undefined;
+    /** Optional 0..1 confidence in the confirmation labelling for this tier. */
+    confidence?: number | undefined;
+};
+export type FindingSeverityCalibrationSignalInput = {
+    repoFullName: string;
+    replayRunId: string;
+    reviewRunId: string;
+    optedIn: boolean;
+    observedAt?: string | undefined;
+    tiers: readonly FindingSeverityTierInput[];
+};
+export type FindingSeverityTierSignal = {
+    tier: FindingSeverityTier;
+    total: number;
+    confirmed: number;
+    confirmationRate: number;
+    weight: number;
+    score: number;
+};
+export type FindingSeverityCalibrationSignal = {
+    repoFullName: string;
+    replayRunId: string;
+    reviewRunId: string;
+    observedAt: string | null;
+    tiers: FindingSeverityTierSignal[];
+    score: number;
+};
+export type FindingSeverityCalibrationIngestion = {
+    accepted: FindingSeverityCalibrationSignal[];
+    rejected: Array<{
+        repoFullName: string;
+        replayRunId: string;
+        reviewRunId: string;
+        reason: "not_opted_in" | "empty_tiers" | "invalid_repo" | "invalid_run_id";
+    }>;
+};
+export type FindingSeverityCalibrationWeights = {
+    objectiveAnchor?: number | undefined;
+    pairwiseJudge?: number | undefined;
+    structuredFindingSeverity?: number | undefined;
+};
+export type FindingSeverityCompositeCalibrationScore = {
+    compositeScore: number;
+    objectiveAnchorScore: number;
+    pairwiseJudgeScore: number | null;
+    structuredFindingSeverityScore: number | null;
+    weights: {
+        objectiveAnchor: number;
+        pairwiseJudge: number;
+        structuredFindingSeverity: number;
+    };
+    audit: {
+        contributingRepos: Array<{
+            repoFullName: string;
+            replayRunId: string;
+            reviewRunId: string;
+            observedAt: string | null;
+            score: number;
+            tiers: FindingSeverityTierSignal[];
+        }>;
+        rejected: FindingSeverityCalibrationIngestion["rejected"];
+    };
+};
+/**
+ * Resolve the explicit per-repo opt-in from a parsed `.gittensory.yml`-style object. Default is opted out. The
+ * preferred path is `miner.calibration.shareStructuredFindingSeverity`; `calibration.shareStructuredFindingSeverity`
+ * is accepted as a narrow alias so private-config surfaces can place the field at top level if needed.
+ */
+export declare function resolveFindingSeverityCalibrationConfig(manifest: FindingSeverityCalibrationManifest | Record<string, unknown> | null | undefined): FindingSeverityCalibrationConfig;
+/**
+ * Ingest only currently opted-in structured finding-severity signals. The opt-in check happens at ingestion time, so
+ * a maintainer opt-out immediately prevents additional calibration rows from contributing even if older collected
+ * data exists elsewhere.
+ */
+export declare function ingestFindingSeverityCalibrationSignals(signals: readonly FindingSeverityCalibrationSignalInput[]): FindingSeverityCalibrationIngestion;
+export declare function computeFindingSeverityCompositeCalibrationScore(input: {
+    objectiveAnchor: number | ObjectiveAnchorScore;
+    pairwise: number | PairwiseCalibrationScore | null;
+    findingSeverity: FindingSeverityCalibrationIngestion | readonly FindingSeverityCalibrationSignalInput[];
+    weights?: FindingSeverityCalibrationWeights | undefined;
+}): FindingSeverityCompositeCalibrationScore;
+/**
+ * Render a deterministic, public-safe Markdown report for a structured finding-severity calibration result. The
+ * report is local-run evidence: it includes aggregate scores, normalized weights, opted-in contributors, and rejected
+ * rows, but never accepts or emits raw review text or private scoring fields.
+ */
+export declare function renderFindingSeverityCalibrationAuditMarkdown(result: FindingSeverityCompositeCalibrationScore): string;