@fourier-labs/harbour-contracts 0.3.1 → 0.5.0

package/schema/error-category.enum.json

@@ -42,6 +42,13 @@
     { "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": "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." },
+    { "id": "promotion.artifact-mismatch", "retryable": false, "description": "The stored preview artifact is missing, mutable, or resolves to a different backend digest." },
+    { "id": "promotion.idempotency-conflict", "retryable": false, "description": "An idempotency key was reused with a different preview version or production commit." },
+    { "id": "promotion.in-progress", "retryable": true, "description": "A different production promotion currently owns the application's production lane." },
+    { "id": "promotion.queue-publication-failed", "retryable": true, "description": "The production version was durably accepted but its version-qualified queue event could not be published." },
     { "id": "cutover.flip-failed", "retryable": false, "description": "The atomic alias flip failed at cutover; previous version keeps serving." },
     { "id": "quota.exceeded", "retryable": false, "family": true, "description": "A provisioning/account limit was hit (cluster/IAM-role quota) — NOT runtime traffic quotas. Concrete token names which limit." },
     { "id": "uncategorized", "retryable": false, "family": true, "description": "A failure that fit no category — this is a bug: file uncategorized.<stage> AND a spec PR to this file." }

package/schema/promotion-request.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/promotion-request.schema.json",
+  "title": "PromotionRequest",
+  "description": "JSON body for POST /v1/tenants/{tenant}/apps/{app}/promotions. Repository identity is loaded from stored application and preview records, not supplied by the caller.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["previewVersionId", "commit", "idempotencyKey"],
+  "properties": {
+    "previewVersionId": {
+      "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 preview version selected by the caller. The API also verifies that its tenant and app match the route."
+    },
+    "commit": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{40}$",
+      "description": "Current commit at the configured production branch head. Its root Git tree must equal the preview tree."
+    },
+    "idempotencyKey": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$",
+      "description": "Durable caller-generated key. Identical replays return the original production version; reuse with a changed request is rejected."
+    }
+  }
+}

package/schema/promotion-response.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/promotion-response.schema.json",
+  "title": "PromotionResponse",
+  "description": "202 Accepted body returned after the production version and its durable idempotency binding exist.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["idempotencyKey", "versionId", "previewVersionId", "tenant", "app", "environment", "status", "acceptedAt", "statusUrl"],
+  "properties": {
+    "idempotencyKey": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$"
+    },
+    "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])?#prod#[0-9]{6,}$",
+      "description": "Immutable identity of the admitted production version."
+    },
+    "previewVersionId": {
+      "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,}$"
+    },
+    "tenant": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 63
+    },
+    "app": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 63
+    },
+    "environment": {
+      "type": "string",
+      "enum": ["prod"]
+    },
+    "status": {
+      "type": "string",
+      "enum": ["QUEUED"]
+    },
+    "acceptedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "statusUrl": {
+      "type": "string",
+      "pattern": "^/v1/tenants/[^/]+/apps/[^/]+/deployments/[^/]+$"
+    }
+  }
+}

