@iworkforces/tracelattice 2.0.3

package/dist/core/PersistenceWorkQueue.js

@@ -0,0 +1,298 @@
+import { assertNever } from "../utils.js";
+class PersistenceWorkQueue {
+    _thoughts = [];
+    _branches = new Map();
+    _edges = new Map();
+    _summaries = new Map();
+    _branchVersions = new Map();
+    _edgeVersions = new Map();
+    _summaryVersions = new Map();
+    _nextSequence = 1;
+    enqueueThought(sessionId, thought) {
+        const acceptance = this._accept();
+        const work = Object.freeze({
+            kind: 'thought',
+            token: acceptance.token,
+            sessionId,
+            thought
+        });
+        this._thoughts.push({
+            acceptedSequence: acceptance.sequence,
+            work,
+            terminalFailure: void 0
+        });
+        return work;
+    }
+    replaceBranch(sessionId, branchId, thoughts) {
+        const versionMap = this._branchVersions.get(sessionId) ?? new Map();
+        this._branchVersions.set(sessionId, versionMap);
+        const version = (versionMap.get(branchId) ?? 0) + 1;
+        versionMap.set(branchId, version);
+        const acceptance = this._accept();
+        const work = Object.freeze({
+            kind: 'branch',
+            operation: 'save',
+            token: acceptance.token,
+            sessionId,
+            key: branchId,
+            version,
+            snapshot: Object.freeze([
+                ...thoughts
+            ])
+        });
+        const branchMap = this._branches.get(sessionId) ?? new Map();
+        this._branches.set(sessionId, branchMap);
+        branchMap.set(branchId, {
+            acceptedSequence: acceptance.sequence,
+            work,
+            terminalFailure: void 0
+        });
+        return work;
+    }
+    deleteBranch(sessionId, branchId) {
+        const versionMap = this._branchVersions.get(sessionId) ?? new Map();
+        this._branchVersions.set(sessionId, versionMap);
+        const version = (versionMap.get(branchId) ?? 0) + 1;
+        versionMap.set(branchId, version);
+        const acceptance = this._accept();
+        const work = Object.freeze({
+            kind: 'branch',
+            operation: 'delete',
+            token: acceptance.token,
+            sessionId,
+            key: branchId,
+            version
+        });
+        const branchMap = this._branches.get(sessionId) ?? new Map();
+        this._branches.set(sessionId, branchMap);
+        branchMap.set(branchId, {
+            acceptedSequence: acceptance.sequence,
+            work,
+            terminalFailure: void 0
+        });
+        return work;
+    }
+    replaceEdges(sessionId, edges) {
+        const version = (this._edgeVersions.get(sessionId) ?? 0) + 1;
+        this._edgeVersions.set(sessionId, version);
+        const acceptance = this._accept();
+        const work = Object.freeze({
+            kind: 'edge',
+            token: acceptance.token,
+            sessionId,
+            key: sessionId,
+            version,
+            snapshot: Object.freeze([
+                ...edges
+            ])
+        });
+        this._edges.set(sessionId, {
+            acceptedSequence: acceptance.sequence,
+            work,
+            terminalFailure: void 0
+        });
+        return work;
+    }
+    replaceSummaries(sessionId, summaries) {
+        const version = (this._summaryVersions.get(sessionId) ?? 0) + 1;
+        this._summaryVersions.set(sessionId, version);
+        const acceptance = this._accept();
+        const work = Object.freeze({
+            kind: 'summary',
+            token: acceptance.token,
+            sessionId,
+            key: sessionId,
+            version,
+            snapshot: Object.freeze([
+                ...summaries
+            ])
+        });
+        this._summaries.set(sessionId, {
+            acceptedSequence: acceptance.sequence,
+            work,
+            terminalFailure: void 0
+        });
+        return work;
+    }
+    hasEligibleWork(selectedTokens, mode, sessionId) {
+        return void 0 !== this._findEligible(selectedTokens, mode, sessionId);
+    }
+    nextEligibleWork(selectedTokens, mode, sessionId) {
+        const entry = this._findEligible(selectedTokens, mode, sessionId);
+        if (void 0 === entry) return;
+        selectedTokens.add(entry.work.token);
+        return entry.work;
+    }
+    acknowledgeSuccess(work) {
+        const entry = this._currentEntry(work);
+        if (void 0 === entry) return;
+        switch(work.kind){
+            case 'thought':
+                {
+                    const index = this._thoughts.findIndex((candidate)=>candidate === entry);
+                    if (index >= 0) this._thoughts.splice(index, 1);
+                    return;
+                }
+            case 'branch':
+                this._branches.get(work.sessionId)?.delete(work.key);
+                return;
+            case 'edge':
+                this._edges.delete(work.key);
+                return;
+            case 'summary':
+                this._summaries.delete(work.key);
+                return;
+            default:
+                assertNever(work);
+        }
+    }
+    acknowledgeFailure(work, failure) {
+        if (!this._matchesFailure(work, failure)) return;
+        const entry = this._currentEntry(work);
+        if (void 0 !== entry) entry.terminalFailure = Object.freeze({
+            ...failure
+        });
+    }
+    currentFailures(selectedTokens, sessionId) {
+        const failures = this._entries().filter((entry)=>void 0 !== entry.terminalFailure && (void 0 === selectedTokens || selectedTokens.has(entry.work.token)) && (void 0 === sessionId || entry.work.sessionId === sessionId)).sort((left, right)=>left.acceptedSequence - right.acceptedSequence).flatMap((entry)=>void 0 === entry.terminalFailure ? [] : [
+                entry.terminalFailure
+            ]);
+        return Object.freeze(failures);
+    }
+    generationResult(selectedTokens, sessionId) {
+        return Object.freeze({
+            failures: this.currentFailures(selectedTokens, sessionId)
+        });
+    }
+    get pendingThoughtCount() {
+        return this._thoughts.length;
+    }
+    get pendingWorkCount() {
+        let branchCount = 0;
+        for (const branches of this._branches.values())branchCount += branches.size;
+        return this._thoughts.length + branchCount + this._edges.size + this._summaries.size;
+    }
+    hasSessionWork(sessionId) {
+        return this._entries().some((entry)=>entry.work.sessionId === sessionId);
+    }
+    hasSessionTerminalFailure(sessionId) {
+        return this.currentFailures(void 0, sessionId).length > 0;
+    }
+    forgetQuiescentSession(sessionId) {
+        if (this.hasSessionWork(sessionId)) return false;
+        this._branches.delete(sessionId);
+        this._branchVersions.delete(sessionId);
+        this._edgeVersions.delete(sessionId);
+        this._summaryVersions.delete(sessionId);
+        return true;
+    }
+    discardSession(sessionId) {
+        for(let index = this._thoughts.length - 1; index >= 0; index -= 1)if (this._thoughts[index]?.work.sessionId === sessionId) this._thoughts.splice(index, 1);
+        this._branches.delete(sessionId);
+        this._edges.delete(sessionId);
+        this._summaries.delete(sessionId);
+        this._branchVersions.delete(sessionId);
+        this._edgeVersions.delete(sessionId);
+        this._summaryVersions.delete(sessionId);
+    }
+    discardAll() {
+        this._thoughts.length = 0;
+        this._branches.clear();
+        this._edges.clear();
+        this._summaries.clear();
+        this._branchVersions.clear();
+        this._edgeVersions.clear();
+        this._summaryVersions.clear();
+    }
+    _accept() {
+        const sequence = this._nextSequence;
+        this._nextSequence += 1;
+        return {
+            token: `persistence-work-${sequence}`,
+            sequence
+        };
+    }
+    _entries() {
+        const entries = [
+            ...this._thoughts
+        ];
+        for (const branches of this._branches.values())entries.push(...branches.values());
+        entries.push(...this._edges.values(), ...this._summaries.values());
+        return entries;
+    }
+    _findEligible(selectedTokens, mode, sessionId) {
+        let oldest;
+        for (const entry of this._entries()){
+            if (!selectedTokens.has(entry.work.token)) {
+                if (void 0 === sessionId || entry.work.sessionId === sessionId) {
+                    if (this._modeAllows(mode, void 0 !== entry.terminalFailure)) {
+                        if (void 0 === oldest || entry.acceptedSequence < oldest.acceptedSequence) oldest = entry;
+                    }
+                }
+            }
+        }
+        return oldest;
+    }
+    _modeAllows(mode, hasTerminalFailure) {
+        switch(mode){
+            case 'explicit':
+                return true;
+            case 'background':
+                return !hasTerminalFailure;
+            default:
+                return assertNever(mode);
+        }
+    }
+    _currentEntry(work) {
+        let entry;
+        switch(work.kind){
+            case 'thought':
+                entry = this._thoughts.find((candidate)=>candidate.work.token === work.token);
+                break;
+            case 'branch':
+                entry = this._branches.get(work.sessionId)?.get(work.key);
+                break;
+            case 'edge':
+                entry = this._edges.get(work.key);
+                break;
+            case 'summary':
+                entry = this._summaries.get(work.key);
+                break;
+            default:
+                return assertNever(work);
+        }
+        return void 0 !== entry && this._matchesWork(entry.work, work) ? entry : void 0;
+    }
+    _matchesWork(current, selected) {
+        if (current.kind !== selected.kind || current.token !== selected.token || current.sessionId !== selected.sessionId) return false;
+        switch(selected.kind){
+            case 'thought':
+                return 'thought' === current.kind;
+            case 'branch':
+                return 'branch' === current.kind && current.operation === selected.operation && current.key === selected.key && current.version === selected.version;
+            case 'edge':
+                return 'edge' === current.kind && current.key === selected.key && current.version === selected.version;
+            case 'summary':
+                return 'summary' === current.kind && current.key === selected.key && current.version === selected.version;
+            default:
+                return assertNever(selected);
+        }
+    }
+    _matchesFailure(work, failure) {
+        if (work.kind !== failure.kind || work.token !== failure.token || work.sessionId !== failure.sessionId) return false;
+        switch(work.kind){
+            case 'thought':
+                return true;
+            case 'branch':
+                return 'branch' === failure.kind && work.operation === failure.operation && work.key === failure.key && work.version === failure.version;
+            case 'edge':
+            case 'summary':
+                return 'key' in failure && work.key === failure.key && work.version === failure.version;
+            default:
+                return assertNever(work);
+        }
+    }
+}
+export { PersistenceWorkQueue };
+
+//# sourceMappingURL=PersistenceWorkQueue.js.map

