sov-kernel-monster / qataaum /ARCHITECTURE_SPEC.md

chore: push full sov-kernel-monster content from local build

9425aed verified 14 days ago

preview code

Raw

History Blame Contribute Delete

17.3 kB

BOB IDE — Quantum Cognitive Civilization Engine

RBG-FS Architecture Specification v3.0

Engine Name: RBG-FS Engine
Expansion: R orchestration, Bash governance, GNU Fortran numerical computation, Smalltalk civilization semantics
Mission: Production-scale multi-language quantum-cognitive civilization engine for BOB IDE

Scientific Integrity Declaration

Classification

The local implementation is a classical simulation of quantum-state-inspired dynamics using NumPy-equivalent operations. This is NOT quantum computation executed on IBM Quantum hardware.

Real Quantum Requirement

The phrase "executed on IBM Quantum hardware" may only be used when:

Valid quantum circuits are created
Submitted to authenticated IBM Quantum backend
Backend job identifiers received
Measured results received with backend metadata
Verifiable execution receipt produced

Dual Execution Modes

Simulation Mode: Classical local simulation via Fortran kernels
Hardware Mode: Optional authenticated IBM Quantum provider adapter with actual job submission

Language Constitution

Smalltalk (Domain Sovereign)

Runtime: Pharo Smalltalk
Role: Live civilization object graph, agents, knowledge nodes, social relations, messages, governance, event dispatch, reflection, inspection, image-based development

Responsibilities:

QuantumCognitiveAgent objects
KnowledgeNode objects
Civilization objects
LatticeProxy objects
AgentAction objects
Perception, Decision, Reflection objects
SocialLink objects
MetricSnapshot objects
SimulationSession objects
Provider objects, Tool objects, Receipts

Principle: Every domain entity must be inspectable while the system runs. Behavior belongs to objects. State transitions occur through messages.

Fortran (Numerical Sovereign)

Standard: Fortran 2018 or newer
Compiler: GNU Fortran baseline
Role: High-performance numerical engine for state evolution, lattice operations, Hamiltonians, linear algebra, measurements, entropy metrics, batch simulation

Responsibilities:

Complex-valued state vectors
Density matrices (where configured)
Sparse lattice coupling
Gate application
Tensor products
Hamiltonian construction
Time evolution
Measurement distributions
Entanglement metrics
Deterministic seeded simulation
Snapshot serialization

Interfaces: ISO_C_BINDING ABI, stable C-compatible function surface, explicit-width numeric types, caller-owned buffer contracts, error codes with structured diagnostics

R (Experimental Sovereign)

Role: Scientific analysis, experiment configuration, metrics, statistical validation, visualization, reproducibility reports, model comparisons, benchmark analysis

Responsibilities:

Parameter sweeps
Statistical summaries
Convergence analysis
Coherence/entropy/energy plots
Agent-behavior distributions
Regression detection
Reproducibility reports
Quarto technical reports

Rules: R must not become the latency-critical simulation loop. R consumes typed engine outputs. All experiments accept explicit seeds and configuration files.

Bash (Execution Sovereign)

Role: Reproducible local tool execution, builds, tests, packaging, process supervision, environment validation, CI entry points, developer commands

Rules: Strict mode, quote variables, validate paths, resolve repository roots, never silently ignore failed commands, produce machine-readable receipts

Prohibited: Bash must not contain core simulation mathematics or parse complex structured data using fragile text pipelines.

Rust (Security Sovereign)

Role: Tauri host, WebSocket bridge, process security, capability enforcement, protocol validation, filesystem boundaries, tool receipts, native packaging

TypeScript (Interface Sovereign)

Role: Browser IDE, Monaco integration, autonomous chat, route state, WebLLM, diff review, terminal display, GitHub integration, WebSocket client

Architecture Layers

Layer 1: Interface

