atlas-pipeline-mcp 1.0.16 → 1.0.18

package/dist/types.d.ts

@@ -3,20 +3,55 @@
  *
  * This module defines all shared interfaces and types used across the
  * multi-stage AI pipeline. Types are organized by domain concern.
+ *
+ * Design Principles:
+ * - Branded types for domain-specific values (IDs, scores)
+ * - Strict readonly types where mutation is not expected
+ * - Comprehensive Zod schemas for runtime validation
+ * - Type guards for safe narrowing
+ *
+ * @module types
+ * @version 2.0.0
  */
 import { z } from 'zod';
+/** Brand type for creating nominal types */
+declare const brand: unique symbol;
+type Brand<T, B> = T & {
+    readonly [brand]: B;
+};
+/** Branded type for variant IDs */
+export type VariantId = Brand<string, 'VariantId'>;
+/** Branded type for task IDs */
+export type TaskId = Brand<string, 'TaskId'>;
+/** Branded type for session IDs */
+export type SessionId = Brand<string, 'SessionId'>;
+/** Score between 0 and 100 */
+export type Score = Brand<number, 'Score'>;
+/** Confidence value between 0 and 1 */
+export type Confidence = Brand<number, 'Confidence'>;
+/** Helper to create a Score (clamped 0-100) */
+export declare function createScore(value: number): Score;
+/** Helper to create a Confidence (clamped 0-1) */
+export declare function createConfidence(value: number): Confidence;
+/** Helper to create a SessionId */
+export declare function createSessionId(value: string): SessionId;
 /**
  * Represents the user's original request to the pipeline
+ * @immutable - Should not be mutated after creation
  */
 export interface PipelineRequest {
     /** The raw user query or instruction */
-    query: string;
+    readonly query: string;
     /** Optional repository path for git operations */
-    repoPath?: string;
+    readonly repoPath?: string;
     /** Additional context provided by the user */
-    userContext?: Record<string, unknown>;
+    readonly userContext?: Readonly<Record<string, unknown>>;
     /** Session identifier for tracking */
-    sessionId?: string;
+    readonly sessionId?: SessionId;
+    /** Request timestamp for metrics */
+    readonly timestamp?: string;
+    /** Request priority (affects queue ordering) */
+    readonly priority?: 'low' | 'normal' | 'high';
 }
 /**
  * The final output of the pipeline after all stages complete
@@ -33,31 +68,48 @@ export interface PipelineResponse {
 }
 /**
  * Metadata collected during pipeline execution
+ * @immutable - Frozen after pipeline completion
  */
 export interface PipelineMetadata {
     /** Total execution time in milliseconds */
-    executionTimeMs: number;
+    readonly executionTimeMs: number;
     /** Results from each pipeline stage */
-    stages: StageResult[];
+    readonly stages: readonly StageResult[];
     /** The model used for generation */
-    model: string;
+    readonly model: string;
+    /** Provider used (ollama, openai, anthropic, auto) */
+    readonly provider?: string;
     /** Timestamp when processing started */
-    startedAt: string;
+    readonly startedAt: string;
     /** Timestamp when processing completed */
-    completedAt: string;
+    readonly completedAt: string;
+    /** Total tokens used (if available) */
+    readonly tokensUsed?: {
+        readonly prompt: number;
+        readonly completion: number;
+        readonly total: number;
+    };
+    /** Cache hit information */
+    readonly cacheHits?: number;
 }
 /**
  * Result from a single pipeline stage
  */
-export interface StageResult {
+export interface StageResult<T = unknown> {
     /** Name of the stage */
-    name: StageName;
+    readonly name: StageName;
     /** Whether this stage succeeded */
-    success: boolean;
+    readonly success: boolean;
     /** Execution time for this stage in milliseconds */
-    durationMs: number;
+    readonly durationMs: number;
     /** Optional output data from the stage */
-    output?: unknown;
+    readonly output?: T;
+    /** Error message if stage failed */
+    readonly error?: string;
+    /** Whether result came from cache */
+    readonly cached?: boolean;
+    /** Retry count if retries were needed */
+    readonly retries?: number;
 }
 /**
  * Names of all pipeline stages
@@ -81,17 +133,21 @@ export interface PipelineError {
  */
 export interface IntentAnalysis {
     /** Primary intent category */
-    primaryIntent: IntentType;
+    readonly primaryIntent: IntentType;
+    /** Secondary intent if detected */
+    readonly secondaryIntent?: IntentType;
     /** Confidence score from 0 to 1 */
-    confidence: number;
+    readonly confidence: Confidence;
     /** Extracted entities from the query */
-    entities: ExtractedEntity[];
+    readonly entities: readonly ExtractedEntity[];
     /** Keywords identified in the query */
-    keywords: string[];
+    readonly keywords: readonly string[];
     /** Whether the query requires clarification */
-    requiresClarification: boolean;
+    readonly requiresClarification: boolean;
     /** Suggested clarifying questions if needed */
-    clarifyingQuestions?: string[];
+    readonly clarifyingQuestions?: readonly string[];
+    /** Raw query for reference */
+    readonly rawQuery?: string;
 }
 /**
  * Types of intents the system can classify
@@ -444,4 +500,5 @@ export interface ServerConfig {
     /** Enable CORS */
     corsEnabled: boolean;
 }
