scrumrun 2.0.0 → 2.1.1

package/lib/v2/run-ledger-migration.js

@@ -0,0 +1,268 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const {
+  ArtifactRepository,
+  METHOD_VERSION,
+  assertNoSymlinkPath,
+  atomicWrite,
+  parseArtifact,
+  serializeArtifact,
+  sha256,
+  validateArtifact,
+  withArtifactLock
+} = require("./artifacts");
+const { RUN_LEDGER_VERSION } = require("./schema");
+const { migrateLegacyRun, validateRunLedger } = require("../runtime/run-ledger");
+const { normalizeGuardrailDocument, validateGuardrailDocument } = require("../runtime/policy-engine");
+
+const MIGRATION_NAME = "run-ledger-v1";
+const MIGRATION_DIR = path.join(".migration", MIGRATION_NAME);
+const MANIFEST_PATH = path.join(MIGRATION_DIR, "manifest.json");
+
+function posix(value) {
+  return value.split(path.sep).join("/");
+}
+
+function backupPath(relative) {
+  return posix(path.join(MIGRATION_DIR, "backup", relative));
+}
+
+function readMarker(scrumDir) {
+  const file = assertNoSymlinkPath(scrumDir, path.join(scrumDir, "method.json"));
+  if (!fs.existsSync(file) || !fs.lstatSync(file).isFile()) throw new Error("Canonical method.json is missing or unsafe.");
+  try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (value.method !== METHOD_VERSION) throw new Error(`method must be ${METHOD_VERSION}`);
+    return { file, value, content: fs.readFileSync(file, "utf8") };
+  } catch (error) {
+    throw new Error(`Canonical method.json is malformed: ${error.message}`);
+  }
+}
+
+function planRunLedgerMigration(projectRoot) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  if (!fs.existsSync(scrumDir) || !fs.lstatSync(scrumDir).isDirectory()) throw new Error("Not a ScrumRun project: .scrumrun/ is missing.");
+  const marker = readMarker(scrumDir);
+  const repository = new ArtifactRepository(scrumDir);
+  const changes = [];
+  const warnings = [];
+  const errors = [];
+
+  const guardrailsFile = assertNoSymlinkPath(scrumDir, path.join(scrumDir, "guardrails.md"));
+  if (fs.existsSync(guardrailsFile) && fs.lstatSync(guardrailsFile).isFile()) {
+    const before = fs.readFileSync(guardrailsFile, "utf8");
+    const after = normalizeGuardrailDocument(before);
+    const validation = validateGuardrailDocument(after);
+    if (validation.errors.length) errors.push(`guardrails.md: ${validation.errors.join("; ")}`);
+    else if (before !== after) {
+      changes.push({
+        relative: "guardrails.md",
+        before,
+        after,
+        beforeSha256: sha256(before),
+        afterSha256: sha256(after),
+        mode: "guardrail-schema"
+      });
+      warnings.push("guardrails.md: inferred legacy policy fields were made explicit without deleting source prose.");
+    }
+  } else {
+    errors.push("guardrails.md is missing or unsafe.");
+  }
+
+  for (const artifact of repository.list("run")) {
+    if (!artifact.record || artifact.errors.length) {
+      errors.push(`${path.relative(scrumDir, artifact.file)}: ${artifact.errors.join("; ")}`);
+      continue;
+    }
+    if (artifact.record.ledger === RUN_LEDGER_VERSION) {
+      const ledger = validateRunLedger(artifact.record, artifact.body);
+      for (const error of ledger.errors) errors.push(`${artifact.record.id}: ${error}`);
+      continue;
+    }
+    const relative = posix(path.relative(scrumDir, artifact.file));
+    const before = fs.readFileSync(artifact.file, "utf8");
+    try {
+      const migrated = migrateLegacyRun(artifact.record, artifact.body, {
+        legacyHash: sha256(before),
+        backupRef: `.scrumrun/${backupPath(relative)}`
+      });
+      const after = serializeArtifact(migrated.record, migrated.body);
+      const parsed = parseArtifact(after);
+      const validation = [...parsed.errors, ...validateArtifact(parsed.record, "run"), ...validateRunLedger(parsed.record, parsed.body).errors];
+      if (validation.length) throw new Error(validation.join("; "));
+      changes.push({ relative, before, after, beforeSha256: sha256(before), afterSha256: sha256(after), mode: migrated.mode });
+      if (migrated.mode === "snapshot") warnings.push(`${artifact.record.id}: missing transition history is preserved as an evidenced snapshot, not reconstructed.`);
+    } catch (error) {
+      errors.push(`${artifact.record.id}: ${error.message}`);
+    }
+  }
+
+  const markerValue = {
+    ...marker.value,
+    schemas: {
+      ...(marker.value.schemas || {}),
+      run_ledger: RUN_LEDGER_VERSION,
+      guardrails: 1,
+      run_obligations: 1,
+      mutation_gateway: 1
+    }
+  };
+  const markerAfter = `${JSON.stringify(markerValue, null, 2)}\n`;
+  if (marker.content !== markerAfter) {
+    changes.push({
+      relative: "method.json",
+      before: marker.content,
+      after: markerAfter,
+      beforeSha256: sha256(marker.content),
+      afterSha256: sha256(markerAfter),
+      mode: "schema-marker"
+    });
+  }
+  const fingerprint = sha256(changes.map((change) => `${change.relative}\0${change.beforeSha256}`).sort().join("\n"));
+  return {
+    projectRoot,
+    scrumDir,
+    status: errors.length ? "blocked" : changes.length ? "ready" : "current",
+    migration: MIGRATION_NAME,
+    ledger: RUN_LEDGER_VERSION,
+    fingerprint,
+    changes,
+    warnings,
+    errors
+  };
+}
+
+function reportRunLedgerMigration(plan, status = plan.status) {
+  const mappings = plan.changes.length
+    ? plan.changes.map((change) => `- \`${change.relative}\` · ${change.mode} · \`${change.beforeSha256.slice(0, 12)}\` → \`${change.afterSha256.slice(0, 12)}\``).join("\n")
+    : "- No changes required.";
+  const warnings = plan.warnings.length ? plan.warnings.map((warning) => `- ${warning}`).join("\n") : "- None.";
+  const errors = plan.errors.length ? plan.errors.map((error) => `- ${error}`).join("\n") : "- None.";
+  return `# ScrumRun Kernel Schema Migration\n\nStatus: ${status}\nRun ledger schema: ${RUN_LEDGER_VERSION}\nGuardrail schema: 1\nMutation Gateway schema: 1\nSource fingerprint: \`${plan.fingerprint}\`\nChanged files: ${plan.changes.length}\n\n## Mappings\n\n${mappings}\n\n## Warnings\n\n${warnings}\n\n## Blockers\n\n${errors}\n`;
+}
+
+function manifestFile(scrumDir) {
+  return assertNoSymlinkPath(scrumDir, path.join(scrumDir, MANIFEST_PATH));
+}
+
+function loadManifest(scrumDir) {
+  const file = manifestFile(scrumDir);
+  if (!fs.existsSync(file)) return null;
+  if (!fs.lstatSync(file).isFile() || fs.lstatSync(file).isSymbolicLink()) throw new Error("Run ledger migration manifest is unsafe.");
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function backupChanges(plan) {
+  for (const change of plan.changes) {
+    const target = assertNoSymlinkPath(plan.scrumDir, path.join(plan.scrumDir, backupPath(change.relative)));
+    if (fs.existsSync(target)) {
+      if (sha256(fs.readFileSync(target)) !== change.beforeSha256) throw new Error(`Migration backup conflicts for ${change.relative}.`);
+      continue;
+    }
+    atomicWrite(target, change.before);
+  }
+}
+
+function verifyChanges(scrumDir, changes, field) {
+  const problems = [];
+  for (const change of changes) {
+    const file = assertNoSymlinkPath(scrumDir, path.join(scrumDir, change.relative));
+    const actual = fs.existsSync(file) && fs.lstatSync(file).isFile() ? sha256(fs.readFileSync(file)) : "missing";
+    if (actual !== change[field]) problems.push(`${change.relative}: expected ${change[field]}, found ${actual}`);
+  }
+  return problems;
+}
+
+function restoreChanges(scrumDir, changes) {
+  for (const change of [...changes].reverse()) {
+    const backup = assertNoSymlinkPath(scrumDir, path.join(scrumDir, backupPath(change.relative)));
+    if (!fs.existsSync(backup) || sha256(fs.readFileSync(backup)) !== change.beforeSha256) {
+      throw new Error(`Run ledger backup is missing or corrupt for ${change.relative}.`);
+    }
+    const target = assertNoSymlinkPath(scrumDir, path.join(scrumDir, change.relative));
+    atomicWrite(target, fs.readFileSync(backup));
+  }
+}
+
+function recoverPrepared(scrumDir, manifest) {
+  if (!manifest || manifest.status !== "prepared") return false;
+  const allowed = [];
+  for (const change of manifest.changes) {
+    const file = path.join(scrumDir, change.relative);
+    const actual = fs.existsSync(file) ? sha256(fs.readFileSync(file)) : "missing";
+    if (![change.beforeSha256, change.afterSha256].includes(actual)) allowed.push(`${change.relative}: unexpected ${actual}`);
+  }
+  if (allowed.length) throw new Error(`Interrupted Run ledger migration cannot recover safely:\n${allowed.join("\n")}`);
+  restoreChanges(scrumDir, manifest.changes);
+  atomicWrite(manifestFile(scrumDir), `${JSON.stringify({ ...manifest, status: "recovered", recovered_at: new Date().toISOString() }, null, 2)}\n`);
+  return true;
+}
+
+function applyRunLedgerMigration(projectRoot, { failurePoint = null } = {}) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  const preview = planRunLedgerMigration(projectRoot);
+  if (preview.errors.length) throw new Error(`Run ledger migration is blocked:\n${preview.errors.join("\n")}`);
+  if (!preview.changes.length) return { status: "current", plan: preview, output: reportRunLedgerMigration(preview, "current") };
+  return withArtifactLock(scrumDir, "run-ledger-migration", () => {
+    const existing = loadManifest(scrumDir);
+    if (existing && existing.status === "prepared") recoverPrepared(scrumDir, existing);
+    const plan = planRunLedgerMigration(projectRoot);
+    if (plan.errors.length) throw new Error(`Run ledger migration is blocked:\n${plan.errors.join("\n")}`);
+    if (!plan.changes.length) return { status: "current", plan, output: reportRunLedgerMigration(plan, "current") };
+    const changed = verifyChanges(scrumDir, plan.changes, "beforeSha256");
+    if (changed.length) throw new Error(`Run ledger source changed after preflight:\n${changed.join("\n")}`);
+    backupChanges(plan);
+    const manifest = {
+      migration: MIGRATION_NAME,
+      schema: RUN_LEDGER_VERSION,
+      status: "prepared",
+      prepared_at: new Date().toISOString(),
+      source_fingerprint: plan.fingerprint,
+      changes: plan.changes.map(({ relative, beforeSha256, afterSha256, mode }) => ({ relative, beforeSha256, afterSha256, mode }))
+    };
+    atomicWrite(manifestFile(scrumDir), `${JSON.stringify(manifest, null, 2)}\n`);
+    try {
+      for (let index = 0; index < plan.changes.length; index++) {
+        const change = plan.changes[index];
+        const target = assertNoSymlinkPath(scrumDir, path.join(scrumDir, change.relative));
+        atomicWrite(target, change.after);
+        if (failurePoint === `after-${index + 1}`) throw new Error(`Injected Run ledger migration failure after write ${index + 1}.`);
+      }
+      const afterProblems = verifyChanges(scrumDir, plan.changes, "afterSha256");
+      if (afterProblems.length) throw new Error(`Run ledger migration verification failed:\n${afterProblems.join("\n")}`);
+      const applied = { ...manifest, status: "applied", applied_at: new Date().toISOString() };
+      atomicWrite(manifestFile(scrumDir), `${JSON.stringify(applied, null, 2)}\n`);
+      return { status: "applied", plan, manifest: applied, output: reportRunLedgerMigration(plan, "applied") };
+    } catch (error) {
+      restoreChanges(scrumDir, manifest.changes);
+      atomicWrite(manifestFile(scrumDir), `${JSON.stringify({ ...manifest, status: "recovered", recovered_at: new Date().toISOString() }, null, 2)}\n`);
+      throw error;
+    }
+  });
+}
+
+function rollbackRunLedgerMigration(projectRoot) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  return withArtifactLock(scrumDir, "run-ledger-migration", () => {
+    const manifest = loadManifest(scrumDir);
+    if (!manifest || !["applied", "prepared"].includes(manifest.status)) throw new Error("No applied Run ledger migration is available for rollback.");
+    if (manifest.status === "applied") {
+      const changed = verifyChanges(scrumDir, manifest.changes, "afterSha256");
+      if (changed.length) throw new Error(`Rollback would erase post-migration changes:\n${changed.join("\n")}`);
+    }
+    restoreChanges(scrumDir, manifest.changes);
+    const rolledBack = { ...manifest, status: "rolled-back", rolled_back_at: new Date().toISOString() };
+    atomicWrite(manifestFile(scrumDir), `${JSON.stringify(rolledBack, null, 2)}\n`);
+    return { status: "rolled-back", manifest: rolledBack };
+  });
+}
+
+module.exports = {
+  MIGRATION_NAME,
+  applyRunLedgerMigration,
+  planRunLedgerMigration,
+  reportRunLedgerMigration,
+  rollbackRunLedgerMigration
+};

