filegrc 0.11.0 → 0.12.0

package/src/evidence-packet.js

@@ -11,10 +11,11 @@ import {
   coverageOverlaps,
   coverageStart
 } from "./coverage.js";
-import { getFilesAtRevisions, getGitSummary, getWorkspaceHistories, getWorkspaceRevisionSnapshot, hasGitRevision } from "./git.js";
+import { getFileHistoryWithPaths, getFilesAtRevisions, getGitSummary, getRecordIdentityHistories, getWorkspaceHistories, getWorkspaceRevisionSnapshot, hasGitRevision, isDataHistoryAncestor } from "./git.js";
 import { planObligations } from "./obligations.js";
 import { isWithin, resolveDataPath, resolveWorkspacePath, resolveWorkspaceRoot } from "./paths.js";
 import { parseCalendarDate } from "./recurrence.js";
+import { resolveProgram, selectedRequirementIds } from "./program.js";
 import { markdownEntries } from "./resource-markdown.js";
 import { serializeWorkspaceMutation } from "./mutation.js";
 import {
@@ -29,6 +30,8 @@ import {
 } from "./soc2.js";
 import { validateWorkspace } from "./validate.js";
 import { measureTiming } from "./timing.js";
+import { assessReportingRoutePeriod } from "./reporting-route-sets.js";
+import { reportingRouteEventCommit, reportingRouteSourceAppliesToProgram, reportingRouteSourceMayApply } from "./reporting-route-integrity.js";
 
 const preparedPacketValidations = new WeakMap();
 
@@ -45,11 +48,15 @@ const NON_EVIDENCE_RECORD_TYPES = new Set([
   "evidence",
   "framework",
   "obligation",
+  "obligation-occurrence",
+  "obligation-rule",
   "organization",
   "person",
   "policy",
   "renderer-settings",
   "requirement",
+  "reporting-route",
+  "reporting-route-set",
   "system",
   "team",
   "training",
@@ -65,10 +72,25 @@ export async function prepareEvidencePacket(input, options = {}) {
   const entriesById = new Map(loaded.entries.map((entry) => [entry.record.id, entry]));
   const audit = options.auditId ? byId.get(options.auditId) : null;
   if (options.auditId && audit?.type !== "audit") throw new Error(`Audit "${options.auditId}" was not found.`);
+  if (audit?.programId && options.programId && audit.programId !== options.programId) {
+    throw new Error(`Audit "${audit.id}" belongs to Program "${audit.programId}", not "${options.programId}".`);
+  }
+  const program = modelSupports(loaded.model, "program-scope")
+    ? resolveProgram(loaded, options.programId || audit?.programId)
+    : null;
+  const scope = audit || (program ? {
+    id: `program-scope:${program.id}`,
+    programScope: true,
+    programId: program.id,
+    frameworkIds: program.frameworkIds || [],
+    systemIds: program.systemIds || [],
+    requirementIds: selectedRequirementIds(program, loaded.model),
+    controlIds: program.controlIds || []
+  } : null);
   const { start, end, basis } = resolvePacketPeriod(options, audit);
   const typeOne = audit?.auditKind === "soc-2-type-1";
   const datedRecords = loaded.entries
-    .filter((entry) => !audit || recordRelevantToAudit(entry.record, audit, byId))
+    .filter((entry) => !scope || recordRelevantToAudit(entry.record, scope, byId))
     .map((entry) => packetRecord(entry.record, loaded.model, start, end, loaded.workspace.timezone))
     .filter(Boolean);
   const datedRecordIds = new Set(datedRecords.map(({ id }) => id));
@@ -78,19 +100,21 @@ export async function prepareEvidencePacket(input, options = {}) {
     ))
   );
   const plan = planObligations(records, {
+    programId: program?.id || options.programId || audit?.programId,
     asOf: end,
     from: start,
     through: end,
     includeComplete: true,
+    additionalControlIds: audit?.controlIds || [],
     model: loaded.model
   });
   const obligations = (typeOne ? [] : plan.calendarItems).filter((item) => (
     item.dueWindowStart <= end
     && item.overdueOn > start
-    && (!audit || recordRelevantToAudit(byId.get(item.obligationId), audit, byId))
+    && (!scope || recordRelevantToAudit(byId.get(item.obligationId), scope, byId))
   ));
   const eventRuns = (typeOne ? [] : plan.eventRuns).filter((run) => (
-    (!audit || run.actions.some((action) => recordRelevantToAudit(byId.get(action.obligationId), audit, byId)))
+    (!scope || run.actions.some((action) => recordRelevantToAudit(byId.get(action.obligationId), scope, byId)))
     && (
       (run.occurredOn >= start && run.occurredOn <= end)
       || datedEvidenceSourceIds.has(run.id)
@@ -103,6 +127,7 @@ export async function prepareEvidencePacket(input, options = {}) {
     )
   ));
   const selectedIds = new Set(datedRecords.map((record) => record.id));
+  if (program) selectedIds.add(program.id);
   if (audit) {
     selectedIds.add(audit.id);
     addIds(selectedIds, [
@@ -137,6 +162,8 @@ export async function prepareEvidencePacket(input, options = {}) {
   }
   for (const item of obligations) {
     selectedIds.add(item.obligationId);
+    if (item.ruleId) selectedIds.add(item.ruleId);
+    if (item.occurrenceId) selectedIds.add(item.occurrenceId);
     addIds(selectedIds, item.completionResourceIds);
     addIds(selectedIds, item.evidenceIds);
   }
@@ -151,28 +178,12 @@ export async function prepareEvidencePacket(input, options = {}) {
   }
 
   const evidenceIds = new Set();
-  for (const evidence of records.filter((record) => record.type === "evidence")) {
-    if (audit && !recordRelevantToAudit(evidence, audit, byId)) continue;
-    const direct = selectedIds.has(evidence.id)
-      || (evidence.sourceResourceIds || []).some((id) => selectedIds.has(id))
-      || overlapsEvidencePeriod(evidence, start, end);
-    if (direct) evidenceIds.add(evidence.id);
-  }
-  for (const id of [...selectedIds]) {
-    const record = byId.get(id);
-    addIds(evidenceIds, record?.evidenceIds);
-    addIds(evidenceIds, record?.sampleEvidenceIds);
-    if (record?.sourceEvidenceId) evidenceIds.add(record.sourceEvidenceId);
-    if (record?.populationId) selectedIds.add(record.populationId);
-  }
-  addIds(selectedIds, evidenceIds);
-  expandEvidenceWorkflowContext(selectedIds, byId);
-  for (const id of selectedIds) if (byId.get(id)?.type === "evidence") evidenceIds.add(id);
+  closeEvidenceSelection({ selectedIds, evidenceIds, records, scope, byId, start, end });
 
-  const controlIds = new Set(audit?.controlIds || records
+  const controlIds = new Set(scope?.controlIds || records
     .filter((record) => record.type === "control" && !["not-applicable", "retired"].includes(record.status))
     .map(({ id }) => id));
-  if (!audit) {
+  if (!scope) {
     for (const id of selectedIds) {
       const record = byId.get(id);
       addIds(controlIds, record?.controlIds);
@@ -204,7 +215,7 @@ export async function prepareEvidencePacket(input, options = {}) {
       selectedIds.add(complementaryControl.id);
     }
   }
-  for (const systemId of audit?.systemIds || []) {
+  for (const systemId of scope?.systemIds || []) {
     const system = byId.get(systemId);
     addIds(selectedIds, system?.subserviceVendorIds);
     for (const commitment of records.filter((record) => (
@@ -214,9 +225,8 @@ export async function prepareEvidencePacket(input, options = {}) {
     }
   }
 
-  const policyIds = new Set(audit
-    ? []
-    : records.filter((record) => record.type === "policy" && ["approved", "active"].includes(record.status)).map((record) => record.id));
+  const policyIds = new Set(program?.policyIds || []);
+  if (!scope) addIds(policyIds, records.filter((record) => record.type === "policy" && ["approved", "active"].includes(record.status)).map((record) => record.id));
   for (const id of selectedIds) addIds(policyIds, policyIdsFor(byId.get(id), byId));
   for (const controlId of controlIds) addIds(policyIds, byId.get(controlId)?.policyIds);
   expandSupersededPolicyIds(policyIds, byId);
@@ -224,12 +234,67 @@ export async function prepareEvidencePacket(input, options = {}) {
 
   const requirementIds = new Set();
   for (const controlId of controlIds) addIds(requirementIds, byId.get(controlId)?.requirementIds);
-  if (audit) addIds(requirementIds, audit.requirementIds);
+  if (scope) addIds(requirementIds, scope.requirementIds);
   addIds(selectedIds, requirementIds);
 
+  const routeRequirementsApply = records.some((record) => (
+    reportingRouteSourceMayApply(record)
+    && record.reportingRouteRequirements?.length
+    && (!program || reportingRouteSourceAppliesToProgram(record, program, records))
+  ));
+  const reportingRouteCoverage = modelSupports(loaded.model, "reporting-route-sets")
+    ? audit && routeRequirementsApply && !audit.timezone
+      ? {
+        supported: true,
+        start,
+        end,
+        timezone: null,
+        snapshots: [],
+        issues: [{
+          code: "missing-audit-timezone",
+          resourceId: audit.id,
+          message: `${audit.title} needs an IANA timezone before FileGRC can assess reporting-route coverage across its date boundaries.`
+        }]
+      }
+      : await assessReportingRoutePeriod(loaded, {
+        start,
+        end,
+        programId: program?.id || audit?.programId,
+        timezone: audit?.timezone || loaded.workspace.timezone
+      })
+    : null;
+  const reportingRouteSets = new Map();
+  for (const assessment of (reportingRouteCoverage?.snapshots || []).flatMap((snapshot) => governingReportingRouteSets(snapshot))) {
+    const current = reportingRouteSets.get(assessment.record.id);
+    reportingRouteSets.set(assessment.record.id, current ? {
+      ...assessment,
+      authorities: [...new Map([...current.authorities, ...assessment.authorities].map((item) => [item.id, item])).values()]
+    } : assessment);
+  }
+  for (const { record: routeSet, authorities } of reportingRouteSets.values()) {
+    selectedIds.add(routeSet.id);
+    addIds(selectedIds, routeSet.sourceResourceIds);
+    addIds(selectedIds, authorities.map(({ id }) => id));
+    addIds(selectedIds, authorities.map(({ holderId }) => holderId));
+    for (const exception of records.filter((record) => (
+      record.type === "exception" && record.reportingRouteSetId === routeSet.id
+    ))) selectedIds.add(exception.id);
+  }
+  for (const snapshot of reportingRouteCoverage?.snapshots || []) {
+    addIds(selectedIds, snapshot.requirements.map(({ sourceId }) => sourceId));
+  }
+  closeEvidenceSelection({ selectedIds, evidenceIds, records, scope, byId, start, end });
+
+  const historyRevision = await getWorkspaceRevisionSnapshot(loaded.root);
   const sourceRevisionValidity = new Map();
   const revisionIsValid = (revision) => {
-    if (!sourceRevisionValidity.has(revision)) sourceRevisionValidity.set(revision, hasGitRevision(loaded.root, revision));
+    if (!sourceRevisionValidity.has(revision)) {
+      sourceRevisionValidity.set(revision, Boolean(
+        historyRevision.commit
+        && hasGitRevision(loaded.root, revision)
+        && isDataHistoryAncestor(loaded, revision, historyRevision.commit)
+      ));
+    }
     return sourceRevisionValidity.get(revision);
   };
   const evidence = [...evidenceIds].map((id) => evidenceSummary(byId.get(id), byId, revisionIsValid)).filter(Boolean).sort(byTitle);
@@ -237,7 +302,7 @@ export async function prepareEvidencePacket(input, options = {}) {
   const sourceSystemIds = new Set([
     ...(v4
       ? [...controlIds].flatMap((id) => byId.get(id)?.evidenceSourceComponentIds || [])
-      : audit?.systemIds || []),
+      : scope?.systemIds || []),
     ...evidence.map((item) => item.sourceComponentId || item.sourceSystemId).filter(Boolean)
   ]);
   const sourceSystems = [...sourceSystemIds]
@@ -249,13 +314,13 @@ export async function prepareEvidencePacket(input, options = {}) {
     `data/${entry.relativePath}`,
     ...markdownEntries(loaded.model, entry.record).map((markdown) => `data/${markdown.path}`)
   ]);
-  const historyRevision = await getWorkspaceRevisionSnapshot(loaded.root);
   const histories = getWorkspaceHistories(
     loaded.root,
     selectedPaths,
     Number.MAX_SAFE_INTEGER,
     { strict: Boolean(historyRevision.commit) }
   );
+  const identityHistories = getRecordIdentityHistories(loaded.root, selectedIds);
   const packetRecords = [...selectedIds]
     .map((id) => byId.get(id))
     .filter(Boolean)
@@ -270,10 +335,10 @@ export async function prepareEvidencePacket(input, options = {}) {
         dates: packetRecord(record, loaded.model, start, end, loaded.workspace.timezone)?.dates || [],
         policyIds: policyIdsFor(record, byId),
         evidenceIds: record.evidenceIds || [],
-        history: histories.get(path) || [],
+        history: identityHistories.get(record.id) || [],
         contentPaths: contentPaths.map((contentPath) => ({
           path: contentPath,
-          history: histories.get(contentPath) || []
+          history: getFileHistoryWithPaths(loaded.root, contentPath, Number.MAX_SAFE_INTEGER) || histories.get(contentPath) || []
         }))
       };
     })
@@ -300,13 +365,21 @@ export async function prepareEvidencePacket(input, options = {}) {
     !NON_EVIDENCE_RECORD_TYPES.has(record.type)
     && controlIdsForRecord(byId.get(record.id), byId).size
   ));
+  const referencedPopulationIds = new Set(controlCoverage.flatMap(({ tests }) => (
+    tests.map(({ populationId }) => populationId).filter(Boolean)
+  )));
   const populations = (typeOne ? [] : records)
-    .filter((record) => record.type === "audit-population" && (!audit || record.auditId === audit.id))
+    .filter((record) => (
+      record.type === "audit-population"
+      && (record.status !== "superseded" || referencedPopulationIds.has(record.id))
+      && (!scope || recordRelevantToAudit(record, scope, byId))
+    ))
     .map((record) => populationSummary(record, byId))
     .sort(byTitle);
   const generatedAt = options.generatedAt || new Date().toISOString();
   const managementPreparation = await assessAuditPreparation(loaded, {
     auditId: audit?.id,
+    programId: program?.id,
     generatedAt,
     selectDefault: false
   });
@@ -325,7 +398,8 @@ export async function prepareEvidencePacket(input, options = {}) {
     records,
     populations,
     model: loaded.model,
-    managementPreparation
+    managementPreparation,
+    reportingRouteCoverage
   });
   const errorCount = gaps.filter(({ severity }) => severity === "error").length;
   const warningCount = gaps.filter(({ severity }) => severity === "warning").length;
@@ -376,7 +450,7 @@ export async function prepareEvidencePacket(input, options = {}) {
       policies: policyIds.size,
       controls: controlIds.size,
       requirements: requirementIds.size,
-      systems: audit?.systemIds?.length || 0,
+      systems: scope?.systemIds?.length || 0,
       [v4 ? "sourceComponents" : "sourceSystems"]: sourceSystems.length,
       obligationOccurrences: obligations.length,
       eventRuns: eventRuns.length,
@@ -398,6 +472,54 @@ export async function prepareEvidencePacket(input, options = {}) {
     dataModelVersion: String(loaded.model.modelVersion),
     populations,
     ...(modelSupports(loaded.model, "governed-document-activation") ? { documentLifecycles } : {}),
+    ...(reportingRouteCoverage ? {
+      reportingRouteCoverage: {
+        start: reportingRouteCoverage.start,
+        end: reportingRouteCoverage.end,
+        timezone: reportingRouteCoverage.timezone,
+        snapshots: reportingRouteCoverage.snapshots.map((snapshot) => ({
+          at: snapshot.at,
+          requirements: snapshot.requirements,
+          routeSets: governingReportingRouteSets(snapshot).map(({
+            record,
+            committed,
+            effective,
+            canceled,
+            authorities,
+            approvalAssertionTiming,
+            cancellationAssertionTiming
+          }) => ({
+            id: record.id,
+            title: record.title,
+            status: record.status,
+            purposeKey: record.purposeKey,
+            predecessorId: record.predecessorId || null,
+            proposalCommit: record.proposalCommit || null,
+            approval: record.approval
+              ? {
+                ...record.approval,
+                assertionTiming: approvalAssertionTiming,
+                authorityRevision: reportingRouteEventCommit(loaded, record, "approval")
+              }
+              : null,
+            cancellation: record.cancellation
+              ? {
+                ...record.cancellation,
+                assertionTiming: cancellationAssertionTiming,
+                authorityRevision: reportingRouteEventCommit(loaded, record, "cancellation")
+              }
+              : null,
+            primaryLane: record.primaryLane,
+            alternateLane: record.alternateLane || null,
+            committed,
+            effective,
+            canceled,
+            authorityAppointmentIds: authorities.map(({ id }) => id)
+          })),
+          issues: snapshot.issues
+        }))
+      }
+    } : {}),
     managementPreparation,
     controlCoverage,
     gaps,
@@ -473,6 +595,7 @@ function recordRelevantToAudit(record, audit, byId, seen = new Set()) {
   if (record.id === audit.id || record.auditId === audit.id || (record.auditIds || []).includes(audit.id)) return true;
   if (record.auditId && record.auditId !== audit.id) return false;
   if ((record.auditIds || []).length) return false;
+  if (audit.programScope && audit.programId && record.programId) return record.programId === audit.programId;
   const selectedIds = new Set([
     ...(audit.frameworkIds || []),
     ...(audit.systemIds || []),
@@ -542,9 +665,48 @@ function expandEvidenceWorkflowContext(selectedIds, byId) {
   for (let index = 0; index < queue.length; index += 1) {
     const record = byId.get(queue[index]);
     enqueue(childrenBySource.get(record?.id));
+    enqueue([
+      ...(record?.completionResourceIds || []),
+      ...(record?.evidenceIds || []),
+      ...(record?.sampleEvidenceIds || []),
+      ...(record?.exceptionIds || []),
+      ...(record?.attestationIds || []),
+      record?.sourceEvidenceId,
+      record?.exceptionId
+    ]);
     if (record?.type === "evidence") enqueue([...(record.sourceResourceIds || []), record.sourceComponentId, record.sourceSystemId]);
     if (record?.type === "audit-population") enqueue([record.sourceEvidenceId, ...(record.controlIds || [])]);
     if (record?.type === "control-test") enqueue([record.populationId, ...(record.sampleEvidenceIds || [])]);
+    if (record?.type === "obligation-occurrence") {
+      enqueue((record.members || []).flatMap((member) => [
+        member.resourceId,
+        member.exceptionId,
+        ...(member.completionResourceIds || [])
+      ]));
+      enqueue([
+        record.obligationId,
+        record.ruleId,
+        record.collectionReviewId,
+        record.supersedesId
+      ]);
+    }
+    if (record?.type === "attestation") enqueue([record.programId, record.reportingRouteId, record.reportingRouteSetId]);
+    if (record?.type === "reporting-route-set") {
+      enqueue([
+        ...(record.sourceResourceIds || []),
+        record.predecessorId,
+        record.approval?.approvalAppointmentId,
+        record.approval?.approvedById,
+        ...(record.approval?.evidenceIds || []),
+        record.cancellation?.authorityAppointmentId,
+        record.cancellation?.canceledById,
+        ...(record.cancellation?.evidenceIds || []),
+        ...(record.primaryLane?.dependencySystemIds || []),
+        ...(record.alternateLane?.dependencySystemIds || [])
+      ]);
+    }
+    if (record?.type === "appointment") enqueue([record.holderId]);
+    if (record?.type === "exception") enqueue([...(record.evidenceIds || []), ...(record.attestationIds || [])]);
     if (record?.type === "action-item") {
       enqueue([
         record.sourceResourceId,
@@ -557,6 +719,30 @@ function expandEvidenceWorkflowContext(selectedIds, byId) {
   }
 }
 
+function closeEvidenceSelection({ selectedIds, evidenceIds, records, scope, byId, start, end }) {
+  let previousSize = -1;
+  while (previousSize !== selectedIds.size + evidenceIds.size) {
+    previousSize = selectedIds.size + evidenceIds.size;
+    for (const evidence of records.filter((record) => record.type === "evidence")) {
+      if (scope && !recordRelevantToAudit(evidence, scope, byId)) continue;
+      const direct = selectedIds.has(evidence.id)
+        || (evidence.sourceResourceIds || []).some((id) => selectedIds.has(id))
+        || overlapsEvidencePeriod(evidence, start, end);
+      if (direct) evidenceIds.add(evidence.id);
+    }
+    for (const id of [...selectedIds]) {
+      const record = byId.get(id);
+      addIds(evidenceIds, record?.evidenceIds);
+      addIds(evidenceIds, record?.sampleEvidenceIds);
+      if (record?.sourceEvidenceId) evidenceIds.add(record.sourceEvidenceId);
+      if (record?.populationId) selectedIds.add(record.populationId);
+    }
+    addIds(selectedIds, evidenceIds);
+    expandEvidenceWorkflowContext(selectedIds, byId);
+    for (const id of selectedIds) if (byId.get(id)?.type === "evidence") evidenceIds.add(id);
+  }
+}
+
 export async function writeEvidencePacket(input, packet, options = {}) {
   const baseName = `${packet.period.start}-to-${packet.period.end}-${packet.revision.shortCommit || "uncommitted"}`;
   let outputOption = options.output || `.filegrc/evidence-packets/${baseName}`;
@@ -641,11 +827,16 @@ export async function writeEvidencePacket(input, packet, options = {}) {
         collectCommittedVersions(historicalFiles, item, content.path, content.history);
       }
     }
-    const historicalSources = getFilesAtRevisions(validation.loaded.root, historicalFiles);
-    for (let index = 0; index < historicalFiles.length; index += 1) {
+    const uniqueHistoricalFiles = historicalFiles.filter((file, index, all) => all.findIndex((candidate) => (
+      candidate.item.id === file.item.id
+      && candidate.history.commit === file.history.commit
+      && candidate.sourcePath === file.sourcePath
+    )) === index);
+    const historicalSources = getFilesAtRevisions(validation.loaded.root, uniqueHistoricalFiles);
+    for (let index = 0; index < uniqueHistoricalFiles.length; index += 1) {
       const source = historicalSources[index];
       if (source === null) continue;
-      const { item, sourcePath, history } = historicalFiles[index];
+      const { item, sourcePath, history } = uniqueHistoricalFiles[index];
       const exportedPath = join("history", item.type, item.id, history.commit, basename(sourcePath));
       await writePacketFile(output, exportedPath, source, files);
       historyIndex.push({
@@ -678,7 +869,13 @@ export function generateEvidencePacket(input, options = {}) {
 
 function collectCommittedVersions(target, item, sourcePath, history) {
   for (const revision of history || []) {
-    target.push({ item, sourcePath, relativePath: sourcePath, revision: revision.commit, history: revision });
+    target.push({
+      item,
+      sourcePath: revision.path || sourcePath,
+      relativePath: revision.path || sourcePath,
+      revision: revision.commit,
+      history: revision
+    });
   }
 }
 
@@ -1117,12 +1314,53 @@ function packetGaps({
   records,
   populations,
   model,
-  managementPreparation
+  managementPreparation,
+  reportingRouteCoverage
 }) {
   const gaps = [];
   if (!git.commit) gaps.push(gap("error", "uncommitted-workspace", "The workspace has no Git revision to bind this packet to."));
   else if (!git.clean) gaps.push(gap("error", "dirty-workspace", "Commit or discard workspace changes before treating this packet as audit evidence."));
 
+  for (const issue of reportingRouteCoverage?.issues || []) {
+    gaps.push(gap("error", issue.code, issue.message, issue.resourceId));
+  }
+  const routeAssessments = (reportingRouteCoverage?.snapshots || []).flatMap(({ routeSets }) => routeSets);
+  for (const assessment of [...new Map(routeAssessments.map((item) => [item.record.id, item])).values()]) {
+    const route = assessment.record;
+    if (assessment.approvalAssertionTiming === "git-recorded-later") {
+      gaps.push(gap(
+        "warning",
+        "non-contemporaneous-reporting-route-approval",
+        `${route.title} has a Git committer timestamp more than one day after the stated approval time. Committer timestamps are user-controlled metadata, so management and the engagement team must evaluate the linked fixed evidence itself.`,
+        route.id
+      ));
+    }
+    if (assessment.approvalAssertionTiming === "git-recorded-before-event") {
+      gaps.push(gap(
+        "warning",
+        "reporting-route-approval-recorded-before-event",
+        `${route.title} has a Git committer timestamp before its stated approval time. Committer timestamps are user-controlled metadata; review the linked fixed evidence before relying on this approval.`,
+        route.id
+      ));
+    }
+    if (assessment.cancellationAssertionTiming === "git-recorded-later") {
+      gaps.push(gap(
+        "warning",
+        "non-contemporaneous-reporting-route-cancellation",
+        `${route.title} has a Git committer timestamp more than one day after the stated cancellation time. Committer timestamps are user-controlled metadata; review the linked fixed evidence.`,
+        route.id
+      ));
+    }
+    if (assessment.cancellationAssertionTiming === "git-recorded-before-event") {
+      gaps.push(gap(
+        "warning",
+        "reporting-route-cancellation-recorded-before-event",
+        `${route.title} has a Git committer timestamp before its stated cancellation time. Committer timestamps are user-controlled metadata; review the linked fixed evidence before relying on this cancellation.`,
+        route.id
+      ));
+    }
+  }
+
   if (!audit) {
     gaps.push(gap("error", "missing-audit-scope", "Select an audit record before treating this packet as an auditor delivery."));
   } else {
@@ -1198,6 +1436,14 @@ function packetGaps({
       if (Number.isInteger(testRecord?.exceptionCount) && testRecord.exceptionCount < 0) {
         gaps.push(gap("error", "control-test-exception-count-invalid", `${coverage.code || coverage.title} records a negative exception count.`, test.id));
       }
+      if (test.populationStatus === "superseded") {
+        gaps.push(gap(
+          "error",
+          "superseded-test-population",
+          `${coverage.code || coverage.title} test ${test.id} used superseded population ${test.populationId}. Perform and review a replacement test against ${test.replacementPopulationId || "the corrected population"}.`,
+          test.id
+        ));
+      }
       const testFindings = records.filter((record) => record.type === "finding" && record.sourceResourceId === test.id);
       if ((testRecord?.exceptionCount > 0 || ["failed", "passed-with-exceptions"].includes(test.outcome)) && !testFindings.length) {
         gaps.push(gap("error", "control-test-finding-missing", `${coverage.code || coverage.title} records exceptions or failure without a linked finding.`, test.id));
@@ -1309,7 +1555,12 @@ function packetGaps({
 
   for (const item of obligations) {
     if (item.dueWindowEnd <= end && item.status !== "complete") {
-      gaps.push(gap("error", "missing-obligation-completion", `${item.title} has no linked completion in ${item.dueWindowStart} through ${item.dueWindowEnd}.`, item.obligationId));
+      gaps.push(gap(
+        "error",
+        "missing-obligation-completion",
+        `${item.title} is not reconciled for ${item.dueWindowStart} through ${item.dueWindowEnd} (${item.completedCount || 0} of ${item.expectedCount || 0} expected members passed).`,
+        item.occurrenceId || item.obligationId
+      ));
     }
   }
   for (const run of eventRuns) {
@@ -1336,6 +1587,20 @@ function packetGaps({
           `${run.title}: ${action.title} is marked ${action.recordedStatus} but has no linked ${action.expectedCompletionTypes.join(" or ")} completion record.`,
           action.actionItemId
         ));
+      } else if (action.timelinessStatus === "unknown") {
+        gaps.push(gap(
+          "error",
+          "event-completion-time-missing",
+          `${run.title}: ${action.title} has an hour-based deadline but its completion proof has no exact timestamp. Link proof with an RFC 3339 completion time or record and resolve a timeliness exception.`,
+          action.actionItemId
+        ));
+      } else if (action.lateCompletion) {
+        gaps.push(gap(
+          "error",
+          "late-event-completion",
+          `${run.title}: ${action.title} was completed after ${action.dueWindowEndAt || action.dueWindowEnd}. Record and resolve the timeliness exception.`,
+          action.actionItemId
+        ));
       } else if (action.dueWindowEnd && action.dueWindowEnd <= end && action.status !== "complete") {
         const cutoff = action.dueWindowEndAt || action.dueWindowEnd;
         gaps.push(gap("error", "incomplete-event-action", `${run.title}: ${action.title} was not completed by ${cutoff}.`, action.actionItemId));
@@ -1343,7 +1608,7 @@ function packetGaps({
     }
   }
   for (const item of evidence) {
-    if (item.artifactKind === "rendered-page" && !item.sourceCommit) {
+    if (item.sourceKind === "rendered-page" && !item.sourceCommit) {
       gaps.push(gap("error", "unbound-rendered-evidence", `${item.title} does not name the Git revision that was rendered.`, item.id));
     } else if (item.sourceCommit && !item.sourceCommitValid) {
       gaps.push(gap("error", "invalid-evidence-revision", `${item.title} names a source Git revision that is not available in this repository.`, item.id));
@@ -1385,7 +1650,7 @@ function packetGaps({
     if (item.externalReference && !item.filePaths.length) {
       gaps.push(gap("warning", "external-only-evidence", `${item.title} relies on an external reference and is not self-contained in the packet.`, item.id));
     }
-    if (item.artifactKind === "rendered-page") {
+    if (item.sourceKind === "rendered-page") {
       const captureComplete = item.capture
         && typeof item.capture.route === "string"
         && item.capture.route.trim()
@@ -1797,8 +2062,17 @@ function sourceSystemSummary(record, evidence, audit) {
 function testPopulationSummary(test, byId) {
   const population = byId.get(test.populationId);
   const evidence = byId.get(population?.sourceEvidenceId);
+  const replacement = population?.status === "superseded"
+    ? [...byId.values()].find((record) => (
+        record.type === "audit-population"
+        && record.supersedesId === population.id
+        && record.status !== "superseded"
+      ))
+    : null;
   return {
     populationId: test.populationId || null,
+    populationStatus: population?.status || null,
+    replacementPopulationId: replacement?.id || null,
     populationCount: evidence?.populationCount ?? null,
     populationEvidenceId: population?.sourceEvidenceId || null
   };
@@ -1806,15 +2080,16 @@ function testPopulationSummary(test, byId) {
 
 function populationGaps(gaps, audit, populations, byId, model) {
   const expected = model.auditReadiness?.populationTemplates || [];
+  const currentPopulations = populations.filter(({ status }) => status !== "superseded");
   for (const template of expected) {
-    const matching = populations.filter((population) => population.populationKind === template.kind);
+    const matching = currentPopulations.filter((population) => population.populationKind === template.kind);
     if (!matching.length) {
       gaps.push(gap("error", "missing-audit-population", `${audit.title} is missing the ${template.title} population.`, audit.id));
     } else if (matching.length > 1) {
       gaps.push(gap("error", "duplicate-audit-population", `${audit.title} has more than one ${template.title} population.`, audit.id));
     }
   }
-  for (const population of populations) {
+  for (const population of currentPopulations) {
     if (!coverageMatches(population.coverage, coverageStart(audit.coverage), coverageEnd(audit.coverage))) {
       gaps.push(gap("error", "population-period-mismatch", `${population.title} does not match the exact audit period.`, population.id));
     }
@@ -2053,6 +2328,13 @@ function addIds(target, values = []) {
   for (const value of values) if (value) target.add(value);
 }
 
+function governingReportingRouteSets(snapshot) {
+  const requiredPurposes = new Set(snapshot.requirements.map(({ purposeKey }) => purposeKey));
+  return snapshot.routeSets.filter(({ record, effective, canceled }) => (
+    effective && !canceled && requiredPurposes.has(record.purposeKey)
+  ));
+}
+
 function requireDate(value, label) {
   if (!parseCalendarDate(value)) throw new Error(`A valid ${label} is required.`);
   return value;