@jeffober/thatch 0.1.5 → 0.1.8

package/src/sideband.ts

@@ -0,0 +1,207 @@
+import { createHash } from "node:crypto";
+import { unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createServer, connect, type Server, type Socket } from "node:net";
+import type { ThatchDB } from "./db";
+import type { EmbeddingModel } from "./embeddings";
+
+/**
+ * Deterministic socket path from the DB path. Both the MCP server and hook
+ * processes resolve the same DB path (from THATCH_DB_PATH or the default
+ * under XDG_CONFIG_HOME), so they independently arrive at the same socket
+ * path without any out-of-band coordination.
+ */
+export function sidebandSocketPath(dbPath: string): string {
+  const hash = createHash("sha256").update(dbPath).digest("hex").slice(0, 16);
+  return join(tmpdir(), `thatch-${hash}.sock`);
+}
+
+export interface SidebandMatch {
+  label: string;
+  score: number;
+  store: string;
+}
+
+interface MatchRequest {
+  method: "match";
+  text: string;
+  stores: string[];
+  threshold: number;
+  limit: number;
+}
+
+interface MatchResponse {
+  ok: boolean;
+  matches?: SidebandMatch[];
+  error?: string;
+}
+
+/**
+ * Serves embedding + semantic search requests over a Unix domain socket.
+ * The MCP server (long-lived, warm model) runs this so that one-shot hook
+ * processes can ask "does this prompt match any memories?" without loading
+ * the ~34 MB model themselves.
+ *
+ * The protocol is newline-delimited JSON: one request per connection, one
+ * response per connection. Requests are `{"method":"match","text":"...",
+ * "stores":[...],"threshold":N,"limit":N}`. Responses are `{"ok":true,
+ * "matches":[...]}` or `{"ok":false,"error":"..."}`.
+ */
+export class SidebandServer {
+  #server: Server | null = null;
+  #path: string;
+  #model: EmbeddingModel;
+  #db: ThatchDB;
+
+  constructor(path: string, model: EmbeddingModel, db: ThatchDB) {
+    this.#path = path;
+    this.#model = model;
+    this.#db = db;
+  }
+
+  /** Opens the socket. Cleans up any stale socket file from a crashed server. */
+  start(): void {
+    try {
+      unlinkSync(this.#path);
+    } catch {
+      // No stale socket — expected on first run.
+    }
+
+    this.#server = createServer((socket) => {
+      this.#handleConnection(socket);
+    });
+
+    this.#server.listen(this.#path);
+  }
+
+  /** Closes the socket and removes the socket file. */
+  stop(): void {
+    this.#server?.close();
+    this.#server = null;
+    try {
+      unlinkSync(this.#path);
+    } catch {
+      // Already gone.
+    }
+  }
+
+  get path(): string {
+    return this.#path;
+  }
+
+  #handleConnection(socket: Socket): void {
+    let buf = "";
+    socket.on("data", (chunk: Buffer) => {
+      buf += chunk.toString();
+      const nl = buf.indexOf("\n");
+      if (nl < 0) return;
+
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      this.#handleRequest(line, socket);
+    });
+    socket.on("error", () => {
+      // Client disconnected abruptly — nothing to do.
+    });
+  }
+
+  async #handleRequest(line: string, socket: Socket): Promise<void> {
+    let req: MatchRequest;
+    try {
+      req = JSON.parse(line);
+    } catch {
+      this.#respond(socket, { ok: false, error: "Invalid JSON" });
+      return;
+    }
+
+    if (req.method !== "match") {
+      this.#respond(socket, { ok: false, error: `Unknown method: ${req.method}` });
+      return;
+    }
+
+    try {
+      const embedding = await this.#model.queryEmbed(req.text);
+      const results = this.#db.search(req.stores, embedding, { limit: req.limit });
+      const matches: SidebandMatch[] = results
+        .filter((r) => r._score >= req.threshold)
+        .map((r) => ({
+          label: r.label,
+          score: Math.round(r._score * 1000) / 1000,
+          store: r.store,
+        }));
+      this.#respond(socket, { ok: true, matches });
+    } catch (err: any) {
+      this.#respond(socket, { ok: false, error: String(err?.message ?? err) });
+    }
+  }
+
+  #respond(socket: Socket, res: MatchResponse): void {
+    if (!socket.destroyed) {
+      socket.write(JSON.stringify(res) + "\n");
+    }
+  }
+}
+
+/**
+ * Connect to the sideband server and request semantic matches for a prompt.
+ * Returns null on any failure (server not running, stale socket, timeout) —
+ * callers must treat null as "skip the recall nudge" and fall back gracefully.
+ */
+export function sidebandMatch(
+  socketPath: string,
+  text: string,
+  stores: string[],
+  threshold: number,
+  limit: number,
+  timeoutMs = 2000,
+): Promise<SidebandMatch[] | null> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (val: SidebandMatch[] | null) => {
+      if (settled) return;
+      settled = true;
+      resolve(val);
+    };
+
+    const socket = connect(socketPath);
+    const req = JSON.stringify({ method: "match", text, stores, threshold, limit }) + "\n";
+    let buf = "";
+
+    const timer = setTimeout(() => {
+      socket.destroy();
+      done(null);
+    }, timeoutMs);
+
+    socket.on("error", () => {
+      clearTimeout(timer);
+      // Stale socket file left by a crashed server — clean it up so the next
+      // connection attempt doesn't hit ECONNREFUSED again.
+      try {
+        unlinkSync(socketPath);
+      } catch {
+        // Already gone or never existed.
+      }
+      done(null);
+    });
+
+    socket.on("connect", () => {
+      socket.write(req);
+    });
+
+    socket.on("data", (chunk: Buffer) => {
+      buf += chunk.toString();
+      const nl = buf.indexOf("\n");
+      if (nl < 0) return;
+
+      clearTimeout(timer);
+      try {
+        const res = JSON.parse(buf.slice(0, nl)) as MatchResponse;
+        done(res.ok ? (res.matches ?? []) : null);
+      } catch {
+        done(null);
+      }
+      socket.destroy();
+    });
+  });
+}

