@company-semantics/contracts 61.0.0 → 62.1.0

package/package.json

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

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 = '4ee1bc3befbf' as const;
-export const SPEC_HASH_FULL = '4ee1bc3befbf8bb865b4bdad38b892c59f198fec45acdcdde93a067a678516b3' as const;
+export const SPEC_HASH = '8e4ad15ffd00' as const;
+export const SPEC_HASH_FULL = '8e4ad15ffd00b9b83f7adb26bd7bfdff0c03994756b3022b9dbc27f3ba9f7852' as const;

package/src/api/generated.ts

@@ -4263,8 +4263,28 @@ export interface components {
             reason: "external-mutation" | "bulk-operation" | "sync-required";
         };
         AiChatRequest: {
+            /**
+             * @default submit-message
+             * @constant
+             */
+            trigger: "submit-message";
+            id?: string;
+            messageId?: string;
+            message?: {
+                id: string;
+                /** @constant */
+                role: "user";
+                parts: unknown[];
+            };
             messages: unknown[];
+            runtimeProfile?: string;
+        } | {
+            /** @constant */
+            trigger: "regenerate-message";
             id?: string;
+            messageId?: string;
+            message?: unknown;
+            messages: unknown[];
             runtimeProfile?: string;
         };
         ProactiveChatResolution: {
@@ -5626,8 +5646,12 @@ export interface components {
                 updatedAt: string;
                 depth: number;
                 hasChildren: boolean;
+                /** @description Accounts with a home assignment, rolled up over this unit's subtree. Legitimately 0 for a fully staffed department in an HRIS-imported org, where almost nobody has signed in — use placedPeopleCount for headcount. */
                 memberCount: number;
+                /** @description Active open roles (`open` + `hiring`) rolled up over this unit's subtree. Vacant seats only — an HRIS-imported seat is `lifecycle_owner='import:hris'` and is counted by neither this nor memberCount. */
                 openRoleCount: number;
+                /** @description Distinct people holding a live canonical seat in this unit's subtree, whether or not they have an account. Deliberately does NOT filter positions.status: an occupied `closed` seat still draws a card on the org chart, so a filter here would disagree with it. */
+                placedPeopleCount: number;
                 missingAtNextLevel: {
                     count: number;
                     userIds: string[];
@@ -5774,8 +5798,12 @@ export interface components {
                 updatedAt: string;
                 depth: number;
                 hasChildren: boolean;
+                /** @description Accounts with a home assignment, rolled up over this unit's subtree. Legitimately 0 for a fully staffed department in an HRIS-imported org, where almost nobody has signed in — use placedPeopleCount for headcount. */
                 memberCount: number;
+                /** @description Active open roles (`open` + `hiring`) rolled up over this unit's subtree. Vacant seats only — an HRIS-imported seat is `lifecycle_owner='import:hris'` and is counted by neither this nor memberCount. */
                 openRoleCount: number;
+                /** @description Distinct people holding a live canonical seat in this unit's subtree, whether or not they have an account. Deliberately does NOT filter positions.status: an occupied `closed` seat still draws a card on the org chart, so a filter here would disagree with it. */
+                placedPeopleCount: number;
                 missingAtNextLevel: {
                     count: number;
                     userIds: string[];

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

@@ -97,6 +97,7 @@ describe("OrgUnitTreeNodeSchema", () => {
       hasChildren: true,
       memberCount: 5,
       openRoleCount: 1,
+      placedPeopleCount: 5,
       missingAtNextLevel: null,
     };
     expect(() => OrgUnitTreeNodeSchema.parse(base)).not.toThrow();
@@ -111,6 +112,7 @@ describe("OrgUnitTreeNodeSchema", () => {
       hasChildren: true,
       memberCount: 5,
       openRoleCount: 0,
+      placedPeopleCount: 5,
       missingAtNextLevel: null,
     };
     expect(() => OrgUnitTreeNodeSchema.parse(base)).not.toThrow();
@@ -118,6 +120,30 @@ describe("OrgUnitTreeNodeSchema", () => {
       OrgUnitTreeNodeSchema.parse({ ...base, openRoleCount: -1 }),
     ).toThrow();
   });
+
+  it("requires placedPeopleCount, and lets it disagree with memberCount", () => {
+    const base = {
+      ...makeUnit(),
+      depth: 3,
+      hasChildren: false,
+      // The HRIS shape: nobody in this department has an account, so the
+      // account-keyed rollup is 0 while 22 people hold seats in it. Both are
+      // correct; they answer different questions (ADR-CONTRACTS-150).
+      memberCount: 0,
+      openRoleCount: 0,
+      placedPeopleCount: 22,
+      missingAtNextLevel: null,
+    };
+    expect(() => OrgUnitTreeNodeSchema.parse(base)).not.toThrow();
+
+    // Required, not optional — pre-launch there is no back-compat window, and
+    // an absent count would be indistinguishable from an empty unit.
+    const { placedPeopleCount: _omitted, ...withoutIt } = base;
+    expect(() => OrgUnitTreeNodeSchema.parse(withoutIt)).toThrow();
+    expect(() =>
+      OrgUnitTreeNodeSchema.parse({ ...base, placedPeopleCount: -1 }),
+    ).toThrow();
+  });
 });
 
 describe("OpenRoleSchema", () => {

package/src/org/schemas.ts

@@ -1581,13 +1581,49 @@ export const MissingAtNextLevelSchema = z.object({
 export const OrgUnitTreeNodeSchema = OrgUnitSchema.extend({
   depth: z.number().int().min(1).max(5),
   hasChildren: z.boolean(),
-  memberCount: z.number().int().min(0),
   /**
-   * Active open roles (`open` + `hiring`) rolled up over this unit's subtree,
-   * the same way `memberCount` rolls up real members. Drives the "(N + M open)"
-   * count split in the people surfaces. `memberCount` stays real-members-only.
+   * WHAT it counts is the `.describe()` below — the single field-level
+   * description, which reaches `openapi/backend.yaml` and the generated API
+   * types. This comment carries only WHY, so the two cannot drift into
+   * disagreeing.
+   *
+   * Why accounts: it is the right population for anything that needs an account
+   * to act on — the share dialog's fanout, the unit-scoped members table. It is
+   * backed by `home_assignments`, whose `user_id` is NOT NULL, so an accountless
+   * person structurally cannot appear in it. Deliberately NOT redefined and NOT
+   * deprecated; {@link placedPeopleCount} answers the headcount question, and the
+   * two legitimately disagree (ADR-CONTRACTS-150, ADR-BE-657).
+   */
+  memberCount: z
+    .number()
+    .int()
+    .min(0)
+    .describe(
+      "Accounts with a home assignment, rolled up over this unit's subtree. Legitimately 0 for a fully staffed department in an HRIS-imported org, where almost nobody has signed in — use placedPeopleCount for headcount.",
+    ),
+  /** Drives the "(N + M open)" count split in the people surfaces. */
+  openRoleCount: z
+    .number()
+    .int()
+    .min(0)
+    .describe(
+      "Active open roles (`open` + `hiring`) rolled up over this unit's subtree. Vacant seats only — an HRIS-imported seat is `lifecycle_owner='import:hris'` and is counted by neither this nor memberCount.",
+    ),
+  /**
+   * Predicate: `placement_role='canonical'`, `status <> 'ended'`, keyed by
+   * `positions.unit_id`. Placement and home are independent graphs
+   * (ADR-CTRL-159), so a person seated here may be homed elsewhere and vice
+   * versa. The `positions.status` non-filter stated in the `.describe()` below
+   * is deliberate and load-bearing — the backend pins it with a test whose name
+   * says so (ADR-BE-657).
    */
-  openRoleCount: z.number().int().min(0),
+  placedPeopleCount: z
+    .number()
+    .int()
+    .min(0)
+    .describe(
+      "Distinct people holding a live canonical seat in this unit's subtree, whether or not they have an account. Deliberately does NOT filter positions.status: an occupied `closed` seat still draws a card on the org chart, so a filter here would disagree with it.",
+    ),
   missingAtNextLevel: MissingAtNextLevelSchema.nullable(),
 });