@ai-pip/csl 0.1.0

package/layers/csl/domain/exceptions/index.ts

@@ -0,0 +1,2 @@
+export * from './ClassificationError';
+export * from './SegmentationError';

package/layers/csl/domain/index.ts

@@ -0,0 +1,4 @@
+export * from './entities'
+export * from './services'
+export * from './value-objects'
+export * from './exceptions'

package/layers/csl/domain/services/AnomalyService.ts

@@ -0,0 +1,255 @@
+import type { Segment } from '../entities'
+import { AnomalyScore } from '../value-objects'
+import type { AnomalyAction, RiskScore } from '../../types'
+import { TrustLevelType } from '../../types'
+
+/**
+ * Configuration for AnomalyService
+ * 
+ * @property highRiskThreshold - Score threshold for BLOCK action (default: 0.7)
+ * @property mediumRiskThreshold - Score threshold for WARN action (default: 0.3)
+ * @property trustLevelWeight - Weight multiplier for trust level in score calculation (default: 0.3)
+ * @property piDetectionWeight - Weight multiplier for PI detection in score calculation (default: 0.5)
+ * @property contentLengthWeight - Weight multiplier for content length anomaly (default: 0.1)
+ * @property originWeight - Weight multiplier for origin risk in score calculation (default: 0.1)
+ */
+export interface AnomalyServiceConfig {
+  readonly highRiskThreshold?: RiskScore
+  readonly mediumRiskThreshold?: RiskScore
+  readonly trustLevelWeight?: number
+  readonly piDetectionWeight?: number
+  readonly contentLengthWeight?: number
+  readonly originWeight?: number
+}
+
+/**
+ * AnomalyService calculates anomaly scores for content segments based on multiple risk factors.
+ * 
+ * @remarks
+ * This service performs complex risk analysis by combining multiple factors:
+ * - Trust level of the segment
+ * - Prompt injection detection results
+ * - Content length anomalies
+ * - Origin risk assessment
+ * 
+ * **Key Features:**
+ * - Configurable thresholds and weights
+ * - Multi-factor risk analysis
+ * - Deterministic scoring algorithm
+ * - Returns AnomalyScore with recommended action
+ * 
+ * **Scoring Algorithm:**
+ * The final score is a weighted combination of:
+ * 1. Trust Level Risk (0-1): Lower trust = higher risk
+ * 2. PI Detection Risk (0-1): Based on detection score
+ * 3. Content Length Anomaly (0-1): Very short or very long content
+ * 4. Origin Risk (0-1): Based on origin type
+ * 
+ * Final score = (trustLevelRisk * trustLevelWeight) +
+ *               (piDetectionRisk * piDetectionWeight) +
+ *               (contentLengthRisk * contentLengthWeight) +
+ *               (originRisk * originWeight)
+ * 
+ * @example
+ * ```typescript
+ * // Default configuration
+ * const anomalyService = new AnomalyService()
+ * 
+ * // Custom configuration
+ * const customService = new AnomalyService({
+ *   highRiskThreshold: 0.8,
+ *   mediumRiskThreshold: 0.4,
+ *   piDetectionWeight: 0.7
+ * })
+ * 
+ * // Calculate anomaly score
+ * const anomalyScore = anomalyService.calculateScore(segment)
+ * 
+ * if (anomalyScore.isHighRisk()) {
+ *   console.log('High risk detected!')
+ * }
+ * ```
+ */
+export class AnomalyService {
+  private readonly config: Required<AnomalyServiceConfig>
+
+  constructor(config?: AnomalyServiceConfig) {
+    this.config = {
+      highRiskThreshold: config?.highRiskThreshold ?? 0.7,
+      mediumRiskThreshold: config?.mediumRiskThreshold ?? 0.3,
+      trustLevelWeight: config?.trustLevelWeight ?? 0.3,
+      piDetectionWeight: config?.piDetectionWeight ?? 0.5,
+      contentLengthWeight: config?.contentLengthWeight ?? 0.1,
+      originWeight: config?.originWeight ?? 0.1,
+    }
+
+    // Validate thresholds
+    if (this.config.highRiskThreshold < this.config.mediumRiskThreshold) {
+      throw new Error(
+        `AnomalyService: highRiskThreshold (${this.config.highRiskThreshold}) ` +
+        `must be >= mediumRiskThreshold (${this.config.mediumRiskThreshold})`
+      )
+    }
+
+    // Validate weights sum to approximately 1.0 (allow small floating point differences)
+    const totalWeight = this.config.trustLevelWeight +
+                       this.config.piDetectionWeight +
+                       this.config.contentLengthWeight +
+                       this.config.originWeight
+
+    if (Math.abs(totalWeight - 1) > 0.01) {
+      throw new Error(
+        `AnomalyService: weights must sum to 1.0, got ${totalWeight}`
+      )
+    }
+  }
+
+  /**
+   * Calculates the anomaly score for a segment based on multiple risk factors
+   * 
+   * @param segment - The segment to analyze
+   * @returns AnomalyScore with calculated score and recommended action
+   * 
+   * @throws {TypeError} If segment is not a Segment instance
+   * 
+   * @example
+   * ```typescript
+   * const anomalyScore = anomalyService.calculateScore(segment)
+   * console.log(`Anomaly score: ${anomalyScore.score}, Action: ${anomalyScore.action}`)
+   * ```
+   */
+  calculateScore(segment: Segment): AnomalyScore {
+    if (!segment || typeof segment !== 'object' || !('id' in segment)) {
+      throw new TypeError('AnomalyService.calculateScore: segment must be a Segment instance')
+    }
+
+    // Calculate individual risk components
+    const trustLevelRisk = this.calculateTrustLevelRisk(segment)
+    const piDetectionRisk = this.calculatePiDetectionRisk(segment)
+    const contentLengthRisk = this.calculateContentLengthRisk(segment)
+    const originRisk = this.calculateOriginRisk(segment)
+
+    // Weighted combination
+    const finalScore = Math.min(1,
+      (trustLevelRisk * this.config.trustLevelWeight) +
+      (piDetectionRisk * this.config.piDetectionWeight) +
+      (contentLengthRisk * this.config.contentLengthWeight) +
+      (originRisk * this.config.originWeight)
+    )
+
+    // Determine action based on thresholds
+    const action = this.determineAction(finalScore)
+
+    return new AnomalyScore(finalScore, action)
+  }
+
+  /**
+   * Calculates risk based on trust level
+   * TC = 0.0 (no risk), STC = 0.5 (medium risk), UC = 1.0 (high risk)
+   */
+  private calculateTrustLevelRisk(segment: Segment): RiskScore {
+    const trustLevel = segment.trustLevel
+    if (!trustLevel) {
+      return 1 as RiskScore // Unknown trust level = maximum risk
+    }
+
+    switch (trustLevel.value) {
+      case TrustLevelType.TC:
+        return 0 as RiskScore
+      case TrustLevelType.STC:
+        return 0.5 as RiskScore
+      case TrustLevelType.UC:
+        return 1 as RiskScore
+      default:
+        return 1 as RiskScore
+    }
+  }
+
+  /**
+   * Calculates risk based on prompt injection detection results
+   */
+  private calculatePiDetectionRisk(segment: Segment): RiskScore {
+    const piDetection = segment.piDetection
+    if (!piDetection) {
+      return 0 as RiskScore // No detection = no risk from this factor
+    }
+
+    // Use the detection score directly
+    return piDetection.score
+  }
+
+  /**
+   * Calculates risk based on content length anomalies
+   * Very short (< 10 chars) or very long (> 10000 chars) content is suspicious
+   */
+  private calculateContentLengthRisk(segment: Segment): RiskScore {
+    const contentLength = segment.content.length
+
+    // Very short content (potential injection fragments)
+    if (contentLength < 10) {
+      return 0.8 as RiskScore
+    }
+
+    // Very long content (potential obfuscation)
+    if (contentLength > 10000) {
+      return 0.6 as RiskScore
+    }
+
+    // Normal length range
+    if (contentLength >= 10 && contentLength <= 1000) {
+      return 0 as RiskScore
+    }
+
+    // Medium length (1000-10000) - slight risk
+    return 0.2 as RiskScore
+  }
+
+  /**
+   * Calculates risk based on origin type
+   */
+  private calculateOriginRisk(segment: Segment): RiskScore {
+    const origin = segment.origin
+
+    // User input is always high risk
+    if (origin.isUser()) {
+      return 1 as RiskScore
+    }
+
+    // External content (network, injected) is high risk
+    if (origin.isExternal()) {
+      return 0.9 as RiskScore
+    }
+
+    // System content is low risk
+    if (origin.isSystem()) {
+      return 0 as RiskScore
+    }
+
+    // DOM content risk depends on visibility
+    if (origin.isDom()) {
+      // Hidden DOM content is more risky
+      return origin.type === 'DOM_HIDDEN' ? 0.7 as RiskScore : 0.3 as RiskScore
+    }
+
+    // Unknown origin is high risk
+    if (origin.isUnknown()) {
+      return 1 as RiskScore
+    }
+
+    // Default: medium risk
+    return 0.5 as RiskScore
+  }
+
+  /**
+   * Determines the action based on the calculated score
+   */
+  private determineAction(score: RiskScore): AnomalyAction {
+    if (score >= this.config.highRiskThreshold) {
+      return 'BLOCK'
+    } else if (score >= this.config.mediumRiskThreshold) {
+      return 'WARN'
+    } else {
+      return 'ALLOW'
+    }
+  }
+}

