@loopover/miner 0.1.0

package/lib/rejection-state-machine.js

@@ -0,0 +1,81 @@
+// Rejection state machine (#4278): the missing detector + classifier that turns a closed-without-merge PR
+// into a rejection-reason bucket and, for the first time, drives `renderRejectionMessage`
+// (rejection-templates.js, which until now had zero callers outside its own test). Pure classification and
+// content only — no GitHub calls, no network, no writes. The caller (a poller) persists the result locally.
+//
+// DESIGN DECISIONS (called out explicitly by #4278):
+//   • "disengaged" is a per-PR OUTCOME, not a per-repo run-state. A rejection is about one PR, so it belongs
+//     with the `manage-poll.js` outcome family (ready / needs-work / open), NOT `run-state.js`'s RUN_STATES
+//     (idle / discovering / planning / preparing). `DISENGAGED_OUTCOME` is defined HERE and left for a poller
+//     to adopt — this module deliberately does NOT mutate manage-poll.js's or run-state.js's enum as a side
+//     effect (the issue explicitly warns against silently expanding another module's vocabulary).
+//   • Zero-signal fallback: with no gate/duplicate signal, a rejection classifies as `maintainer_close_no_reason`
+//     — the courteous, non-assuming bucket — rather than being left unclassified, so a rejection ALWAYS renders
+//     a note.
+//   • This surfaces the PR's terminal fields from a payload the poller already fetches (ci-poller.js's
+//     `fetchHeadSha` GETs the full `/pulls/{n}` body, :155-163, and discards all but `head.sha`) via a pure
+//     extractor — no second API call, and no behavioral change to the existing fetch.
+
+import { renderRejectionMessage } from "./rejection-templates.js";
+
+/** Per-PR terminal outcome for a rejected (closed-without-merge) PR. A poller adds this to its own outcome
+ *  vocabulary alongside ready / needs-work / open. */
+export const DISENGAGED_OUTCOME = "disengaged";
+
+/**
+ * Pull the terminal-outcome fields from a `GET /pulls/{n}` payload the poller already has. Pure — no API call.
+ * Missing/malformed fields normalize to null/false so a partial payload never throws here.
+ * @param {unknown} prPayload
+ * @returns {{ state: string | null, merged: boolean, mergedAt: string | null, closedAt: string | null }}
+ */
+export function extractPrOutcomeFields(prPayload) {
+  const p = prPayload && typeof prPayload === "object" ? prPayload : {};
+  return {
+    state: typeof p.state === "string" ? p.state : null,
+    merged: p.merged === true,
+    mergedAt: typeof p.merged_at === "string" ? p.merged_at : null,
+    closedAt: typeof p.closed_at === "string" ? p.closed_at : null,
+  };
+}
+
+/**
+ * True when a PR is closed WITHOUT a merge — the rejection this state machine acts on. A merged PR (even though
+ * GitHub also marks it `state: "closed"`) is NOT a rejection. Pure.
+ * @param {{ state?: string | null, merged?: boolean }} fields
+ */
+export function isRejectedPr(fields) {
+  const f = fields && typeof fields === "object" ? fields : {};
+  return f.state === "closed" && f.merged !== true;
+}
+
+/**
+ * Classify a detected rejection into one of the rejection-reason buckets from the available signal.
+ * Precedence: an explicit gate close outranks a duplicate signal (the gate is the more specific, actionable
+ * cause). With neither signal, defaults to `maintainer_close_no_reason` (the documented zero-signal fallback).
+ * Pure.
+ * @param {{ gateClosed?: boolean, supersededByDuplicate?: boolean }} [signal]
+ * @returns {"gate_close" | "superseded_by_duplicate" | "maintainer_close_no_reason"}
+ */
+export function classifyRejectionReason(signal = {}) {
+  const s = signal && typeof signal === "object" ? signal : {};
+  if (s.gateClosed === true) return "gate_close";
+  if (s.supersededByDuplicate === true) return "superseded_by_duplicate";
+  return "maintainer_close_no_reason";
+}
+
+/**
+ * The full transition. Given a PR payload, an optional gate/duplicate signal, and the render context
+ * (`{ repoFullName, prNumber }`), decide whether the PR is a rejection and, if so, produce the disengaged
+ * transition: the classified reason and the rendered courtesy note (this is `renderRejectionMessage`'s first
+ * real caller). Returns null when the PR is not a rejection (still open, or merged) — nothing to disengage.
+ * Pure and deterministic; the caller persists `{ outcome, reason, note }` via its local event ledger.
+ * @returns {{ outcome: string, reason: string, note: string,
+ *   fields: ReturnType<typeof extractPrOutcomeFields> } | null}
+ */
+export function resolveRejection(prPayload, signal, context) {
+  const fields = extractPrOutcomeFields(prPayload);
+  if (!isRejectedPr(fields)) return null;
+  const reason = classifyRejectionReason(signal);
+  const note = renderRejectionMessage(reason, context); // throws on malformed context — a half-note never emits
+  return { outcome: DISENGAGED_OUTCOME, reason, note, fields };
+}

