@synapsor/runner 0.1.0-alpha.9 → 0.1.0

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

@@ -0,0 +1,140 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.synapsor.ai/synapsor.change-set.v1.schema.json",
+  "title": "Synapsor Change Set v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "proposal_id",
+    "proposal_version",
+    "action",
+    "mode",
+    "principal",
+    "scope",
+    "source",
+    "before",
+    "patch",
+    "after",
+    "guards",
+    "evidence",
+    "approval",
+    "writeback",
+    "source_database_mutated",
+    "integrity",
+    "created_at"
+  ],
+  "properties": {
+    "schema_version": { "const": "synapsor.change-set.v1" },
+    "proposal_id": { "type": "string", "minLength": 1 },
+    "proposal_version": { "type": "integer", "minimum": 1 },
+    "action": { "type": "string", "minLength": 1 },
+    "mode": { "enum": ["read_only", "shadow", "review_required", "approved_for_writeback"] },
+    "principal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "source"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "source": { "enum": ["trusted_session", "cloud_session", "environment", "static_dev"] }
+      }
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tenant_id", "business_object", "object_id"],
+      "properties": {
+        "tenant_id": { "type": "string", "minLength": 1 },
+        "business_object": { "type": "string", "minLength": 1 },
+        "object_id": { "type": "string", "minLength": 1 }
+      }
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "source_id", "schema", "table", "primary_key"],
+      "properties": {
+        "kind": { "enum": ["external_postgres", "external_mysql", "synapsor_table"] },
+        "source_id": { "type": "string", "minLength": 1 },
+        "schema": { "$ref": "#/$defs/safeIdentifier" },
+        "table": { "$ref": "#/$defs/safeIdentifier" },
+        "primary_key": { "$ref": "#/$defs/columnValue" }
+      }
+    },
+    "before": { "$ref": "#/$defs/scalarMap" },
+    "patch": { "$ref": "#/$defs/scalarMap" },
+    "after": { "$ref": "#/$defs/scalarMap" },
+    "guards": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tenant", "allowed_columns", "expected_version"],
+      "properties": {
+        "tenant": { "$ref": "#/$defs/columnValue" },
+        "allowed_columns": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/safeIdentifier" },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "expected_version": { "$ref": "#/$defs/columnValue" }
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["bundle_id", "query_fingerprint", "items"],
+      "properties": {
+        "bundle_id": { "type": "string", "minLength": 1 },
+        "query_fingerprint": { "type": "string", "pattern": "^sha256:.+" },
+        "items": { "type": "array" }
+      }
+    },
+    "approval": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["status"],
+      "properties": {
+        "status": { "enum": ["pending", "approved", "rejected", "canceled"] },
+        "required_role": { "type": "string" }
+      }
+    },
+    "writeback": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["status", "mode"],
+      "properties": {
+        "status": { "enum": ["not_applied", "pending_worker", "applied", "conflict", "failed", "canceled"] },
+        "mode": { "enum": ["trusted_worker_required", "synapsor_merge", "read_only"] }
+      }
+    },
+    "source_database_mutated": { "type": "boolean" },
+    "integrity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["proposal_hash"],
+      "properties": {
+        "proposal_hash": { "type": "string", "pattern": "^sha256:.+" }
+      }
+    },
+    "created_at": { "type": "string", "format": "date-time" }
+  },
+  "$defs": {
+    "safeIdentifier": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+    "scalar": { "type": ["string", "number", "boolean", "null"] },
+    "scalarMap": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/safeIdentifier" },
+      "additionalProperties": { "$ref": "#/$defs/scalar" },
+      "minProperties": 1
+    },
+    "columnValue": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["column", "value"],
+      "properties": {
+        "column": { "$ref": "#/$defs/safeIdentifier" },
+        "value": { "$ref": "#/$defs/scalar" }
+      }
+    }
+  }
+}

