dsh-research-report 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-08-26
+
+### Added
+
+- Standalone verifier CLI with SARIF/JSON output for offline citation verification.
+
+### Fixed
+
+- Exclude the self-executing verifier CLI entry from coverage (CI).
+
 ## [0.2.0] - 2026-08-23
 
 ### Added

package/README.es.md

@@ -118,6 +118,21 @@ Todos los ajustes son campos `Config` de Schemastery; los valores inválidos fal
 - **Los profiles por defecto no montan proveedor de fetch** — el `dsh-base` distribuido monta solo búsqueda, así que la captura de URLs falla ruidosamente (`WEB_UNAVAILABLE`/`WEB_PROVIDER_UNAVAILABLE`) hasta configurar un proveedor de fetch; el `gather` basado en búsqueda lista las fuentes no capturadas en la lista de brechas.
 - **Ámbito de un solo workspace** — las raíces de libro e informes se resuelven contra el directorio de trabajo del harness al montar; los despliegues multi-workspace deben configurar raíces absolutas por profile.
 
+## Verifier CLI
+
+El binario independiente `dsh-research-verify` (empaquetado como `lib/cli.js`, sin imports de `@deepseek-ai`) audita cualquier directorio de informe sellado sin montar el plugin:
+
+```sh
+dsh-research-verify --report <dir> [--seal <sha256>] [--ledger <dir>] [--format json|sarif]
+```
+
+- `--report <dir>` — directorio sellado (`manifest.json` + `report.md` + diarios de auditoría).
+- `--seal <sha256>` — hash de sello esperado para comparar con el hash del manifest recalculado; omitido = solo se informa el valor, sin comparar.
+- `--ledger <dir>` — raíz del libro de evidencias (`objects/<sha256>` + `index.jsonl`) para re-verificar claims a nivel de bytes; omitido = los re-checks de claims se omiten honestamente.
+- `--format` — `json` (por defecto) o `sarif` (SARIF 2.1.0).
+
+Recalcula el hash de sello, el hash de `report.md` y los hashes de los diarios, re-ejecuta la verificación byte-level + integridad por claim, y sale con código no nulo si alguna comprobación falla. `verifySealedReport` / `buildVerificationReport` / `renderSarif` / `renderVerificationJson` se exportan del paquete para uso como librería.
+
 ## Development
 
 ```sh

package/README.hi.md

@@ -118,6 +118,21 @@ dsh plugin --profile demo remove dsh-research-report    # अनइंस्ट
 - **डिफ़ॉल्ट profile में fetch provider नहीं** — shipped `dsh-base` केवल search माउंट करता है, इसलिए fetch provider कॉन्फ़िगर होने तक URL कैप्चर ठोंककर विफल होता है (`WEB_UNAVAILABLE`/`WEB_PROVIDER_UNAVAILABLE`); search-आधारित `gather` अकैप्चर स्रोतों को गैप-सूची में डालता है।
 - **एकल-workspace दायरा** — बही-खाता व रिपोर्ट रूट माउंट पर harness वर्किंग डायरेक्टरी के सापेक्ष resolve होते हैं; बहु-workspace डिप्लॉयमेंट को प्रति-profile निरपेक्ष रूट कॉन्फ़िगर करने चाहिए।
 
+## Verifier CLI
+
+स्वतंत्र `dsh-research-verify` बाइनरी (`lib/cli.js` के रूप में बंडल, कोई `@deepseek-ai` import नहीं) प्लगिन माउंट किए बिना किसी भी सील्ड रिपोर्ट निर्देशिका का ऑडिट करता है:
+
+```sh
+dsh-research-verify --report <dir> [--seal <sha256>] [--ledger <dir>] [--format json|sarif]
+```
+
+- `--report <dir>` — सील्ड रिपोर्ट निर्देशिका (`manifest.json` + `report.md` + ऑडिट जर्नल)।
+- `--seal <sha256>` — पुनः गणित manifest हैश से तुलना हेतु अपेक्षित सील हैश; छोड़ने पर केवल मान बताया जाता है, तुलना नहीं।
+- `--ledger <dir>` — एविडेंस लेजर रूट (`objects/<sha256>` + `index.jsonl`) दावों की बाइट-स्तरीय पुनः जाँच हेतु; छोड़ने पर दावों की पुनः जाँच ईमानदारी से छोड़ दी जाती है।
+- `--format` — `json` (डिफ़ॉल्ट) या `sarif` (SARIF 2.1.0)।
+
+यह सील हैश, `report.md` हैश और ऑडिट जर्नल हैश की पुनः गणना करता है, प्रत्येक दावे की बाइट-स्तरीय + अखंडता जाँच दोहराता है, और कोई भी जाँच विफल होने पर गैर-शून्य कोड से बाहर निकलता है। `verifySealedReport` / `buildVerificationReport` / `renderSarif` / `renderVerificationJson` पैकेज से लाइब्रेरी उपयोग हेतु निर्यात किए जाते हैं।
+
 ## Development
 
 ```sh

