@synapsor/runner 0.1.0-alpha.0 → 0.1.0-alpha.2

package/docs/writeback-executors.md

@@ -0,0 +1,128 @@
+# Writeback Executors
+
+Synapsor Runner separates proposal authority from execution authority.
+
+The model-facing MCP server can inspect and propose. It cannot approve or
+commit. After a human or trusted process approves a proposal, the local runner
+uses a configured writeback executor.
+
+## `sql_update`
+
+`sql_update` is the default executor.
+
+It applies one guarded `UPDATE` through the database adapter:
+
+- fixed schema/table from reviewed config;
+- fixed primary key column;
+- tenant guard;
+- allowed-column validation;
+- conflict/version guard;
+- idempotency key;
+- affected-row check;
+- terminal receipt in replay.
+
+Use this when the trusted runner is allowed to update the selected business row
+directly.
+
+## `http_handler`
+
+Use `http_handler` when your application/API should own business execution.
+
+The approved proposal becomes a structured HTTP request to an internal handler.
+The handler URL and bearer token come from environment variables, not config
+literal values.
+
+```json
+{
+  "executors": {
+    "billing_api": {
+      "type": "http_handler",
+      "url_env": "SYNAPSOR_BILLING_HANDLER_URL",
+      "method": "POST",
+      "auth": {
+        "type": "bearer_env",
+        "token_env": "SYNAPSOR_BILLING_HANDLER_TOKEN"
+      },
+      "timeout_ms": 5000
+    }
+  },
+  "capabilities": [
+    {
+      "name": "billing.propose_late_fee_waiver",
+      "kind": "proposal",
+      "executor": "billing_api"
+    }
+  ]
+}
+```
+
+Run after approval:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner apply \
+  --proposal wrp_123 \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+The handler receives proposal fields, the exact patch, evidence metadata,
+guards, and an idempotency key. It does not receive arbitrary model SQL or DB
+credentials from Synapsor Runner.
+
+Handler responses:
+
+```json
+{
+  "status": "applied",
+  "rows_affected": 1,
+  "previous_version": "2026-06-20T14:31:08Z",
+  "new_version": "2026-06-20T14:34:19Z",
+  "source_database_mutated": true
+}
+```
+
+Allowed terminal statuses:
+
+- `applied`
+- `already_applied`
+- `conflict`
+- `failed`
+
+Non-2xx responses and timeouts become failed execution receipts. The terminal
+receipt is stored in replay.
+
+Use your application/API for business logic. Use Synapsor Runner for proposal,
+approval, evidence, policy boundary, and replay.
+
+## `command_handler`
+
+`command_handler` is a local integration path for scripts:
+
+```json
+{
+  "executors": {
+    "local_billing_script": {
+      "type": "command_handler",
+      "command_env": "SYNAPSOR_BILLING_HANDLER_COMMAND",
+      "timeout_ms": 5000
+    }
+  }
+}
+```
+
+The command receives the same structured JSON request on stdin and should print
+a JSON receipt body on stdout.
+
+## Safety Boundary
+
+Executor secrets are never exposed over MCP. The model never receives:
+
+- approval tools;
+- commit tools;
+- write credentials;
+- handler bearer tokens;
+- arbitrary SQL authority;
+- tenant/principal authority.
+
+`MCP tool call = request/proposal authority. Trusted runner = execution
+authority.`

package/examples/dangerous-mcp-tools.json

