dsh-research-report 0.1.0

package/lib/types/gather.js

@@ -0,0 +1,165 @@
+/**
+ * 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
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+/** A loud capture failure with a machine-routable code (also in the message). */
+export class CaptureError 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). */
+export 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.
+ */
+export 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. */
+export function toWorkspaceRelative(workspaceRoot, absolute) {
+    const relative = path.relative(path.resolve(workspaceRoot), path.resolve(absolute));
+    return relative.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).
+ */
+export async function captureFromWeb(deps, url, signal) {
+    if (deps.web === undefined) {
+        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 === undefined ? timeout : AbortSignal.any([signal, timeout]);
+    let result;
+    try {
+        result = await deps.web.fetch({ url }, linked);
+    }
+    catch (error) {
+        if (timeout.aborted && (signal === undefined || !signal.aborted)) {
+            throw new CaptureError('FETCH_TIMEOUT', `fetch of ${url} exceeded the configured fetchTimeoutMs ${deps.fetchTimeoutMs}`);
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CaptureError('FETCH_FAILED', `fetch of ${url} failed: ${message}`);
+    }
+    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).
+ */
+export 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.
+ */
+export async function captureSnapshot(deps, origin, signal) {
+    return isUrlOrigin(origin) ? captureFromWeb(deps, origin, signal) : captureFromFile(deps, origin);
+}
+// ── Topic gathering (the optional `gather: true` convenience) ───────────────
+/** Search depth → how many sources are fetched for snapshot capture. */
+export 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.
+ */
+export async function gatherCandidates(deps, topic, depth, signal, register) {
+    if (deps.web === undefined) {
+        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 === undefined ? {} : { title: source.title }),
+                ...(source.snippet === undefined ? {} : { 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 === undefined ? {} : { title: source.title }),
+                ...(source.snippet === undefined ? {} : { 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 };
+}
+//# sourceMappingURL=gather.js.map

package/lib/types/gather.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gather.js","sourceRoot":"","sources":["../../src/gather.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,IAAI,MAAM,WAAW,CAAA;AAY5B,iFAAiF;AACjF,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,yCAAyC;IAChC,IAAI,CAAkB;IAC/B,YAAY,IAAsB,EAAE,OAAe;QACjD,KAAK,CAAC,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC,CAAA;QAC7B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAED,kEAAkE;AAClE,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;AACtC,CAAC;AAoBD;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,aAAqB,EAAE,MAAc;IACxE,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAA;IACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAC3C,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,YAAY,CAAC,0BAA0B,EAAE,UAAU,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,iCAAiC,CAAC,CAAA;IACvH,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,mBAAmB,CAAC,aAAqB,EAAE,QAAgB;IACzE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAA;IACnF,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAiB,EAAE,GAAW,EAAE,MAAoB;IACvF,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,IAAI,YAAY,CACpB,iBAAiB,EACjB,+IAA+I,CAChJ,CAAA;IACH,CAAC;IACD,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;IACxD,MAAM,MAAM,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAClF,IAAI,MAAM,CAAA;IACV,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,EAAE,MAAM,CAAC,CAAA;IAChD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,OAAO,CAAC,OAAO,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YACjE,MAAM,IAAI,YAAY,CAAC,eAAe,EAAE,YAAY,GAAG,2CAA2C,IAAI,CAAC,cAAc,EAAE,CAAC,CAAA;QAC1H,CAAC;QACD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACtE,MAAM,IAAI,YAAY,CAAC,cAAc,EAAE,YAAY,GAAG,YAAY,OAAO,EAAE,CAAC,CAAA;IAC9E,CAAC;IACD,IAAI,MAAM,CAAC,UAAU,GAAG,GAAG,IAAI,MAAM,CAAC,UAAU,IAAI,GAAG,EAAE,CAAC;QACxD,MAAM,IAAI,YAAY,CAAC,cAAc,EAAE,YAAY,GAAG,kBAAkB,MAAM,CAAC,UAAU,wBAAwB,CAAC,CAAA;IACpH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,CAAA;AAC7D,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAiB,EAAE,MAAc;IACrE,MAAM,QAAQ,GAAG,oBAAoB,CAAC,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,CAAA;IACjE,IAAI,OAAe,CAAA;IACnB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,YAAY,CAAC,mBAAmB,EAAE,eAAe,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAA;IACnH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,mBAAmB,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,EAAE,CAAA;AAC/E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAiB,EAAE,MAAc,EAAE,MAAoB;IAC3F,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;AACnG,CAAC;AAED,+EAA+E;AAE/E,wEAAwE;AACxE,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAW,CAAA;AA+B/E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAiB,EACjB,KAAa,EACb,KAAkB,EAClB,MAA+B,EAC/B,QAAgG;IAEhG,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,IAAI,YAAY,CACpB,iBAAiB,EACjB,2HAA2H,CAC5H,CAAA;IACH,CAAC;IACD,MAAM,UAAU,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAA;IAC9C,IAAI,MAAM,CAAA;IACV,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,MAAM,CAAC,CAAA;IACtE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACtE,MAAM,IAAI,YAAY,CAAC,cAAc,EAAE,cAAc,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,YAAY,OAAO,EAAE,CAAC,CAAA;IAClG,CAAC;IACD,MAAM,UAAU,GAAsB,EAAE,CAAA;IACxC,MAAM,IAAI,GAAa,EAAE,CAAA;IACzB,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACpC,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;YAC/D,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC;gBAC5B,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,GAAG;gBACjC,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,OAAO,EAAE,QAAQ,CAAC,OAAO;aAC1B,CAAC,CAAA;YACF,UAAU,CAAC,IAAI,CAAC;gBACd,GAAG,EAAE,MAAM,CAAC,GAAG;gBACf,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;gBAC9D,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpE,MAAM,EAAE,UAAU;gBAClB,UAAU,EAAE,MAAM,CAAC,EAAE;aACtB,CAAC,CAAA;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,MAAM,GAAG,KAAK,YAAY,YAAY,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;YAChG,UAAU,CAAC,IAAI,CAAC;gBACd,GAAG,EAAE,MAAM,CAAC,GAAG;gBACf,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;gBAC9D,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpE,MAAM,EAAE,YAAY;gBACpB,MAAM;aACP,CAAC,CAAA;YACF,IAAI,CAAC,IAAI,CAAC,mBAAmB,MAAM,CAAC,GAAG,KAAK,MAAM,wDAAwD,CAAC,CAAA;QAC7G,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,6BAA6B,UAAU,0BAA0B,UAAU,kBAAkB,CAAC,CAAA;IAC9H,IAAI,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,KAAK,YAAY,CAAC,EAAE,CAAC;QACrE,IAAI,CAAC,IAAI,CAAC,0GAA0G,CAAC,CAAA;IACvH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,CAAA;AACpC,CAAC"}

package/lib/types/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `dsh-research-report` — a domain-agnostic verifiable research-report engine
+ * for DeepSeek Harness. A content-addressed evidence ledger (claim ↔ snapshot
+ * binding, tamper-evident) plus versioned sealed reports: every claim carries
+ * a verification verdict, and the manifest hash seals the report directory.
+ * Retrieval orchestration is deliberately NOT re-implemented here — evidence
+ * gathering reuses the official `ctx.web` seam and long runs ride `ctx.jobs`.
+ *
+ * One package carries the complete capability seam: `service.ts` is the
+ * Service Definition (`ctx.researchReport`, with the byte-frozen assemble
+ * contract), `provider-local.ts` is the local Provider, and `tools/` the
+ * model-facing Consumers.
+ *
+ * Function plugin — no default export (the Loader unwraps
+ * `exports.default ?? exports`, and a stray default would discard
+ * `name`/`inject`/`Config`/`apply`).
+ * @module dsh-research-report
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config } from './config.js';
+export declare 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.
+ */
+export declare const inject: string[];
+export { Config, resolveConfig } from './config.js';
+export type { ResolvedConfig } from './config.js';
+export { VERSION } from './version.js';
+export { ResearchReportService } from './service.js';
+export type { AddEvidenceInput, AssembleContext, AssembleReportRequest, AssembleReportResult, ClaimRegistration, ClaimVerdict, ClaimView, EvidenceInput, EvidenceIntegrity, EvidenceRecord, EvidenceView, LedgerSummary, ReportSectionInput, StoredVerdict, VerdictStatus, } from './service.js';
+export { EvidenceLedger, LedgerError, sha256Of } from './ledger.js';
+export type { LedgerClaimLine, LedgerIndexLine, LedgerVerdictLine } from './ledger.js';
+export { combineOutcomes, contextLabelOf, extractCitations, mapBridgeResults, normalizeNumber, verifyClaimText, } from './verify.js';
+export type { ByteCheckOutcome, Citation, CitationCheckRequest, CitationCheckResult, DataQualityBridge, } from './verify.js';
+export { CONTRADICTED_MARK, MANIFEST_SCHEMA, RequestValidationError, UNVERIFIED_MARK, buildManifest, configFingerprint, renderReportMarkdown, serializeManifest, slugify, validateAssembleRequest, versionIdOf, } from './assemble.js';
+export type { ReportManifest, ReportPlan } from './assemble.js';
+export { CaptureError, GATHER_DEPTH_RESULTS, captureFromFile, captureFromWeb, captureSnapshot, gatherCandidates, isUrlOrigin, resolveWorkspacePath, toWorkspaceRelative, } from './gather.js';
+export type { CaptureDeps, GatherCandidate, GatherOutcome } from './gather.js';
+export { LocalResearchReportService, ResearchReportError } from './provider-local.js';
+/**
+ * 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.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAGlD,OAAO,EAAE,MAAM,EAAiB,MAAM,aAAa,CAAA;AAMnD,eAAO,MAAM,IAAI,oBAAoB,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,MAAM,UAA4B,CAAA;AAE/C,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AACnD,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AACpD,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,aAAa,GACd,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACnE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACtF,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,gBAAgB,EAChB,QAAQ,EACR,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,sBAAsB,EACtB,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,OAAO,EACP,uBAAuB,EACvB,WAAW,GACZ,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC/D,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,eAAe,EACf,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC9E,OAAO,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAQrF;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAqBxD"}

package/lib/types/index.js

@@ -0,0 +1,71 @@
+/**
+ * `dsh-research-report` — a domain-agnostic verifiable research-report engine
+ * for DeepSeek Harness. A content-addressed evidence ledger (claim ↔ snapshot
+ * binding, tamper-evident) plus versioned sealed reports: every claim carries
+ * a verification verdict, and the manifest hash seals the report directory.
+ * Retrieval orchestration is deliberately NOT re-implemented here — evidence
+ * gathering reuses the official `ctx.web` seam and long runs ride `ctx.jobs`.
+ *
+ * One package carries the complete capability seam: `service.ts` is the
+ * Service Definition (`ctx.researchReport`, with the byte-frozen assemble
+ * contract), `provider-local.ts` is the local Provider, and `tools/` the
+ * model-facing Consumers.
+ *
+ * Function plugin — no default export (the Loader unwraps
+ * `exports.default ?? exports`, and a stray default would discard
+ * `name`/`inject`/`Config`/`apply`).
+ * @module dsh-research-report
+ */
+import { resolveConfig } from "./config.js";
+import { LocalResearchReportService } from "./provider-local.js";
+import { makeEvidenceAddTool } from "./tools/evidence-add.js";
+import { makeLedgerQueryTool } from "./tools/ledger-query.js";
+import { makeResearchReportTool } from "./tools/research-report.js";
+export 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.
+ */
+export const inject = ['tools', 'systemPrompt'];
+export { Config, resolveConfig } from "./config.js";
+export { VERSION } from "./version.js";
+export { ResearchReportService } from "./service.js";
+export { EvidenceLedger, LedgerError, sha256Of } from "./ledger.js";
+export { combineOutcomes, contextLabelOf, extractCitations, mapBridgeResults, normalizeNumber, verifyClaimText, } from "./verify.js";
+export { CONTRADICTED_MARK, MANIFEST_SCHEMA, RequestValidationError, UNVERIFIED_MARK, buildManifest, configFingerprint, renderReportMarkdown, serializeManifest, slugify, validateAssembleRequest, versionIdOf, } from "./assemble.js";
+export { CaptureError, GATHER_DEPTH_RESULTS, captureFromFile, captureFromWeb, captureSnapshot, gatherCandidates, isUrlOrigin, resolveWorkspacePath, toWorkspaceRelative, } from "./gather.js";
+export { LocalResearchReportService, ResearchReportError } from "./provider-local.js";
+/** 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.
+ */
+export 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;
+    }
+    // The provider registers itself as ctx.researchReport on construction and
+    // is unregistered with this fiber (Service base semantics).
+    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,
+    });
+}
+//# sourceMappingURL=index.js.map

