filegrc 0.7.1 → 0.8.0

package/src/server.js

@@ -5,6 +5,7 @@ import { extname, join, resolve } from "node:path";
 import { performance } from "node:perf_hooks";
 import { getResourceDefinition } from "../model/index.js";
 import { prepareAuditWorkspace } from "./audit-preparation.js";
+import { activateDocuments } from "./document-activation.js";
 import { createNextAuditCycle, planNextAuditCycle } from "./audit-transition.js";
 import { applyApplicabilityReviewWithContext, planApplicabilityReview } from "./batch-review.js";
 import { applyCollectionReview, planCollectionReview } from "./collection-review.js";
@@ -330,6 +331,13 @@ export function createFilegrcServer(input = process.cwd(), options = {}) {
         }, () => activatePolicies(input, { ...payload, confirmed: true }));
         return json(response, 200, result);
       }
+      if (request.method === "POST" && url.pathname === "/api/document-activations") {
+        const payload = await readJson(request);
+        const result = await browserMutation(input, options, {
+          message: (activation) => `Activate ${activation.documentIds.length} governed ${activation.documentIds.length === 1 ? "Document" : "Documents"}`
+        }, () => activateDocuments(input, { ...payload, confirmed: true }));
+        return json(response, 200, result);
+      }
       if (request.method === "POST" && url.pathname === "/api/resources") {
         const payload = normalizeResourceMutation(await readJson(request));
         const { record } = payload;
@@ -543,13 +551,8 @@ function browserMutation(input, options, mutationOptions, task) {
       includeDetails: false,
       validationProof: result?.[BROWSER_VALIDATION]
     }));
-    if (result?.synchronization?.status === "syncing" && state.repository.status !== "syncing") {
-      result.synchronization = {
-        ...result.synchronization,
-        status: state.repository.status === "synced" ? "synced" : "not-synced",
-        synchronizedAt: state.repository.lastSuccessfulSynchronization ?? null,
-        pushError: state.repository.backgroundSyncError ?? null
-      };
+    if (result?.synchronization) {
+      result.synchronization = reconcileMutationSynchronization(result.synchronization, state.repository);
     }
     return {
       ...result,
@@ -564,6 +567,25 @@ function browserMutation(input, options, mutationOptions, task) {
   });
 }
 
+export function reconcileMutationSynchronization(synchronization, repository) {
+  if (synchronization?.status !== "syncing" || repository.status === "syncing") return synchronization;
+  const backgroundFailed = repository.backgroundSynchronization?.status === "failed";
+  if (repository.status !== "synced" && !backgroundFailed) {
+    // A repository snapshot can finish just before a fast background push while
+    // its state is inspected just after the push. Keep the queued result until
+    // a verified success or failure replaces it.
+    return synchronization;
+  }
+  return {
+    ...synchronization,
+    status: repository.status === "synced" ? "synced" : "not-synced",
+    synchronizedAt: repository.lastSuccessfulSynchronization ?? null,
+    pushError: repository.backgroundSyncError
+      ?? repository.backgroundSynchronization?.error
+      ?? null
+  };
+}
+
 function prefersFastMutation(request) {
   return String(request.headers.prefer || "")
     .split(",")

package/src/setup.js

@@ -1,3 +1,4 @@
+import { modelSupports } from "../model/index.js";
 import { applyResourceBatch } from "./files.js";
 import { createResourceId } from "./id.js";
 import { resolveProgram, selectedRequirementIds } from "./program.js";
@@ -79,7 +80,9 @@ export function summarizeSetupResult(result) {
       commitment: result.commitment ? "saved" : "unchanged"
     },
     system: setupSystemSummary(result.system),
-    target: setupTargetSummary(result.program || result.workspace, { modelVersion: result.program ? "4" : "3" }),
+    target: setupTargetSummary(result.program || result.workspace, {
+      modelVersion: result.workspace?.dataModelVersion || (result.program ? "5" : "3")
+    }),
     renderer: result.renderer ? setupRendererSummary(result.renderer) : null,
     commitment: result.commitment || null,
     onboardingComplete: result.onboardingComplete
@@ -131,7 +134,7 @@ function validateSetup(loaded, setup) {
       throw new Error(`System "${setup.systemId}" cannot be used for initial scope because it is ${system.status}.`);
     }
   }
