@company-semantics/contracts 57.0.0 → 58.1.0

package/src/org/structure-inference.ts

@@ -0,0 +1,521 @@
+/**
+ * Org-structure inference vocabulary — the snapshot in, the proposal out.
+ *
+ * HRIS gives us a department STRING and a reporting graph. Neither one IS the
+ * org-unit tree. This module is the frozen vocabulary for the engine that
+ * reconciles them: a {@link StructureInferenceSnapshotSchema} of the persisted
+ * canonical graph goes in, and a {@link StructureProposalSchema} — a proposed
+ * DESIRED STATE, never a list of database commands — comes out.
+ *
+ * The four terms of the surrounding model are distinct and must stay distinct
+ * here, in the tables and in UI copy:
+ *
+ *  - SOURCE FACT — what the HRIS said ({@link CanonicalFactsSchema}).
+ *  - INFERENCE PROPOSAL — what the reasoning system thinks it means (this file).
+ *  - ACCEPTED ORGANIZATIONAL FACT — what the product considers the org to be.
+ *  - DRIFT FINDING — evidence that a later sync no longer agrees.
+ *
+ * Four decisions are load-bearing and are encoded in the types, not in prose:
+ *
+ *  1. Evidence is TYPED ({@link StructureEvidenceSchema}). A validator cannot
+ *     enforce "this unit is not supported by reporting topology alone" against
+ *     the free-text string "several employees have similar roles"; it can
+ *     enforce it against a discriminated union plus
+ *     {@link TOPOLOGY_ONLY_EVIDENCE_KINDS}.
+ *  2. A proposed unit carries `targetUnitId`. Present means "preserve that
+ *     durable identity"; null means "create". Without it the very first run
+ *     that renames `Human Resources` to `People` creates a SECOND unit beside
+ *     the first and orphans a doc-owning one.
+ *  3. Every person in the snapshot gets EXACTLY ONE outcome — placed,
+ *     needs_review or excluded. "Zero or one placement" would accept a proposal
+ *     that silently forgets three people, which is the same silent-omission
+ *     failure class this whole effort exists because of.
+ *  4. People and units are referenced ONLY by the opaque ids the snapshot
+ *     supplied. Names are display-only and never identifiers — two records with
+ *     no characters in common can be the same person (a legal name and a
+ *     preferred name), so no fuzzy name match can be trusted.
+ *
+ * WHY THIS IS NOT `structure-facts.ts` PROVENANCE. Every other org fact carries
+ * a {@link FactProvenanceSchema} envelope (tier / source / confidence / locked /
+ * supersedesFactId). A proposal deliberately carries none: it is a CANDIDATE,
+ * not a recorded fact, and it has not entered the truth hierarchy at all.
+ * Provenance attaches when a human accepts it.
+ *
+ * WHY {@link StructureUnitAuthoritySchema} IS NOT {@link FactSourceTierSchema}.
+ * The tier axis (`user` > `sync` > `import` > `inferred`) answers "which writer
+ * wins when two facts collide". The authority axis here answers a different
+ * question the model must be told the answer to: "may you reorganize this unit?"
+ * `human_confirmed` is an ANCHOR the model must leave alone and disagree with
+ * out loud; `hris_source` is imported evidence it may reorganize. Collapsing the
+ * two axes would make `inferred` mean both "loses a write race" and "safe to
+ * rearrange", which are not the same claim.
+ *
+ * PROVENANCE IS THREE AXES, NOT ONE LADDER. When a proposal is ACCEPTED it
+ * records {@link StructureProvenanceSchema}: `proposalOrigin` (how it came to be
+ * proposed), `acceptedBy` (who signed off) and `authority` (what it may now
+ * overwrite). Only the third drives precedence, via
+ * {@link mayOverrideAuthority}. Clicking Apply on an AI proposal makes it
+ * `human_confirmed` without making its origin `manual` — collapsing those is
+ * what makes an AI guess indistinguishable from a human decision today.
+ *
+ * NOT TO BE CONFUSED WITH `reasoning-review.ts`. That module
+ * (`OrgStructureReviewInference`, `OrgStructureReviewQueue`, ADR-CONT-095 /
+ * ADR-BE-345) is the OLDER reasoning-lens review queue, backed by
+ * `org_structure_inferences`, which can express only two mutations: re-parent an
+ * existing unit and rename a seat title. This vocabulary is a SEPARATE seam
+ * backed by `org_structure_proposals`, and it describes a whole desired state.
+ * Neither replaces the other in this release.
+ */
+import { z } from "zod";
+
+import { PositionReportingRelationshipTypeSchema } from "./position-reporting";
+
+// ---------------------------------------------------------------------------
+// StructureEvidence — typed support for a boundary, a name or a placement
+// ---------------------------------------------------------------------------
+
+/**
+ * TYPED evidence. Prose evidence cannot be validated; a discriminated union can.
+ * The validator reads these `kind`s directly to enforce "a proposed unit must
+ * have at least one boundary signal that is not reporting topology" and "a name
+ * may not carry specificity absent from its `nameBasis`".
+ */
+export const StructureEvidenceSchema = z.discriminatedUnion("kind", [
+  /** The source stated a department outright for these people. */
+  z.object({
+    kind: z.literal("explicit_department"),
+    personIds: z.array(z.string()),
+    value: z.string(),
+  }),
+  /** The source stated a division outright for these people. */
+  z.object({
+    kind: z.literal("explicit_division"),
+    personIds: z.array(z.string()),
+    value: z.string(),
+  }),
+  /** A title cluster. Role families cut ACROSS reporting lines on purpose. */
+  z.object({
+    kind: z.literal("role_family"),
+    family: z.string(),
+    personIds: z.array(z.string()),
+    count: z.number().int(),
+  }),
+  /** A C-level / VP seat that anchors a function. */
+  z.object({
+    kind: z.literal("functional_leader"),
+    personId: z.string(),
+    function: z.string(),
+  }),
+  /** Manager topology. Alone this is NEVER enough — see the const below. */
+  z.object({
+    kind: z.literal("reporting_cluster"),
+    managerPersonId: z.string(),
+    personIds: z.array(z.string()),
+  }),
+  /**
+   * A manager whose reports span many functions — an administrative supervisor
+   * rather than a unit boundary. Recorded so a proposal can explain why it did
+   * NOT draw a unit around that seat.
+   */
+  z.object({
+    kind: z.literal("administrative_pivot"),
+    personId: z.string(),
+    departmentEntropy: z.number(),
+  }),
+  /** A concept from a controlled ontology rather than from this org's data. */
+  z.object({
+    kind: z.literal("controlled_ontology"),
+    concept: z.string(),
+  }),
+]);
+export type StructureEvidence = z.infer<typeof StructureEvidenceSchema>;
+
+/**
+ * Evidence kinds that alone are NOT sufficient to justify a unit boundary.
+ *
+ * On the reference org, 17 of 19 cross-department placements route through two
+ * `Sr. HR Administrator` seats whose reports span seven departments each.
+ * Deriving units from reporting topology puts the entire company inside one
+ * unit — so a unit whose only support is `reporting_cluster` is rejected.
+ */
+export const TOPOLOGY_ONLY_EVIDENCE_KINDS = [
+  "reporting_cluster",
+] as const satisfies ReadonlyArray<StructureEvidence["kind"]>;
+
+// ---------------------------------------------------------------------------
+// StructureUnitAuthority — may the model reorganize this existing unit?
+// ---------------------------------------------------------------------------
+
+/**
+ * How much license the engine has over an EXISTING unit or placement. See the
+ * file header for why this is a separate axis from {@link FactSourceTierSchema}.
+ *
+ * This is the authority axis of {@link StructureProvenanceSchema} read from the
+ * proposal side; {@link StructureAuthoritySchema} is the SAME schema object read
+ * from the apply side. One ladder, and exactly one meaning per rung:
+ *
+ *  - `human_confirmed` — a PERSON signed off, whether by editing structure
+ *    directly or by accepting an AI proposal. An anchor: never renamed,
+ *    reparented or replaced by inference; a disagreement is surfaced for review
+ *    instead.
+ *  - `ai_inferred` — accepted with nobody in the loop, i.e. `acceptedBy` is
+ *    `system_policy` (calibrated auto-accept); may be revisited. An AI proposal
+ *    a human clicked Apply on is NOT this — it is `human_confirmed`, and the
+ *    fact that an AI proposed it survives in `proposalOrigin`, not here. Writing
+ *    a human-accepted fact as `ai_inferred` would make it reorganizable and
+ *    overwritable by the next AI guess, which is the defect this vocabulary
+ *    exists to close.
+ *  - `hris_source` — imported source evidence the feed accepted for itself; may
+ *    be reorganized when stronger functional evidence supports it.
+ */
+export const StructureUnitAuthoritySchema = z.enum([
+  "human_confirmed",
+  "ai_inferred",
+  "hris_source",
+]);
+export type StructureUnitAuthority = z.infer<
+  typeof StructureUnitAuthoritySchema
+>;
+
+// ---------------------------------------------------------------------------
+// StructureProvenance — three orthogonal axes: origin, acceptor, authority
+// ---------------------------------------------------------------------------
+
+/**
+ * How a structural fact came to be PROPOSED. Orthogonal to who accepted it and
+ * to how much authority it now carries.
+ *
+ * Accepting an AI proposal must not rewrite its origin as `manual`. The moment
+ * it does, an AI guess and a human decision become indistinguishable in the
+ * record — which is exactly the defect being fixed: today both land as
+ * `source_authority.system_of_record = 'user_override'`, nothing downstream can
+ * tell them apart, and nothing ever deletes such a row, so the guess is
+ * permanent AND wears the costume of intent. Nothing is recorded as
+ * `user_override` again.
+ */
+export const StructureProposalOriginSchema = z.enum([
+  "ai_inference",
+  "hris_source",
+  "manual",
+]);
+export type StructureProposalOrigin = z.infer<
+  typeof StructureProposalOriginSchema
+>;
+
+/**
+ * WHO accepted the fact. A discriminated union rather than a nullable `userId`,
+ * because "nobody" and "a policy decided" are different claims, and only the
+ * second one is an answer when someone asks who signed off. A null would let
+ * an unattributed write and an automated one share a representation.
+ */
+export const StructureAcceptedBySchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("user"), userId: z.string().uuid() }),
+  z.object({ kind: z.literal("system_policy") }),
+]);
+export type StructureAcceptedBy = z.infer<typeof StructureAcceptedBySchema>;
+
+/**
+ * The authority axis — the ONLY axis precedence runs on:
+ * `human_confirmed` > `ai_inferred` > `hris_source`.
+ *
+ * Deliberately the same vocabulary as {@link StructureUnitAuthoritySchema}, and
+ * deliberately the same schema object rather than a second identically-valued
+ * enum beside it. "May the model reorganize this unit?" and "may this write
+ * overwrite that fact?" are two readings of ONE ladder; two copies of it would
+ * drift, and a proposal-time answer that disagreed with the apply-time answer is
+ * precisely the class of bug this vocabulary exists to make impossible.
+ */
+export const StructureAuthoritySchema = StructureUnitAuthoritySchema;
+export type StructureAuthority = StructureUnitAuthority;
+
+/**
+ * Highest wins. Private on purpose: callers ask {@link mayOverrideAuthority}
+ * instead of comparing numbers, so the ordering has exactly one definition and
+ * adding a member to the enum is a compile error here rather than a silent tie.
+ */
+const AUTHORITY_RANK: Record<StructureAuthority, number> = {
+  human_confirmed: 3,
+  ai_inferred: 2,
+  hris_source: 1,
+};
+
+/**
+ * True when `incoming` may overwrite a fact currently held at `existing`.
+ *
+ * Equal authority overwrites: a later HRIS sync must be able to correct an
+ * earlier one, and a second human decision must be able to revise the first.
+ * A strict `>` would freeze the first write of every field forever.
+ */
+export function mayOverrideAuthority(
+  incoming: StructureAuthority,
+  existing: StructureAuthority,
+): boolean {
+  return AUTHORITY_RANK[incoming] >= AUTHORITY_RANK[existing];
+}
+
+/**
+ * The three axes together, as one accepted structural fact records them.
+ *
+ *  - v1 — AI proposes, an admin clicks Apply:
+ *    `ai_inference` / `user` / `human_confirmed`.
+ *  - Later — calibrated auto-accept:
+ *    `ai_inference` / `system_policy` / `ai_inferred`.
+ *  - An admin edits structure directly:
+ *    `manual` / `user` / `human_confirmed`.
+ *  - The feed said so:
+ *    `hris_source` / `system_policy` / `hris_source`.
+ *
+ * Read the `authority` column alone and you have precedence. Read a row across
+ * and acceptance has not erased how the fact originated — which is the whole
+ * reason these are three fields and not one.
+ */
+export const StructureProvenanceSchema = z.object({
+  proposalOrigin: StructureProposalOriginSchema,
+  acceptedBy: StructureAcceptedBySchema,
+  authority: StructureAuthoritySchema,
+});
+export type StructureProvenance = z.infer<typeof StructureProvenanceSchema>;
+
+// ---------------------------------------------------------------------------
+// ProposedOrgUnit — one node of the proposed desired state
+// ---------------------------------------------------------------------------
+
+/**
+ * A unit the proposal wants the org to have. `tempId` is proposal-scoped
+ * plumbing; `targetUnitId` is the only durable identity in this record.
+ */
+export const ProposedOrgUnitSchema = z.object({
+  /** Proposal-scoped handle. NOT the durable identity. */
+  tempId: z.string().min(1),
+  /**
+   * Present => this proposal IS an existing durable unit; preserve its id, its
+   * Company.md doc, its history and its permissions. Null => create a new
+   * durable unit on acceptance.
+   *
+   * Without this, renaming `Human Resources` to `People` creates a second unit
+   * and orphans the first. A unit's durable identity is never derived from its
+   * name and never from its leader — when a team lead leaves it is still the
+   * same team.
+   */
+  targetUnitId: z.string().uuid().nullable(),
+  /** Certainty in [0,1] that `targetUnitId` really is this unit. */
+  identityConfidence: z.number().min(0).max(1),
+  /** Typed support for the identity claim above. */
+  identityEvidence: z.array(StructureEvidenceSchema),
+  /** Human-facing unit name. Display only; never an identifier. */
+  name: z.string().min(1),
+  /** Typed support for the NAME specifically — the anti-invention check. */
+  nameBasis: z.array(StructureEvidenceSchema),
+  /** `tempId` of the parent unit; `null` for the proposed root. */
+  parentTempId: z.string().nullable(),
+  /** Free-text level label (e.g. `Department`, `Team`); advisory only. */
+  suggestedTypeLabel: z.string(),
+  /** Opaque person id of the unit's head; `null` when unknown. */
+  headPersonId: z.string().nullable(),
+  /** Certainty in [0,1] that the NAME is right. */
+  nameConfidence: z.number().min(0).max(1),
+  /** Certainty in [0,1] that the BOUNDARY is right. */
+  structureConfidence: z.number().min(0).max(1),
+  /** A leader-derived placeholder label the user is expected to rename. */
+  provisional: z.boolean(),
+  /** Typed support for the BOUNDARY — what the topology-only rule reads. */
+  evidence: z.array(StructureEvidenceSchema),
+});
+export type ProposedOrgUnit = z.infer<typeof ProposedOrgUnitSchema>;
+
+// ---------------------------------------------------------------------------
+// PersonStructureOutcome — exactly one per person in the snapshot
+// ---------------------------------------------------------------------------
+
+/**
+ * EXACTLY ONE outcome per person in the snapshot.
+ *
+ * "Zero or one placement" would accept a proposal that simply forgets three
+ * people — the same silent-omission failure that dropped people out of the
+ * reporting tree while the sync reported a clean run. A person the engine
+ * cannot place returns `needs_review` with a reason; never a guess, and never
+ * an absence.
+ */
+export const PersonStructureOutcomeSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("placed"),
+    personId: z.string(),
+    /** `tempId` of the unit this person is placed in. */
+    unitTempId: z.string(),
+    confidence: z.number().min(0).max(1),
+    evidence: z.array(StructureEvidenceSchema),
+    /** Signals that disagreed with this placement, stated not suppressed. */
+    conflicts: z.array(z.string()),
+  }),
+  z.object({
+    kind: z.literal("needs_review"),
+    personId: z.string(),
+    reason: z.enum([
+      "insufficient_evidence",
+      "conflicting_evidence",
+      "ambiguous_boundary",
+    ]),
+  }),
+  z.object({
+    kind: z.literal("excluded"),
+    personId: z.string(),
+    reason: z.enum(["service_account", "not_workforce", "inactive"]),
+  }),
+]);
+export type PersonStructureOutcome = z.infer<
+  typeof PersonStructureOutcomeSchema
+>;
+
+// ---------------------------------------------------------------------------
+// StructureReviewItem — a decision boundary, not merely a low number
+// ---------------------------------------------------------------------------
+
+/**
+ * A question the engine is asking a human, with the competing signals attached.
+ *
+ * A low confidence number is not a review item. A review item is a genuine
+ * decision boundary: an engine that confidently places an ambiguous person and
+ * never asks scores well on placement accuracy while being WORSE for the
+ * product than one that reports three signals disagreeing.
+ */
+export const StructureReviewItemSchema = z.object({
+  kind: z.enum([
+    "placement_conflict",
+    "unit_boundary",
+    "unit_name",
+    "unit_head",
+  ]),
+  /** Opaque person ids this question is about. */
+  personIds: z.array(z.string()),
+  /** Proposal-scoped unit handles this question is about. */
+  unitTempIds: z.array(z.string()),
+  /** The question, phrased for a human reviewer. */
+  question: z.string(),
+  /** What the engine would do absent an answer. */
+  recommended: z.string(),
+  /** The other defensible answers. */
+  alternatives: z.array(z.string()),
+  /** The competing signals, so a reviewer can see WHY it is ambiguous. */
+  signals: z.record(z.string(), z.string()),
+  confidence: z.number().min(0).max(1),
+  evidence: z.array(StructureEvidenceSchema),
+});
+export type StructureReviewItem = z.infer<typeof StructureReviewItemSchema>;
+
+// ---------------------------------------------------------------------------
+// StructureProposal — the proposed desired state
+// ---------------------------------------------------------------------------
+
+/**
+ * A proposed desired state for one org. Not database commands, not an applied
+ * change: acceptance is a separate, human step.
+ */
+export const StructureProposalSchema = z.object({
+  orgId: z.string().uuid(),
+  /** Lineage only. Staleness is decided by `inputHash`, not by this. */
+  sourceSnapshotId: z.string(),
+  /** The org-graph revision this proposal reasoned about. */
+  structureRevision: z.string(),
+  /** Hash of the NORMALIZED inference inputs — the staleness key. */
+  inputHash: z.string(),
+  /** Registry version of the prompt that produced this proposal. */
+  promptVersion: z.string(),
+  orgUnits: z.array(ProposedOrgUnitSchema),
+  personOutcomes: z.array(PersonStructureOutcomeSchema),
+  /** Things the engine noticed but could not express as a review item. */
+  structureWarnings: z.array(z.string()),
+  reviewItems: z.array(StructureReviewItemSchema),
+});
+export type StructureProposal = z.infer<typeof StructureProposalSchema>;
+
+// ---------------------------------------------------------------------------
+// StructureInferenceSnapshot — the inference INPUT, taken from the graph
+// ---------------------------------------------------------------------------
+
+/**
+ * A person as the inference engine sees them. `personId` is the opaque internal
+ * id and the ONLY handle a proposal may return; `sourcePersonId` is retained
+ * for diagnostics and is stripped before the snapshot reaches the model, because
+ * keeping provider identity out of the reasoning layer is the point.
+ */
+export const StructurePersonFactSchema = z.object({
+  /** Opaque internal id. The only handle a proposal may reference. */
+  personId: z.string().min(1),
+  /** Diagnostics only — stripped from the model-facing snapshot. */
+  sourcePersonId: z.string().min(1).nullable().optional(),
+  /** Display only. Never an identifier, never fuzzy-matched. */
+  displayName: z.string(),
+  title: z.string().nullable(),
+  department: z.string().nullable(),
+  division: z.string().nullable(),
+  location: z.string().nullable(),
+  managerPersonId: z.string().nullable(),
+  directReportPersonIds: z.array(z.string()),
+});
+export type StructurePersonFact = z.infer<typeof StructurePersonFactSchema>;
+
+/**
+ * One reporting edge, at person granularity. Reporting is a SEPARATE axis: a
+ * proposal must never rewrite one, and the validator proves it did not by
+ * comparing against these.
+ */
+export const StructureReportingFactSchema = z.object({
+  reportPersonId: z.string().min(1),
+  managerPersonId: z.string().min(1),
+  relationshipType: PositionReportingRelationshipTypeSchema,
+});
+export type StructureReportingFact = z.infer<
+  typeof StructureReportingFactSchema
+>;
+
+/** An org unit that already exists, with the license the engine has over it. */
+export const ExistingUnitFactSchema = z.object({
+  unitId: z.string().uuid(),
+  name: z.string(),
+  parentUnitId: z.string().uuid().nullable(),
+  depth: z.number().int(),
+  /**
+   * Anchor vs reorganizable. This is the `authority` axis of the accepted
+   * fact's {@link StructureProvenanceSchema}, copied through unchanged — a unit
+   * a human accepted is `human_confirmed` here even when an AI proposed it.
+   */
+  authority: StructureUnitAuthoritySchema,
+});
+export type ExistingUnitFact = z.infer<typeof ExistingUnitFactSchema>;
+
+/** Where a person already sits, and on whose authority they sit there. */
+export const ExistingPlacementFactSchema = z.object({
+  personId: z.string().min(1),
+  unitId: z.string().uuid(),
+  /** The accepted fact's `authority` axis — see {@link ExistingUnitFactSchema}. */
+  authority: StructureUnitAuthoritySchema,
+});
+export type ExistingPlacementFact = z.infer<typeof ExistingPlacementFactSchema>;
+
+/**
+ * The inference INPUT: a point-in-time view of the PERSISTED canonical graph.
+ *
+ * Never a {@link CanonicalFactsSchema} batch. Internal ids are already resolved
+ * here, duplicates already reconciled, provenance already attached — and a delta
+ * batch is a partial workforce, on which inference is meaningless.
+ *
+ * Derived heuristic signals (role families, functional leaders, administrative
+ * pivot candidates, department outliers) are deliberately NOT part of this
+ * contract. They are an engine-local enrichment layered on top by the extractor;
+ * they are tuning knobs that will change without a coordinated release, so they
+ * fail the promotion rule that governs this package. What is frozen here is the
+ * FACTS the engine reasons over and the ids a proposal may reference.
+ */
+export const StructureInferenceSnapshotSchema = z.object({
+  orgId: z.string().uuid(),
+  /** Lineage only. Staleness is decided by the hash of these inputs. */
+  sourceSnapshotId: z.string(),
+  structureRevision: z.string(),
+  persons: z.array(StructurePersonFactSchema),
+  reporting: z.array(StructureReportingFactSchema),
+  existingUnits: z.array(ExistingUnitFactSchema),
+  existingPlacements: z.array(ExistingPlacementFactSchema),
+});
+export type StructureInferenceSnapshot = z.infer<
+  typeof StructureInferenceSnapshotSchema
+>;