stateful-mcp 0.1.1

package/docs/filter.md

@@ -0,0 +1,32 @@
+# Filter Service Reference Guide
+
+The Filter Service provides an incremental, version-controlled builder for database query clauses. This allows client LLMs to construct and tweak complex SQL conditions across multiple turns.
+
+---
+
+## 1. Decoupling Public Filters from Database Columns
+
+A core design principle of the Filter Service is that **the client LLM should not know the internal database table structure or column names**. Instead, the LLM queries against logical, public-facing attribute definitions.
+
+The **Translation Layer** maps these public queries into database column targets dynamically:
+* Public attribute `email` maps to internal column `contact_email_address`.
+* Public operator `is` maps to relational comparison `eq`.
+* This decoupling allows database schemas to evolve (e.g. renaming columns, migrating tables) without breaking the LLM's client-facing tool configuration.
+
+For full translation step mapping and compiler capabilities, refer to [docs/pipeline.md](file:///home/denny/lu/filter/docs/pipeline.md).
+
+---
+
+## 2. Version-Controlled Query Lifecycle
+
+Every mutation on a filter creates a new, immutable state node (commit) tracked in the session's DAG:
+* **`filter_init`**: Starts a root node specifying target tool/table and optional default conditions.
+* **`filter_add`**: Appends logical clauses (`AND`/`OR`) and returns a new version ID.
+* **`filter_inspect`**: Displays the active rules and compiled SQL representation at a specific version.
+* **`filter_compress`**: Flattens a linear chain of version nodes to reduce session storage overhead.
+
+---
+
+## 3. Supported Dialects
+* **SQLite**: Parameters are bound using index numbering (`?`).
+* **PostgreSQL**: Parameters are compiled using position notation (`$1`, `$2`), and nested path syntax is compiled into JSONB arrow access operators (e.g. `metadata->>'status'`).

package/docs/log.md

@@ -0,0 +1,54 @@
+# Log Service Reference Guide
+
+The Log Service is a read-only history walker over the versioned state created by the Filter and Object services. Where those services *build* checkpointed state, the Log Service *traverses* it — letting you page backward through a filter or object's ancestry (the parent-pointer DAG) to inspect how it evolved, one checkpoint at a time.
+
+It is intentionally separate from the Event Service: the Event Service manages an append-only array of structured records, whereas the Log Service replays the lineage of a single filter or object and surfaces the forward/backward deltas between checkpoints.
+
+---
+
+## 1. Stateful Traversal (not stateful mutation)
+
+Unlike the other services, the Log Service holds **no state of its own**. It reads the session stores of the Filter and Object services (`filter_session_state` / `object_session_state`) that are already configured in `storage.config.json`. This means it can only walk history that still exists in the session — running `filter_gc` / `object_gc` will prune the very checkpoints the Log Service would otherwise traverse.
+
+---
+
+## 2. Tools
+
+### `log_open`
+Begins a traversal from a starting filter or object ID/alias and returns the first page of history.
+
+* **`type`**: `"filter"` or `"object"` — which store to walk.
+* **`session_id`**: The session whose checkpoints you want to inspect.
+* **`id_or_alias`**: The starting checkpoint (typically the current tip, or a named alias).
+* **`limit`**: Page size (default `5`).
+
+The response contains:
+* **`entries`**: Ordered from the starting checkpoint back toward the root.
+  * For **filters**: each entry carries `{ id, parent_id, created_at, rules }` — `rules` is the *delta* (`add`/`remove`) recorded at that checkpoint.
+  * For **objects**: each entry carries `{ id, parent_id, created_at, delta }` — `delta` is the sparse set of keys that changed relative to the checkpoint's parent (computed by diffing the parent's data).
+* **`next_page_token`**: A signed, stateless token to fetch the next page, or `null` when the root is reached.
+* **`has_more`**: Convenience boolean mirroring whether `next_page_token` is present.
+
+### `log_next`
+Fetches the next page using a previously returned `next_page_token`. It takes a single argument, **`page_token`**, and returns the same `{ entries, next_page_token, has_more }` shape as `log_open`. Replaying tokens walks further back up the parent chain until `next_page_token` is `null`.
+
+---
+
+## 3. The Page Token (stateless pagination)
+
+Pagination is driven by a cryptographically signed token rather than server-side cursor state:
+
+* The token wraps the current position (`type`, `sessionId`, `currentNodeId`, `pageSize`, optional `userId`).
+* It is signed with HMAC-SHA256 using `LOG_SERVICE_SECRET` (set this env var for stable tokens across restarts; otherwise a random secret is generated on startup).
+* On `log_next`, the signature is verified before the token is trusted. A tampered or forged token is rejected.
+
+Because the token is self-contained, the Log Service remains stateless — no traversal session lives on the server between calls.
+
+---
+
+## 4. Practical Notes
+
+* **Direction**: History flows from the newest checkpoint (the one you pass to `log_open`) toward the oldest (the root with `parent_id: null`).
+* **Filter deltas**: `rules` is the per-checkpoint change set, not the full accumulated filter. To see the fully projected filter at any checkpoint, use `filter_get_filter` on that `id`.
+* **Object deltas**: `delta` shows only the keys that differ from the parent; the full object at any checkpoint can be retrieved with `object_get` / `object_inspect`.
+* **No write path**: `log_open` / `log_next` are strictly read-only by design — they never create, mutate, or compress checkpoints.

