@company-semantics/contracts 0.60.2 → 0.61.0

package/package.json

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

package/src/chat/index.ts

@@ -24,8 +24,25 @@ export type {
   ChatSummaryExtended,
   TitleGenerationRequest,
   TitleGenerationResponse,
+  // Event system types
+  BaseEvent,
+  InvalidationReason,
+  ChatChangedField,
+  // Domain events (carry full state)
+  ChatCreatedEvent,
+  ChatUpdatedEvent,
+  ChatDeletedEvent,
+  ChatDomainEvent,
+  // Invalidation events (staleness signals)
+  InvalidateChatEvent,
+  InvalidateChatListEvent,
+  ChatInvalidationEvent,
+  // SSE event unions
   ChatSseEvent,
   ChatUpdateEvent,
-  // Chat creation event (server-first navigation contract)
-  ChatCreatedEvent,
+  // Legacy types (deprecated, for migration)
+  LegacyChatCreatedEvent,
+  LegacyChatInvalidatedEvent,
+  LegacyChatListInvalidatedEvent,
+  LegacyChatSseEvent,
 } from './types'

package/src/chat/types.ts

@@ -169,14 +169,44 @@ export interface TitleGenerationResponse {
   isAutoGenerated: boolean
 }
 
+// =============================================================================
+// Event System Types
+// =============================================================================
+
+/**
+ * Base envelope for all SSE events.
+ *
+ * INV-EVENT-ORDER-1: Domain events for a given entity are emitted in commit order.
+ *                    Clients may assume monotonic updatedAt.
+ * INV-EVENT-IDEMPOTENT: Clients must treat events as idempotent. Full payload
+ *                       replacement handles duplicate events naturally.
+ * INV-EVENT-CONVERGENCE: Clients must assume events may be missed during SSE
+ *                        disconnects. Invalidation events ensure convergence.
+ */
+export interface BaseEvent {
+  /** Protocol version for forward compatibility */
+  v: 1
+  /** ISO 8601 timestamp when event was created */
+  timestamp: string
+  /** Optional event ID for telemetry/debugging (not for deduplication logic) */
+  eventId?: string
+}
+
 /**
- * SSE event types for chat updates (convention locked).
- * Client receives these and handles accordingly.
+ * Reason for cache invalidation.
+ * INV-REASON-TELEMETRY: This is for telemetry only. UI behavior must be
+ *                       identical regardless of reason. Do not branch on this.
  */
-export type ChatSseEvent =
-  | { type: 'chat.invalidated'; chatId: string; timestamp: string }
-  | { type: 'chat.list.invalidated'; timestamp: string }
-  | ChatCreatedEvent
+export type InvalidationReason = 'external-mutation' | 'bulk-operation' | 'sync-required'
+
+/**
+ * Fields that can change on a chat, used in changed[] array.
+ */
+export type ChatChangedField = 'title' | 'titleSource' | 'status' | 'pinnedAt'
+
+// =============================================================================
+// Domain Events (past-tense facts, carry full state)
+// =============================================================================
 
 /**
  * Emitted exactly once after a chat is successfully persisted.
@@ -185,18 +215,152 @@ export type ChatSseEvent =
  * INV-EVENT-1: This event is emitted exactly once per successful stream.
  * INV-PERSIST-1: Chat record + messages are committed atomically before this event.
  */
