@synapsor/runner 1.5.3 → 1.6.0

package/fixtures/compatibility/published-1.5.4/sources/packages/spec/fixtures/conformance/bounded-set-threats/contract.json

@@ -0,0 +1,115 @@
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "metadata": { "name": "bounded-set-threats", "version": "1.0.0" },
+  "contexts": [
+    {
+      "name": "trusted_operator",
+      "bindings": [
+        { "name": "tenant_id", "source": "environment", "key": "SYNAPSOR_TENANT_ID", "required": true },
+        { "name": "principal", "source": "environment", "key": "SYNAPSOR_PRINCIPAL", "required": true }
+      ],
+      "tenant_binding": "tenant_id",
+      "principal_binding": "principal"
+    }
+  ],
+  "capabilities": [
+    {
+      "name": "billing.close_overdue_invoices",
+      "kind": "proposal",
+      "context": "trusted_operator",
+      "source": "local_postgres",
+      "subject": { "schema": "public", "table": "invoices", "primary_key": "id", "tenant_key": "tenant_id", "conflict_key": "version" },
+      "args": { "reason": { "type": "string", "required": true, "max_length": 500 } },
+      "visible_fields": ["id", "tenant_id", "status", "balance_cents", "version"],
+      "kept_out_fields": ["internal_risk_score"],
+      "evidence": { "required": true, "query_audit": true },
+      "proposal": {
+        "action": "close_overdue",
+        "operation": {
+          "kind": "update",
+          "cardinality": "set",
+          "selection": { "all": [{ "column": "status", "operator": "eq", "value": "overdue" }] },
+          "max_rows": 10,
+          "aggregate_bounds": [{ "column": "balance_cents", "measure": "before", "maximum": 50000 }],
+          "version_advance": { "column": "version", "strategy": "integer_increment" }
+        },
+        "allowed_fields": ["status", "close_reason"],
+        "patch": { "status": { "fixed": "closed" }, "close_reason": { "from_arg": "reason" } },
+        "conflict_guard": { "column": "version" },
+        "approval": { "mode": "human", "required_role": "billing_reviewer" },
+        "writeback": { "mode": "direct_sql" }
+      }
+    },
+    {
+      "name": "billing.delete_expired_drafts",
+      "kind": "proposal",
+      "context": "trusted_operator",
+      "source": "local_postgres",
+      "subject": { "schema": "public", "table": "invoice_drafts", "primary_key": "id", "tenant_key": "tenant_id", "conflict_key": "version" },
+      "args": { "reason": { "type": "string", "required": true, "max_length": 500 } },
+      "visible_fields": ["id", "tenant_id", "status", "estimated_cents", "version"],
+      "evidence": { "required": true, "query_audit": true },
+      "proposal": {
+        "action": "delete_expired_drafts",
+        "operation": {
+          "kind": "delete",
+          "cardinality": "set",
+          "selection": { "all": [{ "column": "status", "operator": "eq", "value": "expired" }] },
+          "max_rows": 5,
+          "aggregate_bounds": [{ "column": "estimated_cents", "measure": "before", "maximum": 10000 }]
+        },
+        "allowed_fields": [],
+        "patch": {},
+        "conflict_guard": { "column": "version" },
+        "approval": { "mode": "human", "required_role": "billing_reviewer", "required_approvals": 2 },
+        "writeback": { "mode": "direct_sql" }
+      }
+    },
+    {
+      "name": "billing.create_credits",
+      "kind": "proposal",
+      "context": "trusted_operator",
+      "source": "local_postgres",
+      "subject": { "schema": "public", "table": "account_credits", "primary_key": "id", "tenant_key": "tenant_id" },
+      "args": {
+        "items": {
+          "type": "object_array",
+          "required": true,
+          "max_items": 10,
+          "fields": {
+            "id": { "type": "string", "required": true, "max_length": 128 },
+            "external_id": { "type": "string", "required": true, "max_length": 128 },
+            "amount_cents": { "type": "number", "required": true, "minimum": 1, "maximum": 2500 },
+            "reason": { "type": "string", "required": true, "max_length": 500 }
+          }
+        }
+      },
+      "visible_fields": ["id", "tenant_id", "external_id", "amount_cents", "reason", "version"],
+      "kept_out_fields": ["internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "proposal": {
+        "action": "create_credits",
+        "operation": {
+          "kind": "insert",
+          "cardinality": "set",
+          "batch": { "items_from_arg": "items" },
+          "max_rows": 10,
+          "aggregate_bounds": [{ "column": "amount_cents", "measure": "after", "maximum": 25000 }],
+          "deduplication": {
+            "components": [
+              { "column": "tenant_id", "source": "trusted_tenant" },
+              { "column": "id", "source": "item_field", "item_field": "id" },
+              { "column": "external_id", "source": "item_field", "item_field": "external_id" }
+            ]
+          }
+        },
+        "allowed_fields": ["amount_cents", "reason"],
+        "patch": { "amount_cents": { "from_item": "amount_cents" }, "reason": { "from_item": "reason" } },
+        "numeric_bounds": { "amount_cents": { "minimum": 1, "maximum": 2500 } },
+        "approval": { "mode": "human", "required_role": "billing_reviewer" },
+        "writeback": { "mode": "direct_sql" }
+      }
+    }
+  ]
+}

