aisp-validator 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bradley Ross
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# AISP Validator
+
+Validate [AISP 5.1](../AI_GUIDE.md) documents with <2% ambiguity using a <10KB WASM kernel.
+
+## Quick Start
+
+### CLI
+
+```bash
+# Validate a file
+npx aisp-validator validate spec.aisp
+
+# Get quality tier
+npx aisp-validator tier spec.aisp
+
+# Get density score
+npx aisp-validator density spec.aisp
+```
+
+### Node.js
+
+```javascript
+import AISP from 'aisp-validator';
+
+await AISP.init();
+
+const result = AISP.validate(`
+𝔸1.0.example@2026-01-14
+γ≔test
+
+⟦Ω:Meta⟧{ ∀D:Ambig(D)<0.02 }
+⟦Σ:Types⟧{ T≜ℕ }
+⟦Γ:Rules⟧{ ∀x:T:x≥0 }
+⟦Λ:Funcs⟧{ f≜λx.x }
+⟦Ε⟧⟨δ≜0.75;φ≜100;τ≜◊⁺⁺⟩
+`);
+
+console.log(result);
+// { valid: true, tier: '◊⁺⁺', delta: 0.78, ambiguity: 0.01 }
+```
+
+### Browser
+
+```html
+<script type="module">
+import AISP from './browser/loader.js';
+
+await AISP.init('/wasm/aisp.wasm');
+
+const result = AISP.validate(document);
+console.log(result.tier);  // '◊⁺⁺'
+</script>
+```
+
+## API
+
+### `AISP.init(wasmPath?)`
+Initialize the WASM kernel. Call 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
+}
+```
+
+### `AISP.isValid(source)`
+Quick check: returns `true` if valid.
+
+### `AISP.getTier(source)`
+Returns tier symbol: `'◊⁺⁺'`, `'◊⁺'`, `'◊'`, `'◊⁻'`, or `'⊘'`
+
+### `AISP.getDensity(source)`
+Returns density score (δ) between 0 and 1.
+
+### `AISP.validateFile(path)` (Node.js only)
+Validate 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 |
+
+## Required AISP Blocks
+
+Every valid AISP document must include:
+
+- `⟦Ω⟧` - Meta/foundation
+- `⟦Σ⟧` - Type definitions
+- `⟦Γ⟧` - Inference rules
+- `⟦Λ⟧` - Functions
+- `⟦Ε⟧` - Evidence
+
+## Building from Source
+
+```bash
+# Prerequisites
+rustup target add wasm32-unknown-unknown
+npm install -g binaryen
+
+# Build
+cd wasm
+./build.sh
+
+# Output: aisp.wasm (<10KB)
+```
+
+## Architecture
+
+The validator uses a Rust WASM kernel based on dependent type theory:
+
+- **Zero-allocation**: Arena-based memory, no heap
+- **Type checking**: Based on lean-agentic
+- **Symbol table**: AISP Σ_512 glossary
+- **Density computation**: AISP symbol ratio
+
+## License
+
+MIT License - see [LICENSE](./LICENSE)
+
+## Links
+
+- [AISP 5.1 Specification](../AI_GUIDE.md)
+- [Reference (Rosetta Stone)](../reference.md)
+- [Repository](https://github.com/bar181/aisp-open-core)

package/bin/cli.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * AISP Validator CLI
+ * Usage: aisp-validator <command> [file]
+ */
+
+import AISP from '../src/index.js';
+import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+
+const HELP = `
+AISP Validator - Validate AISP 5.1 documents
+
+Usage:
+  aisp-validator <command> [file]
+  aisp-validator [file]              Shorthand for validate
+
+Commands:
+  validate <file>   Validate an AISP document
+  tier <file>       Get quality tier (⊘ to ◊⁺⁺)
+  density <file>    Get density score (δ)
+  help              Show this help message
+
+Quality Tiers:
+  ◊⁺⁺  Platinum   δ ≥ 0.75
+  ◊⁺   Gold       δ ≥ 0.60
+  ◊    Silver     δ ≥ 0.40
+  ◊⁻   Bronze     δ ≥ 0.20
+  ⊘    Reject     δ < 0.20
+
+Examples:
+  npx aisp-validator validate spec.aisp
+  npx aisp-validator tier spec.aisp
+  npx aisp-validator spec.aisp
+`;
+
+async function main() {
+    const args = process.argv.slice(2);
+
+    if (args.length === 0 || args[0] === 'help' || args[0] === '--help' || args[0] === '-h') {
+        console.log(HELP);
+        process.exit(0);
+    }
+
+    let command = args[0];
+    let file = args[1];
+
+    // If first arg is a file (no command), default to validate
+    if (command && !['validate', 'tier', 'density'].includes(command)) {
+        file = command;
+        command = 'validate';
+    }
+
+    if (!file) {
+        console.error('Error: No file specified');
+        console.log('Usage: aisp-validator <command> <file>');
+        process.exit(1);
+    }
+
+    if (!existsSync(file)) {
+        console.error(`Error: File not found: ${file}`);
+        process.exit(1);
+    }
+
+    try {
+        await AISP.init();
+        const content = await readFile(file, 'utf-8');
+        const result = AISP.validate(content);
+
+        switch (command) {
+            case 'validate':
+                if (result.valid) {
+                    console.log(`✓ VALID`);
+                    console.log(`  Tier: ${result.tier}`);
+                    console.log(`  Density (δ): ${result.delta.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}`);
+                        console.log(`  Density (δ): ${result.delta.toFixed(3)}`);
+                    }
+                    process.exit(1);
+                }
+                break;
+
+            case 'tier':
+                console.log(result.tier);
+                break;
+
+            case 'density':
+                console.log(result.delta.toFixed(4));
+                break;
+        }
+    } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+}
+
+main();

package/browser/loader.js

@@ -0,0 +1,127 @@
+/**
+ * AISP WASM Loader
+ * Minimal JavaScript interface for browser integration (<1KB minified)
+ */
+
+const AISP = {
+    _instance: null,
+    _memory: null,
+    _allocPtr: 0x1000,
+
+    /**
+     * Initialize AISP kernel
+     * @param {string} wasmUrl - URL to aisp.wasm file
+     * @returns {Promise<number>} 0 on success
+     */
+    async init(wasmUrl = '/aisp.wasm') {
+        const response = await fetch(wasmUrl);
+        const bytes = await response.arrayBuffer();
+
+        const { instance } = await WebAssembly.instantiate(bytes, {
+            env: {
+                // Host memory allocator (optional)
+                host_alloc: (size, align) => {
+                    const aligned = (this._allocPtr + align - 1) & ~(align - 1);
+                    this._allocPtr = aligned + size;
+                    return aligned;
+                }
+            }
+        });
+
+        this._instance = instance.exports;
+        this._memory = new Uint8Array(instance.exports.memory.buffer);
+
+        return this._instance.aisp_init();
+    },
+
+    /**
+     * Validate AISP document
+     * @param {string} source - AISP source code
+     * @returns {object} Validation result
+     */
+    validate(source) {
+        if (!this._instance) {
+            throw new Error('AISP not initialized. Call init() first.');
+        }
+
+        const encoder = new TextEncoder();
+        const bytes = encoder.encode(source);
+
+        // Write to parse buffer at offset 0x1000
+        const ptr = 0x1000;
+        if (bytes.length > 1024) {
+            return { valid: false, error: 'Document too large (max 1KB)' };
+        }
+
+        // Refresh memory view in case it grew
+        this._memory = new Uint8Array(this._instance.memory.buffer);
+        this._memory.set(bytes, ptr);
+
+        // Parse document
+        const docId = this._instance.aisp_parse(ptr, bytes.length);
+        if (docId < 0) {
+            return {
+                valid: false,
+                error: `Parse error at offset ${this._instance.aisp_error_offset()}`,
+                errorCode: this._instance.aisp_error_code()
+            };
+        }
+
+        // Validate
+        const result = this._instance.aisp_validate(docId);
+
+        return {
+            valid: result === 0,
+            tier: this._getTierSymbol(this._instance.aisp_tier(docId)),
+            tierValue: this._instance.aisp_tier(docId),
+            delta: this._instance.aisp_density(docId),
+            ambiguity: this._instance.aisp_ambig(docId),
+            errorCode: result
+        };
+    },
+
+    /**
+     * Get tier symbol from numeric value
+     * @private
+     */
+    _getTierSymbol(tier) {
+        const symbols = ['⊘', '◊⁻', '◊', '◊⁺', '◊⁺⁺'];
+        return symbols[tier] || '⊘';
+    },
+
+    /**
+     * Quick validation check
+     * @param {string} source - AISP source
+     * @returns {boolean} true if valid
+     */
+    isValid(source) {
+        return this.validate(source).valid;
+    },
+
+    /**
+     * Get density score
+     * @param {string} source - AISP source
+     * @returns {number} density δ [0, 1]
+     */
+    getDensity(source) {
+        return this.validate(source).delta;
+    },
+
+    /**
+     * Get quality tier
+     * @param {string} source - AISP source
+     * @returns {string} tier symbol
+     */
+    getTier(source) {
+        return this.validate(source).tier;
+    }
+};
+
+// Export for different environments
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = AISP;
+} else if (typeof window !== 'undefined') {
+    window.AISP = AISP;
+}
+
+export default AISP;

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "aisp-validator",
+  "version": "0.1.0",
+  "description": "AISP 5.1 document validator - validates AI Symbolic Protocol specifications with <2% ambiguity",
+  "main": "src/index.js",
+  "bin": {
+    "aisp-validator": "bin/cli.js"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "require": "./src/index.cjs"
+    },
+    "./browser": "./browser/loader.js"
+  },
+  "files": [
+    "src/",
+    "browser/",
+    "bin/",
+    "wasm/aisp.wasm",
+    "wasm/aisp.h"
+  ],
+  "scripts": {
+    "test": "node --test test/",
+    "build:wasm": "cd wasm && ./build.sh"
+  },
+  "keywords": [
+    "aisp",
+    "validator",
+    "ai",
+    "specification",
+    "wasm",
+    "formal-methods",
+    "type-theory"
+  ],
+  "author": "Bradley Ross",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bar181/aisp-open-core"
+  },
+  "homepage": "https://github.com/bar181/aisp-open-core#readme",
+  "bugs": {
+    "url": "https://github.com/bar181/aisp-open-core/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,137 @@
+/**
+ * AISP Validator - Node.js Entry Point
+ * Validates AISP 5.1 documents using the WASM kernel
+ */
+
+import { readFile } from 'fs/promises';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const AISP = {
+    _instance: null,
+    _memory: null,
+    _allocPtr: 0x1000,
+    _initialized: false,
+
+    /**
+     * Initialize AISP kernel
+     * @param {string} [wasmPath] - Optional path to aisp.wasm
+     * @returns {Promise<number>} 0 on success
+     */
+    async init(wasmPath) {
+        if (this._initialized) return 0;
+
+        const path = wasmPath || join(__dirname, '..', 'wasm', 'aisp.wasm');
+        const bytes = await readFile(path);
+
+        const { instance } = await WebAssembly.instantiate(bytes, {
+            env: {
+                host_alloc: (size, align) => {
+                    const aligned = (this._allocPtr + align - 1) & ~(align - 1);
+                    this._allocPtr = aligned + size;
+                    return aligned;
+                }
+            }
+        });
+
+        this._instance = instance.exports;
+        this._memory = new Uint8Array(instance.exports.memory.buffer);
+        this._initialized = true;
+
+        return this._instance.aisp_init();
+    },
+
+    /**
+     * Validate AISP document
+     * @param {string} source - AISP source code
+     * @returns {object} Validation result
+     */
+    validate(source) {
+        if (!this._instance) {
+            throw new Error('AISP not initialized. Call init() first.');
+        }
+
+        const encoder = new TextEncoder();
+        const bytes = encoder.encode(source);
+
+        const ptr = 0x1000;
+        if (bytes.length > 1024) {
+            return { valid: false, error: 'Document too large (max 1KB)' };
+        }
+
+        this._memory = new Uint8Array(this._instance.memory.buffer);
+        this._memory.set(bytes, ptr);
+
+        const docId = this._instance.aisp_parse(ptr, bytes.length);
+        if (docId < 0) {
+            return {
+                valid: false,
+                error: `Parse error at offset ${this._instance.aisp_error_offset()}`,
+                errorCode: this._instance.aisp_error_code()
+            };
+        }
+
+        const result = this._instance.aisp_validate(docId);
+
+        return {
+            valid: result === 0,
+            tier: this._getTierSymbol(this._instance.aisp_tier(docId)),
+            tierValue: this._instance.aisp_tier(docId),
+            delta: this._instance.aisp_density(docId),
+            ambiguity: this._instance.aisp_ambig(docId),
+            errorCode: result
+        };
+    },
+
+    /**
+     * Get tier symbol from numeric value
+     * @private
+     */
+    _getTierSymbol(tier) {
+        const symbols = ['⊘', '◊⁻', '◊', '◊⁺', '◊⁺⁺'];
+        return symbols[tier] || '⊘';
+    },
+
+    /**
+     * Quick validation check
+     * @param {string} source - AISP source
+     * @returns {boolean} true if valid
+     */
+    isValid(source) {
+        return this.validate(source).valid;
+    },
+
+    /**
+     * Get density score
+     * @param {string} source - AISP source
+     * @returns {number} density δ [0, 1]
+     */
+    getDensity(source) {
+        return this.validate(source).delta;
+    },
+
+    /**
+     * Get quality tier
+     * @param {string} source - AISP source
+     * @returns {string} tier symbol
+     */
+    getTier(source) {
+        return this.validate(source).tier;
+    },
+
+    /**
+     * Validate file
+     * @param {string} filePath - Path to AISP file
+     * @returns {Promise<object>} Validation result
+     */
+    async validateFile(filePath) {
+        const content = await readFile(filePath, 'utf-8');
+        return this.validate(content);
+    }
+};
+
+export default AISP;
+export const { init, validate, isValid, getDensity, getTier, validateFile } = AISP;

package/wasm/aisp.h

@@ -0,0 +1,112 @@
+/**
+ * AISP WASM Kernel - C/C++ Header
+ * For chip integration (ESP32, RP2040, etc.)
+ */
+
+#ifndef AISP_H
+#define AISP_H
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* ============================================================================
+ * Core API
+ * ============================================================================ */
+
+/**
+ * Initialize AISP kernel
+ * Must be called before any other functions.
+ * @return 0 on success, <0 on error
+ */
+int32_t aisp_init(void);
+
+/**
+ * Parse AISP document from memory
+ * @param ptr Pointer to UTF-8 encoded AISP source
+ * @param len Length of source in bytes
+ * @return Document ID (0) on success, <0 on error
+ */
+int32_t aisp_parse(const uint8_t* ptr, uint32_t len);
+
+/**
+ * Validate parsed document
+ * @param doc_id Document ID from aisp_parse
+ * @return 0 if valid, <0 on error
+ */
+int32_t aisp_validate(int32_t doc_id);
+
+/**
+ * Get quality tier
+ * @param doc_id Document ID
+ * @return Tier value (0-4)
+ */
+int32_t aisp_tier(int32_t doc_id);
+
+/**
+ * Get ambiguity score
+ * @param doc_id Document ID
+ * @return Ambiguity [0.0, 1.0]
+ */
+float aisp_ambig(int32_t doc_id);
+
+/**
+ * Get density score (δ)
+ * @param doc_id Document ID
+ * @return Density [0.0, 1.0]
+ */
+float aisp_density(int32_t doc_id);
+
+/* ============================================================================
+ * Error Handling
+ * ============================================================================ */
+
+/**
+ * Get last error code
+ * @return Error code (0 = no error)
+ */
+int32_t aisp_error_code(void);
+
+/**
+ * Get error offset in input
+ * @return Byte offset where error occurred
+ */
+uint32_t aisp_error_offset(void);
+
+/* ============================================================================
+ * Constants
+ * ============================================================================ */
+
+/* Quality Tiers */
+#define AISP_TIER_REJECT    0  /* ⊘: δ < 0.20 */
+#define AISP_TIER_BRONZE    1  /* ◊⁻: δ ≥ 0.20 */
+#define AISP_TIER_SILVER    2  /* ◊: δ ≥ 0.40 */
+#define AISP_TIER_GOLD      3  /* ◊⁺: δ ≥ 0.60 */
+#define AISP_TIER_PLATINUM  4  /* ◊⁺⁺: δ ≥ 0.75 */
+
+/* Error Codes */
+#define AISP_OK             0   /* Success */
+#define AISP_ERR_PARSE     -1   /* Parse error */
+#define AISP_ERR_TYPE      -2   /* Type error */
+#define AISP_ERR_AMBIG     -3   /* Ambiguity too high */
+#define AISP_ERR_MEMORY    -4   /* Memory error */
+#define AISP_ERR_OVERFLOW  -5   /* Buffer overflow */
+
+/* Binding States (Δ⊗λ) */
+#define AISP_BIND_CRASH     0   /* ⊥: Logic conflict */
+#define AISP_BIND_NULL      1   /* ∅: Socket mismatch */
+#define AISP_BIND_ADAPT     2   /* λ: Type mismatch */
+#define AISP_BIND_ZERO      3   /* ⊤: Full compatibility */
+
+/* Limits */
+#define AISP_MAX_DOC_SIZE   1024  /* Maximum document size in bytes */
+#define AISP_MAX_TERMS      128   /* Maximum unique terms */
+#define AISP_MAX_DEPTH      32    /* Maximum context depth */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* AISP_H */