@fourier-labs/harbour-contracts 0.3.1

package/README.md

@@ -0,0 +1,102 @@
+# harbour-contracts
+
+The single source of truth for every data shape that crosses a boundary between Harbour
+components. **Schema-first:** hand-written JSON Schema in `schema/` is the source; the Go
+package (`gen-go/`) and TypeScript package (`gen-ts/` → `@fourier-labs/harbour-contracts`) are **generated**
+and committed. No handler, infra stack, or MCP op is built against a shape that does not
+exist here first.
+
+## Layout
+
+| Path | What |
+|---|---|
+| `schema/*.json` | JSON Schema (draft-07). The only files you hand-edit. |
+| `gen-go/` | Generated Go package `contracts` (import `github.com/Fourier-Labs-AI/harbour-contracts/gen-go`). |
+| `gen-ts/` | Generated TS sources; published as `@fourier-labs/harbour-contracts`. |
+| `tools/gen/gen.mjs` | The single codegen driver (Node). Validates every schema, then emits Go + TS. |
+| `docs/adr/` | Decision records (e.g. `0001-t1-ratified.md`). |
+
+## The schemas
+
+| File | Shape | LLD |
+|---|---|---|
+| `deploy-request.schema.json` | MCP `deploy(app, {commit, branch})` payload | §7 |
+| `error-envelope.schema.json` | The failure envelope emitted once per FAILED transition | §2.1 |
+| `error-category.enum.json` | Closed failure-category enum + per-category `retryable` registry | §2.2 |
+| `artifact-contract.schema.json` | Build output contract (the provider-portability seam) | §3 |
+| `version-state.schema.json` | State machine T1a — states, legal transitions, versionId format | §1 |
+| `env-bindings.schema.json` | `EnvBindings` / `Target` / `Binding` (BYOC-complete) | §4.2.2 |
+| `kvs-routing-entry.schema.json` | CloudFront KVS routing value (`{static, api}`) | §8 |
+
+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
+  `canTransition` / `isTerminal` (TS), driven by the `x-transitions` edge list — so control-plane
+  and any consumer agree on legality from one source.
+
+## Workflow
+
+```sh
+make gen       # regenerate gen-go/ + gen-ts/ from schema/ (Node only — no Go needed)
+make verify    # regenerate, then fail if git shows a diff  ← the staleness gate (CI runs this)
+make build     # compile-check the generated Go + TS (needs go + local tsc)
+make test      # generator determinism + contract-logic tests (Node; Go when installed)
+```
+
+Codegen is **Node-only** so `make gen` is reproducible anywhere; a Go toolchain and `tsc` are
+used solely to *compile-check* the output (`make build`), not to generate it.
+
+### Changing a shape
+
+1. Edit the schema in `schema/`. The category enum and state machine are **closed** — extend
+   them **only by PR to this repo** (that PR is where consumers are notified).
+2. `make gen` and commit `gen-go/` + `gen-ts/` alongside the schema change.
+3. CI (`make verify`) fails any PR whose committed generated code does not match its schema.
+4. A shape change is a `(contracts)` change: it lands via `/review` + `/code-review ultra` → `/ship`.
+
+## Consuming
+
+- **Go:** `go get github.com/Fourier-Labs-AI/harbour-contracts/gen-go@v0.1.0`
+
+  Two things make this work, and the second is not the obvious one.
+
+  **The tag must be 3-part semver.** Go requires exactly `vMAJOR.MINOR.PATCH`, so the
+  repo's 4-digit `VERSION` (`0.1.0.0`) cannot be a Go tag — the proxy rejects it. Each
+  release carries **two** tags on the same commit: `v0.1.0.0` (repo version, what
+  `/ship` manages) and `v0.1.0` (Go module). Keep the first three components identical.
+
+  **The repo is private, and Go fetches it from a global cache.** Set this once per
+  machine:
+
+  ```sh
+  go env -w GOPRIVATE=github.com/Fourier-Labs-AI/*
+  git config --global credential."https://github.com/Fourier-Labs-AI".helper '!gh auth git-credential'
+  git config --global credential."https://github.com/Fourier-Labs-AI".useHttpPath true
+  ```
+
+  The credential config has to be **global and URL-scoped**, and that combination is
+  not incidental:
+
+  - It cannot be folder-scoped (`includeIf gitdir:…`). Go runs `git ls-remote` inside
+    `~/go/pkg/mod/cache/vcs/…`, not inside your repo, so a per-directory helper never
+    applies. This fails identically from `/tmp` and from inside a Harbour repo, which
+    makes it look like a bad tag rather than an auth problem.
+  - Scoping by URL prefix keeps it off your other GitHub accounts: only
+    `github.com/Fourier-Labs-AI/*` uses this credential.
+  - An SSH `insteadOf` rewrite is the usual advice and is **wrong here** unless your
+    SSH key belongs to an account with Fourier org access. Check with
+    `ssh -T git@github.com` before reaching for it.
+
+  Without the above, `go get` fails with `Repository not found` — which reads as a
+  missing tag, not as missing access.
+
+- **TS:** `npm i @fourier-labs/harbour-contracts` — published from the tag by CI.
+
+## Notes
+
+`gen.mjs` produces both languages deterministically from Node. Go **struct field alignment** is
+not gofmt-normalized by the generator (gofmt is optional hygiene via `make fmt`); this never
+affects compilation, and the staleness gate compares raw generator output, so it stays green.

