@iworkforces/tracelattice 2.0.3

package/dist/core/graph/GraphView.d.ts

@@ -0,0 +1,157 @@
+/**
+ * GraphView — read-only graph traversal queries over an {@link IEdgeStore}.
+ *
+ * Provides BFS / topological / ancestor / descendant queries over the
+ * thought DAG. All methods return arrays of thought ids (ulid strings),
+ * never `ThoughtData` objects — the view is intentionally decoupled from
+ * `HistoryManager` so it can be reused by strategies that work purely in
+ * terms of graph structure.
+ *
+ * Construction is cheap (stores a reference to the underlying store).
+ * Each query reads the latest store state — no caching, no snapshots.
+ *
+ * @module core/graph/GraphView
+ */
+import type { IEdgeStore } from '../../contracts/interfaces.js';
+import type { SessionId, ThoughtId } from '../../contracts/ids.js';
+/**
+ * Read-only traversal queries over an {@link IEdgeStore}.
+ *
+ * @example
+ * ```typescript
+ * const store = new EdgeStore();
+ * // ... populate store ...
+ * const view = new GraphView(store);
+ * const order = view.topological('s1');
+ * ```
+ */
+export declare class GraphView {
+    private readonly _store;
+    /**
+     * Create a new GraphView backed by the given edge store.
+     *
+     * @param store - The edge store to query (held by reference, read-only access)
+     *
+     * @example
+     * ```typescript
+     * const view = new GraphView(edgeStore);
+     * ```
+     */
+    constructor(store: IEdgeStore);
+    /**
+     * Return all thought ids in the session, ordered by BFS from roots.
+     *
+     * Roots are nodes with no incoming edges. Within a layer, neighbours
+     * are visited in `outgoing` order (which the underlying store keeps
+     * sorted by `createdAt` ascending).
+     *
+     * @param sessionId - Session to query
+     * @returns Thought ids in chronological BFS order
+     *
+     * @example
+     * ```typescript
+     * const ids = view.chronological('s1');
+     * ```
+     */
+    chronological(sessionId: SessionId): readonly ThoughtId[];
+    /**
+     * Return all thought ids reachable from `rootThoughtId` via `'branch'`
+     * edges, including the root itself.
+     *
+     * Non-branch edges are ignored. Cycles (if any) do not cause infinite
+     * loops because each node is visited at most once.
+     *
+     * @param sessionId - Session to query
+     * @param rootThoughtId - The starting thought id (typically the branch root)
+     * @returns Thought ids forming the branch (includes root)
+     *
+     * @example
+     * ```typescript
+     * const branchIds = view.branchThoughts('s1', 'thought-root');
+     * ```
+     */
+    branchThoughts(sessionId: SessionId, rootThoughtId: ThoughtId): readonly ThoughtId[];
+    /**
+     * Return a topological ordering of all thought ids in the session
+     * using Kahn's algorithm.
+     *
+     * @param sessionId - Session to query
+     * @returns Thought ids in topological order
+     * @throws {CycleDetectedError} If the graph contains a cycle
+     *
+     * @example
+     * ```typescript
+     * const order = view.topological('s1');
+     * ```
+     */
+    topological(sessionId: SessionId): readonly ThoughtId[];
+    /**
+     * Return all ancestors of `thoughtId` via incoming-edge BFS.
+     *
+     * The starting node is NOT included. Cycles do not cause infinite loops.
+     *
+     * @param sessionId - Session to query
+     * @param thoughtId - The thought to traverse from
+     * @param maxDepth - Optional maximum traversal depth (1 = direct parents only)
+     * @returns Ancestor thought ids in BFS order
+     *
+     * @example
+     * ```typescript
+     * const parents = view.ancestors('s1', 'thought-id', 1);
+     * ```
+     */
+    ancestors(sessionId: SessionId, thoughtId: ThoughtId, maxDepth?: number): readonly ThoughtId[];
+    /**
+     * Return all descendants of `thoughtId` via outgoing-edge BFS.
+     *
+     * The starting node is NOT included. Cycles do not cause infinite loops.
+     *
+     * @param sessionId - Session to query
+     * @param thoughtId - The thought to traverse from
+     * @param maxDepth - Optional maximum traversal depth (1 = direct children only)
+     * @returns Descendant thought ids in BFS order
+     *
+     * @example
+     * ```typescript
+     * const children = view.descendants('s1', 'thought-id');
+     * ```
+     */
+    descendants(sessionId: SessionId, thoughtId: ThoughtId, maxDepth?: number): readonly ThoughtId[];
+    /**
+     * Return all thought ids in the session that have no outgoing edges.
+     *
+     * @param sessionId - Session to query
+     * @returns Thought ids that are graph leaves
+     *
+     * @example
+     * ```typescript
+     * const tips = view.leaves('s1');
+     * ```
+     */
+    leaves(sessionId: SessionId): readonly ThoughtId[];
+    /**
+     * Collect every node id referenced by the edges and a set of nodes
+     * that have at least one incoming edge.
+     */
+    private _collectNodes;
+    /**
+     * Find roots (no incoming) ordered by the earliest outgoing edge
+     * `createdAt`. Nodes with no outgoing edges fall back to the order
+     * they appear among edges (already sorted by `createdAt`).
+     */
+    private _findRoots;
+    /**
+     * BFS from a list of root ids, visiting each node at most once.
+     */
+    private _bfsFromRoots;
+    /**
+     * Build an in-degree map covering every node referenced by the edges.
+     */
+    private _buildInDegree;
+    /**
+     * Generic BFS closure in either direction. Excludes the start node
+     * from the result and respects an optional depth cap.
+     */
+    private _bfsClosure;
+}
+//# sourceMappingURL=GraphView.d.ts.map

package/dist/core/graph/GraphView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphView.d.ts","sourceRoot":"","sources":["../../../src/core/graph/GraphView.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAInE;;;;;;;;;;GAUG;AACH,qBAAa,SAAS;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IAEpC;;;;;;;;;OASG;gBACS,KAAK,EAAE,UAAU;IAI7B;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,SAAS,EAAE;IAUzD;;;;;;;;;;;;;;;OAeG;IACH,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,SAAS,GAAG,SAAS,SAAS,EAAE;IAkBpF;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,SAAS,EAAE;IA4BvD;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,SAAS,EAAE;IAI9F;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,SAAS,EAAE;IAIhG;;;;;;;;;;OAUG;IACH,MAAM,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,SAAS,EAAE;IAelD;;;OAGG;IACH,OAAO,CAAC,aAAa;IAcrB;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAmBlB;;OAEG;IACH,OAAO,CAAC,aAAa;IAsBrB;;OAEG;IACH,OAAO,CAAC,cAAc;IAStB;;;OAGG;IACH,OAAO,CAAC,WAAW;CA+BnB"}

