/**
 * Timestamp Utilities Module
 *
 * Provides utilities for handling timestamps safely, addressing edge cases like:
 * - NFS timestamp aliasing (MCP-28)
 * - Clock drift/adjustment (MCP-31)
 * - Future timestamps
 * - Invalid timestamps
 *
 * Uses performance.now() for duration calculations when high precision is needed,
 * and provides validation for file timestamps.
 */
/**
 * Maximum reasonable timestamp age (1 year in milliseconds)
 * Files older than this are suspicious and may indicate timestamp issues
 */
declare const MAX_REASONABLE_AGE_MS: number;
/**
 * Maximum acceptable future timestamp (5 minutes in milliseconds)
 * Files with timestamps this far in the future are suspicious
 */
declare const MAX_FUTURE_TOLERANCE_MS: number;
/**
 * NFS timestamp resolution (1 second in milliseconds)
 * NFS v3 has 1-second resolution, which can cause timestamp aliasing
 */
declare const NFS_TIMESTAMP_RESOLUTION_MS = 1000;
/**
 * Result of timestamp validation
 */
export interface TimestampValidationResult {
    /** Whether the timestamp is valid and usable */
    isValid: boolean;
    /** Reason if timestamp is invalid */
    reason?: string;
    /** Whether the timestamp should be treated with caution */
    isSuspicious: boolean;
}
/**
 * Validate a file timestamp
 *
 * Checks for common timestamp issues:
 * - Negative timestamps (invalid)
 * - Zero timestamps (likely uninitialized)
 * - Timestamps far in the future (clock skew)
 * - Timestamps far in the past (suspicious)
 *
 * @param timestamp - Timestamp in milliseconds since epoch
 * @param referenceTime - Reference time (default: Date.now())
 * @returns Validation result
 *
 * @example
 * ```typescript
 * const result = validateTimestamp(file.mtimeMs);
 * if (!result.isValid) {
 *   console.warn(`Invalid timestamp: ${result.reason}`);
 * }
 * ```
 */
export declare function validateTimestamp(timestamp: number, referenceTime?: number): TimestampValidationResult;
/**
 * Check if two timestamps could be the same due to NFS aliasing
 *
 * NFS v3 has 1-second timestamp resolution, meaning two different
 * file modifications within the same second will have the same timestamp.
 *
 * @param timestamp1 - First timestamp in milliseconds
 * @param timestamp2 - Second timestamp in milliseconds
 * @returns true if timestamps are within NFS resolution
 *
 * @example
 * ```typescript
 * if (couldBeNfsAliased(oldMtime, newMtime)) {
 *   // Fall back to content hash comparison
 *   const hashChanged = await compareHashes(oldHash, newHash);
 * }
 * ```
 */
export declare function couldBeNfsAliased(timestamp1: number, timestamp2: number): boolean;
/**
 * Get a safe timestamp, returning a fallback if the timestamp is invalid
 *
 * @param timestamp - Timestamp to validate
 * @param fallback - Fallback timestamp (default: Date.now())
 * @returns Valid timestamp or fallback
 */
export declare function getSafeTimestamp(timestamp: number, fallback?: number): number;
/**
 * Performance timer for measuring durations with high precision
 *
 * Uses performance.now() which is immune to clock adjustments and
 * provides sub-millisecond precision.
 *
 * @example
 * ```typescript
 * const timer = createPerfTimer();
 * await someOperation();
 * console.log(`Operation took ${timer.elapsed()}ms`);
 * ```
 */
export interface PerfTimer {
    /** Get elapsed time in milliseconds */
    elapsed(): number;
    /** Reset the timer */
    reset(): void;
}
/**
 * Create a high-precision performance timer
 *
 * @returns PerfTimer instance
 */
export declare function createPerfTimer(): PerfTimer;
/**
 * Measure the duration of an async operation with high precision
 *
 * @param operation - Async operation to measure
 * @returns Object with result and duration in milliseconds
 *
 * @example
 * ```typescript
 * const { result, durationMs } = await measureDuration(async () => {
 *   return await searchIndex(query);
 * });
 * console.log(`Search took ${durationMs}ms, found ${result.length} results`);
 * ```
 */
export declare function measureDuration<T>(operation: () => Promise<T>): Promise<{
    result: T;
    durationMs: number;
}>;
export { MAX_REASONABLE_AGE_MS, MAX_FUTURE_TOLERANCE_MS, NFS_TIMESTAMP_RESOLUTION_MS, };
//# sourceMappingURL=timestamp.d.ts.map