@company-semantics/contracts 14.0.0 → 15.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "14.0.0",
+  "version": "15.1.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -119,7 +119,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.9.3",
+    "@types/node": "^22.10.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.7",
     "markdownlint-cli2": "^0.22.1",

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = '16c3b86cc35a' as const;
-export const SPEC_HASH_FULL = '16c3b86cc35a3f329766b702414438de4950430991a603372f1335206c96b600' as const;
+export const SPEC_HASH = '575c0e0c7f6c' as const;
+export const SPEC_HASH_FULL = '575c0e0c7f6c7fdec000c8914101c527ed9e783b38bbfbe5aab536200d1b1da1' as const;

package/src/api/generated.ts

@@ -736,6 +736,23 @@ export interface paths {
         patch: operations["setMemberManager"];
         trace?: never;
     };
+    "/api/chat/interactive-tasks/submit": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Submit a filled-in interactive chat task (creates + runs a governed execution) */
+        post: operations["submitInteractiveTask"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/rbac/roles": {
         parameters: {
             query?: never;
@@ -3650,6 +3667,21 @@ export interface components {
             /** Format: uuid */
             managerUserId: string;
         };
+        SubmitInteractiveTaskResponse: {
+            executionId: string;
+            /** @enum {string} */
+            status: "executing" | "completed" | "failed" | "pending_confirmation";
+        };
+        SubmitInteractiveTaskRequest: {
+            /** Format: uuid */
+            taskId: string;
+            /** @constant */
+            taskKind: "member.changeManager";
+            /** Format: uuid */
+            memberId: string;
+            newManagerUserId: string | null;
+            chatId: string;
+        };
         RoleCatalogResponse: {
             roles: {
                 name: string;
@@ -3920,7 +3952,7 @@ export interface components {
             summary: {
                 executionId: string;
                 /** @enum {string} */
-                kind: "integration.connect" | "integration.disconnect" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup";
+                kind: "integration.connect" | "integration.disconnect" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager";
                 target: {
                     /** @constant */
                     type: "slack";
@@ -6536,6 +6568,30 @@ export interface operations {
             };
         };
     };
+    submitInteractiveTask: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SubmitInteractiveTaskRequest"];
+            };
+        };
+        responses: {
+            /** @description Execution created and run through the governance engine */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SubmitInteractiveTaskResponse"];
+                };
+            };
+        };
+    };
     getRbacRoles: {
         parameters: {
             query?: never;
@@ -7073,7 +7129,7 @@ export interface operations {
             query?: {
                 cursor?: string;
                 limit?: number;
-                kind?: "integration.connect" | "integration.disconnect" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup";
+                kind?: "integration.connect" | "integration.disconnect" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager";
                 targetType?: string;
                 periodStart?: string;
                 periodEnd?: string;
@@ -7208,7 +7264,7 @@ export interface operations {
             query?: {
                 limit?: number;
                 offset?: number;
-                kind?: "integration.connect" | "integration.disconnect" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup";
+                kind?: "integration.connect" | "integration.disconnect" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager";
                 kindPrefix?: string;
             };
             header?: never;

package/src/email/types.ts

@@ -70,7 +70,7 @@ export interface EmailPayloads {
     /** Name of the org unit / team the access applies to */
     unitName: string;
     /** Human-readable role label the recipient was given */
-    roleLabel: "Leader" | "Delegate";
+    roleLabel: "Unit owner" | "Delegate";
     /** Full URL to view the org unit in the app */
     ctaUrl: string;
     /** Optional message from the granter, shown in the email and recorded with the grant */

package/src/execution/__tests__/registry.test.ts

@@ -156,6 +156,28 @@ describe("EXECUTION_KINDS golden snapshot", () => {
           templateId: "system-cleanup",
         },
       },
+      "member.changeManager": {
+        kind: "member.changeManager",
+        domain: "organization",
+        display: {
+          label: "Change Reporting Manager",
+          pastTenseLabel: "Reporting manager changed",
+          icon: "pencil",
+        },
+        governance: {
+          visibility: "user",
+          requiresAdmin: false,
+          reversibleBy: "member.changeManager",
+        },
+        ui: {
+          showInAdmin: false,
+          showInTimeline: true,
+          confirmBeforeRun: true,
+        },
+        explanation: {
+          templateId: "member-change-manager",
+        },
+      },
     });
   });
 });

package/src/execution/kinds.ts