package/schemas/execution-receipt.v1.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.synapsor.ai/synapsor.execution-receipt.v1.schema.json",
+  "title": "Synapsor Execution Receipt v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "writeback_job_id",
+    "proposal_id",
+    "runner_id",
+    "status",
+    "rows_affected",
+    "idempotency_key",
+    "source_database_mutated",
+    "executed_at",
+    "receipt_hash"
+  ],
+  "properties": {
+    "schema_version": { "const": "synapsor.execution-receipt.v1" },
+    "writeback_job_id": { "type": "string", "minLength": 1 },
+    "proposal_id": { "type": "string", "minLength": 1 },
+    "runner_id": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["applied", "conflict", "failed", "canceled", "already_applied"] },
+    "rows_affected": { "type": "integer", "minimum": 0 },
+    "idempotency_key": { "type": "string", "minLength": 1 },
+    "previous_version": { "type": ["string", "number", "boolean", "null"] },
+    "new_version": { "type": ["string", "number", "boolean", "null"] },
+    "source_database_mutated": { "type": "boolean" },
+    "executed_at": { "type": "string", "format": "date-time" },
+    "safe_error_code": { "type": "string" },
+    "receipt_hash": { "type": "string", "pattern": "^sha256:.+" }
+  }
+}

package/schemas/onboarding-selection.v1.schema.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.synapsor.ai/runner/onboarding-selection.v1.schema.json",
+  "title": "Synapsor Runner onboarding selection",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["engine", "schema", "table", "primary_key", "namespace", "visible_columns"],
+  "properties": {
+    "version": { "const": 1 },
+    "engine": { "enum": ["postgres", "mysql"] },
+    "mode": { "enum": ["read_only", "shadow", "review"] },
+    "source_name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+    "read_url_env": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*$" },
+    "database_url_env": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*$" },
+    "write_url_env": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*$" },
+    "statement_timeout_ms": { "type": "integer", "minimum": 1 },
+    "schema": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+    "table": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+    "primary_key": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+    "tenant_key": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+    "single_tenant_dev": { "type": "boolean" },
+    "conflict_column": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+    "namespace": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+    "object_name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+    "read_tool": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)+$" },
+    "proposal_tool": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)+$" },
+    "inspect_tool_name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)+$" },
+    "proposal_tool_name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)+$" },
+    "inspect_description": { "type": "string", "minLength": 1 },
+    "proposal_description": { "type": "string", "minLength": 1 },
+    "inspect_returns_hint": { "type": "string", "minLength": 1 },
+    "proposal_returns_hint": { "type": "string", "minLength": 1 },
+    "lookup_arg": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+    "result_format": { "enum": [1, 2] },
+    "visible_columns": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "allowed_columns": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+      "uniqueItems": true
+    },
+    "patch": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "fixed": { "type": ["string", "number", "boolean", "null"] },
+          "from_arg": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }
+        },
+        "oneOf": [
+          { "required": ["fixed"] },
+          { "required": ["from_arg"] }
+        ]
+      }
+    },
+    "patch_args": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "type": { "enum": ["string", "number", "boolean"] },
+          "required": { "type": "boolean" },
+          "max_length": { "type": "integer", "minimum": 1 },
+          "minimum": { "type": "number" },
+          "maximum": { "type": "number" },
+          "enum": {
+            "type": "array",
+            "items": { "type": ["string", "number", "boolean", "null"] }
+          }
+        }
+      }
+    },
+    "numeric_bounds": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "minProperties": 1,
+        "properties": {
+          "minimum": { "type": "number" },
+          "maximum": { "type": "number" }
+        }
+      }
+    },
+    "transition_guards": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["allowed"],
+        "properties": {
+          "from_column": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+          "allowed": {
+            "type": "object",
+            "minProperties": 1,
+            "additionalProperties": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "minItems": 1,
+              "uniqueItems": true
+            }
+          }
+        }
+      }
+    },
+    "trusted_context": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tenant_id_env": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*$" },
+        "principal_env": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*$" }
+      }
+    },
+    "approval": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "required_role": { "type": "string" }
+      }
+    }
+  },
+  "anyOf": [
+    { "required": ["tenant_key"] },
+    { "required": ["single_tenant_dev"] }
+  ]
+}