package/docs/object.md

@@ -0,0 +1,29 @@
+# Object Service Reference Guide
+
+The Object Service manages structured JSON documents (e.g. order forms, medical prescriptions, patient SOAP notes) with stateful delta tracking and strict validation guards.
+
+---
+
+## 1. Stateful Object Lifecycle
+
+* **`object_init`**: Instantiates a new empty object or pre-populates it with initial data matching a registered schema.
+* **`object_patch`**: Applies a sparse JSON patch delta on an existing object ID, returning a new immutable checkpoint.
+* **`object_validate`**: Runs the object through the Ajv compiler and cross-field constraint validator, returning a structured list of errors and warnings.
+* **`object_resolve`**: Finalizes the object. Resolves recursive lazy reference links (e.g. referencing other entities or variables) and returns the complete, resolved document.
+
+---
+
+## 2. Validation & Schema Guards
+
+* **JSON Schema validation**: Checked via Ajv at each checkpoint.
+* **Cross-Field constraints**: Custom rules like ensuring `start_date < end_date` or verifying ranges.
+* **Cycle detection**: Ensures lazy reference links do not form recursive loops.
+* **Schema guard**: Comparing two object versions with differing schemas throws a `SCHEMA_MISMATCH` error.
+
+---
+
+## 3. Template Loading (`from_saved`)
+
+To reduce token overhead on repeated document creation, the Object Service supports loading saved templates:
+* Templates can be saved to persistent storage.
+* Call `object_from_saved(template_id)` to clone a pre-populated baseline state, allowing the LLM to only patch the specific fields that differ for the current transaction.

package/docs/pipeline.md

