@company-semantics/contracts 26.1.0 → 27.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "26.1.0",
+  "version": "27.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 = 'eb984ad65268' as const;
-export const SPEC_HASH_FULL = 'eb984ad65268ce0b6877c26b331bef135bab04876e6fe9aa732844cd52f29353' as const;
+export const SPEC_HASH = '0a8d3435dba9' as const;
+export const SPEC_HASH_FULL = '0a8d3435dba94642fe2cf529b1743d868363875302393e23cf0b9238a4f5cd47' as const;

package/src/api/generated.ts

@@ -1645,6 +1645,40 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/company-md/context-bank/search": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Search org-wide context docs the caller may view */
+        get: operations["searchCompanyMdContextDocs"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/company-md/docs/:id/context-bank/suggestions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Suggest context docs semantically nearest to a parent the caller may view */
+        get: operations["companyMdContextDocSuggestions"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/company-md/search": {
         parameters: {
             query?: never;
@@ -4437,6 +4471,14 @@ export interface components {
         DenyAccessRequest: {
             reason?: string;
         };
+        /** @description Org-wide context-doc discovery hits the caller may view. */
+        SearchContextDocsResponse: {
+            items: components["schemas"]["ContextDocDiscoveryHit"][];
+        };
+        /** @description Semantically nearest context-doc suggestions the caller may view. */
+        SuggestContextDocsResponse: {
+            items: components["schemas"]["ContextDocDiscoveryHit"][];
+        };
         /** @description Ranked retrieval hits plus the source kinds actually searched. */
         CompanyMdSearchResponse: {
             hits: {
@@ -5005,65 +5047,6 @@ export interface components {
                 /** @enum {string} */
                 relationshipType: "solid" | "dotted";
             }[];
-            nodes: {
-                /** Format: uuid */
-                id: string;
-                fullName: string;
-                jobTitle: string | null;
-                avatarUrl: string | null;
-                primaryUnitId: string | null;
-                ownedUnits: {
-                    /** Format: uuid */
-                    id: string;
-                    name: string;
-                    /** @enum {string} */
-                    mutability: "derived" | "user_managed";
-                }[];
-            }[];
-            edges: {
-                report: {
-                    /** @constant */
-                    kind: "member";
-                    /** Format: uuid */
-                    userId: string;
-                } | {
-                    /** @constant */
-                    kind: "open-role";
-                    /** Format: uuid */
-                    openRoleId: string;
-                };
-                manager: {
-                    /** @constant */
-                    kind: "member";
-                    /** Format: uuid */
-                    userId: string;
-                } | {
-                    /** @constant */
-                    kind: "open-role";
-                    /** Format: uuid */
-                    openRoleId: string;
-                };
-                /** @enum {string} */
-                relationshipType: "solid" | "dotted";
-            }[];
-            openRoles: {
-                /** Format: uuid */
-                id: string;
-                /** Format: uuid */
-                unitId: string;
-                title: string | null;
-                reportsTo: ({
-                    /** @constant */
-                    kind: "member";
-                    /** Format: uuid */
-                    userId: string;
-                } | {
-                    /** @constant */
-                    kind: "open-role";
-                    /** Format: uuid */
-                    openRoleId: string;
-                }) | null;
-            }[];
         };
         /** @description Polling snapshot of a generic ingestion operation. */
         IngestionOperationPollResponse: {
@@ -5754,6 +5737,19 @@ export interface components {
                 userAgent: string;
             } | null;
         };
+        /** @description An ACL-admitted context-doc discovery hit. */
+        ContextDocDiscoveryHit: {
+            id: string;
+            slug: string;
+            title: string;
+            /** @enum {string} */
+            visibility: "private" | "unit" | "org";
+            updatedAt: string;
+            score: number;
+            distance?: number;
+            /** @enum {string} */
+            matchedVia: "fts" | "vector";
+        };
     };
     responses: never;
     parameters: never;
@@ -8325,6 +8321,80 @@ export interface operations {
             };
         };
     };
+    searchCompanyMdContextDocs: {
+        parameters: {
+            query: {
+                q?: string;
+                parentId: string;
+                limit?: number;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description ACL-admitted context-doc discovery hits */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SearchContextDocsResponse"];
+                };
+            };
+            /** @description Invalid query parameters */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Requires org.view_company_md scope */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    companyMdContextDocSuggestions: {
+        parameters: {
+            query?: {
+                limit?: number;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description ACL-admitted semantically-nearest context-doc suggestions */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SuggestContextDocsResponse"];
+                };
+            };
+            /** @description Invalid path or query parameters */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Requires org.view_company_md scope */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     searchCompanyMd: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -24,6 +24,8 @@ export const openApiRoutes = {
   '/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/context-bank/search': ['GET'],
+  '/api/company-md/docs/:id/context-bank/suggestions': ['GET'],
   '/api/company-md/docs/{id}': ['GET'],
   '/api/company-md/docs/{id}/access-requests': ['GET', 'POST'],
   '/api/company-md/docs/{id}/content': ['PUT'],

package/src/identity/README.md

@@ -51,12 +51,6 @@ TypeScript types and functions for user identity and display name resolution.
 - `NameSource` _(type)_ — Source of the user's name data.
 - `OrgChartActorRef` _(type)_
 - `OrgChartActorRefSchema`
-- `PeopleOrgChartEdge` _(type)_
-- `PeopleOrgChartEdgeSchema`
-- `PeopleOrgChartNode` _(type)_
-- `PeopleOrgChartNodeSchema`
-- `PeopleOrgChartOpenRole` _(type)_
-- `PeopleOrgChartOpenRoleSchema`
 - `PeopleOrgChartOwnedUnit` _(type)_
 - `PeopleOrgChartOwnedUnitSchema`
 - `PeopleOrgChartResponse` _(type)_

package/src/identity/index.ts

@@ -65,10 +65,7 @@ export type {
 export {
   ReportingRelationshipTypeSchema,
   OrgChartActorRefSchema,
-  PeopleOrgChartNodeSchema,
   PeopleOrgChartOwnedUnitSchema,
-  PeopleOrgChartEdgeSchema,
-  PeopleOrgChartOpenRoleSchema,
   PeopleOrgChartSeatStatusSchema,
   PeopleOrgChartSeatOccupantSchema,
   PeopleOrgChartSeatSchema,
@@ -78,10 +75,7 @@ export {
 export type {
   ReportingRelationshipType,
   OrgChartActorRef,
-  PeopleOrgChartNode,
   PeopleOrgChartOwnedUnit,
-  PeopleOrgChartEdge,
-  PeopleOrgChartOpenRole,
   PeopleOrgChartSeatStatus,
   PeopleOrgChartSeatOccupant,
   PeopleOrgChartSeat,

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

@@ -4,8 +4,10 @@
  * Zod response schemas for GET /api/users/org-chart — the people-org-chart
  * view rendered from the settings page Structure → Org chart drill-down.
  *
- * Nodes are users (with optional avatar + job title); edges encode
- * person-to-person reporting lines from the `user_reporting` table.
+ * The chart is position-centric (ADR-CONT-093/094): every actor is a `seat`
+ * (a `positions` row) carrying its seat-scoped attributes plus an `occupants[]`
+ * array; reporting is expressed seat→seat in `seatEdges[]`. A VACANT seat (no
+ * occupants) is the old "open role"; an OCCUPIED seat is the old "member".
  *
  * Person-level reporting is intentionally distinct from
  * `org_unit_relationships.type = 'reports_to'` (unit-to-unit graph overlay,
@@ -23,17 +25,16 @@ export type ReportingRelationshipType = z.infer<
   typeof ReportingRelationshipTypeSchema
 >;
 
-// Actor reference — either endpoint of a reporting edge (member | open-role).
-// Defined in its own zero-dependency module to avoid a module-init cycle with
-// `org/schemas` (which this file imports AuthorityMutabilitySchema from, and
-// which needs the actor ref for the set-manager request/response). Re-exported
-// here so the existing import site keeps working.
+// Actor reference (member | open-role). Retained WRITE-ONLY: the set-manager
+// request/response (`org/schemas`) still speaks this vocabulary; the read model
+// is now seat→seat (ADR-CONT-094) and no longer references it. Defined in its
+// own zero-dependency module to avoid a module-init cycle with `org/schemas`,
+// and re-exported here so the existing barrel import site keeps working.
 export { OrgChartActorRefSchema } from "./org-chart-actor";
 export type { OrgChartActorRef } from "./org-chart-actor";
-import { OrgChartActorRefSchema } from "./org-chart-actor";
 
 // ---------------------------------------------------------------------------
-// Node — a person in the chart
+// Owned unit — shared by the seat occupant (below)
 // ---------------------------------------------------------------------------
 
 // A unit this person is a *local structural owner* of — i.e. holds a grant with
@@ -58,61 +59,6 @@ export type PeopleOrgChartOwnedUnit = z.infer<
   typeof PeopleOrgChartOwnedUnitSchema
 >;
 
-export const PeopleOrgChartNodeSchema = z.object({
-  id: z.string().uuid(),
-  fullName: z.string(),
-  jobTitle: z.string().nullable(),
-  avatarUrl: z.string().nullable(),
-  primaryUnitId: z.string().uuid().nullable(),
-  // Units this person is a local structural owner of. Empty ⇒ not a unit owner.
-  // Drives the chart's owner key + tooltip; the account owner (root-unit owner)
-  // is rendered with the org owner icon (crown) instead.
-  ownedUnits: z.array(PeopleOrgChartOwnedUnitSchema),
-});
-
-export type PeopleOrgChartNode = z.infer<typeof PeopleOrgChartNodeSchema>;
-
-// ---------------------------------------------------------------------------
-// Edge — a reporting line between two people
-// ---------------------------------------------------------------------------
-
-export const PeopleOrgChartEdgeSchema = z.object({
-  // Either endpoint may be a member or an open-role seat. An edge whose
-  // `manager` is an open-role seat is "a person reports to a vacant role"
-  // (ADR-BE-312); whose `report` is an open-role seat is "an open role reports
-  // to someone" (ADR-BE-291) — both are now expressible symmetrically.
-  report: OrgChartActorRefSchema,
-  manager: OrgChartActorRefSchema,
-  relationshipType: ReportingRelationshipTypeSchema,
-});
-
-export type PeopleOrgChartEdge = z.infer<typeof PeopleOrgChartEdgeSchema>;
-
-// ---------------------------------------------------------------------------
-// Open role — a persisted placeholder seat rendered as a dashed "Open role"
-// card in its unit's sibling column. Only active roles (open + hiring) are
-// included; filled/closed roles never appear here. `unitId` seats the card in
-// the right column. `reportsTo` is the open role's OWN reporting edge
-// (ADR-BE-291): it defaults to the role's creator and is editable/clearable, so
-// a person-less seat is placed by reporting like everyone else (the chart owns
-// placement, ADR-CTRL-159). Null → the role hangs in its unit's projection-only
-// Unassigned bucket. This replaces the retired unit-head anchor (ADR-BE-284).
-// ---------------------------------------------------------------------------
-
-export const PeopleOrgChartOpenRoleSchema = z.object({
-  id: z.string().uuid(),
-  unitId: z.string().uuid(),
-  title: z.string().nullable(),
-  // The open role's OWN reporting edge (ADR-BE-291). An actor ref so an open
-  // role can report to a person OR to another open-role seat (ADR-BE-312). Null
-  // → the role hangs in its unit's projection-only Unassigned bucket.
-  reportsTo: OrgChartActorRefSchema.nullable(),
-});
-
-export type PeopleOrgChartOpenRole = z.infer<
-  typeof PeopleOrgChartOpenRoleSchema
->;
-
 // ---------------------------------------------------------------------------
 // Seat — the position-centric unification (ADR-CONT-093)
 // ---------------------------------------------------------------------------
@@ -126,12 +72,11 @@ export type PeopleOrgChartOpenRole = z.infer<
 // 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.
+// is retained write-only (set-manager request/response) and is absent 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.
+// `seats[]` + `seatEdges[]` are now the ONLY shape — the legacy
+// `nodes`/`edges`/`openRoles` half was removed in ADR-CONT-094 (breaking).
 
 export const PeopleOrgChartSeatStatusSchema = z.enum([
   "planned",
@@ -204,25 +149,16 @@ export type PeopleOrgChartSeatEdge = z.infer<
 // GET /api/users/org-chart
 // ---------------------------------------------------------------------------
 //
-// Person-less cards (empty-unit placeholders, ghosts, open roles) no longer
-// anchor under a stored unit-head "tether" (ADR-BE-284, retired by ADR-BE-292).
-// Open roles carry their own `reportsTo` edge; placeholders fall back to
-// the render-time reporting heuristic.
+// Position-centric (ADR-CONT-093/094): `seats[]` carries every chart actor
+// (occupied or vacant) and `seatEdges[]` the seat→seat reporting graph — the
+// single source of truth for placement (ADR-CTRL-159). A vacant seat with no
+// edge hangs in its unit's projection-only Unassigned bucket.
 
 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.
+  // Every chart actor (occupied or vacant), keyed by the stable positionId.
   seats: z.array(PeopleOrgChartSeatSchema),
+  // The seat→seat reporting graph (one row per `position_reporting` row).
   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),
 });
 
 export type PeopleOrgChartResponse = z.infer<

package/src/index.ts

@@ -176,10 +176,7 @@ export type {
 export {
   ReportingRelationshipTypeSchema,
   OrgChartActorRefSchema,
-  PeopleOrgChartNodeSchema,
   PeopleOrgChartOwnedUnitSchema,
-  PeopleOrgChartEdgeSchema,
-  PeopleOrgChartOpenRoleSchema,
   PeopleOrgChartSeatStatusSchema,
   PeopleOrgChartSeatOccupantSchema,
   PeopleOrgChartSeatSchema,
@@ -189,10 +186,7 @@ export {
 export type {
   ReportingRelationshipType,
   OrgChartActorRef,
-  PeopleOrgChartNode,
   PeopleOrgChartOwnedUnit,
-  PeopleOrgChartEdge,
-  PeopleOrgChartOpenRole,
   PeopleOrgChartSeatStatus,
   PeopleOrgChartSeatOccupant,
   PeopleOrgChartSeat,