@seanhogg/builderforce-memory 2026.6.35 → 2026.7.11

package/src/memory/MemoryStore.ts

@@ -328,6 +328,16 @@ export class MemoryStore {
      * reason, it transparently falls back to Jaccard word-overlap similarity.
      */
     async recallSimilar(query: string, topK: number, runtime?: SSMRuntimeRef): Promise<MemoryEntry[]> {
+        return (await this.recallSimilarScored(query, topK, runtime)).map(s => s.entry);
+    }
+
+    /**
+     * Like {@link recallSimilar} but returns each hit's real 0..1 relevance score
+     * (SSM-embedding cosine, or Jaccard on the fallback path) alongside the entry —
+     * so callers can rank/threshold by TRUE similarity instead of list position.
+     * {@link recallSimilar} is the score-dropping convenience wrapper over this.
+     */
+    async recallSimilarScored(query: string, topK: number, runtime?: SSMRuntimeRef): Promise<Array<{ entry: MemoryEntry; score: number }>> {
         const all = await this.recallAll();
         if (all.length === 0) return [];
 
@@ -344,7 +354,9 @@ export class MemoryStore {
                         ? synced.index.search(queryVec, topK)
                         // Below it, an exact scan over the (already-embedded) vectors.
                         : denseSearch(queryVec, synced.items, topK, this._annThreshold);
-                    return hits.map(h => synced.byKey.get(h.id)).filter((e): e is MemoryEntry => !!e);
+                    return hits
+                        .map(h => { const entry = synced.byKey.get(h.id); return entry ? { entry, score: h.score } : null; })
+                        .filter((e): e is { entry: MemoryEntry; score: number } => !!e);
                 }
             }
             // Any failure falls through to the Jaccard path below.
@@ -359,7 +371,7 @@ export class MemoryStore {
         });
 
         scored.sort((a, b) => b.score - a.score);
-        return scored.slice(0, topK).map(s => s.entry);
+        return scored.slice(0, topK);
     }
 
     /**

package/src/session/session.ts

@@ -160,12 +160,34 @@ export interface AdaptOptions {
     wsla?         : boolean;  // Default: true  (WSLA fast-adapt mode)
     fullTrain?    : boolean;  // Convenience alias: sets wsla=false and epochs=5
     onProgress?   : (epoch: number, loss: number) => void;
+    /**
+     * Snapshot the weights before adapting and RESTORE them if the adapt produced
+     * a non-finite loss or clearly regressed the model's perplexity on the same
+     * text. Default true — this is the last line of defence behind WSLA + the
+     * per-step trust region that keeps write-through learning from "dying after
+     * several executions". Set false to skip the snapshot cost (e.g. bulk full
+     * training where you validate externally).
+     */
+    rollbackOnRegression? : boolean;  // Default: true
+    /** Regression tolerance: roll back if post-perplexity > pre × this. Default 1.25. */
+    regressionTolerance?  : number;
 }
 
 export interface AdaptResult {
     losses     : number[];
     epochCount : number;
     durationMs : number;
+    /** True when the adapt was reverted to the pre-adapt snapshot (see below). */
+    rolledBack?    : boolean;
+    /** Why it rolled back, when it did (`non-finite loss` | `perplexity regression`). */
+    rollbackReason?: string;
+    /** Perplexity on the adapt text before / after (when measured). */
+    perplexityBefore?: number;
+    perplexityAfter? : number;
+    /** Mean pre-clip gradient L2 norm across the adapt's epochs — the standard
+     *  early-warning for an unstable update (it spikes before a loss goes non-finite).
+     *  Undefined when the trainer didn't measure it. */
+    gradNorm?: number;
 }
 
 export type StorageTarget = 'indexedDB' | 'download' | 'fileSystem';
@@ -531,20 +553,68 @@ export class MambaSession {
             );
         }
 
+        const rollbackOnRegression = options.rollbackOnRegression ?? true;
+        const regressionTolerance  = options.regressionTolerance ?? 1.25;
+
+        // Snapshot the weights and measure the pre-adapt perplexity so a bad adapt
+        // can be reverted. This is what makes repeated write-through learning safe:
+        // an update that produces NaN/Inf or clearly worsens the model is undone
+        // instead of persisting and compounding across executions.
+        let snapshot: ArrayBuffer | null = null;
+        let perplexityBefore: number | undefined;
+        if (rollbackOnRegression) {
+            snapshot = await this._model.exportWeights();
+            perplexityBefore = await this._trainer.evaluate(text).catch(() => undefined);
+        }
+
         const startTime = Date.now();
