tracelattice 1.2.5

package/dist/context/RequestContext.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Request context management using AsyncLocalStorage for correlation IDs.
+ *
+ * This module provides a way to track request IDs across async operations
+ * without explicit parameter passing. Uses Node.js AsyncLocalStorage for
+ * zero-cost context propagation.
+ *
+ * @module context
+ */
+/**
+ * Run a function within a request context.
+ *
+ * The requestId will be available via getRequestId() inside the callback
+ * and any async operations it spawns.
+ *
+ * @param requestId - The correlation ID for this request
+ * @param fn - The function to run within the context
+ * @returns The return value of fn
+ *
+ * @example
+ * ```typescript
+ * await runWithContext('req-123', async () => {
+ *   console.log(getRequestId()); // 'req-123'
+ *   await someAsyncOperation();
+ *   console.log(getRequestId()); // still 'req-123'
+ * });
+ * ```
+ */
+export declare function runWithContext<T>(requestId: string, fn: () => T | Promise<T>): T | Promise<T>;
+/**
+ * Get the current request ID from context.
+ *
+ * Returns undefined if called outside of a runWithContext() call.
+ *
+ * @returns The current request ID or undefined
+ *
+ * @example
+ * ```typescript
+ * // Outside context
+ * getRequestId(); // undefined
+ *
+ * // Inside context
+ * runWithContext('abc', () => {
+ *   getRequestId(); // 'abc'
+ * });
+ * ```
+ */
+export declare function getRequestId(): string | undefined;
+/**
+ * Generate a new unique request ID using UUID v4.
+ *
+ * @returns A UUID string in standard format
+ *
+ * @example
+ * ```typescript
+ * const id = generateRequestId();
+ * // '550e8400-e29b-41d4-a716-446655440000'
+ * ```
+ */
+export declare function generateRequestId(): string;
+//# sourceMappingURL=RequestContext.d.ts.map

package/dist/context/RequestContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestContext.d.ts","sourceRoot":"","sources":["../../src/context/RequestContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkBH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAE7F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,SAAS,CAEjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}

package/dist/context/RequestContext.js

@@ -0,0 +1,17 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+const store = new AsyncLocalStorage();
+function runWithContext(requestId, fn) {
+    return store.run({
+        requestId
+    }, fn);
+}
+function getRequestId() {
+    return store.getStore()?.requestId;
+}
+function generateRequestId() {
+    return randomUUID();
+}
+export { generateRequestId, getRequestId, runWithContext };
+
+//# sourceMappingURL=RequestContext.js.map

package/dist/context/RequestContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context/RequestContext.js","sources":["../../src/context/RequestContext.ts"],"sourcesContent":["/**\n * Request context management using AsyncLocalStorage for correlation IDs.\n *\n * This module provides a way to track request IDs across async operations\n * without explicit parameter passing. Uses Node.js AsyncLocalStorage for\n * zero-cost context propagation.\n *\n * @module context\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport { randomUUID } from 'node:crypto';\n\n/**\n * Internal context structure stored per-request.\n */\ninterface RequestCtx {\n\trequestId: string;\n}\n\n/**\n * AsyncLocalStorage instance for request context.\n * Stores requestId that propagates across async boundaries.\n */\nconst store = new AsyncLocalStorage<RequestCtx>();\n\n/**\n * Run a function within a request context.\n *\n * The requestId will be available via getRequestId() inside the callback\n * and any async operations it spawns.\n *\n * @param requestId - The correlation ID for this request\n * @param fn - The function to run within the context\n * @returns The return value of fn\n *\n * @example\n * ```typescript\n * await runWithContext('req-123', async () => {\n *   console.log(getRequestId()); // 'req-123'\n *   await someAsyncOperation();\n *   console.log(getRequestId()); // still 'req-123'\n * });\n * ```\n */\nexport function runWithContext<T>(requestId: string, fn: () => T | Promise<T>): T | Promise<T> {\n\treturn store.run({ requestId }, fn);\n}\n\n/**\n * Get the current request ID from context.\n *\n * Returns undefined if called outside of a runWithContext() call.\n *\n * @returns The current request ID or undefined\n *\n * @example\n * ```typescript\n * // Outside context\n * getRequestId(); // undefined\n *\n * // Inside context\n * runWithContext('abc', () => {\n *   getRequestId(); // 'abc'\n * });\n * ```\n */\nexport function getRequestId(): string | undefined {\n\treturn store.getStore()?.requestId;\n}\n\n/**\n * Generate a new unique request ID using UUID v4.\n *\n * @returns A UUID string in standard format\n *\n * @example\n * ```typescript\n * const id = generateRequestId();\n * // '550e8400-e29b-41d4-a716-446655440000'\n * ```\n */\nexport function generateRequestId(): string {\n\treturn randomUUID();\n}\n"],"names":["store","AsyncLocalStorage","runWithContext","requestId","fn","getRequestId","generateRequestId","randomUUID"],"mappings":";;AAwBA,MAAMA,QAAQ,IAAIC;AAqBX,SAASC,eAAkBC,SAAiB,EAAEC,EAAwB;IAC5E,OAAOJ,MAAM,GAAG,CAAC;QAAEG;IAAU,GAAGC;AACjC;AAoBO,SAASC;IACf,OAAOL,MAAM,QAAQ,IAAI;AAC1B;AAaO,SAASM;IACf,OAAOC;AACR"}

