shabti 2.5.0 → 2.7.0

package/README.md

@@ -2,7 +2,7 @@
 
 Agent Memory OS — semantic memory for AI agents.
 
-A Rust-powered memory engine with Node.js CLI that provides semantic search, deduplication, time-decay scoring, and graph-based memory linking for AI agents.
+A Rust-powered memory engine with Node.js CLI that provides semantic search, deduplication, time-decay scoring, and graph-based memory linking for AI agents. Integrates with Claude Code, Cursor, and other tools via MCP and A2A protocols.
 
 ## Install
 
@@ -30,11 +30,14 @@ shabti config setup --check
 # Store a memory
 shabti store "Rust is a systems programming language"
 
+# Store with namespace and TTL (auto-expires after 1 hour)
+shabti store "temp note" --namespace work --ttl 3600
+
 # Search memories
 shabti search "systems programming"
 
-# Search with score explanation
-shabti search "programming" --explain
+# Search with score explanation and graph expansion
+shabti search "programming" --explain --follow-links 2
 
 # Check engine status
 shabti status
@@ -42,14 +45,20 @@ shabti status
 
 ## Commands
 
-| Command           | Description                  |
-| ----------------- | ---------------------------- |
-| `store <content>` | Store a memory entry         |
-| `search <query>`  | Search memory entries        |
-| `status`          | Show engine status           |
-| `snapshot`        | Manage storage snapshots     |
-| `config`          | Manage configuration         |
-| `chat`            | Interactive chat with OpenAI |
+| Command           | Description                         |
+| ----------------- | ----------------------------------- |
+| `store <content>` | Store a memory entry                |
+| `search <query>`  | Search memory entries               |
+| `delete <id>`     | Delete a memory entry by ID         |
+| `status`          | Show engine status                  |
+| `export`          | Export memories as JSONL            |
+| `import <file>`   | Import memories from JSONL          |
+| `snapshot`        | Manage storage snapshots            |
+| `config`          | Manage configuration                |
+| `gc`              | Garbage collect expired entries     |
+| `a2a`             | Start A2A protocol server           |
+| `chat`            | Interactive chat with OpenAI        |
+| `mcp-config`      | Print MCP server configuration JSON |
 
 ### store
 
@@ -57,6 +66,7 @@ shabti status
 shabti store "Tokyo is the capital of Japan"
 shabti store "meeting at 3pm" --namespace work
 shabti store "buy groceries" --tags "todo,personal"
+shabti store "temporary note" --ttl 3600    # expires in 1 hour
 ```
 
 ### search
@@ -70,6 +80,28 @@ shabti search "recent events" --min-score 0.5
 shabti search "query" --json                    # JSON output
 ```
 
+### delete
+
+```bash
+shabti delete <uuid>
+```
+
+### export / import
+
+```bash
+# Export all entries to stdout
+shabti export
+
+# Export to file with namespace filter
+shabti export --namespace work --output backup.jsonl
+
+# Import from JSONL file
+shabti import backup.jsonl
+
+# Import with namespace override and dry-run
+shabti import data.jsonl --namespace imported --dry-run
+```
+
 ### snapshot
 
 ```bash
@@ -88,13 +120,18 @@ shabti config setup           # show Qdrant setup instructions
 shabti config setup --check   # test Qdrant connection
 ```
 
+### gc
+
+```bash
+shabti gc    # remove entries past their TTL
+```
+
 ## Interactive Mode (REPL)
 
 Run `shabti` with no arguments in a terminal to enter interactive mode:
 
 ```
 $ shabti
-  shabti v2.0.0
 
   [info] Memory engine connected (/remember, /recall available)
   [info] Interactive mode — model: gpt-4o-mini
@@ -119,14 +156,14 @@ Requires `OPENAI_API_KEY` in `.env` for chat functionality. Memory commands (`/r
 
 ## MCP Server
 
-shabti includes an MCP (Model Context Protocol) server for integration with Claude Code, Cursor, and other MCP-compatible tools.
+Shabti includes an MCP (Model Context Protocol) server for integration with Claude Code, Cursor, and other MCP-compatible tools.
 
 ```bash
 # Start the MCP server (stdio transport)
 npx shabti-mcp
 ```
 
-### Claude Code configuration
+### Claude Code / Cursor configuration
 
 Generate the MCP settings JSON:
 