Runtime: GitHub Pages browser application or Tauri webview
Language: TypeScript + semantic CSS
Components: Monaco editor, BOB autonomous chat, xterm.js terminal, civilization inspector, quantum-state inspector, metrics viewer, GitHub source control, diff review, execution receipts

Layer 2: Native Control (BOB Bridge)

Runtime: Rust WebSocket server
Transport: Authenticated localhost WebSocket
Components: Capability negotiation, process manager, filesystem gateway, Git gateway, shell gateway, Smalltalk runtime adapter, Fortran engine adapter, R analysis adapter, IBM Quantum provider adapter

Layer 3: Civilization

Runtime: Pharo Smalltalk image
Language: Smalltalk
Components: Agent society, knowledge graph, six-stage cognitive lifecycle, actions, social relations, governance, persistence orchestration, live inspection

Layer 4: Numerical

Runtime: Native shared library or supervised worker process
Language: Fortran
Components: Quantum-inspired state engine, lattice engine, Hamiltonian engine, integrator, measurement engine, metrics engine

Layer 5: Analysis

Runtime: Supervised R process
Language: R
Components: Experiment runner, metrics analyzer, visualization generator, benchmark report, validation report

Control Flow

Interactive Cycle

User sends instruction through BOB chat interface
BOB agent converts request into visible execution plan
Browser sends typed request to Rust BOB Bridge
Bridge validates origin, session, workspace, capability, permission
Bridge sends domain message to Smalltalk civilization runtime
Smalltalk resolves objects, cognitive phase, agent state, requested behavior
Smalltalk creates typed numerical request for Fortran engine
Fortran validates dimensions, normalization, timestep, seed, memory bounds
Fortran computes requested evolution and returns structured results
Smalltalk applies domain semantics and emits civilization events
Rust streams events, metrics, state deltas, logs, receipts over WebSocket
Browser updates inspectors without blocking Monaco or chat composer

Analysis Cycle

User or agent selects experiment
Smalltalk creates immutable experiment specification
Bash launches supervised Fortran batch worker
Fortran writes typed result artifacts
R validates, summarizes, visualizes outputs
BOB displays report and links to execution receipts

Smalltalk Domain Model

BOBCivilization

State: agents, knowledgeGraph, socialGraph, globalLattice, simulationClock, governancePolicy, eventJournal, activeExperiment

Messages: initializeFromConfiguration:, advanceBy:, executeCycle, addAgent:, removeAgent:, inspectAgent:, publishEvent:, createCheckpoint, restoreCheckpoint:, collectMetrics, exportSnapshot

BOBQuantumCognitiveAgent

State: identifier, localLattice, knowledgeNodes, relationships, cognitivePhase, energyBudget, coherenceEstimate, actionHistory, randomStream

Messages: perceive:, reason, learnFrom:, decide, actIn:, reflect, executeCognitiveCycleIn:, receiveMessage:, formRelationshipWith:, inspectState

BOBKnowledgeNode

State: identifier, proposition, confidence, provenance, numericalStateReference, creationEvent, revisionHistory

Messages: reinforceBy:, penalizeBy:, mergeWith:, measureConfidence, addProvenance:, reviseWith:

BOBFortranEngine

Responsibility: Smalltalk proxy for native numerical ABI

Messages: createState:, destroyState:, applyGate:to:, evolve:withHamiltonian:forDuration:, measure:usingSeed:, computeMetrics:, createLattice:, updateLattice:

BOBExperiment

State: identifier, configuration, seed, startTime, endTime, engineVersion, results, receipts

BOBExecutionReceipt

State: identifier, timestamp, operation, inputsHash, outputsHash, engineVersion, seed, exitStatus, diagnostics, executionLocation

Six-Stage Cognitive Cycle

Perceive: Receive environment deltas, messages, measurements, available actions. Preserve provenance.
Reason: Evaluate knowledge relationships, request numerical operations. No stochastic selection as substitute for reasoning.
Learn: Update knowledge confidence under explicit rules. Preserve prior state, create revision event.
Decide: Rank valid actions using policy, state, evidence, configured stochastic behavior. Log candidates and rationale.
Act: Apply valid action through civilization object model. Validate preconditions and postconditions.
Reflect: Compare outcome with intent, update metrics, record lessons, create receipt.

