@loopover/engine 1.0.0

package/dist/governor/rate-limit.d.ts

@@ -0,0 +1,40 @@
+export type LocalRateLimitConfig = {
+    /** Maximum number of events permitted within one window. */
+    limit: number;
+    /** Rolling window length in milliseconds. */
+    windowMs: number;
+};
+export type LocalRateBucket = {
+    /** Events already counted in the current window. */
+    count: number;
+    /** Start of the current window as a millisecond epoch. */
+    windowStartMs: number;
+};
+export type LocalRateLimitDecision = {
+    /** Whether an event at `nowMs` is permitted under the bucket + config. */
+    allowed: boolean;
+    /** The configured limit, echoed for callers that render the decision. */
+    limit: number;
+    /** Events still permitted in the effective window AFTER this one (0 when blocked). */
+    remaining: number;
+    /** When the effective window resets, as a millisecond epoch. */
+    resetAtMs: number;
+    /** Milliseconds to wait before the next permitted attempt (0 when allowed). */
+    retryAfterMs: number;
+};
+/**
+ * Decide whether an event at `nowMs` is allowed for a rolling-window bucket. Pure: it reads the bucket and
+ * clock and returns a decision without mutating anything. A window that has fully elapsed is treated as reset,
+ * so a stale bucket at its limit is permitted again in the new window. Every numeric input is normalized first,
+ * so a non-finite, fractional, or negative count/limit/window can never produce a NaN or negative decision.
+ */
+export declare function evaluateLocalRateLimit(bucket: LocalRateBucket, config: LocalRateLimitConfig, nowMs: number): LocalRateLimitDecision;
+/**
+ * Compute a jittered exponential backoff in milliseconds for a retry `attempt` (0-based). The exponential base
+ * is `baseMs * 2 ** attempt` (attempt clamped to a non-negative, bounded range), scaled by a multiplicative
+ * jitter factor drawn from `randomFn` (expected to return a value in [0, 1), like `Math.random`, but injected
+ * so tests stay deterministic): the factor lands in [0.5, 1.5), and the final delay is that product rounded to
+ * the nearest integer (so at the top of the band a delay may round up to the `1.5 * base` value). The result is
+ * always a non-negative integer.
+ */
+export declare function jitteredBackoffMs(baseMs: number, attempt: number, randomFn: () => number): number;

package/dist/governor/rate-limit.js