@@ -147,23 +184,57 @@ Or manually add to your MCP settings:
 }
 ```
 
-### Available tools
+### MCP Tools
 
-| Tool            | Description                            |
-| --------------- | -------------------------------------- |
-| `memory_store`  | Store a memory entry                   |
-| `memory_search` | Search memories by semantic similarity |
-| `memory_delete` | Delete a memory entry by ID            |
-| `memory_list`   | List recent memory entries             |
-| `memory_status` | Get engine status                      |
+| Tool            | Description                                                 |
+| --------------- | ----------------------------------------------------------- |
+| `memory_store`  | Store a memory entry with optional namespace, tags, and TTL |
+| `memory_search` | Search memories by semantic similarity                      |
+| `memory_delete` | Delete a memory entry by ID                                 |
+| `memory_list`   | List recent memory entries                                  |
+| `memory_export` | Export entries as JSONL                                     |
+| `memory_gc`     | Garbage collect expired entries                             |
+| `memory_status` | Get engine status                                           |
 
-### Available resources
+### MCP Resources
 
 | URI               | Description                  |
 | ----------------- | ---------------------------- |
 | `shabti://status` | Engine status and statistics |
 | `shabti://config` | Current configuration        |
 
+## A2A Protocol Server
+
+Shabti supports Google's [Agent-to-Agent (A2A) protocol](https://google.github.io/A2A/) v0.3.0 for inter-agent communication.
+
+```bash
+# Start the A2A server (default port 3000)
+shabti a2a
+
+# Start on a custom port
+shabti a2a --port 4000
+```
+
+### Agent Card
+
+Discoverable at `GET /.well-known/agent-card.json`.
+
+### Skills
+
+| Skill           | Description                          |
+| --------------- | ------------------------------------ |
+| `memory_store`  | Store a memory entry via A2A message |
+| `memory_search` | Semantic search via A2A message      |
+| `memory_status` | Engine status via A2A message        |
+
+### JSON-RPC Methods
+
+| Method         | Description                      |
+| -------------- | -------------------------------- |
+| `message/send` | Send a message to invoke a skill |
+| `tasks/get`    | Retrieve task status and results |
+| `tasks/cancel` | Cancel a running task            |
+
 ## Node.js API
 
 ```javascript
@@ -176,7 +247,11 @@ const engine = new ShabtiEngine({
 });
 
 // Store
-await engine.store("Rust is a systems programming language", {});
+await engine.store("Rust is a systems programming language", {
+  namespace: "tech",
+  tags: ["rust", "programming"],
+  ttlSeconds: 86400, // expires in 24 hours
+});
 
 // Search
 const results = await engine.executeQuery({
@@ -187,29 +262,52 @@ const results = await engine.executeQuery({
 
 for (const r of results) {
   console.log(`${r.score.toFixed(4)}  ${r.content}`);
-  if (r.explanation) {
-    console.log(
-      `  sim=${r.explanation.semanticSimilarity.toFixed(3)} ` +
-        `decay=${r.explanation.timeDecayFactor.toFixed(3)} ` +
-        `boost=${r.explanation.accessBoostFactor.toFixed(3)}`,
-    );
-  }
 }
 
+// Export
+const entries = engine.listEntries({ namespace: "tech", limit: 100 });
+
+// Garbage collect
+const removed = await engine.gc();
+
 await engine.shutdown();
 ```
 
