@company-semantics/contracts 51.3.0 → 52.0.0

package/package.json

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

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

@@ -0,0 +1,75 @@
+import { describe, it, expect } from "vitest";
+
+import {
+  PeopleOrgChartSeatOccupantSchema,
+  PeopleOrgChartSeatSchema,
+} from "../people-org-chart.js";
+
+const PERSON_ID = "3f2504e0-4f89-41d3-9a0c-0305e82c3301";
+const USER_ID = "9c5b94b1-35ad-49bb-b118-8e8fc24abf80";
+const UNIT_ID = "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b";
+const POSITION_ID = "11111111-1111-4111-8111-111111111111";
+
+describe("PeopleOrgChartSeatOccupantSchema", () => {
+  const accountless = {
+    personId: PERSON_ID,
+    userId: null,
+    fullName: "Ada Lovelace",
+    avatarUrl: null,
+    primaryUnitId: null,
+    ownedUnits: [],
+  };
+
+  it("parses an accountless occupant keyed by personId", () => {
+    const occupant = PeopleOrgChartSeatOccupantSchema.parse(accountless);
+    expect(occupant.personId).toBe(PERSON_ID);
+    expect(occupant.userId).toBeNull();
+  });
+
+  it("parses an account-linked occupant carrying a uuid userId", () => {
+    const occupant = PeopleOrgChartSeatOccupantSchema.parse({
+      ...accountless,
+      userId: USER_ID,
+    });
+    expect(occupant.userId).toBe(USER_ID);
+  });
+
+  it("requires personId", () => {
+    const { personId: _omitted, ...withoutPersonId } = accountless;
+    expect(() =>
+      PeopleOrgChartSeatOccupantSchema.parse(withoutPersonId),
+    ).toThrow();
+  });
+
+  // userId is .nullable() WITHOUT .optional(): the server always emits the key,
+  // so an absent userId must be unrepresentable rather than silently null.
+  it("rejects an absent userId — nullable is not optional", () => {
+    const { userId: _omitted, ...withoutUserId } = accountless;
+    const result = PeopleOrgChartSeatOccupantSchema.safeParse(withoutUserId);
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("PeopleOrgChartSeatSchema", () => {
+  it("admits a filled seat whose only occupant is accountless", () => {
+    const seat = PeopleOrgChartSeatSchema.parse({
+      id: POSITION_ID,
+      unitId: UNIT_ID,
+      title: "Analyst",
+      status: "filled",
+      hiring: false,
+      occupants: [
+        {
+          personId: PERSON_ID,
+          userId: null,
+          fullName: "Ada Lovelace",
+          avatarUrl: null,
+          primaryUnitId: null,
+          ownedUnits: [],
+        },
+      ],
+    });
+    expect(seat.occupants).toHaveLength(1);
+    expect(seat.occupants[0]?.userId).toBeNull();
+  });
+});

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

@@ -88,11 +88,30 @@ export type PeopleOrgChartSeatStatus = z.infer<
   typeof PeopleOrgChartSeatStatusSchema
 >;
 
-// Person-scoped attributes of a seat's holder — keyed by `userId`, they travel
-// with the person across seats (ADR-BE-329: a vacant seat grants none of these
-// by construction). Mirrors the legacy `PeopleOrgChartNode` person fields.
+// Person-scoped attributes of a seat's holder — they travel with the person
+// across seats (ADR-BE-329: a vacant seat grants none of these by
+// construction).
+//
+// KEYED BY personId. The org chart is a graph of POSITIONS with PEOPLE
+// projected onto them; the account link is an attribute of the person, never
+// their identity. `userId` is the 0..1 account link and is null for the many
+// people who never sign in (an HRIS import is the normal case, not the edge).
+//
+// For an ACCOUNTLESS occupant each of the following is a FACT, not a fallback:
+//   avatarUrl     always null  -- `persons` carries no avatar column
+//   primaryUnitId always null  -- `home_assignments` is user-keyed, so there is
+//                                 no representable home; null means "no home
+//                                 row", NOT "home unknown, substitute the seat"
+//   ownedUnits    always []    -- the projection of "no grant row exists".
+//                                 Authority is account-keyed; an accountless
+//                                 person holds none. This is the authority
+//                                 boundary made visible.
 export const PeopleOrgChartSeatOccupantSchema = z.object({
-  userId: z.string().uuid(),
+  personId: z.string().uuid(),
+  // .nullable() WITHOUT .optional(): this is a server-generated response, so
+  // `undefined` must be unrepresentable. PersonSchema.userId is
+  // .nullable().optional() because it is an input-shaped vocabulary.
+  userId: z.string().uuid().nullable(),
   fullName: z.string(),
   avatarUrl: z.string().nullable(),
   // Stable HOME unit (home_assignments), not the seat unit — mirrors the legacy
@@ -123,8 +142,8 @@ export const PeopleOrgChartSeatSchema = z.object({
   // fulfillment row ⇒ false.
   hiring: z.boolean(),
   // The seat's current holders. [] ⇒ vacant (the old "open role"); >= 1 ⇒
-  // occupied (the old "member"). Only account-linked, active/interim occupants
-  // appear, mirroring the legacy node-keying.
+  // occupied (the old "member"). Every canonical occupant appears, account or
+  // not — occupancy, not account linkage, is what admits a person here.
   occupants: z.array(PeopleOrgChartSeatOccupantSchema),
 });