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

package/ts/src/recall/evaluator.ts

@@ -0,0 +1,170 @@
+/**
+ * Recall condition evaluator(issue #577,Phase D;研究决策 §3 Phase D;
+ * 自检 review 修复见 PR #578 评论——两轮:广播升级/容器与时钟守卫/单表派生;
+ * #577 收口:条件资格门 + 命中证据,见 docs/design/recall-trigger.md §2)。
+ *
+ * 纯函数:给定 wish-pool 候选条目 + 当前上下文(时间 + 召回窗口 match_context +
+ * 各类简化信号),产出一组 RecallTrigger——每个含「为什么是现在」的具体原因
+ * (条件名 + 当前值 + 阈值)与实际命中的愿望条件(match_hits)与 source tag
+ * (**proactive with provenance**——研究文档红线)。
+ *
+ * 纪律:
+ *   - 原因闭集 5 类,**单表派生**(RECALL_REASON_LABEL 为唯一事实源;union / 数组 /
+ *     label 全部从它推导——新增原因 = 改一张表,编译器强制 card.ts 的 hint 表补全);
+ *   - **条件资格门**:候选必须先过 scoreWishMatch(wish-pool.ts 原样复用,不复制
+ *     判定逻辑)——任一 days/budget/month 命中即有召回资格(既有语义:是召回资格,
+ *     不是「全部出行条件已满足」的证明);命名 down 通道否证。信号(含定向)不能
+ *     绕过资格门;match_context 缺省/畸形 → fail-closed 空返回,绝不降级为广播;
+ *   - **职责边界**:信号是 producer 给的人话信号(current_value/threshold 是展示
+ *     字符串,不是类型化价格/日期事实),评估器不解析它们;资格事实只来自注入的
+ *     match_context;
+ *   - 畸形输入(信号/容器/时钟/条目)**跳过或空返回,不崩**——评估器是消费链一环,
+ *     一个坏 tick 不能杀掉调用方的 drain loop;
+ *   - wish_ids 非数组(如字符串)= 畸形信号,**跳过**(绝不降级为广播匹配——
+ *     广播是最激进模式,降级等于扩权);
+ *   - muted 过滤用 `muted === true` 严格判定(JSON 往返的 'false' 字符串不再误杀)。
+ */
+
+import { scoreWishMatch, type WishMatch, type WishMatchContext, type WishPoolEntry } from '../wish-pool.ts'
+
+/** 唯一事实源:5 类原因 → 中文标签。新增原因 = 在此表加一行(union/数组自动派生;
+ *  card.ts 的 ACTION_HINT 表由 Record<RecallReason,...> 编译强制补全)。 */
+export const RECALL_REASON_LABEL = {
+  holiday_proximity: '假期临近',
+  price_drop: '价格降至阈值',
+  weather_window: '天气窗口打开',
+  route_new: '新航线/班次开通',
+  availability_recovered: '通道恢复可用',
+} as const
+
+export type RecallReason = keyof typeof RECALL_REASON_LABEL
+
+/** 闭集数组从 label 表派生(单一事实源;不再手抄第二份) */
+export const RECALL_REASONS: readonly RecallReason[] = Object.keys(RECALL_REASON_LABEL) as RecallReason[]
+
+/** 单条触发信号(外部世界的一次状态变化;由 M4 的 sensor/tick 填充) */
+export interface RecallSignal {
+  reason: RecallReason
+  /** 源 tag(必填非空;渲染为 `[source:xxx]`) */
+  source: string
+  /** 当前值(人话,如「2026-10-01(距今 7 天)」;producer 展示串,评估器不解析) */
+  current_value: string
+  /** 阈值描述(人话,如「距假期 ≤14 天」;同上) */
+  threshold: string
+  /** 受影响的 wish_id 列表(空/缺省 = 广播;**非数组 = 畸形,整条跳过**) */
+  wish_ids?: string[]
+}
+
+/** 评估上下文(tick 到来时由调用方组装;纯数据)。
+ *  match_context 是 scoreWishMatch 的窗口事实(days/budgetCny/month/channelDown),
+ *  缺省/畸形 → 整轮 fail-closed(空返回)——没有窗口证据就不宣称「现在可以去」。 */
+export interface RecallContext {
+  now: Date
+  signals: RecallSignal[]
+  match_context: WishMatchContext
+}
+
+/** 触发结果:wish × signal 的配对(一个 wish 可命中多个信号,一卡一信号) */
+export interface RecallTrigger {
+  wish_id: string
+  wish_name: string
+  signal: RecallSignal
+  /** 评估时刻(ISO) */
+  evaluated_at: string
+  /** 实际命中的愿望条件(scoreWishMatch 的逐项 hits,如「days≥5」;恒非空数组——
+   *  资格门保证;渲染「为什么是它」用,不主张全部出行条件已满足) */
+  match_hits: string[]
+}
+
+/**
+ * 评估:候选 × 信号 → 触发列表。
+ * 两道门,先资格后匹配:
+ *   1. **资格门**:候选非 muted + 有稳定非空 wish_id + scoreWishMatch(entry,
+ *      match_context) 非空(任一条件命中,且无命名 down 通道否证)——信号匹配只在
+ *      有资格的候选上进行;
+ *   2. **匹配门**:signal.wish_ids 是非空字符串数组时按 id 精确匹配(定向);
+ *      为空/缺省时匹配全部**有资格**候选(广播)。**wish_ids 为其它真值类型
+ *      (字符串/对象等)视为畸形信号,整条跳过**——绝不降级为广播。
+ * 容器/时钟/上下文守卫:signals/pool 非数组、ctx.now 非法、match_context 缺省或
+ * 畸形 → 返回 [](不抛,不崩 drain loop,不广播扩权)。
+ */
+export function evaluateRecallTriggers(pool: WishPoolEntry[], ctx: RecallContext): RecallTrigger[] {
+  // 容器与时钟守卫:一个坏 tick 不能杀掉调用方(fail-closed 空返回)
+  if (!Array.isArray(pool) || !Array.isArray(ctx?.signals)) return []
+  const nowMs = ctx.now instanceof Date ? ctx.now.getTime() : Number.NaN
+  if (!Number.isFinite(nowMs)) return []
+  // 条件上下文守卫:缺省/畸形 → fail-closed(绝不降级为「全部广播」——
+  // 没有窗口证据就广播「现在可以去」正是 #577 要堵住的扩权)
+  if (!isWishMatchContext(ctx.match_context)) return []
+  const evaluatedAt = new Date(nowMs).toISOString()
+
+  // 资格门:scoreWishMatch 非空(≥1 项 days/budget/month 命中,且无命名通道 down 否证)
+  // 才进入候选;保持 pool 原序(广播/定向的输出顺序与既有行为一致)
+  const eligible: Array<{ entry: WishPoolEntry; match: WishMatch }> = []
+  for (const e of pool) {
+    if (e?.muted === true || typeof e?.wish_id !== 'string' || e.wish_id.length === 0) continue
+    const match = scoreCandidate(e, ctx.match_context)
+    if (match !== null) eligible.push({ entry: e, match })
+  }
+
+  const triggers: RecallTrigger[] = []
+  for (const signal of ctx.signals) {
+    if (!isRecallSignal(signal)) continue
+    const targets = Array.isArray(signal.wish_ids) && signal.wish_ids.length > 0
+      ? eligible.filter(({ entry }) => (signal.wish_ids as string[]).includes(entry.wish_id as string))
+      : eligible
+    for (const { entry, match } of targets) {
+      triggers.push({
+        wish_id: String(entry.wish_id),
+        wish_name: typeof entry.name === 'string' && entry.name.length > 0 ? entry.name : String(entry.wish_id),
+        signal,
+        evaluated_at: evaluatedAt,
+        match_hits: [...match.hits],
+      })
+    }
+  }
+  return triggers
+}
+
+/**
+ * 资格判定:scoreWishMatch 原样复用(唯一判定层,不复制判定/阈值逻辑)。
+ * 意外抛错(运行时畸形形态逃过静态与结构检查)→ 该条目无资格,不崩——
+ * 单个坏条目不能杀掉整轮评估。
+ */
+function scoreCandidate(entry: WishPoolEntry, ctx: WishMatchContext): WishMatch | null {
+  try {
+    return scoreWishMatch(entry, ctx)
+  } catch {
+    return null
+  }
+}
+
+/** match_context 运行时校验(JSON 往返边界强制):非数组对象 + 数值字段(若给出)
+ *  必须是有限数字 + channelDown(若给出非 null)必须具备 has 方法(Set 形)。
+ *  与 scoreWishMatch 的缺省语义对齐:channelDown 缺省/null = 不启用通道否证。 */
+function isWishMatchContext(value: unknown): value is WishMatchContext {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const c = value as Record<string, unknown>
+  for (const k of ['days', 'budgetCny', 'month'] as const) {
+    const v = c[k]
+    if (v !== undefined && (typeof v !== 'number' || !Number.isFinite(v))) return false
+  }
+  const down = c.channelDown
+  if (down !== undefined && down !== null && typeof (down as { has?: unknown }).has !== 'function') return false
+  return true
+}
+
+/** 信号校验(边界强制,不从输入信任):reason 在闭集 + source 非空字符串 +
+ *  current_value/threshold 为字符串 + **wish_ids 一旦给出必须是字符串数组**
+ * (字符串等真值非数组 = 畸形,拒绝——绝不降级广播)。 */
+function isRecallSignal(value: unknown): value is RecallSignal {
+  if (typeof value !== 'object' || value === null) return false
+  const s = value as Record<string, unknown>
+  if (!RECALL_REASONS.includes(s.reason as RecallReason)) return false
+  if (typeof s.source !== 'string' || s.source.length === 0) return false
+  if (typeof s.current_value !== 'string' || typeof s.threshold !== 'string') return false
+  if (s.wish_ids !== undefined && s.wish_ids !== null) {
+    if (!Array.isArray(s.wish_ids) || !s.wish_ids.every(id => typeof id === 'string')) return false
+  }
+  return true
+}