Fortran Engine Modules

bob_kinds

Define explicit integer and real kinds, complex precision, ABI-compatible type aliases

bob_errors

Stable error codes, diagnostic buffers, no uncontrolled process termination

bob_rng

Deterministic seeded pseudo-random streams, independent streams per agent, reproducible measurement sampling

bob_state

State-vector representation, optional density-matrix representation, normalization validation, allocation and release

bob_gates

Pauli X, Y, Z, Hadamard, T gate, controlled gates, arbitrary validated unitary operators

bob_tensor

Tensor products, subsystem indexing, joint-state construction, partial trace where supported

bob_lattice

Lattice dimensions, neighbor topology, boundary conditions, coupling matrix, local state references

bob_hamiltonian

Kinetic terms, interaction terms, external-field terms, Hermiticity checks, sparse and dense execution paths

bob_integrator

Exact matrix exponential for small systems, stable numerical approximation for larger systems, configurable timestep, error estimates, norm-preservation checks

bob_measurement

Basis measurement, probability distribution, sampling, collapse behavior, batch shots

bob_metrics

Norm, energy expectation, purity, von Neumann entropy, reduced-state metrics, fidelity, coherence indicators with precise definitions

bob_surface_code

Only exists when stabilizers, syndrome extraction, logical states, error injection, decoding, validation are implemented. Otherwise explicitly marked unavailable.

bob_abi

Export stable ISO_C_BINDING interface consumed by Rust and Smalltalk adapters

Fortran ABI Functions

bob_engine_version()
bob_state_create()
bob_state_destroy()
bob_state_normalize()
bob_state_validate()
bob_gate_apply()
bob_hamiltonian_create()
bob_hamiltonian_destroy()
bob_state_evolve()
bob_state_measure()
bob_lattice_create()
bob_lattice_step()
bob_metrics_compute()
bob_snapshot_write()
bob_snapshot_read()
bob_last_error()

Contract: Every function returns stable status code. Every buffer has explicit length. No function reads beyond caller-provided bounds. No ABI function throws, aborts, or writes to uncontrolled standard output.

R Analysis Engine

Package: bobCivilizationR

Commands: bob-experiment, bob-analyze, bob-benchmark, bob-report, bob-compare

Analyses: Repeated-run variance, seed sensitivity, conservation diagnostics, norm drift, energy drift, scaling by lattice size, scaling by agent count, action-frequency distributions, knowledge-confidence calibration, social-network evolution, correlation vs causation warnings, simulation vs hardware result comparison

Reporting: Quarto for reproducible HTML and PDF reports including configuration, seed, software versions, commit hash, engine mode, machine metadata, runtime, warnings, receipt identifiers

Bash Scripts

scripts/bootstrap.sh - Validate compilers, runtimes, package managers, system requirements
scripts/build-fortran.sh - Build debug and release numerical libraries
scripts/build-smalltalk.sh - Prepare Pharo image and load project packages
scripts/build-bridge.sh - Build Rust bridge
scripts/test-all.sh - Run all tests (Fortran, Smalltalk, Rust, TypeScript, R, protocol, integration)
scripts/run-civilization.sh - Launch bridge, Smalltalk runtime, numerical engine, development UI
scripts/run-experiment.sh - Execute configured deterministic batch experiment
scripts/generate-report.sh - Run R analysis and generate reproducibility reports
scripts/package.sh - Produce versioned runtime artifacts

Receipt Output: Every script writes structured JSON receipt containing command, repository commit, working directory, start/end time, tool versions, exit status, generated artifacts, hashes

WebSocket Services

civilization namespace

civilization.create, .start, .pause, .step, .stop, .snapshot, .restore, .inspect, .metrics.subscribe, .event

