@mutmutco/cli 4.0.17 → 4.1.0

package/dist/repo-index-v4.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   REPO_INDEX_V4_SCHEMA: () => REPO_INDEX_V4_SCHEMA,
+  V4_DELTA_DEEPEN_STEPS: () => V4_DELTA_DEEPEN_STEPS,
   V4_GRAPH_MAX_EDGES: () => V4_GRAPH_MAX_EDGES,
   V4_GRAPH_MAX_EDGES_PER_FILE: () => V4_GRAPH_MAX_EDGES_PER_FILE,
   V4_MAX_ARTIFACT_BYTES: () => V4_MAX_ARTIFACT_BYTES,
@@ -39,10 +40,23 @@ __export(index_exports, {
   V4_STAGE_MAX_RECORDS: () => V4_STAGE_MAX_RECORDS,
   buildGraphEdges: () => buildGraphEdges,
   buildRepoIndexV4: () => buildRepoIndexV4,
+  buildRepoIndexV4Detailed: () => buildRepoIndexV4Detailed,
   buildStructuralChunks: () => buildStructuralChunks,
+  buildStructuralChunksForPaths: () => buildStructuralChunksForPaths,
+  canonicalRepoIndexPaths: () => canonicalRepoIndexPaths,
+  changedPaths: () => changedPaths,
+  compareV4Chunks: () => compareV4Chunks,
   encodedStageBytes: () => encodedStageBytes,
+  formatV4BuildMetrics: () => formatV4BuildMetrics,
+  gitRunner: () => gitRunner,
   graphEdgesForSource: () => graphEdgesForSource,
+  isRepoIndexDeltaCompatible: () => isRepoIndexDeltaCompatible,
   languageForPath: () => languageForPath,
+  parseNameStatusZ: () => parseNameStatusZ,
+  planRepoIndexV4Delta: () => planRepoIndexV4Delta,
+  readRepoIndexProvenance: () => readRepoIndexProvenance,
+  removedPaths: () => removedPaths,
+  repoIndexV4DeltaBase: () => repoIndexV4DeltaBase,
   repoIndexV4StorePath: () => repoIndexV4StorePath,
   shardRepoIndexV4: () => shardRepoIndexV4,
   structuralChunksForSource: () => structuralChunksForSource
@@ -50,10 +64,189 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/repo-index-v4/chunks.ts
-var import_node_crypto2 = require("node:crypto");
+var import_node_crypto3 = require("node:crypto");
 var import_node_fs2 = require("node:fs");
 var import_node_path3 = require("node:path");
 
+// ../infra/repo-index-path-policy.mjs
+var HARD_DENY = Object.freeze([
+  /(^|\/)\.env(\.|$)/i,
+  /(^|\/)\.env\./i,
+  /credentials/i,
+  /secrets?\.json$/i,
+  /\.pem$/i,
+  /\.p12$/i,
+  /\.key$/i,
+  /(^|\/)id_rsa/i,
+  /(^|\/)id_ed25519/i,
+  /\.keystore$/i
+]);
+function isHardDeniedRepoIndexPath(value) {
+  return typeof value !== "string" || HARD_DENY.some((pattern) => pattern.test(value));
+}
+function isSafeRepoIndexPath(value) {
+  if (typeof value !== "string" || !value || value.length > 1024) return false;
+  if (value.startsWith("/") || value.includes("\\") || /[\u0000-\u001f\u007f]/u.test(value)) return false;
+  const segments = value.split("/");
+  if (segments.some((segment) => !segment || segment === "." || segment === "..")) return false;
+  return !isHardDeniedRepoIndexPath(value);
+}
+var REPO_INDEX_ALGORITHM_VERSION = 1;
+var REPO_INDEX_FILTER_VERSION = 2;
+var REPO_INDEX_MATERIAL_LAYOUT_VERSION = 2;
+var LEGACY_REPO_INDEX_PROVENANCE = Object.freeze({
+  algorithmVersion: 1,
+  filterVersion: 1,
+  materialLayoutVersion: 1
+});
+var CURRENT_REPO_INDEX_PROVENANCE = Object.freeze({
+  algorithmVersion: REPO_INDEX_ALGORITHM_VERSION,
+  filterVersion: REPO_INDEX_FILTER_VERSION,
+  materialLayoutVersion: REPO_INDEX_MATERIAL_LAYOUT_VERSION
+});
+function repoIndexProvenanceToken(provenance = CURRENT_REPO_INDEX_PROVENANCE) {
+  const resolved = provenance && typeof provenance === "object" ? provenance : {};
+  return `a${resolved.algorithmVersion}-f${resolved.filterVersion}-l${resolved.materialLayoutVersion}`;
+}
+var CURRENT_REPO_INDEX_PROVENANCE_TOKEN = repoIndexProvenanceToken(CURRENT_REPO_INDEX_PROVENANCE);
+var GENERATED_PROJECTION = Object.freeze([
+  // Host plugin packages: the assembled skills/hooks/scripts/bin payload and the copied host
+  // manifest directory. `packages/<host>-plugin/<file>` at the root stays admitted.
+  /^packages\/(?:claude|codex|kimi|cursor|hermes)-plugin\/(?:skills|hooks|scripts|bin)\//,
+  /^packages\/(?:claude|codex|kimi|cursor|hermes)-plugin\/\.[A-Za-z0-9-]+-plugin\//,
+  // In-repo plugin roots assembled by the same declaration.
+  /^\.kilo-plugin\/(?:skills|scripts)\//,
+  /^\.pi-plugin\/(?:skills|scripts|extensions)\//,
+  // Release metadata regenerated from the tracked tree at every prepare.
+  /^distribution-bom\.json$/,
+  // Cross-repo generator outputs the estate audit named.
+  /^product\/connector\/generated\//,
+  /^packages\/jerv-pi\/generated\/roster\//,
+  /^docs\/\.release-inbox\//
+]);
+function isGeneratedRepoIndexProjection(value) {
+  return typeof value === "string" && GENERATED_PROJECTION.some((pattern) => pattern.test(value));
+}
+function isCanonicalRepoIndexPath(value) {
+  return isSafeRepoIndexPath(value) && !isGeneratedRepoIndexProjection(value);
+}
+function readRepoIndexProvenance(manifest) {
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) return null;
+  const provenance = manifest.indexProvenance;
+  if (provenance === void 0) return { ...LEGACY_REPO_INDEX_PROVENANCE };
+  if (!provenance || typeof provenance !== "object" || Array.isArray(provenance)) return null;
+  const keys = ["algorithmVersion", "filterVersion", "materialLayoutVersion"];
+  if (Object.keys(provenance).length !== keys.length) return null;
+  for (const key of keys) {
+    const value = provenance[key];
+    if (!Number.isInteger(value) || value < 1) return null;
+  }
+  return {
+    algorithmVersion: provenance.algorithmVersion,
+    filterVersion: provenance.filterVersion,
+    materialLayoutVersion: provenance.materialLayoutVersion
+  };
+}
+function isRepoIndexDeltaCompatible(manifest) {
+  const provenance = readRepoIndexProvenance(manifest);
+  return provenance !== null && provenance.algorithmVersion === REPO_INDEX_ALGORITHM_VERSION && provenance.filterVersion === REPO_INDEX_FILTER_VERSION && provenance.materialLayoutVersion === REPO_INDEX_MATERIAL_LAYOUT_VERSION;
+}
+
+// ../infra/repo-index-material-buckets.mjs
+var import_node_crypto = require("node:crypto");
+var REPO_INDEX_MATERIAL_BUCKET_COUNT = 2;
+var REPO_INDEX_MATERIAL_KINDS = Object.freeze(["chunks", "embeddings"]);
+var REPO_INDEX_MATERIAL_PREFIX = "material-v2";
+function canonicalMaterialJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalMaterialJson).join(",")}]`;
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalMaterialJson(value[key])}`).join(",")}}`;
+}
+function repoIndexMaterialDigest(value) {
+  return (0, import_node_crypto.createHash)("sha256").update(canonicalMaterialJson(value)).digest("hex");
+}
+function normalizeRepoIndexMaterialPath(path) {
+  return String(path).replace(/^\.\//, "").normalize("NFC");
+}
+function repoIndexMaterialBucket(path) {
+  const hash = (0, import_node_crypto.createHash)("sha256").update(normalizeRepoIndexMaterialPath(path), "utf8").digest();
+  return hash.readUInt32BE(0) % REPO_INDEX_MATERIAL_BUCKET_COUNT;
+}
+function compareRepoIndexChunks(a, b) {
+  const aPath = String(a?.path ?? "");
+  const bPath = String(b?.path ?? "");
+  if (aPath !== bPath) return aPath < bPath ? -1 : 1;
+  const aLine = Number(a?.citations?.[0]?.startLine ?? 0);
+  const bLine = Number(b?.citations?.[0]?.startLine ?? 0);
+  if (aLine !== bLine) return aLine - bLine;
+  const aId = String(a?.id ?? "");
+  const bId = String(b?.id ?? "");
+  return aId === bId ? 0 : aId < bId ? -1 : 1;
+}
+function compareRepoIndexEmbeddings(a, b) {
+  const aId = String(a?.chunkId ?? "");
+  const bId = String(b?.chunkId ?? "");
+  return aId === bId ? 0 : aId < bId ? -1 : 1;
+}
+function stripRepoIndexChunkCommit(chunk) {
+  const citations = Array.isArray(chunk?.citations) ? chunk.citations : [];
+  return {
+    ...chunk,
+    citations: citations.map((citation2) => {
+      const rest = { ...citation2 };
+      delete rest.commit;
+      return rest;
+    })
+  };
+}
+function repoIndexMaterialIndexKey(repoBase, digest) {
+  return `${repoBase}/${REPO_INDEX_MATERIAL_PREFIX}/index/${digest}.json`;
+}
+function repoIndexMaterialIndexUri(repo, digest) {
+  return `s3://${repoIndexMaterialIndexKey(`repo-index/v4/${repo}`, digest)}`;
+}
+function repoIndexMaterialBucketBody(kind, bucket, records) {
+  return { schemaVersion: 4, materialLayoutVersion: 2, kind, bucket, bucketCount: REPO_INDEX_MATERIAL_BUCKET_COUNT, count: records.length, records };
+}
+var bucketBody = repoIndexMaterialBucketBody;
+function buildRepoIndexMaterialLayout(repo, chunks, embeddings) {
+  const chunkList = Array.isArray(chunks) ? chunks : [];
+  const embeddingList = Array.isArray(embeddings) ? embeddings : [];
+  const pathByChunkId = new Map(chunkList.map((chunk) => [String(chunk?.id), String(chunk?.path)]));
+  const grouped = /* @__PURE__ */ new Map();
+  for (const kind of REPO_INDEX_MATERIAL_KINDS) {
+    for (let bucket = 0; bucket < REPO_INDEX_MATERIAL_BUCKET_COUNT; bucket++) grouped.set(`${kind}:${bucket}`, []);
+  }
+  for (const chunk of chunkList) {
+    grouped.get(`chunks:${repoIndexMaterialBucket(chunk?.path)}`).push(stripRepoIndexChunkCommit(chunk));
+  }
+  for (const embedding of embeddingList) {
+    const path = pathByChunkId.get(String(embedding?.chunkId));
+    if (path === void 0) throw new Error("repo-index material embeds a chunk that is not in the corpus");
+    grouped.get(`embeddings:${repoIndexMaterialBucket(path)}`).push(embedding);
+  }
+  const buckets = [];
+  for (const kind of REPO_INDEX_MATERIAL_KINDS) {
+    for (let bucket = 0; bucket < REPO_INDEX_MATERIAL_BUCKET_COUNT; bucket++) {
+      const records = grouped.get(`${kind}:${bucket}`);
+      records.sort(kind === "chunks" ? compareRepoIndexChunks : compareRepoIndexEmbeddings);
+      const body = bucketBody(kind, bucket, records);
+      buckets.push({ kind, bucket, count: records.length, digest: repoIndexMaterialDigest(body), body });
+    }
+  }
+  const index = {
+    schemaVersion: 4,
+    materialLayoutVersion: 2,
+    repo,
+    bucketCount: REPO_INDEX_MATERIAL_BUCKET_COUNT,
+    chunkCount: chunkList.length,
+    embeddingCount: embeddingList.length,
+    // Ordered descriptors: chunks buckets ascending, then embeddings buckets ascending.
+    buckets: buckets.map(({ kind, bucket, count, digest }) => ({ kind, bucket, count, digest }))
+  };
+  return { bucketCount: REPO_INDEX_MATERIAL_BUCKET_COUNT, buckets, index, indexDigest: repoIndexMaterialDigest(index) };
+}
+
 // src/doc-refs-core.ts
 var import_node_child_process = require("node:child_process");
 var CHECK_IGNORE_MAX_BUFFER = 32 * 1024 * 1024;
