wicked-brain 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "description": "Digital brain as skills for AI coding CLIs — no vector DB, no embeddings, no infrastructure",
   "keywords": [
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "better-sqlite3": "^12.0.0",
-    "wicked-bus": "^1.1.0"
+    "wicked-bus": "^2.0.0"
   },
   "files": [
     "install.mjs",

package/server/bin/wicked-brain-server.mjs

@@ -6,7 +6,13 @@ import { argv, pid, exit } from "node:process";
 import { FileWatcher } from "../lib/file-watcher.mjs";
 import { SqliteSearch } from "../lib/sqlite-search.mjs";
 import { LspClient } from "../lib/lsp-client.mjs";
-import { emitEvent, waitForBus } from "../lib/bus.mjs";
+import {
+  emitEvent,
+  waitForBus,
+  listBusDeadLetters,
+  replayBusDeadLetter,
+  dropBusDeadLetter,
+} from "../lib/bus.mjs";
 import { startMemorySubscriber } from "../lib/memory-subscriber.mjs";
 import { renderViewerHtml } from "../lib/viewer-page.mjs";
 import { walkBrainContent, purgeBrainContent } from "../lib/brain-walker.mjs";
@@ -201,6 +207,17 @@ const actions = {
     emitEvent("wicked.link.confirmed", "brain.link", {
       source_id: p.source_id, target_path: p.target_path, verdict: p.verdict, brain_id: brainId,
     });
+    // Surface contradictions on a dedicated event stream so downstream
+    // consumers don't have to filter by verdict on the generic confirmed event.
+    if (p.verdict === "contradict") {
+      emitEvent("wicked.link.contradicted", "brain.link", {
+        source_id: p.source_id,
+        target_path: p.target_path,
+        confidence: result?.confidence ?? null,
+        evidence_count: result?.evidence_count ?? null,
+        brain_id: brainId,
+      });
+    }
     return result;
   },
   link_health: () => db.linkHealth(),
@@ -259,6 +276,21 @@ const actions = {
         : { skipped: true },
     };
   },
