quantum-spherifier 1.0.0

package/src/index.js

@@ -0,0 +1,178 @@
+/**
+ * quantum-spherifier (qSpherifier) v1.0 — Main entry point
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Autonomous Scientific Research Agent for Quantum Computing.
+ *
+ * MISSION: Build quantum computers capable of solving problems impossible
+ * for current (and short/mid-term) classical computers, across four lines:
+ *   1. Quantum Error Correction (QEC)
+ *   2. New qubit modalities
+ *   3. Quantum algorithms
+ *   4. Molecular simulation
+ *
+ * Based on the Artificial Junky Neuron (AJN) framework by Justo Tapiador
+ * Garcia (UA), extended from predator-jungle-agent v2.0 via fusionary-agent.
+ *
+ * On launch, qSpherifier immediately begins autonomous research. It does NOT
+ * wait for an owner directive (this is the AJN "addiction" property).
+ * The owner can guide it at any time via the web UI or CLI.
+ *
+ * Every proposed solution is enlaced with the actual level of resources that
+ * human civilisation possesses (IBM, Google, IonQ, Quantinuum, QuEra, Atom
+ * Computing, PsiQuantum, etc.) or will possess if proposed infrastructures
+ * are built. Successful solutions are grouped into coherent patent clusters.
+ * Nothing stays isolated.
+ *
+ * References:
+ *   Tapiador García, J. (2024). Agentic Theory: Definition of the
+ *   Artificial Junky Neuron (AJN). Preprint WALLERMAX-AI 2604.00012.
+ *   Universidad de Alicante (UA).
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+
+// Core
+export { QSpherifierAgent } from './core/QSpherifierAgent.js';
+export { ANNPsi, QUANTUM_STIMULUS_CLASSES } from './core/ANNPsi.js';
+export { ArtificialJunkyNeuron, AJNPhase } from './core/ArtificialJunkyNeuron.js';
+export { StateSerializer } from './core/StateSerializer.js';
+
+// Layers
+export {
+  HomogeneousAJNLayer,
+  HeterogeneousAJNLayer,
+  HybridAJNLayer,
+} from './layers/AJNLayer.js';
+export { TransformerBlock } from './layers/TransformerBlock.js';
+
+// Modules
+export { HierarchicalCommandInterpreter } from './modules/HierarchicalCommandInterpreter.js';
+export {
+  TokenEnergyArbitrator,
+  PraxicStreamExecutor,
+} from './modules/TokenEnergyArbitrator.js';
+export { CascadeMonitor } from './modules/CascadeMonitor.js';
+export { MemorySystem } from './modules/MemorySystem.js';
+export { SafetyGuardrails } from './modules/SafetyGuardrails.js';
+export { MetricsCollector } from './modules/MetricsCollector.js';
+export { PluginManager, HOOKS as PLUGIN_HOOKS } from './modules/PluginManager.js';
+export { QuantumKnowledgeGraph, RELATION_TYPES, FEASIBILITY_TIERS, RESEARCH_LINES } from './modules/QuantumKnowledgeGraph.js';
+export { CitationGraph } from './modules/CitationGraph.js';
+export { HypothesisGenerator } from './modules/HypothesisGenerator.js';
+export { ResourceFeasibilityChecker, RESOURCE_ANCHORS, FEASIBILITY_RULES } from './modules/ResourceFeasibilityChecker.js';
+export { DocumentArchivist, CATEGORIES as ARCHIVE_CATEGORIES, TAG_PALETTE } from './modules/DocumentArchivist.js';
+export { PatentDraftAssistant } from './modules/PatentDraftAssistant.js';
+export { PatentClusterManager } from './modules/PatentClusterManager.js';
+export { ResearchLineRouter, LINE_DESCRIPTIONS } from './modules/ResearchLineRouter.js';
+
+// Tools
+export { Tool } from './tools/Tool.js';
+export { FileSystemTool } from './tools/FileSystemTool.js';
+export { LaTeXDocumentTool } from './tools/LaTeXDocumentTool.js';
+export { QuantumPhysicsTool, SURFACE_CODE_THRESHOLD } from './tools/QuantumPhysicsTool.js';
+export { WebSearchTool } from './tools/WebSearchTool.js';
+export { BibliographyTool } from './tools/BibliographyTool.js';
+export { ToolRegistry } from './tools/ToolRegistry.js';
+
+// Training
+export { TrainingPipeline } from './training/TrainingPipeline.js';
+
+// LLM
+export { LLMAdapter } from './llm/LLMAdapter.js';
+export { ZAIAdapter } from './llm/ZAIAdapter.js';
+export { AnthropicAdapter } from './llm/AnthropicAdapter.js';
+export { OpenAIAdapter } from './llm/OpenAIAdapter.js';
+export { GoogleAdapter } from './llm/GoogleAdapter.js';
+export { DeepSeekAdapter } from './llm/DeepSeekAdapter.js';
+export { LocalLLMAdapter } from './llm/LocalLLMAdapter.js';
+export { LLMRouter } from './llm/LLMRouter.js';
+
+// ── Default factory: a configured QSpherifierAgent with multi-LLM router ────
+import { QSpherifierAgent } from './core/QSpherifierAgent.js';
+import { ZAIAdapter } from './llm/ZAIAdapter.js';
+import { AnthropicAdapter } from './llm/AnthropicAdapter.js';
+import { OpenAIAdapter } from './llm/OpenAIAdapter.js';
+import { GoogleAdapter } from './llm/GoogleAdapter.js';
+import { DeepSeekAdapter } from './llm/DeepSeekAdapter.js';
+import { LocalLLMAdapter } from './llm/LocalLLMAdapter.js';
+import { LLMRouter } from './llm/LLMRouter.js';
+
+/**
+ * Build a multi-LLM router using the most powerful frontier models.
+ * Adapters are registered in priority order; missing API keys are skipped
+ * gracefully.
+ */
+export function buildLLMRouter(opts = {}) {
+  const router = new LLMRouter(opts);
+
+  // 1. ZAI / GLM-4.6 (primary — best STEM reasoning per token)
+  try { router.register('zai', new ZAIAdapter({ model: opts.zaiModel ?? 'glm-4.6' }), 10); } catch {}
+
+  // 2. Anthropic Claude Opus 4.1 (precise legal/patent language)
+  if (process.env.ANTHROPIC_API_KEY) {
+    try { router.register('anthropic', new AnthropicAdapter({ model: opts.anthropicModel ?? 'claude-opus-4-1' }), 20); } catch {}
+  }
+
+  // 3. OpenAI GPT-4o (high-throughput hypothesis generation)
+  if (process.env.OPENAI_API_KEY) {
+    try { router.register('openai', new OpenAIAdapter({ model: opts.openaiModel ?? 'gpt-4o' }), 30); } catch {}
+  }
+
+  // 4. Google Gemini 2.0 (long-context literature review)
+  if (process.env.GOOGLE_API_KEY) {
+    try { router.register('google', new GoogleAdapter({ model: opts.googleModel ?? 'gemini-2.0-flash' }), 40); } catch {}
+  }
+
+  // 5. DeepSeek-R1 (chain-of-thought proof verification)
+  if (process.env.DEEPSEEK_API_KEY) {
+    try { router.register('deepseek', new DeepSeekAdapter({ model: opts.deepseekModel ?? 'deepseek-reasoner' }), 50); } catch {}
+  }
+
+  // 6. Local Ollama (air-gapped fallback)
+  if (process.env.OLLAMA_ENDPOINT) {
+    try { router.register('local', new LocalLLMAdapter({}), 60); } catch {}
+  }
+
+  return router;
+}
+
+export async function createQSpherifier(opts = {}) {
+  const llm = opts.llm ?? buildLLMRouter(opts);
+  const agent = new QSpherifierAgent({
+    llm,
+    researchDir: opts.researchDir ?? './research',
+    safetyLevel: opts.safetyLevel ?? 'standard',
+    autonomousMode: opts.autonomousMode ?? true,
+    maxCycles: opts.maxCycles ?? 50,
+    ...opts,
+  });
+  await agent.init();
+  return agent;
+}
+
+// If invoked directly, boot the agent
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const agent = await createQSpherifier({
+    researchDir: process.env.QSPHERIFIER_RESEARCH_DIR ?? './research',
+    maxCycles: parseInt(process.env.QSPHERIFIER_MAX_CYCLES ?? '50', 10),
+  });
+  const llmStatus = agent.llm?.status ? agent.llm.status() : 'single adapter';
+  console.log(`
+  ╔════════════════════════════════════════════════════════════════════╗
+  ║            quantum-spherifier  v1.0  (:qSpherifier) — online       ║
+  ║                                                                    ║
+  ║   Mission: Quantum computers that solve impossible problems.       ║
+  ║   Lines:   QEC · New Qubits · Algorithms · Molecular Simulation    ║
+  ║   Mode:    autonomous (AJN addiction active)                      ║
+  ║   LLM:     ${typeof llmStatus === 'string' ? llmStatus.padEnd(48) : (llmStatus.length + ' adapters registered').padEnd(48)}║
+  ║   Cycles:  ${agent.maxCycles.toString().padEnd(48)}║
+  ║                                                                    ║
+  ║   Web UI:  npm run web  →  http://localhost:3000                   ║
+  ║   Guide:   npm run guide "<directive>"                             ║
+  ╚════════════════════════════════════════════════════════════════════╝
+  `);
+  process.on('SIGINT', async () => {
+    console.log('\n[qSpherifier] Shutting down...');
+    await agent.shutdown();
+    process.exit(0);
+  });
+}