package/ts/src/recall/integration.ts

@@ -0,0 +1,35 @@
+/**
+ * Recall wish-pool integration(issue #577,Phase D)。
+ *
+ * 把 wish-pool 候选条目接到 evaluator:从 tick + signals 组装上下文 → 跑评估 →
+ * 产触发列表 + why-now 卡。**只读 wish-pool**(不调用 mutation;撤回/通知留 M4)。
+ *
+ * 本模块不接 IO——数据进出全靠参数(测试全离线;M4 由真实 tick source + sensor 喂数据)。
+ */
+
+import type { WishMatchContext, WishPoolEntry } from '../wish-pool.ts'
+import { evaluateRecallTriggers, type RecallContext, type RecallSignal, type RecallTrigger } from './evaluator.ts'
+import { buildWhyNowCard, type WhyNowCard } from './card.ts'
+import type { RecallTick } from './tick.ts'
+
+export interface PoolRecallInput {
+  pool: WishPoolEntry[]
+  tick: RecallTick
+  signals: RecallSignal[]
+  /** 召回窗口事实(days/budgetCny/month/channelDown;原样传给 evaluateRecallTriggers
+   *  → scoreWishMatch 条件资格门)。缺省/畸形 → 评估整轮 fail-closed(空返回)。 */
+  match_context: WishMatchContext
+}
+
+export interface PoolRecallResult {
+  triggers: RecallTrigger[]
+  cards: WhyNowCard[]
+}
+
+/** 从 wish-pool + tick + signals + 召回窗口跑一轮评估并产卡(纯函数编排) */
+export function evaluatePoolRecall(input: PoolRecallInput): PoolRecallResult {
+  const ctx: RecallContext = { now: input.tick.at, signals: input.signals, match_context: input.match_context }
+  const triggers = evaluateRecallTriggers(input.pool, ctx)
+  const cards = triggers.map(buildWhyNowCard)
+  return { triggers, cards }
+}