+## Configuration
+
+### Environment Variables
+
+| Variable            | Description                                           | Default                 |
+| ------------------- | ----------------------------------------------------- | ----------------------- |
+| `SHABTI_QDRANT_URL` | Override Qdrant URL                                   | `http://localhost:6334` |
+| `SHABTI_LOG_LEVEL`  | Log level: `debug`, `info`, `warn`, `error`, `silent` | `info`                  |
+| `SHABTI_LOG_JSON`   | Set to `1` for JSON-formatted log output              | —                       |
+| `SHABTI_A2A_PORT`   | A2A server port (standalone mode)                     | `3000`                  |
+| `OPENAI_API_KEY`    | Required for chat/REPL mode                           | —                       |
+
+### Config File
+
+Stored at `~/.shabti/config.json`. Manage via `shabti config` commands.
+
 ## Architecture
 
 ```
 shabti (npm CLI + Node.js API)
-  └── shabti-napi (Rust ↔ Node.js FFI via NAPI-RS)
-       └── shabti-engine (orchestration layer)
-            ├── shabti-embedding (fastembed-rs, MultilingualE5Small 384-dim)
-            ├── shabti-index (Qdrant vector DB client)
-            ├── shabti-storage (append-only log, event store, snapshots)
-            ├── shabti-graph (k-NN memory link graph)
-            └── shabti-core (data models, scoring, dedup, query DSL)
+  ├── src/commands/      12 CLI commands (Commander.js)
+  ├── src/repl/          Interactive REPL with slash commands
+  ├── src/mcp/           MCP server (stdio, 7 tools, 2 resources)
+  ├── src/a2a/           A2A server (HTTP, JSON-RPC 2.0)
+  ├── src/core/          Engine factory, session, retry logic
+  ├── src/utils/         Style, validation, structured logger
+  └── native.cjs         NAPI-RS bridge
+       └── crates/
+            ├── shabti-engine     Orchestration, store/search/gc
+            ├── shabti-core       Data models, scoring, dedup, query DSL
+            ├── shabti-embedding  fastembed-rs (MultilingualE5Small, 384-dim)
+            ├── shabti-index      Qdrant vector DB client
+            ├── shabti-storage    Append-only log, event store, snapshots
+            ├── shabti-graph      k-NN memory link graph
+            └── shabti-napi       NAPI-RS bindings
 ```
 
 ## Benchmarks
