@synapsor/spec 0.1.0

package/examples/external-action.contract.json

@@ -0,0 +1,114 @@
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "metadata": {
+    "name": "support external action intent",
+    "description": "Create an app-owned action intent without model-facing commit authority.",
+    "version": "0.1.0"
+  },
+  "resources": [
+    {
+      "name": "support_tickets",
+      "engine": "postgres",
+      "schema": "public",
+      "table": "tickets",
+      "type": "table",
+      "primary_key": "id",
+      "tenant_key": "tenant_id",
+      "conflict_key": "updated_at"
+    }
+  ],
+  "contexts": [
+    {
+      "name": "support_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": "support.propose_ticket_reply",
+      "kind": "proposal",
+      "context": "support_operator",
+      "source": "support_postgres",
+      "subject": {
+        "resource": "support_tickets"
+      },
+      "args": {
+        "ticket_id": {
+          "type": "string",
+          "required": true,
+          "max_length": 128
+        },
+        "reply_body": {
+          "type": "string",
+          "required": true,
+          "max_length": 2000
+        }
+      },
+      "lookup": {
+        "id_from_arg": "ticket_id"
+      },
+      "visible_fields": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "status",
+        "subject",
+        "updated_at"
+      ],
+      "kept_out_fields": [
+        "private_staff_notes"
+      ],
+      "evidence": {
+        "required": true,
+        "query_audit": true
+      },
+      "max_rows": 1,
+      "proposal": {
+        "action": "support.create_ticket_reply",
+        "allowed_fields": [
+          "reply_body"
+        ],
+        "patch": {
+          "reply_body": {
+            "from_arg": "reply_body"
+          }
+        },
+        "conflict_guard": {
+          "column": "updated_at"
+        },
+        "approval": {
+          "mode": "human",
+          "required_role": "support_lead"
+        },
+        "writeback": {
+          "mode": "app_handler",
+          "executor": "support_reply_handler"
+        }
+      }
+    }
+  ],
+  "external_actions": [
+    {
+      "id": "intent_ticket_reply",
+      "action": "support.create_ticket_reply",
+      "handler": "support_reply_handler",
+      "idempotency_key": "proposal_id"
+    }
+  ]
+}

package/examples/guarded-writeback.contract.json

@@ -0,0 +1,171 @@
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "metadata": {
+    "name": "billing guarded invoice writeback",
+    "description": "Read one invoice and create a review-required late-fee waiver proposal.",
+    "version": "0.1.0"
+  },
+  "resources": [
+    {
+      "name": "billing_invoices",
+      "engine": "postgres",
+      "schema": "public",
+      "table": "invoices",
+      "type": "table",
+      "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,
+          "max_length": 128
+        }
+      },
+      "lookup": {
+        "id_from_arg": "invoice_id"
+      },
+      "visible_fields": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "status",
+        "balance_cents",
+        "late_fee_cents",
+        "waiver_reason",
+        "updated_at"
+      ],
+      "kept_out_fields": [
+        "internal_risk_score",
+        "card_token"
+      ],
+      "evidence": {
+        "required": true,
+        "query_audit": true
+      },
+      "max_rows": 1
+    },
+    {
+      "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,
+          "max_length": 128
+        },
+        "waiver_reason": {
+          "type": "string",
+          "required": true,
+          "max_length": 500
+        }
+      },
+      "lookup": {
+        "id_from_arg": "invoice_id"
+      },
+      "visible_fields": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "status",
+        "balance_cents",
+        "late_fee_cents",
+        "waiver_reason",
+        "updated_at"
+      ],
+      "kept_out_fields": [
+        "internal_risk_score",
+        "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"
+        }
+      }
+    }
+  ],
+  "workflows": [
+    {
+      "name": "billing.late_fee_review",
+      "context": "local_operator",
+      "allowed_capabilities": [
+        "billing.inspect_invoice",
+        "billing.propose_late_fee_waiver"
+      ],
+      "required_evidence": true,
+      "approval": {
+        "required": true,
+        "role": "billing_lead"
+      },
+      "settlement": {
+        "mode": "manual"
+      },
+      "replay": {
+        "checkpoint": "proposal_only"
+      }
+    }
+  ]
+}

package/examples/read-only-analytics.contract.json