package/lib/rejection-templates.d.ts

@@ -0,0 +1,12 @@
+export type RejectionReason = "gate_close" | "maintainer_close_no_reason" | "superseded_by_duplicate";
+
+export type RejectionContext = {
+  repoFullName: string;
+  prNumber: number;
+};
+
+export const REJECTION_REASONS: readonly RejectionReason[];
+
+export function containsPrivateLanguage(text: string): boolean;
+
+export function renderRejectionMessage(reason: RejectionReason, context: RejectionContext): string;

package/lib/rejection-templates.js

@@ -0,0 +1,71 @@
+// CoC-compliant rejection message templates (#2324). When one of the miner's PRs is closed/rejected, it may leave
+// a single, final, human-readable local note (e.g. in a run summary or CLI output — posting anywhere is a separate
+// write action, out of scope here). The note must be courteous, non-defensive, and never re-litigate the
+// maintainer's decision. This module is pure content/formatting: static template strings + a deterministic
+// renderer — no GitHub calls, no LLM, no network. Same inputs always render the same message.
+
+// Templates keyed by rejection-reason bucket. Every placeholder is `{name}`; the renderer resolves the structured
+// context (a PR number + a repo) and never interpolates free-form/private text.
+const REASON_TEMPLATES = {
+  gate_close:
+    "The automated review gate closed PR #{prNumber} on {repoFullName}. Thanks for the review — I'll address the flagged points and open a fresh PR if the change still fits.",
+  maintainer_close_no_reason:
+    "PR #{prNumber} on {repoFullName} was closed by the maintainer. Thanks for taking the time to look — I'll leave it here unless you'd like me to revisit it.",
+  superseded_by_duplicate:
+    "PR #{prNumber} on {repoFullName} looks superseded by other work on the same issue, so I'm closing it on my side to avoid duplication. Thanks to whoever is carrying it forward.",
+};
+
+/** The supported rejection-reason buckets, in declaration order. */
+export const REJECTION_REASONS = Object.freeze(Object.keys(REASON_TEMPLATES));
+
+// Private-language tokens that must never surface in a public-facing courtesy note (mirrors the redaction set in
+// `sanitizePublicComment`, src/github/commands.ts). Templates are authored clean and this is asserted in tests;
+// the structured context (a PR number + a validated `owner/repo`) carries no private scoring/reward/wallet data,
+// so — deliberately — no value-level redaction is applied that could mangle a legitimate repo name.
+const PRIVATE_LANGUAGE =
+  /\b(?:raw trust scores?|trust scores?|wallets?|hotkeys?|coldkeys?|seed phrases?|mnemonics?|payouts?|rewards?)\b/i;
+
+/** True when the given text contains any banned private-language token. */
+export function containsPrivateLanguage(text) {
+  return PRIVATE_LANGUAGE.test(text);
+}
+
+// A GitHub `owner/repo`: owner is 1-39 chars of alphanumerics/hyphens starting alphanumeric; repo is
+// alphanumerics/`.`/`_`/`-`. Anchored + character-class-restricted so control characters, whitespace, markup, or an
+// extra `/` (e.g. `owner/repo\nextra`, `owner/<repo>`) are rejected — the note interpolates this text directly, so a
+// malformed value must throw rather than leak caller-controlled display text.
+const GITHUB_FULL_NAME = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/[A-Za-z0-9._-]{1,100}$/;
+
+function normalizeRepoFullName(repoFullName) {
+  if (typeof repoFullName !== "string") throw new Error("invalid_repo_full_name");
+  const trimmed = repoFullName.trim();
+  if (!GITHUB_FULL_NAME.test(trimmed)) throw new Error("invalid_repo_full_name");
+  return trimmed;
+}
+
+function normalizePrNumber(prNumber) {
+  if (!Number.isInteger(prNumber) || prNumber < 1) throw new Error("invalid_pr_number");
+  return prNumber;
+}
+
+/**
+ * Render the courtesy note for a closed/rejected PR. `reason` must be one of {@link REJECTION_REASONS}; `context`
+ * supplies `repoFullName` (`owner/repo`) and `prNumber` (a positive integer). Throws on an unknown reason, a
+ * malformed context, or (defensively) any placeholder a template leaves unresolved — so a caller can never emit a
+ * half-rendered note. Pure and deterministic.
+ */
+export function renderRejectionMessage(reason, context = {}) {
+  const template = REASON_TEMPLATES[reason];
+  if (template === undefined) throw new Error("invalid_rejection_reason");
+  const values = {
+    repoFullName: normalizeRepoFullName(context.repoFullName),
+    prNumber: normalizePrNumber(context.prNumber),
+  };
+  const rendered = template.replace(/\{(\w+)\}/g, (_match, key) => {
+    const value = values[key];
+    if (value === undefined) throw new Error(`missing_placeholder:${key}`);
+    return String(value);
+  });
+  if (/\{[^}]+\}/.test(rendered)) throw new Error("unresolved_placeholder");
+  return rendered;
+}

