@fourier-labs/harbour-contracts 0.46.0 → 0.50.0

package/gen-ts/saas-connection.ts

@@ -1,63 +1,109 @@
 /* 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, gmail.message.send). Never warehouse.view.read.
    *
    * @minItems 1
-   * @maxItems 2
+   * @maxItems 5
    */
-  operations: ('slack.channel.history' | 'slack.message.post')[];
+  operations: (
+    | 'slack.channel.history'
+    | 'slack.message.post'
+    | 'gmail.thread.list'
+    | 'gmail.message.read'
+    | 'gmail.message.send'
+    | '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 +115,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/gen-ts/transform-report.ts

@@ -6,6 +6,8 @@
  */
 export type TransformReport = {
   /**
+   * Optional self-report of the playbooks the agent says it applied. A claim about its own behaviour is not evidence, so nothing validates it; a deployable report may omit it, and one that still carries it stays valid.
+   *
    * @minItems 1
    */
   applied_playbooks?: string[];

package/gen-ts/well-defined-app-manifest.ts

@@ -18,6 +18,7 @@ export type Workload = {
  */
 export type Command = string[];
 export type ResourceProfile = 'standard' | 'memory-1g' | 'memory-2g';
+export type Capability = 'data' | 'files' | 'actions' | 'realtime' | 'telemetry';
 
 /**
  * Versioned provisioning input emitted by Harbour Transform. It describes runtime wiring and workload lifecycle only; PostgreSQL grants and RLS remain the database authorization authority.
@@ -37,6 +38,17 @@ export interface WellDefinedAppManifest {
    * @maxItems 128
    */
   bindings: WorkloadBinding[];
+  /**
+   * Optional language runtime the application container is built on, spelled exactly as transform-report.application.runtime does (nodejs22, python3.11). Optional so a manifest written before the producer emits it still validates.
+   */
+  runtime?: string;
+  /**
+   * Optional declaration of the Harbour browser capabilities the application uses. Same closed set as the app-capabilities document; this is the declaration, not a source scan.
+   *
+   * @maxItems 5
+   */
+  capabilities?: Capability[];
+  routeAuth?: RouteAuth;
 }
 export interface QueueConsumer {
   logicalName: string;
@@ -68,3 +80,22 @@ export interface WorkloadBinding {
    */
   reference?: string;
 }
+/**
+ * Optional method/path authentication policy. Omitted means every route requires Harbour SSO, the same default the policy states explicitly.
+ */
+export interface RouteAuth {
+  default: 'sso_required';
+  /**
+   * @maxItems 64
+   */
+  public: PublicRoute[];
+}
+export interface PublicRoute {
+  path: string;
+  /**
+   * @minItems 1
+   * @maxItems 7
+   */
+  methods: ('GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS')[];
+  mode: 'application_authorized';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour-contracts",
-  "version": "0.46.0",
+  "version": "0.50.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,14 +19,14 @@
   "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"],
-      "description": "Closed operation set. Extending it is a contracts change."
+      "enum": ["slack.channel.history", "slack.message.post", "gmail.thread.list", "gmail.message.read", "gmail.message.send", "warehouse.view.read"],
+      "description": "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."
     },
     "IntegrationIdentityMode": {
       "type": "string",
@@ -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,9 @@
           "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" },
+            "gmail.message.send": { "$ref": "#/definitions/UserModeChannelOperation" },
             "warehouse.view.read": { "$ref": "#/definitions/AppModeViewOperation" }
           }
         }
@@ -112,7 +120,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"] }, { "required": ["gmail.message.send"] }] }
           }
         }
       }
@@ -129,6 +137,14 @@
             "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"] },
+            "gmail.message.send": { "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": [