package/dist/contracts/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Contracts module — shared interface definitions for DI and cross-module dependencies.
+ *
+ * All modules that need to reference other modules' interfaces should import
+ * from here instead of directly from the implementation module.
+ *
+ * @module contracts
+ */
+export { type DiscoveryCacheOptions, type IDiscoveryCache, type IMetrics, type IServerConfig, type ISkillRegistry, type IThoughtProcessor, type IToolRegistry, } from './interfaces.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACN,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GAClB,MAAM,iBAAiB,CAAC"}

package/dist/contracts/index.js

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

package/dist/contracts/interfaces.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Shared interface contracts for dependency injection.
+ *
+ * This module centralizes all cross-module interface definitions so that
+ * the DI container (ServiceRegistry) and other modules can depend on
+ * interfaces rather than concrete implementations.
+ *
+ * By importing from contracts/ instead of individual module files,
+ * we reduce lateral coupling and keep the dependency graph shallow.
+ *
+ * @module contracts
+ */
+/**
+ * Metrics interface for observability.
+ *
+ * Defines the contract for metrics collection used across modules.
+ * Implementations include the Prometheus-compatible Metrics class.
+ */
+export interface IMetrics {
+    counter(name: string, value?: number, labels?: Record<string, string>, help?: string): void;
+    gauge(name: string, value: number, labels?: Record<string, string>, help?: string): void;
+    histogram(name: string, value: number, labels?: Record<string, string>, buckets?: number[]): void;
+    get(name: string, labels?: Record<string, string>): number | undefined;
+    inc(name: string, labels?: Record<string, string>): void;
+    dec(name: string, labels?: Record<string, string>): void;
+    reset(): void;
+    export(): string;
+}
+/**
+ * Discovery cache interface for caching tool/skill discovery results.
+ *
+ * Defines the contract for LRU+TTL caching used by registries.
+ * Implementations include the DiscoveryCache class.
+ *
+ * @template T - The type of data being cached
+ */
+export interface IDiscoveryCache<T> {
+    get(key: string): T[] | null;
+    set(key: string, data: T[]): void;
+    has(key: string): boolean;
+    invalidate(key: string): void;
+    clear(): void;
+    dispose(): void;
+    size(): number;
+    getStats(): {
+        size: number;
+        keys: string[];
+    };
+}
+/**
+ * Configuration options for creating a discovery cache.
+ */
+export interface DiscoveryCacheOptions {
+    maxSize?: number;
+    ttl?: number;
+    cleanupInterval?: number;
+    metrics?: IMetrics;
+}
+/**
+ * Thought processor interface for processing thought data.
+ *
+ * Defines the contract for the main processing pipeline.
+ */
+export interface IThoughtProcessor {
+    process(input: unknown): Promise<unknown>;
+}
+/**
+ * Server configuration interface.
+ *
+ * Defines the contract for server configuration used by the DI container.
+ */
+export interface IServerConfig {
+    maxHistorySize: number;
+    maxBranches: number;
+    maxBranchSize: number;
+    skillDirs?: string[];
+    discoveryCache?: DiscoveryCacheOptions;
+    persistence?: Record<string, unknown>;
+    persistenceBufferSize?: number;
+    persistenceFlushInterval?: number;
+    persistenceMaxRetries?: number;
+}
+/**
+ * Tool registry interface for managing MCP tools.
+ *
+ * Defines the contract for tool registration and discovery.
+ */
+export interface IToolRegistry {
+    addTool(tool: unknown): void;
+    getTool(name: string): unknown;
+    listTools(): unknown[];
+    discover(): void;
+    discoverAsync(): Promise<number>;
+}
+/**
+ * Skill registry interface for managing Claude skills.
+ *
+ * Defines the contract for skill registration and discovery.
+ */
+export interface ISkillRegistry {
+    addSkill(skill: unknown): void;
+    getSkill(name: string): unknown;
+    listSkills(): unknown[];
+    discover(): void;
+    discoverAsync(): Promise<number>;
+}
+//# sourceMappingURL=interfaces.d.ts.map

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

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

package/dist/contracts/interfaces.js

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