@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.27

package/ts/src/memory-capture.ts

@@ -0,0 +1,283 @@
+/**
+ * T1 动态记忆的合并守门层(M4 记忆域;DeerFlow 研究 T1 落地):
+ *
+ * 分工(founder 校正「正则匹配 rules 不对」后重写):
+ *   - 事实提取 = LLM 的活。契约 (18) 已要求模型当轮把对话透露的新事实
+ *     (预算/日期/窗口/出发地/同伴/实际经历)经 gotry_motivation_save 并入
+ *     画像(evidence=用户原话)——语言理解交给模型,不做第二套正则引擎。
+ *   - 合并守门 = 代码的活。本文件只做三件代码才可靠的事:
+ *     ① 追加不删史(evidence 永不移除,P0 反幻觉:历史依据不可篡改)
+ *     ② 幂等(同 evidence 不重复入池)
+ *     ③ 结构守卫(weights 存在性校验、空补丁拒绝、权重归一)
+ *
+ * 额外承载(issue #338):用户显式声明的常驻城市/默认出发地——typed
+ * homeCity 字段 + 纯函数 resolveDefaultOrigin(explicit origin, profile)。
+ *   - 当前轮显式出发地永远赢(explicit origin > home city > missing)
+ *   - homeCity 变更必须伴新 evidence(P0 与 weights/hard 同向);单条 evidence
+ *     可作为省略 binding 的兼容形态,多条 evidence 必须显式绑定
+ *   - 该契约不触碰算术/求解——只读字段,不进 feasibility/evaluate 路径
+ *
+ * 持久化语义(issue #338):home-city 是 typed self-contained preference
+ * 记录 `{ value, evidence, updated_at }`,与全局 evidence 列表解耦——
+ * 一次不相关的动机补丁不会改写它的「证据指针」「更新时间」「当前值」。
+ * `updated_at` 由调用方在事件边界注入(账本事件行的 ts),mergeProfile
+ * 自身不在 fold 路径里再读时钟——保证 rebuildProjections() 与直读投影
+ * 永不分叉。
+ */
+
+export interface HomeCityPreference {
+  /** string=当前默认城市,null=已显式清除(审计一行留痕) */
+  value: string | null
+  /** 锁定到本次 home-city 操作的用户原话指针(append-only evidence 池里的那条) */
+  evidence: string
+  /** 账本事件行的 ts(非折叠期再读时钟) */
+  updated_at: string
+}
+
+export interface ProfilePatch {
+  weights?: Record<string, number>
+  /** 新增依据(用户原话或工具证据);只增不改不删 */
+  evidence?: string[]
+  hard?: Record<string, unknown>
+  /**
+   * 持久化用户常驻城市/默认出发地(issue #338)。
+   *   - string = 设置默认城市(用户原话指明常驻)
+   *   - null   = 显式清除(审计一行留痕,用于遗忘/迁居)
+   *   - undefined = 字段未传,保持当前值不动
+   * 改值须伴至少一条新 evidence(同 weights/hard 的 P0 守卫);恰好一条非空
+   * evidence 时可省略 homeCityEvidence,多条 evidence 必须显式绑定。
+   * 进入合并前会 trim;trim 后空白 → 视为「未传」,不触发变更、不落事件。
+   */
+  homeCity?: string | null
+  /**
+   * homeCity 在本次 profile.evidence 中的 exact 用户原话绑定。
+   * 显式传入时必须非空、逐字出现在 evidence 且相对当前画像为新值;
+   * 未传时仅允许 evidence 恰好一条且非空,由该条提供 unambiguous binding;
+   * 唯一例外是同 value/clear state + 同 typed evidence 的重复调用(幂等)。
+   */
+  homeCityEvidence?: string
+}
+
+export interface MergedProfile {
+  weights: Record<string, number>
+  evidence: string[]
+  hard: Record<string, unknown>
+  /** 当前持久默认城市。undefined 从未保存;null 显式清除;string 当前默认。 */
+  homeCity?: string | null
+  /**
+   * home-city 自含记录(issue #338):value + 锁定证据 + 更新时间三件套,
+   * 与全局 evidence 列表解耦。缺少或不满足完整 typed contract 的画像按
+   * missing 处理;raw homeCity 不会成为默认值或证据来源。
+   */
+  homeCityPreference?: HomeCityPreference
+}
+
+const ISO_LIKE_TIMESTAMP = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,3})?(Z|[+-]\d{2}:\d{2})$/
+
+function isNonBlankString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+function isValidIsoLikeTimestamp(value: unknown): value is string {
+  if (typeof value !== 'string') return false
+  const match = ISO_LIKE_TIMESTAMP.exec(value)
+  if (!match) return false
+  const year = Number(match[1])
+  const month = Number(match[2])
+  const day = Number(match[3])
+  const hour = Number(match[4])
+  const minute = Number(match[5])
+  const second = Number(match[6])
+  const zone = match[7]!
+  const daysInMonth = month === 2
+    ? (year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0) ? 29 : 28)
+    : [31, 0, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1]
+  if (!daysInMonth || day < 1 || day > daysInMonth) return false
+  // ISO permits 24:00:00 as the end-of-day spelling; no other 24:xx value.
+  if (hour > 23 && !(hour === 24 && minute === 0 && second === 0)) return false
+  if (minute > 59 || second > 59) return false
+  if (zone !== 'Z' && (Number(zone.slice(1, 3)) > 23 || Number(zone.slice(4, 6)) > 59)) return false
+  return Number.isFinite(Date.parse(value))
+}
+
+/**
+ * Typed home-city preference 的唯一有效性判定。
+ * 不读取、不修写 raw profile;raw homeCity 若存在只作镜像一致性校验。
+ */
+export function isValidHomeCityPreference(profile: {
+  homeCity?: unknown
+  evidence?: unknown
+  homeCityPreference?: unknown
+} | null): boolean {
+  const preference = profile?.homeCityPreference
+  if (!preference || typeof preference !== 'object' || Array.isArray(preference)) return false
+  const candidate = preference as Partial<HomeCityPreference>
+  if (!(candidate.value === null || isNonBlankString(candidate.value))) return false
+  if (!isNonBlankString(candidate.evidence) || !isValidIsoLikeTimestamp(candidate.updated_at)) return false
+  if (!profile || !Array.isArray(profile.evidence) || !profile.evidence.some(entry => entry === candidate.evidence)) return false
+  if (profile && Object.prototype.hasOwnProperty.call(profile, 'homeCity') && profile.homeCity !== candidate.value) return false
+  return true
+}
+
+/**
+ * 合并守门。纯函数;不读时钟——`now` 由调用方从事件边界(appendMotivationPatch
+ * 写时 ISO 或 foldEvent 重放时 row.ts)注入,保证写路径与重建路径时间戳一致。
+ *
+ * 触发 homeCity 操作的同时,会原地维护 typed homeCityPreference:
+ *   - valid new binding → 新 `{value, evidence: <homeCityEvidence exact string>, updated_at: now}`
+ *   - unchanged → 沿用 base 的 homeCityPreference(若有);缺失 typed 字段保持缺失
+ *   - missing/mismatched/stale binding → 返回 null,由账本跳过整次事件
+ */
+export function mergeProfile(
+  current: {
+    weights?: Record<string, number>
+    evidence?: string[]
+    hard?: Record<string, unknown>
+    homeCity?: string | null
+    homeCityPreference?: HomeCityPreference
+  } | null,
+  patch: ProfilePatch | null,
+  now: string,
+): MergedProfile | null {
+  if (!patch) return null
+  const base = {
+    weights: (current?.weights ?? {}) as Record<string, number>,
+    evidence: (current?.evidence ?? []) as string[],
+    hard: (current?.hard ?? {}) as Record<string, unknown>,
+    homeCity: (current?.homeCity === undefined ? undefined : current.homeCity) as string | null | undefined,
+    homeCityPreference: current?.homeCityPreference as HomeCityPreference | undefined,
+  } // 首次保存:无档案即空档案
+  const newEvidence = (patch.evidence ?? []).filter(Boolean).filter(e => !base.evidence.includes(e))
+  const patchWeights = patch.weights
+  const weightsChanged = !!patchWeights && Object.keys(patchWeights).length > 0 &&
+    JSON.stringify(patchWeights) !== JSON.stringify(base.weights)
+  const hardChanged = !!patch.hard && Object.keys(patch.hard).length > 0 &&
+    JSON.stringify(patch.hard) !== JSON.stringify(base.hard)
+  // homeCity 变更判定:
+  //   patch.homeCity === undefined → 字段未传,不视为变更
+  //   string 先 trim;trim 后空白 → 视作「未传」(避免把空白值当清除语义或无意义值写入)
+  //   trim 后与 base.homeCity 仍不等 → 视为变更(包括 string↔null、null↔undefined 等差异)
+  let patchedHomeCityInput: string | null | undefined = patch.homeCity
+  if (typeof patchedHomeCityInput === 'string') {
+    const trimmed = patchedHomeCityInput.trim()
+    patchedHomeCityInput = trimmed.length === 0 ? undefined : trimmed
+  }
+  const homeCityTouched = patchedHomeCityInput !== undefined
+  const homeCityChanged = homeCityTouched && patchedHomeCityInput !== base.homeCity
+
+  if (!homeCityTouched && patch.homeCityEvidence !== undefined) return null
+
+  // homeCity 的语义绑定必须在 profile patch 边界明确给出,不从自然语言或
+  // evidence 数组位置推断。唯一兼容例外:本次只有一条非空 evidence 时,
+  // 该条本身就是 unambiguous binding;多条 evidence 仍必须显式命名。
+  let homeCityEvidence: string | undefined
+  let homeCityEvidenceIsNew = false
+  if (homeCityTouched) {
+    const evidenceEntries = patch.evidence ?? []
+    const candidate = patch.homeCityEvidence !== undefined
+      ? patch.homeCityEvidence
+      : evidenceEntries.length === 1 && isNonBlankString(evidenceEntries[0])
+        ? evidenceEntries[0]
+        : undefined
+    const appearsInCall = isNonBlankString(candidate) && evidenceEntries.some(e => e === candidate)
+    homeCityEvidenceIsNew = appearsInCall && !base.evidence.includes(candidate)
+    const exactDuplicate = appearsInCall && !homeCityEvidenceIsNew && !homeCityChanged
+      && base.homeCityPreference?.value === patchedHomeCityInput
+      && base.homeCityPreference?.evidence === candidate
+    if (!appearsInCall || (!homeCityEvidenceIsNew && !exactDuplicate)) return null
+    homeCityEvidence = candidate
+  }
+
+  // A same-city/clear operation with a new bound quote is a real preference
+  // update even though the value itself did not change. The exact duplicate
+  // above remains a no-op.
+  const homeCityPreferenceChanged = homeCityTouched && homeCityEvidenceIsNew
+  if (newEvidence.length === 0 && !weightsChanged && !hardChanged && !homeCityChanged && !homeCityPreferenceChanged) return null
+
+  // 权重变更必须伴至少一条新 evidence(P0:改画像要有依据),否则拒该部分
+  let weights = { ...base.weights }
+  if (weightsChanged && newEvidence.length > 0 && patchWeights) {
+    weights = { ...weights, ...patchWeights }
+    const sum = Object.values(weights).reduce((a, b) => a + b, 0)
+    if (sum > 0) for (const k of Object.keys(weights)) weights[k] = Math.round((weights[k]! / sum) * 100) / 100
+  }
+
+  // homeCity 操作只接受上面验证过的 exact homeCityEvidence 绑定;无关 evidence
+  // 可以继续追加到全局池,但绝不会成为 homeCityPreference 的语义指针。
+  let homeCity: string | null | undefined = base.homeCity
+  let homeCityPreference: HomeCityPreference | undefined = base.homeCityPreference
+  if (homeCityPreferenceChanged) {
+    homeCity = patchedHomeCityInput ?? null
+    if (homeCityEvidence !== undefined) {
+      homeCityPreference = { value: homeCity, evidence: homeCityEvidence, updated_at: now }
+    }
+  }
+
+  return {
+    weights,
+    evidence: [...base.evidence, ...newEvidence],
+    hard: hardChanged ? { ...base.hard, ...(patch.hard ?? {}) } : { ...base.hard },
+    homeCity,
+    homeCityPreference,
+  }
+}
+
+/**
+ * 默认出发地解析契约(issue #338)。
+ *
+ * 纯函数,不读文件、不查 IP/浏览器位置/语言/时区/历史行程;不构造新 evaluate/solve 路径。
+ * 调用方负责传入当轮上下文(currentTripOrigin)与持久画像(profile)。
+ *
+ * 三态判决:
+ *   - explicit    当轮显式出发地(用户当轮输入);永远赢,不被持久默认覆盖
+ *   - home_default 持久化 homeCity;仅在当轮未指定时填补缺省(用于软排序/兜底)
+ *   - missing     二者皆空或显式已清除;调用方须向用户澄清而非自行猜测
+ *
+ * 该契约的硬约束:
+ *   - 不删除候选、不改变可行性判定、不进 evaluate/solve 路径
+ *   - 「只进软排序/补缺」语义由调用方在排序/回退层使用本结果
+ *
+ * 证据来源:只接受 self-contained typed preference(issue #338)的完整合同。
+ * 缺字段、镜像不一致或字段 malformed 的画像一律 missing,不从 raw homeCity
+ * 或全局 evidence 推断默认值/原话。
+ */
+export interface DefaultOriginResolution {
+  /** 解析后的出发地;null = 调用方应澄清 */
+  origin: string | null
+  /** 取值来源 */
+  source: 'explicit' | 'home_default' | 'missing'
+  /** 当前持久 homeCity(原值,便于 UI/日志/审计展示) */
+  homeCity: string | null | undefined
+  /** 锁定到本次 home-city 操作的用户原话指针;仅 valid home_default 填 */
+  homeCityEvidence?: string[]
+  /** 是否来自完整 typed preference 路径(便于 audit/UI 区分) */
+  homeCityPreferenceSource: 'typed' | 'none'
+}
+
+export function resolveDefaultOrigin(
+  currentTripOrigin: string | null | undefined,
+  profile: {
+    homeCity?: string | null
+    evidence?: string[]
+    homeCityPreference?: HomeCityPreference
+  } | null,
+): DefaultOriginResolution {
+  const trimmed = typeof currentTripOrigin === 'string' ? currentTripOrigin.trim() : ''
+  const validTypedPreference = isValidHomeCityPreference(profile)
+  const preference = validTypedPreference ? profile?.homeCityPreference as HomeCityPreference : undefined
+  const typedValue = preference?.value
+  const homeCity = validTypedPreference ? typedValue : undefined
+  if (trimmed) {
+    return { origin: trimmed, source: 'explicit', homeCity, homeCityPreferenceSource: 'none' }
+  }
+  if (validTypedPreference && typeof typedValue === 'string') {
+    return {
+      origin: typedValue.trim(),
+      source: 'home_default',
+      homeCity,
+      homeCityEvidence: [preference!.evidence],
+      homeCityPreferenceSource: 'typed',
+    }
+  }
+  return { origin: null, source: 'missing', homeCity, homeCityPreferenceSource: 'none' }
+}

