@fourier-labs/harbour-contracts 0.45.0 → 0.47.0

package/gen-ts/saas-connection.ts

@@ -1,63 +1,104 @@
 /* eslint-disable */
 // Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
 
+/**
+ * Slack carries an installation and a channel map; Gmail is user-consent only and read-only.
+ */
+export type SaasProvider = 'slack' | 'gmail';
 /**
  * DISABLED stops every app call immediately (details.code CONNECTION_DISABLED).
  */
 export type SaasConnectionStatus = 'ACTIVE' | 'DISABLED';
+export type SaasInstallationStatus = 'installed' | 'reconnect_required' | 'revoked';
+/**
+ */
 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.
+ * Tenant-wide SaaS connection record (control table sk SAASCONN#<sourceId>, same tenant partition as database sources; alias uniqueness is enforced across both). One connection per tenant and provider: a single bot installation of the platform-owned provider app and a single logical channel map shared by every app environment (grants, requests and user consent links stay per environment). A Gmail connection has neither installation nor channels: user consent is the only step and its one resource is the fixed `inbox` alias. Contains references, never secrets: installation tokens live under their own token records. The pre-T25 per-environment shape (`clientId`, `clientSecretRef`, `environments`, `installations`) is deprecated: the control plane normalises such a stored record on read and never writes it.
  */
 export interface SaasConnection {
+  schema: 'harbour.saas-connection/1.0';
+  tenantId: string;
   /**
    * Tenant-wide logical alias of a connection (governance sourceId) or of a resource under it.
    */
   sourceId: string;
   kind: 'saas';
-  provider: 'slack';
+  provider: SaasProvider;
   displayName: string;
   status: SaasConnectionStatus;
   /**
    * Optimistic-concurrency version; every write is conditional on it.
    */
   version: number;
-  clientId: string;
+  installation?: SaasInstallation;
   /**
-   * secretref://tenant/{tenantId}/saas/{sourceId}/client
+   * Logical channel alias -> provider channel ID, shared by every environment. Always empty for Gmail.
    */
-  clientSecretRef?: string;
-  environments: {
-    development?: SaasEnvironmentMapping;
-    preview?: SaasEnvironmentMapping;
-    production?: SaasEnvironmentMapping;
+  channels: {
+    /**
+     * Provider channel ID; only public, non-archived channels are valid.
+     */
+    [k: string]: string;
   };
   /**
-   * Operations IT allows apps to request on this connection.
+   * 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). Never warehouse.view.read.
    *
    * @minItems 1
-   * @maxItems 2
+   * @maxItems 4
    */
-  operations: ('slack.channel.history' | 'slack.message.post')[];
+  operations: (
+    'slack.channel.history' | 'slack.message.post' | 'gmail.thread.list' | 'gmail.message.read' | 'warehouse.view.read'
+  )[];
   developmentPreapproval: DevelopmentPreapproval;
   /**
-   * Provider installations keyed by the installation name environments point at.
+   * Lower-cased builder emails excluded from development preapproval.
+   *
+   * @maxItems 256
+   */
+  blockedDevelopmentBuilders?: string[];
+  createdAt: string;
+  updatedAt: string;
+  /**
+   * @deprecated
+   * Deprecated (pre-T25 tenant-owned provider client). Dropped on read; never written.
+   */
+  clientId?: string;
+  /**
+   * @deprecated
+   * Deprecated (pre-T25 tenant-owned provider client secret reference). Dropped on read; never written.
+   */
+  clientSecretRef?: string;
+  /**
+   * @deprecated
+   * Deprecated pre-T25 per-environment mapping. On read the development entry's channels become `channels`; never written.
+   */
+  environments?: {
+    development?: SaasEnvironmentMapping;
+    preview?: SaasEnvironmentMapping;
+    production?: SaasEnvironmentMapping;
+  };
+  /**
+   * @deprecated
+   * Deprecated pre-T25 named installations. On read the `nonprod` entry (or the development mapping's) becomes `installation`; never written.
    */
   installations?: {
-    [k: string]: SaasInstallation;
+    [k: string]: LegacySaasInstallation;
   };
-  createdAt?: string;
-  updatedAt?: string;
 }
-export interface SaasEnvironmentMapping {
-  installation: InstallationName;
-  channels: {
-    /**
-     * Provider channel ID; only public, non-archived channels are valid.
-     */
-    [k: string]: string;
-  };
+/**
+ * The one bot installation of the platform-owned provider app in this tenant's workspace.
+ */
+export interface SaasInstallation {
+  tokenRecordId: string;
+  workspaceId: string;
+  /**
+   * Empty only for a legacy record normalised without one.
+   */
+  botUserId: string;
+  status: SaasInstallationStatus;
+  installedAt: string;
 }
 export interface DevelopmentPreapproval {
   /**
@@ -69,9 +110,21 @@ export interface DevelopmentPreapproval {
    */
   hours: number;
 }
-export interface SaasInstallation {
-  tokenRecordId: string;
-  workspaceId: string;
-  botUserId: string;
-  status: 'ACTIVE' | 'RECONNECT_REQUIRED' | 'REVOKED';
+/**
+ * @deprecated
+ */
+export interface SaasEnvironmentMapping {
+  installation: InstallationName;
+  channels: {
+    [k: string]: string;
+  };
+}
+/**
+ * @deprecated
+ */
+export interface LegacySaasInstallation {
+  tokenRecordId?: string;
+  workspaceId?: string;
+  botUserId?: string;
+  status?: 'ACTIVE' | 'RECONNECT_REQUIRED' | 'REVOKED';
 }

package/package.json

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

package/schema/ai-policy-snapshot.schema.json

@@ -52,7 +52,8 @@
       "maxItems": 128,
       "items": { "$ref": "#/definitions/AiPolicyLimit" }
     },
-    "retention": { "$ref": "#/definitions/AiPolicyRetention" }
+    "retention": { "$ref": "#/definitions/AiPolicyRetention" },
+    "assignments": { "$ref": "#/definitions/AiPolicyAssignments" }
   },
   "definitions": {
     "AiPolicyIdentifier": {
@@ -366,6 +367,17 @@
           "items": { "$ref": "#/definitions/AiPolicyIdentifier" }
         }
       }
+    },
+    "AiPolicyAssignments": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["routes", "policies", "budgets"],
+      "description": "Application-scope only: the tenant resources this application/environment snapshot pins BY NAME (D-8/D-9). A scope without assignments keeps the default rule (the whole merge-narrowed set is the assignment). Every name must exist in the same snapshot's own family; empty route and budget selections are legal (tenant-scoped limits bind regardless).",
+      "properties": {
+        "routes": { "type": "array", "maxItems": 256, "uniqueItems": true, "items": { "$ref": "#/definitions/AiPolicyIdentifier" } },
+        "policies": { "type": "array", "minItems": 1, "maxItems": 256, "uniqueItems": true, "items": { "$ref": "#/definitions/AiPolicyIdentifier" } },
+        "budgets": { "type": "array", "maxItems": 128, "uniqueItems": true, "items": { "$ref": "#/definitions/AiPolicyIdentifier" } }
+      }
     }
   }
 }