package/dist/core/graph/GraphView.js

@@ -0,0 +1,149 @@
+import { CycleDetectedError } from "../../errors.js";
+class GraphView {
+    _store;
+    constructor(store){
+        this._store = store;
+    }
+    chronological(sessionId) {
+        const edges = this._store.edgesForSession(sessionId);
+        if (0 === edges.length) return [];
+        const { nodes, hasIncoming } = this._collectNodes(edges);
+        const roots = this._findRoots(nodes, hasIncoming, edges);
+        return this._bfsFromRoots(sessionId, roots);
+    }
+    branchThoughts(sessionId, rootThoughtId) {
+        const visited = new Set([
+            rootThoughtId
+        ]);
+        const order = [
+            rootThoughtId
+        ];
+        const queue = [
+            rootThoughtId
+        ];
+        while(queue.length > 0){
+            const current = queue.shift();
+            const out = this._store.outgoing(sessionId, current);
+            for (const edge of out)if ('branch' === edge.kind) {
+                if (!visited.has(edge.to)) {
+                    visited.add(edge.to);
+                    order.push(edge.to);
+                    queue.push(edge.to);
+                }
+            }
+        }
+        return order;
+    }
+    topological(sessionId) {
+        const edges = this._store.edgesForSession(sessionId);
+        if (0 === edges.length) return [];
+        const inDegree = this._buildInDegree(edges);
+        const queue = [];
+        for (const [node, deg] of inDegree)if (0 === deg) queue.push(node);
+        const order = [];
+        while(queue.length > 0){
+            const node = queue.shift();
+            order.push(node);
+            for (const edge of this._store.outgoing(sessionId, node)){
+                const next = (inDegree.get(edge.to) ?? 0) - 1;
+                inDegree.set(edge.to, next);
+                if (0 === next) queue.push(edge.to);
+            }
+        }
+        if (order.length !== inDegree.size) throw new CycleDetectedError(`Cycle detected in session '${sessionId}': topological sort incomplete (${order.length}/${inDegree.size})`);
+        return order;
+    }
+    ancestors(sessionId, thoughtId, maxDepth) {
+        return this._bfsClosure(sessionId, thoughtId, maxDepth, 'incoming');
+    }
+    descendants(sessionId, thoughtId, maxDepth) {
+        return this._bfsClosure(sessionId, thoughtId, maxDepth, 'outgoing');
+    }
+    leaves(sessionId) {
+        const edges = this._store.edgesForSession(sessionId);
+        if (0 === edges.length) return [];
+        const { nodes } = this._collectNodes(edges);
+        const result = [];
+        for (const node of nodes)if (0 === this._store.outgoing(sessionId, node).length) result.push(node);
+        return result;
+    }
+    _collectNodes(edges) {
+        const nodes = new Set();
+        const hasIncoming = new Set();
+        for (const edge of edges){
+            nodes.add(edge.from);
+            nodes.add(edge.to);
+            hasIncoming.add(edge.to);
+        }
+        return {
+            nodes,
+            hasIncoming
+        };
+    }
+    _findRoots(nodes, hasIncoming, edges) {
+        const earliest = new Map();
+        for (const edge of edges)if (!earliest.has(edge.from)) earliest.set(edge.from, edge.createdAt);
+        const roots = [];
+        for (const node of nodes)if (!hasIncoming.has(node)) roots.push(node);
+        roots.sort((a, b)=>(earliest.get(a) ?? 1 / 0) - (earliest.get(b) ?? 1 / 0));
+        return roots;
+    }
+    _bfsFromRoots(sessionId, roots) {
+        const visited = new Set();
+        const order = [];
+        const queue = [];
+        for (const root of roots)if (!visited.has(root)) {
+            visited.add(root);
+            order.push(root);
+            queue.push(root);
+        }
+        while(queue.length > 0){
+            const node = queue.shift();
+            for (const edge of this._store.outgoing(sessionId, node))if (!visited.has(edge.to)) {
+                visited.add(edge.to);
+                order.push(edge.to);
+                queue.push(edge.to);
+            }
+        }
+        return order;
+    }
+    _buildInDegree(edges) {
+        const inDegree = new Map();
+        for (const edge of edges){
+            if (!inDegree.has(edge.from)) inDegree.set(edge.from, 0);
+            inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);
+        }
+        return inDegree;
+    }
+    _bfsClosure(sessionId, startId, maxDepth, direction) {
+        const cap = maxDepth ?? 1 / 0;
+        const visited = new Set([
+            startId
+        ]);
+        const order = [];
+        let frontier = [
+            startId
+        ];
+        let depth = 0;
+        while(frontier.length > 0 && depth < cap){
+            const next = [];
+            for (const node of frontier){
+                const edges = 'outgoing' === direction ? this._store.outgoing(sessionId, node) : this._store.incoming(sessionId, node);
+                for (const edge of edges){
+                    const neighbour = 'outgoing' === direction ? edge.to : edge.from;
+                    if (!visited.has(neighbour)) {
+                        visited.add(neighbour);
+                        order.push(neighbour);
+                        next.push(neighbour);
+                    }
+                }
+            }
+            frontier = next;
+            depth++;
+        }
+        return order;
+    }
+}
+export { GraphView };
+
+//# sourceMappingURL=GraphView.js.map