package/schema/secret-reference.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/secret-reference.schema.json",
+  "title": "SecretReference",
+  "description": "Secret-Manager MVP: a named secret slot an app depends on. Only the reference and its lifecycle cross this boundary — the secret VALUE never appears in any contract. scope=app secrets are shared by the app; scope=personal secrets belong to one builder (ownerBuilderId). origin records whether a builder created the slot or the platform minted it (e.g. for a data grant).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["appId", "name", "scope", "secretRef", "status", "origin"],
+  "properties": {
+    "appId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "App the secret slot belongs to."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "Slot name as the app references it (typically the environment-variable name)."
+    },
+    "scope": {
+      "$ref": "#/definitions/SecretReferenceScope"
+    },
+    "ownerBuilderId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "Owning builder; present only when scope is personal."
+    },
+    "secretRef": {
+      "type": "string",
+      "pattern": "^secretref://[A-Za-z0-9][A-Za-z0-9/_.:-]*$",
+      "description": "secretref URI of the stored value. The value itself never crosses this boundary."
+    },
+    "status": {
+      "$ref": "#/definitions/SecretReferenceStatus"
+    },
+    "origin": {
+      "$ref": "#/definitions/SecretReferenceOrigin"
+    }
+  },
+  "definitions": {
+    "SecretReferenceScope": {
+      "type": "string",
+      "enum": ["app", "personal"],
+      "description": "app = shared by the whole app; personal = owned by a single builder (ownerBuilderId)."
+    },
+    "SecretReferenceStatus": {
+      "type": "string",
+      "enum": ["SET", "UNSET"],
+      "description": "UNSET slots block promotion until a human sets a value (secrets.unresolvable)."
+    },
+    "SecretReferenceOrigin": {
+      "type": "string",
+      "enum": ["builder", "minted"],
+      "description": "builder = created by a builder; minted = created by the platform (e.g. a data-grant credential)."
+    }
+  },
+  "examples": [
+    {
+      "appId": "reports",
+      "name": "STRIPE_API_KEY",
+      "scope": "app",
+      "secretRef": "secretref://tenants/fourier/apps/reports/STRIPE_API_KEY",
+      "status": "SET",
+      "origin": "builder"
+    }
+  ]
+}

package/schema/version-state.schema.json

