@iworkforces/tracelattice 2.0.3

package/dist/core/SessionErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/SessionErrors.js","sources":["../../src/core/SessionErrors.ts"],"sourcesContent":["import type { SessionId } from '../contracts/ids.js';\nimport { ERROR_CODES, SequentialThinkingError } from '../errors.js';\n\n/** Lifecycle phase that can close ordinary session admission. */\nexport type SessionLifecycleClosedPhase =\n\t| 'resetting'\n\t| 'reset_failed'\n\t| 'evicting'\n\t| 'eviction_failed'\n\t| 'shutting_down'\n\t| 'stopped'\n\t| 'shutdown_failed';\n\n/** Error thrown when an operation arrives after lifecycle admission has closed. */\nexport class SessionLifecycleClosedError extends SequentialThinkingError {\n\t/** Session whose admission is closed, or `undefined` for a global exclusive request. */\n\tpublic readonly sessionId: SessionId | undefined;\n\t/** Lifecycle phase that rejected admission. */\n\tpublic readonly phase: SessionLifecycleClosedPhase;\n\n\tpublic constructor(sessionId: SessionId | undefined, phase: SessionLifecycleClosedPhase) {\n\t\tconst scope = sessionId === undefined ? 'Global' : `Session '${sessionId}'`;\n\t\tsuper(\n\t\t\t`${scope} lifecycle admission is closed in phase '${phase}'`,\n\t\t\tERROR_CODES.SESSION_LIFECYCLE_CLOSED\n\t\t);\n\t\tthis.name = 'SessionLifecycleClosedError';\n\t\tthis.sessionId = sessionId;\n\t\tthis.phase = phase;\n\t}\n}\n\n/** Error thrown when a per-session async lock cannot be acquired in time. */\nexport class LockTimeoutError extends SequentialThinkingError {\n\tpublic readonly sessionId: SessionId;\n\tpublic readonly timeoutMs: number;\n\n\tconstructor(sessionId: SessionId, timeoutMs: number) {\n\t\tsuper(`Lock timeout for session '${sessionId}' after ${timeoutMs}ms`, ERROR_CODES.LOCK_TIMEOUT);\n\t\tthis.name = 'LockTimeoutError';\n\t\tthis.sessionId = sessionId;\n\t\tthis.timeoutMs = timeoutMs;\n\t}\n}\n\n/** Error thrown when a session is accessed by a non-owner. */\nexport class SessionAccessDeniedError extends SequentialThinkingError {\n\tpublic readonly sessionId: SessionId;\n\tpublic readonly expectedOwner: string;\n\tpublic readonly actualOwner: string | undefined;\n\n\tconstructor(sessionId: SessionId, expectedOwner: string, actualOwner?: string) {\n\t\tsuper(\n\t\t\t`Access denied to session '${sessionId}': owned by '${expectedOwner}', accessed by '${actualOwner ?? 'anonymous'}'`,\n\t\t\tERROR_CODES.SESSION_ACCESS_DENIED\n\t\t);\n\t\tthis.name = 'SessionAccessDeniedError';\n\t\tthis.sessionId = sessionId;\n\t\tthis.expectedOwner = expectedOwner;\n\t\tthis.actualOwner = actualOwner;\n\t}\n}\n\n/** Scope requested through the legacy synchronous clear API. */\nexport type AsyncResetScope = 'session' | 'all';\n\n/** Condition that makes the legacy synchronous clear API unsafe. */\nexport type AsyncResetReason = 'persistent' | 'active';\n\n/** Error raised when state requires the awaitable reset API. */\nexport class AsyncResetRequiredError extends SequentialThinkingError {\n\tpublic readonly scope: AsyncResetScope;\n\tpublic readonly sessionId: SessionId | undefined;\n\tpublic readonly reason: AsyncResetReason;\n\n\tconstructor(\n\t\tscope: AsyncResetScope,\n\t\tsessionId?: SessionId,\n\t\treason: AsyncResetReason = 'persistent'\n\t) {\n\t\tconst target = scope === 'session' ? `session '${sessionId}'` : 'all sessions';\n\t\tsuper(\n\t\t\t`Synchronous clear cannot reset ${reason} ${target}; use the awaitable ${scope === 'session' ? 'resetSession()' : 'resetAll()'} API`,\n\t\t\tERROR_CODES.ASYNC_RESET_REQUIRED\n\t\t);\n\t\tthis.name = 'AsyncResetRequiredError';\n\t\tthis.scope = scope;\n\t\tthis.sessionId = sessionId;\n\t\tthis.reason = reason;\n\t}\n}\n"],"names":["SessionLifecycleClosedError","SequentialThinkingError","sessionId","phase","scope","undefined","ERROR_CODES","LockTimeoutError","timeoutMs","SessionAccessDeniedError","expectedOwner","actualOwner","AsyncResetRequiredError","reason","target"],"mappings":";AAcO,MAAMA,oCAAoCC;IAEhC,UAAiC;IAEjC,MAAmC;IAEnD,YAAmBC,SAAgC,EAAEC,KAAkC,CAAE;QACxF,MAAMC,QAAQF,AAAcG,WAAdH,YAA0B,WAAW,CAAC,SAAS,EAAEA,UAAU,CAAC,CAAC;QAC3E,KAAK,CACJ,GAAGE,MAAM,yCAAyC,EAAED,MAAM,CAAC,CAAC,EAC5DG,YAAY,wBAAwB;QAErC,IAAI,CAAC,IAAI,GAAG;QACZ,IAAI,CAAC,SAAS,GAAGJ;QACjB,IAAI,CAAC,KAAK,GAAGC;IACd;AACD;AAGO,MAAMI,yBAAyBN;IACrB,UAAqB;IACrB,UAAkB;IAElC,YAAYC,SAAoB,EAAEM,SAAiB,CAAE;QACpD,KAAK,CAAC,CAAC,0BAA0B,EAAEN,UAAU,QAAQ,EAAEM,UAAU,EAAE,CAAC,EAAEF,YAAY,YAAY;QAC9F,IAAI,CAAC,IAAI,GAAG;QACZ,IAAI,CAAC,SAAS,GAAGJ;QACjB,IAAI,CAAC,SAAS,GAAGM;IAClB;AACD;AAGO,MAAMC,iCAAiCR;IAC7B,UAAqB;IACrB,cAAsB;IACtB,YAAgC;IAEhD,YAAYC,SAAoB,EAAEQ,aAAqB,EAAEC,WAAoB,CAAE;QAC9E,KAAK,CACJ,CAAC,0BAA0B,EAAET,UAAU,aAAa,EAAEQ,cAAc,gBAAgB,EAAEC,eAAe,YAAY,CAAC,CAAC,EACnHL,YAAY,qBAAqB;QAElC,IAAI,CAAC,IAAI,GAAG;QACZ,IAAI,CAAC,SAAS,GAAGJ;QACjB,IAAI,CAAC,aAAa,GAAGQ;QACrB,IAAI,CAAC,WAAW,GAAGC;IACpB;AACD;AASO,MAAMC,gCAAgCX;IAC5B,MAAuB;IACvB,UAAiC;IACjC,OAAyB;IAEzC,YACCG,KAAsB,EACtBF,SAAqB,EACrBW,SAA2B,YAAY,CACtC;QACD,MAAMC,SAASV,AAAU,cAAVA,QAAsB,CAAC,SAAS,EAAEF,UAAU,CAAC,CAAC,GAAG;QAChE,KAAK,CACJ,CAAC,+BAA+B,EAAEW,OAAO,CAAC,EAAEC,OAAO,oBAAoB,EAAEV,AAAU,cAAVA,QAAsB,mBAAmB,aAAa,IAAI,CAAC,EACpIE,YAAY,oBAAoB;QAEjC,IAAI,CAAC,IAAI,GAAG;QACZ,IAAI,CAAC,KAAK,GAAGF;QACb,IAAI,CAAC,SAAS,GAAGF;QACjB,IAAI,CAAC,MAAM,GAAGW;IACf;AACD"}