package/ts/src/memory-decay.ts

@@ -0,0 +1,55 @@
+/**
+ * 时间窗衰减原语(memory-design P3):行为偏好的新鲜度置信度——
+ * 30/90/180/365d 分级窗口,确定性纯函数;**只降不删**(历史事件永远在,
+ * 衰减只作用于读时置信度);地板 0.1(记忆永不因旧而消失)。
+ *
+ * 边界(memory-design §4 P3):衰减只作用于**行为事件**(效用 sidecar 等);
+ * 动机权重层零衰减——动机跨年稳定是产品设计 §4 的明文(个性化的锚点),
+ * 本模块不提供任何作用于 motivation-profile 的 API(构造性保证)。
+ *
+ * 未来消费方(行为偏好层落地时):同原语直接复用,窗口即配置。
+ */
+
+export type DecayWindow = '30d' | '90d' | '180d' | '365d' | 'stale'
+
+/** 分级窗口:age(天)→ 因子;单调不增,地板 0.1(只降不删) */
+export function windowFactor(ageDays: number): number {
+  if (ageDays <= 30) return 1.0
+  if (ageDays <= 90) return 0.75
+  if (ageDays <= 180) return 0.5
+  if (ageDays <= 365) return 0.25
+  return 0.1
+}
+
+/** 事件种类权重:verified_outcome 最强,recalled 最弱(自称被召回 ≠ 有用) */
+export const KIND_WEIGHT = { recalled: 0.25, applied: 0.5, verified_outcome: 1.0 } as const
+
+export interface DecayableEvent {
+  ts: string
+  kind: keyof typeof KIND_WEIGHT
+}
+
+export function ageDaysOf(ts: string, now: Date): number {
+  const then = new Date(ts).getTime()
+  if (Number.isNaN(then)) return Number.POSITIVE_INFINITY
+  return Math.max(0, (now.getTime() - then) / 86_400_000)
+}
+
+/** 单事件衰减分:KIND_WEIGHT × windowFactor;未知时间戳按地板(不猜) */
+export function eventDecayScore(ev: DecayableEvent, now: Date): number {
+  const w = KIND_WEIGHT[ev.kind] ?? 0
+  return round4(w * windowFactor(ageDaysOf(ev.ts, now)))
+}
+
+/**
+ * 单条记忆的新鲜置信度 ∈ [0,1]:Σ 事件衰减分,上界 1。
+ * 同 wish 同窗口内事件越多置信越高(有界);旧事件只做地板贡献。
+ */
+export function decayedConfidence(events: DecayableEvent[], now: Date): number {
+  const sum = events.reduce((acc, ev) => acc + eventDecayScore(ev, now), 0)
+  return round4(Math.min(1, sum))
+}
+
+function round4(x: number): number {
+  return Math.round(x * 10_000) / 10_000
+}

