filegrc 0.12.4 → 0.13.1

package/package.json

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

package/src/files.js

@@ -965,14 +965,22 @@ async function updateContentUnlocked(input, dataRelativePath, source, options) {
   const path = resolveDataPath(loaded.root, dataRelativePath);
   const previous = await readFile(path, "utf8");
   assertRevision(previous, options.expectedRevision, "The Markdown file");
-  const before = await validateWorkspace(loaded);
+  const deferValidation = workspaceValidationDeferred();
+  const before = deferValidation ? null : await validateWorkspace(loaded);
   const nextSource = source.endsWith("\n") ? source : `${source}\n`;
   await writeTextAtomic(path, nextSource);
   try {
-    const result = await validateWorkspace(loaded.root);
-    const introduced = newErrors(result, before);
-    if (introduced.length) throw new Error(formatWriteFailure(introduced, dataRelativePath));
-    return { path, dataRelativePath };
+    if (!deferValidation) {
+      const result = await validateWorkspace(loaded.root);
+      const introduced = newErrors(result, before);
+      if (introduced.length) throw new Error(formatWriteFailure(introduced, dataRelativePath));
+    }
+    return {
+      path,
+      dataRelativePath,
+      source: nextSource,
+      revision: contentRevision(nextSource)
+    };
   } catch (error) {
     await writeTextAtomic(path, previous);
     throw error;

package/src/git.js

@@ -1,7 +1,7 @@
 import { execFileSync, spawn } from "node:child_process";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomUUID } from "node:crypto";
-import { closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, readSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { devNull } from "node:os";
 import { relative, resolve, sep } from "node:path";
@@ -23,6 +23,7 @@ const backgroundSynchronizations = new Map();
 const browserRemotePrefetches = new Map();
 const browserRemotePrefetchPromises = new Map();
 const repositorySnapshotPromises = new Map();
+const repositoryObjectFormats = new Map();
 const gitCommandCaches = new AsyncLocalStorage();
 const gitCommandDeadlines = new AsyncLocalStorage();
 const gitCommandCacheBytes = new WeakMap();
@@ -30,6 +31,7 @@ let gitCommandInterceptor = null;
 let gitSubprocessObserver = null;
 let historicalBatchInterceptor = null;
 let historicalRevisionReadObserver = null;
+let workspaceBlobObjectIdOverride = null;
 const BROWSER_REMOTE_PREFETCH_MAX_AGE_MS = 30_000;
 const GIT_DEFAULT_TIMEOUT_MS = 10_000;
 const GIT_REMOTE_TIMEOUT_MS = 30_000;
@@ -680,15 +682,50 @@ export function getFileObjectIdAtRevision(input, revision, relativePath) {
 export function getWorkingFileObjectId(input, relativePath) {
   if (!isSafeDataGitPath(relativePath)) return null;
   const root = resolveWorkspaceRoot(input);
+  let descriptor;
   try {
-    const objectId = git(root, ["hash-object", "--no-filters", "--", relativePath]);
-    return /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/i.test(objectId) ? objectId : null;
+    const objectFormat = repositoryObjectFormat(root);
+    if (!objectFormat) return null;
+    descriptor = openSync(resolve(root, relativePath), constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+    const before = fstatSync(descriptor);
+    if (!before.isFile()) return null;
+    const hash = createHash(objectFormat).update(`blob ${before.size}\0`);
+    const buffer = Buffer.allocUnsafe(64 * 1024);
+    let position = 0;
+    while (position < before.size) {
+      const count = readSync(descriptor, buffer, 0, Math.min(buffer.length, before.size - position), position);
+      if (!count) return null;
+      hash.update(buffer.subarray(0, count));
+      position += count;
+    }
+    const after = fstatSync(descriptor);
+    if (
+      after.size !== before.size
+      || after.dev !== before.dev
+      || after.ino !== before.ino
+      || after.mtimeMs !== before.mtimeMs
+      || after.ctimeMs !== before.ctimeMs
+    ) return null;
+    return hash.digest("hex");
   } catch (error) {
     rethrowGitDeadline(error);
     return null;
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
   }
 }
 
+function repositoryObjectFormat(root) {
+  if (repositoryObjectFormats.has(root)) return repositoryObjectFormats.get(root);
+  if (!tryGit(root, ["rev-parse", "--git-dir"])) return null;
+  const objectFormat = tryGit(root, ["config", "--get", "extensions.objectFormat"]) || "sha1";
+  if (!["sha1", "sha256"].includes(objectFormat)) {
+    throw new Error(`FileGRC does not support the repository object format "${objectFormat}".`);
+  }
+  repositoryObjectFormats.set(root, objectFormat);
+  return objectFormat;
+}
+
 export function getWorkspaceHistories(input, relativePaths, limitPerFile = 12, options = {}) {
   const root = resolveWorkspaceRoot(input);
   const wanted = new Set(relativePaths);
@@ -1415,8 +1452,8 @@ async function runTrunkMutationUnlocked(root, config, options, task) {
     })));
     subject = generatedCommitMessage(typeof options?.message === "function" ? options.message(result) : options?.message);
     assertNoIgnoredAuthoritativeFiles(root);
-    const beforeValidation = workspaceByteManifest(root);
-    const validation = await validateWorkspace(root);
+    const beforeValidation = measureTimingSync("workspace-manifest", () => workspaceByteManifest(root));
+    const validation = await withGitCommandCache(new Map(), () => validateWorkspace(root));
     if (!validation.ok) {
       throw new Error(`The workspace has ${validation.counts.errors} validation ${validation.counts.errors === 1 ? "error" : "errors"}.`);
     }
@@ -1426,9 +1463,9 @@ async function runTrunkMutationUnlocked(root, config, options, task) {
           validation,
           fingerprint: (await measureTiming("fingerprint", () => fingerprintWorkspace(validation.loaded))).fingerprint
     };
-    validatedManifest = workspaceByteManifest(root);
+    validatedManifest = measureTimingSync("workspace-manifest", () => workspaceByteManifest(root));
     assertWorkspaceManifestEqual(beforeValidation, validatedManifest);
-    await assertNoOutsideWorktreeChangesAsync(root);
+    await measureTiming("outside-worktree-check", () => assertNoOutsideWorktreeChangesAsync(root));
   } catch (error) {
     throw new Error(`${error.message} FileGRC preserved every current file instead of guessing which edits it owns. Review the Git diff; later browser mutations are blocked until the worktree is reconciled.`);
   }
@@ -1454,13 +1491,13 @@ async function runTrunkMutationUnlocked(root, config, options, task) {
   }
   assertValidGitIdentity(root);
   assertNoWorkspaceContentFilters(root);
-  await assertNoOutsideWorktreeChangesAsync(root);
+  await measureTiming("outside-worktree-check", () => assertNoOutsideWorktreeChangesAsync(root));
   let commit;
   let indexReconciled;
   try {
     const expectedRef = `refs/heads/${config.authoritativeBranch}`;
     assertExpectedCheckout(root, expectedRef, synchronized.currentCommit);
-    validatedManifest = writeWorkspaceManifestObjects(root, validatedManifest);
+    validatedManifest = measureTimingSync("workspace-manifest-objects", () => writeWorkspaceManifestObjects(root, validatedManifest));
     ({ commit, indexReconciled } = await measureTiming("commit", () => commitValidatedIndexAsync(root, subject, validatedManifest, {
       expectedParent: synchronized.currentCommit,
       expectedRef
@@ -2261,6 +2298,8 @@ function assertNoIgnoredAuthoritativeFiles(root) {
 
 function workspaceByteManifest(root) {
   assertNoHiddenIndexEntries(root);
+  const objectFormat = repositoryObjectFormat(root);
+  if (!objectFormat) throw new Error("FileGRC could not determine the Git repository object format.");
   const paths = [...new Set(nulFields(gitRaw(root, [
     "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", "."
   ])))].sort();
@@ -2298,9 +2337,36 @@ function workspaceByteManifest(root) {
       ) {
         throw new Error(`FileGRC will not commit workspace entry "${path}" because it changed while its bytes were being inspected.`);
       }
-      const bytes = readFileSync(descriptor);
-      const objectId = hashWorkspaceBytes(root, bytes);
-      return [path, { objectId, mode: opened.mode & 0o111 ? "100755" : "100644", bytes }];
+      const objectHash = createHash(objectFormat).update(`blob ${opened.size}\0`);
+      const byteHash = createHash("sha256");
+      const buffer = Buffer.allocUnsafe(64 * 1024);
+      let position = 0;
+      while (position < opened.size) {
+        const count = readSync(descriptor, buffer, 0, Math.min(buffer.length, opened.size - position), position);
+        if (!count) throw new Error(`FileGRC could not read complete workspace entry "${path}".`);
+        const chunk = buffer.subarray(0, count);
+        objectHash.update(chunk);
+        byteHash.update(chunk);
+        position += count;
+      }
+      const after = fstatSync(descriptor);
+      if (
+        after.size !== opened.size
+        || after.dev !== opened.dev
+        || after.ino !== opened.ino
+        || after.mtimeMs !== opened.mtimeMs
+        || after.ctimeMs !== opened.ctimeMs
+      ) {
+        throw new Error(`FileGRC will not commit workspace entry "${path}" because it changed while its bytes were being inspected.`);
+      }
+      const calculatedObjectId = objectHash.digest("hex");
+      const objectId = workspaceBlobObjectIdOverride?.(null, objectFormat, path) ?? calculatedObjectId;
+      return [path, {
+        objectId,
+        byteDigest: byteHash.digest("hex"),
+        size: opened.size,
+        mode: opened.mode & 0o111 ? "100755" : "100644"
+      }];
     } finally {
       closeSync(descriptor);
     }
@@ -2316,24 +2382,42 @@ function assertNoHiddenIndexEntries(root) {
   }
 }
 
-function hashWorkspaceBytes(root, bytes, write = false) {
-  return observedExecFileSync("git", ["hash-object", ...(write ? ["-w"] : []), "--stdin"], {
+function writeWorkspaceManifestObjects(root, manifest) {
+  const valuesByObjectId = new Map();
+  for (const value of manifest.values()) {
+    if (!value.objectId) continue;
+    const prior = valuesByObjectId.get(value.objectId);
+    if (prior && (prior.size !== value.size || prior.byteDigest !== value.byteDigest)) {
+      throw new Error(`Git object ${value.objectId} identifies different validated workspace bytes.`);
+    }
+    valuesByObjectId.set(value.objectId, value);
+  }
+  if (!valuesByObjectId.size) return manifest;
+  const entries = [...manifest].filter(([, value]) => value.objectId);
+  const topLevel = git(root, ["rev-parse", "--show-toplevel"]);
+  const workspacePrefix = relative(topLevel, root).split(sep).join("/");
+  if (workspacePrefix === ".." || workspacePrefix.startsWith("../")) {
+    throw new Error("The FileGRC workspace is outside its Git repository.");
+  }
+  const written = observedExecFileSync("git", ["hash-object", "-w", "--stdin-paths"], {
     cwd: root,
-    input: bytes,
+    input: `${entries.map(([path]) => workspacePrefix ? `${workspacePrefix}/${path}` : path).join("\n")}\n`,
     encoding: "utf8",
     stdio: ["pipe", "pipe", "ignore"],
     timeout: 30_000,
     maxBuffer: 20_000_000,
     env: gitEnvironment()
-  }).trim();
-}
-
-function writeWorkspaceManifestObjects(root, manifest) {
-  return new Map([...manifest].map(([path, value]) => (
-    value.objectId
-      ? [path, { ...value, objectId: hashWorkspaceBytes(root, value.bytes, true) }]
-      : [path, value]
-  )));
+  }).trim().split("\n");
+  if (written.length !== entries.length) {
+    throw new Error("Git returned an unexpected number of workspace objects.");
+  }
+  for (let index = 0; index < entries.length; index += 1) {
+    if (written[index] !== entries[index][1].objectId) {
+      throw new Error(`Git wrote an unexpected object while preparing validated workspace bytes for commit.`);
+    }
+  }
+  assertWorkspaceManifestEqual(manifest, workspaceByteManifest(root));
+  return manifest;
 }
 
 function assertWorkspaceManifestEqual(expected, current) {
@@ -2346,7 +2430,11 @@ function workspaceManifestsEqual(expected, current) {
   return expected.size === current.size
     && [...expected].every(([path, value]) => {
       const other = current.get(path);
-      return other && value.objectId === other.objectId && value.mode === other.mode;
+      return other
+        && value.objectId === other.objectId
+        && value.mode === other.mode
+        && value.size === other.size
+        && value.byteDigest === other.byteDigest;
     });
 }
 
@@ -2621,6 +2709,15 @@ export function setHistoricalRevisionReadObserverForTests(observer) {
   return () => { historicalRevisionReadObserver = previous; };
 }
 
+export function setWorkspaceBlobObjectIdOverrideForTests(override) {
+  if (override !== null && typeof override !== "function") {
+    throw new TypeError("The workspace blob object ID override must be a function or null.");
+  }
+  const previous = workspaceBlobObjectIdOverride;
+  workspaceBlobObjectIdOverride = override;
+  return () => { workspaceBlobObjectIdOverride = previous; };
+}
+
 export function runGitCommand(cwd, args, options = {}) {
   if (gitCommandInterceptor) {
     return Promise.resolve().then(() => gitCommandInterceptor({

package/src/program-amendment.js

@@ -172,13 +172,14 @@ export async function assessProgramAmendmentReadiness(loaded) {
   const commitments = loaded.resources.filter((record) => (
     record.type === "commitment" && !["superseded", "retired"].includes(record.status)
   ));
-  const sourceIds = new Set(commitments.flatMap((record) => record.sourceResourceIds || []));
+  const supplementalCommitments = commitments.filter((record) => (record.sourceResourceIds || []).length > 0);
+  const sourceIds = new Set(supplementalCommitments.flatMap((record) => record.sourceResourceIds || []));
   for (const record of loaded.resources) {
     if (["policy", "document"].includes(record.type) && record.programRole === "supporting" && !["superseded", "retired"].includes(record.status)) {
       sourceIds.add(record.id);
     }
   }
-  const sourceRecords = [...new Set([...sourceIds, ...commitments.map(({ id }) => id)])]
+  const sourceRecords = [...new Set([...sourceIds, ...supplementalCommitments.map(({ id }) => id)])]
     .map((id) => byId.get(id))
     .filter((record) => record && SOURCE_TYPES.has(record.type));
   const plans = await Promise.all(sourceRecords.map((record) => (

package/src/program-path.js

@@ -11,8 +11,8 @@ export const RESOURCE_INSTRUCTIONS = {
   framework: "Confirm the criteria framework and version used for the program.",
   requirement: "Keep the published criterion as catalog content. Record management applicability and rationale on the selected Program.",
   commitment: "Record supplemental customer promises and service requirements that shape the scope or control design. The Commitment’s systemIds and controlIds are authoritative for what fulfills it.",
-  "requirement-mapping": "Record a reviewed relationship among Requirements, Commitments, and Controls. Choose the comparison method and relationship explicitly, explain the rationale, and bind the review to every mapped source revision.",
-  "reporting-route-set": "Record the normal and fallback ways people send one kind of report, including where each channel goes and the role that keeps it usable. Commit the proposal before approval, use separate approval and ongoing authority Appointments, and create a successor when either channel changes.",
+  "requirement-mapping": "Use a Requirement Mapping when supplemental policies, contracts, privacy promises, frameworks, or other sources need explicit coverage semantics. Choose the comparison method and relationship, explain the rationale, and bind the review to every mapped source revision.",
+  "reporting-route-set": "Prepare the normal and fallback ways people will send each report required by proposed program content, including where each channel goes and the role that keeps it usable. Commit the proposal in Step 1, approve it before cutover, use separate approval and ongoing authority Appointments, and create a successor when either channel changes.",
   policy: "Tailor each Policy to match what the company is committing to. Clear placeholders, assign an owner and separate approver, then bind approval to the reviewed content. Approval does not prove implementation. Activate the Policy during the Step 3 cutover after reviewing its implementation gaps.",
   document: "Complete required program Documents in Step 2, assign an owner and separate approver, and bind approval to the intended values and exact Markdown. Implement the linked requirements and activate that approved revision in Step 3. Prepare Audit Documents in Step 5.",
   control: "Finish each applicable starter Control with the procedure people follow, its owner, bounded System scope, operating Components, authoritative evidence-source Components, governing Policy and Requirement mappings, and implementation date. Put calendar and event schedules in Obligations.",
@@ -82,8 +82,8 @@ export const PROGRAM_PATH = [
     description: "Ownership, criteria, and service boundary",
     summary: "Name the owners, criteria, service, Systems, and providers in scope.",
     sections: [
-      { id: "ownership", title: "Program Ownership", description: "Confirm who owns the program, plus the normal security reporting channel and its fallback.", steps: ["Confirm the initial program lead’s actual job title and the separate Policy Owner Appointment.", "Add the organization’s real appointments, reviewers, and operators.", "Review the starter Security and Risk Oversight team, its members, and its chair.", "Set a normal security reporting channel and a fallback, then commit that proposal before approval.", "Add other teams only when the organization assigns shared responsibility to them."], types: ["person", "appointment", "team", "reporting-route-set"], defaultOpen: true },
-      { id: "criteria", title: "Program and Criteria", description: "Define the Program, confirm its Frameworks, record Program-scoped Requirement applicability, and connect customer commitments that shape the System or Control design.", steps: ["Confirm the Program goal, owners, risk method, and candidate period.", "Review the included Security criteria references and record each applicability decision on the Program.", "Record customer commitments and reviewed mappings. Keep optional criteria out until the company chooses to add them."], types: ["program", "framework", "requirement", "commitment", "requirement-mapping"], defaultOpen: true },
+      { id: "ownership", title: "Program Ownership", description: "Confirm who owns the program, plus the normal security reporting channel and its fallback.", steps: ["Confirm the initial program lead’s actual job title and the separate Policy Owner Appointment.", "Add the organization’s real appointments, reviewers, and operators.", "Review the starter Security and Risk Oversight team, its members, and its chair.", "Replace the starter reporting-channel placeholders, propose the set, and commit that proposal before Step 1 is complete. Approve it before the later implementation cutover.", "Add other teams only when the organization assigns shared responsibility to them."], types: ["person", "appointment", "team", "reporting-route-set"], defaultOpen: true },
+      { id: "criteria", title: "Program and Criteria", description: "Define the Program, confirm its Frameworks, record Program-scoped Requirement applicability, and connect customer commitments that shape the System or Control design.", steps: ["Confirm the Program goal, owners, risk method, and candidate period.", "Review the included Security criteria references and record each applicability decision on the Program.", "Replace each planned service-commitment prompt with the actual promise or requirement. Use Requirement Mappings only when a supplemental source needs an explicit coverage comparison. Keep optional criteria out until the company chooses to add them."], types: ["program", "framework", "requirement", "commitment", "requirement-mapping"], defaultOpen: true },
       { id: "boundary", title: "System Boundary", description: "Start with the bounded System. Add Components that materially deliver the service, support Controls, produce authoritative Evidence, or support relevant operations. Keep Vendor relationships and specific Assets separate.", steps: ["Create the complete bounded System and select it on the Program.", "Add only relevant Components, with a role and rationale for each System use.", "Create Vendors for material external provider relationships and link supplied Components when factual.", "Normalize Information Types and Classifications used by the System, Components, Vendors, Risks, and Evidence Artifacts."], types: ["system", "component", "vendor", "classification", "information-type"], defaultOpen: false }
     ],
     resourceTypes: ["person", "appointment", "team", "reporting-route-set", "program", "framework", "requirement", "commitment", "requirement-mapping", "system", "component", "vendor", "classification", "information-type"],

package/src/program-readiness.js

@@ -424,16 +424,32 @@ function reportingRouteSetItem(assessment) {
   const draft = assessment.routeSets.find(({ record }) => ["draft", "proposed"].includes(record.status));
   const required = assessment.requirements.length > 0;
   const proposed = assessment.proposedRequirements.length > 0;
-  const ready = assessment.issues.length === 0 && (!required || Boolean(current));
-  const needsAction = assessment.issues.length > 0;
+  const proposedPurposeKeys = [...new Set(assessment.proposedRequirements
+    .map(({ purposeKey }) => purposeKey)
+    .filter(Boolean))];
+  const preparedPurposeKeys = new Set(assessment.routeSets
+    .filter(({ record, committed, canceled, proposedRequirementIssues }) => (
+      ["proposed", "approved"].includes(record.status)
+      && committed
+      && !canceled
+      && proposedRequirementIssues.length === 0
+    ))
+    .map(({ record }) => record.purposeKey));
+  const unpreparedPurposeKeys = proposedPurposeKeys.filter((purposeKey) => !preparedPurposeKeys.has(purposeKey));
+  const ready = assessment.issues.length === 0
+    && (!required || Boolean(current))
+    && unpreparedPurposeKeys.length === 0;
+  const needsAction = assessment.issues.length > 0 || unpreparedPurposeKeys.length > 0;
   const target = current?.record || draft?.record || { type: "reporting-route-set" };
   let message;
-  if (needsAction) {
+  if (assessment.issues.length) {
     message = assessment.issues[0].message;
+  } else if (unpreparedPurposeKeys.length) {
+    message = `Complete and commit a Reporting Channel Set proposal for ${unpreparedPurposeKeys.join(", ")} before Step 1 is complete. Approval and effectiveness remain part of the later implementation cutover.`;
   } else if (required && ready && current) {
     message = `${current.record.title} is committed, effective, and has a current responsible Appointment. Assignments bind its Git commit.`;
-  } else if (!required && proposed && draft) {
-    message = "A draft or approved-but-inactive rule will require normal and fallback reporting channels later. Review them before that rule becomes active; this is not a current readiness gate.";
+  } else if (!required && proposed) {
+    message = "Every reporting-channel requirement in proposed program content has a committed Reporting Channel Set proposal. Approve the exact proposal before its governing content becomes active.";
   } else if (!required && draft) {
     message = "No approved rule currently requires these reporting channels. Keep the draft for review or remove it; it is not a readiness gate.";
   } else if (!required) {
@@ -443,12 +459,15 @@ function reportingRouteSetItem(assessment) {
   }
   return item(
     "security-reporting-route-set",
-    needsAction ? "action" : required ? ready ? "complete" : "action" : proposed && draft ? "later" : "info",
-    needsAction ? "Fix reporting channel requirements" : required ? "Approve required reporting channels" : proposed ? "Review proposed reporting channels" : "Reporting channels are not currently required",
+    needsAction ? "action" : required ? ready ? "complete" : "action" : proposed ? "complete" : "info",
+    needsAction ? "Prepare required reporting channels" : required ? "Approve required reporting channels" : proposed ? "Reporting channel proposals are ready" : "Reporting channels are not currently required",
     message,
     target,
     {
       requirements: assessment.requirements,
+      proposedRequirements: assessment.proposedRequirements,
+      proposedRequirementIssues: assessment.routeSets.flatMap(({ proposedRequirementIssues }) => proposedRequirementIssues),
+      unpreparedPurposeKeys,
       issues: assessment.issues,
       commands: [
         "npx filegrc reporting-route-sets --json",

package/src/reconciliation.js

@@ -456,6 +456,10 @@ export async function planReconciliation(input = process.cwd(), options = {}) {
 
 function reconciliationCandidate(loaded, transition, record, path, fingerprint, eventId, extra = {}) {
   const needsTimestamp = eventNeedsTimestamp(loaded, transition.eventType);
+  const requiredFacts = [
+    transition.eventType === "person-ended" ? "riskLevel" : null,
+    needsTimestamp ? "occurredAt" : "occurredOn"
+  ].filter(Boolean);
   return {
     id: `reconcile-${fingerprint.slice(0, 16)}`,
     eventId,
@@ -465,12 +469,13 @@ function reconciliationCandidate(loaded, transition, record, path, fingerprint,
     sourcePath: path,
     state: "needs-confirmation",
     message: transition.message,
-    requiredFacts: [
-      transition.eventType === "person-ended" ? "riskLevel" : null,
-      needsTimestamp ? "occurredAt" : "occurredOn"
-    ].filter(Boolean),
+    requiredFacts,
     action: {
-      kind: "command",
+      kind: "reconcile-transition",
+      candidateId: fingerprint,
+      eventType: transition.eventType,
+      subject: { type: record.type, id: record.id },
+      requiredFacts,
       command: reconciliationCommand(transition.eventType, record.id, fingerprint, needsTimestamp)
     },
     ...extra

package/src/reporting-route-integrity.js

@@ -14,6 +14,7 @@ import { appointmentWasAuthorizedOn } from "./soc2.js";
 import { isRfc3339Timestamp, localDateTimeValue, timestampFromLocalDateTime } from "./time.js";
 
 const CONTEMPORANEOUS_COMMIT_WINDOW_MS = 86_400_000;
+const REPORTING_ROUTE_REQUIREMENT_SOURCE_TYPES = new Set(["policy", "document", "commitment", "risk"]);
 
 export function reportingRouteRevision(record) {
   const effectiveFacts = {
@@ -103,10 +104,14 @@ export function reportingRouteAssertionTiming(loaded, routeSet, eventName) {
 
 export function reportingRouteFixedEvidence(records, subjectId, evidenceIds, at, timezone = "UTC", options = {}) {
   let date;
+  let availableDate;
   try {
     date = /^\d{4}-\d{2}-\d{2}$/.test(String(at || ""))
       ? String(at)
       : localDateTimeValue(instant(at, "Supported event time"), timezone).slice(0, 10);
+    availableDate = options.availableAt
+      ? localDateTimeValue(instant(options.availableAt, "Evidence availability time"), timezone).slice(0, 10)
+      : null;
   } catch {
     return [];
   }
@@ -119,6 +124,7 @@ export function reportingRouteFixedEvidence(records, subjectId, evidenceIds, at,
       || evidence.status !== "verified"
       || !arrayValue(evidence.sourceResourceIds).includes(subjectId)
       || !verifiedEvidenceComplete(evidence, personIds)
+      || (availableDate && (evidence.collectedOn > availableDate || evidence.verifiedOn > availableDate))
     ) return false;
     const coversDate = coverageContains(evidence.coverage, date)
       || [evidence.businessEventAt, evidence.sourceGeneratedAt].filter(Boolean).some((value) => {
@@ -274,6 +280,150 @@ export function reportingRouteRequirementAppliesToProgram(requirement, programId
     && arrayValue(requirement.programIds).includes(programId);
 }
 
+export function reportingRouteProposalIssues(records, routeSet, options = {}) {
+  return reportingRouteProposalIssuesForRequirements(
+    reportingRouteRequirementsForProposal(records, routeSet),
+    routeSet,
+    records,
+    options
+  );
+}
+
+export function reportingRouteRequirementsForProposal(records, routeSet, options = {}) {
+  return records.flatMap((source) => (
+    REPORTING_ROUTE_REQUIREMENT_SOURCE_TYPES.has(source.type)
+      && (
+        reportingRouteSourceMayBecomeEffective(source)
+        || reportingRouteSourceEffectiveAt(source, options.at, options.timezone)
+      )
+      ? (Array.isArray(source.reportingRouteRequirements) ? source.reportingRouteRequirements : [])
+        .filter((requirement) => (
+          requirement
+          && typeof requirement === "object"
+          && !Array.isArray(requirement)
+          && requirement.purposeKey === routeSet.purposeKey
+          && reportingRouteRequirementAppliesToProgram(requirement, routeSet.programId)
+        ))
+      : []
+  ));
+}
+
+function reportingRouteSourceEffectiveAt(source, at, timezone = "UTC") {
+  if (!at) return false;
+  try { return reportingRouteSourceEffective(source, at, timezone); } catch { return false; }
+}
+
+export function reportingRouteSupportIssues(requirements, routeSet, proposalRecords, currentRecords, options = {}) {
+  const proposalIssues = reportingRouteProposalIssuesForRequirements(
+    requirements,
+    routeSet,
+    proposalRecords,
+    { ...options, commit: options.proposalCommit }
+  );
+  const currentIssues = reportingRouteProposalIssuesForRequirements(
+    requirements,
+    routeSet,
+    currentRecords,
+    { ...options, commit: options.currentCommit }
+  );
+  return [...new Map([...proposalIssues, ...currentIssues].map((item) => [
+    `${item.code}\0${item.resourceId}\0${item.message}`,
+    item
+  ])).values()];
+}
+
+export function reportingRouteProposalIssuesForRequirements(requirements, routeSet, records, options = {}) {
+  const applicableRequirements = requirements.filter((requirement) => (
+    requirement
+    && typeof requirement === "object"
+    && !Array.isArray(requirement)
+    && requirement.purposeKey === routeSet.purposeKey
+    && reportingRouteRequirementAppliesToProgram(requirement, routeSet.programId)
+  ));
+  const issues = [];
+  const placeholder = (value) => /^(?:\[|tbd\b|todo\b|unknown\b|replace\b|complete before\b)/i.test(String(value || "").trim());
+  if (placeholder(routeSet.primaryLane?.destination)) {
+    issues.push({
+      code: "incomplete-reporting-route-proposal",
+      resourceId: routeSet.id,
+      message: `${routeSet.title} needs the real normal reporting destination before it can be proposed.`
+    });
+  }
+  if (applicableRequirements.some(({ requiredLanes }) => requiredLanes?.includes("alternate"))) {
+    if (!routeSet.alternateLane || placeholder(routeSet.alternateLane.destination)) {
+      issues.push({
+        code: "incomplete-reporting-route-proposal",
+        resourceId: routeSet.id,
+        message: `${routeSet.title} needs the real fallback reporting destination before it can be proposed.`
+      });
+    }
+  }
+  if (applicableRequirements.some(({ distinctChannels }) => distinctChannels)
+    && routeSet.alternateLane?.channelKind === routeSet.primaryLane?.channelKind) {
+    issues.push({
+      code: "reporting-route-channel-not-distinct",
+      resourceId: routeSet.id,
+      message: `${routeSet.title} needs different normal and fallback channel types before it can be proposed.`
+    });
+  }
+  if (applicableRequirements.some(({ independentDependencies }) => independentDependencies)
+    && !reportingRouteLanesIndependent(
+      routeSet,
+      records,
+      options.at || new Date(),
+      options
+    )) {
+    issues.push({
+      code: "reporting-route-dependencies-not-independent",
+      resourceId: routeSet.id,
+      message: `${routeSet.title} needs independent normal and fallback channel dependencies or an applicable Exception before it can be proposed.`
+    });
+  }
+  return issues;
+}
+
+export function reportingRouteLanesIndependent(record, records, at, options = {}) {
+  if (!record.alternateLane) return false;
+  for (const lane of [record.primaryLane, record.alternateLane]) {
+    if (!lane?.dependencyBasis) return false;
+    if (lane.dependencyBasis === "cataloged" && !lane.dependencySystemIds?.length) return false;
+    if (lane.dependencyBasis === "none" && !String(lane.dependencyRationale || "").trim()) return false;
+  }
+  const primary = new Set(record.primaryLane?.dependencySystemIds || []);
+  const overlap = (record.alternateLane.dependencySystemIds || []).filter((id) => primary.has(id));
+  if (!overlap.length) return true;
+  const timezone = options.timezone || record.approval?.timezone || "UTC";
+  let date;
+  let availableDate;
+  try {
+    date = localDateTimeValue(instant(at, "Reporting Route assessment time"), timezone).slice(0, 10);
+    availableDate = localDateTimeValue(
+      instant(options.availableAt || at, "Reporting Route support availability time"),
+      timezone
+    ).slice(0, 10);
+  } catch {
+    return false;
+  }
+  return records.some((candidate) => (
+    candidate.type === "exception"
+    && candidate.status === "approved"
+    && candidate.reportingRouteSetId === record.id
+    && candidate.reportingRouteLanePair === "primary-alternate"
+    && overlap.every((id) => candidate.dependencySystemIds?.includes(id))
+    && candidate.approval?.approvedOn <= date
+    && candidate.approval?.approvedOn <= availableDate
+    && candidate.approval?.expiresOn >= date
+    && reportingRouteFixedEvidence(
+      records,
+      candidate.id,
+      candidate.evidenceIds,
+      candidate.approval?.approvedOn,
+      timezone,
+      { root: options.root, commit: options.commit, availableAt: options.availableAt || at }
+    ).length > 0
+  ));
+}
+
 export function reportingRouteSourceEffective(source, at, timezone = "UTC") {
   const when = instant(at, "Source assessment time");
   if (!reportingRouteSourceMayApply(source)) return false;
@@ -299,6 +449,11 @@ export function reportingRouteSourceMayApply(source) {
   return false;
 }
 
+export function reportingRouteSourceMayBecomeEffective(source) {
+  return REPORTING_ROUTE_REQUIREMENT_SOURCE_TYPES.has(source?.type)
+    && !["superseded", "retired", "closed", "archived"].includes(source.status);
+}
+
 export function reportingRouteSetInterval(routeSet) {
   if (!["approved", "canceled"].includes(routeSet?.status) || !routeSet.approval?.effectiveAt) return null;
   return {
@@ -524,6 +679,32 @@ export function reportingRouteHistory(loaded, routeSetId) {
   return getDataRecordHistoryIndex(loaded.root).historiesById.get(routeSetId) || [];
 }
 
+export function reportingRouteExactHistoryEntry(loaded, routeSet, head) {
+  return reportingRouteHistory(loaded, routeSet.id).find((summary) => {
+    if (head && !isDataHistoryAncestor(loaded, summary.commit, head)) return false;
+    const source = getFileAtRevision(loaded.root, summary.commit, summary.path);
+    try { return source && JSON.stringify(JSON.parse(source)) === JSON.stringify(routeSet); } catch { return false; }
+  }) || null;
+}
+
+export function reportingRouteCommitTimestamp(loaded, routeSetId, commit) {
+  return reportingRouteHistory(loaded, routeSetId)
+    .find(({ commit: changedAt }) => changedAt === commit)?.timestamp || null;
+}
+
+export function reportingRouteProposalAssessmentTime(timestamp, assessmentAt = new Date()) {
+  let commitAt;
+  let assessedAt;
+  try {
+    commitAt = instant(timestamp, "Proposal commit time");
+    assessedAt = instant(assessmentAt, "Proposal assessment time");
+  } catch {
+    return null;
+  }
+  if (commitAt.getTime() > assessedAt.getTime() + CONTEMPORANEOUS_COMMIT_WINDOW_MS) return null;
+  return commitAt > assessedAt ? assessedAt : commitAt;
+}
+
 export function recordsAtRevision(loaded, commit) {
   const index = getDataRecordHistoryIndex(loaded.root);
   const records = [];