@iworkforces/tracelattice 2.0.3

package/dist/core/ThoughtReferenceIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/ThoughtReferenceIndex.js","sources":["../../src/core/ThoughtReferenceIndex.ts"],"sourcesContent":["import type { SessionId, ThoughtId } from '../contracts/ids.js';\nimport type { ThoughtData } from './thought.js';\n\nexport type ThoughtReferenceResolution =\n\t| { readonly kind: 'missing' }\n\t| { readonly kind: 'unique'; readonly thoughtId: ThoughtId }\n\t| { readonly kind: 'ambiguous'; readonly thoughtIds: readonly ThoughtId[] };\n\nconst MISSING: ThoughtReferenceResolution = Object.freeze({ kind: 'missing' });\n\n/** Ref-counted stable-ID lookup for retained thoughts in each session. */\nexport class ThoughtReferenceIndex {\n\tprivate readonly _sessions = new Map<SessionId, Map<number, Map<ThoughtId, number>>>();\n\n\tpublic add(sessionId: SessionId, thought: ThoughtData): void {\n\t\tif (thought.id === undefined) return;\n\t\tlet session = this._sessions.get(sessionId);\n\t\tif (session === undefined) {\n\t\t\tsession = new Map();\n\t\t\tthis._sessions.set(sessionId, session);\n\t\t}\n\t\tthis._addToSession(session, thought);\n\t}\n\n\tpublic remove(sessionId: SessionId, thought: ThoughtData): void {\n\t\tif (thought.id === undefined) return;\n\t\tconst session = this._sessions.get(sessionId);\n\t\tconst bucket = session?.get(thought.thought_number);\n\t\tconst count = bucket?.get(thought.id);\n\t\tif (session === undefined || bucket === undefined || count === undefined) return;\n\t\tif (count > 1) {\n\t\t\tbucket.set(thought.id, count - 1);\n\t\t} else {\n\t\t\tbucket.delete(thought.id);\n\t\t}\n\t\tif (bucket.size === 0) session.delete(thought.thought_number);\n\t\tif (session.size === 0) this._sessions.delete(sessionId);\n\t}\n\n\tpublic resolve(sessionId: SessionId, thoughtNumber: number): ThoughtReferenceResolution {\n\t\tconst bucket = this._sessions.get(sessionId)?.get(thoughtNumber);\n\t\tif (bucket === undefined || bucket.size === 0) return MISSING;\n\t\tif (bucket.size === 1) {\n\t\t\tconst thoughtId = bucket.keys().next().value;\n\t\t\treturn thoughtId === undefined ? MISSING : { kind: 'unique', thoughtId };\n\t\t}\n\t\tconst thoughtIds = Object.freeze(Array.from(bucket.keys()).sort());\n\t\treturn Object.freeze({ kind: 'ambiguous', thoughtIds });\n\t}\n\n\tpublic replaceSession(sessionId: SessionId, thoughts: Iterable<ThoughtData>): void {\n\t\tconst replacement = new Map<number, Map<ThoughtId, number>>();\n\t\tfor (const thought of thoughts) this._addToSession(replacement, thought);\n\t\tif (replacement.size === 0) {\n\t\t\tthis._sessions.delete(sessionId);\n\t\t} else {\n\t\t\tthis._sessions.set(sessionId, replacement);\n\t\t}\n\t}\n\n\tpublic clearSession(sessionId: SessionId): void {\n\t\tthis._sessions.delete(sessionId);\n\t}\n\n\tpublic clearAll(): void {\n\t\tthis._sessions.clear();\n\t}\n\n\tprivate _addToSession(session: Map<number, Map<ThoughtId, number>>, thought: ThoughtData): void {\n\t\tif (thought.id === undefined) return;\n\t\tlet bucket = session.get(thought.thought_number);\n\t\tif (bucket === undefined) {\n\t\t\tbucket = new Map();\n\t\t\tsession.set(thought.thought_number, bucket);\n\t\t}\n\t\tbucket.set(thought.id, (bucket.get(thought.id) ?? 0) + 1);\n\t}\n}\n"],"names":["MISSING","Object","ThoughtReferenceIndex","Map","sessionId","thought","undefined","session","bucket","count","thoughtNumber","thoughtId","thoughtIds","Array","thoughts","replacement"],"mappings":"AAQA,MAAMA,UAAsCC,OAAO,MAAM,CAAC;IAAE,MAAM;AAAU;AAGrE,MAAMC;IACK,YAAY,IAAIC,MAAsD;IAEhF,IAAIC,SAAoB,EAAEC,OAAoB,EAAQ;QAC5D,IAAIA,AAAeC,WAAfD,QAAQ,EAAE,EAAgB;QAC9B,IAAIE,UAAU,IAAI,CAAC,SAAS,CAAC,GAAG,CAACH;QACjC,IAAIG,AAAYD,WAAZC,SAAuB;YAC1BA,UAAU,IAAIJ;YACd,IAAI,CAAC,SAAS,CAAC,GAAG,CAACC,WAAWG;QAC/B;QACA,IAAI,CAAC,aAAa,CAACA,SAASF;IAC7B;IAEO,OAAOD,SAAoB,EAAEC,OAAoB,EAAQ;QAC/D,IAAIA,AAAeC,WAAfD,QAAQ,EAAE,EAAgB;QAC9B,MAAME,UAAU,IAAI,CAAC,SAAS,CAAC,GAAG,CAACH;QACnC,MAAMI,SAASD,SAAS,IAAIF,QAAQ,cAAc;QAClD,MAAMI,QAAQD,QAAQ,IAAIH,QAAQ,EAAE;QACpC,IAAIE,AAAYD,WAAZC,WAAyBC,AAAWF,WAAXE,UAAwBC,AAAUH,WAAVG,OAAqB;QAC1E,IAAIA,QAAQ,GACXD,OAAO,GAAG,CAACH,QAAQ,EAAE,EAAEI,QAAQ;aAE/BD,OAAO,MAAM,CAACH,QAAQ,EAAE;QAEzB,IAAIG,AAAgB,MAAhBA,OAAO,IAAI,EAAQD,QAAQ,MAAM,CAACF,QAAQ,cAAc;QAC5D,IAAIE,AAAiB,MAAjBA,QAAQ,IAAI,EAAQ,IAAI,CAAC,SAAS,CAAC,MAAM,CAACH;IAC/C;IAEO,QAAQA,SAAoB,EAAEM,aAAqB,EAA8B;QACvF,MAAMF,SAAS,IAAI,CAAC,SAAS,CAAC,GAAG,CAACJ,YAAY,IAAIM;QAClD,IAAIF,AAAWF,WAAXE,UAAwBA,AAAgB,MAAhBA,OAAO,IAAI,EAAQ,OAAOR;QACtD,IAAIQ,AAAgB,MAAhBA,OAAO,IAAI,EAAQ;YACtB,MAAMG,YAAYH,OAAO,IAAI,GAAG,IAAI,GAAG,KAAK;YAC5C,OAAOG,AAAcL,WAAdK,YAA0BX,UAAU;gBAAE,MAAM;gBAAUW;YAAU;QACxE;QACA,MAAMC,aAAaX,OAAO,MAAM,CAACY,MAAM,IAAI,CAACL,OAAO,IAAI,IAAI,IAAI;QAC/D,OAAOP,OAAO,MAAM,CAAC;YAAE,MAAM;YAAaW;QAAW;IACtD;IAEO,eAAeR,SAAoB,EAAEU,QAA+B,EAAQ;QAClF,MAAMC,cAAc,IAAIZ;QACxB,KAAK,MAAME,WAAWS,SAAU,IAAI,CAAC,aAAa,CAACC,aAAaV;QAChE,IAAIU,AAAqB,MAArBA,YAAY,IAAI,EACnB,IAAI,CAAC,SAAS,CAAC,MAAM,CAACX;aAEtB,IAAI,CAAC,SAAS,CAAC,GAAG,CAACA,WAAWW;IAEhC;IAEO,aAAaX,SAAoB,EAAQ;QAC/C,IAAI,CAAC,SAAS,CAAC,MAAM,CAACA;IACvB;IAEO,WAAiB;QACvB,IAAI,CAAC,SAAS,CAAC,KAAK;IACrB;IAEQ,cAAcG,OAA4C,EAAEF,OAAoB,EAAQ;QAC/F,IAAIA,AAAeC,WAAfD,QAAQ,EAAE,EAAgB;QAC9B,IAAIG,SAASD,QAAQ,GAAG,CAACF,QAAQ,cAAc;QAC/C,IAAIG,AAAWF,WAAXE,QAAsB;YACzBA,SAAS,IAAIL;YACbI,QAAQ,GAAG,CAACF,QAAQ,cAAc,EAAEG;QACrC;QACAA,OAAO,GAAG,CAACH,QAAQ,EAAE,EAAGG,AAAAA,CAAAA,OAAO,GAAG,CAACH,QAAQ,EAAE,KAAK,KAAK;IACxD;AACD"}