package/dist/api-error-response.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+export interface ApiErrorResponse {
+    code: string;
+    message: string;
+    correlationId: string;
+    requestId?: string;
+    /**
+     * Present when a version was minted before the API-level failure.
+     */
+    versionId?: string;
+}

package/dist/api-error-response.js

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

package/dist/artifact-contract.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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.
+ */
+export interface ArtifactContract {
+    contract_version: 1;
+    app_id: string;
+    commit: string;
+    /**
+     * sha256 of the canonical bundle; the immutable identity that promotion pins to (invariant §1.3.2).
+     */
+    artifact_digest: string;
+    backend: {
+        type: 'oci-image' | 'zip';
+        /**
+         * ECR uri@digest (oci-image) or S3 key (zip).
+         */
+        ref: string;
+        entrypoint: string;
+        runtime: string;
+    };
+    static: {
+        /**
+         * e.g. builds/<digest>/
+         */
+        path: string;
+        /**
+         * true when static assets carry no env-specific values (no static rebuild needed on promotion).
+         */
+        env_agnostic: boolean;
+    };
+    routes: {
+        path: string;
+        target: 'backend' | 'static';
+    }[];
+    env: {
+        /**
+         * Non-secret env vars, e.g. {"PORT":"8080"}.
+         */
+        vars: {
+            [k: string]: string;
+        };
+        /**
+         * Secrets Manager references only, e.g. harbour/<org>/<app>/<env>/STRIPE_KEY. Never values.
+         */
+        secret_refs: string[];
+    };
+    storage_bindings: {
+        kind: 'sql' | 'kv' | 'files';
+        /**
+         * Logical name, e.g. "default".
+         */
+        logical?: string;
+        /**
+         * e.g. aurora-sv2.
+         */
+        provider: string;
+    }[];
+    /**
+     * Post-MVP (migration tooling is post-MVP, LLD §4.6); MVP emits an empty array.
+     */
+    migrations: {
+        seq: number;
+        sha: string;
+        destructive: boolean;
+        path: string;
+    }[];
+    /**
+     * MVP emits an empty array.
+     */
+    scheduled_tasks: {}[];
+    transform_report: {
+        /**
+         * Transformed surfaces, e.g. ["secrets","storage.sql"].
+         */
+        surfaces: string[];
+        static_rebuild_required: boolean;
+    };
+}

package/dist/artifact-contract.js

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

package/dist/deploy-request.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+export interface DeployRequest {
+    source: DeployRequestSource;
+    /**
+     * Deployment target. The API rejects production; production remains human-merge gated.
+     */
+    environment: 'preview';
+    /**
+     * Git branch that must contain the exact requested commit.
+     */
+    branch: string;
+    /**
+     * Exact lowercase hexadecimal Git commit to materialize and deploy.
+     */
+    commit: string;
+    /**
+     * 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.
+     */
+    idempotencyKey?: string;
+}
+export interface DeployRequestSource {
+    /**
+     * Source provider. The preview MVP accepts only github.
+     */
+    provider: 'github';
+    /**
+     * Credential-free HTTPS GitHub repository URL.
+     */
+    repositoryUrl: string;
+}

package/dist/deploy-request.js

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

package/dist/deploy-response.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+export interface DeployResponse {
+    /**
+     * Caller correlation value. This is not the deployment identity.
+     */
+    requestId: string;
+    /**
+     * Immutable identity of the admitted preview version.
+     */
+    versionId: string;
+    tenant: string;
+    app: string;
+    environment: 'preview';
+    status: 'QUEUED';
+    acceptedAt: string;
+    /**
+     * Relative URL for exact-version Status. The versionId path segment is URL encoded.
+     */
+    statusUrl: string;
+}

