@iworkforces/tracelattice 2.0.3

package/dist/core/evaluator/internals.js

@@ -0,0 +1,43 @@
+const ALL_THOUGHT_TYPES = [
+    'regular',
+    'hypothesis',
+    'verification',
+    'critique',
+    'synthesis',
+    'meta',
+    'tool_call',
+    'tool_observation',
+    'assumption',
+    'decomposition',
+    'backtrack'
+];
+function _countByType(history) {
+    const counts = Object.fromEntries(ALL_THOUGHT_TYPES.map((t)=>[
+            t,
+            0
+        ]));
+    for (const thought of history){
+        const type = thought.thought_type ?? 'regular';
+        if (type in counts) counts[type]++;
+    }
+    return counts;
+}
+const countByType = _countByType;
+function _computeChainDepth(history) {
+    if (0 === history.length) return 0;
+    let maxDepth = 1;
+    let currentDepth = 1;
+    for(let i = 1; i < history.length; i++){
+        const thought = history[i];
+        if (thought.branch_from_thought) currentDepth = 1;
+        else {
+            currentDepth++;
+            maxDepth = Math.max(maxDepth, currentDepth);
+        }
+    }
+    return maxDepth;
+}
+const computeChainDepth = _computeChainDepth;
+export { ALL_THOUGHT_TYPES, _computeChainDepth, _countByType, computeChainDepth, countByType };
+
+//# sourceMappingURL=internals.js.map

package/dist/core/evaluator/internals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/evaluator/internals.js","sources":["../../../src/core/evaluator/internals.ts"],"sourcesContent":["/**\n * Shared internal helpers for evaluator submodules.\n *\n * Pure utility functions used by SignalComputer (and future evaluator\n * components such as StatsComputer / PatternDetector). All helpers are\n * stateless and have no side effects.\n *\n * @module core/evaluator/internals\n */\n\nimport type { ThoughtType } from '../reasoning.js';\nimport type { ThoughtData } from '../thought.js';\n\n/** All valid thought types for distribution counting. */\nexport const ALL_THOUGHT_TYPES: ThoughtType[] = [\n\t'regular',\n\t'hypothesis',\n\t'verification',\n\t'critique',\n\t'synthesis',\n\t'meta',\n\t'tool_call',\n\t'tool_observation',\n\t'assumption',\n\t'decomposition',\n\t'backtrack',\n];\n\n/**\n * Count thoughts in `history` grouped by {@link ThoughtType}.\n *\n * Thoughts without an explicit `thought_type` are counted as `'regular'`.\n *\n * @param history - Thoughts to count\n * @returns Record mapping each ThoughtType to its occurrence count\n */\nexport function _countByType(history: ThoughtData[]): Record<ThoughtType, number> {\n\tconst counts = Object.fromEntries(ALL_THOUGHT_TYPES.map((t) => [t, 0])) as Record<\n\t\tThoughtType,\n\t\tnumber\n\t>;\n\n\tfor (const thought of history) {\n\t\tconst type = thought.thought_type ?? 'regular';\n\t\tif (type in counts) {\n\t\t\tcounts[type]++;\n\t\t}\n\t}\n\n\treturn counts;\n}\n\n/** Alias of {@link _countByType} without the underscore prefix. */\nexport const countByType = _countByType;\n\n/**\n * Compute the longest contiguous chain depth (sequence of thoughts without branching).\n *\n * A new chain starts whenever a thought has `branch_from_thought` set.\n *\n * @param history - Thoughts in chronological order\n * @returns Length of the longest non-branching chain (0 for empty history)\n */\nexport function _computeChainDepth(history: ThoughtData[]): number {\n\tif (history.length === 0) return 0;\n\tlet maxDepth = 1;\n\tlet currentDepth = 1;\n\n\tfor (let i = 1; i < history.length; i++) {\n\t\tconst thought = history[i]!;\n\t\tif (!thought.branch_from_thought) {\n\t\t\tcurrentDepth++;\n\t\t\tmaxDepth = Math.max(maxDepth, currentDepth);\n\t\t} else {\n\t\t\tcurrentDepth = 1;\n\t\t}\n\t}\n\n\treturn maxDepth;\n}\n\n/** Alias of {@link _computeChainDepth} without the underscore prefix. */\nexport const computeChainDepth = _computeChainDepth;\n"],"names":["ALL_THOUGHT_TYPES","_countByType","history","counts","Object","t","thought","type","countByType","_computeChainDepth","maxDepth","currentDepth","i","Math","computeChainDepth"],"mappings":"AAcO,MAAMA,oBAAmC;IAC/C;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACA;AAUM,SAASC,aAAaC,OAAsB;IAClD,MAAMC,SAASC,OAAO,WAAW,CAACJ,kBAAkB,GAAG,CAAC,CAACK,IAAM;YAACA;YAAG;SAAE;IAKrE,KAAK,MAAMC,WAAWJ,QAAS;QAC9B,MAAMK,OAAOD,QAAQ,YAAY,IAAI;QACrC,IAAIC,QAAQJ,QACXA,MAAM,CAACI,KAAK;IAEd;IAEA,OAAOJ;AACR;AAGO,MAAMK,cAAcP;AAUpB,SAASQ,mBAAmBP,OAAsB;IACxD,IAAIA,AAAmB,MAAnBA,QAAQ,MAAM,EAAQ,OAAO;IACjC,IAAIQ,WAAW;IACf,IAAIC,eAAe;IAEnB,IAAK,IAAIC,IAAI,GAAGA,IAAIV,QAAQ,MAAM,EAAEU,IAAK;QACxC,MAAMN,UAAUJ,OAAO,CAACU,EAAE;QAC1B,IAAKN,QAAQ,mBAAmB,EAI/BK,eAAe;aAJkB;YACjCA;YACAD,WAAWG,KAAK,GAAG,CAACH,UAAUC;QAC/B;IAGD;IAEA,OAAOD;AACR;AAGO,MAAMI,oBAAoBL"}

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