@@ -0,0 +1,63 @@
+// Governor local rate-limit + jittered backoff (pure).
+// Deterministic, side-effect-free bucket math for the local Governor. Given a rolling-window bucket and a
+// clock reading it decides whether an event is allowed and, when blocked, how long to wait; and it computes a
+// jittered exponential backoff from an INJECTED random source (never Math.random) so it stays fully unit-
+// testable. This module computes numbers only — it does NOT store state, schedule, or gate any write action;
+// that enforcement wiring is a separate, maintainer-owned concern. The vocabulary mirrors the server-side
+// `RateLimitConfig`/`RateLimitDecision` in src/auth/rate-limit.ts (that one is a Cloudflare Durable Object and
+// is not reusable in the fully-local miner), but this variant is millisecond-based and state-free.
+// Cap the backoff exponent so `2 ** attempt` cannot overflow into Infinity for a pathological attempt count;
+// beyond this the delay is already saturated at its ceiling anyway.
+const MAX_BACKOFF_EXPONENT = 30;
+// Normalize any numeric input to a non-negative integer (a non-finite or negative value becomes 0), so counts,
+// limits, and window lengths can never make a decision NaN, fractional, or negative.
+function finiteNonNegativeInt(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
+/**
+ * Decide whether an event at `nowMs` is allowed for a rolling-window bucket. Pure: it reads the bucket and
+ * clock and returns a decision without mutating anything. A window that has fully elapsed is treated as reset,
+ * so a stale bucket at its limit is permitted again in the new window. Every numeric input is normalized first,
+ * so a non-finite, fractional, or negative count/limit/window can never produce a NaN or negative decision.
+ */
+export function evaluateLocalRateLimit(bucket, config, nowMs) {
+    const limit = finiteNonNegativeInt(config.limit);
+    const windowMs = finiteNonNegativeInt(config.windowMs);
+    const count = finiteNonNegativeInt(bucket.count);
+    const windowStartMs = Number.isFinite(bucket.windowStartMs) ? bucket.windowStartMs : 0;
+    const now = Number.isFinite(nowMs) ? nowMs : 0;
+    const windowElapsed = now - windowStartMs >= windowMs;
+    const effectiveCount = windowElapsed ? 0 : count;
+    const effectiveWindowStart = windowElapsed ? now : windowStartMs;
+    const resetAtMs = effectiveWindowStart + windowMs;
+    const allowed = effectiveCount < limit;
+    const remaining = allowed ? limit - effectiveCount - 1 : 0;
+    const retryAfterMs = allowed ? 0 : Math.max(0, resetAtMs - now);
+    return { allowed, limit, remaining, resetAtMs, retryAfterMs };
+}
+/**
+ * Compute a jittered exponential backoff in milliseconds for a retry `attempt` (0-based). The exponential base
+ * is `baseMs * 2 ** attempt` (attempt clamped to a non-negative, bounded range), scaled by a multiplicative
+ * jitter factor drawn from `randomFn` (expected to return a value in [0, 1), like `Math.random`, but injected
+ * so tests stay deterministic): the factor lands in [0.5, 1.5), and the final delay is that product rounded to
+ * the nearest integer (so at the top of the band a delay may round up to the `1.5 * base` value). The result is
+ * always a non-negative integer.
+ */
+export function jitteredBackoffMs(baseMs, attempt, randomFn) {
+    // Normalize non-finite inputs so the result can never be NaN or Infinity — it is always a non-negative integer,
+    // matching this function's documented contract. A non-finite base is treated as 0; a NaN attempt means no
+    // backoff growth, while a huge or Infinity attempt saturates at the capped exponent.
+    const safeBase = Number.isFinite(baseMs) ? Math.max(0, baseMs) : 0;
+    const exponent = Number.isNaN(attempt) ? 0 : Math.min(MAX_BACKOFF_EXPONENT, Math.max(0, Math.floor(attempt)));
+    const exponential = safeBase * 2 ** exponent;
+    // Clamp the random draw into [0, 1) so an out-of-contract source cannot push the factor outside [0.5, 1.5).
+    // A non-finite draw (e.g. NaN) is treated as 0 so the delay never becomes NaN.
+    const rawDraw = randomFn();
+    const draw = Number.isFinite(rawDraw) ? Math.min(0.999999, Math.max(0, rawDraw)) : 0;
+    const jitterFactor = 0.5 + draw;
+    // Round to an integer AND guard finiteness on the return itself: a fractional base yields a rounded integer,
+    // and an extreme (but finite) base that overflows the multiplication to Infinity falls back to a finite max —
+    // so the result is always a non-negative integer for any input, per the documented contract.
+    const rawDelay = exponential * jitterFactor;
+    return Number.isFinite(rawDelay) ? Math.max(0, Math.round(rawDelay)) : Number.MAX_SAFE_INTEGER;
+}

package/dist/governor/reputation-throttle.d.ts

@@ -0,0 +1,50 @@
+import type { GovernorLedgerEvent } from "../governor-ledger.js";
+export type SelfReputationThresholds = {
+    /** Terminal outcomes required on a repo before throttling engages; below this it fails OPEN (full cadence). */
+    minSampleSize: number;
+    /** Unfavorable ratio (unfavorable / decided) at which cadence starts degrading below full. */
+    throttleAtRatio: number;
+    /** Unfavorable ratio at (or above) which cadence is pinned to its floor. */
+    floorAtRatio: number;
+    /** Cadence multiplier at/above `floorAtRatio` — the slowest permitted fraction of normal cadence (never 0). */
+    minCadenceFactor: number;
+};
+/** Conservative built-in defaults; a `.gittensory-miner.yml` override is merged over these. */
+export declare const DEFAULT_SELF_REPUTATION_THRESHOLDS: SelfReputationThresholds;
+/** The miner's own terminal outcomes on one repo over its recent-history window. */
+export type RepoOutcomeHistory = {
+    /** Submissions with a terminal outcome (merged + closed + rejected). */
+    decided: number;
+    /** Terminal outcomes that went against the miner (human-closed or gate-rejected). */
+    unfavorable: number;
+};
+export type SelfReputationThrottleReason = "insufficient_history" | "clean" | "throttled" | "floored";
+export type SelfReputationThrottleDecision = {
+    /** Multiplier on normal submission cadence, in [minCadenceFactor, 1]. 1 = unthrottled. */
+    cadenceFactor: number;
+    throttled: boolean;
+    /** The unfavorable ratio that drove the decision; null when below the sample floor (fail-open). */
+    unfavorableRatio: number | null;
+    reason: SelfReputationThrottleReason;
+};
+/**
+ * Merge a partial (e.g. `.gittensory-miner.yml`-sourced) threshold config over the conservative defaults,
+ * normalizing every field so a malformed value can never produce a NaN/negative/out-of-range decision. The
+ * throttle band is kept well-formed: `floorAtRatio` is pulled to at least `throttleAtRatio` so the interpolation
+ * span is never negative.
+ */
+export declare function resolveSelfReputationThresholds(overrides?: Partial<SelfReputationThresholds>): SelfReputationThresholds;
+/**
+ * Decide the cadence throttle for one repo from the miner's own recent outcome history. Pure: reads the history
+ * and thresholds and returns a decision without mutating anything. Fails OPEN on genuinely insufficient history
+ * (fewer than `minSampleSize` decided outcomes) — a brand-new miner or a new repo is never falsely throttled.
+ * Between `throttleAtRatio` and `floorAtRatio` the cadence factor interpolates linearly from 1 down to
+ * `minCadenceFactor`, so an improving ratio measurably restores cadence and a worsening one measurably cuts it.
+ */
+export declare function selfReputationThrottle(history: RepoOutcomeHistory, thresholds?: SelfReputationThresholds): SelfReputationThrottleDecision;
+/**
+ * Shape a throttle decision as a governor-ledger event so the chokepoint can record WHY a submission cadence was
+ * scaled, with the outcome ratio that triggered it. An unthrottled decision is an `allowed` event; a throttled
+ * one is a `throttled` event.
+ */
+export declare function selfReputationThrottleLedgerEvent(repoFullName: string, actionClass: string, decision: SelfReputationThrottleDecision): GovernorLedgerEvent;

package/dist/governor/reputation-throttle.js

@@ -0,0 +1,94 @@
+/** Conservative built-in defaults; a `.gittensory-miner.yml` override is merged over these. */
+export const DEFAULT_SELF_REPUTATION_THRESHOLDS = Object.freeze({
+    minSampleSize: 5,
+    throttleAtRatio: 0.5,
+    floorAtRatio: 0.9,
+    minCadenceFactor: 0.1,
+});
+function finiteNonNegativeInt(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
+function clampFraction(value, fallback) {
+    return Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : fallback;
+}
+function round3(value) {
+    return Number(value.toFixed(3));
+}
+/**
+ * Merge a partial (e.g. `.gittensory-miner.yml`-sourced) threshold config over the conservative defaults,
+ * normalizing every field so a malformed value can never produce a NaN/negative/out-of-range decision. The
+ * throttle band is kept well-formed: `floorAtRatio` is pulled to at least `throttleAtRatio` so the interpolation
+ * span is never negative.
+ */
+export function resolveSelfReputationThresholds(overrides = {}) {
+    const d = DEFAULT_SELF_REPUTATION_THRESHOLDS;
+    const minSampleSize = Math.max(1, finiteNonNegativeInt(overrides.minSampleSize ?? d.minSampleSize));
+    const throttleAtRatio = clampFraction(overrides.throttleAtRatio ?? d.throttleAtRatio, d.throttleAtRatio);
+    const floorAtRatio = Math.max(throttleAtRatio, clampFraction(overrides.floorAtRatio ?? d.floorAtRatio, d.floorAtRatio));
+    const minCadenceFactor = clampFraction(overrides.minCadenceFactor ?? d.minCadenceFactor, d.minCadenceFactor);
+    return { minSampleSize, throttleAtRatio, floorAtRatio, minCadenceFactor };
+}
+/**
+ * Decide the cadence throttle for one repo from the miner's own recent outcome history. Pure: reads the history
+ * and thresholds and returns a decision without mutating anything. Fails OPEN on genuinely insufficient history
+ * (fewer than `minSampleSize` decided outcomes) — a brand-new miner or a new repo is never falsely throttled.
+ * Between `throttleAtRatio` and `floorAtRatio` the cadence factor interpolates linearly from 1 down to
+ * `minCadenceFactor`, so an improving ratio measurably restores cadence and a worsening one measurably cuts it.
+ */
+export function selfReputationThrottle(history, thresholds = DEFAULT_SELF_REPUTATION_THRESHOLDS) {
+    const decided = finiteNonNegativeInt(history.decided);
+    const unfavorable = Math.min(decided, finiteNonNegativeInt(history.unfavorable));
+    if (decided < thresholds.minSampleSize) {
+        return {
+            cadenceFactor: 1,
+            throttled: false,
+            unfavorableRatio: null,
+            reason: "insufficient_history",
+        };
+    }
+    const ratio = unfavorable / decided;
+    if (ratio < thresholds.throttleAtRatio) {
+        return {
+            cadenceFactor: 1,
+            throttled: false,
+            unfavorableRatio: round3(ratio),
+            reason: "clean",
+        };
+    }
+    if (ratio >= thresholds.floorAtRatio) {
+        return {
+            cadenceFactor: thresholds.minCadenceFactor,
+            throttled: true,
+            unfavorableRatio: round3(ratio),
+            reason: "floored",
+        };
+    }
+    // throttleAtRatio <= ratio < floorAtRatio ⇒ floorAtRatio > throttleAtRatio, so the span is strictly positive.
+    const t = (ratio - thresholds.throttleAtRatio) /
+        (thresholds.floorAtRatio - thresholds.throttleAtRatio);
+    const cadenceFactor = round3(1 - t * (1 - thresholds.minCadenceFactor));
+    return {
+        cadenceFactor,
+        throttled: true,
+        unfavorableRatio: round3(ratio),
+        reason: "throttled",
+    };
+}
+/**
+ * Shape a throttle decision as a governor-ledger event so the chokepoint can record WHY a submission cadence was
+ * scaled, with the outcome ratio that triggered it. An unthrottled decision is an `allowed` event; a throttled
+ * one is a `throttled` event.
+ */
+export function selfReputationThrottleLedgerEvent(repoFullName, actionClass, decision) {
+    return {
+        eventType: decision.throttled ? "throttled" : "allowed",
+        repoFullName,
+        actionClass,
+        decision: decision.throttled ? "throttle" : "allow",
+        reason: decision.reason,
+        payload: {
+            cadenceFactor: decision.cadenceFactor,
+            unfavorableRatio: decision.unfavorableRatio,
+        },
+    };
+}

package/dist/governor/run-halt.d.ts

@@ -0,0 +1,39 @@
+import type { GovernorLedgerEvent, GovernorLedgerEventType } from "../governor-ledger.js";
+import { classifyPortfolioConvergence, type PortfolioConvergenceInput, type PortfolioConvergenceThresholds } from "../portfolio/non-convergence.js";
+import { evaluateGovernorCaps, type GovernorCapLimits, type GovernorCapReport, type GovernorCapUsage } from "./budget-cap.js";
+/** Issue vocabulary alias for the pure budget/turn/termination cap calculator. */
+export declare const evaluateBudgetCaps: typeof evaluateGovernorCaps;
+export type NonConvergenceSignal = {
+    tripped: boolean;
+    status: ReturnType<typeof classifyPortfolioConvergence>["status"];
+    reasons: string[];
+};
+/** Issue vocabulary wrapper over {@link classifyPortfolioConvergence}. */
+export declare function detectNonConvergence(input: PortfolioConvergenceInput, thresholds?: PortfolioConvergenceThresholds): NonConvergenceSignal;
+export type RunLoopHaltReason = "cleared" | "prior_halt" | "non_convergence" | "budget_exceeded" | "turn_cap_exceeded" | "termination_cap_exceeded";
+export type RunLoopHaltVerdict = {
+    shouldHalt: boolean;
+    canClaimNext: boolean;
+    reason: RunLoopHaltReason;
+    convergence: NonConvergenceSignal;
+    caps: GovernorCapReport;
+    ledgerEventType: GovernorLedgerEventType;
+    ledgerReason: string;
+};
+/**
+ * Consult non-convergence and budget caps at a run-loop iteration boundary. A prior halt sticks until
+ * the caller clears it; otherwise either signal tripping halts the run and blocks further queue claims.
+ */
+export declare function evaluateRunLoopHalt(input: {
+    runHalted: boolean;
+    usage: GovernorCapUsage;
+    limits: GovernorCapLimits;
+    convergence: PortfolioConvergenceInput;
+    convergenceThresholds?: PortfolioConvergenceThresholds;
+}): RunLoopHaltVerdict;
+/** Reset latch after an operator clears a halted run. */
+export declare function clearRunLoopHalt(): {
+    runHalted: false;
+};
+/** Governor-ledger row for a run-loop halt decision (#2347 deliverable). */
+export declare function buildRunLoopHaltGovernorLedgerEvent(repoFullName: string | null | undefined, inFlightIdentifier: string | null | undefined, verdict: RunLoopHaltVerdict): GovernorLedgerEvent;

package/dist/governor/run-halt.js

@@ -0,0 +1,83 @@
+// Governor run-loop halt enforcement (#2347): composes the pure non-convergence detector and the
+// budget/turn/termination cap calculator at every iteration boundary before the portfolio queue claims
+// the next item. Either signal tripping halts the current run; the caller releases in-flight work and
+// blocks further claims until a human clears the halt.
+import { classifyPortfolioConvergence, DEFAULT_PORTFOLIO_CONVERGENCE_THRESHOLDS, } from "../portfolio/non-convergence.js";
+import { evaluateGovernorCaps, } from "./budget-cap.js";
+/** Issue vocabulary alias for the pure budget/turn/termination cap calculator. */
+export const evaluateBudgetCaps = evaluateGovernorCaps;
+/** Issue vocabulary wrapper over {@link classifyPortfolioConvergence}. */
+export function detectNonConvergence(input, thresholds = DEFAULT_PORTFOLIO_CONVERGENCE_THRESHOLDS) {
+    const verdict = classifyPortfolioConvergence(input, thresholds);
+    return {
+        tripped: verdict.status === "non_convergent",
+        status: verdict.status,
+        reasons: verdict.reasons,
+    };
+}
+function haltVerdict(reason, convergence, caps, ledgerEventType, ledgerReason) {
+    return {
+        shouldHalt: true,
+        canClaimNext: false,
+        reason,
+        convergence,
+        caps,
+        ledgerEventType,
+        ledgerReason,
+    };
+}
+/**
+ * Consult non-convergence and budget caps at a run-loop iteration boundary. A prior halt sticks until
+ * the caller clears it; otherwise either signal tripping halts the run and blocks further queue claims.
+ */
+export function evaluateRunLoopHalt(input) {
+    const convergence = detectNonConvergence(input.convergence, input.convergenceThresholds);
+    const caps = evaluateGovernorCaps(input.usage, input.limits);
+    if (input.runHalted) {
+        return haltVerdict("prior_halt", convergence, caps, "denied", "run_already_halted");
+    }
+    if (caps.verdict === "kill_switch") {
+        return haltVerdict("termination_cap_exceeded", convergence, caps, "kill_switch", "termination_cap_exceeded");
+    }
+    if (caps.budget.exceeded) {
+        return haltVerdict("budget_exceeded", convergence, caps, "denied", "budget_cap_exceeded");
+    }
+    if (caps.turns.exceeded) {
+        return haltVerdict("turn_cap_exceeded", convergence, caps, "denied", "turn_cap_exceeded");
+    }
+    if (convergence.tripped) {
+        return haltVerdict("non_convergence", convergence, caps, "denied", "non_convergence_detected");
+    }
+    return {
+        shouldHalt: false,
+        canClaimNext: true,
+        reason: "cleared",
+        convergence,
+        caps,
+        ledgerEventType: "allowed",
+        ledgerReason: "under_limit",
+    };
+}
+/** Reset latch after an operator clears a halted run. */
+export function clearRunLoopHalt() {
+    return { runHalted: false };
+}
+/** Governor-ledger row for a run-loop halt decision (#2347 deliverable). */
+export function buildRunLoopHaltGovernorLedgerEvent(repoFullName, inFlightIdentifier, verdict) {
+    return {
+        eventType: verdict.ledgerEventType,
+        repoFullName,
+        actionClass: "run_loop",
+        decision: verdict.shouldHalt ? "halt" : "continue",
+        reason: verdict.ledgerReason,
+        payload: {
+            haltReason: verdict.reason,
+            convergenceStatus: verdict.convergence.status,
+            convergenceReasons: verdict.convergence.reasons,
+            budgetExceeded: verdict.caps.budget.exceeded,
+            turnsExceeded: verdict.caps.turns.exceeded,
+            terminationExceeded: verdict.caps.termination.exceeded,
+            inFlightIdentifier: inFlightIdentifier ?? null,
+        },
+    };
+}

package/dist/governor/self-plagiarism.d.ts

@@ -0,0 +1,47 @@
+import type { GovernorLedgerEventType } from "../governor-ledger.js";
+/** Conservative default — only very similar diff fingerprints throttle (not hard-coded at call sites). */
+export declare const DEFAULT_SELF_PLAGIARISM_SIMILARITY_THRESHOLD = 0.85;
+export type SelfPlagiarismConfig = {
+    /** Jaccard similarity in [0, 1] at/above which two fingerprints read as near-duplicates. */
+    similarityThreshold: number;
+};
+export declare const DEFAULT_SELF_PLAGIARISM_CONFIG: Readonly<SelfPlagiarismConfig>;
+/** One prior submission from the miner's own history (same actor only — never cross-miner). */
+export type OwnSubmissionRecord = {
+    repoFullName: string;
+    /** Stable diff fingerprint for similarity comparison (caller-normalized token set or hash). */
+    fingerprint: string;
+    /** When the submission was recorded — election ordering signal (ISO-8601). */
+    submittedAt?: string | null | undefined;
+    pullRequestNumber?: number | null | undefined;
+    issueNumber?: number | null | undefined;
+};
+export type SelfPlagiarismCandidate = OwnSubmissionRecord;
+export type SelfPlagiarismVerdict = {
+    allowed: boolean;
+    /** Aligns with governor-ledger vocabulary: `allowed`, `throttled`, or `denied`. */
+    eventType: GovernorLedgerEventType;
+    reason: string;
+    /** Highest-similarity prior that triggered the throttle, when present. */
+    matchedSubmission?: OwnSubmissionRecord;
+    similarity?: number;
+};
+/** Token-set Jaccard similarity — deterministic and dependency-free for diff fingerprint comparison. */
+export declare function fingerprintSimilarity(left: string, right: string): number;
+/**
+ * Compare a prospective PR fingerprint against the miner's own recent submissions. Fail closed when the
+ * candidate fingerprint or election timing is missing/ambiguous. When near-duplicates exist, only the
+ * earliest claimant wins — later submissions are throttled.
+ */
+export declare function selfPlagiarismCheck(candidateFingerprint: SelfPlagiarismCandidate, recentOwnSubmissions: readonly OwnSubmissionRecord[], config?: SelfPlagiarismConfig): SelfPlagiarismVerdict;
+/** Governor-ledger row shape for an open_pr self-plagiarism decision (#2345 deliverable). */
+export declare function buildSelfPlagiarismGovernorLedgerEvent(repoFullName: string, verdict: SelfPlagiarismVerdict): {
+    eventType: GovernorLedgerEventType;
+    repoFullName: string;
+    actionClass: string;
+    decision: string;
+    reason: string;
+    payload: Record<string, unknown>;
+};
+/** Normalize a miner-goal-spec selfPlagiarism block (or bare threshold number) into engine config. */
+export declare function resolveSelfPlagiarismConfig(raw: unknown): SelfPlagiarismConfig;

package/dist/governor/self-plagiarism.js

@@ -0,0 +1,200 @@
+// Self-plagiarism throttle (#2345): pure classifier over a prospective PR's diff fingerprint vs the miner's own
+// recent submission history. Gates nothing on its own — the Governor open_pr chokepoint (#2340) composes this
+// verdict with rate-limit, budget caps, and non-convergence before recording to the governor ledger.
+//
+// ELECTION: reuses {@link isDuplicateClusterWinnerByClaim}'s claim-time / earliest-wins ordering so a
+// near-duplicate cluster has exactly one survivor — sparse or ambiguous timing fails closed (deny), mirroring
+// duplicate-cluster adjudication in src/signals/duplicate-winner.ts.
+//
+// DETECTOR ONLY — no IO, no Date.now(), no randomness. Identical inputs always yield the identical verdict.
+/** Conservative default — only very similar diff fingerprints throttle (not hard-coded at call sites). */
+export const DEFAULT_SELF_PLAGIARISM_SIMILARITY_THRESHOLD = 0.85;
+export const DEFAULT_SELF_PLAGIARISM_CONFIG = Object.freeze({
+    similarityThreshold: DEFAULT_SELF_PLAGIARISM_SIMILARITY_THRESHOLD,
+});
+function normalizeThreshold(value) {
+    if (!Number.isFinite(value))
+        return DEFAULT_SELF_PLAGIARISM_SIMILARITY_THRESHOLD;
+    return Math.min(1, Math.max(0, value));
+}
+function normalizeFingerprint(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim().toLowerCase();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function tokenSet(fingerprint) {
+    return new Set(fingerprint
+        .split(/[\s:,]+/)
+        .map((token) => token.trim())
+        .filter(Boolean));
+}
+/** Token-set Jaccard similarity — deterministic and dependency-free for diff fingerprint comparison. */
+export function fingerprintSimilarity(left, right) {
+    const setLeft = tokenSet(normalizeFingerprint(left) ?? "");
+    const setRight = tokenSet(normalizeFingerprint(right) ?? "");
+    if (setLeft.size === 0 && setRight.size === 0)
+        return 1;
+    if (setLeft.size === 0 || setRight.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const token of setLeft) {
+        if (setRight.has(token))
+            intersection += 1;
+    }
+    const union = setLeft.size + setRight.size - intersection;
+    return intersection / union;
+}
+function submissionTimeMs(value) {
+    if (!value)
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function submissionNumber(record) {
+    return ((typeof record.pullRequestNumber === "number" &&
+        Number.isFinite(record.pullRequestNumber)
+        ? record.pullRequestNumber
+        : null) ??
+        (typeof record.issueNumber === "number" &&
+            Number.isFinite(record.issueNumber)
+            ? record.issueNumber
+            : null) ??
+        0);
+}
+function repoTieBreaker(record) {
+    return record.repoFullName.trim().toLowerCase();
+}
+function submissionPrecedesSibling(candidate, sibling) {
+    const candidateTime = submissionTimeMs(candidate.submittedAt);
+    const siblingTime = submissionTimeMs(sibling.submittedAt);
+    if (siblingTime < candidateTime)
+        return false;
+    if (siblingTime > candidateTime)
+        return true;
+    const candidateNumber = submissionNumber(candidate);
+    const siblingNumber = submissionNumber(sibling);
+    if (siblingNumber < candidateNumber)
+        return false;
+    if (siblingNumber > candidateNumber)
+        return true;
+    const candidateRepo = repoTieBreaker(candidate);
+    const siblingRepo = repoTieBreaker(sibling);
+    if (siblingRepo.length === 0 || candidateRepo.length === 0)
+        return false;
+    return candidateRepo < siblingRepo;
+}
+function isSelfPlagiarismClusterWinner(candidate, nearDuplicates) {
+    return nearDuplicates.every((sibling) => submissionPrecedesSibling(candidate, sibling));
+}
+// Precondition: the caller (selfPlagiarismCheck) already confirmed `candidate` is NOT the outright
+// winner (isSelfPlagiarismClusterWinner returned false) before calling this -- so this only needs to
+// search nearDuplicates for a sibling that wins instead.
+function resolveSelfPlagiarismWinner(candidate, nearDuplicates) {
+    for (const sibling of nearDuplicates) {
+        const rest = nearDuplicates.filter((other) => other !== sibling);
+        if (isSelfPlagiarismClusterWinner(sibling, [candidate, ...rest]))
+            return sibling;
+    }
+    return null;
+}
+function buildVerdict(allowed, eventType, reason, matchedSubmission, similarity) {
+    return {
+        allowed,
+        eventType,
+        reason,
+        ...(matchedSubmission ? { matchedSubmission } : {}),
+        ...(similarity !== undefined ? { similarity } : {}),
+    };
+}
+/**
+ * Compare a prospective PR fingerprint against the miner's own recent submissions. Fail closed when the
+ * candidate fingerprint or election timing is missing/ambiguous. When near-duplicates exist, only the
+ * earliest claimant wins — later submissions are throttled.
+ */
+export function selfPlagiarismCheck(candidateFingerprint, recentOwnSubmissions, config = DEFAULT_SELF_PLAGIARISM_CONFIG) {
+    const threshold = normalizeThreshold(config.similarityThreshold);
+    const candidatePrint = normalizeFingerprint(candidateFingerprint.fingerprint);
+    if (candidatePrint === null) {
+        return buildVerdict(false, "denied", "missing_candidate_fingerprint");
+    }
+    if (submissionTimeMs(candidateFingerprint.submittedAt) === null) {
+        return buildVerdict(false, "denied", "missing_candidate_submitted_at");
+    }
+    let bestMatch;
+    let bestSimilarity = 0;
+    const nearDuplicates = [];
+    for (const prior of recentOwnSubmissions) {
+        const priorPrint = normalizeFingerprint(prior.fingerprint);
+        if (priorPrint === null)
+            continue;
+        const similarity = fingerprintSimilarity(candidatePrint, priorPrint);
+        if (similarity >= threshold) {
+            nearDuplicates.push(prior);
+            if (similarity > bestSimilarity) {
+                bestSimilarity = similarity;
+                bestMatch = prior;
+            }
+        }
+    }
+    if (nearDuplicates.length === 0) {
+        return buildVerdict(true, "allowed", "distinct_from_recent_own_submissions");
+    }
+    for (const prior of nearDuplicates) {
+        if (submissionTimeMs(prior.submittedAt) === null) {
+            return buildVerdict(false, "denied", "missing_prior_submitted_at");
+        }
+    }
+    if (isSelfPlagiarismClusterWinner(candidateFingerprint, nearDuplicates)) {
+        return buildVerdict(true, "allowed", "earliest_near_duplicate_claimant");
+    }
+    const winner = resolveSelfPlagiarismWinner(candidateFingerprint, nearDuplicates);
+    const matched = winner && winner !== candidateFingerprint
+        ? winner
+        : (bestMatch ?? nearDuplicates[0]);
+    const matchedPrint = normalizeFingerprint(matched.fingerprint);
+    return buildVerdict(false, "throttled", "near_duplicate_self_plagiarism", matched, bestSimilarity > 0
+        ? bestSimilarity
+        : fingerprintSimilarity(candidatePrint, matchedPrint));
+}
+/** Governor-ledger row shape for an open_pr self-plagiarism decision (#2345 deliverable). */
+export function buildSelfPlagiarismGovernorLedgerEvent(repoFullName, verdict) {
+    const matched = verdict.matchedSubmission;
+    return {
+        eventType: verdict.eventType,
+        repoFullName,
+        actionClass: "open_pr",
+        decision: verdict.allowed
+            ? "allow"
+            : verdict.eventType === "throttled"
+                ? "throttle"
+                : "deny",
+        reason: verdict.reason,
+        payload: matched
+            ? {
+                matchedRepoFullName: matched.repoFullName,
+                matchedPullRequestNumber: matched.pullRequestNumber ?? null,
+                matchedIssueNumber: matched.issueNumber ?? null,
+                matchedSubmittedAt: matched.submittedAt ?? null,
+                similarity: verdict.similarity ?? null,
+            }
+            : {},
+    };
+}
+/** Normalize a miner-goal-spec selfPlagiarism block (or bare threshold number) into engine config. */
+export function resolveSelfPlagiarismConfig(raw) {
+    if (raw === undefined || raw === null)
+        return { ...DEFAULT_SELF_PLAGIARISM_CONFIG };
+    if (typeof raw === "number") {
+        return { similarityThreshold: normalizeThreshold(raw) };
+    }
+    if (typeof raw === "object" && !Array.isArray(raw)) {
+        const record = raw;
+        return {
+            similarityThreshold: normalizeThreshold(typeof record.similarityThreshold === "number"
+                ? record.similarityThreshold
+                : DEFAULT_SELF_PLAGIARISM_SIMILARITY_THRESHOLD),
+        };
+    }
+    return { ...DEFAULT_SELF_PLAGIARISM_CONFIG };
+}