aisp-validator 0.2.0 → 0.2.2

package/README.md

@@ -1,20 +1,49 @@
 # AISP Validator
 
-Validate [AISP 5.1](../AI_GUIDE.md) documents with <2% ambiguity using a <10KB WASM kernel.
+[![npm version](https://img.shields.io/npm/v/aisp-validator.svg)](https://www.npmjs.com/package/aisp-validator)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**Validate AI Symbolic Protocol (AISP) 5.1 documents** with <2% ambiguity using a lightweight <10KB WASM kernel.
+
+AISP is a formal specification language designed for AI-to-AI communication, providing precise, unambiguous specifications that eliminate interpretation errors.
+
+## Installation
+
+```bash
+npm install aisp-validator
+```
+
+Or run directly with npx:
+
+```bash
+npx aisp-validator validate your-spec.aisp
+```
 
 ## Quick Start
 
-### CLI
+### CLI Usage
 
 ```bash
-# Validate a file
+# Validate a document
 npx aisp-validator validate spec.aisp
 
-# Get quality tier
+# Get quality tier (◊⁺⁺, ◊⁺, ◊, ◊⁻, ⊘)
 npx aisp-validator tier spec.aisp
 
 # Get density score
 npx aisp-validator density spec.aisp
+
+# Debug - detailed density breakdown
+npx aisp-validator debug spec.aisp
+```
+
+**Example output:**
+```
+✓ VALID
+  Tier: ◊⁺⁺ Platinum
+  Semantic (δ): 1.000
+  Pure (ρ):     1.857
+  Ambiguity:    0.010
 ```
 
 ### Node.js
@@ -25,7 +54,7 @@ import AISP from 'aisp-validator';
 await AISP.init();
 
 const result = AISP.validate(`
-𝔸1.0.example@2026-01-14
+𝔸1.0.example@2026-01-15
 γ≔test
 
 ⟦Ω:Meta⟧{ ∀D:Ambig(D)<0.02 }
@@ -36,40 +65,52 @@ const result = AISP.validate(`
 `);
 
 console.log(result);
-// { valid: true, tier: '◊⁺⁺', delta: 0.78, ambiguity: 0.01 }
+// {
+//   valid: true,
+//   tier: '◊⁺⁺',
+//   tierName: 'Platinum',
+//   delta: 0.82,
+//   pureDensity: 1.85,
+//   ambiguity: 0.01
+// }
 ```
 
 ### Browser
 
 ```html
 <script type="module">
-import AISP from './browser/loader.js';
+import AISP from 'aisp-validator/browser';
 
-await AISP.init('/wasm/aisp.wasm');
+await AISP.init('/path/to/aisp.wasm');
 
-const result = AISP.validate(document);
+const result = AISP.validate(documentSource);
 console.log(result.tier);  // '◊⁺⁺'
 </script>
 ```
 
-## API
+## API Reference
 
 ### `AISP.init(wasmPath?)`
-Initialize the WASM kernel. Call once before validation.
+Initialize the WASM kernel. Must be called once before validation.
 
 ### `AISP.validate(source)`
 Validate an AISP document. Returns:
 ```javascript
 {
-  valid: boolean,      // true if valid
-  tier: string,        // '⊘' | '◊⁻' | '◊' | '◊⁺' | '◊⁺⁺'
-  tierValue: number,   // 0-4
-  delta: number,       // density δ [0, 1]
-  ambiguity: number,   // [0, 1], must be <0.02
-  errorCode: number    // 0 = success
+  valid: boolean,       // true if document passes validation
+  tier: string,         // '⊘' | '◊⁻' | '◊' | '◊⁺' | '◊⁺⁺'
+  tierName: string,     // 'Reject' | 'Bronze' | 'Silver' | 'Gold' | 'Platinum'
+  tierValue: number,    // 0-4 (numeric tier)
+  delta: number,        // Semantic density δ [0, 1]
+  pureDensity: number,  // Pure density ρ (symbols/tokens)
+  ambiguity: number,    // [0, 1], must be <0.02
+  errorCode: number     // 0 = success
 }
 ```
 
+### `AISP.debug(source)`
+Get detailed density breakdown for debugging.
+
 ### `AISP.isValid(source)`
 Quick check: returns `true` if valid.
 
@@ -77,39 +118,92 @@ Quick check: returns `true` if valid.
 Returns tier symbol: `'◊⁺⁺'`, `'◊⁺'`, `'◊'`, `'◊⁻'`, or `'⊘'`
 
 ### `AISP.getDensity(source)`
-Returns density score (δ) between 0 and 1.
+Returns semantic density score (δ) between 0 and 1.
 
 ### `AISP.validateFile(path)` (Node.js only)
 Validate a file by path.
 
+### `AISP.debugFile(path)` (Node.js only)
+Debug a file by path.
+
 ## Quality Tiers
 
-| Tier | Symbol | Threshold | Meaning |
-|------|--------|-----------|---------|
-| Platinum | ◊⁺⁺ | δ ≥ 0.75 | Production-ready |
-| Gold | ◊⁺ | δ ≥ 0.60 | High quality |
-| Silver | ◊ | δ ≥ 0.40 | Acceptable |
-| Bronze | ◊⁻ | δ ≥ 0.20 | Needs improvement |
-| Reject | ⊘ | δ < 0.20 | Insufficient AISP |
+| Tier | Symbol | Threshold | Use Case |
+|------|--------|-----------|----------|
+| **Platinum** | ◊⁺⁺ | δ ≥ 0.75 | Production deployment |
+| **Gold** | ◊⁺ | δ ≥ 0.60 | Staging/pre-production |
+| **Silver** | ◊ | δ ≥ 0.40 | Development/testing |
+| **Bronze** | ◊⁻ | δ ≥ 0.20 | Draft/review |
+| **Reject** | ⊘ | δ < 0.20 | Insufficient quality |
+
+## Density Metrics
+
+### Semantic Density (δ)
+Measures specification completeness:
+```
+δ = (blockScore × 0.4) + (bindingScore × 0.6)
+```
+- **blockScore**: Required blocks present (⟦Ω⟧, ⟦Σ⟧, ⟦Γ⟧, ⟦Λ⟧, ⟦Ε⟧)
+- **bindingScore**: Semantic operators (≜, ≔, ∀, ∃, λ, ⇒, ∈, etc.)
+
+### Pure Density (ρ)
+Measures symbol concentration:
+```
+ρ = |AISP_symbols| ÷ |non_ws_tokens|
+```
 
 ## Required AISP Blocks
 
-Every valid AISP document must include:
+Every valid AISP document must include these 5 blocks:
+
+| Block | Name | Purpose |
+|-------|------|---------|
+| `⟦Ω⟧` | Meta | Metadata and constraints |
+| `⟦Σ⟧` | Types | Type definitions |
+| `⟦Γ⟧` | Rules | Inference rules |
+| `⟦Λ⟧` | Funcs | Function definitions |
+| `⟦Ε⟧` | Evidence | Quality metrics |
+
+## Example AISP Document
+
+```aisp
+𝔸5.1.tic-tac-toe@2026-01-15
+γ≔game-spec
+
+⟦Ω:Meta⟧{
+  ∀D∈AISP:Ambig(D)<0.02
+  Target≜AI-Agents
+}
+
+⟦Σ:Types⟧{
+  Player≜{X,O}
+  Cell≜{Empty,X,O}
+  Board≜Cell[9]
+}
+
+⟦Γ:Rules⟧{
+  ∀move:ValidMove(board,pos)⇔board[pos]=Empty
+  ∀win:WinCondition⇔∃line∈Lines:∀c∈line:c=player
+}
+
+⟦Λ:Funcs⟧{
+  makeMove≜λ(board,pos,player).board[pos]←player
+  checkWin≜λboard.∃p∈Player:WinCondition(board,p)
+}
 
-- `⟦Ω⟧` - Meta/foundation
-- `⟦Σ⟧` - Type definitions
-- `⟦Γ⟧` - Inference rules
-- `⟦Λ⟧` - Functions
-- `⟦Ε⟧` - Evidence
+⟦Ε⟧⟨δ≜0.75;φ≜100;τ≜◊⁺⁺⟩
+```
 
 ## Building from Source
 
+The validator includes full Rust source code:
+
 ```bash
 # Prerequisites
 rustup target add wasm32-unknown-unknown
-npm install -g binaryen
+cargo install wasm-opt  # or: npm install -g binaryen
 
-# Build
+# Build WASM kernel
 cd wasm
 ./build.sh
 
@@ -118,19 +212,35 @@ cd wasm
 
 ## Architecture
 
-The validator uses a Rust WASM kernel based on dependent type theory:
+- **WASM Kernel**: Zero-allocation Rust core (<10KB)
+- **Type System**: Based on dependent type theory
+- **Symbol Table**: AISP Σ_512 glossary (50+ formal symbols)
+- **Validation**: Structural + semantic analysis
 
-- **Zero-allocation**: Arena-based memory, no heap
-- **Type checking**: Based on lean-agentic
-- **Symbol table**: AISP Σ_512 glossary
-- **Density computation**: AISP symbol ratio
+## What is AISP?
 
-## License
+**AI Symbolic Protocol (AISP)** is a formal specification language designed for precise AI-to-AI communication. Key benefits:
+
+- **<2% Ambiguity**: Eliminates interpretation errors
+- **Formal Semantics**: Based on type theory and logic
+- **Machine-Readable**: Designed for AI agents
+- **Human-Auditable**: Clear structure for review
 
-MIT License - see [LICENSE](./LICENSE)
+Learn more:
+- [AI Guide](https://github.com/bar181/aisp-open-core/blob/main/AI_GUIDE.md) - Complete AISP specification
+- [Human Guide](https://github.com/bar181/aisp-open-core/blob/main/HUMAN_GUIDE.md) - Human-readable introduction
+- [Reference (Rosetta Stone)](https://github.com/bar181/aisp-open-core/blob/main/reference.md) - Symbol glossary
 
 ## Links
 
-- [AISP 5.1 Specification](../AI_GUIDE.md)
-- [Reference (Rosetta Stone)](../reference.md)
-- [Repository](https://github.com/bar181/aisp-open-core)
+- **GitHub**: [github.com/bar181/aisp-open-core](https://github.com/bar181/aisp-open-core)
+- **npm**: [npmjs.com/package/aisp-validator](https://www.npmjs.com/package/aisp-validator)
+- **Issues**: [Report bugs](https://github.com/bar181/aisp-open-core/issues)
+
+## License
+
+MIT License - see [LICENSE](https://github.com/bar181/aisp-open-core/blob/main/validator/LICENSE)
+
+---
+
+**Made for AI agents, auditable by humans.**

package/bin/cli.js

@@ -9,7 +9,7 @@ import { readFile } from 'fs/promises';
 import { existsSync } from 'fs';
 
 const HELP = `
-AISP Validator v0.2.0 - Validate AISP 5.1 documents
+AISP Validator v0.2.2 - Validate AISP 5.1 documents
 
 Usage:
   aisp-validator <command> [file]
@@ -29,11 +29,13 @@ Quality Tiers:
   ◊⁻   Bronze     δ ≥ 0.20
   ⊘    Reject     δ < 0.20
 
-Density Formula:
-  δ = (blockScore × 0.4) + (bindingScore × 0.6)
+Density Formulas:
+  δ (semantic) = (blockScore × 0.4) + (bindingScore × 0.6)
+  ρ (pure)     = |AISP_symbols| ÷ |non_ws_tokens|
 
   blockScore: Required blocks present (⟦Ω⟧, ⟦Σ⟧, ⟦Γ⟧, ⟦Λ⟧, ⟦Ε⟧)
   bindingScore: Semantic operators (≜, ≔, ∀, ∃, λ, ⇒, ∈, etc.)
+  pureDensity: Ratio of AISP symbols to total tokens
 
 Examples:
   npx aisp-validator validate spec.aisp
@@ -50,7 +52,7 @@ async function main() {
     }
 
     if (args[0] === '--version' || args[0] === '-v') {
-        console.log('aisp-validator v0.2.0');
+        console.log('aisp-validator v0.2.2');
         process.exit(0);
     }
 
@@ -84,15 +86,17 @@ async function main() {
                 if (result.valid) {
                     console.log(`✓ VALID`);
                     console.log(`  Tier: ${result.tier} ${result.tierName}`);
-                    console.log(`  Density (δ): ${result.delta.toFixed(3)}`);
-                    console.log(`  Ambiguity: ${result.ambiguity.toFixed(3)}`);
+                    console.log(`  Semantic (δ): ${result.delta.toFixed(3)}`);
+                    console.log(`  Pure (ρ):     ${result.pureDensity.toFixed(3)}`);
+                    console.log(`  Ambiguity:    ${result.ambiguity.toFixed(3)}`);
                     process.exit(0);
                 } else {
                     console.log(`✗ INVALID`);
                     console.log(`  Error: ${result.error || `Error code ${result.errorCode}`}`);
                     if (result.tier) {
                         console.log(`  Tier: ${result.tier} ${result.tierName}`);
-                        console.log(`  Density (δ): ${result.delta.toFixed(3)}`);
+                        console.log(`  Semantic (δ): ${result.delta.toFixed(3)}`);
+                        console.log(`  Pure (ρ):     ${result.pureDensity.toFixed(3)}`);
                     }
                     process.exit(1);
                 }
@@ -116,8 +120,9 @@ async function main() {
                 console.log(`\nAISP Density Debug`);
                 console.log(`==================`);
                 console.log(`\nTier: ${debug.tier} ${debug.tierName}`);
-                console.log(`Density (δ): ${debug.delta.toFixed(3)}`);
-                console.log(`\nScore Breakdown:`);
+                console.log(`Semantic (δ): ${debug.delta.toFixed(3)}`);
+                console.log(`Pure (ρ):     ${debug.pureDensity.toFixed(3)}`);
+                console.log(`\nSemantic Score Breakdown:`);
                 console.log(`  Block Score:   ${(debug.blockScore * 100).toFixed(1)}% (weight: 40%)`);
                 console.log(`  Binding Score: ${(debug.bindingScore * 100).toFixed(1)}% (weight: 60%)`);
                 console.log(`\nBlocks Found: ${debug.breakdown.blocksFound}/${debug.breakdown.blocksRequired}`);
@@ -129,7 +134,12 @@ async function main() {
                 console.log(`  λ lambdas:      ${debug.breakdown.lambdas}`);
                 console.log(`  ⇒⇔ implications: ${debug.breakdown.implications}`);
                 console.log(`  ∈⊆∩∪ set ops:   ${debug.breakdown.setOps}`);
-                console.log(`\nFormula: δ = (${debug.blockScore.toFixed(2)} × 0.4) + (${debug.bindingScore.toFixed(2)} × 0.6) = ${debug.delta.toFixed(3)}`);
+                console.log(`\nPure Density Breakdown:`);
+                console.log(`  AISP Symbols: ${debug.breakdown.symbolCount}`);
+                console.log(`  Total Tokens: ${debug.breakdown.tokenCount}`);
+                console.log(`\nFormulas:`);
+                console.log(`  δ = (${debug.blockScore.toFixed(2)} × 0.4) + (${debug.bindingScore.toFixed(2)} × 0.6) = ${debug.delta.toFixed(3)}`);
+                console.log(`  ρ = ${debug.breakdown.symbolCount} ÷ ${debug.breakdown.tokenCount} = ${debug.pureDensity.toFixed(3)}`);
                 break;
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aisp-validator",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "AISP 5.1 document validator - validates AI Symbolic Protocol specifications with <2% ambiguity",
   "main": "src/index.js",
   "bin": {

package/src/index.js

@@ -10,11 +10,69 @@ import { dirname, join } from 'path';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+/**
+ * AISP Symbol Set (Σ_512 subset for density calculation)
+ * Formal symbols that define AISP semantic content
+ */
+const AISP_SYMBOLS = [
+    // Block delimiters
+    '⟦', '⟧',
+    // Operators
+    '≜', '≔', '≡', '≢',
+    // Quantifiers
+    '∀', '∃',
+    // Lambda
+    'λ',
+    // Logic
+    '⇒', '⇔', '→', '↔', '∧', '∨', '¬', '⊕',
+    // Sets
+    '∈', '∉', '⊆', '⊇', '∩', '∪', '∅', '𝒫',
+    // Relations
+    '≤', '≥', '<', '>',
+    // Types
+    'ℕ', 'ℤ', 'ℝ', '𝔹', '𝕊',
+    // Document
+    '𝔸',
+    // Tier symbols
+    '◊', '⊘',
+    // Angle brackets (tuples)
+    '⟨', '⟩',
+    // Greek letters (commonly used)
+    'α', 'β', 'γ', 'δ', 'ε', 'φ', 'τ', 'ρ', 'Ω', 'Σ', 'Γ', 'Λ', 'Ε', 'Θ', 'Χ', 'Δ', 'Π'
+];
+
+/**
+ * Calculate pure density: |AISP_symbols| ÷ |non_ws_tokens|
+ * @param {string} text - AISP source
+ * @returns {object} { pureDensity, symbolCount, tokenCount }
+ */
+function calculatePureDensity(text) {
+    // Count AISP symbols
+    let symbolCount = 0;
+    for (const symbol of AISP_SYMBOLS) {
+        const matches = text.split(symbol).length - 1;
+        symbolCount += matches;
+    }
+
+    // Count non-whitespace tokens (split on whitespace, filter empty)
+    const tokens = text.split(/\s+/).filter(t => t.length > 0);
+    const tokenCount = tokens.length;
+
+    // Pure density: ratio of AISP symbols to tokens
+    const pureDensity = tokenCount > 0 ? symbolCount / tokenCount : 0;
+
+    return {
+        pureDensity,
+        symbolCount,
+        tokenCount
+    };
+}
+
 /**
  * Calculate semantic density using Block Coverage + Binding Density
  * δ = (blockScore × 0.4) + (bindingScore × 0.6)
  * @param {string} text - AISP source
- * @returns {object} { delta, blockScore, bindingScore, breakdown }
+ * @returns {object} { delta, blockScore, bindingScore, breakdown, pureDensity }
  */
 function calculateSemanticDensity(text) {
     // Required blocks present?
@@ -33,13 +91,17 @@ function calculateSemanticDensity(text) {
     const totalBindings = definitions + assignments + quantifiers + lambdas + implications + setOps;
     const bindingScore = Math.min(1, totalBindings / 20);
 
-    // Combined score
+    // Combined score (semantic delta)
     const delta = (blockScore * 0.4) + (bindingScore * 0.6);
 
+    // Pure density (symbol/token ratio)
+    const pureResult = calculatePureDensity(text);
+
     return {
         delta,
         blockScore,
         bindingScore,
+        pureDensity: pureResult.pureDensity,
         breakdown: {
             blocksFound: blocksFound.length,
             blocksRequired: blocks.length,
@@ -49,7 +111,9 @@ function calculateSemanticDensity(text) {
             lambdas,
             implications,
             setOps,
-            totalBindings
+            totalBindings,
+            symbolCount: pureResult.symbolCount,
+            tokenCount: pureResult.tokenCount
         }
     };
 }
@@ -143,6 +207,7 @@ const AISP = {
             tierValue: tierResult.tierValue,
             tierName: tierResult.tierName,
             delta: densityResult.delta,
+            pureDensity: densityResult.pureDensity,
             ambiguity: this._instance.aisp_ambig(docId),
             errorCode: parseResult
         };
@@ -160,6 +225,7 @@ const AISP = {
         return {
             ...tierResult,
             delta: densityResult.delta,
+            pureDensity: densityResult.pureDensity,
             blockScore: densityResult.blockScore,
             bindingScore: densityResult.bindingScore,
             breakdown: densityResult.breakdown
@@ -225,4 +291,4 @@ const AISP = {
 
 export default AISP;
 export const { init, validate, isValid, getDensity, getTier, validateFile, debug, debugFile } = AISP;
-export { calculateSemanticDensity, getTierFromDelta };
+export { calculateSemanticDensity, calculatePureDensity, getTierFromDelta, AISP_SYMBOLS };