+export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -3,8 +3,29 @@
  *
  * This module defines all shared interfaces and types used across the
  * multi-stage AI pipeline. Types are organized by domain concern.
+ *
+ * Design Principles:
+ * - Branded types for domain-specific values (IDs, scores)
+ * - Strict readonly types where mutation is not expected
+ * - Comprehensive Zod schemas for runtime validation
+ * - Type guards for safe narrowing
+ *
+ * @module types
+ * @version 2.0.0
  */
 import { z } from 'zod';
+/** Helper to create a Score (clamped 0-100) */
+export function createScore(value) {
+    return Math.max(0, Math.min(100, Math.round(value)));
+}
+/** Helper to create a Confidence (clamped 0-1) */
+export function createConfidence(value) {
+    return Math.max(0, Math.min(1, value));
+}
+/** Helper to create a SessionId */
+export function createSessionId(value) {
+    return value;
+}
 // ============================================================================
 // Zod Schemas for Validation
 // ============================================================================

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAqdxB,+EAA+E;AAC/E,6BAA6B;AAC7B,+EAA+E;AAE/E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,mBAAmB,CAAC;IAC7C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC7C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;IACpD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC;QACjB,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE;KACpB,CAAC;CACH,CAAC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAyBxB,+CAA+C;AAC/C,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAU,CAAC;AAChE,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAe,CAAC;AACvD,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,KAAkB,CAAC;AAC5B,CAAC;AA+eD,+EAA+E;AAC/E,6BAA6B;AAC7B,+EAA+E;AAE/E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,mBAAmB,CAAC;IAC7C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC7C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;IACpD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC;QACjB,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE;KACpB,CAAC;CACH,CAAC,CAAC"}

package/dist/utils.d.ts

@@ -2,18 +2,34 @@
  * Atlas Server - Utility Functions
  *
  * Shared utilities for logging, timing, error handling, and common operations.
+ *
+ * Features:
+ * - High-performance logging with MCP mode support
+ * - Circuit breaker pattern for resilient external calls
+ * - LRU cache with TTL for efficient memoization
+ * - Comprehensive retry logic with exponential backoff
+ * - Type-safe error handling utilities
+ *
+ * @module utils
+ * @version 2.0.0
  */
 import pino from 'pino';
 import type { PipelineError, StageName, StageResult } from './types.js';
+/** Default concurrency limit for parallel operations */
+export declare const DEFAULT_CONCURRENCY = 3;
 /**
  * Create a configured pino logger instance
  * In MCP mode, we disable pretty printing to avoid polluting stdio
+ * @param level - Log level (debug, info, warn, error, silent)
  */
