@iworkforces/tracelattice 2.0.3

package/dist/contracts/suspension.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Suspension store contract for tool interleave.
+ *
+ * Manages pending tool_call thoughts that are awaiting tool execution
+ * results. Each suspension is identified by a unique token, has a TTL,
+ * and can be resumed (consumed) or peeked (non-destructive lookup).
+ *
+ * @module contracts/suspension
+ */
+import type { SessionId, SuspensionToken, ThoughtId } from './ids.js';
+/**
+ * A single pending tool-call suspension record.
+ *
+ * Created when a `tool_call` thought is processed and the system is
+ * waiting for the corresponding tool result to be supplied via a
+ * follow-up `tool_result` thought.
+ */
+export interface SuspensionRecord {
+    /** Opaque token used to resume this suspension. */
+    readonly token: SuspensionToken;
+    /** Session that owns this suspension. */
+    readonly sessionId: SessionId;
+    /** Thought number of the originating `tool_call` thought. */
+    readonly toolCallThoughtNumber: number;
+    /** Stable identity of the originating `tool_call` thought. */
+    readonly toolCallThoughtId: ThoughtId;
+    /** Name of the tool to invoke. */
+    readonly toolName: string;
+    /** Arguments supplied to the tool. */
+    readonly toolArguments: Record<string, unknown>;
+    /** Wall-clock millisecond timestamp when the record was created. */
+    readonly createdAt: number;
+    /** Wall-clock millisecond timestamp after which the record is expired. */
+    readonly expiresAt: number;
+}
+/**
+ * Store of pending tool-call suspensions with TTL expiry.
+ *
+ * Implementations are expected to expire records lazily on access and
+ * (optionally) eagerly via a background sweeper started by `start()`.
+ *
+ * @example
+ * ```typescript
+ * const store: ISuspensionStore = new InMemorySuspensionStore();
+ * store.start();
+ * const rec = store.suspend({
+ *   sessionId: 's1',
+ *   toolCallThoughtNumber: 3,
+ *   toolCallThoughtId: 'thought-3',
+ *   toolName: 'search',
+ *   toolArguments: { q: 'foo' },
+ *   expiresAt: Date.now() + 60_000,
+ * });
+ * const resumed = store.resume(rec.token);
+ * store.stop();
+ * ```
+ */
+export interface ISuspensionStore {
+    /**
+     * Create and store a new suspension record.
+     *
+     * The implementation generates a unique `token` and `createdAt`
+     * timestamp. If `ttlMs` is supplied, `expiresAt` is computed as
+     * `Date.now() + ttlMs` and overrides any caller-supplied
+     * `expiresAt` value.
+     *
+     * @param record - Record fields excluding `token` and `createdAt`,
+     * with optional `ttlMs` to derive `expiresAt`.
+     * @returns The fully-populated stored record.
+     *
+     * @example
+     * ```typescript
+     * const rec = store.suspend({
+     *   sessionId: 's1',
+     *   toolCallThoughtNumber: 2,
+     *   toolCallThoughtId: 'thought-2',
+     *   toolName: 'search',
+     *   toolArguments: {},
+     *   ttlMs: 30_000,
+     *   expiresAt: 0,
+     * });
+     * ```
+     */
+    suspend(record: Omit<SuspensionRecord, 'token' | 'createdAt'> & {
+        ttlMs?: number;
+    }): SuspensionRecord;
+    /**
+     * Consume a suspension by token.
+     *
+     * Returns `null` for both unknown tokens and expired records;
+     * expired records are removed as a side-effect. The caller
+     * (typically `ThoughtProcessor`) is expected to distinguish the
+     * two cases (e.g. via a prior `peek()`) and throw
+     * `SuspensionNotFoundError` or `SuspensionExpiredError`
+     * accordingly.
+     *
+     * @param token - Token returned from {@link suspend}.
+     * @returns The record on success, `null` if missing or expired.
+     *
+     * @example
+     * ```typescript
+     * const rec = store.resume(token);
+     * if (!rec) throw new SuspensionNotFoundError(token);
+     * ```
+     */
+    resume(token: string): SuspensionRecord | null;
+    /**
+     * Atomically validate and admit one suspended continuation.
+     *
+     * Operations sharing a token are serialized. The record must exist, remain
+     * unexpired, and belong to `expectedSessionId`. Session mismatches are
+     * reported as not found without consuming the record. `admit` runs
+     * synchronously inside the token critical section; the record is consumed
+     * only after the callback returns successfully.
+     *
+     * @param token - Opaque continuation token returned from {@link suspend}.
+     * @param expectedSessionId - Canonical session presenting the continuation.
+     * @param admit - Synchronous history-admission callback.
+     * @returns The admitted and consumed suspension record.
+     * @throws {SuspensionNotFoundError} If the token is missing or belongs to another session.
+     * @throws {SuspensionExpiredError} If the token expires at or before admission.
+     *
+     * @example
+     * ```typescript
+     * const record = await store.compareAndAdmit(token, sessionId, (candidate) => {
+     *   history.addThought(observation, { toolInvocationSourceThoughtId: candidate.toolCallThoughtId });
+     * });
+     * ```
+     */
+    compareAndAdmit(token: SuspensionToken, expectedSessionId: SessionId, admit: (record: SuspensionRecord) => void): Promise<SuspensionRecord>;
+    /**
+     * Non-destructive lookup of a suspension by token.
+     *
+     * Does not remove expired records. Returns `null` if the token is
+     * unknown.
+     *
+     * @param token - Token to inspect.
+     * @returns The record if present (even when expired), else `null`.
+     *
+     * @example
+     * ```typescript
+     * const rec = store.peek(token);
+     * if (rec && rec.expiresAt < Date.now()) {
+     *   throw new SuspensionExpiredError(token);
+     * }
+     * ```
+     */
+    peek(token: string): SuspensionRecord | null;
+    /**
+     * Remove all records whose `expiresAt` is at or before `now`.
+     *
+     * @param now - Wall-clock millisecond timestamp to compare against.
+     * @returns Number of records removed.
+     *
+     * @example
+     * ```typescript
+     * const removed = store.expireOlderThan(Date.now());
+     * ```
+     */
+    expireOlderThan(now: number): number;
+    /**
+     * Remove all records belonging to a session.
+     *
+     * @param sessionId - Session whose records should be cleared.
+     *
+     * @example
+     * ```typescript
+     * store.clearSession('session-a');
+     * ```
+     */
+    clearSession(sessionId: SessionId): void;
+    /**
+     * Discard records from every session namespace.
+     * Use only for a trusted process-wide reset; scoped callers must use `clearSession`.
+     */
+    clearAll(): void;
+    /**
+     * Count stored records.
+     *
+     * @param sessionId - Optional session filter; when omitted, returns
+     * the total count across all sessions.
+     * @returns Number of currently stored records (expired-but-not-yet-swept
+     * records are included).
+     *
+     * @example
+     * ```typescript
+     * const total = store.size();
+     * const perSession = store.size('session-a');
+     * ```
+     */
+    size(sessionId?: string): number;
+    /**
+     * Start the background sweeper, if any.
+     *
+     * Idempotent — repeated calls have no additional effect.
+     *
+     * @example
+     * ```typescript
+     * store.start();
+     * ```
+     */
+    start(): void;
+    /**
+     * Stop the background sweeper, if any.
+     *
+     * Idempotent — repeated calls have no additional effect.
+     *
+     * @example
+     * ```typescript
+     * store.stop();
+     * ```
+     */
+    stop(): void;
+}
+//# sourceMappingURL=suspension.d.ts.map