package/dist/core/PersistenceWorkQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/PersistenceWorkQueue.js","sources":["../../src/core/PersistenceWorkQueue.ts"],"sourcesContent":["/**\n * Pure attributable queue for accepted persistence work.\n *\n * @module core/PersistenceWorkQueue\n */\n\n// allow: SIZE_OK - Task 8 requires this single-responsibility queue in exactly one production file.\n\nimport type {\n\tPersistenceGenerationResult,\n\tPersistenceWork,\n\tPersistenceWorkFailure,\n\tPersistenceWorkToken,\n} from '../contracts/persistence-work.js';\nimport type { BranchId, SessionId } from '../contracts/ids.js';\nimport { assertNever } from '../utils.js';\nimport type { Summary } from './compression/Summary.js';\nimport type { Edge } from './graph/Edge.js';\nimport type { ThoughtData } from './thought.js';\n\n/** Selects whether retained terminal failures are eligible for a generation. */\nexport type PersistenceSelectionMode = 'explicit' | 'background';\n\ntype WorkKind = PersistenceWork['kind'];\ntype WorkOf<K extends WorkKind> = Extract<PersistenceWork, { readonly kind: K }>;\n\ntype QueueEntry<K extends WorkKind> = {\n\treadonly acceptedSequence: number;\n\treadonly work: WorkOf<K>;\n\tterminalFailure: PersistenceWorkFailure | undefined;\n};\n\ntype ThoughtEntry = QueueEntry<'thought'>;\ntype BranchEntry = QueueEntry<'branch'>;\ntype EdgeEntry = QueueEntry<'edge'>;\ntype SummaryEntry = QueueEntry<'summary'>;\ntype AnyQueueEntry = ThoughtEntry | BranchEntry | EdgeEntry | SummaryEntry;\n\ntype Acceptance = {\n\treadonly token: PersistenceWorkToken;\n\treadonly sequence: number;\n};\n\n/**\n * Stores accepted persistence work independently from live session state.\n *\n * Thought entries retain FIFO acceptance order. Auxiliary snapshots coalesce at\n * their stable coordinate and use versioned compare-and-set acknowledgement.\n * Generation state remains caller-owned in a `Set` passed to selection methods.\n *\n * @example\n * ```ts\n * const queue = new PersistenceWorkQueue();\n * queue.enqueueThought(sessionId, thought);\n * const selected = new Set<PersistenceWorkToken>();\n * const work = queue.nextEligibleWork(selected, 'explicit');\n * if (work !== undefined) queue.acknowledgeSuccess(work);\n * ```\n */\nexport class PersistenceWorkQueue {\n\tprivate readonly _thoughts: ThoughtEntry[] = [];\n\tprivate readonly _branches = new Map<SessionId, Map<BranchId, BranchEntry>>();\n\tprivate readonly _edges = new Map<SessionId, EdgeEntry>();\n\tprivate readonly _summaries = new Map<SessionId, SummaryEntry>();\n\n\tprivate readonly _branchVersions = new Map<SessionId, Map<BranchId, number>>();\n\tprivate readonly _edgeVersions = new Map<SessionId, number>();\n\tprivate readonly _summaryVersions = new Map<SessionId, number>();\n\tprivate _nextSequence = 1;\n\n\t/**\n\t * Accepts one thought as a distinct FIFO work item.\n\t *\n\t * @param sessionId - Session that owns the thought write.\n\t * @param thought - Thought payload accepted by the coordinator.\n\t * @returns The exact immutable work handle used for acknowledgement.\n\t */\n\tpublic enqueueThought(sessionId: SessionId, thought: ThoughtData): WorkOf<'thought'> {\n\t\tconst acceptance = this._accept();\n\t\tconst work: WorkOf<'thought'> = Object.freeze({\n\t\t\tkind: 'thought',\n\t\t\ttoken: acceptance.token,\n\t\t\tsessionId,\n\t\t\tthought,\n\t\t});\n\t\tthis._thoughts.push({\n\t\t\tacceptedSequence: acceptance.sequence,\n\t\t\twork,\n\t\t\tterminalFailure: undefined,\n\t\t});\n\t\treturn work;\n\t}\n\n\t/**\n\t * Replaces the pending snapshot for one session-owned branch.\n\t *\n\t * @param sessionId - Session that owns the branch.\n\t * @param branchId - Stable branch coordinate within the session.\n\t * @param thoughts - Branch snapshot; its array is copied before storage.\n\t * @returns The new immutable, versioned work handle.\n\t */\n\tpublic replaceBranch(\n\t\tsessionId: SessionId,\n\t\tbranchId: BranchId,\n\t\tthoughts: readonly ThoughtData[]\n\t): WorkOf<'branch'> {\n\t\tconst versionMap = this._branchVersions.get(sessionId) ?? new Map<BranchId, number>();\n\t\tthis._branchVersions.set(sessionId, versionMap);\n\t\tconst version = (versionMap.get(branchId) ?? 0) + 1;\n\t\tversionMap.set(branchId, version);\n\n\t\tconst acceptance = this._accept();\n\t\tconst work: WorkOf<'branch'> = Object.freeze({\n\t\t\tkind: 'branch',\n\t\t\toperation: 'save',\n\t\t\ttoken: acceptance.token,\n\t\t\tsessionId,\n\t\t\tkey: branchId,\n\t\t\tversion,\n\t\t\tsnapshot: Object.freeze([...thoughts]),\n\t\t});\n\t\tconst branchMap = this._branches.get(sessionId) ?? new Map<BranchId, BranchEntry>();\n\t\tthis._branches.set(sessionId, branchMap);\n\t\tbranchMap.set(branchId, {\n\t\t\tacceptedSequence: acceptance.sequence,\n\t\t\twork,\n\t\t\tterminalFailure: undefined,\n\t\t});\n\t\treturn work;\n\t}\n\n\t/**\n\t * @param sessionId - Session that owns the branch.\n\t * @param branchId - Stable branch coordinate within the session.\n\t * @returns The new immutable, versioned deletion work handle.\n\t */\n\tpublic deleteBranch(sessionId: SessionId, branchId: BranchId): WorkOf<'branch'> {\n\t\tconst versionMap = this._branchVersions.get(sessionId) ?? new Map<BranchId, number>();\n\t\tthis._branchVersions.set(sessionId, versionMap);\n\t\tconst version = (versionMap.get(branchId) ?? 0) + 1;\n\t\tversionMap.set(branchId, version);\n\n\t\tconst acceptance = this._accept();\n\t\tconst work: WorkOf<'branch'> = Object.freeze({\n\t\t\tkind: 'branch',\n\t\t\toperation: 'delete',\n\t\t\ttoken: acceptance.token,\n\t\t\tsessionId,\n\t\t\tkey: branchId,\n\t\t\tversion,\n\t\t});\n\t\tconst branchMap = this._branches.get(sessionId) ?? new Map<BranchId, BranchEntry>();\n\t\tthis._branches.set(sessionId, branchMap);\n\t\tbranchMap.set(branchId, {\n\t\t\tacceptedSequence: acceptance.sequence,\n\t\t\twork,\n\t\t\tterminalFailure: undefined,\n\t\t});\n\t\treturn work;\n\t}\n\n\t/**\n\t * Replaces the pending edge snapshot for a session.\n\t *\n\t * @param sessionId - Stable session coordinate for the edge set.\n\t * @param edges - Edge snapshot; its array is copied before storage.\n\t * @returns The new immutable, versioned work handle.\n\t */\n\tpublic replaceEdges(sessionId: SessionId, edges: readonly Edge[]): WorkOf<'edge'> {\n\t\tconst version = (this._edgeVersions.get(sessionId) ?? 0) + 1;\n\t\tthis._edgeVersions.set(sessionId, version);\n\t\tconst acceptance = this._accept();\n\t\tconst work: WorkOf<'edge'> = Object.freeze({\n\t\t\tkind: 'edge',\n\t\t\ttoken: acceptance.token,\n\t\t\tsessionId,\n\t\t\tkey: sessionId,\n\t\t\tversion,\n\t\t\tsnapshot: Object.freeze([...edges]),\n\t\t});\n\t\tthis._edges.set(sessionId, {\n\t\t\tacceptedSequence: acceptance.sequence,\n\t\t\twork,\n\t\t\tterminalFailure: undefined,\n\t\t});\n\t\treturn work;\n\t}\n\n\t/**\n\t * Replaces the pending summary snapshot for a session.\n\t *\n\t * @param sessionId - Stable session coordinate for the summary set.\n\t * @param summaries - Summary snapshot; its array is copied before storage.\n\t * @returns The new immutable, versioned work handle.\n\t */\n\tpublic replaceSummaries(sessionId: SessionId, summaries: readonly Summary[]): WorkOf<'summary'> {\n\t\tconst version = (this._summaryVersions.get(sessionId) ?? 0) + 1;\n\t\tthis._summaryVersions.set(sessionId, version);\n\t\tconst acceptance = this._accept();\n\t\tconst work: WorkOf<'summary'> = Object.freeze({\n\t\t\tkind: 'summary',\n\t\t\ttoken: acceptance.token,\n\t\t\tsessionId,\n\t\t\tkey: sessionId,\n\t\t\tversion,\n\t\t\tsnapshot: Object.freeze([...summaries]),\n\t\t});\n\t\tthis._summaries.set(sessionId, {\n\t\t\tacceptedSequence: acceptance.sequence,\n\t\t\twork,\n\t\t\tterminalFailure: undefined,\n\t\t});\n\t\treturn work;\n\t}\n\n\t/**\n\t * Reports whether a generation can select current work.\n\t *\n\t * @param selectedTokens - Tokens already selected by the caller's generation.\n\t * @param mode - Explicit generations re-arm failures; background generations skip them.\n\t * @param sessionId - Optional session projection.\n\t * @returns `true` when at least one current entry is eligible.\n\t */\n\tpublic hasEligibleWork(\n\t\tselectedTokens: ReadonlySet<PersistenceWorkToken>,\n\t\tmode: PersistenceSelectionMode,\n\t\tsessionId?: SessionId\n\t): boolean {\n\t\treturn this._findEligible(selectedTokens, mode, sessionId) !== undefined;\n\t}\n\n\t/**\n\t * Selects the oldest currently eligible work and records it in the generation set.\n\t *\n\t * @param selectedTokens - Mutable set owned by the caller's generation.\n\t * @param mode - Explicit generations re-arm failures; background generations skip them.\n\t * @param sessionId - Optional session projection.\n\t * @returns The selected work, or `undefined` when no current entry is eligible.\n\t */\n\tpublic nextEligibleWork(\n\t\tselectedTokens: Set<PersistenceWorkToken>,\n\t\tmode: PersistenceSelectionMode,\n\t\tsessionId?: SessionId\n\t): PersistenceWork | undefined {\n\t\tconst entry = this._findEligible(selectedTokens, mode, sessionId);\n\t\tif (entry === undefined) return undefined;\n\t\tselectedTokens.add(entry.work.token);\n\t\treturn entry.work;\n\t}\n\n\t/**\n\t * Acknowledges successful persistence using exact token/version CAS semantics.\n\t *\n\t * @param work - Previously selected work handle.\n\t */\n\tpublic acknowledgeSuccess(work: PersistenceWork): void {\n\t\tconst entry = this._currentEntry(work);\n\t\tif (entry === undefined) return;\n\t\tswitch (work.kind) {\n\t\t\tcase 'thought': {\n\t\t\t\tconst index = this._thoughts.findIndex((candidate) => candidate === entry);\n\t\t\t\tif (index >= 0) this._thoughts.splice(index, 1);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tcase 'branch':\n\t\t\t\tthis._branches.get(work.sessionId)?.delete(work.key);\n\t\t\t\treturn;\n\t\t\tcase 'edge':\n\t\t\t\tthis._edges.delete(work.key);\n\t\t\t\treturn;\n\t\t\tcase 'summary':\n\t\t\t\tthis._summaries.delete(work.key);\n\t\t\t\treturn;\n\t\t\tdefault:\n\t\t\t\tassertNever(work);\n\t\t}\n\t}\n\n\t/**\n\t * Attaches a terminal failure only when both work and failure still match current work.\n\t *\n\t * @param work - Previously selected work handle.\n\t * @param failure - Terminal backend failure attributed to that handle.\n\t */\n\tpublic acknowledgeFailure(work: PersistenceWork, failure: PersistenceWorkFailure): void {\n\t\tif (!this._matchesFailure(work, failure)) return;\n\t\tconst entry = this._currentEntry(work);\n\t\tif (entry !== undefined) entry.terminalFailure = Object.freeze({ ...failure });\n\t}\n\n\t/**\n\t * Returns an immutable acceptance-ordered snapshot of current terminal failures.\n\t *\n\t * @param selectedTokens - Optional generation-token projection.\n\t * @param sessionId - Optional session projection.\n\t * @returns A fresh readonly failure array containing only failures on current entries.\n\t */\n\tpublic currentFailures(\n\t\tselectedTokens?: ReadonlySet<PersistenceWorkToken>,\n\t\tsessionId?: SessionId\n\t): readonly PersistenceWorkFailure[] {\n\t\tconst failures = this._entries()\n\t\t\t.filter(\n\t\t\t\t(entry) =>\n\t\t\t\t\tentry.terminalFailure !== undefined &&\n\t\t\t\t\t(selectedTokens === undefined || selectedTokens.has(entry.work.token)) &&\n\t\t\t\t\t(sessionId === undefined || entry.work.sessionId === sessionId)\n\t\t\t)\n\t\t\t.sort((left, right) => left.acceptedSequence - right.acceptedSequence)\n\t\t\t.flatMap((entry) => (entry.terminalFailure === undefined ? [] : [entry.terminalFailure]));\n\t\treturn Object.freeze(failures);\n\t}\n\n\t/**\n\t * Captures the current immutable result for a generation or session projection.\n\t *\n\t * @param selectedTokens - Optional generation-token projection.\n\t * @param sessionId - Optional session projection.\n\t * @returns A result containing a fresh readonly failure snapshot.\n\t */\n\tpublic generationResult(\n\t\tselectedTokens?: ReadonlySet<PersistenceWorkToken>,\n\t\tsessionId?: SessionId\n\t): PersistenceGenerationResult {\n\t\treturn Object.freeze({ failures: this.currentFailures(selectedTokens, sessionId) });\n\t}\n\n\t/** @returns Number of accepted thought writes not yet acknowledged successful. */\n\tpublic get pendingThoughtCount(): number {\n\t\treturn this._thoughts.length;\n\t}\n\n\t/** @returns Number of all current thought and coalesced auxiliary entries. */\n\tpublic get pendingWorkCount(): number {\n\t\tlet branchCount = 0;\n\t\tfor (const branches of this._branches.values()) branchCount += branches.size;\n\t\treturn this._thoughts.length + branchCount + this._edges.size + this._summaries.size;\n\t}\n\n\t/** @returns Whether any accepted work remains for a session across all work kinds. */\n\tpublic hasSessionWork(sessionId: SessionId): boolean {\n\t\treturn this._entries().some((entry) => entry.work.sessionId === sessionId);\n\t}\n\n\t/** @returns Whether current retained work for a session owns a terminal failure. */\n\tpublic hasSessionTerminalFailure(sessionId: SessionId): boolean {\n\t\treturn this.currentFailures(undefined, sessionId).length > 0;\n\t}\n\n\t/**\n\t * Forgets version coordinates only after all accepted work for a session is gone.\n\t *\n\t * @returns `false` without mutation while any accepted work remains.\n\t */\n\tpublic forgetQuiescentSession(sessionId: SessionId): boolean {\n\t\tif (this.hasSessionWork(sessionId)) return false;\n\t\tthis._branches.delete(sessionId);\n\t\tthis._branchVersions.delete(sessionId);\n\t\tthis._edgeVersions.delete(sessionId);\n\t\tthis._summaryVersions.delete(sessionId);\n\t\treturn true;\n\t}\n\n\t/** Discards every retained work item and version coordinate for one deleted session. */\n\tpublic discardSession(sessionId: SessionId): void {\n\t\tfor (let index = this._thoughts.length - 1; index >= 0; index -= 1) {\n\t\t\tif (this._thoughts[index]?.work.sessionId === sessionId) this._thoughts.splice(index, 1);\n\t\t}\n\t\tthis._branches.delete(sessionId);\n\t\tthis._edges.delete(sessionId);\n\t\tthis._summaries.delete(sessionId);\n\t\tthis._branchVersions.delete(sessionId);\n\t\tthis._edgeVersions.delete(sessionId);\n\t\tthis._summaryVersions.delete(sessionId);\n\t}\n\n\t/** Discards all retained work after a successful durable global reset. */\n\tpublic discardAll(): void {\n\t\tthis._thoughts.length = 0;\n\t\tthis._branches.clear();\n\t\tthis._edges.clear();\n\t\tthis._summaries.clear();\n\t\tthis._branchVersions.clear();\n\t\tthis._edgeVersions.clear();\n\t\tthis._summaryVersions.clear();\n\t}\n\n\tprivate _accept(): Acceptance {\n\t\tconst sequence = this._nextSequence;\n\t\tthis._nextSequence += 1;\n\t\treturn { token: `persistence-work-${sequence}`, sequence };\n\t}\n\n\tprivate _entries(): AnyQueueEntry[] {\n\t\tconst entries: AnyQueueEntry[] = [...this._thoughts];\n\t\tfor (const branches of this._branches.values()) entries.push(...branches.values());\n\t\tentries.push(...this._edges.values(), ...this._summaries.values());\n\t\treturn entries;\n\t}\n\n\tprivate _findEligible(\n\t\tselectedTokens: ReadonlySet<PersistenceWorkToken>,\n\t\tmode: PersistenceSelectionMode,\n\t\tsessionId?: SessionId\n\t): AnyQueueEntry | undefined {\n\t\tlet oldest: AnyQueueEntry | undefined;\n\t\tfor (const entry of this._entries()) {\n\t\t\tif (selectedTokens.has(entry.work.token)) continue;\n\t\t\tif (sessionId !== undefined && entry.work.sessionId !== sessionId) continue;\n\t\t\tif (!this._modeAllows(mode, entry.terminalFailure !== undefined)) continue;\n\t\t\tif (oldest === undefined || entry.acceptedSequence < oldest.acceptedSequence) oldest = entry;\n\t\t}\n\t\treturn oldest;\n\t}\n\n\tprivate _modeAllows(mode: PersistenceSelectionMode, hasTerminalFailure: boolean): boolean {\n\t\tswitch (mode) {\n\t\t\tcase 'explicit':\n\t\t\t\treturn true;\n\t\t\tcase 'background':\n\t\t\t\treturn !hasTerminalFailure;\n\t\t\tdefault:\n\t\t\t\treturn assertNever(mode);\n\t\t}\n\t}\n\n\tprivate _currentEntry(work: PersistenceWork): AnyQueueEntry | undefined {\n\t\tlet entry: AnyQueueEntry | undefined;\n\t\tswitch (work.kind) {\n\t\t\tcase 'thought':\n\t\t\t\tentry = this._thoughts.find((candidate) => candidate.work.token === work.token);\n\t\t\t\tbreak;\n\t\t\tcase 'branch':\n\t\t\t\tentry = this._branches.get(work.sessionId)?.get(work.key);\n\t\t\t\tbreak;\n\t\t\tcase 'edge':\n\t\t\t\tentry = this._edges.get(work.key);\n\t\t\t\tbreak;\n\t\t\tcase 'summary':\n\t\t\t\tentry = this._summaries.get(work.key);\n\t\t\t\tbreak;\n\t\t\tdefault:\n\t\t\t\treturn assertNever(work);\n\t\t}\n\t\treturn entry !== undefined && this._matchesWork(entry.work, work) ? entry : undefined;\n\t}\n\n\tprivate _matchesWork(current: PersistenceWork, selected: PersistenceWork): boolean {\n\t\tif (\n\t\t\tcurrent.kind !== selected.kind ||\n\t\t\tcurrent.token !== selected.token ||\n\t\t\tcurrent.sessionId !== selected.sessionId\n\t\t) {\n\t\t\treturn false;\n\t\t}\n\t\tswitch (selected.kind) {\n\t\t\tcase 'thought':\n\t\t\t\treturn current.kind === 'thought';\n\t\t\tcase 'branch':\n\t\t\t\treturn (\n\t\t\t\t\tcurrent.kind === 'branch' &&\n\t\t\t\t\tcurrent.operation === selected.operation &&\n\t\t\t\t\tcurrent.key === selected.key &&\n\t\t\t\t\tcurrent.version === selected.version\n\t\t\t\t);\n\t\t\tcase 'edge':\n\t\t\t\treturn (\n\t\t\t\t\tcurrent.kind === 'edge' &&\n\t\t\t\t\tcurrent.key === selected.key &&\n\t\t\t\t\tcurrent.version === selected.version\n\t\t\t\t);\n\t\t\tcase 'summary':\n\t\t\t\treturn (\n\t\t\t\t\tcurrent.kind === 'summary' &&\n\t\t\t\t\tcurrent.key === selected.key &&\n\t\t\t\t\tcurrent.version === selected.version\n\t\t\t\t);\n\t\t\tdefault:\n\t\t\t\treturn assertNever(selected);\n\t\t}\n\t}\n\n\tprivate _matchesFailure(work: PersistenceWork, failure: PersistenceWorkFailure): boolean {\n\t\tif (\n\t\t\twork.kind !== failure.kind ||\n\t\t\twork.token !== failure.token ||\n\t\t\twork.sessionId !== failure.sessionId\n\t\t) {\n\t\t\treturn false;\n\t\t}\n\t\tswitch (work.kind) {\n\t\t\tcase 'thought':\n\t\t\t\treturn true;\n\t\t\tcase 'branch':\n\t\t\t\treturn (\n\t\t\t\t\tfailure.kind === 'branch' &&\n\t\t\t\t\twork.operation === failure.operation &&\n\t\t\t\t\twork.key === failure.key &&\n\t\t\t\t\twork.version === failure.version\n\t\t\t\t);\n\t\t\tcase 'edge':\n\t\t\tcase 'summary':\n\t\t\t\treturn 'key' in failure && work.key === failure.key && work.version === failure.version;\n\t\t\tdefault:\n\t\t\t\treturn assertNever(work);\n\t\t}\n\t}\n}\n"],"names":["PersistenceWorkQueue","Map","sessionId","thought","acceptance","work","Object","undefined","branchId","thoughts","versionMap","version","branchMap","edges","summaries","selectedTokens","mode","entry","index","candidate","assertNever","failure","failures","left","right","branchCount","branches","sequence","entries","oldest","hasTerminalFailure","current","selected"],"mappings":"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"}

