@seanhogg/builderforce-memory 2026.6.27 → 2026.6.30

package/dist/retrieval/bm25.js

@@ -0,0 +1,66 @@
+/**
+ * BM25 (Okapi) lexical ranking.
+ *
+ * The keyword half of hybrid retrieval. Dense vector search matches meaning but
+ * misses exact tokens (identifiers, error codes, rare names); BM25 catches those.
+ * Fusing the two (see {@link ./fusion}) is what lifts the memory layer from
+ * "cosine only" to a hybrid retriever on par with Weaviate-style search.
+ *
+ * Pure and zero-dependency — reuses the shared `tokenize` from ../similarity.
+ */
+import { tokenize } from '../similarity/index.js';
+/**
+ * Scores every document against `query` with Okapi BM25, returning hits sorted by
+ * descending score (documents with no query-term overlap score 0 and are dropped).
+ * Builds the index inline — for a recall over a bounded candidate set (the memory
+ * store / a vector pre-filter) this is O(N·terms) and needs no persistence.
+ */
+export function bm25Search(query, docs, opts = {}) {
+    const k1 = opts.k1 ?? 1.5;
+    const b = opts.b ?? 0.75;
+    const N = docs.length;
+    if (N === 0)
+        return [];
+    const queryTerms = new Set(tokenize(query));
+    if (queryTerms.size === 0)
+        return [];
+    // Per-doc term frequencies + document lengths.
+    const docTerms = [];
+    const df = new Map();
+    let totalLen = 0;
+    for (const doc of docs) {
+        const tokens = tokenize(doc.text);
+        const tf = new Map();
+        for (const t of tokens)
+            tf.set(t, (tf.get(t) ?? 0) + 1);
+        for (const t of tf.keys())
+            if (queryTerms.has(t))
+                df.set(t, (df.get(t) ?? 0) + 1);
+        docTerms.push({ id: doc.id, tf, len: tokens.length });
+        totalLen += tokens.length;
+    }
+    const avgdl = totalLen / N || 1;
+    // idf with the +1 smoothing variant (always non-negative).
+    const idf = new Map();
+    for (const term of queryTerms) {
+        const n = df.get(term) ?? 0;
+        idf.set(term, Math.log(1 + (N - n + 0.5) / (n + 0.5)));
+    }
+    const hits = [];
+    for (const d of docTerms) {
+        let score = 0;
+        for (const term of queryTerms) {
+            const f = d.tf.get(term);
+            if (!f)
+                continue;
+            const numer = f * (k1 + 1);
+            const denom = f + k1 * (1 - b + b * (d.len / avgdl));
+            score += idf.get(term) * (numer / denom);
+        }
+        if (score > 0)
+            hits.push({ id: d.id, score });
+    }
+    hits.sort((a, b) => b.score - a.score);
+    return hits;
+}
+//# sourceMappingURL=bm25.js.map

package/dist/retrieval/bm25.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bm25.js","sourceRoot":"","sources":["../../src/retrieval/bm25.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/chunk.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Document chunking — recursive character text splitter with overlap.
+ *
+ * The classic RAG ingestion step the memory layer was missing: large documents
+ * are split into smaller, semantically-coherent chunks before embedding so that
+ * retrieval returns precise passages rather than whole files. Mirrors the
+ * behaviour of LangChain's RecursiveCharacterTextSplitter (split on the largest
+ * natural boundary that fits, fall back to finer ones) but is zero-dependency.
+ */
+export interface ChunkOptions {
+    /** Target maximum chunk size in characters. Default 1000. */
+    chunkSize?: number;
+    /** Characters of overlap carried from the end of one chunk into the next,
+     *  preserving context across boundaries. Default 200. Clamped below chunkSize. */
+    chunkOverlap?: number;
+    /** Separators tried in order, largest natural boundary first. */
+    separators?: string[];
+}
+export interface Chunk {
+    /** The chunk text. */
+    text: string;
+    /** 0-based ordinal of this chunk within its source document. */
+    index: number;
+    /** Character offset of this chunk's start within the original document. */
+    start: number;
+}
+/**
+ * Splits `text` into overlapping chunks no larger than `chunkSize` characters,
+ * preferring the largest natural separator that keeps a piece under the limit.
+ * Returns `[]` for empty/whitespace input. Deterministic and pure.
+ */
+export declare function chunkText(text: string, opts?: ChunkOptions): Chunk[];
+//# sourceMappingURL=chunk.d.ts.map

