@fourier-labs/harbour-contracts 0.3.1

package/dist/kvs-routing-entry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Value stored in the CloudFront KeyValueStore, keyed by host header `<app>.(beta.)harbour.dev` and read by the CloudFront Function on every request (LLD §8). MVP carries exactly {static, api} and nothing else — quota/kill-switch fields are a deliberate, additive future extension consumed by the same function.
+ */
+export interface KvsRoutingEntry {
+    /**
+     * S3 origin path for static assets of the LIVE version, e.g. `builds/<app>/<digest>/` (from the artifact `static.path`, LLD §3).
+     */
+    static: string;
+    /**
+     * Backend target for `/api/*` routes — the Lambda alias reached via API Gateway / Function URL for the LIVE version.
+     */
+    api: string;
+}

package/dist/kvs-routing-entry.js

@@ -0,0 +1,3 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+export {};

package/dist/version-state-machine.d.ts

@@ -0,0 +1,19 @@
+export declare const States: {
+    readonly QUEUED: "QUEUED";
+    readonly ANALYZING: "ANALYZING";
+    readonly TRANSFORMING: "TRANSFORMING";
+    readonly VALIDATING: "VALIDATING";
+    readonly BUILDING: "BUILDING";
+    readonly VERIFYING: "VERIFYING";
+    readonly GATING: "GATING";
+    readonly LIVE: "LIVE";
+    readonly AWAITINGPROMOTION: "AWAITING-PROMOTION";
+    readonly PROMOTING: "PROMOTING";
+    readonly FAILED: "FAILED";
+    readonly STALE: "STALE";
+};
+export type StateName = (typeof States)[keyof typeof States];
+/** True iff from→to is a legal edge in the T1a state machine. */
+export declare function canTransition(from: string, to: string): boolean;
+/** True iff the state is terminal (FAILED, STALE). */
+export declare function isTerminal(state: string): boolean;

package/dist/version-state-machine.js

@@ -0,0 +1,35 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+export const States = {
+    QUEUED: "QUEUED",
+    ANALYZING: "ANALYZING",
+    TRANSFORMING: "TRANSFORMING",
+    VALIDATING: "VALIDATING",
+    BUILDING: "BUILDING",
+    VERIFYING: "VERIFYING",
+    GATING: "GATING",
+    LIVE: "LIVE",
+    AWAITINGPROMOTION: "AWAITING-PROMOTION",
+    PROMOTING: "PROMOTING",
+    FAILED: "FAILED",
+    STALE: "STALE",
+};
+const legalTransitions = {
+    "QUEUED": { "ANALYZING": true, "FAILED": true, "STALE": true },
+    "ANALYZING": { "BUILDING": true, "TRANSFORMING": true, "FAILED": true, "STALE": true },
+    "TRANSFORMING": { "VALIDATING": true, "FAILED": true, "STALE": true },
+    "VALIDATING": { "BUILDING": true, "TRANSFORMING": true, "FAILED": true, "STALE": true },
+    "BUILDING": { "VERIFYING": true, "FAILED": true, "STALE": true },
+    "VERIFYING": { "GATING": true, "FAILED": true, "STALE": true },
+    "GATING": { "LIVE": true, "FAILED": true, "STALE": true },
+    "LIVE": { "AWAITING-PROMOTION": true },
+    "AWAITING-PROMOTION": { "PROMOTING": true },
+    "PROMOTING": { "LIVE": true, "FAILED": true },
+};
+const terminalStates = new Set(["FAILED", "STALE"]);
+/** True iff from→to is a legal edge in the T1a state machine. */
+export function canTransition(from, to) {
+    return Boolean(legalTransitions[from] && legalTransitions[from][to]);
+}
+/** True iff the state is terminal (FAILED, STALE). */
+export function isTerminal(state) { return terminalStates.has(state); }

package/dist/version-state.d.ts

