dsh-research-report 0.1.0

package/src/assemble.ts

@@ -0,0 +1,302 @@
+/**
+ * Report assembly and sealing — pure functions. The provider owns the ledger
+ * and the filesystem; this module owns request validation, the `report.md`
+ * rendering, the `manifest.json` construction, and the seal hash.
+ *
+ * Sealing: `report.md` is rendered deterministically from the validated
+ * request plus the verdicts; `manifest.json` carries the report hash, every
+ * evidence hash, and the verdicts; the seal hash is the SHA-256 of the exact
+ * manifest bytes. Recomputing the hashes from the sealed directory always
+ * reproduces the seal.
+ *
+ * @module dsh-research-report/assemble
+ */
+
+import { sha256Of } from './ledger.ts'
+import type { EvidenceRecord } from './service.ts'
+import type { AssembleReportRequest, ClaimVerdict } from './service.ts'
+
+/** The manifest schema tag written into every manifest.json. */
+export const MANIFEST_SCHEMA = 'dsh-research-report/v1'
+
+/** Body marker appended after a paragraph per UNVERIFIED claim it cites. */
+export const UNVERIFIED_MARK = '[未核实]'
+
+/** Body marker appended after a paragraph per CONTRADICTED claim it cites. */
+export const CONTRADICTED_MARK = '[与证据矛盾]'
+
+/** A loud assemble-time request validation failure. */
+export class RequestValidationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'RequestValidationError'
+  }
+}
+
+/**
+ * Slug one topic for the report directory name: unicode letters and digits
+ * are kept, everything else folds to `-`; empty slugs fall back to `report`.
+ * @param topic - the report topic.
+ * @returns a filesystem-safe slug of at most 48 characters.
+ */
+export function slugify(topic: string): string {
+  const slug = topic
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, '-')
+    .replace(/^-+|-+$/gu, '')
+    .slice(0, 48)
+  return slug === '' ? 'report' : slug
+}
+
+/**
+ * Format one timestamp as the version directory id `YYYYMMDD-HHmmss` (UTC).
+ * @param at - the time to format.
+ * @returns the directory id.
+ */
+export function versionIdOf(at: Date): string {
+  const pad = (value: number): string => String(value).padStart(2, '0')
+  return [
+    `${at.getUTCFullYear()}${pad(at.getUTCMonth() + 1)}${pad(at.getUTCDate())}`,
+    `${pad(at.getUTCHours())}${pad(at.getUTCMinutes())}${pad(at.getUTCSeconds())}`,
+  ].join('-')
+}
+
+/**
+ * The config fingerprint recorded in every report: a short hash of the
+ * resolved runtime knobs, so two reports sealed under different policies are
+ * distinguishable at a glance.
+ * @param knobs - the policy values that shape assembly output.
+ * @returns 16 hex characters of the knobs' SHA-256.
+ */
+export function configFingerprint(knobs: { maxEvidenceBytes: number; maxEvidencePerReport: number }): string {
+  const stable = JSON.stringify({
+    maxEvidenceBytes: knobs.maxEvidenceBytes,
+    maxEvidencePerReport: knobs.maxEvidencePerReport,
+  })
+  return sha256Of(stable).slice(0, 16)
+}
+
+/**
+ * Validate one assemble request; every violation throws (a loud rejection —
+ * the caller must fix the request, nothing is silently skipped).
+ * @param request - the frozen assemble request.
+ * @param limits - the resolved caps.
+ */
+export function validateAssembleRequest(
+  request: AssembleReportRequest,
+  limits: { maxEvidenceBytes: number; maxEvidencePerReport: number },
+): void {
+  if (request.title.trim() === '') throw new RequestValidationError('title must be non-empty')
+  if (request.topic.trim() === '') throw new RequestValidationError('topic must be non-empty')
+  if (request.sections.length === 0) throw new RequestValidationError('sections must contain at least one section')
+  for (const [index, section] of request.sections.entries()) {
+    if (section.heading.trim() === '') throw new RequestValidationError(`sections[${index}].heading must be non-empty`)
+  }
+  if (request.evidence.length > limits.maxEvidencePerReport) {
+    throw new RequestValidationError(
+      `evidence has ${request.evidence.length} items, above the configured maxEvidencePerReport ${limits.maxEvidencePerReport}`,
+    )
+  }
+  const evidenceIds = new Set<string>()
+  for (const item of request.evidence) {
+    if (item.id.trim() === '') throw new RequestValidationError('evidence id must be non-empty')
+    if (evidenceIds.has(item.id)) throw new RequestValidationError(`duplicate evidence id "${item.id}"`)
+    evidenceIds.add(item.id)
+    const bytes = Buffer.byteLength(item.content, 'utf8')
+    if (bytes > limits.maxEvidenceBytes) {
+      throw new RequestValidationError(
+        `evidence "${item.id}" is ${bytes} bytes, above the configured maxEvidenceBytes ${limits.maxEvidenceBytes}`,
+      )
+    }
+    if (Number.isNaN(Date.parse(item.capturedAt))) {
+      throw new RequestValidationError(`evidence "${item.id}" has an unparseable capturedAt ${JSON.stringify(item.capturedAt)}`)
+    }
+  }
+  const claimIds = new Set<string>()
+  for (const claim of request.claims) {
+    if (claim.id.trim() === '') throw new RequestValidationError('claim id must be non-empty')
+    if (claimIds.has(claim.id)) throw new RequestValidationError(`duplicate claim id "${claim.id}"`)
+    claimIds.add(claim.id)
+    for (const evidenceId of claim.evidenceIds) {
+      if (!evidenceIds.has(evidenceId)) {
+        throw new RequestValidationError(`claim "${claim.id}" binds unknown evidence id "${evidenceId}"`)
+      }
+    }
+  }
+  for (const [sectionIndex, section] of request.sections.entries()) {
+    for (const [paragraphIndex, paragraph] of section.paragraphs.entries()) {
+      for (const claimId of paragraph.claimIds ?? []) {
+        if (!claimIds.has(claimId)) {
+          throw new RequestValidationError(
+            `sections[${sectionIndex}].paragraphs[${paragraphIndex}] cites unregistered claim id "${claimId}"`,
+          )
+        }
+      }
+    }
+  }
+}
+
+/** Everything the renderers need: the validated request plus the outcomes. */
+export interface ReportPlan {
+  /** The validated request. */
+  request: AssembleReportRequest
+  /** Per-claim verdicts (claim registration order). */
+  verdicts: ClaimVerdict[]
+  /** The durable evidence records (hash + provenance). */
+  evidence: EvidenceRecord[]
+  /** ISO-8601 generation time. */
+  generatedAt: string
+  /** The config fingerprint. */
+  fingerprint: string
+  /** The generator version. */
+  pluginVersion: string
+}
+
+/** The status mark used in the appendix table. */
+function statusMark(status: ClaimVerdict['status']): string {
+  switch (status) {
+    case 'verified': return '✅ verified'
+    case 'unverified': return '⚠️ unverified'
+    case 'contradicted': return '❌ contradicted'
+  }
+}
+
+/** Escape a table cell. */
+function cell(text: string): string {
+  return text.replace(/\|/gu, '\\|').replace(/\r?\n/gu, ' ')
+}
+
+/**
+ * Render `report.md`. Unverified/contradicted claims keep a visible body
+ * marker after every paragraph that cites them — nothing is silently passed.
+ * @param plan - the validated request plus verdicts and evidence records.
+ * @returns the report markdown.
+ */
+export function renderReportMarkdown(plan: ReportPlan): string {
+  const verdictByClaim = new Map(plan.verdicts.map(verdict => [verdict.claimId, verdict]))
+  const counts = { verified: 0, unverified: 0, contradicted: 0 }
+  for (const verdict of plan.verdicts) counts[verdict.status] += 1
+
+  const lines: string[] = [
+    `# ${plan.request.title}`,
+    '',
+    `- Topic: ${plan.request.topic}`,
+    `- Generated: ${plan.generatedAt} (UTC)`,
+    `- Claims: ${counts.verified} verified / ${counts.unverified} unverified / ${counts.contradicted} contradicted`,
+    `- Generator: dsh-research-report ${plan.pluginVersion}`,
+    '',
+  ]
+
+  for (const section of plan.request.sections) {
+    lines.push(`## ${section.heading}`, '')
+    for (const paragraph of section.paragraphs) {
+      const marks: string[] = []
+      for (const claimId of paragraph.claimIds ?? []) {
+        const verdict = verdictByClaim.get(claimId)
+        if (verdict?.status === 'unverified') marks.push(UNVERIFIED_MARK)
+        if (verdict?.status === 'contradicted') marks.push(CONTRADICTED_MARK)
+      }
+      lines.push(marks.length === 0 ? paragraph.text : `${paragraph.text} ${marks.join(' ')}`, '')
+    }
+  }
+
+  lines.push('## Appendix A: Claim verification', '')
+  if (plan.verdicts.length === 0) {
+    lines.push('No claims were registered.', '')
+  } else {
+    lines.push('| Claim | Verdict | Evidence | Note |', '|---|---|---|---|')
+    const claimById = new Map(plan.request.claims.map(claim => [claim.id, claim]))
+    for (const verdict of plan.verdicts) {
+      const claim = claimById.get(verdict.claimId)
+      lines.push(
+        `| ${cell(verdict.claimId)} | ${statusMark(verdict.status)} | ${cell((claim?.evidenceIds ?? []).join(', '))} | ${cell(verdict.note ?? '')} |`,
+      )
+    }
+    lines.push('')
+  }
+
+  lines.push('## Appendix B: Evidence list', '')
+  if (plan.evidence.length === 0) {
+    lines.push('No evidence was bound.', '')
+  } else {
+    lines.push('| Id | Title | Origin | SHA-256 | Captured |', '|---|---|---|---|---|')
+    for (const record of plan.evidence) {
+      lines.push(`| ${cell(record.id)} | ${cell(record.title)} | ${cell(record.origin)} | \`${record.hash}\` | ${record.capturedAt} |`)
+    }
+    lines.push('')
+  }
+
+  lines.push(
+    '## Appendix C: Seal',
+    '',
+    `- Manifest: \`manifest.json\` (schema ${MANIFEST_SCHEMA})`,
+    `- Config fingerprint: \`${plan.fingerprint}\``,
+    `- Generated: ${plan.generatedAt} (UTC)`,
+    '',
+  )
+  return `${lines.join('\n').trimEnd()}\n`
+}
+
+/** The durable manifest document (`manifest.json`). */
+export interface ReportManifest {
+  schema: typeof MANIFEST_SCHEMA
+  title: string
+  topic: string
+  generatedAt: string
+  generator: string
+  reportFile: string
+  reportSha256: string
+  configFingerprint: string
+  evidence: Array<{
+    id: string
+    sha256: string
+    origin: string
+    title: string
+    capturedAt: string
+    bytes: number
+  }>
+  claims: Array<{ id: string; text: string; evidenceIds: string[] }>
+  verdicts: ClaimVerdict[]
+}
+
+/**
+ * Build the manifest document for one sealed report. Key order is fixed by
+ * construction so the serialized bytes (and therefore the seal hash) are
+ * deterministic for the same inputs.
+ * @param plan - the validated request plus verdicts and evidence records.
+ * @param reportSha256 - the SHA-256 of the rendered report.md bytes.
+ * @returns the manifest document.
+ */
+export function buildManifest(plan: ReportPlan, reportSha256: string): ReportManifest {
+  return {
+    schema: MANIFEST_SCHEMA,
+    title: plan.request.title,
+    topic: plan.request.topic,
+    generatedAt: plan.generatedAt,
+    generator: `dsh-research-report ${plan.pluginVersion}`,
+    reportFile: 'report.md',
+    reportSha256,
+    configFingerprint: plan.fingerprint,
+    evidence: plan.evidence.map(record => ({
+      id: record.id,
+      sha256: record.hash,
+      origin: record.origin,
+      title: record.title,
+      capturedAt: record.capturedAt,
+      bytes: record.bytes,
+    })),
+    claims: plan.request.claims.map(claim => ({ id: claim.id, text: claim.text, evidenceIds: claim.evidenceIds })),
+    verdicts: plan.verdicts,
+  }
+}
+
+/**
+ * Serialize one manifest to its exact durable bytes. The seal hash is the
+ * SHA-256 of this text.
+ * @param manifest - the manifest document.
+ * @returns the canonical manifest.json content.
+ */
+export function serializeManifest(manifest: ReportManifest): string {
+  return `${JSON.stringify(manifest, null, 2)}\n`
+}