package/dist/core/graph/GraphView.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/graph/GraphView.js","sources":["../../../src/core/graph/GraphView.ts"],"sourcesContent":["/**\n * GraphView — read-only graph traversal queries over an {@link IEdgeStore}.\n *\n * Provides BFS / topological / ancestor / descendant queries over the\n * thought DAG. All methods return arrays of thought ids (ulid strings),\n * never `ThoughtData` objects — the view is intentionally decoupled from\n * `HistoryManager` so it can be reused by strategies that work purely in\n * terms of graph structure.\n *\n * Construction is cheap (stores a reference to the underlying store).\n * Each query reads the latest store state — no caching, no snapshots.\n *\n * @module core/graph/GraphView\n */\n\nimport type { IEdgeStore } from '../../contracts/interfaces.js';\nimport type { SessionId, ThoughtId } from '../../contracts/ids.js';\nimport { CycleDetectedError } from '../../errors.js';\nimport type { Edge } from './Edge.js';\n\n/**\n * Read-only traversal queries over an {@link IEdgeStore}.\n *\n * @example\n * ```typescript\n * const store = new EdgeStore();\n * // ... populate store ...\n * const view = new GraphView(store);\n * const order = view.topological('s1');\n * ```\n */\nexport class GraphView {\n\tprivate readonly _store: IEdgeStore;\n\n\t/**\n\t * Create a new GraphView backed by the given edge store.\n\t *\n\t * @param store - The edge store to query (held by reference, read-only access)\n\t *\n\t * @example\n\t * ```typescript\n\t * const view = new GraphView(edgeStore);\n\t * ```\n\t */\n\tconstructor(store: IEdgeStore) {\n\t\tthis._store = store;\n\t}\n\n\t/**\n\t * Return all thought ids in the session, ordered by BFS from roots.\n\t *\n\t * Roots are nodes with no incoming edges. Within a layer, neighbours\n\t * are visited in `outgoing` order (which the underlying store keeps\n\t * sorted by `createdAt` ascending).\n\t *\n\t * @param sessionId - Session to query\n\t * @returns Thought ids in chronological BFS order\n\t *\n\t * @example\n\t * ```typescript\n\t * const ids = view.chronological('s1');\n\t * ```\n\t */\n\tchronological(sessionId: SessionId): readonly ThoughtId[] {\n\t\tconst edges = this._store.edgesForSession(sessionId);\n\t\tif (edges.length === 0) {\n\t\t\treturn [];\n\t\t}\n\t\tconst { nodes, hasIncoming } = this._collectNodes(edges);\n\t\tconst roots = this._findRoots(nodes, hasIncoming, edges);\n\t\treturn this._bfsFromRoots(sessionId, roots) as readonly ThoughtId[];\n\t}\n\n\t/**\n\t * Return all thought ids reachable from `rootThoughtId` via `'branch'`\n\t * edges, including the root itself.\n\t *\n\t * Non-branch edges are ignored. Cycles (if any) do not cause infinite\n\t * loops because each node is visited at most once.\n\t *\n\t * @param sessionId - Session to query\n\t * @param rootThoughtId - The starting thought id (typically the branch root)\n\t * @returns Thought ids forming the branch (includes root)\n\t *\n\t * @example\n\t * ```typescript\n\t * const branchIds = view.branchThoughts('s1', 'thought-root');\n\t * ```\n\t */\n\tbranchThoughts(sessionId: SessionId, rootThoughtId: ThoughtId): readonly ThoughtId[] {\n\t\tconst visited = new Set<string>([rootThoughtId]);\n\t\tconst order: string[] = [rootThoughtId];\n\t\tconst queue: string[] = [rootThoughtId];\n\t\twhile (queue.length > 0) {\n\t\t\tconst current = queue.shift()!;\n\t\t\tconst out = this._store.outgoing(sessionId, current as ThoughtId);\n\t\t\tfor (const edge of out) {\n\t\t\t\tif (edge.kind !== 'branch') continue;\n\t\t\t\tif (visited.has(edge.to)) continue;\n\t\t\t\tvisited.add(edge.to);\n\t\t\t\torder.push(edge.to);\n\t\t\t\tqueue.push(edge.to);\n\t\t\t}\n\t\t}\n\t\treturn order as ThoughtId[];\n\t}\n\n\t/**\n\t * Return a topological ordering of all thought ids in the session\n\t * using Kahn's algorithm.\n\t *\n\t * @param sessionId - Session to query\n\t * @returns Thought ids in topological order\n\t * @throws {CycleDetectedError} If the graph contains a cycle\n\t *\n\t * @example\n\t * ```typescript\n\t * const order = view.topological('s1');\n\t * ```\n\t */\n\ttopological(sessionId: SessionId): readonly ThoughtId[] {\n\t\tconst edges = this._store.edgesForSession(sessionId);\n\t\tif (edges.length === 0) {\n\t\t\treturn [];\n\t\t}\n\t\tconst inDegree = this._buildInDegree(edges);\n\t\tconst queue: string[] = [];\n\t\tfor (const [node, deg] of inDegree) {\n\t\t\tif (deg === 0) queue.push(node);\n\t\t}\n\t\tconst order: string[] = [];\n\t\twhile (queue.length > 0) {\n\t\t\tconst node = queue.shift()!;\n\t\t\torder.push(node);\n\t\t\tfor (const edge of this._store.outgoing(sessionId, node as ThoughtId)) {\n\t\t\t\tconst next = (inDegree.get(edge.to) ?? 0) - 1;\n\t\t\t\tinDegree.set(edge.to, next);\n\t\t\t\tif (next === 0) queue.push(edge.to);\n\t\t\t}\n\t\t}\n\t\tif (order.length !== inDegree.size) {\n\t\t\tthrow new CycleDetectedError(\n\t\t\t\t`Cycle detected in session '${sessionId}': topological sort incomplete (${order.length}/${inDegree.size})`\n\t\t\t);\n\t\t}\n\t\treturn order as ThoughtId[];\n\t}\n\n\t/**\n\t * Return all ancestors of `thoughtId` via incoming-edge BFS.\n\t *\n\t * The starting node is NOT included. Cycles do not cause infinite loops.\n\t *\n\t * @param sessionId - Session to query\n\t * @param thoughtId - The thought to traverse from\n\t * @param maxDepth - Optional maximum traversal depth (1 = direct parents only)\n\t * @returns Ancestor thought ids in BFS order\n\t *\n\t * @example\n\t * ```typescript\n\t * const parents = view.ancestors('s1', 'thought-id', 1);\n\t * ```\n\t */\n\tancestors(sessionId: SessionId, thoughtId: ThoughtId, maxDepth?: number): readonly ThoughtId[] {\n\t\treturn this._bfsClosure(sessionId, thoughtId, maxDepth, 'incoming') as readonly ThoughtId[];\n\t}\n\n\t/**\n\t * Return all descendants of `thoughtId` via outgoing-edge BFS.\n\t *\n\t * The starting node is NOT included. Cycles do not cause infinite loops.\n\t *\n\t * @param sessionId - Session to query\n\t * @param thoughtId - The thought to traverse from\n\t * @param maxDepth - Optional maximum traversal depth (1 = direct children only)\n\t * @returns Descendant thought ids in BFS order\n\t *\n\t * @example\n\t * ```typescript\n\t * const children = view.descendants('s1', 'thought-id');\n\t * ```\n\t */\n\tdescendants(sessionId: SessionId, thoughtId: ThoughtId, maxDepth?: number): readonly ThoughtId[] {\n\t\treturn this._bfsClosure(sessionId, thoughtId, maxDepth, 'outgoing') as readonly ThoughtId[];\n\t}\n\n\t/**\n\t * Return all thought ids in the session that have no outgoing edges.\n\t *\n\t * @param sessionId - Session to query\n\t * @returns Thought ids that are graph leaves\n\t *\n\t * @example\n\t * ```typescript\n\t * const tips = view.leaves('s1');\n\t * ```\n\t */\n\tleaves(sessionId: SessionId): readonly ThoughtId[] {\n\t\tconst edges = this._store.edgesForSession(sessionId);\n\t\tif (edges.length === 0) {\n\t\t\treturn [];\n\t\t}\n\t\tconst { nodes } = this._collectNodes(edges);\n\t\tconst result: string[] = [];\n\t\tfor (const node of nodes) {\n\t\t\tif (this._store.outgoing(sessionId, node as ThoughtId).length === 0) {\n\t\t\t\tresult.push(node);\n\t\t\t}\n\t\t}\n\t\treturn result as ThoughtId[];\n\t}\n\n\t/**\n\t * Collect every node id referenced by the edges and a set of nodes\n\t * that have at least one incoming edge.\n\t */\n\tprivate _collectNodes(edges: readonly Edge[]): {\n\t\tnodes: Set<string>;\n\t\thasIncoming: Set<string>;\n\t} {\n\t\tconst nodes = new Set<string>();\n\t\tconst hasIncoming = new Set<string>();\n\t\tfor (const edge of edges) {\n\t\t\tnodes.add(edge.from);\n\t\t\tnodes.add(edge.to);\n\t\t\thasIncoming.add(edge.to);\n\t\t}\n\t\treturn { nodes, hasIncoming };\n\t}\n\n\t/**\n\t * Find roots (no incoming) ordered by the earliest outgoing edge\n\t * `createdAt`. Nodes with no outgoing edges fall back to the order\n\t * they appear among edges (already sorted by `createdAt`).\n\t */\n\tprivate _findRoots(\n\t\tnodes: Set<string>,\n\t\thasIncoming: Set<string>,\n\t\tedges: readonly Edge[]\n\t): string[] {\n\t\tconst earliest = new Map<string, number>();\n\t\tfor (const edge of edges) {\n\t\t\tif (!earliest.has(edge.from)) {\n\t\t\t\tearliest.set(edge.from, edge.createdAt);\n\t\t\t}\n\t\t}\n\t\tconst roots: string[] = [];\n\t\tfor (const node of nodes) {\n\t\t\tif (!hasIncoming.has(node)) roots.push(node);\n\t\t}\n\t\troots.sort((a, b) => (earliest.get(a) ?? Infinity) - (earliest.get(b) ?? Infinity));\n\t\treturn roots;\n\t}\n\n\t/**\n\t * BFS from a list of root ids, visiting each node at most once.\n\t */\n\tprivate _bfsFromRoots(sessionId: SessionId, roots: readonly string[]): readonly string[] {\n\t\tconst visited = new Set<string>();\n\t\tconst order: string[] = [];\n\t\tconst queue: string[] = [];\n\t\tfor (const root of roots) {\n\t\t\tif (visited.has(root)) continue;\n\t\t\tvisited.add(root);\n\t\t\torder.push(root);\n\t\t\tqueue.push(root);\n\t\t}\n\t\twhile (queue.length > 0) {\n\t\t\tconst node = queue.shift()!;\n\t\t\tfor (const edge of this._store.outgoing(sessionId, node as ThoughtId)) {\n\t\t\t\tif (visited.has(edge.to)) continue;\n\t\t\t\tvisited.add(edge.to);\n\t\t\t\torder.push(edge.to);\n\t\t\t\tqueue.push(edge.to);\n\t\t\t}\n\t\t}\n\t\treturn order;\n\t}\n\n\t/**\n\t * Build an in-degree map covering every node referenced by the edges.\n\t */\n\tprivate _buildInDegree(edges: readonly Edge[]): Map<string, number> {\n\t\tconst inDegree = new Map<string, number>();\n\t\tfor (const edge of edges) {\n\t\t\tif (!inDegree.has(edge.from)) inDegree.set(edge.from, 0);\n\t\t\tinDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);\n\t\t}\n\t\treturn inDegree;\n\t}\n\n\t/**\n\t * Generic BFS closure in either direction. Excludes the start node\n\t * from the result and respects an optional depth cap.\n\t */\n\tprivate _bfsClosure(\n\t\tsessionId: SessionId,\n\t\tstartId: string,\n\t\tmaxDepth: number | undefined,\n\t\tdirection: 'incoming' | 'outgoing'\n\t): readonly string[] {\n\t\tconst cap = maxDepth ?? Number.POSITIVE_INFINITY;\n\t\tconst visited = new Set<string>([startId]);\n\t\tconst order: string[] = [];\n\t\tlet frontier: string[] = [startId];\n\t\tlet depth = 0;\n\t\twhile (frontier.length > 0 && depth < cap) {\n\t\t\tconst next: string[] = [];\n\t\t\tfor (const node of frontier) {\n\t\t\t\tconst edges =\n\t\t\t\t\tdirection === 'outgoing'\n\t\t\t\t\t\t? this._store.outgoing(sessionId, node as ThoughtId)\n\t\t\t\t\t\t: this._store.incoming(sessionId, node as ThoughtId);\n\t\t\t\tfor (const edge of edges) {\n\t\t\t\t\tconst neighbour = direction === 'outgoing' ? edge.to : edge.from;\n\t\t\t\t\tif (visited.has(neighbour)) continue;\n\t\t\t\t\tvisited.add(neighbour);\n\t\t\t\t\torder.push(neighbour);\n\t\t\t\t\tnext.push(neighbour);\n\t\t\t\t}\n\t\t\t}\n\t\t\tfrontier = next;\n\t\t\tdepth++;\n\t\t}\n\t\treturn order;\n\t}\n}\n"],"names":["GraphView","store","sessionId","edges","nodes","hasIncoming","roots","rootThoughtId","visited","Set","order","queue","current","out","edge","inDegree","node","deg","next","CycleDetectedError","thoughtId","maxDepth","result","earliest","Map","a","b","Infinity","root","startId","direction","cap","Number","frontier","depth","neighbour"],"mappings":"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"}