+        // Capture the per-epoch grad norm (instability signal) without disturbing the
+        // caller's own progress callback.
+        const gradNorms: number[] = [];
         const losses    = await this._trainer.train(text, {
             epochs,
             learningRate,
             seqLen,
             wsla,
-            onEpochEnd: onProgress ?? null,
+            trackGradNorm: true,
+            onEpochEnd: (epoch, loss, gradNorm) => {
+                if (typeof gradNorm === 'number' && Number.isFinite(gradNorm)) gradNorms.push(gradNorm);
+                onProgress?.(epoch, loss);
+            },
         });
+        const gradNorm = gradNorms.length
+            ? gradNorms.reduce((a, b) => a + b, 0) / gradNorms.length
+            : undefined;
 
-        return {
+        const base: AdaptResult = {
             losses,
             epochCount : losses.length,
             durationMs : Date.now() - startTime,
+            gradNorm,
         };
+
+        if (!rollbackOnRegression || !snapshot) return base;
+
+        // Validate the adapt. Roll back on a non-finite loss (the update poisoned
+        // the weights) or a perplexity regression beyond tolerance.
+        const nonFiniteLoss = losses.some((l) => !Number.isFinite(l));
+        const perplexityAfter = await this._trainer.evaluate(text).catch(() => Number.POSITIVE_INFINITY);
+        const regressed =
+            Number.isFinite(perplexityBefore ?? NaN) && Number.isFinite(perplexityAfter) &&
+            perplexityAfter > (perplexityBefore as number) * regressionTolerance;
+
+        if (nonFiniteLoss || !Number.isFinite(perplexityAfter) || regressed) {
+            await this._model.loadWeights(snapshot);
+            return {
+                ...base,
+                rolledBack    : true,
+                rollbackReason: nonFiniteLoss || !Number.isFinite(perplexityAfter) ? 'non-finite loss' : 'perplexity regression',
+                perplexityBefore,
+                perplexityAfter,
+            };
+        }
+
+        return { ...base, rolledBack: false, perplexityBefore, perplexityAfter };
     }
 
     // ── Evaluation ─────────────────────────────────────────────────────────────

package/src/workflow/code-eval.ts

