@synapsor/runner 0.1.14 → 0.1.16

package/examples/mcp-postgres-billing-app-handler/schema.sql

@@ -40,6 +40,16 @@ CREATE TABLE IF NOT EXISTS public.account_credits (
   created_at timestamptz NOT NULL DEFAULT now()
 );
 
+CREATE TABLE IF NOT EXISTS 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
+);
+
 DO $$
 BEGIN
   IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_reader') THEN
@@ -53,7 +63,7 @@ $$;
 
 GRANT CONNECT ON DATABASE synapsor_billing_app_handler 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.invoices, public.account_credits TO synapsor_reader, synapsor_writer;
+GRANT SELECT, INSERT, UPDATE ON public.synapsor_writeback_receipts TO synapsor_writer;
 GRANT UPDATE (late_fee_cents, waiver_reason, credit_requested_cents, credit_reason, credited_cents, updated_at) ON public.invoices TO synapsor_writer;
 GRANT INSERT ON public.account_credits TO synapsor_writer;

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

@@ -47,6 +47,16 @@ CREATE TABLE IF NOT EXISTS public.orders (
   updated_at timestamptz NOT NULL DEFAULT now()
 );
 
+CREATE TABLE IF NOT EXISTS 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
+);
+
 DO $$
 BEGIN
   IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_reader') THEN
@@ -60,8 +70,8 @@ $$;
 
 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, public.orders TO synapsor_reader, synapsor_writer;
+GRANT SELECT, INSERT, UPDATE ON public.synapsor_writeback_receipts TO synapsor_writer;
 GRANT UPDATE (plan_credit_cents, credit_reason, updated_at) ON public.customers TO 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/support-billing-agent/db/schema.sql

@@ -70,6 +70,16 @@ CREATE TABLE IF NOT EXISTS public.orders (
   updated_at timestamptz NOT NULL DEFAULT now()
 );
 
+CREATE TABLE IF NOT EXISTS 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
+);
+
 DO $$
 BEGIN
   IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_reader') THEN
@@ -83,8 +93,8 @@ $$;
 
 GRANT CONNECT ON DATABASE synapsor_support_billing_agent 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, public.credits, public.agent_actions, public.orders TO synapsor_reader, synapsor_writer;
+GRANT SELECT, INSERT, UPDATE ON public.synapsor_writeback_receipts TO synapsor_writer;
 GRANT UPDATE (plan_credit_cents, credit_reason, updated_at) ON public.customers TO 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/support-plan-credit/README.md

@@ -27,7 +27,7 @@ When working from this source checkout, use `corepack pnpm runner` in place of
 Validate the authored boundary before starting Docker:
 
 ```bash
-synapsor-runner dsl compile examples/support-plan-credit/contract.synapsor \
+synapsor-runner dsl compile examples/support-plan-credit/contract.synapsor.sql \
   --out /tmp/support-plan-credit.contract.json \
   --strict
 synapsor-runner contract validate /tmp/support-plan-credit.contract.json
@@ -192,7 +192,7 @@ tool metadata and results. For Claude, Cursor, or generic MCP clients, omit
 
 ## How The Policy Is Governed
 
-The auto-approval policy lives in `contract.synapsor`:
+The auto-approval policy lives in `contract.synapsor.sql`:
 
 ```sql
 AUTO APPROVE WHEN plan_credit_cents <= 2500

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

@@ -14,6 +14,16 @@ CREATE TABLE IF NOT EXISTS public.customers (
   private_notes text
 );
 
