@fourier-labs/harbour-contracts 0.3.1

package/schema/error-category.enum.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/error-category.enum.json",
+  "title": "ErrorCategory",
+  "description": "The closed failure-category enum T1b (LLD §2.2). Categories are hierarchical lowercase dot-paths; the histogram groups on any prefix. Some entries are FAMILIES (variable last segment, e.g. storage.unsupported-engine.<engine>) — at runtime a concrete token replaces the placeholder. Extended ONLY by PR to this file. Root validates any well-formed category string; x-registry is the source of truth for the per-category `retryable` flag and codegen constants.",
+  "$ref": "#/definitions/ErrorCategory",
+  "definitions": {
+    "ErrorCategory": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(\\.[a-z0-9-]+)+$",
+      "description": "Well-formed category: >=2 lowercase dot-path segments; segments may contain hyphens and digits."
+    }
+  },
+  "x-registry": [
+    { "id": "intake.no-entrypoint", "retryable": false, "description": "No detectable app entrypoint in the repo." },
+    { "id": "intake.unsupported-runtime", "retryable": false, "description": "Detected runtime has no Harbour build recipe." },
+    { "id": "intake.attestation-missing", "retryable": false, "description": "Required auth attestation absent." },
+    { "id": "intake.multi-app-repo", "retryable": false, "description": "Repo contains more than one deployable app." },
+    { "id": "secrets.unresolvable", "retryable": false, "description": "A referenced secret has no value (prod promotion blocks at GATING until a human sets it)." },
+    { "id": "secrets.leaked-in-artifact", "retryable": false, "description": "Artifact secret scan found a plaintext secret in the built image (belt-and-suspenders)." },
+    { "id": "storage.sqlite-misclassified", "retryable": false, "description": "SQLite usage not resolvable to a managed binding." },
+    { "id": "storage.unsupported-engine", "retryable": false, "family": true, "description": "Storage engine with no Harbour mapping; concrete token names the engine, e.g. storage.unsupported-engine.mongodb." },
+    { "id": "storage.mapping-drift", "retryable": false, "description": "Declared storage binding diverged from detected usage." },
+    { "id": "transform.deadline-exceeded", "retryable": false, "description": "The 15-minute transform wall deadline was reached." },
+    { "id": "transform.non-retryable", "retryable": false, "family": true, "description": "Agent declared the app unconvertible or hit an unsupported construct; fails immediately without burning remaining budget. Concrete token names the reason." },
+    { "id": "transform.validation-failed", "retryable": true, "description": "Transform candidate failed validation with iterable feedback; re-enters TRANSFORMING while deadline remains." },
+    { "id": "frontend.env-inlined-unfixable", "retryable": false, "description": "Client code inlined build-time env/self-URLs in a way transformation cannot rewrite." },
+    { "id": "build.recipe-failed", "retryable": false, "description": "The Harbour build recipe failed for the detected runtime." },
+    { "id": "build.image-too-large", "retryable": false, "description": "Built image exceeded the size limit." },
+    { "id": "verify.smoke-failed", "retryable": false, "description": "Candidate smoke/health check failed (boot, routes, storage, secret refs, response shape)." },
+    { "id": "verify.characterization-diverged", "retryable": false, "description": "Post-MVP: recorded req/res replay diverged beyond thresholds." },
+    { "id": "verify.migration-from-zero-failed", "retryable": false, "description": "Post-MVP: from-zero migration chain failed on scratch DB." },
+    { "id": "verify.migration-seeded-failed", "retryable": false, "description": "Post-MVP: seeded-data migration survival test failed." },
+    { "id": "auth.app-publicly-invocable", "retryable": false, "description": "The unsigned Function-URL probe was NOT rejected with 403 — the app door is open (hard verify gate)." },
+    { "id": "auth.identity-header-contract-violated", "retryable": false, "description": "App mishandled the platform identity header contract." },
+    { "id": "gate.security-scan", "retryable": false, "description": "A blocking security-scan gate failed." },
+    { "id": "gate.org-approver-declined", "retryable": false, "description": "An org approver declined promotion." },
+    { "id": "promote.migration-failed", "retryable": false, "description": "Post-MVP: prod migration replay failed; prod alias never moved." },
+    { "id": "promote.static-rebuild-failed", "retryable": false, "description": "Static rebuild during promotion failed." },
+    { "id": "runtime.persistent-compute-required", "retryable": false, "description": "App needs long-lived compute Lambda cannot provide (expected day-one leader; Fargate TODO trigger watches this)." },
+    { "id": "runtime.egress-blocked", "retryable": false, "description": "App required outbound network egress that policy blocked (e.g. external LLM call without NAT allowance)." },
+    { "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": "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/error-envelope.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/error-envelope.schema.json",
+  "title": "ErrorEnvelope",
+  "description": "Emitted exactly once per FAILED transition (LLD §2.1). Consumed identically by MCP (maker), alarms (platform), and the failure-log histogram. `maker_message` is the only human-facing text; everything else is data.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "envelope_version",
+    "app_id",
+    "version_id",
+    "env",
+    "stage",
+    "category",
+    "retryable",
+    "maker_message",
+    "remediation_hint",
+    "evidence_ref",
+    "ts"
+  ],
+  "properties": {
+    "envelope_version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Schema version of this envelope. Bumped only by PR to this file."
+    },
+    "app_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Immutable app slug."
+    },
+    "version_id": {
+      "type": "string",
+      "pattern": "^[^#]+#[^#]+#(preview|prod)#[0-9]{6,}$",
+      "description": "`<org>#<app>#<env>#<zero-padded ordinal>` (LLD §4.2.1)."
+    },
+    "env": {
+      "type": "string",
+      "enum": ["preview", "prod"]
+    },
+    "stage": {
+      "type": "string",
+      "enum": [
+        "admission",
+        "intake",
+        "transform",
+        "validate",
+        "build",
+        "verify",
+        "gate",
+        "cutover",
+        "promote"
+      ],
+      "description": "Pipeline stage that produced the failure (frozen T1b stage enum)."
+    },
+    "category": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(\\.[a-z0-9-]+)+$",
+      "description": "A category from the closed enum in error-category.enum.json (families carry a concrete last segment at runtime)."
+    },
+    "retryable": {
+      "type": "boolean",
+      "description": "Echoed from the category registry (LLD §2.2). The maker's tool renders \"retrying…\" vs \"this app can't be converted because…\"."
+    },
+    "maker_message": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Plain English, no AWS terms. What happened + what next. The ONLY human-facing field."
+    },
+    "remediation_hint": {
+      "type": "string",
+      "description": "Actionable for the maker's AI tool (machine-usable)."
+    },
+    "evidence_ref": {
+      "type": "string",
+      "pattern": "^s3://",
+      "description": "`s3://…/evidence/<org>/<app>/<version_id>/…` — reference to the evidence bundle, never inline."
+    },
+    "ts": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 UTC."
+    }
+  }
+}

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