package/dist/retrieval/chunk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../src/retrieval/chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,YAAY;IACzB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;sFACkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,KAAK;IAClB,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;CACjB;AAID;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,KAAK,EAAE,CA0CxE"}

package/dist/retrieval/chunk.js

@@ -0,0 +1,83 @@
+/**
+ * Document chunking — recursive character text splitter with overlap.
+ *
+ * The classic RAG ingestion step the memory layer was missing: large documents
+ * are split into smaller, semantically-coherent chunks before embedding so that
+ * retrieval returns precise passages rather than whole files. Mirrors the
+ * behaviour of LangChain's RecursiveCharacterTextSplitter (split on the largest
+ * natural boundary that fits, fall back to finer ones) but is zero-dependency.
+ */
+const DEFAULT_SEPARATORS = ['\n\n', '\n', '. ', ' ', ''];
+/**
+ * Splits `text` into overlapping chunks no larger than `chunkSize` characters,
+ * preferring the largest natural separator that keeps a piece under the limit.
+ * Returns `[]` for empty/whitespace input. Deterministic and pure.
+ */
+export function chunkText(text, opts = {}) {
+    const chunkSize = Math.max(1, opts.chunkSize ?? 1000);
+    const overlap = Math.min(Math.max(0, opts.chunkOverlap ?? 200), chunkSize - 1);
+    const separators = opts.separators ?? DEFAULT_SEPARATORS;
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return [];
+    if (trimmed.length <= chunkSize)
+        return [{ text: trimmed, index: 0, start: 0 }];
+    const pieces = splitRecursive(trimmed, chunkSize, separators);
+    // Merge adjacent pieces up to chunkSize, then stitch overlap between chunks.
+    const chunks = [];
+    let buf = '';
+    const flush = () => {
+        const t = buf.trim();
+        if (t.length > 0) {
+            const start = chunks.length === 0 ? 0 : Math.max(0, trimmed.indexOf(t));
+            chunks.push({ text: t, index: chunks.length, start });
+        }
+        buf = '';
+    };
+    for (const piece of pieces) {
+        if (buf.length + piece.length <= chunkSize) {
+            buf += piece;
+        }
+        else {
+            flush();
+            // Carry overlap from the previous chunk's tail.
+            const prev = chunks[chunks.length - 1]?.text ?? '';
+            buf = (overlap > 0 ? prev.slice(-overlap) : '') + piece;
+            // A single piece longer than chunkSize is hard-split.
+            while (buf.length > chunkSize) {
+                const head = buf.slice(0, chunkSize);
+                chunks.push({ text: head.trim(), index: chunks.length, start: 0 });
+                buf = (overlap > 0 ? head.slice(-overlap) : '') + buf.slice(chunkSize);
+            }
+        }
+    }
+    flush();
+    return chunks.map((c, i) => ({ ...c, index: i }));
+}
+/** Recursively splits text on the first separator that yields sub-chunkSize pieces. */
+function splitRecursive(text, chunkSize, separators) {
+    /* istanbul ignore next -- defensive base case; callers only recurse on parts > chunkSize */
+    if (text.length <= chunkSize)
+        return [text];
+    const [sep, ...rest] = separators;
+    if (sep === undefined)
+        return [text];
+    if (sep === '') {
+        // Last resort: hard character split.
+        const out = [];
+        for (let i = 0; i < text.length; i += chunkSize)
+            out.push(text.slice(i, i + chunkSize));
+        return out;
+    }
+    const parts = text.split(sep);
+    const out = [];
+    for (let i = 0; i < parts.length; i++) {
+        const part = i < parts.length - 1 ? parts[i] + sep : parts[i];
+        if (part.length > chunkSize)
+            out.push(...splitRecursive(part, chunkSize, rest));
+        else
+            out.push(part);
+    }
+    return out;
+}
+//# sourceMappingURL=chunk.js.map

