@swoft/platform-contracts/src/shared/SemanticNavigation.ts

DDD-compliant dependency injection contracts for Swoft platform - Defines clean architecture boundaries

/**
 * Semantic Navigation Registry Interfaces
 *
 * Defines semantic navigation patterns that leverage domain knowledge to provide
 * intelligent, context-aware navigation hints across MCP servers.
 *
 * Design Principles:
 * - Domain-agnostic: Works for any domain (GTD, Party, DevOps, DDD, etc.)
 * - Extensible: Domains can add their specific semantic patterns
 * - Type-safe: Leverages TypeScript for compile-time validation
 * - Minimal: Simple to implement and understand
 */

import { NavigationHints, DomainContext, McpServerId } from './NavigationHints';

// ============================================
// CORE SEMANTIC TYPES
// ============================================

/**
 * Semantic relationship types between entities/concepts
 * Standardized across all domains
 */
export type SemanticRelationType =
  | 'contains' // A contains B (project contains actions)
  | 'belongs_to' // A belongs to B (action belongs to project)
  | 'relates_to' // A relates to B (person relates to organization)
  | 'depends_on' // A depends on B (frontend depends on backend)
  | 'triggers' // A triggers B (event triggers workflow)
  | 'completes' // A completes B (action completes project)
  | 'blocks' // A blocks B (issue blocks deployment)
  | 'enables' // A enables B (authentication enables access)
  | 'implements' // A implements B (service implements aggregate)
  | 'extends'; // A extends B (subdomain extends domain)

/**
 * Context sensitivity levels for semantic hints
 * Determines how context-aware the suggestions should be
 */
export type ContextSensitivity = 'low' | 'medium' | 'high' | 'adaptive';

// ============================================
// ENTITY RELATIONSHIP DEFINITIONS
// ============================================

/**
 * Defines relationships between entities in entity-based domains
 * Used by domains like Party Management, DDD Modeling
 */
export interface IEntityRelationship {
  /** Source entity type (e.g., 'person', 'organization', 'aggregate') */
  sourceEntityType: string;

  /** Target entity type that relates to the source */
  targetEntityType: string;

  /** Type of semantic relationship */
  relationshipType: SemanticRelationType;

  /** Human-readable description of the relationship */
  description: string;

  /** Navigation actions available for this relationship */
  availableActions: {
    /** Action name (e.g., 'view_members', 'assign_role') */
    action: string;

    /** Tool that implements this action */
    toolName: string;

    /** When this action would be relevant */
    relevanceContext?: string;
  }[];

  /** Cardinality of the relationship (optional) */
  cardinality?: 'one-to-one' | 'one-to-many' | 'many-to-many';
}

// ============================================
// WORKFLOW DEFINITIONS
// ============================================

/**
 * Defines workflow-based navigation for process-oriented domains
 * Used by domains like GTD, DevOps Operations, Development Workflows
 */
export interface IWorkflowDefinition {
  /** Workflow identifier (e.g., 'gtd_capture_clarify', 'incident_response') */
  workflowId: string;

  /** Human-readable workflow name */
  name: string;

  /** Workflow steps in order */
  steps: {
    /** Step identifier */
    stepId: string;

    /** Step description */
    description: string;

    /** Tools that can execute this step */
    tools: string[];

    /** Conditions to proceed to next step (optional) */
    completionCriteria?: string[];

    /** Next possible steps */
    nextSteps?: string[];
  }[];

  /** Workflow triggers - what initiates this workflow */
  triggers: {
    /** Event or condition that starts the workflow */
    trigger: string;

    /** Context in which this trigger applies */
    context?: Record<string, unknown>;
  }[];

  /** Expected outcomes when workflow completes */
  outcomes: string[];
}

// ============================================
// DOMAIN SEMANTICS
// ============================================

/**
 * What each domain provides for semantic navigation
 * This is what domains register in the semantic registry
 */
export interface IDomainSemantics {
  /** Domain identifier from the canonical list */
  domainId: DomainContext;

  /** MCP server that implements this domain */
  mcpServerId: McpServerId;

  /** Entity relationships this domain understands */
  entityRelationships?: IEntityRelationship[];

  /** Workflows this domain implements */
  workflows?: IWorkflowDefinition[];

  /** Domain-specific semantic patterns */
  customSemantics?: {
    /** Pattern identifier */
    patternId: string;

    /** Pattern description */
    description: string;

    /** Context where this pattern applies */
    applicableContext: Record<string, unknown>;

    /** Navigation hints this pattern provides */
    navigationHints: Partial<NavigationHints>;
  }[];

