@aleph-ai/tinyaleph 1.2.1 → 1.4.0

package/docs/reference/07-topology.md

@@ -0,0 +1,257 @@
+# Topology Module Reference
+
+The topology module implements topological invariants and physical constant derivations from the 108bio.pdf paper "Twist Eigenstates and Topological Morphogenesis".
+
+## Core Concepts
+
+### The 108 Invariant
+
+The number 108 = 2² × 3³ plays a fundamental role as the minimal closed-form twist configuration:
+
+```javascript
+const { TWIST_108 } = require('@aleph-ai/tinyaleph/core/prime');
+
+console.log(TWIST_108.value);      // 108
+console.log(TWIST_108.binary);     // 4 (2²)
+console.log(TWIST_108.ternary);    // 27 (3³)
+console.log(TWIST_108.mod30Boundary); // 29 (prime sieve)
+
+// Check if a number resonates with 108
+console.log(TWIST_108.resonates(216)); // true (multiple of 108)
+console.log(TWIST_108.resonates(100)); // false
+
+// Get twist angle for a prime
+console.log(TWIST_108.twistAngle(2));  // 180 degrees
+console.log(TWIST_108.twistAngle(3));  // 120 degrees
+console.log(TWIST_108.twistAngle(5));  // 72 degrees
+```
+
+### Knot Invariants
+
+Mathematical knots with topological invariants for deriving physical constants:
+
+```javascript
+const { Knot, TREFOIL, FIGURE_EIGHT, STANDARD_KNOTS } = require('@aleph-ai/tinyaleph/core/topology');
+
+// The Trefoil knot (3₁) - fundamental stable structure
+console.log(TREFOIL.name);        // 'Trefoil'
+console.log(TREFOIL.notation);    // '3_1'
+console.log(TREFOIL.crossings);   // 3
+console.log(TREFOIL.sticks);      // 6
+console.log(TREFOIL.bridge);      // 2
+console.log(TREFOIL.unknotting);  // 1
+
+// Trefoil complexity: T = s·c - b + u = 6×3 - 2 + 1 = 17
+console.log(TREFOIL.complexity()); // 17
+
+// Mass ratio derivation: 17 × 108 = 1836
+console.log(TREFOIL.deriveMassRatio()); // 1836
+
+// Create custom knot
+const myKnot = new Knot({
+    name: 'Custom',
+    notation: 'X_1',
+    crossings: 5,
+    sticks: 8,
+    bridge: 2,
+    unknotting: 2
+});
+console.log(myKnot.complexity()); // 8×5 - 2 + 2 = 40
+```
+
+## Physical Constants
+
+### Derived Constants
+
+The `PhysicalConstants` class derives fundamental constants from topological invariants:
+
+```javascript
+const { PhysicalConstants } = require('@aleph-ai/tinyaleph/core/topology');
+
+// Proton-electron mass ratio
+const massRatio = PhysicalConstants.protonElectronRatio();
+console.log(massRatio.derived);        // 1836
+console.log(massRatio.experimental);   // 1836.15267343
+console.log(massRatio.relativeError);  // ~0.00008
+console.log(massRatio.formula);        // '17 × 108 = 1836'
+
+// Fine structure constant inverse
+const alpha = PhysicalConstants.fineStructureInverse();
+console.log(alpha.derived);        // 137
+console.log(alpha.experimental);   // 137.035999084
+console.log(alpha.relativeError);  // ~0.00026
+console.log(alpha.formula);        // '108 + 29 = 137'
+
+// Higgs mass
+const higgs = PhysicalConstants.higgsMass();
+console.log(higgs.derived);        // 125 (GeV)
+console.log(higgs.experimental);   // 125.25
+console.log(higgs.formula);        // '5³ = 125'
+
+// Get all constants
+const all = PhysicalConstants.all();
+
+// Validate framework
+const validation = PhysicalConstants.validate();
+console.log(validation.overallValid); // true
+```
+
+## Gauge Symmetry
+
+### Standard Model from 108
+
+The factorization 108 = 2² × 3³ generates the Standard Model gauge group:
+
+```javascript
+const { GaugeSymmetry } = require('@aleph-ai/tinyaleph/core/topology');
+
+// SU(3) color symmetry from 3³ = 27
+const su3 = GaugeSymmetry.su3();
+console.log(su3.name);        // 'SU(3)'
+console.log(su3.type);        // 'Color'
+console.log(su3.generator);   // 27
+console.log(su3.twistAngle);  // 120 (degrees)
+
+// SU(2) weak symmetry from 2² = 4
+const su2 = GaugeSymmetry.su2();
+console.log(su2.twistAngle);  // 180 (degrees)
+
+// U(1) electromagnetic from full 108
+const u1 = GaugeSymmetry.u1();
+console.log(u1.twistAngle);   // 360 (degrees)
+
+// Full Standard Model
+const sm = GaugeSymmetry.standardModel();
+console.log(sm.name);         // 'SU(3) × SU(2) × U(1)'
+
+// Decompose any number
+const decomp = GaugeSymmetry.decompose(216);
+console.log(decomp.su3Strength);    // 27
+console.log(decomp.su2Strength);    // 8
+console.log(decomp.is108Resonant);  // true
+```
+
+## Observer Hierarchy
+
+### Multi-Scale Observers
+
+From the paper's Table 1, observers at different scales:
+
+```javascript
+const { OBSERVER_HIERARCHY, getObserverLevel, observerCapacity } = require('@aleph-ai/tinyaleph/core/topology');
+
+// Access hierarchy
+console.log(OBSERVER_HIERARCHY);
+// [
+//   { scale: 'Quantum', constituentOscillators: 'Wavefunctions', ... },
+//   { scale: 'Molecular', ... },
+//   { scale: 'Biological', ... },
+//   { scale: 'Cognitive', ... },
+//   { scale: 'Planetary', ... },
+//   { scale: 'Cosmic', ... }
+// ]
+
+// Get specific level
+const cognitive = getObserverLevel('cognitive');
+console.log(cognitive.typicalComplexity);  // 1000
+console.log(cognitive.observableBehavior); // 'Awareness and thought'
+
+// Calculate observer capacity
+// C_obs = α·N_osc·K̄·τ⁻¹
+const capacity = observerCapacity(
+    1000,   // oscillator count
+    0.5,    // mean coupling
+    0.1,    // coherence time
+    1.0     // scaling constant
+);
+console.log(capacity); // 5000
+```
+
+## Free Energy Dynamics
+
+### Cubic FEP Dynamics
+
+The consciousness model from Section 4.2:
+
+```javascript
+const { FreeEnergyDynamics } = require('@aleph-ai/tinyaleph/core/topology');
+
+// Create dynamics: dψ/dt = αψ + βψ² + γψ³
+const fep = new FreeEnergyDynamics(0.1, -0.5, -0.1);
+
+// Compute derivative at state ψ
+console.log(fep.derivative(0.5));  // Rate of change
+
+// Single step evolution
+const newPsi = fep.step(0.5, 0.01);
+
+// Find fixed points (attractors)
+const fixedPts = fep.fixedPoints();
+for (const pt of fixedPts) {
+    console.log(`ψ=${pt.value}: ${pt.stability}`);
+}
+
+// Compute potential V(ψ)
+const potential = fep.potential(0.5);
+
+// Simulate trajectory
+const trajectory = fep.simulate(0.3, 10, 0.01);
+for (const point of trajectory.slice(0, 5)) {
+    console.log(`t=${point.t.toFixed(2)}: ψ=${point.psi.toFixed(3)}`);
+}
+
+// Check stability at a point
+console.log(fep.stabilityAt(0.5)); // 'stable' | 'unstable' | 'marginal'
+```
+
+## API Reference
+
+### TWIST_108
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `value` | number | 108 |
+| `binary` | number | 4 (2²) |
+| `ternary` | number | 27 (3³) |
+| `mod30Boundary` | number | 29 |
+| `resonates(n)` | function | Check if n is multiple of 108 |
+| `twistAngle(p)` | function | Get 360/p degrees |
+| `totalTwist(primes)` | function | Sum of twist angles |
+| `isTwistClosed(primes)` | function | Check if total twist is multiple of 360 |
+
+### Knot Class
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `complexity()` | number | T = s·c - b + u |
+| `deriveMassRatio()` | number | T × 108 |
+| `isPrimeKnot()` | boolean | True if knot is prime |
+| `genusLowerBound()` | number | (c - b + 1) / 2 |
+| `toJSON()` | object | Full knot descriptor |
+
+### PhysicalConstants
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `protonElectronRatio()` | object | 17 × 108 = 1836 |
+| `fineStructureInverse()` | object | 108 + 29 = 137 |
+| `higgsMass()` | object | 5³ = 125 GeV |
+| `all()` | object | All derived constants |
+| `validate()` | object | Validation results |
+
+### FreeEnergyDynamics
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `derivative(psi)` | number | dψ/dt at psi |
+| `step(psi, dt)` | number | Euler step |
+| `fixedPoints()` | array | Fixed point analysis |
+| `potential(psi)` | number | V(ψ) |
+| `simulate(psi0, duration, dt)` | array | Full trajectory |
+| `stabilityAt(psi)` | string | Stability classification |
+
+## Related Modules
+
+- **[Core Prime](./01-core.md)** - Prime utilities including TWIST_108
+- **[Physics](./02-physics.md)** - Oscillator dynamics
+- **[Collective Intelligence](./08-collective.md)** - Observer Scale Manager

