@company-semantics/contracts 0.85.0 → 0.86.0

package/package.json

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

package/src/index.ts

@@ -224,8 +224,6 @@ export type {
   OrgAuthPolicy,
   UpdateAuthPolicyRequest,
   Phase3AuditAction,
-  // Workspace capability types (Phase 3)
-  WorkspaceCapability,
   // Domain and multi-org types (Phase 4)
   // @see ADR-CONT-032 for design rationale
   DomainStatus,
@@ -260,7 +258,7 @@ export type {
   StrategyDoc,
 } from './org/index'
 
-export { ROLE_DISPLAY_MAP, WORKSPACE_CAPABILITIES, ROLE_CAPABILITY_MAP, VIEW_SCOPE_MAP, getViewScope, TRANSFER_RESPONSIBILITIES, IDENTITY_TRUST_LEVEL_LABELS } from './org/index'
+export { ROLE_DISPLAY_MAP, VIEW_SCOPE_MAP, getViewScope, TRANSFER_RESPONSIBILITIES, IDENTITY_TRUST_LEVEL_LABELS } from './org/index'
 
 // View authorization types (Phase 5 - ADR-APP-013)
 export type { AuthorizableView } from './org/index'
@@ -276,6 +274,18 @@ export type {
   ToolDiscoveryResponse,
   ToolListMessagePart,
   ToolListDataPart,
+  // Tool domain taxonomy (PRD-00265)
+  ToolDomain,
+  ToolIntegration,
+  ToolIntent,
+  ToolStability,
+  ToolComplexity,
+  // Resource flow types (PRD-00265)
+  ResourceType,
+  // Capability graph stubs (PRD-00265, implementation in PRD-00268)
+  CapabilityGraph,
+  CapabilityGraphEdge,
+  ToolWorkflow,
 } from './mcp/index'
 
 // Message part types and builder functions

package/src/mcp/index.ts

@@ -1,3 +1,6 @@
+import type { ResourceType } from './resources'
+export type { ResourceType } from './resources'
+
 /**
  * MCP Tool Discovery Types
  *
@@ -18,15 +21,38 @@
  */
 
 /**
- * Tool categories for grouping in UI.
- * Maps to user mental model, not implementation.
+ * @deprecated Use ToolDomain instead. ToolCategory is too coarse —
+ * 'data' conflates discovery, ingestion, and coverage.
  */
 export type ToolCategory =
-  | 'system' // System status, health checks
-  | 'data' // Data access, ingestion, queries
-  | 'connections' // OAuth, integrations
-  | 'automation' // Scheduled tasks, triggers
-  | 'developer' // Debug, internal tools
+  | '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.
@@ -53,6 +79,51 @@ export type ToolInvocationMode = 'manual' | 'assistant' | 'hybrid'
  */
 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.
  *
@@ -85,6 +156,101 @@ export interface MCPToolDescriptor {
   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[]
+}
+
+/**
+ * Edge in the capability graph connecting two tools via a resource.
+ * A tool that produces a resource connects to tools that consume it.
+ *
+ * @stub Implementation in PRD-00268 (buildCapabilityGraph)
+ */
+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").
+ *
+ * @stub Implementation in PRD-00268 (buildCapabilityGraph)
+ */
+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.
+ *
+ * @stub Type definition only. buildCapabilityGraph() ships in PRD-00268.
+ */
+export interface CapabilityGraph {
+  /** Resource flow edges between tools */
+  edges: CapabilityGraphEdge[]
+  /** Named workflows derived from graph paths */
+  workflows: ToolWorkflow[]
 }
 
 /**
@@ -97,6 +263,13 @@ export interface MCPToolDescriptor {
 export interface ToolDiscoveryResponse {
   /** Tools available to the current user */
   tools: MCPToolDescriptor[]
+  /**
+   * Capability graph derived from tool resource flow metadata.
+   * Optional — discovery responses may or may not include the computed graph.
+   *
+   * @stub Graph computation ships in PRD-00268 (buildCapabilityGraph).
+   */
+  graph?: CapabilityGraph
 }
 
 /**

package/src/mcp/resources.ts

@@ -0,0 +1,21 @@
+/**
+ * Resource type vocabulary for MCP tool resource flow.
+ *
+ * Uses dot-separated namespacing consistent with trust/scopes.ts conventions.
+ * Each value represents a typed resource that tools produce or consume,
+ * enabling capability graph derivation from resource flow metadata.
+ *
+ * This is a CLOSED union — new resource types represent architectural
+ * additions that require a contracts release and downstream consumer updates.
+ * 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'

package/src/org/index.ts

@@ -68,10 +68,6 @@ export type {
 
 export { ROLE_DISPLAY_MAP, TRANSFER_RESPONSIBILITIES, IDENTITY_TRUST_LEVEL_LABELS } from './types';
 
-// Workspace capability types (Phase 3)
-export type { WorkspaceCapability } from './capabilities';
-export { WORKSPACE_CAPABILITIES, ROLE_CAPABILITY_MAP } from './capabilities';
-
 // Domain types (Phase 4)
 export type {
   DomainStatus,

package/src/org/capabilities.ts

@@ -1,84 +0,0 @@
-/**
- * Workspace Capability Types
- *
- * Capability constants for Phase 3 workspace expansion features.
- * These define the permission boundaries for workspace actions.
- *
- * INVARIANTS:
- * - Capabilities are checked server-side before any mutation
- * - UI uses capabilities to gate action visibility
- * - Capabilities map to RBAC roles (see RoleCapabilityMap)
- *
- * @see ADR-CONT-031 for design rationale
- */
-
-// =============================================================================
-// Workspace Capability Type
-// =============================================================================
-
-/**
- * Capabilities for workspace actions.
- * Used for capability-based access control in Phase 3 features.
- *
- * Capability hierarchy (implicit):
- * - owner: all capabilities
- * - admin: invite_member, manage_members (limited), manage_auth, demote_integration (own only)
- * - member: none (read-only)
- */
-export type WorkspaceCapability =
-  // Member management
-  | 'org.invite_member'
-  | 'org.manage_members'
-  // Integration management
-  | 'org.promote_integration'
-  | 'org.demote_integration'
-  // Auth policy
-  | 'org.manage_auth'
-  // Domain claiming (future)
-  | 'org.claim_domain';
-
-/**
- * All workspace capabilities.
- * Use for iteration and validation.
- */
-export const WORKSPACE_CAPABILITIES: readonly WorkspaceCapability[] = [
-  'org.invite_member',
-  'org.manage_members',
-  'org.promote_integration',
-  'org.demote_integration',
-  'org.manage_auth',
-  'org.claim_domain',
-] as const;
-
-// =============================================================================
-// Role → Capability Mapping
-// =============================================================================
-
-/**
- * Capabilities granted to each workspace role.
- *
- * INVARIANTS:
- * - Owner has all capabilities (cannot be restricted)
- * - Admin cannot demote other admins (enforce in service layer)
- * - Member has no mutation capabilities
- *
- * @see Phase 3 Invariant #4: Admin floor
- * @see Phase 3 Invariant #5: Admin ≠ owner
- */
-export const ROLE_CAPABILITY_MAP = {
-  owner: [
-    'org.invite_member',
-    'org.manage_members',
-    'org.promote_integration',
-    'org.demote_integration',
-    'org.manage_auth',
-    'org.claim_domain',
-  ],
-  admin: [
-    'org.invite_member',
-    'org.manage_members', // Note: cannot remove/demote other admins
-    'org.manage_auth',
-    'org.demote_integration', // Can demote own integrations only
-  ],
-  member: [],
-} as const satisfies Record<string, readonly WorkspaceCapability[]>;