@company-semantics/contracts 58.0.0 → 58.2.0

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<