@fourier-labs/harbour-contracts 0.43.0 → 0.45.0

package/gen-ts/integration-execute-result.ts

@@ -0,0 +1,27 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * The `data` member of a successful execute response `{data, requestId}`; the SDK unwraps `data`. Exactly one of the three operation results: slack.channel.history -> {messages, hasMore} (plain text/IDs/time only, never the provider payload); slack.message.post -> {messageId}; warehouse.view.read -> {rows} (decimal/64-bit values as strings, dates as ISO strings). An unknown send outcome is never a result; it is an error with details.code SEND_OUTCOME_UNKNOWN. Results over 1 MiB are rejected, not truncated.
+ */
+export type IntegrationExecuteResult = {
+  /**
+   * @maxItems 15
+   */
+  messages?: ChannelMessage[];
+  hasMore?: boolean;
+  messageId?: string;
+  /**
+   * @maxItems 1000
+   */
+  rows?: {
+    [k: string]: unknown;
+  }[];
+};
+
+export interface ChannelMessage {
+  id: string;
+  text: string;
+  authorId: string;
+  createdAt: string;
+}

package/gen-ts/kit-bundle-manifest.ts

@@ -0,0 +1,36 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * Digest-pinned image reference <repository>@sha256:<hex>; tags are never accepted.
+ */
+export type ImageDigestReference = string;
+
+/**
+ * Identity of one published development-kit bundle (shipped with the CLI). It pins the app SDK tarball, the local runtime images and the agent-brief fingerprint that a kit-built app was developed against, so the hosted pipeline can prove compatibility before replacing the vendored SDK (see kit-lock.schema.json).
+ */
+export interface KitBundleManifest {
+  schema: 'harbour.kit-bundle/1.0';
+  /**
+   * The CLI package version that published this bundle.
+   */
+  kitVersion: string;
+  sdk: {
+    package: '@harbour/app-sdk';
+    /**
+     * SHA-256 of the SDK tarball baked into this bundle; the CodeBuild gate compares it with the pipeline's own tarball.
+     */
+    tarballSha256: string;
+  };
+  images: {
+    appGateway: ImageDigestReference;
+    sessionFixture: ImageDigestReference;
+  };
+  brief: {
+    /**
+     * SHA-256 of the agent-brief tar, or the literal unknown when the bundle carried no brief.
+     */
+    fingerprint: string;
+  };
+  declarationSchema: 'harbour.app-integrations/2.0';
+}

package/gen-ts/kit-lock.ts

@@ -0,0 +1,48 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * Committed `.harbour/kit.lock.json`: which app and tenant a kit-built app belongs to and the exact bundle it was developed against. The data-plane vendorAppSDK gate reads bundle.sdk.tarballSha256 and fails with kit_bundle_incompatible (naming both digests) when it differs from the baked tarball; apps without a kit.lock keep the existing path.
+ */
+export interface KitLock {
+  schema: 'harbour.kit-lock/1.0';
+  appId: string;
+  tenantId: string;
+  bundle: KitBundleManifest;
+  createdAt: string;
+  updatedAt: string;
+}
+/**
+ * Identity of one published development-kit bundle (shipped with the CLI). It pins the app SDK tarball, the local runtime images and the agent-brief fingerprint that a kit-built app was developed against, so the hosted pipeline can prove compatibility before replacing the vendored SDK (see kit-lock.schema.json).
+ */
+interface KitBundleManifest {
+  schema: 'harbour.kit-bundle/1.0';
+  /**
+   * The CLI package version that published this bundle.
+   */
+  kitVersion: string;
+  sdk: {
+    package: '@harbour/app-sdk';
+    /**
+     * SHA-256 of the SDK tarball baked into this bundle; the CodeBuild gate compares it with the pipeline's own tarball.
+     */
+    tarballSha256: string;
+  };
+  images: {
+    /**
+     * Digest-pinned image reference <repository>@sha256:<hex>; tags are never accepted.
+     */
+    appGateway: string;
+    /**
+     * Digest-pinned image reference <repository>@sha256:<hex>; tags are never accepted.
+     */
+    sessionFixture: string;
+  };
+  brief: {
+    /**
+     * SHA-256 of the agent-brief tar, or the literal unknown when the bundle carried no brief.
+     */
+    fingerprint: string;
+  };
+  declarationSchema: 'harbour.app-integrations/2.0';
+}