@@ -29,4 +29,5 @@ export type ExecutionKind =
   | "slack.send"
   | "data.ingest"
   | "data.scope"
-  | "system.cleanup";
+  | "system.cleanup"
+  | "member.changeManager";

package/src/execution/registry.ts

@@ -181,6 +181,29 @@ export const EXECUTION_KINDS = {
       templateId: "system-cleanup",
     },
   },
+  "member.changeManager": {
+    kind: "member.changeManager",
+    domain: "organization",
+    display: {
+      label: "Change Reporting Manager",
+      pastTenseLabel: "Reporting manager changed",
+      icon: "pencil",
+    },
+    governance: {
+      visibility: "user",
+      requiresAdmin: false,
+      // Reversible: re-applying the previous solid-line edge undoes the change.
+      reversibleBy: "member.changeManager",
+    },
+    ui: {
+      showInAdmin: false,
+      showInTimeline: true,
+      confirmBeforeRun: true,
+    },
+    explanation: {
+      templateId: "member-change-manager",
+    },
+  },
 } as const satisfies Record<ExecutionKind, ExecutionKindDefinition>;
 
 // =============================================================================

package/src/execution/types.ts

@@ -38,7 +38,8 @@ export type ExecutionDomain =
   | "data"
   | "system"
   | "profile"
-  | "communication";
+  | "communication"
+  | "organization";
 
 // =============================================================================
 // Execution Kind Definition

package/src/generated/openapi-routes.ts

@@ -11,6 +11,7 @@ export const openApiRoutes = {
   '/api/account/sessions/{sessionId}': ['DELETE'],
   '/api/auth/consent/grant': ['POST'],
   '/api/capabilities': ['GET'],
+  '/api/chat/interactive-tasks/submit': ['POST'],
   '/api/chats': ['GET', 'POST'],
   '/api/chats/by-interaction/{interactionId}': ['GET'],
   '/api/chats/events': ['GET'],

package/src/index.ts

@@ -454,6 +454,15 @@ export type {
   ConfirmationData,
   ConfirmationResponseData,
   ConfirmationDataPart,
+  // Interactive task surface types (editable surfaces)
+  InteractiveTaskKind,
+  CandidateSource,
+  InteractiveFieldType,
+  InteractiveFieldDescriptor,
+  InteractiveTaskSubject,
+  InteractiveTaskData,
+  InteractiveTaskPart,
+  InteractiveTaskDataPart,
   // Execution result types (Phase 5)
   ExecutionArtifactStatus,
   ExecutionResultSummary,

package/src/message-parts/__tests__/confirmation.test.ts

@@ -119,6 +119,7 @@ describe("CONFIRMATION_LABELS", () => {
       "data.ingest": "Import Channel",
       "data.scope": "Update Scope",
       "system.cleanup": "Cleanup Connections",
+      "member.changeManager": "Change Reporting Manager",
     });
   });
 });

package/src/message-parts/confirmation.ts

