@company-semantics/contracts 88.0.0 → 88.1.0

package/package.json

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

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = '2be23467fbc1' as const;
-export const SPEC_HASH_FULL = '2be23467fbc1502200e556fec254b5b7419e748cbe86d73bacb358ee2bb4ac45' as const;
+export const SPEC_HASH = 'edc033bdac67' as const;
+export const SPEC_HASH_FULL = 'edc033bdac6767eaf9965214f6dfed6c536d48fb5f1f77a48e1af26533633fe1' as const;

package/src/api/generated.ts

@@ -519,6 +519,24 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/chats/{id}/messages/{messageId}/feedback": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /** Record or replace the caller's rating of a chat message */
+        put: operations["putChatMessageFeedback"];
+        post?: never;
+        /** Withdraw the caller's rating of a chat message */
+        delete: operations["deleteChatMessageFeedback"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/workspace/access": {
         parameters: {
             query?: never;
@@ -5355,6 +5373,18 @@ export interface components {
             /** @constant */
             state: "ineligible";
         };
+        ChatMessageFeedbackResponse: {
+            /** @enum {string} */
+            rating: "up" | "down";
+            reason: string | null;
+            /** Format: date-time */
+            updatedAt: string;
+        };
+        PutChatMessageFeedbackRequest: {
+            /** @enum {string} */
+            rating: "up" | "down";
+            reason?: string;
+        };
         WorkspaceAccessResponse: {
             hasAccess: boolean;
         };
@@ -10734,6 +10764,68 @@ export interface operations {
             };
         };
     };