package/dist/core/VerificationOutcomeAdmission.d.ts

@@ -0,0 +1,15 @@
+import type { SessionId } from '../contracts/ids.js';
+import type { IOutcomeRecorder, VerificationOutcome } from '../contracts/interfaces.js';
+import type { HistorySessionSnapshot, ResolvedThoughtReferences } from './IHistoryManager.js';
+import type { ThoughtData } from './thought.js';
+interface VerificationOutcomeAdmissionContext {
+    readonly input: ThoughtData;
+    readonly snapshot: HistorySessionSnapshot;
+    readonly resolvedReferences: ResolvedThoughtReferences;
+    readonly sessionId: SessionId;
+    readonly recorder?: IOutcomeRecorder;
+}
+/** Builds one immutable calibration sample from the retained pre-admission target. */
+export declare function prepareVerificationOutcome(context: VerificationOutcomeAdmissionContext): Omit<VerificationOutcome, 'recordedAt'> | undefined;
+export {};
+//# sourceMappingURL=VerificationOutcomeAdmission.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VerificationOutcomeAdmission.d.ts","sourceRoot":"","sources":["../../src/core/VerificationOutcomeAdmission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAExF,OAAO,KAAK,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAC9F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,UAAU,mCAAmC;IAC5C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,EAAE,yBAAyB,CAAC;IACvD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED,sFAAsF;AACtF,wBAAgB,0BAA0B,CACzC,OAAO,EAAE,mCAAmC,GAC1C,IAAI,CAAC,mBAAmB,EAAE,YAAY,CAAC,GAAG,SAAS,CA6BrD"}

package/dist/core/VerificationOutcomeAdmission.js

@@ -0,0 +1,28 @@
+import { ValidationError } from "../errors.js";
+function prepareVerificationOutcome(context) {
+    const { input, resolvedReferences, sessionId, snapshot, recorder } = context;
+    if ('verification' !== input.thought_type || void 0 === input.verification_result) return;
+    const thoughtId = resolvedReferences.verificationTargetThoughtId;
+    const thoughtNumber = input.verification_target;
+    if (void 0 === thoughtId || void 0 === thoughtNumber) throw new ValidationError('verification_result', 'requires a retained verification_target');
+    const target = findTarget(snapshot, thoughtId, thoughtNumber);
+    if (void 0 === target) throw new ValidationError('verification_result', 'verification_target is no longer retained');
+    if (true === target.retracted) throw new ValidationError('verification_result', 'verification_target must not be retracted');
+    if (void 0 === target.confidence) throw new ValidationError('verification_result', 'verification_target must have confidence');
+    recorder?.assertCanRecord(sessionId, thoughtId);
+    return Object.freeze({
+        thoughtId,
+        thoughtNumber: target.thought_number,
+        sessionId,
+        predicted: target.confidence,
+        actual: input.verification_result,
+        type: target.thought_type ?? 'regular'
+    });
+}
+function findTarget(snapshot, thoughtId, thoughtNumber) {
+    for (const thought of snapshot.history)if (thought.id === thoughtId && thought.thought_number === thoughtNumber) return thought;
+    for (const branch of Object.values(snapshot.branches))for (const thought of branch)if (thought.id === thoughtId && thought.thought_number === thoughtNumber) return thought;
+}
+export { prepareVerificationOutcome };
+
+//# sourceMappingURL=VerificationOutcomeAdmission.js.map