@@ -47,6 +47,7 @@ export const CONFIRMATION_LABELS: Record<ExecutionKind, string> = {
   "data.ingest": "Import Channel",
   "data.scope": "Update Scope",
   "system.cleanup": "Cleanup Connections",
+  "member.changeManager": "Change Reporting Manager",
 };
 
 /**

package/src/message-parts/index.ts

@@ -43,6 +43,18 @@ export type {
 // Confirmation runtime values
 export { CONFIRMATION_LABELS, getConfirmationLabel } from "./confirmation";
 
+// Interactive task surface types
+export type {
+  InteractiveTaskKind,
+  CandidateSource,
+  InteractiveFieldType,
+  InteractiveFieldDescriptor,
+  InteractiveTaskSubject,
+  InteractiveTaskData,
+  InteractiveTaskPart,
+  InteractiveTaskDataPart,
+} from "./interactive";
+
 // Execution result types
 export type {
   ExecutionArtifactStatus,

package/src/message-parts/interactive.ts

@@ -0,0 +1,123 @@
+/**
+ * Interactive Task Surface Types
+ *
+ * Interactive surfaces are EDITABLE: the assistant emits a form the user fills
+ * out inline in chat (e.g. picking a new reporting manager), then submits. They
+ * are the third surface class alongside `preview` (read-only diff) and
+ * `confirmation` (Y/N). Unlike those, an interactive task is PRE-EXECUTION:
+ *
+ * INTERACTIVE TASK INVARIANTS:
+ * - An interactive task carries NO executionId — no execution exists yet. That
+ *   absence is the structural marker distinguishing it from ConfirmationPart
+ *   (which requires an executionId). The execution is born when the user submits.
+ * - The assistant emits an interactive task only when it lacks the parameters to
+ *   produce an exactly-executable preview. Once parameters are known, a normal
+ *   `preview` + `confirmation` flow is used instead.
+ * - The surface collects user input and POSTs it to `submitEndpoint`; the backend
+ *   then runs the governance engine (create execution → execute), so the change
+ *   is audited and reversible like every other chat action.
+ * - At most one GOVERNED surface (preview ∪ interactive) is active per turn.
+ *
+ * @see decisions/ADR-CONTRACTS-068.md for design rationale
+ */
+
+import type { ConfirmationRiskLevel } from "./confirmation";
+
+/**
+ * The set of editable tasks the assistant can present inline.
+ * Mirrors the `{domain}.{verb}` naming of ExecutionKind. Extensible union.
+ */
+export type InteractiveTaskKind = "member.changeManager";
+
+/**
+ * How the frontend sources candidate values for an editable field.
+ * - `inline`: the options are shipped with the part (small, bounded sets).
+ * - `search`: the frontend queries `endpoint` as the user types (large sets).
+ */
+export type CandidateSource =
+  | {
+      kind: "inline";
+      options: Array<{ value: string; label: string; sublabel?: string }>;
+    }
+  | { kind: "search"; endpoint: string; minChars?: number };
+
+/**
+ * The input shape of an editable field.
+ * - `member-ref`: a workspace member id (backed by a member picker).
+ * - `text`: free text.
+ * - `enum`: one of the field's inline candidate options.
+ */
+export type InteractiveFieldType = "member-ref" | "text" | "enum";
+
+/**
+ * One editable field within an interactive task.
+ */
+export interface InteractiveFieldDescriptor {
+  /** Submit key, e.g. "newManagerUserId". */
+  name: string;
+  /** Display label, e.g. "Reports to". */
+  label: string;
+  /** Input shape. */
+  type: InteractiveFieldType;
+  /** Whether the field must be filled before submit is allowed. */
+  required: boolean;
+  /** Whether the field supports an explicit "clear"/empty submission (e.g. "No manager"). */
+  clearable?: boolean;
+  /** Current value (for the diff's "old" half); null when unset. */
+  currentValue?: string | null;
+  /** Human-readable current value (e.g. "Jordan Rivera") for display. */
+  currentLabel?: string | null;
+  /** How to source candidate values; omitted for free `text` fields. */
+  candidates?: CandidateSource;
+}
+
+/**
+ * Read-only subject the task acts upon (e.g. the member being edited).
+ */
+export interface InteractiveTaskSubject {
+  /** Workspace member id (users.id) the task edits. */
+  memberId: string;
+  /** Display name for the surface header. */
+  displayName: string;
+  /** Arbitrary read-only context the surface may render. */
+  context?: Record<string, string>;
+}
+
+/**
+ * Interactive task surface data payload.
+ */
+export interface InteractiveTaskData {
+  /** Stable id for this task; becomes the governance correlation key on submit. */
+  taskId: string;
+  /** Which editable task this is — selects the frontend renderer. */
+  taskKind: InteractiveTaskKind;
+  /** Human-readable summary of what the user is about to change. */
+  title: string;
+  /** Optional detail. */
+  description?: string;
+  /** What the task acts upon. */
+  subject: InteractiveTaskSubject;
+  /** The editable fields. */
+  fields: InteractiveFieldDescriptor[];
+  /** Endpoint the frontend POSTs the filled form to. */
+  submitEndpoint: string;
+  /** Risk level for UI styling; mirrors ConfirmationData.risk. */
+  risk: ConfirmationRiskLevel;
+}
+
+/**
+ * Interactive task message part (semantic type).
+ */
+export interface InteractiveTaskPart {
+  type: "interactive";
+  data: InteractiveTaskData;
+}
+
+/**
+ * Interactive task data part (wire format).
+ * Uses AI SDK's data-{name} convention.
+ */
+export interface InteractiveTaskDataPart {
+  type: "data-interactive-task";
+  data: InteractiveTaskData;
+}

package/src/message-parts/types.ts

@@ -16,6 +16,7 @@
 import type { ToolListMessagePart } from "../mcp/index";
 import type { PreviewPart } from "./preview";
 import type { ConfirmationPart } from "./confirmation";
