dsh-plugin-usage-stats 0.4.0

package/src/scanner.ts

@@ -0,0 +1,391 @@
+/** 会话用量扫描（纯函数核心，零第三方依赖）：
+ *  读 `<DSH_HOME>/sessions/<workspace-slug>/<session-dir>/session.v3.jsonl.zstd`，
+ *  zstd 解压后逐行折叠成 UsageFact[]。
+ *
+ *  折叠规则（与设计文档一致）：
+ *  - 当前模型 = 最近一条 request/header 的 data.header.config.{provider,model}；缺 header 归 unknown。
+ *  - 每条 assistant/message.data.usage 归入 scope `<sessionId>:<turn>:<step>`（turn/step 由最近
+ *    turn/start / step/start 记录维护）；同 scope 出现新样本即替换旧样本 = 重试取末条（与 token-meter 同规则）。
+ *  - inputTokens 为「未缓存输入」（total = input + output + cacheRead [+ cacheWrite] 已在真实数据核实）。
+ *  - session 行补 cwd/createdAt/delegationDepth/origin；session/title 行补标题。
+ *
+ *  增量解码（会话文件是追加式多帧 zstd，每次全量重解是浪费）：
+ *  - `frameSpans` 按 RFC 8878 解析帧头与块头（块体按 24bit Block_Size 直接跳过，不碰 LZ4），
+ *    得到完整帧的字节区间；文件尾半帧不算数（下次追加补齐再吃），legacy 帧/坏帧即停。
+ *  - `foldChunk` 把一段解压文本喂进可续跑的 FoldState（游标/计数/facts 按 scope 去重 + 残行 tail），
+ *    增量重放与全量重放逐字节等价（scope last-wins 天然幂等，计数只增）。
+ *  - 持久化与失效判定在 store.ts / aggregate.ts；本文件只保证纯函数 + 解码边界正确。
+ */
+import { readFile, readdir, stat } from "node:fs/promises";
+import { execFile, spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { zstdDecompressSync } from "node:zlib";
+
+const execFileAsync = promisify(execFile);
+
+/** 多帧 zstd 全量解码：首选 `zstd -dc`；node:zlib 兜底仅在无 CLI 时启用（它只解首帧，多帧文件会静默丢数据）。 */
+async function decompressZstd(path: string): Promise<string> {
+  try {
+    const { stdout } = await execFileAsync("zstd", ["-dc", path], { maxBuffer: 256 * 1024 * 1024 });
+    return stdout;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    const buf = await readFile(path);
+    return zstdDecompressSync(buf).toString("utf8");
+  }
+}
+
+export interface UsageFact {
+  /** `<sessionId>:<turn>:<step>`，同 scope 只保留末条样本。 */
+  scope: string;
+  sessionId: string;
+  provider: string;
+  model: string;
+  /** YYYY-MM-DD（本地时区，按记录 time）。 */
+  date: string;
+  /** 记录时间（ms epoch）。 */
+  time: number;
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  /** usage 对象是否上报过任一缓存字段（未上报的 provider 命中率应显示“—”而非 0%）。 */
+  hasCache: boolean;
+}
+
+export interface SessionMeta {
+  sessionId: string;
+  cwd: string;
+  title: string;
+  createdAt: number;
+  delegationDepth: number;
+  /** 子代理会话（origin/parentSession/delegationDepth>0 任一命中）。 */
+  subagent: boolean;
+  /** 会话级计数（逐行顺带 O(1)，不做去重）：user/message 行数。 */
+  userMessages: number;
+  /** assistant/message 行数（无 usage 样本的也计）。 */
+  assistantMessages: number;
+  /** tool/call 行数。 */
+  toolCalls: number;
+}
+
+export interface Fold {
+  facts: UsageFact[];
+  meta: SessionMeta | null;
+}
+
+/** 可续跑的折叠状态：游标（模型归因/turn/step）+ 单调计数 + scope 去重的 facts + 半行 tail。
+ *  持久化时 scopeIndex 不写盘（恢复时从 facts 重建）。 */
+export interface FoldState {
+  meta: SessionMeta | null;
+  provider: string;
+  model: string;
+  curTurn: number;
+  curStep: number;
+  facts: UsageFact[];
+  scopeIndex: Map<string, number>;
+  /** 上一段末尾未完成的 JSONL 行（追加式写入可能把一行拆进两帧），下一段拼回头部。 */
+  tail: string;
+  /** 会话 id 兜底（文件路径的上级目录名）。 */
+  sessionIdHint: string;
+}
+
+export function newFoldState(sessionIdHint: string): FoldState {
+  return {
+    meta: null,
+    provider: "unknown",
+    model: "unknown",
+    curTurn: -1,
+    curStep: -1,
+    facts: [],
+    scopeIndex: new Map(),
+    tail: "",
+    sessionIdHint,
+  };
+}
+
+export function foldSnapshot(s: FoldState): Fold {
+  return { facts: s.facts, meta: s.meta };
+}
+
+/** 喂入一段解压文本（允许半行截断，残尾进 tail 续下段）。JSON 解析失败行静默跳过（与全量口径一致）。 */
+export function foldChunk(s: FoldState, text: string): void {
+  let buf = s.tail ? s.tail + text : text;
+  const nl = buf.lastIndexOf("\n");
+  if (nl < 0) {
+    s.tail = buf;
+    return;
+  }
+  s.tail = buf.slice(nl + 1);
+  buf = buf.slice(0, nl);
+  for (const line of buf.split("\n")) {
+    if (!line || !line.trim()) continue;
+    let r: any;
+    try {
+      r = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!r || typeof r !== "object") continue;
+    const t = r.type;
+    if (t === "session") {
+      // 新会话开始：模型归因状态重置（每文件一会话，防御跨会话残留）。
+      s.provider = "unknown";
+      s.model = "unknown";
+      s.curTurn = -1;
+      s.curStep = -1;
+      const depth = Number(r.delegationDepth) || 0;
+      s.meta = {
+        sessionId: String(r.id || s.sessionIdHint),
+        cwd: String(r.cwd || ""),
+        title: "",
+        createdAt: Number(r.createdAt) || 0,
+        delegationDepth: depth,
+        subagent: r.origin != null || r.parentSession != null || depth > 0,
+        userMessages: 0,
+        assistantMessages: 0,
+        toolCalls: 0,
+      };
+    } else if (t === "session/title") {
+      if (s.meta && r.data && typeof r.data.title === "string") s.meta.title = r.data.title;
+    } else if (t === "user/message") {
+      if (s.meta) s.meta.userMessages++;
+    } else if (t === "tool/call") {
+      if (s.meta) s.meta.toolCalls++;
+    } else if (t === "request/header") {
+      const c = r.data?.header?.config;
+      if (c && typeof c.model === "string") {
+        s.provider = String(c.provider || "unknown");
+        s.model = c.model;
+      }
+    } else if (t === "turn/start") {
+      s.curTurn = Number(r.data?.turn) || 0;
+      s.curStep = -1;
+    } else if (t === "step/start") {
+      s.curTurn = Number(r.data?.turn) || s.curTurn;
+      s.curStep = Number(r.data?.step) || 0;
+    } else if (t === "assistant/message") {
+      if (s.meta) s.meta.assistantMessages++;
+      const u = r.data?.usage;
+      if (!u || typeof u.inputTokens !== "number" || typeof u.outputTokens !== "number") continue;
+      if (typeof r.time !== "number" || !s.meta) continue;
+      const scope = `${s.meta.sessionId}:${s.curTurn}:${s.curStep}`;
+      const fact: UsageFact = {
+        scope,
+        sessionId: s.meta.sessionId,
+        provider: s.provider,
+        model: s.model,
+        date: localDate(r.time),
+        time: r.time,
+        input: Number(u.inputTokens) || 0,
+        output: Number(u.outputTokens) || 0,
+        cacheRead: Number(u.cacheReadTokens) || 0,
+        cacheWrite: Number(u.cacheWriteTokens) || 0,
+        hasCache: u.cacheReadTokens != null || u.cacheWriteTokens != null,
+      };
+      const prev = s.scopeIndex.get(scope);
+      if (prev !== undefined) s.facts[prev] = fact;
+      else {
+        s.scopeIndex.set(scope, s.facts.length);
+        s.facts.push(fact);
+      }
+    }
+  }
+}
+
+/** 折叠一个会话的 JSONL 文本为 UsageFact[] + SessionMeta（纯函数，可单测；= 全量 foldChunk 薄包装 + 尾行结算）。 */
+export function foldJsonl(sessionIdHint: string, text: string): Fold {
+  const s = newFoldState(sessionIdHint);
+  foldChunk(s, text);
+  if (s.tail) foldChunk(s, "\n"); // 无换行结尾的最后一行也要结算（旧 split 语义等价）
+  return foldSnapshot(s);
+}
+
+const FILE_NAME = "session.v3.jsonl.zstd";
+
+/** DSH 会话根目录：config.sessionsHome 优先，其次 $DSH_HOME/sessions，最后 ~/.dsh/sessions。 */
+export function sessionsRoot(sessionsHome?: string): string {
+  if (sessionsHome) return sessionsHome;
+  const dshHome = process.env.DSH_HOME;
+  if (dshHome) return join(dshHome, "sessions");
+  return join(homedir(), ".dsh", "sessions");
+}
+
+/** 列出全部 workspace slug 下的会话文件（全局视图），排序保证确定性。 */
+export async function listSessionFiles(root: string): Promise<string[]> {
+  const out: string[] = [];
+  let slugs: string[] = [];
+  try {
+    slugs = await readdir(root);
+  } catch {
+    return out;
+  }
+  for (const slug of slugs) {
+    let dirs: string[] = [];
+    try {
+      dirs = await readdir(join(root, slug));
+    } catch {
+      continue;
+    }
+    for (const dir of dirs) {
+      const full = join(root, slug, dir, FILE_NAME);
+      try {
+        const s = await stat(full);
+        if (s.isFile()) out.push(full);
+      } catch {
+        /* 非会话目录或缺文件：跳过 */
+      }
+    }
+  }
+  out.sort();
+  return out;
+}
+
+/** 毫秒 → 本地日期 YYYY-MM-DD。 */
+export function localDate(ms: number): string {
+  const d = new Date(ms);
+  const p = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+/* ---------------- zstd 帧边界（RFC 8878：只读帧头/块头，不解压内容） ---------------- */
+
+const FRAME_MAGIC = 0xfd2fb528;
+const LEGACY_MAGICS = [0x1eb52ffd, 0x2fb52815, 0x24b52f6d];
+
+/** 从 start 走一个 zstd 帧，返回结束字节；半帧/坏帧/legacy → null。
+ *  位布局以真帧反推 + fzstd 参考实现双重对表（勿凭 RFC 记忆改动）：
+ *  FHD: bit7-6=FCS_flag(字节数=flag?1<<flag:single) bit5=Single_Segment bit3=Unused(须0) bit2=Checksum bit1-0=Did_flag(0/1/2/4B)。
+ *  Block 头（24bit LE）: bit0=Last bit2-1=Type(0=Raws体size｜1=RLE体1B重复值｜2=Compressed体size｜3=坏) bit23-3=Size(21bit)。 */
+function frameEnd(buf: Buffer, start: number): number | null {
+  let off = start;
+  if (off + 5 > buf.length) return null;
+  const magic = buf.readUInt32LE(off);
+  if (magic !== FRAME_MAGIC || LEGACY_MAGICS.includes(magic)) return null;
+  off += 4;
+  const fhd = buf.readUInt8(off);
+  off += 1;
+  if (fhd & 0x08) return null;
+  const single = (fhd >> 5) & 1;
+  const didFlag = fhd & 3;
+  const checksum = (fhd >> 2) & 1;
+  const fcsFlag = fhd >> 6;
+  if (!single) off += 1; // Window_Descriptor
+  off += (fcsFlag ? 1 << fcsFlag : single) + (didFlag === 3 ? 4 : didFlag);
+  for (;;) {
+    if (off + 3 > buf.length) return null;
+    const bh = buf[off] | (buf[off + 1] << 8) | (buf[off + 2] << 16);
+    off += 3;
+    const last = (bh & 1) !== 0;
+    const type = (bh >> 1) & 3;
+    const size = bh >>> 3;
+    if (type === 3) return null;
+    if (type === 1) {
+      if (off + 1 > buf.length) return null; // RLE：1 字节重复值
+      off += 1;
+    } else {
+      if (off + size > buf.length) return null; // Raws/Compressed：体长 = size
+      off += size;
+    }
+    if (last) break;
+  }
+  if (checksum) off += 4;
+  return off <= buf.length ? off : null;
+}
+
+/** 完整帧区间表（增量解码的水位线依据）。 */
+export function frameSpans(buf: Buffer): Array<[number, number]> {
+  const spans: Array<[number, number]> = [];
+  let off = 0;
+  for (;;) {
+    const end = frameEnd(buf, off);
+    if (end === null || end <= off) break;
+    spans.push([off, end]);
+    off = end;
+  }
+  return spans;
+}
+
+/** 已消化完整帧的字节水位（= frameSpans 末区间终点；无完整帧为 0）。 */
+export function frameWatermark(buf: Buffer): number {
+  const spans = frameSpans(buf);
+  return spans.length ? spans[spans.length - 1][1] : 0;
+}
+
+export function hintOf(path: string): string {
+  const parts = path.split("/");
+  return parts[parts.length - 2] || "unknown";
+}
+
+/** 读单个会话文件并全量折叠（首轮/失效重扫路径）。解码失败上抛，空 fold 兜底在 store 层决策。 */
+export async function readFold(path: string): Promise<Fold> {
+  return foldJsonl(hintOf(path), await decompressZstd(path));
+}
+
+/** 从持久 FoldState 续建运行时状态（scopeIndex 重建）。 */
+export function reviveState(hint: string, saved: Pick<FoldState, "meta" | "provider" | "model" | "curTurn" | "curStep" | "facts" | "tail">): FoldState {
+  const s = newFoldState(hint);
+  s.meta = saved.meta;
+  s.provider = saved.provider;
+  s.model = saved.model;
+  s.curTurn = saved.curTurn;
+  s.curStep = saved.curStep;
+  s.facts = saved.facts;
+  s.tail = saved.tail || "";
+  for (let i = 0; i < s.facts.length; i++) s.scopeIndex.set(s.facts[i].scope, i);
+  return s;
+}
+
+/** 增量续跑：把 `fromBytes`（上次完整帧水位）之后的新增帧并进 state。
+ *  @returns 新水位；无新增完整帧返回原值。解码失败抛错（调用方回退全量）。 */
+export async function foldFrom(path: string, state: FoldState, fromBytes: number): Promise<number> {
+  const buf = await readFile(path);
+  const spans = frameSpans(buf);
+  const watermark = spans.length ? spans[spans.length - 1][1] : 0;
+  if (watermark <= fromBytes) return fromBytes;
+  const fresh = spans.filter(([s]) => s >= fromBytes);
+  const text = await decompressSpans(buf, fresh);
+  foldChunk(state, text);
+  return watermark;
+}
+
+/** 新增帧区间解压：CLI（stdin 吃拼接帧）优先；无 CLI 时 node:zlib 按帧逐个解。
+ *  zstdCliMissing 一旦置真（本机没装 CLI）不再重试；输出超限等运行期错误照常抛，由调用方回退全量。 */
+let zstdCliMissing = false;
+async function decompressSpans(buf: Buffer, spans: Array<[number, number]>): Promise<string> {
+  if (!zstdCliMissing) {
+    try {
+      const seg = Buffer.concat(spans.map(([s, e]) => buf.subarray(s, e)));
+      return await zstdStdin(seg);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") zstdCliMissing = true;
+      else throw err;
+    }
+  }
+  let out = "";
+  for (const [s, e] of spans) out += zstdDecompressSync(buf.subarray(s, e)).toString("utf8");
+  return out;
+}
+
+/** `zstd -dc` 子进程喂 stdin（execFile 的 input 选项不在 @types 类型里，自管流 + 尺寸护栏）。 */
+function zstdStdin(seg: Buffer): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn("zstd", ["-dc"]);
+    let out = "";
+    let err = "";
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (d: string) => {
+      out += d;
+      if (out.length > 256 * 1024 * 1024) {
+        child.kill();
+        reject(new Error("zstd output exceeds 256MB guard"));
+      }
+    });
+    child.stderr.on("data", (d: string) => (err += d));
+    child.on("error", reject);
+    child.on("close", (code) => (code === 0 ? resolve(out) : reject(new Error(`zstd exit ${code}: ${err.slice(0, 200)}`))));
+    child.stdin.end(seg);
+  });
+}

