@synapsor/runner 1.4.12 → 1.4.122

package/docs/runner-config-reference.md

@@ -38,6 +38,7 @@ Unknown keys fail when `strict` is true (the default).
 | `session_auth` | HTTP claims | HS256 development or asymmetric RS256/ES256 session-token verification. |
 | `rate_limits` | No | Operational fixed-window limits; fleet-wide only with shared `runtime_store`. |
 | `metrics` | No | Separately authorized scrapeable HTTP metrics. Disabled by default. |
+| `graduated_trust` | No | Off-by-default, operator-only policy recommendation criteria and kill switch. |
 | `executors` | No | App-owned writeback wiring. |
 | `cloud` | Cloud mode | Scoped Cloud adapter configuration. |
 
@@ -375,6 +376,21 @@ metrics token; the MCP bearer does not authorize metrics. Labels are bounded to
 trusted tenant, capability, source, engine, and readiness component. Object
 IDs, principals, URLs, tokens, and raw errors are never labels.
 
+## Graduated trust
+
+`graduated_trust` is runtime/operator policy, not model-facing authority. It is
+disabled unless `enabled` is exactly `true`; `kill_switch: true` stops all
+evaluation. Each criterion fixes one capability, approval policy, numeric
+field, minimum human-reviewed sample (10..10000), window (1..365 days), maximum
+rejection/conflict/failure/revert rates, maximum threshold increment, and
+absolute ceiling. Optional `workspace_id` and `project_id` further scope stored
+recommendations.
+
+Auto-approved outcomes never count as human evidence. Recommendation decisions
+require verified operator identity. Approval only permits exporting a new
+contract artifact bound to the current digest/version; Runner never activates
+it. See [Graduated Trust Recommendations](graduated-trust.md).
+
 ## Operator identity
 
 Local development compatibility uses an explicitly unverified environment

package/docs/running-a-runner-fleet.md

@@ -132,6 +132,14 @@ Every served capability context must bind tenant and principal from
 `HTTP_CLAIM`. Runner rejects an environment-bound contract mixed into this
 server with `TRUSTED_CONTEXT_PROVIDER_CONFLICT` before tools are served.
 
+For same-tenant per-user rows, declare `PRINCIPAL SCOPE KEY assigned_to` (or
+the corresponding canonical `principal_scope_key`) on the capability. The
+signed `sub` claim then becomes a bound SQL predicate composed with the signed
+tenant claim. Session token fingerprint pinning prevents swapping identities
+within an MCP session. `tools preview` displays both locks, and
+`corepack pnpm test:principal-scope` proves two concurrent principals cannot
+read each other's rows or evidence handles on Postgres and MySQL.
+
 Use an HTTPS JWKS URL from an allowlisted identity system. Runner rejects
 redirects, oversized responses, unknown algorithms, `none`, missing/unknown
 `kid`, bad issuer/audience, expired/not-yet-valid tokens, and private JWK

package/docs/security-boundary.md

@@ -40,10 +40,30 @@ The model does not receive:
 - commit/writeback tools;
 - trusted tenant or principal authority as ordinary model arguments.
 
+Reviewed aggregate tools expose one scalar only. Their function, column,
+tenant key, optional equality selection, and minimum-group threshold are fixed
+in the contract; the model receives no predicate arguments or member rows.
+Suppression reduces single-record inference but does not replace statistical
+privacy review. See [Bounded Aggregate Reads](aggregate-reads.md).
+
 Trusted context comes from local configuration, environment bindings, or Cloud
 session context in Cloud mode. Tenant, principal, and authorization scope must
 not be accepted from the model as authority.
 
+A capability may declare `principal_scope_key` (DSL: `PRINCIPAL SCOPE KEY`) to
+narrow rows inside a tenant. Runner then adds both fixed, parameterized guards:
+
+```text
+tenant_key = verified tenant AND principal_scope_key = verified principal
+```
+
+This applies to single-row reads and writes, aggregates, bounded sets, inserts,
+deletes, executor envelopes, and reviewed compensation. Missing principal
+context fails closed. A principal lock never replaces tenant scope and has no
+dynamic supervisor bypass. Use a separately reviewed tenant-wide capability
+for broader roles. RLS and restricted database roles remain valuable defense in
+depth; the contract does not replace them.
+
 Proposal, evidence, and replay handles are references, not bearer credentials.
 Before returning a local MCP resource, Runner resolves the resource's owning
 capability context again and requires both tenant and principal to match the
