@ai-pip/core 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,109 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.4.0] - (unreleased)
+
+### ✨ Added
+
+- **AAL – Remediation plan (what to clean, not how)**
+  - `buildRemediationPlan(islResult, policy)`: builds a **RemediationPlan** describing *what* to clean (target segment IDs, goals, constraints). The SDK or an AI tool performs the actual cleanup.
+  - **RemediationPlan**: `strategy: 'AI_CLEANUP'`, `goals: string[]` (e.g. `remove_prompt_injection`, `remove_role_hijacking`), `constraints: string[]` (e.g. `preserve_user_intent`, `do_not_add_information`, `do_not_change_language`), `targetSegments: string[]` (segment IDs with detections), `needsRemediation: boolean`.
+  - Policy: **`remediation: { enabled: boolean }`** (replaces `removal`).
+
+- **Shared – Audit with remediation plan**
+  - **RemediationPlanLike** (shared type) for audit payloads; same shape as RemediationPlan.
+  - `formatPipelineAuditFull(..., remediationPlan?, cpe?, options?)` and `buildFullAuditPayload` / `formatPipelineAuditAsJson` accept **`remediationPlan`** in options (replacing removal plan).
+  - `formatAALForAudit(reason, remediationPlan?)` documents the remediation plan in the AAL section.
+
+- **CPE – Transversal (documented and clarified)**
+  - CPE (Cryptographic Prompt Envelope) is **transversal**: it **ensures the integrity of each layer** for greater security. It is not a sequential processing layer but a shared capability that wraps pipeline output (e.g. ISL or AAL result) with a cryptographic envelope (nonce, metadata, HMAC-SHA256), so that the result of each layer can be verified and tampering detected. Implementation lives in **`shared/envelope`**; the package exports it as **`@ai-pip/core/cpe`** for backward compatibility. Use `envelope(islResult, secretKey)` to wrap any pipeline result.
+
+### 🗑️ Removed
+
+- **AAL – Removal plan and application (moved to SDK)**
+  - **Removed**: `buildRemovalPlan`, `buildRemovalPlanFromResult`, `applyRemovalPlan`, **RemovalPlan**, **RemovedInstruction**.
+  - The core no longer performs instruction removal; it only produces a remediation plan. The SDK (or an AI cleanup tool) uses the plan to clean the content.
+
+### 🔄 Changed
+
+- **AgentPolicy**: `removal: { enabled }` → **`remediation: { enabled }`**.
+- **Audit**: All formatters and payloads use **remediationPlan** / **RemediationPlanLike** instead of removal plan / RemovalPlanLike.
+
+### 📚 Documentation
+
+- **README.md**: Examples and use cases updated to remediation (buildRemediationPlan, RemediationPlan, policy.remediation); audit section uses remediationPlan; SDK responsibility clarified (remediation execution, e.g. AI cleanup). New subsection *CPE as transversal* in Architecture: CPE ensures the **integrity of each layer** for greater security (shared/envelope, export `@ai-pip/core/cpe`); pipeline clarified (CSL → ISL → optional AAL; CPE wraps result for verification).
+- **FEATURE.md**: 0.4.0 section with new APIs, removed APIs, and CPE transversal; tables updated for remediation.
+
+### 📎 More information
+
+See **[FEATURE.md](./FEATURE.md)** for API details.
+
+---
+
+## [0.3.0] - (unreleased)
+
+### ✨ Added
+
+- **ISL – Threat detection**
+  - `detectThreats(content, options?)`: pure, deterministic function returning `readonly PiDetection[]`.
+  - Default patterns for known attack surfaces (prompt-injection, jailbreak, role hijacking, script_like, hidden_text); expanded set (~287 patterns).
+  - Integration in `sanitize`: each segment may carry `piDetection` (`PiDetectionResult`).
+  - Option `SanitizeOptions.detectThreatsOptions` for custom patterns or limits (`patterns`, `maxTotal`, `maxPerPattern`).
+  - `getDefaultThreatPatterns()`: returns the default set (cached, frozen).
+  - `THREAT_TYPES` and type `ThreatType` for deterministic taxonomy.
+
+- **ISL – Risk score strategies**
+  - Enum `RiskScoreStrategy`: `MAX_CONFIDENCE`, `SEVERITY_PLUS_VOLUME`, `WEIGHTED_BY_TYPE`.
+  - Pure calculators: `maxConfidenceCalculator`, `severityPlusVolumeCalculator`, `weightedByTypeCalculator`, `defaultWeightedByTypeCalculator`.
+  - `getCalculator(strategy, typeWeights?)`: returns the registered calculator for the strategy.
+  - Strategy fixed at `emitSignal`; reflected in `ISLSignal.metadata.strategy` for audit.
+
+- **emitSignal – Risk score options**
+  - `EmitSignalOptions`: `timestamp?`, `riskScore?: { strategy, typeWeights? }`.
+  - Default: `RiskScoreStrategy.MAX_CONFIDENCE`.
+  - Backward compatibility: `emitSignal(islResult, timestamp)` still supported.
+
+- **ISLSignal – Strategy metadata**
+  - `ISLSignal.metadata?: { strategy: RiskScoreStrategy }` for traceability.
+  - `createISLSignal(..., metadata?)` accepts optional fourth argument `metadata`.
+
+- **AAL – Actionable removal plan**
+  - `buildRemovalPlanFromResult(islResult, policy)`: builds `RemovalPlan` from `ISLResult` with `segmentId` per instruction.
+  - `applyRemovalPlan(islResult, plan)`: pure function that removes malicious ranges from each segment's `sanitizedContent`; clamps ranges to content; merges overlapping and adjacent ranges (gap only punctuation/whitespace); returns new `ISLResult`.
+  - `RemovedInstruction.segmentId?`: optional, present when the plan is built from `ISLResult`.
+  - Guards in `resolveAgentAction`, `resolveAgentActionWithScore`, `buildDecisionReason`, `buildRemovalPlan`, and `buildRemovalPlanFromResult` for safe handling of detections and signals.
+
+- **AAL – Resolve action with score**
+  - `resolveAgentActionWithScore(islSignal, policy)`: returns `{ action, anomalyScore }` for SDK/audit use.
+
+- **AAL – Colors for UI/audit**
+  - `ACTION_DISPLAY_COLORS` and `getActionDisplayColor(action)` for ALLOW/WARN/BLOCK.
+
+- **Shared – Audit improvements (run id, JSON, logs, full pipeline)**
+  - **Run identifier**: `createAuditRunId()` generates a unique run id; full-pipeline formatters accept `options.runId` and `options.generatedAt` for correlation across reports and logs.
+  - **Full pipeline audit**: `formatPipelineAuditFull(csl, isl, signal, aalReason, removalPlan?, cpe?, options?)` builds a single report (CSL → ISL → Signal → AAL → optional CPE) with run id and generated-at timestamp; lineage preserved in each section.
+  - **formatPipelineAudit** extended: `options.includeSignalAndAAL`, `options.signal`, `options.aalReason`, `options.removalPlan` to include ISL Signal and AAL sections in the pipeline report.
+  - **JSON variant**: `buildFullAuditPayload(csl, isl, signal, reason, options?)` returns a JSON-serializable object (runId, generatedAt, summary, sections with lineage). `formatPipelineAuditAsJson(...)` returns the JSON string; `options.compact: true` for one-line output (logs, SIEM).
+  - **Audit for logs**: `buildAuditLogEntry(signal, reason, options?)` returns a compact summary (runId, generatedAtIso, action, riskScore, hasThreats, detectionCount) for one-line logging.
+  - Types: `AuditRunInfo`, `AuditLogSummary`, `FullPipelineAuditOptions`, `PipelineAuditJsonOptions`.
+
+### 🔄 Changed
+
+- **sanitize (ISL)**: optional second argument `SanitizeOptions`; uses `detectThreats` per segment and assigns `piDetection` when detections exist; option `detectThreatsOptions` for patterns or limits.
+- **emitSignal (ISL)**: second argument may be `EmitSignalOptions` (object) or `number` (timestamp); computes risk score with configured strategy; includes `metadata.strategy` on the signal.
+- **RemovedInstruction (AAL)**: `type` is now `string` (any `pattern_type`); added `segmentId?: string`.
+
+### 📚 Documentation
+
+- **FEATURE.md**: per-version detail of new and modified features; table of methods/APIs changed in 0.3.0 with description of each change.
+- **README.md**: audit section updated with run id, full pipeline (formatPipelineAuditFull), JSON variant (buildFullAuditPayload, formatPipelineAuditAsJson), and audit for logs (buildAuditLogEntry); examples for full report and compact log entry.
+
+### 📎 More information
+
+For specific method signatures and API changes in 0.3.0, see **[FEATURE.md](./FEATURE.md)**.
+
+---
+
 ## [0.2.0] - 2026-01-26
 
 ### ♻️ Architectural Refactor - ISL / AAL Separation
@@ -161,7 +264,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 **Problem**: When importing types from `@ai-pip/core` in SDK projects, TypeScript could not resolve nested type properties:
 - `this.data.trust.value` appeared as `any` instead of `TrustLevelType`
-- No autocompletado for nested properties
+- No autocomplete for nested properties
 - Type inference failed for complex types
 
 **Root Cause**: Incompatibility between `moduleResolution: "bundler"` (used in `@ai-pip-core`) and `moduleResolution: "nodenext"` (used in SDK projects). TypeScript couldn't follow the chain of type imports correctly.
@@ -173,7 +276,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 **Impact**: 
 - ✅ Nested types now resolve correctly
-- ✅ Autocompletado works for all type properties
+- ✅ Autocomplete works for all type properties
 - ✅ Type inference works correctly in consuming projects
 - ✅ Better compatibility with Node.js ESM module resolution
 
@@ -350,6 +453,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-**Current Version**: 0.1.8  
+**Current Version**: 0.4.0  
 **Status**: Phase 1 - Core Layers (100% completed)