@company-semantics/contracts 21.0.0 → 21.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "21.0.0",
+  "version": "21.2.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -82,7 +82,7 @@
     "build": "tsc -b --noEmit",
     "typecheck": "tsc -b --noEmit",
     "typecheck:ci": "tsc -p scripts/ci/tsconfig.json",
-    "lint:md": "markdownlint-cli2 '**/*.md' '#node_modules'",
+    "lint:md": "markdownlint-cli2 '**/*.md' '#node_modules' '#.ralph/worktrees' '#.claude/worktrees'",
     "format": "prettier --write src/",
     "format:check": "prettier --check src/",
     "lint:json": "node -e \"JSON.parse(require('fs').readFileSync('package.json'))\"",

package/src/integrations/schemas.ts

@@ -30,6 +30,14 @@ export const HrConnectionStatusSchema = z
     connected: z.boolean().meta({
       description: "Whether an HR provider is currently connected.",
     }),
+    connectionId: z
+      .string()
+      .nullable()
+      .meta({
+        description:
+          "Stable id of the active connection — the handle the app passes to " +
+          "`integration.disconnect`. Null when not connected.",
+      }),
     employeeCount: z.number().int().nonnegative().nullable().meta({
       description:
         "Employees mirrored from the HR provider; null when never synced.",

package/src/org/README.md

@@ -75,6 +75,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `CreateDelegationRequest` _(type)_
 - `CreateDelegationRequestSchema`
 - `CreateInviteRequest` _(type)_ — Request payload for creating an organization invite.
+- `CreateInviteRequestPayload` _(type)_
+- `CreateInviteRequestSchema`
 - `CreateOpenRoleRequest` _(type)_
 - `CreateOpenRoleRequestSchema`
 - `Delegation` _(type)_
@@ -258,6 +260,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `SsoReadinessCheck` _(type)_ — Individual readiness check for SSO activation.
 - `SsoSetupInfo` _(type)_ — SSO setup information for admin configuration UI.
 - `SsoStepperStep` _(type)_ — Backend-authoritative stepper step.
+- `StagedPlacement` _(type)_ — Staged member placement: the fuller org position an invitee is slotted into, applied as deferred grants when…
+- `StagedPlacementSchema` — Staged member placement: the fuller org position an invitee is slotted into, applied as deferred grants when…
 - `SubmitInteractiveTaskResponse` _(type)_
 - `SubmitInteractiveTaskResponseSchema` — Response for submitting a filled-in interactive chat task surface (e.g. the editable "change reporting…
 - `SyncRunSummary` _(type)_

package/src/org/__tests__/invite-schemas.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from "vitest";
+import {
+  StagedPlacementSchema,
+  CreateInviteRequestSchema,
+  InviteResponseSchema,
+} from "../schemas.js";
+
+const UUID_A = "11111111-1111-4111-8111-111111111111";
+const UUID_B = "22222222-2222-4222-8222-222222222222";
+const UUID_C = "33333333-3333-4333-8333-333333333333";
+
+const makeInvite = (overrides: Record<string, unknown> = {}) => ({
+  id: UUID_A,
+  orgId: UUID_B,
+  email: "new.hire@example.com",
+  role: "member",
+  invitedBy: { id: UUID_C, name: "Inviter" },
+  status: "pending",
+  createdAt: "2026-06-24T00:00:00Z",
+  expiresAt: "2026-07-01T00:00:00Z",
+  ...overrides,
+});
+
+describe("CreateInviteRequestSchema", () => {
+  it("parses a minimal payload without stagedPlacement", () => {
+    const parsed = CreateInviteRequestSchema.parse({
+      email: "new.hire@example.com",
+      role: "admin",
+    });
+    expect(parsed.stagedPlacement).toBeUndefined();
+    expect(parsed.homeUnitId).toBeUndefined();
+  });
+
+  it("parses a full stagedPlacement with arrays defaulting to []", () => {
+    const parsed = CreateInviteRequestSchema.parse({
+      email: "new.hire@example.com",
+      role: "member",
+      homeUnitId: UUID_A,
+      homeUnitRole: "unit_owner",
+      stagedPlacement: {
+        title: "Staff Engineer",
+        managerUserId: UUID_B,
+        homeUnitId: UUID_A,
+        homeUnitRole: "unit_owner",
+      },
+    });
+    expect(parsed.stagedPlacement?.title).toBe("Staff Engineer");
+    // unitOwnerOf/contributesTo default to [] when omitted.
+    expect(parsed.stagedPlacement?.unitOwnerOf).toEqual([]);
+    expect(parsed.stagedPlacement?.contributesTo).toEqual([]);
+  });
+});
+
+describe("StagedPlacementSchema", () => {
+  it("defaults unitOwnerOf and contributesTo to []", () => {
+    const parsed = StagedPlacementSchema.parse({});
+    expect(parsed.unitOwnerOf).toEqual([]);
+    expect(parsed.contributesTo).toEqual([]);
+  });
+
+  it("retains provided unit arrays", () => {
+    const parsed = StagedPlacementSchema.parse({
+      unitOwnerOf: [UUID_A],
+      contributesTo: [UUID_B, UUID_C],
+    });
+    expect(parsed.unitOwnerOf).toEqual([UUID_A]);
+    expect(parsed.contributesTo).toEqual([UUID_B, UUID_C]);
+  });
+
+  it("trims the title", () => {
+    const parsed = StagedPlacementSchema.parse({ title: "  Lead  " });
+    expect(parsed.title).toBe("Lead");
+  });
+
+  it("rejects a non-uuid managerUserId", () => {
+    expect(() =>
+      StagedPlacementSchema.parse({ managerUserId: "not-a-uuid" }),
+    ).toThrow();
+  });
+});
+
+describe("OrgInviteSchema (via InviteResponseSchema)", () => {
+  it("parses an invite without stagedPlacement (back-compat)", () => {
+    const parsed = InviteResponseSchema.parse({ invite: makeInvite() });
+    expect(parsed.invite.stagedPlacement).toBeUndefined();
+  });
+
+  it("parses an invite carrying a stagedPlacement", () => {
+    const parsed = InviteResponseSchema.parse({
+      invite: makeInvite({
+        homeUnitId: UUID_A,
+        homeUnitRole: "member",
+        stagedPlacement: {
+          title: "Engineer",
+          unitOwnerOf: [UUID_A],
+        },
+      }),
+    });
+    expect(parsed.invite.stagedPlacement?.title).toBe("Engineer");
+    expect(parsed.invite.stagedPlacement?.unitOwnerOf).toEqual([UUID_A]);
+    // Omitted contributesTo still defaults to [].
+    expect(parsed.invite.stagedPlacement?.contributesTo).toEqual([]);
+  });
+});

package/src/org/index.ts

@@ -249,6 +249,8 @@ export type {
 
 // Org lifecycle response schemas (PRD-00446)
 export {
+  StagedPlacementSchema,
+  CreateInviteRequestSchema,
   InviteResponseSchema,
   InviteListResponseSchema,
   DomainResponseSchema,
@@ -259,6 +261,8 @@ export {
   OwnershipTransferPreviewSchema,
 } from "./schemas";
 export type {
+  StagedPlacement,
+  CreateInviteRequestPayload,
   InviteResponse,
   InviteListResponse,
   DomainResponse,

package/src/org/schemas.ts

@@ -606,6 +606,46 @@ export type ScopeCheckBatchResponse = z.infer<
 export const HomeUnitRoleSchema = z.enum(["member", "unit_owner"]);
 export type HomeUnitRole = z.infer<typeof HomeUnitRoleSchema>;
 
+/** Established title cap shared with org-unit/open-role titles. */
+const STAGED_PLACEMENT_TITLE_MAX = 255;
+/**
+ * Upper bound on the number of units an invitee can be staged into as owner or
+ * contributor. Bounds the replay cost of applying a staged placement at accept
+ * time (each entry is a deferred membership grant). A generous-but-finite cap.
+ */
+const STAGED_PLACEMENT_UNITS_MAX = 64;
+
+/**
+ * Staged member placement: the fuller org position an invitee is slotted into,
+ * applied as deferred grants when the invite is accepted. A superset of the
+ * legacy top-level `homeUnitId`/`homeUnitRole` fields, carrying the (optional)
+ * intended title, manager, and the units the invitee will own or contribute to.
+ *
+ * Every field is optional or defaulted so a placement can be partially
+ * specified at invite time. The array caps bound downstream replay cost.
+ */
+export const StagedPlacementSchema = z.object({
+  // Intended job/role title for the invitee. Trimmed; non-empty when present.
+  title: z.string().trim().min(1).max(STAGED_PLACEMENT_TITLE_MAX).optional(),
+  // The invitee's manager on acceptance (a `manages` designation).
+  managerUserId: z.string().uuid().optional(),
+  // Home unit the invitee is placed in (their `users.primary_unit_id`).
+  homeUnitId: z.string().uuid().optional(),
+  // Role the invitee takes in `homeUnitId` ('unit_owner' = deferred grant).
+  homeUnitRole: HomeUnitRoleSchema.optional(),
+  // Additional units the invitee becomes a unit owner of on acceptance.
+  unitOwnerOf: z
+    .array(z.string().uuid())
+    .max(STAGED_PLACEMENT_UNITS_MAX)
+    .default([]),
+  // Units the invitee contributes to (non-owner membership) on acceptance.
+  contributesTo: z
+    .array(z.string().uuid())
+    .max(STAGED_PLACEMENT_UNITS_MAX)
+    .default([]),
+});
+export type StagedPlacement = z.infer<typeof StagedPlacementSchema>;
+
 const OrgInviteSchema = z.object({
   id: z.string(),
   orgId: z.string(),
@@ -620,6 +660,10 @@ const OrgInviteSchema = z.object({
   // deferred unit-ownership grant). Optional/'member' for legacy +
   // unit-less invites.
   homeUnitRole: HomeUnitRoleSchema.optional(),
+  // Fuller staged placement applied as deferred grants on acceptance. A
+  // superset of the top-level homeUnitId/homeUnitRole, kept additive/optional
+  // so legacy invites and unit-less invites parse unchanged.
+  stagedPlacement: StagedPlacementSchema.optional(),
   createdAt: z.string(),
   expiresAt: z.string(),
   acceptedAt: z.string().optional(),
@@ -643,6 +687,33 @@ export const InviteListResponseSchema = z.array(OrgInviteSchema);
 
 export type InviteListResponse = z.infer<typeof InviteListResponseSchema>;
 
+// ---------------------------------------------------------------------------
+// POST /api/workspace/invites — request body
+// Request schema colocated with the response schema (narrow deviation from
+// ADR-CONT-044, per the CreateOpenRoleRequestSchema precedent) because the
+// staged-placement shape is the published promise consumers must satisfy.
+// Mirrors the hand-written `CreateInviteRequest` interface in org/types.ts and
+// extends it with the optional `stagedPlacement` superset.
+// ---------------------------------------------------------------------------
+
+export const CreateInviteRequestSchema = z.object({
+  email: z.string().email(),
+  // Invites only grant the restricted {admin, member} domain.
+  role: z.enum(["admin", "member"]),
+  // Home unit the invitee is placed in on acceptance. Optional in the contract
+  // so the field can roll out without breaking older callers.
+  homeUnitId: z.string().uuid().optional(),
+  // Role the invitee takes in homeUnitId — only meaningful with a home unit.
+  homeUnitRole: HomeUnitRoleSchema.optional(),
+  // Fuller staged placement (title, manager, owned/contributed units) applied
+  // as deferred grants on acceptance. Optional/additive for back-compat.
+  stagedPlacement: StagedPlacementSchema.optional(),
+});
+
+export type CreateInviteRequestPayload = z.infer<
+  typeof CreateInviteRequestSchema
+>;
+
 // ---------------------------------------------------------------------------
 // OrgDomain sub-schema
 // ---------------------------------------------------------------------------

package/src/org/types.ts

@@ -397,6 +397,37 @@ export interface WorkspaceAuditEvent {
  */
 export type OrgInviteStatus = "pending" | "accepted" | "expired" | "revoked";
 
+/**
+ * Staged member placement: the fuller org position an invitee is slotted into,
+ * applied as deferred grants when the invite is accepted. A superset of the
+ * top-level `homeUnitId`/`homeUnitRole` fields, carrying the (optional) intended
+ * title, manager, and the units the invitee will own or contribute to.
+ *
+ * Hand-written mirror of `StagedPlacementSchema` in `org/schemas.ts` — keep in
+ * lockstep. Because the schema defaults `unitOwnerOf`/`contributesTo` to `[]`,
+ * their inferred OUTPUT type is a required `string[]`; the other four fields are
+ * optional. The `homeUnitRole` union is re-typed inline (not imported) to match
+ * the `OrgInvite`/`CreateInviteRequest` convention.
+ *
+ * NOTE: the canonical `StagedPlacement` name is exported package-root from
+ * `org/schemas.ts` (the `z.infer`). This interface is intentionally NOT added to
+ * the `./types` re-export block in `org/index.ts` to avoid a name collision.
+ */
+export interface StagedPlacement {
+  /** Intended job/role title for the invitee. Trimmed; non-empty when present. */
+  title?: string;
+  /** The invitee's manager on acceptance (a `manages` designation) — a member id. */
+  managerUserId?: string;
+  /** Home unit the invitee is placed in (their `users.primary_unit_id`). */
+  homeUnitId?: string;
+  /** Role the invitee takes in `homeUnitId` (`unit_owner` = deferred grant). */
+  homeUnitRole?: "member" | "unit_owner";
+  /** Additional units the invitee becomes a unit owner of on acceptance. */
+  unitOwnerOf: string[];
+  /** Units the invitee contributes to (non-owner membership) on acceptance. */
+  contributesTo: string[];
+}
+
 /**
  * Organization invite for the workspace invites list.
  * Represents a pending or historical invitation.
@@ -425,6 +456,13 @@ export interface OrgInvite {
    * legacy invites and unit-less invites have none (treated as `member`).
    */
   homeUnitRole?: "member" | "unit_owner";
+  /**
+   * Fuller staged placement applied as deferred grants on acceptance. A superset
+   * of the top-level `homeUnitId`/`homeUnitRole`, kept additive/optional so
+   * legacy and unit-less invites parse unchanged. Mirrors
+   * `OrgInviteSchema.stagedPlacement` in `org/schemas.ts`.
+   */
+  stagedPlacement?: StagedPlacement;
   createdAt: string;
   expiresAt: string;
   acceptedAt?: string;
@@ -450,6 +488,12 @@ export interface CreateInviteRequest {
    * rejects `unit_owner` without a home unit. Optional/`member` for older callers.
    */
   homeUnitRole?: "member" | "unit_owner";
+  /**
+   * Fuller staged placement (title, manager, owned/contributed units) applied as
+   * deferred grants on acceptance. Optional/additive for back-compat. Mirrors
+   * `CreateInviteRequestSchema.stagedPlacement` in `org/schemas.ts`.
+   */
+  stagedPlacement?: StagedPlacement;
 }
 
 /**