package/gen-ts/saas-connection.ts

@@ -0,0 +1,77 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * DISABLED stops every app call immediately (details.code CONNECTION_DISABLED).
+ */
+export type SaasConnectionStatus = 'ACTIVE' | 'DISABLED';
+export type InstallationName = string;
+
+/**
+ * Tenant-wide SaaS connection record (control table sk SAASCONN#<sourceId>, same tenant partition as database sources; alias uniqueness is enforced across both). IT maps each environment to a provider installation and logical channel aliases to channel IDs; apps only ever see the aliases. Contains references, never secrets: the client secret lives in Secrets Manager under clientSecretRef and installation tokens under their own token records.
+ */
+export interface SaasConnection {
+  /**
+   * Tenant-wide logical alias of a connection (governance sourceId) or of a resource under it.
+   */
+  sourceId: string;
+  kind: 'saas';
+  provider: 'slack';
+  displayName: string;
+  status: SaasConnectionStatus;
+  /**
+   * Optimistic-concurrency version; every write is conditional on it.
+   */
+  version: number;
+  clientId: string;
+  /**
+   * secretref://tenant/{tenantId}/saas/{sourceId}/client
+   */
+  clientSecretRef?: string;
+  environments: {
+    development?: SaasEnvironmentMapping;
+    preview?: SaasEnvironmentMapping;
+    production?: SaasEnvironmentMapping;
+  };
+  /**
+   * Operations IT allows apps to request on this connection.
+   *
+   * @minItems 1
+   * @maxItems 2
+   */
+  operations: ('slack.channel.history' | 'slack.message.post')[];
+  developmentPreapproval: DevelopmentPreapproval;
+  /**
+   * Provider installations keyed by the installation name environments point at.
+   */
+  installations?: {
+    [k: string]: SaasInstallation;
+  };
+  createdAt?: string;
+  updatedAt?: string;
+}
+export interface SaasEnvironmentMapping {
+  installation: InstallationName;
+  channels: {
+    /**
+     * Provider channel ID; only public, non-archived channels are valid.
+     */
+    [k: string]: string;
+  };
+}
+export interface DevelopmentPreapproval {
+  /**
+   * Auto-approve development requests within the allowlist.
+   */
+  enabled: boolean;
+  /**
+   * Development grant duration; default 24.
+   */
+  hours: number;
+}
+export interface SaasInstallation {
+  tokenRecordId: string;
+  workspaceId: string;
+  botUserId: string;
+  status: 'ACTIVE' | 'RECONNECT_REQUIRED' | 'REVOKED';
+}

package/gen-ts/transform-parked-result.ts

