scrumrun 2.1.0 → 2.2.0

package/lib/runtime/policy-engine.js

@@ -9,9 +9,13 @@ const ENFORCEMENTS = new Set([
   "builtin:approval-gate",
   "builtin:read-only-path",
   "builtin:owner-work",
+  "builtin:canonical-write",
+  "builtin:canonical-truth",
+  "builtin:memory-candidate",
   "builtin:migration-integrity",
   "builtin:review-gate"
 ]);
+const SCOPES = new Set(["all", "intake", "execution", "mutation", "canonical", "memory", "migration", "validation", "learning", "completion", "commit", "release", "logs"]);
 
 function normalized(value) {
   return String(value || "").normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase();
@@ -66,7 +70,21 @@ function parseGuardrails(content) {
     const status = normalized(fields.status || "active").replace(/[._-]+$/, "");
     const enforcement = normalized(fields.enforcement || inferEnforcement(title, rule));
     const scope = (fields.scope || "all").split(/\s*,\s*/).map((value) => normalized(value)).filter(Boolean);
-    return { id: heading[1], title, rule, status, enforcement, scope, source: fields.source || null };
+    return {
+      id: heading[1],
+      title,
+      rule,
+      status,
+      enforcement,
+      scope,
+      source: fields.source || null,
+      explicit: {
+        status: Object.prototype.hasOwnProperty.call(fields, "status"),
+        enforcement: Object.prototype.hasOwnProperty.call(fields, "enforcement"),
+        scope: Object.prototype.hasOwnProperty.call(fields, "scope"),
+        rule: Object.prototype.hasOwnProperty.call(fields, "rule")
+      }
+    };
   });
 }
 
@@ -103,7 +121,7 @@ function requestMentionsPath(request, configuredPath) {
 }
 
 function evaluation(guardrail, status, code, message, evidence = []) {
-  return { guardrail: guardrail.id, status, code, message, enforcement: guardrail.enforcement, evidence };
+  return { guardrail: guardrail.id, status, code, message, enforcement: guardrail.enforcement, scope: guardrail.scope, evidence };
 }
 
 function evaluateGuardrail(guardrail, context) {
@@ -128,6 +146,12 @@ function evaluateGuardrail(guardrail, context) {
     }
     case "builtin:owner-work":
       return evaluation(guardrail, "deferred", "OWNER_WORK", "Mutation-time hashes, scoped staging, and transaction preconditions enforce owner-work preservation.");
+    case "builtin:canonical-write":
+      return evaluation(guardrail, "deferred", "CANONICAL_WRITE", "Canonical writes require the lossless transaction gateway and post-write validation.");
+    case "builtin:canonical-truth":
+      return evaluation(guardrail, "deferred", "CANONICAL_TRUTH", "Completion must prove that generated caches did not replace canonical Markdown truth.");
+    case "builtin:memory-candidate":
+      return evaluation(guardrail, "deferred", "MEMORY_CANDIDATE", "Learning and memory mutations must preserve candidate-first AI knowledge.");
     case "builtin:migration-integrity":
       return evaluation(guardrail, /migrat|migrac/.test(requestText) ? "deferred" : "passed", "MIGRATION_INTEGRITY", /migrat|migrac/.test(requestText) ? "The explicit migration preflight/apply/rollback gate must enforce this Guardrail." : "Request does not invoke migration.");
     case "builtin:review-gate":
@@ -150,15 +174,48 @@ function evaluatePolicy(context) {
     evaluations.push({ guardrail: "I-11", status: "blocked", code: "SECRET_BOUNDARY", message: "Request appears to contain a secret; remove or redact it.", enforcement: "builtin", evidence: ["request"] });
   }
   const blocked = evaluations.filter((item) => item.status === "blocked");
+  const postApprovalScopes = new Set(["all", "execution", "mutation", "canonical", "memory", "migration", "validation", "learning", "completion", "commit", "release", "logs"]);
+  const continuousEnforcement = new Set(["builtin:secret-boundary", "builtin:owner-work", "builtin:read-only-path", "builtin:canonical-write", "builtin:canonical-truth", "builtin:memory-candidate"]);
+  const obligations = evaluations
+    .filter((item) => item.status === "deferred" || (item.status === "passed" && continuousEnforcement.has(item.enforcement) && (item.scope || []).some((scope) => postApprovalScopes.has(scope))))
+    .map((item) => ({
+      guardrail: item.guardrail,
+      code: item.code,
+      enforcement: item.enforcement,
+      scope: item.scope,
+      gate: obligationGate(item)
+    }));
   return {
     status: blocked.length ? "blocked" : "passed",
     checked: [...new Set(evaluations.map((item) => item.guardrail))],
     deferred: [...new Set(evaluations.filter((item) => item.status === "deferred").map((item) => item.guardrail))],
+    obligations,
     evaluations,
     violations: blocked.map((item) => `${item.guardrail} ${item.code}: ${item.message}`)
   };
 }
 
