@thehammer/template-verification 0.2.9 → 0.2.11

package/dist/types.d.ts

@@ -60,19 +60,50 @@ export interface VerificationSource {
     /** The LLM call (ApiLog id) that produced this citation, via the source message. */
     api_log_id?: number | string | null;
 }
+/**
+ * One piece of evidence a {@link SourceDiscrepancy} cites — the page a conflicting value
+ * was read off, plus the classifier's own per-page confidence/explanation for it.
+ */
+export interface SourceDiscrepancyEvidence {
+    page_number: number | null;
+    stored_file_id: string | null;
+    confidence: number | null;
+    explanation: string | null;
+}
+/**
+ * A genuine SOURCE-DOCUMENT conflict a host pipeline already reconciled before this value
+ * was settled — e.g. Input Organization's dedup pass merging two group names that disagreed
+ * because of a typo/OCR error in the source document itself, not because they name two
+ * different real entities (SG-217). Distinct from a *candidate* discrepancy (two candidates
+ * — override/extracted/claim — disagreeing): this is ONE candidate's own value, already
+ * resolved from conflicting SOURCE data. Present only on the rare field the host actually
+ * reconciled this way; null/undefined on every ordinary field.
+ */
+export interface SourceDiscrepancy {
+    /** Which field disagreed — a constant naming the data point (e.g. "group_name"). */
+    field: string;
+    /** The literal conflicting values recorded before reconciliation. */
+    conflicting_values: string[];
+    /** The evidence pages/sources the reconciliation was decided from. */
+    evidence: SourceDiscrepancyEvidence[];
+    /** The value that won. */
+    winning_value: string;
+    /** The reconciling explanation (which values disagreed, why, and what corroborated the winner). */
+    reason: string;
+}
 /**
  * The extracted (pipeline) candidate — carries provenance: confidence, reasoning, citation.
  *
  * SG-392: the host's BASE render (`data.__meta`) ships only `value`/`confidence`/
  * `state` plus the two `_count` integers below — `reasoning`/`basis`/`sources`/
- * `history` are `undefined` there. They populate only after
- * `fetchDataPointDetail()` resolves for this field's anchor (see
- * `VerificationModal.vue`, which fetches the instant the Inspector dialog opens
- * and merges the result in). A real production render was shipping every field's
+ * `history` are `undefined` there, and NOTHING IN THIS LIBRARY FILLS THEM IN ANY
+ * MORE. They used to be lazy-fetched by the in-letter Inspector dialog, which is
+ * deleted; the embedding app reads a data point's full detail against its own
+ * session instead. A real production render was shipping every field's
  * full retry history — each carrying its own `sources[]`, each source carrying two
  * full `StoredFile` objects — unconditionally, on every load (~9MB, WI-1090); this
  * split is the fix. Every consumer here degrades gracefully on the undefined case
- * (a length-based count/tooltip/scoreboard reads `*_count` first, `.length` as a
+ * (a length-based count/accessible-name/scoreboard reads `*_count` first, `.length` as a
  * fallback for a fixture/detail-response that already carries the full arrays).
  */
 export interface ExtractedCandidate {
@@ -90,7 +121,7 @@ export interface ExtractedCandidate {
      * the failure explanation instead of citation reasoning. Undefined/null for
      * candidates predating this field.
      */
-    state?: "extracted" | "corrected" | "failed" | "absent" | null;
+    state?: "present" | "absent" | "removed" | "failed" | null;
     /**
      * The full per-field extraction history (SG-190) — every recorded attempt for this
      * field, oldest first, including the live winner and every non-live loser / FAILED
@@ -102,6 +133,13 @@ export interface ExtractedCandidate {
     history?: VerificationHistoryEntry[];
     /** Cheap `history?.length` equivalent — present even when `history` itself is not (SG-392). */
     history_count?: number;
+    /**
+     * Non-null when this candidate's value was reconciled from a genuine SOURCE-DOCUMENT
+     * conflict (SG-217). Shipped in BOTH light and full mode — unlike reasoning/sources/
+     * history above, it is a handful of short strings, not a per-attempt array, so it carries
+     * none of the SG-392 payload-size risk and `hasDiscrepancy()` needs it in light mode too.
+     */
+    source_discrepancy?: SourceDiscrepancy | null;
 }
 /**
  * One recorded attempt in a field's extraction history (SG-190). Mirrors the extracted
@@ -113,7 +151,7 @@ export interface VerificationHistoryEntry {
     confidence: number | null;
     reasoning?: string | null;
     basis?: "verbatim" | "inferred" | null;
-    state?: "extracted" | "corrected" | "failed" | "absent" | null;
+    state?: "present" | "absent" | "removed" | "failed" | null;
     /** True for the single live/winning attempt; false for losers/FAILED/superseded values. */
     is_chosen: boolean;
     page?: number | null;
@@ -156,6 +194,13 @@ export interface DataPointMeta {
     candidates: CandidateSet;
     discrepancy: boolean;
     resolved: ResolvedValue;
+    /**
+     * Present (non-null) when `discrepancy` is true because of a SOURCE-DOCUMENT conflict
+     * rather than (or in addition to) disagreeing candidates (SG-217). Distinguishes a
+     * source-document discrepancy from an ordinary candidate discrepancy for copy/icon
+     * purposes — see {@link isSourceDiscrepancy} in `lib/discrepancy.ts`.
+     */
+    source_discrepancy?: SourceDiscrepancy | null;
 }
 /** An object node in the rendered `data` tree carrying a keyed `__meta` map. */
 export type MetaCarrier = Record<string, unknown> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/template-verification",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "Read-write verification overlay for rendered template apps — per-data-point confidence, discrepancy, 3-source resolution (override > extracted > claim), inline edit, and a recursive comparison page. Consumes the host's __meta sidecar; fetches nothing.",
   "license": "MIT",
   "type": "module",

package/dist/components/AuditCallCard.vue.d.ts

@@ -1,12 +0,0 @@
-import type { AuditLlmCall } from "../lib/dataPointDetail";
-/**
- * One LLM call in the Inspector's Audit trail — model/service chips, status +
- * timing header, and collapsible JSON request/response viewers (danx-ui
- * CodeViewer, mirroring the dashboard's ApiLogEntryCard UX). Pure presentational;
- * the parent owns fetching.
- */
-type __VLS_Props = {
-    call: AuditLlmCall;
-};
-declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-export default _default;

package/dist/components/CitationEvidence.vue.d.ts

@@ -1,33 +0,0 @@
-import { type CitationEvidence } from "../lib/citations";
-/**
- * The evidence behind one value: why the pipeline chose it, and every source page
- * it cited with that page's own verbatim quotes.
- *
- * Replaces the retired single-blockquote treatment, which flattened every quote
- * from every page into one string joined with ellipses — page attribution, the
- * one thing a citation exists to establish, was unrecoverable from it.
- *
- * Reused by both the Inspector's Citations tab (collapsible, full size) and each
- * History attempt's panel (`dense` + flat), so a losing attempt's citations read
- * exactly like the winner's.
- */
-type __VLS_Props = {
-    evidence: CitationEvidence;
-    /** Why the pipeline chose this value. Null renders no reasoning card. */
-    reasoning?: string | null;
-    /** verbatim = the value appears as-is in a quote; inferred = derived from it. */
-    basis?: "verbatim" | "inferred" | null;
-    /** SG-189: extraction/citation-correction failed — `reasoning` is the failure. */
-    failed?: boolean;
-    /** Collapse pages behind an accordion (off inside a History panel). */
-    collapsible?: boolean;
-    dense?: boolean;
-};
-declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
-    failed: boolean;
-    collapsible: boolean;
-    dense: boolean;
-    reasoning: string | null;
-    basis: "verbatim" | "inferred" | null;
-}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-export default _default;

