filegrc 0.14.0 → 0.15.0

package/model/index.js

@@ -17,7 +17,8 @@ export const MODEL_CAPABILITY_VERSIONS = Object.freeze({
   "temporal-collection-reviews": 9,
   "reporting-routes": 9,
   "reporting-route-sets": 10,
-  "control-collection-oversight": 11
+  "control-collection-oversight": 11,
+  "retention-schedule-approval": 11
 });
 
 export function modelSupports(modelOrVersion, capability) {

package/model/v11.json

@@ -643,12 +643,12 @@
       ]
     },
     "retention-schedule-item": {
-      "title": "Retention schedule",
-      "description": "Confirm that every active information use has an approved or explicitly planned retention schedule item and that no schedule item invents an organization-specific period or disposition.",
+      "title": "Data Retention Schedule",
+      "description": "Approve the schedule document and its structured rows as one governed schedule. Include only actual information uses and keep undecided organization values planned.",
       "reviewPoints": [
-        "Confirm schedule coverage across Systems, Components, Vendors, source families, logs, backups, audit records, and the FileGRC repository.",
-        "Confirm every active item has an approved cutoff, retention period, disposition action, owner, approver, and exact reviewed source revisions.",
-        "Keep undecided periods and disposition behavior planned for management review."
+        "Review the Data Retention Schedule document, its Markdown, and every included structured row as one revision.",
+        "Confirm schedule coverage across the Systems, Components, Vendors, source families, logs, backups, audit records, and FileGRC records the organization actually uses.",
+        "Confirm every active item has an approved cutoff, retention period, disposition action, owner, approver, and exact reviewed source revisions; keep undecided behavior planned."
       ],
       "decisions": [
         "complete",

package/package.json

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

package/src/agent.js

@@ -82,7 +82,7 @@ export function buildAgentGuide(loaded, type, options = {}) {
     instructions: RESOURCE_INSTRUCTIONS[type] || definition.description,
     use: definition.description,
     purpose: definition.description,
-    programStep: resourceProgramContext(type),
+    programStep: resourceProgramContext(type, loaded.model),
     policyBasis: definition.guidance.policyBasis,
     cadence: definition.guidance.cadence,
     emptyState: definition.guidance.emptyState ?? null,

package/src/collection-review.js

@@ -12,6 +12,7 @@ import { loadWorkspace } from "./workspace.js";
 import { resolveProgram } from "./program.js";
 import { currentCalendarDate } from "./time.js";
 import { currentPartyPeople } from "./parties.js";
+import { retentionScheduleApprovalIssues } from "./retention-schedule-approval.js";
 
 export { collectionRevision };
 
@@ -66,7 +67,14 @@ export function assessCollectionReview(loaded, resourceType, options = {}) {
   );
   const reviewerEligibility = resourceType === "control"
     ? assessControlReviewers(loaded, records)
-    : null;
+    : resourceType === "retention-schedule-item" && modelSupports(loaded.model, "retention-schedule-approval")
+      ? assessRetentionScheduleReviewers(loaded, records)
+      : null;
+  const approvalIssues = resourceType === "retention-schedule-item" && modelSupports(loaded.model, "retention-schedule-approval")
+    ? retentionScheduleApprovalIssues(loaded, program, records, {
+        informationTypesReviewed: assessCollectionReview(loaded, "information-type", options).complete
+      })
+    : [];
   const reviewersEligible = !reviewerEligibility || Boolean(
     review?.reviewedByIds?.length
     && review.reviewedByIds.every((id) => reviewerEligibility.eligibleReviewerIds.includes(id))
@@ -77,6 +85,7 @@ export function assessCollectionReview(loaded, resourceType, options = {}) {
     && revisionMatches
     && temporalReview
     && reviewersEligible
+    && !approvalIssues.length
   );
   const stale = Boolean(
     review?.status === "active"
@@ -96,10 +105,15 @@ export function assessCollectionReview(loaded, resourceType, options = {}) {
     status: complete ? "current" : stale ? "stale" : "review-required",
     complete,
     ...(reviewerEligibility || {}),
+    ...(approvalIssues.length ? { approvalIssues } : {}),
     message: complete
       ? `${configuration.title} were reviewed on ${review.reviewedOn}.`
+      : approvalIssues.length
+        ? approvalIssues[0].message
       : revisionMatches && review?.status === "active" && !reviewersEligible
-        ? "Review the Control collection again with a reviewer who does not own an included Control or its enabled Obligation."
+        ? resourceType === "retention-schedule-item"
+          ? "Review the Data Retention Schedule again with a reviewer who does not own its governing document or an included schedule row."
+          : "Review the Control collection again with a reviewer who does not own an included Control or its enabled Obligation."
       : stale
         ? `${configuration.title} changed after the last confirmation. Review the current records again.`
         : !records.length && !allowsEmptyCollection
@@ -143,6 +157,9 @@ export async function scaffoldCollectionReview(input = process.cwd(), options =
     reviewedOn: priorReview?.reviewedOn
       ? currentCalendarDate(loaded.workspace.timezone, now)
       : null,
+    ...(resourceType === "retention-schedule-item" && modelSupports(loaded.model, "retention-schedule-approval")
+      ? { expectedCollectionRevision: assessment.collectionRevision }
+      : {}),
     ...(v4
       ? { authoritativeComponentId: preservedAuthoritativeSourceId }
       : { authoritativeSystemId: preservedAuthoritativeSourceId })
@@ -154,7 +171,14 @@ export async function planCollectionReview(input = process.cwd(), options = {})
   const program = resolveProgram(loaded, options.programId);
   const resourceType = requiredType(loaded, options.resourceType);
   const assessment = assessCollectionReview(loaded, resourceType, { programId: program.id });
+  if (options.expectedCollectionRevision && options.expectedCollectionRevision !== assessment.collectionRevision) {
+    throw new Error(`${assessment.configuration.title} changed after it was displayed. Reload and review the current revision before approving it.`);
+  }
+  if (resourceType === "retention-schedule-item" && modelSupports(loaded.model, "retention-schedule-approval") && !options.expectedCollectionRevision) {
+    throw new Error("Data Retention Schedule approval requires the displayed collection revision. Reload or scaffold the current review before approving it.");
+  }
   await requireControlReviewReady(loaded, resourceType, program.id);
+  await requireRetentionScheduleReady(loaded, resourceType, program);
   const configuration = assessment.configuration;
   const decision = String(options.decision || "").trim();
   const rationale = String(options.rationale || "").trim();
@@ -199,6 +223,13 @@ export async function planCollectionReview(input = process.cwd(), options = {})
       throw new Error(`Control collection review needs a reviewer who does not own an included Control or its enabled Obligation: ${conflicts.join(", ")}.`);
     }
   }
+  if (resourceType === "retention-schedule-item" && modelSupports(loaded.model, "retention-schedule-approval")) {
+    const eligible = new Set(assessment.eligibleReviewerIds || []);
+    const conflicts = reviewedByIds.filter((id) => !eligible.has(id));
+    if (conflicts.length) {
+      throw new Error(`Data Retention Schedule approval needs a reviewer who does not own its governing document or an included schedule row: ${conflicts.join(", ")}.`);
+    }
+  }
   if (temporalReviews) {
     if (reviewedOn !== today) {
       throw new Error("A current Collection Review must use today's workspace-local review date. Reconstruct an older population from Git history instead of backdating today's files.");
@@ -308,6 +339,15 @@ async function requireControlReviewReady(loaded, resourceType, programId) {
   }
 }
 
+async function requireRetentionScheduleReady(loaded, resourceType, program) {
+  if (resourceType !== "retention-schedule-item" || !modelSupports(loaded.model, "retention-schedule-approval")) return;
+  const rows = scopedCollectionRecords(loaded, resourceType, program);
+  const approvalIssues = retentionScheduleApprovalIssues(loaded, program, rows, {
+    informationTypesReviewed: assessCollectionReview(loaded, "information-type", { programId: program.id }).complete
+  });
+  if (approvalIssues.length) throw new Error(approvalIssues[0].message);
+}
+
 function assessControlReviewers(loaded, controls) {
   const byId = new Map(loaded.resources.map((record) => [record.id, record]));
   const controlIds = new Set(controls.map(({ id }) => id));
@@ -329,6 +369,25 @@ function assessControlReviewers(loaded, controls) {
   };
 }
 
+function assessRetentionScheduleReviewers(loaded, rows) {
+  const byId = new Map(loaded.resources.map((record) => [record.id, record]));
+  const conflictIds = new Set();
+  const schedules = loaded.resources.filter((record) => (
+    record.type === "document"
+    && record.documentKind === "schedule"
+    && record.workflowScope === "program"
+    && !["superseded", "retired"].includes(record.status)
+  ));
+  for (const record of [...schedules, ...rows]) {
+    for (const id of currentPartyPeople(record.ownerIds || [], byId)) conflictIds.add(id);
+  }
+  const people = loaded.resources.filter(({ type, status }) => type === "person" && status === "active");
+  return {
+    eligibleReviewerIds: people.map(({ id }) => id).filter((id) => !conflictIds.has(id)),
+    reviewerConflictIds: people.map(({ id }) => id).filter((id) => conflictIds.has(id))
+  };
+}
+
 function sameIds(left, right) {
   return JSON.stringify([...left].sort()) === JSON.stringify([...right].sort());
 }

package/src/collection-revision.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
+import { modelSupports } from "../model/index.js";
 import {
   authoritativeSourceRevisionValue,
   collectionRevisionInputs,
@@ -24,7 +25,8 @@ export function collectionRevisionMatches(loaded, resourceType, storedRevision,
   // Version 0.9.2 narrowed this hash basis. Keep unchanged 0.9.1 reviews valid
   // until management records a new review on the current basis.
   return storedRevision === currentRevision
-    || storedRevision === legacyCollectionRevision(loaded, resourceType, options);
+    || (resourceType !== "retention-schedule-item" || !modelSupports(loaded.model, "retention-schedule-approval"))
+      && storedRevision === legacyCollectionRevision(loaded, resourceType, options);
 }
 
 function calculateCollectionRevision(loaded, resourceType, options, legacy) {

package/src/collection-scope.js

@@ -1,12 +1,17 @@
 import { modelSupports } from "../model/index.js";
 import { programComponents, selectedRequirementIds } from "./program.js";
-import { retentionReviewResourceIds } from "./retention.js";
+import { retentionReviewResourceIds, retentionUses } from "./retention.js";
 import { documentIsAuditSpecific } from "./program-lifecycle.js";
 
 export function scopedCollectionRecords(loaded, resourceType, program) {
   if (!modelSupports(loaded.model, "program-scope")) {
     return loaded.resources.filter((record) => record.type === resourceType);
   }
+  if (resourceType === "retention-schedule-item" && modelSupports(loaded.model, "retention-schedule-approval")) {
+    return loaded.resources.filter((record) => (
+      record.type === resourceType && !["retired", "superseded"].includes(record.status)
+    ));
+  }
   if (resourceType === "person") {
     return scopedProgramPeople(loaded, program);
   }
@@ -225,6 +230,29 @@ export function collectionRevisionInputs(loaded, resourceType, program, options
       .filter((record) => record.type === "vendor" && record.status !== "retired")
       .map(({ id }) => id));
   }
+  if (resourceType === "retention-schedule-item" && !legacy && modelSupports(loaded.model, "retention-schedule-approval")) {
+    const uses = retentionUses(loaded, program || {});
+    addIds(uses.map(({ resource }) => resource.id));
+    addIds(uses.map(({ informationTypeId }) => informationTypeId));
+    const schedules = loaded.resources
+      .filter((record) => (
+        record.type === "document"
+        && record.documentKind === "schedule"
+        && record.workflowScope === "program"
+        && !["superseded", "retired"].includes(record.status)
+      ))
+    addIds(schedules.map(({ id }) => id));
+    for (const schedule of schedules) {
+      addPartyIds([...(schedule.ownerIds || []), ...(schedule.approverIds || [])]);
+    }
+    for (const record of reviewed) {
+      addIds([record.scheduleDocumentId]);
+      addIds(record.informationTypeIds);
+      addIds(record.scopeResourceIds);
+      addIds(record.sourceResourceIds);
+      addPartyIds([...(record.ownerIds || []), ...(record.approvedByIds || [])]);
+    }
+  }
   if (resourceType === "complementary-control") {
     addIds(program?.systemIds);
     addIds(program?.controlIds);
@@ -351,6 +379,21 @@ const dependencyFields = {
     component: ["id", "type", "status", "systemUses", "informationUses"],
     vendor: ["id", "type", "status", "informationTypeIds"]
   },
+  "retention-schedule-item": {
+    document: ["id", "type", "documentKind", "workflowScope", "ownerIds", "approverIds", "approvedOn", "approvedContentRevisions", "controlIds"],
+    policy: ["id", "type", "status", "programRole", "ownerIds", "approverIds", "approvedOn", "approvedContentRevisions", "controlIds"],
+    requirement: ["id", "type", "title", "frameworkId", "reference", "description"],
+    commitment: ["id", "type", "status", "commitmentKind", "statement", "effectiveOn"],
+    control: ["id", "type", "status", "statement", "systemIds", "componentIds"],
+    "information-type": ["id", "type", "status", "classificationId", "description"],
+    system: ["id", "type", "status", "informationTypeIds"],
+    component: ["id", "type", "status", "systemUses", "informationUses"],
+    vendor: ["id", "type", "status", "informationTypeIds"],
+    "source-coverage": ["id", "type", "status", "sourceFamilyId", "coverageKind", "scopeResourceIds", "retentionScheduleItemIds", "componentId"],
+    person: ["id", "type", "status", "affiliation", "jobTitle"],
+    team: ["id", "type", "status", "memberIds", "chairIds"],
+    appointment: ["id", "type", "status", "appointmentKind", "scopeResourceIds", "holderId", "startsOn", "endsOn"]
+  },
   "complementary-control": {
     system: ["id", "type", "status", "purpose", "servicesProvided", "boundary", "exclusions", "criticality", "informationTypeIds", "classificationId", "internetExposed", "continuityObjectives"],
     control: ["id", "type", "status", "statement", "activity", "systemIds", "componentIds", "evidenceSourceComponentIds"],
@@ -382,6 +425,7 @@ const dependencyContentTypes = {
   vendor: new Set(["document"]),
   component: new Set(["system"]),
   control: new Set(["system", "component", "obligation", "source-coverage", "evidence", "retention-schedule-item", "document", "policy", "training"]),
+  "retention-schedule-item": new Set(["document", "policy"]),
   "complementary-control": new Set(["system", "control", "document", "component"])
 };
 

package/src/program-path.js

@@ -1,3 +1,5 @@
+import { ACTIVE_MODEL_VERSION, modelSupports } from "../model/index.js";
+
 export const RESOURCE_INSTRUCTIONS = {
   program: "Define one management compliance or assurance Program with its goal, bounded Systems, selected Frameworks, Requirement applicability decisions, Controls, owners, risk method, and candidate period.",
   person: "Record each person’s actual organizational job title. Keep named program authority, such as CISO, DPO, Policy Owner, or team chair, in dated Appointment records.",
@@ -105,13 +107,14 @@ export const PROGRAM_PATH = [
     id: "policies",
     number: 2,
     title: "Approve Policies",
-    description: "Review governed content and approvals",
-    summary: "Review and independently approve Policies, program Documents, and Training content.",
+    description: "Approve governed content and retention decisions",
+    summary: "Review and independently approve Policies, program Documents, Training content, and the Data Retention Schedule.",
     sections: [
-      { id: "policy-content", title: "Policies", description: "Review every program Policy, Document, and Training record in one table, then bind independent approval to each exact revision.", steps: ["Review each governed Markdown artifact and replace every organization placeholder.", "Confirm the owner, separate approver, linked Controls, audience, and intended values that apply to each artifact.", "Record approval and its date against the exact revision. Leave approved content inactive until its Step 3 implementation cutover."], types: [], relatedLinks: [{ type: "policy", label: "Policies", href: "#/stage/policies" }], defaultOpen: true }
+      { id: "policy-content", title: "Policies", description: "Review every program Policy, Document, and Training record in one table, then bind independent approval to each exact revision.", steps: ["Review each governed Markdown artifact and replace every organization placeholder.", "Confirm the owner, separate approver, linked Controls, audience, and intended values that apply to each artifact.", "Record approval and its date against the exact revision. Leave approved content inactive until its Step 3 implementation cutover."], types: [], relatedLinks: [{ type: "policy", label: "Policies", href: "#/policies" }], defaultOpen: true },
+      { id: "retention", title: "Data Retention Schedule", description: "Approve the schedule document and its structured rows as one governed schedule.", steps: ["Review the schedule policy, legal holds, exceptions, and disposal requirements.", "Define rows only for Information Types and operational sources the organization actually uses.", "Confirm the complete document-and-row revision with one schedule review."], types: [], utility: "retention-schedule", defaultOpen: true }
     ],
     resourceTypes: [],
-    supportingResourceTypes: ["policy", "document", "training"],
+    supportingResourceTypes: ["policy", "document", "training", "retention-schedule-item"],
     commands: [
       "filegrc guide policy --json",
       "filegrc guide document --json",
@@ -119,30 +122,29 @@ export const PROGRAM_PATH = [
       "filegrc list policy --json",
       "filegrc list document --json",
       "filegrc list training --json",
-      "filegrc get POLICY_ID --mutation"
+      "filegrc get POLICY_ID --mutation",
+      "filegrc guide retention-schedule-item --json",
+      "filegrc review-collection retention-schedule-item --scaffold"
     ]
   },
   {
     id: "controls",
     number: 3,
     title: "Implement Controls",
-    description: "Finish controls and their evidence sources",
-    summary: "Describe each Control and connect its evidence source.",
+    description: "Implement and prepare to operate",
+    summary: "Implement Controls, configure their operating schedules and evidence sources, then activate the approved program.",
     sections: [
       { id: "controls", title: "Controls", description: "Implement the selected Controls and connect their scope, procedures, mappings, and operation patterns.", steps: ["Open every planned Control and confirm its mappings and operation pattern.", "Write the real procedure in Record Markdown, add bounded System scope, and map the operating and authoritative evidence-source Components."], types: ["control"], defaultOpen: true },
       { id: "complementary-controls", title: "Complementary Controls", description: "Record customer or provider responsibilities that form part of the implementation boundary, or confirm there are none.", steps: ["Review whether an in-scope Control depends on a customer or carved-out provider action."], types: ["complementary-control"], defaultOpen: true },
       { id: "evidence-sources", title: "Evidence Sources", description: "Check that every Control points to an authoritative source that can produce its expected evidence.", steps: ["Confirm each source Component is active, has the right evidence-source role, names current access owners, and includes repeatable retrieval instructions."], types: [], utility: "evidence-sources", defaultOpen: true },
-      { id: "retention", title: "Retention Schedule", description: "Review each retention rule against current information uses and approved sources.", steps: ["Confirm scope, cutoff, period, disposition, sources, owner, and approval for each rule."], types: ["retention-schedule-item"], defaultOpen: true },
       { id: "obligations", title: "Obligations", description: "Configure the calendar and event schedules that operate the Controls.", steps: ["Review and enable every required calendar and event schedule."], types: ["obligation"], defaultOpen: true }
     ],
-    resourceTypes: ["control", "complementary-control", "retention-schedule-item", "obligation"],
+    resourceTypes: ["control", "complementary-control", "obligation"],
     commands: [
       "filegrc guide control --json",
       "filegrc list control --json",
       "filegrc get CONTROL_ID --mutation",
       "filegrc guide obligation --json",
-      "filegrc guide retention-schedule-item --json",
-      "filegrc review-collection retention-schedule-item --scaffold",
       "filegrc list obligation --json",
       "filegrc review-collection component --scaffold",
       "filegrc review-collection complementary-control --scaffold",
@@ -264,8 +266,51 @@ export const PROGRAM_PATH = [
   }
 ];
 
-export function buildAgentProgramPath(model) {
+export function programPathForModel(model = ACTIVE_MODEL_VERSION) {
+  if (modelSupports(model, "retention-schedule-approval")) return PROGRAM_PATH;
   return PROGRAM_PATH.map((stage) => {
+    if (stage.id === "policies") {
+      return {
+        ...stage,
+        description: "Review governed content and approvals",
+        summary: "Review and independently approve Policies, program Documents, and Training content.",
+        sections: [{
+          ...stage.sections[0],
+          relatedLinks: [{ type: "policy", label: "Policies", href: "#/stage/policies" }]
+        }],
+        supportingResourceTypes: stage.supportingResourceTypes.filter((type) => type !== "retention-schedule-item"),
+        commands: stage.commands.filter((command) => !command.includes("retention-schedule-item"))
+      };
+    }
+    if (stage.id === "controls") {
+      const retention = {
+        id: "retention",
+        title: "Retention Schedule",
+        description: "Review each retention rule against current information uses and approved sources.",
+        steps: ["Confirm scope, cutoff, period, disposition, sources, owner, and approval for each rule."],
+        types: ["retention-schedule-item"],
+        defaultOpen: true
+      };
+      return {
+        ...stage,
+        description: "Finish controls and their evidence sources",
+        summary: "Describe each Control and connect its evidence source.",
+        sections: [...stage.sections.slice(0, 3), retention, ...stage.sections.slice(3)],
+        resourceTypes: [...stage.resourceTypes.slice(0, 2), "retention-schedule-item", ...stage.resourceTypes.slice(2)],
+        commands: [
+          ...stage.commands.slice(0, 5),
+          "filegrc guide retention-schedule-item --json",
+          "filegrc review-collection retention-schedule-item --scaffold",
+          ...stage.commands.slice(5)
+        ]
+      };
+    }
+    return stage;
+  });
+}
+
+export function buildAgentProgramPath(model) {
+  return programPathForModel(model).map((stage) => {
     const programResourceTypes = [...stage.resourceTypes, ...(stage.supportingResourceTypes || [])]
       .filter((type) => model.resources[type]);
     const resourcePages = programResourceTypes.map((type, index) => {
@@ -305,8 +350,8 @@ function agentCommand(command) {
   return command.startsWith("filegrc ") ? `npx ${command}` : command;
 }
 
-export function resourceProgramContext(type) {
-  const stage = PROGRAM_PATH.find((candidate) => (
+export function resourceProgramContext(type, model) {
+  const stage = programPathForModel(model).find((candidate) => (
     candidate.resourceTypes.includes(type) || (candidate.supportingResourceTypes || []).includes(type)
   ));
   if (!stage) return null;

package/src/program-readiness.js

@@ -57,12 +57,19 @@ export async function assessProgramReadiness(input, options = {}) {
     .map(collectionReviewReadinessItem));
   const sourceStage = await evidenceSourcesStage(scope, byId, loaded.model, readMarkdown);
   controlStage.items.push(...sourceStage.items);
-  controlStage.items.push(...await assessRetentionReadiness(loaded, program, {
+  const retentionItems = await assessRetentionReadiness(loaded, program, {
     informationTypesReviewed: collectionReviews.find(({ resourceType }) => resourceType === "information-type")?.complete === true
-  }));
-  controlStage.items.push(...collectionReviews
+  });
+  const retentionReviewItems = collectionReviews
     .filter(({ resourceType }) => resourceType === "retention-schedule-item")
-    .map(collectionReviewReadinessItem));
+    .map(collectionReviewReadinessItem);
+  if (modelSupports(loaded.model, "retention-schedule-approval")) {
+    policyStage.items.push(...retentionItems.filter(({ id }) => !id.startsWith("retention-source-coverage-")));
+    controlStage.items.push(...retentionItems.filter(({ id }) => id.startsWith("retention-source-coverage-")));
+    policyStage.items.push(...retentionReviewItems);
+  } else {
+    controlStage.items.push(...retentionItems, ...retentionReviewItems);
+  }
   const governedContent = await governedContentItems(scope, records, byId, readMarkdown, asOf, loaded.model);
   const policyActivations = await assessPolicyActivations(
     requiredPolicies(scope, byId),
@@ -900,6 +907,11 @@ function requiredGovernedDocuments(scope, records, byId, model) {
     && (
       linkedDocumentIds.has(record.id)
       || obligationDocumentIds.has(record.id)
+      || (
+        modelSupports(model, "retention-schedule-approval")
+        && record.documentKind === "schedule"
+        && record.workflowScope === "program"
+      )
       || (
         record.programRole === "required"
         && (record.controlIds || []).some((id) => selectedControlIds.has(id))

package/src/retention-schedule-approval.js

@@ -0,0 +1,121 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { openPlaceholderCount, substantiveMarkdown } from "./content-readiness.js";
+import { markdownEntries } from "./resource-markdown.js";
+import { resolveDataPath } from "./paths.js";
+import { currentPartyPeople, partiesIndependent } from "./parties.js";
+import {
+  nearDuplicateInformationTypes,
+  resourceReviewRevisionsSync,
+  retentionReviewResourceIds,
+  retentionRuleIsCurrent,
+  retentionUses
+} from "./retention.js";
+
+export function retentionScheduleApprovalIssues(loaded, program, rows, options = {}) {
+  const byId = new Map(loaded.resources.map((record) => [record.id, record]));
+  const issues = [];
+  const planned = rows.filter(({ status }) => status === "planned");
+  if (planned.length) {
+    issues.push(issue("planned-retention-schedule-row", `Complete or retire every planned retention row before approving the schedule revision: ${planned[0].title}.`));
+  }
+  const schedules = loaded.resources.filter((record) => (
+    record.type === "document"
+    && record.documentKind === "schedule"
+    && record.workflowScope === "program"
+    && !["superseded", "retired"].includes(record.status)
+  ));
+  if (!schedules.length) {
+    issues.push(issue("missing-retention-schedule-document", "Add and approve the Data Retention Schedule document before approving the schedule revision."));
+  }
+  if (schedules.length !== 1) {
+    if (schedules.length) {
+      issues.push(issue("multiple-retention-schedule-documents", "Keep exactly one current program Data Retention Schedule document before approving the schedule revision."));
+    }
+  }
+  const schedule = schedules.length === 1 ? schedules[0] : null;
+  const scheduleContent = schedule ? primaryMarkdown(loaded, schedule) : "";
+  const linkedControl = schedule && (schedule.controlIds || []).some((id) => (program.controlIds || []).includes(id));
+  if (
+    schedule
+    && (!["approved", "active"].includes(schedule.status)
+    || !schedule.approvedOn
+    || !schedule.approvedContentRevisions
+    || currentPartyPeople(schedule.ownerIds || [], byId).size === 0
+    || !partiesIndependent(schedule.ownerIds, schedule.approverIds, byId)
+    || !linkedControl
+    || !substantiveMarkdown(scheduleContent)
+    || openPlaceholderCount(scheduleContent) > 0
+    || !approvalBindingsMatch(loaded, schedule))
+  ) {
+    issues.push(issue("unapproved-retention-schedule-document", "Complete and independently approve the Data Retention Schedule document before approving the complete schedule."));
+  }
+  const activeRows = rows.filter(({ status }) => status === "active");
+  const mismatched = schedule
+    ? activeRows.filter(({ scheduleDocumentId }) => scheduleDocumentId !== schedule.id)
+    : [];
+  if (mismatched.length) {
+    issues.push(issue("retention-row-wrong-schedule-document", `Link every active retention row to the current Data Retention Schedule document before approval: ${mismatched[0].title}.`));
+  }
+  const revisions = resourceReviewRevisionsSync(
+    loaded,
+    activeRows.flatMap((row) => retentionReviewResourceIds(row, loaded))
+  );
+  const incomplete = activeRows.filter((row) => !retentionRuleIsCurrent(row, revisions, byId, loaded));
+  if (incomplete.length) {
+    issues.push(issue("incomplete-retention-schedule-row", `Complete the retention decisions before approving the schedule revision: ${incomplete[0].title}.`));
+  }
+  const usableRows = activeRows.filter((row) => !incomplete.includes(row));
+  const uncovered = retentionUses(loaded, program).find((use) => !usableRows.some((row) => (
+    (row.informationTypeIds || []).includes(use.informationTypeId)
+    && ((row.scopeResourceIds || []).includes(use.resource.id) || (row.scopeResourceIds || []).includes(program.id))
+  )));
+  if (uncovered) {
+    issues.push(issue(
+      "uncovered-retention-information-use",
+      `${uncovered.resource.title} uses ${byId.get(uncovered.informationTypeId)?.title || uncovered.informationTypeId}, but no active, current retention schedule row covers both the type and scope.`
+    ));
+  }
+  if (nearDuplicateInformationTypes(loaded.resources).length && !options.informationTypesReviewed) {
+    issues.push(issue("unreviewed-similar-information-types", "Review similar Information Types before approving the Data Retention Schedule."));
+  }
+  return issues;
+}
+
+function issue(code, message) {
+  return { code, message };
+}
+
+function primaryMarkdown(loaded, record) {
+  const definition = loaded.model.resources[record.type];
+  const selected = markdownEntries(loaded.model, record).find((entry) => (
+    definition.markdown?.[entry.name]?.primary || entry.name === loaded.model.recordContent?.slot
+  ));
+  if (!selected) return "";
+  try {
+    return readFileSync(resolveDataPath(loaded.root, selected.path), "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function approvalBindingsMatch(loaded, record) {
+  const actual = {};
+  for (const entry of markdownEntries(loaded.model, record)) {
+    try {
+      actual[entry.path] = createHash("sha256")
+        .update(readFileSync(resolveDataPath(loaded.root, entry.path), "utf8"))
+        .digest("hex");
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  const expected = record.approvedContentRevisions || {};
+  const actualKeys = Object.keys(actual).sort();
+  const expectedKeys = Object.keys(expected).sort();
+  return actualKeys.length === expectedKeys.length
+    && actualKeys.every((key, index) => (
+      key === expectedKeys[index]
+      && actual[key] === expected[key]
+    ));
+}

package/src/retention.js

@@ -1,8 +1,10 @@
+import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { contentRevision } from "./files.js";
 import { resolveDataPath } from "./paths.js";
 import { programComponents } from "./program.js";
 import { markdownEntries } from "./resource-markdown.js";
+import { modelSupports } from "../model/index.js";
 
 export async function assessRetentionReadiness(loaded, program, options = {}) {
   if (!loaded.model.resources["retention-schedule-item"]) return [];
@@ -113,7 +115,7 @@ export async function resourceReviewRevisions(loaded, ids) {
     const entry = entries.get(id);
     if (!entry || reviewing.has(id)) return null;
     reviewing.add(id);
-    const parts = [entry.source];
+    const parts = [reviewSource(loaded, entry)];
     for (const markdown of markdownEntries(loaded.model, entry.record)) {
       try {
         parts.push(await readFile(resolveDataPath(loaded.root, markdown.path), "utf8"));
@@ -136,6 +138,37 @@ export async function resourceReviewRevisions(loaded, ids) {
   return new Map([...revisions].filter(([id]) => wanted.has(id)));
 }
 
+export function resourceReviewRevisionsSync(loaded, ids) {
+  const wanted = new Set(ids);
+  const entries = new Map(loaded.entries.map((entry) => [entry.record.id, entry]));
+  const revisions = new Map();
+  const reviewing = new Set();
+  const review = (id) => {
+    if (revisions.has(id)) return revisions.get(id);
+    const entry = entries.get(id);
+    if (!entry || reviewing.has(id)) return null;
+    reviewing.add(id);
+    const parts = [reviewSource(loaded, entry)];
+    for (const markdown of markdownEntries(loaded.model, entry.record)) {
+      try {
+        parts.push(readFileSync(resolveDataPath(loaded.root, markdown.path), "utf8"));
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+    for (const sourceId of [...new Set(entry.record.sourceResourceIds || [])].sort()) {
+      const revision = review(sourceId);
+      if (revision) parts.push(`${sourceId}:${revision}`);
+    }
+    reviewing.delete(id);
+    const revision = contentRevision(parts.join("\n"));
+    revisions.set(id, revision);
+    return revision;
+  };
+  for (const id of wanted) review(id);
+  return new Map([...revisions].filter(([id]) => wanted.has(id)));
+}
+
 export function retentionUses(loaded, program) {
   const systemIds = new Set(program.systemIds || []);
   const componentIds = new Set(programComponents(loaded, program).map(({ id }) => id));
@@ -157,6 +190,28 @@ export function retentionUses(loaded, program) {
   return [...new Map(uses.map((use) => [`${use.resource.id}:${use.informationTypeId}`, use])).values()];
 }
 
+function reviewSource(loaded, entry) {
+  if (
+    modelSupports(loaded.model, "retention-schedule-approval")
+    && entry.record.type === "document"
+    && entry.record.documentKind === "schedule"
+    && entry.record.workflowScope === "program"
+  ) {
+    const approved = structuredClone(entry.record);
+    if (approved.status === "active") approved.status = "approved";
+    for (const field of [
+      "activationBasis",
+      "activatedByIds",
+      "activatedOn",
+      "activatedContentRevisions",
+      "effectiveOn",
+      "proposedEffectiveOn"
+    ]) delete approved[field];
+    return JSON.stringify(approved);
+  }
+  return entry.source;
+}
+
 export function nearDuplicateInformationTypes(records) {
   const types = records.filter((record) => record.type === "information-type" && !["retired", "superseded"].includes(record.status));
   const pairs = [];