filegrc 0.7.1 → 0.9.0

package/src/evidence-packet.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { copyFile, mkdir, readFile, readdir, readlink, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { modelSupports } from "../model/index.js";
 import { assessAuditPreparation } from "./audit-preparation.js";
 import {
   coverageContains,
@@ -10,9 +11,9 @@ import {
   coverageOverlaps,
   coverageStart
 } from "./coverage.js";
-import { getFileAtRevision, getGitSummary, getWorkspaceHistories, hasGitRevision } from "./git.js";
+import { getFilesAtRevisions, getGitSummary, getWorkspaceHistories, getWorkspaceRevisionSnapshot, hasGitRevision } from "./git.js";
 import { planObligations } from "./obligations.js";
-import { isWithin, resolveDataPath, resolveWorkspacePath } from "./paths.js";
+import { isWithin, resolveDataPath, resolveWorkspacePath, resolveWorkspaceRoot } from "./paths.js";
 import { parseCalendarDate } from "./recurrence.js";
 import { markdownEntries } from "./resource-markdown.js";
 import { serializeWorkspaceMutation } from "./mutation.js";
@@ -27,6 +28,9 @@ import {
   subsequentEventsReviewIssue
 } from "./soc2.js";
 import { validateWorkspace } from "./validate.js";
+import { measureTiming } from "./timing.js";
+
+const preparedPacketValidations = new WeakMap();
 
 const NON_EVIDENCE_RECORD_TYPES = new Set([
   "appointment",
@@ -110,6 +114,7 @@ export async function prepareEvidencePacket(input, options = {}) {
       ...(audit.complementaryControlIds || []),
       ...auditSubserviceVendorIds(audit),
       ...auditSubserviceComponentIds(audit),
+      audit.engagementTermsDocumentId,
       audit.systemDescriptionDocumentId,
       audit.managementAssertionDocumentId,
       audit.managementRepresentationDocumentId,
@@ -228,7 +233,7 @@ export async function prepareEvidencePacket(input, options = {}) {
     return sourceRevisionValidity.get(revision);
   };
   const evidence = [...evidenceIds].map((id) => evidenceSummary(byId.get(id), byId, revisionIsValid)).filter(Boolean).sort(byTitle);
-  const v4 = String(loaded.model.modelVersion) === "4";
+  const v4 = modelSupports(loaded.model, "component-sources");
   const sourceSystemIds = new Set([
     ...(v4
       ? [...controlIds].flatMap((id) => byId.get(id)?.evidenceSourceComponentIds || [])
@@ -244,7 +249,7 @@ export async function prepareEvidencePacket(input, options = {}) {
     `data/${entry.relativePath}`,
     ...markdownEntries(loaded.model, entry.record).map((markdown) => `data/${markdown.path}`)
   ]);
-  const historyRevision = getGitSummary(loaded.root);
+  const historyRevision = await getWorkspaceRevisionSnapshot(loaded.root);
   const histories = getWorkspaceHistories(
     loaded.root,
     selectedPaths,
@@ -305,6 +310,7 @@ export async function prepareEvidencePacket(input, options = {}) {
     generatedAt,
     selectDefault: false
   });
+  const documentLifecycles = auditDocumentLifecycleSummaries(audit, loaded.model, byId);
   const gaps = packetGaps({
     audit,
     byId,
@@ -323,7 +329,7 @@ export async function prepareEvidencePacket(input, options = {}) {
   });
   const errorCount = gaps.filter(({ severity }) => severity === "error").length;
   const warningCount = gaps.filter(({ severity }) => severity === "warning").length;
-  return {
+  const packet = {
     schemaVersion: 1,
     generatedAt,
     period: { start, end, basis },
@@ -376,6 +382,7 @@ export async function prepareEvidencePacket(input, options = {}) {
       eventRuns: eventRuns.length,
       evidence: evidence.length,
       populations: populations.length,
+      ...(modelSupports(loaded.model, "governed-document-activation") ? { documents: documentLifecycles.length } : {}),
       gaps: gaps.length,
       errors: errorCount,
       warnings: warningCount
@@ -390,11 +397,64 @@ export async function prepareEvidencePacket(input, options = {}) {
     [v4 ? "sourceComponents" : "sourceSystems"]: sourceSystems,
     dataModelVersion: String(loaded.model.modelVersion),
     populations,
+    ...(modelSupports(loaded.model, "governed-document-activation") ? { documentLifecycles } : {}),
     managementPreparation,
     controlCoverage,
     gaps,
     records: packetRecords
   };
+  preparedPacketValidations.set(packet, {
+    validation,
+    revision: {
+      commit: packet.revision.commit,
+      branch: packet.revision.branch,
+      dataDigest: packet.revision.dataDigest
+    }
+  });
+  return packet;
+}
+
+function auditDocumentLifecycleSummaries(audit, model, byId) {
+  if (!audit || !modelSupports(model, "governed-document-activation")) return [];
+  const rolesById = new Map();
+  const add = (id, role) => {
+    if (!id) return;
+    const roles = rolesById.get(id) || [];
+    roles.push(role);
+    rolesById.set(id, roles);
+  };
+  add(audit.engagementTermsDocumentId, "Engagement Terms");
+  for (const definition of model.auditReadiness?.managementDocuments || []) {
+    if (!(definition.engagementKinds || []).includes(audit.auditKind)) continue;
+    add(audit[definition.field], definition.title || definition.field);
+  }
+  for (const id of audit.supplementalDocumentIds || []) add(id, "Supplemental");
+  return [...rolesById]
+    .map(([id, roles]) => {
+      const document = byId.get(id);
+      if (document?.type !== "document") return null;
+      const personLabels = (ids = []) => ids.map((personId) => byId.get(personId)?.title || personId);
+      return {
+        id: document.id,
+        title: document.title,
+        workflowScope: document.workflowScope || null,
+        roles: [...new Set(roles)],
+        status: document.status,
+        ownerIds: document.ownerIds || [],
+        approverIds: document.approverIds || [],
+        approvers: personLabels(document.approverIds),
+        approvedOn: document.approvedOn || null,
+        approvedContentRevisions: document.approvedContentRevisions || null,
+        activationBasis: document.activationBasis || null,
+        activatedByIds: document.activatedByIds || [],
+        activators: personLabels(document.activatedByIds),
+        activatedOn: document.activatedOn || null,
+        activatedContentRevisions: document.activatedContentRevisions || null,
+        effectiveOn: document.effectiveOn || null
+      };
+    })
+    .filter(Boolean)
+    .sort(byTitle);
 }
 
 function expandSupersededPolicyIds(policyIds, byId) {
@@ -422,6 +482,7 @@ function recordRelevantToAudit(record, audit, byId, seen = new Set()) {
     ...(audit.complementaryControlIds || []),
     ...auditSubserviceVendorIds(audit),
     ...auditSubserviceComponentIds(audit),
+    audit.engagementTermsDocumentId,
     audit.systemDescriptionDocumentId,
     audit.managementAssertionDocumentId,
     audit.managementRepresentationDocumentId,
@@ -501,7 +562,17 @@ export async function writeEvidencePacket(input, packet, options = {}) {
   let outputOption = options.output || `.filegrc/evidence-packets/${baseName}`;
   requireDerivedOutputPath(outputOption);
   let output = resolveWorkspacePath(input, outputOption);
-  const validation = await validateWorkspace(input);
+  const prepared = preparedPacketValidations.get(packet);
+  const preparedValidation = prepared
+    && prepared.validation.loaded.root === resolveWorkspaceRoot(input)
+    && prepared.revision.commit === packet.revision?.commit
+    && prepared.revision.branch === packet.revision?.branch
+    && prepared.revision.dataDigest === packet.revision?.dataDigest
+    ? prepared.validation
+    : null;
+  const validation = preparedValidation
+    ? preparedValidation
+    : await validateWorkspace(input);
   if (!validation.ok) throw new Error(`The workspace has ${validation.counts.errors} validation ${validation.counts.errors === 1 ? "error" : "errors"}. Fix them before writing evidence.`);
   await assertPacketSourceState(packet, validation.loaded);
   const entriesById = new Map(validation.loaded.entries.map((entry) => [entry.record.id, entry]));
@@ -531,9 +602,12 @@ export async function writeEvidencePacket(input, packet, options = {}) {
     await writePacketFile(output, "README.md", packetMarkdown(packet), files);
     await writePacketFile(output, "index.html", packetHtml(packet), files);
     await writePacketFile(output, "control-matrix.csv", controlMatrixCsv(packet), files);
+    if (modelSupports(packet.dataModelVersion, "governed-document-activation")) {
+      await writePacketFile(output, "document-lifecycle-index.csv", documentLifecycleIndexCsv(packet), files);
+    }
     await writePacketFile(output, "evidence-index.csv", evidenceIndexCsv(packet), files);
-    await writePacketFile(output, packet.dataModelVersion === "4" ? "source-component-index.csv" : "source-system-index.csv", sourceSystemIndexCsv(packet), files);
-    await writePacketFile(output, packet.dataModelVersion === "4" ? "evidence-artifact-index.csv" : "external-evidence-index.csv", externalEvidenceIndexCsv(packet), files);
+    await writePacketFile(output, modelSupports(packet.dataModelVersion, "component-sources") ? "source-component-index.csv" : "source-system-index.csv", sourceSystemIndexCsv(packet), files);
+    await writePacketFile(output, modelSupports(packet.dataModelVersion, "evidence-artifacts") ? "evidence-artifact-index.csv" : "external-evidence-index.csv", externalEvidenceIndexCsv(packet), files);
     await writePacketFile(output, "population-index.csv", populationIndexCsv(packet), files);
     await writePacketFile(output, "HANDLING.md", packetHandlingMarkdown(packet), files);
     for (const item of packet.records) {
@@ -560,12 +634,28 @@ export async function writeEvidencePacket(input, packet, options = {}) {
       }
     }
     const historyIndex = [];
+    const historicalFiles = [];
     for (const item of packet.records) {
-      await exportCommittedVersions(validation.loaded.root, output, item, item.path, item.history, historyIndex, files);
+      collectCommittedVersions(historicalFiles, item, item.path, item.history);
       for (const content of item.contentPaths || []) {
-        await exportCommittedVersions(validation.loaded.root, output, item, content.path, content.history, historyIndex, files);
+        collectCommittedVersions(historicalFiles, item, content.path, content.history);
       }
     }
+    const historicalSources = getFilesAtRevisions(validation.loaded.root, historicalFiles);
+    for (let index = 0; index < historicalFiles.length; index += 1) {
+      const source = historicalSources[index];
+      if (source === null) continue;
+      const { item, sourcePath, history } = historicalFiles[index];
+      const exportedPath = join("history", item.type, item.id, history.commit, basename(sourcePath));
+      await writePacketFile(output, exportedPath, source, files);
+      historyIndex.push({
+        resourceId: item.id,
+        resourceType: item.type,
+        sourcePath,
+        exportedPath: exportedPath.split("\\").join("/"),
+        ...history
+      });
+    }
     await writePacketFile(output, "history/index.json", `${JSON.stringify(historyIndex, null, 2)}\n`, files);
     await assertPacketSourceState(packet, validation.loaded);
     await writeChecksums(output, files);
@@ -586,35 +676,34 @@ export function generateEvidencePacket(input, options = {}) {
   });
 }
 
-async function exportCommittedVersions(root, output, item, sourcePath, history, historyIndex, files) {
+function collectCommittedVersions(target, item, sourcePath, history) {
   for (const revision of history || []) {
-    const source = getFileAtRevision(root, revision.commit, sourcePath);
-    if (source === null) continue;
-    const exportedPath = join("history", item.type, item.id, revision.commit, basename(sourcePath));
-    await writePacketFile(output, exportedPath, source, files);
-    historyIndex.push({
-      resourceId: item.id,
-      resourceType: item.type,
-      sourcePath,
-      exportedPath: exportedPath.split("\\").join("/"),
-      ...revision
-    });
+    target.push({ item, sourcePath, relativePath: sourcePath, revision: revision.commit, history: revision });
   }
 }
 
 async function writeChecksums(output, files) {
-  const lines = [];
-  for (const relativePath of [...files].sort()) {
-    const hash = createHash("sha256");
-    for await (const chunk of createReadStream(resolvePacketOutputPath(output, relativePath))) hash.update(chunk);
-    lines.push(`${hash.digest("hex")}  ${relativePath}`);
-  }
-  await writeFile(resolvePacketOutputPath(output, "SHA256SUMS"), `${lines.join("\n")}\n`, { encoding: "utf8", flag: "wx" });
+  await measureTiming("packet-output-hash", async () => {
+    const paths = [...files].sort();
+    const lines = new Array(paths.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(4, paths.length) }, async () => {
+      while (next < paths.length) {
+        const index = next++;
+        const relativePath = paths[index];
+        const hash = createHash("sha256");
+        for await (const chunk of createReadStream(resolvePacketOutputPath(output, relativePath))) hash.update(chunk);
+        lines[index] = `${hash.digest("hex")}  ${relativePath}`;
+      }
+    });
+    await Promise.all(workers);
+    await writeFile(resolvePacketOutputPath(output, "SHA256SUMS"), `${lines.join("\n")}\n`, { encoding: "utf8", flag: "wx" });
+  });
 }
 
 function controlMatrixCsv(packet) {
   return csv([
-    ["Control ID", "Code", "Control", "Control Statement", "Operating Activity", "Status", "Effective On", "Operation Pattern", "Operation Mode", "System IDs", "Requirement IDs", "Policy IDs", "Risk IDs", "filegrc Evidence IDs", packet.dataModelVersion === "4" ? "Evidence Artifact IDs" : "External Evidence IDs", "Control Test IDs", "Test Outcomes", "Population IDs", "Population Counts", "Sample Sizes", "Exception Counts", "Population Evidence IDs", "Sample Evidence IDs"],
+    ["Control ID", "Code", "Control", "Control Statement", "Operating Activity", "Status", "Effective On", "Operation Pattern", "Operation Mode", "System IDs", "Requirement IDs", "Policy IDs", "Risk IDs", "filegrc Evidence IDs", modelSupports(packet.dataModelVersion, "evidence-artifacts") ? "Evidence Artifact IDs" : "External Evidence IDs", "Control Test IDs", "Test Outcomes", "Population IDs", "Population Counts", "Sample Sizes", "Exception Counts", "Population Evidence IDs", "Sample Evidence IDs"],
     ...packet.controlCoverage.map((control) => [
       control.id,
       control.code,
@@ -643,6 +732,30 @@ function controlMatrixCsv(packet) {
   ]);
 }
 
+function documentLifecycleIndexCsv(packet) {
+  return csv([
+    ["Document ID", "Document", "Workflow Scope", "Audit Roles", "Status", "Owner IDs", "Approver IDs", "Approvers", "Approved On", "Approved Content Revisions", "Activation Basis", "Activator IDs", "Activators", "Activated On", "Activation Content Revisions", "Effective On"],
+    ...packet.documentLifecycles.map((document) => [
+      document.id,
+      document.title,
+      document.workflowScope,
+      document.roles.join("\n"),
+      document.status,
+      document.ownerIds.join("\n"),
+      document.approverIds.join("\n"),
+      document.approvers.join("\n"),
+      document.approvedOn,
+      document.approvedContentRevisions ? JSON.stringify(document.approvedContentRevisions) : "",
+      document.activationBasis,
+      document.activatedByIds.join("\n"),
+      document.activators.join("\n"),
+      document.activatedOn,
+      document.activatedContentRevisions ? JSON.stringify(document.activatedContentRevisions) : "",
+      document.effectiveOn
+    ])
+  ]);
+}
+
 function packetHandlingMarkdown(packet) {
   return [
     "# Packet Handling",
@@ -663,7 +776,7 @@ function packetHandlingMarkdown(packet) {
 }
 
 function evidenceIndexCsv(packet) {
-  const v4 = packet.dataModelVersion === "4";
+  const v4 = modelSupports(packet.dataModelVersion, "component-sources");
   return csv([
     ["Evidence ID", v4 ? "Evidence Artifact" : "Evidence", "Status", "Kind", "Source", v4 ? "Source Component ID" : "Source System ID", v4 ? "Source Component" : "Source System", "Collected On", "Collector IDs", "Verified On", "Verifier IDs", "Period Start", "Period End", "Generated At", "Timezone", "Query or Report Parameters", "Population Count", "Completeness Validation", "Accuracy Validation", "Control IDs", "Source Resource IDs", "Source Commit", "File Paths", "External Reference"],
     ...packet.evidence.map((item) => [
@@ -696,7 +809,7 @@ function evidenceIndexCsv(packet) {
 }
 
 function sourceSystemIndexCsv(packet) {
-  const v4 = packet.dataModelVersion === "4";
+  const v4 = modelSupports(packet.dataModelVersion, "component-sources");
   return csv([
     [v4 ? "Component ID" : "System ID", v4 ? "Component" : "System", "Status", "Evidence Source Roles", "Evidence Access Owner IDs", "Vendor ID", v4 ? "Supports Audit System" : "In Audit Scope", "Evidence IDs"],
     ...(packet.sourceComponents || packet.sourceSystems || []).map((item) => [
@@ -713,7 +826,7 @@ function sourceSystemIndexCsv(packet) {
 }
 
 function externalEvidenceIndexCsv(packet) {
-  const v4 = packet.dataModelVersion === "4";
+  const v4 = modelSupports(packet.dataModelVersion, "component-sources");
   return csv([
     ["Evidence ID", v4 ? "Evidence Artifact" : "Evidence", v4 ? "Source Component ID" : "Source System ID", v4 ? "Source Component" : "Source System", "Control IDs", "External Reference", "Fixed Attachment Included", "Delivery Note"],
     ...packet.evidence
@@ -734,7 +847,7 @@ function externalEvidenceIndexCsv(packet) {
 }
 
 function populationIndexCsv(packet) {
-  const v4 = packet.dataModelVersion === "4";
+  const v4 = modelSupports(packet.dataModelVersion, "component-sources");
   return csv([
     ["Population ID", "Population", "Kind", "Status", "Period Start", "Period End", v4 ? "Source Component ID" : "Source System ID", v4 ? "Source Component" : "Source System", "Authoritative Source", "Query or Report Parameters", "Timezone", "Generated At", "Record Count", "Completeness Validation", "Accuracy Validation", "Reconciled By", "Reconciled On", "Conclusion", "Control IDs", "Evidence ID", "Not Applicable Reason"],
     ...packet.populations.map((item) => [
@@ -787,7 +900,7 @@ function requireDerivedOutputPath(value) {
 async function assertPacketSourceState(packet, loaded) {
   await assertLoadedEntriesCurrent(loaded);
   const dataDigest = await dataTreeDigest(loaded.root);
-  const git = getGitSummary(loaded.root);
+  const git = await getWorkspaceRevisionSnapshot(loaded.root);
   if (
     packet.revision?.dataDigest !== dataDigest
     || packet.revision?.commit !== git.commit
@@ -807,36 +920,38 @@ async function assertLoadedEntriesCurrent(loaded) {
 }
 
 async function dataTreeDigest(root) {
-  const hash = createHash("sha256");
-  updateDigestField(hash, "filegrc-data-tree-v1");
-  const visit = async (directory, prefix = "") => {
-    const entries = await readdir(directory, { withFileTypes: true });
-    entries.sort((a, b) => a.name.localeCompare(b.name));
-    for (const entry of entries) {
-      const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
-      const path = join(directory, entry.name);
-      if (entry.isDirectory()) {
-        updateDigestField(hash, "directory");
-        updateDigestField(hash, relativePath);
-        await visit(path, relativePath);
-      } else if (entry.isFile()) {
-        const fileHash = createHash("sha256");
-        for await (const chunk of createReadStream(path)) fileHash.update(chunk);
-        updateDigestField(hash, "file");
-        updateDigestField(hash, relativePath);
-        updateDigestField(hash, fileHash.digest("hex"));
-      } else if (entry.isSymbolicLink()) {
-        updateDigestField(hash, "symlink");
-        updateDigestField(hash, relativePath);
-        updateDigestField(hash, await readlink(path));
-      } else {
-        updateDigestField(hash, "other");
-        updateDigestField(hash, relativePath);
+  return measureTiming("packet-data-hash", async () => {
+    const hash = createHash("sha256");
+    updateDigestField(hash, "filegrc-data-tree-v1");
+    const visit = async (directory, prefix = "") => {
+      const entries = await readdir(directory, { withFileTypes: true });
+      entries.sort((a, b) => a.name.localeCompare(b.name));
+      for (const entry of entries) {
+        const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) {
+          updateDigestField(hash, "directory");
+          updateDigestField(hash, relativePath);
+          await visit(path, relativePath);
+        } else if (entry.isFile()) {
+          const fileHash = createHash("sha256");
+          for await (const chunk of createReadStream(path)) fileHash.update(chunk);
+          updateDigestField(hash, "file");
+          updateDigestField(hash, relativePath);
+          updateDigestField(hash, fileHash.digest("hex"));
+        } else if (entry.isSymbolicLink()) {
+          updateDigestField(hash, "symlink");
+          updateDigestField(hash, relativePath);
+          updateDigestField(hash, await readlink(path));
+        } else {
+          updateDigestField(hash, "other");
+          updateDigestField(hash, relativePath);
+        }
       }
-    }
-  };
-  await visit(resolveDataPath(root, "."));
-  return `sha256:${hash.digest("hex")}`;
+    };
+    await visit(resolveDataPath(root, "."));
+    return `sha256:${hash.digest("hex")}`;
+  });
 }
 
 function updateDigestField(hash, value) {
@@ -1049,7 +1164,7 @@ function packetGaps({
       }
     }
     if (controlNeedsExternalEvidence(control, model) && !coverage.evidenceIds.length) {
-      gaps.push(gap("error", "control-missing-external-evidence", `${coverage.code || coverage.title} relies on an external source but has no linked ${String(model.modelVersion) === "4" ? "Evidence Artifact" : "External Evidence"} in the packet.`, coverage.id));
+      gaps.push(gap("error", "control-missing-external-evidence", `${coverage.code || coverage.title} relies on an external source but has no linked ${modelSupports(model, "evidence-artifacts") ? "Evidence Artifact" : "External Evidence"} in the packet.`, coverage.id));
     } else if (!controlNeedsExternalEvidence(control, model) && !coverage.operatingRecordIds.length) {
       gaps.push(gap("error", "control-missing-filegrc-evidence", `${coverage.code || coverage.title} has no dated filegrc operating record in the packet.`, coverage.id));
     }
@@ -1265,7 +1380,7 @@ function packetGaps({
         }
       }
     } else if (["population-export", "system-export", "configuration-export"].includes(item.artifactKind)) {
-      gaps.push(gap("error", "evidence-source-system-unrecorded", `${item.title} is a source export but does not link the cataloged ${String(model.modelVersion) === "4" ? "source Component" : "system of record"}.`, item.id));
+      gaps.push(gap("error", "evidence-source-system-unrecorded", `${item.title} is a source export but does not link the cataloged ${modelSupports(model, "component-sources") ? "source Component" : "system of record"}.`, item.id));
     }
     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));
@@ -1322,7 +1437,7 @@ function controlNeedsExternalEvidence(control, model) {
 
 function auditGaps(gaps, audit, byId, records, start, end, model) {
   const program = byId.get(audit.programId);
-  if (String(model.modelVersion) === "4" && program?.assuranceGoal !== audit.auditKind) {
+  if (modelSupports(model, "program-scope") && program?.assuranceGoal !== audit.auditKind) {
     gaps.push(gap("error", "audit-program-goal-mismatch", `${audit.title} is ${audit.auditKind}, but its Program goal is ${program?.assuranceGoal || "missing"}. Align the management objective with the formal engagement before delivery.`, audit.id));
   }
   if (!["soc-2-type-1", "soc-2-type-2"].includes(audit.auditKind)) {
@@ -1350,14 +1465,14 @@ function auditGaps(gaps, audit, byId, records, start, end, model) {
   const missingDescriptionRequirements = descriptionRequirements.filter((requirement) => (
     !(audit.requirementIds || []).includes(requirement.id)
   ));
-  const missingRequiredDescriptionReferences = String(model.modelVersion) === "4"
+  const missingRequiredDescriptionReferences = modelSupports(model, "program-scope")
     ? missingSoc2References(descriptionRequirements, REQUIRED_SOC2_DESCRIPTION_REFERENCES)
     : [];
   const securityRequirements = frameworkRequirements.filter(isSecurityRequirement);
-  const missingRequiredSecurityReferences = String(model.modelVersion) === "4"
+  const missingRequiredSecurityReferences = modelSupports(model, "program-scope")
     ? missingSoc2References(securityRequirements, REQUIRED_SOC2_SECURITY_REFERENCES)
     : [];
-  const missingSelectedSecurityReferences = String(model.modelVersion) === "4"
+  const missingSelectedSecurityReferences = modelSupports(model, "program-scope")
     ? missingSoc2References(selectedRequirements.filter(isSecurityRequirement), REQUIRED_SOC2_SECURITY_REFERENCES)
     : [];
   if (!descriptionRequirements.length) {
@@ -1384,10 +1499,10 @@ function auditGaps(gaps, audit, byId, records, start, end, model) {
   } else if (!auditorWasEngaged(auditor, audit)) {
     gaps.push(gap("error", "auditor-outside-engagement-period", `${auditor.title} was not active during the recorded fieldwork or report period.`, auditor.id));
   }
-  if (String(model.modelVersion) === "4" && !audit.scopeRevision) {
+  if (modelSupports(model, "program-scope") && !audit.scopeRevision) {
     gaps.push(gap("error", "audit-scope-revision-missing", `${audit.title} does not bind management's reviewed engagement scope to a Git revision.`, audit.id));
   }
-  if (String(model.modelVersion) === "4") {
+  if (modelSupports(model, "program-scope")) {
     const treatments = audit.subserviceTreatments || [];
     const treatmentComponentCounts = new Map();
     for (const treatment of treatments) {
@@ -1503,7 +1618,7 @@ function auditGaps(gaps, audit, byId, records, start, end, model) {
       gaps.push(gap("error", "missing-audit-opinion", `${audit.title} does not record the issued opinion and opinion date.`, audit.id));
     }
   }
-  if (String(model.modelVersion) === "4" && ["report-draft", "issued", "delivered", "complete"].includes(audit.status)) {
+  if (modelSupports(model, "program-scope") && ["report-draft", "issued", "delivered", "complete"].includes(audit.status)) {
     const subsequentEventsIssue = subsequentEventsReviewIssue(audit);
     if (subsequentEventsIssue) {
       gaps.push(gap("error", subsequentEventsIssue.code, subsequentEventsIssue.message, audit.id));
@@ -1557,7 +1672,7 @@ function isSecurityRequirement(requirement) {
 }
 
 function requirementIsApplicable(requirement, audit, byId, model) {
-  if (String(model.modelVersion) !== "4") return requirement.applicability === "applicable";
+  if (!modelSupports(model, "program-scope")) return requirement.applicability === "applicable";
   const program = audit?.programId ? byId.get(audit.programId) : null;
   return (program?.requirementApplicability || []).some((decision) => (
     decision.requirementId === requirement.id && decision.decision === "applicable"
@@ -1785,7 +1900,7 @@ function recordSummary(record) {
 }
 
 function packetMarkdown(packet) {
-  const v4 = packet.dataModelVersion === "4";
+  const v4 = modelSupports(packet.dataModelVersion, "component-sources");
   const readiness = packet.readiness.status === "delivery-ready"
     ? "filegrc management checks passed. The engagement team still determines whether the evidence is sufficient and appropriate."
     : `${packet.readiness.errors} errors and ${packet.readiness.warnings} warnings require review. This is a draft packet.`;
@@ -1812,6 +1927,9 @@ function packetMarkdown(packet) {
     `- ${packet.summary.eventRuns} event runs`,
     `- ${packet.summary.evidence} ${v4 ? "Evidence Artifact" : "External Evidence"} records`,
     `- ${packet.summary.populations} reconciled or planned populations`,
+    ...(modelSupports(packet.dataModelVersion, "governed-document-activation")
+      ? [`- ${packet.summary.documents} governed engagement Documents with approval and activation history`]
+      : []),
     `- ${packet.summary.policies} policies`,
     `- ${packet.summary.controls} controls`,
     `- ${packet.summary.requirements} criteria`,
@@ -1819,7 +1937,7 @@ function packetMarkdown(packet) {
     `- ${v4 ? packet.summary.sourceComponents : packet.summary.sourceSystems} cataloged source ${v4 ? "Components" : "Systems"}`,
     "",
     v4
-      ? "Open `index.html` for the auditor-oriented index. `control-matrix.csv` cross-references criteria, Controls, filegrc Evidence, Evidence Artifacts, and tests. `source-component-index.csv` identifies the Components used to produce Evidence. `evidence-artifact-index.csv` lists material that must be delivered or accessed outside this packet. For Type 2, `population-index.csv` records management's population reconciliation and fixed source exports. FileGRC records, governed Markdown, fixed attachments, and committed historical versions are included in their respective directories."
+      ? `Open \`index.html\` for the auditor-oriented index. \`control-matrix.csv\` cross-references criteria, Controls, filegrc Evidence, Evidence Artifacts, and tests.${modelSupports(packet.dataModelVersion, "governed-document-activation") ? " `document-lifecycle-index.csv` lists each engagement Document's approval and activation facts and exact Markdown revisions." : ""} \`source-component-index.csv\` identifies the Components used to produce Evidence. \`evidence-artifact-index.csv\` lists material that must be delivered or accessed outside this packet. For Type 2, \`population-index.csv\` records management's population reconciliation and fixed source exports. FileGRC records, governed Markdown, fixed attachments, and committed historical versions are included in their respective directories.`
       : "Open `index.html` for the auditor-oriented index. `control-matrix.csv` cross-references criteria, controls, filegrc Evidence, External Evidence, and tests. `source-system-index.csv` identifies the systems of record used to produce External Evidence. `external-evidence-index.csv` lists material that must be delivered or accessed outside this packet. For Type 2, `population-index.csv` records management's population reconciliation and fixed source exports. filegrc records, governed Markdown, fixed attachments, and committed historical versions are included in their respective directories.",
     "",
     "After transfer, enter the packet directory and run `shasum -a 256 -c SHA256SUMS` or `sha256sum -c SHA256SUMS`. The checksum file covers every other packet file.",
@@ -1829,7 +1947,7 @@ function packetMarkdown(packet) {
 }
 
 function packetHtml(packet) {
-  const v4 = packet.dataModelVersion === "4";
+  const v4 = modelSupports(packet.dataModelVersion, "component-sources");
   const artifactLabel = v4 ? "Evidence Artifact" : "External Evidence";
   const section = (title, body) => `<section><h2>${escapeHtml(title)}</h2>${body}</section>`;
   const links = (items) => items.length
@@ -1875,13 +1993,16 @@ function packetHtml(packet) {
   const controlCoverage = packet.controlCoverage.length
     ? `<p><a href="control-matrix.csv">Download control matrix CSV</a></p><table><thead><tr><th>Control</th><th>Status and scope</th><th>Criteria</th><th>filegrc Evidence</th><th>${artifactLabel}</th><th>Tests</th></tr></thead><tbody>${packet.controlCoverage.map((control) => `<tr><td><a href="records/control/${encodeURIComponent(control.id)}.json">${escapeHtml(control.code || control.id)}</a><small>${escapeHtml(control.title)}</small></td><td>${escapeHtml(control.status)}<small>${control.systemIds.map(escapeHtml).join(", ") || "No system scope"}</small></td><td>${control.requirementIds.map(escapeHtml).join("<br>") || "None"}</td><td>${control.operatingRecordIds.length}</td><td>${control.evidenceIds.length}</td><td>${control.tests.length}</td></tr>`).join("")}</tbody></table>`
     : "<p>No controls were selected.</p>";
+  const documentLifecycles = packet.documentLifecycles?.length
+    ? `<p><a href="document-lifecycle-index.csv">Download Document lifecycle index CSV</a></p><table><thead><tr><th>Document</th><th>Audit role</th><th>Approval</th><th>Activation</th></tr></thead><tbody>${packet.documentLifecycles.map((document) => `<tr><td><a href="records/document/${encodeURIComponent(document.id)}.json">${escapeHtml(document.title)}</a><small>${escapeHtml(document.status)} · ${escapeHtml(document.workflowScope || "scope not recorded")}</small></td><td>${document.roles.map(escapeHtml).join("<br>")}</td><td>${escapeHtml(document.approvedOn || "Not approved")}<small>${document.approvers.map(escapeHtml).join(", ") || "No approver recorded"}</small></td><td>${escapeHtml(document.activatedOn || "Not activated")}<small>${document.activators.map(escapeHtml).join(", ") || "No activator recorded"}${document.effectiveOn ? ` · effective ${escapeHtml(document.effectiveOn)}` : ""}</small></td></tr>`).join("")}</tbody></table>`
+    : "<p>No governed engagement Documents were linked to this audit.</p>";
   const readinessLabel = packet.readiness.status === "delivery-ready" ? "filegrc management checks passed" : "Draft, do not deliver";
   const packetDate = packet.period.basis === "as-of"
     ? `As of ${escapeHtml(packet.period.start)}`
     : `${escapeHtml(packet.period.start)} through ${escapeHtml(packet.period.end)}`;
   return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Evidence packet</title><style>
 body{font:14px/1.5 system-ui,sans-serif;color:#161825;max-width:1120px;margin:auto;padding:40px;background:#f7f8fc}header,section{background:#fff;border:1px solid #dfe3ef;border-radius:10px;padding:24px;margin:14px 0}h1,h2{margin-top:0}h1{font-size:26px}h2{font-size:17px}ul{padding-left:20px}li{margin:8px 0}small{display:block;color:#656c7e}.attachment{margin-right:10px;font-size:12px}.error{color:#8a2f28}.warning{color:#76500d}.readiness{display:inline-block;padding:5px 9px;border-radius:999px;background:#f7e4e2;color:#7a2520;font-weight:700}.readiness.ready{background:#e2f1e8;color:#245d3b}table{width:100%;border-collapse:collapse}th,td{padding:9px;border:1px solid #dfe3ef;text-align:left;vertical-align:top}code{overflow-wrap:anywhere}dl{display:grid;grid-template-columns:max-content 1fr;gap:8px 16px}dt{font-weight:700}dd{margin:0}
-</style></head><body><header><p>SOC 2 evidence packet</p><span class="readiness ${packet.readiness.status === "delivery-ready" ? "ready" : ""}">${escapeHtml(readinessLabel)}</span><h1>${packetDate}</h1><p>${escapeHtml(packet.workspace.organizationName)} · revision <code>${escapeHtml(packet.revision.commit || "uncommitted")}</code></p></header>${section("Engagement scope", engagement)}${section("Review status", gaps)}${section("Control coverage", controlCoverage)}${section(v4 ? "Source Components" : "Systems of record", sourceSystems)}${packet.period.basis === "period" ? section("Management population reconciliation", populations) : ""}${packet.period.basis === "period" ? section("Recurring obligation coverage", obligations) : ""}${packet.period.basis === "period" ? section("Event workflow coverage", eventRuns) : ""}${section("Policies", links(packet.policies))}${section("filegrc Evidence", filegrcRecords)}${section(v4 ? "Evidence Artifacts" : "External Evidence", evidence)}${section("Integrity and history", "<p>Verify all transferred files with <code>SHA256SUMS</code>. Committed prior versions are under <code>history/</code> with an index that records their source paths and Git metadata.</p>")}</body></html>`;
+</style></head><body><header><p>SOC 2 evidence packet</p><span class="readiness ${packet.readiness.status === "delivery-ready" ? "ready" : ""}">${escapeHtml(readinessLabel)}</span><h1>${packetDate}</h1><p>${escapeHtml(packet.workspace.organizationName)} · revision <code>${escapeHtml(packet.revision.commit || "uncommitted")}</code></p></header>${section("Engagement scope", engagement)}${section("Review status", gaps)}${modelSupports(packet.dataModelVersion, "governed-document-activation") ? section("Document lifecycle", documentLifecycles) : ""}${section("Control coverage", controlCoverage)}${section(v4 ? "Source Components" : "Systems of record", sourceSystems)}${packet.period.basis === "period" ? section("Management population reconciliation", populations) : ""}${packet.period.basis === "period" ? section("Recurring obligation coverage", obligations) : ""}${packet.period.basis === "period" ? section("Event workflow coverage", eventRuns) : ""}${section("Policies", links(packet.policies))}${section("filegrc Evidence", filegrcRecords)}${section(v4 ? "Evidence Artifacts" : "External Evidence", evidence)}${section("Integrity and history", "<p>Verify all transferred files with <code>SHA256SUMS</code>. Committed prior versions are under <code>history/</code> with an index that records their source paths and Git metadata.</p>")}</body></html>`;
 }
 
 async function writePacketFile(output, relativePath, source, files) {

package/src/external-reviewer.js

@@ -1,3 +1,4 @@
+import { modelSupports } from "../model/index.js";
 import { applyResourceBatch } from "./files.js";
 import { createResourceId } from "./id.js";
 import { currentCalendarDate } from "./time.js";
@@ -5,8 +6,8 @@ import { loadWorkspace } from "./workspace.js";
 
 export async function scaffoldExternalReviewerGovernance(input = process.cwd()) {
   const loaded = await loadWorkspace(input);
-  if (!["3", "4"].includes(String(loaded.model.modelVersion))) {
-    throw new Error("External reviewer setup requires a model v3 or v4 workspace.");
+  if (!modelSupports(loaded.model, "guided-workflow")) {
+    throw new Error("External reviewer setup requires a model v3 or newer workspace.");
   }
   return {
     reviewerName: null,
@@ -22,8 +23,8 @@ export async function scaffoldExternalReviewerGovernance(input = process.cwd())
 
 export async function planExternalReviewerGovernance(input = process.cwd(), options = {}) {
   const loaded = await loadWorkspace(input);
-  if (!["3", "4"].includes(String(loaded.model.modelVersion))) {
-    throw new Error("External reviewer setup requires a model v3 or v4 workspace.");
+  if (!modelSupports(loaded.model, "guided-workflow")) {
+    throw new Error("External reviewer setup requires a model v3 or newer workspace.");
   }
   const name = required(options.reviewerName, "External reviewer name");
   const startsOn = required(options.startsOn, "Appointment start date");