@company-semantics/contracts 0.20.0 → 0.21.1

package/package.json

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

package/src/guards/config.ts

@@ -319,11 +319,6 @@ export interface GuardCheckRegistry {
     structural?: BoundGuardCheck[];
     behavioral?: BoundGuardCheck[];
     invariants?: BoundGuardCheck[];
-    /**
-     * @deprecated Evolution guards are CI-owned. Use evolutionBaselines instead.
-     * Product repos should not provide evolution check implementations.
-     */
-    evolution?: BoundGuardCheck[];
     /** Meta-guards: protect the guard system itself (coverage correctness) */
     meta?: BoundGuardCheck[];
   };

package/src/identity/README.md

@@ -0,0 +1,31 @@
+# identity/
+
+## Purpose
+
+TypeScript types and functions for user identity and display name resolution.
+
+## Invariants
+
+- Types with minimal runtime code (pure functions only, no side effects)
+- No external dependencies (contracts policy)
+- `preferredName` is assistant-facing only, not user-edited label
+- `fullName` is user-editable override of derived firstName + lastName
+- `displayName` is NEVER stored — always derived at read time via `resolveDisplayName()`
+- `resolveDisplayName()` is the ONLY approved way to determine assistant addressing
+
+## Public API
+
+### Types
+
+- `ISODateString` — ISO 8601 date-time string alias
+- `UserIdentity` — User identity with name fields and timestamps
+
+### Functions
+
+- `deriveFullName(firstName, lastName?)` — Derive full name from components
+- `resolveDisplayName(identity)` — Get display name (preferredName or firstName)
+
+## Dependencies
+
+**Imports from:** (none — leaf module)
+**Imported by:** company-semantics-backend, company-semantics-app

package/src/identity/display-name.ts

@@ -0,0 +1,60 @@
+/**
+ * Display Name Functions
+ *
+ * Canonical functions for deriving and resolving user display names.
+ * These are the ONLY approved ways to handle display name logic.
+ *
+ * @see DECISIONS.md ADR-2026-01-020 for design rationale
+ */
+
+import type { UserIdentity } from './types.js';
+
+// =============================================================================
+// Full Name Derivation
+// =============================================================================
+
+/**
+ * Derive fullName from firstName and lastName.
+ *
+ * Invariant: fullName MUST be derived automatically unless explicitly provided.
+ *
+ * @param firstName - User's first name (required)
+ * @param lastName - User's last name (optional)
+ * @returns Combined full name
+ *
+ * @example
+ * deriveFullName("Ian", "Heidt")  // "Ian Heidt"
+ * deriveFullName("Ian")           // "Ian"
+ */
+export function deriveFullName(firstName: string, lastName?: string): string {
+  return lastName ? `${firstName} ${lastName}` : firstName;
+}
+
+// =============================================================================
+// Display Name Resolution
+// =============================================================================
+
+/**
+ * Resolve the display name for assistant addressing.
+ *
+ * This is the ONLY approved way to determine how the assistant
+ * or UI should address a user.
+ *
+ * Invariants:
+ * - preferredName overrides if present and non-empty
+ * - Falls back to firstName (never blank)
+ * - displayName is NEVER stored, always derived at read time
+ *
+ * @param identity - Object with preferredName and firstName fields
+ * @returns The resolved display name
+ *
+ * @example
+ * resolveDisplayName({ firstName: "Ian", preferredName: "Heidt" })  // "Heidt"
+ * resolveDisplayName({ firstName: "Ian", preferredName: "" })       // "Ian"
+ * resolveDisplayName({ firstName: "Ian" })                          // "Ian"
+ */
+export function resolveDisplayName(
+  identity: Pick<UserIdentity, 'preferredName' | 'firstName'>
+): string {
+  return identity.preferredName?.trim() || identity.firstName;
+}

package/src/identity/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Identity Types Barrel
+ *
+ * Re-exports user identity vocabulary types and functions.
+ * Import from '@company-semantics/contracts' (root).
+ */
+
+// Types
+export type { ISODateString, UserIdentity } from './types.js';
+
+// Functions
+export { deriveFullName, resolveDisplayName } from './display-name.js';

package/src/identity/types.ts

