dsh-research-report 0.1.0

package/lib/types/service.d.ts

@@ -0,0 +1,302 @@
+/**
+ * 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
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+export interface ReportSectionInput {
+    heading: string;
+    /** Paragraphs; each claim string may carry citations. */
+    paragraphs: Array<{
+        text: string;
+        claimIds?: string[];
+    }>;
+}
+export interface EvidenceInput {
+    id: string;
+    title: string;
+    /** Where the evidence came from (URL or workspace path). */
+    origin: string;
+    /** Verbatim content snapshot used for byte-level checks. */
+    content: string;
+    /** ISO-8601 time the snapshot was captured. */
+    capturedAt: string;
+}
+export interface AssembleReportRequest {
+    title: string;
+    topic: string;
+    evidence: EvidenceInput[];
+    sections: ReportSectionInput[];
+    /** Every claim id referenced in sections must be registered here. */
+    claims: Array<{
+        id: string;
+        text: string;
+        evidenceIds: string[];
+    }>;
+}
+export interface AssembleReportResult {
+    /** Workspace path of the sealed report directory (report.md + manifest.json). */
+    reportDir: string;
+    /** SHA-256 content hash of manifest.json. */
+    sealHash: string;
+    /** Per-claim verification verdicts. */
+    verdicts: Array<{
+        claimId: string;
+        status: 'verified' | 'unverified' | 'contradicted';
+        note?: string;
+    }>;
+}
+/** The three-state verification verdict of one claim. */
+export type VerdictStatus = 'verified' | 'unverified' | 'contradicted';
+/** One claim's verification outcome (same fields as the frozen result item). */
+export interface ClaimVerdict {
+    /** The claim this verdict belongs to. */
+    claimId: string;
+    /** Byte-level (and optional numeric-bridge) outcome. */
+    status: VerdictStatus;
+    /** Human-readable evidence note (missing citations, contradiction detail, …). */
+    note?: string;
+}
+/**
+ * Claim registration accepted by the tools layer: the frozen claim shape plus
+ * the OPTIONAL numeric-bridge extension consumed when the claim's numbers cite
+ * a structured workspace dataset and `ctx.dataQuality` is mounted.
+ */
+export interface ClaimRegistration {
+    /** Stable claim id chosen by the caller. */
+    id: string;
+    /** The claim text; numbers and quoted spans are byte-checked against evidence. */
+    text: string;
+    /** Ledger evidence ids this claim binds to. */
+    evidenceIds: string[];
+    /** Workspace-relative dataset path (CSV/JSON) for the optional numeric bridge. */
+    dataset?: string;
+    /** Dataset citations for `ctx.dataQuality.verifyCitations` (requires `dataset`). */
+    citations?: Array<{
+        /** Stable id chosen by the caller, echoed back in results. */
+        id: string;
+        /** JSON-path-ish locator, e.g. "rows[3].nav". */
+        path: string;
+        /** The value as cited in the claim. */
+        value: number | string;
+        /** Optional relative tolerance for numeric comparison, e.g. 0.01 = 1%. */
+        tolerance?: number;
+    }>;
+}
+/** Input for registering one evidence snapshot in the ledger. */
+export interface AddEvidenceInput {
+    /** Caller-chosen evidence id; omitted derives a content-addressed `ev-<hash12>` id. */
+    id?: string;
+    /** Display title. */
+    title: string;
+    /** Where the evidence came from (URL or workspace path). */
+    origin: string;
+    /** Verbatim content snapshot used for byte-level checks. */
+    content: string;
+    /** ISO-8601 capture time; defaults to the registration clock. */
+    capturedAt?: string;
+}
+/** Durable ledger facts of one evidence snapshot. */
+export interface EvidenceRecord {
+    /** Ledger id (caller-chosen or `ev-<hash12>`). */
+    id: string;
+    /** SHA-256 hex of the snapshot content (the object address). */
+    hash: string;
+    /** Display title. */
+    title: string;
+    /** Where the evidence came from (URL or workspace path). */
+    origin: string;
+    /** ISO-8601 capture time. */
+    capturedAt: string;
+    /** UTF-8 byte length of the snapshot. */
+    bytes: number;
+}
+/** Integrity state of a stored snapshot, recomputed on every read. */
+export type EvidenceIntegrity = 'ok' | 'tampered' | 'missing';
+/** Read view of one ledger evidence item; content stays in the object store. */
+export interface EvidenceView extends EvidenceRecord {
+    /** `ok` when the object bytes still hash to the indexed value. */
+    integrity: EvidenceIntegrity;
+}
+/** Stored verdict record (latest write wins on read). */
+export interface StoredVerdict extends ClaimVerdict {
+    /** ISO-8601 time the verdict was written. */
+    at: string;
+}
+/** Read view of one registered claim and its latest verdict, when any. */
+export interface ClaimView {
+    /** The claim id. */
+    id: string;
+    /** The claim text. */
+    text: string;
+    /** Bound evidence ids. */
+    evidenceIds: string[];
+    /** Optional numeric-bridge dataset citation carried from registration. */
+    dataset?: string;
+    /** Latest stored verdict; absent when the claim was never verified. */
+    verdict?: StoredVerdict;
+}
+/** Aggregate ledger counts for summary queries. */
+export interface LedgerSummary {
+    /** Registered evidence count. */
+    evidenceCount: number;
+    /** Registered claim count. */
+    claimCount: number;
+    /** Claims carrying a stored verdict. */
+    verdictCount: number;
+    /** Evidence items whose object failed the read-time re-hash. */
+    tamperedCount: number;
+}
+/** Optional assemble-time context: the owning session for event logging. */
+export interface AssembleContext {
+    /** The session whose log receives the research-report/* events, when known. */
+    session?: import('@deepseek-ai/dsh-session').Session;
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * One evidence snapshot entered the ledger (id ↔ content hash binding).
+         * Log-only audit record; the ledger itself is the durable source of truth.
+         * @mode emit
+         * @param id - ledger evidence id.
+         * @param hash - SHA-256 of the snapshot bytes.
+         * @param origin - where the evidence came from (URL or workspace path).
+         * @param title - display title.
+         * @param capturedAt - ISO-8601 capture time.
+         * @param bytes - UTF-8 byte length.
+         * @param deduplicated - true when the content was already stored.
+         */
+        'research-report/evidence': {
+            id: string;
+            hash: string;
+            origin: string;
+            title: string;
+            capturedAt: string;
+            bytes: number;
+            deduplicated: boolean;
+        };
+        /**
+         * One claim's verification verdict was written back to the ledger.
+         * Log-only audit record; `verdicts.jsonl` is the durable source of truth.
+         * @mode emit
+         * @param claimId - the verified claim.
+         * @param status - verified | unverified | contradicted.
+         * @param note - human-readable evidence note.
+         * @param evidenceIds - the bindings the verdict was computed over.
+         */
+        'research-report/verify': {
+            claimId: string;
+            status: VerdictStatus;
+            note?: string;
+            evidenceIds: string[];
+        };
+        /**
+         * A report directory was sealed (manifest written, hash computed).
+         * Log-only audit record; `manifest.json` is the durable source of truth.
+         * @mode emit
+         * @param reportDir - workspace path of the sealed report directory.
+         * @param sealHash - SHA-256 of manifest.json.
+         * @param topic - the report topic.
+         * @param title - the report title.
+         * @param verdicts - the per-claim outcomes the seal covers.
+         */
+        'research-report/seal': {
+            reportDir: string;
+            sealHash: string;
+            topic: string;
+            title: string;
+            verdicts: ClaimVerdict[];
+        };
+    }
+}
+declare module '@deepseek-ai/dsh-jobs' {
+    interface JobKindMap {
+        /** Report assembly jobs started by the research_report tool. */
+        'research-report': 'research-report';
+    }
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        researchReport: ResearchReportService;
+    }
+}
+/**
+ * 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.
+ */
+export declare abstract class ResearchReportService extends Service {
+    constructor(ctx: Context);
+    /**
+     * Assemble and seal one report.
+     * @param request - the frozen assemble request (see the module-level block).
+     * @returns the sealed directory, its seal hash, and the per-claim verdicts.
+     */
+    abstract assemble(request: AssembleReportRequest): Promise<AssembleReportResult>;
+    /**
+     * Register one evidence snapshot (content-addressed; same content dedupes).
+     * @param input - the snapshot and its provenance.
+     * @returns the durable record and whether this call created it.
+     */
+    abstract addEvidence(input: AddEvidenceInput): Promise<{
+        record: EvidenceRecord;
+        deduplicated: boolean;
+    }>;
+    /**
+     * Re-run verification for one registered claim and write back the verdict.
+     * @param claimId - the claim to verify.
+     * @returns the fresh verdict.
+     */
+    abstract verifyClaim(claimId: string): Promise<ClaimVerdict>;
+    /**
+     * Read one evidence item; the snapshot is re-hashed on every read.
+     * @param evidenceId - the ledger id.
+     * @returns the view (with integrity), or undefined when unknown.
+     */
+    abstract getEvidence(evidenceId: string): Promise<EvidenceView | undefined>;
+    /**
+     * Read the raw snapshot bytes of one evidence item (verification path).
+     * @param evidenceId - the ledger id.
+     * @returns the content plus integrity state, or undefined when unknown.
+     */
+    abstract readEvidenceContent(evidenceId: string): Promise<{
+        content: string;
+        integrity: EvidenceIntegrity;
+    } | undefined>;
+    /**
+     * Read one registered claim with its latest verdict.
+     * @param claimId - the claim id.
+     * @returns the view, or undefined when unknown.
+     */
+    abstract getClaim(claimId: string): Promise<ClaimView | undefined>;
+    /**
+     * List every registered evidence item (re-hashed on read).
+     * @returns all evidence views in registration order.
+     */
+    abstract listEvidence(): Promise<EvidenceView[]>;
+    /**
+     * List every registered claim.
+     * @returns all claim views in registration order.
+     */
+    abstract listClaims(): Promise<ClaimView[]>;
+    /**
+     * Aggregate ledger counts.
+     * @returns the summary (evidence/claim/verdict/tamper counts).
+     */
+    abstract summarize(): Promise<LedgerSummary>;
+}
+//# sourceMappingURL=service.d.ts.map

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

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

