@fourier-labs/harbour-contracts 0.69.0 → 0.71.0

package/dist/gen-ts/saas-connection.d.ts

@@ -1,5 +1,5 @@
 /**
- * Slack carries an installation and a channel map; Gmail is user-consent only and read-only.
+ * Slack carries an installation and a channel map; Gmail is user-consent only.
  */
 export type SaasProvider = 'slack' | 'gmail';
 /**
@@ -7,6 +7,18 @@ export type SaasProvider = 'slack' | 'gmail';
  */
 export type SaasConnectionStatus = 'ACTIVE' | 'DISABLED';
 export type SaasInstallationStatus = 'installed' | 'reconnect_required' | 'revoked';
+/**
+ * How a user-mode access request on this connection is approved (0.71.0): automatic — the person's own consent is the approval, since the app only ever acts as them; it — an IT admin reviews it like an app-mode request. Absent means it.
+ */
+export type UserModeApproval = 'automatic' | 'it';
+/**
+ * signed_in_person — only the person using the app; channel_members — the members of the named channel; anyone — any workspace member.
+ */
+export type DirectMessageAudience = 'signed_in_person' | 'channel_members' | 'anyone';
+/**
+ * block — every recipient must be internal (the default when absent); allowlist — internal or in `allowedDomains`; allow — any address.
+ */
+export type ExternalRecipientMode = 'block' | 'allowlist' | 'allow';
 /**
  */
 export type InstallationName = string;
@@ -39,13 +51,17 @@ export interface SaasConnection {
         [k: string]: string;
     };
     /**
-     * Operations IT allows apps to request on this connection: the provider's own SaaS operations (Slack: slack.channel.history, slack.message.post; Gmail: gmail.thread.list, gmail.message.read, gmail.message.send). Never warehouse.view.read.
+     * Operations IT allows apps to request on this connection: the provider's own SaaS operations (Slack: slack.channel.history, slack.message.post, slack.message.update, slack.message.delete, slack.dm.send, slack.user.lookup; Gmail: gmail.thread.list, gmail.thread.read, gmail.message.read, gmail.message.send, gmail.attachment.read). Never warehouse.view.read.
      *
      * @minItems 1
-     * @maxItems 5
+     * @maxItems 11
      */
-    operations: ('slack.channel.history' | 'slack.message.post' | 'gmail.thread.list' | 'gmail.message.read' | 'gmail.message.send' | 'warehouse.view.read')[];
+    operations: ('slack.channel.history' | 'slack.message.post' | 'slack.message.update' | 'slack.message.delete' | 'slack.dm.send' | 'slack.user.lookup' | 'gmail.thread.list' | 'gmail.thread.read' | 'gmail.message.read' | 'gmail.message.send' | 'gmail.attachment.read' | 'warehouse.view.read')[];
     developmentPreapproval: DevelopmentPreapproval;
+    oauthClient?: SaasOauthClient;
+    userModeApproval?: UserModeApproval;
+    directMessages?: DirectMessagePolicy;
+    externalRecipients?: ExternalRecipientPolicy;
     /**
      * Lower-cased builder emails excluded from development preapproval.
      *
@@ -114,6 +130,48 @@ export interface DevelopmentPreapproval {
      */
     hours: number;
 }
+/**
+ * The tenant's own OAuth client for this provider (0.71.0; the ADR 0068 follow-up): when present, installation and user consent run through the company's Slack app or Google Cloud project instead of the platform-owned one, so the tenant's IT sees and controls the app in their own admin console. A reference to the secret, never the secret.
+ */
+export interface SaasOauthClient {
+    clientId: string;
+    /**
+     * Where the client secret lives.
+     */
+    secretRef: string;
+    setAt: string;
+    /**
+     * The IT admin who saved it (lower-cased email).
+     */
+    setBy: string;
+}
+/**
+ * Whom an app may direct-message through slack.dm.send (0.71.0), set by IT on the connection and enforced by governance on every send.
+ */
+export interface DirectMessagePolicy {
+    allowed: DirectMessageAudience;
+    /**
+     * Tenant-wide logical alias of a connection (governance sourceId) or of a resource under it.
+     */
+    channel?: string;
+    /**
+     * Distinct recipients one app may message per UTC day on this connection; the cap refuses the send that would exceed it.
+     */
+    dailyRecipientCap: number;
+}
+/**
+ * Whether a gmail.message.send may address people outside the company (0.71.0). An external recipient is one whose email domain is not one of the tenant's verified domains.
+ */
+export interface ExternalRecipientPolicy {
+    mode: ExternalRecipientMode;
+    /**
+     * allowlist only: the external domains a send may address; a recipient's domain must equal one of them.
+     *
+     * @minItems 1
+     * @maxItems 50
+     */
+    allowedDomains?: string[];
+}
 /**
  * @deprecated
  */