package/dist/deploy-response.js

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

package/dist/deployment-environment.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 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.
+ */
+export type DeploymentEnvironment = 'preview';

package/dist/deployment-environment.js

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

package/dist/deployment-source.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Credential-free GitHub source supplied in the DeployRequest body. Credentials are resolved internally by MaterializeSource and never cross the API boundary.
+ */
+export interface DeploymentSource {
+    /**
+     * Source provider. The preview MVP accepts only GitHub.
+     */
+    provider: 'github';
+    /**
+     * Credential-free HTTPS GitHub repository URL. Query strings, fragments, embedded credentials and non-github.com hosts are rejected.
+     */
+    repositoryUrl: string;
+}

package/dist/deployment-source.js

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

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

@@ -0,0 +1,9 @@
+/**
+ * Frontend-safe failure projection nested in a failed DeploymentStatusResponse. Internal evidence references, AWS identifiers and raw provider errors are excluded.
+ */
+export interface DeploymentStatusFailure {
+    category: string;
+    retryable: boolean;
+    message: string;
+    remediationHint: string;
+}

package/dist/deployment-status-failure.js

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

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

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export interface DeploymentStatusRequest {
+    tenant: string;
+    app: string;
+    versionId: string;
+}

package/dist/deployment-status-request.js

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

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

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+export interface DeploymentStatusResponse {
+    requestId: string;
+    versionId: string;
+    tenant: string;
+    app: string;
+    environment: 'preview';
+    status: 'QUEUED' | 'ANALYZING' | 'TRANSFORMING' | 'VALIDATING' | 'BUILDING' | 'VERIFYING' | 'GATING' | 'LIVE' | 'FAILED' | 'STALE';
+    message: string;
+    branch: string;
+    commit: string;
+    requestedAt: string;
+    updatedAt: string;
+    url?: string;
+    failure?: StatusFailureProjection;
+}
+export interface StatusFailureProjection {
+    category: string;
+    retryable: boolean;
+    message: string;
+    remediationHint: string;
+}

package/dist/deployment-status-response.js

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

package/dist/env-bindings.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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').
+ */
+export interface EnvBindings {
+    /**
+     * e.g. preview | prod.
+     */
+    env: string;
+    executor: Binding;
+    sql: Binding;
+    kv: Binding;
+    files: Binding;
+    secrets: Binding;
+    serving: Binding;
+    executionCell: Binding;
+    /**
+     * Ordered gate names evaluated at GATING.
+     */
+    gates: string[];
+    /**
+     * MVP: absent. Future: per-target constraints (region pins, size caps, …).
+     */
+    constraints?: {
+        [k: string]: unknown;
+    };
+    /**
+     * Stamped onto the version record for audit; bumps when the binding shape changes.
+     */
+    bindingsVersion: number;
+}
+/**
+ * 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.
+ */
+export interface Binding {
+    provider: string;
+    target: Target;
+    /**
+     * 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.
+     */
+    config?: {
+        [k: string]: unknown;
+    };
+}
+export interface Target {
+    /**
+     * MVP: own account id.
+     */
+    account: string;
+    /**
+     * MVP: us-east-1.
+     */
+    region: string;
+    /**
+     * BYOC cross-account role; absent in MVP = act locally.
+     */
+    roleArn?: string;
+    /**
+     * BYOC assume-role external id; absent in MVP.
+     */
+    externalId?: string;
+}

package/dist/env-bindings.js

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

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

