@fourier-labs/harbour-contracts 0.4.0 → 0.6.0

package/schema/ai-transform-event.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-transform-event.schema.json",
+  "title": "AiTransformEvent",
+  "description": "Checksum-bound deterministic AI interception task input. Entries are the complete ordered PLAN interception plan so the task can verify the governance plan digest before applying its deterministic subset; source and patches are referenced, never embedded.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "tenantId", "appId", "environment", "versionId", "sourceRevision", "workspace", "inventoryDigest", "policyDigest", "runtimeContractDigest", "interceptionPlanDigest", "entries"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.ai-transform-event/1.0" },
+    "tenantId": { "$ref": "#/definitions/AiTransformIdentifier" },
+    "appId": { "$ref": "#/definitions/AiTransformIdentifier" },
+    "environment": { "$ref": "#/definitions/AiTransformIdentifier" },
+    "versionId": { "type": "string", "minLength": 7, "maxLength": 320, "pattern": "^[^#]+#[^#]+#[^#]+#[0-9]{6,}$" },
+    "sourceRevision": { "type": "string", "minLength": 7, "maxLength": 128 },
+    "workspace": { "$ref": "#/definitions/AiTransformWorkspace" },
+    "inventoryDigest": { "$ref": "#/definitions/AiTransformDigest" },
+    "policyDigest": { "$ref": "#/definitions/AiTransformDigest" },
+    "runtimeContractDigest": { "$ref": "#/definitions/AiTransformDigest" },
+    "interceptionPlanDigest": { "$ref": "#/definitions/AiTransformDigest" },
+    "entries": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 1000,
+      "items": { "$ref": "#/definitions/AiTransformPlanEntry" }
+    }
+  },
+  "definitions": {
+    "AiTransformIdentifier": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.@/-]*$" },
+    "AiTransformDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "AiTransformWorkspace": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["bucket", "key", "sha256", "size"],
+      "properties": {
+        "bucket": { "type": "string", "minLength": 3, "maxLength": 63 },
+        "key": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "sha256": { "$ref": "#/definitions/AiTransformDigest" },
+        "size": { "type": "integer", "minimum": 1, "maximum": 536870912 }
+      }
+    },
+    "AiTransformPlanEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["callSiteFingerprint", "sourcePath", "expectedSourceFileSha256", "strategy", "allowedSyntaxKinds"],
+      "properties": {
+        "callSiteFingerprint": { "$ref": "#/definitions/AiTransformDigest" },
+        "sourcePath": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))[^\\u0000]+$" },
+        "expectedSourceFileSha256": { "$ref": "#/definitions/AiTransformDigest" },
+        "strategy": { "type": "string", "enum": ["deployment_injection", "deterministic_adapter"] },
+        "configurationMappingId": { "$ref": "#/definitions/AiTransformIdentifier" },
+        "configurationMappingVersion": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "transformId": { "$ref": "#/definitions/AiTransformIdentifier" },
+        "transformVersion": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "allowedSyntaxKinds": { "type": "array", "minItems": 1, "maxItems": 32, "uniqueItems": true, "items": { "$ref": "#/definitions/AiTransformIdentifier" } },
+        "runtimeShimName": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^@?[A-Za-z0-9][A-Za-z0-9_.@/-]*$" },
+        "runtimeShimVersion": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "runtimeShimDigest": { "$ref": "#/definitions/AiTransformDigest" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "strategy": { "const": "deployment_injection" } }, "required": ["strategy"] },
+          "then": { "required": ["configurationMappingId", "configurationMappingVersion"] }
+        },
+        {
+          "if": { "properties": { "strategy": { "const": "deterministic_adapter" } }, "required": ["strategy"] },
+          "then": { "required": ["transformId", "transformVersion", "runtimeShimName", "runtimeShimVersion", "runtimeShimDigest"] }
+        }
+      ]
+    }
+  }
+}

