@aleph-ai/tinyaleph 1.5.7 → 1.6.0

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');

package/examples/crypto/02-key-derivation.js

@@ -0,0 +1,210 @@
+/**
+ * @example Key Derivation
+ * @description Derive cryptographic keys from passwords using TinyAleph
+ * 
+ * Key derivation functions (KDFs) create strong cryptographic keys from
+ * potentially weak passwords. TinyAleph's deriveKey function:
+ * - Uses salt to prevent rainbow table attacks
+ * - Supports configurable iterations for work factor
+ * - Produces keys of specified length
+ */
+
+const { CryptographicBackend } = require('../../modular');
+
+// ===========================================
+// SETUP
+// ===========================================
+
+const backend = new CryptographicBackend({ dimension: 32 });
+
+console.log('TinyAleph Key Derivation Example');
+console.log('=================================\n');
+
+// ===========================================
+// BASIC KEY DERIVATION
+// ===========================================
+
+console.log('Basic Key Derivation:');
+console.log('-'.repeat(50) + '\n');
+
+var password = 'MySecretPassword123';
+var salt = 'randomsalt12345678';
+var keyLength = 32;
+var iterations = 1000;
+
+console.log('Input:');
+console.log('  Password: ' + password);
+console.log('  Salt: ' + salt);
+console.log('  Key Length: ' + keyLength + ' bytes');
+console.log('  Iterations: ' + iterations);
+
+var derivedKey = backend.deriveKey(password, salt, keyLength, iterations);
+console.log('\nDerived Key (hex): ' + derivedKey.toString('hex'));
+
+// ===========================================
+// SALT IMPORTANCE
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Salt Importance:');
+console.log('='.repeat(50) + '\n');
+
+console.log('Same password with different salts produces different keys:\n');
+
+var salts = ['salt_user_1', 'salt_user_2', 'salt_user_3'];
+
+for (var i = 0; i < salts.length; i++) {
+    var s = salts[i];
+    var key = backend.deriveKey(password, s, 32, 1000);
+    console.log('  Salt: "' + s + '"');
+    console.log('  Key:  ' + key.toString('hex').substring(0, 40) + '...\n');
+}
+
+// ===========================================
+// ITERATION COUNT
+// ===========================================
+
+console.log('='.repeat(50));
+console.log('Iteration Count (Work Factor):');
+console.log('='.repeat(50) + '\n');
+
+console.log('Higher iterations = more secure but slower:\n');
+
+var iterCounts = [100, 1000, 10000];
+
+for (var i = 0; i < iterCounts.length; i++) {
+    var count = iterCounts[i];
+    var start = Date.now();
+    var key = backend.deriveKey(password, salt, 32, count);
+    var elapsed = Date.now() - start;
+    
+    console.log('  Iterations: ' + count);
+    console.log('  Time: ' + elapsed + 'ms');
+    console.log('  Key: ' + key.toString('hex').substring(0, 32) + '...\n');
+}
+
+// ===========================================
+// KEY LENGTH VARIATIONS
+// ===========================================
+
+console.log('='.repeat(50));
+console.log('Variable Key Lengths:');
+console.log('='.repeat(50) + '\n');
+
+console.log('Derive keys of different lengths for different purposes:\n');
+
+var keyPurposes = [
+    { name: 'AES-128', length: 16 },
+    { name: 'AES-256', length: 32 },
+    { name: 'HMAC-SHA256', length: 32 },
+    { name: 'ChaCha20', length: 32 }
+];
+
+for (var i = 0; i < keyPurposes.length; i++) {
+    var purpose = keyPurposes[i];
+    var key = backend.deriveKey(password, salt, purpose.length, 1000);
+    console.log('  ' + purpose.name + ' (' + purpose.length + ' bytes):');
+    console.log('  ' + key.toString('hex'));
+    console.log('');
+}
+
+// ===========================================
+// MULTIPLE KEYS FROM ONE PASSWORD
+// ===========================================
+
+console.log('='.repeat(50));
+console.log('Deriving Multiple Keys:');
+console.log('='.repeat(50) + '\n');
+
+console.log('Use different salts or purposes to derive multiple keys:\n');
+
+function deriveMultipleKeys(password, masterSalt, keySpecs) {
+    var keys = {};
+    for (var i = 0; i < keySpecs.length; i++) {
+        var spec = keySpecs[i];
+        var specificSalt = masterSalt + ':' + spec.purpose;
+        keys[spec.purpose] = backend.deriveKey(password, specificSalt, spec.length, 1000);
+    }
+    return keys;
+}
+
+var keySpecs = [
+    { purpose: 'encryption', length: 32 },
+    { purpose: 'authentication', length: 32 },
+    { purpose: 'signing', length: 64 }
+];
+
+var keys = deriveMultipleKeys(password, 'master_salt', keySpecs);
+
+for (var purpose in keys) {
+    if (keys.hasOwnProperty(purpose)) {
+        console.log('  ' + purpose + ': ' + keys[purpose].toString('hex').substring(0, 40) + '...');
+    }
+}
+
+// ===========================================
+// PASSWORD STRENGTH
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Password Strength Consideration:');
+console.log('='.repeat(50) + '\n');
+
+console.log('Even with KDF, use strong passwords:\n');
+
+var testPasswords = [
+    { pwd: '123456', strength: 'Very Weak' },
+    { pwd: 'password', strength: 'Weak' },
+    { pwd: 'MyP@ss!', strength: 'Medium' },
+    { pwd: 'Tr0ub4dor&3', strength: 'Strong' },
+    { pwd: 'correct-horse-battery-staple', strength: 'Very Strong' }
+];
+
+for (var i = 0; i < testPasswords.length; i++) {
+    var test = testPasswords[i];
+    var key = backend.deriveKey(test.pwd, salt, 32, 1000);
+    console.log('  "' + test.pwd + '" (' + test.strength + ')');
+    console.log('  Key: ' + key.toString('hex').substring(0, 32) + '...\n');
+}
+
+// ===========================================
+// KEY VERIFICATION
+// ===========================================
+
+console.log('='.repeat(50));
+console.log('Key Verification:');
+console.log('='.repeat(50) + '\n');
+
+console.log('Store salt and verify derived key matches:\n');
+
+// "Store" the salt and a verification hash
+var storedSalt = 'user_specific_salt_123';
+var masterPassword = 'UserMasterPassword';
+var storedVerifier = backend.deriveKey(masterPassword, storedSalt + ':verify', 16, 1000);
+
+console.log('Stored Salt: ' + storedSalt);
+console.log('Stored Verifier: ' + storedVerifier.toString('hex') + '\n');
+
+// Attempt verification
+var attempts = ['UserMasterPassword', 'WrongPassword', 'usermasterpassword'];
+
+for (var i = 0; i < attempts.length; i++) {
+    var attempt = attempts[i];
+    var computedVerifier = backend.deriveKey(attempt, storedSalt + ':verify', 16, 1000);
+    var isValid = computedVerifier.toString('hex') === storedVerifier.toString('hex');
+    
+    console.log('  "' + attempt + '" -> ' + (isValid ? 'VALID' : 'INVALID'));
+}
+
+// ===========================================
+// KEY TAKEAWAYS
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('KEY TAKEAWAYS:');
+console.log('1. Always use a unique salt per user/purpose');
+console.log('2. Increase iterations for stronger security');
+console.log('3. Derive multiple keys using different salts');
+console.log('4. Higher iterations = more time = harder to brute force');
+console.log('5. Key derivation cannot fix weak passwords');
+console.log('6. Store salt with derived key (salt is not secret)');