package/lib/replay-objective-anchor.d.ts

@@ -0,0 +1,79 @@
+export type ChangeKind =
+  | "feature"
+  | "fix"
+  | "refactor"
+  | "docs"
+  | "test"
+  | "chore"
+  | "perf"
+  | "build"
+  | "ci"
+  | "style"
+  | "other";
+
+export const CHANGE_KINDS: readonly ChangeKind[];
+export const MODULE_OVERLAP_WEIGHT: number;
+export const CHANGE_KIND_WEIGHT: number;
+
+export type ReplayPlanInput = {
+  pathsTouched?: unknown;
+  changeKind?: unknown;
+  title?: unknown;
+};
+
+export type RevealedHistoryEntry = {
+  pathsTouched?: unknown;
+  changeKind?: unknown;
+  title?: unknown;
+};
+
+export type ReplayTargetFeatures = {
+  modules: string[];
+  changeKind: ChangeKind;
+};
+
+export type RevealedFeatures = {
+  modules: string[];
+  changeKinds: ChangeKind[];
+};
+
+export type ObjectiveAnchorBreakdown = {
+  score: number;
+  moduleOverlap: number;
+  changeKindMatch: 0 | 1;
+  replayChangeKind: ChangeKind;
+  revealedChangeKinds: ChangeKind[];
+  sharedModules: string[];
+  replayOnlyModules: string[];
+  revealedOnlyModules: string[];
+};
+
+export type ObjectiveAnchorResult = ObjectiveAnchorBreakdown & {
+  replayFeatures: ReplayTargetFeatures;
+  revealedFeatures: RevealedFeatures;
+};
+
+export function classifyChangeKind(value: unknown): ChangeKind;
+
+export function extractReplayTargetFeatures(
+  plan: ReplayPlanInput | null | undefined,
+): ReplayTargetFeatures;
+
+export function extractRevealedFeatures(
+  history: readonly unknown[] | RevealedHistoryEntry | null | undefined,
+): RevealedFeatures;
+
+export function scoreObjectiveAnchor(
+  replayFeatures: { modules?: unknown; changeKind?: unknown } | null | undefined,
+  revealedFeatures: { modules?: unknown; changeKinds?: unknown } | null | undefined,
+): ObjectiveAnchorBreakdown;
+
+export function computeObjectiveAnchor(
+  input:
+    | {
+        replayPlan?: ReplayPlanInput | null;
+        revealedHistory?: RevealedHistoryEntry[] | RevealedHistoryEntry | null;
+      }
+    | null
+    | undefined,
+): ObjectiveAnchorResult;

package/lib/replay-objective-anchor.js