@@ -85,38 +278,14 @@ function defaultIsIgnored(root, relPaths, exec = import_node_child_process.execF
 var import_node_child_process2 = require("node:child_process");
 var import_node_path2 = require("node:path");
 
-// ../infra/repo-index-path-policy.mjs
-var HARD_DENY = Object.freeze([
-  /(^|\/)\.env(\.|$)/i,
-  /(^|\/)\.env\./i,
-  /credentials/i,
-  /secrets?\.json$/i,
-  /\.pem$/i,
-  /\.p12$/i,
-  /\.key$/i,
-  /(^|\/)id_rsa/i,
-  /(^|\/)id_ed25519/i,
-  /\.keystore$/i
-]);
-function isHardDeniedRepoIndexPath(value) {
-  return typeof value !== "string" || HARD_DENY.some((pattern) => pattern.test(value));
-}
-function isSafeRepoIndexPath(value) {
-  if (typeof value !== "string" || !value || value.length > 1024) return false;
-  if (value.startsWith("/") || value.includes("\\") || /[\u0000-\u001f\u007f]/u.test(value)) return false;
-  const segments = value.split("/");
-  if (segments.some((segment) => !segment || segment === "." || segment === "..")) return false;
-  return !isHardDeniedRepoIndexPath(value);
-}
-
 // src/repo-runtime-state.ts
-var import_node_crypto = require("node:crypto");
+var import_node_crypto2 = require("node:crypto");
 var import_node_fs = require("node:fs");
 var import_node_os = require("node:os");
 var import_node_path = require("node:path");
 var RUNTIME_DIR = "mmi-runtime";
 function hashPath(path) {
-  return (0, import_node_crypto.createHash)("sha256").update((0, import_node_path.resolve)(path)).digest("hex").slice(0, 16);
+  return (0, import_node_crypto2.createHash)("sha256").update((0, import_node_path.resolve)(path)).digest("hex").slice(0, 16);
 }
 function resolveGitDir(cwd) {
   const dotGit = (0, import_node_path.join)(cwd, ".git");
@@ -257,7 +426,7 @@ async function parserFor(language) {
   return parser;
 }
 function sha256(value) {
-  return (0, import_node_crypto2.createHash)("sha256").update(value).digest("hex");
+  return (0, import_node_crypto3.createHash)("sha256").update(value).digest("hex");
 }
 function pointerId(path, kind, contentHash, start, end, symbol) {
   return sha256(["repo-index-v4", path, kind, contentHash, String(start), String(end), symbol ?? ""].join("\0"));
@@ -345,12 +514,17 @@ async function structuralChunksForSource(repo, commit, path, source) {
     parser?.delete();
   }
 }
-async function buildStructuralChunks(cwd, repo, commit) {
+function canonicalRepoIndexPaths(cwd) {
   const candidates = listCandidatePaths(cwd).filter(isIndexablePath).sort((a, b) => a.localeCompare(b));
   const ignored = defaultIsIgnored(cwd, candidates);
+  return candidates.filter((path) => !ignored.has(path) && !isHardDeniedPath(path) && isCanonicalRepoIndexPath(path));
+}
+function compareV4Chunks(a, b) {
+  return compareRepoIndexChunks(a, b);
+}
+async function buildStructuralChunksForPaths(cwd, repo, commit, paths) {
   const chunks = [];
-  for (const path of candidates) {
-    if (ignored.has(path) || isHardDeniedPath(path)) continue;
+  for (const path of paths) {
     const absolute = (0, import_node_path3.join)(cwd, ...path.split("/"));
     if (!(0, import_node_fs2.existsSync)(absolute)) continue;
     let source;
@@ -361,23 +535,102 @@ async function buildStructuralChunks(cwd, repo, commit) {
     }
     chunks.push(...await structuralChunksForSource(repo, commit, path, source));
   }
-  return chunks.sort((a, b) => a.path.localeCompare(b.path) || a.citations[0].startLine - b.citations[0].startLine || a.id.localeCompare(b.id));
+  return chunks.sort(compareV4Chunks);
+}
+async function buildStructuralChunks(cwd, repo, commit) {
+  return buildStructuralChunksForPaths(cwd, repo, commit, canonicalRepoIndexPaths(cwd));
 }
 
 // src/repo-index-v4/types.ts
 var REPO_INDEX_V4_SCHEMA = 4;
 
 // src/repo-index-v4/builder.ts
-var import_node_crypto3 = require("node:crypto");
-var import_node_child_process3 = require("node:child_process");
+var import_node_crypto4 = require("node:crypto");
+var import_node_child_process4 = require("node:child_process");
 var import_node_fs3 = require("node:fs");
 var import_node_os2 = require("node:os");
 var import_node_path4 = require("node:path");
+
+// src/repo-index-v4/delta.ts
+var import_node_child_process3 = require("node:child_process");
+var COMMIT = /^[a-f0-9]{40}$/;
+var V4_DELTA_DEEPEN_STEPS = [50, 250, 1e3];
+function gitRunner(cwd) {
+  return (args) => {
+    const result = (0, import_node_child_process3.spawnSync)("git", [...args], { cwd, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
+    if (result.error) return { status: -1, stdout: "" };
+    return { status: typeof result.status === "number" ? result.status : -1, stdout: String(result.stdout ?? "") };
+  };
+}
+function parseNameStatusZ(output) {
+  const fields = output.split("\0");
+  if (fields.length && fields[fields.length - 1] === "") fields.pop();
+  const changes = [];
+  for (let i = 0; i < fields.length; ) {
+    const raw = fields[i++] ?? "";
+    const letter = raw[0];
+    if (!letter || !/^[AMDTRC]\d*$/.test(raw)) return null;
+    if (letter === "R" || letter === "C") {
+      const oldPath = fields[i++];
+      const path2 = fields[i++];
+      if (!oldPath || !path2) return null;
+      changes.push(letter === "C" ? { status: "A", path: path2 } : { status: "R", path: path2, oldPath });
+      continue;
+    }
+    const path = fields[i++];
+    if (!path) return null;
+    changes.push({ status: letter, path });
+  }
+  return changes;
+}
+function changedPaths(changes) {
+  return [...new Set(changes.filter((change) => change.status !== "D").map((change) => change.path))].sort();
+}
+function removedPaths(changes) {
+  const removed = changes.flatMap((change) => change.status === "D" ? [change.path] : change.status === "R" && change.oldPath ? [change.oldPath] : []);
+  return [...new Set(removed)].sort();
+}
+function commitPresent(git2, commit) {
+  return git2(["cat-file", "-e", `${commit}^{commit}`]).status === 0;
+}
+function isAncestor(git2, base, head) {
+  return git2(["merge-base", "--is-ancestor", base, head]).status === 0;
+}
+function planRepoIndexV4Delta(opts) {
+  const headCommit = opts.headCommit.toLowerCase();
+  const baseCommit = opts.baseCommit ? opts.baseCommit.toLowerCase() : null;
+  const full = (fallbackReason) => ({ mode: "full", headCommit, fallbackReason, ...baseCommit ? { baseCommit } : {} });
+  if (opts.forceFull) return full("explicit-full-rebuild");
+  if (!baseCommit || !COMMIT.test(baseCommit) || baseCommit === headCommit) return full("no-active-authority");
+  if (opts.basePipelineCompatible === false) return full("incompatible-base-provenance");
+  if (opts.hasPriorMaterial === false) return full("no-prior-material");
+  const { git: git2 } = opts;
+  let usable = commitPresent(git2, baseCommit) && isAncestor(git2, baseCommit, headCommit);
+  for (const depth of V4_DELTA_DEEPEN_STEPS) {
+    if (usable || !opts.deepen) break;
+    try {
+      opts.deepen(depth);
+    } catch {
+      break;
+    }
+    usable = commitPresent(git2, baseCommit) && isAncestor(git2, baseCommit, headCommit);
+  }
+  if (!usable) {
+    return full(commitPresent(git2, baseCommit) ? "base-not-ancestor" : "base-commit-unavailable");
+  }
+  const diff = git2(["diff", "--name-status", "-z", "--find-renames", baseCommit, headCommit]);
+  if (diff.status !== 0) return full("diff-unreadable");
+  const changes = parseNameStatusZ(diff.stdout);
+  if (!changes) return full("unsupported-change-status");
+  return { mode: "delta", baseCommit, headCommit, changes };
+}
+
+// src/repo-index-v4/builder.ts
 var V4_MAX_CHUNKS = 1e4;
 var V4_MAX_ARTIFACT_BYTES = 64 * 1024 * 1024;
 var V4_EMBED_BATCH = 32;
 var V4_VECTOR_DECIMAL_PLACES = 6;
-var COMMIT = /^[a-f0-9]{40}$/;
+var COMMIT2 = /^[a-f0-9]{40}$/;
 function canonicalJson(value) {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
   if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
@@ -385,7 +638,7 @@ function canonicalJson(value) {
   return `{${Object.keys(record).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(record[k])}`).join(",")}}`;
 }
 function sha2562(value) {
-  return (0, import_node_crypto3.createHash)("sha256").update(canonicalJson(value)).digest("hex");
+  return (0, import_node_crypto4.createHash)("sha256").update(canonicalJson(value)).digest("hex");
 }
 function quantizeV4Vector(vector) {
   return vector.map((value) => Number(value.toFixed(V4_VECTOR_DECIMAL_PLACES)));
@@ -394,11 +647,11 @@ function statePath(cwd) {
   return repoRuntimeStatePath(cwd, "repo-index", "v4.json");
 }
 function git(cwd, args) {
-  return String((0, import_node_child_process3.execFileSync)("git", args, { cwd, encoding: "utf8", windowsHide: true, stdio: ["ignore", "pipe", "ignore"] })).trim();
+  return String((0, import_node_child_process4.execFileSync)("git", args, { cwd, encoding: "utf8", windowsHide: true, stdio: ["ignore", "pipe", "ignore"] })).trim();
 }
 function gitInfo(cwd) {
   const commit = git(cwd, ["rev-parse", "HEAD"]).toLowerCase();
-  if (!COMMIT.test(commit)) throw new Error("repo-index v4 requires an exact git HEAD commit");
+  if (!COMMIT2.test(commit)) throw new Error("repo-index v4 requires an exact git HEAD commit");
   let defaultBranch = "main";
   try {
     defaultBranch = git(cwd, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]).replace(/^origin\//, "") || defaultBranch;
@@ -420,6 +673,9 @@ function prior(cwd) {
     return null;
   }
 }
+function repoIndexV4DeltaBase(envelope) {
+  return envelope && isRepoIndexDeltaCompatible(envelope.manifest) ? envelope : null;
+}
 function tombstone(repo, commit, path, createdAt) {
   const base = { repo, commit, path, reason: "deleted", createdAt };
   return { ...base, id: sha2562(base) };
@@ -454,7 +710,7 @@ function runEmbedderOnce(cwd, chunks, modelDirectory, createdAt) {
   (0, import_node_fs3.writeFileSync)(requestFile, JSON.stringify(request));
   let result;
   try {
-    result = (0, import_node_child_process3.spawnSync)(process.execPath, [file, requestFile], { encoding: "utf8", windowsHide: true, timeout: V4_EMBED_TIMEOUT_MS, maxBuffer: V4_MAX_ARTIFACT_BYTES, env });
+    result = (0, import_node_child_process4.spawnSync)(process.execPath, [file, requestFile], { encoding: "utf8", windowsHide: true, timeout: V4_EMBED_TIMEOUT_MS, maxBuffer: V4_MAX_ARTIFACT_BYTES, env });
   } finally {
     (0, import_node_fs3.rmSync)(requestDir, { recursive: true, force: true });
   }
@@ -510,23 +766,53 @@ function runEmbedder(cwd, chunks, modelDirectory, createdAt) {
   const stderr = runner.stderrTail ? ` stderr=${runner.stderrTail}` : "";
   throw new Error(`repo-index v4 embedding runner failed: ${runner.detail ?? "unknown"}${code}${stdout}${stderr}`);
 }
+function restampCitations(chunk, repo, commit) {
+  return { ...chunk, citations: chunk.citations.map((citation2) => ({ ...citation2, repo, commit })) };
+}
 async function buildRepoIndexV4(cwd, repo, opts = {}) {
+  return (await buildRepoIndexV4Detailed(cwd, repo, opts)).envelope;
+}
+async function buildRepoIndexV4Detailed(cwd, repo, opts = {}) {
   const { commit, defaultBranch, createdAt } = gitInfo(cwd);
-  const chunks = await buildStructuralChunks(cwd, repo, commit);
-  if (chunks.length > V4_MAX_CHUNKS) throw new Error(`repo-index v4 exceeds ${V4_MAX_CHUNKS} chunk ceiling`);
+  const delta = opts.delta;
   const old = prior(cwd);
+  const deltaBase = repoIndexV4DeltaBase(old);
+  let chunks;
+  let carried = 0;
+  let built = 0;
+  let changedCount = 0;
+  let removedCount = 0;
+  if (delta) {
+    const admitted = new Set(canonicalRepoIndexPaths(cwd));
+    const changed = new Set(changedPaths(delta.changes));
+    const removed = new Set(removedPaths(delta.changes));
+    changedCount = changed.size;
+    removedCount = removed.size;
+    const rebuilt = await buildStructuralChunksForPaths(cwd, repo, commit, [...changed].filter((path2) => admitted.has(path2)).sort());
+    const kept = delta.prior.chunks.filter((chunk) => !changed.has(chunk.path) && !removed.has(chunk.path) && admitted.has(chunk.path)).map((chunk) => restampCitations(chunk, repo, commit));
+    carried = kept.length;
+    built = rebuilt.length;
+    chunks = [...kept, ...rebuilt].sort(compareV4Chunks);
+  } else {
+    chunks = await buildStructuralChunks(cwd, repo, commit);
+    built = chunks.length;
+  }
+  if (chunks.length > V4_MAX_CHUNKS) throw new Error(`repo-index v4 exceeds ${V4_MAX_CHUNKS} chunk ceiling`);
   const currentPaths = new Set(chunks.map((c) => c.path));
+  const priorChunks = delta ? delta.prior.chunks : old?.manifest.chunks ?? [];
+  const priorTombstones = delta ? delta.prior.tombstones ?? [] : old?.manifest.tombstones ?? [];
   const tombstonePaths = [
-    ...(old?.manifest.tombstones ?? []).map((t) => t.path),
-    ...(old?.manifest.chunks ?? []).map((c) => c.path).filter((path2) => !currentPaths.has(path2))
+    ...priorTombstones.map((t) => t.path),
+    ...priorChunks.map((c) => c.path).filter((path2) => !currentPaths.has(path2))
   ];
   const tombstones = [...new Set(tombstonePaths)].sort().map((path2) => tombstone(repo, commit, path2, createdAt));
-  const oldChunkHashById = new Map((old?.manifest.chunks ?? []).map((c) => [c.id, c.contentHash]));
+  const embeddingSource = delta ? delta.prior : { chunks: deltaBase?.manifest.chunks ?? [], embeddings: deltaBase?.manifest.embeddings ?? [] };
+  const oldChunkHashById = new Map(embeddingSource.chunks.map((c) => [c.id, c.contentHash]));
   const reusableEmbedding = (embedding) => {
     const norm = Math.hypot(...embedding.vector);
     return embedding.vector.length === 384 && embedding.vector.every(Number.isFinite) && norm >= 0.98 && norm <= 1.02 && embedding.provenance.provider === "local" && embedding.provenance.modelDigest === "828e1496d7fabb79cfa4dcd84fa38625c0d3d21da474a00f08db0f559940cf35" && embedding.provenance.dimensions === 384 && embedding.provenance.input === "pointer-safe-structural-chunk";
   };
-  const oldEmbeddingByHash = new Map((old?.manifest.embeddings ?? []).filter(reusableEmbedding).map((e) => [oldChunkHashById.get(e.chunkId), e]));
+  const oldEmbeddingByHash = new Map(embeddingSource.embeddings.filter(reusableEmbedding).map((e) => [oldChunkHashById.get(e.chunkId), e]));
   const reusable = chunks.flatMap((chunk) => {
     const priorEmbedding = oldEmbeddingByHash.get(chunk.contentHash);
     return priorEmbedding ? [{ ...priorEmbedding, chunkId: chunk.id }] : [];
@@ -534,21 +820,21 @@ async function buildRepoIndexV4(cwd, repo, opts = {}) {
   const reusableIds = new Set(reusable.map((e) => e.chunkId));
   const missing = chunks.filter((chunk) => !reusableIds.has(chunk.id));
   const generated = missing.length === 0 ? { embeddings: [] } : opts.embed === false ? { embeddings: [], reason: "embeddings-unavailable" } : runEmbedder(cwd, missing, opts.modelDirectory, createdAt);
-  const embeddings = [...reusable, ...generated.embeddings].map((embedding) => ({ ...embedding, vector: quantizeV4Vector(embedding.vector) })).sort((a, b) => a.chunkId.localeCompare(b.chunkId));
-  const chunksDigest = sha2562(chunks);
-  const embeddingsDigest = sha2562(embeddings);
-  const artifact = (kind, digest) => {
-    const identity2 = { repo, commit, immutable: true, kind, uri: `s3://repo-index/v4/${repo}/${commit}/${digest}.${kind}.json`, sha256: digest, createdAt };
+  const embeddings = [...reusable, ...generated.embeddings].map((embedding) => ({ ...embedding, vector: quantizeV4Vector(embedding.vector) })).sort(compareRepoIndexEmbeddings);
+  const materialIndexDigest = buildRepoIndexMaterialLayout(repo, chunks, embeddings).indexDigest;
+  const artifact = (kind, digest, uri) => {
+    const identity2 = { repo, commit, immutable: true, kind, uri, sha256: digest, createdAt };
     return { ...identity2, id: sha2562(identity2) };
   };
-  const artifacts = [artifact("chunks", chunksDigest), artifact("embeddings", embeddingsDigest)];
+  const artifacts = [artifact("material-index", materialIndexDigest, repoIndexMaterialIndexUri(repo, materialIndexDigest))];
   const grammarProvenance = {
     runtime: { name: "web-tree-sitter", version: "0.26.12", license: "MIT" },
     grammarPack: { name: "tree-sitter-wasm", version: "1.1.4", license: "MIT", digest: "f3089ddf2c9615a423783b645c4dfb23ccda30807bbd059746f583952357c489" },
     languages: ["go", "java", "javascript", "jsx", "kotlin", "python", "rust", "tsx", "typescript"]
   };
   const rrf = { algorithm: "reciprocal-rank-fusion", k: 60, lexicalWeight: 1, semanticWeight: 1 };
-  const identity = { repo, commit, defaultBranch, immutable: true, createdAt, grammarProvenance, chunks, embeddings, artifacts, tombstones, rrf };
+  const indexProvenance = { ...CURRENT_REPO_INDEX_PROVENANCE };
+  const identity = { repo, commit, defaultBranch, immutable: true, ...delta ? { parentCommit: delta.baseCommit } : {}, createdAt, grammarProvenance, indexProvenance, chunks, embeddings, artifacts, tombstones, rrf };
   const manifest = { ...identity, id: sha2562(identity) };
   const complete = embeddings.length === chunks.length;
   const envelope = {
@@ -562,7 +848,23 @@ async function buildRepoIndexV4(cwd, repo, opts = {}) {
   (0, import_node_fs3.mkdirSync)((0, import_node_path4.dirname)(path), { recursive: true });
   (0, import_node_fs3.writeFileSync)(path, `${JSON.stringify(envelope, null, 2)}
 `, "utf8");
-  return envelope;
+  const metrics = {
+    mode: delta ? "delta" : "full",
+    ...delta ? { baseCommit: delta.baseCommit } : {},
+    changedPaths: changedCount,
+    removedPaths: removedCount,
+    chunksTotal: chunks.length,
+    chunksCarried: carried,
+    chunksBuilt: built,
+    embeddingsReused: reusable.length,
+    embeddingsEmbedded: generated.embeddings.length,
+    tombstones: tombstones.length
+  };
+  return { envelope, metrics };
+}
+function formatV4BuildMetrics(repo, metrics) {
+  const base = metrics.baseCommit ? ` base=${metrics.baseCommit.slice(0, 12)}` : "";
+  return `${repo}: ${metrics.mode}${base} changed=${metrics.changedPaths} removed=${metrics.removedPaths} chunks=${metrics.chunksTotal} (carried=${metrics.chunksCarried} built=${metrics.chunksBuilt}) embeddings(reused=${metrics.embeddingsReused} new=${metrics.embeddingsEmbedded}) tombstones=${metrics.tombstones}`;
 }
 function repoIndexV4StorePath(cwd) {
   return statePath(cwd);
@@ -575,12 +877,12 @@ var V4_STAGE_MAX_SHARDS = 128;
 function encodedBytes(value) {
   return Buffer.byteLength(JSON.stringify(value));
 }
-function split(kind, records, manifest) {
+function split(kind, records, manifest, bucket) {
   const groups = [];
   let group = [];
   for (const record of records) {
     const next = [...group, record];
-    const probe = { repo: manifest.repo, commit: manifest.commit, manifestId: manifest.id, kind, index: 127, total: 128, digest: "0".repeat(64), records: next };
+    const probe = { repo: manifest.repo, commit: manifest.commit, manifestId: manifest.id, kind, ...bucket === void 0 ? {} : { bucket }, index: 127, total: 128, digest: "0".repeat(64), records: next };
     if (group.length && (group.length >= V4_STAGE_MAX_RECORDS || encodedBytes(probe) > V4_STAGE_MAX_BODY_BYTES)) {
       groups.push(group);
       group = [record];
@@ -596,6 +898,7 @@ function split(kind, records, manifest) {
       commit: manifest.commit,
       manifestId: manifest.id,
       kind,
+      ...bucket === void 0 ? {} : { bucket },
       index,
       total: groups.length,
       digest: sha2562(items),
@@ -605,11 +908,27 @@ function split(kind, records, manifest) {
     return request;
   });
 }
-function shardRepoIndexV4(envelope) {
+function shardRepoIndexV4(envelope, opts = {}) {
   const { chunks, embeddings, ...header } = envelope.manifest;
-  const stages = [...split("chunks", chunks, envelope.manifest), ...split("embeddings", embeddings ?? [], envelope.manifest)];
-  const shards = stages.map(({ kind, index, total, digest, records }) => ({ kind, index, total, digest, count: records.length }));
-  return { stages, finalize: { repo: header.repo, commit: header.commit, manifestId: header.id, header, status: envelope.status, shards } };
+  const identity = { repo: header.repo, commit: header.commit, manifestId: header.id, header, status: envelope.status };
+  if ((header.indexProvenance?.materialLayoutVersion ?? 1) < 2) {
+    const stages2 = [...split("chunks", chunks, envelope.manifest), ...split("embeddings", embeddings ?? [], envelope.manifest)];
+    const shards2 = stages2.map(({ kind, index, total, digest, records }) => ({ kind, index, total, digest, count: records.length }));
+    return { stages: stages2, finalize: { ...identity, shards: shards2 } };
+  }
+  const reusable = new Set(opts.priorBucketDigests ?? []);
+  const layout = buildRepoIndexMaterialLayout(header.repo, chunks, embeddings ?? []);
+  const stages = [];
+  const shards = [];
+  const buckets = layout.buckets.map((bucket) => {
+    if (reusable.has(bucket.digest)) return { kind: bucket.kind, bucket: bucket.bucket, count: bucket.count, digest: bucket.digest, shards: 0 };
+    const fragments = split(bucket.kind, bucket.body.records, envelope.manifest, bucket.bucket);
+    stages.push(...fragments);
+    shards.push(...fragments.map(({ kind, index, total, digest, records }) => ({ kind, bucket: bucket.bucket, index, total, digest, count: records.length })));
+    return { kind: bucket.kind, bucket: bucket.bucket, count: bucket.count, digest: bucket.digest, shards: fragments.length };
+  });
+  if (buckets.length !== 2 * REPO_INDEX_MATERIAL_BUCKET_COUNT) throw new Error("repo-index v4 material layout is incomplete");
+  return { stages, finalize: { ...identity, shards, materialLayout: 2, buckets } };
 }
 function encodedStageBytes(stage) {
   return encodedBytes(stage);
@@ -718,6 +1037,7 @@ function buildGraphEdges(cwd, repo, commit, rosterRepos) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   REPO_INDEX_V4_SCHEMA,
+  V4_DELTA_DEEPEN_STEPS,
   V4_GRAPH_MAX_EDGES,
   V4_GRAPH_MAX_EDGES_PER_FILE,
   V4_MAX_ARTIFACT_BYTES,
@@ -726,10 +1046,23 @@ function buildGraphEdges(cwd, repo, commit, rosterRepos) {
   V4_STAGE_MAX_RECORDS,
   buildGraphEdges,
   buildRepoIndexV4,
+  buildRepoIndexV4Detailed,
   buildStructuralChunks,
+  buildStructuralChunksForPaths,
+  canonicalRepoIndexPaths,
+  changedPaths,
+  compareV4Chunks,
   encodedStageBytes,
+  formatV4BuildMetrics,
+  gitRunner,
   graphEdgesForSource,
+  isRepoIndexDeltaCompatible,
   languageForPath,
+  parseNameStatusZ,
+  planRepoIndexV4Delta,
+  readRepoIndexProvenance,
+  removedPaths,
+  repoIndexV4DeltaBase,
   repoIndexV4StorePath,
   shardRepoIndexV4,
   structuralChunksForSource

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "4.0.17",
+  "version": "4.1.0",
   "description": "MMI Future CLI — the org dev toolbox and shared cross-IDE engine for every registry-declared MMI coding surface.",
   "type": "module",
   "license": "UNLICENSED",