package/dist/components/CitationPage.vue.d.ts

@@ -1,27 +0,0 @@
-import type { CitationPage } from "../lib/citations";
-/**
- * The expanded body of one cited page: its page image on the left, its own
- * ordered verbatim quotes on the right, and the page-level actions.
- *
- * Renders ONLY the body — the collapsed header row lives in
- * {@link CitationPageList} because the disclosure's header is itself a
- * `<button>`, and the view/download controls here are buttons too.
- *
- * The thumbnail is a `DanxFile` in `downloadable` mode: hovering it exposes
- * danx-ui's own download control, and clicking it opens the full-screen viewer.
- * A page whose file the host never resolved still renders its quotes; only the
- * image and its actions are withheld.
- */
-type __VLS_Props = {
-    page: CitationPage;
-    /** Compact treatment for the History tab's per-attempt citations. */
-    dense?: boolean;
-};
-declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    view: () => any;
-    document: () => any;
-}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
-    onView?: (() => any) | undefined;
-    onDocument?: (() => any) | undefined;
-}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-export default _default;

package/dist/components/CitationPageList.vue.d.ts

@@ -1,26 +0,0 @@
-import type { CitationPage as CitationPageModel } from "../lib/citations";
-/**
- * The cited-page list — one collapsible section per source page, each showing that
- * page's own verbatim quotes, with a full-screen viewer behind every page and
- * every parent document.
- *
- * Progressive disclosure is the point: a data point can cite many pages, so a
- * collapsed row carries only what you need to decide whether to open it (page
- * number, document, quote count, and the first quote truncated). Opening a row
- * reveals the page image and the full quote list.
- *
- * `collapsible: false` renders the same content flat, for the History tab's
- * per-attempt citations where the list is short and already inside a panel.
- */
-type __VLS_Props = {
-    pages: CitationPageModel[];
-    /** Collapse pages behind an accordion. Off = every page always expanded. */
-    collapsible?: boolean;
-    /** Compact treatment, passed through to each page body. */
-    dense?: boolean;
-};
-declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
-    collapsible: boolean;
-    dense: boolean;
-}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-export default _default;

