@company-semantics/contracts 13.16.0 → 13.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "13.16.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/people-org-chart.ts

@@ -69,7 +69,7 @@ export type PeopleOrgChartOpenRole = z.infer<
 // ---------------------------------------------------------------------------
 // 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-283), NOT authority.
+// 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,

package/src/org/schemas.ts

@@ -948,7 +948,7 @@ export const OrgUnitTreeNodeSchema = OrgUnitSchema.extend({
   openRoleCount: z.number().int().min(0),
   missingAtNextLevel: MissingAtNextLevelSchema.nullable(),
   /**
-   * The unit head (ADR-BE-283): the person this unit (and its person-less
+   * 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,

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) {