@loopover/miner 0.1.0

package/lib/replay-snapshot.js

@@ -0,0 +1,288 @@
+import { join } from "node:path";
+import { removeWorktree } from "@loopover/engine";
+import { openLocalStoreDb, resolveLocalStoreDbPath, normalizeLocalStoreDbPath } from "./local-store.js";
+
+// Freeze/snapshot mechanism for historical replay targets (#3010). Given a repo and a commit SHA T, exports:
+//  (a) the full working tree checked out AT T via a DETACHED git worktree -- the same isolation primitive
+//      worktree-allocator.ts (#4269) uses for attempt isolation, just detached rather than on a new branch,
+//      since a replay target is read-only, never a place to commit -- so it never mutates the caller's own
+//      checkout/branch.
+//  (b) a context bundle: commit history up to and including T (by ANCESTRY, via `git log T` -- walking the DAG
+//      is the tamper-resistant way to bound "up to T", since a commit's committer date is user-controlled and
+//      can't be trusted alone), tags reachable from T (`git tag --merged T`), and the README as it existed at
+//      T (`git ls-tree` + `git show T:<name>`, matched case-insensitively rather than a guessed filename list).
+//
+// REUSE NOTE: this issue's own text frames "the discover and analyze phases... already read git history" as
+// the reuse starting point. Grepped both packages (git log/git tag/commits/tags/releases) before writing this
+// and found no such utility anywhere -- opportunity-fanout.js reads GitHub API issue `updated_at`, not git
+// commit/tag history at all. The one genuinely reusable piece is worktree-allocator.ts's injected-exec
+// convention (WorktreeExecFn) and its removeWorktree -- both reused directly below (import from
+// @loopover/engine), rather than inventing a THIRD "inject the git subprocess" abstraction
+// alongside cli-subprocess-driver.ts's and worktree-allocator.ts's own.
+//
+// FAIL-FAST VALIDATION: ancestry-walking (git log T) already excludes anything NOT reachable from T by
+// construction, but a tag can point at a commit that IS an ancestor of T while the TAG's own creation/tagger
+// date is LATER (e.g. a tag added long after the commit it points to), and commit committer-dates are not
+// strictly monotonic along the DAG in general (rebases, clock skew). So checking every exported commit's date
+// and every exported tag's date against T's own commit date is a genuine, not merely defensive, check.
+//
+// PERSISTENCE: the context bundle is cached in the local store, UNIQUE-keyed on (repo_full_name, commit_sha) --
+// re-exporting the same (repo, T) pair returns the identical cached row rather than re-running git, which is
+// both how "byte-reproducible" holds trivially and avoids redundant work on repeat replay runs. The working-
+// tree export itself is git-content-addressed already (the same commit SHA always checks out identical files).
+
+const defaultDbFileName = "replay-snapshot.sqlite3";
+let defaultDb = null;
+
+export function resolveReplaySnapshotDbPath(env = process.env) {
+  return resolveLocalStoreDbPath(defaultDbFileName, "GITTENSORY_MINER_REPLAY_SNAPSHOT_DB", env);
+}
+
+function normalizeDbPath(dbPath) {
+  return normalizeLocalStoreDbPath(dbPath, resolveReplaySnapshotDbPath(), "invalid_replay_snapshot_db_path");
+}
+
+const FIELD_SEP = "\x1f";
+const README_NAME_PATTERN = /^readme(\.\w+)?$/i;
+
+function normalizeRepoFullName(repoFullName) {
+  if (typeof repoFullName !== "string") throw new Error("invalid_repo_full_name");
+  const [owner, repo, extra] = repoFullName.trim().split("/");
+  if (!owner || !repo || extra !== undefined) throw new Error("invalid_repo_full_name");
+  return `${owner}/${repo}`;
+}
+
+function normalizeCommitSha(commitSha) {
+  if (typeof commitSha !== "string" || !commitSha.trim()) throw new Error("invalid_commit_sha");
+  return commitSha.trim();
+}
+
+/** Worktree exports live under this dir inside the repo, mirroring worktree-allocator.ts's WORKTREE_SUBDIR. */
+export const REPLAY_SNAPSHOT_SUBDIR = ".gittensory-replay-snapshots";
+
+/** PURE: the deterministic on-disk location for a (repo, commit) replay export -- same pair -> same path. */
+export function planReplaySnapshotPath(input) {
+  const commitSha = normalizeCommitSha(input.commitSha);
+  return join(input.repoPath, REPLAY_SNAPSHOT_SUBDIR, commitSha);
+}
+
+function assertExecResult(result, description) {
+  if (result.code !== 0) {
+    const detail = (result.stderr ?? "").trim() || `exit_${result.code}`;
+    throw new Error(`${description}: ${detail}`);
+  }
+  return result.stdout ?? "";
+}
+
+/** Detached checkout at commitSha via `git worktree add --detach` -- never creates a branch, never touches the
+ *  caller's own checkout. Idempotent in effect: `git worktree add` itself fails if the path already has a
+ *  worktree, which callers avoid by checking the store cache first (see exportReplaySnapshot). */
+async function addDetachedWorktree(exec, repoPath, worktreePath, commitSha) {
+  const result = await exec("git", ["worktree", "add", "--detach", worktreePath, commitSha], { cwd: repoPath });
+  assertExecResult(result, "git_worktree_add_failed");
+}
+
+async function readTargetCommitDate(exec, repoPath, commitSha) {
+  const result = await exec("git", ["log", "-1", "--format=%cI", commitSha], { cwd: repoPath });
+  const stdout = assertExecResult(result, "git_log_target_failed").trim();
+  if (!stdout) throw new Error(`git_log_target_failed: no commit found for ${commitSha}`);
+  return stdout;
+}
+
+async function readCommitHistory(exec, repoPath, commitSha) {
+  const result = await exec("git", ["log", commitSha, `--format=%H${FIELD_SEP}%cI${FIELD_SEP}%s`], { cwd: repoPath });
+  const stdout = assertExecResult(result, "git_log_history_failed");
+  return stdout
+    .split("\n")
+    .filter((line) => line.length > 0)
+    .map((line) => {
+      const [sha, date, subject] = line.split(FIELD_SEP);
+      return { sha, date, subject: subject ?? "" };
+    });
+}
+
+// Lightweight tags have no tag object of their own, so `%(creatordate)` falls back to the POINTED-TO commit's
+// date rather than a genuine tag-creation date -- git has no record of when a lightweight tag was actually
+// created at all. That means a lightweight tag added long after T, but pointing at an ancestor of T, would
+// silently pass validateSnapshotFreshness's date check every time (its reported "date" is always <= T's, by
+// construction of --merged). Since this can never be verified, lightweight tags are excluded from the export
+// entirely -- `%(objecttype)` is "tag" only for an annotated tag's own tag object, "commit" for a lightweight
+// tag's direct target, which is how the two are told apart.
+async function readReachableTags(exec, repoPath, commitSha) {
+  const result = await exec(
+    "git",
+    ["tag", "--merged", commitSha, `--format=%(refname:short)${FIELD_SEP}%(creatordate:iso-strict)${FIELD_SEP}%(objectname)${FIELD_SEP}%(objecttype)`],
+    { cwd: repoPath },
+  );
+  const stdout = assertExecResult(result, "git_tag_merged_failed");
+  return stdout
+    .split("\n")
+    .filter((line) => line.length > 0)
+    .map((line) => {
+      const [name, date, targetSha, objectType] = line.split(FIELD_SEP);
+      return { name, date, targetSha, objectType };
+    })
+    .filter((tag) => tag.objectType === "tag")
+    .map(({ objectType, ...tag }) => tag);
+}
+
+/** Finds the repo-root README (any casing/extension) at commitSha and returns its content, or null if none
+ *  exists at that commit. Uses `git ls-tree` to find the real filename rather than guessing a fixed spelling
+ *  list. */
+async function readReadmeAtCommit(exec, repoPath, commitSha) {
+  const listing = await exec("git", ["ls-tree", "--name-only", commitSha], { cwd: repoPath });
+  const stdout = assertExecResult(listing, "git_ls_tree_failed");
+  const filename = stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .find((line) => README_NAME_PATTERN.test(line));
+  if (!filename) return null;
+
+  const shown = await exec("git", ["show", `${commitSha}:${filename}`], { cwd: repoPath });
+  const content = assertExecResult(shown, "git_show_readme_failed");
+  return { filename, content };
+}
+
+/** PURE: fails fast (throws) if any exported commit or tag carries a date LATER than the target commit's own
+ *  date. Returns nothing on success. */
+export function validateSnapshotFreshness(input) {
+  const targetMs = Date.parse(input.targetDate);
+  const violations = [];
+  for (const commit of input.commits) {
+    if (Date.parse(commit.date) > targetMs) violations.push(`commit ${commit.sha} dated ${commit.date} is after target ${input.targetDate}`);
+  }
+  for (const tag of input.tags) {
+    if (Date.parse(tag.date) > targetMs) violations.push(`tag ${tag.name} dated ${tag.date} is after target ${input.targetDate}`);
+  }
+  if (violations.length > 0) throw new Error(`replay_snapshot_freshness_violation: ${violations.join("; ")}`);
+}
+
+export function openReplaySnapshotStore(dbPath = resolveReplaySnapshotDbPath()) {
+  const resolvedPath = normalizeDbPath(dbPath);
+  const db = openLocalStoreDb(resolvedPath);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS replay_snapshots (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      repo_full_name TEXT NOT NULL,
+      commit_sha TEXT NOT NULL,
+      worktree_path TEXT NOT NULL,
+      target_date TEXT NOT NULL,
+      commits_json TEXT NOT NULL,
+      tags_json TEXT NOT NULL,
+      readme_filename TEXT,
+      readme_content TEXT,
+      exported_at TEXT NOT NULL,
+      UNIQUE (repo_full_name, commit_sha)
+    )
+  `);
+  const getStatement = db.prepare("SELECT * FROM replay_snapshots WHERE repo_full_name = ? AND commit_sha = ?");
+  const insertStatement = db.prepare(`
+    INSERT INTO replay_snapshots
+      (repo_full_name, commit_sha, worktree_path, target_date, commits_json, tags_json, readme_filename, readme_content, exported_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  function rowToSnapshot(row) {
+    return {
+      repoFullName: row.repo_full_name,
+      commitSha: row.commit_sha,
+      worktreePath: row.worktree_path,
+      targetDate: row.target_date,
+      commits: JSON.parse(row.commits_json),
+      tags: JSON.parse(row.tags_json),
+      readme: row.readme_filename ? { filename: row.readme_filename, content: row.readme_content } : null,
+      exportedAt: row.exported_at,
+    };
+  }
+
+  return {
+    dbPath: resolvedPath,
+    getSnapshot(repoFullName, commitSha) {
+      const row = getStatement.get(normalizeRepoFullName(repoFullName), normalizeCommitSha(commitSha));
+      return row ? rowToSnapshot(row) : null;
+    },
+    saveSnapshot(snapshot) {
+      const repoFullName = normalizeRepoFullName(snapshot.repoFullName);
+      const commitSha = normalizeCommitSha(snapshot.commitSha);
+      insertStatement.run(
+        repoFullName,
+        commitSha,
+        snapshot.worktreePath,
+        snapshot.targetDate,
+        JSON.stringify(snapshot.commits),
+        JSON.stringify(snapshot.tags),
+        snapshot.readme?.filename ?? null,
+        snapshot.readme?.content ?? null,
+        new Date().toISOString(),
+      );
+      return this.getSnapshot(repoFullName, commitSha);
+    },
+    close() {
+      db.close();
+    },
+  };
+}
+
+function getDefaultReplaySnapshotStore() {
+  defaultDb ??= openReplaySnapshotStore();
+  return defaultDb;
+}
+
+export function closeDefaultReplaySnapshotStore() {
+  if (!defaultDb) return;
+  defaultDb.close();
+  defaultDb = null;
+}
+
+/**
+ * Export a frozen, reproducible replay snapshot for (repoFullName, commitSha): a detached working-tree checkout
+ * at that commit plus a context bundle (commit history, reachable tags, README-at-commit). Returns the CACHED
+ * snapshot without touching git again if one already exists for this exact (repo, commit) pair.
+ *
+ * @param {{ repoPath: string, repoFullName: string, commitSha: string }} input
+ * @param {{ exec: import("./worktree-allocator.js").WorktreeExecFn, store?: ReturnType<typeof openReplaySnapshotStore> }} deps
+ */
+export async function exportReplaySnapshot(input, deps) {
+  if (!input || typeof input !== "object") throw new Error("invalid_replay_snapshot_input");
+  const repoFullName = normalizeRepoFullName(input.repoFullName);
+  const commitSha = normalizeCommitSha(input.commitSha);
+  if (typeof input.repoPath !== "string" || !input.repoPath.trim()) throw new Error("invalid_repo_path");
+  const repoPath = input.repoPath.trim();
+
+  if (!deps || typeof deps !== "object" || typeof deps.exec !== "function") throw new Error("invalid_exec");
+  const { exec } = deps;
+  const store = deps.store ?? getDefaultReplaySnapshotStore();
+
+  const cached = store.getSnapshot(repoFullName, commitSha);
+  if (cached) return cached;
+
+  const worktreePath = planReplaySnapshotPath({ repoPath, commitSha });
+  await addDetachedWorktree(exec, repoPath, worktreePath, commitSha);
+
+  // Everything below can fail (a bad git read, or a deliberate freshness violation) after the worktree already
+  // exists on disk at the deterministic path above. Left behind, a retry for the same (repo, commit) pair would
+  // hit `git worktree add`'s own "path already exists" refusal instead of the real error, permanently masking
+  // it. Clean up the worktree on any failure here before rethrowing, so a retry starts from a clean slate.
+  try {
+    const targetDate = await readTargetCommitDate(exec, repoPath, commitSha);
+    const commits = await readCommitHistory(exec, repoPath, commitSha);
+    const tags = await readReachableTags(exec, repoPath, commitSha);
+    const readme = await readReadmeAtCommit(exec, repoPath, commitSha);
+
+    validateSnapshotFreshness({ targetDate, commits, tags });
+
+    return store.saveSnapshot({ repoFullName, commitSha, worktreePath, targetDate, commits, tags, readme });
+  } catch (error) {
+    await removeReplaySnapshotWorktree(exec, repoPath, worktreePath).catch(() => {
+      /* best-effort cleanup -- the original error below is the one that matters to the caller */
+    });
+    throw error;
+  }
+}
+
+/** Tear down a replay snapshot's working-tree export (the cached context-bundle row is left in place -- it is
+ *  cheap, commit-keyed, and re-usable even after the on-disk tree is removed; only re-adding the worktree would
+ *  require the tree again, which is out of this function's scope). */
+export async function removeReplaySnapshotWorktree(exec, repoPath, worktreePath) {
+  return removeWorktree({ exec, repoPath, worktreePath });
+}

package/lib/replay-task-generation.d.ts

@@ -0,0 +1,126 @@
+export const FORWARD_REF_PLACEHOLDER: string;
+
+export type RecencyPool = "recent" | "older";
+export const RECENCY_POOLS: readonly RecencyPool[];
+
+export type ForwardReference = {
+  kind: "link" | "hashref" | "sha" | "bare-issue-number";
+  value: string | number;
+};
+
+export type ForwardRefContext = {
+  knownIssueMax?: number;
+  knownCommitShas?: string[];
+  revealedIssueNumbers?: number[];
+};
+
+export type DetectedForwardReferences = {
+  scrubbable: ForwardReference[];
+  unscrubbable: ForwardReference[];
+};
+
+export type ScrubResult = {
+  scrubbed: string;
+  removed: ForwardReference[];
+  residual: ForwardReference[];
+};
+
+export type LintResult = {
+  ok: boolean;
+  residual: ForwardReference[];
+};
+
+export type FreezePointThresholds = {
+  minPriorCommits?: number;
+  minRevealedCommits?: number;
+};
+
+export type FreezePointCandidate = {
+  repo?: string;
+  commitT?: string;
+  priorCommitCount?: number;
+  revealedCommitCount?: number;
+  lastActivityAt?: string;
+  frozenContextTexts?: unknown[];
+  revealedGroundTruth?: unknown;
+};
+
+export type FreezePointSelection = {
+  eligible: boolean;
+  reasons: string[];
+  priorCommitCount: number;
+  revealedCommitCount: number;
+};
+
+export type ReplayTaskOptions = {
+  thresholds?: FreezePointThresholds;
+  modelCutoffIso?: string;
+};
+
+export type ReplayTaskRejected = {
+  eligible: false;
+  rejected: "selection" | "unscrubbable_forward_reference";
+  reasons?: string[];
+  residual?: ForwardReference[];
+};
+
+export type ReplayTask = {
+  eligible: true;
+  pool: RecencyPool;
+  frozen: {
+    repo: string | null;
+    commitT: string | null;
+    contextTexts: string[];
+  };
+};
+
+export type ReplayScoringKey = {
+  eligible: true;
+  commitCount: number;
+  groundTruth: unknown;
+};
+
+// generateReplayScoringKey never lints/scrubs frozen context (it doesn't touch context text at all), so
+// unlike ReplayTaskRejected it can only ever reject on selection -- narrower than reusing ReplayTaskRejected,
+// which would advertise an "unscrubbable_forward_reference" branch this function can never actually produce.
+export type ReplayScoringKeyRejected = {
+  eligible: false;
+  rejected: "selection";
+  reasons: string[];
+};
+
+export function detectForwardReferences(
+  text: unknown,
+  context: ForwardRefContext | null | undefined,
+): DetectedForwardReferences;
+
+export function scrubForwardReferences(
+  text: unknown,
+  context: ForwardRefContext | null | undefined,
+): ScrubResult;
+
+export function lintFrozenContext(
+  texts: unknown,
+  context: ForwardRefContext | null | undefined,
+): LintResult;
+
+export function selectFreezePoint(
+  candidate: FreezePointCandidate | null | undefined,
+  thresholds: FreezePointThresholds | null | undefined,
+): FreezePointSelection;
+
+export function classifyRecencyPool(
+  candidate: FreezePointCandidate | null | undefined,
+  options: { modelCutoffIso?: string } | null | undefined,
+): RecencyPool;
+
+export function generateReplayTask(
+  candidate: FreezePointCandidate | null | undefined,
+  context: ForwardRefContext | null | undefined,
+  options: ReplayTaskOptions | null | undefined,
+): ReplayTask | ReplayTaskRejected;
+
+export function generateReplayScoringKey(
+  candidate: FreezePointCandidate | null | undefined,
+  options: ReplayTaskOptions | null | undefined,
+): ReplayScoringKey | ReplayScoringKeyRejected;

package/lib/replay-task-generation.js

@@ -0,0 +1,223 @@
+// Leakage-safe task generation for the historical-replay calibration harness (#3011).
+//
+// A frozen snapshot at commit T is only useful for calibration if (a) the freeze point has enough real
+// history on both sides to be worth scoring, and (b) nothing in the frozen context lets a replay run infer
+// the future by pattern-matching text rather than reasoning. This module selects calibration-worthy freeze
+// points, scrubs forward references out of the frozen context, tags each point's recency pool, and returns
+// the frozen replay task without the revealed post-T ground truth. Scoring data is exposed through a separate
+// function so replay execution never has to hold both sides at once. Every function here is pure and
+// deterministic — no clock, no randomness, no IO — so a given (candidate, context) always yields an
+// identical task.
+
+// What a scrubbed-away forward reference is replaced with. A fixed, self-delimiting token so the scrubbed
+// text stays readable and the substitution is itself deterministic.
+export const FORWARD_REF_PLACEHOLDER = "[redacted-forward-ref]";
+
+// Recency pools. Freeze points are mixed across these bands so a judge/planner that has memorized recent
+// public history cannot dominate the calibration signal.
+export const RECENCY_POOLS = Object.freeze(["recent", "older"]);
+
+function toIssueNumberSet(values) {
+  const set = new Set();
+  if (Array.isArray(values)) {
+    for (const value of values) {
+      if (Number.isInteger(value) && value > 0) set.add(value);
+    }
+  }
+  return set;
+}
+
+function toShaSet(values) {
+  const set = new Set();
+  if (Array.isArray(values)) {
+    for (const value of values) {
+      if (typeof value === "string" && /^[0-9a-f]{7,40}$/i.test(value)) set.add(value.toLowerCase());
+    }
+  }
+  return set;
+}
+
+function resolveContext(context) {
+  return {
+    knownIssueMax:
+      Number.isInteger(context?.knownIssueMax) && context.knownIssueMax >= 0 ? context.knownIssueMax : 0,
+    knownCommitShas: toShaSet(context?.knownCommitShas),
+    revealedIssueNumbers: toIssueNumberSet(context?.revealedIssueNumbers),
+  };
+}
+
+// Core scanner shared by scrub/detect/lint. Walks a text in a fixed priority order (deep-links first, so an
+// issue/PR/commit URL is handled before its inner number/SHA can match a barer pattern) and classifies each
+// forward reference as either:
+//   - scrubbable: a self-delimited token (`#123`, a GitHub issues/pull/commit URL, or a raw commit SHA) that
+//     resolves only to post-T state and can be safely replaced with the placeholder; or
+//   - unscrubbable: a *bare* integer that exactly matches a known post-T issue number. A bare number cannot be
+//     blanket-removed without destroying legitimate pre-T numbers (versions, counts), so it is detected but
+//     left in place — its presence must fail the freeze point rather than be silently mangled.
+function processForwardReferences(rawText, context) {
+  const resolved = resolveContext(context);
+  const removed = [];
+
+  const text = typeof rawText === "string" ? rawText : "";
+
+  // 1. GitHub issue/pull deep-links whose number is after T.
+  let scrubbed = text.replace(
+    /https?:\/\/github\.com\/[\w.-]+\/[\w.-]+\/(?:issues|pull)\/(\d+)\b/gi,
+    (match, digits) => {
+      if (Number(digits) > resolved.knownIssueMax) {
+        removed.push({ kind: "link", value: match });
+        return FORWARD_REF_PLACEHOLDER;
+      }
+      return match;
+    },
+  );
+
+  // 2. GitHub commit deep-links whose SHA is not in pre-T history.
+  scrubbed = scrubbed.replace(
+    /https?:\/\/github\.com\/[\w.-]+\/[\w.-]+\/commit\/([0-9a-f]{7,40})\b/gi,
+    (match, sha) => {
+      if (!resolved.knownCommitShas.has(sha.toLowerCase())) {
+        removed.push({ kind: "link", value: match });
+        return FORWARD_REF_PLACEHOLDER;
+      }
+      return match;
+    },
+  );
+
+  // 3. Bare `#123` issue/PR references after T (not already inside a now-removed link).
+  scrubbed = scrubbed.replace(/(^|[^\w/])#(\d+)\b/g, (match, prefix, digits) => {
+    if (Number(digits) > resolved.knownIssueMax) {
+      removed.push({ kind: "hashref", value: `#${digits}` });
+      return `${prefix}${FORWARD_REF_PLACEHOLDER}`;
+    }
+    return match;
+  });
+
+  // 4. Raw commit SHAs not in pre-T history. Require at least one hex letter so a plain decimal number is
+  //    never misread as a SHA — those flow to the bare-issue-number residual check below instead.
+  scrubbed = scrubbed.replace(/(^|[^\w/#])([0-9a-f]{7,40})\b/gi, (match, prefix, sha) => {
+    if (!/[a-f]/i.test(sha)) return match;
+    if (!resolved.knownCommitShas.has(sha.toLowerCase())) {
+      removed.push({ kind: "sha", value: sha });
+      return `${prefix}${FORWARD_REF_PLACEHOLDER}`;
+    }
+    return match;
+  });
+
+  // Residual: bare integers that name a real post-T issue and so leak the future, but cannot be safely
+  // auto-removed. Detected against the surviving text — if any remain, the freeze point is not usable as-is.
+  const residual = [];
+  if (resolved.revealedIssueNumbers.size > 0) {
+    for (const bareMatch of scrubbed.matchAll(/(?:^|[^\w#/])(\d+)\b/g)) {
+      const value = Number(bareMatch[1]);
+      if (resolved.revealedIssueNumbers.has(value)) {
+        residual.push({ kind: "bare-issue-number", value });
+      }
+    }
+  }
+
+  return { scrubbed, removed, residual };
+}
+
+// Detect forward references in text without modifying it, split by whether they can be safely scrubbed.
+export function detectForwardReferences(text, context) {
+  const { removed, residual } = processForwardReferences(text, context);
+  return { scrubbable: removed, unscrubbable: residual };
+}
+
+// Scrub the safely-removable forward references from text, returning the cleaned text, what was removed, and
+// any unscrubbable references that remain (a non-empty `residual` means the text still leaks the future).
+export function scrubForwardReferences(text, context) {
+  return processForwardReferences(text, context);
+}
+
+// A freeze point's frozen context is clean iff every provided text scrubs to zero residual forward references.
+export function lintFrozenContext(texts, context) {
+  const list = Array.isArray(texts) ? texts : texts == null ? [] : [texts];
+  const residual = [];
+  for (const text of list) {
+    residual.push(...processForwardReferences(text, context).residual);
+  }
+  return { ok: residual.length === 0, residual };
+}
+
+// Selection: a freeze point is calibration-worthy only with enough real history on both sides of T.
+export function selectFreezePoint(candidate, thresholds) {
+  const minPriorCommits = Number.isInteger(thresholds?.minPriorCommits) ? thresholds.minPriorCommits : 0;
+  const minRevealedCommits = Number.isInteger(thresholds?.minRevealedCommits)
+    ? thresholds.minRevealedCommits
+    : 0;
+  const priorCommitCount = Number.isInteger(candidate?.priorCommitCount) ? candidate.priorCommitCount : 0;
+  const revealedCommitCount = Number.isInteger(candidate?.revealedCommitCount)
+    ? candidate.revealedCommitCount
+    : 0;
+
+  const reasons = [];
+  if (priorCommitCount < minPriorCommits) reasons.push("insufficient_prior_history");
+  if (revealedCommitCount < minRevealedCommits) reasons.push("insufficient_revealed_history");
+
+  return { eligible: reasons.length === 0, reasons, priorCommitCount, revealedCommitCount };
+}
+
+// Pool provenance: a freeze point whose last activity is at/after the calibration run's model cutoff is
+// "recent" (higher memorization risk); everything else, including an unknown date, is "older". ISO-8601
+// timestamps sort lexicographically, so no clock is needed.
+export function classifyRecencyPool(candidate, options) {
+  const modelCutoffIso = typeof options?.modelCutoffIso === "string" ? options.modelCutoffIso : "";
+  const lastActivityAt = typeof candidate?.lastActivityAt === "string" ? candidate.lastActivityAt : "";
+  if (!modelCutoffIso || !lastActivityAt) return "older";
+  return lastActivityAt >= modelCutoffIso ? "recent" : "older";
+}
+
+// One-shot replay generator. Applies selection, then scrubs and lints the frozen context, then returns only
+// the frozen replay task. Revealed post-T ground truth is intentionally available only through
+// generateReplayScoringKey, so a replay worker/serializer/logger/model call never receives both sides.
+export function generateReplayTask(candidate, context, options) {
+  const selection = selectFreezePoint(candidate, options?.thresholds);
+  if (!selection.eligible) {
+    return { eligible: false, rejected: "selection", reasons: selection.reasons };
+  }
+
+  const frozenTexts = Array.isArray(candidate?.frozenContextTexts) ? candidate.frozenContextTexts : [];
+  const lint = lintFrozenContext(frozenTexts, context);
+  if (!lint.ok) {
+    return { eligible: false, rejected: "unscrubbable_forward_reference", residual: lint.residual };
+  }
+
+  const pool = classifyRecencyPool(candidate, options);
+  const scrubbedTexts = frozenTexts.map((text) => processForwardReferences(text, context).scrubbed);
+
+  return {
+    eligible: true,
+    pool,
+    frozen: {
+      repo: typeof candidate?.repo === "string" ? candidate.repo : null,
+      commitT: typeof candidate?.commitT === "string" ? candidate.commitT : null,
+      contextTexts: scrubbedTexts,
+    },
+  };
+}
+
+// Scoring-only accessor. Call this from the isolated scorer path after replay execution has finished; do not
+// pass its result to replay workers. It deliberately shares only selection eligibility with generateReplayTask
+// and never carries frozen context.
+//
+// IMPORTANT: `eligible: true` here means only that selectFreezePoint accepted the candidate -- it does NOT
+// mean generateReplayTask would also produce a usable frozen task for it. generateReplayTask can still reject
+// a selection-eligible candidate afterward (`rejected: "unscrubbable_forward_reference"`, from
+// lintFrozenContext), because scrub/lint eligibility is about the FROZEN CONTEXT TEXT, which this function
+// never touches -- it only reveals commitCount/groundTruth, so lint/scrub has nothing to check here. A caller
+// must not assume a scoring key implies a replay task was ever generated for the same candidate; check
+// generateReplayTask's own result independently before treating the two as a matched pair.
+export function generateReplayScoringKey(candidate, options) {
+  const selection = selectFreezePoint(candidate, options?.thresholds);
+  if (!selection.eligible) {
+    return { eligible: false, rejected: "selection", reasons: selection.reasons };
+  }
+
+  return {
+    eligible: true,
+    commitCount: selection.revealedCommitCount,
+    groundTruth: candidate?.revealedGroundTruth ?? null,
+  };
+}

package/lib/repo-clone.d.ts

@@ -0,0 +1,19 @@
+export function resolveRepoCloneBaseDir(env?: Record<string, string | undefined>): string;
+
+export function resolveRepoCloneDir(repoFullName: string, env?: Record<string, string | undefined>): string;
+
+export type EnsureRepoClonedResult = { ok: boolean; repoPath: string; error?: string };
+
+export type RunGitFn = (args: string[], cwd: string, timeoutMs: number) => Promise<{ ok: boolean; stdout: string; stderr: string }>;
+
+export function ensureRepoCloned(
+  repoFullName: string,
+  options?: {
+    baseBranch?: string;
+    cloneBaseDir?: string;
+    env?: Record<string, string | undefined>;
+    timeoutMs?: number;
+    remoteUrl?: string;
+    runGit?: RunGitFn;
+  },
+): Promise<EnsureRepoClonedResult>;