package/dist/components/TvDisclosure.vue.d.ts

@@ -1,61 +0,0 @@
-/**
- * A minimal, accessible collapsible-section list — the package's own, on purpose.
- *
- * danx-ui ships `DanxAccordion`, but a template app does NOT resolve danx-ui from
- * this package's node_modules: the danxbot build marks it external and the browser
- * resolves it at load time from the shell's vendor chunk, which pins
- * `@thehammer/danx-ui: ^0.8.17` (see danxbot `spa-template-shell/package.json`).
- * `DanxAccordion` does not exist there, and importing it fails the template's vite
- * build with a Rollup "not exported" error — which is exactly what happened on the
- * first attempt to ship this feature.
- *
- * The rule this encodes: this package must only use danx-ui surface that exists at
- * the FLOOR of its declared peer range, never whatever the local install happens to
- * resolve. A ~40-line disclosure is a much cheaper guarantee than a version bump
- * coordinated across the shell and every template.
- *
- * The header is a `<button>` (its own accessible toggle), so slot content placed in
- * it must not itself be interactive — put actions in the `panel` slot.
- */
-type __VLS_Props = {
-    /** Sections to render, in order. `value` is the open/closed key. */
-    items: Array<{
-        value: string;
-        label?: string;
-    }>;
-    /** Open section keys. Any number may be open at once. */
-    modelValue: string[];
-    /** Prefix for the generated aria ids — unique per usage on a page. */
-    idPrefix?: string;
-};
-declare var __VLS_1: {
-    item: {
-        value: string;
-        label?: string | undefined;
-    };
-    isOpen: boolean;
-}, __VLS_3: {
-    item: {
-        value: string;
-        label?: string | undefined;
-    };
-    isOpen: boolean;
-};
-type __VLS_Slots = {} & {
-    header?: (props: typeof __VLS_1) => any;
-} & {
-    panel?: (props: typeof __VLS_3) => any;
-};
-declare const _default: __VLS_WithSlots<import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    "update:modelValue": (value: string[]) => any;
-}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
-    "onUpdate:modelValue"?: ((value: string[]) => any) | undefined;
-}>, {
-    idPrefix: string;
-}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>, __VLS_Slots>;
-export default _default;
-type __VLS_WithSlots<T, S> = T & {
-    new (): {
-        $slots: S;
-    };
-};

package/dist/components/VerificationModal.vue.d.ts