package/schema/ai-transform-result.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-transform-result.schema.json",
+  "title": "AiTransformResult",
+  "description": "Bounded deterministic interception result; contains descriptors and digest evidence only.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "workspace", "interceptionPlanDigest", "transformerVersion", "applied"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.ai-transform-result/1.0" },
+    "workspace": { "$ref": "#/definitions/AiTransformResultWorkspace" },
+    "interceptionPlanDigest": { "$ref": "#/definitions/AiTransformResultDigest" },
+    "transformerVersion": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "applied": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/definitions/AiTransformApplied" } }
+  },
+  "definitions": {
+    "AiTransformResultIdentifier": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.@/-]*$" },
+    "AiTransformResultDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "AiTransformResultWorkspace": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["bucket", "key", "sha256", "size"],
+      "properties": {
+        "bucket": { "type": "string", "minLength": 3, "maxLength": 63 },
+        "key": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "sha256": { "$ref": "#/definitions/AiTransformResultDigest" },
+        "size": { "type": "integer", "minimum": 1, "maximum": 536870912 }
+      }
+    },
+    "AiTransformApplied": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["callSiteFingerprint", "transformId", "transformVersion", "sourcePath", "beforeSha256", "afterSha256", "governedBoundaryFingerprint", "runtimeShimDigest"],
+      "properties": {
+        "callSiteFingerprint": { "$ref": "#/definitions/AiTransformResultDigest" },
+        "transformId": { "$ref": "#/definitions/AiTransformResultIdentifier" },
+        "transformVersion": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "sourcePath": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))[^\\u0000]+$" },
+        "beforeSha256": { "$ref": "#/definitions/AiTransformResultDigest" },
+        "afterSha256": { "$ref": "#/definitions/AiTransformResultDigest" },
+        "governedBoundaryFingerprint": { "$ref": "#/definitions/AiTransformResultDigest" },
+        "runtimeShimDigest": { "$ref": "#/definitions/AiTransformResultDigest" }
+      }
+    }
+  }
+}

package/schema/ai-verification-evidence.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-verification-evidence.schema.json",
+  "title": "AiVerificationEvidence",
+  "description": "Bounded, value-free evidence submitted by deployment verification for one governed version.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "tenantId", "appId", "environment", "versionId", "sourceRevision", "inventoryDigest", "interceptionPlanDigest", "runtimeContractDigest", "policyDigest", "finalWorkspaceDigest", "verifiedCallsiteFingerprints", "appliedTransforms", "endpointChecks", "providerCredentialsAbsent", "smokeTraceId", "evidenceDigest", "verifiedAt"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.ai-verification-evidence/1.0" },
+    "tenantId": { "$ref": "#/definitions/AiVerificationIdentifier" },
+    "appId": { "$ref": "#/definitions/AiVerificationIdentifier" },
+    "environment": { "$ref": "#/definitions/AiVerificationIdentifier" },
+    "versionId": { "type": "string", "minLength": 7, "maxLength": 320, "pattern": "^[^#]+#[^#]+#[^#]+#[0-9]{6,}$" },
+    "sourceRevision": { "type": "string", "minLength": 7, "maxLength": 128 },
+    "inventoryDigest": { "$ref": "#/definitions/AiVerificationDigest" },
+    "interceptionPlanDigest": { "$ref": "#/definitions/AiVerificationDigest" },
+    "runtimeContractDigest": { "$ref": "#/definitions/AiVerificationDigest" },
+    "policyDigest": { "$ref": "#/definitions/AiVerificationDigest" },
+    "finalWorkspaceDigest": { "$ref": "#/definitions/AiVerificationDigest" },
+    "verifiedCallsiteFingerprints": { "type": "array", "maxItems": 1000, "uniqueItems": true, "items": { "$ref": "#/definitions/AiVerificationDigest" } },
+    "appliedTransforms": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/definitions/AiVerificationTransform" } },
+    "endpointChecks": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "$ref": "#/definitions/AiVerificationEndpointCheck" } },
+    "providerCredentialsAbsent": { "type": "boolean", "const": true },
+    "smokeTraceId": { "type": "string", "pattern": "^trc_[A-Za-z0-9_-]+$", "maxLength": 160 },
+    "evidenceDigest": { "$ref": "#/definitions/AiVerificationDigest" },
+    "verifiedAt": { "type": "string", "format": "date-time" }
+  },
+  "definitions": {
+    "AiVerificationIdentifier": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.@/-]*$" },
+    "AiVerificationDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "AiVerificationTransform": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["callSiteFingerprint", "governedBoundaryFingerprint", "transformId", "transformVersion", "beforeSha256", "afterSha256", "runtimeShimDigest"],
+      "properties": {
+        "callSiteFingerprint": { "$ref": "#/definitions/AiVerificationDigest" },
+        "governedBoundaryFingerprint": { "$ref": "#/definitions/AiVerificationDigest" },
+        "transformId": { "$ref": "#/definitions/AiVerificationIdentifier" },
+        "transformVersion": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "beforeSha256": { "$ref": "#/definitions/AiVerificationDigest" },
+        "afterSha256": { "$ref": "#/definitions/AiVerificationDigest" },
+        "runtimeShimDigest": { "$ref": "#/definitions/AiVerificationDigest" }
+      }
+    },
+    "AiVerificationEndpointCheck": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "passed", "configurationMappingVersion"],
+      "properties": {
+        "name": { "$ref": "#/definitions/AiVerificationIdentifier" },
+        "passed": { "type": "boolean", "const": true },
+        "configurationMappingVersion": { "type": "string", "minLength": 1, "maxLength": 128 }
+      }
+    }
+  }
+}