@@ -70,7 +90,7 @@ outside the model-facing MCP server and verifies:
 - local approval state;
 - proposal and job digests;
 - target schema/table;
-- primary-key and tenant guards;
+- primary-key, tenant, and declared principal-row guards;
 - allowed mutable columns;
 - conflict/version guard;
 - idempotency key;
@@ -121,6 +141,13 @@ approve/reject actions. It does not expose raw SQL, database URLs, write
 credentials, approval tools, commit tools, or controls that widen reviewed
 tables/columns.
 
+Contract lint and tests are review aids rather than a proof of complete
+security. Scoped report exports omit evidence rows and kept-out values and are
+tamper-evident when their digest/signature verifies; local SQLite is not an
+immutable compliance service. Graduated-trust evaluation is operator-only,
+disabled by default, and can recommend/export a separate artifact but cannot
+approve itself or activate policy.
+
 Synapsor Runner supports reviewed single-row CRUD and the narrowly bounded set
 path documented above. It does not support arbitrary SQL, DDL, UPSERT,
 model-generated predicates, unbounded sets, or cross-table direct writeback.

package/examples/runner-fleet/seed/mysql.sql

@@ -4,6 +4,7 @@ CREATE TABLE invoices (
   status varchar(64) NOT NULL,
   late_fee_cents integer NOT NULL,
   waiver_reason varchar(500),
+  assigned_to varchar(128) NOT NULL DEFAULT 'case_manager_a',
   updated_at datetime(6) NOT NULL
 );
 
@@ -41,7 +42,10 @@ INSERT INTO guard_crud_items (id, tenant_id, request_id, value_cents, version) V
 ALTER TABLE guard_crud_items AUTO_INCREMENT = 2001;
 
 INSERT INTO invoices (id, tenant_id, status, late_fee_cents, waiver_reason, updated_at) VALUES
-  ('MYSQL-ACME', 'acme', 'overdue', 700, NULL, '2026-07-12 12:00:00.000000');
+  ('MYSQL-ACME', 'acme', 'overdue', 700, NULL, '2026-07-12 12:00:00.000000'),
+  ('MYSQL-PRINCIPAL-A', 'hospital_a', 'principal_fixture', 100, NULL, '2026-07-12 12:00:00.000000'),
+  ('MYSQL-PRINCIPAL-B', 'hospital_a', 'principal_fixture', 200, NULL, '2026-07-12 12:00:00.000000');
+UPDATE invoices SET assigned_to = 'case_manager_b' WHERE id = 'MYSQL-PRINCIPAL-B';
 
 CREATE VIEW slow_invoices AS
 SELECT invoices.*, SLEEP(0.35) AS synthetic_delay

package/examples/runner-fleet/seed/postgres.sql

@@ -4,6 +4,7 @@ CREATE TABLE public.invoices (
   status text NOT NULL,
   late_fee_cents integer NOT NULL,
   waiver_reason text,
+  assigned_to text NOT NULL DEFAULT 'case_manager_a',
   updated_at timestamptz NOT NULL
 );
 
