@company-semantics/contracts 62.0.0 → 62.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "62.0.0",
+  "version": "62.2.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 = '5b50d2608eb0' as const;
-export const SPEC_HASH_FULL = '5b50d2608eb090a8a020d1219d8f3ba9d99f825c72fd5f5695f9d2542f32b8a3' as const;
+export const SPEC_HASH = '8e4ad15ffd00' as const;
+export const SPEC_HASH_FULL = '8e4ad15ffd00b9b83f7adb26bd7bfdff0c03994756b3022b9dbc27f3ba9f7852' as const;

package/src/api/generated.ts

@@ -5646,8 +5646,11 @@ export interface components {
                 updatedAt: string;
                 depth: number;
                 hasChildren: boolean;
+                /** @description Accounts with a home assignment, rolled up over this unit's subtree. Legitimately 0 for a fully staffed department in an HRIS-imported org, where almost nobody has signed in — use placedPeopleCount for headcount. */
                 memberCount: number;
+                /** @description Active open roles (`open` + `hiring`) rolled up over this unit's subtree. Vacant seats only — an HRIS-imported seat is `lifecycle_owner='import:hris'` and is counted by neither this nor memberCount. */
                 openRoleCount: number;
+                /** @description Distinct people holding a live canonical seat in this unit's subtree, whether or not they have an account. Deliberately does NOT filter positions.status: an occupied `closed` seat still draws a card on the org chart, so a filter here would disagree with it. */
                 placedPeopleCount: number;
                 missingAtNextLevel: {
                     count: number;
@@ -5795,8 +5798,11 @@ export interface components {
                 updatedAt: string;
                 depth: number;
                 hasChildren: boolean;
+                /** @description Accounts with a home assignment, rolled up over this unit's subtree. Legitimately 0 for a fully staffed department in an HRIS-imported org, where almost nobody has signed in — use placedPeopleCount for headcount. */
                 memberCount: number;
+                /** @description Active open roles (`open` + `hiring`) rolled up over this unit's subtree. Vacant seats only — an HRIS-imported seat is `lifecycle_owner='import:hris'` and is counted by neither this nor memberCount. */
                 openRoleCount: number;
+                /** @description Distinct people holding a live canonical seat in this unit's subtree, whether or not they have an account. Deliberately does NOT filter positions.status: an occupied `closed` seat still draws a card on the org chart, so a filter here would disagree with it. */
                 placedPeopleCount: number;
                 missingAtNextLevel: {
                     count: number;

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

package/src/org/schemas.ts

@@ -1582,36 +1582,48 @@ export const OrgUnitTreeNodeSchema = OrgUnitSchema.extend({
   depth: z.number().int().min(1).max(5),
   hasChildren: z.boolean(),
   /**
-   * ACCOUNTS homed in this unit's subtree — a rollup of `home_assignments`,
-   * whose `user_id` is NOT NULL. A person who has never signed in therefore
-   * cannot contribute to it, and a freshly HRIS-synced org is ~93 people and
-   * one account, so this is legitimately 0 for a fully staffed department.
+   * WHAT it counts is the `.describe()` below — the single field-level
+   * description, which reaches `openapi/backend.yaml` and the generated API
+   * types. This comment carries only WHY, so the two cannot drift into
+   * disagreeing.
    *
-   * That is not a defect: it is the right population for anything that needs an
-   * account to act on — the share dialog's fanout, the unit-scoped members
-   * table. For "how many people are in this department", use
-   * {@link placedPeopleCount}. The two answer different questions and
-   * legitimately disagree (ADR-CONTRACTS-150, ADR-BE-657).
+   * Why accounts: it is the right population for anything that needs an account
+   * to act on — the share dialog's fanout, the unit-scoped members table. It is
+   * backed by `home_assignments`, whose `user_id` is NOT NULL, so an accountless
+   * person structurally cannot appear in it. Deliberately NOT redefined and NOT
+   * deprecated; {@link placedPeopleCount} answers the headcount question, and the
+   * two legitimately disagree (ADR-CONTRACTS-150, ADR-BE-657).
    */
-  memberCount: z.number().int().min(0),
+  memberCount: z
+    .number()
+    .int()
+    .min(0)
+    .describe(
+      "Accounts with a home assignment, rolled up over this unit's subtree. Legitimately 0 for a fully staffed department in an HRIS-imported org, where almost nobody has signed in — use placedPeopleCount for headcount.",
+    ),
+  /** Drives the "(N + M open)" count split in the people surfaces. */
+  openRoleCount: z
+    .number()
+    .int()
+    .min(0)
+    .describe(
+      "Active open roles (`open` + `hiring`) rolled up over this unit's subtree. Vacant seats only — an HRIS-imported seat is `lifecycle_owner='import:hris'` and is counted by neither this nor memberCount.",
+    ),
   /**
-   * Active open roles (`open` + `hiring`) rolled up over this unit's subtree,
-   * the same way `memberCount` rolls up real members. Drives the "(N + M open)"
-   * count split in the people surfaces. `memberCount` stays real-members-only.
+   * Predicate: `placement_role='canonical'`, `status <> 'ended'`, keyed by
+   * `positions.unit_id`. Placement and home are independent graphs
+   * (ADR-CTRL-159), so a person seated here may be homed elsewhere and vice
+   * versa. The `positions.status` non-filter stated in the `.describe()` below
+   * is deliberate and load-bearing — the backend pins it with a test whose name
+   * says so (ADR-BE-657).
    */
-  openRoleCount: z.number().int().min(0),
-  /**
-   * Distinct PEOPLE holding a live canonical seat in this unit's subtree —
-   * `placement_role='canonical'`, `status <> 'ended'`, keyed by
-   * `positions.unit_id`. Account linkage is not consulted, so this is the count
-   * that describes an imported workforce.
-   *
-   * Placement and home are independent graphs (ADR-CTRL-159): a person seated
-   * here may be homed elsewhere, and vice versa. Deliberately does NOT filter
-   * `positions.status` — an occupied `closed` seat still draws a card on the
-   * org chart, and a filter here would disagree with it (ADR-BE-657).
-   */
-  placedPeopleCount: z.number().int().min(0),
+  placedPeopleCount: z
+    .number()
+    .int()
+    .min(0)
+    .describe(
+      "Distinct people holding a live canonical seat in this unit's subtree, whether or not they have an account. Deliberately does NOT filter positions.status: an occupied `closed` seat still draws a card on the org chart, so a filter here would disagree with it.",
+    ),
   missingAtNextLevel: MissingAtNextLevelSchema.nullable(),
 });