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

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,
+    };
+}

package/dist/src/session-link/session-link.js

@@ -0,0 +1,248 @@
+/**
+ * Session link token 签发/校验(issue #580,Phase E;研究决策见
+ * docs/research/karpo-deck-web-research.md §3 Phase E——one-tap 深链回本地
+ * session,不碰写路径,WriteGate 保持 sealed;消费端注册是 M4 激活)。
+ *
+ * HMAC-SHA256 over base64url(payload-json),签名为 base64url。
+ * Token 形如 `${body}.${sig}`(body = base64url(JSON.stringify(payload)))。
+ *
+ * 与 share-token(Phase C)的差异(刻意,非偶然):
+ *   - **schema 闭集到未知键拒绝**:verify 对 payload 里出现 schema 之外的键
+ *     直接 link_invalid——session link 是「de-identified by construction」面,
+ *     链接只携带引用(link_id/session_ref/wish_id)不携带事实/记忆,闭集
+ *     schema 让这句承诺变成可测试字面真(share token 允许附加键,因为 share
+ *     manifest 本身就需要开放扩展;两者威胁模型不同,不共享校验器);
+ *   - **action 词位闭集 = WriteGate 链接层结构性封死**:`plan_it` | `open`,
+ *     词位里不存在 book/pay/confirm——任何写动词连构造都构造不出来
+ *     (sign 层抛错,不只是 verify 层拒绝);
+ *   - **plan_it ⇔ wish_id 成对**:`plan_it` 必须带非空 wish_id(防「规划
+ *     空 wish」退化),`open` 必须不带(防通用打开链接夹带定向意图);
+ *   - **session_ref 路径护栏**:不透明引用,拒绝含 `/` `\` `..` NUL——
+ *     「不写共享状态」的链接层版:链接永远无法命名 state 路径;
+ *   - 失败闭集只有 2 类(`link_invalid` | `link_expired`)——session link
+ *     无 channel/adapter/consent 维度,不需要 share 的 8 类;
+ *   - token 不进 URL:scheme/宿主是消费端渲染期选择(`formatSessionLink`),
+ *     链接产物跨消费端可移植,签名载荷不含宿主细节。
+ *
+ * 硬化清单与 share-token 同源:恰一个点、timingSafeEqual(先长度)、
+ * ttl 非负整数上限 2^31-1(防 expiresMs 溢出 Infinity 永不过期)、
+ * 时间注入(测试不依赖 wall clock)、secret 缺省且 NODE_ENV=production
+ * 时 fail-closed(绝不静默用仓库里公开的 dev 常量签生产链接)——刻意抛错
+ * 保留在签发面(resolve/sign);verify 面把同样的配置错误收敛为 link_invalid,
+ * 不让异常越出「永不抛错」的校验边界。注入时钟本身失效(getTime 非有限值
+ * 或回调抛错)→ fail-closed link_invalid:NaN 与 expiresMs 比较恒 false,
+ * 曾把过期链接静默判成有效——无效时间上不产生任何接受。verify 期 secret
+ * 为非字符串运行期键(数字/对象/Symbol 等 JS 畸形输入)同样收敛 link_invalid,
+ * HMAC 计算本身也在守卫内——任何调用方/配置输入都无法越出「永不抛错」边界。
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/** 行动闭集:`plan_it`(回 session 继续规划某条 wish)| `open`(通用打开)。
+ *  **词位即安全边界**——新增行动先 review;book/pay/confirm 等写动词
+ *  永不入集(WriteGate sealed 在链接层的结构性表达)。 */
+export const SESSION_LINK_ACTIONS = ['plan_it', 'open'];
+/** 显式 dev 默认 secret——生产环境必须由 `SESSION_LINK_HMAC_SECRET` env 覆盖 */
+export const DEFAULT_DEV_SESSION_LINK_SECRET = 'gotry-session-link-dev-secret-DO-NOT-USE-IN-PROD';
+/** ttl 上界(秒):2^31-1,防 created_at + ttl*1000 溢出 Number 上限 */
+export const SESSION_LINK_TTL_MAX_SECONDS = 2_147_483_647;
+/** payload schema 的键闭集(verify 用:未知键 → link_invalid) */
+const PAYLOAD_KEYS = ['link_id', 'session_ref', 'action', 'wish_id', 'created_at', 'ttl_seconds'];
+/** 获取运行期 secret:env 优先;production 缺 env 时 fail-closed */
+export function resolveSessionLinkSecret(env = process.env) {
+    const s = env.SESSION_LINK_HMAC_SECRET;
+    if (typeof s === 'string' && s.length > 0)
+        return s;
+    if (env.NODE_ENV === 'production') {
+        throw new Error('SESSION_LINK_HMAC_SECRET 未设置且 NODE_ENV=production:拒绝回落公开的 dev 默认 secret(fail-closed;任何读到仓库的人都能伪造 session link)');
+    }
+    return DEFAULT_DEV_SESSION_LINK_SECRET;
+}
+/** session_ref 路径护栏:不透明引用——含路径分隔/上跳/NUL 即拒(链接永远无法命名 state 路径) */
+function isSafeSessionRef(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= 128
+        && !value.includes('/') && !value.includes('\\') && !value.includes('..')
+        && !value.includes('\0');
+}
+/** 签发:payload 校验(闭集 action / plan_it⇔wish_id 成对 / session_ref 护栏 / ttl 上界)
+ *  不过期检查由 verify 做(签名时刻的时钟是消费端的)。非法 payload 抛错——
+ *  构造层把坏链接挡在签名之前,不是等到校验才发现。 */
+export function signSessionLink(payload, secret = resolveSessionLinkSecret()) {
+    if (typeof payload !== 'object' || payload === null) {
+        throw new Error(`signSessionLink:payload 必须是对象(实测 ${String(payload)})`);
+    }
+    if (typeof payload.link_id !== 'string' || payload.link_id.length === 0) {
+        throw new Error('signSessionLink:link_id 必须是非空字符串');
+    }
+    if (!isSafeSessionRef(payload.session_ref)) {
+        throw new Error(`signSessionLink:session_ref 必须是不含路径分隔符的不透明引用(实测 ${String(payload.session_ref)})`);
+    }
+    if (!SESSION_LINK_ACTIONS.includes(payload.action)) {
+        throw new Error(`signSessionLink:action 不在闭集(实测 ${String(payload.action)};允许:${SESSION_LINK_ACTIONS.join(' / ')})。写动词(book/pay/confirm)永不入集——WriteGate 在链接层结构性封死`);
+    }
+    // plan_it ⇔ wish_id 成对(双向:plan_it 必须有目标;open 必须不夹带定向意图)
+    if (payload.action === 'plan_it' && (typeof payload.wish_id !== 'string' || payload.wish_id.length === 0)) {
+        throw new Error('signSessionLink:action=plan_it 必须携带非空 wish_id(否则「规划」无对象,是退化链接)');
+    }
+    if (payload.action === 'open' && payload.wish_id !== undefined) {
+        throw new Error('signSessionLink:action=open 必须不携带 wish_id(通用打开链接夹带定向意图 = 混淆行动语义)');
+    }
+    if (typeof payload.created_at !== 'string' || payload.created_at.length === 0 || !Number.isFinite(Date.parse(payload.created_at))) {
+        throw new Error('signSessionLink:created_at 必须是可解析的 ISO 时间字符串');
+    }
+    if (typeof payload.ttl_seconds !== 'number' || !Number.isInteger(payload.ttl_seconds)
+        || payload.ttl_seconds < 0 || payload.ttl_seconds > SESSION_LINK_TTL_MAX_SECONDS) {
+        throw new Error(`signSessionLink:ttl_seconds 必须为 0..${SESSION_LINK_TTL_MAX_SECONDS} 的整数(实测 ${String(payload.ttl_seconds)})`);
+    }
+    // 序列化前剥掉 undefined 键(wish_id 缺省时),保证 body 可复现
+    const clean = {};
+    const raw = payload;
+    for (const k of PAYLOAD_KEYS) {
+        const v = raw[k];
+        if (v !== undefined)
+            clean[k] = v;
+    }
+    const body = Buffer.from(JSON.stringify(clean), 'utf-8').toString('base64url');
+    const sig = createHmac('sha256', secret).update(body).digest('base64url');
+    return `${body}.${sig}`;
+}
+/** 校验:secret 解析(守卫体)→ 格式(恰一个点)→ HMAC 等值(timingSafeEqual)
+ *  → schema 闭集(未知键拒绝)→ 字段形态 → plan_it⇔wish_id 成对 → session_ref
+ *  护栏 → 过期(注入时钟失效 = link_invalid)。**永不抛错**:production 缺 env
+ *  secret 与失效时钟都是操作面错误,收敛进 link_invalid(消费端拿到 link_invalid
+ *  只能 fail-closed 不打开任何 session),刻意的配置/签发异常只保留在 resolve/sign 侧。 */
+export function verifySessionLink(token, secret, now = () => new Date()) {
+    // 运行期 secret 解析放进守卫体:production 缺 env 的配置错在验证面 fail-closed
+    // 为 link_invalid,不抛错(若静默回落公开 dev 常量,伪造链接将被放行);
+    // 非字符串运行期键(数字/对象/Symbol 等 JS 畸形调用方输入)同样收敛
+    // link_invalid——createHmac 对它们会抛 TypeError,绝不让异常越出本函数
+    let hmacSecret;
+    try {
+        const resolved = secret === undefined ? resolveSessionLinkSecret() : secret;
+        if (typeof resolved !== 'string')
+            return { ok: false, reason: 'link_invalid' };
+        hmacSecret = resolved;
+    }
+    catch {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    if (typeof token !== 'string' || token.length === 0)
+        return { ok: false, reason: 'link_invalid' };
+    const dot = token.indexOf('.');
+    // 恰一个点:多点(base64url 解码器会静默吞非法字符)与无点都拒绝
+    if (dot <= 0 || dot === token.length - 1)
+        return { ok: false, reason: 'link_invalid' };
+    if (token.indexOf('.', dot + 1) !== -1)
+        return { ok: false, reason: 'link_invalid' };
+    const body = token.slice(0, dot);
+    const sig = token.slice(dot + 1);
+    // HMAC 等值比较(先长度,再 timingSafeEqual;Buffer-vs-Buffer);加密计算
+    // 本身也在守卫内——任何运行期键异常收敛 link_invalid,绝不外泄异常
+    let expected;
+    try {
+        expected = createHmac('sha256', hmacSecret).update(body).digest();
+    }
+    catch {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    let actual;
+    try {
+        actual = Buffer.from(sig, 'base64url');
+    }
+    catch {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    // 解析 payload
+    let payload;
+    try {
+        const json = Buffer.from(body, 'base64url').toString('utf-8');
+        payload = JSON.parse(json);
+    }
+    catch {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    // schema 闭集:未知键拒绝(de-identified by construction 的可测试形式)
+    for (const key of Object.keys(payload)) {
+        if (!PAYLOAD_KEYS.includes(key))
+            return { ok: false, reason: 'link_invalid' };
+    }
+    // 字段形态
+    if (typeof payload.link_id !== 'string' || payload.link_id.length === 0
+        || !isSafeSessionRef(payload.session_ref)
+        || typeof payload.action !== 'string' || !SESSION_LINK_ACTIONS.includes(payload.action)
+        || typeof payload.created_at !== 'string' || payload.created_at.length === 0) {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    // plan_it ⇔ wish_id 成对(与 sign 同规则,双向)
+    if (payload.action === 'plan_it' && (typeof payload.wish_id !== 'string' || payload.wish_id.length === 0)) {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    if (payload.action === 'open' && payload.wish_id !== undefined) {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    // ttl:非负整数且不溢出(防 created_at + ttl*1000 = Infinity 永不过期)
+    const ttl = payload.ttl_seconds;
+    if (typeof ttl !== 'number' || !Number.isInteger(ttl) || ttl < 0 || ttl > SESSION_LINK_TTL_MAX_SECONDS) {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    const createdMs = Date.parse(payload.created_at);
+    if (!Number.isFinite(createdMs))
+        return { ok: false, reason: 'link_invalid' };
+    const expiresMs = createdMs + ttl * 1000;
+    if (!Number.isFinite(expiresMs))
+        return { ok: false, reason: 'link_invalid' };
+    // 注入时钟失效(抛错/非有限值)fail-closed 为 link_invalid——
+    // NaN 与 expiresMs 比较恒 false,失效时钟不得让任何链接通过
+    let nowMs;
+    try {
+        nowMs = now().getTime();
+    }
+    catch {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    if (!Number.isFinite(nowMs))
+        return { ok: false, reason: 'link_invalid' };
+    if (nowMs > expiresMs)
+        return { ok: false, reason: 'link_expired' };
+    return { ok: true, payload: payload };
+}
+/** 默认深链 base(scheme handler 注册是 M4 激活;消费端可传自己的 base) */
+export const DEFAULT_SESSION_LINK_BASE = 'gotry://session';
+/** 渲染期拼 URL:`${base}/${token}`——token 不进 URL 的签名,宿主是消费端选择 */
+export function formatSessionLink(token, base = DEFAULT_SESSION_LINK_BASE) {
+    if (typeof token !== 'string' || token.length === 0) {
+        throw new Error('formatSessionLink:token 必须是非空字符串');
+    }
+    if (typeof base !== 'string' || base.length === 0 || base.endsWith('/')) {
+        throw new Error(`formatSessionLink:base 必须是非空字符串且不以 '/' 结尾(实测 ${String(base)})`);
+    }
+    if (base.includes('?') || base.includes('#')) {
+        throw new Error('formatSessionLink:base 不得含 query/hash(产出即 parseSessionLink 拒绝的形态,锋利边角)');
+    }
+    return `${base}/${token}`;
+}
+/** 从 URL 严格反解 token:路径最后一段,且段本身须呈 `body.sig` 形态(恰
+ *  一个非空 body、非空 sig;段内多点由 verify 终裁——本函数只保证不把一个
+ *  裸 base(`gotry://session`)的最后一段误当 token)。**拒绝 query/hash**——
+ *  拼接歧义(如 `?x=../../etc`)一律 fail-closed;形态不符返回 null(消费端
+ *  不打开)。 */
+export function parseSessionLink(url) {
+    if (typeof url !== 'string' || url.length === 0)
+        return null;
+    const q = url.indexOf('?');
+    const h = url.indexOf('#');
+    if (q !== -1 || h !== -1)
+        return null;
+    const segments = url.split('/').filter(s => s.length > 0);
+    const token = segments[segments.length - 1];
+    if (segments.length < 2 || token === undefined || token.length === 0)
+        return null;
+    const dot = token.indexOf('.');
+    if (dot <= 0 || dot === token.length - 1)
+        return null;
+    return token;
+}