@fourier-labs/harbour-contracts 0.44.0 → 0.45.0

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

@@ -0,0 +1,3 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+export {};

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

@@ -0,0 +1,52 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+export type IntegrationConnectionKind = 'saas' | 'database';
+/**
+ * Tenant-wide logical alias of a connection (governance sourceId) or of a resource under it.
+ */
+export type IntegrationAlias = string;
+/**
+ * @minItems 1
+ * @maxItems 64
+ */
+export type ResourceNames = IntegrationAlias[];
+
+/**
+ * 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.
+ */
+export interface AppIntegrationsDeclaration {
+  schema: 'harbour.app-integrations/2.0';
+  connections: {
+    [k: string]: DeclaredConnection;
+  };
+}
+export interface DeclaredConnection {
+  kind: IntegrationConnectionKind;
+  operations: {
+    'slack.channel.history'?: UserModeChannelOperation;
+    'slack.message.post'?: AppModeChannelOperation;
+    'warehouse.view.read'?: AppModeViewOperation;
+  };
+}
+export interface UserModeChannelOperation {
+  identity: 'user';
+  resources: ResourceNames;
+}
+export interface AppModeChannelOperation {
+  identity: 'app';
+  resources: ResourceNames;
+}
+export interface AppModeViewOperation {
+  identity: 'app';
+  resources: {
+    [k: string]: ViewResource;
+  };
+}
+export interface ViewResource {
+  /**
+   * @minItems 1
+   * @maxItems 32
+   */
+  columns: string[];
+}

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.44.0.0" as const;
-export const ContractPublishVersion = "0.44.0" as const;
-export const ContractPublishTag = "v0.44.0" as const;
-export const ContractSchemasDigest = "sha256:a83a5d65514b34668ba1aea770f626585b24d07c7bfcc5bb68cf6382a8b6ff6c" as const;
+export const ContractRepositoryVersion = "0.45.0.0" as const;
+export const ContractPublishVersion = "0.45.0" as const;
+export const ContractPublishTag = "v0.45.0" as const;
+export const ContractSchemasDigest = "sha256:4cef9cebaaa623a613cb8c748558a9ac5d3622aeca31138f17c983cd8cfb6eb3" as const;
 export const ContractAiFixturesDigest = "sha256:edac31c92e146ca1c40130f2fb5649db82e24b8cd1ac758153b90612052fddb6" as const;
-export const ContractGeneratedGoDigest = "sha256:95f1e5ec97ac5883d529af6442fa58ae3a59bb3e00d4b5852d03049e23cb7f4d" as const;
-export const ContractGeneratedTypeScriptDigest = "sha256:49048cdb1c9ec15433f6cb7d4fa42d6f39a5fc5da48c9d2c3b4b2ef0c2b39b3d" as const;
+export const ContractGeneratedGoDigest = "sha256:4134b582754e02f9248bcb579a4ec335da3ab1d87d92b3720d9ac8ee3cb1eec1" as const;
+export const ContractGeneratedTypeScriptDigest = "sha256:a57c25fdfbb06518e95bade4dd57441d39a2bb3f11fbbd8d78df5e8773d0ca9b" as const;

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

