@company-semantics/contracts 2.1.0 → 2.2.0

package/package.json

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

package/src/api/generated.ts

@@ -1678,6 +1678,57 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/org-units/{unitId}/owners": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List owners of an org unit (local by default; inherited when ?explain=true) */
+        get: operations["listOrgUnitOwners"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/org-units/{unitId}/delegations": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Grant an explicit delegation to a user on an org unit */
+        post: operations["createOrgUnitDelegation"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/org-units/{unitId}/delegations/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        /** Revoke an existing delegation by id */
+        delete: operations["deleteOrgUnitDelegation"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/org-units/{unitId}/memberships": {
         parameters: {
             query?: never;
@@ -3469,6 +3520,62 @@ export interface components {
                 inheritedFromUnitName: string;
             }[];
         };
+        OrgUnitOwnersResponse: {
+            owners: {
+                /** Format: uuid */
+                userId: string;
+                fullName: string;
+                jobTitle: string | null;
+                slackAvatarUrl: string | null;
+                /** @enum {string} */
+                authoritySource: "structural" | "delegated" | "manual_membership" | "org_admin";
+                /** @enum {string} */
+                authorityOrigin: "topology" | "delegation" | "administrative_override";
+                isLocal: boolean;
+                /** Format: uuid */
+                derivedFromUnitId: string;
+                derivedFromUnitName?: string;
+                derivedFromUserId?: string | null;
+                derivationMetadata?: {
+                    [key: string]: unknown;
+                };
+            }[];
+            inherited?: {
+                /** Format: uuid */
+                userId: string;
+                fullName: string;
+                jobTitle: string | null;
+                slackAvatarUrl: string | null;
+                /** @enum {string} */
+                authoritySource: "structural" | "delegated" | "manual_membership" | "org_admin";
+                /** @enum {string} */
+                authorityOrigin: "topology" | "delegation" | "administrative_override";
+                isLocal: boolean;
+                /** Format: uuid */
+                derivedFromUnitId: string;
+                derivedFromUnitName?: string;
+                derivedFromUserId?: string | null;
+                derivationMetadata?: {
+                    [key: string]: unknown;
+                };
+            }[];
+        };
+        Delegation: {
+            /** Format: uuid */
+            id: string;
+            /** Format: uuid */
+            orgId: string;
+            /** Format: uuid */
+            unitId: string;
+            /** Format: uuid */
+            userId: string;
+            grantedBy: string | null;
+            grantedAt: string;
+            revokedAt: string | null;
+            /** @enum {string} */
+            status: "active" | "revoked";
+            note: string | null;
+        };
         OrgUnitMembershipListResponse: {
             /** Format: uuid */
             unitId: string;
@@ -6377,6 +6484,79 @@ export interface operations {
             };
         };
     };
+    listOrgUnitOwners: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Owners hydrated with profile fields. Includes `inherited` when ?explain=true. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgUnitOwnersResponse"];
+                };
+            };
+        };
+    };
+    createOrgUnitDelegation: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** Format: uuid */
+                    userId: string;
+                    note?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Created delegation row */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Delegation"];
+                };
+            };
+        };
+    };
+    deleteOrgUnitDelegation: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Delegation revoked */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     listOrgUnitMemberships: {
         parameters: {
             query?: never;

package/src/index.ts

@@ -347,12 +347,16 @@ 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)
+// Authority & Delegation vocabulary
 export {
   AuthoritySourceSchema,
   AuthorityOriginSchema,
   AuthorityConfidenceSchema,
-  OwnerRecordSchema,
+  AuthorityMechanismSchema,
+  AuthorityLocalitySchema,
+  AuthorityMutabilitySchema,
+  OwnerAuthoritySchema,
+  OrgUnitOwnerSchema,
   OrgUnitOwnersResponseSchema,
   DelegationSchema,
   CreateDelegationRequestSchema,
@@ -362,7 +366,11 @@ export type {
   AuthoritySource,
   AuthorityOrigin,
   AuthorityConfidence,
-  OwnerRecord,
+  AuthorityMechanism,
+  AuthorityLocality,
+  AuthorityMutability,
+  OwnerAuthority,
+  OrgUnitOwner,
   OrgUnitOwnersResponse,
   Delegation,
   CreateDelegationRequest,

package/src/org/index.ts

@@ -270,12 +270,16 @@ export type {
   UpdateOrgUnitResponse,
 } from './schemas';
 
-// Authority & Delegation vocabulary (PRD-00622)
+// Authority & Delegation vocabulary
 export {
   AuthoritySourceSchema,
   AuthorityOriginSchema,
   AuthorityConfidenceSchema,
-  OwnerRecordSchema,
+  AuthorityMechanismSchema,
+  AuthorityLocalitySchema,
+  AuthorityMutabilitySchema,
+  OwnerAuthoritySchema,
+  OrgUnitOwnerSchema,
   OrgUnitOwnersResponseSchema,
   DelegationSchema,
   CreateDelegationRequestSchema,
@@ -285,7 +289,11 @@ export type {
   AuthoritySource,
   AuthorityOrigin,
   AuthorityConfidence,
-  OwnerRecord,
+  AuthorityMechanism,
+  AuthorityLocality,
+  AuthorityMutability,
+  OwnerAuthority,
+  OrgUnitOwner,
   OrgUnitOwnersResponse,
   Delegation,
   CreateDelegationRequest,

package/src/org/schemas.ts

@@ -759,19 +759,25 @@ export const OrgUnitMembershipSchema = z.object({
 });
 
 // ---------------------------------------------------------------------------
-// Authority & Delegation vocabulary (PRD-00622)
+// Authority & Delegation vocabulary
 //
-// 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.
+// The API expresses authority as orthogonal axes (mechanism × locality ×
+// mutability) instead of a single overloaded `source` enum, so future
+// combinations like inherited-delegated or hris-delegated compose by
+// construction rather than forcing each consumer to add a new switch case.
+// The engine's internal AuthoritySource enum stays narrower than the wire
+// shape — it's debug/audit vocabulary, not API vocabulary.
 // ---------------------------------------------------------------------------
 
+/**
+ * Engine-internal authority source. Used by the projection storage layer for
+ * debugging and drift records; not part of the public API response shape.
+ * `manual_membership` was removed when the legacy `l{N}_unit_owner` track was
+ * canonicalized onto delegations.
+ */
 export const AuthoritySourceSchema = z.enum([
   'structural',
   'delegated',
-  'manual_membership',
   'org_admin',
 ]);
 export type AuthoritySource = z.infer<typeof AuthoritySourceSchema>;
@@ -786,24 +792,79 @@ 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(),
+/** How the authority arose. */
+export const AuthorityMechanismSchema = z.enum([
+  'structural',
+  'delegated',
+  'rbac',
+]);
+export type AuthorityMechanism = z.infer<typeof AuthorityMechanismSchema>;
+
+/** Whether the grant lives on the target unit or is inherited from an ancestor. */
+export const AuthorityLocalitySchema = z.enum(['local', 'inherited']);
+export type AuthorityLocality = z.infer<typeof AuthorityLocalitySchema>;
+
+/**
+ * Whether the user can change this authority from this surface.
+ *  - `derived`: change the upstream source instead (the org chart, RBAC roles).
+ *  - `user_managed`: removable from this UI.
+ */
+export const AuthorityMutabilitySchema = z.enum(['derived', 'user_managed']);
+export type AuthorityMutability = z.infer<typeof AuthorityMutabilitySchema>;
+
+export const OwnerAuthoritySchema = z.object({
+  mechanism: AuthorityMechanismSchema,
+  locality: AuthorityLocalitySchema,
+  mutability: AuthorityMutabilitySchema,
   derivedFromUnitId: z.string().uuid(),
   derivedFromUnitName: z.string().min(1).optional(),
   derivedFromUserId: z.string().uuid().nullable().optional(),
+  /**
+   * Human-readable reason this authority applies, built at serialize time from
+   * the strategy's derivation metadata. Foundation for trust UI, debugging,
+   * AI explainability, governance reports, and audits.
+   */
+  explanation: z.string(),
+  /**
+   * Strategy-specific structured metadata, preserved verbatim for tooling that
+   * needs more than the explanation string (drift detection, audits).
+   */
   derivationMetadata: z.record(z.string(), z.unknown()).optional(),
+  /**
+   * `org_unit_delegations.id` when `mechanism === 'delegated'`. Surfaced
+   * separately so the UI doesn't need to inspect derivationMetadata to render
+   * the revoke action.
+   */
+  delegationId: z.string().uuid().optional(),
+});
+export type OwnerAuthority = z.infer<typeof OwnerAuthoritySchema>;
+
+export const OrgUnitOwnerSchema = z.object({
+  userId: z.string().uuid(),
+  fullName: z.string().min(1),
+  jobTitle: z.string().nullable(),
+  slackAvatarUrl: z.string().nullable(),
+  /** All authority grants this user holds for the unit. At least one entry. */
+  authorities: z.array(OwnerAuthoritySchema).min(1),
 });
-export type OwnerRecord = z.infer<typeof OwnerRecordSchema>;
+export type OrgUnitOwner = z.infer<typeof OrgUnitOwnerSchema>;
+
+/**
+ * Contract-level invariant: each owner list contains each userId at most once.
+ * Duplicate userIds are a serializer bug, not a presentation concern, so we
+ * fail Zod parse at the API boundary on both server and client.
+ */
+const uniqueByUserId = (arr: ReadonlyArray<{ userId: string }>): boolean =>
+  new Set(arr.map((o) => o.userId)).size === arr.length;
 
 export const OrgUnitOwnersResponseSchema = z.object({
-  owners: z.array(OwnerRecordSchema),
-  inherited: z.array(OwnerRecordSchema).optional(),
+  owners: z
+    .array(OrgUnitOwnerSchema)
+    .refine(uniqueByUserId, { message: 'duplicate userId in owners' }),
+  inherited: z
+    .array(OrgUnitOwnerSchema)
+    .refine(uniqueByUserId, { message: 'duplicate userId in inherited' })
+    .optional(),
 });
 export type OrgUnitOwnersResponse = z.infer<typeof OrgUnitOwnersResponseSchema>;