@aleph-ai/tinyaleph 1.5.7 → 1.6.1

package/examples/crt-homology/03-homology-loss.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * Example 03: Homology Loss for Consistency Detection
+ * 
+ * Demonstrates detecting "holes" in residue space - consistency failures
+ * that persist under perturbation.
+ * 
+ * Key insight: "Holes are not degrees of freedom. Holes are consistency
+ * failures that persist under perturbation."
+ * 
+ * Key concepts:
+ * - Ker(ℛ) = { r | ε(r) > τ } (kernel = high reconstruction error)
+ * - Cycles in kernel represent semantic inconsistencies
+ * - Betti numbers: β₀ = components, β₁ = holes (1-cycles)
+ * - ℒ_homology = Σ_{cycles} f(cycle) penalizes inconsistency
+ */
+
+'use strict';
+
+const {
+    CRTReconstructor,
+    HomologyLoss,
+    DEFAULT_PRIMES_SMALL
+} = require('../../core/crt-homology');
+
+console.log('=== Homology Loss Example ===\n');
+
+const primes = DEFAULT_PRIMES_SMALL;
+const crt = new CRTReconstructor(primes);
+const homology = new HomologyLoss({
+    tau: 0.1,     // Kernel detection threshold
+    alpha: 1.0,   // Cycle length exponent
+    beta: 1.0,    // Residue weight
+    gamma: 0.5,   // Residue exponent
+    lambda: 1.0   // Overall loss weight
+});
+
+console.log(`Moduli: [${primes.join(', ')}], Product P = ${crt.P}\n`);
+
+// Example 1: Consistent residue batch (no holes)
+console.log('1. Consistent Residue Batch:');
+const consistentBatch = [];
+for (let i = 0; i < 10; i++) {
+    // Generate residues that are consistent (low error)
+    const L = Math.floor(Math.random() * crt.P);
+    const residues = primes.map(p => L % p);
+    consistentBatch.push(residues);
+}
+
+console.log('   Generated 10 consistent residue tuples');
+const consistentResult = homology.compute(consistentBatch, crt);
+console.log(`   Cycles detected: ${consistentResult.cycles}`);
+console.log(`   Homology loss: ${consistentResult.loss.toFixed(6)}`);
+console.log(`   Total points in kernel: ${consistentResult.totalPoints}`);
+
+const betti1 = homology.computeBettiNumbers(consistentBatch, crt);
+console.log(`   Betti numbers: β₀=${betti1.beta0}, β₁=${betti1.beta1}`);
+
+// Example 2: Inconsistent residue batch (with holes)
+console.log('\n2. Inconsistent Residue Batch:');
+const inconsistentBatch = [];
+for (let i = 0; i < 10; i++) {
+    // Generate residues that may be inconsistent
+    // (random values that don't correspond to valid CRT reconstruction)
+    const residues = primes.map(p => Math.random() * p);
+    inconsistentBatch.push(residues);
+}
+
+console.log('   Generated 10 random (potentially inconsistent) residue tuples');
+const inconsistentResult = homology.compute(inconsistentBatch, crt);
+console.log(`   Cycles detected: ${inconsistentResult.cycles}`);
+console.log(`   Homology loss: ${inconsistentResult.loss.toFixed(6)}`);
+console.log(`   Total points in kernel: ${inconsistentResult.totalPoints}`);
+
+const betti2 = homology.computeBettiNumbers(inconsistentBatch, crt);
+console.log(`   Betti numbers: β₀=${betti2.beta0}, β₁=${betti2.beta1}`);
+
+// Example 3: Mixed batch
+console.log('\n3. Mixed Batch (alternating consistent/inconsistent):');
+const mixedBatch = [];
+for (let i = 0; i < 10; i++) {
+    if (i % 2 === 0) {
+        // Consistent
+        const L = Math.floor(Math.random() * crt.P);
+        mixedBatch.push(primes.map(p => L % p));
+    } else {
+        // Inconsistent
+        mixedBatch.push(primes.map(p => Math.random() * p));
+    }
+}
+
+console.log('   Generated 10 mixed residue tuples');
+const mixedResult = homology.compute(mixedBatch, crt);
+console.log(`   Cycles detected: ${mixedResult.cycles}`);
+console.log(`   Homology loss: ${mixedResult.loss.toFixed(6)}`);
+
+if (mixedResult.details.length > 0) {
+    console.log('\n   Cycle details:');
+    for (const detail of mixedResult.details) {
+        console.log(`     Length ${detail.length}: loss=${detail.loss.toFixed(4)}, ` +
+                    `mean_error=${detail.meanError.toFixed(4)}`);
+    }
+}
+
+// Example 4: Persistence analysis
+console.log('\n4. Cycle Persistence (robustness of holes):');
+
+// Create a persistent hole (cluster of inconsistent points)
+const persistentBatch = [];
+for (let i = 0; i < 20; i++) {
+    if (i >= 5 && i <= 10) {
+        // Create a cluster of high-error points
+        persistentBatch.push([0.99, 0.01, 0.5, 0.5]);
+    } else {
+        const L = Math.floor(Math.random() * crt.P);
+        persistentBatch.push(primes.map(p => L % p));
+    }
+}
+
+const cycles = homology.detectCycles(persistentBatch, crt);
+console.log(`   Batch size: 20, Cluster at indices 5-10`);
+console.log(`   Detected ${cycles.length} cycle(s)`);
+
+for (const cycle of cycles) {
+    const persistence = homology.cyclePersistence(cycle);
+    console.log(`     Cycle of length ${cycle.length}: persistence=${persistence.toFixed(4)}`);
+}
+
+const betti3 = homology.computeBettiNumbers(persistentBatch, crt);
+console.log(`   Final Betti numbers: β₀=${betti3.beta0}, β₁=${betti3.beta1}`);
+
+console.log('\n✓ Example complete\n');

