qiyu-cli 0.2.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +433 -72
  2. package/dist/cli.js +48 -7
  3. package/dist/commands/api-notes.js +70 -0
  4. package/dist/commands/api.js +169 -49
  5. package/dist/commands/auth.js +151 -29
  6. package/dist/commands/credentials-source.js +30 -5
  7. package/dist/commands/db-notes.js +75 -0
  8. package/dist/commands/db.js +165 -127
  9. package/dist/commands/query-notes.js +58 -0
  10. package/dist/commands/query.js +449 -61
  11. package/dist/commands/skill.js +445 -51
  12. package/dist/commands/spec-types.js +101 -1
  13. package/dist/commands/stats.js +160 -33
  14. package/dist/commands/store-flags.js +18 -0
  15. package/dist/commands/store-notes.js +38 -0
  16. package/dist/commands/store-precheck.js +321 -0
  17. package/dist/commands/store.js +165 -77
  18. package/dist/commands/sync-notes.js +374 -0
  19. package/dist/commands/sync-run.js +180 -47
  20. package/dist/commands/sync.js +232 -127
  21. package/dist/core/config.js +280 -24
  22. package/dist/core/credentials.js +38 -4
  23. package/dist/core/edition.js +1 -1
  24. package/dist/core/envelope.js +73 -9
  25. package/dist/core/errors.js +73 -16
  26. package/dist/core/http.js +175 -54
  27. package/dist/core/ratelimit.js +5 -1
  28. package/dist/core/registry/index.js +36 -2
  29. package/dist/core/registry/params/export.session.check.json +17 -2
  30. package/dist/core/registry/params/export.session.json +24 -2
  31. package/dist/core/registry/params/export.session.one.json +10 -2
  32. package/dist/core/registry/params/export.session.one.message.json +17 -2
  33. package/dist/core/registry/specs.json +65 -43
  34. package/dist/core/shell.js +30 -0
  35. package/dist/core/time.js +1 -1
  36. package/dist/core/validate.js +21 -2
  37. package/dist/output.js +215 -29
  38. package/dist/postinstall.js +14 -5
  39. package/dist/query/errors.js +145 -45
  40. package/dist/query/mask.js +1277 -25
  41. package/dist/query/metric-catalog.js +11 -0
  42. package/dist/query/native-error.js +189 -0
  43. package/dist/query/sandbox.js +148 -25
  44. package/dist/query/table-query.js +36 -5
  45. package/dist/schedule/install.js +136 -13
  46. package/dist/skill/check.js +11 -6
  47. package/dist/skill/detect.js +89 -29
  48. package/dist/skill/install.js +233 -43
  49. package/dist/skill/paths.js +54 -0
  50. package/dist/skill/qiyu/SKILL.md +29 -5
  51. package/dist/skill/qiyu/errors.md +5 -4
  52. package/dist/skill/qiyu/protocols.md +57 -5
  53. package/dist/skill/qiyu/setup.md +6 -2
  54. package/dist/store/config.js +92 -16
  55. package/dist/store/duckdb.js +1551 -64
  56. package/dist/store/object-kinds.js +32 -0
  57. package/dist/store/retry.js +190 -7
  58. package/dist/store/schema.js +32 -4
  59. package/dist/sync/engine.js +439 -77
  60. package/dist/sync/registry.js +6 -0
  61. package/dist/sync/state.js +20 -0
  62. package/dist/sync/tasks/dim.js +23 -14
  63. package/dist/sync/tasks/knowledge.js +50 -8
  64. package/dist/sync/tasks/pace.js +27 -0
  65. package/dist/sync/tasks/pipeline.js +29 -9
  66. package/dist/sync/tasks/reports.js +176 -49
  67. package/dist/sync/tasks/sessions.js +88 -21
  68. package/dist/sync/tasks/tickets.js +59 -8
  69. package/dist/sync/types.js +60 -1
  70. package/dist/sync/windowing.js +0 -22
  71. package/dist/sync/write-contract.js +79 -0
  72. package/package.json +2 -2
@@ -1,17 +1,33 @@
1
1
  import { readWatermark, markPending, advanceWatermark, recordGap, clearGap, clearLock, } from './state.js';
2
2
  import { sliceByMaxWindow } from './windowing.js';
3
3
  import { isLockError } from '../store/retry.js';
4
+ import { storeInitCommand, syncRunCommand } from '../output.js';
4
5
  import { clampGateWait } from './rate-gate.js';
5
6
  import { shanghaiDayIso, shanghaiDayStart, shanghaiYesterdayStart } from './day.js';
6
7
  const DAY = 86_400_000;
7
8
  /** 回看毫秒数:水位续跑的起点回退量(overlapDays 天;0 = 不回看)。 */
8
9
  const overlapDaysOf = (task) => (task.overlapDays ?? 0) * DAY;
10
+ /**
11
+ * 窗口级 gap 的 reason —— **完整值域 = 引擎侧失败原因 ∪ 任务层业务提示**
12
+ * (`sync_gaps.reason` / `gaps[].reason` 的取值都来自这两组)。
13
+ *
14
+ * ⚠️ 2026-10-27 修:此前 `WindowGapReason` 只声明引擎侧四个,任务 `gapHint.reason`
15
+ * 是 `string` 且落库处用 `as WindowGapReason` 强转 —— 类型对运行时谎报(业务 reason
16
+ * 真实存在于库里),且这些值全仓无图例。现在两组都是 `as const` 数组(可导出、
17
+ * 可被测试逐项核对),README 图例由 `tests/sync-enums.test.ts` 双向钉住。
18
+ */
19
+ export const ENGINE_GAP_REASONS = [
20
+ 'count_mismatch', // 写入意图行数 ≠ API 声明行数(事务已回滚)
21
+ 'fetch_failed', // 取数失败(有界重试后仍失败,本窗未写入)
22
+ 'write_failed', // 落库失败(事务已回滚,本窗未写入)
23
+ 'rate_limit_local', // 本地限频冷却未到点(持久化冷却)
24
+ ];
9
25
  /** 盖在 sync_state.locked_by 上的进程标识(E 中-1:status 的 locked 字段据此为真)。 */
10
26
  const lockOwner = () => `pid ${process.pid}`;
11
27
  /** 引擎自己的「现在」:ctx.now 优先(命令层给任务层固定 clock 时引擎仍可用真实时刻)。 */
12
28
  const nowOf = (ctx) => (ctx.now ?? ctx.clock)();
13
- /** 限频闸门的键(B 中-6):endpoint id 优先,缺省回退任务 id。 */
14
- const gateKeyOf = (task) => task.endpoint ?? task.id;
29
+ /** 限频闸门的键(B 中-6):任务声明的全部 endpoint,缺省回退 `endpoint ?? id`。 */
30
+ const gateKeysOf = (task) => task.gateEndpoints !== undefined ? [...task.gateEndpoints] : [task.endpoint ?? task.id];
15
31
  /**
16
32
  * 首跑起点的合理下界(C 中-2):起点是 0(或负数)时它是「从头开始」的**哨兵**,
17
33
  * 不是真实日期 —— 1970 年没有任何数据,而 `ticket.search` 的 `opStart` 还会被服务端
@@ -56,6 +72,19 @@ function resolveRangeStart(task, ctx, state, requested, nowMs) {
56
72
  }
57
73
  return floorRangeStart(task, start, requested.end, nowMs);
58
74
  }
75
+ /**
76
+ * 任意拒绝值 → 文本;**转换本身抛**(`Object.create(null)` 没有 `Symbol.toPrimitive`)时交回
77
+ * 占位说明(CR 第五十四轮 store 侧同一形态的引擎收口)。错误路径上的「值转文本」不得自己
78
+ * 成为新的主失败 —— 否则本次运行连 partial / gap 都报不出来。
79
+ */
80
+ function textOf(e) {
81
+ try {
82
+ return e instanceof Error ? e.message : String(e);
83
+ }
84
+ catch {
85
+ return `(无法转成文本的拒绝值,typeof=${typeof e})`;
86
+ }
87
+ }
59
88
  /**
60
89
  * gap detail 的中文包装(C 低-2):gap 要进 stdout 与持久层(sync_gaps),
61
90
  * 而失败原因可能是任意来源 —— `fetch failed`、DuckDB 的英文原文、上游报文片段。
@@ -63,29 +92,88 @@ function resolveRangeStart(task, ctx, state, requested, nowMs) {
63
92
  * ⚠️ 引擎自己抛的中文结论(配对核对/本地限频)不包装 —— 再套一层只会变噪音。
64
93
  */
