@nimiplatform/nimi-coding 0.3.1 → 0.5.0

package/cli/lib/authority/change-candidates.mjs

@@ -0,0 +1,807 @@
+import { Buffer } from "node:buffer";
+
+import { compareText, makeDiagnostic, portablePath } from "./diagnostics.mjs";
+import { diffAuthorityPathsWithSnapshots, diffAuthoritySnapshots } from "./diff.mjs";
+import { normalizeDiscoveryTerms } from "./discover.mjs";
+
+const CHANGE_CANDIDATES_FORMAT = "nimicoding.authority-change-candidates/v1";
+const SIDES = ["before", "after"];
+export const CHANGE_CANDIDATE_CHANNELS = Object.freeze([
+  "owner",
+  "scope",
+  "changed_term",
+  "direct_relation",
+  "definition_identity",
+  "definition_title",
+]);
+const CHANNEL_RANK = new Map(CHANGE_CANDIDATE_CHANNELS.map((channel, index) => [channel, index]));
+const RECALL_RELATION_TYPES = new Set(["applies_to", "supersedes"]);
+const TEXT_FIELD_POINTERS = new Map([
+  ["/metadata/title", "title"],
+  ["/semantic/meaning", "meaning"],
+  ["/semantic/statement", "statement"],
+  ["/semantic/condition", "condition"],
+  ["/semantic/failure", "failure"],
+]);
+const IDENTIFIER_TOKEN_CHARACTER = /[A-Za-z0-9_.-]/u;
+const WORD_CHARACTER = /[\p{L}\p{N}]/u;
+
+function portableLocation(mapped, basePath) {
+  return {
+    file: portablePath(mapped.file, basePath),
+    range: mapped.range,
+    sourcePointer: mapped.sourcePointer,
+  };
+}
+
+function mappedAt(side, unitIndex, pointer) {
+  return portableLocation(side.compiled.sourceMap.fields[`/units/${unitIndex}${pointer}`], side.inputRoot);
+}
+
+function validBudget(value) {
+  return Number.isSafeInteger(value) && value > 0;
+}
+
+function diagnostic(code, reason, repair) {
+  return makeDiagnostic({
+    code,
+    file: ".",
+    range: { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
+    pointer: "",
+    reason,
+    repair,
+  });
+}
+
+function refused(diagnostics, { fileCount = 0, candidateBytes = 0 } = {}) {
+  return {
+    ok: false,
+    diagnostics,
+    fileCount,
+    unitCount: 0,
+    candidateBytes,
+    changeCandidates: null,
+    partial: false,
+  };
+}
+
+function budgetDiagnostic(kind, required, admitted) {
+  const option = kind === "candidates" ? "max-candidates" : kind === "reasons" ? "max-reasons" : "max-bytes";
+  return diagnostic(
+    "AUTH_CHANGE_CANDIDATES_BUDGET",
+    `complete change-derived candidate discovery requires ${required} ${kind} but ${option} is ${admitted}`,
+    "increase the explicit budget; partial candidate unions, reasons, and payloads are forbidden",
+  );
+}
+
+function validateChannels(channels) {
+  if (!Array.isArray(channels) || channels.length === 0) return {
+    error: diagnostic(
+      "AUTH_CHANGE_CANDIDATES_CHANNELS",
+      "change-derived candidate discovery requires one non-empty channel array",
+      `provide one or more unique exact channels from: ${CHANGE_CANDIDATE_CHANNELS.join(", ")}`,
+    ),
+  };
+  const selected = new Set();
+  for (const channel of channels) {
+    if (typeof channel !== "string" || !CHANNEL_RANK.has(channel)) return {
+      error: diagnostic(
+        "AUTH_CHANGE_CANDIDATES_CHANNELS",
+        `change-derived candidate discovery channel is not admitted: ${String(channel)}`,
+        `provide only unique exact channels from: ${CHANGE_CANDIDATE_CHANNELS.join(", ")}`,
+      ),
+    };
+    if (selected.has(channel)) return {
+      error: diagnostic(
+        "AUTH_CHANGE_CANDIDATES_CHANNELS",
+        `change-derived candidate discovery channel is duplicated: ${channel}`,
+        "provide every requested channel exactly once",
+      ),
+    };
+    selected.add(channel);
+  }
+  return {
+    channels: CHANGE_CANDIDATE_CHANNELS.filter((channel) => selected.has(channel)),
+  };
+}
+
+function rawTextFields(entry) {
+  const fields = [{ field: "title", raw: entry.unit.metadata.title, pointer: "/metadata/title" }];
+  if (entry.unit.lifecycle === "removed") return fields;
+  if (entry.unit.kind === "definition") {
+    fields.push({ field: "meaning", raw: entry.unit.semantic.meaning, pointer: "/semantic/meaning" });
+  } else {
+    fields.push(
+      { field: "statement", raw: entry.unit.semantic.statement, pointer: "/semantic/statement" },
+      { field: "condition", raw: entry.unit.semantic.condition, pointer: "/semantic/condition" },
+      { field: "failure", raw: entry.unit.semantic.failure, pointer: "/semantic/failure" },
+    );
+  }
+  return fields;
+}
+
+function rawFieldEndpoint(side, entry, field, raw, pointer) {
+  return { field, raw, location: mappedAt(side, entry.unitIndex, pointer) };
+}
+
+function compareReasons(left, right) {
+  return CHANNEL_RANK.get(left.channel) - CHANNEL_RANK.get(right.channel)
+    || SIDES.indexOf(left.side) - SIDES.indexOf(right.side)
+    || compareText(left.rootId, right.rootId)
+    || compareText(JSON.stringify(left.witness), JSON.stringify(right.witness));
+}
+
+function buildRootLexicalFields(diffResult, side) {
+  const selected = new Map();
+  for (const change of diffResult.diff.changes) {
+    const entry = side.byId.get(change.unitId);
+    if (!entry) continue;
+    if (change.operation === "unit_added") {
+      if (side.name !== "after") continue;
+      for (const field of rawTextFields(entry)) {
+        const terms = normalizeDiscoveryTerms(field.raw);
+        if (terms.length === 0) continue;
+        const key = JSON.stringify([change.unitId, field.field, field.raw]);
+        selected.set(key, { key, rootId: change.unitId, ...field, terms });
+      }
+      continue;
+    }
+    const field = TEXT_FIELD_POINTERS.get(change.pointer);
+    const raw = side.name === "before" ? change.before : change.after;
+    if (field === undefined || typeof raw !== "string") continue;
+    const otherRaw = side.name === "before" ? change.after : change.before;
+    const otherTerms = new Set(typeof otherRaw === "string" ? normalizeDiscoveryTerms(otherRaw) : []);
+    const terms = normalizeDiscoveryTerms(raw).filter((term) => !otherTerms.has(term));
+    if (terms.length === 0) continue;
+    const key = JSON.stringify([change.unitId, field, raw]);
+    selected.set(key, {
+      key,
+      rootId: change.unitId,
+      field,
+      raw,
+      pointer: change.pointer,
+      terms,
+    });
+  }
+  return [...selected.values()].sort((left, right) => (
+    compareText(left.rootId, right.rootId)
+    || compareText(left.field, right.field)
+    || compareText(left.raw, right.raw)
+  ));
+}
+
+function buildDefinitionAnchors(roots, side) {
+  const anchors = new Map();
+  function add(rootId, definition, rootReference) {
+    const key = JSON.stringify([
+      rootId,
+      definition.unit.id,
+      rootReference.kind,
+      rootReference.relationIndex ?? null,
+    ]);
+    anchors.set(key, { key, rootId, definition, rootReference });
+  }
+  for (const rootId of roots) {
+    const root = side.byId.get(rootId);
+    if (!root) continue;
+    if (root.unit.kind === "definition") add(rootId, root, { kind: "root_definition" });
+    root.unit.relations.forEach((relation, relationIndex) => {
+      if (!RECALL_RELATION_TYPES.has(relation.type)) return;
+      const target = side.byId.get(relation.target);
+      if (target.unit.kind !== "definition") return;
+      add(rootId, target, { kind: "root_relation", relationIndex });
+    });
+  }
+  return [...anchors.values()].sort((left, right) => compareText(left.key, right.key));
+}
+
+function compareOccurrence(left, right) {
+  return compareText(left.candidateId, right.candidateId)
+    || compareText(left.field.pointer, right.field.pointer);
+}
+
+function buildCandidateTextIndex(side, candidates, { terms, patterns }) {
+  const fieldsByCandidate = new Map();
+  const termOccurrences = new Map();
+  for (const afterEntry of candidates) {
+    const entry = side.byId.get(afterEntry.unit.id);
+    const fields = rawTextFields(entry).map((field) => {
+      const indexed = { ...field };
+      if (patterns) {
+        indexed.normalized = field.raw.normalize("NFKC");
+        indexed.symbols = Array.from(indexed.normalized);
+      }
+      if (terms) {
+        indexed.terms = normalizeDiscoveryTerms(field.raw);
+        indexed.termSet = new Set(indexed.terms);
+      }
+      return indexed;
+    });
+    fieldsByCandidate.set(entry.unit.id, fields);
+    if (!terms) continue;
+    for (const field of fields) {
+      for (const term of field.terms) {
+        const occurrences = termOccurrences.get(term) ?? [];
+        occurrences.push({ candidateId: entry.unit.id, field });
+        termOccurrences.set(term, occurrences);
+      }
+    }
+  }
+  for (const occurrences of termOccurrences.values()) occurrences.sort(compareOccurrence);
+  return { fieldsByCandidate, termOccurrences };
+}
+
+function buildPatternMatcher(anchors, requested) {
+  const patterns = new Map();
+  function add(channel, anchor, raw, boundary) {
+    const normalized = raw.normalize("NFKC");
+    const pattern = patterns.get(normalized) ?? {
+      normalized,
+      symbols: Array.from(normalized),
+      records: [],
+    };
+    pattern.records.push({ channel, anchor, boundary });
+    patterns.set(normalized, pattern);
+  }
+  for (const anchor of anchors) {
+    if (requested.has("definition_identity")) {
+      add("definition_identity", anchor, anchor.definition.unit.id, IDENTIFIER_TOKEN_CHARACTER);
+    }
+    if (requested.has("definition_title")) {
+      add("definition_title", anchor, anchor.definition.unit.metadata.title, WORD_CHARACTER);
+    }
+  }
+  if (patterns.size === 0) return null;
+
+  const nodes = [{ next: new Map(), failure: 0, outputs: [] }];
+  for (const pattern of [...patterns.values()].sort((left, right) => compareText(left.normalized, right.normalized))) {
+    let state = 0;
+    for (const symbol of pattern.symbols) {
+      let next = nodes[state].next.get(symbol);
+      if (next === undefined) {
+        next = nodes.length;
+        nodes[state].next.set(symbol, next);
+        nodes.push({ next: new Map(), failure: 0, outputs: [] });
+      }
+      state = next;
+    }
+    nodes[state].outputs.push(pattern.normalized);
+  }
+
+  const pending = [];
+  for (const next of nodes[0].next.values()) pending.push(next);
+  for (let cursor = 0; cursor < pending.length; cursor += 1) {
+    const state = pending[cursor];
+    for (const [symbol, next] of nodes[state].next) {
+      pending.push(next);
+      let failure = nodes[state].failure;
+      while (failure !== 0 && !nodes[failure].next.has(symbol)) failure = nodes[failure].failure;
+      if (nodes[failure].next.has(symbol)) failure = nodes[failure].next.get(symbol);
+      nodes[next].failure = failure;
+      nodes[next].outputs = [...new Set([...nodes[next].outputs, ...nodes[failure].outputs])].sort(compareText);
+    }
+  }
+
+  return {
+    patterns,
+    scan(symbols, visit) {
+      let state = 0;
+      symbols.forEach((symbol, index) => {
+        while (state !== 0 && !nodes[state].next.has(symbol)) state = nodes[state].failure;
+        if (nodes[state].next.has(symbol)) state = nodes[state].next.get(symbol);
+        for (const patternId of nodes[state].outputs) {
+          const pattern = patterns.get(patternId);
+          const start = index - pattern.symbols.length + 1;
+          for (const record of pattern.records) {
+            const before = start === 0 ? "" : symbols[start - 1];
+            const after = index + 1 === symbols.length ? "" : symbols[index + 1];
+            if (!record.boundary.test(before) && !record.boundary.test(after)) {
+              visit(record);
+            }
+          }
+        }
+      });
+    },
+  };
+}
+
+function buildSideSearch(side, candidates, roots, diffResult, requested) {
+  const needsTerms = requested.has("changed_term");
+  const needsPatterns = requested.has("definition_identity") || requested.has("definition_title");
+  const anchors = needsPatterns ? buildDefinitionAnchors(roots, side) : [];
+  return {
+    side,
+    text: buildCandidateTextIndex(side, candidates, { terms: needsTerms, patterns: needsPatterns }),
+    rootLexicalFields: needsTerms ? buildRootLexicalFields(diffResult, side) : [],
+    anchors,
+    matcher: needsPatterns ? buildPatternMatcher(anchors, requested) : null,
+  };
+}
+
+function buildContext(diffResult, beforeSnapshot, afterSnapshot, requestedChannels) {
+  const sides = {
+    before: {
+      name: "before",
+      ...beforeSnapshot,
+    },
+    after: {
+      name: "after",
+      ...afterSnapshot,
+    },
+  };
+  const roots = [...new Set(diffResult.diff.changes.map((change) => change.unitId))].sort(compareText);
+  const rootSet = new Set(roots);
+  const candidates = [...sides.after.byId.values()]
+    .filter(({ unit }) => unit.lifecycle === "active" && !rootSet.has(unit.id))
+    .sort((left, right) => compareText(left.unit.id, right.unit.id));
+  const candidateSet = new Set(candidates.map(({ unit }) => unit.id));
+  const requested = new Set(requestedChannels);
+  return {
+    diffResult,
+    sides,
+    roots,
+    rootSet,
+    candidates,
+    candidateSet,
+    requestedChannels,
+    requested,
+    searches: {
+      before: buildSideSearch(sides.before, candidates, roots, diffResult, requested),
+      after: buildSideSearch(sides.after, candidates, roots, diffResult, requested),
+    },
+  };
+}
+
+function visitOwnerMatches(context, search, visit) {
+  const { side } = search;
+  for (const rootId of context.roots) {
+    const root = side.byId.get(rootId);
+    if (!root) continue;
+    for (const entry of side.byOwner.get(root.unit.owner) ?? []) {
+      if (!context.candidateSet.has(entry.unit.id)) continue;
+      visit({ channel: "owner", side, rootId, candidateId: entry.unit.id });
+    }
+  }
+}
+
+function visitScopeMatches(context, search, visit) {
+  const { side } = search;
+  for (const rootId of context.roots) {
+    const root = side.byId.get(rootId);
+    for (const value of root?.unit.semantic?.scope ?? []) {
+      for (const entry of side.byScope.get(value) ?? []) {
+        if (!context.candidateSet.has(entry.unit.id)) continue;
+        visit({ channel: "scope", side, rootId, candidateId: entry.unit.id, value });
+      }
+    }
+  }
+}
+
+function visitChangedTermMatches(context, search, visit) {
+  for (const rootField of search.rootLexicalFields) {
+    const matchedFields = new Map();
+    for (const term of rootField.terms) {
+      for (const occurrence of search.text.termOccurrences.get(term) ?? []) {
+        const key = JSON.stringify([occurrence.candidateId, occurrence.field.pointer]);
+        if (matchedFields.has(key)) continue;
+        matchedFields.set(key, {
+          channel: "changed_term",
+          side: search.side,
+          rootId: rootField.rootId,
+          candidateId: occurrence.candidateId,
+          rootField,
+          candidateField: occurrence.field,
+        });
+      }
+    }
+    for (const match of [...matchedFields.values()].sort((left, right) => (
+      compareText(left.candidateId, right.candidateId)
+      || compareText(left.candidateField.pointer, right.candidateField.pointer)
+    ))) visit(match);
+  }
+}
+
+function visitDirectRelationMatches(context, search, visit) {
+  const { side } = search;
+  for (const rootId of context.roots) {
+    if (!side.byId.has(rootId)) continue;
+    for (const edge of side.outgoing.get(rootId) ?? []) {
+      if (!RECALL_RELATION_TYPES.has(edge.type) || !context.candidateSet.has(edge.target)) continue;
+      visit({ channel: "direct_relation", side, rootId, candidateId: edge.target, direction: "outgoing", edge });
+    }
+    for (const edge of side.incoming.get(rootId) ?? []) {
+      if (!RECALL_RELATION_TYPES.has(edge.type) || !context.candidateSet.has(edge.source)) continue;
+      visit({ channel: "direct_relation", side, rootId, candidateId: edge.source, direction: "incoming", edge });
+    }
+  }
+}
+
+function visitDefinitionRelationMatches(context, search, visit) {
+  const { side } = search;
+  for (const anchor of search.anchors) {
+    for (const edge of side.incoming.get(anchor.definition.unit.id) ?? []) {
+      if (!RECALL_RELATION_TYPES.has(edge.type) || !context.candidateSet.has(edge.source)) continue;
+      visit({
+        channel: "definition_identity",
+        side,
+        rootId: anchor.rootId,
+        candidateId: edge.source,
+        match: "shared_exact_authored_definition_target",
+        anchor,
+        edge,
+      });
+    }
+  }
+}
+
+function visitDefinitionTextMatches(search, visit) {
+  if (search.matcher === null) return;
+  for (const [candidateId, fields] of search.text.fieldsByCandidate) {
+    for (const field of fields) {
+      const matchedPatterns = new Map();
+      search.matcher.scan(field.symbols, (record) => {
+        const key = JSON.stringify([record.channel, record.anchor.key]);
+        if (matchedPatterns.has(key)) return;
+        matchedPatterns.set(key, {
+          channel: record.channel,
+          side: search.side,
+          rootId: record.anchor.rootId,
+          candidateId,
+          match: record.channel === "definition_identity"
+            ? "exact_definition_identity_text"
+            : "exact_NFKC_case_sensitive_definition_title_phrase",
+          anchor: record.anchor,
+          candidateField: field,
+        });
+      });
+      for (const match of [...matchedPatterns.values()].sort((left, right) => (
+        CHANNEL_RANK.get(left.channel) - CHANNEL_RANK.get(right.channel)
+        || compareText(left.anchor.key, right.anchor.key)
+      ))) visit(match);
+    }
+  }
+}
+
+function visitMatches(context, visit) {
+  for (const sideName of SIDES) {
+    const search = context.searches[sideName];
+    if (context.requested.has("owner")) visitOwnerMatches(context, search, visit);
+    if (context.requested.has("scope")) visitScopeMatches(context, search, visit);
+    if (context.requested.has("changed_term")) visitChangedTermMatches(context, search, visit);
+    if (context.requested.has("direct_relation")) visitDirectRelationMatches(context, search, visit);
+    if (context.requested.has("definition_identity")) visitDefinitionRelationMatches(context, search, visit);
+    if (context.requested.has("definition_identity") || context.requested.has("definition_title")) {
+      visitDefinitionTextMatches(search, visit);
+    }
+  }
+}
+
+function reasonKey(match) {
+  if (match.channel === "owner") return JSON.stringify([
+    match.channel, match.side.name, match.rootId, match.candidateId,
+  ]);
+  if (match.channel === "scope") return JSON.stringify([
+    match.channel, match.side.name, match.rootId, match.candidateId, match.value,
+  ]);
+  if (match.channel === "changed_term") return JSON.stringify([
+    match.channel, match.side.name, match.rootField.key, match.candidateId, match.candidateField.pointer,
+  ]);
+  if (match.channel === "direct_relation") return JSON.stringify([
+    match.channel, match.side.name, match.rootId, match.candidateId, match.direction,
+    match.edge.source, match.edge.type, match.edge.target,
+  ]);
+  if (match.match === "shared_exact_authored_definition_target") return JSON.stringify([
+    match.channel, match.side.name, match.anchor.key, match.candidateId, match.match,
+    match.edge.source, match.edge.type, match.edge.target,
+  ]);
+  return JSON.stringify([
+    match.channel, match.side.name, match.anchor.key, match.candidateId, match.match, match.candidateField.pointer,
+  ]);
+}
+
+// Stage 1 deliberately records only IDs. It computes the exact union before
+// any SourceMap witness, candidate record, proximity hint, or payload exists.
+function discoverCandidateIds(context) {
+  const selected = new Set();
+  visitMatches(context, (match) => selected.add(match.candidateId));
+  return [...selected].sort(compareText);
+}
+
+// Every channel visitor emits one record per unique logical reason. Stage 2
+// can therefore obtain the exact count without retaining keys or witnesses.
+function countUniqueReasons(context) {
+  let count = 0;
+  visitMatches(context, () => { count += 1; });
+  return count;
+}
+
+function relationRecord(side, edge) {
+  const source = side.byId.get(edge.source);
+  const target = side.byId.get(edge.target);
+  return {
+    source: edge.source,
+    type: edge.type,
+    target: edge.target,
+    sourceLocation: mappedAt(side, source.unitIndex, "/id"),
+    relationLocation: mappedAt(side, edge.sourceUnitIndex, `/relations/${edge.relationIndex}/target`),
+    targetLocation: mappedAt(side, target.unitIndex, "/id"),
+  };
+}
+
+function materializeRootReference(side, anchor) {
+  const root = side.byId.get(anchor.rootId);
+  if (anchor.rootReference.kind === "root_definition") {
+    return rawFieldEndpoint(side, root, "id", anchor.rootId, "/id");
+  }
+  const relationIndex = anchor.rootReference.relationIndex;
+  return rawFieldEndpoint(
+    side,
+    root,
+    "relations",
+    root.unit.relations[relationIndex],
+    `/relations/${relationIndex}/target`,
+  );
+}
+
+function definitionRecord(side, anchor) {
+  return {
+    id: anchor.definition.unit.id,
+    title: anchor.definition.unit.metadata.title,
+    idLocation: mappedAt(side, anchor.definition.unitIndex, "/id"),
+    titleLocation: mappedAt(side, anchor.definition.unitIndex, "/metadata/title"),
+  };
+}
+
+function materializeReason(match) {
+  const { side, rootId, candidateId } = match;
+  const root = side.byId.get(rootId);
+  const candidate = side.byId.get(candidateId);
+  if (match.channel === "owner") return {
+    channel: match.channel,
+    side: side.name,
+    rootId,
+    witness: {
+      match: "exact_owner",
+      value: root.unit.owner,
+      root: rawFieldEndpoint(side, root, "owner", root.unit.owner, "/owner"),
+      candidate: rawFieldEndpoint(side, candidate, "owner", candidate.unit.owner, "/owner"),
+    },
+  };
+  if (match.channel === "scope") {
+    const rootIndex = root.unit.semantic.scope.indexOf(match.value);
+    const candidateIndex = candidate.unit.semantic.scope.indexOf(match.value);
+    return {
+      channel: match.channel,
+      side: side.name,
+      rootId,
+      witness: {
+        match: "exact_scope",
+        value: match.value,
+        root: rawFieldEndpoint(side, root, "scope", match.value, `/semantic/scope/${rootIndex}`),
+        candidate: rawFieldEndpoint(side, candidate, "scope", match.value, `/semantic/scope/${candidateIndex}`),
+      },
+    };
+  }
+  if (match.channel === "changed_term") {
+    const terms = match.rootField.terms
+      .filter((term) => match.candidateField.termSet.has(term))
+      .sort(compareText);
+    return {
+      channel: match.channel,
+      side: side.name,
+      rootId,
+      witness: {
+        match: "exact_normalized_term",
+        terms,
+        root: {
+          field: match.rootField.field,
+          raw: match.rootField.raw,
+          location: mappedAt(side, root.unitIndex, match.rootField.pointer),
+        },
+        candidate: {
+          field: match.candidateField.field,
+          raw: match.candidateField.raw,
+          location: mappedAt(side, candidate.unitIndex, match.candidateField.pointer),
+        },
+      },
+    };
+  }
+  if (match.channel === "direct_relation") return {
+    channel: match.channel,
+    side: side.name,
+    rootId,
+    witness: {
+      match: "direct_authored_relation",
+      rootTraversal: match.direction,
+      relation: relationRecord(side, match.edge),
+      root: rawFieldEndpoint(side, root, "id", rootId, "/id"),
+      candidate: rawFieldEndpoint(side, candidate, "id", candidateId, "/id"),
+    },
+  };
+  const shared = {
+    match: match.match,
+    definition: definitionRecord(side, match.anchor),
+    root: materializeRootReference(side, match.anchor),
+  };
+  if (match.match === "shared_exact_authored_definition_target") {
+    const relation = candidate.unit.relations[match.edge.relationIndex];
+    shared.candidate = rawFieldEndpoint(
+      side,
+      candidate,
+      "relations",
+      relation,
+      `/relations/${match.edge.relationIndex}/target`,
+    );
+  } else {
+    shared.candidate = {
+      field: match.candidateField.field,
+      raw: match.candidateField.raw,
+      location: mappedAt(side, candidate.unitIndex, match.candidateField.pointer),
+    };
+  }
+  return { channel: match.channel, side: side.name, rootId, witness: shared };
+}
+
+function candidateRecord(entry, reasons, afterSide) {
+  const { unit } = entry;
+  return {
+    id: unit.id,
+    kind: unit.kind,
+    owner: unit.owner,
+    lifecycle: unit.lifecycle,
+    title: unit.metadata.title,
+    modality: unit.kind === "rule" ? unit.semantic.modality : null,
+    scope: unit.kind === "rule" ? [...unit.semantic.scope] : [],
+    rawFields: {
+      meaning: unit.kind === "definition" ? unit.semantic.meaning : null,
+      statement: unit.kind === "rule" ? unit.semantic.statement : null,
+      condition: unit.kind === "rule" ? unit.semantic.condition : null,
+      failure: unit.kind === "rule" ? unit.semantic.failure : null,
+    },
+    relations: unit.relations.map((relation) => ({ ...relation })),
+    primaryIdLocation: mappedAt(afterSide, entry.unitIndex, "/id"),
+    reasons,
+  };
+}
+
+// Stage 3 is the only path that materializes SourceMap witnesses, full
+// candidate records, roots, or a product payload.
+function materializeCandidateRecords(context, selectedIds, expectedReasonCount) {
+  const selected = new Map(selectedIds.map((id) => [id, new Map()]));
+  visitMatches(context, (match) => {
+    const reasons = selected.get(match.candidateId);
+    const key = reasonKey(match);
+    if (!reasons.has(key)) reasons.set(key, materializeReason(match));
+  });
+  const actualReasonCount = [...selected.values()].reduce((total, reasons) => total + reasons.size, 0);
+  if (actualReasonCount !== expectedReasonCount) {
+    throw new Error(`change-candidate reason materialization drifted: counted ${expectedReasonCount}, materialized ${actualReasonCount}`);
+  }
+  return selectedIds.map((id) => {
+    const entry = context.sides.after.byId.get(id);
+    const reasons = [...selected.get(id).values()].sort(compareReasons);
+    return candidateRecord(entry, reasons, context.sides.after);
+  });
+}
+
+function rootSideRecord(side, rootId) {
+  const entry = side.byId.get(rootId);
+  if (!entry) return null;
+  return {
+    kind: entry.unit.kind,
+    owner: entry.unit.owner,
+    lifecycle: entry.unit.lifecycle,
+    title: entry.unit.metadata.title,
+    location: mappedAt(side, entry.unitIndex, "/id"),
+  };
+}
+
+function rootRecords(context) {
+  return context.roots.map((id) => ({
+    id,
+    changes: context.diffResult.diff.changes
+      .filter((change) => change.unitId === id)
+      .map(({ operation, pointer }) => ({ operation, pointer })),
+    before: rootSideRecord(context.sides.before, id),
+    after: rootSideRecord(context.sides.after, id),
+  }));
+}
+
+export function canonicalChangeCandidatesBytes(changeCandidates) {
+  return Buffer.byteLength(JSON.stringify(changeCandidates), "utf8");
+}
+
+function validateRequest({
+  channels,
+  maxCandidates,
+  maxReasons,
+  maxBytes,
+}) {
+  const channelValidation = validateChannels(channels);
+  if (channelValidation.error) return { failure: refused([channelValidation.error]) };
+  if (![maxCandidates, maxReasons, maxBytes].every(validBudget)) return { failure: refused([diagnostic(
+    "AUTH_CHANGE_CANDIDATES_BUDGET",
+    "change-derived candidate discovery budgets must be positive safe integers",
+    "provide explicit positive safe max-candidates, max-reasons, and max-bytes budgets",
+  )]) };
+  return { channelValidation };
+}
+
+function changeCandidatesAuthorityDiffSnapshots(diffResult, beforeSnapshot, afterSnapshot, request) {
+  const { channelValidation, maxCandidates, maxReasons, maxBytes } = request;
+  if (!diffResult.ok) return refused(diffResult.diagnostics, { fileCount: diffResult.fileCount });
+  const context = buildContext(diffResult, beforeSnapshot, afterSnapshot, channelValidation.channels);
+
+  const selectedIds = discoverCandidateIds(context);
+  if (selectedIds.length > maxCandidates) return refused([
+    budgetDiagnostic("candidates", selectedIds.length, maxCandidates),
+  ], { fileCount: diffResult.fileCount });
+
+  const reasonCount = countUniqueReasons(context);
+  if (reasonCount > maxReasons) return refused([
+    budgetDiagnostic("reasons", reasonCount, maxReasons),
+  ], { fileCount: diffResult.fileCount });
+
+  const candidateRecords = materializeCandidateRecords(context, selectedIds, reasonCount);
+  const changeCandidates = {
+    format: CHANGE_CANDIDATES_FORMAT,
+    complete: true,
+    requestedChannels: context.requestedChannels,
+    roots: rootRecords(context),
+    candidates: candidateRecords,
+    counts: {
+      beforeUnits: context.sides.before.compiled.ir.units.length,
+      afterUnits: context.sides.after.compiled.ir.units.length,
+      changedRoots: context.roots.length,
+      eligibleAfterUnits: context.candidates.length,
+      candidates: candidateRecords.length,
+      reasons: reasonCount,
+    },
+    budgets: { maxCandidates, maxReasons, maxBytes },
+    policy: {
+      roots: "all_units_named_by_the_complete_semantic_diff",
+      candidateUniverse: "after_active_non_root_units_only",
+      recall: "complete_union_of_requested_channels_only",
+      changedTerms: "only_before_removed_and_after_added_normalized_term_set_deltas_from_changed_title_or_normative_text_values",
+      ordering: "candidate_ID_then_channel_side_root_and_exact_witness",
+      interpretation: "candidate_recall_only_without_conflict_retirement_authority_or_conformance_judgment",
+    },
+  };
+  const candidateBytes = canonicalChangeCandidatesBytes(changeCandidates);
+  if (candidateBytes > maxBytes) return refused([
+    budgetDiagnostic("UTF-8 bytes", candidateBytes, maxBytes),
+  ], { fileCount: diffResult.fileCount, candidateBytes });
+  return {
+    ok: true,
+    diagnostics: [],
+    fileCount: diffResult.fileCount,
+    unitCount: candidateRecords.length,
+    candidateBytes,
+    changeCandidates,
+    partial: false,
+  };
+}
+
+export function changeCandidatesAuthoritySnapshots(beforeSnapshot, afterSnapshot, options) {
+  const validation = validateRequest(options);
+  if (validation.failure) return validation.failure;
+  return changeCandidatesAuthorityDiffSnapshots(
+    diffAuthoritySnapshots(beforeSnapshot, afterSnapshot),
+    beforeSnapshot,
+    afterSnapshot,
+    { ...options, ...validation },
+  );
+}
+
+export async function changeCandidatesAuthorityPaths(beforePath, afterPath, options) {
+  const validation = validateRequest(options);
+  if (validation.failure) return validation.failure;
+  const admitted = await diffAuthorityPathsWithSnapshots(beforePath, afterPath);
+  if (!admitted.result.ok) return refused(admitted.result.diagnostics, { fileCount: admitted.result.fileCount });
+  return changeCandidatesAuthorityDiffSnapshots(
+    admitted.result,
+    admitted.beforeSnapshot,
+    admitted.afterSnapshot,
+    { ...options, ...validation },
+  );
+}