@@ -1,48 +0,0 @@
-import type { DataPointMeta, SourceChoice } from "../types";
-/**
- * The Inspector — per-data-point detail dialog. 90vw × 90vh danx-ui DanxDialog
- * with a hero strip (resolved value, confidence meter, source of truth,
- * discrepancy alert) over four tabs:
- *
- *  - Citations: why this value, then one collapsible section per cited SOURCE
- *    PAGE carrying that page's own verbatim quotes, each openable full screen
- *    (zoomable, downloadable) with the page's quotes alongside. Replaces the
- *    retired treatment that flattened every quote from every page into one
- *    blockquote, which made page attribution unrecoverable.
- *  - Candidates: the resolution flow — one card per candidate with an Accept
- *    action, plus custom-value entry. Saving toasts + flips the in-document pill.
- *  - History: the live value's confidence + reasoning above the full extraction
- *    history; every attempt (winner, losers, FAILED) collapses to a summary row
- *    and expands to its own reasoning and page-grouped citations.
- *  - Audit trail: every LLM call the pipeline made for this field; hidden
- *    entirely when the host minted no `detail_url`.
- *
- * SG-392: `props.meta.candidates.extracted` may be LIGHT (no `sources`/
- * `history` — the base template render never ships those, only their
- * `*_count`; see `types.ts`'s `ExtractedCandidate` docblock for why). The
- * instant this dialog opens, it fetches the FULL detail (citation sources +
- * extraction history + the LLM audit trace, all in one request — one host
- * endpoint, `verification.detailUrl`) and merges it in; `extracted` (the
- * merged computed) below is what every tab actually reads. A caller that already passed a FULL
- * `extracted` (e.g. the live meta right after a save, which always carries
- * full detail) is used as-is — the fetch still fires (the audit trace is
- * needed either way) but never clobbers already-present sources/history with
- * an absent one.
- *
- * `save` is null when the field is read-only (no transport / no anchor) — the
- * resolution actions are hidden in that case.
- */
-type __VLS_Props = {
-    modelValue: boolean;
-    meta: DataPointMeta;
-    label?: string;
-    save?: ((value: string | null, sourceChoice: SourceChoice) => Promise<DataPointMeta>) | null;
-};
-declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    "update:modelValue": (value: boolean) => any;
-    saved: (meta: DataPointMeta) => any;
-}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
-    "onUpdate:modelValue"?: ((value: boolean) => any) | undefined;
-    onSaved?: ((meta: DataPointMeta) => any) | undefined;
-}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-export default _default;

package/dist/lib/citations.d.ts

@@ -1,84 +0,0 @@
-import type { PreviewFile } from "@thehammer/danx-ui";
-import type { VerificationSource } from "../types";
-/**
- * One cited PAGE of a source document, with the verbatim quotes taken from it.
- *
- * This is the unit the extraction pipeline actually records: `sources[]` holds one
- * row per cited page, and that row carries its OWN ordered `texts[]` (SG-181). The
- * retired `groupSources()` model grouped by "file identity" and left the quotes
- * flattened across the whole candidate, so a reviewer could never tell which page a
- * given quote came from — the defect this model exists to remove.
- *
- * Two source rows that cite the SAME page image merge into one page, their quotes
- * concatenated in source order.
- */
-export interface CitationPage {
-    /** Stable merge/render key — same page image ⇒ same key. */
-    key: string;
-    /** Page position inside the parent document, when the host resolved one. */
-    pageNumber: number | null;
-    /** Human label: "Page 4", else the file name, else a neutral fallback. */
-    label: string;
-    /** The parent document's name, when known — shown as the page's context. */
-    documentName: string | null;
-    /**
-     * The page image itself, danx-ui `PreviewFile`-shaped, carrying `page_number`
-     * so the viewer's own `sortByPageNumber()` orders a multi-page citation
-     * correctly. Null when the host did not resolve a file for this source — the
-     * quotes still render, the view/download affordances do not.
-     */
-    file: PreviewFile | null;
-    /**
-     * A direct URL to this page, from either host shape (`file.url`, else the
-     * idealized `file_url`). Null when the host resolved neither — a plain-text
-     * listing then names the page without linking it.
-     */
-    url: string | null;
-    /** The FULL parent document (the whole PDF), when this page is a transcode child. */
-    document: PreviewFile | null;
-    /** This page's ordered verbatim quotes, duplicates removed. */
-    quotes: string[];
-    /** Any non-empty `explanation` recorded against this page. */
-    explanations: string[];
-    /** The source row ids that merged into this page. */
-    sourceIds: Array<number | string>;
-}
-/** The full citation picture for one candidate (or one history attempt). */
-export interface CitationEvidence {
-    /** Cited pages, ordered by page number, then by input order. */
-    pages: CitationPage[];
-    /** Distinct parent documents across every cited page. */
-    documents: PreviewFile[];
-    /** The LLM calls that produced this citation — the audit-trail anchor. */
-    apiLogIds: Array<number | string>;
-    /**
-     * Citation sources the correction loop could never resolve to a real page
-     * (`source_type: 'failed_file'`). Surfaced rather than dropped — recording
-     * them instead of discarding them is the whole point of that source type.
-     */
-    unresolved: VerificationSource[];
-    pageCount: number;
-    quoteCount: number;
-    /** True when there is nothing at all to show — no page, no unresolved citation. */
-    isEmpty: boolean;
-}
-/**
- * Build the citation picture for a candidate's `sources[]`.
- *
- * Sources are classified by kind before anything is grouped, so provenance rows
- * never masquerade as evidence:
- *
- *  - `failed_file`  → `unresolved` (an unresolvable citation, shown as a warning)
- *  - `api_log`      → `apiLogIds` (the LLM call behind the citation)
- *  - `user`         → dropped (a human override is not a citation)
- *  - anything else  → a cited page, merged by page identity
- *
- * A source with quotes but no resolvable file still becomes a page, so a quote is
- * never silently discarded for want of a thumbnail.
- *
- * Tolerates both host shapes: the live gpt-manager payload (`file` + `page_number`)
- * and the idealized document-page shape (`file_url` / `file_name` / `page`).
- */
-export declare function citationEvidence(sources?: VerificationSource[] | null): CitationEvidence;
-/** "2 pages · 5 quotes" — the one-line summary used in tab badges and headers. */
-export declare function citationSummary(evidence: CitationEvidence): string;