+import type { InteractiveTaskPart } from "./interactive";
 
 // =============================================================================
 // Narrative Parts (Streamable)
@@ -118,7 +119,8 @@ export type SurfacePart =
   | ChartPart
   | TablePart
   | ConfirmationPart
-  | PreviewPart;
+  | PreviewPart
+  | InteractiveTaskPart;
 
 /**
  * All assistant message part types.

package/src/message-parts/wire.ts

@@ -13,6 +13,10 @@
 import type { MCPToolDescriptor, ToolListDataPart } from "../mcp/index";
 import type { PreviewDataPart, PreviewData } from "./preview";
 import type { ConfirmationData, ConfirmationDataPart } from "./confirmation";
+import type {
+  InteractiveTaskData,
+  InteractiveTaskDataPart,
+} from "./interactive";
 import type {
   ExecutionResultData,
   ExecutionResultDataPart,
@@ -87,6 +91,27 @@ export const WireSurfaceBuilder = {
     };
   },
 
+  /**
+   * Build an interactive task data part for streaming.
+   * Interactive tasks are EDITABLE forms the user fills in inline; unlike a
+   * preview they carry no executionId (no execution exists until the user
+   * submits the filled form).
+   *
+   * INVARIANTS:
+   * - taskId must be stable for governance correlation on submit
+   * - At most one governed surface (preview ∪ interactive) per turn
+   * - No execution is created when this part is emitted
+   *
+   * @param data - Interactive task data (subject, fields, submitEndpoint)
+   * @returns Wire-format interactive task part ready for stream
+   */
+  interactiveTask(data: InteractiveTaskData): InteractiveTaskDataPart {
+    return {
+      type: "data-interactive-task",
+      data,
+    };
+  },
+
   /**
    * Build an execution result data part for streaming.
    * Reports the outcome of an executed action.

package/src/org/index.ts

@@ -157,6 +157,7 @@ export {
   RemoveMemberResponseSchema,
   ChangeMemberRoleResponseSchema,
   SetMemberManagerResponseSchema,
+  SubmitInteractiveTaskResponseSchema,
   UserOrgsResponseSchema,
   SetActiveOrgResponseSchema,
   LeaveOrgResponseSchema,
@@ -180,6 +181,7 @@ export type {
   RemoveMemberResponse,
   ChangeMemberRoleResponse,
   SetMemberManagerResponse,
+  SubmitInteractiveTaskResponse,
   UserOrgsResponse,
   SetActiveOrgResponse,
   LeaveOrgResponse,

package/src/org/schemas.ts

@@ -501,6 +501,31 @@ export type SetMemberManagerResponse = z.infer<
   typeof SetMemberManagerResponseSchema
 >;
 
+// ---------------------------------------------------------------------------
+// POST /api/chat/interactive-tasks/submit
+// ---------------------------------------------------------------------------
+
+/**
+ * Response for submitting a filled-in interactive chat task surface (e.g. the
+ * editable "change reporting manager" form). The submit endpoint runs the
+ * Deterministic Execution & Governance Engine: it creates an execution and,
+ * when no further confirmation is required, drives it to execution in the same
+ * request. The frontend then drives the surface's lifecycle card off
+ * `executionId` (the execution-lifecycle stream), exactly like a confirmation.
+ *
+ * See ADR-CONTRACTS-068.
+ */
+export const SubmitInteractiveTaskResponseSchema = z.object({
+  /** Lifecycle record id created for this submission. */
+  executionId: z.string(),
+  /** Coarse lifecycle status at the time the request returns. */
+  status: z.enum(["executing", "completed", "failed", "pending_confirmation"]),
+});
+
+export type SubmitInteractiveTaskResponse = z.infer<
+  typeof SubmitInteractiveTaskResponseSchema
+>;
+
 // ---------------------------------------------------------------------------
 // GET /api/user/orgs
 // ---------------------------------------------------------------------------

package/src/permissions/orgchart-roles.ts

@@ -44,7 +44,7 @@ export const OrgChartRoleSchema = z.enum(ORG_CHART_ROLES);
  */
 export const ORG_CHART_ROLE_LABELS: Record<OrgChartRole, string> = {
   owner: "CEO",
-  leader: "Leader",
+  leader: "Unit owner",
   delegate: "Delegate",
   admin: "Admin",
 };