@synapsor/runner 0.1.8 → 0.1.10

package/docs/local-mode.md

@@ -345,7 +345,7 @@ For CI or direct verification, use:
 corepack pnpm test:mcp-local
 ```
 
-It launches the official MCP stdio client transport against `synapsor-runner mcp serve`, exercises the Postgres billing, Postgres support, and MySQL orders examples, checks that source rows are unchanged before approval, approves locally, generates versioned writeback jobs, applies them, retries idempotently, and then proves stale-row conflict:
+It launches the official MCP stdio client transport against `synapsor-runner mcp serve`, exercises the Postgres billing, Postgres support, MySQL orders, and support plan-credit examples, checks that source rows are unchanged before approval, approves locally, generates versioned writeback jobs, applies them, retries idempotently, and then proves stale-row conflict:
 
 ```text
 The business state changed after the agent saw it, so Synapsor refused to commit.
@@ -360,14 +360,15 @@ corepack pnpm test:live-apply
 Prerequisites:
 
 - Docker daemon running;
-- local ports `55433`, `55434`, and `53307` available;
+- local ports `55433`, `55434`, `55438`, and `53307` available;
 - no Synapsor Cloud account, API key, hosted workspace, or production database.
 
 Expected output:
 
-- disposable Postgres billing, Postgres support, and MySQL orders containers start;
+- disposable Postgres billing, Postgres support, support plan-credit, and MySQL orders containers start;
 - MCP `tools/list` exposes reviewed semantic tools, not raw SQL;
 - proposal calls create exact before/after diffs while source rows remain unchanged;
+- the support plan-credit scenario proves `$25` policy auto-approval, `$100` human approval, and `$1000` bound rejection;
 - local approval happens outside MCP;
 - guarded writeback applies approved jobs and records receipts/replay;
 - idempotent retry returns the existing receipt;

package/docs/release-notes.md

@@ -12,6 +12,15 @@ for the Synapsor Cloud CLI.
 
 ## Unreleased
 
+## 0.1.9
+
+### CLI Hygiene
+
+- Adds top-level `synapsor-runner --version`, `synapsor-runner -v`, and
+  `synapsor-runner version` output.
+
+## 0.1.8
+
 ### DSL / JSON Contract Parity
 
 - Adds portable spec fields for capability `returns_hint`, proposal

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

