dsh-log-contract 0.3.11 → 0.3.13

package/lib/legacy-fold.js

@@ -0,0 +1,177 @@
+/**
+ * dsh-log-contract · lib/legacy-fold.js —— **v0/v1/v2 旧格式的 surface 终验器**
+ *
+ * 为什么需要这个文件（一手证据，2026-09-14）：
+ *
+ * 官方 `@deepseek-ai/dsh-session` 的 `foldSurface` 在 0.1.5-rc.1 里换成了 **v3 语义**，
+ * 它**不是** rc.7（v0 语义）的超集，而是一个**不同格式**的校验器：
+ * - replace 操作数字段改名：rc.7 `{op,start,end}` → 0.1.5 `{op,startSeq,endSeq}`
+ *   （0.1.5 `lib/index.js:279`：`isReplaceOp` 要求 startSeq/endSeq ⇒ 旧 marker 直接
+ *   “carries an invalid replace surfaceOp”）；
+ * - provenance 收紧：0.1.5 `lib/index.js:285` 起对 `assistant/message` **一律**禁止
+ *   `sourceEventSeqs`（“embeds its source stream and cannot carry sourceEventSeqs”）；
+ *   rc.7 允许（空数组仅限 assistant/message）。
+ *
+ * App 2.0.9 的真实文件版本分布证明旧格式仍在线上：App 内置
+ * `dsh-session-format-v0-to-v1` / `v1-to-v2` / `v2-to-v3` 三个迁移包，
+ * `SESSION_FORMAT_VERSION = 3`；且 `v2-to-v3/lib/index.js:361-371` 明示 **v2 仍是
+ * `{start,end}`**、由迁移改名为 `startSeq/endSeq`。
+ *
+ * ⇒ 结论：**用运行时的 v3 `foldSurface` 去终验 v0/v1/v2 文件必然误报**；旧格式必须用
+ *   本文件这份等价实现（rc.7 `foldSurface` 的逐条移植，语义等价、同样 fail-loud）。
+ *
+ * 移植源：`@deepseek-ai/dsh-session@0.1.0-rc.7` `lib/index.js:229-455`
+ * （`isSurfaceEligibleType` / `isEventSeq` / `isReplaceOp` / `surfaceOpOf` /
+ * `assertProvenance` / `replacementRange` / `isDeepEqualJson` / `assertToolResultRewrite` /
+ * `planSurfaceEvent` / `applySurfacePlan` / `foldSurface`）。
+ *
+ * 与官方相同的点：**抛错即拒绝**（官方加载期 `SessionPersistenceCorruptionError` 同源
+ * 判据）；事件按 `index` 作为期望 seq（`baseSeq = 0`），与官方 `foldSurface(events)` 一致。
+ */
+
+/** v0/v1/v2 的 surface 候选类型（官方 rc.7 `SURFACE_EVENT_TYPES`，3 条）。 */
+const SURFACE_EVENT_TYPES = new Set(['user/message', 'assistant/message', 'tool/result']);
+
+/** Whether an event type can join the model-visible surface（rc.7 `isSurfaceEligibleType`）。 */
+export function isLegacySurfaceEligibleType(type) {
+  return SURFACE_EVENT_TYPES.has(type);
+}
+
+/** Whether a runtime value is a non-negative safe event sequence（rc.7 `isEventSeq`）。 */
+function isEventSeq(value) {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+/** Whether a runtime value is the exact positional-replacement shape（rc.7 `isReplaceOp`：start/end）。 */
+function isReplaceOp(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const op = value;
+  return (
+    Object.keys(op).length === 3 &&
+    Object.hasOwn(op, 'op') && Object.hasOwn(op, 'start') && Object.hasOwn(op, 'end') &&
+    op.op === 'replace' && isEventSeq(op.start) && isEventSeq(op.end)
+  );
+}
+
+/** Validate event-local surface eligibility and return its operation（rc.7 `surfaceOpOf`）。 */
+function surfaceOpOf(event) {
+  if (!SURFACE_EVENT_TYPES.has(event.type)) {
+    if (event.surfaceOp !== undefined) throw new Error(`session event "${event.type}" is not surface-eligible and cannot carry surfaceOp`);
+    if (event.sourceEventSeqs !== undefined) throw new Error(`session event "${event.type}" is not surface-eligible and cannot carry sourceEventSeqs`);
+    return undefined;
+  }
+  const op = event.surfaceOp;
+  if (op === undefined) throw new Error(`session event "${event.type}" is surface-eligible and requires a surfaceOp marker`);
+  if (op === 'append') return op;
+  if (op === null || typeof op !== 'object' || Array.isArray(op)) throw new Error(`session event "${event.type}" carries an invalid surfaceOp`);
+  if (!isReplaceOp(op)) throw new Error(`session event "${event.type}" carries an invalid replace surfaceOp`);
+  return op;
+}
+
+/** Validate cited source-event seqs against prior log entries and the replacement range（rc.7 `assertProvenance`）。 */
+function assertProvenance(event, shadowedSeqs) {
+  const raw = event.sourceEventSeqs;
+  const sources = new Set();
+  if (raw !== undefined) {
+    if (!Array.isArray(raw)) throw new Error(`sourceEventSeqs on event at seq ${event.seq} must be an array when present`);
+    if (raw.length === 0 && event.type !== 'assistant/message') throw new Error('sourceEventSeqs must not be empty except on assistant/message');
+    let nonEarlierSource;
+    for (const source of raw) {
+      if (!isEventSeq(source)) throw new Error(`session event "${event.type}" sourceEventSeqs must densely contain non-negative safe integers`);
+      sources.add(source);
+      if (nonEarlierSource === undefined && source >= event.seq) nonEarlierSource = source;
+    }
+    if (sources.size !== raw.length) throw new Error('sourceEventSeqs must not contain duplicates');
+    if (nonEarlierSource !== undefined) throw new Error(`sourceEventSeqs must reference earlier events: ${nonEarlierSource} >= current seq ${event.seq}`);
+  }
+  const missing = shadowedSeqs.filter((seq) => !sources.has(seq));
+  if (missing.length > 0) throw new Error(`surface replace: sourceEventSeqs must include every shadowed surface node; missing ${missing.join(', ')}`);
+}
+
+/** Locate one replacement range without mutating the current fold state（rc.7 `replacementRange`）。 */
+function replacementRange(state, op) {
+  const startIdx = state.nodes.indexOf(op.start);
+  if (startIdx === -1) throw new Error(`surface replace: start seq ${op.start} not found in surface`);
+  const endIdx = state.nodes.indexOf(op.end);
+  if (endIdx === -1) throw new Error(`surface replace: end seq ${op.end} not found in surface`);
+  if (startIdx > endIdx) throw new Error(`surface replace: start seq ${op.start} (index ${startIdx}) is after end seq ${op.end} (index ${endIdx})`);
+  return { startIdx, endIdx, shadowedSeqs: state.nodes.slice(startIdx, endIdx + 1) };
+}
+
+/** Deep structural equality over the session-event JSON value domain（rc.7 `isDeepEqualJson`）。 */
+function isDeepEqualJson(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((item, i) => isDeepEqualJson(item, b[i]));
+  }
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
+  const aKeys = Object.keys(a);
+  if (aKeys.length !== Object.keys(b).length) return false;
+  return aKeys.every((key) => Object.hasOwn(b, key) && isDeepEqualJson(a[key], b[key]));
+}
+
+/** Restrict a tool-result replacement to one current result's content（rc.7 `assertToolResultRewrite`）。 */
+function assertToolResultRewrite(event, shadowedSeqs, events, baseSeq) {
+  if (event.type !== 'tool/result') return;
+  if (shadowedSeqs.length !== 1) throw new Error('tool/result surface replacement must rewrite exactly one current node');
+  for (const originalSeq of shadowedSeqs) {
+    const original = events[originalSeq - baseSeq];
+    if (original?.type !== 'tool/result') throw new Error('tool/result surface replacement must target a current tool/result');
+    const originalRest = { ...original.data };
+    const replacementRest = { ...event.data };
+    const originalResult = original.data.message.content[0];
+    const replacementResult = event.data.message.content[0];
+    originalRest.message = { ...original.data.message, content: [{ ...originalResult, content: null }] };
+    replacementRest.message = { ...event.data.message, content: [{ ...replacementResult, content: null }] };
+    if (!isDeepEqualJson(originalRest, replacementRest)) throw new Error('tool/result surface replacement may change only content');
+  }
+}
+
+/** Validate one event at its replay boundary and prepare its atomic fold transition（rc.7 `planSurfaceEvent`）。 */
+function planSurfaceEvent(state, event, expectedSeq, events, baseSeq) {
+  if (event.seq !== expectedSeq) throw new Error(`session event seq ${event.seq} is not contiguous; expected ${expectedSeq}`);
+  const surfaceOp = surfaceOpOf(event);
+  if (surfaceOp === undefined) return undefined;
+  if (surfaceOp === 'append') {
+    assertProvenance(event, []);
+    return { kind: 'append', seq: event.seq };
+  }
+  const range = replacementRange(state, surfaceOp);
+  assertProvenance(event, range.shadowedSeqs);
+  assertToolResultRewrite(event, range.shadowedSeqs, events, baseSeq);
+  return { kind: 'replace', seq: event.seq, start: surfaceOp.start, end: surfaceOp.end, ...range };
+}
+
+/** Commit one previously validated surface transition（rc.7 `applySurfacePlan`）。 */
+function applySurfacePlan(state, plan) {
+  if (plan?.kind === 'append') state.nodes.push(plan.seq);
+  else if (plan?.kind === 'replace') {
+    state.nodes.splice(plan.startIdx, plan.endIdx - plan.startIdx + 1, plan.seq);
+    state.replaceGeneration += 1;
+  }
+  if (plan?.kind !== 'replace') return undefined;
+  return { seq: plan.seq, start: plan.start, end: plan.end, shadowedSeqs: plan.shadowedSeqs };
+}
+
+/** Apply one event and return replacement metadata only when one occurred（rc.7 `applySurfaceEvent`）。 */
+function applySurfaceEvent(state, event, expectedSeq, events, baseSeq) {
+  return applySurfacePlan(state, planSurfaceEvent(state, event, expectedSeq, events, baseSeq));
+}
+
+/**
+ * Replay a complete session log through the **v0/v1/v2** canonical surface fold.
+ *
+ * @param events - session events in contiguous seq order（seq 从 0 起，与官方 `foldSurface` 同约定）。
+ * @returns {{ nodes: number[], replacements: Array<{seq:number,start:number,end:number,shadowedSeqs:number[]}> }}
+ * @throws when an event violates surface metadata, source-event references, range, or tool-result rewrite rules.
+ */
+export function legacyFoldSurface(events) {
+  const state = { nodes: [], replaceGeneration: 0 };
+  const replacements = [];
+  for (const [index, event] of events.entries()) {
+    const replacement = applySurfaceEvent(state, event, index, events, 0);
+    if (replacement !== undefined) replacements.push(replacement);
+  }
+  return { nodes: [...state.nodes], replacements };
+}