@@ -73,7 +74,10 @@ INSERT INTO public.invoices (id, tenant_id, status, late_fee_cents, waiver_reaso
   ('INV-DEAD-DISCARD', 'acme', 'overdue', 1750, NULL, '2026-07-12T12:00:00Z'),
   ('INV-KILL-BEFORE', 'acme', 'overdue', 1200, NULL, '2026-07-12T12:00:00Z'),
   ('INV-KILL-DURING', 'acme', 'overdue', 1500, NULL, '2026-07-12T12:00:00Z'),
-  ('INV-KILL-AFTER', 'acme', 'overdue', 1800, NULL, '2026-07-12T12:00:00Z');
+  ('INV-KILL-AFTER', 'acme', 'overdue', 1800, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-PRINCIPAL-A', 'hospital_a', 'principal_fixture', 100, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-PRINCIPAL-B', 'hospital_a', 'principal_fixture', 200, NULL, '2026-07-12T12:00:00Z');
+UPDATE public.invoices SET assigned_to = 'case_manager_b' WHERE id = 'INV-PRINCIPAL-B';
 
 CREATE FUNCTION public.synthetic_pool_delay() RETURNS integer
 LANGUAGE plpgsql VOLATILE AS $$

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

@@ -272,10 +272,12 @@ Real push uses your Cloud env vars:
 
 ```bash
 export SYNAPSOR_CLOUD_BASE_URL="https://api.synapsor.ai"
-export SYNAPSOR_CLOUD_TOKEN="<workspace-scoped-token>"
-export SYNAPSOR_WORKSPACE_ID="<workspace_id>"
+export SYNAPSOR_API_KEY="<contracts-write-service-key>"
+export SYNAPSOR_PROJECT_ID="<project_id>"
+export SYNAPSOR_SOURCE_ID="<cloud_source_id>"
 
 synapsor-runner cloud push examples/support-plan-credit/synapsor.contract.json \
+  --workspace "$SYNAPSOR_PROJECT_ID" \
   --name support-plan-credit
 ```
 
@@ -283,11 +285,11 @@ 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_CLOUD_BASE_URL/v1/control/projects/$SYNAPSOR_WORKSPACE_ID/agent-contracts/<contract_id>/versions/<version_id>"
+curl -H "Authorization: Bearer $SYNAPSOR_API_KEY" \
+  "$SYNAPSOR_CLOUD_BASE_URL/v1/control/projects/$SYNAPSOR_PROJECT_ID/agent-contracts/<contract_id>/versions/<version_id>"
 
-curl -H "Authorization: Bearer $SYNAPSOR_CLOUD_TOKEN" \
-  "$SYNAPSOR_CLOUD_BASE_URL/v1/control/projects/$SYNAPSOR_WORKSPACE_ID/agent-contracts/<contract_id>/versions/<version_id>/runner-bundle?download=1" \
+curl -H "Authorization: Bearer $SYNAPSOR_API_KEY" \
+  "$SYNAPSOR_CLOUD_BASE_URL/v1/control/projects/$SYNAPSOR_PROJECT_ID/agent-contracts/<contract_id>/versions/<version_id>/runner-bundle?download=1&source_id=$SYNAPSOR_SOURCE_ID" \
   -o support-plan-credit-runner-bundle.zip
 ```
 

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

@@ -0,0 +1,53 @@
+{
+  "$schema": "../../schemas/synapsor.contract-tests.schema.json",
+  "version": 1,
+  "name": "support-plan-credit contract boundary",
+  "tests": [
+    {
+      "id": "operator-controls-stay-outside-mcp",
+      "kind": "operator_boundary",
+      "capability": "support.propose_plan_credit"
+    },
+    {
+      "id": "private-customer-fields-stay-hidden",
+      "kind": "hide_fields",
+      "capability": "support.inspect_customer",
+      "args": { "customer_id": "CUS-3001" },
+      "trusted_context": { "tenant_id": "acme", "principal": "contract_test" },
+      "fields": ["card_token", "raw_payment_method", "internal_risk_score", "private_notes"]
+    },
+    {
+      "id": "credit-amount-is-bounded",
+      "kind": "argument_constraint",
+      "capability": "support.propose_plan_credit_record",
+      "argument": "credit_cents",
+      "expected": { "minimum": 1, "maximum": 50000 }
+    },
+    {
+      "id": "trusted-tenant-can-read-own-customer",
+      "kind": "tool_allow",
+      "capability": "support.inspect_customer",
+      "args": { "customer_id": "CUS-3001" },
+      "trusted_context": { "tenant_id": "acme", "principal": "contract_test" }
+    },
+    {
+      "id": "trusted-tenant-cannot-read-other-customer",
+      "kind": "tool_deny",
+      "capability": "support.inspect_customer",
+      "args": { "customer_id": "CUS-9001" },
+      "trusted_context": { "tenant_id": "acme", "principal": "contract_test" },
+      "expected_code": "NOT_FOUND_IN_TENANT"
+    },
+    {
+      "id": "proposal-does-not-write-before-approval",
+      "kind": "source_unchanged_before_approval",
+      "capability": "support.propose_plan_credit",
+      "args": {
+        "customer_id": "CUS-3001",
+        "credit_cents": 10000,
+        "reason": "synthetic conformance check"
+      },
+      "trusted_context": { "tenant_id": "acme", "principal": "contract_test" }
+    }
+  ]
+}

package/fixtures/dsl/aggregate-read.synapsor.sql

@@ -0,0 +1,21 @@
+CREATE AGENT CONTEXT finance_operator
+  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 billing.overdue_balance_total
+  DESCRIPTION 'Return one suppressed overdue-balance aggregate for the trusted tenant.'
+  RETURNS HINT 'Returns one scalar or a suppression result; never member rows.'
+  USING CONTEXT finance_operator
+  SOURCE local_postgres
+  ON public.invoices
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  AGGREGATE READ SUM balance_cents
+  SELECT WHERE status = 'overdue'
+  MIN GROUP SIZE 5
+  KEEP OUT customer_email, private_notes
+  REQUIRE EVIDENCE
+END

package/fixtures/dsl/bounded-set-multi-term.synapsor.sql

@@ -0,0 +1,30 @@
+CREATE AGENT CONTEXT local_operator
+  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 cases.close_high_risk
+  DESCRIPTION 'Close active high-risk support cases within reviewed row and value caps.'
+  RETURNS HINT 'Returns a proposal for the exact reviewed set; source rows remain unchanged.'
+  USING CONTEXT local_operator
+  SOURCE support_db
+  ON public.support_cases
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  CONFLICT GUARD version
+  LOOKUP reason BY id
+  ARG reason STRING REQUIRED MAX LENGTH 100
+  ALLOW READ id, tenant_id, risk_level, case_status, exposure_cents, version
+  REQUIRE EVIDENCE
+  PROPOSE ACTION close_high_risk UPDATE SET
+  SELECT WHERE risk_level = 'high' AND case_status = 'active'
+  MAX ROWS 10
+  MAX TOTAL exposure_cents BEFORE 50000
+  ALLOW WRITE case_status
+  PATCH case_status = 'closed'
+  ADVANCE VERSION version USING INTEGER INCREMENT
+  APPROVAL ROLE support_manager
+  WRITEBACK DIRECT SQL
+END

package/fixtures/dsl/principal-row-scope.synapsor.sql

@@ -0,0 +1,23 @@
+CREATE AGENT CONTEXT care_session
+  BIND hospital_id FROM HTTP_CLAIM hospital_id REQUIRED
+  BIND principal FROM HTTP_CLAIM sub REQUIRED
+  TENANT BINDING hospital_id
+  PRINCIPAL BINDING principal
+END
+
+CREATE CAPABILITY 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.'
+  USING CONTEXT care_session
+  SOURCE local_postgres
+  ON public.patients
+  PRIMARY KEY id
+  TENANT KEY hospital_id
+  PRINCIPAL SCOPE KEY assigned_to
+  LOOKUP patient_id BY id
+  ARG patient_id STRING REQUIRED MAX LENGTH 128 DESCRIPTION 'Reviewed patient identifier.'
+  ALLOW READ id, hospital_id, display_name, care_status, updated_at
+  KEEP OUT assigned_to, diagnosis_notes, insurance_member_id
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+END

package/fixtures/protocol/MANIFEST.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "synapsor.protocol-manifest.v1",
   "protocol_set": "database-mcp-writeback",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "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": [
@@ -113,22 +113,22 @@
     {
       "kind": "schema",
       "name": "change-set.v1.schema.json",
-      "sha256": "119ac84f7189e9433d4eaac4defb6ef7c459a14e55e1563aa7948b746d816af5"
+      "sha256": "18f76efd97424efab986b6fb0af87ad0eeafd4314393ed7f83f14afe09d625eb"
     },
     {
       "kind": "schema",
       "name": "change-set.v2.schema.json",
-      "sha256": "cd07204661d08eba31c0cd1f878b881a5b771702de4019f4cf410628384349f8"
+      "sha256": "bd9999361258c5554ffa2791d7c6469beffc5b875e775f5f0c80cea36132eaa4"
     },
     {
       "kind": "schema",
       "name": "change-set.v3.schema.json",
-      "sha256": "c14a5c787c2a269dfee98911fbba40aaa53fa8d5a007d694366ba8b58e20f0b3"
+      "sha256": "24a45eb4d9f29ab4cfe408bedeb0216dc29544fe39b515918d0c0f9742bba9cb"
     },
     {
       "kind": "schema",
       "name": "compensation-change-set.v1.schema.json",
-      "sha256": "24585f9c53bd89119bf7a7ea92a587d37fe7dccbf1517d6736b5ecdeff2b9ebc"
+      "sha256": "6353ddd1a030d0cd25c1663c96794d5420bc1002f46aacdef58c346238a90450"
     },
     {
       "kind": "schema",
@@ -153,7 +153,7 @@
     {
       "kind": "schema",
       "name": "inverse-descriptor.v1.schema.json",
-      "sha256": "ae3aa626896bdc114f5368fee4803994852bb5263a24c234f456e05f1d875fd0"
+      "sha256": "6f310b11946196cf8c829bcf5be39864d5e3bd85181ae2a3a277bfa6fd72a553"
     },
     {
       "kind": "schema",
@@ -163,22 +163,22 @@
     {
       "kind": "schema",
       "name": "writeback-job.v1.schema.json",
-      "sha256": "eab35194dd6b6caa7694aa8f14afbf265338d6ee8ed3d3db5d08ec83c4e7092e"
+      "sha256": "64238559297805e13c04cb8bf71be433e6fb1241594ca021415b1efb95214a01"
     },
     {
       "kind": "schema",
       "name": "writeback-job.v2.schema.json",
-      "sha256": "6f959deedffcb9193b7dffbb0e0beb681bb0b421b6c4460ca14733e3e18acd1f"
+      "sha256": "68110a5ed5b7867522cf86db8d177d2df3f96a458a4343bb77537bdcf304279b"
     },
     {
       "kind": "schema",
       "name": "writeback-job.v3.schema.json",
-      "sha256": "9ee7992ada437f5df9e1f551e0a16a00db0e98ab5dd745f78848b3e4cdb11cfa"
+      "sha256": "3bd46747e737e79bff90dc0496c270bc93d6a913db750ea00486be9a45714831"
     },
     {
       "kind": "schema",
       "name": "writeback-job.v4.schema.json",
-      "sha256": "5031e2476ddaf96042c596e76626d8ce8bce2eb51f7167c92bef44d1676a0487"
+      "sha256": "2c0d23cdf12f6a0d70c5f38fb4fcc5842f2b6c184ee1a195344ae42f58baf4ca"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "1.4.12",
+  "version": "1.4.122",
   "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",
@@ -62,7 +62,10 @@
     "@modelcontextprotocol/sdk": "1.29.0",
     "jose": "6.2.3",
     "mysql2": "^3.11.0",
+    "pdf-lib": "1.17.1",
     "pg": "^8.13.0",
+    "vscode-languageserver": "9.0.1",
+    "vscode-languageserver-textdocument": "1.0.12",
     "zod": "^3.25.0"
   },
   "devDependencies": {

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

@@ -70,6 +70,7 @@
       "required": ["tenant", "allowed_columns", "expected_version"],
       "properties": {
         "tenant": { "$ref": "#/$defs/columnValue" },
+        "principal_scope": { "$ref": "#/$defs/principalScope" },
         "allowed_columns": {
           "type": "array",
           "items": { "$ref": "#/$defs/safeIdentifier" },
@@ -136,6 +137,19 @@
         "column": { "$ref": "#/$defs/safeIdentifier" },
         "value": { "$ref": "#/$defs/scalar" }
       }
+    },
+    "principalScope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema_version", "column", "binding", "provider", "value_fingerprint"],
+      "properties": {
+        "schema_version": { "const": "synapsor.principal-scope.v1" },
+        "column": { "$ref": "#/$defs/safeIdentifier" },
+        "binding": { "$ref": "#/$defs/safeIdentifier" },
+        "provider": { "enum": ["environment", "http_claims", "cloud_session", "static_dev"] },
+        "value_fingerprint": { "type": "string", "pattern": "^sha256:.+" },
+        "value": { "$ref": "#/$defs/scalar" }
+      }
     }
   }
 }

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

@@ -80,6 +80,7 @@
       "required": ["tenant", "allowed_columns"],
       "properties": {
         "tenant": { "$ref": "#/$defs/columnValue" },
+        "principal_scope": { "$ref": "#/$defs/principalScope" },
         "allowed_columns": {
           "type": "array",
           "items": { "$ref": "#/$defs/safeIdentifier" },
@@ -209,6 +210,19 @@
         "value": { "$ref": "#/$defs/scalar" }
       }
     },
+    "principalScope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema_version", "column", "binding", "provider", "value_fingerprint"],
+      "properties": {
+        "schema_version": { "const": "synapsor.principal-scope.v1" },
+        "column": { "$ref": "#/$defs/safeIdentifier" },
+        "binding": { "$ref": "#/$defs/safeIdentifier" },
+        "provider": { "enum": ["environment", "http_claims", "cloud_session", "static_dev"] },
+        "value_fingerprint": { "$ref": "#/$defs/sha256" },
+        "value": { "$ref": "#/$defs/scalar" }
+      }
+    },
     "versionAdvance": {
       "type": "object",
       "additionalProperties": false,

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

@@ -37,6 +37,7 @@
       "type": "object", "additionalProperties": false, "required": ["tenant", "allowed_columns"],
       "properties": {
         "tenant": { "$ref": "#/$defs/columnValue" },
+        "principal_scope": { "$ref": "#/$defs/principalScope" },
         "allowed_columns": { "type": "array", "items": { "$ref": "#/$defs/safeIdentifier" }, "maxItems": 256, "uniqueItems": true },
         "version_advance": { "$ref": "#/$defs/versionAdvance" }
       }
@@ -96,6 +97,7 @@
     "scalarRecord": { "type": "object", "propertyNames": { "$ref": "#/$defs/safeIdentifier" }, "additionalProperties": { "$ref": "#/$defs/scalar" }, "maxProperties": 256 },
     "setOperation": { "enum": ["set_update", "set_delete", "batch_insert"] },
     "columnValue": { "type": "object", "additionalProperties": false, "required": ["column", "value"], "properties": { "column": { "$ref": "#/$defs/safeIdentifier" }, "value": { "$ref": "#/$defs/scalar" } } },
+    "principalScope": { "type": "object", "additionalProperties": false, "required": ["schema_version", "column", "binding", "provider", "value_fingerprint"], "properties": { "schema_version": { "const": "synapsor.principal-scope.v1" }, "column": { "$ref": "#/$defs/safeIdentifier" }, "binding": { "$ref": "#/$defs/safeIdentifier" }, "provider": { "enum": ["environment", "http_claims", "cloud_session", "static_dev"] }, "value_fingerprint": { "$ref": "#/$defs/sha256" }, "value": { "$ref": "#/$defs/scalar" } } },
     "versionAdvance": { "type": "object", "additionalProperties": false, "required": ["column", "strategy"], "properties": { "column": { "$ref": "#/$defs/safeIdentifier" }, "strategy": { "enum": ["integer_increment", "database_generated"] } } },
     "deduplicationComponent": { "type": "object", "additionalProperties": false, "required": ["column", "value", "source"], "properties": { "column": { "$ref": "#/$defs/safeIdentifier" }, "value": { "$ref": "#/$defs/scalar" }, "source": { "enum": ["proposal_id", "trusted_tenant", "fixed"] } } },
     "deduplication": { "type": "object", "additionalProperties": false, "required": ["components"], "properties": { "components": { "type": "array", "items": { "$ref": "#/$defs/deduplicationComponent" }, "minItems": 1, "maxItems": 8 } } },

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

@@ -16,7 +16,7 @@
     "source": { "type": "object", "additionalProperties": false, "required": ["kind", "source_id", "schema", "table", "primary_key"], "properties": { "kind": { "enum": ["external_postgres", "external_mysql"] }, "source_id": { "type": "string", "minLength": 1 }, "schema": { "$ref": "#/$defs/identifier" }, "table": { "$ref": "#/$defs/identifier" }, "primary_key": { "type": "object", "additionalProperties": false, "required": ["column"], "properties": { "column": { "$ref": "#/$defs/identifier" }, "value": { "$ref": "#/$defs/scalar" } } } } },
     "before": { "$ref": "#/$defs/record" }, "patch": { "$ref": "#/$defs/record" }, "after": { "$ref": "#/$defs/record" },
     "compensation": { "type": "object", "additionalProperties": false, "required": ["descriptor", "forward_receipt_hash"], "properties": { "descriptor": { "$ref": "inverse-descriptor.v1.schema.json" }, "forward_receipt_hash": { "$ref": "#/$defs/sha256" } } },
-    "guards": { "type": "object", "additionalProperties": false, "required": ["tenant", "allowed_columns"], "properties": { "tenant": { "$ref": "#/$defs/columnValue" }, "allowed_columns": { "type": "array", "items": { "$ref": "#/$defs/identifier" }, "maxItems": 256, "uniqueItems": true } } },
+    "guards": { "type": "object", "additionalProperties": false, "required": ["tenant", "allowed_columns"], "properties": { "tenant": { "$ref": "#/$defs/columnValue" }, "principal_scope": { "$ref": "#/$defs/principalScope" }, "allowed_columns": { "type": "array", "items": { "$ref": "#/$defs/identifier" }, "maxItems": 256, "uniqueItems": true } } },
     "evidence": { "type": "object", "required": ["bundle_id", "query_fingerprint", "items"], "properties": { "bundle_id": { "type": "string", "minLength": 1 }, "query_fingerprint": { "$ref": "#/$defs/sha256" }, "items": { "type": "array", "maxItems": 100 } } },
     "approval": { "type": "object", "required": ["status", "mode"], "properties": { "status": { "enum": ["pending", "approved", "rejected", "canceled"] }, "mode": { "enum": ["human", "operator"] }, "required_role": { "type": "string", "minLength": 1 }, "required_approvals": { "type": "integer", "minimum": 1, "maximum": 10 } } },
     "writeback": { "type": "object", "additionalProperties": false, "required": ["status", "mode", "executor"], "properties": { "status": { "const": "not_applied" }, "mode": { "const": "trusted_worker_required" }, "executor": { "const": "sql_update" } } },
@@ -27,6 +27,7 @@
   "$defs": {
     "identifier": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "sha256": { "type": "string", "pattern": "^sha256:.+" }, "scalar": { "type": ["string", "number", "boolean", "null"] },
     "record": { "type": "object", "propertyNames": { "$ref": "#/$defs/identifier" }, "additionalProperties": { "$ref": "#/$defs/scalar" }, "maxProperties": 256 },
-    "columnValue": { "type": "object", "additionalProperties": false, "required": ["column", "value"], "properties": { "column": { "$ref": "#/$defs/identifier" }, "value": { "$ref": "#/$defs/scalar" } } }
+    "columnValue": { "type": "object", "additionalProperties": false, "required": ["column", "value"], "properties": { "column": { "$ref": "#/$defs/identifier" }, "value": { "$ref": "#/$defs/scalar" } } },
+    "principalScope": { "type": "object", "additionalProperties": false, "required": ["schema_version", "column", "binding", "provider", "value_fingerprint"], "properties": { "schema_version": { "const": "synapsor.principal-scope.v1" }, "column": { "$ref": "#/$defs/identifier" }, "binding": { "$ref": "#/$defs/identifier" }, "provider": { "enum": ["environment", "http_claims", "cloud_session", "static_dev"] }, "value_fingerprint": { "$ref": "#/$defs/sha256" }, "value": { "$ref": "#/$defs/scalar" } } }
   }
 }

package/schemas/inverse-descriptor.v1.schema.json

@@ -19,6 +19,7 @@
       "properties": { "source_id": { "type": "string", "minLength": 1 }, "schema": { "$ref": "#/$defs/identifier" }, "table": { "$ref": "#/$defs/identifier" }, "primary_key_column": { "$ref": "#/$defs/identifier" } }
     },
     "tenant_guard": { "$ref": "#/$defs/columnValue" },
+    "principal_scope": { "$ref": "#/$defs/principalScope" },
     "allowed_columns": { "type": "array", "items": { "$ref": "#/$defs/identifier" }, "maxItems": 256, "uniqueItems": true },
     "members": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/$defs/member" } },
     "max_rows": { "type": "integer", "minimum": 1, "maximum": 100 },
@@ -38,6 +39,7 @@
     "scalar": { "type": ["string", "number", "boolean", "null"] },
     "record": { "type": "object", "propertyNames": { "$ref": "#/$defs/identifier" }, "additionalProperties": { "$ref": "#/$defs/scalar" }, "maxProperties": 256 },
     "columnValue": { "type": "object", "additionalProperties": false, "required": ["column", "value"], "properties": { "column": { "$ref": "#/$defs/identifier" }, "value": { "$ref": "#/$defs/scalar" } } },
+    "principalScope": { "type": "object", "additionalProperties": false, "required": ["schema_version", "column", "binding", "provider", "value_fingerprint"], "properties": { "schema_version": { "const": "synapsor.principal-scope.v1" }, "column": { "$ref": "#/$defs/identifier" }, "binding": { "$ref": "#/$defs/identifier" }, "provider": { "enum": ["environment", "http_claims", "cloud_session", "static_dev"] }, "value_fingerprint": { "type": "string", "pattern": "^sha256:.+" }, "value": { "$ref": "#/$defs/scalar" } } },
     "member": { "type": "object", "additionalProperties": false, "required": ["primary_key", "expected_state"], "properties": { "primary_key": { "$ref": "#/$defs/columnValue" }, "expected_state": { "$ref": "#/$defs/record" }, "restore_values": { "$ref": "#/$defs/record" } } },
     "versionAdvance": { "type": "object", "additionalProperties": false, "required": ["column", "strategy"], "properties": { "column": { "$ref": "#/$defs/identifier" }, "strategy": { "enum": ["integer_increment", "database_generated"] } } },
     "aggregateBound": { "type": "object", "additionalProperties": false, "required": ["column", "measure", "maximum", "actual"], "properties": { "column": { "$ref": "#/$defs/identifier" }, "measure": { "enum": ["before", "after", "absolute_delta"] }, "maximum": { "type": "number", "minimum": 0 }, "actual": { "type": "number", "minimum": 0 } } },

package/schemas/synapsor.contract-tests.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.synapsor.ai/synapsor.contract-tests.schema.json",
+  "title": "Synapsor adopter contract conformance manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "tests"],
+  "properties": {
+    "$schema": { "type": "string", "minLength": 1 },
+    "version": { "const": 1 },
+    "name": { "type": "string", "minLength": 1 },
+    "tests": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "kind", "capability"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "kind": {
+            "enum": ["tool_allow", "tool_deny", "cross_principal_deny", "hide_fields", "argument_constraint", "transition_guard", "set_cap", "source_unchanged_before_approval", "operator_boundary"]
+          },
+          "capability": { "type": "string", "minLength": 1 },
+          "args": { "type": "object" },
+          "trusted_context": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["tenant_id", "principal"],
+            "properties": {
+              "tenant_id": { "type": "string", "minLength": 1 },
+              "principal": { "type": "string", "minLength": 1 },
+              "provenance": { "enum": ["environment", "static_dev", "http_claims", "cloud_session"] }
+            }
+          },
+          "other_trusted_context": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["tenant_id", "principal"],
+            "properties": {
+              "tenant_id": { "type": "string", "minLength": 1 },
+              "principal": { "type": "string", "minLength": 1 },
+              "provenance": { "enum": ["environment", "static_dev", "http_claims", "cloud_session"] }
+            }
+          },
+          "expected_code": { "type": "string", "minLength": 1 },
+          "fields": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+          "argument": { "type": "string", "minLength": 1 },
+          "expected": { "type": "object" }
+        }
+      }
+    }
+  }
+}