dsh-research-report 0.1.0

package/src/service.ts

@@ -0,0 +1,322 @@
+/**
+ * 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'
+
+// ── Frozen contract (do not edit — see the module doc) ──────────────────────
+
+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 }>
+}
+
+// ── Extended internal vocabulary (not part of the frozen block) ─────────────
+
+/** 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
+}
+
+// ── Session events (typed, merge-extended) ──────────────────────────────────
+
+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[]
+    }
+  }
+}
+
+// ── Background-job kind ─────────────────────────────────────────────────────
+
+declare module '@deepseek-ai/dsh-jobs' {
+  interface JobKindMap {
+    /** Report assembly jobs started by the research_report tool. */
+    'research-report': 'research-report'
+  }
+}
+
+// ── The service ─────────────────────────────────────────────────────────────
+
+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 abstract class ResearchReportService extends Service {
+  constructor(ctx: Context) {
+    super(ctx, 'researchReport')
+  }
+
+  /**
+   * 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>
+}

package/src/tools/evidence-add.ts

@@ -0,0 +1,132 @@
+/**
+ * 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.ts'
+import { ResearchReportError } from '../provider-local.ts'
+import type { LocalResearchReportService } from '../provider-local.ts'
+
+/** 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
+
+/** 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 },
+      },
+    },
+  },
+} as const
+
+/**
+ * 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: LocalResearchReportService) {
+  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 as EvidenceAddValue
+        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 as const,
+          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 as const, error: { code: error.code, message: error.message } }
+        }
+        throw error
+      }
+    },
+  })
+}

package/src/tools/ledger-query.ts

@@ -0,0 +1,191 @@
+/**
+ * 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 { defineTool } from '@deepseek-ai/dsh-tools'
+import type { LocalResearchReportService } from '../provider-local.ts'
+import type { ClaimView, EvidenceView } from '../service.ts'
+
+/** 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
+
+/** The evidence view schema fragment. */
+const evidenceViewSchema = {
+  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'] },
+  },
+} as const
+
+/** The claim view schema fragment. */
+const claimViewSchema = {
+  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 },
+      },
+    },
+  },
+} as const
+
+/** The tool's output schema (all four branches). */
+const OUTPUT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    kind: { type: 'string', required: true, enum: ['evidence', 'claim', 'summary', 'not-found'] },
+    evidence: evidenceViewSchema,
+    claim: claimViewSchema,
+    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' },
+  },
+} as const
+
+/** Render the canonical value as model-facing text. */
+function renderValue(value: LedgerQueryValue): { type: 'text'; text: string }[] {
+  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 !== undefined) lines.push(`  dataset: ${claim.dataset}`)
+      if (claim.verdict === undefined) {
+        lines.push('  verdict: (never verified)')
+      } else {
+        lines.push(`  verdict: ${claim.verdict.status} at ${claim.verdict.at}${claim.verdict.note === undefined ? '' : ` — ${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.
+ */
+export function makeLedgerQueryTool(service: LocalResearchReportService) {
+  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,
+      render: (_args, value) => renderValue(value as LedgerQueryValue),
+    },
+    async execute(args, exec): Promise<LedgerQueryValue> {
+      exec.signal.throwIfAborted()
+      if (args.claimId !== undefined) {
+        const claim = await service.getClaim(args.claimId)
+        return claim === undefined
+          ? { kind: 'not-found', message: `no claim "${args.claimId}" in the ledger` }
+          : { kind: 'claim', claim }
+      }
+      if (args.evidenceId !== undefined) {
+        const evidence = await service.getEvidence(args.evidenceId)
+        return evidence === undefined
+          ? { 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),
+      }
+    },
+  })
+}