@ai-pip/core 0.1.8 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,116 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [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
+
+- Refactored ISL (Instruction Sanitization Layer) to be strictly pure and semantic
+- Removed all decision-making logic from ISL:
+  - No Blocking
+  - No allowing
+  - No warnings
+  - No instruction removal
+- ISL is now responsible for:
+  - Malicious pattern detection (prompt injection, jailbreak, role hijacking, ...)
+  - Risk scoring (RiskScore)
+  - Content sanitization
+  - Signal emission and lineage preservation
+
+- Introduced AAL (Agent Action Lock) as a distinct hybrid layer:
+  - Consume ISL signal (RiskScore, detection)
+  - Applies configurable policies (ALLOW / WARN / BLOCK)
+  - Decides whether to remove malicious instructions
+  - Ensures only sanitized content reaches the LLM
+  - Designed as a core-defined contract, implemented at the SDK level
+
+- **Shared audit utilities**: Pure functions for ordered, human-readable audit output (`formatCSLForAudit`, `formatISLForAudit`, `formatISLSignalForAudit`, `formatAALForAudit`, `formatCPEForAudit`, `formatPipelineAudit`) for compliance and debugging
+
+- **Package**: Version set to 0.2.0; AAL export path corrected (`./aal` → `./dist/AAL/`)
+
+### 📚 Documentation
+
+- README.md updated to clarify the new ISL / AAL responsibility split; architecture and layer sections in English
+- **Use cases** section added with scenarios (secure chat, policy moderation, audit, DOM/API/SYSTEM sources, lineage)
+- Examples for policy-based moderation (ISL + AAL) and audit report using shared formatters
+- Audit and pretty-print utilities documented (formatCSLForAudit, formatISLForAudit, formatISLSignalForAudit, formatAALForAudit, formatCPEForAudit, formatPipelineAudit)
+
+### 🧪 Testing
+
+- Added unit tests for CSL (segment, classify), ISL (signals, emitSignal, buildISLResult, RiskScore), AAL (resolveAgentAction, buildDecisionReason, buildRemovalPlan, buildAALLineage, AnomalyScore, PolicyRule), CPE (envelope), and shared (audit formatters)
+- Integration tests updated for ISL Signal → AAL flow; all test messages in English
+- Coverage target met: **92%+** statements for CSL, ISL, AAL, CPE, and shared layers
+
+### ⚠️ Breaking Semantic Change
+
+- Although public APIs remain mostly stable, ISL behavior has changed semantically
+- Consumers must no longer expect ISL to perform actions or remove instructions
+- Decision logic must be handled by AAL or the SDK
+
 ## [0.1.8] - 2026-01-04
 
 ### 🐛 Critical Fixes - Origin Classification
@@ -92,6 +202,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.1.7] - 2026-01-04
 
+### ⚠️ DEPRECATED
+
+**Deprecation reason**: This version has incorrect source classification that doesn't match the AI-PIP protocol specification. The trust level assignments for sources (UI, DOM, API, SYSTEM) are incorrect, which can lead to improper sanitization levels and security vulnerabilities.
+
+**Known issues**:
+- Incorrect source-to-trust-level mapping (UI classified as TC instead of STC, DOM as STC instead of UC, API as UC instead of STC)
+- Inconsistent behavior with AI-PIP protocol specification
+- Tests and documentation don't match actual implementation
+- Potential security risks due to incorrect sanitization levels
+
+**Recommendation**: Update to `0.1.8` or higher, which fixes all classification issues and aligns with the AI-PIP protocol specification.
+
 ### 🐛 Critical Fixes
 
 #### Type Resolution Fix
@@ -103,7 +225,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.
@@ -115,7 +237,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
 
@@ -145,6 +267,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.1.6] - 2025-12-28
 
