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

package/dist/src/realtime-pricing.js

@@ -0,0 +1,103 @@
+/**
+ * 实时票价 overlay(README Known limitation「机票实时数据」清偿件):
+ * 静态包(data/flights_2026.json)仍是兜底,不再是唯一票价源——dated 航班链 spec
+ * (段带 date + route 词表内城市对)可经 FlyAI 官方只读通道(gotry_flyai_search 同源
+ * `capabilities/flyai.ts`)取实时价,按航班号精确匹配覆写 spec 价格后进求解,
+ * 证据链 `[实时API:flyai@ts]` 随行(data-sources §6)。
+ *
+ * 三值语义(永不抛错,与 hbcli/weather/opensky/anything 同构,L4 不变量):
+ *   - hit 且价正 → 覆写 + 记 evidence(静态原价留档对账);
+ *   - miss/error/打码价(如 "1xxx",非正数)/无匹配 → 段原样保留(静态价即降级);
+ *   - 查询实现注入(测试离线确定性);默认关,`GOTRY_REALTIME_PRICING=1` 开启产品面。
+ */
+import { interpretEffect } from '../capabilities/effect.js';
+/** FlyAI CLI 收中文城市名;route 提示是 IATA 码(spec 层骨架词表,与 skeleton-check 同源) */
+const IATA_TO_CITY = {
+    HKG: '香港', HKT: '普吉', BKK: '曼谷', KMG: '昆明', SZX: '深圳', DXB: '迪拜',
+    LJG: '丽江', DLU: '大理', SHA: '上海', PVG: '上海', PEK: '北京', CTU: '成都',
+};
+/**
+ * dated 航班链 spec 的实时票价覆写:
+ * - 只碰 `date`(YYYY-MM-DD)且 route 落在词表内的段;火车段(无 route 词表)原样;
+ * - 段内 option 按 service id(=航班号,大小写不敏感)与 FlyAI 条目精确匹配;
+ * - 任何失败(查询 error/miss、价格非正数、无匹配)→ 该段原样保留,绝不抛错。
+ */
+export async function overlayRealtimeFlightPrices(spec, opts = {}) {
+    const out = { spec, matched: [], notes: [] };
+    const flights = [];
+    for (const seg of spec.segments) {
+        if (!seg.date || !/^\d{4}-\d{2}-\d{2}$/.test(seg.date))
+            continue;
+        const route = seg.route;
+        if (!route || !route.includes('->'))
+            continue;
+        const [a, b] = route.split('->').map(s => IATA_TO_CITY[s.trim()]);
+        if (!a || !b)
+            continue;
+        if (seg.options.some(o => !o.move))
+            continue;
+        flights.push({ seg, date: seg.date, origin: a, destination: b });
+    }
+    if (flights.length === 0)
+        return out;
+    const query = opts.query ?? defaultQuery;
+    for (const f of flights) {
+        let result;
+        try {
+            result = await query({ kind: 'flight', origin: f.origin, destination: f.destination, depDate: f.date });
+        }
+        catch (e) {
+            out.notes.push(`${f.seg.id}: 实时票价不可用(降级静态包):${e.message?.slice(0, 80)} [实时API:flyai@error]`);
+            continue;
+        }
+        if (!result.ok || result.verdict !== 'hit' || !result.options?.length) {
+            out.notes.push(`${f.seg.id}: 实时票价未取回(${result.verdict},降级静态包) ${result.evidence}`);
+            continue;
+        }
+        const ts = /@(\d{4}-\d{2}-\d{2}T[\d:.]+Z)\]/.exec(result.evidence)?.[1] ?? new Date().toISOString();
+        const byNo = new Map();
+        for (const o of result.options) {
+            if (Number.isFinite(o.price) && o.price > 0)
+                byNo.set(o.no.toUpperCase(), o);
+        }
+        for (const opt of f.seg.options) {
+            const svc = opt.move.services[0];
+            const rt = byNo.get(svc.id.toUpperCase());
+            if (!rt)
+                continue;
+            const evidence = `[实时API:flyai@${ts}] ${rt.no} ¥${rt.price}(静态包原价 ¥${svc.priceCny})`;
+            out.matched.push({ segment: f.seg.id, option: opt.id, staticCny: svc.priceCny, realtimeCny: rt.price, evidence });
+            out.notes.push(evidence);
+            svc.priceCny = rt.price;
+        }
+    }
+    return out;
+}
+/** 默认查询面走效应解译器(ADR-18):多段行程连查享有退避重试/断路器保护——
+ * 断路拒绝(上游连环失败)时抛错,一并落在「实时票价不可用(降级静态包)」既有兜底里 */
+const defaultQuery = async (q) => {
+    const itp = await interpretEffect({ effect: 'FLYAI_SEARCH', params: { kind: q.kind, origin: q.origin, destination: q.destination, depDate: q.depDate } });
+    if (!itp.result)
+        throw new Error(itp.trace.evidence.join(';'));
+    return itp.result;
+};
+/** 求解端口包装(产品接缝):`GOTRY_REALTIME_PRICING=1`(或 opts.enabled)时 dated 航班链段
+ * 先经 FlyAI 实时价覆写,证据行并进结果 skeleton_notes;关闸/零覆写零改动,永不抛错。 */
+export function realtimeSolvePort(base, opts = {}) {
+    return async (spec) => {
+        const enabled = opts.enabled ?? process.env['GOTRY_REALTIME_PRICING'] === '1';
+        if (!enabled)
+            return base(spec);
+        try {
+            const ov = await overlayRealtimeFlightPrices(spec, opts);
+            if (ov.matched.length === 0 && ov.notes.length === 0)
+                return base(ov.spec);
+            const res = await base(ov.spec);
+            res.skeleton_notes = [...(res.skeleton_notes ?? []), ...ov.notes];
+            return res;
+        }
+        catch {
+            return base(spec); // 覆写层任何异常 → 纯静态包原路求解
+        }
+    };
+}

