quantum-spherifier 1.0.0

package/src/core/QSpherifierAgent.js

@@ -0,0 +1,620 @@
+/**
+ * QSpherifierAgent.js — quantum-spherifier (v1.0)
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Main orchestrator. Extends the predator-jungle-agent v2.0 architecture
+ * with a quantum-computing-specialised scientific research loop spanning
+ * four research lines.
+ *
+ * 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
+ *
+ * KEY BEHAVIOUR (AJN "addiction" property):
+ *   - On launch, immediately begins autonomous research (does NOT wait
+ *     for an owner directive — this is the AJN addiction property inherited
+ *     from predator-jungle-agent).
+ *   - Each research cycle:
+ *       1. ResearchLineRouter dispatches to a line (or cross-links two)
+ *       2. Interpret owner directive (or pick under-explored topic autonomously)
+ *       3. Generate hypothesis via HypothesisGenerator (cross-linked to KG)
+ *       4. Assess feasibility via ResourceFeasibilityChecker (real hardware anchors)
+ *       5. If feasible: draft design and patent application
+ *       6. Archive all artifacts under /research/<category>/<topic>/<id>/
+ *       7. Update KG and CitationGraph with cross-links
+ *       8. Periodically rebuild patent clusters
+ *       9. Push progress events to WebSocket subscribers
+ *   - Owner can guide the agent at any time via the web UI or CLI:
+ *       `node scripts/cli.js guide "Focus on surface code distance 11 with neutral atoms"`
+ *
+ * PRINCIPLE: Everything progresses robustly, linking scientific and
+ * technological advances together so nothing stays isolated from reality
+ * and short/mid-term possibility.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+
+import { EventEmitter } from 'eventemitter3';
+import { v4 as uuidv4 } from 'uuid';
+
+import { ANNPsi, QUANTUM_STIMULUS_CLASSES } from './ANNPsi.js';
+import { HierarchicalCommandInterpreter } from '../modules/HierarchicalCommandInterpreter.js';
+import {
+  TokenEnergyArbitrator,
+  PraxicStreamExecutor,
+} from '../modules/TokenEnergyArbitrator.js';
+import { CascadeMonitor } from '../modules/CascadeMonitor.js';
+import { MemorySystem } from '../modules/MemorySystem.js';
+import { SafetyGuardrails } from '../modules/SafetyGuardrails.js';
+import { MetricsCollector } from '../modules/MetricsCollector.js';
+import { PluginManager } from '../modules/PluginManager.js';
+import { QuantumKnowledgeGraph } from '../modules/QuantumKnowledgeGraph.js';
+import { CitationGraph } from '../modules/CitationGraph.js';
+import { HypothesisGenerator } from '../modules/HypothesisGenerator.js';
+import { ResourceFeasibilityChecker } from '../modules/ResourceFeasibilityChecker.js';
+import { DocumentArchivist } from '../modules/DocumentArchivist.js';
+import { PatentDraftAssistant } from '../modules/PatentDraftAssistant.js';
+import { PatentClusterManager } from '../modules/PatentClusterManager.js';
+import { ResearchLineRouter, RESEARCH_LINES } from '../modules/ResearchLineRouter.js';
+
+import { ToolRegistry } from '../tools/ToolRegistry.js';
+import { FileSystemTool } from '../tools/FileSystemTool.js';
+import { LaTeXDocumentTool } from '../tools/LaTeXDocumentTool.js';
+import { QuantumPhysicsTool } from '../tools/QuantumPhysicsTool.js';
+import { WebSearchTool } from '../tools/WebSearchTool.js';
+import { BibliographyTool } from '../tools/BibliographyTool.js';
+
+const DEFAULT_MAX_CYCLES = 50;
+const CYCLE_INTERVAL_MS = 8_000; // 8 seconds between cycles when idle
+
+export class QSpherifierAgent extends EventEmitter {
+  constructor(opts = {}) {
+    super();
+    this.id             = opts.id ?? uuidv4();
+    this.maxCycles      = opts.maxCycles ?? DEFAULT_MAX_CYCLES;
+    this.cycleIntervalMs = opts.cycleIntervalMs ?? CYCLE_INTERVAL_MS;
+    this.autonomousMode = opts.autonomousMode ?? true;
+    this.ownerDirective = null;
+
+    // Core backbone (14-layer ANN-Psi with AJN + Transformer)
+    this.annPsi = new ANNPsi({
+      dModel: opts.dModel ?? 256,
+      nHeads: opts.nHeads ?? 8,
+      dFF: opts.dFF ?? 1024,
+      maxSteps: opts.maxSteps ?? 200,
+    });
+
+    // LLM (router with task routing)
+    this.llm = opts.llm ?? null;
+
+    // Modules
+    this.memory            = new MemorySystem({ llm: this.llm, ...opts.memory });
+    this.safety            = new SafetyGuardrails({ safetyLevel: opts.safetyLevel ?? 'standard' });
+    this.metrics           = new MetricsCollector({ enableConsole: opts.metricsConsole ?? false });
+    this.plugins           = new PluginManager();
+    this.kg                = new QuantumKnowledgeGraph({});
+    this.citations         = new CitationGraph({});
+    this.archivist         = new DocumentArchivist({ rootDir: opts.researchDir ?? './research' });
+    this.feasibility       = new ResourceFeasibilityChecker({ kg: this.kg });
+    this.hypothesisGen     = new HypothesisGenerator({
+      kg: this.kg, llm: this.llm, feasibilityChecker: this.feasibility,
+    });
+    this.patentAssistant   = new PatentDraftAssistant({
+      llm: this.llm, feasibilityChecker: this.feasibility,
+    });
+    this.clusterManager    = new PatentClusterManager({
+      archivist: this.archivist, kg: this.kg, llm: this.llm,
+    });
+    this.router            = new ResearchLineRouter({ kg: this.kg });
+    this.hci               = new HierarchicalCommandInterpreter({
+      llm: this.llm, kg: this.kg,
+    });
+    this.tea               = new TokenEnergyArbitrator({});
+    this.pse               = new PraxicStreamExecutor({ maxRetries: 3 });
+    this.cascade           = new CascadeMonitor({});
+
+    // Tool registry
+    this.tools = new ToolRegistry();
+    this.tools.registerMany([
+      new FileSystemTool({ sandbox: opts.researchDir ?? './research' }),
+      new LaTeXDocumentTool(),
+      new QuantumPhysicsTool(),
+      new WebSearchTool(),
+      new BibliographyTool(),
+    ]);
+    this.pse.registry = this.tools;
+
+    // State
+    this.currentCycle = 0;
+    this.isRunning = false;
+    this._timer = null;
+    this.history = [];
+  }
+
+  // ── Lifecycle ──────────────────────────────────────────────────────────────
+
+  async init() {
+    await this.memory.init();
+    await this.kg.init();
+    await this.citations.init();
+    this.archivist.ensureLayout();
+    this.metrics.start();
+    this.emit('ready', { id: this.id, kg: this.kg.stats() });
+
+    // AUTONOMOUS ACTIVATION: do NOT wait for an owner directive.
+    // This is the AJN "addiction" property — the agent starts working
+    // in its field immediately upon launch.
+    if (this.autonomousMode) {
+      this._scheduleNextCycle(0);
+    }
+  }
+
+  async shutdown() {
+    this.emit('shutdown:start');
+    this.isRunning = false;
+    if (this._timer) clearTimeout(this._timer);
+    await this.kg.persist();
+    await this.citations.persist();
+    this.archivist.rebuildIndices();
+    this.clusterManager.rebuildClusters();
+    this.metrics.stop();
+    this.emit('shutdown:complete');
+  }
+
+  // ── Owner guidance ─────────────────────────────────────────────────────────
+
+  async guide(directive) {
+    this.ownerDirective = directive;
+    this.emit('owner:directive', { directive });
+    // Force-start a new cycle immediately
+    if (!this.isRunning) this._scheduleNextCycle(0);
+    return { accepted: true, directive };
+  }
+
+  // ── Research cycle ─────────────────────────────────────────────────────────
+
+  _scheduleNextCycle(delay = this.cycleIntervalMs) {
+    if (this._timer) clearTimeout(this._timer);
+    this._timer = setTimeout(() => this._runCycle().catch(err => {
+      this.emit('cycle:error', { error: err.message });
+      this._scheduleNextCycle();
+    }), delay);
+  }
+
+  async _runCycle() {
+    if (this.currentCycle >= this.maxCycles) {
+      this.emit('cycles:exhausted', { count: this.currentCycle });
+      return;
+    }
+    this.isRunning = true;
+    this.currentCycle++;
+    const cycleId = `cycle_${this.currentCycle}_${Date.now()}`;
+    this.emit('cycle:start', { cycleId, count: this.currentCycle });
+
+    try {
+      // 1. Safety check before any work
+      const safetyCheck = this.safety.check({
+        type: 'research_cycle',
+        payload: { directive: this.ownerDirective },
+      });
+      if (!safetyCheck.allowed) {
+        this.emit('safety:blocked', safetyCheck);
+        this.isRunning = false;
+        this._scheduleNextCycle();
+        return;
+      }
+
+      // 2. Route to a research line (or cross-link)
+      const routing = this.router.route(this.ownerDirective);
+      this.emit('routed', routing);
+      const lineDesc = this.router.describe(routing.line);
+
+      // 3. Interpret owner directive (or autonomous plan)
+      const plan = await this.hci.interpret(this.ownerDirective);
+      if (plan.researchLine && !routing.crossLink) {
+        routing.line = plan.researchLine;
+      }
+      this.emit('plan:interpreted', { ...plan, researchLine: routing.line, crossLink: routing.crossLink });
+
+      // 4. Forward pass through ANN-Psi
+      const stimulus = {
+        intensity: 0.6 + Math.random() * 0.4,
+        topic: plan.topic ?? routing.seedTopic,
+        researchLine: routing.line,
+        parameters: plan.parameters,
+      };
+      const annResult = this.annPsi.forward(stimulus);
+      this.emit('annPsi:forward', annResult);
+
+      // 5. Generate hypothesis (cross-linked to KG — nothing isolated)
+      const hypotheses = await this.hypothesisGen.generate({
+        count: 1,
+        researchLine: routing.line,
+        seedTopic: plan.topic ?? routing.seedTopic,
+        ownerDirective: this.ownerDirective,
+        crossLink: routing.crossLink,
+        pairedLine: routing.pairedLine,
+      });
+      const hypothesis = hypotheses[0];
+      this.emit('hypothesis:generated', hypothesis);
+      this.metrics.incrementCounter('hypotheses_generated');
+      this.metrics.incrementCounter(`hypotheses_${routing.line}`);
+
+      // 6. Archive the hypothesis document
+      const hypRecord = this.archivist.archive({
+        category: 'hypotheses',
+        title: hypothesis.statement?.slice(0, 100) ?? `Hypothesis ${hypothesis.id}`,
+        topic: routing.line,
+        researchLine: routing.line,
+        markdownSource: this._hypothesisToMarkdown(hypothesis, lineDesc),
+        tags: this._tagsForHypothesis(hypothesis, routing),
+        references: hypothesis.supportingConcepts ?? [],
+        crossLinks: this._findCrossLinks(hypothesis),
+        patent: {
+          eligible: hypothesis.feasibility?.patentEligible ?? false,
+          claims: hypothesis.candidatePatentClaims ?? [],
+        },
+        extra: { hypothesis, routing },
+      });
+      this.emit('document:archived', hypRecord);
+      this.metrics.incrementCounter('documents_produced');
+
+      // 7. Update KG with new concepts from the hypothesis
+      this._updateKGFromHypothesis(hypothesis, routing);
+
+      // 8. If feasibility is OK, draft a patent application
+      if (hypothesis.feasibility?.tier && hypothesis.feasibility.tier !== 'speculative') {
+        const patentDraft = await this.patentAssistant.draft({
+          hypothesis,
+          parameters: plan.parameters,
+          researchLine: routing.line,
+        });
+        this.emit('patent:drafted', patentDraft);
+        this.metrics.incrementCounter('patents_drafted');
+
+        const patentRecord = this.archivist.archive({
+          category: 'patents',
+          title: patentDraft.title,
+          topic: routing.line,
+          researchLine: routing.line,
+          markdownSource: this._patentToMarkdown(patentDraft),
+          latexSource: this._patentToLatex(patentDraft),
+          tags: hypothesis.feasibility?.tier === 'near_term' || hypothesis.feasibility?.tier === 'current'
+            ? ['patent_ready', 'final_result', this._lineTag(routing.line)]
+            : ['patent_pending', 'intermediate_result', this._lineTag(routing.line)],
+          references: hypothesis.supportingConcepts ?? [],
+          crossLinks: this._findCrossLinks(hypothesis),
+          patent: {
+            eligible: true,
+            claims: patentDraft.claims?.map(c => c.text) ?? [],
+          },
+          extra: { patentDraft, hypothesisId: hypothesis.id },
+        });
+        this.emit('document:archived', patentRecord);
+        this.metrics.incrementCounter('documents_produced');
+      }
+
+      // 9. Memory + metrics update
+      await this.memory.store(`cycle_${this.currentCycle}`, {
+        hypothesis: hypothesis.id,
+        plan,
+        routing,
+        feasibility: hypothesis.feasibility,
+      });
+      this.metrics.observeHistogram('average_quality',
+        hypothesis.rewardComponents?.quality ?? 0.5);
+      this.metrics.observeHistogram('average_feasibility',
+        hypothesis.feasibility?.confidence ?? 0.5);
+      this.metrics.observeHistogram('average_patentability',
+        hypothesis.patentabilityHint === 'YES' ? 1.0
+        : hypothesis.patentabilityHint === 'MAYBE' ? 0.5 : 0.0);
+      this.metrics.setGauge('current_cycle', this.currentCycle);
+      this.metrics.setGauge('kg_nodes', this.kg.nodes.size);
+      this.metrics.setGauge('kg_edges', this.kg.edges.size);
+
+      // 10. Plugin hooks
+      await this.plugins.runHook('afterStep', { cycleId, hypothesis, routing });
+
+      // 11. Rebuild indices and clusters periodically
+      if (this.currentCycle % 5 === 0) {
+        this.archivist.rebuildIndices();
+        const clusters = this.clusterManager.rebuildClusters();
+        this.emit('clusters:rebuilt', this.clusterManager.stats());
+        if (clusters.some(c => c.filingReady)) {
+          this.emit('clusters:filing_ready', this.clusterManager.filingReadyClusters());
+        }
+      }
+
+      this.history.push({ cycleId, plan, routing, hypothesis, timestamp: Date.now() });
+      this.emit('cycle:complete', { cycleId, hypothesis, routing });
+    } catch (err) {
+      this.emit('cycle:error', { cycleId, error: err.message });
+      this.cascade.record({ type: 'error', error: err.message });
+    }
+
+    this.isRunning = false;
+    this._scheduleNextCycle();
+  }
+
+  // ── Cross-linking helpers ──────────────────────────────────────────────────
+
+  _findCrossLinks(hypothesis) {
+    // Find existing documents that share KG concepts with this hypothesis
+    const concepts = new Set(hypothesis.supportingConcepts ?? []);
+    if (concepts.size === 0) return [];
+    const all = this.archivist.list();
+    return all
+      .filter(r => r.manifest.id !== hypothesis.id)
+      .map(r => {
+        const otherConcepts = new Set(r.manifest.extra?.hypothesis?.supportingConcepts ?? []);
+        const shared = [...concepts].filter(c => otherConcepts.has(c));
+        return { id: r.manifest.id, shared: shared.length, relationship: shared.length >= 2 ? 'builds_on' : 'related' };
+      })
+      .filter(x => x.shared > 0)
+      .slice(0, 5);
+  }
+
+  _updateKGFromHypothesis(hypothesis, routing) {
+    // Ensure all supporting concepts exist as KG nodes; add cross-link edges
+    const concepts = hypothesis.supportingConcepts ?? [];
+    for (let i = 0; i < concepts.length; i++) {
+      const c = concepts[i];
+      if (!this.kg.nodes.has(c)) continue;
+      for (let j = i + 1; j < concepts.length; j++) {
+        const c2 = concepts[j];
+        if (!this.kg.nodes.has(c2)) continue;
+        // Check if edge already exists
+        let exists = false;
+        for (const edge of this.kg.edges.values()) {
+          if ((edge.from === c && edge.to === c2) || (edge.from === c2 && edge.to === c)) {
+            exists = true;
+            break;
+          }
+        }
+        if (!exists) {
+          try {
+            this.kg.addEdge({ from: c, to: c2, type: 'cross_links', weight: 0.5,
+              evidence: [`Linked by hypothesis ${hypothesis.id}`] });
+          } catch {}
+        }
+      }
+    }
+  }
+
+  _tagsForHypothesis(hypothesis, routing) {
+    const tags = [this._lineTag(routing.line)];
+    if (routing.crossLink) tags.push('cross_linked');
+    if (hypothesis.feasibility?.tier === 'near_term' || hypothesis.feasibility?.tier === 'current') {
+      tags.push('patent_ready', 'final_result');
+    } else {
+      tags.push('intermediate_result');
+    }
+    if (this.ownerDirective) tags.push('human_directed');
+    return tags;
+  }
+
+  _lineTag(line) {
+    return {
+      quantum_error_correction: 'qec',
+      new_qubit_modalities: 'qubits',
+      quantum_algorithms: 'algorithms',
+      molecular_simulation: 'molecular_simulation',
+    }[line] ?? 'cross_cutting';
+  }
+
+  // ── Document renderers ─────────────────────────────────────────────────────
+
+  _hypothesisToMarkdown(h, lineDesc) {
+    return [
+      `# ${h.statement?.slice(0, 120) ?? 'Hypothesis'}`,
+      '',
+      `**ID:** ${h.id}`,
+      `**Research Line:** ${h.researchLine ?? 'unknown'}${h.crossLink ? ` (cross-linking with ${h.pairedLine})` : ''}`,
+      `**Source:** ${h.source ?? 'unknown'}`,
+      `**Created:** ${new Date(h.createdAt ?? Date.now()).toISOString()}`,
+      '',
+      `## Research Line: ${lineDesc?.label ?? h.researchLine}`,
+      '',
+      lineDesc?.goal ?? '',
+      '',
+      '## Statement',
+      '',
+      h.statement ?? '',
+      '',
+      '## Rationale',
+      '',
+      h.rationale ?? '',
+      '',
+      '## Supporting Concepts (Cross-Links)',
+      '',
+      '> quantum-spherifier principle: every hypothesis must cross-link to the KG — nothing stays isolated.',
+      '',
+      ...(h.supportingConcepts ?? []).map(c => `- ${c}`),
+      '',
+      '## Predicted Impact',
+      '',
+      h.predictedImpact
+        ? `Metric: **${h.predictedImpact.metric}** — ${h.predictedImpact.direction} by ${h.predictedImpact.magnitude}`
+        : '_not specified_',
+      '',
+      '## Feasibility Assessment',
+      '',
+      h.feasibility
+        ? [
+            `Tier: **${h.feasibility.tier}** (confidence ${h.feasibility.confidence ?? 'n/a'})`,
+            '',
+            '### Resource Anchors',
+            '',
+            ...(h.feasibility.anchors ?? []).map(a => `- ${a.label}`),
+            '',
+            '### Identified Gaps',
+            '',
+            ...(h.feasibility.gaps ?? []).map(g => `- ${g}`),
+            '',
+            '### Resource Profile',
+            '',
+            `Physical qubits: ${h.feasibility.resourceProfile?.physicalQubits ?? '—'}`,
+            `Logical qubits: ${h.feasibility.resourceProfile?.logicalQubits ?? '—'}`,
+            `Code distance: ${h.feasibility.resourceProfile?.codeDistance ?? '—'}`,
+            `Modality: ${h.feasibility.resourceProfile?.modality ?? '—'}`,
+            `Operating temp: ${h.feasibility.resourceProfile?.operatingTemp ?? '—'}`,
+            '',
+            '### Cross-Link Verification',
+            '',
+            h.feasibility.crossLinks?.sufficient
+              ? `✓ Solution is cross-linked to ${h.feasibility.crossLinks.linkedConcepts} KG concept(s).`
+              : `⚠ WARNING: solution may be isolated — only ${h.feasibility.crossLinks?.linkedConcepts ?? 0} KG concept(s) referenced.`,
+          ].join('\n')
+        : '_not yet assessed_',
+      '',
+      '## Proposed Experiments',
+      '',
+      ...(h.proposedExperiments ?? []).map(e => `- ${e}`),
+      '',
+      '## Candidate Patent Claims',
+      '',
+      ...(h.candidatePatentClaims ?? []).map((c, i) => `${i + 1}. ${c}`),
+      '',
+    ].join('\n');
+  }
+
+  _patentToMarkdown(p) {
+    return [
+      `# ${p.title}`,
+      '',
+      `**Patent Draft ID:** ${p.id}`,
+      `**Research Line:** ${p.researchLine ?? 'unknown'}`,
+      `**Source:** ${p.source ?? 'unknown'}${p.llmAdapter ? ` (${p.llmAdapter})` : ''}`,
+      `**Created:** ${new Date(p.createdAt ?? Date.now()).toISOString()}`,
+      '',
+      '## Abstract',
+      '',
+      p.abstract ?? '',
+      '',
+      '## Field of the Invention',
+      '',
+      p.field ?? '',
+      '',
+      '## Background',
+      '',
+      p.background ?? '',
+      '',
+      '## Summary',
+      '',
+      p.summary ?? '',
+      '',
+      '## Brief Description of Drawings',
+      '',
+      ...(p.drawings ?? []).map(d => `- ${d}`),
+      '',
+      '## Detailed Description',
+      '',
+      '```',
+      p.detailedDescription ?? '',
+      '```',
+      '',
+      '## Claims',
+      '',
+      ...(p.claims ?? []).map(c => `**Claim ${c.number}** (${c.kind}): ${c.text}`),
+      '',
+    ].join('\n');
+  }
+
+  _patentToLatex(p) {
+    const claims = (p.claims ?? [])
+      .map(c => `\\item[${c.kind}] ${c.text.replace(/\n/g, ' ')}`)
+      .join('\n');
+    return [
+      '\\documentclass[11pt]{article}',
+      '\\usepackage[utf8]{inputenc}',
+      '\\usepackage{hyperref}',
+      '\\usepackage{amsmath}',
+      '\\usepackage{amssymb}',
+      '\\title{' + (p.title ?? 'Untitled') + '}',
+      '\\author{quantum-spherifier Autonomous Patent Drafter}',
+      '\\date{\\today}',
+      '\\begin{document}',
+      '\\maketitle',
+      '',
+      '\\begin{abstract}',
+      p.abstract ?? '',
+      '\\end{abstract}',
+      '',
+      '\\section{Field of the Invention}',
+      p.field ?? '',
+      '',
+      '\\section{Background}',
+      p.background ?? '',
+      '',
+      '\\section{Summary}',
+      p.summary ?? '',
+      '',
+      '\\section{Brief Description of Drawings}',
+      '\\begin{itemize}',
+      ...(p.drawings ?? []).map(d => `  \\item ${d}`),
+      '\\end{itemize}',
+      '',
+      '\\section{Detailed Description}',
+      '\\begin{verbatim}',
+      p.detailedDescription ?? '',
+      '\\end{verbatim}',
+      '',
+      '\\section{Claims}',
+      '\\begin{enumerate}',
+      claims,
+      '\\end{enumerate}',
+      '',
+      '\\end{document}',
+    ].join('\n');
+  }
+
+  // ── Status & serialisation ─────────────────────────────────────────────────
+
+  status() {
+    return {
+      id: this.id,
+      currentCycle: this.currentCycle,
+      maxCycles: this.maxCycles,
+      isRunning: this.isRunning,
+      autonomousMode: this.autonomousMode,
+      ownerDirective: this.ownerDirective,
+      annPsi: this.annPsi.status(),
+      memory: this.memory.stats(),
+      kg: this.kg.stats(),
+      citations: this.citations.stats(),
+      archive: this.archivist.stats(),
+      clusters: this.clusterManager.stats(),
+      router: this.router.stats(),
+      cascade: this.cascade.status(),
+      tools: this.tools.list().map(t => t.id),
+      metrics: this.metrics.getSummary(),
+      llm: this.llm?.metadata?.() ?? this.llm?.constructor?.name ?? 'none',
+    };
+  }
+
+  serialize() {
+    return {
+      id: this.id,
+      currentCycle: this.currentCycle,
+      maxCycles: this.maxCycles,
+      autonomousMode: this.autonomousMode,
+      ownerDirective: this.ownerDirective,
+      annPsi: this.annPsi.serialize(),
+      router: this.router.stats(),
+      history: this.history.slice(-100),
+    };
+  }
+
+  deserialize(state) {
+    this.id = state.id ?? this.id;
+    this.currentCycle = state.currentCycle ?? 0;
+    this.maxCycles = state.maxCycles ?? this.maxCycles;
+    this.autonomousMode = state.autonomousMode ?? this.autonomousMode;
+    this.ownerDirective = state.ownerDirective ?? null;
+    if (state.annPsi) this.annPsi.deserialize(state.annPsi);
+    if (state.history) this.history = state.history;
+  }
+}
+
+export { QUANTUM_STIMULUS_CLASSES, RESEARCH_LINES };

package/src/core/StateSerializer.js

@@ -0,0 +1,74 @@
+/**
+ * StateSerializer.js — FUSIONARY (v1.0)
+ * Saves/loads full agent state as versioned JSON files.
+ */
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { v4 as uuidv4 } from 'uuid';
+
+export class StateSerializer {
+  constructor(opts = {}) {
+    this.checkpointDir = opts.checkpointDir ?? './data/checkpoints';
+    this.maxCheckpoints = opts.maxCheckpoints ?? 20;
+  }
+
+  async save(agent, label = 'checkpoint') {
+    if (!existsSync(this.checkpointDir)) mkdirSync(this.checkpointDir, { recursive: true });
+    const id = uuidv4();
+    const timestamp = Date.now();
+    const filename = `${timestamp}_${label.replace(/[^a-zA-Z0-9_-]/g, '_')}.json`;
+    const filepath = join(this.checkpointDir, filename);
+    const state = {
+      version: '1.0',
+      id,
+      label,
+      timestamp,
+      agentState: agent.serialize(),
+    };
+    writeFileSync(filepath, JSON.stringify(state, null, 2));
+    this._prune();
+    return { id, label, filepath };
+  }
+
+  async load(agent, labelOrId) {
+    if (!existsSync(this.checkpointDir)) return null;
+    const files = readdirSync(this.checkpointDir)
+      .filter(f => f.endsWith('.json'))
+      .sort()
+      .reverse();
+    for (const f of files) {
+      if (f.includes(labelOrId)) {
+        const state = JSON.parse(readFileSync(join(this.checkpointDir, f), 'utf8'));
+        agent.deserialize(state.agentState);
+        return { label: state.label, timestamp: state.timestamp };
+      }
+    }
+    return null;
+  }
+
+  list() {
+    if (!existsSync(this.checkpointDir)) return [];
+    return readdirSync(this.checkpointDir)
+      .filter(f => f.endsWith('.json'))
+      .sort()
+      .reverse()
+      .map(f => {
+        try {
+          const s = JSON.parse(readFileSync(join(this.checkpointDir, f), 'utf8'));
+          return { file: f, label: s.label, timestamp: s.timestamp };
+        } catch { return null; }
+      })
+      .filter(Boolean);
+  }
+
+  _prune() {
+    const files = readdirSync(this.checkpointDir)
+      .filter(f => f.endsWith('.json'))
+      .sort();
+    while (files.length > this.maxCheckpoints) {
+      const oldest = files.shift();
+      try { unlinkSync(join(this.checkpointDir, oldest)); } catch {}
+    }
+  }
+}