Add deterministic seeding for generation (#13)

Author: recursive-ai-dev

LOGIC-MAP.md

@@ -84,3 +84,16 @@ This document explains the logic chain for updating `UPDATES_STRATEGY.md` with s
    - **Why:** Verb transitivity must guide whether direct objects appear; adverbs must originate from the lexicon; lyric corpus should load real files when available.
    - **Invariant:** Transitive verbs prefer `V NP`, intransitives avoid object insertion; adverbs are derived from `lexicon.Adv`; corpus loading resolves `/lyrics/*.txt` entries before falling back to embedded lines.
    - **Proof Sketch:** The VP generator branches on `feats.trans` with explicit paths, and `import.meta.glob` enumerates real assets, ensuring coverage without mock fillers.
+
+## Logic Chain: Deterministic Seeding & RNG Propagation (Steps 1–3)
+1. **Identify nondeterministic sources**
+   - **Why:** Kernel PCA initialization, TD(λ) weights, and grammar generation relied on implicit randomness, making runs irreproducible.
+   - **Invariant:** All stochastic paths must consume a single seeded RNG when provided.
+2. **Centralize seeded RNG consumption**
+   - **Why:** A single RNG source enables reproducible training and generation across components.
+   - **Invariant:** KernelPCA, TDValueEstimator, and ConstraintGrammar call the same RNG instance or function.
+   - **Proof Sketch:** Each component accepts a `rng` dependency and defers calls to `rng()` or `rng.next()`, so the RNG state advances deterministically in a single sequence.
+3. **Define deterministic seed resolution**
+   - **Why:** Users need a stable way to set seeds without UI changes.
+   - **Invariant:** When `?seed=` is provided, the engine seed is deterministic for both numeric and string inputs; otherwise, default entropy is used.
+   - **Proof Sketch:** Numeric seeds map directly; string seeds use a deterministic hash (`fnv-1a`), so identical inputs always map to the same 32-bit seed.

TESTING.md

@@ -73,3 +73,21 @@ Each test uses real logic paths without mock data. Run the generation/analysis m
 ## Execution Notes
 - Use the existing UI controls to trigger sentence generation and analysis for cases 1–8.
 - For corpus validation (cases 9–12), temporarily log the returned array length and sample entries after invoking `loadLyricsCorpus`.
+
+## Test Matrix: Deterministic Seeding & RNG Propagation
+Run generation with `?seed=` in the URL and confirm reproducible output across reloads.
+
+- **-1:** `?seed=` empty string should fall back to default entropy (non-deterministic across reloads).
+- **0:** `?seed=0` yields a stable poem across reloads.
+- **1:** `?seed=1` yields a stable poem across reloads.
+- **2:** `?seed=2` yields a stable poem across reloads.
+- **3:** `?seed=3` yields a stable poem across reloads.
+- **4:** `?seed=-42` yields a stable poem across reloads.
+- **5:** `?seed=3.14` is floored to `3` and yields stable output.
+- **6:** `?seed=00012` resolves to `12` and yields stable output.
+- **7:** `?seed=alpha` hashes to a deterministic 32-bit seed and yields stable output.
+- **8:** `?seed=alpha` matches identical output across browsers (same seed string).
+- **9:** `?seed=alpha-beta` yields a different but stable output from `alpha`.
+- **10:** `?seed=9999999999` yields stable output without overflow errors.
+- **11:** Remove `?seed=` after using a deterministic seed to confirm non-deterministic default again.
+- **12:** Load a checkpoint after setting `?seed=` and confirm continued deterministic generation.

WE-CHOSE.md

@@ -77,3 +77,24 @@ Document the three-perspective planning approach for the formatting adjustment i
 - **End Customer:** Higher phonetic and grammatical coherence improves usability.
 
 **Mapped logic chain reference:** LOGIC-MAP.md (Steps 1–3, Linguistic Engine & Corpus Loading).
+
+# Perspective Selection: Deterministic Seeding & RNG Propagation
+
+### CEO Perspective
+- **Goal:** Provide repeatable outcomes for demos, testing, and stakeholder review.
+- **Choice:** Single seeded RNG enables consistent outputs when `?seed=` is supplied.
+
+### Junior Developer Perspective
+- **Goal:** Make randomness easy to reason about and debug.
+- **Choice:** Central RNG injection removes hidden `Math.random()` usage and simplifies tracing.
+
+### End Customer Perspective
+- **Goal:** Allow users to reproduce poems or training runs reliably.
+- **Choice:** Seed parsing accepts numeric and string values without requiring new UI controls.
+
+### Combined Choice Justification
+- **CEO:** Repeatable results reduce demo risk and simplify acceptance validation.
+- **Junior Dev:** Shared RNG path avoids fragmented randomness sources.
+- **End Customer:** Reproducible outputs improve trust and usability.
+
+**Mapped logic chain reference:** LOGIC-MAP.md (Steps 1–3, Deterministic Seeding & RNG Propagation).

src/App.jsx

@@ -23,17 +23,39 @@ import { UniversalLinguisticEngine } from './UniversalLinguisticEngine';
 // CORE ALGORITHM IMPLEMENTATIONS
 // ============================================================================
 
+const hashSeedString = (value) => {
+  let hash = 2166136261;
+  for (let i = 0; i < value.length; i++) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+};
+
+const resolveSeedFromLocation = () => {
+  if (typeof window === 'undefined') return null;
+  const params = new URLSearchParams(window.location.search);
+  const seedParam = params.get('seed');
+  if (seedParam === null) return null;
+  const normalized = seedParam.trim();
+  if (!normalized) return null;
+  const parsed = Number(normalized);
+  if (Number.isFinite(parsed)) return Math.floor(parsed);
+  return hashSeedString(normalized);
+};
+
 /**
  * Kernel PCA for Non-linear Theme Embedding
  * Transforms word embeddings into emotional/thematic space using polynomial kernel
  */
 class KernelPCA {
-  constructor(nComponents = 12, degree = 3) {
+  constructor(nComponents = 12, degree = 3, rng = Math.random) {
     this.nComponents = nComponents;
     this.degree = degree;
     this.eigenvectors = null;
     this.eigenvalues = null;
     this.X_fit = null;
+    this.rng = rng;
   }
 
   /**
@@ -90,8 +112,8 @@ class KernelPCA {
 
     for (let k = 0; k < Math.min(this.nComponents, n); k++) {
       // Initialize random vector for PCA eigenvalue decomposition
-      // Math.random() is acceptable here: used for ML initialization, not cryptographic purposes
-      let v = Array(n).fill().map(() => Math.random() - 0.5);
+      // Non-cryptographic RNG allows deterministic seeding when provided.
+      let v = Array(n).fill().map(() => this.rng() - 0.5);
 
       // Gram-Schmidt orthogonalization against previous eigenvectors
       for (let i = 0; i < eigenvectors.length; i++) {
@@ -178,9 +200,9 @@ class KernelPCA {
  * Estimates aesthetic value of poetic states for reinforcement learning
  */
 class TDValueEstimator {
-  constructor(nFeatures = 24, alpha = 0.01, gamma = 0.95, lambda = 0.8) {
-    // Math.random() is acceptable here: used for neural network weight initialization, not cryptographic purposes
-    this.weights = Array(nFeatures).fill(0).map(() => Math.random() * 0.01);
+  constructor(nFeatures = 24, alpha = 0.01, gamma = 0.95, lambda = 0.8, rng = Math.random) {
+    // Non-cryptographic RNG allows deterministic seeding when provided.
+    this.weights = Array(nFeatures).fill(0).map(() => rng() * 0.01);
     this.alpha = alpha;
     this.gamma = gamma;
     this.lambda = lambda;
@@ -477,12 +499,13 @@ class FFTMeterAnalyzer {
  * Orchestrates all algorithms for multi-objective poetry generation
  */
 class AGTuneEngine {
-  constructor() {
-    this.kpca = new KernelPCA(12, 3);
-    this.valueEstimator = new TDValueEstimator(24, 0.01, 0.95, 0.8);
-    this.rng = new LaggedFibonacciGenerator();
+  constructor(seed = Date.now()) {
+    this.rng = new LaggedFibonacciGenerator(seed);
+    const rng = () => this.rng.next();
+    this.kpca = new KernelPCA(12, 3, rng);
+    this.valueEstimator = new TDValueEstimator(24, 0.01, 0.95, 0.8, rng);
     this.rete = new ReteEngine();
-    this.ule = new UniversalLinguisticEngine(); // Integration of Production-Grade Logic
+    this.ule = new UniversalLinguisticEngine({ rng: this.rng }); // Integration of Production-Grade Logic
     this.parser = new CYKParser(this.ule.getGrammar());
     this.vocabulary = new Set();
     this.embeddings = new Map();
@@ -737,7 +760,11 @@ class AGTuneEngine {
     }
 
     // Restore KPCA (defensively sanitize numeric content)
-    this.kpca = new KernelPCA(data.kpca?.nComponents || 8, data.kpca?.degree || 3);
+    this.kpca = new KernelPCA(
+      data.kpca?.nComponents || 8,
+      data.kpca?.degree || 3,
+      () => this.rng.next()
+    );
     this.kpca.eigenvectors = this._asNumberMatrix(data.kpca?.eigenvectors);
     this.kpca.eigenvalues = this._asNumberArray(data.kpca?.eigenvalues);
     this.kpca.X_fit = this._asNumberMatrix(data.kpca?.X_fit);
@@ -747,7 +774,8 @@ class AGTuneEngine {
       data.valueEstimator?.weights?.length || 16,
       data.valueEstimator?.alpha ?? 0.01,
       data.valueEstimator?.gamma ?? 0.95,
-      data.valueEstimator?.lambda ?? 0.8
+      data.valueEstimator?.lambda ?? 0.8,
+      () => this.rng.next()
     );
     this.valueEstimator.weights = this._asNumberArray(
       data.valueEstimator?.weights,
@@ -859,8 +887,8 @@ class AGTuneEngine {
 
     const scored = candidates.map(word => {
       const eSpace = this.emotionalSpace.get(word);
-      // Math.random() is acceptable here: used for fallback scoring in ML algorithm, not cryptographic purposes
-      if (!eSpace) return { word, score: Math.random() };
+      // Non-cryptographic RNG allows deterministic seeding when provided.
+      if (!eSpace) return { word, score: this.rng.next() };
 
       const dist = Math.sqrt(eSpace.reduce((sum, v, i) => {
         const diff = v - (lastESpace[i] || 0);
@@ -1029,7 +1057,10 @@ class AGTuneEngine {
  * Interactive interface for training and poetry generation
  */
 export default function AGTunePoet() {
-  const [engine] = useState(() => new AGTuneEngine());
+  const [engine] = useState(() => {
+    const seed = resolveSeedFromLocation();
+    return new AGTuneEngine(Number.isFinite(seed) ? seed : Date.now());
+  });
   const [corpus, setCorpus] = useState([]);
   const [trainingState, setTrainingState] = useState({
     isTraining: false,

src/UniversalLinguisticEngine.js

@@ -8,9 +8,10 @@
  * Replaces static lookup tables with algorithmic reasoning.
  */
 export class UniversalLinguisticEngine {
-  constructor() {
+  constructor({ rng } = {}) {
+    this.rng = rng;
     this.phonetics = new PhoneticEngine();
-    this.grammar = new ConstraintGrammar();
+    this.grammar = new ConstraintGrammar(rng);
   }
 
   /**
@@ -303,10 +304,21 @@ class PhoneticEngine {
  * Supports agreement (Number, Person, Tense) and recursive generation.
  */
 class ConstraintGrammar {
-  constructor() {
+  constructor(rng) {
+    this.rng = rng;
     this.lexicon = this._buildProductionLexicon();
   }
 
+  _random() {
+    if (this.rng && typeof this.rng.next === 'function') {
+      return this.rng.next();
+    }
+    if (typeof this.rng === 'function') {
+      return this.rng();
+    }
+    return Math.random();
+  }
+
   _buildProductionLexicon() {
     // Extensive Lexicon categorized by features
     return {
@@ -425,11 +437,11 @@ class ConstraintGrammar {
       if (candidates.length === 0) {
         // Fallback: relax constraints if too strict (simple error recovery)
         if (this.lexicon[symbol].length > 0) {
-             return this.lexicon[symbol][Math.floor(Math.random() * this.lexicon[symbol].length)];
+             return this.lexicon[symbol][Math.floor(this._random() * this.lexicon[symbol].length)];
         }
         return null;
       }
-      return candidates[Math.floor(Math.random() * candidates.length)];
+      return candidates[Math.floor(this._random() * candidates.length)];
   }
 
   /**
@@ -447,18 +459,18 @@ class ConstraintGrammar {
       case 'S':
         // S -> NP VP
         // We decide on a 'number' feature for the subject, which propagates to VP
-        const num = Math.random() > 0.5 ? 'sg' : 'pl';
+        const num = this._random() > 0.5 ? 'sg' : 'pl';
         return `${this.generate('NP', { num })} ${this.generate('VP', { num })}`;
 
       case 'NP': {
         // NP -> Det N | Det Adj N | N (plural/abstract) | Det Adj Adj N
-        const r = Math.random();
+        const r = this._random();
 
         // If constraint is not provided, we should decide on one internally so Det and N agree.
         // If external constraints exists (from S), we use them.
         let localConstraints = { ...constraints };
         if (!localConstraints.num) {
-            localConstraints.num = Math.random() > 0.5 ? 'sg' : 'pl';
+            localConstraints.num = this._random() > 0.5 ? 'sg' : 'pl';
         }
 
         if (r < 0.35) {
@@ -493,13 +505,13 @@ class ConstraintGrammar {
 
         // Optional Adverb prefix
         let prefix = "";
-        if (Math.random() < 0.25) {
+        if (this._random() < 0.25) {
             prefix = this.generate('Adv') + " ";
         }
 
         if (trans === 'intrans') {
             // Intransitive: V or V PP
-            if (Math.random() < 0.4) {
+            if (this._random() < 0.4) {
                  return `${prefix}${verb} ${this.generate('PP')}`;
             }
             return `${prefix}${verb}`;
@@ -508,7 +520,7 @@ class ConstraintGrammar {
             // Note: Object NP doesn't need to agree with Subject (constraints), so we pass empty constraints
             // or specific ones (like Accusative case if we had cases)
             // Passing empty constraints allows NP to pick its own number agreement
-             if (Math.random() < 0.2) {
+             if (this._random() < 0.2) {
                  return `${prefix}${verb} ${this.generate('NP')} ${this.generate('PP')}`;
              }
              return `${prefix}${verb} ${this.generate('NP')}`;
@@ -562,10 +574,10 @@ class ConstraintGrammar {
     });
 
     if (candidates.length > 0) {
-      return candidates[Math.floor(Math.random() * candidates.length)];
+      return candidates[Math.floor(this._random() * candidates.length)];
     }
     if (entries.length > 0) {
-      return entries[Math.floor(Math.random() * entries.length)];
+      return entries[Math.floor(this._random() * entries.length)];
     }
     return { word: '?' };
   }