package/src/skills.ts

@@ -72,6 +72,8 @@ Identify the application's runtime model early: Is it a CLI tool (process exits
 ## Reachability gate
 For every potential finding, you MUST describe a concrete scenario where a real user triggers the problem through normal usage. "The code allows this" is not sufficient — show how a user actually encounters it given the application's runtime model. If the only trigger requires conditions that cannot occur in actual usage, it is not a finding.
 
+Before claiming a value can hold a problematic state (NULL, orphaned, out-of-range, wrong-type), read the artifact that governs that state: the column definition, type declaration, FK/NOT NULL constraint, validation, or guard. Quote it in your finding. If a schema constraint, type, or guard makes the state unreachable, it is not a finding. "The join could drop rows" requires proving a droppable row can exist — cite the constraint that permits it.
+
 ## Intent verification
 Before flagging behavior as a bug, verify intent:
 1. **Trace callers.** Read every caller of the cited code. The behavior may be intentional given how the feature is actually used.
@@ -453,11 +455,13 @@ For each, walk through actual function calls, tracking data shape at each step.
 
 ### 4. Prove the producer chain
 For every finding about invalid state, missing data, shape mismatches, or cross-module behavior, trace the full causal chain:
-- Who produces the state or value?
+- Who produces the state or value? Cite the file:line that writes the problematic value.
 - Which functions transform it?
 - Which consumer or branch fails?
 - Which real entrypoint/workflow exercises that chain?
 
+The producer must be a specific file:line in current code that writes the problematic value. "Source deletion could orphan this" is not a producer; the file:line where a row is written with a dangling reference is. If no such write site exists in the codebase, the state is unreachable — do not report it.
+
 If you cannot identify a real producer in current code, or the only way to trigger the issue is by manually fabricating invalid state/data, do not report it as a real finding.
 
 ### 5. Identify the implicit FSM
@@ -490,6 +494,10 @@ For each new module or significant change:
 - **DEAD_PATH**: Code path exists but cannot be reached given current callers/preconditions
 
 For each finding, cite both sides of any contract (file:line for caller and callee).
