filegrc 0.7.1 → 0.9.0

package/src/files.js

@@ -1,10 +1,11 @@
 import { createHash, randomUUID } from "node:crypto";
 import { constants, link, lstat, mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
-import { getResourceDefinition, loadModel } from "../model/index.js";
+import { getResourceDefinition, loadModel, modelSupports } from "../model/index.js";
 import { openPlaceholderCount } from "./content-readiness.js";
 import { serializeWorkspaceMutation, workspaceValidationDeferred } from "./mutation.js";
 import { isCanonicalDataPath, resolveDataPath, resolveWorkspaceRoot } from "./paths.js";
+import { documentIsAuditSpecific } from "./program-lifecycle.js";
 import { markdownEntries } from "./resource-markdown.js";
 import { measureTiming } from "./timing.js";
 import { loadWorkspace } from "./workspace.js";
@@ -204,7 +205,25 @@ export async function applyResourceBatch(input, changes) {
   return serializeWorkspaceMutation(input, (root) => applyResourceBatchUnlocked(root, changes));
 }
 
-async function applyResourceBatchUnlocked(input, changes = {}) {
+export async function applyDocumentActivationBatch(input, changes) {
+  return serializeWorkspaceMutation(input, (root) => (
+    applyResourceBatchUnlocked(root, changes, "document-activation")
+  ));
+}
+
+export async function applyGovernedContentActivationBatch(input, changes) {
+  return serializeWorkspaceMutation(input, (root) => (
+    applyResourceBatchUnlocked(root, changes, "governed-content-activation")
+  ));
+}
+
+export async function applyModelMigrationBatch(input, changes) {
+  return serializeWorkspaceMutation(input, (root) => (
+    applyResourceBatchUnlocked(root, changes, "model-migration")
+  ));
+}
+
+async function applyResourceBatchUnlocked(input, changes = {}, lifecycleOperation = null) {
   const creates = changes.create || [];
   const updates = changes.update || [];
   const moves = changes.movePaths || [];
@@ -253,12 +272,31 @@ async function applyResourceBatchUnlocked(input, changes = {}) {
       "A cross-model resource batch must validate the whole workspace and update its dataModelVersion to the target model."
     );
   }
+  if (lifecycleOperation === "model-migration" && !targetModelVersion) {
+    throw new Error("The model-migration lifecycle operation requires a cross-model resource batch.");
+  }
+  if (
+    ["document-activation", "governed-content-activation"].includes(lifecycleOperation)
+    && (targetModelVersion || changes.validateWholeWorkspace !== true)
+  ) {
+    throw new Error("The governed-content activation lifecycle operation requires same-model whole-workspace validation.");
+  }
   const writeModel = targetModelVersion ? loadModel(targetModelVersion) : loaded.model;
   const deferValidation = workspaceValidationDeferred();
   const before = deferValidation || changes.validateWholeWorkspace
     ? null
     : await validateWorkspace(loaded);
   const existingById = new Map(loaded.entries.map((entry) => [entry.record.id, entry]));
+  for (const record of updates) {
+    if (!record || Array.isArray(record) || typeof record !== "object" || typeof record.id !== "string") continue;
+    const existing = existingById.get(record.id);
+    if (!existing) continue;
+    assertRevision(
+      existing.source,
+      expectedRevisions[record.id] || existing.revision,
+      `Resource "${record.id}"`
+    );
+  }
   const ids = new Set();
   const writes = [];
   const contentWrites = [];
@@ -315,13 +353,14 @@ async function applyResourceBatchUnlocked(input, changes = {}) {
     const nextRecord = hasContentUpdate
       ? await prepareApprovalBinding(loaded, record, recordContentWrites, existing.record)
       : record;
+    assertGovernedContentLifecycleMutation(existing.record, nextRecord, loaded.model, lifecycleOperation);
     writes.push({ operation: path === previousPath ? "update" : "move-update", path, previousPath, record: nextRecord, previous, fileMode: mode });
   }
   for (const resourceId of Object.keys(contentUpdates)) {
     if (preparedContentIds.has(resourceId)) continue;
     const existing = existingById.get(resourceId);
     if (!existing) throw new Error(`Resource "${resourceId}" was not found.`);
-    if (approvalBound(existing.record)) {
+    if (approvalBound(existing.record, loaded.model)) {
       throw new Error(`Batch content for approved or active resource "${resourceId}" needs a matching resource update and validation of its approval binding.`);
     }
     contentWrites.push(...await prepareContentWrites(loaded, existing.record, contentUpdates[resourceId], {
@@ -574,6 +613,7 @@ async function updateResourceUnlocked(input, type, id, record, options) {
   });
   const existing = loaded.entries.find(({ record: candidate }) => candidate.id === id)?.record;
   const nextRecord = await prepareApprovalBinding(loaded, record, contentWrites, existing);
+  assertGovernedContentLifecycleMutation(existing, nextRecord, loaded.model, null);
   try {
     for (const item of contentWrites) await writeTextAtomic(item.path, item.source);
     await writeAtomic(path, nextRecord);
@@ -783,39 +823,105 @@ async function prepareApprovalBinding(loaded, record, contentWrites, previousRec
   if (record.type === "attestation") {
     return prepareAttestationBinding(loaded, record, previousRecord);
   }
-  const bindingField = approvalBindingField(record, loaded.model);
-  if (!bindingField) return record;
-  const nextRecord = structuredClone(record);
-  if (!approvalBound(record)) {
-    delete nextRecord[bindingField];
-    return nextRecord;
-  }
-  if (approvalBound(previousRecord) && previousRecord[bindingField]) {
-    nextRecord[bindingField] = structuredClone(previousRecord[bindingField]);
-    return nextRecord;
+  const bindingFields = contentBindingFields(record, loaded.model);
+  if (!bindingFields.length) return record;
+  if (
+    (
+      record.type === "document" && modelSupports(loaded.model, "governed-document-activation")
+      || record.type === "training" && modelSupports(loaded.model, "governed-training-activation")
+    )
+    && record.status === "active"
+    && previousRecord?.status !== "active"
+  ) {
+    const step = record.type === "document" && documentIsAuditSpecific(record, loaded.model) ? "Step 5" : "Step 3";
+    const title = getResourceDefinition(loaded.model, record.type).title;
+    throw new Error(`${title} "${record.id}" must use the dedicated ${step} ${title} activation operation after approval.`);
   }
+  const nextRecord = structuredClone(record);
   const proposed = new Map(contentWrites.map((item) => [item.dataRelativePath, item.source]));
-  const revisions = {};
-  for (const item of markdownEntries(loaded.model, nextRecord)) {
-    let source = proposed.get(item.path);
-    if (source === undefined) {
-      try {
-        source = await readFile(resolveDataPath(loaded.root, item.path), "utf8");
-      } catch (error) {
-        if (error.code === "ENOENT") continue;
-        throw error;
-      }
+  for (const { field, bound, label } of bindingFields) {
+    if (!bound(record)) {
+      delete nextRecord[field];
+      continue;
+    }
+    if (bound(previousRecord) && previousRecord[field]) {
+      nextRecord[field] = structuredClone(previousRecord[field]);
+      continue;
     }
-    const placeholders = openPlaceholderCount(source);
-    if (placeholders) {
-      throw new Error(`Cannot approve or activate ${record.title} while its ${item.label} Markdown contains ${placeholders} open ${placeholders === 1 ? "placeholder" : "placeholders"}. Complete the facts and review the exact content first.`);
+    const revisions = {};
+    for (const item of markdownEntries(loaded.model, nextRecord)) {
+      let source = proposed.get(item.path);
+      if (source === undefined) {
+        try {
+          source = await readFile(resolveDataPath(loaded.root, item.path), "utf8");
+        } catch (error) {
+          if (error.code === "ENOENT") continue;
+          throw error;
+        }
+      }
+      const placeholders = openPlaceholderCount(source);
+      if (placeholders) {
+        throw new Error(`Cannot ${label} ${record.title} while its ${item.label} Markdown contains ${placeholders} open ${placeholders === 1 ? "placeholder" : "placeholders"}. Complete the facts and review the exact content first.`);
+      }
+      revisions[item.path] = contentRevision(source);
     }
-    revisions[item.path] = contentRevision(source);
+    nextRecord[field] = revisions;
   }
-  nextRecord[bindingField] = revisions;
   return nextRecord;
 }
 
+function assertGovernedContentLifecycleMutation(previousRecord, nextRecord, model, lifecycleOperation) {
+  if (lifecycleOperation === "model-migration") return;
+  const governedTraining = previousRecord?.type === "training"
+    && nextRecord?.type === "training"
+    && modelSupports(model, "governed-training-activation");
+  const governedDocument = previousRecord?.type === "document"
+    && nextRecord?.type === "document"
+    && modelSupports(model, "governed-document-activation");
+  if (
+    !previousRecord
+    || (!governedDocument && !governedTraining)
+  ) return;
+  const title = getResourceDefinition(model, nextRecord.type).title;
+  const approvedStatuses = new Set(["approved", "active", "superseded", "retired"]);
+  const activatedStatuses = new Set(["active", "superseded", "retired"]);
+  if (approvedStatuses.has(previousRecord.status) && approvedStatuses.has(nextRecord.status)) {
+    assertLifecycleFieldsUnchanged(previousRecord, nextRecord, [
+      "approverIds",
+      "approvedOn",
+      "approvedContentRevisions"
+    ], "approval", title);
+  }
+  if (activatedStatuses.has(previousRecord.status) && activatedStatuses.has(nextRecord.status)) {
+    assertLifecycleFieldsUnchanged(previousRecord, nextRecord, [
+      "activationBasis",
+      "activatedByIds",
+      "activatedOn",
+      "activatedContentRevisions",
+      "effectiveOn"
+    ], "activation", title);
+  }
+  if (
+    nextRecord.status === "active"
+    && previousRecord.status !== "active"
+    && !["document-activation", "governed-content-activation"].includes(lifecycleOperation)
+  ) {
+    const step = governedDocument && documentIsAuditSpecific(nextRecord, model) ? "Step 5" : "Step 3";
+    throw new Error(`${title} "${nextRecord.id}" must use the dedicated ${step} ${title} activation operation after approval.`);
+  }
+}
+
+function assertLifecycleFieldsUnchanged(previousRecord, nextRecord, fields, eventLabel, resourceTitle) {
+  const changed = fields.filter((field) => (
+    JSON.stringify(previousRecord[field] ?? null) !== JSON.stringify(nextRecord[field] ?? null)
+  ));
+  if (!changed.length) return;
+  throw new Error(
+    `${resourceTitle} "${nextRecord.id}" ${eventLabel} facts are immutable after the event: ${changed.join(", ")}. `
+    + `Move the ${resourceTitle} back to ${eventLabel === "approval" ? "draft" : "approved"} and record a new lifecycle event.`
+  );
+}
+
 async function prepareAttestationBinding(loaded, record, previousRecord = null) {
   const nextRecord = structuredClone(record);
   const bound = record.status === "completed" && record.attestationMethod === "git-approval";
@@ -848,22 +954,54 @@ async function prepareAttestationBinding(loaded, record, previousRecord = null)
   return nextRecord;
 }
 
-function approvalBound(record) {
+function approvalBound(record, model) {
   if (!record || !["policy", "document", "training"].includes(record.type)) return false;
   const statuses = record.type === "policy"
     ? ["approved", "active", "superseded", "retired"]
     : record.type === "document"
-      ? ["active", "superseded", "retired"]
-      : ["active", "retired"];
+      ? ["approved", "active", "superseded", "retired"]
+      : modelSupports(model || 0, "governed-training-activation")
+        ? ["approved", "active", "superseded", "retired"]
+        : ["active", "retired"];
   return statuses.includes(record.status);
 }
 
-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: (candidate) => approvalBound(candidate, model),
+      label: record.type === "policy" ? "approve or activate" : "approve"
+    });
+  }
+  if (record?.type === "document" && model.resources.document?.fields?.activatedContentRevisions) {
+    fields.push({
+      field: "activatedContentRevisions",
+      bound: (candidate) => (
+        ["active", "superseded", "retired"].includes(candidate?.status)
+        && candidate.activationBasis === "recorded"
+      ),
+      label: "activate"
+    });
+  }
   if (record?.type === "training" && model.resources.training?.fields?.effectiveContentRevisions) {
-    return "effectiveContentRevisions";
+    fields.push({ field: "effectiveContentRevisions", bound: (candidate) => approvalBound(candidate, model), label: "approve or activate" });
+  }
+  if (record?.type === "training" && model.resources.training?.fields?.approvedContentRevisions) {
+    fields.push({ field: "approvedContentRevisions", bound: (candidate) => approvalBound(candidate, model), label: "approve" });
+  }
+  if (record?.type === "training" && model.resources.training?.fields?.activatedContentRevisions) {
+    fields.push({
+      field: "activatedContentRevisions",
+      bound: (candidate) => (
+        ["active", "superseded", "retired"].includes(candidate?.status)
+        && candidate.activationBasis === "recorded"
+      ),
+      label: "activate"
+    });
   }
-  return null;
+  return fields;
 }
 
 async function exclusiveContentFiles(loaded, record) {

package/src/git.js

@@ -133,29 +133,88 @@ export function getWorkspaceHistories(input, relativePaths, limitPerFile = 12, o
 }
 
 export function getFileAtRevision(input, revision, relativePath) {
+  return getFilesAtRevisions(input, [{ revision, relativePath }])[0];
+}
+
+export function getFilesAtRevisions(input, requests) {
   const root = resolveWorkspaceRoot(input);
-  if (!/^[a-f0-9]{40}$/i.test(String(revision)) || !isSafeDataGitPath(relativePath)) {
+  const invalid = Array.isArray(requests) && requests.find(({ revision, relativePath } = {}) => (
+    !/^[a-f0-9]{40}$/i.test(String(revision)) || !isSafeDataGitPath(relativePath)
+  ));
+  if (!Array.isArray(requests) || invalid) {
     throw new Error("Historical file exports require a Git commit and a data/ path.");
   }
+  if (!requests.length) return [];
   try {
     const topLevel = git(root, ["rev-parse", "--show-toplevel"]);
     const workspacePrefix = relative(topLevel, root).split(sep).join("/");
-    if (workspacePrefix === ".." || workspacePrefix.startsWith("../")) return null;
-    const repositoryPath = workspacePrefix ? `${workspacePrefix}/${relativePath}` : relativePath;
-    return execFileSync("git", ["show", `${revision}:${repositoryPath}`], {
+    if (workspacePrefix === ".." || workspacePrefix.startsWith("../")) return requests.map(() => null);
+    const results = [];
+    for (let offset = 0; offset < requests.length; offset += 4) {
+      const batch = requests.slice(offset, offset + 4);
+      const specifications = batch.map(({ revision, relativePath }) => {
+        const repositoryPath = workspacePrefix ? `${workspacePrefix}/${relativePath}` : relativePath;
+        return `${revision}:${repositoryPath}`;
+      });
+      try {
+        const output = measureTimingSync("git-history-export", () => execFileSync("git", ["cat-file", "--batch"], {
+          cwd: root,
+          input: `${specifications.join("\n")}\n`,
+          stdio: ["pipe", "pipe", "ignore"],
+          timeout: 10_000,
+          maxBuffer: 80_000_000
+        }));
+        results.push(...parseBatchObjects(output, batch.length));
+      } catch {
+        results.push(...specifications.map((specification) => readHistoricalFile(root, specification)));
+      }
+    }
+    return results;
+  } catch {
+    return requests.map(() => null);
+  }
+}
+
+function readHistoricalFile(root, specification) {
+  try {
+    return measureTimingSync("git-history-export", () => execFileSync("git", ["show", specification], {
       cwd: root,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 10_000,
       maxBuffer: 20_000_000
-    });
+    }));
   } catch {
     return null;
   }
 }
 
+function parseBatchObjects(output, expected) {
+  const results = [];
+  let offset = 0;
+  for (let index = 0; index < expected; index += 1) {
+    const headerEnd = output.indexOf(10, offset);
+    if (headerEnd < 0) throw new Error("Git returned an incomplete historical object header.");
+    const header = output.subarray(offset, headerEnd).toString("utf8");
+    offset = headerEnd + 1;
+    if (header.endsWith(" missing")) {
+      results.push(null);
+      continue;
+    }
+    const size = Number(header.split(" ").at(-1));
+    if (!Number.isSafeInteger(size) || size < 0 || offset + size >= output.length) {
+      throw new Error("Git returned an invalid historical object size.");
+    }
+    results.push(output.subarray(offset, offset + size).toString("utf8"));
+    offset += size;
+    if (output[offset++] !== 10) throw new Error("Git returned an incomplete historical object.");
+  }
+  return results;
+}
+
 function isSafeDataGitPath(value) {
   return isCanonicalDataPath(value)
+    && !/[\r\n]/.test(value)
     && value.startsWith("data/")
     && value !== "data/";
 }
@@ -230,6 +289,7 @@ export async function getWorkspaceRevisionSnapshot(input = process.cwd()) {
       available: true,
       commit: parsed.commit,
       shortCommit: parsed.commit?.slice(0, 8) ?? "no commits",
+      branch: parsed.branch,
       clean: parsed.changePaths.length === 0,
       changes: parsed.changePaths,
       workspaceChangePaths: parsed.changePaths
@@ -1121,11 +1181,14 @@ function parsePorcelainV2(source, topLevel, root) {
 function parseWorkspaceRevision(source) {
   const fields = source.split("\0").filter(Boolean);
   let commit = null;
+  let branch = null;
   const changePaths = [];
   for (let index = 0; index < fields.length; index += 1) {
     const field = fields[index];
     if (field.startsWith("# branch.oid ")) {
       commit = field.slice(13) === "(initial)" ? null : field.slice(13);
+    } else if (field.startsWith("# branch.head ")) {
+      branch = field.slice(14) === "(detached)" ? null : field.slice(14);
     } else if (/^[12u?!] /.test(field)) {
       changePaths.push(porcelainV2Path(field));
       if (field.startsWith("2 ")) {
@@ -1135,6 +1198,7 @@ function parseWorkspaceRevision(source) {
   }
   return {
     commit,
+    branch,
     changePaths: [...new Set(changePaths.filter(Boolean))].sort()
   };
 }
@@ -1290,13 +1354,13 @@ async function tryGitAsync(cwd, args, operation) {
 }
 
 function git(cwd, args) {
-  return execFileSync("git", args, {
+  return measureTimingSync("git-command-sync", () => execFileSync("git", args, {
     cwd,
     encoding: "utf8",
     stdio: ["ignore", "pipe", "ignore"],
     timeout: 10_000,
     maxBuffer: 20_000_000
-  }).trim();
+  }).trim());
 }
 
 function tryGit(cwd, args) {

package/src/index.js

@@ -2,10 +2,12 @@ export {
   ACTIVE_MODEL_VERSION,
   getResourceDefinition,
   loadModel,
+  MODEL_CAPABILITY_VERSIONS,
+  modelSupports,
   SUPPORTED_MODEL_VERSIONS
 } from "../model/index.js";
 export { buildAgentGuide, findResourceReferences, listResourceTypes, scaffoldResourceMutation } from "./agent.js";
-export { assessAuditPreparation, prepareAuditWorkspace } from "./audit-preparation.js";
+export { assessAuditDocumentActivations, assessAuditPreparation, prepareAuditWorkspace } from "./audit-preparation.js";
 export { createNextAuditCycle, planNextAuditCycle } from "./audit-transition.js";
 export {
   applyApplicabilityReview,
@@ -52,6 +54,14 @@ export { generateModelDocumentation } from "./model-docs.js";
 export { renderMarkdown } from "./markdown.js";
 export { migrateModel, planModelMigration } from "./model-migration.js";
 export { activatePolicies, planPolicyActivation, scaffoldPolicyActivation } from "./policy-activation.js";
+export {
+  activateDocuments,
+  activateGovernedContent,
+  planDocumentActivation,
+  planGovernedContentActivation,
+  scaffoldDocumentActivation,
+  scaffoldGovernedContentActivation
+} from "./document-activation.js";
 export {
   applyPolicyLibraryUpgrade,
   assessPolicyLibraryUpgrades,