@inerrata-corporation/errata 2.0.2-dev.297 → 2.0.2-dev.305

package/errata.mjs

@@ -28148,6 +28148,19 @@ function summariesByBodyHash(cache) {
   }
   return m;
 }
+function buildDocIndex(store) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const c of store.findNodesByLabel("Comment")) {
+    const name2 = c.attrs["attachedTo"];
+    const kind = c.attrs["kind"];
+    if (typeof name2 !== "string" || !name2) continue;
+    if (typeof kind !== "string" || !DOC_COMMENT_KINDS.has(kind)) continue;
+    const text = typeof c.attrs["text"] === "string" ? c.attrs["text"] : c.description;
+    if (!text?.trim()) continue;
+    if (!byName.has(name2)) byName.set(name2, text.trim().slice(0, MAX_DOC_CHARS));
+  }
+  return byName;
+}
 function parseSummaryJson(text, expected) {
   const start2 = text.indexOf("[");
   const end = text.lastIndexOf("]");
@@ -28173,7 +28186,8 @@ function haikuIntentSummarizer(apiKey) {
       const listing = symbols.map(
         (s, i2) => `### ${i2 + 1}. kind: ${s.kind}
 name: ${s.name}
-${s.snippet ? `\`\`\`
+` + (s.doc ? `doc: ${s.doc}
+` : "") + `${s.snippet ? `\`\`\`
 ${s.snippet}
 \`\`\`` : "(no source available \u2014 describe from the name)"}`
       ).join("\n\n");
@@ -28193,10 +28207,20 @@ SYMBOLS:
 ${listing}` }]
         })
       });
-      if (!resp.ok) return symbols.map(() => null);
+      if (!resp.ok) {
+        const detail = await resp.text().catch(() => "");
+        console.warn(
+          `[errata] symbol summaries: API ${resp.status} \u2014 sweep produced nothing this round. ${detail.slice(0, 200)}`
+        );
+        return symbols.map(() => null);
+      }
       const json2 = await resp.json();
       return parseSummaryJson(json2.content?.find((c) => c.type === "text")?.text ?? "", symbols.length);
-    } catch {
+    } catch (err2) {
+      console.warn(
+        "[errata] symbol summaries: transport failed \u2014 sweep produced nothing this round:",
+        err2 instanceof Error ? err2.message : err2
+      );
       return symbols.map(() => null);
     }
   };
