dsh-research-report 0.1.0

package/lib/types/assemble.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 type { EvidenceRecord } from './service.js';
+import type { AssembleReportRequest, ClaimVerdict } from './service.js';
+/** The manifest schema tag written into every manifest.json. */
+export declare const MANIFEST_SCHEMA = "dsh-research-report/v1";
+/** Body marker appended after a paragraph per UNVERIFIED claim it cites. */
+export declare const UNVERIFIED_MARK = "[\u672A\u6838\u5B9E]";
+/** Body marker appended after a paragraph per CONTRADICTED claim it cites. */
+export declare const CONTRADICTED_MARK = "[\u4E0E\u8BC1\u636E\u77DB\u76FE]";
+/** A loud assemble-time request validation failure. */
+export declare class RequestValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare function slugify(topic: string): string;
+/**
+ * Format one timestamp as the version directory id `YYYYMMDD-HHmmss` (UTC).
+ * @param at - the time to format.
+ * @returns the directory id.
+ */
+export declare function versionIdOf(at: Date): string;
+/**
+ * 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 declare function configFingerprint(knobs: {
+    maxEvidenceBytes: number;
+    maxEvidencePerReport: number;
+}): string;
+/**
+ * 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 declare function validateAssembleRequest(request: AssembleReportRequest, limits: {
+    maxEvidenceBytes: number;
+    maxEvidencePerReport: number;
+}): void;
+/** 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;
+}
+/**
+ * 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 declare function renderReportMarkdown(plan: ReportPlan): string;
+/** 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 declare function buildManifest(plan: ReportPlan, reportSha256: string): ReportManifest;
+/**
+ * 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 declare function serializeManifest(manifest: ReportManifest): string;
+//# sourceMappingURL=assemble.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../src/assemble.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAEvE,gEAAgE;AAChE,eAAO,MAAM,eAAe,2BAA2B,CAAA;AAEvD,4EAA4E;AAC5E,eAAO,MAAM,eAAe,yBAAU,CAAA;AAEtC,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,qCAAY,CAAA;AAE1C,uDAAuD;AACvD,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ7C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,IAAI,GAAG,MAAM,CAM5C;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IAAE,gBAAgB,EAAE,MAAM,CAAC;IAAC,oBAAoB,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAM3G;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE;IAAE,gBAAgB,EAAE,MAAM,CAAC;IAAC,oBAAoB,EAAE,MAAM,CAAA;CAAE,GACjE,IAAI,CAiDN;AAED,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,OAAO,EAAE,qBAAqB,CAAA;IAC9B,qDAAqD;IACrD,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,wDAAwD;IACxD,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAA;IACnB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAA;IACnB,6BAA6B;IAC7B,aAAa,EAAE,MAAM,CAAA;CACtB;AAgBD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CA+D7D;AAED,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,eAAe,CAAA;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,MAAM,CAAA;IACpB,iBAAiB,EAAE,MAAM,CAAA;IACzB,QAAQ,EAAE,KAAK,CAAC;QACd,EAAE,EAAE,MAAM,CAAA;QACV,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;QACd,KAAK,EAAE,MAAM,CAAA;QACb,UAAU,EAAE,MAAM,CAAA;QAClB,KAAK,EAAE,MAAM,CAAA;KACd,CAAC,CAAA;IACF,MAAM,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAA;IAClE,QAAQ,EAAE,YAAY,EAAE,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,GAAG,cAAc,CAqBpF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAElE"}

package/lib/types/assemble.js

@@ -0,0 +1,239 @@
+/**
+ * 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.js";
+/** 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) {
+        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) {
+    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) {
+    const pad = (value) => 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) {
+    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, limits) {
+    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();
+    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();
+    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}"`);
+                }
+            }
+        }
+    }
+}
+/** The status mark used in the appendix table. */
+function statusMark(status) {
+    switch (status) {
+        case 'verified': return '✅ verified';
+        case 'unverified': return '⚠️ unverified';
+        case 'contradicted': return '❌ contradicted';
+    }
+}
+/** Escape a table cell. */
+function cell(text) {
+    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) {
+    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 = [
+        `# ${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 = [];
+            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`;
+}
+/**
+ * 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, reportSha256) {
+    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) {
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+//# sourceMappingURL=assemble.js.map

package/lib/types/assemble.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.js","sourceRoot":"","sources":["../../src/assemble.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAItC,gEAAgE;AAChE,MAAM,CAAC,MAAM,eAAe,GAAG,wBAAwB,CAAA;AAEvD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAA;AAEtC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAA;AAE1C,uDAAuD;AACvD,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAA;IACtC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,MAAM,IAAI,GAAG,KAAK;SACf,IAAI,EAAE;SACN,WAAW,EAAE;SACb,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC;SAChC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;SACxB,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IACf,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAA;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,EAAQ;IAClC,MAAM,GAAG,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IACrE,OAAO;QACL,GAAG,EAAE,CAAC,cAAc,EAAE,GAAG,GAAG,CAAC,EAAE,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC,EAAE;QAC3E,GAAG,GAAG,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,aAAa,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,aAAa,EAAE,CAAC,EAAE;KAC/E,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAiE;IACjG,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC;QAC5B,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;QACxC,oBAAoB,EAAE,KAAK,CAAC,oBAAoB;KACjD,CAAC,CAAA;IACF,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;AACtC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAA8B,EAC9B,MAAkE;IAElE,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,MAAM,IAAI,sBAAsB,CAAC,yBAAyB,CAAC,CAAA;IAC5F,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,MAAM,IAAI,sBAAsB,CAAC,yBAAyB,CAAC,CAAA;IAC5F,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,sBAAsB,CAAC,4CAA4C,CAAC,CAAA;IACjH,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;QAC1D,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,MAAM,IAAI,sBAAsB,CAAC,YAAY,KAAK,6BAA6B,CAAC,CAAA;IACrH,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC,oBAAoB,EAAE,CAAC;QAC1D,MAAM,IAAI,sBAAsB,CAC9B,gBAAgB,OAAO,CAAC,QAAQ,CAAC,MAAM,qDAAqD,MAAM,CAAC,oBAAoB,EAAE,CAC1H,CAAA;IACH,CAAC;IACD,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAA;IACrC,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACpC,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,MAAM,IAAI,sBAAsB,CAAC,+BAA+B,CAAC,CAAA;QAC5F,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,MAAM,IAAI,sBAAsB,CAAC,0BAA0B,IAAI,CAAC,EAAE,GAAG,CAAC,CAAA;QACpG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QACxB,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QACrD,IAAI,KAAK,GAAG,MAAM,CAAC,gBAAgB,EAAE,CAAC;YACpC,MAAM,IAAI,sBAAsB,CAC9B,aAAa,IAAI,CAAC,EAAE,QAAQ,KAAK,iDAAiD,MAAM,CAAC,gBAAgB,EAAE,CAC5G,CAAA;QACH,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;YAC9C,MAAM,IAAI,sBAAsB,CAAC,aAAa,IAAI,CAAC,EAAE,mCAAmC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;QAC5H,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAA;IAClC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnC,IAAI,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,MAAM,IAAI,sBAAsB,CAAC,4BAA4B,CAAC,CAAA;QAC1F,IAAI,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAAE,MAAM,IAAI,sBAAsB,CAAC,uBAAuB,KAAK,CAAC,EAAE,GAAG,CAAC,CAAA;QAChG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QACtB,KAAK,MAAM,UAAU,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;YAC3C,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;gBACjC,MAAM,IAAI,sBAAsB,CAAC,UAAU,KAAK,CAAC,EAAE,gCAAgC,UAAU,GAAG,CAAC,CAAA;YACnG,CAAC;QACH,CAAC;IACH,CAAC;IACD,KAAK,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;QACjE,KAAK,MAAM,CAAC,cAAc,EAAE,SAAS,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;YACvE,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;gBAC/C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC3B,MAAM,IAAI,sBAAsB,CAC9B,YAAY,YAAY,gBAAgB,cAAc,kCAAkC,OAAO,GAAG,CACnG,CAAA;gBACH,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAkBD,kDAAkD;AAClD,SAAS,UAAU,CAAC,MAA8B;IAChD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,UAAU,CAAC,CAAC,OAAO,YAAY,CAAA;QACpC,KAAK,YAAY,CAAC,CAAC,OAAO,eAAe,CAAA;QACzC,KAAK,cAAc,CAAC,CAAC,OAAO,gBAAgB,CAAA;IAC9C,CAAC;AACH,CAAC;AAED,2BAA2B;AAC3B,SAAS,IAAI,CAAC,IAAY;IACxB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAA;AAC5D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAgB;IACnD,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IACxF,MAAM,MAAM,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAA;IAC9D,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ;QAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAEhE,MAAM,KAAK,GAAa;QACtB,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE;QACzB,EAAE;QACF,YAAY,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE;QAChC,gBAAgB,IAAI,CAAC,WAAW,QAAQ;QACxC,aAAa,MAAM,CAAC,QAAQ,eAAe,MAAM,CAAC,UAAU,iBAAiB,MAAM,CAAC,YAAY,eAAe;QAC/G,oCAAoC,IAAI,CAAC,aAAa,EAAE;QACxD,EAAE;KACH,CAAA;IAED,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QAC5C,KAAK,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,CAAC,CAAA;QACvC,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YAC3C,MAAM,KAAK,GAAa,EAAE,CAAA;YAC1B,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;gBAC/C,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;gBAC3C,IAAI,OAAO,EAAE,MAAM,KAAK,YAAY;oBAAE,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAA;gBACjE,IAAI,OAAO,EAAE,MAAM,KAAK,cAAc;oBAAE,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAA;YACvE,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;QAC9F,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,mCAAmC,EAAE,EAAE,CAAC,CAAA;IACnD,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,4BAA4B,EAAE,EAAE,CAAC,CAAA;IAC9C,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,uCAAuC,EAAE,mBAAmB,CAAC,CAAA;QACxE,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAA;QAC9E,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACpC,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;YAC5C,KAAK,CAAC,IAAI,CACR,KAAK,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,EAAE,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,IAAI,CAC9I,CAAA;QACH,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAChB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,8BAA8B,EAAE,EAAE,CAAC,CAAA;IAC9C,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,wBAAwB,EAAE,EAAE,CAAC,CAAA;IAC1C,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,8CAA8C,EAAE,uBAAuB,CAAC,CAAA;QACnF,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,MAAM,CAAC,IAAI,QAAQ,MAAM,CAAC,UAAU,IAAI,CAAC,CAAA;QACnI,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAChB,CAAC;IAED,KAAK,CAAC,IAAI,CACR,qBAAqB,EACrB,EAAE,EACF,yCAAyC,eAAe,GAAG,EAC3D,2BAA2B,IAAI,CAAC,WAAW,IAAI,EAC/C,gBAAgB,IAAI,CAAC,WAAW,QAAQ,EACxC,EAAE,CACH,CAAA;IACD,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,IAAI,CAAA;AAC1C,CAAC;AAwBD;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,IAAgB,EAAE,YAAoB;IAClE,OAAO;QACL,MAAM,EAAE,eAAe;QACvB,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;QACzB,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;QACzB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,SAAS,EAAE,uBAAuB,IAAI,CAAC,aAAa,EAAE;QACtD,UAAU,EAAE,WAAW;QACvB,YAAY;QACZ,iBAAiB,EAAE,IAAI,CAAC,WAAW;QACnC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACrC,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,MAAM,EAAE,MAAM,CAAC,IAAI;YACnB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC,CAAC;QACH,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;QAC9G,QAAQ,EAAE,IAAI,CAAC,QAAQ;KACxB,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAwB;IACxD,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAA;AACjD,CAAC"}

package/lib/types/config.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 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 declare const Config: z<Config>;
+/**
+ * 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 declare function resolveConfig(config?: Config): ResolvedConfig;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAExC,6FAA6F;AAC7F,MAAM,WAAW,MAAM;IACrB,uFAAuF;IACvF,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,+DAA+D;IAC/D,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAChC;AAED,kFAAkF;AAClF,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAO3B,CAAA;AAwBF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,GAAE,MAAW,GAAG,cAAc,CAejE"}

package/lib/types/config.js

@@ -0,0 +1,60 @@
+/**
+ * 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';
+/** Schemastery schema: the loader validates and fills defaults before `apply`. */
+export const 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, value) {
+    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, name) {
+    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 = {}) {
+    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,
+    };
+}
+//# sourceMappingURL=config.js.map