package/src/config.ts

@@ -0,0 +1,97 @@
+/**
+ * Config schema and resolution for `dsh-research-report`. Every tunable is a
+ * validated {@link Config} field changeable from cordis.yml; the resolution
+ * step validates bounds so misconfiguration fails loud at mount.
+ * @module dsh-research-report/config
+ */
+
+import path from 'node:path'
+import z from '@deepseek-ai/schemastery'
+
+/** Raw plugin config — every field optional; {@link resolveConfig} supplies the defaults. */
+export interface Config {
+  /** Master switch. `false` mounts nothing (no service, no tools, no prompt section). */
+  enabled?: boolean
+  /**
+   * Evidence-ledger directory (content-addressed objects + JSONL journals),
+   * resolved against the harness working directory when relative.
+   */
+  ledgerRoot?: string
+  /**
+   * Sealed-report root; each assemble writes
+   * `<reportRoot>/<slug(topic)>/<YYYYMMDD-HHmmss>/{report.md,manifest.json}`.
+   * Resolved against the harness working directory when relative.
+   */
+  reportRoot?: string
+  /** Hard cap on one evidence snapshot's UTF-8 byte size. */
+  maxEvidenceBytes?: number
+  /** Hard cap on how many evidence items one report may bind. */
+  maxEvidencePerReport?: number
+  /** Deadline (ms) for one `ctx.web` fetch during evidence capture. */
+  fetchTimeoutMs?: number
+}
+
+/** Fully resolved config handed to the runtime; roots are absolute paths. */
+export interface ResolvedConfig {
+  readonly enabled: boolean
+  readonly ledgerRoot: string
+  readonly reportRoot: string
+  readonly maxEvidenceBytes: number
+  readonly maxEvidencePerReport: number
+  readonly fetchTimeoutMs: number
+}
+
+/** Schemastery schema: the loader validates and fills defaults before `apply`. */
+export const Config: z<Config> = z.object({
+  enabled: z.boolean().default(true),
+  ledgerRoot: z.string().default('.research-ledger'),
+  reportRoot: z.string().default('research-reports'),
+  maxEvidenceBytes: z.number().default(2 * 1024 * 1024),
+  maxEvidencePerReport: z.number().default(200),
+  fetchTimeoutMs: z.number().default(20_000),
+})
+
+/** Throw unless `value` is a positive safe integer. */
+function assertPositiveInt(name: string, value: number): void {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive safe integer, got ${String(value)}`)
+  }
+}
+
+/**
+ * Resolve one configured root to an absolute path. Relative roots anchor at
+ * the harness working directory (the workspace the deployment runs in), which
+ * keeps the ledger and the sealed reports inside the workspace by default.
+ * @param value - the configured root.
+ * @param name - the config key, for error messages.
+ * @returns the absolute root path.
+ */
+function resolveRoot(value: string, name: string): string {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`${name} must be a non-empty path`)
+  }
+  return path.resolve(value)
+}
+
+/**
+ * Validate raw values and fill explicit defaults. Invalid bounds throw here —
+ * misconfiguration fails loud at mount even without the Schemastery loader.
+ * @param config - raw (possibly partial) plugin config.
+ * @returns the fully resolved config.
+ */
+export function resolveConfig(config: Config = {}): ResolvedConfig {
+  const maxEvidenceBytes = config.maxEvidenceBytes ?? 2 * 1024 * 1024
+  assertPositiveInt('maxEvidenceBytes', maxEvidenceBytes)
+  const maxEvidencePerReport = config.maxEvidencePerReport ?? 200
+  assertPositiveInt('maxEvidencePerReport', maxEvidencePerReport)
+  const fetchTimeoutMs = config.fetchTimeoutMs ?? 20_000
+  assertPositiveInt('fetchTimeoutMs', fetchTimeoutMs)
+  return {
+    enabled: config.enabled ?? true,
+    ledgerRoot: resolveRoot(config.ledgerRoot ?? '.research-ledger', 'ledgerRoot'),
+    reportRoot: resolveRoot(config.reportRoot ?? 'research-reports', 'reportRoot'),
+    maxEvidenceBytes,
+    maxEvidencePerReport,
+    fetchTimeoutMs,
+  }
+}

package/src/gather.ts

@@ -0,0 +1,239 @@
+/**
+ * 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'
+import type { WebRuntime } from '@deepseek-ai/dsh-web'
+
+/** Capture failure codes surfaced to the tools layer. */
+export type CaptureErrorCode =
+  | 'WEB_UNAVAILABLE'
+  | 'FETCH_FAILED'
+  | 'FETCH_STATUS'
+  | 'FETCH_TIMEOUT'
+  | 'ORIGIN_UNREADABLE'
+  | 'ORIGIN_OUTSIDE_WORKSPACE'
+
+/** A loud capture failure with a machine-routable code (also in the message). */
+export class CaptureError extends Error {
+  /** The machine-routable failure code. */
+  readonly code: CaptureErrorCode
+  constructor(code: CaptureErrorCode, message: string) {
+    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: string): boolean {
+  return /^https?:\/\//iu.test(origin)
+}
+
+/** Everything the capture paths need. */
+export interface CaptureDeps {
+  /** The web seam, when the composition mounts it. */
+  web: WebRuntime | undefined
+  /** Fetch deadline (ms). */
+  fetchTimeoutMs: number
+  /** Absolute workspace root; local reads never escape it. */
+  workspaceRoot: string
+}
+
+/** One captured snapshot. */
+export interface CapturedSnapshot {
+  /** The verbatim snapshot bytes as UTF-8 text. */
+  content: string
+  /** The effective origin (final URL after redirects, or the workspace-relative path). */
+  origin: string
+}
+
+/**
+ * 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: string, origin: string): string {
+  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: string, absolute: string): string {
+  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: CaptureDeps, url: string, signal?: AbortSignal): Promise<CapturedSnapshot> {
+  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: CaptureDeps, origin: string): Promise<CapturedSnapshot> {
+  const absolute = resolveWorkspacePath(deps.workspaceRoot, origin)
+  let content: string
+  try {
+    content = await readFile(absolute, 'utf8')
+  } catch (error) {
+    throw new CaptureError('ORIGIN_UNREADABLE', `cannot read ${JSON.stringify(origin)}: ${(error as 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: CaptureDeps, origin: string, signal?: AbortSignal): Promise<CapturedSnapshot> {
+  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 } as const
+
+/** The gather depth knob. */
+export type GatherDepth = keyof typeof GATHER_DEPTH_RESULTS
+
+/** One gathered source and whether its snapshot landed in the ledger. */
+export interface GatherCandidate {
+  /** The source URL. */
+  url: string
+  /** Provider title, when given. */
+  title?: string
+  /** Provider snippet, when given. */
+  snippet?: string
+  /** `captured` entries carry the ledger evidence id. */
+  status: 'captured' | 'uncaptured'
+  /** Ledger evidence id (captured only). */
+  evidenceId?: string
+  /** Why the snapshot could not be captured (uncaptured only). */
+  reason?: string
+}
+
+/** The gather outcome: candidates plus an explicit gap list for the model. */
+export interface GatherOutcome {
+  /** The searched topic. */
+  topic: string
+  /** Every source the search returned, with capture status. */
+  candidates: GatherCandidate[]
+  /** Explicit gaps the model should close before assembling. */
+  gaps: string[]
+}
+
+/**
+ * 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: CaptureDeps,
+  topic: string,
+  depth: GatherDepth,
+  signal: AbortSignal | undefined,
+  register: (input: { title: string; origin: string; content: string }) => Promise<{ id: string }>,
+): Promise<GatherOutcome> {
+  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: GatherCandidate[] = []
+  const gaps: string[] = []
+  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 }
+}