@fourier-labs/harbour-contracts 0.50.0 → 0.53.0

package/gen-ts/transform-report.ts

@@ -2,7 +2,7 @@
 // Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
 
 /**
- * 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 = {
   /**
@@ -11,23 +11,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;
@@ -35,29 +45,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.
@@ -75,12 +102,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: (
+      boundaries?: (
         | 'application'
         | 'routing'
         | 'database'
@@ -159,7 +186,10 @@ export type TransformReport = {
      * @maxItems 8
      */
     uncovered: {
-      boundary:
+      /**
+       * 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'
@@ -247,7 +277,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?: {
@@ -271,6 +307,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';
@@ -285,6 +324,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour-contracts",
-  "version": "0.50.0",
+  "version": "0.53.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

@@ -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 (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.",
+  "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 (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.",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema", "connections"],
@@ -26,18 +26,34 @@
     "IntegrationOperation": {
       "type": "string",
       "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."
+      "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. 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)."
     },
     "IntegrationIdentityMode": {
       "type": "string",
       "enum": ["app", "user"],
-      "description": "Whose authority an operation runs under. Fixed per operation; callers never choose it."
+      "description": "Whose authority an operation runs under. Fixed per operation (slack.message.post: declared per app); never chosen at call time."
     },
     "IntegrationEnvironment": {
       "type": "string",
       "enum": ["development", "preview", "production"],
       "description": "development is the CLI/local kit; preview and production are hosted."
     },
+    "IntegrationPresentation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["displayName"],
+      "description": "How an app's app-mode Slack posts are presented (0.53.0): the display name and optional icon the platform bot posts under, so each app's posts are distinguishable while the bot stays the one audited identity. Declared by the app, shown to IT on the access request (\"posts as\"), copied onto the approved grant and applied only from there — a call can never name itself. Needs the Slack app scope chat:write.customize on the tenant's installation; without it the post goes out under the bot's own name and the receipt says so.",
+      "properties": {
+        "displayName": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80,
+          "pattern": "^(?!\\s*$)(?!.*(^|[\\s(\\[<\"'])@[A-Za-z0-9_])(?!.*<@)[^\\u0000-\\u001F\\u007F]*$",
+          "description": "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."
+        },
+        "iconEmoji": { "type": "string", "pattern": "^:[a-z0-9_+-]{1,60}:$", "description": "A Slack emoji shortcode such as `:sandwich:`; absent keeps the bot's own icon." }
+      }
+    },
     "ColumnName": {
       "type": "string",
       "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,62}$",
@@ -71,12 +87,13 @@
         "resources": { "$ref": "#/definitions/ResourceNames" }
       }
     },
-    "AppModeChannelOperation": {
+    "DeclaredModeChannelOperation": {
       "type": "object",
       "additionalProperties": false,
       "required": ["identity", "resources"],
+      "description": "slack.message.post: the app declares the mode — app (posts as the company's Slack app) or user (posts as the signed-in person).",
       "properties": {
-        "identity": { "type": "string", "const": "app" },
+        "identity": { "$ref": "#/definitions/IntegrationIdentityMode" },
         "resources": { "$ref": "#/definitions/ResourceNames" }
       }
     },
@@ -101,13 +118,14 @@
       "required": ["kind", "operations"],
       "properties": {
         "kind": { "$ref": "#/definitions/IntegrationConnectionKind" },
+        "presentation": { "$ref": "#/definitions/IntegrationPresentation", "description": "saas connections only (Slack): how this app's app-mode posts are presented; meaningless for every other operation." },
         "operations": {
           "type": "object",
           "additionalProperties": false,
           "minProperties": 1,
           "properties": {
             "slack.channel.history": { "$ref": "#/definitions/UserModeChannelOperation" },
-            "slack.message.post": { "$ref": "#/definitions/AppModeChannelOperation" },
+            "slack.message.post": { "$ref": "#/definitions/DeclaredModeChannelOperation" },
             "gmail.thread.list": { "$ref": "#/definitions/UserModeChannelOperation" },
             "gmail.message.read": { "$ref": "#/definitions/UserModeChannelOperation" },
             "gmail.message.send": { "$ref": "#/definitions/UserModeChannelOperation" },
@@ -118,6 +136,7 @@
       "if": { "properties": { "kind": { "const": "saas" } } },
       "then": { "properties": { "operations": { "not": { "required": ["warehouse.view.read"] } } } },
       "else": {
+        "not": { "required": ["presentation"] },
         "properties": {
           "operations": {
             "not": { "anyOf": [{ "required": ["slack.channel.history"] }, { "required": ["slack.message.post"] }, { "required": ["gmail.thread.list"] }, { "required": ["gmail.message.read"] }, { "required": ["gmail.message.send"] }] }
@@ -132,6 +151,7 @@
       "connections": {
         "company-slack": {
           "kind": "saas",
+          "presentation": { "displayName": "Lunch Vote", "iconEmoji": ":sandwich:" },
           "operations": {
             "slack.channel.history": { "identity": "user", "resources": ["team-updates"] },
             "slack.message.post": { "identity": "app", "resources": ["team-updates"] }
@@ -155,6 +175,17 @@
           }
         }
       }
+    },
+    {
+      "schema": "harbour.app-integrations/2.0",
+      "connections": {
+        "company-slack": {
+          "kind": "saas",
+          "operations": {
+            "slack.message.post": { "identity": "user", "resources": ["team-updates"] }
+          }
+        }
+      }
     }
   ]
 }

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

@@ -2,7 +2,7 @@
   "$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. 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.",
+  "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. 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.",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema", "tenantId", "appId", "environment", "sourceId", "mode", "kind", "status", "operations", "resources", "version", "provisioning", "createdAt", "updatedAt"],
@@ -35,6 +35,7 @@
     "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." },
+    "presentation": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationPresentation", "description": "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." },
     "provisioning": { "$ref": "#/definitions/DataGrantV2Provisioning" },
     "credentialRef": {
       "type": "string",

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; 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.",
+  "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 (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.",
   "type": "object",
   "additionalProperties": false,
   "required": ["connection", "operation", "resource", "input"],
@@ -14,8 +14,8 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "limit": { "type": "integer", "minimum": 1, "maximum": 1000 },
-        "text": { "type": "string", "minLength": 1, "maxLength": 4000 },
+        "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "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." },
+        "text": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "slack.message.post / gmail.message.send: the plain-text body, 1..4000 characters." },
         "messageId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "gmail.message.read: the Gmail message id a gmail.thread.list result named." },
         "to": { "$ref": "#/definitions/EmailAddressList", "description": "gmail.message.send: primary recipients." },
         "cc": { "$ref": "#/definitions/EmailAddressList", "description": "gmail.message.send: carbon-copy recipients." },
@@ -42,7 +42,7 @@
       "then": {
         "not": { "required": ["idempotencyKey"] },
         "properties": {
-          "input": { "properties": { "limit": { "maximum": 15 } }, "not": { "anyOf": [{ "required": ["text"] }, { "required": ["columns"] }, { "required": ["messageId"] }, { "required": ["to"] }, { "required": ["subject"] }] } }
+          "input": { "propertyNames": { "enum": ["limit"] }, "properties": { "limit": { "maximum": 15, "default": 15 } } }
         }
       }
     },
@@ -51,7 +51,7 @@
       "then": {
         "required": ["idempotencyKey"],
         "properties": {
-          "input": { "required": ["text"], "not": { "anyOf": [{ "required": ["limit"] }, { "required": ["columns"] }, { "required": ["messageId"] }, { "required": ["to"] }, { "required": ["subject"] }] } }
+          "input": { "propertyNames": { "enum": ["text"] }, "required": ["text"] }
         }
       }
     },
@@ -60,7 +60,7 @@
       "then": {
         "not": { "required": ["idempotencyKey"] },
         "properties": {
-          "input": { "required": ["columns"], "not": { "anyOf": [{ "required": ["text"] }, { "required": ["messageId"] }, { "required": ["to"] }, { "required": ["subject"] }] } }
+          "input": { "propertyNames": { "enum": ["columns", "limit"] }, "required": ["columns"], "properties": { "limit": { "maximum": 1000, "default": 100 } } }
         }
       }
     },
@@ -69,7 +69,7 @@
       "then": {
         "not": { "required": ["idempotencyKey"] },
         "properties": {
-          "input": { "properties": { "limit": { "maximum": 15 } }, "not": { "anyOf": [{ "required": ["text"] }, { "required": ["columns"] }, { "required": ["messageId"] }, { "required": ["to"] }, { "required": ["subject"] }] } }
+          "input": { "propertyNames": { "enum": ["limit"] }, "properties": { "limit": { "maximum": 15, "default": 15 } } }
         }
       }
     },
@@ -78,7 +78,7 @@
       "then": {
         "not": { "required": ["idempotencyKey"] },
         "properties": {
-          "input": { "required": ["messageId"], "not": { "anyOf": [{ "required": ["text"] }, { "required": ["columns"] }, { "required": ["limit"] }, { "required": ["to"] }, { "required": ["subject"] }] } }
+          "input": { "propertyNames": { "enum": ["messageId"] }, "required": ["messageId"] }
         }
       }
     },
@@ -87,7 +87,7 @@
       "then": {
         "required": ["idempotencyKey"],
         "properties": {
-          "input": { "required": ["to", "subject", "text"], "not": { "anyOf": [{ "required": ["limit"] }, { "required": ["columns"] }, { "required": ["messageId"] }] } }
+          "input": { "propertyNames": { "enum": ["to", "cc", "bcc", "subject", "text", "replyToMessageId"] }, "required": ["to", "subject", "text"] }
         }
       }
     }

package/schema/saas-connection.schema.json

@@ -94,7 +94,8 @@
         "workspaceId": { "type": "string", "minLength": 1, "maxLength": 128 },
         "botUserId": { "type": "string", "maxLength": 128, "description": "Empty only for a legacy record normalised without one." },
         "status": { "$ref": "#/definitions/SaasInstallationStatus" },
-        "installedAt": { "type": "string", "format": "date-time" }
+        "installedAt": { "type": "string", "format": "date-time" },
+        "scopes": { "type": "array", "maxItems": 64, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "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." }
       }
     },
     "DevelopmentPreapproval": {
@@ -144,7 +145,7 @@
       "displayName": "Company Slack",
       "status": "ACTIVE",
       "version": 3,
-      "installation": { "tokenRecordId": "tok_workspace", "workspaceId": "T0WORKSPACE", "botUserId": "U0BOT", "status": "installed", "installedAt": "2026-09-09T08:00:00Z" },
+      "installation": { "tokenRecordId": "tok_workspace", "workspaceId": "T0WORKSPACE", "botUserId": "U0BOT", "status": "installed", "installedAt": "2026-09-09T08:00:00Z", "scopes": ["channels:read", "chat:write", "chat:write.customize"] },
       "channels": { "team-updates": "C0123TEAM" },
       "operations": ["slack.channel.history", "slack.message.post"],
       "developmentPreapproval": { "enabled": true, "hours": 24 },

package/schema/transform-report.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://schemas.harbour.dev/transform-report.schema.json",
   "title": "TransformReport",
-  "description": "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.",
+  "description": "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.",
   "x-go-embed": true,
   "type": "object",
   "additionalProperties": false,
@@ -14,26 +14,34 @@
       "minItems": 1,
       "items": { "type": "string", "minLength": 1 }
     },
-    "static_rebuild_required": { "type": "boolean" },
+    "static_rebuild_required": {
+      "description": "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.",
+      "type": "boolean"
+    },
     "analysis": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["deployable", "needsTransformation", "blockers", "surfaces", "evidence"],
+      "required": ["deployable", "blockers"],
       "properties": {
         "deployable": { "type": "boolean" },
-        "needsTransformation": { "type": "boolean" },
+        "needsTransformation": {
+          "description": "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.",
+          "type": "boolean"
+        },
         "blockers": {
           "type": "array",
           "maxItems": 64,
           "items": { "type": "string", "minLength": 1, "maxLength": 1024 }
         },
         "surfaces": {
+          "description": "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.",
           "type": "array",
           "minItems": 1,
           "maxItems": 1024,
           "items": { "type": "string", "minLength": 1, "maxLength": 512 }
         },
         "evidence": {
+          "description": "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.",
           "type": "array",
           "maxItems": 1024,
           "items": {
@@ -52,35 +60,36 @@
     "database": {
       "type": "object",
       "additionalProperties": false,
-      "required": [
-        "mode",
-        "changeType",
-        "requiresCodeChanges",
-        "requiresSchemaMigration",
-        "migrationPaths",
-        "changedFiles",
-        "evidence",
-        "unsupportedFeatures"
-      ],
+      "required": ["mode"],
       "properties": {
         "mode": { "type": "string", "enum": ["none", "sql"] },
         "changeType": {
+          "description": "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.",
           "type": "string",
           "enum": ["none", "code_only", "schema_only", "code_and_schema"]
         },
-        "requiresCodeChanges": { "type": "boolean" },
-        "requiresSchemaMigration": { "type": "boolean" },
+        "requiresCodeChanges": {
+          "description": "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.",
+          "type": "boolean"
+        },
+        "requiresSchemaMigration": {
+          "description": "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.",
+          "type": "boolean"
+        },
         "migrationPaths": {
+          "description": "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.",
           "type": "array",
           "maxItems": 128,
           "items": { "type": "string", "minLength": 1, "maxLength": 512 }
         },
         "changedFiles": {
+          "description": "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.",
           "type": "array",
           "maxItems": 512,
           "items": { "type": "string", "minLength": 1, "maxLength": 512 }
         },
         "evidence": {
+          "description": "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.",
           "type": "array",
           "maxItems": 128,
           "items": {
@@ -95,6 +104,7 @@
           }
         },
         "unsupportedFeatures": {
+          "description": "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.",
           "type": "array",
           "maxItems": 64,
           "items": { "type": "string", "minLength": 1, "maxLength": 512 }
@@ -116,13 +126,13 @@
           "items": {
             "type": "object",
             "additionalProperties": false,
-            "required": ["id", "kind", "name", "boundaries", "evidence", "confidence", "steps"],
+            "required": ["id", "kind", "name", "evidence", "confidence", "steps"],
             "properties": {
               "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" },
               "kind": { "type": "string", "enum": ["happy_path", "boundary_check"] },
               "name": { "type": "string", "minLength": 1, "maxLength": 120 },
               "boundaries": {
-                "description": "Transformation boundaries this test claims to cover.",
+                "description": "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.",
                 "type": "array",
                 "minItems": 1,
                 "maxItems": 8,
@@ -202,9 +212,10 @@
           "items": {
             "type": "object",
             "additionalProperties": false,
-            "required": ["boundary", "reason"],
+            "required": ["reason"],
             "properties": {
               "boundary": {
+                "description": "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.",
                 "type": "string",
                 "enum": ["application", "routing", "database", "authentication", "runtime_dependency", "files", "provider", "background_work"]
               },
@@ -390,8 +401,13 @@
             { "type": "null" }
           ]
         },
-        "buildKind": { "type": "string", "enum": ["container", "static"] },
+        "buildKind": {
+          "description": "Optional: determined by topology (static topology iff static build), so a deployable report may omit it and one that still carries it stays valid.",
+          "type": "string",
+          "enum": ["container", "static"]
+        },
         "topology": {
+          "description": "Optional: determined by the build output kinds, so a deployable report may omit it and one that still carries it stays valid.",
           "type": "string",
           "enum": ["static", "backend", "frontend_and_backend"]
         },
@@ -434,6 +450,7 @@
           }
         },
         "basePath": {
+          "description": "Optional: both members are platform constants, so a deployable report may omit this object and one that still carries it stays valid.",
           "type": "object",
           "additionalProperties": false,
           "required": ["required", "environmentVariable"],
@@ -458,6 +475,7 @@
           }
         },
         "unsupportedFeatures": {
+          "description": "Optional: a deployable plan requires this empty, so a deployable report may omit it and one that still carries it (empty) stays valid.",
           "type": "array",
           "maxItems": 64,
           "items": { "type": "string", "minLength": 1, "maxLength": 512 }
@@ -667,10 +685,10 @@
   ],
   "oneOf": [
     {
-      "required": ["static_rebuild_required", "analysis", "database", "preservation_plan", "validation_fixtures", "application"],
+      "required": ["analysis", "database", "preservation_plan", "application"],
       "properties": {
         "application": {
-          "required": ["runtime", "buildKind", "topology", "entrypoint", "build", "basePath", "evidence", "unsupportedFeatures"],
+          "required": ["runtime", "entrypoint", "build", "evidence"],
           "not": { "required": ["unsupported"] }
         }
       }