package/dist/retrieval/chunk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../src/retrieval/chunk.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/fusion.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Rank fusion + diversity reranking.
+ *
+ *   • Reciprocal Rank Fusion (RRF) merges the dense (vector) and sparse (BM25)
+ *     rankings into one list without needing the two score scales to be
+ *     commensurable — it fuses on RANK, not raw score. This is the standard,
+ *     parameter-light way to combine hybrid retrieval signals.
+ *   • Maximal Marginal Relevance (MMR) reranks the fused list to trade off
+ *     relevance against novelty, so the top-k isn't five near-duplicate chunks.
+ *
+ * Pure and zero-dependency.
+ */
+export interface RankedList {
+    /** Ordered ids, most relevant first. */
+    ids: string[];
+    /** Optional weight for this list in the fusion (default 1). */
+    weight?: number;
+}
+export interface FusedHit {
+    id: string;
+    score: number;
+}
+/**
+ * Reciprocal Rank Fusion over any number of ranked lists.
+ * score(d) = Σ_lists weight / (k + rank(d)).  `k` (default 60) damps the
+ * contribution of low-ranked items; the canonical TREC value.
+ */
+export declare function reciprocalRankFusion(lists: RankedList[], k?: number): FusedHit[];
+export interface MmrCandidate {
+    id: string;
+    vector: Float32Array;
+}
+/**
+ * Maximal Marginal Relevance rerank. Greedily selects up to `topK` candidates,
+ * each step maximising `λ·sim(query, d) − (1−λ)·max sim(d, already-selected)`.
+ * λ=1 is pure relevance; lower λ injects diversity. Candidates without vectors
+ * should be filtered out by the caller (they cannot be MMR-scored).
+ */
+export declare function maximalMarginalRelevance(queryVec: Float32Array, candidates: MmrCandidate[], topK: number, lambda?: number): string[];
+//# sourceMappingURL=fusion.d.ts.map

package/dist/retrieval/fusion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fusion.d.ts","sourceRoot":"","sources":["../../src/retrieval/fusion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,WAAW,UAAU;IACvB,wCAAwC;IACxC,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC,SAAK,GAAG,QAAQ,EAAE,CAW5E;AAED,MAAM,WAAW,YAAY;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,YAAY,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACpC,QAAQ,EAAE,YAAY,EACtB,UAAU,EAAE,YAAY,EAAE,EAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,SAAM,GACb,MAAM,EAAE,CAsBV"}

package/dist/retrieval/fusion.js