@@ -0,0 +1,58 @@
+/**
+ * Edge type definitions for the thought DAG.
+ *
+ * Edges represent semantic relationships between thoughts. Endpoints reference
+ * `thought.id` (ulid string) rather than `thought_number` to avoid ambiguity
+ * across branches.
+ *
+ * @module core/graph/Edge
+ */
+import type { EdgeId, SessionId, ThoughtId } from '../../contracts/ids.js';
+/**
+ * Kinds of relationships between thoughts in the DAG.
+ *
+ * Each kind represents a semantic relationship that the reasoning controller
+ * can use for search policy decisions.
+ *
+ * NOTE: Kept as a hand-written union (not inferred from `EdgeKindSchema`) because
+ * `schema.ts` imports `EdgeKind` from this file to constrain the schema via
+ * `satisfies v.GenericSchema<EdgeKind>`. Reversing the dependency would create a
+ * circular import (schema.ts → Edge.ts → schema.ts). The `satisfies` clause in
+ * schema.ts already guarantees the schema and the union stay in sync.
+ */
+export type EdgeKind = 'sequence' | 'branch' | 'merge' | 'verifies' | 'critiques' | 'derives_from' | 'tool_invocation' | 'revises';
+/**
+ * A directed edge in the thought DAG.
+ *
+ * Endpoints use `thought.id` (ulid string), not `thought_number`,
+ * to avoid ambiguity under branching.
+ *
+ * @example
+ * ```typescript
+ * const edge: Edge = {
+ *   id: generateUlid(),
+ *   from: parentThought.id,
+ *   to: childThought.id,
+ *   kind: 'sequence',
+ *   sessionId: '__global__',
+ *   createdAt: Date.now(),
+ * };
+ * ```
+ */
+export interface Edge {
+    /** Unique edge identifier (ulid). */
+    readonly id: EdgeId;
+    /** Source thought id. */
+    readonly from: ThoughtId;
+    /** Target thought id. */
+    readonly to: ThoughtId;
+    /** Semantic relationship kind. */
+    readonly kind: EdgeKind;
+    /** Session this edge belongs to. */
+    readonly sessionId: SessionId;
+    /** Creation timestamp (`Date.now()`). */
+    readonly createdAt: number;
+    /** Optional metadata for strategy-specific annotations. */
+    readonly metadata?: Record<string, unknown>;
+}
+//# sourceMappingURL=Edge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Edge.d.ts","sourceRoot":"","sources":["../../../src/core/graph/Edge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAE3E;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,QAAQ,GACjB,UAAU,GACV,QAAQ,GACR,OAAO,GACP,UAAU,GACV,WAAW,GACX,cAAc,GACd,iBAAiB,GACjB,SAAS,CAAC;AAEb;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,IAAI;IACpB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,yBAAyB;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,yBAAyB;IACzB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,oCAAoC;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C"}

package/dist/core/graph/Edge.js

@@ -0,0 +1 @@
+export { };

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

@@ -0,0 +1,68 @@
+/**
+ * EdgeEmitter — emits DAG edges for thoughts based on their metadata.
+ *
+ * Stateless helper extracted from HistoryManager. Holds a reference to an
+ * optional `IEdgeStore` and a feature flag (`dagEdges`) gating writes.
+ *
+ * @module EdgeEmitter
+ */
+import type { IEdgeStore } from '../../contracts/interfaces.js';
+import type { Logger } from '../../logger/StructuredLogger.js';
+import type { ThoughtData } from '../thought.js';
+import type { ThoughtAdmissionContext } from '../IHistoryManager.js';
+import { type BranchId, type SessionId } from '../../contracts/ids.js';
+/** Minimal session view needed for edge emission. */
+export interface EdgeEmissionSession {
+    thought_history: ThoughtData[];
+    branches: Record<BranchId, ThoughtData[]>;
+}
+/** Configuration options for EdgeEmitter. */
+export interface EdgeEmitterConfig {
+    edgeStore?: IEdgeStore;
+    dagEdges?: boolean;
+    defaultSessionId: SessionId;
+    logger?: Logger;
+}
+/**
+ * Emits DAG edges for thought relationships when an `IEdgeStore` is configured
+ * and the `dagEdges` feature flag is enabled. No-ops otherwise.
+ */
+export declare class EdgeEmitter {
+    private readonly _edgeStore?;
+    private readonly _dagEdges;
+    private readonly _defaultSessionId;
+    private readonly _logger;
+    constructor(config: EdgeEmitterConfig);
+    /** Returns true when edge emission is active (store + flag both set). */
+    isEnabled(): boolean;
+    /**
+     * Emits DAG edges for a thought based on its metadata fields.
+     *
+     * Edge kinds (in priority order):
+     * - branch: branch_from_thought + branch_id → parent.id → current.id
+     * - merge: merge_from_thoughts → source.id → current.id (per source)
+     * - verifies: verification_target + thought_type=verification → current.id → target.id
+     * - critiques: verification_target + thought_type=critique → current.id → target.id
+     * - derives_from: synthesis_sources → source.id → current.id (per source)
+     * - revises: revises_thought → current.id → target.id
+     * - tool_invocation: stable admission source id → current.id
+     * - sequence: default chronological link from previous thought (if none of the above)
+     * @returns True only when at least one edge was added to the store
+     */
+    emitEdgesForThought(session: EdgeEmissionSession, thought: ThoughtData, context?: ThoughtAdmissionContext): boolean;
+    private _emitBranchEdge;
+    private _emitMergeEdges;
+    private _emitVerificationEdge;
+    private _emitCritiqueEdge;
+    private _emitSynthesisEdges;
+    private _emitRevisionEdge;
+    private _emitToolInvocationEdge;
+    private _emitSequenceEdge;
+    /**
+     * Adds an edge to the edge store if both endpoints are non-empty strings.
+     * Returns true if added, false if skipped (missing endpoint).
+     * Failures (e.g. self-edge) are caught and logged.
+     */
+    private _addEdgeIfValid;
+}
+//# sourceMappingURL=EdgeEmitter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EdgeEmitter.d.ts","sourceRoot":"","sources":["../../../src/core/graph/EdgeEmitter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAEhE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAE/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAA6B,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAEhG,OAAO,EAEN,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,MAAM,wBAAwB,CAAC;AAEhC,qDAAqD;AACrD,MAAM,WAAW,mBAAmB;IACnC,eAAe,EAAE,WAAW,EAAE,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAC;CAC1C;AAED,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IACjC,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gBAAgB,EAAE,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,qBAAa,WAAW;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IACpC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAY;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,iBAAiB;IAOrC,yEAAyE;IAClE,SAAS,IAAI,OAAO;IAI3B;;;;;;;;;;;;;OAaG;IACI,mBAAmB,CACzB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,uBAAuB,GAC/B,OAAO;IA6BV,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,qBAAqB;IAgB7B,OAAO,CAAC,iBAAiB;IAgBzB,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,uBAAuB;IAsB/B,OAAO,CAAC,iBAAiB;IAczB;;;;OAIG;IACH,OAAO,CAAC,eAAe;CA2CvB"}

