@fourier-labs/harbour-contracts 0.6.0 → 0.10.0

package/gen-ts/deploy-request.ts

@@ -0,0 +1,117 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * One environment-variable binding: exactly one of secretRef (secret, resolved at runtime) or value (plain literal).
+ */
+export type DeployRequestEnvironmentBinding = {
+  /**
+   * Environment-variable name the app reads.
+   */
+  name: string;
+  /**
+   * secretref URI resolved at runtime; the value never appears in the request.
+   */
+  secretRef?: string;
+  /**
+   * Plain (non-secret) literal value.
+   */
+  value?: string;
+} & DeployRequestEnvironmentBinding1;
+export type DeployRequestEnvironmentBinding1 = {
+  [k: string]: unknown;
+};
+type BindingClassificationEntry = {
+  kind: 'configuration' | 'secret' | 'provider_credential';
+  confidence: 'high' | 'low';
+  providerId?: 'openai' | 'anthropic' | 'gemini' | 'openrouter';
+  /**
+   * Closed current credential category. Add a reviewed contract version before supporting another credential mechanism.
+   */
+  category?: 'api_key';
+  requestedAiMappingId?: string;
+};
+
+/**
+ * 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;
+  environmentBindings?: DeployRequestEnvironmentBindings;
+  bindingClassification: BindingClassificationSubject;
+}
+export interface DeployRequestSource {
+  /**
+   * Source provider. The preview MVP accepts only github.
+   */
+  provider: 'github';
+  /**
+   * Credential-free HTTPS GitHub repository URL.
+   */
+  repositoryUrl: string;
+}
+/**
+ * Optional runtime environment configuration (Secret-Manager MVP). Named environmentBindings, not environment — the existing required `environment` property is the deployment-target token and predates this object. Additive: requests without it remain valid.
+ */
+export interface DeployRequestEnvironmentBindings {
+  /**
+   * Environment-variable bindings for this deployment.
+   */
+  bindings: DeployRequestEnvironmentBinding[];
+}
+/**
+ * Complete pre-allocation, value-free binding-name classification. DCP verifies its tenant/app/environment/source identity and exact name coverage before minting the versionId.
+ */
+interface BindingClassificationSubject {
+  schema: 'harbour.binding-classification-subject/1.0';
+  /**
+   * Partial or unavailable classification cannot be represented as an admissible subject.
+   */
+  status: 'COMPLETE';
+  tenantId: string;
+  appId: string;
+  environment: 'preview' | 'prod';
+  /**
+   * Provider-neutral, normalized and credential-free source repository reference. Current GitHub HTTPS references and future SCM adapters use the same safe hierarchical grammar; userinfo, ports, percent encoding, query strings and fragments are unrepresentable.
+   */
+  sourceRef: string;
+  /**
+   * Provider-neutral exact revision identifier expressed as algorithm:value. Current Git adapters use git-sha1:<40 lowercase hex>; another SCM or Git hash algorithm does not require a shape change.
+   */
+  sourceRevision: string;
+  sourceRevisionDigest: string;
+  classifierRevision: string;
+  /**
+   * Exact classification set keyed by every declared environment-binding name. Object keys make missing duplication tricks and two classifications for one name unrepresentable. Literal values and secret references are intentionally unrepresentable. DCP additionally requires these keys to equal the names in the request's environmentBindings before allocation.
+   */
+  classifications: {
+    [k: string]: BindingClassificationEntry;
+  };
+  /**
+   * Exact set keyed by requested AI mapping ID of supported mappings intended to own provider-client credentials for this source revision. This is pre-PLAN request evidence, not a claim that enforcement already exists. Provider-credential classifications reference one of these exact mapping IDs.
+   */
+  requestedAiMappings: {
+    [k: string]: BindingClassificationAiMapping;
+  };
+  classificationDigest: string;
+}
+interface BindingClassificationAiMapping {
+  mappingVersion: string;
+  providerId: 'openai' | 'anthropic' | 'gemini' | 'openrouter';
+}

package/gen-ts/deploy-response.ts