package/layers/csl/domain/services/LineageService.ts

@@ -0,0 +1,224 @@
+import { LineageEntry } from '../value-objects'
+
+/**
+ * LineageService manages the lineage (audit trail) of content segments.
+ * 
+ * @remarks
+ * This service maintains a stateful map of segment IDs to their lineage entries,
+ * allowing complete traceability of how each segment was processed through the pipeline.
+ * 
+ * **Key Features:**
+ * - Maintains internal state (Map) for lineage tracking
+ * - Supports multiple entries per segment (chronological order)
+ * - Provides query methods for lineage retrieval
+ * - Thread-safe operations (immutable entries)
+ * 
+ * **Usage:**
+ * LineageService is instantiated once and reused across the processing pipeline.
+ * Each processing step should add an entry to track what happened to the segment.
+ * 
+ * @example
+ * ```typescript
+ * const lineageService = new LineageService()
+ * 
+ * // Add entries during processing
+ * lineageService.addEntry('seg-123', new LineageEntry('normalization', Date.now(), 'Unicode normalized'))
+ * lineageService.addEntry('seg-123', new LineageEntry('classification', Date.now(), 'Classified as TC'))
+ * 
+ * // Retrieve lineage
+ * const lineage = lineageService.getLineage('seg-123')
+ * console.log(`Segment has ${lineage.length} processing steps`)
+ * 
+ * // Clear lineage when done
+ * lineageService.clearLineage('seg-123')
+ * ```
+ */
+export class LineageService {
+  private readonly lineageMap: Map<string, LineageEntry[]>
+
+  constructor() {
+    this.lineageMap = new Map()
+  }
+
+  /**
+   * Adds a lineage entry for a specific segment
+   * 
+   * @param segmentId - The unique identifier of the segment
+   * @param entry - The lineage entry to add
+   * 
+   * @throws {TypeError} If segmentId is not a valid string
+   * @throws {TypeError} If entry is not a LineageEntry instance
+   * 
+   * @example
+   * ```typescript
+   * lineageService.addEntry('seg-123', new LineageEntry('normalization', Date.now(), 'Applied'))
+   * ```
+   */
+  addEntry(segmentId: string, entry: LineageEntry): void {
+    if (!segmentId || typeof segmentId !== 'string' || segmentId.trim().length === 0) {
+      throw new TypeError('LineageService.addEntry: segmentId must be a non-empty string')
+    }
+
+    if (!(entry instanceof LineageEntry)) {
+      throw new TypeError('LineageService.addEntry: entry must be a LineageEntry instance')
+    }
+
+    const currentLineage = this.lineageMap.get(segmentId) ?? []
+    this.lineageMap.set(segmentId, [...currentLineage, entry])
+  }
+
+  /**
+   * Retrieves all lineage entries for a specific segment
+   * 
+   * @param segmentId - The unique identifier of the segment
+   * @returns Array of LineageEntry instances in chronological order (empty array if no entries)
+   * 
+   * @throws {TypeError} If segmentId is not a valid string
+   * 
+   * @example
+   * ```typescript
+   * const lineage = lineageService.getLineage('seg-123')
+   * lineage.forEach(entry => {
+   *   console.log(`${entry.step} at ${new Date(entry.timestamp).toISOString()}`)
+   * })
+   * ```
+   */
+  getLineage(segmentId: string): readonly LineageEntry[] {
+    if (!segmentId || typeof segmentId !== 'string' || segmentId.trim().length === 0) {
+      throw new TypeError('LineageService.getLineage: segmentId must be a non-empty string')
+    }
+
+    const lineage = this.lineageMap.get(segmentId)
+    return lineage ? Object.freeze([...lineage]) : Object.freeze([])
+  }
+
+  /**
+   * Checks if a segment has any lineage entries
+   * 
+   * @param segmentId - The unique identifier of the segment
+   * @returns true if the segment has lineage entries, false otherwise
+   * 
+   * @throws {TypeError} If segmentId is not a valid string
+   * 
+   * @example
+   * ```typescript
+   * if (lineageService.hasLineage('seg-123')) {
+   *   const entries = lineageService.getLineage('seg-123')
+   * }
+   * ```
+   */
+  hasLineage(segmentId: string): boolean {
+    if (!segmentId || typeof segmentId !== 'string' || segmentId.trim().length === 0) {
+      throw new TypeError('LineageService.hasLineage: segmentId must be a non-empty string')
+    }
+
+    const lineage = this.lineageMap.get(segmentId)
+    return lineage !== undefined && lineage.length > 0
+  }
+
+  /**
+   * Clears all lineage entries for a specific segment
+   * 
+   * @param segmentId - The unique identifier of the segment
+   * @returns true if lineage was cleared, false if segment had no lineage
+   * 
+   * @throws {TypeError} If segmentId is not a valid string
+   * 
+   * @example
+   * ```typescript
+   * const hadLineage = lineageService.clearLineage('seg-123')
+   * if (hadLineage) {
+   *   console.log('Lineage cleared')
+   * }
+   * ```
+   */
+  clearLineage(segmentId: string): boolean {
+    if (!segmentId || typeof segmentId !== 'string' || segmentId.trim().length === 0) {
+      throw new TypeError('LineageService.clearLineage: segmentId must be a non-empty string')
+    }
+
+    const hadLineage = this.lineageMap.has(segmentId)
+    this.lineageMap.delete(segmentId)
+    return hadLineage
+  }
+
+  /**
+   * Retrieves all segment IDs that have lineage entries
+   * 
+   * @returns Array of segment IDs that have lineage entries
+   * 
+   * @example
+   * ```typescript
+   * const segmentIds = lineageService.getAllSegmentIds()
+   * console.log(`Tracking ${segmentIds.length} segments`)
+   * ```
+   */
+  getAllSegmentIds(): readonly string[] {
+    return Object.freeze([...this.lineageMap.keys()])
+  }
+
+  /**
+   * Retrieves the total count of lineage entries across all segments
+   * 
+   * @returns Total number of lineage entries
+   * 
+   * @example
+   * ```typescript
+   * const totalEntries = lineageService.getTotalEntryCount()
+   * console.log(`Total lineage entries: ${totalEntries}`)
+   * ```
+   */
+  getTotalEntryCount(): number {
+    let total = 0
+    for (const lineage of this.lineageMap.values()) {
+      total += lineage.length
+    }
+    return total
+  }
+
+  /**
+   * Clears all lineage entries for all segments
+   * 
+   * @returns Number of segments that had lineage entries
+   * 
+   * @example
+   * ```typescript
+   * const clearedCount = lineageService.clearAllLineage()
+   * console.log(`Cleared lineage for ${clearedCount} segments`)
+   * ```
+   */
+  clearAllLineage(): number {
+    const count = this.lineageMap.size
+    this.lineageMap.clear()
+    return count
+  }
+
+  /**
+   * Gets lineage entries for a specific step type
+   * 
+   * @param segmentId - The unique identifier of the segment
+   * @param stepType - The step type to filter by (e.g., 'normalization', 'classification')
+   * @returns Array of LineageEntry instances matching the step type
+   * 
+   * @throws {TypeError} If segmentId or stepType are not valid strings
+   * 
+   * @example
+   * ```typescript
+   * const normalizationEntries = lineageService.getLineageByStep('seg-123', 'normalization')
+   * ```
+   */
+  getLineageByStep(segmentId: string, stepType: string): readonly LineageEntry[] {
+    if (!segmentId || typeof segmentId !== 'string' || segmentId.trim().length === 0) {
+      throw new TypeError('LineageService.getLineageByStep: segmentId must be a non-empty string')
+    }
+
+    if (!stepType || typeof stepType !== 'string' || stepType.trim().length === 0) {
+      throw new TypeError('LineageService.getLineageByStep: stepType must be a non-empty string')
+    }
+
+    const lineage = this.getLineage(segmentId)
+    return Object.freeze(
+      lineage.filter(entry => entry.step === stepType.trim())
+    )
+  }
+}