@company-semantics/contracts 52.0.0 → 53.0.0

package/src/org/__tests__/set-seat-manager.test.ts

@@ -0,0 +1,177 @@
+import { describe, it, expect } from "vitest";
+import {
+  SetSeatManagerResponseSchema,
+  WorkspaceMemberDetailSchema,
+  WorkspaceMembersResponseSchema,
+  OpenRoleSchema,
+} from "../schemas.js";
+
+const REPORT_POSITION_ID = "11111111-1111-4111-8111-111111111111";
+const MANAGER_POSITION_ID = "22222222-2222-4222-8222-222222222222";
+const USER_ID = "33333333-3333-4333-8333-333333333333";
+const UNIT_ID = "44444444-4444-4444-8444-444444444444";
+const ORG_ID = "55555555-5555-4555-8555-555555555555";
+const ROLE_ID = "66666666-6666-4666-8666-666666666666";
+
+const makeResponse = (overrides: Record<string, unknown> = {}) => ({
+  success: true,
+  reportPositionId: REPORT_POSITION_ID,
+  manager: { positionId: MANAGER_POSITION_ID },
+  relationshipType: "solid",
+  message: "Reporting line updated.",
+  ...overrides,
+});
+
+describe("SetSeatManagerResponseSchema", () => {
+  it("accepts a position-keyed set and a position-keyed clear", () => {
+    expect(() =>
+      SetSeatManagerResponseSchema.parse(makeResponse()),
+    ).not.toThrow();
+    expect(() =>
+      SetSeatManagerResponseSchema.parse(
+        makeResponse({ manager: null, message: "Reporting line cleared." }),
+      ),
+    ).not.toThrow();
+  });
+
+  it("requires reportPositionId to be a uuid, not an opaque member id", () => {
+    expect(
+      SetSeatManagerResponseSchema.safeParse(
+        makeResponse({ reportPositionId: "member-1" }),
+      ).success,
+    ).toBe(false);
+  });
+
+  // The whole point of the literal: this route rides
+  // setSolidManagerByPositions, which only ever writes a solid edge. A wider
+  // relationship vocabulary here would promise a dotted-line write the route
+  // cannot perform.
+  it("rejects any relationshipType other than the solid literal", () => {
+    expect(
+      SetSeatManagerResponseSchema.safeParse(
+        makeResponse({ relationshipType: "dotted" }),
+      ).success,
+    ).toBe(false);
+  });
+
+  // The retired shape named the subordinate by user (`memberId`) and the
+  // manager by a member-or-open-role union. Neither survives: a stray memberId
+  // is stripped, and it cannot stand in for the report seat.
+  it("does not admit the retired memberId key as the report reference", () => {
+    expect(
+      SetSeatManagerResponseSchema.parse(makeResponse({ memberId: USER_ID })),
+    ).toEqual(makeResponse());
+    const { reportPositionId: _dropped, ...withoutReport } = makeResponse();
+    expect(
+      SetSeatManagerResponseSchema.safeParse({
+        ...withoutReport,
+        memberId: USER_ID,
+      }).success,
+    ).toBe(false);
+  });
+
+  it("rejects a manager named by userId rather than positionId", () => {
+    expect(
+      SetSeatManagerResponseSchema.safeParse(
+        makeResponse({ manager: { kind: "member", userId: USER_ID } }),
+      ).success,
+    ).toBe(false);
+  });
+});
+
+const makeMember = (overrides: Record<string, unknown> = {}) => ({
+  id: USER_ID,
+  name: "Ada Lovelace",
+  email: "ada@example.com",
+  jobTitle: "Principal Engineer",
+  seatPositionId: REPORT_POSITION_ID,
+  role: null,
+  roleNames: [],
+  joinedAt: "2026-04-17T00:00:00Z",
+  lastActiveAt: null,
+  primaryUnitId: UNIT_ID,
+  unitMemberships: [],
+  unitDesignations: [],
+  unitMembershipsTruncated: false,
+  inviteStatus: "active",
+  ...overrides,
+});
+
+describe("WorkspaceMember seatPositionId", () => {
+  it("carries the seat on the list shape, so a READ resolves it", () => {
+    expect(() =>
+      WorkspaceMembersResponseSchema.parse({
+        items: [makeMember()],
+        nextCursor: null,
+        hasMore: false,
+      }),
+    ).not.toThrow();
+  });
+
+  it("is inherited by the detail shape", () => {
+    expect(() =>
+      WorkspaceMemberDetailSchema.parse({
+        ...makeMember(),
+        effectiveScopes: [],
+        recentActions: [],
+      }),
+    ).not.toThrow();
+  });
+
+  // Null is a real state — a member with no materialized seat. The read reports
+  // it honestly rather than forcing the server to mint one.
+  it("accepts null for a member with no materialized seat", () => {
+    expect(() =>
+      WorkspaceMemberDetailSchema.parse({
+        ...makeMember({ seatPositionId: null }),
+        effectiveScopes: [],
+        recentActions: [],
+      }),
+    ).not.toThrow();
+  });
+
+  it("is required — a member shape without it no longer parses", () => {
+    const { seatPositionId: _dropped, ...withoutSeat } = makeMember();
+    expect(
+      WorkspaceMemberDetailSchema.safeParse({
+        ...withoutSeat,
+        effectiveScopes: [],
+        recentActions: [],
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("OpenRole reportsToPositionId", () => {
+  const makeOpenRole = (overrides: Record<string, unknown> = {}) => ({
+    id: ROLE_ID,
+    orgId: ORG_ID,
+    unitId: UNIT_ID,
+    title: "Senior Engineer",
+    targetStartDate: null,
+    status: "open",
+    filledByUserId: null,
+    reportsToPositionId: MANAGER_POSITION_ID,
+    createdAt: "2026-04-17T00:00:00Z",
+    updatedAt: "2026-04-17T00:00:00Z",
+    ...overrides,
+  });
+
+  it("names the manager by position, and null still means unmanaged", () => {
+    expect(() => OpenRoleSchema.parse(makeOpenRole())).not.toThrow();
+    expect(() =>
+      OpenRoleSchema.parse(makeOpenRole({ reportsToPositionId: null })),
+    ).not.toThrow();
+  });
+
+  // The retired reportsToUserId flattening read null whenever the manager had
+  // no account — which, post-HRIS, is nearly every manager.
+  it("no longer accepts the retired reportsToUserId flattening", () => {
+    const { reportsToPositionId: _dropped, ...withoutPosition } =
+      makeOpenRole();
+    expect(
+      OpenRoleSchema.safeParse({ ...withoutPosition, reportsToUserId: USER_ID })
+        .success,
+    ).toBe(false);
+  });
+});

package/src/org/index.ts

@@ -150,6 +150,24 @@ export type {
   OrgStructureInferenceDecisionResult,
 } from "./reasoning-review";
 
+// Org reconciliation ledger: the org's STANDING disagreements with the connected
+// HRIS — the open ones only, whether they arose during a sync (runId set) or
+// during app use (runId null). Complements the run-scoped conflicts view; does
+// not replace it. Resolution is a LOCAL decision (`sentToSource` is the literal
+// false). (ADR-BE-564)
+export {
+  OrgDivergenceSchema,
+  OrgReconciliationLedgerSchema,
+  OrgDivergenceResolutionSchema,
+  ResolveOrgDivergenceResultSchema,
+} from "./reconciliation";
+export type {
+  OrgDivergence,
+  OrgReconciliationLedger,
+  OrgDivergenceResolution,
+  ResolveOrgDivergenceResult,
+} from "./reconciliation";
+
 // Org transformation wire vocabulary: intent -> simulation -> preview. The
 // engine turns a TransformationRequest into scored mutation bundles and returns
 // a TransformationPreview the operator confirms before apply. (ADR-CONTRACTS-072)
@@ -296,7 +314,7 @@ export {
   TestSsoResultSchema,
   RemoveMemberResponseSchema,
   ChangeMemberRoleResponseSchema,
-  SetMemberManagerResponseSchema,
+  SetSeatManagerResponseSchema,
   SubmitInteractiveTaskResponseSchema,
   UserOrgsResponseSchema,
   SetActiveOrgResponseSchema,
@@ -321,7 +339,7 @@ export type {
   TestSsoResult as TestSsoResultDto,
   RemoveMemberResponse,
   ChangeMemberRoleResponse,
-  SetMemberManagerResponse,
+  SetSeatManagerResponse,
   SubmitInteractiveTaskResponse,
   UserOrgsResponse,
   SetActiveOrgResponse,

package/src/org/reconciliation.ts

@@ -0,0 +1,162 @@
+/**
+ * Org reconciliation ledger — what this workspace currently disagrees with the
+ * connected HRIS about.
+ *
+ * A {@link ConflictRecordSchema} row is the audit trail of ONE reconciliation
+ * event. The ledger is the standing view over those rows: for each contested
+ * `(entityType, entityId, field)` it keeps the workspace's CURRENT word and
+ * drops the ones the two sides have since agreed on. It answers "what is still
+ * open?", where the run-scoped conflicts view answers "what did THIS run
+ * refuse?" — the two coexist and neither replaces the other (ADR-BE-564).
+ *
+ * `runId` is NULLABLE here, and that is the whole reason this is a separate
+ * shape rather than a reuse of `ConflictRecordSchema` (whose `runId` is
+ * required). A divergence can arise OUTSIDE a sync run — at invite acceptance,
+ * or from a canonical-placement integrity breach — and such a row is deliberately
+ * not tied to a run, so it neither disappears when the run is pruned nor
+ * multiplies once per sync.
+ *
+ * Like the sibling org schemas, `entityType` and `field` are OPEN strings (no
+ * enum) so new contested kinds need no schema change, and `winningTier` REUSES
+ * the closed {@link FactSourceTierSchema} precedence axis rather than redefining
+ * it. Both competing values are serialized as strings and are nullable, because
+ * either side may hold no value.
+ *
+ * ## Resolution is LOCAL, always
+ *
+ * {@link ResolveOrgDivergenceResultSchema} is the seam a later write-back phase
+ * plugs into, and it is shaped so that phase cannot arrive by accident:
+ * `sentToSource` is the literal `false`, so any surface claiming a divergence
+ * was pushed upstream fails to typecheck against this contract. Today the HRIS
+ * client is read-only (directory + changed-since over a hardcoded GET) and no
+ * write scope is requested at connect time. Resolving a divergence records a
+ * decision in THIS workspace; nothing may state or imply the HRIS was updated.
+ *
+ * Resolving therefore does NOT close a divergence: the two sides still hold
+ * different values, so the entry stays in the ledger and carries
+ * `acknowledgedAt`. A shape that dropped it on resolution would let a click hide
+ * a live disagreement — the failure this ledger exists to prevent. What DOES
+ * remove an entry is the two sides agreeing.
+ */
+import { z } from "zod";
+
+import { FactSourceTierSchema } from "./structure-facts";
+
+// ---------------------------------------------------------------------------
+// OrgDivergence — one open disagreement between the HRIS and this workspace
+// ---------------------------------------------------------------------------
+
+export const OrgDivergenceSchema = z.object({
+  /** Identifier of the ledger row carrying the workspace's current word. */
+  id: z.string().uuid(),
+  /**
+   * The sync run that observed this disagreement, when one did. `null` marks a
+   * STANDING divergence recorded outside any run (invite acceptance, a
+   * canonical-placement integrity breach).
+   */
+  runId: z.string().uuid().nullable(),
+  /**
+   * Kind of org-graph entity the contested field belongs to (e.g. "person",
+   * "position", "occupancy"). An OPEN string so new entity kinds need no schema
+   * change.
+   */
+  entityType: z.string().min(1),
+  /** Identifier of the specific entity instance in disagreement. */
+  entityId: z.string().uuid(),
+  /** Name of the single contested field. */
+  field: z.string().min(1),
+  /**
+   * What the HRIS asserts for this field, serialized as a string. `null` when
+   * the imported side carries no value.
+   */
+  importedValue: z.string().nullable(),
+  /**
+   * What this workspace currently holds for this field, serialized as a string.
+   * `null` when the workspace holds no value.
+   */
+  currentValue: z.string().nullable(),
+  /**
+   * The value in force, serialized as a string. `null` when the resolution left
+   * the field empty.
+   */
+  winningValue: z.string().nullable(),
+  /**
+   * The precedence tier of the value in force — the same closed truth-hierarchy
+   * axis used across the org model. Reused, not redefined.
+   */
+  winningTier: FactSourceTierSchema,
+  /**
+   * The sentence a human reads: it names BOTH sides and why the winner won.
+   * Capped at 2000 chars to mirror `ConflictRecord.reason`. `null` when the row
+   * was recorded without a narrative.
+   */
+  reason: z.string().max(2000).nullable(),
+  /** ISO timestamp the workspace's current word on this field was recorded. */
+  recordedAt: z.string().datetime(),
+  /**
+   * ISO timestamp someone in this workspace ACKNOWLEDGED this entry, or `null`.
+   *
+   * A triage marker, not a resolution: the two sides still differ and nothing
+   * was sent to the HRIS, so the entry is still open and still listed. It is
+   * keyed to THIS row, so a disagreement that moves — a superseding row becomes
+   * the entry — arrives unacknowledged, which is the right default for a
+   * statement nobody has read yet.
+   */
+  acknowledgedAt: z.string().datetime().nullable(),
+  /** Who acknowledged it. `null` when nobody has, or when that user is gone. */
+  acknowledgedByUserId: z.string().uuid().nullable(),
+});
+
+export type OrgDivergence = z.infer<typeof OrgDivergenceSchema>;
+
+// ---------------------------------------------------------------------------
+// OrgReconciliationLedger — the org's open divergences, newest first
+// ---------------------------------------------------------------------------
+
+export const OrgReconciliationLedgerSchema = z.object({
+  /**
+   * The org's still-open divergences, newest first. One entry per contested
+   * `(entityType, entityId, field)`; settled disagreements are omitted.
+   */
+  divergences: z.array(OrgDivergenceSchema),
+});
+
+export type OrgReconciliationLedger = z.infer<
+  typeof OrgReconciliationLedgerSchema
+>;
+
+// ---------------------------------------------------------------------------
+// Resolution — a LOCAL decision, never an upstream write
+// ---------------------------------------------------------------------------
+
+/**
+ * What resolving a divergence means today. `acknowledged` records that someone
+ * in this workspace has seen and accepted the disagreement; it does not, and
+ * cannot, change anything in the HRIS.
+ */
+export const OrgDivergenceResolutionSchema = z.enum(["acknowledged"]);
+
+export type OrgDivergenceResolution = z.infer<
+  typeof OrgDivergenceResolutionSchema
+>;
+
+export const ResolveOrgDivergenceResultSchema = z.object({
+  /** Identifier of the divergence that was resolved. */
+  id: z.string().uuid(),
+  /** How it was resolved. Local decisions only — see the module docblock. */
+  resolution: OrgDivergenceResolutionSchema,
+  /** ISO timestamp the decision was recorded in this workspace. */
+  resolvedAt: z.string().datetime(),
+  /**
+   * Whether anything was written back to the source system. Pinned to the
+   * literal `false`: the HRIS client is read-only and no write scope is
+   * requested, so a surface that claims otherwise cannot typecheck against this
+   * contract. A future write-back phase widens this deliberately, in its own
+   * decision record — not by accident.
+   */
+  sentToSource: z.literal(false),
+});
+
+export type ResolveOrgDivergenceResult = z.infer<
+  typeof ResolveOrgDivergenceResultSchema
+>;

package/src/org/schemas.ts

@@ -13,7 +13,7 @@
 import { z } from "zod";
 import { CursorPageSchema } from "../api/primitives";
 import { OrgChartRoleSchema } from "../permissions/orgchart-roles";
-import { OrgChartActorRefSchema } from "../identity/org-chart-actor";
+import { PositionRefSchema } from "../identity/position-ref";
 
 // ---------------------------------------------------------------------------
 // Sub-schemas
@@ -90,6 +90,17 @@ const WorkspaceMemberSchema = z.object({
   avatarUrl: z.string().nullable().optional(),
   /** The occupant's Position seat title (org-scoped). Null when the seat is untitled. */
   jobTitle: z.string().nullable(),
+  /**
+   * The member's Position seat in the org graph — the id every reporting write
+   * is keyed on (ADR-CONTRACTS-131). Present here so a user-ADDRESSED surface
+   * (the members table, a person picker) can resolve a seat by READ and hand
+   * the position straight to `PUT /api/reporting/positions/{positionId}/manager`,
+   * instead of a write path minting one with `resolveSeat(create: true)`.
+   *
+   * Nullable: a member with no materialized seat is a legitimate state, and a
+   * read must report that honestly rather than force the server to create one.
+   */
+  seatPositionId: z.string().uuid().nullable(),
   /**
    * Display role — the member's highest org-chart standing, or `null` for a
    * plain member with no org-chart authority. Render via `orgChartRoleLabel`.
@@ -524,30 +535,39 @@ export type ChangeMemberRoleResponse = z.infer<
 >;
 
 // ---------------------------------------------------------------------------
-// PATCH/DELETE /api/workspace/members/:id/manager
+// PUT /api/reporting/positions/:positionId/manager
 // ---------------------------------------------------------------------------
 
 /**
- * Response for setting (PATCH) or clearing (DELETE) a member's solid-line
- * manager — the reporting edge that the org chart is built from. `manager` is
- * the actor the member now reports to: a `member` (person→person) OR an
- * `open-role` seat (person reports to a vacant role — ADR-BE-312); null after a
- * clear.
+ * Response for the one idempotent set-or-clear of a seat's solid-line manager —
+ * the reporting edge the org chart is built from. Position-keyed at BOTH ends
+ * (ADR-CONTRACTS-131): `reportPositionId` is the seat whose edge moved and
+ * `manager` is the POSITION it now reports to, null after a clear. A position
+ * names a vacant seat and an accountless occupant's seat just as well as a
+ * filled one, which the retired member-or-open-role union could not.
+ *
+ * `relationshipType` is a literal rather than the identity-domain
+ * `ReportingRelationshipTypeSchema`: importing that here would invert the
+ * existing people-org-chart → org/schemas dependency and recreate the
+ * module-init cycle. This route only ever writes solid edges, so the narrower
+ * literal is also the truthful shape. (`PositionReportingRelationshipTypeSchema`
+ * in ./position-reporting carries the open {solid, dotted} vocabulary for the
+ * read model.)
  *
  * Distinct from team membership (RBAC scopes) and `primary_unit_id` (home
  * unit): neither of those places a person in the reporting hierarchy.
  * See ADR-BE-253.
  */
-export const SetMemberManagerResponseSchema = z.object({
+export const SetSeatManagerResponseSchema = z.object({
   success: z.boolean(),
-  memberId: z.string(),
-  manager: OrgChartActorRefSchema.nullable(),
-  relationshipType: z.string(),
+  reportPositionId: z.string().uuid(),
+  manager: PositionRefSchema.nullable(),
+  relationshipType: z.literal("solid"),
   message: z.string(),
 });
 
-export type SetMemberManagerResponse = z.infer<
-  typeof SetMemberManagerResponseSchema
+export type SetSeatManagerResponse = z.infer<
+  typeof SetSeatManagerResponseSchema
 >;
 
 // ---------------------------------------------------------------------------
@@ -1134,10 +1154,16 @@ 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(),
+  // The open role's own reporting edge (ADR-BE-291): defaults to its creator's
+  // seat, editable/clearable. Drives chart placement now that the unit-head
+  // anchor is retired (ADR-BE-292). Null → unmanaged (Unassigned bucket).
+  //
+  // The manager POSITION, not a user (ADR-CONTRACTS-131). The retired
+  // user-keyed flattening was a lie in two directions: an open-role manager
+  // already surfaced as null because it had no user to collapse to, and
+  // post-HRIS every open role reporting to an imported (accountless) manager
+  // would read null too.
+  reportsToPositionId: z.string().uuid().nullable(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });

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

@@ -1,24 +0,0 @@
-/**
- * Org-chart actor reference — either endpoint of a reporting edge.
- *
- * A node in the people chart that can sit on EITHER side of a reporting edge: a
- * filled member (keyed by occupant `userId`) OR an unfilled open-role seat
- * (keyed by its own `openRoleId`). A vacant seat is a first-class reporting
- * actor — it can be a manager that real people report to (ADR-BE-312), not just
- * a report. The discriminant lets an edge point at either kind without losing
- * what the id means. Mirrors the app's `ActorIdentity` shape exactly so the app
- * consumes this type directly (one common spine across wire + UI).
- *
- * Lives in its own zero-dependency module (zod only) so both `people-org-chart`
- * (which already depends on `org/schemas` for AuthorityMutability) and
- * `org/schemas` (which needs it for the set-manager request/response) can import
- * it without forming a module-init cycle.
- */
-import { z } from "zod";
-
-export const OrgChartActorRefSchema = z.discriminatedUnion("kind", [
-  z.object({ kind: z.literal("member"), userId: z.string().uuid() }),
-  z.object({ kind: z.literal("open-role"), openRoleId: z.string().uuid() }),
-]);
-
-export type OrgChartActorRef = z.infer<typeof OrgChartActorRefSchema>;