@@ -0,0 +1,33 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * 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';
+  /**
+   * Digest of the validated pre-allocation BindingClassificationSubject.
+   */
+  classificationDigest: string;
+  /**
+   * Digest of the exact version-bound SanitizedBindingEvidence persisted atomically before this response.
+   */
+  sanitizedBindingDigest: string;
+  acceptedAt: string;
+  /**
+   * Relative URL for exact-version Status. The versionId path segment is URL encoded.
+   */
+  statusUrl: string;
+}

package/gen-ts/deployment-environment.ts

@@ -0,0 +1,7 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * 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/gen-ts/deployment-source.ts

@@ -0,0 +1,16 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * 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/gen-ts/deployment-status-failure.ts

@@ -0,0 +1,12 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * 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/gen-ts/deployment-status-request.ts

@@ -0,0 +1,11 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * 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/gen-ts/deployment-status-response.ts

@@ -0,0 +1,39 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * 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' | 'prod';
+  status:
+    | 'QUEUED'
+    | 'ANALYZING'
+    | 'TRANSFORMING'
+    | 'VALIDATING'
+    | 'BUILDING'
+    | 'VERIFYING'
+    | 'GATING'
+    | 'LIVE'
+    | 'AWAITING-PROMOTION'
+    | 'PROMOTING'
+    | '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/gen-ts/env-bindings.ts

@@ -0,0 +1,64 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * 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/gen-ts/error-category-registry.ts

@@ -0,0 +1,108 @@
+/* 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",
+  SecretsReferenceUnresolvable: "secrets.reference-unresolvable",
+  SecretsPlaceholderUnresolved: "secrets.placeholder-unresolved",
+  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",
+  BrowserProbeFailed: "browser.probe-failed",
+  BrowserProbeUnavailable: "browser.probe-unavailable",
+  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",
+  SourceBranchMoved: "source.branch-moved",
+  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",
+} as const;
+
+const retryableExact: Record<string, boolean> = {
+  "intake.no-entrypoint": false,
+  "intake.unsupported-runtime": false,
+  "intake.attestation-missing": false,
+  "intake.multi-app-repo": false,
+  "secrets.unresolvable": false,
+  "secrets.reference-unresolvable": false,
+  "secrets.placeholder-unresolved": 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,
+  "browser.probe-failed": true,
+  "browser.probe-unavailable": 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,
+  "source.branch-moved": false,
+  "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: Record<string, boolean> = {
+  "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: string): boolean {
+  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/gen-ts/error-category.ts

@@ -0,0 +1,7 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * 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/gen-ts/error-envelope.ts

@@ -0,0 +1,49 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * 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/gen-ts/index.ts

@@ -0,0 +1,51 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+export * from './ai-budget-ledger-event.js';
+export * from './ai-callsite-inventory.js';
+export * from './ai-classification-stamp.js';
+export * from './ai-composite-policy-digest-helper.js';
+export * from './ai-composite-policy-digest.js';
+export * from './ai-deployment-gate-decision.js';
+export * from './ai-gateway-key-lifecycle-event.js';
+export * from './ai-gateway-key-lookup.js';
+export * from './ai-gateway-key-token.js';
+export * from './ai-governance-decision.js';
+export * from './ai-metering-policy.js';
+export * from './ai-policy-snapshot.js';
+export * from './ai-pricing-revision.js';
+export * from './ai-runtime-binding.js';
+export * from './ai-runtime-contract.js';
+export * from './ai-trace-event-v2.js';
+export * from './ai-trace-event.js';
+export * from './ai-transform-event.js';
+export * from './ai-transform-result.js';
+export * from './ai-verification-evidence.js';
+export * from './api-error-response.js';
+export * from './artifact-contract.js';
+export * from './binding-classification-digest-helper.js';
+export * from './binding-classification-subject.js';
+export * from './contract-release.js';
+export * from './data-dependency.js';
+export * from './data-grant.js';
+export * from './data-source.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 './promotion-request.js';
+export * from './promotion-response.js';
+export * from './sanitized-binding-digest-helper.js';
+export * from './sanitized-binding-evidence.js';
+export * from './secret-reference.js';
+export * from './transform-report.js';
+export * from './version-state-machine.js';
+export * from './version-state.js';

package/gen-ts/kvs-routing-entry.ts

@@ -0,0 +1,30 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * 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.
+ */
+export interface KvsRoutingEntry {
+  /**
+   * 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.
+   */
+  staticPath: string;
+  /**
+   * 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.
+   */
+  routeMode: 'server' | 'static';
+  /**
+   * 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.
+   */
+  ordinal: number;
+  /**
+   * 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.
+   */
+  apiDomain?: string;
+  /**
+   * 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.
+   *
+   * @maxItems 16
+   */
+  staticAssetPrefixes?: string[];
+}