package/examples/crt-homology/04-crt-resoformer.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * Example 04: CRT-Enhanced ResoFormer
+ * 
+ * Demonstrates the full CRT-enhanced ResoFormer architecture:
+ * - Per-modulus attention heads with Birkhoff projection
+ * - CRT fusion of head outputs
+ * - Homology detection for semantic consistency
+ * 
+ * This integrates with tinyaleph's SparsePrimeState representation.
+ */
+
+'use strict';
+
+const {
+    CRTResonantAttention,
+    HomologyRegularizedBlock,
+    CRTResoFormer,
+    createCRTResoFormer
+} = require('../../core/rformer-crt');
+
+const { SparsePrimeState } = require('../../core/rformer');
+
+console.log('=== CRT-Enhanced ResoFormer Example ===\n');
+
+// Example 1: CRT Resonant Attention
+console.log('1. CRT Resonant Attention:');
+const attention = new CRTResonantAttention({
+    numHeads: 4,
+    numPrimes: 4096,
+    activeK: 32
+});
+
+console.log(`   Number of heads: ${attention.numHeads}`);
+console.log(`   Moduli: [${attention.moduli.join(', ')}]`);
+console.log(`   Product P = ${attention.moduli.reduce((a, b) => a * b, 1)}`);
+
+// Create sample states
+const query = SparsePrimeState.fromHash('query concept');
+const keys = [
+    SparsePrimeState.fromHash('key 1 - related'),
+    SparsePrimeState.fromHash('key 2 - similar'),
+    SparsePrimeState.fromHash('key 3 - different')
+];
+const values = keys.map((_, i) => SparsePrimeState.fromHash(`value ${i}`));
+
+console.log(`   Query: ${query.getActivePrimes().slice(0, 5).join(', ')}...`);
+console.log(`   Keys: ${keys.length} states\n`);
+
+const attnResult = attention.forward(query, keys, values);
+console.log(`   Output primes: ${attnResult.result.getActivePrimes().length} active`);
+console.log(`   Heads computed: ${attnResult.headOutputs.length}`);
+console.log(`   CRT residues: [${attnResult.crtResidues.map(r => r.toFixed(2)).join(', ')}]`);
+console.log(`   Homology detected: ${attnResult.homologyInfo.hasHoles}`);
+console.log(`   Betti numbers: β₀=${attnResult.homologyInfo.bettiNumbers[0]}, ` +
+            `β₁=${attnResult.homologyInfo.bettiNumbers[1]}`);
+
+// Example 2: Homology Regularized Block
+console.log('\n2. Homology Regularized Block:');
+const block = new HomologyRegularizedBlock({
+    numHeads: 4,
+    hiddenDim: 256,
+    numPrimes: 4096,
+    activeK: 32,
+    homologyWeight: 0.1
+});
+
+const input = SparsePrimeState.fromHash('input state');
+const context = [
+    SparsePrimeState.fromHash('context 1'),
+    SparsePrimeState.fromHash('context 2'),
+    SparsePrimeState.fromHash('context 3')
+];
+
+const blockResult = block.forward(input, context);
+console.log(`   Input primes: ${input.getActivePrimes().length}`);
+console.log(`   Output primes: ${blockResult.output.getActivePrimes().length}`);
+console.log(`   Homology loss: ${blockResult.loss.toFixed(6)}`);
+console.log(`   Has holes: ${blockResult.homologyInfo.hasHoles}`);
+
+// Example 3: Full CRT ResoFormer
+console.log('\n3. Full CRT ResoFormer:');
+const model = createCRTResoFormer({
+    numLayers: 3,
+    numHeads: 4,
+    hiddenDim: 256,
+    numPrimes: 4096,
+    activeK: 32,
+    homologyWeight: 0.1,
+    usePositionalEncoding: true
+});
+
+console.log(`   Layers: ${model.numLayers}`);
+console.log(`   Position encoding: ${model.usePositionalEncoding}`);
+console.log(`   Parameter count (est): ${model.getParameterCount()}`);
+
+// Process a sequence
+const sequence = [
+    SparsePrimeState.fromHash('the'),
+    SparsePrimeState.fromHash('quick'),
+    SparsePrimeState.fromHash('brown'),
+    SparsePrimeState.fromHash('fox')
+];
+
+console.log(`\n   Processing sequence of ${sequence.length} tokens...`);
+const result = model.forward(sequence);
+
+console.log(`   Output sequence length: ${result.output.length}`);
+console.log(`   Total homology loss: ${result.totalLoss.toFixed(6)}`);
+console.log(`   Homology report:`);
+console.log(`     Holes detected: ${result.homologyReport.hasHoles}`);
+console.log(`     Total holes: ${result.homologyReport.totalHolesDetected}`);
+console.log(`     Max Betti number: ${result.homologyReport.maxBettiNumber}`);
+console.log(`     Layer reports: ${result.homologyReport.layerReports.length}`);
+
+// Example 4: Training mode
+console.log('\n4. Training vs Evaluation Mode:');
+model.train(true);
+console.log(`   Training mode: ${model.blocks[0].training}`);
+
+model.eval();
+console.log(`   After eval(): ${model.blocks[0].training}`);
+
+// Example 5: CRT Configuration
+console.log('\n5. CRT Configuration:');
+const crtConfig = model.getCRTConfig();
+console.log(`   Moduli: [${crtConfig.moduli.join(', ')}]`);
+console.log(`   Heads: ${crtConfig.numHeads}`);
+console.log(`   Temperature: ${crtConfig.temperature}`);
+console.log(`   Head weights (first head): [${crtConfig.headWeights[0].map(w => w.toFixed(3)).join(', ')}]`);
+
+console.log('\n✓ Example complete\n');