package/gen-ts/app-integrations-declaration.ts

@@ -2,6 +2,10 @@
 // Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
 
 export type IntegrationConnectionKind = 'saas' | 'database';
+/**
+ * Whose authority an operation runs under. Fixed per operation, except the declared-mode Slack operations (slack.message.post; since 0.71.0 also slack.channel.history, slack.message.update, slack.message.delete): declared per app for the access request, and named per call among the app's approved modes (execute request `mode`, 0.55.0).
+ */
+export type IntegrationIdentityMode = 'app' | 'user';
 /**
  * Tenant-wide logical alias of a connection (governance sourceId) or of a resource under it.
  */
@@ -11,17 +15,13 @@ export type IntegrationAlias = string;
  * @maxItems 64
  */
 export type ResourceNames = IntegrationAlias[];
-/**
- * Whose authority an operation runs under. Fixed per operation, except slack.message.post: declared per app for the access request, and named per call among the app's approved modes (execute request `mode`, 0.55.0).
- */
-export type IntegrationIdentityMode = 'app' | 'user';
 /**
  * A plain warehouse column identifier, or `*` as the sole selection when IT exposed all current and future columns.
  */
 export type ColumnName = string;
 
 /**
- * Committed `.isomorph/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 (six operations). Each operation carries a fixed identity mode — slack.channel.history=user, gmail.thread.list=user, gmail.message.read=user, gmail.message.send=user, warehouse.view.read=app — except slack.message.post, whose mode the app DECLARES: `app` posts as the company's Slack app (the one audited bot identity, under the IT-approved per-app display name when the connection declares `presentation`), `user` posts as the signed-in person after their own consent. The declared mode is the one the app requests access for; an app may hold approved grants for both modes after two requests, and each slack.message.post call names which approved mode it runs under (`mode` on the execute request, 0.55.0) — a mode IT did not approve is refused, never swapped for the other. A `saas` connection may declare only the Slack and Gmail operations and a `database` connection only warehouse.view.read; `presentation` is a `saas` connection's optional per-app display name and icon for app-mode Slack posts, shown to IT at approval time and applied only from the approved grant. Gmail is user-mode only (reads plus one send); its single resource is the fixed `inbox` alias. This file also owns the shared IntegrationOperation / IntegrationIdentityMode / IntegrationEnvironment / IntegrationConnectionKind / IntegrationPresentation definitions referenced by the other integration schemas.
+ * Committed `.isomorph/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 (twelve operations since 0.71.0, ADR 0018). Each operation carries a fixed identity mode — slack.dm.send=app, slack.user.lookup=app, every gmail.* operation=user, warehouse.view.read=app — except the declared-mode Slack operations (slack.message.post, and since 0.71.0 slack.channel.history, slack.message.update and slack.message.delete), whose mode the app DECLARES: `app` acts as the company's Slack app (the one audited bot identity; a post goes out under the IT-approved per-app display name when the connection declares `presentation`), `user` acts as the signed-in person after their own consent (reads what they can read, edits what they wrote). The declared mode is the one the app requests access for; an app may hold approved grants for both modes after two requests, and each declared-mode call names which approved mode it runs under (`mode` on the execute request, 0.55.0) — a mode IT did not approve is refused, never swapped for the other. A `saas` connection may declare only the Slack and Gmail operations and a `database` connection only warehouse.view.read; `presentation` is a `saas` connection's optional per-app display name and icon for app-mode Slack posts, shown to IT at approval time and applied only from the approved grant. Gmail is user-mode only (reads, one send); its single resource is the fixed `inbox` alias. slack.dm.send and slack.user.lookup address people by email rather than a channel, so their single resource is the fixed `workspace` alias (the connection's installed workspace), the way Gmail's is `inbox`. This file also owns the shared IntegrationOperation / IntegrationIdentityMode / IntegrationEnvironment / IntegrationConnectionKind / IntegrationPresentation definitions referenced by the other integration schemas.
  */
 export interface AppIntegrationsDeclaration {
   schema: 'isomorph.app-integrations/2.0';
@@ -33,11 +33,17 @@ export interface DeclaredConnection {
   kind: IntegrationConnectionKind;
   presentation?: IntegrationPresentation;
   operations: {
-    'slack.channel.history'?: UserModeChannelOperation;
+    'slack.channel.history'?: DeclaredModeChannelOperation;
     'slack.message.post'?: DeclaredModeChannelOperation;
+    'slack.message.update'?: DeclaredModeChannelOperation;
+    'slack.message.delete'?: DeclaredModeChannelOperation;
+    'slack.dm.send'?: AppModeChannelOperation;
+    'slack.user.lookup'?: AppModeChannelOperation;
     'gmail.thread.list'?: UserModeChannelOperation;
+    'gmail.thread.read'?: UserModeChannelOperation;
     'gmail.message.read'?: UserModeChannelOperation;
     'gmail.message.send'?: UserModeChannelOperation;
+    'gmail.attachment.read'?: UserModeChannelOperation;
     'warehouse.view.read'?: AppModeViewOperation;
   };
 }
@@ -54,17 +60,24 @@ export interface IntegrationPresentation {
    */
   iconEmoji?: string;
 }
-export interface UserModeChannelOperation {
-  identity: 'user';
-  resources: ResourceNames;
-}
 /**
- * slack.message.post: the app declares the mode — app (posts as the company's Slack app) or user (posts as the signed-in person).
+ * slack.message.post, slack.channel.history, slack.message.update, slack.message.delete: the app declares the mode — app (acts as the company's Slack app) or user (acts as the signed-in person).
  */
 export interface DeclaredModeChannelOperation {
   identity: IntegrationIdentityMode;
   resources: ResourceNames;
 }
+/**
+ * slack.dm.send, slack.user.lookup (0.71.0): app mode only — the company's Slack app messages people or resolves them by email; the resource is the fixed `workspace` alias.
+ */
+export interface AppModeChannelOperation {
+  identity: 'app';
+  resources: ResourceNames;
+}
+export interface UserModeChannelOperation {
+  identity: 'user';
+  resources: ResourceNames;
+}
 export interface AppModeViewOperation {
   identity: 'app';
   resources: {

package/gen-ts/contract-release.ts

@@ -1,10 +1,10 @@
 /* eslint-disable */
 // Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
 
-export const ContractRepositoryVersion = "0.69.0.0" as const;
-export const ContractPublishVersion = "0.69.0" as const;
-export const ContractPublishTag = "v0.69.0" as const;
-export const ContractSchemasDigest = "sha256:e21f310517adb289db8b8233fd3c742a711fed8226892591f6581afb8510e30c" as const;
+export const ContractRepositoryVersion = "0.71.0.0" as const;
+export const ContractPublishVersion = "0.71.0" as const;
+export const ContractPublishTag = "v0.71.0" as const;
+export const ContractSchemasDigest = "sha256:25c5de2ee9586c6280dca7c733a7063f46bd5d400112fe60f928cf6db1a627c3" as const;
 export const ContractAiFixturesDigest = "sha256:edac31c92e146ca1c40130f2fb5649db82e24b8cd1ac758153b90612052fddb6" as const;
-export const ContractGeneratedGoDigest = "sha256:1f793a0d039976e5a9b65a72753928ab68de66d6878c96a6ea242e48a16ca24e" as const;
-export const ContractGeneratedTypeScriptDigest = "sha256:6bdb0271dae8bf7df75f72e61addda29ebb778a054b59c8538d05112000ac0e4" as const;
+export const ContractGeneratedGoDigest = "sha256:09bd95f079e733af9bf594a157d7396a645cc6c9866d48b7aee6b00a9762ac62" as const;
+export const ContractGeneratedTypeScriptDigest = "sha256:7fa5c1e4d8fdb68855b5e10208ee6c0a210f3595f7e74174efbf6bfa4c3673ce" as const;

package/gen-ts/data-grant-v2.ts

@@ -27,22 +27,28 @@ export interface DataGrantV2 {
    */
   sourceId: string;
   /**
-   * Whose authority an operation runs under. Fixed per operation, except slack.message.post: declared per app for the access request, and named per call among the app's approved modes (execute request `mode`, 0.55.0).
+   * Whose authority an operation runs under. Fixed per operation, except the declared-mode Slack operations (slack.message.post; since 0.71.0 also slack.channel.history, slack.message.update, slack.message.delete): declared per app for the access request, and named per call among the app's approved modes (execute request `mode`, 0.55.0).
    */
   mode: 'app' | 'user';
   kind: 'saas' | 'database';
   status: DataGrantV2Status;
   /**
-   * Approved operations; each must match this grant's mode. Empty until the first approval.
+   * Approved operations; each must match this grant's mode. Empty until the first approval. At most the eleven SaaS operations (0.71.0); a database grant holds one.
    *
-   * @maxItems 5
+   * @maxItems 11
    */
   operations: (
     | 'slack.channel.history'
     | 'slack.message.post'
+    | 'slack.message.update'
+    | 'slack.message.delete'
+    | 'slack.dm.send'
+    | 'slack.user.lookup'
     | 'gmail.thread.list'
+    | 'gmail.thread.read'
     | 'gmail.message.read'
     | 'gmail.message.send'
+    | 'gmail.attachment.read'
     | 'warehouse.view.read'
   )[];
   /**
@@ -83,7 +89,7 @@ export interface DataGrantV2 {
   updatedAt: string;
   /**
    * @deprecated
-   * Whose authority an operation runs under. Fixed per operation, except slack.message.post: declared per app for the access request, and named per call among the app's approved modes (execute request `mode`, 0.55.0).
+   * Whose authority an operation runs under. Fixed per operation, except the declared-mode Slack operations (slack.message.post; since 0.71.0 also slack.channel.history, slack.message.update, slack.message.delete): declared per app for the access request, and named per call among the app's approved modes (execute request `mode`, 0.55.0).
    */
   identityMode?: 'app' | 'user';
   /**

package/gen-ts/integration-execute-input-rules.ts

@@ -11,7 +11,13 @@
 export type IntegrationExecuteInputFieldRule =
   | { kind: 'integer'; required: boolean; minimum: number; maximum: number; default?: number }
   | { kind: 'string'; required: boolean; minLength: number; maxLength?: number; pattern?: string }
-  | { kind: 'string[]'; required: boolean; minItems: number; maxItems: number; uniqueItems: boolean; item: { minLength: number; maxLength?: number; pattern?: string } };
+  | { kind: 'string[]'; required: boolean; minItems: number; maxItems: number; uniqueItems: boolean; item: { minLength: number; maxLength?: number; pattern?: string }; default?: readonly string[] }
+  | { kind: 'enum'; required: boolean; values: readonly string[]; default?: string }
+  | { kind: 'object[]'; required: boolean; minItems: number; maxItems: number; fields: Readonly<Record<string, IntegrationExecuteInputFieldRule>> }
+  | { kind: 'value'; required: boolean; types: readonly IntegrationExecuteInputValueType[]; maxLength?: number; list?: { minItems: number; maxItems: number; types: readonly IntegrationExecuteInputValueType[] } };
+
+/** The scalar types a `value` input accepts, alone or in its list form. */
+export type IntegrationExecuteInputValueType = 'string' | 'number' | 'boolean';
 
 export type IntegrationExecuteOperationRule = { idempotencyKey: boolean; fields: Record<string, IntegrationExecuteInputFieldRule> };
 
@@ -19,25 +25,67 @@ export const IntegrationExecuteInputRules = {
   "slack.channel.history": {
     idempotencyKey: false,
     fields: {
-      limit: { kind: "integer", required: false, minimum: 1, maximum: 15, default: 15 },
+      limit: { kind: "integer", required: false, minimum: 1, maximum: 100, default: 15 },
+      cursor: { kind: "string", required: false, minLength: 1, maxLength: 256 },
+      oldest: { kind: "string", required: false, minLength: 1, maxLength: 64 },
+      latest: { kind: "string", required: false, minLength: 1, maxLength: 64 },
     },
   },
   "slack.message.post": {
     idempotencyKey: true,
     fields: {
       text: { kind: "string", required: true, minLength: 1, maxLength: 4000 },
+      threadId: { kind: "string", required: false, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
+      format: { kind: "enum", required: false, values: ["plain", "mrkdwn"], default: "plain" },
+    },
+  },
+  "slack.message.update": {
+    idempotencyKey: false,
+    fields: {
+      messageId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
+      text: { kind: "string", required: true, minLength: 1, maxLength: 4000 },
+      format: { kind: "enum", required: false, values: ["plain", "mrkdwn"], default: "plain" },
+    },
+  },
+  "slack.message.delete": {
+    idempotencyKey: false,
+    fields: {
+      messageId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
+    },
+  },
+  "slack.dm.send": {
+    idempotencyKey: true,
+    fields: {
+      to: { kind: "string[]", required: true, minItems: 1, maxItems: 8, uniqueItems: true, item: { minLength: 3, maxLength: 254, pattern: "^[^\\s@<>,;\"]+@[^\\s@<>,;\"]+\\.[^\\s@<>,;\"]+$" } },
+      text: { kind: "string", required: true, minLength: 1, maxLength: 4000 },
+      format: { kind: "enum", required: false, values: ["plain", "mrkdwn"], default: "plain" },
+    },
+  },
+  "slack.user.lookup": {
+    idempotencyKey: false,
+    fields: {
+      email: { kind: "string", required: true, minLength: 3, maxLength: 254, pattern: "^[^\\s@<>,;\"]+@[^\\s@<>,;\"]+\\.[^\\s@<>,;\"]+$" },
     },
   },
   "gmail.thread.list": {
     idempotencyKey: false,
     fields: {
-      limit: { kind: "integer", required: false, minimum: 1, maximum: 15, default: 15 },
+      limit: { kind: "integer", required: false, minimum: 1, maximum: 50, default: 15 },
+      q: { kind: "string", required: false, minLength: 1, maxLength: 256 },
+      labelIds: { kind: "string[]", required: false, minItems: 1, maxItems: 5, uniqueItems: true, item: { minLength: 1, maxLength: 64 }, default: ["INBOX"] },
+      pageToken: { kind: "string", required: false, minLength: 1, maxLength: 256 },
+    },
+  },
+  "gmail.thread.read": {
+    idempotencyKey: false,
+    fields: {
+      threadId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
     },
   },
   "gmail.message.read": {
     idempotencyKey: false,
     fields: {
-      messageId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9_-]{1,64}$" },
+      messageId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
     },
   },
   "gmail.message.send": {
@@ -48,13 +96,41 @@ export const IntegrationExecuteInputRules = {
       bcc: { kind: "string[]", required: false, minItems: 1, maxItems: 50, uniqueItems: true, item: { minLength: 3, maxLength: 254, pattern: "^[^\\s@<>,;\"]+@[^\\s@<>,;\"]+\\.[^\\s@<>,;\"]+$" } },
       subject: { kind: "string", required: true, minLength: 1, maxLength: 256 },
       text: { kind: "string", required: true, minLength: 1, maxLength: 4000 },
+      html: { kind: "string", required: false, minLength: 1, maxLength: 65536 },
+      attachments: { kind: "object[]", required: false, minItems: 1, maxItems: 5, fields: {
+        filename: { kind: "string", required: true, minLength: 1, maxLength: 255 },
+        contentType: { kind: "string", required: true, minLength: 1, maxLength: 128 },
+        dataBase64: { kind: "string", required: true, minLength: 1, maxLength: 2796203 },
+      } },
       replyToMessageId: { kind: "string", required: false, minLength: 0, pattern: "^[A-Za-z0-9_-]{1,64}$" },
     },
   },
+  "gmail.attachment.read": {
+    idempotencyKey: false,
+    fields: {
+      messageId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
+      attachmentId: { kind: "string", required: true, minLength: 1, maxLength: 512 },
+    },
+  },
   "warehouse.view.read": {
     idempotencyKey: false,
     fields: {
-      columns: { kind: "string[]", required: true, minItems: 1, maxItems: 32, uniqueItems: false, item: { minLength: 0, pattern: "^(?:\\*|[A-Za-z_][A-Za-z0-9_]{0,62})$" } },
+      columns: { kind: "string[]", required: false, minItems: 1, maxItems: 32, uniqueItems: false, item: { minLength: 0, pattern: "^(?:\\*|[A-Za-z_][A-Za-z0-9_]{0,62})$" } },
+      where: { kind: "object[]", required: false, minItems: 1, maxItems: 16, fields: {
+        column: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z_][A-Za-z0-9_]{0,62}$" },
+        op: { kind: "enum", required: true, values: ["eq", "ne", "gt", "gte", "lt", "lte", "in", "notIn", "isNull", "isNotNull"] },
+        value: { kind: "value", required: false, types: ["string", "number", "boolean"], maxLength: 256, list: { minItems: 1, maxItems: 100, types: ["string", "number"] } },
+      } },
+      groupBy: { kind: "string[]", required: false, minItems: 1, maxItems: 8, uniqueItems: false, item: { minLength: 0, pattern: "^[A-Za-z_][A-Za-z0-9_]{0,62}$" } },
+      aggregates: { kind: "object[]", required: false, minItems: 1, maxItems: 16, fields: {
+        fn: { kind: "enum", required: true, values: ["count", "sum", "avg", "min", "max"] },
+        column: { kind: "string", required: true, minLength: 0, pattern: "^(?:\\*|[A-Za-z_][A-Za-z0-9_]{0,62})$" },
+        as: { kind: "string", required: true, minLength: 0, pattern: "^[a-z_][a-z0-9_]{0,62}$" },
+      } },
+      orderBy: { kind: "object[]", required: false, minItems: 1, maxItems: 8, fields: {
+        column: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z_][A-Za-z0-9_]{0,62}$" },
+        direction: { kind: "enum", required: false, values: ["asc", "desc"], default: "asc" },
+      } },
       limit: { kind: "integer", required: false, minimum: 1, maximum: 1000, default: 100 },
     },
   },
@@ -79,41 +155,96 @@ function matches(pattern: string, value: string): boolean {
   return compiled.test(value);
 }
 
+type Refusal = { ok: false; problem: IntegrationExecuteInputProblem };
+function refuse(field: string, message: string): Refusal { return { ok: false, problem: { field, message } }; }
+
+const valueNouns = { string: ['a string', 'strings'], number: ['a number', 'numbers'], boolean: ['a boolean', 'booleans'] } as const;
+function either(parts: readonly string[]): string {
+  return parts.length > 1 ? `${parts.slice(0, -1).join(', ')} or ${parts[parts.length - 1]}` : parts.join('');
+}
+function isScalar(types: readonly IntegrationExecuteInputValueType[], maxLength: number | undefined, value: unknown): boolean {
+  if (typeof value === 'string') return types.includes('string') && (maxLength === undefined || value.length <= maxLength);
+  if (typeof value === 'number') return types.includes('number') && Number.isFinite(value);
+  return typeof value === 'boolean' && types.includes('boolean');
+}
+
 /**
- * Validates one operation's input against the contract and returns it with the
- * contract's defaults applied. The message names the field and its allowed
- * range; it is the sentence the platform answers with, so a caller may show it.
+ * Checks one object's fields in rule order and applies defaults: the input
+ * itself (where null counts as absent), or one entry of an object[] input
+ * (where only a missing key is absent, so null is refused like any wrong value).
  */
-export function validateIntegrationExecuteInput(operation: string, input: unknown): IntegrationExecuteInputValidation {
-  const rule = (IntegrationExecuteInputRules as Record<string, IntegrationExecuteOperationRule>)[operation];
-  if (!rule) return { ok: false, problem: { field: 'operation', message: `${operation} is not a declared integration operation` } };
-  const raw = input === undefined ? {} : input;
-  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, problem: { field: 'input', message: 'input must be an object' } };
-  const given = raw as Record<string, unknown>;
-  for (const name of Object.keys(given)) if (!Object.prototype.hasOwnProperty.call(rule.fields, name)) return { ok: false, problem: { field: name, message: `${name} is not an input of ${operation}` } };
+function checkFields(operation: string, prefix: string, fields: Readonly<Record<string, IntegrationExecuteInputFieldRule>>, given: Record<string, unknown>, nullIsAbsent: boolean): { ok: true; value: Record<string, unknown> } | Refusal {
+  for (const name of Object.keys(given)) if (!Object.prototype.hasOwnProperty.call(fields, name)) return refuse(prefix + name, `${prefix}${name} is not an input of ${operation}`);
   const out: Record<string, unknown> = {};
-  for (const [name, field] of Object.entries(rule.fields)) {
+  for (const [name, field] of Object.entries(fields)) {
+    const path = prefix + name;
     const value = given[name];
-    if (value === undefined || value === null) {
-      if (field.required) return { ok: false, problem: { field: name, message: `${name} is required for ${operation}` } };
-      if (field.kind === 'integer' && field.default !== undefined) out[name] = field.default;
+    if (value === undefined || (nullIsAbsent && value === null)) {
+      if (field.required) return refuse(path, `${path} is required for ${operation}`);
+      if ((field.kind === 'integer' || field.kind === 'enum') && field.default !== undefined) out[name] = field.default;
+      if (field.kind === 'string[]' && field.default !== undefined) out[name] = [...field.default];
       continue;
     }
-    if (field.kind === 'integer') {
-      if (typeof value !== 'number' || !Number.isInteger(value) || value < field.minimum || value > field.maximum) return { ok: false, problem: { field: name, message: `${name} must be an integer between ${field.minimum} and ${field.maximum}` } };
-    } else if (field.kind === 'string') {
-      if (typeof value !== 'string' || value.length < field.minLength || (field.maxLength !== undefined && value.length > field.maxLength)) return { ok: false, problem: { field: name, message: field.maxLength !== undefined ? `${name} must be ${field.minLength} to ${field.maxLength} characters` : `${name} must be a string of at least ${field.minLength} characters` } };
-      if (field.pattern && !matches(field.pattern, value)) return { ok: false, problem: { field: name, message: `${name} must match ${field.pattern}` } };
-    } else {
-      if (!Array.isArray(value) || value.length < field.minItems || value.length > field.maxItems) return { ok: false, problem: { field: name, message: `${name} must list ${field.minItems} to ${field.maxItems} items` } };
+    const checked = checkField(operation, path, name, field, value);
+    if (!checked.ok) return checked;
+    out[name] = checked.value;
+  }
+  return { ok: true, value: out };
+}
+
+function checkField(operation: string, path: string, name: string, field: IntegrationExecuteInputFieldRule, value: unknown): { ok: true; value: unknown } | Refusal {
+  switch (field.kind) {
+    case 'integer':
+      if (typeof value !== 'number' || !Number.isInteger(value) || value < field.minimum || value > field.maximum) return refuse(path, `${path} must be an integer between ${field.minimum} and ${field.maximum}`);
+      return { ok: true, value };
+    case 'string':
+      if (typeof value !== 'string' || value.length < field.minLength || (field.maxLength !== undefined && value.length > field.maxLength)) return refuse(path, field.maxLength !== undefined ? `${path} must be ${field.minLength} to ${field.maxLength} characters` : `${path} must be a string of at least ${field.minLength} characters`);
+      if (field.pattern && !matches(field.pattern, value)) return refuse(path, `${path} must match ${field.pattern}`);
+      return { ok: true, value };
+    case 'enum':
+      if (typeof value !== 'string' || !field.values.includes(value)) return refuse(path, `${path} must be one of ${field.values.join(', ')}`);
+      return { ok: true, value };
+    case 'string[]': {
+      if (!Array.isArray(value) || value.length < field.minItems || value.length > field.maxItems) return refuse(path, `${path} must list ${field.minItems} to ${field.maxItems} items`);
       const seen = new Set<string>();
       for (const [index, item] of value.entries()) {
-        if (typeof item !== 'string' || item.length < field.item.minLength || (field.item.maxLength !== undefined && item.length > field.item.maxLength) || (field.item.pattern !== undefined && !matches(field.item.pattern, item))) return { ok: false, problem: { field: name, message: `${name}[${index}] is not a valid ${name} entry` } };
-        if (field.uniqueItems && seen.has(item)) return { ok: false, problem: { field: name, message: `${name} must not repeat an entry` } };
+        if (typeof item !== 'string' || item.length < field.item.minLength || (field.item.maxLength !== undefined && item.length > field.item.maxLength) || (field.item.pattern !== undefined && !matches(field.item.pattern, item))) return refuse(path, `${path}[${index}] is not a valid ${name} entry`);
+        if (field.uniqueItems && seen.has(item)) return refuse(path, `${path} must not repeat an entry`);
         seen.add(item);
       }
+      return { ok: true, value };
+    }
+    case 'object[]': {
+      if (!Array.isArray(value) || value.length < field.minItems || value.length > field.maxItems) return refuse(path, `${path} must list ${field.minItems} to ${field.maxItems} items`);
+      const entries: Record<string, unknown>[] = [];
+      for (const [index, item] of value.entries()) {
+        if (item === null || typeof item !== 'object' || Array.isArray(item)) return refuse(path, `${path}[${index}] is not a valid ${name} entry`);
+        const entry = checkFields(operation, `${path}[${index}].`, field.fields, item as Record<string, unknown>, false);
+        if (!entry.ok) return entry;
+        entries.push(entry.value);
+      }
+      return { ok: true, value: entries };
+    }
+    case 'value': {
+      const { types, maxLength, list } = field;
+      if (isScalar(types, maxLength, value) || (list !== undefined && Array.isArray(value) && value.length >= list.minItems && value.length <= list.maxItems && value.every(item => isScalar(list.types, maxLength, item)))) return { ok: true, value };
+      const shapes = types.map(type => (type === 'string' && maxLength !== undefined ? `a string of at most ${maxLength} characters` : valueNouns[type][0]));
+      if (list !== undefined) shapes.push(`a list of ${list.minItems} to ${list.maxItems} ${either(list.types.map(type => valueNouns[type][1]))}`);
+      return refuse(path, `${path} must be ${either(shapes)}`);
     }
-    out[name] = value;
   }
-  return { ok: true, input: out };
+}
+
+/**
+ * Validates one operation's input against the contract and returns it with the
+ * contract's defaults applied. The message names the field and its allowed
+ * range; it is the sentence the platform answers with, so a caller may show it.
+ */
+export function validateIntegrationExecuteInput(operation: string, input: unknown): IntegrationExecuteInputValidation {
+  const rule = (IntegrationExecuteInputRules as Record<string, IntegrationExecuteOperationRule>)[operation];
+  if (!rule) return refuse('operation', `${operation} is not a declared integration operation`);
+  const raw = input === undefined ? {} : input;
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return refuse('input', 'input must be an object');
+  const checked = checkFields(operation, '', rule.fields, raw as Record<string, unknown>, true);
+  return checked.ok ? { ok: true, input: checked.value } : checked;
 }