package/lib/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,EAAU,aAAa,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAA;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAA;AAEnE,MAAM,CAAC,MAAM,IAAI,GAAG,iBAAiB,CAAA;AAErC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,cAAc,CAAC,CAAA;AAE/C,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEnD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAkBpD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEnE,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,aAAa,CAAA;AAQpB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,sBAAsB,EACtB,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,OAAO,EACP,uBAAuB,EACvB,WAAW,GACZ,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,eAAe,EACf,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAErF,sEAAsE;AACtE,MAAM,cAAc,GAAG;IACrB,mIAAmI;IACnI,kaAAka;CACna,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAEZ;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CAAC,GAAY,EAAE,MAAc;IAChD,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAA;IACtC,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAA;IAC5C,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QACtB,MAAM,CAAC,IAAI,CAAC,+EAA+E,CAAC,CAAA;QAC5F,OAAM;IACR,CAAC;IAED,0EAA0E;IAC1E,4DAA4D;IAC5D,MAAM,OAAO,GAAG,IAAI,0BAA0B,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;IAE5E,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC,EAAE,oCAAoC,CAAC,CAAA;IACxG,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,uCAAuC,CAAC,CAAA;IACvH,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC,EAAE,oCAAoC,CAAC,CAAA;IAExG,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC;QACvB,IAAI,EAAE,8BAA8B;QACpC,KAAK,EAAE,EAAE;QACT,IAAI,EAAE,cAAc;KACrB,CAAC,CAAA;AACJ,CAAC"}