@@ -0,0 +1,4 @@
+/**
+ * The app-version state machine T1a (LLD §1). Root type is the state token itself. `FAILED` carries a separate error category (see error-category.enum.json); the state token is the bare word `FAILED`. Legal edges live in x-transitions; codegen turns them into a shared transition-validation table so control-plane and any consumer agree on legality.
+ */
+export type VersionState = 'QUEUED' | 'ANALYZING' | 'TRANSFORMING' | 'VALIDATING' | 'BUILDING' | 'VERIFYING' | 'GATING' | 'LIVE' | 'AWAITING-PROMOTION' | 'PROMOTING' | 'FAILED' | 'STALE';

package/dist/version-state.js

@@ -0,0 +1,3 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+export {};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@fourier-labs/harbour-contracts",
+  "version": "0.3.1",
+  "description": "Single source of truth for every data shape that crosses a boundary between Harbour components.",
+  "license": "UNLICENSED",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Fourier-Labs-AI/harbour-contracts.git"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "schema"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "gen": "node tools/gen/gen.mjs",
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test tools/gen/*.test.mjs",
+    "verify": "node tools/gen/gen.mjs && { [ -z \"$(git status --porcelain -- gen-ts gen-go)\" ] || { echo 'STALE: generated code out of date or uncommitted — run make gen and commit'; exit 1; }; }"
+  },
+  "devDependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "json-schema-to-typescript": "^15.0.4",
+    "typescript": "^5.7.2"
+  }
+}

package/schema/api-error-response.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/api-error-response.schema.json",
+  "title": "ApiErrorResponse",
+  "description": "Safe JSON error body returned by the Deploy and Status Lambdas for API-level 4xx and 5xx responses. It is distinct from the internal pipeline ErrorEnvelope, which requires a version and evidence reference.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["code", "message", "correlationId"],
+  "properties": {
+    "code": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(\\.[a-z0-9-]+)+$"
+    },
+    "message": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500
+    },
+    "correlationId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "requestId": {
+      "type": "string",
+      "maxLength": 128
+    },
+    "versionId": {
+      "type": "string",
+      "description": "Present when a version was minted before the API-level failure."
+    }
+  }
+}

package/schema/artifact-contract.schema.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/artifact-contract.schema.json",
+  "title": "ArtifactContract",
+  "description": "The build output contract (LLD §3) — the provider-portability seam. Emitted by the build (`artifact.json`) and consumed by every deploy stage below build. Deploy stages read ONLY this document plus the blobs it references. Secret REFERENCES only — never values.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contract_version",
+    "app_id",
+    "commit",
+    "artifact_digest",
+    "backend",
+    "static",
+    "routes",
+    "env",
+    "storage_bindings",
+    "migrations",
+    "scheduled_tasks",
+    "transform_report"
+  ],
+  "properties": {
+    "contract_version": { "type": "integer", "const": 1 },
+    "app_id": { "type": "string", "minLength": 1 },
+    "commit": { "type": "string", "pattern": "^[0-9a-f]{7,40}$" },
+    "artifact_digest": {
+      "type": "string",
+      "pattern": "^(sha256:)?[0-9a-f]{64}$",
+      "description": "sha256 of the canonical bundle; the immutable identity that promotion pins to (invariant §1.3.2)."
+    },
+    "backend": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "ref", "entrypoint", "runtime"],
+      "properties": {
+        "type": { "type": "string", "enum": ["oci-image", "zip"] },
+        "ref": { "type": "string", "minLength": 1, "description": "ECR uri@digest (oci-image) or S3 key (zip)." },
+        "entrypoint": { "type": "string", "minLength": 1 },
+        "runtime": { "type": "string", "minLength": 1 }
+      }
+    },
+    "static": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "env_agnostic"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1, "description": "e.g. builds/<digest>/" },
+        "env_agnostic": { "type": "boolean", "description": "true when static assets carry no env-specific values (no static rebuild needed on promotion)." }
+      }
+    },
+    "routes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "target"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "target": { "type": "string", "enum": ["backend", "static"] }
+        }
+      }
+    },
+    "env": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["vars", "secret_refs"],
+      "properties": {
+        "vars": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Non-secret env vars, e.g. {\"PORT\":\"8080\"}."
+        },
+        "secret_refs": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^harbour/" },
+          "description": "Secrets Manager references only, e.g. harbour/<org>/<app>/<env>/STRIPE_KEY. Never values."
+        }
+      }
+    },
+    "storage_bindings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["kind", "provider"],
+        "properties": {
+          "kind": { "type": "string", "enum": ["sql", "kv", "files"] },
+          "logical": { "type": "string", "description": "Logical name, e.g. \"default\"." },
+          "provider": { "type": "string", "description": "e.g. aurora-sv2." }
+        }
+      }
+    },
+    "migrations": {
+      "type": "array",
+      "description": "Post-MVP (migration tooling is post-MVP, LLD §4.6); MVP emits an empty array.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["seq", "sha", "destructive", "path"],
+        "properties": {
+          "seq": { "type": "integer", "minimum": 0 },
+          "sha": { "type": "string" },
+          "destructive": { "type": "boolean" },
+          "path": { "type": "string" }
+        }
+      }
+    },
+    "scheduled_tasks": {
+      "type": "array",
+      "description": "MVP emits an empty array.",
+      "items": { "type": "object" }
+    },
+    "transform_report": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["surfaces", "static_rebuild_required"],
+      "properties": {
+        "surfaces": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Transformed surfaces, e.g. [\"secrets\",\"storage.sql\"]."
+        },
+        "static_rebuild_required": { "type": "boolean" }
+      }
+    }
+  }
+}

package/schema/deploy-request.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/deploy-request.schema.json",
+  "title": "DeployRequest",
+  "description": "JSON body for POST /v1/tenants/{tenant}/apps/{app}/deployments. tenant and app come from path parameters and are not body fields. The preview MVP requires environment=preview. Every accepted POST is a new deployment intent; idempotencyKey is retained only as request correlation.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["source", "environment", "branch", "commit"],
+  "properties": {
+    "source": {
+      "$ref": "#/definitions/DeployRequestSource"
+    },
+    "environment": {
+      "type": "string",
+      "enum": ["preview"],
+      "description": "Deployment target. The API rejects production; production remains human-merge gated."
+    },
+    "branch": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "Git branch that must contain the exact requested commit."
+    },
+    "commit": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{7,40}$",
+      "description": "Exact lowercase hexadecimal Git commit to materialize and deploy."
+    },
+    "idempotencyKey": {
+      "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."
+    }
+  },
+  "definitions": {
+    "DeployRequestSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "repositoryUrl"],
+      "properties": {
+        "provider": {
+          "type": "string",
+          "enum": ["github"],
+          "description": "Source provider. The preview MVP accepts only github."
+        },
+        "repositoryUrl": {
+          "type": "string",
+          "minLength": 20,
+          "maxLength": 300,
+          "pattern": "^https://github\\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+(?:\\.git)?/?$",
+          "description": "Credential-free HTTPS GitHub repository URL."
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "source": {
+        "provider": "github",
+        "repositoryUrl": "https://github.com/Fourier-Labs-AI/focus-list"
+      },
+      "environment": "preview",
+      "branch": "preview-deployment",
+      "commit": "abc1234567890abcdef1234567890abcdef12345",
+      "idempotencyKey": "deploy-attempt-123"
+    }
+  ]
+}

package/schema/deploy-response.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/deploy-response.schema.json",
+  "title": "DeployResponse",
+  "description": "202 Accepted body returned by POST /v1/tenants/{tenant}/apps/{app}/deployments only after the authoritative QUEUED version exists and its version-qualified SQS message is accepted.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["requestId", "versionId", "tenant", "app", "environment", "status", "acceptedAt", "statusUrl"],
+  "properties": {
+    "requestId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Caller correlation value. This is not the deployment identity."
+    },
+    "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}$",
+      "description": "Immutable identity of the admitted preview version."
+    },
+    "tenant": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 63
+    },
+    "app": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 63
+    },
+    "environment": {
+      "type": "string",
+      "enum": ["preview"]
+    },
+    "status": {
+      "type": "string",
+      "enum": ["QUEUED"]
+    },
+    "acceptedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "statusUrl": {
+      "type": "string",
+      "pattern": "^/v1/tenants/[^/]+/apps/[^/]+/deployments/[^/]+$",
+      "description": "Relative URL for exact-version Status. The versionId path segment is URL encoded."
+    }
+  }
+}

package/schema/deployment-environment.schema.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/deployment-environment.schema.json",
+  "title": "DeploymentEnvironment",
+  "description": "Public environment accepted by the preview deployment-control-plane APIs. The MVP accepts only preview; production remains reachable only through Harbour's human-merge promotion flow.",
+  "type": "string",
+  "enum": ["preview"],
+  "examples": ["preview"]
+}

package/schema/deployment-source.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/deployment-source.schema.json",
+  "title": "DeploymentSource",
+  "description": "Credential-free GitHub source supplied in the DeployRequest body. Credentials are resolved internally by MaterializeSource and never cross the API boundary.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["provider", "repositoryUrl"],
+  "properties": {
+    "provider": {
+      "type": "string",
+      "enum": ["github"],
+      "description": "Source provider. The preview MVP accepts only GitHub."
+    },
+    "repositoryUrl": {
+      "type": "string",
+      "minLength": 20,
+      "maxLength": 300,
+      "pattern": "^https://github\\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+(?:\\.git)?/?$",
+      "description": "Credential-free HTTPS GitHub repository URL. Query strings, fragments, embedded credentials and non-github.com hosts are rejected."
+    }
+  },
+  "examples": [
+    {
+      "provider": "github",
+      "repositoryUrl": "https://github.com/Fourier-Labs-AI/focus-list"
+    }
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/deployment-status-failure.schema.json",
+  "title": "DeploymentStatusFailure",
+  "description": "Frontend-safe failure projection nested in a failed DeploymentStatusResponse. Internal evidence references, AWS identifiers and raw provider errors are excluded.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["category", "retryable", "message", "remediationHint"],
+  "properties": {
+    "category": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(\\.[a-z0-9-]+)+$"
+    },
+    "retryable": {
+      "type": "boolean"
+    },
+    "message": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500
+    },
+    "remediationHint": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1000
+    }
+  }
+}

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

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/deployment-status-request.schema.json",
+  "title": "DeploymentStatusRequest",
+  "description": "Validated path parameters for GET /v1/tenants/{tenant}/apps/{app}/deployments/{versionId}. The Status Lambda constructs this object from API Gateway path parameters; it is not a GET request body.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["tenant", "app", "versionId"],
+  "properties": {
+    "tenant": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 63
+    },
+    "app": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 63
+    },
+    "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}$"
+    }
+  }
+}

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

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/deployment-status-response.schema.json",
+  "title": "DeploymentStatusResponse",
+  "description": "200 OK body returned by GET /v1/tenants/{tenant}/apps/{app}/deployments/{versionId}. It describes that exact immutable version; newer deployments cannot change which record this response represents.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["requestId", "versionId", "tenant", "app", "environment", "status", "message", "branch", "commit", "requestedAt", "updatedAt"],
+  "properties": {
+    "requestId": {
+      "type": "string"
+    },
+    "versionId": {
+      "type": "string"
+    },
+    "tenant": {
+      "type": "string"
+    },
+    "app": {
+      "type": "string"
+    },
+    "environment": {
+      "type": "string",
+      "enum": ["preview"]
+    },
+    "status": {
+      "type": "string",
+      "enum": ["QUEUED", "ANALYZING", "TRANSFORMING", "VALIDATING", "BUILDING", "VERIFYING", "GATING", "LIVE", "FAILED", "STALE"]
+    },
+    "message": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500
+    },
+    "branch": {
+      "type": "string"
+    },
+    "commit": {
+      "type": "string"
+    },
+    "requestedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "url": {
+      "type": "string",
+      "format": "uri"
+    },
+    "failure": {
+      "$ref": "#/definitions/StatusFailureProjection"
+    }
+  },
+  "definitions": {
+    "StatusFailureProjection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["category", "retryable", "message", "remediationHint"],
+      "properties": {
+        "category": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(\\.[a-z0-9-]+)+$"
+        },
+        "retryable": {
+          "type": "boolean"
+        },
+        "message": {
+          "type": "string"
+        },
+        "remediationHint": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/schema/env-bindings.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/env-bindings.schema.json",
+  "title": "EnvBindings",
+  "description": "Resolved environment bindings (LLD §4.2.2). Deliberately COMPLETE — including BYOC/multi-cloud fields MVP does not use (roleArn/externalId absent = act in own account). Resolved once at admission by EnvResolver, stamped onto the version record; every downstream stage reads it from the record and never re-resolves. Adding a field bumps bindingsVersion and touches every consumer — that is the point. `executionCell` is where source-touching stages run (MVP: provider 'harbour').",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["env", "executor", "sql", "kv", "files", "secrets", "serving", "executionCell", "gates", "bindingsVersion"],
+  "properties": {
+    "env": { "type": "string", "description": "e.g. preview | prod." },
+    "executor": { "$ref": "#/definitions/Binding" },
+    "sql": { "$ref": "#/definitions/Binding" },
+    "kv": { "$ref": "#/definitions/Binding" },
+    "files": { "$ref": "#/definitions/Binding" },
+    "secrets": { "$ref": "#/definitions/Binding" },
+    "serving": { "$ref": "#/definitions/Binding" },
+    "executionCell": { "$ref": "#/definitions/Binding" },
+    "gates": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Ordered gate names evaluated at GATING."
+    },
+    "constraints": {
+      "type": "object",
+      "description": "MVP: absent. Future: per-target constraints (region pins, size caps, …).",
+      "additionalProperties": true
+    },
+    "bindingsVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Stamped onto the version record for audit; bumps when the binding shape changes."
+    }
+  },
+  "definitions": {
+    "Target": {
+      "type": "object",
+      "required": ["account", "region"],
+      "properties": {
+        "account": { "type": "string", "description": "MVP: own account id." },
+        "region": { "type": "string", "description": "MVP: us-east-1." },
+        "roleArn": { "type": "string", "description": "BYOC cross-account role; absent in MVP = act locally." },
+        "externalId": { "type": "string", "description": "BYOC assume-role external id; absent in MVP." }
+      },
+      "additionalProperties": false
+    },
+    "Binding": {
+      "type": "object",
+      "required": ["provider", "target"],
+      "additionalProperties": false,
+      "properties": {
+        "provider": { "type": "string" },
+        "target": { "$ref": "#/definitions/Target" },
+        "config": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Provider-specific values, resolved at admission and stamped on the version record. MVP (StaticEnvResolver, from CDK stack outputs) e.g. sql: {clusterArn, proxyEndpoint, databaseName}; serving: {distributionId, bucket}. Kept as a named open map rather than loose top-level keys so BOTH generated languages preserve it faithfully — a Go struct silently drops unrecognized top-level keys, a map does not."
+        }
+      },
+      "description": "provider + target + provider-specific `config` (LLD §4.2.2). The binding object itself is closed: a new first-class field is a deliberate schema change plus a bindingsVersion bump, never an ad-hoc key."
+    }
+  }
+}