@synapsor/spec 0.1.0

package/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/conformance/proposal-capability/expected.proposal.json

@@ -0,0 +1,25 @@
+{
+  "id": "wrp_INV_3001_late_fee_waiver",
+  "capability": "billing.propose_late_fee_waiver",
+  "subject": {
+    "type": "invoice",
+    "id": "INV-3001",
+    "tenant_id": "acme"
+  },
+  "status": "pending",
+  "diff": {
+    "before": {
+      "late_fee_cents": 5500,
+      "waiver_reason": null
+    },
+    "patch": {
+      "late_fee_cents": 0,
+      "waiver_reason": "duplicate billing issue"
+    },
+    "after": {
+      "late_fee_cents": 0,
+      "waiver_reason": "duplicate billing issue"
+    }
+  },
+  "evidence_handle": "ev_prop_INV_3001"
+}

package/fixtures/conformance/proposal-capability/expected.replay.json

@@ -0,0 +1,14 @@
+{
+  "id": "rpl_prop_INV_3001",
+  "proposal_id": "wrp_INV_3001_late_fee_waiver",
+  "events": [
+    {
+      "type": "capability_invoked",
+      "capability": "billing.propose_late_fee_waiver"
+    },
+    {
+      "type": "proposal_created",
+      "proposal_id": "wrp_INV_3001_late_fee_waiver"
+    }
+  ]
+}

package/fixtures/conformance/proposal-capability/scenario.json

@@ -0,0 +1,21 @@
+{
+  "trusted_context": {
+    "tenant_id": "acme",
+    "principal": "dev_test_user"
+  },
+  "invoke": {
+    "capability": "billing.propose_late_fee_waiver",
+    "args": {
+      "invoice_id": "INV-3001",
+      "waiver_reason": "duplicate billing issue"
+    }
+  },
+  "source_row": {
+    "id": "INV-3001",
+    "tenant_id": "acme",
+    "late_fee_cents": 5500,
+    "waiver_reason": null,
+    "updated_at": "2026-06-20T14:31:08Z",
+    "card_token": "tok_should_not_leak"
+  }
+}

package/fixtures/conformance/read-capability/contract.json

@@ -0,0 +1,73 @@
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "metadata": {
+    "name": "read 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",
+          "required": true
+        },
+        {
+          "name": "principal",
+          "source": "environment",
+          "key": "SYNAPSOR_PRINCIPAL",
+          "required": true
+        }
+      ],
+      "tenant_binding": "tenant_id",
+      "principal_binding": "principal"
+    }
+  ],
+  "capabilities": [
+    {
+      "name": "billing.inspect_invoice",
+      "kind": "read",
+      "context": "local_operator",
+      "source": "local_postgres",
+      "subject": {
+        "resource": "billing_invoices"
+      },
+      "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/conformance/read-capability/expected.evidence.json

@@ -0,0 +1,11 @@
+{
+  "handle": "ev_read_INV_3001",
+  "capability": "billing.inspect_invoice",
+  "query_fingerprint": "sha256:read-capability-fixture",
+  "items": [
+    {
+      "field": "late_fee_cents",
+      "value": 5500
+    }
+  ]
+}

package/fixtures/conformance/read-capability/expected.replay.json

@@ -0,0 +1,13 @@
+{
+  "id": "rpl_read_INV_3001",
+  "events": [
+    {
+      "type": "capability_invoked",
+      "capability": "billing.inspect_invoice"
+    },
+    {
+      "type": "evidence_created",
+      "handle": "ev_read_INV_3001"
+    }
+  ]
+}

package/fixtures/conformance/read-capability/scenario.json

@@ -0,0 +1,19 @@
+{
+  "trusted_context": {
+    "tenant_id": "acme",
+    "principal": "dev_test_user"
+  },
+  "invoke": {
+    "capability": "billing.inspect_invoice",
+    "args": {
+      "invoice_id": "INV-3001"
+    }
+  },
+  "source_row": {
+    "id": "INV-3001",
+    "tenant_id": "acme",
+    "late_fee_cents": 5500,
+    "updated_at": "2026-06-20T14:31:08Z",
+    "card_token": "tok_should_not_leak"
+  }
+}

package/fixtures/invalid/kept-out-visible.contract.json

@@ -0,0 +1,46 @@
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "contexts": [
+    {
+      "name": "local_operator",
+      "bindings": [
+        {
+          "name": "tenant_id",
+          "source": "environment",
+          "key": "SYNAPSOR_TENANT_ID"
+        }
+      ],
+      "tenant_binding": "tenant_id"
+    }
+  ],
+  "capabilities": [
+    {
+      "name": "billing.inspect_invoice",
+      "kind": "read",
+      "context": "local_operator",
+      "subject": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "invoice_id": {
+          "type": "string"
+        }
+      },
+      "lookup": {
+        "id_from_arg": "invoice_id"
+      },
+      "visible_fields": [
+        "id",
+        "tenant_id",
+        "card_token"
+      ],
+      "kept_out_fields": [
+        "card_token"
+      ]
+    }
+  ]
+}

