@danceiny/gotry 0.0.1-rc.10

package/ts/src/time-anchor.ts

@@ -0,0 +1,134 @@
+/**
+ * 时间锚点层(确定性纯函数,零依赖):「今天是哪天、相对日期怎么换算」的算术全部在这里,
+ * LLM 只查锚点卡不自算(仓规:算术只在代码层;tool-owned dates 的执行面)。
+ *
+ * 消费面:
+ *  - dsh 成品路径:index.ts 注册 {{time_anchor_card}} 变量,系统时钟;
+ *  - legacy 抽取路径:dsh-llm.ts 注入 FACTS/SKELETON/槽位抽取 prompt;
+ *  - 评测:time-eval-tests.ts 用固定 now(2026-08-27)保证确定性。
+ *
+ * 债务(architecture §10 登记):节日锚点表 SPRING_FESTIVAL 硬编码(2026-08-28 扩至 2031);
+ * 跨 2031 前必须再扩表,否则春节锚点静默缺失。
+ */
+
+export interface TimeAnchor {
+  /** 今天 YYYY-MM-DD(宿主机本地时区) */
+  today: string
+  /** 今天星期几,如「周四」 */
+  todayWeekdayZh: string
+  /** 时区标注,如 UTC+8 / UTC+5:30 */
+  tzLabel: string
+  /** 注入 prompt 的多行锚点卡文本 */
+  card: string
+}
+
+const WEEKDAYS_ZH = ['日', '一', '二', '三', '四', '五', '六'] as const
+
+export function ymd(d: Date): string {
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+}
+
+function addDays(d: Date, n: number): Date {
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate() + n)
+}
+
+/** ISO 周周一:getDay() 周日=0 归到上周一(-6) */
+function weekMonday(d: Date): Date {
+  return addDays(d, -((d.getDay() + 6) % 7))
+}
+
+/** 春节锚点表(仅此节日漂移大,硬编码;元旦/国庆固定月日,按「下一次发生」算)。D-9:2026-08-28 扩至 2031 */
+const SPRING_FESTIVAL: Record<number, string> = {
+  2026: '2026-02-17',
+  2027: '2027-02-06',
+  2028: '2028-01-26',
+  2029: '2029-02-13',
+  2030: '2030-02-03',
+  2031: '2031-01-23',
+}
+
+function tzLabelOf(d: Date): string {
+  const offsetMin = -d.getTimezoneOffset()
+  const sign = offsetMin >= 0 ? '+' : '-'
+  const abs = Math.abs(offsetMin)
+  const h = Math.floor(abs / 60)
+  const m = abs % 60
+  return `UTC${sign}${m === 0 ? h : `${h}:${String(m).padStart(2, '0')}`}`
+}
+
+function weekdayOf(d: Date): string {
+  return `周${WEEKDAYS_ZH[d.getDay()]}`
+}
+
+/** 一周七天的渲染:周一 2026-08-31|周二 …|周日 … */
+function weekRow(label: string, monday: Date): string {
+  const days = Array.from({ length: 7 }, (_, i) => {
+    const d = addDays(monday, i)
+    return `${weekdayOf(d)} ${ymd(d)}`
+  })
+  return `${label}:${days.join('|')}`
+}
+
+/** 固定月日节日的下一次发生(已过则取明年) */
+function nextOccurrence(todayYmd: string, year: number, monthDay: string): string {
+  const thisYear = `${year}-${monthDay}`
+  return thisYear >= todayYmd ? thisYear : `${year + 1}-${monthDay}`
+}
+
+export function buildTimeAnchor(now: Date = new Date()): TimeAnchor {
+  const today = ymd(now)
+  const year = now.getFullYear()
+  const monday = weekMonday(now)
+
+  const tomorrow = addDays(now, 1)
+  const dayAfter = addDays(now, 2)
+  const inThreeDays = addDays(now, 3)
+
+  // 下个月:初(1-10)/中旬(11-20)/下旬(21-月末)
+  const nm = new Date(year, now.getMonth() + 1, 1)
+  const nmYear = nm.getFullYear()
+  const nmMonth = nm.getMonth()
+  const nmLastDay = new Date(nmYear, nmMonth + 1, 0).getDate()
+  const mm = String(nmMonth + 1).padStart(2, '0')
+
+  // 下个季度初
+  const nextQuarterMonth0 = Math.floor(now.getMonth() / 3) * 3 + 3
+  const nq = new Date(nextQuarterMonth0 >= 12 ? year + 1 : year, nextQuarterMonth0 % 12, 1)
+
+  const festivals: string[] = [
+    `国庆 ${nextOccurrence(today, year, '10-01')}`,
+    `元旦 ${nextOccurrence(today, year, '01-01')}`,
+  ]
+  const spring = Object.values(SPRING_FESTIVAL).filter(d => d >= today).sort()[0]
+  if (spring) festivals.push(`春节 ${spring}`)
+
+  const card = [
+    `今天 ${today} ${weekdayOf(now)}(时区 ${tzLabelOf(now)})`,
+    `明天 ${ymd(tomorrow)} ${weekdayOf(tomorrow)}|后天 ${ymd(dayAfter)} ${weekdayOf(dayAfter)}|大后天 ${ymd(inThreeDays)} ${weekdayOf(inThreeDays)}`,
+    weekRow('本周', monday),
+    weekRow('下周', addDays(monday, 7)),
+    weekRow('下下周', addDays(monday, 14)),
+    `下个月 ${nmYear}-${mm}:初 ${mm}-01~${mm}-10|中旬 ${mm}-11~${mm}-20|下旬 ${mm}-21~${mm}-${nmLastDay}`,
+    `下个季度初:${ymd(nq)} 起`,
+    `节日锚点:${festivals.join('|')}(「国庆前」= 该日之前,以此类推)`,
+  ].join('\n')
+
+  return { today, todayWeekdayZh: weekdayOf(now), tzLabel: tzLabelOf(now), card }
+}
+
+/**
+ * 绝对月日表达 → YYYY-MM-DD(年缺省时按锚点年)。只识别**绝对**表达:
+ * ISO(2026-08-01)、数字点分(8.1 / 9.10)、中文(8月5日 / 8月5号)。
+ * 相对/模糊表达(下周一/明天/本周三/下个月中旬/近期/Aug-5 英文月名)一律返回 null——
+ * 逐字保留给下游,本层不做换算也不做过期判定(与评测 golden 对齐:英文月日不判过期)。
+ */
+export function parseAbsoluteDate(expr: string, anchorYear: number): string | null {
+  const t = expr.trim()
+  let m = t.match(/^(\d{4})-(\d{1,2})-(\d{1,2})$/)
+  if (m) return `${m[1]}-${m[2].padStart(2, '0')}-${m[3].padStart(2, '0')}`
+  m = t.match(/^(\d{1,2})[./](\d{1,2})(?:日|号)?$/)
+  if (m) return `${anchorYear}-${m[1].padStart(2, '0')}-${m[2].padStart(2, '0')}`
+  m = t.match(/^(\d{1,2})月(\d{1,2})[日号]?$/)
+  if (m) return `${anchorYear}-${m[1].padStart(2, '0')}-${m[2].padStart(2, '0')}`
+  return null
+}