package/examples/crt-homology/README.md

@@ -0,0 +1,67 @@
+# CRT-Homology Examples
+
+This directory contains examples demonstrating the CRT-Homology framework integrated into tinyaleph.
+
+## Examples
+
+### 01-residue-encoding.js
+Demonstrates encoding hidden vectors into K residue distributions over coprime moduli, then reconstructing via Chinese Remainder Theorem.
+
+```bash
+node examples/crt-homology/01-residue-encoding.js
+```
+
+### 02-birkhoff-attention.js
+Shows projecting attention matrices onto the Birkhoff polytope (doubly-stochastic matrices) using Sinkhorn-Knopp algorithm.
+
+```bash
+node examples/crt-homology/02-birkhoff-attention.js
+```
+
+### 03-homology-loss.js
+Illustrates detecting "holes" in residue space - consistency failures that persist under perturbation. Computes Betti numbers and homology loss.
+
+```bash
+node examples/crt-homology/03-homology-loss.js
+```
+
+### 04-crt-resoformer.js
+Full CRT-enhanced ResoFormer architecture with per-modulus attention heads, CRT fusion, and homology detection.
+
+```bash
+node examples/crt-homology/04-crt-resoformer.js
+```
+
+## Key Concepts
+
+### Chinese Remainder Theorem (CRT)
+Given coprime moduli p₁, p₂, ..., pₖ with product P = ∏pₖ, any value L ∈ [0, P) can be uniquely reconstructed from its residues mod each pₖ:
+
+```
+L̂ = Σₖ E[rₖ] · (P/pₖ) · (P/pₖ)⁻¹ mod P
+```
+
+### Birkhoff Polytope
+The set of doubly-stochastic matrices (all row and column sums = 1). Projecting attention onto this space enforces "conservation of attention mass".
+
+### Homology Loss
+Detects semantic inconsistencies as topological holes:
+
+```
+ℒ_homology = Σ_{cycles ∈ Ker(ℛ)} f(cycle)
+```
+
+Where Ker(ℛ) = { r | ε(r) > τ } is the kernel of high-error residue tuples.
+
+### Betti Numbers
+- β₀: Number of connected components in the kernel
+- β₁: Number of 1-dimensional holes (cycles that don't bound)
+
+## Mathematical Foundation
+
+See [docs/reference/09-crt-homology.md](../../docs/reference/09-crt-homology.md) for complete mathematical details.
+
+## Run All Examples
+
+```bash
+for f in examples/crt-homology/*.js; do node "$f"; done

package/examples/crypto/01-password-hash.js

@@ -0,0 +1,210 @@
+/**
+ * @example Password Hashing
+ * @description Securely hash passwords using TinyAleph's cryptographic backend
+ * 
+ * TinyAleph provides cryptographic hashing that:
+ * - Creates deterministic hashes from input
+ * - Is one-way (cannot reverse to get original)
+ * - Has configurable output length
+ */
+
+const { CryptographicBackend } = require('../../modular');
+
+// ===========================================
+// SETUP
+// ===========================================
+
+const backend = new CryptographicBackend({ dimension: 32 });
+
+console.log('TinyAleph Password Hashing Example');
+console.log('===================================\n');
+
+// ===========================================
+// BASIC PASSWORD HASHING
+// ===========================================
+
+console.log('Basic Password Hashing:');
+console.log('-'.repeat(50) + '\n');
+
+var passwords = [
+    'password123',
+    'SecureP@ss!',
+    'MySecret2024',
+    'hunter2'
+];
+
+console.log('Password                 Hash (first 32 chars)');
+console.log('-'.repeat(60));
+
+for (var i = 0; i < passwords.length; i++) {
+    var password = passwords[i];
+    var hash = backend.hash(password);
+    var hashHex = hash.toString('hex');
+    console.log(password.padEnd(25) + hashHex.substring(0, 32) + '...');
+}
+
+// ===========================================
+// HASH VERIFICATION
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Password Verification:');
+console.log('='.repeat(50) + '\n');
+
+function verifyPassword(password, storedHash) {
+    var computedHash = backend.hash(password);
+    return computedHash.toString('hex') === storedHash;
+}
+
+// Store a password hash
+var originalPassword = 'MySecretPassword';
+var storedHash = backend.hash(originalPassword).toString('hex');
+
+console.log('Stored hash: ' + storedHash.substring(0, 40) + '...\n');
+
+// Test verification
+var testPasswords = [
+    'MySecretPassword',  // Correct
+    'mysecretpassword',  // Wrong case
+    'MySecretPassword ', // Trailing space
+    'WrongPassword'      // Completely wrong
+];
+
+console.log('Verification results:');
+for (var i = 0; i < testPasswords.length; i++) {
+    var testPwd = testPasswords[i];
+    var isValid = verifyPassword(testPwd, storedHash);
+    var status = isValid ? 'VALID' : 'INVALID';
+    console.log('  "' + testPwd + '" -> ' + status);
+}
+
+// ===========================================
+// HASH PROPERTIES
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Hash Properties:');
+console.log('='.repeat(50) + '\n');
+
+// Determinism
+console.log('1. Determinism (same input = same output):');
+var hash1 = backend.hash('test').toString('hex');
+var hash2 = backend.hash('test').toString('hex');
+console.log('   Hash 1: ' + hash1.substring(0, 32));
+console.log('   Hash 2: ' + hash2.substring(0, 32));
+console.log('   Equal: ' + (hash1 === hash2));
+
+// Avalanche effect
+console.log('\n2. Avalanche Effect (small change = big difference):');
+var similar1 = backend.hash('password').toString('hex');
+var similar2 = backend.hash('Password').toString('hex');
+var similar3 = backend.hash('password1').toString('hex');
+
+console.log('   "password"  -> ' + similar1.substring(0, 24));
+console.log('   "Password"  -> ' + similar2.substring(0, 24));
+console.log('   "password1" -> ' + similar3.substring(0, 24));
+
+// Count differing characters
+function countDiff(a, b) {
+    var diff = 0;
+    for (var i = 0; i < Math.min(a.length, b.length); i++) {
+        if (a[i] !== b[i]) diff++;
+    }
+    return diff;
+}
+
+console.log('   Difference (p vs P): ' + countDiff(similar1, similar2) + ' chars');
+console.log('   Difference (p vs p1): ' + countDiff(similar1, similar3) + ' chars');
+
+// ===========================================
+// CONFIGURABLE OUTPUT LENGTH
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Configurable Hash Length:');
+console.log('='.repeat(50) + '\n');
+
+var input = 'SampleInput';
+var lengths = [16, 32, 64, 128];
+
+for (var l = 0; l < lengths.length; l++) {
+    var len = lengths[l];
+    var hash = backend.hash(input, len);
+    console.log(len + ' bytes: ' + hash.toString('hex').substring(0, 40) + (len > 20 ? '...' : ''));
+}
+
+// ===========================================
+// TIMING ATTACK RESISTANCE
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Constant-Time Comparison:');
+console.log('='.repeat(50) + '\n');
+
+// Use constant-time comparison to prevent timing attacks
+function constantTimeCompare(a, b) {
+    if (a.length !== b.length) return false;
+    
+    var result = 0;
+    for (var i = 0; i < a.length; i++) {
+        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+}
+
+var storedHashStr = backend.hash('secret').toString('hex');
+var correctAttempt = backend.hash('secret').toString('hex');
+var wrongAttempt = backend.hash('wrong').toString('hex');
+
+console.log('Constant-time comparison prevents timing attacks:');
+console.log('  Correct password: ' + constantTimeCompare(storedHashStr, correctAttempt));
+console.log('  Wrong password:   ' + constantTimeCompare(storedHashStr, wrongAttempt));
+
+// ===========================================
+// SALT USAGE
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Using Salts:');
+console.log('='.repeat(50) + '\n');
+
+function hashWithSalt(password, salt) {
+    return backend.hash(salt + password);
+}
+
+function generateSalt() {
+    // In production, use crypto.randomBytes
+    var chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+    var salt = '';
+    for (var i = 0; i < 16; i++) {
+        salt += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return salt;
+}
+
+var password = 'CommonPassword';
+var salt1 = generateSalt();
+var salt2 = generateSalt();
+
+var salted1 = hashWithSalt(password, salt1).toString('hex');
+var salted2 = hashWithSalt(password, salt2).toString('hex');
+
+console.log('Same password with different salts:');
+console.log('  Salt 1: ' + salt1);
+console.log('  Hash 1: ' + salted1.substring(0, 32) + '...');
+console.log('  Salt 2: ' + salt2);
+console.log('  Hash 2: ' + salted2.substring(0, 32) + '...');
+console.log('  Different: ' + (salted1 !== salted2));
+
+// ===========================================
+// KEY TAKEAWAYS
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('KEY TAKEAWAYS:');
+console.log('1. Hash passwords before storing them');
+console.log('2. Use salts to prevent rainbow table attacks');
+console.log('3. Use constant-time comparison for security');
+console.log('4. Hashes are deterministic but one-way');
+console.log('5. Small input changes cause large hash changes');
+console.log('6. Configure output length based on security needs');