@company-semantics/contracts 0.145.0 → 0.147.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.145.0",
+  "version": "0.147.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 = 'e00b8f6ac17d' as const;
-export const SPEC_HASH_FULL = 'e00b8f6ac17d37c793d851d3c26864d86ba8dbbf4451608615966a23d0b891ad' as const;
+export const SPEC_HASH = '390e7649da58' as const;
+export const SPEC_HASH_FULL = '390e7649da58e32271a1ad703703bc9d71ef0ec0c66c0918fc6fbd65a385d0d0' as const;

package/src/api/generated.ts

@@ -1627,6 +1627,178 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/org-units": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Create an org unit */
+        post: operations["createOrgUnit"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/org-units/{unitId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get an org unit */
+        get: operations["getOrgUnit"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/org-units/{unitId}/children": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List direct children of an org unit */
+        get: operations["listOrgUnitChildren"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/org-units/{unitId}/descendants": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List descendants of an org unit (subtree) */
+        get: operations["listOrgUnitDescendants"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/org-units/{unitId}/ancestors": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List ancestors of an org unit */
+        get: operations["listOrgUnitAncestors"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/org-units/{unitId}/reparent": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Reparent an org unit (moves the whole subtree) */
+        post: operations["reparentOrgUnit"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/org-units/{unitId}/archive": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Archive an org unit (soft-delete) */
+        post: operations["archiveOrgUnit"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/org-units/{unitId}/relationships": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List incoming + outgoing graph edges for an org unit */
+        get: operations["listOrgUnitRelationships"];
+        put?: never;
+        /** Create a graph edge from this unit */
+        post: operations["createOrgUnitRelationship"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/orgs/{orgId}/tree": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get the org tree (path-ordered snapshot) with level labels */
+        get: operations["getOrgTree"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/orgs/{orgId}/level-config": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List per-depth labels + allow_doc policy */
+        get: operations["listOrgLevelConfig"];
+        /** Replace per-depth labels + allow_doc policy */
+        put: operations["upsertOrgLevelConfig"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/drive/files": {
         parameters: {
             query?: never;
@@ -2982,7 +3154,225 @@ export interface components {
                 role: "member" | "manager" | "owner";
                 joinedAt: string;
             }[];
-            orderKey: string;
+            orderKey: string;
+        };
+        OrgUnitResponse: {
+            unit: {
+                /** Format: uuid */
+                id: string;
+                /** Format: uuid */
+                orgId: string;
+                parentId: string | null;
+                slug: string;
+                name: string;
+                description: string | null;
+                typeTag: string;
+                classification: ("execution_unit" | "org_container" | "custom") | null;
+                orderKey: string;
+                path: string;
+                /** @enum {string} */
+                syncMode: "manual_only" | "synced_readonly" | "synced_with_overrides";
+                visibilityDefault: ("public" | "private" | "restricted") | null;
+                metadata: {
+                    [key: string]: unknown;
+                };
+                archivedAt: string | null;
+                createdAt: string;
+                updatedAt: string;
+            };
+        };
+        OrgUnitChildrenResponse: {
+            /** Format: uuid */
+            parentId: string;
+            children: {
+                /** Format: uuid */
+                id: string;
+                /** Format: uuid */
+                orgId: string;
+                parentId: string | null;
+                slug: string;
+                name: string;
+                description: string | null;
+                typeTag: string;
+                classification: ("execution_unit" | "org_container" | "custom") | null;
+                orderKey: string;
+                path: string;
+                /** @enum {string} */
+                syncMode: "manual_only" | "synced_readonly" | "synced_with_overrides";
+                visibilityDefault: ("public" | "private" | "restricted") | null;
+                metadata: {
+                    [key: string]: unknown;
+                };
+                archivedAt: string | null;
+                createdAt: string;
+                updatedAt: string;
+                depth: number;
+                hasChildren: boolean;
+                memberCount: number;
+            }[];
+        };
+        OrgUnitDescendantsResponse: {
+            /** Format: uuid */
+            rootId: string;
+            descendants: {
+                /** Format: uuid */
+                id: string;
+                /** Format: uuid */
+                orgId: string;
+                parentId: string | null;
+                slug: string;
+                name: string;
+                description: string | null;
+                typeTag: string;
+                classification: ("execution_unit" | "org_container" | "custom") | null;
+                orderKey: string;
+                path: string;
+                /** @enum {string} */
+                syncMode: "manual_only" | "synced_readonly" | "synced_with_overrides";
+                visibilityDefault: ("public" | "private" | "restricted") | null;
+                metadata: {
+                    [key: string]: unknown;
+                };
+                archivedAt: string | null;
+                createdAt: string;
+                updatedAt: string;
+            }[];
+        };
+        OrgUnitAncestorsResponse: {
+            /** Format: uuid */
+            unitId: string;
+            ancestors: {
+                /** Format: uuid */
+                id: string;
+                /** Format: uuid */
+                orgId: string;
+                parentId: string | null;
+                slug: string;
+                name: string;
+                description: string | null;
+                typeTag: string;
+                classification: ("execution_unit" | "org_container" | "custom") | null;
+                orderKey: string;
+                path: string;
+                /** @enum {string} */
+                syncMode: "manual_only" | "synced_readonly" | "synced_with_overrides";
+                visibilityDefault: ("public" | "private" | "restricted") | null;
+                metadata: {
+                    [key: string]: unknown;
+                };
+                archivedAt: string | null;
+                createdAt: string;
+                updatedAt: string;
+            }[];
+        };
+        OrgUnitRelationshipsResponse: {
+            /** Format: uuid */
+            unitId: string;
+            incoming: {
+                /** Format: uuid */
+                id: string;
+                /** Format: uuid */
+                orgId: string;
+                /** Format: uuid */
+                fromUnit: string;
+                /** Format: uuid */
+                toUnit: string;
+                /** @enum {string} */
+                type: "collaborates_with" | "reports_to" | "depends_on" | "custom";
+                /** @enum {string} */
+                role: "owner" | "participant" | "supporting";
+                contextKey: string | null;
+                metadata: {
+                    [key: string]: unknown;
+                };
+                createdAt: string;
+            }[];
+            outgoing: {
+                /** Format: uuid */
+                id: string;
+                /** Format: uuid */
+                orgId: string;
+                /** Format: uuid */
+                fromUnit: string;
+                /** Format: uuid */
+                toUnit: string;
+                /** @enum {string} */
+                type: "collaborates_with" | "reports_to" | "depends_on" | "custom";
+                /** @enum {string} */
+                role: "owner" | "participant" | "supporting";
+                contextKey: string | null;
+                metadata: {
+                    [key: string]: unknown;
+                };
+                createdAt: string;
+            }[];
+        };
+        OrgUnitRelationship: {
+            /** Format: uuid */
+            id: string;
+            /** Format: uuid */
+            orgId: string;
+            /** Format: uuid */
+            fromUnit: string;
+            /** Format: uuid */
+            toUnit: string;
+            /** @enum {string} */
+            type: "collaborates_with" | "reports_to" | "depends_on" | "custom";
+            /** @enum {string} */
+            role: "owner" | "participant" | "supporting";
+            contextKey: string | null;
+            metadata: {
+                [key: string]: unknown;
+            };
+            createdAt: string;
+        };
+        OrgUnitTreeResponse: {
+            nodes: {
+                /** Format: uuid */
+                id: string;
+                /** Format: uuid */
+                orgId: string;
+                parentId: string | null;
+                slug: string;
+                name: string;
+                description: string | null;
+                typeTag: string;
+                classification: ("execution_unit" | "org_container" | "custom") | null;
+                orderKey: string;
+                path: string;
+                /** @enum {string} */
+                syncMode: "manual_only" | "synced_readonly" | "synced_with_overrides";
+                visibilityDefault: ("public" | "private" | "restricted") | null;
+                metadata: {
+                    [key: string]: unknown;
+                };
+                archivedAt: string | null;
+                createdAt: string;
+                updatedAt: string;
+                depth: number;
+                hasChildren: boolean;
+                memberCount: number;
+            }[];
+            levelConfig: {
+                /** Format: uuid */
+                orgId: string;
+                depth: number;
+                label: string;
+                allowDoc: boolean;
+                createdAt: string;
+                updatedAt: string;
+            }[];
+        };
+        OrgLevelConfigResponse: {
+            entries: {
+                /** Format: uuid */
+                orgId: string;
+                depth: number;
+                label: string;
+                allowDoc: boolean;
+                createdAt: string;
+                updatedAt: string;
+            }[];
         };
         DriveFileListResponse: {
             files: {
@@ -5736,6 +6126,324 @@ export interface operations {
             };
         };
     };
+    createOrgUnit: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** Format: uuid */
+                    parentId: string;
+                    slug: string;
+                    name: string;
+                    description?: string | null;
+                    typeTag: string;
+                    /** @enum {string} */
+                    classification?: "execution_unit" | "org_container" | "custom";
+                    /** @enum {string} */
+                    syncMode?: "manual_only" | "synced_readonly" | "synced_with_overrides";
+                    /** @enum {string} */
+                    visibilityDefault?: "public" | "private" | "restricted";
+                    metadata?: {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+        };
+        responses: {
+            /** @description Created org unit */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgUnitResponse"];
+                };
+            };
+        };
+    };
+    getOrgUnit: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Org unit */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgUnitResponse"];
+                };
+            };
+        };
+    };
+    listOrgUnitChildren: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Children of the unit */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgUnitChildrenResponse"];
+                };
+            };
+        };
+    };
+    listOrgUnitDescendants: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Descendants of the unit */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgUnitDescendantsResponse"];
+                };
+            };
+        };
+    };
+    listOrgUnitAncestors: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Ancestors of the unit */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgUnitAncestorsResponse"];
+                };
+            };
+        };
+    };
+    reparentOrgUnit: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** Format: uuid */
+                    newParentId: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Reparented unit */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgUnitResponse"];
+                };
+            };
+        };
+    };
+    archiveOrgUnit: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": Record<string, never>;
+            };
+        };
+        responses: {
+            /** @description Archived unit */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgUnitResponse"];
+                };
+            };
+        };
+    };
+    listOrgUnitRelationships: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Graph edges */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgUnitRelationshipsResponse"];
+                };
+            };
+        };
+    };
+    createOrgUnitRelationship: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** Format: uuid */
+                    toUnit: string;
+                    /** @enum {string} */
+                    type?: "collaborates_with" | "reports_to" | "depends_on" | "custom";
+                    /** @enum {string} */
+                    role?: "owner" | "participant" | "supporting";
+                    contextKey?: string | null;
+                    metadata?: {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+        };
+        responses: {
+            /** @description Created relationship */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgUnitRelationship"];
+                };
+            };
+        };
+    };
+    getOrgTree: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                orgId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Org tree snapshot */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgUnitTreeResponse"];
+                };
+            };
+        };
+    };
+    listOrgLevelConfig: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                orgId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Level config entries */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgLevelConfigResponse"];
+                };
+            };
+        };
+    };
+    upsertOrgLevelConfig: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                orgId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    entries: {
+                        depth: number;
+                        label: string;
+                        allowDoc: boolean;
+                    }[];
+                };
+            };
+        };
+        responses: {
+            /** @description Updated level config entries */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgLevelConfigResponse"];
+                };
+            };
+        };
+    };
     listDriveFiles: {
         parameters: {
             query?: never;

package/src/org/__tests__/org-units.test.ts

@@ -0,0 +1,202 @@
+import { describe, it, expect } from 'vitest';
+import {
+  OrgUnitSchema,
+  OrgUnitTreeNodeSchema,
+  OrgUnitMembershipSchema,
+  OrgUnitRelationshipSchema,
+  OrgLevelConfigSchema,
+  OrgUnitTreeResponseSchema,
+  OrgUnitChildrenResponseSchema,
+  OrgUnitRelationshipsResponseSchema,
+  OrgUnitErrorCodeSchema,
+  OrgUnitClassificationSchema,
+  OrgUnitRelationshipTypeSchema,
+  OrgUnitMembershipSourceSchema,
+} from '../schemas.js';
+
+const UUID_A = '11111111-1111-4111-8111-111111111111';
+const UUID_B = '22222222-2222-4222-8222-222222222222';
+const UUID_C = '33333333-3333-4333-8333-333333333333';
+
+const makeUnit = (overrides: Record<string, unknown> = {}) => ({
+  id: UUID_A,
+  orgId: UUID_B,
+  parentId: UUID_C,
+  slug: 'engineering',
+  name: 'Engineering',
+  description: null,
+  typeTag: 'department',
+  classification: 'org_container',
+  orderKey: 'a0',
+  path: `${UUID_B.replace(/-/g, '_')}.${UUID_A.replace(/-/g, '_')}`,
+  syncMode: 'manual_only',
+  visibilityDefault: null,
+  metadata: {},
+  archivedAt: null,
+  createdAt: '2026-04-17T00:00:00Z',
+  updatedAt: '2026-04-17T00:00:00Z',
+  ...overrides,
+});
+
+describe('OrgUnitSchema', () => {
+  it('accepts a complete unit', () => {
+    const parsed = OrgUnitSchema.parse(makeUnit());
+    expect(parsed.id).toBe(UUID_A);
+    expect(parsed.typeTag).toBe('department');
+  });
+
+  it('accepts a root unit with null parentId', () => {
+    const root = makeUnit({ parentId: null, slug: 'company', name: 'Company', typeTag: 'company' });
+    expect(() => OrgUnitSchema.parse(root)).not.toThrow();
+  });
+
+  it('accepts archived unit (archivedAt non-null)', () => {
+    const archived = makeUnit({ archivedAt: '2026-04-17T12:00:00Z' });
+    expect(() => OrgUnitSchema.parse(archived)).not.toThrow();
+  });
+
+  it('rejects invalid UUID for id', () => {
+    expect(() => OrgUnitSchema.parse(makeUnit({ id: 'not-a-uuid' }))).toThrow();
+  });
+
+  it('rejects invalid classification', () => {
+    expect(() => OrgUnitSchema.parse(makeUnit({ classification: 'bogus' }))).toThrow();
+  });
+
+  it('rejects missing required fields', () => {
+    const { name: _name, ...missingName } = makeUnit();
+    expect(() => OrgUnitSchema.parse(missingName)).toThrow();
+  });
+
+  it('round-trips unknown metadata fields verbatim', () => {
+    const parsed = OrgUnitSchema.parse(makeUnit({ metadata: { legacy_team_id: UUID_C } }));
+    expect(parsed.metadata).toEqual({ legacy_team_id: UUID_C });
+  });
+});
+
+describe('OrgUnitTreeNodeSchema', () => {
+  it('requires depth 1..5', () => {
+    const base = { ...makeUnit(), depth: 3, hasChildren: true, memberCount: 5 };
+    expect(() => OrgUnitTreeNodeSchema.parse(base)).not.toThrow();
+    expect(() => OrgUnitTreeNodeSchema.parse({ ...base, depth: 0 })).toThrow();
+    expect(() => OrgUnitTreeNodeSchema.parse({ ...base, depth: 6 })).toThrow();
+  });
+});
+
+describe('OrgUnitMembershipSchema', () => {
+  it('enforces role + status + source enums', () => {
+    const membership = {
+      id: UUID_A,
+      orgId: UUID_B,
+      unitId: UUID_C,
+      userId: UUID_A,
+      membershipRole: 'manager',
+      status: 'active',
+      source: 'google_groups',
+      sourceRef: 'eng@example.com',
+      createdAt: '2026-04-17T00:00:00Z',
+      updatedAt: '2026-04-17T00:00:00Z',
+    };
+    expect(() => OrgUnitMembershipSchema.parse(membership)).not.toThrow();
+    expect(() =>
+      OrgUnitMembershipSchema.parse({ ...membership, membershipRole: 'root' })
+    ).toThrow();
+    expect(() => OrgUnitMembershipSchema.parse({ ...membership, status: 'terminated' })).toThrow();
+  });
+});
+
+describe('OrgUnitRelationshipSchema', () => {
+  it('accepts graph edge with nullable contextKey', () => {
+    const edge = {
+      id: UUID_A,
+      orgId: UUID_B,
+      fromUnit: UUID_C,
+      toUnit: UUID_A,
+      type: 'collaborates_with' as const,
+      role: 'participant' as const,
+      contextKey: null,
+      metadata: {},
+      createdAt: '2026-04-17T00:00:00Z',
+    };
+    expect(() => OrgUnitRelationshipSchema.parse(edge)).not.toThrow();
+    expect(() =>
+      OrgUnitRelationshipSchema.parse({ ...edge, contextKey: 'infra-context' })
+    ).not.toThrow();
+  });
+});
+
+describe('OrgLevelConfigSchema', () => {
+  it('enforces depth 1..5 and non-empty label', () => {
+    const entry = {
+      orgId: UUID_B,
+      depth: 2,
+      label: 'Department',
+      allowDoc: true,
+      createdAt: '2026-04-17T00:00:00Z',
+      updatedAt: '2026-04-17T00:00:00Z',
+    };
+    expect(() => OrgLevelConfigSchema.parse(entry)).not.toThrow();
+    expect(() => OrgLevelConfigSchema.parse({ ...entry, depth: 6 })).toThrow();
+    expect(() => OrgLevelConfigSchema.parse({ ...entry, label: '' })).toThrow();
+  });
+});
+
+describe('Response schemas', () => {
+  it('OrgUnitTreeResponseSchema accepts empty tree', () => {
+    expect(() =>
+      OrgUnitTreeResponseSchema.parse({ nodes: [], levelConfig: [] })
+    ).not.toThrow();
+  });
+
+  it('OrgUnitChildrenResponseSchema wraps parentId + children array', () => {
+    expect(() =>
+      OrgUnitChildrenResponseSchema.parse({ parentId: UUID_A, children: [] })
+    ).not.toThrow();
+  });
+
+  it('OrgUnitRelationshipsResponseSchema has incoming + outgoing arrays', () => {
+    expect(() =>
+      OrgUnitRelationshipsResponseSchema.parse({
+        unitId: UUID_A,
+        incoming: [],
+        outgoing: [],
+      })
+    ).not.toThrow();
+  });
+});
+
+describe('Enum exhaustiveness', () => {
+  it('OrgUnitErrorCodeSchema enumerates all 7 known codes', () => {
+    const codes = [
+      'CYCLE_BLOCKED',
+      'DEPTH_EXCEEDED',
+      'TARGET_ARCHIVED',
+      'ROOT_HAS_NO_PARENT',
+      'PARENT_ARCHIVED',
+      'SLUG_TAKEN',
+      'CROSS_ORG_REPARENT',
+    ];
+    for (const code of codes) {
+      expect(() => OrgUnitErrorCodeSchema.parse(code)).not.toThrow();
+    }
+    expect(() => OrgUnitErrorCodeSchema.parse('OTHER')).toThrow();
+  });
+
+  it('classification enum matches backend _enums.ts', () => {
+    for (const v of ['execution_unit', 'org_container', 'custom']) {
+      expect(() => OrgUnitClassificationSchema.parse(v)).not.toThrow();
+    }
+  });
+
+  it('relationship type enum matches backend', () => {
+    for (const v of ['collaborates_with', 'reports_to', 'depends_on', 'custom']) {
+      expect(() => OrgUnitRelationshipTypeSchema.parse(v)).not.toThrow();
+    }
+  });
+
+  it('membership source enum matches backend', () => {
+    for (const v of ['manual', 'google_groups', 'scim', 'hris']) {
+      expect(() => OrgUnitMembershipSourceSchema.parse(v)).not.toThrow();
+    }
+  });
+});

package/src/org/index.ts

@@ -214,3 +214,53 @@ export type {
   OrgBudgetConfig,
   OrgUsageResponse,
 } from './schemas';
+
+// OrgUnit canonical model (ADR-BE-120)
+export type {
+  OrgUnitClassification,
+  OrgUnitSyncMode,
+  OrgUnitVisibility,
+  OrgUnitRelationshipType,
+  OrgUnitRelationshipRole,
+  OrgUnitMembershipRole,
+  OrgUnitMembershipStatus,
+  OrgUnitMembershipSource,
+  OrgUnitErrorCode,
+} from './org-units';
+export {
+  OrgUnitClassificationSchema,
+  OrgUnitSyncModeSchema,
+  OrgUnitVisibilitySchema,
+  OrgUnitRelationshipTypeSchema,
+  OrgUnitRelationshipRoleSchema,
+  OrgUnitMembershipRoleSchema,
+  OrgUnitMembershipStatusSchema,
+  OrgUnitMembershipSourceSchema,
+  OrgUnitErrorCodeSchema,
+  OrgUnitSchema,
+  OrgUnitTreeNodeSchema,
+  OrgUnitMembershipSchema,
+  OrgUnitRelationshipSchema,
+  OrgLevelConfigSchema,
+  OrgUnitResponseSchema,
+  OrgUnitTreeResponseSchema,
+  OrgUnitChildrenResponseSchema,
+  OrgUnitAncestorsResponseSchema,
+  OrgUnitDescendantsResponseSchema,
+  OrgUnitRelationshipsResponseSchema,
+  OrgLevelConfigResponseSchema,
+} from './schemas';
+export type {
+  OrgUnit,
+  OrgUnitTreeNode,
+  OrgUnitMembership,
+  OrgUnitRelationship,
+  OrgLevelConfig,
+  OrgUnitResponse,
+  OrgUnitTreeResponse,
+  OrgUnitChildrenResponse,
+  OrgUnitAncestorsResponse,
+  OrgUnitDescendantsResponse,
+  OrgUnitRelationshipsResponse,
+  OrgLevelConfigResponse,
+} from './schemas';

package/src/org/org-units.ts

@@ -0,0 +1,66 @@
+/**
+ * Org Unit Canonical Model Types
+ *
+ * Vocabulary enums for the canonical `org_units` tree + `org_unit_relationships`
+ * graph overlay. Object shapes (OrgUnit, OrgUnitMembership, ...) are owned by
+ * the Zod schemas in `./schemas` and inferred from them — see
+ * `OrgUnitSchema`, `OrgUnitMembershipSchema`, etc.
+ *
+ * Authoritative decision: ADR-BE-120. Structural invariants: INVARIANTS.md §Org Structure.
+ *
+ * Key facts a reader needs:
+ * - The tree (`OrgUnit.parentId` / `path`) is the only structural source.
+ *   The graph (`OrgUnitRelationship`) is structure-inert; never traverse
+ *   parent/child through it.
+ * - `typeTag` and `classification` are projection-only — never use for tree
+ *   traversal. Enforced by CI guards (Phase 2).
+ * - `id` is the immutable identity. `slug` is mutable presentation.
+ * - `path` is an ltree string maintained by a DB trigger; never written from
+ *   application code.
+ * - Depth is derived from `path`. `OrgLevelConfig.depth` is only a key for
+ *   per-depth labels and policy — not authoritative structure.
+ */
+
+/** Semantic classification — projection-only, never drives traversal. */
+export type OrgUnitClassification = 'execution_unit' | 'org_container' | 'custom';
+
+/** External directory reconciliation policy for a unit. */
+export type OrgUnitSyncMode = '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';
+
+/** Edge role — refines the collaboration nature on a graph edge. */
+export type OrgUnitRelationshipRole = 'owner' | 'participant' | 'supporting';
+
+/** Per-unit user role. Privilege order: owner > manager > member. */
+export type OrgUnitMembershipRole = 'member' | 'manager' | 'owner';
+
+/** Active/pending/removed lifecycle for a unit membership. */
+export type OrgUnitMembershipStatus = 'active' | 'pending' | 'removed';
+
+/** External directory origin of a membership row. */
+export type OrgUnitMembershipSource = 'manual' | 'google_groups' | 'scim' | 'hris';
+
+/**
+ * Error codes returned by `POST /api/org-units/:id/reparent` and related
+ * mutation endpoints. Clients must handle these explicitly.
+ */
+export type OrgUnitErrorCode =
+  /** newParent.path contains unit.path — would create a cycle. */
+  | 'CYCLE_BLOCKED'
+  /** Reparent would push subtree above depth 5. */
+  | 'DEPTH_EXCEEDED'
+  /** Target parent is archived; reparenting into archived subtrees is forbidden. */
+  | 'TARGET_ARCHIVED'
+  /** Attempted to set `parent_id` on a level-1 root unit. */
+  | 'ROOT_HAS_NO_PARENT'
+  /** Parent is archived on create. */
+  | 'PARENT_ARCHIVED'
+  /** Slug already taken under the target parent. */
+  | 'SLUG_TAKEN'
+  /** Attempted to reparent across orgs (or create with mismatched orgId). */
+  | 'CROSS_ORG_REPARENT';

package/src/org/schemas.ts

@@ -609,3 +609,155 @@ export const OrgUsageResponseSchema = z.object({
 });
 
 export type OrgUsageResponse = z.infer<typeof OrgUsageResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// OrgUnit canonical model (ADR-BE-120)
+// ---------------------------------------------------------------------------
+
+export const OrgUnitClassificationSchema = z.enum(['execution_unit', 'org_container', 'custom']);
+
+export const OrgUnitSyncModeSchema = z.enum([
+  'manual_only',
+  'synced_readonly',
+  'synced_with_overrides',
+]);
+
+export const OrgUnitVisibilitySchema = z.enum(['public', 'private', 'restricted']);
+
+export const OrgUnitRelationshipTypeSchema = z.enum([
+  'collaborates_with',
+  'reports_to',
+  'depends_on',
+  'custom',
+]);
+
+export const OrgUnitRelationshipRoleSchema = z.enum(['owner', 'participant', 'supporting']);
+
+export const OrgUnitMembershipRoleSchema = z.enum(['member', 'manager', 'owner']);
+
+export const OrgUnitMembershipStatusSchema = z.enum(['active', 'pending', 'removed']);
+
+export const OrgUnitMembershipSourceSchema = z.enum([
+  'manual',
+  'google_groups',
+  'scim',
+  'hris',
+]);
+
+export const OrgUnitErrorCodeSchema = z.enum([
+  'CYCLE_BLOCKED',
+  'DEPTH_EXCEEDED',
+  'TARGET_ARCHIVED',
+  'ROOT_HAS_NO_PARENT',
+  'PARENT_ARCHIVED',
+  'SLUG_TAKEN',
+  'CROSS_ORG_REPARENT',
+]);
+
+export const OrgUnitSchema = z.object({
+  id: z.string().uuid(),
+  orgId: z.string().uuid(),
+  parentId: z.string().uuid().nullable(),
+  slug: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().nullable(),
+  typeTag: z.string().min(1),
+  classification: OrgUnitClassificationSchema.nullable(),
+  orderKey: z.string().min(1),
+  path: z.string().min(1),
+  syncMode: OrgUnitSyncModeSchema,
+  visibilityDefault: OrgUnitVisibilitySchema.nullable(),
+  metadata: z.record(z.string(), z.unknown()),
+  archivedAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+export const OrgUnitTreeNodeSchema = OrgUnitSchema.extend({
+  depth: z.number().int().min(1).max(5),
+  hasChildren: z.boolean(),
+  memberCount: z.number().int().min(0),
+});
+
+export const OrgUnitMembershipSchema = z.object({
+  id: z.string().uuid(),
+  orgId: z.string().uuid(),
+  unitId: z.string().uuid(),
+  userId: z.string().uuid(),
+  membershipRole: OrgUnitMembershipRoleSchema,
+  status: OrgUnitMembershipStatusSchema,
+  source: OrgUnitMembershipSourceSchema,
+  sourceRef: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+export const OrgUnitRelationshipSchema = z.object({
+  id: z.string().uuid(),
+  orgId: z.string().uuid(),
+  fromUnit: z.string().uuid(),
+  toUnit: z.string().uuid(),
+  type: OrgUnitRelationshipTypeSchema,
+  role: OrgUnitRelationshipRoleSchema,
+  contextKey: z.string().nullable(),
+  metadata: z.record(z.string(), z.unknown()),
+  createdAt: z.string(),
+});
+
+export const OrgLevelConfigSchema = z.object({
+  orgId: z.string().uuid(),
+  depth: z.number().int().min(1).max(5),
+  label: z.string().min(1),
+  allowDoc: z.boolean(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+// --- Response schemas (request schemas live in backend per ADR-CONT-044) ---
+
+export const OrgUnitResponseSchema = z.object({ unit: OrgUnitSchema });
+
+export const OrgUnitTreeResponseSchema = z.object({
+  nodes: z.array(OrgUnitTreeNodeSchema),
+  levelConfig: z.array(OrgLevelConfigSchema),
+});
+
+export const OrgUnitChildrenResponseSchema = z.object({
+  parentId: z.string().uuid(),
+  children: z.array(OrgUnitTreeNodeSchema),
+});
+
+export const OrgUnitAncestorsResponseSchema = z.object({
+  unitId: z.string().uuid(),
+  ancestors: z.array(OrgUnitSchema),
+});
+
+export const OrgUnitDescendantsResponseSchema = z.object({
+  rootId: z.string().uuid(),
+  descendants: z.array(OrgUnitSchema),
+});
+
+export const OrgUnitRelationshipsResponseSchema = z.object({
+  unitId: z.string().uuid(),
+  incoming: z.array(OrgUnitRelationshipSchema),
+  outgoing: z.array(OrgUnitRelationshipSchema),
+});
+
+export const OrgLevelConfigResponseSchema = z.object({
+  entries: z.array(OrgLevelConfigSchema),
+});
+
+// --- Inferred types ---
+
+export type OrgUnit = z.infer<typeof OrgUnitSchema>;
+export type OrgUnitTreeNode = z.infer<typeof OrgUnitTreeNodeSchema>;
+export type OrgUnitMembership = z.infer<typeof OrgUnitMembershipSchema>;
+export type OrgUnitRelationship = z.infer<typeof OrgUnitRelationshipSchema>;
+export type OrgLevelConfig = z.infer<typeof OrgLevelConfigSchema>;
+export type OrgUnitResponse = z.infer<typeof OrgUnitResponseSchema>;
+export type OrgUnitTreeResponse = z.infer<typeof OrgUnitTreeResponseSchema>;
+export type OrgUnitChildrenResponse = z.infer<typeof OrgUnitChildrenResponseSchema>;
+export type OrgUnitAncestorsResponse = z.infer<typeof OrgUnitAncestorsResponseSchema>;
+export type OrgUnitDescendantsResponse = z.infer<typeof OrgUnitDescendantsResponseSchema>;
+export type OrgUnitRelationshipsResponse = z.infer<typeof OrgUnitRelationshipsResponseSchema>;
+export type OrgLevelConfigResponse = z.infer<typeof OrgLevelConfigResponseSchema>;