@thehammer/template-verification 0.1.3 → 0.2.2

package/README.md

@@ -2,12 +2,27 @@
 
 A read-write **verification overlay** for rendered template apps. It overlays a
 trust layer on top of an already-rendered document template: per-data-point
-confidence/status icons, discrepancy indicators, a click-through detail modal,
-inline editing, and a recursive comparison page.
-
-The library **fetches nothing** — the host passes in the rendered `data` (with an
-embedded `__meta` sidecar) and a `saveOverride` transport via a single
-`initVerification()` call. It is backend-agnostic and unit-testable standalone.
+confidence pills + verified check chips, discrepancy indicators, and a
+click-through **Inspector** dialog — a hero strip (resolved value, gradient
+confidence meter, discrepancy alert) over three tabs:
+
+- **Evidence** — readonly-markdown reasoning, cited-text quote, an embedded
+  `DanxFileViewer` over the cited source pages, and per-document drill-down
+  to the FULL parent PDF in a stacked dialog.
+- **Candidates** — the resolution flow: one card per candidate
+  (override/extracted/claim) with Accept actions + custom-value entry;
+  saves toast and flip the in-document pill to a verified chip.
+- **Audit trail** — the LLM calls behind the data point (model, status,
+  timing, collapsible JSON request/response), lazy-fetched from the host's
+  token-sealed `audit_url`. Tab hidden when the host mints none.
+
+`VerificationChrome` adds a review-progress meter (X of Y human-verified),
+a needs-review jump button, and completion celebration.
+
+Render data + `__meta` arrive via a single `initVerification()` call — the
+only network the library touches is the host-supplied `saveOverride`
+transport and the optional `auditUrl` endpoint. Backend-agnostic and
+unit-testable standalone.
 
 ## Install
 