package/lib/types/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAmCxC,kFAAkF;AAClF,MAAM,CAAC,MAAM,MAAM,GAAc,CAAC,CAAC,MAAM,CAAC;IACxC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IAClC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,kBAAkB,CAAC;IAClD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,kBAAkB,CAAC;IAClD,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IACrD,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC;IAC7C,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC;CAC3C,CAAC,CAAA;AAEF,uDAAuD;AACvD,SAAS,iBAAiB,CAAC,IAAY,EAAE,KAAa;IACpD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,SAAS,CAAC,GAAG,IAAI,yCAAyC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IACtF,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,KAAa,EAAE,IAAY;IAC9C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,MAAM,IAAI,SAAS,CAAC,GAAG,IAAI,2BAA2B,CAAC,CAAA;IACzD,CAAC;IACD,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAC5B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,SAAiB,EAAE;IAC/C,MAAM,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAAA;IACnE,iBAAiB,CAAC,kBAAkB,EAAE,gBAAgB,CAAC,CAAA;IACvD,MAAM,oBAAoB,GAAG,MAAM,CAAC,oBAAoB,IAAI,GAAG,CAAA;IAC/D,iBAAiB,CAAC,sBAAsB,EAAE,oBAAoB,CAAC,CAAA;IAC/D,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,IAAI,MAAM,CAAA;IACtD,iBAAiB,CAAC,gBAAgB,EAAE,cAAc,CAAC,CAAA;IACnD,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;QAC/B,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,UAAU,IAAI,kBAAkB,EAAE,YAAY,CAAC;QAC9E,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,UAAU,IAAI,kBAAkB,EAAE,YAAY,CAAC;QAC9E,gBAAgB;QAChB,oBAAoB;QACpB,cAAc;KACf,CAAA;AACH,CAAC"}

