wicked-bus 2.1.1 → 2.2.0

package/README.md

@@ -146,7 +146,7 @@ Agent ecosystems have a communication problem. Tools that should work together
 
 ## Requirements
 
-- Node.js >= 18.0.0
+- Node.js >= 20.0.0
 - `better-sqlite3` >= 9.0.0 (peer dependency)
 - macOS, Linux, or Windows
 

package/lib/poll.js

@@ -7,6 +7,20 @@ import { WBError } from './errors.js';
 
 /**
  * Match an event against a filter string.
+ *
+ * Wildcard semantics (trailing only):
+ * - `prefix.*`  — SINGLE-level: matches `prefix.<one-segment>` and nothing
+ *   deeper. `wicked.test.*` matches `wicked.test.run` but NOT
+ *   `wicked.test.run.completed`. Unchanged from v1; existing subscribers keep
+ *   their exact behavior.
+ * - `prefix.**` — MULTI-level: matches `prefix.<one-or-more-segments>`.
+ *   `wicked.**` matches `wicked.fact.extracted` AND `wicked.test.run.completed`.
+ *   This is the "everything under a prefix" filter the naming convention
+ *   implies (every event is `wicked.<noun>.<verb>`, i.e. 3+ segments, so a
+ *   single-level `wicked.*` would match nothing). At least one trailing
+ *   segment is required — `**` does not match the bare prefix itself.
+ * - `*`         — CATCH-ALL (typically `*@domain`): matches every type.
+ *
  * @param {string} eventType - The event_type to test
  * @param {string} domain - The domain of the event
  * @param {string} filterStr - Filter pattern, e.g. 'wicked.test.run.*@wicked-testing'
@@ -32,18 +46,40 @@ export function matchesFilter(eventType, domain, filterStr) {
   // Exact match
   if (typePattern === eventType) return true;
 
+  // Multi-level wildcard (prefix.**) — one or more remaining segments.
+  // Checked before the single-level case so the `.**` suffix is not
+  // mis-parsed as `.*` with a trailing `*` segment.
+  if (typePattern.endsWith('.**')) {
+    const prefix = typePattern.slice(0, -3);
+    if (eventType.startsWith(prefix + '.')) {
+      const remainder = eventType.slice(prefix.length + 1);
+      return remainder.length > 0; // at least one trailing segment
+    }
+    return false;
+  }
+
   // Single-level wildcard (prefix.*)
   if (typePattern.endsWith('.*')) {
     const prefix = typePattern.slice(0, -2);
     if (eventType.startsWith(prefix + '.')) {
       const remainder = eventType.slice(prefix.length + 1);
-      return !remainder.includes('.'); // single-level only
+      return remainder.length > 0 && !remainder.includes('.'); // single-level only
     }
   }
 
   return false;
 }
 
+/**
+ * Escape characters that are special to SQLite's LIKE operator so a filter
+ * prefix is matched literally. Pairs with `ESCAPE '\\'` in the query.
+ * @param {string} s
+ * @returns {string}
+ */
+function escapeLike(s) {
+  return s.replace(/[\\%_]/g, (ch) => '\\' + ch);
+}
+
 /**
  * Build SQL WHERE clauses from a filter string for optimized queries.
  * @param {string} filterStr
@@ -69,15 +105,25 @@ function buildFilterSql(filterStr) {
     params.domain_filter = domainFilter;
   }
 
-  // Type filter
+  // Type filter — must mirror matchesFilter() exactly.
+  // LIKE escaping note: SQLite LIKE treats `%` and `_` as wildcards. Event
+  // types use only `[a-z0-9._-]`, so `_` could theoretically appear and
+  // over-match a single char. We add an ESCAPE clause and escape `_`/`%`/`\`
+  // in the prefix to keep SQL matching faithful to matchesFilter().
   if (typePattern === '*') {
     // Catch-all: no type filter
+  } else if (typePattern.endsWith('.**')) {
+    // Multi-level: prefix.<one-or-more-segments>
+    const prefix = typePattern.slice(0, -3);
+    conditions.push("event_type LIKE :prefix_like ESCAPE '\\'");
+    params.prefix_like = escapeLike(prefix) + '.%';
   } else if (typePattern.endsWith('.*')) {
+    // Single-level: prefix.<exactly-one-segment>
     const prefix = typePattern.slice(0, -2);
-    conditions.push("event_type LIKE :prefix_like");
-    conditions.push("event_type NOT LIKE :prefix_multi");
-    params.prefix_like = prefix + '.%';
-    params.prefix_multi = prefix + '.%.%';
+    conditions.push("event_type LIKE :prefix_like ESCAPE '\\'");
+    conditions.push("event_type NOT LIKE :prefix_multi ESCAPE '\\'");
+    params.prefix_like = escapeLike(prefix) + '.%';
+    params.prefix_multi = escapeLike(prefix) + '.%.%';
   } else {
     // Exact match
     conditions.push('event_type = :exact_type');

package/lib/subscribe-push-or-poll.js

@@ -35,6 +35,24 @@ export const DEFAULT_REPROBE_INTERVAL_MS = 5000;
 export const DEFAULT_PROBE_TIMEOUT_MS    = 100;
 
 /**
+ * ── DELIVERY GUARANTEE: AT-MOST-ONCE (per consumer) ────────────────────────
+ * Each frame is ACK'd (the v1 cursor is durably advanced) BEFORE it is yielded
+ * to the caller's `for await` loop. If the loop body throws or the process
+ * crashes AFTER receiving an event but BEFORE finishing its work, the cursor
+ * has already moved past that event — it will NOT be re-delivered. The cursor
+ * here means "events handed off to the consumer", not "events the consumer
+ * finished processing".
+ *
+ * This is the OPPOSITE guarantee from {@link import('./subscribe.js').subscribe},
+ * the managed `subscribe()` helper, which acks AFTER the handler succeeds
+ * (at-least-once, with retry + DLQ). Pick this push-or-poll iterable only when
+ * duplicate processing is unacceptable and dropping an event on a mid-stream
+ * failure is tolerable. If you need at-least-once + retry + dead-lettering, use
+ * `subscribe()` instead.
+ *
+ * WARNING: do not assume "I received it" == "it is safe". A throw inside the
+ * `for await` body silently loses the in-flight event.
+ *
  * @param {object} opts
  * @param {import('better-sqlite3').Database} opts.db          - live DB connection (poll fallback + pointer resolution)
  * @param {string}  opts.cursor_id

package/lib/subscribe.js

@@ -214,6 +214,21 @@ function computeLag(db, cursorId) {
 /**
  * Subscribe to events with a managed loop, retry, DLQ, and lifecycle.
  *
+ * ── DELIVERY GUARANTEE: AT-LEAST-ONCE ──────────────────────────────────────
+ * The handler is invoked BEFORE the cursor is acked. If the handler throws,
+ * the event is retried (up to `maxRetries`) and only dead-lettered + acked
+ * once the retry budget is exhausted. A crash between "handler succeeded" and
+ * "ack persisted" re-delivers the event on the next poll. Therefore the
+ * handler MAY see the same logical event more than once and MUST be idempotent
+ * (the bus already enforces emit-side idempotency via the `idempotency_key`
+ * UNIQUE constraint; consumers must enforce their own on the consume side).
+ *
+ * This is the OPPOSITE guarantee from {@link subscribePushOrPoll}, which acks
+ * BEFORE yielding (at-most-once). Choose `subscribe()` when losing an event is
+ * worse than processing it twice (the common case); choose
+ * `subscribePushOrPoll()` only when re-processing is unacceptable and dropping
+ * an event on a mid-stream failure is tolerable.
+ *
  * @param {object} opts
  * @param {import('better-sqlite3').Database} opts.db - Open DB handle (required)
  * @param {string} opts.plugin - Subscriber plugin identity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-bus",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Lightweight, local-first SQLite event bus for AI agents and developer tools",
   "type": "module",
   "exports": {

package/skills/wicked-bus/subscribe/SKILL.md

@@ -138,16 +138,22 @@ async function checkBusEvents() {
 | Pattern | Matches |
 |---------|---------|
 | `wicked.run.completed` | Exact match only |
-| `wicked.run.*` | All `wicked.run.` events (single-level wildcard) |
+| `wicked.run.*` | `wicked.run.<one-segment>` — single-level wildcard |
+| `wicked.run.**` | `wicked.run.<one-or-more-segments>` — multi-level wildcard |
+| `wicked.**` | Everything under `wicked.` (every `wicked.<noun>.<verb>` event) |
 | `*@wicked-brain` | All events from the `wicked-brain` domain |
-| `wicked.memory.*@wicked-brain` | Memory events from brain only |
+| `wicked.memory.*@wicked-brain` | Memory events (single-level) from brain only |
 
 ### Filter rules
 
 1. `*` matches exactly one segment (single-level wildcard)
-2. `@domain` suffix scopes by the `domain` column
-3. Wildcards and `@domain` can combine: `wicked.run.*@my-plugin`
-4. `*` alone (catch-all) is valid but noisy
+2. `**` matches one or more segments (multi-level wildcard). Event types are
+   `wicked.<noun>.<verb>` (3+ segments), so to subscribe to "everything under
+   `wicked`" use `wicked.**`, not `wicked.*` (which would match nothing).
+3. A trailing `**` requires at least one segment after the prefix.
+4. `@domain` suffix scopes by the `domain` column
+5. Wildcards and `@domain` can combine: `wicked.run.*@my-plugin` or `wicked.run.**@my-plugin`
+6. `*` alone (catch-all) is valid but noisy
 
 ## Delivery Semantics