package/fixtures/compatibility/published-1.5.4/sources/packages/spec/fixtures/conformance/principal-row-scope/contract.json

@@ -0,0 +1,78 @@
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "metadata": {
+    "name": "trusted principal row scope",
+    "description": "Tenant-additive row authority for two case managers in one hospital."
+  },
+  "contexts": [
+    {
+      "name": "care_session",
+      "bindings": [
+        {
+          "name": "hospital_id",
+          "source": "http_claim",
+          "key": "hospital_id",
+          "required": true
+        },
+        {
+          "name": "principal",
+          "source": "http_claim",
+          "key": "sub",
+          "required": true
+        }
+      ],
+      "tenant_binding": "hospital_id",
+      "principal_binding": "principal"
+    }
+  ],
+  "resources": [],
+  "capabilities": [
+    {
+      "name": "care.inspect_assigned_patient",
+      "description": "Inspect one patient assigned to the authenticated case manager within the trusted hospital.",
+      "returns_hint": "Returns reviewed patient fields and evidence only when both tenant and assignee locks match.",
+      "kind": "read",
+      "context": "care_session",
+      "source": "local_postgres",
+      "subject": {
+        "schema": "public",
+        "table": "patients",
+        "primary_key": "id",
+        "tenant_key": "hospital_id",
+        "principal_scope_key": "assigned_to",
+        "conflict_key": "updated_at"
+      },
+      "args": {
+        "patient_id": {
+          "type": "string",
+          "required": true,
+          "description": "Reviewed patient identifier.",
+          "max_length": 128
+        }
+      },
+      "lookup": {
+        "id_from_arg": "patient_id"
+      },
+      "visible_fields": [
+        "id",
+        "hospital_id",
+        "display_name",
+        "care_status",
+        "updated_at"
+      ],
+      "kept_out_fields": [
+        "assigned_to",
+        "diagnosis_notes",
+        "insurance_member_id"
+      ],
+      "evidence": {
+        "required": true,
+        "query_audit": true
+      },
+      "max_rows": 1
+    }
+  ],
+  "workflows": [],
+  "policies": []
+}

package/fixtures/compatibility/published-1.5.4/sources/packages/spec/fixtures/conformance/proposal-capability/contract.json

