@company-semantics/contracts 27.2.0 → 27.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "27.2.0",
+  "version": "27.3.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/index.ts

@@ -438,6 +438,32 @@ export type {
   OrgStructureInferenceDecisionResult,
 } from "./org/index";
 
+// Org transformation wire vocabulary: intent -> simulation -> preview. The
+// engine turns a TransformationRequest into scored mutation bundles and returns
+// a TransformationPreview the operator confirms before apply. (ADR-CONTRACTS-072)
+export {
+  OrgIntentSchema,
+  FactMutationSchema,
+  TransformationOriginSchema,
+  TransformationRequestSchema,
+  ConstraintViolationSchema,
+  RecommendationSchema,
+  TransformStrategySchema,
+  SelectionRationaleSchema,
+  TransformationPreviewSchema,
+} from "./org/index";
+export type {
+  OrgIntent,
+  FactMutation,
+  TransformationOrigin,
+  TransformationRequest,
+  ConstraintViolation,
+  Recommendation,
+  TransformStrategy,
+  SelectionRationale,
+  TransformationPreview,
+} from "./org/index";
+
 // Canonical facts: the adapter-seam ingestion batch — external-keyed Canonical*
 // facts (each with provenance) plus a CanonicalFacts envelope. The reconciler
 // consumes the batch into the internal org graph. (ADR-CONT-085 / ADR-CTRL-183)

package/src/org/README.md

@@ -74,6 +74,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `CompanyMdVisibility` _(type)_ — Visibility band for a Company.md document — the canonical AUTH `entity_visibility` vocabulary (, backend ). -…
 - `ConflictRecord` _(type)_
 - `ConflictRecordSchema`
+- `ConstraintViolation` _(type)_
+- `ConstraintViolationSchema` — One constraint the transformation engine evaluated and found violated.
 - `CreateDelegationRequest` _(type)_
 - `CreateDelegationRequestSchema`
 - `CreateInviteRequest` _(type)_ — Request payload for creating an organization invite.
@@ -95,6 +97,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `EvaluationStep` _(type)_ — Single step in the access evaluation trace.
 - `ExecutionScope` _(type)_ — Execution scope determines whose identity is used when executing actions. - 'self': Actions execute under the…
 - `FACT_SOURCE_TIER_PRECEDENCE` — Truth hierarchy, highest precedence first.
+- `FactMutation` _(type)_
+- `FactMutationSchema` — A single atomic fact change the engine applies to the live org graph.
 - `FactProvenance` _(type)_
 - `FactProvenanceSchema` — Provenance envelope attached to a structural fact (reporting edge, org unit, membership, home assignment).
 - `FactSourceTier` _(type)_
@@ -148,6 +152,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `OrgDeletionStatus` _(type)_
 - `OrgDeletionStatusSchema`
 - `OrgDomain` _(type)_ — Organization domain claim and verification status.
+- `OrgIntent` _(type)_
+- `OrgIntentSchema` — A requested org-graph change expressed as intent.
 - `OrgInvite` _(type)_ — Organization invite for the workspace invites list.
 - `OrgInviteStatus` _(type)_ — Status of an organization invite.
 - `OrgLevelConfig` _(type)_
@@ -242,6 +248,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `PositionStatusSchema` — Lifecycle of a seat's EXISTENCE — distinct from a hiring pipeline.
 - `ProviderStatus` _(type)_ — Provider-level configuration lifecycle.
 - `ProviderSuggestion` _(type)_ — MX-based provider suggestion for SSO setup.
+- `Recommendation` _(type)_
+- `RecommendationSchema`
 - `RemoveMemberRequest` _(type)_ — Request payload for removing a member from the workspace.
 - `RemoveMemberResponse` _(type)_
 - `RemoveMemberResponseSchema`
@@ -252,6 +260,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `ScopeCheckBatchResponseSchema`
 - `ScopeCheckResponse` _(type)_
 - `ScopeCheckResponseSchema`
+- `SelectionRationale` _(type)_
+- `SelectionRationaleSchema`
 - `SetActiveOrgResponse` _(type)_
 - `SetActiveOrgResponseSchema`
 - `SetMemberManagerResponse` _(type)_
