dsh-research-report 0.1.0

package/lib/index.js

@@ -0,0 +1,2143 @@
+import path from "node:path";
+import z from "@deepseek-ai/schemastery";
+import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { KNOWN_SESSION_EVENT_TYPES } from "@deepseek-ai/dsh-session";
+import { createHash, randomBytes } from "node:crypto";
+import { Service } from "@deepseek-ai/cordis";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/config.ts
+/**
+* Config schema and resolution for `dsh-research-report`. Every tunable is a
+* validated {@link Config} field changeable from cordis.yml; the resolution
+* step validates bounds so misconfiguration fails loud at mount.
+* @module dsh-research-report/config
+*/
+/** Schemastery schema: the loader validates and fills defaults before `apply`. */
+const Config = z.object({
+	enabled: z.boolean().default(true),
+	ledgerRoot: z.string().default(".research-ledger"),
+	reportRoot: z.string().default("research-reports"),
+	maxEvidenceBytes: z.number().default(2097152),
+	maxEvidencePerReport: z.number().default(200),
+	fetchTimeoutMs: z.number().default(2e4)
+});
+/** Throw unless `value` is a positive safe integer. */
+function assertPositiveInt(name, value) {
+	if (!Number.isSafeInteger(value) || value <= 0) throw new TypeError(`${name} must be a positive safe integer, got ${String(value)}`);
+}
+/**
+* Resolve one configured root to an absolute path. Relative roots anchor at
+* the harness working directory (the workspace the deployment runs in), which
+* keeps the ledger and the sealed reports inside the workspace by default.
+* @param value - the configured root.
+* @param name - the config key, for error messages.
+* @returns the absolute root path.
+*/
+function resolveRoot(value, name) {
+	if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty path`);
+	return path.resolve(value);
+}
+/**
+* Validate raw values and fill explicit defaults. Invalid bounds throw here —
+* misconfiguration fails loud at mount even without the Schemastery loader.
+* @param config - raw (possibly partial) plugin config.
+* @returns the fully resolved config.
+*/
+function resolveConfig(config = {}) {
+	const maxEvidenceBytes = config.maxEvidenceBytes ?? 2097152;
+	assertPositiveInt("maxEvidenceBytes", maxEvidenceBytes);
+	const maxEvidencePerReport = config.maxEvidencePerReport ?? 200;
+	assertPositiveInt("maxEvidencePerReport", maxEvidencePerReport);
+	const fetchTimeoutMs = config.fetchTimeoutMs ?? 2e4;
+	assertPositiveInt("fetchTimeoutMs", fetchTimeoutMs);
+	return {
+		enabled: config.enabled ?? true,
+		ledgerRoot: resolveRoot(config.ledgerRoot ?? ".research-ledger", "ledgerRoot"),
+		reportRoot: resolveRoot(config.reportRoot ?? "research-reports", "reportRoot"),
+		maxEvidenceBytes,
+		maxEvidencePerReport,
+		fetchTimeoutMs
+	};
+}
+//#endregion
+//#region src/ledger.ts
+/**
+* The evidence ledger: a content-addressed snapshot store with JSONL journals.
+*
+* Layout under the configured `ledgerRoot`:
+* - `objects/<sha256>` — one immutable snapshot per content hash (same content
+*   is stored exactly once; an "update" is a new object, history is never
+*   rewritten).
+* - `index.jsonl` — evidence registrations: id → hash, origin, capturedAt,
+*   title, bytes. Append-only.
+* - `claims.jsonl` — claim registrations: id → text, evidenceIds, optional
+*   dataset bridge fields. Append-only.
+* - `verdicts.jsonl` — verification verdicts; the latest line per claim wins.
+*
+* Tamper detection is the point of the design: every content read recomputes
+* the SHA-256 of the object file and compares it against the indexed hash —
+* a mismatch surfaces as `tampered`, a deleted object as `missing`.
+*
+* This module is pure Node (zero DSH imports) so it stays testable in
+* isolation; policy (size caps, fetch) lives in the provider.
+*
+* @module dsh-research-report/ledger
+*/
+/** SHA-256 hex of one UTF-8 string. */
+function sha256Of(content) {
+	return createHash("sha256").update(content, "utf8").digest("hex");
+}
+/** A loud ledger failure (audit state must never degrade silently). */
+var LedgerError = class extends Error {
+	/** The machine-routable failure code. */
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "LedgerError";
+		this.code = code;
+	}
+};
+/** Read one JSONL journal; a corrupt line fails loud with file and line number. */
+async function readJournal(file) {
+	let text;
+	try {
+		text = await readFile(file, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw new LedgerError("IO", `cannot read journal ${file}: ${error.message}`);
+	}
+	const lines = [];
+	const rows = text.split("\n");
+	for (let index = 0; index < rows.length; index++) {
+		const row = rows[index];
+		if (row.trim() === "") continue;
+		try {
+			lines.push(JSON.parse(row));
+		} catch {
+			throw new LedgerError("JOURNAL_CORRUPT", `corrupt JSONL at ${file}:${index + 1}`);
+		}
+	}
+	return lines;
+}
+/**
+* The content-addressed evidence ledger. Writes are serialized through an
+* internal promise queue so concurrent tool calls cannot interleave journals.
+*/
+var EvidenceLedger = class {
+	/** Absolute ledger root directory. */
+	root;
+	/** Write serialization chain (never rejects — each link absorbs the previous error). */
+	queue = Promise.resolve();
+	/**
+	* @param root - absolute ledger root directory.
+	*/
+	constructor(root) {
+		this.root = root;
+	}
+	get objectsDir() {
+		return path.join(this.root, "objects");
+	}
+	get indexFile() {
+		return path.join(this.root, "index.jsonl");
+	}
+	get claimsFile() {
+		return path.join(this.root, "claims.jsonl");
+	}
+	get verdictsFile() {
+		return path.join(this.root, "verdicts.jsonl");
+	}
+	/** Run `work` after all previously queued writes settle. */
+	enqueue(work) {
+		const run = this.queue.then(work);
+		this.queue = run.then(() => void 0, () => void 0);
+		return run;
+	}
+	/** Ensure the directory layout exists. */
+	async ensureLayout() {
+		await mkdir(this.objectsDir, { recursive: true });
+	}
+	/** Write one snapshot object atomically (tmp + rename); no-op when present. */
+	async writeObject(hash, content) {
+		const target = path.join(this.objectsDir, hash);
+		try {
+			await readFile(target);
+			return;
+		} catch (error) {
+			if (error.code !== "ENOENT") throw new LedgerError("IO", `cannot stat object ${hash}: ${error.message}`);
+		}
+		const temporary = path.join(this.objectsDir, `.${hash}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`);
+		await writeFile(temporary, content, "utf8");
+		try {
+			await rename(temporary, target);
+		} catch (error) {
+			try {
+				await readFile(target);
+			} catch {
+				throw new LedgerError("IO", `cannot commit object ${hash}: ${error.message}`);
+			}
+		}
+	}
+	/**
+	* Register one evidence snapshot. Same content dedupes to the stored object;
+	* a caller-chosen id that already exists with DIFFERENT content is refused
+	* loudly (history is never rewritten).
+	* @param input - id (optional), title, origin, content, capturedAt.
+	* @returns the record plus whether this call created it.
+	*/
+	async putEvidence(input) {
+		return this.enqueue(async () => {
+			await this.ensureLayout();
+			const hash = sha256Of(input.content);
+			const id = input.id ?? `ev-${hash.slice(0, 12)}`;
+			const existing = (await readJournal(this.indexFile)).find((line) => line.id === id);
+			if (existing !== void 0) {
+				if (existing.hash !== hash) throw new LedgerError("ID_CONFLICT", `evidence id "${id}" is already registered with different content (indexed ${existing.hash}, new ${hash}); choose a new id — snapshots are immutable`);
+				return {
+					record: existing,
+					created: false
+				};
+			}
+			await this.writeObject(hash, input.content);
+			const record = {
+				id,
+				hash,
+				title: input.title,
+				origin: input.origin,
+				capturedAt: input.capturedAt,
+				bytes: Buffer.byteLength(input.content, "utf8")
+			};
+			await appendFile(this.indexFile, `${JSON.stringify(record)}\n`, "utf8");
+			return {
+				record,
+				created: true
+			};
+		});
+	}
+	/**
+	* Register claims (id → text, evidenceIds). Re-registering a claim id with
+	* a different text or different bindings is refused loudly.
+	* @param claims - the registrations to append.
+	* @param registeredAt - ISO-8601 registration time.
+	* @returns the durable claim lines (existing lines for idempotent repeats).
+	*/
+	async registerClaims(claims, registeredAt) {
+		return this.enqueue(async () => {
+			await this.ensureLayout();
+			const journal = await readJournal(this.claimsFile);
+			const out = [];
+			for (const claim of claims) {
+				const existing = journal.find((line) => line.id === claim.id);
+				if (existing !== void 0) {
+					if (!(existing.text === claim.text && JSON.stringify(existing.evidenceIds) === JSON.stringify(claim.evidenceIds) && existing.dataset === claim.dataset)) throw new LedgerError("ID_CONFLICT", `claim id "${claim.id}" is already registered with different text or bindings; choose a new claim id — registrations are immutable`);
+					out.push(existing);
+					continue;
+				}
+				const line = {
+					...claim,
+					registeredAt
+				};
+				await appendFile(this.claimsFile, `${JSON.stringify(line)}\n`, "utf8");
+				journal.push(line);
+				out.push(line);
+			}
+			return out;
+		});
+	}
+	/**
+	* Append one verdict (latest per claim wins on read).
+	* @param verdict - claimId, status, optional note.
+	* @param at - ISO-8601 write time.
+	*/
+	async recordVerdict(verdict, at) {
+		await this.enqueue(async () => {
+			await this.ensureLayout();
+			const line = {
+				...verdict,
+				at
+			};
+			await appendFile(this.verdictsFile, `${JSON.stringify(line)}\n`, "utf8");
+		});
+	}
+	/**
+	* Read the evidence index.
+	* @returns every registration in append order.
+	*/
+	async listEvidence() {
+		return readJournal(this.indexFile);
+	}
+	/**
+	* Read one evidence registration.
+	* @param id - the ledger id.
+	* @returns the record, or undefined when unknown.
+	*/
+	async getEvidence(id) {
+		return (await this.listEvidence()).find((line) => line.id === id);
+	}
+	/**
+	* Read every claim registration.
+	* @returns every claim in append order.
+	*/
+	async listClaims() {
+		return readJournal(this.claimsFile);
+	}
+	/**
+	* Read one claim registration.
+	* @param id - the claim id.
+	* @returns the claim line, or undefined when unknown.
+	*/
+	async getClaim(id) {
+		return (await this.listClaims()).find((line) => line.id === id);
+	}
+	/**
+	* Fold the verdict journal to the latest verdict per claim.
+	* @returns claimId → latest stored verdict.
+	*/
+	async latestVerdicts() {
+		const journal = await readJournal(this.verdictsFile);
+		const latest = /* @__PURE__ */ new Map();
+		for (const line of journal) latest.set(line.claimId, line);
+		return latest;
+	}
+	/**
+	* Read one snapshot and recompute its hash — the tamper-detection path.
+	* @param id - the ledger id.
+	* @returns content plus integrity (`ok` | `tampered` | `missing`), or
+	*   undefined when the id is unknown.
+	*/
+	async readContent(id) {
+		const record = await this.getEvidence(id);
+		if (record === void 0) return void 0;
+		let content;
+		try {
+			content = await readFile(path.join(this.objectsDir, record.hash), "utf8");
+		} catch (error) {
+			if (error.code === "ENOENT") return {
+				content: "",
+				integrity: "missing"
+			};
+			throw new LedgerError("IO", `cannot read object ${record.hash}: ${error.message}`);
+		}
+		return {
+			content,
+			integrity: sha256Of(content) === record.hash ? "ok" : "tampered"
+		};
+	}
+};
+//#endregion
+//#region src/assemble.ts
+/**
+* Report assembly and sealing — pure functions. The provider owns the ledger
+* and the filesystem; this module owns request validation, the `report.md`
+* rendering, the `manifest.json` construction, and the seal hash.
+*
+* Sealing: `report.md` is rendered deterministically from the validated
+* request plus the verdicts; `manifest.json` carries the report hash, every
+* evidence hash, and the verdicts; the seal hash is the SHA-256 of the exact
+* manifest bytes. Recomputing the hashes from the sealed directory always
+* reproduces the seal.
+*
+* @module dsh-research-report/assemble
+*/
+/** The manifest schema tag written into every manifest.json. */
+const MANIFEST_SCHEMA = "dsh-research-report/v1";
+/** Body marker appended after a paragraph per UNVERIFIED claim it cites. */
+const UNVERIFIED_MARK = "[未核实]";
+/** Body marker appended after a paragraph per CONTRADICTED claim it cites. */
+const CONTRADICTED_MARK = "[与证据矛盾]";
+/** A loud assemble-time request validation failure. */
+var RequestValidationError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "RequestValidationError";
+	}
+};
+/**
+* Slug one topic for the report directory name: unicode letters and digits
+* are kept, everything else folds to `-`; empty slugs fall back to `report`.
+* @param topic - the report topic.
+* @returns a filesystem-safe slug of at most 48 characters.
+*/
+function slugify(topic) {
+	const slug = topic.trim().toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-+|-+$/gu, "").slice(0, 48);
+	return slug === "" ? "report" : slug;
+}
+/**
+* Format one timestamp as the version directory id `YYYYMMDD-HHmmss` (UTC).
+* @param at - the time to format.
+* @returns the directory id.
+*/
+function versionIdOf(at) {
+	const pad = (value) => String(value).padStart(2, "0");
+	return [`${at.getUTCFullYear()}${pad(at.getUTCMonth() + 1)}${pad(at.getUTCDate())}`, `${pad(at.getUTCHours())}${pad(at.getUTCMinutes())}${pad(at.getUTCSeconds())}`].join("-");
+}
+/**
+* The config fingerprint recorded in every report: a short hash of the
+* resolved runtime knobs, so two reports sealed under different policies are
+* distinguishable at a glance.
+* @param knobs - the policy values that shape assembly output.
+* @returns 16 hex characters of the knobs' SHA-256.
+*/
+function configFingerprint(knobs) {
+	return sha256Of(JSON.stringify({
+		maxEvidenceBytes: knobs.maxEvidenceBytes,
+		maxEvidencePerReport: knobs.maxEvidencePerReport
+	})).slice(0, 16);
+}
+/**
+* Validate one assemble request; every violation throws (a loud rejection —
+* the caller must fix the request, nothing is silently skipped).
+* @param request - the frozen assemble request.
+* @param limits - the resolved caps.
+*/
+function validateAssembleRequest(request, limits) {
+	if (request.title.trim() === "") throw new RequestValidationError("title must be non-empty");
+	if (request.topic.trim() === "") throw new RequestValidationError("topic must be non-empty");
+	if (request.sections.length === 0) throw new RequestValidationError("sections must contain at least one section");
+	for (const [index, section] of request.sections.entries()) if (section.heading.trim() === "") throw new RequestValidationError(`sections[${index}].heading must be non-empty`);
+	if (request.evidence.length > limits.maxEvidencePerReport) throw new RequestValidationError(`evidence has ${request.evidence.length} items, above the configured maxEvidencePerReport ${limits.maxEvidencePerReport}`);
+	const evidenceIds = /* @__PURE__ */ new Set();
+	for (const item of request.evidence) {
+		if (item.id.trim() === "") throw new RequestValidationError("evidence id must be non-empty");
+		if (evidenceIds.has(item.id)) throw new RequestValidationError(`duplicate evidence id "${item.id}"`);
+		evidenceIds.add(item.id);
+		const bytes = Buffer.byteLength(item.content, "utf8");
+		if (bytes > limits.maxEvidenceBytes) throw new RequestValidationError(`evidence "${item.id}" is ${bytes} bytes, above the configured maxEvidenceBytes ${limits.maxEvidenceBytes}`);
+		if (Number.isNaN(Date.parse(item.capturedAt))) throw new RequestValidationError(`evidence "${item.id}" has an unparseable capturedAt ${JSON.stringify(item.capturedAt)}`);
+	}
+	const claimIds = /* @__PURE__ */ new Set();
+	for (const claim of request.claims) {
+		if (claim.id.trim() === "") throw new RequestValidationError("claim id must be non-empty");
+		if (claimIds.has(claim.id)) throw new RequestValidationError(`duplicate claim id "${claim.id}"`);
+		claimIds.add(claim.id);
+		for (const evidenceId of claim.evidenceIds) if (!evidenceIds.has(evidenceId)) throw new RequestValidationError(`claim "${claim.id}" binds unknown evidence id "${evidenceId}"`);
+	}
+	for (const [sectionIndex, section] of request.sections.entries()) for (const [paragraphIndex, paragraph] of section.paragraphs.entries()) for (const claimId of paragraph.claimIds ?? []) if (!claimIds.has(claimId)) throw new RequestValidationError(`sections[${sectionIndex}].paragraphs[${paragraphIndex}] cites unregistered claim id "${claimId}"`);
+}
+/** The status mark used in the appendix table. */
+function statusMark(status) {
+	switch (status) {
+		case "verified": return "✅ verified";
+		case "unverified": return "⚠️ unverified";
+		case "contradicted": return "❌ contradicted";
+	}
+}
+/** Escape a table cell. */
+function cell(text) {
+	return text.replace(/\|/gu, "\\|").replace(/\r?\n/gu, " ");
+}
+/**
+* Render `report.md`. Unverified/contradicted claims keep a visible body
+* marker after every paragraph that cites them — nothing is silently passed.
+* @param plan - the validated request plus verdicts and evidence records.
+* @returns the report markdown.
+*/
+function renderReportMarkdown(plan) {
+	const verdictByClaim = new Map(plan.verdicts.map((verdict) => [verdict.claimId, verdict]));
+	const counts = {
+		verified: 0,
+		unverified: 0,
+		contradicted: 0
+	};
+	for (const verdict of plan.verdicts) counts[verdict.status] += 1;
+	const lines = [
+		`# ${plan.request.title}`,
+		"",
+		`- Topic: ${plan.request.topic}`,
+		`- Generated: ${plan.generatedAt} (UTC)`,
+		`- Claims: ${counts.verified} verified / ${counts.unverified} unverified / ${counts.contradicted} contradicted`,
+		`- Generator: dsh-research-report ${plan.pluginVersion}`,
+		""
+	];
+	for (const section of plan.request.sections) {
+		lines.push(`## ${section.heading}`, "");
+		for (const paragraph of section.paragraphs) {
+			const marks = [];
+			for (const claimId of paragraph.claimIds ?? []) {
+				const verdict = verdictByClaim.get(claimId);
+				if (verdict?.status === "unverified") marks.push(UNVERIFIED_MARK);
+				if (verdict?.status === "contradicted") marks.push(CONTRADICTED_MARK);
+			}
+			lines.push(marks.length === 0 ? paragraph.text : `${paragraph.text} ${marks.join(" ")}`, "");
+		}
+	}
+	lines.push("## Appendix A: Claim verification", "");
+	if (plan.verdicts.length === 0) lines.push("No claims were registered.", "");
+	else {
+		lines.push("| Claim | Verdict | Evidence | Note |", "|---|---|---|---|");
+		const claimById = new Map(plan.request.claims.map((claim) => [claim.id, claim]));
+		for (const verdict of plan.verdicts) {
+			const claim = claimById.get(verdict.claimId);
+			lines.push(`| ${cell(verdict.claimId)} | ${statusMark(verdict.status)} | ${cell((claim?.evidenceIds ?? []).join(", "))} | ${cell(verdict.note ?? "")} |`);
+		}
+		lines.push("");
+	}
+	lines.push("## Appendix B: Evidence list", "");
+	if (plan.evidence.length === 0) lines.push("No evidence was bound.", "");
+	else {
+		lines.push("| Id | Title | Origin | SHA-256 | Captured |", "|---|---|---|---|---|");
+		for (const record of plan.evidence) lines.push(`| ${cell(record.id)} | ${cell(record.title)} | ${cell(record.origin)} | \`${record.hash}\` | ${record.capturedAt} |`);
+		lines.push("");
+	}
+	lines.push("## Appendix C: Seal", "", `- Manifest: \`manifest.json\` (schema ${MANIFEST_SCHEMA})`, `- Config fingerprint: \`${plan.fingerprint}\``, `- Generated: ${plan.generatedAt} (UTC)`, "");
+	return `${lines.join("\n").trimEnd()}\n`;
+}
+/**
+* Build the manifest document for one sealed report. Key order is fixed by
+* construction so the serialized bytes (and therefore the seal hash) are
+* deterministic for the same inputs.
+* @param plan - the validated request plus verdicts and evidence records.
+* @param reportSha256 - the SHA-256 of the rendered report.md bytes.
+* @returns the manifest document.
+*/
+function buildManifest(plan, reportSha256) {
+	return {
+		schema: MANIFEST_SCHEMA,
+		title: plan.request.title,
+		topic: plan.request.topic,
+		generatedAt: plan.generatedAt,
+		generator: `dsh-research-report ${plan.pluginVersion}`,
+		reportFile: "report.md",
+		reportSha256,
+		configFingerprint: plan.fingerprint,
+		evidence: plan.evidence.map((record) => ({
+			id: record.id,
+			sha256: record.hash,
+			origin: record.origin,
+			title: record.title,
+			capturedAt: record.capturedAt,
+			bytes: record.bytes
+		})),
+		claims: plan.request.claims.map((claim) => ({
+			id: claim.id,
+			text: claim.text,
+			evidenceIds: claim.evidenceIds
+		})),
+		verdicts: plan.verdicts
+	};
+}
+/**
+* Serialize one manifest to its exact durable bytes. The seal hash is the
+* SHA-256 of this text.
+* @param manifest - the manifest document.
+* @returns the canonical manifest.json content.
+*/
+function serializeManifest(manifest) {
+	return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+//#endregion
+//#region src/gather.ts
+/**
+* Evidence capture: URL snapshots via the `ctx.web` seam, workspace file
+* snapshots via `node:fs` — never a direct `fetch` (provider selection and the
+* WebError taxonomy stay with the seam), never a path outside the workspace.
+* @module dsh-research-report/gather
+*/
+/** A loud capture failure with a machine-routable code (also in the message). */
+var CaptureError = class extends Error {
+	/** The machine-routable failure code. */
+	code;
+	constructor(code, message) {
+		super(`[${code}] ${message}`);
+		this.name = "CaptureError";
+		this.code = code;
+	}
+};
+/** Whether the origin is an HTTP(S) URL (vs a workspace path). */
+function isUrlOrigin(origin) {
+	return /^https?:\/\//iu.test(origin);
+}
+/**
+* Resolve a workspace-relative origin to an absolute path inside the
+* workspace. Both sides are resolved before comparison (Windows backslash
+* trap) and the prefix check is segment-aware.
+* @param workspaceRoot - absolute workspace root.
+* @param origin - the workspace-relative (or absolute) origin.
+* @returns the absolute in-workspace path.
+*/
+function resolveWorkspacePath(workspaceRoot, origin) {
+	const root = path.resolve(workspaceRoot);
+	const resolved = path.resolve(root, origin);
+	if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) throw new CaptureError("ORIGIN_OUTSIDE_WORKSPACE", `origin ${JSON.stringify(origin)} resolves outside the workspace`);
+	return resolved;
+}
+/** Relativize an absolute in-workspace path for display/durable records. */
+function toWorkspaceRelative(workspaceRoot, absolute) {
+	return path.relative(path.resolve(workspaceRoot), path.resolve(absolute)).split(path.sep).join("/");
+}
+/**
+* Capture one URL snapshot through the web seam.
+* @param deps - web seam, deadline, workspace root.
+* @param url - the URL to fetch.
+* @param signal - caller cancellation.
+* @returns the snapshot (throws {@link CaptureError} on every failure).
+*/
+async function captureFromWeb(deps, url, signal) {
+	if (deps.web === void 0) throw new CaptureError("WEB_UNAVAILABLE", "the web capability (ctx.web) is not mounted in this composition; pass `content` explicitly or load @deepseek-ai/dsh-web with a fetch provider");
+	const timeout = AbortSignal.timeout(deps.fetchTimeoutMs);
+	const linked = signal === void 0 ? timeout : AbortSignal.any([signal, timeout]);
+	let result;
+	try {
+		result = await deps.web.fetch({ url }, linked);
+	} catch (error) {
+		if (timeout.aborted && (signal === void 0 || !signal.aborted)) throw new CaptureError("FETCH_TIMEOUT", `fetch of ${url} exceeded the configured fetchTimeoutMs ${deps.fetchTimeoutMs}`);
+		throw new CaptureError("FETCH_FAILED", `fetch of ${url} failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (result.statusCode < 200 || result.statusCode >= 300) throw new CaptureError("FETCH_STATUS", `fetch of ${url} returned HTTP ${result.statusCode}; no snapshot captured`);
+	return {
+		content: result.body.content,
+		origin: result.url
+	};
+}
+/**
+* Capture one workspace file snapshot.
+* @param deps - workspace root (the web fields are unused here).
+* @param origin - the workspace-relative path.
+* @returns the snapshot (throws {@link CaptureError} when unreadable).
+*/
+async function captureFromFile(deps, origin) {
+	const absolute = resolveWorkspacePath(deps.workspaceRoot, origin);
+	let content;
+	try {
+		content = await readFile(absolute, "utf8");
+	} catch (error) {
+		throw new CaptureError("ORIGIN_UNREADABLE", `cannot read ${JSON.stringify(origin)}: ${error.message}`);
+	}
+	return {
+		content,
+		origin: toWorkspaceRelative(deps.workspaceRoot, absolute)
+	};
+}
+/**
+* Capture one snapshot from any supported origin.
+* @param deps - web seam, deadline, workspace root.
+* @param origin - URL or workspace path.
+* @param signal - caller cancellation.
+* @returns the snapshot.
+*/
+async function captureSnapshot(deps, origin, signal) {
+	return isUrlOrigin(origin) ? captureFromWeb(deps, origin, signal) : captureFromFile(deps, origin);
+}
+/** Search depth → how many sources are fetched for snapshot capture. */
+const GATHER_DEPTH_RESULTS = {
+	quick: 3,
+	standard: 5,
+	deep: 8
+};
+/**
+* Run one search over the topic and capture snapshots for the top sources.
+* Captured snapshots are registered through `register`; uncaptured sources
+* land in the gap list with their reason — gathering never fabricates
+* evidence and never auto-assembles.
+* @param deps - web seam, deadline, workspace root.
+* @param topic - the research topic.
+* @param depth - quick | standard | deep.
+* @param signal - caller cancellation.
+* @param register - ledger registration callback for captured snapshots.
+* @returns candidates plus gaps.
+*/
+async function gatherCandidates(deps, topic, depth, signal, register) {
+	if (deps.web === void 0) throw new CaptureError("WEB_UNAVAILABLE", "the web capability (ctx.web) is not mounted in this composition; gather needs @deepseek-ai/dsh-web with a search provider");
+	const maxResults = GATHER_DEPTH_RESULTS[depth];
+	let search;
+	try {
+		search = await deps.web.search({
+			query: topic,
+			maxResults
+		}, signal);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new CaptureError("FETCH_FAILED", `search for ${JSON.stringify(topic)} failed: ${message}`);
+	}
+	const candidates = [];
+	const gaps = [];
+	for (const source of search.sources) try {
+		const snapshot = await captureFromWeb(deps, source.url, signal);
+		const record = await register({
+			title: source.title ?? source.url,
+			origin: snapshot.origin,
+			content: snapshot.content
+		});
+		candidates.push({
+			url: source.url,
+			...source.title === void 0 ? {} : { title: source.title },
+			...source.snippet === void 0 ? {} : { snippet: source.snippet },
+			status: "captured",
+			evidenceId: record.id
+		});
+	} catch (error) {
+		const reason = error instanceof CaptureError ? `${error.code}: ${error.message}` : String(error);
+		candidates.push({
+			url: source.url,
+			...source.title === void 0 ? {} : { title: source.title },
+			...source.snippet === void 0 ? {} : { snippet: source.snippet },
+			status: "uncaptured",
+			reason
+		});
+		gaps.push(`no snapshot for ${source.url} (${reason}) — add it with evidence_add once content is available`);
+	}
+	if (search.truncated) gaps.push(`search returned more than ${maxResults} sources; only the top ${maxResults} were considered`);
+	if (candidates.every((candidate) => candidate.status === "uncaptured")) gaps.push("no evidence was captured; the report cannot be assembled until at least one snapshot lands in the ledger");
+	return {
+		topic,
+		candidates,
+		gaps
+	};
+}
+//#endregion
+//#region src/service.ts
+/**
+* Service Definition of the verifiable research-report seam (`ctx.researchReport`).
+*
+* Three roles in one package (they evolve together): this file owns the
+* Definition — the frozen `assemble` contract, the evidence/claim vocabulary,
+* and the typed session events; `provider-local.ts` owns the local Provider
+* (filesystem ledger + byte-level verification); `tools/` owns the model-facing
+* Consumers.
+*
+* The `ReportSectionInput` / `EvidenceInput` / `AssembleReportRequest` /
+* `AssembleReportResult` block below is BYTE-FROZEN: sibling plugins
+* (dsh-industry-research) consume `ctx.researchReport.assemble` against this
+* exact text. `scripts/verify-frozen-contract.mjs` gates drift.
+*
+* @module dsh-research-report/service
+*/
+/**
+* The verifiable research-report service (`ctx.researchReport`).
+*
+* `assemble` is the frozen cross-plugin surface: validate the request, verify
+* every claim against the ledger's immutable snapshots, render `report.md`
+* (unverified/contradicted claims stay visibly marked in the body), write
+* `manifest.json`, and seal the directory with the manifest's SHA-256.
+*/
+var ResearchReportService = class extends Service {
+	constructor(ctx) {
+		super(ctx, "researchReport");
+	}
+};
+//#endregion
+//#region src/verify.ts
+/** Number literal: optional sign, grouped digits, decimals, trailing %. */
+const NUMBER_PATTERN = /-?\d[\d,]*(?:\.\d+)?%?/gu;
+/** Quoted spans: ASCII double quotes, CJK corner brackets, full-width quotes. */
+const QUOTE_PATTERNS = [
+	/"([^"\n]{4,200})"/gu,
+	/「([^」\n]{2,200})」/gu,
+	/“([^“”\n]{4,200})”/gu
+];
+/** The tail run of label characters (letters / CJK) ending a context window. */
+const LABEL_PATTERN = /[\p{L}\p{N}_（）()%$-]{2,24}$/u;
+/**
+* Extract the trailing context label of a number citation: up to 24 characters
+* before the number, trimmed to its trailing label run. Too-short labels are
+* dropped (a weak label would false-positive the contradiction check).
+* @param text - the full claim text.
+* @param index - offset of the number in the text.
+* @returns the label, or undefined when there is no usable one.
+*/
+function contextLabelOf(text, index) {
+	const window = text.slice(Math.max(0, index - 24), index).trimEnd();
+	const label = LABEL_PATTERN.exec(window)?.[0].trim();
+	if (label === void 0 || label.length < 2) return void 0;
+	return label;
+}
+/**
+* Extract every checkable citation from one claim text: number literals (with
+* their left-context labels) and quoted spans.
+* @param claimText - the claim to analyze.
+* @returns citations in first-seen order (duplicates kept once).
+*/
+function extractCitations(claimText) {
+	const citations = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const match of claimText.matchAll(NUMBER_PATTERN)) {
+		const text = match[0];
+		if (seen.has(`number:${text}`)) continue;
+		seen.add(`number:${text}`);
+		const context = contextLabelOf(claimText, match.index);
+		citations.push(context === void 0 ? {
+			kind: "number",
+			text
+		} : {
+			kind: "number",
+			text,
+			context
+		});
+	}
+	for (const pattern of QUOTE_PATTERNS) for (const match of claimText.matchAll(pattern)) {
+		const text = match[1];
+		if (seen.has(`quote:${text}`)) continue;
+		seen.add(`quote:${text}`);
+		citations.push({
+			kind: "quote",
+			text
+		});
+	}
+	return citations;
+}
+/** The number token scan window after a context label (bytes of text). */
+const CONTEXT_SCAN_WINDOW = 24;
+/** Normalize a number literal for comparison (drop grouping commas and %). */
+function normalizeNumber(text) {
+	return text.replace(/[,%]/gu, "");
+}
+/** The first number literal found in `text` from `from` (fresh regex — no shared lastIndex). */
+function numberAfter(text, from) {
+	const window = text.slice(from, from + CONTEXT_SCAN_WINDOW);
+	return /-?\d[\d,]*(?:\.\d+)?%?/u.exec(window)?.[0];
+}
+/** Cap how many problem citations one note enumerates. */
+const NOTE_LIST_CAP = 5;
+/**
+* Run the byte-level check of one claim against its bound evidence snapshots.
+* @param claimText - the claim text.
+* @param evidenceContents - the verbatim snapshot contents of the bound evidence.
+* @returns the outcome (never throws).
+*/
+function verifyClaimText(claimText, evidenceContents) {
+	if (evidenceContents.length === 0) return {
+		status: "unverified",
+		note: "claim binds no evidence snapshot",
+		missing: [],
+		contradictions: []
+	};
+	const haystack = evidenceContents.join("\n");
+	const citations = extractCitations(claimText);
+	if (citations.length === 0) return {
+		status: "unverified",
+		note: "claim carries no checkable citation (number or quoted span); byte-level verification needs a literal to locate",
+		missing: [],
+		contradictions: []
+	};
+	const missing = [];
+	const contradictions = [];
+	for (const citation of citations) {
+		if (citation.kind === "quote") {
+			if (!haystack.includes(citation.text)) missing.push(`"${citation.text}"`);
+			continue;
+		}
+		if (haystack.includes(citation.text)) continue;
+		if (citation.context !== void 0) {
+			let searchFrom = 0;
+			let different;
+			for (;;) {
+				const at = haystack.indexOf(citation.context, searchFrom);
+				if (at === -1) break;
+				const found = numberAfter(haystack, at + citation.context.length);
+				if (found !== void 0 && normalizeNumber(found) !== normalizeNumber(citation.text)) {
+					different = found;
+					break;
+				}
+				searchFrom = at + citation.context.length;
+			}
+			if (different !== void 0) {
+				contradictions.push(`${citation.context}: claim says ${citation.text}, snapshot says ${different}`);
+				continue;
+			}
+		}
+		missing.push(citation.text);
+	}
+	if (contradictions.length > 0) return {
+		status: "contradicted",
+		note: `contradicts the snapshot: ${contradictions.slice(0, NOTE_LIST_CAP).join("; ")}`,
+		missing,
+		contradictions
+	};
+	if (missing.length > 0) return {
+		status: "unverified",
+		note: `citation(s) not found in bound evidence: ${missing.slice(0, NOTE_LIST_CAP).join(", ")}`,
+		missing,
+		contradictions
+	};
+	return {
+		status: "verified",
+		note: `${citations.length} citation(s) located verbatim in the bound snapshot(s)`,
+		missing,
+		contradictions
+	};
+}
+/**
+* Map one bridge result set onto the three-state verdict vocabulary.
+* `mismatch` maps to `contradicted`; `not-found`/`unverifiable` map to
+* `unverified`.
+* @param result - the dataQuality outcome.
+* @returns the mapped status plus a human-readable note.
+*/
+function mapBridgeResults(result) {
+	const mismatch = result.results.filter((entry) => entry.status === "mismatch");
+	if (mismatch.length > 0) return {
+		status: "contradicted",
+		note: `dataset cross-check mismatch: ${mismatch.slice(0, NOTE_LIST_CAP).map((entry) => `${entry.id}: dataset has ${String(entry.actual ?? "?")}${entry.note === void 0 ? "" : ` (${entry.note})`}`).join("; ")}`
+	};
+	const unresolved = result.results.filter((entry) => entry.status === "not-found" || entry.status === "unverifiable");
+	if (unresolved.length > 0) return {
+		status: "unverified",
+		note: `dataset cross-check unresolved: ${unresolved.slice(0, NOTE_LIST_CAP).map((entry) => `${entry.id}: ${entry.status}${entry.note === void 0 ? "" : ` (${entry.note})`}`).join("; ")}`
+	};
+	return {
+		status: "verified",
+		note: `${result.results.length} dataset citation(s) verified via ctx.dataQuality`
+	};
+}
+/**
+* Combine the byte-level and bridge outcomes: `contradicted` wins, then
+* `unverified`, then `verified`.
+* @param byte - the byte-level outcome.
+* @param bridge - the bridge outcome, when the numeric bridge ran.
+* @returns the combined status and a merged note.
+*/
+function combineOutcomes(byte, bridge) {
+	if (bridge === void 0) return {
+		status: byte.status,
+		note: byte.note
+	};
+	const rank = {
+		verified: 0,
+		unverified: 1,
+		contradicted: 2
+	};
+	return {
+		status: rank[bridge.status] > rank[byte.status] ? bridge.status : byte.status,
+		note: `${byte.note} | ${bridge.note}`
+	};
+}
+//#endregion
+//#region src/version.ts
+/**
+* Single source of truth for the plugin version (stamped by scripts/release.mjs).
+* @module dsh-research-report/version
+*/
+/** The published package version. */
+const VERSION = "0.1.0";
+//#endregion
+//#region src/provider-local.ts
+/**
+* The local Provider of the research-report seam: assembles the filesystem
+* evidence ledger, the byte-level verifier, the optional numeric bridge, and
+* the sealing renderer into the `ctx.researchReport` service implementation.
+* @module dsh-research-report/provider-local
+*/
+/** A loud provider failure with a machine-routable code. */
+var ResearchReportError = class extends Error {
+	/** The machine-routable failure code. */
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "ResearchReportError";
+		this.code = code;
+	}
+};
+/**
+* rc.6's persistence layer refuses a session log carrying an event type it
+* does not know, and rc.6 offers no plugin event-registration surface — so the
+* research-report/* events are appended only when the host build already knows
+* them. The ledger journals are always the durable source of truth; these
+* events are the in-log audit mirror and activate automatically once the host
+* learns the vocabulary.
+* @param session - the owning session, when known.
+* @param type - the event type.
+* @param append - the typed append thunk.
+*/
+function appendAudit(session, type, append) {
+	if (session === void 0) return;
+	if (!KNOWN_SESSION_EVENT_TYPES.has(type)) return;
+	append();
+}
+/**
+* The local `ctx.researchReport` implementation. Everything durable lives in
+* the filesystem ledger; the service adds policy (caps), verification, and
+* sealing on top.
+*/
+var LocalResearchReportService = class extends ResearchReportService {
+	/** The content-addressed ledger. */
+	ledger;
+	/** The resolved plugin config. */
+	config;
+	/** Absolute workspace root for local capture and path display. */
+	workspaceRoot;
+	/**
+	* @param ctx - the plugin context.
+	* @param config - the resolved plugin config.
+	* @param workspaceRoot - absolute workspace root (the harness cwd).
+	*/
+	constructor(ctx, config, workspaceRoot) {
+		super(ctx);
+		this.config = config;
+		this.workspaceRoot = workspaceRoot;
+		this.ledger = new EvidenceLedger(config.ledgerRoot);
+	}
+	/** The web seam, resolved at call time (HMR-safe; may be absent). */
+	get web() {
+		return this.ctx.get("web");
+	}
+	/** The optional numeric bridge, resolved at call time (never injected). */
+	get dataQuality() {
+		return this.ctx.get("dataQuality");
+	}
+	/** Capture dependencies for the gather/capture paths. */
+	get captureDeps() {
+		return {
+			web: this.web,
+			fetchTimeoutMs: this.config.fetchTimeoutMs,
+			workspaceRoot: this.workspaceRoot
+		};
+	}
+	/**
+	* Register one evidence snapshot. Over-size content is refused loudly;
+	* same-content registrations dedupe.
+	* @param input - the snapshot and its provenance.
+	* @param session - the owning session (audit event), when known.
+	* @returns the durable record and whether this call created it.
+	*/
+	async addEvidence(input, session) {
+		const bytes = Buffer.byteLength(input.content, "utf8");
+		if (bytes > this.config.maxEvidenceBytes) throw new ResearchReportError("EVIDENCE_TOO_LARGE", `evidence content is ${bytes} bytes, above the configured maxEvidenceBytes ${this.config.maxEvidenceBytes}`);
+		const capturedAt = input.capturedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+		let outcome;
+		try {
+			outcome = await this.ledger.putEvidence({
+				...input.id === void 0 ? {} : { id: input.id },
+				title: input.title,
+				origin: input.origin,
+				content: input.content,
+				capturedAt
+			});
+		} catch (error) {
+			if (error instanceof LedgerError) throw new ResearchReportError("LEDGER", error.message);
+			throw error;
+		}
+		appendAudit(session, "research-report/evidence", () => {
+			session?.append("research-report/evidence", {
+				id: outcome.record.id,
+				hash: outcome.record.hash,
+				origin: outcome.record.origin,
+				title: outcome.record.title,
+				capturedAt: outcome.record.capturedAt,
+				bytes: outcome.record.bytes,
+				deduplicated: !outcome.created
+			});
+		});
+		return {
+			record: outcome.record,
+			deduplicated: !outcome.created
+		};
+	}
+	/**
+	* Capture one origin (URL via ctx.web, workspace path via fs) and register
+	* it. Provider-internal helper for the tools layer.
+	* @param origin - URL or workspace path.
+	* @param title - display title (defaults to the origin).
+	* @param signal - caller cancellation.
+	* @param session - the owning session (audit event), when known.
+	* @returns the durable record and whether this call created it.
+	*/
+	async captureAndRegister(origin, title, signal, session) {
+		const snapshot = await captureSnapshot(this.captureDeps, origin, signal);
+		return this.addEvidence({
+			title: title ?? snapshot.origin,
+			origin: snapshot.origin,
+			content: snapshot.content
+		}, session);
+	}
+	/**
+	* Run one topic gather: search + snapshot capture + registration. Never
+	* auto-assembles; uncaptured sources land in the gap list.
+	* @param topic - the research topic.
+	* @param depth - quick | standard | deep.
+	* @param signal - caller cancellation.
+	* @param session - the owning session (audit events), when known.
+	* @returns candidates plus gaps.
+	*/
+	async gather(topic, depth, signal, session) {
+		return gatherCandidates(this.captureDeps, topic, depth, signal, async (input) => {
+			const { record } = await this.addEvidence(input, session);
+			return record;
+		});
+	}
+	/**
+	* Verify one registered claim against its bound snapshots: integrity first
+	* (tampered/missing ⇒ contradicted), then the byte-level check, then the
+	* optional numeric bridge. The verdict is written back to the ledger.
+	* @param claimId - the claim to verify.
+	* @param session - the owning session (audit event), when known.
+	* @returns the fresh verdict.
+	*/
+	async verifyClaim(claimId, session) {
+		const claim = await this.ledger.getClaim(claimId);
+		if (claim === void 0) throw new ResearchReportError("CLAIM_UNKNOWN", `unknown claim id "${claimId}"`);
+		const verdict = await this.verifyRegistration(claim);
+		await this.ledger.recordVerdict({
+			claimId,
+			status: verdict.status,
+			...verdict.note === void 0 ? {} : { note: verdict.note }
+		}, (/* @__PURE__ */ new Date()).toISOString());
+		appendAudit(session, "research-report/verify", () => {
+			session?.append("research-report/verify", {
+				claimId,
+				status: verdict.status,
+				...verdict.note === void 0 ? {} : { note: verdict.note },
+				evidenceIds: claim.evidenceIds
+			});
+		});
+		return verdict;
+	}
+	/** Compute the verdict for one claim registration (no writeback). */
+	async verifyRegistration(claim) {
+		const contents = [];
+		const broken = [];
+		for (const evidenceId of claim.evidenceIds) {
+			const read = await this.ledger.readContent(evidenceId);
+			if (read === void 0) {
+				broken.push(`${evidenceId} (not in the ledger)`);
+				continue;
+			}
+			if (read.integrity !== "ok") {
+				broken.push(`${evidenceId} (${read.integrity}: object bytes no longer match the indexed hash)`);
+				continue;
+			}
+			contents.push(read.content);
+		}
+		let byte;
+		if (broken.length > 0) byte = {
+			status: "contradicted",
+			note: `bound evidence failed the integrity check: ${broken.join("; ")}`,
+			missing: [],
+			contradictions: broken
+		};
+		else byte = verifyClaimText(claim.text, contents);
+		let bridge;
+		if (claim.dataset !== void 0 && claim.citations !== void 0 && claim.citations.length > 0) {
+			const dataQuality = this.dataQuality;
+			if (dataQuality === void 0) bridge = {
+				status: "unverified",
+				note: "numeric dataset citations not cross-checked: ctx.dataQuality is not mounted (dsh-data-quality absent); byte-level check only"
+			};
+			else try {
+				bridge = mapBridgeResults(await dataQuality.verifyCitations({
+					dataset: claim.dataset,
+					citations: claim.citations
+				}));
+			} catch (error) {
+				bridge = {
+					status: "unverified",
+					note: `numeric dataset bridge failed: ${error instanceof Error ? error.message : String(error)}`
+				};
+			}
+		}
+		const combined = combineOutcomes(byte, bridge);
+		return {
+			claimId: claim.id,
+			status: combined.status,
+			note: combined.note
+		};
+	}
+	/**
+	* Assemble and seal one report: validate (loud), register evidence and
+	* claims (idempotent; conflicts throw), verify every claim, render
+	* `report.md` with visible markers for unverified/contradicted claims, write
+	* `manifest.json`, and seal the versioned directory with the manifest hash.
+	* @param request - the frozen assemble request.
+	* @param context - optional assemble context (owning session for events).
+	* @returns the sealed directory, the seal hash, and the per-claim verdicts.
+	*/
+	async assemble(request, context) {
+		validateAssembleRequest(request, this.config);
+		const records = [];
+		for (const item of request.evidence) {
+			const existing = await this.ledger.getEvidence(item.id);
+			if (existing === void 0) {
+				const added = await this.addEvidence({
+					id: item.id,
+					title: item.title,
+					origin: item.origin,
+					content: item.content,
+					capturedAt: item.capturedAt
+				}, context?.session);
+				records.push(added.record);
+				continue;
+			}
+			if (sha256Of(item.content) !== existing.hash) {
+				const stored = await this.ledger.readContent(item.id);
+				if (stored !== void 0 && stored.integrity === "ok") throw new ResearchReportError("LEDGER", `evidence id "${item.id}" is already registered with different content; snapshots are immutable — choose a new id`);
+			}
+			records.push(existing);
+		}
+		await this.ledger.registerClaims(request.claims.map((claim) => {
+			const registration = claim;
+			return {
+				id: registration.id,
+				text: registration.text,
+				evidenceIds: registration.evidenceIds,
+				...registration.dataset === void 0 ? {} : { dataset: registration.dataset },
+				...registration.citations === void 0 ? {} : { citations: registration.citations }
+			};
+		}), (/* @__PURE__ */ new Date()).toISOString());
+		const verdicts = [];
+		for (const claim of request.claims) verdicts.push(await this.verifyClaim(claim.id, context?.session));
+		const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+		const plan = {
+			request,
+			verdicts,
+			evidence: records,
+			generatedAt,
+			fingerprint: configFingerprint(this.config),
+			pluginVersion: VERSION
+		};
+		const reportText = renderReportMarkdown(plan);
+		const manifestText = serializeManifest(buildManifest(plan, sha256Of(reportText)));
+		const sealHash = sha256Of(manifestText);
+		const reportDir = await this.freshReportDir(request.topic, new Date(generatedAt));
+		await writeFile(path.join(reportDir, "report.md"), reportText, "utf8");
+		await writeFile(path.join(reportDir, "manifest.json"), manifestText, "utf8");
+		appendAudit(context?.session, "research-report/seal", () => {
+			context?.session?.append("research-report/seal", {
+				reportDir,
+				sealHash,
+				topic: request.topic,
+				title: request.title,
+				verdicts
+			});
+		});
+		return {
+			reportDir,
+			sealHash,
+			verdicts
+		};
+	}
+	/** Allocate the next versioned report directory for one topic (UTC clock). */
+	async freshReportDir(topic, at) {
+		const base = path.join(this.config.reportRoot, slugify(topic));
+		await mkdir(base, { recursive: true });
+		const stamp = versionIdOf(at);
+		for (let suffix = 0;; suffix++) {
+			const candidate = path.join(base, suffix === 0 ? stamp : `${stamp}-${suffix + 1}`);
+			try {
+				await mkdir(candidate);
+				return candidate;
+			} catch (error) {
+				if (error.code !== "EEXIST") throw error;
+			}
+		}
+	}
+	/**
+	* Read one evidence item (re-hashed on read).
+	* @param evidenceId - the ledger id.
+	* @returns the view, or undefined when unknown.
+	*/
+	async getEvidence(evidenceId) {
+		const record = await this.ledger.getEvidence(evidenceId);
+		if (record === void 0) return void 0;
+		const read = await this.ledger.readContent(evidenceId);
+		const integrity = read === void 0 ? "missing" : read.integrity;
+		return {
+			...record,
+			integrity
+		};
+	}
+	/**
+	* Read one snapshot's bytes (re-hashed on read).
+	* @param evidenceId - the ledger id.
+	* @returns content plus integrity, or undefined when unknown.
+	*/
+	async readEvidenceContent(evidenceId) {
+		return this.ledger.readContent(evidenceId);
+	}
+	/**
+	* Read one claim with its latest verdict.
+	* @param claimId - the claim id.
+	* @returns the view, or undefined when unknown.
+	*/
+	async getClaim(claimId) {
+		const claim = await this.ledger.getClaim(claimId);
+		if (claim === void 0) return void 0;
+		const verdict = (await this.ledger.latestVerdicts()).get(claimId);
+		return {
+			id: claim.id,
+			text: claim.text,
+			evidenceIds: claim.evidenceIds,
+			...claim.dataset === void 0 ? {} : { dataset: claim.dataset },
+			...verdict === void 0 ? {} : { verdict: {
+				claimId: verdict.claimId,
+				status: verdict.status,
+				...verdict.note === void 0 ? {} : { note: verdict.note },
+				at: verdict.at
+			} }
+		};
+	}
+	/**
+	* List every registered evidence item (re-hashed on read).
+	* @returns all evidence views in registration order.
+	*/
+	async listEvidence() {
+		const records = await this.ledger.listEvidence();
+		const views = [];
+		for (const record of records) {
+			const read = await this.ledger.readContent(record.id);
+			views.push({
+				...record,
+				integrity: read === void 0 ? "missing" : read.integrity
+			});
+		}
+		return views;
+	}
+	/**
+	* List every registered claim with its latest verdict.
+	* @returns all claim views in registration order.
+	*/
+	async listClaims() {
+		const claims = await this.ledger.listClaims();
+		const verdicts = await this.ledger.latestVerdicts();
+		return claims.map((claim) => {
+			const verdict = verdicts.get(claim.id);
+			return {
+				id: claim.id,
+				text: claim.text,
+				evidenceIds: claim.evidenceIds,
+				...claim.dataset === void 0 ? {} : { dataset: claim.dataset },
+				...verdict === void 0 ? {} : { verdict: {
+					claimId: verdict.claimId,
+					status: verdict.status,
+					...verdict.note === void 0 ? {} : { note: verdict.note },
+					at: verdict.at
+				} }
+			};
+		});
+	}
+	/**
+	* Aggregate ledger counts (evidence re-hashed for the tamper count).
+	* @returns the summary.
+	*/
+	async summarize() {
+		const evidence = await this.listEvidence();
+		const claims = await this.ledger.listClaims();
+		const verdicts = await this.ledger.latestVerdicts();
+		return {
+			evidenceCount: evidence.length,
+			claimCount: claims.length,
+			verdictCount: verdicts.size,
+			tamperedCount: evidence.filter((item) => item.integrity !== "ok").length
+		};
+	}
+};
+//#endregion
+//#region src/tools/evidence-add.ts
+/**
+* The `evidence_add` model tool (Consumer): register one evidence snapshot in
+* the ledger. `content` given inline is used verbatim; absent, the origin is
+* captured — a URL through the `ctx.web` seam, a workspace path from disk.
+* @module dsh-research-report/tools/evidence-add
+*/
+/** The tool's output schema (both branches). */
+const OUTPUT_SCHEMA$2 = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		ok: {
+			type: "boolean",
+			required: true
+		},
+		evidenceId: { type: "string" },
+		hash: { type: "string" },
+		bytes: { type: "integer" },
+		title: { type: "string" },
+		origin: { type: "string" },
+		capturedAt: { type: "string" },
+		deduplicated: { type: "boolean" },
+		error: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				code: {
+					type: "string",
+					required: true
+				},
+				message: {
+					type: "string",
+					required: true
+				}
+			}
+		}
+	}
+};
+/**
+* Build the `evidence_add` tool bound to the local provider.
+* @param service - the local research-report provider.
+* @returns the tool definition.
+*/
+function makeEvidenceAddTool(service) {
+	return defineTool({
+		name: "evidence_add",
+		description: [
+			"Register one evidence snapshot in the verifiable research ledger (dsh-research-report).",
+			"",
+			"Pass `content` inline when you already hold the text; otherwise the origin is captured for you — a URL is fetched through the harness web capability (ctx.web), a workspace-relative path is read from disk. Snapshots are content-addressed and immutable: the same content is stored once, and any later byte change is detected as tampering during verification.",
+			"",
+			"Returns the evidence id and its SHA-256 hash. Bind the id to claims in research_report."
+		].join("\n"),
+		parameters: {
+			origin: {
+				type: "string",
+				required: true,
+				description: "Where the evidence comes from: an http(s) URL or a workspace-relative path."
+			},
+			content: {
+				type: "string",
+				description: "The verbatim snapshot text. When omitted, the origin is captured (URL fetched / file read)."
+			},
+			title: {
+				type: "string",
+				description: "Display title (defaults to the origin)."
+			}
+		},
+		output: {
+			schema: OUTPUT_SCHEMA$2,
+			render: (_args, value) => {
+				const result = value;
+				if (!result.ok) return [{
+					type: "text",
+					text: `evidence_add failed (${result.error.code}): ${result.error.message}`
+				}];
+				return [{
+					type: "text",
+					text: `evidence registered: ${result.evidenceId}${result.deduplicated ? " (already stored — deduplicated)" : ""}\nsha256: ${result.hash}\norigin: ${result.origin}\nbytes: ${result.bytes}`
+				}];
+			}
+		},
+		async execute(args, exec) {
+			exec.signal.throwIfAborted();
+			const session = exec.agent?.session;
+			try {
+				const added = args.content !== void 0 ? await service.addEvidence({
+					title: args.title ?? args.origin,
+					origin: args.origin,
+					content: args.content
+				}, session) : await service.captureAndRegister(args.origin, args.title, exec.signal, session);
+				return {
+					ok: true,
+					evidenceId: added.record.id,
+					hash: added.record.hash,
+					bytes: added.record.bytes,
+					title: added.record.title,
+					origin: added.record.origin,
+					capturedAt: added.record.capturedAt,
+					deduplicated: added.deduplicated
+				};
+			} catch (error) {
+				if (error instanceof CaptureError && error.code === "WEB_UNAVAILABLE") throw error;
+				if (error instanceof CaptureError || error instanceof ResearchReportError) return {
+					ok: false,
+					error: {
+						code: error.code,
+						message: error.message
+					}
+				};
+				throw error;
+			}
+		}
+	});
+}
+//#endregion
+//#region src/tools/ledger-query.ts
+/**
+* The `ledger_query` model tool (Consumer): read-only queries over the
+* evidence ledger — bindings, verdicts, and the live integrity re-check.
+* @module dsh-research-report/tools/ledger-query
+*/
+/** The tool's output schema (all four branches). */
+const OUTPUT_SCHEMA$1 = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		kind: {
+			type: "string",
+			required: true,
+			enum: [
+				"evidence",
+				"claim",
+				"summary",
+				"not-found"
+			]
+		},
+		evidence: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				id: {
+					type: "string",
+					required: true
+				},
+				hash: {
+					type: "string",
+					required: true
+				},
+				title: {
+					type: "string",
+					required: true
+				},
+				origin: {
+					type: "string",
+					required: true
+				},
+				capturedAt: {
+					type: "string",
+					required: true
+				},
+				bytes: {
+					type: "integer",
+					required: true
+				},
+				integrity: {
+					type: "string",
+					required: true,
+					enum: [
+						"ok",
+						"tampered",
+						"missing"
+					]
+				}
+			}
+		},
+		claim: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				id: {
+					type: "string",
+					required: true
+				},
+				text: {
+					type: "string",
+					required: true
+				},
+				evidenceIds: {
+					type: "array",
+					required: true,
+					items: { type: "string" }
+				},
+				dataset: { type: "string" },
+				verdict: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						claimId: {
+							type: "string",
+							required: true
+						},
+						status: {
+							type: "string",
+							required: true,
+							enum: [
+								"verified",
+								"unverified",
+								"contradicted"
+							]
+						},
+						note: { type: "string" },
+						at: {
+							type: "string",
+							required: true
+						}
+					}
+				}
+			}
+		},
+		evidenceCount: { type: "integer" },
+		claimCount: { type: "integer" },
+		verdictCount: { type: "integer" },
+		tamperedCount: { type: "integer" },
+		evidenceIds: {
+			type: "array",
+			items: { type: "string" }
+		},
+		claimIds: {
+			type: "array",
+			items: { type: "string" }
+		},
+		message: { type: "string" }
+	}
+};
+/** Render the canonical value as model-facing text. */
+function renderValue$1(value) {
+	switch (value.kind) {
+		case "evidence": {
+			const item = value.evidence;
+			const lines = [
+				`evidence ${item.id}${item.integrity === "ok" ? "" : ` — INTEGRITY ${item.integrity.toUpperCase()}`}`,
+				`  title: ${item.title}`,
+				`  origin: ${item.origin}`,
+				`  sha256: ${item.hash}`,
+				`  captured: ${item.capturedAt} (${item.bytes} bytes)`
+			];
+			if (item.integrity !== "ok") lines.push(`  WARNING: the stored bytes no longer match the indexed hash — any claim bound to this evidence verifies as contradicted`);
+			return [{
+				type: "text",
+				text: lines.join("\n")
+			}];
+		}
+		case "claim": {
+			const claim = value.claim;
+			const lines = [
+				`claim ${claim.id}`,
+				`  text: ${claim.text}`,
+				`  evidence: ${claim.evidenceIds.join(", ") || "(none)"}`
+			];
+			if (claim.dataset !== void 0) lines.push(`  dataset: ${claim.dataset}`);
+			if (claim.verdict === void 0) lines.push("  verdict: (never verified)");
+			else lines.push(`  verdict: ${claim.verdict.status} at ${claim.verdict.at}${claim.verdict.note === void 0 ? "" : ` — ${claim.verdict.note}`}`);
+			return [{
+				type: "text",
+				text: lines.join("\n")
+			}];
+		}
+		case "summary": return [{
+			type: "text",
+			text: [
+				`ledger summary: ${value.evidenceCount} evidence, ${value.claimCount} claims, ${value.verdictCount} verdicts, ${value.tamperedCount} integrity failures`,
+				`evidence ids: ${value.evidenceIds.join(", ") || "(none)"}`,
+				`claim ids: ${value.claimIds.join(", ") || "(none)"}`
+			].join("\n")
+		}];
+		case "not-found": return [{
+			type: "text",
+			text: value.message
+		}];
+	}
+}
+/**
+* Build the `ledger_query` tool bound to the local provider.
+* @param service - the local research-report provider.
+* @returns the tool definition.
+*/
+function makeLedgerQueryTool(service) {
+	return defineTool({
+		name: "ledger_query",
+		description: ["Read-only query over the verifiable research ledger (dsh-research-report): claim ↔ evidence bindings and verification verdicts.", "Pass claimId or evidenceId for one entry (evidence is re-hashed on read — integrity tampered/missing is reported explicitly), or neither for a ledger summary."].join("\n"),
+		parameters: {
+			claimId: {
+				type: "string",
+				description: "Query one claim: its bindings and latest verdict."
+			},
+			evidenceId: {
+				type: "string",
+				description: "Query one evidence item: provenance, hash, live integrity."
+			}
+		},
+		output: {
+			schema: OUTPUT_SCHEMA$1,
+			render: (_args, value) => renderValue$1(value)
+		},
+		async execute(args, exec) {
+			exec.signal.throwIfAborted();
+			if (args.claimId !== void 0) {
+				const claim = await service.getClaim(args.claimId);
+				return claim === void 0 ? {
+					kind: "not-found",
+					message: `no claim "${args.claimId}" in the ledger`
+				} : {
+					kind: "claim",
+					claim
+				};
+			}
+			if (args.evidenceId !== void 0) {
+				const evidence = await service.getEvidence(args.evidenceId);
+				return evidence === void 0 ? {
+					kind: "not-found",
+					message: `no evidence "${args.evidenceId}" in the ledger`
+				} : {
+					kind: "evidence",
+					evidence
+				};
+			}
+			const [summary, evidence, claims] = await Promise.all([
+				service.summarize(),
+				service.listEvidence(),
+				service.listClaims()
+			]);
+			return {
+				kind: "summary",
+				...summary,
+				evidenceIds: evidence.map((item) => item.id),
+				claimIds: claims.map((claim) => claim.id)
+			};
+		}
+	});
+}
+//#endregion
+//#region src/tools/research-report.ts
+/**
+* The `research_report` model tool (Consumer): assemble and seal one
+* verifiable report from ledger evidence, or — with `gather: true` — run one
+* search round over `ctx.web` and hand the candidate/gap list back to the
+* model for confirmation (never auto-assembles). Long runs may go to a
+* `research-report` background job over `ctx.jobs`.
+* @module dsh-research-report/tools/research-report
+*/
+/** The tool's output schema (all three branches). */
+const OUTPUT_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		kind: {
+			type: "string",
+			required: true,
+			enum: [
+				"sealed",
+				"background",
+				"gathered"
+			]
+		},
+		reportDir: { type: "string" },
+		reportFile: { type: "string" },
+		manifestFile: { type: "string" },
+		sealHash: { type: "string" },
+		verdicts: {
+			type: "array",
+			items: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					claimId: {
+						type: "string",
+						required: true
+					},
+					status: {
+						type: "string",
+						required: true,
+						enum: [
+							"verified",
+							"unverified",
+							"contradicted"
+						]
+					},
+					note: { type: "string" }
+				}
+			}
+		},
+		counts: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				verified: {
+					type: "integer",
+					required: true
+				},
+				unverified: {
+					type: "integer",
+					required: true
+				},
+				contradicted: {
+					type: "integer",
+					required: true
+				}
+			}
+		},
+		evidenceCount: { type: "integer" },
+		jobId: { type: "string" },
+		topic: { type: "string" },
+		candidates: {
+			type: "array",
+			items: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					url: {
+						type: "string",
+						required: true
+					},
+					title: { type: "string" },
+					snippet: { type: "string" },
+					status: {
+						type: "string",
+						required: true,
+						enum: ["captured", "uncaptured"]
+					},
+					evidenceId: { type: "string" },
+					reason: { type: "string" }
+				}
+			}
+		},
+		gaps: {
+			type: "array",
+			items: { type: "string" }
+		}
+	}
+};
+/** The sections parameter schema fragment. */
+const sectionsSchema = {
+	type: "array",
+	items: {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			heading: {
+				type: "string",
+				required: true
+			},
+			paragraphs: {
+				type: "array",
+				required: true,
+				items: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						text: {
+							type: "string",
+							required: true
+						},
+						claimIds: {
+							type: "array",
+							items: { type: "string" }
+						}
+					}
+				}
+			}
+		}
+	}
+};
+/** The claims parameter schema fragment (frozen shape + the optional numeric bridge). */
+const claimsSchema = {
+	type: "array",
+	items: {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			id: {
+				type: "string",
+				required: true
+			},
+			text: {
+				type: "string",
+				required: true
+			},
+			evidenceIds: {
+				type: "array",
+				required: true,
+				items: { type: "string" }
+			},
+			dataset: { type: "string" },
+			citations: {
+				type: "array",
+				items: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						id: {
+							type: "string",
+							required: true
+						},
+						path: {
+							type: "string",
+							required: true
+						},
+						value: {
+							oneOf: [{ type: "number" }, { type: "string" }],
+							required: true
+						},
+						tolerance: { type: "number" }
+					}
+				}
+			}
+		}
+	}
+};
+/** Render the sealed branch as model-facing text (gaps/contradictions explicit). */
+function renderSealed(value) {
+	const lines = [
+		`report sealed: ${value.reportDir}`,
+		`seal (sha256 of manifest.json): ${value.sealHash}`,
+		`claims: ${value.counts.verified} verified / ${value.counts.unverified} unverified / ${value.counts.contradicted} contradicted (of ${value.verdicts.length}); evidence bound: ${value.evidenceCount}`
+	];
+	const problems = value.verdicts.filter((verdict) => verdict.status !== "verified");
+	if (problems.length > 0) {
+		lines.push("", "claims needing attention (visible markers kept in the report body):");
+		for (const verdict of problems) lines.push(`- [${verdict.status}] ${verdict.claimId}${verdict.note === void 0 ? "" : ` — ${verdict.note}`}`);
+	}
+	return lines.join("\n");
+}
+/** Render the canonical value as model-facing text. */
+function renderValue(value) {
+	switch (value.kind) {
+		case "background": return [{
+			type: "text",
+			text: `started background report job ${value.jobId}; read progress with job_output and stop it with job_kill — the final output names the sealed directory and seal hash`
+		}];
+		case "gathered": {
+			const lines = [`gathered ${value.candidates.length} candidate source(s) for "${value.topic}" (nothing assembled yet — confirm the evidence set first):`];
+			for (const candidate of value.candidates) lines.push(candidate.status === "captured" ? `- captured ${candidate.evidenceId}: ${candidate.title ?? candidate.url}` : `- uncaptured ${candidate.url}: ${candidate.reason ?? "unknown reason"}`);
+			if (value.gaps.length > 0) {
+				lines.push("", "gaps to close:");
+				for (const gap of value.gaps) lines.push(`- ${gap}`);
+			}
+			lines.push("", "next: call research_report again with evidenceRefs chosen from the captured ids (or add more with evidence_add).");
+			return [{
+				type: "text",
+				text: lines.join("\n")
+			}];
+		}
+		case "sealed": return [{
+			type: "text",
+			text: renderSealed(value)
+		}];
+	}
+}
+/**
+* Build the `research_report` tool bound to the local provider.
+* @param deps - the plugin context plus the provider.
+* @returns the tool definition.
+*/
+function makeResearchReportTool(deps) {
+	const { service } = deps;
+	return defineTool({
+		name: "research_report",
+		description: [
+			"Assemble and seal a verifiable research report (dsh-research-report).",
+			"",
+			"Every claim must bind evidence already in the ledger (evidence_add) and is verified against the stored bytes: numbers and quoted spans must be locatable verbatim. The report directory is versioned and sealed (manifest.json + SHA-256 seal hash); unverified or contradicted claims keep a visible [未核实] / [与证据矛盾] marker in the body and are listed in Appendix A — they are never silently passed.",
+			"",
+			"Optional convenience: set gather: true to run ONE search round over the topic via the harness web capability. Captured snapshots are registered as evidence; the candidate list plus an explicit gap list come back for your confirmation — nothing is assembled automatically.",
+			"",
+			"Set background: true for a background job (returns a job id; read with job_output, stop with job_kill)."
+		].join("\n"),
+		parameters: {
+			topic: {
+				type: "string",
+				required: true,
+				description: "The research topic (names the versioned report directory)."
+			},
+			title: {
+				type: "string",
+				description: "Report title (defaults to \"Research report: <topic>\")."
+			},
+			sections: {
+				...sectionsSchema,
+				description: "Report body: heading + paragraphs; each paragraph may cite claim ids."
+			},
+			claims: {
+				...claimsSchema,
+				description: "Claim registrations: id, text, bound evidence ids, and the optional dataset citation bridge."
+			},
+			evidenceRefs: {
+				type: "array",
+				items: { type: "string" },
+				description: "Ledger evidence ids (from evidence_add / gather) to bind into this report."
+			},
+			gather: {
+				type: "boolean",
+				description: "Run one search round and return candidates + gaps instead of assembling."
+			},
+			depth: {
+				type: "string",
+				enum: [
+					"quick",
+					"standard",
+					"deep"
+				],
+				description: "Gather depth: quick=3, standard=5, deep=8 sources."
+			},
+			background: {
+				type: "boolean",
+				description: "Assemble as a background job (ctx.jobs) and return the job id immediately."
+			}
+		},
+		output: {
+			schema: OUTPUT_SCHEMA,
+			render: (_args, value) => renderValue(value),
+			presentationMeta: (_args, value) => {
+				const result = value;
+				return result.kind === "sealed" ? sealedMeta(result) : {};
+			}
+		},
+		async execute(args, exec) {
+			exec.signal.throwIfAborted();
+			const session = exec.agent?.session;
+			if (args.gather === true) {
+				const outcome = await service.gather(args.topic, args.depth ?? "standard", exec.signal, session);
+				return {
+					kind: "gathered",
+					topic: outcome.topic,
+					candidates: outcome.candidates,
+					gaps: outcome.gaps
+				};
+			}
+			const request = await buildRequest(service, args);
+			if (args.background === true) {
+				const jobs = deps.ctx.get("jobs");
+				if (jobs === void 0) throw new Error("background jobs unavailable: this composition mounts no ctx.jobs (load @deepseek-ai/dsh-jobs-local and @deepseek-ai/dsh-tool-jobs), or call without background");
+				if (exec.signal.aborted) throw new Error("tool call aborted");
+				return {
+					kind: "background",
+					jobId: jobs.start({
+						kind: "research-report",
+						label: `assemble report: ${args.topic}`,
+						...exec.agent === void 0 ? {} : { owner: exec.agent },
+						run: () => startAssembleJob(service, request, session === void 0 ? {} : { session })
+					})
+				};
+			}
+			const result = await service.assemble(request, session === void 0 ? {} : { session });
+			return sealedValue(result.reportDir, result.sealHash, result.verdicts, request.evidence.length);
+		},
+		presentCall: (args) => {
+			const topic = args.topic;
+			return {
+				card: "generic",
+				title: `Research report: ${typeof topic === "string" ? topic : ""}`
+			};
+		},
+		presentResult: (_args, result) => {
+			const meta = result.meta;
+			if (meta?.reportFile === void 0 || meta.manifestFile === void 0) return void 0;
+			return {
+				card: "generic",
+				title: "Sealed research report",
+				kind: "edit",
+				locations: [{ path: meta.reportFile }, { path: meta.manifestFile }]
+			};
+		}
+	});
+}
+/** The durable presentation projection (report file paths for the UI card). */
+function sealedMeta(value) {
+	return {
+		reportFile: value.reportFile,
+		manifestFile: value.manifestFile
+	};
+}
+/** Shape the sealed canonical value. */
+function sealedValue(reportDir, sealHash, verdicts, evidenceCount) {
+	const counts = {
+		verified: 0,
+		unverified: 0,
+		contradicted: 0
+	};
+	for (const verdict of verdicts) counts[verdict.status] += 1;
+	return {
+		kind: "sealed",
+		reportDir,
+		reportFile: path.join(reportDir, "report.md"),
+		manifestFile: path.join(reportDir, "manifest.json"),
+		sealHash,
+		verdicts,
+		counts,
+		evidenceCount
+	};
+}
+/**
+* Build the frozen assemble request from the tool args: resolve evidenceRefs
+* through the ledger (unknown ids fail loud) and default the title.
+* @param service - the local provider.
+* @param args - the validated tool args.
+* @returns the assemble request.
+*/
+async function buildRequest(service, args) {
+	const refs = args.evidenceRefs ?? [];
+	const evidence = [];
+	for (const ref of refs) {
+		const record = await service.getEvidence(ref);
+		const read = await service.readEvidenceContent(ref);
+		if (record === void 0 || read === void 0) throw new Error(`unknown evidence id "${ref}" in evidenceRefs — register it with evidence_add first`);
+		evidence.push({
+			id: record.id,
+			title: record.title,
+			origin: record.origin,
+			content: read.content,
+			capturedAt: record.capturedAt
+		});
+	}
+	return {
+		title: args.title ?? `Research report: ${args.topic}`,
+		topic: args.topic,
+		evidence,
+		sections: args.sections ?? [],
+		claims: args.claims ?? []
+	};
+}
+/**
+* Start the background assemble job body. The job owns its cancellation
+* signal; settlement flushes the sealed summary into the job output.
+* @param service - the local provider.
+* @param request - the frozen assemble request.
+* @param context - the assemble context (owning session, when known).
+* @returns the job hooks.
+*/
+function startAssembleJob(service, request, context) {
+	const abort = new AbortController();
+	const progress = [`assembling report: ${request.topic}`];
+	const done = Promise.withResolvers();
+	let settled = false;
+	const settle = (outcome) => {
+		if (settled) return;
+		settled = true;
+		done.resolve(outcome);
+	};
+	service.assemble(request, context).then((result) => {
+		const value = sealedValue(result.reportDir, result.sealHash, result.verdicts, request.evidence.length);
+		progress.push(renderSealed(value));
+		settle({
+			status: "completed",
+			detail: `sealed ${result.sealHash.slice(0, 12)}`,
+			output: renderSealed(value)
+		});
+	}).catch((error) => {
+		const message = error instanceof CaptureError || error instanceof Error ? error.message : String(error);
+		progress.push(`assemble failed: ${message}`);
+		settle({
+			status: "failed",
+			detail: message.length > 200 ? `${message.slice(0, 197)}…` : message
+		});
+	});
+	return {
+		cancel(reason) {
+			abort.abort(reason ?? "cancelled");
+			settle({
+				status: "killed",
+				detail: `cancelled: ${reason ?? "no reason given"}`
+			});
+		},
+		done: done.promise,
+		readOutput: () => {
+			if (progress.length === 0) return "";
+			return `${progress.splice(0, progress.length).join("\n")}\n`;
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+const name = "research-report";
+/**
+* Public services only. `web` (evidence capture) and `jobs` (background
+* assembly) are deliberately OPTIONAL and resolved with `ctx.get` at call
+* time: a composition without them still mounts, and the affected paths fail
+* loud with an explicit reason.
+*/
+const inject = ["tools", "systemPrompt"];
+/** The short prompt section: one role statement plus the workflow. */
+const PROMPT_SECTION = ["You have a verifiable research-report engine (dsh-research-report) whose reports prove every claim against stored evidence bytes.", "When asked for a research deliverable: register evidence snapshots with evidence_add (URL or workspace path), then call research_report with sections whose paragraphs cite claim ids bound to those evidence ids. Every claim is verified against the stored snapshot bytes; unverified or contradicted claims stay visibly marked in the sealed report — never paper over them. ledger_query reads bindings and verdicts back."].join("\n");
+/**
+* Mount the engine: resolve config (fail loud), construct the local provider
+* (registering `ctx.researchReport` on this fiber), register the three tools,
+* and contribute the short prompt section.
+* @param ctx - the plugin context (host).
+* @param config - raw plugin config.
+*/
+function apply(ctx, config) {
+	const resolved = resolveConfig(config);
+	const logger = ctx.logger("research-report");
+	if (!resolved.enabled) {
+		logger.info("disabled: enabled is false — no service, tools, or prompt section are mounted");
+		return;
+	}
+	const service = new LocalResearchReportService(ctx, resolved, process.cwd());
+	ctx.effect(() => ctx.tools.register(makeEvidenceAddTool(service)), "research-report: evidence_add tool");
+	ctx.effect(() => ctx.tools.register(makeResearchReportTool({
+		ctx,
+		service
+	})), "research-report: research_report tool");
+	ctx.effect(() => ctx.tools.register(makeLedgerQueryTool(service)), "research-report: ledger_query tool");
+	ctx.systemPrompt.section({
+		name: "dsh-research-report:workflow",
+		order: 10,
+		text: PROMPT_SECTION
+	});
+}
+//#endregion
+export { CONTRADICTED_MARK, CaptureError, Config, EvidenceLedger, GATHER_DEPTH_RESULTS, LedgerError, LocalResearchReportService, MANIFEST_SCHEMA, RequestValidationError, ResearchReportError, ResearchReportService, UNVERIFIED_MARK, VERSION, apply, buildManifest, captureFromFile, captureFromWeb, captureSnapshot, combineOutcomes, configFingerprint, contextLabelOf, extractCitations, gatherCandidates, inject, isUrlOrigin, mapBridgeResults, name, normalizeNumber, renderReportMarkdown, resolveConfig, resolveWorkspacePath, serializeManifest, sha256Of, slugify, toWorkspaceRelative, validateAssembleRequest, verifyClaimText, versionIdOf };