@company-semantics/contracts 62.0.0 → 62.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "62.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 = '5b50d2608eb0' as const;
-export const SPEC_HASH_FULL = '5b50d2608eb090a8a020d1219d8f3ba9d99f825c72fd5f5695f9d2542f32b8a3' as const;
+export const SPEC_HASH = '8e4ad15ffd00' as const;
+export const SPEC_HASH_FULL = '8e4ad15ffd00b9b83f7adb26bd7bfdff0c03994756b3022b9dbc27f3ba9f7852' as const;

package/src/api/generated.ts

@@ -5646,8 +5646,11 @@ 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;
@@ -5795,8 +5798,11 @@ 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;

package/src/org/schemas.ts

@@ -1582,36 +1582,48 @@ export const OrgUnitTreeNodeSchema = OrgUnitSchema.extend({
   depth: z.number().int().min(1).max(5),
   hasChildren: z.boolean(),
   /**
-   * ACCOUNTS homed in this unit's subtree — a rollup of `home_assignments`,
-   * whose `user_id` is NOT NULL. A person who has never signed in therefore
-   * cannot contribute to it, and a freshly HRIS-synced org is ~93 people and
-   * one account, so this is legitimately 0 for a fully staffed department.
+   * 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.
    *
-   * That is not a defect: it is the right population for anything that needs an
-   * account to act on — the share dialog's fanout, the unit-scoped members
-   * table. For "how many people are in this department", use
-   * {@link placedPeopleCount}. The two answer different questions and
-   * legitimately disagree (ADR-CONTRACTS-150, ADR-BE-657).
+   * 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),
+  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.",
+    ),
   /**
-   * 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.
+   * 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),
-  /**
-   * Distinct PEOPLE holding a live canonical seat in this unit's subtree —
-   * `placement_role='canonical'`, `status <> 'ended'`, keyed by
-   * `positions.unit_id`. Account linkage is not consulted, so this is the count
-   * that describes an imported workforce.
-   *
-   * Placement and home are independent graphs (ADR-CTRL-159): a person seated
-   * here may be homed elsewhere, and vice versa. Deliberately does NOT filter
-   * `positions.status` — an occupied `closed` seat still draws a card on the
-   * org chart, and a filter here would disagree with it (ADR-BE-657).
-   */
-  placedPeopleCount: 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(),
 });