package/lib/types/service.js

@@ -0,0 +1,31 @@
+/**
+ * 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
+ */
+import { Service } from '@deepseek-ai/cordis';
+/**
+ * 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.
+ */
+export class ResearchReportService extends Service {
+    constructor(ctx) {
+        super(ctx, 'researchReport');
+    }
+}
+//# sourceMappingURL=service.js.map

package/lib/types/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAW,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAwOtD;;;;;;;GAOG;AACH,MAAM,OAAgB,qBAAsB,SAAQ,OAAO;IACzD,YAAY,GAAY;QACtB,KAAK,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAA;IAC9B,CAAC;CA6DF"}

package/lib/types/tools/evidence-add.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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
+ */
+import type { LocalResearchReportService } from '../provider-local.js';
+/** The canonical success value. */
+interface EvidenceAddSuccess {
+    ok: true;
+    evidenceId: string;
+    hash: string;
+    bytes: number;
+    title: string;
+    origin: string;
+    capturedAt: string;
+    deduplicated: boolean;
+}
+/** The canonical domain-failure value (capability absence still throws). */
+interface EvidenceAddFailure {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+/** The `evidence_add` canonical value. */
+export type EvidenceAddValue = EvidenceAddSuccess | EvidenceAddFailure;
+/**
+ * Build the `evidence_add` tool bound to the local provider.
+ * @param service - the local research-report provider.
+ * @returns the tool definition.
+ */
+export declare function makeEvidenceAddTool(service: LocalResearchReportService): import("@deepseek-ai/dsh-tools").ToolDefinition;
+export {};
+//# sourceMappingURL=evidence-add.d.ts.map

package/lib/types/tools/evidence-add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-add.d.ts","sourceRoot":"","sources":["../../../src/tools/evidence-add.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAA;AAEtE,mCAAmC;AACnC,UAAU,kBAAkB;IAC1B,EAAE,EAAE,IAAI,CAAA;IACR,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,OAAO,CAAA;CACtB;AAED,4EAA4E;AAC5E,UAAU,kBAAkB;IAC1B,EAAE,EAAE,KAAK,CAAA;IACT,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CACzC;AAED,0CAA0C;AAC1C,MAAM,MAAM,gBAAgB,GAAG,kBAAkB,GAAG,kBAAkB,CAAA;AA0BtE;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,mDAqEtE"}

package/lib/types/tools/evidence-add.js

@@ -0,0 +1,107 @@
+/**
+ * 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
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { CaptureError } from "../gather.js";
+import { ResearchReportError } from "../provider-local.js";
+/** The tool's output schema (both branches). */
+const OUTPUT_SCHEMA = {
+    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.
+ */
+export 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,
+            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 !== undefined
+                    ? 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) {
+                // The web capability being absent for a URL origin is a deployment
+                // fact: fail loudly (isError) so the model stops retrying URLs.
+                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;
+            }
+        },
+    });
+}
+//# sourceMappingURL=evidence-add.js.map