package/schema/data-dependency.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/data-dependency.schema.json",
+  "title": "DataDependency",
+  "description": "A single external data dependency of an app, either declared by the builder or detected during analysis. Classification records how the dependency resolved against the tenant's registered data-source inventory; matchedSourceId is present only when classification is matched.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["kind", "identifiers", "classification", "origin"],
+  "properties": {
+    "kind": {
+      "$ref": "#/definitions/DataDependencyKind"
+    },
+    "identifiers": {
+      "$ref": "#/definitions/DataDependencyIdentifiers"
+    },
+    "classification": {
+      "$ref": "#/definitions/DataDependencyClassification"
+    },
+    "matchedSourceId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "sourceId of the registered data source this dependency matched; present only when classification is matched."
+    },
+    "origin": {
+      "$ref": "#/definitions/DataDependencyOrigin"
+    }
+  },
+  "definitions": {
+    "DataDependencyKind": {
+      "type": "string",
+      "enum": ["database", "api", "app_owned_external"],
+      "description": "database = a SQL/warehouse connection; api = an HTTP(S) service; app_owned_external = infrastructure the app owns outside Harbour."
+    },
+    "DataDependencyIdentifiers": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["hosts", "envNames"],
+      "properties": {
+        "hosts": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Hostnames the dependency was observed or declared against."
+        },
+        "driver": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255,
+          "description": "Client driver/library that surfaced the dependency (e.g. pg, snowflake-sdk)."
+        },
+        "envNames": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Environment-variable names the app reads to configure this dependency."
+        }
+      },
+      "description": "Evidence identifying the dependency; used to match it against the registered source inventory."
+    },
+    "DataDependencyClassification": {
+      "type": "string",
+      "enum": ["matched", "out_of_scope", "unknown", "inventory", "app_owned_external"],
+      "description": "matched = resolved to a registered source; out_of_scope = resolved but not requestable; unknown = unresolvable; inventory = registered but unused; app_owned_external = app-owned, outside Harbour's remit."
+    },
+    "DataDependencyOrigin": {
+      "type": "string",
+      "enum": ["declared", "detected"],
+      "description": "declared = stated by the builder; detected = found by analysis."
+    }
+  },
+  "examples": [
+    {
+      "kind": "database",
+      "identifiers": {
+        "hosts": ["analytics.internal.example.com"],
+        "driver": "pg",
+        "envNames": ["DATABASE_URL"]
+      },
+      "classification": "matched",
+      "matchedSourceId": "analytics-warehouse",
+      "origin": "detected"
+    }
+  ]
+}

