@company-semantics/contracts 20.0.0 → 20.1.0

package/package.json

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

package/src/index.ts

@@ -408,6 +408,36 @@ export type {
 export { SourceAuthoritySchema } from "./org/index";
 export type { SourceAuthority } from "./org/index";
 
+// Sync run summary: the outcome record of one adapter sync run (counts +
+// cursor watermark). A flat report shape, not a structure fact. (ADR-CONT-085)
+export { SyncRunSummarySchema } from "./org/index";
+export type { SyncRunSummary } from "./org/index";
+
+// Conflict record: one recorded reconciliation conflict surfaced during a sync.
+// Operational audit record about a sync, not a structure fact. (ADR-CONT-085)
+export { ConflictRecordSchema } from "./org/index";
+export type { ConflictRecord } from "./org/index";
+
+// Canonical facts: the adapter-seam ingestion batch — external-keyed Canonical*
+// facts (each with provenance) plus a CanonicalFacts envelope. The reconciler
+// consumes the batch into the internal org graph. (ADR-CONT-085 / ADR-CTRL-183)
+export {
+  CanonicalPersonSchema,
+  CanonicalOrgUnitSchema,
+  CanonicalPositionSchema,
+  CanonicalOccupancySchema,
+  CanonicalReportingEdgeSchema,
+  CanonicalFactsSchema,
+} from "./org/index";
+export type {
+  CanonicalPerson,
+  CanonicalOrgUnit,
+  CanonicalPosition,
+  CanonicalOccupancy,
+  CanonicalReportingEdge,
+  CanonicalFacts,
+} from "./org/index";
+
 // Authority & Delegation vocabulary
 export {
   AuthoritySourceSchema,

package/src/org/README.md

@@ -40,6 +40,18 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `AuthoritySource` _(type)_
 - `AuthoritySourceSchema` — Engine-internal authority source.
 - `AuthorizableView` _(type)_ — Type for views that can be checked against VIEWSCOPEMAP.
+- `CanonicalFacts` _(type)_
+- `CanonicalFactsSchema` — The full normalized batch an external-source adapter emits in one pass: every person, org unit, position…
+- `CanonicalOccupancy` _(type)_
+- `CanonicalOccupancySchema` — An occupancy (a person holds a seat) as reported by an external source.
+- `CanonicalOrgUnit` _(type)_
+- `CanonicalOrgUnitSchema` — An org unit as reported by an external source.
+- `CanonicalPerson` _(type)_
+- `CanonicalPersonSchema` — A person as reported by an external source, keyed by external identity.
+- `CanonicalPosition` _(type)_
+- `CanonicalPositionSchema` — A position (seat) as reported by an external source, placed in a unit by external reference…
+- `CanonicalReportingEdge` _(type)_
+- `CanonicalReportingEdgeSchema` — A reporting edge (a seat reports to a manager seat) as reported by an external source.
 - `CapabilitiesResponse` _(type)_
 - `CapabilitiesResponseSchema` — The single validated capability surface the UI reads.
 - `ChangeMemberRoleRequest` _(type)_ — Request payload for changing a member's role.
@@ -58,6 +70,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `CompanyMdSource` _(type)_
 - `CompanyMdTreeNode` _(type)_
 - `CompanyMdVisibility` _(type)_ — Visibility band for a Company.md document — the canonical AUTH `entity_visibility` vocabulary (, backend ). -…
+- `ConflictRecord` _(type)_
+- `ConflictRecordSchema`
 - `CreateDelegationRequest` _(type)_
 - `CreateDelegationRequestSchema`
 - `CreateInviteRequest` _(type)_ — Request payload for creating an organization invite.
@@ -246,6 +260,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `SsoStepperStep` _(type)_ — Backend-authoritative stepper step.
 - `SubmitInteractiveTaskResponse` _(type)_
 - `SubmitInteractiveTaskResponseSchema` — Response for submitting a filled-in interactive chat task surface (e.g. the editable "change reporting…
+- `SyncRunSummary` _(type)_
+- `SyncRunSummarySchema`
 - `TRANSFER_RESPONSIBILITIES` — Responsibility checklist items shown on the acceptance page.
 - `TestSsoInitiation` _(type)_ — Initiation payload for a test SSO login attempt.
 - `TestSsoInitiationDto` _(type)_ — Initiation payload for a test SSO login attempt.

package/src/org/__tests__/canonical-facts.test.ts

@@ -0,0 +1,270 @@
+import { describe, it, expect } from "vitest";
+
+import {
+  CanonicalPersonSchema,
+  CanonicalOrgUnitSchema,
+  CanonicalPositionSchema,
+  CanonicalOccupancySchema,
+  CanonicalReportingEdgeSchema,
+  CanonicalFactsSchema,
+} from "../canonical-facts.js";
+
+const provenance = {
+  tier: "import",
+  source: "bamboohr",
+  confidence: 0.9,
+  locked: false,
+};
+
+describe("CanonicalPersonSchema", () => {
+  const base = {
+    externalSourceId: "emp-123",
+    externalSourceSystem: "bamboohr",
+    displayName: "Ada Lovelace",
+    provenance,
+  };
+
+  it("parses a minimal person without an email", () => {
+    const p = CanonicalPersonSchema.parse(base);
+    expect(p.externalSourceId).toBe("emp-123");
+    expect(p.primaryEmail).toBeUndefined();
+  });
+
+  it("accepts a null or valid email", () => {
+    expect(
+      CanonicalPersonSchema.parse({ ...base, primaryEmail: null }).primaryEmail,
+    ).toBeNull();
+    expect(
+      CanonicalPersonSchema.parse({ ...base, primaryEmail: "ada@x.io" })
+        .primaryEmail,
+    ).toBe("ada@x.io");
+  });
+
+  it("rejects a malformed email", () => {
+    expect(() =>
+      CanonicalPersonSchema.parse({ ...base, primaryEmail: "not-an-email" }),
+    ).toThrow();
+  });
+
+  it("rejects empty external identity (open strings still require content)", () => {
+    expect(() =>
+      CanonicalPersonSchema.parse({ ...base, externalSourceId: "" }),
+    ).toThrow();
+    expect(() =>
+      CanonicalPersonSchema.parse({ ...base, externalSourceSystem: "" }),
+    ).toThrow();
+  });
+
+  it("requires a provenance envelope (canonical facts are inputs)", () => {
+    const { provenance: _omitted, ...without } = base;
+    expect(() => CanonicalPersonSchema.parse(without)).toThrow();
+  });
+
+  it("does NOT require a uuid for external ids", () => {
+    // External ids are arbitrary strings from the origin system, not uuids.
+    expect(() =>
+      CanonicalPersonSchema.parse({ ...base, externalSourceId: "abc/42" }),
+    ).not.toThrow();
+  });
+});
+
+describe("CanonicalOrgUnitSchema", () => {
+  const base = {
+    externalSourceId: "dept-9",
+    externalSourceSystem: "workday",
+    name: "Platform",
+    provenance,
+  };
+
+  it("parses a root unit (no parent)", () => {
+    const u = CanonicalOrgUnitSchema.parse(base);
+    expect(u.parentExternalSourceId).toBeUndefined();
+  });
+
+  it("accepts a parent external reference or null", () => {
+    expect(
+      CanonicalOrgUnitSchema.parse({
+        ...base,
+        parentExternalSourceId: "dept-1",
+      }).parentExternalSourceId,
+    ).toBe("dept-1");
+    expect(
+      CanonicalOrgUnitSchema.parse({ ...base, parentExternalSourceId: null })
+        .parentExternalSourceId,
+    ).toBeNull();
+  });
+
+  it("rejects an empty name", () => {
+    expect(() => CanonicalOrgUnitSchema.parse({ ...base, name: "" })).toThrow();
+  });
+});
+
+describe("CanonicalPositionSchema", () => {
+  const base = {
+    externalSourceId: "pos-7",
+    externalSourceSystem: "workday",
+    title: "Staff Engineer",
+    unitExternalSourceId: "dept-9",
+    provenance,
+  };
+
+  it("parses a seat placed in a unit by external reference", () => {
+    const p = CanonicalPositionSchema.parse(base);
+    expect(p.unitExternalSourceId).toBe("dept-9");
+  });
+
+  it("rejects an empty title or missing unit reference", () => {
+    expect(() =>
+      CanonicalPositionSchema.parse({ ...base, title: "" }),
+    ).toThrow();
+    const { unitExternalSourceId: _u, ...without } = base;
+    expect(() => CanonicalPositionSchema.parse(without)).toThrow();
+  });
+});
+
+describe("CanonicalOccupancySchema", () => {
+  const base = {
+    externalSourceId: "occ-3",
+    externalSourceSystem: "bamboohr",
+    positionExternalSourceId: "pos-7",
+    personExternalSourceId: "emp-123",
+    provenance,
+  };
+
+  it("parses a person-holds-seat fact keyed by external ids", () => {
+    const o = CanonicalOccupancySchema.parse(base);
+    expect(o.positionExternalSourceId).toBe("pos-7");
+    expect(o.personExternalSourceId).toBe("emp-123");
+  });
+
+  it("requires both sides of the relation", () => {
+    const { positionExternalSourceId: _p, ...noPosition } = base;
+    expect(() => CanonicalOccupancySchema.parse(noPosition)).toThrow();
+    const { personExternalSourceId: _q, ...noPerson } = base;
+    expect(() => CanonicalOccupancySchema.parse(noPerson)).toThrow();
+  });
+});
+
+describe("CanonicalReportingEdgeSchema", () => {
+  const base = {
+    externalSourceId: "edge-2",
+    externalSourceSystem: "workday",
+    reportPositionExternalSourceId: "pos-7",
+    managerPositionExternalSourceId: "pos-1",
+    relationshipType: "solid",
+    provenance,
+  };
+
+  it("parses a seat -> manager-seat edge", () => {
+    const e = CanonicalReportingEdgeSchema.parse(base);
+    expect(e.relationshipType).toBe("solid");
+  });
+
+  it("accepts the dotted relationship type", () => {
+    expect(
+      CanonicalReportingEdgeSchema.parse({
+        ...base,
+        relationshipType: "dotted",
+      }).relationshipType,
+    ).toBe("dotted");
+  });
+
+  it("rejects an unknown relationship type", () => {
+    expect(() =>
+      CanonicalReportingEdgeSchema.parse({
+        ...base,
+        relationshipType: "matrix",
+      }),
+    ).toThrow();
+  });
+});
+
+describe("CanonicalFactsSchema", () => {
+  it("parses an empty batch (all arrays empty)", () => {
+    const facts = CanonicalFactsSchema.parse({
+      people: [],
+      orgUnits: [],
+      positions: [],
+      occupancies: [],
+      reportingEdges: [],
+    });
+    expect(facts.people).toEqual([]);
+    expect(facts.reportingEdges).toEqual([]);
+  });
+
+  it("parses a populated batch with one of each fact", () => {
+    const facts = CanonicalFactsSchema.parse({
+      people: [
+        {
+          externalSourceId: "emp-123",
+          externalSourceSystem: "bamboohr",
+          displayName: "Ada Lovelace",
+          provenance,
+        },
+      ],
+      orgUnits: [
+        {
+          externalSourceId: "dept-9",
+          externalSourceSystem: "workday",
+          name: "Platform",
+          provenance,
+        },
+      ],
+      positions: [
+        {
+          externalSourceId: "pos-7",
+          externalSourceSystem: "workday",
+          title: "Staff Engineer",
+          unitExternalSourceId: "dept-9",
+          provenance,
+        },
+      ],
+      occupancies: [
+        {
+          externalSourceId: "occ-3",
+          externalSourceSystem: "bamboohr",
+          positionExternalSourceId: "pos-7",
+          personExternalSourceId: "emp-123",
+          provenance,
+        },
+      ],
+      reportingEdges: [
+        {
+          externalSourceId: "edge-2",
+          externalSourceSystem: "workday",
+          reportPositionExternalSourceId: "pos-7",
+          managerPositionExternalSourceId: "pos-1",
+          relationshipType: "solid",
+          provenance,
+        },
+      ],
+    });
+    expect(facts.people).toHaveLength(1);
+    expect(facts.positions[0].unitExternalSourceId).toBe("dept-9");
+  });
+
+  it("requires every array key to be present", () => {
+    expect(() =>
+      CanonicalFactsSchema.parse({ people: [], orgUnits: [], positions: [] }),
+    ).toThrow();
+  });
+
+  it("rejects a member that fails its element schema", () => {
+    expect(() =>
+      CanonicalFactsSchema.parse({
+        people: [
+          {
+            externalSourceId: "",
+            externalSourceSystem: "x",
+            displayName: "y",
+            provenance,
+          },
+        ],
+        orgUnits: [],
+        positions: [],
+        occupancies: [],
+        reportingEdges: [],
+      }),
+    ).toThrow();
+  });
+});

package/src/org/__tests__/conflict-record.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect } from "vitest";
+
+import { ConflictRecordSchema } from "../conflict-record.js";
+import { FactSourceTierSchema } from "../structure-facts.js";
+
+describe("ConflictRecordSchema", () => {
+  const base = {
+    id: "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
+    runId: "9c5b94b1-35ad-49bb-b118-8e8fc24abf80",
+    entityType: "person",
+    entityId: "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
+    field: "managerPositionId",
+    importedValue: "seat-a",
+    currentValue: "seat-b",
+    winningValue: "seat-b",
+    winningTier: "user",
+    reason: "Human override outranks the imported feed.",
+  };
+
+  it("parses a valid conflict record", () => {
+    const record = ConflictRecordSchema.parse(base);
+    expect(record.field).toBe("managerPositionId");
+    expect(record.winningTier).toBe("user");
+    expect(record.winningValue).toBe("seat-b");
+  });
+
+  it("accepts any entity kind and field as open strings", () => {
+    for (const entityType of ["person", "position", "occupancy", "future"]) {
+      expect(
+        ConflictRecordSchema.parse({ ...base, entityType }).entityType,
+      ).toBe(entityType);
+    }
+    expect(
+      ConflictRecordSchema.parse({ ...base, field: "anything_at_all" }).field,
+    ).toBe("anything_at_all");
+  });
+
+  it("accepts every FactSourceTier as winningTier", () => {
+    for (const tier of FactSourceTierSchema.options) {
+      expect(
+        ConflictRecordSchema.parse({ ...base, winningTier: tier }).winningTier,
+      ).toBe(tier);
+    }
+  });
+
+  it("rejects an unknown winningTier", () => {
+    expect(() =>
+      ConflictRecordSchema.parse({ ...base, winningTier: "guess" }),
+    ).toThrow();
+  });
+
+  it("allows null competing values", () => {
+    const record = ConflictRecordSchema.parse({
+      ...base,
+      importedValue: null,
+      currentValue: null,
+      winningValue: null,
+    });
+    expect(record.importedValue).toBeNull();
+    expect(record.currentValue).toBeNull();
+    expect(record.winningValue).toBeNull();
+  });
+
+  it("treats reason as optional and nullable", () => {
+    const { reason: _reason, ...withoutReason } = base;
+    expect(() => ConflictRecordSchema.parse(withoutReason)).not.toThrow();
+    expect(
+      ConflictRecordSchema.parse({ ...base, reason: null }).reason,
+    ).toBeNull();
+  });
+
+  it("rejects a reason longer than 2000 chars", () => {
+    expect(() =>
+      ConflictRecordSchema.parse({ ...base, reason: "x".repeat(2001) }),
+    ).toThrow();
+  });
+
+  it("rejects a non-uuid id, runId, or entityId", () => {
+    expect(() => ConflictRecordSchema.parse({ ...base, id: "nope" })).toThrow();
+    expect(() =>
+      ConflictRecordSchema.parse({ ...base, runId: "nope" }),
+    ).toThrow();
+    expect(() =>
+      ConflictRecordSchema.parse({ ...base, entityId: "nope" }),
+    ).toThrow();
+  });
+
+  it("rejects an empty entityType or field", () => {
+    expect(() =>
+      ConflictRecordSchema.parse({ ...base, entityType: "" }),
+    ).toThrow();
+    expect(() => ConflictRecordSchema.parse({ ...base, field: "" })).toThrow();
+  });
+});

package/src/org/__tests__/sync-run.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from "vitest";
+
+import { SyncRunSummarySchema } from "../sync-run.js";
+
+describe("SyncRunSummarySchema", () => {
+  const base = {
+    id: "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
+    startedAt: "2026-01-01T00:00:00.000Z",
+    processed: 100,
+    changed: 12,
+    skipped: 85,
+    conflicts: 2,
+    failures: 1,
+  };
+
+  it("parses a minimal in-progress run without endedAt or sinceCursor", () => {
+    const run = SyncRunSummarySchema.parse(base);
+    expect(run.processed).toBe(100);
+    expect(run.endedAt).toBeUndefined();
+    expect(run.sinceCursor).toBeUndefined();
+  });
+
+  it("accepts null and ISO datetime for endedAt", () => {
+    expect(
+      SyncRunSummarySchema.parse({ ...base, endedAt: null }).endedAt,
+    ).toBeNull();
+    const ended = SyncRunSummarySchema.parse({
+      ...base,
+      endedAt: "2026-01-01T00:05:00.000Z",
+    });
+    expect(ended.endedAt).toBe("2026-01-01T00:05:00.000Z");
+  });
+
+  it("accepts null and a string watermark for sinceCursor", () => {
+    expect(
+      SyncRunSummarySchema.parse({ ...base, sinceCursor: null }).sinceCursor,
+    ).toBeNull();
+    expect(
+      SyncRunSummarySchema.parse({
+        ...base,
+        sinceCursor: "2026-01-01T00:00:00Z",
+      }).sinceCursor,
+    ).toBe("2026-01-01T00:00:00Z");
+  });
+
+  it("rejects a non-ISO startedAt", () => {
+    expect(() =>
+      SyncRunSummarySchema.parse({ ...base, startedAt: "2026-01-01" }),
+    ).toThrow();
+  });
+
+  it("rejects a non-uuid id", () => {
+    expect(() => SyncRunSummarySchema.parse({ ...base, id: "nope" })).toThrow();
+  });
+
+  it("rejects negative or non-integer counters", () => {
+    expect(() =>
+      SyncRunSummarySchema.parse({ ...base, processed: -1 }),
+    ).toThrow();
+    expect(() =>
+      SyncRunSummarySchema.parse({ ...base, changed: 1.5 }),
+    ).toThrow();
+  });
+
+  it("requires startedAt (run has begun)", () => {
+    const { startedAt: _omitted, ...withoutStartedAt } = base;
+    expect(() => SyncRunSummarySchema.parse(withoutStartedAt)).toThrow();
+  });
+});

package/src/org/canonical-facts.ts

@@ -0,0 +1,181 @@
+/**
+ * Canonical Facts — the adapter-seam ingestion vocabulary.
+ *
+ * A `CanonicalFacts` batch is the NORMALIZED shape an external-source adapter
+ * (an HRIS sync, a CSV import, an org-chart scrape) emits BEFORE reconciliation
+ * into the internal org graph. It is the single hand-off point between "what a
+ * source said" and "what the org graph becomes": adapters translate their
+ * proprietary payloads into this vocabulary, and the reconciler consumes it to
+ * create/supersede internal Person / OrgUnit / Position / Occupancy / reporting
+ * records. See contracts ADR-CONT-085 and control ADR-CTRL-183.
+ *
+ * Two properties make these facts distinct from the in-graph schemas they mirror
+ * ({@link PersonSchema}, {@link PositionSchema}, {@link OccupancySchema}, …):
+ *
+ *  1. They are keyed by EXTERNAL identity, not internal uuids. Every fact carries
+ *     `externalSourceId` (the id in the origin system, an arbitrary string — NOT
+ *     a uuid) plus `externalSourceSystem` (an OPEN string naming the system, e.g.
+ *     `bamboohr` | `workday` | `csv`). Cross-references between facts in a batch
+ *     (an occupancy's person, a reporting edge's manager seat) are expressed with
+ *     those external ids too, because internal uuids do not exist yet at ingest.
+ *
+ *  2. They ALL carry a {@link FactProvenanceSchema} envelope — including
+ *     `CanonicalPerson`. This is a deliberate divergence from the in-graph
+ *     vocabulary, where identity types (`Person`, `SourceAuthority`) carry no
+ *     provenance: a canonical fact is by definition a reconciliation INPUT, and
+ *     the truth hierarchy (user > sync > import > inferred) plus the
+ *     append+supersede correction model must apply uniformly to every fact a
+ *     source reports, identity-shaped or not.
+ *
+ * `externalSourceSystem` mirrors the open-string idiom of `provenance.source`
+ * and `SourceAuthority.systemOfRecord`: new origin systems need no schema change.
+ */
+import { z } from "zod";
+
+import { FactProvenanceSchema } from "./structure-facts";
+import { PositionReportingRelationshipTypeSchema } from "./position-reporting";
+
+// ---------------------------------------------------------------------------
+// CanonicalPerson — a normalized person reported by an external source
+// ---------------------------------------------------------------------------
+
+/**
+ * A person as reported by an external source, keyed by external identity. Mirrors
+ * {@link PersonSchema} but carries provenance because it is a reconciliation
+ * input (see file header for why identity-shaped canonical facts still carry it).
+ */
+export const CanonicalPersonSchema = z.object({
+  /** Id of this person in the origin system — arbitrary string, NOT a uuid. */
+  externalSourceId: z.string().min(1),
+  /** Origin system naming this id — OPEN string (e.g. `bamboohr`, `workday`). */
+  externalSourceSystem: z.string().min(1),
+  /** Human-facing display name as reported by the source. */
+  displayName: z.string().min(1),
+  /** Primary email as reported; `null`/absent when the source omits it. */
+  primaryEmail: z.string().email().nullable().optional(),
+  /** Provenance of this fact (truth hierarchy + supersede model). */
+  provenance: FactProvenanceSchema,
+});
+export type CanonicalPerson = z.infer<typeof CanonicalPersonSchema>;
+
+// ---------------------------------------------------------------------------
+// CanonicalOrgUnit — a normalized org unit reported by an external source
+// ---------------------------------------------------------------------------
+
+/**
+ * An org unit as reported by an external source. The parent reference is an
+ * external id (`parentExternalSourceId`), so the unit tree is reconstructable
+ * within a batch before any internal uuid exists; a root unit has no parent.
+ */
+export const CanonicalOrgUnitSchema = z.object({
+  /** Id of this unit in the origin system — arbitrary string, NOT a uuid. */
+  externalSourceId: z.string().min(1),
+  /** Origin system naming this id — OPEN string. */
+  externalSourceSystem: z.string().min(1),
+  /** Human-facing unit name as reported by the source. */
+  name: z.string().min(1),
+  /** External id of the parent unit; `null`/absent for a root unit. */
+  parentExternalSourceId: z.string().min(1).nullable().optional(),
+  /** Provenance of this fact (truth hierarchy + supersede model). */
+  provenance: FactProvenanceSchema,
+});
+export type CanonicalOrgUnit = z.infer<typeof CanonicalOrgUnitSchema>;
+
+// ---------------------------------------------------------------------------
+// CanonicalPosition — a normalized seat reported by an external source
+// ---------------------------------------------------------------------------
+
+/**
+ * A position (seat) as reported by an external source, placed in a unit by
+ * external reference (`unitExternalSourceId`). Mirrors {@link PositionSchema};
+ * `title` is the seat's LABEL, never the occupant's identity.
+ */
+export const CanonicalPositionSchema = z.object({
+  /** Id of this seat in the origin system — arbitrary string, NOT a uuid. */
+  externalSourceId: z.string().min(1),
+  /** Origin system naming this id — OPEN string. */
+  externalSourceSystem: z.string().min(1),
+  /** Human-facing label for the seat, NOT the occupant's identity. */
+  title: z.string().min(1),
+  /** External id of the org unit this seat lives in. */
+  unitExternalSourceId: z.string().min(1),
+  /** Provenance of this fact (truth hierarchy + supersede model). */
+  provenance: FactProvenanceSchema,
+});
+export type CanonicalPosition = z.infer<typeof CanonicalPositionSchema>;
+
+// ---------------------------------------------------------------------------
+// CanonicalOccupancy — a normalized holds_position fact (external-keyed)
+// ---------------------------------------------------------------------------
+
+/**
+ * An occupancy (a person holds a seat) as reported by an external source. Both
+ * sides are external references: `positionExternalSourceId` and
+ * `personExternalSourceId`. Mirrors {@link OccupancySchema} at the ingestion
+ * seam.
+ */
+export const CanonicalOccupancySchema = z.object({
+  /** Id of this occupancy in the origin system — arbitrary string, NOT a uuid. */
+  externalSourceId: z.string().min(1),
+  /** Origin system naming this id — OPEN string. */
+  externalSourceSystem: z.string().min(1),
+  /** External id of the position (seat) being held. */
+  positionExternalSourceId: z.string().min(1),
+  /** External id of the person holding the seat. */
+  personExternalSourceId: z.string().min(1),
+  /** Provenance of this fact (truth hierarchy + supersede model). */
+  provenance: FactProvenanceSchema,
+});
+export type CanonicalOccupancy = z.infer<typeof CanonicalOccupancySchema>;
+
+// ---------------------------------------------------------------------------
+// CanonicalReportingEdge — a normalized seat -> manager-seat reporting edge
+// ---------------------------------------------------------------------------
+
+/**
+ * A reporting edge (a seat reports to a manager seat) as reported by an external
+ * source. Both seats are external references; `relationshipType` reuses the
+ * org-domain {@link PositionReportingRelationshipTypeSchema} (solid vs dotted).
+ * Mirrors {@link PositionReportingSchema} at the ingestion seam.
+ */
+export const CanonicalReportingEdgeSchema = z.object({
+  /** Id of this edge in the origin system — arbitrary string, NOT a uuid. */
+  externalSourceId: z.string().min(1),
+  /** Origin system naming this id — OPEN string. */
+  externalSourceSystem: z.string().min(1),
+  /** External id of the reporting (subordinate) seat. */
+  reportPositionExternalSourceId: z.string().min(1),
+  /** External id of the manager seat this seat reports to. */
+  managerPositionExternalSourceId: z.string().min(1),
+  /** Solid (primary) vs dotted (matrixed) reporting line. */
+  relationshipType: PositionReportingRelationshipTypeSchema,
+  /** Provenance of this fact (truth hierarchy + supersede model). */
+  provenance: FactProvenanceSchema,
+});
+export type CanonicalReportingEdge = z.infer<
+  typeof CanonicalReportingEdgeSchema
+>;
+
+// ---------------------------------------------------------------------------
+// CanonicalFacts — the batch envelope an adapter emits for reconciliation
+// ---------------------------------------------------------------------------
+
+/**
+ * The full normalized batch an external-source adapter emits in one pass: every
+ * person, org unit, position, occupancy, and reporting edge it observed, each
+ * carrying external identity + provenance. The reconciler consumes this whole
+ * envelope to create/supersede internal org-graph records.
+ */
+export const CanonicalFactsSchema = z.object({
+  /** Every person observed in this batch. */
+  people: z.array(CanonicalPersonSchema),
+  /** Every org unit observed in this batch. */
+  orgUnits: z.array(CanonicalOrgUnitSchema),
+  /** Every position (seat) observed in this batch. */
+  positions: z.array(CanonicalPositionSchema),
+  /** Every occupancy (person-holds-seat) observed in this batch. */
+  occupancies: z.array(CanonicalOccupancySchema),
+  /** Every seat-to-manager-seat reporting edge observed in this batch. */
+  reportingEdges: z.array(CanonicalReportingEdgeSchema),
+});
+export type CanonicalFacts = z.infer<typeof CanonicalFactsSchema>;

package/src/org/conflict-record.ts

@@ -0,0 +1,76 @@
+/**
+ * ConflictRecord Vocabulary — a single recorded reconciliation conflict.
+ *
+ * When a connector's normalized `CanonicalFacts` are reconciled against the
+ * org graph's existing facts, two systems may disagree — for example, two HR
+ * feeds reporting a different manager for the same person, or a feed
+ * contradicting a human override. A ConflictRecord is the audit trail for one
+ * such disagreement: it names the entity and field in conflict, the competing
+ * values (the value the feed imported vs. the value already held), the value
+ * that won, the tier of the winning value, and a human-meaningful reason. It is
+ * the record an operator and the override UX read to understand what happened
+ * during a sync (ADR-CONT-085, control ADR-CTRL-183).
+ *
+ * ConflictRecord is an operational record ABOUT a sync, not a structure fact:
+ * it references the precedence axis ({@link FactSourceTierSchema}) rather than
+ * carrying a full {@link FactProvenance} envelope, mirroring how SourceAuthority
+ * and SyncRunSummary stay distinct from the provenance-bearing facts. Like the
+ * sibling org schemas, `entityType` and `field` are OPEN strings (no enum) so
+ * new entity kinds and field names need no schema change, and `entityId`/`runId`
+ * are uuids. `winningTier` REUSES the closed `FactSourceTier` precedence axis
+ * rather than redefining it. The competing values are serialized as strings and
+ * are nullable because a conflicting (or absent) side may hold no value.
+ */
+import { z } from "zod";
+
+import { FactSourceTierSchema } from "./structure-facts";
+
+// ---------------------------------------------------------------------------
+// ConflictRecord — one recorded conflict surfaced while reconciling a sync
+// ---------------------------------------------------------------------------
+
+export const ConflictRecordSchema = z.object({
+  /** Identifier of this conflict record. */
+  id: z.string().uuid(),
+  /** The sync run during which this conflict was surfaced. */
+  runId: z.string().uuid(),
+  /**
+   * Kind of org-graph entity the conflicting 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 conflict. */
+  entityId: z.string().uuid(),
+  /** Name of the single field that was in conflict. */
+  field: z.string().min(1),
+  /**
+   * The value the connector's `CanonicalFacts` reported for this field,
+   * serialized as a string. `null` when the imported side carried no value.
+   */
+  importedValue: z.string().nullable(),
+  /**
+   * The value already held in the org graph for this field before
+   * reconciliation, serialized as a string. `null` when no prior value existed.
+   */
+  currentValue: z.string().nullable(),
+  /**
+   * The value that won reconciliation, serialized as a string. `null` when the
+   * resolution cleared the field.
+   */
+  winningValue: z.string().nullable(),
+  /**
+   * The precedence tier of the value that won — the same closed truth-hierarchy
+   * axis used across the org model ({@link FactSourceTierSchema}). Reused, not
+   * redefined.
+   */
+  winningTier: FactSourceTierSchema,
+  /**
+   * Human-meaningful WHY the conflict resolved as it did — a free-text audit
+   * record of intent, capped at 2000 chars to mirror the `FactProvenance.reason`
+   * / unit-owner reason API cap. `null`/absent when no narrative was recorded.
+   */
+  reason: z.string().max(2000).nullable().optional(),
+});
+
+export type ConflictRecord = z.infer<typeof ConflictRecordSchema>;

package/src/org/index.ts

@@ -126,6 +126,36 @@ export type {
 export { SourceAuthoritySchema } from "./source-authority";
 export type { SourceAuthority } from "./source-authority";
 
+// Sync run summary: the outcome record of one adapter sync run (counts +
+// cursor watermark). A flat report shape, not a structure fact. (ADR-CONT-085)
+export { SyncRunSummarySchema } from "./sync-run";
+export type { SyncRunSummary } from "./sync-run";
+
+// Conflict record: one recorded reconciliation conflict surfaced during a sync.
+// Operational audit record about a sync, not a structure fact. (ADR-CONT-085)
+export { ConflictRecordSchema } from "./conflict-record";
+export type { ConflictRecord } from "./conflict-record";
+
+// Canonical facts: the adapter-seam ingestion batch. Each fact is keyed by
+// external identity (externalSourceId/externalSourceSystem) and carries a
+// FactProvenance envelope; the reconciler consumes the batch. (ADR-CONT-085 / ADR-CTRL-183)
+export {
+  CanonicalPersonSchema,
+  CanonicalOrgUnitSchema,
+  CanonicalPositionSchema,
+  CanonicalOccupancySchema,
+  CanonicalReportingEdgeSchema,
+  CanonicalFactsSchema,
+} from "./canonical-facts";
+export type {
+  CanonicalPerson,
+  CanonicalOrgUnit,
+  CanonicalPosition,
+  CanonicalOccupancy,
+  CanonicalReportingEdge,
+  CanonicalFacts,
+} from "./canonical-facts";
+
 // Canonical OrgUnit tree ordering (PRD-00506)
 export type { TreeOrderableNode } from "./tree-ordering";
 export { orderTreeNodes } from "./tree-ordering";

package/src/org/sync-run.ts

@@ -0,0 +1,57 @@
+/**
+ * SyncRunSummary: the outcome record of a single adapter sync run.
+ *
+ * An external source adapter (BambooHR, Workday, CSV import, ...) ingests
+ * {@link CanonicalFacts} into the org graph in discrete RUNS. A SyncRunSummary
+ * is the audit/observability record of one such run: how much was processed,
+ * how much actually changed, and how far the run advanced its incremental
+ * cursor. It is a flat report shape — NOT a structure fact — so it carries no
+ * {@link FactProvenanceSchema} envelope; provenance lives on the individual
+ * facts a run produces, not on the run summary itself.
+ *
+ * The counters are independent tallies of what the run did:
+ *
+ *  - `processed` — facts examined by the run (the denominator).
+ *  - `changed`   — facts that resulted in an insert/supersede (real mutations).
+ *  - `skipped`   — facts examined but left untouched (no-op / already current).
+ *  - `conflicts` — facts that collided with higher-tier truth and were held
+ *    back rather than overwriting it (truth hierarchy: user > sync > import).
+ *  - `failures`  — facts that errored and were neither applied nor cleanly
+ *    skipped (the run's error budget).
+ *
+ * `sinceCursor` is the incremental watermark the run started from — the
+ * resume point handed to the adapter so it only fetches changes after that
+ * point. It is `null`/absent for a full (non-incremental) run. It is a plain
+ * resume watermark, not a paginated page cursor, so it is modeled as a bare
+ * nullable string rather than wrapped in a page envelope.
+ */
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// SyncRunSummary — the outcome record of one adapter sync run
+// ---------------------------------------------------------------------------
+
+export const SyncRunSummarySchema = z.object({
+  /** Unique identifier for this sync run within the org graph. */
+  id: z.string().uuid(),
+  /** ISO start of the run. Always set once a run has begun. */
+  startedAt: z.string().datetime(),
+  /** ISO end of the run; `null`/absent while the run is still in progress. */
+  endedAt: z.string().datetime().nullable().optional(),
+  /** Count of facts examined by the run (the denominator). */
+  processed: z.number().int().nonnegative(),
+  /** Count of facts that resulted in a real mutation (insert/supersede). */
+  changed: z.number().int().nonnegative(),
+  /** Count of facts examined but left untouched (no-op / already current). */
+  skipped: z.number().int().nonnegative(),
+  /** Count of facts held back due to a collision with higher-tier truth. */
+  conflicts: z.number().int().nonnegative(),
+  /** Count of facts that errored and were neither applied nor cleanly skipped. */
+  failures: z.number().int().nonnegative(),
+  /**
+   * Incremental watermark the run started from; `null`/absent for a full run.
+   * A resume point, not a paginated page cursor.
+   */
+  sinceCursor: z.string().nullable().optional(),
+});
+export type SyncRunSummary = z.infer<typeof SyncRunSummarySchema>;