@company-semantics/contracts 18.2.0 → 19.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "18.2.0",
+  "version": "19.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 = '4944d64336bd' as const;
-export const SPEC_HASH_FULL = '4944d64336bd97c454ceef9917209bd1da7bab66a771e02c91bafec5ab31d47e' as const;
+export const SPEC_HASH = '814c99a18543' as const;
+export const SPEC_HASH_FULL = '814c99a18543f448daaed5312db276f7704a9b63710c512b1a298be5fc652105' as const;

package/src/api/generated.ts

@@ -4745,6 +4745,11 @@ export interface components {
                 jobTitle: string | null;
                 avatarUrl: string | null;
                 primaryUnitId: string | null;
+                ownedUnits: {
+                    /** Format: uuid */
+                    id: string;
+                    name: string;
+                }[];
             }[];
             edges: {
                 /** Format: uuid */

package/src/identity/README.md

@@ -44,6 +44,8 @@ TypeScript types and functions for user identity and display name resolution.
 - `BannerDismissedListResponseSchema`
 - `DeletionBlocker` _(type)_ — Conditions that block account deletion.
 - `ISODateString` _(type)_ — ISO 8601 date-time string.
+- `IdentityLink` _(type)_
+- `IdentityLinkSchema`
 - `MeResponse` _(type)_
 - `MeResponseSchema` — Full identity context returned by GET /api/me.
 - `NameSource` _(type)_ — Source of the user's name data.
@@ -53,8 +55,12 @@ TypeScript types and functions for user identity and display name resolution.
 - `PeopleOrgChartNodeSchema`
 - `PeopleOrgChartOpenRole` _(type)_
 - `PeopleOrgChartOpenRoleSchema`
+- `PeopleOrgChartOwnedUnit` _(type)_
+- `PeopleOrgChartOwnedUnitSchema`
 - `PeopleOrgChartResponse` _(type)_
 - `PeopleOrgChartResponseSchema`
+- `Person` _(type)_
+- `PersonSchema`
 - `ProfileResponse` _(type)_
 - `ProfileResponseSchema`
 - `ReportingRelationshipType` _(type)_

package/src/identity/__tests__/identity-link.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { IdentityLinkSchema } from "../identity-link.js";
+
+const validLink = {
+  id: "11111111-1111-4111-8111-111111111111",
+  orgId: "22222222-2222-4222-8222-222222222222",
+  provider: "bamboohr",
+  externalId: "emp-4081",
+  personId: "33333333-3333-4333-8333-333333333333",
+  createdAt: "2026-06-21T10:00:00.000Z",
+  updatedAt: "2026-06-21T10:00:00.000Z",
+};
+
+describe("IdentityLinkSchema", () => {
+  it("accepts a valid identity link record", () => {
+    expect(IdentityLinkSchema.parse(validLink)).toEqual(validLink);
+  });
+
+  it("accepts arbitrary provider strings (open vocabulary)", () => {
+    for (const provider of ["bamboohr", "workday", "scim", "custom-hris"]) {
+      expect(
+        IdentityLinkSchema.safeParse({ ...validLink, provider }).success,
+      ).toBe(true);
+    }
+  });
+
+  it("rejects an empty provider", () => {
+    expect(
+      IdentityLinkSchema.safeParse({ ...validLink, provider: "" }).success,
+    ).toBe(false);
+  });
+
+  it("rejects an empty externalId", () => {
+    expect(
+      IdentityLinkSchema.safeParse({ ...validLink, externalId: "" }).success,
+    ).toBe(false);
+  });
+
+  it("rejects a non-uuid personId", () => {
+    expect(
+      IdentityLinkSchema.safeParse({ ...validLink, personId: "not-a-uuid" })
+        .success,
+    ).toBe(false);
+  });
+
+  it("rejects a non-datetime createdAt", () => {
+    expect(
+      IdentityLinkSchema.safeParse({ ...validLink, createdAt: "yesterday" })
+        .success,
+    ).toBe(false);
+  });
+});

package/src/identity/__tests__/person.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+
+import { PersonSchema } from "../person.js";
+
+describe("PersonSchema", () => {
+  const base = {
+    id: "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
+    orgId: "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b",
+    displayName: "Ada Lovelace",
+  };
+
+  it("parses a minimal accountless person", () => {
+    const person = PersonSchema.parse(base);
+    expect(person.displayName).toBe("Ada Lovelace");
+    expect(person.userId).toBeUndefined();
+  });
+
+  it("accepts a null userId (accountless) and a uuid userId (linked)", () => {
+    expect(PersonSchema.parse({ ...base, userId: null }).userId).toBeNull();
+    const linked = PersonSchema.parse({
+      ...base,
+      userId: "9c5b94b1-35ad-49bb-b118-8e8fc24abf80",
+    });
+    expect(linked.userId).toBe("9c5b94b1-35ad-49bb-b118-8e8fc24abf80");
+  });
+
+  it("accepts a null primaryEmail and validates email format", () => {
+    expect(
+      PersonSchema.parse({ ...base, primaryEmail: null }).primaryEmail,
+    ).toBeNull();
+    expect(() =>
+      PersonSchema.parse({ ...base, primaryEmail: "not-an-email" }),
+    ).toThrow();
+  });
+
+  it("rejects an empty displayName and non-uuid id", () => {
+    expect(() => PersonSchema.parse({ ...base, displayName: "" })).toThrow();
+    expect(() => PersonSchema.parse({ ...base, id: "nope" })).toThrow();
+  });
+});

package/src/identity/identity-link.ts

@@ -0,0 +1,38 @@
+/**
+ * Identity Link Vocabulary
+ *
+ * An IdentityLink is a durable map from an external system's identifier to a
+ * Person in the org graph. It generalizes the legacy
+ * `users.external_source_id` / `users.external_source_system` pair into a
+ * first-class, per-source record: a BambooHR link is simply an IdentityLink
+ * with `provider: 'bamboohr'`.
+ *
+ * `provider` is an OPEN string (e.g. 'bamboohr', 'workday', 'scim') rather than
+ * an enum, so onboarding a new identity source needs no schema change.
+ *
+ * Logical uniqueness is the tuple (orgId, provider, externalId): a given
+ * external id from a given provider, within a given org, maps to exactly one
+ * Person. The (orgId, provider, externalId) tuple is the natural key.
+ *
+ * @see ADR-CONT-032 for identity vocabulary design rationale
+ */
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// IdentityLink — external system id → Person
+// ---------------------------------------------------------------------------
+
+export const IdentityLinkSchema = z.object({
+  id: z.string().uuid(),
+  orgId: z.string().uuid(),
+  // Open string (NOT an enum) so new sources need no schema change.
+  provider: z.string().min(1),
+  // The opaque identifier the external system uses for this person.
+  externalId: z.string().min(1),
+  // The Person this external identity resolves to (Person.id).
+  personId: z.string().uuid(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+});
+
+export type IdentityLink = z.infer<typeof IdentityLinkSchema>;

package/src/identity/index.ts

@@ -65,6 +65,7 @@ export type {
 export {
   ReportingRelationshipTypeSchema,
   PeopleOrgChartNodeSchema,
+  PeopleOrgChartOwnedUnitSchema,
   PeopleOrgChartEdgeSchema,
   PeopleOrgChartOpenRoleSchema,
   PeopleOrgChartResponseSchema,
@@ -72,7 +73,16 @@ export {
 export type {
   ReportingRelationshipType,
   PeopleOrgChartNode,
+  PeopleOrgChartOwnedUnit,
   PeopleOrgChartEdge,
   PeopleOrgChartOpenRole,
   PeopleOrgChartResponse,
 } from "./people-org-chart";
+
+// Person — the org-graph node for a human (0..1 User link), per ADR-CTRL-182
+export { PersonSchema } from "./person";
+export type { Person } from "./person";
+
+// Identity Link — external system id → Person (provider is an open string)
+export { IdentityLinkSchema } from "./identity-link";
+export type { IdentityLink } from "./identity-link";

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

@@ -26,12 +26,30 @@ export type ReportingRelationshipType = z.infer<
 // Node — a person in the chart
 // ---------------------------------------------------------------------------
 
+// A unit this person is a *local structural owner* of — i.e. holds a grant with
+// `authority_source = 'structural'` directly on that unit (ADR-BE-168). Carries
+// the unit name so the chart can render an owner tooltip ("Unit owner of …")
+// without a second lookup. The org root unit appears here for the account
+// owner(s) (the CEO), whom the chart marks with the owner icon instead.
+export const PeopleOrgChartOwnedUnitSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+});
+
+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>;

package/src/identity/person.ts

@@ -0,0 +1,28 @@
+/**
+ * Person Identity Vocabulary
+ *
+ * Person: the human in the org — the org-graph node. Distinct from `User` (an
+ * authenticated account). A Person has 0..1 linked User (`userId`); accountless
+ * People are valid from day one. Identity vocabulary, NOT a structure fact, so it
+ * carries no FactProvenance envelope. See control ADR-CTRL-182.
+ */
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Person — the org-graph node for a human, with an optional 0..1 User link
+// ---------------------------------------------------------------------------
+
+export const PersonSchema = z.object({
+  /** Unique identifier for the person within the org graph. */
+  id: z.string().uuid(),
+  /** Owning organization (tenant) this person belongs to. */
+  orgId: z.string().uuid(),
+  /** Human-facing name of the person in the org. */
+  displayName: z.string().min(1),
+  /** Primary email if known; null for people imported without one. */
+  primaryEmail: z.string().email().nullable().optional(),
+  /** The authenticated account this person is, if any (0..1). Null when accountless. */
+  userId: z.string().uuid().nullable().optional(),
+});
+
+export type Person = z.infer<typeof PersonSchema>;

package/src/index.ts

@@ -171,6 +171,7 @@ export type {
 export {
   ReportingRelationshipTypeSchema,
   PeopleOrgChartNodeSchema,
+  PeopleOrgChartOwnedUnitSchema,
   PeopleOrgChartEdgeSchema,
   PeopleOrgChartOpenRoleSchema,
   PeopleOrgChartResponseSchema,
@@ -178,11 +179,20 @@ export {
 export type {
   ReportingRelationshipType,
   PeopleOrgChartNode,
+  PeopleOrgChartOwnedUnit,
   PeopleOrgChartEdge,
   PeopleOrgChartOpenRole,
   PeopleOrgChartResponse,
 } from "./identity/index";
 
+// Person — the org-graph node for a human (0..1 User link), per ADR-CTRL-182
+export { PersonSchema } from "./identity/index";
+export type { Person } from "./identity/index";
+
+// Identity Link — external system id → Person (provider is an open string)
+export { IdentityLinkSchema } from "./identity/index";
+export type { IdentityLink } from "./identity/index";
+
 // Auth domain types
 export type { AuthStartMode, AuthStartResponse } from "./auth/index";
 export { OTPErrorCode } from "./auth/index";
@@ -367,6 +377,32 @@ export type {
   HomeAssignment,
 } from "./org/index";
 
+// Occupancy: the holds_position relation (M:N, co-occupancy first-class).
+// Vacancy = a position with no active occupancy. (ADR-CONT-083 / ADR-CTRL-182)
+export { OccupancyStatusSchema, OccupancySchema } from "./org/index";
+export type { OccupancyStatus, Occupancy } from "./org/index";
+
+// Position: the org seat (planned/open/filled/closed) — a seat, not a person
+// or a title. Carries a FactProvenance envelope. (ADR-CONT-083 / ADR-CTRL-182)
+export { PositionStatusSchema, PositionSchema } from "./org/index";
+export type { PositionStatus, Position } from "./org/index";
+
+// Position reporting: the canonical seat -> manager-seat reporting edge. The
+// person hierarchy derives from this composed with occupancy. (ADR-CONT-083 / ADR-CTRL-182)
+export {
+  PositionReportingRelationshipTypeSchema,
+  PositionReportingSchema,
+} from "./org/index";
+export type {
+  PositionReportingRelationshipType,
+  PositionReporting,
+} from "./org/index";
+
+// Source authority: per-field ownership — who may WRITE a given entity field.
+// Orthogonal to provenance (who reported). (ADR-CONT-083 / ADR-CTRL-182)
+export { SourceAuthoritySchema } from "./org/index";
+export type { SourceAuthority } from "./org/index";
+
 // Authority & Delegation vocabulary
 export {
   AuthoritySourceSchema,

package/src/org/README.md

@@ -105,6 +105,10 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `MissingAtNextLevel` _(type)_
 - `MissingAtNextLevelSchema` — Active users home directly at this unit who have no level-(depth+1) home assignment within its subtree.
 - `ORG_UNITS_ROUTES` — Canonical route path constants for the `/api/org-units` surface.
+- `Occupancy` _(type)_
+- `OccupancySchema`
+- `OccupancyStatus` _(type)_
+- `OccupancyStatusSchema` — Lifecycle of a single occupancy of a position.
 - `OidcValidationResult` _(type)_ — Result of validating an OIDC discovery URL.
 - `OidcValidationResultDto` _(type)_ — Result of validating an OIDC discovery URL.
 - `OidcValidationResultSchema`
@@ -204,6 +208,14 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `PermissionAuditEntry` _(type)_ — Single entry in the permission change audit log.
 - `Phase3AuditAction` _(type)_ — Audit actions for Phase 3 workspace expansion features.
 - `Phase4AuditAction` _(type)_ — Audit actions for Phase 4 enterprise identity features.
+- `Position` _(type)_
+- `PositionReporting` _(type)_
+- `PositionReportingRelationshipType` _(type)_
+- `PositionReportingRelationshipTypeSchema` — The kind of reporting line.
+- `PositionReportingSchema`
+- `PositionSchema`
+- `PositionStatus` _(type)_
+- `PositionStatusSchema` — Lifecycle of a seat's EXISTENCE — distinct from a hiring pipeline.
 - `ProviderStatus` _(type)_ — Provider-level configuration lifecycle.
 - `ProviderSuggestion` _(type)_ — MX-based provider suggestion for SSO setup.
 - `RemoveMemberRequest` _(type)_ — Request payload for removing a member from the workspace.
@@ -222,6 +234,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `SetMemberManagerResponseSchema` — Response for setting (PATCH) or clearing (DELETE) a member's solid-line manager — the person-to-person…
 - `SharePolicy` _(type)_ — Document sharing policy. - restricted: Only explicit ACL + owning unit + org admins - orgread: All org…
 - `ShareState` _(type)_ — Complete sharing state for a document.
+- `SourceAuthority` _(type)_
+- `SourceAuthoritySchema`
 - `SsoCredentialStatus` _(type)_ — Boolean credential presence indicators (never expose actual values).
 - `SsoDiscoveryConfig` _(type)_ — OIDC discovery configuration for the SSO provider.
 - `SsoEnforcementStatus` _(type)_ — SSO enforcement status for the workspace.

package/src/org/__tests__/occupancy.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from "vitest";
+
+import { OccupancySchema, OccupancyStatusSchema } from "../occupancy.js";
+
+describe("OccupancySchema", () => {
+  const base = {
+    id: "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
+    orgId: "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b",
+    positionId: "9c5b94b1-35ad-49bb-b118-8e8fc24abf80",
+    personId: "7d793037-a076-4f50-9c0e-0e4c0b9d5b1f",
+    status: "active",
+    provenance: {
+      tier: "user",
+      source: "manual",
+      confidence: null,
+      locked: true,
+    },
+  };
+
+  it("parses a minimal active occupancy without dates", () => {
+    const occ = OccupancySchema.parse(base);
+    expect(occ.status).toBe("active");
+    expect(occ.startsAt).toBeUndefined();
+    expect(occ.endsAt).toBeUndefined();
+  });
+
+  it("accepts null and ISO datetime for startsAt/endsAt", () => {
+    expect(
+      OccupancySchema.parse({ ...base, startsAt: null, endsAt: null }).endsAt,
+    ).toBeNull();
+    const dated = OccupancySchema.parse({
+      ...base,
+      startsAt: "2026-01-01T00:00:00.000Z",
+      endsAt: "2026-06-01T00:00:00.000Z",
+    });
+    expect(dated.startsAt).toBe("2026-01-01T00:00:00.000Z");
+  });
+
+  it("rejects a non-ISO datetime", () => {
+    expect(() =>
+      OccupancySchema.parse({ ...base, startsAt: "2026-01-01" }),
+    ).toThrow();
+  });
+
+  it("rejects non-uuid ids", () => {
+    expect(() => OccupancySchema.parse({ ...base, id: "nope" })).toThrow();
+    expect(() =>
+      OccupancySchema.parse({ ...base, positionId: "nope" }),
+    ).toThrow();
+    expect(() =>
+      OccupancySchema.parse({ ...base, personId: "nope" }),
+    ).toThrow();
+  });
+
+  it("requires a provenance envelope (structure fact)", () => {
+    const { provenance: _omitted, ...withoutProvenance } = base;
+    expect(() => OccupancySchema.parse(withoutProvenance)).toThrow();
+  });
+
+  it("rejects an unknown status", () => {
+    expect(() =>
+      OccupancySchema.parse({ ...base, status: "vacant" }),
+    ).toThrow();
+  });
+
+  it("OccupancyStatusSchema is the closed pending/active/ended set", () => {
+    expect(OccupancyStatusSchema.options).toEqual([
+      "pending",
+      "active",
+      "ended",
+    ]);
+    expect(() => OccupancyStatusSchema.parse("filled")).toThrow();
+  });
+});

package/src/org/__tests__/position-reporting.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from "vitest";
+import {
+  PositionReportingSchema,
+  PositionReportingRelationshipTypeSchema,
+} from "../position-reporting.js";
+
+const validEdge = {
+  id: "11111111-1111-4111-8111-111111111111",
+  orgId: "22222222-2222-4222-8222-222222222222",
+  reportPositionId: "33333333-3333-4333-8333-333333333333",
+  managerPositionId: "44444444-4444-4444-8444-444444444444",
+  relationshipType: "solid" as const,
+  provenance: {
+    tier: "user" as const,
+    source: "manual",
+    confidence: null,
+    locked: true,
+  },
+};
+
+describe("PositionReportingSchema", () => {
+  it("accepts a valid position reporting edge", () => {
+    expect(PositionReportingSchema.parse(validEdge)).toEqual(validEdge);
+  });
+
+  it("accepts an edge without provenance (lightweight projection)", () => {
+    const { provenance: _omit, ...lightweight } = validEdge;
+    expect(PositionReportingSchema.safeParse(lightweight).success).toBe(true);
+  });
+
+  it("accepts both relationship types", () => {
+    for (const relationshipType of ["solid", "dotted"]) {
+      expect(
+        PositionReportingSchema.safeParse({ ...validEdge, relationshipType })
+          .success,
+      ).toBe(true);
+    }
+  });
+
+  it("rejects an unknown relationship type", () => {
+    expect(
+      PositionReportingSchema.safeParse({
+        ...validEdge,
+        relationshipType: "matrix",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("rejects a non-uuid reportPositionId", () => {
+    expect(
+      PositionReportingSchema.safeParse({
+        ...validEdge,
+        reportPositionId: "not-a-uuid",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("rejects a non-uuid managerPositionId", () => {
+    expect(
+      PositionReportingSchema.safeParse({
+        ...validEdge,
+        managerPositionId: "not-a-uuid",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("rejects a missing orgId", () => {
+    const { orgId: _omit, ...noOrg } = validEdge;
+    expect(PositionReportingSchema.safeParse(noOrg).success).toBe(false);
+  });
+});
+
+describe("PositionReportingRelationshipTypeSchema", () => {
+  it("accepts solid and dotted", () => {
+    expect(PositionReportingRelationshipTypeSchema.parse("solid")).toBe(
+      "solid",
+    );
+    expect(PositionReportingRelationshipTypeSchema.parse("dotted")).toBe(
+      "dotted",
+    );
+  });
+
+  it("rejects any other value", () => {
+    expect(
+      PositionReportingRelationshipTypeSchema.safeParse("solid-line").success,
+    ).toBe(false);
+  });
+});

package/src/org/__tests__/positions.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from "vitest";
+
+import { PositionSchema, PositionStatusSchema } from "../positions.js";
+
+describe("PositionSchema", () => {
+  const base = {
+    id: "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
+    orgId: "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b",
+    unitId: "9c5b94b1-35ad-49bb-b118-8e8fc24abf80",
+    title: "Staff Engineer — Platform",
+    status: "open",
+    lifecycleOwner: "org_design",
+    provenance: {
+      tier: "user",
+      source: "manual",
+      confidence: null,
+      locked: true,
+    },
+  };
+
+  it("parses a valid open position", () => {
+    const position = PositionSchema.parse(base);
+    expect(position.status).toBe("open");
+    expect(position.title).toBe("Staff Engineer — Platform");
+    expect(position.lifecycleOwner).toBe("org_design");
+  });
+
+  it("accepts every lifecycle status", () => {
+    for (const status of ["planned", "open", "filled", "closed"] as const) {
+      expect(PositionSchema.parse({ ...base, status }).status).toBe(status);
+    }
+  });
+
+  it("rejects a non-uuid id, orgId, or unitId", () => {
+    expect(() => PositionSchema.parse({ ...base, id: "nope" })).toThrow();
+    expect(() => PositionSchema.parse({ ...base, orgId: "nope" })).toThrow();
+    expect(() => PositionSchema.parse({ ...base, unitId: "nope" })).toThrow();
+  });
+
+  it("rejects an empty title or lifecycleOwner", () => {
+    expect(() => PositionSchema.parse({ ...base, title: "" })).toThrow();
+    expect(() =>
+      PositionSchema.parse({ ...base, lifecycleOwner: "" }),
+    ).toThrow();
+  });
+
+  it("rejects an invalid status and a hiring-only status", () => {
+    expect(() =>
+      PositionSchema.parse({ ...base, status: "archived" }),
+    ).toThrow();
+    // 'hiring' belongs to OpenRoleStatus, not the seat-existence lifecycle.
+    expect(() => PositionSchema.parse({ ...base, status: "hiring" })).toThrow();
+  });
+
+  it("requires a provenance envelope (Position is a structure fact)", () => {
+    const { provenance: _provenance, ...withoutProvenance } = base;
+    expect(() => PositionSchema.parse(withoutProvenance)).toThrow();
+  });
+});
+
+describe("PositionStatusSchema", () => {
+  it("is a closed set distinct from OpenRoleStatus", () => {
+    expect(PositionStatusSchema.options).toEqual([
+      "planned",
+      "open",
+      "filled",
+      "closed",
+    ]);
+  });
+});

package/src/org/__tests__/source-authority.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from "vitest";
+
+import { SourceAuthoritySchema } from "../source-authority.js";
+
+describe("SourceAuthoritySchema", () => {
+  const base = {
+    entityType: "position",
+    entityId: "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
+    field: "title",
+    systemOfRecord: "hris",
+  };
+
+  it("parses a valid source-authority record", () => {
+    const authority = SourceAuthoritySchema.parse(base);
+    expect(authority.entityType).toBe("position");
+    expect(authority.field).toBe("title");
+    expect(authority.systemOfRecord).toBe("hris");
+  });
+
+  it("accepts any entity kind as an open string", () => {
+    for (const entityType of [
+      "position",
+      "occupancy",
+      "person",
+      "future_kind",
+    ]) {
+      expect(
+        SourceAuthoritySchema.parse({ ...base, entityType }).entityType,
+      ).toBe(entityType);
+    }
+  });
+
+  it("accepts any system of record as an open string", () => {
+    for (const systemOfRecord of ["hris", "manual", "scim", "future_system"]) {
+      expect(
+        SourceAuthoritySchema.parse({ ...base, systemOfRecord }).systemOfRecord,
+      ).toBe(systemOfRecord);
+    }
+  });
+
+  it("rejects a non-uuid entityId", () => {
+    expect(() =>
+      SourceAuthoritySchema.parse({ ...base, entityId: "nope" }),
+    ).toThrow();
+  });
+
+  it("rejects an empty entityType, field, or systemOfRecord", () => {
+    expect(() =>
+      SourceAuthoritySchema.parse({ ...base, entityType: "" }),
+    ).toThrow();
+    expect(() => SourceAuthoritySchema.parse({ ...base, field: "" })).toThrow();
+    expect(() =>
+      SourceAuthoritySchema.parse({ ...base, systemOfRecord: "" }),
+    ).toThrow();
+  });
+
+  it("does not carry a provenance envelope (distinct from provenance)", () => {
+    const parsed = SourceAuthoritySchema.parse({
+      ...base,
+      provenance: { tier: "user", source: "manual" },
+    });
+    expect("provenance" in parsed).toBe(false);
+  });
+});

package/src/org/index.ts

@@ -100,6 +100,32 @@ export type {
   HomeAssignment,
 } from "./structure-facts";
 
+// Occupancy: the holds_position relation (M:N, co-occupancy first-class).
+// Vacancy = a position with no active occupancy. (ADR-CONT-083 / ADR-CTRL-182)
+export { OccupancyStatusSchema, OccupancySchema } from "./occupancy";
+export type { OccupancyStatus, Occupancy } from "./occupancy";
+
+// Position: the org seat (planned/open/filled/closed) — a seat, not a person
+// or a title. Carries a FactProvenance envelope. (ADR-CONT-083 / ADR-CTRL-182)
+export { PositionStatusSchema, PositionSchema } from "./positions";
+export type { PositionStatus, Position } from "./positions";
+
+// Position reporting: the canonical seat -> manager-seat reporting edge. The
+// person hierarchy derives from this composed with occupancy. (ADR-CONT-083 / ADR-CTRL-182)
+export {
+  PositionReportingRelationshipTypeSchema,
+  PositionReportingSchema,
+} from "./position-reporting";
+export type {
+  PositionReportingRelationshipType,
+  PositionReporting,
+} from "./position-reporting";
+
+// Source authority: per-field ownership — who may WRITE a given entity field.
+// Orthogonal to provenance (who reported). (ADR-CONT-083 / ADR-CTRL-182)
+export { SourceAuthoritySchema } from "./source-authority";
+export type { SourceAuthority } from "./source-authority";
+
 // Canonical OrgUnit tree ordering (PRD-00506)
 export type { TreeOrderableNode } from "./tree-ordering";
 export { orderTreeNodes } from "./tree-ordering";

package/src/org/occupancy.ts

@@ -0,0 +1,69 @@
+/**
+ * Occupancy: the `holds_position` relation between a Person and a Position.
+ *
+ * A Position is a SEAT in the org graph; an Occupancy records that a particular
+ * Person holds that seat over some interval. The relation is many-to-many and
+ * co-occupancy is FIRST-CLASS (ADR-CTRL-182 clause 2 / contracts ADR-CONT-083):
+ *
+ *  - A single Position MAY be held by several People at once (job share,
+ *    transition overlap, interim + permanent), so co-occupancy is a normal
+ *    state, not an error to be reconciled away.
+ *  - A single Person MAY hold several Positions at once (one human, many seats).
+ *
+ * VACANCY is the absence of any active Occupancy for a Position — a Position with
+ * no `status: "active"` Occupancy is vacant. Vacancy is therefore derived, never
+ * stored: do not add a `vacant` flag to Position; query Occupancy instead.
+ *
+ * Occupancy is a STRUCTURE FACT: it carries a {@link FactProvenanceSchema}
+ * envelope so the truth hierarchy (user > sync > import > inferred) and the
+ * append+supersede correction model apply to it exactly as they do to reporting
+ * edges, memberships, and home assignments. This is the distinction from
+ * Person/IdentityLink, which are identity vocabulary and carry no provenance.
+ *
+ * `positionId` is a forward reference to a Position seat id (a bare uuid here);
+ * `personId` references the org-graph {@link PersonSchema} node, not a User
+ * account.
+ */
+import { z } from "zod";
+
+import { FactProvenanceSchema } from "./structure-facts";
+
+// ---------------------------------------------------------------------------
+// Occupancy status — closed lifecycle axis
+// ---------------------------------------------------------------------------
+
+/**
+ * Lifecycle of a single occupancy of a position. Closed set.
+ *
+ *  - `pending` — a future hold not yet in effect (e.g. an accepted offer with a
+ *    start date in the future). Does NOT make the position occupied.
+ *  - `active`  — the person currently holds the position. The only status that
+ *    counts toward occupancy; a position with no `active` occupancy is vacant.
+ *  - `ended`   — the hold has concluded (kept as history, never deleted).
+ */
+export const OccupancyStatusSchema = z.enum(["pending", "active", "ended"]);
+export type OccupancyStatus = z.infer<typeof OccupancyStatusSchema>;
+
+// ---------------------------------------------------------------------------
+// Occupancy — the holds_position structure fact
+// ---------------------------------------------------------------------------
+
+export const OccupancySchema = z.object({
+  /** Unique identifier for this occupancy record within the org graph. */
+  id: z.string().uuid(),
+  /** Owning organization (tenant) this occupancy belongs to. */
+  orgId: z.string().uuid(),
+  /** The position (seat) being held. Forward reference to a Position id. */
+  positionId: z.string().uuid(),
+  /** The person holding the position — an org-graph node, not a User account. */
+  personId: z.string().uuid(),
+  /** Lifecycle of this hold; only `active` makes the position occupied. */
+  status: OccupancyStatusSchema,
+  /** ISO start of the hold; `null`/absent when unknown or open-started. */
+  startsAt: z.string().datetime().nullable().optional(),
+  /** ISO end of the hold; `null`/absent while the hold is still open. */
+  endsAt: z.string().datetime().nullable().optional(),
+  /** Provenance of this occupancy fact (truth hierarchy + supersede model). */
+  provenance: FactProvenanceSchema,
+});
+export type Occupancy = z.infer<typeof OccupancySchema>;

package/src/org/position-reporting.ts

@@ -0,0 +1,63 @@
+/**
+ * Position Reporting Vocabulary
+ *
+ * A PositionReporting record is the CANONICAL reporting edge of the org graph:
+ * a position reports to a manager position. The person-level "who reports to
+ * whom" hierarchy is DERIVED from this edge composed with occupancy (who holds
+ * each position) — see ADR-CTRL-182 clause 3. Modelling reporting at the
+ * position layer (seat → seat) rather than the person layer keeps the chart
+ * stable across re-orgs and vacancies: the edge survives even when a seat is
+ * temporarily unfilled.
+ *
+ * `relationshipType` distinguishes a `solid` line (primary, single chain of
+ * accountability) from a `dotted` line (secondary / matrixed reporting). It is
+ * defined locally here as a closed two-member enum so the org module stays
+ * self-contained and takes on no dependency on the identity domain.
+ *
+ * NOTE ON PLACEMENT / PROVENANCE: ADR-CONT-083 sketches the Position family in
+ * the identity domain and describes authority via a separate SourceAuthority
+ * qualifier. This module instead lives in the org domain and carries the shared
+ * {@link FactProvenanceSchema} envelope — consistent with the other structural
+ * facts in this domain (reporting edges, home assignments). The reporting edge
+ * is a structure fact, so it records its own provenance.
+ *
+ * @see ADR-CONT-083 for the Position/Occupancy/PositionReporting vocabulary
+ * @see structure-facts.ts for the FactProvenance envelope
+ */
+import { z } from "zod";
+import { FactProvenanceSchema } from "./structure-facts";
+
+// ---------------------------------------------------------------------------
+// Reporting relationship type — solid (primary) vs dotted (matrixed)
+// ---------------------------------------------------------------------------
+
+/**
+ * The kind of reporting line. Closed set: `solid` is the primary accountability
+ * chain (a position has exactly one solid manager); `dotted` is a secondary /
+ * matrixed line. Defined locally to keep the org module self-contained.
+ */
+export const PositionReportingRelationshipTypeSchema = z.enum([
+  "solid",
+  "dotted",
+]);
+export type PositionReportingRelationshipType = z.infer<
+  typeof PositionReportingRelationshipTypeSchema
+>;
+
+// ---------------------------------------------------------------------------
+// PositionReporting — position → manager position canonical edge
+// ---------------------------------------------------------------------------
+
+export const PositionReportingSchema = z.object({
+  id: z.string().uuid(),
+  orgId: z.string().uuid(),
+  // The reporting (subordinate) position — the seat that reports up.
+  reportPositionId: z.string().uuid(),
+  // The manager position this seat reports to.
+  managerPositionId: z.string().uuid(),
+  // Solid (primary) vs dotted (matrixed) reporting line.
+  relationshipType: PositionReportingRelationshipTypeSchema,
+  // Provenance of this reporting edge. Optional on lightweight projections.
+  provenance: FactProvenanceSchema.optional(),
+});
+export type PositionReporting = z.infer<typeof PositionReportingSchema>;

package/src/org/positions.ts

@@ -0,0 +1,65 @@
+/**
+ * Position Vocabulary — the org seat.
+ *
+ * A Position is a SEAT in the org, NOT a person and NOT a title (ADR-CTRL-182
+ * clause 1). It is the slot a Person can occupy: it exists independently of
+ * whoever fills it, can be `planned` before anyone is hired, sits `open` while
+ * vacant, becomes `filled` when a Person occupies it, and is `closed` when the
+ * seat is retired. `title` is a human-facing LABEL for the seat (e.g. "Staff
+ * Engineer — Platform"); it is descriptive metadata, never the occupant's
+ * identity.
+ *
+ * Position is a structure fact (it lives in a unit and is sourced/imported like
+ * other org-structure edges), so unlike `Person` it carries a
+ * {@link FactProvenanceSchema} envelope. See control ADR-CTRL-182 for the
+ * org-model rationale and the contracts-side ADR-CONT-083 for the API addition.
+ */
+import { z } from "zod";
+
+import { FactProvenanceSchema } from "./structure-facts";
+
+// ---------------------------------------------------------------------------
+// Position lifecycle status
+// ---------------------------------------------------------------------------
+
+/**
+ * Lifecycle of a seat's EXISTENCE — distinct from a hiring pipeline. A seat is
+ * `planned` (intended, not yet active), `open` (active and vacant), `filled` (a
+ * Person occupies it), or `closed` (retired). This is deliberately NOT
+ * `OpenRoleStatusSchema` (which models the hiring funnel and has `hiring`): a
+ * Position's status is about whether the seat is, not about recruiting for it.
+ */
+export const PositionStatusSchema = z.enum([
+  "planned",
+  "open",
+  "filled",
+  "closed",
+]);
+export type PositionStatus = z.infer<typeof PositionStatusSchema>;
+
+// ---------------------------------------------------------------------------
+// Position — the org seat
+// ---------------------------------------------------------------------------
+
+export const PositionSchema = z.object({
+  /** Unique identifier for the seat within the org graph. */
+  id: z.string().uuid(),
+  /** Owning organization (tenant) this seat belongs to. */
+  orgId: z.string().uuid(),
+  /** The org unit the seat lives in (references `org_units`). */
+  unitId: z.string().uuid(),
+  /** Human-facing LABEL for the seat, NOT the occupant's identity. */
+  title: z.string().min(1),
+  /** Lifecycle of the seat's existence. */
+  status: PositionStatusSchema,
+  /**
+   * Who owns the seat's EXISTENCE (its creation, retitling, retirement) — an
+   * OPEN string (no enum) so new owner kinds need no schema change, mirroring
+   * the `provider`/`source` open-string idiom. This is about the seat, not who
+   * fills it.
+   */
+  lifecycleOwner: z.string().min(1),
+  /** Provenance of this seat as a structure fact. */
+  provenance: FactProvenanceSchema,
+});
+export type Position = z.infer<typeof PositionSchema>;

package/src/org/source-authority.ts

@@ -0,0 +1,44 @@
+/**
+ * SourceAuthority Vocabulary — the per-field ownership axis.
+ *
+ * A SourceAuthority binds a single FIELD of a single org-graph entity to its
+ * `systemOfRecord` — the authority that may WRITE that field (ADR-CTRL-182
+ * clause 4). It answers "who owns this value?", a question that is deliberately
+ * DISTINCT from provenance: provenance ({@link FactProvenanceSchema}) records
+ * who *reported* a fact and how confident it is, whereas SourceAuthority
+ * records who is *allowed to change* it. The two axes are orthogonal — a fact
+ * may be reported manually yet owned by an HRIS — so this schema does NOT embed
+ * or reference the provenance envelope.
+ *
+ * Like `Person`, SourceAuthority is identity/ownership vocabulary, not a
+ * structure fact, so it carries no provenance envelope. `entityType` and
+ * `systemOfRecord` are OPEN strings (no enum) so new entity kinds and new
+ * systems of record need no schema change, mirroring the `provider`/`source`
+ * open-string idiom used elsewhere in the org model. See control ADR-CTRL-182.
+ */
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// SourceAuthority — per-field ownership: who may WRITE a given entity field
+// ---------------------------------------------------------------------------
+
+export const SourceAuthoritySchema = z.object({
+  /**
+   * Kind of org-graph entity the owned field belongs to (e.g. "position",
+   * "occupancy", "person"). An OPEN string so new entity kinds need no schema
+   * change.
+   */
+  entityType: z.string().min(1),
+  /** Identifier of the specific entity instance that owns the field. */
+  entityId: z.string().uuid(),
+  /** Name of the single field this authority record governs. */
+  field: z.string().min(1),
+  /**
+   * The authority that may WRITE this field — the system of record. An OPEN
+   * string (no enum) so new systems of record need no schema change. This is
+   * about who may change the value, NOT who reported it (provenance).
+   */
+  systemOfRecord: z.string().min(1),
+});
+
+export type SourceAuthority = z.infer<typeof SourceAuthoritySchema>;