@company-semantics/contracts 9.0.0 → 9.2.0

package/src/chat/runtime-profile.ts

@@ -8,29 +8,44 @@
  * - balanced: Default. AiSdkOrchestrator + gpt-4o with tool support.
  * - agentic: Multi-turn agent loop. ClaudeAgentOrchestrator.
  */
-export type ChatRuntimeProfile = 'fast' | 'balanced' | 'agentic'
+export type ChatRuntimeProfile = "fast" | "balanced" | "agentic";
 
 /**
  * Runtime profile metadata for UI rendering.
  * Labels and descriptions are user-facing — no vendor names.
  */
 export interface ChatRuntimeProfileInfo {
-  id: ChatRuntimeProfile
-  label: string
-  description: string
-  model: string
+  id: ChatRuntimeProfile;
+  label: string;
+  description: string;
+  model: string;
 }
 
 /**
  * Ordered list of available profiles for UI rendering.
  */
 export const CHAT_RUNTIME_PROFILES: readonly ChatRuntimeProfileInfo[] = [
-  { id: 'fast', label: 'Fast', description: 'Single-step, no tools', model: 'gpt-3.5-turbo' },
-  { id: 'balanced', label: 'Balanced', description: 'Multi-step with tools', model: 'gpt-4o' },
-  { id: 'agentic', label: 'Agentic', description: 'Agent loop, full reasoning', model: 'claude-sonnet-4-20250514' },
-] as const
+  {
+    id: "fast",
+    label: "Fast",
+    description: "Single-step, no tools",
+    model: "gpt-3.5-turbo",
+  },
+  {
+    id: "balanced",
+    label: "Balanced",
+    description: "Multi-step with tools",
+    model: "gpt-4o",
+  },
+  {
+    id: "agentic",
+    label: "Agentic",
+    description: "Agent loop, full reasoning",
+    model: "claude-sonnet-4-20250514",
+  },
+] as const;
 
 /**
  * Default profile when none is specified in the request.
  */
-export const DEFAULT_CHAT_RUNTIME_PROFILE: ChatRuntimeProfile = 'agentic'
+export const DEFAULT_CHAT_RUNTIME_PROFILE: ChatRuntimeProfile = "agentic";

package/src/chat/schemas.ts

@@ -1,20 +1,28 @@
-import { z } from 'zod'
+import { z } from "zod";
 
 // =============================================================================
 // Reusable Primitives
 // =============================================================================
 
 /** ISO 8601 datetime string — the runtime safety net for date serialization. */
-export const IsoDateString = z.string().datetime()
+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'])
+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
@@ -27,28 +35,28 @@ export const ChatSummarySchema = z.object({
   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']),
+  role: z.enum(["user", "assistant"]),
   content: z.string(),
   parts: z.array(z.unknown()).optional(),
-})
+});
 
 export const ChatShareInfoSchema = z.object({
   id: z.string(),
@@ -61,7 +69,7 @@ export const ChatShareInfoSchema = z.object({
   createdAt: IsoDateString,
   createdByName: z.string(),
   isRevoked: z.boolean(),
-})
+});
 
 export const SharedChatViewSchema = z.object({
   title: z.string(),
@@ -69,7 +77,7 @@ export const SharedChatViewSchema = z.object({
   sharedAt: IsoDateString,
   sharedByName: z.string(),
   visibility: ChatVisibilitySchema,
-})
+});
 
 // =============================================================================
 // SSE Event Schemas