package/schema/data-grant.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/data-grant.schema.json",
+  "title": "DataGrant",
+  "description": "An app's approved (or requested) read scope against a registered data source. MVP is deliberately narrow: mode is read-only and identityModel is service (one minted principal per grant, no per-end-user identity passthrough). Grant status is a tiny state machine — legal edges live in x-transitions and codegen turns them into shared CanTransitionDataGrantStatus / IsTerminalDataGrantStatus helpers so control-plane and consumers agree on legality.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["appId", "sourceId", "scope", "mode", "identityModel", "status"],
+  "properties": {
+    "appId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "App the grant belongs to."
+    },
+    "sourceId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "Registered data source the grant targets (data-source.schema.json)."
+    },
+    "scope": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "minItems": 1,
+      "description": "Requested/granted selectors; every selector must fall inside the source's allowedScope."
+    },
+    "mode": {
+      "$ref": "#/definitions/DataGrantMode"
+    },
+    "identityModel": {
+      "$ref": "#/definitions/DataGrantIdentityModel"
+    },
+    "status": {
+      "$ref": "#/definitions/DataGrantStatus"
+    },
+    "credentialRef": {
+      "type": "string",
+      "pattern": "^secretref://[A-Za-z0-9][A-Za-z0-9/_.:-]*$",
+      "description": "secretref URI of the minted per-grant credential; present once GRANTED."
+    },
+    "mintedPrincipal": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "Name of the scoped principal minted on the source for this grant; present once GRANTED."
+    },
+    "requestedByOperationId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "Operation (e.g. deployment analysis) that raised the request, for audit correlation."
+    },
+    "approvedBy": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "Admin identity that resolved the request; present once GRANTED or DENIED."
+    },
+    "approvedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "RFC 3339 instant the request was resolved; present once GRANTED or DENIED."
+    }
+  },
+  "definitions": {
+    "DataGrantMode": {
+      "type": "string",
+      "enum": ["read"],
+      "description": "Access mode. MVP is read-only; write is a deliberate future schema change."
+    },
+    "DataGrantIdentityModel": {
+      "type": "string",
+      "enum": ["service"],
+      "description": "MVP: one minted service principal per grant. Per-end-user passthrough is a future schema change."
+    },
+    "DataGrantStatus": {
+      "type": "string",
+      "enum": ["REQUESTED", "GRANTED", "DENIED"],
+      "description": "Grant lifecycle state. Legal edges live in x-transitions; GRANTED and DENIED are terminal."
+    }
+  },
+  "x-status-definition": "DataGrantStatus",
+  "x-terminal": ["GRANTED", "DENIED"],
+  "x-transitions": [
+    { "from": "REQUESTED", "to": "GRANTED", "trigger": "admin approves: scope within allowedScope, principal minted, credentialRef set" },
+    { "from": "REQUESTED", "to": "DENIED", "trigger": "admin declines the request" }
+  ],
+  "examples": [
+    {
+      "appId": "reports",
+      "sourceId": "analytics-warehouse",
+      "scope": ["public.orders"],
+      "mode": "read",
+      "identityModel": "service",
+      "status": "GRANTED",
+      "credentialRef": "secretref://tenants/fourier/grants/reports/analytics-warehouse",
+      "mintedPrincipal": "harbour_grant_reports_analytics",
+      "requestedByOperationId": "fourier#reports#preview#1000042",
+      "approvedBy": "admin@fourier.example",
+      "approvedAt": "2026-08-05T12:00:00Z"
+    }
+  ]
+}