package/ts/src/tool-packet.ts

@@ -0,0 +1,32 @@
+/**
+ * 工具调用 packet 纪律(RFC S1,loopx agent-loop-effect-interpreter 映射):
+ * 每次工具交互 = effect_request(args) → interpretation(interpretArgs)→ observation(返回值)。
+ *
+ * envelope 是**平铺**的(house style,与 guardToolExecute 兜底同形):
+ *  - 成功:{ ok: true, ...payload } —— 渲染/调用方按字段读,不受扰;
+ *  - 失败:{ ok: false, summary, evidence? } —— guard 异常降级天然就是这一支。
+ * Handler 是数据不是 callable:observation 必须可 JSON 序列化(跨 dsh/cordis 边界)。
+ */
+
+/** 失败分支(guardToolExecute 兜底与工具显式失败共用此形状) */
+export interface ToolFailure {
+  ok: false
+  summary: string
+  evidence?: string
+}
+
+/** 成功分支:业务载荷平铺 + ok:true 标记 */
+export type GotryObservation<T extends object> = (T & { ok: true }) | ToolFailure
+
+/**
+ * 参数归一(interpretation 层):dsh 模型侧对 query 包装参数的三种形态——
+ * ① 包装对象 { query: {...} } ② 裸对象(平铺字段) ③ 字符串(按主键收)。
+ * 唯一归一入口;工具面不再各自猜形状。
+ */
+export function interpretArgs<T extends Record<string, unknown>>(args: { query?: unknown } & Record<string, unknown>, stringKey?: string): T {
+  if (args.query && typeof args.query === 'object') return args.query as T
+  const { query, ...rest } = args as Record<string, unknown>
+  if (Object.keys(rest).length > 0) return rest as T
+  if (typeof query === 'string' && stringKey) return { [stringKey]: query } as T
+  return {} as T
+}