package/dist/core/PersistenceWriter.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Bounded persistence dispatch for one accepted work item.
+ *
+ * @module PersistenceWriter
+ */
+import type { PersistenceBackend } from '../contracts/PersistenceBackend.js';
+import type { PersistenceWork, PersistenceWorkFailure } from '../contracts/persistence-work.js';
+/** Async scheduler used between persistence attempts. */
+export type PersistenceDelay = (milliseconds: number) => Promise<void>;
+/** Immutable dependencies and retry policy for {@link PersistenceWriter}. */
+export type PersistenceWriterConfig = {
+    readonly persistence: PersistenceBackend;
+    readonly maxRetries: number;
+    readonly retryDelays?: readonly number[];
+    readonly delay?: PersistenceDelay;
+};
+/** Allocation-free success sentinel or an attributable terminal failure. */
+export type PersistenceWriteResult = true | PersistenceWorkFailure;
+/**
+ * Writes one sealed persistence item with a bounded retry policy.
+ *
+ * The writer owns no queue or generation state. Each call preserves the work
+ * coordinates and delegates retention or error aggregation to its caller.
+ *
+ * @example
+ * ```ts
+ * const writer = new PersistenceWriter({ persistence, maxRetries: 0 });
+ * const result = await writer.write(work);
+ * if (result !== true) failures.push(result);
+ * ```
+ */
+export declare class PersistenceWriter {
+    private readonly _persistence;
+    private readonly _maxRetries;
+    private readonly _retryDelays;
+    private readonly _delay;
+    /**
+     * Creates a bounded writer.
+     *
+     * @param config - Persistence dependency, retry bound, cadence, and delay scheduler.
+     * @throws {RangeError} When `maxRetries` is not a non-negative safe integer.
+     */
+    constructor(config: PersistenceWriterConfig);
+    /**
+     * Writes one item once initially and at most `maxRetries` additional times.
+     *
+     * @param work - Sealed persistence item selected by the coordinator.
+     * @returns `true` on success, or the exact attributable failure after exhaustion.
+     */
+    write(work: PersistenceWork): Promise<PersistenceWriteResult>;
+    private _retryDelay;
+    private _dispatch;
+    private _failure;
+}
+//# sourceMappingURL=PersistenceWriter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PersistenceWriter.d.ts","sourceRoot":"","sources":["../../src/core/PersistenceWriter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAOhG,yDAAyD;AACzD,MAAM,MAAM,gBAAgB,GAAG,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEvE,6EAA6E;AAC7E,MAAM,MAAM,uBAAuB,GAAG;IACrC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;CAClC,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,sBAAsB,GAAG,IAAI,GAAG,sBAAsB,CAAC;AAMnE;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoB;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAE1C;;;;;OAKG;gBACgB,MAAM,EAAE,uBAAuB;IAWlD;;;;;OAKG;IACU,KAAK,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAmB1E,OAAO,CAAC,WAAW;YAIL,SAAS;IAmCvB,OAAO,CAAC,QAAQ;CA2ChB"}