+### ⚠️ DEPRECATED
+
+**Deprecation reason**: This version has incorrect source classification that doesn't match the AI-PIP protocol specification. The trust level assignments for sources are incorrect, which can lead to improper sanitization levels and security vulnerabilities.
+
+**Known issues**:
+- Incorrect source-to-trust-level mapping
+- Inconsistent behavior with AI-PIP protocol specification
+- Potential security risks due to incorrect sanitization levels
+
+**Recommendation**: Update to `0.1.8` or higher, which fixes all classification issues and aligns with the AI-PIP protocol specification.
+
 ### 📚 Documentation Improvements
 - **Centralized documentation**: Moved all protocol documentation to `ai-pip-docs` repository
 - **Updated README**: Added comprehensive links to centralized documentation
@@ -158,6 +291,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.1.5] - 2025-12-28
 
+### ⚠️ DEPRECATED
+
+**Deprecation reason**: This version has incorrect source classification that doesn't match the AI-PIP protocol specification. The trust level assignments for sources are incorrect, which can lead to improper sanitization levels and security vulnerabilities.
+
+**Known issues**:
+- Incorrect source-to-trust-level mapping
+- Inconsistent behavior with AI-PIP protocol specification
+- Potential security risks due to incorrect sanitization levels
+
+**Recommendation**: Update to `0.1.8` or higher, which fixes all classification issues and aligns with the AI-PIP protocol specification.
+
 ### 📚 Documentation Improvements
 - **Updated README**: Added links to whitepaper, roadmap, and complete layer documentation
 - **Updated Roadmap**: Added SDK-browser in Phase 4, updated Phase 1 status to 100% completed
@@ -176,6 +320,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.1.3] - 2025-12-28
 
+### ⚠️ DEPRECATED
+
+**Deprecation reason**: This version has incorrect source classification that doesn't match the AI-PIP protocol specification. The trust level assignments for sources are incorrect, which can lead to improper sanitization levels and security vulnerabilities.
+
+**Known issues**:
+- Incorrect source-to-trust-level mapping
+- Inconsistent behavior with AI-PIP protocol specification
+- Potential security risks due to incorrect sanitization levels
+
+**Recommendation**: Update to `0.1.8` or higher, which fixes all classification issues and aligns with the AI-PIP protocol specification.
+
 ### ✨ New Features
 - **JavaScript compilation**: The package now compiles to JavaScript (`dist/`) for better compatibility
 - **Type declaration files**: `.d.ts` files are generated for full TypeScript support

package/README.md