package/ts/src/travel-slots.ts

@@ -0,0 +1,219 @@
+/**
+ * 槽位抽取层(travel_slot_extraction.v1):面向差旅 intake 的槽位 schema + 确定性过期校验 + 评分器。
+ *
+ * 设计约定(与评测 golden 逐条对齐):
+ *  - 时间表达**逐字保留**(「下周一」就写「下周一」),换算归下游工具——tool-owned dates;
+ *  - 过期判定在代码层(flagExpiredSlots),LLM 只负责逐字抽取;
+ *  - 过期只判**主日期字段**(requisition.start_date / flight.departure_date / hotel.check_in_date),
+ *    且槽位原值保留,仅往 missing_slots 追加 "<domain>.<field> (date is expired)";
+ *  - 相对/模糊表达永不判过期(「本周三」即使已过也逐字传递,由人裁决语义)。
+ *
+ * slot→spec 求解桥接不在本期(architecture §10 债务)。
+ */
+
+import { parseAbsoluteDate, type TimeAnchor } from './time-anchor.ts'
+
+export type SlotDomain = 'requisition' | 'flight' | 'hotel'
+
+export interface RequisitionSlots {
+  mode?: 'create' | string
+  destination?: string | string[]
+  start_date?: string
+  end_date?: string
+  duration_days?: number
+  trip_type?: 'one_way' | 'round_trip' | string
+}
+
+export interface FlightSlots {
+  action?: 'search' | string
+  origin?: string
+  destination?: string | string[]
+  departure_date?: string
+  return_date?: string
+  departure_time_pref?: string
+  sort_name?: string
+  sort_type?: string
+  multi_destination?: boolean
+  trip_type?: 'one_way' | 'round_trip' | string
+}
+
+export interface HotelSlots {
+  action?: 'search' | string
+  city?: string
+  check_in_date?: string
+  check_out_date?: string
+}
+
+export interface TravelSlotExtraction {
+  schema_version: 'travel_slot_extraction.v1'
+  language: 'zh' | 'en' | 'mixed'
+  domains: SlotDomain[]
+  slots: {
+    requisition?: RequisitionSlots
+    flight?: FlightSlots
+    hotel?: HotelSlots
+  }
+  missing_slots: string[]
+}
+
+/** 各域的主日期字段——过期校验只判它(对齐 golden:8.1-8.10 仅 start_date 进 missing_slots) */
+const PRIMARY_DATE_FIELD: Record<SlotDomain, string> = {
+  requisition: 'start_date',
+  flight: 'departure_date',
+  hotel: 'check_in_date',
+}
+
+/**
+ * 确定性过期校验(纯函数,不改入参):主日期字段是**绝对**月日表达且早于锚点今天,
+ * 往 missing_slots 追加 "<domain>.<field> (date is expired)"(幂等去重);槽位原值不动。
+ */
+export function flagExpiredSlots(ext: TravelSlotExtraction, anchor: TimeAnchor): TravelSlotExtraction {
+  const anchorYear = Number(anchor.today.slice(0, 4))
+  const missing = [...ext.missing_slots]
+  for (const domain of ext.domains) {
+    const slots = ext.slots[domain] as Record<string, unknown> | undefined
+    const field = PRIMARY_DATE_FIELD[domain]
+    const value = slots?.[field]
+    if (typeof value !== 'string') continue
+    const resolved = parseAbsoluteDate(value, anchorYear)
+    if (resolved && resolved < anchor.today) {
+      const flag = `${domain}.${field} (date is expired)`
+      if (!missing.includes(flag)) missing.push(flag)
+    }
+  }
+  return { ...ext, missing_slots: missing }
+}
+
+/** 槽位抽取 system prompt:锚点卡注入 + 逐字保留铁律(LLM 不做算术、不判过期) */
+export function buildSlotSystem(anchor: TimeAnchor): string {
+  return `你是差旅需求的槽位抽取器。从用户原话抽取槽位,只输出 JSON:
+{"schema_version":"travel_slot_extraction.v1","language":"zh|en|mixed","domains":["requisition"|"flight"|"hotel",...],"slots":{...},"missing_slots":[...]}
+
+## 时间锚点卡
+${anchor.card}
+相对日期(明天/下周X/下个月中旬/国庆前…)对应的绝对日期都查锚点卡,不要自己心算。
+
+## 铁律
+1. 时间表达逐字保留、不翻译:用户说「下周一」就写「下周一」,说「next Thursday」就写 "next Thursday"——绝不换算成绝对日期、绝不切换语言(换算归下游工具)。模糊时间词(过几天/近期/下周初/隔周/下个月)同样是合法槽位值,逐字保留,**不算缺失**。
+2. language 指**用户原话**的语言(与槽位值用什么语言无关):全中文 zh;全英文 en;中英混排 mixed。即使槽位值按规则 10 含中文城市名,只要原话全英文,language 仍为 en。
+3. 域判定——看用户的**动作动词**,一句话可落多个域:
+   - 安排行程/行程推荐/帮我安排 → requisition:{"mode":"create","destination","start_date","end_date"?,"trip_type"}
+   - 看/查/订机票、航班、票价 → flight:{"action":"search","origin"?,"destination","departure_date","return_date"?,"trip_type"}
+   - 看/订酒店、入住、订房 → hotel:{"action":"search","city","check_in_date","check_out_date"?};「待/住 N 天」只是时长语义,不单独构成 hotel 域
+   - 「出差/去 X」本身不构成 requisition;没有上述动词的单城出行意图按回程形态分流:
+     「去 X,当天往返」→ 仅 requisition(round_trip);「去 X,周日回/X 号回」跨天回程 → 仅 flight(round_trip)。
+4. trip_type 必填(requisition 与 flight;hotel 不要):出现「往返/回程/当天往返/X 号回」→ "round_trip";否则显式 "one_way"。
+5. 停留天数:「出差/待/住 N 天」→ requisition 用 "duration_days":N;hotel 用 "check_out_date":"<入住表达>+N" 原样拼接。
+6. 回程机票(「住 N 天回 X」「待到周日回 X」):flight.origin=旅行城市, flight.destination=X, flight.departure_date="<入住/到达表达>+N" 或逐字回程表达,只有回程时 trip_type="one_way"。
+7. 价格**排序**偏好只在找低价时加(「哪天便宜/比较便宜/最便宜」→ flight "sort_name":"PRICE","sort_type":"ASC");单纯「看价格/多少钱」不加。
+8. 出发时段偏好(「早上七点后出发」)→ flight 加 "departure_time_pref":"07:00后"(HH:MM后 格式)。
+9. 多目的地:
+   - 国内多城链路(≥3 城):requisition.destination 与 flight.destination 都写**全程城市数组**(含首站),flight 不写 origin,departure_date=首段出发表达,加 "multi_destination":true;不为链路每段单独建 hotel/子段。
+   - 国际开口程(open-jaw):flight.origin=首站(单值), flight.destination=后续链路数组, 加 "multi_destination":true。
+10. 城市名:纯国内行程用中文标准名(北京/上海/广州/深圳…,即使原文是拼音);国际或跨国多城链路的城市名保留用户原文。
+11. 关键槽位缺失(如有机票意图但无目的地)→ missing_slots 加 "<domain>.<field>";不缺则空数组。
+12. 过期判定不归你:绝对日期是否已过由下游确定性层处理,你只管逐字抽取。
+
+## 示例(学习约定,勿照抄内容)
+用户:下周五入住上海,住三天回杭州
+输出:{"schema_version":"travel_slot_extraction.v1","language":"zh","domains":["hotel","flight"],"slots":{"hotel":{"action":"search","city":"上海","check_in_date":"下周五","check_out_date":"下周五+3"},"flight":{"action":"search","origin":"上海","destination":"杭州","departure_date":"下周五+3","trip_type":"one_way"}},"missing_slots":[]}
+
+用户:next Monday 去上海,订酒店
+输出:{"schema_version":"travel_slot_extraction.v1","language":"mixed","domains":["hotel"],"slots":{"hotel":{"action":"search","city":"上海","check_in_date":"next Monday"}},"missing_slots":[]}
+
+用户:这阵子想去广州,帮我看下深圳到广州的机票
+输出:{"schema_version":"travel_slot_extraction.v1","language":"zh","domains":["flight"],"slots":{"flight":{"action":"search","origin":"深圳","destination":"广州","departure_date":"这阵子","trip_type":"one_way"}},"missing_slots":[]}
+
+用户:8.20 日去杭州,当天往返
+输出:{"schema_version":"travel_slot_extraction.v1","language":"zh","domains":["requisition"],"slots":{"requisition":{"mode":"create","destination":"杭州","start_date":"8.20","trip_type":"round_trip"}},"missing_slots":[]}
+
+用户:下周三去杭州,周六回
+输出:{"schema_version":"travel_slot_extraction.v1","language":"zh","domains":["flight"],"slots":{"flight":{"action":"search","destination":"杭州","departure_date":"下周三","return_date":"周六","trip_type":"round_trip"}},"missing_slots":[]}
+
+用户:下周三去成都,待到周六,周六去西安待一天然后回杭州
+输出:{"schema_version":"travel_slot_extraction.v1","language":"zh","domains":["requisition","flight"],"slots":{"requisition":{"mode":"create","destination":["成都","西安","杭州"],"start_date":"下周三","trip_type":"round_trip"},"flight":{"action":"search","destination":["成都","西安","杭州"],"departure_date":"下周三","multi_destination":true,"trip_type":"round_trip"}},"missing_slots":[]}
+
+用户:open-jaw please: Shanghai to Tokyo next Monday, back from Osaka to Shanghai next Friday
+输出:{"schema_version":"travel_slot_extraction.v1","language":"en","domains":["flight"],"slots":{"flight":{"action":"search","origin":"Shanghai","destination":["Tokyo","Osaka","Shanghai"],"departure_date":"next Monday","return_date":"next Friday","multi_destination":true,"trip_type":"round_trip"}},"missing_slots":[]}
+
+只输出 JSON,不要多余文本。`
+}
+
+/**
+ * language 的确定性判定(判定归代码层,不信模型):只看用户原话——
+ * 含中文且含拉丁字母 → mixed;仅中文 → zh;仅拉丁 → en。
+ * (对齐 golden:「next Thursday 去北京」=mixed;全英文带中文槽位值仍=en)
+ */
+export function detectLanguage(utterance: string): 'zh' | 'en' | 'mixed' {
+  const hasCjk = /[一-鿿]/.test(utterance)
+  const hasLatin = /[A-Za-z]/.test(utterance)
+  if (hasCjk && hasLatin) return 'mixed'
+  if (hasLatin) return 'en'
+  return 'zh'
+}
+
+/** 模型原始 JSON → 规范化 v1 抽取结果(缺省补齐,域外键容忍;language 由 detectLanguage 覆写) */
+export function normalizeExtraction(obj: Record<string, unknown>, utterance?: string): TravelSlotExtraction | null {
+  const domains = obj['domains']
+  if (!Array.isArray(domains) || domains.length === 0) return null
+  const valid = domains.filter((d): d is SlotDomain => d === 'requisition' || d === 'flight' || d === 'hotel')
+  if (valid.length === 0) return null
+  const lang = obj['language']
+  const slots = (obj['slots'] ?? {}) as TravelSlotExtraction['slots']
+  const missing = obj['missing_slots']
+  return {
+    schema_version: 'travel_slot_extraction.v1',
+    language: utterance !== undefined ? detectLanguage(utterance) : (lang === 'en' || lang === 'mixed' ? lang : 'zh'),
+    domains: valid,
+    slots,
+    missing_slots: Array.isArray(missing) ? missing.map(String) : [],
+  }
+}
+
+export interface ScoreResult {
+  pass: boolean
+  /** 致命差异(导致 fail) */
+  diffs: string[]
+  /** 非致命提示(actual 多出 expected 没有的槽位键等) */
+  warnings: string[]
+}
+
+const sortedSet = (xs: string[]) => [...xs].sort()
+
+/**
+ * 评分器:case pass 的口径 = language 一致 + domains 集合一致 +
+ * expected 的每个槽位键值在 actual 中精确命中(actual 多出的键只记 warning)+
+ * missing_slots 集合一致。逐字保留语义下,值比较就是字符串精确比较。
+ */
+export function scoreExtraction(expected: TravelSlotExtraction, actual: TravelSlotExtraction): ScoreResult {
+  const diffs: string[] = []
+  const warnings: string[] = []
+
+  if (expected.language !== actual.language) {
+    diffs.push(`language: 期望 ${expected.language},实际 ${actual.language}`)
+  }
+  if (JSON.stringify(sortedSet(expected.domains)) !== JSON.stringify(sortedSet(actual.domains))) {
+    diffs.push(`domains: 期望 [${sortedSet(expected.domains)}],实际 [${sortedSet(actual.domains)}]`)
+  }
+  for (const domain of expected.domains) {
+    const exp = expected.slots[domain] as Record<string, unknown> | undefined
+    const act = actual.slots[domain] as Record<string, unknown> | undefined
+    if (!exp) continue
+    if (!act) {
+      diffs.push(`slots.${domain}: 实际缺失整个域`)
+      continue
+    }
+    for (const [k, v] of Object.entries(exp)) {
+      if (JSON.stringify(act[k]) !== JSON.stringify(v)) {
+        diffs.push(`slots.${domain}.${k}: 期望 ${JSON.stringify(v)},实际 ${JSON.stringify(act[k])}`)
+      }
+    }
+    for (const k of Object.keys(act)) {
+      if (!(k in exp)) warnings.push(`slots.${domain}.${k}: 实际多出键 ${JSON.stringify(act[k])}`)
+    }
+  }
+  if (JSON.stringify(sortedSet(expected.missing_slots)) !== JSON.stringify(sortedSet(actual.missing_slots))) {
+    diffs.push(`missing_slots: 期望 [${expected.missing_slots}],实际 [${actual.missing_slots}]`)
+  }
+  return { pass: diffs.length === 0, diffs, warnings }
+}

