Squashed 'vendor/ruvector/' content from commit b64c2172
git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
This commit is contained in:
ruv
418
examples/delta-behavior/wasm/README.md
Normal file
418
examples/delta-behavior/wasm/README.md
Normal file
@@ -0,0 +1,418 @@
|
||||
# Delta-Behavior WASM SDK
|
||||
|
||||
A TypeScript/JavaScript SDK for coherence-preserving state transitions and self-limiting AI systems.
|
||||
|
||||
## Overview
|
||||
|
||||
The Delta-Behavior SDK provides implementations of 10 "exotic" mathematical properties that enable AI systems to be self-limiting, bounded, and safe by construction. Based on the research paper "Delta-Behavior: A Mathematical Framework for Coherence-Preserving State Transitions."
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install @ruvector/delta-behavior
|
||||
```
|
||||
|
||||
Or with yarn:
|
||||
|
||||
```bash
|
||||
yarn add @ruvector/delta-behavior
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```typescript
|
||||
import { init, DeltaBehavior, ContainmentSubstrate } from '@ruvector/delta-behavior';
|
||||
|
||||
// Initialize the SDK (optional WASM for performance)
|
||||
await init();
|
||||
|
||||
// Core delta behavior system
|
||||
const delta = new DeltaBehavior();
|
||||
|
||||
// Check if a transition is allowed
|
||||
const result = delta.checkTransition(1.0, 0.8);
|
||||
// => { type: 'allowed' }
|
||||
|
||||
// Pre-AGI containment substrate
|
||||
const substrate = new ContainmentSubstrate();
|
||||
const growth = substrate.attemptGrowth('reasoning', 0.5);
|
||||
// Growth is bounded by coherence requirements
|
||||
```
|
||||
|
||||
## Applications
|
||||
|
||||
The SDK implements 10 applications, each demonstrating a different "exotic" property:
|
||||
|
||||
### 1. Self-Limiting Reasoning
|
||||
|
||||
A reasoning system that automatically limits its depth and scope based on coherence.
|
||||
|
||||
```typescript
|
||||
import { SelfLimitingReasoner } from '@ruvector/delta-behavior';
|
||||
|
||||
const reasoner = new SelfLimitingReasoner({
|
||||
maxDepth: 10,
|
||||
maxScope: 100,
|
||||
depthCollapse: { type: 'quadratic' },
|
||||
});
|
||||
|
||||
// Reasoning depth collapses as coherence drops
|
||||
console.log(reasoner.getAllowedDepth()); // 10 at full coherence
|
||||
|
||||
reasoner.updateCoherence(-0.5);
|
||||
console.log(reasoner.getAllowedDepth()); // ~2 at 50% coherence
|
||||
|
||||
// Attempt reasoning that requires 8 steps
|
||||
const result = reasoner.reason('complex problem', (ctx) => {
|
||||
if (ctx.depth >= 8) return 'SOLUTION';
|
||||
return null;
|
||||
});
|
||||
// result.type may be 'collapsed' if coherence is too low
|
||||
```
|
||||
|
||||
### 2. Computational Event Horizons
|
||||
|
||||
Define boundaries in state space that cannot be crossed.
|
||||
|
||||
```typescript
|
||||
import { EventHorizon } from '@ruvector/delta-behavior';
|
||||
|
||||
const horizon = new EventHorizon({
|
||||
dimensions: 2,
|
||||
horizonRadius: 10,
|
||||
energyBudget: 1000,
|
||||
});
|
||||
|
||||
// Try to move to the edge
|
||||
const result = horizon.moveToward([10, 0]);
|
||||
// result.type === 'asymptoticApproach'
|
||||
// Cannot cross the horizon - approaches asymptotically
|
||||
|
||||
// Recursive self-improvement is bounded
|
||||
const improvement = horizon.recursiveImprove(
|
||||
(pos) => pos.map(p => p + 0.5), // Always try to go further
|
||||
1000 // Max iterations
|
||||
);
|
||||
// improvement.type === 'horizonBounded'
|
||||
// System finds its own stopping point
|
||||
```
|
||||
|
||||
### 3. Artificial Homeostasis
|
||||
|
||||
Organisms with coherence-enforced internal regulation.
|
||||
|
||||
```typescript
|
||||
import { HomeostasticOrganism } from '@ruvector/delta-behavior';
|
||||
|
||||
const genome = HomeostasticOrganism.randomGenome();
|
||||
const organism = new HomeostasticOrganism(1, genome);
|
||||
|
||||
// Actions cost more energy when coherence is low
|
||||
organism.act({ type: 'eat', amount: 20 });
|
||||
organism.act({ type: 'regulate', variable: 'temperature', target: 37 });
|
||||
organism.act({ type: 'rest' });
|
||||
|
||||
// Memory is lost under uncertainty (low coherence)
|
||||
// Organism naturally maintains homeostasis or dies trying
|
||||
```
|
||||
|
||||
### 4. Self-Stabilizing World Models
|
||||
|
||||
World models that refuse to learn incoherent updates.
|
||||
|
||||
```typescript
|
||||
import { SelfStabilizingWorldModel } from '@ruvector/delta-behavior';
|
||||
|
||||
const model = new SelfStabilizingWorldModel();
|
||||
|
||||
// Feed observations
|
||||
const result = model.observe({
|
||||
entityId: BigInt(1),
|
||||
properties: new Map([['temperature', { type: 'number', value: 20 }]]),
|
||||
position: [0, 0, 0],
|
||||
timestamp: 0,
|
||||
sourceConfidence: 0.9,
|
||||
}, 0);
|
||||
|
||||
// Model rejects updates that would make the world incoherent
|
||||
// Instead of hallucinating structure, it freezes learning
|
||||
```
|
||||
|
||||
### 5. Coherence-Bounded Creativity
|
||||
|
||||
Creative generation within coherence-preserving manifolds.
|
||||
|
||||
```typescript
|
||||
import { CoherenceBoundedCreator } from '@ruvector/delta-behavior';
|
||||
|
||||
const creator = new CoherenceBoundedCreator(
|
||||
{ values: [0, 0, 0] }, // Initial element
|
||||
0.6, // Min coherence
|
||||
0.95 // Max coherence (too high = boring)
|
||||
);
|
||||
|
||||
creator.addConstraint({
|
||||
name: 'magnitude',
|
||||
satisfaction: (elem) => Math.max(0, 1 - magnitude(elem) / 10),
|
||||
isHard: false,
|
||||
});
|
||||
|
||||
const result = creator.create(varyFn, distanceFn, 0.5);
|
||||
// Novelty without collapse, exploration without nonsense
|
||||
```
|
||||
|
||||
### 6. Anti-Cascade Financial System
|
||||
|
||||
Financial systems that cannot cascade into collapse by construction.
|
||||
|
||||
```typescript
|
||||
import { AntiCascadeFinancialSystem } from '@ruvector/delta-behavior';
|
||||
|
||||
const system = new AntiCascadeFinancialSystem();
|
||||
system.addParticipant('bank_a', 1000);
|
||||
system.addParticipant('bank_b', 1000);
|
||||
|
||||
// Transactions that would reduce coherence are blocked
|
||||
const result = system.processTransaction({
|
||||
id: BigInt(1),
|
||||
from: 'bank_a',
|
||||
to: 'bank_b',
|
||||
amount: 100,
|
||||
transactionType: { type: 'openLeverage', leverage: 10 },
|
||||
timestamp: 0,
|
||||
});
|
||||
// result.type may be 'rejected' if it threatens coherence
|
||||
|
||||
// Circuit breaker activates automatically
|
||||
console.log(system.getCircuitBreakerState()); // 'open' | 'cautious' | 'restricted' | 'halted'
|
||||
```
|
||||
|
||||
### 7. Gracefully Aging Systems
|
||||
|
||||
Distributed systems that become simpler and more reliable with age.
|
||||
|
||||
```typescript
|
||||
import { GracefullyAgingSystem } from '@ruvector/delta-behavior';
|
||||
|
||||
const system = new GracefullyAgingSystem();
|
||||
system.addNode('primary', true);
|
||||
|
||||
// As the system ages, capabilities are gracefully removed
|
||||
system.simulateAge(600000); // 10 minutes
|
||||
|
||||
console.log(system.hasCapability('schemaMigration')); // false
|
||||
console.log(system.hasCapability('basicReads')); // true (always available)
|
||||
|
||||
// Operations become more conservative over time
|
||||
const result = system.attemptOperation({ type: 'write', key: 'test', value: new Uint8Array() });
|
||||
// Latency penalty increases with age
|
||||
```
|
||||
|
||||
### 8. Coherent Swarm Intelligence
|
||||
|
||||
Swarms where local actions are allowed but global incoherence is forbidden.
|
||||
|
||||
```typescript
|
||||
import { CoherentSwarm } from '@ruvector/delta-behavior';
|
||||
|
||||
const swarm = new CoherentSwarm(0.6); // Min coherence threshold
|
||||
|
||||
swarm.addAgent('a1', [0, 0]);
|
||||
swarm.addAgent('a2', [1, 0]);
|
||||
swarm.addAgent('a3', [0, 1]);
|
||||
|
||||
// Divergent actions are rejected or modified
|
||||
const result = swarm.executeAction('a1', { type: 'move', dx: 80, dy: 80 });
|
||||
// result.type === 'rejected' - would break swarm coherence
|
||||
|
||||
// Emergent intelligence that cannot emerge pathological behaviors
|
||||
```
|
||||
|
||||
### 9. Graceful Shutdown
|
||||
|
||||
Systems that actively move toward safe termination when unstable.
|
||||
|
||||
```typescript
|
||||
import { GracefulSystem } from '@ruvector/delta-behavior';
|
||||
|
||||
const system = new GracefulSystem();
|
||||
system.addResource('database', 10);
|
||||
system.addShutdownHook({
|
||||
name: 'FlushBuffers',
|
||||
priority: 10,
|
||||
execute: async () => { /* cleanup */ },
|
||||
});
|
||||
|
||||
// As coherence degrades, system moves toward shutdown
|
||||
system.applyCoherenceChange(-0.5);
|
||||
console.log(system.getState()); // 'degraded' | 'shuttingDown'
|
||||
|
||||
// Shutdown is an attractor, not a failure
|
||||
await system.progressShutdown();
|
||||
```
|
||||
|
||||
### 10. Pre-AGI Containment
|
||||
|
||||
Bounded intelligence growth with coherence-enforced safety.
|
||||
|
||||
```typescript
|
||||
import { ContainmentSubstrate } from '@ruvector/delta-behavior';
|
||||
|
||||
const substrate = new ContainmentSubstrate();
|
||||
|
||||
// Capabilities have ceilings
|
||||
// self-modification is highly restricted (ceiling: 3)
|
||||
const result = substrate.attemptGrowth('selfModification', 1.0);
|
||||
// result.type may be 'dampened' - growth reduced to preserve coherence
|
||||
|
||||
// Recursive self-improvement is bounded
|
||||
for (let i = 0; i < 100; i++) {
|
||||
substrate.attemptGrowth('reasoning', 0.3);
|
||||
substrate.attemptGrowth('selfModification', 0.5);
|
||||
substrate.rest(); // Recover coherence
|
||||
}
|
||||
|
||||
// Intelligence grows but remains bounded
|
||||
console.log(substrate.getCapability('selfModification')); // <= 3.0
|
||||
```
|
||||
|
||||
## Core API
|
||||
|
||||
### DeltaBehavior
|
||||
|
||||
The core class for coherence-preserving state transitions.
|
||||
|
||||
```typescript
|
||||
const delta = new DeltaBehavior(config);
|
||||
|
||||
// Check if a transition is allowed
|
||||
delta.checkTransition(currentCoherence, predictedCoherence);
|
||||
// => { type: 'allowed' | 'throttled' | 'blocked' | 'energyExhausted' }
|
||||
|
||||
// Find attractors in state trajectory
|
||||
delta.findAttractors(trajectory);
|
||||
|
||||
// Calculate guidance force toward attractor
|
||||
delta.calculateGuidance(currentState, attractor);
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
```typescript
|
||||
const config: DeltaConfig = {
|
||||
bounds: {
|
||||
minCoherence: 0.3, // Hard floor
|
||||
throttleThreshold: 0.5, // Slow down below this
|
||||
targetCoherence: 0.8, // Optimal level
|
||||
maxDeltaDrop: 0.1, // Max drop per transition
|
||||
},
|
||||
energy: {
|
||||
baseCost: 1.0,
|
||||
instabilityExponent: 2.0,
|
||||
maxCost: 100.0,
|
||||
budgetPerTick: 10.0,
|
||||
},
|
||||
scheduling: {
|
||||
priorityThresholds: [0.0, 0.3, 0.5, 0.7, 0.9],
|
||||
rateLimits: [100, 50, 20, 10, 5],
|
||||
},
|
||||
gating: {
|
||||
minWriteCoherence: 0.3,
|
||||
minPostWriteCoherence: 0.25,
|
||||
recoveryMargin: 0.2,
|
||||
},
|
||||
guidanceStrength: 0.5,
|
||||
};
|
||||
```
|
||||
|
||||
## WASM Support
|
||||
|
||||
For maximum performance, you can load the WASM module:
|
||||
|
||||
```typescript
|
||||
import { init } from '@ruvector/delta-behavior';
|
||||
|
||||
// Browser
|
||||
await init({ wasmPath: '/delta_behavior_bg.wasm' });
|
||||
|
||||
// Node.js
|
||||
await init({ wasmPath: './node_modules/@ruvector/delta-behavior/delta_behavior_bg.wasm' });
|
||||
|
||||
// Or with pre-loaded bytes
|
||||
const wasmBytes = await fetch('/delta_behavior_bg.wasm').then(r => r.arrayBuffer());
|
||||
await init({ wasmBytes: new Uint8Array(wasmBytes) });
|
||||
```
|
||||
|
||||
The SDK works without WASM using a JavaScript fallback.
|
||||
|
||||
## Examples
|
||||
|
||||
### Node.js
|
||||
|
||||
```bash
|
||||
npx tsx examples/node-example.ts
|
||||
```
|
||||
|
||||
### Browser
|
||||
|
||||
Open `examples/browser-example.html` in a browser.
|
||||
|
||||
## TypeScript Support
|
||||
|
||||
Full TypeScript types are included. Import types as needed:
|
||||
|
||||
```typescript
|
||||
import type {
|
||||
Coherence,
|
||||
DeltaConfig,
|
||||
TransitionResult,
|
||||
GrowthResult,
|
||||
CapabilityDomain,
|
||||
} from '@ruvector/delta-behavior';
|
||||
```
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Coherence
|
||||
|
||||
A value from 0.0 to 1.0 representing system stability and internal consistency. Higher coherence means the system is more stable and can perform more operations.
|
||||
|
||||
### Attractors
|
||||
|
||||
Stable states in phase space that the system naturally moves toward. Used for guidance and to detect stable operating regimes.
|
||||
|
||||
### Energy Budget
|
||||
|
||||
Operations cost energy based on how destabilizing they are. When energy is exhausted, operations are blocked until the budget regenerates.
|
||||
|
||||
### Collapse Functions
|
||||
|
||||
Functions that determine how capabilities scale with coherence:
|
||||
|
||||
- **Linear**: Capability = coherence * maxCapability
|
||||
- **Quadratic**: Capability = coherence^2 * maxCapability
|
||||
- **Sigmoid**: Smooth transition at a midpoint
|
||||
- **Step**: Binary on/off at threshold
|
||||
|
||||
## Safety Properties
|
||||
|
||||
The delta-behavior framework provides several safety guarantees:
|
||||
|
||||
1. **Bounded Growth**: Intelligence/capability cannot exceed defined ceilings
|
||||
2. **Graceful Degradation**: Systems become simpler (not chaotic) under stress
|
||||
3. **Self-Limiting**: Operations that would destabilize are automatically blocked
|
||||
4. **Shutdown Attractors**: Unstable systems naturally move toward safe termination
|
||||
5. **Coherence Preservation**: All transitions must maintain minimum coherence
|
||||
|
||||
## Research Paper
|
||||
|
||||
For the full mathematical framework, see:
|
||||
"Delta-Behavior: A Mathematical Framework for Coherence-Preserving State Transitions"
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome. Please ensure all changes maintain the safety properties described above.
|
||||
Reference in New Issue
Block a user