package/dist/core/SessionLifecycleCoordinator.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Core-local admission and exclusive lifecycle coordination.
+ *
+ * @module SessionLifecycleCoordinator
+ */
+import type { SessionId } from '../contracts/ids.js';
+/** Global lifecycle phases owned by the coordinator. */
+export type GlobalLifecyclePhase = 'open' | 'resetting' | 'reset_failed' | 'shutting_down' | 'stopped' | 'shutdown_failed';
+/** Per-session lifecycle phases owned by the coordinator. */
+export type SessionLifecyclePhase = 'open' | 'resetting' | 'reset_failed' | 'evicting' | 'eviction_failed';
+/** Options for retrying a failed session eviction. */
+export interface SessionEvictionOptions {
+    readonly retryFailed: boolean;
+}
+/**
+ * Linearizes operation admission before external session locking and owns lifecycle exclusives.
+ *
+ * @example
+ * ```ts
+ * const lifecycle = new SessionLifecycleCoordinator();
+ * await lifecycle.runOperation(sessionId, () => sessionLock.withLock(sessionId, operation));
+ * ```
+ */
+export declare class SessionLifecycleCoordinator {
+    private readonly _sessions;
+    private readonly _context;
+    private readonly _sessionIdleWaiters;
+    private readonly _globalIdleWaiters;
+    private _globalPhase;
+    private _activeOperations;
+    private _maintenanceOwners;
+    private _shutdownPromise;
+    /** @returns The current global lifecycle phase. */
+    get globalPhase(): GlobalLifecyclePhase;
+    /** @returns Whether any session lifecycle exclusive is active. */
+    get hasMaintenance(): boolean;
+    /** @returns The current phase for a session, defaulting to `open`. */
+    phaseFor(sessionId: SessionId): SessionLifecyclePhase;
+    /** @returns Whether a session is open and has no admitted operation. */
+    isIdle(sessionId: SessionId): boolean;
+    /** Admits an asynchronous operation synchronously and releases it in `finally`. */
+    runOperation<T>(sessionId: SessionId, operation: () => Promise<T>): Promise<T>;
+    /** Guards direct synchronous mutation, reusing a valid owning lifecycle context. */
+    runMutation<T>(sessionId: SessionId, mutation: () => T): T;
+    /** Closes one session for reset and permits retry only from `reset_failed`. */
+    withSessionReset<T>(sessionId: SessionId, operation: () => Promise<T>): Promise<T>;
+    /** Closes one session for eviction, optionally retrying `eviction_failed`. */
+    withSessionEviction<T>(sessionId: SessionId, operation: () => Promise<T>, options?: SessionEvictionOptions): Promise<T>;
+    /** Closes global admission for a reset and permits retry from `reset_failed`. */
+    withGlobalReset<T>(operation: () => Promise<T>): Promise<T>;
+    /** Closes admission once and returns the same shutdown settlement to every caller. */
+    shutdown(operation: () => Promise<void>): Promise<void>;
+    /**
+     * Atomically claims and removes a complete already-idle candidate set.
+     *
+     * @returns `false` without invoking cleanup when any candidate is not idle.
+     */
+    tryEvictIdleSessions(sessionIds: readonly SessionId[], operation: (sessionIds: readonly SessionId[]) => void): boolean;
+    private _startSessionExclusive;
+    private _runSessionExclusive;
+    private _runGlobalReset;
+    private _runShutdown;
+    private _state;
+    private _admissionError;
+    private _admit;
+    private _release;
+    private _waitSessionIdle;
+    private _waitGlobalIdle;
+    private _notifyGlobalIdle;
+    private _contextOwnsSession;
+    private _upgradeError;
+    private _globalUpgradeError;
+}
+//# sourceMappingURL=SessionLifecycleCoordinator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SessionLifecycleCoordinator.d.ts","sourceRoot":"","sources":["../../src/core/SessionLifecycleCoordinator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGrD,wDAAwD;AACxD,MAAM,MAAM,oBAAoB,GAC/B,MAAM,GAAG,WAAW,GAAG,cAAc,GAAG,eAAe,GAAG,SAAS,GAAG,iBAAiB,CAAC;AAEzF,6DAA6D;AAC7D,MAAM,MAAM,qBAAqB,GAChC,MAAM,GAAG,WAAW,GAAG,cAAc,GAAG,UAAU,GAAG,iBAAiB,CAAC;AAExE,sDAAsD;AACtD,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC9B;AAoBD;;;;;;;;GAQG;AACH,qBAAa,2BAA2B;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsC;IAChE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6C;IACtE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAyC;IAC7E,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAyB;IAC5D,OAAO,CAAC,YAAY,CAAgC;IACpD,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,gBAAgB,CAA8B;IAEtD,mDAAmD;IACnD,IAAW,WAAW,IAAI,oBAAoB,CAE7C;IAED,kEAAkE;IAClE,IAAW,cAAc,IAAI,OAAO,CAEnC;IAED,sEAAsE;IAC/D,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,qBAAqB;IAI5D,wEAAwE;IACjE,MAAM,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO;IAK5C,mFAAmF;IAC5E,YAAY,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAarF,oFAAoF;IAC7E,WAAW,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC;IAYjE,+EAA+E;IACxE,gBAAgB,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIzF,8EAA8E;IACvE,mBAAmB,CAAC,CAAC,EAC3B,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,sBAA+C,GACtD,OAAO,CAAC,CAAC,CAAC;IASb,iFAAiF;IAC1E,eAAe,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAUlE,sFAAsF;IAC/E,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAa9D;;;;OAIG;IACI,oBAAoB,CAC1B,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,SAAS,EAAE,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,KAAK,IAAI,GACnD,OAAO;IAoBV,OAAO,CAAC,sBAAsB;YAuChB,oBAAoB;YAmBpB,eAAe;YAaf,YAAY;IAW1B,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,MAAM;IAKd,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,mBAAmB;CAG3B"}

package/dist/core/SessionLifecycleCoordinator.js

