@fourier-labs/harbour-contracts 0.4.0 → 0.6.0

package/schema/kvs-routing-entry.schema.json

@@ -2,20 +2,40 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://schemas.harbour.dev/kvs-routing-entry.schema.json",
   "title": "KvsRoutingEntry",
-  "description": "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.",
+  "description": "Value stored in the CloudFront KeyValueStore and read by the viewer-request router on EVERY request. Keyed by `<org>.<app>` — the tenant-qualified app identity, not a host header; slugs are lowercase DNS-label-shaped and cannot contain dots, so the single dot is an unambiguous separator. Two constraints cannot be expressed in JSON Schema and are enforced in the router: the TOTAL length of all `staticAssetPrefixes` must not exceed 512 bytes, and the array must be empty when `routeMode` is `static`. Written by cutover; a request whose entry fails any of these rules is refused at the edge rather than routed on a guess.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["static", "api"],
+  "required": ["staticPath", "routeMode", "ordinal"],
   "properties": {
-    "static": {
+    "staticPath": {
       "type": "string",
-      "minLength": 1,
-      "description": "S3 origin path for static assets of the LIVE version, e.g. `builds/<app>/<digest>/` (from the artifact `static.path`, LLD §3)."
+      "pattern": "^builds/[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?/[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?/[0-9a-f]{64}$",
+      "description": "Immutable prefix of the LIVE version's static output: `builds/<org>/<app>/<64-hex-digest>`, with no trailing slash. The digest is what makes a cutover safe — the router rewrites matching requests to this prefix before the cache lookup, so it is also the edge cache key, and a new version therefore cannot serve the previous version's cached bytes."
     },
-    "api": {
+    "routeMode": {
       "type": "string",
-      "minLength": 1,
-      "description": "Backend target for `/api/*` routes — the Lambda alias reached via API Gateway / Function URL for the LIVE version."
+      "enum": ["server", "static"],
+      "description": "Whether the app has an application runtime. REQUIRED: an entry without it is refused with 503 rather than guessed at. In `server` mode a path under a declared `staticAssetPrefixes` entry is served from S3 and everything else goes to `apiDomain`; in `static` mode every path is served from S3."
+    },
+    "ordinal": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "The version's monotonic sequence number within its lane. Cutover uses it to keep writes one-way: an entry is only replaced by a strictly higher ordinal, so a delayed or replayed write cannot move an app backwards."
+    },
+    "apiDomain": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+\\.lambda-url\\.[a-z0-9-]+\\.on\\.aws$",
+      "description": "The app runtime's AWS_IAM-protected Lambda Function URL host. Required in `server` mode and omitted entirely for a static-only app. The router refuses any other domain shape, so this cannot be pointed at an arbitrary origin."
+    },
+    "staticAssetPrefixes": {
+      "type": "array",
+      "maxItems": 16,
+      "uniqueItems": true,
+      "description": "Build-derived prefixes that a `server` app serves from its immutable S3 output rather than from its runtime, e.g. `_next/static/`. Derived from verified build output, never from framework names. Must be strictly ascending, must total at most 512 bytes, and must be absent or empty in `static` mode — the last two are enforced in the router because JSON Schema cannot express them. Omitted when empty: a server app with public build output and no prefixes serves every asset from its Lambda, which is a build-plan defect rather than a routing one.",
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9_-]+(?:/[A-Za-z0-9_-]+)*/$"
+      }
     }
   }
 }

package/schema/promotion-request.schema.json

@@ -21,6 +21,44 @@
       "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."
+    },
+    "environmentBindings": {
+      "$ref": "#/definitions/PromotionRequestEnvironmentBindings"
+    }
+  },
+  "definitions": {
+    "PromotionRequestEnvironmentBindings": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["bindings"],
+      "properties": {
+        "bindings": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PromotionRequestSecretBinding"
+          },
+          "description": "Secret bindings for the production version. An empty array is meaningful: it says the caller looked and the app declares no secrets."
+        }
+      },
+      "description": "Optional secret bindings for the production version. Additive: promotions without it remain valid, and a deployment plane that ignores the field behaves exactly as before. Named environmentBindings to match deploy-request.schema.json, whose preview counterpart this mirrors."
+    },
+    "PromotionRequestSecretBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "secretRef"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[A-Z][A-Z0-9_]{0,127}$",
+          "description": "Environment-variable name the app reads."
+        },
+        "secretRef": {
+          "type": "string",
+          "pattern": "^secretref://tenant/[A-Za-z0-9._-]+/app/[A-Za-z0-9._-]+/secret/[A-Z][A-Z0-9_]{0,127}$",
+          "description": "Governance reference the deployment plane resolves. The value never appears in the request, in this schema, or in any record derived from it."
+        }
+      },
+      "description": "One secret binding. Unlike the preview counterpart there is no `value` member and `secretRef` is required, so a plain literal is unrepresentable on the promotion path rather than merely refused by the handler. The secretRef pattern admits only the app-secret shape, which is what keeps a promotion from naming a tenant integration credential."
     }
   }
 }

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/transform-report.schema.json