package/dist/core/PersistenceWriter.js

@@ -0,0 +1,112 @@
+import { GLOBAL_SESSION_ID } from "../contracts/ids.js";
+import { requireSessionScopedPersistence } from "../persistence/SessionScopedPersistence.js";
+import { assertNever } from "../utils.js";
+const DEFAULT_RETRY_DELAYS = [
+    100,
+    500,
+    2000
+];
+function defaultDelay(milliseconds) {
+    return new Promise((resolve)=>setTimeout(resolve, milliseconds));
+}
+class PersistenceWriter {
+    _persistence;
+    _maxRetries;
+    _retryDelays;
+    _delay;
+    constructor(config){
+        if (!Number.isSafeInteger(config.maxRetries) || config.maxRetries < 0) throw new RangeError('maxRetries must be a non-negative safe integer');
+        this._persistence = config.persistence;
+        this._maxRetries = config.maxRetries;
+        this._retryDelays = [
+            ...config.retryDelays ?? DEFAULT_RETRY_DELAYS
+        ];
+        this._delay = config.delay ?? defaultDelay;
+    }
+    async write(work) {
+        let finalCause;
+        for(let attemptIndex = 0; attemptIndex <= this._maxRetries; attemptIndex++){
+            if (attemptIndex > 0) await this._delay(this._retryDelay(attemptIndex - 1));
+            try {
+                await this._dispatch(work);
+                return true;
+            } catch (cause) {
+                finalCause = cause;
+            }
+        }
+        return this._failure(work, this._maxRetries + 1, finalCause);
+    }
+    _retryDelay(retryIndex) {
+        return this._retryDelays[retryIndex] ?? this._retryDelays.at(-1) ?? 0;
+    }
+    async _dispatch(work) {
+        switch(work.kind){
+            case 'thought':
+                if (work.sessionId === GLOBAL_SESSION_ID) return this._persistence.saveThought(work.thought);
+                return requireSessionScopedPersistence(this._persistence, 'saveThoughtForSession').saveThoughtForSession(work.sessionId, work.thought);
+            case 'branch':
+                if ('delete' === work.operation) {
+                    const persistence = requireSessionScopedPersistence(this._persistence, work.sessionId === GLOBAL_SESSION_ID ? 'deleteBranch' : 'deleteBranchForSession');
+                    return work.sessionId === GLOBAL_SESSION_ID ? persistence.deleteBranch(work.key) : persistence.deleteBranchForSession(work.sessionId, work.key);
+                }
+                if (work.sessionId === GLOBAL_SESSION_ID) return this._persistence.saveBranch(work.key, [
+                    ...work.snapshot
+                ]);
+                return requireSessionScopedPersistence(this._persistence, 'saveBranchForSession').saveBranchForSession(work.sessionId, work.key, work.snapshot);
+            case 'edge':
+                return this._persistence.saveEdges(work.sessionId, work.snapshot);
+            case 'summary':
+                return this._persistence.saveSummaries(work.sessionId, work.snapshot);
+            default:
+                return assertNever(work);
+        }
+    }
+    _failure(work, attempts, cause) {
+        switch(work.kind){
+            case 'thought':
+                return {
+                    kind: work.kind,
+                    token: work.token,
+                    sessionId: work.sessionId,
+                    attempts,
+                    cause
+                };
+            case 'branch':
+                return {
+                    kind: work.kind,
+                    operation: work.operation,
+                    token: work.token,
+                    sessionId: work.sessionId,
+                    key: work.key,
+                    version: work.version,
+                    attempts,
+                    cause
+                };
+            case 'edge':
+                return {
+                    kind: work.kind,
+                    token: work.token,
+                    sessionId: work.sessionId,
+                    key: work.key,
+                    version: work.version,
+                    attempts,
+                    cause
+                };
+            case 'summary':
+                return {
+                    kind: work.kind,
+                    token: work.token,
+                    sessionId: work.sessionId,
+                    key: work.key,
+                    version: work.version,
+                    attempts,
+                    cause
+                };
+            default:
+                return assertNever(work);
+        }
+    }
+}
+export { PersistenceWriter };
+
+//# sourceMappingURL=PersistenceWriter.js.map

