export declare function assertUuid(str: string, which?: string): string;
/**
 * Generate a UUID v7 from a timestamp.
 *
 * @param timestamp - The timestamp in milliseconds
 * @returns A UUID v7 string
 */
export declare function uuid7FromTime(timestamp: number | string): string;
/**
 * Get the version of a UUID string.
 * @param uuidStr - The UUID string to check
 * @returns The version number (1-7) or null if invalid
 */
export declare function getUuidVersion(uuidStr: string): number | null;
/**
 * Warn if a UUID is not version 7.
 *
 * @param uuidStr - The UUID string to check
 * @param idType - The type of ID (e.g., "run_id", "trace_id") for the warning message
 */
export declare function warnIfNotUuidV7(uuidStr: string, _idType: string): void;
/**
 * Generate a deterministic UUID v7 derived from an original UUID and a key.
 *
 * A pure function of `originalId` and `key`: it reads no ambient state, so the
 * same pair always yields the same UUID, in any process, at any time. This is
 * used for creating replica ids that are reproducible across distributed
 * systems, including across SDK implementations.
 *
 * A UUID v7 original keeps its timestamp, so derived ids stay ordered by run
 * start time. Any other original has none to keep, and the field is
 * hash-derived: stable, but not chronological.
 *
 * @param originalId - The source UUID string (ideally UUID v7 to preserve timestamp)
 * @param key - A string key used for deterministic derivation (e.g., project name)
 * @returns A new UUID v7 string with preserved timestamp (if original is v7) and
 *          deterministic random bits
 *
 * @example
 * ```typescript
 * const original = uuidv7();
 * const replicaId = nonCryptographicUuid7Deterministic(original, "replica-project");
 * // Same inputs always produce same output
 * assert(nonCryptographicUuid7Deterministic(original, "replica-project") === replicaId);
 * ```
 */
export declare function nonCryptographicUuid7Deterministic(originalId: string, key: string): string;