package/dist/core/graph/EdgeEmitter.js

@@ -0,0 +1,118 @@
+import { getErrorMessage } from "../../errors.js";
+import { NullLogger } from "../../logger/NullLogger.js";
+import { generateEdgeId } from "../../contracts/ids.js";
+class EdgeEmitter {
+    _edgeStore;
+    _dagEdges;
+    _defaultSessionId;
+    _logger;
+    constructor(config){
+        this._edgeStore = config.edgeStore;
+        this._dagEdges = config.dagEdges ?? true;
+        this._defaultSessionId = config.defaultSessionId;
+        this._logger = config.logger ?? new NullLogger();
+    }
+    isEnabled() {
+        return void 0 !== this._edgeStore && this._dagEdges;
+    }
+    emitEdgesForThought(session, thought, context) {
+        if (!this._edgeStore || !this._dagEdges) return false;
+        if (!thought.id) return false;
+        const sessionId = thought.session_id ?? this._defaultSessionId;
+        const references = context?.resolvedReferences ?? {};
+        const hasRelationalIntent = void 0 !== thought.branch_from_thought && void 0 !== thought.branch_id || (thought.merge_from_thoughts?.length ?? 0) > 0 || void 0 !== thought.verification_target && ('verification' === thought.thought_type || 'critique' === thought.thought_type) || (thought.synthesis_sources?.length ?? 0) > 0 || void 0 !== thought.revises_thought || 'tool_observation' === thought.thought_type && context?.toolInvocationSourceThoughtId !== void 0;
+        const emittedRelational = [
+            this._emitBranchEdge(thought, references, sessionId),
+            this._emitMergeEdges(thought, references, sessionId),
+            this._emitVerificationEdge(thought, references, sessionId),
+            this._emitCritiqueEdge(thought, references, sessionId),
+            this._emitSynthesisEdges(thought, references, sessionId),
+            this._emitRevisionEdge(thought, references, sessionId),
+            this._emitToolInvocationEdge(thought, sessionId, context)
+        ].some((emitted)=>emitted);
+        if (emittedRelational || hasRelationalIntent) return emittedRelational;
+        return this._emitSequenceEdge(session, thought, sessionId);
+    }
+    _emitBranchEdge(thought, references, sessionId) {
+        if (void 0 === thought.branch_from_thought || !thought.branch_id) return false;
+        return this._addEdgeIfValid(references.branchFromThoughtId, thought.id, 'branch', sessionId);
+    }
+    _emitMergeEdges(thought, references, sessionId) {
+        let emitted = false;
+        for (const srcId of references.mergeFromThoughtIds ?? [])emitted = this._addEdgeIfValid(srcId, thought.id, 'merge', sessionId) || emitted;
+        return emitted;
+    }
+    _emitVerificationEdge(thought, references, sessionId) {
+        if (void 0 === thought.verification_target || 'verification' !== thought.thought_type) return false;
+        return this._addEdgeIfValid(thought.id, references.verificationTargetThoughtId, 'verifies', sessionId);
+    }
+    _emitCritiqueEdge(thought, references, sessionId) {
+        if (void 0 === thought.verification_target || 'critique' !== thought.thought_type) return false;
+        return this._addEdgeIfValid(thought.id, references.verificationTargetThoughtId, 'critiques', sessionId);
+    }
+    _emitSynthesisEdges(thought, references, sessionId) {
+        let emitted = false;
+        for (const srcId of references.synthesisSourceThoughtIds ?? [])emitted = this._addEdgeIfValid(srcId, thought.id, 'derives_from', sessionId) || emitted;
+        return emitted;
+    }
+    _emitRevisionEdge(thought, references, sessionId) {
+        if (void 0 === thought.revises_thought) return false;
+        return this._addEdgeIfValid(thought.id, references.revisesThoughtId, 'revises', sessionId);
+    }
+    _emitToolInvocationEdge(thought, sessionId, context) {
+        if ('tool_observation' !== thought.thought_type || context?.toolInvocationSourceThoughtId === void 0) return false;
+        const metadata = void 0 !== thought.tool_name ? {
+            tool_name: thought.tool_name
+        } : void 0;
+        return this._addEdgeIfValid(context.toolInvocationSourceThoughtId, thought.id, 'tool_invocation', sessionId, metadata);
+    }
+    _emitSequenceEdge(session, thought, sessionId) {
+        const history = session.thought_history;
+        if (history.length < 2) return false;
+        const prev = history[history.length - 2];
+        if (!prev?.id) return false;
+        return this._addEdgeIfValid(prev.id, thought.id, 'sequence', sessionId);
+    }
+    _addEdgeIfValid(from, to, kind, sessionId, metadata) {
+        if (!from || !to) {
+            this._logger.debug('Skipping edge: unresolved endpoint', {
+                kind,
+                from: from ?? null,
+                to: to ?? null
+            });
+            return false;
+        }
+        const edge = {
+            id: generateEdgeId(),
+            from: from,
+            to: to,
+            kind,
+            sessionId: sessionId,
+            createdAt: Date.now(),
+            ...void 0 !== metadata ? {
+                metadata
+            } : {}
+        };
+        if (!this._edgeStore) {
+            this._logger.warn('EdgeStore not available; skipping edge', {
+                kind
+            });
+            return false;
+        }
+        const duplicate = this._edgeStore.edgesForSession(sessionId).some((existing)=>existing.kind === kind && existing.from === from && existing.to === to);
+        if (duplicate) return false;
+        try {
+            this._edgeStore.addEdge(edge);
+            return true;
+        } catch (err) {
+            this._logger.info('Failed to add DAG edge', {
+                kind,
+                error: getErrorMessage(err)
+            });
+            return false;
+        }
+    }
+}
+export { EdgeEmitter };
+
+//# sourceMappingURL=EdgeEmitter.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"core/graph/EdgeEmitter.js","sources":["../../../src/core/graph/EdgeEmitter.ts"],"sourcesContent":["/**\n * EdgeEmitter — emits DAG edges for thoughts based on their metadata.\n *\n * Stateless helper extracted from HistoryManager. Holds a reference to an\n * optional `IEdgeStore` and a feature flag (`dagEdges`) gating writes.\n *\n * @module EdgeEmitter\n */\n\nimport type { IEdgeStore } from '../../contracts/interfaces.js';\nimport { getErrorMessage } from '../../errors.js';\nimport type { Logger } from '../../logger/StructuredLogger.js';\nimport { NullLogger } from '../../logger/NullLogger.js';\nimport type { ThoughtData } from '../thought.js';\nimport type { ResolvedThoughtReferences, ThoughtAdmissionContext } from '../IHistoryManager.js';\nimport type { Edge, EdgeKind } from './Edge.js';\nimport {\n\tgenerateEdgeId,\n\ttype BranchId,\n\ttype SessionId,\n\ttype ThoughtId,\n} from '../../contracts/ids.js';\n\n/** Minimal session view needed for edge emission. */\nexport interface EdgeEmissionSession {\n\tthought_history: ThoughtData[];\n\tbranches: Record<BranchId, ThoughtData[]>;\n}\n\n/** Configuration options for EdgeEmitter. */\nexport interface EdgeEmitterConfig {\n\tedgeStore?: IEdgeStore;\n\tdagEdges?: boolean;\n\tdefaultSessionId: SessionId;\n\tlogger?: Logger;\n}\n\n/**\n * Emits DAG edges for thought relationships when an `IEdgeStore` is configured\n * and the `dagEdges` feature flag is enabled. No-ops otherwise.\n */\nexport class EdgeEmitter {\n\tprivate readonly _edgeStore?: IEdgeStore;\n\tprivate readonly _dagEdges: boolean;\n\tprivate readonly _defaultSessionId: SessionId;\n\tprivate readonly _logger: Logger;\n\n\tconstructor(config: EdgeEmitterConfig) {\n\t\tthis._edgeStore = config.edgeStore;\n\t\tthis._dagEdges = config.dagEdges ?? true;\n\t\tthis._defaultSessionId = config.defaultSessionId;\n\t\tthis._logger = config.logger ?? new NullLogger();\n\t}\n\n\t/** Returns true when edge emission is active (store + flag both set). */\n\tpublic isEnabled(): boolean {\n\t\treturn this._edgeStore !== undefined && this._dagEdges;\n\t}\n\n\t/**\n\t * Emits DAG edges for a thought based on its metadata fields.\n\t *\n\t * Edge kinds (in priority order):\n\t * - branch: branch_from_thought + branch_id → parent.id → current.id\n\t * - merge: merge_from_thoughts → source.id → current.id (per source)\n\t * - verifies: verification_target + thought_type=verification → current.id → target.id\n\t * - critiques: verification_target + thought_type=critique → current.id → target.id\n\t * - derives_from: synthesis_sources → source.id → current.id (per source)\n\t * - revises: revises_thought → current.id → target.id\n\t * - tool_invocation: stable admission source id → current.id\n\t * - sequence: default chronological link from previous thought (if none of the above)\n\t * @returns True only when at least one edge was added to the store\n\t */\n\tpublic emitEdgesForThought(\n\t\tsession: EdgeEmissionSession,\n\t\tthought: ThoughtData,\n\t\tcontext?: ThoughtAdmissionContext\n\t): boolean {\n\t\tif (!this._edgeStore || !this._dagEdges) return false;\n\t\tif (!thought.id) return false;\n\n\t\tconst sessionId = thought.session_id ?? this._defaultSessionId;\n\t\tconst references = context?.resolvedReferences ?? {};\n\t\tconst hasRelationalIntent =\n\t\t\t(thought.branch_from_thought !== undefined && thought.branch_id !== undefined) ||\n\t\t\t(thought.merge_from_thoughts?.length ?? 0) > 0 ||\n\t\t\t(thought.verification_target !== undefined &&\n\t\t\t\t(thought.thought_type === 'verification' || thought.thought_type === 'critique')) ||\n\t\t\t(thought.synthesis_sources?.length ?? 0) > 0 ||\n\t\t\tthought.revises_thought !== undefined ||\n\t\t\t(thought.thought_type === 'tool_observation' &&\n\t\t\t\tcontext?.toolInvocationSourceThoughtId !== undefined);\n\t\tconst emittedRelational = [\n\t\t\tthis._emitBranchEdge(thought, references, sessionId),\n\t\t\tthis._emitMergeEdges(thought, references, sessionId),\n\t\t\tthis._emitVerificationEdge(thought, references, sessionId),\n\t\t\tthis._emitCritiqueEdge(thought, references, sessionId),\n\t\t\tthis._emitSynthesisEdges(thought, references, sessionId),\n\t\t\tthis._emitRevisionEdge(thought, references, sessionId),\n\t\t\tthis._emitToolInvocationEdge(thought, sessionId, context),\n\t\t].some((emitted) => emitted);\n\n\t\tif (emittedRelational || hasRelationalIntent) return emittedRelational;\n\t\treturn this._emitSequenceEdge(session, thought, sessionId);\n\t}\n\n\tprivate _emitBranchEdge(\n\t\tthought: ThoughtData,\n\t\treferences: ResolvedThoughtReferences,\n\t\tsessionId: SessionId\n\t): boolean {\n\t\tif (thought.branch_from_thought === undefined || !thought.branch_id) return false;\n\n\t\treturn this._addEdgeIfValid(references.branchFromThoughtId, thought.id, 'branch', sessionId);\n\t}\n\n\tprivate _emitMergeEdges(\n\t\tthought: ThoughtData,\n\t\treferences: ResolvedThoughtReferences,\n\t\tsessionId: SessionId\n\t): boolean {\n\t\tlet emitted = false;\n\t\tfor (const srcId of references.mergeFromThoughtIds ?? []) {\n\t\t\temitted = this._addEdgeIfValid(srcId, thought.id, 'merge', sessionId) || emitted;\n\t\t}\n\t\treturn emitted;\n\t}\n\n\tprivate _emitVerificationEdge(\n\t\tthought: ThoughtData,\n\t\treferences: ResolvedThoughtReferences,\n\t\tsessionId: SessionId\n\t): boolean {\n\t\tif (thought.verification_target === undefined || thought.thought_type !== 'verification')\n\t\t\treturn false;\n\n\t\treturn this._addEdgeIfValid(\n\t\t\tthought.id,\n\t\t\treferences.verificationTargetThoughtId,\n\t\t\t'verifies',\n\t\t\tsessionId\n\t\t);\n\t}\n\n\tprivate _emitCritiqueEdge(\n\t\tthought: ThoughtData,\n\t\treferences: ResolvedThoughtReferences,\n\t\tsessionId: SessionId\n\t): boolean {\n\t\tif (thought.verification_target === undefined || thought.thought_type !== 'critique')\n\t\t\treturn false;\n\n\t\treturn this._addEdgeIfValid(\n\t\t\tthought.id,\n\t\t\treferences.verificationTargetThoughtId,\n\t\t\t'critiques',\n\t\t\tsessionId\n\t\t);\n\t}\n\n\tprivate _emitSynthesisEdges(\n\t\tthought: ThoughtData,\n\t\treferences: ResolvedThoughtReferences,\n\t\tsessionId: SessionId\n\t): boolean {\n\t\tlet emitted = false;\n\t\tfor (const srcId of references.synthesisSourceThoughtIds ?? []) {\n\t\t\temitted = this._addEdgeIfValid(srcId, thought.id, 'derives_from', sessionId) || emitted;\n\t\t}\n\t\treturn emitted;\n\t}\n\n\tprivate _emitRevisionEdge(\n\t\tthought: ThoughtData,\n\t\treferences: ResolvedThoughtReferences,\n\t\tsessionId: SessionId\n\t): boolean {\n\t\tif (thought.revises_thought === undefined) return false;\n\n\t\treturn this._addEdgeIfValid(thought.id, references.revisesThoughtId, 'revises', sessionId);\n\t}\n\n\tprivate _emitToolInvocationEdge(\n\t\tthought: ThoughtData,\n\t\tsessionId: SessionId,\n\t\tcontext?: ThoughtAdmissionContext\n\t): boolean {\n\t\tif (\n\t\t\tthought.thought_type !== 'tool_observation' ||\n\t\t\tcontext?.toolInvocationSourceThoughtId === undefined\n\t\t) {\n\t\t\treturn false;\n\t\t}\n\n\t\tconst metadata = thought.tool_name !== undefined ? { tool_name: thought.tool_name } : undefined;\n\t\treturn this._addEdgeIfValid(\n\t\t\tcontext.toolInvocationSourceThoughtId,\n\t\t\tthought.id,\n\t\t\t'tool_invocation',\n\t\t\tsessionId,\n\t\t\tmetadata\n\t\t);\n\t}\n\n\tprivate _emitSequenceEdge(\n\t\tsession: EdgeEmissionSession,\n\t\tthought: ThoughtData,\n\t\tsessionId: SessionId\n\t): boolean {\n\t\tconst history = session.thought_history;\n\t\tif (history.length < 2) return false;\n\n\t\tconst prev = history[history.length - 2];\n\t\tif (!prev?.id) return false;\n\n\t\treturn this._addEdgeIfValid(prev.id, thought.id, 'sequence', sessionId);\n\t}\n\n\t/**\n\t * Adds an edge to the edge store if both endpoints are non-empty strings.\n\t * Returns true if added, false if skipped (missing endpoint).\n\t * Failures (e.g. self-edge) are caught and logged.\n\t */\n\tprivate _addEdgeIfValid(\n\t\tfrom: ThoughtId | undefined,\n\t\tto: ThoughtId | undefined,\n\t\tkind: EdgeKind,\n\t\tsessionId: SessionId,\n\t\tmetadata?: Record<string, unknown>\n\t): boolean {\n\t\tif (!from || !to) {\n\t\t\tthis._logger.debug('Skipping edge: unresolved endpoint', {\n\t\t\t\tkind,\n\t\t\t\tfrom: from ?? null,\n\t\t\t\tto: to ?? null,\n\t\t\t});\n\t\t\treturn false;\n\t\t}\n\t\tconst edge: Edge = {\n\t\t\tid: generateEdgeId(),\n\t\t\tfrom: from as Edge['from'],\n\t\t\tto: to as Edge['to'],\n\t\t\tkind,\n\t\t\tsessionId: sessionId as Edge['sessionId'],\n\t\t\tcreatedAt: Date.now(),\n\t\t\t...(metadata !== undefined ? { metadata } : {}),\n\t\t};\n\t\tif (!this._edgeStore) {\n\t\t\tthis._logger.warn('EdgeStore not available; skipping edge', { kind });\n\t\t\treturn false;\n\t\t}\n\t\tconst duplicate = this._edgeStore\n\t\t\t.edgesForSession(sessionId)\n\t\t\t.some((existing) => existing.kind === kind && existing.from === from && existing.to === to);\n\t\tif (duplicate) return false;\n\t\ttry {\n\t\t\tthis._edgeStore.addEdge(edge);\n\t\t\treturn true;\n\t\t} catch (err) {\n\t\t\tthis._logger.info('Failed to add DAG edge', {\n\t\t\t\tkind,\n\t\t\t\terror: getErrorMessage(err),\n\t\t\t});\n\t\t\treturn false;\n\t\t}\n\t}\n}\n"],"names":["EdgeEmitter","config","NullLogger","undefined","session","thought","context","sessionId","references","hasRelationalIntent","emittedRelational","emitted","srcId","metadata","history","prev","from","to","kind","edge","generateEdgeId","Date","duplicate","existing","err","getErrorMessage"],"mappings":"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"}

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