package/fixtures/invalid/model-controlled-tenant.contract.json

@@ -0,0 +1,45 @@
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "contexts": [
+    {
+      "name": "local_operator",
+      "bindings": [
+        {
+          "name": "tenant_id",
+          "source": "environment",
+          "key": "SYNAPSOR_TENANT_ID"
+        }
+      ],
+      "tenant_binding": "tenant_id"
+    }
+  ],
+  "capabilities": [
+    {
+      "name": "billing.inspect_invoice",
+      "kind": "read",
+      "context": "local_operator",
+      "subject": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "tenant_id": {
+          "type": "string"
+        },
+        "invoice_id": {
+          "type": "string"
+        }
+      },
+      "lookup": {
+        "id_from_arg": "invoice_id"
+      },
+      "visible_fields": [
+        "id",
+        "tenant_id"
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,37 @@
+{
+  "name": "@synapsor/spec",
+  "version": "0.1.0",
+  "description": "Canonical Synapsor contract schemas, types, validation, and conformance fixtures.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "synapsor-spec": "dist/cli.js"
+  },
+  "files": [
+    "dist/**",
+    "schemas/**",
+    "examples/**",
+    "fixtures/**",
+    "README.md",
+    "package.json"
+  ],
+  "keywords": [
+    "synapsor",
+    "ai-agents",
+    "mcp",
+    "database-safety",
+    "contracts"
+  ],
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run"
+  }
+}

package/schemas/capability.schema.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.synapsor.ai/capability.schema.json",
+  "title": "Synapsor Capability",
+  "$ref": "synapsor-contract.schema.json#/$defs/capability"
+}

package/schemas/context.schema.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.synapsor.ai/context.schema.json",
+  "title": "Synapsor Agent Context",
+  "$ref": "synapsor-contract.schema.json#/$defs/context"
+}

package/schemas/envelope-v2.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.synapsor.ai/envelope-v2.schema.json",
+  "title": "Synapsor Result Envelope V2",
+  "type": "object",
+  "required": ["ok", "summary", "action", "kind", "source_database_changed", "_meta"],
+  "additionalProperties": true,
+  "properties": {
+    "ok": { "type": "boolean" },
+    "summary": { "type": "string" },
+    "action": { "type": "string" },
+    "kind": { "enum": ["read", "proposal", "external_action", "answer_with_evidence"] },
+    "data": { "type": ["object", "null"] },
+    "proposal": { "type": ["object", "null"] },
+    "error": { "type": ["object", "null"] },
+    "evidence": { "type": ["object", "null"] },
+    "source_database_changed": { "type": "boolean" },
+    "_meta": { "type": "object" }
+  }
+}

package/schemas/evidence.schema.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.synapsor.ai/evidence.schema.json",
+  "title": "Synapsor Evidence Record",
+  "$ref": "synapsor-contract.schema.json#/$defs/evidenceRecord"
+}

package/schemas/external-action.schema.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.synapsor.ai/external-action.schema.json",
+  "title": "Synapsor External Action",
+  "$ref": "synapsor-contract.schema.json#/$defs/externalAction"
+}

package/schemas/policy.schema.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.synapsor.ai/policy.schema.json",
+  "title": "Synapsor Policy",
+  "$ref": "synapsor-contract.schema.json#/$defs/policy"
+}

package/schemas/proposal.schema.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.synapsor.ai/proposal.schema.json",
+  "title": "Synapsor Proposal Record",
+  "$ref": "synapsor-contract.schema.json#/$defs/proposalRecord"
+}

package/schemas/receipt.schema.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.synapsor.ai/receipt.schema.json",
+  "title": "Synapsor Receipt",
+  "$ref": "synapsor-contract.schema.json#/$defs/receipt"
+}

package/schemas/replay.schema.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.synapsor.ai/replay.schema.json",
+  "title": "Synapsor Replay Record",
+  "$ref": "synapsor-contract.schema.json#/$defs/replay"
+}