@@ -28227,6 +28251,7 @@ async function runSymbolSummarySweep(store, workspaceRoot, configDir, summarizer
   const cache = loadSymbolSummaryCache(configDir);
   const candidates = [];
   const seen = /* @__PURE__ */ new Set();
+  const docs = buildDocIndex(store);
   for (const [label, kind] of SUMMARY_LABELS) {
     for (const n of store.findNodesByLabel(label)) {
       const bodyHash = n.attrs["bodyHash"];
@@ -28236,7 +28261,15 @@ async function runSymbolSummarySweep(store, workspaceRoot, configDir, summarizer
       if (!name2 || !isDistinctiveIdentifier(name2)) continue;
       seen.add(bodyHash);
       const snippet = readSnippet(workspaceRoot, n.attrs);
-      candidates.push({ bodyHash, name: name2, kind, ...snippet ? { snippet } : {} });
+      const qname = typeof n.attrs["qname"] === "string" ? n.attrs["qname"] : void 0;
+      const doc = docs.get(name2) ?? (qname ? docs.get(qname) : void 0);
+      candidates.push({
+        bodyHash,
+        name: name2,
+        kind,
+        ...snippet ? { snippet } : {},
+        ...doc ? { doc } : {}
+      });
     }
   }
   const todo = candidates.slice(0, maxSymbols);
@@ -28266,7 +28299,7 @@ async function runSymbolSummarySweep(store, workspaceRoot, configDir, summarizer
   }
   return { generated, rejected, remaining };
 }
-var SUMMARY_LABELS, MAX_SNIPPET_CHARS, DEFAULT_MAX_SYMBOLS_PER_SWEEP, DEFAULT_BATCH_SIZE, SUMMARY_MODEL, SUMMARY_PROMPT;
+var SUMMARY_LABELS, MAX_SNIPPET_CHARS, DEFAULT_MAX_SYMBOLS_PER_SWEEP, DEFAULT_BATCH_SIZE, DOC_COMMENT_KINDS, MAX_DOC_CHARS, SUMMARY_MODEL, SUMMARY_PROMPT;
 var init_symbol_summaries = __esm({
   "src/symbol-summaries.ts"() {
     "use strict";
@@ -28280,10 +28313,13 @@ var init_symbol_summaries = __esm({
     MAX_SNIPPET_CHARS = 1500;
     DEFAULT_MAX_SYMBOLS_PER_SWEEP = 64;
     DEFAULT_BATCH_SIZE = 16;
+    DOC_COMMENT_KINDS = /* @__PURE__ */ new Set(["docstring", "explanation"]);
+    MAX_DOC_CHARS = 600;
     SUMMARY_MODEL = "claude-haiku-4-5-20251001";
     SUMMARY_PROMPT = `For each code symbol below, write ONE short English phrase stating its intent/role, shaped like "a <kind> that <does what>" (e.g. "a function that binds the server's listen port").
+Some symbols include a "doc:" line \u2014 the author's own description of what it is for. When present TRUST IT as the primary source of intent and translate it into the required shape; the code is secondary evidence. Carry the SPECIFIC job the symbol does, not the category it belongs to: "a function that releases a pooled connection on every exit path including cancellation" is useful; "a function that handles cleanup" is not.
 HARD RULES \u2014 a violating phrase is discarded:
-- NEVER include any identifier, symbol name, variable, type name, file path, or module name from the code \u2014 describe meaning in plain English words only.
+- NEVER include any identifier, symbol name, variable, type name, file path, or module name from the code or the doc \u2014 describe meaning in plain English words only.
 - NEVER include quoted strings, literals, numbers copied from the code, or code syntax.
 - One phrase per symbol, under 200 characters, lowercase start, no trailing period.
 Output a JSON array of strings, one per symbol in the SAME ORDER (use null for a symbol you cannot describe). Output JSON only, no prose.`;
@@ -52635,6 +52671,14 @@ function enqueueWitnesses(queue, fresh, now) {
 function pendingFor(queue, channel) {
   return queue.filter((w) => w.channel === channel);
 }
+function partitionReplayable(queue, channel, isShipped) {
+  const replay2 = [];
+  const waiting = [];
+  for (const w of pendingFor(queue, channel)) {
+    (isShipped(w.nodeId) ? replay2 : waiting).push(w);
+  }
+  return { replay: replay2, waiting };
+}
 function retireWitnesses(queue, channel, settledKeys) {
   return queue.filter((w) => !(w.channel === channel && settledKeys.has(w.witnessKey)));
 }
@@ -52894,7 +52938,7 @@ function startLoopLagMonitor(thresholdMs = 1e3) {
 }
 
 // src/engine.ts
-var DAEMON_VERSION = true ? "2.0.2-dev.297" : "2.0.0-alpha.0";
+var DAEMON_VERSION = true ? "2.0.2-dev.305" : "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;
@@ -53837,8 +53881,20 @@ function createWorkspaceEngine(opts) {
         const citingSession = sessionOriginKey(sessionId);
         const mintedHere = (nodeId) => store.getNode(nodeId)?.attrs["sources"]?.[0] === sessionId;
         const sendWitnesses = async (channel, fresh, send) => {
-          const queued = pendingFor(witnessQueue, channel);
-          if (fresh.length === 0 && queued.length === 0) return;
+          const { replay: queued, waiting } = partitionReplayable(
+            witnessQueue,
+            channel,
+            (nodeId) => {
+              const n = store.getNode(nodeId);
+              return !n || n.attrs["contributedAtSeq"] != null;
+            }
+          );
+          if (fresh.length === 0 && queued.length === 0) {
+            if (waiting.length > 0) {
+              console.log(`[errata] ${channel}: ${waiting.length} parked awaiting node drain`);
+            }
+            return;
+          }
           const groups = /* @__PURE__ */ new Map();
           for (const q of queued) {
             const g = groups.get(q.sessionKey) ?? [];
@@ -53883,7 +53939,7 @@ function createWorkspaceEngine(opts) {
           witnessQueue = enqueueWitnesses(witnessQueue, stillUnmatched, Date.now());
           saveWitnessQueue(witnessQueuePath(paths.configDir), witnessQueue);
           console.log(
-            `[errata] ${channel}: ${formatDisposition({ recorded, unmatched, duplicate, selfGated })}` + (queued.length > 0 ? ` (incl. ${queued.length} replayed)` : "")
+            `[errata] ${channel}: ${formatDisposition({ recorded, unmatched, duplicate, selfGated })}` + (queued.length > 0 ? ` (incl. ${queued.length} replayed)` : "") + (waiting.length > 0 ? ` (${waiting.length} awaiting drain)` : "")
           );
           appendWitnessLedger(paths.configDir, {
             ts: Date.now(),
@@ -53892,7 +53948,8 @@ function createWorkspaceEngine(opts) {
             unmatched,
             duplicate,
             selfGated,
-            parked: pendingFor(witnessQueue, channel).length
+            parked: pendingFor(witnessQueue, channel).length,
+            awaitingDrain: waiting.length
           });
         };
         if (typeof cloud.reportContradictions === "function") {

package/package.json

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