@@ -0,0 +1,101 @@
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "metadata": {
+    "name": "proposal capability conformance"
+  },
+  "resources": [
+    {
+      "name": "billing_invoices",
+      "engine": "postgres",
+      "schema": "public",
+      "table": "invoices",
+      "primary_key": "id",
+      "tenant_key": "tenant_id",
+      "conflict_key": "updated_at"
+    }
+  ],
+  "contexts": [
+    {
+      "name": "local_operator",
+      "bindings": [
+        {
+          "name": "tenant_id",
+          "source": "environment",
+          "key": "SYNAPSOR_TENANT_ID"
+        },
+        {
+          "name": "principal",
+          "source": "environment",
+          "key": "SYNAPSOR_PRINCIPAL"
+        }
+      ],
+      "tenant_binding": "tenant_id",
+      "principal_binding": "principal"
+    }
+  ],
+  "capabilities": [
+    {
+      "name": "billing.propose_late_fee_waiver",
+      "kind": "proposal",
+      "context": "local_operator",
+      "source": "local_postgres",
+      "subject": {
+        "resource": "billing_invoices"
+      },
+      "args": {
+        "invoice_id": {
+          "type": "string",
+          "required": true
+        },
+        "waiver_reason": {
+          "type": "string",
+          "required": true
+        }
+      },
+      "lookup": {
+        "id_from_arg": "invoice_id"
+      },
+      "visible_fields": [
+        "id",
+        "tenant_id",
+        "late_fee_cents",
+        "waiver_reason",
+        "updated_at"
+      ],
+      "kept_out_fields": [
+        "card_token"
+      ],
+      "evidence": {
+        "required": true,
+        "query_audit": true
+      },
+      "max_rows": 1,
+      "proposal": {
+        "action": "billing.waive_late_fee",
+        "allowed_fields": [
+          "late_fee_cents",
+          "waiver_reason"
+        ],
+        "patch": {
+          "late_fee_cents": {
+            "fixed": 0
+          },
+          "waiver_reason": {
+            "from_arg": "waiver_reason"
+          }
+        },
+        "conflict_guard": {
+          "column": "updated_at"
+        },
+        "approval": {
+          "mode": "human",
+          "required_role": "billing_lead"
+        },
+        "writeback": {
+          "mode": "direct_sql"
+        }
+      }
+    }
+  ]
+}

package/fixtures/compatibility/published-1.5.4/sources/packages/spec/fixtures/conformance/reversible-change-sets/contract.json

@@ -0,0 +1,98 @@
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "metadata": {
+    "name": "reviewed-reversible-change-sets",
+    "version": "1.4.0"
+  },
+  "contexts": [
+    {
+      "name": "trusted_operator",
+      "bindings": [
+        { "name": "tenant_id", "source": "environment", "key": "SYNAPSOR_TENANT_ID", "required": true },
+        { "name": "principal", "source": "environment", "key": "SYNAPSOR_PRINCIPAL", "required": true }
+      ],
+      "tenant_binding": "tenant_id",
+      "principal_binding": "principal"
+    }
+  ],
+  "capabilities": [
+    {
+      "name": "billing.adjust_credit",
+      "kind": "proposal",
+      "context": "trusted_operator",
+      "source": "local_postgres",
+      "subject": {
+        "schema": "public",
+        "table": "account_credits",
+        "primary_key": "id",
+        "tenant_key": "tenant_id",
+        "conflict_key": "version"
+      },
+      "args": {
+        "credit_id": { "type": "string", "required": true, "max_length": 128 },
+        "amount_cents": { "type": "number", "required": true, "minimum": 0, "maximum": 2500 }
+      },
+      "lookup": { "id_from_arg": "credit_id" },
+      "visible_fields": ["id", "tenant_id", "amount_cents", "version"],
+      "kept_out_fields": ["internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "proposal": {
+        "action": "adjust_credit",
+        "operation": {
+          "kind": "update",
+          "cardinality": "single",
+          "version_advance": { "column": "version", "strategy": "integer_increment" }
+        },
+        "allowed_fields": ["amount_cents"],
+        "patch": { "amount_cents": { "from_arg": "amount_cents" } },
+        "numeric_bounds": { "amount_cents": { "minimum": 0, "maximum": 2500 } },
+        "reversibility": { "mode": "reviewed_inverse" },
+        "conflict_guard": { "column": "version" },
+        "approval": { "mode": "human", "required_role": "billing_reviewer", "required_approvals": 2 },
+        "writeback": { "mode": "direct_sql" }
+      }
+    },
+    {
+      "name": "billing.create_credit",
+      "kind": "proposal",
+      "context": "trusted_operator",
+      "source": "local_postgres",
+      "subject": {
+        "schema": "public",
+        "table": "account_credits",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "amount_cents": { "type": "number", "required": true, "minimum": 1, "maximum": 2500 },
+        "reason": { "type": "string", "required": true, "max_length": 500 }
+      },
+      "visible_fields": ["id", "tenant_id", "amount_cents", "reason"],
+      "kept_out_fields": ["internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "proposal": {
+        "action": "create_credit",
+        "operation": {
+          "kind": "insert",
+          "cardinality": "single",
+          "deduplication": {
+            "components": [
+              { "column": "tenant_id", "source": "trusted_tenant" },
+              { "column": "id", "source": "proposal_id" }
+            ]
+          }
+        },
+        "allowed_fields": ["amount_cents", "reason"],
+        "patch": {
+          "amount_cents": { "from_arg": "amount_cents" },
+          "reason": { "from_arg": "reason" }
+        },
+        "numeric_bounds": { "amount_cents": { "minimum": 1, "maximum": 2500 } },
+        "reversibility": { "mode": "reviewed_inverse" },
+        "approval": { "mode": "human", "required_role": "billing_reviewer" },
+        "writeback": { "mode": "direct_sql" }
+      }
+    }
+  ]
+}