package/dist/core/VerificationOutcomeAdmission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/VerificationOutcomeAdmission.js","sources":["../../src/core/VerificationOutcomeAdmission.ts"],"sourcesContent":["import type { SessionId } from '../contracts/ids.js';\nimport type { IOutcomeRecorder, VerificationOutcome } from '../contracts/interfaces.js';\nimport { ValidationError } from '../errors.js';\nimport type { HistorySessionSnapshot, ResolvedThoughtReferences } from './IHistoryManager.js';\nimport type { ThoughtData } from './thought.js';\n\ninterface VerificationOutcomeAdmissionContext {\n\treadonly input: ThoughtData;\n\treadonly snapshot: HistorySessionSnapshot;\n\treadonly resolvedReferences: ResolvedThoughtReferences;\n\treadonly sessionId: SessionId;\n\treadonly recorder?: IOutcomeRecorder;\n}\n\n/** Builds one immutable calibration sample from the retained pre-admission target. */\nexport function prepareVerificationOutcome(\n\tcontext: VerificationOutcomeAdmissionContext\n): Omit<VerificationOutcome, 'recordedAt'> | undefined {\n\tconst { input, resolvedReferences, sessionId, snapshot, recorder } = context;\n\tif (input.thought_type !== 'verification' || input.verification_result === undefined) {\n\t\treturn undefined;\n\t}\n\tconst thoughtId = resolvedReferences.verificationTargetThoughtId;\n\tconst thoughtNumber = input.verification_target;\n\tif (thoughtId === undefined || thoughtNumber === undefined) {\n\t\tthrow new ValidationError('verification_result', 'requires a retained verification_target');\n\t}\n\tconst target = findTarget(snapshot, thoughtId, thoughtNumber);\n\tif (target === undefined) {\n\t\tthrow new ValidationError('verification_result', 'verification_target is no longer retained');\n\t}\n\tif (target.retracted === true) {\n\t\tthrow new ValidationError('verification_result', 'verification_target must not be retracted');\n\t}\n\tif (target.confidence === undefined) {\n\t\tthrow new ValidationError('verification_result', 'verification_target must have confidence');\n\t}\n\trecorder?.assertCanRecord(sessionId, thoughtId);\n\treturn Object.freeze({\n\t\tthoughtId,\n\t\tthoughtNumber: target.thought_number,\n\t\tsessionId,\n\t\tpredicted: target.confidence,\n\t\tactual: input.verification_result,\n\t\ttype: target.thought_type ?? 'regular',\n\t});\n}\n\nfunction findTarget(\n\tsnapshot: HistorySessionSnapshot,\n\tthoughtId: VerificationOutcome['thoughtId'],\n\tthoughtNumber: number\n): ThoughtData | undefined {\n\tfor (const thought of snapshot.history) {\n\t\tif (thought.id === thoughtId && thought.thought_number === thoughtNumber) return thought;\n\t}\n\tfor (const branch of Object.values(snapshot.branches)) {\n\t\tfor (const thought of branch) {\n\t\t\tif (thought.id === thoughtId && thought.thought_number === thoughtNumber) return thought;\n\t\t}\n\t}\n\treturn undefined;\n}\n"],"names":["prepareVerificationOutcome","context","input","resolvedReferences","sessionId","snapshot","recorder","undefined","thoughtId","thoughtNumber","ValidationError","target","findTarget","Object","thought","branch"],"mappings":";AAeO,SAASA,2BACfC,OAA4C;IAE5C,MAAM,EAAEC,KAAK,EAAEC,kBAAkB,EAAEC,SAAS,EAAEC,QAAQ,EAAEC,QAAQ,EAAE,GAAGL;IACrE,IAAIC,AAAuB,mBAAvBA,MAAM,YAAY,IAAuBA,AAA8BK,WAA9BL,MAAM,mBAAmB,EACrE;IAED,MAAMM,YAAYL,mBAAmB,2BAA2B;IAChE,MAAMM,gBAAgBP,MAAM,mBAAmB;IAC/C,IAAIM,AAAcD,WAAdC,aAA2BC,AAAkBF,WAAlBE,eAC9B,MAAM,IAAIC,gBAAgB,uBAAuB;IAElD,MAAMC,SAASC,WAAWP,UAAUG,WAAWC;IAC/C,IAAIE,AAAWJ,WAAXI,QACH,MAAM,IAAID,gBAAgB,uBAAuB;IAElD,IAAIC,AAAqB,SAArBA,OAAO,SAAS,EACnB,MAAM,IAAID,gBAAgB,uBAAuB;IAElD,IAAIC,AAAsBJ,WAAtBI,OAAO,UAAU,EACpB,MAAM,IAAID,gBAAgB,uBAAuB;IAElDJ,UAAU,gBAAgBF,WAAWI;IACrC,OAAOK,OAAO,MAAM,CAAC;QACpBL;QACA,eAAeG,OAAO,cAAc;QACpCP;QACA,WAAWO,OAAO,UAAU;QAC5B,QAAQT,MAAM,mBAAmB;QACjC,MAAMS,OAAO,YAAY,IAAI;IAC9B;AACD;AAEA,SAASC,WACRP,QAAgC,EAChCG,SAA2C,EAC3CC,aAAqB;IAErB,KAAK,MAAMK,WAAWT,SAAS,OAAO,CACrC,IAAIS,QAAQ,EAAE,KAAKN,aAAaM,QAAQ,cAAc,KAAKL,eAAe,OAAOK;IAElF,KAAK,MAAMC,UAAUF,OAAO,MAAM,CAACR,SAAS,QAAQ,EACnD,KAAK,MAAMS,WAAWC,OACrB,IAAID,QAAQ,EAAE,KAAKN,aAAaM,QAAQ,cAAc,KAAKL,eAAe,OAAOK;AAIpF"}

package/dist/core/compression/CompressionService.d.ts

@@ -0,0 +1,76 @@
+/**
+ * CompressionService — deterministic branch summarization.
+ *
+ * Compresses a terminated branch (or any subtree rooted at a thought) into a
+ * single {@link Summary} record. Pure offline computation: no LLM, no I/O.
+ *
+ * Topic extraction is unigram frequency with stopword filtering; aggregate
+ * confidence is the arithmetic mean of per-thought calibrated (or raw)
+ * confidence values. The covered set is identified via
+ * {@link GraphView.descendants}. Compression is **additive**: original
+ * thoughts are never mutated or deleted.
+ *
+ * @module core/compression/CompressionService
+ */
+import type { ISummaryStore, Summary } from '../../contracts/summary.js';
+import type { IEdgeStore } from '../../contracts/interfaces.js';
+import type { Logger } from '../../logger/StructuredLogger.js';
+import type { IHistoryManager } from '../IHistoryManager.js';
+import type { BranchId, SessionId, ThoughtId } from '../../contracts/ids.js';
+/** Dependencies required by {@link CompressionService}. */
+export interface CompressionDeps {
+    readonly historyManager: IHistoryManager;
+    readonly edgeStore: IEdgeStore;
+    readonly summaryStore: ISummaryStore;
+    readonly onSummaryCreated?: (summary: Summary) => void;
+    readonly logger?: Logger;
+}
+/**
+ * Deterministic, offline compression of branch subtrees into {@link Summary}.
+ *
+ * @example
+ * ```typescript
+ * const svc = new CompressionService({ historyManager, edgeStore, summaryStore });
+ * const summary = svc.compressBranch('s1', 'alt-1', 'thought-root');
+ * ```
+ */
+export declare class CompressionService {
+    private readonly _deps;
+    private readonly _graph;
+    constructor(deps: CompressionDeps);
+    /**
+     * Compress the subtree rooted at `rootThoughtId` into a {@link Summary}.
+     *
+     * Idempotency: if a summary for the same `(branchId, rootThoughtId)` already
+     * exists in the store, the existing summary is returned unchanged — same
+     * inputs always yield the same Summary identity.
+     */
+    compressBranch(sessionId: SessionId, branchId: BranchId, rootThoughtId: ThoughtId): Summary;
+    /** Look up an existing summary on this branch with a matching root. */
+    private _findExistingForRoot;
+    /** Collect the root and all of its descendants (chronological BFS). */
+    private _collectCovered;
+    /**
+     * Resolve covered ids to {@link ThoughtData}, dropping any not found in
+     * the history (defensive — graph may reference evicted thoughts).
+     */
+    private _lookupThoughts;
+    /**
+     * Mean of (`calibrated_confidence` ?? `confidence` ?? 0) across covered.
+     * Returns 0 when no thoughts are covered.
+     */
+    private _meanConfidence;
+    /**
+     * Inclusive `[min, max]` of `thought_number` across covered thoughts.
+     * Returns `[0, 0]` when no thoughts are covered.
+     */
+    private _coveredRange;
+    /**
+     * Extract top-3 unigrams by frequency from concatenated thought text.
+     * Ties broken by first-occurrence order (stable).
+     */
+    private _extractTopics;
+    /** Lowercase + strip non-alphanumerics; reject if too short or a stopword. */
+    private _normalizeToken;
+}
+//# sourceMappingURL=CompressionService.d.ts.map