package/src/layers/AJNLayer.js

@@ -0,0 +1,248 @@
+/**
+ * AJNLayer.js — FUSIONARY (v1.0)
+ * Wrapper classes around the AJN core, providing layer-level abstractions.
+ * Compatible interface with predator-jungle-agent v2.0 so existing tools
+ * and modules can interoperate, but extended with multi-objective rewards.
+ */
+
+import { ArtificialJunkyNeuron, AJNPhase } from '../core/ArtificialJunkyNeuron.js';
+
+// ── Homogeneous AJN layer (all neurons crave the same stimulus class) ──────
+export class HomogeneousAJNLayer {
+  constructor(opts = {}) {
+    this.id             = opts.id ?? `homog_${Math.random().toString(36).slice(2, 8)}`;
+    this.dModel         = opts.dModel ?? 256;
+    this.stimulusClass  = opts.stimulusClass ?? 'default';
+    this.neurons        = [];
+    const count = opts.neuronCount ?? 4;
+    for (let i = 0; i < count; i++) {
+      this.neurons.push(new ArtificialJunkyNeuron({
+        id: `${this.id}_n${i}`,
+        stimulusClass: this.stimulusClass,
+        params: opts.params,
+      }));
+    }
+  }
+
+  forward(stimulus) {
+    const outputs = this.neurons.map(n => n.process(stimulus));
+    // Aggregate: take the praxis vector with highest alpha
+    let best = outputs[0];
+    for (const o of outputs) {
+      if (o.alpha > best.alpha) best = o;
+    }
+    return {
+      vector: best.praxis,
+      alpha: best.alpha,
+      phase: best.phase,
+      layerId: this.id,
+      neuronSnapshots: outputs.map(o => ({
+        id: o.id, phase: o.phase, alpha: o.alpha, craving: o.craving,
+      })),
+    };
+  }
+
+  update(reward) {
+    for (const n of this.neurons) {
+      // Inject reward as delta in the next process cycle
+      n.alphaPrev = (n.alphaPrev ?? 0) - reward;
+    }
+  }
+
+  snapshot() {
+    return {
+      id: this.id,
+      type: 'homogeneous',
+      stimulusClass: this.stimulusClass,
+      neurons: this.neurons.map(n => n.snapshot()),
+    };
+  }
+
+  serialize() {
+    return {
+      id: this.id,
+      type: 'homogeneous',
+      stimulusClass: this.stimulusClass,
+      dModel: this.dModel,
+      neurons: this.neurons.map(n => n.serialize()),
+    };
+  }
+
+  deserialize(state) {
+    this.id = state.id ?? this.id;
+    this.stimulusClass = state.stimulusClass ?? this.stimulusClass;
+    if (state.neurons && Array.isArray(state.neurons)) {
+      for (let i = 0; i < Math.min(state.neurons.length, this.neurons.length); i++) {
+        this.neurons[i].deserialize(state.neurons[i]);
+      }
+    }
+  }
+}
+
+// ── Heterogeneous AJN layer (K classes compete via softmax) ───────────────
+export class HeterogeneousAJNLayer {
+  constructor(opts = {}) {
+    this.id              = opts.id ?? `hetero_${Math.random().toString(36).slice(2, 8)}`;
+    this.dModel          = opts.dModel ?? 256;
+    this.kClasses        = opts.kClasses ?? 8;
+    this.stimulusClasses = opts.stimulusClasses ?? Array.from({ length: this.kClasses }, (_, i) => `class_${i}`);
+    this.neurons         = [];
+    for (let i = 0; i < this.kClasses; i++) {
+      this.neurons.push(new ArtificialJunkyNeuron({
+        id: `${this.id}_n${i}`,
+        stimulusClass: this.stimulusClasses[i % this.stimulusClasses.length],
+        params: opts.params,
+      }));
+    }
+    this.temperature = opts.temperature ?? 1.0;
+  }
+
+  forward(stimulus) {
+    const outputs = this.neurons.map(n => n.process(stimulus));
+    // Softmax over alphas to pick a winning class
+    const alphas = outputs.map(o => o.alpha);
+    const maxA = Math.max(...alphas);
+    const exps = alphas.map(a => Math.exp((a - maxA) / this.temperature));
+    const sumExp = exps.reduce((s, v) => s + v, 0) || 1;
+    const probs = exps.map(e => e / sumExp);
+    const winnerIdx = probs.indexOf(Math.max(...probs));
+    const winner = outputs[winnerIdx];
+    return {
+      vector: winner.praxis,
+      alpha: winner.alpha,
+      phase: winner.phase,
+      layerId: this.id,
+      winnerClass: this.stimulusClasses[winnerIdx % this.stimulusClasses.length],
+      winnerIdx,
+      probabilities: probs,
+      neuronSnapshots: outputs.map((o, i) => ({
+        id: o.id, phase: o.phase, alpha: o.alpha, prob: probs[i],
+      })),
+    };
+  }
+
+  update(reward) {
+    for (const n of this.neurons) {
+      n.alphaPrev = (n.alphaPrev ?? 0) - reward;
+    }
+  }
+
+  snapshot() {
+    return {
+      id: this.id,
+      type: 'heterogeneous',
+      kClasses: this.kClasses,
+      stimulusClasses: this.stimulusClasses,
+      neurons: this.neurons.map(n => n.snapshot()),
+    };
+  }
+
+  serialize() {
+    return {
+      id: this.id,
+      type: 'heterogeneous',
+      kClasses: this.kClasses,
+      stimulusClasses: this.stimulusClasses,
+      dModel: this.dModel,
+      temperature: this.temperature,
+      neurons: this.neurons.map(n => n.serialize()),
+    };
+  }
+
+  deserialize(state) {
+    this.id = state.id ?? this.id;
+    this.kClasses = state.kClasses ?? this.kClasses;
+    this.stimulusClasses = state.stimulusClasses ?? this.stimulusClasses;
+    this.temperature = state.temperature ?? this.temperature;
+    if (state.neurons && Array.isArray(state.neurons)) {
+      for (let i = 0; i < Math.min(state.neurons.length, this.neurons.length); i++) {
+        this.neurons[i].deserialize(state.neurons[i]);
+      }
+    }
+  }
+}
+
+// ── Hybrid AJN layer (mix of homogeneous + heterogeneous neurons) ─────────
+export class HybridAJNLayer {
+  constructor(opts = {}) {
+    this.id             = opts.id ?? `hybrid_${Math.random().toString(36).slice(2, 8)}`;
+    this.dModel         = opts.dModel ?? 256;
+    this.stimulusClass  = opts.stimulusClass ?? 'default';
+    this.neurons        = [];
+    const homCount = opts.homCount ?? 3;
+    const hetCount = opts.hetCount ?? 3;
+    for (let i = 0; i < homCount; i++) {
+      this.neurons.push(new ArtificialJunkyNeuron({
+        id: `${this.id}_hom_${i}`,
+        stimulusClass: this.stimulusClass,
+        params: opts.params,
+      }));
+    }
+    for (let i = 0; i < hetCount; i++) {
+      this.neurons.push(new ArtificialJunkyNeuron({
+        id: `${this.id}_het_${i}`,
+        stimulusClass: `${this.stimulusClass}_variant_${i}`,
+        params: opts.params,
+      }));
+    }
+  }
+
+  forward(stimulus) {
+    const outputs = this.neurons.map(n => n.process(stimulus));
+    // Average the praxis vectors (modulation behaviour)
+    const dim = outputs[0]?.praxis?.length ?? this.dModel;
+    const aggregated = new Float64Array(dim);
+    for (const o of outputs) {
+      for (let i = 0; i < Math.min(o.praxis.length, dim); i++) {
+        aggregated[i] += o.praxis[i] / outputs.length;
+      }
+    }
+    const avgAlpha = outputs.reduce((s, o) => s + o.alpha, 0) / outputs.length;
+    return {
+      vector: aggregated,
+      alpha: avgAlpha,
+      phase: outputs[0]?.phase,
+      layerId: this.id,
+      neuronSnapshots: outputs.map(o => ({
+        id: o.id, phase: o.phase, alpha: o.alpha, craving: o.craving,
+      })),
+    };
+  }
+
+  update(reward) {
+    for (const n of this.neurons) {
+      n.alphaPrev = (n.alphaPrev ?? 0) - reward;
+    }
+  }
+
+  snapshot() {
+    return {
+      id: this.id,
+      type: 'hybrid',
+      stimulusClass: this.stimulusClass,
+      neurons: this.neurons.map(n => n.snapshot()),
+    };
+  }
+
+  serialize() {
+    return {
+      id: this.id,
+      type: 'hybrid',
+      stimulusClass: this.stimulusClass,
+      dModel: this.dModel,
+      neurons: this.neurons.map(n => n.serialize()),
+    };
+  }
+
+  deserialize(state) {
+    this.id = state.id ?? this.id;
+    this.stimulusClass = state.stimulusClass ?? this.stimulusClass;
+    if (state.neurons && Array.isArray(state.neurons)) {
+      for (let i = 0; i < Math.min(state.neurons.length, this.neurons.length); i++) {
+        this.neurons[i].deserialize(state.neurons[i]);
+      }
+    }
+  }
+}
+
+export { AJNPhase };