package/dist/core/PersistenceWriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/PersistenceWriter.js","sources":["../../src/core/PersistenceWriter.ts"],"sourcesContent":["/**\n * Bounded persistence dispatch for one accepted work item.\n *\n * @module PersistenceWriter\n */\n\nimport type { PersistenceBackend } from '../contracts/PersistenceBackend.js';\nimport type { PersistenceWork, PersistenceWorkFailure } from '../contracts/persistence-work.js';\nimport { GLOBAL_SESSION_ID } from '../contracts/ids.js';\nimport { requireSessionScopedPersistence } from '../persistence/SessionScopedPersistence.js';\nimport { assertNever } from '../utils.js';\n\nconst DEFAULT_RETRY_DELAYS = [100, 500, 2000] as const;\n\n/** Async scheduler used between persistence attempts. */\nexport type PersistenceDelay = (milliseconds: number) => Promise<void>;\n\n/** Immutable dependencies and retry policy for {@link PersistenceWriter}. */\nexport type PersistenceWriterConfig = {\n\treadonly persistence: PersistenceBackend;\n\treadonly maxRetries: number;\n\treadonly retryDelays?: readonly number[];\n\treadonly delay?: PersistenceDelay;\n};\n\n/** Allocation-free success sentinel or an attributable terminal failure. */\nexport type PersistenceWriteResult = true | PersistenceWorkFailure;\n\nfunction defaultDelay(milliseconds: number): Promise<void> {\n\treturn new Promise((resolve) => setTimeout(resolve, milliseconds));\n}\n\n/**\n * Writes one sealed persistence item with a bounded retry policy.\n *\n * The writer owns no queue or generation state. Each call preserves the work\n * coordinates and delegates retention or error aggregation to its caller.\n *\n * @example\n * ```ts\n * const writer = new PersistenceWriter({ persistence, maxRetries: 0 });\n * const result = await writer.write(work);\n * if (result !== true) failures.push(result);\n * ```\n */\nexport class PersistenceWriter {\n\tprivate readonly _persistence: PersistenceBackend;\n\tprivate readonly _maxRetries: number;\n\tprivate readonly _retryDelays: readonly number[];\n\tprivate readonly _delay: PersistenceDelay;\n\n\t/**\n\t * Creates a bounded writer.\n\t *\n\t * @param config - Persistence dependency, retry bound, cadence, and delay scheduler.\n\t * @throws {RangeError} When `maxRetries` is not a non-negative safe integer.\n\t */\n\tpublic constructor(config: PersistenceWriterConfig) {\n\t\tif (!Number.isSafeInteger(config.maxRetries) || config.maxRetries < 0) {\n\t\t\tthrow new RangeError('maxRetries must be a non-negative safe integer');\n\t\t}\n\n\t\tthis._persistence = config.persistence;\n\t\tthis._maxRetries = config.maxRetries;\n\t\tthis._retryDelays = [...(config.retryDelays ?? DEFAULT_RETRY_DELAYS)];\n\t\tthis._delay = config.delay ?? defaultDelay;\n\t}\n\n\t/**\n\t * Writes one item once initially and at most `maxRetries` additional times.\n\t *\n\t * @param work - Sealed persistence item selected by the coordinator.\n\t * @returns `true` on success, or the exact attributable failure after exhaustion.\n\t */\n\tpublic async write(work: PersistenceWork): Promise<PersistenceWriteResult> {\n\t\tlet finalCause: unknown;\n\n\t\tfor (let attemptIndex = 0; attemptIndex <= this._maxRetries; attemptIndex++) {\n\t\t\tif (attemptIndex > 0) {\n\t\t\t\tawait this._delay(this._retryDelay(attemptIndex - 1));\n\t\t\t}\n\n\t\t\ttry {\n\t\t\t\tawait this._dispatch(work);\n\t\t\t\treturn true;\n\t\t\t} catch (cause) {\n\t\t\t\tfinalCause = cause;\n\t\t\t}\n\t\t}\n\n\t\treturn this._failure(work, this._maxRetries + 1, finalCause);\n\t}\n\n\tprivate _retryDelay(retryIndex: number): number {\n\t\treturn this._retryDelays[retryIndex] ?? this._retryDelays.at(-1) ?? 0;\n\t}\n\n\tprivate async _dispatch(work: PersistenceWork): Promise<void> {\n\t\tswitch (work.kind) {\n\t\t\tcase 'thought':\n\t\t\t\tif (work.sessionId === GLOBAL_SESSION_ID) {\n\t\t\t\t\treturn this._persistence.saveThought(work.thought);\n\t\t\t\t}\n\t\t\t\treturn requireSessionScopedPersistence(\n\t\t\t\t\tthis._persistence,\n\t\t\t\t\t'saveThoughtForSession'\n\t\t\t\t).saveThoughtForSession(work.sessionId, work.thought);\n\t\t\tcase 'branch':\n\t\t\t\tif (work.operation === 'delete') {\n\t\t\t\t\tconst persistence = requireSessionScopedPersistence(\n\t\t\t\t\t\tthis._persistence,\n\t\t\t\t\t\twork.sessionId === GLOBAL_SESSION_ID ? 'deleteBranch' : 'deleteBranchForSession'\n\t\t\t\t\t);\n\t\t\t\t\treturn work.sessionId === GLOBAL_SESSION_ID\n\t\t\t\t\t\t? persistence.deleteBranch(work.key)\n\t\t\t\t\t\t: persistence.deleteBranchForSession(work.sessionId, work.key);\n\t\t\t\t}\n\t\t\t\tif (work.sessionId === GLOBAL_SESSION_ID)\n\t\t\t\t\treturn this._persistence.saveBranch(work.key, [...work.snapshot]);\n\t\t\t\treturn requireSessionScopedPersistence(\n\t\t\t\t\tthis._persistence,\n\t\t\t\t\t'saveBranchForSession'\n\t\t\t\t).saveBranchForSession(work.sessionId, work.key, work.snapshot);\n\t\t\tcase 'edge':\n\t\t\t\treturn this._persistence.saveEdges(work.sessionId, work.snapshot);\n\t\t\tcase 'summary':\n\t\t\t\treturn this._persistence.saveSummaries(work.sessionId, work.snapshot);\n\t\t\tdefault:\n\t\t\t\treturn assertNever(work);\n\t\t}\n\t}\n\n\tprivate _failure(\n\t\twork: PersistenceWork,\n\t\tattempts: number,\n\t\tcause: unknown\n\t): PersistenceWorkFailure {\n\t\tswitch (work.kind) {\n\t\t\tcase 'thought':\n\t\t\t\treturn { kind: work.kind, token: work.token, sessionId: work.sessionId, attempts, cause };\n\t\t\tcase 'branch':\n\t\t\t\treturn {\n\t\t\t\t\tkind: work.kind,\n\t\t\t\t\toperation: work.operation,\n\t\t\t\t\ttoken: work.token,\n\t\t\t\t\tsessionId: work.sessionId,\n\t\t\t\t\tkey: work.key,\n\t\t\t\t\tversion: work.version,\n\t\t\t\t\tattempts,\n\t\t\t\t\tcause,\n\t\t\t\t};\n\t\t\tcase 'edge':\n\t\t\t\treturn {\n\t\t\t\t\tkind: work.kind,\n\t\t\t\t\ttoken: work.token,\n\t\t\t\t\tsessionId: work.sessionId,\n\t\t\t\t\tkey: work.key,\n\t\t\t\t\tversion: work.version,\n\t\t\t\t\tattempts,\n\t\t\t\t\tcause,\n\t\t\t\t};\n\t\t\tcase 'summary':\n\t\t\t\treturn {\n\t\t\t\t\tkind: work.kind,\n\t\t\t\t\ttoken: work.token,\n\t\t\t\t\tsessionId: work.sessionId,\n\t\t\t\t\tkey: work.key,\n\t\t\t\t\tversion: work.version,\n\t\t\t\t\tattempts,\n\t\t\t\t\tcause,\n\t\t\t\t};\n\t\t\tdefault:\n\t\t\t\treturn assertNever(work);\n\t\t}\n\t}\n}\n"],"names":["DEFAULT_RETRY_DELAYS","defaultDelay","milliseconds","Promise","resolve","setTimeout","PersistenceWriter","config","Number","RangeError","work","finalCause","attemptIndex","cause","retryIndex","GLOBAL_SESSION_ID","requireSessionScopedPersistence","persistence","assertNever","attempts"],"mappings":"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"}

