filegrc 0.3.4 → 0.4.0

package/src/git.js

@@ -1,14 +1,19 @@
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { relative, resolve, sep } from "node:path";
+import { performance } from "node:perf_hooks";
 import { isSafeGitName } from "./git-name.js";
-import { serializeWorkspaceMutation } from "./mutation.js";
+import { serializeWorkspaceMutation, withDeferredWorkspaceValidation } from "./mutation.js";
 import { resolveWorkspaceRoot } from "./paths.js";
-import { validateWorkspace } from "./validate.js";
+import { measureTiming, measureTimingSync, timingEnabled } from "./timing.js";
+import { fingerprintWorkspace, validateWorkspace } from "./validate.js";
 import { loadWorkspace } from "./workspace.js";
 
 const lastSuccessfulSynchronizations = new Map();
+const workspaceHistoryCache = new Map();
+const backgroundSynchronizations = new Map();
+export const BROWSER_VALIDATION = Symbol("filegrc.browserValidation");
 
 export function getGitSummary(input = process.cwd()) {
   const root = resolveWorkspaceRoot(input);
@@ -65,6 +70,13 @@ export function getWorkspaceHistories(input, relativePaths, limitPerFile = 12) {
   const wanted = new Set(relativePaths);
   const histories = new Map([...wanted].map((path) => [path, []]));
   if (!wanted.size) return histories;
+  const head = tryGit(root, ["rev-parse", "HEAD"]) || null;
+  const cached = workspaceHistoryCache.get(root);
+  if (cached?.head === head && cached.limitPerFile === limitPerFile) {
+    for (const path of wanted) histories.set(path, cached.histories.get(path) ?? []);
+    return histories;
+  }
+  const allHistories = new Map();
   try {
     const output = git(root, ["log", "--relative", "--format=%x1e%H%x1f%aI%x1f%an%x1f%s", "--name-only", "--", "data"]);
     for (const block of output.split("\x1e")) {
@@ -72,13 +84,16 @@ export function getWorkspaceHistories(input, relativePaths, limitPerFile = 12) {
       if (lines.length < 2) continue;
       const commit = parseLogLine(lines[0]);
       for (const path of lines.slice(1)) {
-        const history = histories.get(path);
-        if (history && history.length < limitPerFile) history.push(commit);
+        if (!allHistories.has(path)) allHistories.set(path, []);
+        const history = allHistories.get(path);
+        if (history.length < limitPerFile) history.push(commit);
       }
     }
   } catch {
     // An uncommitted workspace has no history yet.
   }
+  workspaceHistoryCache.set(root, { head, limitPerFile, histories: allHistories });
+  for (const path of wanted) histories.set(path, allHistories.get(path) ?? []);
   return histories;
 }
 
@@ -184,11 +199,14 @@ export async function retryBrowserSync(input = process.cwd(), options = {}) {
   return serializeWorkspaceMutation(input, async (root) => {
     const config = await getRepositoryConfig(root);
     if (config.mode !== "trunk") throw new Error("Retry sync is available only in trunk repository mode.");
+    if (backgroundSynchronizations.get(root)?.status === "syncing") {
+      throw new Error("A FileGRC background push is already in progress. Wait for it to finish before retrying sync.");
+    }
     if (options.allowNonAuthoritativeWrites === true) {
       throw new Error("Retry sync is disabled while the development write override is active.");
     }
     const before = requireTrunkPreconditions(root, config, { allowAhead: true });
-    fetchConfiguredRemote(root, config.remote);
+    await fetchConfiguredRemote(root, config.remote);
     const synchronized = inspectTrunkRepository(root, config, getGitSummary(root));
     if (synchronized.behind > 0 && synchronized.ahead > 0) {
       throw new Error("The authoritative branch has diverged from its upstream. FileGRC will not merge or rebase it. Reconcile the repository with Git, then reload.");
@@ -200,13 +218,14 @@ export async function retryBrowserSync(input = process.cwd(), options = {}) {
     if (ready.ahead > 0 && !ready.pendingCommitsFilegrcOnly) {
       throw new Error("At least one commit ahead of upstream changes files outside this FileGRC workspace. FileGRC will not push it. Reconcile the repository with Git.");
     }
-    if (ready.ahead > 0) pushConfiguredBranch(root, config);
+    if (ready.ahead > 0) await pushConfiguredBranch(root, config);
     const after = inspectTrunkRepository(root, config, getGitSummary(root));
     if (after.ahead !== 0 || after.behind !== 0) {
       throw new Error("The authoritative branch is still not synchronized. Reload the repository state before trying again.");
     }
     const synchronizedAt = new Date().toISOString();
     lastSuccessfulSynchronizations.set(root, synchronizedAt);
+    backgroundSynchronizations.delete(root);
     return {
       commit: after.currentCommit,
       shortCommit: after.currentCommit?.slice(0, 8) ?? null,
@@ -220,7 +239,7 @@ export async function retryBrowserSync(input = process.cwd(), options = {}) {
 
 async function runTrunkMutationUnlocked(root, config, options, task) {
   requireTrunkPreconditions(root, config);
-  fetchConfiguredRemote(root, config.remote);
+  await fetchConfiguredRemote(root, config.remote);
   let synchronized = inspectTrunkRepository(root, config, getGitSummary(root));
   if (synchronized.ahead > 0 && synchronized.behind > 0) {
     throw new Error("The authoritative branch has diverged from its upstream. FileGRC will not merge or rebase it. Reconcile the repository with Git, then reload.");
@@ -238,13 +257,18 @@ async function runTrunkMutationUnlocked(root, config, options, task) {
 
   let result;
   let subject;
+  let validationProof;
   try {
-    result = await task(root);
+    result = await withDeferredWorkspaceValidation(() => task(root));
     subject = generatedCommitMessage(typeof options?.message === "function" ? options.message(result) : options?.message);
     const validation = await validateWorkspace(root);
     if (!validation.ok) {
       throw new Error(`The workspace has ${validation.counts.errors} validation ${validation.counts.errors === 1 ? "error" : "errors"}. The browser change was rolled back.`);
     }
+    validationProof = {
+      validation,
+      fingerprint: (await fingerprintWorkspace(validation.loaded)).fingerprint
+    };
     assertNoOutsideWorktreeChanges(root);
   } catch (error) {
     try {
@@ -255,6 +279,19 @@ async function runTrunkMutationUnlocked(root, config, options, task) {
     throw error;
   }
 
+  if (!getGitSummary(root).changes.length && options?.allowNoChanges === true) {
+    return withValidationProof({
+      ...result,
+      synchronization: {
+        status: "unchanged",
+        commit: synchronized.currentCommit,
+        shortCommit: synchronized.currentCommit?.slice(0, 8) ?? null,
+        upstream: synchronized.upstream,
+        synchronizedAt: lastSuccessfulSynchronizations.get(root) ?? null,
+        pushError: null
+      }
+    }, validationProof);
+  }
   if (!getGitSummary(root).changes.length) {
     throw new Error("The browser action did not change any FileGRC workspace files.");
   }
@@ -265,35 +302,100 @@ async function runTrunkMutationUnlocked(root, config, options, task) {
   assertNoOutsideWorktreeChanges(root, false);
   assertOnlyWorkspaceFilesStaged(root);
   try {
-    gitForWrite(root, ["commit", "-m", subject, "--", "."], "create the FileGRC browser commit");
+    measureTimingSync("commit", () => {
+      gitForWrite(root, ["commit", "-m", subject, "--", "."], "create the FileGRC browser commit");
+    });
   } catch (error) {
     throw new Error(`${error.message} The saved files remain in the Git worktree and later browser changes are blocked.`);
   }
 
   const committed = getGitSummary(root);
-  let pushError = null;
-  try {
-    pushConfiguredBranch(root, config);
-  } catch (error) {
-    pushError = `${error.message} The local FileGRC commit was retained. Use Retry sync after the remote is available.`;
-  }
-  const after = inspectTrunkRepository(root, config, getGitSummary(root));
-  let synchronizedAt = null;
-  if (!pushError && after.ahead === 0 && after.behind === 0) {
-    synchronizedAt = new Date().toISOString();
-    lastSuccessfulSynchronizations.set(root, synchronizedAt);
-  }
-  return {
+  queueBackgroundPush(root, config, committed, options?.backgroundPushDelayMs);
+  return withValidationProof({
     ...result,
     synchronization: {
-      status: pushError ? "not-synced" : "synced",
+      status: "syncing",
       commit: committed.commit,
       shortCommit: committed.shortCommit,
-      upstream: after.upstream,
-      synchronizedAt,
-      pushError
+      upstream: synchronized.upstream,
+      synchronizedAt: null,
+      pushError: null
+    }
+  }, validationProof);
+}
+
+function withValidationProof(result, proof) {
+  if (result && typeof result === "object") {
+    Object.defineProperty(result, BROWSER_VALIDATION, { value: proof });
+  }
+  return result;
+}
+
+function queueBackgroundPush(root, config, committed, delayMs = 0) {
+  backgroundSynchronizations.set(root, {
+    status: "syncing",
+    commit: committed.commit,
+    shortCommit: committed.shortCommit,
+    startedAt: new Date().toISOString(),
+    error: null
+  });
+  const start = () => {
+    try {
+      const ready = requireTrunkPreconditions(root, config, { allowAhead: true });
+      if (ready.currentCommit !== committed.commit) {
+        throw new Error("The authoritative branch changed after FileGRC created its browser commit. FileGRC did not push it.");
+      }
+      if (ready.behind > 0) {
+        throw new Error("The authoritative branch changed upstream after FileGRC created its browser commit. FileGRC did not push it.");
+      }
+      if (ready.ahead < 1 || !ready.pendingCommitsFilegrcOnly) {
+        throw new Error("The pending commits are no longer limited to this FileGRC workspace. FileGRC did not push them.");
+      }
+      void finishBackgroundPush(root, config, committed);
+    } catch (error) {
+      recordBackgroundPushFailure(root, committed, error);
     }
   };
+  const delay = Math.max(0, Math.min(Number(delayMs) || 0, 30_000));
+  if (delay) setTimeout(start, delay);
+  else setImmediate(start);
+}
+
+async function finishBackgroundPush(root, config, committed) {
+  const started = performance.now();
+  let outcome = "failed";
+  try {
+    await pushConfiguredBranch(root, config, committed.commit);
+    const after = inspectTrunkRepository(root, config, getGitSummary(root), { ignoreBackground: true });
+    if (after.ahead !== 0 || after.behind !== 0) {
+      throw new Error("The authoritative branch is still not synchronized after the background push.");
+    }
+    const synchronizedAt = new Date().toISOString();
+    lastSuccessfulSynchronizations.set(root, synchronizedAt);
+    backgroundSynchronizations.delete(root);
+    outcome = "synced";
+  } catch (error) {
+    recordBackgroundPushFailure(root, committed, error);
+  } finally {
+    if (timingEnabled()) {
+      console.error(`[filegrc timing] ${JSON.stringify({
+        operation: "background-sync",
+        push: { count: 1, durationMs: performance.now() - started },
+        outcome
+      })}`);
+    }
+  }
+}
+
+function recordBackgroundPushFailure(root, committed, error) {
+  backgroundSynchronizations.set(root, {
+    status: "failed",
+    commit: committed.commit,
+    shortCommit: committed.shortCommit,
+    startedAt: backgroundSynchronizations.get(root)?.startedAt ?? null,
+    finishedAt: new Date().toISOString(),
+    error: `${error.message} The local FileGRC commit was retained. Use Retry sync after the remote is available.`
+  });
 }
 
 async function commitWorkspaceUnlocked(root, message) {
@@ -412,14 +514,16 @@ function syncReadySummary(root, action) {
 async function getRepositoryConfig(root) {
   const loaded = await loadWorkspace(root);
   const renderer = loaded.resources.find(({ type, id }) => type === "renderer-settings" && id === "renderer-settings");
-  const mode = renderer?.repositoryMode === "trunk" ? "trunk" : "manual";
-  const authoritativeBranch = cleanGitName(renderer?.authoritativeBranch, "main");
-  const remote = cleanGitName(renderer?.repositoryRemote, "origin");
+  const mode = renderer?.repositoryMode;
+  const authoritativeBranch = cleanGitName(renderer?.authoritativeBranch);
+  const remote = cleanGitName(renderer?.repositoryRemote);
   return {
     mode,
     authoritativeBranch,
     remote,
-    configurationError: !isSafeGitName(authoritativeBranch)
+    configurationError: !["trunk", "manual"].includes(mode)
+      ? "Repository mode is missing or invalid. Run the model migration or update renderer settings."
+      : !isSafeGitName(authoritativeBranch)
       ? "The configured authoritative branch is not a safe Git branch name. Update renderer settings before using browser writes."
       : !isSafeGitName(remote)
         ? "The configured repository remote is not a safe Git remote name. Update renderer settings before using browser writes."
@@ -427,7 +531,8 @@ async function getRepositoryConfig(root) {
   };
 }
 
-function inspectTrunkRepository(root, config, summary = getGitSummary(root)) {
+function inspectTrunkRepository(root, config, summary = getGitSummary(root), options = {}) {
+  const background = options.ignoreBackground ? null : backgroundSynchronizations.get(root);
   const base = {
     mode: "trunk",
     authoritativeBranch: config.authoritativeBranch,
@@ -442,6 +547,14 @@ function inspectTrunkRepository(root, config, summary = getGitSummary(root)) {
     lastSuccessfulSynchronization: lastSuccessfulSynchronizations.get(root) ?? null,
     wholeWorktreeClean: summary.available ? wholeWorktreeClean(root) : null,
     operationInProgress: summary.available ? repositoryOperation(root) : null,
+    backgroundSynchronization: background ? {
+      status: background.status,
+      commit: background.commit,
+      shortCommit: background.shortCommit,
+      startedAt: background.startedAt,
+      finishedAt: background.finishedAt ?? null,
+      error: background.error
+    } : null,
     writesAllowed: false
   };
   if (config.configurationError) {
@@ -513,6 +626,16 @@ function inspectTrunkRepository(root, config, summary = getGitSummary(root)) {
       message: "The Git worktree has uncommitted changes. Commit, discard, or move them with Git before using browser writes."
     };
   }
+  if (background?.status === "syncing" && background.commit === summary.commit) {
+    return {
+      ...details,
+      status: "syncing",
+      label: "Syncing",
+      message: `The FileGRC commit ${background.shortCommit} is saved locally and is being pushed to ${expectedUpstream}.`,
+      writesAllowed: false,
+      retrySafe: false
+    };
+  }
   if (counts.ahead === null || counts.behind === null) {
     return {
       ...details,
@@ -523,19 +646,27 @@ function inspectTrunkRepository(root, config, summary = getGitSummary(root)) {
   }
   if (counts.ahead > 0 || counts.behind > 0) {
     const external = counts.ahead > 0 && !pendingCommitsFilegrcOnly;
+    const backgroundFailure = background?.status === "failed"
+      && background.commit === summary.commit
+      && counts.ahead > 0
+      && counts.behind === 0
+      && pendingCommitsFilegrcOnly
+      ? background.error
+      : null;
     return {
       ...details,
       status: "not-synced",
       label: "Not synced",
-      message: external
+      message: backgroundFailure || (external
         ? "A commit ahead of upstream changes files outside this FileGRC workspace. Reconcile it with Git. FileGRC will not push it."
         : counts.ahead > 0 && counts.behind > 0
           ? "The authoritative branch has diverged from upstream. Reconcile it with Git. FileGRC will not merge or rebase it."
           : counts.ahead > 0
             ? "FileGRC-only commits are waiting to be pushed. Use Retry sync."
-            : "The authoritative branch is behind upstream. The next browser mutation will fast-forward before writing.",
+            : "The authoritative branch is behind upstream. The next browser mutation will fast-forward before writing."),
       writesAllowed: counts.ahead === 0 && counts.behind > 0,
-      retrySafe: counts.ahead > 0 && counts.behind === 0 && pendingCommitsFilegrcOnly
+      retrySafe: counts.ahead > 0 && counts.behind === 0 && pendingCommitsFilegrcOnly,
+      backgroundSyncError: backgroundFailure
     };
   }
   return {
@@ -564,20 +695,20 @@ function requireTrunkPreconditions(root, config, options = {}) {
   return state;
 }
 
-function fetchConfiguredRemote(root, remote) {
-  gitForWrite(root, ["fetch", "--prune", "--", remote], `fetch ${remote}`);
+async function fetchConfiguredRemote(root, remote) {
+  return measureTiming("fetch", () => gitForWriteAsync(root, ["fetch", "--prune", "--", remote], `fetch ${remote}`));
 }
 
 function fastForwardConfiguredBranch(root, upstream) {
   gitForWrite(root, ["merge", "--ff-only", "--", upstream], `fast-forward from ${upstream}`);
 }
 
-function pushConfiguredBranch(root, config) {
-  gitForWrite(
+async function pushConfiguredBranch(root, config, source = "HEAD") {
+  return measureTiming("push", () => gitForWriteAsync(
     root,
-    ["push", "--porcelain", "--", config.remote, `HEAD:refs/heads/${config.authoritativeBranch}`],
+    ["push", "--porcelain", "--", config.remote, `${source}:refs/heads/${config.authoritativeBranch}`],
     `push ${config.authoritativeBranch} to ${config.remote}`
-  );
+  ));
 }
 
 function wholeWorktreeClean(root) {
@@ -772,6 +903,73 @@ function gitForWrite(cwd, args, action = "create the commit") {
   }
 }
 
+async function gitForWriteAsync(cwd, args, action = "update the repository") {
+  return new Promise((resolve, reject) => {
+    const child = spawn("git", args, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: process.platform !== "win32",
+      env: {
+        ...process.env,
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_MERGE_AUTOEDIT: "no"
+      }
+    });
+    const stdout = [];
+    const stderr = [];
+    let size = 0;
+    let timedOut = false;
+    let forceKillTimer = null;
+    const terminate = (signal) => {
+      try {
+        if (process.platform !== "win32" && child.pid) process.kill(-child.pid, signal);
+        else child.kill(signal);
+      } catch {
+        try {
+          child.kill(signal);
+        } catch {
+          // The process may have exited between the timeout and termination.
+        }
+      }
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      terminate("SIGTERM");
+      forceKillTimer = setTimeout(() => terminate("SIGKILL"), 2_000);
+    }, 30_000);
+    child.stdout.on("data", (chunk) => {
+      size += chunk.length;
+      if (size <= 20_000_000) stdout.push(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      size += chunk.length;
+      if (size <= 20_000_000) stderr.push(chunk);
+    });
+    child.once("error", (error) => {
+      clearTimeout(timer);
+      clearTimeout(forceKillTimer);
+      reject(new Error(`Git could not ${action}. ${sanitizeGitErrorMessage(error.message)}`));
+    });
+    child.once("close", (code) => {
+      clearTimeout(timer);
+      clearTimeout(forceKillTimer);
+      const output = Buffer.concat(stdout).toString("utf8").trim();
+      const errorOutput = Buffer.concat(stderr).toString("utf8").trim();
+      if (code === 0 && !timedOut && size <= 20_000_000) {
+        resolve(output);
+        return;
+      }
+      const detail = size > 20_000_000
+        ? "Git output exceeded 20 MB."
+        : timedOut
+          ? "Git timed out after 30 seconds."
+          : errorOutput || output || `Git exited with status ${code}.`;
+      const message = sanitizeGitErrorMessage(detail);
+      reject(new Error(`Git could not ${action}. ${message}`));
+    });
+  });
+}
+
 export function sanitizeGitErrorMessage(value) {
   return String(value || "Git returned no error detail.")
     .replace(/\b([a-z][a-z0-9+.-]*:\/\/)[^/\s@]+@/gi, "$1[redacted]@")

package/src/index.js

@@ -3,9 +3,9 @@ export { buildAgentGuide, findResourceReferences, listResourceTypes, scaffoldRes
 export { assessAuditPreparation, prepareAuditWorkspace } from "./audit-preparation.js";
 export { buildWorkspace } from "./build.js";
 export { generateEvidencePacket, prepareEvidencePacket, writeEvidencePacket } from "./evidence-packet.js";
-export { ensureEvidenceTestDrafts, planEvidenceTestDrafts } from "./evidence-tests.js";
 export {
   addEvidenceAttachment,
+  applyResourceBatch,
   createResource,
   createResourceAndLink,
   createResources,
@@ -29,6 +29,7 @@ export {
 } from "./git.js";
 export { generateModelDocumentation } from "./model-docs.js";
 export { renderMarkdown } from "./markdown.js";
+export { migrateModel, planModelMigration } from "./model-migration.js";
 export {
   completeObligationAction,
   completeObligationEvent,
@@ -36,11 +37,9 @@ export {
   createObligationEvent,
   planObligations
 } from "./obligations.js";
-export { assessProgramReadiness } from "./program-readiness.js";
+export { assessEvidenceMap, assessProgramReadiness } from "./program-readiness.js";
 export {
   buildAgentProgramPath,
-  policyEventName,
-  POLICY_EVENT_NAMES,
   PROGRAM_PATH,
   RESOURCE_INSTRUCTIONS,
   resourceProgramContext
@@ -53,9 +52,10 @@ export {
   nextCalendarOccurrence
 } from "./recurrence.js";
 export { searchResources, searchableValues } from "./search.js";
+export { effectiveResourceStatus } from "./resource-status.js";
 export { createFilegrcServer, serveWorkspace } from "./server.js";
 export { normalizeSetupPayload, planWorkspaceSetup, setupWorkspace, summarizeSetupResult } from "./setup.js";
-export { createAppState } from "./state.js";
+export { createAppState, createResourceDetail } from "./state.js";
 export { currentCalendarDate, formatCalendarDate, formatLocalDateTime } from "./time.js";
 export { validateWorkspace } from "./validate.js";
 export { indexResources, loadWorkspace } from "./workspace.js";

package/src/model-docs.js

@@ -15,7 +15,7 @@ export function generateModelDocumentation(model) {
     "",
     "## Program path",
     "",
-    "The renderer, CLI, generated agent instructions, and this reference use the same six-step lifecycle:",
+    "The renderer, CLI, generated agent instructions, and this reference use the same five-step lifecycle:",
     "",
     ...programPath.flatMap((stage) => [
       `### Step ${stage.number}. ${stage.title}`,
@@ -35,6 +35,52 @@ export function generateModelDocumentation(model) {
       ...stage.commands.map((command) => `- \`${command}\``),
       ""
     ]),
+    "## Relation groups",
+    "",
+    "Relationship fields use the named groups below. The registry expands each group to explicit resource types, so no relationship accepts an unrestricted wildcard.",
+    "",
+    "| Group | Resource types |",
+    "| --- | --- |",
+    ...Object.entries(model.relationGroups || {}).map(([name, types]) => (
+      `| \`${name}\` | ${types.map((type) => `\`${type}\``).join(", ")} |`
+    )),
+    "",
+    "## Relationship constraints",
+    "",
+    "Relationship constraints prevent cycles and duplicate active authority or access records.",
+    "",
+    ...((model.relationshipConstraints?.acyclic || []).map((constraint) => (
+      `- \`${constraint.resourceType}.${constraint.field}\` must be acyclic.`
+    ))),
+    ...((model.relationshipConstraints?.unique || []).map((constraint) => (
+      `- \`${constraint.resourceType}\` records in ${constraint.statuses.map((status) => `\`${status}\``).join(", ")} must be unique by ${constraint.fields.map((field) => `\`${field}\``).join(", ")}.`
+    ))),
+    "",
+    "## Obligation activities",
+    "",
+    "The model owns each activity name, allowed recurrence modes and scope types, its default completion record, and every record type that can prove completion.",
+    "",
+    "| Activity | Title | Recurrence | Scope resource types | Default completion | Accepted completion records |",
+    "| --- | --- | --- | --- | --- | --- |",
+    ...Object.entries(model.obligationActivities || {}).map(([name, activity]) => (
+      `| \`${name}\` | ${escapeCell(activity.title)} | ${activity.recurrenceModes.map((mode) => `\`${mode}\``).join(", ")} | ${activity.scopeResourceTypes.map((type) => `\`${type}\``).join(", ")} | \`${activity.completionType}\` | ${activity.completionResourceTypes.map((type) => `\`${type}\``).join(", ")} |`
+    )),
+    "",
+    "## Policy events",
+    "",
+    "The model owns each event title and the minimum and maximum count for each subject resource type.",
+    "",
+    "| Event | Title | Subject rules |",
+    "| --- | --- | --- |",
+    ...Object.entries(model.policyEvents || {}).map(([name, event]) => (
+      `| \`${name}\` | ${escapeCell(event.title)} | ${event.subjectRules.map(({ resourceType, minimum = 0, maximum }) => `\`${resourceType}\` ${minimum}..${Number.isInteger(maximum) ? maximum : "*"}`).join(", ")} |`
+    )),
+    "",
+    "## Nested object schemas",
+    "",
+    "Named object schemas reject unknown keys unless the schema explicitly allows a typed map or arbitrary JSON. Conditional properties are valid only for the selected discriminator.",
+    "",
+    ...Object.entries(model.objectTypes || {}).flatMap(([name, schema]) => objectTypeDocumentation(name, schema)),
     "## Common fields",
     "",
     "| Field | Type | Required | Meaning |",
@@ -53,7 +99,7 @@ export function generateModelDocumentation(model) {
     "",
     "## Program and audit readiness defaults",
     "",
-    "Program Readiness checks management scope, policy adoption, control implementation, authoritative source configuration, and verified test captures without requiring an audit record. Audit Readiness starts after a CPA firm is engaged and uses the defaults below to prepare Type 1 and Type 2 fieldwork.",
+    "Program Readiness checks management scope, policy adoption, control implementation, and authoritative evidence mapping without requiring an audit record. Audit Readiness starts after a CPA firm is engaged and uses the defaults below to prepare Type 1 and Type 2 fieldwork.",
     "",
     "Management documents:",
     "",
@@ -66,9 +112,9 @@ export function generateModelDocumentation(model) {
     "Authoritative systems of record:",
     "",
     ...model.evidenceSourceFamilies.map((item) => (
-      item.collectionTestRequired === false
-        ? `- **${item.title}** (${item.sourceKinds.map((kind) => `\`${kind}\``).join(", ")}): ${item.description} filegrc operating records: ${item.operationRecordTypes.map((type) => `\`${type}\``).join(", ")}. No separate collection test is required. ${item.timing}`
-        : `- **${item.title}** (${item.sourceKinds.map((kind) => `\`${kind}\``).join(", ")}): ${item.description} Test external collection: ${item.testPrompt} ${item.timing}`
+      item.filegrcManaged === true
+        ? `- **${item.title}** (${item.sourceKinds.map((kind) => `\`${kind}\``).join(", ")}): ${item.description} FileGRC operating records: ${item.operationRecordTypes.map((type) => `\`${type}\``).join(", ")}. Expected evidence: ${item.evidencePrompt} ${item.timing}`
+        : `- **${item.title}** (${item.sourceKinds.map((kind) => `\`${kind}\``).join(", ")}): ${item.description} Expected evidence: ${item.evidencePrompt} ${item.timing}`
     )),
     "",
     "## Resource groups",
@@ -143,7 +189,12 @@ function choiceLabel(name) {
 }
 
 function fieldType(field) {
-  if (field.type === "array") return `array of ${field.items ?? "values"}`;
+  if (field.type === "array") {
+    return field.itemObjectType
+      ? `array of object (\`${field.itemObjectType}\`)`
+      : `array of ${field.items ?? "values"}`;
+  }
+  if (field.type === "object" && field.objectType) return `object (\`${field.objectType}\`)`;
   return field.format && field.format !== field.type ? `${field.type} (${field.format})` : field.type;
 }
 
@@ -151,14 +202,44 @@ function fieldNotes(field) {
   return [
     field.label,
     field.values ? `Values: ${field.values.map((item) => `\`${item}\``).join(", ")}` : "",
+    field.registry ? `Values come from the \`${field.registry}\` registry.` : "",
+    field.relationGroup ? `Relation group: \`${field.relationGroup}\`.` : "",
     field.relation ? `References: ${field.relation.map((item) => `\`${item}\``).join(", ")}` : "",
     field.minimum !== undefined ? `Minimum: \`${field.minimum}\`.` : "",
     field.maximum !== undefined ? `Maximum: \`${field.maximum}\`.` : "",
+    field.managed ? "Managed by filegrc." : "",
     field.disjointFrom ? `Must not overlap \`${field.disjointFrom}\`.` : "",
-    field.requiredWhen ? `Required when ${Object.entries(field.requiredWhen).map(([key, value]) => `\`${key}\` is \`${value}\``).join(" and ")}` : ""
+    field.requiredWhen ? `Required when ${conditionText(field.requiredWhen)}.` : "",
+    field.allowedWhen ? `Allowed when ${conditionText(field.allowedWhen)}.` : ""
   ].filter(Boolean).join(" ");
 }
 
+function objectTypeDocumentation(name, schema) {
+  const lines = [`### \`${name}\``, ""];
+  const properties = Object.entries(schema.properties || {});
+  if (properties.length) {
+    const required = new Set(schema.required || []);
+    lines.push("| Property | Type | Required | Notes |", "| --- | --- | --- | --- |");
+    for (const [propertyName, property] of properties) {
+      const requiredLabel = required.has(propertyName)
+        ? "Yes"
+        : property.requiredWhen
+          ? "Conditional"
+          : "No";
+      lines.push(`| \`${propertyName}\` | ${fieldType(property)} | ${requiredLabel} | ${escapeCell(fieldNotes(property))} |`);
+    }
+  } else if (schema.additionalProperties === true) {
+    lines.push("Allows arbitrary JSON properties.");
+  } else if (schema.additionalProperties) {
+    lines.push(`Allows dynamic keys whose values are ${fieldType(schema.additionalProperties)}.`);
+  } else {
+    lines.push("Does not allow properties.");
+  }
+  if (schema.keyFormat) lines.push("", `Key format: \`${schema.keyFormat}\`.`);
+  lines.push("");
+  return lines;
+}
+
 function escapeCell(value) {
   return String(value).replaceAll("|", "\\|").replaceAll("\n", " ");
 }