@@ -0,0 +1,116 @@
+# Query Compilation & Translation Pipeline
+
+This document explains how user-defined query filters are translated and compiled into execution-ready database commands (SQLite/Postgres).
+
+---
+
+## 1. The Pipeline Flow
+
+```
+┌─────────────────┐
+│ Filter State ID │ (VCS Commit Node)
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ project() State │ (Topological project of all rules)
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ translate()     │ (Dynamic dialect field & operator mapping)
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ compile()       │ (SQL generator: Postgres / SQLite)
+└─────────────────┘
+```
+
+---
+
+## 2. Dynamic Translation Mapping (`translation`)
+
+The `translation` property on a tool defines how user-supplied field identifiers and operators are preprocessed before being passed to the SQL generator.
+
+### Example Translation Schema
+A translation map is configured using the `TableTranslation` schema structure under `properties`:
+
+```json
+{
+  "properties": {
+    "customer_name": {
+      "internal": "billing_name",
+      "allowed_operators": ["eq", "neq"]
+    },
+    "age": {
+      "internal": "birth_date",
+      "transform": {
+        "pipeline": [
+          {
+            "op": "date_diff",
+            "args": [{ "$init": "value" }, { "$fn": "now" }],
+            "return_var": "calculated_age"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+* **`internal`**: Maps the public field name (e.g. `customer_name`) to its internal database column (e.g. `billing_name`).
+* **`allowed_operators`**: Narrows down which operator families can be queried on the field (e.g. only allowing `eq` and `neq` on name fields).
+* **`transform`**: Defines pipeline conversion steps using arithmetic, date, or nested JSON operations to transform values dynamically before compilation.
+* **`$fn` Reference**: Represents dynamic system values evaluated at run time:
+  - `{ "$fn": "now" }`: Resolves to the current date string (`YYYY-MM-DD`). Compiles to `date('now')` in SQLite and `CURRENT_DATE` in PostgreSQL.
+  - `{ "$fn": "utc_time" }`: Resolves to the current UTC timestamp string (`ISO 8601`). Compiles to `datetime('now')` in SQLite and `CURRENT_TIMESTAMP` in PostgreSQL.
+
+---
+
+## 3. SQL Compilation Engines
+
+The middleware compiles the final logical state into target database dialects:
+
+### SQLite Engine
+* Compiles logical operations (e.g. `like`, `geq`) to standard ANSI SQL parameters.
+* Validates properties against the registered `table_schemas` in `tools.config.json` before execution.
+
+### PostgreSQL Engine
+* Generates dialect-safe parameterized SQL (`$1`, `$2`, etc.) to prevent SQL injection.
+* Supports nested JSONB path queries (e.g. `meta->>'source'`) automatically.
+
+---
+
+## 4. Available Pipeline Operators (`OpName`)
+
+The following operators can be used within translation pipelines. They are categorized by family:
+
+### Arithmetic Operations
+Used to modify or combine numeric field values.
+* **`add`**: Sums two numbers. E.g. `{ "op": "add", "args": [{ "$init": "value" }, 10] }`
+* **`sub`**: Subtracts second argument from first.
+* **`mul`**: Multiplies two numbers.
+* **`div`**: Divides first argument by second.
+* **`mod`**: Modulo arithmetic (remainder).
+* **`exp`**: Exponential power ($x^y$).
+
+### Comparison Operations
+Performs boolean comparisons.
+* **`lt`** ($<$), **`leq`** ($\le$), **`eq`** ($=$), **`neq`** ($\ne$), **`geq`** ($\ge$), **`gt`** ($>$).
+* E.g. `{ "op": "gt", "args": [{ "$init": "value" }, 100] }`
+
+### Date Operations
+Parses and extracts calendar details from ISO date strings.
+* **`year`**: Extracts year. E.g. `{ "op": "year", "args": [{ "$init": "value" }] }` (returns e.g. `2026`).
+* **`month`**: Extracts month index (`1` to `12`).
+* **`day`**: Extracts calendar day of the month (`1` to `31`).
+* **`quarter`**: Extracts quarter index (`1` to `4`).
+* **`date_diff`**: Days between two dates. E.g. `{ "op": "date_diff", "args": [{ "$init": "value" }, { "$fn": "now" }] }`
+
+### Nested Access & JSON Operations
+Allows parsing and exploring nested JSON structures.
+* **`json_parse`**: Deserializes a raw JSON string into a structured object.
+* **`get`**: Accesses a property at a specific key path on an object.
+  * E.g. `{ "op": "get", "args": [{ "$var": "parsed_object" }, "metadata", "authors", 0] }`
+

package/docs/resource_types.md

@@ -0,0 +1,138 @@
+# Resource Locators & Database Specifications
+
+This document outlines the detailed specifications for `ResourceLocator` parameters and the database schema fields required when configuring SQLite or PostgreSQL storage backends.
+
+---
+
+## 1. Resource Locator Types (`ResourceLocator`)
+
+### 1.1 `file`
+Loads JSON or text assets directly from the local filesystem.
+* **Fields**:
+  * `path` (string, required): Filesystem path relative to the workspace root.
+* **Example**:
+  ```json
+  { "_type": "file", "path": "config/pharmacy_dictionary.json" }
+  ```
+
+### 1.2 `remote_url`
+Fetches configuration or constants over HTTP/HTTPS.
+* **Fields**:
+  * `url` (string, required): The target endpoint.
+  * `headers` (object, optional): Map of headers (e.g. `Authorization`, `Accept`).
+  * `ttl_ms` (number, optional): Time-to-live caching interval in milliseconds.
+* **Variable Substitutions**:
+  * **Boot-Time (Environment Variables)**: Any string prefixing `env:` (e.g. `env:DATABASE_URL`) anywhere in the configuration is substituted with the value of the environment variable at server startup.
+  * **Runtime (Contextual Variables)**: Any bracketed template placeholder `{variableName}` (e.g., `{userId}`, `{department}`, `{employeeId}`) is replaced dynamically at runtime on a per-request basis with the caller's contextual parameters. The parser replaces the brackets and variable names with URL-encoded parameters supplied by the client's request context. This replacement is supported in both the `url` property of `remote_url` and the `path` property of `file` locators. E.g., `"path": "config/{department}/constants.json"`.
+* **Example**:
+  ```json
+  {
+    "_type": "remote_url",
+    "url": "https://api.firm.internal/users/{userId}/constants",
+    "headers": { "Authorization": "Bearer token123" },
+    "ttl_ms": 600000
+  }
+  ```
+
+### 1.3 `adapter`
+Instantiates registered database storage repositories.
+* **Fields**:
+  * `name` (string, required): Name of the adapter (`"sqlite"` or `"postgres"`).
+  * `options` (object, required): Connection parameters:
+    * `url` (string, required): Connection URL (e.g. `sqlite://data/filter_sessions.db` or `postgresql://user:pass@localhost:5432/dbname`).
+* **Example**:
+  ```json
+  {
+    "_type": "adapter",
+    "name": "sqlite",
+    "options": { "url": "sqlite://data/filter_sessions.db" }
+  }
+  ```
+
+### 1.4 Behavior on Stateful vs. Read-Only Services
+
+The middleware treats resource locators differently depending on whether the service requires write operations (stateful) or is read-only:
+
+#### A. Read-Only & Configuration Services (Schemas, Dictionaries, Constants)
+* **How it works**: These can be configured using `file` or `remote_url` locators. The middleware fetches or reads the entire asset at startup (or after TTL expires) and holds it in memory for instant lookups.
+* **JSON/JSONL Support**: You can point a `file` locator to a static JSON ontology file for the Dictionary Service.
+
+#### B. Stateful & Transactional Services (Filter conditions, Object states, Event logs)
+* **How it works**: Stateful services require transactional mutation logic, branch merges, LCA graph traversals, and targeted garbage collection. Because of this complexity, they **require a database adapter** (`sqlite` or `postgres`).
+* **Fallback Behavior**: If you configure a stateful service using a standard `.json` `file` or `remote_url` locator directly, the service falls back to its **in-memory storage engine**.
+* **Special Case: JSONL Files (`.jsonl`)**: If a stateful service `file` locator points to a `.jsonl` file, the middleware treats it as a **built-in append-only file database**:
+  * **Schema**: Each line in the `.jsonl` file is a single JSON-serialized object matching the exact column keys defined in Section 2 (e.g. `commitId`, `parentCommitId`, `mutations`).
+  * **Startup Read**: On server initialization, the service reads the `.jsonl` file line-by-line to reconstruct the commit DAG in memory.
+  * **Mutations**: Any new checkpoint or commit appends a new serialized JSON line to the file.
+  * **GC/Compression**: When garbage collection or compression runs, the system rewrites the `.jsonl` file containing only the survived/flattened commits to prevent file size bloat.
+* **Custom File/HTTP Backends**: To save stateful commits to other formats, you must write a custom storage adapter class (implementing the store interfaces in `src/adapters/storage/interfaces.ts`) and register it under a custom name via `registerAdapter`.
+
+---
+
+## 2. Database Schema Specifications
+
+When utilizing `sqlite` or `postgres` storage adapters, the databases must implement the following structures. Columns storing arrays or objects must map to `TEXT` (JSON-serialized strings) in SQLite, and `JSONB` in PostgreSQL.
+
+### 2.1 Filter VCS Tables
+
+#### Table: `filter_conditions`
+Stores logical condition nodes in the query builder DAG.
+* **`filterId`** (VARCHAR/TEXT, Primary Key): Unique checkpoint node ID.
+* **`parentFilterId`** (VARCHAR/TEXT, Nullable): Parent checkpoint ID.
+* **`toolName`** (VARCHAR/TEXT): Target tool name.
+* **`tableName`** (VARCHAR/TEXT): Target table name.
+* **`rules`** (JSON/TEXT): Array of serialized conditions.
+* **`schema_snapshot`** (JSON/TEXT, Nullable): JSON schema copy at checkpoint time.
+* **`linearDepth`** (INTEGER): Distance from nearest branch or root.
+* **`gcLock`** (BOOLEAN): If true, prevents pruning during GC.
+* **`createdAt`** (TIMESTAMP/TEXT): Creation timestamp.
+
+#### Table: `filter_aliases`
+* **`sessionId`** (VARCHAR/TEXT): Active session.
+* **`alias`** (VARCHAR/TEXT): Shorthand descriptor (e.g. `"main"`).
+* **`targetId`** (VARCHAR/TEXT): Pointed commit node ID.
+* *Composite Primary Key*: `(sessionId, alias)`
+
+---
+
+### 2.2 Object VCS Tables
+
+#### Table: `object_states`
+Stores structured document checkpoints.
+* **`objectId`** (VARCHAR/TEXT, Primary Key): Unique object version ID.
+* **`parentObjectId`** (VARCHAR/TEXT, Nullable): Parent object version ID.
+* **`schemaName`** (VARCHAR/TEXT): Schema validator identifier.
+* **`data`** (JSON/TEXT): Key-value properties of the object.
+* **`linearDepth`** (INTEGER): Node chain depth.
+* **`gcLock`** (BOOLEAN): Lock status.
+* **`createdAt`** (TIMESTAMP/TEXT): Timestamp.
+
+#### Table: `object_aliases`
+* **`sessionId`** (VARCHAR/TEXT)
+* **`alias`** (VARCHAR/TEXT)
+* **`targetId`** (VARCHAR/TEXT)
+* *Composite Primary Key*: `(sessionId, alias)`
+
+---
+
+### 2.3 Event VCS Tables
+
+#### Table: `event_commits`
+Stores VCS commits representing mutations on event logs.
+* **`commitId`** (VARCHAR/TEXT, Primary Key): Unique commit ID.
+* **`parentCommitId`** (VARCHAR/TEXT, Nullable): Parent commit ID.
+* **`sessionId`** (VARCHAR/TEXT): Associated session.
+* **`operation`** (VARCHAR/TEXT): Mutation type (`"add"`, `"update"`, `"remove"`, `"merge"`).
+* **`mutations`** (JSON/TEXT): Array of mutations (detailing `event_id`, `before_data`, `data`, and `mutation_parent_ids`).
+* **`mergeSourceCommitIds`** (JSON/TEXT, Nullable): Array of source merge parent IDs.
+* **`mergeAcceptedIds`** (JSON/TEXT, Nullable): Array of accepted resolutions.
+* **`mergeRejectedIds`** (JSON/TEXT, Nullable): Array of rejected resolutions.
+* **`linearDepth`** (INTEGER): Depth.
+* **`gcLock`** (BOOLEAN): Lock status.
+* **`createdAt`** (TIMESTAMP/TEXT): Timestamp.
+
+#### Table: `event_aliases`
+* **`sessionId`** (VARCHAR/TEXT)
+* **`alias`** (VARCHAR/TEXT)
+* **`targetId`** (VARCHAR/TEXT)
+* *Composite Primary Key*: `(sessionId, alias)`

