@nimiplatform/nimi-coding 0.4.0 → 0.6.0

package/cli/lib/authority/audit.mjs

@@ -7,13 +7,15 @@ import { fileURLToPath } from "node:url";
 import YAML, { isMap, isScalar, isSeq } from "yaml";
 
 import { compileAuthorityPath } from "./compile.mjs";
+import { createCompiledAuthoritySnapshot } from "./compiled-snapshot.mjs";
 import { compareText, createLocator, makeDiagnostic, portablePath } from "./diagnostics.mjs";
-import { buildAuthorityGraphSnapshot } from "./graph.mjs";
 
-const AUDIT_FORMAT = "nimicoding.authority-audit/v1";
-const BINDING_FORMAT = "nimicoding.authority-verifier-bindings/v1";
-const DETECTOR = "minimum-independent-incoming-reference/v1";
-const FINGERPRINT_FORMAT = "nimicoding.authority-audit-fingerprint/v1";
+const AUDIT_FORMAT = "nimicoding.authority-audit/v2";
+const BINDING_FORMAT = "nimicoding.authority-verifier-bindings/v2";
+const GRAPH_DETECTOR = "minimum-independent-incoming-reference/v1";
+const LEXICAL_DETECTOR = "exact-lexical-invariant/v1";
+const FINGERPRINT_FORMAT = "nimicoding.authority-audit-fingerprint/v2";
+const NORMATIVE_FIELDS = ["meaning", "statement", "condition", "failure"];
 const contractPath = fileURLToPath(new URL("../../../contracts/authority-verifier-bindings.schema.yaml", import.meta.url));
 
 let contractPromise = null;
