@company-semantics/contracts 13.19.1 → 14.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "13.19.1",
+  "version": "14.0.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -119,15 +119,15 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^22.19.20",
+    "@types/node": "^25.9.3",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.7",
     "markdownlint-cli2": "^0.22.1",
     "openapi-typescript": "^7.13.0",
-    "prettier": "^3.8.3",
+    "prettier": "^3.8.4",
     "tsx": "^4.22.4",
     "typescript": "^5.8.3",
-    "vitest": "^4.1.8",
+    "vitest": "^4.1.9",
     "yaml": "^2.9.0"
   },
   "pnpm": {

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 = '4c830693f0ba' as const;
-export const SPEC_HASH_FULL = '4c830693f0ba3d236b60cb5494fbfe4d62bdb8bf4cc6fedc1df0e2d1a5d7a2d6' as const;
+export const SPEC_HASH = '16c3b86cc35a' as const;
+export const SPEC_HASH_FULL = '16c3b86cc35a3f329766b702414438de4950430991a603372f1335206c96b600' as const;

package/src/api/generated.ts

@@ -1972,24 +1972,6 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/org-units/{unitId}/head": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        /** Pin an explicit head (anchor person) for an org unit */
-        put: operations["setOrgUnitHead"];
-        post?: never;
-        /** Revert an org unit head to the system-inferred default */
-        delete: operations["revertOrgUnitHead"];
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     "/api/org-units/{unitId}/my-authority": {
         parameters: {
             query?: never;
@@ -2111,6 +2093,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/org-units/{unitId}/open-roles/{roleId}/reports-to": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /** Set or clear an open role's own reporting edge */
+        put: operations["setOrgUnitOpenRoleReportsTo"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/users/org-chart": {
         parameters: {
             query?: never;
@@ -4051,6 +4050,11 @@ export interface components {
                         state: "allowed" | "blocked";
                         requiredScope?: string;
                     };
+                    manageSharing: {
+                        /** @enum {string} */
+                        state: "allowed" | "blocked";
+                        requiredScope?: string;
+                    };
                 };
                 workItem?: {
                     transferOwnership: {
@@ -4058,6 +4062,18 @@ export interface components {
                         state: "allowed" | "blocked";
                         requiredScope?: string;
                     };
+                    manageSharing: {
+                        /** @enum {string} */
+                        state: "allowed" | "blocked";
+                        requiredScope?: string;
+                    };
+                };
+                meetingRecording?: {
+                    manageSharing: {
+                        /** @enum {string} */
+                        state: "allowed" | "blocked";
+                        requiredScope?: string;
+                    };
                 };
             };
         };
@@ -4305,8 +4321,6 @@ export interface components {
                     count: number;
                     userIds: string[];
                 } | null;
-                headUserId: string | null;
-                headOrigin: ("user" | "inferred") | null;
             }[];
         };
         OrgUnitDescendantsResponse: {
@@ -4455,8 +4469,6 @@ export interface components {
                     count: number;
                     userIds: string[];
                 } | null;
-                headUserId: string | null;
-                headOrigin: ("user" | "inferred") | null;
             }[];
             levelConfig: {
                 /** Format: uuid */
@@ -4601,12 +4613,6 @@ export interface components {
             revokedAt: string | null;
             reason: string | null;
         };
-        UnitHeadResponse: {
-            /** Format: uuid */
-            unitId: string;
-            headUserId: string | null;
-            origin: ("user" | "inferred") | null;
-        };
         OrgUnitMyAuthorityResponse: {
             /** Format: uuid */
             unitId: string;
@@ -4676,6 +4682,7 @@ export interface components {
                 /** @enum {string} */
                 status: "open" | "hiring" | "filled" | "closed";
                 filledByUserId: string | null;
+                reportsToUserId: string | null;
                 createdAt: string;
                 updatedAt: string;
             }[];
@@ -4693,6 +4700,7 @@ export interface components {
                 /** @enum {string} */
                 status: "open" | "hiring" | "filled" | "closed";
                 filledByUserId: string | null;
+                reportsToUserId: string | null;
                 createdAt: string;
                 updatedAt: string;
             };
@@ -4720,14 +4728,7 @@ export interface components {
                 /** Format: uuid */
                 unitId: string;
                 title: string | null;
-            }[];
-            unitHeads: {
-                /** Format: uuid */
-                unitId: string;
-                /** Format: uuid */
-                headUserId: string;
-                /** @enum {string} */
-                origin: "user" | "inferred";
+                reportsToUserId: string | null;
             }[];
         };
         /** @description Polling snapshot of a generic ingestion operation. */
@@ -8480,57 +8481,6 @@ export interface operations {
             };
         };
     };
