@company-semantics/contracts 27.1.0 → 27.3.0

package/package.json

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

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = '0a8d3435dba9' as const;
-export const SPEC_HASH_FULL = '0a8d3435dba94642fe2cf529b1743d868363875302393e23cf0b9238a4f5cd47' as const;
+export const SPEC_HASH = '409ce57139cd' as const;
+export const SPEC_HASH_FULL = '409ce57139cd78a8ec633efb516bc92ba81dd2cdaab0a4afe240d20c67bb6b1e' as const;

package/src/api/generated.ts

@@ -1338,6 +1338,40 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/integrations/bamboohr/inferences": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List the org’s pending org-structure reasoning inferences (review queue) */
+        get: operations["listBambooHrInferences"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/integrations/bamboohr/inferences/{id}/decision": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Accept or reject one pending org-structure reasoning inference */
+        post: operations["decideBambooHrInference"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/company-md/tree": {
         parameters: {
             query?: never;
@@ -4366,6 +4400,29 @@ export interface components {
                 };
             };
         };
+        OrgStructureReviewQueue: {
+            items: {
+                /** Format: uuid */
+                id: string;
+                inferenceType: string;
+                payload: unknown;
+                confidence: number;
+                reason: string;
+                /** Format: date-time */
+                createdAt: string;
+            }[];
+        };
+        OrgStructureInferenceDecisionResult: {
+            /** Format: uuid */
+            id: string;
+            /** @enum {string} */
+            status: "accepted" | "rejected";
+            applied: boolean;
+        };
+        BambooHrInferenceDecision: {
+            /** @enum {string} */
+            decision: "accept" | "reject";
+        };
         CompanyMdListResponse: {
             items: {
                 id: string;
@@ -7799,6 +7856,66 @@ export interface operations {
             };
         };
     };
+    listBambooHrInferences: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The org’s pending (review) org-structure inferences, newest first */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgStructureReviewQueue"];
+                };
+            };
+        };
+    };
+    decideBambooHrInference: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["BambooHrInferenceDecision"];
+            };
+        };
+        responses: {
+            /** @description The decision outcome (status + whether the org graph was mutated) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgStructureInferenceDecisionResult"];
+                };
+            };
+            /** @description Invalid decision value */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Inference not found or already decided */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     getCompanyMdTree: {
         parameters: {
             query?: {

package/src/generated/openapi-routes.ts

@@ -62,6 +62,8 @@ export const openApiRoutes = {
   '/api/factory/kpis': ['GET'],
   '/api/factory/snapshot': ['GET'],
   '/api/ingestion/operations/{id}': ['GET'],
+  '/api/integrations/bamboohr/inferences': ['GET'],
+  '/api/integrations/bamboohr/inferences/{id}/decision': ['POST'],
   '/api/internal-admin/impersonate/end': ['POST'],
   '/api/internal-admin/impersonate/session': ['GET'],
   '/api/internal-admin/impersonate/start': ['POST'],

package/src/index.ts

@@ -424,6 +424,46 @@ export type { SyncRunSummary } from "./org/index";
 export { ConflictRecordSchema } from "./org/index";
 export type { ConflictRecord } from "./org/index";
 
+// Org-structure reasoning review queue: pending structure inferences an operator
+// accepts/rejects, and the outcome of one decision. Published response shapes.
+// Provider-agnostic store; BambooHR is the first surface. (ADR-CONT-095)
+export {
+  OrgStructureReviewInferenceSchema,
+  OrgStructureReviewQueueSchema,
+  OrgStructureInferenceDecisionResultSchema,
+} from "./org/index";
+export type {
+  OrgStructureReviewInference,
+  OrgStructureReviewQueue,
+  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)_
@@ -159,6 +165,12 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `OrgOwnerIcon` _(type)_
 - `OrgOwnerIconSchema` — Icon options for the `owner` org-chart role.
 - `OrgScopedContext` _(type)_ — Validated organization-scoped context for policy implementations.
+- `OrgStructureInferenceDecisionResult` _(type)_
+- `OrgStructureInferenceDecisionResultSchema`
+- `OrgStructureReviewInference` _(type)_
+- `OrgStructureReviewInferenceSchema`
+- `OrgStructureReviewQueue` _(type)_
+- `OrgStructureReviewQueueSchema`
 - `OrgSystemEventsList` _(type)_
 - `OrgSystemEventsListSchema`
 - `OrgTreeResponse` _(type)_
@@ -236,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`
@@ -246,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)_
@@ -281,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

@@ -136,6 +136,46 @@ export type { SyncRunSummary } from "./sync-run";
 export { ConflictRecordSchema } from "./conflict-record";
 export type { ConflictRecord } from "./conflict-record";
 
+// Org-structure reasoning review queue: pending structure inferences an operator
+// accepts/rejects, and the outcome of one decision. Published response shapes;
+// provider-agnostic store, BambooHR is the first surface. (ADR-CONT-095)
+export {
+  OrgStructureReviewInferenceSchema,
+  OrgStructureReviewQueueSchema,
+  OrgStructureInferenceDecisionResultSchema,
+} from "./reasoning-review";
+export type {
+  OrgStructureReviewInference,
+  OrgStructureReviewQueue,
+  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/reasoning-review.ts

@@ -0,0 +1,85 @@
+/**
+ * Org-structure reasoning review vocabulary — the operator review queue for
+ * proposed structure changes and the outcome of deciding one.
+ *
+ * An org-structure reasoning pass (the adapter → reasoning-engine pipeline,
+ * BambooHR being the guinea-pig source — control ADR-CTRL-159, backend
+ * ADR-BE-345) emits structure INFERENCES (nest a unit, place a report, ...) that
+ * are held in `review` rather than applied blindly. The review queue is the set
+ * of an org's pending inferences; an operator with integration-management
+ * authority ACCEPTS one (re-applying it to the live org graph) or REJECTS it.
+ *
+ * These are published RESPONSE shapes (ADR-CONT-029: response/published shapes
+ * live in contracts; the `decision` request body stays backend-local). They are
+ * provider-agnostic — the underlying store (`org_structure_inferences`) is not
+ * BambooHR-specific even though the first surface that reads it is the BambooHR
+ * integration route. `inferenceType` is an OPEN string (no enum) so new
+ * inference kinds need no schema change, mirroring the sibling org schemas
+ * ({@link ConflictRecordSchema}, {@link SyncRunSummarySchema}). `payload` is the
+ * inference-kind-specific body, modeled as unknown — its shape is keyed off
+ * `inferenceType` and is not part of the stable contract surface.
+ */
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// OrgStructureReviewInference — one pending ('review') structure inference
+// ---------------------------------------------------------------------------
+
+export const OrgStructureReviewInferenceSchema = z.object({
+  /** Identifier of this inference within the org graph. */
+  id: z.string().uuid(),
+  /**
+   * Kind of structure inference (e.g. "NestOrgUnit", "PlaceReport"). An OPEN
+   * string so new inference kinds need no schema change.
+   */
+  inferenceType: z.string().min(1),
+  /**
+   * The inference-kind-specific body. Its shape is keyed off `inferenceType`
+   * and is intentionally unmodeled here — not part of the stable contract.
+   */
+  payload: z.unknown(),
+  /** Engine confidence in this inference, 0..1. */
+  confidence: z.number(),
+  /** Human-meaningful WHY the engine proposed this change. */
+  reason: z.string(),
+  /** ISO timestamp the inference was created. */
+  createdAt: z.string().datetime(),
+});
+
+export type OrgStructureReviewInference = z.infer<
+  typeof OrgStructureReviewInferenceSchema
+>;
+
+// ---------------------------------------------------------------------------
+// OrgStructureReviewQueue — an org's pending review inferences (newest first)
+// ---------------------------------------------------------------------------
+
+export const OrgStructureReviewQueueSchema = z.object({
+  /** The org's pending ('review') inferences, newest first. */
+  items: z.array(OrgStructureReviewInferenceSchema),
+});
+
+export type OrgStructureReviewQueue = z.infer<
+  typeof OrgStructureReviewQueueSchema
+>;
+
+// ---------------------------------------------------------------------------
+// OrgStructureInferenceDecisionResult — outcome of accepting/rejecting one
+// ---------------------------------------------------------------------------
+
+export const OrgStructureInferenceDecisionResultSchema = z.object({
+  /** Identifier of the decided inference. */
+  id: z.string().uuid(),
+  /** The terminal status the inference was moved to. */
+  status: z.enum(["accepted", "rejected"]),
+  /**
+   * Whether the decision mutated the live org graph. True on an accept that
+   * re-applied the inference; false on a reject (and on an accept that resolved
+   * to a no-op).
+   */
+  applied: z.boolean(),
+});
+
+export type OrgStructureInferenceDecisionResult = z.infer<
+  typeof OrgStructureInferenceDecisionResultSchema
+>;

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>;