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

package/dist/src/turn-deadline.js

@@ -0,0 +1,287 @@
+/**
+ * Per-agent, per-turn wall-clock boundary driven by routing (ADR-24 v2).
+ *
+ * 职责只有一件:保证每一轮终结在三态之一——当面答完(converge)、转后台
+ * 并给出回访承诺(handoff)、或明确暂停。绝不允许第四态:流死掉、什么
+ * 都没交付(2026-09-02 轨迹的失败形态)。
+ *
+ * - 阈值不再固定:每次 user/message 由 `turn-policy.ts` 的确定性分类器
+ *   解析 TurnPolicy(softMs/hardMs/exit);benchmark opt-in 用 fixedPolicy
+ *   钉死以保证可复现。
+ * - 硬阈拒绝时**同步**抑制工具 schema(防同 step 回环),并按 exit 语义
+ *   返回两种结构化结果:converge=用已有证据作答;handoff=落
+ *   `gotry_turn_handoff.v1` 工单并指令模型告知用户 ETA 与回访方式。
+ * - handoff 工单是**新的独立格式**,落在 `<stateRoot>/gotry-state/
+ *   turn-handoffs/`,不与 `async/` 的 loop 求解工单混用——async-collect
+ *   对无 spec 的 state 会立即结算 failed(假失败),收集器是未来的
+ *   agent tick(loopx),不是 async-collect。
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { classifyTurn, TURN_HANDOFF_ETA_LABEL, turnPolicyFor } from './turn-policy.js';
+export const TURN_DEADLINE_SOFT = 'TURN_DEADLINE_SOFT';
+export const TURN_DEADLINE_EXHAUSTED = 'TURN_DEADLINE_EXHAUSTED';
+export const TURN_DEADLINE_HANDOFF = 'TURN_DEADLINE_HANDOFF';
+export const TURN_HANDOFF_SCHEMA = 'gotry_turn_handoff.v1';
+export async function writeTurnHandoffTicket(stateRoot, userMessage) {
+    const ticket = {
+        schema: TURN_HANDOFF_SCHEMA,
+        id: `th-${Date.now().toString(36)}-${randomUUID().slice(0, 6)}`,
+        objective: userMessage.length > 120 ? `${userMessage.slice(0, 120)}…` : userMessage,
+        userMessage,
+        requestedAt: new Date().toISOString(),
+        etaLabel: TURN_HANDOFF_ETA_LABEL,
+        status: 'open',
+    };
+    await writeTicketJson(stateRoot, ticket);
+    return ticket;
+}
+function handoffDir(stateRoot) {
+    const root = stateRoot === '.' ? process.cwd() : stateRoot;
+    return join(root, 'gotry-state', 'turn-handoffs');
+}
+async function writeTicketJson(stateRoot, ticket) {
+    const dir = handoffDir(stateRoot);
+    await mkdir(dir, { recursive: true });
+    const path = join(dir, `${ticket.id}.json`);
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, JSON.stringify(ticket, null, 2), 'utf-8');
+    await rename(tmp, path);
+    return path;
+}
+/**
+ * 结算工单:交付物落 `<id>.deliverable.md`(settled=规划产物;failed=诚实
+ * 失败说明),工单 json 原子更新 status/settledAt/deliverableFile/error。
+ */
+export async function settleTurnHandoffTicket(stateRoot, ticket, status, deliverable, error) {
+    const dir = handoffDir(stateRoot);
+    await mkdir(dir, { recursive: true });
+    const deliverablePath = join(dir, `${ticket.id}.deliverable.md`);
+    const deliverableTmp = `${deliverablePath}.tmp`;
+    await writeFile(deliverableTmp, deliverable, 'utf-8');
+    await rename(deliverableTmp, deliverablePath);
+    const settled = {
+        ...ticket,
+        status,
+        settledAt: new Date().toISOString(),
+        deliverableFile: `${ticket.id}.deliverable.md`,
+        ...(error ? { error } : {}),
+    };
+    const ticketPath = await writeTicketJson(stateRoot, settled);
+    return { ticketPath, deliverablePath };
+}
+/** 复访查询:按请求时间倒序列出工单;settled 附交付物摘录(≤600 字)。 */
+export async function listTurnHandoffTickets(stateRoot) {
+    const dir = handoffDir(stateRoot);
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const views = [];
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            const raw = JSON.parse(await readFile(join(dir, name), 'utf-8'));
+            if (raw?.schema !== TURN_HANDOFF_SCHEMA)
+                continue;
+            const view = {
+                id: raw.id,
+                status: raw.status,
+                objective: raw.objective,
+                requestedAt: raw.requestedAt,
+                etaLabel: raw.etaLabel,
+                ...(raw.settledAt ? { settledAt: raw.settledAt } : {}),
+                ...(raw.error ? { error: raw.error } : {}),
+            };
+            if (raw.status !== 'open' && raw.deliverableFile) {
+                try {
+                    const text = await readFile(join(dir, raw.deliverableFile), 'utf-8');
+                    view.deliverableExcerpt = text.length > 600 ? `${text.slice(0, 600)}…` : text;
+                }
+                catch { /* 交付物缺失时视图降级,不阻塞列表 */ }
+            }
+            views.push(view);
+        }
+        catch { /* 单个坏工单不阻塞列表 */ }
+    }
+    views.sort((a, b) => (a.requestedAt < b.requestedAt ? 1 : -1));
+    return views;
+}
+function resolveEnvPin(name) {
+    const raw = process.env[name];
+    if (!raw)
+        return null;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+function convergenceContext(code, text) {
+    return {
+        id: randomUUID(),
+        role: 'user',
+        content: [{ type: 'text', text: `${code}: ${text}` }],
+        // 0.2.0-rc.2(V4 会话格式)移除 'plugin' source kind;运行时自产注入归 system-prompt。
+        source: { kind: 'system-prompt' },
+    };
+}
+function exhaustionResult(reason) {
+    return {
+        isError: true,
+        error: {
+            message: reason,
+            info: { name: 'TurnDeadlineError', code: TURN_DEADLINE_EXHAUSTED },
+        },
+        content: [{ type: 'text', text: reason }],
+        additionalContexts: [convergenceContext(TURN_DEADLINE_EXHAUSTED, 'No more tool dispatches are permitted in this turn. Produce the final answer from existing results.')],
+    };
+}
+function handoffResult(ticket) {
+    const instruction = `Turn handed off to background planning. Async ticket ${ticket.id} created (ETA ${ticket.etaLabel}). Stop dispatching tools and tell the user in one short message: the deep planning continues in the background, the expected time, and to check back later (mention ticket ${ticket.id}).`;
+    return {
+        isError: true,
+        error: {
+            message: `${TURN_DEADLINE_HANDOFF}: sync window exhausted for a deep-planning turn; ticket ${ticket.id}`,
+            info: { name: 'TurnDeadlineHandoff', code: TURN_DEADLINE_HANDOFF },
+        },
+        content: [{ type: 'text', text: `${TURN_DEADLINE_HANDOFF}: ${instruction}` }],
+        additionalContexts: [convergenceContext(TURN_DEADLINE_HANDOFF, instruction)],
+    };
+}
+/**
+ * Install the runtime boundary, kept separate from the GoTry tool catalog so
+ * the actual Cordis waterfalls can be exercised without booting every tool.
+ */
+export function installTurnDeadline(ctx, options = {}) {
+    if (options.enabled === false)
+        return;
+    // Some offline contract tests intentionally provide a registration-only
+    // Context slice. They do not drive an agent loop, so there is no boundary
+    // to install and no reason to require an event bus.
+    if (typeof ctx.on !== 'function')
+        return;
+    const now = options.now ?? (() => Date.now());
+    // Test/benchmark seam only: pin the resolved numbers without touching the
+    // routed exit strategy. Product runs never set these.
+    const softPin = resolveEnvPin('GOTRY_TURN_DEADLINE_SOFT_MS');
+    const hardPin = resolveEnvPin('GOTRY_TURN_DEADLINE_HARD_MS');
+    const defaultPolicy = options.fixedPolicy ?? turnPolicyFor('sync-planning');
+    const routePolicy = (message) => {
+        if (options.fixedPolicy)
+            return { ...options.fixedPolicy };
+        const policy = turnPolicyFor(classifyTurn(message));
+        return { ...policy, softMs: softPin ?? policy.softMs, hardMs: hardPin ?? policy.hardMs };
+    };
+    const stateByAgent = new Map();
+    const softExecutions = new Map();
+    const finalOnlyDisposers = new Map();
+    const clearAgent = (agentId) => {
+        stateByAgent.delete(agentId);
+        for (const [token, owner] of softExecutions) {
+            if (owner.agentId === agentId)
+                softExecutions.delete(token);
+        }
+        finalOnlyDisposers.get(agentId)?.();
+        finalOnlyDisposers.delete(agentId);
+    };
+    const enterFinalOnly = (agent) => {
+        const agentId = String(agent.id);
+        if (finalOnlyDisposers.has(agentId))
+            return;
+        const globalTools = ctx.tools;
+        const scopedTools = agent.ctx?.tools;
+        if (typeof globalTools.schemas !== 'function' || typeof scopedTools?.restrict !== 'function') {
+            // No registry to suppress: subsequent tool calls in the same turn hit the
+            // same per-call denial branch and stay refused until the next turn.
+            return;
+        }
+        const inheritedNames = globalTools.schemas()
+            .map(schema => schema.name)
+            .filter(name => name !== 'run_code');
+        if (inheritedNames.length === 0)
+            return;
+        finalOnlyDisposers.set(agentId, scopedTools.restrict({ deny: inheritedNames }));
+    };
+    // 事件主体是 session 对象;agent 归属同一 session 时共用同一预算键。
+    const keyOfAgent = (agent) => {
+        const session = agent.session;
+        return String(session?.id ?? agent.id);
+    };
+    ctx.on('session/event', (subject, event) => {
+        const agentId = String(subject.id);
+        if (event.type === 'turn/end') {
+            clearAgent(agentId);
+            return;
+        }
+        if (event.type === 'turn/start') {
+            finalOnlyDisposers.get(agentId)?.();
+            finalOnlyDisposers.delete(agentId);
+            if (!stateByAgent.has(agentId)) {
+                stateByAgent.set(agentId, {
+                    startedAt: now(),
+                    policy: { ...defaultPolicy, softMs: softPin ?? defaultPolicy.softMs, hardMs: hardPin ?? defaultPolicy.hardMs },
+                });
+            }
+            return;
+        }
+        if (event.type === 'user/message') {
+            // dsh 事件载荷在 event.data 下(benchmark-agent-conformance 同型读法)。
+            const message = event.data;
+            if (message?.source?.kind !== 'user')
+                return;
+            const text = (message.content ?? []).find(block => block.type === 'text')?.text ?? '';
+            if (!text.trim())
+                return;
+            // 每个 user 消息 = 新的预算:路由分类 + 时钟重置。plugin/skill 注入
+            // 的 user/message(source.kind !== 'user')不参与路由。
+            stateByAgent.set(agentId, { startedAt: now(), policy: routePolicy(text), userMessage: text });
+        }
+    });
+    ctx.on('session/disposed', subject => clearAgent(String(subject.id)));
+    ctx.on('tools/execute', (exec, next) => {
+        // Programmatic/direct calls are not part of a model planner turn.
+        if (!exec.agent)
+            return next();
+        const agentId = keyOfAgent(exec.agent);
+        const state = stateByAgent.get(agentId)
+            ?? { startedAt: now(), policy: { ...defaultPolicy, softMs: softPin ?? defaultPolicy.softMs, hardMs: hardPin ?? defaultPolicy.hardMs } };
+        stateByAgent.set(agentId, state);
+        const elapsed = now() - state.startedAt;
+        if (elapsed > state.policy.hardMs) {
+            // Synchronous schema suppression so same-step follow-up calls cannot
+            // loop on refusal results (the 2026-09-02 trajectory failure).
+            enterFinalOnly(exec.agent);
+            if (state.policy.exit === 'handoff' && state.userMessage && options.stateRoot) {
+                return writeTurnHandoffTicket(options.stateRoot, state.userMessage)
+                    .then(ticket => handoffResult(ticket))
+                    .catch(() => exhaustionResult(`${TURN_DEADLINE_EXHAUSTED}: hard deadline ${state.policy.hardMs}ms reached (ticket persistence failed; degraded to converge)`));
+            }
+            return Promise.resolve(exhaustionResult(`${TURN_DEADLINE_EXHAUSTED}: turn exceeded hard deadline of ${state.policy.hardMs}ms (elapsed ${elapsed}ms); provide a final answer using existing results`));
+        }
+        if (elapsed > state.policy.softMs) {
+            softExecutions.set(exec.token, { agentId, exit: state.policy.exit });
+        }
+        return next();
+    });
+    ctx.on('tools/post-execute', (exec, _result, next) => {
+        return next().then(decision => {
+            const owner = softExecutions.get(exec.token);
+            if (!owner)
+                return decision;
+            softExecutions.delete(exec.token);
+            const text = owner.exit === 'handoff'
+                ? 'Turn has crossed the soft deadline of a deep-planning turn. Wrap up context gathering now; the turn will hand off to background planning at the hard deadline.'
+                : 'Turn has crossed the soft deadline. Stop dispatching new tools and produce the final answer from gathered evidence.';
+            return {
+                ...decision,
+                additionalContexts: [
+                    ...(decision.additionalContexts ?? []),
+                    convergenceContext(TURN_DEADLINE_SOFT, text),
+                ],
+            };
+        });
+    });
+}

package/dist/src/turn-policy.js

@@ -0,0 +1,118 @@
+/**
+ * Per-turn routing & time allocation (ADR-24 v2).
+ *
+ * 用户主观时间是产品路径唯一的预算:复杂度决定**出口结构**(converge /
+ * handoff),时间只是在所选结构内的资源分配。路由在 user/message 落地时
+ * 一次完成,纯函数、零 LLM、零 IO——控制面判定必须是确定性组件
+ * (stage1 责任铁律;ADR-9 同型先例),且不能花它要分配的资源。
+ *
+ * Tier 0(消息内禀)是 v1 的全部规则输入;Tier 1(账本读回)只在
+ * handoff 落单时用于工单上下文,不参与分类。`loop.ts` 的 isComplex 是
+ * S5 循环架构内的访谈后复核,不在产品路径上,不进本层。
+ */
+/** v1 阈值表:数据不是代码;评测/部署换表不换执行器。 */
+export const TURN_POLICIES = {
+    // quick:实际上限只是安全网——quick 类历史上没有发散记录。
+    quick: { softMs: 120_000, hardMs: 180_000, exit: 'converge' },
+    'sync-planning': { softMs: 300_000, hardMs: 600_000, exit: 'converge' },
+    // deep-planning:同步窗口只够"摸底 + 落单承诺",到点必须转后台。
+    'deep-planning': { softMs: 120_000, hardMs: 240_000, exit: 'handoff' },
+};
+export const TURN_HANDOFF_ETA_LABEL = '约 1 小时';
+/** 约束词表:只作弱信号(命中≥2 才可能推 deep);新增词=加一行+一测。 */
+export const TURN_CONSTRAINT_LEXICON = [
+    '婚礼', '婚宴', '回门', '订婚',
+    'IRW', 'irw',
+    '请假', '年假', '调休', '额度',
+    '签证', '同行', '伴侣', '亲子', '带娃', '父母', '团建', '出差',
+    '红眼', '中转', '联程', '多城',
+];
+const CN_DIGITS = {
+    一: 1, 二: 2, 两: 2, 三: 3, 四: 4, 五: 5, 六: 6, 七: 7, 八: 8, 九: 9, 十: 10,
+};
+function dayCount(year, month, day) {
+    // 无年份时按平年锚定:跨度计算只需要差值,月份跨年场景 v1 不覆盖。
+    const y = year ?? 1970;
+    return Date.UTC(y, month - 1, day) / 86_400_000;
+}
+/** 跨度词 → 估算天数;按声明强度取第一个命中,v1 不做组合。 */
+function spanWordDays(message) {
+    if (/十几天/.test(message))
+        return 12;
+    if (/半个月/.test(message))
+        return 15;
+    if (/一个月/.test(message))
+        return 30;
+    const week = message.match(/[一两]个?(?:星期|周)/);
+    if (week)
+        return week[0].startsWith('两') ? 14 : 7;
+    const dayMatch = message.match(/([0-9一二两三四五六七八九十]+)\s*天/);
+    if (dayMatch) {
+        const raw = dayMatch[1];
+        if (/^[0-9]+$/.test(raw))
+            return Math.min(Number.parseInt(raw, 10), 60);
+        if (CN_DIGITS[raw] !== undefined)
+            return Math.min(CN_DIGITS[raw], 60);
+    }
+    return null;
+}
+export function extractTurnSignals(message) {
+    const absoluteDates = [];
+    // 完整日期先摘除,避免 2026-10-03 再被月/日模式重复计数。
+    let rest = message.replace(/(?<!\d)(\d{4})[年\-.\/](\d{1,2})[月\-.\/](\d{1,2})日?(?!\d)/g, (_all, y, m, d) => {
+        const month = Number.parseInt(m, 10);
+        const day = Number.parseInt(d, 10);
+        if (month >= 1 && month <= 12 && day >= 1 && day <= 31) {
+            absoluteDates.push({ year: Number.parseInt(y, 10), month, day });
+        }
+        return ' ';
+    });
+    rest = rest.replace(/(?<!\d)(\d{1,2})月(\d{1,2})日?(?!\d)/g, (_all, m, d) => {
+        const month = Number.parseInt(m, 10);
+        const day = Number.parseInt(d, 10);
+        if (month >= 1 && month <= 12 && day >= 1 && day <= 31) {
+            absoluteDates.push({ year: null, month, day });
+        }
+        return ' ';
+    });
+    rest = rest.replace(/(?<!\d)(\d{1,2})[.\/](\d{1,2})(?!\d)/g, (_all, m, d) => {
+        const month = Number.parseInt(m, 10);
+        const day = Number.parseInt(d, 10);
+        if (month >= 1 && month <= 12 && day >= 1 && day <= 31) {
+            absoluteDates.push({ year: null, month, day });
+        }
+        return ' ';
+    });
+    const constraintHits = TURN_CONSTRAINT_LEXICON.filter(word => message.includes(word));
+    let spanDays = null;
+    if (absoluteDates.length >= 2) {
+        const counts = absoluteDates.map(d => dayCount(d.year, d.month, d.day));
+        spanDays = Math.max(...counts) - Math.min(...counts);
+    }
+    else {
+        spanDays = spanWordDays(message);
+    }
+    return { messageLength: message.length, absoluteDates, spanDays, constraintHits };
+}
+/**
+ * 分类规则(有序,可表测):长跨度或多约束 → deep(转后台);无日期无约束
+ * 且短 → quick;其余落默认中间档 sync-planning。误分有界:三态出口保证
+ * 最坏结局是"本可当面答的被转了后台"(下一轮可救),而非流死掉。
+ */
+export function classifyTurn(message) {
+    const s = extractTurnSignals(message);
+    if (s.spanDays !== null && s.spanDays >= 7)
+        return 'deep-planning';
+    if (s.absoluteDates.length >= 2 && s.constraintHits.length >= 1)
+        return 'deep-planning';
+    if (s.constraintHits.length >= 2 && (s.absoluteDates.length >= 1 || s.spanDays !== null)) {
+        return 'deep-planning';
+    }
+    if (s.absoluteDates.length === 0 && s.constraintHits.length === 0 && s.spanDays === null && s.messageLength <= 60) {
+        return 'quick';
+    }
+    return 'sync-planning';
+}
+export function turnPolicyFor(taskClass) {
+    return { ...TURN_POLICIES[taskClass] };
+}

package/dist/src/tz-resolver.js

@@ -0,0 +1,143 @@
+/**
+ * tz-resolver(v1):IANA 时区权威路径的统一模型输入(Issue #343)。
+ *
+ * 设计动机:
+ * - `ts/src/unified.ts` 既往消费 `tz_offset_min / origin_tz_offset_min / home_tz_offset_min` 数值,
+ *   无法表达 DST/历史/未来规则。中国出境首发已跨区(Asia/Shanghai ↔ Asia/Tokyo),
+ *   同一班次在不同时点 offset 不同,数值口径不可持续。
+ * - 此模块只做 IANA zone + 当地日期 → 确定性 offset(分)。无网络无新依赖;
+ *   Node24 内置 `Intl.DateTimeFormat` 已足够,并由其构造结果作为 zone authority。
+ * - 不存在的"DST 跳过"墙时(spring forward gap)与"两次出现"的"DST 重复"墙时
+ *   (fall back overlap)必须**显式拒绝**,不允许静默选边——这是 §acceptance 第 2 条。
+ * - 结果不依赖 `Date.now`、机器时区或外部 IO;formatter 仅作 module-local cache,同一输入必给同一输出。
+ *
+ * 不变量:
+ * - `offsetMin` 单位 = 分,正值 = 东向 UTC(Asia/Tokyo = +540)。
+ * - 输入校验失败返回结构化失败;调用方显式决定是否拒绝。
+ * - unknown zone / gap / overlap 用同名 `string` 字段区分(returned object 形态);
+ *   调用方负责转 typed error。
+ */
+/**
+ * 以同一份 formatter cache 作为 zone authority。
+ * `Intl.supportedValuesOf` 不是完整 authority(例如 `US/Pacific` 等 alias 可能不列出),
+ * 而 `Intl.DateTimeFormat` 会接受合法 alias 并拒绝 `Foo/Bar`。
+ */
+export function isKnownZoneLoose(zone) {
+    try {
+        wallFormatter(zone);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// 每个 zone 缓存一份 Intl.DateTimeFormat(root 要求:不要为每条候选 instant 重造)。
+// Node 的 DateTimeFormat 本身不可缓存结果(因 ms 输入不同),但实例可重用(无外部 IO)。
+const FMT_CACHE = new Map();
+function wallFormatter(zone) {
+    let f = FMT_CACHE.get(zone);
+    if (f)
+        return f;
+    f = new Intl.DateTimeFormat('en-US', {
+        timeZone: zone,
+        year: 'numeric', month: '2-digit', day: '2-digit',
+        hour: '2-digit', minute: '2-digit',
+        hour12: false,
+    });
+    FMT_CACHE.set(zone, f);
+    return f;
+}
+/** UTC instant → 该 zone 的墙时分量。导出用于 workWindowBlocks 把 depUtcMs 投影到 home zone。 */
+export function readWallParts(zone, ms) {
+    const parts = wallFormatter(zone).formatToParts(new Date(ms));
+    const out = {};
+    for (const p of parts)
+        out[p.type] = p.value;
+    // Intl en-US hour12:false 在午夜 0:00 有时给 "24";规范化回 "00"
+    let hour = Number(out.hour);
+    if (hour === 24)
+        hour = 0;
+    return {
+        year: Number(out.year),
+        month: Number(out.month),
+        day: Number(out.day),
+        hour,
+        minute: Number(out.minute),
+    };
+}
+/** wall 时分量 → ISO yyyy-mm-dd hh:mm 表示(供 parseFlightPackToSpecV2 work window 用)。 */
+export function wallPartsToIso(p) {
+    return {
+        ymd: `${String(p.year).padStart(4, '0')}-${String(p.month).padStart(2, '0')}-${String(p.day).padStart(2, '0')}`,
+        hhmm: `${String(p.hour).padStart(2, '0')}:${String(p.minute).padStart(2, '0')}`,
+    };
+}
+function wallEqual(a, b) {
+    return a.year === b.year && a.month === b.month && a.day === b.day && a.hour === b.hour && a.minute === b.minute;
+}
+/**
+ * IANA zone + 当地日期 + 当地时间 → 确定性 offset(分)与对应 UTC instant。
+ *
+ * 失败 4 类:
+ *   unknown_zone        — `Intl.DateTimeFormat` 不接受该 zone。
+ *   malformed_input     — ymd / hhmm 解析失败或非法(wall 不存在的月日,如 2-30)。
+ *   gap_nonexistent     — DST spring-forward 跳过该墙时(墙上 02:30 不存在)。
+ *   overlap_ambiguous   — DST fall-back 重复该墙时(墙上 01:30 发生两次)。
+ *
+ * 实现要点:
+ *   - 把 ymd/hhmm 当作 UTC 算 epoch 得到候选点 `wallAsUtcMs`;
+ *   - 计算该候选点 offset 用 longOffset 解析,得到"大概"UTC;
+ *   - 在 ±14h 内以 1 分步长扫描,统计能映射回同一 wall 的候选数:
+ *       0 → gap;1 → 唯一;≥2 → overlap。
+ *   - 唯一候选 offset 即结果。
+ */
+export function resolveOffsetForLocalDate(zone, ymd, hhmm) {
+    if (!isKnownZoneLoose(zone))
+        return { ok: false, kind: 'unknown_zone', zone };
+    const dateMatch = ymd.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+    if (!dateMatch)
+        return { ok: false, kind: 'malformed_input', zone, reason: `bad date ${ymd}` };
+    const timeMatch = hhmm.match(/^(\d{2}):(\d{2})$/);
+    if (!timeMatch)
+        return { ok: false, kind: 'malformed_input', zone, reason: `bad time ${hhmm}` };
+    const y = Number(dateMatch[1]);
+    const mo = Number(dateMatch[2]);
+    const d = Number(dateMatch[3]);
+    const h = Number(timeMatch[1]);
+    const mi = Number(timeMatch[2]);
+    if (mo < 1 || mo > 12 || d < 1 || d > 31 || h < 0 || h > 23 || mi < 0 || mi > 59) {
+        return { ok: false, kind: 'malformed_input', zone, reason: `out-of-range ${ymd} ${hhmm}` };
+    }
+    const want = { year: y, month: mo, day: d, hour: h, minute: mi };
+    const wallAsUtcMs = Date.UTC(y, mo - 1, d, h, mi);
+    // ±14h 1-min 步长扫描;此范围覆盖全球 ±14:00 时区(含政治区)+ DST 1-2h 偏移
+    const matches = [];
+    for (let offMin = -14 * 60; offMin <= 14 * 60; offMin++) {
+        // 假 wall 是 UTC,实际 UTC 与 wall 相差 offMin 分钟。
+        // wall = UTC + offMin ⇒ UTC = wall - offMin。
+        const ms = wallAsUtcMs - offMin * 60_000;
+        const local = readWallParts(zone, ms);
+        if (wallEqual(local, want)) {
+            matches.push({ offsetMin: offMin, utcMs: ms });
+        }
+    }
+    if (matches.length === 0)
+        return { ok: false, kind: 'gap_nonexistent', zone, ymd, hhmm };
+    if (matches.length > 1)
+        return { ok: false, kind: 'overlap_ambiguous', zone, ymd, hhmm };
+    return { ok: true, offsetMin: matches[0].offsetMin, utcMs: matches[0].utcMs };
+}
+/**
+ * 仅取 offset(分),不返回 utcMs;若失败给出失败描述字符串(便于 wire 到 red_flags / unsat_core)。
+ *
+ * `unknown != null` 语义在调用方需要的场景(差异日志)很贵,故另开轻 API;
+ * 主路径应使用 `resolveOffsetForLocalDate` 的 discriminated union。
+ */
+export function describeResolveFailure(f) {
+    switch (f.kind) {
+        case 'unknown_zone': return `unknown IANA zone: ${f.zone}`;
+        case 'malformed_input': return `malformed input (${f.reason}) for zone ${f.zone}`;
+        case 'gap_nonexistent': return `DST gap (wall time skipped) in ${f.zone} at ${f.ymd} ${f.hhmm}`;
+        case 'overlap_ambiguous': return `DST overlap (wall time ambiguous) in ${f.zone} at ${f.ymd} ${f.hhmm}`;
+    }
+}