package/gen-ts/promotion-request.ts

@@ -0,0 +1,95 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+type BindingClassificationEntry = {
+  kind: 'configuration' | 'secret' | 'provider_credential';
+  confidence: 'high' | 'low';
+  providerId?: 'openai' | 'anthropic' | 'gemini' | 'openrouter';
+  /**
+   * Closed current credential category. Add a reviewed contract version before supporting another credential mechanism.
+   */
+  category?: 'api_key';
+  requestedAiMappingId?: string;
+};
+
+/**
+ * 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;
+  environmentBindings?: PromotionRequestEnvironmentBindings;
+  bindingClassification: BindingClassificationSubject;
+}
+/**
+ * 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.
+ */
+export interface PromotionRequestEnvironmentBindings {
+  /**
+   * Secret bindings for the production version. An empty array is meaningful: it says the caller looked and the app declares no secrets.
+   */
+  bindings: PromotionRequestSecretBinding[];
+}
+/**
+ * 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.
+ */
+export interface PromotionRequestSecretBinding {
+  /**
+   * Environment-variable name the app reads.
+   */
+  name: string;
+  /**
+   * Governance reference the deployment plane resolves. The value never appears in the request, in this schema, or in any record derived from it.
+   */
+  secretRef: string;
+}
+/**
+ * Complete pre-allocation, value-free classification for the exact production source revision and declared production binding names. It intentionally has no production versionId; DCP allocates that identity atomically.
+ */
+interface BindingClassificationSubject {
+  schema: 'harbour.binding-classification-subject/1.0';
+  /**
+   * Partial or unavailable classification cannot be represented as an admissible subject.
+   */
+  status: 'COMPLETE';
+  tenantId: string;
+  appId: string;
+  environment: 'preview' | 'prod';
+  /**
+   * Provider-neutral, normalized and credential-free source repository reference. Current GitHub HTTPS references and future SCM adapters use the same safe hierarchical grammar; userinfo, ports, percent encoding, query strings and fragments are unrepresentable.
+   */
+  sourceRef: string;
+  /**
+   * Provider-neutral exact revision identifier expressed as algorithm:value. Current Git adapters use git-sha1:<40 lowercase hex>; another SCM or Git hash algorithm does not require a shape change.
+   */
+  sourceRevision: string;
+  sourceRevisionDigest: string;
+  classifierRevision: string;
+  /**
+   * Exact classification set keyed by every declared environment-binding name. Object keys make missing duplication tricks and two classifications for one name unrepresentable. Literal values and secret references are intentionally unrepresentable. DCP additionally requires these keys to equal the names in the request's environmentBindings before allocation.
+   */
+  classifications: {
+    [k: string]: BindingClassificationEntry;
+  };
+  /**
+   * Exact set keyed by requested AI mapping ID of supported mappings intended to own provider-client credentials for this source revision. This is pre-PLAN request evidence, not a claim that enforcement already exists. Provider-credential classifications reference one of these exact mapping IDs.
+   */
+  requestedAiMappings: {
+    [k: string]: BindingClassificationAiMapping;
+  };
+  classificationDigest: string;
+}
+interface BindingClassificationAiMapping {
+  mappingVersion: string;
+  providerId: 'openai' | 'anthropic' | 'gemini' | 'openrouter';
+}