@company-semantics/contracts 62.1.0 → 62.2.0

package/package.json

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

package/src/org/README.md

@@ -335,6 +335,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `RemoveMemberRequest` _(type)_ — Request payload for removing a member from the workspace.
 - `RemoveMemberResponse` _(type)_
 - `RemoveMemberResponseSchema`
+- `ReportingErrorCode` _(type)_
+- `ReportingErrorCodeSchema` — Structured codes for reporting-line mutation rejections, surfaced as `ErrorResponse.meta.reportingCode` by…
 - `ResolveOrgDivergenceResult` _(type)_
 - `ResolveOrgDivergenceResultSchema`
 - `RoleCatalogEntry` _(type)_ — Entry in the RBAC roles catalog (GET /api/rbac/roles).

package/src/org/__tests__/position-reporting.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect } from "vitest";
 import {
   PositionReportingSchema,
   PositionReportingRelationshipTypeSchema,
+  ReportingErrorCodeSchema,
 } from "../position-reporting.js";
 
 const validEdge = {
@@ -86,3 +87,17 @@ describe("PositionReportingRelationshipTypeSchema", () => {
     ).toBe(false);
   });
 });
+
+describe("Enum exhaustiveness", () => {
+  it("ReportingErrorCodeSchema enumerates all 3 known codes", () => {
+    const codes = [
+      "REPORTING_CYCLE_BLOCKED",
+      "ENDPOINT_NOT_ON_CHART",
+      "SELF_REPORT_BLOCKED",
+    ];
+    for (const code of codes) {
+      expect(() => ReportingErrorCodeSchema.parse(code)).not.toThrow();
+    }
+    expect(() => ReportingErrorCodeSchema.parse("OTHER")).toThrow();
+  });
+});

package/src/org/index.ts

@@ -115,10 +115,12 @@ export type { PositionStatus, Position } from "./positions";
 export {
   PositionReportingRelationshipTypeSchema,
   PositionReportingSchema,
+  ReportingErrorCodeSchema,
 } from "./position-reporting";
 export type {
   PositionReportingRelationshipType,
   PositionReporting,
+  ReportingErrorCode,
 } from "./position-reporting";
 
 // Source authority: per-field ownership — who may WRITE a given entity field.

package/src/org/position-reporting.ts

@@ -61,3 +61,27 @@ export const PositionReportingSchema = z.object({
   provenance: FactProvenanceSchema.optional(),
 });
 export type PositionReporting = z.infer<typeof PositionReportingSchema>;
+
+// ---------------------------------------------------------------------------
+// ReportingErrorCode — structured rejection codes for reporting-line mutations
+// ---------------------------------------------------------------------------
+
+/**
+ * Structured codes for reporting-line mutation rejections, surfaced as
+ * `ErrorResponse.meta.reportingCode` by `PUT /api/reporting/positions/{id}/manager`
+ * and its preview twin. The top-level `error` field only carries the error
+ * class (`CONFLICT`, `VALIDATION_ERROR`), so this code is the one channel that
+ * lets a client tell a cycle 409 from a not-on-chart 409 and key per-code copy
+ * off it (the `OrgUnitErrorCode` lesson). The closed set ships all known codes
+ * at once: adding a member later is a breaking change for consumers holding an
+ * exhaustive `Record<ReportingErrorCode, …>`.
+ */
+export const ReportingErrorCodeSchema = z.enum([
+  // 409 — the edge would close a reporting cycle on the position graph.
+  "REPORTING_CYCLE_BLOCKED",
+  // 409 — an endpoint of the edge has no seat on the org chart yet.
+  "ENDPOINT_NOT_ON_CHART",
+  // 400 — a seat (or member) cannot report to itself.
+  "SELF_REPORT_BLOCKED",
+]);
+export type ReportingErrorCode = z.infer<typeof ReportingErrorCodeSchema>;