import type { ChartInput } from '../types/chart';
import type { IztroAstrolabe, IztroHoroscope } from '../types/iztro';
import { type DecadalTimelineOption, type VerifiedDecadalTimelineBatch, type ZiweiHoroscopeResolver } from './iztro/decadal';
/** 紫微任务书可读取的时间范围。范围只描述已有排盘精度，不制造新的周期。 */
export type ZiweiFortuneRangeScope = 'current' | 'all' | 'year' | 'month' | 'day' | 'hour';
export type ZiweiFortuneRangeOptions = {
    scope: ZiweiFortuneRangeScope;
    /** 未提供时使用默认当前时点；网页、API 和 MCP 可传入同一固定日期。 */
    dateStr?: string;
    hourIndex?: number;
    /** 当前阶段或全部范围按年龄年分页；同一年龄年的实际流年交界片段完整返回。 */
    batch?: {
        startIndex?: number;
        limit?: number;
    };
};
export type ZiweiFortuneLayer = {
    name: string;
    heavenlyStem: string;
    earthlyBranch: string;
    palaceNames: string[];
    palaceTargets: string[];
    mutagen: string[];
    stars: string[][];
    yearlyDecStars?: {
        jiangqian12: string[];
        suiqian12: string[];
    };
};
export type ZiweiFortuneMonth = {
    month: number;
    dateStr: string;
    layer: ZiweiFortuneLayer;
    /** 流年从节令年首开始但尚未进入本年正月时，保留这一段真实交界资料。 */
    boundaryFragment?: 'previous-year-tail';
};
export type ZiweiFortuneDay = {
    dateStr: string;
    layer: ZiweiFortuneLayer;
};
export type ZiweiFortuneYear = {
    age: number;
    year: number;
    dateStr: string;
    endDateStr?: string;
    label: string;
    ganZhi: string;
    layer: ZiweiFortuneLayer;
    months?: ZiweiFortuneMonth[];
    targetMonth?: ZiweiFortuneMonth;
    targetDay?: ZiweiFortuneDay;
    targetHour?: ZiweiFortuneLayer;
};
export type ZiweiFortunePeriod = DecadalTimelineOption & {
    layer: ZiweiFortuneLayer;
    years: ZiweiFortuneYear[];
};
export type ZiweiFortuneTimeline = {
    scope: ZiweiFortuneRangeScope;
    targetDateStr: string;
    targetHourIndex: number;
    targetAge: number;
    targetYear: number;
    actualStartDateStr: string;
    actualEndDateStr: string;
    selectedPeriodIndex: number;
    periods: ZiweiFortunePeriod[];
    batch?: {
        unit: 'age-year';
        totalYears: number;
        startIndex: number;
        endIndexExclusive: number;
        nextIndex: number | null;
    };
};
/** 完整运限资料中的一个连续阶段；年份索引保持原时间线顺序。 */
export type ZiweiFortuneTimelinePhaseSelection = {
    periodIndex: number;
    startYearIndex: number;
    endYearIndex: number;
};
/**
 * 年龄分界和流年分界可能不在同一天。按公历每年一月至三月的实际引擎结果
 * 找到流年切换，再把该日期与年龄分界合并；这样不会把两个流年压成一条年龄行。
 */
export declare function collectYearBoundaryDates(startDateStr: string, endDateStr: string, hourIndex: number, resolveHoroscope: ZiweiHoroscopeResolver): Promise<string[]>;
/**
 * 年龄边界沿用 iztro 的虚岁口径：普通分界在对应农历年正月初一，
 * 生日分界则从引擎真正返回该虚岁的首日开始。不能用出生日期的公历年直移。
 */
export declare function buildYearDate(astrolabe: IztroAstrolabe, input: ChartInput, age: number, hourIndex: number, resolveHoroscope: ZiweiHoroscopeResolver, birthSolarDate?: string): Promise<string>;
/** 与运限时间线共用引擎实际流月边界，供日期选择器逐层展开。 */
export declare function buildZiweiFlowMonths(astrolabe: IztroAstrolabe, input: ChartInput, targetDateStr: string, targetHourIndex: number, targetHoroscope: IztroHoroscope, resolveHoroscope: ZiweiHoroscopeResolver): Promise<ZiweiFortuneMonth[]>;
/** 从已生成的星盘复用验证过的大限时间线，组织当前、全部或指定下层资料。 */
export declare function buildZiweiFortuneTimelineFromAstrolabe(astrolabe: IztroAstrolabe, input: ChartInput, decadalTimeline: DecadalTimelineOption[], options: ZiweiFortuneRangeOptions, calculationContext?: {
    resolveHoroscope?: ZiweiHoroscopeResolver;
    verifiedBatch?: VerifiedDecadalTimelineBatch;
}): Promise<ZiweiFortuneTimeline>;
/**
 * normal 年龄口径的独立全范围年龄年内部入口。
 * targetAge 由出生盘和目标日期在核心内计算，不接受调用方提供中间盘面或年龄。
 */
export declare function buildNormalZiweiFortuneBatchTimelineFromAstrolabe(astrolabe: IztroAstrolabe, input: ChartInput, decadalTimeline: DecadalTimelineOption[], options: ZiweiFortuneRangeOptions & {
    scope: 'all';
    dateStr: string;
    hourIndex: number;
    batch: {
        startIndex?: number;
        limit?: number;
    };
}, calculationContext: {
    resolveHoroscope: ZiweiHoroscopeResolver;
    verifiedBatch: VerifiedDecadalTimelineBatch;
    verifiedTargetAge: number;
}): Promise<ZiweiFortuneTimeline>;
/** 独立使用时生成星盘、时间线和范围资料；网页 worker 与公开入口共用此实现。 */
export declare function buildZiweiFortuneTimeline(input: ChartInput, options: ZiweiFortuneRangeOptions): Promise<ZiweiFortuneTimeline>;
/** 将范围资料格式化为可直接放入任务书的紧凑事实段。 */
export declare function formatZiweiFortuneTimeline(timeline: ZiweiFortuneTimeline): string;
/**
 * 将已有完整时间线按大限/流年边界格式化为一个自包含阶段。
 * 阶段只裁剪结构化 periods/years，不裁剪已经格式化的字符串。
 */
export declare function formatZiweiFortuneTimelinePhase(timeline: ZiweiFortuneTimeline, selections: readonly ZiweiFortuneTimelinePhaseSelection[], phaseNumber: number, phaseCount: number): string;
export declare function findZiweiFortunePeriod(timeline: ZiweiFortuneTimeline, nominalAge: number): ZiweiFortunePeriod | null;