@company-semantics/contracts 9.0.0 → 9.2.0

package/src/mcp/capability-graph.ts

@@ -3,7 +3,7 @@ import type {
   CapabilityGraph,
   CapabilityGraphEdge,
   ToolWorkflow,
-} from './index'
+} from "./index";
 
 /**
  * Build a capability graph from tool resource flow metadata.
@@ -14,25 +14,27 @@ import type {
  * For each tool's `consumes` array, finds all tools whose `produces`
  * includes that ResourceType and creates a CapabilityGraphEdge.
  */
-export function buildCapabilityGraph(tools: MCPToolDescriptor[]): CapabilityGraph {
-  const edges: CapabilityGraphEdge[] = []
+export function buildCapabilityGraph(
+  tools: MCPToolDescriptor[],
+): CapabilityGraph {
+  const edges: CapabilityGraphEdge[] = [];
 
   for (const consumer of tools) {
     for (const resourceType of consumer.consumes ?? []) {
-      const producers = tools.filter(t => t.produces?.includes(resourceType))
+      const producers = tools.filter((t) => t.produces?.includes(resourceType));
       for (const producer of producers) {
         edges.push({
           from: producer.id,
           to: consumer.id,
           resource: resourceType,
-          domain: resourceType.split('.')[0],
-        })
+          domain: resourceType.split(".")[0],
+        });
       }
     }
   }
 
-  const workflows = deriveWorkflows(tools, edges)
-  return { edges, workflows }
+  const workflows = deriveWorkflows(tools, edges);
+  return { edges, workflows };
 }
 
 /**
@@ -48,66 +50,66 @@ function deriveWorkflows(
   edges: CapabilityGraphEdge[],
 ): ToolWorkflow[] {
   // Build adjacency: tool ID → outgoing edges, tool ID → incoming edges
-  const outgoing = new Map<string, CapabilityGraphEdge[]>()
-  const incoming = new Map<string, CapabilityGraphEdge[]>()
+  const outgoing = new Map<string, CapabilityGraphEdge[]>();
+  const incoming = new Map<string, CapabilityGraphEdge[]>();
 
   for (const edge of edges) {
-    if (!outgoing.has(edge.from)) outgoing.set(edge.from, [])
-    outgoing.get(edge.from)!.push(edge)
-    if (!incoming.has(edge.to)) incoming.set(edge.to, [])
-    incoming.get(edge.to)!.push(edge)
+    if (!outgoing.has(edge.from)) outgoing.set(edge.from, []);
+    outgoing.get(edge.from)!.push(edge);
+    if (!incoming.has(edge.to)) incoming.set(edge.to, []);
+    incoming.get(edge.to)!.push(edge);
   }
 
   // Find chain start nodes: have outgoing edges, no incoming edges
   const startNodes = [...outgoing.keys()].filter(
-    id => !incoming.has(id) || incoming.get(id)!.length === 0,
-  )
+    (id) => !incoming.has(id) || incoming.get(id)!.length === 0,
+  );
 
-  const workflows: ToolWorkflow[] = []
-  const visited = new Set<string>()
+  const workflows: ToolWorkflow[] = [];
+  const visited = new Set<string>();
 
   for (const start of startNodes) {
-    if (visited.has(start)) continue
+    if (visited.has(start)) continue;
 
-    const chain: string[] = [start]
-    visited.add(start)
-    let current = start
+    const chain: string[] = [start];
+    visited.add(start);
+    let current = start;
 
     // Walk forward: follow single outgoing edge while next node has single incoming edge
     while (true) {
-      const outs = outgoing.get(current)
-      if (!outs || outs.length !== 1) break
+      const outs = outgoing.get(current);
+      if (!outs || outs.length !== 1) break;
 
-      const next = outs[0].to
-      const ins = incoming.get(next)
-      if (!ins || ins.length !== 1) break
+      const next = outs[0].to;
+      const ins = incoming.get(next);
+      if (!ins || ins.length !== 1) break;
 
-      if (visited.has(next)) break
-      visited.add(next)
-      chain.push(next)
-      current = next
+      if (visited.has(next)) break;
+      visited.add(next);
+      chain.push(next);
+      current = next;
     }
 
     // Only emit workflows with > 2 steps
     if (chain.length > 2) {
-      const toolMap = new Map(tools.map(t => [t.id, t]))
-      const chainTools = chain.map(id => toolMap.get(id)).filter(Boolean)
+      const toolMap = new Map(tools.map((t) => [t.id, t]));
+      const chainTools = chain.map((id) => toolMap.get(id)).filter(Boolean);
 
       // Derive name from common integration or domain
       const integrations = chainTools
-        .flatMap(t => t!.integrations ?? [])
-        .filter((v, i, a) => a.indexOf(v) === i)
+        .flatMap((t) => t!.integrations ?? [])
+        .filter((v, i, a) => a.indexOf(v) === i);
       const name =
         integrations.length === 1
           ? `${integrations[0]}_ingestion`
-          : `workflow_${chain[0]}`
+          : `workflow_${chain[0]}`;
 
-      const steps = chain.map(s => s.replace(/^cs_/, ''))
-      const description = `Workflow: ${steps.join(' → ')}`
+      const steps = chain.map((s) => s.replace(/^cs_/, ""));
+      const description = `Workflow: ${steps.join(" → ")}`;
 
-      workflows.push({ name: name, description: description, steps: chain })
+      workflows.push({ name: name, description: description, steps: chain });
     }
   }
 
-  return workflows
+  return workflows;
 }

package/src/mcp/failure-context.ts

@@ -43,6 +43,4 @@ export interface FailureContext {
  * Discriminated union — 'retry' is distinct from calling the same tool.
  * Retry implies: arguments may change, timing may change, reason awareness.
  */