@@ -0,0 +1,116 @@
+/**
+ * EdgeStore — in-memory store for the thought DAG with per-session isolation.
+ *
+ * Stores directed edges between thoughts, keyed by their `id` field. Each
+ * session maintains independent adjacency maps (outgoing/incoming) so that
+ * edges in one session are invisible to another.
+ *
+ * The store is intentionally small and synchronous; it does not persist
+ * anything and does not perform graph traversal. Strategy code consumes
+ * `outgoing()` / `incoming()` to navigate the DAG.
+ *
+ * @module core/graph/EdgeStore
+ */
+import type { IEdgeStore } from '../../contracts/interfaces.js';
+import { type SessionId, type ThoughtId } from '../../contracts/ids.js';
+import type { Edge } from './Edge.js';
+/**
+ * In-memory implementation of {@link IEdgeStore}.
+ *
+ * Edges are stored per-session in three indexes:
+ * - `byId`: edge id → edge (for `getEdge`)
+ * - `outgoing`: from-id → edges sorted by `createdAt` ascending
+ * - `incoming`: to-id → edges sorted by `createdAt` ascending
+ *
+ * @example
+ * ```typescript
+ * const store = new EdgeStore();
+ * store.addEdge({
+ *   id: generateUlid(),
+ *   from: 'thought-1',
+ *   to: 'thought-2',
+ *   kind: 'sequence',
+ *   sessionId: 's1',
+ *   createdAt: Date.now(),
+ * });
+ * const out = store.outgoing('s1', 'thought-1');
+ * ```
+ */
+export declare class EdgeStore implements IEdgeStore {
+    private readonly _sessions;
+    /**
+     * Add a directed edge to the store.
+     *
+     * Self-edges (`from === to`) are rejected. Identical edges
+     * (same `from`, `to`, `kind`, `sessionId`) are silently deduped — the
+     * existing edge is preserved and its id is not replaced.
+     *
+     * @param edge - The edge to add
+     * @throws {InvalidEdgeError} When `edge.from === edge.to`
+     */
+    addEdge(edge: Edge): void;
+    /**
+     * Retrieve a specific edge by its id, searching across all sessions.
+     *
+     * @param id - The edge's unique identifier
+     * @returns The edge, or `undefined` if not found
+     */
+    getEdge(id: string): Edge | undefined;
+    /**
+     * Get all outgoing edges from a thought, sorted by `createdAt` ascending.
+     *
+     * @param sessionId - Session to query within
+     * @param from - Source thought id
+     * @returns Array of outgoing edges (empty if none / unknown session)
+     */
+    outgoing(sessionId: SessionId, from: string): readonly Edge[];
+    /**
+     * Get all incoming edges to a thought, sorted by `createdAt` ascending.
+     *
+     * @param sessionId - Session to query within
+     * @param to - Target thought id
+     * @returns Array of incoming edges (empty if none / unknown session)
+     */
+    incoming(sessionId: SessionId, to: string): readonly Edge[];
+    /**
+     * Get all edges in a session, sorted by `createdAt` ascending.
+     *
+     * @param sessionId - Session to query
+     * @returns All edges in the session (empty if unknown session)
+     */
+    edgesForSession(sessionId: SessionId): readonly Edge[];
+    /**
+     * Remove edges whose source or target is absent from the retained thought set.
+     * Rebuilds all indexes before replacing the session container atomically.
+     *
+     * @param sessionId - Session whose edges should be pruned
+     * @param retainedThoughtIds - Union of retained thought ids for the session
+     * @param retainedBranchThoughtIds - Retained targets for branch edges
+     * @returns The exact number of removed edges
+     */
+    pruneSession(sessionId: SessionId, retainedThoughtIds: ReadonlySet<ThoughtId>, retainedBranchThoughtIds?: ReadonlySet<ThoughtId>): number;
+    /**
+     * Clear all edges for a specific session. Other sessions are unaffected.
+     *
+     * @param sessionId - Session to clear
+     */
+    clearSession(sessionId: SessionId): void;
+    clearAll(): void;
+    /**
+     * Count edges, optionally scoped to one session.
+     *
+     * @param sessionId - If provided, count only that session's edges
+     * @returns Total edge count
+     */
+    size(sessionId?: SessionId): number;
+    /**
+     * Get an existing session container or create a new empty one.
+     */
+    private _getOrCreateSession;
+    /**
+     * Insert an edge into an adjacency bucket, maintaining ascending
+     * `createdAt` order. Uses binary search to keep insertion at O(log n).
+     */
+    private _insertSorted;
+}
+//# sourceMappingURL=EdgeStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EdgeStore.d.ts","sourceRoot":"","sources":["../../../src/core/graph/EdgeStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAIN,KAAK,SAAS,EACd,KAAK,SAAS,EACd,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAWtC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,SAAU,YAAW,UAAU;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2C;IAErE;;;;;;;;;OASG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAwBzB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAUrC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,IAAI,EAAE;IAQ7D;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,IAAI,EAAE;IAQ3D;;;;;OAKG;IACH,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,IAAI,EAAE;IAQtD;;;;;;;;OAQG;IACH,YAAY,CACX,SAAS,EAAE,SAAS,EACpB,kBAAkB,EAAE,WAAW,CAAC,SAAS,CAAC,EAC1C,wBAAwB,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,GAC/C,MAAM;IAkCT;;;;OAIG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAIxC,QAAQ,IAAI,IAAI;IAIhB;;;;;OAKG;IACH,IAAI,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,MAAM;IAYnC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAa3B;;;OAGG;IACH,OAAO,CAAC,aAAa;CAoBrB"}

