@company-semantics/contracts 15.0.0 → 16.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "15.0.0",
+  "version": "16.0.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -109,7 +109,9 @@
     "generate:api-types": "openapi-typescript openapi/backend.yaml -o src/api/generated.ts",
     "generate:openapi-routes": "tsx scripts/generate-openapi-routes.ts",
     "generate:api-types:check": "openapi-typescript openapi/backend.yaml -o /tmp/cs-api-types-check.ts && diff -q src/api/generated.ts /tmp/cs-api-types-check.ts",
-    "generate:current": "tsx ../company-semantics-ci/scripts/generate-current.ts"
+    "generate:current": "tsx ../company-semantics-ci/scripts/generate-current.ts",
+    "repo-map": "tsx ../company-semantics-ci/scripts/generate-repo-map.ts --roots src --name company-semantics-contracts --write",
+    "repo-map:check": "tsx ../company-semantics-ci/scripts/generate-repo-map.ts --roots src --name company-semantics-contracts --check"
   },
   "packageManager": "pnpm@10.25.0",
   "engines": {

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 = 'bd74b6f7478d' as const;
+export const SPEC_HASH_FULL = 'bd74b6f7478dcfb445d1e848ab3b65309f9b602b40c3fe2f0ce29b484e94943f' 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;
@@ -3398,7 +3415,7 @@ export interface components {
                 email: string;
                 avatarUrl?: string | null;
                 jobTitle: string | null;
-                role: ("owner" | "leader" | "delegate" | "admin") | null;
+                role: ("owner" | "unit_owner" | "delegate" | "admin") | null;
                 roleNames: string[];
                 joinedAt: string;
                 lastActiveAt: string | null;
@@ -3410,11 +3427,11 @@ export interface components {
                     /** @enum {string} */
                     role: "owner" | "manager" | "member";
                 }[];
-                manages: {
+                unitDesignations: {
                     unitId: string;
                     unitName: string;
                     /** @enum {string} */
-                    designation: "whole_org" | "admin" | "leader" | "delegate" | "member";
+                    designation: "whole_org" | "admin" | "unit_owner" | "delegate" | "member";
                 }[];
                 unitMembershipsTruncated: boolean;
                 inviteStatus: ("active" | "pending" | "expired") | null;
@@ -3593,7 +3610,7 @@ export interface components {
             email: string;
             avatarUrl?: string | null;
             jobTitle: string | null;
-            role: ("owner" | "leader" | "delegate" | "admin") | null;
+            role: ("owner" | "unit_owner" | "delegate" | "admin") | null;
             roleNames: string[];
             joinedAt: string;
             lastActiveAt: string | null;
@@ -3605,11 +3622,11 @@ export interface components {
                 /** @enum {string} */
                 role: "owner" | "manager" | "member";
             }[];
-            manages: {
+            unitDesignations: {
                 unitId: string;
                 unitName: string;
                 /** @enum {string} */
-                designation: "whole_org" | "admin" | "leader" | "delegate" | "member";
+                designation: "whole_org" | "admin" | "unit_owner" | "delegate" | "member";
             }[];
             unitMembershipsTruncated: boolean;
             inviteStatus: ("active" | "pending" | "expired") | null;
@@ -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;
@@ -3666,7 +3698,7 @@ export interface components {
                 orgId: string;
                 orgName: string;
                 orgSlug: string;
-                role: ("owner" | "leader" | "delegate" | "admin") | null;
+                role: ("owner" | "unit_owner" | "delegate" | "admin") | null;
                 joinedAt: string;
                 isActive: boolean;
                 /** @enum {string} */
@@ -3711,7 +3743,7 @@ export interface components {
                 /** Format: uuid */
                 homeUnitId?: string;
                 /** @enum {string} */
-                homeUnitRole?: "member" | "leader";
+                homeUnitRole?: "member" | "unit_owner";
                 createdAt: string;
                 expiresAt: string;
                 acceptedAt?: string;
@@ -3725,7 +3757,7 @@ export interface components {
             /** Format: uuid */
             homeUnitId?: string;
             /** @enum {string} */
-            homeUnitRole?: "member" | "leader";
+            homeUnitRole?: "member" | "unit_owner";
         };
         InviteListResponse: {
             id: string;
@@ -3742,7 +3774,7 @@ export interface components {
             /** Format: uuid */
             homeUnitId?: string;
             /** @enum {string} */
-            homeUnitRole?: "member" | "leader";
+            homeUnitRole?: "member" | "unit_owner";
             createdAt: string;
             expiresAt: string;
             acceptedAt?: 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";
@@ -4616,7 +4648,7 @@ export interface components {
         OrgUnitMyAuthorityResponse: {
             /** Format: uuid */
             unitId: string;
-            role: ("owner" | "leader" | "delegate" | "admin") | null;
+            role: ("owner" | "unit_owner" | "delegate" | "admin") | null;
             canManageMembers: boolean;
             canAssignDelegate: boolean;
             canAssignAdmin: boolean;
@@ -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/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

@@ -141,8 +141,9 @@ export {
   WorkspaceOverviewSchema,
   WorkspaceMembersResponseSchema,
   WorkspaceMemberDetailSchema,
-  WorkspaceMemberManagesEntrySchema,
+  WorkspaceMemberUnitDesignationEntrySchema,
   OrgUnitDesignationSchema,
+  HomeUnitRoleSchema,
   RoleCatalogEntrySchema,
   RoleCatalogResponseSchema,
   WorkspaceAuthConfigSchema,
@@ -157,6 +158,7 @@ export {
   RemoveMemberResponseSchema,
   ChangeMemberRoleResponseSchema,
   SetMemberManagerResponseSchema,
+  SubmitInteractiveTaskResponseSchema,
   UserOrgsResponseSchema,
   SetActiveOrgResponseSchema,
   LeaveOrgResponseSchema,
@@ -167,8 +169,9 @@ export type {
   WorkspaceAccessResponse,
   WorkspaceOverview as WorkspaceOverviewDto,
   WorkspaceMembersResponse,
-  WorkspaceMemberManagesEntry,
+  WorkspaceMemberUnitDesignationEntry,
   OrgUnitDesignation,
+  HomeUnitRole,
   WorkspaceAuthConfig as WorkspaceAuthConfigDto,
   WorkspaceAuditEvent as WorkspaceAuditEventDto,
   WorkspaceResolvePathResponse,
@@ -180,6 +183,7 @@ export type {
   RemoveMemberResponse,
   ChangeMemberRoleResponse,
   SetMemberManagerResponse,
+  SubmitInteractiveTaskResponse,
   UserOrgsResponse,
   SetActiveOrgResponse,
   LeaveOrgResponse,

package/src/org/schemas.ts

@@ -28,7 +28,7 @@ const WorkspaceMemberUnitSummarySchema = z.object({
 /**
  * Designation a member holds over a unit they manage (ADR-CTRL-112).
  *
- * Precedence, highest-first: whole_org > admin > leader > delegate > member.
+ * Precedence, highest-first: whole_org > admin > unit_owner > delegate > member.
  * The org-wide designations (`whole_org`, `admin`) anchor to the org root
  * unit. This vocabulary is DISPLAY-ONLY — it summarizes management reach for
  * UI surfaces and is NEVER an authorization input (authority resolution uses
@@ -37,19 +37,19 @@ const WorkspaceMemberUnitSummarySchema = z.object({
 export const OrgUnitDesignationSchema = z.enum([
   "whole_org",
   "admin",
-  "leader",
+  "unit_owner",
   "delegate",
   "member",
 ]);
 export type OrgUnitDesignation = z.infer<typeof OrgUnitDesignationSchema>;
 
-export const WorkspaceMemberManagesEntrySchema = z.object({
+export const WorkspaceMemberUnitDesignationEntrySchema = z.object({
   unitId: z.string(),
   unitName: z.string(),
   designation: OrgUnitDesignationSchema,
 });
-export type WorkspaceMemberManagesEntry = z.infer<
-  typeof WorkspaceMemberManagesEntrySchema
+export type WorkspaceMemberUnitDesignationEntry = z.infer<
+  typeof WorkspaceMemberUnitDesignationEntrySchema
 >;
 
 const WorkspaceMemberSchema = z.object({
@@ -87,11 +87,13 @@ const WorkspaceMemberSchema = z.object({
   /** OrgUnit memberships for this member, capped at a small number server-side. */
   unitMemberships: z.array(WorkspaceMemberUnitSummarySchema),
   /**
-   * Per-unit org-chart designations the member holds where they manage
-   * (ADR-CTRL-112). Display-only summary of management reach; never an
-   * authorization input. Empty array when the member manages nothing.
+   * Per-unit org-chart designations the member holds (ADR-CTRL-112). Carries
+   * BOTH management-reach entries (whole_org/admin/unit_owner/delegate) and
+   * plain contributor entries (`member`); consumers split by designation.
+   * Display-only summary; never an authorization input. Empty array when the
+   * member holds no per-unit designation.
    */
-  manages: z.array(WorkspaceMemberManagesEntrySchema),
+  unitDesignations: z.array(WorkspaceMemberUnitDesignationEntrySchema),
   /** True when server truncated `unitMemberships`; detail endpoint returns the full list. */
   unitMembershipsTruncated: z.boolean(),
   /** Invite lifecycle status. `null` for members without an invite record. */
@@ -501,6 +503,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
 // ---------------------------------------------------------------------------
@@ -570,6 +597,15 @@ export type ScopeCheckBatchResponse = z.infer<
 // Invite sub-schema
 // ---------------------------------------------------------------------------
 
+/**
+ * Role the invitee takes in their home unit on acceptance. `unit_owner` is a
+ * deferred structural-leadership grant applied at accept time. Source of truth
+ * for the hand-mirrored `OrgInvite`/`CreateInviteRequest` interface unions in
+ * `org/types.ts` (enforced by the `schema-type-mirror` guard).
+ */
+export const HomeUnitRoleSchema = z.enum(["member", "unit_owner"]);
+export type HomeUnitRole = z.infer<typeof HomeUnitRoleSchema>;
+
 const OrgInviteSchema = z.object({
   id: z.string(),
   orgId: z.string(),
@@ -580,9 +616,10 @@ const OrgInviteSchema = z.object({
   // Home unit the invitee is placed in on acceptance (users.primary_unit_id).
   // Optional/nullable: legacy invites predate this field.
   homeUnitId: z.string().uuid().optional(),
-  // Role the invitee takes in homeUnitId on acceptance ('leader' is a deferred
-  // structural-leadership grant). Optional/'member' for legacy + unit-less invites.
-  homeUnitRole: z.enum(["member", "leader"]).optional(),
+  // Role the invitee takes in homeUnitId on acceptance ('unit_owner' is a
+  // deferred structural-leadership grant). Optional/'member' for legacy +
+  // unit-less invites.
+  homeUnitRole: HomeUnitRoleSchema.optional(),
   createdAt: z.string(),
   expiresAt: z.string(),
   acceptedAt: z.string().optional(),

package/src/org/types.ts

@@ -420,11 +420,11 @@ export interface OrgInvite {
   homeUnitId?: string;
   /**
    * Role the invitee takes in `homeUnitId` on acceptance — a plain team member,
-   * or a structural leader of that unit (a *deferred* leadership grant applied
+   * or a unit owner of that unit (a *deferred* leadership grant applied
    * at acceptance time). Distinct from the org-level {@link role}. Optional:
    * legacy invites and unit-less invites have none (treated as `member`).
    */
-  homeUnitRole?: "member" | "leader";
+  homeUnitRole?: "member" | "unit_owner";
   createdAt: string;
   expiresAt: string;
   acceptedAt?: string;
@@ -444,12 +444,12 @@ export interface CreateInviteRequest {
   homeUnitId?: string;
   /**
    * Role the invitee takes in `homeUnitId` on acceptance: a plain team member
-   * (default), or a structural leader of that unit. `leader` is a *deferred*
+   * (default), or a unit owner of that unit. `unit_owner` is a *deferred*
    * grant — the invite is sent now and the leadership is assigned when the
    * invitee accepts. Only meaningful when `homeUnitId` is set; the backend
-   * rejects `leader` without a home unit. Optional/`member` for older callers.
+   * rejects `unit_owner` without a home unit. Optional/`member` for older callers.
    */
-  homeUnitRole?: "member" | "leader";
+  homeUnitRole?: "member" | "unit_owner";
 }
 
 /**

package/src/permissions/orgchart-roles.ts

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