package/schema/data-source.schema.json

@@ -0,0 +1,151 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/data-source.schema.json",
+  "title": "DataSource",
+  "description": "An admin-registered external data source (Data-Access MVP). The credential the platform holds for the source never crosses this boundary — credentialRef is a secretref URI resolved internally. allowedScope is the admin-declared selector allowlist grants are checked against; observedScope is what discovery actually saw and is informational only.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "tenantId",
+    "sourceId",
+    "connector",
+    "displayName",
+    "endpoint",
+    "credentialRef",
+    "provisioningMode",
+    "allowedScope",
+    "requestableByBuilders",
+    "status"
+  ],
+  "properties": {
+    "tenantId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "Owning tenant (org) identifier."
+    },
+    "sourceId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "Tenant-unique data-source identifier."
+    },
+    "connector": {
+      "$ref": "#/definitions/DataSourceConnector"
+    },
+    "displayName": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "Human-readable name shown to admins and builders."
+    },
+    "endpoint": {
+      "$ref": "#/definitions/DataSourceEndpoint"
+    },
+    "credentialRef": {
+      "type": "string",
+      "pattern": "^secretref://[A-Za-z0-9][A-Za-z0-9/_.:-]*$",
+      "description": "secretref URI naming the platform-held credential for this source. The referenced value never crosses this boundary."
+    },
+    "provisioningMode": {
+      "$ref": "#/definitions/DataSourceProvisioningMode"
+    },
+    "allowedScope": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Admin-declared selector allowlist (e.g. schema.table patterns) that grant scopes are validated against."
+    },
+    "observedScope": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Selectors discovery actually observed on the source. Informational; never widens allowedScope."
+    },
+    "requestableByBuilders": {
+      "type": "boolean",
+      "description": "Whether builders may request grants against this source."
+    },
+    "status": {
+      "$ref": "#/definitions/DataSourceStatus"
+    }
+  },
+  "definitions": {
+    "DataSourceConnector": {
+      "type": "string",
+      "enum": ["postgres", "redshift", "bigquery", "databricks"],
+      "description": "Closed connector set for the Data-Access MVP."
+    },
+    "DataSourceEndpoint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["host"],
+      "properties": {
+        "host": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255,
+          "description": "Network host (or warehouse endpoint) of the source."
+        },
+        "port": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 65535,
+          "description": "TCP port; absent where the connector implies it."
+        },
+        "database": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255,
+          "description": "Database name (postgres/redshift-style connectors)."
+        },
+        "project": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255,
+          "description": "Project identifier (bigquery-style connectors)."
+        },
+        "workspace": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255,
+          "description": "Workspace identifier (databricks-style connectors)."
+        }
+      },
+      "description": "Connector endpoint coordinates. host is always present; database vs project/workspace depends on the connector family."
+    },
+    "DataSourceProvisioningMode": {
+      "type": "string",
+      "enum": ["byo", "harbour_managed"],
+      "description": "byo = admin brought existing infrastructure; harbour_managed = Harbour provisioned it."
+    },
+    "DataSourceStatus": {
+      "type": "string",
+      "enum": ["ACTIVE", "DISABLED"],
+      "description": "DISABLED sources reject new grants and suspend existing access."
+    }
+  },
+  "examples": [
+    {
+      "tenantId": "fourier",
+      "sourceId": "analytics-warehouse",
+      "connector": "postgres",
+      "displayName": "Analytics Warehouse",
+      "endpoint": {
+        "host": "analytics.internal.example.com",
+        "port": 5432,
+        "database": "analytics"
+      },
+      "credentialRef": "secretref://tenants/fourier/sources/analytics-warehouse/admin",
+      "provisioningMode": "byo",
+      "allowedScope": ["public.orders", "public.customers"],
+      "observedScope": ["public.orders", "public.customers", "public.internal_audit"],
+      "requestableByBuilders": true,
+      "status": "ACTIVE"
+    }
+  ]
+}