package/src/layers/TransformerBlock.js

@@ -0,0 +1,201 @@
+/**
+ * TransformerBlock.js — FUSIONARY (v1.0)
+ * Real multi-head self-attention block (inherited from predator v2.0).
+ * Used for cross-document context attention and reasoning over
+ * hypothesis chains.
+ *
+ * Architecture per block:
+ *   x -> LayerNorm -> MultiHeadAttention -> + residual -> LayerNorm -> FFN(GELU) -> + residual
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+
+function xavierInit(rows, cols) {
+  const limit = Math.sqrt(6 / (rows + cols));
+  const m = new Float64Array(rows * cols);
+  for (let i = 0; i < m.length; i++) m[i] = (Math.random() * 2 - 1) * limit;
+  return m;
+}
+
+function matVec(m, v, rows, cols) {
+  const out = new Float64Array(rows);
+  for (let i = 0; i < rows; i++) {
+    let s = 0;
+    for (let j = 0; j < cols; j++) s += m[i * cols + j] * v[j];
+    out[i] = s;
+  }
+  return out;
+}
+
+function layerNorm(v, eps = 1e-5) {
+  let mean = 0;
+  for (const x of v) mean += x;
+  mean /= v.length || 1;
+  let variance = 0;
+  for (const x of v) variance += (x - mean) ** 2;
+  variance /= v.length || 1;
+  const denom = Math.sqrt(variance + eps);
+  const out = new Float64Array(v.length);
+  for (let i = 0; i < v.length; i++) out[i] = (v[i] - mean) / denom;
+  return out;
+}
+
+function gelu(x) {
+  return 0.5 * x * (1 + Math.tanh(Math.sqrt(2 / Math.PI) * (x + 0.044715 * x ** 3)));
+}
+
+function softmax(v) {
+  let max = -Infinity;
+  for (const x of v) if (x > max) max = x;
+  let sum = 0;
+  const exps = new Float64Array(v.length);
+  for (let i = 0; i < v.length; i++) {
+    exps[i] = Math.exp(v[i] - max);
+    sum += exps[i];
+  }
+  if (sum === 0) return exps;
+  for (let i = 0; i < v.length; i++) exps[i] /= sum;
+  return exps;
+}
+
+export class TransformerBlock {
+  constructor(opts = {}) {
+    this.id      = opts.id ?? `tf_${uuidv4().slice(0, 8)}`;
+    this.dModel  = opts.dModel ?? 256;
+    this.nHeads  = opts.nHeads ?? 8;
+    this.dFF     = opts.dFF ?? 1024;
+    this.dHead   = Math.floor(this.dModel / this.nHeads);
+
+    // Q/K/V projections (per head)
+    this.Wq = [];
+    this.Wk = [];
+    this.Wv = [];
+    for (let h = 0; h < this.nHeads; h++) {
+      this.Wq.push(xavierInit(this.dHead, this.dModel));
+      this.Wk.push(xavierInit(this.dHead, this.dModel));
+      this.Wv.push(xavierInit(this.dHead, this.dModel));
+    }
+    // Output projection
+    this.Wo = xavierInit(this.dModel, this.dModel);
+
+    // FFN weights
+    this.W1 = xavierInit(this.dFF, this.dModel);
+    this.b1 = new Float64Array(this.dFF);
+    this.W2 = xavierInit(this.dModel, this.dFF);
+    this.b2 = new Float64Array(this.dModel);
+
+    // LayerNorm gains/biases
+    this.ln1Gamma = new Float64Array(this.dModel).fill(1);
+    this.ln1Beta  = new Float64Array(this.dModel);
+    this.ln2Gamma = new Float64Array(this.dModel).fill(1);
+    this.ln2Beta  = new Float64Array(this.dModel);
+
+    this.step = 0;
+  }
+
+  forward(x) {
+    // x can be a stimulus object with .vector, or a plain Float64Array
+    const input = x?.vector ?? x ?? new Float64Array(this.dModel);
+    const v = input.length === this.dModel
+      ? Float64Array.from(input)
+      : Float64Array.from({ length: this.dModel }, (_, i) => input[i % input.length] ?? 0);
+
+    // Multi-head self-attention (using v as Q, K, V — single-token attention)
+    const headOutputs = [];
+    for (let h = 0; h < this.nHeads; h++) {
+      const q = matVec(this.Wq[h], v, this.dHead, this.dModel);
+      const k = matVec(this.Wk[h], v, this.dHead, this.dModel);
+      const val = matVec(this.Wv[h], v, this.dHead, this.dModel);
+      // Single-token attention: softmax(q.k^T / sqrt(dHead)) * v
+      let score = 0;
+      for (let i = 0; i < this.dHead; i++) score += q[i] * k[i];
+      score /= Math.sqrt(this.dHead);
+      const attnWeight = 1 / (1 + Math.exp(-score)); // sigmoid approximation for single-token
+      const headOut = new Float64Array(this.dHead);
+      for (let i = 0; i < this.dHead; i++) headOut[i] = attnWeight * val[i];
+      headOutputs.push(headOut);
+    }
+    // Concatenate heads
+    const concat = new Float64Array(this.dModel);
+    for (let h = 0; h < this.nHeads; h++) {
+      for (let i = 0; i < this.dHead; i++) {
+        concat[h * this.dHead + i] = headOutputs[h][i];
+      }
+    }
+    const attnOut = matVec(this.Wo, concat, this.dModel, this.dModel);
+
+    // Residual + LayerNorm
+    const res1 = new Float64Array(this.dModel);
+    for (let i = 0; i < this.dModel; i++) res1[i] = v[i] + attnOut[i];
+    const norm1 = layerNorm(res1);
+    for (let i = 0; i < this.dModel; i++) norm1[i] = norm1[i] * this.ln1Gamma[i] + this.ln1Beta[i];
+
+    // FFN
+    const ffnHidden = matVec(this.W1, norm1, this.dFF, this.dModel);
+    for (let i = 0; i < this.dFF; i++) ffnHidden[i] = gelu(ffnHidden[i] + this.b1[i]);
+    const ffnOut = matVec(this.W2, ffnHidden, this.dModel, this.dFF);
+    for (let i = 0; i < this.dModel; i++) ffnOut[i] += this.b2[i];
+
+    // Residual + LayerNorm
+    const res2 = new Float64Array(this.dModel);
+    for (let i = 0; i < this.dModel; i++) res2[i] = norm1[i] + ffnOut[i];
+    const norm2 = layerNorm(res2);
+    for (let i = 0; i < this.dModel; i++) norm2[i] = norm2[i] * this.ln2Gamma[i] + this.ln2Beta[i];
+
+    this.step++;
+    return {
+      vector: norm2,
+      layerId: this.id,
+      attentionWeights: headOutputs.map(h => h[0]), // diagnostic
+    };
+  }
+
+  update(reward) {
+    // Light Hebbian-style update on output projection (small perturbation)
+    const lr = 0.001 * Math.sign(reward);
+    for (let i = 0; i < this.Wo.length; i++) {
+      this.Wo[i] += lr * (Math.random() - 0.5) * 0.01;
+    }
+  }
+
+  snapshot() {
+    return {
+      id: this.id,
+      type: 'transformer',
+      dModel: this.dModel,
+      nHeads: this.nHeads,
+      dFF: this.dFF,
+      step: this.step,
+    };
+  }
+
+  serialize() {
+    return {
+      id: this.id,
+      type: 'transformer',
+      dModel: this.dModel,
+      nHeads: this.nHeads,
+      dFF: this.dFF,
+      step: this.step,
+      // For brevity we serialize norms but skip the heavy weight matrices
+      // in the default snapshot. A full checkpoint serializer in
+      // StateSerializer will dump the weights as base64.
+      ln1Gamma: Array.from(this.ln1Gamma),
+      ln1Beta: Array.from(this.ln1Beta),
+      ln2Gamma: Array.from(this.ln2Gamma),
+      ln2Beta: Array.from(this.ln2Beta),
+    };
+  }
+
+  deserialize(state) {
+    this.id = state.id ?? this.id;
+    this.dModel = state.dModel ?? this.dModel;
+    this.nHeads = state.nHeads ?? this.nHeads;
+    this.dFF = state.dFF ?? this.dFF;
+    this.step = state.step ?? 0;
+    if (state.ln1Gamma) this.ln1Gamma = Float64Array.from(state.ln1Gamma);
+    if (state.ln1Beta) this.ln1Beta = Float64Array.from(state.ln1Beta);
+    if (state.ln2Gamma) this.ln2Gamma = Float64Array.from(state.ln2Gamma);
+    if (state.ln2Beta) this.ln2Beta = Float64Array.from(state.ln2Beta);
+  }
+}