@beyondwork/docx-react-component 1.0.1 → 1.0.3

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

@@ -0,0 +1,764 @@
+/**
+ * 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;
+}