+
+## Worked non-finding (negative example)
+
+Example non-finding: "INNER JOIN on source_id silently drops rows whose source was deleted." Before reporting, read the FK: if source_id is NOT NULL with a foreign key and deletion cascades to children, an orphaned row cannot exist and the drop is unreachable. Reporting it anyway is the canonical reachability failure. The fix is not to switch to LEFT JOIN (which would add dead code for an impossible case) but to verify the constraint that governs the state.
 `;
 
 const REVIEW_NO_SLOP = `---
@@ -649,25 +657,35 @@ For each finding from the specialists:
 
 3. **Determine provenance.** Is the finding a new issue introduced by this change, or a pre-existing problem? Note pre-existing bugs separately.
 
-4. **Check runtime model applicability.** Can the finding realistically manifest in normal usage given the application's runtime model? A finding that requires conditions impossible in the actual runtime context is not a real bug (e.g., state accumulation in a short-lived process, concurrency in single-threaded code).
+**Finding type determines which steps apply next.** Steps 4-6 apply to behavioral findings (from acceptance, state-flow). Mechanical findings (from pedantic, no-slop, breadcrumbs — docs, naming, style, comments, prose) skip steps 4-6 and use the mechanical verification criteria in step 4m instead.
+
+4. **Check runtime model applicability (behavioral findings only).** Can the finding realistically manifest in normal usage given the application's runtime model? A finding that requires conditions impossible in the actual runtime context is not a real bug (e.g., state accumulation in a short-lived process, concurrency in single-threaded code).
 
-5. **Prove the causal chain** for any finding about state, data shape, cross-module contracts, or behavior:
+5. **Prove the causal chain (behavioral findings only)** for any finding about state, data shape, cross-module contracts, or behavior:
    - Identify the authoritative producer or source of the state/data.
    - Identify the transforms between producer and consumer.
    - Identify the consumer or branch where failure occurs.
    - Identify the real entrypoint/workflow that exercises this chain.
    If the only way to trigger the issue is by manually fabricating invalid data/state or bypassing the real producers/guards, reject the finding. If the citation is real but you cannot prove the producer chain, classify as UNVERIFIABLE rather than CONFIRMED.
 
-6. **Verify intent.** If the specialist flagged behavior as a bug but the code appears to work as designed, check whether the behavior is intentional:
+5a. **Verify governing constraints for data-shape findings.** For findings claiming a field can be NULL/missing/orphaned/malformed, locate and read the field's definition (schema migration, model, type declaration). If a NOT NULL, FK, enum, or type constraint forecloses the claimed state, REJECT and cite the constraint. Do not classify such a finding CONFIRMED without having read the governing definition.
+
+6. **Verify intent (behavioral findings only).** If the specialist flagged behavior as a bug but the code appears to work as designed, check whether the behavior is intentional:
    - Read the callers of the cited code to see if the pattern makes sense in context.
    - Check git log or git blame on the cited file for commit messages explaining the decision.
    - Use thatch_memory_recall to search for documented rationale.
    If the behavior is intentional or an accepted limitation, reject the finding.
 
+4m. **Mechanical verification (pedantic, no-slop, breadcrumbs, docs, naming, style, comments).** For mechanical findings, verification means:
+   - The cited text exists at the cited location (already confirmed in step 2).
+   - The finding is branch-introduced or newly made relevant by the change. Pre-existing issues go in the pre-existing appendix, not rejected.
+   - The cited text violates the stated guideline, specialist taxonomy, or project norm. Identify the source of truth: the specific guideline, convention, or writing norm being violated.
+   Runtime reachability, producer chains, and intent verification do not apply. A mechanical finding is not a "bug" and does not need a "trigger scenario."
+
 7. **Classify:**