-export declare function createLogger(level?: string): pino.Logger<never, boolean>;
-/** Default logger instance */
+export declare function createLogger(level?: string): pino.Logger;
+/** Default logger instance (singleton) */
 export declare const logger: pino.Logger<never, boolean>;
 /**
- * Measure execution time of an async function
+ * Measure execution time of an async function with high precision
+ * @template T - Return type of the function
+ * @param fn - Async function to measure
+ * @returns Result and duration in milliseconds
  */
 export declare function measureTime<T>(fn: () => Promise<T>): Promise<{
     result: T;
@@ -21,19 +37,29 @@ export declare function measureTime<T>(fn: () => Promise<T>): Promise<{
 }>;
 /**
  * Create a simple timer for measuring elapsed time
+ * Useful for tracking duration across multiple operations
  */
 export declare function createTimer(): {
     elapsed: () => number;
+    reset: () => void;
 };
 /**
  * Safely stringify an object, handling circular references
  */
 export declare function safeStringify(obj: unknown, indent?: number): string;
 /**
- * Create a stage result with timing
- */
-export declare function executeStage<T>(name: StageName, fn: () => Promise<T>): Promise<{
-    stageResult: StageResult;
+ * Create a stage result with timing, error handling, and optional retry
+ * @template T - Output type of the stage function
+ * @param name - Stage name for tracking
+ * @param fn - Async function to execute
+ * @param options - Optional configuration (retries, timeout)
+ * @returns Stage result with output or error
+ */
+export declare function executeStage<T>(name: StageName, fn: () => Promise<T>, options?: {
+    retries?: number;
+    timeoutMs?: number;
+}): Promise<{
+    stageResult: StageResult<T>;
     output: T;
 }>;
 /**
@@ -85,6 +111,31 @@ export declare function retry<T>(fn: () => Promise<T>, options?: Partial<RetryOp
  * Sleep for a specified duration
  */
 export declare function sleep(ms: number): Promise<void>;
+/**
+ * Circuit breaker states
+ */
+type CircuitState = 'closed' | 'open' | 'half-open';
+/**
+ * Circuit breaker for resilient external service calls
+ * Prevents cascade failures by failing fast when service is unavailable
+ */
+export declare class CircuitBreaker {
+    private readonly options;
+    private state;
+    private failureCount;
+    private lastFailureTime;
+    private successCount;
+    constructor(options?: {
+        failureThreshold: number;
+        resetTimeoutMs: number;
+        halfOpenSuccesses: number;
+    });
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    private onSuccess;
+    private onFailure;
+    getState(): CircuitState;
+    reset(): void;
+}
 /**
  * Safely parse JSON with error handling
  */
@@ -116,15 +167,60 @@ export declare function nowISO(): string;
  */
 export declare function formatDuration(ms: number): string;
 /**
- * Process items in parallel with concurrency limit
+ * Process items in parallel with concurrency limit and progress tracking
+ * @template T - Input item type
+ * @template R - Result type
+ * @param items - Array of items to process
+ * @param fn - Async function to apply to each item
+ * @param options - Configuration options
+ * @returns Array of results in original order
  */
-export declare function parallelMap<T, R>(items: T[], fn: (item: T, index: number) => Promise<R>, concurrency?: number): Promise<R[]>;
+export declare function parallelMap<T, R>(items: T[], fn: (item: T, index: number) => Promise<R>, options?: {
+    concurrency?: number;
+    onProgress?: (completed: number, total: number) => void;
+    stopOnError?: boolean;
+}): Promise<R[]>;
 /**
  * Debounce async function calls
  */
 export declare function debounce<T extends (...args: unknown[]) => Promise<unknown>>(fn: T, delayMs: number): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
 /**
- * Memoize async function with TTL and automatic cleanup
- */
-export declare function memoizeAsync<T extends (...args: unknown[]) => Promise<unknown>>(fn: T, ttlMs?: number, keyFn?: (...args: Parameters<T>) => string, maxCacheSize?: number): T;
+ * LRU Cache with TTL support for efficient memoization
+ * @template K - Key type
+ * @template V - Value type
+ */
+export declare class LRUCache<K, V> {
+    private readonly maxSize;
+    private readonly ttlMs;
+    private cache;
+    constructor(maxSize?: number, ttlMs?: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V, ttlMs?: number): void;
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    clear(): void;
+    get size(): number;
+    private evictLRU;
+    /** Get cache statistics */
+    getStats(): {
+        size: number;
+        maxSize: number;
+    };
+}
+/**
+ * Memoize async function with LRU cache and TTL
+ * @template T - Function type
+ * @param fn - Async function to memoize
+ * @param options - Cache configuration
+ * @returns Memoized function
+ */
+export declare function memoizeAsync<T extends (...args: unknown[]) => Promise<unknown>>(fn: T, options?: {
+    ttlMs?: number;
+    maxCacheSize?: number;
+    keyFn?: (...args: Parameters<T>) => string;
+}): T & {
+    cache: LRUCache<string, Awaited<ReturnType<T>>>;
+    clearCache: () => void;
+};
+export {};
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAWxE;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,GAAE,MAAe,+BAoBlD;AAED,8BAA8B;AAC9B,eAAO,MAAM,MAAM,6BAAmD,CAAC;AAMvE;;GAEG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAK5C;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI;IAAE,OAAO,EAAE,MAAM,MAAM,CAAA;CAAE,CAKvD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,MAAU,GAAG,MAAM,CAetE;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,IAAI,EAAE,SAAS,EACf,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC;IAAE,WAAW,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CA+BlD;AAMD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,SAAS,EACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,aAAa,CAOf;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAEtD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQtD;AAMD;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAGnC;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAG/D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAazF;AAMD,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AASD;;GAEG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,OAAO,CAAC,YAAY,CAAM,GAClC,OAAO,CAAC,CAAC,CAAC,CA0BZ;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAMD;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAO7G;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAoBrD;AAMD;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,IAAI,CAAC,CAEpE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,CAAC,CAKhF;AAMD;;GAEG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAE/B;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAUjD;AAMD;;GAEG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,CAAC,EACpC,KAAK,EAAE,CAAC,EAAE,EACV,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,WAAW,GAAE,MAAU,GACtB,OAAO,CAAC,CAAC,EAAE,CAAC,CAoBd;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,EACzE,EAAE,EAAE,CAAC,EACL,OAAO,EAAE,MAAM,GACd,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAmB7D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,EAC7E,EAAE,EAAE,CAAC,EACL,KAAK,GAAE,MAAc,EACrB,KAAK,GAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,MAA0C,EAC7E,YAAY,GAAE,MAAY,GACzB,CAAC,CAkCH"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}