@synapsor/runner 1.5.4 → 1.6.1

package/fixtures/compatibility/published-1.6.0/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.6.0/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/fixtures/protocol/MANIFEST.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "synapsor.protocol-manifest.v1",
   "protocol_set": "database-mcp-writeback",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "hash_algorithm": "sha256",
   "note": "This manifest is copied in Synapsor main protocol/MANIFEST.json and synapsor-runner fixtures/protocol/MANIFEST.json. Hashes are over the checked-in JSON artifact bytes.",
   "artifacts": [
@@ -10,6 +10,11 @@
       "name": "change-set.bounded-update.v3.json",
       "sha256": "9d60a96cd5f14b9cf36f635214398437676bd90fbb180b3befe1596f982a2f02"
     },
+    {
+      "kind": "fixture",
+      "name": "change-set.freshness-update.v2.json",
+      "sha256": "cf541387dcc13ccf5e82c38da80e7f5a8ae9d95b6bcd29b7c63542abbccef401"
+    },
     {
       "kind": "fixture",
       "name": "change-set.delete.v2.json",
@@ -75,6 +80,16 @@
       "name": "execution-receipt.update-applied.v2.json",
       "sha256": "31be662ec370db24528f71c60423a9d4a6da8a7bc2922b4d222d92d650568743"
     },
+    {
+      "kind": "fixture",
+      "name": "freshness-authority.invoice.v1.json",
+      "sha256": "f8abfff7ea058b81aa9ef4e3281fabe1105ed8ed91ad5dde3c3b08d694fe1a39"
+    },
+    {
+      "kind": "fixture",
+      "name": "freshness-proof.fresh.v1.json",
+      "sha256": "895083bdcc226f16f86131a90263104b22be60a60e855e9c106dbc15f636b3b3"
+    },
     {
       "kind": "fixture",
       "name": "runner-registration.v1.json",
@@ -95,6 +110,11 @@
       "name": "writeback-job.delete.v2.json",
       "sha256": "4169885a125528a09e06b55184969edd96e2a179711c664d4a61622f0d0b3b19"
     },
