/**
 * Resolution helpers for relationship-qualified field names (`relationship.field`).
 *
 * v1 supports one hop over to-one relationships (`belongsTo`, `hasOne`) only,
 * addressing dimensions declared on the target dataset. `hasMany` stays
 * metadata-only to avoid fan-out corruption of aggregates. See
 * `plans/relationship-aware-semantics-design.md`.
 */
import type { AnyDatasetInstance, DimensionDefinition, RelationshipDefinition } from '../types.js';
/**
 * Enumerates the queryable qualified field names (`<name>.<dimension>`) a
 * relationship contributes, applying the same rules `resolveQualifiedField`
 * enforces at query time: `hasMany` contributes nothing and SQL-backed target
 * dimensions are excluded. Keep the two in sync — the catalog, contract, and
 * generated input schemas all advertise exactly this list.
 */
export declare function listQueryableRelationshipFields(name: string, relationship: RelationshipDefinition): string[];
export interface ParsedQualifiedField {
    /** The relationship name (prefix before the first dot). */
    relationship: string;
    /** Everything after the first dot — the target field, possibly multi-hop. */
    field: string;
}
/** True when a field name is relationship-qualified (contains a dot). */
export declare function isQualifiedField(name: string): boolean;
/**
 * Splits a qualified name into its relationship prefix and remaining field.
 * Returns null when `name` is not qualified (no dot), so callers can treat it
 * as a local field.
 */
export declare function parseQualifiedField(name: string): ParsedQualifiedField | null;
export interface ResolvedQualifiedField {
    /** Relationship name, also used as the SQL table alias / qualified prefix. */
    relationshipName: string;
    relationship: RelationshipDefinition;
    /** The resolved target dataset instance. */
    target: AnyDatasetInstance;
    /** Target dimension name (the allowlist key on the target). */
    targetDimensionName: string;
    targetDimension: DimensionDefinition;
    /** Physical column backing the target dimension. */
    targetColumn: string;
    /** The qualified name exactly as referenced, e.g. `customer.country`. */
    qualifiedName: string;
}
export type QualifiedFieldResolution = {
    resolved: ResolvedQualifiedField;
    error?: undefined;
} | {
    resolved?: undefined;
    error: string;
};
/**
 * Resolves a relationship-qualified field name against a base dataset.
 *
 * Returns null when `name` is not qualified (caller handles it as a local
 * field). Otherwise returns either the resolved to-one target dimension or an
 * actionable validation error (unknown relationship, multi-hop, `hasMany`,
 * unknown target dimension, or SQL-backed target dimension).
 */
export declare function resolveQualifiedField(ds: AnyDatasetInstance, name: string): QualifiedFieldResolution | null;
//# sourceMappingURL=relationship-fields.d.ts.map