codecartographer-pi 0.17.0 → 0.17.1

package/dist/core/completion.js

@@ -2,7 +2,7 @@ import { appendFile, copyFile, mkdir, readFile, readdir, writeFile } from "node:
 import { join } from "node:path";
 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;
@@ -343,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";

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";

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;
@@ -153,6 +183,15 @@ export interface PublishOptions {
      * 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;
@@ -162,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;
@@ -182,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;
 }

package/dist/core/library.js

@@ -15,11 +15,16 @@
 //  - publishEntry is content-hash idempotent: re-publishing the same
 //    spec bytes does not create a new version. Metadata-only changes
 //    (headline, tags, capabilities) update the existing latest
-//    metadata.yaml in place.
+//    metadata.yaml in place; the version's recorded provenance is
+//    carried forward unless the publish supplies its own.
 //  - reindex regenerates index.yaml and INDEX.md from filesystem state.
 //    Treat both as derived artifacts; never hand-edit. Resolution
 //    recipe for git merge conflicts is documented in
 //    docs/library-format.md.
+//  - reindex also reports, on its return value and never in the index
+//    files, entries whose versions disagree about source_repo — the shape
+//    a slug collision left behind before publish refused cross-project
+//    appends. Repair is manual; see the "Provenance conflicts" section.
 //  - Git operations (`commitPublish`) shell out to the `git` binary.
 //    Failures are non-fatal — the caller decides how to surface them.
 import { createHash } from "node:crypto";
