Skip to content

World's first open-source enterprise world model.

60.5 KB
Raw Blame
//! 时间提及按文档解析(0045 决定 2–5):模型读,代码算。
//!
//! 抽取只记时间**词**(`time_mentions`:原样的字、块、偏移、起/止)。这里是它后面的任务:
//!
//! 1. **文档时间上下文**(决定 3;0064 起由抽取时各块报上来,这里不再问模型)。从前:把开头交给模型,它转写文档自己的日期
//!    (落款、备案日、公报的报告年)和文档命名的期间(「fiscal 2027」及其起止);日期词要在
//!    开头里核对得到才算数。结果存在 `documents.time_context`;文档自己的日期写进 `doc_time`
//!    (来源 `content`)。上传时间永远不进来(#714)。
//! 2. **解释**(决定 2)。把文档的每个时间词连同它所在的那句话,和上下文一起交给模型;模型
//!    只回形状、引用(写明的数字部分 / 锚点加偏移 / 命名的期间 / 没有)和粒度,**从不算日期**。
//!    解释原样存回提及上,错了看得见、改得了。
//! 3. **算**。日历算术、期间到区间、按粒度截断、形状蕴含的区间,都在这里用结构化字段算,
//!    没有一个时间词写在代码里(决定 8)。写明的日期是 A 级,从文档自己给的锚点算出来的是
//!    B 级,锚不到的是 C 级——C 级什么也不写,等锚点(决定 4、6)。
//! 4. 结果落到开放陈述的 `valid_from` / `valid_to`(决定 5 的第一根轴),时间轴上才有它。
//!
//! 例外只长在推送的陈述上(0054 来源):`when` / `ended` 写的是完整日期或带区时刻时,
//! 载荷就已经是结构化的绝对值——结构化的时间戳不是时间词(0045 决定 8,#1089),代码
//! 直接读成解释,不送模型;没有对话模型时,代码读得动的照解,读不动的留 C,任务照常收工。

use crate::extraction::chat_retrying_rate_limits_at;
use crate::llm_util;
use crate::state::AppState;
use chrono::{DateTime, Duration, Months, NaiveDate, NaiveTime, TimeZone, Utc};
use std::collections::{HashMap, HashSet};
use utopia_extract::time::{
    build_interpretation_messages, headings_at, now_in_force, parse_interpretation_response,
    Anchor, DateParts, Direction, DocumentDating, Granularity, Interpretation, MentionInput,
    NamedPeriod, Offset, Reference, Shape, TimeContext, Unit,
};
use utopia_store::graph::{truncate_to, ENDED_UNKNOWN, WORLD_PRECISIONS};
use uuid::Uuid;

/// 一批解释问多少个提及。
const BATCH: usize = 40;

/// 一次解析的结果:世界轴上的位置与等级。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct Resolved {
    from: Option<DateTime<Utc>>,
    from_p: Option<&'static str>,
    to: Option<DateTime<Utc>>,
    to_p: Option<&'static str>,
    /// A:写明的;B:从文档自己的锚点算出来的;C:锚不到
    grade: &'static str,
}

const UNRESOLVED: Resolved = Resolved {
    from: None,
    from_p: None,
    to: None,
    to_p: None,
    grade: "C",
};

/// 数字部分 → 时刻与精度。精度是字写到的那一档:只有年就是年。
fn parts_to_time(p: &DateParts) -> Option<(DateTime<Utc>, &'static str)> {
    // 写明的季度从它的头一个月起(日历季度;财年的季度走命名的期间)
    let month = p.month.or(p.quarter.map(|q| (q - 1) * 3 + 1));
    let p = &DateParts { month, ..p.clone() };
    let date = NaiveDate::from_ymd_opt(p.year, p.month.unwrap_or(1), p.day.unwrap_or(1))?;
    let time = NaiveTime::from_hms_opt(
        p.hour.unwrap_or(0),
        p.minute.unwrap_or(0),
        p.second.unwrap_or(0),
    )?;
    let precision = if p.month.is_none() {
        "year"
    } else if p.day.is_none() {
        "month"
    } else if p.hour.is_none() {
        "day"
    } else if p.minute.is_none() {
        "hour"
    } else if p.second.is_none() {
        "minute"
    } else {
        "second"
    };
    Some((Utc.from_utc_datetime(&date.and_time(time)), precision))
}

fn granularity_str(g: Granularity) -> &'static str {
    match g {
        Granularity::Year => "year",
        Granularity::Month => "month",
        Granularity::Day => "day",
        Granularity::Hour => "hour",
        Granularity::Minute => "minute",
        Granularity::Second => "second",
    }
}

/// 两档精度取粗的那一档:字只写到年,模型说是「天」也只能是年——精度不能比字更细
fn coarser(a: &'static str, b: &'static str) -> &'static str {
    let rank = |p: &str| WORLD_PRECISIONS.iter().position(|x| *x == p).unwrap_or(0);
    if rank(a) <= rank(b) {
        a
    } else {
        b
    }
}

/// 锚点加偏移(决定 2 的算术)。月、季、年按月份加减(月末自动收口);周和天以下按时长。
fn shift(t: DateTime<Utc>, offset: &Offset) -> Option<DateTime<Utc>> {
    let count = offset.count.unsigned_abs();
    let forward = (offset.direction == Direction::After) == (offset.count >= 0);
    let months = |n: u64| -> Option<DateTime<Utc>> {
        let m = Months::new(u32::try_from(n).ok()?);
        if forward {
            t.checked_add_months(m)
        } else {
            t.checked_sub_months(m)
        }
    };
    let span = |d: Duration| -> Option<DateTime<Utc>> {
        if forward {
            t.checked_add_signed(d)
        } else {
            t.checked_sub_signed(d)
        }
    };
    match offset.unit {
        Unit::Year => months(count.checked_mul(12)?),
        Unit::Quarter => months(count.checked_mul(3)?),
        Unit::Month => months(count),
        Unit::Week => span(Duration::weeks(i64::try_from(count).ok()?)),
        Unit::Day => span(Duration::days(i64::try_from(count).ok()?)),
        Unit::Hour => span(Duration::hours(i64::try_from(count).ok()?)),
        Unit::Minute => span(Duration::minutes(i64::try_from(count).ok()?)),
        Unit::Second => span(Duration::seconds(i64::try_from(count).ok()?)),
    }
}