+function obligationGate(evaluationResult) {
+  const scopes = evaluationResult.scope || [];
+  for (const gate of ["mutation", "migration", "validation", "learning", "completion", "commit", "release", "memory", "canonical"]) {
+    if (scopes.includes(gate)) return gate;
+  }
+  switch (evaluationResult.enforcement) {
+    case "builtin:owner-work":
+    case "builtin:read-only-path":
+    case "builtin:secret-boundary":
+      return "mutation";
+    case "builtin:migration-integrity":
+      return "migration";
+    case "builtin:memory-candidate":
+      return "learning";
+    case "builtin:review-gate":
+      return "commit";
+    default:
+      return "completion";
+  }
+}
+
 function validateGuardrailDocument(content) {
   const records = parseGuardrails(content);
   const errors = [];
@@ -169,14 +226,40 @@ function validateGuardrailDocument(content) {
     if (!GUARDRAIL_STATUSES.has(record.status)) errors.push(`${record.id} has invalid status: ${record.status || "missing"}`);
     if (!record.rule.trim()) errors.push(`${record.id} has no rule content`);
     if (!ENFORCEMENTS.has(record.enforcement)) errors.push(`${record.id} has unknown enforcement: ${record.enforcement}`);
+    if (!record.scope.length) errors.push(`${record.id} has no scope`);
+    for (const scope of record.scope) if (!SCOPES.has(scope)) errors.push(`${record.id} has unknown scope: ${scope}`);
   }
   return { records, errors };
 }
 
