@company-semantics/contracts 57.0.0 → 58.1.0

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

package/src/org/canonical-facts.ts

@@ -7,7 +7,9 @@
  * 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.
+ * records. See contracts ADR-CONT-085 and control ADR-CTRL-183; ADR-CONTRACTS-140
+ * amends ADR-CONT-085 with the sixth fact kind (`unresolvedManagers`), the
+ * required `status` on a position, and the major-bump consequence.
  *
  * Two properties make these facts distinct from the in-graph schemas they mirror
  * ({@link PersonSchema}, {@link PositionSchema}, {@link OccupancySchema}, …):
@@ -81,6 +83,34 @@ export const CanonicalOrgUnitSchema = z.object({
 });
 export type CanonicalOrgUnit = z.infer<typeof CanonicalOrgUnitSchema>;
 
+// ---------------------------------------------------------------------------
+// CanonicalPositionStatus — seat existence AS REPORTED by the source
+// ---------------------------------------------------------------------------
+
+/**
+ * Seat-existence as the SOURCE reported it. `filled` is the ordinary case; an
+ * adapter that cannot say must say `filled` rather than omit the field.
+ *
+ * This is a REPORTED claim at the ingest seam, deliberately narrower than the
+ * in-graph {@link PositionStatusSchema} lifecycle (which also has `closed`): a
+ * source describing its current workforce reports seats that exist, and seat
+ * retirement is a reconciliation outcome, not something a directory states.
+ *
+ * It does NOT contradict the occupancy invariant that in-graph VACANCY is
+ * derived from the absence of an active {@link OccupancySchema} (see
+ * `occupancy.ts`). This field records what the source SAID about the seat; the
+ * reconciler still derives vacancy from occupancy facts and never reads a
+ * `vacant` flag off a Position.
+ */
+export const CanonicalPositionStatusSchema = z.enum([
+  "planned",
+  "open",
+  "filled",
+]);
+export type CanonicalPositionStatus = z.infer<
+  typeof CanonicalPositionStatusSchema
+>;
+
 // ---------------------------------------------------------------------------
 // CanonicalPosition — a normalized seat reported by an external source
 // ---------------------------------------------------------------------------
@@ -99,6 +129,11 @@ export const CanonicalPositionSchema = z.object({
   title: z.string().min(1),
   /** External id of the org unit this seat lives in. */
   unitExternalSourceId: z.string().min(1),
+  /**
+   * Seat existence as the source reported it. REQUIRED — pre-launch we ship no
+   * back-compat optionality; an adapter that cannot say must say `filled`.
+   */
+  status: CanonicalPositionStatusSchema,
   /** Provenance of this fact (truth hierarchy + supersede model). */
   provenance: FactProvenanceSchema,
 });
@@ -156,6 +191,58 @@ export type CanonicalReportingEdge = z.infer<
   typeof CanonicalReportingEdgeSchema
 >;
 
+// ---------------------------------------------------------------------------
+// CanonicalUnresolvedManager — a supervisory reference that resolved to nothing
+// ---------------------------------------------------------------------------
+
+/**
+ * Why a supervisory reference could not be resolved to a seat in this batch.
+ *
+ * `unknown` is the default and asserts NOTHING beyond "we could not resolve
+ * it". Only `vacant_position` claims the company has an unfilled seat, and only
+ * when the source actually says so — "we could not resolve this reference" and
+ * "the company has an open requisition" are different organizational claims,
+ * and their causes (permissions, termination, stale data, scope limits, a
+ * hidden record, a real vacancy) are not interchangeable.
+ */
+export const CanonicalUnresolvedManagerResolutionSchema = z.enum([
+  "unknown",
+  "vacant_position",
+  "inactive_employee",
+  "not_visible",
+]);
+export type CanonicalUnresolvedManagerResolution = z.infer<
+  typeof CanonicalUnresolvedManagerResolutionSchema
+>;
+
+/**
+ * A supervisory reference the source reported that we could NOT resolve to a
+ * seat in this batch.
+ *
+ * Emitting this fact is what keeps an unresolvable supervisor from becoming a
+ * SILENT drop: the report seats that pointed at it stay traceable instead of
+ * surfacing as unexplained roots in the org graph. It never mints a seat by
+ * itself — see {@link CanonicalUnresolvedManagerResolutionSchema} for why only
+ * `vacant_position` licenses that.
+ */
+export const CanonicalUnresolvedManagerSchema = z.object({
+  /** Stable id for this unresolved reference in the origin system. */
+  externalSourceId: z.string().min(1),
+  /** Origin system naming this id — OPEN string. */
+  externalSourceSystem: z.string().min(1),
+  /** The supervisor identifier the source gave us and we could not resolve. */
+  externalManagerId: z.string().min(1),
+  /** External ids of the report seats pointing at this unresolved manager. */
+  reportPositionExternalSourceIds: z.array(z.string().min(1)),
+  /** Why it did not resolve; defaults to the non-committal `unknown`. */
+  resolution: CanonicalUnresolvedManagerResolutionSchema.default("unknown"),
+  /** Provenance of this fact (truth hierarchy + supersede model). */
+  provenance: FactProvenanceSchema,
+});
+export type CanonicalUnresolvedManager = z.infer<
+  typeof CanonicalUnresolvedManagerSchema
+>;
+
 // ---------------------------------------------------------------------------
 // CanonicalFacts — the batch envelope an adapter emits for reconciliation
 // ---------------------------------------------------------------------------