65
94
  function failDetail(label, e) {
66
- const raw = e instanceof Error ? e.message : String(e);
95
+ const raw = textOf(e);
67
96
  return `${label}(底层:${raw})`;
68
97
  }
69
98
  /**
70
- * 写策略落地(事务内调用):deleteRangeInsert 按范围列删旧 + upsert;upsertRows 直接 upsert。
71
- * ⚠️ 窗口是**半开** [start, end),而删除条件是闭区间 —— 天对齐分支的上界必须取
72
- * `dayIso(end − 1ms)`(窗口内最后一个瞬时所在的自然日),否则 end 恰落在日界
73
- *(`--until` 指定日期 / windowEndClamp 钳到昨天 0:00 / 日对齐水位都会产生)时
74
- * `dayIso(end)` = 下一天零点,删除会多删**下一天**的行:`--since D0 --until D2`
75
- * 的第二窗 end=D2 零点 → 删除范围含 D2 → D2 日已同步的行被删而本轮不重拉(D2 在
76
- * 请求区间外,永久损失)。`end − 1ms` 后:1 天窗 [D, D+1) → 删除恰好 [D, D],
77
- * 31 天考勤窗 [D0, D0+31d) → [D0, D0+30](= 31 天),与写入行集一致。
99
+ * fetch 失败的原因分派:`callPaced` 在**真正要调用**的端点冷却时抛 `rate_limit_local`
100
+ * (Sourcery PR#58 复核,2026-11-15)。那是「本窗没发请求 / 已发部分请求但未落库」的
101
+ * 限频,不是取数失败 —— 记成 fetch_failed 会让 Agent 去查接口形态而不是等冷却。
102
+ */
103
+ function fetchGapReason(e) {
104
+ return safeKindOf(e) === 'rate_limit_local' ? 'rate_limit_local' : 'fetch_failed';
105
+ }
106
+ function fetchGapDetail(e) {
107
+ return fetchGapReason(e) === 'rate_limit_local'
108
+ ? textOf(e)
109
+ : failDetail('取数失败', e);
110
+ }
111
+ /**
112
+ * DuckDB 对「INSERT / DELETE 的目标不是基表」(同名 view 等)的原文:
113
+ * `Catalog Error: tags is not an table`(实测,2026-11-15;DELETE 侧另有
114
+ * `Binder Error: Can only delete from base table`)。
115
+ * ⚠️ 匹配前先剥一层可能的包装前缀?不需要:两个 store 路径(`upsert` 的 usage 包装只发生在
116
+ * 列校验,而 view 的列集若对得上就一路走到 INSERT)与 `delete` 都直接抛驱动原文。
117
+ */
118
+ function isNotAnTableError(raw) {
119
+ return /\bis not an table\b|\bCan only delete from base table\b/i.test(raw);
120
+ }
121
+ /**
122
+ * `write_failed` 的 detail(唯一渲染点):普通落库失败保持原有的 `落库失败(底层:…)`;
123
+ * 目标对象不是基表时**点名成因**并给出与 `sync verify` 的 `not_base_table`、
124
+ * `query --table`、`stats fields` 同一套恢复动作 —— 否则 Agent 只会反复重跑 `sync run`。
125
+ * 不回显 DuckDB 原文里被操作的对象名(那是用户自己的表名,不是故障点;原文对 Agent 无益)。
126
+ */
127
+ function writeFailedDetail(e, ctx) {
128
+ const raw = textOf(e);
129
+ if (!isNotAnTableError(raw))
130
+ return failDetail('落库失败', e);
131
+ const loc = ctx.storeLocation;
132
+ const rebuild = loc === undefined
133
+ ? '先备份旧库文件,再把 --db 换成新的 .duckdb 路径跑 qiyu store init 建库、'
134
+ + 'qiyu sync run 重新拉取(不要指回出问题的文件)'
135
+ : '先备份旧库文件,再把 --db 换成新的 .duckdb 路径跑 '
136
+ + storeInitCommand('<新路径>', loc.profileFlag) + ' 建库、'
137
+ + syncRunCommand('<新路径>', loc.profileFlag) + ' 重新拉取'
138
+ + '(把 <新路径> 整段替换成新路径,不要指回出问题的文件)';
139
+ return '落库失败:本 CLI 的一张声明表在库里不是基表(view 等,写入被库拒绝)。'
140
+ + '执行它的主体会读到旧数据或直接失败。' + rebuild;
141
+ }
142
+ /**
143
+ * 写策略落地(事务内调用):deleteRangeInsert 按声明基准删旧 + upsert;upsertRows 直接 upsert。
144
+ * ⚠️ 窗口是**半开** [start, end),而删除条件是闭区间 —— 上界一律取「最后 1ms」:
145
+ * · 天对齐分支取 `dayIso(end − 1ms)`(窗口内最后一个瞬时所在的自然日),否则 end 恰落在
146
+ * 日界时(`--until` 指定日期 / windowEndClamp 钳到昨天 0:00 / 日对齐水位都会产生)
147
+ * `dayIso(end)` = 下一天零点,删除会多删**下一天**的行:`--since D0 --until D2` 的第二窗
148
+ * end=D2 零点 → 删除范围含 D2 → D2 日已同步的行被删而本轮不重拉(D2 在请求区间外,
149
+ * 永久损失)。
150
+ * · `instantColumn` 分支取 `toISOString(end − 1ms)`,与行内值同为毫秒精度 ISO 串,
151
+ * 等价于 `< end`。
78
152
  */