package/dist/contracts/suspension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suspension.d.ts","sourceRoot":"","sources":["../../src/contracts/suspension.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAChC,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,8DAA8D;IAC9D,QAAQ,CAAC,iBAAiB,EAAE,SAAS,CAAC;IACtC,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChD,oEAAoE;IACpE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CACN,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,WAAW,CAAC,GAAG;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACxE,gBAAgB,CAAC;IAEpB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAE/C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,eAAe,CACd,KAAK,EAAE,eAAe,EACtB,iBAAiB,EAAE,SAAS,EAC5B,KAAK,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,GACvC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE7B;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAE7C;;;;;;;;;;OAUG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAErC;;;;;;;;;OASG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAEzC;;;OAGG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEjC;;;;;;;;;OASG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;;;;;;;;OASG;IACH,IAAI,IAAI,IAAI,CAAC;CACb"}

package/dist/contracts/suspension.js

@@ -0,0 +1 @@
+export { };

package/dist/contracts/transport.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Transport kind discriminator.
+ */
+import type { McpServer } from 'tmcp';
+export type TransportKind = 'sse' | 'http' | 'streamable-http';
+/**
+ * Shared lifecycle interface for MCP transports.
+ *
+ * All transports (SSE, HTTP, Streamable HTTP) implement this interface.
+ * Share lifecycle only — request/response shapes genuinely differ across transports.
+ */
+export interface ITransport {
+    /** Discriminator for transport type identification. */
+    readonly kind: TransportKind;
+    /** Connect the transport to an MCP server. */
+    connect(mcpServer: McpServer): Promise<void>;
+    /** Stop the transport with graceful shutdown. */
+    stop(timeout?: number): Promise<void>;
+    /** Number of currently active client connections. */
+    readonly clientCount: number;
+    /** Whether the transport is in the process of shutting down. */
+    readonly isShuttingDown: boolean;
+    /** The server URL for client connections. */
+    readonly serverUrl: string;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/contracts/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/contracts/transport.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAEtC,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,GAAG,iBAAiB,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAE7B,8CAA8C;IAC9C,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7C,iDAAiD;IACjD,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtC,qDAAqD;IACrD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,gEAAgE;IAChE,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IAEjC,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B"}

package/dist/contracts/transport.js

@@ -0,0 +1 @@
+export { };

package/dist/core/CrossReferenceValidator.d.ts

@@ -0,0 +1,18 @@
+import type { Logger } from '../logger/StructuredLogger.js';
+import type { HistorySessionSnapshot, ResolvedThoughtReferences } from './IHistoryManager.js';
+import type { ThoughtData } from './thought.js';
+import type { ThoughtReferenceResolution } from './ThoughtReferenceIndex.js';
+export interface CrossReferenceValidationResult {
+    readonly result: ThoughtData;
+    readonly warnings: string[];
+    readonly resolvedReferences: ResolvedThoughtReferences;
+}
+export interface CrossReferenceValidationContext {
+    readonly snapshot: HistorySessionSnapshot;
+    readonly resolveThoughtReference: (thoughtNumber: number) => ThoughtReferenceResolution;
+    readonly strictBranchReferences: boolean;
+    readonly logger: Logger;
+}
+export declare function validateThoughtCrossReferences(input: ThoughtData, context: CrossReferenceValidationContext): CrossReferenceValidationResult;
+export declare function resolveThoughtReferencesForAdmission(input: ThoughtData, resolveThoughtReference: (thoughtNumber: number) => ThoughtReferenceResolution): ResolvedThoughtReferences;
+//# sourceMappingURL=CrossReferenceValidator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CrossReferenceValidator.d.ts","sourceRoot":"","sources":["../../src/core/CrossReferenceValidator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,KAAK,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAC9F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAK7E,MAAM,WAAW,8BAA8B;IAC9C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC5B,QAAQ,CAAC,kBAAkB,EAAE,yBAAyB,CAAC;CACvD;AAED,MAAM,WAAW,+BAA+B;IAC/C,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,uBAAuB,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,0BAA0B,CAAC;IACxF,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,8BAA8B,CAC7C,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,+BAA+B,GACtC,8BAA8B,CAsBhC;AAED,wBAAgB,oCAAoC,CACnD,KAAK,EAAE,WAAW,EAClB,uBAAuB,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,0BAA0B,GAC5E,yBAAyB,CAkC3B"}

package/dist/core/CrossReferenceValidator.js

@@ -0,0 +1,125 @@
+import { InvalidBacktrackError, ValidationError } from "../errors.js";
+function validateThoughtCrossReferences(input, context) {
+    const warnings = [];
+    const resolvedReferences = Object.freeze({
+        verificationTargetThoughtId: validateScalarReference(input, 'verification_target', context, warnings),
+        revisesThoughtId: validateScalarReference(input, 'revises_thought', context, warnings),
+        branchFromThoughtId: validateScalarReference(input, 'branch_from_thought', context, warnings),
+        synthesisSourceThoughtIds: filterThoughtReferences(input, 'synthesis_sources', context, warnings),
+        mergeFromThoughtIds: filterThoughtReferences(input, 'merge_from_thoughts', context, warnings),
+        backtrackTargetThoughtId: resolveBacktrackTarget(input, context)
+    });
+    filterBranchReferences(input, context, warnings);
+    return {
+        result: input,
+        warnings,
+        resolvedReferences
+    };
+}
+function resolveThoughtReferencesForAdmission(input, resolveThoughtReference) {
+    const resolveUnique = (thoughtNumber)=>{
+        if (void 0 === thoughtNumber) return;
+        const resolution = resolveThoughtReference(thoughtNumber);
+        return 'unique' === resolution.kind ? resolution.thoughtId : void 0;
+    };
+    const resolveArray = (thoughtNumbers)=>{
+        if (void 0 === thoughtNumbers) return;
+        const resolved = thoughtNumbers.flatMap((thoughtNumber)=>{
+            const thoughtId = resolveUnique(thoughtNumber);
+            return void 0 === thoughtId ? [] : [
+                thoughtId
+            ];
+        });
+        return 0 === resolved.length ? void 0 : Object.freeze(resolved);
+    };
+    const backtrackResolution = 'backtrack' === input.thought_type && void 0 !== input.backtrack_target ? resolveThoughtReference(input.backtrack_target) : void 0;
+    if (void 0 !== backtrackResolution && 'unique' !== backtrackResolution.kind) throw new InvalidBacktrackError(`backtrack_target ${input.backtrack_target} is ${backtrackResolution.kind} in session history`);
+    return Object.freeze({
+        verificationTargetThoughtId: resolveUnique(input.verification_target),
+        revisesThoughtId: resolveUnique(input.revises_thought),
+        branchFromThoughtId: resolveUnique(input.branch_from_thought),
+        synthesisSourceThoughtIds: resolveArray(input.synthesis_sources),
+        mergeFromThoughtIds: resolveArray(input.merge_from_thoughts),
+        backtrackTargetThoughtId: backtrackResolution?.kind === 'unique' ? backtrackResolution.thoughtId : void 0
+    });
+}
+function validateScalarReference(input, field, context, warnings) {
+    const target = input[field];
+    const strictVerificationTarget = 'verification_target' === field && 'verification' === input.thought_type && void 0 !== input.verification_result;
+    if (void 0 === target) {
+        if (strictVerificationTarget) throw new ValidationError('verification_result', 'requires verification_target');
+        return;
+    }
+    const resolution = context.resolveThoughtReference(target);
+    if ('unique' === resolution.kind) return resolution.thoughtId;
+    if (strictVerificationTarget) throw new ValidationError('verification_result', `verification_target ${target} is ${resolution.kind} in session history`);
+    const descriptor = 'missing' === resolution.kind ? 'dangling' : 'ambiguous';
+    warnings.push(`Dropped ${descriptor} ${field}: ${target} (history has ${context.snapshot.history.length} thoughts)`);
+    context.logger.warn(`Dropped ${descriptor} ${field}`, {
+        [field]: target,
+        historyLength: context.snapshot.history.length
+    });
+    input[field] = void 0;
+}
+function filterThoughtReferences(input, field, context, warnings) {
+    const references = input[field];
+    if (!references?.length) return;
+    const valid = [];
+    const validThoughtIds = [];
+    const dangling = [];
+    const ambiguous = [];
+    for (const thoughtNumber of references){
+        const resolution = context.resolveThoughtReference(thoughtNumber);
+        switch(resolution.kind){
+            case 'unique':
+                valid.push(thoughtNumber);
+                validThoughtIds.push(resolution.thoughtId);
+                break;
+            case 'missing':
+                dangling.push(thoughtNumber);
+                break;
+            case 'ambiguous':
+                ambiguous.push(thoughtNumber);
+                break;
+        }
+    }
+    appendFilteredWarning(input, field, 'dangling', dangling, valid, context, warnings);
+    appendFilteredWarning(input, field, 'ambiguous', ambiguous, valid, context, warnings);
+    input[field] = valid.length > 0 ? valid : void 0;
+    return validThoughtIds.length > 0 ? Object.freeze(validThoughtIds) : void 0;
+}
+function resolveBacktrackTarget(input, context) {
+    if ('backtrack' !== input.thought_type || void 0 === input.backtrack_target) return;
+    const resolution = context.resolveThoughtReference(input.backtrack_target);
+    if ('unique' === resolution.kind) return resolution.thoughtId;
+    throw new InvalidBacktrackError('backtrack_target ' + input.backtrack_target + ('missing' === resolution.kind ? ' does not exist in session history' : ' is ambiguous in session history'));
+}
+function appendFilteredWarning(input, field, descriptor, dropped, valid, context, warnings) {
+    if (0 === dropped.length) return;
+    warnings.push(`Filtered ${descriptor} ${field}: [${dropped.join(', ')}] (history has ${context.snapshot.history.length} thoughts)`);
+    context.logger.warn(`Filtered ${descriptor} ${field}`, {
+        original: input[field],
+        filtered: valid,
+        historyLength: context.snapshot.history.length
+    });
+}
+function filterBranchReferences(input, context, warnings) {
+    const references = input.merge_branch_ids;
+    if (!references?.length) return;
+    const existingBranches = new Set(context.snapshot.branchIds);
+    const valid = references.filter((branchId)=>existingBranches.has(branchId));
+    const dropped = references.filter((branchId)=>!existingBranches.has(branchId));
+    if (dropped.length > 0) {
+        if (context.strictBranchReferences) throw new ValidationError('merge_branch_ids', `references missing branches [${dropped.join(', ')}]`);
+        warnings.push(`Filtered dangling merge_branch_ids: [${dropped.join(', ')}]`);
+        context.logger.warn('Filtered dangling merge_branch_ids', {
+            original: references,
+            filtered: valid,
+            existingBranches: context.snapshot.branchIds
+        });
+    }
+    input.merge_branch_ids = valid.length > 0 ? valid : void 0;
+}
+export { resolveThoughtReferencesForAdmission, validateThoughtCrossReferences };
+
+//# sourceMappingURL=CrossReferenceValidator.js.map

package/dist/core/CrossReferenceValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/CrossReferenceValidator.js","sources":["../../src/core/CrossReferenceValidator.ts"],"sourcesContent":["import type { BranchId, ThoughtId } from '../contracts/ids.js';\nimport { InvalidBacktrackError, ValidationError } from '../errors.js';\nimport type { Logger } from '../logger/StructuredLogger.js';\nimport type { HistorySessionSnapshot, ResolvedThoughtReferences } from './IHistoryManager.js';\nimport type { ThoughtData } from './thought.js';\nimport type { ThoughtReferenceResolution } from './ThoughtReferenceIndex.js';\n\ntype ScalarReferenceField = 'verification_target' | 'revises_thought' | 'branch_from_thought';\ntype ThoughtReferenceField = 'synthesis_sources' | 'merge_from_thoughts';\n\nexport interface CrossReferenceValidationResult {\n\treadonly result: ThoughtData;\n\treadonly warnings: string[];\n\treadonly resolvedReferences: ResolvedThoughtReferences;\n}\n\nexport interface CrossReferenceValidationContext {\n\treadonly snapshot: HistorySessionSnapshot;\n\treadonly resolveThoughtReference: (thoughtNumber: number) => ThoughtReferenceResolution;\n\treadonly strictBranchReferences: boolean;\n\treadonly logger: Logger;\n}\n\nexport function validateThoughtCrossReferences(\n\tinput: ThoughtData,\n\tcontext: CrossReferenceValidationContext\n): CrossReferenceValidationResult {\n\tconst warnings: string[] = [];\n\tconst resolvedReferences = Object.freeze({\n\t\tverificationTargetThoughtId: validateScalarReference(\n\t\t\tinput,\n\t\t\t'verification_target',\n\t\t\tcontext,\n\t\t\twarnings\n\t\t),\n\t\trevisesThoughtId: validateScalarReference(input, 'revises_thought', context, warnings),\n\t\tbranchFromThoughtId: validateScalarReference(input, 'branch_from_thought', context, warnings),\n\t\tsynthesisSourceThoughtIds: filterThoughtReferences(\n\t\t\tinput,\n\t\t\t'synthesis_sources',\n\t\t\tcontext,\n\t\t\twarnings\n\t\t),\n\t\tmergeFromThoughtIds: filterThoughtReferences(input, 'merge_from_thoughts', context, warnings),\n\t\tbacktrackTargetThoughtId: resolveBacktrackTarget(input, context),\n\t});\n\tfilterBranchReferences(input, context, warnings);\n\treturn { result: input, warnings, resolvedReferences };\n}\n\nexport function resolveThoughtReferencesForAdmission(\n\tinput: ThoughtData,\n\tresolveThoughtReference: (thoughtNumber: number) => ThoughtReferenceResolution\n): ResolvedThoughtReferences {\n\tconst resolveUnique = (thoughtNumber: number | undefined): ThoughtId | undefined => {\n\t\tif (thoughtNumber === undefined) return undefined;\n\t\tconst resolution = resolveThoughtReference(thoughtNumber);\n\t\treturn resolution.kind === 'unique' ? resolution.thoughtId : undefined;\n\t};\n\tconst resolveArray = (\n\t\tthoughtNumbers: readonly number[] | undefined\n\t): readonly ThoughtId[] | undefined => {\n\t\tif (thoughtNumbers === undefined) return undefined;\n\t\tconst resolved = thoughtNumbers.flatMap((thoughtNumber) => {\n\t\t\tconst thoughtId = resolveUnique(thoughtNumber);\n\t\t\treturn thoughtId === undefined ? [] : [thoughtId];\n\t\t});\n\t\treturn resolved.length === 0 ? undefined : Object.freeze(resolved);\n\t};\n\tconst backtrackResolution =\n\t\tinput.thought_type === 'backtrack' && input.backtrack_target !== undefined\n\t\t\t? resolveThoughtReference(input.backtrack_target)\n\t\t\t: undefined;\n\tif (backtrackResolution !== undefined && backtrackResolution.kind !== 'unique') {\n\t\tthrow new InvalidBacktrackError(\n\t\t\t`backtrack_target ${input.backtrack_target} is ${backtrackResolution.kind} in session history`\n\t\t);\n\t}\n\treturn Object.freeze({\n\t\tverificationTargetThoughtId: resolveUnique(input.verification_target),\n\t\trevisesThoughtId: resolveUnique(input.revises_thought),\n\t\tbranchFromThoughtId: resolveUnique(input.branch_from_thought),\n\t\tsynthesisSourceThoughtIds: resolveArray(input.synthesis_sources),\n\t\tmergeFromThoughtIds: resolveArray(input.merge_from_thoughts),\n\t\tbacktrackTargetThoughtId:\n\t\t\tbacktrackResolution?.kind === 'unique' ? backtrackResolution.thoughtId : undefined,\n\t});\n}\n\nfunction validateScalarReference(\n\tinput: ThoughtData,\n\tfield: ScalarReferenceField,\n\tcontext: CrossReferenceValidationContext,\n\twarnings: string[]\n): ThoughtId | undefined {\n\tconst target = input[field];\n\tconst strictVerificationTarget =\n\t\tfield === 'verification_target' &&\n\t\tinput.thought_type === 'verification' &&\n\t\tinput.verification_result !== undefined;\n\tif (target === undefined) {\n\t\tif (strictVerificationTarget) {\n\t\t\tthrow new ValidationError('verification_result', 'requires verification_target');\n\t\t}\n\t\treturn undefined;\n\t}\n\tconst resolution = context.resolveThoughtReference(target);\n\tif (resolution.kind === 'unique') return resolution.thoughtId;\n\tif (strictVerificationTarget) {\n\t\tthrow new ValidationError(\n\t\t\t'verification_result',\n\t\t\t`verification_target ${target} is ${resolution.kind} in session history`\n\t\t);\n\t}\n\tconst descriptor = resolution.kind === 'missing' ? 'dangling' : 'ambiguous';\n\twarnings.push(\n\t\t`Dropped ${descriptor} ${field}: ${target} (history has ${context.snapshot.history.length} thoughts)`\n\t);\n\tcontext.logger.warn(`Dropped ${descriptor} ${field}`, {\n\t\t[field]: target,\n\t\thistoryLength: context.snapshot.history.length,\n\t});\n\tinput[field] = undefined;\n\treturn undefined;\n}\n\nfunction filterThoughtReferences(\n\tinput: ThoughtData,\n\tfield: ThoughtReferenceField,\n\tcontext: CrossReferenceValidationContext,\n\twarnings: string[]\n): readonly ThoughtId[] | undefined {\n\tconst references = input[field];\n\tif (!references?.length) return undefined;\n\tconst valid: number[] = [];\n\tconst validThoughtIds: ThoughtId[] = [];\n\tconst dangling: number[] = [];\n\tconst ambiguous: number[] = [];\n\tfor (const thoughtNumber of references) {\n\t\tconst resolution = context.resolveThoughtReference(thoughtNumber);\n\t\tswitch (resolution.kind) {\n\t\t\tcase 'unique':\n\t\t\t\tvalid.push(thoughtNumber);\n\t\t\t\tvalidThoughtIds.push(resolution.thoughtId);\n\t\t\t\tbreak;\n\t\t\tcase 'missing':\n\t\t\t\tdangling.push(thoughtNumber);\n\t\t\t\tbreak;\n\t\t\tcase 'ambiguous':\n\t\t\t\tambiguous.push(thoughtNumber);\n\t\t\t\tbreak;\n\t\t}\n\t}\n\tappendFilteredWarning(input, field, 'dangling', dangling, valid, context, warnings);\n\tappendFilteredWarning(input, field, 'ambiguous', ambiguous, valid, context, warnings);\n\tinput[field] = valid.length > 0 ? valid : undefined;\n\treturn validThoughtIds.length > 0 ? Object.freeze(validThoughtIds) : undefined;\n}\n\nfunction resolveBacktrackTarget(\n\tinput: ThoughtData,\n\tcontext: CrossReferenceValidationContext\n): ThoughtId | undefined {\n\tif (input.thought_type !== 'backtrack' || input.backtrack_target === undefined) return undefined;\n\tconst resolution = context.resolveThoughtReference(input.backtrack_target);\n\tif (resolution.kind === 'unique') return resolution.thoughtId;\n\tthrow new InvalidBacktrackError(\n\t\t'backtrack_target ' +\n\t\t\tinput.backtrack_target +\n\t\t\t(resolution.kind === 'missing'\n\t\t\t\t? ' does not exist in session history'\n\t\t\t\t: ' is ambiguous in session history')\n\t);\n}\n\nfunction appendFilteredWarning(\n\tinput: ThoughtData,\n\tfield: ThoughtReferenceField,\n\tdescriptor: 'dangling' | 'ambiguous',\n\tdropped: readonly number[],\n\tvalid: readonly number[],\n\tcontext: CrossReferenceValidationContext,\n\twarnings: string[]\n): void {\n\tif (dropped.length === 0) return;\n\twarnings.push(\n\t\t`Filtered ${descriptor} ${field}: [${dropped.join(', ')}] (history has ${context.snapshot.history.length} thoughts)`\n\t);\n\tcontext.logger.warn(`Filtered ${descriptor} ${field}`, {\n\t\toriginal: input[field],\n\t\tfiltered: valid,\n\t\thistoryLength: context.snapshot.history.length,\n\t});\n}\n\nfunction filterBranchReferences(\n\tinput: ThoughtData,\n\tcontext: CrossReferenceValidationContext,\n\twarnings: string[]\n): void {\n\tconst references = input.merge_branch_ids;\n\tif (!references?.length) return;\n\tconst existingBranches = new Set(context.snapshot.branchIds);\n\tconst valid = references.filter((branchId) => existingBranches.has(branchId));\n\tconst dropped = references.filter((branchId) => !existingBranches.has(branchId));\n\tif (dropped.length > 0) {\n\t\tif (context.strictBranchReferences) {\n\t\t\tthrow new ValidationError(\n\t\t\t\t'merge_branch_ids',\n\t\t\t\t`references missing branches [${dropped.join(', ')}]`\n\t\t\t);\n\t\t}\n\t\twarnings.push(`Filtered dangling merge_branch_ids: [${dropped.join(', ')}]`);\n\t\tcontext.logger.warn('Filtered dangling merge_branch_ids', {\n\t\t\toriginal: references,\n\t\t\tfiltered: valid,\n\t\t\texistingBranches: context.snapshot.branchIds,\n\t\t});\n\t}\n\tinput.merge_branch_ids = valid.length > 0 ? (valid as BranchId[]) : undefined;\n}\n"],"names":["validateThoughtCrossReferences","input","context","warnings","resolvedReferences","Object","validateScalarReference","filterThoughtReferences","resolveBacktrackTarget","filterBranchReferences","resolveThoughtReferencesForAdmission","resolveThoughtReference","resolveUnique","thoughtNumber","undefined","resolution","resolveArray","thoughtNumbers","resolved","thoughtId","backtrackResolution","InvalidBacktrackError","field","target","strictVerificationTarget","ValidationError","descriptor","references","valid","validThoughtIds","dangling","ambiguous","appendFilteredWarning","dropped","existingBranches","Set","branchId"],"mappings":"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"}

package/dist/core/HistoryManager.d.ts

@@ -0,0 +1,215 @@
+/**
+ * History and branch management for sequential thinking.
+ *
+ * This module provides the `HistoryManager` class which manages thought history,
+ * branching, and optional persistence with per-session state isolation.
+ *
+ * Internally delegates to three focused collaborators:
+ * - `EdgeEmitter` — DAG edge emission
+ * - `PersistenceBuffer` — buffered persistence + retry/backoff
+ * - `SessionManager` — session lifecycle (TTL/LRU eviction)
+ *
+ * @module HistoryManager
+ */
+import type { IEdgeStore, IMetrics, ISessionLock } from '../contracts/interfaces.js';
+import { type BranchId, type SessionId } from '../contracts/ids.js';
+import type { ISummaryStore } from '../contracts/summary.js';
+import type { Logger } from '../logger/StructuredLogger.js';
+import type { PersistenceBackend } from '../contracts/PersistenceBackend.js';
+import { type DehydrationOptions, type HydratedEntry } from './compression/DehydrationPolicy.js';
+import type { Summary } from './compression/Summary.js';
+import type { HistorySessionSnapshot, IHistoryManager, ThoughtAdmissionContext } from './IHistoryManager.js';
+import { type PersistenceEventEmitter } from './PersistenceBuffer.js';
+import type { ThoughtData } from './thought.js';
+import { type ThoughtReferenceResolution } from './ThoughtReferenceIndex.js';
+import { SessionLifecycleCoordinator } from './SessionLifecycleCoordinator.js';
+/** Absolute maximum history size (~20MB at 2KB/thought). Cannot be overridden. */
+export declare const ABSOLUTE_MAX_HISTORY_SIZE = 10000;
+export interface HistoryManagerConfig {
+    /** Maximum number of thoughts to keep in main history. @default 1000 */
+    maxHistorySize?: number;
+    /** Maximum number of branches to maintain. @default 50 */
+    maxBranches?: number;
+    /** Maximum size of each branch. @default 100 */
+    maxBranchSize?: number;
+    logger?: Logger;
+    persistence?: PersistenceBackend | null;
+    metrics?: IMetrics;
+    /** Maximum number of thoughts to buffer before flushing. @default 100 */
+    persistenceBufferSize?: number;
+    /** Periodic flush interval in ms. @default 1000 */
+    persistenceFlushInterval?: number;
+    /** Max retries for failed persistence flushes. @default 3 */
+    persistenceMaxRetries?: number;
+    eventEmitter?: PersistenceEventEmitter;
+    edgeStore?: IEdgeStore;
+    summaryStore?: ISummaryStore;
+    /** Whether to emit DAG edges (gated independently of edgeStore). @default false */
+    dagEdges?: boolean;
+    /** Maximum sessions per owner (per-owner LRU bucket). @default 50 */
+    maxSessionsPerOwner?: number;
+    /** Shared processor lock used to reject unsafe legacy synchronous clears. */
+    sessionLock?: ISessionLock;
+    /** Shared admission and exclusive lifecycle coordinator. */
+    lifecycleCoordinator?: SessionLifecycleCoordinator;
+    /** Clears processor-owned state after a session is actually removed. */
+    clearSessionAuxiliaryState?: (sessionId: SessionId) => void;
+    /** Clears all processor-owned state after a successful global lifecycle operation. */
+    clearAllAuxiliaryState?: () => void;
+}
+/**
+ * Manages thought history and branching for sequential thinking.
+ *
+ * Owns the per-session `Map<string, SessionState>`. Delegates DAG edge emission,
+ * buffered persistence, and session TTL/LRU eviction to focused collaborators while
+ * preserving test-coupled private member names (`_flushTimer`, `_startFlushTimer`,
+ * `_flushBuffer`, `_sessions`).
+ */
+export declare class HistoryManager implements IHistoryManager {
+    private static readonly DEFAULT_SESSION;
+    private static readonly SESSION_TTL_MS;
+    private static readonly MAX_SESSIONS;
+    private _sessions;
+    private _maxHistorySize;
+    private _maxBranches;
+    private _maxBranchSize;
+    private _logger;
+    private _persistence;
+    private _persistenceEnabled;
+    private _metrics?;
+    private _edgeStore?;
+    private _summaryStore?;
+    private _dagEdges;
+    private _eventEmitter;
+    private readonly _edgeEmitter;
+    private _referenceIndex;
+    private _persistenceBuffer;
+    private readonly _sessionManager;
+    private readonly _resetCoordinator;
+    private readonly _sessionLock?;
+    private readonly _lifecycle;
+    private _shutdownOwner;
+    private readonly _clearSessionAuxiliaryState?;
+    private readonly _clearAllAuxiliaryState?;
+    constructor(config?: HistoryManagerConfig);
+    private get _flushTimer();
+    private _startFlushTimer;
+    private _stopFlushTimer;
+    /** @internal Public for backward-compatible test coupling. */
+    _flushBuffer(): Promise<void>;
+    /**
+     * Drains accepted persistence work and projects terminal failures to one session.
+     *
+     * @param sessionId - Authoritative session whose persistence barrier to await.
+     * @returns A promise that settles when the session's accepted work settles.
+     */
+    drainSession(sessionId: SessionId): Promise<void>;
+    /**
+     * Registers the latest summary snapshot for coordinator-owned persistence.
+     *
+     * @param sessionId - Authoritative session that owns the summaries.
+     * @param summaries - Complete current summary snapshot for the session.
+     */
+    bufferSummaries(sessionId: SessionId, summaries: readonly Summary[]): void;
+    /** EdgeStore instance, if configured. Used by ThoughtProcessor for StrategyContext. */
+    getEdgeStore(): IEdgeStore | undefined;
+    private log;
+    /** Reads owner from RequestContext (AsyncLocalStorage). Stdio path returns undefined. */
+    private _getCurrentOwner;
+    /**
+     * Gets or creates session state; updates lastAccessedAt.
+     *
+     * Ownership semantics:
+     * - `owner === undefined` (stdio path): never rejects, never sets owner.
+     * - `owner !== undefined`: if session has a different owner, throws
+     *   `SessionAccessDeniedError`. If session was created without an owner
+     *   (e.g. by stdio), the owner is set on first owner-aware access.
+     */
+    private _getSession;
+    private _getSessionWithinOperation;
+    private _assertSessionOwner;
+    private _makeCapacityForSession;
+    private _isCapacityEvictionEligible;
+    private _isTtlEvictionEligible;
+    private _isPersistenceQuiescent;
+    private _evictSessions;
+    private _evictSession;
+    private _removeLiveSession;
+    private _createSessionState;
+    private _authorizeExistingSession;
+    private _assertOwnerlessResetAll;
+    /**
+     * Adds a thought to the history. Routes per-session, applies retraction for backtrack,
+     * caches tools/skills, trims, branches, emits DAG edges, and buffers for persistence.
+     */
+    addThought(thought: ThoughtData, context?: ThoughtAdmissionContext): void;
+    private _addThoughtWithinOperation;
+    private _resolveAdmissionReferences;
+    private _enforceRetention;
+    private _pruneUnretainedEdges;
+    private _bufferRetainedState;
+    private _stageAllRestoreBranchReconciliation;
+    private _stageRestoreBranchReconciliation;
+    private _stageBranchPersistence;
+    /** Marks the thought as retracted within the session (append-only). */
+    private _applyRetraction;
+    private _rebuildReferenceIndex;
+    resolveThoughtReference(sessionId: SessionId, thoughtNumber: number): ThoughtReferenceResolution;
+    private _addToSessionBranch;
+    private _cleanupSessionBranches;
+    private _trimSessionBranchSize;
+    getHistory(sessionId?: string): ThoughtData[];
+    /**
+     * Returns history with optional sliding-window dehydration. Non-mutating: when
+     * `dagEdges` is off OR no `ISummaryStore` is configured, returns same as getHistory.
+     */
+    getHistoryHydrated(sessionId?: string, opts?: DehydrationOptions): HydratedEntry[];
+    getHistoryLength(sessionId?: string): number;
+    getBranches(sessionId?: string): Record<BranchId, ThoughtData[]>;
+    getBranchIds(sessionId?: string): BranchId[];
+    /** Returns validation state without creating a session, binding an owner, or updating LRU data. */
+    inspectSession(sessionId: string): HistorySessionSnapshot;
+    /** @throws {ValidationError} If branchId is empty or already exists. */
+    registerBranch(sessionId: string | undefined, branchId: BranchId): void;
+    branchExists(sessionId: string | undefined, branchId: BranchId): boolean;
+    getAvailableMcpTools(sessionId?: string): string[] | undefined;
+    getAvailableSkills(sessionId?: string): string[] | undefined;
+    getBranch(branchId: BranchId, sessionId?: string): ThoughtData[] | undefined;
+    /** Clears only persistence-disabled state synchronously. */
+    clear(sessionId?: string): void;
+    /** Awaitably deletes one authorized durable namespace before replacing its live state. */
+    resetSession(sessionId: string, clearAuxiliaryState?: () => void): Promise<void>;
+    /** Performs scoped reset work while its lifecycle exclusive is already owned. */
+    resetSessionWithinExclusive(sessionId: SessionId, clearAuxiliaryState?: () => void): Promise<void>;
+    /** Awaitably deletes all durable namespaces from a trusted ownerless context. */
+    resetAll(clearAuxiliaryState?: () => void): Promise<void>;
+    /** Performs global reset work while its lifecycle exclusive is already owned. */
+    resetAllWithinExclusive(clearAuxiliaryState?: () => void): Promise<void>;
+    clearSession(sessionId: string): void;
+    getSessionIds(): string[];
+    getSessionCount(): number;
+    private _restoredState;
+    /** Loads and atomically commits every authoritative persistence namespace. Call at init. */
+    loadFromPersistence(): Promise<void>;
+    isPersistenceEnabled(): boolean;
+    getPersistenceBackend(): PersistenceBackend | null;
+    /** Sets the event emitter for persistence error events (post-construction wiring). */
+    setEventEmitter(emitter: PersistenceEventEmitter): void;
+    /**
+     * Binds shutdown to the resource owner responsible for the complete cleanup sequence.
+     *
+     * @internal
+     * @param owner - Callback returning the owner's memoized shutdown promise.
+     * @throws {TypeError} When a shutdown owner has already been bound.
+     */
+    bindShutdownOwner(owner: () => Promise<void>): void;
+    /** Stops timers, drains writes, and clears live state under one memoized lifecycle settlement. */
+    shutdown(): Promise<void>;
+    /** Stops timers and drains writes while the caller owns global shutdown. */
+    shutdownWithinLifecycle(): Promise<void>;
+    /** Clears non-durable state after every shutdown resource has closed successfully. */
+    clearLiveStateAfterShutdown(): void;
+    /** Number of coordinator-owned thought writes not yet acknowledged successful. */
+    getWriteBufferLength(): number;
+}
+//# sourceMappingURL=HistoryManager.d.ts.map