@@ -0,0 +1,33 @@
+export declare const ErrorCategories: {
+    readonly IntakeNoEntrypoint: "intake.no-entrypoint";
+    readonly IntakeUnsupportedRuntime: "intake.unsupported-runtime";
+    readonly IntakeAttestationMissing: "intake.attestation-missing";
+    readonly IntakeMultiAppRepo: "intake.multi-app-repo";
+    readonly SecretsUnresolvable: "secrets.unresolvable";
+    readonly SecretsLeakedInArtifact: "secrets.leaked-in-artifact";
+    readonly StorageSqliteMisclassified: "storage.sqlite-misclassified";
+    readonly StorageMappingDrift: "storage.mapping-drift";
+    readonly TransformDeadlineExceeded: "transform.deadline-exceeded";
+    readonly TransformValidationFailed: "transform.validation-failed";
+    readonly FrontendEnvInlinedUnfixable: "frontend.env-inlined-unfixable";
+    readonly BuildRecipeFailed: "build.recipe-failed";
+    readonly BuildImageTooLarge: "build.image-too-large";
+    readonly VerifySmokeFailed: "verify.smoke-failed";
+    readonly VerifyCharacterizationDiverged: "verify.characterization-diverged";
+    readonly VerifyMigrationFromZeroFailed: "verify.migration-from-zero-failed";
+    readonly VerifyMigrationSeededFailed: "verify.migration-seeded-failed";
+    readonly AuthAppPubliclyInvocable: "auth.app-publicly-invocable";
+    readonly AuthIdentityHeaderContractViolated: "auth.identity-header-contract-violated";
+    readonly GateSecurityScan: "gate.security-scan";
+    readonly GateOrgApproverDeclined: "gate.org-approver-declined";
+    readonly PromoteMigrationFailed: "promote.migration-failed";
+    readonly PromoteStaticRebuildFailed: "promote.static-rebuild-failed";
+    readonly RuntimePersistentComputeRequired: "runtime.persistent-compute-required";
+    readonly RuntimeEgressBlocked: "runtime.egress-blocked";
+    readonly AdmissionAppNotRegistered: "admission.app-not-registered";
+    readonly DeployCommitNotOnBranch: "deploy.commit-not-on-branch";
+    readonly DeployQueuePublicationFailed: "deploy.queue-publication-failed";
+    readonly CutoverFlipFailed: "cutover.flip-failed";
+};
+/** Retryable lookup for a concrete or family-suffixed category. Unknown → false (fail closed). */
+export declare function isRetryable(category: string): boolean;

package/dist/error-category-registry.js

@@ -0,0 +1,85 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+export const ErrorCategories = {
+    IntakeNoEntrypoint: "intake.no-entrypoint",
+    IntakeUnsupportedRuntime: "intake.unsupported-runtime",
+    IntakeAttestationMissing: "intake.attestation-missing",
+    IntakeMultiAppRepo: "intake.multi-app-repo",
+    SecretsUnresolvable: "secrets.unresolvable",
+    SecretsLeakedInArtifact: "secrets.leaked-in-artifact",
+    StorageSqliteMisclassified: "storage.sqlite-misclassified",
+    StorageMappingDrift: "storage.mapping-drift",
+    TransformDeadlineExceeded: "transform.deadline-exceeded",
+    TransformValidationFailed: "transform.validation-failed",
+    FrontendEnvInlinedUnfixable: "frontend.env-inlined-unfixable",
+    BuildRecipeFailed: "build.recipe-failed",
+    BuildImageTooLarge: "build.image-too-large",
+    VerifySmokeFailed: "verify.smoke-failed",
+    VerifyCharacterizationDiverged: "verify.characterization-diverged",
+    VerifyMigrationFromZeroFailed: "verify.migration-from-zero-failed",
+    VerifyMigrationSeededFailed: "verify.migration-seeded-failed",
+    AuthAppPubliclyInvocable: "auth.app-publicly-invocable",
+    AuthIdentityHeaderContractViolated: "auth.identity-header-contract-violated",
+    GateSecurityScan: "gate.security-scan",
+    GateOrgApproverDeclined: "gate.org-approver-declined",
+    PromoteMigrationFailed: "promote.migration-failed",
+    PromoteStaticRebuildFailed: "promote.static-rebuild-failed",
+    RuntimePersistentComputeRequired: "runtime.persistent-compute-required",
+    RuntimeEgressBlocked: "runtime.egress-blocked",
+    AdmissionAppNotRegistered: "admission.app-not-registered",
+    DeployCommitNotOnBranch: "deploy.commit-not-on-branch",
+    DeployQueuePublicationFailed: "deploy.queue-publication-failed",
+    CutoverFlipFailed: "cutover.flip-failed",
+};
+const retryableExact = {
+    "intake.no-entrypoint": false,
+    "intake.unsupported-runtime": false,
+    "intake.attestation-missing": false,
+    "intake.multi-app-repo": false,
+    "secrets.unresolvable": false,
+    "secrets.leaked-in-artifact": false,
+    "storage.sqlite-misclassified": false,
+    "storage.mapping-drift": false,
+    "transform.deadline-exceeded": false,
+    "transform.validation-failed": true,
+    "frontend.env-inlined-unfixable": false,
+    "build.recipe-failed": false,
+    "build.image-too-large": false,
+    "verify.smoke-failed": false,
+    "verify.characterization-diverged": false,
+    "verify.migration-from-zero-failed": false,
+    "verify.migration-seeded-failed": false,
+    "auth.app-publicly-invocable": false,
+    "auth.identity-header-contract-violated": false,
+    "gate.security-scan": false,
+    "gate.org-approver-declined": false,
+    "promote.migration-failed": false,
+    "promote.static-rebuild-failed": false,
+    "runtime.persistent-compute-required": false,
+    "runtime.egress-blocked": false,
+    "admission.app-not-registered": false,
+    "deploy.commit-not-on-branch": false,
+    "deploy.queue-publication-failed": true,
+    "cutover.flip-failed": false,
+};
+const retryableFamilies = {
+    "storage.unsupported-engine": false,
+    "transform.non-retryable": false,
+    "quota.exceeded": false,
+    "uncategorized": false,
+};
+/** Retryable lookup for a concrete or family-suffixed category. Unknown → false (fail closed). */
+export function isRetryable(category) {
+    if (category in retryableExact)
+        return retryableExact[category];
+    let best = false, bestLen = -1;
+    for (const prefix of Object.keys(retryableFamilies)) {
+        if (category === prefix || category.startsWith(prefix + '.')) {
+            if (prefix.length > bestLen) {
+                best = retryableFamilies[prefix];
+                bestLen = prefix.length;
+            }
+        }
+    }
+    return best;
+}