package/docs/validation_examples.md

@@ -0,0 +1,230 @@
+# Validation Engine Examples
+
+The `validation_engine` parameter in `tools.config.json` points to an external JSON Schema or Ajv configuration file to enforce advanced logic constraints on public filter inputs before they hit database compilation.
+
+---
+
+## Example 1: Drug Dosage Threshold Restrictions (JSON Schema)
+This validation file enforces that when querying pharmacy databases for controlled narcotics, the dosage or quantity filtered must not exceed strict medical limits.
+
+### Configuration (`config/tools.config.json`)
+```json
+{
+  "tools": {
+    "dispense_medication": {
+      "schema": { "_type": "file", "path": "schemas/dispense.json" },
+      "validation_engine": { "_type": "file", "path": "validators/dispense_rules.json" },
+      "engine": { "_type": "adapter", "name": "postgres", "options": { "url": "env:DATABASE_URL" } }
+    }
+  }
+}
+```
+
+### Validator File (`validators/dispense_rules.json`)
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Narcotics Dosage Guard",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "properties": {
+      "property": { "type": "string" },
+      "operator": { "type": "string" },
+      "value": { "type": "any" }
+    },
+    "allOf": [
+      {
+        "if": {
+          "properties": {
+            "property": { "const": "qty" },
+            "operator": { "enum": ["eq", "gt", "geq"] }
+          }
+        },
+        "then": {
+          "properties": {
+            "value": {
+              "type": "number",
+              "maximum": 120,
+              "description": "Controlled narcotics dispense limit exceeded (Max: 120 units)"
+            }
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Example 2: Allowed Date Range Constraints (JSON Schema)
+Enforces constraints ensuring start/end date ranges in transaction history queries are within a maximum period (e.g., no queries spanning more than 90 days).
+
+### Validator File (`validators/date_range_rules.json`)
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "90-Day Transaction Query Guard",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "properties": {
+      "property": { "type": "string" },
+      "operator": { "type": "string" },
+      "value": { "type": "any" }
+    },
+    "allOf": [
+      {
+        "if": {
+          "properties": {
+            "property": { "const": "transaction_date" },
+            "operator": { "const": "between" }
+          }
+        },
+        "then": {
+          "properties": {
+            "value": {
+              "type": "array",
+              "minItems": 2,
+              "maxItems": 2,
+              "items": { "type": "string", "format": "date-time" }
+            }
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Example 3: External API Validator (Remote Schema URL)
+If the validation schema is hosted remotely (e.g., an internal hospital compliance API), the system fetches it dynamically using a `remote_url` locator.
+
+### Configuration (`config/tools.config.json`)
+```json
+{
+  "tools": {
+    "dispense_medication": {
+      "schema": { "_type": "file", "path": "schemas/dispense.json" },
+      "validation_engine": {
+        "_type": "remote_url",
+        "url": "https://compliance.hospital.org/api/v1/narcotics-schema",
+        "headers": { "Authorization": "Bearer env:API_TOKEN" }
+      },
+      "engine": { "_type": "adapter", "name": "postgres", "options": { "url": "env:DATABASE_URL" } }
+    }
+  }
+}
+```
+
+### Request & Response Payloads
+When the filter is initialized or modified, the middleware sends a POST request to the `url` endpoint with the following payload structure:
+
+#### POST Request Body
+```json
+{
+  "toolName": "dispense_medication",
+  "tableName": "prescriptions",
+  "rules": [
+    {
+      "property": "qty",
+      "operator": "gt",
+      "value": 150
+    }
+  ]
+}
+```
+
+#### Expected JSON Response (Success)
+```json
+{
+  "valid": true
+}
+```
+
+#### Expected JSON Response (Validation Failure)
+```json
+{
+  "valid": false,
+  "errors": [
+    "Controlled narcotics dispense limit exceeded (Max: 120 units)"
+  ]
+}
+```
+
+---
+
+## Example 4: Custom Validation Script Execution (Custom Adapter)
+For complex validation logic (e.g., verifying a patient's active status via an external script), register a custom validation adapter factory that executes a script subprocess:
+
+### Configuration (`config/tools.config.json`)
+```json
+{
+  "tools": {
+    "dispense_medication": {
+      "schema": { "_type": "file", "path": "schemas/dispense.json" },
+      "validation_engine": {
+        "_type": "adapter",
+        "name": "script_validator",
+        "options": {
+          "script_path": "scripts/validate_narcotic_limits.js",
+          "runtime_path": "node"
+        }
+      },
+      "engine": { "_type": "adapter", "name": "postgres", "options": { "url": "env:DATABASE_URL" } }
+    }
+  }
+}
+```
+
+### Script Validator Factory Registration (`src/adapters/validators/script-validator.ts`)
+
+> [!WARNING]
+> Do **not** use `spawnSync` here. It blocks the entire Node.js event loop for the duration of the subprocess, freezing the MCP server for all concurrent requests. Use async `spawn` with a promise wrapper instead.
+
+```typescript
+import { registerAdapter } from "@stateful-mcp/loader";
+import { spawn } from "child_process";
+
+/** Wraps child_process.spawn as a non-blocking promise. */
+function runScript(runtime: string, script: string, stdinPayload: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(runtime, [script], { stdio: ["pipe", "pipe", "pipe"] });
+
+    let stdout = "";
+    let stderr = "";
+
+    proc.stdout.on("data", (chunk) => { stdout += chunk; });
+    proc.stderr.on("data", (chunk) => { stderr += chunk; });
+
+    proc.on("close", (code) => {
+      if (code !== 0) reject(new Error(`Validator script exited ${code}: ${stderr.trim()}`));
+      else resolve(stdout);
+    });
+
+    proc.on("error", reject);
+
+    proc.stdin.write(stdinPayload);
+    proc.stdin.end();
+  });
+}
+
+registerAdapter("script_validator", {
+  create: async (options) => {
+    return {
+      validate: async (rules: any[]) => {
+        const script = String(options.script_path);
+        const runtime = String(options.runtime_path || "node");
+
+        // Pass rules as JSON via stdin — non-blocking, event loop stays free
+        const output = await runScript(runtime, script, JSON.stringify(rules));
+        return JSON.parse(output); // Expected: { valid: true } or { valid: false, errors: [...] }
+      }
+    };
+  }
+});
+```
+