@@ -79,10 +87,10 @@ 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'),
+  type: z.literal("chat.created"),
   data: z.object({
     chatId: z.string(),
     interactionId: z.string().optional(),
@@ -94,10 +102,10 @@ export const ChatCreatedEventSchema = BaseEventSchema.extend({
     updatedAt: IsoDateString,
     isShared: z.boolean(),
   }),
-})
+});
 
 export const ChatUpdatedEventSchema = BaseEventSchema.extend({
-  type: z.literal('chat.updated'),
+  type: z.literal("chat.updated"),
   data: z.object({
     chatId: z.string(),
     title: z.string(),
@@ -110,48 +118,48 @@ export const ChatUpdatedEventSchema = BaseEventSchema.extend({
     isShared: z.boolean(),
   }),
   changed: z.array(ChatChangedFieldSchema),
-})
+});
 
 export const ChatDeletedEventSchema = BaseEventSchema.extend({
-  type: z.literal('chat.deleted'),
+  type: z.literal("chat.deleted"),
   data: z.object({
     chatId: z.string(),
   }),
-})
+});
 
 export const InvalidateChatEventSchema = BaseEventSchema.extend({
-  type: z.literal('invalidate.chat'),
+  type: z.literal("invalidate.chat"),
   chatId: z.string(),
   reason: InvalidationReasonSchema,
-})
+});
 
 export const InvalidateChatListEventSchema = BaseEventSchema.extend({
-  type: z.literal('invalidate.chat-list'),
+  type: z.literal("invalidate.chat-list"),
   reason: InvalidationReasonSchema,
-})
+});
 
 // =============================================================================
 // SSE Event Unions
 // =============================================================================
 
-export const ChatDomainEventSchema = z.discriminatedUnion('type', [
+export const ChatDomainEventSchema = z.discriminatedUnion("type", [
   ChatCreatedEventSchema,
   ChatUpdatedEventSchema,
   ChatDeletedEventSchema,
-])
+]);
 
-export const ChatInvalidationEventSchema = z.discriminatedUnion('type', [
+export const ChatInvalidationEventSchema = z.discriminatedUnion("type", [
   InvalidateChatEventSchema,
   InvalidateChatListEventSchema,
-])
+]);
 
-export const ChatSseEventSchema = z.discriminatedUnion('type', [
+export const ChatSseEventSchema = z.discriminatedUnion("type", [
   ChatCreatedEventSchema,
   ChatUpdatedEventSchema,
   ChatDeletedEventSchema,
   InvalidateChatEventSchema,
   InvalidateChatListEventSchema,
-])
+]);
 
 // =============================================================================
 // Message Types
@@ -160,12 +168,12 @@ export const ChatSseEventSchema = z.discriminatedUnion('type', [
 /** Individual message in a chat, as returned by GET /api/chats/:id. */
 export const ChatMessageSchema = z.object({
   id: z.string(),
-  role: z.enum(['user', 'assistant']),
+  role: z.enum(["user", "assistant"]),
   content: z.string(),
   parts: z.array(z.unknown()).optional(),
   sequenceNumber: z.number().int(),
   createdAt: IsoDateString,
-})
+});
 
 // =============================================================================
 // HTTP Response Schemas
@@ -174,38 +182,38 @@ export const ChatMessageSchema = z.object({
 /** Generic success confirmation for mutations that return no entity data. */
 export const ChatSuccessResponseSchema = z.object({
   success: z.literal(true),
-})
+});
 
 /** Response for GET /api/chats/by-interaction/:interactionId */
 export const ChatByInteractionResponseSchema = z.object({
   chatId: z.string(),
-})
+});
 
 /** Response for GET /api/chats */
 export const ChatListResponseSchema = z.object({
   chats: z.array(ChatSummaryExtendedSchema),
-})
+});
 
 /** Response for POST /api/chats */
 export const CreateChatResponseSchema = z.object({
   chat: ChatSummaryExtendedSchema,
-})
+});
 
 /** Response for POST /api/chats/:chatId/shares */
 export const CreateShareResponseSchema = z.object({
   share: ChatShareInfoSchema,
   shareUrl: z.string(),
-})
+});
 
 /** Response for GET /api/chats/:chatId/shares */
 export const ListSharesResponseSchema = z.object({
   shares: z.array(ChatShareInfoSchema),
-})
+});
 
 /** Response for PATCH /api/shares/:shareId */
 export const UpdateShareResponseSchema = z.object({
   share: ChatShareInfoSchema,
-})
+});
 
 /**
  * Chat detail object in GET /api/chats/:id response.
@@ -220,10 +228,10 @@ export const ChatDetailSchema = z.object({
   titleGeneratedAt: IsoDateString.nullable().optional(),
   createdAt: IsoDateString,
   updatedAt: IsoDateString,
-})
+});
 
 /** Response for GET /api/chats/:id */
 export const GetChatResponseSchema = z.object({
   chat: ChatDetailSchema,
   messages: z.array(ChatMessageSchema),
-})
+});