@@ -51,7 +66,9 @@ async function saveOverride(args) {
 initVerification({
   data: props.data,
   saveOverride,
-  workflowInputId: props.data.workflow_input_id
+  workflowInputId: props.data.__verification?.workflow_input_id,
+  // Token-sealed audit endpoint (optional) — enables the Inspector's Audit tab.
+  auditUrl: props.data.__verification?.audit_url ?? null
 })
 </script>
 

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

@@ -0,0 +1,12 @@
+import type { AuditLlmCall } from "../lib/audit";
+/**
+ * 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/VerificationModal.vue.d.ts

@@ -1,13 +1,20 @@
 import type { DataPointMeta, SourceChoice } from "../types";
 /**
- * Per-data-point detail dialog (danx-ui {@link DanxDialog}, not hand-rolled).
- * Shows the resolved value + winning source, every candidate side-by-side with
- * any discrepancy called out, the extracted candidate's confidence / reasoning /
- * cited text (+ verification flag) / grouped source pages, and a resolution
- * control whose three actions create or update the override via the injected save.
+ * The Inspector — per-data-point detail dialog. 90vw × 90vh danx-ui DanxDialog
+ * with a hero strip (resolved value, confidence meter, source-of-truth chips,
+ * discrepancy alert) over three tabs:
+ *
+ *  - Evidence: reasoning (readonly MarkdownEditor), cited text, and an embedded
+ *    DanxFileViewer over the cited source pages, plus per-distinct-document
+ *    "view full document" drill-downs (stacked DanxDialogs — breadcrumb back-nav
+ *    comes free from danx-ui's dialog stack).
+ *  - Candidates: the resolution flow — one card per candidate with an Accept
+ *    action, plus custom-value entry. Saving toasts + flips the in-document pill.
+ *  - Audit trail: lazily fetched LLM calls (token-sealed host endpoint) rendered
+ *    as AuditCallCards; hidden entirely when the host minted no audit_url.
  *
  * `save` is null when the field is read-only (no transport / no anchor) — the
- * resolution control is hidden in that case.
+ * resolution actions are hidden in that case.
  */
 type __VLS_Props = {
     modelValue: boolean;

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

@@ -2,13 +2,14 @@ import type { MetaCarrier } from "../types";
 /**
  * Wraps a single rendered value. Reads the data point's `__meta` from the bound
  * `source` object at `field` (`source.__meta[field]`), renders the RESOLVED value
- * (override > extracted > claim), and — when the overlay is enabled via
- * `useVerification()` — overlays a confidence/status icon plus a discrepancy
- * indicator (orthogonal to confidence), click-through to the detail modal.
- * Supports inline contenteditable editing whenever a `saveOverride` transport was
- * passed to `initVerification`; absent it, read-only. With no meta/source it
- * degrades to a bare value — and with no `initVerification` call at all it still
- * renders the bare value and never throws.
+ * (override > extracted > claim) with a HARD fallback to the host's raw value —
+ * the document must never lose data because provenance is thin. When the overlay
+ * is enabled via `useVerification()` it overlays a confidence pill (or, for
+ * provenance-less points, a subtle dotted underline), a discrepancy indicator,
+ * and click-through to the Inspector dialog. Inline contenteditable editing is
+ * available whenever a `saveOverride` transport was passed to `initVerification`;
+ * absent it, read-only. With no meta/source it degrades to a bare value — and
+ * with no `initVerification` call at all it still renders and never throws.
  */
 type __VLS_Props = {
     source?: MetaCarrier;

package/dist/context.d.ts

@@ -26,6 +26,12 @@ export interface InitVerificationConfig {
     saveOverride?: SaveOverrideFn;
     /** Opaque workflow input id echoed back in saves. */
     workflowInputId?: number | string | null;
+    /**
+     * Token-sealed audit endpoint base (`__verification.audit_url` from the host).
+     * Present ⇒ the Inspector's Audit tab lazy-loads a data point's LLM-call trace
+     * from `{auditUrl}?object_id=&field=`. Absent ⇒ the Audit tab is hidden.
+     */
+    auditUrl?: string | null;
     /** Seeds the overlay toggle ONLY when localStorage holds no prior value. */
     defaultEnabled?: boolean;
 }
@@ -39,6 +45,8 @@ export interface Verification {
     saveOverride?: SaveOverrideFn;
     /** Opaque workflow input id echoed back in saves. */
     workflowInputId?: number | string | null;
+    /** Token-sealed audit endpoint base; null/absent hides the Audit tab. */
+    auditUrl?: string | null;
     /** Open the comparison page (rendered by `<VerificationChrome>`). */
     openComparison: () => void;
 }

package/dist/index.d.ts

@@ -21,5 +21,9 @@ export { walkDataPoints } from "./lib/walk";
 export type { WalkedDataPoint } from "./lib/walk";
 export { groupSources, sourceRowLabel } from "./lib/sources";
 export type { SourceGroup } from "./lib/sources";
+export { computeProgress } from "./lib/progress";
+export type { VerificationProgress } from "./lib/progress";
+export { fetchDataPointAudit } from "./lib/audit";
+export type { AuditLlmCall } from "./lib/audit";
 export { CHROME_CLASS, ENABLED_STORAGE_KEY } from "./constants";
 export type { VerificationStatus, ResolvedSource, SourceChoice, VerificationSource, ExtractedCandidate, OverrideCandidate, ClaimCandidate, CandidateSet, DataPointAnchor, ResolvedValue, DataPointMeta, MetaCarrier, SaveOverrideArgs, SaveOverrideFn, } from "./types";

package/dist/lib/audit.d.ts

@@ -0,0 +1,25 @@
+import type { DataPointAnchor } from "../types";
+/**
+ * One sanitized LLM call from the host's token-sealed data-point audit endpoint
+ * (gpt-manager `TemplateRenderDataController::dataPointAudit`). 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;
+}
+/**
+ * Lazy-fetch the LLM-call trace for one data point. 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 `data` array is a valid "no trace"
+ * result, not an error.
+ */
+export declare function fetchDataPointAudit(auditUrl: string, anchor: DataPointAnchor): Promise<AuditLlmCall[]>;

package/dist/lib/progress.d.ts

@@ -0,0 +1,19 @@
+/** Review-progress summary over a rendered data tree. */
+export interface VerificationProgress {
+    /** Anchored data points (have a __meta entry) — the reviewable universe. */
+    total: number;
+    /** Points a human has locked in (an override candidate exists). */
+    verified: number;
+    /** Points needing attention: discrepancy, or low/absent confidence, not yet verified. */
+    needsReview: number;
+    /** 0-100 integer percent (100 when total is 0 — nothing to review is "done"). */
+    percent: number;
+}
+/**
+ * Compute review progress by walking the data tree ({@link walkDataPoints}).
+ * "Verified" = an override candidate exists (a human explicitly locked a value —
+ * including accepting the extracted/claim value, which persists as an override
+ * with that source_choice). "Needs review" = unverified points that disagree
+ * across candidates or whose extracted confidence is low (≤2) or absent.
+ */
+export declare function computeProgress(data: unknown): VerificationProgress;

package/dist/lib/sources.d.ts

@@ -18,8 +18,10 @@ export interface SourceGroup {
 }
 /**
  * Group an extracted candidate's sources by file identity so the modal can render
- * one block per file with its pages beneath. Links a group only when a `file_url`
- * is present on any of its sources.
+ * one block per file with its pages beneath. Links a group when a `file_url` (the
+ * idealized shape) is present on any of its sources, falling back to the resolved
+ * `file.url` (the live gpt-manager backend shape — `TemplateDataResource` never
+ * emits `file_url`, only `file: {id,name,url,mime,size,thumb}`).
  */
 export declare function groupSources(sources?: VerificationSource[] | null): SourceGroup[];
 /** Human page/citation label for a single source row. */