@@ -0,0 +1,18 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * Discriminated result returned by sequential preview after it has durably checkpointed settled transformation work and must stop for builder input. It is not a successful transformation report.
+ */
+export interface TransformParkedResult {
+  outcome: 'parked';
+  requestId: string;
+  checkpoint: {
+    schema: 'harbour.transform-checkpoint/1.0';
+    key: string;
+    sha256: string;
+  };
+  answerRevision: number;
+  remainingActiveMs: number;
+  outstandingWork: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour-contracts",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "description": "Single source of truth for every data shape that crosses a boundary between Harbour components.",
   "license": "UNLICENSED",
   "private": false,

package/schema/app-integrations-declaration.schema.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/app-integrations-declaration.schema.json",
+  "title": "AppIntegrationsDeclaration",
+  "description": "Committed `.harbour/integrations.json`: the app's declared use of tenant-wide integration connections. Keys are logical connection aliases (the governance sourceId); resources are logical names (Slack channel alias, warehouse view name), never IDs, tokens or URLs. The operation set is closed (three operations) and each operation carries a fixed identity mode: slack.channel.history=user, slack.message.post=app, warehouse.view.read=app. A `saas` connection may declare only the Slack operations and a `database` connection only warehouse.view.read. This file also owns the shared IntegrationOperation / IntegrationIdentityMode / IntegrationEnvironment / IntegrationConnectionKind enums referenced by the other integration schemas.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "connections"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.app-integrations/2.0" },
+    "connections": {
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 32,
+      "propertyNames": { "$ref": "#/definitions/IntegrationAlias" },
+      "additionalProperties": { "$ref": "#/definitions/DeclaredConnection" }
+    }
+  },
+  "definitions": {
+    "IntegrationAlias": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_-]{0,62}$",
+      "description": "Tenant-wide logical alias of a connection (governance sourceId) or of a resource under it."
+    },
+    "IntegrationConnectionKind": { "type": "string", "enum": ["saas", "database"] },
+    "IntegrationOperation": {
+      "type": "string",
+      "enum": ["slack.channel.history", "slack.message.post", "warehouse.view.read"],
+      "description": "Closed operation set. Extending it is a contracts change."
+    },
+    "IntegrationIdentityMode": {
+      "type": "string",
+      "enum": ["app", "user"],
+      "description": "Whose authority an operation runs under. Fixed per operation; callers never choose it."
+    },
+    "IntegrationEnvironment": {
+      "type": "string",
+      "enum": ["development", "preview", "production"],
+      "description": "development is the CLI/local kit; preview and production are hosted."
+    },
+    "ResourceNames": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 64,
+      "items": { "$ref": "#/definitions/IntegrationAlias" }
+    },
+    "ViewResource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["columns"],
+      "properties": {
+        "columns": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$" }
+        }
+      }
+    },
+    "UserModeChannelOperation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["identity", "resources"],
+      "properties": {
+        "identity": { "type": "string", "const": "user" },
+        "resources": { "$ref": "#/definitions/ResourceNames" }
+      }
+    },
+    "AppModeChannelOperation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["identity", "resources"],
+      "properties": {
+        "identity": { "type": "string", "const": "app" },
+        "resources": { "$ref": "#/definitions/ResourceNames" }
+      }
+    },
+    "AppModeViewOperation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["identity", "resources"],
+      "properties": {
+        "identity": { "type": "string", "const": "app" },
+        "resources": {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 64,
+          "propertyNames": { "$ref": "#/definitions/IntegrationAlias" },
+          "additionalProperties": { "$ref": "#/definitions/ViewResource" }
+        }
+      }
+    },
+    "DeclaredConnection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "operations"],
+      "properties": {
+        "kind": { "$ref": "#/definitions/IntegrationConnectionKind" },
+        "operations": {
+          "type": "object",
+          "additionalProperties": false,
+          "minProperties": 1,
+          "properties": {
+            "slack.channel.history": { "$ref": "#/definitions/UserModeChannelOperation" },
+            "slack.message.post": { "$ref": "#/definitions/AppModeChannelOperation" },
+            "warehouse.view.read": { "$ref": "#/definitions/AppModeViewOperation" }
+          }
+        }
+      },
+      "if": { "properties": { "kind": { "const": "saas" } } },
+      "then": { "properties": { "operations": { "not": { "required": ["warehouse.view.read"] } } } },
+      "else": {
+        "properties": {
+          "operations": {
+            "not": { "anyOf": [{ "required": ["slack.channel.history"] }, { "required": ["slack.message.post"] }] }
+          }
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "schema": "harbour.app-integrations/2.0",
+      "connections": {
+        "company-slack": {
+          "kind": "saas",
+          "operations": {
+            "slack.channel.history": { "identity": "user", "resources": ["team-updates"] },
+            "slack.message.post": { "identity": "app", "resources": ["team-updates"] }
+          }
+        },
+        "sales-warehouse": {
+          "kind": "database",
+          "operations": {
+            "warehouse.view.read": {
+              "identity": "app",
+              "resources": { "weekly_sales": { "columns": ["week", "total"] } }
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/schema/builder-input-proposal.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/builder-input-proposal.schema.json",
+  "title": "BuilderInputProposal",
+  "description": "Bounded, value-free proposal emitted when sequential preview transformation cannot continue without builder-owned input. The deployment control plane remains authoritative and applies eligibility checks before exposing it.",
+  "x-go-embed": true,
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["outcome", "summary", "outstandingWork", "questions"],
+  "properties": {
+    "outcome": { "const": "needs_input" },
+    "summary": { "type": "string", "minLength": 1, "maxLength": 500 },
+    "outstandingWork": { "type": "string", "minLength": 1, "maxLength": 2000 },
+    "questions": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 5,
+      "items": { "$ref": "#/definitions/BuilderInputQuestion" }
+    }
+  },
+  "definitions": {
+    "BuilderInputQuestion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "prompt", "whyNeeded", "effect", "evidence"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" },
+        "kind": { "type": "string", "enum": ["secret", "text", "choice"] },
+        "format": { "type": "string", "enum": ["plain", "email", "url", "integer"] },
+        "prompt": { "type": "string", "minLength": 1, "maxLength": 300 },
+        "whyNeeded": { "type": "string", "minLength": 1, "maxLength": 500 },
+        "effect": { "type": "string", "minLength": 1, "maxLength": 500 },
+        "secretName": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,254}$" },
+        "options": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 5,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1, "maxLength": 200 }
+        },
+        "evidence": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 8,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "finding"],
+            "properties": {
+              "path": { "type": "string", "minLength": 1, "maxLength": 512 },
+              "line": { "type": "integer", "minimum": 1 },
+              "finding": { "type": "string", "minLength": 1, "maxLength": 500 }
+            }
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "kind": { "const": "secret" } } },
+          "then": { "required": ["secretName"], "not": { "required": ["options"] } }
+        },
+        {
+          "if": { "properties": { "kind": { "const": "choice" } } },
+          "then": { "required": ["options"], "not": { "required": ["secretName"] } }
+        },
+        {
+          "if": { "properties": { "kind": { "const": "text" } } },
+          "then": { "not": { "anyOf": [{ "required": ["secretName"] }, { "required": ["options"] }] } }
+        }
+      ]
+    }
+  }
+}