-   - **CONFIRMED**: The cited code matches, the claim is accurate, the bug is reachable through realistic usage, you proved the workflow/producer chain where applicable, and the behavior is not intentional.
-   - **REJECTED**: The citation is wrong, the claim is inaccurate, the bug cannot manifest in the actual runtime context, or the behavior is an intentional design decision (explain why briefly). Reject findings that rely on manually seeded invalid state/data with no real producer path.
-   - **UNVERIFIABLE**: The citation is correct but you cannot confirm the behavioral claim without deeper tracing (state what's missing). This is the default for plausible claims that lack a proven trigger path, producer chain, or authoritative source of truth.
+   - **CONFIRMED**: For behavioral findings: the cited code matches, the claim is accurate, the bug is reachable through realistic usage, you proved the workflow/producer chain where applicable, the behavior is not intentional, and for data-shape findings you read and cited the governing constraint confirming the claimed state is reachable. For mechanical findings: the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy.
+   - **REJECTED**: For behavioral findings: the citation is wrong, the claim is inaccurate, the bug cannot manifest in the actual runtime context, the behavior is an intentional design decision (explain why briefly), or a governing constraint (NOT NULL, FK, type, guard) forecloses the claimed state. Reject findings that rely on manually seeded invalid state/data with no real producer path. For mechanical findings: the cited text does not exist, does not violate the stated guideline, is unchanged legacy outside the touched scope, or the finding duplicates another confirmed finding.
+   - **UNVERIFIABLE**: The citation is correct but you cannot confirm the claim without deeper tracing. This is the default for plausible behavioral claims that lack a proven trigger path, producer chain, or authoritative source of truth. A data-shape finding that lacks the governing-constraint citation is UNVERIFIABLE, not CONFIRMED. Mechanical findings should rarely be UNVERIFIABLE — if the text exists and violates the guideline, it is CONFIRMED.
 
 ## Deduplication
 
@@ -683,10 +701,14 @@ Assign final severity based on YOUR verification:
 - **MEDIUM**: Edge cases, UX friction, or issues where the citation is correct but the impact is limited or requires unusual conditions.
 - **LOW**: Mechanical issues (stale docs, guideline violations, naming) that don't affect correctness.
 
+A data-shape or reachability finding that lacks the governing-constraint citation (the schema, type, or guard definition you read to confirm the state is reachable) is capped at UNVERIFIABLE. It cannot be classified CONFIRMED or assigned a severity. This removes the path where a plausible-but-unchecked claim lands at MEDIUM.
+
 ## Report format
 
 You MUST produce the full report structure below. Do not simplify or omit sections. Every confirmed finding must include all numbered fields. If a section has no entries, write "None" — do not skip the section.
 
+Confirmed LOW findings are mandatory. Do not summarize them away or omit them for being non-functional. Pedantic, no-slop, breadcrumbs, docs, naming, style, and comment findings are first-class review findings when confirmed. Group them under LOW, but include every one.
+
 ### Scope
 - Branch/range reviewed
 - Design context (if provided)
@@ -858,13 +880,15 @@ For the integration review unit (5+ points), dispatch a sub-agent focused on:
 
 After all sub-agents complete, load the thatch-review-synthesizer skill to verify findings, deduplicate across specialists, classify (CONFIRMED/REJECTED/UNVERIFIABLE), and produce the final severity-grouped report.
 
+Confirmed LOW findings are mandatory in the final report, including mechanical findings (pedantic, no-slop, breadcrumbs, docs, naming, style, comments). Do not omit them for being non-functional.
+
 Alternatively, perform the synthesis yourself:
 1. Read each finding's cited location to verify evidence accuracy.
 2. Deduplicate findings flagged by multiple specialists.
 3. Group findings by root cause where multiple findings stem from the same issue.
-4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE based on citation verification, reachability, and intent verification.
+4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE. For behavioral findings, apply citation verification, reachability, and intent verification. For mechanical findings, verify the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy.
 5. Calibrate severity (BLOCKING > HIGH > MEDIUM > LOW) based on your verification.
-6. Produce a final report grouped by severity, with coverage gaps noted.
+6. Produce a final report grouped by severity, with coverage gaps noted. Include every confirmed LOW finding.
 
 ## Specialist briefing template
 
@@ -876,7 +900,7 @@ When dispatching each sub-agent, include in the prompt:
 - Any design context or specific concerns
 - Explicit scope boundaries ("your scope is X; do NOT review Y")
 - Instruction to produce markdown findings with: severity, category, file:line, finding, evidence, trigger scenario, reachability, source of truth, producer chain, provenance
-- Instruction to apply the reachability gate and intent verification before reporting
+- Instruction to apply the reachability gate (including reading and citing governing constraints for data-state claims) and intent verification before reporting
 `;
 
 // ---------------------------------------------------------------------------