/** * EvidencePack schema + total decoder (T1, docs/plans/investigate-pipeline * PRD AC-6; ADR-0013 §7). * * The EvidencePack is the self-contained deliverable of an Investigation * (CONTEXT.md glossary): question, sub-queries, sources with per-source * content hashes and extracted passages, and a coverage block. The pack is * data, not prose — agent-synthesis is the contract; `--synthesize` (T7) * attaches a `brief` additively and is not part of this schema. * * This module declares the pack type, its total decoder, and the * contentSha256 shape predicate. It imports NOTHING from other src modules * (self-contained by ticket contract; hashing itself lands in T5 — this * module only validates hash *shape*). * * Decoder discipline mirrors capabilities/reader.ts exactly: * - accepts `unknown`, returns the pack or `null`, never throws, * never trusts a generic cast; * - reject primitives and arrays at the top level; * - `schemaVersion` MUST be the literal number 1 (rejects "1", 1.5, * bigints, any future version); * - `title: null` is a valid decoded value (reader parity); * - optional fields preserved verbatim when present. */ /** `[start, end)` character offsets into the source `content` string. */ export type CharRange = readonly [number, number]; /** * One extracted passage. `quote` is pinned to the content by `charRange`: * `content.slice(...charRange) === quote` for every passage (D4). The pin * is enforced where content is available (assembly in T5, extraction in * T3); the decoder enforces the shape so a decoded pack is at least * structurally sound. */ export interface EvidencePassage { readonly quote: string; readonly charRange: CharRange; } /** One read source: reader-envelope fields + passages. */ export interface EvidenceSource { readonly url: string; /** The URL the Reader actually fetched (provider rewrite possible). */ readonly finalUrl: string; /** Page title if the provider returned one; `null` if absent (reader parity). */ readonly title: string | null; /** ISO-8601 UTC Z timestamp captured when the read resolved (D5). */ readonly fetchedAt: string; /** Provider id that surfaced the source (search-arm winner). */ readonly provider: string; /** Mirrors the read `format`; `"markdown"` or `"text"`. */ readonly contentFormat: "markdown" | "text"; /** Lowercase hex SHA-256 of the UTF-8 normalized content string (D5). */ readonly contentSha256: string; readonly passages: readonly EvidencePassage[]; } /** Coverage block: how much of the planned grid actually produced evidence. */ export interface EvidenceCoverage { /** Number of planned sub-queries. */ readonly subQueries: number; /** Number of search arms actually used. */ readonly armsUsed: number; /** Number of post-cluster candidate sources surfaced. */ readonly sourcesConsidered: number; /** Number of sources whose read resolved successfully. */ readonly sourcesRead: number; /** Count of search arms + reads served warm from cache (D5). */ readonly cacheHits: number; /** * Sources surfaced but not read, each with a reason code only — * redacted, no error prose crossing the interface (house rule, D5). */ readonly unread: readonly { readonly url: string; readonly reason: string; }[]; } /** The self-contained Investigation deliverable (PRD AC-6). */ export interface EvidencePack { readonly schemaVersion: 1; readonly question: string; readonly subQueries: readonly string[]; readonly sources: readonly EvidenceSource[]; readonly coverage: EvidenceCoverage; /** * investigate-verify lane T2 (PRD AC-6): the additive claim- * corroboration block. ABSENT on question-mode packs (byte-identity * pin); present only when `investigate --verify` assembled the pack. */ readonly verify?: VerifyBlock; } /** The deterministic verdict vocabulary (cue heuristic, PRD AC-5). */ export type ClaimVerdict = "corroborated" | "contradicted" | "unresolved"; /** One evidence pointer into the pack's own `sources` array. */ export interface ClaimEvidencePointer { readonly sourceIndex: number; readonly passageIndex: number; } /** * One claim row: the claim text, its verdict, the count of cue-bearing * matching passages (agent re-judgment input — the cue heuristic is * DISCLOSED hint-grade), and first-encounter evidence pointers. */ export interface ClaimRow { readonly text: string; readonly verdict: ClaimVerdict; readonly negationCues: number; readonly evidence: readonly ClaimEvidencePointer[]; } /** The additive verify block: the statement plus one row per claim. */ export interface VerifyBlock { readonly statement: string; readonly claims: readonly ClaimRow[]; } /** * `contentSha256` validity: a 64-character lowercase hex string — * the exact shape of `createHash("sha256")…digest("hex")` output. * Ruling (ticket T1): hex-shape is enforced at decode, so an * uppercased, truncated, or non-hex string fails closed. Full * recompute-vs-content binding belongs to assembly (T5), which is the * only place the paired content string exists. */ export declare function isValidContentSha256(value: unknown): value is string; /** * Decode an `unknown` value into a canonical `EvidencePack`. Returns the * typed pack on success, `null` for any malformed value. NEVER throws, * NEVER trusts a generic cast. * * `title: null` is valid (reader parity). `sources` and `passages` may be * empty arrays (a pack whose every read failed is still a valid, sad pack). * `brief` (T7) is additive: unknown keys are NOT rejected — a decoded pack * carries exactly the AC-6 keys, and an input carrying extra keys decodes * to the canonical subset. */ export declare function decodeInvestigationPack(value: unknown): EvidencePack | null; //# sourceMappingURL=investigation.d.ts.map