dsh-log-contract 0.3.13 → 0.3.15

package/lib/validate.js

@@ -12,6 +12,9 @@
 import { ruleById } from './contracts.js';
 import { normalizeEventSeqRanges } from './compat.js';
 import { HOST_MAX_FILE_VERSION, MIGRATION_TARGET_VERSION, hostCapability, isAssessableFileVersion } from './vocab.js';
+import { detectSupport } from './version-support.js';
+import { runHostProbes } from './host-probes.js';
+import { SOURCE_DRIFT } from './contracts.js';
 import {
   CHUNK_ROW_TYPES,
   envelopeViolations,
@@ -103,7 +106,7 @@ export function validateSessionLog(log, opts = {}) {
     }
   }
 
-  // ── Z3 · 空文件体检（2026-09-09 反向挑刺 T3 增量）──────────────────────────
+  // ── Z3 · 空文件体检（2026-09-09 T3 增量）──────────────────────────
   // 空态无覆盖:36 条规则全来自"有内容"事故,空会话文件应显式报(不管 DSH 编排层怎么处理)。
   // 有 header 但零事件 = 异常空会话(warning,不破坏 ok);连 header 都没有 → H1 已报。
   if (header !== null && events.length === 0) {
@@ -156,7 +159,7 @@ export function validateSessionLog(log, opts = {}) {
   violations.push(...nullTurnStepViolations(events));
   violations.push(...turnEndReasonViolations(events));
 
-  // ── E7 · ignorable 未知 type 合法性（反向挑刺 T2）────────────────────
+  // ── E7 · ignorable 未知 type 合法性（T2）────────────────────
   violations.push(...ignorableTypeViolations(events, formatVersion));
 
   // ── I1 · inbox seed 相对重放（fork 边界孤儿；交接书 L1）──────────────
@@ -219,6 +222,12 @@ export function validateSessionLog(log, opts = {}) {
     summary,
     surface: folded.surface ?? { nodes: replay.nodes, replacements: [] },
   };
+  // 版本支持面（2026-09-14 用户要求第 1 条）：宿主版本 vs 测试基线 + 被检文件格式版本，
+  // 给出 warnings/readOnly。只读档由入口（prewrite/fix）强制执行。
+  result.support = detectSupport({ header, events });
+  // R-D 漂移检测：行为探针（宿主自己的运行时函数当 oracle）+ R-F 出处/前提漂移清单。
+  result.probes = hostProbes();
+  result.drift = driftOf(result.probes);
   result.migration = migrationVerdict(result);
   result.assessmentScope = result.migration.assessmentScope;
   return result;
@@ -322,11 +331,53 @@ function unassessableResult({ header, headerLine, rows, events, frameInfo, baseS
     },
     surface: null,
   };
+  result.support = detectSupport({ header, events });
+  result.probes = hostProbes();
+  result.drift = driftOf(result.probes);
   result.migration = migrationVerdict(result);
   result.assessmentScope = result.migration.assessmentScope;
   return result;
 }
 
+/** 行为探针只跑一次（宿主在同一进程内不变）。 */
+let probesMemo;
+function hostProbes() {
+  if (probesMemo === undefined) {
+    try {
+      probesMemo = runHostProbes();
+    } catch (err) {
+      probesMemo = { hostPackage: 'unknown', sessionFormatVersion: null, knownTypes: 0, verified: false, probes: [], unverifiedRules: ['<probe-run-failed>'], error: String(err?.message ?? err) };
+    }
+  }
+  return probesMemo;
+}
+
+/**
+ * R-D/R-F 合并出的**漂移报告**（`check` 抬头与 `--json` 共用）。
+ *   · `unverifiedRules` —— 行为探针在本宿主上**不成立**的规则（宿主语义与规则假设不符）;
+ *   · `driftedSources`  —— 出处停在 rc.7、未在 0.1.5 上复核（R-F，机读清单）;
+ *   · `premiseStale`    —— 判定前提已不成立/无法判定（复核 §1）;
+ *   · `fixApplyBlocked` —— 只要任一非空,就**不得据此跑 `fix --apply`**（R-E）。
+ */
+export function driftOf(probes) {
+  const p = probes ?? hostProbes();
+  const unverifiedRules = [...new Set(p.unverifiedRules ?? [])];
+  const driftedSources = [...SOURCE_DRIFT.drifted];
+  const premiseStale = [...SOURCE_DRIFT.premiseStale];
+  return {
+    probeVerified: p.verified === true,
+    unverifiedRules,
+    driftedSources,
+    premiseStale,
+    undecidable: [...SOURCE_DRIFT.undecidable],
+    // `fix --apply` 的**硬前提**只看行为探针（宿主语义与规则假设不一致时才禁止写入类动作）;
+    // 出处/前提清单（R-F）是**已知文档债**，会显式告警但不阻断修复流程 —— 否则只要历史
+    // 清单非空,"修一个坏会话"这条主路径就永久不可用（见报告"我未照做之处"）。
+    fixApplyBlocked: unverifiedRules.length > 0,
+    note: SOURCE_DRIFT.note,
+  };
+}
+
 /**
  * 迁移预检结论（S1）——**独立维度**：官方把 v0/v1/v2 升到当前格式会不会拒。
  *
@@ -349,7 +400,7 @@ export function migrationVerdict(result) {
       // 2026-09-15 第五轮：`turn/start` 试做后在**真实语料**上被判定为"应用对象错"——
       // 官方状态机（assertReleasedArtifactRelationships）由 v1→v2 在**变换后的 v1/v2 artifact**
       // 上调用（v1-to-v2/lib/index.js:104），带 cut/继承切点处理；在原始 v0 上照抄会在已 seed
-      // 的会话上狂报（样本 session-62c5b531：0.1.5 链并不以该规则拒它，原始 v0 上会报 19 条）。
+      // 的会话上狂报（实测样本：0.1.5 链并不以该规则拒它，原始 v0 上会报 19 条）。
       // ⇒ 忠实复现需先做 v0→v1→v2 变换；本轮不做，保持未覆盖。
       'turn/start 闭合/预期轮（官方 v1→v2 在**变换后** artifact 上判：does not close the prior turn / does not open expected turn）',
       'assistant/attempt 配对/闭合（migration refuses the transformed artifact）',
@@ -437,7 +488,7 @@ export function resumeVerdict(result) {
       violationsByTier: { structural: [], inbox: [], tokenMeter: [] },
     };
   }
-  // 三档各自的「阻断规则集」——按任务书 §L3 档位定义：
+  // 三档各自的「阻断规则集」——按 L3 档位定义：
   //   可加载：结构层（PERSISTENCE/FRAMING）+ 引擎层非 I1/T1/T2/T3/T4 的 error；
   //   可继续：+ I1（inbox 重放）；
   //   可压缩：+ T1/T2/T3/T4（token-meter 配对 + 渲染层节点 key/turn）。
@@ -449,7 +500,7 @@ export function resumeVerdict(result) {
   const has = (id) => (byId[id]?.length ?? 0) > 0;
 
   // 可加载阻断 = 除 I1/T1/T2/T3/T4 外的所有 error 违规（结构/信封/物理序/工具配对等）。
-  // 注意：不能用 result.ok（它把 T1/T2/T3/T4/I1 也计为 error）——三档判定按任务书定义，
+  // 注意：不能用 result.ok（它把 T1/T2/T3/T4/I1 也计为 error）——三档判定按 L3 定义，
   // T1/T2/T3/T4 只影响「可压缩」档、I1 只影响「可继续」档。
   const loadableBlockers = violations.filter(
     (v) => v.severity === 'error' && !['I1', 'T1', 'T2', 'T3', 'T4', 'T5'].includes(v.id),

package/lib/version-support.js

@@ -0,0 +1,148 @@
+/**
+ * dsh-log-contract · lib/version-support.js —— **版本支持面**:测试基线 + 运行时检测/告警
+ * （2026-09-14 用户要求第 1 条:把"哪些版本被验证过"写成明文,并在运行时检测报告）。
+ *
+ * 背景（外部质疑 + 事实核对）：
+ * - 事实①:本包 `peerDependencies` = `^0.1.0-rc.7 || ^0.1.5-rc.1`,devDependency 与开发机
+ *   宿主实装都是 `0.1.5-rc.1` ⇒ **覆盖到了**;且本规则集在 v3 会话上实测有效
+ *   （在真实 v3 文件上准确拒绝了伪造的 `seq: 0`，见 E2/S6/S8 用例）。
+ * - 事实②:"**哪些版本被验证过**"此前只散落在注释与 CHANGELOG 里,**没有一处明文**,
+ *   外部无法核对 ⇒ 本模块把**测试基线**变成一个可读、可比对、会告警的常量。
+ *
+ * 三条运行时规则（"不闷着按旧规则判"）：
+ * 1. 宿主 `@deepseek-ai/dsh-session` 版本**比基线新** ⇒ 明确告警（规则集未在该版本上验证）；
+ * 2. 被检**会话文件格式版本**不在已知集合 {0,1,2,3} 内 ⇒ 报"未验证格式"并**按只读处理**
+ *    （不做写入前判定、不做修复）；
+ * 3. 两者都可解析时,给出一行可核对的摘要（宿主 / 文件格式 / 基线）。
+ */
+import { hostPackageVersion, resolveFormatVersionDetailed, HOST_MAX_FILE_VERSION } from './vocab.js';
+
+/**
+ * **测试基线**（唯一权威）：本规则集在下列宿主 / 会话格式版本上被验证。
+ * 改这里必须同步 README（中英）与 docs/CONTRACTS.md 头部（生成器模板）。
+ */
+export const TESTED_BASELINE = Object.freeze({
+  hostPackage: '@deepseek-ai/dsh-session',
+  /** 开发机与 CI 实装宿主版本（devDependency 同值）。 */
+  hostVersion: '0.1.5-rc.1',
+  /** 声明的 peer 范围（允许安装,但未逐一验证）。 */
+  peerRange: '^0.1.0-rc.7 || ^0.1.5-rc.1',
+  /** 会话格式版本基线（= 宿主 SESSION_FORMAT_VERSION）。 */
+  sessionFormatVersion: 3,
+  /** 已知/受支持的会话格式版本（0/1/2 由本包 vendored 词表 + 本地等价折叠支持）。 */
+  knownFormatVersions: Object.freeze([0, 1, 2, 3]),
+  note: '旧格式（0/1/2）由本包自带的 vendored 词表与 legacyFoldSurface 支持,与宿主版本无关;'
+    + 'v3 用运行时词表/官方 foldSurface ⇒ 需要宿主 SESSION_FORMAT_VERSION ≥ 3。',
+});
+
+/**
+ * 语义化版本比较（只处理 `x.y.z[-pre[.n]]`;不认识 → null = 不可比较）。
+ * 预发布版 < 同号正式版（0.1.5-rc.1 < 0.1.5）。
+ * @returns {-1|0|1|null}
+ */
+export function compareVersions(a, b) {
+  const parse = (v) => {
+    const m = /^\s*(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(String(v ?? ''));
+    if (!m) return null;
+    return { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ? m[4].split('.') : [] };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i++) if (pa.nums[i] !== pb.nums[i]) return pa.nums[i] < pb.nums[i] ? -1 : 1;
+  if (pa.pre.length === 0 && pb.pre.length === 0) return 0;
+  if (pa.pre.length === 0) return 1;
+  if (pb.pre.length === 0) return -1;
+  for (let i = 0; i < Math.max(pa.pre.length, pb.pre.length); i++) {
+    const x = pa.pre[i];
+    const y = pb.pre[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    const nx = /^\d+$/.test(x);
+    const ny = /^\d+$/.test(y);
+    if (nx && ny) { if (Number(x) !== Number(y)) return Number(x) < Number(y) ? -1 : 1; continue; }
+    if (nx !== ny) return nx ? -1 : 1;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+/** 被检文件格式版本 → 支持档（`baseline` = 与测试基线同版;`legacy` = 旧格式,由本包自带实现支持）。 */
+function fileStatusOf(version) {
+  if (!TESTED_BASELINE.knownFormatVersions.includes(version)) return 'unverified';
+  return version === TESTED_BASELINE.sessionFormatVersion ? 'baseline' : 'legacy';
+}
+
+/**
+ * **运行时版本检测**：宿主版本 + 被检文件格式版本,与测试基线对比。
+ *
+ * @param {{header?:object|null, events?:Array, formatVersion?:number}} [input]
+ * @returns {{baseline:object, host:object, file:object, warnings:string[], readOnly:boolean, summary:string}}
+ *   `readOnly === true` ⇒ 调用方**不得**给出写入结论（prewrite/fix 必须拒绝）——
+ *   触发条件:被检文件格式版本未知(不在 knownFormatVersions 内),或格式完全无法识别。
+ */
+export function detectSupport({ header, events, formatVersion, hostVersion: hostOverride } = {}) {
+  const warnings = [];
+  // ── 宿主 ────────────────────────────────────────────────────────────────
+  // `hostVersion` 仅用于测试/演示（注入"比基线新的宿主"场景），生产路径不传。
+  const hostVersion = hostOverride ?? hostPackageVersion();
+  const hostCmp = compareVersions(hostVersion, TESTED_BASELINE.hostVersion);
+  let hostStatus;
+  if (hostCmp === null) {
+    hostStatus = 'unknown';
+    warnings.push(`宿主 ${TESTED_BASELINE.hostPackage} 版本不可解析（${hostVersion}）——无法与测试基线 ${TESTED_BASELINE.hostVersion} 比对;结论按"未验证"对待。`);
+  } else if (hostCmp > 0) {
+    hostStatus = 'newer-than-baseline';
+    warnings.push(`宿主 ${TESTED_BASELINE.hostPackage}@${hostVersion} **比测试基线 ${TESTED_BASELINE.hostVersion} 新** —— 本规则集未在该宿主上验证,官方语义可能已变（词表/折叠/replace 字段）;结论可能不适用,请先核对上游变更或升级本包基线。`);
+  } else if (hostCmp < 0) {
+    hostStatus = 'older-than-baseline';
+    warnings.push(`宿主 ${TESTED_BASELINE.hostPackage}@${hostVersion} 比测试基线 ${TESTED_BASELINE.hostVersion} 旧（仍在声明的 peer 范围 ${TESTED_BASELINE.peerRange} 内）—— v3 文件需要宿主能提供对应词表/折叠（本宿主 SESSION_FORMAT_VERSION=${HOST_MAX_FILE_VERSION}）。`);
+  } else {
+    hostStatus = 'baseline';
+  }
+
+  // ── 被检文件格式 ────────────────────────────────────────────────────────
+  const resolved = resolveFormatVersionDetailed({ formatVersion, header, events });
+  const unknownSource = resolved.source === 'default';
+  // S4（独立核验）:无法识别格式时**状态标签必须是 `unverified`**（README 就是这么写的:
+  // "Format unrecognisable → same: "unverified format" + read-only"）。旧实现让版本回落到默认 0
+  // ⇒ 标签打印成 `legacy`，与 README 不一致（`readOnly` 本来就对）。
+  const status = unknownSource ? 'unverified' : fileStatusOf(resolved.version);
+  const readOnly = unknownSource || status === 'unverified';
+  if (unknownSource) {
+    warnings.push('被检文件格式版本**无法识别**（无 header.version,且事件形状无判别特征:S4 replace 字段名 / system/message / assistant/chunk / assistant/attempt 皆未见）——按"未验证格式"处理,仅只读。');
+  } else if (status === 'unverified') {
+    warnings.push(`被检文件格式版本 ${resolved.version} **不在已知集合 {${TESTED_BASELINE.knownFormatVersions.join(',')}}** 内（来源 ${resolved.source}）——按"未验证格式"处理,仅只读;不得据此判定可写/可修。`);
+  }
+  const file = {
+    version: resolved.version,
+    source: resolved.source,   // explicit | header | inferred | default
+    status,                    // baseline | legacy | unverified
+    known: status !== 'unverified' && !unknownSource,
+    evidence: resolved.evidence ?? null,
+  };
+  // 无法识别时版本号是占位 0 —— 显示成 `?`（否则"文件格式 v0（default,unverified）"自相矛盾）
+  const versionLabel = unknownSource ? '?' : `v${file.version}`;
+  const summary = `宿主 ${TESTED_BASELINE.hostPackage}@${hostVersion}（基线 ${TESTED_BASELINE.hostVersion},${hostStatus}）`
+    + ` ｜ 文件格式 ${versionLabel}（${file.source},${status}${readOnly ? ',只读' : ''}）`;
+  return {
+    baseline: TESTED_BASELINE,
+    host: {
+      package: TESTED_BASELINE.hostPackage,
+      version: hostVersion,
+      sessionFormatVersion: HOST_MAX_FILE_VERSION,
+      status: hostStatus,
+      tested: hostStatus === 'baseline',
+      newerThanBaseline: hostStatus === 'newer-than-baseline',
+    },
+    file,
+    warnings,
+    readOnly,
+    summary,
+  };
+}
+
+/** 从 `loadSessionLog()` 的结果算支持面（CLI/调用方共用）。 */
+export function supportOfLog(log) {
+  return detectSupport({ header: log?.header ?? null, events: (log?.events ?? []).map((e) => e.event ?? e) });
+}

package/lib/vocab.js

@@ -1,10 +1,10 @@
 /**
- * dsh-log-contract · lib/vocab.js —— **按被检文件自身版本选词表与折叠路径**（1.3 第二半，engineer comm-369 裁定）
+ * dsh-log-contract · lib/vocab.js —— **按被检文件自身版本选词表与折叠路径**（1.3 第二半，内部评审裁定）
  *
  * 背景（一手实测）：同一健康会话，在**生产 0.1.1 解析**下 0 违规，在 **0.1.5 解析**下 3606 违规——
  * 根因是本包原先用**运行时导出**的 `KNOWN_SESSION_EVENT_TYPES` / `foldSurface` 去判**旧格式(v0)文件**：
  * 官方 0.1.5 的词汇表已不含 `assistant/chunk`（v0 词表 51 条里**有**），于是每个 chunk 事件被 E3 误报。
- * 裁定原文（comm-369 §二）：**"判据必须来自文件自身的版本，不是判官(运行时)的版本"**。
+ * 裁定原文（内部评审 §二）：**"判据必须来自文件自身的版本，不是判官(运行时)的版本"**。
  *
  * 2026-09-14 复核补强（同一裁定的完整落地）——一手证据：
  * 1. **0.1.5 的 `foldSurface` 不是"放宽"，而是换成了 v3 语义**（对照 `dsh-session@0.1.0-rc.7`
@@ -103,6 +103,15 @@ export function isLegacyFormat(version) {
  * 返回 3 / 2 / 0。**这是启发式**；有 `header.version` 或显式 `formatVersion` 时优先用它们。
  */
 export function inferFormatVersion(events = []) {
+  return inferFormatVersionDetailed(events) ?? 0;
+}
+
+/**
+ * 同上，但**没有判别证据时返回 `null`**（而不是假装 0）——供版本支持面报"未验证格式"
+ * （2026-09-14 用户要求第 1 条：无法识别格式 ⇒ 报未验证并按只读处理）。
+ * @returns {3|2|0|null} 版本号；null = 事件里没有任何判别特征
+ */
+export function inferFormatVersionDetailed(events = []) {
   let sawLegacyReplace = false;
   let sawModernReplace = false;
   let sawSystemMessage = false;
@@ -123,7 +132,26 @@ export function inferFormatVersion(events = []) {
   if (sawLegacyReplace) return sawAttempt ? 2 : 0;
   if (sawAttempt) return 2;
   if (sawChunk) return 0;
-  return 0;
+  return null;   // 无证据：调用方（版本支持面）据此报"未验证格式"
+}
+
+/**
+ * 解析版本 + **来源**（版本支持面用）：显式 `formatVersion` > `header.version` > 事件形状推断 > 无证据。
+ * @param {{formatVersion?:number, header?:object|null, events?:Array}} [input]
+ * @returns {{version:number, source:'explicit'|'header'|'inferred'|'default', evidence:string|null}}
+ */
+export function resolveFormatVersionDetailed({ formatVersion, header, events } = {}) {
+  if (Number.isSafeInteger(formatVersion) && formatVersion >= 0) {
+    return { version: formatVersion, source: 'explicit', evidence: null };
+  }
+  if (header && Number.isSafeInteger(header.version) && header.version >= 0) {
+    return { version: header.version, source: 'header', evidence: null };
+  }
+  const inferred = inferFormatVersionDetailed(events ?? []);
+  if (inferred !== null) {
+    return { version: inferred, source: 'inferred', evidence: 'replace 字段名/system/message/assistant/{chunk,attempt} 形状' };
+  }
+  return { version: 0, source: 'default', evidence: 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.13",
+  "version": "0.3.15",
   "packageManager": "pnpm@11.7.0",
   "type": "module",
   "main": "lib/index.js",
@@ -29,9 +29,9 @@
     "README.zh.md"
   ],
   "scripts": {
-    "check": "node scripts/check-syntax.mjs",
+    "check": "node scripts/check-syntax.mjs && node scripts/gen-contracts-doc.mjs --check",
     "test": "vitest run",
-    "prepublishOnly": "node scripts/check-pkg-meta.mjs && pnpm check && pnpm test"
+    "prepublishOnly": "node scripts/check-pkg-meta.mjs && node scripts/prepublish-gate.mjs && pnpm check && pnpm test"
   },
   "keywords": [
     "dsh",