@seanhogg/builderforce-memory 2026.6.28 → 2026.6.30

package/src/diagnostics/stack-diagnostic.ts

@@ -0,0 +1,103 @@
+/**
+ * stack-diagnostic.ts — the generic workflow runner + execution-output types.
+ *
+ * A workflow is an ordered list of {@link StackStep}s. `runStackDiagnostic`
+ * executes them, capturing per-step pass/fail + timing + error and streaming a
+ * callback — so the result is an "execution output" timeline a UI renders: run a
+ * workflow, watch each step, see exactly which one breaks.
+ *
+ * The concrete steps (the 7 agent-stack layers, the LLM-creation pipeline) and
+ * the configurable workflow/template layer live in `../workflow/` and compile
+ * down to `StackStep[]` runnable here. Steps share a {@link StackContext}: `bag`
+ * is scratch threaded across steps; `artifacts` is the workflow's OUTPUT (e.g. a
+ * trained `.evermind` blob).
+ */
+
+export type StepStatus = "pass" | "fail" | "skip";
+
+/** One step's result — the shape an execution-output timeline renders per row. */
+export interface StackStepResult {
+  id: string;
+  /** Grouping tag, e.g. "L1".."L7" for the agent-stack layers, or "BUILD". */
+  layer: string;
+  label: string;
+  status: StepStatus;
+  ms: number;
+  /** Short human detail on success (e.g. "retrieved 3 chunks"). */
+  detail?: string;
+  /** Failure message when status === "fail". */
+  error?: string;
+}
+
+/** Shared state threaded across steps. */
+export interface StackContext {
+  /** Scratch populated/consumed by steps (e.g. the model L1 builds, L7 deploys). */
+  bag: Record<string, unknown>;
+  /** Workflow OUTPUTS — what the run produces (e.g. `artifacts.evermind` = blob). */
+  artifacts: Record<string, unknown>;
+  /** Prior step results so far — this IS the observability trace. */
+  trace: StackStepResult[];
+  /** Optional IDBFactory (Node/fake-indexeddb); browser uses global indexedDB. */
+  idbFactory?: unknown;
+  now: () => number;
+}
+
+export interface StackStep {
+  id: string;
+  layer: string;
+  label: string;
+  /** Throw to fail the step; optionally return a human detail string. */
+  run: (ctx: StackContext) => Promise<string | void>;
+}
+
+export interface RunStackOptions {
+  /** Streamed as each step settles — for live execution-output rendering. */
+  onStep?: (r: StackStepResult) => void;
+  /** Injectable clock for deterministic timing in tests. Default Date.now. */
+  now?: () => number;
+  /** IDBFactory for Node; omit in the browser. */
+  idbFactory?: unknown;
+}
+
+export interface StackDiagnosticResult {
+  ok: boolean;
+  steps: StackStepResult[];
+  /** The first step that failed (the breaking point), if any. */
+  firstFailure?: StackStepResult;
+  /** Outputs produced by the run (e.g. `artifacts.evermind` for a build workflow). */
+  artifacts: Record<string, unknown>;
+  totalMs: number;
+}
+
+/**
+ * Run the steps in order, capturing each result. Never throws — a step that
+ * throws becomes a `fail` row, and the run continues so the caller sees the full
+ * timeline (and exactly where it broke). Pass `onStep` to stream rows live.
+ */
+export async function runStackDiagnostic(
+  steps: StackStep[],
+  opts: RunStackOptions = {},
+): Promise<StackDiagnosticResult> {
+  const now = opts.now ?? (() => Date.now());
+  const ctx: StackContext = { bag: {}, artifacts: {}, trace: [], idbFactory: opts.idbFactory, now };
+  const results: StackStepResult[] = [];
+  let firstFailure: StackStepResult | undefined;
+  const start = now();
+
+  for (const step of steps) {
+    const t0 = now();
+    let result: StackStepResult;
+    try {
+      const detail = await step.run(ctx);
+      result = { id: step.id, layer: step.layer, label: step.label, status: "pass", ms: now() - t0, ...(detail ? { detail } : {}) };
+    } catch (e) {
+      result = { id: step.id, layer: step.layer, label: step.label, status: "fail", ms: now() - t0, error: e instanceof Error ? e.message : String(e) };
+      firstFailure ??= result;
+    }
+    results.push(result);
+    ctx.trace.push(result);
+    opts.onStep?.(result);
+  }
+
+  return { ok: !firstFailure, steps: results, ...(firstFailure ? { firstFailure } : {}), artifacts: ctx.artifacts, totalMs: now() - start };
+}