-export type RecoveryAction =
-  | { type: 'retry' }
-  | { type: 'tool'; tool: string };
+export type RecoveryAction = { type: "retry" } | { type: "tool"; tool: string };

package/src/mcp/index.ts

@@ -1,7 +1,7 @@
-import type { ResourceType } from './resources'
-export type { ResourceType } from './resources'
-export { buildCapabilityGraph } from './capability-graph'
-export type { FailureContext, RecoveryAction } from './failure-context'
+import type { ResourceType } from "./resources";
+export type { ResourceType } from "./resources";
+export { buildCapabilityGraph } from "./capability-graph";
+export type { FailureContext, RecoveryAction } from "./failure-context";
 
 /**
  * MCP Tool Discovery Types
@@ -27,11 +27,11 @@ export type { FailureContext, RecoveryAction } from './failure-context'
  * 'data' conflates discovery, ingestion, and coverage.
  */
 export type ToolCategory =
-  | 'system'
-  | 'data'
-  | 'connections'
-  | 'automation'
-  | 'developer'
+  | "system"
+  | "data"
+  | "connections"
+  | "automation"
+  | "developer";
 
 /**
  * Tool domain taxonomy.
@@ -48,19 +48,19 @@ export type ToolCategory =
  * - system: Health, status, runtime diagnostics
  */
 export type ToolDomain =
-  | 'organization'
-  | 'identity'
-  | 'integrations'
-  | 'ingestion'
-  | 'discovery'
-  | 'knowledge'
-  | 'system'
+  | "organization"
+  | "identity"
+  | "integrations"
+  | "ingestion"
+  | "discovery"
+  | "knowledge"
+  | "system";
 
 /**
  * Tool visibility levels.
  * Controls who can see the tool in discovery.
  */
-export type ToolVisibility = 'user' | 'admin'
+export type ToolVisibility = "user" | "admin";
 
 /**
  * How the tool can be invoked.
@@ -68,7 +68,7 @@ export type ToolVisibility = 'user' | 'admin'
  * - assistant: AI can invoke proactively
  * - hybrid: Both manual and assistant invocation
  */