79
153
  async function writeRows(task, ops, rows, range) {
80
- if (task.write.kind === 'deleteRangeInsert') {
81
- const dayAligned = task.write.rangeAlign === 'shanghaiDay';
82
- const from = dayAligned ? shanghaiDayIso(range.start) : new Date(range.start).toISOString();
83
- const to = dayAligned ? shanghaiDayIso(range.end - 1) : new Date(range.end).toISOString();
84
- // where 是可信代码常量(同 query 红线):列名来自任务声明(代码级),值参数化绑定。
85
- // 范围边界与行内日期列同口径(rangeAlign):行写「上海天对齐的日期列」时,删除范围
86
- // 也必须是天对齐边界——否则 --full 与增量对同一业务日的删除范围互不覆盖(A 中-2)。
87
- for (const col of task.write.rangeColumns) {
88
- await ops.delete(task.table, `"${col}" >= ? AND "${col}" <= ?`, [from, to]);
154
+ const write = task.write;
155
+ if (write.kind === 'deleteRangeInsert') {
156
+ if ('instantColumn' in write) {
157
+ // ⚠️ 行内自带**逐行瞬时时间**的表按 `[start, end)` 精确删(2026-11-03 修,CodeRabbit #59):
158
+ // 按自然日删在「窗口起止不在日界」时无解 —— 删整日会把相邻窗写好的边界日整片抹掉
159
+ // (实测 staff_attendance 边界日 16/24 小时);改成「只删完整日内」又会把半个边界日里
160
+ // 被上游撤掉的行永久留下(陈旧行)。逐行时间列能同时避免两头:窗内精确覆盖、窗外不碰。
161
+ // 列名来自任务声明(代码级),值参数化绑定;`write-contract.ts` 保证它是表的
162
+ // timeColumn(kind='iso-instant'),与 `toISOString()` 的比较口径一致。
163
+ await ops.delete(task.table, `"${write.instantColumn}" >= ? AND "${write.instantColumn}" <= ?`, [new Date(range.start).toISOString(), new Date(range.end - 1).toISOString()]);
164
+ }
165
+ else {
166
+ const dayAligned = write.rangeAlign === 'shanghaiDay';
167
+ const from = dayAligned ? shanghaiDayIso(range.start) : new Date(range.start).toISOString();
168
+ const to = dayAligned ? shanghaiDayIso(range.end - 1) : new Date(range.end).toISOString();
169
+ // where 是可信代码常量(同 query 红线):列名来自任务声明(代码级),值参数化绑定。
170
+ // 范围边界与行内日期列同口径(rangeAlign):行写「上海天对齐的日期列」时,删除范围
171
+ // 也必须是天对齐边界——否则 --full 与增量对同一业务日的删除范围互不覆盖(A 中-2)。
172
+ // ⚠️ 按自然日删**只在窗起止都落在日界时精确**:注册表加载期由 `write-contract.ts`
173
+ // 校验「rangeAlign='shanghaiDay' ⇒ windowAlign='shanghaiDay'」,不让边界日被邻窗抹掉。
174
+ for (const col of write.rangeColumns) {
175
+ await ops.delete(task.table, `"${col}" >= ? AND "${col}" <= ?`, [from, to]);
176
+ }
89
177
  }
90
178
  }
91
179
  if (rows.length === 0)
@@ -140,6 +228,11 @@ async function withRetries(ctx, op, retryable = () => true) {
140
228
  * · 网络失败(kind=network)**不在此列** —— core `http.call` 已自带 2 次退避重试
141
229
  * (实测 300ms/600ms),引擎再套一层等于 3 倍往返与 3 倍等待,把 core 的预算语义
142
230
  * 变成噪声(实测形态:一次「fetch failed」会从 3 次请求变成 9 次);
231
+ * ⚠️ 这条前提在 2026-11-02 之前**是假的**:当时只有 fetch 抛错与 body 读取失败
232
+ * 两支会重试,5xx(网关 HTML / Spring JSON 两种载体)**只发 1 个请求就抛出** ——
233
+ * 于是一次网关 502 就把整个窗口打成 `fetch_failed` gap,而 gap 的 detail 还写着
234
+ * 「可退避重试」。现在 core 的四支网络载体共用同一预算(实测每支 3 次请求),
235
+ * 前提才成立;改 core 的重试覆盖面时必须一并回来核对这条注释。
143
236
  * · 限频(kind=rate_limit)不在此列 —— 任务层 callPaced 已有自己的等待预算,
144
237
  * 引擎层再等一轮只会把冷却乘起来(限频靠冷却解决,不靠重试);
145
238
  * · 本地参数错误(usage)、配对核对结论(count_mismatch)、任务层自抛的形态漂移
@@ -147,16 +240,58 @@ async function withRetries(ctx, op, retryable = () => true) {
147
240
  * 于是引擎重试真正覆盖的是 core 无法归类/无法重试的那一类:撞锁(store_locked)
148
241
  * 与任务层显式标注 retryable 的瞬时错误。
149
242
  */
243
+ /**
244
+ * 实例已退役(稳定 `code`)—— **两层重试判据的最高优先终止条件**(Codex 第七轮 P2,真驱动
245
+ * 注入实测):回滚未确认的撞锁失败会保留原 `kind`(`store_locked`)并打上
246
+ * `code=store_retired`;若只按 kind 判「撞锁可重试」,就会再碰**已退役的同一实例** ——
247
+ * 第二次尝试撞上「Store 已退役」,把主失败与「先核对再重放」整段换掉。
248
+ */
249
+ /**
250
+ * 安全读取拒绝值上的字符串字段(**唯一实现点**,CR 第六十五轮 / Codex 第十二轮 P2):
251
+ * 拒绝值可能是 `null` / `undefined`(读属性直接 TypeError),也可能是 getter 抛异常的对象 ——
252
+ * 错误路径上的判据自己成了新的主失败,就会把原始错误整段换掉。读不出来一律按「不匹配」。
253
+ * ⚠️ 不只是 `code`:`kind` / `hint` / `retryable` 同样被判据读,一律经这里
254
+ *(实测事故:`query` 以 `null` 拒绝时 `fetchGapReason` 的 `(e as {kind}).kind` 抛
255
+ * `Cannot read properties of null (reading 'kind')`,原始拒绝值整段丢失)。
256
+ */
257
+ const safeStringField = (e, field) => {
258
+ if (e === null || (typeof e !== 'object' && typeof e !== 'function'))
259
+ return undefined;
260
+ try {
261
+ const v = e[field];
262
+ return typeof v === 'string' ? v : undefined;
263
+ }
264
+ catch {
265
+ return undefined;
266
+ }
267
+ };
268
+ const safeBoolField = (e, field) => {
269
+ if (e === null || (typeof e !== 'object' && typeof e !== 'function'))
270
+ return undefined;
271
+ try {
272
+ const v = e[field];
273
+ return typeof v === 'boolean' ? v : undefined;
274
+ }
275
+ catch {
276
+ return undefined;
277
+ }
278
+ };
279
+ const safeCodeOf = (e) => safeStringField(e, 'code');
280
+ const safeKindOf = (e) => safeStringField(e, 'kind');
281
+ const isRetiredFailure = (e) => safeCodeOf(e) === 'store_retired';
150
282
  function isTransient(e) {
151
- const err = e;
152
- if (err.kind === 'store_locked')
283
+ if (isRetiredFailure(e))
284
+ return false;
285
+ const kind = safeKindOf(e);
286
+ if (kind === 'store_locked')
153
287
  return true;
154
- if (err.kind === 'rate_limit' || err.kind === 'network')
288
+ if (kind === 'rate_limit' || kind === 'network')
155
289
  return false;
156
- return err.retryable === true;
290
+ return safeBoolField(e, 'retryable') === true;
157
291
  }
158
292
  /** store 事务的撞锁重试(B 中-4,spec §6.3:C1 写者无内置重试,重试调度归 D 层)。 */
159
- const storeRetryable = (e) => e.kind === 'store_locked' || isLockError(e);
293
+ const storeRetryable = (e) => !isRetiredFailure(e)
294
+ && (safeKindOf(e) === 'store_locked' || isLockError(e));
160
295
  const withStoreRetries = (ctx, op) => withRetries(ctx, op, storeRetryable);
161
296
  /** 本窗 gap 落库 + 收集(独立事务:本窗已回滚,gap 不能混进失败事务)。 */
162
297
  async function storeGap(ctx, task, w, reason, detail, gaps) {
@@ -166,6 +301,51 @@ async function storeGap(ctx, task, w, reason, detail, gaps) {
166
301
  }));
167
302
  gaps.push(info);
168
303
  }
304
+ /**
305
+ * Store 连接已退役(事务状态无法确认,存储层拒绝一切后续语句)—— 判据是存储层打的
306
+ * 稳定 `code`,不按报文文本匹配(文案随成因变化,code 不变)。
307
+ * ⚠️ 为什么引擎必须认它(CR 第四十一轮 major 的追问,真驱动注入实测):落库事务的
308
+ * COMMIT 结果未知时 Store 当场退役;随后的 **gap 落库**与**清锁**都会撞上退役。
309
+ * 若让这两条次生失败照常上抛,用户看到的会是「Store 已退役,请关闭重建后再试」——
310
+ * 把原始失败里的「写入可能已落库,不要按失败直接重试(可能重复写),核对后再决定是否
311
+ * 重放」整段换掉,恰好诱导重复写。
312
+ */
313
+ const isStoreRetired = (e) => safeCodeOf(e) === 'store_retired';
314
+ /**
315
+ * 记本窗 gap;连接已退役时 gap 写不进去,**把本窗的原始失败原样交回**(它带着恢复指令)。
316
+ * 其它 error 照旧上抛 —— 那是 gap 真正的写入失败,不能吞。
317
+ */
318
+ async function storeGapOrPrimary(ctx, task, w, reason, detail, gaps, primary) {
319
+ try {
320
+ await storeGap(ctx, task, w, reason, detail, gaps);
321
+ }
322
+ catch (e) {
323
+ if (!isStoreRetired(e))
324
+ throw e;
325
+ // 主失败本身已让实例退役(它先退役、gap 写是次生)→ 原样交回主失败(它带着恢复指令)。
326
+ if (isStoreRetired(primary))
327
+ throw primary;
328
+ // ⚠️ 否则是**补记缺口这次事务首次**让实例退役(COMMIT 结果未知,CR 第五十一轮 major #2):
329
+ // 两条事实都必须交回 —— 只留主失败会静默丢掉「缺口记录可能没落库、实例已退役、后续窗口
330
+ // 写不进」;只留退役文案又丢掉主失败。合并成一条,`code`/`kind` 让编排层识别退役。
331
+ const primaryMsg = textOf(primary);
332
+ // ⚠️ **不得断言 COMMIT 已下发**(Codex 第五轮 P1,隔离探针实测):补记缺口的事务也可能
333
+ // 在 INSERT 阶段就失败、ROLLBACK 又未确认(SQL 序列里根本没有 COMMIT)—— 摘要必须用
334
+ // 那条错误**自己的**成因(提交结果未知 / 回滚未能确认),否则恢复动作被误导。
335
+ const gapMsg = textOf(e);
336
+ const wrapped = new Error(`${primaryMsg} —— 补记缺口时实例退役(${gapMsg})`, { cause: primary });
337
+ wrapped.kind = safeKindOf(e) ?? 'internal';
338
+ wrapped.retryable = false;
339
+ wrapped.code = 'store_retired';
340
+ const eh = safeStringField(e, 'hint');
341
+ const ph = safeStringField(primary, 'hint');
342
+ const hints = [eh, ph].filter((h) => typeof h === 'string');
343
+ wrapped.hint = hints.length > 0
344
+ ? hints.join(';')
345
+ : '关闭并重建 Store 实例,先核对数据(本窗写入是否落库)再决定是否重放;后续窗口需要重跑';
346
+ throw wrapped;
347
+ }
348
+ }
169
349
  /**
170
350
  * gapHint → sync_gaps.detail(C-8):hint 带 `fixture`(会话导出的尾部标记行原文)时
171
351
  * 追加标注 —— 「为什么可疑」在 detail 正文、「可疑的那行原文」在其后,同一行可见。
@@ -184,8 +364,23 @@ function gapHintDetail(hint) {
184
364
  */
185
365
  const GATE_WAIT_BUDGET = 3;
186
366
  const GATE_WAIT_FALLBACK_MS = 1_000;
367
+ /**
368
+ * 任务的**首次请求端点**(`gateKeysOf` 的首键):fetch 前的**快速失败**预检只看这一把键。
369
+ *
370
+ * ⚠️ 为什么不再预检**全部**声明键(Sourcery PR#58 复核,2026-11-15 实测):声明式地
371
+ * 在 fetch 前检查 `gateEndpoints` 全部键,会把「本次根本不会调用」的端点冷却也算成失败 ——
372
+ * 实测 `ticket.template.fields` 冷却 + 模板列表为空时,`dim.ticket_template_fields`
373
+ * 一发请求都不发就被记成 `failed` + `rate_limit_local`,而空快照本该删掉旧字段行。
374
+ * 次要端点改由 `callPaced` 在**真正调用前**逐一拦(那里才是「会不会调用」的唯一答案)。
375
+ * 主端点预检保留:常见成因(主端点冷却)仍然在发请求前就失败,语义没变。
376
+ */
187
377
  async function acquireGated(ctx, task) {
188
- const key = gateKeyOf(task);
378
+ // 首键 = 任务**实际先请求**的那个端点(`gateEndpoints` 缺省回退成 `[endpoint ?? id]`;
379
+ // 多端点任务的声明按「先调的在前」写,实测 dim.ticket_template_fields 先 list 后 fields)。
380
+ // ⚠️ 不要改成「`endpoint` 声明的那个」:`dim.ticket_template_fields` 的 `endpoint` 是
381
+ // `ticket.template.fields`,而它第一次发的是 `ticket.template.list` —— 预检要拦的是
382
+ // 「马上要发的这一发」,声明字段只是写库/文档归属。
383
+ const key = gateKeysOf(task)[0];
189
384
  for (let waits = 0;; waits++) {
190
385
  try {
191
386
  // 冷却是持久化的:读库也在 store 上,撞锁走同一有界重试(B 中-4)。
@@ -193,7 +388,7 @@ async function acquireGated(ctx, task) {
193
388
  return;
194
389
  }
195
390
  catch (e) {
196
- if (e.kind !== 'rate_limit_local' || waits >= GATE_WAIT_BUDGET)
391
+ if (safeKindOf(e) !== 'rate_limit_local' || waits >= GATE_WAIT_BUDGET)
197
392
  throw e;
198
393
  const wait = clampGateWait(e.retryAfter ?? 0) || GATE_WAIT_FALLBACK_MS;
199
394
  await engineSleep(ctx, wait);
@@ -243,7 +438,7 @@ function fetchCtx(ctx) {
243
438
  }
244
439
  /**
245
440
  * 窗口末端上限(G 高-1,任务声明式):`staffAttendance` / `statistic.performance` 的
246
- * `endTime` 不得晚于今天 00:00(`14501 endTime is invalid`),而「今天 0:00」这条边界
441
+ * `endTime` 必须早于今天 00:00(`14501 endTime is invalid`),而「今天 0:00」这条边界
247
442
  * 本身不稳定(同一取值时而 200 时而 14501,设计稿 §6.2 实测)→ 统一退到**昨天 00:00**。
248
443
  * 返回该任务本轮可拉的末端上限(未声明钳制的任务为 +∞,行为不变)。
249
444
  */
@@ -267,6 +462,24 @@ function clampWindowEnd(windows, limit) {
267
462
  }
268
463
  return out;
269
464
  }
465
+ /** 被 clampWindowEnd **整窗丢弃**的窗数(丢弃不等于跳过:必须计数可见,2026-11-03 修)。 */
466
+ const clampedAwayCount = (windows, limit) => Number.isFinite(limit) ? windows.filter((w) => w.start >= limit).length : 0;
467
+ /**
468
+ * 被 clampWindowEnd **截短**(不是整窗丢弃)的窗(2026-11-09 审计)。
469
+ *
470
+ * 它们照常执行,但实际拉取的时间片比切窗时短(如 31 天窗只拉到 `limit`)。
471
+ * 计数上它是「一个成功窗」,`resolved_range.end` 也已如实收到 `limit` —— 唯独
472
+ * 「这个窗被截短了」这一步此前没有任何输出。stderr 进度行补上它(数据没少:
473
+ * 截掉的那段本来就晚于上限、拉不到)。
474
+ */
475
+ const truncatedByClamp = (windows, limit) => Number.isFinite(limit) ? windows.filter((w) => w.start < limit && w.end > limit) : [];
476
+ /** 合并窗的覆盖窗失败时的进度行:那个窗被合并进了一个没成功的窗 —— 该段没拉到。 */
477
+ const containedUnreachedNote = (task, w) => `[${task.id}] 窗未执行(原本落在前一窗的回看重叠区、被合并,但覆盖它的那一窗失败):`
478
+ + `[${new Date(w.start).toISOString()}, ${new Date(w.end).toISOString()}) —— 已按 skipped 计入,须重跑补齐`;
479
+ /** 截短窗的进度行(人读 stderr;与整窗丢弃的 clampedAwayNote 分开说成因)。 */
480
+ const clampedShortNote = (task, w, limit) => `[${task.id}] 窗末端被上限截短(只拉到 ${new Date(limit).toISOString()}):`
481
+ + `[${new Date(w.start).toISOString()}, ${new Date(w.end).toISOString()}) —— `
482
+ + '截掉的部分晚于末端上限、接口给不出数据,不是丢失已有数据';
270
483
  /**
271
484
  * 声明了 `windowAlign: 'shanghaiDay'` 的任务的**段式日对齐切片**(修复批 5 #1):
272
485
  * 从 `shanghaiDayStart(range.start)`(上海日 0 点)起按 `maxWindowDays` 天的步长推进,
@@ -341,6 +554,9 @@ function isResidualWindow(task, w) {
341
554
  return w.start !== shanghaiDayStart(w.start) || w.end !== shanghaiDayStart(w.end);
342
555
  }
343
556
  /** 残段窗的进度行(人读 stderr;skip 窗仍计入 windows.total / windows.skipped)。 */
557
+ /** 整窗晚于末端上限时的进度行(与残段窗同为「有意不 fetch」,但成因不同,分开说)。 */
558
+ const clampedAwayNote = (task, w, limit) => `[${task.id}] 窗整窗跳过(晚于末端上限 ${new Date(limit).toISOString()}):`
559
+ + `[${new Date(w.start).toISOString()}, ${new Date(w.end).toISOString()})`;
344
560
  const residualNote = (task, w) => `[${task.id}] 残段窗跳过(非日界首/末段):[${new Date(w.start).toISOString()}, ${new Date(w.end).toISOString()})`;
345
561
  /**
346
562
  * 运行一个同步任务(spec §6.1 的 run(task))。
@@ -395,9 +611,22 @@ async function runWindowed(task, ctx) {
395
611
  const raw = wholeRangeBelowFloor
396
612
  ? [resolvedRange]
397
613
  : sliceForTask(task, resolvedRange, task.maxWindowDays);
614
+ // ⚠️ 末端上限之外的窗是**整窗丢弃**(2026-11-03 实测修):此前它既不在 total 也不在
615
+ // skipped、无任何进度行 —— 请求「今天」的考勤/绩效会得到 `total:0, complete, gaps:[]`,
616
+ // Agent 无法区分「今天被上限挡掉了」与「已同步完成」,而本仓自定的残段窗原则是
617
+ // 「绝不静默消失」。现在与残段窗一样计数进 skipped 并逐窗出进度行。
618
+ const droppedByClamp = raw.filter((w) => w.start >= limit);
398
619
  const clamped = clampWindowEnd(raw, limit);
399
620
  const skippedResidual = clamped.filter((w) => isResidualWindow(task, w));
400
- const windows = skipContained(clamped.filter((w) => !isResidualWindow(task, w)), overlapMs);
621
+ const notResidual = clamped.filter((w) => !isResidualWindow(task, w));
622
+ const links = containedLinks(notResidual, overlapMs);
623
+ const windows = links.kept;
624
+ // 重叠压缩掉的窗(2026-11-09 审计):overlapDays > 0 的任务里,完全落进前一窗重叠区的
625
+ // 窗被合并——它既不执行也不该算「跳过」(按切窗形态,数据已被前一窗覆盖),但此前它从
626
+ // 所有计数里消失。⚠️ 是否**真的**覆盖要看覆盖窗的结果(Codex 2026-11-10 第三轮 P2:
627
+ // 覆盖窗自己失败时 `failed:1, contained:1` 而表是空的)—— 所以 `containedCount` 等到
628
+ // 循环结束、按「覆盖窗成功」结算(见下面循环后的结算段),失败覆盖窗名下的合并窗进 skipped。
629
+ // ⚠️ 只能声明在成功返回的那条路径作用域里(空窗早返回不涉及任何反馈射)。
401
630
  // 可拉范围 = 请求范围 ∩ 末端上限:resolved_range 如实回显「这轮实际覆盖到哪」——
402
631
  // 回显一个没覆盖到的 end 会让 Agent 以为今天的数据已同步(G 高-1 的静默面)。
403
632
  const effectiveRange = { start: rangeStart, end: Math.min(resolvedRange.end, limit) };
@@ -417,8 +646,13 @@ async function runWindowed(task, ctx) {
417
646
  // ② 全残段跳过(批 6 新增)——outRange 非退化,必须收口到起点。
418
647
  for (const w of skippedResidual)
419
648
  progress(residualNote(task, w));
649
+ for (const w of droppedByClamp)
650
+ progress(clampedAwayNote(task, w, limit));
651
+ for (const w of truncatedByClamp(raw, limit))
652
+ progress(clampedShortNote(task, w, limit));
653
+ const skippedAll = skippedResidual.length + droppedByClamp.length;
420
654
  return { taskId: task.id,
421
- windows: { total: skippedResidual.length, succeeded: 0, failed: 0, skipped: skippedResidual.length },
655
+ windows: { total: skippedAll, succeeded: 0, failed: 0, skipped: skippedAll },
422
656
  rows: { fetched: 0, written: 0 },
423
657
  resolvedRange: { start: outRange.start, end: outRange.start }, gaps, status: 'complete' };
424
658
  }
@@ -445,22 +679,33 @@ async function runWindowed(task, ctx) {
445
679
  // 修复批 6 #2:残段窗不进执行循环(上面的过滤已排除),但仍如实计数 ——
446
680
  // 裁定:计入 total、标 skipped,每窗一条进度行。「跳过了什么」必须可见,
447
681
  // 绝不静默消失;跳过段不算成功窗,contiguousEnd 不受影响(不进循环)。
448
- const skipped = skippedResidual.length;
682
+ const skipped = skippedResidual.length + droppedByClamp.length;
449
683
  for (const w of skippedResidual)
450
684
  progress(residualNote(task, w));
685
+ for (const w of droppedByClamp)
686
+ progress(clampedAwayNote(task, w, limit));
687
+ for (const w of truncatedByClamp(raw, limit))
688
+ progress(clampedShortNote(task, w, limit));
689
+ // 每个执行窗成功与否,结束时结算它名下的合并窗(见上的注释)
690
+ const windowOk = [];
691
+ let containedCount = 0;
692
+ let containedUnreached = 0;
451
693
  for (let i = 0; i < windows.length; i++) {
452
694
  const w = windows[i];
453
695
  const ref = { ...w, index: i, total: windows.length };
696
+ windowOk.push(false);
454
697
  progress(`[${task.id}] 窗口 ${i + 1}/${windows.length}: ${new Date(w.start).toISOString()} ~ ${new Date(w.end).toISOString()}`);
455
698
  // —— 限频闸门(持久化冷却;慢不是错:等待后重试本窗,预算耗尽才记 gap)——
456
699
  try {
457
700
  await acquireGated(ctx, task);
458
701
  }
459
702
  catch (e) {
460
- if (e.kind === 'rate_limit_local') {
703
+ if (safeKindOf(e) === 'rate_limit_local') {
461
704
  failed++;
462
705
  contiguousBroken = true;
463
- await storeGap(ctx, task, w, 'rate_limit_local', e.message, gaps);
706
+ // ⚠️ **次生的退役错误不得顶掉这里的原始失败**(CR 第六十三轮 major):限频
707
+ // 预算耗尽本身带恢复指令;补记缺口的事务若首次让实例退役,两条事实合并交回。
708
+ await storeGapOrPrimary(ctx, task, w, 'rate_limit_local', e.message, gaps, e);
464
709
  continue;
465
710
  }
466
711
  throw e;
@@ -473,7 +718,7 @@ async function runWindowed(task, ctx) {
473
718
  catch (e) {
474
719
  failed++;
475
720
  contiguousBroken = true;
476
- await storeGap(ctx, task, w, 'fetch_failed', failDetail('取数失败', e), gaps);
721
+ await storeGapOrPrimary(ctx, task, w, fetchGapReason(e), fetchGapDetail(e), gaps, e);
477
722
  continue;
478
723
  }
479
724
  // —— enrich 过滤 + 同事务落库(红线 2/3)——
@@ -501,11 +746,11 @@ async function runWindowed(task, ctx) {
501
746
  catch (e) {
502
747
  failed++;
503
748
  contiguousBroken = true;
504
- const isMismatch = e.code === 'count_mismatch';
749
+ const isMismatch = safeCodeOf(e) === 'count_mismatch';
505
750
  // 行数统计口径(brief 钉死用例):mismatch 时 written 记「应写行数」(kept)——
506
751
  // 实际行已随事务回滚,计入的是本窗参与核对的落库意图行数。
507
752
  writtenTotal += kept.length;
508
- await storeGap(ctx, task, w, isMismatch ? 'count_mismatch' : 'write_failed', isMismatch ? e.message : failDetail('落库失败', e), gaps);
753
+ await storeGapOrPrimary(ctx, task, w, isMismatch ? 'count_mismatch' : 'write_failed', isMismatch ? textOf(e) : writeFailedDetail(e, ctx), gaps, e);
509
754
  continue;
510
755
  }
511
756
  resolvedEndOut = watermarkMs;
@@ -514,16 +759,38 @@ async function runWindowed(task, ctx) {
514
759
  // —— gapHint(如 order_performance 的 orders:null 筛选失败,spec §5.2):成功窗也落提示 ——
515
760
  // T5 裁定(T7 接线):透传 hint 的原始 reason(filter_matched_no_staff 等),
516
761
  // 不压成统一 fetch_failed——缺口原因在 sync_gaps 里必须可分派。
517
- if (fetchRes.gapHint) {
518
- await storeGap(ctx, task, w, fetchRes.gapHint.reason, gapHintDetail(fetchRes.gapHint), gaps);
762
+ // ⚠️ 单条或**多条**(CodeRabbit PR #67):同一窗可能既缺行(row_missing_key)又缺
763
+ // fixture(export_fixture_unreported),压成一条会让消费方永远漏掉另一类信号。
764
+ const hints = Array.isArray(fetchRes.gapHint) ? fetchRes.gapHint : [fetchRes.gapHint];
765
+ for (const h of hints) {
766
+ if (h === undefined)
767
+ continue;
768
+ await storeGap(ctx, task, w, h.reason, gapHintDetail(h), gaps);
519
769
  }
520
770
  succeeded++;
771
+ windowOk[i] = true;
521
772
  writtenTotal += written;
522
773
  progress(`[${task.id}] 窗口 ${i + 1}/${windows.length} 完成:拉取 ${fetchRes.rows.length} 行,写入 ${written} 行`);
523
774
  }
775
+ // 合并窗结算:覆盖窗成功 → contained;覆盖窗失败 → 这些窗该拉没拉 → skipped
776
+ //(并逐窗出进度行点名「未覆盖」,绝不静默)。
777
+ for (let i = 0; i < windows.length; i++) {
778
+ const merged = links.containedBy[i] ?? [];
779
+ if (merged.length === 0)
780
+ continue;
781
+ if (windowOk[i])
782
+ containedCount += merged.length;
783
+ else {
784
+ containedUnreached += merged.length;
785
+ for (const w of merged)
786
+ progress(containedUnreachedNote(task, w));
787
+ }
788
+ }
789
+ const skippedTotal = skipped + containedUnreached;
524
790
  return {
525
791
  taskId: task.id,
526
- windows: { total: windows.length + skipped, succeeded, failed, skipped },
792
+ windows: { total: windows.length + skippedTotal, succeeded, failed, skipped: skippedTotal,
793
+ ...(containedCount > 0 ? { contained: containedCount } : {}) },
527
794
  rows: { fetched: fetchedTotal, written: writtenTotal },
528
795
  // 末端与水位同源(见上):断链时 = 连续成功末端,未断链 = 本窗 end。
529
796
  // ⚠️ 末端是「上次成功推进到的时刻」,与删除边界(天对齐下取 dayOf(end−1ms),
@@ -560,7 +827,7 @@ async function runSnapshot(task, ctx) {
560
827
  await acquireGated(ctx, task);
561
828
  }
562
829
  catch (e) {
563
- if (e.kind === 'rate_limit_local') {
830
+ if (safeKindOf(e) === 'rate_limit_local') {
564
831
  // 快照也要留下可查的状态行(E 中-1):门都没进就放弃时,若库里连一行都没有,
565
832
  // 建一行 pending(盖章后立即清章)——「这个任务本轮被本地冷却拦下了」必须可查,
566
833
  // 而不是 status 里什么都看不到。
@@ -571,7 +838,7 @@ async function runSnapshot(task, ctx) {
571
838
  }));
572
839
  await releaseLock(ctx, task);
573
840
  }
574
- await storeGap(ctx, task, resolvedRange, 'rate_limit_local', e.message, gaps);
841
+ await storeGapOrPrimary(ctx, task, resolvedRange, 'rate_limit_local', e.message, gaps, e);
575
842
  return snapshotResult(task, resolvedRange, gaps, 0, 0, 0, 1, 'failed');
576
843
  }
577
844
  throw e;
@@ -589,11 +856,16 @@ async function runSnapshot(task, ctx) {
589
856
  fetchRes = await withRetries(ctx, () => fetchWithFakeEmptyRetry(task, ref, ctx), isTransient);
590
857
  }
591
858
  catch (e) {
592
- await storeGap(ctx, task, resolvedRange, 'fetch_failed', failDetail('取数失败', e), gaps);
859
+ await storeGapOrPrimary(ctx, task, resolvedRange, fetchGapReason(e), fetchGapDetail(e), gaps, e);
593
860
  return snapshotResult(task, resolvedRange, gaps, 0, 0, 0, 1, 'failed');
594
861
  }
595
862
  const { kept } = applyEnrich(task, fetchRes.rows);
596
- const expected = kept.length;
863
+ // ⚠️ 与 windowed(`engine.ts` 的 `expected = apiCount ?? kept.length`)和 `sync verify`
864
+ // (`apiCount ?? rows.length`)**同一口径**:`apiCount` 是 fetch 声明的配对核对基准,
865
+ // 快照此前只用 `kept.length` —— 三条路径对同一字段三种读法,上游声明的行数与实际
866
+ // 解析出的行数不等时,只有快照会把它静默吞掉(`types.ts` 的字段注释写着「配对核对
867
+ // 基准」)。当前所有快照任务都把 apiCount 取成过滤后的行数,故行为零漂移。
868
+ const expected = fetchRes.apiCount !== undefined ? fetchRes.apiCount : kept.length;
597
869
  let written = 0;
598
870
  try {
599
871
  written = await withStoreRetries(ctx, () => store.transaction(async (tx) => {
@@ -610,15 +882,17 @@ async function runSnapshot(task, ctx) {
610
882
  }));
611
883
  }
612
884
  catch (e) {
613
- const isMismatch = e.code === 'count_mismatch';
614
- await storeGap(ctx, task, resolvedRange, isMismatch ? 'count_mismatch' : 'write_failed', isMismatch ? e.message : failDetail('落库失败', e), gaps);
885
+ const isMismatch = safeCodeOf(e) === 'count_mismatch';
886
+ await storeGapOrPrimary(ctx, task, resolvedRange, isMismatch ? 'count_mismatch' : 'write_failed', isMismatch ? textOf(e) : writeFailedDetail(e, ctx), gaps, e);
615
887
  return snapshotResult(task, resolvedRange, gaps, fetchRes.rows.length, 0, 0, 1, 'failed');
616
888
  }
617
889
  // gapHint(如 dim.staff_group_members 的 staffIdList 形态漂移):成功快照也落提示。
618
890
  // T5 裁定(T7 接线):透传 hint 的原始 reason,不压成统一 fetch_failed ——
619
891
  // 缺口原因在 sync_gaps 里必须可分派(与 runWindowed 的 gapHint 路径同口径)。
620
- if (fetchRes.gapHint) {
621
- await storeGap(ctx, task, resolvedRange, fetchRes.gapHint.reason, gapHintDetail(fetchRes.gapHint), gaps);
892
+ for (const h of (Array.isArray(fetchRes.gapHint) ? fetchRes.gapHint : [fetchRes.gapHint])) {
893
+ if (h === undefined)
894
+ continue;
895
+ await storeGap(ctx, task, resolvedRange, h.reason, gapHintDetail(h), gaps);
622
896
  }
623
897
  progress(`[${task.id}] 快照完成:拉取 ${fetchRes.rows.length} 行,写入 ${written} 行`);
624
898
  return snapshotResult(task, resolvedRange, gaps, fetchRes.rows.length, written, 1, 0, 'complete');
@@ -632,7 +906,20 @@ async function runSnapshot(task, ctx) {
632
906
  * 无行(如空范围空跑、或在 markPending 之前就抛错)时不动库 —— 不为清章凭空建一行。
633
907
  */
634
908
  async function releaseLock(ctx, task) {
635
- const st = await readWatermark(ctx.store, task.id);
909
+ // ⚠️ **读水位失败**才可能是主失败的次生结果(CR 第四十一轮 major;第五十一轮 major #5
910
+ // 细化):本函数在 `finally` 里,若实例在进入这里**之前**就已退役,读水位的 store_retired
911
+ // 纯属次生 —— 吞掉,才能保住主失败里「核对数据后再决定是否重放」的恢复指令。
912
+ let st;
913
+ try {
914
+ st = await readWatermark(ctx.store, task.id);
915
+ }
916
+ catch (e) {
917
+ if (isStoreRetired(e))
918
+ return;
919
+ throw e;
920
+ }
921
+ // 读水位成功说明实例此前可用 —— 随后清锁事务里的 store_retired 是本函数**首次**让实例退役
922
+ //(COMMIT 结果未知),不是次生结果:必须上抛,否则本次 run 被报成 complete、写者锁可能没清。
636
923
  if (st.watermark === null && st.rangeStatus === null && st.lastSyncedAt === null)
637
924
  return;
638
925
  await withStoreRetries(ctx, () => ctx.store.transaction(async (tx) => {
@@ -653,17 +940,47 @@ function snapshotResult(task, resolvedRange, gaps, fetched, written, succeeded,
653
940
  * 跳过不改变数据、只省一次 API 调用。相邻重叠窗(end 超出 prev.end)不跳过。
654
941
  */
655
942
  function skipContained(windows, overlapMs) {
656
- if (windows.length < 2 || overlapMs <= 0)
657
- return windows;
658
- const out = [windows[0]];
943
+ return containedLinks(windows, overlapMs).kept;
944
+ }
945
+ /**
946
+ * 与 `skipContained` 同一次遍历,额外记下**每个被合并窗落在哪个执行窗里**。
947
+ *
948
+ * 被合并 ≠ 已覆盖(Codex 2026-11-10 第三轮 P2):覆盖它的那一窗自己也可能失败
949
+ * (`sessions.export` 的 1 天窗失败 → `failed:1, contained:1` 而表是空的)。所以
950
+ * `windows.contained` 只统计「**覆盖窗已经成功**」的那些合并窗,未覆盖的归入 `unreached`,
951
+ * 由调用方按 skipped 计 —— 字段的承诺是「数据已由前一窗覆盖」,不能只看切窗形态。
952
+ */
953
+ function containedLinks(windows, overlapMs) {
954
+ const kept = [];
955
+ const containedBy = [];
956
+ if (windows.length === 0)
957
+ return { kept, containedBy, unreached: [] };
958
+ if (windows.length < 2 || overlapMs <= 0) {
959
+ kept.push(...windows);
960
+ for (let i = 0; i < windows.length; i++)
961
+ containedBy.push([]);
962
+ return { kept, containedBy, unreached: [] };
963
+ }
964
+ let dropped = [];
965
+ kept.push(windows[0]);
966
+ containedBy.push([]);
659
967
  for (let i = 1; i < windows.length; i++) {
660
- const prev = out[out.length - 1];
968
+ const prev = kept[kept.length - 1];
661
969
  const cur = windows[i];
662
- if (cur.end <= prev.end && cur.start >= prev.end - overlapMs)
970
+ if (cur.end <= prev.end && cur.start >= prev.end - overlapMs) {
971
+ dropped.push(cur);
663
972
  continue;
664
- out.push(cur);
973
+ }
974
+ containedBy[containedBy.length - 1] = dropped;
975
+ dropped = [];
976
+ kept.push(cur);
977
+ containedBy.push([]);
665
978
  }
666
- return out;
979
+ // 最后一个执行窗之后若还有被合并窗(cur 落在 prev 重叠区但 prev 已是末窗)——
980
+ // 上面的循环只在遇到下一个执行窗时才结算 dropped,末尾这次要补上
981
+ if (dropped.length > 0)
982
+ containedBy[containedBy.length - 1] = dropped;
983
+ return { kept, containedBy, unreached: [] };
667
984
  }
668
985
  async function planRotation(task, ctx, now) {
669
986
  if (task.kind !== 'windowed')
@@ -682,11 +999,20 @@ async function planRotation(task, ctx, now) {
682
999
  const limit = windowEndLimit(task, now);
683
1000
  // 残段窗过滤(修复批 6 #2):与 runWindowed 同口径 —— 切片+钳制后把非日界首/末段
684
1001
  // 排除在执行集外、收进 skippedResidual(半日聚合不落日行的裁定对轮转路径同样生效)。
685
- const clamped = resolvedRange.end <= resolvedRange.start
1002
+ const rawWindows = resolvedRange.end <= resolvedRange.start
686
1003
  ? []
687
- : clampWindowEnd(sliceForTask(task, resolvedRange, task.maxWindowDays), limit);
1004
+ : sliceForTask(task, resolvedRange, task.maxWindowDays);
1005
+ // 末端上限之外的窗整窗丢弃 → 与 runWindowed 同口径:计数可见 + 进度行(见那边的注释)。
1006
+ const droppedByClamp = rawWindows.filter((w) => w.start >= limit);
1007
+ const truncatedSource = rawWindows;
1008
+ const clamped = clampWindowEnd(rawWindows, limit);
688
1009
  const skippedResidual = clamped.filter((w) => isResidualWindow(task, w));
689
- const windows = skipContained(clamped.filter((w) => !isResidualWindow(task, w)), overlapMs);
1010
+ const notResidual = clamped.filter((w) => !isResidualWindow(task, w));
1011
+ const links = containedLinks(notResidual, overlapMs);
1012
+ const windows = links.kept;
1013
+ // 重叠压缩掉的窗:与 runWindowed 同口径(见那边的注释)—— 是否算「已覆盖」要等
1014
+ // 覆盖窗的结果,由 runRotated 的结算段定(plan 里先带 links)。
1015
+ const containedCount = 0;
690
1016
  const outRange = { start: rangeStart,
691
1017
  end: Math.max(rangeStart, Math.min(resolvedRange.end, limit)) };
692
1018
  const lock = { by: lockOwner(), at: new Date(now).toISOString() };
@@ -696,16 +1022,28 @@ async function planRotation(task, ctx, now) {
696
1022
  if (windows.length === 0) {
697
1023
  for (const w of skippedResidual)
698
1024
  ctx.onProgress?.(residualNote(task, w));
699
- return { task, state, resolvedRange: outRange, windows, skippedResidual, lock, gaps: [],
1025
+ for (const w of droppedByClamp)
1026
+ ctx.onProgress?.(clampedAwayNote(task, w, limit));
1027
+ for (const w of truncatedByClamp(truncatedSource, limit))
1028
+ ctx.onProgress?.(clampedShortNote(task, w, limit));
1029
+ return { task, state, resolvedRange: outRange, windows, skippedResidual, droppedByClamp, containedCount,
1030
+ containedBy: links.containedBy, windowOk: [], truncatedSource, lock, gaps: [],
700
1031
  succeeded: 0, failed: 0, fetched: 0, written: 0,
701
1032
  contiguousEnd: null, contiguousBroken: false, resolvedEnd: null };
702
1033
  }
703
1034
  for (const w of skippedResidual)
704
1035
  ctx.onProgress?.(residualNote(task, w));
1036
+ for (const w of droppedByClamp)
1037
+ ctx.onProgress?.(clampedAwayNote(task, w, limit));
1038
+ // 截短提示(Codex 2026-11-10 P2):考勤/绩效这类声明了 windowEndClamp 的任务在
1039
+ // `sync run` 里**全部走轮转路径**,此前只有 runWindowed 出这句 —— 实际命令面看不到。
1040
+ for (const w of truncatedByClamp(truncatedSource, limit))
1041
+ ctx.onProgress?.(clampedShortNote(task, w, limit));
705
1042
  await withStoreRetries(ctx, () => ctx.store.transaction(async (tx) => {
706
1043
  await markPending(tx, task.id, state, lock);
707
1044
  }));
708
- return { task, state, resolvedRange: outRange, windows, skippedResidual, lock, gaps: [],
1045
+ return { task, state, resolvedRange: outRange, windows, skippedResidual, droppedByClamp, containedCount,
1046
+ containedBy: links.containedBy, windowOk: windows.map(() => false), truncatedSource, lock, gaps: [],
709
1047
  succeeded: 0, failed: 0, fetched: 0, written: 0,
710
1048
  contiguousEnd: null, contiguousBroken: false, resolvedEnd: null };
711
1049
  }
@@ -744,10 +1082,10 @@ export async function runRotated(tasks, ctx) {
744
1082
  await acquireGated(ctx, task);
745
1083
  }
746
1084
  catch (e) {
747
- if (e.kind === 'rate_limit_local') {
1085
+ if (safeKindOf(e) === 'rate_limit_local') {
748
1086
  plan.failed++;
749
1087
  plan.contiguousBroken = true;
750
- await storeGap(ctx, task, w, 'rate_limit_local', e.message, plan.gaps);
1088
+ await storeGapOrPrimary(ctx, task, w, 'rate_limit_local', e.message, plan.gaps, e);
751
1089
  continue;
752
1090
  }
753
1091
  throw e;
@@ -760,7 +1098,7 @@ export async function runRotated(tasks, ctx) {
760
1098
  catch (e) {
761
1099
  plan.failed++;
762
1100
  plan.contiguousBroken = true;
763
- await storeGap(ctx, task, w, 'fetch_failed', failDetail('取数失败', e), plan.gaps);
1101
+ await storeGapOrPrimary(ctx, task, w, fetchGapReason(e), fetchGapDetail(e), plan.gaps, e);
764
1102
  continue;
765
1103
  }
766
1104
  const { kept } = applyEnrich(task, fetchRes.rows);
@@ -776,6 +1114,7 @@ export async function runRotated(tasks, ctx) {
776
1114
  const written = await withRetries(ctx, () => commitWindow(ctx, task, w, kept, expected, watermarkRange, plan.lock), isTransient);
777
1115
  plan.written += written;
778
1116
  plan.succeeded++;
1117
+ plan.windowOk[round] = true;
779
1118
  plan.resolvedEnd = watermarkMs;
780
1119
  if (!plan.contiguousBroken)
781
1120
  plan.contiguousEnd = w.end;
@@ -783,13 +1122,15 @@ export async function runRotated(tasks, ctx) {
783
1122
  catch (e) {
784
1123
  plan.failed++;
785
1124
  plan.contiguousBroken = true;
786
- const isMismatch = e.code === 'count_mismatch';
1125
+ const isMismatch = safeCodeOf(e) === 'count_mismatch';
787
1126
  plan.written += kept.length;
788
- await storeGap(ctx, task, w, isMismatch ? 'count_mismatch' : 'write_failed', isMismatch ? e.message : failDetail('落库失败', e), plan.gaps);
1127
+ await storeGapOrPrimary(ctx, task, w, isMismatch ? 'count_mismatch' : 'write_failed', isMismatch ? e.message : writeFailedDetail(e, { storeLocation: ctx.storeLocation }), plan.gaps, e);
789
1128
  continue;
790
1129
  }
791
- if (fetchRes.gapHint) {
792
- await storeGap(ctx, task, w, fetchRes.gapHint.reason, gapHintDetail(fetchRes.gapHint), plan.gaps);
1130
+ for (const h of (Array.isArray(fetchRes.gapHint) ? fetchRes.gapHint : [fetchRes.gapHint])) {
1131
+ if (h === undefined)
1132
+ continue;
1133
+ await storeGap(ctx, task, w, h.reason, gapHintDetail(h), plan.gaps);
793
1134
  }
794
1135
  progress(`[${task.id}] 轮转 round ${round + 1}/${maxRounds} 完成:拉取 ${fetchRes.rows.length} 行,写入 ${kept.length} 行`);
795
1136
  }
@@ -805,14 +1146,35 @@ export async function runRotated(tasks, ctx) {
805
1146
  // 末端与水位同源(修复批 4 #2):断链时 = 连续成功末端(resolvedEnd),未断链 = 请求末。
806
1147
  // ⚠️ 末端是「上次成功推进到的时刻」,与删除边界(天对齐下取 dayOf(end−1ms),
807
1148
  // 见 writeRows)刻意不同:前者是位置、后者是行集覆盖。
808
- return plans.map((p) => ({
809
- taskId: p.task.id,
810
- // 修复批 6 #2:残段窗计入 total、标 skipped(与 runWindowed 同口径)。
811
- windows: { total: p.windows.length + p.skippedResidual.length,
812
- succeeded: p.succeeded, failed: p.failed, skipped: p.skippedResidual.length },
813
- rows: { fetched: p.fetched, written: p.written },
814
- resolvedRange: { start: p.resolvedRange.start, end: p.resolvedEnd ?? p.resolvedRange.start },
815
- gaps: p.gaps,
816
- status: p.failed === 0 ? 'complete' : 'partial',
817
- }));
1149
+ return plans.map((p) => {
1150
+ // 合并窗结算(与 runWindowed 同口径,Codex 2026-11-10 第三轮 P2):覆盖窗成功才算
1151
+ // contained;覆盖窗失败 → 该段没拉到 → 归 skipped 并逐窗出进度行。
1152
+ let contained = 0;
1153
+ let unreached = 0;
1154
+ for (let i = 0; i < p.windows.length; i++) {
1155
+ const merged = p.containedBy[i] ?? [];
1156
+ if (merged.length === 0)
1157
+ continue;
1158
+ if (p.windowOk[i] === true)
1159
+ contained += merged.length;
1160
+ else {
1161
+ unreached += merged.length;
1162
+ for (const w of merged)
1163
+ progress(containedUnreachedNote(p.task, w));
1164
+ }
1165
+ }
1166
+ const skippedTotal = p.skippedResidual.length + p.droppedByClamp.length + unreached;
1167
+ return {
1168
+ taskId: p.task.id,
1169
+ // 修复批 6 #2:残段窗计入 total、标 skipped(与 runWindowed 同口径)。
1170
+ windows: { total: p.windows.length + skippedTotal,
1171
+ succeeded: p.succeeded, failed: p.failed,
1172
+ skipped: skippedTotal,
1173
+ ...(contained > 0 ? { contained } : {}) },
1174
+ rows: { fetched: p.fetched, written: p.written },
1175
+ resolvedRange: { start: p.resolvedRange.start, end: p.resolvedEnd ?? p.resolvedRange.start },
1176
+ gaps: p.gaps,
1177
+ status: p.failed === 0 ? 'complete' : 'partial',
1178
+ };
1179
+ });
818
1180
  }