@iworkforces/tracelattice 2.0.3

package/dist/core/InputNormalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core/InputNormalizer.js","sources":["../../src/core/InputNormalizer.ts"],"sourcesContent":["/**\n * Input normalization for common LLM field name mistakes.\n *\n * This module provides normalization logic to handle common mistakes\n * that LLMs make when generating field names, such as using singular\n * instead of plural forms (e.g., `recommended_tool` vs `recommended_tools`).\n *\n * It also fills in sensible defaults for missing fields in `previous_steps`,\n * which LLMs naturally provide as partial/skeletal data (historical context).\n *\n * @module processor\n */\n\nimport { ValidationError } from '../errors.js';\nimport {\n\tsanitizeString,\n\tsanitizeRationale,\n\tsanitizeStepField,\n\tsanitizeSuggestedInputs,\n} from '../sanitize.js';\nimport type { ThoughtData } from './thought.js';\nimport { SESSION_ID_PATTERN, MAX_SESSION_ID_LENGTH } from './ids.js';\nimport { asBranchId, asSessionId, generateThoughtId, type BranchId } from '../contracts/ids.js';\n\n/**\n * Default values for missing partial recommendation fields.\n *\n * Shared between tool and skill recommendations (identical defaults).\n */\nconst DEFAULT_RECOMMENDATION_CONFIDENCE = 0.5;\nconst DEFAULT_RECOMMENDATION_PRIORITY = 999;\nconst DEFAULT_RECOMMENDATION_RATIONALE = '';\nconst DEFAULT_STEP_OUTCOME = '';\n\n/**\n * Recursively sanitizes all string values within an unknown structure.\n * Walks into plain objects and arrays to reach deeply nested strings.\n * Non-plain objects (Date, RegExp, etc.) are returned as-is.\n *\n * @param value - The value to sanitize recursively\n * @returns The sanitized value with all nested strings cleaned\n *\n * @example\n * ```typescript\n * sanitizeRecursive('<script>x</script>'); // 'x'\n * sanitizeRecursive({ a: { b: '<iframe>y' } }); // { a: { b: 'y' } }\n * sanitizeRecursive(['a\\x00b', 42]); // ['ab', 42]\n * ```\n */\nexport function sanitizeRecursive(value: unknown): unknown {\n\tif (value === null || value === undefined) {\n\t\treturn value;\n\t}\n\tif (typeof value === 'string') {\n\t\treturn sanitizeString(value);\n\t}\n\tif (Array.isArray(value)) {\n\t\treturn value.map((item) => sanitizeRecursive(item));\n\t}\n\tif (typeof value === 'object') {\n\t\t// Only recurse into plain objects — skip Date, RegExp, Map, Set, etc.\n\t\tconst proto = Object.getPrototypeOf(value);\n\t\tif (proto !== Object.prototype && proto !== null) {\n\t\t\treturn value;\n\t\t}\n\t\tconst result: Record<string, unknown> = {};\n\t\tfor (const [key, val] of Object.entries(value as Record<string, unknown>)) {\n\t\t\tresult[key] = sanitizeRecursive(val);\n\t\t}\n\t\treturn result;\n\t}\n\treturn value;\n}\n\n/**\n * Valid branch ID pattern: alphanumeric, hyphens, underscores only.\n * Prevents path traversal attacks by rejecting special characters like / . \\ etc.\n */\nconst BRANCH_ID_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;\n\n/**\n * Sanitizes and validates a branch ID to prevent path traversal attacks.\n *\n * @param branchId - The branch ID to sanitize\n * @returns The sanitized branch ID\n * @throws ValidationError if the branch ID contains invalid characters\n *\n * @example\n * ```typescript\n * sanitizeBranchId('my-branch_01'); // 'my-branch_01'\n * sanitizeBranchId('../etc/passwd'); // throws ValidationError\n * ```\n */\nexport function sanitizeBranchId(branchId: string): BranchId {\n\t// Validate format\n\tif (!BRANCH_ID_PATTERN.test(branchId)) {\n\t\tthrow new ValidationError(\n\t\t\t'branch_id',\n\t\t\t'Invalid format - must be 1-64 alphanumeric characters, hyphens, or underscores only'\n\t\t);\n\t}\n\treturn asBranchId(branchId);\n}\n\n/**\n * Sanitizes and validates a session ID.\n *\n * @param sessionId - The session ID to sanitize\n * @returns The sanitized session ID, or undefined if invalid after sanitization\n *\n * @example\n * ```typescript\n * sanitizeSessionId('analysis-task-42'); // 'analysis-task-42'\n * sanitizeSessionId('bad session!'); // undefined (stripped)\n * ```\n */\nexport function sanitizeSessionId(sessionId: string): string | undefined {\n\t// First sanitize control characters\n\tconst cleaned = sanitizeString(sessionId);\n\t// Validate format after sanitization\n\tif (cleaned.length > MAX_SESSION_ID_LENGTH || !SESSION_ID_PATTERN.test(cleaned)) {\n\t\treturn undefined;\n\t}\n\treturn cleaned;\n}\n\n/**\n * Normalizes a recommendation object (tool or skill) with default values.\n *\n * Fills in sensible defaults for missing optional fields:\n * - `confidence`: 0.5\n * - `priority`: 999\n * - `rationale`: empty string\n *\n * @param rec - The recommendation object to normalize\n * @returns The normalized recommendation with defaults filled in\n *\n * @example\n * ```typescript\n * const input = { tool_name: 'Read', rationale: 'Read the file' };\n * const normalized = normalizeRecommendation(input);\n * // { tool_name: 'Read', rationale: 'Read the file', confidence: 0.5, priority: 999 }\n * ```\n */\nfunction normalizeRecommendation(rec: Record<string, unknown>): Record<string, unknown> {\n\tconst normalized: Record<string, unknown> = { ...rec };\n\n\t// Fill in default confidence if missing\n\tif (!('confidence' in normalized) || normalized.confidence === undefined) {\n\t\tnormalized.confidence = DEFAULT_RECOMMENDATION_CONFIDENCE;\n\t}\n\n\t// Fill in default priority if missing\n\tif (!('priority' in normalized) || normalized.priority === undefined) {\n\t\tnormalized.priority = DEFAULT_RECOMMENDATION_PRIORITY;\n\t}\n\n\t// Fill in default rationale if missing\n\t// Fill in default rationale if missing, otherwise sanitize urgency phrases + cap length\n\tif (!('rationale' in normalized) || normalized.rationale === undefined) {\n\t\tnormalized.rationale = DEFAULT_RECOMMENDATION_RATIONALE;\n\t} else if (typeof normalized.rationale === 'string') {\n\t\tnormalized.rationale = sanitizeRationale(normalized.rationale);\n\t}\n\t// Sanitize suggested_inputs: enforce flat primitives, key cap, value-length cap\n\tif (\n\t\tnormalized.suggested_inputs &&\n\t\ttypeof normalized.suggested_inputs === 'object' &&\n\t\t!Array.isArray(normalized.suggested_inputs)\n\t) {\n\t\tnormalized.suggested_inputs = sanitizeSuggestedInputs(\n\t\t\tnormalized.suggested_inputs as Record<string, unknown>\n\t\t);\n\t}\n\n\treturn normalized;\n}\n/**\n * Normalizes step recommendation objects.\n *\n * Handles common field name mistakes:\n * - `recommended_tool` (singular) → `recommended_tools` (plural)\n * - `recommended_skill` (singular) → `recommended_skills` (plural)\n *\n * Also normalizes tool recommendations within the step to fill in defaults.\n *\n * @param step - The step recommendation to normalize\n * @param lenient - Whether to use lenient mode (fill in defaults for missing fields)\n * @returns The normalized step recommendation\n *\n * @example\n * ```typescript\n * // Strict mode (for current_step)\n * const input = {\n *   step_description: 'Analyze data',\n *   recommended_tool: [{ tool_name: 'Read', confidence: 0.9, rationale: 'test', priority: 1 }],\n *   expected_outcome: 'Data analyzed'\n * };\n * const normalized = normalizeStepRecommendation(input, false);\n * // normalized.recommended_tools exists (plural form)\n *\n * // Lenient mode (for previous_steps)\n * const partialInput = {\n *   step_description: 'Read file',\n *   recommended_tools: [{ tool_name: 'Read', rationale: 'Read file' }]\n * };\n * const normalized = normalizeStepRecommendation(partialInput, true);\n * // confidence: 0.5, priority: 999, expected_outcome: '' filled in\n * ```\n */\nfunction normalizeStepRecommendation(\n\tstep: Record<string, unknown>,\n\tlenient: boolean\n): Record<string, unknown> {\n\tconst normalized: Record<string, unknown> = { ...step };\n\n\t// Transform `recommended_tool` (singular) → `recommended_tools` (plural)\n\tif ('recommended_tool' in normalized && !('recommended_tools' in normalized)) {\n\t\tnormalized.recommended_tools = normalized.recommended_tool;\n\t\tdelete normalized.recommended_tool;\n\t}\n\n\t// Transform `recommended_skill` (singular) → `recommended_skills` (plural)\n\tif ('recommended_skill' in normalized && !('recommended_skills' in normalized)) {\n\t\tnormalized.recommended_skills = normalized.recommended_skill;\n\t\tdelete normalized.recommended_skill;\n\t}\n\n\t// Normalize recommended_tools array if present\n\tif (Array.isArray(normalized.recommended_tools)) {\n\t\tnormalized.recommended_tools = normalized.recommended_tools.map((tool) =>\n\t\t\ttypeof tool === 'object' && tool !== null\n\t\t\t\t? normalizeRecommendation(tool as Record<string, unknown>)\n\t\t\t\t: tool\n\t\t);\n\t}\n\n\t// Normalize recommended_skills array if present\n\tif (Array.isArray(normalized.recommended_skills)) {\n\t\tnormalized.recommended_skills = normalized.recommended_skills.map((skill) =>\n\t\t\ttypeof skill === 'object' && skill !== null\n\t\t\t\t? normalizeRecommendation(skill as Record<string, unknown>)\n\t\t\t\t: skill\n\t\t);\n\t}\n\t// Sanitize step-level string fields for prompt injection prevention\n\tif (typeof normalized.step_description === 'string') {\n\t\tnormalized.step_description = sanitizeStepField(normalized.step_description);\n\t}\n\tif (typeof normalized.expected_outcome === 'string') {\n\t\tnormalized.expected_outcome = sanitizeStepField(normalized.expected_outcome);\n\t}\n\tif (Array.isArray(normalized.next_step_conditions)) {\n\t\tnormalized.next_step_conditions = normalized.next_step_conditions.map((cond: unknown) =>\n\t\t\ttypeof cond === 'string' ? sanitizeStepField(cond) : cond\n\t\t);\n\t}\n\t// In lenient mode, fill in default expected_outcome if missing\n\tif (lenient && !('expected_outcome' in normalized)) {\n\t\tnormalized.expected_outcome = DEFAULT_STEP_OUTCOME;\n\t}\n\n\treturn normalized;\n}\n\n/**\n * Normalizes reasoning-specific fields on a thought input object.\n * Always applies reasoning normalization — reasoning is the default pipeline.\n * Applies the following normalization rules:\n * - Defaults `thought_type` to `'regular'` if not provided\n * - Clamps `quality_score` to [0, 1] range\n * - Clamps `confidence` to [0, 1] range\n * - Sanitizes `hypothesis_id` using `sanitizeBranchId` pattern\n * - Filters `synthesis_sources` to positive integers only\n * - Filters `merge_from_thoughts` to positive integers only\n * - Sanitizes each entry in `merge_branch_ids`\n * - Defaults `reasoning_depth` to `'moderate'` for hypothesis/verification types\n *\n * @param input - The mutable normalized input object to apply reasoning defaults to\n *\n * @example\n * ```typescript\n * const input: Record<string, unknown> = { thought_type: 'hypothesis', quality_score: 1.5 };\n * normalizeReasoningFields(input);\n * // input.quality_score === 1, input.reasoning_depth === 'moderate'\n * ```\n */\nexport function normalizeReasoningFields(input: Record<string, unknown>): void {\n\t// Always apply reasoning field normalization — reasoning is the default pipeline\n\t// Default thought_type to 'regular'\n\n\tif (!('thought_type' in input) || input.thought_type === undefined) {\n\t\tinput.thought_type = 'regular';\n\t}\n\n\t// Clamp quality_score to [0, 1]\n\tif (typeof input.quality_score === 'number') {\n\t\tinput.quality_score = Math.max(0, Math.min(1, input.quality_score));\n\t}\n\n\t// Clamp confidence to [0, 1]\n\tif (typeof input.confidence === 'number') {\n\t\tinput.confidence = Math.max(0, Math.min(1, input.confidence));\n\t}\n\n\t// Sanitize hypothesis_id (same rules as branch_id)\n\tif (typeof input.hypothesis_id === 'string') {\n\t\tinput.hypothesis_id = sanitizeBranchId(input.hypothesis_id);\n\t}\n\n\t// Filter synthesis_sources to positive integers only\n\tif (Array.isArray(input.synthesis_sources)) {\n\t\tinput.synthesis_sources = input.synthesis_sources.filter(\n\t\t\t(v: unknown) => typeof v === 'number' && Number.isInteger(v) && v > 0\n\t\t);\n\t}\n\n\t// Filter merge_from_thoughts to positive integers only\n\tif (Array.isArray(input.merge_from_thoughts)) {\n\t\tinput.merge_from_thoughts = input.merge_from_thoughts.filter(\n\t\t\t(v: unknown) => typeof v === 'number' && Number.isInteger(v) && v > 0\n\t\t);\n\t}\n\n\t// Sanitize merge_branch_ids entries\n\tif (Array.isArray(input.merge_branch_ids)) {\n\t\tinput.merge_branch_ids = input.merge_branch_ids.map((id: unknown) => {\n\t\t\tif (typeof id === 'string') {\n\t\t\t\treturn sanitizeBranchId(id);\n\t\t\t}\n\t\t\treturn id;\n\t\t});\n\t}\n\n\t// Default reasoning_depth to 'moderate' for hypothesis/verification types\n\tif (\n\t\t(input.thought_type === 'hypothesis' || input.thought_type === 'verification') &&\n\t\t!('reasoning_depth' in input)\n\t) {\n\t\tinput.reasoning_depth = 'moderate';\n\t}\n}\n\n/**\n * Normalizes thought input data by fixing common LLM field name mistakes.\n *\n * This function handles cases where LLMs incorrectly use singular forms\n * of field names that should be plural. It applies normalization to both\n * `current_step` and `previous_steps` fields.\n *\n * The normalization is applied BEFORE schema validation, allowing the\n * strict Valibot schema to remain correct while still being tolerant\n * of common LLM mistakes.\n *\n * @param input - The raw thought input data to normalize\n * @returns Normalized thought data with correct field names\n *\n * @remarks\n * **Normalization Rules:**\n * - `recommended_tool` (singular) → `recommended_tools` (plural)\n * - `recommended_skill` (singular) → `recommended_skills` (plural)\n * - Applied to `current_step` if present (strict mode)\n * - Applied to all items in `previous_steps` if present (lenient mode with defaults)\n *\n * **Design Rationale:**\n * LLMs sometimes use singular field names even when the schema explicitly\n * defines plural forms. Rather than forcing the LLM to be perfect (which\n * leads to cryptic validation errors), we normalize the input to handle\n * these common mistakes gracefully.\n *\n * Additionally, LLMs naturally provide complete data for `current_step`\n * but only partial/skeletal data for `previous_steps` (historical context).\n * The lenient mode for `previous_steps` fills in sensible defaults:\n * - `confidence`: 0.5 for missing tool recommendation confidence\n * - `priority`: 999 for missing tool recommendation priority\n * - `rationale`: empty string for missing tool recommendation rationale\n * - `expected_outcome`: empty string for missing step expected outcome\n *\n * @example\n * ```typescript\n * const input = {\n *   thought: 'I need to analyze the data',\n *   thought_number: 1,\n *   total_thoughts: 3,\n *   next_thought_needed: true,\n *   current_step: {\n *     step_description: 'Read the data file',\n *     recommended_tool: [{ tool_name: 'Read', confidence: 0.9, rationale: 'test', priority: 1 }],\n *     expected_outcome: 'Data loaded'\n *   },\n *   previous_steps: [{\n *     step_description: 'Previous step',\n *     recommended_tools: [{ tool_name: 'Grep', rationale: 'Search code' }]\n *   }]\n * };\n *\n * const normalized = normalizeInput(input);\n * // current_step: recommended_tools exists (plural form)\n * // previous_steps[0]: confidence=0.5, priority=999, expected_outcome='' filled in\n * ```\n */\nexport function normalizeInput(input: unknown): ThoughtData {\n\tif (typeof input !== 'object' || input === null) {\n\t\treturn input as ThoughtData;\n\t}\n\n\tconst normalized = { ...input } as Record<string, unknown>;\n\n\t// Normalize current_step if present (strict mode - no defaults)\n\tif (normalized.current_step && typeof normalized.current_step === 'object') {\n\t\tnormalized.current_step = normalizeStepRecommendation(\n\t\t\tnormalized.current_step as Record<string, unknown>,\n\t\t\tfalse // strict mode\n\t\t);\n\t}\n\n\t// Normalize all items in previous_steps if present (lenient mode - with defaults)\n\tif (Array.isArray(normalized.previous_steps) && normalized.previous_steps.length > 0) {\n\t\tnormalized.previous_steps = normalized.previous_steps.map((step) =>\n\t\t\ttypeof step === 'object' && step !== null\n\t\t\t\t? normalizeStepRecommendation(step as Record<string, unknown>, true) // lenient mode\n\t\t\t\t: step\n\t\t);\n\t}\n\n\t// Sanitize branch_id to prevent path traversal attacks\n\tif (typeof normalized.branch_id === 'string') {\n\t\tnormalized.branch_id = sanitizeBranchId(normalized.branch_id);\n\t}\n\n\t// Explicit identity is validated, never sanitized into another namespace.\n\tif (typeof normalized.session_id === 'string') {\n\t\tnormalized.session_id = asSessionId(normalized.session_id);\n\t}\n\n\tif (typeof normalized.register_branch_id === 'string') {\n\t\tnormalized.register_branch_id = sanitizeBranchId(normalized.register_branch_id);\n\t}\n\n\t// Auto-generate id if not provided (for DAG node identity)\n\tif (!normalized.id || typeof normalized.id !== 'string') {\n\t\tnormalized.id = generateThoughtId();\n\t}\n\n\t// Normalize reasoning fields\n\tnormalizeReasoningFields(normalized);\n\n\t// Sanitize meta_observation for prompt injection prevention\n\tif (typeof normalized.meta_observation === 'string') {\n\t\tnormalized.meta_observation = sanitizeStepField(normalized.meta_observation);\n\t}\n\n\t// Sanitize all free-text string fields recursively (dangerous HTML tags + null bytes)\n\t// This was moved from schema transforms because v.transform() cannot be converted to JSON Schema\n\tconst sanitized = sanitizeRecursive(normalized);\n\n\treturn sanitized as ThoughtData;\n}\n"],"names":["DEFAULT_RECOMMENDATION_CONFIDENCE","DEFAULT_RECOMMENDATION_PRIORITY","DEFAULT_RECOMMENDATION_RATIONALE","DEFAULT_STEP_OUTCOME","sanitizeRecursive","value","sanitizeString","Array","item","proto","Object","result","key","val","BRANCH_ID_PATTERN","sanitizeBranchId","branchId","ValidationError","asBranchId","sanitizeSessionId","sessionId","cleaned","MAX_SESSION_ID_LENGTH","SESSION_ID_PATTERN","normalizeRecommendation","rec","normalized","undefined","sanitizeRationale","sanitizeSuggestedInputs","normalizeStepRecommendation","step","lenient","tool","skill","sanitizeStepField","cond","normalizeReasoningFields","input","Math","v","Number","id","normalizeInput","asSessionId","generateThoughtId","sanitized"],"mappings":"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"}

package/dist/core/PersistenceBuffer.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Joinable coordinator for attributable persistence work.
+ *
+ * @module PersistenceBuffer
+ */
+import type { PersistenceBackend } from '../contracts/PersistenceBackend.js';
+import type { IEdgeStore } from '../contracts/interfaces.js';
+import type { BranchId, SessionId } from '../contracts/ids.js';
+import type { Logger } from '../logger/StructuredLogger.js';
+import type { Summary } from './compression/Summary.js';
+import type { Edge } from './graph/Edge.js';
+import { type PersistenceDelay } from './PersistenceWriter.js';
+import type { ThoughtData } from './thought.js';
+/** Minimal compatibility view for legacy callers that own a `writeBuffer`. */
+export interface BufferedSession {
+    writeBuffer: ThoughtData[];
+}
+/** Event emitter contract for persistence error events. */
+export interface PersistenceEventEmitter {
+    emit(event: 'persistenceError', payload: {
+        operation: string;
+        error: Error;
+    }): boolean;
+}
+/** Observable persistence state relevant to safe in-memory session eviction. */
+export type SessionEvictionState = 'quiescent' | 'pending' | 'failed' | 'barrier';
+/** Configuration options for {@link PersistenceBuffer}. */
+export interface PersistenceBufferConfig<S extends BufferedSession> {
+    readonly persistence: PersistenceBackend;
+    readonly bufferSize: number;
+    readonly flushInterval: number;
+    readonly maxRetries: number;
+    readonly defaultSessionId: SessionId;
+    /** Compatibility-only session source retained until producer wiring is migrated. */
+    readonly getSessions: () => Map<SessionId, S>;
+    /** Compatibility-only default session retained until producer wiring is migrated. */
+    readonly getDefaultSession: () => S;
+    /** Compatibility-only edge source retained until producers register snapshots. */
+    readonly edgeStore?: IEdgeStore;
+    /** Optional emitter for `persistenceError` events. */
+    readonly eventEmitter?: PersistenceEventEmitter | null;
+    readonly logger?: Logger;
+    /** Optional retry scheduler for deterministic coordination and testing. */
+    readonly delay?: PersistenceDelay;
+}
+/**
+ * Coordinates one globally joinable persistence generation at a time.
+ *
+ * Accepted work is owned by a queue independent of live session state. Explicit
+ * callers can join and upgrade a background generation without starting another writer.
+ */
+export declare class PersistenceBuffer<S extends BufferedSession> {
+    private readonly _bufferSize;
+    private readonly _flushInterval;
+    private readonly _defaultSessionId;
+    private readonly _queue;
+    private readonly _writer;
+    private _eventEmitter;
+    private readonly _logger;
+    private _flushTimer;
+    private _activeDrain;
+    private readonly _sessionBarriers;
+    private readonly _sessionBarrierOwnership;
+    private readonly _sessionProgressWaiters;
+    private readonly _quarantinedSessions;
+    private readonly _evictionQuarantinedSessions;
+    private _globalResetTail;
+    private _globalResetOwners;
+    private _globalQuarantined;
+    /**
+     * Creates a persistence-drain coordinator.
+     *
+     * @param config - Persistence dependencies, trigger thresholds, and retry policy.
+     */
+    constructor(config: PersistenceBufferConfig<S>);
+    /** @returns The underlying flush timer for lifecycle introspection. */
+    get timer(): ReturnType<typeof setInterval> | null;
+    /** @returns Whether a global drain generation is active. */
+    get isFlushing(): boolean;
+    /** @returns Number of accepted thought writes not yet acknowledged successful. */
+    get pendingThoughtCount(): number;
+    /**
+     * Sets or clears the persistence error event emitter.
+     *
+     * @param emitter - Replacement emitter, or `null` to disable events.
+     */
+    setEventEmitter(emitter: PersistenceEventEmitter | null): void;
+    /**
+     * Accepts a thought with authoritative session attribution.
+     *
+     * The legacy session overload derives attribution from `thought.session_id` and
+     * falls back to the configured default session without using the live write buffer.
+     *
+     * @param sessionId - Session that owns the accepted thought.
+     * @param thought - Thought to persist.
+     */
+    bufferThought(sessionId: SessionId, thought: ThoughtData): void;
+    bufferThought(session: BufferedSession, thought: ThoughtData): void;
+    /**
+     * Accepts the latest snapshot for one session-owned branch.
+     *
+     * @param sessionId - Session that owns the branch.
+     * @param branchId - Stable branch coordinate.
+     * @param thoughts - Branch snapshot copied by the queue.
+     */
+    bufferBranch(sessionId: SessionId, branchId: BranchId, thoughts: readonly ThoughtData[]): void;
+    /**
+     * @param sessionId - Session that owns the branch.
+     * @param branchId - Stable branch coordinate to delete.
+     */
+    deleteBranch(sessionId: SessionId, branchId: BranchId): void;
+    /**
+     * Accepts the latest edge snapshot for one session.
+     *
+     * @param sessionId - Session that owns the edges.
+     * @param edges - Edge snapshot copied by the queue.
+     */
+    bufferEdges(sessionId: SessionId, edges: readonly Edge[]): void;
+    /**
+     * Accepts the latest summary snapshot for one session.
+     *
+     * @param sessionId - Session that owns the summaries.
+     * @param summaries - Summary snapshot copied by the queue.
+     */
+    bufferSummaries(sessionId: SessionId, summaries: readonly Summary[]): void;
+    /** Rejects synchronously when lifecycle coordination has closed persistence admission. */
+    assertSessionAdmissionOpen(sessionId: SessionId): void;
+    /** Starts the periodic background-drain timer without keeping the process alive. */
+    startFlushTimer(): void;
+    /** Stops the periodic background-drain timer. */
+    stopFlushTimer(): void;
+    /**
+     * Starts or joins an explicit global drain generation.
+     *
+     * @returns The exact shared promise for the active generation.
+     */
+    drain(): Promise<void>;
+    /** @returns The exact same promise as {@link drain} for the active generation. */
+    flush(): Promise<void>;
+    /**
+     * Joins the global explicit generation and projects its terminal failures to one session.
+     * This method does not close admission; lifecycle owners must use
+     * {@link withSessionBarrier} when work must not cross an owner callback.
+     *
+     * @param sessionId - Session whose accepted writes form the barrier projection.
+     * @returns A promise that rejects only for that session's failures or an unknown fault.
+     */
+    drainSession(sessionId: SessionId): Promise<void>;
+    /** Returns queue-derived persistence state for safe session eviction planning. */
+    sessionEvictionState(sessionId: SessionId): SessionEvictionState;
+    /**
+     * Drains accepted session work before ordinary in-memory eviction cleanup.
+     *
+     * Unlike reset barriers, this operation never clears durable state or discards
+     * accepted work. Failure retains admission quarantine until a later explicit
+     * invocation successfully drains and completes cleanup.
+     */
+    withSessionEvictionBarrier<T>(sessionId: SessionId, operation: () => Promise<T>): Promise<T>;
+    /** Forgets queue coordinates only when the session is fully quiescent. */
+    forgetQuiescentSession(sessionId: SessionId): boolean;
+    /**
+     * Runs one lifecycle operation while persistence admission is closed for a session.
+     *
+     * Admission closes synchronously when this method is called. Already accepted work for
+     * the session is settled first; an exhausted session failure rejects without invoking
+     * `operation`. Concurrent calls for the same session execute in FIFO call order and keep
+     * admission closed until the final callback settles. Other sessions remain admissible and
+     * may be owned by a nested callback. Reacquiring the same session from the owning callback's
+     * async call chain rejects before joining the FIFO because awaiting it would deadlock its owner.
+     *
+     * @example
+     * ```ts
+     * await buffer.withSessionBarrier(sessionId, async () => {
+     *   await persistence.clearSession(sessionId);
+     * });
+     * ```
+     *
+     * @param sessionId - Session exclusively owned for the callback duration.
+     * @param operation - Awaited lifecycle operation run only after prior work settles.
+     * @returns The callback result after admission has reopened when no owner remains.
+     * @throws {@link PersistenceSessionBarrierReentrancyError} when the owning async call chain
+     * attempts to reacquire `sessionId`.
+     */
+    withSessionBarrier<T>(sessionId: SessionId, operation: () => Promise<T>): Promise<T>;
+    /**
+     * Runs a scoped reset, retaining admission quarantine on failure.
+     * A retry may pass retained write failures because successful durable deletion
+     * invalidates those stale queue entries before admission reopens.
+     */
+    withSessionResetBarrier<T>(sessionId: SessionId, operation: () => Promise<T>): Promise<T>;
+    /** Runs a trusted global reset behind a global admission barrier. */
+    withGlobalResetBarrier<T>(operation: () => Promise<T>): Promise<T>;
+    private _joinOrStart;
+    private _triggerBackgroundDrain;
+    private _runDrain;
+    private _closeGeneration;
+    private _awaitSessionQuiescence;
+    private _sessionQuiescence;
+    private _waitForSessionProgress;
+    private _notifySessionProgress;
+    private _assertSessionAdmissionOpen;
+    private _observeFailure;
+}
+//# sourceMappingURL=PersistenceBuffer.d.ts.map

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

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

package/dist/core/PersistenceBuffer.js

@@ -0,0 +1,382 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { PersistenceDrainError, PersistenceSessionAdmissionClosedError, PersistenceSessionBarrierReentrancyError } from "./PersistenceBufferErrors.js";
+import { NullLogger } from "../logger/NullLogger.js";
+import { assertNever } from "../utils.js";
+import { PersistenceWorkQueue } from "./PersistenceWorkQueue.js";
+import { PersistenceWriter } from "./PersistenceWriter.js";
+class PersistenceBuffer {
+    _bufferSize;
+    _flushInterval;
+    _defaultSessionId;
+    _queue = new PersistenceWorkQueue();
+    _writer;
+    _eventEmitter;
+    _logger;
+    _flushTimer = null;
+    _activeDrain = null;
+    _sessionBarriers = new Map();
+    _sessionBarrierOwnership = new AsyncLocalStorage();
+    _sessionProgressWaiters = new Map();
+    _quarantinedSessions = new Set();
+    _evictionQuarantinedSessions = new Set();
+    _globalResetTail = Promise.resolve();
+    _globalResetOwners = 0;
+    _globalQuarantined = false;
+    constructor(config){
+        this._bufferSize = config.bufferSize;
+        this._flushInterval = config.flushInterval;
+        this._defaultSessionId = config.defaultSessionId;
+        this._eventEmitter = config.eventEmitter ?? null;
+        this._logger = config.logger ?? new NullLogger();
+        this._writer = new PersistenceWriter({
+            persistence: config.persistence,
+            maxRetries: config.maxRetries,
+            delay: config.delay
+        });
+    }
+    get timer() {
+        return this._flushTimer;
+    }
+    get isFlushing() {
+        return null !== this._activeDrain;
+    }
+    get pendingThoughtCount() {
+        return this._queue.pendingThoughtCount;
+    }
+    setEventEmitter(emitter) {
+        this._eventEmitter = emitter;
+    }
+    bufferThought(source, thought) {
+        const sessionId = 'string' == typeof source ? source : thought.session_id ?? this._defaultSessionId;
+        this._assertSessionAdmissionOpen(sessionId);
+        if (this._queue.pendingThoughtCount >= this._bufferSize && this.isFlushing) this._logger.info('Write buffer full and flush in progress, applying backpressure', {
+            bufferSize: this._queue.pendingThoughtCount,
+            maxSize: this._bufferSize
+        });
+        this._queue.enqueueThought(sessionId, thought);
+        if (this._queue.pendingThoughtCount >= this._bufferSize) this._triggerBackgroundDrain();
+    }
+    bufferBranch(sessionId, branchId, thoughts) {
+        this._assertSessionAdmissionOpen(sessionId);
+        this._queue.replaceBranch(sessionId, branchId, thoughts);
+    }
+    deleteBranch(sessionId, branchId) {
+        this._assertSessionAdmissionOpen(sessionId);
+        this._queue.deleteBranch(sessionId, branchId);
+    }
+    bufferEdges(sessionId, edges) {
+        this._assertSessionAdmissionOpen(sessionId);
+        this._queue.replaceEdges(sessionId, edges);
+    }
+    bufferSummaries(sessionId, summaries) {
+        this._assertSessionAdmissionOpen(sessionId);
+        this._queue.replaceSummaries(sessionId, summaries);
+    }
+    assertSessionAdmissionOpen(sessionId) {
+        this._assertSessionAdmissionOpen(sessionId);
+    }
+    startFlushTimer() {
+        if (null !== this._flushTimer) return;
+        this._flushTimer = setInterval(()=>this._triggerBackgroundDrain(), this._flushInterval);
+        if ('object' == typeof this._flushTimer && 'unref' in this._flushTimer) this._flushTimer.unref();
+    }
+    stopFlushTimer() {
+        if (null === this._flushTimer) return;
+        clearInterval(this._flushTimer);
+        this._flushTimer = null;
+    }
+    drain() {
+        return this._joinOrStart('explicit').promise;
+    }
+    flush() {
+        return this.drain();
+    }
+    drainSession(sessionId) {
+        const generation = this._joinOrStart('explicit');
+        return generation.promise.catch((reason)=>{
+            if (!(reason instanceof PersistenceDrainError)) throw reason;
+            const failures = reason.failures.filter((failure)=>failure.sessionId === sessionId);
+            if (failures.length > 0) throw new PersistenceDrainError(failures);
+        });
+    }
+    sessionEvictionState(sessionId) {
+        if (this._globalResetOwners > 0 || this._sessionBarriers.has(sessionId)) return 'barrier';
+        if (this._globalQuarantined || this._queue.hasSessionTerminalFailure(sessionId) || this._quarantinedSessions.has(sessionId) || this._evictionQuarantinedSessions.has(sessionId)) return 'failed';
+        return this._queue.hasSessionWork(sessionId) ? 'pending' : 'quiescent';
+    }
+    withSessionEvictionBarrier(sessionId, operation) {
+        if (this._globalResetOwners > 0 || this._globalQuarantined || this._quarantinedSessions.has(sessionId)) return Promise.reject(new PersistenceSessionAdmissionClosedError(sessionId));
+        const currentOwnership = this._sessionBarrierOwnership.getStore();
+        if (currentOwnership?.has(sessionId) === true) return Promise.reject(new PersistenceSessionBarrierReentrancyError(sessionId));
+        const operationOwnership = new Set(currentOwnership);
+        operationOwnership.add(sessionId);
+        const state = this._sessionBarriers.get(sessionId) ?? {
+            tail: Promise.resolve(),
+            pendingOwners: 0
+        };
+        this._sessionBarriers.set(sessionId, state);
+        state.pendingOwners += 1;
+        const result = state.tail.then(async ()=>{
+            try {
+                await this._awaitSessionQuiescence(sessionId);
+                const value = await this._sessionBarrierOwnership.run(operationOwnership, operation);
+                this._queue.forgetQuiescentSession(sessionId);
+                this._evictionQuarantinedSessions.delete(sessionId);
+                return value;
+            } catch (error) {
+                this._evictionQuarantinedSessions.add(sessionId);
+                throw error;
+            } finally{
+                state.pendingOwners -= 1;
+                if (0 === state.pendingOwners) this._sessionBarriers.delete(sessionId);
+            }
+        });
+        state.tail = result.then(()=>void 0, ()=>void 0);
+        return result;
+    }
+    forgetQuiescentSession(sessionId) {
+        return 'quiescent' === this.sessionEvictionState(sessionId) ? this._queue.forgetQuiescentSession(sessionId) : false;
+    }
+    withSessionBarrier(sessionId, operation) {
+        const currentOwnership = this._sessionBarrierOwnership.getStore();
+        if (currentOwnership?.has(sessionId) === true) return Promise.reject(new PersistenceSessionBarrierReentrancyError(sessionId));
+        const operationOwnership = new Set(currentOwnership);
+        operationOwnership.add(sessionId);
+        const state = this._sessionBarriers.get(sessionId) ?? {
+            tail: Promise.resolve(),
+            pendingOwners: 0
+        };
+        this._sessionBarriers.set(sessionId, state);
+        state.pendingOwners += 1;
+        const result = state.tail.then(async ()=>{
+            try {
+                await this._awaitSessionQuiescence(sessionId);
+                return await this._sessionBarrierOwnership.run(operationOwnership, operation);
+            } finally{
+                state.pendingOwners -= 1;
+                if (0 === state.pendingOwners) this._sessionBarriers.delete(sessionId);
+            }
+        });
+        state.tail = result.then(()=>void 0, ()=>void 0);
+        return result;
+    }
+    withSessionResetBarrier(sessionId, operation) {
+        if (this._globalResetOwners > 0 || this._globalQuarantined) return Promise.reject(new PersistenceSessionAdmissionClosedError(sessionId));
+        const currentOwnership = this._sessionBarrierOwnership.getStore();
+        if (currentOwnership?.has(sessionId) === true) return Promise.reject(new PersistenceSessionBarrierReentrancyError(sessionId));
+        const operationOwnership = new Set(currentOwnership);
+        operationOwnership.add(sessionId);
+        const state = this._sessionBarriers.get(sessionId) ?? {
+            tail: Promise.resolve(),
+            pendingOwners: 0
+        };
+        this._sessionBarriers.set(sessionId, state);
+        state.pendingOwners += 1;
+        const result = state.tail.then(async ()=>{
+            try {
+                try {
+                    await this._awaitSessionQuiescence(sessionId);
+                } catch (error) {
+                    if (!(error instanceof PersistenceDrainError)) throw error;
+                }
+                const value = await this._sessionBarrierOwnership.run(operationOwnership, operation);
+                this._queue.discardSession(sessionId);
+                this._quarantinedSessions.delete(sessionId);
+                this._evictionQuarantinedSessions.delete(sessionId);
+                return value;
+            } catch (error) {
+                this._quarantinedSessions.add(sessionId);
+                throw error;
+            } finally{
+                state.pendingOwners -= 1;
+                if (0 === state.pendingOwners) this._sessionBarriers.delete(sessionId);
+            }
+        });
+        state.tail = result.then(()=>void 0, ()=>void 0);
+        return result;
+    }
+    withGlobalResetBarrier(operation) {
+        this._globalResetOwners += 1;
+        const prior = this._globalResetTail;
+        const result = prior.then(async ()=>{
+            try {
+                await Promise.all(Array.from(this._sessionBarriers.values(), (state)=>state.tail));
+                try {
+                    await this.drain();
+                } catch (error) {
+                    if (!(error instanceof PersistenceDrainError)) throw error;
+                }
+                const value = await operation();
+                this._queue.discardAll();
+                this._quarantinedSessions.clear();
+                this._evictionQuarantinedSessions.clear();
+                this._globalQuarantined = false;
+                return value;
+            } catch (error) {
+                this._globalQuarantined = true;
+                throw error;
+            } finally{
+                this._globalResetOwners -= 1;
+            }
+        });
+        this._globalResetTail = result.then(()=>void 0, ()=>void 0);
+        return result;
+    }
+    _joinOrStart(mode) {
+        const active = this._activeDrain;
+        if (null !== active) {
+            if ('explicit' === mode) active.mode = mode;
+            return active;
+        }
+        let resolveGeneration = ()=>void 0;
+        let rejectGeneration = (_reason)=>void 0;
+        const promise = new Promise((resolve, reject)=>{
+            resolveGeneration = resolve;
+            rejectGeneration = reject;
+        });
+        const generation = {
+            promise,
+            resolve: resolveGeneration,
+            reject: rejectGeneration,
+            selectedTokens: new Set(),
+            mode,
+            backgroundObserved: false,
+            inFlightWork: null,
+            settlement: null
+        };
+        this._activeDrain = generation;
+        this._runDrain(generation).catch((fault)=>{
+            this._closeGeneration(generation, {
+                kind: 'fault',
+                fault
+            });
+        });
+        return generation;
+    }
+    _triggerBackgroundDrain() {
+        const generation = this._joinOrStart('background');
+        if (generation.backgroundObserved) return;
+        generation.backgroundObserved = true;
+        generation.promise.catch(()=>void 0);
+    }
+    async _runDrain(generation) {
+        while(true){
+            const work = this._queue.nextEligibleWork(generation.selectedTokens, generation.mode);
+            if (void 0 === work) return void this._closeGeneration(generation, {
+                kind: 'result'
+            });
+            generation.inFlightWork = work;
+            const result = await this._writer.write(work);
+            if (true === result) this._queue.acknowledgeSuccess(work);
+            else this._queue.acknowledgeFailure(work, result);
+            generation.inFlightWork = null;
+            this._notifySessionProgress();
+        }
+    }
+    _closeGeneration(generation, termination) {
+        if (this._activeDrain !== generation) return;
+        let settlement;
+        switch(termination.kind){
+            case 'result':
+                {
+                    const result = this._queue.generationResult(generation.selectedTokens);
+                    settlement = 0 === result.failures.length ? {
+                        kind: 'resolved'
+                    } : {
+                        kind: 'rejected',
+                        reason: new PersistenceDrainError(result.failures)
+                    };
+                    break;
+                }
+            case 'fault':
+                settlement = {
+                    kind: 'rejected',
+                    reason: termination.fault
+                };
+                break;
+            default:
+                assertNever(termination);
+        }
+        generation.inFlightWork = null;
+        generation.settlement = settlement;
+        this._activeDrain = null;
+        this._notifySessionProgress();
+        switch(settlement.kind){
+            case 'resolved':
+                generation.resolve();
+                return;
+            case 'rejected':
+                generation.reject(settlement.reason);
+                if (settlement.reason instanceof PersistenceDrainError) this._observeFailure(generation, settlement.reason);
+                return;
+            default:
+                assertNever(settlement);
+        }
+    }
+    async _awaitSessionQuiescence(sessionId) {
+        const generation = this._joinOrStart('explicit');
+        generation.promise.catch(()=>void 0);
+        while(true){
+            const quiescence = this._sessionQuiescence(generation, sessionId);
+            switch(quiescence.kind){
+                case 'pending':
+                    await this._waitForSessionProgress(sessionId);
+                    break;
+                case 'resolved':
+                    return;
+                case 'rejected':
+                    throw quiescence.reason;
+                default:
+                    return assertNever(quiescence);
+            }
+        }
+    }
+    _sessionQuiescence(generation, sessionId) {
+        if (generation.settlement?.kind === 'rejected' && !(generation.settlement.reason instanceof PersistenceDrainError)) return {
+            kind: 'rejected',
+            reason: generation.settlement.reason
+        };
+        if (generation.inFlightWork?.sessionId === sessionId) return {
+            kind: 'pending'
+        };
+        if (this._queue.hasEligibleWork(generation.selectedTokens, generation.mode, sessionId)) return {
+            kind: 'pending'
+        };
+        const failures = this._queue.currentFailures(generation.selectedTokens, sessionId);
+        return 0 === failures.length ? {
+            kind: 'resolved'
+        } : {
+            kind: 'rejected',
+            reason: new PersistenceDrainError(failures)
+        };
+    }
+    _waitForSessionProgress(sessionId) {
+        return new Promise((resolve)=>{
+            const waiters = this._sessionProgressWaiters.get(sessionId) ?? new Set();
+            waiters.add(resolve);
+            this._sessionProgressWaiters.set(sessionId, waiters);
+        });
+    }
+    _notifySessionProgress() {
+        for (const [sessionId, waiters] of this._sessionProgressWaiters){
+            this._sessionProgressWaiters.delete(sessionId);
+            for (const resolve of waiters)resolve();
+        }
+    }
+    _assertSessionAdmissionOpen(sessionId) {
+        if (this._globalResetOwners > 0 || this._globalQuarantined || this._sessionBarriers.has(sessionId) || this._quarantinedSessions.has(sessionId) || this._evictionQuarantinedSessions.has(sessionId)) throw new PersistenceSessionAdmissionClosedError(sessionId);
+    }
+    _observeFailure(generation, error) {
+        this._logger.info('Persistence drain completed with failures', {
+            failed: error.failures.length,
+            selected: generation.selectedTokens.size
+        });
+        this._eventEmitter?.emit('persistenceError', {
+            operation: 'flushBuffer',
+            error
+        });
+    }
+}
+export { PersistenceBuffer };
+
+//# sourceMappingURL=PersistenceBuffer.js.map