@@ -86,6 +91,16 @@ function normalizeMarker(raw) {
 function isVisibility(v) {
     return v === "internal" || v === "shared" || v === "public";
 }
+/**
+ * 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 const DEFAULT_VISIBILITY = "internal";
+// Ordered from most to least restricted. An entry may sit in a library at or
+// below its own level; one above it would expose the entry to everyone the
+// library reaches.
+const VISIBILITY_RANK = { internal: 0, shared: 1, public: 2 };
 /**
  * Initialize a CodeCartographer library at the given path: create the
  * directory if needed, write the `.codecarto-library` marker if missing,
@@ -102,7 +117,7 @@ export async function initLibrary(libraryPath, options = {}) {
         schema_version: MARKER_SCHEMA_VERSION,
         name,
         namespaced: options.namespaced ?? false,
-        visibility: options.visibility ?? "internal",
+        visibility: options.visibility ?? DEFAULT_VISIBILITY,
         created_at: new Date().toISOString(),
     };
     await writeMarker(libraryPath, marker);
@@ -193,10 +208,11 @@ export function sameSourceRepo(a, b) {
     return normalizeSourceRepo(a) === normalizeSourceRepo(b);
 }
 /**
- * The `source_repo` recorded on an entry's newest version, or null when it
+ * The `source_repo` recorded on one version of an entry, or null when it
  * cannot be determined (no metadata, unreadable, or malformed). Null means
  * "unknown", and callers treat unknown as permission to proceed rather than
- * as a mismatch.
+ * as a mismatch — the publish guard lets the publish through, and conflict
+ * detection skips the version.
  */
 async function readRecordedSourceRepo(libraryRoot, namespace, slug, version) {
     const metaPath = join(versionDir(libraryRoot, namespace, slug, version), METADATA_FILE);
@@ -213,6 +229,26 @@ async function readRecordedSourceRepo(libraryRoot, namespace, slug, version) {
         return null;
     }
 }
+/**
+ * The `provenance` block recorded on one version of an entry, or undefined
+ * when there is none to carry forward (no metadata, unreadable, malformed,
+ * or a version that never had the block — a hand-built entry, say). The
+ * metadata-only publish branch uses this so an identical re-publish, which
+ * neither surface sends `provenance` with, rewrites `metadata.yaml` without
+ * dropping what the version's original publish recorded.
+ */
+async function readRecordedProvenance(libraryRoot, namespace, slug, version) {
+    const metaPath = join(versionDir(libraryRoot, namespace, slug, version), METADATA_FILE);
+    if (!(await pathExists(metaPath)))
+        return undefined;
+    try {
+        const raw = parseSimpleYaml(await readFile(metaPath, "utf8"));
+        return normalizeMetadata(raw, { slug, namespace, version }).provenance;
+    }
+    catch {
+        return undefined;
+    }
+}
 // ─── Path helpers ───────────────────────────────────────────────────────────
 function entryRoot(libraryRoot, namespace, slug) {
     return namespace ? join(libraryRoot, ENTRIES_DIR, namespace, slug) : join(libraryRoot, ENTRIES_DIR, slug);
@@ -253,6 +289,22 @@ async function readLatestPointer(entryDir) {
         return null;
     }
 }
+/**
+ * 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 class ConfidentialityMismatchError extends Error {
+    entryConfidentiality;
+    libraryVisibility;
+    constructor(message, entryConfidentiality, libraryVisibility) {
+        super(message);
+        this.name = "ConfidentialityMismatchError";
+        this.entryConfidentiality = entryConfidentiality;
+        this.libraryVisibility = libraryVisibility;
+    }
+}
 export async function publishEntry(libraryRoot, spec, input, opts = {}) {
     const marker = await readMarker(libraryRoot);
     if (!marker) {
@@ -295,6 +347,29 @@ export async function publishEntry(libraryRoot, spec, input, opts = {}) {
                 `allowSourceRepoChange in PublishOptions.`);
         }
     }
+    // Confidentiality guard. Levels are ordered internal < shared < public. An
+    // entry may sit in a library at or below its own level, but one more
+    // restricted than its library would be exposed to everyone the library
+    // reaches: an internal spec in a public library is a leak. Either side that
+    // declares nothing counts as internal — the marker default initLibrary
+    // writes, and the entry default docs/library-format.md documents — so a
+    // library with no visibility field accepts everything it did before. Like
+    // the collision guard this runs ahead of the idempotence branch, so a
+    // metadata-only update cannot reclassify an entry past it, and it fails
+    // before anything is written.
+    const entryConfidentiality = input.confidentiality ?? DEFAULT_VISIBILITY;
+    const libraryVisibility = marker.visibility ?? DEFAULT_VISIBILITY;
+    if (!opts.allowConfidentialityMismatch && VISIBILITY_RANK[entryConfidentiality] < VISIBILITY_RANK[libraryVisibility]) {
+        const label = namespace ? `${namespace}/${input.slug}` : input.slug;
+        const declared = input.confidentiality ? "" : " (the default when none is declared)";
+        throw new ConfidentialityMismatchError(`Refusing to publish: entry "${label}" has confidentiality "${entryConfidentiality}"${declared}, ` +
+            `but library "${marker.name}" has visibility "${libraryVisibility}". Publishing would expose a ` +
+            `spec classified "${entryConfidentiality}" to everyone the "${libraryVisibility}" library reaches. ` +
+            `Publish it to a library whose visibility is "${entryConfidentiality}" or narrower, declare a ` +
+            `confidentiality of "${libraryVisibility}" or wider if the spec may travel that far, or — if ` +
+            `this exposure is intended — re-publish with the mismatch allowed: ` +
+            `allow_confidentiality_mismatch on codecarto_publish, allowConfidentialityMismatch in PublishOptions.`, entryConfidentiality, libraryVisibility);
+    }
     // Content-hash idempotence: if the latest version's spec matches bytes-for-bytes,
     // update metadata in place and return without bumping the version.
     if (latestVersion > 0 && !opts.forceNewVersion) {
@@ -303,7 +378,11 @@ export async function publishEntry(libraryRoot, spec, input, opts = {}) {
         if (await pathExists(latestSpecPath)) {
             const existingSpec = await readFile(latestSpecPath, "utf8");
             if (sha256(existingSpec) === newSpecHash) {
-                const metadata = buildMetadata(input, latestVersion);
+                // buildMetadata writes provenance only when the input carries it, and
+                // neither surface sends it on publish — so without this the rewrite
+                // would drop the block the version's original publish recorded.
+                const provenance = input.provenance ?? (await readRecordedProvenance(libraryRoot, namespace, input.slug, latestVersion));
+                const metadata = buildMetadata({ ...input, provenance }, latestVersion);
                 await atomicWriteYaml(join(latestVersionDir, METADATA_FILE), metadata);
                 if (!opts.skipReindex)
                     await reindex(libraryRoot);
@@ -605,7 +684,10 @@ export async function reindex(libraryRoot) {
     };
     await atomicWriteYaml(join(libraryRoot, LIBRARY_INDEX_FILE), index);
     await writeIndexMarkdown(libraryRoot, index, marker);
-    return index;
+    // Reported, not written. The index files above are ABI, so the conflict
+    // list travels on the return value only (see ReindexResult).
+    const provenance_conflicts = await detectProvenanceConflicts(libraryRoot, entries);
+    return { ...index, provenance_conflicts };
 }
 async function buildIndexEntry(libraryRoot, namespace, slug) {
     const entryDir = entryRoot(libraryRoot, namespace, slug);
@@ -687,7 +769,10 @@ async function writeIndexMarkdown(libraryRoot, index, marker) {
     lines.push("");
     lines.push(`_Generated ${index.generated_at}. Do not edit by hand — regenerate with \`codecarto library-reindex\`._`);
     lines.push("");
-    lines.push(`**${index.entry_count} ${index.entry_count === 1 ? "entry" : "entries"}** across ${index.namespaces.length || 1} ${index.namespaces.length === 1 ? "namespace" : "namespaces"}.`);
+    // A single-tenant library has no namespaces but is still one namespace's
+    // worth of entries; count once so the noun agrees with the number shown.
+    const namespaceCount = index.namespaces.length || 1;
+    lines.push(`**${index.entry_count} ${index.entry_count === 1 ? "entry" : "entries"}** across ${namespaceCount} ${namespaceCount === 1 ? "namespace" : "namespaces"}.`);
     lines.push("");
     if (marker.namespaced) {
         const grouped = new Map();
@@ -725,7 +810,11 @@ async function writeIndexMarkdown(libraryRoot, index, marker) {
     await rename(tempPath, path);
 }
 function formatIndexRow(e, namespaced) {
-    const pathPart = namespaced && e.namespace ? `${ENTRIES_DIR}/${e.namespace}/${e.slug}/latest/` : `${ENTRIES_DIR}/${e.slug}/latest/`;
+    // Link to the newest version directory, not `latest/`: the pointer is a
+    // one-line regular file (see the module header), so a `latest/` link has
+    // nothing to land on when the library is browsed on a forge.
+    const entryPath = namespaced && e.namespace ? `${ENTRIES_DIR}/${e.namespace}/${e.slug}` : `${ENTRIES_DIR}/${e.slug}`;
+    const pathPart = `${entryPath}/v${e.latest_version}/`;
     const slugLink = `[${escapeMd(e.slug)}](${pathPart})`;
     const headline = escapeMd(e.headline).replace(/\n+/g, " ");
     const tags = e.tags.length === 0 ? "" : e.tags.map(escapeMd).join(", ");
@@ -737,6 +826,70 @@ function escapeMd(value) {
     // break out of the table cell (code scanning alert #3).
     return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
 }
+// ─── Provenance conflicts ───────────────────────────────────────────────────
+//
+// Before publish refused cross-project appends (#123), two projects whose
+// source_repo shared a trailing path segment derived the same slug, and the
+// second publish landed as the next version of the first project's entry.
+// Nothing rewrites those entries after the fact: the index reads only the
+// newest version's metadata, so it advertises every version under whichever
+// project published last, and a synthesis run reading the entry gets one
+// project's spec history presented as another's (#148). Detection reads every
+// version and reports the disagreement. Repair is deliberately manual —
+// splitting an entry means inventing a slug, renumbering versions and
+// repointing `latest`, all of which are paths docs/library-format.md calls
+// ABI — so nothing here renames, renumbers, or moves anything.
+/**
+ * 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 async function detectProvenanceConflicts(libraryRoot, entries) {
+    const conflicts = [];
+    for (const entry of entries) {
+        const conflict = await findProvenanceConflict(libraryRoot, entry.namespace, entry.slug);
+        if (conflict)
+            conflicts.push(conflict);
+    }
+    return conflicts;
+}
+async function findProvenanceConflict(libraryRoot, namespace, slug) {
+    const versions = await listVersionDirs(entryRoot(libraryRoot, namespace, slug));
+    if (versions.length < 2)
+        return null;
+    const latest = versions[versions.length - 1];
+    const latestRepo = await readRecordedSourceRepo(libraryRoot, namespace, slug, latest);
+    if (latestRepo === null)
+        return null;
+    const disagreeing = [];
+    for (const version of versions.slice(0, -1)) {
+        const recorded = await readRecordedSourceRepo(libraryRoot, namespace, slug, version);
+        if (recorded === null)
+            continue;
+        if (!sameSourceRepo(recorded, latestRepo))
+            disagreeing.push({ version, source_repo: recorded });
+    }
+    if (disagreeing.length === 0)
+        return null;
+    const conflict = {
+        slug,
+        latest_version: latest,
+        source_repo: latestRepo,
+        disagreeing_versions: disagreeing,
+    };
+    if (namespace)
+        conflict.namespace = namespace;
+    return conflict;
+}
 // ─── Atomic YAML write ──────────────────────────────────────────────────────
 async function atomicWriteYaml(path, value) {
     const serialized = `${stringifySimpleYaml(value)}\n`;