@@ -0,0 +1,62 @@
+/**
+ * User Identity Types
+ *
+ * Canonical vocabulary for user identity across Company Semantics.
+ *
+ * @see DECISIONS.md ADR-2026-01-020 for design rationale
+ */
+
+// =============================================================================
+// Utility Types
+// =============================================================================
+
+/**
+ * ISO 8601 date-time string.
+ * Example: "2025-12-25T14:30:00.000Z"
+ */
+export type ISODateString = string;
+
+// =============================================================================
+// User Identity
+// =============================================================================
+
+/**
+ * User identity information.
+ * Represents the canonical identity vocabulary for a user.
+ *
+ * Invariants:
+ * - firstName is required (always addressable)
+ * - lastName is optional (single-name users exist globally)
+ * - fullName is STORED (derived by default, user-editable)
+ * - preferredName is STORED (assistant-only addressing)
+ * - displayName is NEVER stored (derived at read time via resolveDisplayName)
+ */
+export type UserIdentity = {
+  /** Unique user identifier */
+  userId: string;
+
+  /** User's first name (required) */
+  firstName: string;
+
+  /** User's last name (optional) */
+  lastName?: string;
+
+  /**
+   * Full name for display in UI, exports, and audit logs.
+   * Derived by default from firstName + lastName, but user-editable.
+   */
+  fullName: string;
+
+  /**
+   * Preferred name for AI assistant to use.
+   * Assistant-only field; may differ from firstName.
+   * If not set, assistant falls back to firstName via resolveDisplayName().
+   */
+  preferredName?: string;
+
+  /** When the identity was created */
+  createdAt: ISODateString;
+
+  /** When the identity was last updated */
+  updatedAt: ISODateString;
+};

package/src/index.ts

@@ -84,3 +84,19 @@ export {
 // @see ADR-2025-12-011 for design rationale
 export { COMPATIBILITY } from './compatibility.js'
 export type { Compatibility, Deprecation } from './compatibility.js'
+
+// User identity types and functions
+// @see ADR-2026-01-020 for design rationale
+export type { ISODateString, UserIdentity } from './identity/index.js'
+export { deriveFullName, resolveDisplayName } from './identity/index.js'
+
+// MCP tool discovery types
+// @see company-semantics-backend/src/interfaces/mcp/ for implementation
+export type {
+  ToolCategory,
+  ToolVisibility,
+  ToolInvocationMode,
+  MCPToolDescriptor,
+  ToolDiscoveryResponse,
+  ToolListMessagePart,
+} from './mcp/index.js'

package/src/mcp/index.ts

@@ -0,0 +1,85 @@
+/**
+ * MCP Tool Discovery Types
+ *
+ * Types for tool discovery flow (read-only, UI-first).
+ * Same descriptor used for discovery and invocation, different fields matter.
+ *
+ * INVARIANTS:
+ * - Discovery is descriptive (never executes)
+ * - Invocation is authoritative (runtime is executor)
+ * - Tool discovery output must be runtime-sourced
+ * - Tool discovery must not be streamed char-by-char
+ *
+ * @see company-semantics-backend/src/interfaces/mcp/ for implementation
+ */
+
+/**
+ * Tool categories for grouping in UI.
+ * Maps to user mental model, not implementation.
+ */
+export type ToolCategory =
+  | 'system' // System status, health checks
+  | 'data' // Data access, ingestion, queries
+  | 'connections' // OAuth, integrations
+  | 'automation' // Scheduled tasks, triggers
+  | 'developer' // Debug, internal tools
+
+/**
+ * Tool visibility levels.
+ * Controls who can see the tool in discovery.
+ */
+export type ToolVisibility = 'user' | 'admin'
+
+/**
+ * How the tool can be invoked.
+ * - manual: User must explicitly request
+ * - assistant: AI can invoke proactively
+ * - hybrid: Both manual and assistant invocation
+ */
+export type ToolInvocationMode = 'manual' | 'assistant' | 'hybrid'
+
+/**
+ * Complete tool descriptor for discovery and invocation.
+ *
+ * Discovery uses: id, name, description, category
+ * Invocation uses: id, requiresConfirmation, invocationMode
+ */
+export interface MCPToolDescriptor {
+  /** Unique identifier (matches MCP tool name, e.g., 'cs_help') */
+  id: string
+  /** Human-readable name for display */
+  name: string
+  /** User-facing description (what it does, not how) */
+  description: string
+  /** Grouping category for UI organization */
+  category: ToolCategory
+  /** Whether user confirmation is required before execution */
+  requiresConfirmation: boolean
+  /** How the tool can be triggered */
+  invocationMode: ToolInvocationMode
+  /** Who can see this tool */
+  visibility: ToolVisibility
+}
+
+/**
+ * Response shape for tool discovery endpoint.
+ * Used by GET /api/capabilities/tools
+ *
+ * Transport-level type (HTTP API response).
+ * No timestamp - ephemeral, regenerated often.
+ */
+export interface ToolDiscoveryResponse {
+  /** Tools available to the current user */
+  tools: MCPToolDescriptor[]
+}
+
+/**
+ * Structured message part for protocol-level rendering.
+ *
+ * Conversation-level type (chat protocol part).
+ * Rendered atomically, not streamed char-by-char.
+ */
+export interface ToolListMessagePart {
+  type: 'tool-list'
+  tools: MCPToolDescriptor[]
+}