-export type ToolInvocationMode = 'manual' | 'assistant' | 'hybrid'
+export type ToolInvocationMode = "manual" | "assistant" | "hybrid";
 
 /**
  * Tool effect classification.
@@ -79,7 +79,7 @@ export type ToolInvocationMode = 'manual' | 'assistant' | 'hybrid'
  * 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'
+export type ToolEffectClass = "pure" | "effectful";
 
 /**
  * Tool intent classification.
@@ -96,7 +96,7 @@ export type ToolEffectClass = 'pure' | 'effectful'
  * INVARIANT: intent 'mutate' + risk 'high' → requiresConfirmation must be true.
  * Enforced in backend tool registration, typed here for documentation.
  */
-export type ToolIntent = 'read' | 'mutate' | 'analysis'
+export type ToolIntent = "read" | "mutate" | "analysis";
 
 /**
  * Tool lifecycle stability classification.
@@ -105,7 +105,7 @@ export type ToolIntent = 'read' | 'mutate' | 'analysis'
  * - stable: Production-ready with backward compatibility guarantees
  * - deprecated: Scheduled for removal, consumers should migrate
  */
-export type ToolStability = 'experimental' | 'stable' | 'deprecated'
+export type ToolStability = "experimental" | "stable" | "deprecated";
 
 /**
  * Tool computational complexity classification.
@@ -115,7 +115,7 @@ export type ToolStability = 'experimental' | 'stable' | 'deprecated'
  * - moderate: 100ms-5s, may involve external API calls
  * - heavy: 5s+, batch processing, large data transfers, long-running ops
  */
-export type ToolComplexity = 'trivial' | 'moderate' | 'heavy'
+export type ToolComplexity = "trivial" | "moderate" | "heavy";
 
 /**
  * Integration provider tag for tools.
@@ -124,7 +124,7 @@ export type ToolComplexity = 'trivial' | 'moderate' | 'heavy'
  * Extensible via (string & {}) — new integrations do not require
  * a contracts release, but known values get autocomplete.
  */
-export type ToolIntegration = 'slack' | 'google' | 'zoom' | (string & {})
+export type ToolIntegration = "slack" | "google" | "zoom" | (string & {});
 
 /**
  * Complete tool descriptor for discovery and invocation.
@@ -135,15 +135,15 @@ export type ToolIntegration = 'slack' | 'google' | 'zoom' | (string & {})
 // @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
+  id: string;
   /** Human-readable name for display */
-  name: string
+  name: string;
   /** User-facing description (what it does, not how) */
-  description: string
+  description: string;
   /** Grouping category for UI organization */
-  category: ToolCategory
+  category: ToolCategory;
   /** Whether user confirmation is required before execution */
