@documentation-robotics/cli 0.3.0 → 0.4.0

package/dist/core/changeset-verify.js

@@ -2,6 +2,11 @@ import { Changeset } from "./changeset.js";
 import { ChangesetGraph } from "./changeset-graph.js";
 import { tryReadBaseIndex } from "./changeset-base-index.js";
 import { stagedSourceReference } from "./staged-source-reference.js";
+import { loadExtractionCoverage } from "./extraction-observability.js";
+import { currentGitHead, resolveAnalyzerName } from "../analyzers/active-analyzer.js";
+import { decisionKey } from "../analyzers/extraction-plan.js";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
 const LIFECYCLE_FIELDS = ["attributes.status"], LIFECYCLE_STAGES = [
   ["proposed", "draft"],
   ["planned", "under-review"],
@@ -21,6 +26,37 @@ function isLifecycleMove(difference) {
   const from = lifecycleStage(difference.planned), to = lifecycleStage(difference.built);
   return from >= 0 && to > from;
 }
+function readList(value, keep) {
+  return Array.isArray(value) ? value.filter((e) => e && typeof e == "object" && keep(e)) : [];
+}
+async function readRecordFile(file) {
+  try {
+    const parsed = JSON.parse(await readFile(file, "utf-8"));
+    return parsed && typeof parsed == "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+async function readExtractionRecord(rootPath, changeset, gitHead) {
+  const dir = path.join(rootPath, ".dr", "analyzers", "extract");
+  let raw = await readRecordFile(path.join(dir, `${changeset.id.replace(/[^\w.-]/g, "_")}.json`)), source = "changeset";
+  if (raw && (raw.pending || raw.changesetId !== void 0 && raw.changesetId !== changeset.id) && (raw = null), !raw) {
+    const pending = await readRecordFile(path.join(dir, "pending.json"));
+    pending?.pending && pending.changesetName === changeset.name && (raw = pending, source = "pending");
+  }
+  if (!raw)
+    return null;
+  const symbol = (e) => typeof e.symbol == "string", readAt = source === "pending" && typeof raw.gitHead == "string" && raw.gitHead !== gitHead ? raw.gitHead : void 0;
+  return {
+    source,
+    ...readAt ? { readAt } : {},
+    staged: readList(raw.staged, (e) => typeof e.id == "string"),
+    cards: readList(raw.cards, symbol),
+    earlierCards: readList(raw.earlierCards, symbol),
+    updated: readList(raw.updated, (e) => typeof e.id == "string"),
+    candidateDeletes: Array.isArray(raw.candidateDeletes) ? raw.candidateDeletes.filter((d) => typeof d == "string") : []
+  };
+}
 function planFromChangeset(changeset, context = {}) {
   const resolve = context.resolve ?? ((id) => id), notes = [], elements = /* @__PURE__ */ new Map(), relationships = /* @__PURE__ */ new Map(), changes = [...changeset.changes].map((change, index) => ({ change, index })).sort((a, b) => (a.change.sequenceNumber ?? a.index) - (b.change.sequenceNumber ?? b.index));
   for (const { change, index } of changes) {
@@ -84,9 +120,17 @@ async function planFromModel(model, changeset) {
 function builtFromGraph(graph, label = graph.changeset.name) {
   const elements = [], changedElements = [];
   for (const element of graph.elements.values()) {
+    const staged = element.status === "added" || element.status === "updated" && !sameValue(element.sourceReference ?? null, (element.before && stagedSourceReference(element.before)) ?? null), current = fromGraphElement(element);
+    let updatedFrom;
+    if (element.status === "updated" && element.before) {
+      const before = toVerifyElement(element.before, element.layer, element.id);
+      updatedFrom = Object.fromEntries(changedFields(before, current).map((f) => [f, fieldValue(before, f)])), sameValue(current.sourceReference ?? null, before.sourceReference ?? null) || (updatedFrom.source_reference = before.sourceReference ?? null);
+    }
     const built = {
-      ...fromGraphElement(element),
-      ...element.status !== "unchanged" ? { change: element.status } : {}
+      ...current,
+      ...element.status !== "unchanged" ? { change: element.status } : {},
+      ...staged ? { stagedProvenance: element.sourceReference?.provenance ?? "none" } : {},
+      ...updatedFrom ? { updatedFrom } : {}
     };
     element.status !== "deleted" && elements.push(built), element.status !== "unchanged" && changedElements.push(built);
   }
@@ -143,9 +187,29 @@ function verifyChangeset(plan, built, options = {}) {
     verdict: "match",
     verdictText: "",
     summary: { elements: emptyCounts(), relationships: emptyCounts() },
-    elements: { matched: [], divergent: [], missing: [], unplanned: [], deletionsNotDone: [] },
-    relationships: { matched: [], divergent: [], missing: [], unplanned: [], deletionsNotDone: [] },
+    elements: { matched: [], divergent: [], missing: [], unverifiable: [], unplanned: [], deletionsNotDone: [] },
+    relationships: { matched: [], divergent: [], missing: [], unverifiable: [], unplanned: [], deletionsNotDone: [] },
     notes
+  }, observability = options.observability, unverifiableIds = /* @__PURE__ */ new Map(), missingHints = /* @__PURE__ */ new Map(), markUnverifiable = (planned) => {
+    if (!observability)
+      return !1;
+    const verdict2 = observability.element(planned);
+    if (verdict2.observable)
+      return !1;
+    if (verdict2.unlocated) {
+      const others = (built.changedElements ?? []).filter((e) => e.change !== "deleted" && e.layer === planned.layer && sameType(e, planned) && !claimed.has(e.id));
+      if (others.length > 0)
+        return missingHints.set(planned.id, `not found in the build by id or name, and it has no method, path or source reference to find it by; the build has ${others.length} unplanned ${planned.layer}.${planned.type} element(s) (${others.slice(0, 5).map((e) => e.id).join(", ")}${others.length > 5 ? ", ..." : ""}). If one of them is this one, give the plan's element its http_method and http_path, or its sourceFile and sourceSymbol, and verify again`), !1;
+    }
+    const reason = verdict2.reason ?? "extraction can't produce it";
+    return unverifiableIds.set(planned.id, reason), report.elements.unverifiable.push({
+      planned: planned.id,
+      layer: planned.layer,
+      type: planned.type,
+      name: planned.name,
+      op: planned.op,
+      reason
+    }), !0;
   }, live = plan.elements.filter((e) => e.op !== "delete"), deletions = plan.elements.filter((e) => e.op === "delete");
   for (const planned of live)
     builtById.has(planned.id) && (claimed.add(planned.id), elementMap.set(planned.id, { built: planned.id, match: "exact" }));
@@ -219,6 +283,8 @@ function verifyChangeset(plan, built, options = {}) {
   for (const planned of live) {
     const mapping = elementMap.get(planned.id);
     if (!mapping) {
+      if (markUnverifiable(planned))
+        continue;
       const candidates = ambiguous.get(planned.id);
       report.elements.missing.push({
         planned: planned.id,
@@ -226,21 +292,39 @@ function verifyChangeset(plan, built, options = {}) {
         type: planned.type,
         name: planned.name,
         op: planned.op,
-        reason: candidates ? `several built elements could be it (${candidates.length}); none matched uniquely` : planned.op === "update" ? "the element the plan updates does not exist in the build" : "not found in the build by id, name or source file",
+        reason: candidates ? `several built elements could be it (${candidates.length}); none matched uniquely` : planned.op === "update" ? "the element the plan updates does not exist in the build" : missingHints.get(planned.id) ?? "not found in the build by id, name or source file",
         ...candidates ? { candidates } : {}
       });
       continue;
     }
-    const builtElement = builtById.get(mapping.built), fields = compareElements(planned, builtElement, planned.op === "update" ? planned.changedFields : void 0), match = {
+    const builtElement = builtById.get(mapping.built);
+    let fields = compareElements(planned, builtElement, planned.op === "update" ? planned.changedFields : void 0);
+    const match = {
       planned: planned.id,
       built: mapping.built,
       op: planned.op,
       match: mapping.match,
       ...mapping.reason ? { reason: mapping.reason } : {}
-    };
-    if (planned.op === "update" && planned.changedFields && planned.changedFields.length > 0) {
-      const unmet = fields.filter((f) => planned.changedFields.includes(f.field)), touched = unmet.some((f) => buildTouched(planned, builtElement, f.field));
-      if (unmet.length === planned.changedFields.length && !touched) {
+    }, unverifiableFields = observability?.field ? fields.filter((f) => !observability.field(planned, f.field) && buildLeft(planned, builtElement, f)) : [];
+    if (unverifiableFields.length > 0 && (match.unverifiableFields = unverifiableFields, fields = fields.filter((f) => !unverifiableFields.includes(f))), planned.op === "update" && planned.changedFields && planned.changedFields.length > 0) {
+      const checkable = planned.changedFields.filter((field) => !unverifiableFields.some((u) => u.field === field));
+      if (checkable.length === 0) {
+        const reason = `extraction doesn't write ${unverifiableFields.map((f) => f.field).join(", ")}`;
+        report.elements.unverifiable.push({
+          planned: planned.id,
+          layer: planned.layer,
+          type: planned.type,
+          name: planned.name,
+          op: planned.op,
+          reason,
+          fields: unverifiableFields
+        });
+        continue;
+      }
+      const unmet = fields.filter((f) => checkable.includes(f.field)), touched = unmet.some((f) => buildTouched(planned, builtElement, f.field));
+      if (unmet.length === checkable.length && !touched) {
+        if (markUnverifiable(planned))
+          continue;
         report.elements.missing.push({
           planned: planned.id,
           layer: planned.layer,
@@ -253,18 +337,27 @@ function verifyChangeset(plan, built, options = {}) {
         continue;
       }
     }
-    const lifecycle = fields.filter(isLifecycleMove), differences = fields.filter((f) => !isLifecycleMove(f));
+    const lifecycle = fields.filter(isLifecycleMove), descriptionChecked = planned.op === "update" && (planned.changedFields ?? []).includes("description"), informational = fields.filter((f) => f.field === "description" && !descriptionChecked), differences = fields.filter((f) => !isLifecycleMove(f) && !informational.includes(f));
     if (lifecycle.length > 0) {
       match.lifecycle = lifecycle;
       for (const f of lifecycle)
         lifecycleMoves.push(`${planned.id} ${f.field} ${String(f.planned)} \u2192 ${String(f.built)}`);
     }
-    differences.length > 0 ? report.elements.divergent.push({ ...match, fields: differences }) : report.elements.matched.push(match);
+    informational.length > 0 && (match.notes = informational), differences.length > 0 ? report.elements.divergent.push({ ...match, fields: differences }) : report.elements.matched.push(match);
   }
   lifecycleMoves.length > 0 && notes.push(`Lifecycle progress, not counted as divergence (${LIFECYCLE_FIELDS.join(", ")} moving to a later stage of ${LIFECYCLE_STAGES.map((stage) => stage.join("/")).join(" \u2192 ")}): ${lifecycleMoves.join("; ")}.`);
+  const described = [...report.elements.matched, ...report.elements.divergent].filter((m) => m.notes);
+  described.length > 0 && notes.push(`${described.length} matched element${described.length === 1 ? " has a description that differs" : "s have descriptions that differ"} from the plan's (under notes on each match). Descriptions are not compared: no need to edit the plan to match the build's text.`);
+  const unwritten = [...report.elements.matched, ...report.elements.divergent].filter((m) => m.unverifiableFields);
+  unwritten.length > 0 && notes.push(`${unwritten.length} matched element${unwritten.length === 1 ? " has" : "s have"} planned fields extraction doesn't write (under unverifiableFields on each match): check them in the code or the review.`);
   for (const planned of deletions) {
     const still = builtById.get(planned.id);
-    still ? (claimed.add(still.id), report.elements.deletionsNotDone.push({ planned: planned.id, built: still.id })) : (claimed.add(planned.id), report.elements.matched.push({ planned: planned.id, built: planned.id, op: "delete", match: "exact" }));
+    if (still) {
+      if (claimed.add(still.id), markUnverifiable(planned))
+        continue;
+      report.elements.deletionsNotDone.push({ planned: planned.id, built: still.id });
+    } else
+      claimed.add(planned.id), report.elements.matched.push({ planned: planned.id, built: planned.id, op: "delete", match: "exact" });
   }
   if (built.changedElements)
     for (const element of built.changedElements)
@@ -275,7 +368,25 @@ function verifyChangeset(plan, built, options = {}) {
         name: element.name,
         change: element.change ?? "added"
       });
-  const builtRels = new Map(built.relationships.map((r) => [relKey(r), r])), claimedRels = /* @__PURE__ */ new Set(), mapId = (id) => elementMap.get(id)?.built ?? id, probableEndpoints = (rel) => [rel.source, rel.target].filter((id, i, all) => all.indexOf(id) === i).filter((id) => elementMap.get(id)?.match === "probable").map((id) => `${id} \u2192 ${elementMap.get(id).built}`), missingEndpoints = new Set(report.elements.missing.map((m) => m.planned)), mapRel = (planned) => ({
+  const builtRels = new Map(built.relationships.map((r) => [relKey(r), r])), claimedRels = /* @__PURE__ */ new Set(), mapId = (id) => elementMap.get(id)?.built ?? id, probableEndpoints = (rel) => [rel.source, rel.target].filter((id, i, all) => all.indexOf(id) === i).filter((id) => elementMap.get(id)?.match === "probable").map((id) => `${id} \u2192 ${elementMap.get(id).built}`), missingEndpoints = new Set(report.elements.missing.map((m) => m.planned)), plannedById = new Map(plan.elements.map((e) => [e.id, e])), elementOf = (id) => builtById.get(elementMap.get(id)?.built ?? "") ?? plannedById.get(id) ?? builtById.get(id) ?? fromId(id, ""), unverifiableReason = (rel) => {
+    if (!observability)
+      return;
+    for (const end of [rel.source, rel.target]) {
+      const known = unverifiableIds.get(end);
+      if (known !== void 0)
+        return `${end} is unverifiable (${known})`;
+      if (missingHints.has(end))
+        continue;
+      const verdict3 = observability.element(elementOf(end));
+      if (!verdict3.observable)
+        return `extraction can't see ${end}: ${verdict3.reason ?? "no rule produces it"}`;
+    }
+    const verdict2 = observability.relationship(elementOf(rel.source), rel.predicate, elementOf(rel.target));
+    return verdict2.observable ? void 0 : verdict2.reason ?? "no mapped code edge produces it";
+  }, pushUnverifiable = (planned) => {
+    const reason = unverifiableReason(planned);
+    return reason === void 0 ? !1 : (report.relationships.unverifiable.push({ planned: strip(planned), op: planned.op, reason }), !0);
+  }, mapRel = (planned) => ({
     source: mapId(planned.source),
     predicate: planned.predicate,
     target: mapId(planned.target)
@@ -291,7 +402,12 @@ function verifyChangeset(plan, built, options = {}) {
     }
     claimedRels.add(relKey(found));
     const plannedRef = strip(planned);
-    planned.op === "delete" ? report.relationships.deletionsNotDone.push({ planned: plannedRef, built: strip(found) }) : report.relationships.matched.push({ planned: plannedRef, built: strip(found), op: "add", ...matchInfoFor(planned) });
+    if (planned.op === "delete") {
+      if (pushUnverifiable(planned))
+        continue;
+      report.relationships.deletionsNotDone.push({ planned: plannedRef, built: strip(found) });
+    } else
+      report.relationships.matched.push({ planned: plannedRef, built: strip(found), op: "add", ...matchInfoFor(planned) });
   }
   const addedBuiltIds = new Set(live.filter((e) => e.op === "add" && elementMap.has(e.id)).map((e) => elementMap.get(e.id).built));
   for (const planned of unresolved) {
@@ -323,6 +439,8 @@ function verifyChangeset(plan, built, options = {}) {
       });
       continue;
     }
+    if (pushUnverifiable(planned))
+      continue;
     const candidates = built.changedRelationships ? [] : built.relationships.filter(isAlternative).map(strip), absent = [planned.source, planned.target].filter((id) => missingEndpoints.has(id) || !elementMap.has(id) && !builtById.has(id));
     report.relationships.missing.push({
       planned: plannedRef,
@@ -343,14 +461,187 @@ function verifyChangeset(plan, built, options = {}) {
 async function verifyChangesetInModel(model, options) {
   const { planned } = options, plan = await planFromModel(model, planned), notes = [], baseIndex = await tryReadBaseIndex(model.rootPath, planned.id);
   baseIndex.index && (plan.baseElementIds = Object.keys(baseIndex.index.elements)), baseIndex.warning && notes.push(baseIndex.warning);
-  let built;
+  let built, extraction, observability, warning;
   if ("changeset" in options.against) {
     const asBuilt = options.against.changeset;
     asBuilt.id === planned.id && notes.push("The planned and as-built changesets are the same changeset, so everything matches by definition."), built = builtFromGraph(await ChangesetGraph.build(model, asBuilt), `${asBuilt.name} (${asBuilt.id})`);
+    const record = await readExtractionRecord(model.rootPath, { id: asBuilt.id, name: asBuilt.name }, currentGitHead(model.codebaseRoot));
+    if (!record)
+      extraction = {
+        applied: !1,
+        reason: "codebase_extract has no record of the as-built changeset (.dr/analyzers/extract/), so it is not taken as extraction output: every planned change is checked, and its elements count as added by hand, whatever provenance they declare.",
+        asBuilt: asBuiltShare(built, plan, { record: null })
+      }, EXTRACTION_MARKER.test(asBuilt.description ?? "") && notes.push("The as-built changeset's description says codebase_extract staged it, but its record is gone. Run codebase_extract on it again (with the same since) to record what it stages, then verify again.");
+    else {
+      const codeFiles = [...new Set((built.changedElements ?? []).flatMap((e) => sourceFiles(e)))];
+      ({ extraction, observability } = await extractionRule(model, options, codeFiles, "The as-built changeset came from codebase_extract"));
+      const share2 = asBuiltShare(built, plan, { record, ...observability ? { observe: (e) => observability.element(e) } : {} });
+      extraction.asBuilt = share2, record.readAt && notes.push(`The extraction record is from a run that staged nothing, at ${record.readAt.slice(0, 7)}; the code has moved since (a commit after the extract). Its cards still name what extraction offered then; run codebase_extract on this changeset again if the code changed since.`), share2.copiedFromPlan?.length && notes.push(`${share2.copiedFromPlan.length} as-built element(s) share an id with the plan's adds but did not come from extraction (${share2.copiedFromPlan.join(", ")}). If they were copied from the plan, their match says nothing about the code; extract again with codebase_extract and leave them out.`);
+    }
+    warning = asBuiltWarning(extraction.asBuilt, extraction.applied);
   } else
-    built = await builtFromBase(model), planned.status === "staged" && notes.push("The planned changeset is still staged, so its own changes are not in the base model: anything reported missing is missing from what was committed to the base (e.g. an as-built changeset).");
-  const report = verifyChangeset(plan, built, { matchBySource: options.matchBySource });
-  return report.notes.push(...notes), { plannedChangeset: { id: planned.id, name: planned.name }, ...report };
+    built = await builtFromBase(model), planned.status === "staged" && notes.push("The planned changeset is still staged, so its own changes are not in the base model: anything reported missing is missing from what was committed to the base (e.g. an as-built changeset)."), options.against.extracted ? { extraction, observability } = await extractionRule(model, options, [], "Compared with the base model, which holds a landed extraction (extracted: true)") : extraction = {
+      applied: !1,
+      reason: "Compared with the base model: every planned change is checked. Pass extracted: true when the base holds a landed extraction of the build."
+    };
+  const report = verifyChangeset(plan, built, { matchBySource: options.matchBySource, observability });
+  report.extraction = extraction, report.notes.push(...notes);
+  const share = extraction.asBuilt;
+  if (share) {
+    const agentIds = new Set((share.agentAdded ?? []).map((a) => a.id)), edits = new Map((share.editedAfterExtraction ?? []).map((e) => [e.id, e.edits])), matches = [...report.elements.matched, ...report.elements.divergent], onEdited = matches.filter((m) => edits.has(m.built));
+    for (const m of onEdited)
+      m.editedAfterExtraction = edits.get(m.built);
+    const onAgent = matches.filter((m) => agentIds.has(m.built) || edits.has(m.built));
+    for (const m of onAgent)
+      m.builtByAgent = !0;
+    onEdited.length > 0 && report.notes.push(`${onEdited.length} match(es) are against extracted elements changed after extraction staged them (editedAfterExtraction on each): the match shows the edit, not the code.`), warning && (report.warning = warning, report.verdictText += ` But ${warning.charAt(0).toLowerCase()}${warning.slice(1)}`), onAgent.length > 0 && share.record !== "not-found" && (report.verdict === "match" && (report.verdict = "probable-match"), report.verdictText += ` ${onAgent.length} of the matches ${onAgent.length === 1 ? "rests" : "rest"} on elements extraction didn't stage` + (onEdited.length > 0 ? ` or that were edited after it (${onEdited.length})` : "") + " (builtByAgent): confirm them in the code.");
+  }
+  return { plannedChangeset: { id: planned.id, name: planned.name }, ...report };
+}
+async function extractionRule(model, options, codeFiles, why) {
+  const analyzer = options.analyzer ?? await resolveAnalyzerName(model.rootPath).catch(() => "cbm"), coverage = options.coverage !== void 0 ? options.coverage : await loadExtractionCoverage(analyzer);
+  return coverage ? {
+    observability: {
+      element: (element) => coverage.element(element, codeFiles),
+      relationship: (source, predicate, target) => coverage.relationship(source, predicate, target),
+      field: (element, field) => coverage.field(element, field)
+    },
+    extraction: {
+      applied: !0,
+      reason: `${why}: planned changes extraction can't produce (intent, types or files no rule covers, relationships no code edge maps to, fields it doesn't write) are unverifiable, not missing.`,
+      analyzer: coverage.analyzer,
+      observableTypes: coverage.observableTypes()
+    }
+  } : {
+    extraction: {
+      applied: !1,
+      reason: `${why}, but the ${analyzer} mapping could not be read, so extraction's blind spots are not known: every planned change is checked.`,
+      analyzer
+    }
+  };
+}
+const EXTRACTION_MARKER = /Staged by codebase_extract/;
+function asBuiltShare(built, plan, context = {}) {
+  const record = context.record ?? null, changed = built.changedElements ?? [], planAdds = (plan?.elements ?? []).filter((e) => e.op === "add"), plannedAdds = new Set(planAdds.map((e) => e.id)), plannedNames = new Set(planAdds.flatMap((e) => [...nameKeys(e)])), stagedById = new Map((record?.staged ?? []).map((e) => [e.id, e])), updatedById = new Map((record?.updated ?? []).map((u) => [u.id, u])), candidateDeletes = new Set(record?.candidateDeletes ?? []), offered = /* @__PURE__ */ new Map();
+  for (const entry of [...record?.staged ?? [], ...record?.cards ?? [], ...record?.earlierCards ?? []]) {
+    const key = decisionKey(entry.file, entry.symbol);
+    offered.set(key, [...offered.get(key) ?? [], entry]);
+  }
+  const notFromExtraction = (e) => {
+    if (!record)
+      return "no codebase_extract record of this changeset confirms it";
+    if (e.change === "deleted")
+      return candidateDeletes.has(e.id) ? void 0 : "a delete that is not one of extraction's candidate deletes";
+    if (e.change === "updated")
+      return updatedById.has(e.id) ? void 0 : "an update extraction did not stage";
+    const type = `${e.layer}.${e.type}`, looksPlanned = plannedAdds.has(e.id) || [...nameKeys(e)].some((k) => plannedNames.has(k)), staged = stagedById.get(e.id), located = (e.sourceReference?.locations ?? []).filter((l) => typeof l?.symbol == "string" && l.symbol.length > 0), cards = located.flatMap((l) => offered.get(decisionKey(normalizeFile(l.file), l.symbol)) ?? []);
+    if (!staged && cards.length === 0) {
+      const verdict = context.observe?.(e);
+      return verdict && !verdict.observable ? `extraction can't produce it: ${verdict.reason ?? type}` : located.length === 0 ? "extraction did not stage it, and it names no source symbol" : "extraction did not stage it, and no card of its runs has its file and symbol";
+    }
+    const producible = context.observe ? context.observe(e) : { observable: !0 }, allowed = (c) => c.candidates?.length ? c.candidates.some((t) => t === type || t === `${e.layer}.*`) : producible.observable, fitting = cards.filter(allowed), withCandidates = cards.filter((c) => c.candidates?.length);
+    if (withCandidates.length > 0 && !withCandidates.some(allowed))
+      return `its card allows ${[...new Set(withCandidates.flatMap((c) => c.candidates))].join(", ")}, not ${type}`;
+    if (!producible.observable && withCandidates.length === 0)
+      return `extraction can't produce it ${staged ? "there" : "from its card"}: ${producible.reason ?? type}`;
+    if (looksPlanned && !(staged && namedAfterCard(e, staged) || fitting.some((c) => namedAfterCard(e, c))))
+      return staged ? "named after the plan's element, not after the symbol extraction staged it from" : "named after the plan's element, not after its card";
+  }, byProvenance = {}, extracted = /* @__PURE__ */ new Set(), agentAdded = [], edited = [];
+  for (const e of changed) {
+    const declared = e.change === "deleted" ? "deleted" : e.stagedProvenance ?? (e.change === "updated" ? "sourceUnchanged" : e.sourceReference?.provenance ?? "none");
+    byProvenance[declared] = (byProvenance[declared] ?? 0) + 1;
+    const reason = notFromExtraction(e);
+    if (reason !== void 0) {
+      agentAdded.push({ id: e.id, declared, reason });
+      continue;
+    }
+    extracted.add(e.id);
+    const edits = editsAfterExtraction(e, stagedById.get(e.id), updatedById.get(e.id));
+    edits.length > 0 && edited.push({ id: e.id, edits });
+  }
+  const relationships = (built.changedRelationships ?? []).filter((r) => r.change !== "deleted"), betweenExtracted = relationships.filter((r) => extracted.has(r.source) && extracted.has(r.target)).length, addedIds = new Set(changed.filter((e) => e.change === "added").map((e) => e.id)), copied = agentAdded.filter((a) => plannedAdds.has(a.id) && addedIds.has(a.id)).map((a) => a.id);
+  return {
+    elements: { total: changed.length, byProvenance, fromExtraction: extracted.size, agentAdded: agentAdded.length },
+    relationships: { total: relationships.length, betweenExtracted, other: relationships.length - betweenExtracted },
+    record: record ? record.source === "pending" ? "pending" : "found" : "not-found",
+    ...agentAdded.length > 0 ? { agentAdded } : {},
+    ...edited.length > 0 ? { editedAfterExtraction: edited } : {},
+    ...copied.length > 0 ? { copiedFromPlan: copied } : {}
+  };
+}
+function recordFieldValue(element, field) {
+  return field === "source_reference" ? element.sourceReference ?? null : fieldValue(element, field);
+}
+function sameRecordValue(field, a, b) {
+  if (field !== "source_reference")
+    return sameFieldValue(field, a, b);
+  const where = (v) => {
+    const locations = v?.locations;
+    return Array.isArray(locations) ? locations.map((l) => `${String(l?.file ?? "")}#${String(l?.symbol ?? "")}`).sort() : [];
+  };
+  return sameValue(where(a), where(b));
+}
+function editsAfterExtraction(e, staged, own) {
+  const edits = [], values = own?.values && typeof own.values == "object" ? own.values : void 0, byValue = (field) => {
+    if (!values || !Object.hasOwn(values, field))
+      return;
+    const now = recordFieldValue(e, field);
+    return sameRecordValue(field, values[field], now) ? void 0 : { field, extracted: values[field] ?? null, now: now ?? null };
+  };
+  if (e.change === "updated") {
+    if (!own)
+      return edits;
+    for (const [field, was] of Object.entries(e.updatedFrom ?? {}))
+      own.fields && !own.fields.includes(field) && edits.push({ field, extracted: was ?? null, now: recordFieldValue(e, field) ?? null });
+    for (const field of own.fields ?? []) {
+      const edit = byValue(field);
+      edit && edits.push(edit);
+    }
+    return edits;
+  }
+  if (e.change !== "added")
+    return edits;
+  const folded = new Set(own?.fields ?? []);
+  staged && edits.push(...editsSinceExtraction(e, staged).filter((d) => !folded.has(d.field) && !(own && !own.fields)));
+  for (const field of folded) {
+    const edit = byValue(field);
+    edit && edits.push(edit);
+  }
+  return edits;
+}
+function editsSinceExtraction(element, staged) {
+  const edits = [];
+  if (typeof staged.name != "string")
+    return edits;
+  staged.name !== element.name && edits.push({ field: "name", extracted: staged.name, now: element.name });
+  const stagedAttributes = staged.attributes && typeof staged.attributes == "object" ? staged.attributes : {};
+  {
+    const keys = /* @__PURE__ */ new Set([...Object.keys(stagedAttributes), ...Object.keys(element.attributes ?? {})]);
+    for (const key of [...keys].sort()) {
+      const was = stagedAttributes[key], now = element.attributes?.[key];
+      sameValue(was, now) || edits.push({ field: `attributes.${key}`, extracted: was ?? null, now: now ?? null });
+    }
+  }
+  return edits;
+}
+function namedAfterCard(element, card) {
+  if (card.proposed?.id && card.proposed.id === element.id)
+    return !0;
+  const route = routeKey(card.symbol) ?? (card.name ? routeKey(card.name) : void 0);
+  if (route && routeKey(element.name) === route)
+    return !0;
+  const keys = nameKeys(element), parts = card.symbol.split(/[.#/\s]+/).filter(Boolean), file = card.file ?? "";
+  return [card.symbol, card.name, card.proposed?.name, parts[parts.length - 1], file, file.replace(/\.[^./]+$/, "")].some((n) => typeof n == "string" && n.length > 0 && keys.has(normalizeName(n)));
+}
+function normalizeFile(file) {
+  return typeof file == "string" && file.length > 0 ? file.replace(/\\/g, "/").replace(/^\.\//, "") : null;
+}
+function asBuiltWarning(share, blindSpotsApplied = !0) {
+  const { total, agentAdded } = share.elements, edited = share.editedAfterExtraction?.length ?? 0;
+  if (total === 0 || (agentAdded + edited) * 2 <= total)
+    return;
+  const copied = share.copiedFromPlan?.length ?? 0;
+  return `${agentAdded + edited} of the ${total} as-built elements were not staged by extraction` + (edited > 0 ? ` or were edited after it (${edited})` : "") + (copied > 0 ? ` (${copied} share an id with the plan's adds)` : "") + ", so this comparison says little about the code." + (blindSpotsApplied ? " Extraction's blind spots were still applied." : share.record === "not-found" ? " No extraction record covers this changeset, so extraction's blind spots were not applied." : " Extraction's blind spots were not applied.") + " To verify the code, discard this changeset and stage the build with codebase_extract: from its cards, named after them (see extraction.asBuilt.agentAdded for why each one doesn't count).";
 }
 function normalizeName(name) {
   return name.toLowerCase().replace(/[^a-z0-9]/g, "");
@@ -386,7 +677,7 @@ function compareElements(planned, built, removedBy) {
   planned.type && !sameType(planned, built) && fields.push({ field: "type", planned: planned.type, built: built.type }), planned.name && normalizeName(planned.name) !== normalizeName(built.name) && fields.push({ field: "name", planned: planned.name, built: built.name }), planned.description !== void 0 && planned.description.trim() !== (built.description ?? "").trim() && fields.push({ field: "description", planned: planned.description, built: built.description });
   for (const [key, value] of Object.entries(planned.attributes ?? {})) {
     const builtValue = built.attributes?.[key];
-    sameValue(value, builtValue) || fields.push({ field: `attributes.${key}`, planned: value, built: builtValue });
+    sameAttribute(key, value, builtValue) || fields.push({ field: `attributes.${key}`, planned: value, built: builtValue });
   }
   for (const field of removedBy ?? [])
     if (field === "description")
@@ -395,7 +686,7 @@ function compareElements(planned, built, removedBy) {
       const key = field.slice(11);
       !(planned.attributes !== void 0 && Object.hasOwn(planned.attributes, key)) && built.attributes?.[key] !== void 0 && fields.push({ field, planned: void 0, built: built.attributes[key] });
     }
-  return fields;
+  return fields.map((f) => ({ field: f.field, planned: f.planned ?? null, built: f.built ?? null }));
 }
 function fieldValue(element, field) {
   if (field === "type")
@@ -408,7 +699,26 @@ function fieldValue(element, field) {
     return element.attributes?.[field.slice(11)];
 }
 function sameFieldValue(field, a, b) {
-  return field === "type" || field === "name" ? normalizeName(String(a ?? "")) === normalizeName(String(b ?? "")) : field === "description" ? String(a ?? "").trim() === String(b ?? "").trim() : sameValue(a, b);
+  return field === "type" || field === "name" ? normalizeName(String(a ?? "")) === normalizeName(String(b ?? "")) : field === "description" ? String(a ?? "").trim() === String(b ?? "").trim() : field.startsWith("attributes.") ? sameAttribute(field.slice(11), a, b) : sameValue(a, b);
+}
+function normalizeHttpPath(p) {
+  return p.replace(/\{[^}]*\}|:[A-Za-z_]\w*/g, "{}").replace(/\/+$/, "") || "/";
+}
+function routeKey(text) {
+  const m = /^__route__([A-Z]+)__(\/\S*)$/.exec(text.trim()) ?? /^([A-Z]+)\s+(\/\S*)$/.exec(text.trim());
+  return m ? `${m[1]} ${normalizeHttpPath(m[2])}` : void 0;
+}
+function sameAttribute(key, a, b) {
+  if (typeof a == "string" && typeof b == "string") {
+    if (key === "http_path")
+      return normalizeHttpPath(a) === normalizeHttpPath(b);
+    if (key === "http_method")
+      return a.toUpperCase() === b.toUpperCase();
+  }
+  return sameValue(a, b);
+}
+function buildLeft(planned, built, difference) {
+  return difference.built === null ? !0 : planned.op !== "update" ? !1 : planned.baseValues && Object.hasOwn(planned.baseValues, difference.field) ? sameFieldValue(difference.field, fieldValue(built, difference.field), planned.baseValues[difference.field]) : built.change !== "updated" && built.change !== "added";
 }
 function buildTouched(planned, built, field) {
   return planned.baseValues && Object.hasOwn(planned.baseValues, field) ? !sameFieldValue(field, fieldValue(built, field), planned.baseValues[field]) : built.change === "updated" || built.change === "added";
@@ -475,7 +785,7 @@ function toVerifyElement(record, layerName, id) {
   };
 }
 function emptyCounts() {
-  return { planned: 0, matched: 0, probable: 0, missing: 0, divergent: 0, unplanned: 0, deletionsNotDone: 0 };
+  return { planned: 0, matched: 0, probable: 0, missing: 0, divergent: 0, unplanned: 0, deletionsNotDone: 0, unverifiable: 0 };
 }
 function countCategories(planned, section) {
   return {
@@ -485,7 +795,8 @@ function countCategories(planned, section) {
     missing: section.missing.length,
     divergent: section.divergent.length,
     unplanned: section.unplanned.length,
-    deletionsNotDone: section.deletionsNotDone.length
+    deletionsNotDone: section.deletionsNotDone.length,
+    unverifiable: section.unverifiable.length
   };
 }
 function decideVerdict(report) {
@@ -496,8 +807,24 @@ function decideVerdict(report) {
     n > 0 && parts.push(`${n} ${what}`);
   };
   say(e.missing, plural(e.missing, "planned element", "planned elements") + " missing"), say(r.missing, plural(r.missing, "planned relationship", "planned relationships") + " missing"), say(e.deletionsNotDone + r.deletionsNotDone, "planned deletion(s) not done"), say(e.divergent, plural(e.divergent, "element differs", "elements differ")), say(r.divergent, plural(r.divergent, "relationship differs", "relationships differ")), say(e.unplanned, plural(e.unplanned, "unplanned element change", "unplanned element changes")), say(r.unplanned, plural(r.unplanned, "unplanned relationship", "unplanned relationships"));
-  const probable = e.probable + r.probable, probableText = probable > 0 ? ` ${probable} match(es) are probable, not exact; confirm them.` : "";
-  return e.missing + r.missing + e.deletionsNotDone + r.deletionsNotDone > 0 ? { verdict: "incomplete", text: `The build is incomplete: ${parts.join(", ")}.${probableText}` } : e.divergent + r.divergent + e.unplanned + r.unplanned > 0 ? { verdict: "diverges", text: `The build diverges from the plan: ${parts.join(", ")}.${probableText}` } : probable > 0 ? { verdict: "probable-match", text: `Everything planned was found.${probableText}` } : { verdict: "match", text: "The build matches the plan." };
+  const probable = e.probable + r.probable, probableText = probable > 0 ? ` ${probable} match(es) are probable, not exact; confirm them.` : "", unverifiable = e.unverifiable + r.unverifiable, unverifiableText = unverifiable > 0 ? ` ${[
+    e.unverifiable > 0 ? `${e.unverifiable} planned ${plural(e.unverifiable, "element", "elements")}` : "",
+    r.unverifiable > 0 ? `${r.unverifiable} planned ${plural(r.unverifiable, "relationship", "relationships")}` : ""
+  ].filter(Boolean).join(" and ")} can't be seen by extraction (unverifiable, not counted): check them in the code or the review.` : "";
+  if (e.planned + r.planned === unverifiable && e.unplanned + r.unplanned === 0)
+    return {
+      verdict: "unverifiable",
+      text: `Nothing in the plan can be checked against extracted code.${unverifiableText}`
+    };
+  if (e.missing + r.missing + e.deletionsNotDone + r.deletionsNotDone > 0)
+    return { verdict: "incomplete", text: `The build is incomplete: ${parts.join(", ")}.${probableText}${unverifiableText}` };
+  if (e.divergent + r.divergent + e.unplanned + r.unplanned > 0)
+    return { verdict: "diverges", text: `The build diverges from the plan: ${parts.join(", ")}.${probableText}${unverifiableText}` };
+  const scope = unverifiable > 0 ? "Everything extraction can see was found." : "Everything planned was found.";
+  return probable > 0 ? { verdict: "probable-match", text: `${scope}${probableText}${unverifiableText}` } : {
+    verdict: "match",
+    text: unverifiable > 0 ? `The build matches what extraction can see of the plan.${unverifiableText}` : "The build matches the plan."
+  };
 }
 function plural(n, one, many) {
   return n === 1 ? one : many;
@@ -505,6 +832,8 @@ function plural(n, one, many) {
 export {
   LIFECYCLE_FIELDS,
   LIFECYCLE_STAGES,
+  asBuiltShare,
+  asBuiltWarning,
   builtFromBase,
   builtFromGraph,
   builtFromSnapshot,
@@ -512,6 +841,7 @@ export {
   normalizeName,
   planFromChangeset,
   planFromModel,
+  readExtractionRecord,
   verifyChangeset,
   verifyChangesetInModel
 };