@@ -0,0 +1,21 @@
+{
+  "$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.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["static", "api"],
+  "properties": {
+    "static": {
+      "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)."
+    },
+    "api": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Backend target for `/api/*` routes — the Lambda alias reached via API Gateway / Function URL for the LIVE version."
+    }
+  }
+}

package/schema/version-state.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/version-state.schema.json",
+  "title": "VersionState",
+  "description": "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.",
+  "$ref": "#/definitions/State",
+  "definitions": {
+    "State": {
+      "type": "string",
+      "enum": [
+        "QUEUED",
+        "ANALYZING",
+        "TRANSFORMING",
+        "VALIDATING",
+        "BUILDING",
+        "VERIFYING",
+        "GATING",
+        "LIVE",
+        "AWAITING-PROMOTION",
+        "PROMOTING",
+        "FAILED",
+        "STALE"
+      ]
+    },
+    "Env": {
+      "type": "string",
+      "enum": ["preview", "prod"]
+    },
+    "VersionId": {
+      "type": "string",
+      "pattern": "^[^#]+#[^#]+#(preview|prod)#[0-9]{6,}$",
+      "description": "`<org>#<app>#<env>#<zero-padded ordinal>` (LLD §4.2.1). Globally unique by composition; the ordinal is human-speakable (\"deploy #124\")."
+    }
+  },
+  "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": "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": "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" }
+  ]
+}