@nimiplatform/nimi-coding 0.1.0

package/cli/lib/audit-sweep-runtime/common.mjs

@@ -0,0 +1,329 @@
+import { createHash } from "node:crypto";
+import { appendFile, mkdir, open, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import YAML from "yaml";
+
+import { AUDIT_SWEEP_ARTIFACT_ROOTS } from "../../constants.mjs";
+import { pathExists } from "../fs-helpers.mjs";
+import { loadYamlFile } from "../yaml-helpers.mjs";
+import { isIsoUtcTimestamp, isPlainObject } from "../value-helpers.mjs";
+
+export const DEFAULT_MAX_FILES_PER_CHUNK = 60;
+export const DEFAULT_CRITERIA = ["quality"];
+export const AUDITABLE_EXTENSIONS = new Set([
+  ".cjs",
+  ".css",
+  ".go",
+  ".js",
+  ".jsx",
+  ".json",
+  ".md",
+  ".mjs",
+  ".proto",
+  ".py",
+  ".rs",
+  ".ts",
+  ".tsx",
+  ".yaml",
+  ".yml",
+]);
+export const DEFAULT_EXCLUDE_PATTERNS = [
+  ".git/",
+  ".next/",
+  ".nimi/local/",
+  ".turbo/",
+  "archive/",
+  "dist/",
+  "generated/",
+  "node_modules/",
+  "pnpm-lock.yaml",
+  "package-lock.json",
+  "yarn.lock",
+];
+export const FINDING_SEVERITY = new Set(["critical", "high", "medium", "low"]);
+export const FINDING_ACTIONABILITY = new Set(["auto-fix", "needs-decision", "deferred-backlog"]);
+export const FINDING_CONFIDENCE = new Set(["high", "medium", "low"]);
+export const FINDING_DISPOSITION = new Set(["open", "remediated", "accepted-risk", "false-positive", "deferred-backlog"]);
+export const RERUN_VERDICT = new Set(["not_reproduced", "still_reproduced", "manager_accepted", "deferred"]);
+export const CHUNK_STATES = new Set(["planned", "dispatched", "ingested", "reviewed", "frozen", "failed", "skipped"]);
+export const ACTIVE_CHUNK_STATES = new Set(["planned", "dispatched", "ingested", "reviewed"]);
+export const SEVERITY_RANK = {
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+};
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+export function toPosix(filePath) {
+  return filePath.split(path.sep).join(path.posix.sep);
+}
+
+export function stableJson(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableJson).join(",")}]`;
+  }
+
+  if (isPlainObject(value)) {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+  }
+
+  return JSON.stringify(value);
+}
+
+export function sha256Text(text) {
+  return createHash("sha256").update(text).digest("hex");
+}
+
+export function sha256Object(value) {
+  return sha256Text(stableJson(value));
+}
+
+export function relPath(projectRoot, absolutePath) {
+  return toPosix(path.relative(projectRoot, absolutePath));
+}
+
+export function isPathInside(parent, child) {
+  const relative = path.relative(parent, child);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+export function resolveInsideProject(projectRoot, inputPath, label) {
+  const absolutePath = path.resolve(projectRoot, inputPath);
+  if (!isPathInside(projectRoot, absolutePath)) {
+    return {
+      ok: false,
+      error: `nimicoding audit-sweep refused: ${label} must stay inside the project root.\n`,
+    };
+  }
+
+  return {
+    ok: true,
+    absolutePath,
+    ref: relPath(projectRoot, absolutePath),
+  };
+}
+
+export function normalizeCsv(value, fallback = []) {
+  if (!value) {
+    return [...fallback];
+  }
+
+  return String(value)
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+export function safeSweepId(value) {
+  if (typeof value !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{2,120}$/.test(value)) {
+    return null;
+  }
+
+  return value;
+}
+
+export function deriveSweepId(targetRootRef, date = new Date()) {
+  const day = date.toISOString().slice(0, 10);
+  const slug = targetRootRef
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase() || "project";
+  return `audit-sweep-${day}-${slug}`;
+}
+
+export function artifactRef(kind, ...parts) {
+  return path.posix.join(AUDIT_SWEEP_ARTIFACT_ROOTS[kind], ...parts);
+}
+
+export function artifactPath(projectRoot, ref) {
+  return path.join(projectRoot, ...ref.split("/"));
+}
+
+export async function writeYamlRef(projectRoot, ref, value) {
+  const destination = artifactPath(projectRoot, ref);
+  await mkdir(path.dirname(destination), { recursive: true });
+  await writeFile(destination, YAML.stringify(value, { aliasDuplicateObjects: false }), "utf8");
+}
+
+export async function writeJsonRef(projectRoot, ref, value) {
+  const destination = artifactPath(projectRoot, ref);
+  await mkdir(path.dirname(destination), { recursive: true });
+  await writeFile(destination, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function auditSweepLockPath(projectRoot, sweepId) {
+  return path.join(projectRoot, ".nimi", "local", "audit", "locks", `${sweepId}.lock`);
+}
+
+export async function withAuditSweepMutationLock(projectRoot, sweepId, label, fn) {
+  const lockPath = auditSweepLockPath(projectRoot, sweepId);
+  await mkdir(path.dirname(lockPath), { recursive: true });
+  let handle = null;
+  try {
+    handle = await open(lockPath, "wx");
+  } catch (error) {
+    if (error?.code === "EEXIST") {
+      return inputError(`nimicoding audit-sweep refused: ${label} mutation already in progress for ${sweepId}; retry after the current command finishes.\n`);
+    }
+    throw error;
+  }
+
+  try {
+    await handle.writeFile(`${JSON.stringify({
+      sweep_id: sweepId,
+      label,
+      pid: process.pid,
+      locked_at: nowIso(),
+    })}\n`, "utf8");
+    await handle.close();
+    handle = null;
+    return await fn();
+  } finally {
+    if (handle) {
+      await handle.close();
+    }
+    await rm(lockPath, { force: true });
+  }
+}
+
+export async function loadYamlRef(projectRoot, ref) {
+  return loadYamlFile(artifactPath(projectRoot, ref));
+}
+
+export async function loadJsonFile(filePath) {
+  try {
+    return { ok: true, value: JSON.parse(await readFile(filePath, "utf8")) };
+  } catch {
+    return { ok: false, error: "must contain valid JSON" };
+  }
+}
+
+export async function assertExistingFile(filePath, message) {
+  const info = await pathExists(filePath);
+  if (!info || !info.isFile()) {
+    return { ok: false, error: message };
+  }
+  return { ok: true };
+}
+
+export function planRef(sweepId) {
+  return artifactRef("plan_ref", `${sweepId}.yaml`);
+}
+
+export function chunkRef(sweepId, chunkId) {
+  return artifactRef("chunk_refs", sweepId, `${chunkId}.yaml`);
+}
+
+export function findingsRef(sweepId) {
+  return artifactRef("evidence_refs", sweepId, "findings.yaml");
+}
+
+export function runLedgerRef(sweepId) {
+  return artifactRef("run_ledger_ref", `${sweepId}.jsonl`);
+}
+
+export function reportRef(sweepId, snapshotId) {
+  return artifactRef("report_ref", sweepId, `${snapshotId}.md`);
+}
+
+export function ledgerRef(sweepId, snapshotId) {
+  return artifactRef("ledger_ref", sweepId, `${snapshotId}.yaml`);
+}
+
+export function remediationMapRef(sweepId, snapshotId) {
+  return artifactRef("remediation_map_ref", sweepId, `${snapshotId}.yaml`);
+}
+
+export function auditCloseoutRef(sweepId, snapshotId) {
+  return artifactRef("audit_closeout_ref", sweepId, `${snapshotId}.yaml`);
+}
+
+export function packetRef(sweepId, chunkId) {
+  return artifactRef("packet_ref", sweepId, `${chunkId}.auditor-packet.yaml`);
+}
+
+export async function appendRunEvent(projectRoot, sweepId, event) {
+  const ref = runLedgerRef(sweepId);
+  const destination = artifactPath(projectRoot, ref);
+  await mkdir(path.dirname(destination), { recursive: true });
+  await appendFile(destination, `${JSON.stringify({
+    event_id: sha256Object({ sweepId, event, ordinal_hint: Date.now() }).slice(0, 16),
+    sweep_id: sweepId,
+    recorded_at: nowIso(),
+    ...event,
+  })}\n`, "utf8");
+  return ref;
+}
+
+export async function loadPlan(projectRoot, sweepId) {
+  const ref = planRef(sweepId);
+  const plan = await loadYamlRef(projectRoot, ref);
+  if (!isPlainObject(plan) || plan.kind !== "audit-plan" || plan.sweep_id !== sweepId) {
+    return { ok: false, error: `nimicoding audit-sweep refused: plan not found for ${sweepId}.\n` };
+  }
+  return { ok: true, plan, planRef: ref };
+}
+
+export async function loadChunk(projectRoot, sweepId, chunkId) {
+  const ref = chunkRef(sweepId, chunkId);
+  const chunk = await loadYamlRef(projectRoot, ref);
+  if (!isPlainObject(chunk) || chunk.kind !== "audit-chunk" || chunk.sweep_id !== sweepId || chunk.chunk_id !== chunkId) {
+    return { ok: false, error: `nimicoding audit-sweep refused: chunk not found for ${sweepId}/${chunkId}.\n` };
+  }
+  return { ok: true, chunk, chunkRef: ref };
+}
+
+export async function loadFindings(projectRoot, sweepId) {
+  const ref = findingsRef(sweepId);
+  const existing = await loadYamlRef(projectRoot, ref);
+  if (isPlainObject(existing) && existing.kind === "audit-findings" && existing.sweep_id === sweepId && Array.isArray(existing.findings)) {
+    return { findingsRef: ref, store: existing };
+  }
+
+  return {
+    findingsRef: ref,
+    store: {
+      version: 1,
+      kind: "audit-findings",
+      sweep_id: sweepId,
+      findings: [],
+      duplicate_count: 0,
+      clusters: [],
+      clustered_symptom_count: 0,
+      accepted_cluster_skip_count: 0,
+      remediation_obligation_count: 0,
+      updated_at: nowIso(),
+    },
+  };
+}
+
+export async function loadLatestLedger(projectRoot, sweepId) {
+  const latestRef = artifactRef("ledger_ref", sweepId, "latest.yaml");
+  const pointer = await loadYamlRef(projectRoot, latestRef);
+  if (!isPlainObject(pointer) || typeof pointer.ledger_ref !== "string") {
+    return { ok: false, error: `nimicoding audit-sweep refused: latest ledger not found for ${sweepId}.\n` };
+  }
+
+  const ledger = await loadYamlRef(projectRoot, pointer.ledger_ref);
+  if (!isPlainObject(ledger) || ledger.kind !== "audit-ledger" || ledger.sweep_id !== sweepId) {
+    return { ok: false, error: `nimicoding audit-sweep refused: latest ledger is malformed for ${sweepId}.\n` };
+  }
+
+  return { ok: true, ledger, ledgerRef: pointer.ledger_ref, pointerRef: latestRef };
+}
+
+export function inputError(error) {
+  return { ok: false, inputError: true, exitCode: 2, error };
+}
+
+export function ensureIsoTimestamp(value, label = "--verified-at") {
+  if (!isIsoUtcTimestamp(value)) {
+    return inputError(`nimicoding audit-sweep refused: ${label} must be an ISO-8601 UTC timestamp.\n`);
+  }
+  return null;
+}

package/cli/lib/audit-sweep-runtime/coverage-quality.mjs

@@ -0,0 +1,172 @@
+export const COVERAGE_SCOPE_LABEL = "declared_authority_and_evidence_inventory";
+export const FILE_INVENTORY_SCOPE_LABEL = "file_inventory";
+
+function makeDiagnostic(id, message, details = {}) {
+  return { id, message, ...details };
+}
+
+function ownerDomainCoverage(chunks) {
+  const byOwner = {};
+  for (const chunk of chunks) {
+    const ownerDomain = chunk.owner_domain ?? "unknown";
+    const evidenceCount = Array.isArray(chunk.evidence_inventory) ? chunk.evidence_inventory.length : 0;
+    const entry = byOwner[ownerDomain] ?? {
+      authority_chunks: 0,
+      chunks_with_evidence_inventory: 0,
+      chunks_without_evidence_inventory: 0,
+      evidence_file_refs: new Set(),
+      posture: "strong",
+    };
+    entry.authority_chunks += 1;
+    for (const fileRef of Array.isArray(chunk.evidence_inventory) ? chunk.evidence_inventory : []) {
+      entry.evidence_file_refs.add(fileRef);
+    }
+    if (evidenceCount > 0) {
+      entry.chunks_with_evidence_inventory += 1;
+    } else {
+      entry.chunks_without_evidence_inventory += 1;
+    }
+    byOwner[ownerDomain] = entry;
+  }
+  for (const entry of Object.values(byOwner)) {
+    entry.evidence_files = entry.evidence_file_refs.size;
+    delete entry.evidence_file_refs;
+    entry.posture = entry.authority_chunks > 0 && entry.evidence_files === 0 ? "warning" : "strong";
+  }
+  return byOwner;
+}
+
+export function buildCoverageQuality(plan, chunks, coverage = plan.coverage ?? {}) {
+  if (plan?.planning_basis?.mode !== "spec_authority") {
+    return {
+      scope_label: FILE_INVENTORY_SCOPE_LABEL,
+      posture: "strong",
+      authority_chunk_count: chunks.length,
+      chunks_with_evidence_inventory: 0,
+      chunks_without_evidence_inventory: 0,
+      empty_evidence_chunk_ratio: 0,
+      evidence_file_count: 0,
+      max_evidence_files_per_chunk: 0,
+      max_evidence_chunk_id: null,
+      evidence_concentration_ratio: 0,
+      owner_domain_coverage: ownerDomainCoverage(chunks),
+      warnings: [],
+      blockers: [],
+    };
+  }
+
+  const authorityChunkCount = chunks.length;
+  const evidenceCounts = chunks.map((chunk) => Array.isArray(chunk.evidence_inventory) ? chunk.evidence_inventory.length : 0);
+  const chunksWithEvidenceInventory = evidenceCounts.filter((count) => count > 0).length;
+  const chunksWithoutEvidenceInventory = authorityChunkCount - chunksWithEvidenceInventory;
+  const evidenceFileCount = coverage.evidence_coverage?.total_files
+    ?? coverage.evidence_files
+    ?? plan.evidence_inventory?.length
+    ?? 0;
+  const maxEvidenceFilesPerChunk = evidenceCounts.length > 0 ? Math.max(...evidenceCounts) : 0;
+  const maxEvidenceChunkIndex = evidenceCounts.findIndex((count) => count === maxEvidenceFilesPerChunk);
+  const maxEvidenceChunkId = maxEvidenceChunkIndex >= 0 ? chunks[maxEvidenceChunkIndex]?.chunk_id ?? null : null;
+  const evidenceConcentrationRatio = evidenceFileCount > 0 ? maxEvidenceFilesPerChunk / evidenceFileCount : 0;
+  const emptyEvidenceChunkRatio = authorityChunkCount > 0 ? chunksWithoutEvidenceInventory / authorityChunkCount : 0;
+  const ownerCoverage = ownerDomainCoverage(chunks);
+  const warnings = [];
+  const blockers = [];
+
+  if (chunksWithoutEvidenceInventory > 0) {
+    warnings.push(makeDiagnostic("sparse_evidence_inventory", "Some authority chunks have no mapped evidence inventory.", {
+      chunks_without_evidence_inventory: chunksWithoutEvidenceInventory,
+      authority_chunk_count: authorityChunkCount,
+    }));
+  }
+
+  for (const [owner_domain, entry] of Object.entries(ownerCoverage)) {
+    if (entry.authority_chunks > 0 && entry.evidence_files === 0) {
+      warnings.push(makeDiagnostic("owner_domain_authority_only", "Owner domain has authority chunks but no mapped evidence files.", {
+        owner_domain,
+        authority_chunks: entry.authority_chunks,
+      }));
+    }
+  }
+
+  if (evidenceFileCount > 0 && evidenceConcentrationRatio >= 0.5 && chunksWithEvidenceInventory > 1) {
+    warnings.push(makeDiagnostic("evidence_fan_in_concentrated", "One chunk owns a concentrated share of the mapped evidence inventory.", {
+      chunk_id: maxEvidenceChunkId,
+      evidence_concentration_ratio: evidenceConcentrationRatio,
+    }));
+  }
+
+  const unresolvedChunks = chunks
+    .filter((chunk) => Array.isArray(chunk.declared_evidence_unresolved) && chunk.declared_evidence_unresolved.length > 0)
+    .map((chunk) => chunk.chunk_id);
+  if (unresolvedChunks.length > 0) {
+    blockers.push(makeDiagnostic("declared_evidence_target_unresolved", "Declared evidence targets remain unresolved.", {
+      chunk_ids: unresolvedChunks,
+    }));
+  }
+
+  const unmappedEvidenceFiles = coverage.evidence_coverage?.unmapped_files
+    ?? coverage.unmapped_evidence_files
+    ?? plan.unmapped_evidence_files?.length
+    ?? 0;
+  if (unmappedEvidenceFiles > 0) {
+    blockers.push(makeDiagnostic("unmapped_evidence_files", "Evidence inventory contains files that no authority chunk can accept.", {
+      unmapped_evidence_files: unmappedEvidenceFiles,
+    }));
+  }
+
+  return {
+    scope_label: COVERAGE_SCOPE_LABEL,
+    posture: blockers.length > 0 ? "blocked" : warnings.length > 0 ? "warning" : "strong",
+    authority_chunk_count: authorityChunkCount,
+    chunks_with_evidence_inventory: chunksWithEvidenceInventory,
+    chunks_without_evidence_inventory: chunksWithoutEvidenceInventory,
+    empty_evidence_chunk_ratio: emptyEvidenceChunkRatio,
+    evidence_file_count: evidenceFileCount,
+    max_evidence_files_per_chunk: maxEvidenceFilesPerChunk,
+    max_evidence_chunk_id: maxEvidenceChunkId,
+    evidence_concentration_ratio: evidenceConcentrationRatio,
+    owner_domain_coverage: ownerCoverage,
+    warnings,
+    blockers,
+  };
+}
+
+export function withFullScopeWarning(coverageQuality) {
+  if (!coverageQuality) {
+    return coverageQuality;
+  }
+  if (coverageQuality.scope_label !== COVERAGE_SCOPE_LABEL) {
+    return coverageQuality;
+  }
+  if (coverageQuality.warnings?.some((warning) => warning.id === "full_status_scope_is_declared_inventory")) {
+    return coverageQuality;
+  }
+  return {
+    ...coverageQuality,
+    posture: coverageQuality.posture === "strong" ? "warning" : coverageQuality.posture,
+    warnings: [
+      ...(coverageQuality.warnings ?? []),
+      makeDiagnostic("full_status_scope_is_declared_inventory", "Full spec-authority coverage is scoped to declared authority and admitted evidence inventory."),
+    ],
+  };
+}
+
+export function deriveCoverageStatus(ledgerStatus) {
+  if (ledgerStatus === "candidate_ready") {
+    return "full";
+  }
+  if (ledgerStatus === "blocked") {
+    return "blocked";
+  }
+  return "partial";
+}
+
+export function deriveCoverageCloseoutPosture({ coverageStatus, openFindingCount }) {
+  if (coverageStatus === "blocked") {
+    return "blocked";
+  }
+  if (coverageStatus === "partial") {
+    return openFindingCount > 0 ? "partial_coverage_findings_open" : "partial_coverage_all_findings_postured";
+  }
+  return openFindingCount > 0 ? "audit_complete_findings_open" : "audit_complete_all_findings_postured";
+}

package/cli/lib/audit-sweep-runtime/evidence-assignment.mjs

@@ -0,0 +1,152 @@
+function chunkMatchesEvidenceFile(chunk, fileRef) {
+  const roots = Array.isArray(chunk.admitted_evidence_roots) && chunk.admitted_evidence_roots.length > 0
+    ? chunk.admitted_evidence_roots
+    : chunk.evidence_roots;
+  return Array.isArray(roots)
+    && roots.some((rootRef) => {
+      const normalizedRoot = rootRef.replace(/\\/g, "/").replace(/\/$/, "");
+      return fileRef === normalizedRoot || fileRef.startsWith(`${normalizedRoot}/`);
+    });
+}
+
+function normalizedRef(value) {
+  return String(value ?? "").replace(/\\/g, "/").replace(/\/$/, "");
+}
+
+function refInsideRoot(fileRef, rootRef) {
+  const normalizedRoot = normalizedRef(rootRef);
+  return Boolean(normalizedRoot) && (fileRef === normalizedRoot || fileRef.startsWith(`${normalizedRoot}/`));
+}
+
+function chunkHasExactAdmittedEvidenceRef(chunk, fileRef) {
+  return Array.isArray(chunk.evidence_root_admission_refs)
+    && Array.isArray(chunk.admitted_evidence_roots)
+    && chunk.admitted_evidence_roots.some((rootRef) => normalizedRef(rootRef) === fileRef);
+}
+
+function topLevelEvidenceDocForRoot(rootRef, fileRef) {
+  const normalizedRoot = normalizedRef(rootRef);
+  if (!normalizedRoot || !refInsideRoot(fileRef, normalizedRoot)) {
+    return false;
+  }
+  const relative = fileRef === normalizedRoot ? "" : fileRef.slice(normalizedRoot.length + 1);
+  return !relative.includes("/") && /^(README|AGENTS)(?:\.[^.]+)?$/i.test(relative);
+}
+
+function chunkDeclaredEvidenceRoots(chunk) {
+  if (!Array.isArray(chunk.declared_evidence_targets)) {
+    return [];
+  }
+  return chunk.declared_evidence_targets
+    .flatMap((target) => Array.isArray(target.candidates) ? target.candidates : [])
+    .map((candidate) => normalizedRef(candidate))
+    .filter(Boolean);
+}
+
+function chunkAcceptsEvidenceFile(chunk, fileRef) {
+  const surface = String(chunk.spec_surface ?? "");
+  if (chunkDeclaredEvidenceRoots(chunk).some((rootRef) => refInsideRoot(fileRef, rootRef))) {
+    return true;
+  }
+  const roots = Array.isArray(chunk.admitted_evidence_roots) && chunk.admitted_evidence_roots.length > 0
+    ? chunk.admitted_evidence_roots
+    : chunk.evidence_roots;
+  const isTopLevelDoc = (roots ?? []).some((rootRef) => topLevelEvidenceDocForRoot(rootRef, fileRef));
+  if (isTopLevelDoc) {
+    return surface === "domain-guides" || surface === "app-domain-guides" || surface === "package-root" || surface === "INDEX";
+  }
+  if (
+    surface === "kernel-contracts"
+    || surface === "app-kernel-contracts"
+    || surface === "kernel-tables"
+    || surface === "app-kernel-tables"
+    || surface === "package-kernel-tables"
+  ) {
+    return true;
+  }
+  if (surface === "spec-generation-audit" || surface === "high-risk-admissions" || surface === "package-meta" || surface === "package-root") {
+    return true;
+  }
+  return false;
+}
+
+function unresolvedDeclaredEvidenceTargets(chunk, evidenceEntries) {
+  if (!Array.isArray(chunk.declared_evidence_targets)) {
+    return [];
+  }
+  return chunk.declared_evidence_targets
+    .map((target) => {
+      const candidates = Array.isArray(target.candidates)
+        ? target.candidates.map((candidate) => normalizedRef(candidate)).filter(Boolean)
+        : [];
+      const resolved = candidates.some((candidate) => evidenceEntries.some((entry) => refInsideRoot(entry.file_ref, candidate)));
+      return resolved ? null : {
+        source_path: target.source_path,
+        candidates,
+      };
+    })
+    .filter(Boolean);
+}
+
+function deriveEmptyEvidenceInventoryReason(chunk) {
+  if (chunk.spec_surface === "kernel-generated" || String(chunk.spec_surface ?? "").includes("generated")) {
+    return "generated_projection_authority_no_direct_implementation_evidence";
+  }
+  if (chunk.spec_surface === "kernel-tables" || String(chunk.spec_surface ?? "").includes("tables")) {
+    return "structured_fact_authority_no_direct_implementation_evidence";
+  }
+  if (chunk.spec_surface === "domain-guides" || String(chunk.spec_surface ?? "").endsWith("guides")) {
+    return "domain_guide_authority_no_direct_implementation_evidence";
+  }
+  return "no_matching_evidence_files_after_spec_authority_assignment";
+}
+
+export function assignEvidenceInventory(evidenceEntries, chunks, options = {}) {
+  const chunksById = new Map(chunks.map((chunk) => [chunk.chunk_id, { ...chunk, evidence_inventory: [] }]));
+  const unmapped = [];
+
+  for (const entry of evidenceEntries.sort((left, right) => left.file_ref.localeCompare(right.file_ref))) {
+    const candidates = chunks.filter((chunk) => chunkMatchesEvidenceFile(chunk, entry.file_ref));
+    if (candidates.length === 0) {
+      unmapped.push(entry.file_ref);
+      continue;
+    }
+    const exactAdmissionCandidates = candidates.filter((chunk) => chunkHasExactAdmittedEvidenceRef(chunk, entry.file_ref));
+    const selectedChunks = (exactAdmissionCandidates.length > 0 ? exactAdmissionCandidates : candidates.filter((chunk) => chunkAcceptsEvidenceFile(chunk, entry.file_ref)))
+      .sort((left, right) => left.chunk_id.localeCompare(right.chunk_id));
+    if (selectedChunks.length === 0) {
+      unmapped.push(entry.file_ref);
+      continue;
+    }
+    for (const selected of selectedChunks) {
+      chunksById.get(selected.chunk_id).evidence_inventory.push(entry.file_ref);
+    }
+  }
+
+  return {
+    chunks: chunks.map((chunk) => {
+      const enriched = chunksById.get(chunk.chunk_id);
+      const evidenceInventory = enriched.evidence_inventory.sort();
+      const evidenceInventoryEmpty = evidenceInventory.length === 0;
+      const declaredEvidenceUnresolved = unresolvedDeclaredEvidenceTargets(chunk, evidenceEntries);
+      return {
+        ...chunk,
+        evidence_inventory: evidenceInventory,
+        evidence_inventory_status: evidenceInventoryEmpty ? "empty" : "mapped",
+        ...(declaredEvidenceUnresolved.length > 0 ? {
+          declared_evidence_unresolved: declaredEvidenceUnresolved,
+        } : {}),
+        ...(evidenceInventoryEmpty ? {
+          evidence_inventory_empty_reason: deriveEmptyEvidenceInventoryReason(chunk),
+        } : {}),
+        coverage_contract: {
+          authority_refs_required: true,
+          evidence_inventory_required: true,
+          evidence_files_must_cover_inventory: true,
+          empty_evidence_inventory_requires_reason: true,
+        },
+      };
+    }),
+    unmappedEvidenceFiles: unmapped.sort(),
+  };
+}