package/dist/core/SessionErrors.d.ts

@@ -0,0 +1,37 @@
+import type { SessionId } from '../contracts/ids.js';
+import { SequentialThinkingError } from '../errors.js';
+/** Lifecycle phase that can close ordinary session admission. */
+export type SessionLifecycleClosedPhase = 'resetting' | 'reset_failed' | 'evicting' | 'eviction_failed' | 'shutting_down' | 'stopped' | 'shutdown_failed';
+/** Error thrown when an operation arrives after lifecycle admission has closed. */
+export declare class SessionLifecycleClosedError extends SequentialThinkingError {
+    /** Session whose admission is closed, or `undefined` for a global exclusive request. */
+    readonly sessionId: SessionId | undefined;
+    /** Lifecycle phase that rejected admission. */
+    readonly phase: SessionLifecycleClosedPhase;
+    constructor(sessionId: SessionId | undefined, phase: SessionLifecycleClosedPhase);
+}
+/** Error thrown when a per-session async lock cannot be acquired in time. */
+export declare class LockTimeoutError extends SequentialThinkingError {
+    readonly sessionId: SessionId;
+    readonly timeoutMs: number;
+    constructor(sessionId: SessionId, timeoutMs: number);
+}
+/** Error thrown when a session is accessed by a non-owner. */
+export declare class SessionAccessDeniedError extends SequentialThinkingError {
+    readonly sessionId: SessionId;
+    readonly expectedOwner: string;
+    readonly actualOwner: string | undefined;
+    constructor(sessionId: SessionId, expectedOwner: string, actualOwner?: string);
+}
+/** Scope requested through the legacy synchronous clear API. */
+export type AsyncResetScope = 'session' | 'all';
+/** Condition that makes the legacy synchronous clear API unsafe. */
+export type AsyncResetReason = 'persistent' | 'active';
+/** Error raised when state requires the awaitable reset API. */
+export declare class AsyncResetRequiredError extends SequentialThinkingError {
+    readonly scope: AsyncResetScope;
+    readonly sessionId: SessionId | undefined;
+    readonly reason: AsyncResetReason;
+    constructor(scope: AsyncResetScope, sessionId?: SessionId, reason?: AsyncResetReason);
+}
+//# sourceMappingURL=SessionErrors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SessionErrors.d.ts","sourceRoot":"","sources":["../../src/core/SessionErrors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAe,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAEpE,iEAAiE;AACjE,MAAM,MAAM,2BAA2B,GACpC,WAAW,GACX,cAAc,GACd,UAAU,GACV,iBAAiB,GACjB,eAAe,GACf,SAAS,GACT,iBAAiB,CAAC;AAErB,mFAAmF;AACnF,qBAAa,2BAA4B,SAAQ,uBAAuB;IACvE,wFAAwF;IACxF,SAAgB,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;IACjD,+CAA+C;IAC/C,SAAgB,KAAK,EAAE,2BAA2B,CAAC;gBAEhC,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE,KAAK,EAAE,2BAA2B;CAUvF;AAED,6EAA6E;AAC7E,qBAAa,gBAAiB,SAAQ,uBAAuB;IAC5D,SAAgB,SAAS,EAAE,SAAS,CAAC;IACrC,SAAgB,SAAS,EAAE,MAAM,CAAC;gBAEtB,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM;CAMnD;AAED,8DAA8D;AAC9D,qBAAa,wBAAyB,SAAQ,uBAAuB;IACpE,SAAgB,SAAS,EAAE,SAAS,CAAC;IACrC,SAAgB,aAAa,EAAE,MAAM,CAAC;IACtC,SAAgB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEpC,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAU7E;AAED,gEAAgE;AAChE,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,KAAK,CAAC;AAEhD,oEAAoE;AACpE,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEvD,gEAAgE;AAChE,qBAAa,uBAAwB,SAAQ,uBAAuB;IACnE,SAAgB,KAAK,EAAE,eAAe,CAAC;IACvC,SAAgB,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;IACjD,SAAgB,MAAM,EAAE,gBAAgB,CAAC;gBAGxC,KAAK,EAAE,eAAe,EACtB,SAAS,CAAC,EAAE,SAAS,EACrB,MAAM,GAAE,gBAA+B;CAYxC"}

