@fourier-labs/harbour-contracts 0.35.0 → 0.41.0

package/schema/transform-report.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://schemas.harbour.dev/transform-report.schema.json",
   "title": "TransformReport",
-  "description": "Structured output an agent must return from one Harbour transformation attempt. Handed to the agent as its output schema, then decoded and semantically re-validated by the control plane, which remains the authority. The enum on applied_playbooks.items is the one dynamic part: the adapter injects the names of the playbooks supplied for that invocation before writing the document, so the model is structurally prevented from naming a playbook it was not given. Application-secret handling was removed platform-wide, so this document carries no redactions and no secrets fields. A deployable report must also carry preservation_plan: the agent's own grounded smoke tests (one to three happy_path user journeys plus a boundary_check per behaviour its playbooks or edits could regress) that the validation cell executes after transformation, and an uncovered list naming every boundary it could not test and why. An unsupported report carries only application.unsupported and no plan.",
+  "description": "Structured output an agent must return from one Harbour transformation attempt. Handed to the agent as its output schema, then decoded and semantically re-validated by the control plane, which remains the authority. The enum on applied_playbooks.items is the one dynamic part: the adapter injects the names of the playbooks supplied for that invocation before writing the document, so the model is structurally prevented from naming a playbook it was not given. Application-secret handling was removed platform-wide, so this document carries no redactions and no secrets fields. A deployable report must also carry preservation_plan: the agent's own grounded smoke tests (one to three happy_path user journeys plus a boundary_check per behaviour its playbooks or edits could regress) that the validation cell executes after transformation, and an uncovered list naming every boundary it could not test and why. It also carries validation_fixtures: null when no external fixture is needed, or a bounded generic HTTP/WebSocket fixture declaration for that one run. An unsupported report carries only application.unsupported and no plan or fixtures.",
   "x-go-embed": true,
   "type": "object",
   "additionalProperties": false,
@@ -56,21 +56,19 @@
         "changeType",
         "requiresCodeChanges",
         "requiresSchemaMigration",
-        "desiredSchemaPath",
         "migrationPaths",
         "changedFiles",
         "evidence",
         "unsupportedFeatures"
       ],
       "properties": {
-        "mode": { "type": "string", "enum": ["none", "sql", "unsupported"] },
+        "mode": { "type": "string", "enum": ["none", "sql"] },
         "changeType": {
           "type": "string",
           "enum": ["none", "code_only", "schema_only", "code_and_schema"]
         },
         "requiresCodeChanges": { "type": "boolean" },
         "requiresSchemaMigration": { "type": "boolean" },
-        "desiredSchemaPath": { "type": "string", "maxLength": 512 },
         "migrationPaths": {
           "type": "array",
           "maxItems": 128,
@@ -219,6 +217,86 @@
         }
       }
     },
