@iworkforces/tracelattice 2.3.6 → 2.4.0

package/README.md

@@ -151,6 +151,7 @@ persistence:
 persistenceBufferSize: 7 # example file-only override; default 100
 persistenceFlushInterval: 750 # milliseconds, file-only; default 1000
 persistenceMaxRetries: 2 # example file-only override; default 3
+persistenceMaxPendingThoughtsPerSession: 500 # example file-only override; default and maximum 10000
 features:
   dagEdges: true
   reasoningStrategy: sequential # sequential or tot
@@ -210,10 +211,18 @@ environment value is not expanded by `ConfigLoader`. `TRACELATTICE_DISCOVERY_CAC
 300 seconds and becomes `discoveryCache.ttl: 300000` milliseconds. The interleave environment
 variables ending in `_MS` and the corresponding YAML fields use milliseconds.
 
-`persistenceBufferSize` (default 100 thoughts), `persistenceFlushInterval` (default 1000 ms), and
-`persistenceMaxRetries` (default 3) are YAML/JSON settings, not environment variables. There are no
-`TRACELATTICE_PERSISTENCE_BUFFER_SIZE`, `TRACELATTICE_PERSISTENCE_FLUSH_INTERVAL`, or
-`TRACELATTICE_PERSISTENCE_MAX_RETRIES` overrides.
+`persistenceBufferSize` (default 100 thoughts), `persistenceFlushInterval` (default 1000 ms),
+`persistenceMaxRetries` (default 3), and `persistenceMaxPendingThoughtsPerSession` (default 10000,
+allowed 1 to 10000) are YAML/JSON settings, not environment variables. There are no
+`TRACELATTICE_PERSISTENCE_BUFFER_SIZE`, `TRACELATTICE_PERSISTENCE_FLUSH_INTERVAL`,
+`TRACELATTICE_PERSISTENCE_MAX_RETRIES`, or `TRACELATTICE_PERSISTENCE_MAX_PENDING_THOUGHTS_PER_SESSION`
+overrides.
+
+`persistenceMaxPendingThoughtsPerSession` limits the thought and backtrack writes one session may hold
+unacknowledged, counting writes that failed terminally. At the limit a thought is rejected with
+`PERSISTENCE_BACKLOG_FULL` before any history, branch, edge, outcome or suspension state changes, so
+the same call can be retried with the same thought id. Other sessions are unaffected. Each rejection
+also retries the retained failures in the background, so a retry succeeds once the backend is back.
 
 ## Transports
 
@@ -226,6 +235,8 @@ Set `TRACELATTICE_TRANSPORT_TYPE` to pick one:
 
 The Streamable HTTP endpoint defaults to `POST /mcp` for JSON-RPC requests and supports stateful sessions via the `Mcp-Session-Id` header. `GET /mcp` is not allowed. The library also exposes `HttpTransport` for stateless JSON-RPC over HTTP, but the CLI does not select it with `TRACELATTICE_TRANSPORT_TYPE`.
 
+Streamable HTTP also serves `GET /health` (liveness) and `GET /ready` (readiness). Both answer after Host validation and the shutting-down 503 but ahead of the per-client rate limiter, so an orchestrator polling them neither spends nor is rejected by the client budget. They still apply CORS origin validation and headers. With persistence disabled, `/ready` is `ok` with no components. With persistence enabled it probes the backend under a one second deadline: concurrent polls share one probe, a probe that timed out is joined until it settles, and a settled result is reused for one second. `/ready` answers 503 when the probe fails or times out, or when persistence is globally quarantined after a failed global reset. Otherwise it answers 200 and lists the quarantined session count, retained write failure count and pending thought count in the `persistenceBacklog` component details. Those counts do not make the instance unready, because nothing retries retained failures until an explicit drain.
+
 Set all three transport-session retention variables or leave all three unset. Each must be a positive safe integer; the two timing values use milliseconds. With none set, transport sessions remain unbounded and live until shutdown. Retention settings are rejected with `TRACELATTICE_STREAMABLE_HTTP_STATEFUL=false`. At capacity, a request that would create a new session receives HTTP 503 with JSON-RPC code `-32000`. After an idle session is swept, a request using its header receives HTTP 404 with code `-32001`; the client must re-initialize without the old `Mcp-Session-Id`. Sweeps skip sessions with accepted POSTs still in flight and don't change thought sessions (`session_id`), their history, ownership, or TTL handling.
 
 In Streamable HTTP mode, the port and retention values accept only unsigned decimal integers without leading zeros (except `0`), signs, whitespace, or trailing characters, and must be safe integers. `TRACELATTICE_STREAMABLE_HTTP_PORT` accepts 0 through 65535 and defaults to 9007. `TRACELATTICE_STREAMABLE_HTTP_SESSION_SWEEP_INTERVAL_MS` must be at most 2147483647, the largest timer delay Node and Bun honor. Invalid values, a partial retention set, or an unknown `TRACELATTICE_TRANSPORT_TYPE` stop CLI startup with exit code 1. Stdio ignores HTTP-only variables.
@@ -296,7 +307,7 @@ The checked evaluation report separates deterministic structural validation and
 
 ### Persistence, recovery, and backtracking
 
-Library callers can supply their own backend with `createServer({ persistenceBackend })`. This skips the persistence factory and the configured backend, whether or not configured persistence is enabled. The package root exports the implementation types `PersistenceBackend`, `ThoughtData`, `Edge`, `Summary`, `SessionId`, `ThoughtId`, and `BranchId` as types only; deep imports aren't needed. Startup restore reads the injected backend unless `loadFromPersistence: false` is set.
+Library callers can supply their own backend with `createServer({ persistenceBackend })`. This skips the persistence factory and the configured backend, whether or not configured persistence is enabled. The package root exports the implementation types `PersistenceBackend`, `ThoughtData`, `Edge`, `Summary`, `SessionId`, `ThoughtId`, and `BranchId`, plus the restore-read types `PersistenceRestoreRead`, `PersistedSessionRecord`, and `PersistedBranchRecord`, as types only; deep imports aren't needed. Startup restore reads the injected backend unless `loadFromPersistence: false` is set.
 
 An injected backend belongs to the caller. The server drains buffered writes before `stop()` or `dispose()` resolves, but never calls the backend's `close()`, including during startup-failure cleanup. The caller must close it after the awaited shutdown resolves. Factory-created backends are server-owned and closed exactly once.
 
@@ -304,6 +315,8 @@ SQLite selects its driver by runtime. Bun, including the packed `tracelattice` C
 
 `PersistenceBackend` requires `saveBacktrackForSession(sessionId, thought, targetThoughtId)`. Every custom backend must implement it. The operation atomically corrects every retained stable-ID copy of the target, appends the backtrack thought, and applies retention. There is no capability fallback; the ordinary persistence methods retain their existing contracts.
 
+`PersistenceBackend` also requires `loadAllSessionsForRestore()`, which returns a `PersistenceRestoreRead`. Every custom backend must implement it. Startup restore calls `healthy()` and then this one method: no `listSessions`, per-session, or per-branch load. The result must come from one consistent view of storage and hold each session exactly once in ascending id order, with its history, branches (ascending by branch id), edges, and summaries. Its sessions are the same set `listSessions()` reports, including sessions that exist only through edges or summaries; with branch persistence disabled the branches are empty. Duplicate session or branch records are rejected as incompatible storage. The per-item loads remain on the interface for other callers, and restore does not fall back to them.
+
 Startup File/SQLite restore reads supported retained durable records with provenance restrictions; it doesn't restore all transient auxiliary state. It repairs retained backtrack copies without writing the snapshot, ignores an absent retained target, and rejects an ambiguous retained numeric target. TTL and capacity eviction remove live state without deleting durable records, but ordinary access doesn't reload them. Evidence pruned from durable storage by retention or deleted by explicit reset cannot be recovered. With persistence disabled, state cannot resume across restart; process-local expiration markers are also lost on restart.
 
 Branches and revisions may legally reuse thought numbers. A numeric `verification_target` must uniquely identify a retained thought identity in the same session, so avoid reusing numbers when you intend unique numeric verification references. Targets may have any thought type. Recording a verification outcome requires an explicit result of `0` or `1` and a non-retracted target with confidence.

package/dist/ServerConfig.d.ts

@@ -88,6 +88,13 @@ export interface ServerConfigOptions {
      * @default 3
      */
     persistenceMaxRetries?: number;
+    /**
+     * Maximum unacknowledged thought and backtrack writes per session, counting writes
+     * that failed terminally. At the limit new thoughts are rejected before any state changes.
+     * YAML/JSON only; no environment override.
+     * @default 10000
+     */
+    persistenceMaxPendingThoughtsPerSession?: number;
     /**
      * Feature flag overrides. Missing fields are filled with defaults (all ON,
      * reasoningStrategy='sequential').
@@ -162,6 +169,8 @@ export declare class ServerConfig {
     persistenceFlushInterval: number;
     /** Maximum number of retries for failed persistence flushes. */
     persistenceMaxRetries: number;
+    /** Maximum unacknowledged thought and backtrack writes per session. */
+    persistenceMaxPendingThoughtsPerSession: number;
     /** Feature flag toggles. */
     features: FeatureFlags;
     /** TTL in milliseconds for suspended tool-interleave entries. */
@@ -251,6 +260,13 @@ export declare class ServerConfig {
      * @private
      */
     private validatePersistenceMaxRetries;
+    /**
+     * Validates the per-session pending thought limit.
+     * @param value - The value to validate
+     * @returns The validated value or default (10000)
+     * @private
+     */
+    private validatePersistenceMaxPendingThoughts;
     /**
      * Validates feature flags and fills defaults for missing fields.
      * @param value - Partial feature flag overrides

package/dist/ServerConfig.d.ts.map

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

package/dist/ServerConfig.js

@@ -12,6 +12,7 @@ class ServerConfig {
     persistenceBufferSize;
     persistenceFlushInterval;
     persistenceMaxRetries;
+    persistenceMaxPendingThoughtsPerSession;
     features;
     toolInterleaveTtlMs;
     toolInterleaveSweepMs;
@@ -27,6 +28,7 @@ class ServerConfig {
         this.persistenceBufferSize = this.validatePersistenceBufferSize(options.persistenceBufferSize);
         this.persistenceFlushInterval = this.validatePersistenceFlushInterval(options.persistenceFlushInterval);
         this.persistenceMaxRetries = this.validatePersistenceMaxRetries(options.persistenceMaxRetries);
+        this.persistenceMaxPendingThoughtsPerSession = this.validatePersistenceMaxPendingThoughts(options.persistenceMaxPendingThoughtsPerSession);
         this.features = this.validateFeatures(options.features);
         this.toolInterleaveTtlMs = this.validatePositiveMs(options.toolInterleaveTtlMs, 60000, 'toolInterleaveTtlMs');
         this.toolInterleaveSweepMs = this.validatePositiveMs(options.toolInterleaveSweepMs, 60000, 'toolInterleaveSweepMs');
@@ -124,6 +126,14 @@ class ServerConfig {
         if (value > 10) throw new ConfigurationError(`persistenceMaxRetries must not exceed 10, got ${value}`);
         return value;
     }
+    validatePersistenceMaxPendingThoughts(value) {
+        const defaultValue = 10000;
+        if (null == value) return defaultValue;
+        if ('number' != typeof value || !Number.isFinite(value)) throw new ConfigurationError(`persistenceMaxPendingThoughtsPerSession must be a finite number, got ${value}`);
+        if (value < 1) throw new ConfigurationError(`persistenceMaxPendingThoughtsPerSession must be at least 1, got ${value}`);
+        if (value > 10000) throw new ConfigurationError(`persistenceMaxPendingThoughtsPerSession must not exceed 10000, got ${value}`);
+        return value;
+    }
     validateFeatures(value) {
         const reasoningStrategy = value?.reasoningStrategy ?? 'sequential';
         if ('sequential' !== reasoningStrategy && 'tot' !== reasoningStrategy) throw new ConfigurationError(`features.reasoningStrategy must be one of sequential, tot, got ${reasoningStrategy}`);
@@ -163,6 +173,7 @@ class ServerConfig {
             persistenceBufferSize: this.persistenceBufferSize,
             persistenceFlushInterval: this.persistenceFlushInterval,
             persistenceMaxRetries: this.persistenceMaxRetries,
+            persistenceMaxPendingThoughtsPerSession: this.persistenceMaxPendingThoughtsPerSession,
             features: this.features,
             toolInterleaveTtlMs: this.toolInterleaveTtlMs,
             toolInterleaveSweepMs: this.toolInterleaveSweepMs,

package/dist/ServerConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"ServerConfig.js","sources":["../src/ServerConfig.ts"],"sourcesContent":["/**\n * Server configuration management with validation.\n *\n * This module provides the `ServerConfig` class which handles all server configuration\n * with built-in validation and sensible defaults. Configuration values are validated\n * on construction and warnings are emitted for out-of-range values.\n *\n * @module ServerConfig\n */\n\nimport { homedir } from 'node:os';\nimport { join } from 'node:path';\nimport { ConfigurationError } from './errors.js';\nimport type { PersistenceConfig } from './contracts/PersistenceBackend.js';\n\n/**\n * Configuration options for creating a `ServerConfig` instance.\n *\n * All properties are optional with sensible defaults applied during validation.\n *\n * @example\n * ```typescript\n * const options: ServerConfigOptions = {\n *   maxHistorySize: 500,\n *   maxBranches: 25,\n *   skillDirs: ['./custom-skills'],\n *   toolDirs: ['./custom-tools'],\n *   persistence: { enabled: true, backend: 'sqlite' }\n * };\n * ```\n */\n\nimport type { FeatureFlags } from './contracts/features.js';\nexport interface ServerConfigOptions {\n\t/**\n\t * Maximum number of thoughts to keep in history.\n\t * @default 10000\n\t */\n\tmaxHistorySize?: number;\n\n\t/**\n\t * Maximum number of branches to maintain.\n\t * @default 50\n\t */\n\tmaxBranches?: number;\n\n\t/**\n\t * Maximum size of each branch.\n\t * @default 100\n\t */\n\tmaxBranchSize?: number;\n\n\t/**\n\t * Directory paths to search for skills.\n\t * @default Project .claude/skills and .agents/skills, plus both paths under the home directory\n\t */\n\tskillDirs?: string[];\n\n\t/**\n\t * Directory paths to search for tools.\n\t * @default ['.claude/tools', '~/.claude/tools']\n\t */\n\ttoolDirs?: string[];\n\n\t/**\n\t * Discovery cache configuration.\n\t */\n\tdiscoveryCache?: {\n\t\t/**\n\t\t * Time-to-live for cache entries in milliseconds.\n\t\t * @default 300000 (5 minutes)\n\t\t */\n\t\tttl?: number;\n\t\t/**\n\t\t * Maximum number of entries in the cache.\n\t\t * @default 100\n\t\t */\n\t\tmaxSize?: number;\n\t};\n\n\t/**\n\t * Persistence configuration for storing history and state.\n\t */\n\tpersistence?: PersistenceConfig;\n\n\t/**\n\t * Maximum number of thoughts to buffer before flushing to persistence.\n\t * YAML/JSON only; no environment override.\n\t * @default 100\n\t */\n\tpersistenceBufferSize?: number;\n\n\t/**\n\t * Interval in milliseconds between periodic persistence flushes.\n\t * YAML/JSON only; no environment override.\n\t * @default 1000\n\t */\n\tpersistenceFlushInterval?: number;\n\n\t/**\n\t * Maximum number of retries for failed persistence flushes.\n\t * YAML/JSON only; no environment override.\n\t * @default 3\n\t */\n\tpersistenceMaxRetries?: number;\n\n\t/**\n\t * Feature flag overrides. Missing fields are filled with defaults (all ON,\n\t * reasoningStrategy='sequential').\n\t */\n\tfeatures?: Partial<FeatureFlags>;\n\n\t/**\n\t * TTL in milliseconds for suspended tool-interleave entries in SuspensionStore.\n\t * @default 60000\n\t */\n\ttoolInterleaveTtlMs?: number;\n\n\t/**\n\t * Sweep interval in milliseconds for SuspensionStore expiration cleanup.\n\t * @default 60000\n\t */\n\ttoolInterleaveSweepMs?: number;\n\n\t/**\n\t * Maximum sessions per owner. Prevents one user from consuming all session slots.\n\t * @default 50\n\t */\n\tmaxSessionsPerOwner?: number;\n}\n\n/**\n * Server configuration with validation and defaults.\n *\n * This class manages all server configuration including history limits,\n * branch limits, discovery directories, cache settings, and persistence.\n * All values are validated on construction with appropriate defaults applied.\n *\n * @remarks\n * - Values outside recommended ranges trigger warnings but are still applied\n * - Supported environment variables override file-based configuration through ConfigLoader\n * - Logging uses file/environment input separately; ServerConfig does not hold log settings\n * - The `toJSON()` method provides a plain object representation\n *\n * @example\n * ```typescript\n * // Using defaults\n * const config1 = new ServerConfig();\n * console.log(config1.maxHistorySize); // 10000\n *\n * // With custom options\n * const config2 = new ServerConfig({\n *   maxHistorySize: 500,\n *   persistence: { enabled: true, backend: 'file', options: { dataDir: './data' } }\n * });\n *\n * // Export as plain object\n * const json = config2.toJSON();\n * ```\n */\nexport class ServerConfig {\n\t/** Maximum number of thoughts to keep in history. */\n\tpublic maxHistorySize: number;\n\n\t/** Maximum number of branches to maintain. */\n\tpublic maxBranches: number;\n\n\t/** Maximum size of each branch. */\n\tpublic maxBranchSize: number;\n\n\t/** Directory paths to search for skills. */\n\tpublic skillDirs: string[];\n\n\t/** Directory paths to search for tools. */\n\tpublic toolDirs: string[];\n\n\t/** Discovery cache configuration. */\n\tpublic discoveryCache: { ttl: number; maxSize: number };\n\n\t/** Persistence configuration. */\n\tpublic persistence: PersistenceConfig;\n\n\t/** Maximum number of thoughts to buffer before flushing to persistence. */\n\tpublic persistenceBufferSize: number;\n\n\t/** Interval in milliseconds between periodic persistence flushes. */\n\tpublic persistenceFlushInterval: number;\n\n\t/** Maximum number of retries for failed persistence flushes. */\n\tpublic persistenceMaxRetries: number;\n\n\t/** Feature flag toggles. */\n\tpublic features: FeatureFlags;\n\n\t/** TTL in milliseconds for suspended tool-interleave entries. */\n\tpublic toolInterleaveTtlMs: number;\n\n\t/** Sweep interval in milliseconds for SuspensionStore expiration cleanup. */\n\tpublic toolInterleaveSweepMs: number;\n\n\t/** Maximum sessions per owner (LRU per-owner bucket). */\n\tpublic maxSessionsPerOwner: number;\n\n\t/**\n\t * Creates a new ServerConfig instance with validation.\n\t *\n\t * All values are validated and defaults are applied for undefined options.\n\t * Warnings are emitted to console for values outside recommended ranges.\n\t *\n\t * @param options - Optional configuration overrides\n\t *\n\t * @example\n\t * ```typescript\n\t * const config = new ServerConfig({\n\t *   maxHistorySize: 500,\n\t *   skillDirs: ['./my-skills']\n\t * });\n\t * ```\n\t */\n\tconstructor(options: ServerConfigOptions = {}) {\n\t\tthis.maxHistorySize = this.validateMaxHistorySize(options.maxHistorySize);\n\t\tthis.maxBranches = this.validateMaxBranches(options.maxBranches);\n\t\tthis.maxBranchSize = this.validateMaxBranchSize(options.maxBranchSize);\n\t\tthis.skillDirs = this.validateSkillDirs(options.skillDirs);\n\t\tthis.toolDirs = this.validateToolDirs(options.toolDirs);\n\t\tthis.discoveryCache = this.validateDiscoveryCache(options.discoveryCache);\n\t\tthis.persistence = this.validatePersistence(options.persistence);\n\t\tthis.persistenceBufferSize = this.validatePersistenceBufferSize(options.persistenceBufferSize);\n\t\tthis.persistenceFlushInterval = this.validatePersistenceFlushInterval(\n\t\t\toptions.persistenceFlushInterval\n\t\t);\n\t\tthis.persistenceMaxRetries = this.validatePersistenceMaxRetries(options.persistenceMaxRetries);\n\t\tthis.features = this.validateFeatures(options.features);\n\t\tthis.toolInterleaveTtlMs = this.validatePositiveMs(\n\t\t\toptions.toolInterleaveTtlMs,\n\t\t\t60000,\n\t\t\t'toolInterleaveTtlMs'\n\t\t);\n\t\tthis.toolInterleaveSweepMs = this.validatePositiveMs(\n\t\t\toptions.toolInterleaveSweepMs,\n\t\t\t60000,\n\t\t\t'toolInterleaveSweepMs'\n\t\t);\n\t\tthis.maxSessionsPerOwner = this.validateMaxSessionsPerOwner(options.maxSessionsPerOwner);\n\t}\n\n\t/**\n\t * Validates the max history size value.\n\t * @param value - The value to validate\n\t * @returns The validated value or default (10000)\n\t * @private\n\t */\n\tprivate validateMaxHistorySize(value?: number): number {\n\t\tconst defaultValue = 10000;\n\t\tif (value === undefined || value === null) return defaultValue;\n\t\tif (typeof value !== 'number' || !Number.isFinite(value)) {\n\t\t\tthrow new ConfigurationError(`maxHistorySize must be a finite number, got ${value}`);\n\t\t}\n\t\tif (value < 1) {\n\t\t\tthrow new ConfigurationError(`maxHistorySize must be at least 1, got ${value}`);\n\t\t}\n\t\tif (value > 10000) {\n\t\t\tthrow new ConfigurationError(`maxHistorySize must not exceed 10000, got ${value}`);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Validates the max branches value.\n\t * @param value - The value to validate\n\t * @returns The validated value or default (50)\n\t * @private\n\t */\n\tprivate validateMaxBranches(value?: number): number {\n\t\tconst defaultValue = 50;\n\t\tif (value === undefined || value === null) return defaultValue;\n\t\tif (typeof value !== 'number' || !Number.isFinite(value)) {\n\t\t\tthrow new ConfigurationError(`maxBranches must be a finite number, got ${value}`);\n\t\t}\n\t\tif (value < 0) {\n\t\t\tthrow new ConfigurationError(`maxBranches must be non-negative, got ${value}`);\n\t\t}\n\t\tif (value > 1000) {\n\t\t\tthrow new ConfigurationError(`maxBranches must not exceed 1000, got ${value}`);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Validates the max branch size value.\n\t * @param value - The value to validate\n\t * @returns The validated value or default (100)\n\t * @private\n\t */\n\tprivate validateMaxBranchSize(value?: number): number {\n\t\tconst defaultValue = 100;\n\t\tif (value === undefined || value === null) return defaultValue;\n\t\tif (typeof value !== 'number' || !Number.isFinite(value)) {\n\t\t\tthrow new ConfigurationError(`maxBranchSize must be a finite number, got ${value}`);\n\t\t}\n\t\tif (value < 1) {\n\t\t\tthrow new ConfigurationError(`maxBranchSize must be at least 1, got ${value}`);\n\t\t}\n\t\tif (value > 1000) {\n\t\t\tthrow new ConfigurationError(`maxBranchSize must not exceed 1000, got ${value}`);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Validates the skill directories value.\n\t * @param value - The value to validate\n\t * @returns The validated value or project-local and home-directory .claude/.agents skill paths\n\t * @private\n\t */\n\tprivate validateSkillDirs(value?: string[]): string[] {\n\t\tconst defaultValue = [\n\t\t\t'.claude/skills',\n\t\t\tjoin(homedir(), '.claude/skills'),\n\t\t\t'.agents/skills',\n\t\t\tjoin(homedir(), '.agents/skills'),\n\t\t];\n\t\treturn value === undefined ? defaultValue : [...value];\n\t}\n\n\tprivate validateToolDirs(value?: string[]): string[] {\n\t\tconst defaultValue = ['.claude/tools', join(homedir(), '.claude/tools')];\n\t\treturn value === undefined ? defaultValue : [...value];\n\t}\n\n\t/**\n\t * Validates the discovery cache configuration.\n\t * @param value - The value to validate\n\t * @returns The validated value with defaults applied\n\t * @private\n\t */\n\tprivate validateDiscoveryCache(value?: { ttl?: number; maxSize?: number }): {\n\t\tttl: number;\n\t\tmaxSize: number;\n\t} {\n\t\treturn {\n\t\t\tttl: value?.ttl ?? 300000,\n\t\t\tmaxSize: value?.maxSize ?? 100,\n\t\t};\n\t}\n\n\t/**\n\t * Validates the persistence configuration.\n\t * @param value - The value to validate\n\t * @returns The validated value with defaults applied\n\t * @private\n\t */\n\tprivate validatePersistence(value?: PersistenceConfig): PersistenceConfig {\n\t\tif (!value) {\n\t\t\t// Default to in-memory (no actual persistence, just consistency)\n\t\t\treturn {\n\t\t\t\tenabled: false,\n\t\t\t\tbackend: 'memory',\n\t\t\t};\n\t\t}\n\n\t\t// Validate backend type\n\t\tconst validBackends = ['file', 'sqlite', 'memory'];\n\t\tconst backend = value.backend ?? 'memory';\n\t\tif (!validBackends.includes(backend)) {\n\t\t\tthrow new ConfigurationError(\n\t\t\t\t`persistence.backend must be one of ${validBackends.join(', ')}, got ${backend}`\n\t\t\t);\n\t\t}\n\n\t\treturn {\n\t\t\tenabled: value.enabled ?? false,\n\t\t\tbackend,\n\t\t\toptions: value.options ?? {},\n\t\t};\n\t}\n\n\t/**\n\t * Validates the persistence buffer size value.\n\t * @param value - The value to validate\n\t * @returns The validated value or default (100)\n\t * @private\n\t */\n\tprivate validatePersistenceBufferSize(value?: number): number {\n\t\tconst defaultValue = 100;\n\t\tif (value === undefined || value === null) return defaultValue;\n\t\tif (typeof value !== 'number' || !Number.isFinite(value)) {\n\t\t\tthrow new ConfigurationError(`persistenceBufferSize must be a finite number, got ${value}`);\n\t\t}\n\t\tif (value < 1) {\n\t\t\tthrow new ConfigurationError(`persistenceBufferSize must be at least 1, got ${value}`);\n\t\t}\n\t\tif (value > 10000) {\n\t\t\tthrow new ConfigurationError(`persistenceBufferSize must not exceed 10000, got ${value}`);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Validates the persistence flush interval value.\n\t * @param value - The value to validate\n\t * @returns The validated value or default (1000)\n\t * @private\n\t */\n\tprivate validatePersistenceFlushInterval(value?: number): number {\n\t\tconst defaultValue = 1000;\n\t\tif (value === undefined || value === null) return defaultValue;\n\t\tif (typeof value !== 'number' || !Number.isFinite(value)) {\n\t\t\tthrow new ConfigurationError(\n\t\t\t\t`persistenceFlushInterval must be a finite number, got ${value}`\n\t\t\t);\n\t\t}\n\t\tif (value < 100) {\n\t\t\tthrow new ConfigurationError(`persistenceFlushInterval must be at least 100, got ${value}`);\n\t\t}\n\t\tif (value > 60000) {\n\t\t\tthrow new ConfigurationError(`persistenceFlushInterval must not exceed 60000, got ${value}`);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Validates the persistence max retries value.\n\t * @param value - The value to validate\n\t * @returns The validated value or default (3)\n\t * @private\n\t */\n\tprivate validatePersistenceMaxRetries(value?: number): number {\n\t\tconst defaultValue = 3;\n\t\tif (value === undefined || value === null) return defaultValue;\n\t\tif (typeof value !== 'number' || !Number.isFinite(value)) {\n\t\t\tthrow new ConfigurationError(`persistenceMaxRetries must be a finite number, got ${value}`);\n\t\t}\n\t\tif (value < 0) {\n\t\t\tthrow new ConfigurationError(`persistenceMaxRetries must be non-negative, got ${value}`);\n\t\t}\n\t\tif (value > 10) {\n\t\t\tthrow new ConfigurationError(`persistenceMaxRetries must not exceed 10, got ${value}`);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Validates feature flags and fills defaults for missing fields.\n\t * @param value - Partial feature flag overrides\n\t * @returns Fully populated FeatureFlags with defaults applied\n\t * @private\n\t */\n\tprivate validateFeatures(value?: Partial<FeatureFlags>): FeatureFlags {\n\t\tconst reasoningStrategy = value?.reasoningStrategy ?? 'sequential';\n\t\tif (reasoningStrategy !== 'sequential' && reasoningStrategy !== 'tot') {\n\t\t\tthrow new ConfigurationError(\n\t\t\t\t`features.reasoningStrategy must be one of sequential, tot, got ${reasoningStrategy}`\n\t\t\t);\n\t\t}\n\t\treturn {\n\t\t\tdagEdges: value?.dagEdges ?? true,\n\t\t\treasoningStrategy,\n\t\t\tcalibration: value?.calibration ?? true,\n\t\t\tcompression: value?.compression ?? true,\n\t\t\ttoolInterleave: value?.toolInterleave ?? true,\n\t\t\tnewThoughtTypes: value?.newThoughtTypes ?? true,\n\t\t\toutcomeRecording: value?.outcomeRecording ?? true,\n\t\t};\n\t}\n\n\t/**\n\t * Validates a positive millisecond value with a default fallback.\n\t * @param value - The value to validate\n\t * @param defaultValue - Default applied if value is undefined/null\n\t * @param fieldName - Field name for error messages\n\t * @returns The validated millisecond value\n\t * @private\n\t */\n\tprivate validatePositiveMs(\n\t\tvalue: number | undefined,\n\t\tdefaultValue: number,\n\t\tfieldName: string\n\t): number {\n\t\tif (value === undefined || value === null) return defaultValue;\n\t\tif (typeof value !== 'number' || !Number.isFinite(value)) {\n\t\t\tthrow new ConfigurationError(`${fieldName} must be a finite number, got ${value}`);\n\t\t}\n\t\tif (value < 1) {\n\t\t\tthrow new ConfigurationError(`${fieldName} must be at least 1, got ${value}`);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Validates the max sessions per owner value.\n\t * @param value - The value to validate\n\t * @returns The validated value or default (50)\n\t * @private\n\t */\n\tprivate validateMaxSessionsPerOwner(value?: number): number {\n\t\tconst defaultValue = 50;\n\t\tif (value === undefined || value === null) return defaultValue;\n\t\tif (typeof value !== 'number' || !Number.isFinite(value)) {\n\t\t\tthrow new ConfigurationError(`maxSessionsPerOwner must be a finite number, got ${value}`);\n\t\t}\n\t\tif (value < 1) {\n\t\t\tthrow new ConfigurationError(`maxSessionsPerOwner must be at least 1, got ${value}`);\n\t\t}\n\t\tif (value > 10000) {\n\t\t\tthrow new ConfigurationError(`maxSessionsPerOwner must not exceed 10000, got ${value}`);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Converts the configuration to a plain object.\n\t *\n\t * Useful for serialization, logging, or when a plain object representation\n\t * is preferred over the ServerConfig instance.\n\t *\n\t * @returns A plain object representation of the configuration\n\t *\n\t * @example\n\t * ```typescript\n\t * const config = new ServerConfig({ maxHistorySize: 500 });\n\t * const json = config.toJSON();\n\t * console.log(JSON.stringify(json, null, 2));\n\t * ```\n\t */\n\tpublic toJSON(): ServerConfigOptions {\n\t\treturn {\n\t\t\tmaxHistorySize: this.maxHistorySize,\n\t\t\tmaxBranches: this.maxBranches,\n\t\t\tmaxBranchSize: this.maxBranchSize,\n\t\t\tskillDirs: this.skillDirs,\n\t\t\ttoolDirs: this.toolDirs,\n\t\t\tdiscoveryCache: this.discoveryCache,\n\t\t\tpersistence: this.persistence,\n\t\t\tpersistenceBufferSize: this.persistenceBufferSize,\n\t\t\tpersistenceFlushInterval: this.persistenceFlushInterval,\n\t\t\tpersistenceMaxRetries: this.persistenceMaxRetries,\n\t\t\tfeatures: this.features,\n\t\t\ttoolInterleaveTtlMs: this.toolInterleaveTtlMs,\n\t\t\ttoolInterleaveSweepMs: this.toolInterleaveSweepMs,\n\t\t\tmaxSessionsPerOwner: this.maxSessionsPerOwner,\n\t\t};\n\t}\n}\n"],"names":["ServerConfig","options","value","defaultValue","Number","ConfigurationError","join","homedir","undefined","validBackends","backend","reasoningStrategy","fieldName"],"mappings":"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"}
+{"version":3,"file":"ServerConfig.js","sources":["../src/ServerConfig.ts"],"sourcesContent":["/**\n * Server configuration management with validation.\n *\n * This module provides the `ServerConfig` class which handles all server configuration\n * with built-in validation and sensible defaults. Configuration values are validated\n * on construction and warnings are emitted for out-of-range values.\n *\n * @module ServerConfig\n */\n\nimport { homedir } from 'node:os';\nimport { join } from 'node:path';\nimport { ConfigurationError } from './errors.js';\nimport type { PersistenceConfig } from './contracts/PersistenceBackend.js';\n\n/**\n * Configuration options for creating a `ServerConfig` instance.\n *\n * All properties are optional with sensible defaults applied during validation.\n *\n * @example\n * ```typescript\n * const options: ServerConfigOptions = {\n *   maxHistorySize: 500,\n *   maxBranches: 25,\n *   skillDirs: ['./custom-skills'],\n *   toolDirs: ['./custom-tools'],\n *   persistence: { enabled: true, backend: 'sqlite' }\n * };\n * ```\n */\n\nimport type { FeatureFlags } from './contracts/features.js';\nexport interface ServerConfigOptions {\n\t/**\n\t * Maximum number of thoughts to keep in history.\n\t * @default 10000\n\t */\n\tmaxHistorySize?: number;\n\n\t/**\n\t * Maximum number of branches to maintain.\n\t * @default 50\n\t */\n\tmaxBranches?: number;\n\n\t/**\n\t * Maximum size of each branch.\n\t * @default 100\n\t */\n\tmaxBranchSize?: number;\n\n\t/**\n\t * Directory paths to search for skills.\n\t * @default Project .claude/skills and .agents/skills, plus both paths under the home directory\n\t */\n\tskillDirs?: string[];\n\n\t/**\n\t * Directory paths to search for tools.\n\t * @default ['.claude/tools', '~/.claude/tools']\n\t */\n\ttoolDirs?: string[];\n\n\t/**\n\t * Discovery cache configuration.\n\t */\n\tdiscoveryCache?: {\n\t\t/**\n\t\t * Time-to-live for cache entries in milliseconds.\n\t\t * @default 300000 (5 minutes)\n\t\t */\n\t\tttl?: number;\n\t\t/**\n\t\t * Maximum number of entries in the cache.\n\t\t * @default 100\n\t\t */\n\t\tmaxSize?: number;\n\t};\n\n\t/**\n\t * Persistence configuration for storing history and state.\n\t */\n\tpersistence?: PersistenceConfig;\n\n\t/**\n\t * Maximum number of thoughts to buffer before flushing to persistence.\n\t * YAML/JSON only; no environment override.\n\t * @default 100\n\t */\n\tpersistenceBufferSize?: number;\n\n\t/**\n\t * Interval in milliseconds between periodic persistence flushes.\n\t * YAML/JSON only; no environment override.\n\t * @default 1000\n\t */\n\tpersistenceFlushInterval?: number;\n\n\t/**\n\t * Maximum number of retries for failed persistence flushes.\n\t * YAML/JSON only; no environment override.\n\t * @default 3\n\t */\n\tpersistenceMaxRetries?: number;\n\n\t/**\n\t * Maximum unacknowledged thought and backtrack writes per session, counting writes\n\t * that failed terminally. At the limit new thoughts are rejected before any state changes.\n\t * YAML/JSON only; no environment override.\n\t * @default 10000\n\t */\n\tpersistenceMaxPendingThoughtsPerSession?: number;\n\n\t/**\n\t * Feature flag overrides. Missing fields are filled with defaults (all ON,\n\t * reasoningStrategy='sequential').\n\t */\n\tfeatures?: Partial<FeatureFlags>;\n\n\t/**\n\t * TTL in milliseconds for suspended tool-interleave entries in SuspensionStore.\n\t * @default 60000\n\t */\n\ttoolInterleaveTtlMs?: number;\n\n\t/**\n\t * Sweep interval in milliseconds for SuspensionStore expiration cleanup.\n\t * @default 60000\n\t */\n\ttoolInterleaveSweepMs?: number;\n\n\t/**\n\t * Maximum sessions per owner. Prevents one user from consuming all session slots.\n\t * @default 50\n\t */\n\tmaxSessionsPerOwner?: number;\n}\n\n/**\n * Server configuration with validation and defaults.\n *\n * This class manages all server configuration including history limits,\n * branch limits, discovery directories, cache settings, and persistence.\n * All values are validated on construction with appropriate defaults applied.\n *\n * @remarks\n * - Values outside recommended ranges trigger warnings but are still applied\n * - Supported environment variables override file-based configuration through ConfigLoader\n * - Logging uses file/environment input separately; ServerConfig does not hold log settings\n * - The `toJSON()` method provides a plain object representation\n *\n * @example\n * ```typescript\n * // Using defaults\n * const config1 = new ServerConfig();\n * console.log(config1.maxHistorySize); // 10000\n *\n * // With custom options\n * const config2 = new ServerConfig({\n *   maxHistorySize: 500,\n *   persistence: { enabled: true, backend: 'file', options: { dataDir: './data' } }\n * });\n *\n * // Export as plain object\n * const json = config2.toJSON();\n * ```\n */\nexport class ServerConfig {\n\t/** Maximum number of thoughts to keep in history. */\n\tpublic maxHistorySize: number;\n\n\t/** Maximum number of branches to maintain. */\n\tpublic maxBranches: number;\n\n\t/** Maximum size of each branch. */\n\tpublic maxBranchSize: number;\n\n\t/** Directory paths to search for skills. */\n\tpublic skillDirs: string[];\n\n\t/** Directory paths to search for tools. */\n\tpublic toolDirs: string[];\n\n\t/** Discovery cache configuration. */\n\tpublic discoveryCache: { ttl: number; maxSize: number };\n\n\t/** Persistence configuration. */\n\tpublic persistence: PersistenceConfig;\n\n\t/** Maximum number of thoughts to buffer before flushing to persistence. */\n\tpublic persistenceBufferSize: number;\n\n\t/** Interval in milliseconds between periodic persistence flushes. */\n\tpublic persistenceFlushInterval: number;\n\n\t/** Maximum number of retries for failed persistence flushes. */\n\tpublic persistenceMaxRetries: number;\n\n\t/** Maximum unacknowledged thought and backtrack writes per session. */\n\tpublic persistenceMaxPendingThoughtsPerSession: number;\n\n\t/** Feature flag toggles. */\n\tpublic features: FeatureFlags;\n\n\t/** TTL in milliseconds for suspended tool-interleave entries. */\n\tpublic toolInterleaveTtlMs: number;\n\n\t/** Sweep interval in milliseconds for SuspensionStore expiration cleanup. */\n\tpublic toolInterleaveSweepMs: number;\n\n\t/** Maximum sessions per owner (LRU per-owner bucket). */\n\tpublic maxSessionsPerOwner: number;\n\n\t/**\n\t * Creates a new ServerConfig instance with validation.\n\t *\n\t * All values are validated and defaults are applied for undefined options.\n\t * Warnings are emitted to console for values outside recommended ranges.\n\t *\n\t * @param options - Optional configuration overrides\n\t *\n\t * @example\n\t * ```typescript\n\t * const config = new ServerConfig({\n\t *   maxHistorySize: 500,\n\t *   skillDirs: ['./my-skills']\n\t * });\n\t * ```\n\t */\n\tconstructor(options: ServerConfigOptions = {}) {\n\t\tthis.maxHistorySize = this.validateMaxHistorySize(options.maxHistorySize);\n\t\tthis.maxBranches = this.validateMaxBranches(options.maxBranches);\n\t\tthis.maxBranchSize = this.validateMaxBranchSize(options.maxBranchSize);\n\t\tthis.skillDirs = this.validateSkillDirs(options.skillDirs);\n\t\tthis.toolDirs = this.validateToolDirs(options.toolDirs);\n\t\tthis.discoveryCache = this.validateDiscoveryCache(options.discoveryCache);\n\t\tthis.persistence = this.validatePersistence(options.persistence);\n\t\tthis.persistenceBufferSize = this.validatePersistenceBufferSize(options.persistenceBufferSize);\n\t\tthis.persistenceFlushInterval = this.validatePersistenceFlushInterval(\n\t\t\toptions.persistenceFlushInterval\n\t\t);\n\t\tthis.persistenceMaxRetries = this.validatePersistenceMaxRetries(options.persistenceMaxRetries);\n\t\tthis.persistenceMaxPendingThoughtsPerSession = this.validatePersistenceMaxPendingThoughts(\n\t\t\toptions.persistenceMaxPendingThoughtsPerSession\n\t\t);\n\t\tthis.features = this.validateFeatures(options.features);\n\t\tthis.toolInterleaveTtlMs = this.validatePositiveMs(\n\t\t\toptions.toolInterleaveTtlMs,\n\t\t\t60000,\n\t\t\t'toolInterleaveTtlMs'\n\t\t);\n\t\tthis.toolInterleaveSweepMs = this.validatePositiveMs(\n\t\t\toptions.toolInterleaveSweepMs,\n\t\t\t60000,\n\t\t\t'toolInterleaveSweepMs'\n\t\t);\n\t\tthis.maxSessionsPerOwner = this.validateMaxSessionsPerOwner(options.maxSessionsPerOwner);\n\t}\n\n\t/**\n\t * Validates the max history size value.\n\t * @param value - The value to validate\n\t * @returns The validated value or default (10000)\n\t * @private\n\t */\n\tprivate validateMaxHistorySize(value?: number): number {\n\t\tconst defaultValue = 10000;\n\t\tif (value === undefined || value === null) return defaultValue;\n\t\tif (typeof value !== 'number' || !Number.isFinite(value)) {\n\t\t\tthrow new ConfigurationError(`maxHistorySize must be a finite number, got ${value}`);\n\t\t}\n\t\tif (value < 1) {\n\t\t\tthrow new ConfigurationError(`maxHistorySize must be at least 1, got ${value}`);\n\t\t}\n\t\tif (value > 10000) {\n\t\t\tthrow new ConfigurationError(`maxHistorySize must not exceed 10000, got ${value}`);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Validates the max branches value.\n\t * @param value - The value to validate\n\t * @returns The validated value or default (50)\n\t * @private\n\t */\n\tprivate validateMaxBranches(value?: number): number {\n\t\tconst defaultValue = 50;\n\t\tif (value === undefined || value === null) return defaultValue;\n\t\tif (typeof value !== 'number' || !Number.isFinite(value)) {\n\t\t\tthrow new ConfigurationError(`maxBranches must be a finite number, got ${value}`);\n\t\t}\n\t\tif (value < 0) {\n\t\t\tthrow new ConfigurationError(`maxBranches must be non-negative, got ${value}`);\n\t\t}\n\t\tif (value > 1000) {\n\t\t\tthrow new ConfigurationError(`maxBranches must not exceed 1000, got ${value}`);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Validates the max branch size value.\n\t * @param value - The value to validate\n\t * @returns The validated value or default (100)\n\t * @private\n\t */\n\tprivate validateMaxBranchSize(value?: number): number {\n\t\tconst defaultValue = 100;\n\t\tif (value === undefined || value === null) return defaultValue;\n\t\tif (typeof value !== 'number' || !Number.isFinite(value)) {\n\t\t\tthrow new ConfigurationError(`maxBranchSize must be a finite number, got ${value}`);\n\t\t}\n\t\tif (value < 1) {\n\t\t\tthrow new ConfigurationError(`maxBranchSize must be at least 1, got ${value}`);\n\t\t}\n\t\tif (value > 1000) {\n\t\t\tthrow new ConfigurationError(`maxBranchSize must not exceed 1000, got ${value}`);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Validates the skill directories value.\n\t * @param value - The value to validate\n\t * @returns The validated value or project-local and home-directory .claude/.agents skill paths\n\t * @private\n\t */\n\tprivate validateSkillDirs(value?: string[]): string[] {\n\t\tconst defaultValue = [\n\t\t\t'.claude/skills',\n\t\t\tjoin(homedir(), '.claude/skills'),\n\t\t\t'.agents/skills',\n\t\t\tjoin(homedir(), '.agents/skills'),\n\t\t];\n\t\treturn value === undefined ? defaultValue : [...value];\n\t}\n\n\tprivate validateToolDirs(value?: string[]): string[] {\n\t\tconst defaultValue = ['.claude/tools', join(homedir(), '.claude/tools')];\n\t\treturn value === undefined ? defaultValue : [...value];\n\t}\n\n\t/**\n\t * Validates the discovery cache configuration.\n\t * @param value - The value to validate\n\t * @returns The validated value with defaults applied\n\t * @private\n\t */\n\tprivate validateDiscoveryCache(value?: { ttl?: number; maxSize?: number }): {\n\t\tttl: number;\n\t\tmaxSize: number;\n\t} {\n\t\treturn {\n\t\t\tttl: value?.ttl ?? 300000,\n\t\t\tmaxSize: value?.maxSize ?? 100,\n\t\t};\n\t}\n\n\t/**\n\t * Validates the persistence configuration.\n\t * @param value - The value to validate\n\t * @returns The validated value with defaults applied\n\t * @private\n\t */\n\tprivate validatePersistence(value?: PersistenceConfig): PersistenceConfig {\n\t\tif (!value) {\n\t\t\t// Default to in-memory (no actual persistence, just consistency)\n\t\t\treturn {\n\t\t\t\tenabled: false,\n\t\t\t\tbackend: 'memory',\n\t\t\t};\n\t\t}\n\n\t\t// Validate backend type\n\t\tconst validBackends = ['file', 'sqlite', 'memory'];\n\t\tconst backend = value.backend ?? 'memory';\n\t\tif (!validBackends.includes(backend)) {\n\t\t\tthrow new ConfigurationError(\n\t\t\t\t`persistence.backend must be one of ${validBackends.join(', ')}, got ${backend}`\n\t\t\t);\n\t\t}\n\n\t\treturn {\n\t\t\tenabled: value.enabled ?? false,\n\t\t\tbackend,\n\t\t\toptions: value.options ?? {},\n\t\t};\n\t}\n\n\t/**\n\t * Validates the persistence buffer size value.\n\t * @param value - The value to validate\n\t * @returns The validated value or default (100)\n\t * @private\n\t */\n\tprivate validatePersistenceBufferSize(value?: number): number {\n\t\tconst defaultValue = 100;\n\t\tif (value === undefined || value === null) return defaultValue;\n\t\tif (typeof value !== 'number' || !Number.isFinite(value)) {\n\t\t\tthrow new ConfigurationError(`persistenceBufferSize must be a finite number, got ${value}`);\n\t\t}\n\t\tif (value < 1) {\n\t\t\tthrow new ConfigurationError(`persistenceBufferSize must be at least 1, got ${value}`);\n\t\t}\n\t\tif (value > 10000) {\n\t\t\tthrow new ConfigurationError(`persistenceBufferSize must not exceed 10000, got ${value}`);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Validates the persistence flush interval value.\n\t * @param value - The value to validate\n\t * @returns The validated value or default (1000)\n\t * @private\n\t */\n\tprivate validatePersistenceFlushInterval(value?: number): number {\n\t\tconst defaultValue = 1000;\n\t\tif (value === undefined || value === null) return defaultValue;\n\t\tif (typeof value !== 'number' || !Number.isFinite(value)) {\n\t\t\tthrow new ConfigurationError(\n\t\t\t\t`persistenceFlushInterval must be a finite number, got ${value}`\n\t\t\t);\n\t\t}\n\t\tif (value < 100) {\n\t\t\tthrow new ConfigurationError(`persistenceFlushInterval must be at least 100, got ${value}`);\n\t\t}\n\t\tif (value > 60000) {\n\t\t\tthrow new ConfigurationError(`persistenceFlushInterval must not exceed 60000, got ${value}`);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Validates the persistence max retries value.\n\t * @param value - The value to validate\n\t * @returns The validated value or default (3)\n\t * @private\n\t */\n\tprivate validatePersistenceMaxRetries(value?: number): number {\n\t\tconst defaultValue = 3;\n\t\tif (value === undefined || value === null) return defaultValue;\n\t\tif (typeof value !== 'number' || !Number.isFinite(value)) {\n\t\t\tthrow new ConfigurationError(`persistenceMaxRetries must be a finite number, got ${value}`);\n\t\t}\n\t\tif (value < 0) {\n\t\t\tthrow new ConfigurationError(`persistenceMaxRetries must be non-negative, got ${value}`);\n\t\t}\n\t\tif (value > 10) {\n\t\t\tthrow new ConfigurationError(`persistenceMaxRetries must not exceed 10, got ${value}`);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Validates the per-session pending thought limit.\n\t * @param value - The value to validate\n\t * @returns The validated value or default (10000)\n\t * @private\n\t */\n\tprivate validatePersistenceMaxPendingThoughts(value?: number): number {\n\t\tconst defaultValue = 10000;\n\t\tif (value === undefined || value === null) return defaultValue;\n\t\tif (typeof value !== 'number' || !Number.isFinite(value)) {\n\t\t\tthrow new ConfigurationError(\n\t\t\t\t`persistenceMaxPendingThoughtsPerSession must be a finite number, got ${value}`\n\t\t\t);\n\t\t}\n\t\tif (value < 1) {\n\t\t\tthrow new ConfigurationError(\n\t\t\t\t`persistenceMaxPendingThoughtsPerSession must be at least 1, got ${value}`\n\t\t\t);\n\t\t}\n\t\tif (value > 10000) {\n\t\t\tthrow new ConfigurationError(\n\t\t\t\t`persistenceMaxPendingThoughtsPerSession must not exceed 10000, got ${value}`\n\t\t\t);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Validates feature flags and fills defaults for missing fields.\n\t * @param value - Partial feature flag overrides\n\t * @returns Fully populated FeatureFlags with defaults applied\n\t * @private\n\t */\n\tprivate validateFeatures(value?: Partial<FeatureFlags>): FeatureFlags {\n\t\tconst reasoningStrategy = value?.reasoningStrategy ?? 'sequential';\n\t\tif (reasoningStrategy !== 'sequential' && reasoningStrategy !== 'tot') {\n\t\t\tthrow new ConfigurationError(\n\t\t\t\t`features.reasoningStrategy must be one of sequential, tot, got ${reasoningStrategy}`\n\t\t\t);\n\t\t}\n\t\treturn {\n\t\t\tdagEdges: value?.dagEdges ?? true,\n\t\t\treasoningStrategy,\n\t\t\tcalibration: value?.calibration ?? true,\n\t\t\tcompression: value?.compression ?? true,\n\t\t\ttoolInterleave: value?.toolInterleave ?? true,\n\t\t\tnewThoughtTypes: value?.newThoughtTypes ?? true,\n\t\t\toutcomeRecording: value?.outcomeRecording ?? true,\n\t\t};\n\t}\n\n\t/**\n\t * Validates a positive millisecond value with a default fallback.\n\t * @param value - The value to validate\n\t * @param defaultValue - Default applied if value is undefined/null\n\t * @param fieldName - Field name for error messages\n\t * @returns The validated millisecond value\n\t * @private\n\t */\n\tprivate validatePositiveMs(\n\t\tvalue: number | undefined,\n\t\tdefaultValue: number,\n\t\tfieldName: string\n\t): number {\n\t\tif (value === undefined || value === null) return defaultValue;\n\t\tif (typeof value !== 'number' || !Number.isFinite(value)) {\n\t\t\tthrow new ConfigurationError(`${fieldName} must be a finite number, got ${value}`);\n\t\t}\n\t\tif (value < 1) {\n\t\t\tthrow new ConfigurationError(`${fieldName} must be at least 1, got ${value}`);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Validates the max sessions per owner value.\n\t * @param value - The value to validate\n\t * @returns The validated value or default (50)\n\t * @private\n\t */\n\tprivate validateMaxSessionsPerOwner(value?: number): number {\n\t\tconst defaultValue = 50;\n\t\tif (value === undefined || value === null) return defaultValue;\n\t\tif (typeof value !== 'number' || !Number.isFinite(value)) {\n\t\t\tthrow new ConfigurationError(`maxSessionsPerOwner must be a finite number, got ${value}`);\n\t\t}\n\t\tif (value < 1) {\n\t\t\tthrow new ConfigurationError(`maxSessionsPerOwner must be at least 1, got ${value}`);\n\t\t}\n\t\tif (value > 10000) {\n\t\t\tthrow new ConfigurationError(`maxSessionsPerOwner must not exceed 10000, got ${value}`);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Converts the configuration to a plain object.\n\t *\n\t * Useful for serialization, logging, or when a plain object representation\n\t * is preferred over the ServerConfig instance.\n\t *\n\t * @returns A plain object representation of the configuration\n\t *\n\t * @example\n\t * ```typescript\n\t * const config = new ServerConfig({ maxHistorySize: 500 });\n\t * const json = config.toJSON();\n\t * console.log(JSON.stringify(json, null, 2));\n\t * ```\n\t */\n\tpublic toJSON(): ServerConfigOptions {\n\t\treturn {\n\t\t\tmaxHistorySize: this.maxHistorySize,\n\t\t\tmaxBranches: this.maxBranches,\n\t\t\tmaxBranchSize: this.maxBranchSize,\n\t\t\tskillDirs: this.skillDirs,\n\t\t\ttoolDirs: this.toolDirs,\n\t\t\tdiscoveryCache: this.discoveryCache,\n\t\t\tpersistence: this.persistence,\n\t\t\tpersistenceBufferSize: this.persistenceBufferSize,\n\t\t\tpersistenceFlushInterval: this.persistenceFlushInterval,\n\t\t\tpersistenceMaxRetries: this.persistenceMaxRetries,\n\t\t\tpersistenceMaxPendingThoughtsPerSession: this.persistenceMaxPendingThoughtsPerSession,\n\t\t\tfeatures: this.features,\n\t\t\ttoolInterleaveTtlMs: this.toolInterleaveTtlMs,\n\t\t\ttoolInterleaveSweepMs: this.toolInterleaveSweepMs,\n\t\t\tmaxSessionsPerOwner: this.maxSessionsPerOwner,\n\t\t};\n\t}\n}\n"],"names":["ServerConfig","options","value","defaultValue","Number","ConfigurationError","join","homedir","undefined","validBackends","backend","reasoningStrategy","fieldName"],"mappings":"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"}