@@ -0,0 +1,98 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * Grant lifecycle state. Legal edges live in x-transitions; DENIED and REVOKED are terminal.
+ */
+export type DataGrantV2Status = 'REQUESTED' | 'GRANTED' | 'DENIED' | 'REVOKED';
+/**
+ * Provider-side work for the current approved scope (credential mint, cleanup, installation check).
+ */
+export type DataGrantV2ProvisioningStatus = 'NONE' | '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. 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.
+ */
+export interface DataGrantV2 {
+  schema: 'harbour.data-grant/2.0';
+  appId: string;
+  /**
+   * Tenant-wide logical alias of a connection (governance sourceId) or of a resource under it.
+   */
+  sourceId: string;
+  kind: 'saas' | 'database';
+  /**
+   * development is the CLI/local kit; preview and production are hosted.
+   */
+  environment: 'development' | 'preview' | 'production';
+  /**
+   * Whose authority an operation runs under. Fixed per operation; callers never choose it.
+   */
+  identityMode: 'app' | 'user';
+  status: DataGrantV2Status;
+  /**
+   * Approved operations; each must match this grant's identityMode.
+   *
+   * @minItems 1
+   * @maxItems 3
+   */
+  operations: ('slack.channel.history' | 'slack.message.post' | 'warehouse.view.read')[];
+  /**
+   * Approved logical resource names (channel aliases or view names). Never inherited by wildcard.
+   *
+   * @minItems 1
+   * @maxItems 64
+   */
+  resources: string[];
+  /**
+   * Absent only for explicitly approved ongoing production access.
+   */
+  expiresAt?: string;
+  approvedBy?: string;
+  /**
+   * Optimistic-concurrency version; approvals compare it with the reviewed value.
+   */
+  version: number;
+  /**
+   * The one open access request attached to this grant, if any.
+   */
+  pendingRequestId?: string;
+  provisioning: DataGrantV2Provisioning;
+  /**
+   * Database grants: secretref://tenant/{t}/app/{a}/env/{env}/source/{s}.
+   */
+  credentialRef?: string;
+  /**
+   * Database grants: the deterministic per tenant/app/environment/source principal.
+   */
+  mintedPrincipal?: string;
+  /**
+   * SaaS grants: the connection installation this environment maps to.
+   */
+  installation?: string;
+}
+export interface DataGrantV2Provisioning {
+  status: DataGrantV2ProvisioningStatus;
+  /**
+   * Failed attempts; three requires an admin retry.
+   */
+  attempts: number;
+  /**
+   * Sanitized reason; never a provider error body.
+   */
+  lastError?: string;
+}
+
+const legalDataGrantV2StatusTransitions: Record<string, Record<string, true>> = {
+  "REQUESTED": { "GRANTED": true, "DENIED": true },
+  "GRANTED": { "REVOKED": true },
+};
+const terminalDataGrantV2StatusStates = new Set<string>(["DENIED", "REVOKED"]);
+
+/** True iff from→to is a legal DataGrantV2Status edge (schema x-transitions). */
+export function canTransitionDataGrantV2Status(from: string, to: string): boolean {
+  return Boolean(legalDataGrantV2StatusTransitions[from]?.[to]);
+}
+
+/** True iff the DataGrantV2Status is terminal (DENIED, REVOKED). */
+export function isTerminalDataGrantV2Status(state: string): boolean { return terminalDataGrantV2StatusStates.has(state); }

package/gen-ts/index.ts

@@ -22,12 +22,14 @@ export * from './ai-transform-event.js';
 export * from './ai-transform-result.js';
 export * from './ai-verification-evidence.js';
 export * from './api-error-response.js';
+export * from './app-integrations-declaration.js';
 export * from './artifact-contract.js';
 export * from './binding-classification-digest-helper.js';
 export * from './binding-classification-subject.js';
 export * from './builder-input-proposal.js';
 export * from './contract-release.js';
 export * from './data-dependency.js';
+export * from './data-grant-v2.js';
 export * from './data-grant.js';
 export * from './data-source.js';
 export * from './deploy-request.js';
@@ -42,9 +44,16 @@ export * from './env-bindings.js';
 export * from './error-category-registry.js';
 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-request.js';
+export * from './integration-execute-result.js';
+export * from './kit-bundle-manifest.js';
+export * from './kit-lock.js';
 export * from './kvs-routing-entry.js';
 export * from './promotion-request.js';
 export * from './promotion-response.js';
+export * from './saas-connection.js';
 export * from './sanitized-binding-digest-helper.js';
 export * from './sanitized-binding-evidence.js';
 export * from './secret-reference.js';

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

@@ -0,0 +1,21 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * The `data` member of the connect (POST) and disconnect (DELETE) responses on /_harbour/integrations/connect. connected: this user's consent link for the app/environment/connection is ACTIVE (accountLabel is a display label, never an ID or token); consent_required: the user must follow authorizationUrl (governance OAuth start with an opaque ticket); disconnected: only this user's consent for this app/environment was revoked. Connect is a user action and never requests IT app approval.
+ */
+export type IntegrationConnectResult = {
+  status: 'connected' | 'consent_required' | 'disconnected';
+  accountLabel?: string;
+  authorizationUrl?: string;
+} & (
+  | {
+      status?: 'connected';
+    }
+  | {
+      status?: 'consent_required';
+    }
+  | {
+      status?: 'disconnected';
+    }
+);