package/schema/ai-runtime-contract.schema.json

@@ -104,7 +104,7 @@
       "properties": {
         "mappingId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$" },
         "version": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" },
-        "protocol": { "type": "string", "const": "openai-chat" },
+        "protocol": { "type": "string", "enum": ["openai-chat", "openai-images"] },
         "providerId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_.-]{0,63}$" },
         "apiKeyEnvironmentName": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z][A-Z0-9_]{0,127}$" },
         "baseUrlEnvironmentName": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z][A-Z0-9_]{0,127}$" }

package/schema/ai-trace-event.schema.json

@@ -45,7 +45,13 @@
     "provider": { "type": "string", "enum": ["openai", "anthropic", "gemini", "openrouter", "deepseek", "elevenlabs", "deepgram", "higgsfield"] },
     "providerModel": { "type": "string", "minLength": 1, "maxLength": 256 },
     "outcome": { "type": "string", "enum": ["succeeded", "blocked", "failed", "cancelled"] },
-    "usage": { "$ref": "#/definitions/AiTraceUsage" },
+    "usage": {
+      "description": "Trace-level provider-reported usage, or null when no attempt reported any (the reservation stays committed rather than reconciled against invented zero usage).",
+      "oneOf": [
+        { "$ref": "#/definitions/AiTraceUsage" },
+        { "type": "null" }
+      ]
+    },
     "priceRevision": { "$ref": "#/definitions/AiTraceIdentifier" },
     "costMicroUsd": { "type": "integer", "minimum": 0 },
     "latencyMs": { "type": "integer", "minimum": 0 },

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