@@ -52,7 +54,7 @@ function collectLocations(node, locator, pointer, locations) {
 async function loadContract() {
   if (!contractPromise) contractPromise = readFile(contractPath, "utf8").then((text) => {
     const contract = YAML.parse(text);
-    if (contract?.version !== 1 || contract?.contract?.id !== "nimicoding.authority-verifier-bindings.v1") {
+    if (contract?.version !== 2 || contract?.contract?.id !== "nimicoding.authority-verifier-bindings.v2") {
       throw new Error("installed authority verifier binding contract is invalid");
     }
     return contract;
@@ -67,7 +69,7 @@ function bindingDiagnostic(file, reason, location = null) {
     range: location?.range ?? { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
     pointer: location?.sourcePointer ?? "",
     reason,
-    repair: "declare the exact closed verifier binding without inferring project policy from authority prose",
+    repair: "declare one exact closed built-in verifier binding; project policy is never inferred from authority prose or change history",
   });
 }
 
@@ -88,6 +90,13 @@ function syntaxLocation(error, file, locator) {
   };
 }
 
+function validExactTerm(value) {
+  return typeof value === "string"
+    && value.length > 0
+    && value.trim() === value
+    && !/[\0\r\n\v\f\u0085\u2028\u2029]/u.test(value);
+}
+
 async function loadBindings(file, labelOverride = null) {
   const absolute = path.resolve(file);
   const label = labelOverride ?? portablePath(absolute);
@@ -133,38 +142,55 @@ async function loadBindings(file, labelOverride = null) {
   collectLocations(documents[0].contents, locator, "", locations);
   const parsed = { file: label, locations, data };
   const contract = await loadContract();
-  if (!exactObject(data, contract.fields.top) || data.format !== BINDING_FORMAT || !Array.isArray(data.required_bindings) || data.required_bindings.length === 0 || !Array.isArray(data.bindings)) {
-    return { ok: false, diagnostics: [bindingDiagnostic(label, "verifier bindings require exact format, required_bindings, and bindings fields", parsedLocation(parsed, ""))] };
+  if (!exactObject(data, contract.fields.top) || data.format !== BINDING_FORMAT || !Array.isArray(data.bindings) || data.bindings.length === 0) {
+    return { ok: false, diagnostics: [bindingDiagnostic(label, "verifier bindings require exact format and one non-empty bindings list", parsedLocation(parsed, ""))] };
   }
   const identifier = new RegExp(contract.identifier_pattern);
-  const required = [];
-  const requiredIds = new Set();
-  for (let index = 0; index < data.required_bindings.length; index += 1) {
-    const id = data.required_bindings[index];
-    const pointer = `/required_bindings/${index}`;
-    if (typeof id !== "string" || !identifier.test(id)) {
-      return { ok: false, diagnostics: [bindingDiagnostic(label, "required binding IDs must be exact dotted lowercase identifiers", parsedLocation(parsed, pointer))] };
-    }
-    if (requiredIds.has(id)) return { ok: false, diagnostics: [bindingDiagnostic(label, `duplicate required binding ID: ${id}`, parsedLocation(parsed, pointer))] };
-    requiredIds.add(id);
-    required.push({ id, location: parsedLocation(parsed, pointer) });
-  }
+  const token = new RegExp(contract.token_pattern, "u");
   const bindings = [];
   const bindingIds = new Set();
   for (let index = 0; index < data.bindings.length; index += 1) {
     const value = data.bindings[index];
     const pointer = `/bindings/${index}`;
-    if (!exactObject(value, contract.fields.binding)) {
-      return { ok: false, diagnostics: [bindingDiagnostic(label, "each binding requires exact id, detector, premise, targets, minimum, and policy fields", parsedLocation(parsed, pointer))] };
+    const fields = value?.detector === GRAPH_DETECTOR
+      ? contract.fields.graph_binding
+      : value?.detector === LEXICAL_DETECTOR ? contract.fields.lexical_binding : null;
+    if (fields === null) {
+      return { ok: false, diagnostics: [bindingDiagnostic(label, `unknown detector: ${String(value?.detector)}`, parsedLocation(parsed, `${pointer}/detector`))] };
+    }
+    if (!exactObject(value, fields)) {
+      return { ok: false, diagnostics: [bindingDiagnostic(label, `binding fields do not match detector ${value.detector}`, parsedLocation(parsed, pointer))] };
     }
     if (typeof value.id !== "string" || !identifier.test(value.id)) {
       return { ok: false, diagnostics: [bindingDiagnostic(label, "binding id must be an exact dotted lowercase identifier", parsedLocation(parsed, `${pointer}/id`))] };
     }
     if (bindingIds.has(value.id)) return { ok: false, diagnostics: [bindingDiagnostic(label, `duplicate binding ID: ${value.id}`, parsedLocation(parsed, `${pointer}/id`))] };
     bindingIds.add(value.id);
-    if (value.detector !== DETECTOR) {
-      return { ok: false, diagnostics: [bindingDiagnostic(label, `unknown detector: ${String(value.detector)}`, parsedLocation(parsed, `${pointer}/detector`))] };
+    if (!contract.policies.includes(value.policy)) {
+      return { ok: false, diagnostics: [bindingDiagnostic(label, "binding policy must be advisory or blocking", parsedLocation(parsed, `${pointer}/policy`))] };
+    }
+
+    if (value.detector === LEXICAL_DETECTOR) {
+      if (!validExactTerm(value.term)) {
+        return { ok: false, diagnostics: [bindingDiagnostic(label, "lexical term must be non-empty trimmed single-line exact text", parsedLocation(parsed, `${pointer}/term`))] };
+      }
+      if (!contract.lexical_matches.includes(value.match)) {
+        return { ok: false, diagnostics: [bindingDiagnostic(label, "lexical match must be token or phrase", parsedLocation(parsed, `${pointer}/match`))] };
+      }
+      if (value.match === "token" && !token.test(value.term)) {
+        return { ok: false, diagnostics: [bindingDiagnostic(label, "token matching requires one exact lexical token", parsedLocation(parsed, `${pointer}/term`))] };
+      }
+      if (!contract.lexical_expectations.includes(value.expectation)) {
+        return { ok: false, diagnostics: [bindingDiagnostic(label, "lexical expectation must be present or absent", parsedLocation(parsed, `${pointer}/expectation`))] };
+      }
+      bindings.push({
+        ...value,
+        location: parsedLocation(parsed, `${pointer}/id`),
+        termLocation: parsedLocation(parsed, `${pointer}/term`),
+      });
+      continue;
     }
+
     if (typeof value.premise !== "string" || !identifier.test(value.premise)) {
       return { ok: false, diagnostics: [bindingDiagnostic(label, "binding premise must be one exact authority ID", parsedLocation(parsed, `${pointer}/premise`))] };
     }
@@ -186,9 +212,6 @@ async function loadBindings(file, labelOverride = null) {
     if (!Number.isSafeInteger(value.minimum) || value.minimum <= 0) {
       return { ok: false, diagnostics: [bindingDiagnostic(label, "binding minimum must be a positive safe integer", parsedLocation(parsed, `${pointer}/minimum`))] };
     }
-    if (!contract.policies.includes(value.policy)) {
-      return { ok: false, diagnostics: [bindingDiagnostic(label, "binding policy must be advisory or blocking", parsedLocation(parsed, `${pointer}/policy`))] };
-    }
     bindings.push({
       ...value,
       location: parsedLocation(parsed, `${pointer}/id`),
@@ -196,9 +219,8 @@ async function loadBindings(file, labelOverride = null) {
       targetEntries: targets,
     });
   }
-  required.sort((left, right) => compareText(left.id, right.id));
   bindings.sort((left, right) => compareText(left.id, right.id));
-  return { ok: true, diagnostics: [], required, bindings };
+  return { ok: true, diagnostics: [], bindings };
 }
 
 function refused(compiled, diagnostics) {
@@ -241,7 +263,7 @@ function auditBudgetDiagnostic(kind, required, admitted, location = null) {
     range: location?.range ?? { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
     pointer: location?.sourcePointer ?? "",
     reason: `complete authority audit requires ${required} ${kind} but the explicit budget is ${admitted}`,
-    repair: "increase the explicit audit budget; partial observations, findings, or gaps are forbidden",
+    repair: "increase the explicit audit budget; partial findings are forbidden",
   });
 }
 
@@ -250,6 +272,7 @@ function validBudget(value) {
 }
 
 function validateBindingAuthority(binding, snapshot, compiled) {
+  if (binding.detector !== GRAPH_DETECTOR) return { ok: true };
   const premise = snapshot.byId.get(binding.premise);
   if (!premise || premise.unit.kind !== "rule" || premise.unit.lifecycle !== "active") {
     return refused(compiled, [bindingDiagnostic(
@@ -268,20 +291,20 @@ function validateBindingAuthority(binding, snapshot, compiled) {
       )]);
     }
   }
-  return { premise };
+  return { ok: true };
 }
 
-function findingBase(binding, target, code, message, witness, primaryLocation, relatedLocations) {
+function graphFinding(binding, target, code, message, witness, primaryLocation, relatedLocations) {
   const authorityRefs = [...new Set([binding.premise, target.id, ...(witness.incomingRefs ?? [])])].sort(compareText);
   return {
     code,
-    detector: DETECTOR,
+    detector: GRAPH_DETECTOR,
     binding: binding.id,
     premise: binding.premise,
     target: target.id,
-    basis: "governance_bound",
+    basis: "configured",
     policy: binding.policy,
-    fingerprint: fingerprint([code, DETECTOR, binding.id, binding.premise, target.id, `minimum=${binding.minimum}`]),
+    fingerprint: fingerprint([code, GRAPH_DETECTOR, binding.id, binding.premise, target.id, `minimum=${binding.minimum}`]),
     message,
     authorityRefs,
     primaryLocation,
@@ -290,185 +313,226 @@ function findingBase(binding, target, code, message, witness, primaryLocation, r
   };
 }
 
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+function countExactMatches(text, term, match) {
+  if (match === "token") {
+    const expression = new RegExp(`(?<![\\p{L}\\p{N}_.-])${escapeRegExp(term)}(?![\\p{L}\\p{N}_.-])`, "gu");
+    return [...text.matchAll(expression)].length;
+  }
+  let count = 0;
+  let offset = 0;
+  while (offset <= text.length - term.length) {
+    const found = text.indexOf(term, offset);
+    if (found < 0) break;
+    count += 1;
+    offset = found + term.length;
+  }
+  return count;
+}
+
+function portableMappedLocation(compiled, pointer, basePath) {
+  const mapped = compiled.sourceMap.fields[pointer];
+  return { file: portablePath(mapped.file, basePath), range: mapped.range, sourcePointer: mapped.sourcePointer };
+}
+
+function unitIdentityLocation(snapshot, entry) {
+  return portableMappedLocation(
+    snapshot.compiled,
+    `/units/${entry.unitIndex}/id`,
+    snapshot.inputRoot,
+  );
+}
+
+function relationTargetLocation(snapshot, edge) {
+  return portableMappedLocation(
+    snapshot.compiled,
+    `/units/${edge.sourceUnitIndex}/relations/${edge.relationIndex}/target`,
+    snapshot.inputRoot,
+  );
+}
+
+function lexicalOccurrences(binding, compiled, basePath, traversedUnits) {
+  const occurrences = [];
+  compiled.ir.units.forEach((unit, unitIndex) => {
+    if (unit.lifecycle !== "active") return;
+    traversedUnits.add(unit.id);
+    for (const field of NORMATIVE_FIELDS) {
+      const text = unit.semantic?.[field];
+      if (typeof text !== "string") continue;
+      const count = countExactMatches(text, binding.term, binding.match);
+      if (count === 0) continue;
+      occurrences.push({
+        unitId: unit.id,
+        field,
+        count,
+        location: portableMappedLocation(compiled, `/units/${unitIndex}/semantic/${field}`, basePath),
+      });
+    }
+  });
+  return occurrences;
+}
+
+function evaluateLexicalBinding(binding, compiled, basePath, traversedUnits) {
+  const occurrences = lexicalOccurrences(binding, compiled, basePath, traversedUnits);
+  const count = occurrences.reduce((total, entry) => total + entry.count, 0);
+  const satisfied = binding.expectation === "present" ? count > 0 : count === 0;
+  const authorityRefs = [...new Set(occurrences.map((entry) => entry.unitId))].sort(compareText);
+  const witness = {
+    type: "exact-lexical-invariant",
+    term: binding.term,
+    match: binding.match,
+    expectation: binding.expectation,
+    satisfied,
+    count,
+    occurrences,
+  };
+  const relatedLocations = [
+    relatedLocation("binding-term", binding.termLocation),
+    ...occurrences.map((entry) => relatedLocation("normative-field", entry.location)),
+  ].sort(compareRelatedLocation);
+  if (satisfied) return null;
+  const code = "AUTH_AUDIT_EXACT_LEXICAL_INVARIANT_VIOLATION";
+  const primaryLocation = occurrences[0]?.location ?? binding.termLocation;
+  return {
+    code,
+    detector: LEXICAL_DETECTOR,
+    binding: binding.id,
+    premise: null,
+    basis: "configured",
+    policy: binding.policy,
+    fingerprint: fingerprint([code, LEXICAL_DETECTOR, binding.id, binding.match, binding.expectation, binding.term]),
+    message: `expected exact ${binding.match} ${JSON.stringify(binding.term)} to be ${binding.expectation} in active normative authority fields; observed ${count}`,
+    authorityRefs,
+    primaryLocation,
+    relatedLocations,
+    witness,
+  };
+}
+
+function evaluateGraphBinding(binding, snapshot, traversedUnits, traversedEdges) {
+  const premise = snapshot.byId.get(binding.premise);
+  traversedUnits.add(binding.premise);
+  const premiseEdges = snapshot.outgoing.get(binding.premise).filter((edge) => edge.type === "applies_to");
+  for (const edge of premiseEdges) {
+    traversedEdges.add(edgeKey(edge));
+    traversedUnits.add(edge.source);
+    traversedUnits.add(edge.target);
+  }
+  const findings = [];
+  for (const target of [...binding.targetEntries].sort((left, right) => compareText(left.id, right.id))) {
+    const targetNode = snapshot.byId.get(target.id);
+    traversedUnits.add(target.id);
+    const attachment = premiseEdges.find((edge) => edge.target === target.id) ?? null;
+    if (attachment) traversedEdges.add(edgeKey(attachment));
+    const incomingCandidates = snapshot.incoming.get(target.id).filter((edge) => edge.type === "applies_to");
+    for (const edge of incomingCandidates) {
+      traversedEdges.add(edgeKey(edge));
+      traversedUnits.add(edge.source);
+      traversedUnits.add(edge.target);
+    }
+    const incoming = incomingCandidates
+      .filter((edge) => edge.source !== binding.premise)
+      .filter((edge) => {
+        const source = snapshot.byId.get(edge.source).unit;
+        return source.kind === "rule" && source.lifecycle === "active";
+      });
+    if (!attachment) {
+      findings.push(graphFinding(
+        binding,
+        target,
+        "AUTH_AUDIT_PREMISE_TARGET_UNATTACHED",
+        `premise ${binding.premise} does not directly attach required target ${target.id}`,
+        { type: "premise-direct-attachment", relation: "applies_to", attached: false },
+        unitIdentityLocation(snapshot, targetNode),
+        [
+          relatedLocation("binding", binding.location),
+          relatedLocation("binding-target", target.location),
+          relatedLocation("premise", unitIdentityLocation(snapshot, premise)),
+        ],
+      ));
+    }
+    const observed = new Set(incoming.map((edge) => edge.source)).size;
+    if (observed < binding.minimum) {
+      const relatedLocations = [
+        relatedLocation("binding", binding.location),
+        relatedLocation("binding-target", target.location),
+        relatedLocation("premise", unitIdentityLocation(snapshot, premise)),
+      ];
+      if (attachment) relatedLocations.push(relatedLocation("premise-attachment", relationTargetLocation(snapshot, attachment)));
+      for (const edge of incoming) relatedLocations.push(relatedLocation("incoming-reference", relationTargetLocation(snapshot, edge)));
+      findings.push(graphFinding(
+        binding,
+        target,
+        "AUTH_AUDIT_MINIMUM_INDEPENDENT_INCOMING_REFERENCE",
+        `target ${target.id} has ${observed} independent active-rule applies_to references; binding requires ${binding.minimum}`,
+        {
+          type: "minimum-independent-incoming-reference",
+          relation: "applies_to",
+          minimum: binding.minimum,
+          observed,
+          incomingRefs: [...new Set(incoming.map((edge) => edge.source))].sort(compareText),
+        },
+        unitIdentityLocation(snapshot, targetNode),
+        relatedLocations,
+      ));
+    }
+  }
+  return findings;
+}
+
 export function canonicalAuditBytes(audit) {
   return Buffer.byteLength(JSON.stringify(audit), "utf8");
 }
 
-export async function auditAuthorityPath(inputPath, bindingsPath, { maxUnits, maxEdges, maxBytes, bindingLabel = null }) {
+export async function auditAuthoritySnapshot(authoritySnapshot, bindingsPath, { maxUnits, maxEdges, maxBytes, bindingLabel = null }) {
   if (![maxUnits, maxEdges, maxBytes].every(validBudget)) {
     return refused(null, [auditBudgetDiagnostic("positive safe-integer budget values", "all", "invalid")]);
   }
-  const compiled = await compileAuthorityPath(inputPath);
-  if (!compiled.ok) return refused(compiled, compiled.diagnostics);
+  const compiled = authoritySnapshot?.compiled;
+  if (compiled?.ok !== true || typeof authoritySnapshot?.inputRoot !== "string") {
+    throw new TypeError("authority audit snapshot requires one successful immutable compiler snapshot");
+  }
   const parsedBindings = await loadBindings(bindingsPath, bindingLabel);
   if (!parsedBindings.ok) return refused(compiled, parsedBindings.diagnostics);
-  const absoluteInput = path.resolve(inputPath);
-  const inputInfo = await stat(absoluteInput);
-  const basePath = inputInfo.isDirectory() ? absoluteInput : path.dirname(absoluteInput);
-  const snapshot = buildAuthorityGraphSnapshot(compiled, basePath, ["applies_to"]);
+  const basePath = authoritySnapshot.inputRoot;
   for (const binding of parsedBindings.bindings) {
-    const validation = validateBindingAuthority(binding, snapshot, compiled);
+    const validation = validateBindingAuthority(binding, authoritySnapshot, compiled);
     if (validation.ok === false) return validation;
   }
 
-  const proofUnits = new Set();
-  const proofEdges = new Set();
-  const observations = [];
+  const traversedUnits = new Set();
+  const traversedEdges = new Set();
   const findings = [];
-  const gaps = [];
-  const presentBindings = new Set(parsedBindings.bindings.map((binding) => binding.id));
-
-  for (const required of parsedBindings.required) {
-    if (presentBindings.has(required.id)) continue;
-    const code = "AUTH_AUDIT_REQUIRED_BINDING_MISSING";
-    gaps.push({
-      code,
-      detector: null,
-      binding: required.id,
-      premise: null,
-      basis: "required_coverage",
-      policy: "required",
-      fingerprint: fingerprint([code, required.id]),
-      message: `required verifier binding is missing: ${required.id}`,
-      authorityRefs: [],
-      primaryLocation: required.location,
-      relatedLocations: [],
-      witness: { type: "required-binding", required: true, present: false },
-    });
-  }
-
   for (const binding of parsedBindings.bindings) {
-    const premise = snapshot.byId.get(binding.premise);
-    proofUnits.add(binding.premise);
-    const premiseEdges = snapshot.outgoing.get(binding.premise).filter((edge) => edge.type === "applies_to");
-    for (const edge of premiseEdges) {
-      proofEdges.add(edgeKey(edge));
-      proofUnits.add(edge.source);
-      proofUnits.add(edge.target);
+    if (binding.detector === GRAPH_DETECTOR) {
+      findings.push(...evaluateGraphBinding(binding, authoritySnapshot, traversedUnits, traversedEdges));
+    } else {
+      const finding = evaluateLexicalBinding(binding, compiled, basePath, traversedUnits);
+      if (finding) findings.push(finding);
     }
-    const targetObservations = [];
-    const observationRelated = [relatedLocation("premise", premise.node.location)];
-    for (const target of [...binding.targetEntries].sort((left, right) => compareText(left.id, right.id))) {
-      const targetNode = snapshot.byId.get(target.id);
-      proofUnits.add(target.id);
-      const attachment = premiseEdges.find((edge) => edge.target === target.id) ?? null;
-      if (attachment) proofEdges.add(edgeKey(attachment));
-      const incomingCandidates = snapshot.incoming.get(target.id).filter((edge) => edge.type === "applies_to");
-      for (const edge of incomingCandidates) {
-        proofEdges.add(edgeKey(edge));
-        proofUnits.add(edge.source);
-        proofUnits.add(edge.target);
-      }
-      const incoming = incomingCandidates
-        .filter((edge) => edge.source !== binding.premise)
-        .filter((edge) => {
-          const source = snapshot.byId.get(edge.source).unit;
-          return source.kind === "rule" && source.lifecycle === "active";
-        });
-      targetObservations.push({
-        id: target.id,
-        attached: attachment !== null,
-        observed: new Set(incoming.map((edge) => edge.source)).size,
-        incomingRefs: [...new Set(incoming.map((edge) => edge.source))].sort(compareText),
-      });
-      observationRelated.push(relatedLocation("binding-target", target.location));
-      observationRelated.push(relatedLocation("target", targetNode.node.location));
-      if (attachment) observationRelated.push(relatedLocation("premise-attachment", attachment.relationLocation));
-      for (const edge of incoming) observationRelated.push(relatedLocation("incoming-reference", edge.relationLocation));
-      const commonRelated = [
-        relatedLocation("binding", binding.location),
-        relatedLocation("binding-target", target.location),
-        relatedLocation("premise", premise.node.location),
-      ];
-      if (!attachment) {
-        findings.push(findingBase(
-          binding,
-          target,
-          "AUTH_AUDIT_PREMISE_TARGET_UNATTACHED",
-          `premise ${binding.premise} does not directly attach required target ${target.id}`,
-          { type: "premise-direct-attachment", relation: "applies_to", attached: false },
-          targetNode.node.location,
-          commonRelated,
-        ));
-      } else {
-        commonRelated.push(relatedLocation("premise-attachment", attachment.relationLocation));
-      }
-      const observed = new Set(incoming.map((edge) => edge.source)).size;
-      if (observed < binding.minimum) {
-        for (const edge of incoming) commonRelated.push(relatedLocation("incoming-reference", edge.relationLocation));
-        findings.push(findingBase(
-          binding,
-          target,
-          "AUTH_AUDIT_MINIMUM_INDEPENDENT_INCOMING_REFERENCE",
-          `target ${target.id} has ${observed} independent active-rule applies_to references; binding requires ${binding.minimum}`,
-          {
-            type: "minimum-independent-incoming-reference",
-            relation: "applies_to",
-            minimum: binding.minimum,
-            observed,
-            incomingRefs: [...new Set(incoming.map((edge) => edge.source))].sort(compareText),
-          },
-          targetNode.node.location,
-          commonRelated,
-        ));
-      }
-    }
-    observations.push({
-      code: "AUTH_AUDIT_INDEPENDENT_INCOMING_REFERENCE_OBSERVATION",
-      detector: DETECTOR,
-      binding: binding.id,
-      premise: binding.premise,
-      basis: "governance_bound",
-      policy: binding.policy,
-      fingerprint: fingerprint([
-        "AUTH_AUDIT_INDEPENDENT_INCOMING_REFERENCE_OBSERVATION",
-        DETECTOR,
-        binding.id,
-        binding.premise,
-        `targets=${targetObservations.map((target) => target.id).join(",")}`,
-        `minimum=${binding.minimum}`,
-      ]),
-      message: `evaluated ${targetObservations.length} exact targets for binding ${binding.id}`,
-      authorityRefs: [...new Set([
-        binding.premise,
-        ...targetObservations.flatMap((target) => [target.id, ...target.incomingRefs]),
-      ])].sort(compareText),
-      primaryLocation: binding.location,
-      relatedLocations: observationRelated.sort(compareRelatedLocation),
-      witness: {
-        type: "minimum-independent-incoming-reference",
-        relation: "applies_to",
-        minimum: binding.minimum,
-        targets: targetObservations,
-      },
-    });
   }
 
-  findings.sort((left, right) => compareText(left.binding, right.binding) || compareText(left.target, right.target) || compareText(left.code, right.code));
-  gaps.sort((left, right) => compareText(left.binding, right.binding));
-  const traversal = { units: proofUnits.size, edges: proofEdges.size };
-  const firstLocation = parsedBindings.bindings[0]?.location ?? parsedBindings.required[0]?.location ?? null;
+  findings.sort((left, right) => compareText(left.binding, right.binding) || compareText(left.target ?? "", right.target ?? "") || compareText(left.code, right.code));
+  const traversal = { units: traversedUnits.size, edges: traversedEdges.size };
+  const firstLocation = parsedBindings.bindings[0]?.location ?? null;
   if (traversal.units > maxUnits) return refused(compiled, [auditBudgetDiagnostic("units", traversal.units, maxUnits, firstLocation)]);
   if (traversal.edges > maxEdges) return refused(compiled, [auditBudgetDiagnostic("edges", traversal.edges, maxEdges, firstLocation)]);
   const blocking = findings.some((finding) => finding.policy === "blocking");
   const audit = {
     format: AUDIT_FORMAT,
     operationStatus: "completed",
-    policyStatus: blocking ? "blocked" : gaps.length > 0 ? "indeterminate" : "passed",
-    complete: gaps.length === 0,
-    observations,
+    blockingStatus: blocking ? "blocked" : "clear",
     findings,
-    gaps,
     counts: {
       bindings: {
-        required: parsedBindings.required.length,
         configured: parsedBindings.bindings.length,
-        evaluated: observations.length,
+        evaluated: parsedBindings.bindings.length,
       },
       returned: {
-        observations: observations.length,
         findings: findings.length,
-        gaps: gaps.length,
       },
       traversal,
     },
@@ -487,4 +551,17 @@ export async function auditAuthorityPath(inputPath, bindingsPath, { maxUnits, ma
   };
 }
 
-export { AUDIT_FORMAT, BINDING_FORMAT, DETECTOR };
+export async function auditAuthorityPath(inputPath, bindingsPath, options) {
+  const { maxUnits, maxEdges, maxBytes } = options;
+  if (![maxUnits, maxEdges, maxBytes].every(validBudget)) {
+    return refused(null, [auditBudgetDiagnostic("positive safe-integer budget values", "all", "invalid")]);
+  }
+  const compiled = await compileAuthorityPath(inputPath);
+  if (!compiled.ok) return refused(compiled, compiled.diagnostics);
+  const absoluteInput = path.resolve(inputPath);
+  const inputInfo = await stat(absoluteInput);
+  const basePath = inputInfo.isDirectory() ? absoluteInput : path.dirname(absoluteInput);
+  return auditAuthoritySnapshot(createCompiledAuthoritySnapshot(compiled, basePath), bindingsPath, options);
+}
+
+export { AUDIT_FORMAT, BINDING_FORMAT, GRAPH_DETECTOR, LEXICAL_DETECTOR };