+CREATE TABLE IF NOT EXISTS 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
+);
+
 INSERT INTO public.customers (
   id,
   tenant_id,
@@ -87,6 +97,6 @@ $$;
 
 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;
+GRANT SELECT, INSERT, UPDATE ON public.synapsor_writeback_receipts TO synapsor_writer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "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",

package/schemas/synapsor.runner.schema.json

@@ -5,12 +5,36 @@
   "description": "Configuration for local Synapsor Runner MCP capabilities over Postgres/MySQL.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["version", "mode", "sources", "trusted_context", "capabilities"],
+  "required": ["version", "mode"],
+  "allOf": [
+    {
+      "if": { "properties": { "mode": { "const": "cloud" } }, "required": ["mode"] },
+      "then": { "required": ["cloud"] },
+      "else": { "required": ["sources"] }
+    },
+    {
+      "if": { "required": ["contracts"] },
+      "then": {},
+      "else": {
+        "if": { "properties": { "mode": { "not": { "const": "cloud" } } }, "required": ["mode"] },
+        "then": {
+          "required": ["capabilities"],
+          "properties": { "capabilities": { "minItems": 1 } },
+          "anyOf": [
+            { "required": ["trusted_context"] },
+            { "required": ["contexts"] }
+          ]
+        }
+      }
+    }
+  ],
   "properties": {
     "version": {
+      "description": "Runner configuration contract version. Version 1 is the current public format.",
       "const": 1
     },
     "mode": {
+      "description": "Local execution mode. review permits proposals and trusted writeback; cloud delegates reviewed tools to Synapsor Cloud.",
       "type": "string",
       "enum": ["read_only", "shadow", "review", "cloud"]
     },
@@ -21,20 +45,24 @@
       "default": 1
     },
     "strict": {
+      "description": "Reject unknown configuration keys when true.",
       "type": "boolean",
       "default": true
     },
     "storage": {
+      "description": "Local proposal, evidence, receipt, and replay ledger. Relative sqlite_path values resolve from the Runner process working directory.",
       "type": "object",
       "additionalProperties": false,
       "properties": {
         "sqlite_path": {
+          "description": "SQLite ledger path. The file can contain visible business-data evidence and is created with owner-only permissions on POSIX.",
           "type": "string",
           "minLength": 1
         }
       }
     },
     "sources": {
+      "description": "Named Postgres/MySQL sources. Contract SOURCE names must match these keys.",
       "type": "object",
       "minProperties": 1,
       "additionalProperties": {
@@ -42,30 +70,69 @@
       }
     },
     "trusted_context": {
+      "description": "Default operator-controlled tenant/principal binding. These values are never model arguments.",
       "$ref": "#/$defs/trusted_context"
     },
     "contexts": {
+      "description": "Named trusted contexts referenced by capabilities or portable contracts.",
       "type": "object",
       "additionalProperties": {
         "$ref": "#/$defs/trusted_context"
       }
     },
     "executors": {
+      "description": "Trusted app-owned writeback executors. URLs, tokens, and commands are referenced through environment-variable names.",
       "type": "object",
       "additionalProperties": {
         "$ref": "#/$defs/executor"
       }
     },
-    "capabilities": {
+    "contracts": {
+      "description": "Portable @synapsor/spec contract files. Relative paths resolve from this config file's directory.",
       "type": "array",
       "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "capabilities": {
+      "description": "Embedded compatibility capabilities. May be empty when contracts supplies the capability catalog.",
+      "type": "array",
+      "minItems": 0,
       "items": {
         "$ref": "#/$defs/capability"
       }
     },
+    "policies": {
+      "description": "Embedded reviewed policies. Contract-authored policies are merged into the same runtime catalog.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/policy" }
+    },
+    "approvals": {
+      "description": "Local approval behavior overrides.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "disable_auto_approval": { "type": "boolean" }
+      }
+    },
     "cloud": {
       "type": "object",
-      "additionalProperties": true
+      "additionalProperties": false,
+      "required": ["base_url_env", "runner_token_env", "adapter_id"],
+      "properties": {
+        "base_url_env": { "$ref": "#/$defs/env_name" },
+        "runner_token_env": { "$ref": "#/$defs/env_name" },
+        "runner_id": { "type": "string", "minLength": 1 },
+        "runner_version": { "type": "string", "minLength": 1 },
+        "project_id": { "type": "string", "minLength": 1 },
+        "adapter_id": { "type": "string", "minLength": 1 },
+        "source_id": { "type": "string", "minLength": 1 },
+        "engines": { "type": "array", "minItems": 1, "items": { "enum": ["postgres", "mysql"] } },
+        "capabilities": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+        "session": { "type": "object" }
+      }
     }
   },
   "$defs": {
@@ -94,15 +161,18 @@
           "enum": ["postgres", "mysql"]
         },
         "read_url_env": {
+          "description": "Environment variable containing the least-privilege read connection URL.",
           "$ref": "#/$defs/env_name"
         },
         "write_url_env": {
+          "description": "Environment variable containing the separate trusted writer URL. It is never exposed over MCP.",
           "$ref": "#/$defs/env_name"
         },
         "read_only": {
           "type": "boolean"
         },
         "statement_timeout_ms": {
+          "description": "Per-read database statement timeout in milliseconds.",
           "type": "integer",
           "minimum": 1
         },
@@ -295,9 +365,16 @@
             },
             "required_role": {
               "type": "string"
+            },
+            "policy": {
+              "type": "string",
+              "minLength": 1
             }
           }
         },
+        "writeback": {
+          "$ref": "#/$defs/writeback"
+        },
         "single_tenant_dev_ack": {
           "type": "boolean"
         }
@@ -410,6 +487,42 @@
           }
         }
       }
+    },
+    "writeback": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode"],
+      "properties": {
+        "mode": {
+          "enum": ["direct_sql", "app_handler", "cloud_worker", "none"]
+        },
+        "executor": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "kind"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["approval", "settlement", "scope", "custom"] },
+        "mode": { "type": "string" },
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["field", "max"],
+            "properties": {
+              "field": { "$ref": "#/$defs/identifier" },
+              "max": { "type": "integer", "minimum": 0 }
+            }
+          }
+        }
+      }
     }
   }
 }