package/dist/core/ids.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Unique identifier generation utilities for thoughts and edges.
+ *
+ * @module core/ids
+ */
+/**
+ * Generate a unique lexicographically-sortable identifier.
+ *
+ * Format: 8-char base36 timestamp + 20-char hex random (10 random bytes).
+ * Result is up to 28 characters, sortable by creation time.
+ *
+ * @returns A unique string identifier.
+ *
+ * @example
+ * ```typescript
+ * const id = generateUlid(); // '01h2k3m400a1b2c3d4e5f6...'
+ * ```
+ */
+export declare function generateUlid(): string;
+/**
+ * Valid session ID pattern: alphanumeric, hyphens, underscores.
+ *
+ * Length is enforced separately via {@link MAX_SESSION_ID_LENGTH}.
+ * Same character set as branch IDs.
+ */
+export declare const SESSION_ID_PATTERN: RegExp;
+/**
+ * Maximum session ID length (in characters).
+ *
+ * Allows compound identifiers (e.g. `user-123_task-abc`).
+ */
+export declare const MAX_SESSION_ID_LENGTH = 100;
+//# sourceMappingURL=ids.d.ts.map

package/dist/core/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/core/ids.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAIrC;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAAqB,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC"}

package/dist/core/ids.js

@@ -0,0 +1,11 @@
+import * as __rspack_external_node_crypto_2e7c4b46 from "node:crypto";
+function generateUlid() {
+    const timestamp = Date.now().toString(36).padStart(8, '0');
+    const random = __rspack_external_node_crypto_2e7c4b46.randomBytes(10).toString('hex');
+    return `${timestamp}${random}`;
+}
+const SESSION_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+const MAX_SESSION_ID_LENGTH = 100;
+export { MAX_SESSION_ID_LENGTH, SESSION_ID_PATTERN, generateUlid };
+
+//# sourceMappingURL=ids.js.map