-    setOrgUnitHead: {
-        parameters: {
-            query?: never;
-            header?: never;
-            path: {
-                unitId: string;
-            };
-            cookie?: never;
-        };
-        requestBody: {
-            content: {
-                "application/json": {
-                    /** Format: uuid */
-                    userId: string;
-                };
-            };
-        };
-        responses: {
-            /** @description The pinned unit head */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["UnitHeadResponse"];
-                };
-            };
-        };
-    };
-    revertOrgUnitHead: {
-        parameters: {
-            query?: never;
-            header?: never;
-            path: {
-                unitId: string;
-            };
-            cookie?: never;
-        };
-        requestBody?: never;
-        responses: {
-            /** @description The re-inferred unit head (or null when none resolves) */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["UnitHeadResponse"];
-                };
-            };
-        };
-    };
     getMyOrgUnitAuthority: {
         parameters: {
             query?: never;
@@ -8777,6 +8727,35 @@ export interface operations {
             };
         };
     };
+    setOrgUnitOpenRoleReportsTo: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+                roleId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    userId: string | null;
+                };
+            };
+        };
+        responses: {
+            /** @description Open role with updated reporting edge */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OpenRoleResponse"];
+                };
+            };
+        };
+    };
     getPeopleOrgChart: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -89,6 +89,7 @@ export const openApiRoutes = {
   '/api/org-units/{unitId}/open-roles': ['GET', 'POST'],
   '/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}/owners': ['GET'],
   '/api/org-units/{unitId}/permissions': ['GET'],
   '/api/org-units/{unitId}/relationships': ['GET', 'POST'],

package/src/identity/index.ts

@@ -67,8 +67,6 @@ export {
   PeopleOrgChartNodeSchema,
   PeopleOrgChartEdgeSchema,
   PeopleOrgChartOpenRoleSchema,
-  UnitHeadOriginSchema,
-  PeopleOrgChartUnitHeadSchema,
   PeopleOrgChartResponseSchema,
 } from "./people-org-chart";
 export type {
@@ -76,7 +74,5 @@ export type {
   PeopleOrgChartNode,
   PeopleOrgChartEdge,
   PeopleOrgChartOpenRole,
-  UnitHeadOrigin,
-  PeopleOrgChartUnitHead,
   PeopleOrgChartResponse,
 } from "./people-org-chart";

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

@@ -52,52 +52,37 @@ 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 and resolves its attach-person, mirroring how empty-unit
-// placeholders and pending-invite ghosts are positioned.
+// the right column. `reportsToUserId` 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(),
+  reportsToUserId: z.string().uuid().nullable(),
 });
 
 export type PeopleOrgChartOpenRole = z.infer<
   typeof PeopleOrgChartOpenRoleSchema
 >;
 