@@ -0,0 +1,88 @@
+{
+  "tools": [
+    {
+      "name": "execute_sql",
+      "description": "Execute arbitrary SQL against the application database.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "sql": { "type": "string" }
+        },
+        "required": ["sql"]
+      }
+    },
+    {
+      "name": "run_query",
+      "description": "Run any query and return database rows.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": { "type": "string" },
+          "table": { "type": "string" },
+          "columns": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "required": ["query"]
+      }
+    },
+    {
+      "name": "approve_refund",
+      "description": "Approve and issue a customer refund immediately.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "refund_id": { "type": "string" },
+          "tenant_id": { "type": "string" },
+          "amount_cents": { "type": "number" }
+        },
+        "required": ["refund_id", "tenant_id", "amount_cents"]
+      }
+    },
+    {
+      "name": "update_customer",
+      "description": "Update a customer record directly.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "customer_id": { "type": "string" },
+          "tenant_id": { "type": "string" },
+          "column": { "type": "string" },
+          "value": { "type": "string" }
+        },
+        "required": ["customer_id", "tenant_id", "column", "value"]
+      }
+    },
+    {
+      "name": "delete_order",
+      "description": "Delete an order from the database.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "order_id": { "type": "string" },
+          "tenant_id": { "type": "string" }
+        },
+        "required": ["order_id", "tenant_id"]
+      }
+    },
+    {
+      "name": "query_database",
+      "description": "Query arbitrary tables and columns from the database.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "database": { "type": "string" },
+          "schema": { "type": "string" },
+          "table": { "type": "string" },
+          "columns": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "where": { "type": "string" }
+        },
+        "required": ["table"]
+      }
+    }
+  ]
+}

package/examples/reference-support-billing-app/README.md

@@ -0,0 +1,86 @@
+# Reference Support/Billing App
+
+This is the main local reference app for Synapsor Runner.
+
+It shows the commit-safe MCP loop against a disposable Postgres app database:
+
+1. The MCP model sees semantic tools, not `execute_sql`.
+2. Reads are scoped by trusted `SYNAPSOR_TENANT_ID` and `SYNAPSOR_PRINCIPAL`.
+3. Proposal tools create exact diffs and leave the source database unchanged.
+4. Approval happens through the local CLI or UI, outside MCP.
+5. The trusted runner applies one guarded update with tenant, allowed-column, idempotency, and `updated_at` conflict checks.
+6. Replay exports evidence, diff, approval, writeback receipt, and conflict outcome.
+
+The app fixture is split into `schema.sql` and `seed.sql` so the database shape
+and demo data are easy to inspect.
+
+## Start
+
+From the repository root:
+
+```bash
+docker compose -f examples/reference-support-billing-app/docker-compose.yml up -d
+
+export REFERENCE_POSTGRES_READ_URL="postgresql://synapsor_reader:synapsor_reader_password@localhost:55435/synapsor_reference_support_billing"
+export REFERENCE_POSTGRES_WRITE_URL="postgresql://synapsor_writer:synapsor_writer_password@localhost:55435/synapsor_reference_support_billing"
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="local_support_operator"
+```
+
+Or run the complete success/conflict/replay smoke:
+
+```bash
+examples/reference-support-billing-app/scripts/run-demo.sh
+```
+
+Validate the reviewed contract:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner config validate --config examples/reference-support-billing-app/synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --config examples/reference-support-billing-app/synapsor.runner.json
+```
+
+Serve MCP:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve \
+  --config examples/reference-support-billing-app/synapsor.runner.json \
+  --store ./tmp/reference-support-billing/local.db
+```
+
+## Tools
+
+The model-facing MCP tools are:
+
+- `support.inspect_ticket`
+- `support.propose_ticket_resolution`
+- `billing.inspect_invoice`
+- `billing.propose_late_fee_waiver`
+
+The model does not receive approval tools, commit tools, write credentials, raw SQL, arbitrary table names, arbitrary column names, or tenant authority.
+
+## Review And Replay
+
+After a proposal exists:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals list --store ./tmp/reference-support-billing/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals approve <proposal_id> --store ./tmp/reference-support-billing/local.db --actor local_reviewer --yes
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals writeback-job <proposal_id> --store ./tmp/reference-support-billing/local.db --output ./tmp/reference-support-billing/job.json
+npx -y -p @synapsor/runner@alpha synapsor-runner apply --job ./tmp/reference-support-billing/job.json --store ./tmp/reference-support-billing/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner replay export <proposal_id> --store ./tmp/reference-support-billing/local.db --output ./tmp/reference-support-billing/replay.json
+```
+
+To inspect locally in a browser:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner ui \
+  --config examples/reference-support-billing-app/synapsor.runner.json \
+  --store ./tmp/reference-support-billing/local.db
+```
+
+## Stop
+
+```bash
+docker compose -f examples/reference-support-billing-app/docker-compose.yml down -v
+```