package/README.md

@@ -40,6 +40,7 @@
 - **Falsification ledger** — every contradicted or disproven claim is recorded in `disconfirmation.jsonl` (claim + evidence references + reason) and listed in the report's `证伪记录` appendix.
 - **Negative knowledge** — a disproven claim is remembered by its content hash (`disproofs.jsonl`); the same text re-reported against unchanged evidence is forced back to `disproven` and only re-verifies once the evidence changes.
 - **Read-only verifier loop** — after sealing, a deterministic `verifySealedReport` fallback (zero network, zero model) recomputes the seal and audit hashes and re-checks every claim, writing the machine check to `verifier-note.md`; when `ctx.jobs` is mounted a read-only verifier job is also spawned (the model review is an enhancement, never a replacement).
+- **Standalone verifier CLI** — `dsh-research-verify --report <dir> [--seal <sha256>] [--ledger <dir>] [--format json|sarif]` recomputes the seal hash + per-claim re-checks from the sealed directory alone and prints a JSON envelope or a SARIF 2.1.0 document (see [Verifier CLI](#verifier-cli)).
 - **Session-anchored evidence** — `evidence_add` accepts an optional `sessionRef` (`sessionId` + `eventRange`, validated loud); the anchor is stored, rendered in Appendix B, and registered in the manifest and `verification.jsonl`. Session-anchored evidence verifies honestly as `unverified` (`会话锚定证据需人工回查会话日志`).
 - **Honest gaps** — unverified, insufficient, contradicted, and disproven claims keep a visible `[未核实]` / `[证据不足]` / `[与证据矛盾]` / `[已证伪]` marker in the report body and are listed in Appendix A. Nothing is silently passed.
 - **No deep-research loop** — retrieval orchestration is deliberately reused: `ctx.web` for search/fetch, `ctx.jobs` for long runs. Planning and synthesis stay with the model (or an upstream plugin).
@@ -119,6 +120,21 @@ All tunables are Schemastery `Config` fields; invalid values fail the profile lo
 - **Default profiles mount no fetch provider** — the shipped `dsh-base` mounts search only, so URL capture fails loud (`WEB_UNAVAILABLE`/`WEB_PROVIDER_UNAVAILABLE`) until a fetch provider is configured; search-based `gather` lists uncaptured sources in the gap list.
 - **Single-workspace scope** — ledger and report roots resolve against the harness working directory at mount; multi-workspace deployments should configure absolute roots per profile.
 
+## Verifier CLI
+
+The standalone `dsh-research-verify` binary (bundled as `lib/cli.js`, zero `@deepseek-ai` imports) audits any sealed report directory without mounting the plugin:
+
+```sh
+dsh-research-verify --report <dir> [--seal <sha256>] [--ledger <dir>] [--format json|sarif]
+```
+
+- `--report <dir>` — the sealed report directory (`manifest.json` + `report.md` + the audit journals).
+- `--seal <sha256>` — the expected seal hash to compare the recomputed manifest hash against. Omitted = the recomputed hash is reported without comparison.
+- `--ledger <dir>` — the evidence ledger root (`objects/<sha256>` + `index.jsonl`) enabling per-claim byte-level re-checks. Omitted = claim re-checks are skipped honestly.
+- `--format` — `json` (default) or `sarif` (SARIF 2.1.0).
+
+It recomputes the seal hash (SHA-256 of `manifest.json`), the `report.md` hash, and the audit-journal hashes, re-runs the byte-level + integrity check for every claim, and exits non-zero when any performed check fails. The same `verifySealedReport` / `buildVerificationReport` / `renderSarif` / `renderVerificationJson` functions are exported from the package for library use.
+
 ## Development
 
 ```sh

package/README.pt.md

@@ -118,6 +118,21 @@ Todos os ajustes são campos `Config` de Schemastery; valores inválidos falham
 - **Profiles por omissão não montam provider de fetch** — o `dsh-base` distribuído monta apenas pesquisa, por isso a captura de URLs falha ruidosamente (`WEB_UNAVAILABLE`/`WEB_PROVIDER_UNAVAILABLE`) até configurar um provider de fetch; o `gather` baseado em pesquisa lista as fontes não capturadas na lista de lacunas.
 - **Âmbito de um só workspace** — as raízes de livro e relatórios resolvem contra o diretório de trabalho do harness no mount; deployments multi-workspace devem configurar raízes absolutas por profile.
 
+## Verifier CLI
+
+O binário independente `dsh-research-verify` (empacotado como `lib/cli.js`, sem imports de `@deepseek-ai`) audita qualquer diretório de relatório selado sem montar o plugin:
+
+```sh
+dsh-research-verify --report <dir> [--seal <sha256>] [--ledger <dir>] [--format json|sarif]
+```
+
+- `--report <dir>` — diretório selado (`manifest.json` + `report.md` + diários de auditoria).
+- `--seal <sha256>` — hash de selo esperado para comparar com o hash do manifest recalculado; omitido = apenas o valor é informado, sem comparação.
+- `--ledger <dir>` — raiz do ledger de evidências (`objects/<sha256>` + `index.jsonl`) para re-verificar claims byte a byte; omitido = os re-checks de claims são omitidos honestamente.
+- `--format` — `json` (padrão) ou `sarif` (SARIF 2.1.0).
+
+Recalcula o hash de selo, o hash de `report.md` e os hashes dos diários, re-executa a verificação byte-level + integridade por claim, e sai com código não nulo se alguma checagem falhar. `verifySealedReport` / `buildVerificationReport` / `renderSarif` / `renderVerificationJson` são exportados do pacote para uso como biblioteca.
+
 ## Development
 
 ```sh

package/README.zh.md

@@ -118,6 +118,21 @@ dsh plugin --profile demo remove dsh-research-report    # 卸载
 - **默认 profile 不挂载 fetch provider**——官方 `dsh-base` 只挂搜索，所以配置 fetch provider 之前 URL 抓取会响亮失败（`WEB_UNAVAILABLE`/`WEB_PROVIDER_UNAVAILABLE`）；基于搜索的 `gather` 会把未捕获的来源列入缺口清单。
 - **单 workspace 作用域**——账本与报告根目录在挂载时相对 harness 工作目录解析；多 workspace 部署应在各 profile 配置绝对路径。
 
+## Verifier CLI
+
+独立的 `dsh-research-verify` 二进制（打包为 `lib/cli.js`，零 `@deepseek-ai` 导入）无需挂载插件即可审计任意密封报告目录：
+
+```sh
+dsh-research-verify --report <dir> [--seal <sha256>] [--ledger <dir>] [--format json|sarif]
+```
+
+- `--report <dir>`：密封报告目录（`manifest.json` + `report.md` + 审计日志）。
+- `--seal <sha256>`：期望的 seal 哈希，用于与重算的 manifest 哈希比对；缺省则只报告重算值、不比对。
+- `--ledger <dir>`：证据账本根目录（`objects/<sha256>` + `index.jsonl`），用于逐 claim 字节级复检；缺省则如实跳过 claim 复检。
+- `--format`：`json`（默认）或 `sarif`（SARIF 2.1.0）。
+
+它重算 seal 哈希（`manifest.json` 的 SHA-256）、`report.md` 哈希与审计日志哈希，逐 claim 重跑字节级 + 完整性检查，任一已执行检查失败则以非零码退出。`verifySealedReport` / `buildVerificationReport` / `renderSarif` / `renderVerificationJson` 亦从包导出供库调用。
+
 ## Development
 
 ```sh

package/lib/cli.js

@@ -0,0 +1,103 @@
+import { _ as sha256Of, a as renderSarif, o as renderVerificationJson, r as buildVerificationReport, s as verifySealedReport } from "./verify-sealed-CMJp1f_v.js";
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+//#region src/cli.ts
+/**
+* Standalone sealed-report verifier CLI. One command recomputes the seal hash
+* (SHA-256 of manifest.json), the report hash, and the audit-journal hashes,
+* re-runs the byte-level + integrity claim check against the evidence ledger,
+* and prints a SARIF 2.1.0 or JSON report. Zero network, zero model, zero
+* @deepseek-ai imports — this entry bundles to a self-contained binary.
+*
+* Usage:
+*   dsh-research-verify --report <dir> [--seal <sha256>] [--ledger <dir>] [--format json|sarif]
+*
+* @module dsh-research-report/cli
+*/
+/** Print usage and exit non-zero. */
+function usage(message) {
+	if (message !== void 0) console.error(`dsh-research-verify: ${message}`);
+	console.error("Usage: dsh-research-verify --report <dir> [--seal <sha256>] [--ledger <dir>] [--format json|sarif]");
+	console.error("  --report <dir>    Sealed report directory (holds manifest.json + report.md).");
+	console.error("  --seal <sha256>   Expected seal hash to compare the recomputed manifest hash against.");
+	console.error("  --ledger <dir>    Evidence ledger root (objects/<sha256> + index.jsonl) for claim re-checks.");
+	console.error("  --format <fmt>    Output format: json (default) or sarif.");
+	process.exit(message === void 0 ? 0 : 2);
+}
+/** Parse argv into {@link CliArgs}. */
+function parseArgs(argv) {
+	const args = {
+		reportDir: "",
+		seal: null,
+		ledger: null,
+		format: "json"
+	};
+	for (let index = 0; index < argv.length; index++) {
+		const token = argv[index];
+		switch (token) {
+			case "--help":
+			case "-h":
+				usage();
+				break;
+			case "--report":
+				args.reportDir = argv[++index] ?? "";
+				break;
+			case "--seal":
+				args.seal = argv[++index] ?? null;
+				break;
+			case "--ledger":
+				args.ledger = argv[++index] ?? null;
+				break;
+			case "--format":
+				args.format = argv[++index] === "sarif" ? "sarif" : "json";
+				break;
+			default: usage(`unknown argument ${token}`);
+		}
+	}
+	if (args.reportDir === "") usage("--report is required");
+	return args;
+}
+/** Read one evidence snapshot from a ledger root by its manifest evidence record. */
+async function readLedgerEvidence(ledgerRoot, record) {
+	let content;
+	try {
+		content = await readFile(path.join(ledgerRoot, "objects", record.sha256), "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return {
+			content: "",
+			integrity: "missing"
+		};
+		throw error;
+	}
+	return {
+		content,
+		integrity: sha256Of(content) === record.sha256 ? "ok" : "tampered"
+	};
+}
+/** The standalone verifier entry point. */
+async function main(argv) {
+	const args = parseArgs(argv);
+	const manifestText = await readFile(path.join(args.reportDir, "manifest.json"), "utf8");
+	const manifest = JSON.parse(manifestText);
+	const sealHash = sha256Of(manifestText);
+	const evidenceById = new Map((Array.isArray(manifest.evidence) ? manifest.evidence : []).map((record) => [record.id, record]));
+	const claimRecheck = args.ledger === null ? "skipped-no-ledger" : "rechecked";
+	const result = await verifySealedReport(args.reportDir, args.seal ?? sealHash, {
+		readFile: (file) => readFile(file, "utf8"),
+		readEvidenceContent: async (id) => {
+			if (args.ledger === null) return void 0;
+			const record = evidenceById.get(id);
+			if (record === void 0) return void 0;
+			return readLedgerEvidence(args.ledger, record);
+		}
+	});
+	const report = buildVerificationReport(result, args.reportDir, args.seal, claimRecheck);
+	process.stdout.write(args.format === "sarif" ? renderSarif(report) : renderVerificationJson(report));
+	if (!report.ok) process.exitCode = 1;
+}
+main(process.argv.slice(2)).catch((error) => {
+	console.error(`dsh-research-verify: ${error instanceof Error ? error.message : String(error)}`);
+	process.exitCode = 1;
+});
+//#endregion
+export {};