package/ts/src/recall/tick.ts

@@ -0,0 +1,213 @@
+/**
+ * Recall tick scheduler(issue #577,Phase D;研究决策见
+ * docs/research/karpo-deck-web-research.md §3 Phase D;
+ * seam 约束见 docs/design/external-event-seam.md §3.3/§4——**pull model,M5 前无 push**;
+ * 自检 review 两轮修复见 PR #578 评论)。
+ *
+ * 设计契约:
+ *   - TickSource:`next()` **运行中阻塞到下一个 tick 可用**;**未运行(未启动或已
+ *     stop)返回 null = 流终结**——drain-loop 调用方安全退出,永不悬挂;
+ *   - PeriodicTickSource:**默认 enabled=false**(显式 opt-in);start() 三态
+ *     ('started'|'disabled'|'already-running');timer.unref()(不拽住事件循环);
+ *     pending 有界(maxPending 默认 100,溢出丢最旧);**stop() 清空 pending 并把
+ *     全部等待者以 null 唤醒**(终结核平——消费协程不泄漏,重启不吐陈旧 tick);
+ *   - RecallTickScheduler:**永不抛错**——evaluate/toCard/deliver 全部容错:
+ *     evaluate 抛错 → {delivered:0, failed:0, error};单卡 toCard/deliver 抛错 →
+ *     只弃该卡(failed++ 并记 errors),余下继续;返回 {delivered, failed, errors?};
+ *   - **不推送**:sink 是注入的下游,不是 notification/push 通道(seam §4)。
+ */
+
+export interface RecallTick {
+  /** tick 发生的时刻 */
+  at: Date
+  /** 来源标记(fail-safe 渲染用;不参与逻辑) */
+  source: string
+}
+
+export interface TickSource {
+  /** 拉下一个 tick:**运行中**阻塞到可用;**未运行**(未启动/已 stop)返回 null = 流终结 */
+  next(): Promise<RecallTick | null>
+}
+
+/** 测试用 InMemory tick source:预排好的一组 tick,按序返回,耗尽返回 null。
+ *  构造与 next() 均防御式深拷贝(调用方改返回的 tick.at 不会污染队列快照)。 */
+export class InMemoryTickSource implements TickSource {
+  private queue: RecallTick[]
+  constructor(ticks: RecallTick[]) {
+    this.queue = ticks.map(t => ({ at: new Date(t.at.getTime()), source: t.source }))
+  }
+  async next(): Promise<RecallTick | null> {
+    const t = this.queue.shift()
+    if (t === undefined) return null
+    return { at: new Date(t.at.getTime()), source: t.source }  // 返回副本,调用方可安全改
+  }
+}
+
+export type PeriodicTickStartResult = 'started' | 'disabled' | 'already-running'
+
+export interface PeriodicTickSourceOptions {
+  /** tick 间隔(毫秒;必须为正数) */
+  intervalMs: number
+  /** **默认 false;显式 opt-in 才产生 tick**(纪律:不悄悄起后台循环) */
+  enabled?: boolean
+  /** 来源标记 */
+  source?: string
+  /** pending 队列上界(默认 100;溢出丢最旧——慢消费者不会无限积压过期 tick) */
+  maxPending?: number
+}
+
+/**
+ * 周期 tick source(默认关闭):封装 Node setInterval。
+ * - enabled=false 构造默认,显式 opt-in;start() 三态返回(不混同);
+ * - next() 语义:**运行中**阻塞到下个 tick;**未运行**(disabled/未 start/已 stop)
+ *   立即返回 null(流终结——drain-loop 安全退出,永不悬挂);
+ * - stop() 幂等:**清空 pending(重启不吐陈旧 tick)+ 把全部等待者以 null 唤醒**
+ *   (消费协程不泄漏);
+ * - timer.unref():忘了 stop() 也不拽住进程事件循环;
+ * - pending 有界(maxPending,溢出丢最旧)。
+ */
+export class PeriodicTickSource implements TickSource {
+  readonly enabled: boolean
+  private intervalMs: number
+  private sourceLabel: string
+  private maxPending: number
+  private timer: ReturnType<typeof setInterval> | null = null
+  private pending: RecallTick[] = []
+  private waiters: Array<(t: RecallTick | null) => void> = []
+
+  constructor(opts: PeriodicTickSourceOptions) {
+    this.enabled = opts.enabled === true
+    this.intervalMs = opts.intervalMs
+    this.sourceLabel = opts.source ?? 'periodic'
+    this.maxPending = opts.maxPending ?? 100
+    if (!Number.isFinite(this.intervalMs) || this.intervalMs <= 0) {
+      throw new Error(`PeriodicTickSource intervalMs 必须为正数(实测 ${this.intervalMs})`)
+    }
+    if (!Number.isInteger(this.maxPending) || this.maxPending < 1) {
+      throw new Error(`PeriodicTickSource maxPending 必须为 ≥1 整数(实测 ${this.maxPending})`)
+    }
+  }
+
+  /** 启动内部 setInterval;三态返回(见类注释)。已启动时幂等。 */
+  start(): PeriodicTickStartResult {
+    if (!this.enabled) return 'disabled'
+    if (this.timer !== null) return 'already-running'
+    this.timer = setInterval(() => {
+      const tick: RecallTick = { at: new Date(), source: this.sourceLabel }
+      // 优先唤醒等待者;无等待者入有界队列(溢出丢最旧)
+      const waiter = this.waiters.shift()
+      if (waiter !== undefined) {
+        waiter(tick)
+        return
+      }
+      if (this.pending.length >= this.maxPending) this.pending.shift()
+      this.pending.push(tick)
+    }, this.intervalMs)
+    // unref:不拽住事件循环(调用方忘了 stop() 也不会让进程赖着不死;测试进程自然退出)
+    ;(this.timer as unknown as { unref?: () => void }).unref?.()
+    return 'started'
+  }
+
+  /** 停止(幂等):清 timer + **清空 pending(重启不吐陈旧 tick)+ 等待者全部以 null 唤醒**(终结核平) */
+  stop(): void {
+    if (this.timer !== null) {
+      clearInterval(this.timer)
+      this.timer = null
+    }
+    this.pending = []
+    const waiters = this.waiters
+    this.waiters = []
+    for (const w of waiters) w(null)
+  }
+
+  /** 当前 pending 队列长度(只读;测试与诊断用) */
+  get pendingLength(): number {
+    return this.pending.length
+  }
+
+  /** **运行中**阻塞到下一个 tick;**未运行**(disabled/未 start/已 stop)返回 null(流终结) */
+  async next(): Promise<RecallTick | null> {
+    if (this.timer === null) return null
+    const queued = this.pending.shift()
+    if (queued !== undefined) return queued
+    return new Promise<RecallTick | null>(resolve => {
+      this.waiters.push(resolve)
+    })
+  }
+}
+
+/** scheduler 的下游 sink:注入(测试用数组收集;M4 接 wish_pool_list / 对话面) */
+export interface RecallSink {
+  deliver(card: unknown): Promise<void> | void
+}
+
+/** 数组收集 sink(测试用) */
+export class ArrayRecallSink implements RecallSink {
+  readonly items: unknown[] = []
+  deliver(card: unknown): void {
+    this.items.push(card)
+  }
+}
+
+export interface RecallTickSchedulerDeps<E, C> {
+  /** tick 到来时的评估函数(evaluator;契约上纯函数) */
+  evaluate: (tick: RecallTick) => E[]
+  /** 评估结果到卡的转换(纯函数;签名带 tick——卡的 evaluated_at 应取 tick.at) */
+  toCard: (evaluation: E, tick: RecallTick) => C
+  /** 下游(注入;测试用 ArrayRecallSink) */
+  sink: RecallSink
+}
+
+export interface RecallRunResult {
+  /** 成功送出的卡数 */
+  delivered: number
+  /** toCard 或 deliver 抛错被跳过的卡数(不弃余下;不外泄异常) */
+  failed: number
+  /** 容错捕获的错误消息(前几条;诊断用,绝不外泄为异常) */
+  errors?: string[]
+}
+
+/**
+ * 编排器:拉 tick → 评估 → 转卡 → 送 sink。
+ * 每次 run 处理一个 tick(调用方决定循环;scheduler 自己不循环——不悄悄长驻)。
+ * **永不抛错**:evaluate 抛错 → {delivered:0, failed:0, error 记入 errors};
+ * 单卡 toCard/deliver 抛错 → 只弃该卡(failed++/errors 记一条),余下继续。
+ */
+export class RecallTickScheduler<E, C> {
+  private deps: RecallTickSchedulerDeps<E, C>
+
+  constructor(deps: RecallTickSchedulerDeps<E, C>) {
+    this.deps = deps
+  }
+
+  async run(tick: RecallTick): Promise<RecallRunResult> {
+    const errors: string[] = []
+    let evaluations: E[]
+    try {
+      evaluations = this.deps.evaluate(tick)
+      if (!Array.isArray(evaluations)) evaluations = []
+    } catch (err) {
+      return { delivered: 0, failed: 0, errors: [`evaluate: ${(err as Error)?.message ?? String(err)}`] }
+    }
+    let delivered = 0
+    let failed = 0
+    for (const evaluation of evaluations) {
+      let card: C
+      try {
+        card = this.deps.toCard(evaluation, tick)
+      } catch (err) {
+        failed++
+        if (errors.length < 4) errors.push(`toCard: ${(err as Error)?.message ?? String(err)}`)
+        continue
+      }
+      try {
+        await this.deps.sink.deliver(card)
+        delivered++
+      } catch (err) {
+        failed++
+        if (errors.length < 4) errors.push(`deliver: ${(err as Error)?.message ?? String(err)}`)
+      }
+    }
+    return errors.length > 0 ? { delivered, failed, errors } : { delivered, failed }
+  }
+}