  /** Confidence level in these semantic definitions (0-1) */
  confidence?: number;

  /** Last updated timestamp */
  lastUpdated?: string;
}

// ============================================
// SEMANTIC NAVIGATION REGISTRY
// ============================================

/**
 * Main registry interface for domain semantics
 * Central registry that aggregates semantic knowledge from all domains
 */
export interface ISemanticNavigationRegistry {
  /**
   * Register domain semantics
   * Domains call this to register their semantic patterns
   */
  registerDomainSemantics(semantics: IDomainSemantics): Promise<void>;

  /**
   * Get semantics for a specific domain
   */
  getDomainSemantics(domainId: DomainContext): Promise<IDomainSemantics | null>;

  /**
   * Get all registered domain semantics
   */
  getAllDomainSemantics(): Promise<IDomainSemantics[]>;

  /**
   * Find related entities across domains
   * Returns semantic relationships that span multiple domains
   */
  findCrossDomainRelationships(
    entityType: string,
    entityId: string
  ): Promise<
    {
      domain: DomainContext;
      relationships: IEntityRelationship[];
    }[]
  >;

  /**
   * Get applicable workflows for current context
   * Returns workflows that could be relevant given the current state
   */
  getApplicableWorkflows(context: Record<string, unknown>): Promise<
    {
      domain: DomainContext;
      workflows: IWorkflowDefinition[];
      relevanceScore: number;
    }[]
  >;

  /**
   * Generate semantic navigation hints
   * Core method that produces enhanced navigation hints using domain semantics
   */
  generateSemanticHints(
    currentContext: Record<string, unknown>,
    sensitivity?: ContextSensitivity
  ): Promise<SemanticNavigationHints>;
}

// ============================================
// ENHANCED NAVIGATION HINTS
// ============================================

/**
 * Enhanced NavigationHints with semantic information
 * Extends the base NavigationHints with domain-aware semantic intelligence
 */
export interface SemanticNavigationHints extends NavigationHints {
  /** Semantic relationships relevant to current context */
  semantic_relationships: {
    /** Relationship definition */
    relationship: IEntityRelationship;

    /** Domain that provides this relationship */
    sourceDomain: DomainContext;

    /** Current relevance score (0-1) */
    relevanceScore: number;

    /** Suggested navigation actions */
    suggestedActions: string[];
  }[];

  /** Applicable workflows for current context */
  applicable_workflows: {
    /** Workflow definition */
    workflow: IWorkflowDefinition;

    /** Domain that provides this workflow */
    sourceDomain: DomainContext;

    /** Current step in workflow (if already in progress) */
    currentStep?: string;

    /** Suggested next actions */
    suggestedNextActions: string[];

    /** Confidence this workflow applies (0-1) */
    applicabilityScore: number;
  }[];

  /** Cross-domain insights */
  cross_domain_insights: {
    /** Insight description */
    insight: string;

    /** Domains involved in this insight */
    involvedDomains: DomainContext[];

    /** Suggested actions to leverage this insight */
    actionableSteps: string[];

    /** Confidence level (0-1) */
    confidence: number;
  }[];

  /** Semantic metadata */
  semantic_metadata: {
    /** Context sensitivity level used */
    contextSensitivity: ContextSensitivity;

    /** Domains consulted for these hints */
    consultedDomains: DomainContext[];

    /** Processing time for semantic analysis */
    processingTimeMs?: number;

    /** Version of semantic registry used */
    registryVersion?: string;
  };
}

// ============================================
// UTILITY TYPES
// ============================================

/**
 * Registry configuration options
 */
export interface SemanticRegistryOptions {
  /** How often to refresh domain semantics */
  refreshIntervalMs?: number;

  /** Default context sensitivity */
  defaultSensitivity?: ContextSensitivity;

  /** Maximum number of relationships to include in hints */
  maxRelationships?: number;

  /** Maximum number of workflows to suggest */
  maxWorkflows?: number;

  /** Enable cross-domain insights */
  enableCrossDomainInsights?: boolean;
}

/**
 * Semantic hint generation options
 */
export interface SemanticHintOptions {
  /** Context sensitivity level */
  sensitivity?: ContextSensitivity;

  /** Specific domains to consult (default: all) */
  consultDomains?: DomainContext[];

  /** Include cross-domain insights */
  includeCrossDomainInsights?: boolean;

  /** Maximum processing time before fallback */
  maxProcessingTimeMs?: number;
}

/**
 * Factory function for creating semantic navigation hints
 */
export type SemanticNavigationHintsFactory = (
  context: Record<string, unknown>,
  options?: SemanticHintOptions
) => Promise<SemanticNavigationHints>;