@@ -287,6 +297,14 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `TransferMemberEligibility` _(type)_ — Per-member eligibility for transfer recipient picker
 - `TransferResponsibility` _(type)_
 - `TransferStatusResponse` _(type)_ — Response for transfer status queries — extends existing OwnershipTransferStatus.
+- `TransformStrategy` _(type)_
+- `TransformStrategySchema`
+- `TransformationOrigin` _(type)_
+- `TransformationOriginSchema` — Where a transformation originated.
+- `TransformationPreview` _(type)_
+- `TransformationPreviewSchema`
+- `TransformationRequest` _(type)_
+- `TransformationRequestSchema`
 - `TreeOrderableNode` _(type)_ — Canonical per-parent sibling ordering for OrgUnit trees.
 - `UnitMembershipRole` _(type)_
 - `UnitMembershipRoleSchema` — Positional slot a member holds in the org-unit tree.

package/src/org/__tests__/transformation.test.ts

@@ -0,0 +1,273 @@
+import { describe, it, expect } from "vitest";
+import {
+  OrgIntentSchema,
+  FactMutationSchema,
+  TransformationOriginSchema,
+  TransformationRequestSchema,
+  ConstraintViolationSchema,
+  RecommendationSchema,
+  TransformStrategySchema,
+  SelectionRationaleSchema,
+  TransformationPreviewSchema,
+} from "../transformation.js";
+
+const REPORT = "33333333-3333-4333-8333-333333333333";
+const MANAGER = "44444444-4444-4444-8444-444444444444";
+
+const setManagerIntent = {
+  kind: "reporting.setManager" as const,
+  reportPositionId: REPORT,
+  managerPositionId: MANAGER,
+};
+
+const setManagerMutation = {
+  kind: "reporting.setManager" as const,
+  reportPositionId: REPORT,
+  managerPositionId: MANAGER,
+};
+
+describe("OrgIntentSchema", () => {
+  it("accepts a reporting.setManager intent", () => {
+    expect(OrgIntentSchema.parse(setManagerIntent)).toEqual(setManagerIntent);
+  });
+
+  it("rejects an unknown intent kind", () => {
+    expect(
+      OrgIntentSchema.safeParse({ ...setManagerIntent, kind: "home.setUnit" })
+        .success,
+    ).toBe(false);
+  });
+
+  it("rejects a non-uuid reportPositionId", () => {
+    expect(
+      OrgIntentSchema.safeParse({ ...setManagerIntent, reportPositionId: "x" })
+        .success,
+    ).toBe(false);
+  });
+
+  it("rejects a null managerPositionId (intents always set a manager)", () => {
+    expect(
+      OrgIntentSchema.safeParse({
+        ...setManagerIntent,
+        managerPositionId: null,
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("FactMutationSchema", () => {
+  it("accepts a reporting.setManager mutation", () => {
+    expect(FactMutationSchema.parse(setManagerMutation)).toEqual(
+      setManagerMutation,
+    );
+  });
+
+  it("accepts a null managerPositionId (un-setting the manager edge)", () => {
+    expect(
+      FactMutationSchema.safeParse({
+        ...setManagerMutation,
+        managerPositionId: null,
+      }).success,
+    ).toBe(true);
+  });
+
+  it("rejects an unknown mutation kind", () => {
+    expect(
+      FactMutationSchema.safeParse({ ...setManagerMutation, kind: "unit.move" })
+        .success,
+    ).toBe(false);
+  });
+});
+
+describe("TransformationOriginSchema", () => {
+  it("accepts each known origin", () => {
+    for (const origin of [
+      "user_intent",
+      "business_event",
+      "external_observation",
+    ]) {
+      expect(TransformationOriginSchema.safeParse(origin).success).toBe(true);
+    }
+  });
+
+  it("rejects an unknown origin", () => {
+    expect(TransformationOriginSchema.safeParse("system").success).toBe(false);
+  });
+});
+
+describe("TransformationRequestSchema", () => {
+  const request = {
+    origin: "user_intent" as const,
+    intent: setManagerIntent,
+    reason: "New manager after team merge",
+  };
+
+  it("accepts a full request", () => {
+    expect(TransformationRequestSchema.parse(request)).toEqual(request);
+  });
+
+  it("accepts a request without a reason", () => {
+    const { reason: _omit, ...noReason } = request;
+    expect(TransformationRequestSchema.safeParse(noReason).success).toBe(true);
+  });
+
+  it("rejects a reason longer than 2000 chars", () => {
+    expect(
+      TransformationRequestSchema.safeParse({
+        ...request,
+        reason: "x".repeat(2001),
+      }).success,
+    ).toBe(false);
+  });
+
+  it("rejects an unknown origin", () => {
+    expect(
+      TransformationRequestSchema.safeParse({ ...request, origin: "robot" })
+        .success,
+    ).toBe(false);
+  });
+});
+
+describe("ConstraintViolationSchema", () => {
+  it("accepts an error violation with a subject", () => {
+    expect(
+      ConstraintViolationSchema.parse({
+        code: "reporting.cycle",
+        severity: "error",
+        subject: REPORT,
+      }),
+    ).toEqual({ code: "reporting.cycle", severity: "error", subject: REPORT });
+  });
+
+  it("accepts a warning without a subject", () => {
+    expect(
+      ConstraintViolationSchema.safeParse({
+        code: "span.wide",
+        severity: "warning",
+      }).success,
+    ).toBe(true);
+  });
+
+  it("rejects an unknown severity", () => {
+    expect(
+      ConstraintViolationSchema.safeParse({ code: "c", severity: "fatal" })
+        .success,
+    ).toBe(false);
+  });
+});
+
+describe("RecommendationSchema / TransformStrategySchema", () => {
+  const recommendation = {
+    label: "Reassign report",
+    mutations: [setManagerMutation],
+    cost: 1,
+    explanation: ["Direct edge rewrite", "No descendants affected"],
+  };
+
+  it("accepts a recommendation without a warning", () => {
+    expect(RecommendationSchema.parse(recommendation)).toEqual(recommendation);
+  });
+
+  it("accepts a recommendation with a warning", () => {
+    expect(
+      RecommendationSchema.safeParse({
+        ...recommendation,
+        warning: "Crosses a department boundary",
+      }).success,
+    ).toBe(true);
+  });
+
+  it("accepts a strategy wrapping recommendations", () => {
+    expect(
+      TransformStrategySchema.parse({
+        recommendations: [recommendation],
+        totalCost: 1,
+        warnings: [],
+      }).recommendations,
+    ).toHaveLength(1);
+  });
+
+  it("rejects a recommendation with a non-array explanation", () => {
+    expect(
+      RecommendationSchema.safeParse({ ...recommendation, explanation: "one" })
+        .success,
+    ).toBe(false);
+  });
+});
+
+describe("SelectionRationaleSchema", () => {
+  it("accepts chosen reasons and rejected alternatives", () => {
+    const rationale = {
+      chosen: ["Lowest cost"],
+      rejectedAlternatives: [
+        {
+          label: "Restructure subtree",
+          reasons: ["Higher cost", "Wider span"],
+        },
+      ],
+    };
+    expect(SelectionRationaleSchema.parse(rationale)).toEqual(rationale);
+  });
+
+  it("accepts an empty rejected-alternatives list", () => {
+    expect(
+      SelectionRationaleSchema.safeParse({
+        chosen: ["Only option"],
+        rejectedAlternatives: [],
+      }).success,
+    ).toBe(true);
+  });
+});
+
+describe("TransformationPreviewSchema", () => {
+  const strategy = {
+    recommendations: [
+      {
+        label: "Reassign report",
+        mutations: [setManagerMutation],
+        cost: 1,
+        explanation: ["Direct edge rewrite"],
+      },
+    ],
+    totalCost: 1,
+    warnings: [],
+  };
+
+  const preview = {
+    intentLabel: "Set manager",
+    primary: setManagerMutation,
+    defaultStrategy: strategy,
+    alternatives: [],
+    warnings: [],
+    selectionRationale: { chosen: ["Lowest cost"], rejectedAlternatives: [] },
+  };
+
+  it("accepts a preview without a hardBlock", () => {
+    expect(TransformationPreviewSchema.parse(preview)).toEqual(preview);
+  });
+
+  it("accepts a preview with a hardBlock", () => {
+    expect(
+      TransformationPreviewSchema.safeParse({
+        ...preview,
+        hardBlock: { code: "reporting.cycle", reason: "Would create a cycle" },
+      }).success,
+    ).toBe(true);
+  });
+
+  it("rejects a hardBlock missing its reason", () => {
+    expect(
+      TransformationPreviewSchema.safeParse({
+        ...preview,
+        hardBlock: { code: "reporting.cycle" },
+      }).success,
+    ).toBe(false);
+  });
+
+  it("rejects a preview missing the primary mutation", () => {
+    const { primary: _omit, ...noPrimary } = preview;
+    expect(TransformationPreviewSchema.safeParse(noPrimary).success).toBe(
+      false,
+    );
+  });
+});

package/src/org/index.ts

@@ -150,6 +150,32 @@ export type {
   OrgStructureInferenceDecisionResult,
 } from "./reasoning-review";
 
+// Org transformation wire vocabulary: intent -> simulation -> preview. The
+// engine turns a TransformationRequest into scored mutation bundles and returns
+// a TransformationPreview the operator confirms before apply. (ADR-CONTRACTS-072)
+export {
+  OrgIntentSchema,
+  FactMutationSchema,
+  TransformationOriginSchema,
+  TransformationRequestSchema,
+  ConstraintViolationSchema,
+  RecommendationSchema,
+  TransformStrategySchema,
+  SelectionRationaleSchema,
+  TransformationPreviewSchema,
+} from "./transformation";
+export type {
+  OrgIntent,
+  FactMutation,
+  TransformationOrigin,
+  TransformationRequest,
+  ConstraintViolation,
+  Recommendation,
+  TransformStrategy,
+  SelectionRationale,
+  TransformationPreview,
+} from "./transformation";
+
 // Canonical facts: the adapter-seam ingestion batch. Each fact is keyed by
 // external identity (externalSourceId/externalSourceSystem) and carries a
 // FactProvenance envelope; the reconciler consumes the batch. (ADR-CONT-085 / ADR-CTRL-183)

package/src/org/transformation.ts

@@ -0,0 +1,215 @@
+/**
+ * Org transformation wire vocabulary — intent → simulation → preview.
+ *
+ * A transformation is a deliberate change to the org graph expressed at the
+ * level of INTENT ("make this seat report to that one") rather than raw fact
+ * writes. The semantic transformation engine (control ADR-CTRL — see
+ * ADR-CONTRACTS-072) turns one {@link TransformationRequestSchema} into a set of
+ * candidate {@link FactMutationSchema} bundles, scores them deterministically,
+ * and returns a {@link TransformationPreviewSchema} the operator confirms before
+ * anything is applied. This module is the shared WIRE vocabulary for that flow.
+ *
+ * Layers, smallest → largest:
+ *  - {@link OrgIntentSchema} — WHAT the operator wants, as a discriminated union
+ *    on `kind`. Today only `reporting.setManager`; shaped so future kinds
+ *    (home.setUnit, unit.move, position.open, position.close) append without
+ *    breaking existing consumers.
+ *  - {@link FactMutationSchema} — the typed ATOMIC fact change the engine applies
+ *    to the live graph. Distinct from intent: an intent may expand into several
+ *    mutations, and a mutation can express un-setting (a null target) that an
+ *    intent never does.
+ *  - {@link TransformationRequestSchema} — an intent plus its `origin` and an
+ *    optional human WHY (`reason`).
+ *  - {@link RecommendationSchema} / {@link TransformStrategySchema} — the scored,
+ *    explained candidate bundles the engine produces.
+ *  - {@link TransformationPreviewSchema} — the full operator-facing preview: the
+ *    primary mutation, the default strategy, alternatives, and the deterministic
+ *    rationale for what was chosen.
+ *
+ * NOTE ON PLACEMENT: these are PUBLISHED response/preview shapes (ADR-CONT-029:
+ * response shapes live in contracts, request bodies stay backend-local). The
+ * transformation REQUEST body the backend route accepts is modeled there; this
+ * module carries only the vocabulary the contract surface promises.
+ *
+ * Reporting edge field names (`reportPositionId` / `managerPositionId`) match
+ * {@link PositionReportingSchema} exactly so intent, mutation, and the canonical
+ * edge speak one language.
+ *
+ * @see ADR-CONTRACTS-072 for the transformation vocabulary decision
+ * @see position-reporting.ts for the canonical reporting-edge field names
+ * @see structure-facts.ts (FactProvenance.reason) for the human-WHY precedent
+ */
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// OrgIntent — WHAT the operator wants (discriminated union, designed to grow)
+// ---------------------------------------------------------------------------
+
+/**
+ * A requested org-graph change expressed as intent. Discriminated on `kind`, a
+ * dotted string naming the affected relation and verb. Today the only variant
+ * is `reporting.setManager` — point a reporting seat at a (non-null) manager
+ * seat. Future kinds (`home.setUnit`, `unit.move`, `position.open`,
+ * `position.close`) append as new union members without breaking consumers.
+ */
+export const OrgIntentSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("reporting.setManager"),
+    /** The reporting (subordinate) seat whose manager is being set. */
+    reportPositionId: z.string().uuid(),
+    /** The manager seat to report to. Non-null on an intent (un-setting is a mutation concern). */
+    managerPositionId: z.string().uuid(),
+  }),
+]);
+export type OrgIntent = z.infer<typeof OrgIntentSchema>;
+
+// ---------------------------------------------------------------------------
+// FactMutation — the atomic fact change the engine applies
+// ---------------------------------------------------------------------------
+
+/**
+ * A single atomic fact change the engine applies to the live org graph.
+ * Discriminated on `kind`, mirroring {@link OrgIntentSchema}. Unlike an intent,
+ * a mutation can express UN-SETTING: `reporting.setManager` with a null
+ * `managerPositionId` clears the seat's manager edge entirely.
+ */
+export const FactMutationSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("reporting.setManager"),
+    /** The reporting (subordinate) seat whose manager edge is being written. */
+    reportPositionId: z.string().uuid(),
+    /** The new manager seat, or `null` to un-set (clear) the manager edge. */
+    managerPositionId: z.string().uuid().nullable(),
+  }),
+]);
+export type FactMutation = z.infer<typeof FactMutationSchema>;
+
+// ---------------------------------------------------------------------------
+// TransformationRequest — an intent plus origin and an optional human WHY
+// ---------------------------------------------------------------------------
+
+/**
+ * Where a transformation originated. Closed set: a direct `user_intent`, a
+ * `business_event` (e.g. a sync-observed reorg), or an `external_observation`
+ * (an inference proposed from outside the system).
+ */
+export const TransformationOriginSchema = z.enum([
+  "user_intent",
+  "business_event",
+  "external_observation",
+]);
+export type TransformationOrigin = z.infer<typeof TransformationOriginSchema>;
+
+export const TransformationRequestSchema = z.object({
+  /** Provenance class of the request — drives how much scrutiny it gets. */
+  origin: TransformationOriginSchema,
+  /** The requested change, as intent. */
+  intent: OrgIntentSchema,
+  /**
+   * Human-meaningful WHY for an authority-relevant change — a free-text audit
+   * record of intent, capped at 2000 chars to mirror {@link FactProvenanceSchema}'s
+   * `reason`. `null`/absent for machine-originated requests. It records why a
+   * change was requested, NOT who may make it (ADR-CTRL-180).
+   */
+  reason: z.string().max(2000).nullable().optional(),
+});
+export type TransformationRequest = z.infer<typeof TransformationRequestSchema>;
+
+// ---------------------------------------------------------------------------
+// ConstraintViolation — a rule the engine found broken or at risk
+// ---------------------------------------------------------------------------
+
+/**
+ * One constraint the transformation engine evaluated and found violated. `code`
+ * is an open string naming the rule; `severity` distinguishes a hard `error`
+ * (the change is rejected) from a `warning` (allowed but flagged); `subject` is
+ * the optional id of the entity the violation is about.
+ */
+export const ConstraintViolationSchema = z.object({
+  /** Open string naming the violated rule (e.g. "reporting.cycle"). */
+  code: z.string().min(1),
+  /** `error` blocks the change; `warning` allows it but surfaces a caution. */
+  severity: z.enum(["error", "warning"]),
+  /** Optional id of the entity the violation concerns. */
+  subject: z.string().optional(),
+});
+export type ConstraintViolation = z.infer<typeof ConstraintViolationSchema>;
+
+// ---------------------------------------------------------------------------
+// Recommendation — one scored, explained candidate bundle of mutations
+// ---------------------------------------------------------------------------
+
+export const RecommendationSchema = z.object({
+  /** Short human label for this candidate (e.g. "Move report to new manager"). */
+  label: z.string().min(1),
+  /** The atomic fact changes this candidate would apply. */
+  mutations: z.array(FactMutationSchema),
+  /** Deterministic relative cost of this candidate; lower is preferred. */
+  cost: z.number(),
+  /** Optional single caution shown alongside this candidate. */
+  warning: z.string().optional(),
+  /** Deterministic, ordered reasons explaining how this candidate was derived. */
+  explanation: z.array(z.string()),
+});
+export type Recommendation = z.infer<typeof RecommendationSchema>;
+
+// ---------------------------------------------------------------------------
+// TransformStrategy — a scored set of recommendations
+// ---------------------------------------------------------------------------
+
+export const TransformStrategySchema = z.object({
+  /** Candidate bundles, in the engine's preference order. */
+  recommendations: z.array(RecommendationSchema),
+  /** Aggregate cost across the strategy's recommendations. */
+  totalCost: z.number(),
+  /** Strategy-level cautions not tied to a single recommendation. */
+  warnings: z.array(z.string()),
+});
+export type TransformStrategy = z.infer<typeof TransformStrategySchema>;
+
+// ---------------------------------------------------------------------------
+// SelectionRationale — why the default strategy was chosen over alternatives
+// ---------------------------------------------------------------------------
+
+export const SelectionRationaleSchema = z.object({
+  /** Ordered reasons the chosen strategy won. */
+  chosen: z.array(z.string()),
+  /** Each alternative that lost, with the ordered reasons it was rejected. */
+  rejectedAlternatives: z.array(
+    z.object({
+      label: z.string().min(1),
+      reasons: z.array(z.string()),
+    }),
+  ),
+});
+export type SelectionRationale = z.infer<typeof SelectionRationaleSchema>;
+
+// ---------------------------------------------------------------------------
+// TransformationPreview — the full operator-facing preview before apply
+// ---------------------------------------------------------------------------
+
+export const TransformationPreviewSchema = z.object({
+  /** Human label for the intent being previewed. */
+  intentLabel: z.string().min(1),
+  /** The headline fact change the preview is centered on. */
+  primary: FactMutationSchema,
+  /** The strategy the engine recommends by default. */
+  defaultStrategy: TransformStrategySchema,
+  /** Other viable strategies the operator may pick instead. */
+  alternatives: z.array(TransformStrategySchema),
+  /** Preview-level cautions spanning the whole transformation. */
+  warnings: z.array(z.string()),
+  /** Deterministic rationale for the default choice over the alternatives. */
+  selectionRationale: SelectionRationaleSchema,
+  /**
+   * Present only when the transformation is hard-blocked: a terminal reason the
+   * change cannot proceed at all. Absent on a previewable (confirmable) change.
+   */
+  hardBlock: z
+    .object({
+      code: z.string().min(1),
+      reason: z.string().min(1),
+    })
+    .optional(),
+});
+export type TransformationPreview = z.infer<typeof TransformationPreviewSchema>;