@beyondwork/docx-react-component 1.0.0 → 1.0.1

package/src/runtime/ai-action-policy.ts

@@ -1,764 +0,0 @@
-/**
- * AI Action Policy for Legal Document Editor
- * 
- * This module defines the AI capability matrix and policy boundaries for the
- * legal document review editor. It establishes clear boundaries between 
- * allowed AI actions, those requiring confirmation, blocked actions, and 
- * unsupported operations.
- */
-
-/**
- * Categories of AI actions in the legal document context
- */
-export type AIActionCategory = 
-  | 'text-editing'
-  | 'content-generation'
-  | 'review-assistance'
-  | 'document-analysis'
-  | 'formatting-assistance'
-  | 'validation-assistance'
-  | 'workflow-automation'
-  | 'data-extraction'
-  | 'external-integration'
-  | 'system-modification';
-
-/**
- * Specific AI actions within each category
- */
-export type AIAction =
-  // Text editing actions
-  | 'edit_selection'
-  | 'rewrite_paragraph'
-  | 'fix_grammar'
-  | 'improve_clarity'
-  | 'adjust_tone'
-  
-  // Content generation actions  
-  | 'generate_text'
-  | 'expand_outline'
-  | 'create_summary'
-  | 'generate_boilerplate'
-  | 'draft_response'
-  
-  // Review assistance actions
-  | 'suggest_comment_response'
-  | 'analyze_changes'
-  | 'resolve_comment_thread'
-  | 'identify_issues'
-  | 'check_consistency'
-  
-  // Document analysis actions
-  | 'summarize_document'
-  | 'extract_key_points'
-  | 'identify_risks'
-  | 'find_defined_terms'
-  | 'analyze_structure'
-  
-  // Formatting assistance actions
-  | 'fix_formatting'
-  | 'standardize_styles'
-  | 'apply_template'
-  | 'number_headings'
-  | 'create_toc'
-  
-  // Validation assistance actions
-  | 'check_compliance'
-  | 'validate_citations'
-  | 'verify_cross_references'
-  | 'check_word_compatibility'
-  | 'run_spell_check'
-  
-  // Workflow automation actions
-  | 'auto_accept_changes'
-  | 'batch_resolve_comments'
-  | 'apply_bulk_formatting'
-  | 'merge_documents'
-  | 'split_document'
-  
-  // Data extraction actions
-  | 'extract_metadata'
-  | 'list_defined_terms'
-  | 'export_comments'
-  | 'generate_report'
-  | 'create_redline_summary'
-  
-  // External integration actions
-  | 'lookup_external_data'
-  | 'verify_external_references'
-  | 'sync_with_external_system'
-  | 'fetch_template'
-  | 'send_for_approval'
-  
-  // System modification actions  
-  | 'modify_permissions'
-  | 'change_document_settings'
-  | 'alter_preservation_rules'
-  | 'bypass_compatibility_checks'
-  | 'override_security_policies';
-
-/**
- * AI action support levels
- */
-export type AIActionSupport = 
-  | 'allowed'              // Action can proceed without confirmation
-  | 'confirmation-required' // Action requires explicit user confirmation
-  | 'blocked'              // Action is blocked by policy
-  | 'unsupported';         // Action is not implemented
-
-/**
- * Risk levels for AI actions
- */
-export type AIActionRisk = 
-  | 'low'       // No significant risk to document integrity or workflow
-  | 'medium'    // Some risk, requires careful handling
-  | 'high'      // High risk of data loss or workflow disruption
-  | 'critical'; // Critical risk, could compromise document or security
-
-/**
- * Policy for a specific AI action
- */
-export interface AIActionPolicy {
-  action: AIAction;
-  category: AIActionCategory;
-  support: AIActionSupport;
-  risk: AIActionRisk;
-  rationale: string;
-  
-  requirements: {
-    userConfirmation: boolean;
-    preserveOriginal: boolean;
-    validateOutput: boolean;
-    auditLog: boolean;
-  };
-  
-  constraints: {
-    maxScope: 'selection' | 'paragraph' | 'section' | 'document';
-    preservedContentRespect: boolean;
-    compatibilityValidation: boolean;
-    undoSupport: boolean;
-  };
-  
-  fallbackBehavior: 'fail-safe' | 'user-prompt' | 'degrade-gracefully' | 'block-entirely';
-}
-
-/**
- * Complete AI action policy matrix
- */
-export const AI_ACTION_POLICIES: AIActionPolicy[] = [
-  // Text editing actions - generally allowed with appropriate safeguards
-  {
-    action: 'edit_selection',
-    category: 'text-editing',
-    support: 'confirmation-required',
-    risk: 'medium',
-    rationale: 'Text edits need user review to ensure they maintain legal accuracy and intent.',
-    requirements: {
-      userConfirmation: true,
-      preserveOriginal: true,
-      validateOutput: true,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'selection',
-      preservedContentRespect: true,
-      compatibilityValidation: true,
-      undoSupport: true
-    },
-    fallbackBehavior: 'user-prompt'
-  },
-  
-  {
-    action: 'rewrite_paragraph',
-    category: 'text-editing',
-    support: 'confirmation-required',
-    risk: 'medium',
-    rationale: 'Paragraph rewrites can significantly change meaning and require legal review.',
-    requirements: {
-      userConfirmation: true,
-      preserveOriginal: true,
-      validateOutput: true,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'paragraph',
-      preservedContentRespect: true,
-      compatibilityValidation: true,
-      undoSupport: true
-    },
-    fallbackBehavior: 'user-prompt'
-  },
-  
-  {
-    action: 'fix_grammar',
-    category: 'text-editing',
-    support: 'allowed',
-    risk: 'low',
-    rationale: 'Grammar fixes are low-risk mechanical corrections that improve document quality.',
-    requirements: {
-      userConfirmation: false,
-      preserveOriginal: false,
-      validateOutput: true,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'selection',
-      preservedContentRespect: true,
-      compatibilityValidation: true,
-      undoSupport: true
-    },
-    fallbackBehavior: 'fail-safe'
-  },
-  
-  // Content generation actions - require confirmation
-  {
-    action: 'generate_text',
-    category: 'content-generation',
-    support: 'confirmation-required',
-    risk: 'high',
-    rationale: 'Generated text must be reviewed for legal accuracy and appropriateness.',
-    requirements: {
-      userConfirmation: true,
-      preserveOriginal: true,
-      validateOutput: true,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'selection',
-      preservedContentRespect: true,
-      compatibilityValidation: true,
-      undoSupport: true
-    },
-    fallbackBehavior: 'user-prompt'
-  },
-  
-  {
-    action: 'create_summary',
-    category: 'content-generation',
-    support: 'allowed',
-    risk: 'low',
-    rationale: 'Summaries are analytical outputs that do not modify the source document.',
-    requirements: {
-      userConfirmation: false,
-      preserveOriginal: true,
-      validateOutput: false,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'document',
-      preservedContentRespect: true,
-      compatibilityValidation: false,
-      undoSupport: false
-    },
-    fallbackBehavior: 'fail-safe'
-  },
-  
-  // Review assistance actions - generally allowed
-  {
-    action: 'suggest_comment_response',
-    category: 'review-assistance',
-    support: 'allowed',
-    risk: 'low',
-    rationale: 'Comment response suggestions help workflow efficiency without modifying content.',
-    requirements: {
-      userConfirmation: false,
-      preserveOriginal: true,
-      validateOutput: false,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'selection',
-      preservedContentRespect: true,
-      compatibilityValidation: false,
-      undoSupport: false
-    },
-    fallbackBehavior: 'fail-safe'
-  },
-  
-  {
-    action: 'analyze_changes',
-    category: 'review-assistance',
-    support: 'allowed',
-    risk: 'low',
-    rationale: 'Change analysis provides insights without modifying document content.',
-    requirements: {
-      userConfirmation: false,
-      preserveOriginal: true,
-      validateOutput: false,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'document',
-      preservedContentRespect: true,
-      compatibilityValidation: false,
-      undoSupport: false
-    },
-    fallbackBehavior: 'fail-safe'
-  },
-  
-  // Document analysis actions - allowed as read-only operations
-  {
-    action: 'summarize_document',
-    category: 'document-analysis',
-    support: 'allowed',
-    risk: 'low',
-    rationale: 'Document summarization is a read-only analysis operation.',
-    requirements: {
-      userConfirmation: false,
-      preserveOriginal: true,
-      validateOutput: false,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'document',
-      preservedContentRespect: true,
-      compatibilityValidation: false,
-      undoSupport: false
-    },
-    fallbackBehavior: 'fail-safe'
-  },
-  
-  {
-    action: 'identify_risks',
-    category: 'document-analysis', 
-    support: 'allowed',
-    risk: 'low',
-    rationale: 'Risk identification helps legal review without modifying content.',
-    requirements: {
-      userConfirmation: false,
-      preserveOriginal: true,
-      validateOutput: false,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'document',
-      preservedContentRespect: true,
-      compatibilityValidation: false,
-      undoSupport: false
-    },
-    fallbackBehavior: 'fail-safe'
-  },
-  
-  // Formatting assistance - confirmation required for changes
-  {
-    action: 'fix_formatting',
-    category: 'formatting-assistance',
-    support: 'confirmation-required',
-    risk: 'medium',
-    rationale: 'Formatting changes can affect document presentation and legal meaning.',
-    requirements: {
-      userConfirmation: true,
-      preserveOriginal: true,
-      validateOutput: true,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'document',
-      preservedContentRespect: true,
-      compatibilityValidation: true,
-      undoSupport: true
-    },
-    fallbackBehavior: 'user-prompt'
-  },
-  
-  // Validation assistance - allowed as analysis
-  {
-    action: 'check_compliance',
-    category: 'validation-assistance',
-    support: 'allowed',
-    risk: 'low',
-    rationale: 'Compliance checking provides analytical insights without modification.',
-    requirements: {
-      userConfirmation: false,
-      preserveOriginal: true,
-      validateOutput: false,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'document',
-      preservedContentRespect: true,
-      compatibilityValidation: false,
-      undoSupport: false
-    },
-    fallbackBehavior: 'fail-safe'
-  },
-  
-  {
-    action: 'check_word_compatibility',
-    category: 'validation-assistance',
-    support: 'allowed',
-    risk: 'low',
-    rationale: 'Compatibility checking aligns with the editor\'s Word-safe design goals.',
-    requirements: {
-      userConfirmation: false,
-      preserveOriginal: true,
-      validateOutput: false,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'document',
-      preservedContentRespect: true,
-      compatibilityValidation: false,
-      undoSupport: false
-    },
-    fallbackBehavior: 'fail-safe'
-  },
-  
-  // Workflow automation - blocked or requires confirmation
-  {
-    action: 'auto_accept_changes',
-    category: 'workflow-automation',
-    support: 'blocked',
-    risk: 'critical',
-    rationale: 'Automatic change acceptance bypasses necessary legal review processes.',
-    requirements: {
-      userConfirmation: false,
-      preserveOriginal: false,
-      validateOutput: false,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'document',
-      preservedContentRespect: false,
-      compatibilityValidation: false,
-      undoSupport: false
-    },
-    fallbackBehavior: 'block-entirely'
-  },
-  
-  {
-    action: 'batch_resolve_comments',
-    category: 'workflow-automation',
-    support: 'confirmation-required',
-    risk: 'high',
-    rationale: 'Batch comment resolution needs review to ensure all issues are properly addressed.',
-    requirements: {
-      userConfirmation: true,
-      preserveOriginal: true,
-      validateOutput: true,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'document',
-      preservedContentRespect: true,
-      compatibilityValidation: true,
-      undoSupport: true
-    },
-    fallbackBehavior: 'user-prompt'
-  },
-  
-  // External integration - blocked for security
-  {
-    action: 'lookup_external_data',
-    category: 'external-integration',
-    support: 'blocked',
-    risk: 'critical',
-    rationale: 'External data access poses security and privacy risks in legal workflows.',
-    requirements: {
-      userConfirmation: false,
-      preserveOriginal: false,
-      validateOutput: false,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'document',
-      preservedContentRespect: false,
-      compatibilityValidation: false,
-      undoSupport: false
-    },
-    fallbackBehavior: 'block-entirely'
-  },
-  
-  {
-    action: 'sync_with_external_system',
-    category: 'external-integration',
-    support: 'blocked',
-    risk: 'critical',
-    rationale: 'External system integration creates security vulnerabilities and data integrity risks.',
-    requirements: {
-      userConfirmation: false,
-      preserveOriginal: false,
-      validateOutput: false,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'document',
-      preservedContentRespect: false,
-      compatibilityValidation: false,
-      undoSupport: false
-    },
-    fallbackBehavior: 'block-entirely'
-  },
-  
-  // System modification - all blocked
-  {
-    action: 'modify_permissions',
-    category: 'system-modification',
-    support: 'blocked',
-    risk: 'critical',
-    rationale: 'Permission modifications compromise security and access control.',
-    requirements: {
-      userConfirmation: false,
-      preserveOriginal: false,
-      validateOutput: false,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'document',
-      preservedContentRespect: false,
-      compatibilityValidation: false,
-      undoSupport: false
-    },
-    fallbackBehavior: 'block-entirely'
-  },
-  
-  {
-    action: 'bypass_compatibility_checks',
-    category: 'system-modification',
-    support: 'blocked',
-    risk: 'critical',
-    rationale: 'Compatibility checks are essential for Word-safe round-trip behavior.',
-    requirements: {
-      userConfirmation: false,
-      preserveOriginal: false,
-      validateOutput: false,
-      auditLog: true
-    },
-    constraints: {
-      maxScope: 'document',
-      preservedContentRespect: false,
-      compatibilityValidation: false,
-      undoSupport: false
-    },
-    fallbackBehavior: 'block-entirely'
-  }
-];
-
-/**
- * Get policy for a specific AI action
- */
-export function getAIActionPolicy(action: AIAction): AIActionPolicy {
-  const policy = AI_ACTION_POLICIES.find(p => p.action === action);
-  if (!policy) {
-    // Default policy for unknown actions
-    return {
-      action,
-      category: 'system-modification',
-      support: 'unsupported',
-      risk: 'critical',
-      rationale: 'Unknown action - blocked by default for security.',
-      requirements: {
-        userConfirmation: false,
-        preserveOriginal: false,
-        validateOutput: false,
-        auditLog: true
-      },
-      constraints: {
-        maxScope: 'selection',
-        preservedContentRespect: true,
-        compatibilityValidation: true,
-        undoSupport: false
-      },
-      fallbackBehavior: 'block-entirely'
-    };
-  }
-  return policy;
-}
-
-/**
- * Check if an AI action is allowed to proceed
- */
-export function isAIActionAllowed(action: AIAction): boolean {
-  const policy = getAIActionPolicy(action);
-  return policy.support === 'allowed' || policy.support === 'confirmation-required';
-}
-
-/**
- * Check if an AI action requires user confirmation
- */
-export function requiresConfirmation(action: AIAction): boolean {
-  const policy = getAIActionPolicy(action);
-  return policy.support === 'confirmation-required' || policy.requirements.userConfirmation;
-}
-
-/**
- * Get actions by support level
- */
-export function getActionsBySupport(support: AIActionSupport): AIAction[] {
-  return AI_ACTION_POLICIES
-    .filter(policy => policy.support === support)
-    .map(policy => policy.action);
-}
-
-/**
- * Get actions by risk level
- */
-export function getActionsByRisk(risk: AIActionRisk): AIAction[] {
-  return AI_ACTION_POLICIES
-    .filter(policy => policy.risk === risk)
-    .map(policy => policy.action);
-}
-
-/**
- * Generate AI capability summary
- */
-export interface AICapabilitySummary {
-  totalActions: number;
-  allowedActions: number;
-  confirmationRequiredActions: number;
-  blockedActions: number;
-  unsupportedActions: number;
-  
-  lowRiskActions: number;
-  mediumRiskActions: number;
-  highRiskActions: number;
-  criticalRiskActions: number;
-  
-  categoryCounts: Record<AIActionCategory, number>;
-}
-
-/**
- * Generate summary of AI capabilities and restrictions
- */
-export function generateAICapabilitySummary(): AICapabilitySummary {
-  const policies = AI_ACTION_POLICIES;
-  
-  const categoryCounts: Record<AIActionCategory, number> = {
-    'text-editing': 0,
-    'content-generation': 0,
-    'review-assistance': 0,
-    'document-analysis': 0,
-    'formatting-assistance': 0,
-    'validation-assistance': 0,
-    'workflow-automation': 0,
-    'data-extraction': 0,
-    'external-integration': 0,
-    'system-modification': 0
-  };
-  
-  policies.forEach(policy => {
-    categoryCounts[policy.category]++;
-  });
-  
-  return {
-    totalActions: policies.length,
-    allowedActions: policies.filter(p => p.support === 'allowed').length,
-    confirmationRequiredActions: policies.filter(p => p.support === 'confirmation-required').length,
-    blockedActions: policies.filter(p => p.support === 'blocked').length,
-    unsupportedActions: policies.filter(p => p.support === 'unsupported').length,
-    
-    lowRiskActions: policies.filter(p => p.risk === 'low').length,
-    mediumRiskActions: policies.filter(p => p.risk === 'medium').length,
-    highRiskActions: policies.filter(p => p.risk === 'high').length,
-    criticalRiskActions: policies.filter(p => p.risk === 'critical').length,
-    
-    categoryCounts
-  };
-}
-
-/**
- * Context required for AI action execution
- */
-export interface AIActionContext {
-  documentId: string;
-  userId: string;
-  selection?: {
-    from: number;
-    to: number;
-    text: string;
-  };
-  preservedContent: {
-    hasPreservedElements: boolean;
-    preservedTypes: string[];
-  };
-  compatibility: {
-    hasWarnings: boolean;
-    blockingIssues: string[];
-  };
-  permissions: {
-    canEdit: boolean;
-    canExport: boolean;
-    isReadOnly: boolean;
-  };
-}
-
-/**
- * Validate AI action against context and policy
- */
-export interface AIActionValidationResult {
-  allowed: boolean;
-  requiresConfirmation: boolean;
-  blockingReasons: string[];
-  warnings: string[];
-  contextConstraints: {
-    maxScope: 'selection' | 'paragraph' | 'section' | 'document';
-    mustPreserveContent: boolean;
-    requiresCompatibilityValidation: boolean;
-  };
-}
-
-/**
- * Validate an AI action against the current context
- */
-export function validateAIAction(
-  action: AIAction,
-  context: AIActionContext
-): AIActionValidationResult {
-  const policy = getAIActionPolicy(action);
-  const result: AIActionValidationResult = {
-    allowed: true,
-    requiresConfirmation: policy.requirements.userConfirmation,
-    blockingReasons: [],
-    warnings: [],
-    contextConstraints: {
-      maxScope: policy.constraints.maxScope,
-      mustPreserveContent: policy.constraints.preservedContentRespect,
-      requiresCompatibilityValidation: policy.constraints.compatibilityValidation
-    }
-  };
-  
-  // Check if action is blocked by policy
-  if (policy.support === 'blocked' || policy.support === 'unsupported') {
-    result.allowed = false;
-    result.blockingReasons.push(policy.rationale);
-    return result;
-  }
-  
-  // Check read-only permissions
-  if (context.permissions.isReadOnly && 
-      (policy.category === 'text-editing' || 
-       policy.category === 'content-generation' ||
-       policy.category === 'formatting-assistance')) {
-    result.allowed = false;
-    result.blockingReasons.push('Document is in read-only mode');
-  }
-  
-  // Check edit permissions for content-modifying actions
-  if (!context.permissions.canEdit &&
-      (policy.category === 'text-editing' ||
-       policy.category === 'content-generation' ||
-       policy.category === 'workflow-automation')) {
-    result.allowed = false;
-    result.blockingReasons.push('User does not have edit permissions');
-  }
-  
-  // Check compatibility constraints
-  if (policy.constraints.compatibilityValidation && 
-      context.compatibility.blockingIssues.length > 0) {
-    result.allowed = false;
-    result.blockingReasons.push('Document has blocking compatibility issues');
-  }
-  
-  // Check preserved content constraints
-  if (policy.constraints.preservedContentRespect && 
-      context.preservedContent.hasPreservedElements) {
-    result.warnings.push('Document contains preserved content that cannot be modified');
-  }
-  
-  // Validate scope constraints
-  if (policy.constraints.maxScope === 'selection' && !context.selection) {
-    result.allowed = false;
-    result.blockingReasons.push('Action requires text selection');
-  }
-  
-  return result;
-}