-  const classifications = String(loaded.model.modelVersion) === "4"
+  const classifications = modelSupports(loaded.model, "program-scope")
     ? loaded.resources.filter(({ type, status }) => type === "classification" && status === "active").map(({ id }) => id)
     : Object.keys(loaded.workspace.classificationDefinitions || {});
   if (classifications.length && !classifications.includes(setup.classificationId)) {
@@ -142,7 +145,7 @@ function validateSetup(loaded, setup) {
 function resolveClassificationId(loaded, value) {
   const normalized = String(value || "").trim().toLowerCase();
   if (!normalized) return value;
-  const candidates = String(loaded.model.modelVersion) === "4"
+  const candidates = modelSupports(loaded.model, "program-scope")
     ? loaded.resources
       .filter(({ type, status }) => type === "classification" && status === "active")
       .map(({ id, title }) => ({ id, label: title }))
@@ -167,7 +170,7 @@ function findSetupSystem(resources, target, setup) {
 
 function buildSetupRecords(loaded, setup) {
   const target = resolveProgram(loaded);
-  const v4 = String(loaded.model.modelVersion) === "4";
+  const v4 = modelSupports(loaded.model, "program-scope");
   const existingSystem = findSetupSystem(loaded.resources, target, setup);
   const systemId = existingSystem?.id || createResourceId(
     "system",
@@ -233,7 +236,7 @@ function buildSetupRecords(loaded, setup) {
     && !["superseded", "retired"].includes(record.status)
     && (record.systemIds || []).includes(systemId)
   ));
-  const commitment = ["3", "4"].includes(String(loaded.model.modelVersion)) && !existingCommitment
+  const commitment = modelSupports(loaded.model, "guided-workflow") && !existingCommitment
     ? {
         id: createResourceId(
           "commitment",

package/src/soc2.js

@@ -1,3 +1,4 @@
+import { modelSupports } from "../model/index.js";
 import { coverageEnd, coverageStart } from "./coverage.js";
 
 export const REQUIRED_SOC2_DESCRIPTION_REFERENCES = Array.from(
@@ -49,7 +50,7 @@ const SOC2_PROGRAM_GOALS = new Set([
 
 export function soc2RequirementApplicabilityConstraint(requirement, program, modelVersion = "4") {
   if (
-    String(modelVersion) !== "4"
+    !modelSupports(modelVersion, "program-scope")
     || requirement?.type !== "requirement"
     || !SOC2_PROGRAM_GOALS.has(program?.assuranceGoal)
   ) return null;
@@ -171,7 +172,7 @@ export function soc2ReportEvidenceIssue(evidence, audit, modelVersion = "4") {
       message: `${evidence?.title || audit?.title || "The audit"} must be verified third-party-report Evidence with subtype soc2-report for the issued SOC 2 report.`
     };
   }
-  const issuedOn = (String(modelVersion) === "4"
+  const issuedOn = (modelSupports(modelVersion, "program-scope")
     ? evidence.sourceGeneratedAt
     : evidence.sourceGeneratedAt || evidence.businessEventAt || evidence.collectedOn
   )?.slice(0, 10);

package/src/validate.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import { performance } from "node:perf_hooks";
-import { getResourceDefinition } from "../model/index.js";
+import { getResourceDefinition, modelSupports } from "../model/index.js";
 import { scopedCollectionRecords } from "./collection-scope.js";
 import { collectionRevision } from "./collection-revision.js";
 import { isSafeGitName } from "./git-name.js";
@@ -12,6 +12,7 @@ import { partyPeople } from "./parties.js";
 import { isMarkdownChoice, markdownEntries } from "./resource-markdown.js";
 import { currentCalendarDate, isRfc3339Timestamp } from "./time.js";
 import { recordTiming } from "./timing.js";
+import { personWasActiveOn } from "./soc2.js";
 import { indexResources, loadWorkspace } from "./workspace.js";
 
 const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -147,6 +148,9 @@ async function validateWorkspaceUnmeasured(input) {
     pathById,
     diagnostics
   );
+  if (modelSupports(loaded.model, "document-workflow-scope")) {
+    validateDocumentWorkflowScopes(loaded.resources, loaded.model, byId, pathById, diagnostics);
+  }
 
   diagnostics.sort((a, b) => `${a.severity}:${a.path}:${a.code}`.localeCompare(`${b.severity}:${b.path}:${b.code}`));
   return {
@@ -161,6 +165,116 @@ async function validateWorkspaceUnmeasured(input) {
   };
 }
 
+function validateDocumentWorkflowScopes(resources, model, byId, pathById, diagnostics) {
+  const managementFields = [
+    "engagementTermsDocumentId",
+    ...(model.auditReadiness?.managementDocuments || []).map(({ field }) => field)
+  ];
+  const auditReferences = new Map();
+  const governedAuditReferences = new Map();
+  const addAuditReference = (map, documentId, audit, field) => {
+    if (!documentId) return;
+    if (!map.has(documentId)) map.set(documentId, []);
+    map.get(documentId).push({ audit, field });
+  };
+  for (const audit of resources.filter(({ type }) => type === "audit")) {
+    for (const field of managementFields) {
+      const documentId = audit[field];
+      if (!documentId) continue;
+      addAuditReference(auditReferences, documentId, audit, field);
+      addAuditReference(governedAuditReferences, documentId, audit, field);
+      const document = byId.get(documentId);
+      if (document?.type === "document" && document.workflowScope !== "engagement") {
+        diagnostics.push(error(
+          "invalid-document-workflow-scope",
+          pathById.get(audit.id) || `data/${audit.id}`,
+          `${field} must reference an engagement-scoped Document; "${document.title}" is scoped to the program workflow.`
+        ));
+      }
+    }
+    for (const documentId of audit.supplementalDocumentIds || []) {
+      addAuditReference(auditReferences, documentId, audit, "supplementalDocumentIds");
+    }
+  }
+
+  const programDocumentReferences = new Map();
+  const addProgramReference = (documentId, record, field) => {
+    if (!documentId) return;
+    if (!programDocumentReferences.has(documentId)) programDocumentReferences.set(documentId, []);
+    programDocumentReferences.get(documentId).push({ record, field });
+  };
+  for (const policy of resources.filter(({ type }) => type === "policy")) {
+    for (const documentId of policy.relatedDocumentIds || []) addProgramReference(documentId, policy, "relatedDocumentIds");
+  }
+  for (const obligation of resources.filter(({ type }) => type === "obligation")) {
+    for (const documentId of obligation.scopeResourceIds || []) {
+      if (byId.get(documentId)?.type === "document") addProgramReference(documentId, obligation, "scopeResourceIds");
+    }
+    if (byId.get(obligation.templateResourceId)?.type === "document") {
+      addProgramReference(obligation.templateResourceId, obligation, "templateResourceId");
+    }
+  }
+
+  for (const document of resources.filter(({ type }) => type === "document")) {
+    const path = pathById.get(document.id) || `data/${document.id}`;
+    const auditRefs = auditReferences.get(document.id) || [];
+    const auditIds = new Set(auditRefs.map(({ audit }) => audit.id));
+    const programRefs = programDocumentReferences.get(document.id) || [];
+    if (document.workflowScope === "engagement" && programRefs.length) {
+      const references = programRefs.map(({ record, field }) => `${record.id}.${field}`).join(", ");
+      diagnostics.push(error(
+        "engagement-document-in-program-workflow",
+        path,
+        `Engagement-scoped Document "${document.title}" cannot govern reusable program work through ${references}. Split the engagement deliverable from the program Document.`
+      ));
+    }
+    if (
+      document.workflowScope === "engagement"
+      && ["approved", "active"].includes(document.status)
+      && auditIds.size !== 1
+    ) {
+      diagnostics.push(error(
+        "invalid-engagement-document-audit-count",
+        path,
+        `Approved or active engagement Document "${document.title}" must belong to exactly one Audit; found ${auditIds.size}.`
+      ));
+    }
+    if (document.workflowScope === "program" && (governedAuditReferences.get(document.id) || []).length) {
+      diagnostics.push(error(
+        "program-document-in-engagement-workflow",
+        path,
+        `Program-scoped Document "${document.title}" cannot fill an Audit engagement or management-Document field.`
+      ));
+    }
+    if (document.activationBasis !== "legacy-v4") continue;
+    const historicalAuditIds = new Set(auditRefs
+      .filter(({ audit }) => ["issued", "delivered", "complete"].includes(audit.status))
+      .map(({ audit }) => audit.id));
+    if (document.workflowScope !== "engagement" || historicalAuditIds.size !== 1 || auditIds.size !== 1) {
+      diagnostics.push(error(
+        "invalid-legacy-document-activation",
+        path,
+        `activationBasis legacy-v4 is reserved for an engagement Document tied to exactly one issued, delivered, or completed Audit.`
+      ));
+    }
+  }
+
+  for (const document of resources.filter(({ type, activationBasis }) => (
+    type === "document" && activationBasis === "recorded"
+  ))) {
+    const invalidActorIds = (document.activatedByIds || []).filter((id) => (
+      !personWasActiveOn(byId.get(id), document.activatedOn)
+    ));
+    if (invalidActorIds.length) {
+      diagnostics.push(error(
+        "invalid-document-activation-actor",
+        pathById.get(document.id) || `data/${document.id}`,
+        `Document activation actors must have been active on ${document.activatedOn}: ${invalidActorIds.join(", ")}.`
+      ));
+    }
+  }
+}
+
 function validateCollectionReview(record, loaded, byId, path, diagnostics) {
   if (record.status !== "active") return;
   const { model } = loaded;
@@ -175,7 +289,7 @@ function validateCollectionReview(record, loaded, byId, path, diagnostics) {
     ));
     return;
   }
-  const program = String(model.modelVersion) === "4"
+  const program = modelSupports(model, "program-scope")
     ? (record.scopeResourceIds || []).map((id) => byId.get(id)).find(({ type } = {}) => type === "program")
     : null;
   const recordCount = scopedCollectionRecords(loaded, record.resourceType, program).length;
@@ -208,7 +322,7 @@ function validateCollectionReview(record, loaded, byId, path, diagnostics) {
     diagnostics.push(error(
       "inactive-authoritative-system",
       path,
-      `${configuration.title} must name an active authoritative ${String(model.modelVersion) === "4" ? "Component" : "System"} for an externally managed conclusion.`
+      `${configuration.title} must name an active authoritative ${modelSupports(model, "component-sources") ? "Component" : "System"} for an externally managed conclusion.`
     ));
   }
 }
@@ -436,7 +550,7 @@ function validateCompletedObligationEvent(record, byId, model, path, diagnostics
       ? model.obligationActivities?.[obligation.activityType]?.completionResourceTypes || []
       : [];
     if (!expectedTypes.length) continue;
-    const completionIds = ["3", "4"].includes(String(model.modelVersion))
+    const completionIds = modelSupports(model, "guided-workflow")
       ? action.completionResourceIds || []
       : [...(action.completionResourceIds || []), ...(action.evidenceIds || [])];
     const linked = [...new Set(completionIds)]
@@ -454,7 +568,7 @@ function validateCompletedObligationEvent(record, byId, model, path, diagnostics
 
 function validateCompletedObligationAction(record, byId, model, path, diagnostics) {
   if (
-    !["3", "4"].includes(String(model.modelVersion))
+    !modelSupports(model, "guided-workflow")
     || record.status !== "done"
     || !record.obligationId
   ) return;
@@ -672,6 +786,9 @@ function validateCompletionDates(record, path, diagnostics) {
   ]);
   validateOrderedDates(record, path, diagnostics, ["startedAt", "endedAt"]);
   validateOrderedDates(record, path, diagnostics, ["fieldworkStart", "fieldworkEnd", "reportDate"]);
+  if (record.type === "document") {
+    validateOrderedDates(record, path, diagnostics, ["approvedOn", "activatedOn", "effectiveOn"]);
+  }
   if (record.acceptance) {
     validateOrderedDates(record.acceptance, path, diagnostics, ["acceptedOn", "expiresOn"], "acceptance.");
   }
@@ -766,8 +883,15 @@ async function validateAttestationBinding(record, model, root, byId, path, diagn
 }
 
 async function validateApprovalBinding(record, model, root, path, diagnostics) {
-  const bindingField = approvalBindingField(record, model);
-  if (!bindingField || !approvalBound(record) || !record[bindingField]) return;
+  const bindingFields = contentBindingFields(record, model);
+  for (const binding of bindingFields) {
+    await validateContentBinding(record, model, root, path, diagnostics, binding);
+  }
+}
+
+async function validateContentBinding(record, model, root, path, diagnostics, binding) {
+  const { field: bindingField, bound, label } = binding;
+  if (!bound(record) || !record[bindingField]) return;
   const actual = {};
   for (const item of markdownEntries(model, record)) {
     try {
@@ -787,24 +911,34 @@ async function validateApprovalBinding(record, model, root, path, diagnostics) {
     diagnostics.push(error(
       "approval-content-changed",
       path,
-      `Approved content no longer matches ${invalid.map((item) => `data/${item}`).join(", ")}. Move the record to draft or in-review, review the change, then approve it again.`
+      `${label} content no longer matches ${invalid.map((item) => `data/${item}`).join(", ")}. Move the record to draft or in-review, review the change, then approve and activate it again.`
     ));
   }
 }
 
 function approvalBound(record) {
   if (record.type === "policy") return ["approved", "active", "superseded", "retired"].includes(record.status);
-  if (record.type === "document") return ["active", "superseded", "retired"].includes(record.status);
+  if (record.type === "document") return ["approved", "active", "superseded", "retired"].includes(record.status);
   if (record.type === "training") return ["active", "retired"].includes(record.status);
   return false;
 }
 
-function approvalBindingField(record, model) {
-  if (["policy", "document"].includes(record.type)) return "approvedContentRevisions";
+function contentBindingFields(record, model) {
+  const fields = [];
+  if (["policy", "document"].includes(record.type)) {
+    fields.push({ field: "approvedContentRevisions", bound: approvalBound, label: "Approved" });
+  }
+  if (record.type === "document" && model.resources.document?.fields?.activatedContentRevisions) {
+    fields.push({
+      field: "activatedContentRevisions",
+      bound: (candidate) => ["active", "superseded", "retired"].includes(candidate?.status),
+      label: "Activated"
+    });
+  }
   if (record.type === "training" && model.resources.training?.fields?.effectiveContentRevisions) {
-    return "effectiveContentRevisions";
+    fields.push({ field: "effectiveContentRevisions", bound: approvalBound, label: "Approved" });
   }
-  return null;
+  return fields;
 }
 
 function validateCoverage(record, path, diagnostics) {
@@ -858,7 +992,7 @@ function validateCoverage(record, path, diagnostics) {
 
 function validateClassification(record, loaded, path, diagnostics) {
   if (!record.classificationId) return;
-  if (String(loaded.model.modelVersion) === "4") {
+  if (modelSupports(loaded.model, "program-scope")) {
     if (!loaded.resources.some(({ id, type }) => id === record.classificationId && type === "classification")) {
       diagnostics.push(error(
         "unknown-classification",