@@ -165,6 +252,10 @@ export type CanonicalReportingEdge = z.infer<
  * 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.
+ *
+ * `unresolvedManagers` is the batch's honesty channel: a supervisory reference
+ * the adapter could not resolve is REPORTED here rather than dropped, so the
+ * count of observed seats minus placed edges is fully explained.
  */
 export const CanonicalFactsSchema = z.object({
   /** Every person observed in this batch. */
@@ -177,5 +268,7 @@ export const CanonicalFactsSchema = z.object({
   occupancies: z.array(CanonicalOccupancySchema),
   /** Every seat-to-manager-seat reporting edge observed in this batch. */
   reportingEdges: z.array(CanonicalReportingEdgeSchema),
+  /** Every supervisory reference this batch could NOT resolve to a seat. */
+  unresolvedManagers: z.array(CanonicalUnresolvedManagerSchema),
 });
 export type CanonicalFacts = z.infer<typeof CanonicalFactsSchema>;

package/src/org/index.ts

@@ -208,20 +208,74 @@ export type {
 export {
   CanonicalPersonSchema,
   CanonicalOrgUnitSchema,
+  CanonicalPositionStatusSchema,
   CanonicalPositionSchema,
   CanonicalOccupancySchema,
   CanonicalReportingEdgeSchema,
+  CanonicalUnresolvedManagerResolutionSchema,
+  CanonicalUnresolvedManagerSchema,
   CanonicalFactsSchema,
 } from "./canonical-facts";
 export type {
   CanonicalPerson,
   CanonicalOrgUnit,
+  CanonicalPositionStatus,
   CanonicalPosition,
   CanonicalOccupancy,
   CanonicalReportingEdge,
+  CanonicalUnresolvedManagerResolution,
+  CanonicalUnresolvedManager,
   CanonicalFacts,
 } from "./canonical-facts";
 
+// Org-structure inference: the snapshot the engine reasons over and the
+// proposed desired state it returns. Evidence is TYPED so the validator can
+// enforce boundary and naming rules mechanically; a proposed unit carries
+// targetUnitId so a rename preserves durable identity; every person in the
+// snapshot receives exactly one outcome. (PRD-00955)
+//
+// Accepted structural facts additionally carry StructureProvenance: three
+// ORTHOGONAL axes — proposalOrigin, acceptedBy and authority — so that clicking
+// Apply on an AI proposal makes it human_confirmed without making its origin
+// manual. Precedence runs on `authority` alone, via mayOverrideAuthority.
+// (PRD-00956)
+export {
+  StructureEvidenceSchema,
+  TOPOLOGY_ONLY_EVIDENCE_KINDS,
+  StructureUnitAuthoritySchema,
+  StructureProposalOriginSchema,
+  StructureAcceptedBySchema,
+  StructureAuthoritySchema,
+  StructureProvenanceSchema,
+  mayOverrideAuthority,
+  ProposedOrgUnitSchema,
+  PersonStructureOutcomeSchema,
+  StructureReviewItemSchema,
+  StructureProposalSchema,
+  StructurePersonFactSchema,
+  StructureReportingFactSchema,
+  ExistingUnitFactSchema,
+  ExistingPlacementFactSchema,
+  StructureInferenceSnapshotSchema,
+} from "./structure-inference";
+export type {
+  StructureEvidence,
+  StructureUnitAuthority,
+  StructureProposalOrigin,
+  StructureAcceptedBy,
+  StructureAuthority,
+  StructureProvenance,
+  ProposedOrgUnit,
+  PersonStructureOutcome,
+  StructureReviewItem,
+  StructureProposal,
+  StructurePersonFact,
+  StructureReportingFact,
+  ExistingUnitFact,
+  ExistingPlacementFact,
+  StructureInferenceSnapshot,
+} from "./structure-inference";
+
 // Canonical OrgUnit tree ordering (PRD-00506)
 export type { TreeOrderableNode } from "./tree-ordering";
 export { orderTreeNodes } from "./tree-ordering";

package/src/org/schemas.ts

@@ -1192,6 +1192,29 @@ export type UpdateInviteBatchRequest = z.infer<
  */
 export const SendInviteBatchRequestSchema = z.object({
   expectedRevision: z.number().int().nonnegative(),
+  /**
+   * The reviewer's optional note, carried into every invitation this send mails
+   * and attributed to the inviter (`NotificationPayloads['org.invite'].message`).
+   *
+   * It rides the SEND rather than the batch on purpose: it authorizes nothing,
+   * so it has no business bumping a revision that every open review reads as
+   * "read this again". Not persisted — the invitation is the only thing that
+   * ever carries it.
+   */
+  message: z.string().max(2000).optional(),
+  /**
+   * Per-person role overrides, keyed by `personId` — the reviewer set a role for
+   * ONE recipient rather than for the batch.
+   *
+   * The batch's own `role` remains what everyone else is invited as; a key here
+   * replaces it for that person only. A key naming somebody outside the batch,
+   * or somebody it is no longer sending to, is INERT rather than an error: the
+   * live directory re-check at send time already decides who is mailed, and a
+   * stale override describes a person nobody is inviting.
+   */
+  roleByPersonId: z
+    .record(z.string().uuid(), z.enum(["admin", "member"]))
+    .optional(),
 });
 
 export type SendInviteBatchRequest = z.infer<