@company-semantics/contracts 19.0.0 → 19.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "19.0.0",
+  "version": "19.2.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/index.ts

@@ -23,7 +23,12 @@ export type InsightConfidence = "low" | "medium" | "high";
 export type InvariantPhase = "observe" | "stabilize" | "enforce";
 
 // Integration partner categories — surface grouping in settings UIs
-export const INTEGRATION_CATEGORIES = ["Meetings", "Comms", "Docs"] as const;
+export const INTEGRATION_CATEGORIES = [
+  "Meetings",
+  "Comms",
+  "Docs",
+  "HR",
+] as const;
 export type IntegrationCategory = (typeof INTEGRATION_CATEGORIES)[number];
 
 // System diagram types
@@ -377,6 +382,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,
@@ -812,3 +843,8 @@ export * from "./permissions";
 // Single source of truth for upload formats; the backend normalizer joins its
 // private dispatch fields locally, the app derives its accept-set + copy.
 export * from "./ingestion";
+
+// Third-party integration vocabulary (PRD-00793)
+// HrConnectionStatus / HrConnectInput — see ./integrations/schemas.ts.
+// Pairs with the `HR` member of INTEGRATION_CATEGORIES above.
+export * from "./integrations";

package/src/integrations/README.md

@@ -0,0 +1,46 @@
+# integrations/
+
+Shared vocabulary for third-party integration surfaces.
+
+## Purpose
+
+The cross-repo contract for HR-system integrations. The backend owns the
+provider sync and persistence; the app renders the connection state and submits
+the connect form. Both repos share the same `HrConnectionStatus` projection and
+`HrConnectInput` shape so the boundary stays stable across independent releases.
+
+The `HR` member of `INTEGRATION_CATEGORIES` (package root) names this category
+alongside `Meetings`, `Comms`, and `Docs`.
+
+## Invariants
+
+- `HrConnectionStatusSchema` is a read projection: count and sync fields are
+  `null` until the first successful sync (a connected, never-synced integration).
+- `HrConnectInputSchema` carries only the customer's provider `subdomain`; no
+  secrets or provider credentials live in contracts.
+- Pure vocabulary — `zod` is the only runtime import (vocabulary-guard).
+
+<!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
+
+## Public API
+
+- `HrConnectInput` _(type)_
+- `HrConnectInputSchema` — Input submitted by the app to initiate an HR provider connection.
+- `HrConnectionStatus` _(type)_
+- `HrConnectionStatusSchema` — Health of the most recent HR provider sync.
+
+<!-- END GENERATED: readme-public-api -->
+
+<!-- BEGIN GENERATED: readme-dependencies — derived from code by `pnpm readme-api`. Do not edit. -->
+
+## Dependencies
+
+**Internal domains:**
+
+_None._
+
+**External packages:**
+
+- `zod`
+
+<!-- END GENERATED: readme-dependencies -->

package/src/integrations/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Third-party integration vocabulary barrel (PRD-00793).
+ *
+ * @see ./schemas.ts for the full schema definitions and invariants.
+ */
+export { HrConnectionStatusSchema, HrConnectInputSchema } from "./schemas";
+
+export type { HrConnectionStatus, HrConnectInput } from "./schemas";

package/src/integrations/schemas.ts

@@ -0,0 +1,72 @@
+/**
+ * Third-party integration shared vocabulary (PRD-00793).
+ *
+ * Zod schemas describing the cross-repo contract for HR-system integrations.
+ * The `HR` integration category joins the existing `INTEGRATION_CATEGORIES`
+ * tuple in the package root; these schemas describe the connection-status
+ * projection the backend exposes and the connect input the app submits.
+ *
+ * Lives in contracts because the integration surface crosses backend (which
+ * owns the provider sync + persistence) and app (which renders the connection
+ * state and the connect form), and breaking it would require coordinated
+ * releases (see the promotion rule in CLAUDE.md).
+ *
+ * Per the durable user preference `feedback_structured_metadata_not_json_strings`,
+ * descriptions live in `.meta({ description })` — structured metadata, not
+ * stringified JSON blobs on the schema.
+ */
+import { z } from "zod";
+
+// =============================================================================
+// HR connection status
+// =============================================================================
+
+/**
+ * Health of the most recent HR provider sync. `null` when no sync has run yet
+ * (a freshly connected, never-synced integration).
+ */
+export const HrConnectionStatusSchema = z
+  .object({
+    connected: z.boolean().meta({
+      description: "Whether an HR provider is currently connected.",
+    }),
+    employeeCount: z.number().int().nonnegative().nullable().meta({
+      description:
+        "Employees mirrored from the HR provider; null when never synced.",
+    }),
+    departmentCount: z.number().int().nonnegative().nullable().meta({
+      description:
+        "Departments mirrored from the HR provider; null when never synced.",
+    }),
+    lastSyncAt: z.string().datetime().nullable().meta({
+      description: "ISO timestamp of the last successful sync; null if never.",
+    }),
+    syncHealth: z.enum(["healthy", "degraded", "error"]).nullable().meta({
+      description:
+        "Health of the most recent sync; null when no sync has run yet.",
+    }),
+  })
+  .meta({
+    description: "Connection-status projection for an HR integration.",
+  });
+export type HrConnectionStatus = z.infer<typeof HrConnectionStatusSchema>;
+
+// =============================================================================
+// HR connect input
+// =============================================================================
+
+/**
+ * Input submitted by the app to initiate an HR provider connection. The
+ * `subdomain` identifies the customer's tenant on the provider (e.g. the
+ * BambooHR company subdomain).
+ */
+export const HrConnectInputSchema = z
+  .object({
+    subdomain: z.string().meta({
+      description: "Customer tenant subdomain on the HR provider.",
+    }),
+  })
+  .meta({
+    description: "Input to initiate an HR provider connection.",
+  });
+export type HrConnectInput = z.infer<typeof HrConnectInputSchema>;

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>;