@@ -0,0 +1,143 @@
+/**
+ * workflow/code-eval.ts — dependency-free code-validity + execution-reward checks.
+ *
+ * These power the code-specific BUILD diagnostics that grade what Evermind's
+ * generator produces when we teach it to program:
+ *   • {@link analyzeCode}  — structural validity (balanced delimiters/strings) +
+ *                            an optional JS parse. The portable "does this look
+ *                            like valid code" gate.
+ *   • {@link runJsCases}   — execution-grounded reward: run generated JS against
+ *                            test cases and score the pass-rate. Code's signal is
+ *                            that it RUNS — this turns that into a number.
+ *
+ * Both are zero-dependency (no AST library) so they run in the same WebGPU/TS
+ * runtime as the rest of the engine. Execution uses the `Function` constructor —
+ * a heuristic reward sandbox, NOT a security boundary; only feed it code from a
+ * trusted teacher / the model under training.
+ */
+
+const OPEN: Record<string, string> = { ")": "(", "]": "[", "}": "{" };
+
+export interface CodeAnalysis {
+  /** 0..1 structural-validity score (1 = delimiters and strings all balanced). */
+  score: number;
+  /** True when every bracket/brace/paren and string literal closes cleanly. */
+  balanced: boolean;
+  /** For language="js": whether the source parses (Function constructor). undefined otherwise. */
+  jsParse?: boolean;
+}
+
+/**
+ * Score how structurally valid `code` is: walk the source tracking string state
+ * (so brackets inside strings are ignored) and a delimiter stack. A clean parse
+ * scores 1; each unmatched/mismatched delimiter or unterminated string lowers it.
+ */
+export function analyzeCode(code: string, language = "js"): CodeAnalysis {
+  const stack: string[] = [];
+  let mismatches = 0;
+  let delims = 0;
+  let inString: string | null = null; // the opening quote char, or null
+  let escaped = false;
+
+  for (let i = 0; i < code.length; i++) {
+    const ch = code[i]!;
+    if (inString) {
+      if (escaped) { escaped = false; continue; }
+      if (ch === "\\") { escaped = true; continue; }
+      if (ch === inString) inString = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") { inString = ch; continue; }
+    if (ch === "(" || ch === "[" || ch === "{") { stack.push(ch); delims++; continue; }
+    if (ch === ")" || ch === "]" || ch === "}") {
+      delims++;
+      if (stack.pop() !== OPEN[ch]) mismatches++;
+    }
+  }
+  // Anything left open is an unmatched delimiter; an open string is one more fault.
+  mismatches += stack.length;
+  const faults = mismatches + (inString ? 1 : 0);
+  const denom = Math.max(1, delims + (inString ? 1 : 0));
+  const balanced = faults === 0;
+  const score = balanced ? 1 : Math.max(0, 1 - faults / denom);
+
+  const analysis: CodeAnalysis = { score, balanced };
+  if (language === "js" || language === "ts" || language === "javascript" || language === "typescript") {
+    analysis.jsParse = jsParses(code);
+  }
+  return analysis;
+}
+
+/** True when `code` parses as JS (Function constructor parses but does not run). */
+function jsParses(code: string): boolean {
+  try {
+    // eslint-disable-next-line no-new-func
+    new Function(code);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface CodeCase {
+  /** An expression to evaluate after the code is loaded, e.g. "add(2, 3)". */
+  call: string;
+  /** The expected result (deep-equal compared). */
+  expect: unknown;
+}
+
+export interface CodeEvalResult {
+  passed: number;
+  total: number;
+  /** passed / total (0 when there are no cases). */
+  passRate: number;
+  /** A whole-program error (e.g. syntax error) that failed every case, if any. */
+  error?: string;
+}
+
+/**
+ * Load `code` (which defines functions) and evaluate each case's `call`
+ * expression, comparing the result to `expect`. A syntax error in `code` fails
+ * every case. Per-case runtime errors fail only that case.
+ *
+ * NOTE: heuristic reward sandbox, not a security boundary — see file header.
+ */
+export function runJsCases(code: string, cases: CodeCase[]): CodeEvalResult {
+  const total = cases.length;
+  if (total === 0) return { passed: 0, total: 0, passRate: 0 };
+
+  let passed = 0;
+  for (const c of cases) {
+    try {
+      // Code defines functions (hoisted); the trailing return evaluates the call.
+      // eslint-disable-next-line no-new-func
+      const fn = new Function(`${code}\n;return (${c.call});`);
+      const actual = fn();
+      if (deepEqual(actual, c.expect)) passed++;
+    } catch (err) {
+      // A syntax error throws at construction for ALL cases — report it once.
+      if (err instanceof SyntaxError) {
+        return { passed: 0, total, passRate: 0, error: err.message };
+      }
+      // Runtime error → this case simply fails.
+    }
+  }
+  return { passed, total, passRate: passed / total };
+}
+
+/** Structural deep equality good enough for JSON-shaped test expectations. */
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null) return false;
+  if (typeof a !== "object") return Object.is(a, b);
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((v, i) => deepEqual(v, b[i]));
+  }
+  const ao = a as Record<string, unknown>;
+  const bo = b as Record<string, unknown>;
+  const ak = Object.keys(ao);
+  const bk = Object.keys(bo);
+  if (ak.length !== bk.length) return false;
+  return ak.every((k) => deepEqual(ao[k], bo[k]));
+}

package/src/workflow/index.ts

@@ -6,14 +6,22 @@
 
 export type { WorkflowConfig, WorkflowStepConfig, StepTypeInfo, StepFactory } from "./types.js";
 export { StepTypeRegistry, createDefaultRegistry, defaultStepRegistry } from "./registry.js";
-export { BUILTIN_STEPS } from "./steps.js";
+export { BUILTIN_STEPS, selectBestCandidate, stripCodeFences } from "./steps.js";
 export {
   AGENTIC_SEVEN_LAYER,
   TRAIN_LLM,
+  TEACH_CODE,
   WORKFLOW_TEMPLATES,
   getTemplate,
   cloneTemplate,
 } from "./templates.js";
+export {
+  analyzeCode,
+  runJsCases,
+  type CodeAnalysis,
+  type CodeCase,
+  type CodeEvalResult,
+} from "./code-eval.js";
 export {
   compileWorkflow,
   validateWorkflow,