wolverine-ai 1.6.1 → 1.7.1

package/README.md

@@ -185,17 +185,19 @@ Most production bugs don't crash the process — Fastify/Express catch them and
 ```
 Route returns 500 (process still alive)
   → Error hook reports to parent via IPC (auto-injected, zero user code changes)
-  → ErrorMonitor tracks consecutive 500s per route
-  → 3 failures in 30s → triggers heal pipeline (same as crash healing)
+  → ErrorMonitor tracks errors per normalized route (/api/users/:id)
+  → Single error triggers heal pipeline immediately (configurable threshold)
   → Fix applied → server restarted → route prober verifies fix
 ```
 
 | Setting | Default | Env Variable |
 |---------|---------|-------------|
-| Failure threshold | 3 | `WOLVERINE_ERROR_THRESHOLD` |
+| Failure threshold | 1 | `WOLVERINE_ERROR_THRESHOLD` |
 | Time window | 30s | `WOLVERINE_ERROR_WINDOW_MS` |
 | Cooldown per route | 60s | `WOLVERINE_ERROR_COOLDOWN_MS` |
 
+Routes are auto-normalized: `/api/users/123` and `/api/users/456` aggregate as `/api/users/:id`.
+
 The error hook auto-patches Fastify and Express via `--require` preload. No middleware, no code changes to your server.
 
 ---
@@ -315,7 +317,7 @@ Reasoning models (`o-series`, `gpt-5-nano`) automatically get 4x token limits to
 | **Admin Auth** | Dashboard requires key + IP allowlist. Localhost always allowed. Remote IPs via `WOLVERINE_ADMIN_IPS` env var or `POST /api/admin/add-ip` at runtime. Timing-safe comparison, lockout after 10 failures |
 | **Rate Limiter** | Sliding window, min gap, hourly budget, exponential backoff on error loops |
 | **MCP Security** | Per-server tool allowlists, arg sanitization, result injection scanning |
-| **SQL Skill** | `sqlGuard()` middleware blocks 15 injection pattern families on all endpoints |
+| **SQL Skill** | `sqlGuard()` blocks 15 injection pattern families; `idempotencyGuard()` prevents double-fire in cluster mode |
 
 ---
 
@@ -354,17 +356,35 @@ The `📊 Analytics` dashboard panel shows memory/CPU charts, route health statu
 
 ---
 
-## Auto-Clustering
+## Cluster Mode
 
-Wolverine detects your machine and forks the optimal number of workers:
+The server handles its own clustering. Wolverine is the single process manager — it spawns your server, which forks workers internally.
 
 ```bash
-wolverine server/index.js           # auto-detect: 20 cores → 10 workers
-wolverine server/index.js --single  # force single worker (dev mode)
-wolverine server/index.js --workers 4  # force 4 workers
-wolverine --info                    # show system capabilities
+# Enable cluster mode
+WOLVERINE_CLUSTER=true wolverine server/index.js
+
+# System info (cores, RAM, recommended workers)
+wolverine --info
+```
+
+**How it works:**
+```
+Wolverine (single process manager)
+  └── spawns server/index.js
+        ├── WOLVERINE_CLUSTER=false → single server (default)
+        └── WOLVERINE_CLUSTER=true  → master forks N workers
+             ├── Worker 1 (port 3000, reusePort)
+             ├── Worker 2 (port 3000, reusePort)
+             └── Worker N (port 3000, reusePort)
 ```
 
+- **`WOLVERINE_RECOMMENDED_WORKERS`** auto-set based on CPU cores/RAM
+- Workers share port 3000 via `reusePort` — OS handles load balancing
+- Dead workers auto-respawn by the master process
+- Wolverine kills the **entire process tree** on restart (no orphaned workers)
+- **Idempotency protection** prevents double-fire across workers (see below)
+
 **System detection:**
 - CPU cores, model, speed
 - Total/free RAM, disk space
@@ -372,18 +392,6 @@ wolverine --info                    # show system capabilities
 - Container environment (Docker, Kubernetes)
 - Cloud provider (AWS, GCP, Azure, Railway, Fly, Render, Heroku)
 
-**Scaling rules:**
-
-| Cores | Workers |
-|-------|---------|
-| 1 | 1 (no clustering) |
-| 2 | 2 |
-| 3-4 | cores - 1 |
-| 5-8 | cores - 1, cap 6 |
-| 9+ | cores / 2, cap 16 |
-
-Workers auto-respawn on crash with exponential backoff (1s → 30s). Max 5 restarts per worker.
-
 ---
 
 ## Configuration