-// ---------------------------------------------------------------------------
-// Unit head — the person a unit (and its person-less children: empty-unit
-// placeholders, pending-invite ghosts, open-role seats) anchors under in the
-// people chart. A presentation/anchor "tether" (ADR-BE-284), NOT authority.
-// `origin` distinguishes an explicit user choice from a system-inferred default
-// so the UI can render "Pinned" vs "Auto" and offer revert-to-auto. The client
-// prefers the head of a unit's PARENT when anchoring its person-less children,
-// falling back to the render-time heuristic only when no head row exists.
-// ---------------------------------------------------------------------------
-
-export const UnitHeadOriginSchema = z.enum(["user", "inferred"]);
-export type UnitHeadOrigin = z.infer<typeof UnitHeadOriginSchema>;
-
-export const PeopleOrgChartUnitHeadSchema = z.object({
-  unitId: z.string().uuid(),
-  headUserId: z.string().uuid(),
-  origin: UnitHeadOriginSchema,
-});
-
-export type PeopleOrgChartUnitHead = z.infer<
-  typeof PeopleOrgChartUnitHeadSchema
->;
-
 // ---------------------------------------------------------------------------
 // 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 `reportsToUserId` edge; placeholders fall back to
+// the render-time reporting heuristic.
 
 export const PeopleOrgChartResponseSchema = z.object({
   nodes: z.array(PeopleOrgChartNodeSchema),
   edges: z.array(PeopleOrgChartEdgeSchema),
   openRoles: z.array(PeopleOrgChartOpenRoleSchema),
-  unitHeads: z.array(PeopleOrgChartUnitHeadSchema),
 });
 
 export type PeopleOrgChartResponse = z.infer<

package/src/index.ts