@@ -0,0 +1,64 @@
+/**
+ * Rank fusion + diversity reranking.
+ *
+ *   • Reciprocal Rank Fusion (RRF) merges the dense (vector) and sparse (BM25)
+ *     rankings into one list without needing the two score scales to be
+ *     commensurable — it fuses on RANK, not raw score. This is the standard,
+ *     parameter-light way to combine hybrid retrieval signals.
+ *   • Maximal Marginal Relevance (MMR) reranks the fused list to trade off
+ *     relevance against novelty, so the top-k isn't five near-duplicate chunks.
+ *
+ * Pure and zero-dependency.
+ */
+import { cosineSimilarity } from '../similarity/index.js';
+/**
+ * Reciprocal Rank Fusion over any number of ranked lists.
+ * score(d) = Σ_lists weight / (k + rank(d)).  `k` (default 60) damps the
+ * contribution of low-ranked items; the canonical TREC value.
+ */
+export function reciprocalRankFusion(lists, k = 60) {
+    const acc = new Map();
+    for (const list of lists) {
+        const weight = list.weight ?? 1;
+        list.ids.forEach((id, rank) => {
+            acc.set(id, (acc.get(id) ?? 0) + weight / (k + rank + 1));
+        });
+    }
+    return [...acc.entries()]
+        .map(([id, score]) => ({ id, score }))
+        .sort((a, b) => b.score - a.score);
+}
+/**
+ * Maximal Marginal Relevance rerank. Greedily selects up to `topK` candidates,
+ * each step maximising `λ·sim(query, d) − (1−λ)·max sim(d, already-selected)`.
+ * λ=1 is pure relevance; lower λ injects diversity. Candidates without vectors
+ * should be filtered out by the caller (they cannot be MMR-scored).
+ */
+export function maximalMarginalRelevance(queryVec, candidates, topK, lambda = 0.7) {
+    const remaining = [...candidates];
+    const selected = [];
+    const relevance = new Map();
+    for (const c of remaining)
+        relevance.set(c.id, cosineSimilarity(queryVec, c.vector));
+    while (selected.length < topK && remaining.length > 0) {
+        let bestIdx = 0;
+        let bestScore = -Infinity;
+        for (let i = 0; i < remaining.length; i++) {
+            const c = remaining[i];
+            let maxSimToSelected = 0;
+            for (const s of selected) {
+                const sim = cosineSimilarity(c.vector, s.vector);
+                if (sim > maxSimToSelected)
+                    maxSimToSelected = sim;
+            }
+            const mmr = lambda * relevance.get(c.id) - (1 - lambda) * maxSimToSelected;
+            if (mmr > bestScore) {
+                bestScore = mmr;
+                bestIdx = i;
+            }
+        }
+        selected.push(remaining.splice(bestIdx, 1)[0]);
+    }
+    return selected.map(s => s.id);
+}
+//# sourceMappingURL=fusion.js.map

package/dist/retrieval/fusion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fusion.js","sourceRoot":"","sources":["../../src/retrieval/fusion.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Retrieval layer — chunking, BM25, rank fusion, and the HybridRetriever.
+ *
+ * The classic RAG pieces the memory stack previously lacked (chunking, hybrid
+ * dense+sparse search, reranking), implemented zero-dependency so they run in the
+ * browser, Node, and the SSM runtime alike.
+ */
+export { chunkText } from './chunk.js';
+export type { Chunk, ChunkOptions } from './chunk.js';
+export { bm25Search } from './bm25.js';
+export type { Bm25Doc, Bm25Hit, Bm25Options } from './bm25.js';
+export { reciprocalRankFusion, maximalMarginalRelevance } from './fusion.js';
+export type { RankedList, FusedHit, MmrCandidate } from './fusion.js';
+export { hybridRetrieve } from './HybridRetriever.js';
+export type { RetrievalCandidate, HybridQuery, HybridRetrieveOptions, HybridHit, } from './HybridRetriever.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/retrieval/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE/D,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACR,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,SAAS,GACZ,MAAM,sBAAsB,CAAC"}

package/dist/retrieval/index.js

@@ -0,0 +1,12 @@
+/**
+ * Retrieval layer — chunking, BM25, rank fusion, and the HybridRetriever.
+ *
+ * The classic RAG pieces the memory stack previously lacked (chunking, hybrid
+ * dense+sparse search, reranking), implemented zero-dependency so they run in the
+ * browser, Node, and the SSM runtime alike.
+ */
+export { chunkText } from './chunk.js';
+export { bm25Search } from './bm25.js';
+export { reciprocalRankFusion, maximalMarginalRelevance } from './fusion.js';
+export { hybridRetrieve } from './HybridRetriever.js';
+//# sourceMappingURL=index.js.map

package/dist/retrieval/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvC,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAG7E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/workflow/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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";
+//# sourceMappingURL=index.d.ts.map

package/dist/workflow/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/workflow/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAChG,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC7F,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,kBAAkB,EAClB,WAAW,EACX,aAAa,GACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,uBAAuB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACxB,MAAM,UAAU,CAAC"}