package/lib/types/ledger.d.ts

@@ -0,0 +1,159 @@
+/**
+ * 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. */
+export declare function sha256Of(content: string): string;
+/** Error codes the ledger reports. */
+export type LedgerErrorCode = 'ID_CONFLICT' | 'JOURNAL_CORRUPT' | 'IO';
+/** A loud ledger failure (audit state must never degrade silently). */
+export declare class LedgerError extends Error {
+    /** The machine-routable failure code. */
+    readonly code: LedgerErrorCode;
+    constructor(code: LedgerErrorCode, message: string);
+}
+/** One line of `index.jsonl` — the durable evidence record. */
+export interface LedgerIndexLine {
+    id: string;
+    hash: string;
+    title: string;
+    origin: string;
+    capturedAt: string;
+    bytes: number;
+}
+/** One line of `claims.jsonl` — the durable claim registration. */
+export interface LedgerClaimLine {
+    id: string;
+    text: string;
+    evidenceIds: string[];
+    dataset?: string;
+    citations?: Array<{
+        id: string;
+        path: string;
+        value: number | string;
+        tolerance?: number;
+    }>;
+    registeredAt: string;
+}
+/** One line of `verdicts.jsonl` — the durable verdict record. */
+export interface LedgerVerdictLine {
+    claimId: string;
+    status: 'verified' | 'unverified' | 'contradicted';
+    note?: string;
+    at: string;
+}
+/** Outcome of one {@link EvidenceLedger.putEvidence}. */
+export interface PutOutcome {
+    /** The durable record (the existing one when deduplicated). */
+    record: LedgerIndexLine;
+    /** True when this call appended a new registration. */
+    created: boolean;
+}
+/**
+ * The content-addressed evidence ledger. Writes are serialized through an
+ * internal promise queue so concurrent tool calls cannot interleave journals.
+ */
+export declare class EvidenceLedger {
+    /** Absolute ledger root directory. */
+    readonly root: string;
+    /** Write serialization chain (never rejects — each link absorbs the previous error). */
+    private queue;
+    /**
+     * @param root - absolute ledger root directory.
+     */
+    constructor(root: string);
+    private get objectsDir();
+    private get indexFile();
+    private get claimsFile();
+    private get verdictsFile();
+    /** Run `work` after all previously queued writes settle. */
+    private enqueue;
+    /** Ensure the directory layout exists. */
+    private ensureLayout;
+    /** Write one snapshot object atomically (tmp + rename); no-op when present. */
+    private writeObject;
+    /**
+     * 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.
+     */
+    putEvidence(input: {
+        id?: string;
+        title: string;
+        origin: string;
+        content: string;
+        capturedAt: string;
+    }): Promise<PutOutcome>;
+    /**
+     * 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).
+     */
+    registerClaims(claims: Array<Omit<LedgerClaimLine, 'registeredAt'>>, registeredAt: string): Promise<LedgerClaimLine[]>;
+    /**
+     * Append one verdict (latest per claim wins on read).
+     * @param verdict - claimId, status, optional note.
+     * @param at - ISO-8601 write time.
+     */
+    recordVerdict(verdict: Omit<LedgerVerdictLine, 'at'>, at: string): Promise<void>;
+    /**
+     * Read the evidence index.
+     * @returns every registration in append order.
+     */
+    listEvidence(): Promise<LedgerIndexLine[]>;
+    /**
+     * Read one evidence registration.
+     * @param id - the ledger id.
+     * @returns the record, or undefined when unknown.
+     */
+    getEvidence(id: string): Promise<LedgerIndexLine | undefined>;
+    /**
+     * Read every claim registration.
+     * @returns every claim in append order.
+     */
+    listClaims(): Promise<LedgerClaimLine[]>;
+    /**
+     * Read one claim registration.
+     * @param id - the claim id.
+     * @returns the claim line, or undefined when unknown.
+     */
+    getClaim(id: string): Promise<LedgerClaimLine | undefined>;
+    /**
+     * Fold the verdict journal to the latest verdict per claim.
+     * @returns claimId → latest stored verdict.
+     */
+    latestVerdicts(): Promise<Map<string, LedgerVerdictLine>>;
+    /**
+     * 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.
+     */
+    readContent(id: string): Promise<{
+        content: string;
+        integrity: 'ok' | 'tampered' | 'missing';
+    } | undefined>;
+}
+//# sourceMappingURL=ledger.d.ts.map

