@thehammer/template-verification 0.2.13 → 0.2.15

package/dist/types.d.ts

@@ -132,6 +132,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 +190,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 +213,45 @@ 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 {
     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 +279,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 +311,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 +330,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.13",
+  "version": "0.2.15",
   "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",