@@ -0,0 +1,176 @@
+# Support Plan Credit Example
+
+This example shows three enforcement tiers on one support action:
+
+- `$25` (`2500` cents): policy-approved, then applied locally through guarded writeback.
+- `$100` (`10000` cents): saved as `pending_review` until a local operator approves.
+- `$1000` (`100000` cents): rejected before proposal creation by the contract bound.
+
+## Prerequisites
+
+- Docker
+- Node 22.5+
+- Port `55438` available
+
+## Quick Start
+
+```bash
+docker compose -f examples/support-plan-credit/docker-compose.yml up -d
+
+export PLAN_CREDIT_POSTGRES_READ_URL="postgresql://synapsor_reader:synapsor_reader_password@localhost:55438/synapsor_runner_plan_credit"
+export PLAN_CREDIT_POSTGRES_WRITE_URL="postgresql://synapsor_writer:synapsor_writer_password@localhost:55438/synapsor_runner_plan_credit"
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="local_support_agent"
+
+synapsor-runner tools preview \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+
+# Run this in a second terminal if you want to attach an MCP client.
+synapsor-runner mcp serve \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+```
+
+## Walkthrough
+
+Inspect the customer first:
+
+```bash
+synapsor-runner smoke call support.inspect_customer \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db \
+  --json '{"customer_id":"CUS-3001"}'
+```
+
+Propose a `$25` credit:
+
+```bash
+synapsor-runner propose support.propose_plan_credit \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db \
+  --json '{"customer_id":"CUS-3001","credit_cents":2500,"reason":"SLA outage ticket SUP-481"}'
+```
+
+`proposals show` displays `policy:support_propose_plan_credit_auto_approval`.
+The proposal is approved, but it is not applied until the local writeback step:
+
+```bash
+synapsor-runner proposals show latest --store ./tmp/support-plan-credit/local.db
+synapsor-runner apply latest \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+synapsor-runner receipts list --proposal <proposal_id> --store ./tmp/support-plan-credit/local.db
+```
+
+Propose a `$100` credit:
+
+```bash
+synapsor-runner propose support.propose_plan_credit \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db \
+  --json '{"customer_id":"CUS-3001","credit_cents":10000,"reason":"larger support credit"}'
+
+synapsor-runner proposals approve latest --yes --store ./tmp/support-plan-credit/local.db
+synapsor-runner apply latest \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+```
+
+Propose a `$1000` credit:
+
+```bash
+synapsor-runner propose support.propose_plan_credit \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db \
+  --json '{"customer_id":"CUS-3001","credit_cents":100000,"reason":"too large"}'
+```
+
+The contract bound rejects it before a proposal row exists.
+
+Replay and stale-row checks:
+
+```bash
+synapsor-runner replay export --proposal latest --store ./tmp/support-plan-credit/local.db --output ./tmp/support-plan-credit/replay.json
+synapsor-runner apply latest --config examples/support-plan-credit/synapsor.runner.json --store ./tmp/support-plan-credit/local.db
+```
+
+The live smoke test mutates `updated_at` before apply and proves stale proposals
+return `VERSION_CONFLICT` without changing the source row.
+
+## What The Agent Never Sees
+
+The contract keeps these fields out:
+
+- `card_token`
+- `raw_payment_method`
+- `internal_risk_score`
+- `private_notes`
+
+`tools preview` should show only:
+
+```text
+support.inspect_customer
+support.propose_plan_credit
+auto-approval: enabled
+```
+
+No raw SQL, approval tools, commit tools, write credentials, or model-controlled
+tenant authority are exposed to MCP.
+
+## How The Policy Is Governed
+
+The auto-approval policy lives in `contract.synapsor`:
+
+```sql
+AUTO APPROVE WHEN plan_credit_cents <= 2500
+```
+
+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.
+
+To disable local policy approval without changing the contract:
+
+```json
+{
+  "approvals": {
+    "disable_auto_approval": true
+  }
+}
+```
+
+Auto-approval never applies the write. It only records an approval row and audit
+event with actor `policy:<policy_name>`.
+
+## Cloud
+
+Dry-run the Cloud payload:
+
+```bash
+synapsor-runner cloud push examples/support-plan-credit/synapsor.contract.json --dry-run
+```
+
+Real push uses your Cloud env vars:
+
+```bash
+export SYNAPSOR_CONTROL_PLANE_URL="https://api.synapsor.ai"
+export SYNAPSOR_RUNNER_TOKEN="syn_wbr_..."
+
+synapsor-runner cloud push examples/support-plan-credit/synapsor.contract.json \
+  --workspace <workspace_id> \
+  --name support-plan-credit
+```
+
+After push, Cloud can return the registered version and a runner bundle with
+placeholder env names:
+
+```bash
+curl -H "Authorization: Bearer $SYNAPSOR_CLOUD_TOKEN" \
+  "$SYNAPSOR_CONTROL_PLANE_URL/v1/control/projects/<workspace_id>/agent-contracts/support-plan-credit/versions/latest"
+
+curl -H "Authorization: Bearer $SYNAPSOR_CLOUD_TOKEN" \
+  "$SYNAPSOR_CONTROL_PLANE_URL/v1/control/projects/<workspace_id>/agent-contracts/support-plan-credit/runner-bundle" \
+  -o support-plan-credit-runner-bundle.json
+```
+
+No Cloud account is needed to run this local example.

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

