@fourier-labs/harbour-contracts 0.50.0 → 0.53.0

package/dist/gen-ts/integration-execute-request.d.ts

@@ -1,5 +1,5 @@
 /**
- * Body of POST /_harbour/integrations/execute (app SDK), forwarded unchanged to the governance development and runtime execute routes. Exactly one declared operation against one declared resource. The identity mode is NOT a caller field: it is fixed by the operation and enforced from the approved grant; any identity/userId/scope field is rejected by additionalProperties. Per-operation input bounds: slack.channel.history {limit? 1..15, default 15}; slack.message.post {text 1..4000 chars} and a required idempotencyKey retained across retries of one explicit Send; gmail.thread.list {limit? 1..15, default 15}; gmail.message.read {messageId}; gmail.message.send {to 1..50 addresses (to+cc+bcc <= 50 in total), cc?, bcc?, subject 1..256 chars, text 1..4000 chars, replyToMessageId?} and a required idempotencyKey like slack.message.post (plain text only, no attachments); warehouse.view.read {columns 1..32, limit? 1..1000, default 100}. Transport limits (not expressible here): request <= 16 KiB, total deadline 10 s.
+ * Body of POST /_harbour/integrations/execute (app SDK), forwarded unchanged to the governance development and runtime execute routes. Exactly one declared operation against one declared resource. The identity mode is NOT a caller field: it is fixed by the operation (declared per app for slack.message.post) and enforced from the approved grant; any identity/userId/scope field is rejected by additionalProperties. A slack.message.post runs as the app (the IT-approved per-app name from the grant, plus a "Posted by <app> on Harbour" footer) or as the signed-in person (no name, no footer), whichever mode the app declared and IT approved — the same input either way. Per-operation input bounds: slack.channel.history {limit? 1..15, default 15}; slack.message.post {text 1..4000 chars} and a required idempotencyKey retained across retries of one explicit Send; gmail.thread.list {limit? 1..15, default 15}; gmail.message.read {messageId}; gmail.message.send {to 1..50 addresses (to+cc+bcc <= 50 in total), cc?, bcc?, subject 1..256 chars, text 1..4000 chars, replyToMessageId?} and a required idempotencyKey like slack.message.post (plain text only, no attachments); warehouse.view.read {columns 1..32, limit? 1..1000, default 100}. Each operation's then-block is the one statement of its input rules: propertyNames.enum names the fields it accepts, required the ones it needs, and per-field overrides (maximum, default) narrow the shared property. Codegen derives IntegrationExecuteInputRules and validateIntegrationExecuteInput (gen-ts/integration-execute-input-rules.ts, gen-go/integration_execute_input_rules.go) from exactly these blocks, so the governance execute route, the app SDK and the kit's local check refuse the same request with the same message. Transport limits (not expressible here): request <= 16 KiB, total deadline 10 s.
  */
 export type IntegrationExecuteRequest = {
     /**
@@ -7,7 +7,7 @@ export type IntegrationExecuteRequest = {
      */
     connection: string;
     /**
-     * Closed operation set. Extending it is a contracts change. gmail.message.send (0.50.0) sends one plain-text email as the signed-in person: a send like slack.message.post (explicit Send, idempotencyKey, write receipt) under user identity.
+     * Closed operation set. Extending it is a contracts change. gmail.message.send (0.50.0) sends one plain-text email as the signed-in person: a send like slack.message.post (explicit Send, idempotencyKey, write receipt) under user identity. slack.message.post (0.53.0) runs in the mode the app declares: app (the company's Slack app, under the IT-approved per-app name) or user (the signed-in person, after their consent).
      */
     operation: 'slack.channel.history' | 'slack.message.post' | 'gmail.thread.list' | 'gmail.message.read' | 'gmail.message.send' | 'warehouse.view.read';
     /**
@@ -15,7 +15,13 @@ export type IntegrationExecuteRequest = {
      */
     resource: string;
     input: {
+        /**
+         * Read operations: how many items to return; the per-operation then-block sets the real ceiling (15 for slack.channel.history and gmail.thread.list, 1000 for warehouse.view.read) and the default.
+         */
         limit?: number;
+        /**
+         * slack.message.post / gmail.message.send: the plain-text body, 1..4000 characters.
+         */
         text?: string;
         /**
          * gmail.message.read: the Gmail message id a gmail.thread.list result named.

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

@@ -93,6 +93,12 @@ export interface SaasInstallation {
     botUserId: string;
     status: SaasInstallationStatus;
     installedAt: string;
+    /**
+     * The bot scopes Slack granted at installation (0.53.0). Absent on installations recorded before it, which therefore lack chat:write.customize: per-app display names need a reinstall.
+     *
+     * @maxItems 64
+     */
+    scopes?: string[];
 }
 export interface DevelopmentPreapproval {
     /**

package/dist/gen-ts/transform-report.d.ts

@@ -1,5 +1,5 @@
 /**
- * Structured output an agent must return from one Harbour transformation attempt. Handed to the agent as its output schema, then decoded and semantically re-validated by the control plane, which remains the authority. The enum on applied_playbooks.items is the one dynamic part: the adapter injects the names of the playbooks supplied for that invocation before writing the document, so the model is structurally prevented from naming a playbook it was not given. Application-secret handling was removed platform-wide, so this document carries no redactions and no secrets fields. A deployable report must also carry preservation_plan: the agent's own grounded smoke tests (one to three happy_path user journeys plus a boundary_check per behaviour its playbooks or edits could regress) that the validation cell executes after transformation, and an uncovered list naming every boundary it could not test and why. It also carries validation_fixtures: null when no external fixture is needed, or a bounded generic HTTP/WebSocket fixture declaration for that one run. An unsupported report carries only application.unsupported and no plan or fixtures.
+ * Structured output an agent must return from one Harbour transformation attempt. Handed to the agent as its output schema, then decoded and semantically re-validated by the control plane, which remains the authority. The enum on applied_playbooks.items is the one dynamic part: the adapter injects the names of the playbooks supplied for that invocation before writing the document, so the model is structurally prevented from naming a playbook it was not given. Application-secret handling was removed platform-wide, so this document carries no redactions and no secrets fields. A deployable report must also carry preservation_plan: the agent's own grounded smoke tests (one to three happy_path user journeys plus a boundary_check per behaviour its playbooks or edits could regress) that the validation cell executes after transformation, and an uncovered list naming every boundary it could not test and why. It may also carry validation_fixtures: null when no external fixture is needed, or a bounded generic HTTP/WebSocket fixture declaration for that one run; the deployment plane reads the workspace fixture sidecar, so the report's copy is optional. An unsupported report carries only application.unsupported and no plan or fixtures.
  */
 export type TransformReport = {
     /**
@@ -8,23 +8,33 @@ export type TransformReport = {
      * @minItems 1
      */
     applied_playbooks?: string[];
+    /**
+     * Optional. The deployed value is a platform constant supplied to the build, not a report field, so a deployable report may omit it and one that still carries it stays valid.
+     */
     static_rebuild_required?: boolean;
     analysis?: {
         deployable: boolean;
-        needsTransformation: boolean;
+        /**
+         * Whether the attempt changed the tree. Optional: Harbour derives this from the transformed workspace, so a deployable report may omit it and one that still carries it stays valid.
+         */
+        needsTransformation?: boolean;
         /**
          * @maxItems 64
          */
         blockers: string[];
         /**
+         * Paths the attempt touched. Optional: Harbour derives this from the transformed workspace, so a deployable report may omit it and one that still carries it stays valid.
+         *
          * @minItems 1
          * @maxItems 1024
          */
-        surfaces: string[];
+        surfaces?: string[];
         /**
+         * Optional file-and-line citations for why the transformation was needed. Nothing downstream reads them, so a deployable report may omit them and one that still carries them stays valid.
+         *
          * @maxItems 1024
          */
-        evidence: {
+        evidence?: {
             path: string;
             line: number;
             reason: string;
@@ -32,29 +42,46 @@ export type TransformReport = {
     };
     database?: {
         mode: 'none' | 'sql';
-        changeType: 'none' | 'code_only' | 'schema_only' | 'code_and_schema';
-        requiresCodeChanges: boolean;
-        requiresSchemaMigration: boolean;
         /**
+         * Classification of the changed paths. Optional: Harbour derives this from the transformed workspace, so a deployable report may omit it and one that still carries it stays valid.
+         */
+        changeType?: 'none' | 'code_only' | 'schema_only' | 'code_and_schema';
+        /**
+         * Whether any changed path sits outside the database boundary. Optional: Harbour derives this from the transformed workspace, so a deployable report may omit it and one that still carries it stays valid.
+         */
+        requiresCodeChanges?: boolean;
+        /**
+         * Whether the Aurora bundle grew past its seeded prefix. Optional: Harbour derives this from the transformed workspace, so a deployable report may omit it and one that still carries it stays valid.
+         */
+        requiresSchemaMigration?: boolean;
+        /**
+         * Migration files in the Aurora bundle. Optional: Harbour derives this from the transformed workspace, so a deployable report may omit it and one that still carries it stays valid.
+         *
          * @maxItems 128
          */
-        migrationPaths: string[];
+        migrationPaths?: string[];
         /**
+         * Changed paths on the database boundary. Optional: Harbour derives this from the transformed workspace, so a deployable report may omit it and one that still carries it stays valid.
+         *
          * @maxItems 512
          */
-        changedFiles: string[];
+        changedFiles?: string[];
         /**
+         * Optional file-and-line citations for the database findings. Nothing downstream reads them, so a deployable report may omit them and one that still carries them stays valid.
+         *
          * @maxItems 128
          */
-        evidence: {
+        evidence?: {
             path: string;
             line: number;
             reason: string;
         }[];
         /**
+         * Optional. The platform's only structural decline is application.unsupported; nothing reads this list, so a deployable report may omit it and one that still carries it stays valid.
+         *
          * @maxItems 64
          */
-        unsupportedFeatures: string[];
+        unsupportedFeatures?: string[];
     };
     /**
      * Agent-authored preservation (smoke) plan for this attempt. Required whenever the report is deployable; forbidden on an unsupported report. Every test must be grounded in files the agent actually read or changed (evidence) and expressed as tenant-relative browser or HTTP steps the validation cell can execute without secrets. Structural bounds live here; per-action required fields, at least one assert* step per test, one to three happy_path tests, unique ids, the {{runId}} substitution and path safety are enforced semantically by the deployment plane.
@@ -72,12 +99,12 @@ export type TransformReport = {
             kind: 'happy_path' | 'boundary_check';
             name: string;
             /**
-             * Transformation boundaries this test claims to cover.
+             * Transformation boundaries this test claims to cover. Optional: Harbour derives them from the test's own evidence paths, so a deployable report may omit them and one that still carries them stays valid.
              *
              * @minItems 1
              * @maxItems 8
              */
-            boundaries: ('application' | 'routing' | 'database' | 'authentication' | 'runtime_dependency' | 'files' | 'provider' | 'background_work')[];
+            boundaries?: ('application' | 'routing' | 'database' | 'authentication' | 'runtime_dependency' | 'files' | 'provider' | 'background_work')[];
             /**
              * Files (and optionally lines) in the transformed workspace that ground this test. Paths must exist after transformation.
              *
@@ -147,7 +174,10 @@ export type TransformReport = {
          * @maxItems 8
          */
         uncovered: {
-            boundary: 'application' | 'routing' | 'database' | 'authentication' | 'runtime_dependency' | 'files' | 'provider' | 'background_work';
+            /**
+             * Optional: Harbour derives the uncovered boundaries from the changed paths and the covered set, so a deployable report may omit this and one that still carries it stays valid.
+             */
+            boundary?: 'application' | 'routing' | 'database' | 'authentication' | 'runtime_dependency' | 'files' | 'provider' | 'background_work';
             reason: 'not-observable-in-validation-cell' | 'no-safe-fixture' | 'no-grounded-surface';
             detail?: string;
         }[];
@@ -224,7 +254,13 @@ export type TransformReport = {
             kind: 'sql';
             path: string;
         } | null;
+        /**
+         * Optional: determined by topology (static topology iff static build), so a deployable report may omit it and one that still carries it stays valid.
+         */
         buildKind?: 'container' | 'static';
+        /**
+         * Optional: determined by the build output kinds, so a deployable report may omit it and one that still carries it stays valid.
+         */
         topology?: 'static' | 'backend' | 'frontend_and_backend';
         entrypoint?: string;
         build?: {
@@ -248,6 +284,9 @@ export type TransformReport = {
                 route: string;
             }[];
         };
+        /**
+         * Optional: both members are platform constants, so a deployable report may omit this object and one that still carries it stays valid.
+         */
         basePath?: {
             required: boolean;
             environmentVariable: 'HARBOUR_BASE_PATH';
@@ -262,6 +301,8 @@ export type TransformReport = {
             reason: string;
         }[];
         /**
+         * Optional: a deployable plan requires this empty, so a deployable report may omit it and one that still carries it (empty) stays valid.
+         *
          * @maxItems 64
          */
         unsupportedFeatures?: string[];

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

@@ -11,13 +11,17 @@ export type IntegrationAlias = string;
  * @maxItems 64
  */
 export type ResourceNames = IntegrationAlias[];
+/**
+ * Whose authority an operation runs under. Fixed per operation (slack.message.post: declared per app); never chosen at call time.
+ */
+export type IntegrationIdentityMode = 'app' | 'user';
 /**
  * A plain column identifier of a warehouse view.
  */
 export type ColumnName = string;
 
 /**
- * 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 (five operations) and each operation carries a fixed identity mode: slack.channel.history=user, slack.message.post=app, gmail.thread.list=user, gmail.message.read=user, warehouse.view.read=app. A `saas` connection may declare only the Slack and Gmail operations and a `database` connection only warehouse.view.read. Gmail is read-only and user-mode only; its single resource is the fixed `inbox` alias. This file also owns the shared IntegrationOperation / IntegrationIdentityMode / IntegrationEnvironment / IntegrationConnectionKind enums referenced by the other integration schemas.
+ * 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 (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 mode is never chosen at call time: governance runs the call under the approved grant of the declared mode. 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.
  */
 export interface AppIntegrationsDeclaration {
   schema: 'harbour.app-integrations/2.0';
@@ -27,21 +31,38 @@ export interface AppIntegrationsDeclaration {
 }
 export interface DeclaredConnection {
   kind: IntegrationConnectionKind;
+  presentation?: IntegrationPresentation;
   operations: {
     'slack.channel.history'?: UserModeChannelOperation;
-    'slack.message.post'?: AppModeChannelOperation;
+    'slack.message.post'?: DeclaredModeChannelOperation;
     'gmail.thread.list'?: UserModeChannelOperation;
     'gmail.message.read'?: UserModeChannelOperation;
     'gmail.message.send'?: UserModeChannelOperation;
     'warehouse.view.read'?: AppModeViewOperation;
   };
 }
+/**
+ * saas connections only (Slack): how this app's app-mode posts are presented; meaningless for every other operation.
+ */
+export interface IntegrationPresentation {
+  /**
+   * 1..80 characters of plain text: not blank, no control characters, no @-mentions (`@name`, `<@id>`). Must not impersonate a person: IT sees it before approving.
+   */
+  displayName: string;
+  /**
+   * A Slack emoji shortcode such as `:sandwich:`; absent keeps the bot's own icon.
+   */
+  iconEmoji?: string;
+}
 export interface UserModeChannelOperation {
   identity: 'user';
   resources: ResourceNames;
 }
-export interface AppModeChannelOperation {
-  identity: 'app';
+/**
+ * slack.message.post: the app declares the mode — app (posts as the company's Slack app) or user (posts as the signed-in person).
+ */
+export interface DeclaredModeChannelOperation {
+  identity: IntegrationIdentityMode;
   resources: ResourceNames;
 }
 export interface AppModeViewOperation {

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.50.0.0" as const;
-export const ContractPublishVersion = "0.50.0" as const;
-export const ContractPublishTag = "v0.50.0" as const;
-export const ContractSchemasDigest = "sha256:c77dcbf9daad9c66141e9cb8215760a098afd1bf3e665e247f6a4df8db2bcd4f" as const;
+export const ContractRepositoryVersion = "0.53.0.0" as const;
+export const ContractPublishVersion = "0.53.0" as const;
+export const ContractPublishTag = "v0.53.0" as const;
+export const ContractSchemasDigest = "sha256:c4d7c9642842bf3709003f447fb22429ce3573acabaa2da8279e0fc399e8d237" as const;
 export const ContractAiFixturesDigest = "sha256:edac31c92e146ca1c40130f2fb5649db82e24b8cd1ac758153b90612052fddb6" as const;
-export const ContractGeneratedGoDigest = "sha256:545d8b23ab712e75285ea962851bcf8f08f5baeb018bea6f7ba4e1ca2fe80ed0" as const;
-export const ContractGeneratedTypeScriptDigest = "sha256:1e47c3956a3468531690693ff50ff7947a798af01e01d25659401f727cb934c4" as const;
+export const ContractGeneratedGoDigest = "sha256:8f3c3281a76792a9480ca1f7bcbad820db1908efffb29072fcdb0a8f99dbd208" as const;
+export const ContractGeneratedTypeScriptDigest = "sha256:82a083862e500a06df3550e694221cff9dcb98461d5174889c374713f961040c" as const;

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

@@ -12,7 +12,7 @@ export type DataGrantV2ProvisioningStatus = 'NONE' | 'PENDING' | 'FAILED' | 'DON
 export type DataGrantV2CleanupStatus = 'PENDING' | 'FAILED' | 'DONE';
 
 /**
- * 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. A fresh REQUESTED record carries empty `operations`/`resources` until the attached request is approved; approved resources are structured `{name, columns?}` entries (a Slack channel alias, the fixed Gmail `inbox` alias, or a warehouse view alias with its approved columns). Expiry is enforced from UTC time on every call and SDK calls never extend it; `expiredAt` is stamped by the recovery sweep afterwards. 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; both hold references only. `identityMode` and `installation` are the deprecated 0.45.0 spellings: the record carries `mode`, and a SaaS grant runs on the connection's single installation.
+ * 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. A fresh REQUESTED record carries empty `operations`/`resources` until the attached request is approved; approved resources are structured `{name, columns?}` entries (a Slack channel alias, the fixed Gmail `inbox` alias, or a warehouse view alias with its approved columns). Expiry is enforced from UTC time on every call and SDK calls never extend it; `expiredAt` is stamped by the recovery sweep afterwards. 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; both hold references only. An app-mode Slack grant may carry `presentation` (0.53.0): the IT-approved display name and icon the app's posts go out under, copied from the approved request and read by every post — never from the call. `identityMode` and `installation` are the deprecated 0.45.0 spellings: the record carries `mode`, and a SaaS grant runs on the connection's single installation.
  */
 export interface DataGrantV2 {
   schema: 'harbour.data-grant/2.0';
@@ -27,7 +27,7 @@ export interface DataGrantV2 {
    */
   sourceId: string;
   /**
-   * Whose authority an operation runs under. Fixed per operation; callers never choose it.
+   * Whose authority an operation runs under. Fixed per operation (slack.message.post: declared per app); never chosen at call time.
    */
   mode: 'app' | 'user';
   kind: 'saas' | 'database';
@@ -69,6 +69,7 @@ export interface DataGrantV2 {
    * The one open access request attached to this grant, if any.
    */
   pendingRequestId?: string;
+  presentation?: IntegrationPresentation;
   provisioning: DataGrantV2Provisioning;
   /**
    * Database grants: secretref://tenant/{t}/app/{a}/env/{env}/source/{s}. Set only by a successful publish and removed by cleanup.
@@ -82,7 +83,7 @@ export interface DataGrantV2 {
   updatedAt: string;
   /**
    * @deprecated
-   * Whose authority an operation runs under. Fixed per operation; callers never choose it.
+   * Whose authority an operation runs under. Fixed per operation (slack.message.post: declared per app); never chosen at call time.
    */
   identityMode?: 'app' | 'user';
   /**
@@ -107,6 +108,19 @@ export interface IntegrationResource {
    */
   columns?: string[];
 }
+/**
+ * App-mode Slack grants only: how the app's posts are presented, as IT approved it. Absent means the posts carry the bot's own name.
+ */
+interface IntegrationPresentation {
+  /**
+   * 1..80 characters of plain text: not blank, no control characters, no @-mentions (`@name`, `<@id>`). Must not impersonate a person: IT sees it before approving.
+   */
+  displayName: string;
+  /**
+   * A Slack emoji shortcode such as `:sandwich:`; absent keeps the bot's own icon.
+   */
+  iconEmoji?: string;
+}
 export interface DataGrantV2Provisioning {
   status: DataGrantV2ProvisioningStatus;
   /**

package/gen-ts/index.ts

@@ -46,6 +46,7 @@ export * from './error-category.js';
 export * from './error-envelope.js';
 export * from './integration-connect-result.js';
 export * from './integration-error-details.js';
+export * from './integration-execute-input-rules.js';
 export * from './integration-execute-request.js';
 export * from './integration-execute-result.js';
 export * from './kit-bundle-manifest.js';

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

@@ -0,0 +1,119 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * Per-operation input rules of integration-execute-request: derived from each
+ * operation's then-block (propertyNames.enum, required, per-field overrides).
+ * The governance execute route, the app SDK and the kit's local check validate
+ * with validateIntegrationExecuteInput below, so a request is refused with the
+ * same message wherever it is made.
+ */
+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 } };
+
+export type IntegrationExecuteOperationRule = { idempotencyKey: boolean; fields: Record<string, IntegrationExecuteInputFieldRule> };
+
+export const IntegrationExecuteInputRules = {
+  "slack.channel.history": {
+    idempotencyKey: false,
+    fields: {
+      limit: { kind: "integer", required: false, minimum: 1, maximum: 15, default: 15 },
+    },
+  },
+  "slack.message.post": {
+    idempotencyKey: true,
+    fields: {
+      text: { kind: "string", required: true, minLength: 1, maxLength: 4000 },
+    },
+  },
+  "gmail.thread.list": {
+    idempotencyKey: false,
+    fields: {
+      limit: { kind: "integer", required: false, minimum: 1, maximum: 15, default: 15 },
+    },
+  },
+  "gmail.message.read": {
+    idempotencyKey: false,
+    fields: {
+      messageId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9_-]{1,64}$" },
+    },
+  },
+  "gmail.message.send": {
+    idempotencyKey: true,
+    fields: {
+      to: { kind: "string[]", required: true, minItems: 1, maxItems: 50, uniqueItems: true, item: { minLength: 3, maxLength: 254, pattern: "^[^\\s@<>,;\"]+@[^\\s@<>,;\"]+\\.[^\\s@<>,;\"]+$" } },
+      cc: { kind: "string[]", required: false, minItems: 1, maxItems: 50, uniqueItems: true, item: { minLength: 3, maxLength: 254, pattern: "^[^\\s@<>,;\"]+@[^\\s@<>,;\"]+\\.[^\\s@<>,;\"]+$" } },
+      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 },
+      replyToMessageId: { kind: "string", required: false, minLength: 0, pattern: "^[A-Za-z0-9_-]{1,64}$" },
+    },
+  },
+  "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}$" } },
+      limit: { kind: "integer", required: false, minimum: 1, maximum: 1000, default: 100 },
+    },
+  },
+} as const satisfies Record<string, IntegrationExecuteOperationRule>;
+
+export type IntegrationExecuteOperation = keyof typeof IntegrationExecuteInputRules;
+
+/** The upper bound of one integer input as a literal type: integrationExecuteInputMaximum('slack.channel.history', 'limit') is 15. */
+export function integrationExecuteInputMaximum<O extends IntegrationExecuteOperation, F extends keyof (typeof IntegrationExecuteInputRules)[O]['fields']>(operation: O, field: F): Extract<(typeof IntegrationExecuteInputRules)[O]['fields'][F], { maximum: number }>['maximum'] {
+  const rule = (IntegrationExecuteInputRules[operation].fields as Record<string, IntegrationExecuteInputFieldRule>)[field as string];
+  if (!rule || rule.kind !== 'integer') throw new Error(`${String(operation)}.input.${String(field)} has no integer bound`);
+  return rule.maximum as never;
+}
+
+export type IntegrationExecuteInputProblem = { field: string; message: string };
+export type IntegrationExecuteInputValidation = { ok: true; input: Record<string, unknown> } | { ok: false; problem: IntegrationExecuteInputProblem };
+
+const patterns = new Map<string, RegExp>();
+function matches(pattern: string, value: string): boolean {
+  let compiled = patterns.get(pattern);
+  if (!compiled) { compiled = new RegExp(pattern, 'u'); patterns.set(pattern, compiled); }
+  return compiled.test(value);
+}
+
+/**
+ * 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 { 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}` } };
+  const out: Record<string, unknown> = {};
+  for (const [name, field] of Object.entries(rule.fields)) {
+    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;
+      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 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` } };
+        seen.add(item);
+      }
+    }
+    out[name] = value;
+  }
+  return { ok: true, input: out };
+}

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

@@ -2,7 +2,7 @@
 // Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
 
 /**
- * Body of POST /_harbour/integrations/execute (app SDK), forwarded unchanged to the governance development and runtime execute routes. Exactly one declared operation against one declared resource. The identity mode is NOT a caller field: it is fixed by the operation and enforced from the approved grant; any identity/userId/scope field is rejected by additionalProperties. Per-operation input bounds: slack.channel.history {limit? 1..15, default 15}; slack.message.post {text 1..4000 chars} and a required idempotencyKey retained across retries of one explicit Send; gmail.thread.list {limit? 1..15, default 15}; gmail.message.read {messageId}; gmail.message.send {to 1..50 addresses (to+cc+bcc <= 50 in total), cc?, bcc?, subject 1..256 chars, text 1..4000 chars, replyToMessageId?} and a required idempotencyKey like slack.message.post (plain text only, no attachments); warehouse.view.read {columns 1..32, limit? 1..1000, default 100}. Transport limits (not expressible here): request <= 16 KiB, total deadline 10 s.
+ * Body of POST /_harbour/integrations/execute (app SDK), forwarded unchanged to the governance development and runtime execute routes. Exactly one declared operation against one declared resource. The identity mode is NOT a caller field: it is fixed by the operation (declared per app for slack.message.post) and enforced from the approved grant; any identity/userId/scope field is rejected by additionalProperties. A slack.message.post runs as the app (the IT-approved per-app name from the grant, plus a "Posted by <app> on Harbour" footer) or as the signed-in person (no name, no footer), whichever mode the app declared and IT approved — the same input either way. Per-operation input bounds: slack.channel.history {limit? 1..15, default 15}; slack.message.post {text 1..4000 chars} and a required idempotencyKey retained across retries of one explicit Send; gmail.thread.list {limit? 1..15, default 15}; gmail.message.read {messageId}; gmail.message.send {to 1..50 addresses (to+cc+bcc <= 50 in total), cc?, bcc?, subject 1..256 chars, text 1..4000 chars, replyToMessageId?} and a required idempotencyKey like slack.message.post (plain text only, no attachments); warehouse.view.read {columns 1..32, limit? 1..1000, default 100}. Each operation's then-block is the one statement of its input rules: propertyNames.enum names the fields it accepts, required the ones it needs, and per-field overrides (maximum, default) narrow the shared property. Codegen derives IntegrationExecuteInputRules and validateIntegrationExecuteInput (gen-ts/integration-execute-input-rules.ts, gen-go/integration_execute_input_rules.go) from exactly these blocks, so the governance execute route, the app SDK and the kit's local check refuse the same request with the same message. Transport limits (not expressible here): request <= 16 KiB, total deadline 10 s.
  */
 export type IntegrationExecuteRequest = {
   /**
@@ -10,7 +10,7 @@ export type IntegrationExecuteRequest = {
    */
   connection: string;
   /**
-   * Closed operation set. Extending it is a contracts change. gmail.message.send (0.50.0) sends one plain-text email as the signed-in person: a send like slack.message.post (explicit Send, idempotencyKey, write receipt) under user identity.
+   * Closed operation set. Extending it is a contracts change. gmail.message.send (0.50.0) sends one plain-text email as the signed-in person: a send like slack.message.post (explicit Send, idempotencyKey, write receipt) under user identity. slack.message.post (0.53.0) runs in the mode the app declares: app (the company's Slack app, under the IT-approved per-app name) or user (the signed-in person, after their consent).
    */
   operation:
     | 'slack.channel.history'
@@ -24,7 +24,13 @@ export type IntegrationExecuteRequest = {
    */
   resource: string;
   input: {
+    /**
+     * Read operations: how many items to return; the per-operation then-block sets the real ceiling (15 for slack.channel.history and gmail.thread.list, 1000 for warehouse.view.read) and the default.
+     */
     limit?: number;
+    /**
+     * slack.message.post / gmail.message.send: the plain-text body, 1..4000 characters.
+     */
     text?: string;
     /**
      * gmail.message.read: the Gmail message id a gmail.thread.list result named.

package/gen-ts/saas-connection.ts

@@ -104,6 +104,12 @@ export interface SaasInstallation {
   botUserId: string;
   status: SaasInstallationStatus;
   installedAt: string;
+  /**
+   * The bot scopes Slack granted at installation (0.53.0). Absent on installations recorded before it, which therefore lack chat:write.customize: per-app display names need a reinstall.
+   *
+   * @maxItems 64
+   */
+  scopes?: string[];
 }
 export interface DevelopmentPreapproval {
   /**