package/dist/error-category.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 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.
+ */
+export type ErrorCategory = string;

package/dist/error-category.js

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

package/dist/error-envelope.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+export interface ErrorEnvelope {
+    /**
+     * Schema version of this envelope. Bumped only by PR to this file.
+     */
+    envelope_version: 1;
+    /**
+     * Immutable app slug.
+     */
+    app_id: string;
+    /**
+     * `<org>#<app>#<env>#<zero-padded ordinal>` (LLD §4.2.1).
+     */
+    version_id: string;
+    env: 'preview' | 'prod';
+    /**
+     * Pipeline stage that produced the failure (frozen T1b stage enum).
+     */
+    stage: 'admission' | 'intake' | 'transform' | 'validate' | 'build' | 'verify' | 'gate' | 'cutover' | 'promote';
+    /**
+     * A category from the closed enum in error-category.enum.json (families carry a concrete last segment at runtime).
+     */
+    category: string;
+    /**
+     * Echoed from the category registry (LLD §2.2). The maker's tool renders "retrying…" vs "this app can't be converted because…".
+     */
+    retryable: boolean;
+    /**
+     * Plain English, no AWS terms. What happened + what next. The ONLY human-facing field.
+     */
+    maker_message: string;
+    /**
+     * Actionable for the maker's AI tool (machine-usable).
+     */
+    remediation_hint: string;
+    /**
+     * `s3://…/evidence/<org>/<app>/<version_id>/…` — reference to the evidence bundle, never inline.
+     */
+    evidence_ref: string;
+    /**
+     * ISO-8601 UTC.
+     */
+    ts: string;
+}

package/dist/error-envelope.js

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

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export * from './api-error-response.js';
+export * from './artifact-contract.js';
+export * from './deploy-request.js';
+export * from './deploy-response.js';
+export * from './deployment-environment.js';
+export * from './deployment-source.js';
+export * from './deployment-status-failure.js';
+export * from './deployment-status-request.js';
+export * from './deployment-status-response.js';
+export * from './env-bindings.js';
+export * from './error-category-registry.js';
+export * from './error-category.js';
+export * from './error-envelope.js';
+export * from './kvs-routing-entry.js';
+export * from './version-state-machine.js';
+export * from './version-state.js';

package/dist/index.js

@@ -0,0 +1,18 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+export * from './api-error-response.js';
+export * from './artifact-contract.js';
+export * from './deploy-request.js';
+export * from './deploy-response.js';
+export * from './deployment-environment.js';
+export * from './deployment-source.js';
+export * from './deployment-status-failure.js';
+export * from './deployment-status-request.js';
+export * from './deployment-status-response.js';
+export * from './env-bindings.js';
+export * from './error-category-registry.js';
+export * from './error-category.js';
+export * from './error-envelope.js';
+export * from './kvs-routing-entry.js';
+export * from './version-state-machine.js';
+export * from './version-state.js';