package/ts/src/travel-timeline.ts

@@ -0,0 +1,83 @@
+/**
+ * 旅行时间线(memory-design M4 层,P1):「去过哪、何时、和谁」的 append-only 事实层。
+ *
+ * 立场(memory-design §1):确定性事实归代码——日期解析复用 slot-spec(锚点卡词表+绝对),
+ * 词表外 unresolved 不猜;每条事件必须带 evidence(用户原话或 wish 确认),溯源 P0。
+ * 消费:出发地三级解析(未来行程→时间线→问用户)/「去过不再推」排序通道/
+ * 回流率分子(verified_outcome ⟺ timeline 有对应行程)。
+ * 多用户前向兼容:append-only + 稳定 trip_id,账本化只换存储面(RFC §6.5)。
+ */
+
+import { parseAbsoluteDate, ymd, type TimeAnchor } from './time-anchor.ts'
+import { resolveSlotDate } from './slot-spec.ts'
+
+export type TimelineSource = 'user-verbatim' | 'wish-confirmed'
+
+export interface TimelineEvent {
+  schema: 'travel_timeline.v1'
+  /** 稳定主键:语义派生(目的地|start|source),重放 no-op */
+  trip_id: string
+  destination: string
+  /** YYYY-MM-DD(入库前必须已解析为绝对日期) */
+  start: string
+  end?: string
+  companions?: string[]
+  source: TimelineSource
+  /** 用户原话或 wish confirm-outcome 指针 */
+  evidence: string
+  ts: string
+}
+
+/** 相对/模糊表达 → 绝对日期(守门:词表外返回 null,调用方必须拒收而非猜) */
+export function resolveTimelineDate(expr: string, anchor: TimeAnchor): string | null {
+  return resolveSlotDate(expr, anchor).date
+}
+
+/** 语义主键:同目的地+同 start+同 source = 同一行程(重放 no-op) */
+export function makeTripId(ev: Omit<TimelineEvent, 'schema' | 'trip_id' | 'ts'>): string {
+  return `${ev.destination}|${ev.start}|${ev.source}`.replace(/\s+/g, '_')
+}
+
+/**
+ * 追加守门(纯函数,不改入参):
+ *  - destination/evidence 必填,start 必须已是绝对日期(YYYY-MM-DD),否则拒收(null);
+ *  - end < start 拒收;
+ *  - 同 trip_id 已存在 → no-op(返回 appended:false,幂等);
+ *  - 同目的地日期区间重叠(不同 trip_id)→ 拒收(冲突即停,由人裁决)。
+ */
+export function appendTrip(
+  events: TimelineEvent[],
+  ev: Omit<TimelineEvent, 'schema' | 'trip_id' | 'ts'>,
+): { events: TimelineEvent[]; appended: boolean; tripId?: string; reason?: string } {
+  if (!ev.destination?.trim()) return { events, appended: false, reason: 'destination 必填' }
+  if (!ev.evidence?.trim()) return { events, appended: false, reason: 'evidence 必填(用户原话或 wish 确认指针)' }
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(ev.start)) return { events, appended: false, reason: 'start 必须为 YYYY-MM-DD(词表外日期由上游解析,不猜)' }
+  if (ev.end && ev.end < ev.start) return { events, appended: false, reason: 'end 早于 start' }
+  const tripId = makeTripId(ev)
+  if (events.some(e => e.trip_id === tripId)) return { events, appended: false, tripId }
+  const overlap = events.find(e => e.destination === ev.destination && !(e.end && e.end < ev.start) && !(ev.end && ev.end < e.start))
+  if (overlap) return { events, appended: false, tripId: overlap.trip_id, reason: `与已有行程 ${overlap.trip_id} 日期重叠,冲突即停` }
+  const full: TimelineEvent = { schema: 'travel_timeline.v1', trip_id: tripId, ts: new Date().toISOString(), ...ev }
+  return { events: [...events, full], appended: true, tripId }
+}
+
+/** 只读投影:按 start 倒序的行程摘要(「去过」行/brief 注入用) */
+export function projectTimeline(events: TimelineEvent[]): Array<{ tripId: string; destination: string; start: string; end?: string; companions?: string[] }> {
+  return [...events]
+    .sort((a, b) => (a.start < b.start ? 1 : -1))
+    .map(e => ({ tripId: e.trip_id, destination: e.destination, start: e.start, end: e.end, companions: e.companions }))
+}
+
+/**
+ * 交叉一致(回流率分子的质变):verified_outcome 的 wish 应有对应时间线行程。
+ * 返回缺口清单(verified 但无 timeline)——巡检口径,不自动补写(补写需要用户确认日期)。
+ */
+export function timelineGapsForVerified(
+  timeline: TimelineEvent[],
+  verifiedWishes: Array<{ wishId: string; destination?: string }>,
+): Array<{ wishId: string }> {
+  const dests = new Set(timeline.map(t => t.destination))
+  return verifiedWishes.filter(w => w.destination && !dests.has(w.destination)).map(w => ({ wishId: w.wishId }))
+}
+
+export { ymd }