@iworkforces/tracelattice 2.0.3

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

@@ -0,0 +1 @@
+{"version":3,"file":"HistoryManager.d.ts","sourceRoot":"","sources":["../../src/core/HistoryManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AACrF,OAAO,EAGN,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAO7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,EAEN,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAGxD,OAAO,KAAK,EACX,sBAAsB,EACtB,eAAe,EACf,uBAAuB,EACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAqB,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAIzF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAyB,KAAK,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAEpG,OAAO,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC;AAE/E,kFAAkF;AAClF,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAiBhD,MAAM,WAAW,oBAAoB;IACpC,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACxC,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,yEAAyE;IACzE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,mDAAmD;IACnD,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,6DAA6D;IAC7D,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,YAAY,CAAC,EAAE,uBAAuB,CAAC;IACvC,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,mFAAmF;IACnF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,6EAA6E;IAC7E,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,4DAA4D;IAC5D,oBAAoB,CAAC,EAAE,2BAA2B,CAAC;IACnD,wEAAwE;IACxE,0BAA0B,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,IAAI,CAAC;IAC5D,sFAAsF;IACtF,sBAAsB,CAAC,EAAE,MAAM,IAAI,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,qBAAa,cAAe,YAAW,eAAe;IACrD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAqB;IAC5D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAkB;IACxD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAO;IAC3C,OAAO,CAAC,SAAS,CAA2C;IAC5D,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,mBAAmB,CAAU;IACrC,OAAO,CAAC,QAAQ,CAAC,CAAW;IAE5B,OAAO,CAAC,UAAU,CAAC,CAAa;IAChC,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,SAAS,CAAU;IAE3B,OAAO,CAAC,aAAa,CAAiC;IAEtD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;IAC3C,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,kBAAkB,CAAyC;IACnE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA+B;IAC/D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAwC;IAC1E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8B;IACzD,OAAO,CAAC,cAAc,CAAsC;IAC5D,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAC,CAAiC;IAC9E,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAC,CAAa;gBAE1C,MAAM,GAAE,oBAAyB;IA4E7C,OAAO,KAAK,WAAW,GAEtB;IAED,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,eAAe;IAKvB,8DAA8D;IACvD,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAKpC;;;;;OAKG;IACI,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxD;;;;;OAKG;IACI,eAAe,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAQjF,uFAAuF;IAChF,YAAY,IAAI,UAAU,GAAG,SAAS;IAI7C,OAAO,CAAC,GAAG;IAIX,yFAAyF;IACzF,OAAO,CAAC,gBAAgB;IAIxB;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,0BAA0B;IAalC,OAAO,CAAC,mBAAmB;IAe3B,OAAO,CAAC,uBAAuB;IAiB/B,OAAO,CAAC,2BAA2B;IAInC,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,uBAAuB;YAMjB,cAAc;IAU5B,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,mBAAmB;IAe3B,OAAO,CAAC,yBAAyB;IAcjC,OAAO,CAAC,wBAAwB;IAOhC;;;OAGG;IACI,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,IAAI;IAOhF,OAAO,CAAC,0BAA0B;IA+DlC,OAAO,CAAC,2BAA2B;IAsBnC,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,qBAAqB;IAa7B,OAAO,CAAC,oBAAoB;IAuB5B,OAAO,CAAC,oCAAoC;IAM5C,OAAO,CAAC,iCAAiC;IAKzC,OAAO,CAAC,uBAAuB;IAkB/B,uEAAuE;IACvE,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,sBAAsB;IAKvB,uBAAuB,CAC7B,SAAS,EAAE,SAAS,EACpB,aAAa,EAAE,MAAM,GACnB,0BAA0B;IAK7B,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,uBAAuB;IAiB/B,OAAO,CAAC,sBAAsB;IAYvB,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE;IAIpD;;;OAGG;IACI,kBAAkB,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,aAAa,EAAE;IAUlF,gBAAgB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM;IAI5C,WAAW,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,QAAQ,EAAE,WAAW,EAAE,CAAC;IAIhE,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,EAAE;IAInD,mGAAmG;IAC5F,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,sBAAsB;IA0BhE,wEAAwE;IACjE,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI;IA4BvE,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO;IAKxE,oBAAoB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IAI9D,kBAAkB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IAI5D,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE,GAAG,SAAS;IAInF,4DAA4D;IACrD,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAqBtC,0FAA0F;IAC7E,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,mBAAmB,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAW7F,iFAAiF;IACpE,2BAA2B,CACvC,SAAS,EAAE,SAAS,EACpB,mBAAmB,CAAC,EAAE,MAAM,IAAI,GAC9B,OAAO,CAAC,IAAI,CAAC;IAahB,iFAAiF;IACpE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtE,iFAAiF;IACpE,uBAAuB,CAAC,mBAAmB,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9E,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIrC,aAAa,IAAI,MAAM,EAAE;IAIzB,eAAe,IAAI,MAAM;IAIhC,OAAO,CAAC,cAAc;IA0BtB,4FAA4F;IAC/E,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAgD1C,oBAAoB,IAAI,OAAO;IAI/B,qBAAqB,IAAI,kBAAkB,GAAG,IAAI;IAIzD,sFAAsF;IAC/E,eAAe,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI;IAK9D;;;;;;OAMG;IACI,iBAAiB,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAO1D,kGAAkG;IAC3F,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAQhC,4EAA4E;IAC/D,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC;IAMrD,sFAAsF;IAC/E,2BAA2B,IAAI,IAAI;IAW1C,kFAAkF;IAC3E,oBAAoB,IAAI,MAAM;CAGrC"}

package/dist/core/HistoryManager.js

@@ -0,0 +1,594 @@
+import { GLOBAL_SESSION_ID, asSessionId } from "../contracts/ids.js";
+import { InvalidBacktrackError, MaxSessionsReachedError, ValidationError } from "../errors.js";
+import { NullLogger } from "../logger/NullLogger.js";
+import { DehydrationPolicy } from "./compression/DehydrationPolicy.js";
+import { AsyncResetRequiredError, SessionAccessDeniedError } from "./SessionErrors.js";
+import { EdgeEmitter } from "./graph/EdgeEmitter.js";
+import { PersistenceBuffer } from "./PersistenceBuffer.js";
+import { SessionManager } from "./SessionManager.js";
+import { SessionResetCoordinator } from "./SessionResetCoordinator.js";
+import { stagePersistenceRestore } from "./PersistenceRestore.js";
+import { getOwner } from "../context/RequestContext.js";
+import { ThoughtReferenceIndex } from "./ThoughtReferenceIndex.js";
+import { resolveThoughtReferencesForAdmission } from "./CrossReferenceValidator.js";
+import { SessionLifecycleCoordinator } from "./SessionLifecycleCoordinator.js";
+const ABSOLUTE_MAX_HISTORY_SIZE = 10000;
+class HistoryManager {
+    static DEFAULT_SESSION = GLOBAL_SESSION_ID;
+    static SESSION_TTL_MS = 1800000;
+    static MAX_SESSIONS = 100;
+    _sessions = new Map();
+    _maxHistorySize;
+    _maxBranches;
+    _maxBranchSize;
+    _logger;
+    _persistence;
+    _persistenceEnabled;
+    _metrics;
+    _edgeStore;
+    _summaryStore;
+    _dagEdges;
+    _eventEmitter;
+    _edgeEmitter;
+    _referenceIndex = new ThoughtReferenceIndex();
+    _persistenceBuffer;
+    _sessionManager;
+    _resetCoordinator;
+    _sessionLock;
+    _lifecycle;
+    _shutdownOwner = null;
+    _clearSessionAuxiliaryState;
+    _clearAllAuxiliaryState;
+    constructor(config = {}){
+        this._logger = config.logger ?? new NullLogger();
+        const requestedMaxSize = config.maxHistorySize ?? 10000;
+        this._maxHistorySize = Math.min(requestedMaxSize, ABSOLUTE_MAX_HISTORY_SIZE);
+        if (requestedMaxSize > ABSOLUTE_MAX_HISTORY_SIZE) this._logger.warn('maxHistorySize exceeds absolute maximum, capped', {
+            requested: requestedMaxSize,
+            applied: ABSOLUTE_MAX_HISTORY_SIZE
+        });
+        this._maxBranches = config.maxBranches ?? 50;
+        this._maxBranchSize = config.maxBranchSize || 100;
+        this._persistence = config.persistence ?? null;
+        this._persistenceEnabled = null !== this._persistence;
+        this._metrics = config.metrics;
+        this._eventEmitter = config.eventEmitter ?? null;
+        this._edgeStore = config.edgeStore;
+        this._summaryStore = config.summaryStore;
+        this._dagEdges = config.dagEdges ?? true;
+        this._sessionLock = config.sessionLock;
+        this._lifecycle = config.lifecycleCoordinator ?? new SessionLifecycleCoordinator();
+        this._clearSessionAuxiliaryState = config.clearSessionAuxiliaryState;
+        this._clearAllAuxiliaryState = config.clearAllAuxiliaryState;
+        this._edgeEmitter = new EdgeEmitter({
+            edgeStore: this._edgeStore,
+            dagEdges: this._dagEdges,
+            defaultSessionId: HistoryManager.DEFAULT_SESSION,
+            logger: this._logger
+        });
+        this._sessionManager = new SessionManager({
+            defaultSessionId: HistoryManager.DEFAULT_SESSION,
+            sessionTtlMs: HistoryManager.SESSION_TTL_MS,
+            cleanupIntervalMs: 300000,
+            getMaxSessions: ()=>HistoryManager.MAX_SESSIONS,
+            maxSessionsPerOwner: config.maxSessionsPerOwner ?? 50,
+            logger: this._logger
+        });
+        this._persistenceBuffer = null;
+        if (this._persistenceEnabled && this._persistence) {
+            this._persistenceBuffer = new PersistenceBuffer({
+                persistence: this._persistence,
+                bufferSize: config.persistenceBufferSize ?? 100,
+                flushInterval: config.persistenceFlushInterval ?? 1000,
+                maxRetries: config.persistenceMaxRetries ?? 3,
+                defaultSessionId: asSessionId(HistoryManager.DEFAULT_SESSION),
+                getSessions: ()=>this._sessions,
+                getDefaultSession: ()=>this._getSession(),
+                edgeStore: this._edgeStore,
+                eventEmitter: this._eventEmitter,
+                logger: this._logger
+            });
+            this._startFlushTimer();
+        }
+        this._resetCoordinator = new SessionResetCoordinator({
+            persistence: this._persistence,
+            barrier: this._persistenceBuffer,
+            edgeStore: this._edgeStore,
+            summaryStore: this._summaryStore,
+            sessions: this._sessions,
+            createSessionState: (owner)=>this._createSessionState(owner),
+            logger: this._logger
+        });
+        this._sessionManager.startCleanupTimer(this._sessions, (sessionId)=>this._isTtlEvictionEligible(sessionId), (sessionIds)=>this._evictSessions(sessionIds));
+    }
+    get _flushTimer() {
+        return this._persistenceBuffer?.timer ?? null;
+    }
+    _startFlushTimer() {
+        this._persistenceBuffer?.startFlushTimer();
+    }
+    _stopFlushTimer() {
+        if (null === this._flushTimer) return;
+        this._persistenceBuffer?.stopFlushTimer();
+    }
+    _flushBuffer() {
+        this._stageAllRestoreBranchReconciliation();
+        return this._persistenceBuffer?.flush() ?? Promise.resolve();
+    }
+    drainSession(sessionId) {
+        const session = this._sessions.get(sessionId);
+        if (void 0 !== session) this._stageRestoreBranchReconciliation(sessionId, session);
+        return this._persistenceBuffer?.drainSession(sessionId) ?? Promise.resolve();
+    }
+    bufferSummaries(sessionId, summaries) {
+        this._lifecycle.runMutation(sessionId, ()=>{
+            this._persistenceBuffer?.bufferSummaries(sessionId, summaries);
+            const session = this._sessions.get(sessionId);
+            if (void 0 !== session) this._stageRestoreBranchReconciliation(sessionId, session);
+        });
+    }
+    getEdgeStore() {
+        return this._edgeStore;
+    }
+    log(message, meta) {
+        this._logger.info(message, meta);
+    }
+    _getCurrentOwner() {
+        return getOwner();
+    }
+    _getSession(sessionId, owner) {
+        const key = void 0 === sessionId ? HistoryManager.DEFAULT_SESSION : asSessionId(sessionId);
+        const existing = this._sessions.get(key);
+        if (void 0 !== existing) {
+            this._assertSessionOwner(key, existing, owner);
+            existing.lastAccessedAt = Date.now();
+            return existing;
+        }
+        return this._lifecycle.runMutation(key, ()=>this._getSessionWithinOperation(key, owner));
+    }
+    _getSessionWithinOperation(key, owner) {
+        let session = this._sessions.get(key);
+        if (session) this._assertSessionOwner(key, session, owner);
+        else {
+            this._makeCapacityForSession(owner);
+            session = this._createSessionState(owner);
+            this._sessions.set(key, session);
+        }
+        session.lastAccessedAt = Date.now();
+        return session;
+    }
+    _assertSessionOwner(sessionId, session, owner) {
+        if (void 0 === owner) return;
+        if ('restored' === session.provenance) throw new SessionAccessDeniedError(sessionId, 'unavailable', owner);
+        if (void 0 !== session.owner && session.owner !== owner) throw new SessionAccessDeniedError(sessionId, session.owner, owner);
+        if (void 0 === session.owner) session.owner = owner;
+    }
+    _makeCapacityForSession(owner) {
+        const victims = this._sessionManager.planProspectiveAdmission(this._sessions, owner, (sessionId)=>this._isCapacityEvictionEligible(sessionId));
+        if (void 0 === victims) throw new MaxSessionsReachedError(HistoryManager.MAX_SESSIONS);
+        if (0 === victims.length) return;
+        const evicted = this._lifecycle.tryEvictIdleSessions(victims, (sessionIds)=>{
+            if (sessionIds.some((sessionId)=>!this._isPersistenceQuiescent(sessionId))) throw new MaxSessionsReachedError(HistoryManager.MAX_SESSIONS);
+            for (const sessionId of sessionIds)this._removeLiveSession(sessionId);
+        });
+        if (!evicted) throw new MaxSessionsReachedError(HistoryManager.MAX_SESSIONS);
+    }
+    _isCapacityEvictionEligible(sessionId) {
+        return this._lifecycle.isIdle(sessionId) && this._isPersistenceQuiescent(sessionId);
+    }
+    _isTtlEvictionEligible(sessionId) {
+        const persistenceState = this._persistenceBuffer?.sessionEvictionState(sessionId) ?? 'quiescent';
+        return this._lifecycle.isIdle(sessionId) && 'failed' !== persistenceState && 'barrier' !== persistenceState;
+    }
+    _isPersistenceQuiescent(sessionId) {
+        return (this._persistenceBuffer?.sessionEvictionState(sessionId) ?? 'quiescent') === 'quiescent';
+    }
+    async _evictSessions(sessionIds) {
+        const results = await Promise.allSettled(sessionIds.map((sessionId)=>this._evictSession(sessionId)));
+        const failures = results.flatMap((result)=>'rejected' === result.status ? [
+                result.reason
+            ] : []);
+        if (failures.length > 0) throw new AggregateError(failures, 'Session eviction failed');
+    }
+    _evictSession(sessionId) {
+        return this._lifecycle.withSessionEviction(sessionId, async ()=>{
+            if (null === this._persistenceBuffer) return void this._removeLiveSession(sessionId);
+            const session = this._sessions.get(sessionId);
+            if (void 0 !== session) this._stageRestoreBranchReconciliation(sessionId, session);
+            await this._persistenceBuffer.withSessionEvictionBarrier(sessionId, async ()=>{
+                this._removeLiveSession(sessionId);
+            });
+        });
+    }
+    _removeLiveSession(sessionId) {
+        this._clearSessionAuxiliaryState?.(sessionId);
+        this._edgeStore?.clearSession(sessionId);
+        this._summaryStore?.clearSession(sessionId);
+        this._referenceIndex.clearSession(sessionId);
+        this._sessions.delete(sessionId);
+        this._persistenceBuffer?.forgetQuiescentSession(sessionId);
+    }
+    _createSessionState(owner, provenance) {
+        return {
+            thought_history: [],
+            branches: {},
+            availableMcpTools: void 0,
+            availableSkills: void 0,
+            writeBuffer: [],
+            lastAccessedAt: Date.now(),
+            branchIdentities: new Set(),
+            pendingRestoreBranchDeletes: new Set(),
+            owner,
+            provenance
+        };
+    }
+    _authorizeExistingSession(sessionId, owner) {
+        const sessionOwner = this._sessions.get(sessionId)?.owner;
+        if (void 0 !== owner && this._sessions.get(sessionId)?.provenance === 'restored') throw new SessionAccessDeniedError(sessionId, 'unavailable', owner);
+        if (void 0 !== owner && void 0 !== sessionOwner && sessionOwner !== owner) throw new SessionAccessDeniedError(sessionId, sessionOwner, owner);
+        return sessionOwner ?? owner;
+    }
+    _assertOwnerlessResetAll() {
+        const owner = this._getCurrentOwner();
+        if (void 0 === owner) return;
+        const firstSessionId = this._sessions.keys().next().value ?? HistoryManager.DEFAULT_SESSION;
+        throw new SessionAccessDeniedError(firstSessionId, 'trusted ownerless context', owner);
+    }
+    addThought(thought, context) {
+        const sessionId = asSessionId(thought.session_id ?? HistoryManager.DEFAULT_SESSION);
+        this._lifecycle.runMutation(sessionId, ()=>this._addThoughtWithinOperation(sessionId, thought, context));
+    }
+    _addThoughtWithinOperation(sessionId, thought, context) {
+        this._persistenceBuffer?.assertSessionAdmissionOpen(sessionId);
+        const owner = this._getCurrentOwner();
+        this._authorizeExistingSession(sessionId, owner);
+        const resolvedReferences = this._resolveAdmissionReferences(sessionId, thought, context);
+        const session = this._getSessionWithinOperation(sessionId, owner);
+        this._metrics?.counter('thought_requests_total', 1, {}, 'Total thought requests added to history');
+        session.thought_history.push(thought);
+        if (void 0 !== resolvedReferences.backtrackTargetThoughtId) this._applyRetraction(session, resolvedReferences.backtrackTargetThoughtId);
+        if (thought.available_mcp_tools) session.availableMcpTools = thought.available_mcp_tools;
+        if (thought.available_skills) session.availableSkills = thought.available_skills;
+        if (thought.branch_from_thought && thought.branch_id) this._addToSessionBranch(session, thought.branch_id, thought);
+        if (thought.merge_from_thoughts?.length || thought.merge_branch_ids?.length) this._metrics?.counter('thought_merge_operations_total', 1, {}, 'Total merge operations (graph topology)');
+        const edgeAdded = this._edgeEmitter.emitEdgesForThought(session, thought, {
+            ...context,
+            resolvedReferences
+        });
+        const evictedBranchIds = this._enforceRetention(session, thought.branch_id);
+        this._rebuildReferenceIndex(sessionId, session);
+        const prunedEdges = this._pruneUnretainedEdges(sessionId, session);
+        this._bufferRetainedState(sessionId, session, thought, evictedBranchIds, edgeAdded, prunedEdges);
+    }
+    _resolveAdmissionReferences(sessionId, thought, context) {
+        const resolved = context?.resolvedReferences ?? resolveThoughtReferencesForAdmission(thought, (thoughtNumber)=>this._referenceIndex.resolve(sessionId, thoughtNumber));
+        if ('backtrack' === thought.thought_type && void 0 !== thought.backtrack_target && void 0 === resolved.backtrackTargetThoughtId) throw new InvalidBacktrackError(`backtrack_target ${thought.backtrack_target} is missing in session history`);
+        return resolved;
+    }
+    _enforceRetention(session, branchId) {
+        if (session.thought_history.length > this._maxHistorySize) {
+            session.thought_history = session.thought_history.slice(-this._maxHistorySize);
+            this.log(`History trimmed to ${this._maxHistorySize} items`, {
+                maxSize: this._maxHistorySize
+            });
+        }
+        if (void 0 !== branchId) this._trimSessionBranchSize(session, branchId);
+        return this._cleanupSessionBranches(session);
+    }
+    _pruneUnretainedEdges(sessionId, session) {
+        if (void 0 === this._edgeStore) return 0;
+        const retainedIds = new Set();
+        const retainedBranchThoughtIds = new Set();
+        for (const thought of [
+            session.thought_history,
+            ...Object.values(session.branches)
+        ].flat())if (void 0 !== thought.id) retainedIds.add(thought.id);
+        for (const thought of Object.values(session.branches).flat())if (void 0 !== thought.id) retainedBranchThoughtIds.add(thought.id);
+        return this._edgeStore.pruneSession(sessionId, retainedIds, retainedBranchThoughtIds);
+    }
+    _bufferRetainedState(sessionId, session, thought, evictedBranchIds, edgeAdded, prunedEdges) {
+        const buffer = this._persistenceBuffer;
+        if (null === buffer) return;
+        buffer.bufferThought(sessionId, thought);
+        if (void 0 !== thought.branch_id || evictedBranchIds.length > 0 || session.pendingRestoreBranchDeletes.size > 0) this._stageBranchPersistence(sessionId, session, evictedBranchIds);
+        if (void 0 !== this._edgeStore && (edgeAdded || prunedEdges > 0)) buffer.bufferEdges(sessionId, this._edgeStore.edgesForSession(sessionId));
+    }
+    _stageAllRestoreBranchReconciliation() {
+        for (const [sessionId, session] of this._sessions)this._stageRestoreBranchReconciliation(sessionId, session);
+    }
+    _stageRestoreBranchReconciliation(sessionId, session) {
+        if (0 === session.pendingRestoreBranchDeletes.size) return;
+        this._stageBranchPersistence(sessionId, session, []);
+    }
+    _stageBranchPersistence(sessionId, session, ordinaryDeletes) {
+        const buffer = this._persistenceBuffer;
+        if (null === buffer) return;
+        for (const branchId of session.branchIdentities){
+            const branch = session.branches[branchId];
+            if (void 0 !== branch) buffer.bufferBranch(sessionId, branchId, branch);
+        }
+        const branchIdsToDelete = new Set([
+            ...session.pendingRestoreBranchDeletes,
+            ...ordinaryDeletes
+        ]);
+        for (const branchId of branchIdsToDelete)if (void 0 === session.branches[branchId]) buffer.deleteBranch(sessionId, branchId);
+        session.pendingRestoreBranchDeletes.clear();
+    }
+    _applyRetraction(session, targetId) {
+        for (const t of session.thought_history)if (t.id === targetId) t.retracted = true;
+        for (const branchThoughts of Object.values(session.branches))for (const t of branchThoughts)if (t.id === targetId) t.retracted = true;
+    }
+    _rebuildReferenceIndex(sessionId, session) {
+        const retained = [
+            session.thought_history,
+            ...Object.values(session.branches)
+        ].flat();
+        this._referenceIndex.replaceSession(sessionId, retained);
+    }
+    resolveThoughtReference(sessionId, thoughtNumber) {
+        this._authorizeExistingSession(sessionId, this._getCurrentOwner());
+        return this._referenceIndex.resolve(sessionId, thoughtNumber);
+    }
+    _addToSessionBranch(session, branchId, thought) {
+        if (!session.branches[branchId]) session.branches[branchId] = [];
+        session.branchIdentities.add(branchId);
+        session.branches[branchId].push(thought);
+    }
+    _cleanupSessionBranches(session) {
+        const branchCount = session.branchIdentities.size;
+        if (branchCount <= this._maxBranches) return [];
+        const identitiesToRemove = Array.from(session.branchIdentities).slice(0, branchCount - this._maxBranches);
+        const branchesToDelete = [];
+        for (const branchId of identitiesToRemove){
+            session.branchIdentities.delete(branchId);
+            if (void 0 !== session.branches[branchId]) branchesToDelete.push(branchId);
+            delete session.branches[branchId];
+            this.log(`Removed old branch: ${branchId}`, {
+                branchId
+            });
+        }
+        return branchesToDelete;
+    }
+    _trimSessionBranchSize(session, branchId) {
+        const branch = session.branches[branchId];
+        if (void 0 !== branch && branch.length > this._maxBranchSize) {
+            const removed = branch.length - this._maxBranchSize;
+            session.branches[branchId] = branch.slice(-this._maxBranchSize);
+            this.log(`Trimmed branch '${branchId}': removed ${removed} old thoughts`, {
+                branchId,
+                removed
+            });
+        }
+    }
+    getHistory(sessionId) {
+        return this._getSession(sessionId, this._getCurrentOwner()).thought_history;
+    }
+    getHistoryHydrated(sessionId, opts) {
+        const history = this.getHistory(sessionId);
+        if (!this._dagEdges || !this._summaryStore) return history.slice();
+        const sid = sessionId ?? HistoryManager.DEFAULT_SESSION;
+        const policy = new DehydrationPolicy(this._summaryStore);
+        return policy.apply(history, asSessionId(sid), opts);
+    }
+    getHistoryLength(sessionId) {
+        return this._getSession(sessionId, this._getCurrentOwner()).thought_history.length;
+    }
+    getBranches(sessionId) {
+        return this._getSession(sessionId, this._getCurrentOwner()).branches;
+    }
+    getBranchIds(sessionId) {
+        return Array.from(this._getSession(sessionId, this._getCurrentOwner()).branchIdentities);
+    }
+    inspectSession(sessionId) {
+        const canonicalSessionId = asSessionId(sessionId);
+        this._authorizeExistingSession(canonicalSessionId, this._getCurrentOwner());
+        const session = this._sessions.get(canonicalSessionId);
+        if (void 0 === session) return {
+            history: [],
+            branches: {},
+            branchIds: [],
+            availableMcpTools: void 0,
+            availableSkills: void 0
+        };
+        return {
+            history: [
+                ...session.thought_history
+            ],
+            branches: Object.fromEntries(Object.entries(session.branches).map(([branchId, thoughts])=>[
+                    branchId,
+                    [
+                        ...thoughts
+                    ]
+                ])),
+            branchIds: Array.from(session.branchIdentities),
+            availableMcpTools: void 0 === session.availableMcpTools ? void 0 : [
+                ...session.availableMcpTools
+            ],
+            availableSkills: void 0 === session.availableSkills ? void 0 : [
+                ...session.availableSkills
+            ]
+        };
+    }
+    registerBranch(sessionId, branchId) {
+        if ('string' != typeof branchId || 0 === branchId.length) throw new ValidationError('branch_id', 'branch_id must be a non-empty string');
+        const canonicalSessionId = asSessionId(sessionId ?? HistoryManager.DEFAULT_SESSION);
+        this._lifecycle.runMutation(canonicalSessionId, ()=>{
+            this._persistenceBuffer?.assertSessionAdmissionOpen(canonicalSessionId);
+            const session = this._getSessionWithinOperation(canonicalSessionId, this._getCurrentOwner());
+            if (session.branchIdentities.has(branchId)) throw new ValidationError('branch_id', `Branch already exists: ${branchId}`);
+            session.branchIdentities.add(branchId);
+            const evictedBranchIds = this._cleanupSessionBranches(session);
+            this._rebuildReferenceIndex(canonicalSessionId, session);
+            const prunedEdges = this._pruneUnretainedEdges(canonicalSessionId, session);
+            if (evictedBranchIds.length > 0 || session.pendingRestoreBranchDeletes.size > 0) this._stageBranchPersistence(canonicalSessionId, session, evictedBranchIds);
+            if (void 0 !== this._edgeStore && prunedEdges > 0) this._persistenceBuffer?.bufferEdges(canonicalSessionId, this._edgeStore.edgesForSession(canonicalSessionId));
+            this.log('Registered branch', {
+                branchId,
+                sessionId: sessionId ?? null
+            });
+        });
+    }
+    branchExists(sessionId, branchId) {
+        const session = this._getSession(sessionId, this._getCurrentOwner());
+        return session.branchIdentities.has(branchId);
+    }
+    getAvailableMcpTools(sessionId) {
+        return this._getSession(sessionId, this._getCurrentOwner()).availableMcpTools;
+    }
+    getAvailableSkills(sessionId) {
+        return this._getSession(sessionId, this._getCurrentOwner()).availableSkills;
+    }
+    getBranch(branchId, sessionId) {
+        return this._getSession(sessionId, this._getCurrentOwner()).branches[branchId];
+    }
+    clear(sessionId) {
+        if (void 0 !== sessionId) {
+            const canonicalSessionId = asSessionId(sessionId);
+            this._authorizeExistingSession(canonicalSessionId, this._getCurrentOwner());
+            if (this._sessionLock?.isActive(canonicalSessionId) === true) throw new AsyncResetRequiredError('session', canonicalSessionId, 'active');
+            this._resetCoordinator.clearSession(canonicalSessionId);
+            this._referenceIndex.clearSession(canonicalSessionId);
+            this._clearSessionAuxiliaryState?.(canonicalSessionId);
+            return;
+        }
+        this._assertOwnerlessResetAll();
+        if (void 0 !== this._sessionLock && this._sessionLock.size > 0) throw new AsyncResetRequiredError('all', void 0, 'active');
+        this._resetCoordinator.clearAll();
+        this._referenceIndex.clearAll();
+        this._clearAllAuxiliaryState?.();
+    }
+    async resetSession(sessionId, clearAuxiliaryState) {
+        const canonicalSessionId = asSessionId(sessionId);
+        this._authorizeExistingSession(canonicalSessionId, this._getCurrentOwner());
+        await this._lifecycle.withSessionReset(canonicalSessionId, async ()=>{
+            const reset = async ()=>await this.resetSessionWithinExclusive(canonicalSessionId, clearAuxiliaryState);
+            if (void 0 === this._sessionLock) return await reset();
+            await this._sessionLock.withLock(canonicalSessionId, reset);
+        });
+    }
+    async resetSessionWithinExclusive(sessionId, clearAuxiliaryState) {
+        const preservedOwner = this._authorizeExistingSession(sessionId, this._getCurrentOwner());
+        await this._resetCoordinator.resetSession(sessionId, preservedOwner, clearAuxiliaryState ?? (void 0 === this._clearSessionAuxiliaryState ? void 0 : ()=>this._clearSessionAuxiliaryState?.(sessionId)));
+        this._referenceIndex.clearSession(sessionId);
+    }
+    async resetAll(clearAuxiliaryState) {
+        this._assertOwnerlessResetAll();
+        await this._lifecycle.withGlobalReset(async ()=>await this.resetAllWithinExclusive(clearAuxiliaryState));
+    }
+    async resetAllWithinExclusive(clearAuxiliaryState) {
+        this._assertOwnerlessResetAll();
+        await this._resetCoordinator.resetAll(clearAuxiliaryState ?? this._clearAllAuxiliaryState);
+        this._referenceIndex.clearAll();
+    }
+    clearSession(sessionId) {
+        this.clear(sessionId);
+    }
+    getSessionIds() {
+        return Array.from(this._sessions.keys());
+    }
+    getSessionCount() {
+        return this._sessions.size;
+    }
+    _restoredState(restored) {
+        const session = this._createSessionState(void 0, 'restored');
+        for(let index = restored.history.length - 1; index >= 0; index--){
+            const thought = restored.history[index];
+            if (void 0 !== thought) {
+                if (void 0 === session.availableMcpTools && void 0 !== thought.available_mcp_tools) session.availableMcpTools = [
+                    ...thought.available_mcp_tools
+                ];
+                if (void 0 === session.availableSkills && void 0 !== thought.available_skills) session.availableSkills = [
+                    ...thought.available_skills
+                ];
+                if (void 0 !== session.availableMcpTools && void 0 !== session.availableSkills) break;
+            }
+        }
+        session.thought_history = restored.history.slice(-this._maxHistorySize);
+        const retainedStart = Math.max(0, restored.branches.length - this._maxBranches);
+        const retainedBranches = restored.branches.slice(retainedStart);
+        for (const branch of restored.branches.slice(0, retainedStart))session.pendingRestoreBranchDeletes.add(branch.branchId);
+        for (const branch of retainedBranches){
+            session.branchIdentities.add(branch.branchId);
+            session.branches[branch.branchId] = branch.thoughts.slice(-this._maxBranchSize);
+        }
+        return session;
+    }
+    async loadFromPersistence() {
+        if (!this._persistenceEnabled || !this._persistence) return;
+        const restored = await stagePersistenceRestore(this._persistence);
+        const sessions = restored.sessions.map((session)=>[
+                session.sessionId,
+                this._restoredState(session)
+            ]);
+        const referenceIndex = new ThoughtReferenceIndex();
+        const retainedThoughtIds = new Map();
+        const retainedBranchThoughtIds = new Map();
+        for (const [sessionId, session] of sessions){
+            const retained = [
+                session.thought_history,
+                ...Object.values(session.branches)
+            ].flat();
+            referenceIndex.replaceSession(sessionId, retained);
+            retainedThoughtIds.set(sessionId, new Set(retained.flatMap((thought)=>void 0 === thought.id ? [] : [
+                    thought.id
+                ])));
+            retainedBranchThoughtIds.set(sessionId, new Set(Object.values(session.branches).flatMap((branch)=>branch.flatMap((thought)=>void 0 === thought.id ? [] : [
+                        thought.id
+                    ]))));
+        }
+        this._edgeStore?.clearAll();
+        this._summaryStore?.clearAll();
+        this._sessions.clear();
+        for (const [sessionId, session] of sessions)this._sessions.set(sessionId, session);
+        this._referenceIndex = referenceIndex;
+        for (const session of restored.sessions){
+            const retainedIds = retainedThoughtIds.get(session.sessionId) ?? new Set();
+            const retainedBranchIds = retainedBranchThoughtIds.get(session.sessionId) ?? new Set();
+            for (const edge of session.edges)if (retainedIds.has(edge.from) && retainedIds.has(edge.to)) {
+                if ('branch' !== edge.kind || retainedBranchIds.has(edge.to)) this._edgeStore?.addEdge(edge);
+            }
+            for (const summary of session.summaries)this._summaryStore?.add(summary);
+        }
+        this.log(`Restored ${restored.sessions.length} persistence namespaces`);
+    }
+    isPersistenceEnabled() {
+        return this._persistenceEnabled;
+    }
+    getPersistenceBackend() {
+        return this._persistence;
+    }
+    setEventEmitter(emitter) {
+        this._eventEmitter = emitter;
+        this._persistenceBuffer?.setEventEmitter(emitter);
+    }
+    bindShutdownOwner(owner) {
+        if (null !== this._shutdownOwner) throw new TypeError('HistoryManager shutdown owner is already bound');
+        this._shutdownOwner = owner;
+    }
+    shutdown() {
+        if (null !== this._shutdownOwner) return this._shutdownOwner();
+        return this._lifecycle.shutdown(async ()=>{
+            await this.shutdownWithinLifecycle();
+            this.clearLiveStateAfterShutdown();
+        });
+    }
+    async shutdownWithinLifecycle() {
+        this._stopFlushTimer();
+        this._sessionManager.stopCleanupTimer();
+        await this._flushBuffer();
+    }
+    clearLiveStateAfterShutdown() {
+        for (const sessionId of this._sessions.keys())this._persistenceBuffer?.forgetQuiescentSession(sessionId);
+        this._sessions.clear();
+        this._referenceIndex.clearAll();
+        this._edgeStore?.clearAll();
+        this._summaryStore?.clearAll();
+        this._clearAllAuxiliaryState?.();
+    }
+    getWriteBufferLength() {
+        return this._persistenceBuffer?.pendingThoughtCount ?? 0;
+    }
+}
+export { ABSOLUTE_MAX_HISTORY_SIZE, HistoryManager };
+
+//# sourceMappingURL=HistoryManager.js.map