@synapsor/runner 0.1.16 → 1.1.0

package/examples/runner-fleet/Dockerfile

@@ -0,0 +1,11 @@
+FROM node:22-bookworm-slim
+
+RUN corepack enable && corepack prepare pnpm@10.14.0 --activate
+
+WORKDIR /app
+COPY . .
+RUN corepack pnpm install --frozen-lockfile \
+  && corepack pnpm build:runner-package
+
+ENTRYPOINT ["node", "apps/runner/dist/cli.js"]
+CMD ["mcp", "serve", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8766", "--config", "/config/synapsor.runner.json"]

package/examples/runner-fleet/README.md

@@ -0,0 +1,52 @@
+# Two-Runner Fleet Fixture
+
+This synthetic fixture starts Postgres, MySQL, and two stateless Streamable
+HTTP Runner services. Both Runners share one bounded Postgres runtime ledger.
+The committed passwords and HS256 key are disposable local-demo values. Never
+reuse them outside this fixture.
+
+From the repository root:
+
+```bash
+corepack pnpm install
+docker compose --profile fleet -f examples/runner-fleet/docker-compose.yml up --build -d --wait
+docker compose --profile fleet -f examples/runner-fleet/docker-compose.yml ps
+```
+
+Check both instances:
+
+```bash
+curl --fail http://127.0.0.1:8871/healthz
+curl --fail http://127.0.0.1:8871/readyz
+curl --fail http://127.0.0.1:8872/readyz
+```
+
+The MCP endpoint requires a claim-bearing development JWT. Generate one for
+the fixture only:
+
+```bash
+node examples/runner-fleet/mint-dev-token.mjs acme local-agent
+```
+
+The production path should use `jwt_asymmetric` with an explicit RS256/ES256
+allowlist and a trusted JWKS URL or public PEM. See
+[Running A Runner Fleet](../../docs/running-a-runner-fleet.md).
+
+Run the stronger automated verification instead of treating a green Compose
+status as proof:
+
+```bash
+corepack pnpm test:fleet
+```
+
+That test launches two source-tree Runners, uses asymmetric claim-bound
+sessions and concurrent signed reviewers, starts competing workers, kills
+workers before, during, and after writeback, and verifies readiness,
+dead-letter recovery, idempotency, pool pressure, backup/restore, and
+archive-before-retention. It deletes all fixture volumes when complete.
+
+Clean up the visual Compose fixture with:
+
+```bash
+docker compose --profile fleet -f examples/runner-fleet/docker-compose.yml down -v --remove-orphans
+```

package/examples/runner-fleet/docker-compose.yml

@@ -0,0 +1,76 @@
+services:
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_DB: synapsor_fleet
+      POSTGRES_USER: synapsor_admin
+      POSTGRES_PASSWORD: synapsor_admin_password
+    ports:
+      - "55439:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "test \"$(psql -U synapsor_admin -d synapsor_fleet -tAc \"SELECT pg_postmaster_start_time() > initialized_at FROM public.synapsor_fixture_ready LIMIT 1\" 2>/dev/null | xargs)\" = t"]
+      interval: 1s
+      timeout: 3s
+      retries: 30
+    volumes:
+      - ./seed/postgres.sql:/docker-entrypoint-initdb.d/001-schema.sql:ro
+
+  mysql:
+    image: mysql:8
+    environment:
+      MYSQL_DATABASE: synapsor_fleet
+      MYSQL_ROOT_PASSWORD: root_password
+    ports:
+      - "53309:3306"
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-proot_password"]
+      interval: 2s
+      timeout: 5s
+      retries: 40
+    volumes:
+      - ./seed/mysql.sql:/docker-entrypoint-initdb.d/001-schema.sql:ro
+
+  runner-a:
+    profiles: ["fleet"]
+    build:
+      context: ../..
+      dockerfile: examples/runner-fleet/Dockerfile
+    command: ["mcp", "serve", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8766", "--config", "/config/synapsor.runner.json"]
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment: &runner_environment
+      FLEET_POSTGRES_READ_URL: postgresql://synapsor_reader:synapsor_reader_password@postgres:5432/synapsor_fleet
+      FLEET_POSTGRES_WRITE_URL: postgresql://synapsor_writer:synapsor_writer_password@postgres:5432/synapsor_fleet
+      SYNAPSOR_LEDGER_DATABASE_URL: postgresql://synapsor_admin:synapsor_admin_password@postgres:5432/synapsor_fleet
+      SYNAPSOR_SESSION_JWT_SECRET: synthetic-fleet-session-secret-change-before-use-0001
+      SYNAPSOR_METRICS_TOKEN: synthetic-fleet-metrics-token-change-before-use
+    ports:
+      - "8871:8766"
+    volumes:
+      - ./synapsor.runner.json:/config/synapsor.runner.json:ro
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:8766/readyz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+
+  runner-b:
+    profiles: ["fleet"]
+    build:
+      context: ../..
+      dockerfile: examples/runner-fleet/Dockerfile
+    command: ["mcp", "serve", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8766", "--config", "/config/synapsor.runner.json"]
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment: *runner_environment
+    ports:
+      - "8872:8766"
+    volumes:
+      - ./synapsor.runner.json:/config/synapsor.runner.json:ro
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:8766/readyz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 2s
+      timeout: 5s
+      retries: 30

package/examples/runner-fleet/mint-dev-token.mjs

@@ -0,0 +1,19 @@
+import crypto from "node:crypto";
+
+const tenant = process.argv[2] ?? "acme";
+const subject = process.argv[3] ?? "fleet-demo-agent";
+const secret = "synthetic-fleet-session-secret-change-before-use-0001";
+const now = Math.floor(Date.now() / 1000);
+const header = { alg: "HS256", typ: "JWT" };
+const payload = {
+  sub: subject,
+  tenant_id: tenant,
+  iss: "https://fleet.example.invalid",
+  aud: "synapsor-runner-fleet",
+  iat: now,
+  exp: now + 600,
+};
+const encode = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
+const unsigned = `${encode(header)}.${encode(payload)}`;
+const signature = crypto.createHmac("sha256", secret).update(unsigned).digest("base64url");
+process.stdout.write(`${unsigned}.${signature}\n`);

package/examples/runner-fleet/seed/mysql.sql

@@ -0,0 +1,20 @@
+CREATE TABLE invoices (
+  id varchar(128) PRIMARY KEY,
+  tenant_id varchar(128) NOT NULL,
+  status varchar(64) NOT NULL,
+  late_fee_cents integer NOT NULL,
+  waiver_reason varchar(500),
+  updated_at datetime(6) NOT NULL
+);
+
+INSERT INTO invoices (id, tenant_id, status, late_fee_cents, waiver_reason, updated_at) VALUES
+  ('MYSQL-ACME', 'acme', 'overdue', 700, NULL, '2026-07-12 12:00:00.000000');
+
+CREATE VIEW slow_invoices AS
+SELECT invoices.*, SLEEP(0.35) AS synthetic_delay
+FROM invoices;
+
+CREATE USER IF NOT EXISTS 'synapsor_reader'@'%' IDENTIFIED BY 'synapsor_reader_password';
+GRANT SELECT ON synapsor_fleet.invoices TO 'synapsor_reader'@'%';
+GRANT SELECT ON synapsor_fleet.slow_invoices TO 'synapsor_reader'@'%';
+FLUSH PRIVILEGES;

package/examples/runner-fleet/seed/postgres.sql

@@ -0,0 +1,73 @@
+CREATE TABLE public.invoices (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL,
+  status text NOT NULL,
+  late_fee_cents integer NOT NULL,
+  waiver_reason text,
+  updated_at timestamptz NOT NULL
+);
+
+CREATE TABLE public.synapsor_writeback_receipts (
+  idempotency_key text PRIMARY KEY,
+  job_id text UNIQUE NOT NULL,
+  proposal_id text NOT NULL,
+  status text NOT NULL,
+  result_hash text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  completed_at timestamptz
+);
+
+CREATE TABLE public.synthetic_handler_receipts (
+  idempotency_key text PRIMARY KEY,
+  proposal_id text NOT NULL,
+  object_id text NOT NULL,
+  status text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+INSERT INTO public.invoices (id, tenant_id, status, late_fee_cents, waiver_reason, updated_at) VALUES
+  ('INV-ACME', 'acme', 'overdue', 2500, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-GLOBEX', 'globex', 'overdue', 3100, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-RATECO', 'rateco', 'overdue', 900, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-QUORUM-RACE', 'acme', 'overdue', 1400, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-WORKER-RACE', 'acme', 'overdue', 1600, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-DEAD-REQUEUE', 'acme', 'overdue', 1700, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-DEAD-DISCARD', 'acme', 'overdue', 1750, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-KILL-BEFORE', 'acme', 'overdue', 1200, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-KILL-DURING', 'acme', 'overdue', 1500, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-KILL-AFTER', 'acme', 'overdue', 1800, NULL, '2026-07-12T12:00:00Z');
+
+CREATE FUNCTION public.synthetic_pool_delay() RETURNS integer
+LANGUAGE plpgsql VOLATILE AS $$
+BEGIN
+  PERFORM pg_sleep(0.15);
+  RETURN 0;
+END
+$$;
+
+CREATE VIEW public.slow_invoices AS
+SELECT invoices.*, public.synthetic_pool_delay() AS synthetic_delay
+FROM public.invoices;
+
+DO $$
+BEGIN
+  CREATE ROLE synapsor_reader LOGIN PASSWORD 'synapsor_reader_password';
+  CREATE ROLE synapsor_writer LOGIN PASSWORD 'synapsor_writer_password';
+EXCEPTION WHEN duplicate_object THEN NULL;
+END
+$$;
+
+GRANT CONNECT ON DATABASE synapsor_fleet TO synapsor_reader, synapsor_writer;
+GRANT USAGE ON SCHEMA public TO synapsor_reader, synapsor_writer;
+GRANT SELECT ON public.invoices TO synapsor_reader, synapsor_writer;
+GRANT SELECT ON public.slow_invoices TO synapsor_reader;
+GRANT UPDATE (late_fee_cents, waiver_reason, updated_at) ON public.invoices TO synapsor_writer;
+GRANT SELECT, INSERT, UPDATE ON public.synapsor_writeback_receipts TO synapsor_writer;
+
+-- Docker's Postgres entrypoint briefly starts a temporary postmaster while it
+-- runs init scripts. The Compose health check compares this timestamp with the
+-- current postmaster start time so dependents wait for the final server.
+CREATE TABLE public.synapsor_fixture_ready (
+  initialized_at timestamptz NOT NULL
+);
+INSERT INTO public.synapsor_fixture_ready (initialized_at) VALUES (clock_timestamp());

package/examples/runner-fleet/synapsor.runner.json

@@ -0,0 +1,105 @@
+{
+  "version": 1,
+  "mode": "review",
+  "storage": {
+    "shared_postgres": {
+      "mode": "runtime_store",
+      "url_env": "SYNAPSOR_LEDGER_DATABASE_URL",
+      "schema": "synapsor_runner",
+      "lock_timeout_ms": 5000,
+      "max_entries": 5000
+    }
+  },
+  "sources": {
+    "fleet_postgres": {
+      "engine": "postgres",
+      "read_url_env": "FLEET_POSTGRES_READ_URL",
+      "write_url_env": "FLEET_POSTGRES_WRITE_URL",
+      "statement_timeout_ms": 3000,
+      "pool": {
+        "max_connections": 2,
+        "connection_timeout_ms": 2000,
+        "idle_timeout_ms": 30000,
+        "queue_timeout_ms": 1000,
+        "queue_limit": 8
+      }
+    }
+  },
+  "trusted_context": {
+    "provider": "http_claims",
+    "values": {
+      "tenant_id_key": "tenant_id",
+      "principal_key": "sub"
+    }
+  },
+  "session_auth": {
+    "provider": "jwt_hs256",
+    "secret_env": "SYNAPSOR_SESSION_JWT_SECRET",
+    "issuer": "https://fleet.example.invalid",
+    "audience": "synapsor-runner-fleet",
+    "tenant_claim": "tenant_id",
+    "principal_claim": "sub",
+    "clock_skew_seconds": 10
+  },
+  "rate_limits": {
+    "enabled": true,
+    "default": { "requests": 20, "window_seconds": 60 },
+    "capabilities": {
+      "billing.inspect_invoice": { "requests": 3, "window_seconds": 60 }
+    }
+  },
+  "metrics": {
+    "enabled": true,
+    "token_env": "SYNAPSOR_METRICS_TOKEN"
+  },
+  "capabilities": [
+    {
+      "name": "billing.inspect_invoice",
+      "kind": "read",
+      "source": "fleet_postgres",
+      "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", "status", "late_fee_cents", "waiver_reason", "updated_at"],
+      "evidence": "required",
+      "max_rows": 1
+    },
+    {
+      "name": "billing.propose_late_fee_waiver",
+      "kind": "proposal",
+      "source": "fleet_postgres",
+      "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", "status", "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"],
+      "conflict_guard": { "column": "updated_at" },
+      "approval": {
+        "mode": "human",
+        "required_role": "billing_lead",
+        "required_approvals": 2
+      }
+    }
+  ]
+}

package/examples/support-plan-credit/README.md

@@ -196,10 +196,15 @@ The auto-approval policy lives in `contract.synapsor.sql`:
 
 ```sql
 AUTO APPROVE WHEN plan_credit_cents <= 2500
+LIMIT 20 PER DAY
+LIMIT TOTAL 100000 PER DAY
 ```
 
 That compiles into `synapsor.contract.json` as a reviewed approval policy. It is
-stored in git, validated by `@synapsor/spec`, and included in Cloud push payloads.
+stored in git, validated by `@synapsor/spec`, and included in Cloud push
+payloads. The policy may approve at most 20 qualifying credits or 100,000 cents
+in total per trusted tenant and UTC day. The first ceiling reached leaves later
+proposals in `pending_review` and records why the policy deferred to a human.
 
 To disable local policy approval without changing the contract:
 
@@ -214,6 +219,16 @@ To disable local policy approval without changing the contract:
 Auto-approval never applies the write. It only records an approval row and audit
 event with actor `policy:<policy_name>`.
 
+After reviewing the ceilings and running `doctor`, an operator can drain the
+approved queue without letting one stale-row conflict abort the remaining jobs:
+
+```bash
+synapsor-runner apply --all-approved --yes \
+  --capability support.propose_plan_credit --tenant acme --max 20 \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+```
+
 ## Cloud
 
 Dry-run the Cloud payload:

package/examples/support-plan-credit/contract.synapsor.sql

@@ -46,6 +46,8 @@ CREATE CAPABILITY support.propose_plan_credit
   BOUND plan_credit_cents 1..50000
   APPROVAL ROLE support_reviewer
   AUTO APPROVE WHEN plan_credit_cents <= 2500
+  LIMIT 20 PER DAY
+  LIMIT TOTAL 100000 PER DAY
   WRITEBACK DIRECT SQL
 END
 

package/examples/support-plan-credit/synapsor.contract.json

@@ -166,6 +166,21 @@
   "policies": [
     {
       "kind": "approval",
+      "limits": [
+        {
+          "kind": "count",
+          "max": 20,
+          "period": "day",
+          "scope": "tenant_policy"
+        },
+        {
+          "field": "plan_credit_cents",
+          "kind": "total",
+          "max": 100000,
+          "period": "day",
+          "scope": "tenant_policy"
+        }
+      ],
       "mode": "green",
       "name": "support_propose_plan_credit_auto_approval",
       "rules": [

package/fixtures/protocol/MANIFEST.json

@@ -33,7 +33,7 @@
     {
       "kind": "schema",
       "name": "change-set.v1.schema.json",
-      "sha256": "4e52b369b0d3bea30b0ed7b61ec239fc67de3dc691ed4014d6d5eabc7d2be4de"
+      "sha256": "119ac84f7189e9433d4eaac4defb6ef7c459a14e55e1563aa7948b746d816af5"
     },
     {
       "kind": "schema",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.16",
+  "version": "1.1.0",
   "description": "Stop giving AI agents execute_sql; expose reviewed Postgres/MySQL MCP actions with proposals, approval, writeback, and replay.",
   "license": "Apache-2.0",
   "type": "module",
@@ -25,6 +25,7 @@
     "examples/openai-agents-stdio/**",
     "examples/raw-sql-vs-synapsor/**",
     "examples/reference-support-billing-app/**",
+    "examples/runner-fleet/**",
     "examples/support-plan-credit/**",
     "examples/support-billing-agent/**",
     "fixtures/**",
@@ -58,6 +59,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
+    "jose": "6.2.3",
     "mysql2": "^3.11.0",
     "pg": "^8.13.0",
     "zod": "^3.25.0"

package/schemas/change-set.v1.schema.json

@@ -95,7 +95,8 @@
       "required": ["status"],
       "properties": {
         "status": { "enum": ["pending", "approved", "rejected", "canceled"] },
-        "required_role": { "type": "string" }
+        "required_role": { "type": "string" },
+        "required_approvals": { "type": "integer", "minimum": 1, "maximum": 10 }
       }
     },
     "writeback": {