-  requiresConfirmation: boolean
+  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).
@@ -154,21 +154,21 @@ export interface MCPToolDescriptor {
    * The bridge enforces: effectful tools must return previewResponse()
    * with ExecutionIntent, never direct side effects.
    */
-  effectClass: ToolEffectClass
+  effectClass: ToolEffectClass;
   /** How the tool can be triggered */
-  invocationMode: ToolInvocationMode
+  invocationMode: ToolInvocationMode;
   /** Who can see this tool */
-  visibility: ToolVisibility
+  visibility: ToolVisibility;
 
   // --- New fields (PRD-00265) ---
 
   /** Domain taxonomy classification. Replaces category for routing and grouping. */
-  domain: ToolDomain
+  domain: ToolDomain;
   /**
    * Integration providers this tool interacts with.
    * Empty or omitted for tools that don't touch external integrations.
    */
-  integrations?: ToolIntegration[]
+  integrations?: ToolIntegration[];
   /**
    * User-impact risk classification.
    * - none: Read-only, no side effects
@@ -178,37 +178,50 @@ export interface MCPToolDescriptor {
    *
    * INVARIANT: intent 'mutate' + risk 'high' → requiresConfirmation must be true.
    */
-  risk: 'none' | 'low' | 'moderate' | 'high'
+  risk: "none" | "low" | "moderate" | "high";
   /** What the tool does to the system (read, mutate, analysis). */
-  intent: ToolIntent
+  intent: ToolIntent;
   /** Lifecycle stability classification. */
-  stability: ToolStability
+  stability: ToolStability;
   /** Computational complexity and latency profile. */
-  complexity: ToolComplexity
+  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
+  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[]
+  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[]
+  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[]
+  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 };
 }
 
 /**
@@ -219,13 +232,13 @@ export interface MCPToolDescriptor {
  */
 export interface CapabilityGraphEdge {
   /** Tool ID that produces the resource */
-  from: string
+  from: string;
   /** Tool ID that consumes the resource */
-  to: string
+  to: string;
   /** Resource type flowing between tools */
-  resource: ResourceType
+  resource: ResourceType;
   /** Resource domain (extracted from resource namespace prefix, e.g., 'slack' from 'slack.channel') */
-  domain?: string
+  domain?: string;
 }
 
 /**
@@ -236,11 +249,11 @@ export interface CapabilityGraphEdge {
  */
 export interface ToolWorkflow {
   /** Workflow name (e.g., "Slack Onboarding") */
-  name: string
+  name: string;
   /** Human-readable description of the workflow */
-  description: string
+  description: string;
   /** Ordered list of tool IDs in this workflow */
-  steps: string[]
+  steps: string[];
 }
 
 /**
@@ -251,9 +264,9 @@ export interface ToolWorkflow {
  */
 export interface CapabilityGraph {
   /** Resource flow edges between tools */
-  edges: CapabilityGraphEdge[]
+  edges: CapabilityGraphEdge[];
   /** Named workflows derived from graph paths */
-  workflows: ToolWorkflow[]
+  workflows: ToolWorkflow[];
 }
 
 /**
@@ -265,14 +278,14 @@ export interface CapabilityGraph {
  */
 export interface ToolDiscoveryResponse {
   /** Tools available to the current user */
-  tools: MCPToolDescriptor[]
+  tools: MCPToolDescriptor[];
   /**
    * Capability graph derived from tool resource flow metadata.
    * Optional — discovery responses may or may not include the computed graph.
    *
    * @see capability-graph.ts for buildCapabilityGraph() implementation
    */
-  graph?: CapabilityGraph
+  graph?: CapabilityGraph;
 }
 
 /**
@@ -282,8 +295,8 @@ export interface ToolDiscoveryResponse {
  * Rendered atomically, not streamed char-by-char.
  */
 export interface ToolListMessagePart {
-  type: 'tool-list'
-  tools: MCPToolDescriptor[]
+  type: "tool-list";
+  tools: MCPToolDescriptor[];
 }
 
 /**
@@ -296,6 +309,6 @@ export interface ToolListMessagePart {
  * Frontend normalizes this to `tool-list` for semantic handling.
  */
 export interface ToolListDataPart {
-  type: 'data-tool-list'
-  data: { tools: MCPToolDescriptor[] }
+  type: "data-tool-list";
+  data: { tools: MCPToolDescriptor[] };
 }

package/src/mcp/resources.ts

@@ -10,12 +10,12 @@
  * Unlike ToolIntegration, resource types are not extensible via (string & {}).
  */
 export type ResourceType =
-  | 'integration.connection'
-  | 'slack.channel'
-  | 'slack.channel_scope'
-  | 'slack.coverage'
-  | 'ingestion.job'
-  | 'knowledge.fingerprint'
-  | 'org.status'
-  | 'system.status'
-  | 'system.runtime'
+  | "integration.connection"
+  | "slack.channel"
+  | "slack.channel_scope"
+  | "slack.coverage"
+  | "ingestion.job"
+  | "knowledge.fingerprint"
+  | "org.status"
+  | "system.status"
+  | "system.runtime";

package/src/meetings/index.ts

@@ -16,7 +16,7 @@ export {
   RecordingEventSchema,
   TranscriptionSessionGrantSchema,
   MeetingMetadataProjectionSchema,
-} from './schemas';
+} from "./schemas";
 
 export type {
   RecordingId,
@@ -31,4 +31,4 @@ export type {
   RecordingEvent,
   TranscriptionSessionGrant,
   MeetingMetadataProjection,
-} from './schemas';
+} from "./schemas";