+    putChatMessageFeedback: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+                messageId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["PutChatMessageFeedbackRequest"];
+            };
+        };
+        responses: {
+            /** @description Rating recorded */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ChatMessageFeedbackResponse"];
+                };
+            };
+            /** @description Chat not readable by the caller, or message not in it */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    deleteChatMessageFeedback: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+                messageId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Rating withdrawn (or there was none) */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Chat not readable by the caller, or message not in it */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     getWorkspaceAccess: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -25,6 +25,7 @@ export const openApiRoutes = {
   '/api/chats/{id}/generate-title': ['POST'],
   '/api/chats/{id}/messages': ['POST'],
   '/api/chats/{id}/messages/{messageId}': ['DELETE'],
+  '/api/chats/{id}/messages/{messageId}/feedback': ['DELETE', 'PUT'],
   '/api/chats/{id}/participants': ['GET', 'POST'],
   '/api/chats/{id}/participants/{userId}': ['DELETE', 'PATCH'],
   '/api/chats/{id}/pin': ['DELETE', 'POST'],

package/src/index.ts

@@ -253,9 +253,7 @@ export type {
 // lists exactly the subset of its domain the root exposes, by name — see
 // src/root-exports/README.md.
 export * from "./root-exports/delivery";
-
 export * from "./root-exports/collaboration";
-
 export * from "./root-exports/org-workspace";
 
 // The org sharing AccessLevel is exported BY NAME, not through a root-exports
@@ -326,3 +324,7 @@ export * from "./product-intake/index";
 // for one target document; the wire carries facts and a count, never content.
 // See ./source-sync/vocabulary.ts and ./source-sync/schemas.ts.
 export * from "./source-sync/index";
+
+// Quality control plane vocabulary (PRD-01088 / quality-control-plane)
+// Closed evaluation/decision sets plus QualityRunReportSchema — ids, scores and failure kinds only. See ./quality/index.ts.
+export * from "./quality/index";

package/src/mcp/README.md

@@ -19,25 +19,25 @@ Type vocabulary for MCP (Model Context Protocol) tool discovery, invocation meta
 
 ## Public API
 
-- `CapabilityGraph` _(type)_
-- `CapabilityGraphEdge` _(type)_
+- `CapabilityGraph` _(type)_ — Capability graph derived from tool resource flow metadata.
+- `CapabilityGraphEdge` _(type)_ — Edge in the capability graph connecting two tools via a resource.
 - `FailureContext` _(type)_ — Structured recovery context emitted when an MCP tool call fails.
-- `MCPToolDescriptor` _(type)_
+- `MCPToolDescriptor` _(type)_ — Complete tool descriptor for discovery and invocation.
 - `RecoveryAction` _(type)_ — A recovery action the agent may take.
 - `ResourceType` _(type)_ — Resource type vocabulary for MCP tool resource flow.
 - `ToolCategory` _(type)_
-- `ToolComplexity` _(type)_
+- `ToolComplexity` _(type)_ — Tool computational complexity classification.
 - `ToolDiscoveryResponse` _(type)_
-- `ToolDomain` _(type)_
-- `ToolEffectClass` _(type)_
-- `ToolIntegration` _(type)_
-- `ToolIntent` _(type)_
-- `ToolInvocationMode` _(type)_
+- `ToolDomain` _(type)_ — Tool domain taxonomy.
+- `ToolEffectClass` _(type)_ — Tool effect classification.
+- `ToolIntegration` _(type)_ — Integration provider tag for tools.
+- `ToolIntent` _(type)_ — Tool intent classification.
+- `ToolInvocationMode` _(type)_ — How the tool can be invoked. - manual: User must explicitly request - assistant: AI can invoke proactively -…
 - `ToolListDataPart` _(type)_
 - `ToolListMessagePart` _(type)_
-- `ToolStability` _(type)_
-- `ToolVisibility` _(type)_
-- `ToolWorkflow` _(type)_
+- `ToolStability` _(type)_ — Tool lifecycle stability classification. - experimental: May change or be removed without notice - stable…
+- `ToolVisibility` _(type)_ — Tool visibility levels.
+- `ToolWorkflow` _(type)_ — Named workflow derived from capability graph paths.
 - `buildCapabilityGraph` — Build a capability graph from tool resource flow metadata.
 
 <!-- END GENERATED: readme-public-api -->

package/src/mcp/capability-graph.ts

@@ -3,7 +3,7 @@ import type {
   CapabilityGraph,
   CapabilityGraphEdge,
   ToolWorkflow,
-} from "./index";
+} from "./tool-descriptor";
 
 /**
  * Build a capability graph from tool resource flow metadata.

package/src/mcp/index.ts

@@ -1,7 +1,22 @@
-import type { ResourceType } from "./resources";
+import type { CapabilityGraph, MCPToolDescriptor } from "./tool-descriptor";
 export type { ResourceType } from "./resources";
 export { buildCapabilityGraph } from "./capability-graph";
 export type { FailureContext, RecoveryAction } from "./failure-context";
+export type {
+  ToolCategory,
+  ToolDomain,
+  ToolVisibility,
+  ToolInvocationMode,
+  ToolEffectClass,
+  ToolIntent,
+  ToolStability,
+  ToolComplexity,
+  ToolIntegration,
+  MCPToolDescriptor,
+  CapabilityGraphEdge,
+  ToolWorkflow,
+  CapabilityGraph,
+} from "./tool-descriptor";
 
 /**
  * MCP Tool Discovery Types
@@ -22,249 +37,6 @@ export type { FailureContext, RecoveryAction } from "./failure-context";
  * @see company-semantics-backend/src/interfaces/mcp/ for implementation
  */
 
-/**
- * @deprecated Use ToolDomain instead. ToolCategory is too coarse —
- * 'data' conflates discovery, ingestion, and coverage.
- */
-export type ToolCategory =
-  "system" | "data" | "connections" | "automation" | "developer";
-
-/**
- * Tool domain taxonomy.
- *
- * Each value maps to a distinct domain boundary in the system architecture.
- * Replaces ToolCategory which was too coarse for resource flow reasoning.
- *
- * - organization: Org settings, membership, billing queries
- * - identity: User profile, auth state, preferences
- * - integrations: OAuth connections, provider management
- * - ingestion: Data import, sync jobs, source configuration
- * - discovery: Search, exploration, content queries
- * - knowledge: Fingerprints, embeddings, knowledge graph
- * - system: Health, status, runtime diagnostics
- */
-export type ToolDomain =
-  | "organization"
-  | "identity"
-  | "integrations"
-  | "ingestion"
-  | "discovery"
-  | "knowledge"
-  | "system";
-
-/**
- * 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";
-
-/**
- * Tool effect classification.
- * Effect classification is orthogonal to requiresConfirmation and requiresApproval.
- * - effectClass: "Does this tool mutate state?"
- * - requiresConfirmation: "Does the user need to approve before execution?"
- * - requiresApproval: "Does this need cross-principal authorization?"
- * An effectful tool may auto-execute (requiresConfirmation: false) for low-risk operations.
- * An effectful tool may require approval without confirmation.
- */
-export type ToolEffectClass = "pure" | "effectful";
-
-/**
- * Tool intent classification.
- *
- * Classifies what the tool does to the system:
- * - read: Pure data retrieval (no side effects)
- * - mutate: State change (creates, updates, deletes)
- * - analysis: Computation over data without mutation (aggregation, scoring)
- *
- * Note: 'control' was removed — system-level operations (health, status,
- * runtime) use 'read' intent in the 'system' domain. Control is a domain
- * classification, not an intent.
- *
- * INVARIANT: intent 'mutate' + risk 'high' → requiresConfirmation must be true.
- * Enforced in backend tool registration, typed here for documentation.
- */
-export type ToolIntent = "read" | "mutate" | "analysis";
-
-/**
- * Tool lifecycle stability classification.
- *
- * - experimental: May change or be removed without notice
- * - stable: Production-ready with backward compatibility guarantees
- * - deprecated: Scheduled for removal, consumers should migrate
- */
-export type ToolStability = "experimental" | "stable" | "deprecated";
-
-/**
- * Tool computational complexity classification.
- *
- * Classifies the cost and latency profile of a tool invocation:
- * - trivial: Sub-100ms, in-memory or single DB lookup
- * - moderate: 100ms-5s, may involve external API calls
- * - heavy: 5s+, batch processing, large data transfers, long-running ops
- */
-export type ToolComplexity = "trivial" | "moderate" | "heavy";
-
-/**
- * Integration provider tag for tools.
- *
- * Known values correspond to registered OAuth providers.
- * Extensible via (string & {}) — new integrations do not require
- * a contracts release, but known values get autocomplete.
- */
-export type ToolIntegration = "slack" | "google" | "zoom" | (string & {});
-
-/**
- * Complete tool descriptor for discovery and invocation.
- *
- * Discovery uses: id, name, description, category
- * Invocation uses: id, requiresConfirmation, invocationMode, effectClass
- */
-// @vocabulary-exempt reason: MCPToolDescriptor is a single cohesive descriptor consumed by multiple repos; splitting would break consumers
-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;
-  /**
-   * Whether this tool causes durable state change.
-   * Effectful = any tool that can cause durable state change (DB writes, external API calls, background job enqueue).
-   * Pure = read-only operations, URL generation, status queries.
-   *
-   * Orthogonal to requiresConfirmation — an effectful tool may auto-execute
-   * for low-risk operations, and a pure tool never needs confirmation.
-   * The bridge enforces: effectful tools must return previewResponse()
-   * with ExecutionIntent, never direct side effects.
-   */
-  effectClass: ToolEffectClass;
-  /** How the tool can be triggered */
-  invocationMode: ToolInvocationMode;
-  /** Who can see this tool */
-  visibility: ToolVisibility;
-
-  // --- New fields (PRD-00265) ---
-
-  /** Domain taxonomy classification. Replaces category for routing and grouping. */
-  domain: ToolDomain;
-  /**
-   * Integration providers this tool interacts with.
-   * Empty or omitted for tools that don't touch external integrations.
-   */
-  integrations?: ToolIntegration[];
-  /**
-   * User-impact risk classification.
-   * - none: Read-only, no side effects
-   * - low: Reversible mutation (can be undone)
-   * - moderate: User-visible side effect (notification sent, state changed)
-   * - high: Destructive or irreversible (data deletion, external action)
-   *
-   * INVARIANT: intent 'mutate' + risk 'high' → requiresConfirmation must be true.
-   */
-  risk: "none" | "low" | "moderate" | "high";
-  /** What the tool does to the system (read, mutate, analysis). */
-  intent: ToolIntent;
-  /** Lifecycle stability classification. */
-  stability: ToolStability;
-  /** Computational complexity and latency profile. */
-  complexity: ToolComplexity;
-  /**
-   * Input schema version number.
-   * Disambiguates input schema versioning from tool behavior versioning.
-   * Increment when the tool's input schema changes shape.
-   */
-  schemaVersion: number;
-  /**
-   * Authorization scopes required to invoke this tool.
-   * References scope strings from trust/scopes.ts.
-   * Omit for tools with no specific scope requirements.
-   */
-  scopes?: string[];
-  /**
-   * Resource types this tool produces (creates or outputs).
-   * Used for capability graph derivation — enables workflow ordering
-   * via resource flow instead of explicit `requires` fields.
-   */
-  produces?: ResourceType[];
-  /**
-   * Resource types this tool consumes (requires as input).
-   * Used for capability graph derivation — a tool that consumes
-   * 'integration.connection' can only run after a tool that produces it.
-   */
-  consumes?: ResourceType[];
-  /**
-   * Mutation-capability gate (ADR-BE-241). When present, the tool is locked
-   * unless the viewer's resolved capabilities permit it — the SINGLE source of
-   * truth consumed by BOTH the backend execution gate and the frontend tool-lock
-   * UI (replacing the previously triplicated ACTION_TOOL_GATES / FIELD_GATES /
-   * ACTION_GATES maps).
-   * - kind 'field': `path` addresses a FieldCapability in CapabilitiesResponse
-   *   (e.g. 'org.name', 'profile.fullName'); locked unless state === 'editable'.
-   * - kind 'action': `path` addresses an ActionCapability under `.actions`
-   *   (e.g. 'members.invite', 'orgAdmins.manage'); locked unless 'allowed'.
-   * Absent ⇒ ungated (gating is additive).
-   */
-  capabilityGate?: { kind: "field" | "action"; path: string };
-}
-
-/**
- * Edge in the capability graph connecting two tools via a resource.
- * A tool that produces a resource connects to tools that consume it.
- *
- * @see capability-graph.ts for buildCapabilityGraph() implementation
- */
-export interface CapabilityGraphEdge {
-  /** Tool ID that produces the resource */
-  from: string;
-  /** Tool ID that consumes the resource */
-  to: string;
-  /** Resource type flowing between tools */
-  resource: ResourceType;
-  /** Resource domain (extracted from resource namespace prefix, e.g., 'slack' from 'slack.channel') */
-  domain?: string;
-}
-
-/**
- * Named workflow derived from capability graph paths.
- * Represents a common multi-tool sequence (e.g., "Connect Slack → Ingest → Query").
- *
- * @see capability-graph.ts for buildCapabilityGraph() implementation
- */
-export interface ToolWorkflow {
-  /** Workflow name (e.g., "Slack Onboarding") */
-  name: string;
-  /** Human-readable description of the workflow */
-  description: string;
-  /** Ordered list of tool IDs in this workflow */
-  steps: string[];
-}
-
-/**
- * Capability graph derived from tool resource flow metadata.
- * Built from produces/consumes fields on MCPToolDescriptor.
- *
- * @see capability-graph.ts for buildCapabilityGraph() implementation
- */
-export interface CapabilityGraph {
-  /** Resource flow edges between tools */
-  edges: CapabilityGraphEdge[];
-  /** Named workflows derived from graph paths */
-  workflows: ToolWorkflow[];
-}
-
 /**
  * Response shape for tool discovery endpoint.
  * Used by GET /api/capabilities/tools