@company-semantics/contracts 25.0.0 → 26.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "25.0.0",
+  "version": "26.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 = 'ca30049e5670' as const;
-export const SPEC_HASH_FULL = 'ca30049e56707141ae807a8c218d97947e9aeade592540d5e2609eb985f43480' as const;
+export const SPEC_HASH = 'eb984ad65268' as const;
+export const SPEC_HASH_FULL = 'eb984ad65268ce0b6877c26b331bef135bab04876e6fe9aa732844cd52f29353' as const;

package/src/api/generated.ts

@@ -1593,6 +1593,58 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/company-md/docs/{id}/access-requests": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List a node’s access requests (owner inbox) */
+        get: operations["listCompanyMdAccessRequests"];
+        put?: never;
+        /** Request access to a locked company.md node */
+        post: operations["createCompanyMdAccessRequest"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/company-md/access-requests/{id}/approve": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Approve an access request (first owner wins; mints a grant) */
+        post: operations["approveCompanyMdAccessRequest"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/company-md/access-requests/{id}/deny": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Deny an access request (first owner wins) */
+        post: operations["denyCompanyMdAccessRequest"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/company-md/search": {
         parameters: {
             query?: never;
@@ -2144,6 +2196,40 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/org-units/{unitId}/open-roles/{roleId}/unit": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /** Move an open role to a different unit (set the seat's unit) */
+        put: operations["setOrgUnitOpenRoleUnit"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/org-units/{unitId}/open-roles/{roleId}/title": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /** Set an open role's seat title */
+        put: operations["setOrgUnitOpenRoleTitle"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/users/org-chart": {
         parameters: {
             query?: never;
@@ -4341,6 +4427,16 @@ export interface components {
             /** Format: uuid */
             toUserId: string;
         };
+        AccessRequestCreate: {
+            message?: string;
+        };
+        ApproveAccessRequest: {
+            /** @enum {string} */
+            accessLevel: "editor" | "commenter" | "viewer";
+        };
+        DenyAccessRequest: {
+            reason?: string;
+        };
         /** @description Ranked retrieval hits plus the source kinds actually searched. */
         CompanyMdSearchResponse: {
             hits: {
@@ -4877,6 +4973,38 @@ export interface components {
             };
         };
         PeopleOrgChartResponse: {
+            seats: {
+                /** Format: uuid */
+                id: string;
+                /** Format: uuid */
+                unitId: string;
+                title: string | null;
+                /** @enum {string} */
+                status: "planned" | "open" | "filled" | "closed";
+                hiring: boolean;
+                occupants: {
+                    /** Format: uuid */
+                    userId: string;
+                    fullName: string;
+                    avatarUrl: string | null;
+                    primaryUnitId: string | null;
+                    ownedUnits: {
+                        /** Format: uuid */
+                        id: string;
+                        name: string;
+                        /** @enum {string} */
+                        mutability: "derived" | "user_managed";
+                    }[];
+                }[];
+            }[];
+            seatEdges: {
+                /** Format: uuid */
+                reportPositionId: string;
+                /** Format: uuid */
+                managerPositionId: string;
+                /** @enum {string} */
+                relationshipType: "solid" | "dotted";
+            }[];
             nodes: {
                 /** Format: uuid */
                 id: string;
@@ -8063,6 +8191,140 @@ export interface operations {
             };
         };
     };
+    listCompanyMdAccessRequests: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Access requests for the node, with requestor identity */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Caller cannot manage sharing for this node */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    createCompanyMdAccessRequest: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["AccessRequestCreate"];
+            };
+        };
+        responses: {
+            /** @description Pending access request created (or the existing pending request) */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Cannot request access (already a reader, or no-leak node) */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    approveCompanyMdAccessRequest: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ApproveAccessRequest"];
+            };
+        };
+        responses: {
+            /** @description Approved; the requester gains a normal grant */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Request not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Already resolved by another owner */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    denyCompanyMdAccessRequest: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["DenyAccessRequest"];
+            };
+        };
+        responses: {
+            /** @description Denied */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Request not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Already resolved by another owner */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     searchCompanyMd: {
         parameters: {
             query?: never;
@@ -9109,6 +9371,65 @@ export interface operations {
             };
         };
     };
+    setOrgUnitOpenRoleUnit: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+                roleId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** Format: uuid */
+                    unitId: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Open role moved to the destination unit */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OpenRoleResponse"];
+                };
+            };
+        };
+    };
+    setOrgUnitOpenRoleTitle: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+                roleId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    title: string | null;
+                };
+            };
+        };
+        responses: {
+            /** @description Open role with updated title */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OpenRoleResponse"];
+                };
+            };
+        };
+    };
     getPeopleOrgChart: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -21,8 +21,11 @@ export const openApiRoutes = {
   '/api/chats/{id}/messages': ['POST'],
   '/api/chats/{id}/messages/{messageId}': ['DELETE'],
   '/api/chats/{id}/pin': ['DELETE', 'POST'],
+  '/api/company-md/access-requests/{id}/approve': ['POST'],
+  '/api/company-md/access-requests/{id}/deny': ['POST'],
   '/api/company-md/context-bank': ['POST'],
   '/api/company-md/docs/{id}': ['GET'],
+  '/api/company-md/docs/{id}/access-requests': ['GET', 'POST'],
   '/api/company-md/docs/{id}/content': ['PUT'],
   '/api/company-md/docs/{id}/context-bank': ['GET'],
   '/api/company-md/docs/{id}/context-bank/associate': ['POST'],
@@ -54,6 +57,7 @@ export const openApiRoutes = {
   '/api/executions/{executionId}/timeline': ['GET'],
   '/api/executions/{executionId}/undo': ['POST'],
   '/api/factory/floor': ['GET'],
+  '/api/factory/kpis': ['GET'],
   '/api/factory/snapshot': ['GET'],
   '/api/ingestion/operations/{id}': ['GET'],
   '/api/internal-admin/impersonate/end': ['POST'],
@@ -91,6 +95,8 @@ export const openApiRoutes = {
   '/api/org-units/{unitId}/open-roles/{roleId}': ['PATCH'],
   '/api/org-units/{unitId}/open-roles/{roleId}/fill': ['POST'],
   '/api/org-units/{unitId}/open-roles/{roleId}/reports-to': ['PUT'],
+  '/api/org-units/{unitId}/open-roles/{roleId}/title': ['PUT'],
+  '/api/org-units/{unitId}/open-roles/{roleId}/unit': ['PUT'],
   '/api/org-units/{unitId}/owners': ['GET'],
   '/api/org-units/{unitId}/permissions': ['GET'],
   '/api/org-units/{unitId}/relationships': ['GET', 'POST'],

package/src/identity/README.md

@@ -61,6 +61,14 @@ TypeScript types and functions for user identity and display name resolution.
 - `PeopleOrgChartOwnedUnitSchema`
 - `PeopleOrgChartResponse` _(type)_
 - `PeopleOrgChartResponseSchema`
+- `PeopleOrgChartSeat` _(type)_
+- `PeopleOrgChartSeatEdge` _(type)_
+- `PeopleOrgChartSeatEdgeSchema`
+- `PeopleOrgChartSeatOccupant` _(type)_
+- `PeopleOrgChartSeatOccupantSchema`
+- `PeopleOrgChartSeatSchema`
+- `PeopleOrgChartSeatStatus` _(type)_
+- `PeopleOrgChartSeatStatusSchema`
 - `Person` _(type)_
 - `PersonSchema`
 - `ProfileResponse` _(type)_

package/src/identity/index.ts

@@ -69,6 +69,10 @@ export {
   PeopleOrgChartOwnedUnitSchema,
   PeopleOrgChartEdgeSchema,
   PeopleOrgChartOpenRoleSchema,
+  PeopleOrgChartSeatStatusSchema,
+  PeopleOrgChartSeatOccupantSchema,
+  PeopleOrgChartSeatSchema,
+  PeopleOrgChartSeatEdgeSchema,
   PeopleOrgChartResponseSchema,
 } from "./people-org-chart";
 export type {
@@ -78,6 +82,10 @@ export type {
   PeopleOrgChartOwnedUnit,
   PeopleOrgChartEdge,
   PeopleOrgChartOpenRole,
+  PeopleOrgChartSeatStatus,
+  PeopleOrgChartSeatOccupant,
+  PeopleOrgChartSeat,
+  PeopleOrgChartSeatEdge,
   PeopleOrgChartResponse,
 } from "./people-org-chart";
 

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

@@ -113,6 +113,93 @@ export type PeopleOrgChartOpenRole = z.infer<
   typeof PeopleOrgChartOpenRoleSchema
 >;
 
+// ---------------------------------------------------------------------------
+// Seat — the position-centric unification (ADR-CONT-093)
+// ---------------------------------------------------------------------------
+//
+// A `PeopleOrgChartSeat` is the unified chart actor: a `positions` row carrying
+// its SEAT-SCOPED attributes (unit placement, title, seat-existence status,
+// hiring/staffing sub-state) plus an `occupants[]` array of PERSON-SCOPED
+// attributes for whoever currently holds it. The split is structural, not
+// member-vs-open-role: a VACANT seat (`occupants: []`) is the old "open role";
+// an OCCUPIED seat (`occupants.length >= 1`) is the old "member" (N occupants
+// for a co-occupied seat — forward-compatible; live data is 0/1). Reporting is
+// expressed seat→seat in `seatEdges[]`, NOT on the seat, so the edge list stays
+// the single source of truth for placement (ADR-CTRL-159). `OrgChartActorRef`
+// is retained write-only (set-manager request/response) and is removed from
+// this read model.
+//
+// This pair (`seats[]` + `seatEdges[]`) is ADDITIVE alongside the legacy
+// `nodes`/`edges`/`openRoles` during the transition; the projector dual-emits
+// both from one position pass. A later breaking minor removes the legacy half.
+
+export const PeopleOrgChartSeatStatusSchema = z.enum([
+  "planned",
+  "open",
+  "filled",
+  "closed",
+]);
+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.
+export const PeopleOrgChartSeatOccupantSchema = z.object({
+  userId: z.string().uuid(),
+  fullName: z.string(),
+  avatarUrl: z.string().nullable(),
+  // Stable HOME unit (home_assignments), not the seat unit — mirrors the legacy
+  // node's `primaryUnitId`. Null ⇒ no home assignment.
+  primaryUnitId: z.string().uuid().nullable(),
+  // Units this occupant is a local structural owner of (ADR-BE-168). Empty ⇒
+  // not a unit owner. Same shape + semantics as the legacy node's `ownedUnits`.
+  ownedUnits: z.array(PeopleOrgChartOwnedUnitSchema),
+});
+
+export type PeopleOrgChartSeatOccupant = z.infer<
+  typeof PeopleOrgChartSeatOccupantSchema
+>;
+
+export const PeopleOrgChartSeatSchema = z.object({
+  // positionId — the seat identity (stable across occupancy changes).
+  id: z.string().uuid(),
+  // positions.unit_id — the seat's placement column. The chart columns a seat by
+  // this unit regardless of occupancy.
+  unitId: z.string().uuid(),
+  // positions.title — '' is mapped to null to preserve the legacy nullable wire
+  // shape (ADR-BE-312). Seat-scoped, NOT the occupant's member-display jobTitle.
+  title: z.string().nullable(),
+  // Seat-existence lifecycle (ADR-CTRL-182).
+  status: PeopleOrgChartSeatStatusSchema,
+  // Staffing sub-state: `position_fulfillment.status != 'inactive'` (ADR-BE-312).
+  // Orthogonal to `status` — "are we trying to staff this seat?". An absent
+  // 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.
+  occupants: z.array(PeopleOrgChartSeatOccupantSchema),
+});
+
+export type PeopleOrgChartSeat = z.infer<typeof PeopleOrgChartSeatSchema>;
+
+// A seat→seat reporting edge — one row per `position_reporting` row (NOT a
+// member cross-product). Endpoints are positionIds; resolve each to its seat in
+// `seats[]`. Mirrors the legacy person-keyed `PeopleOrgChartEdge`, but keyed by
+// the stable seat identity so a vacant seat's edge is expressible without an
+// `OrgChartActorRef`.
+export const PeopleOrgChartSeatEdgeSchema = z.object({
+  reportPositionId: z.string().uuid(),
+  managerPositionId: z.string().uuid(),
+  relationshipType: ReportingRelationshipTypeSchema,
+});
+
+export type PeopleOrgChartSeatEdge = z.infer<
+  typeof PeopleOrgChartSeatEdgeSchema
+>;
+
 // ---------------------------------------------------------------------------
 // GET /api/users/org-chart
 // ---------------------------------------------------------------------------
@@ -123,6 +210,16 @@ export type PeopleOrgChartOpenRole = z.infer<
 // the render-time reporting heuristic.
 
 export const PeopleOrgChartResponseSchema = z.object({
+  // Position-centric unified view (ADR-CONT-093). `seats[]` carries every chart
+  // actor (occupied or vacant) and `seatEdges[]` the seat→seat reporting graph.
+  // ADDITIVE alongside the legacy fields below during the transition; a later
+  // breaking minor removes the legacy half.
+  seats: z.array(PeopleOrgChartSeatSchema),
+  seatEdges: z.array(PeopleOrgChartSeatEdgeSchema),
+  // Legacy, transitional (ADR-CONT-093 supersedes). Derived from the same
+  // position pass as `seats`/`seatEdges`; consumers should migrate to the seat
+  // model. `nodes` = occupied actors, `openRoles` = vacant 'open' actors,
+  // `edges` = the same reporting graph keyed by person/open-role actor refs.
   nodes: z.array(PeopleOrgChartNodeSchema),
   edges: z.array(PeopleOrgChartEdgeSchema),
   openRoles: z.array(PeopleOrgChartOpenRoleSchema),

package/src/index.ts

@@ -180,6 +180,10 @@ export {
   PeopleOrgChartOwnedUnitSchema,
   PeopleOrgChartEdgeSchema,
   PeopleOrgChartOpenRoleSchema,
+  PeopleOrgChartSeatStatusSchema,
+  PeopleOrgChartSeatOccupantSchema,
+  PeopleOrgChartSeatSchema,
+  PeopleOrgChartSeatEdgeSchema,
   PeopleOrgChartResponseSchema,
 } from "./identity/index";
 export type {
@@ -189,6 +193,10 @@ export type {
   PeopleOrgChartOwnedUnit,
   PeopleOrgChartEdge,
   PeopleOrgChartOpenRole,
+  PeopleOrgChartSeatStatus,
+  PeopleOrgChartSeatOccupant,
+  PeopleOrgChartSeat,
+  PeopleOrgChartSeatEdge,
   PeopleOrgChartResponse,
 } from "./identity/index";