codecartographer-pi 0.17.0 → 0.18.0

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;
@@ -106,6 +136,11 @@ export declare function isValidSlug(slug: string): boolean;
  * Caller is responsible for collision handling — derived slugs may already
  * exist in the library and the calling UX (Pi or MCP) is the right place
  * to ask the user about it.
+ *
+ * A clone's remote URL and its checkout directory derive the same slug
+ * (`…/whisper.git`, `git@host:acme/whisper`, and `/path/whisper` all give
+ * `whisper`), which is what lets the Pi command switch from recording the
+ * directory to recording the remote without renaming anyone's entry.
  */
 export declare function deriveSlug(sourceRepo: string): string;
 /**
@@ -153,6 +188,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 +206,52 @@ 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);
+}
+/**
+ * Thrown by `publishEntry` when the target entry's newest version records a
+ * `source_repo` that denotes a different repository than the incoming one.
+ * Nothing has been written when this is raised. It carries both values so a
+ * wrapper with a user to ask (Pi) can pose "did the repository move?" from
+ * the values rather than by matching the message.
+ */
+export declare class SourceRepoMismatchError extends Error {
+    /** The `source_repo` the entry's newest version records. */
+    readonly recorded: string;
+    /** The `source_repo` this publish carries. */
+    readonly incoming: string;
+    constructor(message: string, recorded: string, incoming: string);
+}
+/** What `publishEntry` would do to an entry's version history, without doing it. */
+export interface PublishVersionPreview {
+    /** Highest version directory present, or 0 for a new entry. */
+    latestVersion: number;
+    /** The version the publish would write or update. */
+    version: number;
+    /** True when a new version directory would be created; false for a metadata-only update. */
+    isNewVersion: boolean;
+}
+/**
+ * Read-only preview of the version a publish would land on. This is the same
+ * content-hash decision `publishEntry` makes (it calls this), so a wrapper
+ * that has to describe a publish before performing it — the MCP server's
+ * `publish_confirm` refusal — shows what would actually happen. Neither the
+ * collision nor the confidentiality guard is evaluated here; those still run
+ * on the real publish.
+ */
+export declare function previewPublishVersion(libraryRoot: string, spec: string, ref: {
+    slug: string;
+    namespace?: string;
+}, opts?: Pick<PublishOptions, "forceNewVersion">): Promise<PublishVersionPreview>;
 export declare function publishEntry(libraryRoot: string, spec: string, input: PublishInput, opts?: PublishOptions): Promise<PublishResult>;
 export interface EntryRef {
     slug: string;
@@ -182,7 +272,55 @@ 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[]>;
+/** What a Pi publish records as `source_repo`, and where the value came from. */
+export interface ResolvedSourceRepo {
+    /** The value to record: a remote's fetch URL verbatim, or the directory itself. */
+    source_repo: string;
+    /**
+     * The git remote the URL was read from (`origin`, or the current branch's
+     * upstream remote), or null when the directory was recorded instead — it
+     * is not a git work tree, is a subdirectory of one, or has no usable
+     * remote.
+     */
+    remote: string | null;
+}
+/**
+ * Resolve the repository reference a publish from `cwd` should record. The
+ * remote is preferred over the path because a path means nothing outside the
+ * machine that published it, and because a slug derived from the remote is
+ * stable across clones of one repository, which is what lets the collision
+ * guard compare something meaningful (#147).
+ *
+ * Resolution order: `origin`'s fetch URL, else the fetch URL of the remote
+ * the current branch tracks, else `cwd`. The remote is consulted only when
+ * `cwd` is the root of its work tree. A subdirectory keeps recording its
+ * path: every subdirectory of one repository would otherwise resolve to the
+ * same URL and the same slug, and the second one published would land as a
+ * new version of the first with no guard able to tell — exactly the
+ * cross-project append the guard exists to refuse.
+ *
+ * The URL is stored as git reports it. Spellings of one repository are
+ * reconciled at comparison time by `sameSourceRepo`, not here, so the
+ * recorded value stays human-readable. Never throws: a missing `git` binary
+ * or any git failure falls back to the path.
+ */
+export declare function resolvePublishSourceRepo(cwd: string): Promise<ResolvedSourceRepo>;
 export interface CommitOptions {
     addAll?: boolean;
 }

package/dist/core/library.js

@@ -15,18 +15,24 @@
 //  - 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.
-//  - Git operations (`commitPublish`) shell out to the `git` binary.
-//    Failures are non-fatal — the caller decides how to surface them.
+//  - 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`, `resolvePublishSourceRepo`) shell out
+//    to the `git` binary. Failures are non-fatal — the caller decides how to
+//    surface them, and the resolver falls back to the directory itself.
 import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
 import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
-import { isPlainObject, pathExists } from "./utils.js";
+import { canonicalPath, isPlainObject, normalizeForComparison, pathExists } from "./utils.js";
 import { parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
 // ─── Constants ──────────────────────────────────────────────────────────────
 export const LIBRARY_MARKER_FILE = ".codecarto-library";
@@ -86,6 +92,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 +118,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);
@@ -122,9 +138,19 @@ export function isValidSlug(slug) {
  * Caller is responsible for collision handling — derived slugs may already
  * exist in the library and the calling UX (Pi or MCP) is the right place
  * to ask the user about it.
+ *
+ * A clone's remote URL and its checkout directory derive the same slug
+ * (`…/whisper.git`, `git@host:acme/whisper`, and `/path/whisper` all give
+ * `whisper`), which is what lets the Pi command switch from recording the
+ * directory to recording the remote without renaming anyone's entry.
  */
 export function deriveSlug(sourceRepo) {
-    const cleaned = sourceRepo.replace(/\.git$/i, "").replace(/\\/g, "/");
+    let cleaned = sourceRepo.replace(/\.git$/i, "").replace(/\\/g, "/");
+    // SCP shorthand for a repository at the root of a host (`git@host:whisper`)
+    // has no slash at all, so the colon is the only separator to split on. Any
+    // form with a slash already yields the right trailing segment below.
+    if (!cleaned.includes("/"))
+        cleaned = cleaned.replace(/^[^:]*:/, "");
     const parts = cleaned.split("/").filter((p) => p.length > 0);
     const last = parts[parts.length - 1] ?? "entry";
     const slug = last
@@ -180,8 +206,10 @@ export function normalizeSourceRepo(sourceRepo) {
     // Windows drive paths. A POSIX absolute path is not: /srv/Repos/tool and
     // /srv/repos/tool are two directories on Linux, and folding them together
     // would hide exactly the cross-project collision this comparison exists to
-    // catch. Pi records the analyzed directory as source_repo, so local paths
-    // are a common case here rather than a curiosity.
+    // catch. Pi records the analyzed directory as source_repo whenever it has
+    // no git remote to record instead, and every entry Pi published before it
+    // resolved remotes holds one, so local paths are a common case here rather
+    // than a curiosity.
     return isCaseSensitivePath(s) ? s : s.toLowerCase();
 }
 /** An absolute POSIX path (or a `~` home reference), where case is significant. */
@@ -193,10 +221,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 +242,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 +302,64 @@ 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;
+    }
+}
+/**
+ * Thrown by `publishEntry` when the target entry's newest version records a
+ * `source_repo` that denotes a different repository than the incoming one.
+ * Nothing has been written when this is raised. It carries both values so a
+ * wrapper with a user to ask (Pi) can pose "did the repository move?" from
+ * the values rather than by matching the message.
+ */
+export class SourceRepoMismatchError extends Error {
+    /** The `source_repo` the entry's newest version records. */
+    recorded;
+    /** The `source_repo` this publish carries. */
+    incoming;
+    constructor(message, recorded, incoming) {
+        super(message);
+        this.name = "SourceRepoMismatchError";
+        this.recorded = recorded;
+        this.incoming = incoming;
+    }
+}
+/**
+ * Read-only preview of the version a publish would land on. This is the same
+ * content-hash decision `publishEntry` makes (it calls this), so a wrapper
+ * that has to describe a publish before performing it — the MCP server's
+ * `publish_confirm` refusal — shows what would actually happen. Neither the
+ * collision nor the confidentiality guard is evaluated here; those still run
+ * on the real publish.
+ */
+export async function previewPublishVersion(libraryRoot, spec, ref, opts = {}) {
+    const entryDir = entryRoot(libraryRoot, ref.namespace, ref.slug);
+    const existingVersions = await listVersionDirs(entryDir);
+    const latestVersion = existingVersions.length === 0 ? 0 : existingVersions[existingVersions.length - 1];
+    if (latestVersion > 0 && !opts.forceNewVersion) {
+        const latestSpecPath = join(versionDir(libraryRoot, ref.namespace, ref.slug, latestVersion), SPEC_FILE);
+        if (await pathExists(latestSpecPath)) {
+            const existingSpec = await readFile(latestSpecPath, "utf8");
+            if (sha256(existingSpec) === sha256(spec)) {
+                return { latestVersion, version: latestVersion, isNewVersion: false };
+            }
+        }
+    }
+    return { latestVersion, version: latestVersion + 1, isNewVersion: true };
+}
 export async function publishEntry(libraryRoot, spec, input, opts = {}) {
     const marker = await readMarker(libraryRoot);
     if (!marker) {
@@ -272,9 +379,8 @@ export async function publishEntry(libraryRoot, spec, input, opts = {}) {
     }
     const namespace = input.namespace;
     const entryDir = entryRoot(libraryRoot, namespace, input.slug);
-    const existingVersions = await listVersionDirs(entryDir);
-    const latestVersion = existingVersions.length === 0 ? 0 : existingVersions[existingVersions.length - 1];
-    const newSpecHash = sha256(spec);
+    const preview = await previewPublishVersion(libraryRoot, spec, { slug: input.slug, namespace }, opts);
+    const latestVersion = preview.latestVersion;
     // Collision guard. Slugs derive from the trailing path segment of the source
     // repo, so two unrelated projects (acme/whisper and openai/whisper) collapse
     // onto one slug. Without this check the second publish would append its spec
@@ -286,39 +392,61 @@ export async function publishEntry(libraryRoot, spec, input, opts = {}) {
         const recorded = await readRecordedSourceRepo(libraryRoot, namespace, input.slug, latestVersion);
         if (recorded !== null && !sameSourceRepo(recorded, input.source_repo)) {
             const label = namespace ? `${namespace}/${input.slug}` : input.slug;
-            throw new Error(`Refusing to publish: entry "${label}" v${latestVersion} records source_repo ` +
+            throw new SourceRepoMismatchError(`Refusing to publish: entry "${label}" v${latestVersion} records source_repo ` +
                 `"${recorded}", but this publish carries "${input.source_repo}". Publishing would ` +
                 `append this spec to a different project's version history. Publish this project ` +
                 `under a distinct slug to shelve it separately, or — if the repository itself ` +
                 `moved (rename, org transfer, host change) — re-publish with the source-repo ` +
                 `change allowed: allow_source_repo_change on codecarto_publish, ` +
-                `allowSourceRepoChange in PublishOptions.`);
+                `allowSourceRepoChange in PublishOptions.`, recorded, input.source_repo);
         }
     }
-    // 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) {
+    // 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
+    // (decided by previewPublishVersion above), update metadata in place and
+    // return without bumping the version.
+    if (!preview.isNewVersion) {
         const latestVersionDir = versionDir(libraryRoot, namespace, input.slug, latestVersion);
-        const latestSpecPath = join(latestVersionDir, SPEC_FILE);
-        if (await pathExists(latestSpecPath)) {
-            const existingSpec = await readFile(latestSpecPath, "utf8");
-            if (sha256(existingSpec) === newSpecHash) {
-                const metadata = buildMetadata(input, latestVersion);
-                await atomicWriteYaml(join(latestVersionDir, METADATA_FILE), metadata);
-                if (!opts.skipReindex)
-                    await reindex(libraryRoot);
-                return {
-                    slug: input.slug,
-                    namespace,
-                    version: latestVersion,
-                    isNewVersion: false,
-                    entryDir,
-                    versionDir: latestVersionDir,
-                };
-            }
-        }
+        // 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);
+        return {
+            slug: input.slug,
+            namespace,
+            version: latestVersion,
+            isNewVersion: false,
+            entryDir,
+            versionDir: latestVersionDir,
+        };
     }
-    const nextVersion = latestVersion + 1;
+    const nextVersion = preview.version;
     const finalVersionDir = versionDir(libraryRoot, namespace, input.slug, nextVersion);
     const stagingDir = `${entryDir}.publish.${process.pid}.${Date.now()}`;
     // Stage all files under a sibling directory, then atomically rename it
@@ -605,7 +733,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 +818,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 +859,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 +875,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`;
@@ -748,6 +950,55 @@ async function atomicWriteYaml(path, value) {
 function sha256(content) {
     return createHash("sha256").update(content, "utf8").digest("hex");
 }
+/**
+ * Resolve the repository reference a publish from `cwd` should record. The
+ * remote is preferred over the path because a path means nothing outside the
+ * machine that published it, and because a slug derived from the remote is
+ * stable across clones of one repository, which is what lets the collision
+ * guard compare something meaningful (#147).
+ *
+ * Resolution order: `origin`'s fetch URL, else the fetch URL of the remote
+ * the current branch tracks, else `cwd`. The remote is consulted only when
+ * `cwd` is the root of its work tree. A subdirectory keeps recording its
+ * path: every subdirectory of one repository would otherwise resolve to the
+ * same URL and the same slug, and the second one published would land as a
+ * new version of the first with no guard able to tell — exactly the
+ * cross-project append the guard exists to refuse.
+ *
+ * The URL is stored as git reports it. Spellings of one repository are
+ * reconciled at comparison time by `sameSourceRepo`, not here, so the
+ * recorded value stays human-readable. Never throws: a missing `git` binary
+ * or any git failure falls back to the path.
+ */
+export async function resolvePublishSourceRepo(cwd) {
+    const asPath = { source_repo: cwd, remote: null };
+    try {
+        const toplevel = await runGit(cwd, ["rev-parse", "--show-toplevel"]);
+        if (!toplevel.ok || toplevel.stdout.trim() === "")
+            return asPath;
+        const [canonicalCwd, canonicalTop] = await Promise.all([canonicalPath(cwd), canonicalPath(toplevel.stdout.trim())]);
+        if (normalizeForComparison(canonicalCwd) !== normalizeForComparison(canonicalTop))
+            return asPath;
+        const origin = await runGit(cwd, ["remote", "get-url", "origin"]);
+        if (origin.ok && origin.stdout.trim() !== "")
+            return { source_repo: origin.stdout.trim(), remote: "origin" };
+        const branch = await runGit(cwd, ["symbolic-ref", "--short", "HEAD"]);
+        if (!branch.ok || branch.stdout.trim() === "")
+            return asPath;
+        const upstream = await runGit(cwd, ["config", "--get", `branch.${branch.stdout.trim()}.remote`]);
+        const remote = upstream.stdout.trim();
+        // `.` marks a branch tracking another local branch; there is no URL behind it.
+        if (!upstream.ok || remote === "" || remote === ".")
+            return asPath;
+        const url = await runGit(cwd, ["remote", "get-url", remote]);
+        if (url.ok && url.stdout.trim() !== "")
+            return { source_repo: url.stdout.trim(), remote };
+        return asPath;
+    }
+    catch {
+        return asPath;
+    }
+}
 /**
  * Optional convenience: stage and commit publish output. Never pushes.
  * On any failure, returns `{ ok: false, skipped: <reason> }` rather than

package/dist/core/orchestrator-config.d.ts

@@ -17,6 +17,12 @@ export interface LibraryConfig {
     /** Whether `codecarto publish` should display a confirmation prompt
      *  with slug + source + library path before writing. Default true. */
     publish_confirm: boolean;
+    /** True when some config layer set `publish_confirm`; false when the
+     *  default above supplied it. Pi confirms either way (a dialog costs
+     *  nothing), but the MCP server's refuse-unless-confirmed gate on
+     *  `codecarto_publish` costs every host a round trip, so it applies only
+     *  to hosts that actually configured the key. */
+    publish_confirm_configured: boolean;
 }
 export interface CodecartoConfig {
     orchestrator: OrchestratorConfig;

package/dist/core/orchestrator-config.js

@@ -38,6 +38,7 @@ const DEFAULT_CONFIG = {
         path: null,
         namespace: null,
         publish_confirm: true,
+        publish_confirm_configured: false,
     },
 };
 export async function loadCodecartoConfig(workspaceDir) {
@@ -101,6 +102,7 @@ function applyRaw(base, raw) {
         }
         if (typeof l.publish_confirm === "boolean") {
             out.library.publish_confirm = l.publish_confirm;
+            out.library.publish_confirm_configured = true;
         }
     }
     return out;