aisp-validator 0.2.1 → 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.1 - Validate AISP 5.1 documents
+AISP Validator v0.2.2 - Validate AISP 5.1 documents
 
 Usage:
   aisp-validator <command> [file]
@@ -52,7 +52,7 @@ async function main() {
     }
 
     if (args[0] === '--version' || args[0] === '-v') {
-        console.log('aisp-validator v0.2.1');
+        console.log('aisp-validator v0.2.2');
         process.exit(0);
     }
 

package/package.json

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