@company-semantics/contracts 60.0.0 → 62.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "60.0.0",
+  "version": "62.0.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 = '5b50d2608eb0' as const;
+export const SPEC_HASH_FULL = '5b50d2608eb090a8a020d1219d8f3ba9d99f825c72fd5f5695f9d2542f32b8a3' 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: {
@@ -5628,6 +5648,7 @@ export interface components {
                 hasChildren: boolean;
                 memberCount: number;
                 openRoleCount: number;
+                placedPeopleCount: number;
                 missingAtNextLevel: {
                     count: number;
                     userIds: string[];
@@ -5776,6 +5797,7 @@ export interface components {
                 hasChildren: boolean;
                 memberCount: number;
                 openRoleCount: number;
+                placedPeopleCount: number;
                 missingAtNextLevel: {
                     count: number;
                     userIds: string[];

package/src/decisions/types.ts

@@ -71,7 +71,29 @@ export type DecisionEffect =
    * derivation to run again. Carries the reason so the follow-up has something
    * to act on, and so the reviewer is not told "saved" when nothing moved.
    */
-  | { readonly kind: "needs_reinference"; readonly note: string };
+  | { readonly kind: "needs_reinference"; readonly note: string }
+  /**
+   * Mark a person as the head of a DURABLE unit, and optionally set that unit's
+   * owner label. Today the only producer names the org root, so accepting is how
+   * an imported chart's CEO becomes the workspace's root owner.
+   *
+   * DURABLE addressing, not a temp id: post-apply every unit is durable, so a
+   * real id is the general form. A temp id would serve only corrections to
+   * not-yet-created units, which a proposal's own `headPersonId` already covers
+   * with no effect at all.
+   *
+   * THIS EFFECT NEVER MINTS AUTHORITY. It writes a presentation/semantic marker
+   * and a label. Granting unit or account ownership stays with the human-gated
+   * ownership route — a root-unit owner IS an account owner, so an automated
+   * grant would be a privilege-escalation path.
+   */
+  | {
+      readonly kind: "set_unit_head";
+      readonly unitId: string;
+      readonly personId: string;
+      /** Non-null also sets the unit's owner label; null marks the head only. */
+      readonly title: string | null;
+    };
 
 /** The closed set of effect kinds, as runtime data for validators. */
 export const DECISION_EFFECT_KINDS = [
@@ -81,6 +103,7 @@ export const DECISION_EFFECT_KINDS = [
   "unadopt_unit",
   "archive_unit",
   "needs_reinference",
+  "set_unit_head",
 ] as const satisfies ReadonlyArray<DecisionEffect["kind"]>;
 
 /** One answer a human may give, with what it means and what it does. */

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,6 +1581,18 @@ export const MissingAtNextLevelSchema = z.object({
 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.
+   *
+   * 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).
+   */
   memberCount: z.number().int().min(0),
   /**
    * Active open roles (`open` + `hiring`) rolled up over this unit's subtree,
@@ -1588,6 +1600,18 @@ export const OrgUnitTreeNodeSchema = OrgUnitSchema.extend({
    * count split in the people surfaces. `memberCount` stays real-members-only.
    */
   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),
   missingAtNextLevel: MissingAtNextLevelSchema.nullable(),
 });