+    "validation_fixtures": {
+      "description": "A bounded, non-secret fixture program for this transformation's throwaway validation cell. Null means the application needs no external fixture. Bindings use application-owned logical names and explicitly inject only generated fixture URLs; fixtures describe deterministic HTTP or WebSocket exchanges without naming an application or provider and without executable code. The deployment plane semantically verifies unique fixture ids, template references, operation coverage, JSON text and safe config updates before forwarding the spec to the data plane.",
+      "anyOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["version", "bindings", "fixtures"],
+          "properties": {
+            "version": { "type": "integer", "const": 1 },
+            "bindings": {
+              "description": "Bounded per-run fixture requirements. logical_name is an arbitrary application-owned binding name; deployment-plane semantic validation requires it to be unique within this array.",
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 32,
+              "items": { "$ref": "#/definitions/ValidationFixtureBinding" }
+            },
+            "fixtures": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 32,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["id", "type", "http", "websocket"],
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9-]{0,63}$"
+                  },
+                  "type": { "type": "string", "enum": ["http", "websocket"] },
+                  "http": {
+                    "anyOf": [
+                      { "$ref": "#/definitions/ValidationHttpFixture" },
+                      { "type": "null" }
+                    ]
+                  },
+                  "websocket": {
+                    "anyOf": [
+                      { "$ref": "#/definitions/ValidationWebSocketFixture" },
+                      { "type": "null" }
+                    ]
+                  }
+                },
+                "oneOf": [
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["id", "type", "http", "websocket"],
+                    "properties": {
+                      "id": {
+                        "type": "string",
+                        "pattern": "^[a-z][a-z0-9-]{0,63}$"
+                      },
+                      "type": { "const": "http" },
+                      "http": { "$ref": "#/definitions/ValidationHttpFixture" },
+                      "websocket": { "type": "null" }
+                    }
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["id", "type", "http", "websocket"],
+                    "properties": {
+                      "id": {
+                        "type": "string",
+                        "pattern": "^[a-z][a-z0-9-]{0,63}$"
+                      },
+                      "type": { "const": "websocket" },
+                      "http": { "type": "null" },
+                      "websocket": { "$ref": "#/definitions/ValidationWebSocketFixture" }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        },
+        { "type": "null" }
+      ]
+    },
     "application": {
       "type": "object",
       "additionalProperties": false,
@@ -226,11 +304,42 @@
         "unsupported": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["capability", "constraint", "reason"],
+          "required": ["category", "capability", "operation", "constraint", "reason", "evidence"],
           "properties": {
+            "category": {
+              "type": "string",
+              "enum": [
+                "auth.validation-seed-unsupported",
+                "auth.identity-entity-unresolvable",
+                "capability.unsupported"
+              ],
+              "description": "Closed machine category selected independently from the human explanation."
+            },
             "capability": { "type": "string", "minLength": 1, "maxLength": 512 },
+            "operation": {
+              "description": "The exact source operation that cannot be preserved, such as a cross-document transactional write. Name a concrete operation, not an engine or product.",
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512
+            },
             "constraint": { "type": "string", "minLength": 1, "maxLength": 512 },
-            "reason": { "type": "string", "minLength": 1, "maxLength": 2048 }
+            "reason": { "type": "string", "minLength": 1, "maxLength": 2048 },
+            "evidence": {
+              "description": "Exact source locations proving the required operation and the unsupported platform capability. Environment failures and unfinished conversion work are not evidence.",
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 32,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["path", "line", "reason"],
+                "properties": {
+                  "path": { "type": "string", "minLength": 1, "maxLength": 512 },
+                  "line": { "type": "integer", "minimum": 1 },
+                  "reason": { "type": "string", "minLength": 1, "maxLength": 1024 }
+                }
+              }
+            }
           }
         },
         "runtime": {
@@ -262,23 +371,18 @@
           ]
         },
         "validationSeed": {
-          "description": "Build-only bootstrap for authenticated browser validation. Use null when the application does not require a local database user. When local authorization resolves Harbour identity to an application-owned user or membership row, declare an idempotent command that creates the fixed validation identity in the throwaway database. Reuse an existing seed command when available; otherwise add the smallest validation-only script using the application's existing database layer. The command is never run during production deployment.",
+          "description": "Build-only PostgreSQL bootstrap for authenticated browser validation. Use null when the application does not require a pre-existing database identity. The SQL file runs only in Harbour's throwaway validation database after migrations and before candidate boot. Harbour supplies the fixed probe subject and lowercased email as transaction-local settings.",
           "anyOf": [
             {
               "type": "object",
               "additionalProperties": false,
-              "required": ["command", "identityEmailEnvironmentVariable"],
+              "required": ["kind", "path"],
               "properties": {
-                "command": {
-                  "type": "array",
-                  "minItems": 1,
-                  "maxItems": 64,
-                  "items": { "type": "string", "minLength": 1, "maxLength": 1024 }
-                },
-                "identityEmailEnvironmentVariable": {
+                "kind": { "type": "string", "const": "sql" },
+                "path": {
                   "type": "string",
-                  "pattern": "^[A-Z][A-Z0-9_]{0,127}$",
-                  "description": "Existing application-owned environment variable that receives the trusted browser probe email, for example ADMIN_EMAIL."
+                  "pattern": "^\\.harbour/validation/(?:[^/]+/)*[^/]+\\.sql$",
+                  "maxLength": 512
                 }
               }
             },
@@ -360,9 +464,209 @@
       }
     }
   },