@@ -25,6 +25,9 @@ This package contains the **core** implementation of the protocol, which include
   - [Complete Example (Layer-Specific Imports)](#complete-example-layer-specific-imports)
   - [Example with additional functions](#example-with-additional-functions)
   - [Example: Multi-Layer Lineage and Audit Trail](#example-multi-layer-lineage-and-audit-trail)
+  - [Example: ISL Signal and AAL Integration](#example-isl-signal-aal)
+  - [Example: Audit and pretty-print utilities](#example-audit-utilities)
+  - [Use cases](#use-cases)
   - [Examples by Content Source](#examples-by-content-source)
     - [DOM Source (HTML Content)](#example-dom-source-html-content)
     - [UI Source (User Input)](#example-ui-source-user-input)
@@ -32,6 +35,7 @@ This package contains the **core** implementation of the protocol, which include
     - [API Source (External Data)](#example-api-source-external-data)
 - [Documentation](#documentation)
 - [Testing](#testing)
+  - [Coverage](#coverage)
 - [Development](#development)
 - [Requirements](#requirements)
 - [License](#license)
@@ -40,25 +44,77 @@ This package contains the **core** implementation of the protocol, which include
 - [Import Strategies](#import-strategies)
 - [Official SDK](#official-sdk)
 - [CHANGELOG](#changelog)
-
+- [FEATURES](#features)
 <a id="architecture"></a>
 ## 🏗️ Architecture
 
-The AI-PIP protocol is composed of the following layers:
+The AI-PIP protocol is composed of the following layers with clear separation of responsibilities:
 
 ### ✅ Implemented Layers
 
 - **CSL (Context Segmentation Layer)**: Segments and classifies content according to its origin
-- **ISL (Instruction Sanitization Layer)**: Sanitizes instructions according to trust level
+- **ISL (Instruction Sanitization Layer)**: Detects malicious patterns (`detectThreats`, ~287 default patterns), scores risk (configurable strategies), and sanitizes content. Each segment may carry `piDetection` (`PiDetectionResult`). Optional `SanitizeOptions.detectThreatsOptions` for custom patterns or limits. Emits signals (ISLSignal) for other layers to consume.
+- **AAL (Agent Action Lock)**: Hybrid layer that consumes ISL signals and applies configurable policies (ALLOW/WARN/BLOCK). Core-defined contract, SDK-implemented.
 - **CPE (Cryptographic Prompt Envelope)**: Generates cryptographic envelope with HMAC-SHA256 signature
 
 ### 🔧 Shared Features
 
 - **Shared**: Shared functions and global incremental lineage (not a layer, but features shared between layers)
 
+### 🏛️ Architectural Principles
+
+#### Layer Separation and Signals
+
+**Fundamental rule**: A layer must never consume another layer's internal "result". It consumes a signal.
+
+- **ISLResult**: Internal result of the ISL pipeline (segments, lineage, full metadata)
+  - Intended for: debugging, reporter, internal traceability
+- **ISLSignal**: Semantic contract between layers (risk scores, detections, security signals)
+  - Intended for: AAL, SDK, Engine
+  - Does not expose ISL internals
+
+**Processing flow:**
+```
+ISL.process() 
+  → ISLResult          (internal)
+  → ISLSignal          (external)
+      → AAL consumes ISLSignal (not ISLResult)
+```
+
+#### Layer Organization
+
+Each layer follows a consistent structure:
+
+```
+Layer/
+ ├─ exceptions/        → what is invalid
+ ├─ value-objects/     → what it is
+ ├─ process/           → how it transforms
+ ├─ lineage/           → what happened
+ ├─ types.ts
+ └─ index.ts
+```
+
+**Benefits:**
+- ✅ No layer overlap
+- ✅ Clear separation of responsibilities
+- ✅ Core scales better
+- ✅ Clear separation between internals and semantic contracts
+
 ### 📝 Note on AAL and Model Gateway
 
-**AAL (Agent Action Lock)** and **Model Gateway** are SDK components, not part of the semantic core. The semantic core focuses on pure functions and signals, while these layers require operational decisions and side effects that belong to the implementation (SDK).
+**AAL (Agent Action Lock)** is a hybrid layer defined in the semantic core but implemented at the SDK level. The core provides:
+- Value objects (AnomalyScore, AgentPolicy, PolicyRule)
+- Semantic contracts and types
+- Pure functions for decision logic
+
+The SDK implements:
+- Operational decision execution
+- Policy enforcement
+- Instruction removal
+- Side effects and state management
+
+**Model Gateway** is a pure SDK component for routing and managing AI model interactions.
 
 <a id="installation"></a>
 ## 📦 Installation
@@ -97,8 +153,12 @@ import { segment, classifySource, createTrustLevel } from '@ai-pip/core/csl'
 import type { CSLResult, CSLSegment, TrustLevel } from '@ai-pip/core/csl'
 
 // Import from ISL (Instruction Sanitization Layer)
-import { sanitize } from '@ai-pip/core/isl'
-import type { ISLResult, ISLSegment } from '@ai-pip/core/isl'
+import { sanitize, createISLSignal, detectThreats, getDefaultThreatPatterns } from '@ai-pip/core/isl'
+import type { ISLResult, ISLSegment, ISLSignal, DetectThreatsOptions } from '@ai-pip/core/isl'
+
+// Import from AAL (Agent Action Lock)
+import { createAnomalyScore, resolveAgentAction, resolveAgentActionWithScore, buildRemovalPlanFromResult, applyRemovalPlan } from '@ai-pip/core/aal'
+import type { AnomalyScore, AgentPolicy } from '@ai-pip/core/aal'
 
 // Import from CPE (Cryptographic Prompt Envelope)
 import { envelope, createNonce, createMetadata } from '@ai-pip/core/cpe'
@@ -139,7 +199,7 @@ This example demonstrates the complete AI-PIP processing pipeline:
 
 1. **CSL (Context Segmentation Layer)**: The `segment()` function takes user input and segments it into semantic chunks. Each segment is classified by its origin (`source: 'UI'`), which determines its trust level. The result contains multiple segments, each with its own trust classification and lineage tracking.
 
-2. **ISL (Instruction Sanitization Layer)**: The `sanitize()` function processes the segmented content and applies sanitization based on each segment's trust level. Trusted content (TC) receives minimal sanitization, semi-trusted (STC) gets moderate sanitization, and untrusted content (UC) receives aggressive sanitization to remove potential prompt injection attempts.
+2. **ISL (Instruction Sanitization Layer)**: The `sanitize()` function processes the segmented content and applies sanitization based on each segment's trust level. Trusted content (TC) receives minimal sanitization, semi-trusted (STC) gets moderate sanitization, and untrusted content (UC) receives aggressive sanitization to remove potential prompt injection attempts. ISL runs `detectThreats` per segment (default ~287 patterns; optional `SanitizeOptions.detectThreatsOptions` for custom patterns or limits) and attaches `piDetection` (`PiDetectionResult`) to segments with detections. It emits signals (ISLSignal) that can be consumed by AAL for policy-based decisions.
 
 3. **CPE (Cryptographic Prompt Envelope)**: The `envelope()` function creates a cryptographic wrapper around the sanitized content. It generates a unique nonce, timestamp, and HMAC-SHA256 signature to ensure the integrity and authenticity of the processed prompt. The resulting envelope can be safely sent to an AI model with cryptographic proof that the content hasn't been tampered with.
 
@@ -194,7 +254,7 @@ This example shows the same processing pipeline but using layer-specific imports
 
 2. **Content Segmentation**: The `segment()` function breaks down the input into semantic segments. Each segment inherits the trust classification from its source, allowing different parts of the content to be processed according to their trustworthiness.
 
-3. **Content Sanitization**: The `sanitize()` function applies security measures based on each segment's trust level. This step removes or neutralizes potential prompt injection attempts, especially in untrusted content segments.
+3. **Content Sanitization**: The `sanitize()` function applies security measures based on each segment's trust level and runs threat detection per segment (each segment may have `piDetection`). This step removes or neutralizes potential prompt injection attempts, especially in untrusted content segments.
 
 4. **Nonce Generation**: `createNonce()` generates a unique random value that prevents replay attacks. This nonce is included in the cryptographic envelope to ensure each processed prompt is unique.
 
@@ -529,6 +589,276 @@ const cpeResult = envelope(islResult, 'your-secret-key')
 - Enhanced pattern matching and anomaly detection
 - Production-ready implementations with comprehensive security features
 - and more...
+
+---
+
+<a id="example-isl-signal-aal"></a>
+### Example: ISL Signal and AAL Integration
+
+**How signals work:** ISL produces an internal result (`ISLResult`). You call `emitSignal(islResult)` to obtain an `ISLSignal` (risk score, detections, `hasThreats`). AAL consumes only this signal via `resolveAgentAction(islSignal, policy)` and never sees `ISLResult`. Minimal flow:
+
+```typescript
+const islResult = sanitize(cslResult)       // ISL internal result
+const islSignal = emitSignal(islResult)      // External signal for other layers
+const action = resolveAgentAction(islSignal, policy)  // AAL consumes signal → 'ALLOW' | 'WARN' | 'BLOCK'
+```
+
+Full example below demonstrates the signal-based communication between ISL and AAL layers, following the architectural principle that layers should consume signals, not internal results:
+
+```typescript
+import {
+  segment,
+  sanitize,
+  emitSignal,
+  resolveAgentAction,
+  buildDecisionReason,
+  buildRemovalPlan,
+  buildRemovalPlanFromResult,
+  applyRemovalPlan
+} from '@ai-pip/core'
+import type { ISLSignal, AgentPolicy } from '@ai-pip/core'
+
+// 1. Segment content (CSL)
+const cslResult = segment({
+  content: 'User input with potential injection',
+  source: 'UI',
+  metadata: {}
+})
+
+// 2. Sanitize content (ISL) - produces internal result; segments may have piDetection
+const islResult = sanitize(cslResult)
+
+// 3. Emit signal from ISL result - external contract
+const islSignal: ISLSignal = emitSignal(islResult)
+
+// 4. Define agent policy
+const policy: AgentPolicy = {
+  thresholds: {
+    warn: 0.3,
+    block: 0.7
+  },
+  removal: {
+    enabled: true
+  },
+  mode: 'balanced'
+}
+
+// 5. AAL consumes ISLSignal (not ISLResult) and resolves action
+const action = resolveAgentAction(islSignal, policy)
+console.log('Agent action:', action) // 'ALLOW', 'WARN', or 'BLOCK'
+
+// 6. Build decision reason for audit
+const reason = buildDecisionReason(action, islSignal, policy)
+console.log('Decision reason:', reason.reason)
+
+// 7. Build removal plan from signal (descriptive) or from result (actionable)
+const removalPlan = buildRemovalPlan(islSignal, policy)
+if (removalPlan.shouldRemove) {
+  const planFromResult = buildRemovalPlanFromResult(islResult, policy)
+  const cleanedResult = applyRemovalPlan(islResult, planFromResult)
+  console.log(`Removed ${planFromResult.instructionsToRemove.length} instruction(s); use cleanedResult for LLM`)
+}
+```
+
+**What this example demonstrates:**
+
+1. **Signal-Based Communication**: ISL emits `ISLSignal` (external contract) instead of exposing `ISLResult` (internal). This maintains layer separation.
+
+2. **AAL Decision Making**: AAL consumes the signal and applies configurable policies to determine actions (ALLOW/WARN/BLOCK).
+
+3. **Separation of Concerns**: 
+   - ISL: Detects threats, scores risk, sanitizes content
+   - AAL: Evaluates signals, applies policies, builds removal plans
+   - SDK: Executes actions, removes instructions, manages state
+
+4. **Architectural Benefits**:
+   - ✅ No layer coupling (AAL doesn't know ISL internals)
+   - ✅ Clear contracts between layers
+   - ✅ Easy to test and maintain
+   - ✅ Scalable architecture
+
+**Key Principle**: A layer should never consume the internal "result" of another layer. It consumes a signal.
+
+#### Risk score strategies (ISL)
+
+The risk score on the signal is derived from aggregated detections using a **strategy** chosen at emit time. Only registered strategies are allowed (auditability and reproducibility).
+
+| Strategy | Description | When to use |
+|----------|-------------|-------------|
+| **MAX_CONFIDENCE** (default) | Single highest confidence among detections. | Simple, conservative; good default. |
+| **SEVERITY_PLUS_VOLUME** | Highest confidence plus a small bump per extra detection (volume). | When multiple detections should raise risk. |
+| **WEIGHTED_BY_TYPE** | Weight by pattern type (e.g. jailbreak vs prompt-injection). | When some threat types should count more. |
+
+```typescript
+import { emitSignal, RiskScoreStrategy } from '@ai-pip/core/isl'
+
+// Default: MAX_CONFIDENCE
+const signal = emitSignal(islResult)
+
+// Explicit strategy
+const signalSev = emitSignal(islResult, {
+  riskScore: { strategy: RiskScoreStrategy.SEVERITY_PLUS_VOLUME }
+})
+
+// WEIGHTED_BY_TYPE with custom weights
+const signalWeighted = emitSignal(islResult, {
+  riskScore: {
+    strategy: RiskScoreStrategy.WEIGHTED_BY_TYPE,
+    typeWeights: { 'prompt-injection': 1.2, jailbreak: 1 }
+  }
+})
+```
+
+The strategy used is stored in **`signal.metadata.strategy`** for auditability. For full API and formulas, see the [ISL layer documentation](https://github.com/AI-PIP/ai-pip-docs/blob/main/docs/core/layers/ISL.md) in the protocol docs.
+
+---
+
+<a id="example-audit-utilities"></a>
+### Example: Audit and pretty-print utilities
+
+The core provides pure functions to format layer results and signals for clear, ordered audit output. Use them for logging, compliance, and debugging:
+
+```typescript
+import {
+  segment,
+  sanitize,
+  emitSignal,
+  envelope,
+  resolveAgentAction,
+  buildDecisionReason,
+  buildRemovalPlan,
+  formatCSLForAudit,
+  formatISLForAudit,
+  formatISLSignalForAudit,
+  formatAALForAudit,
+  formatCPEForAudit,
+  formatPipelineAudit,
+  formatPipelineAuditFull,
+  formatPipelineAuditAsJson,
+  createAuditRunId,
+  buildAuditLogEntry,
+  buildFullAuditPayload
+} from '@ai-pip/core'
+import type { AgentPolicy } from '@ai-pip/core'
+
+// Run pipeline
+const cslResult = segment({ content: 'User input', source: 'UI', metadata: {} })
+const islResult = sanitize(cslResult)
+const islSignal = emitSignal(islResult)
+const cpeResult = envelope(islResult, 'secret-key')
+
+const policy: AgentPolicy = {
+  thresholds: { warn: 0.3, block: 0.7 },
+  removal: { enabled: true }
+}
+const action = resolveAgentAction(islSignal, policy)
+const reason = buildDecisionReason(action, islSignal, policy)
+const removalPlan = buildRemovalPlan(islSignal, policy)
+
+// Pretty-print per layer (ordered, human-readable)
+console.log(formatCSLForAudit(cslResult))
+console.log(formatISLForAudit(islResult))
+console.log(formatISLSignalForAudit(islSignal))
+console.log(formatAALForAudit(reason, removalPlan))
+console.log(formatCPEForAudit(cpeResult))
+
+// Full pipeline audit report (CSL → ISL → CPE)
+const fullAudit = formatPipelineAudit(cslResult, islResult, cpeResult, {
+  title: 'AI-PIP Pipeline Audit',
+  sectionSeparator: '\n\n'
+})
+console.log(fullAudit)
+
+// Full pipeline with run id and Signal + AAL (CSL → ISL → Signal → AAL → optional CPE)
+const runId = createAuditRunId()
+const generatedAt = Date.now()
+const fullReport = formatPipelineAuditFull(cslResult, islResult, islSignal, reason, removalPlan, cpeResult, {
+  runId,
+  generatedAt,
+  includeCpe: true,
+  title: 'AI-PIP Pipeline Audit (full)'
+})
+console.log(fullReport)
+
+// JSON for logs / SIEM / machine consumption
+const payload = buildFullAuditPayload(cslResult, islResult, islSignal, reason, { runId, generatedAt, removalPlan, cpe: cpeResult })
+const jsonReport = formatPipelineAuditAsJson(cslResult, islResult, islSignal, reason, { runId, generatedAt, removalPlan, compact: true })
+logger.info(jsonReport)
+
+// Compact log entry (one line per request)
+const logEntry = buildAuditLogEntry(islSignal, reason, { runId, generatedAt })
+logger.info(JSON.stringify(logEntry))
+```
+
+**What this example demonstrates:**
+
+- **`formatCSLForAudit(result)`**: Formats CSL result (segments, trust, lineage) for audit.
+- **`formatISLForAudit(result)`**: Formats ISL result (segments, sanitization level, metadata, lineage).
+- **`formatISLSignalForAudit(signal)`**: Formats ISL signal (risk score, threats, detections) for audit.
+- **`formatAALForAudit(reason, removalPlan?)`**: Formats AAL decision reason and optional removal plan.
+- **`formatCPEForAudit(result)`**: Formats CPE result (metadata, signature, lineage).
+- **`formatPipelineAudit(csl, isl, cpe, options?)`**: Builds a single full pipeline audit string (CSL → ISL → CPE). Use **`options.includeSignalAndAAL`** with **`options.signal`** and **`options.aalReason`** to include ISL Signal and AAL sections.
+- **`formatPipelineAuditFull(csl, isl, signal, aalReason, removalPlan?, cpe?, options?)`**: Full pipeline report (CSL → ISL → Signal → AAL → optional CPE) with **run id** and **generated at** timestamp; lineage in each section.
+- **Run identifier**: **`createAuditRunId()`** generates a unique run id; pass **`options.runId`** and **`options.generatedAt`** to formatters for correlation across reports and logs.
+- **JSON variant**: **`buildFullAuditPayload(csl, isl, signal, reason, options?)`** returns a JSON-serializable object (runId, generatedAt, summary, sections with lineage). **`formatPipelineAuditAsJson(...)`** returns the JSON string; use **`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 (e.g. `logger.info(JSON.stringify(entry))`).
+
+All formatters accept minimal shapes (layer-agnostic) so you can pass any compatible object. Output is ordered and consistent for compliance and debugging. Lineage is preserved in every section for traceability.
+
+<a id="use-cases"></a>
+### Use cases
+
+Typical scenarios where AI-PIP core is used:
+
+| Use case | Layers involved | Goal |
+|----------|-----------------|------|
+| **Secure user chat** | CSL → ISL → CPE | Segment UI input, sanitize, wrap in envelope before sending to the model. |
+| **Policy-based moderation** | CSL → ISL → emitSignal → AAL | Get risk signal from ISL, resolve ALLOW/WARN/BLOCK; use `buildRemovalPlanFromResult` + `applyRemovalPlan` to get cleaned content for the LLM. |
+| **Audit and compliance** | Shared audit formatters | Pretty-print CSL/ISL/AAL/CPE results; full pipeline with run id (`formatPipelineAuditFull`); JSON variant (`buildFullAuditPayload`, `formatPipelineAuditAsJson`) for SIEM; compact log entry (`buildAuditLogEntry`) for one-line logging. |
+| **DOM / scraped content** | CSL (source: DOM) → ISL → CPE | Treat web content as untrusted (UC), apply aggressive sanitization. |
+| **System instructions** | CSL (source: SYSTEM) → ISL → CPE | Trusted content (TC), minimal sanitization. |
+| **Lineage and forensics** | All layers | Use lineage from results and `filterLineageByStep` / `getLastLineageEntry` for tracing. |
+
+**Example: policy-based moderation (ISL + AAL)**
+
+```typescript
+const cslResult = segment({ content: userInput, source: 'UI', metadata: {} })
+const islResult = sanitize(cslResult)
+const signal = emitSignal(islResult)
+const action = resolveAgentAction(signal, policy)
+const reason = buildDecisionReason(action, signal, policy)
+const plan = buildRemovalPlan(signal, policy)
+const planFromResult = buildRemovalPlanFromResult(islResult, policy)
+const cleanedResult = applyRemovalPlan(islResult, planFromResult)
+// Use action, reason, plan; send cleanedResult.segments to the LLM when removal is enabled.
+```
+
+**Example: audit report**
+
+```typescript
+// Text report (CSL → ISL → CPE)
+const report = formatPipelineAudit(cslResult, islResult, cpeResult, {
+  title: 'Request Audit',
+  sectionSeparator: '\n---\n'
+})
+logger.info(report)
+
+// Full report with run id and Signal + AAL
+const runId = createAuditRunId()
+const fullReport = formatPipelineAuditFull(cslResult, islResult, signal, reason, removalPlan, cpeResult, {
+  runId, generatedAt: Date.now(), includeCpe: true
+})
+logger.info(fullReport)
+
+// JSON for SIEM / machine consumption
+const jsonReport = formatPipelineAuditAsJson(cslResult, islResult, signal, reason, { runId, generatedAt: Date.now(), removalPlan, compact: true })
+logger.info(jsonReport)
+
+// One-line log entry per request
+const logEntry = buildAuditLogEntry(signal, reason, { runId, generatedAt: Date.now() })
+logger.info(JSON.stringify(logEntry))
+```
+
 <a id="documentation"></a>
 ## 📚 Documentation
 
@@ -545,6 +875,7 @@ All AI-PIP protocol documentation is centralized in the [documentation repositor
 - **[Core Overview](https://github.com/AI-PIP/ai-pip-docs/blob/main/docs/core/CORE.md)** - Semantic core description
 - **[CSL (Context Segmentation Layer)](https://github.com/AI-PIP/ai-pip-docs/blob/main/docs/core/layers/CSL.md)** - Context segmentation layer
 - **[ISL (Instruction Sanitization Layer)](https://github.com/AI-PIP/ai-pip-docs/blob/main/docs/core/layers/ISL.md)** - Instruction sanitization layer
+- **[AAL (Agent Action Lock)](https://github.com/AI-PIP/ai-pip-docs/blob/main/docs/core/layers/AAL.md)** - Agent Action Lock (hybrid layer)
 - **[CPE (Cryptographic Prompt Envelope)](https://github.com/AI-PIP/ai-pip-docs/blob/main/docs/core/layers/CPE.md)** - Cryptographic prompt envelope
 - **[Shared](https://github.com/AI-PIP/ai-pip-docs/blob/main/docs/core/layers/shared.md)** - Shared features and lineage
 
@@ -556,6 +887,7 @@ All AI-PIP protocol documentation is centralized in the [documentation repositor
 ### Code-Specific Documentation
 
 - **[CHANGELOG](./CHANGELOG.md)** - Package version history
+- **[FEATURE](./FEATURE.md)** - New and modified features by version
 - **[API Reference](#-basic-usage)** - Usage examples in this README
 
 <a id="testing"></a>
@@ -575,7 +907,9 @@ pnpm test:coverage
 pnpm test:ui
 ```
 
-**Current coverage**: 88.5%
+### Coverage
+- **Current coverage**: 92%+ (CSL, ISL, AAL, CPE, shared)
+
 
 <a id="development"></a>
 ## 🔧 Development
@@ -750,7 +1084,13 @@ For SDK development updates and roadmap, see the [AI-PIP Documentation Repositor
 
 For complete details and all version history, see [CHANGELOG.md](./CHANGELOG.md).
 
+<a id="features"></a>
+## 📋 Features
+
+Summary of new and modified features per version (aligned with the changelog): **[FEATURE.md](./FEATURE.md)**.
+
 ---
 
-**Current Version**: 0.1.8  
-**Status**: Phase 1 - Core Layers (100% completed)
+**Current Version**: 0.2.0  
+**Status**: Phase 1 - Core Layers (100% completed)  
+**Latest**: Architectural refactor with ISL/AAL separation and signal-based communication

package/dist/AAL/constants.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AAL display constants - semantic mapping for SDK/UI.
+ * Used for consistent display of AAL decisions (e.g. colors).
+ */
+import type { AnomalyAction } from './types.js';
+/**
+ * Display color for each AAL action.
+ * SDK/UI can use this for consistent styling (e.g. green = allow, yellow = warn, red = block).
+ */
+export declare const ACTION_DISPLAY_COLORS: Record<AnomalyAction, string>;
+/**
+ * Returns the display color for an AAL action.
+ */
+export declare function getActionDisplayColor(action: AnomalyAction): string;
+//# sourceMappingURL=constants.d.ts.map