package/schema/deploy-request.schema.json

@@ -30,9 +30,54 @@
       "type": "string",
       "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$",
       "description": "Optional legacy request-correlation value returned as requestId. It does not make repeated HTTP POSTs idempotent; versionId is the deployment identity and SQS deduplication key."
+    },
+    "environmentBindings": {
+      "$ref": "#/definitions/DeployRequestEnvironmentBindings"
     }
   },
   "definitions": {
+    "DeployRequestEnvironmentBindings": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["bindings"],
+      "properties": {
+        "bindings": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/DeployRequestEnvironmentBinding"
+          },
+          "description": "Environment-variable bindings for this deployment."
+        }
+      },
+      "description": "Optional runtime environment configuration (Secret-Manager MVP). Named environmentBindings, not environment — the existing required `environment` property is the deployment-target token and predates this object. Additive: requests without it remain valid."
+    },
+    "DeployRequestEnvironmentBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255,
+          "description": "Environment-variable name the app reads."
+        },
+        "secretRef": {
+          "type": "string",
+          "pattern": "^secretref://[A-Za-z0-9][A-Za-z0-9/_.:-]*$",
+          "description": "secretref URI resolved at runtime; the value never appears in the request."
+        },
+        "value": {
+          "type": "string",
+          "description": "Plain (non-secret) literal value."
+        }
+      },
+      "oneOf": [
+        { "required": ["secretRef"] },
+        { "required": ["value"] }
+      ],
+      "description": "One environment-variable binding: exactly one of secretRef (secret, resolved at runtime) or value (plain literal)."
+    },
     "DeployRequestSource": {
       "type": "object",
       "additionalProperties": false,
@@ -63,6 +108,21 @@
       "branch": "preview-deployment",
       "commit": "abc1234567890abcdef1234567890abcdef12345",
       "idempotencyKey": "deploy-attempt-123"
+    },
+    {
+      "source": {
+        "provider": "github",
+        "repositoryUrl": "https://github.com/Fourier-Labs-AI/focus-list"
+      },
+      "environment": "preview",
+      "branch": "preview-deployment",
+      "commit": "abc1234567890abcdef1234567890abcdef12345",
+      "environmentBindings": {
+        "bindings": [
+          { "name": "STRIPE_API_KEY", "secretRef": "secretref://tenants/fourier/apps/reports/STRIPE_API_KEY" },
+          { "name": "LOG_LEVEL", "value": "debug" }
+        ]
+      }
     }
   ]
 }

package/schema/error-category.enum.json

@@ -16,7 +16,9 @@
     { "id": "intake.unsupported-runtime", "retryable": false, "description": "Detected runtime has no Harbour build recipe." },
     { "id": "intake.attestation-missing", "retryable": false, "description": "Required auth attestation absent." },
     { "id": "intake.multi-app-repo", "retryable": false, "description": "Repo contains more than one deployable app." },
-    { "id": "secrets.unresolvable", "retryable": false, "description": "A referenced secret has no value (prod promotion blocks at GATING until a human sets it)." },
+    { "id": "secrets.unresolvable", "retryable": false, "retired": true, "description": "RETIRED 2026-08-08 and no longer emittable: the secret-materializer stack, its reconciler and the secret-reference playbook were all removed, so nothing can reach this state. Kept rather than deleted because historical failure records still carry it and a dropped id would decode to nothing. Do not emit in new code." },
+    { "id": "secrets.reference-unresolvable", "retryable": false, "description": "A governance secret reference supplied on the deploy request could not be resolved to a stored value — the secret does not exist, the read was denied, or the secretref:// URI is malformed. Not retryable: no amount of waiting produces the value, a human must set it (or fix the reference) before the deploy can proceed." },
+    { "id": "secrets.placeholder-unresolved", "retryable": false, "description": "The built workspace still contains a ${HARBOUR_REDACTED_<KEY>} substitution placeholder after transformation, meaning the transform never converted it into a runtime secret lookup and the artifact would ship a literal placeholder where a secret belongs. Not retryable: the workspace is already built, so the same input yields the same placeholder until the transform is corrected." },
     { "id": "secrets.leaked-in-artifact", "retryable": false, "description": "Artifact secret scan found a plaintext secret in the built image (belt-and-suspenders)." },
     { "id": "storage.sqlite-misclassified", "retryable": false, "description": "SQLite usage not resolvable to a managed binding." },
     { "id": "storage.unsupported-engine", "retryable": false, "family": true, "description": "Storage engine with no Harbour mapping; concrete token names the engine, e.g. storage.unsupported-engine.mongodb." },