@@ -227,10 +325,10 @@ See [BENCHMARKS.md](BENCHMARKS.md) for detailed results.
 ```bash
 npm install          # install JS dependencies
 cargo build          # build Rust workspace
-npm test             # run JS tests (vitest)
-cargo test           # run Rust tests
+npm test             # run JS tests (vitest) — 129 tests
+cargo test           # run Rust tests — 26 test modules
 npm run lint         # eslint
-cargo clippy         # Rust linter
+npm run ci           # lint + format check + audit + coverage
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shabti",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Agent Memory OS — semantic memory for AI agents",
   "type": "module",
   "main": "native.cjs",

package/src/a2a/server.js

@@ -2,6 +2,7 @@ import { createServer } from "http";
 import { randomUUID } from "crypto";
 import { buildAgentCard } from "./agentCard.js";
 import { createEngine } from "../core/engine.js";
+import { logger } from "../utils/logger.js";
 
 // ============================================================
 // Task Store (in-memory)
@@ -289,7 +290,9 @@ export function startA2AServer(port = 3000) {
     if (engineError) throw engineError;
     try {
       engine = createEngine();
+      logger.info("A2A engine initialized");
     } catch (err) {
+      logger.error("A2A engine initialization failed", { error: err.message });
       engineError = err;
       throw err;
     }
@@ -322,7 +325,7 @@ export function startA2AServer(port = 3000) {
       let body;
       try {
         body = await readBody(req);
-      } catch {
+      } catch (_) {
         res.writeHead(400);
         return res.end();
       }
@@ -330,7 +333,7 @@ export function startA2AServer(port = 3000) {
       let rpc;
       try {
         rpc = JSON.parse(body);
-      } catch {
+      } catch (_) {
         res.writeHead(200, { "Content-Type": "application/json" });
         return res.end(
           JSON.stringify({
@@ -367,5 +370,21 @@ export function startA2AServer(port = 3000) {
     console.log(`  Skills: ${agentCard.skills.map((s) => s.id).join(", ")}\n`);
   });
 
+  async function shutdown() {
+    console.log("\n  Shutting down A2A server...");
+    server.close();
+    if (engine && engine.shutdown) {
+      try {
+        await engine.shutdown();
+      } catch (_) {
+        // best-effort
+      }
+    }
+    process.exit(0);
+  }
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
   return server;
 }

package/src/commands/a2a.js

@@ -1,4 +1,6 @@
 import { startA2AServer } from "../a2a/server.js";
+import { error } from "../utils/style.js";
+import { parsePort } from "../utils/validate.js";
 
 export function registerA2A(program) {
   program
@@ -6,7 +8,12 @@ export function registerA2A(program) {
     .description("Start the A2A (Agent-to-Agent) protocol server")
     .option("-p, --port <port>", "Port to listen on", "3000")
     .action((opts) => {
-      const port = parseInt(opts.port, 10);
-      startA2AServer(port);
+      try {
+        const port = parsePort(opts.port, "--port");
+        startA2AServer(port);
+      } catch (err) {
+        error(err.message);
+        process.exitCode = 1;
+      }
     });
 }

package/src/commands/delete.js

@@ -0,0 +1,20 @@
+import { createEngine } from "../core/engine.js";
+import { success, error } from "../utils/style.js";
+
+export function registerDelete(program) {
+  program
+    .command("delete")
+    .description("Delete a memory entry by ID")
+    .argument("<id>", "UUID of the memory entry to delete")
+    .action(async (id) => {
+      try {
+        const engine = createEngine();
+        await engine.delete(id);
+        success(`Deleted: ${id}`);
+        await engine.shutdown();
+      } catch (err) {
+        error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/export.js

@@ -1,6 +1,7 @@
 import { writeFileSync } from "fs";
 import { createEngine } from "../core/engine.js";
 import { success, error } from "../utils/style.js";
+import { parsePositiveInt } from "../utils/validate.js";
 
 export function registerExport(program) {
   program
@@ -15,7 +16,7 @@ export function registerExport(program) {
         const engine = createEngine();
         const listOpts = {};
         if (opts.namespace) listOpts.namespace = opts.namespace;
-        if (opts.limit) listOpts.limit = parseInt(opts.limit, 10);
+        if (opts.limit) listOpts.limit = parsePositiveInt(opts.limit, "--limit");
         listOpts.includeEmbeddings = opts.embeddings !== false ? false : false;
         // --no-embeddings sets opts.embeddings = false (commander negatable)
         // default: exclude embeddings for smaller output

package/src/commands/import.js

@@ -1,4 +1,4 @@
-import { readFileSync } from "fs";
+import { readFileSync, existsSync } from "fs";
 import { createEngine } from "../core/engine.js";
 import { success, error, info, warn } from "../utils/style.js";
 
@@ -11,6 +11,11 @@ export function registerImport(program) {
     .option("--dry-run", "Parse and validate without storing")
     .action(async (file, opts) => {
       try {
+        if (!existsSync(file)) {
+          error(`File not found: ${file}`);
+          process.exitCode = 1;
+          return;
+        }
         const raw = readFileSync(file, "utf8");
         const lines = raw
           .split("\n")
@@ -27,7 +32,7 @@ export function registerImport(program) {
         for (let i = 0; i < lines.length; i++) {
           try {
             entries.push(JSON.parse(lines[i]));
-          } catch {
+          } catch (_) {
             warn(`Skipping invalid JSON on line ${i + 1}`);
           }
         }

package/src/commands/search.js

@@ -2,6 +2,7 @@ import chalk from "chalk";
 import Table from "cli-table3";
 import { createEngine } from "../core/engine.js";
 import { error, heading } from "../utils/style.js";
+import { parsePositiveInt, parseScore } from "../utils/validate.js";
 
 export function registerSearch(program) {
   program
@@ -23,13 +24,13 @@ export function registerSearch(program) {
         const engine = createEngine();
 
         const query = { text: queryText };
-        query.limit = parseInt(opts.limit, 10);
+        query.limit = parsePositiveInt(opts.limit, "--limit");
         if (opts.namespace) query.namespace = opts.namespace;
-        if (opts.timeStart) query.timeStart = parseInt(opts.timeStart, 10);
-        if (opts.timeEnd) query.timeEnd = parseInt(opts.timeEnd, 10);
-        if (opts.cluster) query.clusterId = parseInt(opts.cluster, 10);
-        if (opts.followLinks) query.maxHops = parseInt(opts.followLinks, 10);
-        if (opts.minScore) query.minScore = parseFloat(opts.minScore);
+        if (opts.timeStart) query.timeStart = parsePositiveInt(opts.timeStart, "--time-start");
+        if (opts.timeEnd) query.timeEnd = parsePositiveInt(opts.timeEnd, "--time-end");
+        if (opts.cluster) query.clusterId = parsePositiveInt(opts.cluster, "--cluster");
+        if (opts.followLinks) query.maxHops = parsePositiveInt(opts.followLinks, "--follow-links");
+        if (opts.minScore) query.minScore = parseScore(opts.minScore, "--min-score");
         if (opts.explain) query.withExplanation = true;
         if (opts.excludeSuperseded) query.excludeSuperseded = true;
 

package/src/commands/store.js

@@ -1,5 +1,6 @@
 import { createEngine, loadConfig, saveConfig } from "../core/engine.js";
 import { success, error, info, warn } from "../utils/style.js";
+import { parsePositiveInt } from "../utils/validate.js";
 
 export function registerStore(program) {
   program
@@ -17,7 +18,7 @@ export function registerStore(program) {
         if (opts.namespace) options.namespace = opts.namespace;
         if (opts.session) options.sessionId = opts.session;
         if (opts.tags) options.tags = opts.tags.split(",").map((t) => t.trim());
-        if (opts.ttl) options.ttlSeconds = parseInt(opts.ttl, 10);
+        if (opts.ttl) options.ttlSeconds = parsePositiveInt(opts.ttl, "--ttl");
 
         // Model versioning check
         const currentModelId = engine.modelId();

package/src/core/engine.js

@@ -26,7 +26,7 @@ export function loadConfig() {
   if (existsSync(CONFIG_PATH)) {
     try {
       config = { ...config, ...JSON.parse(readFileSync(CONFIG_PATH, "utf8")) };
-    } catch {
+    } catch (_) {
       // keep defaults
     }
   }

package/src/core/retry.js

@@ -0,0 +1,49 @@
+import { logger } from "../utils/logger.js";
+
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BACKOFF_MS = [500, 1000, 2000];
+
+/**
+ * Create an engine with retry and exponential backoff.
+ * Intended for long-running servers (MCP, A2A) — not for one-shot CLI commands.
+ *
+ * @param {Function} factory - Function that creates the engine (e.g., createEngine)
+ * @param {object} [options]
+ * @param {number} [options.maxRetries=3]
+ * @param {number[]} [options.backoffMs=[500,1000,2000]]
+ * @returns {Promise<object>} The created engine
+ */
+export async function createEngineWithRetry(factory, options = {}) {
+  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const backoffs = options.backoffMs ?? DEFAULT_BACKOFF_MS;
+
+  let lastError;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const engine = factory();
+      if (attempt > 0) {
+        logger.info(`Engine connected after ${attempt + 1} attempts`);
+      }
+      return engine;
+    } catch (err) {
+      lastError = err;
+      if (attempt < maxRetries) {
+        const delay = backoffs[Math.min(attempt, backoffs.length - 1)];
+        logger.warn(
+          `Engine connection failed (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms`,
+          {
+            error: err.message,
+          },
+        );
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  logger.error(`Engine connection failed after ${maxRetries + 1} attempts`, {
+    error: lastError.message,
+    hint: "Is Qdrant running? Try: shabti config setup --check",
+  });
+  throw lastError;
+}

package/src/index.js

@@ -15,6 +15,7 @@ import { registerStatus } from "./commands/status.js";
 import { registerExport } from "./commands/export.js";
 import { registerImport } from "./commands/import.js";
 import { registerStore } from "./commands/store.js";
+import { registerDelete } from "./commands/delete.js";
 
 const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 
@@ -84,6 +85,7 @@ function buildProgram() {
   registerExport(program);
   registerImport(program);
   registerStore(program);
+  registerDelete(program);
 
   program
     .command("gc")

package/src/mcp/server.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { createInterface } from "readline";
 import { createEngine, loadConfig } from "../core/engine.js";
+import { createEngineWithRetry } from "../core/retry.js";
+import { logger } from "../utils/logger.js";
 
 const SERVER_INFO = {
   name: "shabti-memory",
@@ -123,11 +125,22 @@ let engineInitAttempted = false;
 function initEngine() {
   if (engine) return engine;
   if (engineInitAttempted) return null;
+  // Synchronous fallback for initial attempt
   engineInitAttempted = true;
   try {
     engine = createEngine();
-  } catch {
-    // engine stays null — tools will return errors
+    logger.info("Engine initialized");
+  } catch (err) {
+    logger.warn("Engine not available, starting background retry", { error: err.message });
+    // Start async retry in background
+    createEngineWithRetry(createEngine)
+      .then((eng) => {
+        engine = eng;
+        logger.info("Engine connected via retry");
+      })
+      .catch(() => {
+        logger.error("Engine retry exhausted — tools will return errors");
+      });
   }
   return engine;
 }
@@ -415,7 +428,7 @@ async function handleRequest(line) {
   let req;
   try {
     req = JSON.parse(line);
-  } catch {
+  } catch (_) {
     return respondError(null, -32700, "Parse error");
   }
 
@@ -445,4 +458,20 @@ rl.on("line", (line) => {
   const trimmed = line.trim();
   if (trimmed) handleRequest(trimmed);
 });
-rl.on("close", () => process.exit(0));
+
+async function shutdown() {
+  logger.info("MCP server shutting down");
+  rl.close();
+  if (engine && engine.shutdown) {
+    try {
+      await engine.shutdown();
+    } catch (_) {
+      // best-effort
+    }
+  }
+  process.exit(0);
+}
+
+rl.on("close", shutdown);
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/src/repl/index.js

@@ -26,7 +26,7 @@ export async function launchRepl() {
     info(
       `Memory engine connected (${chalk.cyan("/remember")}, ${chalk.cyan("/recall")} available)`,
     );
-  } catch {
+  } catch (_) {
     warn("Memory engine not available. Chat-only mode (start Qdrant to enable memory).");
   }
 

package/src/utils/logger.js

@@ -0,0 +1,40 @@
+const LEVELS = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
+
+function getLevel() {
+  const name = (process.env.SHABTI_LOG_LEVEL || "info").toLowerCase();
+  return LEVELS[name] ?? LEVELS.info;
+}
+
+function isJsonMode() {
+  return process.env.SHABTI_LOG_JSON === "1";
+}
+
+function shouldLog(level) {
+  return LEVELS[level] >= getLevel();
+}
+
+function formatTimestamp() {
+  return new Date().toISOString();
+}
+
+function log(level, message, data) {
+  if (!shouldLog(level)) return;
+
+  if (isJsonMode()) {
+    const entry = { timestamp: formatTimestamp(), level, message };
+    if (data !== undefined) entry.data = data;
+    process.stderr.write(JSON.stringify(entry) + "\n");
+  } else {
+    const prefix = `[${formatTimestamp()}] [${level.toUpperCase()}]`;
+    const msg =
+      data !== undefined ? `${prefix} ${message} ${JSON.stringify(data)}` : `${prefix} ${message}`;
+    process.stderr.write(msg + "\n");
+  }
+}
+
+export const logger = {
+  debug: (message, data) => log("debug", message, data),
+  info: (message, data) => log("info", message, data),
+  warn: (message, data) => log("warn", message, data),
+  error: (message, data) => log("error", message, data),
+};

package/src/utils/validate.js

@@ -0,0 +1,54 @@
+/**
+ * Parse a string as a positive integer. Returns the number or throws.
+ */
+export function parsePositiveInt(value, name) {
+  const n = parseInt(value, 10);
+  if (isNaN(n) || n <= 0) {
+    throw new Error(`${name} must be a positive integer, got: ${value}`);
+  }
+  return n;
+}
+
+/**
+ * Parse a string as a non-negative integer (>= 0). Returns the number or throws.
+ */
+export function parseNonNegativeInt(value, name) {
+  const n = parseInt(value, 10);
+  if (isNaN(n) || n < 0) {
+    throw new Error(`${name} must be a non-negative integer, got: ${value}`);
+  }
+  return n;
+}
+
+/**
+ * Parse a string as a positive float. Returns the number or throws.
+ */
+export function parsePositiveFloat(value, name) {
+  const n = parseFloat(value);
+  if (isNaN(n) || n <= 0) {
+    throw new Error(`${name} must be a positive number, got: ${value}`);
+  }
+  return n;
+}
+
+/**
+ * Parse a string as a float in [0, 1]. Returns the number or throws.
+ */
+export function parseScore(value, name) {
+  const n = parseFloat(value);
+  if (isNaN(n) || n < 0 || n > 1) {
+    throw new Error(`${name} must be a number between 0 and 1, got: ${value}`);
+  }
+  return n;
+}
+
+/**
+ * Parse a string as a valid TCP port (1–65535). Returns the number or throws.
+ */
+export function parsePort(value, name) {
+  const n = parseInt(value, 10);
+  if (isNaN(n) || n < 1 || n > 65535) {
+    throw new Error(`${name} must be a port number (1–65535), got: ${value}`);
+  }
+  return n;
+}