package/schema/data-grant-v2.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/data-grant-v2.schema.json",
+  "title": "DataGrantV2",
+  "description": "An app's integration grant for one connection, environment and identity mode (control table sk APP#<appId>#IGRANT#<environment>#<sourceId>#<mode>; grantId = base64url(JSON [\"v2\",appId,environment,sourceId,mode])). Additive to the legacy DataGrant (data-grant.schema.json), which is never consulted by v2 paths. Expiry is enforced from UTC time on every call and SDK calls never extend it. Status edges live in x-transitions; DENIED and REVOKED are terminal (a regrant after revocation is a new REQUESTED record once cleanup is DONE). Database grants add credentialRef/mintedPrincipal, SaaS grants add installation; both hold references only.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "appId", "sourceId", "kind", "environment", "identityMode", "status", "operations", "resources", "version", "provisioning"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.data-grant/2.0" },
+    "appId": { "type": "string", "minLength": 1, "maxLength": 255 },
+    "sourceId": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
+    "kind": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationConnectionKind" },
+    "environment": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationEnvironment" },
+    "identityMode": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationIdentityMode" },
+    "status": { "$ref": "#/definitions/DataGrantV2Status" },
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 3,
+      "uniqueItems": true,
+      "items": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationOperation" },
+      "description": "Approved operations; each must match this grant's identityMode."
+    },
+    "resources": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 64,
+      "uniqueItems": true,
+      "items": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
+      "description": "Approved logical resource names (channel aliases or view names). Never inherited by wildcard."
+    },
+    "expiresAt": { "type": "string", "format": "date-time", "description": "Absent only for explicitly approved ongoing production access." },
+    "approvedBy": { "type": "string", "minLength": 1, "maxLength": 255 },
+    "version": { "type": "integer", "minimum": 1, "description": "Optimistic-concurrency version; approvals compare it with the reviewed value." },
+    "pendingRequestId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The one open access request attached to this grant, if any." },
+    "provisioning": { "$ref": "#/definitions/DataGrantV2Provisioning" },
+    "credentialRef": {
+      "type": "string",
+      "pattern": "^secretref://[A-Za-z0-9][A-Za-z0-9/_.:-]*$",
+      "description": "Database grants: secretref://tenant/{t}/app/{a}/env/{env}/source/{s}."
+    },
+    "mintedPrincipal": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Database grants: the deterministic per tenant/app/environment/source principal." },
+    "installation": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,62}$", "description": "SaaS grants: the connection installation this environment maps to." }
+  },
+  "definitions": {
+    "DataGrantV2Status": {
+      "type": "string",
+      "enum": ["REQUESTED", "GRANTED", "DENIED", "REVOKED"],
+      "description": "Grant lifecycle state. Legal edges live in x-transitions; DENIED and REVOKED are terminal."
+    },
+    "DataGrantV2ProvisioningStatus": {
+      "type": "string",
+      "enum": ["NONE", "PENDING", "FAILED", "DONE"],
+      "description": "Provider-side work for the current approved scope (credential mint, cleanup, installation check)."
+    },
+    "DataGrantV2Provisioning": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "attempts"],
+      "properties": {
+        "status": { "$ref": "#/definitions/DataGrantV2ProvisioningStatus" },
+        "attempts": { "type": "integer", "minimum": 0, "maximum": 3, "description": "Failed attempts; three requires an admin retry." },
+        "lastError": { "type": "string", "maxLength": 500, "description": "Sanitized reason; never a provider error body." }
+      }
+    }
+  },
+  "x-status-definition": "DataGrantV2Status",
+  "x-terminal": ["DENIED", "REVOKED"],
+  "x-transitions": [
+    { "from": "REQUESTED", "to": "GRANTED", "trigger": "approval published conditionally after provisioning verified (or auto-approved within development preapproval)" },
+    { "from": "REQUESTED", "to": "DENIED", "trigger": "admin denies the request" },
+    { "from": "GRANTED", "to": "REVOKED", "trigger": "admin revokes; Isomorph access is cut first, provider cleanup follows" }
+  ],
+  "examples": [
+    {
+      "schema": "harbour.data-grant/2.0",
+      "appId": "app-1f2e3d4c",
+      "sourceId": "company-slack",
+      "kind": "saas",
+      "environment": "development",
+      "identityMode": "user",
+      "status": "GRANTED",
+      "operations": ["slack.channel.history"],
+      "resources": ["team-updates"],
+      "expiresAt": "2026-09-10T08:00:00Z",
+      "approvedBy": "policy:development-preapproval",
+      "version": 2,
+      "provisioning": { "status": "DONE", "attempts": 0 },
+      "installation": "nonprod"
+    },
+    {
+      "schema": "harbour.data-grant/2.0",
+      "appId": "app-1f2e3d4c",
+      "sourceId": "sales-warehouse",
+      "kind": "database",
+      "environment": "preview",
+      "identityMode": "app",
+      "status": "REQUESTED",
+      "operations": ["warehouse.view.read"],
+      "resources": ["weekly_sales"],
+      "expiresAt": "2026-09-16T08:00:00Z",
+      "version": 1,
+      "pendingRequestId": "req_9a8b7c6d",
+      "provisioning": { "status": "PENDING", "attempts": 1, "lastError": "credential verification timed out" }
+    }
+  ]
+}

