@iworkforces/tracelattice 2.0.3

package/dist/core/PersistenceBuffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/PersistenceBuffer.js","sources":["../../src/core/PersistenceBuffer.ts"],"sourcesContent":["/**\n * Joinable coordinator for attributable persistence work.\n *\n * @module PersistenceBuffer\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\nimport type { PersistenceBackend } from '../contracts/PersistenceBackend.js';\nimport type { IEdgeStore } from '../contracts/interfaces.js';\nimport type { BranchId, SessionId } from '../contracts/ids.js';\nimport type { PersistenceWork, PersistenceWorkToken } from '../contracts/persistence-work.js';\nimport {\n\tPersistenceDrainError,\n\tPersistenceSessionAdmissionClosedError,\n\tPersistenceSessionBarrierReentrancyError,\n} from './PersistenceBufferErrors.js';\nimport { NullLogger } from '../logger/NullLogger.js';\nimport type { Logger } from '../logger/StructuredLogger.js';\nimport { assertNever } from '../utils.js';\nimport type { Summary } from './compression/Summary.js';\nimport type { Edge } from './graph/Edge.js';\nimport { PersistenceWorkQueue, type PersistenceSelectionMode } from './PersistenceWorkQueue.js';\nimport { PersistenceWriter, type PersistenceDelay } from './PersistenceWriter.js';\nimport type { ThoughtData } from './thought.js';\n\n/** Minimal compatibility view for legacy callers that own a `writeBuffer`. */\nexport interface BufferedSession {\n\twriteBuffer: ThoughtData[];\n}\n\n/** Event emitter contract for persistence error events. */\nexport interface PersistenceEventEmitter {\n\temit(event: 'persistenceError', payload: { operation: string; error: Error }): boolean;\n}\n\n/** Observable persistence state relevant to safe in-memory session eviction. */\nexport type SessionEvictionState = 'quiescent' | 'pending' | 'failed' | 'barrier';\n\n/** Configuration options for {@link PersistenceBuffer}. */\nexport interface PersistenceBufferConfig<S extends BufferedSession> {\n\treadonly persistence: PersistenceBackend;\n\treadonly bufferSize: number;\n\treadonly flushInterval: number;\n\treadonly maxRetries: number;\n\treadonly defaultSessionId: SessionId;\n\t/** Compatibility-only session source retained until producer wiring is migrated. */\n\treadonly getSessions: () => Map<SessionId, S>;\n\t/** Compatibility-only default session retained until producer wiring is migrated. */\n\treadonly getDefaultSession: () => S;\n\t/** Compatibility-only edge source retained until producers register snapshots. */\n\treadonly edgeStore?: IEdgeStore;\n\t/** Optional emitter for `persistenceError` events. */\n\treadonly eventEmitter?: PersistenceEventEmitter | null;\n\treadonly logger?: Logger;\n\t/** Optional retry scheduler for deterministic coordination and testing. */\n\treadonly delay?: PersistenceDelay;\n}\n\ntype ActiveDrain = {\n\treadonly promise: Promise<void>;\n\treadonly resolve: () => void;\n\treadonly reject: (reason: unknown) => void;\n\treadonly selectedTokens: Set<PersistenceWorkToken>;\n\tmode: PersistenceSelectionMode;\n\tbackgroundObserved: boolean;\n\tinFlightWork: PersistenceWork | null;\n\tsettlement: DrainSettlement | null;\n};\n\ntype SessionBarrierState = {\n\ttail: Promise<void>;\n\tpendingOwners: number;\n};\n\ntype DrainTermination =\n\t{ readonly kind: 'result' } | { readonly kind: 'fault'; readonly fault: unknown };\n\ntype DrainSettlement =\n\t{ readonly kind: 'resolved' } | { readonly kind: 'rejected'; readonly reason: unknown };\n\ntype SessionQuiescence =\n\t| { readonly kind: 'pending' }\n\t| { readonly kind: 'resolved' }\n\t| { readonly kind: 'rejected'; readonly reason: unknown };\n\n/**\n * Coordinates one globally joinable persistence generation at a time.\n *\n * Accepted work is owned by a queue independent of live session state. Explicit\n * callers can join and upgrade a background generation without starting another writer.\n */\nexport class PersistenceBuffer<S extends BufferedSession> {\n\tprivate readonly _bufferSize: number;\n\tprivate readonly _flushInterval: number;\n\tprivate readonly _defaultSessionId: SessionId;\n\tprivate readonly _queue = new PersistenceWorkQueue();\n\tprivate readonly _writer: PersistenceWriter;\n\tprivate _eventEmitter: PersistenceEventEmitter | null;\n\tprivate readonly _logger: Logger;\n\n\tprivate _flushTimer: ReturnType<typeof setInterval> | null = null;\n\tprivate _activeDrain: ActiveDrain | null = null;\n\tprivate readonly _sessionBarriers = new Map<SessionId, SessionBarrierState>();\n\tprivate readonly _sessionBarrierOwnership = new AsyncLocalStorage<ReadonlySet<SessionId>>();\n\tprivate readonly _sessionProgressWaiters = new Map<SessionId, Set<() => void>>();\n\tprivate readonly _quarantinedSessions = new Set<SessionId>();\n\tprivate readonly _evictionQuarantinedSessions = new Set<SessionId>();\n\tprivate _globalResetTail: Promise<void> = Promise.resolve();\n\tprivate _globalResetOwners = 0;\n\tprivate _globalQuarantined = false;\n\n\t/**\n\t * Creates a persistence-drain coordinator.\n\t *\n\t * @param config - Persistence dependencies, trigger thresholds, and retry policy.\n\t */\n\tpublic constructor(config: PersistenceBufferConfig<S>) {\n\t\tthis._bufferSize = config.bufferSize;\n\t\tthis._flushInterval = config.flushInterval;\n\t\tthis._defaultSessionId = config.defaultSessionId;\n\t\tthis._eventEmitter = config.eventEmitter ?? null;\n\t\tthis._logger = config.logger ?? new NullLogger();\n\t\tthis._writer = new PersistenceWriter({\n\t\t\tpersistence: config.persistence,\n\t\t\tmaxRetries: config.maxRetries,\n\t\t\tdelay: config.delay,\n\t\t});\n\t}\n\n\t/** @returns The underlying flush timer for lifecycle introspection. */\n\tpublic get timer(): ReturnType<typeof setInterval> | null {\n\t\treturn this._flushTimer;\n\t}\n\n\t/** @returns Whether a global drain generation is active. */\n\tpublic get isFlushing(): boolean {\n\t\treturn this._activeDrain !== null;\n\t}\n\n\t/** @returns Number of accepted thought writes not yet acknowledged successful. */\n\tpublic get pendingThoughtCount(): number {\n\t\treturn this._queue.pendingThoughtCount;\n\t}\n\n\t/**\n\t * Sets or clears the persistence error event emitter.\n\t *\n\t * @param emitter - Replacement emitter, or `null` to disable events.\n\t */\n\tpublic setEventEmitter(emitter: PersistenceEventEmitter | null): void {\n\t\tthis._eventEmitter = emitter;\n\t}\n\n\t/**\n\t * Accepts a thought with authoritative session attribution.\n\t *\n\t * The legacy session overload derives attribution from `thought.session_id` and\n\t * falls back to the configured default session without using the live write buffer.\n\t *\n\t * @param sessionId - Session that owns the accepted thought.\n\t * @param thought - Thought to persist.\n\t */\n\tpublic bufferThought(sessionId: SessionId, thought: ThoughtData): void;\n\tpublic bufferThought(session: BufferedSession, thought: ThoughtData): void;\n\tpublic bufferThought(source: SessionId | BufferedSession, thought: ThoughtData): void {\n\t\tconst sessionId =\n\t\t\ttypeof source === 'string' ? source : (thought.session_id ?? this._defaultSessionId);\n\t\tthis._assertSessionAdmissionOpen(sessionId);\n\t\tif (this._queue.pendingThoughtCount >= this._bufferSize && this.isFlushing) {\n\t\t\tthis._logger.info('Write buffer full and flush in progress, applying backpressure', {\n\t\t\t\tbufferSize: this._queue.pendingThoughtCount,\n\t\t\t\tmaxSize: this._bufferSize,\n\t\t\t});\n\t\t}\n\n\t\tthis._queue.enqueueThought(sessionId, thought);\n\t\tif (this._queue.pendingThoughtCount >= this._bufferSize) this._triggerBackgroundDrain();\n\t}\n\n\t/**\n\t * Accepts the latest snapshot for one session-owned branch.\n\t *\n\t * @param sessionId - Session that owns the branch.\n\t * @param branchId - Stable branch coordinate.\n\t * @param thoughts - Branch snapshot copied by the queue.\n\t */\n\tpublic bufferBranch(\n\t\tsessionId: SessionId,\n\t\tbranchId: BranchId,\n\t\tthoughts: readonly ThoughtData[]\n\t): void {\n\t\tthis._assertSessionAdmissionOpen(sessionId);\n\t\tthis._queue.replaceBranch(sessionId, branchId, thoughts);\n\t}\n\n\t/**\n\t * @param sessionId - Session that owns the branch.\n\t * @param branchId - Stable branch coordinate to delete.\n\t */\n\tpublic deleteBranch(sessionId: SessionId, branchId: BranchId): void {\n\t\tthis._assertSessionAdmissionOpen(sessionId);\n\t\tthis._queue.deleteBranch(sessionId, branchId);\n\t}\n\n\t/**\n\t * Accepts the latest edge snapshot for one session.\n\t *\n\t * @param sessionId - Session that owns the edges.\n\t * @param edges - Edge snapshot copied by the queue.\n\t */\n\tpublic bufferEdges(sessionId: SessionId, edges: readonly Edge[]): void {\n\t\tthis._assertSessionAdmissionOpen(sessionId);\n\t\tthis._queue.replaceEdges(sessionId, edges);\n\t}\n\n\t/**\n\t * Accepts the latest summary snapshot for one session.\n\t *\n\t * @param sessionId - Session that owns the summaries.\n\t * @param summaries - Summary snapshot copied by the queue.\n\t */\n\tpublic bufferSummaries(sessionId: SessionId, summaries: readonly Summary[]): void {\n\t\tthis._assertSessionAdmissionOpen(sessionId);\n\t\tthis._queue.replaceSummaries(sessionId, summaries);\n\t}\n\n\t/** Rejects synchronously when lifecycle coordination has closed persistence admission. */\n\tpublic assertSessionAdmissionOpen(sessionId: SessionId): void {\n\t\tthis._assertSessionAdmissionOpen(sessionId);\n\t}\n\n\t/** Starts the periodic background-drain timer without keeping the process alive. */\n\tpublic startFlushTimer(): void {\n\t\tif (this._flushTimer !== null) return;\n\t\tthis._flushTimer = setInterval(() => this._triggerBackgroundDrain(), this._flushInterval);\n\t\tif (typeof this._flushTimer === 'object' && 'unref' in this._flushTimer) {\n\t\t\tthis._flushTimer.unref();\n\t\t}\n\t}\n\n\t/** Stops the periodic background-drain timer. */\n\tpublic stopFlushTimer(): void {\n\t\tif (this._flushTimer === null) return;\n\t\tclearInterval(this._flushTimer);\n\t\tthis._flushTimer = null;\n\t}\n\n\t/**\n\t * Starts or joins an explicit global drain generation.\n\t *\n\t * @returns The exact shared promise for the active generation.\n\t */\n\tpublic drain(): Promise<void> {\n\t\treturn this._joinOrStart('explicit').promise;\n\t}\n\n\t/** @returns The exact same promise as {@link drain} for the active generation. */\n\tpublic flush(): Promise<void> {\n\t\treturn this.drain();\n\t}\n\n\t/**\n\t * Joins the global explicit generation and projects its terminal failures to one session.\n\t * This method does not close admission; lifecycle owners must use\n\t * {@link withSessionBarrier} when work must not cross an owner callback.\n\t *\n\t * @param sessionId - Session whose accepted writes form the barrier projection.\n\t * @returns A promise that rejects only for that session's failures or an unknown fault.\n\t */\n\tpublic drainSession(sessionId: SessionId): Promise<void> {\n\t\tconst generation = this._joinOrStart('explicit');\n\t\treturn generation.promise.catch((reason: unknown) => {\n\t\t\tif (!(reason instanceof PersistenceDrainError)) throw reason;\n\t\t\tconst failures = reason.failures.filter((failure) => failure.sessionId === sessionId);\n\t\t\tif (failures.length > 0) throw new PersistenceDrainError(failures);\n\t\t});\n\t}\n\n\t/** Returns queue-derived persistence state for safe session eviction planning. */\n\tpublic sessionEvictionState(sessionId: SessionId): SessionEvictionState {\n\t\tif (this._globalResetOwners > 0 || this._sessionBarriers.has(sessionId)) return 'barrier';\n\t\tif (\n\t\t\tthis._globalQuarantined ||\n\t\t\tthis._queue.hasSessionTerminalFailure(sessionId) ||\n\t\t\tthis._quarantinedSessions.has(sessionId) ||\n\t\t\tthis._evictionQuarantinedSessions.has(sessionId)\n\t\t) {\n\t\t\treturn 'failed';\n\t\t}\n\t\treturn this._queue.hasSessionWork(sessionId) ? 'pending' : 'quiescent';\n\t}\n\n\t/**\n\t * Drains accepted session work before ordinary in-memory eviction cleanup.\n\t *\n\t * Unlike reset barriers, this operation never clears durable state or discards\n\t * accepted work. Failure retains admission quarantine until a later explicit\n\t * invocation successfully drains and completes cleanup.\n\t */\n\tpublic withSessionEvictionBarrier<T>(\n\t\tsessionId: SessionId,\n\t\toperation: () => Promise<T>\n\t): Promise<T> {\n\t\tif (\n\t\t\tthis._globalResetOwners > 0 ||\n\t\t\tthis._globalQuarantined ||\n\t\t\tthis._quarantinedSessions.has(sessionId)\n\t\t) {\n\t\t\treturn Promise.reject(new PersistenceSessionAdmissionClosedError(sessionId));\n\t\t}\n\t\tconst currentOwnership = this._sessionBarrierOwnership.getStore();\n\t\tif (currentOwnership?.has(sessionId) === true) {\n\t\t\treturn Promise.reject(new PersistenceSessionBarrierReentrancyError(sessionId));\n\t\t}\n\t\tconst operationOwnership = new Set(currentOwnership);\n\t\toperationOwnership.add(sessionId);\n\t\tconst state = this._sessionBarriers.get(sessionId) ?? {\n\t\t\ttail: Promise.resolve(),\n\t\t\tpendingOwners: 0,\n\t\t};\n\t\tthis._sessionBarriers.set(sessionId, state);\n\t\tstate.pendingOwners += 1;\n\n\t\tconst result = state.tail.then(async () => {\n\t\t\ttry {\n\t\t\t\tawait this._awaitSessionQuiescence(sessionId);\n\t\t\t\tconst value = await this._sessionBarrierOwnership.run(operationOwnership, operation);\n\t\t\t\tthis._queue.forgetQuiescentSession(sessionId);\n\t\t\t\tthis._evictionQuarantinedSessions.delete(sessionId);\n\t\t\t\treturn value;\n\t\t\t} catch (error) {\n\t\t\t\tthis._evictionQuarantinedSessions.add(sessionId);\n\t\t\t\tthrow error;\n\t\t\t} finally {\n\t\t\t\tstate.pendingOwners -= 1;\n\t\t\t\tif (state.pendingOwners === 0) this._sessionBarriers.delete(sessionId);\n\t\t\t}\n\t\t});\n\t\tstate.tail = result.then(\n\t\t\t() => undefined,\n\t\t\t() => undefined\n\t\t);\n\t\treturn result;\n\t}\n\n\t/** Forgets queue coordinates only when the session is fully quiescent. */\n\tpublic forgetQuiescentSession(sessionId: SessionId): boolean {\n\t\treturn this.sessionEvictionState(sessionId) === 'quiescent'\n\t\t\t? this._queue.forgetQuiescentSession(sessionId)\n\t\t\t: false;\n\t}\n\n\t/**\n\t * Runs one lifecycle operation while persistence admission is closed for a session.\n\t *\n\t * Admission closes synchronously when this method is called. Already accepted work for\n\t * the session is settled first; an exhausted session failure rejects without invoking\n\t * `operation`. Concurrent calls for the same session execute in FIFO call order and keep\n\t * admission closed until the final callback settles. Other sessions remain admissible and\n\t * may be owned by a nested callback. Reacquiring the same session from the owning callback's\n\t * async call chain rejects before joining the FIFO because awaiting it would deadlock its owner.\n\t *\n\t * @example\n\t * ```ts\n\t * await buffer.withSessionBarrier(sessionId, async () => {\n\t *   await persistence.clearSession(sessionId);\n\t * });\n\t * ```\n\t *\n\t * @param sessionId - Session exclusively owned for the callback duration.\n\t * @param operation - Awaited lifecycle operation run only after prior work settles.\n\t * @returns The callback result after admission has reopened when no owner remains.\n\t * @throws {@link PersistenceSessionBarrierReentrancyError} when the owning async call chain\n\t * attempts to reacquire `sessionId`.\n\t */\n\tpublic withSessionBarrier<T>(sessionId: SessionId, operation: () => Promise<T>): Promise<T> {\n\t\tconst currentOwnership = this._sessionBarrierOwnership.getStore();\n\t\tif (currentOwnership?.has(sessionId) === true) {\n\t\t\treturn Promise.reject(new PersistenceSessionBarrierReentrancyError(sessionId));\n\t\t}\n\t\tconst operationOwnership = new Set(currentOwnership);\n\t\toperationOwnership.add(sessionId);\n\n\t\tconst state = this._sessionBarriers.get(sessionId) ?? {\n\t\t\ttail: Promise.resolve(),\n\t\t\tpendingOwners: 0,\n\t\t};\n\t\tthis._sessionBarriers.set(sessionId, state);\n\t\tstate.pendingOwners += 1;\n\n\t\tconst result = state.tail.then(async () => {\n\t\t\ttry {\n\t\t\t\tawait this._awaitSessionQuiescence(sessionId);\n\t\t\t\treturn await this._sessionBarrierOwnership.run(operationOwnership, operation);\n\t\t\t} finally {\n\t\t\t\tstate.pendingOwners -= 1;\n\t\t\t\tif (state.pendingOwners === 0) this._sessionBarriers.delete(sessionId);\n\t\t\t}\n\t\t});\n\t\tstate.tail = result.then(\n\t\t\t() => undefined,\n\t\t\t() => undefined\n\t\t);\n\t\treturn result;\n\t}\n\n\t/**\n\t * Runs a scoped reset, retaining admission quarantine on failure.\n\t * A retry may pass retained write failures because successful durable deletion\n\t * invalidates those stale queue entries before admission reopens.\n\t */\n\tpublic withSessionResetBarrier<T>(sessionId: SessionId, operation: () => Promise<T>): Promise<T> {\n\t\tif (this._globalResetOwners > 0 || this._globalQuarantined) {\n\t\t\treturn Promise.reject(new PersistenceSessionAdmissionClosedError(sessionId));\n\t\t}\n\t\tconst currentOwnership = this._sessionBarrierOwnership.getStore();\n\t\tif (currentOwnership?.has(sessionId) === true) {\n\t\t\treturn Promise.reject(new PersistenceSessionBarrierReentrancyError(sessionId));\n\t\t}\n\t\tconst operationOwnership = new Set(currentOwnership);\n\t\toperationOwnership.add(sessionId);\n\t\tconst state = this._sessionBarriers.get(sessionId) ?? {\n\t\t\ttail: Promise.resolve(),\n\t\t\tpendingOwners: 0,\n\t\t};\n\t\tthis._sessionBarriers.set(sessionId, state);\n\t\tstate.pendingOwners += 1;\n\n\t\tconst result = state.tail.then(async () => {\n\t\t\ttry {\n\t\t\t\ttry {\n\t\t\t\t\tawait this._awaitSessionQuiescence(sessionId);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tif (!(error instanceof PersistenceDrainError)) throw error;\n\t\t\t\t}\n\t\t\t\tconst value = await this._sessionBarrierOwnership.run(operationOwnership, operation);\n\t\t\t\tthis._queue.discardSession(sessionId);\n\t\t\t\tthis._quarantinedSessions.delete(sessionId);\n\t\t\t\tthis._evictionQuarantinedSessions.delete(sessionId);\n\t\t\t\treturn value;\n\t\t\t} catch (error) {\n\t\t\t\tthis._quarantinedSessions.add(sessionId);\n\t\t\t\tthrow error;\n\t\t\t} finally {\n\t\t\t\tstate.pendingOwners -= 1;\n\t\t\t\tif (state.pendingOwners === 0) this._sessionBarriers.delete(sessionId);\n\t\t\t}\n\t\t});\n\t\tstate.tail = result.then(\n\t\t\t() => undefined,\n\t\t\t() => undefined\n\t\t);\n\t\treturn result;\n\t}\n\n\t/** Runs a trusted global reset behind a global admission barrier. */\n\tpublic withGlobalResetBarrier<T>(operation: () => Promise<T>): Promise<T> {\n\t\tthis._globalResetOwners += 1;\n\t\tconst prior = this._globalResetTail;\n\t\tconst result = prior.then(async () => {\n\t\t\ttry {\n\t\t\t\tawait Promise.all(Array.from(this._sessionBarriers.values(), (state) => state.tail));\n\t\t\t\ttry {\n\t\t\t\t\tawait this.drain();\n\t\t\t\t} catch (error) {\n\t\t\t\t\tif (!(error instanceof PersistenceDrainError)) throw error;\n\t\t\t\t}\n\t\t\t\tconst value = await operation();\n\t\t\t\tthis._queue.discardAll();\n\t\t\t\tthis._quarantinedSessions.clear();\n\t\t\t\tthis._evictionQuarantinedSessions.clear();\n\t\t\t\tthis._globalQuarantined = false;\n\t\t\t\treturn value;\n\t\t\t} catch (error) {\n\t\t\t\tthis._globalQuarantined = true;\n\t\t\t\tthrow error;\n\t\t\t} finally {\n\t\t\t\tthis._globalResetOwners -= 1;\n\t\t\t}\n\t\t});\n\t\tthis._globalResetTail = result.then(\n\t\t\t() => undefined,\n\t\t\t() => undefined\n\t\t);\n\t\treturn result;\n\t}\n\n\tprivate _joinOrStart(mode: PersistenceSelectionMode): ActiveDrain {\n\t\tconst active = this._activeDrain;\n\t\tif (active !== null) {\n\t\t\tif (mode === 'explicit') active.mode = mode;\n\t\t\treturn active;\n\t\t}\n\n\t\tlet resolveGeneration = (): void => undefined;\n\t\tlet rejectGeneration = (_reason: unknown): void => undefined;\n\t\tconst promise = new Promise<void>((resolve, reject) => {\n\t\t\tresolveGeneration = resolve;\n\t\t\trejectGeneration = reject;\n\t\t});\n\t\tconst generation: ActiveDrain = {\n\t\t\tpromise,\n\t\t\tresolve: resolveGeneration,\n\t\t\treject: rejectGeneration,\n\t\t\tselectedTokens: new Set<PersistenceWorkToken>(),\n\t\t\tmode,\n\t\t\tbackgroundObserved: false,\n\t\t\tinFlightWork: null,\n\t\t\tsettlement: null,\n\t\t};\n\t\tthis._activeDrain = generation;\n\t\tvoid this._runDrain(generation).catch((fault: unknown) => {\n\t\t\tthis._closeGeneration(generation, { kind: 'fault', fault });\n\t\t});\n\t\treturn generation;\n\t}\n\n\tprivate _triggerBackgroundDrain(): void {\n\t\tconst generation = this._joinOrStart('background');\n\t\tif (generation.backgroundObserved) return;\n\t\tgeneration.backgroundObserved = true;\n\t\tvoid generation.promise.catch(() => undefined);\n\t}\n\n\tprivate async _runDrain(generation: ActiveDrain): Promise<void> {\n\t\twhile (true) {\n\t\t\tconst work = this._queue.nextEligibleWork(generation.selectedTokens, generation.mode);\n\t\t\tif (work === undefined) {\n\t\t\t\tthis._closeGeneration(generation, { kind: 'result' });\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tgeneration.inFlightWork = work;\n\t\t\tconst result = await this._writer.write(work);\n\t\t\tif (result === true) this._queue.acknowledgeSuccess(work);\n\t\t\telse this._queue.acknowledgeFailure(work, result);\n\t\t\tgeneration.inFlightWork = null;\n\t\t\tthis._notifySessionProgress();\n\t\t}\n\t}\n\n\tprivate _closeGeneration(generation: ActiveDrain, termination: DrainTermination): void {\n\t\tif (this._activeDrain !== generation) return;\n\t\tlet settlement: DrainSettlement;\n\t\tswitch (termination.kind) {\n\t\t\tcase 'result': {\n\t\t\t\tconst result = this._queue.generationResult(generation.selectedTokens);\n\t\t\t\tsettlement =\n\t\t\t\t\tresult.failures.length === 0\n\t\t\t\t\t\t? { kind: 'resolved' }\n\t\t\t\t\t\t: { kind: 'rejected', reason: new PersistenceDrainError(result.failures) };\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tcase 'fault':\n\t\t\t\tsettlement = { kind: 'rejected', reason: termination.fault };\n\t\t\t\tbreak;\n\t\t\tdefault:\n\t\t\t\tassertNever(termination);\n\t\t}\n\n\t\tgeneration.inFlightWork = null;\n\t\tgeneration.settlement = settlement;\n\t\tthis._activeDrain = null;\n\t\tthis._notifySessionProgress();\n\t\tswitch (settlement.kind) {\n\t\t\tcase 'resolved':\n\t\t\t\tgeneration.resolve();\n\t\t\t\treturn;\n\t\t\tcase 'rejected':\n\t\t\t\tgeneration.reject(settlement.reason);\n\t\t\t\tif (settlement.reason instanceof PersistenceDrainError) {\n\t\t\t\t\tthis._observeFailure(generation, settlement.reason);\n\t\t\t\t}\n\t\t\t\treturn;\n\t\t\tdefault:\n\t\t\t\tassertNever(settlement);\n\t\t}\n\t}\n\n\tprivate async _awaitSessionQuiescence(sessionId: SessionId): Promise<void> {\n\t\tconst generation = this._joinOrStart('explicit');\n\t\tvoid generation.promise.catch(() => undefined);\n\t\twhile (true) {\n\t\t\tconst quiescence = this._sessionQuiescence(generation, sessionId);\n\t\t\tswitch (quiescence.kind) {\n\t\t\t\tcase 'pending':\n\t\t\t\t\tawait this._waitForSessionProgress(sessionId);\n\t\t\t\t\tbreak;\n\t\t\t\tcase 'resolved':\n\t\t\t\t\treturn;\n\t\t\t\tcase 'rejected':\n\t\t\t\t\tthrow quiescence.reason;\n\t\t\t\tdefault:\n\t\t\t\t\treturn assertNever(quiescence);\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate _sessionQuiescence(generation: ActiveDrain, sessionId: SessionId): SessionQuiescence {\n\t\tif (\n\t\t\tgeneration.settlement?.kind === 'rejected' &&\n\t\t\t!(generation.settlement.reason instanceof PersistenceDrainError)\n\t\t) {\n\t\t\treturn { kind: 'rejected', reason: generation.settlement.reason };\n\t\t}\n\t\tif (generation.inFlightWork?.sessionId === sessionId) return { kind: 'pending' };\n\t\tif (this._queue.hasEligibleWork(generation.selectedTokens, generation.mode, sessionId)) {\n\t\t\treturn { kind: 'pending' };\n\t\t}\n\n\t\tconst failures = this._queue.currentFailures(generation.selectedTokens, sessionId);\n\t\treturn failures.length === 0\n\t\t\t? { kind: 'resolved' }\n\t\t\t: { kind: 'rejected', reason: new PersistenceDrainError(failures) };\n\t}\n\n\tprivate _waitForSessionProgress(sessionId: SessionId): Promise<void> {\n\t\treturn new Promise((resolve) => {\n\t\t\tconst waiters = this._sessionProgressWaiters.get(sessionId) ?? new Set<() => void>();\n\t\t\twaiters.add(resolve);\n\t\t\tthis._sessionProgressWaiters.set(sessionId, waiters);\n\t\t});\n\t}\n\n\tprivate _notifySessionProgress(): void {\n\t\tfor (const [sessionId, waiters] of this._sessionProgressWaiters) {\n\t\t\tthis._sessionProgressWaiters.delete(sessionId);\n\t\t\tfor (const resolve of waiters) resolve();\n\t\t}\n\t}\n\n\tprivate _assertSessionAdmissionOpen(sessionId: SessionId): void {\n\t\tif (\n\t\t\tthis._globalResetOwners > 0 ||\n\t\t\tthis._globalQuarantined ||\n\t\t\tthis._sessionBarriers.has(sessionId) ||\n\t\t\tthis._quarantinedSessions.has(sessionId) ||\n\t\t\tthis._evictionQuarantinedSessions.has(sessionId)\n\t\t) {\n\t\t\tthrow new PersistenceSessionAdmissionClosedError(sessionId);\n\t\t}\n\t}\n\n\tprivate _observeFailure(generation: ActiveDrain, error: PersistenceDrainError): void {\n\t\tthis._logger.info('Persistence drain completed with failures', {\n\t\t\tfailed: error.failures.length,\n\t\t\tselected: generation.selectedTokens.size,\n\t\t});\n\t\tthis._eventEmitter?.emit('persistenceError', { operation: 'flushBuffer', error });\n\t}\n}\n"],"names":["PersistenceBuffer","PersistenceWorkQueue","Map","AsyncLocalStorage","Set","Promise","config","NullLogger","PersistenceWriter","emitter","source","thought","sessionId","branchId","thoughts","edges","summaries","setInterval","clearInterval","generation","reason","PersistenceDrainError","failures","failure","operation","PersistenceSessionAdmissionClosedError","currentOwnership","PersistenceSessionBarrierReentrancyError","operationOwnership","state","result","value","error","undefined","prior","Array","mode","active","resolveGeneration","rejectGeneration","_reason","promise","resolve","reject","fault","work","termination","settlement","assertNever","quiescence","waiters"],"mappings":"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"}

package/dist/core/PersistenceBufferErrors.d.ts

@@ -0,0 +1,22 @@
+import type { SessionId } from '../contracts/ids.js';
+import type { PersistenceWorkFailure } from '../contracts/persistence-work.js';
+import { SequentialThinkingError } from '../errors.js';
+/** Error raised when an explicit persistence drain has terminal write failures. */
+export declare class PersistenceDrainError extends SequentialThinkingError {
+    /** Failures captured when the drain generation settled. */
+    readonly failures: readonly PersistenceWorkFailure[];
+    constructor(failures: readonly PersistenceWorkFailure[]);
+}
+/** Error raised when persistence work is submitted while a lifecycle owner holds the session. */
+export declare class PersistenceSessionAdmissionClosedError extends SequentialThinkingError {
+    /** Session whose persistence admission is closed. */
+    readonly sessionId: SessionId;
+    constructor(sessionId: SessionId);
+}
+/** Error raised when an owning async call chain tries to reacquire its session barrier. */
+export declare class PersistenceSessionBarrierReentrancyError extends SequentialThinkingError {
+    /** Session already owned by the current async call chain. */
+    readonly sessionId: SessionId;
+    constructor(sessionId: SessionId);
+}
+//# sourceMappingURL=PersistenceBufferErrors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PersistenceBufferErrors.d.ts","sourceRoot":"","sources":["../../src/core/PersistenceBufferErrors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC/E,OAAO,EAAe,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAEpE,mFAAmF;AACnF,qBAAa,qBAAsB,SAAQ,uBAAuB;IACjE,2DAA2D;IAC3D,SAAgB,QAAQ,EAAE,SAAS,sBAAsB,EAAE,CAAC;gBAEhD,QAAQ,EAAE,SAAS,sBAAsB,EAAE;CAQvD;AAED,iGAAiG;AACjG,qBAAa,sCAAuC,SAAQ,uBAAuB;IAClF,qDAAqD;IACrD,SAAgB,SAAS,EAAE,SAAS,CAAC;gBAEzB,SAAS,EAAE,SAAS;CAQhC;AAED,2FAA2F;AAC3F,qBAAa,wCAAyC,SAAQ,uBAAuB;IACpF,6DAA6D;IAC7D,SAAgB,SAAS,EAAE,SAAS,CAAC;gBAEzB,SAAS,EAAE,SAAS;CAQhC"}

package/dist/core/PersistenceBufferErrors.js

@@ -0,0 +1,30 @@
+import { ERROR_CODES, SequentialThinkingError } from "../errors.js";
+class PersistenceDrainError extends SequentialThinkingError {
+    failures;
+    constructor(failures){
+        super(`Persistence drain failed with ${failures.length} terminal ${1 === failures.length ? 'failure' : 'failures'}`, ERROR_CODES.PERSISTENCE_DRAIN);
+        this.name = 'PersistenceDrainError';
+        this.failures = Object.freeze([
+            ...failures
+        ]);
+    }
+}
+class PersistenceSessionAdmissionClosedError extends SequentialThinkingError {
+    sessionId;
+    constructor(sessionId){
+        super(`Persistence admission for session '${sessionId}' is closed by a lifecycle barrier`, ERROR_CODES.PERSISTENCE_SESSION_ADMISSION_CLOSED);
+        this.name = 'PersistenceSessionAdmissionClosedError';
+        this.sessionId = sessionId;
+    }
+}
+class PersistenceSessionBarrierReentrancyError extends SequentialThinkingError {
+    sessionId;
+    constructor(sessionId){
+        super(`Persistence lifecycle barrier for session '${sessionId}' is not reentrant`, ERROR_CODES.PERSISTENCE_SESSION_BARRIER_REENTRANCY);
+        this.name = 'PersistenceSessionBarrierReentrancyError';
+        this.sessionId = sessionId;
+    }
+}
+export { PersistenceDrainError, PersistenceSessionAdmissionClosedError, PersistenceSessionBarrierReentrancyError };
+
+//# sourceMappingURL=PersistenceBufferErrors.js.map

package/dist/core/PersistenceBufferErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/PersistenceBufferErrors.js","sources":["../../src/core/PersistenceBufferErrors.ts"],"sourcesContent":["import type { SessionId } from '../contracts/ids.js';\nimport type { PersistenceWorkFailure } from '../contracts/persistence-work.js';\nimport { ERROR_CODES, SequentialThinkingError } from '../errors.js';\n\n/** Error raised when an explicit persistence drain has terminal write failures. */\nexport class PersistenceDrainError extends SequentialThinkingError {\n\t/** Failures captured when the drain generation settled. */\n\tpublic readonly failures: readonly PersistenceWorkFailure[];\n\n\tconstructor(failures: readonly PersistenceWorkFailure[]) {\n\t\tsuper(\n\t\t\t`Persistence drain failed with ${failures.length} terminal ${failures.length === 1 ? 'failure' : 'failures'}`,\n\t\t\tERROR_CODES.PERSISTENCE_DRAIN\n\t\t);\n\t\tthis.name = 'PersistenceDrainError';\n\t\tthis.failures = Object.freeze([...failures]);\n\t}\n}\n\n/** Error raised when persistence work is submitted while a lifecycle owner holds the session. */\nexport class PersistenceSessionAdmissionClosedError extends SequentialThinkingError {\n\t/** Session whose persistence admission is closed. */\n\tpublic readonly sessionId: SessionId;\n\n\tconstructor(sessionId: SessionId) {\n\t\tsuper(\n\t\t\t`Persistence admission for session '${sessionId}' is closed by a lifecycle barrier`,\n\t\t\tERROR_CODES.PERSISTENCE_SESSION_ADMISSION_CLOSED\n\t\t);\n\t\tthis.name = 'PersistenceSessionAdmissionClosedError';\n\t\tthis.sessionId = sessionId;\n\t}\n}\n\n/** Error raised when an owning async call chain tries to reacquire its session barrier. */\nexport class PersistenceSessionBarrierReentrancyError extends SequentialThinkingError {\n\t/** Session already owned by the current async call chain. */\n\tpublic readonly sessionId: SessionId;\n\n\tconstructor(sessionId: SessionId) {\n\t\tsuper(\n\t\t\t`Persistence lifecycle barrier for session '${sessionId}' is not reentrant`,\n\t\t\tERROR_CODES.PERSISTENCE_SESSION_BARRIER_REENTRANCY\n\t\t);\n\t\tthis.name = 'PersistenceSessionBarrierReentrancyError';\n\t\tthis.sessionId = sessionId;\n\t}\n}\n"],"names":["PersistenceDrainError","SequentialThinkingError","failures","ERROR_CODES","Object","PersistenceSessionAdmissionClosedError","sessionId","PersistenceSessionBarrierReentrancyError"],"mappings":";AAKO,MAAMA,8BAA8BC;IAE1B,SAA4C;IAE5D,YAAYC,QAA2C,CAAE;QACxD,KAAK,CACJ,CAAC,8BAA8B,EAAEA,SAAS,MAAM,CAAC,UAAU,EAAEA,AAAoB,MAApBA,SAAS,MAAM,GAAS,YAAY,YAAY,EAC7GC,YAAY,iBAAiB;QAE9B,IAAI,CAAC,IAAI,GAAG;QACZ,IAAI,CAAC,QAAQ,GAAGC,OAAO,MAAM,CAAC;eAAIF;SAAS;IAC5C;AACD;AAGO,MAAMG,+CAA+CJ;IAE3C,UAAqB;IAErC,YAAYK,SAAoB,CAAE;QACjC,KAAK,CACJ,CAAC,mCAAmC,EAAEA,UAAU,kCAAkC,CAAC,EACnFH,YAAY,oCAAoC;QAEjD,IAAI,CAAC,IAAI,GAAG;QACZ,IAAI,CAAC,SAAS,GAAGG;IAClB;AACD;AAGO,MAAMC,iDAAiDN;IAE7C,UAAqB;IAErC,YAAYK,SAAoB,CAAE;QACjC,KAAK,CACJ,CAAC,2CAA2C,EAAEA,UAAU,kBAAkB,CAAC,EAC3EH,YAAY,sCAAsC;QAEnD,IAAI,CAAC,IAAI,GAAG;QACZ,IAAI,CAAC,SAAS,GAAGG;IAClB;AACD"}

package/dist/core/PersistenceRestore.d.ts

@@ -0,0 +1,21 @@
+import type { PersistenceBackend } from '../contracts/PersistenceBackend.js';
+import { type BranchId, type SessionId } from '../contracts/ids.js';
+import type { Summary } from '../contracts/summary.js';
+import type { Edge } from './graph/Edge.js';
+import type { ThoughtData } from './thought.js';
+export type RestoredBranch = {
+    readonly branchId: BranchId;
+    readonly thoughts: readonly ThoughtData[];
+};
+export type RestoredSession = {
+    readonly sessionId: SessionId;
+    readonly history: readonly ThoughtData[];
+    readonly branches: readonly RestoredBranch[];
+    readonly edges: readonly Edge[];
+    readonly summaries: readonly Summary[];
+};
+export type PersistenceRestoreSnapshot = {
+    readonly sessions: readonly RestoredSession[];
+};
+export declare function stagePersistenceRestore(backend: PersistenceBackend): Promise<PersistenceRestoreSnapshot>;
+//# sourceMappingURL=PersistenceRestore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PersistenceRestore.d.ts","sourceRoot":"","sources":["../../src/core/PersistenceRestore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,kBAAkB,EAElB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAkC,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACpG,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAavD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,MAAM,MAAM,cAAc,GAAG;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;CAC1C,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,OAAO,EAAE,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;CAC9C,CAAC;AA2EF,wBAAsB,uBAAuB,CAC5C,OAAO,EAAE,kBAAkB,GACzB,OAAO,CAAC,0BAA0B,CAAC,CAiBrC"}

package/dist/core/PersistenceRestore.js

@@ -0,0 +1,87 @@
+import { GLOBAL_SESSION_ID, asSessionId } from "../contracts/ids.js";
+import { PersistenceCompatibilityError, PersistenceUnavailableError } from "../errors.js";
+import { requireSessionScopedPersistence } from "../persistence/SessionScopedPersistence.js";
+import { assertBranchScope, assertEdgeScopes, assertPersistableThoughtCollections, assertSummaryScopes, assertThoughtScope, assertUniqueRecordIds, parsePersistenceBranchId } from "../persistence/PersistenceScope.js";
+import { EdgeStore } from "./graph/EdgeStore.js";
+function validateThoughts(sessionId, history, branches) {
+    for (const thought of history)assertThoughtScope('saveThoughtForSession', sessionId, thought);
+    for (const branch of branches)assertBranchScope('saveBranchForSession', sessionId, branch.branchId, branch.thoughts);
+    const collections = [
+        {
+            sessionId,
+            thoughts: history
+        },
+        ...branches.map((branch)=>({
+                sessionId,
+                thoughts: branch.thoughts
+            }))
+    ];
+    if (sessionId === GLOBAL_SESSION_ID) return void assertPersistableThoughtCollections(collections.map((collection)=>({
+            sessionId,
+            thoughts: collection.thoughts.filter((thought)=>void 0 !== thought.id)
+        })), `restore:${sessionId}`);
+    assertPersistableThoughtCollections(collections, `restore:${sessionId}`);
+}
+async function stageSession(persistence, sessionId) {
+    const history = await persistence.loadHistoryForSession(sessionId);
+    const listedBranches = await persistence.listBranchesForSession(sessionId);
+    const branches = [];
+    const seenBranches = new Set();
+    for (const listedBranchId of listedBranches){
+        const branchId = parsePersistenceBranchId(listedBranchId, `restore:${sessionId}:branches`);
+        if (seenBranches.has(branchId)) throw new PersistenceCompatibilityError(`restore:${sessionId}:branches`, `duplicate branch id '${branchId}'`);
+        seenBranches.add(branchId);
+        const thoughts = await persistence.loadBranchForSession(sessionId, branchId);
+        if (void 0 === thoughts) throw new PersistenceCompatibilityError(`restore:${sessionId}:branches:${branchId}`, 'listed branch is missing');
+        branches.push(Object.freeze({
+            branchId,
+            thoughts: Object.freeze([
+                ...thoughts
+            ])
+        }));
+    }
+    validateThoughts(sessionId, history, branches);
+    const edges = await persistence.loadEdges(sessionId);
+    assertEdgeScopes(sessionId, edges);
+    assertUniqueRecordIds(edges, `restore:${sessionId}:edges`, 'edge');
+    const validationStore = new EdgeStore();
+    for (const restoredEdge of edges)validationStore.addEdge(restoredEdge);
+    const summaries = await persistence.loadSummaries(sessionId);
+    assertSummaryScopes(sessionId, summaries);
+    assertUniqueRecordIds(summaries, `restore:${sessionId}:summaries`, 'summary');
+    return Object.freeze({
+        sessionId,
+        history: Object.freeze([
+            ...history
+        ]),
+        branches: Object.freeze(branches),
+        edges: Object.freeze([
+            ...edges
+        ]),
+        summaries: Object.freeze([
+            ...summaries
+        ])
+    });
+}
+async function stagePersistenceRestore(backend) {
+    const persistence = requireSessionScopedPersistence(backend, 'listSessions');
+    if (!await persistence.healthy()) throw new PersistenceUnavailableError();
+    const listedSessions = await persistence.listSessions();
+    const sessionIds = [];
+    const seen = new Set();
+    for (const listedSessionId of listedSessions){
+        const sessionId = asSessionId(listedSessionId);
+        if (!seen.has(sessionId)) {
+            seen.add(sessionId);
+            sessionIds.push(sessionId);
+        }
+    }
+    const sessions = [];
+    for (const sessionId of sessionIds)sessions.push(await stageSession(persistence, sessionId));
+    return Object.freeze({
+        sessions: Object.freeze(sessions)
+    });
+}
+export { stagePersistenceRestore };
+
+//# sourceMappingURL=PersistenceRestore.js.map

package/dist/core/PersistenceRestore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/PersistenceRestore.js","sources":["../../src/core/PersistenceRestore.ts"],"sourcesContent":["import type {\n\tPersistenceBackend,\n\tSessionScopedPersistenceBackend,\n} from '../contracts/PersistenceBackend.js';\nimport { GLOBAL_SESSION_ID, asSessionId, type BranchId, type SessionId } from '../contracts/ids.js';\nimport type { Summary } from '../contracts/summary.js';\nimport { PersistenceCompatibilityError, PersistenceUnavailableError } from '../errors.js';\nimport { requireSessionScopedPersistence } from '../persistence/SessionScopedPersistence.js';\nimport {\n\tassertBranchScope,\n\tassertEdgeScopes,\n\tassertPersistableThoughtCollections,\n\tassertSummaryScopes,\n\tassertThoughtScope,\n\tassertUniqueRecordIds,\n\tparsePersistenceBranchId,\n\ttype PersistedThoughtCollection,\n} from '../persistence/PersistenceScope.js';\nimport type { Edge } from './graph/Edge.js';\nimport { EdgeStore } from './graph/EdgeStore.js';\nimport type { ThoughtData } from './thought.js';\n\nexport type RestoredBranch = {\n\treadonly branchId: BranchId;\n\treadonly thoughts: readonly ThoughtData[];\n};\n\nexport type RestoredSession = {\n\treadonly sessionId: SessionId;\n\treadonly history: readonly ThoughtData[];\n\treadonly branches: readonly RestoredBranch[];\n\treadonly edges: readonly Edge[];\n\treadonly summaries: readonly Summary[];\n};\n\nexport type PersistenceRestoreSnapshot = {\n\treadonly sessions: readonly RestoredSession[];\n};\n\nfunction validateThoughts(\n\tsessionId: SessionId,\n\thistory: readonly ThoughtData[],\n\tbranches: readonly RestoredBranch[]\n): void {\n\tfor (const thought of history) assertThoughtScope('saveThoughtForSession', sessionId, thought);\n\tfor (const branch of branches) {\n\t\tassertBranchScope('saveBranchForSession', sessionId, branch.branchId, branch.thoughts);\n\t}\n\tconst collections: PersistedThoughtCollection[] = [\n\t\t{ sessionId, thoughts: history },\n\t\t...branches.map((branch) => ({ sessionId, thoughts: branch.thoughts })),\n\t];\n\tif (sessionId === GLOBAL_SESSION_ID) {\n\t\tassertPersistableThoughtCollections(\n\t\t\tcollections.map((collection) => ({\n\t\t\t\tsessionId,\n\t\t\t\tthoughts: collection.thoughts.filter((thought) => thought.id !== undefined),\n\t\t\t})),\n\t\t\t`restore:${sessionId}`\n\t\t);\n\t\treturn;\n\t}\n\tassertPersistableThoughtCollections(collections, `restore:${sessionId}`);\n}\n\nasync function stageSession(\n\tpersistence: SessionScopedPersistenceBackend,\n\tsessionId: SessionId\n): Promise<RestoredSession> {\n\tconst history = await persistence.loadHistoryForSession(sessionId);\n\tconst listedBranches = await persistence.listBranchesForSession(sessionId);\n\tconst branches: RestoredBranch[] = [];\n\tconst seenBranches = new Set<BranchId>();\n\tfor (const listedBranchId of listedBranches) {\n\t\tconst branchId = parsePersistenceBranchId(listedBranchId, `restore:${sessionId}:branches`);\n\t\tif (seenBranches.has(branchId)) {\n\t\t\tthrow new PersistenceCompatibilityError(\n\t\t\t\t`restore:${sessionId}:branches`,\n\t\t\t\t`duplicate branch id '${branchId}'`\n\t\t\t);\n\t\t}\n\t\tseenBranches.add(branchId);\n\t\tconst thoughts = await persistence.loadBranchForSession(sessionId, branchId);\n\t\tif (thoughts === undefined) {\n\t\t\tthrow new PersistenceCompatibilityError(\n\t\t\t\t`restore:${sessionId}:branches:${branchId}`,\n\t\t\t\t'listed branch is missing'\n\t\t\t);\n\t\t}\n\t\tbranches.push(Object.freeze({ branchId, thoughts: Object.freeze([...thoughts]) }));\n\t}\n\tvalidateThoughts(sessionId, history, branches);\n\n\tconst edges = await persistence.loadEdges(sessionId);\n\tassertEdgeScopes(sessionId, edges);\n\tassertUniqueRecordIds(edges, `restore:${sessionId}:edges`, 'edge');\n\tconst validationStore = new EdgeStore();\n\tfor (const restoredEdge of edges) validationStore.addEdge(restoredEdge);\n\n\tconst summaries = await persistence.loadSummaries(sessionId);\n\tassertSummaryScopes(sessionId, summaries);\n\tassertUniqueRecordIds(summaries, `restore:${sessionId}:summaries`, 'summary');\n\n\treturn Object.freeze({\n\t\tsessionId,\n\t\thistory: Object.freeze([...history]),\n\t\tbranches: Object.freeze(branches),\n\t\tedges: Object.freeze([...edges]),\n\t\tsummaries: Object.freeze([...summaries]),\n\t});\n}\n\nexport async function stagePersistenceRestore(\n\tbackend: PersistenceBackend\n): Promise<PersistenceRestoreSnapshot> {\n\tconst persistence = requireSessionScopedPersistence(backend, 'listSessions');\n\tif (!(await persistence.healthy())) throw new PersistenceUnavailableError();\n\n\tconst listedSessions = await persistence.listSessions();\n\tconst sessionIds: SessionId[] = [];\n\tconst seen = new Set<SessionId>();\n\tfor (const listedSessionId of listedSessions) {\n\t\tconst sessionId = asSessionId(listedSessionId);\n\t\tif (seen.has(sessionId)) continue;\n\t\tseen.add(sessionId);\n\t\tsessionIds.push(sessionId);\n\t}\n\n\tconst sessions: RestoredSession[] = [];\n\tfor (const sessionId of sessionIds) sessions.push(await stageSession(persistence, sessionId));\n\treturn Object.freeze({ sessions: Object.freeze(sessions) });\n}\n"],"names":["validateThoughts","sessionId","history","branches","thought","assertThoughtScope","branch","assertBranchScope","collections","GLOBAL_SESSION_ID","assertPersistableThoughtCollections","collection","undefined","stageSession","persistence","listedBranches","seenBranches","Set","listedBranchId","branchId","parsePersistenceBranchId","PersistenceCompatibilityError","thoughts","Object","edges","assertEdgeScopes","assertUniqueRecordIds","validationStore","EdgeStore","restoredEdge","summaries","assertSummaryScopes","stagePersistenceRestore","backend","requireSessionScopedPersistence","PersistenceUnavailableError","listedSessions","sessionIds","seen","listedSessionId","asSessionId","sessions"],"mappings":"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"}

package/dist/core/PersistenceWorkQueue.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Pure attributable queue for accepted persistence work.
+ *
+ * @module core/PersistenceWorkQueue
+ */
+import type { PersistenceGenerationResult, PersistenceWork, PersistenceWorkFailure, PersistenceWorkToken } from '../contracts/persistence-work.js';
+import type { BranchId, SessionId } from '../contracts/ids.js';
+import type { Summary } from './compression/Summary.js';
+import type { Edge } from './graph/Edge.js';
+import type { ThoughtData } from './thought.js';
+/** Selects whether retained terminal failures are eligible for a generation. */
+export type PersistenceSelectionMode = 'explicit' | 'background';
+type WorkKind = PersistenceWork['kind'];
+type WorkOf<K extends WorkKind> = Extract<PersistenceWork, {
+    readonly kind: K;
+}>;
+/**
+ * Stores accepted persistence work independently from live session state.
+ *
+ * Thought entries retain FIFO acceptance order. Auxiliary snapshots coalesce at
+ * their stable coordinate and use versioned compare-and-set acknowledgement.
+ * Generation state remains caller-owned in a `Set` passed to selection methods.
+ *
+ * @example
+ * ```ts
+ * const queue = new PersistenceWorkQueue();
+ * queue.enqueueThought(sessionId, thought);
+ * const selected = new Set<PersistenceWorkToken>();
+ * const work = queue.nextEligibleWork(selected, 'explicit');
+ * if (work !== undefined) queue.acknowledgeSuccess(work);
+ * ```
+ */
+export declare class PersistenceWorkQueue {
+    private readonly _thoughts;
+    private readonly _branches;
+    private readonly _edges;
+    private readonly _summaries;
+    private readonly _branchVersions;
+    private readonly _edgeVersions;
+    private readonly _summaryVersions;
+    private _nextSequence;
+    /**
+     * Accepts one thought as a distinct FIFO work item.
+     *
+     * @param sessionId - Session that owns the thought write.
+     * @param thought - Thought payload accepted by the coordinator.
+     * @returns The exact immutable work handle used for acknowledgement.
+     */
+    enqueueThought(sessionId: SessionId, thought: ThoughtData): WorkOf<'thought'>;
+    /**
+     * Replaces the pending snapshot for one session-owned branch.
+     *
+     * @param sessionId - Session that owns the branch.
+     * @param branchId - Stable branch coordinate within the session.
+     * @param thoughts - Branch snapshot; its array is copied before storage.
+     * @returns The new immutable, versioned work handle.
+     */
+    replaceBranch(sessionId: SessionId, branchId: BranchId, thoughts: readonly ThoughtData[]): WorkOf<'branch'>;
+    /**
+     * @param sessionId - Session that owns the branch.
+     * @param branchId - Stable branch coordinate within the session.
+     * @returns The new immutable, versioned deletion work handle.
+     */
+    deleteBranch(sessionId: SessionId, branchId: BranchId): WorkOf<'branch'>;
+    /**
+     * Replaces the pending edge snapshot for a session.
+     *
+     * @param sessionId - Stable session coordinate for the edge set.
+     * @param edges - Edge snapshot; its array is copied before storage.
+     * @returns The new immutable, versioned work handle.
+     */
+    replaceEdges(sessionId: SessionId, edges: readonly Edge[]): WorkOf<'edge'>;
+    /**
+     * Replaces the pending summary snapshot for a session.
+     *
+     * @param sessionId - Stable session coordinate for the summary set.
+     * @param summaries - Summary snapshot; its array is copied before storage.
+     * @returns The new immutable, versioned work handle.
+     */
+    replaceSummaries(sessionId: SessionId, summaries: readonly Summary[]): WorkOf<'summary'>;
+    /**
+     * Reports whether a generation can select current work.
+     *
+     * @param selectedTokens - Tokens already selected by the caller's generation.
+     * @param mode - Explicit generations re-arm failures; background generations skip them.
+     * @param sessionId - Optional session projection.
+     * @returns `true` when at least one current entry is eligible.
+     */
+    hasEligibleWork(selectedTokens: ReadonlySet<PersistenceWorkToken>, mode: PersistenceSelectionMode, sessionId?: SessionId): boolean;
+    /**
+     * Selects the oldest currently eligible work and records it in the generation set.
+     *
+     * @param selectedTokens - Mutable set owned by the caller's generation.
+     * @param mode - Explicit generations re-arm failures; background generations skip them.
+     * @param sessionId - Optional session projection.
+     * @returns The selected work, or `undefined` when no current entry is eligible.
+     */
+    nextEligibleWork(selectedTokens: Set<PersistenceWorkToken>, mode: PersistenceSelectionMode, sessionId?: SessionId): PersistenceWork | undefined;
+    /**
+     * Acknowledges successful persistence using exact token/version CAS semantics.
+     *
+     * @param work - Previously selected work handle.
+     */
+    acknowledgeSuccess(work: PersistenceWork): void;
+    /**
+     * Attaches a terminal failure only when both work and failure still match current work.
+     *
+     * @param work - Previously selected work handle.
+     * @param failure - Terminal backend failure attributed to that handle.
+     */
+    acknowledgeFailure(work: PersistenceWork, failure: PersistenceWorkFailure): void;
+    /**
+     * Returns an immutable acceptance-ordered snapshot of current terminal failures.
+     *
+     * @param selectedTokens - Optional generation-token projection.
+     * @param sessionId - Optional session projection.
+     * @returns A fresh readonly failure array containing only failures on current entries.
+     */
+    currentFailures(selectedTokens?: ReadonlySet<PersistenceWorkToken>, sessionId?: SessionId): readonly PersistenceWorkFailure[];
+    /**
+     * Captures the current immutable result for a generation or session projection.
+     *
+     * @param selectedTokens - Optional generation-token projection.
+     * @param sessionId - Optional session projection.
+     * @returns A result containing a fresh readonly failure snapshot.
+     */
+    generationResult(selectedTokens?: ReadonlySet<PersistenceWorkToken>, sessionId?: SessionId): PersistenceGenerationResult;
+    /** @returns Number of accepted thought writes not yet acknowledged successful. */
+    get pendingThoughtCount(): number;
+    /** @returns Number of all current thought and coalesced auxiliary entries. */
+    get pendingWorkCount(): number;
+    /** @returns Whether any accepted work remains for a session across all work kinds. */
+    hasSessionWork(sessionId: SessionId): boolean;
+    /** @returns Whether current retained work for a session owns a terminal failure. */
+    hasSessionTerminalFailure(sessionId: SessionId): boolean;
+    /**
+     * Forgets version coordinates only after all accepted work for a session is gone.
+     *
+     * @returns `false` without mutation while any accepted work remains.
+     */
+    forgetQuiescentSession(sessionId: SessionId): boolean;
+    /** Discards every retained work item and version coordinate for one deleted session. */
+    discardSession(sessionId: SessionId): void;
+    /** Discards all retained work after a successful durable global reset. */
+    discardAll(): void;
+    private _accept;
+    private _entries;
+    private _findEligible;
+    private _modeAllows;
+    private _currentEntry;
+    private _matchesWork;
+    private _matchesFailure;
+}
+export {};
+//# sourceMappingURL=PersistenceWorkQueue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PersistenceWorkQueue.d.ts","sourceRoot":"","sources":["../../src/core/PersistenceWorkQueue.ts"],"names":[],"mappings":"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"}