package/ts/src/memory-utility.ts

@@ -0,0 +1,70 @@
+/**
+ * 记忆效用 sidecar(RFC S2,post-outcome-memory-utility-attribution 映射):
+ * 「被召回 ≠ 有用,自称用了 ≠ 让结果变好」——召回/使用/结果/归因四件语义独立记录,
+ * 确定性 reducer 只做投影;verified_outcome 只能来自 owner 确认(owner_correction tier),
+ * 模型永远不能自称「有用」。默认 fail-open:sidecar 缺失/损坏不阻塞主路径。
+ *
+ * 多用户 AaaS 前向兼容(RFC §6.5):append-only 事件流 + 稳定 wish_id,
+ * 未来账本化(CAS/receipt)是存储面替换,语义层零改造。
+ */
+
+export type UtilityEventKind = 'recalled' | 'applied' | 'verified_outcome'
+/** 归因只能来自 verified_outcome 事件,且必须 owner 确认(用户原话/显式选择) */
+export type UtilityAttribution = 'helpful' | 'harmful' | 'neutral'
+
+export interface MemoryUtilityEvent {
+  schema: 'memory_utility_observation.v0'
+  /** 幂等键:wish_id|kind|ctx|attribution 派生(语义派生,不用墙钟) */
+  event_id: string
+  wish_id: string
+  kind: UtilityEventKind
+  ts: string
+  /** 召回/确认发生的表面(turn id / 工具调用标识) */
+  ctx?: string
+  detail?: string
+  /** 仅 verified_outcome 携带;owner_correction tier */
+  attribution?: UtilityAttribution
+}
+
+export type UtilityStatus = 'unknown' | UtilityAttribution
+
+export interface WishUtility {
+  wish_id: string
+  status: UtilityStatus
+  recalled: number
+  applied: number
+  verified: number
+  last_event_ts?: string
+}
+
+/** 事件幂等键:同 wish 同类同 ctx 同归因 = 同一事件(重放 no-op) */
+export function makeEventId(ev: Omit<MemoryUtilityEvent, 'schema' | 'event_id'>): string {
+  return [ev.wish_id, ev.kind, ev.ctx ?? '', ev.attribution ?? ''].join('|')
+}
+
+/** 追加不重复(纯函数,不改入参):同 event_id 已存在 → no-op */
+export function appendEvent(events: MemoryUtilityEvent[], ev: Omit<MemoryUtilityEvent, 'schema' | 'event_id'>): { events: MemoryUtilityEvent[]; appended: boolean } {
+  const full: MemoryUtilityEvent = { schema: 'memory_utility_observation.v0', event_id: makeEventId(ev), ...ev }
+  if (events.some(e => e.event_id === full.event_id)) return { events, appended: false }
+  if (ev.kind === 'verified_outcome' && !ev.attribution) {
+    // 无归因的结果不算归因证据:降级为 applied(六件语义不越界)
+    return appendEvent(events, { ...ev, kind: 'applied' })
+  }
+  return { events: [...events, full], appended: true }
+}
+
+/** 只读投影:status = 最后一次 verified_outcome 的归因;无 verified_outcome 永远 unknown */
+export function projectUtility(events: MemoryUtilityEvent[]): Record<string, WishUtility> {
+  const out: Record<string, WishUtility> = {}
+  for (const ev of events) {
+    const w = out[ev.wish_id] ??= { wish_id: ev.wish_id, status: 'unknown', recalled: 0, applied: 0, verified: 0 }
+    if (ev.kind === 'recalled') w.recalled++
+    if (ev.kind === 'applied') w.applied++
+    if (ev.kind === 'verified_outcome') {
+      w.verified++
+      if (ev.attribution) w.status = ev.attribution
+    }
+    w.last_event_ts = ev.ts
+  }
+  return out
+}

