@fourier-labs/harbour-contracts 0.3.1 → 0.5.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/deploy-response.schema.json

@@ -15,7 +15,7 @@
     },
     "versionId": {
       "type": "string",
-      "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?#[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?#preview#[0-9]{6}$",
+      "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?#[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?#preview#[0-9]{6,}$",
       "description": "Immutable identity of the admitted preview version."
     },
     "tenant": {

package/schema/deployment-status-request.schema.json

@@ -19,7 +19,7 @@
     },
     "versionId": {
       "type": "string",
-      "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?#[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?#preview#[0-9]{6}$"
+      "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?#[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?#(?:preview|prod)#[0-9]{6,}$"
     }
   }
 }

package/schema/deployment-status-response.schema.json

@@ -21,11 +21,11 @@
     },
     "environment": {
       "type": "string",
-      "enum": ["preview"]
+      "enum": ["preview", "prod"]
     },
     "status": {
       "type": "string",
-      "enum": ["QUEUED", "ANALYZING", "TRANSFORMING", "VALIDATING", "BUILDING", "VERIFYING", "GATING", "LIVE", "FAILED", "STALE"]
+      "enum": ["QUEUED", "ANALYZING", "TRANSFORMING", "VALIDATING", "BUILDING", "VERIFYING", "GATING", "LIVE", "AWAITING-PROMOTION", "PROMOTING", "FAILED", "STALE"]
     },
     "message": {
       "type": "string",