package/fixtures/compatibility/published-1.5.4/sources/packages/spec/fixtures/valid/basic-read.contract.json

@@ -0,0 +1,60 @@
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "contexts": [
+    {
+      "name": "local_operator",
+      "bindings": [
+        {
+          "name": "tenant_id",
+          "source": "environment",
+          "key": "SYNAPSOR_TENANT_ID"
+        },
+        {
+          "name": "principal",
+          "source": "environment",
+          "key": "SYNAPSOR_PRINCIPAL"
+        }
+      ],
+      "tenant_binding": "tenant_id",
+      "principal_binding": "principal"
+    }
+  ],
+  "capabilities": [
+    {
+      "name": "billing.inspect_invoice",
+      "kind": "read",
+      "context": "local_operator",
+      "subject": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id",
+        "conflict_key": "updated_at"
+      },
+      "args": {
+        "invoice_id": {
+          "type": "string",
+          "required": true
+        }
+      },
+      "lookup": {
+        "id_from_arg": "invoice_id"
+      },
+      "visible_fields": [
+        "id",
+        "tenant_id",
+        "late_fee_cents",
+        "updated_at"
+      ],
+      "kept_out_fields": [
+        "card_token"
+      ],
+      "evidence": {
+        "required": true,
+        "query_audit": true
+      },
+      "max_rows": 1
+    }
+  ]
+}

package/llms.txt

