@company-semantics/contracts 63.3.0 → 63.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "63.3.0",
+  "version": "63.5.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 = '191634e28786' as const;
-export const SPEC_HASH_FULL = '191634e28786b02448431968a7b8f6f3fbbcd5f5cadc9f48e3067511a790c38b' as const;
+export const SPEC_HASH = '0d2acd64eacb' as const;
+export const SPEC_HASH_FULL = '0d2acd64eacb1b9c0e7433170aa68300d2ad9197870f35b3b420f55d9e597abf' as const;

package/src/api/generated.ts

@@ -264,6 +264,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/chats/mentionable": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List the principals the chat composer may mention */
+        get: operations["listChatMentionable"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/chats/{id}": {
         parameters: {
             query?: never;
@@ -4087,6 +4104,20 @@ export interface components {
         ChatByInteractionResponse: {
             chatId: string;
         };
+        ChatMentionableResponse: {
+            items: {
+                principal: {
+                    /** @constant */
+                    kind: "user";
+                    userId: string;
+                } | {
+                    /** @constant */
+                    kind: "agent";
+                };
+                displayName: string;
+                avatarUrl: string | null;
+            }[];
+        };
         GetChatResponse: {
             chat: {
                 id: string;
@@ -4324,6 +4355,19 @@ export interface components {
                 role: "user";
                 parts: unknown[];
             };
+            mentions?: ({
+                /** @constant */
+                kind: "user";
+                /** Format: uuid */
+                userId: string;
+                startOffset: number;
+                endOffset: number;
+            } | {
+                /** @constant */
+                kind: "agent";
+                startOffset: number;
+                endOffset: number;
+            })[];
             messages?: unknown;
             runtimeProfile?: string;
             pageContext?: {
@@ -5377,6 +5421,7 @@ export interface components {
                     };
                 };
             };
+            chatMentions: boolean;
         };
         OrgStructureReviewQueue: {
             items: {
@@ -5972,7 +6017,7 @@ export interface components {
                 /** Format: uuid */
                 userId: string;
                 /** @enum {string} */
-                membershipRole: "member" | "l1_unit_owner" | "l2_unit_owner" | "l3_unit_owner" | "l4_unit_owner" | "l5_unit_owner";
+                membershipRole: "member" | "l1_unit_owner" | "l2_unit_owner" | "l3_unit_owner" | "l4_unit_owner" | "l5_unit_owner" | "l6_unit_owner" | "l7_unit_owner" | "l8_unit_owner" | "l9_unit_owner" | "l10_unit_owner" | "l11_unit_owner" | "l12_unit_owner" | "l13_unit_owner" | "l14_unit_owner" | "l15_unit_owner" | "l16_unit_owner" | "l17_unit_owner" | "l18_unit_owner" | "l19_unit_owner" | "l20_unit_owner";
                 /** Format: uuid */
                 inheritedFromUnitId: string;
                 inheritedFromUnitName: string;
@@ -6108,7 +6153,7 @@ export interface components {
                 /** Format: uuid */
                 userId: string;
                 /** @enum {string} */
-                membershipRole: "member" | "l1_unit_owner" | "l2_unit_owner" | "l3_unit_owner" | "l4_unit_owner" | "l5_unit_owner";
+                membershipRole: "member" | "l1_unit_owner" | "l2_unit_owner" | "l3_unit_owner" | "l4_unit_owner" | "l5_unit_owner" | "l6_unit_owner" | "l7_unit_owner" | "l8_unit_owner" | "l9_unit_owner" | "l10_unit_owner" | "l11_unit_owner" | "l12_unit_owner" | "l13_unit_owner" | "l14_unit_owner" | "l15_unit_owner" | "l16_unit_owner" | "l17_unit_owner" | "l18_unit_owner" | "l19_unit_owner" | "l20_unit_owner";
                 /** @enum {string} */
                 status: "active" | "pending" | "removed";
                 /** @enum {string} */
@@ -6129,7 +6174,7 @@ export interface components {
                 /** Format: uuid */
                 userId: string;
                 /** @enum {string} */
-                membershipRole: "member" | "l1_unit_owner" | "l2_unit_owner" | "l3_unit_owner" | "l4_unit_owner" | "l5_unit_owner";
+                membershipRole: "member" | "l1_unit_owner" | "l2_unit_owner" | "l3_unit_owner" | "l4_unit_owner" | "l5_unit_owner" | "l6_unit_owner" | "l7_unit_owner" | "l8_unit_owner" | "l9_unit_owner" | "l10_unit_owner" | "l11_unit_owner" | "l12_unit_owner" | "l13_unit_owner" | "l14_unit_owner" | "l15_unit_owner" | "l16_unit_owner" | "l17_unit_owner" | "l18_unit_owner" | "l19_unit_owner" | "l20_unit_owner";
                 /** @enum {string} */
                 status: "active" | "pending" | "removed";
                 /** @enum {string} */
@@ -7781,6 +7826,28 @@ export interface operations {
             };
         };
     };
+    listChatMentionable: {
+        parameters: {
+            query?: {
+                q?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The mention candidates the composer may offer */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ChatMentionableResponse"];
+                };
+            };
+        };
+    };
     getChat: {
         parameters: {
             query?: never;
@@ -11521,7 +11588,7 @@ export interface operations {
                     /** Format: uuid */
                     userId: string;
                     /** @enum {string} */
-                    role?: "member" | "l1_unit_owner" | "l2_unit_owner" | "l3_unit_owner" | "l4_unit_owner" | "l5_unit_owner";
+                    role?: "member" | "l1_unit_owner" | "l2_unit_owner" | "l3_unit_owner" | "l4_unit_owner" | "l5_unit_owner" | "l6_unit_owner" | "l7_unit_owner" | "l8_unit_owner" | "l9_unit_owner" | "l10_unit_owner" | "l11_unit_owner" | "l12_unit_owner" | "l13_unit_owner" | "l14_unit_owner" | "l15_unit_owner" | "l16_unit_owner" | "l17_unit_owner" | "l18_unit_owner" | "l19_unit_owner" | "l20_unit_owner";
                 };
             };
         };
@@ -11551,7 +11618,7 @@ export interface operations {
             content: {
                 "application/json": {
                     /** @enum {string} */
-                    role: "member" | "l1_unit_owner" | "l2_unit_owner" | "l3_unit_owner" | "l4_unit_owner" | "l5_unit_owner";
+                    role: "member" | "l1_unit_owner" | "l2_unit_owner" | "l3_unit_owner" | "l4_unit_owner" | "l5_unit_owner" | "l6_unit_owner" | "l7_unit_owner" | "l8_unit_owner" | "l9_unit_owner" | "l10_unit_owner" | "l11_unit_owner" | "l12_unit_owner" | "l13_unit_owner" | "l14_unit_owner" | "l15_unit_owner" | "l16_unit_owner" | "l17_unit_owner" | "l18_unit_owner" | "l19_unit_owner" | "l20_unit_owner";
                 };
             };
         };

package/src/generated/openapi-routes.ts

@@ -15,6 +15,7 @@ export const openApiRoutes = {
   '/api/chats': ['GET', 'POST'],
   '/api/chats/by-interaction/{interactionId}': ['GET'],
   '/api/chats/events': ['GET'],
+  '/api/chats/mentionable': ['GET'],
   '/api/chats/proactive/{eventId}': ['GET'],
   '/api/chats/{chatId}/shares': ['GET', 'POST'],
   '/api/chats/{id}': ['DELETE', 'GET', 'PATCH'],

package/src/index.ts

@@ -683,6 +683,8 @@ export {
   getViewScope,
   TRANSFER_RESPONSIBILITIES,
   IDENTITY_TRUST_LEVEL_LABELS,
+  ORG_UNIT_DESIGNED_MAX_DEPTH,
+  ORG_UNIT_ABSOLUTE_MAX_DEPTH,
 } from "./org/index";
 
 // View authorization types (Phase 5 - ADR-APP-013)

package/src/org/README.md

@@ -193,6 +193,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `MissingAtNextLevel` _(type)_
 - `MissingAtNextLevelSchema` — Active users home directly at this unit who have no level-(depth+1) home assignment within its subtree.
 - `ORG_UNITS_ROUTES` — Canonical route path constants for the `/api/org-units` surface.
+- `ORG_UNIT_ABSOLUTE_MAX_DEPTH` — Hard ceiling mirrored by the `org_units_depth_max` CHECK; ingest-only past designed.
+- `ORG_UNIT_DESIGNED_MAX_DEPTH` — Depth a human may build from scratch; the UI ceiling for a fresh org.
 - `Occupancy` _(type)_
 - `OccupancySchema`
 - `OccupancyStatus` _(type)_

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

@@ -0,0 +1,64 @@
+import { describe, it, expect } from "vitest";
+import {
+  ORG_UNIT_ABSOLUTE_MAX_DEPTH,
+  ORG_UNIT_DESIGNED_MAX_DEPTH,
+} from "../../index.js";
+import {
+  OrgLevelConfigSchema,
+  OrgUnitTreeNodeSchema,
+  UnitMembershipRoleSchema,
+} from "../schemas.js";
+
+const UUID_A = "11111111-1111-4111-8111-111111111111";
+
+describe("org-unit depth ceilings", () => {
+  it("designed stays below absolute and both reach the package root", () => {
+    expect(ORG_UNIT_DESIGNED_MAX_DEPTH).toBe(5);
+    expect(ORG_UNIT_ABSOLUTE_MAX_DEPTH).toBe(20);
+    expect(ORG_UNIT_DESIGNED_MAX_DEPTH).toBeLessThan(
+      ORG_UNIT_ABSOLUTE_MAX_DEPTH,
+    );
+  });
+
+  it("OrgLevelConfigSchema accepts every depth up to the absolute ceiling", () => {
+    const row = (depth: number) => ({
+      orgId: UUID_A,
+      depth,
+      label: "Pod",
+      labelPlural: "Pods",
+      icon: "users",
+      createdAt: "2026-01-01T00:00:00.000Z",
+      updatedAt: "2026-01-01T00:00:00.000Z",
+    });
+    expect(
+      OrgLevelConfigSchema.safeParse(row(ORG_UNIT_DESIGNED_MAX_DEPTH + 1))
+        .success,
+    ).toBe(true);
+    expect(
+      OrgLevelConfigSchema.safeParse(row(ORG_UNIT_ABSOLUTE_MAX_DEPTH)).success,
+    ).toBe(true);
+    expect(
+      OrgLevelConfigSchema.safeParse(row(ORG_UNIT_ABSOLUTE_MAX_DEPTH + 1))
+        .success,
+    ).toBe(false);
+  });
+
+  it("OrgUnitTreeNodeSchema bounds depth by the absolute ceiling, not the designed one", () => {
+    const shape = OrgUnitTreeNodeSchema.shape.depth;
+    expect(shape.safeParse(ORG_UNIT_DESIGNED_MAX_DEPTH + 1).success).toBe(true);
+    expect(shape.safeParse(ORG_UNIT_ABSOLUTE_MAX_DEPTH).success).toBe(true);
+    expect(shape.safeParse(ORG_UNIT_ABSOLUTE_MAX_DEPTH + 1).success).toBe(
+      false,
+    );
+  });
+
+  it("carries one unit-owner membership role per depth up to the absolute ceiling", () => {
+    const owners = UnitMembershipRoleSchema.options.filter(
+      (r) => r !== "member",
+    );
+    expect(owners).toHaveLength(ORG_UNIT_ABSOLUTE_MAX_DEPTH);
+    for (let depth = 1; depth <= ORG_UNIT_ABSOLUTE_MAX_DEPTH; depth++) {
+      expect(owners).toContain(`l${depth}_unit_owner`);
+    }
+  });
+});

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

@@ -90,7 +90,7 @@ describe("OrgUnitSchema", () => {
 });
 
 describe("OrgUnitTreeNodeSchema", () => {
-  it("requires depth 1..5", () => {
+  it("requires depth 1..20 (absolute ceiling)", () => {
     const base = {
       ...makeUnit(),
       depth: 3,
@@ -102,7 +102,10 @@ describe("OrgUnitTreeNodeSchema", () => {
     };
     expect(() => OrgUnitTreeNodeSchema.parse(base)).not.toThrow();
     expect(() => OrgUnitTreeNodeSchema.parse({ ...base, depth: 0 })).toThrow();
-    expect(() => OrgUnitTreeNodeSchema.parse({ ...base, depth: 6 })).toThrow();
+    expect(() =>
+      OrgUnitTreeNodeSchema.parse({ ...base, depth: 6 }),
+    ).not.toThrow();
+    expect(() => OrgUnitTreeNodeSchema.parse({ ...base, depth: 21 })).toThrow();
   });
 
   it("requires a non-negative openRoleCount", () => {
@@ -277,7 +280,7 @@ describe("OrgUnitRelationshipSchema", () => {
 });
 
 describe("OrgLevelConfigSchema", () => {
-  it("enforces depth 1..5, non-empty-when-present label/labelPlural, and icon enum", () => {
+  it("enforces depth 1..20, non-empty-when-present label/labelPlural, and icon enum", () => {
     const entry = {
       orgId: UUID_B,
       depth: 2,
@@ -296,7 +299,10 @@ describe("OrgLevelConfigSchema", () => {
         icon: null,
       }),
     ).not.toThrow();
-    expect(() => OrgLevelConfigSchema.parse({ ...entry, depth: 6 })).toThrow();
+    expect(() =>
+      OrgLevelConfigSchema.parse({ ...entry, depth: 6 }),
+    ).not.toThrow();
+    expect(() => OrgLevelConfigSchema.parse({ ...entry, depth: 21 })).toThrow();
     expect(() => OrgLevelConfigSchema.parse({ ...entry, label: "" })).toThrow();
     expect(() =>
       OrgLevelConfigSchema.parse({ ...entry, labelPlural: "" }),

package/src/org/company-md.ts

@@ -144,9 +144,9 @@ export interface CompanyMdNodeIdentity {
    * docs/goals/sources/maps that are not owned by a unit).
    *
    * Prefer this over `level` for structural reasoning. `level` is retained for
-   * backward compatibility and is @deprecated.
+   * backward compatibility and is @deprecated. Bounded 1..`ORG_UNIT_ABSOLUTE_MAX_DEPTH`.
    */
-  readonly depth: 1 | 2 | 3 | 4 | 5 | null;
+  readonly depth: number | null;
   readonly parentId: string | null;
   readonly visibility: CompanyMdVisibility;
   /**

package/src/org/index.ts

@@ -498,6 +498,10 @@ export type {
   OrgTreeResponse,
 } from "./org-units";
 export { ORG_UNITS_ROUTES } from "./org-units";
+export {
+  ORG_UNIT_DESIGNED_MAX_DEPTH,
+  ORG_UNIT_ABSOLUTE_MAX_DEPTH,
+} from "./org-depth";
 export {
   OrgUnitClassificationSchema,
   OrgUnitSyncModeSchema,

package/src/org/org-depth.ts

@@ -0,0 +1,51 @@
+/**
+ * Org-unit tree depth ceilings.
+ *
+ * Depth counts the org root as 1 (`nlevel(org_units.path)`). Two ceilings,
+ * deliberately distinct (backend ADR: org-unit depth, designed vs absolute):
+ *
+ * - {@link ORG_UNIT_DESIGNED_MAX_DEPTH} is the depth a human can build from
+ *   scratch. The UI's "+ New child", "Add level" and drag-reparent, and the
+ *   server's default (`designed`) depth policy, never deepen an org past
+ *   `max(DESIGNED, the org's current deepest unit)`.
+ * - {@link ORG_UNIT_ABSOLUTE_MAX_DEPTH} mirrors the database CHECK
+ *   (`org_units_depth_max`). Only ingest (structure inference apply, HRIS sync,
+ *   org-chart import) runs under the `absolute` policy and may deepen an org
+ *   past the designed depth, up to this bound. Nothing exceeds it.
+ *
+ * Both are compile-time constants, not per-org configuration.
+ */
+
+/** Depth a human may build from scratch; the UI ceiling for a fresh org. */
+export const ORG_UNIT_DESIGNED_MAX_DEPTH = 5;
+
+/** Hard ceiling mirrored by the `org_units_depth_max` CHECK; ingest-only past designed. */
+export const ORG_UNIT_ABSOLUTE_MAX_DEPTH = 20;
+
+/**
+ * The positional unit-owner membership roles, one per depth 1..absolute. Spelled
+ * out rather than generated so each member stays a string literal type; the
+ * schema that consumes it (`UnitMembershipRoleSchema`) adds `member` in front.
+ */
+export const UNIT_OWNER_MEMBERSHIP_ROLES = [
+  "l1_unit_owner",
+  "l2_unit_owner",
+  "l3_unit_owner",
+  "l4_unit_owner",
+  "l5_unit_owner",
+  "l6_unit_owner",
+  "l7_unit_owner",
+  "l8_unit_owner",
+  "l9_unit_owner",
+  "l10_unit_owner",
+  "l11_unit_owner",
+  "l12_unit_owner",
+  "l13_unit_owner",
+  "l14_unit_owner",
+  "l15_unit_owner",
+  "l16_unit_owner",
+  "l17_unit_owner",
+  "l18_unit_owner",
+  "l19_unit_owner",
+  "l20_unit_owner",
+] as const;

package/src/org/org-units.ts

@@ -18,7 +18,8 @@
  * - `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.
+ *   per-depth labels and policy — not authoritative structure. Ceilings live in
+ *   `./org-depth` (designed 5, absolute 20; ingest-only past designed).
  */
 
 /** Semantic classification — projection-only, never drives traversal. */
@@ -113,7 +114,7 @@ export type { OrgUnitTreeResponse as OrgTreeResponse } from "./schemas";
 export type OrgUnitErrorCode =
   /** newParent.path contains unit.path — would create a cycle. */
   | "CYCLE_BLOCKED"
-  /** Reparent would push subtree above depth 5. */
+  /** Create/reparent would push the subtree past the effective depth ceiling (`./org-depth`). */
   | "DEPTH_EXCEEDED"
   /** Target parent is archived; reparenting into archived subtrees is forbidden. */
   | "TARGET_ARCHIVED"

package/src/org/schemas.ts

@@ -14,6 +14,10 @@ import { z } from "zod";
 import { CursorPageSchema, IsoDateTime } from "../api/primitives";
 import { OrgChartRoleSchema } from "../permissions/orgchart-roles";
 import { PositionRefSchema } from "../identity/position-ref";
+import {
+  ORG_UNIT_ABSOLUTE_MAX_DEPTH,
+  UNIT_OWNER_MEMBERSHIP_ROLES,
+} from "./org-depth";
 
 // ---------------------------------------------------------------------------
 // Sub-schemas
@@ -1496,15 +1500,12 @@ export const OrgUnitRelationshipRoleSchema = z.enum([
 /**
  * Positional slot a member holds in the org-unit tree. ORTHOGONAL to the
  * `OrgChartRole` policy vocabulary (this is an INPUT to authority resolution,
- * not the derived policy role). Level is encoded in the value (l1…l5).
+ * not the derived policy role). Level is encoded in the value (l1…l20, one
+ * per depth up to `ORG_UNIT_ABSOLUTE_MAX_DEPTH`).
  */
 export const UnitMembershipRoleSchema = z.enum([
   "member",
-  "l1_unit_owner",
-  "l2_unit_owner",
-  "l3_unit_owner",
-  "l4_unit_owner",
-  "l5_unit_owner",
+  ...UNIT_OWNER_MEMBERSHIP_ROLES,
 ]);
 
 export type UnitMembershipRole = z.infer<typeof UnitMembershipRoleSchema>;
@@ -1579,7 +1580,7 @@ export const MissingAtNextLevelSchema = z.object({
 });
 
 export const OrgUnitTreeNodeSchema = OrgUnitSchema.extend({
-  depth: z.number().int().min(1).max(5),
+  depth: z.number().int().min(1).max(ORG_UNIT_ABSOLUTE_MAX_DEPTH),
   hasChildren: z.boolean(),
   /**
    * WHAT it counts is the `.describe()` below — the single field-level
@@ -1871,7 +1872,7 @@ export const OrgLevelIconSchema = z.enum([
 
 export const OrgLevelConfigSchema = z.object({
   orgId: z.string().uuid(),
-  depth: z.number().int().min(1).max(5),
+  depth: z.number().int().min(1).max(ORG_UNIT_ABSOLUTE_MAX_DEPTH),
   label: z.string().min(1).nullable(),
   labelPlural: z.string().min(1).nullable(),
   icon: OrgLevelIconSchema.nullable(),
@@ -2132,6 +2133,11 @@ export const CapabilitiesResponseSchema = z.object({
         .optional(),
     })
     .optional(),
+  // Gates the chat composer's mention affordance (PRD-00988). Optional for the
+  // same rollout symmetry as the action sub-objects above: a backend that does
+  // not yet derive the flag must still validate its own response, and the spec
+  // already carried the field before this schema did.
+  chatMentions: z.boolean().optional(),
 });
 
 export type FieldCapability = z.infer<typeof FieldCapabilitySchema>;