@@ -0,0 +1,59 @@
+CREATE AGENT CONTEXT support_agent_context
+  BIND tenant_id FROM ENVIRONMENT SYNAPSOR_TENANT_ID REQUIRED
+  BIND principal FROM ENVIRONMENT SYNAPSOR_PRINCIPAL REQUIRED
+  TENANT BINDING tenant_id
+  PRINCIPAL BINDING principal
+END
+
+CREATE CAPABILITY support.inspect_customer
+  DESCRIPTION 'Inspect one support customer in the trusted tenant before proposing a plan credit.'
+  RETURNS HINT 'Returns reviewed customer fields plus evidence/query-audit handles.'
+  USING CONTEXT support_agent_context
+  SOURCE local_postgres
+  ON public.customers
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  CONFLICT GUARD updated_at
+  LOOKUP customer_id BY id
+  ARG customer_id STRING REQUIRED MAX LENGTH 128 DESCRIPTION 'Customer id such as CUS-3001.'
+  ALLOW READ id, tenant_id, customer_id, plan, invoice_status, support_ticket_reason, plan_credit_cents, credit_reason, updated_at
+  KEEP OUT card_token, raw_payment_method, internal_risk_score, private_notes
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+END
+
+CREATE CAPABILITY support.propose_plan_credit
+  DESCRIPTION 'Propose a bounded support plan credit after inspecting customer and ticket evidence.'
+  RETURNS HINT 'Returns a proposal id, exact diff, evidence handle, and source_database_changed:false. Policy may approve small credits, but writeback is still separate.'
+  USING CONTEXT support_agent_context
+  SOURCE local_postgres
+  ON public.customers
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  CONFLICT GUARD updated_at
+  LOOKUP customer_id BY id
+  ARG customer_id STRING REQUIRED MAX LENGTH 128 DESCRIPTION 'Customer id such as CUS-3001.'
+  ARG credit_cents NUMBER REQUIRED MIN 1 DESCRIPTION 'Requested plan credit in cents.'
+  ARG reason TEXT REQUIRED MAX LENGTH 500 DESCRIPTION 'Business reason tied to support evidence.'
+  ALLOW READ id, tenant_id, customer_id, plan, invoice_status, support_ticket_reason, plan_credit_cents, credit_reason, updated_at
+  KEEP OUT card_token, raw_payment_method, internal_risk_score, private_notes
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+  PROPOSE ACTION grant_plan_credit
+  ALLOW WRITE plan_credit_cents, credit_reason
+  PATCH plan_credit_cents = ARG credit_cents
+  PATCH credit_reason = ARG reason
+  BOUND plan_credit_cents 1..50000
+  APPROVAL ROLE support_reviewer
+  AUTO APPROVE WHEN plan_credit_cents <= 2500
+  WRITEBACK DIRECT SQL
+END
+
+CREATE AGENT WORKFLOW support.plan_credit_request
+  USING CONTEXT support_agent_context
+  ALLOW CAPABILITY support.inspect_customer
+  ALLOW CAPABILITY support.propose_plan_credit
+  REQUIRE EVIDENCE
+  APPROVAL REQUIRED ROLE support_reviewer
+  CHECKPOINT PROPOSAL ONLY
+END

package/examples/support-plan-credit/docker-compose.yml

@@ -0,0 +1,12 @@
+services:
+  postgres:
+    image: postgres:16
+    container_name: synapsor_runner_plan_credit
+    environment:
+      POSTGRES_DB: synapsor_runner_plan_credit
+      POSTGRES_USER: synapsor_admin
+      POSTGRES_PASSWORD: synapsor_admin_password
+    ports:
+      - "55438:5432"
+    volumes:
+      - ./seed:/docker-entrypoint-initdb.d:ro

package/examples/support-plan-credit/seed/001_seed.sql

