@thehammer/template-verification 0.2.14 → 0.2.16

package/dist/types.d.ts

@@ -7,7 +7,6 @@
  * A rendered object node carries a `__meta` MAP keyed by leaf field name; each
  * entry is a {@link DataPointMeta} describing that one field's verification state.
  */
-import type { PreviewFile } from "@thehammer/danx-ui";
 /**
  * Status bucket derived from the integer 1-5 confidence (orthogonal to discrepancy),
  * plus 'failed' (SG-189) — a distinct extraction/citation-correction OUTCOME, not a
@@ -20,45 +19,69 @@ export type ResolvedSource = "override" | "extracted" | "claim" | "none";
 /** The basis a user picked when saving an override. */
 export type SourceChoice = "extracted" | "claim" | "custom";
 /**
- * One citation source for an extracted candidate. The live host shape carries
- * `id`/`source_type`/`stored_file_id`/`explanation`; the optional `file_*`/`page`
- * fields cover the idealized document-page shape. Grouping + linking tolerate
- * either: group by file identity, link only when `file_url` is present.
+ * One citation source for an extracted candidate — `CitationSourceResource`-shaped (SG-685),
+ * the SAME shape gpt-manager's session-authed `data-point-sources`/`data-point-history`
+ * endpoints already returned before this card promoted the token-sealed detail endpoint (and
+ * `history[]`) onto it too. Replaces the earlier `file`/`original_file`/`page_number`/
+ * `source_id`/`agent_thread_message_id` shape (`TemplateDataResource::sourcesPayload()`/
+ * `sourceFilePayload()`, deleted) — one citation transport, not two.
  */
 export interface VerificationSource {
     id?: number | string;
     source_type?: string | null;
-    source_id?: number | string | null;
     explanation?: string | null;
-    stored_file_id?: number | string | null;
-    agent_thread_message_id?: number | string | null;
     /**
      * Ordered verbatim snippets cited on this source's page (SG-181 — replaces the
      * retired attribute-level `cited_text` column). Empty only when the page has no
      * text transcript at all (image-only).
      */
     texts?: string[] | null;
-    file_id?: number | string;
-    page?: number;
-    file_url?: string;
-    file_name?: string;
-    /**
-     * The resolved StoredFile behind `stored_file_id`, danx-ui `PreviewFile`-shaped
-     * (id/name/size/mime/url/thumb?). Present when the host resolved it (gpt-manager's
-     * `TemplateDataResource::sourceFilePayload`); null/absent when the source has no
-     * linked file. This is what the modal renders a real thumbnail/preview from.
-     */
-    file?: PreviewFile | null;
-    /** The page's position inside its parent document (from the transcode StoredFile). */
-    page_number?: number | null;
+    /** Whether this citation resolved to a real page (or, for a `field` citation, a real
+     *  cited attribute). `false` reports WHY via `unresolved_reason` rather than a silent gap. */
+    resolved?: boolean;
+    unresolved_reason?: string | null;
+    stored_file_id?: number | string | null;
+    /** The rendered PAGE this source cites. Null when unresolved, or not a document citation. */
+    page?: {
+        id: string;
+        page_number: number | null;
+        url: string | null;
+        thumb_url: string | null;
+        mime: string | null;
+        size: number | null;
+    } | null;
+    /** The FULL document the cited page was rendered from, reached through the page's own
+     *  parent. Null when `page` is null. */
+    document?: {
+        id: string;
+        name: string | null;
+        url: string | null;
+        mime: string | null;
+    } | null;
+    /** Present only for a `field`-type citation (Generate Artifact) that resolved — the OTHER
+     *  field this value was drawn from, never a document. Null for every other source_type. */
+    field?: {
+        team_object_id: number;
+        field: string;
+        value: unknown;
+        confidence: number | null;
+        reasoning: string | null;
+        state: string | null;
+        superseded: boolean;
+        record_deleted: boolean;
+    } | null;
+    /** The LLM call (ApiLog id) that produced this citation. */
+    api_log_id?: number | string | null;
+    created_at?: string | null;
     /**
-     * The FULL parent document the cited page was transcoded from (PreviewFile-
-     * shaped; `url` is the whole PDF). Null when the source file is not a
-     * transcode page. Drives the Inspector's "view full document" drill-down.
+     * `CitationSourceResource extends` danx's `ActionResource`, which auto-prepends these three
+     * envelope keys to every `::collection()` call — a real, always-present part of the wire
+     * shape (unlike the retired `sourcesPayload()`, a plain array that never carried them), not
+     * something this library's own components read.
      */
-    original_file?: PreviewFile | null;
-    /** The LLM call (ApiLog id) that produced this citation, via the source message. */
-    api_log_id?: number | string | null;
+    __type?: string;
+    __timestamp?: number;
+    __deleted_at?: string | null;
 }
 /**
  * One piece of evidence a {@link SourceDiscrepancy} cites — the page a conflicting value
@@ -132,6 +155,14 @@ export interface Correction {
  */
 export interface ExtractedCandidate {
     value: unknown;
+    /**
+     * WHO authored the value standing on this field — `extraction`, `audit` or `human`
+     * (SG-428/SG-615). Shipped in BOTH light and full mode, same argument as
+     * `source_discrepancy` below: one short string per field. Not to be confused with
+     * `VerificationSource.source_type`, which names a CITATION's own kind (`file` /
+     * `api_log`), a different fact about a different object.
+     */
+    source?: string | null;
     confidence: number | null;
     reasoning?: string | null;
     /**
@@ -182,10 +213,22 @@ export interface ExtractedCandidate {
 /**
  * One recorded attempt in a field's extraction history (SG-190). Mirrors the extracted
  * candidate's provenance plus `is_chosen` (the single live winner) and its timestamp.
+ *
+ * SG-615: caught up to the host's `fieldHistoryPayload()` (SG-450, gpt-manager
+ * `TemplateDataResource`), which this type had drifted from in both directions — it never
+ * declared `source` (WHO authored this attempt — `extraction`/`audit`/`human`) or
+ * `set_by_name` (a real display name for the `human` tier), and it declared a `page` this
+ * host method has never emitted (no source in this library reads `.page` off a history
+ * entry either — the per-source `page`/`page_number` on {@link VerificationSource} is
+ * what's real).
  */
 export interface VerificationHistoryEntry {
     id?: number | string;
     value: unknown;
+    /** WHO authored this attempt — `extraction`, `audit` or `human`. See {@link ExtractedCandidate.source}. */
+    source?: string | null;
+    /** A real display name for the `human` tier; null for every other tier. See {@link OverrideCandidate.set_by_name}. */
+    set_by_name?: string | null;
     confidence: number | null;
     reasoning?: string | null;
     /** See {@link ExtractedCandidate.verbatim} — the same two-value model, per recorded attempt. */
@@ -193,16 +236,51 @@ export interface VerificationHistoryEntry {
     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;
     sources?: VerificationSource[];
     created_at?: string | null;
 }
-/** A user-saved override candidate — always the highest-priority resolution. */
+/**
+ * One page a human cites when saving/overriding a value (SG-565, widened to a list by
+ * SG-573) — the SAME `{file_id, texts}` shape on both the write side
+ * (`SaveOverrideArgs.citation`) and the read side (`OverrideCandidate.citations`), reused
+ * rather than shaped into two types so a reopened picker round-trips through the exact
+ * shape the save endpoint takes. `file_id` is a page-level StoredFile id (danx StoredFile
+ * is UUID-keyed, never an integer); `texts` is the ordered quoted passages the person read
+ * on that page, optional even once a page is named.
+ */
+export interface HumanCitation {
+    file_id: string;
+    texts?: string[];
+}
+/**
+ * A user-saved override candidate — always the highest-priority resolution.
+ *
+ * `source_choice` is deliberately ABSENT here (SG-428) — it recorded whether the person
+ * pinned a candidate's value or typed their own, a fact about the gesture the host never
+ * reads back, and it is not part of the RESPONSE shape. It still rides on
+ * {@link SaveOverrideArgs} below, because both shipped clients still POST it.
+ *
+ * `state`/`set_by_name` (SG-428) and `confidence`/`reasoning`/`citations` (SG-565/SG-573)
+ * mirror the host's `humanCandidate()` (gpt-manager `TemplateDataResource`) — a person may
+ * OPTIONALLY rate their own confidence, explain their reasoning, and cite the page(s) they
+ * read the value from, the same three columns the extracted candidate carries for a
+ * machine reading. Null/absent on every override that did not opt in.
+ */
 export interface OverrideCandidate {
+    /**
+     * The decisive human reading's own id (SG-685) — matches this exact row's `id` in
+     * gpt-manager's `data-point-history` response, letting a consumer find this candidate's own
+     * citations there rather than re-deriving which reading is decisive.
+     */
+    reading_id?: number;
     value: unknown;
-    source_choice?: SourceChoice | string;
+    state?: "present" | "absent" | "removed" | null;
     set_by?: number | string | null;
+    set_by_name?: string | null;
     set_at?: string | null;
+    confidence?: number | null;
+    reasoning?: string | null;
+    citations?: HumanCitation[];
 }
 /** A claim candidate asserted by an example/reference output — lowest priority. */
 export interface ClaimCandidate {
@@ -230,6 +308,16 @@ export interface ResolvedValue {
 /** The per-data-point verification metadata (one `__meta` map entry). */
 export interface DataPointMeta {
     anchor: DataPointAnchor;
+    /**
+     * The field's own declared JSON-Schema `type`/`format` (e.g. `{type: 'string',
+     * format: 'date'}`) — present on every `__meta` entry the host emits, but consumed
+     * by the `views/demands` React app (a separate consumer from this library), not by
+     * anything here. Declared here for shape accuracy against the wire contract; every
+     * `it` in `verificationContract.test.ts` would otherwise have to omit a key the host
+     * genuinely sends.
+     */
+    type?: string | null;
+    format?: string | null;
     candidates: CandidateSet;
     discrepancy: boolean;
     resolved: ResolvedValue;
@@ -252,7 +340,18 @@ export interface DataPointMeta {
 export type MetaCarrier = Record<string, unknown> & {
     __meta?: Record<string, DataPointMeta>;
 };
-/** Arguments the library passes to the host-injected save transport (guide §7.4). */
+/**
+ * Arguments the library passes to the host-injected save transport (guide §7.4).
+ *
+ * `confidence`/`reason`/`citation` (SG-565, `citation` widened to a list by SG-573) let a
+ * person OPTIONALLY carry the same evidentiary shape a machine reading does — never
+ * required, so all three are optional here exactly as the host's
+ * `DataPointValueService::validationRules()` marks them `nullable`/`sometimes`. Omitted
+ * entirely, the save is byte-identical to before these two cards. Named `citation`
+ * (singular) and `reason` on the WRITE side, `citations`/`reasoning` on the READ side
+ * ({@link OverrideCandidate}) — deliberately different names on each side of the wire, so
+ * neither field is ever confused for the other.
+ */
 export interface SaveOverrideArgs {
     workflow_input_id: number | string | null | undefined;
     object_ids: Array<number | string>;
@@ -260,6 +359,9 @@ export interface SaveOverrideArgs {
     field_path: string;
     value: string | null;
     source_choice: SourceChoice;
+    confidence?: number | null;
+    reason?: string | null;
+    citation?: HumanCitation[];
 }
 /**
  * The host-injected save transport. Backend-agnostic: the host supplies the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/template-verification",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "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",