@@ -35,32 +35,33 @@
   "x-terminal": ["FAILED", "STALE"],
   "x-terminalStable": ["LIVE", "AWAITING-PROMOTION"],
   "x-transitions": [
-    { "from": "QUEUED", "to": "ANALYZING", "trigger": "admission: slot free AND commit reachable from branch" },
+    { "from": "QUEUED", "to": "ANALYZING", "environments": ["preview"], "trigger": "admission: slot free AND commit reachable from branch" },
+    { "from": "QUEUED", "to": "PROMOTING", "environments": ["prod"], "trigger": "production promotion admission: stored preview and source-fidelity guards pass" },
     { "from": "QUEUED", "to": "FAILED", "trigger": "admission validation fails — commit not reachable from branch" },
-    { "from": "ANALYZING", "to": "BUILDING", "trigger": "nothing to transform (fast path)" },
-    { "from": "ANALYZING", "to": "TRANSFORMING", "trigger": "transform-relevant findings; 15-min wall deadline stamped" },
-    { "from": "ANALYZING", "to": "FAILED", "trigger": "hard intake failure" },
-    { "from": "TRANSFORMING", "to": "VALIDATING", "trigger": "agent produced candidate" },
-    { "from": "TRANSFORMING", "to": "FAILED", "trigger": "non-retryable failure or deadline exceeded" },
-    { "from": "VALIDATING", "to": "BUILDING", "trigger": "validation passed" },
-    { "from": "VALIDATING", "to": "TRANSFORMING", "trigger": "retryable failure AND now < deadline" },
-    { "from": "VALIDATING", "to": "FAILED", "trigger": "non-retryable failure or deadline exceeded" },
-    { "from": "BUILDING", "to": "VERIFYING", "trigger": "artifact produced + artifact secret scan clean" },
-    { "from": "BUILDING", "to": "FAILED", "trigger": "build recipe failed or secret scan hit" },
-    { "from": "VERIFYING", "to": "GATING", "trigger": "all candidate checks pass" },
-    { "from": "VERIFYING", "to": "FAILED", "trigger": "a verification check fails (e.g. auth.app-publicly-invocable)" },
-    { "from": "GATING", "to": "LIVE", "trigger": "all gates pass -> atomic alias flip" },
-    { "from": "GATING", "to": "FAILED", "trigger": "a blocking gate fails" },
-    { "from": "LIVE", "to": "AWAITING-PROMOTION", "trigger": "preview only — maker confirms; platform raises PR" },
-    { "from": "AWAITING-PROMOTION", "to": "PROMOTING", "trigger": "human merges PR (no agent-callable path)" },
+    { "from": "ANALYZING", "to": "BUILDING", "environments": ["preview"], "trigger": "nothing to transform (fast path)" },
+    { "from": "ANALYZING", "to": "TRANSFORMING", "environments": ["preview"], "trigger": "transform-relevant findings; 15-min wall deadline stamped" },
+    { "from": "ANALYZING", "to": "FAILED", "environments": ["preview"], "trigger": "hard intake failure" },
+    { "from": "TRANSFORMING", "to": "VALIDATING", "environments": ["preview"], "trigger": "agent produced candidate" },
+    { "from": "TRANSFORMING", "to": "FAILED", "environments": ["preview"], "trigger": "non-retryable failure or deadline exceeded" },
+    { "from": "VALIDATING", "to": "BUILDING", "environments": ["preview"], "trigger": "validation passed" },
+    { "from": "VALIDATING", "to": "TRANSFORMING", "environments": ["preview"], "trigger": "retryable failure AND now < deadline" },
+    { "from": "VALIDATING", "to": "FAILED", "environments": ["preview"], "trigger": "non-retryable failure or deadline exceeded" },
+    { "from": "BUILDING", "to": "VERIFYING", "environments": ["preview"], "trigger": "artifact produced + artifact secret scan clean" },
+    { "from": "BUILDING", "to": "FAILED", "environments": ["preview"], "trigger": "build recipe failed or secret scan hit" },
+    { "from": "VERIFYING", "to": "GATING", "environments": ["preview"], "trigger": "all candidate checks pass" },
+    { "from": "VERIFYING", "to": "FAILED", "environments": ["preview"], "trigger": "a verification check fails (e.g. auth.app-publicly-invocable)" },
+    { "from": "GATING", "to": "LIVE", "environments": ["preview"], "trigger": "all gates pass -> atomic alias flip" },
+    { "from": "GATING", "to": "FAILED", "environments": ["preview"], "trigger": "a blocking gate fails" },
+    { "from": "LIVE", "to": "AWAITING-PROMOTION", "environments": ["preview"], "trigger": "preview only — maker confirms; platform raises PR" },
+    { "from": "AWAITING-PROMOTION", "to": "PROMOTING", "environments": ["preview"], "trigger": "human merges PR (no agent-callable path)" },
     { "from": "PROMOTING", "to": "LIVE", "trigger": "prod candidate verified -> flip" },
     { "from": "PROMOTING", "to": "FAILED", "trigger": "candidate verify/migration fails; prod alias never moved" },
-    { "from": "QUEUED", "to": "STALE", "trigger": "newer deploy request passes its guard" },
-    { "from": "ANALYZING", "to": "STALE", "trigger": "newer deploy request passes its guard" },
-    { "from": "TRANSFORMING", "to": "STALE", "trigger": "newer deploy request; survives unless new commit touches transform-relevant files" },
-    { "from": "VALIDATING", "to": "STALE", "trigger": "newer deploy request passes its guard" },
-    { "from": "BUILDING", "to": "STALE", "trigger": "newer deploy request; let finish, skip flip" },
-    { "from": "VERIFYING", "to": "STALE", "trigger": "newer deploy request; let finish, skip flip" },
-    { "from": "GATING", "to": "STALE", "trigger": "newer deploy request passes its guard" }
+    { "from": "QUEUED", "to": "STALE", "environments": ["preview"], "trigger": "newer deploy request passes its guard" },
+    { "from": "ANALYZING", "to": "STALE", "environments": ["preview"], "trigger": "newer deploy request passes its guard" },
+    { "from": "TRANSFORMING", "to": "STALE", "environments": ["preview"], "trigger": "newer deploy request; survives unless new commit touches transform-relevant files" },
+    { "from": "VALIDATING", "to": "STALE", "environments": ["preview"], "trigger": "newer deploy request passes its guard" },
+    { "from": "BUILDING", "to": "STALE", "environments": ["preview"], "trigger": "newer deploy request; let finish, skip flip" },
+    { "from": "VERIFYING", "to": "STALE", "environments": ["preview"], "trigger": "newer deploy request; let finish, skip flip" },
+    { "from": "GATING", "to": "STALE", "environments": ["preview"], "trigger": "newer deploy request passes its guard" }
   ]
 }

package/dist/version-state-machine.js

@@ -1,35 +0,0 @@
-/* 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); }