@@ -27,6 +29,8 @@
     { "id": "frontend.env-inlined-unfixable", "retryable": false, "description": "Client code inlined build-time env/self-URLs in a way transformation cannot rewrite." },
     { "id": "build.recipe-failed", "retryable": false, "description": "The Harbour build recipe failed for the detected runtime." },
     { "id": "build.image-too-large", "retryable": false, "description": "Built image exceeded the size limit." },
+    { "id": "browser.probe-failed", "retryable": true, "description": "The app built and produced its declared outputs, but the browser probe found it does not serve them — typically assets emitted at the root instead of under the app base path. Retryable because it is fed back to the transform agent, which is the component that can fix it; the merged job retries in-loop and the state machine retries the job. Distinct from build.recipe-failed, which means the build itself did not succeed: here it did." },
+    { "id": "browser.probe-unavailable", "retryable": false, "description": "The browser probe could not reach a verdict — Chromium crashed or disconnected, or it wrote no result document. Says nothing about the app, so it is NOT fed back to the agent: retrying would spend agent budget on something the agent cannot influence, and that budget is currently the only cost control in the system (control-plane-infra ADR 0007). Replaces the uncategorized.browser-probe token the merged job emitted while this entry did not exist." },
     { "id": "verify.smoke-failed", "retryable": false, "description": "Candidate smoke/health check failed (boot, routes, storage, secret refs, response shape)." },
     { "id": "verify.characterization-diverged", "retryable": false, "description": "Post-MVP: recorded req/res replay diverged beyond thresholds." },
     { "id": "verify.migration-from-zero-failed", "retryable": false, "description": "Post-MVP: from-zero migration chain failed on scratch DB." },
@@ -42,6 +46,7 @@
     { "id": "admission.app-not-registered", "retryable": false, "description": "Admission rejected: the app directory does not know this app, so there is no sourceRef to fetch a commit from. Fails closed rather than creating the app on demand — a deploy request must not become an app-creation side effect, or app naming stops being a reviewed act. Non-retryable: the directory is authoritative, so retrying cannot make an unknown app known." },
     { "id": "deploy.commit-not-on-branch", "retryable": false, "description": "Admission rejected: the deploy request's commit is not reachable from the app's branch." },
     { "id": "deploy.queue-publication-failed", "retryable": true, "description": "The version was created but its version-qualified SQS message definitively could not be published. The lane is released when this version still owns it; submitting a new deployment is safe." },
+    { "id": "source.branch-moved", "retryable": false, "description": "The app branch head moved while the transformed commit was being published, so the publish would have raced another push. Non-retryable at this version: the deploy request named a commit and the branch now points elsewhere, so a retry would deploy something the requester did not ask for. Submitting a new deployment for the new head is the recovery." },
     { "id": "promotion.preview-not-promotable", "retryable": false, "description": "The referenced preview is missing, belongs to another route, is not LIVE, or lacks immutable artifact and source-tree evidence." },
     { "id": "promotion.production-branch-moved", "retryable": false, "description": "The requested production commit is not the current configured production branch head." },
     { "id": "promotion.source-tree-mismatch", "retryable": false, "description": "The production commit root Git tree identity differs from the referenced preview tree identity." },