@company-semantics/contracts 0.106.0 → 0.107.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.106.0",
+  "version": "0.107.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -90,6 +90,9 @@
   "engines": {
     "node": "22.x"
   },
+  "dependencies": {
+    "zod": "^4.2.1"
+  },
   "devDependencies": {
     "@types/node": "^25.0.3",
     "husky": "^9.1.7",

package/src/chat/index.ts

@@ -40,6 +40,33 @@ export type {
   ChatSseEvent,
 } from './types'
 
+// =============================================================================
+// Schemas (Zod runtime validation)
+// =============================================================================
+
+export {
+  IsoDateString,
+  ChatVisibilitySchema,
+  TitleSourceSchema,
+  InvalidationReasonSchema,
+  ChatChangedFieldSchema,
+  ChatSummarySchema,
+  ChatSummaryExtendedSchema,
+  TitleGenerationResponseSchema,
+  SharedChatMessageSchema,
+  ChatShareInfoSchema,
+  SharedChatViewSchema,
+  BaseEventSchema,
+  ChatCreatedEventSchema,
+  ChatUpdatedEventSchema,
+  ChatDeletedEventSchema,
+  InvalidateChatEventSchema,
+  InvalidateChatListEventSchema,
+  ChatDomainEventSchema,
+  ChatInvalidationEventSchema,
+  ChatSseEventSchema,
+} from './schemas'
+
 // Runtime profile types and constants
 export type { ChatRuntimeProfile, ChatRuntimeProfileInfo } from './runtime-profile'
 export { CHAT_RUNTIME_PROFILES, DEFAULT_CHAT_RUNTIME_PROFILE } from './runtime-profile'

package/src/chat/schemas.ts

@@ -0,0 +1,154 @@
+import { z } from 'zod'
+
+// =============================================================================
+// Reusable Primitives
+// =============================================================================
+
+/** ISO 8601 datetime string — the runtime safety net for date serialization. */
+export const IsoDateString = z.string().datetime()
+
+// =============================================================================
+// Enums
+// =============================================================================
+
+export const ChatVisibilitySchema = z.enum(['private', 'public'])
+export const TitleSourceSchema = z.enum(['auto', 'manual'])
+export const InvalidationReasonSchema = z.enum(['external-mutation', 'bulk-operation', 'sync-required'])
+export const ChatChangedFieldSchema = z.enum(['title', 'titleSource', 'pinnedAt'])
+
+// =============================================================================
+// Core Entities
+// =============================================================================
+
+export const ChatSummarySchema = z.object({
+  id: z.string(),
+  title: z.string().nullable(),
+  messageCount: z.number().int(),
+  createdAt: IsoDateString,
+  updatedAt: IsoDateString,
+  isShared: z.boolean(),
+})
+
+export const ChatSummaryExtendedSchema = ChatSummarySchema.extend({
+  pinnedAt: IsoDateString.nullable(),
+  titleSource: TitleSourceSchema.nullable(),
+  titleGeneratedAt: IsoDateString.nullable(),
+})
+
+export const TitleGenerationResponseSchema = z.object({
+  title: z.string(),
+  isAutoGenerated: z.boolean(),
+})
+
+// =============================================================================
+// Share Types
+// =============================================================================
+
+export const SharedChatMessageSchema = z.object({
+  role: z.enum(['user', 'assistant']),
+  content: z.string(),
+  parts: z.array(z.unknown()).optional(),
+})
+
+export const ChatShareInfoSchema = z.object({
+  id: z.string(),
+  chatId: z.string(),
+  token: z.string(),
+  visibility: ChatVisibilitySchema,
+  shareUrl: z.string(),
+  messageCountAtShare: z.number().int(),
+  titleAtShare: z.string(),
+  createdAt: IsoDateString,
+  createdByName: z.string(),
+  isRevoked: z.boolean(),
+})
+
+export const SharedChatViewSchema = z.object({
+  title: z.string(),
+  messages: z.array(SharedChatMessageSchema),
+  sharedAt: IsoDateString,
+  sharedByName: z.string(),
+  visibility: ChatVisibilitySchema,
+})
+
+// =============================================================================
+// SSE Event Schemas
+// =============================================================================
+
+export const BaseEventSchema = z.object({
+  v: z.literal(1),
+  timestamp: IsoDateString,
+  eventId: z.string().optional(),
+})
+
+export const ChatCreatedEventSchema = BaseEventSchema.extend({
+  type: z.literal('chat.created'),
+  data: z.object({
+    chatId: z.string(),
+    interactionId: z.string().optional(),
+    title: z.string(),
+    titleSource: TitleSourceSchema,
+    pinnedAt: IsoDateString.nullable(),
+    messageCount: z.number().int(),
+    createdAt: IsoDateString,
+    updatedAt: IsoDateString,
+    isShared: z.boolean(),
+  }),
+})
+
+export const ChatUpdatedEventSchema = BaseEventSchema.extend({
+  type: z.literal('chat.updated'),
+  data: z.object({
+    chatId: z.string(),
+    title: z.string(),
+    titleSource: TitleSourceSchema.nullable(),
+    titleGeneratedAt: IsoDateString.nullable(),
+    pinnedAt: IsoDateString.nullable(),
+    messageCount: z.number().int(),
+    createdAt: IsoDateString,
+    updatedAt: IsoDateString,
+    isShared: z.boolean(),
+  }),
+  changed: z.array(ChatChangedFieldSchema),
+})
+
+export const ChatDeletedEventSchema = BaseEventSchema.extend({
+  type: z.literal('chat.deleted'),
+  data: z.object({
+    chatId: z.string(),
+  }),
+})
+
+export const InvalidateChatEventSchema = BaseEventSchema.extend({
+  type: z.literal('invalidate.chat'),
+  chatId: z.string(),
+  reason: InvalidationReasonSchema,
+})
+
+export const InvalidateChatListEventSchema = BaseEventSchema.extend({
+  type: z.literal('invalidate.chat-list'),
+  reason: InvalidationReasonSchema,
+})
+
+// =============================================================================
+// SSE Event Unions
+// =============================================================================
+
+export const ChatDomainEventSchema = z.discriminatedUnion('type', [
+  ChatCreatedEventSchema,
+  ChatUpdatedEventSchema,
+  ChatDeletedEventSchema,
+])
+
+export const ChatInvalidationEventSchema = z.discriminatedUnion('type', [
+  InvalidateChatEventSchema,
+  InvalidateChatListEventSchema,
+])
+
+export const ChatSseEventSchema = z.discriminatedUnion('type', [
+  ChatCreatedEventSchema,
+  ChatUpdatedEventSchema,
+  ChatDeletedEventSchema,
+  InvalidateChatEventSchema,
+  InvalidateChatListEventSchema,
+])

package/src/chat/types.ts

@@ -2,8 +2,32 @@
  * Chat Domain Types
  *
  * Shared types for chat persistence and sharing across Company Semantics codebases.
- * Types only - no runtime code, no business logic.
- */
+ * Response and event types are derived from Zod schemas (single source of truth).
+ * Request-only types remain as interfaces (no runtime validation needed).
+ */
+
+import { z } from 'zod'
+import {
+  ChatVisibilitySchema,
+  TitleSourceSchema,
+  InvalidationReasonSchema,
+  ChatChangedFieldSchema,
+  ChatSummarySchema,
+  ChatSummaryExtendedSchema,
+  TitleGenerationResponseSchema,
+  ChatShareInfoSchema,
+  SharedChatViewSchema,
+  SharedChatMessageSchema,
+  BaseEventSchema,
+  ChatCreatedEventSchema,
+  ChatUpdatedEventSchema,
+  ChatDeletedEventSchema,
+  InvalidateChatEventSchema,
+  InvalidateChatListEventSchema,
+  ChatDomainEventSchema,
+  ChatInvalidationEventSchema,
+  ChatSseEventSchema,
+} from './schemas'
 
 // =============================================================================
 // Visibility
@@ -14,7 +38,7 @@
  * - private: Token exists but access requires authentication as chat owner
  * - public: Token grants anonymous access to anyone with the link
  */
-export type ChatVisibility = 'private' | 'public'
+export type ChatVisibility = z.infer<typeof ChatVisibilitySchema>
 
 // =============================================================================
 // Chat Summary
@@ -23,16 +47,7 @@ export type ChatVisibility = 'private' | 'public'
 /**
  * Lightweight chat summary for list views.
  */
-export interface ChatSummary {
-  id: string
-  /** Title - null means intentionally untitled (title not yet generated) */
-  title: string | null
-  messageCount: number
-  createdAt: string
-  updatedAt: string
-  /** True if this chat has an active (non-revoked) share */
-  isShared: boolean
-}
+export type ChatSummary = z.infer<typeof ChatSummarySchema>
 
 // =============================================================================
 // Share Types
@@ -45,42 +60,18 @@ export interface ChatSummary {
  * A chat share must never expose messages with sequenceNumber > messageCountAtShare.
  * Enforced in ChatShareService.viewSharedChat() only.
  */
-export interface ChatShareInfo {
-  id: string
-  chatId: string
-  token: string
-  visibility: ChatVisibility
-  shareUrl: string
-  /** Message count at time of sharing - the snapshot boundary */
-  messageCountAtShare: number
-  /** Title snapshot at share time */
-  titleAtShare: string
-  createdAt: string
-  createdByName: string
-  isRevoked: boolean
-}
+export type ChatShareInfo = z.infer<typeof ChatShareInfoSchema>
 
 /**
  * Shared chat view returned to viewers.
  * Messages are limited by the snapshot boundary.
  */
-export interface SharedChatView {
-  title: string
-  messages: SharedChatMessage[]
-  sharedAt: string
-  sharedByName: string
-  visibility: ChatVisibility
-}
+export type SharedChatView = z.infer<typeof SharedChatViewSchema>
 
 /**
  * Individual message in a shared chat view.
  */
-export interface SharedChatMessage {
-  role: 'user' | 'assistant'
-  content: string
-  /** Optional rich content parts (tool calls, artifacts, etc.) */
-  parts?: unknown[]
-}
+export type SharedChatMessage = z.infer<typeof SharedChatMessageSchema>
 
 // =============================================================================
 // API Request/Response Types
@@ -114,7 +105,7 @@ export interface UpdateShareRequest {
  * - auto: Generated automatically by LLM
  * - manual: Set by user (disables future auto-generation)
  */
-export type TitleSource = 'auto' | 'manual'
+export type TitleSource = z.infer<typeof TitleSourceSchema>
 
 /**
  * Filters for listing chats.
@@ -133,14 +124,7 @@ export interface ChatListFilters {
 /**
  * Extended chat summary with pin/title status.
  */
-export interface ChatSummaryExtended extends ChatSummary {
-  /** If pinned, when it was pinned */
-  pinnedAt: string | null
-  /** How the title was set: 'auto' or 'manual' */
-  titleSource: TitleSource | null
-  /** When auto-title was generated (null if never auto-generated) */
-  titleGeneratedAt: string | null
-}
+export type ChatSummaryExtended = z.infer<typeof ChatSummaryExtendedSchema>
 
 /**
  * Request to generate a title for a chat.
@@ -154,11 +138,7 @@ export interface TitleGenerationRequest {
 /**
  * Response from title generation.
  */
-export interface TitleGenerationResponse {
-  title: string
-  /** Whether this was auto-generated */
-  isAutoGenerated: boolean
-}
+export type TitleGenerationResponse = z.infer<typeof TitleGenerationResponseSchema>
 
 // =============================================================================
 // Event System Types
@@ -174,26 +154,19 @@ export interface TitleGenerationResponse {
  * 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
-}
+export type BaseEvent = z.infer<typeof BaseEventSchema>
 
 /**
  * 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 InvalidationReason = 'external-mutation' | 'bulk-operation' | 'sync-required'
+export type InvalidationReason = z.infer<typeof InvalidationReasonSchema>
 
 /**
  * Fields that can change on a chat, used in changed[] array.
  */
-export type ChatChangedField = 'title' | 'titleSource' | 'pinnedAt'
+export type ChatChangedField = z.infer<typeof ChatChangedFieldSchema>
 
 // =============================================================================
 // Domain Events (past-tense facts, carry full state)
@@ -206,60 +179,18 @@ export type ChatChangedField = 'title' | 'titleSource' | 'pinnedAt'
  * 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 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
-    /** 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
-  }
-}
+export type ChatCreatedEvent = z.infer<typeof ChatCreatedEventSchema>
 
 /**
  * Emitted when chat metadata changes (title, pin, 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
-    pinnedAt: string | null
-    messageCount: number
-    createdAt: string
-    updatedAt: string
-    isShared: boolean
-  }
-  /** What fields changed - for UI optimization only */
-  changed: ChatChangedField[]
-}
+export type ChatUpdatedEvent = z.infer<typeof ChatUpdatedEventSchema>
 
 /**
  * Emitted when a chat is deleted.
  */
-export interface ChatDeletedEvent extends BaseEvent {
-  type: 'chat.deleted'
-  data: {
-    chatId: string
-  }
-}
+export type ChatDeletedEvent = z.infer<typeof ChatDeletedEventSchema>
 
 // =============================================================================
 // Invalidation Events (staleness signals)
@@ -269,20 +200,13 @@ export interface ChatDeletedEvent extends BaseEvent {
  * 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
-}
+export type InvalidateChatEvent = z.infer<typeof InvalidateChatEventSchema>
 
 /**
  * Collection staleness signal.
  * Emitted when chat list ordering/filtering may be stale.
  */
-export interface InvalidateChatListEvent extends BaseEvent {
-  type: 'invalidate.chat-list'
-  reason: InvalidationReason
-}
+export type InvalidateChatListEvent = z.infer<typeof InvalidateChatListEventSchema>
 
 // =============================================================================
 // SSE Event Union
@@ -291,16 +215,15 @@ export interface InvalidateChatListEvent extends BaseEvent {
 /**
  * All domain events that carry full state.
  */
-export type ChatDomainEvent = ChatCreatedEvent | ChatUpdatedEvent | ChatDeletedEvent
+export type ChatDomainEvent = z.infer<typeof ChatDomainEventSchema>
 
 /**
  * All invalidation events that signal staleness.
  */
-export type ChatInvalidationEvent = InvalidateChatEvent | InvalidateChatListEvent
+export type ChatInvalidationEvent = z.infer<typeof ChatInvalidationEventSchema>
 
 /**
  * SSE event types for chat updates.
  * Client receives these via SSE and handles accordingly.
  */
-export type ChatSseEvent = ChatDomainEvent | ChatInvalidationEvent
-
+export type ChatSseEvent = z.infer<typeof ChatSseEventSchema>