@company-semantics/contracts 13.15.0 → 13.17.0

package/package.json

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

package/src/__tests__/resource-keys.test.ts

@@ -31,6 +31,34 @@ describe("resource-keys: orgUnitOwners (org-scoped)", () => {
   });
 });
 
+describe("resource-keys: orgUnitOpenRoles (per-unit identity)", () => {
+  const UNIT_ID = "33333333-3333-4333-8333-333333333333";
+  const key: ResourceKey = {
+    type: "orgUnitOpenRoles",
+    orgId: ORG_ID,
+    unitId: UNIT_ID,
+  };
+
+  it("toQueryKey produces [type, orgId, unitId]", () => {
+    const qk = toQueryKey(key);
+    expect(qk).toEqual(["orgUnitOpenRoles", ORG_ID, UNIT_ID]);
+    expect(qk).toHaveLength(3);
+  });
+
+  it("roundtrips through fromQueryKey", () => {
+    const parsed = fromQueryKey(toQueryKey(key));
+    expect(parsed).toEqual(key);
+  });
+
+  it("matchesResourceKey is unitId-scoped: rejects a different unit", () => {
+    const otherUnit = "44444444-4444-4444-8444-444444444444";
+    expect(matchesResourceKey(toQueryKey(key), key)).toBe(true);
+    expect(
+      matchesResourceKey(["orgUnitOpenRoles", ORG_ID, otherUnit], key),
+    ).toBe(false);
+  });
+});
+
 describe("resource-keys: system-scoped internalAdmin* types", () => {
   const systemTypes = [
     "internalAdminAiProviders",

package/src/api/generated.ts

@@ -1972,6 +1972,24 @@ 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;
@@ -4287,6 +4305,8 @@ export interface components {
                     count: number;
                     userIds: string[];
                 } | null;
+                headUserId: string | null;
+                headOrigin: ("user" | "inferred") | null;
             }[];
         };
         OrgUnitDescendantsResponse: {
@@ -4435,6 +4455,8 @@ export interface components {
                     count: number;
                     userIds: string[];
                 } | null;
+                headUserId: string | null;
+                headOrigin: ("user" | "inferred") | null;
             }[];
             levelConfig: {
                 /** Format: uuid */
@@ -4579,6 +4601,12 @@ 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 +4721,14 @@ export interface components {
                 unitId: string;
                 title: string | null;
             }[];
+            unitHeads: {
+                /** Format: uuid */
+                unitId: string;
+                /** Format: uuid */
+                headUserId: string;
+                /** @enum {string} */
+                origin: "user" | "inferred";
+            }[];
         };
         /** @description Polling snapshot of a generic ingestion operation. */
         IngestionOperationPollResponse: {
@@ -8444,6 +8480,57 @@ 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;

package/src/identity/index.ts

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

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

@@ -66,6 +66,29 @@ 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
 // ---------------------------------------------------------------------------
@@ -74,6 +97,7 @@ 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,6 +173,8 @@ export {
   PeopleOrgChartNodeSchema,
   PeopleOrgChartEdgeSchema,
   PeopleOrgChartOpenRoleSchema,
+  UnitHeadOriginSchema,
+  PeopleOrgChartUnitHeadSchema,
   PeopleOrgChartResponseSchema,
 } from "./identity/index";
 export type {
@@ -180,6 +182,8 @@ export type {
   PeopleOrgChartNode,
   PeopleOrgChartEdge,
   PeopleOrgChartOpenRole,
+  UnitHeadOrigin,
+  PeopleOrgChartUnitHead,
   PeopleOrgChartResponse,
 } from "./identity/index";
 

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

@@ -98,6 +98,8 @@ 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();
@@ -112,6 +114,8 @@ describe("OrgUnitTreeNodeSchema", () => {
       memberCount: 5,
       openRoleCount: 0,
       missingAtNextLevel: null,
+      headUserId: null,
+      headOrigin: null,
     };
     expect(() => OrgUnitTreeNodeSchema.parse(base)).not.toThrow();
     expect(() =>

package/src/org/schemas.ts

@@ -947,6 +947,16 @@ 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({

package/src/resource-keys.ts

@@ -36,6 +36,11 @@ export type ResourceKey =
   | { type: "orgUnitAncestors"; orgId: string; unitId: string }
   | { type: "orgUnitMemberships"; orgId: string; unitId: string }
   | { type: "orgUnitPermissions"; orgId: string; unitId: string }
+  // Open roles seated in a unit (ADR-BE-277) — a per-unit list, unitId-scoped
+  // like memberships/permissions. Read in the unit members view and the
+  // org-chart card; refreshed as a graph target of orgTree on structural
+  // mutations (create / advance lifecycle / fill). See ADR-CONTRACTS-065.
+  | { type: "orgUnitOpenRoles"; orgId: string; unitId: string }
   // Org-unit owners list (ADR-CONTRACTS-052) — owners are an org-wide
   // projection, not a per-unit collection, so unitId is intentionally excluded.
   | { type: "orgUnitOwners"; orgId: string }
@@ -145,6 +150,7 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "orgUnitAncestors":
     case "orgUnitMemberships":
     case "orgUnitPermissions":
+    case "orgUnitOpenRoles":
       return [key.type, key.orgId, key.unitId] as const;
 
     // User-scoped
@@ -218,6 +224,7 @@ export function fromQueryKey(queryKey: readonly string[]): ResourceKey {
     orgUnitAncestors: "unitId",
     orgUnitMemberships: "unitId",
     orgUnitPermissions: "unitId",
+    orgUnitOpenRoles: "unitId",
   };
 
   if (type in identityFields) {