package/gen-ts/integration-error-details.ts

@@ -0,0 +1,47 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * App-SDK HarbourErrorCategory values an integration route may emit; INTERNAL is reserved for the transport.
+ */
+export type IntegrationErrorCategory =
+  'AUTH_REQUIRED' | 'FORBIDDEN' | 'NOT_FOUND' | 'CONFLICT' | 'VALIDATION_FAILED' | 'RATE_LIMITED' | 'UNAVAILABLE';
+/**
+ * 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.
+ */
+export type IntegrationErrorCode =
+  | 'USER_CONNECTION_REQUIRED'
+  | 'USER_RECONNECT_REQUIRED'
+  | 'GRANT_NOT_READY'
+  | 'GRANT_EXPIRED'
+  | 'GRANT_REVOKED'
+  | 'CONNECTION_DISABLED'
+  | 'OPERATION_NOT_DECLARED'
+  | 'RESOURCE_NOT_APPROVED'
+  | 'IDENTITY_MODE_MISMATCH'
+  | 'SEND_OUTCOME_UNKNOWN'
+  | 'SEND_KEY_REUSED'
+  | 'PROVIDER_RATE_LIMITED'
+  | 'PROVIDER_UNAVAILABLE'
+  | 'REQUEST_TOO_LARGE'
+  | 'RESULT_TOO_LARGE'
+  | 'DEADLINE_EXCEEDED'
+  | 'APP_ACCESS_REQUIRED'
+  | 'GRANT_DENIED'
+  | 'TOKEN_REFRESH_PENDING'
+  | 'REQUEST_PENDING';
+
+/**
+ * The `error` member of an integration failure response `{error, requestId}` on the execute/connect routes; the SDK maps it onto HarbourError(category, message, details). `category` is the app-SDK HarbourErrorCategory (not the deployment pipeline's dot-path error-category registry), with the HTTP status fixed per category: 401 AUTH_REQUIRED, 403 FORBIDDEN (denied/revoked/expired), 404 NOT_FOUND (unknown app/connection/resource), 409 CONFLICT (pending provisioning/consent/concurrent request), 400 or 413 VALIDATION_FAILED (invalid input / size overflow), 429 RATE_LIMITED (+ Retry-After header), 503 UNAVAILABLE. `details.code` is the closed stable reason set; `message` is human-facing and never carries provider error bodies, tokens or SQL.
+ */
+export interface IntegrationErrorDetails {
+  category: IntegrationErrorCategory;
+  message: string;
+  details: {
+    code: IntegrationErrorCode;
+    /**
+     * Mirrors the Retry-After header on RATE_LIMITED responses.
+     */
+    retryAfterSeconds?: number;
+  };
+}

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

@@ -0,0 +1,33 @@
+/* eslint-disable */
+// 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; warehouse.view.read {columns 1..32, limit? 1..1000, default 100}. Transport limits (not expressible here): request <= 16 KiB, total deadline 10 s.
+ */
+export type IntegrationExecuteRequest = {
+  /**
+   * Tenant-wide logical alias of a connection (governance sourceId) or of a resource under it.
+   */
+  connection: string;
+  /**
+   * Closed operation set. Extending it is a contracts change.
+   */
+  operation: 'slack.channel.history' | 'slack.message.post' | 'warehouse.view.read';
+  /**
+   * Tenant-wide logical alias of a connection (governance sourceId) or of a resource under it.
+   */
+  resource: string;
+  input: {
+    limit?: number;
+    text?: string;
+    /**
+     * @minItems 1
+     * @maxItems 32
+     */
+    columns?: string[];
+  };
+  /**
+   * UUID of one explicit Send action; required for slack.message.post only. The same key with the same payload and subject returns the recorded outcome for seven days.
+   */
+  idempotencyKey?: string;
+};

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

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

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

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

package/gen-ts/kit-lock.ts

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

package/gen-ts/saas-connection.ts

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

package/package.json

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

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

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