filegrc 0.16.10 → 0.16.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "filegrc",
-  "version": "0.16.10",
+  "version": "0.16.12",
   "description": "Zero-dependency Git-native GRC engine",
   "license": "MIT",
   "repository": {

package/src/applicability-scope.js

@@ -1,4 +1,10 @@
 import { CALCULATED_REVISION_FIELDS, CALCULATED_REVISION_MAP_FIELDS, calculateRevision, canonicalCalculatedRevision, revisionsMatch } from "./revisions.js";
+import { reviewCommitsChangingTypes, reviewHistoricalWorkspace, reviewHistoryCommits, reviewHistoryContext } from "./historical-workspace.js";
+
+const scopeSourceTypes = new Set([
+  "workspace", "program", "commitment", "control", "complementary-control",
+  "system", "framework", "component", "vendor", "policy", "requirement"
+]);
 
 const excludedResourceFields = new Set([
   "applicabilityReview",
@@ -22,13 +28,30 @@ const unorderedStringArrayFields = new Set([
 ]);
 
 export function applicabilityScopeRevision(record, program, resources, model, options = {}) {
-  const selectedSystemIds = new Set(program?.systemIds || []);
-  const selectedFrameworkIds = new Set(program?.frameworkIds || []);
-  const selectedControlIds = new Set(program?.controlIds || []);
-  const selectedComponents = resources.filter(({ type, status, systemUses }) => (
+  const scopedResource = ["commitment", "control", "complementary-control"].includes(record?.type)
+    && !options.legacyBroadScope && !options.legacyBroadCommitment;
+  const linkedRequirementIds = new Set(record?.requirementIds || []);
+  const linkedControlIds = record?.type === "control"
+    ? [record.id]
+    : record?.type === "complementary-control"
+      ? record.relatedControlIds || []
+      : record?.controlIds || [];
+  const selectedSystemIds = new Set((program?.systemIds || []).filter((id) => (
+    !scopedResource || !(record.systemIds || []).length || record.systemIds.includes(id)
+  )));
+  const selectedFrameworkIds = new Set((program?.frameworkIds || []).filter((id) => (
+    !scopedResource || !linkedRequirementIds.size || resources.some((candidate) => (
+      candidate.type === "requirement" && candidate.frameworkId === id && linkedRequirementIds.has(candidate.id)
+    ))
+  )));
+  const selectedControlIds = new Set((program?.controlIds || []).filter((id) => (
+    !scopedResource || !linkedControlIds.length || linkedControlIds.includes(id)
+  )));
+  const selectedComponents = resources.filter(({ type, status, systemUses, id }) => (
     type === "component"
     && status !== "retired"
     && (systemUses || []).some(({ systemId }) => selectedSystemIds.has(systemId))
+    && (!scopedResource || !(record.componentIds || []).length || record.componentIds.includes(id))
   ));
   const selectedVendorIds = new Set(selectedComponents.map(({ vendorId }) => vendorId).filter(Boolean));
   const selectedPolicyIds = new Set(resources
@@ -38,17 +61,24 @@ export function applicabilityScopeRevision(record, program, resources, model, op
   const facts = {
     modelVersion: model.modelVersion,
     program: {
-      ...pick(program || {}, [
+      ...pick(scopedResource ? {
+        ...program,
+        systemIds: [...selectedSystemIds],
+        frameworkIds: [...selectedFrameworkIds],
+        requirementIds: (program?.requirementIds || []).filter((id) => !linkedRequirementIds.size || linkedRequirementIds.has(id)),
+        controlIds: [...selectedControlIds]
+      } : program || {}, [
         "id",
         "assuranceGoal",
         "systemIds",
         "frameworkIds",
         "requirementIds",
         "controlIds",
-        "riskMethodology"
+        ...(record?.type === "commitment" && scopedResource ? [] : ["riskMethodology"])
       ], model),
       ...(record.type === "requirement" ? {} : {
         requirementApplicability: (program?.requirementApplicability || [])
+          .filter((review) => !scopedResource || !linkedRequirementIds.size || linkedRequirementIds.has(review.requirementId))
           .map((review) => pick(review, ["requirementId", "decision"], model, "program-applicability"))
           .sort((left, right) => left.requirementId.localeCompare(right.requirementId))
       })
@@ -134,14 +164,19 @@ export function applicabilityScopeRevision(record, program, resources, model, op
           ], model)
         : pick(policy, ["id", "requirementIds"], model)),
     requirements: resources
-      .filter(({ type, frameworkId }) => type === "requirement" && selectedFrameworkIds.has(frameworkId))
+      .filter(({ type, frameworkId, id }) => type === "requirement" && selectedFrameworkIds.has(frameworkId)
+        && (!scopedResource || !linkedRequirementIds.size || linkedRequirementIds.has(id)))
       .sort(compareRecordIds)
       .map((requirement) => pick(requirement, ["id", "frameworkId", "reference", "description", "parentRequirementId"], model)),
     commitments: resources
-      .filter(({ type, status, systemIds }) => (
+      .filter(({ type, status, systemIds, controlIds, id }) => (
         type === "commitment"
         && !["retired", "superseded"].includes(status)
         && (systemIds || []).some((id) => selectedSystemIds.has(id))
+        && (!scopedResource
+          || record.type === "commitment" && id === record.id
+          || record.type === "control" && (controlIds || []).includes(record.id)
+          || record.type === "complementary-control" && (controlIds || []).some((controlId) => selectedControlIds.has(controlId)))
       ))
       .sort(compareRecordIds)
       .map((commitment) => pick(commitment, [
@@ -161,7 +196,7 @@ function compareRecordIds(left, right) {
   return left.id.localeCompare(right.id);
 }
 
-export function applicabilityReviewIsCurrent(review, record, program, resources, model) {
+export function applicabilityReviewIsCurrent(review, record, program, resources, model, root = null) {
   if (
     review?.scopeRevision
     && !review.scopeRevision.startsWith("scope:")
@@ -171,6 +206,12 @@ export function applicabilityReviewIsCurrent(review, record, program, resources,
   if (!review?.scopeRevision) return false;
   const matches = (revision) => revisionsMatch("applicability-scope", review.scopeRevision, revision);
   if (matches(applicabilityScopeRevision(record, program, resources, model))) return true;
+  if (["commitment", "control", "complementary-control"].includes(record?.type) && matches(applicabilityScopeRevision(
+    record, program, resources, model, { legacyBroadScope: true }
+  ))) return true;
+  if (["commitment", "control", "complementary-control"].includes(record?.type) && root && historicalScopedReviewMatches(
+    review.scopeRevision, record, program, resources, model, root
+  )) return true;
   // Older reviews hashed Policy approval metadata alongside scope facts.
   // Reconstruct each Policy independently because other Policies may already
   // have been approved when one Policy changes. Material fields stay current.
@@ -204,6 +245,31 @@ export function applicabilityReviewIsCurrent(review, record, program, resources,
   return false;
 }
 
+function historicalScopedReviewMatches(stored, record, program, resources, model, root) {
+  const current = applicabilityScopeRevision(record, program, resources, model);
+  const context = reviewHistoryContext(root, resources);
+  const { index } = context;
+  const commits = index?.available
+    ? reviewCommitsChangingTypes(index, scopeSourceTypes)
+    : reviewHistoryCommits(context);
+  for (const commit of [...commits].reverse()) {
+    const snapshot = reviewHistoricalWorkspace(context, commit);
+    if (!snapshot) continue;
+    const historicalResources = snapshot.resources;
+    const historicalRecord = historicalResources.find(({ id }) => id === record.id);
+    const historicalProgram = historicalResources.find(({ id }) => id === program?.id);
+    if (!historicalRecord || !historicalProgram) continue;
+    const historicalModel = snapshot.model;
+    if (!revisionsMatch("applicability-scope", current, applicabilityScopeRevision(
+      historicalRecord, historicalProgram, historicalResources, historicalModel
+    ))) continue;
+    if (revisionsMatch("applicability-scope", stored, applicabilityScopeRevision(
+      historicalRecord, historicalProgram, historicalResources, historicalModel, { legacyBroadScope: true }
+    ))) return true;
+  }
+  return false;
+}
+
 function legacyPolicyAlternatives(policy) {
   const prior = {
     active: ["approved", "in-review", "draft"],

package/src/audit-preparation.js

@@ -373,7 +373,7 @@ function scopeStage(loaded, audit, records, byId, programReadiness) {
   const v4Decisions = new Map((program?.requirementApplicability || [])
     .filter((decision) => (
       requirementById.has(decision.requirementId)
-      && applicabilityReviewIsCurrent(decision, requirementById.get(decision.requirementId), program, records, loaded.model)
+      && applicabilityReviewIsCurrent(decision, requirementById.get(decision.requirementId), program, records, loaded.model, loaded.root)
     ))
     .map((decision) => [decision.requirementId, decision]));
   const unresolvedRequirements = frameworkRequirementIds

package/src/batch-review.js

@@ -37,7 +37,7 @@ export async function scaffoldApplicabilityReview(input = process.cwd(), options
     .filter((review) => (
       ["applicable", "not-applicable"].includes(review.decision)
       && requirementById.has(review.requirementId)
-      && applicabilityReviewIsCurrent(review, requirementById.get(review.requirementId), program, loaded.resources, loaded.model)
+      && applicabilityReviewIsCurrent(review, requirementById.get(review.requirementId), program, loaded.resources, loaded.model, loaded.root)
     ))
     .map(({ requirementId }) => requirementId));
   const requirementReviews = new Map((program.requirementApplicability || [])
@@ -47,7 +47,7 @@ export async function scaffoldApplicabilityReview(input = process.cwd(), options
     && (!requestedType || record.type === requestedType)
     && (record.type === "requirement" && modelSupports(loaded.model, "program-scope")
       ? !reviewedRequirementIds.has(record.id)
-      : !applicabilityReviewIsCurrent(record.applicabilityReview, record, program, loaded.resources, loaded.model))
+      : !applicabilityReviewIsCurrent(record.applicabilityReview, record, program, loaded.resources, loaded.model, loaded.root))
     && !["retired", "superseded"].includes(record.status)
   ));
   return {

package/src/collection-revision.js

@@ -7,6 +7,8 @@ import {
   collectionScopeRevisionFacts
 } from "./collection-scope.js";
 import { resolveDataPath } from "./paths.js";
+import { getFileAtRevision } from "./git.js";
+import { reviewHistoricalWorkspace, reviewHistoryCommits, reviewHistoryContext } from "./historical-workspace.js";
 import { resolveProgram } from "./program.js";
 import { markdownEntries } from "./resource-markdown.js";
 import { CALCULATED_REVISION_FIELDS, CALCULATED_REVISION_MAP_FIELDS, calculateRevision, canonicalCalculatedRevision, revisionsMatch } from "./revisions.js";
@@ -39,6 +41,36 @@ export function collectionRevisionMatches(loaded, resourceType, storedRevision,
       }
     }
   }
+  return historicallyEquivalentCollection(loaded, resourceType, storedRevision, options, currentRevision);
+}
+
+function historicallyEquivalentCollection(loaded, resourceType, stored, options, current) {
+  if (!loaded.root) return false;
+  const context = reviewHistoryContext(loaded.root, loaded);
+  for (const commit of [...reviewHistoryCommits(context)].reverse()) {
+    const snapshot = reviewHistoricalWorkspace(context, commit);
+    if (!snapshot) continue;
+    const historicalOptions = {
+      ...options,
+      programId: options.programId || options.program?.id,
+      historicalCommit: commit
+    };
+    delete historicalOptions.program;
+    delete historicalOptions.currentRevision;
+    // Require the complete reviewed basis to be unchanged under the current
+    // semantic calculation before accepting an older byte-sensitive digest.
+    if (!revisionsMatch("collection", current, collectionRevision(snapshot, resourceType, historicalOptions))) continue;
+    for (const legacy of [false, true]) {
+      for (const scopeHashInput of ["legacy", "digest"]) {
+        for (const scopeFactsInput of ["legacy", "source"]) {
+          if (revisionsMatch("collection", stored, calculateCollectionRevision(
+            snapshot, resourceType, { ...historicalOptions, historicalReviewMetadata: true },
+            legacy, scopeHashInput, scopeFactsInput
+          ))) return true;
+        }
+      }
+    }
+  }
   return false;
 }
 
@@ -51,7 +83,7 @@ function calculateCollectionRevision(loaded, resourceType, options, legacy, scop
     : Object.hasOwn(options, "program")
     ? options.program
     : resolveProgram(loaded, options.programId);
-  const inputs = new Map(collectionRevisionInputs(loaded, resourceType, program, { legacy })
+  const inputs = new Map(collectionRevisionInputs(loaded, resourceType, program, { legacy, historicalReviewMetadata: options.historicalReviewMetadata })
     .map((input) => [input.record.id, input]));
   const authoritativeSource = loaded.resources.find(({ id }) => id === options.authoritativeSourceId);
   if (authoritativeSource) {
@@ -71,7 +103,12 @@ function calculateCollectionRevision(loaded, resourceType, options, legacy, scop
         .digest("hex"),
       contentRevisions: (legacy || includeContent ? markdownEntries(loaded.model, record) : []).flatMap(({ path }) => {
         try {
-          const content = readFileSync(resolveDataPath(loaded.root, path), "utf8");
+          const content = options.historicalCommit
+            ? loaded.historicalFiles
+              ? loaded.historicalFiles.get(`data/${path}`) ?? null
+              : getFileAtRevision(loaded.root, options.historicalCommit, `data/${path}`)
+            : readFileSync(resolveDataPath(loaded.root, path), "utf8");
+          if (content === null) return [];
           return [{ path, revision: createHash("sha256").update(content).digest("hex") }];
         } catch (error) {
           if (error.code === "ENOENT") return [];
@@ -80,7 +117,9 @@ function calculateCollectionRevision(loaded, resourceType, options, legacy, scop
       })
     }))
     .sort((left, right) => left.id.localeCompare(right.id));
-  const scopeFacts = collectionScopeRevisionFacts(loaded, resourceType, program);
+  const scopeFacts = collectionScopeRevisionFacts(loaded, resourceType, program, {
+    historicalReviewMetadata: options.historicalReviewMetadata
+  });
   const workspaceScope = scopeFactsInput === "source" ? scopeFacts : canonicalScopeFacts(scopeFacts);
   const source = JSON.stringify({ resourceType, records, workspaceScope });
   return legacy

package/src/collection-scope.js

@@ -360,23 +360,26 @@ export function collectionRevisionInputs(loaded, resourceType, program, options
     record,
     value: reviewedIds.has(record.id)
       ? resourceType === "retention-schedule-item" && modelSupports(loaded.model, "retention-schedule-approval")
-        ? retentionScheduleRowProposalValue(record)
-        : record
+        ? retentionScheduleRowProposalValue(record, options.historicalReviewMetadata)
+        : options.historicalReviewMetadata ? record : substantiveRevisionValue(record)
       : resourceType === "retention-schedule-item"
         && modelSupports(loaded.model, "retention-schedule-approval")
         && record.type === "document"
           ? retentionScheduleDocumentProposalValue(record)
-          : dependencyRevisionValue(resourceType, record, legacy),
+          : options.historicalReviewMetadata
+            ? dependencyRevisionValue(resourceType, record, legacy)
+            : substantiveRevisionValue(dependencyRevisionValue(resourceType, record, legacy)),
     includeContent: legacy
       || reviewedIds.has(record.id)
       || dependencyContentAffectsRevision(resourceType, record.type)
   }));
 }
 
-function retentionScheduleRowProposalValue(record) {
+function retentionScheduleRowProposalValue(record, historicalReviewMetadata = false) {
   return Object.fromEntries(Object.entries(record).filter(([field]) => ![
     "approvedByIds",
-    "approvedOn"
+    "approvedOn",
+    ...(historicalReviewMetadata ? [] : ["reviewedSourceRevisions"])
   ].includes(field)));
 }
 
@@ -396,7 +399,7 @@ function retentionScheduleDocumentProposalValue(record) {
   ].includes(field)));
 }
 
-export function collectionScopeRevisionFacts(loaded, resourceType, program) {
+export function collectionScopeRevisionFacts(loaded, resourceType, program, options = {}) {
   if (!modelSupports(loaded.model, "program-scope")) {
     const common = { programId: program?.id ?? null };
     if (resourceType === "framework") {
@@ -426,7 +429,7 @@ export function collectionScopeRevisionFacts(loaded, resourceType, program) {
       programs: programs.map((record) => ({
         id: record.id,
         systemIds: sorted(record.systemIds),
-        controlIds: sorted(record.controlIds)
+        ...(options.historicalReviewMetadata ? { controlIds: sorted(record.controlIds) } : {})
       }))
     };
   }
@@ -454,7 +457,11 @@ export function collectionScopeRevisionFacts(loaded, resourceType, program) {
       assuranceGoal: program?.assuranceGoal ?? null,
       frameworkIds: sorted(program?.frameworkIds),
       requirementIds: sorted(selectedRequirementIds(program || {}, loaded.model)),
-      requirementApplicability: program?.requirementApplicability || [],
+      requirementApplicability: options.historicalReviewMetadata
+        ? program?.requirementApplicability || []
+        : (program?.requirementApplicability || [])
+            .map(({ requirementId, decision }) => ({ requirementId, decision }))
+            .sort((left, right) => left.requirementId.localeCompare(right.requirementId)),
       riskMethodology: program?.riskMethodology || null
     } : scope;
   }
@@ -462,9 +469,33 @@ export function collectionScopeRevisionFacts(loaded, resourceType, program) {
 }
 
 export function authoritativeSourceRevisionValue(record) {
-  return Object.fromEntries(Object.entries(record).filter(([field]) => (
+  return substantiveRevisionValue(Object.fromEntries(Object.entries(record).filter(([field]) => (
     !authoritativeSourceBookkeepingFields.has(field)
-  )));
+  ))));
+}
+
+function substantiveRevisionValue(record) {
+  if (!record) return record;
+  const value = { ...record };
+  if (value.type === "retention-schedule-item") {
+    delete value.approvedByIds;
+    delete value.approvedOn;
+    delete value.reviewedSourceRevisions;
+  }
+  if (value.type === "program" && value.requirementApplicability) {
+    value.requirementApplicability = value.requirementApplicability
+      .map(({ requirementId, decision }) => ({ requirementId, decision }))
+      .sort((left, right) => left.requirementId.localeCompare(right.requirementId));
+  }
+  if (value.applicabilityReview) value.applicabilityReview = { decision: value.applicabilityReview.decision };
+  if (["policy", "document", "training"].includes(value.type)) {
+    for (const field of [
+      "approverIds", "approvedOn", "activationBasis", "activatedByIds",
+      "activatedOn", "activatedContentRevisions", "statusTransition"
+    ]) delete value[field];
+    if (["approved", "active"].includes(value.status)) value.status = "approved";
+  }
+  return value;
 }
 
 const authoritativeSourceBookkeepingFields = new Set([

package/src/historical-workspace.js

@@ -0,0 +1,131 @@
+import { loadModel } from "../model/index.js";
+import { getDataCommitHistory, getDataFilesAtRevision, getDataRecordHistoryIndex, getFileAtRevision } from "./git.js";
+import { performance } from "node:perf_hooks";
+
+const reviewContexts = new WeakMap();
+
+export function reviewHistoryContext(root, owner) {
+  const key = owner.resources || owner;
+  let context = reviewContexts.get(key);
+  if (context) return context;
+  let index = null;
+  try {
+    // Leave time for the original Git recovery path if this larger index
+    // cannot be built within a browser request.
+    index = getDataRecordHistoryIndex(root, { deadline: performance.now() + 3_000 });
+  } catch (error) {
+    if (error.code !== "FILEGRC_HISTORY_DEADLINE") throw error;
+  }
+  context = { root, index, statesByCommit: new Map(), workspacesByCommit: new Map() };
+  reviewContexts.set(key, context);
+  return context;
+}
+
+export function reviewHistoryCommits(context) {
+  if (context.index?.available) return context.index.commits;
+  context.fallbackCommits ||= getDataCommitHistory(context.root);
+  return context.fallbackCommits;
+}
+
+export function reviewCommitsChangingTypes(index, types) {
+  const paths = new Set();
+  for (const records of index.recordsByCommit.values()) {
+    for (const { record, path } of records.values()) {
+      if (types.has(record.type)) paths.add(path);
+    }
+  }
+  return index.commits.filter((commit) => [...(index.fileChangesByCommit.get(commit)?.keys() || [])]
+    .some((path) => paths.has(path)));
+}
+
+export function reviewHistoricalWorkspace(context, commit) {
+  if (context.index?.available) return indexedHistoricalWorkspace(context, commit);
+  if (context.workspacesByCommit.has(commit)) return context.workspacesByCommit.get(commit);
+  const loaded = historicalWorkspace(context.root, commit);
+  context.workspacesByCommit.set(commit, loaded);
+  if (context.workspacesByCommit.size > 128) context.workspacesByCommit.delete(context.workspacesByCommit.keys().next().value);
+  return loaded;
+}
+
+// Preserve recovery beyond the reconciliation index's size and build limits.
+// It is slower, but still requires the same substantive comparison.
+function historicalWorkspace(root, commit) {
+  const entries = [];
+  for (const path of getDataFilesAtRevision(root, commit).filter(authoritativeJsonPath)) {
+    const source = getFileAtRevision(root, commit, path);
+    if (!source) return null;
+    try {
+      entries.push({ record: JSON.parse(source), source, relativePath: path.slice("data/".length) });
+    } catch {
+      return null;
+    }
+  }
+  const resources = entries.map(({ record }) => record);
+  const workspace = resources.find(({ type }) => type === "workspace");
+  if (!workspace) return null;
+  try {
+    return { root, entries, resources, workspace, model: loadModel(workspace.dataModelVersion) };
+  } catch {
+    return null;
+  }
+}
+
+// The history index already contains every committed JSON and Markdown source.
+// Materialize its first-parent states once instead of asking Git to list and
+// read the entire workspace for every legacy review binding.
+export function indexedHistoricalWorkspace(context, commit) {
+  const { root, index } = context;
+  if (!index?.available || !index.parentsByCommit.has(commit)) return null;
+  // Reuse a full request-sized history for ordinary workspaces while bounding
+  // retained maps when a repository contains many thousands of data files.
+  const cacheLimit = Math.max(1, Math.min(512, Math.floor(200_000 / Math.max(1, index.historicalRecordPaths.size))));
+  if (context.workspacesByCommit.has(commit)) return context.workspacesByCommit.get(commit);
+  let state = context.statesByCommit.get(commit);
+  if (!state) {
+    const lineage = [];
+    let cursor = commit;
+    while (cursor && !context.statesByCommit.has(cursor)) {
+      lineage.push(cursor);
+      cursor = index.parentsByCommit.get(cursor)?.[0] || null;
+    }
+    state = cursor ? context.statesByCommit.get(cursor) : new Map();
+    for (let position = lineage.length - 1; position >= 0; position -= 1) {
+      const changedAt = lineage[position];
+      const next = new Map(state);
+      for (const [path, source] of index.fileChangesByCommit.get(changedAt) || []) {
+        if (source === null) next.delete(path);
+        else next.set(path, source);
+      }
+      context.statesByCommit.set(changedAt, next);
+      if (context.statesByCommit.size > cacheLimit) context.statesByCommit.delete(context.statesByCommit.keys().next().value);
+      state = next;
+    }
+  }
+  const entries = [];
+  for (const [path, source] of state) {
+    if (!authoritativeJsonPath(path)) continue;
+    try {
+      entries.push({ record: JSON.parse(source), source, relativePath: path.slice("data/".length) });
+    } catch {
+      return null;
+    }
+  }
+  const resources = entries.map(({ record }) => record);
+  const workspace = resources.find(({ type }) => type === "workspace");
+  if (!workspace) return null;
+  try {
+    const loaded = { root, entries, resources, workspace, model: loadModel(workspace.dataModelVersion), historicalFiles: state };
+    context.workspacesByCommit.set(commit, loaded);
+    if (context.workspacesByCommit.size > cacheLimit) context.workspacesByCommit.delete(context.workspacesByCommit.keys().next().value);
+    return loaded;
+  } catch {
+    return null;
+  }
+}
+
+function authoritativeJsonPath(path) {
+  const parts = path.split("/");
+  if (parts[0] !== "data" || !path.endsWith(".json")) return false;
+  if (parts.slice(1).some((part) => part.startsWith(".") || part === "content")) return false;
+  return !(parts[1] === "evidence" && parts.length > 3 && parts.at(-1) !== "evidence.json");
+}

package/src/program-readiness.js

@@ -155,7 +155,7 @@ export async function assessProgramReadiness(input, options = {}) {
   };
 
   const policyStage = await policiesStage(scope, records, byId, readMarkdown, loaded.model);
-  const controlStage = await controlsStage(scope, byId, readMarkdown, asOf, loaded.model);
+  const controlStage = await controlsStage(scope, byId, readMarkdown, asOf, loaded.model, loaded.root);
   controlStage.items.unshift(...collectionReviews
     .filter(({ resourceType }) => resourceType === "complementary-control")
     .map(collectionReviewReadinessItem));
@@ -218,7 +218,8 @@ export async function assessProgramReadiness(input, options = {}) {
       byId,
       loaded.model,
       collectionReviews.filter(({ resourceType }) => ["person", "framework", "system", "component", "vendor", "classification", "information-type"].includes(resourceType)),
-      workspace?.timezone || "UTC"
+      workspace?.timezone || "UTC",
+      loaded.root
     );
   if (modelSupports(loaded.model, "reporting-route-sets")) {
     const routeSets = await assessReportingRouteSets(loaded, {
@@ -373,7 +374,7 @@ function programScope(program, records, byId, model, loaded) {
   };
 }
 
-function scopeStage(workspace, scope, records, byId, model, collectionReviews = [], timezone = "UTC") {
+function scopeStage(workspace, scope, records, byId, model, collectionReviews = [], timezone = "UTC", root = null) {
   const items = [];
   const goal = workspace?.assuranceGoal || "none";
   items.push(item(
@@ -459,7 +460,7 @@ function scopeStage(workspace, scope, records, byId, model, collectionReviews =
       && record.effectiveOn
       && (!model.resources.commitment?.fields?.applicabilityReview || (
         record.applicabilityReview?.decision === "applicable"
-        && applicabilityReviewIsCurrent(record.applicabilityReview, record, workspace, records, model)
+        && applicabilityReviewIsCurrent(record.applicabilityReview, record, workspace, records, model, root)
       ))
       && currentPartyPeople(record.ownerIds, byId).size > 0
       && (record.requirementIds || []).length > 0
@@ -496,7 +497,7 @@ function scopeStage(workspace, scope, records, byId, model, collectionReviews =
   const reviewedRequirements = (workspace?.requirementApplicability || [])
     .filter((decision) => (
       requirementById.has(decision.requirementId)
-      && applicabilityReviewIsCurrent(decision, requirementById.get(decision.requirementId), workspace, records, model)
+      && applicabilityReviewIsCurrent(decision, requirementById.get(decision.requirementId), workspace, records, model, root)
     ));
   const v4Decisions = new Map(reviewedRequirements.map((decision) => [decision.requirementId, decision.decision]));
   const staleRequirementIds = new Set((workspace?.requirementApplicability || [])
@@ -1617,7 +1618,7 @@ function legacyPolicyLibraryProposals(records) {
   }];
 }
 
-async function controlsStage(scope, byId, readMarkdown, asOf, model) {
+async function controlsStage(scope, byId, readMarkdown, asOf, model, root = null) {
   const items = [];
   const families = selectedControlFamilies(scope.controls, model);
   if (!scope.controls.length) {
@@ -1651,7 +1652,7 @@ async function controlsStage(scope, byId, readMarkdown, asOf, model) {
     const checks = {
       ...(model.resources.control?.fields?.applicabilityReview ? {
         applicability: control.applicabilityReview?.decision === "applicable"
-          && applicabilityReviewIsCurrent(control.applicabilityReview, control, scope.program, [...byId.values()], model)
+          && applicabilityReviewIsCurrent(control.applicabilityReview, control, scope.program, [...byId.values()], model, root)
       } : {}),
       implemented: control.status === "implemented",
       owner: (control.ownerIds || []).length > 0,

package/src/retention.js

@@ -6,6 +6,8 @@ import { programComponents } from "./program.js";
 import { markdownEntries } from "./resource-markdown.js";
 import { modelSupports } from "../model/index.js";
 import { canonicalCalculatedRevisionJson, revisionDigest, revisionsMatch } from "./revisions.js";
+import { getFileAtRevision } from "./git.js";
+import { reviewHistoricalWorkspace, reviewHistoryCommits, reviewHistoryContext } from "./historical-workspace.js";
 
 export async function assessRetentionReadiness(loaded, program, options = {}) {
   if (!loaded.model.resources["retention-schedule-item"]) return [];
@@ -187,7 +189,7 @@ export async function resourceReviewRevisions(loaded, ids, scopeHashInput = "leg
   return new Map([...revisions].filter(([id]) => wanted.has(id)));
 }
 
-export function resourceReviewRevisionsSync(loaded, ids, scopeHashInput = "legacy") {
+export function resourceReviewRevisionsSync(loaded, ids, scopeHashInput = "legacy", legacySource = false, historicalCommit = null) {
   const wanted = new Set(ids);
   const entries = new Map(loaded.entries.map((entry) => [entry.record.id, entry]));
   const revisions = new Map();
@@ -197,10 +199,15 @@ export function resourceReviewRevisionsSync(loaded, ids, scopeHashInput = "legac
     const entry = entries.get(id);
     if (!entry || reviewing.has(id)) return null;
     reviewing.add(id);
-    const parts = [reviewSource(loaded, entry, scopeHashInput)];
+    const parts = [reviewSource(loaded, entry, scopeHashInput, legacySource)];
     for (const markdown of markdownEntries(loaded.model, entry.record)) {
       try {
-        parts.push(readFileSync(resolveDataPath(loaded.root, markdown.path), "utf8"));
+        const source = historicalCommit
+          ? loaded.historicalFiles
+            ? loaded.historicalFiles.get(`data/${markdown.path}`) ?? null
+            : getFileAtRevision(loaded.root, historicalCommit, `data/${markdown.path}`)
+          : readFileSync(resolveDataPath(loaded.root, markdown.path), "utf8");
+        if (source !== null) parts.push(source);
       } catch (error) {
         if (error.code !== "ENOENT") throw error;
       }
@@ -222,10 +229,47 @@ export function resourceReviewRevisionMatches(loaded, revisions, id, stored) {
   const current = revisions.get(id);
   if (!current || !revisionDigest("content", stored)) return false;
   if (revisionsMatch("content", stored, current)) return true;
+  const legacy = resourceReviewRevisionsSync(loaded, [id], "legacy", true).get(id);
+  if (revisionsMatch("content", stored, legacy)) return true;
   // Version 0.16.0 used a bare digest as the hash input for scopeRevision.
   // Read that binding without changing the legacy scope: basis restored here.
-  const compatible = resourceReviewRevisionsSync(loaded, [id], "digest").get(id);
-  return revisionsMatch("content", stored, compatible);
+  const compatible = resourceReviewRevisionsSync(loaded, [id], "digest", true).get(id);
+  if (revisionsMatch("content", stored, compatible)) return true;
+  return historicallyEquivalentReviewSource(loaded, id, stored, current);
+}
+
+// Recompute the old byte-sensitive binding at each committed state. The
+// semantic source graph must still equal today's graph, including linked
+// records and Markdown, before the old approval is treated as current.
+function historicallyEquivalentReviewSource(loaded, id, stored, current) {
+  if (!loaded.root) return false;
+  const context = reviewHistoryContext(loaded.root, loaded);
+  const { index } = context;
+  const relevantPaths = index?.available ? new Set(["data/workspace.json"]) : null;
+  const graphIds = new Set();
+  const visit = (resourceId) => {
+    if (graphIds.has(resourceId)) return;
+    graphIds.add(resourceId);
+    const entry = loaded.entries.find(({ record }) => record.id === resourceId);
+    if (!entry) return;
+    for (const path of (index.historiesById.get(resourceId) || []).map(({ path }) => path)) relevantPaths.add(path);
+    for (const markdown of markdownEntries(loaded.model, entry.record)) relevantPaths.add(`data/${markdown.path}`);
+    for (const sourceId of entry.record.sourceResourceIds || []) visit(sourceId);
+  };
+  if (relevantPaths) visit(id);
+  for (const commit of [...reviewHistoryCommits(context)].reverse()) {
+    const changed = index?.available ? index.fileChangesByCommit.get(commit) : null;
+    if (relevantPaths && ![...changed.keys()].some((path) => relevantPaths.has(path) || path.endsWith(".md"))) continue;
+    const snapshot = reviewHistoricalWorkspace(context, commit);
+    if (!snapshot?.entries.some(({ record }) => record.id === id)) continue;
+    const semantic = resourceReviewRevisionsSync(snapshot, [id], "legacy", false, commit).get(id);
+    if (!revisionsMatch("content", semantic, current)) continue;
+    for (const scopeHashInput of ["legacy", "digest"]) {
+      const legacy = resourceReviewRevisionsSync(snapshot, [id], scopeHashInput, true, commit).get(id);
+      if (revisionsMatch("content", stored, legacy)) return true;
+    }
+  }
+  return false;
 }
 
 export function retentionUses(loaded, program) {
@@ -249,7 +293,7 @@ export function retentionUses(loaded, program) {
   return [...new Map(uses.map((use) => [`${use.resource.id}:${use.informationTypeId}`, use])).values()];
 }
 
-function reviewSource(loaded, entry, scopeHashInput = "legacy") {
+function reviewSource(loaded, entry, scopeHashInput = "legacy", legacySource = false) {
   if (
     modelSupports(loaded.model, "retention-schedule-approval")
     && entry.record.type === "document"
@@ -271,7 +315,34 @@ function reviewSource(loaded, entry, scopeHashInput = "legacy") {
     ]) delete approved[field];
     return JSON.stringify(approved);
   }
-  return canonicalCalculatedRevisionJson(entry.source, scopeHashInput);
+  return legacySource
+    ? canonicalCalculatedRevisionJson(entry.source, scopeHashInput)
+    : canonicalCalculatedRevisionJson(JSON.stringify(substantiveReviewSource(JSON.parse(entry.source))), scopeHashInput);
+}
+
+function substantiveReviewSource(record) {
+  const source = record.type === "program" ? {
+    id: record.id,
+    type: record.type,
+    status: record.status,
+    assuranceGoal: record.assuranceGoal,
+    systemIds: [...(record.systemIds || [])].sort(),
+    extensions: record.extensions,
+    requirementApplicability: (record.requirementApplicability || [])
+      .map(({ requirementId, decision }) => ({ requirementId, decision }))
+      .sort((left, right) => left.requirementId.localeCompare(right.requirementId))
+  } : { ...record };
+  if (source.applicabilityReview) {
+    source.applicabilityReview = { decision: source.applicabilityReview.decision };
+  }
+  if (["policy", "document", "training"].includes(source.type)) {
+    for (const field of [
+      "approverIds", "approvedOn", "activationBasis", "activatedByIds",
+      "activatedOn", "activatedContentRevisions", "statusTransition"
+    ]) delete source[field];
+    if (["approved", "active"].includes(source.status)) source.status = "approved";
+  }
+  return source;
 }
 
 export function nearDuplicateInformationTypes(records) {

package/src/state.js

@@ -351,7 +351,7 @@ function assessApplicabilityReviewStatuses(loaded, program) {
         : record.applicabilityReview;
       return [record.id, !review || !["applicable", "not-applicable", "externally-managed", "zero-population"].includes(review.decision)
         ? "missing" : applicabilityReviewIsCurrent(
-        review, record, program, loaded.resources, loaded.model
+        review, record, program, loaded.resources, loaded.model, loaded.root
       ) ? "current" : "stale"];
     }));
 }

package/src/workflow.js

@@ -397,7 +397,7 @@ function recordFinalizationFindings(loaded, program) {
     if (incomplete) {
       findings.push(finalizationFinding(record, incomplete, loaded.model));
     }
-    for (const missing of finalizationFields(record, loaded.model, loaded.resources, program)) {
+    for (const missing of finalizationFields(record, loaded.model, loaded.resources, program, loaded.root)) {
       findings.push(fieldFinding(record, missing, loaded.model));
     }
   }
@@ -532,11 +532,11 @@ function recordFinalizationRequiredness(record, loaded, program) {
   return "conditional";
 }
 
-function finalizationFields(record, model, resources, program) {
+function finalizationFields(record, model, resources, program, root) {
   const fields = [];
   const needsReview = ["requirement", "commitment", "complementary-control", "control"].includes(record.type)
     && model.resources[record.type]?.fields?.applicabilityReview
-    && !applicabilityReviewIsCurrent(record.applicabilityReview, record, program, resources, model);
+    && !applicabilityReviewIsCurrent(record.applicabilityReview, record, program, resources, model, root);
   if (needsReview) {
     const currentRevision = applicabilityScopeRevision(record, program, resources, model);
     fields.push({