@@ -0,0 +1,94 @@
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "metadata": {
+    "name": "read only customer analytics",
+    "description": "Expose scoped customer reads without model-facing SQL.",
+    "version": "0.1.0"
+  },
+  "resources": [
+    {
+      "name": "analytics_customers",
+      "engine": "mysql",
+      "schema": "app",
+      "table": "customers",
+      "type": "view",
+      "primary_key": "id",
+      "tenant_key": "tenant_id",
+      "conflict_key": "updated_at"
+    }
+  ],
+  "contexts": [
+    {
+      "name": "tenant_session",
+      "bindings": [
+        {
+          "name": "tenant_id",
+          "source": "session",
+          "key": "tenant_id",
+          "required": true
+        },
+        {
+          "name": "principal",
+          "source": "session",
+          "key": "principal",
+          "required": true
+        }
+      ],
+      "tenant_binding": "tenant_id",
+      "principal_binding": "principal"
+    }
+  ],
+  "capabilities": [
+    {
+      "name": "analytics.inspect_customer",
+      "kind": "read",
+      "context": "tenant_session",
+      "source": "analytics_mysql",
+      "subject": {
+        "resource": "analytics_customers"
+      },
+      "args": {
+        "customer_id": {
+          "type": "string",
+          "required": true,
+          "max_length": 128
+        }
+      },
+      "lookup": {
+        "id_from_arg": "customer_id"
+      },
+      "visible_fields": [
+        "id",
+        "tenant_id",
+        "name",
+        "plan",
+        "created_at",
+        "updated_at"
+      ],
+      "kept_out_fields": [
+        "email",
+        "phone",
+        "billing_notes"
+      ],
+      "evidence": {
+        "required": true,
+        "query_audit": true
+      },
+      "max_rows": 1
+    }
+  ],
+  "workflows": [
+    {
+      "name": "analytics.customer_lookup",
+      "context": "tenant_session",
+      "allowed_capabilities": [
+        "analytics.inspect_customer"
+      ],
+      "required_evidence": true,
+      "replay": {
+        "checkpoint": "every_step"
+      }
+    }
+  ]
+}

package/examples/support-refund.contract.json

@@ -0,0 +1,168 @@
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "metadata": {
+    "name": "support refund request",
+    "description": "Support workflow with read evidence and a review-required refund proposal.",
+    "version": "0.1.0"
+  },
+  "resources": [
+    {
+      "name": "support_orders",
+      "engine": "postgres",
+      "schema": "public",
+      "table": "orders",
+      "type": "table",
+      "primary_key": "id",
+      "tenant_key": "tenant_id",
+      "conflict_key": "updated_at"
+    }
+  ],
+  "contexts": [
+    {
+      "name": "support_agent_context",
+      "bindings": [
+        {
+          "name": "tenant_id",
+          "source": "session",
+          "key": "tenant_id",
+          "required": true
+        },
+        {
+          "name": "principal",
+          "source": "session",
+          "key": "principal",
+          "required": true
+        }
+      ],
+      "tenant_binding": "tenant_id",
+      "principal_binding": "principal"
+    }
+  ],
+  "capabilities": [
+    {
+      "name": "support.inspect_order",
+      "kind": "read",
+      "context": "support_agent_context",
+      "source": "support_postgres",
+      "subject": {
+        "resource": "support_orders"
+      },
+      "args": {
+        "order_id": {
+          "type": "string",
+          "required": true,
+          "max_length": 128
+        }
+      },
+      "lookup": {
+        "id_from_arg": "order_id"
+      },
+      "visible_fields": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "status",
+        "amount_cents",
+        "updated_at"
+      ],
+      "kept_out_fields": [
+        "payment_token",
+        "internal_fraud_score"
+      ],
+      "evidence": {
+        "required": true,
+        "query_audit": true
+      },
+      "max_rows": 1
+    },
+    {
+      "name": "support.propose_refund_review",
+      "kind": "proposal",
+      "context": "support_agent_context",
+      "source": "support_postgres",
+      "subject": {
+        "resource": "support_orders"
+      },
+      "args": {
+        "order_id": {
+          "type": "string",
+          "required": true,
+          "max_length": 128
+        },
+        "refund_note": {
+          "type": "string",
+          "required": true,
+          "max_length": 500
+        }
+      },
+      "lookup": {
+        "id_from_arg": "order_id"
+      },
+      "visible_fields": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "status",
+        "amount_cents",
+        "refund_note",
+        "updated_at"
+      ],
+      "kept_out_fields": [
+        "payment_token",
+        "internal_fraud_score"
+      ],
+      "evidence": {
+        "required": true,
+        "query_audit": true
+      },
+      "max_rows": 1,
+      "proposal": {
+        "action": "support.mark_refund_for_review",
+        "allowed_fields": [
+          "status",
+          "refund_note"
+        ],
+        "patch": {
+          "status": {
+            "fixed": "refund_review"
+          },
+          "refund_note": {
+            "from_arg": "refund_note"
+          }
+        },
+        "conflict_guard": {
+          "column": "updated_at"
+        },
+        "approval": {
+          "mode": "human",
+          "required_role": "support_lead"
+        },
+        "writeback": {
+          "mode": "direct_sql"
+        }
+      }
+    }
+  ],
+  "workflows": [
+    {
+      "name": "support.refund_request",
+      "context": "support_agent_context",
+      "allowed_capabilities": [
+        "support.inspect_order",
+        "support.propose_refund_review"
+      ],
+      "required_evidence": true,
+      "approval": {
+        "required": true,
+        "role": "support_lead"
+      },
+      "settlement": {
+        "mode": "manual"
+      },
+      "replay": {
+        "checkpoint": "proposal_only"
+      }
+    }
+  ]
+}