@@ -0,0 +1,204 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/transform-report.schema.json",
+  "title": "TransformReport",
+  "description": "Structured output an agent must return from one Harbour transformation attempt. Handed to the agent as its output schema, then decoded and semantically re-validated by the control plane, which remains the authority. The enum on applied_playbooks.items is the one dynamic part: the adapter injects the names of the playbooks supplied for that invocation before writing the document, so the model is structurally prevented from naming a playbook it was not given. Application-secret handling was removed platform-wide, so this document carries no redactions and no secrets fields.",
+  "x-go-embed": true,
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "applied_playbooks",
+    "static_rebuild_required",
+    "analysis",
+    "database",
+    "application"
+  ],
+  "properties": {
+    "applied_playbooks": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "static_rebuild_required": { "type": "boolean" },
+    "analysis": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["deployable", "needsTransformation", "blockers", "surfaces", "evidence"],
+      "properties": {
+        "deployable": { "type": "boolean" },
+        "needsTransformation": { "type": "boolean" },
+        "blockers": {
+          "type": "array",
+          "maxItems": 64,
+          "items": { "type": "string", "minLength": 1, "maxLength": 1024 }
+        },
+        "surfaces": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1024,
+          "items": { "type": "string", "minLength": 1, "maxLength": 512 }
+        },
+        "evidence": {
+          "type": "array",
+          "maxItems": 1024,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "line", "reason"],
+            "properties": {
+              "path": { "type": "string", "minLength": 1, "maxLength": 512 },
+              "line": { "type": "integer", "minimum": 1 },
+              "reason": { "type": "string", "minLength": 1, "maxLength": 1024 }
+            }
+          }
+        }
+      }
+    },
+    "database": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "mode",
+        "changeType",
+        "requiresCodeChanges",
+        "requiresSchemaMigration",
+        "desiredSchemaPath",
+        "migrationPaths",
+        "changedFiles",
+        "evidence",
+        "unsupportedFeatures"
+      ],
+      "properties": {
+        "mode": { "type": "string", "enum": ["none", "sql", "unsupported"] },
+        "changeType": {
+          "type": "string",
+          "enum": ["none", "code_only", "schema_only", "code_and_schema"]
+        },
+        "requiresCodeChanges": { "type": "boolean" },
+        "requiresSchemaMigration": { "type": "boolean" },
+        "desiredSchemaPath": { "type": "string", "maxLength": 512 },
+        "migrationPaths": {
+          "type": "array",
+          "maxItems": 128,
+          "items": { "type": "string", "minLength": 1, "maxLength": 512 }
+        },
+        "changedFiles": {
+          "type": "array",
+          "maxItems": 512,
+          "items": { "type": "string", "minLength": 1, "maxLength": 512 }
+        },
+        "evidence": {
+          "type": "array",
+          "maxItems": 128,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "line", "reason"],
+            "properties": {
+              "path": { "type": "string", "minLength": 1, "maxLength": 512 },
+              "line": { "type": "integer", "minimum": 1 },
+              "reason": { "type": "string", "minLength": 1, "maxLength": 1024 }
+            }
+          }
+        },
+        "unsupportedFeatures": {
+          "type": "array",
+          "maxItems": 64,
+          "items": { "type": "string", "minLength": 1, "maxLength": 512 }
+        }
+      }
+    },
+    "application": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "runtime",
+        "buildKind",
+        "topology",
+        "entrypoint",
+        "build",
+        "basePath",
+        "evidence",
+        "unsupportedFeatures"
+      ],
+      "properties": {
+        "runtime": {
+          "type": "string",
+          "pattern": "^(?:nodejs|python)[0-9]+(?:\\.[0-9]+)?$"
+        },
+        "buildKind": { "type": "string", "enum": ["container", "static"] },
+        "topology": {
+          "type": "string",
+          "enum": ["static", "backend", "frontend_and_backend"]
+        },
+        "entrypoint": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "build": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["installCommand", "buildCommand", "outputs"],
+          "properties": {
+            "installCommand": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 64,
+              "items": { "type": "string", "minLength": 1, "maxLength": 1024 }
+            },
+            "buildCommand": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 64,
+              "items": { "type": "string", "minLength": 1, "maxLength": 1024 }
+            },
+            "outputs": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 16,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["path", "kind", "route"],
+                "properties": {
+                  "path": { "type": "string", "minLength": 1, "maxLength": 512 },
+                  "kind": { "type": "string", "enum": ["public", "backend"] },
+                  "route": {
+                    "type": "string",
+                    "pattern": "^(?:/\\*|/[A-Za-z0-9_-]+(?:/[A-Za-z0-9_-]+)*/\\*)$"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "basePath": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["required", "environmentVariable"],
+          "properties": {
+            "required": { "type": "boolean" },
+            "environmentVariable": { "type": "string", "enum": ["HARBOUR_BASE_PATH"] }
+          }
+        },
+        "evidence": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "line", "reason"],
+            "properties": {
+              "path": { "type": "string", "minLength": 1, "maxLength": 512 },
+              "line": { "type": "integer", "minimum": 1 },
+              "reason": { "type": "string", "minLength": 1, "maxLength": 1024 }
+            }
+          }
+        },
+        "unsupportedFeatures": {
+          "type": "array",
+          "maxItems": 64,
+          "items": { "type": "string", "minLength": 1, "maxLength": 512 }
+        }
+      }
+    }
+  }
+}

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

@@ -1,13 +0,0 @@
-/**
- * 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/promotion-request.d.ts

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