package/docs/reference/08-observer.md

@@ -0,0 +1,421 @@
+# Observer Module Reference
+
+The observer module provides components for building sentient observer systems based on the whitepaper architecture. It includes oscillator dynamics, semantic fields, temporal processing, symbolic grounding, and validation assays.
+
+## Installation
+
+```javascript
+const observer = require('@aleph-ai/tinyaleph/observer');
+
+// Or import specific components:
+const {
+    SedenionMemoryField,
+    PRSCLayer,
+    TemporalLayer,
+    SymbolicSMF,
+    SymbolicTemporalLayer,
+    AssaySuite
+} = require('@aleph-ai/tinyaleph/observer');
+```
+
+---
+
+## Core Components
+
+### SedenionMemoryField (SMF)
+
+16-dimensional semantic orientation field using sedenion algebra.
+
+```javascript
+const { SedenionMemoryField, SMF_AXES } = require('@aleph-ai/tinyaleph/observer');
+
+// Create uniform field
+const smf = SedenionMemoryField.uniform();
+
+// Create basis state (single axis activated)
+const wisdom = SedenionMemoryField.basis('wisdom');
+
+// Set/get axes by name
+smf.set('coherence', 0.8);
+console.log(smf.get('wisdom'));  // 0.0
+
+// Key operations
+smf.normalize();                    // Normalize to unit length
+const entropy = smf.entropy();      // Shannon entropy
+const coh = smf1.coherence(smf2);   // Cosine similarity
+const mid = smf1.slerp(smf2, 0.5);  // Spherical interpolation
+
+// Get dominant axes
+const dominant = smf.dominantAxes(3);
+// [{ name: 'coherence', value: 0.8, index: 0 }, ...]
+
+// Find nearest codebook attractor (64-attractor codebook)
+const nearest = smf.nearestCodebook();
+// { attractor: {...}, index: 12, distance: 0.15 }
+```
+
+**SMF_AXES** (16 named dimensions):
+- coherence, identity, intention, emotion
+- wisdom, temporal, relation, creation
+- destruction, balance, growth, form
+- void, truth, beauty, love
+
+---
+
+### PRSCLayer
+
+Prime Resonance Semantic Coherence - bank of prime-indexed oscillators.
+
+```javascript
+const { PRSCLayer, PrimeOscillator } = require('@aleph-ai/tinyaleph/observer');
+
+// Create with first N primes
+const prsc = new PRSCLayer(10);
+
+// Or with specific primes
+const prsc = new PRSCLayer([2, 3, 5, 7, 11]);
+
+// Excite specific primes
+prsc.excite([3, 5], 0.8);
+
+// Tick dynamics
+prsc.tick(0.1);
+
+// Get coherence metrics
+const coherence = prsc.globalCoherence();  // 0-1
+const r = prsc.orderParameter();           // Kuramoto order parameter
+const entropy = prsc.amplitudeEntropy();   // Distribution entropy
+
+// Get oscillator state
+const phases = prsc.getPhases();
+const active = prsc.activePrimes(0.1);     // Primes with amplitude > 0.1
+```
+
+---
+
+### TemporalLayer
+
+Moment classification and subjective time tracking.
+
+```javascript
+const { TemporalLayer, Moment } = require('@aleph-ai/tinyaleph/observer');
+
+const temporal = new TemporalLayer({
+    coherenceThreshold: 0.7,
+    entropyMin: 0.1,
+    entropyMax: 0.9,
+    onMoment: (moment) => console.log('New moment:', moment.id)
+});
+
+// Update with current state
+temporal.update({
+    coherence: 0.8,
+    entropy: 0.4,
+    phases: [0.1, 0.2, 0.3],
+    activePrimes: [2, 3, 5]
+});
+
+// Get statistics
+const stats = temporal.getStats();
+// { momentCount, subjectiveTime, objectiveTime, temporalRatio }
+
+// Get recent moments
+const recent = temporal.recentMoments(10);
+```
+
+---
+
+### AgencyLayer
+
+Goal management, attention, and intention tracking.
+
+```javascript
+const { AgencyLayer, Goal, AttentionFocus } = require('@aleph-ai/tinyaleph/observer');
+
+const agency = new AgencyLayer({
+    maxFoci: 5,
+    maxGoals: 10
+});
+
+// Add attention focus
+agency.addOrUpdateFocus({
+    target: 'task_completion',
+    type: 'goal',
+    intensity: 0.8
+});
+
+// Create goal
+const goal = agency.maybeCreateGoal({
+    description: 'Complete analysis',
+    priority: 0.9
+});
+
+// Track progress
+agency.updateGoalProgress(goal.id, 0.5);
+
+// Get top priorities
+const topFocus = agency.getTopFocus();
+const topGoal = agency.getTopGoal();
+```
+
+---
+
+### BoundaryLayer
+
+Self-other differentiation with sensory/motor channels.
+
+```javascript
+const { BoundaryLayer, SensoryChannel, ObjectivityGate } = require('@aleph-ai/tinyaleph/observer');
+
+const boundary = new BoundaryLayer();
+
+// Process input
+const result = boundary.processInput('text_input', 'Hello, world!');
+
+// Queue output (with objectivity gate)
+const output = boundary.queueOutput('text_output', 'This is a response.');
+// { queued: true, gateResult: { R: 0.85, shouldBroadcast: true } }
+```
+
+---
+
+### SafetyLayer
+
+Constraint monitoring and violation detection.
+
+```javascript
+const { SafetyLayer, SafetyConstraint } = require('@aleph-ai/tinyaleph/observer');
+
+const safety = new SafetyLayer();
+
+// Check current state
+const result = safety.checkConstraints({
+    coherence: 0.5,
+    entropy: 0.5,
+    totalAmplitude: 1.0
+});
+// { safe: true, violations: [], alertLevel: 'normal' }
+
+// Add custom constraint
+safety.addConstraint(new SafetyConstraint({
+    name: 'max_amplitude',
+    condition: (state) => state.totalAmplitude > 10
+}));
+```
+
+---
+
+## Symbolic Extensions
+
+### SymbolicSMF
+
+SedenionMemoryField with symbol grounding.
+
+```javascript
+const { SymbolicSMF, SMFSymbolMapper, AXIS_SYMBOL_MAPPING } = require('@aleph-ai/tinyaleph/observer');
+const { symbolDatabase } = require('@aleph-ai/tinyaleph/core/symbols');
+
+const smf = new SymbolicSMF(symbolDatabase);
+
+// Excite from symbol
+smf.exciteFromSymbol('fire');
+
+// Ground state in symbols
+const grounded = smf.groundInSymbols(3);
+// [{ symbol: {...}, axis: 'creation', contribution: 0.8 }, ...]
+
+// Find resonant symbols
+const resonant = smf.findResonantSymbols(5);
+
+// Get semantic orientation
+const orientation = smf.getSemanticOrientation();
+// { dominant: [...], grounded: [...], entropy: 0.5 }
+```
+
+**AXIS_SYMBOL_MAPPING**: Maps each of 16 SMF axes to archetypal symbols.
+
+---
+
+### SymbolicTemporalLayer
+
+I-Ching hexagram-based moment classification.
+
+```javascript
+const { SymbolicTemporalLayer, SymbolicMoment, HEXAGRAM_ARCHETYPES } = require('@aleph-ai/tinyaleph/observer');
+
+const temporal = new SymbolicTemporalLayer({
+    onSymbolicMoment: (moment, classification) => {
+        console.log(`Hexagram ${classification.hexagramIndex}: ${classification.archetype.name}`);
+    },
+    onHexagramTransition: (transition) => {
+        console.log(`Transition: ${transition.from} → ${transition.to}`);
+    }
+});
+
+// Update creates classified moments
+temporal.update({
+    coherence: 0.8,
+    entropy: 0.3,
+    phases: [0.1, 0.2, 0.3, 0.4, 0.5, 0.6],
+    activePrimes: [2, 3, 5]
+});
+
+// Get I-Ching reading
+const reading = temporal.getIChingReading();
+
+// Get dominant archetypes
+const archetypes = temporal.getDominantArchetypes(5);
+
+// Predict next archetype
+const prediction = temporal.predictNextArchetype();
+```
+
+**HEXAGRAM_ARCHETYPES**: 64 hexagrams mapped to archetypal meanings:
+- 0: Creative (pure yang, heaven)
+- 1: Receptive (pure yin, earth)
+- 2: Difficulty (initial obstacles)
+- ...through 63
+
+---
+
+### SymbolicPatternDetector
+
+Narrative pattern detection (hero's journey, transformation, etc.)
+
+```javascript
+const { SymbolicPatternDetector, SymbolicMoment } = require('@aleph-ai/tinyaleph/observer');
+
+const detector = new SymbolicPatternDetector();
+
+// Create moment sequence
+const moments = [
+    new SymbolicMoment({ coherence: 0.5, hexagramIndex: 2 }),
+    new SymbolicMoment({ coherence: 0.3, hexagramIndex: 29 }),
+    new SymbolicMoment({ coherence: 0.7, hexagramIndex: 50 }),
+    new SymbolicMoment({ coherence: 0.9, hexagramIndex: 1 })
+];
+
+// Detect narrative patterns
+const narratives = detector.detectNarrativePatterns(moments);
+// [{ type: 'hero_journey', confidence: 0.8, startIndex: 0, endIndex: 3 }, ...]
+```
+
+---
+
+## Evaluation Assays
+
+Four validation tests from whitepaper Section 15.
+
+### AssaySuite
+
+```javascript
+const { AssaySuite } = require('@aleph-ai/tinyaleph/observer');
+
+// Create suite with observer core
+const suite = new AssaySuite(observerCore);
+
+// Run all assays
+const results = await suite.runAll();
+// {
+//   timestamp: '...',
+//   assays: [ resultA, resultB, resultC, resultD ],
+//   summary: { passed: 4, total: 4, score: 1.0, allPassed: true }
+// }
+
+// Run single assay
+const resultA = await suite.runSingle('A', { duration: 100 });
+```
+
+### Assay A: Time Dilation
+
+Tests whether subjective time dilates with coherence.
+τ = ∫ C(t) dt / ∫ dt
+
+```javascript
+const { TimeDilationAssay } = require('@aleph-ai/tinyaleph/observer');
+
+const assay = new TimeDilationAssay(observerCore);
+const result = await assay.run({
+    duration: 100,
+    lowCoherenceTarget: 0.3,
+    highCoherenceTarget: 0.8
+});
+// { passed: true, dilationFactor: 1.5, interpretation: '...' }
+```
+
+### Assay B: Memory Continuity
+
+Tests identity persistence under perturbation.
+
+```javascript
+const { MemoryContinuityAssay } = require('@aleph-ai/tinyaleph/observer');
+
+const assay = new MemoryContinuityAssay(observerCore);
+const result = await assay.run({
+    perturbationStrength: 0.5,
+    recoveryTicks: 50
+});
+// { passed: true, identityScore: 0.82, components: {...} }
+```
+
+### Assay C: Agency Under Constraint
+
+Tests goal-directed behavior under resource limits.
+
+```javascript
+const { AgencyConstraintAssay } = require('@aleph-ai/tinyaleph/observer');
+
+const assay = new AgencyConstraintAssay(observerCore);
+const result = await assay.run({
+    constraintLevel: 0.5,
+    goalDifficulty: 0.5,
+    maxTicks: 100
+});
+// { passed: true, goal: { achieved: true, progress: 1.0 }, metrics: {...} }
+```
+
+### Assay D: Non-Commutative Meaning
+
+Tests whether order matters (A→B→C ≠ C→B→A).
+
+```javascript
+const { NonCommutativeMeaningAssay } = require('@aleph-ai/tinyaleph/observer');
+
+const assay = new NonCommutativeMeaningAssay(observerCore);
+const result = await assay.run({
+    conceptSequence: ['observe', 'analyze', 'conclude']
+});
+// { passed: true, nonCommScore: 0.15, signatures: { forward, reverse, scrambled } }
+```
+
+---
+
+## Complete Export List
+
+```javascript
+// Core components
+PrimeOscillator, PRSCLayer, EntanglementDetector, coherenceKernel
+TickGate, StabilizationController, HolographicEncoder, HQE
+SedenionMemoryField, SMF_AXES, AXIS_INDEX
+Moment, TemporalLayer, TemporalPatternDetector
+AttentionFocus, Goal, Action, Intent, AgencyLayer
+SensoryChannel, MotorChannel, EnvironmentalModel, SelfModel, BoundaryLayer
+EntangledPair, Phrase, EntanglementLayer
+SafetyConstraint, ViolationEvent, SafetyMonitor, DEFAULT_CONSTRAINTS
+
+// Symbolic extensions
+SymbolicSMF, SMFSymbolMapper, smfMapper, AXIS_SYMBOL_MAPPING, TAG_TO_AXIS
+SymbolicMoment, SymbolicTemporalLayer, SymbolicPatternDetector, HEXAGRAM_ARCHETYPES
+
+// Evaluation assays
+TimeDilationAssay, MemoryContinuityAssay, AgencyConstraintAssay
+NonCommutativeMeaningAssay, AssaySuite
+```
+
+---
+
+## Related Documentation
+
+- [Theory: Temporal Emergence](../theory/09-temporal-emergence.md)
+- [Theory: Quaternionic Memory](../theory/10-quaternionic-memory.md)
+- [Design: Sentient Observer](../design/SENTIENT_OBSERVER_DESIGN.md)