@@ -2,7 +2,7 @@
   "$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.",
+  "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 (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.",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema", "connections"],
@@ -19,13 +19,13 @@
   "definitions": {
     "IntegrationAlias": {
       "type": "string",
-      "pattern": "^[a-z][a-z0-9_-]{0,62}$",
+      "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$",
       "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"],
+      "enum": ["slack.channel.history", "slack.message.post", "gmail.thread.list", "gmail.message.read", "warehouse.view.read"],
       "description": "Closed operation set. Extending it is a contracts change."
     },
     "IntegrationIdentityMode": {
@@ -38,6 +38,11 @@
       "enum": ["development", "preview", "production"],
       "description": "development is the CLI/local kit; preview and production are hosted."
     },
+    "ColumnName": {
+      "type": "string",
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,62}$",
+      "description": "A plain column identifier of a warehouse view."
+    },
     "ResourceNames": {
       "type": "array",
       "minItems": 1,
@@ -53,7 +58,7 @@
           "type": "array",
           "minItems": 1,
           "maxItems": 32,
-          "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$" }
+          "items": { "$ref": "#/definitions/ColumnName" }
         }
       }
     },
@@ -103,6 +108,8 @@
           "properties": {
             "slack.channel.history": { "$ref": "#/definitions/UserModeChannelOperation" },
             "slack.message.post": { "$ref": "#/definitions/AppModeChannelOperation" },
+            "gmail.thread.list": { "$ref": "#/definitions/UserModeChannelOperation" },
+            "gmail.message.read": { "$ref": "#/definitions/UserModeChannelOperation" },
             "warehouse.view.read": { "$ref": "#/definitions/AppModeViewOperation" }
           }
         }
@@ -112,7 +119,7 @@
       "else": {
         "properties": {
           "operations": {
-            "not": { "anyOf": [{ "required": ["slack.channel.history"] }, { "required": ["slack.message.post"] }] }
+            "not": { "anyOf": [{ "required": ["slack.channel.history"] }, { "required": ["slack.message.post"] }, { "required": ["gmail.thread.list"] }, { "required": ["gmail.message.read"] }] }
           }
         }
       }
@@ -129,6 +136,13 @@
             "slack.message.post": { "identity": "app", "resources": ["team-updates"] }
           }
         },