package/dist/core/SessionErrors.js

@@ -0,0 +1,50 @@
+import { ERROR_CODES, SequentialThinkingError } from "../errors.js";
+class SessionLifecycleClosedError extends SequentialThinkingError {
+    sessionId;
+    phase;
+    constructor(sessionId, phase){
+        const scope = void 0 === sessionId ? 'Global' : `Session '${sessionId}'`;
+        super(`${scope} lifecycle admission is closed in phase '${phase}'`, ERROR_CODES.SESSION_LIFECYCLE_CLOSED);
+        this.name = 'SessionLifecycleClosedError';
+        this.sessionId = sessionId;
+        this.phase = phase;
+    }
+}
+class LockTimeoutError extends SequentialThinkingError {
+    sessionId;
+    timeoutMs;
+    constructor(sessionId, timeoutMs){
+        super(`Lock timeout for session '${sessionId}' after ${timeoutMs}ms`, ERROR_CODES.LOCK_TIMEOUT);
+        this.name = 'LockTimeoutError';
+        this.sessionId = sessionId;
+        this.timeoutMs = timeoutMs;
+    }
+}
+class SessionAccessDeniedError extends SequentialThinkingError {
+    sessionId;
+    expectedOwner;
+    actualOwner;
+    constructor(sessionId, expectedOwner, actualOwner){
+        super(`Access denied to session '${sessionId}': owned by '${expectedOwner}', accessed by '${actualOwner ?? 'anonymous'}'`, ERROR_CODES.SESSION_ACCESS_DENIED);
+        this.name = 'SessionAccessDeniedError';
+        this.sessionId = sessionId;
+        this.expectedOwner = expectedOwner;
+        this.actualOwner = actualOwner;
+    }
+}
+class AsyncResetRequiredError extends SequentialThinkingError {
+    scope;
+    sessionId;
+    reason;
+    constructor(scope, sessionId, reason = 'persistent'){
+        const target = 'session' === scope ? `session '${sessionId}'` : 'all sessions';
+        super(`Synchronous clear cannot reset ${reason} ${target}; use the awaitable ${'session' === scope ? 'resetSession()' : 'resetAll()'} API`, ERROR_CODES.ASYNC_RESET_REQUIRED);
+        this.name = 'AsyncResetRequiredError';
+        this.scope = scope;
+        this.sessionId = sessionId;
+        this.reason = reason;
+    }
+}
+export { AsyncResetRequiredError, LockTimeoutError, SessionAccessDeniedError, SessionLifecycleClosedError };
+
+//# sourceMappingURL=SessionErrors.js.map