@@ -0,0 +1,179 @@
+// Deterministic structural "objective-anchor" score for the historical-replay calibration harness (#3012).
+//
+// Once a replay run produces a plan/PR against a frozen snapshot, half of the calibration score is meant to
+// come from a deterministic, auditable structural comparison rather than an LLM judgment. This module is that
+// structural half: it compares what the miner's replayed output *targeted* (modules touched + change kind)
+// against what the revealed post-T history *actually* changed, and returns a reproducible `[0, 1]` score plus
+// a full audit breakdown. There is no model call in this path — given the same two feature sets it is
+// byte-for-byte reproducible.
+
+// Fixed change-kind vocabulary. Conventional-Commit types collapse onto these buckets; anything unrecognized
+// degrades to "other" so a novel prefix lowers the signal instead of throwing.
+export const CHANGE_KINDS = Object.freeze([
+  "feature",
+  "fix",
+  "refactor",
+  "docs",
+  "test",
+  "chore",
+  "perf",
+  "build",
+  "ci",
+  "style",
+  "other",
+]);
+
+const CONVENTIONAL_TYPE_TO_KIND = new Map([
+  ["feat", "feature"],
+  ["feature", "feature"],
+  ["fix", "fix"],
+  ["bugfix", "fix"],
+  ["refactor", "refactor"],
+  ["docs", "docs"],
+  ["doc", "docs"],
+  ["test", "test"],
+  ["tests", "test"],
+  ["chore", "chore"],
+  ["perf", "perf"],
+  ["build", "build"],
+  ["ci", "ci"],
+  ["style", "style"],
+]);
+
+// Fixed weights for the two structural components. They sum to 1 so the composed score stays in [0, 1].
+export const MODULE_OVERLAP_WEIGHT = 0.7;
+export const CHANGE_KIND_WEIGHT = 0.3;
+
+const SCORE_PRECISION = 1e4;
+
+function roundScore(value) {
+  return Math.round(value * SCORE_PRECISION) / SCORE_PRECISION;
+}
+
+// A path's "module" is its directory (everything before the final slash); a bare filename is its own module.
+// Grouping by directory is what makes two different files in one directory a *partial* overlap, not a miss.
+function pathToModule(path) {
+  const trimmed = path.trim().replace(/^(?:\.\/)+/, "").replace(/\/+$/, "");
+  if (!trimmed) return null;
+  const slash = trimmed.lastIndexOf("/");
+  return slash === -1 ? trimmed : trimmed.slice(0, slash);
+}
+
+function normalizeModules(pathsTouched) {
+  if (!Array.isArray(pathsTouched)) return [];
+  const modules = new Set();
+  for (const entry of pathsTouched) {
+    if (typeof entry !== "string") continue;
+    const module = pathToModule(entry);
+    if (module) modules.add(module);
+  }
+  return [...modules].sort();
+}
+
+function normalizeKindList(value) {
+  if (!Array.isArray(value)) return [];
+  const kinds = new Set();
+  for (const entry of value) {
+    if (typeof entry === "string" && CHANGE_KINDS.includes(entry)) kinds.add(entry);
+  }
+  return [...kinds].sort();
+}
+
+function normalizeModuleList(value) {
+  if (!Array.isArray(value)) return [];
+  const modules = new Set();
+  for (const entry of value) {
+    if (typeof entry === "string" && entry) modules.add(entry);
+  }
+  return [...modules].sort();
+}
+
+// Deterministically map a Conventional-Commit-style subject (`feat(scope)!: …`) to a change-kind bucket.
+// Missing prefix, unknown type, or non-string input all resolve to "other" rather than throwing.
+export function classifyChangeKind(value) {
+  if (typeof value !== "string") return "other";
+  const match = /^\s*([A-Za-z]+)\s*(?:\([^)]*\))?\s*!?\s*:/.exec(value);
+  if (!match) return "other";
+  return CONVENTIONAL_TYPE_TO_KIND.get(match[1].toLowerCase()) ?? "other";
+}
+
+function resolveChangeKind(entry) {
+  if (entry && typeof entry.changeKind === "string") {
+    const explicit = entry.changeKind.trim().toLowerCase();
+    if (CHANGE_KINDS.includes(explicit)) return explicit;
+  }
+  return classifyChangeKind(entry?.title);
+}
+
+// Structural features of the miner's replayed plan/PR: the sorted, de-duplicated set of modules it targeted
+// and its single change kind (explicit `changeKind` wins; otherwise classified from `title`).
+export function extractReplayTargetFeatures(plan) {
+  return {
+    modules: normalizeModules(plan?.pathsTouched),
+    changeKind: resolveChangeKind(plan),
+  };
+}
+
+// Structural features of the revealed post-T history. The history is a list of commits/PRs (a single object
+// is tolerated as a one-element list); modules are unioned and change kinds collected into a set, since the
+// revealed side legitimately spans several changes.
+export function extractRevealedFeatures(history) {
+  const entries = Array.isArray(history) ? history : history ? [history] : [];
+  const modules = new Set();
+  const changeKinds = new Set();
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object") continue;
+    for (const module of normalizeModules(entry.pathsTouched)) modules.add(module);
+    changeKinds.add(resolveChangeKind(entry));
+  }
+  return {
+    modules: [...modules].sort(),
+    changeKinds: [...changeKinds].sort(),
+  };
+}
+
+// Deterministic objective-anchor score from two already-extracted feature sets. No LLM, no clock, no
+// randomness — identical inputs always yield an identical breakdown. A zero-overlap comparison (disjoint
+// modules and a change kind the revealed side never shows) resolves to the score floor `0`, never an error.
+export function scoreObjectiveAnchor(replayFeatures, revealedFeatures) {
+  const replayModules = normalizeModuleList(replayFeatures?.modules);
+  const revealedModules = normalizeModuleList(revealedFeatures?.modules);
+  const replayChangeKind =
+    typeof replayFeatures?.changeKind === "string" && CHANGE_KINDS.includes(replayFeatures.changeKind)
+      ? replayFeatures.changeKind
+      : "other";
+  const revealedChangeKinds = normalizeKindList(revealedFeatures?.changeKinds);
+
+  const replaySet = new Set(replayModules);
+  const revealedSet = new Set(revealedModules);
+  const sharedModules = replayModules.filter((module) => revealedSet.has(module));
+  const replayOnlyModules = replayModules.filter((module) => !revealedSet.has(module));
+  const revealedOnlyModules = revealedModules.filter((module) => !replaySet.has(module));
+
+  const unionSize = replayModules.length + revealedModules.length - sharedModules.length;
+  const moduleOverlap = unionSize === 0 ? 0 : sharedModules.length / unionSize;
+  const changeKindMatch = revealedChangeKinds.includes(replayChangeKind) ? 1 : 0;
+
+  return {
+    score: roundScore(MODULE_OVERLAP_WEIGHT * moduleOverlap + CHANGE_KIND_WEIGHT * changeKindMatch),
+    moduleOverlap: roundScore(moduleOverlap),
+    changeKindMatch,
+    replayChangeKind,
+    revealedChangeKinds,
+    sharedModules,
+    replayOnlyModules,
+    revealedOnlyModules,
+  };
+}
+
+// One-shot entry point: extract both sides, score them, and return the score together with the extracted
+// feature sets so a low score is auditable after the fact without re-running the extraction.
+export function computeObjectiveAnchor(input) {
+  const replayFeatures = extractReplayTargetFeatures(input?.replayPlan);
+  const revealedFeatures = extractRevealedFeatures(input?.revealedHistory);
+  return {
+    ...scoreObjectiveAnchor(replayFeatures, revealedFeatures),
+    replayFeatures,
+    revealedFeatures,
+  };
+}

