@company-semantics/contracts 51.2.0 → 52.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "51.2.0",
+  "version": "52.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 = 'b044ca016033' as const;
-export const SPEC_HASH_FULL = 'b044ca016033c3a7224160a73898e3f551218dbef0139a23601f1ca4eb171d15' as const;
+export const SPEC_HASH = 'd0171aedf623' as const;
+export const SPEC_HASH_FULL = 'd0171aedf623604dc721fb42b626ebc019afcc2fda9be59e1f06360cd6a4fcca' as const;

package/src/api/generated.ts

@@ -3616,6 +3616,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/comments/threads/{threadId}/accept-apply": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Apply a claimed suggestion and record the accept, on one commit */
+        post: operations["acceptSuggestionApply"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/comments/threads/{threadId}/accept-release": {
         parameters: {
             query?: never;
@@ -6542,6 +6559,15 @@ export interface components {
         SuggestionClaimRequest: {
             claimToken: string;
         };
+        /** @description The accepted thread and the document mutation that landed with it, on one commit. */
+        SuggestionAcceptAppliedResponse: {
+            thread: components["schemas"]["CommentThreadSummary"];
+            applied: components["schemas"]["SuggestionApplied"];
+        };
+        SuggestionApplyRequest: {
+            claimToken: string;
+            expectedRevision: string;
+        };
         /** @description Server-enforced collaboration size limits, published so clients can pre-check. */
         CollabSyncLimits: {
             maxUpdateBytes: number;
@@ -6712,6 +6738,17 @@ export interface components {
             createdAt: string;
             updatedAt: string;
         };
+        /** @description What the accept-apply did to the document: whether there was a CRDT to write into at all, and the canonical edit that was spliced. */
+        SuggestionApplied: {
+            bridged: boolean;
+            edit: components["schemas"]["SuggestionPlannedEdit"];
+        };
+        /** @description The canonical mutation derived from the stored payload: splice out deleteLength UTF-16 code units at `at` and insert `insert`. */
+        SuggestionPlannedEdit: {
+            at: number;
+            deleteLength: number;
+            insert: string;
+        };
     };
     responses: never;
     parameters: never;
@@ -12979,6 +13016,53 @@ export interface operations {
             };
         };
     };
+    acceptSuggestionApply: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                threadId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SuggestionApplyRequest"];
+            };
+        };
+        responses: {
+            /** @description Suggestion applied and accepted: the canonical edit landed in the document and the thread was resolved on the SAME transaction */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SuggestionAcceptAppliedResponse"];
+                };
+            };
+            /** @description Malformed claim token or expectedRevision */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Thread not found, or the caller may not read its subject */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Terminal, never retry: not a suggestion thread, the token does not match a live claim, the document moved past expectedRevision, the anchor is orphaned or no longer reads, or the payload resolves to a no-op — re-read the document and decide again */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     releaseSuggestionClaim: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -23,6 +23,7 @@ export const openApiRoutes = {
   '/api/chats/{id}/pin': ['DELETE', 'POST'],
   '/api/comments': ['GET'],
   '/api/comments/threads': ['POST'],
+  '/api/comments/threads/{threadId}/accept-apply': ['POST'],
   '/api/comments/threads/{threadId}/accept-complete': ['POST'],
   '/api/comments/threads/{threadId}/accept-intent': ['POST'],
   '/api/comments/threads/{threadId}/accept-release': ['POST'],

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),
 });