package/dist/workflow/index.js

@@ -0,0 +1,10 @@
+/**
+ * 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 { 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, } from "./run.js";
+//# sourceMappingURL=index.js.map

package/dist/workflow/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/workflow/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC7F,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,kBAAkB,EAClB,WAAW,EACX,aAAa,GACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,uBAAuB,GAGxB,MAAM,UAAU,CAAC"}

package/dist/workflow/registry.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 type { StepFactory, StepTypeInfo, WorkflowStepConfig } from "./types.js";
+import type { StackStep } from "../diagnostics/stack-diagnostic.js";
+export declare class StepTypeRegistry {
+    private readonly map;
+    register(info: StepTypeInfo, factory: StepFactory): this;
+    has(type: string): boolean;
+    /** Compile one step config to a runnable step (failing step for unknown types). */
+    build(cfg: WorkflowStepConfig): StackStep;
+    /** All registered step types — a workflow-builder palette reads this. */
+    types(): StepTypeInfo[];
+}
+export declare function createDefaultRegistry(): StepTypeRegistry;
+/** Shared registry seeded with the built-in step types. */
+export declare const defaultStepRegistry: StepTypeRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/workflow/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/workflow/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAEpE,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAmE;IAEvF,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAKxD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,mFAAmF;IACnF,KAAK,CAAC,GAAG,EAAE,kBAAkB,GAAG,SAAS;IAezC,yEAAyE;IACzE,KAAK,IAAI,YAAY,EAAE;CAGxB;AAED,wBAAgB,qBAAqB,IAAI,gBAAgB,CAIxD;AAED,2DAA2D;AAC3D,eAAO,MAAM,mBAAmB,kBAA0B,CAAC"}

package/dist/workflow/registry.js