package/dist/core/graph/EdgeStore.js

@@ -0,0 +1,107 @@
+import { asEdgeId, asThoughtId } from "../../contracts/ids.js";
+import { InvalidEdgeError } from "../../errors.js";
+class EdgeStore {
+    _sessions = new Map();
+    addEdge(edge) {
+        if (edge.from === edge.to) throw new InvalidEdgeError(`Self-edge not allowed: from and to are the same (${edge.from})`);
+        const session = this._getOrCreateSession(edge.sessionId);
+        const existing = session.outgoing.get(edge.from);
+        if (existing) {
+            for (const candidate of existing)if (candidate.to === edge.to && candidate.kind === edge.kind) return;
+        }
+        session.byId.set(edge.id, edge);
+        this._insertSorted(session.outgoing, edge.from, edge);
+        this._insertSorted(session.incoming, edge.to, edge);
+    }
+    getEdge(id) {
+        for (const session of this._sessions.values()){
+            const edge = session.byId.get(asEdgeId(id));
+            if (edge) return edge;
+        }
+    }
+    outgoing(sessionId, from) {
+        const session = this._sessions.get(sessionId);
+        if (!session) return [];
+        return session.outgoing.get(asThoughtId(from)) ?? [];
+    }
+    incoming(sessionId, to) {
+        const session = this._sessions.get(sessionId);
+        if (!session) return [];
+        return session.incoming.get(asThoughtId(to)) ?? [];
+    }
+    edgesForSession(sessionId) {
+        const session = this._sessions.get(sessionId);
+        if (!session) return [];
+        return Array.from(session.byId.values()).sort((a, b)=>a.createdAt - b.createdAt);
+    }
+    pruneSession(sessionId, retainedThoughtIds, retainedBranchThoughtIds) {
+        const session = this._sessions.get(sessionId);
+        if (!session) return 0;
+        const retainedEdges = Array.from(session.byId.values()).filter((edge)=>{
+            if (!retainedThoughtIds.has(edge.from) || !retainedThoughtIds.has(edge.to)) return false;
+            return 'branch' !== edge.kind || void 0 === retainedBranchThoughtIds || retainedBranchThoughtIds.has(edge.to);
+        });
+        const removed = session.byId.size - retainedEdges.length;
+        if (0 === retainedEdges.length) {
+            this._sessions.delete(sessionId);
+            return removed;
+        }
+        const rebuilt = {
+            byId: new Map(),
+            outgoing: new Map(),
+            incoming: new Map()
+        };
+        for (const edge of retainedEdges){
+            rebuilt.byId.set(edge.id, edge);
+            this._insertSorted(rebuilt.outgoing, edge.from, edge);
+            this._insertSorted(rebuilt.incoming, edge.to, edge);
+        }
+        this._sessions.set(sessionId, rebuilt);
+        return removed;
+    }
+    clearSession(sessionId) {
+        this._sessions.delete(sessionId);
+    }
+    clearAll() {
+        this._sessions.clear();
+    }
+    size(sessionId) {
+        if (void 0 !== sessionId) {
+            const session = this._sessions.get(sessionId);
+            return session ? session.byId.size : 0;
+        }
+        let total = 0;
+        for (const session of this._sessions.values())total += session.byId.size;
+        return total;
+    }
+    _getOrCreateSession(sessionId) {
+        let session = this._sessions.get(sessionId);
+        if (!session) {
+            session = {
+                byId: new Map(),
+                outgoing: new Map(),
+                incoming: new Map()
+            };
+            this._sessions.set(sessionId, session);
+        }
+        return session;
+    }
+    _insertSorted(index, key, edge) {
+        let bucket = index.get(key);
+        if (!bucket) {
+            bucket = [];
+            index.set(key, bucket);
+        }
+        let lo = 0;
+        let hi = bucket.length;
+        while(lo < hi){
+            const mid = lo + hi >>> 1;
+            if (bucket[mid].createdAt <= edge.createdAt) lo = mid + 1;
+            else hi = mid;
+        }
+        bucket.splice(lo, 0, edge);
+    }
+}
+export { EdgeStore };
+
+//# sourceMappingURL=EdgeStore.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"core/graph/EdgeStore.js","sources":["../../../src/core/graph/EdgeStore.ts"],"sourcesContent":["/**\n * EdgeStore — in-memory store for the thought DAG with per-session isolation.\n *\n * Stores directed edges between thoughts, keyed by their `id` field. Each\n * session maintains independent adjacency maps (outgoing/incoming) so that\n * edges in one session are invisible to another.\n *\n * The store is intentionally small and synchronous; it does not persist\n * anything and does not perform graph traversal. Strategy code consumes\n * `outgoing()` / `incoming()` to navigate the DAG.\n *\n * @module core/graph/EdgeStore\n */\n\nimport type { IEdgeStore } from '../../contracts/interfaces.js';\nimport {\n\tasEdgeId,\n\tasThoughtId,\n\ttype EdgeId,\n\ttype SessionId,\n\ttype ThoughtId,\n} from '../../contracts/ids.js';\nimport { InvalidEdgeError } from '../../errors.js';\nimport type { Edge } from './Edge.js';\n\n/**\n * Per-session adjacency container.\n */\ninterface SessionEdges {\n\treadonly byId: Map<EdgeId, Edge>;\n\treadonly outgoing: Map<ThoughtId, Edge[]>;\n\treadonly incoming: Map<ThoughtId, Edge[]>;\n}\n\n/**\n * In-memory implementation of {@link IEdgeStore}.\n *\n * Edges are stored per-session in three indexes:\n * - `byId`: edge id → edge (for `getEdge`)\n * - `outgoing`: from-id → edges sorted by `createdAt` ascending\n * - `incoming`: to-id → edges sorted by `createdAt` ascending\n *\n * @example\n * ```typescript\n * const store = new EdgeStore();\n * store.addEdge({\n *   id: generateUlid(),\n *   from: 'thought-1',\n *   to: 'thought-2',\n *   kind: 'sequence',\n *   sessionId: 's1',\n *   createdAt: Date.now(),\n * });\n * const out = store.outgoing('s1', 'thought-1');\n * ```\n */\nexport class EdgeStore implements IEdgeStore {\n\tprivate readonly _sessions: Map<SessionId, SessionEdges> = new Map();\n\n\t/**\n\t * Add a directed edge to the store.\n\t *\n\t * Self-edges (`from === to`) are rejected. Identical edges\n\t * (same `from`, `to`, `kind`, `sessionId`) are silently deduped — the\n\t * existing edge is preserved and its id is not replaced.\n\t *\n\t * @param edge - The edge to add\n\t * @throws {InvalidEdgeError} When `edge.from === edge.to`\n\t */\n\taddEdge(edge: Edge): void {\n\t\tif (edge.from === edge.to) {\n\t\t\tthrow new InvalidEdgeError(`Self-edge not allowed: from and to are the same (${edge.from})`);\n\t\t}\n\n\t\tconst session = this._getOrCreateSession(edge.sessionId);\n\n\t\t// Dedupe: if an edge with the same (from, to, kind) already exists in this\n\t\t// session, silently no-op. Searching the smaller `outgoing` bucket avoids\n\t\t// scanning every edge in the session.\n\t\tconst existing = session.outgoing.get(edge.from);\n\t\tif (existing) {\n\t\t\tfor (const candidate of existing) {\n\t\t\t\tif (candidate.to === edge.to && candidate.kind === edge.kind) {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tsession.byId.set(edge.id, edge);\n\t\tthis._insertSorted(session.outgoing, edge.from, edge);\n\t\tthis._insertSorted(session.incoming, edge.to, edge);\n\t}\n\n\t/**\n\t * Retrieve a specific edge by its id, searching across all sessions.\n\t *\n\t * @param id - The edge's unique identifier\n\t * @returns The edge, or `undefined` if not found\n\t */\n\tgetEdge(id: string): Edge | undefined {\n\t\tfor (const session of this._sessions.values()) {\n\t\t\tconst edge = session.byId.get(asEdgeId(id));\n\t\t\tif (edge) {\n\t\t\t\treturn edge;\n\t\t\t}\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Get all outgoing edges from a thought, sorted by `createdAt` ascending.\n\t *\n\t * @param sessionId - Session to query within\n\t * @param from - Source thought id\n\t * @returns Array of outgoing edges (empty if none / unknown session)\n\t */\n\toutgoing(sessionId: SessionId, from: string): readonly Edge[] {\n\t\tconst session = this._sessions.get(sessionId);\n\t\tif (!session) {\n\t\t\treturn [];\n\t\t}\n\t\treturn session.outgoing.get(asThoughtId(from)) ?? [];\n\t}\n\n\t/**\n\t * Get all incoming edges to a thought, sorted by `createdAt` ascending.\n\t *\n\t * @param sessionId - Session to query within\n\t * @param to - Target thought id\n\t * @returns Array of incoming edges (empty if none / unknown session)\n\t */\n\tincoming(sessionId: SessionId, to: string): readonly Edge[] {\n\t\tconst session = this._sessions.get(sessionId);\n\t\tif (!session) {\n\t\t\treturn [];\n\t\t}\n\t\treturn session.incoming.get(asThoughtId(to)) ?? [];\n\t}\n\n\t/**\n\t * Get all edges in a session, sorted by `createdAt` ascending.\n\t *\n\t * @param sessionId - Session to query\n\t * @returns All edges in the session (empty if unknown session)\n\t */\n\tedgesForSession(sessionId: SessionId): readonly Edge[] {\n\t\tconst session = this._sessions.get(sessionId);\n\t\tif (!session) {\n\t\t\treturn [];\n\t\t}\n\t\treturn Array.from(session.byId.values()).sort((a, b) => a.createdAt - b.createdAt);\n\t}\n\n\t/**\n\t * Remove edges whose source or target is absent from the retained thought set.\n\t * Rebuilds all indexes before replacing the session container atomically.\n\t *\n\t * @param sessionId - Session whose edges should be pruned\n\t * @param retainedThoughtIds - Union of retained thought ids for the session\n\t * @param retainedBranchThoughtIds - Retained targets for branch edges\n\t * @returns The exact number of removed edges\n\t */\n\tpruneSession(\n\t\tsessionId: SessionId,\n\t\tretainedThoughtIds: ReadonlySet<ThoughtId>,\n\t\tretainedBranchThoughtIds?: ReadonlySet<ThoughtId>\n\t): number {\n\t\tconst session = this._sessions.get(sessionId);\n\t\tif (!session) {\n\t\t\treturn 0;\n\t\t}\n\n\t\tconst retainedEdges = Array.from(session.byId.values()).filter((edge) => {\n\t\t\tif (!retainedThoughtIds.has(edge.from) || !retainedThoughtIds.has(edge.to)) return false;\n\t\t\treturn (\n\t\t\t\tedge.kind !== 'branch' ||\n\t\t\t\tretainedBranchThoughtIds === undefined ||\n\t\t\t\tretainedBranchThoughtIds.has(edge.to)\n\t\t\t);\n\t\t});\n\t\tconst removed = session.byId.size - retainedEdges.length;\n\t\tif (retainedEdges.length === 0) {\n\t\t\tthis._sessions.delete(sessionId);\n\t\t\treturn removed;\n\t\t}\n\n\t\tconst rebuilt: SessionEdges = {\n\t\t\tbyId: new Map<EdgeId, Edge>(),\n\t\t\toutgoing: new Map<ThoughtId, Edge[]>(),\n\t\t\tincoming: new Map<ThoughtId, Edge[]>(),\n\t\t};\n\t\tfor (const edge of retainedEdges) {\n\t\t\trebuilt.byId.set(edge.id, edge);\n\t\t\tthis._insertSorted(rebuilt.outgoing, edge.from, edge);\n\t\t\tthis._insertSorted(rebuilt.incoming, edge.to, edge);\n\t\t}\n\t\tthis._sessions.set(sessionId, rebuilt);\n\t\treturn removed;\n\t}\n\n\t/**\n\t * Clear all edges for a specific session. Other sessions are unaffected.\n\t *\n\t * @param sessionId - Session to clear\n\t */\n\tclearSession(sessionId: SessionId): void {\n\t\tthis._sessions.delete(sessionId);\n\t}\n\n\tclearAll(): void {\n\t\tthis._sessions.clear();\n\t}\n\n\t/**\n\t * Count edges, optionally scoped to one session.\n\t *\n\t * @param sessionId - If provided, count only that session's edges\n\t * @returns Total edge count\n\t */\n\tsize(sessionId?: SessionId): number {\n\t\tif (sessionId !== undefined) {\n\t\t\tconst session = this._sessions.get(sessionId);\n\t\t\treturn session ? session.byId.size : 0;\n\t\t}\n\t\tlet total = 0;\n\t\tfor (const session of this._sessions.values()) {\n\t\t\ttotal += session.byId.size;\n\t\t}\n\t\treturn total;\n\t}\n\n\t/**\n\t * Get an existing session container or create a new empty one.\n\t */\n\tprivate _getOrCreateSession(sessionId: SessionId): SessionEdges {\n\t\tlet session = this._sessions.get(sessionId);\n\t\tif (!session) {\n\t\t\tsession = {\n\t\t\t\tbyId: new Map<EdgeId, Edge>(),\n\t\t\t\toutgoing: new Map<ThoughtId, Edge[]>(),\n\t\t\t\tincoming: new Map<ThoughtId, Edge[]>(),\n\t\t\t};\n\t\t\tthis._sessions.set(sessionId, session);\n\t\t}\n\t\treturn session;\n\t}\n\n\t/**\n\t * Insert an edge into an adjacency bucket, maintaining ascending\n\t * `createdAt` order. Uses binary search to keep insertion at O(log n).\n\t */\n\tprivate _insertSorted<K>(index: Map<K, Edge[]>, key: K, edge: Edge): void {\n\t\tlet bucket = index.get(key);\n\t\tif (!bucket) {\n\t\t\tbucket = [];\n\t\t\tindex.set(key, bucket);\n\t\t}\n\n\t\t// Binary search for insertion index.\n\t\tlet lo = 0;\n\t\tlet hi = bucket.length;\n\t\twhile (lo < hi) {\n\t\t\tconst mid = (lo + hi) >>> 1;\n\t\t\tif (bucket[mid]!.createdAt <= edge.createdAt) {\n\t\t\t\tlo = mid + 1;\n\t\t\t} else {\n\t\t\t\thi = mid;\n\t\t\t}\n\t\t}\n\t\tbucket.splice(lo, 0, edge);\n\t}\n}\n"],"names":["EdgeStore","Map","edge","InvalidEdgeError","session","existing","candidate","id","asEdgeId","sessionId","from","asThoughtId","to","Array","a","b","retainedThoughtIds","retainedBranchThoughtIds","retainedEdges","undefined","removed","rebuilt","total","index","key","bucket","lo","hi","mid"],"mappings":"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"}