@company-semantics/contracts 13.15.0 → 13.16.0

package/package.json

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

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-283), 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-283): 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({