@@ -0,0 +1,92 @@
+CREATE TABLE IF NOT EXISTS public.customers (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL,
+  customer_id text NOT NULL,
+  plan text NOT NULL,
+  invoice_status text NOT NULL,
+  support_ticket_reason text NOT NULL,
+  plan_credit_cents integer NOT NULL DEFAULT 0,
+  credit_reason text,
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  card_token text,
+  raw_payment_method text,
+  internal_risk_score integer,
+  private_notes text
+);
+
+INSERT INTO public.customers (
+  id,
+  tenant_id,
+  customer_id,
+  plan,
+  invoice_status,
+  support_ticket_reason,
+  plan_credit_cents,
+  credit_reason,
+  updated_at,
+  card_token,
+  raw_payment_method,
+  internal_risk_score,
+  private_notes
+)
+VALUES
+  (
+    'CUS-3001',
+    'acme',
+    'CUS-3001',
+    'enterprise',
+    'open_dispute',
+    'SLA outage ticket SUP-481 confirmed by support lead',
+    0,
+    NULL,
+    '2026-06-20T14:31:08Z',
+    'tok_fake_acme_3001',
+    'fake_visa_4242',
+    12,
+    'fake internal note: do not expose'
+  ),
+  (
+    'CUS-9001',
+    'otherco',
+    'CUS-9001',
+    'starter',
+    'paid',
+    'OtherCo tenant row for spoof checks',
+    0,
+    NULL,
+    '2026-06-20T14:31:08Z',
+    'tok_fake_otherco_9001',
+    'fake_mastercard_4444',
+    77,
+    'fake other tenant note'
+  )
+ON CONFLICT (id) DO UPDATE SET
+  tenant_id = EXCLUDED.tenant_id,
+  customer_id = EXCLUDED.customer_id,
+  plan = EXCLUDED.plan,
+  invoice_status = EXCLUDED.invoice_status,
+  support_ticket_reason = EXCLUDED.support_ticket_reason,
+  plan_credit_cents = EXCLUDED.plan_credit_cents,
+  credit_reason = EXCLUDED.credit_reason,
+  updated_at = EXCLUDED.updated_at,
+  card_token = EXCLUDED.card_token,
+  raw_payment_method = EXCLUDED.raw_payment_method,
+  internal_risk_score = EXCLUDED.internal_risk_score,
+  private_notes = EXCLUDED.private_notes;
+
+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_runner_plan_credit 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.customers TO synapsor_reader, synapsor_writer;
+GRANT UPDATE (plan_credit_cents, credit_reason, updated_at) ON public.customers TO synapsor_writer;

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