+function normalizeGuardrailDocument(content) {
+  const source = String(content || "");
+  const records = parseGuardrails(source);
+  const headings = [...source.matchAll(/^## (GR-\d{3,})\s*[-—:]\s*([^\r\n]+)$/gm)];
+  let next = source;
+  for (let index = headings.length - 1; index >= 0; index--) {
+    const heading = headings[index];
+    const record = records.find((item) => item.id === heading[1]);
+    if (!record) continue;
+    const missing = [];
+    if (!record.explicit.status) missing.push(`Status: ${record.status}`);
+    if (!record.explicit.enforcement) missing.push(`Enforcement: ${record.enforcement}`);
+    if (!record.explicit.scope) missing.push(`Scope: ${record.scope.join(", ") || "all"}`);
+    if (!record.explicit.rule) missing.push(`Rule: ${record.rule}`);
+    if (!missing.length) continue;
+    const lineEnd = next.indexOf("\n", heading.index);
+    const insertAt = lineEnd < 0 ? next.length : lineEnd + 1;
+    next = `${next.slice(0, insertAt)}\n${missing.join("\n")}\n${next.slice(insertAt)}`;
+  }
+  return next.endsWith("\n") ? next : `${next}\n`;
+}
+
 module.exports = {
   configWeakeningAttempts,
   evaluatePolicy,
   inferEnforcement,
+  normalizeGuardrailDocument,
+  obligationGate,
   normalized,
   parseGuardrails,
   readOnlyPaths,

package/lib/runtime/request-engine.js

@@ -4,6 +4,7 @@ const { sha256 } = require("../v2/artifacts");
 const { buildContextPackage } = require("./context");
 const { containsSecret } = require("../security/secrets");
 const { evaluatePolicy, normalized } = require("./policy-engine");
+const { workspaceState } = require("./workspace-state");
 
 function assessRisk(request) {
   const text = normalized(request);
@@ -71,6 +72,7 @@ function encodeApproval(plan) {
     classification: plan.classification,
     risk: plan.risk,
     policy: plan.policy,
+    workspaceFingerprint: plan.workspaceFingerprint,
     issuedAt: plan.issuedAt
   };
   const encoded = Buffer.from(stableJson(payload)).toString("base64url");
@@ -98,6 +100,7 @@ function planRequest(projectRoot, request) {
   if (!normalized) throw new Error("A non-empty request is required for intake.");
   if (normalized.length > 10000) throw new Error("Request exceeds the 10,000 character intake limit.");
   const context = buildContextPackage(projectRoot, normalized);
+  const workspaceFingerprint = workspaceState(projectRoot).fingerprint;
   const policy = applyPolicy(context);
   const risk = assessRisk(normalized);
   const classification = classifyRequest(normalized);
@@ -106,6 +109,7 @@ function planRequest(projectRoot, request) {
     pipeline: ["received", "contextualizing", "policy", "risk", "classification", "planning", policy.status === "passed" ? "awaiting_approval" : "blocked"],
     request: normalized,
     context,
+    workspaceFingerprint,
     policy,
     risk,
     classification,

package/lib/runtime/review-service.js

@@ -0,0 +1,92 @@
+"use strict";
+
+const path = require("node:path");
+const { ArtifactRepository, METHOD_VERSION, withArtifactLock } = require("../v2/artifacts");
+const { auditProject } = require("../v2/conformance");
+const { assertCanonicalWrite } = require("./mutation-gateway");
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function oneLine(value, label) {
+  const text = String(value || "").replace(/\s+/g, " ").trim();
+  if (!text) throw new Error(`${label} is required.`);
+  if (text.length > 500) throw new Error(`${label} exceeds 500 characters.`);
+  return text;
+}
+
+function nextReviewId(repository) {
+  const highest = repository.list("review").reduce((max, artifact) => {
+    const match = artifact.record.id.match(/-(\d+)$/);
+    return match ? Math.max(max, Number(match[1])) : max;
+  }, 0);
+  return `REV-${String(highest + 1).padStart(3, "0")}`;
+}
+
+function recordArtifactReviewUnlocked(projectRoot, options) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  const repository = new ArtifactRepository(scrumDir);
+  const taskId = oneLine(options.task, "task");
+  const task = repository.read("task", taskId);
+  if (!task || task.errors.length) throw new Error(`Review Task is missing or invalid: ${taskId}`);
+  const runId = options.run ? oneLine(options.run, "run") : null;
+  if (runId) {
+    const run = repository.read("run", runId);
+    if (!run || run.errors.length) throw new Error(`Review Run is missing or invalid: ${runId}`);
+    if (run.record.task !== taskId) throw new Error(`${runId} belongs to ${run.record.task}, not ${taskId}.`);
+  }
+  const title = oneLine(options.title || `Artifact conformance review for ${runId || taskId}`, "title");
+  const suppliedEvidence = (Array.isArray(options.evidence) ? options.evidence : []).map((item) => oneLine(item, "evidence"));
+  const audit = auditProject(projectRoot);
+  const created = today();
+  const record = {
+    id: nextReviewId(repository),
+    kind: "review",
+    status: audit.passed ? "passed" : "failed",
+    created,
+    updated: created,
+    method: METHOD_VERSION,
+    task: taskId
+  };
+  const findings = audit.findings.length
+    ? audit.findings.map((finding) => `- ${finding.severity}: ${finding.code} — ${finding.message}`)
+    : ["- No conformance findings."];
+  const evidence = [
+    `- Artifact audit: ${audit.invariants} invariants; ${audit.findings.length} finding(s); passed=${audit.passed}.`,
+    ...(runId ? [`- Run under review: ${runId}.`] : []),
+    ...suppliedEvidence.map((item) => `- ${item}`)
+  ];
+  const verdict = audit.passed
+    ? "Passed. The machine-readable artifact audit has no blocking finding."
+    : "Failed. Blocking conformance findings must be resolved in a separately authorized mutation.";
+  const body = [
+    `# ${title}`,
+    "",
+    "## Scope",
+    "",
+    `Review canonical project conformance for ${runId || taskId}.`,
+    "",
+    "## Evidence",
+    "",
+    ...evidence,
+    "",
+    "## Findings",
+    "",
+    ...findings,
+    "",
+    "## Verdict",
+    "",
+    verdict
+  ].join("\n");
+  assertCanonicalWrite(projectRoot, "record-artifact-review", [title, ...suppliedEvidence, body]);
+  repository.write(record, body);
+  return { review: repository.read("review", record.id), audit };
+}
+
+function recordArtifactReview(projectRoot, options = {}) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  return withArtifactLock(scrumDir, "review-artifact", () => recordArtifactReviewUnlocked(projectRoot, options));
+}
+
+module.exports = { recordArtifactReview };

package/lib/runtime/run-ledger.js

@@ -1,7 +1,10 @@
 "use strict";
 
+const crypto = require("node:crypto");
+
 const {
   ARTIFACT_TRANSITIONS,
+  GUARDRAIL_RESULTS,
   RUN_EVENT_TYPES,
   RUN_EVIDENCE_KINDS,
   RUN_LEDGER_VERSION
@@ -57,7 +60,8 @@ function makeRunEvent({
   from,
   to,
   reason,
-  evidence = []
+  evidence = [],
+  ...details
 }) {
   return {
     schema: RUN_LEDGER_VERSION,
@@ -70,7 +74,8 @@ function makeRunEvent({
     from: from === undefined ? null : from,
     to,
     reason,
-    evidence: normalizeEvidence(evidence)
+    evidence: normalizeEvidence(evidence),
+    ...details
   };
 }
 
@@ -92,7 +97,10 @@ function createRunBody(record, {
   occurredAt = instant(),
   actor = "owner",
   reason = "Explicit approval accepted.",
-  evidence = null
+  evidence = null,
+  obligations = [],
+  policyFingerprint = null,
+  workspaceBaseline = null
 } = {}) {
   const eventEvidence = evidence || [{
     kind: "approval",
@@ -107,9 +115,133 @@ function createRunBody(record, {
     from: "created",
     to: "executing",
     reason,
-    evidence: eventEvidence
+    evidence: eventEvidence,
+    ...(policyFingerprint ? { policy_fingerprint: policyFingerprint } : {}),
+    ...(workspaceBaseline ? { workspace_baseline: workspaceBaseline } : {})
   });
-  return { body: `# ${title}\n\n${eventsSection([event])}`, event };
+  const declarations = obligations.map((obligation, index) => makeRunEvent({
+    runId: record.id,
+    sequence: index + 2,
+    type: "guardrail",
+    occurredAt,
+    actor: "policy-engine",
+    from: "executing",
+    to: "executing",
+    reason: `Guardrail obligation declared for ${obligation.gate}.`,
+    evidence: [{ kind: "guardrail", ref: obligation.guardrail, summary: `${obligation.code} must pass at ${obligation.gate}.` }],
+    guardrail: obligation.guardrail,
+    code: obligation.code,
+    enforcement: obligation.enforcement,
+    gate: obligation.gate,
+    result: "pending",
+    scope: obligation.scope || []
+  }));
+  const events = [event, ...declarations];
+  return { body: `# ${title}\n\n${eventsSection(events)}`, event, events };
+}
+
+function validateWorkspaceState(value, label) {
+  const errors = [];
+  if (!value || typeof value !== "object" || Array.isArray(value)) return [`${label} must be an object`];
+  if (value.schema !== 1) errors.push(`${label}.schema must be 1`);
+  if (!['git', 'files'].includes(value.mode)) errors.push(`${label}.mode must be git or files`);
+  if (!/^[a-f0-9]{64}$/.test(value.fingerprint || "")) errors.push(`${label}.fingerprint must be sha256`);
+  if (!Array.isArray(value.files)) errors.push(`${label}.files must be an array`);
+  const paths = new Set();
+  for (const item of Array.isArray(value.files) ? value.files : []) {
+    if (!item || typeof item !== "object" || typeof item.path !== "string" || !item.path || item.path.startsWith("/") || item.path.split("/").includes("..")) {
+      errors.push(`${label}.files contains an unsafe path`);
+      continue;
+    }
+    if (paths.has(item.path)) errors.push(`${label}.files contains duplicate path: ${item.path}`);
+    paths.add(item.path);
+    if (item.sha256 !== null && !/^[a-f0-9]{64}$/.test(item.sha256 || "")) errors.push(`${label}.${item.path}.sha256 is invalid`);
+    if (!["file", "missing", "symlink", "other", "clean"].includes(item.kind)) errors.push(`${label}.${item.path}.kind is invalid`);
+    if (item.mode !== null && (!Number.isInteger(item.mode) || item.mode < 0 || item.mode > 0o777)) errors.push(`${label}.${item.path}.mode is invalid`);
+    if (!["text", "binary", "too-large", "not-applicable"].includes(item.scan)) errors.push(`${label}.${item.path}.scan is invalid`);
+    if (item.kind === "file" && !["text", "binary", "too-large"].includes(item.scan)) errors.push(`${label}.${item.path}.scan is invalid for a file`);
+    if (item.kind !== "file" && item.scan !== "not-applicable") errors.push(`${label}.${item.path}.scan must be not-applicable`);
+  }
+  const canonical = value && {
+    schema: value.schema,
+    mode: value.mode,
+    head: value.head || null,
+    files: Array.isArray(value.files) ? value.files.map((item) => ({ path: item.path, sha256: item.sha256, kind: item.kind, mode: item.mode, scan: item.scan })) : []
+  };
+  const fingerprint = crypto.createHash("sha256").update(stableJson(canonical)).digest("hex");
+  if (value && value.fingerprint !== fingerprint) errors.push(`${label}.fingerprint does not match its workspace state`);
+  return errors;
+}
+
+function validateGuardrailEvent(event, declared) {
+  const errors = [];
+  if (!/^GR-\d{3,}$/.test(event.guardrail || "")) errors.push(`${event.id}.guardrail is invalid`);
+  if (!GUARDRAIL_RESULTS.includes(event.result)) errors.push(`${event.id}.result is invalid: ${event.result || "missing"}`);
+  if (typeof event.code !== "string" || !event.code.trim()) errors.push(`${event.id}.code is required`);
+  if (typeof event.enforcement !== "string" || !event.enforcement.trim()) errors.push(`${event.id}.enforcement is required`);
+  if (typeof event.gate !== "string" || !event.gate.trim()) errors.push(`${event.id}.gate is required`);
+  if (!Array.isArray(event.scope)) errors.push(`${event.id}.scope must be an array`);
+  if (event.result === "pending") {
+    if (declared.has(event.guardrail)) errors.push(`${event.id} redeclares ${event.guardrail}`);
+    declared.set(event.guardrail, { code: event.code, enforcement: event.enforcement, gate: event.gate, scope: event.scope || [] });
+  } else if (!declared.has(event.guardrail)) {
+    errors.push(`${event.id} resolves undeclared ${event.guardrail}`);
+  } else {
+    const original = declared.get(event.guardrail);
+    for (const field of ["code", "enforcement", "gate"]) {
+      if (event[field] !== original[field]) errors.push(`${event.id}.${field} disagrees with the ${event.guardrail} declaration`);
+    }
+    if (stableJson(event.scope || []) !== stableJson(original.scope)) errors.push(`${event.id}.scope disagrees with the ${event.guardrail} declaration`);
+  }
+  return errors;
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+  return JSON.stringify(value);
+}
+
+function safeEventPath(value) {
+  return typeof value === "string" && value && !value.startsWith("/") && !value.split("/").includes("..") && value !== ".scrumrun" && !value.startsWith(".scrumrun/");
+}
+
+function validateMutationEvent(event, expectedWorkspace, policyFingerprint) {
+  const errors = [];
+  if (!/^MUT-[A-Za-z0-9-]{8,}$/.test(event.mutation_id || "")) errors.push(`${event.id}.mutation_id is invalid`);
+  if (!Array.isArray(event.paths) || !event.paths.length) errors.push(`${event.id}.paths must be a non-empty array`);
+  if (!Array.isArray(event.changes) || !event.changes.length) errors.push(`${event.id}.changes must be a non-empty array`);
+  if (!/^[a-f0-9]{64}$/.test(event.workspace_before || "")) errors.push(`${event.id}.workspace_before must be sha256`);
+  if (expectedWorkspace && event.workspace_before !== expectedWorkspace) errors.push(`${event.id}.workspace_before breaks the mutation chain`);
+  if (event.policy_fingerprint !== policyFingerprint) errors.push(`${event.id}.policy_fingerprint disagrees with Run approval`);
+  const paths = new Set();
+  for (const value of Array.isArray(event.paths) ? event.paths : []) {
+    if (!safeEventPath(value)) errors.push(`${event.id}.paths contains an unsafe path`);
+    if (paths.has(value)) errors.push(`${event.id}.paths contains duplicate path: ${value}`);
+    paths.add(value);
+  }
+  const changed = new Set();
+  for (const change of Array.isArray(event.changes) ? event.changes : []) {
+    if (!change || !safeEventPath(change.path)) {
+      errors.push(`${event.id}.changes contains an unsafe path`);
+      continue;
+    }
+    if (changed.has(change.path)) errors.push(`${event.id}.changes contains duplicate path: ${change.path}`);
+    changed.add(change.path);
+    if (![...paths].some((allowed) => change.path === allowed || change.path.startsWith(`${allowed}/`))) errors.push(`${event.id}.${change.path} is outside declared paths`);
+    for (const field of ["before_sha256", "after_sha256"]) {
+      if (change[field] !== null && !/^[a-f0-9]{64}$/.test(change[field] || "")) errors.push(`${event.id}.${change.path}.${field} is invalid`);
+    }
+    for (const field of ["before_scan", "after_scan"]) {
+      if (!["text", "binary", "too-large", "not-applicable"].includes(change[field])) errors.push(`${event.id}.${change.path}.${field} is invalid`);
+    }
+    for (const field of ["before_mode", "after_mode"]) {
+      if (change[field] !== null && (!Number.isInteger(change[field]) || change[field] < 0 || change[field] > 0o777)) errors.push(`${event.id}.${change.path}.${field} is invalid`);
+    }
+  }
+  if (!event.workspace_after) errors.push(`${event.id}.workspace_after is required`);
+  else errors.push(...validateWorkspaceState(event.workspace_after, `${event.id}.workspace_after`));
+  return errors;
 }
 
 function parseRunLedger(body) {
@@ -158,6 +290,10 @@ function validateRunLedger(record, body) {
   const ids = new Set();
   let previous = null;
   let previousTime = null;
+  const declared = new Map();
+  const obligationResults = new Map();
+  let expectedWorkspace = events[0] && events[0].workspace_baseline && events[0].workspace_baseline.fingerprint;
+  const policyFingerprint = events[0] && events[0].policy_fingerprint;
   for (let index = 0; index < events.length; index++) {
     const event = events[index];
     const expectedSequence = index + 1;
@@ -188,6 +324,18 @@ function validateRunLedger(record, body) {
       if (!event.evidence.some((item) => item && ["migration", "legacy"].includes(item.kind))) {
         errors.push(`${event.id} snapshot requires migration or legacy evidence`);
       }
+    } else if (["guardrail", "mutation"].includes(event.type)) {
+      if (!previous) errors.push(`${event.id} cannot precede the initial Run event`);
+      const currentState = previous && previous.to;
+      if (event.from !== currentState || event.to !== currentState) errors.push(`${event.id} must not change Run state ${currentState || "unknown"}`);
+      if (event.type === "guardrail") {
+        errors.push(...validateGuardrailEvent(event, declared));
+        if (event.result !== "pending") obligationResults.set(event.guardrail, event.result);
+        else obligationResults.set(event.guardrail, "pending");
+      } else {
+        errors.push(...validateMutationEvent(event, expectedWorkspace, policyFingerprint));
+        if (event.workspace_after && event.workspace_after.fingerprint) expectedWorkspace = event.workspace_after.fingerprint;
+      }
     } else {
       const expectedFrom = index === 0 ? "created" : previous.to;
       if (event.type !== "transition") errors.push(`${event.id} snapshot is allowed only as the first event`);
@@ -202,6 +350,12 @@ function validateRunLedger(record, body) {
     if (!["snapshot"].includes(event.type) && !event.evidence.length) errors.push(`${event.id} transition requires evidence`);
     previous = event;
   }
+  if (record.workspace === 1 && events[0] && events[0].type !== "snapshot") {
+    errors.push(...validateWorkspaceState(events[0].workspace_baseline, `${events[0].id}.workspace_baseline`));
+  }
+  if (record.guardrails === 1 && events[0] && events[0].type !== "snapshot") {
+    if (!/^[a-f0-9]{64}$/.test(events[0].policy_fingerprint || "")) errors.push(`${events[0].id}.policy_fingerprint must be sha256`);
+  }
   if (previous && previous.to !== record.status) errors.push(`Run status ${record.status} disagrees with final event state ${previous.to}`);
   if (previous && record.updated !== String(previous.occurred_at || "").slice(0, 10)) {
     errors.push(`Run updated date ${record.updated} disagrees with final event timestamp`);
@@ -211,8 +365,73 @@ function validateRunLedger(record, body) {
       const event = events.find((item) => item.type === "transition" && item.to === required);
       if (!event || !event.evidence.length) errors.push(`completed Run requires evidenced ${required} transition`);
     }
+    for (const guardrail of declared.keys()) {
+      if (obligationResults.get(guardrail) !== "passed") errors.push(`completed Run has unresolved Guardrail obligation: ${guardrail}`);
+    }
   }
-  return { events, errors };
+  return { events, errors, obligations: [...declared.keys()].map((guardrail) => ({ guardrail, status: obligationResults.get(guardrail) || "pending" })) };
+}
+
+function appendAuxiliaryEvent(record, body, details, options = {}) {
+  const current = validateRunLedger(record, body);
+  if (current.errors.length) throw new Error(`Invalid Run ledger: ${current.errors.join("; ")}`);
+  const occurredAt = options.occurredAt ? instant(options.occurredAt) : instant();
+  const nextRecord = { ...record, updated: occurredAt.slice(0, 10) };
+  const evidence = normalizeEvidence(options.evidence || []);
+  if (!evidence.length) throw new Error(`${details.type} event requires structured evidence.`);
+  const event = makeRunEvent({
+    runId: record.id,
+    sequence: current.events.length + 1,
+    type: details.type,
+    occurredAt,
+    actor: options.actor || "agent",
+    from: record.status,
+    to: record.status,
+    reason: String(options.note || evidence.map((item) => item.summary || item.ref).filter(Boolean).join("; ")).trim(),
+    evidence,
+    ...details
+  });
+  const nextBody = `${String(body).trimEnd()}\n\n${renderRunEvent(event)}\n`;
+  const validated = validateRunLedger(nextRecord, nextBody);
+  if (validated.errors.length) throw new Error(`${details.type} event failed validation: ${validated.errors.join("; ")}`);
+  return { body: nextBody, record: nextRecord, event, events: validated.events, obligations: validated.obligations };
+}
+
+function appendGuardrailEvent(record, body, obligation, result, options = {}) {
+  if (!GUARDRAIL_RESULTS.includes(result) || result === "pending") throw new Error(`Guardrail result must be passed or blocked.`);
+  return appendAuxiliaryEvent(record, body, {
+    type: "guardrail",
+    guardrail: obligation.guardrail,
+    code: obligation.code,
+    enforcement: obligation.enforcement,
+    gate: obligation.gate,
+    result,
+    scope: obligation.scope || []
+  }, options);
+}
+
+function appendMutationEvent(record, body, mutation, options = {}) {
+  return appendAuxiliaryEvent(record, body, { type: "mutation", ...mutation }, options);
+}
+
+function guardrailState(record, body) {
+  const ledger = validateRunLedger(record, body);
+  if (ledger.errors.length) throw new Error(`Invalid Run ledger: ${ledger.errors.join("; ")}`);
+  const declarations = new Map();
+  const results = new Map();
+  for (const event of ledger.events.filter((item) => item.type === "guardrail")) {
+    if (event.result === "pending") declarations.set(event.guardrail, event);
+    else results.set(event.guardrail, event);
+  }
+  return [...declarations.values()].map((event) => ({
+    guardrail: event.guardrail,
+    code: event.code,
+    enforcement: event.enforcement,
+    gate: event.gate,
+    scope: event.scope || [],
+    status: results.has(event.guardrail) ? results.get(event.guardrail).result : "pending",
+    resultEvent: results.get(event.guardrail) || null
+  }));
 }
 
 function appendRunEvent(record, body, nextRecord, {
@@ -309,12 +528,15 @@ function migrateLegacyRun(record, body, { legacyHash, backupRef }) {
 }
 
 module.exports = {
+  appendGuardrailEvent,
+  appendMutationEvent,
   appendRunEvent,
   createRunBody,
   dateInstant,
   eventId,
   eventsSection,
   evidenceForTransition,
+  guardrailState,
   instant,
   makeRunEvent,
   migrateLegacyRun,