scrumrun 2.0.0 → 2.1.1

package/lib/memory/index.js

@@ -5,12 +5,17 @@ const path = require("node:path");
 const { DatabaseSync } = require("node:sqlite");
 const { ARTIFACT_TYPES, ArtifactRepository, assertNoSymlinkPath, atomicWrite, sha256 } = require("../v2/artifacts");
 const { extractEvidence, extractRelations } = require("./markdown");
-const { scanProject } = require("../code-intel/scanner");
+const { JavaScriptAdapter } = require("../code-intel/javascript");
+const { scanProject, sourceFiles } = require("../code-intel/scanner");
 const { DEFAULT_CONTEXT_RESULTS, DEFAULT_RELATIONS_PER_RESULT, MAX_CONTEXT_RESULTS, MAX_RELATIONS_PER_RESULT } = require("../runtime/budgets");
 const { containsSecret } = require("../security/secrets");
+const { canonicalWatchSnapshot, fileWatchSnapshot } = require("../runtime/canonical-snapshot");
 
 const CACHE_RELATIVE = path.join(".cache", "semantic-index.sqlite");
+const INDEX_SCHEMA_VERSION = 4;
 const INACTIVE = new Set(["rejected", "invalidated", "deprecated", "archived"]);
+const SEARCH_BACKENDS = new Set(["auto", "fts5", "like"]);
+const MAX_SEARCH_TOKENS = 32;
 
 function indexPath(projectRoot) {
   return path.join(projectRoot, ".scrumrun", CACHE_RELATIVE);
@@ -20,6 +25,10 @@ function titleFromBody(body, fallback) {
   return ((String(body || "").match(/^#\s+([^\r\n]+)/m) || [])[1] || fallback).trim();
 }
 
+function normalizeSearchText(...values) {
+  return values.map((value) => String(value || "")).join(" ").normalize("NFKC").toLowerCase();
+}
+
 function canonicalArtifacts(scrumDir) {
   const repository = new ArtifactRepository(scrumDir);
   const artifacts = [];
@@ -46,7 +55,7 @@ function memoryFingerprint(scrumDir) {
   return sha256(rows.join("\n"));
 }
 
-function sourceSnapshot(projectRoot) {
+function sourceSnapshot(projectRoot, { watch = null } = {}) {
   const scrumDir = path.join(projectRoot, ".scrumrun");
   const artifacts = canonicalArtifacts(scrumDir);
   const code = scanProject(projectRoot);
@@ -54,8 +63,26 @@ function sourceSnapshot(projectRoot) {
   const codeRows = code.nodes
     .filter((node) => node.kind === "module")
     .map((node) => `${node.path}\0${node.fingerprint}`);
-  const fingerprint = sha256([...artifactRows, ...codeRows, `commit\0${code.commit || "unavailable"}`].sort().join("\n"));
-  return { artifacts, code, fingerprint };
+  const fingerprint = sha256([...artifactRows, ...codeRows].sort().join("\n"));
+  return { artifacts, code, fingerprint, watch: watch || sourceWatchSnapshot(projectRoot) };
+}
+
+function sourceWatchSnapshot(projectRoot) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  const canonical = canonicalWatchSnapshot(scrumDir);
+  const adapters = [new JavaScriptAdapter()];
+  const discovered = sourceFiles(path.resolve(projectRoot), adapters);
+  const code = fileWatchSnapshot(projectRoot, discovered.files.map((item) => item.file), adapters.map((adapter) => `adapter\0${adapter.id}`));
+  const rows = [
+    ...canonical.rows.map((row) => `canonical\0${row}`),
+    ...code.rows.map((row) => `code\0${row}`)
+  ];
+  return {
+    fingerprint: sha256(rows.sort().join("\n")),
+    canonicalFiles: canonical.files,
+    sourceFiles: code.files,
+    warnings: discovered.warnings
+  };
 }
 
 function explicitEdges(artifact) {
@@ -83,7 +110,8 @@ function explicitEdges(artifact) {
   return [...unique.values()];
 }
 
-function createSchema(database) {
+function createSchema(database, { searchBackend = "auto" } = {}) {
+  if (!SEARCH_BACKENDS.has(searchBackend)) throw new Error(`Unknown semantic search backend: ${searchBackend}`);
   database.exec(`
     PRAGMA journal_mode = DELETE;
     PRAGMA synchronous = FULL;
@@ -100,6 +128,7 @@ function createSchema(database) {
       valid_until TEXT,
       last_verified_commit TEXT,
       review_trigger TEXT,
+      search_text TEXT NOT NULL,
       active INTEGER NOT NULL CHECK (active IN (0, 1))
     );
     CREATE TABLE edges (
@@ -122,7 +151,8 @@ function createSchema(database) {
       status TEXT NOT NULL CHECK (status IN ('current', 'orphaned')),
       language TEXT NOT NULL,
       exported INTEGER NOT NULL CHECK (exported IN (0, 1)),
-      remapped_from TEXT
+      remapped_from TEXT,
+      search_text TEXT NOT NULL
     );
     CREATE TABLE evidence_snapshots (
       artifact_id TEXT NOT NULL,
@@ -146,9 +176,18 @@ function createSchema(database) {
     CREATE INDEX edges_from ON edges(from_id);
     CREATE INDEX edges_to ON edges(to_id);
     CREATE INDEX artifacts_status ON artifacts(status);
-    CREATE VIRTUAL TABLE artifacts_fts USING fts5(id UNINDEXED, title, content, tokenize='unicode61');
-    CREATE VIRTUAL TABLE code_fts USING fts5(id UNINDEXED, name, qualified_name, path, tokenize='unicode61');
   `);
+  if (searchBackend === "like") return "like";
+  try {
+    database.exec(`
+      CREATE VIRTUAL TABLE artifacts_fts USING fts5(id UNINDEXED, title, content, tokenize='unicode61');
+      CREATE VIRTUAL TABLE code_fts USING fts5(id UNINDEXED, name, qualified_name, path, tokenize='unicode61');
+    `);
+    return "fts5";
+  } catch (error) {
+    if (searchBackend === "fts5" || !/no such module:\s*fts5/i.test(error.message)) throw error;
+    return "like";
+  }
 }
 
 function tableExists(database, name) {
@@ -321,7 +360,7 @@ function derivedInvalidations(projectRoot, artifacts, codeNodes, prior, evidence
   return { invalidations: [...invalidations.values()], subjects };
 }
 
-function rebuildIndex(projectRoot) {
+function rebuildIndex(projectRoot, { searchBackend = "auto" } = {}) {
   const scrumDir = path.join(projectRoot, ".scrumrun");
   if (!fs.existsSync(scrumDir)) throw new Error("Not a ScrumRun project: .scrumrun/ is missing.");
   const cacheDir = path.join(scrumDir, ".cache");
@@ -337,14 +376,19 @@ function rebuildIndex(projectRoot) {
   const evidence = evidenceSnapshots(projectRoot, artifacts);
   const derived = derivedInvalidations(projectRoot, artifacts, remapped.nodes, prior, evidence);
   let database;
+  let selectedSearchBackend;
   try {
     database = new DatabaseSync(temp);
-    createSchema(database);
-    const insertArtifact = database.prepare("INSERT INTO artifacts(id, kind, status, title, path, hash, content, valid_from, valid_until, last_verified_commit, review_trigger, active) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
-    const insertFts = database.prepare("INSERT INTO artifacts_fts(id, title, content) VALUES (?, ?, ?)");
+    selectedSearchBackend = createSchema(database, { searchBackend });
+    const insertArtifact = database.prepare("INSERT INTO artifacts(id, kind, status, title, path, hash, content, valid_from, valid_until, last_verified_commit, review_trigger, search_text, active) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
+    const insertFts = selectedSearchBackend === "fts5"
+      ? database.prepare("INSERT INTO artifacts_fts(id, title, content) VALUES (?, ?, ?)")
+      : null;
     const insertEdge = database.prepare("INSERT OR IGNORE INTO edges(from_id, relation, to_id, evidence, confidence) VALUES (?, ?, ?, ?, ?)");
-    const insertCode = database.prepare("INSERT INTO code_nodes(id, kind, name, qualified_name, path, line, fingerprint, commit_hash, status, language, exported, remapped_from) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
-    const insertCodeFts = database.prepare("INSERT INTO code_fts(id, name, qualified_name, path) VALUES (?, ?, ?, ?)");
+    const insertCode = database.prepare("INSERT INTO code_nodes(id, kind, name, qualified_name, path, line, fingerprint, commit_hash, status, language, exported, remapped_from, search_text) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
+    const insertCodeFts = selectedSearchBackend === "fts5"
+      ? database.prepare("INSERT INTO code_fts(id, name, qualified_name, path) VALUES (?, ?, ?, ?)")
+      : null;
     database.exec("BEGIN IMMEDIATE");
     try {
       for (const artifact of artifacts) {
@@ -360,14 +404,29 @@ function rebuildIndex(projectRoot) {
           artifact.record.valid_until || null,
           artifact.record.last_verified_commit || null,
           artifact.record.review_trigger || null,
+          normalizeSearchText(artifact.title, artifact.content),
           INACTIVE.has(artifact.record.status) ? 0 : 1
         );
-        insertFts.run(artifact.record.id, artifact.title, artifact.content);
+        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");
       }
       for (const node of remapped.nodes) {
-        insertCode.run(node.id, node.kind, node.name, node.qualifiedName, node.path, node.line, node.fingerprint, node.commit || null, node.status, node.language, node.exported ? 1 : 0, node.remappedFrom || null);
-        insertCodeFts.run(node.id, node.name, node.qualifiedName, node.path);
+        insertCode.run(
+          node.id,
+          node.kind,
+          node.name,
+          node.qualifiedName,
+          node.path,
+          node.line,
+          node.fingerprint,
+          node.commit || null,
+          node.status,
+          node.language,
+          node.exported ? 1 : 0,
+          node.remappedFrom || null,
+          normalizeSearchText(node.name, node.qualifiedName, node.path)
+        );
+        if (insertCodeFts) insertCodeFts.run(node.id, node.name, node.qualifiedName, node.path);
       }
       for (const edge of snapshot.code.edges) insertEdge.run(edge.from, edge.relation, edge.to, edge.evidence, edge.confidence);
       for (const edge of prior.edges.filter((item) => remapped.orphanIds.has(item.from_id))) {
@@ -380,11 +439,14 @@ function rebuildIndex(projectRoot) {
       const insertInvalidation = database.prepare("INSERT INTO invalidations(artifact_id, reason, reference, artifact_hash) VALUES (?, ?, ?, ?)");
       for (const item of derived.invalidations) insertInvalidation.run(item.artifactId, item.reason, item.reference, item.artifactHash);
       const metadata = database.prepare("INSERT INTO metadata(key, value) VALUES (?, ?)");
-      metadata.run("schema_version", "2");
+      metadata.run("schema_version", String(INDEX_SCHEMA_VERSION));
       metadata.run("method_version", "2.0.0");
+      metadata.run("search_backend", selectedSearchBackend);
       metadata.run("source_fingerprint", snapshot.fingerprint);
+      metadata.run("source_watch_fingerprint", snapshot.watch.fingerprint);
       metadata.run("artifact_count", String(artifacts.length));
       metadata.run("code_node_count", String(remapped.nodes.length));
+      metadata.run("source_file_count", String(snapshot.watch.sourceFiles));
       metadata.run("code_adapter", snapshot.code.adapterIds.join(","));
       database.exec("COMMIT");
     } catch (error) {
@@ -399,7 +461,24 @@ function rebuildIndex(projectRoot) {
     if (fs.existsSync(temp)) fs.rmSync(temp, { force: true });
     throw error;
   }
-  return { file: target, fingerprint: snapshot.fingerprint, artifacts: artifacts.length, codeNodes: remapped.nodes.length, warnings: snapshot.code.warnings };
+  return {
+    file: target,
+    fingerprint: snapshot.fingerprint,
+    watchFingerprint: snapshot.watch.fingerprint,
+    searchBackend: selectedSearchBackend,
+    artifacts: artifacts.length,
+    codeNodes: remapped.nodes.length,
+    warnings: [...snapshot.code.warnings, ...snapshot.watch.warnings]
+  };
+}
+
+function runtimeSupportsFts5(database) {
+  try {
+    database.prepare("SELECT 1 FROM artifacts_fts LIMIT 1").get();
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 function indexStatus(projectRoot) {
@@ -409,9 +488,35 @@ function indexStatus(projectRoot) {
   try {
     assertNoSymlinkPath(path.join(projectRoot, ".scrumrun"), file);
     database = new DatabaseSync(file, { readOnly: true });
-    const row = database.prepare("SELECT value FROM metadata WHERE key = 'source_fingerprint'").get();
-    const actual = sourceSnapshot(projectRoot).fingerprint;
-    return { exists: true, stale: !row || row.value !== actual, file, stored: row && row.value, actual };
+    const metadata = new Map(database.prepare("SELECT key, value FROM metadata").all().map((row) => [row.key, row.value]));
+    const stored = metadata.get("source_fingerprint") || null;
+    const searchBackend = metadata.get("search_backend") || null;
+    if (
+      metadata.get("schema_version") !== String(INDEX_SCHEMA_VERSION)
+      || !metadata.get("source_watch_fingerprint")
+      || !["fts5", "like"].includes(searchBackend)
+    ) {
+      return { exists: true, stale: true, file, stored, check: "schema", reason: `semantic index schema ${INDEX_SCHEMA_VERSION} rebuild required` };
+    }
+    if (searchBackend === "fts5" && !runtimeSupportsFts5(database)) {
+      return { exists: true, stale: true, file, stored, searchBackend, check: "schema", reason: "semantic index requires unavailable FTS5; fallback rebuild required" };
+    }
+    const watch = sourceWatchSnapshot(projectRoot);
+    if (metadata.get("source_watch_fingerprint") === watch.fingerprint) {
+      return { exists: true, stale: false, file, stored, actual: stored, watch: watch.fingerprint, searchBackend, check: "metadata" };
+    }
+    const actual = sourceSnapshot(projectRoot, { watch }).fingerprint;
+    return {
+      exists: true,
+      stale: !stored || stored !== actual,
+      file,
+      stored,
+      actual,
+      watch: watch.fingerprint,
+      searchBackend,
+      check: "hash",
+      reason: stored === actual ? "file metadata changed but semantic content is unchanged" : "canonical or source content changed"
+    };
   } catch (error) {
     return { exists: true, stale: true, file, error: error.message };
   } finally {
@@ -419,11 +524,40 @@ function indexStatus(projectRoot) {
   }
 }
 
+function searchTokens(query) {
+  return (String(query || "").normalize("NFKC").match(/[\p{L}\p{N}_-]+/gu) || []).slice(0, MAX_SEARCH_TOKENS);
+}
+
 function ftsQuery(query) {
-  const tokens = String(query || "").normalize("NFKC").match(/[\p{L}\p{N}_-]+/gu) || [];
+  const tokens = searchTokens(query);
   return tokens.map((token) => `"${token.replace(/"/g, "")}"`).join(" AND ");
 }
 
+function fallbackArtifactRows(database, tokens, activeClause, cap) {
+  if (!tokens.length) return [];
+  const clauses = tokens.map(() => "instr(a.search_text, ?) > 0").join(" AND ");
+  const parameters = tokens.map((token) => normalizeSearchText(token));
+  return database.prepare(`
+    SELECT a.id, a.kind, a.status, a.title, a.path, a.active, a.valid_until, a.review_trigger
+    FROM artifacts a
+    WHERE ${clauses} ${activeClause}
+    ORDER BY a.id LIMIT ?
+  `).all(...parameters, cap);
+}
+
+function fallbackCodeRows(database, tokens, cap) {
+  if (!tokens.length) return [];
+  const clauses = tokens.map(() => "instr(c.search_text, ?) > 0").join(" AND ");
+  const parameters = tokens.map((token) => normalizeSearchText(token));
+  return database.prepare(`
+    SELECT c.id, c.kind, c.name AS title, c.qualified_name, c.path, c.line, c.fingerprint,
+      c.commit_hash, c.status, c.language, c.remapped_from
+    FROM code_nodes c
+    WHERE ${clauses}
+    ORDER BY CASE c.status WHEN 'current' THEN 0 ELSE 1 END, c.id LIMIT ?
+  `).all(...parameters, cap);
+}
+
 function queryIndex(projectRoot, query, { includeInactive = false, limit = DEFAULT_CONTEXT_RESULTS, relationLimit = DEFAULT_RELATIONS_PER_RESULT, rebuild = true } = {}) {
   const text = String(query || "").trim();
   if (!text) throw new Error("A non-empty memory query is required.");
@@ -436,18 +570,23 @@ function queryIndex(projectRoot, query, { includeInactive = false, limit = DEFAU
   }
   const database = new DatabaseSync(indexPath(projectRoot), { readOnly: true });
   try {
+    const metadata = new Map(database.prepare("SELECT key, value FROM metadata").all().map((row) => [row.key, row.value]));
+    const searchBackend = metadata.get("search_backend");
     const cap = Math.max(1, Math.min(Number(limit) || DEFAULT_CONTEXT_RESULTS, MAX_CONTEXT_RESULTS));
     const relationCap = Math.max(1, Math.min(Number(relationLimit) || DEFAULT_RELATIONS_PER_RESULT, MAX_RELATIONS_PER_RESULT));
     const activeClause = includeInactive ? "" : "AND a.active = 1";
     const matches = new Map();
+    const tokens = searchTokens(text);
     const match = ftsQuery(text);
-    if (match) {
-      const rows = database.prepare(`
-        SELECT a.id, a.kind, a.status, a.title, a.path, a.active, a.valid_until, a.review_trigger, bm25(artifacts_fts) AS rank
-        FROM artifacts_fts JOIN artifacts a ON a.id = artifacts_fts.id
-        WHERE artifacts_fts MATCH ? ${activeClause}
-        ORDER BY rank, a.id LIMIT ?
-      `).all(match, cap);
+    if (tokens.length) {
+      const rows = searchBackend === "fts5"
+        ? database.prepare(`
+          SELECT a.id, a.kind, a.status, a.title, a.path, a.active, a.valid_until, a.review_trigger, bm25(artifacts_fts) AS rank
+          FROM artifacts_fts JOIN artifacts a ON a.id = artifacts_fts.id
+          WHERE artifacts_fts MATCH ? ${activeClause}
+          ORDER BY rank, a.id LIMIT ?
+        `).all(match, cap)
+        : fallbackArtifactRows(database, tokens, activeClause, cap);
       for (const row of rows) matches.set(`artifact:${row.id}`, { ...row, nodeType: "artifact", match: "content" });
     }
     const like = `%${text.toLowerCase()}%`;
@@ -464,14 +603,16 @@ function queryIndex(projectRoot, query, { includeInactive = false, limit = DEFAU
       if (existing) existing.match = "content+relation";
       else matches.set(key, { ...row, nodeType: "artifact", match: "relation" });
     }
-    if (match) {
-      const codeRows = database.prepare(`
-        SELECT c.id, c.kind, c.name AS title, c.qualified_name, c.path, c.line, c.fingerprint,
-          c.commit_hash, c.status, c.language, c.remapped_from, bm25(code_fts) AS rank
-        FROM code_fts JOIN code_nodes c ON c.id = code_fts.id
-        WHERE code_fts MATCH ?
-        ORDER BY CASE c.status WHEN 'current' THEN 0 ELSE 1 END, rank, c.id LIMIT ?
-      `).all(match, cap);
+    if (tokens.length) {
+      const codeRows = searchBackend === "fts5"
+        ? database.prepare(`
+          SELECT c.id, c.kind, c.name AS title, c.qualified_name, c.path, c.line, c.fingerprint,
+            c.commit_hash, c.status, c.language, c.remapped_from, bm25(code_fts) AS rank
+          FROM code_fts JOIN code_nodes c ON c.id = code_fts.id
+          WHERE code_fts MATCH ?
+          ORDER BY CASE c.status WHEN 'current' THEN 0 ELSE 1 END, rank, c.id LIMIT ?
+        `).all(match, cap)
+        : fallbackCodeRows(database, tokens, cap);
       for (const row of codeRows) matches.set(`code:${row.id}`, { ...row, nodeType: "code", match: "code" });
     }
     const codeRelationRows = database.prepare(`
@@ -535,7 +676,7 @@ function queryIndex(projectRoot, query, { includeInactive = false, limit = DEFAU
         relations
       };
     });
-    return { indexFile: indexPath(projectRoot), rebuilt, query: text, results };
+    return { indexFile: indexPath(projectRoot), rebuilt, searchBackend, query: text, results };
   } finally {
     database.close();
   }
@@ -571,7 +712,8 @@ function writeMap(projectRoot, { nodeLimit = 200, edgeLimit = 400 } = {}) {
   const body = [
     "# ScrumRun Project Map",
     "",
-    `Generated: ${new Date().toISOString().slice(0, 10)}`,
+    "Projection schema: 1",
+    `Generated: ${new Date().toISOString()}`,
     `Source fingerprint: ${current.stored}`,
     "Authority: none; rebuild from canonical artifacts and source code.",
     "",
@@ -597,4 +739,22 @@ function writeMap(projectRoot, { nodeLimit = 200, edgeLimit = 400 } = {}) {
   return { file, nodes: graph.nodes.length, edges: graph.edges.length, fingerprint: current.stored };
 }
 
-module.exports = { CACHE_RELATIVE, graphIndex, indexPath, indexStatus, memoryFingerprint, queryIndex, rebuildIndex, sourceSnapshot, writeMap };
+function mapStatus(projectRoot, { semanticStatus = null } = {}) {
+  const file = path.join(projectRoot, ".scrumrun", "map.md");
+  if (!fs.existsSync(file)) return { exists: false, stale: true, file, reason: "map.md is missing" };
+  try {
+    assertNoSymlinkPath(path.join(projectRoot, ".scrumrun"), file);
+    if (!fs.lstatSync(file).isFile()) return { exists: true, stale: true, file, reason: "map.md is not a regular file" };
+    const content = fs.readFileSync(file, "utf8");
+    const stored = (content.match(/^Source fingerprint:\s*([a-f0-9]{64})$/m) || [])[1] || null;
+    if (!stored) return { exists: true, stale: true, file, stored, reason: "map.md has no source fingerprint" };
+    const semantic = semanticStatus || indexStatus(projectRoot);
+    if (!semantic.exists) return { exists: true, stale: true, file, stored, reason: "semantic index is missing" };
+    if (semantic.stale) return { exists: true, stale: true, file, stored, reason: semantic.reason || "semantic index is stale" };
+    return { exists: true, stale: stored !== semantic.stored, file, stored, actual: semantic.stored, reason: stored === semantic.stored ? null : "map fingerprint differs from the semantic index" };
+  } catch (error) {
+    return { exists: true, stale: true, file, error: error.message, reason: "map freshness check failed" };
+  }
+}
+
+module.exports = { CACHE_RELATIVE, INDEX_SCHEMA_VERSION, graphIndex, indexPath, indexStatus, mapStatus, memoryFingerprint, queryIndex, rebuildIndex, sourceSnapshot, sourceWatchSnapshot, writeMap };

package/lib/memory/service.js

@@ -15,6 +15,7 @@ const {
 } = require("../v2/artifacts");
 const { extractEvidence, renderBullets } = require("./markdown");
 const { assertNoSecret } = require("../security/secrets");
+const { assertCanonicalWrite } = require("../runtime/mutation-gateway");
 
 const MEMORY_KINDS = new Set(["knowledge", "decision", "insight", "dossier"]);
 const DEFAULT_STATUS = Object.freeze({ knowledge: "candidate", decision: "open", insight: "candidate", dossier: "active" });
@@ -203,6 +204,7 @@ function createMemoryUnlocked(projectRoot, kind, options = {}) {
     "",
     `- ${created}: ${record.status} — proposed by ${sourceType}.`
   ].join("\n");
+  assertCanonicalWrite(projectRoot, `create-${kind}`, [title, content, body]);
   repository.write(record, body);
   return repository.read(kind, record.id);
 }
@@ -267,6 +269,7 @@ function transitionMemoryUnlocked(projectRoot, kind, id, action, options = {}) {
   const parsed = parseArtifact(next);
   const errors = [...parsed.errors, ...validateArtifact(parsed.record, kind)];
   if (errors.length) throw new Error(`Memory transition validation failed: ${errors.join("; ")}`);
+  assertCanonicalWrite(projectRoot, `transition-${kind}`, [next]);
   atomicWrite(artifact.file, next);
   return repository.read(kind, id);
 }

package/lib/runtime/budgets.js

@@ -7,10 +7,14 @@ const MAX_CONTEXT_RESULTS = 100;
 const DEFAULT_CONTEXT_RESULTS = 10;
 const MAX_RELATIONS_PER_RESULT = 100;
 const DEFAULT_RELATIONS_PER_RESULT = 40;
+const KERNEL_LIFECYCLE_MAX_MS = 1500;
+const INDEX_STATUS_100_MAX_MS = 2500;
 
 module.exports = {
   DEFAULT_CONTEXT_RESULTS,
   DEFAULT_RELATIONS_PER_RESULT,
+  INDEX_STATUS_100_MAX_MS,
+  KERNEL_LIFECYCLE_MAX_MS,
   LEAN_CONTROL_CONTEXT_MAX_CHARS,
   LEAN_CONTROL_CONTEXT_MAX_RATIO,
   MAX_CONTEXT_RESULTS,

package/lib/runtime/canonical-snapshot.js

@@ -0,0 +1,110 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { ARTIFACT_TYPES, ArtifactRepository, assertNoSymlinkPath, sha256 } = require("../v2/artifacts");
+const { containsSecret } = require("../security/secrets");
+
+const CONTROL_FILES = Object.freeze(["guardrails.md", "config.md", "project.md", "method.json"]);
+
+function posix(value) {
+  return value.split(path.sep).join("/");
+}
+
+function read(file) {
+  return fs.existsSync(file) && fs.lstatSync(file).isFile() ? fs.readFileSync(file, "utf8") : "";
+}
+
+function artifactSnapshot(scrumDir) {
+  const repository = new ArtifactRepository(scrumDir);
+  const records = {};
+  const hashes = [];
+  const warnings = [];
+  for (const kind of Object.keys(ARTIFACT_TYPES)) {
+    records[kind] = repository.list(kind).map((artifact) => {
+      const relative = posix(path.relative(scrumDir, artifact.file));
+      const content = read(artifact.file);
+      hashes.push(`${relative}\0${sha256(content)}`);
+      if (containsSecret(content)) {
+        warnings.push(`Secret-like content detected in canonical artifact: ${relative}`);
+        return { id: artifact.record ? artifact.record.id : path.basename(artifact.file, ".md"), status: "unsafe", title: "[redacted]" };
+      }
+      return artifact.record ? {
+        id: artifact.record.id,
+        status: artifact.record.status,
+        title: ((artifact.body || "").match(/^# ([^\r\n]+)/m) || [])[1] || artifact.record.id,
+        task: artifact.record.task || null,
+        sprint: artifact.record.sprint || null,
+        feature: artifact.record.feature || null
+      } : { id: path.basename(artifact.file, ".md"), status: "invalid", errors: artifact.errors };
+    });
+  }
+  return { records, hashes, warnings };
+}
+
+function canonicalFingerprint(scrumDir, artifactHashes = null) {
+  const hashes = artifactHashes || artifactSnapshot(scrumDir).hashes;
+  const controls = CONTROL_FILES.map((relative) => {
+    const file = path.join(scrumDir, relative);
+    const exists = fs.existsSync(file) && fs.lstatSync(file).isFile();
+    return `${relative}\0${exists ? sha256(fs.readFileSync(file)) : "missing"}`;
+  });
+  return sha256([...controls, ...hashes].sort().join("\n"));
+}
+
+function statRow(root, file) {
+  assertNoSymlinkPath(root, file);
+  const stat = fs.statSync(file, { bigint: true });
+  if (!stat.isFile()) throw new Error(`Projection source is not a regular file: ${posix(path.relative(root, file))}`);
+  return [
+    posix(path.relative(root, file)),
+    stat.size,
+    stat.mtimeNs,
+    stat.ctimeNs,
+    stat.ino,
+    stat.dev
+  ].join("\0");
+}
+
+function canonicalWatchSnapshot(scrumDir) {
+  const root = path.resolve(scrumDir);
+  const rows = [];
+  let files = 0;
+  for (const relative of CONTROL_FILES) {
+    const file = path.join(root, relative);
+    if (!fs.existsSync(file)) rows.push(`${relative}\0missing`);
+    else {
+      rows.push(statRow(root, file));
+      files++;
+    }
+  }
+  for (const type of Object.values(ARTIFACT_TYPES)) {
+    const directory = path.join(root, type.directory);
+    assertNoSymlinkPath(root, directory);
+    if (!fs.existsSync(directory)) continue;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+      if (!new RegExp(`^${type.prefix}-\\d{3,}\\.md$`).test(entry.name)) continue;
+      const file = path.join(directory, entry.name);
+      if (!entry.isFile()) throw new Error(`Canonical projection source is not a regular file: ${posix(path.relative(root, file))}`);
+      rows.push(statRow(root, file));
+      files++;
+    }
+  }
+  return { fingerprint: sha256(rows.sort().join("\n")), files, rows };
+}
+
+function fileWatchSnapshot(root, files, extraRows = []) {
+  const resolvedRoot = path.resolve(root);
+  const rows = files.map((file) => statRow(resolvedRoot, path.resolve(file)));
+  rows.push(...extraRows.map(String));
+  return { fingerprint: sha256(rows.sort().join("\n")), files: files.length, rows };
+}
+
+module.exports = {
+  CONTROL_FILES,
+  artifactSnapshot,
+  canonicalFingerprint,
+  canonicalWatchSnapshot,
+  fileWatchSnapshot,
+  statRow
+};

package/lib/runtime/context.js

@@ -2,9 +2,10 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
-const { ARTIFACT_TYPES, ArtifactRepository, sha256 } = require("../v2/artifacts");
 const { readProjectModel } = require("../v2/project-store");
 const { containsSecret } = require("../security/secrets");
+const { parseGuardrails } = require("./policy-engine");
+const { artifactSnapshot, canonicalFingerprint } = require("./canonical-snapshot");
 
 const EXCLUDED_ROOT_ENTRIES = new Set([".git", ".scrumrun", "node_modules", "dist", "build", "coverage"]);
 
@@ -40,51 +41,10 @@ function projectScan(projectRoot) {
   return { project: path.basename(projectRoot), entries, package: packageSummary };
 }
 
-function guardrailRecords(content) {
-  const headings = [...content.matchAll(/^## (GR-\d{3,})\s*[-—:]\s*([^\r\n]+)$/gm)];
-  return headings.map((heading, index) => {
-    const end = index + 1 < headings.length ? headings[index + 1].index : content.length;
-    const block = content.slice(heading.index, end);
-    const rule = (block.match(/^Rule:\s*(.+)$/m) || [])[1] || heading[2];
-    const status = ((block.match(/^Status:\s*(.+)$/m) || [])[1] || "active").trim();
-    return { id: heading[1], title: heading[2].trim(), rule: capped(rule.trim(), 500), status };
-  });
-}
-
-function artifactSnapshot(scrumDir) {
-  const repository = new ArtifactRepository(scrumDir);
-  const records = {};
-  const hashes = [];
-  const warnings = [];
-  for (const kind of Object.keys(ARTIFACT_TYPES)) {
-    records[kind] = repository.list(kind).map((artifact) => {
-      const relative = path.relative(scrumDir, artifact.file).split(path.sep).join("/");
-      const content = read(artifact.file);
-      hashes.push(`${relative}\0${sha256(content)}`);
-      if (containsSecret(content)) {
-        warnings.push(`Secret-like content detected in canonical artifact: ${relative}`);
-        return { id: artifact.record ? artifact.record.id : path.basename(artifact.file, ".md"), status: "unsafe", title: "[redacted]" };
-      }
-      return artifact.record ? {
-        id: artifact.record.id,
-        status: artifact.record.status,
-        title: ((artifact.body || "").match(/^# ([^\r\n]+)/m) || [])[1] || artifact.record.id,
-        task: artifact.record.task || null,
-        sprint: artifact.record.sprint || null,
-        feature: artifact.record.feature || null
-      } : { id: path.basename(artifact.file, ".md"), status: "invalid", errors: artifact.errors };
-    });
-  }
-  return { records, hashes, warnings };
-}
+const guardrailRecords = parseGuardrails;
 
 function contextFingerprint(scrumDir, artifactHashes) {
-  const canonical = ["guardrails.md", "config.md", "project.md", "method.json"]
-    .map((relative) => {
-      const content = read(path.join(scrumDir, relative));
-      return `${relative}\0${content ? sha256(content) : "missing"}`;
-    });
-  return sha256([...canonical, ...artifactHashes].sort().join("\n"));
+  return canonicalFingerprint(scrumDir, artifactHashes);
 }
 
 function buildContextPackage(projectRoot, request) {
@@ -138,4 +98,4 @@ function buildContextPackage(projectRoot, request) {
   };
 }
 
-module.exports = { buildContextPackage, contextFingerprint, guardrailRecords, projectScan };
+module.exports = { artifactSnapshot, buildContextPackage, contextFingerprint, guardrailRecords, projectScan };