+        "gmail": {
+          "kind": "saas",
+          "operations": {
+            "gmail.thread.list": { "identity": "user", "resources": ["inbox"] },
+            "gmail.message.read": { "identity": "user", "resources": ["inbox"] }
+          }
+        },
         "sales-warehouse": {
           "kind": "database",
           "operations": {

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

@@ -2,48 +2,78 @@
   "$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.",
+  "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. 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.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["schema", "appId", "sourceId", "kind", "environment", "identityMode", "status", "operations", "resources", "version", "provisioning"],
+  "required": ["schema", "tenantId", "appId", "environment", "sourceId", "mode", "kind", "status", "operations", "resources", "version", "provisioning", "createdAt", "updatedAt"],
   "properties": {
     "schema": { "type": "string", "const": "harbour.data-grant/2.0" },
+    "tenantId": { "type": "string", "minLength": 1, "maxLength": 255 },
     "appId": { "type": "string", "minLength": 1, "maxLength": 255 },
+    "environment": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationEnvironment" },
     "sourceId": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
+    "mode": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationIdentityMode" },
     "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,
+      "maxItems": 5,
       "uniqueItems": true,
       "items": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationOperation" },
-      "description": "Approved operations; each must match this grant's identityMode."
+      "description": "Approved operations; each must match this grant's mode. Empty until the first approval."
     },
     "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."
+      "items": { "$ref": "#/definitions/IntegrationResource" },
+      "description": "Approved logical resources. Never inherited by wildcard. Empty until the first approval."
     },
     "expiresAt": { "type": "string", "format": "date-time", "description": "Absent only for explicitly approved ongoing production access." },
+    "expiredAt": { "type": "string", "format": "date-time", "description": "Set by the recovery sweep once expiry has passed; enforcement itself is the UTC check on every call." },
     "approvedBy": { "type": "string", "minLength": 1, "maxLength": 255 },
+    "approvedAt": { "type": "string", "format": "date-time" },
     "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}."
+      "description": "Database grants: secretref://tenant/{t}/app/{a}/env/{env}/source/{s}. Set only by a successful publish and removed by cleanup."
     },
     "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." }
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" },
+    "identityMode": {
+      "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationIdentityMode",
+      "deprecated": true,
+      "description": "Deprecated 0.45.0 spelling of `mode`; the control plane never writes it."
+    },
+    "installation": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_-]{0,62}$",
+      "deprecated": true,
+      "description": "Deprecated: a SaaS grant runs on the connection's single installation; the control plane never writes it."
+    }
   },
   "definitions": {
+    "IntegrationResource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "description": "One approved logical resource: a channel alias, the fixed Gmail `inbox` alias, or a warehouse view alias with the approved columns.",
+      "properties": {
+        "name": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
+        "columns": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": { "$ref": "app-integrations-declaration.schema.json#/definitions/ColumnName" },
+          "description": "warehouse.view.read only: the approved columns of the view."
+        }
+      }
+    },
     "DataGrantV2Status": {
       "type": "string",
       "enum": ["REQUESTED", "GRANTED", "DENIED", "REVOKED"],
@@ -54,6 +84,10 @@
       "enum": ["NONE", "PENDING", "FAILED", "DONE"],
       "description": "Provider-side work for the current approved scope (credential mint, cleanup, installation check)."
     },
+    "DataGrantV2CleanupStatus": {
+      "type": "string",
+      "enum": ["PENDING", "FAILED", "DONE"]
+    },
     "DataGrantV2Provisioning": {
       "type": "object",
       "additionalProperties": false,
@@ -61,7 +95,28 @@
       "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." }
+        "lastError": { "type": "string", "maxLength": 500, "description": "Sanitized reason; never a provider error body." },
+        "lease": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["until", "owner"],
+          "description": "Conditional worker lease serialising database mutations (120 s).",
+          "properties": {
+            "until": { "type": "string", "format": "date-time" },
+            "owner": { "type": "string", "minLength": 1, "maxLength": 128 }
+          }
+        },
+        "cleanup": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status", "attempts"],
+          "description": "Provider-side cleanup after revocation or expiry; a FAILED cleanup waits for an admin retry-cleanup.",
+          "properties": {
+            "status": { "$ref": "#/definitions/DataGrantV2CleanupStatus" },
+            "attempts": { "type": "integer", "minimum": 0, "maximum": 3 },
+            "lastError": { "type": "string", "maxLength": 500 }
+          }
+        }
       }
     }
   },
