@company-semantics/contracts 27.3.0 → 27.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "27.3.0",
+  "version": "27.5.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -123,12 +123,12 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^22.10.0",
+    "@types/node": "^26.0.1",
     "husky": "^9.1.7",
-    "lint-staged": "^17.0.7",
+    "lint-staged": "^17.0.8",
     "markdownlint-cli2": "^0.22.1",
     "openapi-typescript": "^7.13.0",
-    "prettier": "^3.8.4",
+    "prettier": "^3.9.4",
     "tsx": "^4.22.4",
     "typescript": "^5.8.3",
     "vitest": "^4.1.9",

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 = '409ce57139cd' as const;
-export const SPEC_HASH_FULL = '409ce57139cd78a8ec633efb516bc92ba81dd2cdaab0a4afe240d20c67bb6b1e' as const;
+export const SPEC_HASH = '511ebe19b2ad' as const;
+export const SPEC_HASH_FULL = '511ebe19b2adea947b0bfbd6ad39a192a616cf10e2d30606dde9ef8517389eed' as const;

package/src/api/generated.ts

@@ -753,6 +753,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/reporting/move/preview": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Preview an org-chart reporting move as a semantic transform */
+        post: operations["previewReportingMove"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/chat/interactive-tasks/submit": {
         parameters: {
             query?: never;
@@ -3909,6 +3926,18 @@ export interface components {
             };
             idempotencyKey: string;
         };
+        MovePreviewRequest: {
+            /**
+             * Format: uuid
+             * @description Workspace member (users.id) being moved in the chart
+             */
+            memberId: string;
+            /**
+             * Format: uuid
+             * @description The member (users.id) the dragged member should report to after the move
+             */
+            newManagerUserId: string;
+        };
         SubmitInteractiveTaskResponse: {
             executionId: string;
             /** @enum {string} */
@@ -4440,6 +4469,13 @@ export interface components {
                 memberCount: number;
                 description?: string;
                 orderKey?: string;
+                /** @enum {string} */
+                discoverabilityPolicy: "org" | "owners";
+                /** @enum {string} */
+                classification: "public" | "internal" | "confidential" | "highly_confidential";
+                /** @enum {string} */
+                accessState?: "full" | "redacted_admin" | "locked_requestable";
+                canRequestAccess?: boolean;
             }[];
             nextCursor: string | null;
             hasMore: boolean;
@@ -4453,7 +4489,14 @@ export interface components {
             content: string;
             contentRedacted?: boolean;
             /** @enum {string} */
+            accessState?: "full" | "redacted_admin" | "locked_requestable";
+            canRequestAccess?: boolean;
+            /** @enum {string} */
             visibility: "private" | "unit" | "org";
+            /** @enum {string} */
+            discoverabilityPolicy: "org" | "owners";
+            /** @enum {string} */
+            classification: "public" | "internal" | "confidential" | "highly_confidential";
             parentId: string | null;
             owningUnitId: string | null;
             owner: {
@@ -7036,6 +7079,28 @@ export interface operations {
             };
         };
     };
+    previewReportingMove: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["MovePreviewRequest"];
+            };
+        };
+        responses: {
+            /** @description Transformation preview plus the semantic.transform execution intent (mutations) the app confirms */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     submitInteractiveTask: {
         parameters: {
             query?: never;
@@ -8467,13 +8532,6 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Requires org.view_company_md scope */
-            403: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content?: never;
-            };
         };
     };
     companyMdContextDocSuggestions: {
@@ -8503,13 +8561,6 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Requires org.view_company_md scope */
-            403: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content?: never;
-            };
         };
     };
     searchCompanyMd: {

package/src/autotune.ts

@@ -86,9 +86,6 @@ export type ControllerInput = {
 export type ControllerOutput<Min extends number, Max extends number> = {
   readonly value: Bounded<Min, Max>;
   readonly reason:
-    | "deadband-hold"
-    | "window-hold"
-    | "adjusted"
-    | "bounded-clamp";
+    "deadband-hold" | "window-hold" | "adjusted" | "bounded-clamp";
   readonly adjustmentWindowId: string;
 };

package/src/ci-envelope/types.ts

@@ -130,11 +130,7 @@ export type CIGuardPlan = {
  * Note: Transition validation logic lives in CI repo, not here.
  */
 export type CIEnvelopeStatus =
-  | "proposed"
-  | "validated"
-  | "blocked"
-  | "executing"
-  | "finalized";
+  "proposed" | "validated" | "blocked" | "executing" | "finalized";
 
 // =============================================================================
 // Outcome Types

package/src/ci-results/repo-ci-result.ts

@@ -6,11 +6,7 @@
  */
 
 export type GuardTier =
-  | "structural"
-  | "behavioral"
-  | "invariants"
-  | "evolution"
-  | "meta";
+  "structural" | "behavioral" | "invariants" | "evolution" | "meta";
 
 /**
  * Minimal structural shape of a guard orchestrator result payload.

package/src/content/schemas.ts

@@ -59,6 +59,25 @@ const CompanyMdTreeNodeSchema = z.object({
   description: z.string().optional(),
   /** Fractional-index key for ordered entity wrappers (unit/context). */
   orderKey: z.string().optional(),
+  // Governance + discovery projections of the node (ADR-BE-348 / ADR-CTRL-194).
+  // Present on the TS `CompanyMdNodeIdentity` since the projection split but only
+  // now promoted into the published response schema. `discoverabilityPolicy`
+  // governs who knows the node exists; `classification` is the governance label
+  // (drives no permission).
+  discoverabilityPolicy: z.enum(["org", "owners"]),
+  classification: z.enum([
+    "public",
+    "internal",
+    "confidential",
+    "highly_confidential",
+  ]),
+  // Combined Authorization + Discovery read-state for the requesting actor
+  // (ADR-BE-348). Set on non-reader stubs the tree now surfaces; absent on
+  // full-read nodes (treat as `full`).
+  accessState: z
+    .enum(["full", "redacted_admin", "locked_requestable"])
+    .optional(),
+  canRequestAccess: z.boolean().optional(),
 });
 
 // ---------------------------------------------------------------------------
@@ -83,7 +102,26 @@ export const CompanyMdDocResponseSchema = z.object({
    * its body (ADR-BE-245). Omitted/`false` on the normal full-content path.
    */
   contentRedacted: z.boolean().optional(),
+  // Combined Authorization + Discovery read-state for the requesting actor
+  // (ADR-BE-348): `full` (reader), `redacted_admin` (inspectable metadata stub),
+  // `locked_requestable` (listed locked stub). Optional for back-compat with
+  // legacy paths that set only `contentRedacted`.
+  accessState: z
+    .enum(["full", "redacted_admin", "locked_requestable"])
+    .optional(),
+  /** Whether the requesting actor may request access (ADR-BE-348 / ADR-BE-338). */
+  canRequestAccess: z.boolean().optional(),
   visibility: z.enum(["private", "unit", "org"]),
+  // Governance + discovery projections (ADR-BE-348 / ADR-CTRL-194). Present on
+  // the TS contract since the projection split; now promoted into the published
+  // response schema so consumers receive them typed.
+  discoverabilityPolicy: z.enum(["org", "owners"]),
+  classification: z.enum([
+    "public",
+    "internal",
+    "confidential",
+    "highly_confidential",
+  ]),
   parentId: z.string().nullable(),
   owningUnitId: z.string().nullable(),
   owner: CompanyMdPersonSchema.nullable(),

package/src/generated/openapi-routes.ts

@@ -126,6 +126,7 @@ export const openApiRoutes = {
   '/api/orgs/{orgId}/level-config': ['GET', 'PUT'],
   '/api/rbac/roles': ['GET'],
   '/api/reporting/bulk-reparent': ['POST'],
+  '/api/reporting/move/preview': ['POST'],
   '/api/scope/check': ['GET'],
   '/api/scope/check-batch': ['POST'],
   '/api/shared/{token}': ['GET'],

package/src/guards/types.ts

@@ -59,11 +59,7 @@ export interface GuardTierResult {
  * - meta: guards that protect the guard system itself (coverage correctness)
  */
 export type GuardTier =
-  | "structural"
-  | "behavioral"
-  | "invariants"
-  | "evolution"
-  | "meta";
+  "structural" | "behavioral" | "invariants" | "evolution" | "meta";
 
 /**
  * Full guard results, organized by tier.

package/src/index.ts

@@ -445,9 +445,13 @@ export {
   OrgIntentSchema,
   FactMutationSchema,
   TransformationOriginSchema,
+  ProvenanceSchema,
+  ExecutionContextSchema,
   TransformationRequestSchema,
   ConstraintViolationSchema,
   RecommendationSchema,
+  FindingSeveritySchema,
+  FindingSchema,
   TransformStrategySchema,
   SelectionRationaleSchema,
   TransformationPreviewSchema,
@@ -456,9 +460,13 @@ export type {
   OrgIntent,
   FactMutation,
   TransformationOrigin,
+  Provenance,
+  ExecutionContext,
   TransformationRequest,
   ConstraintViolation,
   Recommendation,
+  FindingSeverity,
+  Finding,
   TransformStrategy,
   SelectionRationale,
   TransformationPreview,

package/src/mcp/index.ts

@@ -27,11 +27,7 @@ export type { FailureContext, RecoveryAction } from "./failure-context";
  * 'data' conflates discovery, ingestion, and coverage.
  */
 export type ToolCategory =
-  | "system"
-  | "data"
-  | "connections"
-  | "automation"
-  | "developer";
+  "system" | "data" | "connections" | "automation" | "developer";
 
 /**
  * Tool domain taxonomy.

package/src/message-parts/confirmation.ts

@@ -30,10 +30,7 @@ export type ConfirmationChoice = "confirm" | "cancel";
  * 'irreversible' indicates destructive operations that cannot be undone.
  */
 export type ConfirmationRiskLevel =
-  | "low"
-  | "moderate"
-  | "high"
-  | "irreversible";
+  "low" | "moderate" | "high" | "irreversible";
 
 /**
  * Human-readable confirmation dialog titles for each execution kind.

package/src/message-parts/interactive.ts

@@ -33,8 +33,7 @@ import type { ConfirmationRiskLevel } from "./confirmation";
  * Mirrors the `{domain}.{verb}` naming of ExecutionKind. Extensible union.
  */
 export type InteractiveTaskKind =
-  | "member.changeManager"
-  | "companyMd.importContextDoc";
+  "member.changeManager" | "companyMd.importContextDoc";
 
 /**
  * How the frontend sources candidate values for an editable field.

package/src/message-parts/lifecycle.ts

@@ -34,9 +34,7 @@ export type StreamPhase = "idle" | "streaming" | "complete";
  * Lifecycle event type discriminator.
  */
 export type MessageLifecycleEventType =
-  | "message.start"
-  | "message.delta"
-  | "message.complete";
+  "message.start" | "message.delta" | "message.complete";
 
 /**
  * Base interface for all message lifecycle events.

package/src/org/README.md

@@ -95,6 +95,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `DomainVerificationMethod` _(type)_ — Method used to verify domain ownership. - 'dnstxt': DNS TXT record verification (primary method) - 'email'…
 - `EffectiveAccess` _(type)_ — Effective access for a user on a document.
 - `EvaluationStep` _(type)_ — Single step in the access evaluation trace.
+- `ExecutionContext` _(type)_
+- `ExecutionContextSchema` — ExecutionContext — the RUN in which an intent was produced or applied.
 - `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)_
@@ -107,6 +109,10 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `FieldCapabilitySchema` — A mutable field's gate: editable, or locked with attribution (sso vs rbac).
 - `FillOpenRoleRequest` _(type)_
 - `FillOpenRoleRequestSchema` — Fill an open role by seating an existing org member (`userId`) or inviting a new person by email.
+- `Finding` _(type)_
+- `FindingSchema` — A single diagnostic the system emits about the org graph — the GENERAL model of which {@link…
+- `FindingSeverity` _(type)_
+- `FindingSeveritySchema` — Severity of a {@link FindingSchema}.
 - `HomeAssignment` _(type)_
 - `HomeAssignmentSchema` — A person's single structural home unit — at most one per person per org.
 - `HomeUnitRole` _(type)_
@@ -246,6 +252,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `PositionSchema`
 - `PositionStatus` _(type)_
 - `PositionStatusSchema` — Lifecycle of a seat's EXISTENCE — distinct from a hiring pipeline.
+- `Provenance` _(type)_
+- `ProvenanceSchema` — Provenance — WHO/WHAT generated an intent.
 - `ProviderStatus` _(type)_ — Provider-level configuration lifecycle.
 - `ProviderSuggestion` _(type)_ — MX-based provider suggestion for SSO setup.
 - `Recommendation` _(type)_

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

@@ -3,9 +3,12 @@ import {
   OrgIntentSchema,
   FactMutationSchema,
   TransformationOriginSchema,
+  ProvenanceSchema,
+  ExecutionContextSchema,
   TransformationRequestSchema,
   ConstraintViolationSchema,
   RecommendationSchema,
+  FindingSchema,
   TransformStrategySchema,
   SelectionRationaleSchema,
   TransformationPreviewSchema,
@@ -13,6 +16,9 @@ import {
 
 const REPORT = "33333333-3333-4333-8333-333333333333";
 const MANAGER = "44444444-4444-4444-8444-444444444444";
+const UNIT = "55555555-5555-4555-8555-555555555555";
+const PARENT_UNIT = "66666666-6666-4666-8666-666666666666";
+const POSITION = "77777777-7777-4777-8777-777777777777";
 
 const setManagerIntent = {
   kind: "reporting.setManager" as const,
@@ -53,6 +59,53 @@ describe("OrgIntentSchema", () => {
       }).success,
     ).toBe(false);
   });
+
+  it("accepts a unit.setParent intent with a parent", () => {
+    const intent = {
+      kind: "unit.setParent" as const,
+      unitId: UNIT,
+      parentUnitId: PARENT_UNIT,
+    };
+    expect(OrgIntentSchema.parse(intent)).toEqual(intent);
+  });
+
+  it("accepts a unit.setParent intent with a null parent (unit becomes a root)", () => {
+    const intent = {
+      kind: "unit.setParent" as const,
+      unitId: UNIT,
+      parentUnitId: null,
+    };
+    expect(OrgIntentSchema.parse(intent)).toEqual(intent);
+  });
+
+  it("rejects a non-uuid parentUnitId", () => {
+    expect(
+      OrgIntentSchema.safeParse({
+        kind: "unit.setParent",
+        unitId: UNIT,
+        parentUnitId: "x",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("accepts a position.setTitle intent", () => {
+    const intent = {
+      kind: "position.setTitle" as const,
+      positionId: POSITION,
+      title: "Staff Engineer",
+    };
+    expect(OrgIntentSchema.parse(intent)).toEqual(intent);
+  });
+
+  it("rejects a position.setTitle intent with an empty title", () => {
+    expect(
+      OrgIntentSchema.safeParse({
+        kind: "position.setTitle",
+        positionId: POSITION,
+        title: "",
+      }).success,
+    ).toBe(false);
+  });
 });
 
 describe("FactMutationSchema", () => {
@@ -77,6 +130,34 @@ describe("FactMutationSchema", () => {
         .success,
     ).toBe(false);
   });
+
+  it("accepts a unit.setParent mutation with a parent", () => {
+    const mutation = {
+      kind: "unit.setParent" as const,
+      unitId: UNIT,
+      parentUnitId: PARENT_UNIT,
+    };
+    expect(FactMutationSchema.parse(mutation)).toEqual(mutation);
+  });
+
+  it("accepts a unit.setParent mutation with a null parent (unit becomes a root)", () => {
+    expect(
+      FactMutationSchema.safeParse({
+        kind: "unit.setParent",
+        unitId: UNIT,
+        parentUnitId: null,
+      }).success,
+    ).toBe(true);
+  });
+
+  it("accepts a position.setTitle mutation", () => {
+    const mutation = {
+      kind: "position.setTitle" as const,
+      positionId: POSITION,
+      title: "Principal Engineer",
+    };
+    expect(FactMutationSchema.parse(mutation)).toEqual(mutation);
+  });
 });
 
 describe("TransformationOriginSchema", () => {
@@ -126,6 +207,49 @@ describe("TransformationRequestSchema", () => {
         .success,
     ).toBe(false);
   });
+
+  it("accepts an optional executionContext", () => {
+    const withCtx = {
+      ...request,
+      executionContext: { runId: "run-42", trigger: "scheduled_sync" },
+    };
+    expect(TransformationRequestSchema.parse(withCtx)).toEqual(withCtx);
+  });
+});
+
+describe("ProvenanceSchema", () => {
+  it("accepts an origin plus optional sourceSystem", () => {
+    const provenance = {
+      origin: "business_event" as const,
+      sourceSystem: "hris",
+    };
+    expect(ProvenanceSchema.parse(provenance)).toEqual(provenance);
+  });
+
+  it("accepts an origin without a sourceSystem", () => {
+    expect(ProvenanceSchema.safeParse({ origin: "user_intent" }).success).toBe(
+      true,
+    );
+  });
+
+  it("rejects an unknown origin", () => {
+    expect(ProvenanceSchema.safeParse({ origin: "robot" }).success).toBe(false);
+  });
+});
+
+describe("ExecutionContextSchema", () => {
+  it("accepts runId and trigger", () => {
+    const ctx = { runId: "run-1", trigger: "webhook" };
+    expect(ExecutionContextSchema.parse(ctx)).toEqual(ctx);
+  });
+
+  it("accepts an empty context (both fields optional)", () => {
+    expect(ExecutionContextSchema.safeParse({}).success).toBe(true);
+  });
+
+  it("rejects a non-string runId", () => {
+    expect(ExecutionContextSchema.safeParse({ runId: 42 }).success).toBe(false);
+  });
 });
 
 describe("ConstraintViolationSchema", () => {
@@ -156,6 +280,48 @@ describe("ConstraintViolationSchema", () => {
   });
 });
 
+describe("FindingSchema", () => {
+  it("accepts each severity level", () => {
+    for (const severity of ["error", "warning", "info"] as const) {
+      expect(
+        FindingSchema.safeParse({ code: "topology.ownerless", severity })
+          .success,
+      ).toBe(true);
+    }
+  });
+
+  it("accepts optional detail and recommendation", () => {
+    const finding = {
+      code: "reporting.cycle",
+      severity: "info" as const,
+      subject: REPORT,
+      detail: "This seat participates in a reporting loop.",
+      recommendation: {
+        label: "Move report to new manager",
+        mutations: [setManagerMutation],
+        cost: 1,
+        explanation: ["Breaks the cycle by re-parenting the report."],
+      },
+    };
+    expect(FindingSchema.parse(finding)).toEqual(finding);
+  });
+
+  it("rejects an unknown severity", () => {
+    expect(
+      FindingSchema.safeParse({ code: "c", severity: "fatal" }).success,
+    ).toBe(false);
+  });
+
+  it("parses every ConstraintViolation value (structural superset)", () => {
+    const violation = ConstraintViolationSchema.parse({
+      code: "reporting.cycle",
+      severity: "error",
+      subject: REPORT,
+    });
+    expect(FindingSchema.parse(violation)).toEqual(violation);
+  });
+});
+
 describe("RecommendationSchema / TransformStrategySchema", () => {
   const recommendation = {
     label: "Reassign report",

package/src/org/company-md.ts

@@ -39,15 +39,29 @@ export type CompanyMdDiscoverabilityPolicy = "org" | "owners";
 
 /**
  * Information classification for a Company.md node — *what the document is*, for
- * governance, NOT permissions (ADR-CTRL-194 / ADR-BE-338). Later drives export
- * watermarking, share-approval gates, retrieval rules, and audit verbosity
- * without changing who can read. Named now; enforcement behaviors deferred.
+ * governance, NOT permissions (ADR-CTRL-194 / ADR-BE-338 / ADR-BE-348). It is the
+ * input to the Governance projection and NEVER participates in authorization or
+ * discovery (ADR-BE-348 invariant 4).
+ *
+ * The value is now emitted on the published response schemas (tree + doc) so a
+ * consumer can read it. Enforcement behaviors remain deferred — each is named
+ * with the concrete trigger that promotes it from decorative to enforced:
+ *
+ * - **Export watermarking** — wire when a doc-export/download surface ships
+ *   (`confidential`+ stamps the exporter identity + timestamp).
+ * - **Share-approval friction** — wire when external/cross-org sharing exists
+ *   (`highly_confidential` requires a second approver before an ACL grant lands).
+ * - **Retrieval rules** — wire when agent browsing / RAG over knowledge nodes is
+ *   on (`confidential`+ excluded from un-attributed retrieval contexts).
+ * - **Audit verbosity** — wire when the audit sink supports per-class verbosity
+ *   (`highly_confidential` reads emit a full access record, not a sampled one).
+ *
+ * Until those surfaces exist there is nothing to gate, so classification is
+ * carried, not enforced — a deliberate "named now, enforced on trigger" deferral,
+ * not an omission.
  */
 export type CompanyMdClassification =
-  | "public"
-  | "internal"
-  | "confidential"
-  | "highly_confidential";
+  "public" | "internal" | "confidential" | "highly_confidential";
 
 /**
  * @deprecated Since 1.12.0. `CompanyMdDocLevel` is superseded by `CompanyMdDocKind` + `depth`.
@@ -159,6 +173,26 @@ export interface CompanyMdTreeNode extends CompanyMdNodeIdentity {
    * unordered types.
    */
   readonly orderKey?: string;
+  /**
+   * Combined Authorization + Discovery read-state of this tree node for the
+   * requesting actor (ADR-BE-348). The tree now surfaces discoverable nodes a
+   * non-reader cannot read, as stubs:
+   * - `full`: actor holds a read grant — the normal, fully-navigable node.
+   * - `redacted_admin`: non-reader at Discovery `inspectable` (oversight/owner) —
+   *   a metadata stub.
+   * - `locked_requestable`: non-reader at Discovery `listed` — a locked stub.
+   * Discovery `hidden` nodes are omitted from the tree entirely (no leak).
+   * Omitted on legacy/full-content nodes that predate the stub surface; treat an
+   * absent value as `full`.
+   */
+  readonly accessState?: "full" | "redacted_admin" | "locked_requestable";
+  /**
+   * Whether the requesting actor may request access to this node — the same
+   * resolver the read affordance uses (ADR-BE-348). Set on non-reader stubs so
+   * the tree can render a "Request access" affordance; absent/`false` on nodes
+   * the actor already reads.
+   */
+  readonly canRequestAccess?: boolean;
 }
 
 export interface CompanyMdDocCore extends CompanyMdNodeIdentity {

package/src/org/index.ts

@@ -157,9 +157,13 @@ export {
   OrgIntentSchema,
   FactMutationSchema,
   TransformationOriginSchema,
+  ProvenanceSchema,
+  ExecutionContextSchema,
   TransformationRequestSchema,
   ConstraintViolationSchema,
   RecommendationSchema,
+  FindingSeveritySchema,
+  FindingSchema,
   TransformStrategySchema,
   SelectionRationaleSchema,
   TransformationPreviewSchema,
@@ -168,9 +172,13 @@ export type {
   OrgIntent,
   FactMutation,
   TransformationOrigin,
+  Provenance,
+  ExecutionContext,
   TransformationRequest,
   ConstraintViolation,
   Recommendation,
+  FindingSeverity,
+  Finding,
   TransformStrategy,
   SelectionRationale,
   TransformationPreview,

package/src/org/org-units.ts

@@ -23,25 +23,18 @@
 
 /** Semantic classification — projection-only, never drives traversal. */
 export type OrgUnitClassification =
-  | "execution_unit"
-  | "org_container"
-  | "custom";
+  "execution_unit" | "org_container" | "custom";
 
 /** External directory reconciliation policy for a unit. */
 export type OrgUnitSyncMode =
-  | "manual_only"
-  | "synced_readonly"
-  | "synced_with_overrides";
+  "manual_only" | "synced_readonly" | "synced_with_overrides";
 
 /** Default visibility inherited by new docs under this unit. */
 export type OrgUnitVisibility = "public" | "private" | "restricted";
 
 /** Edge classification for `org_unit_relationships`. Graph-only; never structural. */
 export type OrgUnitRelationshipType =
-  | "collaborates_with"
-  | "reports_to"
-  | "depends_on"
-  | "custom";
+  "collaborates_with" | "reports_to" | "depends_on" | "custom";
 
 /** Edge role — refines the collaboration nature on a graph edge. */
 export type OrgUnitRelationshipRole = "owner" | "participant" | "supporting";
@@ -51,10 +44,7 @@ export type OrgUnitMembershipStatus = "active" | "pending" | "removed";
 
 /** External directory origin of a membership row. */
 export type OrgUnitMembershipSource =
-  | "manual"
-  | "google_groups"
-  | "scim"
-  | "hris";
+  "manual" | "google_groups" | "scim" | "hris";
 
 /**
  * Hiring lifecycle of an open role — a persisted placeholder for the person

package/src/org/sharing.ts

@@ -12,10 +12,7 @@ export type AccessLevel = "viewer" | "commenter" | "editor";
  * - org_edit: All org members can edit (does NOT imply canShare)
  */
 export type SharePolicy =
-  | "restricted"
-  | "org_read"
-  | "org_comment"
-  | "org_edit";
+  "restricted" | "org_read" | "org_comment" | "org_edit";
 
 export interface AclEntry {
   readonly principalType: "user" | "unit";

package/src/org/transformation.ts

@@ -11,9 +11,12 @@
  *
  * Layers, smallest → largest:
  *  - {@link OrgIntentSchema} — WHAT the operator wants, as a discriminated union
- *    on `kind`. Today only `reporting.setManager`; shaped so future kinds
+ *    on `kind`: `reporting.setManager` (point a seat at a manager),
+ *    `unit.setParent` (re-parent an org unit, null parent → root), and
+ *    `position.setTitle` (relabel a seat). Shaped so further kinds
  *    (home.setUnit, unit.move, position.open, position.close) append without
- *    breaking existing consumers.
+ *    breaking existing consumers. Any consumer that exhaustively switches on
+ *    `kind` (an `assertNever` default arm) MUST add an arm for each new kind.
  *  - {@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
@@ -47,12 +50,30 @@ import { z } from "zod";
 
 /**
  * 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.
+ * dotted string naming the affected relation and verb:
+ *  - `reporting.setManager` — point a reporting seat at a (non-null) manager seat.
+ *  - `unit.setParent` — re-parent an org unit; `parentUnitId` null means the unit
+ *    becomes a root (level-1) unit, which is a meaningful intent, not an un-set.
+ *  - `position.setTitle` — relabel a seat's human-facing title.
+ *
+ * These are the intents the reasoning pipeline's NestOrgUnit (→ `unit.setParent`)
+ * and NormalizeRole (→ `position.setTitle`) inferences resolve into, after
+ * external→canonical id resolution, so every id here is a canonical uuid.
+ *
+ * Further kinds (`home.setUnit`, `unit.move`, `position.open`, `position.close`)
+ * append as new union members without breaking consumers. Appending is
+ * backward-compatible for producers and for consumers that do not exhaustively
+ * switch on `kind`; any consumer that DOES exhaustively switch (an `assertNever`
+ * default arm on `OrgIntent.kind`) MUST add an arm for each new kind.
  */
 export const OrgIntentSchema = z.discriminatedUnion("kind", [
+  // reporting.setManager — UNCHANGED from the shipped PRD-00823 vocabulary. This
+  // PRD (00827) is purely additive: it appends unit.setParent and
+  // position.setTitle below and touches neither this arm's fields nor its types.
+  // Its `managerPositionId` is intentionally NON-NULLABLE here (an intent points
+  // a seat AT a manager); the corresponding FactMutation arm keeps it nullable so
+  // a mutation can un-set the edge. That Intent-vs-Mutation asymmetry is the
+  // original by-design shape, not something this PRD introduced or altered.
   z.object({
     kind: z.literal("reporting.setManager"),
     /** The reporting (subordinate) seat whose manager is being set. */
@@ -60,6 +81,20 @@ export const OrgIntentSchema = z.discriminatedUnion("kind", [
     /** The manager seat to report to. Non-null on an intent (un-setting is a mutation concern). */
     managerPositionId: z.string().uuid(),
   }),
+  z.object({
+    kind: z.literal("unit.setParent"),
+    /** The org unit being re-parented. */
+    unitId: z.string().uuid(),
+    /** The new parent unit, or `null` to make the unit a root (level-1) unit. */
+    parentUnitId: z.string().uuid().nullable(),
+  }),
+  z.object({
+    kind: z.literal("position.setTitle"),
+    /** The seat whose title is being set. */
+    positionId: z.string().uuid(),
+    /** The new human-facing title for the seat (non-empty, matching PositionSchema.title). */
+    title: z.string().min(1),
+  }),
 ]);
 export type OrgIntent = z.infer<typeof OrgIntentSchema>;
 
@@ -72,8 +107,19 @@ export type OrgIntent = z.infer<typeof OrgIntentSchema>;
  * 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.
+ *
+ * `unit.setParent` and `position.setTitle` mirror their intent counterparts.
+ * `unit.setParent.parentUnitId` is nullable here for the SAME reason it is on the
+ * intent — null means "root", a meaningful target — not because a mutation
+ * un-sets it. Any consumer that exhaustively switches on `FactMutation.kind`
+ * (an `assertNever` default arm) MUST add an arm for each new kind.
  */
 export const FactMutationSchema = z.discriminatedUnion("kind", [
+  // reporting.setManager — UNCHANGED from the shipped PRD-00823 vocabulary; this
+  // PRD (00827) only appends unit.setParent and position.setTitle below. Its
+  // `managerPositionId` stays NULLABLE (a mutation can un-set the edge), which is
+  // deliberately broader than the OrgIntent arm's non-nullable field — the
+  // original, intentional Intent-vs-Mutation asymmetry, preserved as-is.
   z.object({
     kind: z.literal("reporting.setManager"),
     /** The reporting (subordinate) seat whose manager edge is being written. */
@@ -81,6 +127,20 @@ export const FactMutationSchema = z.discriminatedUnion("kind", [
     /** The new manager seat, or `null` to un-set (clear) the manager edge. */
     managerPositionId: z.string().uuid().nullable(),
   }),
+  z.object({
+    kind: z.literal("unit.setParent"),
+    /** The org unit whose parent edge is being written. */
+    unitId: z.string().uuid(),
+    /** The new parent unit, or `null` to make the unit a root (level-1) unit. */
+    parentUnitId: z.string().uuid().nullable(),
+  }),
+  z.object({
+    kind: z.literal("position.setTitle"),
+    /** The seat whose title is being written. */
+    positionId: z.string().uuid(),
+    /** The new human-facing title for the seat (non-empty, matching PositionSchema.title). */
+    title: z.string().min(1),
+  }),
 ]);
 export type FactMutation = z.infer<typeof FactMutationSchema>;
 
@@ -100,6 +160,37 @@ export const TransformationOriginSchema = z.enum([
 ]);
 export type TransformationOrigin = z.infer<typeof TransformationOriginSchema>;
 
+/**
+ * Provenance — WHO/WHAT generated an intent. Distinct from motivation (the
+ * free-text {@link TransformationRequestSchema} `reason`, which records *why*)
+ * and from {@link ExecutionContextSchema} (the *run* the intent happened in).
+ * `origin` reuses the closed {@link TransformationOriginSchema} enum; the
+ * optional `sourceSystem` names the concrete system or actor that emitted it
+ * (e.g. an HRIS connector id) for machine-originated intents.
+ */
+export const ProvenanceSchema = z.object({
+  /** Provenance class of the intent — reuses the closed origin enum. */
+  origin: TransformationOriginSchema,
+  /** Optional concrete system/actor that emitted the intent. */
+  sourceSystem: z.string().optional(),
+});
+export type Provenance = z.infer<typeof ProvenanceSchema>;
+
+/**
+ * ExecutionContext — the RUN in which an intent was produced or applied. Kept
+ * separate from {@link ProvenanceSchema} (who/what generated it) and from
+ * motivation ({@link TransformationRequestSchema} `reason`). Both fields are
+ * optional: `runId` correlates the intent to a batch/job, `trigger` names what
+ * kicked off that run (e.g. a webhook or scheduled sync).
+ */
+export const ExecutionContextSchema = z.object({
+  /** Optional id correlating the intent to a batch/job run. */
+  runId: z.string().optional(),
+  /** Optional label for what kicked off the run (e.g. "scheduled_sync"). */
+  trigger: z.string().optional(),
+});
+export type ExecutionContext = z.infer<typeof ExecutionContextSchema>;
+
 export const TransformationRequestSchema = z.object({
   /** Provenance class of the request — drives how much scrutiny it gets. */
   origin: TransformationOriginSchema,
@@ -112,6 +203,12 @@ export const TransformationRequestSchema = z.object({
    * change was requested, NOT who may make it (ADR-CTRL-180).
    */
   reason: z.string().max(2000).nullable().optional(),
+  /**
+   * Optional {@link ExecutionContextSchema} — the run this intent was produced
+   * in. Additive and distinct from `origin` (provenance class) and `reason`
+   * (motivation); absent for ad-hoc requests. (ADR-CONTRACTS-074)
+   */
+  executionContext: ExecutionContextSchema.optional(),
 });
 export type TransformationRequest = z.infer<typeof TransformationRequestSchema>;
 
@@ -153,6 +250,52 @@ export const RecommendationSchema = z.object({
 });
 export type Recommendation = z.infer<typeof RecommendationSchema>;
 
+// ---------------------------------------------------------------------------
+// Finding — the general diagnostic model (superset of ConstraintViolation)
+// ---------------------------------------------------------------------------
+
+/**
+ * Severity of a {@link FindingSchema}. Broader than
+ * {@link ConstraintViolationSchema}'s `error | warning`: `info` is the added
+ * non-blocking, non-cautionary level a diagnostic-only (Observation) producer
+ * emits. `error` blocks a change; `warning` allows it but flags a caution;
+ * `info` is purely descriptive.
+ */
+export const FindingSeveritySchema = z.enum(["error", "warning", "info"]);
+export type FindingSeverity = z.infer<typeof FindingSeveritySchema>;
+
+/**
+ * A single diagnostic the system emits about the org graph — the GENERAL model
+ * of which {@link ConstraintViolationSchema} is the error-severity subtype.
+ *
+ * Finding is a structural SUPERSET of ConstraintViolation: it carries the same
+ * `code` / `severity` / `subject` fields, widens `severity` to include `info`
+ * (via {@link FindingSeveritySchema}), and adds an optional human-readable
+ * `detail` and an optional {@link RecommendationSchema} pointing at a suggested
+ * fix. Every ConstraintViolation value therefore parses as a Finding.
+ *
+ * The Constraint Engine emits the error-severity Findings today, modeled as
+ * {@link ConstraintViolationSchema} (which stays unchanged). A future
+ * Observation Engine produces the broader `info`/`warning` Findings — advisory
+ * diagnostics that describe the graph without blocking a change.
+ *
+ * @see ConstraintViolationSchema — the unchanged error-severity subtype
+ * @see ADR-CONTRACTS-074 for the org mutation / diagnostic vocabulary decision
+ */
+export const FindingSchema = z.object({
+  /** Open string naming the finding (e.g. "reporting.cycle", "span.wide"). */
+  code: z.string().min(1),
+  /** `error` blocks; `warning` cautions; `info` is purely descriptive. */
+  severity: FindingSeveritySchema,
+  /** Optional id of the entity the finding concerns. */
+  subject: z.string().optional(),
+  /** Optional human-readable elaboration of the finding. */
+  detail: z.string().optional(),
+  /** Optional suggested fix for the finding. */
+  recommendation: RecommendationSchema.optional(),
+});
+export type Finding = z.infer<typeof FindingSchema>;
+
 // ---------------------------------------------------------------------------
 // TransformStrategy — a scored set of recommendations
 // ---------------------------------------------------------------------------

package/src/org/types.ts

@@ -292,10 +292,7 @@ export interface OidcValidationResult {
   authorizationEndpoint?: string;
   error?: string;
   errorCode?:
-    | "UNREACHABLE"
-    | "INVALID_DOCUMENT"
-    | "MISSING_FIELDS"
-    | "SSRF_BLOCKED";
+    "UNREACHABLE" | "INVALID_DOCUMENT" | "MISSING_FIELDS" | "SSRF_BLOCKED";
 }
 
 /** Initiation payload for a test SSO login attempt. */

package/src/ralph/prd.ts

@@ -48,11 +48,7 @@ export type AllowedRepo = (typeof REPO_PRECEDENCE)[number];
  * Used for prioritization and verification strategy selection.
  */
 export type RalphPRDCategory =
-  | "functional"
-  | "architectural"
-  | "integration"
-  | "polish"
-  | "validation";
+  "functional" | "architectural" | "integration" | "polish" | "validation";
 
 /**
  * Priority level for feature ordering.

package/src/system/capabilities.ts

@@ -26,13 +26,7 @@ import type { DiagramNode, FlowStage } from "./index";
  * Add new repos here as the system grows.
  */
 export type RepoId =
-  | "backend"
-  | "edge"
-  | "app"
-  | "site"
-  | "ci"
-  | "contracts"
-  | "control";
+  "backend" | "edge" | "app" | "site" | "ci" | "contracts" | "control";
 
 /**
  * Semantic invariants for a capability.

package/src/system/diagram.ts

@@ -59,12 +59,7 @@ export type DiagramNodeKind = "repo" | "group" | "feature" | "artifact";
  * - feedback: Bidirectional loop
  */
 export type DiagramEdgeRelation =
-  | "invokes"
-  | "emits"
-  | "authorizes"
-  | "reads"
-  | "depends_on"
-  | "feedback";
+  "invokes" | "emits" | "authorizes" | "reads" | "depends_on" | "feedback";
 
 /**
  * Edge direction semantics.