package/dist/core/compression/CompressionService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompressionService.d.ts","sourceRoot":"","sources":["../../../src/core/compression/CompressionService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAK7D,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAiB7E,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,cAAc,EAAE,eAAe,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC;IACrC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;gBAEvB,IAAI,EAAE,eAAe;IAKjC;;;;;;OAMG;IACH,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,SAAS,GAAG,OAAO;IA8B3F,uEAAuE;IACvE,OAAO,CAAC,oBAAoB;IAW5B,uEAAuE;IACvE,OAAO,CAAC,eAAe;IAKvB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAcvB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAWvB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAYrB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAsBtB,8EAA8E;IAC9E,OAAO,CAAC,eAAe;CAMvB"}

package/dist/core/compression/CompressionService.js

@@ -0,0 +1,160 @@
+import { GraphView } from "../graph/GraphView.js";
+import { generateUlid } from "../ids.js";
+const STOPWORDS = new Set([
+    'the',
+    'this',
+    'that',
+    'then',
+    'than',
+    'with',
+    'from',
+    'have',
+    'will',
+    'been',
+    'they',
+    'them',
+    'their',
+    'there',
+    'about',
+    'would',
+    'could',
+    'should',
+    'which',
+    'where',
+    'when',
+    'what',
+    'some',
+    'into',
+    'also',
+    'just',
+    'like',
+    'over',
+    'such',
+    'after',
+    'only',
+    'most',
+    'very',
+    'much',
+    'well',
+    'even',
+    'still',
+    'since',
+    'being',
+    'doing',
+    'going',
+    'using'
+]);
+const MIN_TOKEN_LENGTH = 4;
+const TOP_TOPICS = 3;
+class CompressionService {
+    _deps;
+    _graph;
+    constructor(deps){
+        this._deps = deps;
+        this._graph = new GraphView(deps.edgeStore);
+    }
+    compressBranch(sessionId, branchId, rootThoughtId) {
+        const existing = this._findExistingForRoot(sessionId, branchId, rootThoughtId);
+        if (existing) return existing;
+        const coveredIds = this._collectCovered(sessionId, rootThoughtId);
+        const thoughts = this._lookupThoughts(sessionId, coveredIds);
+        const summary = {
+            id: generateUlid(),
+            sessionId,
+            branchId,
+            rootThoughtId,
+            coveredIds,
+            coveredRange: this._coveredRange(thoughts),
+            topics: this._extractTopics(thoughts),
+            aggregateConfidence: this._meanConfidence(thoughts),
+            createdAt: Date.now()
+        };
+        this._deps.summaryStore.add(summary);
+        this._deps.onSummaryCreated?.(summary);
+        this._deps.logger?.debug('compression.branch.compressed', {
+            sessionId,
+            branchId,
+            rootThoughtId,
+            covered: coveredIds.length,
+            topics: summary.topics
+        });
+        return summary;
+    }
+    _findExistingForRoot(sessionId, branchId, rootThoughtId) {
+        for (const s of this._deps.summaryStore.forBranch(sessionId, branchId))if (s.rootThoughtId === rootThoughtId) return s;
+    }
+    _collectCovered(sessionId, rootThoughtId) {
+        const descendants = this._graph.descendants(sessionId, rootThoughtId);
+        return [
+            rootThoughtId,
+            ...descendants
+        ];
+    }
+    _lookupThoughts(sessionId, coveredIds) {
+        const history = this._deps.historyManager.getHistory(sessionId);
+        const byId = new Map();
+        for (const t of history)if (void 0 !== t.id) byId.set(t.id, t);
+        const out = [];
+        for (const id of coveredIds){
+            const t = byId.get(id);
+            if (t) out.push(t);
+        }
+        return out;
+    }
+    _meanConfidence(thoughts) {
+        if (0 === thoughts.length) return 0;
+        let sum = 0;
+        for (const t of thoughts){
+            const withSignals = t;
+            const calibrated = withSignals.confidence_signals?.calibrated_confidence;
+            sum += calibrated ?? t.confidence ?? 0;
+        }
+        return sum / thoughts.length;
+    }
+    _coveredRange(thoughts) {
+        if (0 === thoughts.length) return [
+            0,
+            0
+        ];
+        let min = 1 / 0;
+        let max = -1 / 0;
+        for (const t of thoughts){
+            const n = t.thought_number;
+            if (n < min) min = n;
+            if (n > max) max = n;
+        }
+        return [
+            min,
+            max
+        ];
+    }
+    _extractTopics(thoughts) {
+        if (0 === thoughts.length) return [];
+        const counts = new Map();
+        const order = new Map();
+        let position = 0;
+        for (const t of thoughts)for (const raw of (t.thought ?? '').split(/\s+/)){
+            const token = this._normalizeToken(raw);
+            if (null !== token) {
+                if (!counts.has(token)) order.set(token, position++);
+                counts.set(token, (counts.get(token) ?? 0) + 1);
+            }
+        }
+        if (0 === counts.size) return [];
+        const entries = Array.from(counts.entries());
+        entries.sort((a, b)=>{
+            if (b[1] !== a[1]) return b[1] - a[1];
+            return (order.get(a[0]) ?? 0) - (order.get(b[0]) ?? 0);
+        });
+        return entries.slice(0, TOP_TOPICS).map(([word])=>word);
+    }
+    _normalizeToken(raw) {
+        const cleaned = raw.toLowerCase().replace(/[^a-z0-9]+/g, '');
+        if (cleaned.length < MIN_TOKEN_LENGTH) return null;
+        if (STOPWORDS.has(cleaned)) return null;
+        return cleaned;
+    }
+}
+export { CompressionService };
+
+//# sourceMappingURL=CompressionService.js.map