package/lib/types/tools/evidence-add.js.map

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

package/lib/types/tools/ledger-query.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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
+ */
+import type { LocalResearchReportService } from '../provider-local.js';
+import type { ClaimView, EvidenceView } from '../service.js';
+/** The evidence branch of the canonical value. */
+interface EvidenceBranch {
+    kind: 'evidence';
+    evidence: EvidenceView;
+}
+/** The claim branch of the canonical value. */
+interface ClaimBranch {
+    kind: 'claim';
+    claim: ClaimView;
+}
+/** The summary branch (no id given). */
+interface SummaryBranch {
+    kind: 'summary';
+    evidenceCount: number;
+    claimCount: number;
+    verdictCount: number;
+    tamperedCount: number;
+    evidenceIds: string[];
+    claimIds: string[];
+}
+/** The not-found branch (unknown id — query semantics, not an error). */
+interface NotFoundBranch {
+    kind: 'not-found';
+    message: string;
+}
+/** The `ledger_query` canonical value. */
+export type LedgerQueryValue = EvidenceBranch | ClaimBranch | SummaryBranch | NotFoundBranch;
+/**
+ * Build the `ledger_query` tool bound to the local provider.
+ * @param service - the local research-report provider.
+ * @returns the tool definition.
+ */
+export declare function makeLedgerQueryTool(service: LocalResearchReportService): import("@deepseek-ai/dsh-tools").ToolDefinition;
+export {};
+//# sourceMappingURL=ledger-query.d.ts.map

package/lib/types/tools/ledger-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-query.d.ts","sourceRoot":"","sources":["../../../src/tools/ledger-query.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAA;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAE5D,kDAAkD;AAClD,UAAU,cAAc;IACtB,IAAI,EAAE,UAAU,CAAA;IAChB,QAAQ,EAAE,YAAY,CAAA;CACvB;AAED,+CAA+C;AAC/C,UAAU,WAAW;IACnB,IAAI,EAAE,OAAO,CAAA;IACb,KAAK,EAAE,SAAS,CAAA;CACjB;AAED,wCAAwC;AACxC,UAAU,aAAa;IACrB,IAAI,EAAE,SAAS,CAAA;IACf,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,yEAAyE;AACzE,UAAU,cAAc;IACtB,IAAI,EAAE,WAAW,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,0CAA0C;AAC1C,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG,WAAW,GAAG,aAAa,GAAG,cAAc,CAAA;AAuG5F;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,mDA0CtE"}