@@ -75,34 +130,58 @@
   "examples": [
     {
       "schema": "harbour.data-grant/2.0",
+      "tenantId": "fourier",
       "appId": "app-1f2e3d4c",
+      "environment": "development",
       "sourceId": "company-slack",
+      "mode": "user",
       "kind": "saas",
-      "environment": "development",
-      "identityMode": "user",
       "status": "GRANTED",
       "operations": ["slack.channel.history"],
-      "resources": ["team-updates"],
+      "resources": [{ "name": "team-updates" }],
       "expiresAt": "2026-09-10T08:00:00Z",
       "approvedBy": "policy:development-preapproval",
+      "approvedAt": "2026-09-09T08:00:00Z",
       "version": 2,
       "provisioning": { "status": "DONE", "attempts": 0 },
-      "installation": "nonprod"
+      "createdAt": "2026-09-09T08:00:00Z",
+      "updatedAt": "2026-09-09T08:00:00Z"
     },
     {
       "schema": "harbour.data-grant/2.0",
+      "tenantId": "fourier",
       "appId": "app-1f2e3d4c",
+      "environment": "preview",
       "sourceId": "sales-warehouse",
+      "mode": "app",
       "kind": "database",
-      "environment": "preview",
-      "identityMode": "app",
       "status": "REQUESTED",
-      "operations": ["warehouse.view.read"],
-      "resources": ["weekly_sales"],
-      "expiresAt": "2026-09-16T08:00:00Z",
+      "operations": [],
+      "resources": [],
       "version": 1,
       "pendingRequestId": "req_9a8b7c6d",
-      "provisioning": { "status": "PENDING", "attempts": 1, "lastError": "credential verification timed out" }
+      "provisioning": { "status": "PENDING", "attempts": 1, "lastError": "credential verification timed out", "lease": { "until": "2026-09-09T08:02:00Z", "owner": "worker-7" } },
+      "createdAt": "2026-09-09T08:00:00Z",
+      "updatedAt": "2026-09-09T08:00:00Z"
+    },
+    {
+      "schema": "harbour.data-grant/2.0",
+      "tenantId": "fourier",
+      "appId": "app-1f2e3d4c",
+      "environment": "production",
+      "sourceId": "sales-warehouse",
+      "mode": "app",
+      "kind": "database",
+      "status": "REVOKED",
+      "operations": ["warehouse.view.read"],
+      "resources": [{ "name": "weekly_sales", "columns": ["week", "total"] }],
+      "approvedBy": "it-admin@example.com",
+      "approvedAt": "2026-09-09T08:00:00Z",
+      "version": 5,
+      "provisioning": { "status": "NONE", "attempts": 0, "cleanup": { "status": "PENDING", "attempts": 0 } },
+      "mintedPrincipal": "harbour_fourier_app1f2e3d4c_production_sales_warehouse",
+      "createdAt": "2026-09-09T08:00:00Z",
+      "updatedAt": "2026-09-11T08:00:00Z"
     }
   ]
 }

package/schema/integration-error-details.schema.json

@@ -52,9 +52,17 @@
         "APP_ACCESS_REQUIRED",
         "GRANT_DENIED",
         "TOKEN_REFRESH_PENDING",
-        "REQUEST_PENDING"
+        "REQUEST_PENDING",
+        "INPUT_INVALID",
+        "IDEMPOTENCY_KEY_REQUIRED",
+        "SEND_IN_PROGRESS",
+        "CONNECTION_NOT_FOUND",
+        "APP_NOT_FOUND",
+        "GRANT_NOT_FOUND",
+        "AUTH_REQUIRED",
+        "UNAVAILABLE"
       ],