@@ -0,0 +1,222 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { SessionLifecycleClosedError } from "./SessionErrors.js";
+const RESET_EXCLUSIVE = {
+    active: 'resetting',
+    failed: 'reset_failed'
+};
+const EVICTION_EXCLUSIVE = {
+    active: 'evicting',
+    failed: 'eviction_failed'
+};
+class SessionLifecycleCoordinator {
+    _sessions = new Map();
+    _context = new AsyncLocalStorage();
+    _sessionIdleWaiters = new Map();
+    _globalIdleWaiters = new Set();
+    _globalPhase = 'open';
+    _activeOperations = 0;
+    _maintenanceOwners = 0;
+    _shutdownPromise = null;
+    get globalPhase() {
+        return this._globalPhase;
+    }
+    get hasMaintenance() {
+        return this._maintenanceOwners > 0;
+    }
+    phaseFor(sessionId) {
+        return this._sessions.get(sessionId)?.phase ?? 'open';
+    }
+    isIdle(sessionId) {
+        const state = this._sessions.get(sessionId);
+        return void 0 === state || 'open' === state.phase && 0 === state.activeOperations;
+    }
+    runOperation(sessionId, operation) {
+        const admissionError = this._admissionError(sessionId);
+        if (void 0 !== admissionError) return Promise.reject(admissionError);
+        this._admit(sessionId);
+        return this._context.run({
+            kind: 'operation',
+            sessionId
+        }, async ()=>{
+            try {
+                return await operation();
+            } finally{
+                this._release(sessionId);
+            }
+        });
+    }
+    runMutation(sessionId, mutation) {
+        if (this._contextOwnsSession(sessionId)) return mutation();
+        const admissionError = this._admissionError(sessionId);
+        if (void 0 !== admissionError) throw admissionError;
+        this._admit(sessionId);
+        try {
+            return this._context.run({
+                kind: 'operation',
+                sessionId
+            }, mutation);
+        } finally{
+            this._release(sessionId);
+        }
+    }
+    withSessionReset(sessionId, operation) {
+        return this._startSessionExclusive(sessionId, RESET_EXCLUSIVE, operation, true);
+    }
+    withSessionEviction(sessionId, operation, options = {
+        retryFailed: false
+    }) {
+        return this._startSessionExclusive(sessionId, EVICTION_EXCLUSIVE, operation, options.retryFailed);
+    }
+    withGlobalReset(operation) {
+        const context = this._context.getStore();
+        if (void 0 !== context) return Promise.reject(this._globalUpgradeError('global reset'));
+        if ('open' !== this._globalPhase && 'reset_failed' !== this._globalPhase) return Promise.reject(new SessionLifecycleClosedError(void 0, this._globalPhase));
+        this._globalPhase = 'resetting';
+        return this._runGlobalReset(operation);
+    }
+    shutdown(operation) {
+        if (null !== this._shutdownPromise) return this._shutdownPromise;
+        const context = this._context.getStore();
+        if (void 0 !== context) return Promise.reject(this._globalUpgradeError('shutdown'));
+        if ('open' !== this._globalPhase && 'reset_failed' !== this._globalPhase) return Promise.reject(new SessionLifecycleClosedError(void 0, this._globalPhase));
+        this._globalPhase = 'shutting_down';
+        const settlement = this._runShutdown(operation);
+        this._shutdownPromise = settlement;
+        return settlement;
+    }
+    tryEvictIdleSessions(sessionIds, operation) {
+        if ('open' !== this._globalPhase || sessionIds.some((sessionId)=>!this.isIdle(sessionId))) return false;
+        const uniqueIds = [
+            ...new Set(sessionIds)
+        ];
+        for (const sessionId of uniqueIds)this._state(sessionId).phase = 'evicting';
+        this._maintenanceOwners += 1;
+        try {
+            operation(uniqueIds);
+            for (const sessionId of uniqueIds)this._sessions.delete(sessionId);
+            return true;
+        } catch (error) {
+            for (const sessionId of uniqueIds)this._state(sessionId).phase = 'eviction_failed';
+            throw error;
+        } finally{
+            this._maintenanceOwners -= 1;
+            this._notifyGlobalIdle();
+        }
+    }
+    _startSessionExclusive(sessionId, exclusive, operation, allowFailedRetry) {
+        const context = this._context.getStore();
+        if (context?.kind === 'session_exclusive' && context.sessionId === sessionId && this.phaseFor(sessionId) === exclusive.active) return operation();
+        if (context?.kind === 'operation') return Promise.reject(this._upgradeError('resetting' === exclusive.active ? 'reset' : 'eviction', sessionId));
+        if (void 0 !== context && !this._contextOwnsSession(sessionId)) return Promise.reject(this._globalUpgradeError(`session ${'resetting' === exclusive.active ? 'reset' : 'eviction'}`));
+        const state = this._state(sessionId);
+        const retrying = state.phase === exclusive.failed && allowFailedRetry;
+        if ('open' !== this._globalPhase) return Promise.reject(new SessionLifecycleClosedError(sessionId, this._globalPhase));
+        if ('open' !== state.phase && !retrying) return Promise.reject(new SessionLifecycleClosedError(sessionId, state.phase));
+        state.phase = exclusive.active;
+        this._maintenanceOwners += 1;
+        return this._runSessionExclusive(sessionId, exclusive, operation);
+    }
+    async _runSessionExclusive(sessionId, exclusive, operation) {
+        try {
+            await this._waitSessionIdle(sessionId);
+            const result = await this._context.run({
+                kind: 'session_exclusive',
+                sessionId
+            }, operation);
+            this._sessions.delete(sessionId);
+            return result;
+        } catch (error) {
+            this._state(sessionId).phase = exclusive.failed;
+            throw error;
+        } finally{
+            this._maintenanceOwners -= 1;
+            this._notifyGlobalIdle();
+        }
+    }
+    async _runGlobalReset(operation) {
+        try {
+            await this._waitGlobalIdle();
+            const result = await this._context.run({
+                kind: 'global_exclusive'
+            }, operation);
+            this._sessions.clear();
+            this._globalPhase = 'open';
+            return result;
+        } catch (error) {
+            this._globalPhase = 'reset_failed';
+            throw error;
+        }
+    }
+    async _runShutdown(operation) {
+        try {
+            await this._waitGlobalIdle();
+            await this._context.run({
+                kind: 'global_exclusive'
+            }, operation);
+            this._globalPhase = 'stopped';
+        } catch (error) {
+            this._globalPhase = 'shutdown_failed';
+            throw error;
+        }
+    }
+    _state(sessionId) {
+        const state = this._sessions.get(sessionId) ?? {
+            phase: 'open',
+            activeOperations: 0
+        };
+        this._sessions.set(sessionId, state);
+        return state;
+    }
+    _admissionError(sessionId) {
+        if ('open' !== this._globalPhase) return new SessionLifecycleClosedError(sessionId, this._globalPhase);
+        const phase = this.phaseFor(sessionId);
+        return 'open' === phase ? void 0 : new SessionLifecycleClosedError(sessionId, phase);
+    }
+    _admit(sessionId) {
+        this._state(sessionId).activeOperations += 1;
+        this._activeOperations += 1;
+    }
+    _release(sessionId) {
+        const state = this._state(sessionId);
+        state.activeOperations -= 1;
+        this._activeOperations -= 1;
+        if (0 === state.activeOperations) {
+            const waiters = this._sessionIdleWaiters.get(sessionId);
+            this._sessionIdleWaiters.delete(sessionId);
+            for (const resolve of waiters ?? [])resolve();
+        }
+        this._notifyGlobalIdle();
+    }
+    _waitSessionIdle(sessionId) {
+        if (0 === this._state(sessionId).activeOperations) return Promise.resolve();
+        const result = Promise.withResolvers();
+        const waiters = this._sessionIdleWaiters.get(sessionId) ?? new Set();
+        waiters.add(result.resolve);
+        this._sessionIdleWaiters.set(sessionId, waiters);
+        return result.promise;
+    }
+    _waitGlobalIdle() {
+        if (0 === this._activeOperations && 0 === this._maintenanceOwners) return Promise.resolve();
+        const result = Promise.withResolvers();
+        this._globalIdleWaiters.add(result.resolve);
+        return result.promise;
+    }
+    _notifyGlobalIdle() {
+        if (0 !== this._activeOperations || 0 !== this._maintenanceOwners) return;
+        for (const resolve of this._globalIdleWaiters)resolve();
+        this._globalIdleWaiters.clear();
+    }
+    _contextOwnsSession(sessionId) {
+        const context = this._context.getStore();
+        return context?.kind === 'global_exclusive' || context?.sessionId === sessionId;
+    }
+    _upgradeError(mode, sessionId) {
+        return new TypeError(`Cannot upgrade an admitted operation for session '${sessionId}' to ${mode}`);
+    }
+    _globalUpgradeError(mode) {
+        return new TypeError(`Cannot upgrade an active lifecycle context to ${mode}`);
+    }
+}
+export { SessionLifecycleCoordinator };
+
+//# sourceMappingURL=SessionLifecycleCoordinator.js.map