package/lib/types/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../src/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH,uCAAuC;AACvC,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,sCAAsC;AACtC,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,iBAAiB,GAAG,IAAI,CAAA;AAEtE,uEAAuE;AACvE,qBAAa,WAAY,SAAQ,KAAK;IACpC,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;gBAClB,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM;CAKnD;AAED,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;CACd;AAED,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC3F,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,UAAU,GAAG,YAAY,GAAG,cAAc,CAAA;IAClD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,EAAE,EAAE,MAAM,CAAA;CACX;AAED,yDAAyD;AACzD,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,MAAM,EAAE,eAAe,CAAA;IACvB,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAA;CACjB;AA0BD;;;GAGG;AACH,qBAAa,cAAc;IACzB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB,wFAAwF;IACxF,OAAO,CAAC,KAAK,CAAmC;IAEhD;;OAEG;gBACS,IAAI,EAAE,MAAM;IAIxB,OAAO,KAAK,UAAU,GAErB;IAED,OAAO,KAAK,SAAS,GAEpB;IAED,OAAO,KAAK,UAAU,GAErB;IAED,OAAO,KAAK,YAAY,GAEvB;IAED,4DAA4D;IAC5D,OAAO,CAAC,OAAO;IASf,0CAA0C;YAC5B,YAAY;IAI1B,+EAA+E;YACjE,WAAW;IAyBzB;;;;;;OAMG;IACG,WAAW,CAAC,KAAK,EAAE;QACvB,EAAE,CAAC,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,MAAM,CAAA;QACb,MAAM,EAAE,MAAM,CAAA;QACd,OAAO,EAAE,MAAM,CAAA;QACf,UAAU,EAAE,MAAM,CAAA;KACnB,GAAG,OAAO,CAAC,UAAU,CAAC;IA8BvB;;;;;;OAMG;IACG,cAAc,CAClB,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,eAAe,EAAE,cAAc,CAAC,CAAC,EACpD,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,eAAe,EAAE,CAAC;IA6B7B;;;;OAIG;IACG,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQtF;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAIhD;;;;OAIG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAKnE;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAI9C;;;;OAIG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAKhE;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAO/D;;;;;OAKG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,IAAI,GAAG,UAAU,GAAG,SAAS,CAAA;KAAE,GAAG,SAAS,CAAC;CAclH"}