@fourier-labs/harbour-contracts 0.3.1 → 0.4.0

package/README.md

@@ -33,7 +33,7 @@ Two schemas carry logic beyond structural types, generated into helpers:
 - **`error-category.enum.json`** → `IsRetryable(category)` (Go) / `isRetryable(category)` (TS),
   handling both concrete categories and family prefixes (`storage.unsupported-engine.<engine>`).
   Unknown categories fail closed (non-retryable).
-- **`version-state.schema.json`** → `CanTransition(from, to)` / `IsTerminal(state)` (Go) and
+- **`version-state.schema.json`** → `CanTransition(environment, from, to)` / `IsTerminal(state)` (Go) and
   `canTransition` / `isTerminal` (TS), driven by the `x-transitions` edge list — so control-plane
   and any consumer agree on legality from one source.
 

package/dist/deployment-status-response.d.ts

@@ -6,8 +6,8 @@ export interface DeploymentStatusResponse {
     versionId: string;
     tenant: string;
     app: string;
-    environment: 'preview';
-    status: 'QUEUED' | 'ANALYZING' | 'TRANSFORMING' | 'VALIDATING' | 'BUILDING' | 'VERIFYING' | 'GATING' | 'LIVE' | 'FAILED' | 'STALE';
+    environment: 'preview' | 'prod';
+    status: 'QUEUED' | 'ANALYZING' | 'TRANSFORMING' | 'VALIDATING' | 'BUILDING' | 'VERIFYING' | 'GATING' | 'LIVE' | 'AWAITING-PROMOTION' | 'PROMOTING' | 'FAILED' | 'STALE';
     message: string;
     branch: string;
     commit: string;

package/dist/error-category-registry.d.ts

@@ -27,6 +27,13 @@ export declare const ErrorCategories: {
     readonly AdmissionAppNotRegistered: "admission.app-not-registered";
     readonly DeployCommitNotOnBranch: "deploy.commit-not-on-branch";
     readonly DeployQueuePublicationFailed: "deploy.queue-publication-failed";
+    readonly PromotionPreviewNotPromotable: "promotion.preview-not-promotable";
+    readonly PromotionProductionBranchMoved: "promotion.production-branch-moved";
+    readonly PromotionSourceTreeMismatch: "promotion.source-tree-mismatch";
+    readonly PromotionArtifactMismatch: "promotion.artifact-mismatch";
+    readonly PromotionIdempotencyConflict: "promotion.idempotency-conflict";
+    readonly PromotionInProgress: "promotion.in-progress";
+    readonly PromotionQueuePublicationFailed: "promotion.queue-publication-failed";
     readonly CutoverFlipFailed: "cutover.flip-failed";
 };
 /** Retryable lookup for a concrete or family-suffixed category. Unknown → false (fail closed). */

package/dist/error-category-registry.js

@@ -29,6 +29,13 @@ export const ErrorCategories = {
     AdmissionAppNotRegistered: "admission.app-not-registered",
     DeployCommitNotOnBranch: "deploy.commit-not-on-branch",
     DeployQueuePublicationFailed: "deploy.queue-publication-failed",
+    PromotionPreviewNotPromotable: "promotion.preview-not-promotable",
+    PromotionProductionBranchMoved: "promotion.production-branch-moved",
+    PromotionSourceTreeMismatch: "promotion.source-tree-mismatch",
+    PromotionArtifactMismatch: "promotion.artifact-mismatch",
+    PromotionIdempotencyConflict: "promotion.idempotency-conflict",
+    PromotionInProgress: "promotion.in-progress",
+    PromotionQueuePublicationFailed: "promotion.queue-publication-failed",
     CutoverFlipFailed: "cutover.flip-failed",
 };
 const retryableExact = {
@@ -60,6 +67,13 @@ const retryableExact = {
     "admission.app-not-registered": false,
     "deploy.commit-not-on-branch": false,
     "deploy.queue-publication-failed": true,
+    "promotion.preview-not-promotable": false,
+    "promotion.production-branch-moved": false,
+    "promotion.source-tree-mismatch": false,
+    "promotion.artifact-mismatch": false,
+    "promotion.idempotency-conflict": false,
+    "promotion.in-progress": true,
+    "promotion.queue-publication-failed": true,
     "cutover.flip-failed": false,
 };
 const retryableFamilies = {

package/dist/index.d.ts

@@ -12,5 +12,7 @@ export * from './error-category-registry.js';
 export * from './error-category.js';
 export * from './error-envelope.js';
 export * from './kvs-routing-entry.js';
+export * from './promotion-request.js';
+export * from './promotion-response.js';
 export * from './version-state-machine.js';
 export * from './version-state.js';

package/dist/index.js

@@ -14,5 +14,7 @@ export * from './error-category-registry.js';
 export * from './error-category.js';
 export * from './error-envelope.js';
 export * from './kvs-routing-entry.js';
+export * from './promotion-request.js';
+export * from './promotion-response.js';
 export * from './version-state-machine.js';
 export * from './version-state.js';

package/dist/promotion-request.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+export interface PromotionRequest {
+    /**
+     * Immutable preview version selected by the caller. The API also verifies that its tenant and app match the route.
+     */
+    previewVersionId: string;
+    /**
+     * Current commit at the configured production branch head. Its root Git tree must equal the preview tree.
+     */
+    commit: string;
+    /**
+     * Durable caller-generated key. Identical replays return the original production version; reuse with a changed request is rejected.
+     */
+    idempotencyKey: string;
+}

package/dist/promotion-request.js

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

package/dist/promotion-response.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 202 Accepted body returned after the production version and its durable idempotency binding exist.
+ */
+export interface PromotionResponse {
+    idempotencyKey: string;
+    /**
+     * Immutable identity of the admitted production version.
+     */
+    versionId: string;
+    previewVersionId: string;
+    tenant: string;
+    app: string;
+    environment: 'prod';
+    status: 'QUEUED';
+    acceptedAt: string;
+    statusUrl: string;
+}

package/dist/promotion-response.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

@@ -13,7 +13,12 @@ export declare const States: {
     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;
+export declare const Environments: {
+    readonly Preview: "preview";
+    readonly Prod: "prod";
+};
+export type EnvironmentName = (typeof Environments)[keyof typeof Environments];
+/** True iff from→to is a legal edge for environment in the T1a state machine. */
+export declare function canTransition(environment: string, 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

@@ -14,22 +14,32 @@ export const States = {
     FAILED: "FAILED",
     STALE: "STALE",
 };
+export const Environments = {
+    Preview: "preview",
+    Prod: "prod",
+};
 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 },
+    "preview": {
+        "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 },
+    },
+    "prod": {
+        "QUEUED": { "PROMOTING": true, "FAILED": 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 from→to is a legal edge for environment in the T1a state machine. */
+export function canTransition(environment, from, to) {
+    return Boolean(legalTransitions[environment]?.[from]?.[to]);
 }
 /** True iff the state is terminal (FAILED, STALE). */
 export function isTerminal(state) { return terminalStates.has(state); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour-contracts",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Single source of truth for every data shape that crosses a boundary between Harbour components.",
   "license": "UNLICENSED",
   "private": false,

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",

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/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" }
   ]
 }