euthyna 0.1.0 → 0.1.1

package/README.md

@@ -46,11 +46,14 @@ between you and the agent:
 
 ### 1. It measures what a model cannot
 
-Two fact producers — a zero-dependency Node CLI:
-
-- **`history`** — for every line a change deletes, it finds the commit that introduced
-  that line and classifies that commit from its own message. If the deleted code came
-  from a security fix, that is flagged. This is git archaeology no model can do from
+Three fact producers — a zero-dependency Node CLI:
+
+- **`history`** — for every line a change deletes, it attributes the line to a commit
+  and classifies that commit from its message, its own diff, and the deleted line's
+  content (a deleted `if (!authorized)` is flagged even under a "tweaks" subject). By
+  default the attribution is blame's "last touched"; `--origins` digs for the commit
+  that *first introduced* the content with `git log -S`. If the deleted code came from
+  a security fix, that is flagged. This is git archaeology no model can do from
   reading a diff.
 - **`coverage`** — was this symbol *ever actually invoked* by a test? It has exactly two
   answers: never invoked (established), or entered but that proves nothing about any
@@ -58,6 +61,12 @@ Two fact producers — a zero-dependency Node CLI:
   unreachable code as covered, and "line covered → call ran" is wrong in exactly the
   direction an audit cannot afford. The reasoning is in
   [`docs/fact-contract.md`](https://github.com/slow-stack/euthyna/blob/main/docs/fact-contract.md) §6.2.
+- **`deps`** — what version is a dependency *actually* pinned to? It reads the lockfile
+  (package-lock.json / Cargo.lock / go.mod) and reports the resolved versions, or that a
+  dependency is absent from the tree entirely. This is the fact that resolves
+  supply-chain claims ("the app uses a vulnerable version of X"): the version-to-CVE
+  mapping is left to the adjudication layer, exactly as the fact contract requires. See
+  [`docs/fact-contract.md`](https://github.com/slow-stack/euthyna/blob/main/docs/fact-contract.md) §6.3.
 
 ### 2. It gates what the agent claims
 
@@ -67,6 +76,14 @@ impact, and their counterparts. A claim that cannot produce evidence is **downgr
 an observation**, not reported as a finding. "I'm done" becomes a package: claims,
 evidence, and the commands that reproduce both.
 
+The gates are not only prose. `euthyna gate <report>` reads an adjudication report and
+mechanically checks every finding against its verdict — evidence down to `path:L123`, a
+reproduce command, an impact statement, consistent gate statuses — and downgrades
+whatever does not measure up. `--verify` re-runs the reproduce commands: `git` commands
+by default, interpreter commands (`node`/`npm`/`python`) only with the explicit
+`--allow-exec`, because an interpreter command from a report is arbitrary code and the
+flag is the caller vouching for that report.
+
 ---
 
 ## 🖥️ Which tools it works in, and how to install
@@ -79,6 +96,8 @@ the project is deliberately zero-dependency.
 | **DSH** | Copy `.agents/skills/euthyna/` into `~/.agents/skills/` (user-wide) or `<project>/.agents/skills/`. Markdown hot-reloads; no restart needed. | `npm install -g euthyna` — runs in any terminal |
 | **Claude Code** | Copy the same folder into `~/.claude/skills/` | Same |
 | **Codex** | The same Markdown layer works; packaging goes through Codex's plugin/marketplace format | Same |
+| **Hermes** | Copy the same folder into `~/.hermes/skills/` under a category folder (Hermes reads the open skill standard; or install from a repo with `hermes skills install`) | Same |
+| **OpenCode** | Copy the same folder into `~/.agents/skills/` or `~/.config/opencode/skills/` (OpenCode loads both; unknown frontmatter fields are ignored) | Same |
 | **Any terminal** | — | `npm install -g euthyna`, then `euthyna …` |
 
 Two honest notes:
@@ -98,8 +117,10 @@ Two honest notes:
 
 ```sh
 npm install -g euthyna
-euthyna history --repo <path> --base main --head HEAD
+euthyna history --repo <path> --base main --head HEAD          # add --origins to chase the first introducer
 euthyna coverage --coverage coverage/coverage-final.json --symbol <name>
+euthyna deps --repo <path> --dep <name>
+euthyna gate <adjudication-report.md> --verify --cwd <repo>    # mechanically check the six gates
 ```
 
 Or without a global install: `npx euthyna history --repo <path> --base main`.
@@ -108,7 +129,7 @@ From a checkout instead (development):
 
 ```sh
 git clone https://github.com/slow-stack/euthyna
-cd euthyna && npm test                                 # 92 tests; no install step exists
+cd euthyna && npm test                                 # 167 tests; no install step exists
 node bin/euthyna.js history --repo <path> --base main --head HEAD
 ```
 
@@ -122,10 +143,11 @@ What `history` reports looks like this:
       复现: git blame --porcelain -L 104,104 -L 114,114 <base> -- lib/checks/.../evaluate.js
 ```
 
-Every deleted line is blamed back to the commit that introduced it, and the `复现`
+Every deleted line is blamed back to a commit, and the `复现`
 (Reproduce) command lets you re-derive the claim yourself without trusting the report.
-Add `--json` for the structured fact report, and `--pickaxe` to detect lines that were
-removed and are now being added back.
+Add `--json` for the structured fact report, `--pickaxe` to detect lines that were
+removed and are now being added back, and `--origins` to attribute deleted lines to the
+commit that first introduced their content rather than to blame's last modifier.
 
 ### Exit codes are part of the contract
 
@@ -134,10 +156,10 @@ process exit code**, which makes their output unusable as a CI gate. This one do
 
 | Code | Meaning |
 |---|---|
-| `0` | Measured; nothing security-classified found |
-| `10` | Measured; at least one `security`-classified fact exists |
+| `0` | Measured; nothing security-classified found — or a `gate` report fully passes |
+| `10` | Measured; at least one `security`-classified fact exists — or a `gate` report has findings downgraded to observations |
 | `1` | Usage error |
-| `2` | **Could not measure at all** — must not be read as clean |
+| `2` | **Could not measure at all** — must not be read as clean (also: a `gate` report that cannot be read or has no findings) |
 
 `2` being distinct from `0` is the whole point: *failing to measure* and *measuring and
 finding nothing* are different things.
@@ -148,9 +170,9 @@ finding nothing* are different things.
 
 | Piece | What it is | Status |
 |---|---|---|
-| **Fact producers** | A zero-dependency Node CLI that answers two questions deterministically | Working, tested |
+| **Fact producers** | A zero-dependency Node CLI that answers three questions deterministically | Working, tested |
 | **The skill** | The audit discipline itself, as loadable Markdown | Working, loadable |
-| **The benchmark** | A blind recall measurement for the adjudication layer | Four rounds complete |
+| **The benchmark** | A blind recall measurement for the adjudication layer | Four rounds complete; the loop is one command (`bench/adjudicate.js`), with a deterministic golden round on CI |
 
 ---
 
@@ -165,8 +187,14 @@ This project tries to be explicit about the difference. Current state:
   [crewAI](https://github.com/crewAIInc/crewAI) (Python); deleted lines attributed to the
   commits that introduced them, then checked **by hand** against `git blame`. The checks
   developed for that comparison now run as regression tests in the suite.
-- **`coverage` on real output in two formats** — c8/V8 JSON and coverage.py JSON (format 3) —
-  distinguishing all three states correctly.
+- **`coverage` on real output in three formats** — c8/V8 JSON, classic istanbul (jest/nyc, same
+  fnMap/f shape) and coverage.py JSON (format 3) — distinguishing all three states correctly, and
+  refusing anything that is not a recognizable coverage report instead of answering "symbol not
+  located" against it.
+- **`deps` against a real lockfile** — resolved versions reported with a line-level evidence
+  pointer into the lockfile, and absent dependencies reported as established absences rather
+  than silent skips. Verified against a populated npm v3 lockfile and fixture lockfiles for
+  Cargo.lock and go.mod.
 - **Adjudication recall and specificity**, measured blind: **10/10 cases**, 4 real
   vulnerabilities all caught, 6 non-vulnerabilities all correctly cleared, no abstentions.
   Round 2 repeated every case three times — **30 adjudications, zero flips**, four of them
@@ -186,6 +214,16 @@ This project tries to be explicit about the difference. Current state:
   and [`bench/RESULTS-round4.md`](https://github.com/slow-stack/euthyna/blob/main/bench/RESULTS-round4.md).
 - **The delivery-gate mechanism**, by running the real host plugin: blocking works, and the two
   documented ways of getting it wrong do not. See [`docs/dsh-stop-gate.md`](https://github.com/slow-stack/euthyna/blob/main/docs/dsh-stop-gate.md).
+- **The gate discipline, mechanically.** `euthyna gate` is not a claim in prose: the suite
+  pins the contract per verdict (a TRUE POSITIVE without `path:L123` evidence, a reproduce
+  command or all six gates passing is downgraded; a FALSE POSITIVE needs a failing gate with
+  a reason), and `--verify` is tested to *not* execute an interpreter command without
+  `--allow-exec`. `test/skill.test.js` fails CI if the skill text stops declaring the six
+  gates, the three verdicts, or the command that enforces them.
+- **The adjudication loop, end to end and on CI.** `bench/adjudicate.js` runs a whole round —
+  blind tree, one adjudicator process per case, machine-validated reports, scoring — and a
+  deterministic `golden` round runs on every push, so the pipeline (and `score.js` going red
+  on a wrong verdict) is checked without a model.
 
 ### Not verified
 
@@ -197,6 +235,16 @@ This project tries to be explicit about the difference. Current state:
 - **Recall in the field.** The benchmark's real-bug cases are constructed; whether the
   discipline helps on code nobody staged for it is unmeasured.
 - **Source maps, bundlers, monorepos** for the coverage producer. Untested.
+- **A real model round on CI.** The golden round is deterministic plumbing, not an
+  adjudication: it writes the ground truth into the reports by design. A model round needs
+  credentials and is non-deterministic by nature, so it stays a local/manual step
+  (`bench/README.md` documents the command) rather than a CI gate that could flake.
+- **`--verify` as a sandbox.** It is not one, and does not claim to be: it executes the
+  report's commands with your privileges, `git` only unless `--allow-exec` is passed.
+- **`deps` beyond three formats and version facts only.** pnpm/yarn/poetry lockfiles are
+  detected but not parsed (reported as *not evaluated*, never guessed at); go.mod reports the
+  *declared* requirement, not the resolved build version; and the producer never maps a version
+  to a CVE — that mapping is deliberately left to the adjudication layer.
 - **Anything about the case-study targets' security** — the runs found nothing to endorse or
   condemn; that is not a statement about either project. See
   [`docs/case-study-crewai.md`](https://github.com/slow-stack/euthyna/blob/main/docs/case-study-crewai.md) and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euthyna",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Deterministic fact producers for security auditing: which deleted code came from a security fix, and which changed symbols no test ever executed.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -15,8 +15,11 @@
  */
 import process from 'node:process';
 import path from 'node:path';
+import { readFile } from 'node:fs/promises';
 import { collectHistoryFacts } from './facts/history.js';
 import { collectCoverageFacts } from './facts/coverage.js';
+import { collectDependencyFacts } from './facts/deps.js';
+import { parseGateReport, validateFindings, verifyFinding, renderGateReport } from './gate.js';
 import { makeReport, renderReport, safeTextLines, KIND } from './contract.js';
 import { repoToplevel, revParse } from './git.js';
 
@@ -37,6 +40,11 @@ const COVERAGE_PRODUCER = {
   version: '0.1.0',
   purpose: '符号调用计数（只能证伪）'
 };
+const DEPS_PRODUCER = {
+  name: 'euthyna-deps',
+  version: '0.1.0',
+  purpose: '依赖锁定版本（读取 lockfile，不含漏洞判定）'
+};
 
 const HELP = `
 euthyna —— 给 AI 编码 agent 用的确定性事实产出器
@@ -44,24 +52,40 @@ euthyna —— 给 AI 编码 agent 用的确定性事实产出器
 它不是扫描器。它只回答两个模型算不准的问题，并把答案写成带证据的事实。
 
 用法:
-  euthyna history  --base <rev> [--head <rev>] [--repo <dir>] [--pickaxe] [--json]
+  euthyna history  --base <rev> [--head <rev>] [--repo <dir>] [--pickaxe] [--origins] [--json]
   euthyna coverage --coverage <file> --symbol <name> [--file <path>] [--json]
+  euthyna deps     [--repo <dir>] [--lockfile <file>] --dep <name> [--dep <name>] [--json]
+  euthyna gate     <报告文件> [--verify] [--cwd <dir>] [--json]
 
 命令:
   history    本次变更删掉了哪些代码、它们分别由哪个提交引入、该提交是不是安全修复
              --base    必填，比较的基线版本（如 main、HEAD~5、某个 commit）
              --head    可选，默认 HEAD
              --pickaxe 额外检查「曾被移除又加回来」的新增行（有探针上限）
+             --origins 用 git log -S 把删除行归属到「最初引入」该内容的提交，
+                       而非 blame 的「最后修改者」（有探针上限，比默认慢）
   coverage   某个符号在测试运行中到底有没有被调用过
              --coverage  覆盖率数据文件，c8 的 coverage-final.json
              --symbol    要查询的符号名，可重复
              --file      可选，限定到某个文件
+  deps       某个依赖在 lockfile 里被锁定/声明成什么版本（供应链声明的裁决依据）
+             --repo      可选，依赖清单所在目录（默认当前目录，自动检测）
+             --lockfile  可选，显式指定清单文件（支持 package-lock.json / Cargo.lock / go.mod）
+             --dep       要查询的依赖名，可重复
+             注：只报版本事实，不判「是否含漏洞」——版本到 CVE 的映射归判定层
+  gate       检查一份审计报告是否符合 6 门禁契约（不测量，只核对报告的自我声明）
+             <报告文件>   报告的 markdown 文件，裁定格式见技能 SKILL.md
+             --verify     重跑每条 TRUE POSITIVE 的复现命令（按 argv 执行，不经过 shell）
+                          默认只执行 git 命令；⚠ 执行结果以你的权限生效，只对你信任的报告用
+             --allow-exec 允许 --verify 执行解释器命令（node/npm/python）——
+                          它们能跑报告里的任意代码，加了它就等于你为该报告背书
+             --cwd <dir>  --verify 的工作目录（默认当前目录）
 
 退出码:
-  0   已测量，没有安全相关的发现
-  10  已测量，且存在被分类为 security 的事实
+  0   已测量，没有安全相关的发现；或 gate 报告全部通过门禁契约
+  10  已测量，且存在被分类为 security 的事实；或 gate 报告有 finding 被降级
   1   用法错误
-  2   完全无法测量（此时**不得**当作干净）
+  2   完全无法测量（此时**不得**当作干净）；或 gate 报告无法读取/没有可校验的 finding
 
 注意: 缺数据不等于干净。无法测量的判据会列在输出的「未评估的判据」一节。
 `;
@@ -146,7 +170,8 @@ async function runHistory(flags) {
     cwd: toplevel,
     base,
     head,
-    pickaxe: flags.pickaxe === true
+    pickaxe: flags.pickaxe === true,
+    origins: flags.origins === true
   });
 
   const report = makeReport({
@@ -198,6 +223,123 @@ async function runCoverage(flags) {
   return { exit: measured ? EXIT.CLEAN : EXIT.UNMEASURED, report };
 }
 
+async function runDeps(flags) {
+  const cwd = path.resolve(flags.repo ? String(flags.repo) : process.cwd());
+  const deps = asArray(flags.dep).map(String);
+  const lockfile = flags.lockfile ? String(flags.lockfile) : undefined;
+
+  // Asking for nothing is a caller mistake, not a measurement failure.
+  if (deps.length === 0) {
+    return { exit: EXIT.USAGE, error: 'deps 需要至少一个 --dep <name>' };
+  }
+
+  const { facts, evaluated, notEvaluated, measured } = await collectDependencyFacts({
+    cwd,
+    lockfile,
+    deps
+  });
+
+  const report = makeReport({
+    producer: DEPS_PRODUCER,
+    subject: { repo: cwd, lockfile: lockfile ?? '(自动检测)', deps },
+    facts,
+    evaluated,
+    notEvaluated
+  });
+
+  return { exit: measured ? EXIT.CLEAN : EXIT.UNMEASURED, report };
+}
+async function runGate(flags, positional) {
+  const file = positional[1];
+  if (!file) {
+    return { exit: EXIT.USAGE, error: 'gate 需要 <报告文件>（markdown，裁定格式见技能 SKILL.md）' };
+  }
+
+  let text;
+  try {
+    text = await readFile(path.resolve(file), 'utf8');
+  } catch (error) {
+    // An unreadable report is not a clean pass: there is nothing to check, and
+    // "nothing was checked" must not read as "everything passed".
+    return { exit: EXIT.UNMEASURED, error: `无法读取报告 ${file}: ${error.message}` };
+  }
+
+  const { findings, unparseable } = parseGateReport(text);
+  if (findings.length === 0 && unparseable.length === 0) {
+    return { exit: EXIT.UNMEASURED, error: `报告 ${file} 中没有可校验的 finding（需要 BUG #N <VERDICT> — 说明 形式）` };
+  }
+
+  const validated = validateFindings(findings);
+  for (const line of unparseable) {
+    validated.push({ unparseableLine: line, violations: ['无法解析的 BUG 行'], downgraded: true });
+  }
+
+  if (flags.verify) {
+    const cwd = path.resolve(flags.cwd ? String(flags.cwd) : process.cwd());
+    const allowInterpreters = flags['allow-exec'] === true;
+    for (const entry of validated) {
+      if (entry.unparseableLine) continue;
+      entry.verification = await verifyFinding(entry.finding, { cwd, allowInterpreters });
+      const v = entry.verification;
+      // Every status other than "verified" means the reproduction claim was
+      // not actually checked, which is a downgrade: a refused tool, an
+      // interpreter awaiting consent, an unparseable command and a failed run
+      // are different failures, but none of them is a verified reproduction.
+      if (v.status === 'failed') {
+        entry.violations.push(`复现命令未通过（exit ${v.exitCode ?? '?'}${v.detail ? `: ${v.detail}` : ''}）`);
+        entry.downgraded = true;
+      } else if (v.status === 'refused') {
+        entry.violations.push(`复现命令被拒绝（${v.tool} 不在白名单）——复现未验证`);
+        entry.downgraded = true;
+      } else if (v.status === 'needs-consent') {
+        entry.violations.push(`复现命令是解释器命令（${v.tool}），未执行——复现未验证；信任该报告时加 --allow-exec`);
+        entry.downgraded = true;
+      } else if (v.status === 'unparseable') {
+        entry.violations.push('复现命令无法拆分为 argv——复现未验证');
+        entry.downgraded = true;
+      }
+      // no-command is already a structural violation (a TRUE POSITIVE without a
+      // reproduce line), so --verify does not double-report it.
+    }
+  }
+
+  const downgraded = validated.filter(e => e.downgraded).length;
+  const result = { file, findings: validated, unparseable, downgraded, verify: flags.verify === true };
+
+  if (flags.json) {
+    return {
+      exit: downgraded > 0 ? EXIT.FLAGGED : EXIT.CLEAN,
+      json: JSON.stringify(
+        {
+          command: 'gate',
+          file,
+          findings: validated.map(e => ({
+            ...(e.unparseableLine
+              ? { unparseable: e.unparseableLine }
+              : {
+                  number: e.finding.number,
+                  verdict: e.finding.verdict,
+                  claim: e.finding.claim,
+                  evidence: e.finding.evidence,
+                  reproduce: e.finding.reproduce,
+                  impact: e.finding.impact,
+                  gates: e.finding.gates
+                }),
+            violations: e.violations,
+            downgraded: e.downgraded
+          })),
+          downgraded
+        },
+        null,
+        2
+      )
+    };
+  }
+
+  renderGateReport(result);
+  return { exit: downgraded > 0 ? EXIT.FLAGGED : EXIT.CLEAN, report: null };
+}
+
 /** Entry point. Returns the process exit code. */
 export async function main(argv = process.argv.slice(2)) {
   const { positional, flags } = parseArgs(argv);
@@ -213,6 +355,10 @@ export async function main(argv = process.argv.slice(2)) {
     result = await runHistory(flags);
   } else if (command === 'coverage') {
     result = await runCoverage(flags);
+  } else if (command === 'deps') {
+    result = await runDeps(flags);
+  } else if (command === 'gate') {
+    result = await runGate(flags, positional);
   } else {
     // stderr boundary, mirroring the render boundary in contract.js: text that
     // reaches the error channel may carry user or repo-controlled bytes (an
@@ -228,9 +374,14 @@ export async function main(argv = process.argv.slice(2)) {
     return result.exit;
   }
 
+  if (result.json) {
+    process.stdout.write(`${result.json}\n`);
+    return result.exit;
+  }
+
   if (flags.json) {
     process.stdout.write(`${JSON.stringify(result.report, null, 2)}\n`);
-  } else {
+  } else if (result.report) {
     renderReport(result.report);
   }
 

package/src/contract.js

@@ -66,7 +66,8 @@ export function safeTextLines(value) {
 export const KIND = Object.freeze({
   HISTORY: 'history',
   REINTRODUCTION: 'reintroduction',
-  TEST_COVERAGE: 'test_coverage'
+  TEST_COVERAGE: 'test_coverage',
+  DEPENDENCY: 'dependency'
 });
 
 /** Fact status. `unknown` is a first-class value, not an error. */

package/src/facts/coverage.js

@@ -62,14 +62,18 @@ function reproduceCommand({ coverageFile, symbol, file }) {
 /**
  * Read a coverage report.
  *
- * Two formats are accepted:
+ * Three formats are accepted, all identified by shape rather than by filename:
  *
  * 1. c8 / v8-to-istanbul `coverage-final.json` — per-file keys are
  *    path/all/statementMap/s/branchMap/b/fnMap/f. There is no istanbul `hash`,
  *    and `branchMap` is a relabelled V8 block range rather than an if/else
  *    model, so a consumer written against classic istanbul field lists reads
  *    the wrong thing.
- * 2. coverage.py JSON (`coverage json`, format 3) — top level is
+ * 2. classic istanbul (jest's default provider, nyc) `coverage-final.json` —
+ *    the same per-file statementMap/s/branchMap/b/fnMap/f plus a `hash` field.
+ *    The symbol locator only reads fnMap/f, which classic istanbul and c8 emit
+ *    in the same shape, so both resolve through the same code path.
+ * 3. coverage.py JSON (`coverage json`, format 3) — top level is
  *    `{meta, files}`, and per-file `functions` maps a function name
  *    (`name`, or `Class.method` for methods) to
  *    `{executed_lines, missing_lines, start_line, ...}`. There is **no
@@ -77,6 +81,10 @@ function reproduceCommand({ coverageFile, symbol, file }) {
  *    evidence that the function was never entered. coverage.py reports
  *    functions that were never called as long as their module was loaded,
  *    which is exactly what makes "never invoked" an established fact.
+ *
+ * Anything that matches none of these shapes is **not a coverage report this
+ * producer can read**, and is reported as notEvaluated — never fed through the
+ * locator, where it would answer "symbol not located" with a straight face.
  */
 export async function loadCoverage(coverageFile) {
   const raw = await readFile(coverageFile, 'utf8');
@@ -98,6 +106,35 @@ function isCoveragePyReport(coverage) {
   );
 }
 
+/**
+ * Identify the coverage format by shape, or null when the file is not a
+ * coverage report at all. c8 and classic istanbul share the fnMap/f shape the
+ * locator reads; they differ only in `hash` (istanbul has it, c8 does not) and
+ * `all` (c8 has it), neither of which the locator reads — but naming the format
+ * honestly is still part of the fact, so the distinction is kept.
+ */
+export function detectCoverageFormat(coverage) {
+  if (isCoveragePyReport(coverage)) return 'coverage.py';
+
+  const entries = Object.entries(coverage).filter(([, v]) => v && typeof v === 'object');
+  if (entries.length === 0) return null;
+
+  // A real c8/istanbul entry carries both `fnMap` (function metadata) and `f`
+  // (per-index invocation counts). Requiring both stops a partial shape — a
+  // file with `fnMap` but no `f`, say — from being classified as coverage and
+  // then emitting "never invoked" for a count a missing `f` defaults to zero.
+  // coverage.py's per-file `functions` is only valid inside a `meta.files`
+  // report, which isCoveragePyReport already handled above; a bare `functions`
+  // object is not a JS report and must not be accepted here.
+  const jsShaped = entries.some(
+    ([, e]) =>
+      e.fnMap && typeof e.fnMap === 'object' && e.f && typeof e.f === 'object'
+  );
+  if (!jsShaped) return null;
+
+  return entries.some(([, e]) => typeof e === 'object' && 'hash' in e) ? 'istanbul' : 'c8';
+}
+
 /**
  * Locate a symbol inside one file entry and normalise the hit.
  *
@@ -215,6 +252,21 @@ export async function collectCoverageFacts({ coverageFile, targets = [] } = {})
     return { facts, evaluated, notEvaluated, measured: false };
   }
 
+  // A non-empty object that matches no known shape is not a coverage report at
+  // all. Feeding it through the locator would answer "symbol not located" with
+  // a straight face — the confident wrong answer this producer exists to refuse.
+  const format = detectCoverageFormat(coverage);
+  if (format === null) {
+    notEvaluated.push(
+      notEvaluatedEntry(
+        KIND.TEST_COVERAGE,
+        '覆盖率数据不是可识别的报告形状（既无 c8/istanbul 的 fnMap/f，也无 coverage.py 的 functions）——' +
+          '它可能根本不是覆盖率文件，任何「符号未定位/未覆盖」的结论在此都不可信'
+      )
+    );
+    return { facts, evaluated, notEvaluated, measured: false };
+  }
+
   if (targets.length === 0) {
     notEvaluated.push(notEvaluatedEntry(KIND.TEST_COVERAGE, '没有指定要查询的符号（--symbol）'));
     return { facts, evaluated, notEvaluated, measured: false };
@@ -331,6 +383,7 @@ export async function collectCoverageFacts({ coverageFile, targets = [] } = {})
   evaluated.push({
     kind: KIND.TEST_COVERAGE,
     producer: 'euthyna-coverage',
+    format,
     count: facts.length
   });