@@ -0,0 +1,37 @@
+# Synapsor Runner
+
+Synapsor Runner is the Apache-2.0 MCP runtime that gives AI agents reviewed
+Postgres/MySQL business capabilities instead of raw SQL. Credentials, trusted
+tenant/principal identity, activation, approval, and commit stay outside the
+model-facing tool surface.
+
+Start here:
+- README: https://github.com/Synapsor/Synapsor-Runner
+- Auto Boundary, Scoped Explore, and Protect: https://github.com/Synapsor/Synapsor-Runner/blob/main/docs/auto-boundary-and-scoped-explore.md
+- Connect a staging database: https://github.com/Synapsor/Synapsor-Runner/blob/main/docs/getting-started-own-database.md
+- Security boundary: https://github.com/Synapsor/Synapsor-Runner/blob/main/docs/security-boundary.md
+- Current scope: https://github.com/Synapsor/Synapsor-Runner/blob/main/docs/current-scope.md
+- Current limitations: https://github.com/Synapsor/Synapsor-Runner/blob/main/docs/limitations.md
+- DSL reference: https://github.com/Synapsor/Synapsor-Runner/blob/main/docs/dsl-reference.md
+- MCP audit: https://github.com/Synapsor/Synapsor-Runner/blob/main/docs/mcp-audit.md
+
+Current adoption loop:
+Connect staging -> deterministic whole-schema draft -> human boundary review ->
+bounded row or PM-style aggregate Explore in local Cursor -> Protect This Query
+-> digest-bound human activation -> named production capability -> proposal ->
+external approval -> guarded commit -> receipt and replay.
+
+Important boundaries:
+- No raw SQL or SQL-string tool argument.
+- Scoped Explore is disabled by default and is local development/staging
+  authoring only. Production and shared/remote HTTP never advertise it.
+- Aggregate Explore is a reviewed analytical cube: approved measures,
+  dimensions, time buckets, filters, at most one proven many-to-one path,
+  suppression, and extraction/differencing budgets.
+- Auto Boundary and Protect are deterministic and use no LLM.
+- Generated authority starts disabled. The model cannot activate, approve,
+  apply, commit, or widen it.
+- Existing hand-authored 1.x contracts and established CLI routes do not
+  require Auto Boundary, Workbench, rescanning, or generation locks.
+- Rich multi-table transactions and external side effects remain app-owned
+  executor work after approval.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "1.5.3",
+  "version": "1.6.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",
@@ -40,6 +40,7 @@
     "docs/**/*.md",
     "examples/dangerous-mcp-tools.json",
     "examples/app-owned-writeback/**",
+    "examples/auto-boundary-churn/**",
     "examples/claude-desktop-postgres/**",
     "examples/cursor-postgres/**",
     "examples/mcp-postgres-billing-app-handler/**",
@@ -62,7 +63,8 @@
     "LICENSE",
     "NOTICE",
     "THREAT_MODEL.md",
-    "TRADEMARKS.md"
+    "TRADEMARKS.md",
+    "llms.txt"
   ],
   "keywords": [
     "mcp",
@@ -83,7 +85,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
-    "@synapsor/spec": "^1.4.2",
     "jose": "6.2.3",
     "mysql2": "^3.11.0",
     "pdf-lib": "1.17.1",
@@ -92,9 +93,11 @@
     "vscode-languageserver": "9.0.1",
     "vscode-languageserver-textdocument": "1.0.12",
     "yaml": "2.8.3",
-    "zod": "^3.25.0"
+    "zod": "^3.25.0",
+    "@synapsor/spec": "^1.5.0"
   },
   "devDependencies": {
+    "@types/pg": "^8.11.0",
     "ajv": "^8.17.1",
     "vitest": "^3.2.0"
   },

package/schemas/synapsor.runner.schema.json

@@ -132,6 +132,23 @@
         "minLength": 1
       }
     },
+    "generated_authority": {
+      "description": "Opt-in fail-closed drift enforcement for Auto Boundary and Protect This Query output. Legacy/manual projects omit this object and are not scanned.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["generation_lock_path", "enforcement"],
+      "properties": {
+        "generation_lock_path": {
+          "description": "Local generation-lock file. Relative paths resolve from this config file's directory.",
+          "type": "string",
+          "minLength": 1,
+          "not": { "pattern": "://" }
+        },
+        "enforcement": {
+          "const": "required"
+        }
+      }
+    },
     "capabilities": {
       "description": "Embedded compatibility capabilities. May be empty when contracts supplies the capability catalog.",
       "type": "array",
@@ -293,6 +310,80 @@
         "max_response_bytes": { "type": "integer", "minimum": 1024, "maximum": 10485760 }
       }
     },
