@company-semantics/contracts 13.20.0 → 15.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "13.20.0",
+  "version": "15.0.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 = '255ee9f997af' as const;
-export const SPEC_HASH_FULL = '255ee9f997afb36f3e96cdcffb8aa30a97e5c14f8c21b884974c75f9d126d596' as const;
+export const SPEC_HASH = '16c3b86cc35a' as const;
+export const SPEC_HASH_FULL = '16c3b86cc35a3f329766b702414438de4950430991a603372f1335206c96b600' as const;

package/src/api/generated.ts

@@ -1972,24 +1972,6 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/org-units/{unitId}/head": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        /** Pin an explicit head (anchor person) for an org unit */
-        put: operations["setOrgUnitHead"];
-        post?: never;
-        /** Revert an org unit head to the system-inferred default */
-        delete: operations["revertOrgUnitHead"];
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     "/api/org-units/{unitId}/my-authority": {
         parameters: {
             query?: never;
@@ -2111,6 +2093,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/org-units/{unitId}/open-roles/{roleId}/reports-to": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /** Set or clear an open role's own reporting edge */
+        put: operations["setOrgUnitOpenRoleReportsTo"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/users/org-chart": {
         parameters: {
             query?: never;
@@ -4322,8 +4321,6 @@ export interface components {
                     count: number;
                     userIds: string[];
                 } | null;
-                headUserId: string | null;
-                headOrigin: ("user" | "inferred") | null;
             }[];
         };
         OrgUnitDescendantsResponse: {
@@ -4472,8 +4469,6 @@ export interface components {
                     count: number;
                     userIds: string[];
                 } | null;
-                headUserId: string | null;
-                headOrigin: ("user" | "inferred") | null;
             }[];
             levelConfig: {
                 /** Format: uuid */
@@ -4618,12 +4613,6 @@ export interface components {
             revokedAt: string | null;
             reason: string | null;
         };
-        UnitHeadResponse: {
-            /** Format: uuid */
-            unitId: string;
-            headUserId: string | null;
-            origin: ("user" | "inferred") | null;
-        };
         OrgUnitMyAuthorityResponse: {
             /** Format: uuid */
             unitId: string;
@@ -4693,6 +4682,7 @@ export interface components {
                 /** @enum {string} */
                 status: "open" | "hiring" | "filled" | "closed";
                 filledByUserId: string | null;
+                reportsToUserId: string | null;
                 createdAt: string;
                 updatedAt: string;
             }[];
@@ -4710,6 +4700,7 @@ export interface components {
                 /** @enum {string} */
                 status: "open" | "hiring" | "filled" | "closed";
                 filledByUserId: string | null;
+                reportsToUserId: string | null;
                 createdAt: string;
                 updatedAt: string;
             };
@@ -4737,14 +4728,7 @@ export interface components {
                 /** Format: uuid */
                 unitId: string;
                 title: string | null;
-            }[];
-            unitHeads: {
-                /** Format: uuid */
-                unitId: string;
-                /** Format: uuid */
-                headUserId: string;
-                /** @enum {string} */
-                origin: "user" | "inferred";
+                reportsToUserId: string | null;
             }[];
         };
         /** @description Polling snapshot of a generic ingestion operation. */
@@ -8497,57 +8481,6 @@ export interface operations {
             };
         };
     };
-    setOrgUnitHead: {
-        parameters: {
-            query?: never;
-            header?: never;
-            path: {
-                unitId: string;
-            };
-            cookie?: never;
-        };
-        requestBody: {
-            content: {
-                "application/json": {
-                    /** Format: uuid */
-                    userId: string;
-                };
-            };
-        };
-        responses: {
-            /** @description The pinned unit head */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["UnitHeadResponse"];
-                };
-            };
-        };
-    };
-    revertOrgUnitHead: {
-        parameters: {
-            query?: never;
-            header?: never;
-            path: {
-                unitId: string;
-            };
-            cookie?: never;
-        };
-        requestBody?: never;
-        responses: {
-            /** @description The re-inferred unit head (or null when none resolves) */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["UnitHeadResponse"];
-                };
-            };
-        };
-    };
     getMyOrgUnitAuthority: {
         parameters: {
             query?: never;
@@ -8794,6 +8727,35 @@ export interface operations {
             };
         };
     };