package/src/store.ts

@@ -0,0 +1,152 @@
+/** 增量扫描的存量持久化：折叠状态落 `<DSH_HOME>/cache/usage-stats.folds.json`。
+ *  语义 = 每个会话文件一行 {file, size, mtimeMs, ino, bytes(已消化完整帧水位), FoldState 快照}；
+ *  host 重启后：未变文件 0 解压直接复用，追加文件只解新增帧（foldFrom），
+ *  size 变小 / inode 变化（文件被替换）→ 该行失效整文件重解。
+ *  水位铁律：bytes 只能是 frameWatermark 的真实完整帧边界（文件尾半帧不计），
+ *  否则追加后跨水位的帧会被漏掉；半帧尾巴等下次追加补齐。
+ *  写盘策略 = 单次扫描若有推进则 tmp+rename 原子落一次；坏文件（JSON 解析失败）静默作废从零开始。
+ *  ⚠ 版本铁律：foldJsonl/foldFrom/归因语义任何变化必须 bump VERSION——旧快照里冻结的是
+ *  当时算出的 facts，永不回改（实测教训：scanner 早期误产 unknown-model facts，被增量状态
+ *  带病复用，页面 unknown 行在逻辑修复后仍不消失，只能靠版本门整体作废）。 */
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { foldFrom, frameWatermark, hintOf, readFold, reviveState, type Fold, type FoldState } from "./scanner.ts";
+
+/** 存量格式+折叠语义的联合版本：与磁盘 payload.version 不符 = 冷启动全量重扫。 */
+export const VERSION = 2;
+
+export interface UnitRow {
+  file: string;
+  size: number;
+  mtimeMs: number;
+  ino: number;
+  /** 已消化的完整帧字节水位；0 = 帧链不可识（legacy/坏头），每次走全量。 */
+  bytes: number;
+  meta: FoldState["meta"];
+  provider: string;
+  model: string;
+  curTurn: number;
+  curStep: number;
+  facts: FoldState["facts"];
+  tail: string;
+}
+
+export class FoldStore {
+  readonly file: string;
+  rows = new Map<string, UnitRow>();
+  private states = new Map<string, FoldState>();
+  private loaded = false;
+  dirty = false;
+
+  /** root = sessions 目录；cache 落其同级的 cache/ 下（sessionsHome 自定义时同样成立）。 */
+  constructor(root: string) {
+    this.file = join(dirname(root), "cache", "usage-stats.folds.json");
+  }
+
+  async load(): Promise<void> {
+    if (this.loaded) return;
+    this.loaded = true;
+    try {
+      const parsed = JSON.parse(await readFile(this.file, "utf8"));
+      if (parsed && parsed.version === VERSION && Array.isArray(parsed.units)) {
+        for (const u of parsed.units) if (u && typeof u.file === "string" && typeof u.bytes === "number") this.rows.set(u.file, u);
+      }
+    } catch {
+      /* 缺文件/坏文件 = 冷启动 */
+    }
+  }
+
+  /** 取得该文件最新折叠结果；内部按行状态决定 复用 / 增量 / 全量。 */
+  async foldFor(path: string, st: { size: number; mtimeMs: number; ino: number }): Promise<Fold> {
+    const row = this.rows.get(path);
+    if (row && row.ino === st.ino && row.size === st.size && row.mtimeMs === st.mtimeMs) {
+      return this.foldOf(row); // 未变：直接复用存量
+    }
+    if (row && row.ino === st.ino && row.bytes > 0 && st.size > row.size) {
+      // 追加增长：只解新增完整帧。水位没推进（文件尾半帧未补齐）也正常，等下次。
+      try {
+        const next = await foldFrom(path, this.stateOf(path, row), row.bytes);
+        if (next !== row.bytes) this.dirty = true;
+        row.bytes = next;
+        row.size = st.size;
+        row.mtimeMs = st.mtimeMs;
+        this.syncRow(path, row);
+        return this.foldOf(row);
+      } catch {
+        /* 增量失败：落到全量 */
+      }
+    }
+    // 冷启动 / 文件被替换 / size 倒退 / 无水位：整文件重解，水位取真实帧边界（尾半帧留给下次）。
+    let fold: Fold;
+    try {
+      fold = await readFold(path);
+    } catch {
+      // 解码失败：不落行——增量续跑要求存量状态完整（首帧含 session/meta 行），坏文件每轮重试（与旧缓存语义一致）。
+      return { facts: [], meta: null };
+    }
+    const buf = await readFile(path).catch(() => null);
+    const wm = buf ? frameWatermark(buf) : 0;
+    const fresh: UnitRow = {
+      file: path,
+      size: st.size,
+      mtimeMs: st.mtimeMs,
+      ino: st.ino,
+      bytes: wm,
+      meta: fold.meta,
+      provider: "unknown",
+      model: "unknown",
+      curTurn: -1,
+      curStep: -1,
+      facts: fold.facts,
+      tail: "",
+    };
+    this.rows.set(path, fresh);
+    this.states.delete(path); // 全量重解后旧 state 作废，下次增量从快照重建
+    this.dirty = true;
+    return this.foldOf(fresh);
+  }
+
+  /** 增量成功后把 state 的游标/计数/facts 回写行（bytes 由调用处单独赋值）。 */
+  private syncRow(path: string, row: UnitRow): void {
+    const s = this.states.get(path);
+    if (!s) return;
+    row.meta = s.meta;
+    row.provider = s.provider;
+    row.model = s.model;
+    row.curTurn = s.curTurn;
+    row.curStep = s.curStep;
+    row.facts = s.facts;
+    row.tail = s.tail;
+  }
+
+  private stateOf(path: string, row: UnitRow): FoldState {
+    let s = this.states.get(path);
+    if (!s) {
+      s = reviveState(hintOf(path), row);
+      this.states.set(path, s);
+    }
+    return s;
+  }
+
+  private foldOf(row: UnitRow): Fold {
+    // facts/meta 是共享引用；同一次扫描内消费方只读，安全。
+    return { facts: row.facts, meta: row.meta ?? null };
+  }
+
+  /** 清理消失文件 + 原子落盘（仅 dirty 时写）。 */
+  async flush(aliveFiles: Set<string>): Promise<void> {
+    for (const key of [...this.rows.keys()]) if (!aliveFiles.has(key)) this.rows.delete(key);
+    for (const key of [...this.states.keys()]) if (!aliveFiles.has(key)) this.states.delete(key);
+    if (!this.dirty) return;
+    this.dirty = false;
+    try {
+      await mkdir(dirname(this.file), { recursive: true });
+      const payload = { version: VERSION, units: [...this.rows.values()] };
+      const tmp = this.file + ".tmp";
+      await writeFile(tmp, JSON.stringify(payload));
+      await rename(tmp, this.file);
+    } catch {
+      /* cache 写失败不影响查询，下次再试 */
+    }
+  }
+}

