@company-semantics/contracts 13.9.0 → 13.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "13.9.0",
+  "version": "13.11.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/api/generated.ts

@@ -2041,6 +2041,58 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/org-units/{unitId}/open-roles": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List open roles of an org unit */
+        get: operations["listOrgUnitOpenRoles"];
+        put?: never;
+        /** Create an open role (placeholder seat) in an org unit */
+        post: operations["createOrgUnitOpenRole"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/org-units/{unitId}/open-roles/{roleId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        /** Advance (hiring) or close an open role */
+        patch: operations["updateOrgUnitOpenRoleStatus"];
+        trace?: never;
+    };
+    "/api/org-units/{unitId}/open-roles/{roleId}/fill": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Fill an open role by seating an existing member or inviting a person */
+        post: operations["fillOrgUnitOpenRole"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/users/org-chart": {
         parameters: {
             query?: never;
@@ -3636,6 +3688,8 @@ export interface components {
                 };
                 /** @enum {string} */
                 status: "pending" | "accepted" | "expired" | "revoked";
+                /** Format: uuid */
+                homeUnitId?: string;
                 createdAt: string;
                 expiresAt: string;
                 acceptedAt?: string;
@@ -3646,6 +3700,8 @@ export interface components {
             email: string;
             /** @enum {string} */
             role: "admin" | "member";
+            /** Format: uuid */
+            homeUnitId?: string;
         };
         InviteListResponse: {
             id: string;
@@ -3659,6 +3715,8 @@ export interface components {
             };
             /** @enum {string} */
             status: "pending" | "accepted" | "expired" | "revoked";
+            /** Format: uuid */
+            homeUnitId?: string;
             createdAt: string;
             expiresAt: string;
             acceptedAt?: string;
@@ -4564,6 +4622,42 @@ export interface components {
                 updatedAt: string;
             };
         };
+        OpenRoleListResponse: {
+            /** Format: uuid */
+            unitId: string;
+            openRoles: {
+                /** Format: uuid */
+                id: string;
+                /** Format: uuid */
+                orgId: string;
+                /** Format: uuid */
+                unitId: string;
+                title: string | null;
+                targetStartDate: string | null;
+                /** @enum {string} */
+                status: "open" | "hiring" | "filled" | "closed";
+                filledByUserId: string | null;
+                createdAt: string;
+                updatedAt: string;
+            }[];
+        };
+        OpenRoleResponse: {
+            openRole: {
+                /** Format: uuid */
+                id: string;
+                /** Format: uuid */
+                orgId: string;
+                /** Format: uuid */
+                unitId: string;
+                title: string | null;
+                targetStartDate: string | null;
+                /** @enum {string} */
+                status: "open" | "hiring" | "filled" | "closed";
+                filledByUserId: string | null;
+                createdAt: string;
+                updatedAt: string;
+            };
+        };
         PeopleOrgChartResponse: {
             nodes: {
                 /** Format: uuid */
@@ -8457,6 +8551,126 @@ export interface operations {
             };
         };
     };
+    listOrgUnitOpenRoles: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Open roles of the unit (all lifecycle states) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OpenRoleListResponse"];
+                };
+            };
+        };
+    };
+    createOrgUnitOpenRole: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    title?: string | null;
+                    targetStartDate?: string | null;
+                };
+            };
+        };
+        responses: {
+            /** @description Created open role */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OpenRoleResponse"];
+                };
+            };
+        };
+    };
+    updateOrgUnitOpenRoleStatus: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+                roleId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @enum {string} */
+                    status: "hiring" | "closed";
+                };
+            };
+        };
+        responses: {
+            /** @description Updated open role */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OpenRoleResponse"];
+                };
+            };
+        };
+    };
+    fillOrgUnitOpenRole: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+                roleId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @constant */
+                    mode: "existing";
+                    /** Format: uuid */
+                    userId: string;
+                } | {
+                    /** @constant */
+                    mode: "invite";
+                    /** Format: email */
+                    email: string;
+                    /** @enum {string} */
+                    role: "admin" | "member";
+                };
+            };
+        };
+        responses: {
+            /** @description Filled open role */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OpenRoleResponse"];
+                };
+            };
+        };
+    };
     getPeopleOrgChart: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -86,6 +86,9 @@ export const openApiRoutes = {
   '/api/org-units/{unitId}/memberships/{userId}': ['DELETE'],
   '/api/org-units/{unitId}/memberships/{userId}/role': ['PUT'],
   '/api/org-units/{unitId}/my-authority': ['GET'],
+  '/api/org-units/{unitId}/open-roles': ['GET', 'POST'],
+  '/api/org-units/{unitId}/open-roles/{roleId}': ['PATCH'],
+  '/api/org-units/{unitId}/open-roles/{roleId}/fill': ['POST'],
   '/api/org-units/{unitId}/owners': ['GET'],
   '/api/org-units/{unitId}/permissions': ['GET'],
   '/api/org-units/{unitId}/relationships': ['GET', 'POST'],

package/src/identity/index.ts

@@ -66,11 +66,13 @@ export {
   ReportingRelationshipTypeSchema,
   PeopleOrgChartNodeSchema,
   PeopleOrgChartEdgeSchema,
+  PeopleOrgChartOpenRoleSchema,
   PeopleOrgChartResponseSchema,
 } from "./people-org-chart";
 export type {
   ReportingRelationshipType,
   PeopleOrgChartNode,
   PeopleOrgChartEdge,
+  PeopleOrgChartOpenRole,
   PeopleOrgChartResponse,
 } from "./people-org-chart";

package/src/identity/people-org-chart.ts

@@ -48,6 +48,24 @@ export const PeopleOrgChartEdgeSchema = z.object({
 
 export type PeopleOrgChartEdge = z.infer<typeof PeopleOrgChartEdgeSchema>;
 
+// ---------------------------------------------------------------------------
+// Open role — a persisted placeholder seat rendered as a dashed "Open role"
+// card in its unit's sibling column. Only active roles (open + hiring) are
+// included; filled/closed roles never appear here. `unitId` seats the card in
+// the right column and resolves its attach-person, mirroring how empty-unit
+// placeholders and pending-invite ghosts are positioned.
+// ---------------------------------------------------------------------------
+
+export const PeopleOrgChartOpenRoleSchema = z.object({
+  id: z.string().uuid(),
+  unitId: z.string().uuid(),
+  title: z.string().nullable(),
+});
+
+export type PeopleOrgChartOpenRole = z.infer<
+  typeof PeopleOrgChartOpenRoleSchema
+>;
+
 // ---------------------------------------------------------------------------
 // GET /api/users/org-chart
 // ---------------------------------------------------------------------------
@@ -55,6 +73,7 @@ export type PeopleOrgChartEdge = z.infer<typeof PeopleOrgChartEdgeSchema>;
 export const PeopleOrgChartResponseSchema = z.object({
   nodes: z.array(PeopleOrgChartNodeSchema),
   edges: z.array(PeopleOrgChartEdgeSchema),
+  openRoles: z.array(PeopleOrgChartOpenRoleSchema),
 });
 
 export type PeopleOrgChartResponse = z.infer<

package/src/index.ts

@@ -172,12 +172,14 @@ export {
   ReportingRelationshipTypeSchema,
   PeopleOrgChartNodeSchema,
   PeopleOrgChartEdgeSchema,
+  PeopleOrgChartOpenRoleSchema,
   PeopleOrgChartResponseSchema,
 } from "./identity/index";
 export type {
   ReportingRelationshipType,
   PeopleOrgChartNode,
   PeopleOrgChartEdge,
+  PeopleOrgChartOpenRole,
   PeopleOrgChartResponse,
 } from "./identity/index";
 

package/src/org/__tests__/org-units.test.ts

@@ -14,6 +14,10 @@ import {
   OrgUnitMembershipSourceSchema,
   OrgUnitPermissionsEntrySchema,
   ListOrgUnitPermissionsResponseSchema,
+  OpenRoleSchema,
+  CreateOpenRoleRequestSchema,
+  UpdateOpenRoleStatusRequestSchema,
+  FillOpenRoleRequestSchema,
 } from "../schemas.js";
 
 const UUID_A = "11111111-1111-4111-8111-111111111111";
@@ -92,12 +96,113 @@ describe("OrgUnitTreeNodeSchema", () => {
       depth: 3,
       hasChildren: true,
       memberCount: 5,
+      openRoleCount: 1,
       missingAtNextLevel: null,
     };
     expect(() => OrgUnitTreeNodeSchema.parse(base)).not.toThrow();
     expect(() => OrgUnitTreeNodeSchema.parse({ ...base, depth: 0 })).toThrow();
     expect(() => OrgUnitTreeNodeSchema.parse({ ...base, depth: 6 })).toThrow();
   });
+
+  it("requires a non-negative openRoleCount", () => {
+    const base = {
+      ...makeUnit(),
+      depth: 3,
+      hasChildren: true,
+      memberCount: 5,
+      openRoleCount: 0,
+      missingAtNextLevel: null,
+    };
+    expect(() => OrgUnitTreeNodeSchema.parse(base)).not.toThrow();
+    expect(() =>
+      OrgUnitTreeNodeSchema.parse({ ...base, openRoleCount: -1 }),
+    ).toThrow();
+  });
+});
+
+describe("OpenRoleSchema", () => {
+  const makeOpenRole = (overrides: Record<string, unknown> = {}) => ({
+    id: UUID_A,
+    orgId: UUID_B,
+    unitId: UUID_C,
+    title: "Senior Engineer",
+    targetStartDate: "2026-09-01",
+    status: "open",
+    filledByUserId: null,
+    createdAt: "2026-04-17T00:00:00Z",
+    updatedAt: "2026-04-17T00:00:00Z",
+    ...overrides,
+  });
+
+  it("accepts a valid open role and the four lifecycle states", () => {
+    expect(() => OpenRoleSchema.parse(makeOpenRole())).not.toThrow();
+    for (const status of ["open", "hiring", "filled", "closed"]) {
+      expect(() =>
+        OpenRoleSchema.parse(makeOpenRole({ status })),
+      ).not.toThrow();
+    }
+  });
+
+  it("allows null title and targetStartDate, rejects unknown status", () => {
+    expect(() =>
+      OpenRoleSchema.parse(
+        makeOpenRole({ title: null, targetStartDate: null }),
+      ),
+    ).not.toThrow();
+    expect(() =>
+      OpenRoleSchema.parse(makeOpenRole({ status: "vacant" })),
+    ).toThrow();
+  });
+});
+
+describe("Open role request schemas", () => {
+  it("CreateOpenRoleRequest accepts empty body and ISO date, rejects bad date", () => {
+    expect(() => CreateOpenRoleRequestSchema.parse({})).not.toThrow();
+    expect(() =>
+      CreateOpenRoleRequestSchema.parse({
+        title: "PM",
+        targetStartDate: "2026-09-01",
+      }),
+    ).not.toThrow();
+    expect(() =>
+      CreateOpenRoleRequestSchema.parse({ targetStartDate: "Sept 1" }),
+    ).toThrow();
+  });
+
+  it("UpdateOpenRoleStatusRequest only accepts hiring|closed", () => {
+    expect(() =>
+      UpdateOpenRoleStatusRequestSchema.parse({ status: "hiring" }),
+    ).not.toThrow();
+    expect(() =>
+      UpdateOpenRoleStatusRequestSchema.parse({ status: "closed" }),
+    ).not.toThrow();
+    expect(() =>
+      UpdateOpenRoleStatusRequestSchema.parse({ status: "filled" }),
+    ).toThrow();
+    expect(() =>
+      UpdateOpenRoleStatusRequestSchema.parse({ status: "open" }),
+    ).toThrow();
+  });
+
+  it("FillOpenRoleRequest discriminates on mode", () => {
+    expect(() =>
+      FillOpenRoleRequestSchema.parse({ mode: "existing", userId: UUID_A }),
+    ).not.toThrow();
+    expect(() =>
+      FillOpenRoleRequestSchema.parse({
+        mode: "invite",
+        email: "a@b.com",
+        role: "member",
+      }),
+    ).not.toThrow();
+    // wrong branch fields
+    expect(() =>
+      FillOpenRoleRequestSchema.parse({ mode: "existing", email: "a@b.com" }),
+    ).toThrow();
+    expect(() =>
+      FillOpenRoleRequestSchema.parse({ mode: "invite", userId: UUID_A }),
+    ).toThrow();
+  });
 });
 
 describe("OrgUnitMembershipSchema", () => {

package/src/org/__tests__/view-scopes.test.ts

@@ -10,6 +10,7 @@ describe("VIEW_SCOPE_MAP golden snapshot", () => {
       "teamwork-member": "org.view_teamwork",
       "company-md": "org.view_company_md",
       "internal-admin": "internal.view_admin",
+      "execution-detail": "org.view_timeline",
       teams: null,
       chat: null,
       settings: null,
@@ -28,6 +29,7 @@ describe("getViewScope", () => {
     expect(getViewScope("teamwork")).toBe("org.view_teamwork");
     expect(getViewScope("company-md")).toBe("org.view_company_md");
     expect(getViewScope("internal-admin")).toBe("internal.view_admin");
+    expect(getViewScope("execution-detail")).toBe("org.view_timeline");
   });
 
   it("returns null for public views", () => {

package/src/org/index.ts

@@ -219,6 +219,7 @@ export type {
   OrgUnitRelationshipRole,
   OrgUnitMembershipStatus,
   OrgUnitMembershipSource,
+  OpenRoleStatus,
   OrgUnitErrorCode,
   OrgTreeResponse,
 } from "./org-units";
@@ -236,6 +237,13 @@ export {
   OrgUnitSchema,
   OrgUnitTreeNodeSchema,
   OrgUnitMembershipSchema,
+  OpenRoleStatusSchema,
+  OpenRoleSchema,
+  OpenRoleResponseSchema,
+  OpenRoleListResponseSchema,
+  CreateOpenRoleRequestSchema,
+  UpdateOpenRoleStatusRequestSchema,
+  FillOpenRoleRequestSchema,
   OrgUnitRelationshipSchema,
   OrgLevelConfigSchema,
   OrgLevelIconSchema,
@@ -259,6 +267,12 @@ export type {
   OrgUnit,
   OrgUnitTreeNode,
   OrgUnitMembership,
+  OpenRole,
+  OpenRoleResponse,
+  OpenRoleListResponse,
+  CreateOpenRoleRequest,
+  UpdateOpenRoleStatusRequest,
+  FillOpenRoleRequest,
   OrgUnitRelationship,
   OrgLevelConfig,
   OrgLevelIcon,

package/src/org/org-units.ts

@@ -56,6 +56,19 @@ export type OrgUnitMembershipSource =
   | "scim"
   | "hris";
 
+/**
+ * Hiring lifecycle of an open role — a persisted placeholder for the person
+ * who will sit in an org unit (PRD open-roles). A unit is seeded with one
+ * `open` role at creation so it never renders as a unit with nobody.
+ *
+ * Transitions: `open → hiring → filled` and `open|hiring → closed`. `filled`
+ * and `closed` are terminal. `filled` means a real `org_unit_membership` was
+ * created from this role (the row is kept as staffing history); `closed` means
+ * the seat was cancelled. Only `open` and `hiring` are "active" — they are the
+ * states that render an Open role card and count toward `openRoleCount`.
+ */
+export type OpenRoleStatus = "open" | "hiring" | "filled" | "closed";
+
 /**
  * Canonical route path constants for the `/api/org-units` surface.
  *
@@ -87,6 +100,11 @@ export const ORG_UNITS_ROUTES = {
   membershipRole: (unitId: string, userId: string) =>
     `/api/org-units/${unitId}/memberships/${userId}/role`,
   permissions: (unitId: string) => `/api/org-units/${unitId}/permissions`,
+  openRoles: (unitId: string) => `/api/org-units/${unitId}/open-roles`,
+  openRoleById: (unitId: string, roleId: string) =>
+    `/api/org-units/${unitId}/open-roles/${roleId}`,
+  fillOpenRole: (unitId: string, roleId: string) =>
+    `/api/org-units/${unitId}/open-roles/${roleId}/fill`,
 } as const;
 
 /**

package/src/org/schemas.ts

@@ -855,6 +855,18 @@ export const OrgUnitMembershipSourceSchema = z.enum([
   "hris",
 ]);
 
+/**
+ * Hiring lifecycle of an open role. See `OpenRoleStatus` in `./org-units` for
+ * the transition rules. Only `open` and `hiring` are "active" (render a card
+ * and count toward `openRoleCount`); `filled`/`closed` are terminal.
+ */
+export const OpenRoleStatusSchema = z.enum([
+  "open",
+  "hiring",
+  "filled",
+  "closed",
+]);
+
 export const OrgUnitErrorCodeSchema = z.enum([
   "CYCLE_BLOCKED",
   "DEPTH_EXCEEDED",
@@ -903,6 +915,12 @@ export const OrgUnitTreeNodeSchema = OrgUnitSchema.extend({
   depth: z.number().int().min(1).max(5),
   hasChildren: z.boolean(),
   memberCount: z.number().int().min(0),
+  /**
+   * Active open roles (`open` + `hiring`) rolled up over this unit's subtree,
+   * the same way `memberCount` rolls up real members. Drives the "(N + M open)"
+   * count split in the people surfaces. `memberCount` stays real-members-only.
+   */
+  openRoleCount: z.number().int().min(0),
   missingAtNextLevel: MissingAtNextLevelSchema.nullable(),
 });
 
@@ -919,6 +937,25 @@ export const OrgUnitMembershipSchema = z.object({
   updatedAt: z.string(),
 });
 
+/**
+ * An open role — a persisted placeholder for the person who will sit in a unit.
+ * Carries unit membership (a seat) but never authority. `title` and
+ * `targetStartDate` are optional planning attributes. On `fill`, `filledByUserId`
+ * points at the seated user and a real `org_unit_membership` is created; the row
+ * is kept as staffing history. `targetStartDate` is an ISO date (YYYY-MM-DD).
+ */
+export const OpenRoleSchema = z.object({
+  id: z.string().uuid(),
+  orgId: z.string().uuid(),
+  unitId: z.string().uuid(),
+  title: z.string().nullable(),
+  targetStartDate: z.string().nullable(),
+  status: OpenRoleStatusSchema,
+  filledByUserId: z.string().uuid().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
 // ---------------------------------------------------------------------------
 // Authority & Delegation vocabulary
 //
@@ -1177,6 +1214,49 @@ export const OrgUnitMembershipListResponseSchema = z.object({
   memberships: z.array(OrgUnitMembershipSchema),
 });
 
+// ---------------------------------------------------------------------------
+// Open roles (PRD open-roles)
+// Request schemas are colocated here (a narrow deviation from ADR-CONT-044, as
+// with UpdateOrgUnitRequest) so the app's add-role form and the backend
+// validate against one published shape.
+// ---------------------------------------------------------------------------
+
+export const OpenRoleResponseSchema = z.object({ openRole: OpenRoleSchema });
+
+export const OpenRoleListResponseSchema = z.object({
+  unitId: z.string().uuid(),
+  openRoles: z.array(OpenRoleSchema),
+});
+
+/** ISO calendar date (YYYY-MM-DD) — version-agnostic vs `z.string().date()`. */
+const IsoDateSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, {
+  message: "must be an ISO date (YYYY-MM-DD)",
+});
+
+export const CreateOpenRoleRequestSchema = z.object({
+  title: z.string().min(1).max(255).nullable().optional(),
+  targetStartDate: IsoDateSchema.nullable().optional(),
+});
+
+/** Only the non-terminal client transitions are accepted; `fill` is its own
+ * endpoint and `open` is the seeded initial state, never set by the client. */
+export const UpdateOpenRoleStatusRequestSchema = z.object({
+  status: z.enum(["hiring", "closed"]),
+});
+
+/**
+ * Fill an open role by seating an existing org member (`userId`) or inviting a
+ * new person by email. Exactly one branch — a discriminated union keyed on `mode`.
+ */
+export const FillOpenRoleRequestSchema = z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("existing"), userId: z.string().uuid() }),
+  z.object({
+    mode: z.literal("invite"),
+    email: z.string().email(),
+    role: z.enum(["admin", "member"]),
+  }),
+]);
+
 /**
  * Effective manager of an org unit — a user whose membership (direct or
  * inherited from an ancestor) grants the `orgUnit.{id}.manage` capability.
@@ -1249,6 +1329,14 @@ export type OrgUnitMembershipResponse = z.infer<
 export type OrgUnitMembershipListResponse = z.infer<
   typeof OrgUnitMembershipListResponseSchema
 >;
+export type OpenRole = z.infer<typeof OpenRoleSchema>;
+export type OpenRoleResponse = z.infer<typeof OpenRoleResponseSchema>;
+export type OpenRoleListResponse = z.infer<typeof OpenRoleListResponseSchema>;
+export type CreateOpenRoleRequest = z.infer<typeof CreateOpenRoleRequestSchema>;
+export type UpdateOpenRoleStatusRequest = z.infer<
+  typeof UpdateOpenRoleStatusRequestSchema
+>;
+export type FillOpenRoleRequest = z.infer<typeof FillOpenRoleRequestSchema>;
 export type OrgUnitPermissionsEntry = z.infer<
   typeof OrgUnitPermissionsEntrySchema
 >;

package/src/org/view-scopes.ts

@@ -23,6 +23,11 @@ export const VIEW_SCOPE_MAP = {
   "teamwork-member": "org.view_teamwork",
   "company-md": "org.view_company_md",
   "internal-admin": "internal.view_admin",
+  // `execution-detail` (/@org/executions/{id}) is gated behind the same scope as
+  // its only entry point, the timeline. Per-execution visibility is additionally
+  // enforced at the data layer (GET /summary + /result return 404 when the
+  // execution is not visible). See ADR-APP-045.
+  "execution-detail": "org.view_timeline",
   // Public views (require only authentication)
   // `teams`: team/directory visibility is membership-derived (ADR-BE-241 tier 1),
   // not a scope. Repointed from the never-enforced `org.view_teams` to null when