-export interface ChatCreatedEvent {
+export interface ChatCreatedEvent extends BaseEvent {
+  type: 'chat.created'
+  data: {
+    /** Canonical server-generated UUID - use this for URLs */
+    chatId: string
+    /** Client-provided ID for correlation (optional) */
+    interactionId?: string
+    /** Chat title */
+    title: string
+    /** How the title was set */
+    titleSource: TitleSource
+    /** Chat status */
+    status: ChatStatus
+    /** When pinned (null if not pinned) */
+    pinnedAt: string | null
+    /** Message count */
+    messageCount: number
+    /** ISO timestamp */
+    createdAt: string
+    /** ISO timestamp */
+    updatedAt: string
+    /** Whether chat is shared */
+    isShared: boolean
+  }
+}
+
+/**
+ * Emitted when chat metadata changes (title, pin, archive, etc.)
+ * Carries full current state - clients should replace local state entirely.
+ */
+export interface ChatUpdatedEvent extends BaseEvent {
+  type: 'chat.updated'
+  data: {
+    chatId: string
+    title: string
+    titleSource: TitleSource | null
+    titleGeneratedAt: string | null
+    status: ChatStatus
+    pinnedAt: string | null
+    messageCount: number
+    createdAt: string
+    updatedAt: string
+    isShared: boolean
+  }
+  /** What fields changed - for UI optimization only */
+  changed: ChatChangedField[]
+}
+
+/**
+ * Emitted when a chat is deleted.
+ */
+export interface ChatDeletedEvent extends BaseEvent {
+  type: 'chat.deleted'
+  data: {
+    chatId: string
+  }
+}
+
+// =============================================================================
+// Invalidation Events (staleness signals)
+// =============================================================================
+
+/**
+ * Single-entity staleness signal.
+ * Emitted when a specific chat may be out of sync (e.g., external mutation).
+ */
+export interface InvalidateChatEvent extends BaseEvent {
+  type: 'invalidate.chat'
+  chatId: string
+  reason: InvalidationReason
+}
+
+/**
+ * Collection staleness signal.
+ * Emitted when chat list ordering/filtering may be stale.
+ */
+export interface InvalidateChatListEvent extends BaseEvent {
+  type: 'invalidate.chat-list'
+  reason: InvalidationReason
+}
+
+// =============================================================================
+// SSE Event Union
+// =============================================================================
+
+/**
+ * All domain events that carry full state.
+ */
+export type ChatDomainEvent = ChatCreatedEvent | ChatUpdatedEvent | ChatDeletedEvent
+
+/**
+ * All invalidation events that signal staleness.
+ */
+export type ChatInvalidationEvent = InvalidateChatEvent | InvalidateChatListEvent
+
+/**
+ * SSE event types for chat updates.
+ * Client receives these via SSE and handles accordingly.
+ */
+export type ChatSseEvent = ChatDomainEvent | ChatInvalidationEvent
+
+/**
+ * Convenience alias for backwards compat.
+ */
+export type ChatUpdateEvent = ChatSseEvent
+
+// =============================================================================
+// Legacy Event Types (deprecated, for migration period only)
+// =============================================================================
+
+/**
+ * @deprecated Use ChatCreatedEvent with v:1 instead.
+ * Legacy event shape without v field or data wrapper.
+ */
+export interface LegacyChatCreatedEvent {
   type: 'chat.created'
-  /** Canonical server-generated UUID - use this for URLs */
   chatId: string
-  /** Client-provided ID for correlation (optional) */
   interactionId?: string
-  /** Auto-generated title from first message */
   title?: string
   timestamp: string
 }
 
 /**
- * Convenience alias for backwards compat.
+ * @deprecated Use InvalidateChatEvent instead.
+ * Legacy invalidation event without v field.
  */
-export type ChatUpdateEvent = ChatSseEvent
+export interface LegacyChatInvalidatedEvent {
+  type: 'chat.invalidated'
+  chatId: string
+  timestamp: string
+}
+
+/**
+ * @deprecated Use InvalidateChatListEvent instead.
+ * Legacy list invalidation event without v field.
+ */
+export interface LegacyChatListInvalidatedEvent {
+  type: 'chat.list.invalidated'
+  timestamp: string
+}
+
+/**
+ * @deprecated Use ChatSseEvent instead.
+ * Legacy SSE event union for migration period.
+ */
+export type LegacyChatSseEvent =
+  | LegacyChatInvalidatedEvent
+  | LegacyChatListInvalidatedEvent
+  | LegacyChatCreatedEvent