package/src/index.ts

@@ -182,6 +182,42 @@ export type {
     Verdict,
 } from './cognition/index.js';
 
+// ── Diagnostics (execution-output runner) ──────────────────────────────────────
+export { runStackDiagnostic } from './diagnostics/index.js';
+export type {
+    StackStep,
+    StackStepResult,
+    StackContext,
+    StackDiagnosticResult,
+    RunStackOptions,
+    StepStatus,
+} from './diagnostics/index.js';
+
+// ── Workflows (configurable templates + step registry → run + .evermind output) ─
+export {
+    runWorkflow,
+    compileWorkflow,
+    validateWorkflow,
+    buildEvermindStackSteps,
+    StepTypeRegistry,
+    createDefaultRegistry,
+    defaultStepRegistry,
+    BUILTIN_STEPS,
+    AGENTIC_SEVEN_LAYER,
+    TRAIN_LLM,
+    WORKFLOW_TEMPLATES,
+    getTemplate,
+    cloneTemplate,
+} from './workflow/index.js';
+export type {
+    WorkflowConfig,
+    WorkflowStepConfig,
+    StepTypeInfo,
+    StepFactory,
+    WorkflowValidationError,
+    RunWorkflowOptions,
+} from './workflow/index.js';
+
 // ── Distillation ──────────────────────────────────────────────────────────────
 export { DistillationEngine } from './distillation/DistillationEngine.js';
 export type {

package/src/workflow/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Configurable agent/LLM workflows — templates, a step-type registry, and a
+ * runner that produces an execution-output timeline (+ a trained `.evermind`
+ * artifact for build workflows).
+ */
+
+export type { WorkflowConfig, WorkflowStepConfig, StepTypeInfo, StepFactory } from "./types.js";
+export { StepTypeRegistry, createDefaultRegistry, defaultStepRegistry } from "./registry.js";
+export { BUILTIN_STEPS } from "./steps.js";
+export {
+  AGENTIC_SEVEN_LAYER,
+  TRAIN_LLM,
+  WORKFLOW_TEMPLATES,
+  getTemplate,
+  cloneTemplate,
+} from "./templates.js";
+export {
+  compileWorkflow,
+  validateWorkflow,
+  runWorkflow,
+  buildEvermindStackSteps,
+  type WorkflowValidationError,
+  type RunWorkflowOptions,
+} from "./run.js";

package/src/workflow/registry.ts

@@ -0,0 +1,55 @@
+/**
+ * workflow/registry.ts — the step-type registry.
+ *
+ * Maps a step `type` → its factory + metadata. Built-ins are pre-registered;
+ * callers (e.g. the agent runtime) can `register` real implementations for the
+ * layers they own. Unknown types compile to a failing step so a bad workflow is
+ * localized in the timeline rather than crashing the run.
+ */
+
+import { BUILTIN_STEPS } from "./steps.js";
+import type { StepFactory, StepTypeInfo, WorkflowStepConfig } from "./types.js";
+import type { StackStep } from "../diagnostics/stack-diagnostic.js";
+
+export class StepTypeRegistry {
+  private readonly map = new Map<string, { info: StepTypeInfo; factory: StepFactory }>();
+
+  register(info: StepTypeInfo, factory: StepFactory): this {
+    this.map.set(info.type, { info, factory });
+    return this;
+  }
+
+  has(type: string): boolean {
+    return this.map.has(type);
+  }
+
+  /** Compile one step config to a runnable step (failing step for unknown types). */
+  build(cfg: WorkflowStepConfig): StackStep {
+    const entry = this.map.get(cfg.type);
+    if (!entry) {
+      return {
+        id: cfg.id,
+        layer: "?",
+        label: cfg.label ?? cfg.type,
+        run: async () => {
+          throw new Error(`unknown step type "${cfg.type}"`);
+        },
+      };
+    }
+    return entry.factory(cfg);
+  }
+
+  /** All registered step types — a workflow-builder palette reads this. */
+  types(): StepTypeInfo[] {
+    return [...this.map.values()].map((e) => e.info);
+  }
+}
+
+export function createDefaultRegistry(): StepTypeRegistry {
+  const r = new StepTypeRegistry();
+  for (const { info, factory } of Object.values(BUILTIN_STEPS)) r.register(info, factory);
+  return r;
+}
+
+/** Shared registry seeded with the built-in step types. */
+export const defaultStepRegistry = createDefaultRegistry();

package/src/workflow/run.ts

@@ -0,0 +1,58 @@
+/**
+ * workflow/run.ts — compile, validate, and run a workflow config.
+ */
+
+import {
+  runStackDiagnostic,
+  type RunStackOptions,
+  type StackDiagnosticResult,
+  type StackStep,
+} from "../diagnostics/stack-diagnostic.js";
+import { defaultStepRegistry, StepTypeRegistry } from "./registry.js";
+import { AGENTIC_SEVEN_LAYER } from "./templates.js";
+import type { WorkflowConfig } from "./types.js";
+
+/** Compile a workflow config to runnable steps (unknown types → failing steps). */
+export function compileWorkflow(config: WorkflowConfig, registry: StepTypeRegistry = defaultStepRegistry): StackStep[] {
+  return config.steps.map((s) => registry.build(s));
+}
+
+export interface WorkflowValidationError {
+  stepId: string;
+  type: string;
+  message: string;
+}
+
+/** Static checks before running: non-empty, unique ids, known types. */
+export function validateWorkflow(config: WorkflowConfig, registry: StepTypeRegistry = defaultStepRegistry): WorkflowValidationError[] {
+  const errors: WorkflowValidationError[] = [];
+  if (!config.steps || config.steps.length === 0) {
+    errors.push({ stepId: "", type: "", message: "workflow has no steps" });
+    return errors;
+  }
+  const seen = new Set<string>();
+  for (const s of config.steps) {
+    if (seen.has(s.id)) errors.push({ stepId: s.id, type: s.type, message: `duplicate step id "${s.id}"` });
+    seen.add(s.id);
+    if (!registry.has(s.type)) errors.push({ stepId: s.id, type: s.type, message: `unknown step type "${s.type}"` });
+  }
+  return errors;
+}
+
+export interface RunWorkflowOptions extends RunStackOptions {
+  registry?: StepTypeRegistry;
+}
+
+/**
+ * Run a workflow config and return its execution-output timeline + artifacts
+ * (e.g. `result.artifacts.evermind` is the trained model for a build workflow).
+ */
+export function runWorkflow(config: WorkflowConfig, opts: RunWorkflowOptions = {}): Promise<StackDiagnosticResult> {
+  const { registry = defaultStepRegistry, ...runOpts } = opts;
+  return runStackDiagnostic(compileWorkflow(config, registry), runOpts);
+}
+
+/** Back-compat: the 7-layer template compiled to steps (consumed by the e2e test). */
+export function buildEvermindStackSteps(): StackStep[] {
+  return compileWorkflow(AGENTIC_SEVEN_LAYER);
+}

package/src/workflow/steps.ts

@@ -0,0 +1,325 @@
+/**
+ * workflow/steps.ts — the built-in step types.
+ *
+ * Two families, both compiling to a runnable {@link StackStep}:
+ *   • Agent-stack layers (L1..L7) — the diagnostic checks (the 7-layer template).
+ *   • LLM-creation pipeline (BUILD) — train-tokenizer → train-model → evaluate →
+ *     package, which produces a trained `.evermind` artifact (a custom LLM) into
+ *     `ctx.artifacts.evermind`.
+ *
+ * A custom workflow mixes these freely; new step types register the same way.
+ */
+
+import {
+  EvermindLM,
+  EvermindLMTrainer,
+  BPETokenizer,
+  EvermindModelPackage,
+} from "@seanhogg/builderforce-memory-engine";
+import { EvermindCognition } from "../cognition/index.js";
+import { hybridRetrieve, chunkText } from "../retrieval/index.js";
+import { MemoryStore } from "../memory/MemoryStore.js";
+import type { StackStep } from "../diagnostics/stack-diagnostic.js";
+import type { StepFactory, StepTypeInfo, WorkflowStepConfig } from "./types.js";
+
+const KNOWLEDGE =
+  "BuilderForce orchestrates many agents through a planning loop. " +
+  "The memory layer stores facts as SSM embeddings. " +
+  "Deployment runs on Cloudflare Workers and Durable Objects. " +
+  "Tools are gated by a capability registry.";
+
+let dbSeq = 0;
+
+// ── param readers (configurable per step) ──────────────────────────────────────
+function pStr(cfg: WorkflowStepConfig, key: string, def: string): string {
+  const v = cfg.params?.[key];
+  return typeof v === "string" ? v : def;
+}
+function pNum(cfg: WorkflowStepConfig, key: string, def: number): number {
+  const v = cfg.params?.[key];
+  return typeof v === "number" && Number.isFinite(v) ? v : def;
+}
+
+function mkStep(cfg: WorkflowStepConfig, layer: string, defaultLabel: string, run: StackStep["run"]): StackStep {
+  return { id: cfg.id, layer, label: cfg.label ?? defaultLabel, run };
+}
+
+/** Encode a corpus into next-token training sequences (one per sentence). */
+function corpusToSequences(corpus: string, tok: BPETokenizer): number[][] {
+  return corpus
+    .split(/(?<=\.)\s+/)
+    .map((s) => tok.encode(s.trim()))
+    .filter((ids) => ids.length >= 2);
+}
+
+interface Registered {
+  info: StepTypeInfo;
+  factory: StepFactory;
+}
+
+export const BUILTIN_STEPS: Record<string, Registered> = {
+  // ── Agent-stack layers (the diagnostic / 7-layer template) ──────────────────
+  foundation: {
+    info: { type: "foundation", layer: "L1", label: "Foundation Model", description: "EvermindLM + tokenizer generate text" },
+    factory: (cfg) =>
+      mkStep(cfg, "L1", "Foundation Model — EvermindLM + tokenizer", async (ctx) => {
+        const tok = new BPETokenizer();
+        tok.train(KNOWLEDGE.repeat(4), { numMerges: 60 });
+        const model = new EvermindLM({ vocabSize: tok.vocabSize, dModel: 16, numLayers: 2, hiddenDim: 24, seed: 7 });
+        const out = model.generateText("Deployment", tok, { maxNewTokens: 4, temperature: 0 });
+        if (typeof out !== "string") throw new Error("model did not produce text");
+        if (tok.decode(tok.encode("Cloudflare Workers")) !== "Cloudflare Workers") throw new Error("tokenizer did not round-trip text");
+        ctx.bag.model = model;
+        ctx.bag.tokenizer = tok;
+        return `vocab ${tok.vocabSize}, generated ${out.length} chars`;
+      }),
+  },
+  memory: {
+    info: { type: "memory", layer: "L3", label: "Memory", description: "Write-through cognition (replace-on-write)" },
+    factory: (cfg) =>
+      mkStep(cfg, "L3", "Memory — write-through cognition", async (ctx) => {
+        const store = new MemoryStore({ dbName: `wf-${ctx.now()}-${dbSeq++}`, idbFactory: ctx.idbFactory as never });
+        const cognition = new EvermindCognition({ store });
+        await cognition.commit({ subjectKey: "fact:deploy", content: "deploy target = unknown" });
+        const r = await cognition.commit({ subjectKey: "fact:deploy", content: "deploy target = Cloudflare" });
+        if (r.verdict !== "supersede") throw new Error(`expected supersede, got ${r.verdict}`);
+        ctx.bag.cognition = cognition;
+        return `verdict ${r.verdict}`;
+      }),
+  },
+  rag: {
+    info: { type: "rag", layer: "L4", label: "RAG", description: "Chunk + hybrid (BM25 + dense) retrieve" },
+    factory: (cfg) =>
+      mkStep(cfg, "L4", "RAG — chunk + hybrid retrieve", async (ctx) => {
+        const candidates = chunkText(KNOWLEDGE, { chunkSize: 70, chunkOverlap: 0 }).map((c, i) => ({ id: `c${i}`, text: c.text }));
+        const hits = hybridRetrieve({ text: "where does deployment run" }, candidates, { topK: 2 });
+        if (hits.length === 0 || !hits[0]!.text.toLowerCase().includes("cloudflare")) throw new Error("retriever did not surface the deployment passage");
+        ctx.bag.candidates = candidates;
+        return `top hit: ${hits[0]!.text.slice(0, 40)}…`;
+      }),
+  },
+  tools: {
+    info: { type: "tools", layer: "L5", label: "Tools", description: "Capability-gated tool registry" },
+    factory: (cfg) =>
+      mkStep(cfg, "L5", "Tools — capability-gated registry", async (ctx) => {
+        const tools = new Map<string, (a: string) => string>([["shout", (a) => a.toUpperCase()]]);
+        if (tools.get("shout")?.("deploy") !== "DEPLOY") throw new Error("tool invocation failed");
+        if (tools.get("missing")) throw new Error("ungated tool resolved");
+        ctx.bag.tools = tools;
+        return "1 tool registered + invoked";
+      }),
+  },
+  orchestration: {
+    info: { type: "orchestration", layer: "L2", label: "Orchestration", description: "retrieve→recall→act→generate loop" },
+    factory: (cfg) =>
+      mkStep(cfg, "L2", "Orchestration — retrieve→recall→act→generate", async (ctx) => {
+        const model = ctx.bag.model as EvermindLM | undefined;
+        const tokenizer = ctx.bag.tokenizer as BPETokenizer | undefined;
+        const cognition = ctx.bag.cognition as EvermindCognition | undefined;
+        const candidates = ctx.bag.candidates as { id: string; text: string }[] | undefined;
+        const tools = ctx.bag.tools as Map<string, (a: string) => string> | undefined;
+        if (!model || !tokenizer || !cognition || !candidates || !tools) throw new Error("a prerequisite layer (L1/L3/L4/L5) did not complete");
+        const steps: string[] = [];
+        const hits = hybridRetrieve({ text: "deployment cloudflare" }, candidates, { topK: 1 });
+        steps.push("retrieve");
+        await cognition.recall("deployment", 3);
+        steps.push("recall");
+        tools.get("shout")!(hits[0]?.text ?? "deploy");
+        steps.push("tool");
+        model.generateText("Deployment", tokenizer, { maxNewTokens: 3, temperature: 0 });
+        steps.push("model");
+        if (steps.join(",") !== "retrieve,recall,tool,model") throw new Error("loop did not complete all stages");
+        return steps.join(" → ");
+      }),
+  },
+  observability: {
+    info: { type: "observability", layer: "L6", label: "Observability", description: "Trace captured every prior step" },
+    factory: (cfg) =>
+      mkStep(cfg, "L6", "Observability — trace captured prior steps", async (ctx) => {
+        if (ctx.trace.length === 0) throw new Error("no spans captured");
+        for (const s of ctx.trace) {
+          if (typeof s.layer !== "string" || typeof s.status !== "string" || s.ms < 0) throw new Error(`malformed span: ${s.id}`);
+        }
+        return `${ctx.trace.length} spans recorded`;
+      }),
+  },
+  deployment: {
+    info: { type: "deployment", layer: "L7", label: "Deployment", description: ".evermind artifact ships + runs identically" },
+    factory: (cfg) =>
+      mkStep(cfg, "L7", "Deployment — .evermind ships + runs identically", async (ctx) => {
+        const model = ctx.bag.model as EvermindLM | undefined;
+        const tokenizer = ctx.bag.tokenizer as BPETokenizer | undefined;
+        if (!model || !tokenizer) throw new Error("no model from L1 to deploy");
+        const before = model.generateText("Deployment", tokenizer, { maxNewTokens: 4, temperature: 0 });
+        const blob = EvermindModelPackage.fromLM(model, { name: "stack-demo", version: "1.0.0", card: { description: "diagnostic" } }).toBlob();
+        const pkg = EvermindModelPackage.fromBlob(blob);
+        if (!pkg.validate().ok) throw new Error("packaged artifact failed validation");
+        const after = pkg.loadLM().generateText("Deployment", tokenizer, { maxNewTokens: 4, temperature: 0 });
+        if (after !== before) throw new Error("deployed instance produced different output");
+        return `artifact ${blob.byteLength} bytes, output matches`;
+      }),
+  },
+
+  // ── LLM-creation pipeline (BUILD) — produces a custom .evermind model ────────
+  "train-tokenizer": {
+    info: { type: "train-tokenizer", layer: "BUILD", label: "Train tokenizer", description: "Learn a BPE vocab from your corpus (params: corpus, numMerges)" },
+    factory: (cfg) =>
+      mkStep(cfg, "BUILD", "Train tokenizer (BPE)", async (ctx) => {
+        const corpus = pStr(cfg, "corpus", KNOWLEDGE.repeat(4));
+        const numMerges = pNum(cfg, "numMerges", 100);
+        const tok = new BPETokenizer();
+        tok.train(corpus, { numMerges });
+        ctx.bag.tokenizer = tok;
+        ctx.bag.corpus = corpus;
+        return `vocab ${tok.vocabSize} (${numMerges} merges)`;
+      }),
+  },
+  "train-model": {
+    info: { type: "train-model", layer: "BUILD", label: "Train model", description: "Train an EvermindLM on the corpus (params: dModel, numLayers, hiddenDim, epochs, lr)" },
+    factory: (cfg) =>
+      mkStep(cfg, "BUILD", "Train model (EvermindLM)", async (ctx) => {
+        const tok = ctx.bag.tokenizer as BPETokenizer | undefined;
+        if (!tok) throw new Error("no tokenizer — add a 'train-tokenizer' step first");
+        const corpus = pStr(cfg, "corpus", (ctx.bag.corpus as string) ?? KNOWLEDGE.repeat(4));
+        const sequences = corpusToSequences(corpus, tok);
+        if (sequences.length === 0) throw new Error("corpus produced no trainable sequences");
+        const model = new EvermindLM({
+          vocabSize: tok.vocabSize,
+          dModel: pNum(cfg, "dModel", 16),
+          numLayers: pNum(cfg, "numLayers", 2),
+          hiddenDim: pNum(cfg, "hiddenDim", 24),
+          seed: pNum(cfg, "seed", 7),
+        });
+        const epochs = pNum(cfg, "epochs", 40);
+        const history = new EvermindLMTrainer(model, { lr: pNum(cfg, "lr", 0.03), epochs }).fit(sequences);
+        ctx.bag.model = model;
+        // Surface the loss curve so a `convergence` diagnostic / observability can
+        // assert training actually worked (it was previously discarded).
+        ctx.bag.trainingHistory = history;
+        const last = history.at(-1) ?? 0;
+        return `trained ${epochs} epochs over ${sequences.length} seqs, loss ${last.toFixed(3)}`;
+      }),
+  },
+  evaluate: {
+    info: { type: "evaluate", layer: "BUILD", label: "Evaluate", description: "Sanity-check the model generates text (params: prompt)" },
+    factory: (cfg) =>
+      mkStep(cfg, "BUILD", "Evaluate model", async (ctx) => {
+        const model = ctx.bag.model as EvermindLM | undefined;
+        const tok = ctx.bag.tokenizer as BPETokenizer | undefined;
+        if (!model || !tok) throw new Error("no trained model — add 'train-model' first");
+        const prompt = pStr(cfg, "prompt", "The");
+        const out = model.generateText(prompt, tok, { maxNewTokens: pNum(cfg, "maxNewTokens", 6), temperature: 0 });
+        if (typeof out !== "string") throw new Error("evaluation generation failed");
+        ctx.bag.sample = out;
+        return `sample: "${out.slice(0, 40)}"`;
+      }),
+  },
+  "dataset-quality": {
+    info: { type: "dataset-quality", layer: "BUILD", label: "Dataset quality", description: "Validate the corpus is trainable before spending epochs (params: minSequences, minWords, maxDuplicateRatio)" },
+    factory: (cfg) =>
+      mkStep(cfg, "BUILD", "Dataset quality gate", async (ctx) => {
+        const tok = ctx.bag.tokenizer as BPETokenizer | undefined;
+        if (!tok) throw new Error("no tokenizer — add a 'train-tokenizer' step first");
+        const corpus = pStr(cfg, "corpus", (ctx.bag.corpus as string) ?? "");
+        const words = corpus.trim().split(/\s+/).filter(Boolean).length;
+        const sequences = corpusToSequences(corpus, tok);
+        const seqLens = sequences.map((s) => s.length);
+        const avgSeqLen = seqLens.length ? seqLens.reduce((a, b) => a + b, 0) / seqLens.length : 0;
+        const uniqueSeqs = new Set(sequences.map((s) => s.join(","))).size;
+        const duplicateRatio = sequences.length ? 1 - uniqueSeqs / sequences.length : 1;
+
+        const minSequences = pNum(cfg, "minSequences", 3);
+        const minWords = pNum(cfg, "minWords", 20);
+        const maxDuplicateRatio = pNum(cfg, "maxDuplicateRatio", 0.7);
+
+        const metrics = { words, sequences: sequences.length, avgSeqLen: Number(avgSeqLen.toFixed(1)), duplicateRatio: Number(duplicateRatio.toFixed(2)) };
+        ctx.bag.datasetMetrics = metrics;
+
+        if (words < minWords) throw new Error(`corpus too small: ${words} words < ${minWords}`);
+        if (sequences.length < minSequences) throw new Error(`too few trainable sequences: ${sequences.length} < ${minSequences} (need more sentences)`);
+        if (duplicateRatio > maxDuplicateRatio) throw new Error(`corpus too repetitive: ${(duplicateRatio * 100) | 0}% duplicate sequences > ${(maxDuplicateRatio * 100) | 0}%`);
+        return `${words} words, ${sequences.length} seqs (avg ${metrics.avgSeqLen} tok), ${(duplicateRatio * 100) | 0}% dup`;
+      }),
+  },
+  convergence: {
+    info: { type: "convergence", layer: "BUILD", label: "Convergence", description: "Assert the model actually learned — training loss decreased (params: minDrop)" },
+    factory: (cfg) =>
+      mkStep(cfg, "BUILD", "Training convergence", async (ctx) => {
+        const history = ctx.bag.trainingHistory as number[] | undefined;
+        if (!history || history.length === 0) throw new Error("no training history — run 'train-model' first");
+        const first = history[0]!;
+        const last = history.at(-1)!;
+        if (!Number.isFinite(first) || !Number.isFinite(last)) throw new Error(`loss is not finite (first=${first}, last=${last}) — training diverged`);
+        const minDrop = pNum(cfg, "minDrop", 0); // require at least this absolute loss drop
+        if (last >= first - minDrop) throw new Error(`loss did not decrease: ${first.toFixed(3)} → ${last.toFixed(3)} (model did not learn — raise epochs/lr)`);
+        ctx.bag.converged = true;
+        return `loss ${first.toFixed(3)} → ${last.toFixed(3)} (−${(first - last).toFixed(3)})`;
+      }),
+  },
+  "generate-check": {
+    info: { type: "generate-check", layer: "BUILD", label: "Generation check", description: "Validate the model generates non-empty, reproducible text (params: prompt, seed, temperature)" },
+    factory: (cfg) =>
+      mkStep(cfg, "BUILD", "Generation quality + determinism", async (ctx) => {
+        const model = ctx.bag.model as EvermindLM | undefined;
+        const tok = ctx.bag.tokenizer as BPETokenizer | undefined;
+        if (!model || !tok) throw new Error("no trained model — add 'train-model' first");
+        const prompt = pStr(cfg, "prompt", "The");
+        const maxNewTokens = pNum(cfg, "maxNewTokens", 8);
+        const seed = pNum(cfg, "seed", 1234);
+        const temperature = pNum(cfg, "temperature", 0.8);
+        // Same seed + temperature MUST reproduce — serving relies on it.
+        const a = model.generateText(prompt, tok, { maxNewTokens, temperature, seed });
+        const b = model.generateText(prompt, tok, { maxNewTokens, temperature, seed });
+        if (a !== b) throw new Error("sampling is non-deterministic for a fixed seed — serving would be unreproducible");
+        const greedy = model.generateText(prompt, tok, { maxNewTokens, temperature: 0 });
+        if (typeof greedy !== "string" || greedy.trim().length === 0) throw new Error("model produced empty output");
+        ctx.bag.sample = greedy;
+        return `deterministic@seed ${seed}; sample "${greedy.slice(0, 40)}"`;
+      }),
+  },
+  roundtrip: {
+    info: { type: "roundtrip", layer: "BUILD", label: "Deploy round-trip", description: "Package the TRAINED model → load → generate; output must match (the real serve smoke test)" },
+    factory: (cfg) =>
+      mkStep(cfg, "BUILD", "Deploy round-trip (.evermind)", async (ctx) => {
+        const model = ctx.bag.model as EvermindLM | undefined;
+        const tok = ctx.bag.tokenizer as BPETokenizer | undefined;
+        if (!model || !tok) throw new Error("no trained model — add 'train-model' first");
+        const prompt = pStr(cfg, "prompt", "The");
+        const maxNewTokens = pNum(cfg, "maxNewTokens", 6);
+        const before = model.generateText(prompt, tok, { maxNewTokens, temperature: 0 });
+        const blob = EvermindModelPackage.fromLM(model, {
+          name: pStr(cfg, "name", "custom-evermind"),
+          version: pStr(cfg, "version", "1.0.0"),
+          card: { description: pStr(cfg, "description", "round-trip validated model") },
+        }).toBlob();
+        const pkg = EvermindModelPackage.fromBlob(blob);
+        const v = pkg.validate();
+        if (!v.ok) throw new Error(`packaged artifact failed validation: ${v.errors.join("; ")}`);
+        const after = pkg.loadLM().generateText(prompt, tok, { maxNewTokens, temperature: 0 });
+        if (after !== before) throw new Error("served model produced different output than the trained model");
+        ctx.artifacts.evermind = blob;
+        ctx.artifacts.tokenizer = { vocab: Object.fromEntries(tok.vocab), merges: [...tok.merges.keys()] };
+        return `artifact ${blob.byteLength} bytes; trained vs served output matches`;
+      }),
+  },
+  package: {
+    info: { type: "package", layer: "BUILD", label: "Package", description: "Bundle the trained model into a portable .evermind artifact (params: name, version)" },
+    factory: (cfg) =>
+      mkStep(cfg, "BUILD", "Package .evermind artifact", async (ctx) => {
+        const model = ctx.bag.model as EvermindLM | undefined;
+        if (!model) throw new Error("no trained model — add 'train-model' first");
+        const blob = EvermindModelPackage.fromLM(model, {
+          name: pStr(cfg, "name", "custom-evermind"),
+          version: pStr(cfg, "version", "1.0.0"),
+          card: { description: pStr(cfg, "description", "workflow-built model") },
+        }).toBlob();
+        ctx.artifacts.evermind = blob;
+        // Ship the tokenizer alongside so the deployed model has text I/O.
+        const tok = ctx.bag.tokenizer as BPETokenizer | undefined;
+        if (tok) {
+          ctx.artifacts.tokenizer = { vocab: Object.fromEntries(tok.vocab), merges: [...tok.merges.keys()] };
+        }
+        return `packaged ${blob.byteLength} bytes${tok ? " + tokenizer" : ""}`;
+      }),
+  },
+};