package/schema/deployment-continuation.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/deployment-continuation.schema.json",
+  "title": "DeploymentContinuation",
+  "description": "Internal immutable reference admitting one child deployment from a parked sequential-preview input request. It contains references and accepted non-secret answers, never credential values.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["resumeFrom"],
+  "properties": {
+    "resumeFrom": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["parentVersionId", "requestId", "checkpointKey", "checkpointSha256", "answerRevision", "answers"],
+      "properties": {
+        "parentVersionId": { "type": "string", "pattern": "^[^#]+#[^#]+#preview#[0-9]{6,}$" },
+        "requestId": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "checkpointKey": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "checkpointSha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+        "answerRevision": { "type": "integer", "minimum": 1 },
+        "answers": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 5,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["questionId"],
+            "properties": {
+              "questionId": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" },
+              "value": { "type": "string", "maxLength": 2000 },
+              "secretRef": { "type": "string", "pattern": "^secretref://[A-Za-z0-9][A-Za-z0-9/_.:-]*$" }
+            },
+            "oneOf": [{ "required": ["value"] }, { "required": ["secretRef"] }]
+          }
+        }
+      }
+    }
+  }
+}

package/schema/deployment-status-response.schema.json

@@ -25,7 +25,7 @@
     },
     "status": {
       "type": "string",
-      "enum": ["QUEUED", "ANALYZING", "TRANSFORMING", "VALIDATING", "BUILDING", "VERIFYING", "GATING", "LIVE", "AWAITING-PROMOTION", "PROMOTING", "FAILED", "STALE"]
+      "enum": ["QUEUED", "ANALYZING", "TRANSFORMING", "WAITING_INPUT", "VALIDATING", "BUILDING", "VERIFYING", "GATING", "LIVE", "AWAITING-PROMOTION", "PROMOTING", "FAILED", "STALE"]
     },
     "message": {
       "type": "string",
@@ -66,9 +66,58 @@
     },
     "deployTarget": {
       "$ref": "#/definitions/StatusDeployTarget"
+    },
+    "pendingInput": {
+      "$ref": "#/definitions/StatusPendingInput"
     }
   },
   "definitions": {
+    "StatusPendingInput": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["requestId", "revision", "questions", "waitMode", "createdAt"],
+      "properties": {
+        "requestId": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "revision": { "type": "integer", "minimum": 0 },
+        "questions": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 5,
+          "items": { "$ref": "#/definitions/StatusInputQuestion" }
+        },
+        "waitMode": { "type": "string", "enum": ["active", "parking", "parked"] },
+        "warmUntil": { "type": "string", "format": "date-time" },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "continuationVersionId": { "type": "string", "pattern": "^[^#]+#[^#]+#preview#[0-9]{6,}$" },
+        "statusUrl": { "type": "string", "pattern": "^/v1/tenants/[^/]+/apps/[^/]+/deployments/[^/]+$" }
+      }
+    },
+    "StatusInputQuestion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "prompt", "whyNeeded", "effect"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" },
+        "kind": { "type": "string", "enum": ["secret", "text", "choice"] },
+        "format": { "type": "string", "enum": ["plain", "email", "url", "integer"] },
+        "prompt": { "type": "string", "minLength": 1, "maxLength": 300 },
+        "whyNeeded": { "type": "string", "minLength": 1, "maxLength": 500 },
+        "effect": { "type": "string", "minLength": 1, "maxLength": 500 },
+        "secretName": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,254}$" },
+        "options": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 5,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1, "maxLength": 200 }
+        }
+      },
+      "allOf": [
+        { "if": { "properties": { "kind": { "const": "secret" } } }, "then": { "required": ["secretName"], "not": { "required": ["options"] } } },
+        { "if": { "properties": { "kind": { "const": "choice" } } }, "then": { "required": ["options"], "not": { "required": ["secretName"] } } },
+        { "if": { "properties": { "kind": { "const": "text" } } }, "then": { "not": { "anyOf": [{ "required": ["secretName"] }, { "required": ["options"] }] } } }
+      ]
+    },
     "StatusDeployTarget": {
       "type": "object",
       "additionalProperties": false,