+    setOrgUnitOpenRoleReportsTo: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+                roleId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    userId: string | null;
+                };
+            };
+        };
+        responses: {
+            /** @description Open role with updated reporting edge */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OpenRoleResponse"];
+                };
+            };
+        };
+    };
     getPeopleOrgChart: {
         parameters: {
             query?: 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/generated/openapi-routes.ts

@@ -82,7 +82,6 @@ export const openApiRoutes = {
   '/api/org-units/{unitId}/delegations': ['POST'],
   '/api/org-units/{unitId}/delegations/{id}': ['DELETE', 'PATCH'],
   '/api/org-units/{unitId}/descendants': ['GET'],
-  '/api/org-units/{unitId}/head': ['DELETE', 'PUT'],
   '/api/org-units/{unitId}/memberships': ['GET', 'POST'],
   '/api/org-units/{unitId}/memberships/{userId}': ['DELETE'],
   '/api/org-units/{unitId}/memberships/{userId}/role': ['PUT'],
@@ -90,6 +89,7 @@ export const openApiRoutes = {
   '/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}/open-roles/{roleId}/reports-to': ['PUT'],
   '/api/org-units/{unitId}/owners': ['GET'],
   '/api/org-units/{unitId}/permissions': ['GET'],
   '/api/org-units/{unitId}/relationships': ['GET', 'POST'],

package/src/identity/index.ts

@@ -67,8 +67,6 @@ export {
   PeopleOrgChartNodeSchema,
   PeopleOrgChartEdgeSchema,
   PeopleOrgChartOpenRoleSchema,
-  UnitHeadOriginSchema,
-  PeopleOrgChartUnitHeadSchema,
   PeopleOrgChartResponseSchema,
 } from "./people-org-chart";
 export type {
@@ -76,7 +74,5 @@ export type {
   PeopleOrgChartNode,
   PeopleOrgChartEdge,
   PeopleOrgChartOpenRole,
-  UnitHeadOrigin,
-  PeopleOrgChartUnitHead,
   PeopleOrgChartResponse,
 } from "./people-org-chart";

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

@@ -52,52 +52,37 @@ 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.
+// the right column. `reportsToUserId` is the open role's OWN reporting edge
+// (ADR-BE-291): it defaults to the role's creator and is editable/clearable, so
+// a person-less seat is placed by reporting like everyone else (the chart owns
+// placement, ADR-CTRL-159). Null → the role hangs in its unit's projection-only
+// Unassigned bucket. This replaces the retired unit-head anchor (ADR-BE-284).
 // ---------------------------------------------------------------------------
 
 export const PeopleOrgChartOpenRoleSchema = z.object({
   id: z.string().uuid(),
   unitId: z.string().uuid(),
   title: z.string().nullable(),
+  reportsToUserId: z.string().uuid().nullable(),
 });
 
 export type PeopleOrgChartOpenRole = z.infer<
   typeof PeopleOrgChartOpenRoleSchema
 >;
 
-// ---------------------------------------------------------------------------
-// Unit head — the person a unit (and its person-less children: empty-unit
-// placeholders, pending-invite ghosts, open-role seats) anchors under in the
-// people chart. A presentation/anchor "tether" (ADR-BE-284), NOT authority.
-// `origin` distinguishes an explicit user choice from a system-inferred default
-// so the UI can render "Pinned" vs "Auto" and offer revert-to-auto. The client
-// prefers the head of a unit's PARENT when anchoring its person-less children,
-// falling back to the render-time heuristic only when no head row exists.
-// ---------------------------------------------------------------------------
-
-export const UnitHeadOriginSchema = z.enum(["user", "inferred"]);
-export type UnitHeadOrigin = z.infer<typeof UnitHeadOriginSchema>;
-
-export const PeopleOrgChartUnitHeadSchema = z.object({
-  unitId: z.string().uuid(),
-  headUserId: z.string().uuid(),
-  origin: UnitHeadOriginSchema,
-});
-
-export type PeopleOrgChartUnitHead = z.infer<
-  typeof PeopleOrgChartUnitHeadSchema
->;
-
 // ---------------------------------------------------------------------------
 // GET /api/users/org-chart
 // ---------------------------------------------------------------------------
+//
+// Person-less cards (empty-unit placeholders, ghosts, open roles) no longer
+// anchor under a stored unit-head "tether" (ADR-BE-284, retired by ADR-BE-292).
+// Open roles carry their own `reportsToUserId` edge; placeholders fall back to
+// the render-time reporting heuristic.
 
 export const PeopleOrgChartResponseSchema = z.object({
   nodes: z.array(PeopleOrgChartNodeSchema),
   edges: z.array(PeopleOrgChartEdgeSchema),
   openRoles: z.array(PeopleOrgChartOpenRoleSchema),
-  unitHeads: z.array(PeopleOrgChartUnitHeadSchema),
 });
 
 export type PeopleOrgChartResponse = z.infer<

package/src/index.ts

@@ -173,8 +173,6 @@ export {
   PeopleOrgChartNodeSchema,
   PeopleOrgChartEdgeSchema,
   PeopleOrgChartOpenRoleSchema,
-  UnitHeadOriginSchema,
-  PeopleOrgChartUnitHeadSchema,
   PeopleOrgChartResponseSchema,
 } from "./identity/index";
 export type {
@@ -182,8 +180,6 @@ export type {
   PeopleOrgChartNode,
   PeopleOrgChartEdge,
   PeopleOrgChartOpenRole,
-  UnitHeadOrigin,
-  PeopleOrgChartUnitHead,
   PeopleOrgChartResponse,
 } from "./identity/index";
 

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

@@ -98,8 +98,6 @@ describe("OrgUnitTreeNodeSchema", () => {
       memberCount: 5,
       openRoleCount: 1,
       missingAtNextLevel: null,
-      headUserId: null,
-      headOrigin: null,
     };
     expect(() => OrgUnitTreeNodeSchema.parse(base)).not.toThrow();
     expect(() => OrgUnitTreeNodeSchema.parse({ ...base, depth: 0 })).toThrow();
@@ -114,8 +112,6 @@ describe("OrgUnitTreeNodeSchema", () => {
       memberCount: 5,
       openRoleCount: 0,
       missingAtNextLevel: null,
-      headUserId: null,
-      headOrigin: null,
     };
     expect(() => OrgUnitTreeNodeSchema.parse(base)).not.toThrow();
     expect(() =>
@@ -133,6 +129,7 @@ describe("OpenRoleSchema", () => {
     targetStartDate: "2026-09-01",
     status: "open",
     filledByUserId: null,
+    reportsToUserId: null,
     createdAt: "2026-04-17T00:00:00Z",
     updatedAt: "2026-04-17T00:00:00Z",
     ...overrides,

package/src/org/schemas.ts

@@ -949,16 +949,6 @@ export const OrgUnitTreeNodeSchema = OrgUnitSchema.extend({
    */
   openRoleCount: z.number().int().min(0),
   missingAtNextLevel: MissingAtNextLevelSchema.nullable(),
-  /**
-   * The unit head (ADR-BE-284): the person this unit (and its person-less
-   * children) anchors under in the people chart — a presentation "tether", NOT
-   * authority. `headUserId` is null when no head is resolved (e.g. an empty
-   * unit with no members). `headOrigin` is `'user'` for an explicit choice,
-   * `'inferred'` for a system default (so the management UI can show Pinned vs
-   * Auto and offer revert-to-auto), or null when there is no head.
-   */
-  headUserId: z.string().uuid().nullable(),
-  headOrigin: z.enum(["user", "inferred"]).nullable(),
 });
 
 export const OrgUnitMembershipSchema = z.object({
@@ -989,6 +979,10 @@ export const OpenRoleSchema = z.object({
   targetStartDate: z.string().nullable(),
   status: OpenRoleStatusSchema,
   filledByUserId: z.string().uuid().nullable(),
+  // The open role's own reporting edge (ADR-BE-291): defaults to its creator,
+  // editable/clearable. Drives chart placement now that the unit-head anchor is
+  // retired (ADR-BE-292). Null → unmanaged (Unassigned bucket).
+  reportsToUserId: z.string().uuid().nullable(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });

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",
 };