package/lib/replay-snapshot.d.ts

@@ -0,0 +1,41 @@
+import type { WorktreeExecFn, WorktreeRemoveResult } from "@loopover/engine";
+
+export const REPLAY_SNAPSHOT_SUBDIR: ".gittensory-replay-snapshots";
+
+export type ReplaySnapshotCommit = { sha: string; date: string; subject: string };
+export type ReplaySnapshotTag = { name: string; date: string; targetSha: string };
+export type ReplaySnapshotReadme = { filename: string; content: string };
+
+export type ReplaySnapshot = {
+  repoFullName: string;
+  commitSha: string;
+  worktreePath: string;
+  targetDate: string;
+  commits: ReplaySnapshotCommit[];
+  tags: ReplaySnapshotTag[];
+  readme: ReplaySnapshotReadme | null;
+  exportedAt: string;
+};
+
+export function resolveReplaySnapshotDbPath(env?: NodeJS.ProcessEnv): string;
+
+export function planReplaySnapshotPath(input: { repoPath: string; commitSha: string }): string;
+
+export function validateSnapshotFreshness(input: { targetDate: string; commits: ReplaySnapshotCommit[]; tags: ReplaySnapshotTag[] }): void;
+
+export type ReplaySnapshotStore = {
+  dbPath: string;
+  getSnapshot(repoFullName: string, commitSha: string): ReplaySnapshot | null;
+  saveSnapshot(snapshot: Omit<ReplaySnapshot, "exportedAt">): ReplaySnapshot;
+  close(): void;
+};
+
+export function openReplaySnapshotStore(dbPath?: string): ReplaySnapshotStore;
+export function closeDefaultReplaySnapshotStore(): void;
+
+export function exportReplaySnapshot(
+  input: { repoPath: string; repoFullName: string; commitSha: string },
+  deps: { exec: WorktreeExecFn; store?: ReplaySnapshotStore },
+): Promise<ReplaySnapshot>;
+
+export function removeReplaySnapshotWorktree(exec: WorktreeExecFn, repoPath: string, worktreePath: string): Promise<WorktreeRemoveResult>;