+    "http_security": {
+      "description": "Runner-only deployment security for networked MCP. Credential values remain in environment or secret-manager wiring and never enter portable contracts.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "deployment": {
+          "description": "Trust topology. shared requires signed per-session http_claims identity; single_tenant may use one opaque service token.",
+          "enum": ["loopback", "single_tenant", "shared"]
+        },
+        "channel": {
+          "description": "How a remote listener is protected in transit. insecure_http_break_glass is unsafe and still requires authentication.",
+          "enum": ["direct_tls", "trusted_tls_proxy", "insecure_http_break_glass"]
+        },
+        "static_token": {
+          "description": "Environment-variable names for the current opaque endpoint token and at most one previous rotation token.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "active_env": { "$ref": "#/$defs/env_name" },
+            "previous_env": { "$ref": "#/$defs/env_name" }
+          }
+        },
+        "oauth_resource": {
+          "description": "RFC 9728 metadata for Runner as an OAuth protected resource. The external authorization server issues tokens; Runner only verifies them.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["resource", "authorization_servers"],
+          "properties": {
+            "resource": { "type": "string", "pattern": "^https://" },
+            "authorization_servers": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 8,
+              "uniqueItems": true,
+              "items": { "type": "string", "pattern": "^https://" }
+            },
+            "scopes_supported": { "type": "array", "minItems": 1, "maxItems": 64, "uniqueItems": true, "items": { "$ref": "#/$defs/oauth_scope" } },
+            "required_scopes": { "type": "array", "minItems": 1, "maxItems": 64, "uniqueItems": true, "items": { "$ref": "#/$defs/oauth_scope" } },
+            "resource_name": { "type": "string", "minLength": 1, "maxLength": 128 },
+            "resource_documentation": { "type": "string", "pattern": "^https://" }
+          }
+        },
+        "allowed_origins": {
+          "description": "Exact browser origins accepted on HTTP MCP requests. Native clients may omit Origin. Wildcards are forbidden.",
+          "type": "array",
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^https?://[^/*]+(?::[0-9]+)?$" }
+        },
+        "allowed_hosts": {
+          "description": "Exact HTTP Host authorities accepted by the direct listener or trusted proxy. Forwarded host headers are never authority.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^(?:\\[[0-9A-Fa-f:.]+\\]|[A-Za-z0-9.-]+)(?::[0-9]{1,5})?$" }
+        },
+        "limits": {
+          "description": "Bounded HTTP request, header, connection, and session resource limits.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "max_request_bytes": { "type": "integer", "minimum": 1024, "maximum": 16777216 },
+            "max_header_bytes": { "type": "integer", "minimum": 4096, "maximum": 65536 },
+            "max_sessions": { "type": "integer", "minimum": 1, "maximum": 100000 },
+            "session_idle_timeout_seconds": { "type": "integer", "minimum": 10, "maximum": 86400 },
+            "request_timeout_ms": { "type": "integer", "minimum": 1000, "maximum": 300000 },
+            "headers_timeout_ms": { "type": "integer", "minimum": 1000, "maximum": 120000 },
+            "keep_alive_timeout_ms": { "type": "integer", "minimum": 1000, "maximum": 120000 },
+            "max_connections": { "type": "integer", "minimum": 1, "maximum": 100000 }
+          }
+        }
+      }
+    },
     "cloud": {
       "type": "object",
       "additionalProperties": false,
@@ -347,6 +438,12 @@
       "type": "string",
       "pattern": "^[A-Z_][A-Z0-9_]*$"
     },
+    "oauth_scope": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[!#-\\[\\]-~]+$"
+    },
     "identifier": {
       "type": "string",
       "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
@@ -408,7 +505,7 @@
             {
               "type": "object",
               "additionalProperties": false,
-              "required": ["mode", "tenant_setting", "principal_setting"],
+              "required": ["mode", "tenant_setting"],
               "properties": {
                 "mode": { "const": "postgres_rls" },
                 "tenant_setting": {