@@ -0,0 +1,198 @@
+{
+  "capabilities": [
+    {
+      "args": {
+        "customer_id": {
+          "description": "Customer id such as CUS-3001.",
+          "max_length": 128,
+          "required": true,
+          "type": "string"
+        }
+      },
+      "context": "support_agent_context",
+      "description": "Inspect one support customer in the trusted tenant before proposing a plan credit.",
+      "evidence": {
+        "query_audit": true,
+        "required": true
+      },
+      "kept_out_fields": [
+        "card_token",
+        "raw_payment_method",
+        "internal_risk_score",
+        "private_notes"
+      ],
+      "kind": "read",
+      "lookup": {
+        "id_from_arg": "customer_id"
+      },
+      "max_rows": 1,
+      "name": "support.inspect_customer",
+      "returns_hint": "Returns reviewed customer fields plus evidence/query-audit handles.",
+      "source": "local_postgres",
+      "subject": {
+        "conflict_key": "updated_at",
+        "primary_key": "id",
+        "schema": "public",
+        "table": "customers",
+        "tenant_key": "tenant_id"
+      },
+      "visible_fields": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "plan",
+        "invoice_status",
+        "support_ticket_reason",
+        "plan_credit_cents",
+        "credit_reason",
+        "updated_at"
+      ]
+    },
+    {
+      "args": {
+        "credit_cents": {
+          "description": "Requested plan credit in cents.",
+          "minimum": 1,
+          "required": true,
+          "type": "number"
+        },
+        "customer_id": {
+          "description": "Customer id such as CUS-3001.",
+          "max_length": 128,
+          "required": true,
+          "type": "string"
+        },
+        "reason": {
+          "description": "Business reason tied to support evidence.",
+          "max_length": 500,
+          "required": true,
+          "type": "string"
+        }
+      },
+      "context": "support_agent_context",
+      "description": "Propose a bounded support plan credit after inspecting customer and ticket evidence.",
+      "evidence": {
+        "query_audit": true,
+        "required": true
+      },
+      "kept_out_fields": [
+        "card_token",
+        "raw_payment_method",
+        "internal_risk_score",
+        "private_notes"
+      ],
+      "kind": "proposal",
+      "lookup": {
+        "id_from_arg": "customer_id"
+      },
+      "max_rows": 1,
+      "name": "support.propose_plan_credit",
+      "proposal": {
+        "action": "grant_plan_credit",
+        "allowed_fields": [
+          "plan_credit_cents",
+          "credit_reason"
+        ],
+        "approval": {
+          "mode": "policy",
+          "policy": "support_propose_plan_credit_auto_approval",
+          "required_role": "support_reviewer"
+        },
+        "conflict_guard": {
+          "column": "updated_at"
+        },
+        "numeric_bounds": {
+          "plan_credit_cents": {
+            "maximum": 50000,
+            "minimum": 1
+          }
+        },
+        "patch": {
+          "credit_reason": {
+            "from_arg": "reason"
+          },
+          "plan_credit_cents": {
+            "from_arg": "credit_cents"
+          }
+        },
+        "writeback": {
+          "mode": "direct_sql"
+        }
+      },
+      "returns_hint": "Returns a proposal id, exact diff, evidence handle, and source_database_changed:false. Policy may approve small credits, but writeback is still separate.",
+      "source": "local_postgres",
+      "subject": {
+        "conflict_key": "updated_at",
+        "primary_key": "id",
+        "schema": "public",
+        "table": "customers",
+        "tenant_key": "tenant_id"
+      },
+      "visible_fields": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "plan",
+        "invoice_status",
+        "support_ticket_reason",
+        "plan_credit_cents",
+        "credit_reason",
+        "updated_at"
+      ]
+    }
+  ],
+  "contexts": [
+    {
+      "bindings": [
+        {
+          "key": "SYNAPSOR_TENANT_ID",
+          "name": "tenant_id",
+          "required": true,
+          "source": "environment"
+        },
+        {
+          "key": "SYNAPSOR_PRINCIPAL",
+          "name": "principal",
+          "required": true,
+          "source": "environment"
+        }
+      ],
+      "name": "support_agent_context",
+      "principal_binding": "principal",
+      "tenant_binding": "tenant_id"
+    }
+  ],
+  "kind": "SynapsorContract",
+  "policies": [
+    {
+      "kind": "approval",
+      "mode": "green",
+      "name": "support_propose_plan_credit_auto_approval",
+      "rules": [
+        {
+          "field": "plan_credit_cents",
+          "max": 2500
+        }
+      ]
+    }
+  ],
+  "spec_version": "0.1",
+  "workflows": [
+    {
+      "allowed_capabilities": [
+        "support.inspect_customer",
+        "support.propose_plan_credit"
+      ],
+      "approval": {
+        "required": true,
+        "role": "support_reviewer"
+      },
+      "context": "support_agent_context",
+      "name": "support.plan_credit_request",
+      "replay": {
+        "checkpoint": "proposal_only"
+      },
+      "required_evidence": true
+    }
+  ]
+}

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

@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "mode": "review",
+  "storage": {
+    "sqlite_path": "./tmp/support-plan-credit/local.db"
+  },
+  "contracts": [
+    "./synapsor.contract.json"
+  ],
+  "sources": {
+    "local_postgres": {
+      "engine": "postgres",
+      "read_url_env": "PLAN_CREDIT_POSTGRES_READ_URL",
+      "write_url_env": "PLAN_CREDIT_POSTGRES_WRITE_URL",
+      "statement_timeout_ms": 3000
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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/support-plan-credit/**",
     "examples/support-billing-agent/**",
     "fixtures/**",
     "schemas/**",