package/lib/types/gather.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 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 declare class CaptureError extends Error {
+    /** The machine-routable failure code. */
+    readonly code: CaptureErrorCode;
+    constructor(code: CaptureErrorCode, message: string);
+}
+/** Whether the origin is an HTTP(S) URL (vs a workspace path). */
+export declare function isUrlOrigin(origin: string): boolean;
+/** 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 declare function resolveWorkspacePath(workspaceRoot: string, origin: string): string;
+/** Relativize an absolute in-workspace path for display/durable records. */
+export declare function toWorkspaceRelative(workspaceRoot: string, absolute: string): string;
+/**
+ * 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 declare function captureFromWeb(deps: CaptureDeps, url: string, signal?: AbortSignal): Promise<CapturedSnapshot>;
+/**
+ * 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 declare function captureFromFile(deps: CaptureDeps, origin: string): Promise<CapturedSnapshot>;
+/**
+ * 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 declare function captureSnapshot(deps: CaptureDeps, origin: string, signal?: AbortSignal): Promise<CapturedSnapshot>;
+/** Search depth → how many sources are fetched for snapshot capture. */
+export declare const GATHER_DEPTH_RESULTS: {
+    readonly quick: 3;
+    readonly standard: 5;
+    readonly deep: 8;
+};
+/** 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 declare function gatherCandidates(deps: CaptureDeps, topic: string, depth: GatherDepth, signal: AbortSignal | undefined, register: (input: {
+    title: string;
+    origin: string;
+    content: string;
+}) => Promise<{
+    id: string;
+}>): Promise<GatherOutcome>;
+//# sourceMappingURL=gather.d.ts.map

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

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