dsh-research-report 0.1.0

package/lib/types/ledger.js

@@ -0,0 +1,276 @@
+/**
+ * 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
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { appendFile, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+/** SHA-256 hex of one UTF-8 string. */
+export function sha256Of(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+/** A loud ledger failure (audit state must never degrade silently). */
+export class LedgerError 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) {
+        // A not-yet-created journal is an empty journal; anything else is loud.
+        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.
+ */
+export class EvidenceLedger {
+    /** 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(() => undefined, () => undefined);
+        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; // object exists — content-addressed storage is immutable
+        }
+        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) {
+            // A concurrent writer may have won the rename; the object is identical
+            // either way (same hash ⇒ same content), so only non-exists errors matter.
+            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 index = await readJournal(this.indexFile);
+            const existing = index.find(line => line.id === id);
+            if (existing !== undefined) {
+                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 !== undefined) {
+                    const same = existing.text === claim.text
+                        && JSON.stringify(existing.evidenceIds) === JSON.stringify(claim.evidenceIds)
+                        && existing.dataset === claim.dataset;
+                    if (!same) {
+                        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) {
+        const index = await this.listEvidence();
+        return index.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) {
+        const claims = await this.listClaims();
+        return claims.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 = 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 === undefined)
+            return undefined;
+        let content;
+        try {
+            content = await readFile(path.join(this.objectsDir, record.hash), 'utf8');
+        }
+        catch (error) {
+            // A deleted object degrades to the `missing` integrity state, never an
+            // unhandled failure; anything else is loud.
+            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' };
+    }
+}
+//# sourceMappingURL=ledger.js.map

package/lib/types/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../src/ledger.ts"],"names":[],"mappings":"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"}

package/lib/types/provider-local.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { ResolvedConfig } from './config.js';
+import type { GatherOutcome } from './gather.js';
+import { ResearchReportService } from './service.js';
+import type { AddEvidenceInput, AssembleContext, AssembleReportRequest, AssembleReportResult, ClaimVerdict, ClaimView, EvidenceIntegrity, EvidenceRecord, EvidenceView, LedgerSummary } from './service.js';
+/** A loud provider failure with a machine-routable code. */
+export declare class ResearchReportError extends Error {
+    /** The machine-routable failure code. */
+    readonly code: 'EVIDENCE_TOO_LARGE' | 'CLAIM_UNKNOWN' | 'LEDGER';
+    constructor(code: ResearchReportError['code'], message: string);
+}
+/**
+ * The local `ctx.researchReport` implementation. Everything durable lives in
+ * the filesystem ledger; the service adds policy (caps), verification, and
+ * sealing on top.
+ */
+export declare class LocalResearchReportService extends ResearchReportService {
+    /** The content-addressed ledger. */
+    private readonly ledger;
+    /** The resolved plugin config. */
+    private readonly config;
+    /** Absolute workspace root for local capture and path display. */
+    private readonly workspaceRoot;
+    /**
+     * @param ctx - the plugin context.
+     * @param config - the resolved plugin config.
+     * @param workspaceRoot - absolute workspace root (the harness cwd).
+     */
+    constructor(ctx: Context, config: ResolvedConfig, workspaceRoot: string);
+    /** The web seam, resolved at call time (HMR-safe; may be absent). */
+    private get web();
+    /** The optional numeric bridge, resolved at call time (never injected). */
+    private get dataQuality();
+    /** Capture dependencies for the gather/capture paths. */
+    private get captureDeps();
+    /**
+     * 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.
+     */
+    addEvidence(input: AddEvidenceInput, session?: Session): Promise<{
+        record: EvidenceRecord;
+        deduplicated: boolean;
+    }>;
+    /**
+     * 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.
+     */
+    captureAndRegister(origin: string, title: string | undefined, signal?: AbortSignal, session?: Session): Promise<{
+        record: EvidenceRecord;
+        deduplicated: boolean;
+    }>;
+    /**
+     * 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.
+     */
+    gather(topic: string, depth: 'quick' | 'standard' | 'deep', signal?: AbortSignal, session?: Session): Promise<GatherOutcome>;
+    /**
+     * 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.
+     */
+    verifyClaim(claimId: string, session?: Session): Promise<ClaimVerdict>;
+    /** Compute the verdict for one claim registration (no writeback). */
+    private verifyRegistration;
+    /**
+     * 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.
+     */
+    assemble(request: AssembleReportRequest, context?: AssembleContext): Promise<AssembleReportResult>;
+    /** Allocate the next versioned report directory for one topic (UTC clock). */
+    private freshReportDir;
+    /**
+     * Read one evidence item (re-hashed on read).
+     * @param evidenceId - the ledger id.
+     * @returns the view, or undefined when unknown.
+     */
+    getEvidence(evidenceId: string): Promise<EvidenceView | undefined>;
+    /**
+     * Read one snapshot's bytes (re-hashed on read).
+     * @param evidenceId - the ledger id.
+     * @returns content plus integrity, or undefined when unknown.
+     */
+    readEvidenceContent(evidenceId: string): Promise<{
+        content: string;
+        integrity: EvidenceIntegrity;
+    } | undefined>;
+    /**
+     * Read one claim with its latest verdict.
+     * @param claimId - the claim id.
+     * @returns the view, or undefined when unknown.
+     */
+    getClaim(claimId: string): Promise<ClaimView | undefined>;
+    /**
+     * List every registered evidence item (re-hashed on read).
+     * @returns all evidence views in registration order.
+     */
+    listEvidence(): Promise<EvidenceView[]>;
+    /**
+     * List every registered claim with its latest verdict.
+     * @returns all claim views in registration order.
+     */
+    listClaims(): Promise<ClaimView[]>;
+    /**
+     * Aggregate ledger counts (evidence re-hashed for the tamper count).
+     * @returns the summary.
+     */
+    summarize(): Promise<LedgerSummary>;
+}
+//# sourceMappingURL=provider-local.d.ts.map

package/lib/types/provider-local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-local.d.ts","sourceRoot":"","sources":["../../src/provider-local.ts"],"names":[],"mappings":"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"}