@@ -0,0 +1,47 @@
+/**
+ * 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";
+export class StepTypeRegistry {
+    map = new Map();
+    register(info, factory) {
+        this.map.set(info.type, { info, factory });
+        return this;
+    }
+    has(type) {
+        return this.map.has(type);
+    }
+    /** Compile one step config to a runnable step (failing step for unknown types). */
+    build(cfg) {
+        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() {
+        return [...this.map.values()].map((e) => e.info);
+    }
+}
+export function createDefaultRegistry() {
+    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();
+//# sourceMappingURL=registry.js.map

package/dist/workflow/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/workflow/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI3C,MAAM,OAAO,gBAAgB;IACV,GAAG,GAAG,IAAI,GAAG,EAAwD,CAAC;IAEvF,QAAQ,CAAC,IAAkB,EAAE,OAAoB;QAC/C,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QAC3C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,mFAAmF;IACnF,KAAK,CAAC,GAAuB;QAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO;gBACL,EAAE,EAAE,GAAG,CAAC,EAAE;gBACV,KAAK,EAAE,GAAG;gBACV,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,IAAI;gBAC5B,GAAG,EAAE,KAAK,IAAI,EAAE;oBACd,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC;gBACrD,CAAC;aACF,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IAED,yEAAyE;IACzE,KAAK;QACH,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACnD,CAAC;CACF;AAED,MAAM,UAAU,qBAAqB;IACnC,MAAM,CAAC,GAAG,IAAI,gBAAgB,EAAE,CAAC;IACjC,KAAK,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC;QAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACxF,OAAO,CAAC,CAAC;AACX,CAAC;AAED,2DAA2D;AAC3D,MAAM,CAAC,MAAM,mBAAmB,GAAG,qBAAqB,EAAE,CAAC"}

package/dist/workflow/run.d.ts

@@ -0,0 +1,26 @@
+/**
+ * workflow/run.ts — compile, validate, and run a workflow config.
+ */
+import { type RunStackOptions, type StackDiagnosticResult, type StackStep } from "../diagnostics/stack-diagnostic.js";
+import { StepTypeRegistry } from "./registry.js";
+import type { WorkflowConfig } from "./types.js";
+/** Compile a workflow config to runnable steps (unknown types → failing steps). */
+export declare function compileWorkflow(config: WorkflowConfig, registry?: StepTypeRegistry): StackStep[];
+export interface WorkflowValidationError {
+    stepId: string;
+    type: string;
+    message: string;
+}
+/** Static checks before running: non-empty, unique ids, known types. */
+export declare function validateWorkflow(config: WorkflowConfig, registry?: StepTypeRegistry): WorkflowValidationError[];
+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 declare function runWorkflow(config: WorkflowConfig, opts?: RunWorkflowOptions): Promise<StackDiagnosticResult>;
+/** Back-compat: the 7-layer template compiled to steps (consumed by the e2e test). */
+export declare function buildEvermindStackSteps(): StackStep[];
+//# sourceMappingURL=run.d.ts.map

package/dist/workflow/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/workflow/run.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EACf,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAuB,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,GAAE,gBAAsC,GAAG,SAAS,EAAE,CAErH;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,GAAE,gBAAsC,GAAG,uBAAuB,EAAE,CAapI;AAED,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAGjH;AAED,sFAAsF;AACtF,wBAAgB,uBAAuB,IAAI,SAAS,EAAE,CAErD"}

package/dist/workflow/run.js

@@ -0,0 +1,40 @@
+/**
+ * workflow/run.ts — compile, validate, and run a workflow config.
+ */
+import { runStackDiagnostic, } from "../diagnostics/stack-diagnostic.js";
+import { defaultStepRegistry } from "./registry.js";
+import { AGENTIC_SEVEN_LAYER } from "./templates.js";
+/** Compile a workflow config to runnable steps (unknown types → failing steps). */
+export function compileWorkflow(config, registry = defaultStepRegistry) {
+    return config.steps.map((s) => registry.build(s));
+}
+/** Static checks before running: non-empty, unique ids, known types. */
+export function validateWorkflow(config, registry = defaultStepRegistry) {
+    const errors = [];
+    if (!config.steps || config.steps.length === 0) {
+        errors.push({ stepId: "", type: "", message: "workflow has no steps" });
+        return errors;
+    }
+    const seen = new Set();
+    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;
+}
+/**
+ * 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, opts = {}) {
+    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() {
+    return compileWorkflow(AGENTIC_SEVEN_LAYER);
+}
+//# sourceMappingURL=run.js.map

package/dist/workflow/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/workflow/run.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,kBAAkB,GAInB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAoB,MAAM,eAAe,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGrD,mFAAmF;AACnF,MAAM,UAAU,eAAe,CAAC,MAAsB,EAAE,WAA6B,mBAAmB;IACtG,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAQD,wEAAwE;AACxE,MAAM,UAAU,gBAAgB,CAAC,MAAsB,EAAE,WAA6B,mBAAmB;IACvG,MAAM,MAAM,GAA8B,EAAE,CAAC;IAC7C,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/C,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC,CAAC;QACxE,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,sBAAsB,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;QACxG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACf,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,sBAAsB,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC;IACnH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAMD;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,MAAsB,EAAE,OAA2B,EAAE;IAC/E,MAAM,EAAE,QAAQ,GAAG,mBAAmB,EAAE,GAAG,OAAO,EAAE,GAAG,IAAI,CAAC;IAC5D,OAAO,kBAAkB,CAAC,eAAe,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC;AACxE,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,uBAAuB;IACrC,OAAO,eAAe,CAAC,mBAAmB,CAAC,CAAC;AAC9C,CAAC"}

package/dist/workflow/steps.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 type { StepFactory, StepTypeInfo } from "./types.js";
+interface Registered {
+    info: StepTypeInfo;
+    factory: StepFactory;
+}
+export declare const BUILTIN_STEPS: Record<string, Registered>;
+export {};
+//# sourceMappingURL=steps.d.ts.map

package/dist/workflow/steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../../src/workflow/steps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAsB,MAAM,YAAY,CAAC;AAgChF,UAAU,UAAU;IAClB,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAyQpD,CAAC"}