-      "description": "Stable reason codes. SEND_OUTCOME_UNKNOWN: dispatch happened but the outcome is unknown; never re-post automatically. SEND_KEY_REUSED: the idempotency key was seen with a different payload or subject. GRANT_DENIED: IT denied the request. TOKEN_REFRESH_PENDING: another call holds the refresh lease; retry shortly. REQUEST_PENDING: a different request for this grant is still open."
+      "description": "Stable reason codes. SEND_OUTCOME_UNKNOWN: dispatch happened but the outcome is unknown; never re-post automatically. SEND_KEY_REUSED: the idempotency key was seen with a different payload or subject. GRANT_DENIED: IT denied the request. TOKEN_REFRESH_PENDING: another call holds the refresh lease; retry shortly. REQUEST_PENDING: a different request for this grant is still open. INPUT_INVALID: the operation input failed its bounds. IDEMPOTENCY_KEY_REQUIRED: a send without a UUID idempotencyKey. SEND_IN_PROGRESS: a retry arrived while the first send of that key is still running. CONNECTION_NOT_FOUND / APP_NOT_FOUND / GRANT_NOT_FOUND: the named record does not exist. AUTH_REQUIRED: no verified caller. UNAVAILABLE: the governance dependency (store, provider seam) is unreachable."
     }
   },
   "examples": [

package/schema/integration-execute-request.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://schemas.harbour.dev/integration-execute-request.schema.json",
   "title": "IntegrationExecuteRequest",
-  "description": "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; warehouse.view.read {columns 1..32, limit? 1..1000, default 100}. Transport limits (not expressible here): request <= 16 KiB, total deadline 10 s.",
+  "description": "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}; warehouse.view.read {columns 1..32, limit? 1..1000, default 100}. Transport limits (not expressible here): request <= 16 KiB, total deadline 10 s.",
   "type": "object",
   "additionalProperties": false,
   "required": ["connection", "operation", "resource", "input"],
@@ -16,11 +16,12 @@
       "properties": {
         "limit": { "type": "integer", "minimum": 1, "maximum": 1000 },
         "text": { "type": "string", "minLength": 1, "maxLength": 4000 },
+        "messageId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "gmail.message.read: the Gmail message id a gmail.thread.list result named." },
         "columns": {
           "type": "array",
           "minItems": 1,
           "maxItems": 32,
-          "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$" }
+          "items": { "$ref": "app-integrations-declaration.schema.json#/definitions/ColumnName" }
         }
       }
     },
@@ -36,7 +37,7 @@
       "then": {
         "not": { "required": ["idempotencyKey"] },
         "properties": {
-          "input": { "properties": { "limit": { "maximum": 15 } }, "not": { "anyOf": [{ "required": ["text"] }, { "required": ["columns"] }] } }
+          "input": { "properties": { "limit": { "maximum": 15 } }, "not": { "anyOf": [{ "required": ["text"] }, { "required": ["columns"] }, { "required": ["messageId"] }] } }
         }
       }
     },
@@ -45,7 +46,7 @@
       "then": {
         "required": ["idempotencyKey"],
         "properties": {
-          "input": { "required": ["text"], "not": { "anyOf": [{ "required": ["limit"] }, { "required": ["columns"] }] } }
+          "input": { "required": ["text"], "not": { "anyOf": [{ "required": ["limit"] }, { "required": ["columns"] }, { "required": ["messageId"] }] } }
         }
       }
     },
@@ -54,7 +55,25 @@
       "then": {
         "not": { "required": ["idempotencyKey"] },
         "properties": {
-          "input": { "required": ["columns"], "not": { "required": ["text"] } }
+          "input": { "required": ["columns"], "not": { "anyOf": [{ "required": ["text"] }, { "required": ["messageId"] }] } }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "operation": { "const": "gmail.thread.list" } } },
+      "then": {
+        "not": { "required": ["idempotencyKey"] },
+        "properties": {
+          "input": { "properties": { "limit": { "maximum": 15 } }, "not": { "anyOf": [{ "required": ["text"] }, { "required": ["columns"] }, { "required": ["messageId"] }] } }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "operation": { "const": "gmail.message.read" } } },
+      "then": {
+        "not": { "required": ["idempotencyKey"] },
+        "properties": {
+          "input": { "required": ["messageId"], "not": { "anyOf": [{ "required": ["text"] }, { "required": ["columns"] }, { "required": ["limit"] }] } }
         }
       }
     }
@@ -68,6 +87,8 @@
       "input": { "text": "Weekly update posted." },
       "idempotencyKey": "6f1c2c1e-3a1c-4c3e-9f0e-2b6f7d8a9c10"
     },
-    { "connection": "sales-warehouse", "operation": "warehouse.view.read", "resource": "weekly_sales", "input": { "columns": ["week", "total"], "limit": 100 } }
+    { "connection": "sales-warehouse", "operation": "warehouse.view.read", "resource": "weekly_sales", "input": { "columns": ["week", "total"], "limit": 100 } },
+    { "connection": "gmail", "operation": "gmail.thread.list", "resource": "inbox", "input": { "limit": 15 } },
+    { "connection": "gmail", "operation": "gmail.message.read", "resource": "inbox", "input": { "messageId": "18f2c3a4b5d6e7f8" } }
   ]
 }