@company-semantics/contracts 0.100.0 → 0.102.0

package/package.json

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

package/src/api/README.md

@@ -0,0 +1,21 @@
+# api/
+
+Shared API route helpers and contracts for backend HTTP endpoints.
+
+## Purpose
+
+Provides reusable functions that encode API response shapes shared between the contracts package and backend route implementations. Currently focused on tool discovery response building.
+
+## Invariants
+
+- Functions in this domain are pure — no side effects, no database access
+- Response shapes must match the types defined in `src/mcp/` (e.g., `ToolDiscoveryResponse`)
+- Capability graph inclusion is opt-in via query parameter convention (`?include=graph`)
+
+## Public API
+
+- `buildToolDiscoveryResponse(tools, includeGraph)` — Constructs a `ToolDiscoveryResponse`, optionally including the capability graph derived from tool metadata
+
+## Dependencies
+
+- `src/mcp/` — `MCPToolDescriptor`, `ToolDiscoveryResponse`, `CapabilityGraph` types and `buildCapabilityGraph` function

package/src/api/http/README.md

@@ -0,0 +1,21 @@
+# api/http/
+
+HTTP-specific API route contracts and helpers.
+
+## Purpose
+
+Contains route-level shared logic for HTTP API endpoints. Organizes helpers by route path under `routes/`. Currently provides the tool discovery response builder used by the backend's `/api/capabilities/tools` endpoint.
+
+## Invariants
+
+- Route helpers are pure functions — no HTTP framework coupling (no Fastify, no Express)
+- Helpers encode response shape logic only; authentication, authorization, and request parsing belong in the backend
+- File organization mirrors backend route paths (`routes/ai-chat.ts` → backend's `ai-chat.ts`)
+
+## Public API
+
+- `routes/ai-chat.ts` — `buildToolDiscoveryResponse(tools, includeGraph)` for the capabilities/tools endpoint
+
+## Dependencies
+
+- `src/mcp/` — Tool descriptor types and capability graph builder

package/src/api/http/utils/resource-response.ts

@@ -0,0 +1,11 @@
+import type { ResourceResponse } from '../../../resource-response';
+
+/**
+ * Wrap resource data with version for cache invalidation.
+ * @param data - The resource data
+ * @param version - MUST be entity.updatedAt or DB row version. NEVER Date.now().
+ *   Using request time defeats invalidation — race conditions reappear.
+ */
+export function resourceResponse<T>(data: T, version: number): ResourceResponse<T> {
+  return { data, version };
+}

package/src/auth/README.md

@@ -0,0 +1,21 @@
+# auth/
+
+## Purpose
+
+Shared types for authentication flows across Company Semantics codebases. Defines the OTP and SSO authentication start protocol.
+
+## Invariants
+
+- AuthStartResponse is a discriminated union on `mode` — consumers must handle all three modes
+- OTPErrorCode values are stable strings used by both backend (error generation) and frontend (user messaging)
+
+## Public API
+
+**Types:**
+- `OTPErrorCode` — enum: `InvalidCode`, `Expired`, `AlreadyUsed`, `NotFound`
+- `AuthStartMode` — `'otp' | 'sso' | 'hybrid'`
+- `AuthStartResponse` — discriminated union describing auth flow entry point
+
+## Dependencies
+
+- None (leaf domain in contracts)

package/src/billing/README.md

@@ -0,0 +1,22 @@
+# billing/
+
+Read-only billing DTO types for the organization billing surface.
+
+## Purpose
+
+Defines the shared type vocabulary for organization billing status and plan information. These types are consumed by backend (billing routes) and app (billing UI) to display plan and seat information.
+
+## Invariants
+
+- All types are read-only DTOs — no mutation operations in v1
+- `billingOwnerUserId` must equal `org.ownerUserId` — no separate billing owner concept in v1
+- `OrgPlanStatus` is a closed union: `active`, `trialing`, `past_due`, `canceled`
+
+## Public API
+
+- `OrgPlanStatus` — Union type for organization plan states
+- `OrgBillingInfo` — Read-only billing information (plan name, status, cadence, seats, billing owner)
+
+## Dependencies
+
+- None — leaf domain with no imports from other contracts modules

package/src/chat/README.md

@@ -0,0 +1,38 @@
+# chat/
+
+## Purpose
+
+Shared types for chat persistence, sharing, real-time events, and runtime profile selection.
+
+## Invariants
+
+- Chat share snapshot boundary: messages with sequenceNumber > messageCountAtShare are never exposed (SNAPSHOT-1)
+- Domain events for a given entity are emitted in commit order; clients may assume monotonic updatedAt
+- Clients must treat SSE events as idempotent — full payload replacement handles duplicates
+- Invalidation events ensure convergence after SSE disconnects
+- Runtime profile labels are vendor-agnostic (no model names in UI)
+- Default runtime profile is `agentic`
+
+## Public API
+
+**Types:**
+- `ChatVisibility` — `'private' | 'public'` share visibility
+- `ChatSummary`, `ChatSummaryExtended` — list view models
+- `ChatShareInfo`, `SharedChatView`, `SharedChatMessage` — sharing types
+- `CreateShareRequest`, `UpdateShareRequest` — share mutation requests
+- `TitleSource`, `ChatListFilters`, `TitleGenerationRequest/Response` — lifecycle types
+- `ChatRuntimeProfile` — `'fast' | 'balanced' | 'agentic'` orchestration strategy
+- `ChatRuntimeProfileInfo` — profile metadata for UI rendering
+
+**SSE event types:**
+- `ChatCreatedEvent`, `ChatUpdatedEvent`, `ChatDeletedEvent` — domain events
+- `InvalidateChatEvent`, `InvalidateChatListEvent` — staleness signals
+- `ChatSseEvent` — union of all SSE event types
+
+**Runtime values:**
+- `CHAT_RUNTIME_PROFILES` — ordered array of profile info for UI rendering
+- `DEFAULT_CHAT_RUNTIME_PROFILE` — `'agentic'`
+
+## Dependencies
+
+- None (leaf domain in contracts)

package/src/ci-envelope/README.md

@@ -0,0 +1,34 @@
+# ci-envelope/
+
+Type vocabulary for CI execution envelopes — the governance records that capture AI intent before mutations.
+
+## Purpose
+
+Defines the shared type vocabulary for CI execution envelopes. An envelope is an append-only record created before code mutations that captures intent, scope, authority, and outcome. This enables pre-execution gating and post-hoc audit without LLM guesswork.
+
+## Invariants
+
+- Types only — no validation logic, no policy mappings (those live in `company-semantics-ci/envelope/`)
+- Envelopes are append-only: status transitions forward only, no field deletions
+- `ENVELOPE_TRANSITIONS` documents the state machine but does not enforce it
+- Terminal states: `blocked` and `finalized` have no outgoing transitions
+
+## 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`
+- `CIIntentDeclaration` — Intent with description and optional ADR references
+- `CIExecutionScope` — Affected repos, path globs, and change kinds
+- `CIAuthorityGrant` — Permission basis (CLAUDE.md/AI_AUTONOMY.md references)
+- `CIGuardPlan` — Required and advisory guard lists
+- `CIActorInfo`, `CISessionInfo` — Actor and session metadata
+- `CIGuardViolation`, `CIExecutionOutcome` — Post-execution audit data
+
+**Constants:**
+- `ENVELOPE_TRANSITIONS` — Valid status transition graph (documentation only)
+
+## Dependencies
+
+- None (leaf module — no imports from other contracts domains)

package/src/index.ts

@@ -531,3 +531,11 @@ export type {
 } from './ci-envelope/index'
 
 export { ENVELOPE_TRANSITIONS } from './ci-envelope/index'
+
+// Resource key types (shared vocabulary for data layer)
+// @see PRD-00321 for design rationale
+export type { ResourceKey, Action } from './resource-keys'
+export { resolveScope, toQueryKey, fromQueryKey, resourceRelationships, matchesResourceKey } from './resource-keys'
+
+// Resource response wrapper (typed versioning for cache invalidation)
+export type { ResourceResponse } from './resource-response'

package/src/interfaces/README.md

@@ -0,0 +1,23 @@
+# interfaces/
+
+Shared logic for MCP tool interface presentation and formatting.
+
+## Purpose
+
+Contains pure formatting functions used by MCP tool interfaces. Currently provides help tool enrichment — functions that format workflow summaries and domain groupings from tool descriptors for the `cs_help` tool output.
+
+## Invariants
+
+- Functions are pure — no side effects, no service dependencies
+- Input is always `MCPToolDescriptor[]` (the same shape backend tool handlers produce)
+- Output is formatted text, not structured data — these are presentation-layer helpers
+
+## Public API
+
+- `mcp/tools/help.ts`:
+  - `formatWorkflowSummaries(descriptors)` — Derives workflows via capability graph and formats as text
+  - `formatDomainGroupings(descriptors)` — Groups tools by domain field and formats as text
+
+## Dependencies
+
+- `src/mcp/` — `MCPToolDescriptor` type and `buildCapabilityGraph` function

package/src/mcp/README.md

@@ -0,0 +1,36 @@
+# mcp/
+
+## Purpose
+
+Type vocabulary for MCP (Model Context Protocol) tool discovery, invocation metadata, capability graph derivation, and failure recovery.
+
+## Invariants
+
+- Discovery is descriptive (never executes); invocation is authoritative (runtime is executor)
+- Tool discovery output must be runtime-sourced, not streamed char-by-char
+- Intent `mutate` + risk `high` requires `requiresConfirmation: true` — enforced at tool registration
+- ResourceType is a closed union — new types require a contracts release
+- FailureContext recoveryActions are exhaustive — the LLM cannot invent alternatives
+- `cancel` is always implicitly available in failure recovery (not declared in recoveryActions)
+- At most one FailureContext is active at a time (no stacking)
+- Capability graph is a pure derivation from produces/consumes metadata
+
+## Public API
+
+**Types:**
+- `MCPToolDescriptor` — complete tool descriptor for discovery and invocation
+- `ToolDomain`, `ToolCategory` (deprecated), `ToolVisibility`, `ToolInvocationMode` — classification enums
+- `ToolEffectClass`, `ToolIntent`, `ToolStability`, `ToolComplexity` — tool metadata types
+- `ToolIntegration` — extensible integration provider tag
+- `ResourceType` — closed union of tool resource flow types
+- `CapabilityGraph`, `CapabilityGraphEdge`, `ToolWorkflow` — graph types
+- `ToolDiscoveryResponse` — HTTP transport for GET /api/capabilities/tools
+- `ToolListMessagePart`, `ToolListDataPart` — chat protocol and wire format parts
+- `FailureContext`, `RecoveryAction` — structured failure recovery types
+
+**Runtime values:**
+- `buildCapabilityGraph(tools)` — pure function deriving graph from produces/consumes metadata
+
+## Dependencies
+
+- None (leaf domain in contracts; consumed by backend, app)

package/src/message-parts/README.md

@@ -0,0 +1,39 @@
+# message-parts/
+
+## Purpose
+
+Canonical vocabulary for structured assistant message output. Defines the type system for all rich content parts that flow between backend (producer) and app (consumer) in the chat protocol.
+
+## Invariants
+
+- Narrative (text) parts MUST come before surface parts — enforced by PartBuilder state machine
+- SurfacePart is an extensible union — add new surface kinds without protocol changes
+- TextPart is the ONLY part type that may be streamed character-by-character
+- Wire format uses AI SDK's `data-{name}` convention; frontend normalizes to semantic types
+- At most one preview proposal is active at a time
+- Confirmation is deterministic — no natural language inference ("yes" is invalid)
+- Execution results carry `state` resolved from ExecutionState (single authority, no redundant status)
+- Undo creates append-only audit rows — original execution is never mutated
+
+## Public API
+
+**Types:**
+- `TextPart`, `SurfacePart`, `AssistantMessagePart` — core part unions
+- `ToolListPart`, `StatusPanelPart`, `ChartPart`, `TablePart` — surface part variants
+- `PreviewData`, `PreviewArtifact`, `PreviewPart` — action preview surfaces
+- `ConfirmationData`, `ConfirmationRiskLevel`, `ConfirmationPart` — confirmation surfaces
+- `ExecutionResultData`, `ExecutionArtifactStatus`, `UndoResultData` — execution results
+- `StreamPhase`, `MessageLifecycleEvent` — message lifecycle events
+- `IntegrationKey`, `IntegrationProvider` — integration identifiers
+
+**Runtime values:**
+- `CONFIRMATION_LABELS` — exhaustive map of ExecutionKind to human-readable labels
+- `getConfirmationLabel(kind, fallback)` — label lookup with fallback
+- `WireSurfaceBuilder` — factory for creating wire-format data parts
+- `createPartBuilder()`, `addText()`, `addSurface()`, `buildParts()` — functional part builder
+- `isTextPart()`, `isSurfacePart()` — type guards
+
+## Dependencies
+
+- `../execution/kinds` — ExecutionKind type for confirmation labels
+- `../mcp/index` — MCPToolDescriptor for tool list parts

package/src/message-parts/builder.ts

@@ -15,7 +15,7 @@
  *
  * This prevents "post-surface commentary" features from sneaking in.
  *
- * @see DECISIONS.md ADR-2026-01-022 for design rationale
+ * @see decisions/ADR-CONT-026.md for design rationale
  */
 
 import type { AssistantMessagePart, TextPart, SurfacePart } from './types'

package/src/message-parts/confirmation.ts

@@ -14,7 +14,7 @@
  * - At most one action is confirmable at a time
  * - Mismatched actionId fails closed and re-prompts
  *
- * @see DECISIONS.md for design rationale
+ * @see decisions/ADR-CONT-037.md for design rationale
  */
 
 import type { ExecutionKind } from '../execution/kinds'

package/src/message-parts/execution.ts

@@ -24,7 +24,7 @@
  * INV-6: Undo race condition — 409 on expired window. Server rejects undo
  *        attempts after availableUntil deadline.
  *
- * @see DECISIONS.md for design rationale
+ * @see decisions/ADR-CONT-037.md for design rationale
  */
 
 import type { PreviewArtifactKind } from './preview';

package/src/message-parts/preview.ts

@@ -14,7 +14,7 @@
  * - User messages during preview do not affect mode; only assistant output controls persistence
  * - At most one preview proposal is active at a time (multiple previews are sequential, not concurrent)
  *
- * @see DECISIONS.md for design rationale
+ * @see decisions/ADR-CONT-026.md for design rationale
  */
 
 /**

package/src/message-parts/types.ts

@@ -10,7 +10,7 @@
  * - TextPart is the ONLY part type that may be streamed char-by-char
  * - Once a surface is added, the turn is in "surface phase" permanently
  *
- * @see DECISIONS.md ADR-2026-01-022 for design rationale
+ * @see decisions/ADR-CONT-026.md for design rationale
  */
 
 import type { ToolListMessagePart } from '../mcp/index'

package/src/message-parts/wire.ts

@@ -7,7 +7,7 @@
  * Use these in backend code when writing to UIMessageStream.
  * Frontend normalizes wire format to semantic types.
  *
- * @see DECISIONS.md ADR-2026-01-022 for design rationale
+ * @see decisions/ADR-CONT-026.md for design rationale
  */
 
 import type { MCPToolDescriptor, ToolListDataPart } from '../mcp/index'

package/src/resource-keys.ts

@@ -0,0 +1,174 @@
+/**
+ * ResourceKey — shared vocabulary for resources across the system.
+ * All keys MUST include scope (orgId or userId) to prevent cross-org cache leaks.
+ * Naming: camelCase nouns. Collections plural, identities singular.
+ */
+export type ResourceKey =
+  // Collections (plural) — lists of entities
+  | { type: 'members'; orgId: string }
+  | { type: 'departments'; orgId: string }
+  | { type: 'chats'; orgId: string }
+  | { type: 'teams'; orgId: string }
+  | { type: 'integrations'; orgId: string }
+  | { type: 'invites'; orgId: string }
+  | { type: 'auditEvents'; orgId: string }
+  // Identities (singular) — single entities
+  | { type: 'member'; orgId: string; memberId: string }
+  | { type: 'workspace'; orgId: string }
+  | { type: 'authSettings'; orgId: string }
+  | { type: 'billing'; orgId: string }
+  | { type: 'aiUsage'; orgId: string }
+  | { type: 'deletionEligibility'; orgId: string }
+  | { type: 'transferOwnership'; orgId: string }
+  | { type: 'goals'; orgId: string }
+  // User-scoped
+  | { type: 'dismissedBanners'; userId: string }
+  | { type: 'userOrgs'; userId: string }
+  | { type: 'sessions'; userId: string };
+
+/**
+ * Action — structured mutation key used across execution system, audit, permissions.
+ */
+export type Action = { resource: string; verb: string };
+
+/**
+ * Resolve scope for cache partitioning. Handles impersonation.
+ */
+export function resolveScope(context: {
+  orgId: string;
+  impersonatedOrgId?: string;
+}): { orgId: string } {
+  return { orgId: context.impersonatedOrgId ?? context.orgId };
+}
+
+/** All ResourceKey type literals for exhaustive checking. */
+const ORG_SCOPED_TYPES = [
+  'members', 'departments', 'chats', 'teams', 'integrations', 'invites',
+  'auditEvents', 'workspace', 'authSettings', 'billing', 'aiUsage',
+  'deletionEligibility', 'transferOwnership', 'goals',
+] as const;
+
+const USER_SCOPED_TYPES = ['dismissedBanners', 'userOrgs', 'sessions'] as const;
+
+/**
+ * Canonical ResourceKey → query key conversion.
+ * This is the ONLY function that constructs query keys — no ad-hoc key
+ * construction anywhere in the codebase.
+ *
+ * Mapping is deterministic and stable:
+ *   { type: 'members', orgId: 'abc' }                → ['members', 'abc']
+ *   { type: 'member', orgId: 'abc', memberId: '123' } → ['member', 'abc', '123']
+ */
+export function toQueryKey(key: ResourceKey): readonly string[] {
+  switch (key.type) {
+    // Identity with extra field
+    case 'member':
+      return [key.type, key.orgId, key.memberId] as const;
+
+    // User-scoped
+    case 'dismissedBanners':
+    case 'userOrgs':
+    case 'sessions':
+      return [key.type, key.userId] as const;
+
+    // Org-scoped collections and identities
+    case 'members':
+    case 'departments':
+    case 'chats':
+    case 'teams':
+    case 'integrations':
+    case 'invites':
+    case 'auditEvents':
+    case 'workspace':
+    case 'authSettings':
+    case 'billing':
+    case 'aiUsage':
+    case 'deletionEligibility':
+    case 'transferOwnership':
+    case 'goals':
+      return [key.type, key.orgId] as const;
+
+    default: {
+      const _exhaustive: never = key;
+      throw new Error(`Unknown resource type: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}
+
+/**
+ * Inverse of toQueryKey — reconstructs a ResourceKey from a query key array.
+ * Throws if the array cannot be parsed into a valid ResourceKey.
+ */
+export function fromQueryKey(queryKey: readonly string[]): ResourceKey {
+  const [type, ...rest] = queryKey;
+
+  if (!type || rest.length === 0) {
+    throw new Error(`Invalid query key: expected at least [type, scope], got ${JSON.stringify(queryKey)}`);
+  }
+
+  // Identity with extra field
+  if (type === 'member') {
+    if (rest.length !== 2) {
+      throw new Error(`Invalid query key for 'member': expected [type, orgId, memberId], got ${JSON.stringify(queryKey)}`);
+    }
+    return { type: 'member', orgId: rest[0], memberId: rest[1] };
+  }
+
+  // User-scoped types
+  if ((USER_SCOPED_TYPES as readonly string[]).includes(type)) {
+    return { type, userId: rest[0] } as ResourceKey;
+  }
+
+  // Org-scoped types
+  if ((ORG_SCOPED_TYPES as readonly string[]).includes(type)) {
+    return { type, orgId: rest[0] } as ResourceKey;
+  }
+
+  throw new Error(`Unknown resource type in query key: '${type}'`);
+}
+
+/**
+ * Bidirectional resource relationships.
+ * TanStack does NOT support prefix matching across different key shapes.
+ * When invalidating a collection, we must also invalidate related identity entries (and vice versa).
+ */
+export const resourceRelationships: Record<string, string[]> = {
+  members: ['member'],
+  member: ['members'],
+  departments: ['department'],
+  department: ['departments'],
+  chats: ['chat'],
+  chat: ['chats'],
+  teams: ['team'],
+  team: ['teams'],
+};
+
+/**
+ * Strict predicate for matching resource keys.
+ * Compares type + scope fields exactly. No partial matching. No loose comparisons.
+ * Used by invalidateResource with TanStack's predicate-based invalidation.
+ */
+export function matchesResourceKey(queryKey: readonly unknown[], targetKey: ResourceKey): boolean {
+  if (!Array.isArray(queryKey) && !isReadonlyArray(queryKey)) return false;
+  const stringKey = queryKey.filter((v): v is string => typeof v === 'string');
+  if (stringKey.length !== queryKey.length) return false;
+
+  let parsed: ResourceKey;
+  try {
+    parsed = fromQueryKey(stringKey);
+  } catch {
+    return false;
+  }
+
+  if (parsed.type !== targetKey.type) return false;
+
+  if ('orgId' in parsed && 'orgId' in targetKey && parsed.orgId !== targetKey.orgId) return false;
+  if ('userId' in parsed && 'userId' in targetKey && parsed.userId !== targetKey.userId) return false;
+  if ('memberId' in parsed && 'memberId' in targetKey && parsed.memberId !== targetKey.memberId) return false;
+
+  return true;
+}
+
+function isReadonlyArray(value: unknown): value is readonly unknown[] {
+  return Array.isArray(value);
+}

package/src/resource-response.ts

@@ -0,0 +1,9 @@
+/**
+ * Standard response wrapper for resource endpoints.
+ * version MUST come from data source (entity.updatedAt), NEVER from request time (Date.now()).
+ * Using request time defeats invalidation — race conditions reappear.
+ */
+export type ResourceResponse<T> = {
+  data: T;
+  version: number;
+};

package/src/usage/README.md

@@ -0,0 +1,34 @@
+# usage/
+
+Type vocabulary for AI usage tracking, execution telemetry, and budget governance.
+
+## Purpose
+
+Defines shared types for two usage tracking layers: (1) low-level AI usage events (token counts, costs per model/feature) and (2) higher-level runtime execution telemetry (per-request aggregates across tool loops). Also includes budget governance types for org-level spend controls.
+
+## Invariants
+
+- All cost fields are `string` (decimal USD with 8 decimal places) — never floating point
+- Types only — no runtime logic, no database access
+- `AiFeature` enum must stay in sync with the backend's `ai_feature` pgEnum
+- `ChatRuntimeProfile` dependency flows from `src/chat/` — usage types reference it, not the reverse
+
+## Public API
+
+**AI Usage Types (`types.ts`):**
+- `AiFeature` — Feature categories: `chat`, `chat_title`, `ingest_summarize`, `ingest_embedding`, `goal_extraction`
+- `UsageSummary`, `DailyUsage`, `UsageByModel`, `UsageByFeature`, `UsageByUser` — Aggregation response shapes
+- `UnifiedUsageResponse` and related interfaces — Combined usage dashboard response
+
+**Execution Telemetry (`execution-types.ts`):**
+- `RuntimeExecutionTelemetry` — Per-execution record (tokens, cost, duration, profile, success)
+- `ExecutionFailureReason` — Failure categories: `tool_error`, `timeout`, `model_error`, `budget_exceeded`, `client_disconnect`, `unknown`
+- `OrgExecutionSummary`, `DailyExecutionStats`, `ExecutionByUser`, `ExecutionDetail`, `ProfileStats` — Aggregation shapes
+
+**Budget Governance (`execution-types.ts`):**
+- `BudgetCheck` — Pre-execution budget gate result
+- `OrgBudgetSettings` — Org budget configuration shape
+
+## Dependencies
+
+- `src/chat/` — `ChatRuntimeProfile` type (used by execution telemetry)