agent namespace

agent.list, .create, .inspect, .cycle, .message, .action.approve, .event

quantum namespace

quantum.state.create, .inspect, .gate.apply, .evolve, .measure, .metrics, .result

experiment namespace

experiment.create, .run, .cancel, .progress, .complete, .report

runtime namespace

runtime.capabilities, .health, .logs, .receipt, .error

Streaming Rules: Assign every operation a request identifier. Stream progress without blocking command responses. Preserve event order per simulation session. Attach simulation tick and event sequence to civilization events. Never silently retry state mutations after uncertain connection failure.

BOB IDE Integration

Routes

/workspace/:workspaceId/civilization - Live civilization map, agent list, state timeline, knowledge graph, social network, metrics, controls, event stream
/workspace/:workspaceId/civilization/agents/:agentId - Object inspector for one Smalltalk agent
/workspace/:workspaceId/quantum - Simulation-state inspector, lattice viewer, operator history, measurement distributions, normalization diagnostics, energy, entropy, coherence metrics
/workspace/:workspaceId/experiments - Experiment configurations, active runs, completed runs, comparisons, reports
/workspace/:workspaceId/runtime - Smalltalk image state, Fortran engine state, R worker state, bridge state, process logs, versions, capabilities, receipts

Agent Chat Tools

inspect_civilization, inspect_agent, advance_civilization, pause_civilization, create_checkpoint, restore_checkpoint, run_experiment, compare_experiments, apply_quantum_gate, measure_state, analyze_metrics, generate_report

Visual Principle: Civilization controls belong beside autonomous BOB chat and active editor. Do not convert IDE into detached analytics dashboard.

Persistence

Event Journal: Append-only ordered domain events generated by Smalltalk
Checkpoint: Versioned full or incremental state snapshots
Numerical Snapshot: Fortran-owned binary format with version, dimensions, precision, endianness, normalization status, checksum
Portable Export: JSON metadata plus referenced binary numerical artifacts
Migration: Explicit schema versions and deterministic migrations. Never load incompatible snapshots silently.

Repository Structure

bob-quantum-civilization/
├── apps/
│   ├── bob-web/              # Browser IDE (GitHub Pages)
│   ├── bob-desktop/          # Tauri desktop application
│   └── bob-bridge/           # Rust WebSocket bridge
├── smalltalk/
│   └── src/
│       ├── BOB-Civilization/
│       ├── BOB-Agents/
│       ├── BOB-Knowledge/
│       ├── BOB-Numerics/
│       ├── BOB-Experiments/
│       ├── BOB-Receipts/
│       └── BOB-Protocol/
├── fortran/
│   └── src/
│       ├── bob_kinds.f90
│       ├── bob_errors.f90
│       ├── bob_rng.f90
│       ├── bob_state.f90
│       ├── bob_gates.f90
│       ├── bob_tensor.f90
│       ├── bob_lattice.f90
│       ├── bob_hamiltonian.f90
│       ├── bob_integrator.f90
│       ├── bob_measurement.f90
│       ├── bob_metrics.f90
│       └── bob_abi.f90
├── r/
│   ├── bobCivilizationR/
│   └── experiments/
├── scripts/
│   ├── bootstrap.sh
│   ├── build-fortran.sh
│   ├── build-smalltalk.sh
│   ├── build-bridge.sh
│   ├── test-all.sh
│   ├── run-civilization.sh
│   ├── run-experiment.sh
│   ├── generate-report.sh
│   └── package.sh
├── docs/
│   ├── ARCHITECTURE_SPEC.md
│   ├── FORTRAN_ABI.md
│   ├── SMALLTALK_API.md
│   ├── WEBSOCKET_PROTOCOL.md
│   └── SCIENTIFIC_INTEGRITY.md
├── reference/
│   └── IBM_QUANTUM_WATSON_CIVILIZATION.py  # Behavioral reference
└── README.md

Status: Architecture specification complete. Ready for implementation scaffold.