package/dist/core/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/ids.js","sources":["../../src/core/ids.ts"],"sourcesContent":["/**\n * Unique identifier generation utilities for thoughts and edges.\n *\n * @module core/ids\n */\n\nimport * as crypto from 'node:crypto';\n\n/**\n * Generate a unique lexicographically-sortable identifier.\n *\n * Format: 8-char base36 timestamp + 20-char hex random (10 random bytes).\n * Result is up to 28 characters, sortable by creation time.\n *\n * @returns A unique string identifier.\n *\n * @example\n * ```typescript\n * const id = generateUlid(); // '01h2k3m400a1b2c3d4e5f6...'\n * ```\n */\nexport function generateUlid(): string {\n\tconst timestamp = Date.now().toString(36).padStart(8, '0');\n\tconst random = crypto.randomBytes(10).toString('hex');\n\treturn `${timestamp}${random}`;\n}\n\n/**\n * Valid session ID pattern: alphanumeric, hyphens, underscores.\n *\n * Length is enforced separately via {@link MAX_SESSION_ID_LENGTH}.\n * Same character set as branch IDs.\n */\nexport const SESSION_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;\n\n/**\n * Maximum session ID length (in characters).\n *\n * Allows compound identifiers (e.g. `user-123_task-abc`).\n */\nexport const MAX_SESSION_ID_LENGTH = 100;\n"],"names":["generateUlid","timestamp","Date","random","crypto","SESSION_ID_PATTERN","MAX_SESSION_ID_LENGTH"],"mappings":";AAqBO,SAASA;IACf,MAAMC,YAAYC,KAAK,GAAG,GAAG,QAAQ,CAAC,IAAI,QAAQ,CAAC,GAAG;IACtD,MAAMC,SAASC,uCAAAA,WAAkB,CAAC,IAAI,QAAQ,CAAC;IAC/C,OAAO,GAAGH,YAAYE,QAAQ;AAC/B;AAQO,MAAME,qBAAqB;AAO3B,MAAMC,wBAAwB"}

package/dist/core/reasoning/OutcomeRecorder.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Records verification outcomes for confidence calibration.
+ *
+ * No-op implementation when feature flag is disabled.
+ * Stores outcomes per-session in memory for later calibration use.
+ *
+ * @module core/reasoning/OutcomeRecorder
+ */
+import type { IOutcomeRecorder, VerificationOutcome } from '../../contracts/interfaces.js';
+import type { SessionId, ThoughtId } from '../../contracts/ids.js';
+/**
+ * Configuration for OutcomeRecorder.
+ */
+export interface OutcomeRecorderConfig {
+    /** Whether outcome recording is enabled. */
+    enabled: boolean;
+}
+/**
+ * Records verification outcomes for confidence calibration.
+ *
+ * When disabled (default), all methods are no-ops and return empty arrays.
+ * When enabled, outcomes are stored in memory per-session.
+ *
+ * @example
+ * ```typescript
+ * const recorder = new OutcomeRecorder({ enabled: true });
+ * recorder.recordVerification({
+ *   thoughtId: 't1',
+ *   thoughtNumber: 1,
+ *   sessionId: 'session-a',
+ *   predicted: 0.8,
+ *   actual: 1,
+ *   type: 'verification',
+ * });
+ * const outcomes = recorder.getOutcomes('session-a');
+ * ```
+ */
+export declare class OutcomeRecorder implements IOutcomeRecorder {
+    private readonly _outcomes;
+    private readonly _enabled;
+    /**
+     * Whether outcome recording is currently enabled.
+     */
+    get enabled(): boolean;
+    /**
+     * Create a new OutcomeRecorder.
+     *
+     * @param config - Recorder configuration
+     */
+    constructor(config: OutcomeRecorderConfig);
+    /**
+     * Assert that a target is available for one outcome label.
+     *
+     * @param sessionId - Canonical session namespace
+     * @param thoughtId - Stable target identity
+     * @throws {ValidationError} When the target was already labeled
+     */
+    assertCanRecord(sessionId: SessionId, thoughtId: ThoughtId): void;
+    /**
+     * Record a verification outcome.
+     *
+     * No-op when outcome recording is disabled.
+     *
+     * @param outcome - The outcome data (recordedAt is auto-set)
+     */
+    recordVerification(outcome: Omit<VerificationOutcome, 'recordedAt'>): void;
+    /**
+     * Get all recorded outcomes for a session.
+     *
+     * @param sessionId - The session id to query
+     * @returns Array of outcomes (empty when disabled or no data)
+     */
+    getOutcomes(sessionId: SessionId): VerificationOutcome[];
+    /**
+     * Get outcomes across all sessions.
+     *
+     * @returns Flat array of all outcomes (empty when disabled)
+     */
+    getAllOutcomes(): VerificationOutcome[];
+    /**
+     * Clear outcomes for a specific session.
+     *
+     * @param sessionId - The session id to clear
+     */
+    clearOutcomes(sessionId: SessionId): void;
+    clearAllOutcomes(): void;
+}
+//# sourceMappingURL=OutcomeRecorder.d.ts.map