package/dist/lib/dataPointDetail.d.ts

@@ -1,41 +0,0 @@
-import type { DataPointAnchor, ExtractedCandidate } from "../types";
-/**
- * One sanitized LLM call from the host's token-sealed data-point detail endpoint
- * (gpt-manager `TemplateRenderDataController::dataPointDetail()`).
- * Request/response are the raw JSON payloads the team owns; headers/stack traces
- * never ship.
- */
-export interface AuditLlmCall {
-    id: number | string;
-    service?: string | null;
-    endpoint?: string | null;
-    model?: string | null;
-    status_code?: number | null;
-    run_time_ms?: number | null;
-    started_at?: string | null;
-    request?: unknown;
-    response?: unknown;
-    /**
-     * Which pipeline stage this call belongs to (e.g. "Data Extraction Directive") —
-     * the TaskOrchestrator name the host resolved this call's TaskWorker back to.
-     * Null when the host could not attribute a stage (see gpt-manager's
-     * DataPointAuditService for the current Extraction-only attribution scope).
-     */
-    stage?: string | null;
-}
-/** One host detail-endpoint response — the full candidate + its LLM-call trace. */
-export interface DataPointDetail {
-    /** The full extracted candidate (sources/history included), or null when the
-     * field has no verification provenance at all. */
-    extracted: ExtractedCandidate | null;
-    audit: AuditLlmCall[];
-}
-/**
- * Lazy-fetch the FULL detail for one data point (SG-392): its citation sources,
- * full extraction history, and the LLM-call trace behind it, all in ONE request.
- * The anchor's NEAREST object id + leaf field identify the attribute; the host
- * re-resolves its sources server-side (the client never names ApiLog ids). Throws
- * on a non-OK response — callers surface the failure state; an empty `audit`
- * array or a null `extracted` is a valid "nothing there" result, not an error.
- */
-export declare function fetchDataPointDetail(detailUrl: string, anchor: DataPointAnchor): Promise<DataPointDetail>;

package/dist/useSaveDataPoint.d.ts

@@ -1,17 +0,0 @@
-import type { Ref } from "vue";
-import type { Verification } from "./context";
-import type { DataPointMeta, SourceChoice } from "./types";
-/** A bound save: commit an override (pinned candidate or custom value). */
-export type SaveDataPointFn = (value: string | null, sourceChoice: SourceChoice) => Promise<DataPointMeta>;
-/** The transport-bearing slice of the verification state a save needs. */
-export type SaveContext = Pick<Verification, "saveOverride" | "workflowInputId">;
-/**
- * Build a save function for one data point, bound to its anchor + the host
- * transport. Reads the anchor from the CURRENT meta, commits an override, and
- * hands the host's recomputed {@link DataPointMeta} to `onSaved` so the caller can
- * update its writable state and re-render the new resolution.
- *
- * Returns null when no transport was passed to `initVerification` OR the meta
- * carries no anchor — both mean the field is read-only.
- */
-export declare function useSaveDataPoint(verification: SaveContext, currentMeta: Ref<DataPointMeta | null | undefined>, onSaved: (meta: DataPointMeta) => void): SaveDataPointFn | null;