dsh-log-contract 0.3.9 → 0.3.10

package/lib/index.js

@@ -4,7 +4,7 @@
  * 日志契约守护（DSH session log contract guard）。
  * 公开 API：离线体检 + 写前校验 + 修复 + 契约目录。
  */
-export { loadSessionLog, tailSeq } from './log-reader.js';
+export { loadSessionLog, tailSeq, readSessionHeader } from './log-reader.js';
 export { validateSessionLog, resumeVerdict } from './validate.js';
 export { createPreWriter, preWriterFromLog } from './prewrite.js';
 export { repairSession, strictScanText, removeMarkersText, neutralizeMarkersText, clipCrossStepSourcesText, dropFailedTurnsText, trimLastMessagesText, trimLastMessagesByBudget, estimateTokensText, compactLastMessagesText, rebuildZstdText, tailRenumberText, neutralizeOrphanText, extractTurnText, keepRangesText } from './repair.js';

package/lib/log-reader.js

@@ -220,3 +220,52 @@ export function loadSessionLog(path) {
 
   return { header, headerLine, rows, events, frameInfo };
 }
+
+/**
+ * 轻量读取会话文件 header（只解第一帧，不读全文件帧）。
+ *
+ * 帧布局：帧 1 = header 行（单行 JSON，~几百字节），帧 2+ = 事件流。
+ * 短码推导（工作区 createdAt 序号）需要扫全部会话但只需要 header——
+ * 读文件前缀 64KiB 足够覆盖完整帧 1，避免全量读大文件（opena 工作区
+ * ~108MiB 压缩）。失败返回 null（调用方降级）。
+ *
+ * @param {string} path 会话日志文件路径（.jsonl.zstd 或明文 .jsonl）。
+ * @returns {object|null} header 对象；无法解析返回 null。
+ */
+export function readSessionHeader(path) {
+  let head;
+  try {
+    const fd = fs.openSync(path, 'r');
+    const buf = Buffer.alloc(64 * 1024);
+    const n = fs.readSync(fd, buf, 0, buf.length, 0);
+    fs.closeSync(fd);
+    head = buf.subarray(0, n);
+  } catch {
+    return null;
+  }
+  if (head.length < 4 || head.readUInt32LE(0) !== ZSTD_MAGIC) {
+    // 明文（无 zstd magic）：直接取首行
+    try {
+      const line = head.toString('utf8').split('\n').find((l) => l.trim().length > 0);
+      return line ? JSON.parse(line) : null;
+    } catch {
+      return null;
+    }
+  }
+  const { frames } = scanZstdFrames(head);
+  if (frames.length === 0) return null;
+  const [s, e] = frames[0];
+  let plain;
+  try {
+    plain = zstdDecompressSync(head.subarray(s, e));
+  } catch {
+    return null;
+  }
+  const line = plain.toString('utf8').split('\n').find((l) => l.trim().length > 0);
+  if (!line) return null;
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-log-contract",
   "description": "日志契约守护 — DSH session log contract guard: offline health check (CLI) + pre-write validation for DeepSeek Harness session logs",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "packageManager": "pnpm@11.7.0",
   "type": "module",
   "main": "lib/index.js",