package/dist/src/recall/card.js

@@ -0,0 +1,74 @@
+/**
+ * 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 } from './evaluator.js';
+const ACTION_HINT = {
+    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) {
+    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)) {
+        throw new Error(`buildWhyNowCard:signal.reason 不在闭集(实测 ${String(signal.reason)};允许:${RECALL_REASONS.join(' / ')})`);
+    }
+    // 条件命中证据:all-or-nothing 校验(非空的非空字符串数组才带上;不发明、不裁剪)
+    const rawHits = trigger.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] } : {}),
+    };
+}
+/** 渲染为单行中文摘要(对话/日志面用;卡片数据仍是权威)。
+ *  必须含证据边界标记(渲染契约:每个渲染面都要展示 evidence_boundary);
+ *  卡带 match_evidence 时逐项陈述命中条件,并显式声明**不主张全部出行条件已满足**
+ *  (命中部分愿望条件只是召回资格,不是出行可行性证明)。 */
+export function renderWhyNowCardLine(card) {
+    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}`;
+}

package/dist/src/recall/evaluator.js

@@ -0,0 +1,140 @@
+/**
+ * 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 } from '../wish-pool.js';
+/** 唯一事实源:5 类原因 → 中文标签。新增原因 = 在此表加一行(union/数组自动派生;
+ *  card.ts 的 ACTION_HINT 表由 Record<RecallReason,...> 编译强制补全)。 */
+export const RECALL_REASON_LABEL = {
+    holiday_proximity: '假期临近',
+    price_drop: '价格降至阈值',
+    weather_window: '天气窗口打开',
+    route_new: '新航线/班次开通',
+    availability_recovered: '通道恢复可用',
+};
+/** 闭集数组从 label 表派生(单一事实源;不再手抄第二份) */
+export const RECALL_REASONS = Object.keys(RECALL_REASON_LABEL);
+/**
+ * 评估:候选 × 信号 → 触发列表。
+ * 两道门,先资格后匹配:
+ *   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, ctx) {
+    // 容器与时钟守卫:一个坏 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 = [];
+    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 = [];
+    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.includes(entry.wish_id))
+            : 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, ctx) {
+    try {
+        return scoreWishMatch(entry, ctx);
+    }
+    catch {
+        return null;
+    }
+}
+/** match_context 运行时校验(JSON 往返边界强制):非数组对象 + 数值字段(若给出)
+ *  必须是有限数字 + channelDown(若给出非 null)必须具备 has 方法(Set 形)。
+ *  与 scoreWishMatch 的缺省语义对齐:channelDown 缺省/null = 不启用通道否证。 */
+function isWishMatchContext(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const c = value;
+    for (const k of ['days', 'budgetCny', 'month']) {
+        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.has !== 'function')
+        return false;
+    return true;
+}
+/** 信号校验(边界强制,不从输入信任):reason 在闭集 + source 非空字符串 +
+ *  current_value/threshold 为字符串 + **wish_ids 一旦给出必须是字符串数组**
+ * (字符串等真值非数组 = 畸形,拒绝——绝不降级广播)。 */
+function isRecallSignal(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const s = value;
+    if (!RECALL_REASONS.includes(s.reason))
+        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/dist/src/recall/integration.js

@@ -0,0 +1,17 @@
+/**
+ * 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 { evaluateRecallTriggers } from './evaluator.js';
+import { buildWhyNowCard } from './card.js';
+/** 从 wish-pool + tick + signals + 召回窗口跑一轮评估并产卡(纯函数编排) */
+export function evaluatePoolRecall(input) {
+    const ctx = { 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/dist/src/recall/tick.js

@@ -0,0 +1,166 @@
+/**
+ * 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)。
+ */
+/** 测试用 InMemory tick source:预排好的一组 tick,按序返回,耗尽返回 null。
+ *  构造与 next() 均防御式深拷贝(调用方改返回的 tick.at 不会污染队列快照)。 */
+export class InMemoryTickSource {
+    queue;
+    constructor(ticks) {
+        this.queue = ticks.map(t => ({ at: new Date(t.at.getTime()), source: t.source }));
+    }
+    async next() {
+        const t = this.queue.shift();
+        if (t === undefined)
+            return null;
+        return { at: new Date(t.at.getTime()), source: t.source }; // 返回副本,调用方可安全改
+    }
+}
+/**
+ * 周期 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 {
+    enabled;
+    intervalMs;
+    sourceLabel;
+    maxPending;
+    timer = null;
+    pending = [];
+    waiters = [];
+    constructor(opts) {
+        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() {
+        if (!this.enabled)
+            return 'disabled';
+        if (this.timer !== null)
+            return 'already-running';
+        this.timer = setInterval(() => {
+            const tick = { 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);
+        this.timer.unref?.();
+        return 'started';
+    }
+    /** 停止(幂等):清 timer + **清空 pending(重启不吐陈旧 tick)+ 等待者全部以 null 唤醒**(终结核平) */
+    stop() {
+        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() {
+        return this.pending.length;
+    }
+    /** **运行中**阻塞到下一个 tick;**未运行**(disabled/未 start/已 stop)返回 null(流终结) */
+    async next() {
+        if (this.timer === null)
+            return null;
+        const queued = this.pending.shift();
+        if (queued !== undefined)
+            return queued;
+        return new Promise(resolve => {
+            this.waiters.push(resolve);
+        });
+    }
+}
+/** 数组收集 sink(测试用) */
+export class ArrayRecallSink {
+    items = [];
+    deliver(card) {
+        this.items.push(card);
+    }
+}
+/**
+ * 编排器:拉 tick → 评估 → 转卡 → 送 sink。
+ * 每次 run 处理一个 tick(调用方决定循环;scheduler 自己不循环——不悄悄长驻)。
+ * **永不抛错**:evaluate 抛错 → {delivered:0, failed:0, error 记入 errors};
+ * 单卡 toCard/deliver 抛错 → 只弃该卡(failed++/errors 记一条),余下继续。
+ */
+export class RecallTickScheduler {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async run(tick) {
+        const errors = [];
+        let evaluations;
+        try {
+            evaluations = this.deps.evaluate(tick);
+            if (!Array.isArray(evaluations))
+                evaluations = [];
+        }
+        catch (err) {
+            return { delivered: 0, failed: 0, errors: [`evaluate: ${err?.message ?? String(err)}`] };
+        }
+        let delivered = 0;
+        let failed = 0;
+        for (const evaluation of evaluations) {
+            let card;
+            try {
+                card = this.deps.toCard(evaluation, tick);
+            }
+            catch (err) {
+                failed++;
+                if (errors.length < 4)
+                    errors.push(`toCard: ${err?.message ?? String(err)}`);
+                continue;
+            }
+            try {
+                await this.deps.sink.deliver(card);
+                delivered++;
+            }
+            catch (err) {
+                failed++;
+                if (errors.length < 4)
+                    errors.push(`deliver: ${err?.message ?? String(err)}`);
+            }
+        }
+        return errors.length > 0 ? { delivered, failed, errors } : { delivered, failed };
+    }
+}

package/dist/src/session-link/plan-it-action.js

@@ -0,0 +1,48 @@
+/**
+ * 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 { formatSessionLink, signSessionLink } from './session-link.js';
+/** plan-it 行动文案(封闭词汇) */
+export const PLAN_IT_LABEL = '好,规划它';
+/**
+ * why-now 卡 → plan-it 行动卡。wish_id 取卡上的结构化字段(Phase E 起
+ * WhyNowCard 必含 wish_id——从 title 字符串反解不可接受)。
+ * 非法输入(wish_id 缺失/空、session_ref 路径化)抛错:行动卡构造层
+ * 即 fail-closed,不产「点了不知道开什么」的链接。
+ */
+export function buildPlanItAction(card, deps) {
+    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 = {
+        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,
+    };
+}