@company-semantics/contracts 6.5.0 → 7.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "6.5.0",
+  "version": "7.0.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 = 'c8a21126db6c' as const;
-export const SPEC_HASH_FULL = 'c8a21126db6c84f641327e778c710c41e539cd5f0a1272d077ec54f1a6e382b2' as const;
+export const SPEC_HASH = 'e20bec799e8f' as const;
+export const SPEC_HASH_FULL = 'e20bec799e8f8bd1a51fccbafa626fad0f4e001789ff8b13cda65847c32972f2' as const;

package/src/api/generated.ts

@@ -4078,6 +4078,7 @@ export interface components {
                     /** Format: uuid */
                     derivedFromUnitId: string;
                     derivedFromUnitName?: string;
+                    derivedFromRoot?: boolean;
                     derivedFromUserId?: string | null;
                     explanation: string;
                     derivationMetadata?: {
@@ -4104,6 +4105,7 @@ export interface components {
                     /** Format: uuid */
                     derivedFromUnitId: string;
                     derivedFromUnitName?: string;
+                    derivedFromRoot?: boolean;
                     derivedFromUserId?: string | null;
                     explanation: string;
                     derivationMetadata?: {

package/src/identity/__tests__/avatar.test.ts

@@ -36,39 +36,39 @@ describe('generateInitials', () => {
 })
 
 describe('resolveAvatar', () => {
-  it('initials is always populated when source is slack (critical invariant)', () => {
-    const result = resolveAvatar({ slackAvatarUrl: 'https://example.com/img.jpg', fullName: 'Ian Heidt' })
-    expect(result.source).toBe('slack')
+  it('initials is always populated when source is photo (critical invariant)', () => {
+    const result = resolveAvatar({ avatarUrl: 'https://example.com/img.jpg', fullName: 'Ian Heidt' })
+    expect(result.source).toBe('photo')
     expect(result.url).toBe('https://example.com/img.jpg')
     // INVARIANT: initials is ALWAYS populated, regardless of source.
-    // This prevents UI regressions when Slack avatars fail to load.
+    // This prevents UI regressions when the photo fails to load.
     expect(typeof result.initials).toBe('string')
     expect(result.initials).toBe('IH')
   })
 
-  it('returns initials source when no slackAvatarUrl', () => {
+  it('returns initials source when no avatarUrl', () => {
     const result = resolveAvatar({ fullName: 'Ian Heidt' } as any)
     expect(result.source).toBe('initials')
     expect(result.initials).toBe('IH')
     expect(result.url).toBeUndefined()
   })
 
-  it('returns slack source with empty initials when fullName is empty', () => {
-    const result = resolveAvatar({ slackAvatarUrl: 'https://example.com/img.jpg', fullName: '' })
-    expect(result.source).toBe('slack')
+  it('returns photo source with empty initials when fullName is empty', () => {
+    const result = resolveAvatar({ avatarUrl: 'https://example.com/img.jpg', fullName: '' })
+    expect(result.source).toBe('photo')
     expect(result.url).toBe('https://example.com/img.jpg')
     // Empty is valid — just not undefined
     expect(result.initials).toBe('')
   })
 
-  it('returns initials source when slackAvatarUrl is explicitly undefined', () => {
-    const result = resolveAvatar({ slackAvatarUrl: undefined, fullName: 'Ian Heidt' })
+  it('returns initials source when avatarUrl is explicitly undefined', () => {
+    const result = resolveAvatar({ avatarUrl: undefined, fullName: 'Ian Heidt' })
     expect(result.source).toBe('initials')
     expect(result.initials).toBe('IH')
   })
 
-  it('returns initials source when slackAvatarUrl is empty string (falsy)', () => {
-    const result = resolveAvatar({ slackAvatarUrl: '', fullName: 'Ian Heidt' })
+  it('returns initials source when avatarUrl is empty string (falsy)', () => {
+    const result = resolveAvatar({ avatarUrl: '', fullName: 'Ian Heidt' })
     expect(result.source).toBe('initials')
     expect(result.initials).toBe('IH')
   })

package/src/identity/avatar.ts

@@ -2,7 +2,7 @@
  * Avatar Resolution Functions
  *
  * Canonical functions for resolving user avatars.
- * Determines whether to use Slack profile photo or initials fallback.
+ * Determines whether to use a resolved profile photo or initials fallback.
  *
  * @see ADR-BE-063 for design rationale
  */
@@ -15,22 +15,22 @@ import type { UserIdentity } from './types';
 
 /**
  * Source of the resolved avatar.
- * - 'slack': Using Slack profile photo
+ * - 'photo': Using a resolved profile photo
  * - 'initials': Using generated initials (fallback)
  */
-export type AvatarSource = 'slack' | 'initials';
+export type AvatarSource = 'photo' | 'initials';
 
 /**
  * Resolved avatar for UI rendering.
  *
  * INVARIANT: initials is ALWAYS populated, regardless of source.
- * This prevents UI regressions if Slack avatar fails to load.
+ * This prevents UI regressions if the photo fails to load.
  */
 export interface ResolvedAvatar {
-  /** Source of the avatar (slack or initials) */
+  /** Source of the avatar (photo or initials) */
   source: AvatarSource;
 
-  /** Slack profile image URL (present only if source === 'slack') */
+  /** resolved photo URL (present only if source === photo) */
   url?: string;
 
   /**
@@ -85,29 +85,29 @@ export function generateInitials(fullName: string): string {
  * Returns a ResolvedAvatar with source, optional URL, and required initials.
  *
  * INVARIANT: initials is ALWAYS populated, regardless of source.
- * This ensures the UI always has a fallback if the Slack image fails to load.
+ * This ensures the UI always has a fallback if the photo fails to load.
  *
- * @param identity - Object with slackAvatarUrl and fullName fields
- * @returns ResolvedAvatar with source, url (if slack), and initials
+ * @param identity - Object with avatarUrl and fullName fields
+ * @returns ResolvedAvatar with source, url (if photo), and initials
  *
  * @example
- * // Slack avatar available
- * resolveAvatar({ slackAvatarUrl: "https://...", fullName: "Ian Heidt" })
- * // { source: 'slack', url: 'https://...', initials: 'IH' }
+ * // Photo avatar available
+ * resolveAvatar({ avatarUrl: "https://...", fullName: "Ian Heidt" })
+ * // { source: 'photo', url: 'https://...', initials: 'IH' }
  *
- * // No Slack avatar (initials fallback)
+ * // No photo avatar (initials fallback)
  * resolveAvatar({ fullName: "Ian Heidt" })
  * // { source: 'initials', initials: 'IH' }
  */
 export function resolveAvatar(
-  identity: Pick<UserIdentity, 'slackAvatarUrl' | 'fullName'>
+  identity: Pick<UserIdentity, 'avatarUrl' | 'fullName'>
 ): ResolvedAvatar {
   const initials = generateInitials(identity.fullName);
 
-  if (identity.slackAvatarUrl) {
+  if (identity.avatarUrl) {
     return {
-      source: 'slack',
-      url: identity.slackAvatarUrl,
+      source: 'photo',
+      url: identity.avatarUrl,
       initials,
     };
   }

package/src/identity/people-org-chart.ts

@@ -28,7 +28,7 @@ export const PeopleOrgChartNodeSchema = z.object({
   id: z.string().uuid(),
   fullName: z.string(),
   jobTitle: z.string().nullable(),
-  slackAvatarUrl: z.string().nullable(),
+  avatarUrl: z.string().nullable(),
   primaryUnitId: z.string().uuid().nullable(),
 });
 

package/src/identity/schemas.ts

@@ -15,7 +15,7 @@ import { z } from 'zod';
 // ---------------------------------------------------------------------------
 
 const ResolvedAvatarSchema = z.object({
-  source: z.enum(['slack', 'initials']),
+  source: z.enum(['photo', 'initials']),
   url: z.string().optional(),
   initials: z.string(),
 });

package/src/identity/types.ts

@@ -79,26 +79,46 @@ export type UserIdentity = {
   updatedAt: ISODateString;
 
   // ==========================================================================
-  // Slack Avatar Fields (ADR-BE-063)
+  // Avatar Fields (source-agnostic; see ADR-BE-063 for original Slack origin)
   // ==========================================================================
+  //
+  // The avatar model is source-agnostic: avatarUrl is the resolved profile
+  // image regardless of where it came from, avatarSource records the stored
+  // origin (if any), and avatarUpdatedAt records when it last changed. Avatar
+  // rendering depends only on avatarUrl (falling back to generated initials);
+  // avatarSource/avatarUpdatedAt are metadata for sync and audit.
 
   /**
-   * Slack user ID (set when Slack is connected and email matches).
-   * Used for efficient lookups in user_change event handling.
+   * Source-agnostic resolved profile image URL.
+   * When present, avatar resolution uses this photo (source === 'photo');
+   * otherwise it falls back to generated initials.
    */
-  slackUserId?: string;
+  avatarUrl?: string;
 
   /**
-   * Slack profile image URL (synced from Slack events).
-   * May be undefined if Slack not connected or email mismatch.
+   * Stored origin of the avatar image.
+   * Absent when there is no stored avatar (resolution falls back to initials).
+   * - 'slack': synced from a connected Slack workspace
+   * - 'upload': uploaded directly by the user
    */
-  slackAvatarUrl?: string;
+  avatarSource?: 'slack' | 'upload';
 
   /**
-   * When the Slack avatar was last synced.
+   * When the avatar was last updated (synced or uploaded).
    * Used for debugging and audit purposes.
    */
-  slackAvatarLastSyncedAt?: ISODateString;
+  avatarUpdatedAt?: ISODateString;
+
+  // ==========================================================================
+  // Slack Identity Fields (ADR-BE-063)
+  // ==========================================================================
+
+  /**
+   * Slack user ID (set when Slack is connected and email matches).
+   * Used for efficient lookups in user_change event handling.
+   * This is Slack identity, not avatar data — retained independently of avatar source.
+   */
+  slackUserId?: string;
 };
 
 // =============================================================================

package/src/org/schemas.ts

@@ -826,6 +826,14 @@ export const OwnerAuthoritySchema = z.object({
   mutability: AuthorityMutabilitySchema,
   derivedFromUnitId: z.string().uuid(),
   derivedFromUnitName: z.string().min(1).optional(),
+  /**
+   * True when this authority derives from the org ROOT unit — i.e. the holder
+   * is a CEO (a structural leader of the org root, observed locally on the root
+   * or as inherited authority on a descendant). Lets consumers classify CEO
+   * without a separate org-tree lookup, the same way `mechanism === 'rbac'`
+   * identifies an org admin. Omitted (falsy) for non-root derivations.
+   */
+  derivedFromRoot: z.boolean().optional(),
   derivedFromUserId: z.string().uuid().nullable().optional(),
   /**
    * Human-readable reason this authority applies, built at serialize time from
@@ -859,7 +867,7 @@ export const OrgUnitOwnerSchema = z.object({
   userId: z.string().uuid(),
   fullName: z.string().min(1),
   jobTitle: z.string().nullable(),
-  slackAvatarUrl: z.string().nullable(),
+  avatarUrl: z.string().nullable(),
   /** All authority grants this user holds for the unit. At least one entry. */
   authorities: z.array(OwnerAuthoritySchema).min(1),
 });