package/lib/log-reader.js

@@ -7,14 +7,14 @@
  * 契约来源：
  * - 帧扫描/撕裂尾帧判定：复用本项目审计方法论（scan-seq-gaps.mjs），
  *   帧头布局对齐 zstd 规范（magic 0xFD2FB528、descriptor、block 头）。
- * - 行解码：`@deepseek-ai/dsh-session` 的 `decodeStorageRecord`
+ * - 行解码：本地兼容层 `./compat.js` 的 `decodeStorageRecord`（原官方导出于 0.1.5 移除）
  *   （lib/index.js:1029，validateRow :922 / expandRow :973）。
  * - 损坏语义：R2 —— chunk 行损坏 = 整段 run 丢失且加载失败（dsh-session
  *   lib/index.js:1022-1024 注释明示 fail-loud，无跳过逃生舱）。
  */
 import fs from 'node:fs';
 import { zstdDecompressSync } from 'node:zlib';
-import { decodeStorageRecord } from '@deepseek-ai/dsh-session';
+import { decodeStorageRecord, normalizeEventSeqRanges } from './compat.js';
 
 const ZSTD_MAGIC = 0xfd2fb528;
 
@@ -209,10 +209,14 @@ export function loadSessionLog(path) {
       rows.push({ lineNo, value, decoded: null, error: err });
       continue;
     }
