@company-semantics/contracts 58.0.0 → 58.1.0

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

@@ -6,6 +6,7 @@ import {
   CanonicalPositionSchema,
   CanonicalOccupancySchema,
   CanonicalReportingEdgeSchema,
+  CanonicalUnresolvedManagerSchema,
   CanonicalFactsSchema,
 } from "../canonical-facts.js";
 
@@ -105,12 +106,14 @@ describe("CanonicalPositionSchema", () => {
     externalSourceSystem: "workday",
     title: "Staff Engineer",
     unitExternalSourceId: "dept-9",
+    status: "filled",
     provenance,
   };
 
   it("parses a seat placed in a unit by external reference", () => {
     const p = CanonicalPositionSchema.parse(base);
     expect(p.unitExternalSourceId).toBe("dept-9");
+    expect(p.status).toBe("filled");
   });
 
   it("rejects an empty title or missing unit reference", () => {
@@ -120,6 +123,95 @@ describe("CanonicalPositionSchema", () => {
     const { unitExternalSourceId: _u, ...without } = base;
     expect(() => CanonicalPositionSchema.parse(without)).toThrow();
   });
+
+  it("accepts every reported seat-existence value", () => {
+    for (const status of ["planned", "open", "filled"]) {
+      expect(CanonicalPositionSchema.parse({ ...base, status }).status).toBe(
+        status,
+      );
+    }
+  });
+
+  it("requires status — an adapter that cannot say must say 'filled'", () => {
+    const { status: _s, ...without } = base;
+    expect(() => CanonicalPositionSchema.parse(without)).toThrow();
+  });
+
+  it("rejects a status outside the reported-existence axis", () => {
+    // `closed` is an in-graph lifecycle outcome, not something a source reports.
+    expect(() =>
+      CanonicalPositionSchema.parse({ ...base, status: "closed" }),
+    ).toThrow();
+  });
+});
+
+describe("CanonicalUnresolvedManagerSchema", () => {
+  const base = {
+    externalSourceId: "unresolved-mgr-42",
+    externalSourceSystem: "bamboohr",
+    externalManagerId: "42",
+    reportPositionExternalSourceIds: ["pos-7", "pos-8"],
+    provenance,
+  };
+
+  it("parses a dangling supervisor reference with its report seats", () => {
+    const u = CanonicalUnresolvedManagerSchema.parse(base);
+    expect(u.externalManagerId).toBe("42");
+    expect(u.reportPositionExternalSourceIds).toEqual(["pos-7", "pos-8"]);
+  });
+
+  it("defaults resolution to 'unknown' — never to a vacancy", () => {
+    expect(CanonicalUnresolvedManagerSchema.parse(base).resolution).toBe(
+      "unknown",
+    );
+  });
+
+  it("records a vacancy only when the source says so", () => {
+    expect(
+      CanonicalUnresolvedManagerSchema.parse({
+        ...base,
+        resolution: "vacant_position",
+      }).resolution,
+    ).toBe("vacant_position");
+  });
+
+  it("accepts the remaining causes, which are not interchangeable", () => {
+    for (const resolution of ["inactive_employee", "not_visible"]) {
+      expect(
+        CanonicalUnresolvedManagerSchema.parse({ ...base, resolution })
+          .resolution,
+      ).toBe(resolution);
+    }
+  });
+
+  it("rejects an unknown resolution cause", () => {
+    expect(() =>
+      CanonicalUnresolvedManagerSchema.parse({
+        ...base,
+        resolution: "terminated",
+      }),
+    ).toThrow();
+  });
+
+  it("requires the unresolvable manager id and a provenance envelope", () => {
+    expect(() =>
+      CanonicalUnresolvedManagerSchema.parse({
+        ...base,
+        externalManagerId: "",
+      }),
+    ).toThrow();
+    const { provenance: _omitted, ...without } = base;
+    expect(() => CanonicalUnresolvedManagerSchema.parse(without)).toThrow();
+  });
+
+  it("accepts an empty report list (the reference dangles on its own)", () => {
+    expect(
+      CanonicalUnresolvedManagerSchema.parse({
+        ...base,
+        reportPositionExternalSourceIds: [],
+      }).reportPositionExternalSourceIds,
+    ).toEqual([]);
+  });
 });
 
 describe("CanonicalOccupancySchema", () => {
@@ -187,9 +279,11 @@ describe("CanonicalFactsSchema", () => {
       positions: [],
       occupancies: [],
       reportingEdges: [],
+      unresolvedManagers: [],
     });
     expect(facts.people).toEqual([]);
     expect(facts.reportingEdges).toEqual([]);
+    expect(facts.unresolvedManagers).toEqual([]);
   });
 
   it("parses a populated batch with one of each fact", () => {
@@ -216,6 +310,7 @@ describe("CanonicalFactsSchema", () => {
           externalSourceSystem: "workday",
           title: "Staff Engineer",
           unitExternalSourceId: "dept-9",
+          status: "filled",
           provenance,
         },
       ],
@@ -238,9 +333,19 @@ describe("CanonicalFactsSchema", () => {
           provenance,
         },
       ],
+      unresolvedManagers: [
+        {
+          externalSourceId: "unresolved-mgr-42",
+          externalSourceSystem: "bamboohr",
+          externalManagerId: "42",
+          reportPositionExternalSourceIds: ["pos-7"],
+          provenance,
+        },
+      ],
     });
     expect(facts.people).toHaveLength(1);
     expect(facts.positions[0].unitExternalSourceId).toBe("dept-9");
+    expect(facts.unresolvedManagers[0].resolution).toBe("unknown");
   });
 
   it("requires every array key to be present", () => {
@@ -249,6 +354,18 @@ describe("CanonicalFactsSchema", () => {
     ).toThrow();
   });
 
+  it("requires the unresolvedManagers channel — silence is not an option", () => {
+    expect(() =>
+      CanonicalFactsSchema.parse({
+        people: [],
+        orgUnits: [],
+        positions: [],
+        occupancies: [],
+        reportingEdges: [],
+      }),
+    ).toThrow();
+  });
+
   it("rejects a member that fails its element schema", () => {
     expect(() =>
       CanonicalFactsSchema.parse({
@@ -264,6 +381,7 @@ describe("CanonicalFactsSchema", () => {
         positions: [],
         occupancies: [],
         reportingEdges: [],
+        unresolvedManagers: [],
       }),
     ).toThrow();
   });

package/src/org/__tests__/structure-inference.test.ts

@@ -0,0 +1,392 @@
+import { describe, it, expect } from "vitest";
+
+import {
+  StructureEvidenceSchema,
+  TOPOLOGY_ONLY_EVIDENCE_KINDS,
+  StructureUnitAuthoritySchema,
+  ProposedOrgUnitSchema,
+  PersonStructureOutcomeSchema,
+  StructureReviewItemSchema,
+  StructureProposalSchema,
+  StructurePersonFactSchema,
+  StructureReportingFactSchema,
+  ExistingUnitFactSchema,
+  ExistingPlacementFactSchema,
+  StructureInferenceSnapshotSchema,
+} from "../structure-inference.js";
+
+const UNIT_ID = "11111111-1111-4111-8111-111111111111";
+const ORG_ID = "22222222-2222-4222-8222-222222222222";
+
+const roleFamilyEvidence = {
+  kind: "role_family" as const,
+  family: "Technical Recruiter",
+  personIds: ["p1", "p2", "p3", "p4"],
+  count: 4,
+};
+
+const topologyEvidence = {
+  kind: "reporting_cluster" as const,
+  managerPersonId: "mgr-1",
+  personIds: ["p1", "p2"],
+};
+
+describe("StructureEvidenceSchema", () => {
+  it("round-trips every evidence kind the validator reasons over", () => {
+    const kinds = [
+      { kind: "explicit_department", personIds: ["p1"], value: "People" },
+      { kind: "explicit_division", personIds: ["p1"], value: "G&A" },
+      roleFamilyEvidence,
+      { kind: "functional_leader", personId: "p9", function: "People" },
+      topologyEvidence,
+      { kind: "administrative_pivot", personId: "p7", departmentEntropy: 1.9 },
+      { kind: "controlled_ontology", concept: "Recruiting" },
+    ];
+    for (const evidence of kinds) {
+      expect(StructureEvidenceSchema.parse(evidence)).toEqual(evidence);
+    }
+  });
+
+  it("rejects prose masquerading as evidence — the whole point of typing it", () => {
+    expect(() =>
+      StructureEvidenceSchema.parse("several employees have similar roles"),
+    ).toThrow();
+    expect(() =>
+      StructureEvidenceSchema.parse({ kind: "vibes", note: "feels right" }),
+    ).toThrow();
+  });
+
+  it("names administrative_pivot, so a proposal can explain a boundary it did NOT draw", () => {
+    const parsed = StructureEvidenceSchema.parse({
+      kind: "administrative_pivot",
+      personId: "olivia",
+      departmentEntropy: 1.94,
+    });
+    expect(parsed.kind).toBe("administrative_pivot");
+  });
+});
+
+describe("TOPOLOGY_ONLY_EVIDENCE_KINDS", () => {
+  it("names reporting_cluster and nothing else", () => {
+    expect(TOPOLOGY_ONLY_EVIDENCE_KINDS).toEqual(["reporting_cluster"]);
+  });
+
+  it("holds only kinds StructureEvidence actually declares", () => {
+    for (const kind of TOPOLOGY_ONLY_EVIDENCE_KINDS) {
+      expect(() =>
+        StructureEvidenceSchema.parse({
+          kind,
+          managerPersonId: "mgr-1",
+          personIds: [],
+        }),
+      ).not.toThrow();
+    }
+  });
+});
+
+describe("StructureUnitAuthoritySchema", () => {
+  it("is the anchor-vs-reorganizable axis, not the fact truth hierarchy", () => {
+    expect(StructureUnitAuthoritySchema.options).toEqual([
+      "human_confirmed",
+      "ai_inferred",
+      "hris_source",
+    ]);
+    // The FactSourceTier members must NOT be accepted here — two closed sets
+    // meaning almost the same thing is exactly the ambiguity to avoid.
+    expect(() => StructureUnitAuthoritySchema.parse("inferred")).toThrow();
+    expect(() => StructureUnitAuthoritySchema.parse("user")).toThrow();
+  });
+});
+
+describe("ProposedOrgUnitSchema", () => {
+  const base = {
+    tempId: "u1",
+    targetUnitId: UNIT_ID,
+    identityConfidence: 0.95,
+    identityEvidence: [roleFamilyEvidence],
+    name: "People",
+    nameBasis: [roleFamilyEvidence],
+    parentTempId: null,
+    suggestedTypeLabel: "Department",
+    headPersonId: "p9",
+    nameConfidence: 0.8,
+    structureConfidence: 0.9,
+    provisional: false,
+    evidence: [roleFamilyEvidence],
+  };
+
+  it("carries targetUnitId so a rename preserves durable identity", () => {
+    expect(ProposedOrgUnitSchema.parse(base).targetUnitId).toBe(UNIT_ID);
+  });
+
+  it("requires targetUnitId to be present-or-null, never absent", () => {
+    const { targetUnitId: _omitted, ...without } = base;
+    expect(() => ProposedOrgUnitSchema.parse(without)).toThrow();
+    expect(
+      ProposedOrgUnitSchema.parse({ ...base, targetUnitId: null }).targetUnitId,
+    ).toBeNull();
+  });
+
+  it("requires targetUnitId to be a durable uuid, not a name or a tempId", () => {
+    expect(() =>
+      ProposedOrgUnitSchema.parse({ ...base, targetUnitId: "People" }),
+    ).toThrow();
+  });
+
+  it("rejects confidences outside [0,1]", () => {
+    expect(() =>
+      ProposedOrgUnitSchema.parse({ ...base, nameConfidence: 1.4 }),
+    ).toThrow();
+    expect(() =>
+      ProposedOrgUnitSchema.parse({ ...base, structureConfidence: -0.1 }),
+    ).toThrow();
+  });
+
+  it("keeps nameBasis separate from boundary evidence", () => {
+    const parsed = ProposedOrgUnitSchema.parse({
+      ...base,
+      nameBasis: [],
+      evidence: [topologyEvidence],
+    });
+    expect(parsed.nameBasis).toEqual([]);
+    expect(parsed.evidence).toEqual([topologyEvidence]);
+  });
+});
+
+describe("PersonStructureOutcomeSchema", () => {
+  it("round-trips all three outcomes — placed, needs_review, excluded", () => {
+    const placed = PersonStructureOutcomeSchema.parse({
+      kind: "placed",
+      personId: "p1",
+      unitTempId: "u1",
+      confidence: 0.9,
+      evidence: [roleFamilyEvidence],
+      conflicts: [],
+    });
+    expect(placed.kind).toBe("placed");
+
+    const review = PersonStructureOutcomeSchema.parse({
+      kind: "needs_review",
+      personId: "emily",
+      reason: "insufficient_evidence",
+    });
+    expect(review.kind).toBe("needs_review");
+
+    const excluded = PersonStructureOutcomeSchema.parse({
+      kind: "excluded",
+      personId: "bamboo-svc",
+      reason: "service_account",
+    });
+    expect(excluded.kind).toBe("excluded");
+  });
+
+  it("gives an unplaceable person a REASON — never a guess, never an absence", () => {
+    expect(() =>
+      PersonStructureOutcomeSchema.parse({
+        kind: "needs_review",
+        personId: "emily",
+      }),
+    ).toThrow();
+    expect(() =>
+      PersonStructureOutcomeSchema.parse({
+        kind: "needs_review",
+        personId: "emily",
+        reason: "felt_odd",
+      }),
+    ).toThrow();
+  });
+
+  it("has no 'unplaced' or empty outcome — every person lands in one arm", () => {
+    expect(() =>
+      PersonStructureOutcomeSchema.parse({ kind: "unplaced", personId: "p1" }),
+    ).toThrow();
+  });
+
+  it("requires a placed outcome to name the unit it placed the person in", () => {
+    expect(() =>
+      PersonStructureOutcomeSchema.parse({
+        kind: "placed",
+        personId: "p1",
+        confidence: 0.9,
+        evidence: [],
+        conflicts: [],
+      }),
+    ).toThrow();
+  });
+});
+
+describe("StructureReviewItemSchema", () => {
+  const base = {
+    kind: "placement_conflict",
+    personIds: ["clarissa"],
+    unitTempIds: ["u1", "u2"],
+    question: "Which unit does this Account Executive belong to?",
+    recommended: "u2",
+    alternatives: ["u1"],
+    signals: {
+      department: "Human Resources",
+      manager: "VP of Marketing",
+      roleFamily: "Account Executive",
+    },
+    confidence: 0.45,
+    evidence: [roleFamilyEvidence],
+  };
+
+  it("carries the competing signals so a reviewer can see WHY it is ambiguous", () => {
+    const parsed = StructureReviewItemSchema.parse(base);
+    expect(Object.keys(parsed.signals)).toHaveLength(3);
+    expect(parsed.signals.manager).toBe("VP of Marketing");
+  });
+
+  it("rejects an unknown review kind", () => {
+    expect(() =>
+      StructureReviewItemSchema.parse({ ...base, kind: "something_else" }),
+    ).toThrow();
+  });
+});
+
+describe("StructureProposalSchema", () => {
+  const proposal = {
+    orgId: ORG_ID,
+    sourceSnapshotId: "snap-1",
+    structureRevision: "rev-7",
+    inputHash: "sha256:abc",
+    promptVersion: "3",
+    orgUnits: [
+      {
+        tempId: "u1",
+        targetUnitId: UNIT_ID,
+        identityConfidence: 0.95,
+        identityEvidence: [roleFamilyEvidence],
+        name: "People",
+        nameBasis: [roleFamilyEvidence],
+        parentTempId: null,
+        suggestedTypeLabel: "Department",
+        headPersonId: "p9",
+        nameConfidence: 0.8,
+        structureConfidence: 0.9,
+        provisional: false,
+        evidence: [roleFamilyEvidence],
+      },
+    ],
+    personOutcomes: [
+      {
+        kind: "placed",
+        personId: "p1",
+        unitTempId: "u1",
+        confidence: 0.9,
+        evidence: [roleFamilyEvidence],
+        conflicts: [],
+      },
+    ],
+    structureWarnings: [],
+    reviewItems: [],
+  };
+
+  it("round-trips a whole proposal without loss", () => {
+    expect(StructureProposalSchema.parse(proposal)).toEqual(proposal);
+  });
+
+  it("keeps inputHash and sourceSnapshotId as separate fields", () => {
+    // Staleness is decided by inputHash; sourceSnapshotId is lineage only.
+    const parsed = StructureProposalSchema.parse(proposal);
+    expect(parsed.inputHash).not.toBe(parsed.sourceSnapshotId);
+  });
+
+  it("rejects an orgId that is not a durable uuid", () => {
+    expect(() =>
+      StructureProposalSchema.parse({ ...proposal, orgId: "Bamboo Workspace" }),
+    ).toThrow();
+  });
+});
+
+describe("StructureInferenceSnapshotSchema", () => {
+  const person = {
+    personId: "p1",
+    sourcePersonId: "emp-42",
+    displayName: "Duke Smith",
+    title: "Technical Recruiter",
+    department: "Human Resources",
+    division: null,
+    location: null,
+    managerPersonId: "mgr-1",
+    directReportPersonIds: [],
+  };
+
+  const snapshot = {
+    orgId: ORG_ID,
+    sourceSnapshotId: "snap-1",
+    structureRevision: "rev-7",
+    persons: [person],
+    reporting: [
+      {
+        reportPersonId: "p1",
+        managerPersonId: "mgr-1",
+        relationshipType: "solid",
+      },
+    ],
+    existingUnits: [
+      {
+        unitId: UNIT_ID,
+        name: "Human Resources",
+        parentUnitId: null,
+        depth: 2,
+        authority: "hris_source",
+      },
+    ],
+    existingPlacements: [
+      { personId: "p1", unitId: UNIT_ID, authority: "hris_source" },
+    ],
+  };
+
+  it("round-trips the persisted-graph view the engine reasons over", () => {
+    expect(StructureInferenceSnapshotSchema.parse(snapshot)).toEqual(snapshot);
+  });
+
+  it("accepts a person fact with sourcePersonId stripped for the model", () => {
+    const { sourcePersonId: _stripped, ...modelFacing } = person;
+    expect(
+      StructurePersonFactSchema.parse(modelFacing).sourcePersonId,
+    ).toBeUndefined();
+    expect(
+      StructurePersonFactSchema.parse({ ...person, sourcePersonId: null })
+        .sourcePersonId,
+    ).toBeNull();
+  });
+
+  it("still requires the opaque personId — the only handle a proposal may use", () => {
+    const { personId: _omitted, ...without } = person;
+    expect(() => StructurePersonFactSchema.parse(without)).toThrow();
+    expect(() =>
+      StructurePersonFactSchema.parse({ ...person, personId: "" }),
+    ).toThrow();
+  });
+
+  it("carries the authority axis on every existing unit and placement", () => {
+    expect(() =>
+      ExistingUnitFactSchema.parse({
+        unitId: UNIT_ID,
+        name: "People",
+        parentUnitId: null,
+        depth: 2,
+      }),
+    ).toThrow();
+    expect(
+      ExistingPlacementFactSchema.parse({
+        personId: "p1",
+        unitId: UNIT_ID,
+        authority: "human_confirmed",
+      }).authority,
+    ).toBe("human_confirmed");
+  });
+
+  it("keeps reporting a typed edge list, so the validator can prove it unchanged", () => {
+    expect(() =>
+      StructureReportingFactSchema.parse({
+        reportPersonId: "p1",
+        managerPersonId: "mgr-1",
+        relationshipType: "advisory",
+      }),
+    ).toThrow();
+  });
+});