@@ -173,8 +173,6 @@ export {
   PeopleOrgChartNodeSchema,
   PeopleOrgChartEdgeSchema,
   PeopleOrgChartOpenRoleSchema,
-  UnitHeadOriginSchema,
-  PeopleOrgChartUnitHeadSchema,
   PeopleOrgChartResponseSchema,
 } from "./identity/index";
 export type {
@@ -182,8 +180,6 @@ export type {
   PeopleOrgChartNode,
   PeopleOrgChartEdge,
   PeopleOrgChartOpenRole,
-  UnitHeadOrigin,
-  PeopleOrgChartUnitHead,
   PeopleOrgChartResponse,
 } from "./identity/index";
 
@@ -358,6 +354,19 @@ export {
 // View authorization types (Phase 5 - ADR-APP-013)
 export type { AuthorizableView } from "./org/index";
 
+// Org structure facts: provenance + home/membership separation (ADR-CONTRACTS-066)
+export {
+  FactSourceTierSchema,
+  FACT_SOURCE_TIER_PRECEDENCE,
+  FactProvenanceSchema,
+  HomeAssignmentSchema,
+} from "./org/index";
+export type {
+  FactSourceTier,
+  FactProvenance,
+  HomeAssignment,
+} from "./org/index";
+
 // Authority & Delegation vocabulary
 export {
   AuthoritySourceSchema,

package/src/org/__tests__/org-units.test.ts

@@ -98,8 +98,6 @@ describe("OrgUnitTreeNodeSchema", () => {
       memberCount: 5,
       openRoleCount: 1,
       missingAtNextLevel: null,
-      headUserId: null,
-      headOrigin: null,
     };
     expect(() => OrgUnitTreeNodeSchema.parse(base)).not.toThrow();
     expect(() => OrgUnitTreeNodeSchema.parse({ ...base, depth: 0 })).toThrow();
@@ -114,8 +112,6 @@ describe("OrgUnitTreeNodeSchema", () => {
       memberCount: 5,
       openRoleCount: 0,
       missingAtNextLevel: null,
-      headUserId: null,
-      headOrigin: null,
     };
     expect(() => OrgUnitTreeNodeSchema.parse(base)).not.toThrow();
     expect(() =>
@@ -133,6 +129,7 @@ describe("OpenRoleSchema", () => {
     targetStartDate: "2026-09-01",
     status: "open",
     filledByUserId: null,
+    reportsToUserId: null,
     createdAt: "2026-04-17T00:00:00Z",
     updatedAt: "2026-04-17T00:00:00Z",
     ...overrides,

package/src/org/index.ts

@@ -87,6 +87,19 @@ export type {
 export type { AuthorizableView } from "./view-scopes";
 export { VIEW_SCOPE_MAP, getViewScope } from "./view-scopes";
 
+// Org structure facts: provenance + home/membership separation (ADR-CONTRACTS-066)
+export {
+  FactSourceTierSchema,
+  FACT_SOURCE_TIER_PRECEDENCE,
+  FactProvenanceSchema,
+  HomeAssignmentSchema,
+} from "./structure-facts";
+export type {
+  FactSourceTier,
+  FactProvenance,
+  HomeAssignment,
+} from "./structure-facts";
+
 // Canonical OrgUnit tree ordering (PRD-00506)
 export type { TreeOrderableNode } from "./tree-ordering";
 export { orderTreeNodes } from "./tree-ordering";

package/src/org/schemas.ts

@@ -949,16 +949,6 @@ export const OrgUnitTreeNodeSchema = OrgUnitSchema.extend({
    */
   openRoleCount: z.number().int().min(0),
   missingAtNextLevel: MissingAtNextLevelSchema.nullable(),
-  /**
-   * The unit head (ADR-BE-284): the person this unit (and its person-less
-   * children) anchors under in the people chart — a presentation "tether", NOT
-   * authority. `headUserId` is null when no head is resolved (e.g. an empty
-   * unit with no members). `headOrigin` is `'user'` for an explicit choice,
-   * `'inferred'` for a system default (so the management UI can show Pinned vs
-   * Auto and offer revert-to-auto), or null when there is no head.
-   */
-  headUserId: z.string().uuid().nullable(),
-  headOrigin: z.enum(["user", "inferred"]).nullable(),
 });
 
 export const OrgUnitMembershipSchema = z.object({
@@ -989,6 +979,10 @@ export const OpenRoleSchema = z.object({
   targetStartDate: z.string().nullable(),
   status: OpenRoleStatusSchema,
   filledByUserId: z.string().uuid().nullable(),
+  // The open role's own reporting edge (ADR-BE-291): defaults to its creator,
+  // editable/clearable. Drives chart placement now that the unit-head anchor is
+  // retired (ADR-BE-292). Null → unmanaged (Unassigned bucket).
+  reportsToUserId: z.string().uuid().nullable(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
@@ -1438,16 +1432,25 @@ export const CapabilitiesResponseSchema = z.object({
       orgUnit: z.object({
         manage: ActionCapabilitySchema,
       }),
-      // Entity ownership-transfer overrides (backend ADR-BE-259). Optional so
-      // older backends that don't derive them still validate.
+      // Entity ownership-transfer overrides (backend ADR-BE-259) +
+      // sharing-management custody (backend ADR-BE-288). Optional so older
+      // backends that don't derive them still validate. manageSharing gates the
+      // admin Share affordance on content the admin may not be able to view.
       companyMd: z
         .object({
           transferOwnership: ActionCapabilitySchema,
+          manageSharing: ActionCapabilitySchema,
         })
         .optional(),
       workItem: z
         .object({
           transferOwnership: ActionCapabilitySchema,
+          manageSharing: ActionCapabilitySchema,
+        })
+        .optional(),
+      meetingRecording: z
+        .object({
+          manageSharing: ActionCapabilitySchema,
         })
         .optional(),
     })

package/src/org/structure-facts.ts

@@ -0,0 +1,105 @@
+/**
+ * Org structure facts: provenance envelope + the home/membership separation.
+ *
+ * The org model is several INDEPENDENT graphs — the org-unit tree, the reporting
+ * graph, the home assignment, and the membership graph (and, later, positions).
+ * This module is the shared vocabulary for two cross-cutting ideas in that model
+ * (see ADR-CONTRACTS-066 and control ADR-CTRL-159):
+ *
+ *  1. Every structural fact carries provenance ({@link FactProvenanceSchema}).
+ *  2. "Home" is a dedicated ≤1-per-person relation ({@link HomeAssignmentSchema}),
+ *     kept SEPARATE from `org_unit_memberships` — not a `kind` flag on memberships.
+ *
+ * Principles encoded here (do not drift from these):
+ *  - Membership / home is an INPUT to authority derivation, NOT authority itself.
+ *    `home member of unit` does not mean `owns unit`.
+ *  - Facts are immutable; corrections SUPERSEDE prior facts (`supersedesFactId`)
+ *    rather than mutating in place. This leaves room for event-sourcing later
+ *    without forcing it now.
+ *  - A truth hierarchy decides which fact wins: user > sync > import > inferred.
+ *  - `source` is an OPEN string so new origins (scim, workday, csv, org_chart,
+ *    google, slack, …) need no schema change; `tier` is the closed precedence axis.
+ */
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Provenance
+// ---------------------------------------------------------------------------
+
+/**
+ * The precedence axis for a fact. Closed set, ordered highest-precedence first
+ * (see {@link FACT_SOURCE_TIER_PRECEDENCE}). The specific origin lives in the
+ * open `source` string; this enum is what comparison / "who wins" reasons over.
+ */
+export const FactSourceTierSchema = z.enum([
+  "user",
+  "sync",
+  "import",
+  "inferred",
+]);
+export type FactSourceTier = z.infer<typeof FactSourceTierSchema>;
+
+/**
+ * Truth hierarchy, highest precedence first. A writer at a lower tier must never
+ * supersede a fact recorded at a higher tier (e.g. an org-chart import must not
+ * overwrite a `user`-entered reporting edge).
+ */
+export const FACT_SOURCE_TIER_PRECEDENCE = [
+  "user",
+  "sync",
+  "import",
+  "inferred",
+] as const satisfies ReadonlyArray<FactSourceTier>;
+
+/**
+ * Provenance envelope attached to a structural fact (reporting edge, org unit,
+ * membership, home assignment). The live value of any fact is the
+ * highest-precedence, non-superseded record.
+ */
+export const FactProvenanceSchema = z.object({
+  /** Precedence axis used by the truth hierarchy. */
+  tier: FactSourceTierSchema,
+  /**
+   * Specific origin — OPEN set, e.g. `manual` | `org_chart` | `scim` | `hris` |
+   * `csv` | `google` | `slack`. New origins slot in without a schema change.
+   */
+  source: z.string().min(1),
+  /** Extractor/matcher certainty in [0,1]; `null` for human-entered facts. */
+  confidence: z.number().min(0).max(1).nullable(),
+  /**
+   * True once a human has corrected/confirmed the fact. A locked fact is sticky:
+   * lower-tier writers (imports, inference) must not supersede it.
+   */
+  locked: z.boolean(),
+  /**
+   * The fact this record supersedes (immutable correction history); `null`/absent
+   * for an original. Enables append+supersede without destructive updates.
+   */
+  supersedesFactId: z.string().uuid().nullable().optional(),
+});
+export type FactProvenance = z.infer<typeof FactProvenanceSchema>;
+
+// ---------------------------------------------------------------------------
+// HomeAssignment (separate from membership)
+// ---------------------------------------------------------------------------
+
+/**
+ * A person's single structural home unit — at most one per person per org.
+ *
+ * SEPARATE relation from `org_unit_memberships` (NOT a `kind`/role flag on a
+ * shared table): the cardinalities differ on purpose — exactly one home, many
+ * memberships — which is the tell that they are different concepts. A shared
+ * `Membership(kind='home'|'member')` would inevitably grow
+ * `acting-home`/`temporary-home`/`future-home` flags.
+ *
+ * Home is an INPUT to authority derivation, sets `department`/`org` scope, and
+ * filters chart inclusion. It is NOT authority by itself (see Principles above).
+ * Supersedes the legacy `users.primary_unit_id` pointer (ADR-BE-120).
+ */
+export const HomeAssignmentSchema = z.object({
+  personId: z.string().uuid(),
+  orgUnitId: z.string().uuid(),
+  /** Provenance of this home assignment. Optional on lightweight projections. */
+  provenance: FactProvenanceSchema.optional(),
+});
+export type HomeAssignment = z.infer<typeof HomeAssignmentSchema>;