codecartographer-pi 0.16.0 → 0.17.1

package/dist/core/completion.d.ts

@@ -2,6 +2,11 @@ import type { ValidationResult, WorkspaceState } from "./types.ts";
 export type CompletionResult = {
     updatedState: WorkspaceState;
     closeoutNotice?: string;
+    /**
+     * Non-gating closure-integrity observations (#122): closures the handoff
+     * claims that the primary output never mentions. Empty when clean.
+     */
+    warnings: string[];
     /**
      * One-line phase-boundary reminder covering what completion just mechanized
      * (decisions appended, proposals staged) and what still needs orchestrator

package/dist/core/completion.js

@@ -1,8 +1,8 @@
 import { appendFile, copyFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { getNextEligiblePhase, resolvePhase } from "./pipeline.js";
+import { getNextEligiblePhase, resolvePhase, validatePhaseOutput } from "./pipeline.js";
 import { applyHandoff, autoAssignIds, buildTerminalNextActions, loadHandoffFile, normalizeStatus } from "./status.js";
-import { dateOnly, pathExists, uniqueStrings } from "./utils.js";
+import { dateOnly, newlineIfUnterminated, pathExists, uniqueStrings } from "./utils.js";
 import { getWorkspaceState, updateStatusAtomically } from "./workspace.js";
 /**
  * The Markdown a reader sees: content inside `<!-- -->` blocks removed by a
@@ -223,7 +223,7 @@ async function writeCompletionArtifacts(workspaceDir, phaseId, validation, times
     }
     const link = `[closeout](closeouts/${closeoutFile})`;
     if (!current.split(/\r?\n/).some((line) => line.includes(link))) {
-        await appendFile(threadLogPath, `${entry}\n`, "utf8");
+        await appendFile(threadLogPath, `${newlineIfUnterminated(current)}${entry}\n`, "utf8");
     }
     // Mechanize the orchestrator loop's bookkeeping half (issue #98): decisions
     // reach DECISIONS.md and proposals reach CONVENTIONS.md at completion, so a
@@ -268,6 +268,21 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
                 throw new Error("Invalid handoff: post_pipeline entries require a canonical id");
         }
     }
+    // Closure integrity (#122, warning only): a handoff can close a carry-forward
+    // or open question the report never addressed — "closed in the handoff,
+    // resolved nowhere." The id of every claimed closure should appear somewhere
+    // in the primary output that claims to resolve it.
+    const warnings = [];
+    if (handoff && validation.outputPath) {
+        const closures = [...handoff.carry_forward_closures, ...handoff.open_question_closures].filter((id) => id?.trim());
+        if (closures.length > 0) {
+            const output = await readFile(validation.outputPath, "utf8").catch(() => "");
+            const unmentioned = closures.filter((id) => !output.includes(id));
+            if (unmentioned.length > 0) {
+                warnings.push(`The handoff closes ${unmentioned.join(", ")} but .codecarto/${validation.primaryOutput} never mentions ${unmentioned.length === 1 ? "that id" : "those ids"} — a closure should be visible in the report that claims to resolve it, not only in the handoff.`);
+            }
+        }
+    }
     const completionTimestamp = new Date().toISOString();
     let closeoutPath;
     let orchestratorCheckpoint;
@@ -275,6 +290,22 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
         const phase = resolvePhase(lockedState, validation.phaseId);
         if (!phase?.primary_output)
             throw new Error(`Phase ${validation.phaseId} is missing primary_output.`);
+        // Re-validate the output under the lock (#132). The caller's
+        // validation snapshot can predate a concurrent edit or another
+        // session's completion; a stale PASS must not complete a phase whose
+        // output no longer validates. The locked recheck is the authoritative
+        // one and is what every artifact below is written from.
+        // A validation that never touched a file on disk (no outputPath)
+        // has nothing to race against, so the caller's result stands — the
+        // real surfaces (MCP, Pi) always validate real files.
+        const authoritative = validation.outputPath
+            ? await validatePhaseOutput(lockedState, validation.phaseId)
+            : validation;
+        if (authoritative.overall === "FAIL" || authoritative.overall === "MISSING") {
+            throw new Error(`Refusing to complete ${validation.phaseId}: the output no longer validates under the status lock ` +
+                `(now ${authoritative.overall}). It changed since the last validation — re-run validation and fix the output first.`);
+        }
+        const lockedValidation = authoritative;
         const nextStatus = normalizeStatus(lockedState.status, lockedState.pipeline, lockedState.status.pipeline, lockedState.cwd);
         const existingPhase = nextStatus.phases[validation.phaseId] ?? {
             status: "pending",
@@ -283,7 +314,7 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
             open_questions: [],
             carry_forward: [],
         };
-        const gapEntries = validation.rows
+        const gapEntries = lockedValidation.rows
             .filter((row) => row.result.toUpperCase().includes("PARTIAL"))
             .map((row) => ({
             kind: "needs-maintainer-decision",
@@ -303,7 +334,7 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
                 ...existingPhase.owner_notes,
                 `Completed via ${sourceLabel}.`,
                 `Primary output: .codecarto/${validation.primaryOutput}`,
-                `Validation: ${validation.overall}`,
+                `Validation: ${lockedValidation.overall}`,
             ]),
             outputs_present: uniqueStrings([...existingPhase.outputs_present, validation.primaryOutput]),
             open_questions: mergedOpenQuestions,
@@ -318,7 +349,7 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
         nextStatus.next_actions = nextEligible
             ? [`Begin ${nextEligible.id} phase by producing ${nextEligible.primary_output ?? `findings/${nextEligible.id}/`}`]
             : buildTerminalNextActions(nextStatus);
-        const artifacts = await writeCompletionArtifacts(lockedState.workspaceDir, validation.phaseId, validation, completionTimestamp, handoff);
+        const artifacts = await writeCompletionArtifacts(lockedState.workspaceDir, validation.phaseId, lockedValidation, completionTimestamp, handoff);
         closeoutPath = artifacts.closeoutPath;
         orchestratorCheckpoint = buildOrchestratorCheckpoint(artifacts.decisionsAppended, artifacts.totalPendingProposals, nextStatus);
         return { state: { ...nextWorkspace, status: nextStatus } };
@@ -327,5 +358,6 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
         updatedState,
         closeoutNotice: closeoutPath ? `Closeout: ${closeoutPath}` : undefined,
         orchestratorCheckpoint,
+        warnings,
     };
 }

package/dist/core/dashboard.js

@@ -452,7 +452,9 @@ function usagePhaseNote(phaseId, status) {
 function renderActivityTimeline(runs) {
     if (runs.length === 0)
         return "";
-    const sorted = [...runs].sort((a, b) => (a.timestamp < b.timestamp ? 1 : -1));
+    // Newest first. The comparator must return 0 for equal keys: returning -1
+    // in both directions left same-timestamp order implementation-defined (#134).
+    const sorted = [...runs].sort((a, b) => (a.timestamp < b.timestamp ? 1 : a.timestamp > b.timestamp ? -1 : 0));
     const visible = sorted.slice(0, TIMELINE_VISIBLE_COUNT);
     const overflow = sorted.slice(TIMELINE_VISIBLE_COUNT);
     const hasSessionLinks = sorted.some((run) => Boolean(run.session_file && safeRelativeHref(run.session_file)));
@@ -507,7 +509,7 @@ function renderCloseoutsList(inputs) {
     const closeouts = inputs.closeouts;
     if (closeouts.length === 0)
         return [`<section class="cc-card cc-closeouts" id="closeouts" aria-label="Closeouts" data-section>`, `<h2>Closeouts</h2>`, `<p class="cc-empty">No closeouts yet.</p>`, `</section>`].join("\n");
-    const sorted = [...closeouts].sort((a, b) => (a.date < b.date ? 1 : -1));
+    const sorted = [...closeouts].sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0));
     const rows = sorted.map((c) => {
         const phase = getPhase(inputs.pipeline, c.phaseOrModule);
         const outputs = inputs.outputsPresent.get(c.phaseOrModule);
@@ -646,7 +648,7 @@ function getPhase(pipeline, phaseId) {
     return pipeline.phases.find((p) => p.id === phaseId);
 }
 function closeoutForPhase(closeouts, phaseId) {
-    return [...closeouts].filter((c) => c.phaseOrModule === phaseId).sort((a, b) => (a.date < b.date ? 1 : -1))[0];
+    return [...closeouts].filter((c) => c.phaseOrModule === phaseId).sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0))[0];
 }
 function phaseAnchor(phaseId) {
     return `phase-${phaseId.replace(/[^a-zA-Z0-9_-]/g, "-")}`;

package/dist/core/findings.d.ts

@@ -0,0 +1,59 @@
+/**
+ * First scaffold version whose defect templates offer `verify at runtime`.
+ * A workspace scaffolded before it had no honest action for an unsettled
+ * finding, so the pairing violation is reported as a warning there instead
+ * of failing a phase mid-run.
+ */
+export declare const FINDINGS_PAIRING_GATE_SCAFFOLD_VERSION = "0.17.1";
+/** Evidence levels that mean "not settled by reading this source". */
+export declare const UNSETTLED_EVIDENCE_LEVELS: ReadonlySet<string>;
+/** Actions that assert the diagnosis is settled enough to act on. */
+export declare const SETTLED_FIX_ACTIONS: ReadonlySet<string>;
+/** The pre-porting action an unsettled finding takes. */
+export declare const RUNTIME_VERIFY_ACTION = "verify at runtime";
+export type FindingRow = {
+    /** The `## Pass N` heading the table sits under, when there is one. */
+    pass: string | null;
+    /** The `#` cell, verbatim. */
+    number: string;
+    /** Normalized Evidence Level cell (lowercase, markup stripped). */
+    evidence: string;
+    /** Normalized Action cell. */
+    action: string;
+    /** 1-based line of the row in the document. */
+    line: number;
+};
+export type FindingsCrossCheck = {
+    /** Violations that fail validation on a current scaffold. */
+    errors: string[];
+    /** Non-gating observations, rendered as NOTE lines. */
+    warnings: string[];
+    findings: FindingRow[];
+};
+/**
+ * Every data row of every table whose header carries both an Evidence Level
+ * and an Action column. Placeholder rows (both cells empty) are skipped so an
+ * untouched template section contributes nothing.
+ */
+export declare function parseFindingsTables(content: string): FindingRow[];
+/** Whether the report has an `## Open Questions` table, and how many filled rows it holds. */
+export declare function parseOpenQuestionsTable(content: string): {
+    present: boolean;
+    rows: number;
+};
+/**
+ * Whether the pairing violation fails validation for this workspace. True from
+ * the scaffold version that introduced `verify at runtime`; an unversioned or
+ * older scaffold only warns.
+ */
+export declare function findingsPairingGateActive(scaffoldVersion: string | undefined | null): boolean;
+/**
+ * Run the cross-checks over a phase output. Returns empty results for any
+ * document without findings tables, so non-defect phases are untouched.
+ *
+ * @param content - The primary output's markdown.
+ * @param opts.gate - Whether the pairing violation is an error (current scaffold) or a warning.
+ */
+export declare function crossCheckFindings(content: string, opts: {
+    gate: boolean;
+}): FindingsCrossCheck;

package/dist/core/findings.js

@@ -0,0 +1,145 @@
+// Mechanical cross-checks over a defect report's findings tables (issue #122).
+//
+// A run can register an open question saying "source alone cannot determine
+// which" and, in the same run, ship one of that question's candidates as
+// `strong inference` / `fix before porting`. Both artifacts validate on their
+// own criteria because nothing reads what the evidence and action cells SAY.
+// The checks here do: they are deterministic reads of two cells the model
+// wrote itself, so the gating one cannot wedge an --auto run on a heuristic.
+//
+// The findings tables are header-identical across the three defect templates
+// (`| # | Location | Defect | Severity | Evidence Level | Action |`, with an
+// optional trailing Spec Reference), which is what makes a header-driven parse
+// a parse and not a guess. Any table without both an Evidence Level and an
+// Action column is left alone.
+import { compareDottedVersions } from "./utils.js";
+/**
+ * First scaffold version whose defect templates offer `verify at runtime`.
+ * A workspace scaffolded before it had no honest action for an unsettled
+ * finding, so the pairing violation is reported as a warning there instead
+ * of failing a phase mid-run.
+ */
+export const FINDINGS_PAIRING_GATE_SCAFFOLD_VERSION = "0.17.1";
+/** Evidence levels that mean "not settled by reading this source". */
+export const UNSETTLED_EVIDENCE_LEVELS = new Set(["open question", "external-behavior claim"]);
+/** Actions that assert the diagnosis is settled enough to act on. */
+export const SETTLED_FIX_ACTIONS = new Set(["fix before porting", "fix now"]);
+/** The pre-porting action an unsettled finding takes. */
+export const RUNTIME_VERIFY_ACTION = "verify at runtime";
+function normalizeCell(cell) {
+    return cell.replace(/[`*_]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
+}
+function isTableRow(line) {
+    return line.trim().startsWith("|");
+}
+function isSeparatorRow(line) {
+    return /^\s*\|?\s*:?-{3,}/.test(line);
+}
+function splitRow(line) {
+    const trimmed = line.trim();
+    const inner = trimmed.slice(1, trimmed.endsWith("|") ? -1 : undefined);
+    return inner.split("|").map((cell) => cell.trim());
+}
+/**
+ * Every data row of every table whose header carries both an Evidence Level
+ * and an Action column. Placeholder rows (both cells empty) are skipped so an
+ * untouched template section contributes nothing.
+ */
+export function parseFindingsTables(content) {
+    const lines = content.split(/\r?\n/);
+    const rows = [];
+    let pass = null;
+    for (let i = 0; i < lines.length; i++) {
+        const heading = /^##\s+Pass\s+(\d+)\b/i.exec(lines[i]);
+        if (heading) {
+            pass = heading[1];
+            continue;
+        }
+        if (!isTableRow(lines[i]) || !isSeparatorRow(lines[i + 1] ?? ""))
+            continue;
+        const header = splitRow(lines[i]).map(normalizeCell);
+        const evidenceIdx = header.indexOf("evidence level");
+        const actionIdx = header.indexOf("action");
+        const numberIdx = header.indexOf("#");
+        if (evidenceIdx < 0 || actionIdx < 0)
+            continue;
+        for (let j = i + 2; j < lines.length && isTableRow(lines[j]); j++) {
+            const cells = splitRow(lines[j]);
+            const evidence = normalizeCell(cells[evidenceIdx] ?? "");
+            const action = normalizeCell(cells[actionIdx] ?? "");
+            if (!evidence && !action)
+                continue;
+            rows.push({ pass, number: numberIdx >= 0 ? (cells[numberIdx] ?? "").trim() : "", evidence, action, line: j + 1 });
+            i = j;
+        }
+    }
+    return rows;
+}
+/** Whether the report has an `## Open Questions` table, and how many filled rows it holds. */
+export function parseOpenQuestionsTable(content) {
+    const lines = content.split(/\r?\n/);
+    const start = lines.findIndex((line) => /^##\s+Open Questions\s*$/i.test(line));
+    if (start < 0)
+        return { present: false, rows: 0 };
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^##\s/.test(lines[i]))
+            break; // next section, no table
+        if (!isTableRow(lines[i]) || !isSeparatorRow(lines[i + 1] ?? ""))
+            continue;
+        let rows = 0;
+        for (let j = i + 2; j < lines.length && isTableRow(lines[j]); j++) {
+            if (splitRow(lines[j]).some((cell) => cell.length > 0))
+                rows++;
+        }
+        return { present: true, rows };
+    }
+    return { present: true, rows: 0 };
+}
+/**
+ * Whether the pairing violation fails validation for this workspace. True from
+ * the scaffold version that introduced `verify at runtime`; an unversioned or
+ * older scaffold only warns.
+ */
+export function findingsPairingGateActive(scaffoldVersion) {
+    if (!scaffoldVersion)
+        return false;
+    const comparison = compareDottedVersions(scaffoldVersion, FINDINGS_PAIRING_GATE_SCAFFOLD_VERSION);
+    return comparison !== null && comparison >= 0;
+}
+function describe(row) {
+    const where = row.pass ? `Pass ${row.pass} finding #${row.number || "?"}` : `finding #${row.number || "?"}`;
+    return `${where} (line ${row.line})`;
+}
+/**
+ * Run the cross-checks over a phase output. Returns empty results for any
+ * document without findings tables, so non-defect phases are untouched.
+ *
+ * @param content - The primary output's markdown.
+ * @param opts.gate - Whether the pairing violation is an error (current scaffold) or a warning.
+ */
+export function crossCheckFindings(content, opts) {
+    const findings = parseFindingsTables(content);
+    const errors = [];
+    const warnings = [];
+    if (findings.length === 0)
+        return { errors, warnings, findings };
+    for (const row of findings) {
+        if (UNSETTLED_EVIDENCE_LEVELS.has(row.evidence) && SETTLED_FIX_ACTIONS.has(row.action)) {
+            const message = `${describe(row)}: evidence level "${row.evidence}" cannot carry the settled action "${row.action}" — ` +
+                `use "${RUNTIME_VERIFY_ACTION}" or "port differently" ("investigate" on maintenance pipelines), and list the finding under ## Open Questions.`;
+            if (opts.gate)
+                errors.push(message);
+            else
+                warnings.push(`${message} Warning only: this workspace's scaffold predates the verify-at-runtime vocabulary — refresh it to make this gating.`);
+        }
+        if (row.evidence === "observed fact" && row.action === RUNTIME_VERIFY_ACTION) {
+            warnings.push(`${describe(row)}: "observed fact" paired with "${RUNTIME_VERIFY_ACTION}" contradicts itself — a settled label with an unsettled action. Pick the one that is true.`);
+        }
+    }
+    const unsettled = findings.filter((row) => UNSETTLED_EVIDENCE_LEVELS.has(row.evidence) || row.action === RUNTIME_VERIFY_ACTION);
+    const openQuestions = parseOpenQuestionsTable(content);
+    if (unsettled.length > 0 && openQuestions.present && openQuestions.rows === 0) {
+        warnings.push(`${unsettled.length} unsettled finding(s) but the ## Open Questions table is empty — each open question / external-behavior claim finding needs a row there so the hedge travels with the finding, not only with the handoff.`);
+    }
+    return { errors, warnings, findings };
+}

package/dist/core/index.d.ts

@@ -4,6 +4,7 @@ export * from "./yaml.ts";
 export * from "./status.ts";
 export * from "./amendment.ts";
 export * from "./pipeline.ts";
+export * from "./findings.ts";
 export * from "./prompts.ts";
 export * from "./workspace.ts";
 export * from "./completion.ts";
@@ -13,3 +14,4 @@ export * from "./guide.ts";
 export * from "./dashboard.ts";
 export * from "./library.ts";
 export * from "./synthesis.ts";
+export * from "./broadside.ts";

package/dist/core/index.js

@@ -7,6 +7,7 @@ export * from "./yaml.js";
 export * from "./status.js";
 export * from "./amendment.js";
 export * from "./pipeline.js";
+export * from "./findings.js";
 export * from "./prompts.js";
 export * from "./workspace.js";
 export * from "./completion.js";
@@ -16,3 +17,4 @@ export * from "./guide.js";
 export * from "./dashboard.js";
 export * from "./library.js";
 export * from "./synthesis.js";
+export * from "./broadside.js";

package/dist/core/library.d.ts

@@ -75,9 +75,39 @@ export interface LibraryIndex {
     namespaces: string[];
     entries: LibraryIndexEntry[];
 }
+/** One older version whose recorded source_repo names a different repository than the newest version's. */
+export interface ProvenanceConflictVersion {
+    version: number;
+    source_repo: string;
+}
+/** An entry whose version history spans more than one repository. */
+export interface ProvenanceConflict {
+    slug: string;
+    namespace?: string;
+    /** The newest version — the one whose metadata the index reports for the whole entry. */
+    latest_version: number;
+    /** The source_repo recorded on the newest version, i.e. what index.yaml advertises. */
+    source_repo: string;
+    /** Older versions that disagree with it, ascending. Versions with missing or unreadable metadata are skipped. */
+    disagreeing_versions: ProvenanceConflictVersion[];
+}
+/**
+ * What `reindex` returns: the index it wrote, plus findings that ride on the
+ * return value only. `provenance_conflicts` is never serialized into
+ * index.yaml or INDEX.md — both shapes are ABI (docs/library-format.md).
+ */
+export interface ReindexResult extends LibraryIndex {
+    provenance_conflicts: ProvenanceConflict[];
+}
 export declare function discoverLibrary(libraryPath: string): Promise<LibraryMarker | null>;
 export declare function readMarker(libraryRoot: string): Promise<LibraryMarker | null>;
 export declare function writeMarker(libraryRoot: string, marker: LibraryMarker): Promise<void>;
+/**
+ * The level a marker's `visibility` or an entry's `confidentiality` is taken
+ * to have when it declares none. It is the default `initLibrary` writes and
+ * the default docs/library-format.md gives the entry field.
+ */
+export declare const DEFAULT_VISIBILITY: LibraryVisibility;
 export interface InitLibraryOptions {
     /** Library name (defaults to basename of the path). */
     name?: string;
@@ -108,6 +138,20 @@ export declare function isValidSlug(slug: string): boolean;
  * to ask the user about it.
  */
 export declare function deriveSlug(sourceRepo: string): string;
+/**
+ * Reduce a repo reference to a comparable form so that spellings of the same
+ * repository do not read as different projects. Handles scheme, `git@host:path`
+ * SCP syntax, a `www.` host prefix, a trailing `.git`, repeated and trailing
+ * slashes, backslash separators, and case.
+ *
+ * This is deliberately conservative: it only collapses spellings that are
+ * unambiguously the same target. Anything it cannot prove equivalent stays
+ * distinct, because the caller treats "different" as a hard error. Case is the
+ * one place that cuts the other way — see the note above the return.
+ */
+export declare function normalizeSourceRepo(sourceRepo: string): string;
+/** True when two repo references denote the same repository. */
+export declare function sameSourceRepo(a: string, b: string): boolean;
 export interface PublishInput {
     slug: string;
     namespace?: string;
@@ -131,6 +175,23 @@ export interface PublishOptions {
     forceNewVersion?: boolean;
     /** Skip the regen of index.yaml + INDEX.md (caller will batch). */
     skipReindex?: boolean;
+    /**
+     * Permit publishing when the target entry's recorded `source_repo` differs
+     * from the incoming one. Off by default: a mismatch usually means two
+     * different projects derived the same slug, and continuing would append
+     * one project's spec to the other's version history. Set this only when
+     * the repository genuinely moved (rename, org transfer, host change).
+     */
+    allowSourceRepoChange?: boolean;
+    /**
+     * Permit publishing when the entry's `confidentiality` is more restricted
+     * than the library's `visibility` — an `internal` entry into a `shared` or
+     * `public` library, a `shared` entry into a `public` one. Off by default:
+     * that direction exposes the spec to everyone the library reaches. Set
+     * this only when the exposure is intended. It does not change the
+     * confidentiality recorded on the entry.
+     */
+    allowConfidentialityMismatch?: boolean;
 }
 export interface PublishResult {
     slug: string;
@@ -140,6 +201,17 @@ export interface PublishResult {
     entryDir: string;
     versionDir: string;
 }
+/**
+ * Thrown by `publishEntry` when the entry is more restricted than the library
+ * it is headed for. Nothing has been written when this is raised. It carries
+ * the two compared levels so a wrapper with a user to ask (Pi) can pose the
+ * question from the values rather than by matching the message.
+ */
+export declare class ConfidentialityMismatchError extends Error {
+    readonly entryConfidentiality: LibraryVisibility;
+    readonly libraryVisibility: LibraryVisibility;
+    constructor(message: string, entryConfidentiality: LibraryVisibility, libraryVisibility: LibraryVisibility);
+}
 export declare function publishEntry(libraryRoot: string, spec: string, input: PublishInput, opts?: PublishOptions): Promise<PublishResult>;
 export interface EntryRef {
     slug: string;
@@ -160,7 +232,22 @@ export interface ListEntriesFilter {
     source_repo?: string;
 }
 export declare function listEntries(libraryRoot: string, filter?: ListEntriesFilter): Promise<LibraryIndexEntry[]>;
-export declare function reindex(libraryRoot: string): Promise<LibraryIndex>;
+export declare function reindex(libraryRoot: string): Promise<ReindexResult>;
+/**
+ * Read-only check over the given entries: does every version of each entry
+ * record the same repository as its newest version? Comparison goes through
+ * `sameSourceRepo`, so spellings of one repository (scheme, `.git`, SCP
+ * syntax, casing where safe) do not count as disagreement. A version whose
+ * metadata is missing, unreadable, or lacks `source_repo` is skipped rather
+ * than reported — the stance the publish guard takes — and an entry whose
+ * newest version is unreadable is skipped entirely, since there is nothing to
+ * compare against. Never writes.
+ *
+ * A repository that genuinely moved and was re-published with
+ * `allowSourceRepoChange` leaves the same on-disk shape as a collision and is
+ * reported the same way; the history alone cannot tell the two apart.
+ */
+export declare function detectProvenanceConflicts(libraryRoot: string, entries: ReadonlyArray<Pick<LibraryIndexEntry, "slug" | "namespace">>): Promise<ProvenanceConflict[]>;
 export interface CommitOptions {
     addAll?: boolean;
 }