@nimiplatform/nimi-coding 0.4.0 → 0.5.0

package/cli/lib/authority/closed-sets.mjs

@@ -65,11 +65,6 @@ function refused(diagnostics, { fileCount = 0 } = {}) {
   };
 }
 
-function isWithin(root, candidate) {
-  const relative = path.relative(root, candidate);
-  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-
 function portableRelative(repository, candidate) {
   return path.relative(repository, candidate).split(path.sep).join(path.posix.sep);
 }
@@ -540,12 +535,16 @@ export async function closedSetsAuthorityRepository(repositoryPath, specPath, {
   }
   const canonical = canonicalGroups(compiled);
 
+  const gitlinks = new Set(inventory.gitlinks);
   const classifiedFiles = await classifyTrackedTextFiles(
     inventory.repository,
     inventory.files,
-    (file) => file === ".nimi/spec" || file.startsWith(".nimi/spec/")
-      ? "authority-corpus"
-      : implementationFileKind(file) === null ? "not-a-scanned-kind" : null,
+    (file) => {
+      if (gitlinks.has(file)) return "gitlink";
+      return file === ".nimi/spec" || file.startsWith(".nimi/spec/")
+        ? "authority-corpus"
+        : implementationFileKind(file) === null ? "not-a-scanned-kind" : null;
+    },
   );
   if (classifiedFiles.error !== undefined) {
     return refused([inputDiagnostic("AUTH_CLOSED_SETS_IMPLEMENTATION_INPUT_INVALID", classifiedFiles.error)], { fileCount: compiled.fileCount });

package/cli/lib/authority/compile.mjs

@@ -1,4 +1,4 @@
-import { compareText, makeDiagnostic, sortDiagnostics } from "./diagnostics.mjs";
+import { compareText } from "./diagnostics.mjs";
 import { formattingDiagnostics, parseAuthorityPath } from "./format.mjs";
 import { validateAuthorityScopeBindings } from "./scope-bindings.mjs";
 import { buildSourceMap } from "./source-map.mjs";
@@ -39,31 +39,13 @@ async function admittedSources(inputPath) {
   return { ok: true, diagnostics: [], parsed };
 }
 
-function requiredFormatDiagnostics(documents, requiredFormat) {
-  if (requiredFormat === null) return [];
-  return sortDiagnostics(documents.flatMap((document) => {
-    const found = document.data?.format;
-    if (found === requiredFormat) return [];
-    return [makeDiagnostic({
-      code: "AUTH_FORMAT_REQUIRED",
-      file: document.file,
-      range: document.locations.get("/format") ?? document.locations.get("") ?? document.locator.range(0),
-      pointer: "/format",
-      reason: `authority check requires format ${requiredFormat}, but ${document.file} declares ${found}`,
-      repair: "rewrite the container in the explicitly required admitted format without changing product semantics",
-    })];
-  }));
-}
-
-export async function checkAuthorityPath(inputPath, { scopeBindings = null, requireFormat = null } = {}) {
+export async function checkAuthorityPath(inputPath, { scopeBindings = null } = {}) {
   const result = await admittedSources(inputPath);
-  const formatDiagnostics = requiredFormatDiagnostics(result.parsed.documents, requireFormat);
-  const diagnostics = sortDiagnostics([...result.diagnostics, ...formatDiagnostics]);
-  if (!result.ok || formatDiagnostics.length > 0 || scopeBindings === null) return {
-    ok: result.ok && formatDiagnostics.length === 0,
-    diagnostics,
+  if (!result.ok || scopeBindings === null) return {
+    ok: result.ok,
+    diagnostics: result.diagnostics,
     fileCount: result.parsed.files.length,
-    unitCount: result.ok && formatDiagnostics.length === 0 ? result.parsed.sources.length : 0,
+    unitCount: result.ok ? result.parsed.sources.length : 0,
   };
   const scopeValidation = await validateAuthorityScopeBindings(result.parsed.sources, scopeBindings);
   return {

package/cli/lib/authority/compiled-snapshot.mjs

@@ -0,0 +1,143 @@
+import path from "node:path";
+
+import { compareText, portablePath } from "./diagnostics.mjs";
+
+class ReadonlyIndex {
+  #values;
+
+  constructor(entries) {
+    this.#values = new Map(entries);
+    Object.freeze(this);
+  }
+
+  get size() {
+    return this.#values.size;
+  }
+
+  get(key) {
+    return this.#values.get(key);
+  }
+
+  has(key) {
+    return this.#values.has(key);
+  }
+
+  *entries() {
+    for (const [key, value] of this.#values) yield Object.freeze([key, value]);
+  }
+
+  keys() {
+    return this.#values.keys();
+  }
+
+  values() {
+    return this.#values.values();
+  }
+
+  forEach(callback, thisArg = undefined) {
+    for (const [key, value] of this.#values) callback.call(thisArg, value, key, this);
+  }
+
+  [Symbol.iterator]() {
+    return this.entries();
+  }
+
+  get [Symbol.toStringTag]() {
+    return "ReadonlyIndex";
+  }
+}
+
+function freezeTree(value, seen = new Set()) {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value) || seen.has(value)) return value;
+  seen.add(value);
+  for (const key of Reflect.ownKeys(value)) freezeTree(value[key], seen);
+  return Object.freeze(value);
+}
+
+function readonlyIndex(entries) {
+  return new ReadonlyIndex([...entries].sort(([left], [right]) => compareText(left, right)));
+}
+
+function groupedIndex(entries, keys) {
+  const groups = new Map();
+  for (const entry of entries) {
+    for (const key of keys(entry)) {
+      const values = groups.get(key) ?? [];
+      values.push(entry);
+      groups.set(key, values);
+    }
+  }
+  return readonlyIndex([...groups.entries()].map(([key, values]) => [
+    key,
+    Object.freeze(values.sort((left, right) => compareText(left.unit.id, right.unit.id))),
+  ]));
+}
+
+function compareEdge(left, right) {
+  return compareText(left.source, right.source)
+    || compareText(left.type, right.type)
+    || compareText(left.target, right.target);
+}
+
+function adjacencyIndexes(entries) {
+  const outgoing = new Map(entries.map((entry) => [entry.unit.id, []]));
+  const incoming = new Map(entries.map((entry) => [entry.unit.id, []]));
+  for (const entry of entries) {
+    entry.unit.relations.forEach((relation, relationIndex) => {
+      const edge = Object.freeze({
+        source: entry.unit.id,
+        type: relation.type,
+        target: relation.target,
+        sourceUnitIndex: entry.unitIndex,
+        relationIndex,
+      });
+      outgoing.get(edge.source).push(edge);
+      incoming.get(edge.target).push(edge);
+    });
+  }
+  const finish = (index) => readonlyIndex([...index.entries()].map(([id, edges]) => [
+    id,
+    Object.freeze(edges.sort(compareEdge)),
+  ]));
+  return { outgoing: finish(outgoing), incoming: finish(incoming) };
+}
+
+export function createCompiledAuthoritySnapshot(compiled, inputRoot) {
+  if (
+    compiled?.ok !== true
+    || !Array.isArray(compiled?.ir?.units)
+    || compiled?.sourceMap?.fields === null
+    || typeof compiled?.sourceMap?.fields !== "object"
+  ) {
+    throw new TypeError("compiled authority snapshot requires one successful compiler result");
+  }
+  if (typeof inputRoot !== "string" || inputRoot.length === 0) {
+    throw new TypeError("compiled authority snapshot requires one non-empty input root");
+  }
+  const resolvedRoot = path.resolve(inputRoot);
+  const entries = compiled.ir.units.map((unit, unitIndex) => {
+    const mapped = compiled.sourceMap.fields[`/units/${unitIndex}/id`];
+    if (!mapped) throw new TypeError(`compiled authority snapshot cannot locate unit identity: ${unit.id}`);
+    return Object.freeze({
+      unit,
+      unitIndex,
+      container: portablePath(mapped.file, resolvedRoot),
+    });
+  });
+  const byId = readonlyIndex(entries.map((entry) => [entry.unit.id, entry]));
+  const byOwner = groupedIndex(entries, (entry) => [entry.unit.owner]);
+  const byScope = groupedIndex(entries, (entry) => entry.unit.semantic?.scope ?? []);
+  const byContainer = groupedIndex(entries, (entry) => [entry.container]);
+  const { incoming, outgoing } = adjacencyIndexes(entries);
+  freezeTree(compiled);
+  return Object.freeze({
+    inputRoot: resolvedRoot,
+    compiled,
+    byId,
+    byOwner,
+    byScope,
+    byContainer,
+    incoming,
+    outgoing,
+  });
+}

package/cli/lib/authority/consumers.mjs

@@ -3,7 +3,7 @@ import path from "node:path";
 
 import YAML from "yaml";
 
-import { compareText, makeDiagnostic, sortDiagnostics } from "./diagnostics.mjs";
+import { compareText, isPathWithin, makeDiagnostic, sortDiagnostics } from "./diagnostics.mjs";
 import { AuthorityReviewRefusal } from "./git-snapshot.mjs";
 import { resolveRepositoryCorpus } from "./repository-corpus.mjs";
 import { repositoryInventory } from "./repository-inventory.mjs";
@@ -15,7 +15,10 @@ const CONSUMERS_FORMAT = "nimicoding.authority-consumers/v1";
 // requiring a trailing segment reported it as no reference at all.
 // A separator run rather than one character: inside a source string literal a
 // Windows path is written escaped, so the file text holds ".nimi\\spec".
-const SPEC_REFERENCE = /\.nimi[/\\]+spec(?:[/\\]+[A-Za-z0-9_.\\/*<>-]*[A-Za-z0-9_*<>-])?/gu;
+// A single backslash followed by a common source-string escape starter ends a
+// local path instead of creating another path segment. Escaped Windows
+// separators remain visible in source as a run of at least two backslashes.
+const SPEC_REFERENCE = /\.nimi(?:\/+|\\{2,}|\\(?![nrtbfv0xu'"`$]))spec(?:(?:\/+|\\{2,}|\\(?![nrtbfv0xu'"`$]))[A-Za-z0-9_.*<>-]+)*/gu;
 // A path built from adjacent string literals, e.g. path.join(root, '.nimi',
 // 'spec', 'runtime', 'x.yaml'). Reconstructed only while every segment is a
 // literal; the first non-literal segment makes the target unresolved.
@@ -84,11 +87,6 @@ function repositoryDiagnostic(error) {
   return inputDiagnostic("AUTH_CONSUMERS_REPOSITORY_INVALID", error.message, error.file ?? ".");
 }
 
-function isWithin(root, candidate) {
-  const relative = path.relative(root, candidate);
-  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-
 async function resolveCorpus(repository, specPath) {
   return resolveRepositoryCorpus(repository, specPath, "authority consumer");
 }
@@ -115,29 +113,66 @@ function lineCounter(text) {
   };
 }
 
+function collapseEscapedLineContinuations(text) {
+  const chunks = [];
+  const continuations = [];
+  let segmentStart = 0;
+  let searchFrom = 0;
+  let normalizedLength = 0;
+  for (let index = text.indexOf("\\", searchFrom); index !== -1; index = text.indexOf("\\", searchFrom)) {
+    const width = text[index + 1] === "\n"
+      ? 2
+      : text[index + 1] === "\r" && text[index + 2] === "\n" ? 3 : 0;
+    if (width === 0) {
+      searchFrom = index + 1;
+      continue;
+    }
+    const chunk = text.slice(segmentStart, index);
+    chunks.push(chunk);
+    normalizedLength += chunk.length;
+    continuations.push({ offset: normalizedLength, width });
+    segmentStart = index + width;
+    searchFrom = segmentStart;
+  }
+  if (continuations.length === 0) return { text, originalOffset: (index) => index };
+  chunks.push(text.slice(segmentStart));
+  return {
+    text: chunks.join(""),
+    originalOffset(index) {
+      let removedWidth = 0;
+      for (const continuation of continuations) {
+        if (continuation.offset > index) break;
+        removedWidth += continuation.width;
+      }
+      return index + removedWidth;
+    },
+  };
+}
+
 function extractReferences(consumer, text) {
+  const logical = collapseEscapedLineContinuations(text);
   const found = [];
-  for (const match of text.matchAll(SPEC_REFERENCE)) {
+  for (const match of logical.text.matchAll(SPEC_REFERENCE)) {
     const target = match[0].replace(/[/\\]+/gu, "/");
     if (target.includes("*") || target.includes("<") || target.includes(">")) continue;
-    found.push({ index: match.index, target, reason: null });
+    found.push({ index: logical.originalOffset(match.index), target, reason: null });
   }
-  for (const match of text.matchAll(SPEC_CONSTRUCTOR)) {
+  for (const match of logical.text.matchAll(SPEC_CONSTRUCTOR)) {
     const segments = [...match[3].matchAll(CONSTRUCTOR_SEGMENT)].map((segment) => segment[2]);
     const target = [".nimi", "spec", ...segments].join("/");
     // A further segment that is not a string literal makes the built path
     // unknowable here. Reporting it as unresolved keeps the scan from
     // presenting silence as proof that nothing consumes the corpus.
-    const continues = CONSTRUCTOR_CONTINUES.test(text.slice(match.index + match[0].length));
-    found.push({ index: match.index, target, reason: continues ? "non-literal-path-segment" : null });
+    const continues = CONSTRUCTOR_CONTINUES.test(logical.text.slice(match.index + match[0].length));
+    found.push({ index: logical.originalOffset(match.index), target, reason: continues ? "non-literal-path-segment" : null });
   }
-  for (const match of text.matchAll(EXTERNAL_REFERENCE)) {
+  for (const match of logical.text.matchAll(EXTERNAL_REFERENCE)) {
     const externalPath = match[2];
     const fragment = match[3] ?? null;
     const coordinate = `${match[1]}:${externalPath}${fragment === null ? "" : `#${fragment}`}`;
     const nonCanonical = externalPath.split("/").some((segment) => segment === "." || segment === "..");
     found.push({
-      index: match.index + match[0].indexOf(`${match[1]}:`),
+      index: logical.originalOffset(match.index + match[0].indexOf(`${match[1]}:`)),
       target: coordinate,
       scheme: match[1],
       path: externalPath,
@@ -173,18 +208,28 @@ function targetExists(target, trackedFiles) {
 // own. Without a root for that scheme the target is unknowable here, which is
 // not the same claim as dead.
 function classifyLocalReference(reference, trackedFiles) {
-  return targetExists(reference.target, trackedFiles) ? "canonical" : "canonicalDead";
+  if (targetExists(reference.target, trackedFiles)) return { classification: "canonical", reference };
+  if (reference.target.endsWith(".")) {
+    const withoutSentencePeriod = reference.target.slice(0, -1);
+    if (targetExists(withoutSentencePeriod, trackedFiles)) {
+      return {
+        classification: "canonical",
+        reference: { ...reference, target: withoutSentencePeriod },
+      };
+    }
+  }
+  return { classification: "canonicalDead", reference };
 }
 
 async function externalTargetStatus(root, relative) {
   const candidate = path.resolve(root, ...relative.split("/"));
-  if (!isWithin(root, candidate)) return "non-canonical";
+  if (!isPathWithin(root, candidate)) return "non-canonical";
 
   let probe = candidate;
   while (true) {
     try {
       const resolved = await realpath(probe);
-      if (!isWithin(root, resolved)) return "non-canonical";
+      if (!isPathWithin(root, resolved)) return "non-canonical";
       return probe === candidate ? "authority" : "dead";
     } catch (error) {
       if (error.code !== "ENOENT" && error.code !== "ENOTDIR") throw error;
@@ -354,10 +399,14 @@ export async function consumersAuthorityRepository(repositoryPath, specPath, { m
   }
 
   const candidates = [...new Set([...inventory.files, "package.json"])].sort(compareText);
+  const gitlinks = new Set(inventory.gitlinks);
   const classifiedFiles = await classifyTrackedTextFiles(
     inventory.repository,
     candidates,
-    (file) => isSpecSource(file) ? "authority-corpus" : null,
+    (file) => {
+      if (gitlinks.has(file)) return "gitlink";
+      return isSpecSource(file) ? "authority-corpus" : null;
+    },
   );
   if (classifiedFiles.error !== undefined) {
     return refused([inputDiagnostic("AUTH_CONSUMERS_INPUT_INVALID", classifiedFiles.error)]);
@@ -401,7 +450,8 @@ export async function consumersAuthorityRepository(repositoryPath, specPath, { m
   try {
     for (const reference of references) {
       if (reference.external === undefined) {
-        classified[classifyLocalReference(reference, trackedFiles)].push(reference);
+        const local = classifyLocalReference(reference, trackedFiles);
+        classified[local.classification].push(local.reference);
         continue;
       }
       const root = roots.get(reference.external.scheme);

package/cli/lib/authority/diagnostics.mjs

@@ -6,9 +6,15 @@ export function compareText(left, right) {
   return a === b ? 0 : a < b ? -1 : 1;
 }
 
+export function isPathWithin(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === ""
+    || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
 export function portablePath(filePath, cwd = process.cwd()) {
   const relative = path.relative(cwd, filePath);
-  const value = relative && !relative.startsWith("..") && !path.isAbsolute(relative) ? relative : filePath;
+  const value = relative && isPathWithin(cwd, filePath) ? relative : filePath;
   return value.split(path.sep).join(path.posix.sep);
 }
 

package/cli/lib/authority/diff.mjs

@@ -3,6 +3,7 @@ import { stat } from "node:fs/promises";
 import path from "node:path";
 
 import { compileAuthorityPath } from "./compile.mjs";
+import { createCompiledAuthoritySnapshot } from "./compiled-snapshot.mjs";
 import { compareText, makeDiagnostic, portablePath, sortDiagnostics } from "./diagnostics.mjs";
 
 const DIFF_FORMAT = "nimicoding.authority-diff/v1";
@@ -46,14 +47,14 @@ function portableMapping(mapping, basePath) {
   return { ...mapping, file: portablePath(mapping.file, basePath) };
 }
 
-function mappedAt(compiled, unitIndex, pointer, basePath) {
-  const exact = compiled.sourceMap.fields[`/units/${unitIndex}${pointer}`];
-  if (exact) return portableMapping(exact, basePath);
+function mappedAt(snapshot, unitIndex, pointer) {
+  const exact = snapshot.compiled.sourceMap.fields[`/units/${unitIndex}${pointer}`];
+  if (exact) return portableMapping(exact, snapshot.inputRoot);
   const prefix = `/units/${unitIndex}${pointer}/`;
-  const nested = Object.entries(compiled.sourceMap.fields)
+  const nested = Object.entries(snapshot.compiled.sourceMap.fields)
     .filter(([candidate]) => candidate.startsWith(prefix))
     .sort(([left], [right]) => compareText(left, right))[0]?.[1];
-  return portableMapping(nested, basePath);
+  return portableMapping(nested, snapshot.inputRoot);
 }
 
 function addChange(changes, { unitId, operation = "modified", pointer, before, after, beforeSource = null, afterSource = null }) {
@@ -68,7 +69,7 @@ function addChange(changes, { unitId, operation = "modified", pointer, before, a
   });
 }
 
-function compareScalar(changes, beforeEntry, afterEntry, pointer, beforeBase, afterBase) {
+function compareScalar(changes, beforeSnapshot, afterSnapshot, beforeEntry, afterEntry, pointer) {
   const before = beforeEntry.unit;
   const after = afterEntry.unit;
   const read = (value, parts) => parts.reduce((current, part) => current?.[part], value);
@@ -81,21 +82,21 @@ function compareScalar(changes, beforeEntry, afterEntry, pointer, beforeBase, af
     pointer,
     before: left,
     after: right,
-    beforeSource: mappedAt(beforeEntry.compiled, beforeEntry.index, pointer, beforeBase),
-    afterSource: mappedAt(afterEntry.compiled, afterEntry.index, pointer, afterBase),
+    beforeSource: mappedAt(beforeSnapshot, beforeEntry.unitIndex, pointer),
+    afterSource: mappedAt(afterSnapshot, afterEntry.unitIndex, pointer),
   });
 }
 
-function compareValueSet(changes, beforeEntry, afterEntry, pointer, beforeBase, afterBase) {
+function compareValueSet(changes, beforeSnapshot, afterSnapshot, beforeEntry, afterEntry, pointer) {
   const parts = pointer.slice(1).split("/");
   const read = (unit) => parts.reduce((current, part) => current?.[part], unit) ?? [];
   const beforeValues = read(beforeEntry.unit);
   const afterValues = read(afterEntry.unit);
   const beforeSet = new Set(beforeValues.map((value) => JSON.stringify(value)));
   const afterSet = new Set(afterValues.map((value) => JSON.stringify(value)));
-  for (const [operation, values, otherSet, entry, basePath, sourceSide] of [
-    ["removed", beforeValues, afterSet, beforeEntry, beforeBase, "beforeSource"],
-    ["added", afterValues, beforeSet, afterEntry, afterBase, "afterSource"],
+  for (const [operation, values, otherSet, snapshot, entry, sourceSide] of [
+    ["removed", beforeValues, afterSet, beforeSnapshot, beforeEntry, "beforeSource"],
+    ["added", afterValues, beforeSet, afterSnapshot, afterEntry, "afterSource"],
   ]) {
     values.forEach((value, index) => {
       if (otherSet.has(JSON.stringify(value))) return;
@@ -105,20 +106,20 @@ function compareValueSet(changes, beforeEntry, afterEntry, pointer, beforeBase,
         pointer,
         before: operation === "removed" ? value : null,
         after: operation === "added" ? value : null,
-        [sourceSide]: mappedAt(entry.compiled, entry.index, `${pointer}/${index}`, basePath),
+        [sourceSide]: mappedAt(snapshot, entry.unitIndex, `${pointer}/${index}`),
       });
     });
   }
 }
 
-function compareRelations(changes, beforeEntry, afterEntry, beforeBase, afterBase) {
+function compareRelations(changes, beforeSnapshot, afterSnapshot, beforeEntry, afterEntry) {
   const beforeRelations = beforeEntry.unit.relations;
   const afterRelations = afterEntry.unit.relations;
   const beforeSet = new Set(beforeRelations.map((edge) => `${edge.type}\0${edge.target}`));
   const afterSet = new Set(afterRelations.map((edge) => `${edge.type}\0${edge.target}`));
-  for (const [operation, edges, otherSet, entry, basePath, sourceSide] of [
-    ["removed", beforeRelations, afterSet, beforeEntry, beforeBase, "beforeSource"],
-    ["added", afterRelations, beforeSet, afterEntry, afterBase, "afterSource"],
+  for (const [operation, edges, otherSet, snapshot, entry, sourceSide] of [
+    ["removed", beforeRelations, afterSet, beforeSnapshot, beforeEntry, "beforeSource"],
+    ["added", afterRelations, beforeSet, afterSnapshot, afterEntry, "afterSource"],
   ]) {
     edges.forEach((edge, index) => {
       if (otherSet.has(`${edge.type}\0${edge.target}`)) return;
@@ -128,23 +129,23 @@ function compareRelations(changes, beforeEntry, afterEntry, beforeBase, afterBas
         pointer: "/relations",
         before: operation === "removed" ? edge : null,
         after: operation === "added" ? edge : null,
-        [sourceSide]: mappedAt(entry.compiled, entry.index, `/relations/${index}`, basePath),
+        [sourceSide]: mappedAt(snapshot, entry.unitIndex, `/relations/${index}`),
       });
     });
   }
 }
 
-function sideMappedAt(compiled, unitIndex, pointer, basePath, side) {
-  const mapped = mappedAt(compiled, unitIndex, pointer, basePath);
+function sideMappedAt(snapshot, unitIndex, pointer, side) {
+  const mapped = mappedAt(snapshot, unitIndex, pointer);
   return { ...mapped, file: path.posix.join(side, mapped.file) };
 }
 
-function transitionDiagnostics(before, after, beforeBase, afterBase) {
+function transitionDiagnostics(before, after) {
   const diagnostics = [];
-  const afterById = new Map(after.ir.units.map((unit) => [unit.id, unit]));
-  before.ir.units.forEach((unit, index) => {
-    if (afterById.has(unit.id)) return;
-    const mapped = sideMappedAt(before, index, "/id", beforeBase, "before");
+  for (const entry of before.byId.values()) {
+    const { unit, unitIndex } = entry;
+    if (after.byId.has(unit.id)) continue;
+    const mapped = sideMappedAt(before, unitIndex, "/id", "before");
     diagnostics.push(makeDiagnostic({
       code: "AUTH_DIFF_TRANSITION_INVALID",
       file: mapped.file,
@@ -155,12 +156,12 @@ function transitionDiagnostics(before, after, beforeBase, afterBase) {
         ? "retain the removed tombstone; permanent reserved-ID storage is not admitted"
         : "replace the active unit with a valid removed tombstone carrying an explicit reason",
     }));
-  });
-  const beforeById = new Map(before.ir.units.map((unit) => [unit.id, unit]));
-  after.ir.units.forEach((unit, index) => {
-    const previous = beforeById.get(unit.id);
-    if (!previous) return;
-    const mapped = sideMappedAt(after, index, "/id", afterBase, "after");
+  }
+  for (const entry of after.byId.values()) {
+    const { unit, unitIndex } = entry;
+    const previous = before.byId.get(unit.id)?.unit;
+    if (!previous) continue;
+    const mapped = sideMappedAt(after, unitIndex, "/id", "after");
     if (previous.lifecycle === "removed" && unit.lifecycle !== "removed") diagnostics.push(makeDiagnostic({
       code: "AUTH_DIFF_TRANSITION_INVALID",
       file: mapped.file,
@@ -177,18 +178,16 @@ function transitionDiagnostics(before, after, beforeBase, afterBase) {
       reason: `authority identity cannot change kind from ${previous.kind} to ${unit.kind}: ${unit.id}`,
       repair: "retain the original identity and declare a distinct ID for the new kind",
     }));
-  });
+  }
   return sortDiagnostics(diagnostics);
 }
 
-function compareUnits(before, after, beforeBase, afterBase) {
+function compareUnits(before, after) {
   const changes = [];
-  const beforeById = new Map(before.ir.units.map((unit, index) => [unit.id, { unit, index, compiled: before }]));
-  const afterById = new Map(after.ir.units.map((unit, index) => [unit.id, { unit, index, compiled: after }]));
-  const ids = [...new Set([...beforeById.keys(), ...afterById.keys()])].sort(compareText);
+  const ids = [...new Set([...before.byId.keys(), ...after.byId.keys()])].sort(compareText);
   for (const id of ids) {
-    const left = beforeById.get(id);
-    const right = afterById.get(id);
+    const left = before.byId.get(id);
+    const right = after.byId.get(id);
     if (!left) {
       addChange(changes, {
         unitId: id,
@@ -196,16 +195,16 @@ function compareUnits(before, after, beforeBase, afterBase) {
         pointer: "",
         before: null,
         after: right.unit,
-        afterSource: mappedAt(after, right.index, "/id", afterBase),
+        afterSource: mappedAt(after, right.unitIndex, "/id"),
       });
       continue;
     }
     if (!right) continue;
     for (const pointer of ["/kind", "/owner", "/lifecycle", "/metadata/title", "/metadata/reason", "/semantic/meaning", "/semantic/modality", "/semantic/statement", "/semantic/condition", "/semantic/failure"]) {
-      compareScalar(changes, left, right, pointer, beforeBase, afterBase);
+      compareScalar(changes, before, after, left, right, pointer);
     }
-    compareValueSet(changes, left, right, "/semantic/scope", beforeBase, afterBase);
-    compareRelations(changes, left, right, beforeBase, afterBase);
+    compareValueSet(changes, before, after, left, right, "/semantic/scope");
+    compareRelations(changes, before, after, left, right);
   }
   return changes.sort((left, right) => (
     compareText(left.unitId, right.unitId)
@@ -231,7 +230,7 @@ function budgetDiagnostic(requiredBytes, maxBytes) {
   });
 }
 
-export async function diffAuthorityPaths(beforePath, afterPath, { maxBytes = null } = {}) {
+export async function diffAuthorityPathsWithSnapshots(beforePath, afterPath, { maxBytes = null } = {}) {
   const [before, after, beforeBase, afterBase] = await Promise.all([
     compileAuthorityPath(beforePath),
     compileAuthorityPath(afterPath),
@@ -239,24 +238,46 @@ export async function diffAuthorityPaths(beforePath, afterPath, { maxBytes = nul
     sourceRoot(afterPath),
   ]);
   if (!before.ok || !after.ok) return {
-    ok: false,
-    diagnostics: sortDiagnostics([
-      ...sideDiagnostics(before.diagnostics, beforeBase, "before"),
-      ...sideDiagnostics(after.diagnostics, afterBase, "after"),
-    ]),
-    fileCount: before.fileCount + after.fileCount,
-    unitCount: 0,
-    diff: null,
+    beforeSnapshot: null,
+    afterSnapshot: null,
+    result: {
+      ok: false,
+      diagnostics: sortDiagnostics([
+        ...sideDiagnostics(before.diagnostics, beforeBase, "before"),
+        ...sideDiagnostics(after.diagnostics, afterBase, "after"),
+      ]),
+      fileCount: before.fileCount + after.fileCount,
+      unitCount: 0,
+      diff: null,
+      partial: false,
+    },
+  };
+  const beforeSnapshot = createCompiledAuthoritySnapshot(before, beforeBase);
+  const afterSnapshot = createCompiledAuthoritySnapshot(after, afterBase);
+  return {
+    beforeSnapshot,
+    afterSnapshot,
+    result: diffAuthoritySnapshots(beforeSnapshot, afterSnapshot, { maxBytes }),
   };
-  const invalidTransitions = transitionDiagnostics(before, after, beforeBase, afterBase);
+}
+
+export async function diffAuthorityPaths(beforePath, afterPath, options = {}) {
+  return (await diffAuthorityPathsWithSnapshots(beforePath, afterPath, options)).result;
+}
+
+export function diffAuthoritySnapshots(beforeSnapshot, afterSnapshot, { maxBytes = null } = {}) {
+  const before = beforeSnapshot.compiled;
+  const after = afterSnapshot.compiled;
+  const invalidTransitions = transitionDiagnostics(beforeSnapshot, afterSnapshot);
   if (invalidTransitions.length > 0) return {
     ok: false,
     diagnostics: invalidTransitions,
     fileCount: before.fileCount + after.fileCount,
     unitCount: 0,
     diff: null,
+    partial: false,
   };
-  const changes = compareUnits(before, after, beforeBase, afterBase);
+  const changes = compareUnits(beforeSnapshot, afterSnapshot);
   const diff = {
     format: DIFF_FORMAT,
     changes,
@@ -273,15 +294,17 @@ export async function diffAuthorityPaths(beforePath, afterPath, { maxBytes = nul
     unitCount: 0,
     payloadBytes,
     diff: null,
+    partial: false,
   };
   return {
     ok: true,
     diagnostics: [],
     fileCount: before.fileCount + after.fileCount,
-    unitCount: new Set([...before.ir.units, ...after.ir.units].map((unit) => unit.id)).size,
+    unitCount: new Set([...beforeSnapshot.byId.keys(), ...afterSnapshot.byId.keys()]).size,
     payloadBytes,
     diff,
     before,
     after,
+    partial: false,
   };
 }