package/dist/core/compression/CompressionService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/compression/CompressionService.js","sources":["../../../src/core/compression/CompressionService.ts"],"sourcesContent":["/**\n * CompressionService — deterministic branch summarization.\n *\n * Compresses a terminated branch (or any subtree rooted at a thought) into a\n * single {@link Summary} record. Pure offline computation: no LLM, no I/O.\n *\n * Topic extraction is unigram frequency with stopword filtering; aggregate\n * confidence is the arithmetic mean of per-thought calibrated (or raw)\n * confidence values. The covered set is identified via\n * {@link GraphView.descendants}. Compression is **additive**: original\n * thoughts are never mutated or deleted.\n *\n * @module core/compression/CompressionService\n */\n\nimport type { ISummaryStore, Summary } from '../../contracts/summary.js';\nimport type { IEdgeStore } from '../../contracts/interfaces.js';\nimport type { Logger } from '../../logger/StructuredLogger.js';\nimport type { IHistoryManager } from '../IHistoryManager.js';\nimport type { ThoughtData } from '../thought.js';\nimport type { ConfidenceSignals } from '../reasoning.js';\nimport { GraphView } from '../graph/GraphView.js';\nimport { generateUlid } from '../ids.js';\nimport type { BranchId, SessionId, ThoughtId } from '../../contracts/ids.js';\n\n/** Stopwords excluded from topic extraction (lowercase). */\nconst STOPWORDS: ReadonlySet<string> = new Set([\n\t'the', 'this', 'that', 'then', 'than', 'with', 'from', 'have', 'will', 'been',\n\t'they', 'them', 'their', 'there', 'about', 'would', 'could', 'should', 'which',\n\t'where', 'when', 'what', 'some', 'into', 'also', 'just', 'like', 'over', 'such',\n\t'after', 'only', 'most', 'very', 'much', 'well', 'even', 'still', 'since',\n\t'being', 'doing', 'going', 'using',\n]);\n\nconst MIN_TOKEN_LENGTH = 4;\nconst TOP_TOPICS = 3;\n\n/** Local view of {@link ThoughtData} that exposes optional confidence signals. */\ntype ThoughtWithSignals = ThoughtData & { readonly confidence_signals?: ConfidenceSignals };\n\n/** Dependencies required by {@link CompressionService}. */\nexport interface CompressionDeps {\n\treadonly historyManager: IHistoryManager;\n\treadonly edgeStore: IEdgeStore;\n\treadonly summaryStore: ISummaryStore;\n\treadonly onSummaryCreated?: (summary: Summary) => void;\n\treadonly logger?: Logger;\n}\n\n/**\n * Deterministic, offline compression of branch subtrees into {@link Summary}.\n *\n * @example\n * ```typescript\n * const svc = new CompressionService({ historyManager, edgeStore, summaryStore });\n * const summary = svc.compressBranch('s1', 'alt-1', 'thought-root');\n * ```\n */\nexport class CompressionService {\n\tprivate readonly _deps: CompressionDeps;\n\tprivate readonly _graph: GraphView;\n\n\tconstructor(deps: CompressionDeps) {\n\t\tthis._deps = deps;\n\t\tthis._graph = new GraphView(deps.edgeStore);\n\t}\n\n\t/**\n\t * Compress the subtree rooted at `rootThoughtId` into a {@link Summary}.\n\t *\n\t * Idempotency: if a summary for the same `(branchId, rootThoughtId)` already\n\t * exists in the store, the existing summary is returned unchanged — same\n\t * inputs always yield the same Summary identity.\n\t */\n\tcompressBranch(sessionId: SessionId, branchId: BranchId, rootThoughtId: ThoughtId): Summary {\n\t\tconst existing = this._findExistingForRoot(sessionId, branchId, rootThoughtId);\n\t\tif (existing) return existing;\n\n\t\tconst coveredIds = this._collectCovered(sessionId, rootThoughtId);\n\t\tconst thoughts = this._lookupThoughts(sessionId, coveredIds);\n\t\tconst summary: Summary = {\n\t\t\tid: generateUlid(),\n\t\t\tsessionId,\n\t\t\tbranchId,\n\t\t\trootThoughtId,\n\t\t\tcoveredIds,\n\t\t\tcoveredRange: this._coveredRange(thoughts),\n\t\t\ttopics: this._extractTopics(thoughts),\n\t\t\taggregateConfidence: this._meanConfidence(thoughts),\n\t\t\tcreatedAt: Date.now(),\n\t\t};\n\n\t\tthis._deps.summaryStore.add(summary);\n\t\tthis._deps.onSummaryCreated?.(summary);\n\t\tthis._deps.logger?.debug('compression.branch.compressed', {\n\t\t\tsessionId,\n\t\t\tbranchId,\n\t\t\trootThoughtId,\n\t\t\tcovered: coveredIds.length,\n\t\t\ttopics: summary.topics,\n\t\t});\n\t\treturn summary;\n\t}\n\n\t/** Look up an existing summary on this branch with a matching root. */\n\tprivate _findExistingForRoot(\n\t\tsessionId: SessionId,\n\t\tbranchId: BranchId,\n\t\trootThoughtId: ThoughtId\n\t): Summary | undefined {\n\t\tfor (const s of this._deps.summaryStore.forBranch(sessionId, branchId)) {\n\t\t\tif (s.rootThoughtId === rootThoughtId) return s;\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t/** Collect the root and all of its descendants (chronological BFS). */\n\tprivate _collectCovered(sessionId: SessionId, rootThoughtId: ThoughtId): readonly ThoughtId[] {\n\t\tconst descendants = this._graph.descendants(sessionId, rootThoughtId);\n\t\treturn [rootThoughtId, ...descendants];\n\t}\n\n\t/**\n\t * Resolve covered ids to {@link ThoughtData}, dropping any not found in\n\t * the history (defensive — graph may reference evicted thoughts).\n\t */\n\tprivate _lookupThoughts(sessionId: SessionId, coveredIds: readonly ThoughtId[]): ThoughtData[] {\n\t\tconst history = this._deps.historyManager.getHistory(sessionId);\n\t\tconst byId = new Map<string, ThoughtData>();\n\t\tfor (const t of history) {\n\t\t\tif (t.id !== undefined) byId.set(t.id, t);\n\t\t}\n\t\tconst out: ThoughtData[] = [];\n\t\tfor (const id of coveredIds) {\n\t\t\tconst t = byId.get(id);\n\t\t\tif (t) out.push(t);\n\t\t}\n\t\treturn out;\n\t}\n\n\t/**\n\t * Mean of (`calibrated_confidence` ?? `confidence` ?? 0) across covered.\n\t * Returns 0 when no thoughts are covered.\n\t */\n\tprivate _meanConfidence(thoughts: readonly ThoughtData[]): number {\n\t\tif (thoughts.length === 0) return 0;\n\t\tlet sum = 0;\n\t\tfor (const t of thoughts) {\n\t\t\tconst withSignals = t as ThoughtWithSignals;\n\t\t\tconst calibrated = withSignals.confidence_signals?.calibrated_confidence;\n\t\t\tsum += calibrated ?? t.confidence ?? 0;\n\t\t}\n\t\treturn sum / thoughts.length;\n\t}\n\n\t/**\n\t * Inclusive `[min, max]` of `thought_number` across covered thoughts.\n\t * Returns `[0, 0]` when no thoughts are covered.\n\t */\n\tprivate _coveredRange(thoughts: readonly ThoughtData[]): readonly [number, number] {\n\t\tif (thoughts.length === 0) return [0, 0];\n\t\tlet min = Number.POSITIVE_INFINITY;\n\t\tlet max = Number.NEGATIVE_INFINITY;\n\t\tfor (const t of thoughts) {\n\t\t\tconst n = t.thought_number;\n\t\t\tif (n < min) min = n;\n\t\t\tif (n > max) max = n;\n\t\t}\n\t\treturn [min, max];\n\t}\n\n\t/**\n\t * Extract top-3 unigrams by frequency from concatenated thought text.\n\t * Ties broken by first-occurrence order (stable).\n\t */\n\tprivate _extractTopics(thoughts: readonly ThoughtData[]): readonly string[] {\n\t\tif (thoughts.length === 0) return [];\n\t\tconst counts = new Map<string, number>();\n\t\tconst order = new Map<string, number>();\n\t\tlet position = 0;\n\t\tfor (const t of thoughts) {\n\t\t\tfor (const raw of (t.thought ?? '').split(/\\s+/)) {\n\t\t\t\tconst token = this._normalizeToken(raw);\n\t\t\t\tif (token === null) continue;\n\t\t\t\tif (!counts.has(token)) order.set(token, position++);\n\t\t\t\tcounts.set(token, (counts.get(token) ?? 0) + 1);\n\t\t\t}\n\t\t}\n\t\tif (counts.size === 0) return [];\n\t\tconst entries = Array.from(counts.entries());\n\t\tentries.sort((a, b) => {\n\t\t\tif (b[1] !== a[1]) return b[1] - a[1];\n\t\t\treturn (order.get(a[0]) ?? 0) - (order.get(b[0]) ?? 0);\n\t\t});\n\t\treturn entries.slice(0, TOP_TOPICS).map(([word]) => word);\n\t}\n\n\t/** Lowercase + strip non-alphanumerics; reject if too short or a stopword. */\n\tprivate _normalizeToken(raw: string): string | null {\n\t\tconst cleaned = raw.toLowerCase().replace(/[^a-z0-9]+/g, '');\n\t\tif (cleaned.length < MIN_TOKEN_LENGTH) return null;\n\t\tif (STOPWORDS.has(cleaned)) return null;\n\t\treturn cleaned;\n\t}\n}\n"],"names":["STOPWORDS","Set","MIN_TOKEN_LENGTH","TOP_TOPICS","CompressionService","deps","GraphView","sessionId","branchId","rootThoughtId","existing","coveredIds","thoughts","summary","generateUlid","Date","s","descendants","history","byId","Map","t","undefined","out","id","sum","withSignals","calibrated","min","Number","max","n","counts","order","position","raw","token","entries","Array","a","b","word","cleaned"],"mappings":"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"}

package/dist/core/compression/DehydrationPolicy.d.ts

@@ -0,0 +1,75 @@
+/**
+ * DehydrationPolicy — sliding-window history compaction.
+ *
+ * Replaces older thoughts (the "cold" prefix beyond the most recent K) with
+ * lightweight {@link SummaryRef} placeholders that point to existing
+ * {@link Summary} records in an {@link ISummaryStore}. Recent thoughts (the
+ * "hot" suffix of length K) are preserved verbatim.
+ *
+ * Pure and **non-mutating**: the input history array is never modified, and
+ * neither the summary store nor any thought record is altered. When a cold
+ * thought has no matching summary, the original {@link ThoughtData} is emitted
+ * unchanged. Consecutive cold thoughts that fall within the same summary's
+ * `coveredRange` are deduplicated to a single `SummaryRef`.
+ *
+ * @module core/compression/DehydrationPolicy
+ */
+import type { ISummaryStore } from '../../contracts/summary.js';
+import type { ThoughtData } from '../thought.js';
+import type { SessionId } from '../../contracts/ids.js';
+/** Options controlling sliding-window dehydration. */
+export interface DehydrationOptions {
+    /**
+     * Number of most-recent thoughts to keep verbatim ("hot" window).
+     * Older thoughts (the "cold" prefix) are eligible for replacement by
+     * summary references.
+     * @default 50
+     */
+    readonly keepLastK?: number;
+}
+/**
+ * Lightweight reference replacing one or more cold thoughts covered by a
+ * {@link Summary}. Carries only the summary id and the inclusive
+ * `thought_number` range it covers.
+ */
+export interface SummaryRef {
+    readonly kind: 'summary';
+    readonly summaryId: string;
+    readonly coveredRange: readonly [number, number];
+}
+/** Output entry in a dehydrated history: either a verbatim thought or a ref. */
+export type HydratedEntry = ThoughtData | SummaryRef;
+/**
+ * Sliding-window dehydration policy.
+ *
+ * @example
+ * ```typescript
+ * const policy = new DehydrationPolicy(summaryStore);
+ * const hydrated = policy.apply(history, sessionId, { keepLastK: 50 });
+ * ```
+ */
+export declare class DehydrationPolicy {
+    private readonly _summaryStore;
+    constructor(_summaryStore: ISummaryStore);
+    /**
+     * Apply sliding-window dehydration to a history array.
+     *
+     * Returns a new array of `(ThoughtData | SummaryRef)` where:
+     * - The last `keepLastK` thoughts are preserved verbatim.
+     * - Older thoughts whose `thought_number` falls within an existing
+     *   summary's `coveredRange` are replaced by a single {@link SummaryRef}.
+     * - Consecutive cold thoughts covered by the same summary collapse to one
+     *   `SummaryRef`.
+     * - Cold thoughts with no matching summary are emitted verbatim.
+     *
+     * Non-mutating: the input array is not modified and original thoughts are
+     * never altered.
+     *
+     * @param history - Input history (chronological)
+     * @param sessionId - Session whose summaries should be considered
+     * @param opts - Optional dehydration options
+     * @returns A new array of hydrated entries
+     */
+    apply(history: readonly ThoughtData[], sessionId: SessionId, opts?: DehydrationOptions): HydratedEntry[];
+}
+//# sourceMappingURL=DehydrationPolicy.d.ts.map

package/dist/core/compression/DehydrationPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DehydrationPolicy.d.ts","sourceRoot":"","sources":["../../../src/core/compression/DehydrationPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAW,MAAM,4BAA4B,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAMxD,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjD;AAED,gFAAgF;AAChF,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;AAErD;;;;;;;;GAQG;AACH,qBAAa,iBAAiB;IACjB,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,EAAE,aAAa;IAEzD;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CACJ,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,SAAS,EAAE,SAAS,EACpB,IAAI,CAAC,EAAE,kBAAkB,GACvB,aAAa,EAAE;CAgClB"}

package/dist/core/compression/DehydrationPolicy.js

@@ -0,0 +1,45 @@
+const DEFAULT_KEEP_LAST_K = 50;
+class DehydrationPolicy {
+    _summaryStore;
+    constructor(_summaryStore){
+        this._summaryStore = _summaryStore;
+    }
+    apply(history, sessionId, opts) {
+        const k = opts?.keepLastK ?? DEFAULT_KEEP_LAST_K;
+        if (0 === history.length) return [];
+        if (history.length <= k) return history.slice();
+        const splitAt = history.length - k;
+        const cold = history.slice(0, splitAt);
+        const hot = history.slice(splitAt);
+        const summaries = this._summaryStore.forSession(sessionId);
+        const out = [];
+        let lastEmittedSummaryId;
+        for (const thought of cold){
+            const match = findCoveringSummary(summaries, thought.thought_number);
+            if (void 0 === match) {
+                out.push(thought);
+                lastEmittedSummaryId = void 0;
+                continue;
+            }
+            if (match.id !== lastEmittedSummaryId) {
+                out.push({
+                    kind: 'summary',
+                    summaryId: match.id,
+                    coveredRange: match.coveredRange
+                });
+                lastEmittedSummaryId = match.id;
+            }
+        }
+        for (const t of hot)out.push(t);
+        return out;
+    }
+}
+function findCoveringSummary(summaries, thoughtNumber) {
+    for (const s of summaries){
+        const [lo, hi] = s.coveredRange;
+        if (thoughtNumber >= lo && thoughtNumber <= hi) return s;
+    }
+}
+export { DehydrationPolicy };
+
+//# sourceMappingURL=DehydrationPolicy.js.map

package/dist/core/compression/DehydrationPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/compression/DehydrationPolicy.js","sources":["../../../src/core/compression/DehydrationPolicy.ts"],"sourcesContent":["/**\n * DehydrationPolicy — sliding-window history compaction.\n *\n * Replaces older thoughts (the \"cold\" prefix beyond the most recent K) with\n * lightweight {@link SummaryRef} placeholders that point to existing\n * {@link Summary} records in an {@link ISummaryStore}. Recent thoughts (the\n * \"hot\" suffix of length K) are preserved verbatim.\n *\n * Pure and **non-mutating**: the input history array is never modified, and\n * neither the summary store nor any thought record is altered. When a cold\n * thought has no matching summary, the original {@link ThoughtData} is emitted\n * unchanged. Consecutive cold thoughts that fall within the same summary's\n * `coveredRange` are deduplicated to a single `SummaryRef`.\n *\n * @module core/compression/DehydrationPolicy\n */\n\nimport type { ISummaryStore, Summary } from '../../contracts/summary.js';\nimport type { ThoughtData } from '../thought.js';\nimport type { SessionId } from '../../contracts/ids.js';\n\n\n/** Default value for {@link DehydrationOptions.keepLastK}. */\nconst DEFAULT_KEEP_LAST_K = 50;\n\n/** Options controlling sliding-window dehydration. */\nexport interface DehydrationOptions {\n\t/**\n\t * Number of most-recent thoughts to keep verbatim (\"hot\" window).\n\t * Older thoughts (the \"cold\" prefix) are eligible for replacement by\n\t * summary references.\n\t * @default 50\n\t */\n\treadonly keepLastK?: number;\n}\n\n/**\n * Lightweight reference replacing one or more cold thoughts covered by a\n * {@link Summary}. Carries only the summary id and the inclusive\n * `thought_number` range it covers.\n */\nexport interface SummaryRef {\n\treadonly kind: 'summary';\n\treadonly summaryId: string;\n\treadonly coveredRange: readonly [number, number];\n}\n\n/** Output entry in a dehydrated history: either a verbatim thought or a ref. */\nexport type HydratedEntry = ThoughtData | SummaryRef;\n\n/**\n * Sliding-window dehydration policy.\n *\n * @example\n * ```typescript\n * const policy = new DehydrationPolicy(summaryStore);\n * const hydrated = policy.apply(history, sessionId, { keepLastK: 50 });\n * ```\n */\nexport class DehydrationPolicy {\n\tconstructor(private readonly _summaryStore: ISummaryStore) {}\n\n\t/**\n\t * Apply sliding-window dehydration to a history array.\n\t *\n\t * Returns a new array of `(ThoughtData | SummaryRef)` where:\n\t * - The last `keepLastK` thoughts are preserved verbatim.\n\t * - Older thoughts whose `thought_number` falls within an existing\n\t *   summary's `coveredRange` are replaced by a single {@link SummaryRef}.\n\t * - Consecutive cold thoughts covered by the same summary collapse to one\n\t *   `SummaryRef`.\n\t * - Cold thoughts with no matching summary are emitted verbatim.\n\t *\n\t * Non-mutating: the input array is not modified and original thoughts are\n\t * never altered.\n\t *\n\t * @param history - Input history (chronological)\n\t * @param sessionId - Session whose summaries should be considered\n\t * @param opts - Optional dehydration options\n\t * @returns A new array of hydrated entries\n\t */\n\tapply(\n\t\thistory: readonly ThoughtData[],\n\t\tsessionId: SessionId,\n\t\topts?: DehydrationOptions\n\t): HydratedEntry[] {\n\t\tconst k = opts?.keepLastK ?? DEFAULT_KEEP_LAST_K;\n\t\tif (history.length === 0) return [];\n\t\tif (history.length <= k) return history.slice();\n\n\t\tconst splitAt = history.length - k;\n\t\tconst cold = history.slice(0, splitAt);\n\t\tconst hot = history.slice(splitAt);\n\n\t\tconst summaries = this._summaryStore.forSession(sessionId);\n\t\tconst out: HydratedEntry[] = [];\n\t\tlet lastEmittedSummaryId: string | undefined;\n\n\t\tfor (const thought of cold) {\n\t\t\tconst match = findCoveringSummary(summaries, thought.thought_number);\n\t\t\tif (match === undefined) {\n\t\t\t\tout.push(thought);\n\t\t\t\tlastEmittedSummaryId = undefined;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (match.id === lastEmittedSummaryId) continue;\n\t\t\tout.push({\n\t\t\t\tkind: 'summary',\n\t\t\t\tsummaryId: match.id,\n\t\t\t\tcoveredRange: match.coveredRange,\n\t\t\t});\n\t\t\tlastEmittedSummaryId = match.id;\n\t\t}\n\n\t\tfor (const t of hot) out.push(t);\n\t\treturn out;\n\t}\n}\n\n/**\n * Find the first summary whose `coveredRange` includes the given thought\n * number (inclusive on both ends). Returns `undefined` when none match.\n */\nfunction findCoveringSummary(\n\tsummaries: readonly Summary[],\n\tthoughtNumber: number\n): Summary | undefined {\n\tfor (const s of summaries) {\n\t\tconst [lo, hi] = s.coveredRange;\n\t\tif (thoughtNumber >= lo && thoughtNumber <= hi) return s;\n\t}\n\treturn undefined;\n}\n"],"names":["DEFAULT_KEEP_LAST_K","DehydrationPolicy","_summaryStore","history","sessionId","opts","k","splitAt","cold","hot","summaries","out","lastEmittedSummaryId","thought","match","findCoveringSummary","undefined","t","thoughtNumber","s","lo","hi"],"mappings":"AAuBA,MAAMA,sBAAsB;AAoCrB,MAAMC;;IACZ,YAA6BC,aAA4B,CAAE;aAA9BA,aAAa,GAAbA;IAA+B;IAqB5D,MACCC,OAA+B,EAC/BC,SAAoB,EACpBC,IAAyB,EACP;QAClB,MAAMC,IAAID,MAAM,aAAaL;QAC7B,IAAIG,AAAmB,MAAnBA,QAAQ,MAAM,EAAQ,OAAO,EAAE;QACnC,IAAIA,QAAQ,MAAM,IAAIG,GAAG,OAAOH,QAAQ,KAAK;QAE7C,MAAMI,UAAUJ,QAAQ,MAAM,GAAGG;QACjC,MAAME,OAAOL,QAAQ,KAAK,CAAC,GAAGI;QAC9B,MAAME,MAAMN,QAAQ,KAAK,CAACI;QAE1B,MAAMG,YAAY,IAAI,CAAC,aAAa,CAAC,UAAU,CAACN;QAChD,MAAMO,MAAuB,EAAE;QAC/B,IAAIC;QAEJ,KAAK,MAAMC,WAAWL,KAAM;YAC3B,MAAMM,QAAQC,oBAAoBL,WAAWG,QAAQ,cAAc;YACnE,IAAIC,AAAUE,WAAVF,OAAqB;gBACxBH,IAAI,IAAI,CAACE;gBACTD,uBAAuBI;gBACvB;YACD;YACA,IAAIF,MAAM,EAAE,KAAKF;gBACjBD,IAAI,IAAI,CAAC;oBACR,MAAM;oBACN,WAAWG,MAAM,EAAE;oBACnB,cAAcA,MAAM,YAAY;gBACjC;gBACAF,uBAAuBE,MAAM,EAAE;;QAChC;QAEA,KAAK,MAAMG,KAAKR,IAAKE,IAAI,IAAI,CAACM;QAC9B,OAAON;IACR;AACD;AAMA,SAASI,oBACRL,SAA6B,EAC7BQ,aAAqB;IAErB,KAAK,MAAMC,KAAKT,UAAW;QAC1B,MAAM,CAACU,IAAIC,GAAG,GAAGF,EAAE,YAAY;QAC/B,IAAID,iBAAiBE,MAAMF,iBAAiBG,IAAI,OAAOF;IACxD;AAED"}

package/dist/core/compression/InMemorySummaryStore.d.ts

@@ -0,0 +1,132 @@
+/**
+ * InMemorySummaryStore — in-memory implementation of {@link ISummaryStore}.
+ *
+ * Stores compressed thought summaries in three indexes for O(1) point lookups
+ * and O(n) bucket reads (n = result size). Per-session and per-branch isolation
+ * is enforced by maintaining independent buckets keyed by session and
+ * `${sessionId}:${branchId}`.
+ *
+ * The store is intentionally synchronous and pure in-memory — no I/O. Persistence
+ * adapters may wrap this implementation if durability is required.
+ *
+ * @module core/compression/InMemorySummaryStore
+ */
+import type { ISummaryStore, Summary } from '../../contracts/summary.js';
+import { type BranchId } from '../../contracts/ids.js';
+/**
+ * In-memory implementation of {@link ISummaryStore}.
+ *
+ * Maintains three indexes:
+ * - `_byId`: id → summary (global lookup)
+ * - `_bySession`: sessionId → summaries[] (sorted by `createdAt` ascending)
+ * - `_byBranch`: `${sessionId}:${branchId}` → summaries[] (sorted by `createdAt`)
+ *
+ * @example
+ * ```typescript
+ * const store = new InMemorySummaryStore();
+ * store.add({
+ *   id: '01HX...',
+ *   sessionId: 's1',
+ *   rootThoughtId: 't5',
+ *   coveredIds: ['t5', 't6'],
+ *   coveredRange: [5, 6],
+ *   topics: ['cache', 'lookup'],
+ *   aggregateConfidence: 0.8,
+ *   createdAt: Date.now(),
+ * });
+ * const all = store.forSession('s1');
+ * ```
+ */
+export declare class InMemorySummaryStore implements ISummaryStore {
+    private readonly _byId;
+    private readonly _bySession;
+    private readonly _byBranch;
+    /**
+     * Add a summary to the store.
+     *
+     * Inserts the summary into all three indexes, maintaining ascending
+     * `createdAt` order in the per-session and per-branch buckets via binary
+     * search insertion (O(log n)).
+     *
+     * @param summary - The summary record to add
+     * @throws {SequentialThinkingError} When a summary with the same id already exists
+     *
+     * @example
+     * ```typescript
+     * store.add(summary);
+     * ```
+     */
+    add(summary: Summary): void;
+    /**
+     * Retrieve a summary by its unique id.
+     *
+     * @param id - The summary's unique identifier
+     * @returns The summary, or `undefined` if not found
+     *
+     * @example
+     * ```typescript
+     * const s = store.get('01HX...');
+     * ```
+     */
+    get(id: string): Summary | undefined;
+    /**
+     * Get all summaries for a session, sorted by `createdAt` ascending.
+     *
+     * @param sessionId - Session to query
+     * @returns Read-only array of summaries (empty if none)
+     *
+     * @example
+     * ```typescript
+     * for (const s of store.forSession('s1')) console.log(s.topics);
+     * ```
+     */
+    forSession(sessionId: string): readonly Summary[];
+    /**
+     * Get all summaries on a specific branch within a session.
+     *
+     * @param sessionId - Session to query
+     * @param branchId - Branch identifier
+     * @returns Read-only array of summaries (empty if none)
+     *
+     * @example
+     * ```typescript
+     * const branch = store.forBranch('s1', 'alt-1');
+     * ```
+     */
+    forBranch(sessionId: string, branchId: BranchId): readonly Summary[];
+    /**
+     * Remove all summaries for a session. Other sessions are unaffected.
+     *
+     * Removes entries from all three indexes in a single pass over the
+     * session's summary list.
+     *
+     * @param sessionId - Session to clear
+     *
+     * @example
+     * ```typescript
+     * store.clearSession('s1');
+     * ```
+     */
+    clearSession(sessionId: string): void;
+    clearAll(): void;
+    /**
+     * Count summaries.
+     *
+     * @param sessionId - If provided, count for that session only;
+     *   otherwise return the total across all sessions
+     * @returns The number of summaries
+     *
+     * @example
+     * ```typescript
+     * const total = store.size();
+     * const perSession = store.size('s1');
+     * ```
+     */
+    size(sessionId?: string): number;
+    /**
+     * Insert a summary into a bucket maintaining ascending `createdAt` order
+     * via binary search (O(log n) search, O(n) splice).
+     */
+    private _insertSorted;
+}
+//# sourceMappingURL=InMemorySummaryStore.d.ts.map

package/dist/core/compression/InMemorySummaryStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemorySummaryStore.d.ts","sourceRoot":"","sources":["../../../src/core/compression/InMemorySummaryStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,EAIN,KAAK,QAAQ,EAGb,MAAM,wBAAwB,CAAC;AAahC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,oBAAqB,YAAW,aAAa;IACzD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsD;IAC5E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAwC;IACnE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuC;IAEjE;;;;;;;;;;;;;;OAcG;IACH,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAqB3B;;;;;;;;;;OAUG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAQpC;;;;;;;;;;OAUG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE;IAIjD;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,SAAS,OAAO,EAAE;IAIpE;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAerC,QAAQ,IAAI,IAAI;IAMhB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM;IAShC;;;OAGG;IACH,OAAO,CAAC,aAAa;CAmBrB"}