package/dist/core/SessionLifecycleCoordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/SessionLifecycleCoordinator.js","sources":["../../src/core/SessionLifecycleCoordinator.ts"],"sourcesContent":["/**\n * Core-local admission and exclusive lifecycle coordination.\n *\n * @module SessionLifecycleCoordinator\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\nimport type { SessionId } from '../contracts/ids.js';\nimport { SessionLifecycleClosedError } from './SessionErrors.js';\n\n/** Global lifecycle phases owned by the coordinator. */\nexport type GlobalLifecyclePhase =\n\t'open' | 'resetting' | 'reset_failed' | 'shutting_down' | 'stopped' | 'shutdown_failed';\n\n/** Per-session lifecycle phases owned by the coordinator. */\nexport type SessionLifecyclePhase =\n\t'open' | 'resetting' | 'reset_failed' | 'evicting' | 'eviction_failed';\n\n/** Options for retrying a failed session eviction. */\nexport interface SessionEvictionOptions {\n\treadonly retryFailed: boolean;\n}\n\ntype SessionState = {\n\tphase: SessionLifecyclePhase;\n\tactiveOperations: number;\n};\n\ntype LifecycleContext =\n\t| { readonly kind: 'operation'; readonly sessionId: SessionId }\n\t| { readonly kind: 'session_exclusive'; readonly sessionId: SessionId }\n\t| { readonly kind: 'global_exclusive' };\n\ntype SessionExclusive = {\n\treadonly active: 'resetting' | 'evicting';\n\treadonly failed: 'reset_failed' | 'eviction_failed';\n};\n\nconst RESET_EXCLUSIVE: SessionExclusive = { active: 'resetting', failed: 'reset_failed' };\nconst EVICTION_EXCLUSIVE: SessionExclusive = { active: 'evicting', failed: 'eviction_failed' };\n\n/**\n * Linearizes operation admission before external session locking and owns lifecycle exclusives.\n *\n * @example\n * ```ts\n * const lifecycle = new SessionLifecycleCoordinator();\n * await lifecycle.runOperation(sessionId, () => sessionLock.withLock(sessionId, operation));\n * ```\n */\nexport class SessionLifecycleCoordinator {\n\tprivate readonly _sessions = new Map<SessionId, SessionState>();\n\tprivate readonly _context = new AsyncLocalStorage<LifecycleContext>();\n\tprivate readonly _sessionIdleWaiters = new Map<SessionId, Set<() => void>>();\n\tprivate readonly _globalIdleWaiters = new Set<() => void>();\n\tprivate _globalPhase: GlobalLifecyclePhase = 'open';\n\tprivate _activeOperations = 0;\n\tprivate _maintenanceOwners = 0;\n\tprivate _shutdownPromise: Promise<void> | null = null;\n\n\t/** @returns The current global lifecycle phase. */\n\tpublic get globalPhase(): GlobalLifecyclePhase {\n\t\treturn this._globalPhase;\n\t}\n\n\t/** @returns Whether any session lifecycle exclusive is active. */\n\tpublic get hasMaintenance(): boolean {\n\t\treturn this._maintenanceOwners > 0;\n\t}\n\n\t/** @returns The current phase for a session, defaulting to `open`. */\n\tpublic phaseFor(sessionId: SessionId): SessionLifecyclePhase {\n\t\treturn this._sessions.get(sessionId)?.phase ?? 'open';\n\t}\n\n\t/** @returns Whether a session is open and has no admitted operation. */\n\tpublic isIdle(sessionId: SessionId): boolean {\n\t\tconst state = this._sessions.get(sessionId);\n\t\treturn state === undefined || (state.phase === 'open' && state.activeOperations === 0);\n\t}\n\n\t/** Admits an asynchronous operation synchronously and releases it in `finally`. */\n\tpublic runOperation<T>(sessionId: SessionId, operation: () => Promise<T>): Promise<T> {\n\t\tconst admissionError = this._admissionError(sessionId);\n\t\tif (admissionError !== undefined) return Promise.reject(admissionError);\n\t\tthis._admit(sessionId);\n\t\treturn this._context.run({ kind: 'operation', sessionId }, async () => {\n\t\t\ttry {\n\t\t\t\treturn await operation();\n\t\t\t} finally {\n\t\t\t\tthis._release(sessionId);\n\t\t\t}\n\t\t});\n\t}\n\n\t/** Guards direct synchronous mutation, reusing a valid owning lifecycle context. */\n\tpublic runMutation<T>(sessionId: SessionId, mutation: () => T): T {\n\t\tif (this._contextOwnsSession(sessionId)) return mutation();\n\t\tconst admissionError = this._admissionError(sessionId);\n\t\tif (admissionError !== undefined) throw admissionError;\n\t\tthis._admit(sessionId);\n\t\ttry {\n\t\t\treturn this._context.run({ kind: 'operation', sessionId }, mutation);\n\t\t} finally {\n\t\t\tthis._release(sessionId);\n\t\t}\n\t}\n\n\t/** Closes one session for reset and permits retry only from `reset_failed`. */\n\tpublic withSessionReset<T>(sessionId: SessionId, operation: () => Promise<T>): Promise<T> {\n\t\treturn this._startSessionExclusive(sessionId, RESET_EXCLUSIVE, operation, true);\n\t}\n\n\t/** Closes one session for eviction, optionally retrying `eviction_failed`. */\n\tpublic withSessionEviction<T>(\n\t\tsessionId: SessionId,\n\t\toperation: () => Promise<T>,\n\t\toptions: SessionEvictionOptions = { retryFailed: false }\n\t): Promise<T> {\n\t\treturn this._startSessionExclusive(\n\t\t\tsessionId,\n\t\t\tEVICTION_EXCLUSIVE,\n\t\t\toperation,\n\t\t\toptions.retryFailed\n\t\t);\n\t}\n\n\t/** Closes global admission for a reset and permits retry from `reset_failed`. */\n\tpublic withGlobalReset<T>(operation: () => Promise<T>): Promise<T> {\n\t\tconst context = this._context.getStore();\n\t\tif (context !== undefined) return Promise.reject(this._globalUpgradeError('global reset'));\n\t\tif (this._globalPhase !== 'open' && this._globalPhase !== 'reset_failed') {\n\t\t\treturn Promise.reject(new SessionLifecycleClosedError(undefined, this._globalPhase));\n\t\t}\n\t\tthis._globalPhase = 'resetting';\n\t\treturn this._runGlobalReset(operation);\n\t}\n\n\t/** Closes admission once and returns the same shutdown settlement to every caller. */\n\tpublic shutdown(operation: () => Promise<void>): Promise<void> {\n\t\tif (this._shutdownPromise !== null) return this._shutdownPromise;\n\t\tconst context = this._context.getStore();\n\t\tif (context !== undefined) return Promise.reject(this._globalUpgradeError('shutdown'));\n\t\tif (this._globalPhase !== 'open' && this._globalPhase !== 'reset_failed') {\n\t\t\treturn Promise.reject(new SessionLifecycleClosedError(undefined, this._globalPhase));\n\t\t}\n\t\tthis._globalPhase = 'shutting_down';\n\t\tconst settlement = this._runShutdown(operation);\n\t\tthis._shutdownPromise = settlement;\n\t\treturn settlement;\n\t}\n\n\t/**\n\t * Atomically claims and removes a complete already-idle candidate set.\n\t *\n\t * @returns `false` without invoking cleanup when any candidate is not idle.\n\t */\n\tpublic tryEvictIdleSessions(\n\t\tsessionIds: readonly SessionId[],\n\t\toperation: (sessionIds: readonly SessionId[]) => void\n\t): boolean {\n\t\tif (this._globalPhase !== 'open' || sessionIds.some((sessionId) => !this.isIdle(sessionId))) {\n\t\t\treturn false;\n\t\t}\n\t\tconst uniqueIds = [...new Set(sessionIds)];\n\t\tfor (const sessionId of uniqueIds) this._state(sessionId).phase = 'evicting';\n\t\tthis._maintenanceOwners += 1;\n\t\ttry {\n\t\t\toperation(uniqueIds);\n\t\t\tfor (const sessionId of uniqueIds) this._sessions.delete(sessionId);\n\t\t\treturn true;\n\t\t} catch (error) {\n\t\t\tfor (const sessionId of uniqueIds) this._state(sessionId).phase = 'eviction_failed';\n\t\t\tthrow error;\n\t\t} finally {\n\t\t\tthis._maintenanceOwners -= 1;\n\t\t\tthis._notifyGlobalIdle();\n\t\t}\n\t}\n\n\tprivate _startSessionExclusive<T>(\n\t\tsessionId: SessionId,\n\t\texclusive: SessionExclusive,\n\t\toperation: () => Promise<T>,\n\t\tallowFailedRetry: boolean\n\t): Promise<T> {\n\t\tconst context = this._context.getStore();\n\t\tif (\n\t\t\tcontext?.kind === 'session_exclusive' &&\n\t\t\tcontext.sessionId === sessionId &&\n\t\t\tthis.phaseFor(sessionId) === exclusive.active\n\t\t) {\n\t\t\treturn operation();\n\t\t}\n\t\tif (context?.kind === 'operation') {\n\t\t\treturn Promise.reject(\n\t\t\t\tthis._upgradeError(exclusive.active === 'resetting' ? 'reset' : 'eviction', sessionId)\n\t\t\t);\n\t\t}\n\t\tif (context !== undefined && !this._contextOwnsSession(sessionId)) {\n\t\t\treturn Promise.reject(\n\t\t\t\tthis._globalUpgradeError(\n\t\t\t\t\t`session ${exclusive.active === 'resetting' ? 'reset' : 'eviction'}`\n\t\t\t\t)\n\t\t\t);\n\t\t}\n\t\tconst state = this._state(sessionId);\n\t\tconst retrying = state.phase === exclusive.failed && allowFailedRetry;\n\t\tif (this._globalPhase !== 'open') {\n\t\t\treturn Promise.reject(new SessionLifecycleClosedError(sessionId, this._globalPhase));\n\t\t}\n\t\tif (state.phase !== 'open' && !retrying) {\n\t\t\treturn Promise.reject(new SessionLifecycleClosedError(sessionId, state.phase));\n\t\t}\n\t\tstate.phase = exclusive.active;\n\t\tthis._maintenanceOwners += 1;\n\t\treturn this._runSessionExclusive(sessionId, exclusive, operation);\n\t}\n\n\tprivate async _runSessionExclusive<T>(\n\t\tsessionId: SessionId,\n\t\texclusive: SessionExclusive,\n\t\toperation: () => Promise<T>\n\t): Promise<T> {\n\t\ttry {\n\t\t\tawait this._waitSessionIdle(sessionId);\n\t\t\tconst result = await this._context.run({ kind: 'session_exclusive', sessionId }, operation);\n\t\t\tthis._sessions.delete(sessionId);\n\t\t\treturn result;\n\t\t} catch (error) {\n\t\t\tthis._state(sessionId).phase = exclusive.failed;\n\t\t\tthrow error;\n\t\t} finally {\n\t\t\tthis._maintenanceOwners -= 1;\n\t\t\tthis._notifyGlobalIdle();\n\t\t}\n\t}\n\n\tprivate async _runGlobalReset<T>(operation: () => Promise<T>): Promise<T> {\n\t\ttry {\n\t\t\tawait this._waitGlobalIdle();\n\t\t\tconst result = await this._context.run({ kind: 'global_exclusive' }, operation);\n\t\t\tthis._sessions.clear();\n\t\t\tthis._globalPhase = 'open';\n\t\t\treturn result;\n\t\t} catch (error) {\n\t\t\tthis._globalPhase = 'reset_failed';\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\tprivate async _runShutdown(operation: () => Promise<void>): Promise<void> {\n\t\ttry {\n\t\t\tawait this._waitGlobalIdle();\n\t\t\tawait this._context.run({ kind: 'global_exclusive' }, operation);\n\t\t\tthis._globalPhase = 'stopped';\n\t\t} catch (error) {\n\t\t\tthis._globalPhase = 'shutdown_failed';\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\tprivate _state(sessionId: SessionId): SessionState {\n\t\tconst state = this._sessions.get(sessionId) ?? { phase: 'open', activeOperations: 0 };\n\t\tthis._sessions.set(sessionId, state);\n\t\treturn state;\n\t}\n\n\tprivate _admissionError(sessionId: SessionId): SessionLifecycleClosedError | undefined {\n\t\tif (this._globalPhase !== 'open') {\n\t\t\treturn new SessionLifecycleClosedError(sessionId, this._globalPhase);\n\t\t}\n\t\tconst phase = this.phaseFor(sessionId);\n\t\treturn phase === 'open' ? undefined : new SessionLifecycleClosedError(sessionId, phase);\n\t}\n\n\tprivate _admit(sessionId: SessionId): void {\n\t\tthis._state(sessionId).activeOperations += 1;\n\t\tthis._activeOperations += 1;\n\t}\n\n\tprivate _release(sessionId: SessionId): void {\n\t\tconst state = this._state(sessionId);\n\t\tstate.activeOperations -= 1;\n\t\tthis._activeOperations -= 1;\n\t\tif (state.activeOperations === 0) {\n\t\t\tconst waiters = this._sessionIdleWaiters.get(sessionId);\n\t\t\tthis._sessionIdleWaiters.delete(sessionId);\n\t\t\tfor (const resolve of waiters ?? []) resolve();\n\t\t}\n\t\tthis._notifyGlobalIdle();\n\t}\n\n\tprivate _waitSessionIdle(sessionId: SessionId): Promise<void> {\n\t\tif (this._state(sessionId).activeOperations === 0) return Promise.resolve();\n\t\tconst result = Promise.withResolvers<void>();\n\t\tconst waiters = this._sessionIdleWaiters.get(sessionId) ?? new Set<() => void>();\n\t\twaiters.add(result.resolve);\n\t\tthis._sessionIdleWaiters.set(sessionId, waiters);\n\t\treturn result.promise;\n\t}\n\n\tprivate _waitGlobalIdle(): Promise<void> {\n\t\tif (this._activeOperations === 0 && this._maintenanceOwners === 0) return Promise.resolve();\n\t\tconst result = Promise.withResolvers<void>();\n\t\tthis._globalIdleWaiters.add(result.resolve);\n\t\treturn result.promise;\n\t}\n\n\tprivate _notifyGlobalIdle(): void {\n\t\tif (this._activeOperations !== 0 || this._maintenanceOwners !== 0) return;\n\t\tfor (const resolve of this._globalIdleWaiters) resolve();\n\t\tthis._globalIdleWaiters.clear();\n\t}\n\n\tprivate _contextOwnsSession(sessionId: SessionId): boolean {\n\t\tconst context = this._context.getStore();\n\t\treturn context?.kind === 'global_exclusive' || context?.sessionId === sessionId;\n\t}\n\n\tprivate _upgradeError(mode: string, sessionId: SessionId): TypeError {\n\t\treturn new TypeError(\n\t\t\t`Cannot upgrade an admitted operation for session '${sessionId}' to ${mode}`\n\t\t);\n\t}\n\n\tprivate _globalUpgradeError(mode: string): TypeError {\n\t\treturn new TypeError(`Cannot upgrade an active lifecycle context to ${mode}`);\n\t}\n}\n"],"names":["RESET_EXCLUSIVE","EVICTION_EXCLUSIVE","SessionLifecycleCoordinator","Map","AsyncLocalStorage","Set","sessionId","state","undefined","operation","admissionError","Promise","mutation","options","context","SessionLifecycleClosedError","settlement","sessionIds","uniqueIds","error","exclusive","allowFailedRetry","retrying","result","phase","waiters","resolve","mode","TypeError"],"mappings":"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"}

package/dist/core/SessionLock.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Per-session async lock to prevent concurrent state mutations.
+ *
+ * Uses chained promises: each lock acquisition waits for the previous
+ * holder's promise to resolve. The lock map entry is purged after release
+ * (when no waiters chained on top), preventing unbounded memory growth.
+ *
+ * Different sessions are fully independent: locks for distinct session
+ * ids never block each other. `undefined`/empty session ids share a
+ * single global slot.
+ *
+ * @module session-lock
+ */
+import type { ISessionLock } from '../contracts/interfaces.js';
+import type { SessionId } from '../contracts/ids.js';
+/**
+ * In-memory implementation of {@link ISessionLock}.
+ *
+ * Maintains a `Map<string, Promise<void>>` where each value is the tail
+ * of the lock chain for that session. New acquisitions chain onto the
+ * tail and replace it; once they release, the entry is purged unless a
+ * later acquisition chained on top.
+ *
+ * Lock chain integrity is preserved across timeouts and `fn` errors: a
+ * waiter's slot is only released after the previous holder actually
+ * finishes, even if the waiter aborted via {@link LockTimeoutError}.
+ *
+ * @example
+ * ```typescript
+ * const lock = new SessionLock();
+ * await lock.withLock('session-a', async () => {
+ *   // critical section — concurrent calls for 'session-a' wait
+ * });
+ * ```
+ */
+export declare class SessionLock implements ISessionLock {
+    private readonly _locks;
+    /**
+     * Number of currently held lock chains. Useful for diagnostics
+     * and leak assertions in tests.
+     */
+    get size(): number;
+    /** Returns whether a session currently has a holder or queued operation. */
+    isActive(sessionId: SessionId | undefined): boolean;
+    /**
+     * Execute `fn` while holding the lock for the given session.
+     *
+     * Concurrent calls for the same session are serialized. Calls for
+     * different sessions run in parallel. The lock is always released
+     * (via `finally`) even if `fn` throws.
+     *
+     * @param sessionId - Session to lock. Falsy values share a global slot.
+     * @param fn - Critical section to run while holding the lock.
+     * @param timeoutMs - Maximum time to wait for the lock (default 5000ms).
+     * @throws {LockTimeoutError} When the lock cannot be acquired within `timeoutMs`.
+     */
+    withLock<T>(sessionId: SessionId | undefined, fn: () => Promise<T>, timeoutMs?: number): Promise<T>;
+}
+//# sourceMappingURL=SessionLock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SessionLock.d.ts","sourceRoot":"","sources":["../../src/core/SessionLock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAgBrD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,WAAY,YAAW,YAAY;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAE9D;;;OAGG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED,4EAA4E;IACrE,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO;IAI1D;;;;;;;;;;;OAWG;IACU,QAAQ,CAAC,CAAC,EACtB,SAAS,EAAE,SAAS,GAAG,SAAS,EAChC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,SAAS,GAAE,MAAgC,GACzC,OAAO,CAAC,CAAC,CAAC;CAqCb"}

package/dist/core/SessionLock.js

@@ -0,0 +1,39 @@
+import { GLOBAL_SESSION_ID } from "../contracts/ids.js";
+import { LockTimeoutError } from "./SessionErrors.js";
+const DEFAULT_LOCK_TIMEOUT_MS = 5000;
+function lockKey(sessionId) {
+    return sessionId && sessionId.length > 0 ? sessionId : GLOBAL_SESSION_ID;
+}
+class SessionLock {
+    _locks = new Map();
+    get size() {
+        return this._locks.size;
+    }
+    isActive(sessionId) {
+        return this._locks.has(lockKey(sessionId));
+    }
+    async withLock(sessionId, fn, timeoutMs = DEFAULT_LOCK_TIMEOUT_MS) {
+        const key = lockKey(sessionId);
+        const previous = this._locks.get(key) ?? Promise.resolve();
+        const release = Promise.withResolvers();
+        const next = previous.then(()=>release.promise, ()=>release.promise);
+        this._locks.set(key, next);
+        next.then(()=>{
+            if (this._locks.get(key) === next) this._locks.delete(key);
+        });
+        let timeoutId;
+        try {
+            await new Promise((resolve, reject)=>{
+                timeoutId = setTimeout(()=>reject(new LockTimeoutError(key, timeoutMs)), timeoutMs);
+                previous.then(()=>resolve(), ()=>resolve());
+            });
+            return await fn();
+        } finally{
+            if (void 0 !== timeoutId) clearTimeout(timeoutId);
+            release.resolve();
+        }
+    }
+}
+export { SessionLock };
+
+//# sourceMappingURL=SessionLock.js.map

package/dist/core/SessionLock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/SessionLock.js","sources":["../../src/core/SessionLock.ts"],"sourcesContent":["/**\n * Per-session async lock to prevent concurrent state mutations.\n *\n * Uses chained promises: each lock acquisition waits for the previous\n * holder's promise to resolve. The lock map entry is purged after release\n * (when no waiters chained on top), preventing unbounded memory growth.\n *\n * Different sessions are fully independent: locks for distinct session\n * ids never block each other. `undefined`/empty session ids share a\n * single global slot.\n *\n * @module session-lock\n */\n\nimport type { ISessionLock } from '../contracts/interfaces.js';\nimport type { SessionId } from '../contracts/ids.js';\nimport { GLOBAL_SESSION_ID } from '../contracts/ids.js';\nimport { LockTimeoutError } from './SessionErrors.js';\n\nconst DEFAULT_LOCK_TIMEOUT_MS = 5000;\n\n/**\n * Normalize a session id for keying the internal lock map.\n * Treats `undefined`, `null`, and empty strings as the global session.\n *\n * @internal\n */\nfunction lockKey(sessionId: SessionId | undefined): SessionId {\n\treturn sessionId && sessionId.length > 0 ? sessionId : GLOBAL_SESSION_ID;\n}\n\n/**\n * In-memory implementation of {@link ISessionLock}.\n *\n * Maintains a `Map<string, Promise<void>>` where each value is the tail\n * of the lock chain for that session. New acquisitions chain onto the\n * tail and replace it; once they release, the entry is purged unless a\n * later acquisition chained on top.\n *\n * Lock chain integrity is preserved across timeouts and `fn` errors: a\n * waiter's slot is only released after the previous holder actually\n * finishes, even if the waiter aborted via {@link LockTimeoutError}.\n *\n * @example\n * ```typescript\n * const lock = new SessionLock();\n * await lock.withLock('session-a', async () => {\n *   // critical section — concurrent calls for 'session-a' wait\n * });\n * ```\n */\nexport class SessionLock implements ISessionLock {\n\tprivate readonly _locks = new Map<SessionId, Promise<void>>();\n\n\t/**\n\t * Number of currently held lock chains. Useful for diagnostics\n\t * and leak assertions in tests.\n\t */\n\tpublic get size(): number {\n\t\treturn this._locks.size;\n\t}\n\n\t/** Returns whether a session currently has a holder or queued operation. */\n\tpublic isActive(sessionId: SessionId | undefined): boolean {\n\t\treturn this._locks.has(lockKey(sessionId));\n\t}\n\n\t/**\n\t * Execute `fn` while holding the lock for the given session.\n\t *\n\t * Concurrent calls for the same session are serialized. Calls for\n\t * different sessions run in parallel. The lock is always released\n\t * (via `finally`) even if `fn` throws.\n\t *\n\t * @param sessionId - Session to lock. Falsy values share a global slot.\n\t * @param fn - Critical section to run while holding the lock.\n\t * @param timeoutMs - Maximum time to wait for the lock (default 5000ms).\n\t * @throws {LockTimeoutError} When the lock cannot be acquired within `timeoutMs`.\n\t */\n\tpublic async withLock<T>(\n\t\tsessionId: SessionId | undefined,\n\t\tfn: () => Promise<T>,\n\t\ttimeoutMs: number = DEFAULT_LOCK_TIMEOUT_MS\n\t): Promise<T> {\n\t\tconst key = lockKey(sessionId);\n\t\tconst previous = this._locks.get(key) ?? Promise.resolve();\n\n\t\t// `next` is the tail this acquirer publishes to the chain. It only\n\t\t// resolves after `previous` settles, guaranteeing serialization even\n\t\t// when the current acquirer times out before holding the lock.\n\t\tconst release = Promise.withResolvers<void>();\n\t\tconst next = previous.then(\n\t\t\t() => release.promise,\n\t\t\t() => release.promise\n\t\t);\n\t\tthis._locks.set(key, next);\n\t\t// Identity protects a later acquisition from an earlier tail's cleanup.\n\t\tvoid next.then(() => {\n\t\t\tif (this._locks.get(key) === next) {\n\t\t\t\tthis._locks.delete(key);\n\t\t\t}\n\t\t});\n\n\t\tlet timeoutId: ReturnType<typeof setTimeout> | undefined;\n\t\ttry {\n\t\t\tawait new Promise<void>((resolve, reject) => {\n\t\t\t\ttimeoutId = setTimeout(() => reject(new LockTimeoutError(key, timeoutMs)), timeoutMs);\n\t\t\t\tprevious.then(\n\t\t\t\t\t() => resolve(),\n\t\t\t\t\t() => resolve() // previous holder's failure must not poison the chain\n\t\t\t\t);\n\t\t\t});\n\t\t\treturn await fn();\n\t\t} finally {\n\t\t\tif (timeoutId !== undefined) {\n\t\t\t\tclearTimeout(timeoutId);\n\t\t\t}\n\t\t\trelease.resolve();\n\t\t}\n\t}\n}\n"],"names":["DEFAULT_LOCK_TIMEOUT_MS","lockKey","sessionId","GLOBAL_SESSION_ID","SessionLock","Map","fn","timeoutMs","key","previous","Promise","release","next","timeoutId","resolve","reject","setTimeout","LockTimeoutError","undefined","clearTimeout"],"mappings":";;AAmBA,MAAMA,0BAA0B;AAQhC,SAASC,QAAQC,SAAgC;IAChD,OAAOA,aAAaA,UAAU,MAAM,GAAG,IAAIA,YAAYC;AACxD;AAsBO,MAAMC;IACK,SAAS,IAAIC,MAAgC;IAM9D,IAAW,OAAe;QACzB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI;IACxB;IAGO,SAASH,SAAgC,EAAW;QAC1D,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAACD,QAAQC;IAChC;IAcA,MAAa,SACZA,SAAgC,EAChCI,EAAoB,EACpBC,YAAoBP,uBAAuB,EAC9B;QACb,MAAMQ,MAAMP,QAAQC;QACpB,MAAMO,WAAW,IAAI,CAAC,MAAM,CAAC,GAAG,CAACD,QAAQE,QAAQ,OAAO;QAKxD,MAAMC,UAAUD,QAAQ,aAAa;QACrC,MAAME,OAAOH,SAAS,IAAI,CACzB,IAAME,QAAQ,OAAO,EACrB,IAAMA,QAAQ,OAAO;QAEtB,IAAI,CAAC,MAAM,CAAC,GAAG,CAACH,KAAKI;QAEhBA,KAAK,IAAI,CAAC;YACd,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAACJ,SAASI,MAC5B,IAAI,CAAC,MAAM,CAAC,MAAM,CAACJ;QAErB;QAEA,IAAIK;QACJ,IAAI;YACH,MAAM,IAAIH,QAAc,CAACI,SAASC;gBACjCF,YAAYG,WAAW,IAAMD,OAAO,IAAIE,iBAAiBT,KAAKD,aAAaA;gBAC3EE,SAAS,IAAI,CACZ,IAAMK,WACN,IAAMA;YAER;YACA,OAAO,MAAMR;QACd,SAAU;YACT,IAAIO,AAAcK,WAAdL,WACHM,aAAaN;YAEdF,QAAQ,OAAO;QAChB;IACD;AACD"}

package/dist/core/SessionManager.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Deterministic session cleanup candidate policy and periodic timer.
+ *
+ * @module SessionManager
+ */
+import type { SessionId } from '../contracts/ids.js';
+import type { Logger } from '../logger/StructuredLogger.js';
+/** Minimal session facts needed by capacity and TTL policy. */
+export interface SessionLike {
+    readonly lastAccessedAt: number;
+    readonly owner?: string;
+    readonly provenance?: 'restored';
+}
+/** Determines whether a candidate can be removed at this instant. */
+export type SessionEligibility<S extends SessionLike> = (sessionId: SessionId, session: S) => boolean;
+/** Configuration options for {@link SessionManager}. */
+export interface SessionManagerConfig {
+    readonly defaultSessionId: SessionId;
+    readonly sessionTtlMs: number;
+    readonly cleanupIntervalMs: number;
+    readonly getMaxSessions: () => number;
+    readonly maxSessionsPerOwner?: number;
+    readonly logger?: Logger;
+}
+/**
+ * Produces complete candidate sets but never mutates the caller-owned session map.
+ *
+ * @example
+ * ```ts
+ * const victims = manager.planProspectiveAdmission(sessions, owner, lifecycle.isIdle);
+ * ```
+ */
+export declare class SessionManager<S extends SessionLike> {
+    private readonly _defaultSessionId;
+    private readonly _sessionTtlMs;
+    private readonly _cleanupIntervalMs;
+    private readonly _getMaxSessions;
+    private readonly _maxSessionsPerOwner;
+    private readonly _logger;
+    private _cleanupTimer;
+    constructor(config: SessionManagerConfig);
+    /** @returns The periodic cleanup timer, when active. */
+    get timer(): ReturnType<typeof setInterval> | null;
+    /**
+     * Starts periodic TTL candidate cleanup and observes every asynchronous rejection.
+     */
+    startCleanupTimer(sessions: Map<SessionId, S>, isEligible: SessionEligibility<S>, cleanup: (sessionIds: readonly SessionId[]) => Promise<void>): void;
+    /** Stops the periodic cleanup timer. */
+    stopCleanupTimer(): void;
+    /**
+     * Plans the complete victim union required before admitting one prospective session.
+     *
+     * Owner quota need is selected first. Those victims also satisfy global need, then
+     * oldest globally eligible alternatives fill any remainder. `undefined` means no
+     * complete eligible set exists; the input map is never modified.
+     */
+    planProspectiveAdmission(sessions: ReadonlyMap<SessionId, S>, owner: string | undefined, isEligible: SessionEligibility<S>): readonly SessionId[] | undefined;
+    /** Returns stable oldest-first TTL candidates under the same eligibility rules. */
+    staleSessionCandidates(sessions: ReadonlyMap<SessionId, S>, isEligible: SessionEligibility<S>, now?: number): readonly SessionId[];
+    private _orderedLiveCandidates;
+}
+//# sourceMappingURL=SessionManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SessionManager.d.ts","sourceRoot":"","sources":["../../src/core/SessionManager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAE5D,+DAA+D;AAC/D,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;CACjC;AAED,qEAAqE;AACrE,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,WAAW,IAAI,CACvD,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,CAAC,KACN,OAAO,CAAC;AAEb,wDAAwD;AACxD,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,MAAM,CAAC;IACtC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAQD;;;;;;;GAOG;AACH,qBAAa,cAAc,CAAC,CAAC,SAAS,WAAW;IAChD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAY;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAe;IAC/C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,aAAa,CAA+C;gBAEjD,MAAM,EAAE,oBAAoB;IAS/C,wDAAwD;IACxD,IAAW,KAAK,IAAI,UAAU,CAAC,OAAO,WAAW,CAAC,GAAG,IAAI,CAExD;IAED;;OAEG;IACI,iBAAiB,CACvB,QAAQ,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,EAC3B,UAAU,EAAE,kBAAkB,CAAC,CAAC,CAAC,EACjC,OAAO,EAAE,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAC1D,IAAI;IAgBP,wCAAwC;IACjC,gBAAgB,IAAI,IAAI;IAM/B;;;;;;OAMG;IACI,wBAAwB,CAC9B,QAAQ,EAAE,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC,EACnC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,UAAU,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC/B,SAAS,SAAS,EAAE,GAAG,SAAS;IAiCnC,mFAAmF;IAC5E,sBAAsB,CAC5B,QAAQ,EAAE,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC,EACnC,UAAU,EAAE,kBAAkB,CAAC,CAAC,CAAC,EACjC,GAAG,GAAE,MAAmB,GACtB,SAAS,SAAS,EAAE;IAWvB,OAAO,CAAC,sBAAsB;CAe9B"}

package/dist/core/SessionManager.js

@@ -0,0 +1,75 @@
+import { NullLogger } from "../logger/NullLogger.js";
+class SessionManager {
+    _defaultSessionId;
+    _sessionTtlMs;
+    _cleanupIntervalMs;
+    _getMaxSessions;
+    _maxSessionsPerOwner;
+    _logger;
+    _cleanupTimer = null;
+    constructor(config){
+        this._defaultSessionId = config.defaultSessionId;
+        this._sessionTtlMs = config.sessionTtlMs;
+        this._cleanupIntervalMs = config.cleanupIntervalMs;
+        this._getMaxSessions = config.getMaxSessions;
+        this._maxSessionsPerOwner = config.maxSessionsPerOwner ?? 50;
+        this._logger = config.logger ?? new NullLogger();
+    }
+    get timer() {
+        return this._cleanupTimer;
+    }
+    startCleanupTimer(sessions, isEligible, cleanup) {
+        if (null !== this._cleanupTimer) return;
+        this._cleanupTimer = setInterval(()=>{
+            const candidates = this.staleSessionCandidates(sessions, isEligible);
+            if (0 === candidates.length) return;
+            Promise.resolve().then(()=>cleanup(candidates)).catch((error)=>{
+                this._logger.error('Session cleanup failed', {
+                    error
+                });
+            });
+        }, this._cleanupIntervalMs);
+        if ('object' == typeof this._cleanupTimer && 'unref' in this._cleanupTimer) this._cleanupTimer.unref();
+    }
+    stopCleanupTimer() {
+        if (null === this._cleanupTimer) return;
+        clearInterval(this._cleanupTimer);
+        this._cleanupTimer = null;
+    }
+    planProspectiveAdmission(sessions, owner, isEligible) {
+        const live = this._orderedLiveCandidates(sessions);
+        const selected = [];
+        if (void 0 !== owner) {
+            const ownerCount = live.filter((candidate)=>candidate.session.owner === owner).length;
+            const ownerNeed = Math.max(0, ownerCount + 1 - this._maxSessionsPerOwner);
+            selected.push(...live.filter((candidate)=>candidate.session.owner === owner && candidate.sessionId !== this._defaultSessionId && isEligible(candidate.sessionId, candidate.session)).slice(0, ownerNeed));
+            if (selected.length < ownerNeed) return;
+        }
+        const globalNeed = Math.max(0, live.length + 1 - this._getMaxSessions());
+        const remainingNeed = Math.max(0, globalNeed - selected.length);
+        const selectedIds = new Set(selected.map((candidate)=>candidate.sessionId));
+        const alternatives = live.filter((candidate)=>candidate.sessionId !== this._defaultSessionId && !selectedIds.has(candidate.sessionId) && isEligible(candidate.sessionId, candidate.session));
+        if (alternatives.length < remainingNeed) return;
+        selected.push(...alternatives.slice(0, remainingNeed));
+        return selected.map((candidate)=>candidate.sessionId);
+    }
+    staleSessionCandidates(sessions, isEligible, now = Date.now()) {
+        return this._orderedLiveCandidates(sessions).filter((candidate)=>candidate.sessionId !== this._defaultSessionId && now - candidate.session.lastAccessedAt > this._sessionTtlMs && isEligible(candidate.sessionId, candidate.session)).map((candidate)=>candidate.sessionId);
+    }
+    _orderedLiveCandidates(sessions) {
+        const candidates = [];
+        let insertionOrder = 0;
+        for (const [sessionId, session] of sessions){
+            if ('restored' !== session.provenance) candidates.push({
+                sessionId,
+                session,
+                insertionOrder
+            });
+            insertionOrder += 1;
+        }
+        return candidates.sort((left, right)=>left.session.lastAccessedAt - right.session.lastAccessedAt || left.insertionOrder - right.insertionOrder);
+    }
+}
+export { SessionManager };
+
+//# sourceMappingURL=SessionManager.js.map