package/schemas/runner-registration.v1.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.synapsor.ai/synapsor.runner-registration.v1.schema.json",
+  "title": "Synapsor Runner Registration v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "runner_id",
+    "runner_version",
+    "engines",
+    "capabilities",
+    "scope",
+    "registered_at"
+  ],
+  "properties": {
+    "schema_version": { "const": "synapsor.runner-registration.v1" },
+    "runner_id": { "type": "string", "minLength": 1 },
+    "runner_version": { "type": "string", "minLength": 1 },
+    "engines": {
+      "type": "array",
+      "items": { "enum": ["postgres", "mysql"] },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "capabilities": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["project_id", "source_ids"],
+      "properties": {
+        "project_id": { "type": "string", "minLength": 1 },
+        "source_ids": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      }
+    },
+    "registered_at": { "type": "string", "format": "date-time" }
+  }
+}

package/schemas/synapsor.app-handler-receipt.v1.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://synapsor.ai/schemas/synapsor.app-handler-receipt.v1.json",
+  "title": "Synapsor App-Owned Writeback Handler Receipt v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["status", "rows_affected", "source_database_mutated"],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["applied", "already_applied", "conflict", "failed"]
+    },
+    "rows_affected": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "source_database_mutated": {
+      "type": "boolean"
+    },
+    "previous_version": {
+      "$ref": "#/$defs/scalar"
+    },
+    "new_version": {
+      "$ref": "#/$defs/scalar"
+    },
+    "safe_error_code": {
+      "type": ["string", "null"]
+    },
+    "details": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  },
+  "$defs": {
+    "scalar": {
+      "type": ["string", "number", "boolean", "null"]
+    }
+  }
+}

package/schemas/synapsor.app-handler-request.v1.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://synapsor.ai/schemas/synapsor.app-handler-request.v1.json",
+  "title": "Synapsor App-Owned Writeback Handler Request v1",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["proposal_id", "idempotency_key", "change_set"],
+  "properties": {
+    "protocol_version": {
+      "type": "string",
+      "enum": ["1.0"]
+    },
+    "schema_version": {
+      "type": "string",
+      "enum": ["synapsor.handler-writeback.v1"]
+    },
+    "proposal_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "idempotency_key": {
+      "type": "string",
+      "minLength": 1
+    },
+    "issued_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "signature": {
+      "type": "string",
+      "pattern": "^sha256=[a-fA-F0-9]{64}$"
+    },
+    "change_set": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["action", "scope", "target", "patch", "guards"],
+      "properties": {
+        "action": {
+          "type": "string",
+          "minLength": 1
+        },
+        "scope": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["tenant_id", "object_id"],
+          "properties": {
+            "tenant_id": { "type": ["string", "number", "boolean"] },
+            "object_id": { "type": ["string", "number", "boolean"] }
+          }
+        },
+        "principal": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "id": { "type": "string" }
+          }
+        },
+        "target": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["schema", "table", "primary_key"],
+          "properties": {
+            "schema": { "$ref": "#/$defs/identifier" },
+            "table": { "$ref": "#/$defs/identifier" },
+            "primary_key": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["column", "value"],
+              "properties": {
+                "column": { "$ref": "#/$defs/identifier" },
+                "value": { "$ref": "#/$defs/scalar" }
+              }
+            }
+          }
+        },
+        "patch": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": { "$ref": "#/$defs/scalar" },
+          "propertyNames": { "$ref": "#/$defs/identifier" }
+        },
+        "guards": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["tenant", "expected_version"],
+          "properties": {
+            "tenant": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["column", "value"],
+              "properties": {
+                "column": { "$ref": "#/$defs/identifier" },
+                "value": { "$ref": "#/$defs/scalar" }
+              }
+            },
+            "expected_version": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["column", "value"],
+              "properties": {
+                "column": { "$ref": "#/$defs/identifier" },
+                "value": { "$ref": "#/$defs/scalar" }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+    },
+    "scalar": {
+      "type": ["string", "number", "boolean", "null"]
+    }
+  }
+}