scrumrun 3.1.2 → 4.1.0

package/lib/guardrails/evaluate.js

@@ -0,0 +1,175 @@
+"use strict";
+
+// Deliberately small YAML subset for Guardrail declarations. It accepts the
+// mapping + string-list shape documented in SPEC.md without pulling a parser
+// into every client installation. JSON is valid YAML, but this keeps authored
+// Markdown pleasant to read and rejects unsupported YAML instead of guessing.
+
+const ACTIONS = new Set(["block", "warn"]);
+const SEVERITIES = new Set(["low", "medium", "high", "critical"]);
+
+function unquote(value) {
+  const text = String(value || "").trim();
+  if ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'"))) {
+    try { return text.startsWith('"') ? JSON.parse(text) : text.slice(1, -1).replace(/''/g, "'"); } catch { return text; }
+  }
+  return text;
+}
+
+function yamlError(id, message) {
+  return `SR-E-153 ${id}: ${message}`;
+}
+
+function parseInlineList(value) {
+  const text = String(value || "").trim();
+  if (!text.startsWith("[") || !text.endsWith("]")) return null;
+  const inner = text.slice(1, -1).trim();
+  return inner ? inner.split(",").map((item) => unquote(item)).filter(Boolean) : [];
+}
+
+function parseEnforcementYaml(source, id = "GR-???") {
+  const lines = String(source || "").replace(/\r/g, "").split("\n");
+  const value = { match: { paths: [], diff: [], symbols: [] }, evidence: [] };
+  let section = null;
+  let sawMatch = false;
+  for (let index = 0; index < lines.length; index++) {
+    const raw = lines[index];
+    if (!raw.trim() || /^\s*#/.test(raw)) continue;
+    const top = raw.match(/^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/);
+    if (top) {
+      const [, key, rawValue] = top;
+      const inline = parseInlineList(rawValue);
+      if (key === "match") {
+        if (rawValue.trim()) throw new Error(yamlError(id, "match must contain paths, diff, and/or symbols."));
+        section = "match";
+        sawMatch = true;
+      } else if (key === "evidence") {
+        if (inline) value.evidence = inline;
+        else if (rawValue.trim()) value.evidence = [unquote(rawValue)];
+        else section = "evidence";
+      } else if (["on_violation", "severity"].includes(key)) {
+        if (!rawValue.trim()) throw new Error(yamlError(id, `${key} requires a scalar value.`));
+        value[key] = unquote(rawValue);
+        section = null;
+      } else {
+        throw new Error(yamlError(id, `unsupported enforcement field: ${key}`));
+      }
+      continue;
+    }
+    const nested = raw.match(/^  ([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/);
+    if (nested && (section === "match" || /^match\./.test(section || ""))) {
+      const [, key, rawValue] = nested;
+      if (!Object.hasOwn(value.match, key)) throw new Error(yamlError(id, `match.${key} is not supported.`));
+      const inline = parseInlineList(rawValue);
+      if (inline) value.match[key] = inline;
+      else if (rawValue.trim()) value.match[key] = [unquote(rawValue)];
+      else section = `match.${key}`;
+      continue;
+    }
+    const list = raw.match(/^\s{2,}-\s+(.+)$/);
+    if (list && (section === "evidence" || /^match\.(paths|diff|symbols)$/.test(section || ""))) {
+      const target = section === "evidence" ? value.evidence : value.match[section.slice("match.".length)];
+      target.push(unquote(list[1]));
+      continue;
+    }
+    throw new Error(yamlError(id, `malformed YAML line ${index + 1}.`));
+  }
+  if (!sawMatch) throw new Error(yamlError(id, "enforcement requires a match mapping."));
+  if (!value.on_violation || !ACTIONS.has(value.on_violation)) throw new Error(yamlError(id, "on_violation must be block or warn."));
+  if (!value.severity) value.severity = "high";
+  if (!SEVERITIES.has(value.severity)) throw new Error(yamlError(id, "severity must be low, medium, high, or critical."));
+  if (!value.match.paths.length && !value.match.diff.length && !value.match.symbols.length) throw new Error(yamlError(id, "match requires paths, diff, or symbols."));
+  return value;
+}
+
+function enforcementBlock(markdown, id) {
+  const source = String(markdown || "");
+  const named = source.match(/```ya?ml\s+enforcement\s*\n([\s\S]*?)```/i);
+  const nested = source.match(/```ya?ml\s*\n\s*enforcement:\s*\n([\s\S]*?)```/i);
+  const body = named ? named[1] : nested ? nested[1].split("\n").map((line) => line.replace(/^  /, "")).join("\n") : null;
+  if (body === null) return { value: null, errors: [] };
+  try { return { value: parseEnforcementYaml(body, id), errors: [] }; }
+  catch (error) { return { value: null, errors: [error.message] }; }
+}
+
+function regex(value) {
+  const source = String(value || "").trim();
+  const slash = source.match(/^\/(.*)\/([gimsuy]*)$/);
+  try { return slash ? new RegExp(slash[1], slash[2].replace("g", "")) : new RegExp(source); }
+  catch { return null; }
+}
+
+function globRegex(pattern) {
+  let out = "^";
+  const source = String(pattern || "").replace(/\\/g, "/");
+  for (let index = 0; index < source.length; index++) {
+    const character = source[index];
+    if (character === "*") {
+      if (source[index + 1] === "*") {
+        if (source[index + 2] === "/") { out += "(?:.*/)?"; index += 2; }
+        else { out += ".*"; index++; }
+      }
+      else out += "[^/]*";
+    } else if (character === "?") out += "[^/]";
+    else out += character.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+  }
+  return new RegExp(`${out}$`);
+}
+
+function matchPath(pattern, candidate) {
+  const text = String(candidate || "").replace(/\\/g, "/");
+  const rule = String(pattern || "").trim();
+  if (!rule) return false;
+  if (rule.startsWith("regex:")) { const expression = regex(rule.slice(6)); return Boolean(expression && expression.test(text)); }
+  if (/^\/.+\/[gimsuy]*$/.test(rule)) { const expression = regex(rule); return Boolean(expression && expression.test(text)); }
+  if (rule.startsWith("ext:")) return text.endsWith(rule.slice(4));
+  if (rule.startsWith(".")) return text.endsWith(rule);
+  return globRegex(rule.replace(/^glob:/, "")).test(text);
+}
+
+function matchDiff(pattern, diff) {
+  const rule = String(pattern || "").trim();
+  const expression = regex(rule.startsWith("regex:") ? rule.slice(6) : rule);
+  return expression ? expression.test(String(diff || "")) : String(diff || "").includes(rule);
+}
+
+function symbols(changeSet) {
+  return (changeSet.symbols || []).map((item) => typeof item === "string" ? item : item && (item.name || item.symbol)).filter(Boolean);
+}
+
+function effectiveAction(rule, config = {}) {
+  // Configuration may only make a rule stricter; explicit policy always wins.
+  return rule.on_violation === "block" || config.on_violation === "block" ? "block" : "warn";
+}
+
+function evaluate(rules, changeSet = {}, options = {}) {
+  const paths = [...new Set([...(changeSet.paths || []), ...(changeSet.files || [])])];
+  const diff = changeSet.diff || "";
+  const knownSymbols = symbols(changeSet);
+  const result = { passed: [], blocked: [], warnings: [] };
+  for (const rule of rules || []) {
+    if (!rule || !rule.enforcement_rule) continue;
+    const matcher = rule.enforcement_rule.match;
+    const matchedPaths = paths.filter((item) => matcher.paths.some((pattern) => matchPath(pattern, item)));
+    const matchedDiff = matcher.diff.filter((pattern) => matchDiff(pattern, diff));
+    const matchedSymbols = matcher.symbols.filter((pattern) => knownSymbols.some((item) => matchPath(pattern, item) || item === pattern));
+    const evidence = [...matchedPaths, ...matchedDiff, ...matchedSymbols];
+    if (!evidence.length) {
+      result.passed.push({ guardrail: rule.id, severity: rule.enforcement_rule.severity, evidence: rule.enforcement_rule.evidence || [] });
+      continue;
+    }
+    const finding = {
+      guardrail: rule.id,
+      severity: rule.enforcement_rule.severity,
+      code: "DECLARATIVE_GUARDRAIL_MATCH",
+      message: `${rule.id} matched declarative enforcement.`,
+      evidence: [...new Set(evidence)],
+      declared_evidence: rule.enforcement_rule.evidence || []
+    };
+    if (effectiveAction(rule.enforcement_rule, options.config) === "block") result.blocked.push(finding);
+    else result.warnings.push(finding);
+  }
+  return result;
+}
+
+module.exports = { ACTIONS, SEVERITIES, enforcementBlock, evaluate, parseEnforcementYaml };

package/lib/memory/compaction.js

@@ -0,0 +1,289 @@
+"use strict";
+
+// Deterministic, opt-in memory compaction. This deliberately has no model,
+// embedding, or network dependency: the only inputs are canonical Markdown
+// records and the project's explicitly configured threshold.
+const fs = require("node:fs");
+const path = require("node:path");
+const {
+  ARTIFACT_TYPES,
+  ArtifactRepository,
+  METHOD_VERSION,
+  atomicWrite,
+  parseArtifact,
+  sha256,
+  validateArtifact,
+  withArtifactLock
+} = require("../v2/artifacts");
+const { extractRelations, sectionItems } = require("./markdown");
+const { assertNoSecret } = require("../security/secrets");
+const { assertCanonicalWrite } = require("../runtime/mutation-gateway");
+
+const DEFAULT_THRESHOLD = 0.6;
+const DEFAULT_MIN_MEMBERS = 3;
+const RECORD_PREFIX = "<!-- scrumrun-compaction-v1: ";
+const RECORD_SUFFIX = " -->";
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function configNumber(content, key, fallback, { min = 0, max = Number.MAX_SAFE_INTEGER } = {}) {
+  const match = String(content || "").match(new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:\\s*([^\\r\\n#]+)`, "m"));
+  if (!match) return fallback;
+  const value = Number(match[1].trim());
+  return Number.isFinite(value) && value >= min && value <= max ? value : fallback;
+}
+
+function compactionConfig(projectRoot) {
+  const file = path.join(projectRoot, ".scrumrun", "config.md");
+  const content = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  return {
+    threshold: configNumber(content, "memory.compaction.threshold", DEFAULT_THRESHOLD, { min: 0, max: 1 }),
+    minMembers: Math.floor(configNumber(content, "memory.compaction.min_members", DEFAULT_MIN_MEMBERS, { min: 2, max: 100 }))
+  };
+}
+
+function titleOf(body, fallback) {
+  return ((String(body || "").match(/^#\s+([^\r\n]+)/m) || [])[1] || fallback).trim();
+}
+
+function featureSet(artifact) {
+  const features = new Set();
+  if (artifact.record.subject_id) features.add(`subject:${String(artifact.record.subject_id).toLowerCase()}`);
+  if (artifact.record.subject_type) features.add(`subject-type:${String(artifact.record.subject_type).toLowerCase()}`);
+  for (const relation of extractRelations(artifact.body)) {
+    features.add(`relation:${relation.relation.toLowerCase()}:${String(relation.target).toLowerCase()}`);
+    // Keep used_by separately visible in preview/evidence, while also being a relation.
+    if (relation.relation.toLowerCase() === "used_by") features.add(`used_by:${String(relation.target).toLowerCase()}`);
+  }
+  const tagText = [
+    String(artifact.body || "").match(/(?:^|\s)#([a-z][a-z0-9_-]{1,})\b/gi) || [],
+    ...sectionItems(artifact.body, ["tags", "topics"])
+  ].join(" ");
+  for (const token of tagText.match(/#?([a-z][a-z0-9_-]{1,})/gi) || []) {
+    const normalized = token.replace(/^#/, "").toLowerCase();
+    if (normalized) features.add(`tag:${normalized}`);
+  }
+  return features;
+}
+
+function overlap(left, right) {
+  const union = new Set([...left, ...right]);
+  if (!union.size) return 0;
+  let common = 0;
+  for (const value of left) if (right.has(value)) common++;
+  return common / union.size;
+}
+
+function activeMemory(repository) {
+  return ["knowledge", "insight"].flatMap((kind) => repository.list(kind))
+    .filter((artifact) => !artifact.errors.length)
+    .filter((artifact) => (artifact.record.kind === "knowledge" && artifact.record.status === "approved")
+      || (artifact.record.kind === "insight" && artifact.record.status === "confirmed"))
+    .filter((artifact) => !artifact.record.superseded_by)
+    .map((artifact) => ({ ...artifact, title: titleOf(artifact.body, artifact.record.id), features: featureSet(artifact) }))
+    .sort((left, right) => left.record.id.localeCompare(right.record.id));
+}
+
+function labelFor(members) {
+  const counts = new Map();
+  for (const member of members) {
+    for (const feature of member.features) counts.set(feature, (counts.get(feature) || 0) + 1);
+  }
+  const shared = [...counts.entries()]
+    .filter(([, count]) => count === members.length)
+    .map(([feature]) => feature)
+    .sort();
+  return shared[0] || `memory-${members.map((member) => member.record.id).join("-").toLowerCase()}`;
+}
+
+function compactKey(members) {
+  return sha256(members.map((member) => member.record.id).sort().join("\n")).slice(0, 16);
+}
+
+function proposedClusters(projectRoot) {
+  const repository = new ArtifactRepository(path.join(projectRoot, ".scrumrun"));
+  const config = compactionConfig(projectRoot);
+  const members = activeMemory(repository);
+  const parent = members.map((_, index) => index);
+  const find = (index) => parent[index] === index ? index : (parent[index] = find(parent[index]));
+  const join = (left, right) => {
+    const a = find(left); const b = find(right);
+    if (a !== b) parent[b] = a;
+  };
+  const links = [];
+  for (let left = 0; left < members.length; left++) {
+    for (let right = left + 1; right < members.length; right++) {
+      const score = overlap(members[left].features, members[right].features);
+      if (score >= config.threshold) {
+        join(left, right);
+        links.push({ left: members[left].record.id, right: members[right].record.id, score });
+      }
+    }
+  }
+  const groups = new Map();
+  for (let index = 0; index < members.length; index++) {
+    const root = find(index);
+    if (!groups.has(root)) groups.set(root, []);
+    groups.get(root).push(members[index]);
+  }
+  const clusters = [...groups.values()]
+    .filter((group) => group.length >= config.minMembers)
+    .map((group) => {
+      const label = labelFor(group);
+      return {
+        key: compactKey(group),
+        label,
+        members: group.map((member) => ({ id: member.record.id, kind: member.record.kind, title: member.title })),
+        evidence: group.map((member) => member.record.id),
+        links: links.filter((link) => group.some((member) => member.record.id === link.left) && group.some((member) => member.record.id === link.right))
+      };
+    })
+    .sort((left, right) => left.key.localeCompare(right.key));
+  return { config, clusters };
+}
+
+function updateFrontmatter(content, updates) {
+  const match = String(content).match(/^---\r?\n([\s\S]*?)\r?\n---([\s\S]*)$/);
+  if (!match) throw new Error("Memory artifact has malformed frontmatter.");
+  let frontmatter = match[1];
+  for (const [field, value] of Object.entries(updates)) {
+    const line = new RegExp(`^${field}:\\s*.*$`, "m");
+    const rendered = value === null ? "null" : String(value);
+    frontmatter = line.test(frontmatter) ? frontmatter.replace(line, `${field}: ${rendered}`) : `${frontmatter}\n${field}: ${rendered}`;
+  }
+  return `---\n${frontmatter}\n---${match[2]}`;
+}
+
+function nextDossierId(repository) {
+  const largest = repository.list("dossier").reduce((max, artifact) => Math.max(max, Number((artifact.record.id.match(/-(\d+)$/) || [])[1]) || 0), 0);
+  return `DOS-${String(largest + 1).padStart(3, "0")}`;
+}
+
+function recordComment(record) {
+  return `${RECORD_PREFIX}${Buffer.from(JSON.stringify(record)).toString("base64")}${RECORD_SUFFIX}`;
+}
+
+function readRecord(body) {
+  const match = String(body || "").match(/<!-- scrumrun-compaction-v1: ([A-Za-z0-9+/=]+) -->/);
+  if (!match) throw new Error("Dossier does not contain a reversible compaction record.");
+  try {
+    const record = JSON.parse(Buffer.from(match[1], "base64").toString("utf8"));
+    if (record.version !== 1 || !Array.isArray(record.sources)) throw new Error("invalid record");
+    return record;
+  } catch {
+    throw new Error("Dossier compaction record is malformed.");
+  }
+}
+
+function dossierBody(cluster, record) {
+  const summaries = cluster.members.map((member) => `- ${member.id}: ${member.title}`).join("\n");
+  return [
+    `# Compacted memory — ${cluster.label}`,
+    "",
+    "## Scope",
+    "",
+    `Deterministic compaction of ${cluster.members.length} related confirmed memory records around \`${cluster.label}\`.`,
+    "",
+    "## Sources",
+    "",
+    summaries,
+    "",
+    "## Evidence",
+    "",
+    cluster.evidence.map((id) => `- ${id}`).join("\n"),
+    "",
+    "## Relations",
+    "",
+    cluster.evidence.map((id) => `- compacts: ${id}`).join("\n"),
+    "",
+    "## Compaction",
+    "",
+    `- Key: ${cluster.key}`,
+    `- Threshold: ${record.threshold}`,
+    `- Applied: ${record.applied_at}`,
+    "",
+    recordComment(record)
+  ].join("\n");
+}
+
+function applyCompaction(projectRoot, { approved = false } = {}) {
+  if (!approved) throw new Error("Memory compaction requires explicit approval: pass --approve with --apply.");
+  const preview = proposedClusters(projectRoot);
+  if (!preview.clusters.length) return { ...preview, applied: [] };
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  return withArtifactLock(scrumDir, "memory-compaction", () => {
+    const repository = new ArtifactRepository(scrumDir);
+    const applied = [];
+    for (const cluster of preview.clusters) {
+      const sources = cluster.members.map(({ id, kind }) => {
+        const artifact = repository.read(kind, id);
+        if (!artifact || artifact.errors.length || artifact.record.superseded_by) throw new Error(`Compaction source changed: ${id}`);
+        return artifact;
+      });
+      const date = today();
+      const dossierId = nextDossierId(repository);
+      const snapshots = sources.map((source) => ({
+        id: source.record.id,
+        kind: source.record.kind,
+        file: path.relative(scrumDir, source.file).split(path.sep).join("/"),
+        original: Buffer.from(fs.readFileSync(source.file, "utf8")).toString("base64")
+      }));
+      const record = { version: 1, key: cluster.key, threshold: preview.config.threshold, applied_at: date, sources: snapshots };
+      const body = dossierBody(cluster, record);
+      const dossier = { id: dossierId, kind: "dossier", status: "active", created: date, updated: date, method: METHOD_VERSION, compaction_key: cluster.key };
+      assertNoSecret([body, ...snapshots.map((source) => source.original)]);
+      assertCanonicalWrite(projectRoot, "compact-memory", [body, ...sources.map((source) => fs.readFileSync(source.file, "utf8"))]);
+      const changed = [];
+      try {
+        repository.write(dossier, body);
+        for (const source of sources) {
+          const current = fs.readFileSync(source.file, "utf8");
+          const next = updateFrontmatter(current, { superseded_by: dossierId, updated: date });
+          const parsed = parseArtifact(next);
+          const errors = [...parsed.errors, ...validateArtifact(parsed.record, source.record.kind)];
+          if (errors.length) throw new Error(`Compaction source validation failed for ${source.record.id}: ${errors.join("; ")}`);
+          atomicWrite(source.file, next);
+          changed.push({ file: source.file, content: current, applied_sha256: sha256(next) });
+        }
+        // Store the expected post-apply bytes only after all source writes succeeded.
+        record.sources.forEach((source, index) => { source.applied_sha256 = changed[index].applied_sha256; });
+        repository.write(dossier, dossierBody(cluster, record), { overwrite: true });
+        applied.push({ dossier: dossierId, sources: sources.map((source) => source.record.id), key: cluster.key });
+      } catch (error) {
+        for (const source of changed.reverse()) atomicWrite(source.file, source.content);
+        const file = repository.pathFor(dossier);
+        if (fs.existsSync(file)) fs.rmSync(file, { force: true });
+        throw error;
+      }
+    }
+    return { ...preview, applied };
+  });
+}
+
+function rollbackCompaction(projectRoot, dossierId) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  return withArtifactLock(scrumDir, "memory-compaction", () => {
+    const repository = new ArtifactRepository(scrumDir);
+    const dossier = repository.read("dossier", dossierId);
+    if (!dossier || dossier.errors.length) throw new Error(`Invalid compaction Dossier: ${dossierId}`);
+    if (dossier.record.status !== "active") throw new Error(`Compaction Dossier is not active: ${dossierId}`);
+    const record = readRecord(dossier.body);
+    const sources = record.sources.map((snapshot) => {
+      const artifact = repository.read(snapshot.kind, snapshot.id);
+      if (!artifact || artifact.errors.length) throw new Error(`Compaction source is missing or invalid: ${snapshot.id}`);
+      const content = fs.readFileSync(artifact.file, "utf8");
+      if (sha256(content) !== snapshot.applied_sha256) throw new Error(`Refusing rollback: ${snapshot.id} changed after compaction.`);
+      return { ...snapshot, file: artifact.file, content };
+    });
+    const date = today();
+    assertCanonicalWrite(projectRoot, "rollback-memory-compaction", [fs.readFileSync(dossier.file, "utf8"), ...sources.map((source) => source.content)]);
+    for (const source of sources) atomicWrite(source.file, Buffer.from(source.original, "base64").toString("utf8"));
+    const archived = updateFrontmatter(fs.readFileSync(dossier.file, "utf8"), { status: "archived", updated: date });
+    atomicWrite(dossier.file, `${archived.trimEnd()}\n\n## Compaction rollback\n\n- Restored: ${date}\n`);
+    return { dossier: dossierId, restored: sources.map((source) => source.id) };
+  });
+}
+
+module.exports = { DEFAULT_MIN_MEMBERS, DEFAULT_THRESHOLD, applyCompaction, compactionConfig, proposedClusters, rollbackCompaction };

package/lib/memory/index.js

@@ -14,6 +14,10 @@ const { canonicalWatchSnapshot, fileWatchSnapshot } = require("../runtime/canoni
 const CACHE_RELATIVE = path.join(".cache", "semantic-index.sqlite");
 const INDEX_SCHEMA_VERSION = 5;
 const INACTIVE = new Set(["rejected", "invalidated", "deprecated", "archived"]);
+
+function isSearchActive(record) {
+  return !INACTIVE.has(record.status) && !record.superseded_by;
+}
 const SEARCH_BACKENDS = new Set(["auto", "fts5", "like"]);
 const MAX_SEARCH_TOKENS = 32;
 
@@ -407,7 +411,7 @@ function rebuildIndex(projectRoot, { searchBackend = "auto" } = {}) {
           artifact.record.last_verified_commit || null,
           artifact.record.review_trigger || null,
           normalizeSearchText(artifact.title, artifact.content),
-          INACTIVE.has(artifact.record.status) ? 0 : 1
+          isSearchActive(artifact.record) ? 1 : 0
         );
         if (insertFts) insertFts.run(artifact.record.id, artifact.title, artifact.content);
         for (const edge of explicitEdges(artifact)) insertEdge.run(artifact.record.id, edge.relation, edge.target, edge.evidence, "canonical");
@@ -474,6 +478,62 @@ function rebuildIndex(projectRoot, { searchBackend = "auto" } = {}) {
   };
 }
 
+function incrementalArtifact(projectRoot, changedPaths = []) {
+  if (!Array.isArray(changedPaths) || changedPaths.length !== 1) return null;
+  const relative = String(changedPaths[0]).split(path.sep).join("/").replace(/^\.scrumrun\//, "");
+  const kind = Object.entries(ARTIFACT_TYPES).find(([, spec]) => relative.startsWith(`${spec.directory}/`));
+  if (!kind || !relative.endsWith(".md")) return null;
+  const target = indexPath(projectRoot);
+  if (!fs.existsSync(target)) return null;
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  const repository = new ArtifactRepository(scrumDir);
+  const id = path.basename(relative, ".md");
+  const artifact = repository.read(kind[0], id);
+  if (!artifact || artifact.errors.length || /^(?:##\s+(?:Evidence|Subject|Relations)\b)/mi.test(artifact.body || "")) return null;
+  const content = fs.readFileSync(artifact.file, "utf8");
+  if (containsSecret(content)) throw new Error(`Secret-like content detected in canonical artifact: ${relative}`);
+  let database;
+  try {
+    database = new DatabaseSync(target);
+    const metadata = new Map(database.prepare("SELECT key, value FROM metadata").all().map((row) => [row.key, row.value]));
+    if (metadata.get("schema_version") !== String(INDEX_SCHEMA_VERSION)) return null;
+    const backend = metadata.get("search_backend");
+    const title = titleFromBody(artifact.body, artifact.record.id);
+    const hash = sha256(content);
+    database.exec("BEGIN IMMEDIATE");
+    try {
+      database.prepare("DELETE FROM edges WHERE from_id = ?").run(artifact.record.id);
+      database.prepare("DELETE FROM artifacts WHERE id = ?").run(artifact.record.id);
+      if (backend === "fts5") database.prepare("DELETE FROM artifacts_fts WHERE id = ?").run(artifact.record.id);
+      database.prepare("INSERT INTO artifacts(id, kind, status, title, path, hash, content, branch, valid_from, valid_until, last_verified_commit, review_trigger, search_text, active) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)").run(
+        artifact.record.id, artifact.record.kind, artifact.record.status, title, relative, hash, content,
+        artifact.record.branch || null, artifact.record.valid_from || null, artifact.record.valid_until || null,
+        artifact.record.last_verified_commit || null, artifact.record.review_trigger || null,
+        normalizeSearchText(title, content), isSearchActive(artifact.record) ? 1 : 0
+      );
+      if (backend === "fts5") database.prepare("INSERT INTO artifacts_fts(id, title, content) VALUES (?, ?, ?)").run(artifact.record.id, title, content);
+      const insertEdge = database.prepare("INSERT OR IGNORE INTO edges(from_id, relation, to_id, evidence, confidence) VALUES (?, ?, ?, ?, ?)");
+      for (const edge of explicitEdges({ record: artifact.record, body: artifact.body })) insertEdge.run(artifact.record.id, edge.relation, edge.target, edge.evidence, "canonical");
+      const rows = [
+        ...database.prepare("SELECT path, hash FROM artifacts").all().map((row) => `${row.path}\0${row.hash}`),
+        ...database.prepare("SELECT path, fingerprint FROM code_nodes WHERE kind = 'module'").all().map((row) => `${row.path}\0${row.fingerprint}`)
+      ];
+      const watch = sourceWatchSnapshot(projectRoot);
+      const update = database.prepare("INSERT OR REPLACE INTO metadata(key, value) VALUES (?, ?)");
+      update.run("source_fingerprint", sha256(rows.sort().join("\n")));
+      update.run("source_watch_fingerprint", watch.fingerprint);
+      update.run("artifact_count", String(database.prepare("SELECT COUNT(*) AS count FROM artifacts").get().count));
+      database.exec("COMMIT");
+      return { file: target, mode: "incremental-artifact", changed: relative, fingerprint: sha256(rows.sort().join("\n")), watchFingerprint: watch.fingerprint };
+    } catch (error) {
+      database.exec("ROLLBACK");
+      throw error;
+    }
+  } finally {
+    if (database) database.close();
+  }
+}
+
 function runtimeSupportsFts5(database) {
   try {
     database.prepare("SELECT 1 FROM artifacts_fts LIMIT 1").get();
@@ -762,4 +822,4 @@ function mapStatus(projectRoot, { semanticStatus = null } = {}) {
   }
 }
 
-module.exports = { CACHE_RELATIVE, INDEX_SCHEMA_VERSION, graphIndex, indexPath, indexStatus, mapStatus, memoryFingerprint, queryIndex, rebuildIndex, sourceSnapshot, sourceWatchSnapshot, writeMap };
+module.exports = { CACHE_RELATIVE, INDEX_SCHEMA_VERSION, graphIndex, incrementalArtifact, indexPath, indexStatus, mapStatus, memoryFingerprint, queryIndex, rebuildIndex, sourceSnapshot, sourceWatchSnapshot, writeMap };

package/lib/migrate/ops.js

@@ -0,0 +1,92 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function sha256(content) {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+function insideRoot(projectRoot, target) {
+  const absoluteRoot = path.resolve(projectRoot);
+  const absoluteTarget = path.resolve(projectRoot, target);
+  return absoluteTarget === absoluteRoot || absoluteTarget.startsWith(`${absoluteRoot}${path.sep}`);
+}
+
+function requireInside(projectRoot, relative, label) {
+  if (!relative || typeof relative !== "string") throw new Error(`${label}: path must be a non-empty string`);
+  if (path.isAbsolute(relative)) throw new Error(`${label}: absolute paths are not allowed`);
+  if (!insideRoot(projectRoot, relative)) throw new Error(`${label}: path escapes the project root`);
+  return path.resolve(projectRoot, relative);
+}
+
+const OPS = Object.freeze({
+  rename_path(projectRoot, step, journal) {
+    const from = requireInside(projectRoot, step.from, "rename_path.from");
+    const to = requireInside(projectRoot, step.to, "rename_path.to");
+    if (!fs.existsSync(from)) {
+      if (step.if_missing === "skip") return { skipped: true };
+      throw new Error(`rename_path: source does not exist: ${step.from}`);
+    }
+    if (fs.existsSync(to)) throw new Error(`rename_path: destination already exists: ${step.to}`);
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.renameSync(from, to);
+    journal.push({ op: "rename_path", from: step.from, to: step.to });
+    return { renamed: true };
+  },
+  bump_schema(projectRoot, step, journal) {
+    const file = requireInside(projectRoot, step.file || "method.json", "bump_schema.file");
+    if (!fs.existsSync(file)) throw new Error(`bump_schema: method file missing: ${step.file || "method.json"}`);
+    const before = fs.readFileSync(file, "utf8");
+    const method = JSON.parse(before);
+    const previous = method.schemas && method.schemas[step.field];
+    if (step.from !== undefined && previous !== step.from) {
+      throw new Error(`bump_schema: expected ${step.field} to be ${step.from}, found ${previous}`);
+    }
+    method.schemas = method.schemas || {};
+    method.schemas[step.field] = step.to;
+    fs.writeFileSync(file, `${JSON.stringify(method, null, 2)}\n`);
+    journal.push({ op: "bump_schema", file: step.file || "method.json", field: step.field, from: previous, to: step.to });
+    return { previous, next: step.to };
+  },
+  assert_hash(projectRoot, step) {
+    const file = requireInside(projectRoot, step.file, "assert_hash.file");
+    if (!fs.existsSync(file)) throw new Error(`assert_hash: missing file ${step.file}`);
+    const actual = sha256(fs.readFileSync(file));
+    if (actual !== step.sha256) throw new Error(`assert_hash: ${step.file} hash mismatch (expected ${step.sha256}, got ${actual})`);
+    return { hash: actual };
+  },
+  create_backup(projectRoot, step, journal) {
+    const source = requireInside(projectRoot, step.file, "create_backup.file");
+    const backupRoot = requireInside(projectRoot, step.backup_dir || ".backup", "create_backup.backup_dir");
+    if (!fs.existsSync(source)) throw new Error(`create_backup: missing source ${step.file}`);
+    fs.mkdirSync(backupRoot, { recursive: true });
+    const destination = path.join(backupRoot, path.basename(step.file));
+    fs.copyFileSync(source, destination);
+    journal.push({ op: "create_backup", file: step.file, backup: path.relative(projectRoot, destination) });
+    return { backup: path.relative(projectRoot, destination) };
+  },
+  move_frontmatter_field(projectRoot, step, journal) {
+    const file = requireInside(projectRoot, step.file, "move_frontmatter_field.file");
+    if (!fs.existsSync(file)) throw new Error(`move_frontmatter_field: missing ${step.file}`);
+    const source = fs.readFileSync(file, "utf8");
+    const match = /^---\r?\n([\s\S]*?)\r?\n---([\s\S]*)$/.exec(source);
+    if (!match) throw new Error(`move_frontmatter_field: no frontmatter in ${step.file}`);
+    const lines = match[1].split(/\r?\n/);
+    const fromRe = new RegExp(`^${step.from}:\\s*(.*)$`);
+    const idx = lines.findIndex((line) => fromRe.test(line));
+    if (idx === -1) {
+      if (step.if_missing === "skip") return { skipped: true };
+      throw new Error(`move_frontmatter_field: field ${step.from} not found in ${step.file}`);
+    }
+    const value = lines[idx].replace(fromRe, "$1");
+    lines[idx] = `${step.to}: ${value}`;
+    const next = `---\n${lines.join("\n")}\n---${match[2]}`;
+    fs.writeFileSync(file, next);
+    journal.push({ op: "move_frontmatter_field", file: step.file, from: step.from, to: step.to, value });
+    return { renamed: true };
+  }
+});
+
+module.exports = { OPS, sha256, requireInside };