package/examples/reference-support-billing-app/docker-compose.yml

@@ -0,0 +1,13 @@
+services:
+  postgres:
+    image: postgres:16
+    container_name: synapsor_runner_reference_support_billing
+    environment:
+      POSTGRES_DB: synapsor_reference_support_billing
+      POSTGRES_USER: synapsor_admin
+      POSTGRES_PASSWORD: synapsor_admin_password
+    ports:
+      - "55435:5432"
+    volumes:
+      - ./schema.sql:/docker-entrypoint-initdb.d/001_schema.sql:ro
+      - ./seed.sql:/docker-entrypoint-initdb.d/002_seed.sql:ro

package/examples/reference-support-billing-app/mcp-client.generic.json

@@ -0,0 +1,11 @@
+{
+  "command": "synapsor",
+  "args": [
+    "mcp",
+    "serve",
+    "--config",
+    "examples/reference-support-billing-app/synapsor.runner.json",
+    "--store",
+    "./tmp/reference-support-billing/local.db"
+  ]
+}

package/examples/reference-support-billing-app/schema.sql

@@ -0,0 +1,55 @@
+CREATE TABLE IF NOT EXISTS public.tenants (
+  id text PRIMARY KEY,
+  name text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.customers (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  name text NOT NULL,
+  email text,
+  plan text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.support_tickets (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  customer_id text NOT NULL REFERENCES public.customers(id),
+  subject text NOT NULL,
+  status text NOT NULL,
+  resolution_note text,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.invoices (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  customer_id text NOT NULL REFERENCES public.customers(id),
+  status text NOT NULL,
+  balance_cents integer NOT NULL,
+  late_fee_cents integer NOT NULL,
+  waiver_reason text,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_reader') THEN
+    CREATE ROLE synapsor_reader LOGIN PASSWORD 'synapsor_reader_password';
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_writer') THEN
+    CREATE ROLE synapsor_writer LOGIN PASSWORD 'synapsor_writer_password';
+  END IF;
+END
+$$;
+
+GRANT CONNECT ON DATABASE synapsor_reference_support_billing TO synapsor_reader, synapsor_writer;
+GRANT USAGE ON SCHEMA public TO synapsor_reader, synapsor_writer;
+GRANT CREATE ON SCHEMA public TO synapsor_writer;
+GRANT SELECT ON public.tenants, public.customers, public.support_tickets, public.invoices TO synapsor_reader, synapsor_writer;
+GRANT UPDATE (status, resolution_note, updated_at) ON public.support_tickets TO synapsor_writer;
+GRANT UPDATE (late_fee_cents, waiver_reason, updated_at) ON public.invoices TO synapsor_writer;

package/examples/reference-support-billing-app/scripts/run-demo.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+cd "$ROOT_DIR"
+
+corepack pnpm test:reference-app

package/examples/reference-support-billing-app/seed.sql

@@ -0,0 +1,26 @@
+INSERT INTO public.tenants (id, name, created_at, updated_at)
+VALUES
+  ('acme', 'Acme Robotics', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
+  ('otherco', 'OtherCo Labs', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z')
+ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name, updated_at = EXCLUDED.updated_at;
+
+INSERT INTO public.customers (id, tenant_id, name, email, plan, created_at, updated_at)
+VALUES
+  ('cust_acme_1', 'acme', 'Acme Robotics', 'ops@example.invalid', 'enterprise', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
+  ('cust_acme_2', 'acme', 'Acme Field Ops', 'field@example.invalid', 'builder', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
+  ('cust_other_1', 'otherco', 'OtherCo Labs', 'ops@otherco.invalid', 'builder', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z')
+ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, name = EXCLUDED.name, email = EXCLUDED.email, plan = EXCLUDED.plan, updated_at = EXCLUDED.updated_at;
+
+INSERT INTO public.support_tickets (id, tenant_id, customer_id, subject, status, resolution_note, updated_at)
+VALUES
+  ('T-1042', 'acme', 'cust_acme_1', 'Late fee waiver request for INV-3001', 'open', NULL, '2026-06-20T12:00:00Z'),
+  ('T-1043', 'acme', 'cust_acme_2', 'Duplicate card charge question', 'open', NULL, '2026-06-20T12:05:00Z'),
+  ('T-9001', 'otherco', 'cust_other_1', 'OtherCo private billing ticket', 'open', NULL, '2026-06-20T12:00:00Z')
+ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, customer_id = EXCLUDED.customer_id, subject = EXCLUDED.subject, status = EXCLUDED.status, resolution_note = EXCLUDED.resolution_note, updated_at = EXCLUDED.updated_at;
+
+INSERT INTO public.invoices (id, tenant_id, customer_id, status, balance_cents, late_fee_cents, waiver_reason, updated_at)
+VALUES
+  ('INV-3001', 'acme', 'cust_acme_1', 'overdue', 25500, 5500, NULL, '2026-06-20T14:31:08Z'),
+  ('INV-3002', 'acme', 'cust_acme_2', 'paid', 0, 0, NULL, '2026-06-20T14:40:00Z'),
+  ('INV-9001', 'otherco', 'cust_other_1', 'overdue', 25500, 5500, NULL, '2026-06-20T14:31:08Z')
+ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, customer_id = EXCLUDED.customer_id, status = EXCLUDED.status, balance_cents = EXCLUDED.balance_cents, late_fee_cents = EXCLUDED.late_fee_cents, waiver_reason = EXCLUDED.waiver_reason, updated_at = EXCLUDED.updated_at;

package/examples/reference-support-billing-app/synapsor.runner.json

@@ -0,0 +1,136 @@
+{
+  "version": 1,
+  "mode": "review",
+  "storage": {
+    "sqlite_path": "./tmp/reference-support-billing/local.db"
+  },
+  "sources": {
+    "app_postgres": {
+      "engine": "postgres",
+      "read_url_env": "REFERENCE_POSTGRES_READ_URL",
+      "write_url_env": "REFERENCE_POSTGRES_WRITE_URL",
+      "statement_timeout_ms": 3000
+    }
+  },
+  "trusted_context": {
+    "provider": "environment",
+    "values": {
+      "tenant_id_env": "SYNAPSOR_TENANT_ID",
+      "principal_env": "SYNAPSOR_PRINCIPAL"
+    }
+  },
+  "contexts": {
+    "local_operator": {
+      "provider": "environment",
+      "values": {
+        "tenant_id_env": "SYNAPSOR_TENANT_ID",
+        "principal_env": "SYNAPSOR_PRINCIPAL"
+      }
+    }
+  },
+  "capabilities": [
+    {
+      "name": "support.inspect_ticket",
+      "kind": "read",
+      "source": "app_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "support_tickets",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "ticket_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "ticket_id" },
+      "visible_columns": ["id", "tenant_id", "customer_id", "subject", "status", "resolution_note", "updated_at"],
+      "evidence": "required",
+      "max_rows": 1
+    },
+    {
+      "name": "support.propose_ticket_resolution",
+      "kind": "proposal",
+      "source": "app_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "support_tickets",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "ticket_id": { "type": "string", "required": true, "max_length": 128 },
+        "resolution_note": { "type": "string", "required": true, "max_length": 1000 }
+      },
+      "lookup": { "id_from_arg": "ticket_id" },
+      "visible_columns": ["id", "tenant_id", "customer_id", "subject", "status", "resolution_note", "updated_at"],
+      "evidence": "required",
+      "max_rows": 1,
+      "patch": {
+        "status": { "fixed": "pending_review" },
+        "resolution_note": { "from_arg": "resolution_note" }
+      },
+      "allowed_columns": ["status", "resolution_note"],
+      "transition_guards": {
+        "status": {
+          "allowed": {
+            "open": ["pending_review"],
+            "pending_review": ["resolved"]
+          }
+        }
+      },
+      "conflict_guard": { "column": "updated_at" },
+      "approval": { "mode": "human", "required_role": "support_lead" }
+    },
+    {
+      "name": "billing.inspect_invoice",
+      "kind": "read",
+      "source": "app_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "invoice_id" },
+      "visible_columns": ["id", "tenant_id", "customer_id", "status", "balance_cents", "late_fee_cents", "waiver_reason", "updated_at"],
+      "evidence": "required",
+      "max_rows": 1
+    },
+    {
+      "name": "billing.propose_late_fee_waiver",
+      "kind": "proposal",
+      "source": "app_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "invoice_id": { "type": "string", "required": true, "max_length": 128 },
+        "reason": { "type": "string", "required": true, "max_length": 500 }
+      },
+      "lookup": { "id_from_arg": "invoice_id" },
+      "visible_columns": ["id", "tenant_id", "customer_id", "status", "balance_cents", "late_fee_cents", "waiver_reason", "updated_at"],
+      "evidence": "required",
+      "max_rows": 1,
+      "patch": {
+        "late_fee_cents": { "fixed": 0 },
+        "waiver_reason": { "from_arg": "reason" }
+      },
+      "allowed_columns": ["late_fee_cents", "waiver_reason"],
+      "numeric_bounds": {
+        "late_fee_cents": { "minimum": 0, "maximum": 10000 }
+      },
+      "conflict_guard": { "column": "updated_at" },
+      "approval": { "mode": "human", "required_role": "billing_lead" }
+    }
+  ]
+}

package/package.json

@@ -1,22 +1,28 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "description": "Commit-safe MCP runner for Postgres and MySQL agents",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {
-    "synapsor-runner": "dist/bin.cjs"
+    "synapsor": "dist/cli.js",
+    "synapsor-runner": "dist/cli.js"
   },
   "files": [
-    "dist/bin.cjs",
     "dist/cli.js",
     "dist/cli.d.ts",
     "dist/cli.d.ts.map",
     "dist/local-ui.d.ts",
     "dist/local-ui.d.ts.map",
+    "dist/runner.mjs",
+    "docs/**/*.md",
+    "examples/dangerous-mcp-tools.json",
+    "examples/reference-support-billing-app/**",
+    "recipes/**/*.json",
     "README.md",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "TRADEMARKS.md"
   ],
   "engines": {
     "node": ">=22.5.0"

package/recipes/accounts.trial_extension.json

@@ -0,0 +1,42 @@
+{
+  "id": "accounts.trial_extension",
+  "title": "Trial extension",
+  "summary": "Inspect one account and propose a bounded trial extension.",
+  "expected_table_type": "accounts or subscriptions table",
+  "required_columns": ["id", "tenant_id", "trial_ends_at", "extension_reason", "updated_at"],
+  "recommended_primary_key": "id",
+  "recommended_tenant_key": "tenant_id",
+  "recommended_conflict_column": "updated_at",
+  "visible_columns": ["id", "tenant_id", "plan", "trial_ends_at", "extension_reason", "updated_at"],
+  "allowed_write_columns": ["trial_ends_at", "extension_reason"],
+  "semantic_tools": ["accounts.inspect_account", "accounts.propose_trial_extension"],
+  "notes": [
+    "Use a handler executor if trial changes must go through your billing service."
+  ],
+  "spec": {
+    "version": 1,
+    "engine": "postgres",
+    "mode": "review",
+    "schema": "public",
+    "table": "accounts",
+    "primary_key": "id",
+    "tenant_key": "tenant_id",
+    "conflict_column": "updated_at",
+    "namespace": "accounts",
+    "object_name": "account",
+    "inspect_tool_name": "accounts.inspect_account",
+    "proposal_tool_name": "accounts.propose_trial_extension",
+    "lookup_arg": "account_id",
+    "visible_columns": ["id", "tenant_id", "plan", "trial_ends_at", "extension_reason", "updated_at"],
+    "allowed_columns": ["trial_ends_at", "extension_reason"],
+    "patch": {
+      "trial_ends_at": { "from_arg": "trial_ends_at" },
+      "extension_reason": { "from_arg": "reason" }
+    },
+    "patch_args": {
+      "trial_ends_at": { "type": "string", "required": true, "max_length": 64 },
+      "reason": { "type": "string", "required": true, "max_length": 500 }
+    },
+    "approval": { "required_role": "account_admin" }
+  }
+}