@@ -412,8 +420,8 @@ Startup:
 - Auto-registers on first run, retries every 60s until platform responds
 - Saves key to `.wolverine/platform-key` (survives restarts)
 - Sends one ~2KB JSON POST every 60 seconds (5s timeout, non-blocking)
-- Payload matches [PLATFORM.md](PLATFORM.md) spec: `instanceId`, `server`, `process`, `routes`, `repairs`, `usage` (tokens/cost/calls + `byCategory` + `byModel` + `byTool`), `brain`, `backups`
-- Platform analytics aggregates across all servers: total tokens/cost, breakdown by category (heal/chat/develop/security/classify/research/brain), by model, by tool
+- Payload: `instanceId`, `server`, `process`, `routes`, `repairs`, `usage` (tokens/cost/calls + `byCategory` + `byModel` + `byTool`), `brain`, `backups`
+- Platform aggregates across all servers: total tokens/cost by category, model, tool
 - Secrets redacted before sending
 - Offline-resilient: queues up to 1440 heartbeats locally, drains on reconnect
 
@@ -422,7 +430,7 @@ Startup:
 **Override:** `WOLVERINE_PLATFORM_URL=https://your-own-platform.com`
 **Opt out:** `WOLVERINE_TELEMETRY=false`
 
-See [PLATFORM.md](PLATFORM.md) for the backend spec and [TELEMETRY.md](TELEMETRY.md) for the protocol.
+Telemetry payload includes: `instanceId`, `server`, `process`, `routes`, `repairs`, `usage` (by category/model/tool), `brain`, `backups`.
 
 ---
 
@@ -478,14 +486,53 @@ Full `server/` directory snapshots with lifecycle management:
 Auto-discovered from `src/skills/`. Each skill exports metadata for the registry:
 
 ### SQL Skill (`src/skills/sql.js`)
-- **sqlGuard()** — Express middleware blocking SQL injection (UNION, stacked queries, tautologies, timing attacks, etc.)
-- **SafeDB** — Parameterized-only database wrapper (blocks string concatenation in queries)
+- **sqlGuard()** — Fastify/Express middleware blocking SQL injection (UNION, stacked queries, tautologies, timing attacks, 15 pattern families)
+- **SafeDB** — Cluster-safe database with split read/write connections, FIFO write queue, WAL mode
+- **idempotencyGuard()** — Prevents double-fire of write requests in cluster mode (see below)
+- **db.idempotent(key, fn)** — Database-level dedup for critical writes (payments, orders)
 - Auto-injected into agent prompts when building database features
 
 Add new skills by creating a file in `src/skills/` with `SKILL_NAME`, `SKILL_DESCRIPTION`, `SKILL_KEYWORDS`, `SKILL_USAGE` exports.
 
 ---
 