-    for (const event of decoded) {
+    // v3 storage-form `sourceEventSeqs` 区间编码 → 内存稠密序列（C1）。
+    // 必须在**读取层唯一入口**做：下游 S5/S6 与官方 foldSurface 都按稠密整数序列判定，
+    // 拿到含 `[start,end]` 对的未展开形态会误判真实健康会话（S5/S6/S8 + --resume broken）。
+    const normalized = decoded.map(normalizeEventSeqRanges);
+    for (const event of normalized) {
       events.push({ seq: event.seq, event, lineNo });
     }
-    rows.push({ lineNo, value, decoded, error: null });
+    rows.push({ lineNo, value, decoded: normalized, error: null });
   }
 
   // 按 seq 排序（文件顺序即日志顺序，此处防御性排序以便下游契约检查）

package/lib/prewrite.js

@@ -17,7 +17,9 @@
  * 所有判定复用 `lib/checks.js`（与离线体检同一套逻辑），
  * 保证"体检看到的问题 = 写入前拦下的问题"。
  */
-import { envelopeViolations, engineViolations, finalFold, isSafeInt, nullTurnStepViolations, pluginViolations, replaySurface, stepKeyViolations, tokenMeterViolations, turnEndReasonViolations, violation } from './checks.js';
+import { envelopeViolations, engineViolations, finalFold, isSafeInt, nullTurnStepViolations, pluginViolations, replaySurface, stepKeyViolations, tokenMeterViolations, turnEndReasonViolations, violation, wireViolations } from './checks.js';
+import { resolveFormatVersion } from './vocab.js';
+import { normalizeEventSeqRanges } from './compat.js';
 
 /** retrace 类 marker：data.editor 存在（assistant/message replace，turn/step=null）。 */
 function isKnownMarkerCandidate(event) {
@@ -32,17 +34,28 @@ function normalizeCandidate(candidate, nextSeq) {
 /**
  * 基于当前日志事件列表建立写前校验器。
  *
- * @param {{ events: Array<object>, baseSeq?: number }} input 当前日志的已解码事件
- *   （按日志顺序；无 seq 字段的事件按位置补 seq，用于窗口校验）。
+ * **格式版本（C2）**：`formatVersion` > `header.version` > 事件形状推断 > 0，在**本次
+ * `createPreWriter` 调用内固定**并显式传给每条按版本择路的判定。**不再读写模块级全局**
+ * `fileVersion`——旧实现下同一进程"先 validate(v3) 再 prewrite(v0)"会把同一份合法 v0 输入
+ * 的结论翻成 S4+S8（独立审核复现 B）。下游 `dsh-retrace` 正是只传 `events` 直接调用
+ * （`lib/prewrite-guard.js:166`），所以缺省时必须能自行推断，不能把 v3 输入按 0 处理
+ * （否则首次调用即 10 条 E3/S2/S8 误报，复现 C）。
+ *
+ * @param {{ events: Array<object>, baseSeq?: number, formatVersion?: number, header?: object|null }} input
+ *   当前日志的已解码事件（按日志顺序；无 seq 字段的事件按位置补 seq，用于窗口校验）。
+ *   `formatVersion`/`header` 二者其一优先决定被检文件的格式版本。
  * @returns {{
- *   events: Array, nextSeq: number,
+ *   events: Array, nextSeq: number, formatVersion: number,
  *   validateAppend(candidate, opts?): { ok, violations, stateAfter },
  *   validateEdit(editedEvents, opts?): { ok, violations, stateAfter },
  * }}
  */
 export function createPreWriter(input = {}) {
-  const { baseSeq = 0 } = input;
-  let events = [...input.events];
+  const { baseSeq = 0, header = null } = input;
+  // C1：v3 storage-form 区间编码 → 内存稠密序列（与 log-reader 同一归一，覆盖"直接传 events"入口）
+  let events = (input.events ?? []).map(normalizeEventSeqRanges);
+  // C2：版本显式解析并固定在本次调用内（不读模块级全局）
+  const formatVersion = resolveFormatVersion({ formatVersion: input.formatVersion, header, events });
   // 窗口校验支持"无 seq 的原始事件列表"：按位置补齐 seq 与 time。
   let nextSeq = baseSeq;
   events = events.map((e) => {
@@ -71,18 +84,21 @@ export function createPreWriter(input = {}) {
     // E1/E3/E4/E5/E6 + M1 + P1/P2 —— 逐事件
     for (const event of candidateEvents) {
       const loc = { seq: event.seq, lineNo: null, eventType: event.type };
-      violations.push(...envelopeViolations(event, loc));
+      violations.push(...envelopeViolations(event, loc, formatVersion));
       violations.push(...engineViolations(event, loc));
       violations.push(...pluginViolations(event, loc));
     }
     // S1–S7 —— 与官方同语义的增量重放（含拟写事件）
-    const replay = replaySurface(candidateEvents.map((event) => ({ event })));
+    const replay = replaySurface(candidateEvents.map((event) => ({ event })), formatVersion);
     violations.push(...replay.violations);
-    // S8 —— 官方 foldSurface 终验
-    const folded = finalFold(candidateEvents);
+    // S8 —— fold 终验（按当前文件版本选：v3 官方 foldSurface / v0–v2 本地 legacyFoldSurface）
+    const folded = finalFold(candidateEvents, formatVersion);
     if (folded.error) {
-      violations.push(violation('S8', { lineNo: null }, `官方 foldSurface 重放失败：${folded.error.message} —— 会话加载会被拒（SessionPersistenceCorruptionError）`));
+      violations.push(violation('S8', { lineNo: null }, `foldSurface 重放失败（按文件版本选：v3 官方 / v0–v2 本地等价）：${folded.error.message} —— 会话加载会被拒（SessionPersistenceCorruptionError）`));
     }
+    // W1/W2 —— wire 流配对（2026-09-09 V3 验证补：离线 check 有、写前原漏——悬空 tool
+    // 编辑必须写前拦，否则违约写入先落盘、体检才报 = 晚一步）
+    violations.push(...wireViolations(candidateEvents.map((event) => ({ event })), formatVersion));
     // T1 —— token-meter 配对（事故根因 3 固化）。写前校验只判定**拟写事件自身**
     // 的 step 配对：retrace 的 turn-null 编辑/撤回 marker 必然命中（空
     // assistant/message replace 无 step 可配对），但编辑功能必须可用——白名单
@@ -129,6 +145,7 @@ export function createPreWriter(input = {}) {
 
   return {
     events,
+    formatVersion,
     get nextSeq() {
       return nextSeq;
     },
@@ -147,7 +164,7 @@ export function createPreWriter(input = {}) {
           nextSeq,
         };
       }
-      const normalized = normalizeCandidate(candidate, nextSeq);
+      const normalized = normalizeEventSeqRanges(normalizeCandidate(candidate, nextSeq));
       const after = [...events, normalized];
       const result = runChecks(after, nextSeq);      result.stateAfter = {
         events: after,
@@ -172,9 +189,10 @@ export function createPreWriter(input = {}) {
           nextSeq,
         };
       }
-      const result = runChecks(editedEvents, undefined);
+      const edited = editedEvents.map(normalizeEventSeqRanges);
+      const result = runChecks(edited, undefined);
       result.stateAfter = {
-        events: editedEvents,
+        events: edited,
         nextSeq: result.nextSeq,
         surfaceNodes: result.surface?.nodes ?? [],
       };
@@ -189,5 +207,5 @@ export function createPreWriter(input = {}) {
  */
 export function preWriterFromLog(log) {
   const events = (log.events ?? []).map((e) => e.event);
-  return createPreWriter({ events });
+  return createPreWriter({ events, header: log?.header ?? null });
 }

package/lib/repair.js

@@ -554,6 +554,48 @@ export function tailRenumberText(text, startSeq, delta) {
   const parts = text.split('\n');
   const out = [];
   let changed = 0;
+  // ── seq 引用平移（2026-09-14 第五轮：把 round4 存档的未审补丁评审后纳入，并补两处同族缺口）──
+  // 一手依据（官方 v0→v1 校验，@0.1.5-rc.2）：
+  // - `data.shadowedRange{start,end}` + `data.shadowedSeqs`：`dsh-session-format-v0-to-v1`
+  //   `lib/index.js:55-70`（compaction/prune、compaction/summary 的 dispositions）、
+  //   `:1142-1146` `shadowedValue()`：start/end 必须是 `earlierSeq(, eventSeq)` 且与 shadowedSeqs 端点一致。
+  // - v3 的 `shadowedRange` 仍是 `{start,end}`（`dsh-session-format-v2-to-v3` `lib/index.js:634-640` `range()`），
+  //   而 v3 `surfaceOp` 是 `{startSeq,endSeq}`（同包 `:361-371`）⇒ 两种字段名都要覆盖。
+  // - `sourceEventSeqs` 在 v3 可为**区间对数组** `[[a,b],…]`（`decodeSeqRanges`）；旧实现把区间对
+  //   当数字减 delta ⇒ `NaN` ⇒ `JSON.stringify` 成 `null`（实测破坏）。此处改为：两端点同侧才平移，
+  //   **跨平移起点**的区间对直接报错（单区间无法忠实表达）。
+  // - `data.messageSeqs`（session/title、session/title-llm-request）同样是 seq 引用
+  //   （`v0-to-v1/lib/index.js:2543-2556` `assertTitleSources` 用 `events[seq]` 取源事件）。
+  const shiftNum = (sv, label) => {
+    if (typeof sv !== 'number' || !Number.isSafeInteger(sv) || sv < startSeq) return { changed: false, value: sv };
+    const ns = sv - delta;
+    if (ns < 0) return { error: `${label} ${sv} 平移后为负（delta 过大或起点有误）` };
+    return { changed: true, value: ns };
+  };
+  const shiftSeqList = (list, label) => {
+    const mapped = [];
+    let local = false;
+    for (const item of list) {
+      if (Array.isArray(item)) {
+        const [a, b] = item;
+        if (!Number.isSafeInteger(a) || !Number.isSafeInteger(b) || a > b) return { error: `${label} 区间对 [${String(a)},${String(b)}] 形状非法` };
+        if (b < startSeq) { mapped.push(item); continue; }
+        if (a < startSeq) return { error: `${label} 区间对 [${a},${b}] 跨平移起点 ${startSeq}，无法用单区间表达（请先展开区间编码）` };
+        const na = a - delta;
+        const nb = b - delta;
+        if (na < 0) return { error: `${label} 区间对 [${a},${b}] 平移后为负` };
+        mapped.push([na, nb]);
+        local = true;
+        continue;
+      }
+      const r = shiftNum(item, label);
+      if (r.error) return { error: r.error };
+      mapped.push(r.value);
+      if (r.changed) local = true;
+    }
+    return { changed: local, value: mapped };
+  };
+
   for (const raw of parts) {
     if (!raw.trim()) {
       out.push(raw);
@@ -567,37 +609,34 @@ export function tailRenumberText(text, startSeq, delta) {
       continue;
     }
     let modified = false;
-    const seq = v.seq;
-    if (typeof seq === 'number' && seq >= startSeq) {
-      const ns = seq - delta;
-      if (ns < 0) return { text, changed: 0, startSeq, delta, error: `seq ${seq} 平移后为负（delta 过大或起点有误）` };
-      v.seq = ns;
-      modified = true;
-    }
-    if (typeof v.seq0 === 'number' && v.seq0 >= startSeq) {
-      const ns = v.seq0 - delta;
-      if (ns < 0) return { text, changed: 0, startSeq, delta, error: `seq0 ${v.seq0} 平移后为负（delta 过大或起点有误）` };
-      v.seq0 = ns;
-      modified = true;
-    }
-    if (Array.isArray(v.sourceEventSeqs)) {
-      let mapped;
-      try {
-        mapped = v.sourceEventSeqs.map((s) => {
-          if (s < startSeq) return s;
-          const ns = s - delta;
-          if (ns < 0) throw new Error(`sourceEventSeqs ${s} 平移后为负`);
-          return ns;
-        });
-      } catch (err) {
-        // 与 seq/seq0 的优雅返回一致：错误走 error 字段而非未捕获异常
-        return { text, changed: 0, startSeq, delta, error: err.message };
-      }
-      if (mapped.some((s, i) => s !== v.sourceEventSeqs[i])) {
-        v.sourceEventSeqs = mapped;
-        modified = true;
-      }
-    }
+    const applyNum = (obj, key, label) => {
+      if (!obj || typeof obj !== 'object') return null;
+      const r = shiftNum(obj[key], label);
+      if (r.error) return r.error;
+      if (r.changed) { obj[key] = r.value; modified = true; }
+      return null;
+    };
+    const applyList = (obj, key, label) => {
+      if (!obj || typeof obj !== 'object' || !Array.isArray(obj[key])) return null;
+      const r = shiftSeqList(obj[key], label);
+      if (r.error) return r.error;
+      if (r.changed) { obj[key] = r.value; modified = true; }
+      return null;
+    };
+
+    let err = applyNum(v, 'seq', 'seq');
+    if (!err) err = applyNum(v, 'seq0', 'seq0');
+    if (!err) err = applyList(v, 'sourceEventSeqs', 'sourceEventSeqs');
+    if (!err) err = applyNum(v.surfaceOp, 'start', 'surfaceOp.start');
+    if (!err) err = applyNum(v.surfaceOp, 'end', 'surfaceOp.end');
+    if (!err) err = applyNum(v.surfaceOp, 'startSeq', 'surfaceOp.startSeq');
+    if (!err) err = applyNum(v.surfaceOp, 'endSeq', 'surfaceOp.endSeq');
+    if (!err) err = applyNum(v.data?.shadowedRange, 'start', 'shadowedRange.start');
+    if (!err) err = applyNum(v.data?.shadowedRange, 'end', 'shadowedRange.end');
+    if (!err) err = applyList(v.data, 'shadowedSeqs', 'shadowedSeqs');
+    if (!err) err = applyList(v.data, 'messageSeqs', 'messageSeqs');
+    if (err) return { text, changed: 0, startSeq, delta, error: err };
+
     if (modified) changed++;
     out.push(JSON.stringify(v));
   }