@synapsor/runner 0.1.15 → 1.0.0

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/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/package.json

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

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,53 @@
       "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
+        },
+        "shared_postgres": {
+          "description": "Optional shared Postgres ledger. mode=mirror coordinates bounded CLI mutations with a schema-scoped advisory lock while the live runtime store remains local SQLite. mode=runtime_store makes MCP serving use Postgres as the primary proposal/evidence/replay store.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode", "url_env"],
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": ["mirror", "runtime_store", "disabled"]
+            },
+            "url_env": {
+              "description": "Environment variable containing the shared ledger Postgres URL. The URL itself must not be stored in config.",
+              "type": "string",
+              "pattern": "^[A-Z_][A-Z0-9_]*$"
+            },
+            "schema": {
+              "description": "Postgres schema for shared ledger tables.",
+              "type": "string",
+              "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+              "default": "synapsor_runner"
+            },
+            "lock_timeout_ms": {
+              "description": "How long mirror-mode CLI commands wait for the schema-scoped advisory lock.",
+              "type": "integer",
+              "minimum": 0,
+              "default": 10000
+            }
+          }
         }
       }
     },
     "sources": {
+      "description": "Named Postgres/MySQL sources. Contract SOURCE names must match these keys.",
       "type": "object",
       "minProperties": 1,
       "additionalProperties": {
@@ -42,30 +99,116 @@
       }
     },
     "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" }
+      }
+    },
+    "operator_identity": {
+      "description": "Operator identity used by approve, reject, and apply. signed_key verifies possession of a registered private key; dev_env is local-development compatibility only.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider"],
+      "allOf": [
+        {
+          "if": { "properties": { "provider": { "const": "signed_key" } }, "required": ["provider"] },
+          "then": { "required": ["operators"] }
+        }
+      ],
+      "properties": {
+        "provider": { "enum": ["dev_env", "signed_key"] },
+        "actor_env": { "$ref": "#/$defs/env_name" },
+        "roles_env": { "$ref": "#/$defs/env_name" },
+        "apply_roles": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/identifier" } },
+        "operators": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["public_key_path", "roles"],
+            "properties": {
+              "public_key_path": { "type": "string", "minLength": 1 },
+              "roles": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/identifier" } }
+            }
+          }
+        }
+      }
+    },
+    "session_auth": {
+      "description": "Signed per-session identity for Streamable HTTP http_claims contexts. The HMAC secret stays in an environment variable.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "secret_env"],
+      "properties": {
+        "provider": { "const": "jwt_hs256" },
+        "secret_env": { "$ref": "#/$defs/env_name" },
+        "previous_secret_env": { "$ref": "#/$defs/env_name" },
+        "issuer": { "type": "string", "minLength": 1 },
+        "audience": { "type": "string", "minLength": 1 },
+        "tenant_claim": { "$ref": "#/$defs/identifier" },
+        "principal_claim": { "$ref": "#/$defs/identifier" },
+        "clock_skew_seconds": { "type": "integer", "minimum": 0, "maximum": 300 }
+      }
+    },
     "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 +237,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 +441,16 @@
             },
             "required_role": {
               "type": "string"
+            },
+            "policy": {
+              "type": "string",
+              "minLength": 1
             }
           }
         },
+        "writeback": {
+          "$ref": "#/$defs/writeback"
+        },
         "single_tenant_dev_ack": {
           "type": "boolean"
         }
@@ -410,6 +563,66 @@
           }
         }
       }
+    },
+    "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 }
+            }
+          }
+        },
+        "limits": {
+          "description": "Reviewed aggregate ceilings for policy auto-approval. Exceeding one falls back to human review.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "max", "period"],
+            "allOf": [
+              {
+                "if": { "properties": { "kind": { "const": "total" } }, "required": ["kind"] },
+                "then": { "required": ["field"] },
+                "else": { "not": { "required": ["field"] } }
+              }
+            ],
+            "properties": {
+              "kind": { "enum": ["count", "total"] },
+              "max": { "type": "integer", "minimum": 0 },
+              "period": { "const": "day" },
+              "field": { "$ref": "#/$defs/identifier" },
+              "scope": { "enum": ["tenant_policy", "tenant_policy_object"] }
+            }
+          }
+        }
+      }
     }
   }
 }