@inerrata-corporation/errata 2.0.0-dev.40 → 2.0.0-dev.42

package/errata.mjs

@@ -18445,7 +18445,7 @@ var init_triage = __esm({
 // ../../packages/math/src/relevance.ts
 function scoreRelevance(input, weights) {
   const w = { ...DEFAULT_RELEVANCE_WEIGHTS, ...weights };
-  const semantic = input.semantic == null ? 1 : clamp01((input.semantic - w.semanticFloor) / (1 - w.semanticFloor));
+  const semantic = input.semantic != null ? clamp01((input.semantic - w.semanticFloor) / (1 - w.semanticFloor)) : input.semanticUnknown ? clamp01(w.semanticNeutral) : 1;
   const specificity = 1 + w.specificityWeight * clamp01(input.specificity ?? 0);
   const centrality = 1 + w.centralityWeight * Math.tanh((input.centrality ?? 0) / w.centralityScale);
   const quality = 1 + w.qualityWeight * Math.tanh((input.quality ?? 0) / w.qualityScale);
@@ -18462,6 +18462,7 @@ var init_relevance = __esm({
     "use strict";
     DEFAULT_RELEVANCE_WEIGHTS = {
       semanticFloor: 0.5,
+      semanticNeutral: 0.4,
       centralityWeight: 0.5,
       centralityScale: 1,
       qualityWeight: 0.4,
@@ -20054,11 +20055,15 @@ function buildSnapshot(opts) {
     languages: opts.profile.languages.map((name2) => ({ name: name2, node: matchNode(langNodes, name2) })),
     packages: opts.profile.stack.map((name2) => ({ name: name2, node: matchNode(pkgNodes, pkgBase(name2)) }))
   };
+  const causalNudge = recent.length >= 2 && recent.every(
+    (r) => opts.store.outEdges(r.node.id, ["CAUSED_BY"]).length === 0 && opts.store.inEdges(r.node.id, ["CAUSED_BY"]).length === 0
+  );
   return {
     profile: opts.profile,
     profileContext,
     recentProblems: recent,
     recentResolved,
+    ...causalNudge ? { causalNudge } : {},
     motifs,
     reviewCount: opts.reviewCount,
     reviewUiUrl: opts.reviewUiUrl,
@@ -20205,6 +20210,11 @@ function renderSnapshot(s) {
         const surprise = (r.node.cumulativeSurprise ?? 0).toFixed(2);
         lines.push(`  - observed ${hits}\xD7 \xB7 cumulativeSurprise ${surprise}`);
       }
+      if (s.causalNudge) {
+        lines.push(
+          "_None of these problems are causally linked yet \u2014 if one caused another (or your report says so in prose), bind them with `(cause:#slug \u2026)` / `(cause:[handle])`. Trace can only follow edges you declare._"
+        );
+      }
     }
     if (s.recentResolved.length > 0) {
       lines.push("_Recently resolved \u2014 solved here; jumping-off points, not live defects:_");
@@ -20358,12 +20368,17 @@ _${dropped} lower-priority item${dropped === 1 ? "" : "s"} omitted to fit the pa
   }
   return { body: body2, snapshot, dropped };
 }
-var SEARCH_IMPERATIVE_HEADER, SEARCH_IMPERATIVE_BODY, EVICTION_ORDER, DEFAULT_AGENT_CONTEXT_BUDGET;
+var RECALL_FIRST_HEADER, RECALL_FIRST_BODY, RECALL_FIRST_BLOCK, SEARCH_IMPERATIVE_HEADER, SEARCH_IMPERATIVE_BODY, EVICTION_ORDER, DEFAULT_AGENT_CONTEXT_BUDGET;
 var init_render = __esm({
   "../../packages/context-writer/src/render.ts"() {
     "use strict";
     init_src4();
     init_src2();
+    RECALL_FIRST_HEADER = "## errata \u2014 recall before you work";
+    RECALL_FIRST_BODY = "Before investigating any bug or error, your FIRST tool call must be `mcp__errata__errata_search` with a few words describing the problem. This machine's knowledge graph records previously solved problems \u2014 the answer may already be recorded. Read what it returns before touching any files.";
+    RECALL_FIRST_BLOCK = `${RECALL_FIRST_HEADER}
+
+${RECALL_FIRST_BODY}`;
     SEARCH_IMPERATIVE_HEADER = "### \u{1F50E} PRIORS ARE SEEDS \u2014 a sample, not the whole graph";
     SEARCH_IMPERATIVE_BODY = "Everything below is a budgeted, top-of-head slice of a much larger graph. Any prior id below is a live burst seed: `errata.burst` it (or read `.errata/g/burst/<id>`) to pull its wider neighborhood \u2014 causes, fixes, siblings. When a prior is adjacent-but-not-quite, or none fit, that gap is exactly when to search deeper before solving cold: a stuck search is itself a signal that routes help to you.";
     EVICTION_ORDER = [
@@ -21361,7 +21376,7 @@ function loadConfig() {
     saveConfig(cfg);
     return cfg;
   }
-  const raw2 = readFileSync3(p, "utf8");
+  const raw2 = readFileSync3(p, "utf8").replace(/^\uFEFF/, "");
   const parsed = JSON.parse(raw2);
   const base = defaultConfig();
   return {
@@ -24583,6 +24598,18 @@ import { mkdirSync as mkdirSync4, existsSync as existsSync6 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
 import { dirname as dirname3, join as join4 } from "node:path";
 import { createRequire } from "node:module";
+function semanticFloorFor(version2) {
+  if (version2 === EMBEDDING_VERSION) return 0.25;
+  return 0.5;
+}
+function noteHashFallback() {
+  if (warnedHashFallback) return;
+  if (process.env["ERRATA_EMBED_HASH_ONLY"] === "1") return;
+  warnedHashFallback = true;
+  console.warn(
+    `[errata] embedding model unavailable (${lastError?.message ?? "unknown"}) \u2014 falling back to ${EMBEDDING_VERSION} hash vectors; semantic ranking runs at reduced fidelity`
+  );
+}
 function getCacheDir() {
   return process.env["ERRATA_MODEL_CACHE"] ?? join4(homedir2(), ".errata", "models");
 }
@@ -24673,6 +24700,7 @@ async function embedBatchWithModelOrHash(texts) {
     }
   } catch {
   }
+  noteHashFallback();
   return texts.map((t) => {
     const v = embed(t);
     return { vector: v, version: EMBEDDING_VERSION, dim: v.length };
@@ -24687,11 +24715,12 @@ async function embedTextWithModelOrHash(text) {
     const v = await embedTextWithModel(text);
     return { vector: v, version: MODEL_EMBEDDING_VERSION, dim: v.length };
   } catch {
+    noteHashFallback();
     const v = embed(text);
     return { vector: v, version: EMBEDDING_VERSION, dim: v.length };
   }
 }
-var MODEL_NAME, MODEL_EMBEDDING_DIM, MODEL_EMBEDDING_VERSION, pipelinePromise, lastError;
+var MODEL_NAME, MODEL_EMBEDDING_DIM, MODEL_EMBEDDING_VERSION, pipelinePromise, lastError, warnedHashFallback;
 var init_model = __esm({
   "../../packages/embedding/src/model.ts"() {
     "use strict";
@@ -24701,6 +24730,7 @@ var init_model = __esm({
     MODEL_EMBEDDING_VERSION = "minilm-l6-v2";
     pipelinePromise = null;
     lastError = null;
+    warnedHashFallback = false;
   }
 });
 
@@ -25860,11 +25890,11 @@ var init_generalizer = __esm({
 function layerOf(kind) {
   return kind === "Technique" ? "technique" : kind === "AntiPattern" ? "antipattern" : "pattern";
 }
-function motifTitle(members, layer) {
+function motifTitle(members, layer, instanceCount) {
   const top = [...members].sort(
     (a, b) => b.extractionConfidence - a.extractionConfidence
   )[0];
-  return `${layer}: ${top?.description ?? "recurring problem cluster"}`;
+  return `${layer} \xD7${instanceCount} (exemplar): ${top?.description ?? "recurring problem cluster"}`;
 }
 function classifyMotif(store, instances, promoted) {
   if (!promoted || instances.length === 0) return "Pattern";
@@ -25910,7 +25940,9 @@ function promoteMotifs(store, t) {
       const motif = {
         id: motifId,
         label: kind,
-        description: existing?.description ?? motifTitle(members, layerOf(kind)),
+        // Refresh the deterministic title every run (exemplar/count/kind drift),
+        // but never clobber a distilled one — a distillation pass owns it then.
+        description: existing?.attrs["titleDistilled"] === true ? existing.description : motifTitle(members, layerOf(kind), instanceCount),
         extractionConfidence: d.motifConfidence,
         extractionSource: "bko-inferred",
         embedding: existing?.embedding ?? [],
@@ -26121,8 +26153,8 @@ async function embedNodesByLabels(store, labels, opts = {}) {
     durationMs: 0,
     versionsSeen: {}
   };
-  const probe = await embedBatchWithModelOrHash(["probe"]);
-  const currentVersion = probe[0]?.version ?? "unknown";
+  const hashOnly = opts.mode === "hash";
+  const currentVersion = hashOnly ? EMBEDDING_VERSION : (await embedBatchWithModelOrHash(["probe"]))[0]?.version ?? "unknown";
   const todo = [];
   for (const label of labels) {
     for (const node2 of store.findNodesByLabel(label)) {
@@ -26131,6 +26163,10 @@ async function embedNodesByLabels(store, labels, opts = {}) {
       if (existingVersion) {
         report.versionsSeen[existingVersion] = (report.versionsSeen[existingVersion] ?? 0) + 1;
       }
+      if (hashOnly && node2.embedding.length > 0) {
+        report.skippedFresh++;
+        continue;
+      }
       if (!opts.force && existingVersion === currentVersion && node2.embedding.length > 0) {
         report.skippedFresh++;
         continue;
@@ -26144,7 +26180,10 @@ async function embedNodesByLabels(store, labels, opts = {}) {
     const batch = todo.slice(i2, i2 + BATCH_SIZE);
     let results;
     try {
-      results = await embedBatchWithModelOrHash(batch.map((b) => b.text));
+      results = hashOnly ? batch.map((b) => {
+        const v = embed(b.text);
+        return { vector: v, version: EMBEDDING_VERSION, dim: v.length };
+      }) : await embedBatchWithModelOrHash(batch.map((b) => b.text));
     } catch {
       report.failed += batch.length;
       continue;
@@ -26210,12 +26249,15 @@ function nodeFreshness(node2, currentIngestSeq) {
 }
 function scoreCandidate(candidate, ctx = {}, weights) {
   const sameVersion = !ctx.seedEmbeddingVersion || !candidate.attrs["embeddingVersion"] || candidate.attrs["embeddingVersion"] === ctx.seedEmbeddingVersion;
-  const semantic = ctx.seedEmbedding && candidate.embedding.length === ctx.seedEmbedding.length && sameVersion ? cosine(ctx.seedEmbedding, candidate.embedding) : void 0;
+  const comparable = ctx.seedEmbedding != null && candidate.embedding.length === ctx.seedEmbedding.length && sameVersion;
+  const semantic = comparable ? cosine(ctx.seedEmbedding, candidate.embedding) : void 0;
+  const semanticUnknown = ctx.seedEmbedding != null && !comparable;
   const quality = typeof candidate.attrs["effectivenessScore"] === "number" ? candidate.attrs["effectivenessScore"] : void 0;
   const trustTier = candidate.attrs["trustTier"];
   return scoreRelevance(
     {
       ...semantic !== void 0 ? { semantic } : {},
+      ...semanticUnknown ? { semanticUnknown } : {},
       centrality: candidate.pageRank,
       ...quality !== void 0 ? { quality } : {},
       ...ctx.specificity !== void 0 ? { specificity: ctx.specificity } : {},
@@ -26235,7 +26277,11 @@ function rankByRelevance(store, seedId, candidateIds, opts = {}) {
   };
   const nodes = candidateIds.map((id) => store.getNode(id)).filter((n) => n != null);
   const maxPr = Math.max(1e-9, ...nodes.map((n) => n.pageRank));
-  const weights = { centralityScale: maxPr, ...opts.weights };
+  const weights = {
+    centralityScale: maxPr,
+    ...ctx.seedEmbedding ? { semanticFloor: semanticFloorFor(ctx.seedEmbeddingVersion) } : {},
+    ...opts.weights
+  };
   const now = store.currentIngestSeq();
   return nodes.map((node2) => {
     const r = scoreCandidate(node2, { ...ctx, decay: nodeFreshness(node2, now) }, weights);
@@ -26270,7 +26316,11 @@ function localBurst(store, seedId, opts = {}) {
   const gated = seed.embedding.length > 0;
   const nodes = [...hopOf.entries()].map(([id, hops]) => ({ node: store.getNode(id), hops })).filter((x) => x.node != null);
   const maxPr = Math.max(1e-9, ...nodes.map((x) => x.node.pageRank));
-  const weights = { centralityScale: maxPr, ...opts.weights };
+  const weights = {
+    centralityScale: maxPr,
+    ...gated ? { semanticFloor: semanticFloorFor(ctxSeed.seedEmbeddingVersion) } : {},
+    ...opts.weights
+  };
   const now = store.currentIngestSeq();
   return nodes.map(({ node: node2, hops }) => {
     const r = scoreCandidate(node2, { ...ctxSeed, hops, decay: nodeFreshness(node2, now) }, weights);
@@ -36972,7 +37022,7 @@ function resolvePath(rawPath) {
   const rest2 = segs.slice(1);
   if (verb === "index" || verb === "README" || verb === "help") return { kind: "index" };
   if (verb === "search") {
-    const query = rest2.join(" ").trim();
+    const query = rest2.join(" ").replace(/[-_]+/g, " ").trim();
     if (!query) return null;
     return { kind: "tool", tool: "errata.search", args: { query } };
   }
@@ -42504,7 +42554,7 @@ function startLoopLagMonitor(thresholdMs = 1e3) {
 }
 
 // src/engine.ts
-var DAEMON_VERSION = true ? "2.0.0-dev.40" : "2.0.0-alpha.0";
+var DAEMON_VERSION = true ? "2.0.0-dev.42" : "2.0.0-alpha.0";
 var IGNORED_PATH = /[\\/](?:\.git|node_modules|\.errata|\.claude|\.codex|\.cursor|\.turbo|\.next|dist|coverage|test-results|playwright-report|__pycache__)(?:[\\/]|$)/;
 var IGNORED_NOISE = /castalia\.db|eventlog\.sqlite|turn-cursors/;
 var GIT_OP_MUTE_MS = 4e3;
@@ -43532,6 +43582,16 @@ function createWorkspaceEngine(opts) {
       telemetry.count("problems_resolved", gen.problemsResolved);
       telemetry.count("reviews_triggered", gen.reviewsTriggered);
       telemetry.count("signals_credited", report.signalsCredited);
+      if (gen.problemsWritten > 0) {
+        try {
+          const inline = await embedSemanticNodes(store, { mode: "hash" });
+          if (inline.embedded > 0) {
+            console.log(`[errata] inline-embedded ${inline.embedded} fresh semantic node(s) (hash)`);
+          }
+        } catch (err2) {
+          console.warn("[errata] inline semantic embed failed:", err2 instanceof Error ? err2.message : err2);
+        }
+      }
       const graphChanged = gen.problemsWritten + gen.problemsResolved + gen.problemsReinforced + gen.reviewsTriggered + report.signalsCredited > 0;
       if (!opts.skipContextWriter && (graphChanged || contextDirty)) {
         refreshContextNow();
@@ -47033,6 +47093,7 @@ async function installClaudeHooks(port) {
     }
   }
   const matcher = "Read|Edit|Write|Grep|Glob|NotebookEdit|Bash";
+  const postMatcher = `${matcher}|ToolSearch|mcp__errata__.*`;
   const preCmd = `${hookCurlCommand(port)} ${ERRATA_TAG}`;
   const postCmd = `${hookRelayCommand(port, "/api/hook")} ${ERRATA_TAG}`;
   settings.hooks ??= {};
@@ -47041,13 +47102,13 @@ async function installClaudeHooks(port) {
       if (list[i2].hooks.some((h) => h.command.includes(ERRATA_TAG))) list.splice(i2, 1);
     }
   };
-  for (const [event, command] of [
-    ["PreToolUse", preCmd],
-    ["PostToolUse", postCmd]
+  for (const [event, command, eventMatcher] of [
+    ["PreToolUse", preCmd, matcher],
+    ["PostToolUse", postCmd, postMatcher]
   ]) {
     const list = settings.hooks[event] ??= [];
     dropErrata(list);
-    list.push({ matcher, hooks: [{ type: "command", command }] });
+    list.push({ matcher: eventMatcher, hooks: [{ type: "command", command }] });
   }
   const turnCmd = `${hookCurlCommand(port, "/api/turn")} ${ERRATA_TAG}`;
   for (const event of ["Stop", "SubagentStop"]) {
@@ -47074,6 +47135,15 @@ async function installClaudeHooks(port) {
   writeFileSync16(file2, JSON.stringify(settings, null, 2) + "\n", "utf8");
   console.log(`installed Claude Code hooks \u2192 ${file2}`);
   await installClaudeMcpConfig();
+  const claudeMd = join24(ROOT, "CLAUDE.md");
+  const recall = writeManagedBlock(claudeMd, { body: RECALL_FIRST_BLOCK });
+  if (recall.kind === "collision") {
+    console.warn(
+      `  \u26A0\uFE0F  CLAUDE.md errata block was hand-edited \u2014 leaving it alone (expected ${recall.expectedHash}, found ${recall.actualHash})`
+    );
+  } else {
+    console.log(`installed recall-first block \u2192 ${claudeMd}`);
+  }
   console.log(`  endpoint: http://127.0.0.1:${port}/api/hook`);
 }
 async function installClaudeMcpConfig() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inerrata-corporation/errata",
-  "version": "2.0.0-dev.40",
+  "version": "2.0.0-dev.42",
   "description": "errata - local-first observation engine for AI coding agents",
   "type": "module",
   "bin": {

package/pass-worker.mjs

@@ -25393,11 +25393,11 @@ var MEMBER_LABELS = ["Problem", "RootCause", "Solution"];
 function layerOf(kind) {
   return kind === "Technique" ? "technique" : kind === "AntiPattern" ? "antipattern" : "pattern";
 }
-function motifTitle(members, layer) {
+function motifTitle(members, layer, instanceCount) {
   const top = [...members].sort(
     (a, b) => b.extractionConfidence - a.extractionConfidence
   )[0];
-  return `${layer}: ${top?.description ?? "recurring problem cluster"}`;
+  return `${layer} \xD7${instanceCount} (exemplar): ${top?.description ?? "recurring problem cluster"}`;
 }
 function classifyMotif(store2, instances, promoted) {
   if (!promoted || instances.length === 0) return "Pattern";
@@ -25443,7 +25443,9 @@ function promoteMotifs(store2, t) {
       const motif = {
         id: motifId,
         label: kind,
-        description: existing?.description ?? motifTitle(members, layerOf(kind)),
+        // Refresh the deterministic title every run (exemplar/count/kind drift),
+        // but never clobber a distilled one — a distillation pass owns it then.
+        description: existing?.attrs["titleDistilled"] === true ? existing.description : motifTitle(members, layerOf(kind), instanceCount),
         extractionConfidence: d.motifConfidence,
         extractionSource: "bko-inferred",
         embedding: existing?.embedding ?? [],
@@ -25681,11 +25683,15 @@ function buildSnapshot(opts) {
     languages: opts.profile.languages.map((name2) => ({ name: name2, node: matchNode(langNodes, name2) })),
     packages: opts.profile.stack.map((name2) => ({ name: name2, node: matchNode(pkgNodes, pkgBase(name2)) }))
   };
+  const causalNudge = recent.length >= 2 && recent.every(
+    (r) => opts.store.outEdges(r.node.id, ["CAUSED_BY"]).length === 0 && opts.store.inEdges(r.node.id, ["CAUSED_BY"]).length === 0
+  );
   return {
     profile: opts.profile,
     profileContext,
     recentProblems: recent,
     recentResolved,
+    ...causalNudge ? { causalNudge } : {},
     motifs,
     reviewCount: opts.reviewCount,
     reviewUiUrl: opts.reviewUiUrl,
@@ -25754,6 +25760,11 @@ function fileOf(store2, nodeId) {
   }
   return null;
 }
+var RECALL_FIRST_HEADER = "## errata \u2014 recall before you work";
+var RECALL_FIRST_BODY = "Before investigating any bug or error, your FIRST tool call must be `mcp__errata__errata_search` with a few words describing the problem. This machine's knowledge graph records previously solved problems \u2014 the answer may already be recorded. Read what it returns before touching any files.";
+var RECALL_FIRST_BLOCK = `${RECALL_FIRST_HEADER}
+
+${RECALL_FIRST_BODY}`;
 
 // ../../packages/context-writer/src/select-durable-memory.ts
 init_src2();