+  // DLQ inspection — read-only listing, scoped to wicked-brain's plugin.
+  // Surfaces dead-lettered fact events from the auto-memorize subscriber
+  // so operators can decide whether to replay or drop them.
+  dlq_list: (p = {}) => ({
+    dead_letters: listBusDeadLetters({
+      cursor_id: p.cursor_id,
+      limit: p.limit,
+    }),
+  }),
+  // Mark one DLQ entry for replay. The managed subscriber drains pending
+  // replays before each poll cycle — success here means queued, not delivered.
+  // dl_id alone identifies the row (it's the bus's primary key).
+  dlq_replay: (p = {}) => replayBusDeadLetter({ dl_id: p.dl_id }),
+  // Permanently delete a DLQ row. Use when replay would just dead-letter again.
+  dlq_drop: (p = {}) => dropBusDeadLetter({ dl_id: p.dl_id }),
   purge_brain: async (p = {}) => {
     // Destructive. Wipes chunks/, wiki/, and memory/ content and clears the
     // SQLite index. Requires p.confirm === "DELETE" to execute — typed
@@ -283,6 +315,9 @@ const WRITE_ACTIONS = new Set([
   "confirm_link",
   "reonboard",
   "purge_brain",
+  // DLQ replay/drop mutate the bus DB; list is read-only.
+  "dlq_replay",
+  "dlq_drop",
 ]);
 
 // HTTP server

package/server/lib/bus.mjs

@@ -9,8 +9,12 @@
  */
 
 const DOMAIN = "wicked-brain";
+const PLUGIN = "wicked-brain";
 
 let busEmit = null;
+let busListDeadLetters = null;
+let busReplayDeadLetter = null;
+let busDropDeadLetter = null;
 let busDb = null;
 let busConfig = null;
 let available = false;
@@ -25,6 +29,9 @@ async function init() {
     const dbPath = bus.resolveDbPath();
     busDb = bus.openDb(dbPath);
     busEmit = bus.emit;
+    busListDeadLetters = bus.listDeadLetters;
+    busReplayDeadLetter = bus.replayDeadLetter;
+    busDropDeadLetter = bus.dropDeadLetter;
     available = true;
   } catch {
     // wicked-bus not installed or not initialized — degrade silently
@@ -83,3 +90,82 @@ export async function waitForBus() {
   await ready;
   return available;
 }
+
+/**
+ * List dead-lettered events scoped to wicked-brain's plugin.
+ * Returns [] when the bus is unavailable so callers don't have to branch.
+ *
+ * Upstream takes camelCase `cursorId`; we keep snake_case at this layer
+ * for consistency with the rest of wicked-brain's API and translate here.
+ * `limit` is parsed to an integer because params arriving from the HTTP
+ * dispatch layer can be strings (and upstream rejects non-integers by
+ * silently falling back to its default).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cursor_id] filter to one cursor
+ * @param {number|string} [opts.limit=100]
+ * @returns {Array}
+ */
+export function listBusDeadLetters(opts = {}) {
+  if (!available || !busListDeadLetters) return [];
+  const limit = parseInt(opts.limit ?? 100, 10) || 100;
+  const upstreamOpts = { plugin: PLUGIN, limit };
+  if (opts.cursor_id) upstreamOpts.cursorId = opts.cursor_id;
+  try {
+    return busListDeadLetters(busDb, upstreamOpts);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Mark a dead letter for replay. The managed subscriber drains pending
+ * replays before each poll cycle, so a successful return means the request
+ * is queued, not that the event has re-delivered yet.
+ *
+ * Upstream signature is positional `(db, dlId)`. dl_id is globally unique
+ * (the bus's own primary key) so plugin/cursor scoping is implicit.
+ *
+ * @param {object} args
+ * @param {string} args.dl_id
+ * @returns {{ ok: boolean, error?: string }}
+ */
+export function replayBusDeadLetter({ dl_id } = {}) {
+  if (!available || !busReplayDeadLetter) {
+    return { ok: false, error: "bus unavailable" };
+  }
+  if (!dl_id) {
+    return { ok: false, error: "dl_id required" };
+  }
+  try {
+    busReplayDeadLetter(busDb, dl_id);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * Drop (delete) a dead letter row. Use when an event is no longer relevant
+ * — replay would just dead-letter again.
+ *
+ * Upstream signature is positional `(db, dlId)`. dl_id is globally unique.
+ *
+ * @param {object} args
+ * @param {string} args.dl_id
+ * @returns {{ ok: boolean, error?: string }}
+ */
+export function dropBusDeadLetter({ dl_id } = {}) {
+  if (!available || !busDropDeadLetter) {
+    return { ok: false, error: "bus unavailable" };
+  }
+  if (!dl_id) {
+    return { ok: false, error: "dl_id required" };
+  }
+  try {
+    busDropDeadLetter(busDb, dl_id);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}

package/server/lib/memory-subscriber.mjs

@@ -43,7 +43,7 @@ export async function startMemorySubscriber({ brainPath, brainId, db }) {
     plugin: "wicked-brain",
     filter: "wicked.fact.extracted",
     cursor_init: "latest",
-    pollIntervalMs: 15000,
+    pollIntervalMs: 5000,
     maxRetries: 3,
     backoffMs: [1000, 5000, 30000],
     handler: async (event) => {

package/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain-server",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "description": "SQLite FTS5 search server for wicked-brain digital knowledge bases",
   "keywords": [
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "better-sqlite3": "^12.0.0",
-    "wicked-bus": "^1.1.0"
+    "wicked-bus": "^2.0.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/skills/wicked-brain-dlq/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: wicked-brain:dlq
+description: |
+  Inspect, replay, or drop dead-lettered events from wicked-brain's bus
+  subscriber. The auto-memorize subscriber consumes `wicked.fact.extracted`
+  and dead-letters events that exhaust their retry budget. Without this
+  skill, those events sit untouched forever — a fixable handler bug
+  silently loses every fact.
+
+  Use when: "show DLQ", "replay dead letters", "what events failed",
+  "drop dead letter", "memory subscriber DLQ", "stuck fact events".
+---
+
+# wicked-brain:dlq
+
+List, replay, and drop dead-lettered events held by wicked-bus on behalf of
+the wicked-brain auto-memorize subscriber.
+
+## Cross-Platform Notes
+
+Uses `npx wicked-brain-call` for all server interaction. Cross-platform on
+macOS, Linux, and Windows.
+
+- Paths use forward slashes
+- No Unix-only shell features
+
+## Config
+
+Brain discovery + server lifecycle are handled by `wicked-brain-call`. The
+server bridges to the wicked-bus DB it opened at startup, so DLQ rows are
+always scoped to `plugin: "wicked-brain"`.
+
+If the bus is unavailable (not installed, or the DB is unreachable), `list`
+returns an empty array and `replay` / `drop` return `{ ok: false, error: "bus unavailable" }`.
+
+## Parameters
+
+- **mode** (required): `list`, `replay`, or `drop`
+- **cursor_id** (list, optional): filter to one subscriber cursor
+- **dl_id** (replay/drop, required): dead-letter row id, returned by `list`. Globally unique — alone identifies the row.
+- **limit** (list, optional, default 100): max rows to return
+
+## List mode
+
+```bash
+npx wicked-brain-call dlq_list --param limit=50
+```
+
+Optional cursor scoping:
+```bash
+npx wicked-brain-call dlq_list --param cursor_id={cursor_id}
+```
+
+Returns `{ dead_letters: [...] }`. Each row has `dl_id`, `cursor_id`,
+`event_type`, `domain`, `subdomain`, `payload`, `dead_lettered_at`,
+`attempts`, `last_error`.
+
+The `payload` field is denormalized at DLQ time — the originating row in
+`events` may have been swept by the 24h `dedup_expires_at`, so it reflects
+the event as it failed, not current state.
+
+## Replay mode
+
+```bash
+npx wicked-brain-call dlq_replay --param dl_id={dl_id}
+```
+
+Marks the row for replay. The managed subscriber drains pending replays
+before each poll cycle (5s by default), so a successful return means
+*queued*, not *delivered*. If the handler still rejects the event, it
+will dead-letter again with an incremented attempt count.
+
+Replay is for recovery — not transparent retry. The original
+`idempotency_key` may already have been swept (24h TTL), so a re-emission
+inside the handler will not be deduped against the original event.
+
+## Drop mode
+
+```bash
+npx wicked-brain-call dlq_drop --param dl_id={dl_id}
+```
+
+Permanently deletes the DLQ row. Use when replay would just dead-letter
+again — for example, when the source event was malformed and there's no
+fix path.
+
+## Workflow
+
+A typical recovery loop:
+
+1. `list` to see what's pending and inspect `last_error`.
+2. Fix the handler (`server/lib/memory-promoter.mjs` or `memory-subscriber.mjs`).
+3. Restart the server so the fix takes effect.
+4. `replay` each row.
+5. `list` again to confirm the queue is empty.
+6. `drop` any rows that can't be fixed.
+
+## Reporting
+
+Always surface `dl_id`, `cursor_id`, `event_type`, `attempts`, and
+`last_error` for each row so the operator has enough context to choose
+between replay and drop.