/**
 * Base reference types for ContractSpec versioning.
 *
 * Provides canonical reference types for linking between specs.
 * Domain-specific refs (OpRef, EventRef, etc.) should alias these
 * base types for consistency and maintainability.
 *
 * @module versioning/refs
 */
/**
 * Base reference type for versioned specs.
 * Used to reference any spec by its key and version.
 *
 * @example
 * ```typescript
 * const opRef: VersionedSpecRef = { key: 'auth.login', version: '1.0.0' };
 * ```
 */
export interface VersionedSpecRef {
    /** Unique key identifying the spec (e.g., "auth.login", "user.created"). */
    key: string;
    /** Semantic version of the spec (e.g., "1.0.0", "2.1.0"). */
    version: string;
}
/**
 * Base reference type for specs with optional version.
 * When version is omitted, typically refers to the latest version.
 *
 * @example
 * ```typescript
 * // Reference to latest version
 * const latestRef: OptionalVersionedSpecRef = { key: 'auth.login' };
 *
 * // Reference to specific version
 * const specificRef: OptionalVersionedSpecRef = { key: 'auth.login', version: '1.0.0' };
 * ```
 */
export interface OptionalVersionedSpecRef {
    /** Unique key identifying the spec. */
    key: string;
    /** Optional semantic version. When omitted, refers to the latest version. */
    version?: string;
}
/**
 * Base reference type for unversioned spec keys.
 * Used when only the key is needed without version information.
 *
 * @example
 * ```typescript
 * const featureRef: SpecKeyRef = { key: 'premium-features' };
 * ```
 */
export interface SpecKeyRef {
    /** Unique key identifying the spec. */
    key: string;
}
/**
 * Checks if a value is a valid VersionedSpecRef.
 *
 * @param ref - The value to check
 * @returns True if the value has both key and version as strings
 *
 * @example
 * ```typescript
 * const ref = { key: 'auth.login', version: '1.0.0' };
 * if (isVersionedSpecRef(ref)) {
 *   console.log(`Spec: ${ref.key}@${ref.version}`);
 * }
 * ```
 */
export declare function isVersionedSpecRef(ref: unknown): ref is VersionedSpecRef;
/**
 * Checks if a value is a valid OptionalVersionedSpecRef.
 *
 * @param ref - The value to check
 * @returns True if the value has a key string and optional version string
 *
 * @example
 * ```typescript
 * const ref = { key: 'auth.login' };
 * if (isOptionalVersionedSpecRef(ref)) {
 *   console.log(`Spec: ${ref.key}${ref.version ? `@${ref.version}` : ''}`);
 * }
 * ```
 */
export declare function isOptionalVersionedSpecRef(ref: unknown): ref is OptionalVersionedSpecRef;
/**
 * Checks if a value is a valid SpecKeyRef.
 *
 * @param ref - The value to check
 * @returns True if the value has a key string
 *
 * @example
 * ```typescript
 * const ref = { key: 'premium-features' };
 * if (isSpecKeyRef(ref)) {
 *   console.log(`Feature: ${ref.key}`);
 * }
 * ```
 */
export declare function isSpecKeyRef(ref: unknown): ref is SpecKeyRef;
/**
 * Creates a versioned spec reference.
 *
 * @param key - The spec key (e.g., "auth.login")
 * @param version - The semantic version (e.g., "1.0.0")
 * @returns A VersionedSpecRef object
 * @throws {Error} If key or version is empty
 *
 * @example
 * ```typescript
 * const ref = createVersionedRef('auth.login', '1.0.0');
 * // { key: 'auth.login', version: '1.0.0' }
 * ```
 */
export declare function createVersionedRef(key: string, version: string): VersionedSpecRef;
/**
 * Creates an optional versioned spec reference.
 *
 * @param key - The spec key (e.g., "auth.login")
 * @param version - Optional semantic version
 * @returns An OptionalVersionedSpecRef object
 * @throws {Error} If key is empty
 *
 * @example
 * ```typescript
 * // Reference to latest version
 * const latestRef = createOptionalRef('auth.login');
 * // { key: 'auth.login' }
 *
 * // Reference to specific version
 * const specificRef = createOptionalRef('auth.login', '1.0.0');
 * // { key: 'auth.login', version: '1.0.0' }
 * ```
 */
export declare function createOptionalRef(key: string, version?: string): OptionalVersionedSpecRef;
/**
 * Creates a spec key reference.
 *
 * @param key - The spec key (e.g., "premium-features")
 * @returns A SpecKeyRef object
 * @throws {Error} If key is empty
 *
 * @example
 * ```typescript
 * const ref = createKeyRef('premium-features');
 * // { key: 'premium-features' }
 * ```
 */
export declare function createKeyRef(key: string): SpecKeyRef;
/**
 * Formats a versioned ref as a string key.
 *
 * @param ref - The versioned spec reference
 * @returns A string in the format "key.vversion"
 *
 * @example
 * ```typescript
 * const str = formatVersionedRefKey({ key: 'auth.login', version: '1.0.0' });
 * // "auth.login.v1.0.0"
 * ```
 */
export declare function formatVersionedRefKey(ref: VersionedSpecRef): string;
/**
 * Parses a versioned ref string back into a ref object.
 *
 * @param refKey - A string in the format "key.vversion"
 * @returns A VersionedSpecRef or undefined if parsing fails
 *
 * @example
 * ```typescript
 * const ref = parseVersionedRefKey('auth.login.v1.0.0');
 * // { key: 'auth.login', version: '1.0.0' }
 * ```
 */
export declare function parseVersionedRefKey(refKey: string): VersionedSpecRef | undefined;