package/src/chat/types.ts

@@ -6,7 +6,7 @@
  * Request-only types remain as interfaces (no runtime validation needed).
  */
 
-import { z } from 'zod'
+import { z } from "zod";
 import {
   ChatVisibilitySchema,
   TitleSourceSchema,
@@ -37,7 +37,7 @@ import {
   ChatMessageSchema,
   ChatDetailSchema,
   GetChatResponseSchema,
-} from './schemas'
+} from "./schemas";
 
 // =============================================================================
 // Visibility
@@ -48,7 +48,7 @@ import {
  * - private: Token exists but access requires authentication as chat owner
  * - public: Token grants anonymous access to anyone with the link
  */
-export type ChatVisibility = z.infer<typeof ChatVisibilitySchema>
+export type ChatVisibility = z.infer<typeof ChatVisibilitySchema>;
 
 // =============================================================================
 // Chat Summary
@@ -57,7 +57,7 @@ export type ChatVisibility = z.infer<typeof ChatVisibilitySchema>
 /**
  * Lightweight chat summary for list views.
  */
-export type ChatSummary = z.infer<typeof ChatSummarySchema>
+export type ChatSummary = z.infer<typeof ChatSummarySchema>;
 
 // =============================================================================
 // Share Types
@@ -70,18 +70,18 @@ export type ChatSummary = z.infer<typeof ChatSummarySchema>
  * A chat share must never expose messages with sequenceNumber > messageCountAtShare.
  * Enforced in ChatShareService.viewSharedChat() only.
  */
-export type ChatShareInfo = z.infer<typeof ChatShareInfoSchema>
+export type ChatShareInfo = z.infer<typeof ChatShareInfoSchema>;
 
 /**
  * Shared chat view returned to viewers.
  * Messages are limited by the snapshot boundary.
  */
-export type SharedChatView = z.infer<typeof SharedChatViewSchema>
+export type SharedChatView = z.infer<typeof SharedChatViewSchema>;
 
 /**
  * Individual message in a shared chat view.
  */
-export type SharedChatMessage = z.infer<typeof SharedChatMessageSchema>
+export type SharedChatMessage = z.infer<typeof SharedChatMessageSchema>;
 
 // =============================================================================
 // API Request/Response Types
@@ -91,19 +91,19 @@ export type SharedChatMessage = z.infer<typeof SharedChatMessageSchema>
  * Request to create a new share for a chat.
  */
 export interface CreateShareRequest {
-  chatId: string
-  visibility: ChatVisibility
+  chatId: string;
+  visibility: ChatVisibility;
   /** Optional: send email notification to this address */
-  recipientEmail?: string
+  recipientEmail?: string;
 }
 
 /**
  * Request to update an existing share.
  */
 export interface UpdateShareRequest {
-  visibility?: ChatVisibility
+  visibility?: ChatVisibility;
   /** If true, update snapshot to include new messages added since share creation */
-  updateSnapshot?: boolean
+  updateSnapshot?: boolean;
 }
 
 // =============================================================================
@@ -115,40 +115,42 @@ export interface UpdateShareRequest {
  * - auto: Generated automatically by LLM
  * - manual: Set by user (disables future auto-generation)
  */
-export type TitleSource = z.infer<typeof TitleSourceSchema>
+export type TitleSource = z.infer<typeof TitleSourceSchema>;
 
 /**
  * Filters for listing chats.
  */
 export interface ChatListFilters {
   /** Search query - matches against title */
-  search?: string
+  search?: string;
   /** Include pinned chats at top */
-  includePinned?: boolean
+  includePinned?: boolean;
   /** Pagination limit */
-  limit?: number
+  limit?: number;
   /** Pagination offset */
-  offset?: number
+  offset?: number;
 }
 
 /**
  * Extended chat summary with pin/title status.
  */
-export type ChatSummaryExtended = z.infer<typeof ChatSummaryExtendedSchema>
+export type ChatSummaryExtended = z.infer<typeof ChatSummaryExtendedSchema>;
 
 /**
  * Request to generate a title for a chat.
  */
 export interface TitleGenerationRequest {
-  chatId: string
+  chatId: string;
   /** First few messages for context */
-  messages: Array<{ role: 'user' | 'assistant'; content: string }>
+  messages: Array<{ role: "user" | "assistant"; content: string }>;
 }
 
 /**
  * Response from title generation.
  */
-export type TitleGenerationResponse = z.infer<typeof TitleGenerationResponseSchema>
+export type TitleGenerationResponse = z.infer<
+  typeof TitleGenerationResponseSchema
+>;
 
 // =============================================================================
 // Event System Types
@@ -164,19 +166,19 @@ export type TitleGenerationResponse = z.infer<typeof TitleGenerationResponseSche
  * INV-EVENT-CONVERGENCE: Clients must assume events may be missed during SSE
  *                        disconnects. Invalidation events ensure convergence.
  */
-export type BaseEvent = z.infer<typeof BaseEventSchema>
+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 = z.infer<typeof InvalidationReasonSchema>
+export type InvalidationReason = z.infer<typeof InvalidationReasonSchema>;
 
 /**
  * Fields that can change on a chat, used in changed[] array.
  */
-export type ChatChangedField = z.infer<typeof ChatChangedFieldSchema>
+export type ChatChangedField = z.infer<typeof ChatChangedFieldSchema>;
 
 // =============================================================================
 // Domain Events (past-tense facts, carry full state)
@@ -189,18 +191,18 @@ export type ChatChangedField = z.infer<typeof ChatChangedFieldSchema>
  * 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 type ChatCreatedEvent = z.infer<typeof ChatCreatedEventSchema>
+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 type ChatUpdatedEvent = z.infer<typeof ChatUpdatedEventSchema>
+export type ChatUpdatedEvent = z.infer<typeof ChatUpdatedEventSchema>;
 
 /**
  * Emitted when a chat is deleted.
  */
-export type ChatDeletedEvent = z.infer<typeof ChatDeletedEventSchema>
+export type ChatDeletedEvent = z.infer<typeof ChatDeletedEventSchema>;
 
 // =============================================================================
 // Invalidation Events (staleness signals)
@@ -210,13 +212,15 @@ export type ChatDeletedEvent = z.infer<typeof ChatDeletedEventSchema>
  * Single-entity staleness signal.
  * Emitted when a specific chat may be out of sync (e.g., external mutation).
  */
-export type InvalidateChatEvent = z.infer<typeof InvalidateChatEventSchema>
+export type InvalidateChatEvent = z.infer<typeof InvalidateChatEventSchema>;
 
 /**
  * Collection staleness signal.
  * Emitted when chat list ordering/filtering may be stale.
  */
-export type InvalidateChatListEvent = z.infer<typeof InvalidateChatListEventSchema>
+export type InvalidateChatListEvent = z.infer<
+  typeof InvalidateChatListEventSchema
+>;
 
 // =============================================================================
 // SSE Event Union
@@ -225,49 +229,51 @@ export type InvalidateChatListEvent = z.infer<typeof InvalidateChatListEventSche
 /**
  * All domain events that carry full state.
  */
-export type ChatDomainEvent = z.infer<typeof ChatDomainEventSchema>
+export type ChatDomainEvent = z.infer<typeof ChatDomainEventSchema>;
 
 /**
  * All invalidation events that signal staleness.
  */
-export type ChatInvalidationEvent = z.infer<typeof ChatInvalidationEventSchema>
+export type ChatInvalidationEvent = z.infer<typeof ChatInvalidationEventSchema>;
 
 /**
  * SSE event types for chat updates.
  * Client receives these via SSE and handles accordingly.
  */
-export type ChatSseEvent = z.infer<typeof ChatSseEventSchema>
+export type ChatSseEvent = z.infer<typeof ChatSseEventSchema>;
 
 // =============================================================================
 // HTTP Response Types (derived from response schemas)
 // =============================================================================
 
 /** Generic mutation success confirmation. */
-export type ChatSuccessResponse = z.infer<typeof ChatSuccessResponseSchema>
+export type ChatSuccessResponse = z.infer<typeof ChatSuccessResponseSchema>;
 
 /** Response for GET /api/chats/by-interaction/:interactionId */
-export type ChatByInteractionResponse = z.infer<typeof ChatByInteractionResponseSchema>
+export type ChatByInteractionResponse = z.infer<
+  typeof ChatByInteractionResponseSchema
+>;
 
 /** Response for GET /api/chats */
-export type ChatListResponse = z.infer<typeof ChatListResponseSchema>
+export type ChatListResponse = z.infer<typeof ChatListResponseSchema>;
 
 /** Response for POST /api/chats */
-export type CreateChatResponse = z.infer<typeof CreateChatResponseSchema>
+export type CreateChatResponse = z.infer<typeof CreateChatResponseSchema>;
 
 /** Response for POST /api/chats/:chatId/shares */
-export type CreateShareResponse = z.infer<typeof CreateShareResponseSchema>
+export type CreateShareResponse = z.infer<typeof CreateShareResponseSchema>;
 
 /** Response for GET /api/chats/:chatId/shares */
-export type ListSharesResponse = z.infer<typeof ListSharesResponseSchema>
+export type ListSharesResponse = z.infer<typeof ListSharesResponseSchema>;
 
 /** Response for PATCH /api/shares/:shareId */
-export type UpdateShareResponse = z.infer<typeof UpdateShareResponseSchema>
+export type UpdateShareResponse = z.infer<typeof UpdateShareResponseSchema>;
 
 /** Individual message in a chat response (GET /api/chats/:id). */
-export type ChatMessage = z.infer<typeof ChatMessageSchema>
+export type ChatMessage = z.infer<typeof ChatMessageSchema>;
 
 /** Chat detail object in GET /api/chats/:id — includes interactionId for append-on-edit flows. */
-export type ChatDetail = z.infer<typeof ChatDetailSchema>
+export type ChatDetail = z.infer<typeof ChatDetailSchema>;
 
 /** Response for GET /api/chats/:id */
-export type GetChatResponse = z.infer<typeof GetChatResponseSchema>
+export type GetChatResponse = z.infer<typeof GetChatResponseSchema>;

package/src/ci-envelope/README.md

@@ -16,6 +16,7 @@ Defines the shared type vocabulary for CI execution envelopes. An envelope is an
 ## Public API
 
 **Types:**
+
 - `CIExecutionEnvelope` — Core envelope record (version, id, actor, session, intent, scope, authority, guardPlan, status, outcome)
 - `CIEnvelopeStatus` — Lifecycle states: `proposed` → `validated` → `executing` → `finalized` (or `blocked`)
 - `ExecutionIntent` — Semantic categories: `feature_extension`, `bug_fix`, `refactor_structural`, `guard_update`, `policy_update`, `schema_change`, `doc_update`, `cleanup`, `experimental`
@@ -27,6 +28,7 @@ Defines the shared type vocabulary for CI execution envelopes. An envelope is an
 - `CIGuardViolation`, `CIExecutionOutcome` — Post-execution audit data
 
 **Constants:**
+
 - `ENVELOPE_TRANSITIONS` — Valid status transition graph (documentation only)
 
 ## Dependencies