@company-semantics/contracts 58.0.0 → 58.2.0

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();
+  });
+});

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

@@ -0,0 +1,187 @@
+import { describe, it, expect } from "vitest";
+
+import {
+  ExistingPlacementFactSchema,
+  ExistingUnitFactSchema,
+  StructureProposalOriginSchema,
+  StructureAcceptedBySchema,
+  StructureAuthoritySchema,
+  StructureProvenanceSchema,
+  StructureUnitAuthoritySchema,
+  mayOverrideAuthority,
+} from "../structure-inference.js";
+import type { StructureAuthority } from "../structure-inference.js";
+
+const USER_ID = "33333333-3333-4333-8333-333333333333";
+const UNIT_ID = "44444444-4444-4444-8444-444444444444";
+
+/** v1: the AI proposed it and an admin clicked Apply. */
+const aiProposedHumanAccepted = {
+  proposalOrigin: "ai_inference" as const,
+  acceptedBy: { kind: "user" as const, userId: USER_ID },
+  authority: "human_confirmed" as const,
+};
+
+describe("StructureProposalOriginSchema", () => {
+  it("names the three ways a structural fact can come to be proposed", () => {
+    for (const origin of ["ai_inference", "hris_source", "manual"]) {
+      expect(StructureProposalOriginSchema.parse(origin)).toBe(origin);
+    }
+  });
+
+  it("has no user_override member — that value is what the axes replace", () => {
+    expect(() =>
+      StructureProposalOriginSchema.parse("user_override"),
+    ).toThrow();
+  });
+});
+
+describe("StructureAcceptedBySchema", () => {
+  it("distinguishes a person signing off from a policy deciding", () => {
+    expect(
+      StructureAcceptedBySchema.parse({ kind: "user", userId: USER_ID }),
+    ).toEqual({ kind: "user", userId: USER_ID });
+    expect(StructureAcceptedBySchema.parse({ kind: "system_policy" })).toEqual({
+      kind: "system_policy",
+    });
+  });
+
+  it("refuses an unattributed acceptance — a null acceptor is not an answer", () => {
+    expect(() => StructureAcceptedBySchema.parse(null)).toThrow();
+    expect(() => StructureAcceptedBySchema.parse({ kind: "user" })).toThrow();
+    expect(() =>
+      StructureAcceptedBySchema.parse({ kind: "user", userId: "not-a-uuid" }),
+    ).toThrow();
+  });
+});
+
+describe("StructureAuthoritySchema", () => {
+  it("human confirmed outranks ai inferred outranks hris source", () => {
+    const descending: StructureAuthority[] = [
+      "human_confirmed",
+      "ai_inferred",
+      "hris_source",
+    ];
+
+    // Every authority may overwrite itself and everything below it...
+    for (let i = 0; i < descending.length; i += 1) {
+      for (let j = i; j < descending.length; j += 1) {
+        expect(mayOverrideAuthority(descending[i]!, descending[j]!)).toBe(true);
+      }
+    }
+    // ...and nothing below may overwrite something above it.
+    for (let i = 0; i < descending.length; i += 1) {
+      for (let j = 0; j < i; j += 1) {
+        expect(mayOverrideAuthority(descending[i]!, descending[j]!)).toBe(
+          false,
+        );
+      }
+    }
+  });
+
+  it("lets an equal authority correct itself, so a first write is not frozen", () => {
+    expect(mayOverrideAuthority("hris_source", "hris_source")).toBe(true);
+    expect(mayOverrideAuthority("human_confirmed", "human_confirmed")).toBe(
+      true,
+    );
+  });
+
+  it("stops an HRIS sync reverting an accepted placement", () => {
+    expect(mayOverrideAuthority("hris_source", "human_confirmed")).toBe(false);
+    expect(mayOverrideAuthority("hris_source", "ai_inferred")).toBe(false);
+  });
+
+  it("is the same ladder the engine reads, not a second copy of it", () => {
+    expect(StructureAuthoritySchema).toBe(StructureUnitAuthoritySchema);
+  });
+});
+
+describe("StructureProvenanceSchema", () => {
+  it("records acceptance without erasing how the fact originated", () => {
+    const parsed = StructureProvenanceSchema.parse(aiProposedHumanAccepted);
+    expect(parsed.authority).toBe("human_confirmed");
+    // The origin survives acceptance — this is the whole defect being fixed.
+    expect(parsed.proposalOrigin).toBe("ai_inference");
+  });
+
+  it("keeps the axes orthogonal: same origin, different acceptor, different authority", () => {
+    const autoAccepted = StructureProvenanceSchema.parse({
+      proposalOrigin: "ai_inference",
+      acceptedBy: { kind: "system_policy" },
+      authority: "ai_inferred",
+    });
+    expect(autoAccepted.proposalOrigin).toBe(
+      aiProposedHumanAccepted.proposalOrigin,
+    );
+    expect(autoAccepted.authority).not.toBe(aiProposedHumanAccepted.authority);
+  });
+
+  it("round-trips the manual and HRIS rows of the provenance table", () => {
+    const manual = {
+      proposalOrigin: "manual" as const,
+      acceptedBy: { kind: "user" as const, userId: USER_ID },
+      authority: "human_confirmed" as const,
+    };
+    const feed = {
+      proposalOrigin: "hris_source" as const,
+      acceptedBy: { kind: "system_policy" as const },
+      authority: "hris_source" as const,
+    };
+    expect(StructureProvenanceSchema.parse(manual)).toEqual(manual);
+    expect(StructureProvenanceSchema.parse(feed)).toEqual(feed);
+  });
+
+  it("carries its authority onto the existing fact a human accepted", () => {
+    const accepted = StructureProvenanceSchema.parse(aiProposedHumanAccepted);
+    const placement = ExistingPlacementFactSchema.parse({
+      personId: "p1",
+      unitId: UNIT_ID,
+      authority: accepted.authority,
+    });
+
+    // A human-accepted placement is an ANCHOR, never a revisitable AI guess —
+    // recording it as ai_inferred is the failure this vocabulary exists to close.
+    expect(placement.authority).toBe("human_confirmed");
+    expect(placement.authority).not.toBe("ai_inferred");
+    expect(mayOverrideAuthority("ai_inferred", placement.authority)).toBe(
+      false,
+    );
+  });
+
+  it("reserves ai_inferred for acceptance by policy, with nobody in the loop", () => {
+    const autoAccepted = StructureProvenanceSchema.parse({
+      proposalOrigin: "ai_inference",
+      acceptedBy: { kind: "system_policy" },
+      authority: "ai_inferred",
+    });
+    expect(autoAccepted.acceptedBy.kind).toBe("system_policy");
+
+    const unit = ExistingUnitFactSchema.parse({
+      unitId: UNIT_ID,
+      name: "Platform",
+      parentUnitId: null,
+      depth: 0,
+      authority: autoAccepted.authority,
+    });
+
+    // Nobody signed off, so the engine may still reorganize it and a later
+    // human decision overwrites it.
+    expect(unit.authority).toBe("ai_inferred");
+    expect(mayOverrideAuthority("human_confirmed", unit.authority)).toBe(true);
+  });
+
+  it("requires all three axes — a partial record cannot answer who signed off", () => {
+    expect(() =>
+      StructureProvenanceSchema.parse({
+        proposalOrigin: "ai_inference",
+        authority: "human_confirmed",
+      }),
+    ).toThrow();
+    expect(() =>
+      StructureProvenanceSchema.parse({
+        acceptedBy: { kind: "system_policy" },
+        authority: "hris_source",
+      }),
+    ).toThrow();
+  });
+});