package/fixtures/conformance/kept-out-fields/contract.json

@@ -0,0 +1,47 @@
+{
+  "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",
+        "late_fee_cents"
+      ],
+      "kept_out_fields": [
+        "card_token",
+        "internal_risk_score"
+      ]
+    }
+  ]
+}

package/fixtures/conformance/kept-out-fields/expected.redaction.json

@@ -0,0 +1,11 @@
+{
+  "visible": {
+    "id": "INV-3001",
+    "tenant_id": "acme",
+    "late_fee_cents": 5500
+  },
+  "redacted_fields": [
+    "card_token",
+    "internal_risk_score"
+  ]
+}

package/fixtures/conformance/kept-out-fields/scenario.json

@@ -0,0 +1,9 @@
+{
+  "source_row": {
+    "id": "INV-3001",
+    "tenant_id": "acme",
+    "late_fee_cents": 5500,
+    "card_token": "tok_should_not_leak",
+    "internal_risk_score": 91
+  }
+}

package/fixtures/conformance/manual-approval/contract.json

@@ -0,0 +1,66 @@
+{
+  "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.propose_late_fee_waiver",
+      "kind": "proposal",
+      "context": "local_operator",
+      "subject": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id",
+        "conflict_key": "updated_at"
+      },
+      "args": {
+        "invoice_id": {
+          "type": "string"
+        }
+      },
+      "lookup": {
+        "id_from_arg": "invoice_id"
+      },
+      "visible_fields": [
+        "id",
+        "tenant_id",
+        "late_fee_cents",
+        "updated_at"
+      ],
+      "proposal": {
+        "action": "billing.waive_late_fee",
+        "allowed_fields": [
+          "late_fee_cents"
+        ],
+        "patch": {
+          "late_fee_cents": {
+            "fixed": 0
+          }
+        },
+        "conflict_guard": {
+          "column": "updated_at"
+        },
+        "approval": {
+          "mode": "human",
+          "required_role": "billing_lead"
+        },
+        "writeback": {
+          "mode": "direct_sql"
+        }
+      }
+    }
+  ]
+}

package/fixtures/conformance/manual-approval/expected.proposal.json

@@ -0,0 +1,9 @@
+{
+  "id": "wrp_INV_3001_late_fee_waiver",
+  "capability": "billing.propose_late_fee_waiver",
+  "subject": {
+    "id": "INV-3001",
+    "tenant_id": "acme"
+  },
+  "status": "approved"
+}

package/fixtures/conformance/manual-approval/scenario.json

@@ -0,0 +1,5 @@
+{
+  "proposal_id": "wrp_INV_3001_late_fee_waiver",
+  "operator": "billing_lead@example.com",
+  "decision": "approved"
+}