@company-semantics/contracts 2.0.0 → 2.1.0

package/package.json

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

package/src/api/generated.ts

@@ -1747,6 +1747,43 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/users/org-chart/import": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Upload an org-chart artifact (PDF/DOCX/TXT/MD/CSV/XLSX/PNG/JPG/HEIC) for ingestion
+         * @description Accepts a multipart file upload up to 10 MB. With `?dryRun=true` the operation only reaches the validated state and writes no live rows. Returns 202 with the operationId so the caller can poll.
+         */
+        post: operations["importOrgChart"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/users/org-chart/import/{operationId}/retry": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Retry a prior org-chart import operation (cap: 3 attempts) */
+        post: operations["retryOrgChartImport"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/drive/files": {
         parameters: {
             query?: never;
@@ -3096,6 +3133,8 @@ export interface components {
             }[];
             /** @enum {string} */
             extractionStatus: "pending" | "extracting" | "complete" | "failed";
+            errorClass?: string | null;
+            errorReason?: string | null;
             createdAt: string;
             updatedAt: string;
         };
@@ -3175,7 +3214,7 @@ export interface components {
                 name: string;
                 description: string | null;
                 typeTag: string;
-                classification: ("execution_unit" | "org_container" | "custom") | null;
+                classification: ("execution_unit" | "org_container" | "leadership" | "custom") | null;
                 orderKey: string;
                 path: string;
                 /** @enum {string} */
@@ -3200,7 +3239,7 @@ export interface components {
                 name: string;
                 description: string | null;
                 typeTag: string;
-                classification: ("execution_unit" | "org_container" | "custom") | null;
+                classification: ("execution_unit" | "org_container" | "leadership" | "custom") | null;
                 orderKey: string;
                 path: string;
                 /** @enum {string} */
@@ -3227,7 +3266,7 @@ export interface components {
                 name: string;
                 description: string | null;
                 typeTag: string;
-                classification: ("execution_unit" | "org_container" | "custom") | null;
+                classification: ("execution_unit" | "org_container" | "leadership" | "custom") | null;
                 orderKey: string;
                 path: string;
                 /** @enum {string} */
@@ -3261,7 +3300,7 @@ export interface components {
                 name: string;
                 description: string | null;
                 typeTag: string;
-                classification: ("execution_unit" | "org_container" | "custom") | null;
+                classification: ("execution_unit" | "org_container" | "leadership" | "custom") | null;
                 orderKey: string;
                 path: string;
                 /** @enum {string} */
@@ -3288,7 +3327,7 @@ export interface components {
                 name: string;
                 description: string | null;
                 typeTag: string;
-                classification: ("execution_unit" | "org_container" | "custom") | null;
+                classification: ("execution_unit" | "org_container" | "leadership" | "custom") | null;
                 orderKey: string;
                 path: string;
                 /** @enum {string} */
@@ -3374,7 +3413,7 @@ export interface components {
                 name: string;
                 description: string | null;
                 typeTag: string;
-                classification: ("execution_unit" | "org_container" | "custom") | null;
+                classification: ("execution_unit" | "org_container" | "leadership" | "custom") | null;
                 orderKey: string;
                 path: string;
                 /** @enum {string} */
@@ -3424,7 +3463,7 @@ export interface components {
                 /** Format: uuid */
                 userId: string;
                 /** @enum {string} */
-                membershipRole: "member" | "manager" | "owner";
+                membershipRole: "member" | "l1_unit_owner" | "l2_unit_owner" | "l3_unit_owner" | "l4_unit_owner" | "l5_unit_owner";
                 /** Format: uuid */
                 inheritedFromUnitId: string;
                 inheritedFromUnitName: string;
@@ -3443,7 +3482,7 @@ export interface components {
                 /** Format: uuid */
                 userId: string;
                 /** @enum {string} */
-                membershipRole: "member" | "manager" | "owner";
+                membershipRole: "member" | "l1_unit_owner" | "l2_unit_owner" | "l3_unit_owner" | "l4_unit_owner" | "l5_unit_owner";
                 /** @enum {string} */
                 status: "active" | "pending" | "removed";
                 /** @enum {string} */
@@ -3464,7 +3503,7 @@ export interface components {
                 /** Format: uuid */
                 userId: string;
                 /** @enum {string} */
-                membershipRole: "member" | "manager" | "owner";
+                membershipRole: "member" | "l1_unit_owner" | "l2_unit_owner" | "l3_unit_owner" | "l4_unit_owner" | "l5_unit_owner";
                 /** @enum {string} */
                 status: "active" | "pending" | "removed";
                 /** @enum {string} */
@@ -5956,7 +5995,7 @@ export interface operations {
                     description?: string | null;
                     typeTag: string;
                     /** @enum {string} */
-                    classification?: "execution_unit" | "org_container" | "custom";
+                    classification?: "execution_unit" | "org_container" | "leadership" | "custom";
                     /** @enum {string} */
                     syncMode?: "manual_only" | "synced_readonly" | "synced_with_overrides";
                     /** @enum {string} */
@@ -6375,7 +6414,7 @@ export interface operations {
                     /** Format: uuid */
                     userId: string;
                     /** @enum {string} */
-                    role?: "member" | "manager" | "owner";
+                    role?: "member" | "l1_unit_owner" | "l2_unit_owner" | "l3_unit_owner" | "l4_unit_owner" | "l5_unit_owner";
                 };
             };
         };
@@ -6405,7 +6444,7 @@ export interface operations {
             content: {
                 "application/json": {
                     /** @enum {string} */
-                    role: "member" | "manager" | "owner";
+                    role: "member" | "l1_unit_owner" | "l2_unit_owner" | "l3_unit_owner" | "l4_unit_owner" | "l5_unit_owner";
                 };
             };
         };
@@ -6462,6 +6501,78 @@ export interface operations {
             };
         };
     };
+    importOrgChart: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "multipart/form-data": {
+                    [key: string]: unknown;
+                };
+            };
+        };
+        responses: {
+            /** @description Operation accepted; ingestion enqueued */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Upload exceeds the 10 MB size limit */
+            413: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Unsupported MIME type or declared MIME contradicts server-side sniff */
+            415: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    retryOrgChartImport: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                operationId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Retry enqueued */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Operation not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Retry limit exceeded */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     listDriveFiles: {
         parameters: {
             query?: never;

package/src/index.ts

@@ -347,6 +347,28 @@ export { ROLE_DISPLAY_MAP, VIEW_SCOPE_MAP, getViewScope, TRANSFER_RESPONSIBILITI
 // View authorization types (Phase 5 - ADR-APP-013)
 export type { AuthorizableView } from './org/index'
 
+// Authority & Delegation vocabulary (PRD-00622)
+export {
+  AuthoritySourceSchema,
+  AuthorityOriginSchema,
+  AuthorityConfidenceSchema,
+  OwnerRecordSchema,
+  OrgUnitOwnersResponseSchema,
+  DelegationSchema,
+  CreateDelegationRequestSchema,
+  DelegationListResponseSchema,
+} from './org/index'
+export type {
+  AuthoritySource,
+  AuthorityOrigin,
+  AuthorityConfidence,
+  OwnerRecord,
+  OrgUnitOwnersResponse,
+  Delegation,
+  CreateDelegationRequest,
+  DelegationListResponse,
+} from './org/index'
+
 // MCP tool discovery types
 // @see company-semantics-backend/src/interfaces/mcp/ for implementation
 export type {

package/src/org/index.ts

@@ -269,3 +269,25 @@ export type {
   UpdateOrgUnitRequest,
   UpdateOrgUnitResponse,
 } from './schemas';
+
+// Authority & Delegation vocabulary (PRD-00622)
+export {
+  AuthoritySourceSchema,
+  AuthorityOriginSchema,
+  AuthorityConfidenceSchema,
+  OwnerRecordSchema,
+  OrgUnitOwnersResponseSchema,
+  DelegationSchema,
+  CreateDelegationRequestSchema,
+  DelegationListResponseSchema,
+} from './schemas';
+export type {
+  AuthoritySource,
+  AuthorityOrigin,
+  AuthorityConfidence,
+  OwnerRecord,
+  OrgUnitOwnersResponse,
+  Delegation,
+  CreateDelegationRequest,
+  DelegationListResponse,
+} from './schemas';

package/src/org/schemas.ts

@@ -758,6 +758,79 @@ export const OrgUnitMembershipSchema = z.object({
   updatedAt: z.string(),
 });
 
+// ---------------------------------------------------------------------------
+// Authority & Delegation vocabulary (PRD-00622)
+//
+// Models effective owner attribution across the org topology: structural
+// membership (l1..l5 unit owner roles), delegated authority, manual
+// membership, and administrative override (org_admin). The `authoritySource`
+// + `authorityOrigin` pair lets UI explain *why* a user appears as an
+// owner without re-running the resolver.
+// ---------------------------------------------------------------------------
+
+export const AuthoritySourceSchema = z.enum([
+  'structural',
+  'delegated',
+  'manual_membership',
+  'org_admin',
+]);
+export type AuthoritySource = z.infer<typeof AuthoritySourceSchema>;
+
+export const AuthorityOriginSchema = z.enum([
+  'topology',
+  'delegation',
+  'administrative_override',
+]);
+export type AuthorityOrigin = z.infer<typeof AuthorityOriginSchema>;
+
+export const AuthorityConfidenceSchema = z.enum(['authoritative', 'inferred']);
+export type AuthorityConfidence = z.infer<typeof AuthorityConfidenceSchema>;
+
+export const OwnerRecordSchema = z.object({
+  userId: z.string().uuid(),
+  fullName: z.string().min(1),
+  jobTitle: z.string().nullable(),
+  slackAvatarUrl: z.string().nullable(),
+  authoritySource: AuthoritySourceSchema,
+  authorityOrigin: AuthorityOriginSchema,
+  isLocal: z.boolean(),
+  derivedFromUnitId: z.string().uuid(),
+  derivedFromUnitName: z.string().min(1).optional(),
+  derivedFromUserId: z.string().uuid().nullable().optional(),
+  derivationMetadata: z.record(z.string(), z.unknown()).optional(),
+});
+export type OwnerRecord = z.infer<typeof OwnerRecordSchema>;
+
+export const OrgUnitOwnersResponseSchema = z.object({
+  owners: z.array(OwnerRecordSchema),
+  inherited: z.array(OwnerRecordSchema).optional(),
+});
+export type OrgUnitOwnersResponse = z.infer<typeof OrgUnitOwnersResponseSchema>;
+
+export const DelegationSchema = z.object({
+  id: z.string().uuid(),
+  orgId: z.string().uuid(),
+  unitId: z.string().uuid(),
+  userId: z.string().uuid(),
+  grantedBy: z.string().uuid().nullable(),
+  grantedAt: z.string(),
+  revokedAt: z.string().nullable(),
+  status: z.enum(['active', 'revoked']),
+  note: z.string().nullable(),
+});
+export type Delegation = z.infer<typeof DelegationSchema>;
+
+export const CreateDelegationRequestSchema = z.object({
+  userId: z.string().uuid(),
+  note: z.string().max(2000).optional(),
+});
+export type CreateDelegationRequest = z.infer<typeof CreateDelegationRequestSchema>;
+
+export const DelegationListResponseSchema = z.object({
+  delegations: z.array(DelegationSchema),
+});
+export type DelegationListResponse = z.infer<typeof DelegationListResponseSchema>;
+
 export const OrgUnitRelationshipSchema = z.object({
   id: z.string().uuid(),
   orgId: z.string().uuid(),