/// 一个时刻和它的精度(世界轴的一端)。
type Bound = (DateTime<Utc>, &'static str);

/// 一个季度:包含 `t` 的那三个月(有财年结束日就按财年的季,否则按日历季),
/// 起是季首月,止是季末月(终点精度到月)。「本季度」「上季度」都从这里来
fn quarter_around(t: DateTime<Utc>, fiscal_year_end: Option<(u32, u32)>) -> Option<(Bound, Bound)> {
    use chrono::Datelike;
    // 财年从结束日的下一个月算起:结束于 1 月 25 日的财年,季首月是 2、5、8、11 月
    let first_month = fiscal_year_end.map(|(m, _)| m % 12 + 1).unwrap_or(1);
    let month0 = (t.month() as i32 - first_month as i32).rem_euclid(12); // 财年内第几个月(0 起)
    let start_month0 = month0 - month0 % 3;
    let start = t.checked_sub_months(Months::new(u32::try_from(month0 - start_month0).ok()?))?;
    let start = truncate_to(start, Some("month"));
    let end = start.checked_add_months(Months::new(2))?;
    Some(((start, "month"), (end, "month")))
}

/// 一个期间的起止(写明的数字部分)。
fn period_bounds(from: &DateParts, to: &DateParts) -> Option<(Bound, Bound)> {
    Some((parts_to_time(from)?, parts_to_time(to)?))
}

/// 形状决定字在世界轴上占哪一段(决定 7:形状另存,这里只算区间)。
/// 点:一刻,两端同值(0031 事件的写法);自:起点;至:终点;区间:两端;
/// 截至:观察到的起点;时长:没有位置;结束但不知何时:终点精度 unknown
fn place(
    shape: Shape,
    at: Option<(DateTime<Utc>, &'static str)>,
    until: Option<(DateTime<Utc>, &'static str)>,
    grade: &'static str,
) -> Resolved {
    let trunc = |(t, p): (DateTime<Utc>, &'static str)| (truncate_to(t, Some(p)), p);
    let at = at.map(trunc);
    let until = until.map(trunc);
    let mut r = Resolved {
        grade,
        ..UNRESOLVED
    };
    match shape {
        Shape::Point => {
            if let Some((t, p)) = at {
                r.from = Some(t);
                r.from_p = Some(p);
                r.to = Some(t);
                r.to_p = Some(p);
            }
        }
        Shape::Since | Shape::AsOf => {
            if let Some((t, p)) = at {
                r.from = Some(t);
                r.from_p = Some(p);
            }
        }
        Shape::Until => {
            if let Some((t, p)) = until.or(at) {
                r.to = Some(t);
                r.to_p = Some(p);
            }
        }
        Shape::Interval => {
            if let Some((t, p)) = at {
                r.from = Some(t);
                r.from_p = Some(p);
            }
            if let Some((t, p)) = until {
                r.to = Some(t);
                r.to_p = Some(p);
            }
        }
        Shape::Duration => return UNRESOLVED,
        Shape::EndedUnknown => {
            r.to_p = Some(ENDED_UNKNOWN);
        }
    }
    if r.from.is_none() && r.to.is_none() && r.to_p.is_none() {
        return UNRESOLVED;
    }
    r
}

/// 一个锚点在世界轴上的位置:文档日期、另一个提及、命名的期间。
fn anchor_time(
    anchor: &Anchor,
    ctx: &DocumentDating,
    earlier: &HashMap<i64, Resolved>,
) -> Option<(Bound, Option<Bound>)> {
    match anchor {
        Anchor::Document => ctx.date.as_ref().and_then(parts_to_time).map(|t| (t, None)),
        Anchor::Mention { id } => {
            let r = earlier.get(id)?;
            let from = r.from.zip(r.from_p)?;
            Some((from, r.to.zip(r.to_p)))
        }
        Anchor::Period { name } => {
            let p = ctx
                .periods
                .iter()
                .find(|p| p.name.eq_ignore_ascii_case(name))?;
            let (from, to) = period_bounds(&p.from, &p.to)?;
            Some((from, Some(to)))
        }
    }
}

/// 一条解释 → 世界轴位置。`earlier` 是同一文档里已经算出来的提及(锚点指着它们)。
fn resolve_one(
    interp: &Interpretation,
    ctx: &DocumentDating,
    earlier: &HashMap<i64, Resolved>,
) -> Resolved {
    let g = granularity_str(interp.granularity);
    // 「结束了,不知哪天」是字明说的(#393 的那一档):没有日期可算,但结束本身是 A 级
    if interp.shape == Shape::EndedUnknown {
        return place(Shape::EndedUnknown, None, None, "A");
    }
    match &interp.reference {
        Reference::Absolute { from, to } => {
            let Some((t, p)) = parts_to_time(from) else {
                return UNRESOLVED;
            };
            let until = to.as_ref().and_then(parts_to_time);
            // 一个季度是三个月的区间:到它最后一个月为止
            if let (Some(_), None) = (from.quarter, &until) {
                let last = t.checked_add_months(Months::new(2)).map(|m| (m, "month"));
                let shape = match interp.shape {
                    Shape::Point | Shape::Duration => Shape::Interval,
                    s => s,
                };
                return place(shape, Some((t, "month")), last, "A");
            }
            place(interp.shape, Some((t, coarser(p, g))), until, "A")
        }
        Reference::Anchored { anchor, offset } => {
            let Some(((t, p), until)) = anchor_time(anchor, ctx, earlier) else {
                return UNRESOLVED;
            };
            // 对着一个期间说「截至」「至」(「年末」对着报告年):说的是期间的末,不是首。
            // 这是形状的语义,不是认词
            if offset.is_none()
                && matches!(anchor, Anchor::Period { .. })
                && matches!(interp.shape, Shape::AsOf | Shape::Until)
            {
                if let Some(end) = until {
                    return place(interp.shape, Some(end), None, "B");
                }
            }
            let (t, until) = match offset {
                Some(o) => {
                    let Some(moved) = shift(t, o) else {
                        return UNRESOLVED;
                    };
                    // 以「年」「月」为单位的偏移(本年、去年、上个月)说的是那一整段:
                    // 起止同一个桶,精度就是那个单位
                    if matches!(o.unit, Unit::Year | Unit::Month)
                        && matches!(interp.shape, Shape::Point | Shape::Interval)
                    {
                        let unit_p = if o.unit == Unit::Year {
                            "year"
                        } else {
                            "month"
                        };
                        let start = truncate_to(moved, Some(unit_p));
                        return place(Shape::Point, Some((start, unit_p)), None, "B");
                    }
                    // 以「季」为单位的偏移(本季度、上季度)说的是那一整个季度,不是某一天
                    if o.unit == Unit::Quarter {
                        let Some((from, to)) = quarter_around(moved, ctx.fiscal_year_end) else {
                            return UNRESOLVED;
                        };
                        let shape = match interp.shape {
                            Shape::Point | Shape::Since | Shape::AsOf | Shape::Duration => {
                                Shape::Interval
                            }
                            s => s,
                        };
                        return place(shape, Some(from), Some(to), "B");
                    }
                    (moved, until.and_then(|(u, _)| shift(u, o).map(|m| (m, g))))
                }
                None => (t, until),
            };
            // 锚点算出来的时刻,精度由字说的粒度定,但不能比锚点自己更细
            place(interp.shape, Some((t, coarser(p, g))), until, "B")
        }
        Reference::Period { name, from, to } => {
            // 只写了一端的期间(「三个月截至 6 月 30 日」):写明的那一端照写,另一端不猜
            match (from, to) {
                (None, Some(t)) => {
                    return place(Shape::Until, None, parts_to_time(t), "A");
                }
                (Some(f), None) => {
                    return place(Shape::Since, parts_to_time(f), None, "A");
                }
                _ => {}
            }
            let (bounds, grade) = match (from, to) {
                (Some(f), Some(t)) => (period_bounds(f, t), "A"),
                _ => (
                    ctx.periods
                        .iter()
                        .find(|p| p.name.eq_ignore_ascii_case(name))
                        .and_then(|p| period_bounds(&p.from, &p.to)),
                    "B",
                ),
            };
            let Some((from, to)) = bounds else {
                return UNRESOLVED;
            };
            // 一个期间本身是区间;「截至期末」这类形状照形状算
            let shape = match interp.shape {
                Shape::Point | Shape::Since | Shape::Duration => Shape::Interval,
                s => s,
            };
            place(shape, Some(from), Some(to), grade)
        }
        Reference::None => UNRESOLVED,
    }
}

/// 计算已收到的解释;每条解释使用它自己的章节上下文。
fn resolve_interpretations(
    interpretations: &[Interpretation],
    context_for: impl Fn(i64) -> DocumentDating,
) -> HashMap<i64, Resolved> {
    let mut resolved = HashMap::new();
    let mut pending: Vec<&Interpretation> = interpretations.iter().collect();
    while !pending.is_empty() {
        let before = pending.len();
        pending.retain(|interp| {
            let r = resolve_one(interp, &context_for(interp.id), &resolved);
            if r == UNRESOLVED {
                return true;
            }
            resolved.insert(interp.id, r);
            false
        });
        // 每轮至少解开一条才继续;循环、自引用、缺失或不可用的锚点都在无进展时留下 C。
        // 不能固定遍数:模型回复可以把任意长的依赖链倒着写。
        if pending.len() == before {
            break;
        }
    }
    for interp in pending {
        resolved.insert(interp.id, UNRESOLVED);
    }
    resolved
}

/// 算的时候文档的日期换成提及所在那一节的起算点。
fn context_at(context: &DocumentDating, now: Option<usize>) -> DocumentDating {
    let mut scoped = context.clone();
    if let Some(entry) = now.and_then(|i| context.entries.get(i)) {
        scoped.date = Some(entry.from.clone());
        scoped.date_words = Some(entry.words.clone());
    }
    scoped
}

/// 推送的陈述把 `when` / `ended` 写成完整日期或带区时刻时,这里就把它读成一条解释
/// (#1089;0045 决定 8:结构化的时间戳不是时间词)。形状是点、参照是照写的绝对值、
/// 粒度是字写到的那一级——与模型对同样的字该给的回答一致。`from` 存换算成 UTC 后的
/// 部件:`DateParts` 不带区,偏移在 `parse_time` 里已经折进值里;存 UTC 部件的解释
/// 再算一遍得到同一个值,存原样的本地钟点反而会读出另一个时刻。
///
/// 只收 `parse_time` 读到「日」或更细的:`YYYY-MM-DD` 与带 `Z` 或偏移的
/// `YYYY-MM-DDTHH[:MM[:SS]]`。光杆的年、年月、以及任何读不动的字都回 `None`,
/// 照旧走模型那条路——这一刀不替代码认时间词。
fn stated_reading(text: &str, id: i64) -> Option<Interpretation> {
    let (t, precision) = utopia_extract::parse_time(text)?;
    use chrono::{Datelike, Timelike};
    let (granularity, hour, minute, second) = match precision {
        "day" => (Granularity::Day, None, None, None),
        "hour" => (Granularity::Hour, Some(t.hour()), None, None),
        "minute" => (Granularity::Minute, Some(t.hour()), Some(t.minute()), None),
        "second" => (
            Granularity::Second,
            Some(t.hour()),
            Some(t.minute()),
            Some(t.second()),
        ),
        // 光杆的年、年月不在这刀里(#1089 的界),退回 None 让模型读
        _ => return None,
    };
    Some(Interpretation {
        id,
        shape: Shape::Point,
        reference: Reference::Absolute {
            from: DateParts {
                year: t.year(),
                quarter: None,
                month: Some(t.month()),
                day: Some(t.day()),
                hour,
                minute,
                second,
            },
            to: None,
        },
        granularity,
    })
}

/// 一条陈述的起与止:`when` 给起(点与区间也给止),`ended` 给止。
fn combine(when: Option<Resolved>, ended: Option<Resolved>) -> Resolved {
    let mut r = when.unwrap_or(UNRESOLVED);
    if let Some(e) = ended {
        let to = e.to.or(e.from);
        let to_p = e.to_p.or(e.from_p);
        if to.is_some() || to_p.is_some() {
            r.to = to;
            r.to_p = to_p;
        }
        if r.grade == "C" {
            r.grade = e.grade;
        }
    }
    r
}

/// 解析一篇文档的全部时间提及(任务 `resolve_time`)。幂等:再跑一次覆盖上一次的结果,
/// 所以锚点晚到(改了文档日期、后一块给了期间)时重排一次即可(决定 4 的第一步)
pub async fn resolve_document(state: &AppState, document_id: Uuid) -> anyhow::Result<()> {
    let pool = &state.pool;
    let doc = utopia_store::documents::get(pool, document_id).await?;
    if doc.deleted_at.is_some() {
        return Ok(());
    }
    let kb = utopia_store::kbs::get(pool, doc.kb_id).await?;
    let settings = utopia_store::settings::get(pool, kb.workspace_id).await?;
    let client = settings.as_ref().and_then(llm_util::chat_client);
    // 推送来的陈述(0054):`when` / `ended` 写的完整日期或带区时刻由代码直接读(#1089),
    // 没有对话模型也照常解;别的文档照旧——没有对话模型,这一步就没有替它读字的人
    let pushed = crate::pipeline::source_kind(state, doc.source_id)
        .await?
        .as_deref()
        == Some("statements");
    if !pushed && client.is_none() {
        anyhow::bail!("Chat model not configured; cannot resolve time");
    }

    // 1. 文档时间上下文:抽取时各块报上来的(0064)。这里不问模型
    let context: DocumentDating = match doc.time_context.clone() {
        Some(json) => {
            let context: DocumentDating = serde_json::from_value(json)?;
            // 整篇的起算点照旧记成文档的日期(文库排序、引擎给没起点的行排次序都读它)
            if crate::extraction_open::dated_at(&doc).is_none() {
                if let Some((t, _)) = context.date.as_ref().and_then(parts_to_time) {
                    utopia_store::documents::set_content_date(pool, document_id, t).await?;
                }
            }
            context
        }
        // 抽取一条日期都没报:文档没说自己是哪天的。不再另问一次开头(0064 决定 1)——
        // 那一次调用在抽取报了「没有」的文档上问的是同一个问题,测量里二十篇有十六篇这样
        // 白问;文档里写了日期的,抽取都报上来了
        None => DocumentDating::default(),
    };

    // 这一刀之前读开头定出来、存在文档上的日期(只有日期、没有条目):它就是整篇的起算点,
    // 和抽取报上来的一样进条目里,下面给陈述作证、给相对的时间词当基准都从条目里找
    let mut context = context;
    if context.entries.is_empty() {
        if let (Some(date), Some(words)) = (context.date.clone(), context.date_words.clone()) {
            context.entries.push(utopia_extract::time::TimeEntry {
                kind: "now".into(),
                name: String::new(),
                words,
                from: date,
                to: None,
                scope: Vec::new(),
                chunk: None,
                char_start: None,
            });
        }
    }
    attest_statements(state, &doc, &context).await?;

    // 抽取报上来的期间(0064)并进文档命名的期间里:解释时按名字指它
    for e in context
        .entries
        .clone()
        .iter()
        .filter(|e| e.kind == "period")
    {
        let name = if e.name.is_empty() { &e.words } else { &e.name };
        if let (Some(to), false) = (
            e.to.clone(),
            context
                .periods
                .iter()
                .any(|p| p.name.eq_ignore_ascii_case(name)),
        ) {
            context.periods.push(NamedPeriod {
                name: name.clone(),
                from: e.from.clone(),
                to,
            });
        }
    }
    let context = context;

    // 2. 提及:同一篇里同样的字在同样的句子里只解释一次
    let mentions = utopia_store::time_mentions::for_document(pool, document_id).await?;
    if mentions.is_empty() {
        return Ok(());
    }
    // 每条提及所在的那一节里管事的起算点(0064 决定 4):从它那一块正文里的标题读出所在的
    // 节,再在文档报上来的日期里找范围最深的那个 `now`。一篇文档里两份周报各有各的提报日,
    // 「上周」在哪一节就从哪一节的日期起算。没有条目的文档(老的、推送来的)照旧用文档的日期
    let chunk_text: HashMap<Uuid, String> =
        sqlx::query_as::<_, (Uuid, String)>("SELECT id, text FROM chunks WHERE document_id = $1")
            .bind(document_id)
            .fetch_all(pool)
            .await?
            .into_iter()
            .collect();
    let now_of = |m: &utopia_store::time_mentions::MentionToResolve| -> Option<usize> {
        let text = chunk_text.get(&m.chunk_id)?;
        let path = headings_at(text, usize::try_from(m.char_start).unwrap_or(0));
        let found = now_in_force(&context.entries, &path)?;
        context.entries.iter().position(|e| std::ptr::eq(e, found))
    };
    type Key = (String, String, Option<usize>);
    let mut distinct: Vec<Key> = Vec::new();
    let mut index: HashMap<Key, usize> = HashMap::new();
    let mut key_of: HashMap<Uuid, Key> = HashMap::new();
    // 推送来的陈述(0054):载荷写的完整日期或带区时刻由代码读成解释(#1089)。
    // 解释与别的提及同去同回,只是它从不进问模型的清单——重问也只能是这个答案,
    // 代码读过的不许模型盖掉;判据是文档来自 `statements` 来源,不是字长得像日期,
    // 普通文档里同样的字照旧交给模型
    let mut presolved: HashMap<usize, Interpretation> = HashMap::new();
    for m in &mentions {
        let key = (m.text.clone(), m.sentence.clone(), now_of(m));
        key_of.insert(m.id, key.clone());
        if index.contains_key(&key) {
            continue;
        }
        index.insert(key.clone(), distinct.len());
        distinct.push(key);
        if pushed {
            if let Some(interp) = stated_reading(&m.text, (distinct.len() - 1) as i64) {
                presolved.insert(distinct.len() - 1, interp);
            }
        }
    }
    let ctx = TimeContext {
        date: context.date.as_ref(),
        date_words: context.date_words.as_deref(),
        periods: &context.periods,
        fiscal_year_end: context.fiscal_year_end,
    };
    let mut interpretations: Vec<Interpretation> = presolved.values().cloned().collect();
    let mut received = HashSet::new();
    let mut malformed = 0usize;
    // 问两轮:第一轮全部,第二轮只问第一轮没答到的。模型漏答的提及从前就留着字、没有解释,
    // 也没有人再问(测量台上的「上周」三遍都是这样)。代码已经读出答案的不问
    let mut todo: Vec<usize> = (0..distinct.len())
        .filter(|i| !presolved.contains_key(i))
        .collect();
    if let (Some(settings), Some(client)) = (settings.as_ref(), client.as_ref()) {
        for round in 0..2 {
            if round == 1 {
                todo.retain(|i| !received.contains(&(*i as i64)));
                if todo.is_empty() {
                    break;
                }
                tracing::info!(%document_id, unanswered = todo.len(), "时间解释有没答到的,再问一次");
            }
            for batch in todo.clone().chunks(BATCH) {
                let inputs: Vec<MentionInput<'_>> = batch
                    .iter()
                    .map(|&i| MentionInput {
                        id: i as i64,
                        text: &distinct[i].0,
                        sentence: &distinct[i].1,
                    })
                    .collect();
                let ids: Vec<i64> = inputs.iter().map(|m| m.id).collect();
                let messages = build_interpretation_messages(&ctx, &inputs);
                let reply = match chat_retrying_rate_limits_at(
                    state,
                    settings,
                    client,
                    &messages,
                    Some(0.0),
                )
                .await
                {
                    Ok(r) => r,
                    Err(e) => {
                        tracing::warn!(%document_id, error = %e, "时间解释调用失败,这一批留作未解析");
                        continue;
                    }
                };
                let (interps, skipped) = match parse_interpretation_response(&reply.text, &ids) {
                    Ok(x) => x,
                    Err(e) => {
                        tracing::warn!(%document_id, error = %e, "时间解释回复解析失败,这一批留作未解析");
                        continue;
                    }
                };
                malformed += skipped;
                if skipped > 0 {
                    // 坏条目要看得见是哪一条、坏在哪:只报一个数的话,「上周」三遍都没日期也查不出原因
                    tracing::warn!(%document_id, skipped, reply = %reply.text.chars().take(600).collect::<String>(), "时间解释里有读不了的条目");
                }
                received.extend(interps.iter().map(|interp| interp.id));
                interpretations.extend(interps);
            }
        }
    }
    // 收到解释和算出日期是两件事:补答只问没收到的,计算则看全部批次和补答里的解释。
    // 这样下游不用再问模型,也能用上后一批或补答才给出的锚点。
    let computed = resolve_interpretations(&interpretations, |id| {
        let now = usize::try_from(id)
            .ok()
            .and_then(|i| distinct.get(i))
            .and_then(|key| key.2);
        context_at(&context, now)
    });
    let mut resolved: HashMap<usize, (Interpretation, Resolved)> = HashMap::new();
    for interp in interpretations {
        if let Ok(i) = usize::try_from(interp.id) {
            let r = computed[&interp.id];
            resolved.insert(i, (interp, r));
        }
    }

    // 3. 写回提及,再按陈述合起止
    let mut per_fact: HashMap<Uuid, (Option<Resolved>, Option<Resolved>)> = HashMap::new();
    let (mut a, mut b, mut c) = (0usize, 0usize, 0usize);
    for m in &mentions {
        let Some(&i) = key_of.get(&m.id).and_then(|k| index.get(k)) else {
            continue;
        };
        let Some((interp, r)) = resolved.get(&i) else {
            // 推送的文档没有对话模型可问(#1089):代码读不动的提及按 C 记——「有提及、
            // 没能放上轴」和「没有时间词」要分得出;任务照常收工,不因一个没配的模型
            // 留下永远失败的任务。解释列留空:没有人读过它,不编一条出来
            if pushed && client.is_none() {
                utopia_store::time_mentions::set_resolution(
                    pool, m.id, "C", None, None, None, None,
                )
                .await?;
                c += 1;
                let slot = per_fact.entry(m.fact_id).or_insert((None, None));
                if m.role == "ended" {
                    slot.1 = Some(UNRESOLVED);
                } else {
                    slot.0 = Some(UNRESOLVED);
                }
            }
            // 有模型而没答到的:留着字,不写等级(下次重跑再问)
            continue;
        };
        utopia_store::time_mentions::set_interpretation(
            pool,
            m.id,
            serde_json::to_value(interp.shape)?
                .as_str()
                .unwrap_or("point"),
            &serde_json::to_value(&interp.reference)?,
            granularity_str(interp.granularity),
        )
        .await?;
        utopia_store::time_mentions::set_resolution(
            pool, m.id, r.grade, r.from, r.from_p, r.to, r.to_p,
        )
        .await?;
        match r.grade {
            "A" => a += 1,
            "B" => b += 1,
            _ => c += 1,
        }
        let slot = per_fact.entry(m.fact_id).or_insert((None, None));
        if m.role == "ended" {
            slot.1 = Some(*r);
        } else {
            slot.0 = Some(*r);
        }
    }
    let mut dated = 0usize;
    for (fact_id, (when, ended)) in per_fact {
        let r = combine(when, ended);
        // 起点的等级只看起点那条提及。combine 在起点锚不到时借结束端的等级来报数,
        // 这里不借:引擎问的是「这一行的起点是怎么来的」(0045 第 3 刀)
        let grade = when.map(|w| w.grade);
        let placed = r.from.is_some() || r.to.is_some() || r.to_p.is_some();
        // 什么都没算出来也要写等级 C:只有这一列说得出「这句话有时间词、我们没能把它
        // 放到轴上」,否则它和「整句没有时间词」在库里长得一模一样
        if !placed && grade != Some("C") {
            continue;
        }
        utopia_store::graph::set_open_validity(
            pool, fact_id, r.from, r.from_p, r.to, r.to_p, grade,
        )
        .await?;
        if placed {
            dated += 1;
        }
    }
    tracing::info!(
        %document_id,
        mentions = mentions.len(),
        grade_a = a,
        grade_b = b,
        grade_c = c,
        malformed,
        statements_dated = dated,
        "时间提及解析完成"
    );
    if dated > 0 {
        state.emit_graph(doc.kb_id);
    }
    Ok(())
}

/// 见证的名字:日期的名字加它的字(「提报日期 2026年9月4日」)。没有名字的光是字;封面上
/// 一个光秃秃的日期,模型常把日期自己又填成名字,那就只写一遍
fn witness_name(name: &str, words: &str) -> String {
    let (name, words) = (name.trim(), words.trim());
    if name.is_empty() || name == words {
        words.to_string()
    } else {
        format!("{name} {words}")
    }
}

/// 这篇文档的陈述各由它所在那一节里文本说话的那一刻作证(0064 决定 3)。
///
/// 一条陈述在哪一节,看它的引文在它那一块里的位置、那一块正文里的标题;管着它的是范围
/// 最深的那个 `now`。没有的不写——见证留空,这条陈述在任何时点都成立(决定 5)。
/// 这是「截至」,不是起点:报告里的「所属市场为全球」说的是那天是这样,不是从那天起
async fn attest_statements(
    state: &AppState,
    doc: &utopia_core::models::Document,
    context: &DocumentDating,
) -> anyhow::Result<()> {
    let pool = &state.pool;
    if !context.entries.iter().any(|e| e.kind == "now") {
        // 这一遍文档一条日期都没说:上一遍记在证据上的也不算数了
        sqlx::query(
            "UPDATE fact_evidence SET attested_at = NULL, attested_by = NULL
              WHERE document_id = $1 AND attested_at IS NOT NULL",
        )
        .bind(doc.id)
        .execute(pool)
        .await?;
        return Ok(());
    }
    let rows: Vec<(Uuid, Uuid, String, Option<i32>)> = sqlx::query_as(
        "SELECT fe.fact_id, fe.chunk_id, c.text, fe.quote_start
           FROM fact_evidence fe
           JOIN facts f ON f.id = fe.fact_id
           JOIN chunks c ON c.id = fe.chunk_id
          WHERE fe.document_id = $1 AND c.superseded_at IS NULL
            AND f.layer = 'open' AND f.invalidated_at IS NULL",
    )
    .bind(doc.id)
    .fetch_all(pool)
    .await?;
    let mut moved = 0usize;
    for (fact_id, chunk_id, text, start) in rows {
        let path = headings_at(&text, usize::try_from(start.unwrap_or(0)).unwrap_or(0));
        let witness = now_in_force(&context.entries, &path).and_then(|now| {
            let (at, _) = parts_to_time(&now.from)?;
            Some((at, witness_name(&now.name, &now.words)))
        });
        // 每条证据记下自己这一节的日期(没说的记成空):事实上只留最早的那一个,证据所在
        // 的文档删了之后要照还在的证据重算,得知道每一条各是哪天
        utopia_store::graph::witness_evidence(
            pool,
            fact_id,
            chunk_id,
            witness.as_ref().map(|(at, by)| (*at, by.as_str())),
        )
        .await?;
        let Some((at, by)) = witness else {
            continue;
        };
        if utopia_store::graph::attest_statement(pool, fact_id, at, &by).await? {
            moved += 1;
        }
    }
    // 已经物化出来的、规则算出来的类型化行跟着它们的陈述走
    let typed = utopia_store::materialize::sync_typed_attestation(pool, doc.kb_id, None).await?;
    // 见证动了的行换了它在唯一性时间线上的位置:只把这些行所在的时间线重算一遍,不是整个库
    // ——每篇文档都把全库的时间线各开一个事务重算一遍,库一大就是每篇几千个事务。
    // 先提交同步,再拿时间线锁,不在持有 UPDATE 行锁时等咨询锁(与物化提交后对账的顺序一致)
    let reconciled = utopia_store::temporal::reconcile_moved_facts(pool, doc.kb_id, &typed).await?;
    let typed = typed.len();
    if moved > 0 || typed > 0 {
        tracing::info!(document_id = %doc.id, statements = moved, typed,
            corrected = reconciled.corrected.len(), conflicts = reconciled.conflicts,
            "陈述按它所在那一节的日期作了证");
        state.emit_graph(doc.kb_id);
    }
    Ok(())
}

#[cfg(test)]
#[path = "time_context_tests.rs"]
mod context_tests;

#[cfg(test)]
#[path = "time_attestation_tests.rs"]
mod attestation_tests;

#[cfg(test)]
#[path = "time_resolution_pushed_tests.rs"]
mod pushed_tests;

#[cfg(test)]
mod tests {
    use super::*;

    /// 推送载荷里写明的值(#1089):完整日期与带区时刻读成点状绝对解释,精度随字;
    /// 光杆的年、年月、读不动的字都回 None——不替代码认时间词
    #[test]
    fn a_stated_value_reads_at_the_precision_it_writes() {
        let read = |s: &str| {
            let interp = stated_reading(s, 0)?;
            let Reference::Absolute { from, to } = interp.reference else {
                return None;
            };
            assert_eq!(interp.shape, Shape::Point);
            assert!(to.is_none());
            Some((from, interp.granularity))
        };
        let date = |y, m, d, h, mi, s| DateParts {
            year: y,
            quarter: None,
            month: Some(m),
            day: Some(d),
            hour: h,
            minute: mi,
            second: s,
        };
        assert_eq!(
            read("2026-09-23"),
            Some((date(2026, 9, 23, None, None, None), Granularity::Day))
        );
        assert_eq!(
            read("2026-09-23T08Z"),
            Some((date(2026, 9, 23, Some(8), None, None), Granularity::Hour))
        );
        assert_eq!(
            read("2026-09-23T08:14Z"),
            Some((
                date(2026, 9, 23, Some(8), Some(14), None),
                Granularity::Minute
            ))
        );
        assert_eq!(
            read("2026-09-23T08:14:03Z"),
            Some((
                date(2026, 9, 23, Some(8), Some(14), Some(3)),
                Granularity::Second
            ))
        );
        // 偏移折进值里:+08:00 的 08:14 是 UTC 的 00:14
        assert_eq!(
            read("2026-09-23T08:14:03+08:00"),
            Some((
                date(2026, 9, 23, Some(0), Some(14), Some(3)),
                Granularity::Second
            ))
        );
        // 这一刀之外的字:光杆的年、年月、自然语言
        for s in ["2026", "2026-09", "last Tuesday", "ended", ""] {
            assert!(read(s).is_none(), "{s:?} is not code-resolved");
        }
    }

    #[test]
    fn a_bare_date_is_named_once() {
        assert_eq!(
            witness_name("提报日期", "2026年9月4日"),
            "提报日期 2026年9月4日"
        );
        assert_eq!(witness_name("", "2024年10月10日"), "2024年10月10日");
        assert_eq!(
            witness_name("2024年10月10日", " 2024年10月10日"),
            "2024年10月10日"
        );
    }
    use utopia_extract::time::NamedPeriod;

    fn parts(y: i32, m: Option<u32>, d: Option<u32>) -> DateParts {
        DateParts {
            quarter: None,
            year: y,
            month: m,
            day: d,
            hour: None,
            minute: None,
            second: None,
        }
    }
    fn at(s: &str) -> DateTime<Utc> {
        DateTime::parse_from_rfc3339(s).unwrap().with_timezone(&Utc)
    }
    fn ctx_dated(y: i32, m: u32, d: u32) -> DocumentDating {
        DocumentDating {
            entries: Vec::new(),
            date: Some(parts(y, Some(m), Some(d))),
            date_words: Some("x".into()),
            periods: vec![NamedPeriod {
                name: "fiscal 2027".into(),
                from: parts(2026, Some(1), Some(26)),
                to: parts(2027, Some(1), Some(25)),
            }],
            fiscal_year_end: Some((1, 25)),
            skipped: 0,
        }
    }

    fn day_point(date: &str, grade: &'static str) -> Resolved {
        Resolved {
            from: Some(at(date)),
            from_p: Some("day"),
            to: Some(at(date)),
            to_p: Some("day"),
            grade,
        }
    }

    fn absolute_day(id: i64) -> Interpretation {
        Interpretation {
            id,
            shape: Shape::Point,
            reference: Reference::Absolute {
                from: parts(2024, Some(1), Some(1)),
                to: None,
            },
            granularity: Granularity::Day,
        }
    }

    fn next_day(id: i64, anchor_id: i64) -> Interpretation {
        Interpretation {
            reference: Reference::Anchored {
                anchor: Anchor::Mention { id: anchor_id },
                offset: Some(Offset {
                    count: 1,
                    unit: Unit::Day,
                    direction: Direction::After,
                }),
            },
            ..absolute_day(id)
        }
    }

    #[test]
    fn mention_dependencies_resolve_in_all_reply_orders() {
        let items = [
            serde_json::json!([0, "point", {"kind": "absolute", "from": {"y": 2024, "m": 1, "d": 1}}, "day"]),
            serde_json::json!([1, "point", {"kind": "anchored", "anchor": {"kind": "mention", "id": 0}, "offset": {"count": 1, "unit": "day", "direction": "after"}}, "day"]),
            serde_json::json!([2, "point", {"kind": "anchored", "anchor": {"kind": "mention", "id": 1}, "offset": {"count": 1, "unit": "day", "direction": "after"}}, "day"]),
        ];
        let expected = HashMap::from([
            (0, day_point("2024-01-01T00:00:00Z", "A")),
            (1, day_point("2024-01-02T00:00:00Z", "B")),
            (2, day_point("2024-01-03T00:00:00Z", "B")),
        ]);
        for order in [
            [0, 1, 2],
            [0, 2, 1],
            [1, 0, 2],
            [1, 2, 0],
            [2, 0, 1],
            [2, 1, 0],
        ] {
            let reply = serde_json::json!({"m": order.map(|i| items[i].clone())});
            let (interpretations, skipped) =
                parse_interpretation_response(&reply.to_string(), &[0, 1, 2]).unwrap();
            assert_eq!(skipped, 0);
            assert_eq!(interpretations.len(), 3);
            let resolved = resolve_interpretations(&interpretations, |_| DocumentDating::default());
            assert_eq!(resolved, expected, "reply order: {order:?}");
        }
    }

    #[test]
    fn a_long_reverse_chain_does_not_follow_numeric_ids_or_a_fixed_pass_limit() {
        // 编号上下交错,与依赖次序无关;链长也超过一批的大小。
        let ids: Vec<i64> = (0..81).map(|depth| 500 + (depth * 37) % 101).collect();
        let mut interpretations = vec![absolute_day(ids[0])];
        for pair in ids.windows(2) {
            interpretations.push(next_day(pair[1], pair[0]));
        }
        interpretations.reverse();
        let resolved = resolve_interpretations(&interpretations, |_| DocumentDating::default());
        assert_eq!(resolved.len(), ids.len());
        for (depth, id) in ids.iter().enumerate() {
            let date = at("2024-01-01T00:00:00Z") + Duration::days(depth as i64);
            assert_eq!(
                resolved[id],
                Resolved {
                    from: Some(date),
                    from_p: Some("day"),
                    to: Some(date),
                    to_p: Some("day"),
                    grade: if depth == 0 { "A" } else { "B" },
                },
                "depth {depth}, id {id}"
            );
        }
    }

    #[test]
    fn independent_chains_resolve_while_cycles_and_missing_anchors_stay_unresolved() {
        let second_root = Interpretation {
            reference: Reference::Absolute {
                from: parts(2025, Some(6), Some(10)),
                to: None,
            },
            ..absolute_day(20)
        };
        let interpretations = [
            next_day(2, 1),
            next_day(30, 30), // 自引用
            next_day(31, 32),
            next_day(32, 31),  // 循环
            next_day(33, 999), // 缺失的解释
            next_day(34, 31),  // 依赖循环的下游
            next_day(22, 21),
            next_day(1, 0),
            next_day(21, 20),
            second_root,
            absolute_day(0),
        ];
        let resolved = resolve_interpretations(&interpretations, |_| ctx_dated(2030, 1, 1));
        assert_eq!(
            resolved,
            HashMap::from([
                (0, day_point("2024-01-01T00:00:00Z", "A")),
                (1, day_point("2024-01-02T00:00:00Z", "B")),
                (2, day_point("2024-01-03T00:00:00Z", "B")),
                (20, day_point("2025-06-10T00:00:00Z", "A")),
                (21, day_point("2025-06-11T00:00:00Z", "B")),
                (22, day_point("2025-06-12T00:00:00Z", "B")),
                (30, UNRESOLVED),
                (31, UNRESOLVED),
                (32, UNRESOLVED),
                (33, UNRESOLVED),
                (34, UNRESOLVED),
            ])
        );
    }

    #[test]
    fn received_interpretations_can_use_anchors_from_later_batches_and_the_makeup_reply() {
        let first_reply = r#"{"m": [
            [2, "point", {"kind": "anchored", "anchor": {"kind": "mention", "id": 1}, "offset": {"count": 1, "unit": "day", "direction": "after"}}, "day"],
            [1, "point", {"kind": "anchored", "anchor": {"kind": "mention", "id": 40}, "offset": {"count": 1, "unit": "day", "direction": "after"}}, "day"]
        ]}"#;
        let (mut interpretations, skipped) =
            parse_interpretation_response(first_reply, &[0, 1, 2]).unwrap();
        assert_eq!(skipped, 0);
        let before = resolve_interpretations(&interpretations, |_| DocumentDating::default());
        assert_eq!(before, HashMap::from([(1, UNRESOLVED), (2, UNRESOLVED)]));
        assert!(!before.contains_key(&0), "未回答与已回答但未解析的提及不同");

        let later_batch = r#"{"m": [
            [40, "point", {"kind": "anchored", "anchor": {"kind": "mention", "id": 0}, "offset": {"count": 1, "unit": "day", "direction": "after"}}, "day"]
        ]}"#;
        let (later, skipped) = parse_interpretation_response(later_batch, &[40]).unwrap();
        assert_eq!(skipped, 0);
        interpretations.extend(later);
        let still_waiting =
            resolve_interpretations(&interpretations, |_| DocumentDating::default());
        assert_eq!(still_waiting[&2], UNRESOLVED);

        let makeup_reply = r#"{"m": [
            [0, "point", {"kind": "absolute", "from": {"y": 2024, "m": 1, "d": 1}}, "day"]
        ]}"#;
        let (makeup, skipped) = parse_interpretation_response(makeup_reply, &[0]).unwrap();
        assert_eq!(skipped, 0);
        interpretations.extend(makeup);
        let after = resolve_interpretations(&interpretations, |_| DocumentDating::default());
        assert_eq!(
            after,
            HashMap::from([
                (0, day_point("2024-01-01T00:00:00Z", "A")),
                (40, day_point("2024-01-02T00:00:00Z", "B")),
                (1, day_point("2024-01-03T00:00:00Z", "B")),
                (2, day_point("2024-01-04T00:00:00Z", "B")),
            ])
        );
    }

    #[test]
    fn dependency_resolution_keeps_each_mentions_section_context() {
        let mut context = ctx_dated(2030, 1, 1);
        for (section, year) in [("First report", 2024), ("Second report", 2025)] {
            context.entries.push(utopia_extract::time::TimeEntry {
                kind: "now".into(),
                name: String::new(),
                words: year.to_string(),
                from: parts(year, Some(1), Some(1)),
                to: None,
                scope: vec![section.into()],
                chunk: None,
                char_start: None,
            });
        }
        let document_anchor = |id| Interpretation {
            reference: Reference::Anchored {
                anchor: Anchor::Document,
                offset: None,
            },
            ..absolute_day(id)
        };
        // 偶数在第一节,奇数在第二节;两条链各自从本节日期起算。
        let interpretations = [
            next_day(4, 2),
            next_day(5, 3),
            next_day(2, 0),
            next_day(3, 1),
            document_anchor(1),
            document_anchor(0),
        ];
        let resolved = resolve_interpretations(&interpretations, |id| {
            context_at(&context, Some((id % 2) as usize))
        });
        assert_eq!(
            resolved,
            HashMap::from([
                (0, day_point("2024-01-01T00:00:00Z", "B")),
                (2, day_point("2024-01-02T00:00:00Z", "B")),
                (4, day_point("2024-01-03T00:00:00Z", "B")),
                (1, day_point("2025-01-01T00:00:00Z", "B")),
                (3, day_point("2025-01-02T00:00:00Z", "B")),
                (5, day_point("2025-01-03T00:00:00Z", "B")),
            ])
        );
    }

    #[test]
    fn dependency_resolution_preserves_dateless_endings_and_unusable_anchors() {
        let interpretations = [
            next_day(1, 0),
            Interpretation {
                shape: Shape::Until,
                ..absolute_day(0)
            },
            next_day(3, 2),
            Interpretation {
                shape: Shape::EndedUnknown,
                ..next_day(2, 2)
            },
        ];
        let resolved = resolve_interpretations(&interpretations, |_| DocumentDating::default());
        assert_eq!(
            resolved,
            HashMap::from([
                (
                    0,
                    Resolved {
                        from: None,
                        from_p: None,
                        ..day_point("2024-01-01T00:00:00Z", "A")
                    }
                ),
                (1, UNRESOLVED),
                (
                    2,
                    Resolved {
                        to_p: Some(ENDED_UNKNOWN),
                        grade: "A",
                        ..UNRESOLVED
                    }
                ),
                (3, UNRESOLVED),
            ])
        );
    }

    #[test]
    fn parts_give_the_precision_the_words_state() {
        assert_eq!(parts_to_time(&parts(2024, None, None)).unwrap().1, "year");
        assert_eq!(
            parts_to_time(&parts(2024, Some(3), None)).unwrap().1,
            "month"
        );
        let (t, p) = parts_to_time(&parts(2011, Some(3), Some(4))).unwrap();
        assert_eq!((t, p), (at("2011-03-04T00:00:00Z"), "day"));
        assert!(parts_to_time(&parts(2024, Some(13), None)).is_none());
    }

    #[test]
    fn an_absolute_date_is_grade_a_and_a_point_has_two_equal_ends() {
        let i = Interpretation {
            id: 0,
            shape: Shape::Point,
            reference: Reference::Absolute {
                from: parts(2011, Some(3), Some(4)),
                to: None,
            },
            granularity: Granularity::Day,
        };
        let r = resolve_one(&i, &ctx_dated(2026, 9, 2), &HashMap::new());
        assert_eq!(r.grade, "A");
        assert_eq!(r.from, Some(at("2011-03-04T00:00:00Z")));
        assert_eq!(r.to, r.from);
        assert_eq!((r.from_p, r.to_p), (Some("day"), Some("day")));
    }

    #[test]
    fn a_bare_year_stays_a_year_even_if_the_model_says_day() {
        let i = Interpretation {
            id: 0,
            shape: Shape::Since,
            reference: Reference::Absolute {
                from: parts(1987, None, None),
                to: None,
            },
            granularity: Granularity::Day,
        };
        let r = resolve_one(&i, &ctx_dated(2026, 9, 2), &HashMap::new());
        assert_eq!(
            (r.from, r.from_p, r.to),
            (Some(at("1987-01-01T00:00:00Z")), Some("year"), None)
        );
    }

    #[test]
    fn today_and_last_year_anchor_to_the_document_as_grade_b() {
        let today = Interpretation {
            id: 0,
            shape: Shape::Point,
            reference: Reference::Anchored {
                anchor: Anchor::Document,
                offset: None,
            },
            granularity: Granularity::Day,
        };
        let r = resolve_one(&today, &ctx_dated(2026, 9, 2), &HashMap::new());
        assert_eq!((r.grade, r.from), ("B", Some(at("2026-09-02T00:00:00Z"))));
        let last_year = Interpretation {
            id: 1,
            shape: Shape::Interval,
            reference: Reference::Anchored {
                anchor: Anchor::Document,
                offset: Some(Offset {
                    count: 1,
                    unit: Unit::Year,
                    direction: Direction::Before,
                }),
            },
            granularity: Granularity::Year,
        };
        let r = resolve_one(&last_year, &ctx_dated(2026, 9, 2), &HashMap::new());
        assert_eq!(
            (r.grade, r.from, r.from_p),
            ("B", Some(at("2025-01-01T00:00:00Z")), Some("year"))
        );
        // 没有文档日期就锚不到
        let undated = DocumentDating::default();
        assert_eq!(resolve_one(&today, &undated, &HashMap::new()), UNRESOLVED);
    }

    #[test]
    fn a_named_period_is_an_interval_from_the_context() {
        let i = Interpretation {
            id: 0,
            shape: Shape::Point,
            reference: Reference::Period {
                name: "Fiscal 2027".into(),
                from: None,
                to: None,
            },
            granularity: Granularity::Day,
        };
        let r = resolve_one(&i, &ctx_dated(2026, 9, 2), &HashMap::new());
        assert_eq!(r.grade, "B");
        assert_eq!(r.from, Some(at("2026-01-26T00:00:00Z")));
        assert_eq!(r.to, Some(at("2027-01-25T00:00:00Z")));
        // 文中自己写了起止的期间是 A 级
        let stated = Interpretation {
            reference: Reference::Period {
                name: "three months ended July 26, 2026".into(),
                from: Some(parts(2026, Some(4), Some(27))),
                to: Some(parts(2026, Some(7), Some(26))),
            },
            ..i
        };
        assert_eq!(
            resolve_one(&stated, &DocumentDating::default(), &HashMap::new()).grade,
            "A"
        );
    }

    #[test]
    fn a_stated_quarter_is_the_three_months_it_names() {
        let i = Interpretation {
            id: 0,
            shape: Shape::Point,
            reference: Reference::Absolute {
                from: DateParts {
                    quarter: Some(3),
                    ..parts(2025, None, None)
                },
                to: None,
            },
            granularity: Granularity::Month,
        };
        let r = resolve_one(&i, &DocumentDating::default(), &HashMap::new());
        assert_eq!(r.grade, "A");
        assert_eq!(r.from, Some(at("2025-07-01T00:00:00Z")));
        assert_eq!(r.from_p, Some("month"));
        assert_eq!(r.to, Some(at("2025-09-01T00:00:00Z")));
        assert_eq!(r.to_p, Some("month"));
    }

    #[test]
    fn two_years_later_follows_the_mention_it_names() {
        let mut earlier = HashMap::new();
        earlier.insert(
            7,
            Resolved {
                from: Some(at("2019-01-01T00:00:00Z")),
                from_p: Some("year"),
                to: Some(at("2019-01-01T00:00:00Z")),
                to_p: Some("year"),
                grade: "A",
            },
        );
        let i = Interpretation {
            id: 8,
            shape: Shape::Point,
            reference: Reference::Anchored {
                anchor: Anchor::Mention { id: 7 },
                offset: Some(Offset {
                    count: 2,
                    unit: Unit::Year,
                    direction: Direction::After,
                }),
            },
            granularity: Granularity::Year,
        };
        let r = resolve_one(&i, &DocumentDating::default(), &earlier);
        assert_eq!(
            (r.grade, r.from, r.from_p),
            ("B", Some(at("2021-01-01T00:00:00Z")), Some("year"))
        );
    }

    #[test]
    fn an_ending_without_a_date_and_a_when_plus_ended_combine() {
        let ended = Interpretation {
            id: 0,
            shape: Shape::EndedUnknown,
            reference: Reference::None,
            granularity: Granularity::Day,
        };
        let e = resolve_one(&ended, &DocumentDating::default(), &HashMap::new());
        assert_eq!((e.to, e.to_p, e.grade), (None, Some(ENDED_UNKNOWN), "A"));
        let since = Resolved {
            from: Some(at("2020-01-01T00:00:00Z")),
            from_p: Some("year"),
            to: None,
            to_p: None,
            grade: "A",
        };
        let until = Resolved {
            from: Some(at("2024-06-01T00:00:00Z")),
            from_p: Some("month"),
            to: None,
            to_p: None,
            grade: "A",
        };
        let r = combine(Some(since), Some(until));
        assert_eq!(
            (r.from, r.to, r.to_p),
            (since.from, until.from, Some("month"))
        );
        assert_eq!(combine(None, Some(e)).to_p, Some(ENDED_UNKNOWN));
    }

    #[test]
    fn this_quarter_is_the_whole_quarter_and_the_fiscal_calendar_moves_it() {
        let this_quarter = Interpretation {
            id: 0,
            shape: Shape::Point,
            reference: Reference::Anchored {
                anchor: Anchor::Document,
                offset: Some(Offset {
                    count: 0,
                    unit: Unit::Quarter,
                    direction: Direction::After,
                }),
            },
            granularity: Granularity::Month,
        };
        // 日历季:9 月 2 日在第三季(7–9 月)
        let calendar = DocumentDating {
            fiscal_year_end: None,
            ..ctx_dated(2026, 9, 2)
        };
        let r = resolve_one(&this_quarter, &calendar, &HashMap::new());
        assert_eq!(
            (r.from, r.to),
            (
                Some(at("2026-07-01T00:00:00Z")),
                Some(at("2026-09-01T00:00:00Z"))
            )
        );
        assert_eq!(
            (r.from_p, r.to_p, r.grade),
            (Some("month"), Some("month"), "B")
        );
        // 财年结束于 1 月 25 日:季首月是 2、5、8、11 月,9 月 2 日在 8–10 月那一季
        let r = resolve_one(&this_quarter, &ctx_dated(2026, 9, 2), &HashMap::new());
        assert_eq!(
            (r.from, r.to),
            (
                Some(at("2026-08-01T00:00:00Z")),
                Some(at("2026-10-01T00:00:00Z"))
            )
        );
        // 上一季度
        let last_quarter = Interpretation {
            reference: Reference::Anchored {
                anchor: Anchor::Document,
                offset: Some(Offset {
                    count: 1,
                    unit: Unit::Quarter,
                    direction: Direction::Before,
                }),
            },
            ..this_quarter
        };
        let r = resolve_one(&last_quarter, &calendar, &HashMap::new());
        assert_eq!(r.from, Some(at("2026-04-01T00:00:00Z")));
    }

    #[test]
    fn as_of_a_period_means_its_end_and_a_whole_year_is_one_bucket() {
        let year_end = Interpretation {
            id: 0,
            shape: Shape::AsOf,
            reference: Reference::Anchored {
                anchor: Anchor::Period {
                    name: "fiscal 2027".into(),
                },
                offset: None,
            },
            granularity: Granularity::Day,
        };
        let r = resolve_one(&year_end, &ctx_dated(2026, 9, 2), &HashMap::new());
        assert_eq!((r.from, r.grade), (Some(at("2027-01-25T00:00:00Z")), "B"));
        let whole_year = Interpretation {
            id: 1,
            shape: Shape::Interval,
            reference: Reference::Anchored {
                anchor: Anchor::Document,
                offset: Some(Offset {
                    count: 0,
                    unit: Unit::Year,
                    direction: Direction::After,
                }),
            },
            granularity: Granularity::Year,
        };
        let r = resolve_one(&whole_year, &ctx_dated(2024, 1, 1), &HashMap::new());
        assert_eq!(
            (r.from, r.to, r.from_p, r.to_p),
            (
                Some(at("2024-01-01T00:00:00Z")),
                Some(at("2024-01-01T00:00:00Z")),
                Some("year"),
                Some("year")
            )
        );
    }

    #[test]
    fn a_period_with_one_stated_bound_writes_only_that_bound() {
        let ended = Interpretation {
            id: 0,
            shape: Shape::Interval,
            reference: Reference::Period {
                name: "three months ended June 30, 2019".into(),
                from: None,
                to: Some(parts(2019, Some(6), Some(30))),
            },
            granularity: Granularity::Day,
        };
        let r = resolve_one(&ended, &DocumentDating::default(), &HashMap::new());
        assert_eq!(
            (r.from, r.to, r.grade),
            (None, Some(at("2019-06-30T00:00:00Z")), "A")
        );
    }

    #[test]
    fn month_arithmetic_clamps_to_the_month_end() {
        let t = at("2024-03-31T00:00:00Z");
        let back = shift(
            t,
            &Offset {
                count: 1,
                unit: Unit::Month,
                direction: Direction::Before,
            },
        )
        .unwrap();
        assert_eq!(back, at("2024-02-29T00:00:00Z"));
        let q = shift(
            t,
            &Offset {
                count: 1,
                unit: Unit::Quarter,
                direction: Direction::After,
            },
        )
        .unwrap();
        assert_eq!(q, at("2024-06-30T00:00:00Z"));
    }
}