package/ts/src/mock-llm.ts

@@ -9,6 +9,7 @@ import type { InterviewQuestion, TravelerProfile, TripState, Turn, CalendarState
 import type { JourneySpecTS } from './unified.ts'
 import type { TravelSlotExtraction } from './travel-slots.ts'
 import { parseFlightPackToSpec } from './unified.ts'
+import { mergeProfileWorkWindow } from './flight-pack-adapter.ts'
 
 interface ScriptStep {
   /** 命中条件:用户消息包含此关键词(第一条匹配生效) */
@@ -79,14 +80,9 @@ export function createMockLlm(flightPackPath?: string, slotScript: SlotScriptSte
       const { readFile } = await import('node:fs/promises')
       const pack = JSON.parse(await readFile(flightPackPath, 'utf-8'))
       const spec = parseFlightPackToSpec(pack)
-      spec.workWindow = {
-        homeTzOffsetMin: state.profile.workWindow.homeTzOffsetMin,
-        startMin: state.profile.workWindow.startMin,
-        endMin: state.profile.workWindow.endMin,
-        workdays: state.profile.workWindow.workdays,
-      }
-      spec.budgetCny = 9000
-      return spec
+      const merged = mergeProfileWorkWindow(spec, state.profile.workWindow)
+      merged.budgetCny = 9000
+      return merged
     },
     async extractSlots(history: Turn[]): Promise<TravelSlotExtraction | null> {
       const last = history[history.length - 1]?.text ?? ''

package/ts/src/model.ts

@@ -19,6 +19,16 @@ export interface TransferMode {
   mode: string
   minutes: number
   priceCny: number
+  /**
+   * Per-direction overrides supplied by the ground-transfer capability when a
+   * driving route fact successfully resolves for outbound (A→B) and/or return
+   * (B→A). `minutesOut` feeds the outbound arrival stay minute;
+   * `minutesRet` feeds the return departure-from-stay minute. When absent
+   * the solver falls back to the symmetric `minutes` field, preserving
+   * byte-for-byte behavior for static and symmetric inputs.
+   */
+  minutesOut?: number
+  minutesRet?: number
 }
 
 export interface Service {
@@ -26,6 +36,14 @@ export interface Service {
   depMin: number
   arrMin: number
   priceCny: number
+  /**
+   * Issue #343 v2 路径填充(可选):service 出发/到达对应的真实 UTC instant(epoch ms)。
+   * 同一 service 在 arrMin - depMin ≤ 真实飞行时长 跨日 / DST 切换场景下需要这两个字段
+   * 才能算出正确的 (arrUtcMs - depUtcMs) / 60000。v1 数值路径不填,由 evaluateChoice/Segment 走
+   * 旧 `(arrMin - depMin) - tzOffsetMin` 公式,字节不变。
+   */
+  depUtcMs?: number
+  arrUtcMs?: number
 }
 
 export interface HubAccess {
@@ -46,6 +64,8 @@ export interface MotivationProfile {
 export interface Candidate {
   id: string
   name: string
+  /** 可选的明确出行日;未提供时保持旧版无日期可行性计算语义 */
+  date?: string
   hub: string
   bufferOutMin: number
   bufferRetMin: number
@@ -147,6 +167,7 @@ export function parseCandidate(d: Record<string, unknown>): Candidate {
   return {
     id: String(d['id']),
     name: String(d['name']),
+    date: typeof d['date'] === 'string' ? d['date'] : undefined,
     hub: String(d['hub']),
     bufferOutMin: Number(d['buffer_out_min'] ?? 60),
     bufferRetMin: Number(d['buffer_ret_min'] ?? 60),
@@ -161,11 +182,76 @@ export function parseCandidate(d: Record<string, unknown>): Candidate {
   }
 }
 
+/** Issue #343 d2d canonical arithmetic。 */
+export class NonpositiveDurationError extends Error {
+  /** 'arr_not_after_dep' | 'legacy_negative_offset' */
+  readonly kind: 'arr_not_after_dep' | 'legacy_negative_offset'
+  readonly code = 'nonpositive_duration'
+  constructor(kind: 'arr_not_after_dep' | 'legacy_negative_offset', message: string) {
+    super(message)
+    this.kind = kind
+    this.name = 'NonpositiveDurationError'
+  }
+}
+
+/**
+ * doorToDoorFromMove 所需的最小 move 字段。本模型层不耦合 unified.ts 的 MoveSpecTS(避免循环)。
+ * unified.ts evaluateOptionMove 必须用这个 helper,而不是再写一份 (arrUtcMs - depUtcMs)/60000。
+ */
+export interface D2DMoveView {
+  bufferMin: number
+  originTransferMin: number
+  destTransferMin: number
+  /** 仅 v1 路径用;v2 路径无需。 */
+  tzOffsetMin?: number
+}
+
+export interface DoorToDoorParts {
+  /** 真实飞行时长(分);v2 = (arrUtcMs - depUtcMs)/60000,v1 = (arrMin - depMin) - tzOffsetMin */
+  trueFlightMin: number
+  /** 门到门(分) = buffer + originTransfer + trueFlight + destTransfer */
+  doorToDoorMin: number
+}
+
+/**
+ * 单段门到门时长(分)。v2 路径用真实 UTC instant(跨日 / 反向日界线 / DST 切换正确),
+ * 且强制 `arrUtcMs > depUtcMs` — parse 边界也会再做一次防御性 throw。
+ * v1 路径用墙上分钟差 - tzOffsetMin(原数值口径,字节不变,即使结果为负也照旧返回)。
+ *
+ * v2:arrUtcMs 必须严格大于 depUtcMs;否则抛 NonpositiveDurationError(arr_not_after_dep)。
+ * v1:沿用 legacy 公式,字节不变;不抛错。
+ *
+ * 调用方(unified.ts evaluateOptionMove)只负责拿到 doorToDoorMin 并包装 LegReport。
+ */
+export function doorToDoorFromMove(svc: Service, mv: D2DMoveView): DoorToDoorParts {
+  if (typeof svc.depUtcMs === 'number' && typeof svc.arrUtcMs === 'number') {
+    if (svc.arrUtcMs <= svc.depUtcMs) {
+      throw new NonpositiveDurationError(
+        'arr_not_after_dep',
+        `service ${svc.id}: arrUtcMs (${svc.arrUtcMs}) must be strictly greater than depUtcMs (${svc.depUtcMs})`,
+      )
+    }
+    const trueFlightMin = (svc.arrUtcMs - svc.depUtcMs) / 60_000
+    const doorToDoorMin = mv.bufferMin + mv.originTransferMin + trueFlightMin + mv.destTransferMin
+    return { trueFlightMin, doorToDoorMin }
+  }
+  // v1 legacy 字节不变:不校验正负,沿用原公式。
+  const trueFlightMin = (svc.arrMin - svc.depMin) - (mv.tzOffsetMin ?? 0)
+  const doorToDoorMin = mv.bufferMin + mv.originTransferMin + trueFlightMin + mv.destTransferMin
+  return { trueFlightMin, doorToDoorMin }
+}
+
 export function evaluateChoice(cand: Candidate, req: TravelRequest, ch: Choice): TrueCost {
   /** 门到门全成本核算(与 Python evaluate_choice 完全一致)。 */
   const access = req.homeHubAccess[cand.hub]
+  const outTransferMin = typeof ch.outTransfer.minutesOut === 'number'
+    ? ch.outTransfer.minutesOut
+    : ch.outTransfer.minutes
+  const retTransferMin = typeof ch.retTransfer.minutesRet === 'number'
+    ? ch.retTransfer.minutesRet
+    : ch.retTransfer.minutes
   const wake = ch.outService.depMin - cand.bufferOutMin - access.toHubMin
-  const arriveStay = ch.outService.arrMin + ch.outTransfer.minutes
+  const arriveStay = ch.outService.arrMin + outTransferMin
   const d2dOut = arriveStay - wake
 
   let energy = 100
@@ -179,7 +265,7 @@ export function evaluateChoice(cand: Candidate, req: TravelRequest, ch: Choice):
 
   const day1Raw = Math.max(0, DAY_END_MIN - arriveStay) / 60
   const day1 = day1Raw * (0.5 + energy / 200)
-  const leaveStayRet = ch.retService.depMin - cand.bufferRetMin - ch.retTransfer.minutes
+  const leaveStayRet = ch.retService.depMin - cand.bufferRetMin - retTransferMin
   const day2 = Math.max(0, leaveStayRet - DAY2_START_MIN) / 60 * DAY2_QUALITY
   const midDays = Math.max(0, ch.days - 2)
   const usable = day1 + day2 + midDays * 8.0 * DAY2_QUALITY

package/ts/src/recall/card.ts

@@ -0,0 +1,106 @@
+/**
+ * Why-now card builder(issue #577,Phase D;研究决策 §3 Phase D;
+ * 自检 review 修复见 PR #578——边界校验让「无信源的卡构造上不可能」成为字面真)。
+ *
+ * 纯函数:RecallTrigger → WhyNowCard(中文文案:标题 + 触发原因 + 当前值/阈值 +
+ * 行动建议 + source tag)。
+ *
+ * 纪律:
+ *   - **边界强制 provenance**:buildWhyNowCard 校验 signal.source 非空 + reason 在
+ *     闭集,不合法**直接抛错**——「source_tag 必现」不再是注释承诺而是构造保证;
+ *   - 文案模板是封闭词汇(标题/建议的措辞改 = 契约变更,先 review);
+ *   - 卡片是数据(不是渲染 HTML);渲染面(deck / 对话 / SMS)各自消费;
+ *   - renderWhyNowCardLine 必须带证据边界标记(渲染契约:每个渲染面都要展示)。
+ */
+
+import { RECALL_REASON_LABEL, RECALL_REASONS, type RecallReason, type RecallTrigger } from './evaluator.ts'
+
+export interface WhyNowCard {
+  /** 卡片标题(如「现在可以去了:大理 · 洱海恢复之旅」;半角冒号——代码字面量即契约) */
+  title: string
+  /** 卡片所指的 wish(结构化自指;Phase E 起必含——plan-it 深链的行动目标,
+   *  从 title 字符串反解不可接受) */
+  wish_id: string
+  /** 触发原因(枚举) */
+  reason: RecallReason
+  /** 触发原因的人话标签(如「假期临近」) */
+  reason_label: string
+  /** 当前值(如「2026-10-01(距今 7 天)」) */
+  current_value: string
+  /** 阈值(如「距假期 ≤14 天」) */
+  threshold: string
+  /** 行动建议(如「建议本周内规划出发」) */
+  action_hint: string
+  /** 源 tag(必现;渲染为 `[source:xxx]`) */
+  source_tag: string
+  /** 评估时刻(ISO) */
+  evaluated_at: string
+  /** 证据边界声明(恒 true;渲染面必须展示) */
+  evidence_boundary: true
+  /** 实际命中的愿望条件(评估器从 scoreWishMatch 带出的逐项 hits,如「days≥5」;
+   *  **缺省 = 该卡未附条件命中证据**——手工构造的卡不发明证据;渲染面必须把
+   *  「命中部分愿望条件」与「全部出行条件已满足」区分开,后者永不主张)。 */
+  match_evidence?: string[]
+}
+
+const ACTION_HINT: Record<RecallReason, string> = {
+  holiday_proximity: '建议在假期前完成规划,锁定当前档期',
+  price_drop: '价格已降至阈值,建议尽快确认出发日期',
+  weather_window: '天气窗口已打开,适合按原计划出行',
+  route_new: '新班次已覆盖目标日期,可以重新评估可行性',
+  availability_recovered: '通道已恢复,此前不可行的方案现在可以重新查询',
+}
+
+/**
+ * 构造 why-now 卡:trigger → 人话卡片。
+ * **边界强制 provenance**:signal.source 非空 + reason 在闭集,否则抛错
+ * (「无信源的卡构造上不可能存在」的字面兑现——手工构造的 trigger 同样受检)。
+ * **证据诚实**:trigger.match_hits 是非空字符串数组时原样带上(all-or-nothing,
+ * 不部分裁剪、不发明);缺省/空/畸形 → 卡不带 match_evidence——手工构造的卡
+ * 宁可无证据,不虚构命中。
+ * title 格式:`现在可以去了:${wish_name}`(半角冒号)——封闭词汇,改措辞 = 契约变更。
+ */
+export function buildWhyNowCard(trigger: RecallTrigger): WhyNowCard {
+  const { wish_id, wish_name, signal, evaluated_at } = trigger
+  if (signal === null || typeof signal !== 'object') {
+    throw new Error(`buildWhyNowCard:signal 必须是对象(实测 ${String(signal)})`)
+  }
+  if (typeof signal.source !== 'string' || signal.source.length === 0) {
+    throw new Error('buildWhyNowCard:signal.source 必须是非空字符串(无信源的卡构造上不可能存在)')
+  }
+  if (!RECALL_REASONS.includes(signal.reason as RecallReason)) {
+    throw new Error(`buildWhyNowCard:signal.reason 不在闭集(实测 ${String(signal.reason)};允许:${RECALL_REASONS.join(' / ')})`)
+  }
+  // 条件命中证据:all-or-nothing 校验(非空的非空字符串数组才带上;不发明、不裁剪)
+  const rawHits: unknown = (trigger as Partial<RecallTrigger>).match_hits
+  const hasEvidence = Array.isArray(rawHits) && rawHits.length > 0
+    && rawHits.every(h => typeof h === 'string' && h.length > 0)
+  return {
+    title: `现在可以去了:${wish_name}`,
+    wish_id,
+    reason: signal.reason,
+    reason_label: RECALL_REASON_LABEL[signal.reason],
+    current_value: signal.current_value,
+    threshold: signal.threshold,
+    action_hint: ACTION_HINT[signal.reason],
+    source_tag: `[source:${signal.source}]`,
+    evaluated_at,
+    evidence_boundary: true,
+    ...(hasEvidence ? { match_evidence: [...(rawHits as string[])] } : {}),
+  }
+}
+
+/** 渲染为单行中文摘要(对话/日志面用;卡片数据仍是权威)。
+ *  必须含证据边界标记(渲染契约:每个渲染面都要展示 evidence_boundary);
+ *  卡带 match_evidence 时逐项陈述命中条件,并显式声明**不主张全部出行条件已满足**
+ *  (命中部分愿望条件只是召回资格,不是出行可行性证明)。 */
+export function renderWhyNowCardLine(card: WhyNowCard): string {
+  const evidence = Array.isArray(card.match_evidence) && card.match_evidence.length > 0
+    ? card.match_evidence
+    : null
+  const conditionClause = evidence !== null ? `;命中条件:${evidence.join('+')}` : ''
+  const boundary = evidence !== null
+    ? '[证据边界:仅命中上述愿望条件,非全部出行条件已满足]'
+    : '[证据边界:仅证据驱动]'
+  return `${card.title}——${card.reason_label}(当前:${card.current_value};阈值:${card.threshold}${conditionClause})。${card.action_hint} ${card.source_tag} ${boundary}`
+}