+    {
+      "kind": "fixture",
+      "name": "writeback-job.freshness-update.v2.json",
+      "sha256": "e703ee6a4c333c4fdbf2d7e6d264a9b537e114038e258ed7f87349f3add6a718"
+    },
     {
       "kind": "fixture",
       "name": "writeback-job.insert.v2.json",
@@ -113,17 +133,17 @@
     {
       "kind": "schema",
       "name": "change-set.v1.schema.json",
-      "sha256": "18f76efd97424efab986b6fb0af87ad0eeafd4314393ed7f83f14afe09d625eb"
+      "sha256": "686a3696dc92ad7562035cdef972bbc9bc6dcb2e36368ada72d133d92a31436c"
     },
     {
       "kind": "schema",
       "name": "change-set.v2.schema.json",
-      "sha256": "bd9999361258c5554ffa2791d7c6469beffc5b875e775f5f0c80cea36132eaa4"
+      "sha256": "b7ea55cf2aa0b7914ca7383d4590a1a4e0235e6551f2285aac64153b3f196405"
     },
     {
       "kind": "schema",
       "name": "change-set.v3.schema.json",
-      "sha256": "24a45eb4d9f29ab4cfe408bedeb0216dc29544fe39b515918d0c0f9742bba9cb"
+      "sha256": "a02cf865bb45271b3552c8fb4f1180522eb4fed3462429612d218a9468410c0f"
     },
     {
       "kind": "schema",
@@ -150,6 +170,16 @@
       "name": "execution-receipt.v4.schema.json",
       "sha256": "1f75e88da8340a71fba5c8dd16f19bc38a89615134b36d235c74122e2adea499"
     },
+    {
+      "kind": "schema",
+      "name": "freshness-authority.v1.schema.json",
+      "sha256": "6069026c5f56e3516d2b4043597c3efad20b41655bd4d8dea26bd7ae19d16d84"
+    },
+    {
+      "kind": "schema",
+      "name": "freshness-proof.v1.schema.json",
+      "sha256": "b4a26ab98e348928862520adf49418c8e16ad16e1c07af406cbe90a8ac5800ad"
+    },
     {
       "kind": "schema",
       "name": "inverse-descriptor.v1.schema.json",
@@ -163,17 +193,17 @@
     {
       "kind": "schema",
       "name": "writeback-job.v1.schema.json",
-      "sha256": "64238559297805e13c04cb8bf71be433e6fb1241594ca021415b1efb95214a01"
+      "sha256": "5d5e4c1d86e5419d72a321872c9387e85b3c8cc7e26ab6157998c11fca7dde11"
     },
     {
       "kind": "schema",
       "name": "writeback-job.v2.schema.json",
-      "sha256": "68110a5ed5b7867522cf86db8d177d2df3f96a458a4343bb77537bdcf304279b"
+      "sha256": "a6fd68f273b97c8d9f3911ffcb3ffb5d46c4a82b420e183c918d6688e4018117"
     },
     {
       "kind": "schema",
       "name": "writeback-job.v3.schema.json",
-      "sha256": "3bd46747e737e79bff90dc0496c270bc93d6a913db750ea00486be9a45714831"
+      "sha256": "7b8fa3e3fcd8b918f81cde25eec82f4c7e813a7221cf6fee0e9c69033ed80629"
     },
     {
       "kind": "schema",

package/fixtures/protocol/change-set.freshness-update.v2.json

@@ -0,0 +1,58 @@
+{
+  "schema_version": "synapsor.change-set.v2",
+  "proposal_id": "wrp_update_2001",
+  "proposal_version": 1,
+  "action": "billing.propose_plan_credit_update",
+  "operation": "single_row_update",
+  "mode": "review_required",
+  "principal": { "id": "operator_demo", "source": "trusted_session" },
+  "scope": { "tenant_id": "tenant_demo", "business_object": "account_credit", "object_id": "credit_2001" },
+  "source": {
+    "kind": "external_postgres",
+    "source_id": "src_billing_demo",
+    "schema": "public",
+    "table": "account_credits",
+    "primary_key": { "column": "id", "value": "credit_2001" }
+  },
+  "before": { "id": "credit_2001", "tenant_id": "tenant_demo", "amount_cents": 1000, "version": 7 },
+  "patch": { "amount_cents": 2500 },
+  "after": { "id": "credit_2001", "tenant_id": "tenant_demo", "amount_cents": 2500, "version": 8 },
+  "guards": {
+    "tenant": { "column": "tenant_id", "value": "tenant_demo" },
+    "allowed_columns": ["amount_cents"],
+    "expected_version": { "column": "version", "value": 7 },
+    "version_advance": { "column": "version", "strategy": "integer_increment" }
+  },
+  "freshness": {
+    "schema_version": "synapsor.freshness-authority.v1",
+    "required": true,
+    "target": { "mode": "exact_guard", "member_count": 1 },
+    "dependencies": [
+      {
+        "id": "invoice_eligibility",
+        "capability": "billing.inspect_invoice",
+        "source_id": "src_billing_demo",
+        "engine": "postgres",
+        "target": {
+          "schema": "public",
+          "table": "invoices",
+          "primary_key": { "column": "invoice_id", "value": "INV-3001" },
+          "tenant_column": "tenant_id"
+        },
+        "expected_version": { "column": "version", "value": 7 },
+        "evidence": {
+          "bundle_id": "ev_invoice_3001",
+          "query_fingerprint": "sha256:invoice-evidence"
+        },
+        "descriptor_digest": "sha256:c7f183d5697eff084d30ead6602383f6a0033c13080a859d2eb514d71ec4e9bf"
+      }
+    ],
+    "dependency_set_digest": "sha256:720d1300cc30f5732c864f41ef79767268095483b0bac93d871b19299886141b"
+  },
+  "evidence": { "bundle_id": "ev_update_2001", "query_fingerprint": "sha256:update-evidence", "items": [] },
+  "approval": { "status": "pending", "required_role": "billing_reviewer" },
+  "writeback": { "status": "not_applied", "mode": "trusted_worker_required" },
+  "source_database_mutated": false,
+  "integrity": { "proposal_hash": "sha256:update-proposal" },
+  "created_at": "2026-07-23T17:59:00Z"
+}

package/fixtures/protocol/freshness-authority.invoice.v1.json

@@ -0,0 +1,35 @@
+{
+  "schema_version": "synapsor.freshness-authority.v1",
+  "required": true,
+  "target": {
+    "mode": "exact_guard",
+    "member_count": 1
+  },
+  "dependencies": [
+    {
+      "id": "invoice_eligibility",
+      "capability": "billing.inspect_invoice",
+      "source_id": "src_billing_demo",
+      "engine": "postgres",
+      "target": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": {
+          "column": "invoice_id",
+          "value": "INV-3001"
+        },
+        "tenant_column": "tenant_id"
+      },
+      "expected_version": {
+        "column": "version",
+        "value": 7
+      },
+      "evidence": {
+        "bundle_id": "ev_invoice_3001",
+        "query_fingerprint": "sha256:invoice-evidence"
+      },
+      "descriptor_digest": "sha256:c7f183d5697eff084d30ead6602383f6a0033c13080a859d2eb514d71ec4e9bf"
+    }
+  ],
+  "dependency_set_digest": "sha256:720d1300cc30f5732c864f41ef79767268095483b0bac93d871b19299886141b"
+}

package/fixtures/protocol/freshness-proof.fresh.v1.json

@@ -0,0 +1,38 @@
+{
+  "schema_version": "synapsor.freshness-proof.v1",
+  "proposal_id": "wrp_update_2001",
+  "proposal_hash": "sha256:update-proposal",
+  "proposal_version": 1,
+  "dependency_set_digest": "sha256:720d1300cc30f5732c864f41ef79767268095483b0bac93d871b19299886141b",
+  "checked_at": "2026-07-23T18:00:00.000Z",
+  "valid_until": "2026-07-23T18:00:30.000Z",
+  "source_adapters": [
+    {
+      "source_id": "src_billing_demo",
+      "engine": "postgres"
+    }
+  ],
+  "result": "fresh",
+  "safe_code": "FRESHNESS_FRESH",
+  "target_count": 1,
+  "supporting_count": 1,
+  "checks": [
+    {
+      "id": "target",
+      "kind": "target",
+      "status": "fresh",
+      "safe_code": "FRESHNESS_TARGET_FRESH",
+      "expected_version_digest": "sha256:cf6cbc0a5d9b4fe7d9d3fd832e5e1b05b73fa6eefdc496fd95d7268ab1d9268c",
+      "observed_version_digest": "sha256:cf6cbc0a5d9b4fe7d9d3fd832e5e1b05b73fa6eefdc496fd95d7268ab1d9268c"
+    },
+    {
+      "id": "invoice_eligibility",
+      "kind": "supporting",
+      "status": "fresh",
+      "safe_code": "FRESHNESS_DEPENDENCY_FRESH",
+      "expected_version_digest": "sha256:cf6cbc0a5d9b4fe7d9d3fd832e5e1b05b73fa6eefdc496fd95d7268ab1d9268c",
+      "observed_version_digest": "sha256:cf6cbc0a5d9b4fe7d9d3fd832e5e1b05b73fa6eefdc496fd95d7268ab1d9268c"
+    }
+  ],
+  "proof_digest": "sha256:0030e42a6f494acdfd65fb4042c917444f2c6df621fcae5021b3d7d15fdc1877"
+}

package/fixtures/protocol/writeback-job.freshness-update.v2.json

@@ -0,0 +1,50 @@
+{
+  "schema_version": "synapsor.writeback-job.v2",
+  "writeback_job_id": "wbj_update_2001",
+  "proposal_id": "wrp_update_2001",
+  "proposal_version": 1,
+  "proposal_hash": "sha256:update-proposal",
+  "runner_scope": { "project_id": "project_demo", "source_id": "src_billing_demo" },
+  "engine": "postgres",
+  "target": {
+    "schema": "public",
+    "table": "account_credits",
+    "primary_key": { "column": "id", "value": "credit_2001" }
+  },
+  "tenant_guard": { "column": "tenant_id", "value": "tenant_demo" },
+  "allowed_columns": ["amount_cents"],
+  "mutation": {
+    "kind": "single_row_update",
+    "values": { "amount_cents": 2500 },
+    "conflict_guard": { "kind": "column", "column": "version", "expected_value": 7 },
+    "version_advance": { "column": "version", "strategy": "integer_increment" }
+  },
+  "freshness": {
+    "schema_version": "synapsor.freshness-authority.v1",
+    "required": true,
+    "target": { "mode": "exact_guard", "member_count": 1 },
+    "dependencies": [
+      {
+        "id": "invoice_eligibility",
+        "capability": "billing.inspect_invoice",
+        "source_id": "src_billing_demo",
+        "engine": "postgres",
+        "target": {
+          "schema": "public",
+          "table": "invoices",
+          "primary_key": { "column": "invoice_id", "value": "INV-3001" },
+          "tenant_column": "tenant_id"
+        },
+        "expected_version": { "column": "version", "value": 7 },
+        "evidence": {
+          "bundle_id": "ev_invoice_3001",
+          "query_fingerprint": "sha256:invoice-evidence"
+        },
+        "descriptor_digest": "sha256:c7f183d5697eff084d30ead6602383f6a0033c13080a859d2eb514d71ec4e9bf"
+      }
+    ],
+    "dependency_set_digest": "sha256:720d1300cc30f5732c864f41ef79767268095483b0bac93d871b19299886141b"
+  },
+  "idempotency_key": "idem_update_2001",
+  "lease": { "lease_id": "lease_update_2001", "attempt": 1, "expires_at": "2026-07-23T19:00:00Z" }
+}

package/llms.txt

@@ -0,0 +1,38 @@
+# 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
+- Proposal and evidence freshness: https://github.com/Synapsor/Synapsor-Runner/blob/main/docs/proposal-evidence-freshness.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.4",
+  "version": "1.6.1",
   "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",
@@ -81,9 +83,14 @@
   "engines": {
     "node": ">=22.13.0"
   },
+  "scripts": {
+    "build": "tsc -b && node ../../scripts/build-runner-package.mjs",
+    "prepack": "cd ../.. && corepack pnpm build:runner-package",
+    "test": "vitest run"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
-    "@synapsor/spec": "^1.4.2",
+    "@synapsor/spec": "workspace:^",
     "jose": "6.2.3",
     "mysql2": "^3.11.0",
     "pdf-lib": "1.17.1",
@@ -95,6 +102,7 @@
     "zod": "^3.25.0"
   },
   "devDependencies": {
+    "@types/pg": "^8.11.0",
     "ajv": "^8.17.1",
     "vitest": "^3.2.0"
   },
@@ -108,9 +116,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "tsc -b && node ../../scripts/build-runner-package.mjs",
-    "test": "vitest run"
   }
-}
+}

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

@@ -80,6 +80,7 @@
         "expected_version": { "$ref": "#/$defs/columnValue" }
       }
     },
+    "freshness": { "$ref": "https://schemas.synapsor.ai/synapsor.freshness-authority.v1.schema.json" },
     "evidence": {
       "type": "object",
       "additionalProperties": true,

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

@@ -92,6 +92,7 @@
         "deduplication": { "$ref": "#/$defs/deduplication" }
       }
     },
+    "freshness": { "$ref": "https://schemas.synapsor.ai/synapsor.freshness-authority.v1.schema.json" },
     "evidence": {
       "type": "object",
       "additionalProperties": true,

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

@@ -42,6 +42,7 @@
         "version_advance": { "$ref": "#/$defs/versionAdvance" }
       }
     },
+    "freshness": { "$ref": "https://schemas.synapsor.ai/synapsor.freshness-authority.v1.schema.json" },
     "frozen_set": { "$ref": "#/$defs/frozenSet" },
     "evidence": {
       "type": "object", "additionalProperties": true, "required": ["bundle_id", "query_fingerprint", "items"],