package/dist/core/reasoning/OutcomeRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OutcomeRecorder.d.ts","sourceRoot":"","sources":["../../../src/core/reasoning/OutcomeRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAC3F,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnE;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,eAAgB,YAAW,gBAAgB;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkE;IAC5F,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IAEnC;;OAEG;IACH,IAAW,OAAO,IAAI,OAAO,CAE5B;IAED;;;;OAIG;gBACS,MAAM,EAAE,qBAAqB;IAIzC;;;;;;OAMG;IACH,eAAe,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI;IAUjE;;;;;;OAMG;IACH,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC,mBAAmB,EAAE,YAAY,CAAC,GAAG,IAAI;IAc1E;;;;;OAKG;IACH,WAAW,CAAC,SAAS,EAAE,SAAS,GAAG,mBAAmB,EAAE;IAKxD;;;;OAIG;IACH,cAAc,IAAI,mBAAmB,EAAE;IASvC;;;;OAIG;IACH,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAIzC,gBAAgB,IAAI,IAAI;CAGxB"}

package/dist/core/reasoning/OutcomeRecorder.js

@@ -0,0 +1,51 @@
+import { ValidationError } from "../../errors.js";
+class OutcomeRecorder {
+    _outcomes = new Map();
+    _enabled;
+    get enabled() {
+        return this._enabled;
+    }
+    constructor(config){
+        this._enabled = config.enabled;
+    }
+    assertCanRecord(sessionId, thoughtId) {
+        if (!this._enabled) return;
+        if (this._outcomes.get(sessionId)?.has(thoughtId)) throw new ValidationError('verification_result', 'The verification target already has a recorded result');
+    }
+    recordVerification(outcome) {
+        if (!this._enabled) return;
+        this.assertCanRecord(outcome.sessionId, outcome.thoughtId);
+        const full = {
+            ...outcome,
+            recordedAt: Date.now()
+        };
+        const sessionOutcomes = this._outcomes.get(outcome.sessionId) ?? new Map();
+        sessionOutcomes.set(outcome.thoughtId, full);
+        this._outcomes.set(outcome.sessionId, sessionOutcomes);
+    }
+    getOutcomes(sessionId) {
+        if (!this._enabled) return [];
+        return [
+            ...this._outcomes.get(sessionId)?.values() ?? []
+        ].map((outcome)=>({
+                ...outcome
+            }));
+    }
+    getAllOutcomes() {
+        if (!this._enabled) return [];
+        const all = [];
+        for (const outcomes of this._outcomes.values())for (const outcome of outcomes.values())all.push({
+            ...outcome
+        });
+        return all;
+    }
+    clearOutcomes(sessionId) {
+        this._outcomes.delete(sessionId);
+    }
+    clearAllOutcomes() {
+        this._outcomes.clear();
+    }
+}
+export { OutcomeRecorder };
+
+//# sourceMappingURL=OutcomeRecorder.js.map