package/ts/src/session-link/plan-it-action.ts

@@ -0,0 +1,78 @@
+/**
+ * Plan-it 行动卡(issue #580,Phase E)——why-now 卡(Phase D)的一键行动
+ * 面:「好,规划它」深链回本地 session 继续规划该 wish。**只打开,不写**:
+ * 行动词位只有 plan_it(Continue planning),booking/payment 不在链接词位
+ * (session-link.ts 的 action 闭集),WriteGate 保持 sealed。
+ *
+ * 纪律:
+ *   - 行动卡是数据(不是渲染 HTML);渲染面(deck / 对话 / 通知)各自消费;
+ *   - `wish_id` 与 token payload **同源构造**(同一个值进两处),不可能漂移——
+ *     渲染面显示的 wish 与链接打开的 wish 是构造级同一个;
+ *   - label 是封闭词汇(「好,规划它」改措辞 = 契约变更,先 review);
+ *   - why-now 卡的「not_now」是渲染面本地消解(无链接、无状态写),
+ *     本契约不覆盖(文档声明)。
+ */
+
+import type { WhyNowCard } from '../recall/card.ts'
+import { formatSessionLink, signSessionLink, type SessionLinkPayload } from './session-link.ts'
+
+export interface PlanItAction {
+  /** 恒 'plan_it'(构造保证;不存在其它 kind 的 PlanItAction) */
+  kind: 'plan_it'
+  /** 行动文案(封闭词汇) */
+  label: string
+  /** 渲染好的深链(formatSessionLink 默认 base `gotry://session/<token>`) */
+  deep_link: string
+  /** 与 token payload 同源构造的 wish_id(冗余自洽;渲染面可直接显示) */
+  wish_id: string
+}
+
+/** plan-it 行动文案(封闭词汇) */
+export const PLAN_IT_LABEL = '好,规划它'
+
+export interface BuildPlanItActionDeps {
+  /** 不透明 session 引用(session-link.ts 护栏:非路径) */
+  session_ref: string
+  /** 幂等 id(调用方给;缺省随机) */
+  link_id?: string
+  /** 链接有效秒数(默认 24h;上限 SESSION_LINK_TTL_MAX_SECONDS) */
+  ttl_seconds?: number
+  /** 渲染 base(缺省 gotry://session;本地 http 消费端可传 http://127.0.0.1:3080/session) */
+  base?: string
+  /** HMAC secret(缺省 resolveSessionLinkSecret()) */
+  secret?: string
+  /** 时钟注入(测试用) */
+  now?: () => Date
+}
+
+/**
+ * why-now 卡 → plan-it 行动卡。wish_id 取卡上的结构化字段(Phase E 起
+ * WhyNowCard 必含 wish_id——从 title 字符串反解不可接受)。
+ * 非法输入(wish_id 缺失/空、session_ref 路径化)抛错:行动卡构造层
+ * 即 fail-closed,不产「点了不知道开什么」的链接。
+ */
+export function buildPlanItAction(card: WhyNowCard, deps: BuildPlanItActionDeps): PlanItAction {
+  if (typeof card?.wish_id !== 'string' || card.wish_id.length === 0) {
+    throw new Error('buildPlanItAction:card.wish_id 必须是非空字符串(WhyNowCard 结构化自指其 wish 是 plan-it 行动的前提)')
+  }
+  if (typeof deps?.session_ref !== 'string' || deps.session_ref.length === 0) {
+    throw new Error(`buildPlanItAction:session_ref 必须是非空字符串(实测 ${String(deps?.session_ref)})`)
+  }
+  const now = deps.now ?? (() => new Date())
+  const payload: SessionLinkPayload = {
+    link_id: deps.link_id ?? `plan-${now().getTime().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
+    session_ref: deps.session_ref,
+    action: 'plan_it',
+    wish_id: card.wish_id,
+    created_at: now().toISOString(),
+    ttl_seconds: deps.ttl_seconds ?? 86_400,
+  }
+  // wish_id 同源:payload.wish_id 就是上面 card.wish_id 这一个值
+  const token = signSessionLink(payload, deps.secret)
+  return {
+    kind: 'plan_it',
+    label: PLAN_IT_LABEL,
+    deep_link: formatSessionLink(token, deps.base),
+    wish_id: card.wish_id,
+  }
+}