package/tests/contract-pair.test.ts

@@ -0,0 +1,108 @@
+/** 两端契约配对门（AGENTS「两端改名必须同步」的机器化）：
+ *  服务端真解析（运行时 SRC 标记 + 网关 methodParameterNames 语义的函数源码形参解析）
+ *  ↔ 浏览器半真声明（lib/client.js 文本提取的 descriptor 调用点与固定字段）。
+ *  改任一端而忘另一端 = 本测试红灯。v3 曾为 without inject 误诊半天（真因是 fiber 可见性
+ *  而非契约错位），但契约错位这条风险真实存在，从此由机器兜底而非人肉对表。
+ *  descriptor 形态对齐 @deepseek-ai/dsh-typert-generator 的 codegen 产物规范
+ *  （emitter.invocationLiteral：acceptsUndefined 显式可选参 + sourceLocation 出处锚点——
+ *  后者是机器可校验的：指到服务端真实定义行，方法挪位/改名即红灯）。
+ *  共享实现：本门等价于工作区 plugin-standard/（本地包暂未发 npm；上架后本文件改为
+ *  contractPairSuite() 三行注册，删去本地实现——不留双轨）。 */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import { UsageStatsService } from "../src/cordis.ts";
+
+const MARKER_KEY = "@deepseek-ai/dsh-typert-protocol/remote-methods";
+const ROOT = new URL("..", import.meta.url);
+const CLIENT = readFileSync(new URL("lib/client.js", ROOT), "utf8");
+const SERVER = readFileSync(new URL("src/cordis.ts", ROOT), "utf8");
+
+/** client 调用点的真声明提取（第三参 sourceLocation 必填——官方产物恒带）。 */
+interface ClientCall {
+  method: string;
+  param: string;
+  file: string;
+  line: number;
+  column: number;
+}
+function clientDescriptorCalls(): ClientCall[] {
+  const calls: ClientCall[] = [];
+  for (const m of CLIENT.matchAll(/descriptor\(\s*"([^"]+)",\s*"([^"]+)",\s*\{\s*file:\s*"([^"]+)",\s*line:\s*(\d+),\s*column:\s*(\d+)\s*\}\s*\)/g)) {
+    calls.push({ method: m[1], param: m[2], file: m[3], line: Number(m[4]), column: Number(m[5]) });
+  }
+  return calls;
+}
+
+/** 网关 methodParameterNames 的解析复刻（与 cordis.test.ts 同规则）：括号内 → 逗号切分 → trim → 纯标识符。 */
+function srcParamNames(fn: Function): string[] {
+  const source = Function.prototype.toString.call(fn);
+  const open = source.indexOf("(");
+  const close = source.indexOf(")", open + 1);
+  const inside = source.slice(open + 1, close);
+  return inside
+    .split(",")
+    .map((token) => token.trim())
+    .filter((token) => /^[A-Za-z_$][\w$]*$/.test(token));
+}
+
+interface RemoteMethodsMarker {
+  version: number;
+  methods: Array<{ method: string; invocation: { kind: string } }>;
+}
+
+test("client descriptor 调用点全部提取且无漏网（防绕过式新增方法）", () => {
+  const calls = clientDescriptorCalls();
+  assert.ok(calls.length > 0, "必须至少有一个带 sourceLocation 的 descriptor 调用点");
+  // descriptor( 出现次数 = 1 处定义 + N 处调用；对不上说明有调用点没被提取正则抓到。
+  const occurrences = (CLIENT.match(/\bdescriptor\(/g) ?? []).length;
+  assert.equal(occurrences, calls.length + 1, "descriptor 调用点数与提取数不一致（提取正则失配）");
+});
+
+test("两端方法集与 wire 参数名一一对应", () => {
+  const marker = Object.getOwnPropertyDescriptor(UsageStatsService.prototype, MARKER_KEY) as { value: RemoteMethodsMarker } | undefined;
+  assert.ok(marker, "服务端必须挂 remote-methods 标记（原型字符串键）");
+  const proto = UsageStatsService.prototype as unknown as Record<string, Function>;
+  const serverMethods = new Map<string, string[]>();
+  for (const entry of marker!.value.methods) {
+    assert.equal(entry.invocation.kind, "direct", `方法 ${entry.method} 的 invocation 形态`);
+    assert.equal(typeof proto[entry.method], "function", `标记声明了 ${entry.method} 但实现缺失`);
+    serverMethods.set(entry.method, srcParamNames(proto[entry.method]!));
+  }
+
+  const clientCalls = clientDescriptorCalls();
+  assert.equal(clientCalls.length, serverMethods.size, "方法数量两端不一致");
+  for (const call of clientCalls) {
+    assert.ok(serverMethods.has(call.method), `client 声明了服务端没有的方法 ${call.method}`);
+    const params = serverMethods.get(call.method)!;
+    assert.equal(params.length, 1, `服务端 ${call.method} 应为单参数（descriptor() 只编码单参数形态）`);
+    assert.equal(params[0], call.param, `两端 ${call.method} 的 wire 参数名错位：server=${params[0]} client=${call.param}`);
+  }
+});
+
+test("sourceLocation 锚定服务端真实定义行（官方 codegen 产物规范）", () => {
+  for (const call of clientDescriptorCalls()) {
+    const path = new URL(call.file, ROOT);
+    assert.ok(existsSync(path), `sourceLocation.file 不存在：${call.file}`);
+    const line = readFileSync(path, "utf8").split("\n")[call.line - 1] ?? "";
+    assert.ok(
+      line.slice(call.column - 1).startsWith(`${call.method}(`),
+      `sourceLocation ${call.file}:${call.line}:${call.column} 未直指 ${call.method} 的定义行（内容：${JSON.stringify(line.trim())}）——方法挪位/改名后同步 descriptor 的 line`,
+    );
+  }
+});
+
+test("descriptor 固定字段与客户端挂载路径两端一致", () => {
+  // id 前缀 = SETTINGS_NS + "#usageStats/"；service/namespace 字面量 = usageStats。
+  assert.match(CLIENT, /id:\s*SETTINGS_NS\s*\+\s*"#usageStats\/"\s*\+\s*method/);
+  assert.match(CLIENT, /service:\s*"usageStats"/);
+  assert.match(CLIENT, /namespace:\s*"usageStats"/);
+  assert.match(CLIENT, /source:\s*"json"/);
+  assert.match(CLIENT, /mode:\s*"strict"/);
+  assert.match(CLIENT, /acceptsUndefined:\s*true/, "filter 可省略必须用官方显式字段声明（codegen 规范）");
+  // 服务端 provide 的命名空间必须同为 usageStats（网关按 namespace/method 路由）。
+  assert.match(SERVER, /provide\(\s*"usageStats"/);
+  // 浏览器半取服务必须走名字解析（属性式在动态 fiber 被可见性隔离拒绝，见 AGENTS 宿主契约）。
+  assert.match(CLIENT, /ctx\.get\("remote\.usageStats"\)/);
+  assert.doesNotMatch(CLIENT, /ctx\.remote\.usageStats\b/, "属性式访问会 throw without inject");
+});