package/lib/v2/schema.js

@@ -7,6 +7,26 @@ function deepFreeze(value) {
 }
 
 const METHOD_VERSION = "2.0.0";
+const RUN_LEDGER_VERSION = 1;
+
+const RUN_EVENT_TYPES = deepFreeze(["transition", "snapshot", "guardrail", "mutation"]);
+const RUN_EVIDENCE_KINDS = deepFreeze([
+  "approval",
+  "command",
+  "test",
+  "file",
+  "review",
+  "decision",
+  "insight",
+  "risk",
+  "note",
+  "migration",
+  "legacy",
+  "guardrail",
+  "mutation"
+]);
+
+const GUARDRAIL_RESULTS = deepFreeze(["pending", "passed", "blocked"]);
 
 const ARTIFACT_TYPES = deepFreeze({
   feature: {
@@ -92,7 +112,10 @@ const STRUCTURAL_RELATIONS = deepFreeze({
 });
 
 const SCALAR_FIELDS = deepFreeze({
-  attempt: { kinds: ["run"], required: true, type: "positive integer", meaning: "monotonic execution-attempt number within one Task" }
+  attempt: { kinds: ["run"], required: true, type: "positive integer", meaning: "monotonic execution-attempt number within one Task" },
+  ledger: { kinds: ["run"], required: false, type: `integer ${RUN_LEDGER_VERSION}`, meaning: "canonical Run event-ledger schema; required for newly authored Runs" },
+  guardrails: { kinds: ["run"], required: false, type: "integer 1", meaning: "append-only Guardrail obligation schema" },
+  workspace: { kinds: ["run"], required: false, type: "integer 1", meaning: "workspace mutation-gateway schema" }
 });
 
 const TRUTH_OWNERSHIP = deepFreeze({
@@ -120,7 +143,11 @@ module.exports = {
   ARTIFACT_TRANSITIONS,
   ARTIFACT_TYPES,
   AUTHORITY,
+  GUARDRAIL_RESULTS,
   METHOD_VERSION,
+  RUN_EVENT_TYPES,
+  RUN_EVIDENCE_KINDS,
+  RUN_LEDGER_VERSION,
   SCALAR_FIELDS,
   STRUCTURAL_RELATIONS,
   TRUTH_OWNERSHIP,

package/lib/v2/transaction.js

@@ -0,0 +1,254 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+const {
+  assertNoSymlinkPath,
+  atomicWrite,
+  sha256,
+  withArtifactLock
+} = require("./artifacts");
+
+const TRANSACTION_SCHEMA = 1;
+const TRANSACTION_ROOT = path.join(".backup", "transactions");
+const PENDING_DIR = path.join(TRANSACTION_ROOT, "pending");
+const RECEIPT_DIR = path.join(TRANSACTION_ROOT, "receipts");
+const FORBIDDEN = [".backup/", ".cache/", ".migration/", "vault.local.md"];
+
+function posix(value) {
+  return value.split(path.sep).join("/");
+}
+
+function transactionId() {
+  return `TXN-${Date.now()}-${crypto.randomBytes(6).toString("hex")}`;
+}
+
+function safeTransactionPath(scrumDir, relative) {
+  return assertNoSymlinkPath(scrumDir, path.join(scrumDir, relative));
+}
+
+function relativeTarget(scrumDir, file) {
+  const target = assertNoSymlinkPath(scrumDir, path.resolve(file));
+  const relative = posix(path.relative(path.resolve(scrumDir), target));
+  if (!relative || relative.startsWith("../") || path.isAbsolute(relative)) throw new Error(`Transaction target escapes .scrumrun: ${file}`);
+  if (FORBIDDEN.some((entry) => relative === entry.replace(/\/$/, "") || relative.startsWith(entry))) {
+    throw new Error(`Transaction target is outside the canonical mutation boundary: ${relative}`);
+  }
+  return { relative, file: target };
+}
+
+function snapshot(content) {
+  if (content === null) return { exists: false, sha256: "missing", content_base64: null };
+  const value = Buffer.isBuffer(content) ? content : Buffer.from(String(content));
+  return { exists: true, sha256: sha256(value), content_base64: value.toString("base64") };
+}
+
+function fileSnapshot(scrumDir, relative) {
+  const file = safeTransactionPath(scrumDir, relative);
+  if (!fs.existsSync(file)) return snapshot(null);
+  if (!fs.lstatSync(file).isFile()) throw new Error(`Transaction target is not a regular file: ${relative}`);
+  return snapshot(fs.readFileSync(file));
+}
+
+function sameSnapshot(left, right) {
+  return Boolean(left && right && left.exists === right.exists && left.sha256 === right.sha256);
+}
+
+function applySnapshot(scrumDir, relative, value) {
+  const file = safeTransactionPath(scrumDir, relative);
+  if (!value.exists) {
+    if (fs.existsSync(file)) fs.rmSync(file, { force: true });
+    return;
+  }
+  atomicWrite(file, Buffer.from(value.content_base64, "base64"));
+}
+
+function pendingDirectory(scrumDir) {
+  return safeTransactionPath(scrumDir, PENDING_DIR);
+}
+
+function receipt(transaction, status, details = {}) {
+  return {
+    schema: TRANSACTION_SCHEMA,
+    id: transaction.id,
+    name: transaction.name,
+    status,
+    created_at: transaction.created_at,
+    finished_at: new Date().toISOString(),
+    changes: transaction.changes.map((change) => ({
+      relative: change.relative,
+      before_sha256: change.before.sha256,
+      after_sha256: change.after.sha256
+    })),
+    ...details
+  };
+}
+
+function finishJournal(scrumDir, journalFile, transaction, status, details = {}) {
+  const receiptFile = safeTransactionPath(scrumDir, path.join(RECEIPT_DIR, `${transaction.id}.json`));
+  atomicWrite(receiptFile, `${JSON.stringify(receipt(transaction, status, details), null, 2)}\n`);
+  fs.rmSync(journalFile, { force: true });
+}
+
+function pendingTransactions(scrumDir) {
+  const directory = pendingDirectory(scrumDir);
+  if (!fs.existsSync(directory)) return [];
+  if (!fs.lstatSync(directory).isDirectory()) throw new Error("Transaction pending path is not a directory.");
+  const entries = fs.readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+  for (const entry of entries) {
+    if (entry.isSymbolicLink() || !entry.isFile() || !/^TXN-[a-zA-Z0-9-]+\.json$/.test(entry.name)) {
+      throw new Error(`Unexpected transaction journal entry: ${entry.name}`);
+    }
+  }
+  return entries.map((entry) => {
+      const file = safeTransactionPath(scrumDir, path.join(PENDING_DIR, entry.name));
+      try {
+        const transaction = JSON.parse(fs.readFileSync(file, "utf8"));
+        return { file, transaction };
+      } catch (error) {
+        throw new Error(`Transaction journal is malformed: ${entry.name}: ${error.message}`);
+      }
+    });
+}
+
+function validateJournal(transaction) {
+  const errors = [];
+  if (!transaction || transaction.schema !== TRANSACTION_SCHEMA) errors.push(`schema must be ${TRANSACTION_SCHEMA}`);
+  if (!/^TXN-[a-zA-Z0-9-]+$/.test(transaction && transaction.id || "")) errors.push("id is invalid");
+  if (!transaction || !["prepared", "committed"].includes(transaction.status)) errors.push("status must be prepared or committed");
+  if (!transaction || !Array.isArray(transaction.changes) || !transaction.changes.length) errors.push("changes must be a non-empty array");
+  for (const change of transaction && Array.isArray(transaction.changes) ? transaction.changes : []) {
+    if (typeof change.relative !== "string" || !change.relative) errors.push("change.relative is required");
+    for (const key of ["before", "after"]) {
+      const value = change[key];
+      if (!value || typeof value.exists !== "boolean" || typeof value.sha256 !== "string") errors.push(`${change.relative || "change"}.${key} is malformed`);
+      if (value && value.exists && typeof value.content_base64 !== "string") errors.push(`${change.relative || "change"}.${key} content is missing`);
+      if (value && value.exists && typeof value.content_base64 === "string") {
+        const decoded = Buffer.from(value.content_base64, "base64");
+        if (decoded.toString("base64") !== value.content_base64 || sha256(decoded) !== value.sha256) {
+          errors.push(`${change.relative || "change"}.${key} content hash is invalid`);
+        }
+      }
+      if (value && !value.exists && (value.sha256 !== "missing" || value.content_base64 !== null)) {
+        errors.push(`${change.relative || "change"}.${key} missing snapshot is invalid`);
+      }
+    }
+  }
+  return errors;
+}
+
+function recoverPendingTransactionsUnlocked(scrumDir) {
+  const recovered = [];
+  for (const { file, transaction } of pendingTransactions(scrumDir)) {
+    const errors = validateJournal(transaction);
+    if (errors.length) throw new Error(`Unsafe transaction journal ${path.basename(file)}: ${errors.join("; ")}`);
+    for (const change of transaction.changes) {
+      const target = relativeTarget(scrumDir, path.join(scrumDir, change.relative));
+      if (target.relative !== change.relative) throw new Error(`Unsafe transaction target in ${transaction.id}: ${change.relative}`);
+    }
+    const current = transaction.changes.map((change) => ({ change, value: fileSnapshot(scrumDir, change.relative) }));
+    const unexpected = current.filter(({ change, value }) => !sameSnapshot(value, change.before) && !sameSnapshot(value, change.after));
+    if (unexpected.length) {
+      throw new Error(`Pending transaction ${transaction.id} cannot recover without overwriting owner changes: ${unexpected.map(({ change }) => change.relative).join(", ")}`);
+    }
+    if (transaction.status === "prepared") {
+      for (const change of [...transaction.changes].reverse()) applySnapshot(scrumDir, change.relative, change.before);
+      const unrestored = transaction.changes.filter((change) => !sameSnapshot(fileSnapshot(scrumDir, change.relative), change.before));
+      if (unrestored.length) throw new Error(`Transaction ${transaction.id} recovery verification failed: ${unrestored.map((change) => change.relative).join(", ")}`);
+      finishJournal(scrumDir, file, transaction, "recovered", { action: "rolled-back-prepared" });
+      recovered.push({ id: transaction.id, action: "rolled-back" });
+    } else {
+      const incomplete = current.filter(({ change, value }) => !sameSnapshot(value, change.after));
+      if (incomplete.length) throw new Error(`Committed transaction ${transaction.id} is incomplete: ${incomplete.map(({ change }) => change.relative).join(", ")}`);
+      finishJournal(scrumDir, file, transaction, "committed", { action: "verified-commit" });
+      recovered.push({ id: transaction.id, action: "verified" });
+    }
+  }
+  return recovered;
+}
+
+function recoverPendingTransactions(scrumDir) {
+  return withArtifactLock(scrumDir, "kernel", () => recoverPendingTransactionsUnlocked(scrumDir));
+}
+
+function normalizeChanges(scrumDir, changes) {
+  if (!Array.isArray(changes) || !changes.length) throw new Error("Kernel transaction requires at least one change.");
+  const seen = new Set();
+  return changes.map((change) => {
+    const target = relativeTarget(scrumDir, change.file);
+    if (seen.has(target.relative)) throw new Error(`Duplicate transaction target: ${target.relative}`);
+    seen.add(target.relative);
+    if (!Object.prototype.hasOwnProperty.call(change, "previous") || !Object.prototype.hasOwnProperty.call(change, "next")) {
+      throw new Error(`Transaction change requires previous and next content: ${target.relative}`);
+    }
+    return { relative: target.relative, before: snapshot(change.previous), after: snapshot(change.next) };
+  });
+}
+
+function writeKernelTransactionUnlocked(scrumDir, name, changes, { failurePoint = null, interruptPoint = null } = {}) {
+  if (!/^[a-z0-9-]+$/i.test(name || "")) throw new Error(`Invalid transaction name: ${name || "missing"}`);
+  const normalized = normalizeChanges(scrumDir, changes);
+  const conflicts = normalized.filter((change) => !sameSnapshot(fileSnapshot(scrumDir, change.relative), change.before));
+  if (conflicts.length) throw new Error(`Transaction source changed before prepare: ${conflicts.map((change) => change.relative).join(", ")}`);
+  const transaction = {
+    schema: TRANSACTION_SCHEMA,
+    id: transactionId(),
+    name,
+    status: "prepared",
+    created_at: new Date().toISOString(),
+    changes: normalized
+  };
+  const journalFile = safeTransactionPath(scrumDir, path.join(PENDING_DIR, `${transaction.id}.json`));
+  atomicWrite(journalFile, `${JSON.stringify(transaction, null, 2)}\n`);
+  if (interruptPoint === "after-prepare") throw Object.assign(new Error("Simulated interruption after transaction prepare."), { code: "SCRUMRUN_INTERRUPTED" });
+  try {
+    for (let index = 0; index < transaction.changes.length; index++) {
+      const change = transaction.changes[index];
+      applySnapshot(scrumDir, change.relative, change.after);
+      if (interruptPoint === `after-${index + 1}`) {
+        throw Object.assign(new Error(`Simulated interruption after transaction write ${index + 1}.`), { code: "SCRUMRUN_INTERRUPTED" });
+      }
+      if (failurePoint === `after-${index + 1}`) throw new Error(`Injected transaction failure after write ${index + 1}.`);
+    }
+    const invalid = transaction.changes.filter((change) => !sameSnapshot(fileSnapshot(scrumDir, change.relative), change.after));
+    if (invalid.length) throw new Error(`Transaction verification failed: ${invalid.map((change) => change.relative).join(", ")}`);
+    const committed = { ...transaction, status: "committed", committed_at: new Date().toISOString() };
+    atomicWrite(journalFile, `${JSON.stringify(committed, null, 2)}\n`);
+    if (interruptPoint === "after-commit") {
+      throw Object.assign(new Error("Simulated interruption after transaction commit."), { code: "SCRUMRUN_INTERRUPTED" });
+    }
+    finishJournal(scrumDir, journalFile, committed, "committed", { action: "applied" });
+    return { id: transaction.id, status: "committed", changes: transaction.changes.length };
+  } catch (error) {
+    if (error.code === "SCRUMRUN_INTERRUPTED") throw error;
+    for (const change of [...transaction.changes].reverse()) applySnapshot(scrumDir, change.relative, change.before);
+    finishJournal(scrumDir, journalFile, transaction, "recovered", { action: "rolled-back-error", error: error.message });
+    throw error;
+  }
+}
+
+function runKernelTransaction(scrumDir, name, changes, options = {}) {
+  return withArtifactLock(scrumDir, "kernel", () => {
+    const recovered = recoverPendingTransactionsUnlocked(scrumDir);
+    const result = writeKernelTransactionUnlocked(scrumDir, name, changes, options);
+    return { ...result, recovered };
+  });
+}
+
+function pendingTransactionStatus(scrumDir) {
+  try {
+    return { pending: pendingTransactions(scrumDir).map(({ transaction }) => ({ id: transaction.id, name: transaction.name, status: transaction.status })) };
+  } catch (error) {
+    return { pending: [], error: error.message };
+  }
+}
+
+module.exports = {
+  TRANSACTION_SCHEMA,
+  pendingTransactionStatus,
+  recoverPendingTransactions,
+  recoverPendingTransactionsUnlocked,
+  runKernelTransaction,
+  writeKernelTransactionUnlocked
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrumrun",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Evidence-driven Agile runtime and semantic project memory for AI coding agents.",
   "bin": {
     "scrumrun": "bin/scrumrun.js",

package/scripts/generate-contract-docs.js

@@ -8,6 +8,9 @@ const {
   ARTIFACT_TYPES,
   AUTHORITY,
   METHOD_VERSION,
+  RUN_EVENT_TYPES,
+  RUN_EVIDENCE_KINDS,
+  RUN_LEDGER_VERSION,
   SCALAR_FIELDS,
   STRUCTURAL_RELATIONS,
   TRUTH_OWNERSHIP
@@ -76,6 +79,14 @@ ${scalarRows.join("\n")}
 
 Native creation uses the declared initial statuses. Migration may restore a historical non-initial status only with provenance and validation.
 
+## Run event ledger
+
+Newly authored Runs use \`ledger: ${RUN_LEDGER_VERSION}\`. Their \`## Events\` section contains append-only JSON event blocks with stable ids in the form \`RUN-NNN-EVT-NNN\`.
+
+Every event requires \`schema\`, \`id\`, contiguous \`sequence\`, RFC3339 \`occurred_at\`, \`timestamp_precision\`, \`actor\`, \`from\`, \`to\`, \`reason\`, and structured \`evidence\`. Event types are ${RUN_EVENT_TYPES.map((value) => `\`${value}\``).join(", ")}. Evidence kinds are ${RUN_EVIDENCE_KINDS.map((value) => `\`${value}\``).join(", ")}.
+
+A native ledger begins with \`created → executing\`; an evidenced migration \`snapshot\` may establish one historical baseline without inventing missing transitions. Event order, transition legality, final status, updated date, and completion evidence are machine-validated. Run owns the event history; Task stores its intended scope and synchronized current status without copying Run events.
+
 ## Truth questions
 
 ${Object.entries(TRUTH_OWNERSHIP).map(([kind, owner]) => `- **${kind}:** ${owner.question}`).join("\n")}

package/templates/project/.scrumrun/guardrails.md

@@ -5,19 +5,27 @@ Canonical project policy. Universal method invariants live in `core.md`; this fi
 ## GR-001 - Protect secrets
 
 Status: active
+Enforcement: builtin:secret-boundary
+Scope: all
 Rule: Never commit or print real secrets. Keep local development values in `vault.local.md` and runtime values in environment/config.
 
 ## GR-002 - Preserve owner work
 
 Status: active
+Enforcement: builtin:owner-work
+Scope: all
 Rule: Never overwrite unrelated or pre-existing owner changes. Canonical mutations must be scoped, lossless, validated, and recoverable.
 
 ## GR-003 - Respect read-only paths
 
 Status: active
+Enforcement: builtin:read-only-path
+Scope: all
 Rule: Never modify a path marked read-only by the owner or project configuration.
 
 ## GR-004 - Approval gates execution
 
 Status: active
+Enforcement: builtin:approval-gate
+Scope: intake, execution
 Rule: Intake remains read-only. Create/update a Task and create a Run only after explicit valid approval.

package/templates/project/.scrumrun/map.md

@@ -1,8 +1,9 @@
-# ScrumRun Map - {{PROJECT_NAME}}
+# ScrumRun Project Map
 
 Generated: {{DATE}}
+Status: stale
 Authority: none; rebuild from canonical artifacts and source code.
 
-## Active Graph
+## Summary
 
-- Pending: no Features, Tasks, Sprints, Runs, Memory, or Reviews yet.
+- No source fingerprint exists until `/sc knowledge map --build` creates the disposable semantic index and this bounded view.

package/templates/project/.scrumrun/method.json

@@ -1,4 +1,10 @@
 {
   "method": "2.0.0",
-  "layout": "v2"
+  "layout": "v2",
+  "schemas": {
+    "run_ledger": 1,
+    "guardrails": 1,
+    "run_obligations": 1,
+    "mutation_gateway": 1
+  }
 }