package/dist/cli.js

@@ -136,7 +136,8 @@ __webpack_require__.d(__webpack_exports__, {
     PERSISTENCE_SESSION_BARRIER_REENTRANCY: 'PERSISTENCE_SESSION_BARRIER_REENTRANCY',
     PERSISTENCE_SCOPE_MISMATCH: 'PERSISTENCE_SCOPE_MISMATCH',
     PERSISTENCE_UNAVAILABLE: 'PERSISTENCE_UNAVAILABLE',
-    PERSISTENCE_COMPATIBILITY: 'PERSISTENCE_COMPATIBILITY'
+    PERSISTENCE_COMPATIBILITY: 'PERSISTENCE_COMPATIBILITY',
+    PERSISTENCE_BACKLOG_FULL: 'PERSISTENCE_BACKLOG_FULL'
 };
 /**
  * All known warning codes as a const object.
@@ -2209,6 +2210,34 @@ function parseSessionRetentionOptions(options) {
             this._metrics?.histogram('streamable_http_request_duration_seconds', durationSeconds, {});
         });
     }
+    /**
+	 * Validate the request origin and attach CORS headers.
+	 *
+	 * @returns false when the origin is rejected and the 403 has been sent
+	 */ _admitCors(req, res) {
+        if (!this.validateCorsOrigin(req)) {
+            this._sendJsonRpcError(res, 403, -32000, 'Forbidden - invalid origin');
+            return false;
+        }
+        this.setCorsHeaders(res);
+        return true;
+    }
+    _isProbeRoute(req, urlPath) {
+        return req.method === 'GET' && (urlPath === '/health' || urlPath === '/ready');
+    }
+    /**
+	 * Serve GET /health and GET /ready. These run after Host validation and the shutdown check
+	 * but ahead of the rate limiter; they keep CORS origin validation and headers.
+	 */ async _serveProbe(req, res, urlPath) {
+        if (!this._admitCors(req, res)) {
+            return;
+        }
+        if (urlPath === '/health') {
+            this._handleHealthCheck(res);
+        } else {
+            await this._handleReadinessCheck(res);
+        }
+    }
     /**
 	 * Route and handle incoming HTTP requests.
 	 */ async _handleRequest(req, res) {
@@ -2223,6 +2252,13 @@ function parseSessionRetentionOptions(options) {
             this._sendJsonRpcError(res, 503, -32603, 'Server is shutting down');
             return;
         }
+        // Parse URL path
+        const urlPath = req.url?.split('?')[0] ?? '/';
+        // Probes (/health, /ready) precede rate limiting so polling never spends the client budget
+        if (this._isProbeRoute(req, urlPath)) {
+            await this._serveProbe(req, res, urlPath);
+            return;
+        }
         // Rate limiting
         const clientIp = this.getClientIp(req);
         if (this.checkRateLimit(clientIp)) {
@@ -2231,11 +2267,9 @@ function parseSessionRetentionOptions(options) {
             return;
         }
         // CORS validation
-        if (!this.validateCorsOrigin(req)) {
-            this._sendJsonRpcError(res, 403, -32000, 'Forbidden - invalid origin');
+        if (!this._admitCors(req, res)) {
             return;
         }
-        this.setCorsHeaders(res);
         // CORS preflight
         if (req.method === 'OPTIONS') {
             res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id');
@@ -2243,23 +2277,11 @@ function parseSessionRetentionOptions(options) {
             res.end();
             return;
         }
-        // Parse URL path
-        const urlPath = req.url?.split('?')[0] ?? '/';
         // Metrics endpoint
         if (req.method === 'GET' && urlPath === '/metrics') {
             this._handleMetrics(res);
             return;
         }
-        // Health check (liveness)
-        if (req.method === 'GET' && urlPath === '/health') {
-            this._handleHealthCheck(res);
-            return;
-        }
-        // Readiness check
-        if (req.method === 'GET' && urlPath === '/ready') {
-            await this._handleReadinessCheck(res);
-            return;
-        }
         // MCP endpoint routing
         if (urlPath === this._path) {
             if (req.method === 'POST') {
@@ -3159,6 +3181,191 @@ var RequestContext = __webpack_require__("i");
     }
 }
 
+;// CONCATENATED MODULE: ./src/health/HealthChecker.ts
+/**
+ * Aggregate health checking system.
+ *
+ * Provides liveness and readiness checks by aggregating the health
+ * status of registered backend components (persistence, pool, etc.).
+ *
+ * @module health
+ */ 
+const DEFAULT_PROBE_TIMEOUT_MS = 1000;
+function describeBacklog(view) {
+    const counts = `quarantined sessions: ${view.quarantinedSessionCount}, ` + `retained failures: ${view.retainedFailureCount}, ` + `pending thoughts: ${view.pendingThoughtCount}`;
+    return view.globalQuarantined ? `Persistence is globally quarantined; ${counts}` : counts;
+}
+/**
+ * No-op logger used when none is provided.
+ */ class NoopLogger {
+    info() {}
+    warn() {}
+    error() {}
+    debug() {}
+}
+/**
+ * Aggregates component health into liveness and readiness checks.
+ *
+ * - `checkLiveness()` always returns 'ok' if the process is running.
+ * - `checkReadiness()` checks all registered backends and returns an aggregate status.
+ *
+ * @example
+ * ```typescript
+ * const checker = new HealthChecker({ persistence: myBackend });
+ * const readiness = await checker.checkReadiness();
+ * // { status: 'ok', timestamp: '...', components: { persistence: { ... } } }
+ * ```
+ */ class HealthChecker {
+    _persistence;
+    _backlog;
+    _logger;
+    _probeTimeoutMs;
+    _probeFreshnessMs;
+    /** Verdict of the backend probe that has not settled yet, shared by every caller. */ _inFlight = null;
+    _settled = null;
+    constructor(options = {}){
+        this._persistence = options.persistence ?? null;
+        this._backlog = options.persistenceBacklog ?? null;
+        this._logger = options.logger ?? new NoopLogger();
+        this._probeTimeoutMs = options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+        this._probeFreshnessMs = options.probeFreshnessMs ?? 0;
+    }
+    /**
+	 * Liveness check — returns 'ok' if the process is alive.
+	 *
+	 * This is a synchronous check that always succeeds; if this code
+	 * can execute, the process is alive.
+	 */ checkLiveness() {
+        return {
+            status: 'ok',
+            timestamp: new Date().toISOString(),
+            components: {}
+        };
+    }
+    /**
+	 * Readiness check — aggregates health of all registered backends.
+	 *
+	 * Checks each component and returns:
+	 * - 'ok' if all components are healthy (or no components registered)
+	 * - 'degraded' if some components are unhealthy
+	 * - 'unhealthy' if all components are unhealthy
+	 *
+	 * The persistence probe is bounded by `probeTimeoutMs`, shared between concurrent calls, and
+	 * reused for `probeFreshnessMs` after it settles. The backlog component is read on every call.
+	 */ async checkReadiness() {
+        const components = {};
+        if (this._persistence) {
+            components['persistence'] = {
+                ...await this._checkPersistence()
+            };
+        }
+        const backlog = this._checkBacklog();
+        if (backlog) {
+            components['persistenceBacklog'] = backlog;
+        }
+        const totalCount = Object.keys(components).length;
+        const healthyCount = Object.values(components).filter((component)=>component.healthy).length;
+        // Determine aggregate status
+        let status;
+        if (totalCount === 0 || healthyCount === totalCount) {
+            status = 'ok';
+        } else if (healthyCount === 0) {
+            status = 'unhealthy';
+        } else {
+            status = 'degraded';
+        }
+        const result = {
+            status,
+            timestamp: new Date().toISOString(),
+            components
+        };
+        if (status !== 'ok') {
+            this._logger.warn('Readiness check returned non-ok status', {
+                status,
+                components
+            });
+        }
+        return result;
+    }
+    /**
+	 * Persistence component from the freshest source available: a settled result still inside
+	 * the freshness window, else the probe already running (even past its deadline), else a new
+	 * probe.
+	 */ async _checkPersistence() {
+        const settled = this._settled;
+        if (settled !== null && Date.now() - settled.settledAt < this._probeFreshnessMs) {
+            return settled.component;
+        }
+        this._inFlight ??= this._startProbe();
+        return this._inFlight;
+    }
+    /**
+	 * Start one backend probe. The backend call is never abandoned: it stays tracked until it
+	 * settles, while the returned verdict resolves at that point or at the deadline, whichever
+	 * comes first.
+	 */ _startProbe() {
+        const settled = this._probeBackend().then((component)=>{
+            this._inFlight = null;
+            this._settled = {
+                component,
+                settledAt: Date.now()
+            };
+            return component;
+        });
+        return new Promise((resolve)=>{
+            const timer = setTimeout(()=>{
+                resolve({
+                    name: 'persistence',
+                    healthy: false,
+                    latencyMs: this._probeTimeoutMs,
+                    details: `Health check timed out after ${this._probeTimeoutMs}ms`
+                });
+            }, this._probeTimeoutMs);
+            timer.unref();
+            void settled.then((component)=>{
+                clearTimeout(timer);
+                resolve(component);
+            });
+        });
+    }
+    _checkBacklog() {
+        const view = this._backlog?.getPersistenceBacklogView() ?? null;
+        if (view === null) {
+            return null;
+        }
+        return {
+            name: 'persistenceBacklog',
+            healthy: !view.globalQuarantined,
+            details: describeBacklog(view)
+        };
+    }
+    /**
+	 * Probe the persistence backend with latency measurement. Never rejects: every failure,
+	 * including a rejection that arrives after the deadline, becomes an unhealthy component.
+	 */ async _probeBackend() {
+        const start = Date.now();
+        try {
+            const healthy = await this._persistence.healthy();
+            return {
+                name: 'persistence',
+                healthy,
+                latencyMs: Date.now() - start,
+                details: healthy ? 'Backend is responsive' : 'Backend reported unhealthy'
+            };
+        } catch (error) {
+            this._logger.error('Persistence health check failed', {
+                error: (0,errors/* .getErrorMessage */.u1)(error)
+            });
+            return {
+                name: 'persistence',
+                healthy: false,
+                latencyMs: Date.now() - start,
+                details: `Health check error: ${(0,errors/* .getErrorMessage */.u1)(error)}`
+            };
+        }
+    }
+}
+
 // EXTERNAL MODULE: ./src/schema.ts
 var schema = __webpack_require__("R");
 ;// CONCATENATED MODULE: ./src/cli.ts
@@ -3178,12 +3385,15 @@ var schema = __webpack_require__("R");
 
 
 
+
 // Get version from package.json
 const CLI_NAME = 'tracelattice';
 const cli_filename = (0,__rspack_external_node_url_3991086a.fileURLToPath)(import.meta.url);
 const cli_dirname = (0,__rspack_external_node_path_806ed179.dirname)(cli_filename);
 const package_json = JSON.parse((0,__rspack_external_node_fs_1b05aee1.readFileSync)((0,__rspack_external_node_path_806ed179.join)(cli_dirname, '../package.json'), 'utf-8'));
 const { version } = package_json;
+// Orchestrators poll /ready often; one settled probe serves every poll inside this window.
+const READINESS_PROBE_FRESHNESS_MS = 1000;
 // Handle CLI arguments
 const args = process.argv.slice(2);
 const shouldShowVersion = args.includes('--version') || args.includes('-v');
@@ -3233,14 +3443,20 @@ async function main() {
     const { StreamableHttpTransport } = await Promise.resolve(/* import() */).then(__webpack_require__.bind(__webpack_require__, "q"));
     const { lifecycle, config } = options;
     const { port, host } = config;
-    const transportMetrics = thinkingServer.getContainer().resolve('Metrics');
+    const container = thinkingServer.getContainer();
+    const healthChecker = new HealthChecker({
+        persistence: container.resolve('Persistence'),
+        persistenceBacklog: container.resolve('HistoryManager'),
+        probeFreshnessMs: READINESS_PROBE_FRESHNESS_MS
+    });
     const streamableTransport = new StreamableHttpTransport({
         port,
         host,
         corsOrigin: config.corsOrigin,
         enableCors: config.enableCors,
         allowedHosts: config.allowedHosts,
-        metrics: transportMetrics,
+        metrics: container.resolve('Metrics'),
+        healthChecker,
         stateful: config.stateful,
         ...config.retention
     });