+## Idempotency (Double-Fire Protection)
+
+In cluster mode, a retry or duplicate request can land on a different worker and execute twice. Two layers prevent this:
+
+### Layer 1: HTTP Middleware
+
+```javascript
+const { idempotencyGuard, idempotencyAfterHook } = require("wolverine-ai");
+
+fastify.addHook("preHandler", idempotencyGuard({ db, logger }));
+fastify.addHook("onSend", idempotencyAfterHook(db));
+```
+
+- Client sends `X-Idempotency-Key: order-abc-123` header
+- Without header: auto-generates key from `sha256(method + url + body)`
+- First request: executes handler, caches response in shared SQLite table
+- Duplicate: returns cached response with `X-Idempotency-Cached: true` header
+- Safe methods (GET/HEAD/OPTIONS) always pass through
+- Keys expire after 24h (configurable)
+
+### Layer 2: Database-Level
+
+```javascript
+const result = await db.idempotent("charge-abc-123", (tx) => {
+  tx.run("INSERT INTO charges (id, amount) VALUES (?, ?)", ["abc-123", 99.99]);
+  tx.run("UPDATE balance SET amount = amount - ? WHERE user_id = ?", [99.99, 1]);
+  return { charged: true };
+});
+// result.executed = true (first time) or false (duplicate)
+```
+
+- Wraps `fn` in a transaction with idempotency key check
+- All workers share the `_idempotency` table via WAL mode — globally consistent
+- Auto-created on `db.connect()`, pruned via `db.pruneIdempotency()`
+
+---
+
 ## MCP Integration
 
 Connect external tools via [Model Context Protocol](https://modelcontextprotocol.io):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wolverine-ai",
-  "version": "1.6.1",
+  "version": "1.7.1",
   "description": "Self-healing Node.js server framework powered by AI. Catches crashes, diagnoses errors, generates fixes, verifies, and restarts — automatically.",
   "main": "src/index.js",
   "bin": {

package/src/brain/brain.js

@@ -96,7 +96,7 @@ const SEED_DOCS = [
     metadata: { topic: "skill-sql-patterns" },
   },
   {
-    text: "Database best practices: SafeDB uses split connections — separate read connection (concurrent, never waits) and write connection (single writer, FIFO queue). Write queue drains synchronously in one microtask, zero delays. WAL mode means readers never block writers. Each write is microseconds. db.transaction(fn) queues as single atomic unit. No busy_timeout, no blocking, no IPC. Reads: db.get(), db.all() are instant. Writes: db.run(), db.exec() go through queue.",
+    text: "Database best practices: SafeDB uses split connections — separate read connection (concurrent, never waits) and write connection (single writer, FIFO queue). Write queue drains synchronously in one microtask, zero delays. WAL mode means readers never block writers. Each write is microseconds. db.transaction(fn) queues as single atomic unit. No busy_timeout, no blocking, no IPC. Reads: db.get(), db.all() are instant. Writes: db.run(), db.exec() go through queue. Idempotent writes: db.idempotent(key, fn, ttlSeconds) executes fn only once per key — prevents double-charge/double-insert when retries or cluster workers duplicate a request. Idempotency keys stored in _idempotency table (auto-created on connect), shared across all workers via WAL mode.",
     metadata: { topic: "skill-sql-best-practices" },
   },
   {
@@ -120,7 +120,7 @@ const SEED_DOCS = [
     metadata: { topic: "process-manager" },
   },
   {
-    text: "Auto-clustering: wolverine detects machine capabilities (cores, RAM, disk, platform, Docker/K8s, cloud provider) and forks optimal workers. 2 cores = 2 workers, 3-4 = cores-1, 5-8 = cores-1 cap 6, 9+ = cores/2 cap 16. Workers auto-respawn on crash with exponential backoff. CLI: --single (no cluster), --workers N (fixed), --info (show system). Settings in server/config/settings.json cluster.mode.",
+    text: "Cluster mode: server handles its own clustering (not wolverine-level). WOLVERINE_CLUSTER=true enables it. Server forks N workers (WOLVERINE_RECOMMENDED_WORKERS set by system detection). Workers share port 3000 via reusePort. Wolverine kills entire process tree on restart (_killProcessTree: taskkill /T on Windows, kill -pgid + pgrep -P on Linux). Idempotency protection prevents double-fire: idempotencyGuard() middleware deduplicates write requests across workers using shared SQLite _idempotency table. Client sends X-Idempotency-Key header, or auto-generated from method+path+body hash. All workers see the same table via WAL mode. SafeDB.idempotent(key, fn) for database-level dedup.",
     metadata: { topic: "clustering" },
   },
   {
@@ -220,9 +220,13 @@ const SEED_DOCS = [
     metadata: { topic: "agent-tools-v2" },
   },
   {
-    text: "Server problem categories the agent can fix: CODE BUGS (SyntaxError, TypeError, ReferenceError → edit_file), DEPENDENCIES (Cannot find module → npm install, corrupted node_modules → rm + reinstall), DATABASE (invalid entries → run_db_fix UPDATE, missing table → CREATE TABLE, schema mismatch → ALTER TABLE, constraint violation → fix data or schema), CONFIG (invalid JSON → edit_file, missing env vars → write .env, wrong port → edit config), FILESYSTEM (misplaced files → move_file, missing directories → bash_exec mkdir, wrong permissions → chmod), NETWORK (port conflict → check_port + kill, service down → restart, connection refused → check config), STATE (corrupted cache → delete + restart, stale locks → remove lock file, git conflicts → resolve markers). The agent investigates before fixing — reads files, checks directories, inspects databases, never guesses.",
+    text: "Server problem categories the agent can fix: CODE BUGS (SyntaxError, TypeError, ReferenceError → edit_file), DEPENDENCIES (Cannot find module → npm install, corrupted node_modules → rm + reinstall), DATABASE (invalid entries → run_db_fix UPDATE, missing table → CREATE TABLE, schema mismatch → ALTER TABLE, constraint violation → fix data or schema), CONFIG (invalid JSON → edit_file, missing env vars → write .env, wrong port → edit config), FILESYSTEM (misplaced files → move_file, missing directories → bash_exec mkdir, wrong permissions → chmod), NETWORK (port conflict → check_port + kill, service down → restart, connection refused → check config), STATE (corrupted cache → delete + restart, stale locks → remove lock file, git conflicts → resolve markers), IDEMPOTENCY (double-fire → add idempotencyGuard middleware, missing idempotency key → add X-Idempotency-Key header support, duplicate DB entries → add UNIQUE constraint or use db.idempotent()). The agent investigates before fixing — reads files, checks directories, inspects databases, never guesses.",
     metadata: { topic: "server-problems" },
   },
+  {
+    text: "Idempotency protection: two layers prevent double-fire in cluster mode. Layer 1: idempotencyGuard() Fastify middleware — intercepts POST/PUT/PATCH/DELETE, checks X-Idempotency-Key header (or auto-generates key from method+path+body hash), queries _idempotency table. If key exists and not expired → return cached response with X-Idempotency-Cached:true header, skip handler. If new → pass through, idempotencyAfterHook() stores response. Layer 2: SafeDB.idempotent(key, fn) — database-level dedup. Wraps fn in transaction, checks key, executes only if new. Returns {executed:true/false, result, cached}. Keys expire after TTL (default 24h). All workers share the SQLite _idempotency table via WAL mode — globally consistent. Auto-pruned on connect and via db.pruneIdempotency().",
+    metadata: { topic: "idempotency" },
+  },
   {
     text: "Heal pipeline no longer requires a file path. When no file is identified from the error (database errors, config problems, port conflicts), the pipeline skips fast path and goes straight to the agent, which uses investigation tools (glob_files, grep_code, list_dir, inspect_db, check_env, check_port) to find the root cause. Agent verification for no-file errors: if agent made changes or ran commands, trust the agent's assessment. For file-based errors, verification uses syntax check + boot probe as before.",
     metadata: { topic: "fileless-heal" },

package/src/index.js

@@ -33,7 +33,7 @@ const { scanProject } = require("./brain/function-map");
 const { detect: detectSystem } = require("./core/system-info");
 const { ClusterManager } = require("./core/cluster-manager");
 const { loadConfig, getConfig } = require("./core/config");
-const { sqlGuard, SafeDB, scanForInjection } = require("./skills/sql");
+const { sqlGuard, SafeDB, scanForInjection, idempotencyGuard, idempotencyAfterHook } = require("./skills/sql");
 
 module.exports = {
   // Core
@@ -93,4 +93,6 @@ module.exports = {
   sqlGuard,
   SafeDB,
   scanForInjection,
+  idempotencyGuard,
+  idempotencyAfterHook,
 };

package/src/skills/sql.js

@@ -201,6 +201,18 @@ class SafeDB {
         this._writer.pragma("foreign_keys = ON");
         this._writer.pragma("synchronous = NORMAL");
 
+        // Idempotency table — prevents double-execution of writes in cluster mode
+        this._writer.exec(`
+          CREATE TABLE IF NOT EXISTS _idempotency (
+            key TEXT PRIMARY KEY,
+            result TEXT,
+            created_at INTEGER DEFAULT (strftime('%s','now')),
+            expires_at INTEGER
+          )
+        `);
+        // Clean expired keys on connect
+        this._writer.exec(`DELETE FROM _idempotency WHERE expires_at < strftime('%s','now')`);
+
       } catch (err) {
         if (err.code === "MODULE_NOT_FOUND") {
           throw new Error("Install better-sqlite3: npm install better-sqlite3");
@@ -216,6 +228,49 @@ class SafeDB {
     process.on("exit", () => this.close());
   }
 
+  /**
+   * Idempotent write — execute fn only if this key hasn't been seen before.
+   * In cluster mode, prevents the same request from double-firing across workers.
+   *
+   * @param {string} key — unique idempotency key (e.g. from X-Idempotency-Key header)
+   * @param {Function} fn — function that performs the write, receives writerProxy
+   * @param {number} ttlSeconds — how long to remember this key (default: 86400 = 24h)
+   * @returns {{ executed: boolean, result: any }} — executed=false if key was already seen
+   */
+  idempotent(key, fn, ttlSeconds = 86400) {
+    this._assertOpen();
+    return this._enqueueWrite(() => {
+      // Check if key already executed
+      const existing = this._writer.prepare("SELECT result FROM _idempotency WHERE key = ? AND expires_at > strftime('%s','now')").get(key);
+      if (existing) {
+        return { executed: false, result: JSON.parse(existing.result || "null"), cached: true };
+      }
+
+      // Execute the write
+      const txn = this._writer.transaction(() => {
+        const result = fn(this._writerProxy());
+        // Store the key so duplicates are rejected
+        this._writer.prepare(
+          "INSERT OR REPLACE INTO _idempotency (key, result, expires_at) VALUES (?, ?, strftime('%s','now') + ?)"
+        ).run(key, JSON.stringify(result ?? null), ttlSeconds);
+        return result;
+      });
+
+      const result = txn();
+      return { executed: true, result, cached: false };
+    });
+  }
+
+  /**
+   * Clean up expired idempotency keys. Call periodically (e.g., every hour).
+   */
+  pruneIdempotency() {
+    this._assertOpen();
+    return this._enqueueWrite(() => {
+      return this._writer.prepare("DELETE FROM _idempotency WHERE expires_at < strftime('%s','now')").run();
+    });
+  }
+
   /**
    * Write query (INSERT, UPDATE, DELETE, CREATE).
    * Queued and executed in order. Returns a promise that resolves with the result.
@@ -327,27 +382,137 @@ class SafeDB {
   }
 }
 
+// ── Idempotency Middleware ──────────────────────────────────────
+
+/**
+ * Request idempotency middleware — prevents double-fire in cluster mode.
+ *
+ * How it works:
+ * 1. Client sends write request (POST/PUT/PATCH/DELETE) with X-Idempotency-Key header
+ * 2. Middleware checks if this key was already processed
+ * 3. If yes: return cached response (no re-execution)
+ * 4. If no: execute handler, cache response, return result
+ *
+ * Without the header, mutating requests get an auto-generated key based on
+ * method + path + body hash. This means identical retries are deduplicated
+ * even without client cooperation.
+ *
+ * In cluster mode (reusePort), a retry can land on a different worker.
+ * Since all workers share the same SQLite database (WAL mode), the
+ * idempotency table is visible to all workers instantly.
+ *
+ * Safe methods (GET, HEAD, OPTIONS) are always passed through — they're
+ * inherently idempotent.
+ *
+ * @param {object} options
+ * @param {SafeDB} options.db — SafeDB instance (must be connected)
+ * @param {number} options.ttlSeconds — how long to cache responses (default: 86400)
+ * @param {object} options.logger — wolverine EventLogger (optional)
+ */
+function idempotencyGuard(options = {}) {
+  const db = options.db;
+  const ttlSeconds = options.ttlSeconds || 86400;
+  const logger = options.logger || null;
+  const crypto = require("crypto");
+
+  return async (req, res, next) => {
+    // Safe methods are inherently idempotent — pass through
+    const method = (req.method || "GET").toUpperCase();
+    if (["GET", "HEAD", "OPTIONS"].includes(method)) return next();
+
+    // Get or generate idempotency key
+    let key = req.headers["x-idempotency-key"] || req.headers["idempotency-key"];
+    if (!key) {
+      // Auto-generate from method + path + body hash
+      const bodyStr = typeof req.body === "string" ? req.body : JSON.stringify(req.body || "");
+      key = crypto.createHash("sha256").update(`${method}:${req.url}:${bodyStr}`).digest("hex");
+    }
+
+    if (!db || !db._writer) return next(); // No DB — can't check, pass through
+
+    try {
+      // Check idempotency table directly (read from writer for consistency)
+      const existing = db._writer.prepare(
+        "SELECT result FROM _idempotency WHERE key = ? AND expires_at > strftime('%s','now')"
+      ).get(key);
+
+      if (existing) {
+        // Already processed — return cached response
+        const cached = JSON.parse(existing.result || "null");
+        if (logger) logger.debug("idempotency.hit", `Duplicate request blocked: ${method} ${req.url}`, { key: key.slice(0, 16) });
+
+        const status = cached?.statusCode || 200;
+        const body = cached?.body || cached;
+        if (typeof res.code === "function") {
+          // Fastify
+          res.code(status).header("X-Idempotency-Cached", "true").send(body);
+        } else {
+          // Express
+          res.status(status).set("X-Idempotency-Cached", "true").json(body);
+        }
+        return;
+      }
+
+      // Not seen — attach key to request for the route handler to use
+      req._idempotencyKey = key;
+      req._idempotencyTtl = ttlSeconds;
+    } catch {
+      // DB error — don't block the request, just pass through
+    }
+
+    next();
+  };
+}
+
+/**
+ * After-response hook — stores the response for future idempotency checks.
+ * For Fastify, add as onSend hook. For Express, monkey-patch res.json.
+ *
+ * @param {SafeDB} db — connected SafeDB instance
+ */
+function idempotencyAfterHook(db) {
+  return (req, reply, payload, done) => {
+    if (req._idempotencyKey && db && db._writer) {
+      try {
+        const statusCode = reply.statusCode || 200;
+        const result = JSON.stringify({ statusCode, body: typeof payload === "string" ? JSON.parse(payload) : payload });
+        db._writer.prepare(
+          "INSERT OR IGNORE INTO _idempotency (key, result, expires_at) VALUES (?, ?, strftime('%s','now') + ?)"
+        ).run(req._idempotencyKey, result, req._idempotencyTtl || 86400);
+      } catch { /* non-fatal */ }
+    }
+    done();
+  };
+}
+
 // ── Skill Metadata (for SkillRegistry discovery) ──
 
 const SKILL_NAME = "sql";
-const SKILL_DESCRIPTION = "SQL database interface with injection prevention. Provides sqlGuard() middleware to block SQL injection on all endpoints, and SafeDB class for parameterized-only database queries.";
-const SKILL_KEYWORDS = ["sql", "database", "db", "query", "injection", "sqlite", "postgres", "mysql", "select", "insert", "update", "delete", "table", "schema", "migration", "parameterized"];
-const SKILL_USAGE = `// Protect all routes from SQL injection
-const { sqlGuard } = require("../src/skills/sql");
-app.use(sqlGuard({ logger: wolverineLogger }));
-
-// Cluster-safe database (each worker gets its own connection)
-const { SafeDB } = require("../src/skills/sql");
+const SKILL_DESCRIPTION = "SQL database interface with injection prevention + idempotency. Provides sqlGuard() middleware to block SQL injection, idempotencyGuard() middleware to prevent double-fire in cluster mode, and SafeDB class for parameterized-only database queries with built-in idempotency key support.";
+const SKILL_KEYWORDS = ["sql", "database", "db", "query", "injection", "sqlite", "postgres", "mysql", "select", "insert", "update", "delete", "table", "schema", "migration", "parameterized", "idempotent", "idempotency", "duplicate", "double", "cluster", "transaction"];
+const SKILL_USAGE = `// Protect routes from SQL injection + double-fire
+const { sqlGuard, idempotencyGuard, idempotencyAfterHook, SafeDB } = require("../src/skills/sql");
 const db = new SafeDB({ type: "sqlite", path: "./server/data.db" });
-await db.connect(); // WAL mode, busy_timeout=5s, write serialization
+await db.connect();
+
+// Middleware: injection prevention + idempotency (cluster-safe)
+fastify.addHook("preHandler", sqlGuard({ logger }));
+fastify.addHook("preHandler", idempotencyGuard({ db, logger }));
+fastify.addHook("onSend", idempotencyAfterHook(db));
 
-// Reads (concurrent across workers)
+// Reads (concurrent across workers — never waits)
 const users = db.all("SELECT * FROM users WHERE role = ?", ["admin"]);
 
-// Writes (serialized — no corruption)
+// Writes (serialized FIFO queue — no corruption)
 db.run("INSERT INTO users (name, role) VALUES (?, ?)", ["Alice", "admin"]);
 
-// Batch writes (atomic transaction, single lock)
+// Idempotent write — prevents double-charge/double-insert in cluster mode
+const result = await db.idempotent("order-abc-123", (tx) => {
+  tx.run("INSERT INTO orders (id, total) VALUES (?, ?)", ["abc-123", 99.99]);
+  return { orderId: "abc-123" };
+}); // result.executed=true first time, false on retry
+
+// Atomic transaction (all-or-nothing)
 db.transaction((tx) => {
   tx.run("INSERT INTO orders (user_id, total) VALUES (?, ?)", [1, 99.99]);
   tx.run("UPDATE users SET order_count = order_count + 1 WHERE id = ?", [1]);
@@ -364,6 +529,8 @@ module.exports = {
 
   // Middleware
   sqlGuard,
+  idempotencyGuard,
+  idempotencyAfterHook,
   scanForInjection,
   deepScan,