+  "definitions": {
+    "ValidationFixtureBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["logical_name", "operations", "environment", "config"],
+      "properties": {
+        "logical_name": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+        },
+        "fixture_id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{0,63}$",
+          "description": "Optional explicit fixture association for a binding that has no URL mapping, such as a credential-only binding."
+        },
+        "operations": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 5,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": ["http", "websocket", "email", "webhook", "ai"]
+          }
+        },
+        "environment": {
+          "description": "Environment variables that receive a generated fixture URL. Values cannot carry arbitrary configuration or secrets.",
+          "type": "array",
+          "maxItems": 32,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
+              },
+              "value": {
+                "type": "string",
+                "pattern": "^\\{\\{fixture\\.[a-z][a-z0-9-]{0,63}\\.url\\}\\}$"
+              },
+              "test_value": {
+                "type": "string",
+                "minLength": 13,
+                "maxLength": 256,
+                "pattern": "^harbour-test-[^:/\\s]{1,243}$",
+                "description": "Validation-only synthetic credential. It is never exported as deployed runtime configuration."
+              }
+            },
+            "oneOf": [
+              { "required": ["value"], "not": { "required": ["test_value"] } },
+              { "required": ["test_value"], "not": { "required": ["value"] } }
+            ]
+          }
+        },
+        "config": {
+          "description": "Structured JSON or YAML keys that receive a generated fixture URL in a bounded relative application config file.",
+          "type": "array",
+          "maxItems": 32,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "format", "key", "value"],
+            "properties": {
+              "path": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 512,
+                "pattern": "^(?:[A-Za-z0-9_-][A-Za-z0-9._-]*/)*[A-Za-z0-9_-][A-Za-z0-9._-]*$"
+              },
+              "format": { "type": "string", "enum": ["json", "yaml"] },
+              "key": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 256,
+                "pattern": "^[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*$"
+              },
+              "value": {
+                "type": "string",
+                "pattern": "^\\{\\{fixture\\.[a-z][a-z0-9-]{0,63}\\.url\\}\\}$"
+              }
+            }
+          }
+        }
+      }
+    },
+    "ValidationFixtureNameValuePairs": {
+      "type": "array",
+      "maxItems": 32,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "value"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1, "maxLength": 128 },
+          "value": { "type": "string", "maxLength": 2048 }
+        }
+      }
+    },
+    "ValidationHttpFixture": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["base_path", "routes"],
+      "properties": {
+        "base_path": {
+          "type": "string",
+          "maxLength": 512,
+          "pattern": "^/(?:[A-Za-z0-9._~-]+(?:/[A-Za-z0-9._~-]+)*)?$"
+        },
+        "routes": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["operation", "request", "response"],
+            "properties": {
+              "operation": {
+                "type": "string",
+                "enum": ["http", "email", "webhook", "ai"]
+              },
+              "request": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["method", "path", "query", "headers", "body"],
+                "properties": {
+                  "method": {
+                    "type": "string",
+                    "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"]
+                  },
+                  "path": {
+                    "type": "string",
+                    "maxLength": 512,
+                    "pattern": "^/(?:[A-Za-z0-9._~-]+(?:/[A-Za-z0-9._~-]+)*)?$"
+                  },
+                  "query": { "$ref": "#/definitions/ValidationFixtureNameValuePairs" },
+                  "headers": { "$ref": "#/definitions/ValidationFixtureNameValuePairs" },
+                  "body": { "type": "string", "maxLength": 16384 }
+                }
+              },
+              "response": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["status", "headers", "body"],
+                "properties": {
+                  "status": { "type": "integer", "minimum": 100, "maximum": 599 },
+                  "headers": { "$ref": "#/definitions/ValidationFixtureNameValuePairs" },
+                  "body": { "type": "string", "maxLength": 16384 }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "ValidationWebSocketFixture": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "expected_json", "send_messages", "close"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "maxLength": 512,
+          "pattern": "^/(?:[A-Za-z0-9._~-]+(?:/[A-Za-z0-9._~-]+)*)?$"
+        },
+        "expected_json": {
+          "description": "Exact JSON value the fixture expects as the first client message, or null when no client message is required. JSON parsing is a semantic check.",
+          "anyOf": [
+            { "type": "string", "minLength": 1, "maxLength": 16384 },
+            { "type": "null" }
+          ]
+        },
+        "send_messages": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": { "type": "string", "maxLength": 16384 }
+        },
+        "close": {
+          "anyOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["code", "reason"],
+              "properties": {
+                "code": { "type": "integer", "minimum": 1000, "maximum": 4999 },
+                "reason": { "type": "string", "maxLength": 123 }
+              }
+            },
+            { "type": "null" }
+          ]
+        }
+      }
+    }
+  },
+  "x-unique-array-by": [
+    { "field": "validation_fixtures.bindings", "key": "logical_name" }
+  ],
   "oneOf": [
     {
-      "required": ["applied_playbooks", "static_rebuild_required", "analysis", "database", "preservation_plan", "application"],
+      "required": ["applied_playbooks", "static_rebuild_required", "analysis", "database", "preservation_plan", "validation_fixtures", "application"],
       "properties": {
         "application": {
           "required": ["runtime", "buildKind", "topology", "entrypoint", "build", "basePath", "evidence", "unsupportedFeatures"],