package/dist/core/reasoning/OutcomeRecorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/reasoning/OutcomeRecorder.js","sources":["../../../src/core/reasoning/OutcomeRecorder.ts"],"sourcesContent":["/**\n * Records verification outcomes for confidence calibration.\n *\n * No-op implementation when feature flag is disabled.\n * Stores outcomes per-session in memory for later calibration use.\n *\n * @module core/reasoning/OutcomeRecorder\n */\n\nimport type { IOutcomeRecorder, VerificationOutcome } from '../../contracts/interfaces.js';\nimport type { SessionId, ThoughtId } from '../../contracts/ids.js';\nimport { ValidationError } from '../../errors.js';\n\n/**\n * Configuration for OutcomeRecorder.\n */\nexport interface OutcomeRecorderConfig {\n\t/** Whether outcome recording is enabled. */\n\tenabled: boolean;\n}\n\n/**\n * Records verification outcomes for confidence calibration.\n *\n * When disabled (default), all methods are no-ops and return empty arrays.\n * When enabled, outcomes are stored in memory per-session.\n *\n * @example\n * ```typescript\n * const recorder = new OutcomeRecorder({ enabled: true });\n * recorder.recordVerification({\n *   thoughtId: 't1',\n *   thoughtNumber: 1,\n *   sessionId: 'session-a',\n *   predicted: 0.8,\n *   actual: 1,\n *   type: 'verification',\n * });\n * const outcomes = recorder.getOutcomes('session-a');\n * ```\n */\nexport class OutcomeRecorder implements IOutcomeRecorder {\n\tprivate readonly _outcomes: Map<SessionId, Map<ThoughtId, VerificationOutcome>> = new Map();\n\tprivate readonly _enabled: boolean;\n\n\t/**\n\t * Whether outcome recording is currently enabled.\n\t */\n\tpublic get enabled(): boolean {\n\t\treturn this._enabled;\n\t}\n\n\t/**\n\t * Create a new OutcomeRecorder.\n\t *\n\t * @param config - Recorder configuration\n\t */\n\tconstructor(config: OutcomeRecorderConfig) {\n\t\tthis._enabled = config.enabled;\n\t}\n\n\t/**\n\t * Assert that a target is available for one outcome label.\n\t *\n\t * @param sessionId - Canonical session namespace\n\t * @param thoughtId - Stable target identity\n\t * @throws {ValidationError} When the target was already labeled\n\t */\n\tassertCanRecord(sessionId: SessionId, thoughtId: ThoughtId): void {\n\t\tif (!this._enabled) return;\n\t\tif (this._outcomes.get(sessionId)?.has(thoughtId)) {\n\t\t\tthrow new ValidationError(\n\t\t\t\t'verification_result',\n\t\t\t\t'The verification target already has a recorded result'\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Record a verification outcome.\n\t *\n\t * No-op when outcome recording is disabled.\n\t *\n\t * @param outcome - The outcome data (recordedAt is auto-set)\n\t */\n\trecordVerification(outcome: Omit<VerificationOutcome, 'recordedAt'>): void {\n\t\tif (!this._enabled) return;\n\t\tthis.assertCanRecord(outcome.sessionId, outcome.thoughtId);\n\n\t\tconst full: VerificationOutcome = {\n\t\t\t...outcome,\n\t\t\trecordedAt: Date.now(),\n\t\t};\n\n\t\tconst sessionOutcomes = this._outcomes.get(outcome.sessionId) ?? new Map();\n\t\tsessionOutcomes.set(outcome.thoughtId, full);\n\t\tthis._outcomes.set(outcome.sessionId, sessionOutcomes);\n\t}\n\n\t/**\n\t * Get all recorded outcomes for a session.\n\t *\n\t * @param sessionId - The session id to query\n\t * @returns Array of outcomes (empty when disabled or no data)\n\t */\n\tgetOutcomes(sessionId: SessionId): VerificationOutcome[] {\n\t\tif (!this._enabled) return [];\n\t\treturn [...(this._outcomes.get(sessionId)?.values() ?? [])].map((outcome) => ({ ...outcome }));\n\t}\n\n\t/**\n\t * Get outcomes across all sessions.\n\t *\n\t * @returns Flat array of all outcomes (empty when disabled)\n\t */\n\tgetAllOutcomes(): VerificationOutcome[] {\n\t\tif (!this._enabled) return [];\n\t\tconst all: VerificationOutcome[] = [];\n\t\tfor (const outcomes of this._outcomes.values()) {\n\t\t\tfor (const outcome of outcomes.values()) all.push({ ...outcome });\n\t\t}\n\t\treturn all;\n\t}\n\n\t/**\n\t * Clear outcomes for a specific session.\n\t *\n\t * @param sessionId - The session id to clear\n\t */\n\tclearOutcomes(sessionId: SessionId): void {\n\t\tthis._outcomes.delete(sessionId);\n\t}\n\n\tclearAllOutcomes(): void {\n\t\tthis._outcomes.clear();\n\t}\n}\n"],"names":["OutcomeRecorder","Map","config","sessionId","thoughtId","ValidationError","outcome","full","Date","sessionOutcomes","all","outcomes"],"mappings":";AAyCO,MAAMA;IACK,YAAiE,IAAIC,MAAM;IAC3E,SAAkB;IAKnC,IAAW,UAAmB;QAC7B,OAAO,IAAI,CAAC,QAAQ;IACrB;IAOA,YAAYC,MAA6B,CAAE;QAC1C,IAAI,CAAC,QAAQ,GAAGA,OAAO,OAAO;IAC/B;IASA,gBAAgBC,SAAoB,EAAEC,SAAoB,EAAQ;QACjE,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE;QACpB,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAACD,YAAY,IAAIC,YACtC,MAAM,IAAIC,gBACT,uBACA;IAGH;IASA,mBAAmBC,OAAgD,EAAQ;QAC1E,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE;QACpB,IAAI,CAAC,eAAe,CAACA,QAAQ,SAAS,EAAEA,QAAQ,SAAS;QAEzD,MAAMC,OAA4B;YACjC,GAAGD,OAAO;YACV,YAAYE,KAAK,GAAG;QACrB;QAEA,MAAMC,kBAAkB,IAAI,CAAC,SAAS,CAAC,GAAG,CAACH,QAAQ,SAAS,KAAK,IAAIL;QACrEQ,gBAAgB,GAAG,CAACH,QAAQ,SAAS,EAAEC;QACvC,IAAI,CAAC,SAAS,CAAC,GAAG,CAACD,QAAQ,SAAS,EAAEG;IACvC;IAQA,YAAYN,SAAoB,EAAyB;QACxD,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE;QAC7B,OAAO;eAAK,IAAI,CAAC,SAAS,CAAC,GAAG,CAACA,YAAY,YAAY,EAAE;SAAE,CAAC,GAAG,CAAC,CAACG,UAAa;gBAAE,GAAGA,OAAO;YAAC;IAC5F;IAOA,iBAAwC;QACvC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE;QAC7B,MAAMI,MAA6B,EAAE;QACrC,KAAK,MAAMC,YAAY,IAAI,CAAC,SAAS,CAAC,MAAM,GAC3C,KAAK,MAAML,WAAWK,SAAS,MAAM,GAAID,IAAI,IAAI,CAAC;YAAE,GAAGJ,OAAO;QAAC;QAEhE,OAAOI;IACR;IAOA,cAAcP,SAAoB,EAAQ;QACzC,IAAI,CAAC,SAAS,CAAC,MAAM,CAACA;IACvB;IAEA,mBAAyB;QACxB,IAAI,CAAC,SAAS,CAAC,KAAK;IACrB;AACD"}

package/dist/core/reasoning/strategies/SequentialStrategy.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Sequential reasoning strategy — the default policy that preserves existing
+ * {@link ThoughtProcessor} behavior. Continues the chain unless the current
+ * thought explicitly signals termination via `next_thought_needed === false`.
+ *
+ * Pure policy: no mutable state, no I/O, no module-level variables. All
+ * methods are deterministic functions of their inputs.
+ *
+ * @module core/reasoning/strategies/SequentialStrategy
+ */
+import type { IReasoningStrategy, StrategyContext, StrategyDecision } from '../../../contracts/strategy.js';
+/**
+ * Default sequential strategy. Mirrors the legacy linear thinking flow:
+ *
+ * - Continue while `next_thought_needed` is truthy (or unset).
+ * - Terminate as soon as `next_thought_needed === false`.
+ * - Branch when both `branch_from_thought` and `branch_id` are present.
+ *
+ * Type-agnostic: all `ThoughtType` variants (including `assumption`,
+ * `decomposition`, `backtrack`, `tool_call`, `tool_observation`, and the
+ * legacy six) pass through unchanged. The strategy intentionally inspects
+ * only `next_thought_needed`, `branch_from_thought`, and `branch_id` —
+ * type-aware behavior lives in evaluator/scoring layers, not here.
+ *
+ * @example
+ * ```ts
+ * const strategy = new SequentialStrategy();
+ * const decision = strategy.decide(ctx);
+ * if (decision.action === 'terminate') stop();
+ * ```
+ */
+export declare class SequentialStrategy implements IReasoningStrategy {
+    readonly name: "sequential";
+    /**
+     * Compute the next action for the chain.
+     *
+     * @param ctx - Read-only session snapshot.
+     * @returns `{ action: 'terminate' }` when current thought signals stop,
+     *          otherwise `{ action: 'continue' }`.
+     */
+    decide(ctx: StrategyContext): StrategyDecision;
+    /**
+     * Predicate: should the chain branch right now?
+     * True iff both `branch_from_thought` and `branch_id` are set on the
+     * current thought.
+     */
+    shouldBranch(ctx: StrategyContext): boolean;
+    /**
+     * Predicate: should the chain terminate right now?
+     * True iff `next_thought_needed === false`.
+     */
+    shouldTerminate(ctx: StrategyContext): boolean;
+}
+//# sourceMappingURL=SequentialStrategy.d.ts.map

package/dist/core/reasoning/strategies/SequentialStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SequentialStrategy.d.ts","sourceRoot":"","sources":["../../../../src/core/reasoning/strategies/SequentialStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACX,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,MAAM,gCAAgC,CAAC;AAExC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,kBAAmB,YAAW,kBAAkB;IAC5D,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;IAEtC;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,EAAE,eAAe,GAAG,gBAAgB;IAO9C;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO;IAK3C;;;OAGG;IACH,eAAe,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO;CAG9C"}

package/dist/core/reasoning/strategies/SequentialStrategy.js

@@ -0,0 +1,22 @@
+class SequentialStrategy {
+    name = 'sequential';
+    decide(ctx) {
+        if (false === ctx.currentThought.next_thought_needed) return {
+            action: 'terminate',
+            reason: 'next_thought_needed=false'
+        };
+        return {
+            action: 'continue'
+        };
+    }
+    shouldBranch(ctx) {
+        const t = ctx.currentThought;
+        return void 0 !== t.branch_from_thought && void 0 !== t.branch_id;
+    }
+    shouldTerminate(ctx) {
+        return false === ctx.currentThought.next_thought_needed;
+    }
+}
+export { SequentialStrategy };
+
+//# sourceMappingURL=SequentialStrategy.js.map

package/dist/core/reasoning/strategies/SequentialStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/reasoning/strategies/SequentialStrategy.js","sources":["../../../../src/core/reasoning/strategies/SequentialStrategy.ts"],"sourcesContent":["/**\n * Sequential reasoning strategy — the default policy that preserves existing\n * {@link ThoughtProcessor} behavior. Continues the chain unless the current\n * thought explicitly signals termination via `next_thought_needed === false`.\n *\n * Pure policy: no mutable state, no I/O, no module-level variables. All\n * methods are deterministic functions of their inputs.\n *\n * @module core/reasoning/strategies/SequentialStrategy\n */\n\nimport type {\n\tIReasoningStrategy,\n\tStrategyContext,\n\tStrategyDecision,\n} from '../../../contracts/strategy.js';\n\n/**\n * Default sequential strategy. Mirrors the legacy linear thinking flow:\n *\n * - Continue while `next_thought_needed` is truthy (or unset).\n * - Terminate as soon as `next_thought_needed === false`.\n * - Branch when both `branch_from_thought` and `branch_id` are present.\n *\n * Type-agnostic: all `ThoughtType` variants (including `assumption`,\n * `decomposition`, `backtrack`, `tool_call`, `tool_observation`, and the\n * legacy six) pass through unchanged. The strategy intentionally inspects\n * only `next_thought_needed`, `branch_from_thought`, and `branch_id` —\n * type-aware behavior lives in evaluator/scoring layers, not here.\n *\n * @example\n * ```ts\n * const strategy = new SequentialStrategy();\n * const decision = strategy.decide(ctx);\n * if (decision.action === 'terminate') stop();\n * ```\n */\nexport class SequentialStrategy implements IReasoningStrategy {\n\treadonly name = 'sequential' as const;\n\n\t/**\n\t * Compute the next action for the chain.\n\t *\n\t * @param ctx - Read-only session snapshot.\n\t * @returns `{ action: 'terminate' }` when current thought signals stop,\n\t *          otherwise `{ action: 'continue' }`.\n\t */\n\tdecide(ctx: StrategyContext): StrategyDecision {\n\t\tif (ctx.currentThought.next_thought_needed === false) {\n\t\t\treturn { action: 'terminate', reason: 'next_thought_needed=false' };\n\t\t}\n\t\treturn { action: 'continue' };\n\t}\n\n\t/**\n\t * Predicate: should the chain branch right now?\n\t * True iff both `branch_from_thought` and `branch_id` are set on the\n\t * current thought.\n\t */\n\tshouldBranch(ctx: StrategyContext): boolean {\n\t\tconst t = ctx.currentThought;\n\t\treturn t.branch_from_thought !== undefined && t.branch_id !== undefined;\n\t}\n\n\t/**\n\t * Predicate: should the chain terminate right now?\n\t * True iff `next_thought_needed === false`.\n\t */\n\tshouldTerminate(ctx: StrategyContext): boolean {\n\t\treturn ctx.currentThought.next_thought_needed === false;\n\t}\n}\n"],"names":["SequentialStrategy","ctx","t","undefined"],"mappings":"AAqCO,MAAMA;IACH,OAAO,aAAsB;IAStC,OAAOC,GAAoB,EAAoB;QAC9C,IAAIA,AAA2C,UAA3CA,IAAI,cAAc,CAAC,mBAAmB,EACzC,OAAO;YAAE,QAAQ;YAAa,QAAQ;QAA4B;QAEnE,OAAO;YAAE,QAAQ;QAAW;IAC7B;IAOA,aAAaA,GAAoB,EAAW;QAC3C,MAAMC,IAAID,IAAI,cAAc;QAC5B,OAAOC,AAA0BC,WAA1BD,EAAE,mBAAmB,IAAkBA,AAAgBC,WAAhBD,EAAE,SAAS;IAC1D;IAMA,gBAAgBD,GAAoB,EAAW;QAC9C,OAAOA,AAA2C,UAA3CA,IAAI,cAAc,CAAC,mBAAmB;IAC9C;AACD"}