@fourier-labs/harbour-contracts 0.5.0 → 0.9.0

package/gen-ts/data-grant.ts

@@ -0,0 +1,71 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * Access mode. MVP is read-only; write is a deliberate future schema change.
+ */
+export type DataGrantMode = 'read';
+/**
+ * MVP: one minted service principal per grant. Per-end-user passthrough is a future schema change.
+ */
+export type DataGrantIdentityModel = 'service';
+/**
+ * Grant lifecycle state. Legal edges live in x-transitions; GRANTED and DENIED are terminal.
+ */
+export type DataGrantStatus = 'REQUESTED' | 'GRANTED' | 'DENIED';
+
+/**
+ * An app's approved (or requested) read scope against a registered data source. MVP is deliberately narrow: mode is read-only and identityModel is service (one minted principal per grant, no per-end-user identity passthrough). Grant status is a tiny state machine — legal edges live in x-transitions and codegen turns them into shared CanTransitionDataGrantStatus / IsTerminalDataGrantStatus helpers so control-plane and consumers agree on legality.
+ */
+export interface DataGrant {
+  /**
+   * App the grant belongs to.
+   */
+  appId: string;
+  /**
+   * Registered data source the grant targets (data-source.schema.json).
+   */
+  sourceId: string;
+  /**
+   * Requested/granted selectors; every selector must fall inside the source's allowedScope.
+   *
+   * @minItems 1
+   */
+  scope: string[];
+  mode: DataGrantMode;
+  identityModel: DataGrantIdentityModel;
+  status: DataGrantStatus;
+  /**
+   * secretref URI of the minted per-grant credential; present once GRANTED.
+   */
+  credentialRef?: string;
+  /**
+   * Name of the scoped principal minted on the source for this grant; present once GRANTED.
+   */
+  mintedPrincipal?: string;
+  /**
+   * Operation (e.g. deployment analysis) that raised the request, for audit correlation.
+   */
+  requestedByOperationId?: string;
+  /**
+   * Admin identity that resolved the request; present once GRANTED or DENIED.
+   */
+  approvedBy?: string;
+  /**
+   * RFC 3339 instant the request was resolved; present once GRANTED or DENIED.
+   */
+  approvedAt?: string;
+}
+
+const legalDataGrantStatusTransitions: Record<string, Record<string, true>> = {
+  "REQUESTED": { "GRANTED": true, "DENIED": true },
+};
+const terminalDataGrantStatusStates = new Set<string>(["GRANTED", "DENIED"]);
+
+/** True iff from→to is a legal DataGrantStatus edge (schema x-transitions). */
+export function canTransitionDataGrantStatus(from: string, to: string): boolean {
+  return Boolean(legalDataGrantStatusTransitions[from]?.[to]);
+}
+
+/** True iff the DataGrantStatus is terminal (GRANTED, DENIED). */
+export function isTerminalDataGrantStatus(state: string): boolean { return terminalDataGrantStatusStates.has(state); }

package/gen-ts/data-source.ts

@@ -0,0 +1,78 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * Closed connector set for the Data-Access MVP.
+ */
+export type DataSourceConnector = 'postgres' | 'redshift' | 'bigquery' | 'databricks';
+/**
+ * byo = admin brought existing infrastructure; harbour_managed = Harbour provisioned it.
+ */
+export type DataSourceProvisioningMode = 'byo' | 'harbour_managed';
+/**
+ * DISABLED sources reject new grants and suspend existing access.
+ */
+export type DataSourceStatus = 'ACTIVE' | 'DISABLED';
+
+/**
+ * An admin-registered external data source (Data-Access MVP). The credential the platform holds for the source never crosses this boundary — credentialRef is a secretref URI resolved internally. allowedScope is the admin-declared selector allowlist grants are checked against; observedScope is what discovery actually saw and is informational only.
+ */
+export interface DataSource {
+  /**
+   * Owning tenant (org) identifier.
+   */
+  tenantId: string;
+  /**
+   * Tenant-unique data-source identifier.
+   */
+  sourceId: string;
+  connector: DataSourceConnector;
+  /**
+   * Human-readable name shown to admins and builders.
+   */
+  displayName: string;
+  endpoint: DataSourceEndpoint;
+  /**
+   * secretref URI naming the platform-held credential for this source. The referenced value never crosses this boundary.
+   */
+  credentialRef: string;
+  provisioningMode: DataSourceProvisioningMode;
+  /**
+   * Admin-declared selector allowlist (e.g. schema.table patterns) that grant scopes are validated against.
+   */
+  allowedScope: string[];
+  /**
+   * Selectors discovery actually observed on the source. Informational; never widens allowedScope.
+   */
+  observedScope?: string[];
+  /**
+   * Whether builders may request grants against this source.
+   */
+  requestableByBuilders: boolean;
+  status: DataSourceStatus;
+}
+/**
+ * Connector endpoint coordinates. host is always present; database vs project/workspace depends on the connector family.
+ */
+export interface DataSourceEndpoint {
+  /**
+   * Network host (or warehouse endpoint) of the source.
+   */
+  host: string;
+  /**
+   * TCP port; absent where the connector implies it.
+   */
+  port?: number;
+  /**
+   * Database name (postgres/redshift-style connectors).
+   */
+  database?: string;
+  /**
+   * Project identifier (bigquery-style connectors).
+   */
+  project?: string;
+  /**
+   * Workspace identifier (databricks-style connectors).
+   */
+  workspace?: string;
+}

package/gen-ts/deploy-request.ts

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

package/gen-ts/deploy-response.ts

@@ -0,0 +1,25 @@
+/* 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';
+  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,47 @@
+/* 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 './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 './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[];
+}