@kontourai/survey 0.4.13 → 0.4.15

package/dist/src/index.d.ts

@@ -19,5 +19,7 @@ export { repeatedObservation } from "./repeated-observation.js";
 export type { RepeatedObservationInput } from "./repeated-observation.js";
 export { sourceOfAuthorityObservation, sourceOfAuthorityObservationBuilder, SourceOfAuthorityObservationBuilder, } from "./source-of-authority-observation.js";
 export type { SourceAuthorityClass, SourceAuthorityMetadata, SourceOfAuthorityObservationBuilderArgs, SourceOfAuthorityObservationInput, } from "./source-of-authority-observation.js";
+export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-workbench/review-presentation.js";
+export type { ReviewCandidatePresentation, ReviewCandidatePresentationContext, ReviewItemPresentation, ReviewItemPresentationContext, ReviewPresentationAdapter, ReviewPresentationLink, ReviewResultPresentation, ReviewTracePresentationContext, ReviewTraceRef, ReviewValuePresentationContext, } from "./review-workbench/review-presentation.js";
 export { apiRecordSource, manualEntrySource, policyStandardSource, uploadedDocumentSource, webPageSource, } from "./raw-source.js";
 export type { ApiRecordSourceInput, ChecksumInput, ManualEntrySourceInput, PolicyStandardMetadata, PolicyStandardSourceInput, RawSourceInput, UploadedDocumentSourceInput, WebPageSourceInput, } from "./raw-source.js";

package/dist/src/index.js

@@ -8,4 +8,5 @@ export { buildCanonicalReviewProofPayload, buildReviewProofAnchor, canonicalRevi
 export { fieldObservation } from "./field-observation.js";
 export { repeatedObservation } from "./repeated-observation.js";
 export { sourceOfAuthorityObservation, sourceOfAuthorityObservationBuilder, SourceOfAuthorityObservationBuilder, } from "./source-of-authority-observation.js";
+export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-workbench/review-presentation.js";
 export { apiRecordSource, manualEntrySource, policyStandardSource, uploadedDocumentSource, webPageSource, } from "./raw-source.js";

package/dist/src/review-workbench/review-presentation.d.ts

@@ -0,0 +1,67 @@
+import { type ReviewCandidate, type ReviewItem } from "../review-resource.js";
+import { type ReviewWorkbenchResult } from "./review-workbench.js";
+export interface ReviewPresentationAdapter {
+    readonly labelForTarget?: (target: string, context: ReviewItemPresentationContext) => string | undefined;
+    readonly labelForCandidateRole?: (role: ReviewCandidate["role"] | undefined, context: ReviewCandidatePresentationContext) => string | undefined;
+    readonly summarizeValue?: (value: unknown, context: ReviewValuePresentationContext) => string | undefined;
+    readonly linkForReviewItem?: (item: ReviewItem, context: ReviewItemPresentationContext) => ReviewPresentationLink | undefined;
+    readonly linkForSource?: (sourceRef: string, context: ReviewCandidatePresentationContext) => ReviewPresentationLink | undefined;
+    readonly linkForTraceRef?: (ref: ReviewTraceRef, context: ReviewTracePresentationContext) => ReviewPresentationLink | undefined;
+    readonly statusLabel?: (status: string, context: ReviewItemPresentationContext) => string | undefined;
+}
+export interface ReviewItemPresentationContext {
+    readonly item: ReviewItem;
+}
+export interface ReviewCandidatePresentationContext extends ReviewItemPresentationContext {
+    readonly candidate: ReviewCandidate;
+}
+export interface ReviewValuePresentationContext extends ReviewCandidatePresentationContext {
+    readonly value: unknown;
+}
+export interface ReviewTracePresentationContext extends ReviewItemPresentationContext {
+    readonly candidate?: ReviewCandidate;
+}
+export interface ReviewPresentationLink {
+    readonly label?: string;
+    readonly href: string;
+}
+export interface ReviewTraceRef {
+    readonly label: string;
+    readonly value: string;
+    readonly kind: "review-item" | "candidate" | "candidate-set" | "claim" | "source" | "locator" | "proposal" | "external-record";
+    readonly link?: ReviewPresentationLink;
+}
+export interface ReviewCandidatePresentation {
+    readonly candidate: ReviewCandidate;
+    readonly roleLabel: string;
+    readonly valueLabel: string;
+    readonly valueText: string;
+    readonly sourceLabel: string;
+    readonly sourceText: string;
+    readonly sourceLink?: ReviewPresentationLink;
+    readonly traceRefs: readonly ReviewTraceRef[];
+}
+export interface ReviewItemPresentation {
+    readonly item: ReviewItem;
+    readonly target: string;
+    readonly targetLabel: string;
+    readonly statusLabel: string;
+    readonly reviewItemLink?: ReviewPresentationLink;
+    readonly traceRefs: readonly ReviewTraceRef[];
+    readonly candidates: readonly ReviewCandidatePresentation[];
+}
+export interface ReviewResultPresentation {
+    readonly result: ReviewWorkbenchResult;
+    readonly item?: ReviewItem;
+    readonly target: string;
+    readonly targetLabel: string;
+    readonly decisionLabel: string;
+    readonly selectedValueText: string;
+    readonly applyMeaning: string;
+    readonly reviewItemLink?: ReviewPresentationLink;
+    readonly traceRefs: readonly ReviewTraceRef[];
+}
+export declare function buildReviewItemPresentation(item: ReviewItem, adapter?: ReviewPresentationAdapter): ReviewItemPresentation;
+export declare function buildReviewCandidatePresentation(item: ReviewItem, candidate: ReviewCandidate, adapter?: ReviewPresentationAdapter, targetLabel?: string): ReviewCandidatePresentation;
+export declare function buildReviewResultPresentation(result: ReviewWorkbenchResult, item: ReviewItem | undefined, adapter?: ReviewPresentationAdapter): ReviewResultPresentation;
+export declare function humanizeIdentifier(value: string): string;

package/dist/src/review-workbench/review-presentation.js

@@ -0,0 +1,133 @@
+import { formatValue } from "./review-surface-preview.js";
+export function buildReviewItemPresentation(item, adapter = {}) {
+    const context = { item };
+    const targetLabel = adapter.labelForTarget?.(item.spec.target, context) ?? humanizeIdentifier(item.spec.target);
+    const status = item.spec.candidateSetStatus ?? "needs-review";
+    return {
+        item,
+        target: item.spec.target,
+        targetLabel,
+        statusLabel: adapter.statusLabel?.(status, context) ?? humanizeIdentifier(status),
+        reviewItemLink: adapter.linkForReviewItem?.(item, context),
+        traceRefs: traceRefsForReviewItem(item, adapter),
+        candidates: item.spec.candidates.map((candidate) => buildReviewCandidatePresentation(item, candidate, adapter, targetLabel)),
+    };
+}
+export function buildReviewCandidatePresentation(item, candidate, adapter = {}, targetLabel = adapter.labelForTarget?.(item.spec.target, { item }) ?? humanizeIdentifier(item.spec.target)) {
+    const context = { item, candidate };
+    const sourceRef = candidate.source.sourceRef;
+    const sourceLink = adapter.linkForSource?.(sourceRef, context) ?? urlLink(sourceRef);
+    return {
+        candidate,
+        roleLabel: adapter.labelForCandidateRole?.(candidate.role, context) ?? defaultCandidateRoleLabel(candidate.role),
+        valueLabel: targetLabel,
+        valueText: adapter.summarizeValue?.(candidate.value, { ...context, value: candidate.value }) ?? formatValue(candidate.value),
+        sourceLabel: "Source",
+        sourceText: sourceLink?.label ?? sourceRef,
+        sourceLink,
+        traceRefs: traceRefsForCandidate(item, candidate, adapter),
+    };
+}
+export function buildReviewResultPresentation(result, item, adapter = {}) {
+    const target = item?.spec.target ?? result.reviewItemName;
+    const itemContext = item ? { item } : undefined;
+    const targetLabel = item && itemContext
+        ? adapter.labelForTarget?.(target, itemContext) ?? humanizeIdentifier(target)
+        : humanizeIdentifier(target);
+    const selectedCandidate = item?.spec.candidates.find((candidate) => candidate.role === result.selectedCandidateRole || candidate.id === result.selectedCandidateId);
+    return {
+        result,
+        item,
+        target,
+        targetLabel,
+        decisionLabel: humanizeIdentifier(result.decision),
+        selectedValueText: selectedCandidate && item
+            ? buildReviewCandidatePresentation(item, selectedCandidate, adapter, targetLabel).valueText
+            : result.selectedDisplayValue,
+        applyMeaning: result.selectedCandidateRole === "proposed"
+            ? "Saved decision applies proposed value"
+            : "Saved decision keeps current value",
+        reviewItemLink: item && itemContext ? adapter.linkForReviewItem?.(item, itemContext) : undefined,
+        traceRefs: item
+            ? traceRefsForResult(item, result, selectedCandidate, adapter)
+            : [{ label: "Survey ReviewItem", value: result.reviewItemName, kind: "review-item" }],
+    };
+}
+export function humanizeIdentifier(value) {
+    return value
+        .replace(/[_-]+/g, " ")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+function traceRefsForReviewItem(item, adapter) {
+    const refs = [
+        { label: "Survey ReviewItem", value: item.metadata.name, kind: "review-item" },
+    ];
+    const candidateSetId = item.spec.projection?.candidateSetId;
+    if (candidateSetId) {
+        refs.push({ label: "Candidate set", value: candidateSetId, kind: "candidate-set" });
+    }
+    return withTraceLinks(refs, { item }, adapter);
+}
+function traceRefsForCandidate(item, candidate, adapter) {
+    const refs = [
+        { label: "Candidate ID", value: candidate.id, kind: "candidate" },
+        {
+            label: "Claim ID",
+            value: candidate.claimTarget.claimId ?? candidate.claimTarget.fieldOrBehavior,
+            kind: "claim",
+        },
+        {
+            label: "Source ID",
+            value: candidate.source.sourceId ?? candidate.source.sourceRef,
+            kind: "source",
+        },
+    ];
+    const locator = candidate.locator?.locator ?? candidate.locator?.scheme;
+    if (locator) {
+        refs.push({ label: "Locator", value: locator, kind: "locator" });
+    }
+    return withTraceLinks(refs, { item, candidate }, adapter);
+}
+function traceRefsForResult(item, result, selectedCandidate, adapter) {
+    return withTraceLinks([
+        { label: "Survey ReviewItem", value: result.reviewItemName, kind: "review-item" },
+        { label: "Selected candidate", value: result.selectedCandidateId, kind: "candidate" },
+        {
+            label: "Selected claim",
+            value: selectedCandidate?.claimTarget.claimId ?? "not provided",
+            kind: "claim",
+        },
+    ], { item, candidate: selectedCandidate }, adapter);
+}
+function withTraceLinks(refs, context, adapter) {
+    return refs.map((ref) => ({
+        ...ref,
+        link: ref.link ?? adapter.linkForTraceRef?.(ref, context),
+    }));
+}
+function defaultCandidateRoleLabel(role) {
+    if (role === "current")
+        return "Current value";
+    if (role === "proposed")
+        return "Proposed value";
+    return "Candidate";
+}
+function urlLink(value) {
+    if (!/^https?:\/\//.test(value)) {
+        return undefined;
+    }
+    return {
+        label: displayUrl(value),
+        href: value,
+    };
+}
+function displayUrl(value) {
+    try {
+        const parsed = new URL(value);
+        return `${parsed.hostname}${parsed.pathname === "/" ? "" : parsed.pathname}`;
+    }
+    catch {
+        return value;
+    }
+}

package/dist/src/review-workbench/review-surface-preview.d.ts

@@ -1,4 +1,5 @@
 import { type ReviewDecision, type ReviewItem } from "../review-resource.js";
+import { type ReviewPresentationAdapter } from "./review-presentation.js";
 export interface SurfaceProjectionPreview {
     readonly canonicalClaim: PreviewClaim;
     readonly candidateHistory: PreviewCandidateHistory[];
@@ -51,5 +52,5 @@ export interface PreviewAuthorityTrace {
     readonly label: string;
     readonly detail: string;
 }
-export declare function buildSurfaceProjectionPreview(item: ReviewItem, decision: ReviewDecision | undefined): SurfaceProjectionPreview | undefined;
+export declare function buildSurfaceProjectionPreview(item: ReviewItem, decision: ReviewDecision | undefined, presentationAdapter?: ReviewPresentationAdapter): SurfaceProjectionPreview | undefined;
 export declare function formatValue(value: unknown): string;

package/dist/src/review-workbench/review-surface-preview.js

@@ -1,12 +1,12 @@
-export function buildSurfaceProjectionPreview(item, decision) {
+export function buildSurfaceProjectionPreview(item, decision, presentationAdapter = {}) {
     const selectedCandidate = selectedPreviewCandidate(item, decision);
     if (!selectedCandidate || !decision) {
         return undefined;
     }
     const projection = decision.spec.projection ?? selectedCandidate.projection;
     return {
-        canonicalClaim: buildPreviewClaim(selectedCandidate, decision, projection),
-        candidateHistory: buildCandidateHistory(item, selectedCandidate),
+        canonicalClaim: buildPreviewClaim(item, selectedCandidate, decision, projection, presentationAdapter),
+        candidateHistory: buildCandidateHistory(item, selectedCandidate, presentationAdapter),
         sourceEvidence: buildSourceEvidence(selectedCandidate),
         reviewEvent: buildReviewEvent(decision, projection),
         integrityPosture: buildIntegrityPosture(item, selectedCandidate, projection),
@@ -44,20 +44,22 @@ function selectedPreviewCandidate(item, decision) {
     }
     return candidate;
 }
-function buildPreviewClaim(candidate, decision, projection) {
+function buildPreviewClaim(item, candidate, decision, projection, presentationAdapter) {
     return {
         candidateId: candidate.id,
         claimId: projection?.claimId ?? candidate.claimTarget.claimId ?? candidate.claimTarget.fieldOrBehavior,
-        value: formatValue(candidate.value),
+        value: presentationAdapter.summarizeValue?.(candidate.value, { item, candidate, value: candidate.value })
+            ?? formatValue(candidate.value),
         status: decision.spec.status,
     };
 }
-function buildCandidateHistory(item, selectedCandidate) {
+function buildCandidateHistory(item, selectedCandidate, presentationAdapter) {
     return item.spec.candidates
         .filter((candidate) => candidate.id !== selectedCandidate.id)
         .map((candidate) => ({
         candidateId: candidate.id,
-        value: formatValue(candidate.value),
+        value: presentationAdapter.summarizeValue?.(candidate.value, { item, candidate, value: candidate.value })
+            ?? formatValue(candidate.value),
         historyLabel: "Unselected candidate history",
     }));
 }

package/dist/src/review-workbench/review-workbench.css

@@ -771,7 +771,7 @@
 
 .survey-workbench-embed .candidate-card{
   display: grid;
-  grid-template-rows: auto auto minmax(0, 1fr);
+  grid-template-rows: auto auto minmax(0, 1fr) auto;
   gap: 11px;
   min-height: auto;
   padding: 14px;
@@ -817,7 +817,7 @@
   color: var(--paper-faint);
   font-size: 10px;
   letter-spacing: 0.1em;
-  text-transform: none;
+  text-transform: uppercase;
   overflow-wrap: anywhere;
   word-break: break-word;
 }
@@ -1110,6 +1110,44 @@
   color: var(--paper-faint);
 }
 
+.survey-workbench-embed .reference-details{
+  margin-top: 10px;
+  border-top: 1px solid var(--line);
+  padding-top: 8px;
+}
+
+.survey-workbench-embed .reference-details summary{
+  cursor: pointer;
+  color: var(--paper-faint);
+  font-family: "IBM Plex Mono", ui-monospace, monospace;
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.survey-workbench-embed .reference-details summary::-webkit-details-marker{
+  display: none;
+}
+
+.survey-workbench-embed .reference-details summary::before{
+  content: "› ";
+  color: var(--paper-faint);
+}
+
+.survey-workbench-embed .reference-details[open] summary{
+  color: var(--accent);
+}
+
+.survey-workbench-embed .reference-details[open] summary::before{
+  content: "⌄ ";
+  color: var(--accent);
+}
+
+.survey-workbench-embed .reference-details .field-stack{
+  margin-top: 8px;
+}
+
 /* ---- Decision payload: terminal readout, intentionally demoted -------- */
 
 .survey-workbench-embed .payload-panel{

package/dist/src/review-workbench/review-workbench.d.ts

@@ -1,6 +1,8 @@
 import { type ReviewQueueSessionState, type ReviewWorkbenchDecision, type ReviewWorkbenchState } from "./review-queue-session.js";
+import { type ReviewPresentationAdapter } from "./review-presentation.js";
 import { type ReviewCandidate, type ReviewDecision, type ReviewSession, type ReviewSessionEvent } from "../review-resource.js";
 export { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionResource, candidateForDecision, currentReviewItem, currentReviewWorkbenchState, defaultReviewSessionName, deriveQueueRowStatus, initialReviewQueueSessionState, initialReviewWorkbenchState, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, reviewWorkbenchSessionStorageKey, selectedCandidateRole, workbenchDecisionDefinitions, type ReviewQueueRowStatus, type ReviewQueueSessionState, type ReviewSessionSummary, type ReviewWorkbenchDecision, type ReviewWorkbenchState, } from "./review-queue-session.js";
+export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, type ReviewCandidatePresentation, type ReviewCandidatePresentationContext, type ReviewItemPresentation, type ReviewItemPresentationContext, type ReviewPresentationAdapter, type ReviewPresentationLink, type ReviewResultPresentation, type ReviewTracePresentationContext, type ReviewTraceRef, type ReviewValuePresentationContext, } from "./review-presentation.js";
 export { buildSurfaceProjectionPreview, type PreviewAuthorityTrace, type PreviewCandidateHistory, type PreviewClaim, type PreviewIntegrityPosture, type PreviewReviewEvent, type PreviewSourceAuthority, type PreviewSourceEvidence, type SurfaceProjectionPreview, } from "./review-surface-preview.js";
 export declare function buildReviewDecision(state: ReviewWorkbenchState): ReviewDecision | undefined;
 export interface ReviewWorkbenchSessionExport {
@@ -43,6 +45,7 @@ export interface PersistentReviewSessionEventStoreOptions {
 }
 export interface MountReviewWorkbenchOptions {
     readonly eventStore?: ReviewSessionEventStore;
+    readonly presentationAdapter?: ReviewPresentationAdapter;
 }
 export interface BrowserReviewWorkbenchConfig {
     readonly startState?: ReviewQueueSessionState | ReviewWorkbenchState;
@@ -73,7 +76,9 @@ export declare function createLocalStorageReviewSessionEventStore(storage: Pick<
 export declare function createPersistentReviewSessionEventStore(options: PersistentReviewSessionEventStoreOptions): ReviewSessionEventStore & {
     events(): readonly ReviewSessionEvent[];
 };
-export declare function renderReviewWorkbenchHtml(state: ReviewWorkbenchState | ReviewQueueSessionState, events?: readonly ReviewSessionEvent[]): string;
+export declare function renderReviewWorkbenchHtml(state: ReviewWorkbenchState | ReviewQueueSessionState, events?: readonly ReviewSessionEvent[], options?: {
+    readonly presentationAdapter?: ReviewPresentationAdapter;
+}): string;
 export declare function mountReviewWorkbench(root: HTMLElement, startState?: ReviewQueueSessionState | ReviewWorkbenchState, options?: MountReviewWorkbenchOptions): void;
 export declare function browserReviewWorkbenchStartState(): ReviewQueueSessionState | ReviewWorkbenchState | undefined;
 declare global {

package/dist/src/review-workbench/review-workbench.js

@@ -1,7 +1,9 @@
 import { candidateForDecision, buildReviewSessionEvent, buildReviewSessionEvents, buildReviewSessionResource, currentReviewItem, currentReviewWorkbenchState, defaultReviewSessionName, deriveQueueRowStatus, initialReviewQueueSessionState, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, reviewWorkbenchSessionStorageKey, selectedCandidateRole, workbenchDecisionDefinitions, } from "./review-queue-session.js";
 import { buildSurfaceProjectionPreview, formatValue, } from "./review-surface-preview.js";
+import { buildReviewCandidatePresentation, buildReviewItemPresentation, } from "./review-presentation.js";
 import { reviewResourceApiVersion, } from "../review-resource.js";
 export { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionResource, candidateForDecision, currentReviewItem, currentReviewWorkbenchState, defaultReviewSessionName, deriveQueueRowStatus, initialReviewQueueSessionState, initialReviewWorkbenchState, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, reviewWorkbenchSessionStorageKey, selectedCandidateRole, workbenchDecisionDefinitions, } from "./review-queue-session.js";
+export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-presentation.js";
 export { buildSurfaceProjectionPreview, } from "./review-surface-preview.js";
 export function buildReviewDecision(state) {
     if (!state.decision) {
@@ -212,38 +214,38 @@ export function createPersistentReviewSessionEventStore(options) {
         },
     };
 }
-export function renderReviewWorkbenchHtml(state, events) {
+export function renderReviewWorkbenchHtml(state, events, options = {}) {
     if ("items" in state) {
-        return renderReviewQueueSessionHtml(state, events);
+        return renderReviewQueueSessionHtml(state, events, options.presentationAdapter);
     }
     return `
     <section class="workbench-shell" aria-label="Survey review workbench">
-      ${renderWorkbenchHeader(state)}
+      ${renderWorkbenchHeader(state, options.presentationAdapter)}
       <div class="content-grid">
-        ${renderReviewFocus(state)}
-        ${renderDecisionColumn(state)}
-        ${renderCandidateComparison(state)}
+        ${renderReviewFocus(state, options.presentationAdapter)}
+        ${renderDecisionColumn(state, options.presentationAdapter)}
+        ${renderCandidateComparison(state, options.presentationAdapter)}
       </div>
     </section>
   `;
 }
-function renderReviewQueueSessionHtml(session, events) {
+function renderReviewQueueSessionHtml(session, events, presentationAdapter) {
     const state = currentReviewWorkbenchState(session);
     const sessionExport = buildReviewWorkbenchSessionExport(session, events);
     return `
     <section class="workbench-shell" aria-label="Survey review workbench">
-      ${renderWorkbenchHeader(state)}
-      ${renderActiveReviewStrip(session, state)}
+      ${renderWorkbenchHeader(state, presentationAdapter)}
+      ${renderActiveReviewStrip(session, state, presentationAdapter)}
       <div class="queue-layout">
         <aside class="queue-panel" aria-label="Review queue">
-          ${renderQueueRows(session)}
+          ${renderQueueRows(session, presentationAdapter)}
           ${renderSessionSummary(session)}
           ${renderSessionAudit(session, sessionExport)}
         </aside>
         <div class="content-grid">
-          ${renderReviewFocus(state)}
-          ${renderDecisionColumn(state)}
-          ${renderCandidateComparison(state)}
+          ${renderReviewFocus(state, presentationAdapter)}
+          ${renderDecisionColumn(state, presentationAdapter)}
+          ${renderCandidateComparison(state, presentationAdapter)}
         </div>
       </div>
     </section>
@@ -309,25 +311,26 @@ function renderSessionEventRow(event) {
     </li>
   `;
 }
-function renderQueueRows(session) {
+function renderQueueRows(session, presentationAdapter) {
     return `
     <section class="queue-list" data-testid="review-queue">
       <div class="queue-head">
         <h2>Review queue</h2>
         <button class="next-button" type="button" data-testid="next-unresolved">Next unresolved</button>
       </div>
-      ${session.items.map((item) => renderQueueRow(item, session)).join("")}
+      ${session.items.map((item) => renderQueueRow(item, session, presentationAdapter)).join("")}
     </section>
   `;
 }
-function renderQueueRow(item, session) {
+function renderQueueRow(item, session, presentationAdapter) {
     const status = deriveQueueRowStatus(item, session);
     const isActive = item.metadata.name === session.activeItemName;
+    const presentation = buildReviewItemPresentation(item, presentationAdapter);
     return `
     <button class="queue-row${isActive ? " is-active" : ""}" type="button" data-item-name="${escapeHtml(item.metadata.name)}" data-testid="queue-row" data-queue-status="${status}">
       <span class="queue-row-main">
-        <span class="queue-row-title">${escapeHtml(item.metadata.name)}</span>
-        <span class="queue-row-target">${escapeHtml(item.spec.target)}</span>
+        <span class="queue-row-title">${escapeHtml(presentation.targetLabel)}</span>
+        <span class="queue-row-target">${escapeHtml(item.metadata.name)}</span>
       </span>
       <span class="state-label">${escapeHtml(status)}</span>
     </button>
@@ -348,16 +351,17 @@ function renderSessionSummary(session) {
     </section>
   `;
 }
-function renderActiveReviewStrip(session, state) {
+function renderActiveReviewStrip(session, state, presentationAdapter) {
     const activeIndex = session.items.findIndex((item) => item.metadata.name === session.activeItemName);
     const position = activeIndex >= 0 ? activeIndex + 1 : 1;
     const status = deriveQueueRowStatus(state.item, session);
+    const presentation = buildReviewItemPresentation(state.item, presentationAdapter);
     return `
     <section class="active-review-strip" data-testid="active-review-strip" aria-label="Active review item">
       <div class="active-review-copy">
         <span class="field-label">Review ${position} of ${session.items.length}</span>
-        <strong>${escapeHtml(state.item.metadata.name)}</strong>
-        <span>${escapeHtml(state.item.spec.target)}</span>
+        <strong>${escapeHtml(presentation.targetLabel)}</strong>
+        <span>${escapeHtml(state.item.metadata.name)}</span>
       </div>
       <div class="active-review-actions">
         <span class="state-label">${escapeHtml(status)}</span>
@@ -366,19 +370,22 @@ function renderActiveReviewStrip(session, state) {
     </section>
   `;
 }
-function renderWorkbenchHeader(state) {
+function renderWorkbenchHeader(state, presentationAdapter) {
     const current = candidateByRole(state.item, "current");
     const proposed = candidateByRole(state.item, "proposed");
+    const presentation = buildReviewItemPresentation(state.item, presentationAdapter);
+    const currentPresentation = buildReviewCandidatePresentation(state.item, current, presentationAdapter, presentation.targetLabel);
+    const proposedPresentation = buildReviewCandidatePresentation(state.item, proposed, presentationAdapter, presentation.targetLabel);
     return `
     <header class="topbar">
       <div>
         <p class="eyebrow">${escapeHtml(String(state.item.metadata.producer?.displayName ?? "Survey"))}</p>
         <h1>Review candidate update</h1>
-        <p class="review-question">For <strong>${escapeHtml(state.item.spec.target)}</strong>, decide whether <strong>${escapeHtml(formatValue(proposed.value))}</strong> should replace <strong>${escapeHtml(formatValue(current.value))}</strong>.</p>
+        <p class="review-question">For <strong>${escapeHtml(presentation.targetLabel)}</strong>, decide whether <strong>${escapeHtml(proposedPresentation.valueText)}</strong> should replace <strong>${escapeHtml(currentPresentation.valueText)}</strong>.</p>
       </div>
       <dl class="meta-grid">
         ${metaItem("Item", state.item.metadata.name)}
-        ${metaItem("Status", state.item.spec.candidateSetStatus ?? "unresolved")}
+        ${metaItem("Status", presentation.statusLabel)}
         ${metaItem("Selected", state.item.spec.selectedCandidateId ?? "none")}
         ${metaItem("Candidate count", String(state.item.status?.observedCandidateCount ?? state.item.spec.candidates.length))}
       </dl>
@@ -393,53 +400,55 @@ function renderReviewMain(state) {
     </div>
   `;
 }
-function renderReviewFocus(state) {
+function renderReviewFocus(state, presentationAdapter) {
     const current = candidateByRole(state.item, "current");
     const proposed = candidateByRole(state.item, "proposed");
     const proposedConfidence = proposed.extraction.confidence ?? proposed.confidence;
     const currentConfidence = current.extraction.confidence ?? current.confidence;
+    const presentation = buildReviewItemPresentation(state.item, presentationAdapter);
     return `
     <section class="review-focus" data-testid="review-focus" aria-label="Active review focus">
       <div class="focus-head">
         <span class="field-label">Active review</span>
-        <span class="state-label">${escapeHtml(state.item.spec.candidateSetStatus ?? "unresolved")}</span>
+        <span class="state-label">${escapeHtml(presentation.statusLabel)}</span>
       </div>
       <div class="focus-values">
-        ${focusValue("Current", current, currentConfidence, "current")}
-        ${focusValue("Proposed", proposed, proposedConfidence, "proposed")}
+        ${focusValue(state.item, current, currentConfidence, "current", presentationAdapter, presentation.targetLabel)}
+        ${focusValue(state.item, proposed, proposedConfidence, "proposed", presentationAdapter, presentation.targetLabel)}
       </div>
       <dl class="focus-evidence">
-        ${fieldItem("Target", state.item.spec.target)}
+        ${fieldItem("Target", presentation.targetLabel)}
         ${fieldItem("Proposed source", proposed.source.sourceRef)}
         ${fieldItem("Proposed excerpt", proposed.locator?.excerpt ?? "none", "excerpt")}
       </dl>
     </section>
   `;
 }
-function focusValue(label, candidate, confidence, tone) {
+function focusValue(item, candidate, confidence, tone, presentationAdapter, targetLabel) {
+    const presentation = buildReviewCandidatePresentation(item, candidate, presentationAdapter, targetLabel);
     return `
     <div class="focus-value is-${tone}">
-      <span class="field-label">${escapeHtml(label)}</span>
-      <strong>${escapeHtml(formatValue(candidate.value))}</strong>
+      <span class="field-label">${escapeHtml(presentation.roleLabel)}</span>
+      <strong>${escapeHtml(presentation.valueText)}</strong>
       <span>${escapeHtml(confidence === undefined ? "confidence unknown" : formatConfidence(confidence))}</span>
     </div>
   `;
 }
-function renderCandidateComparison(state) {
+function renderCandidateComparison(state, presentationAdapter) {
     const current = candidateByRole(state.item, "current");
     const proposed = candidateByRole(state.item, "proposed");
     return `
     <section class="candidate-grid" aria-label="Candidate comparison">
-      ${renderCandidateCard(current, state)}
-      ${renderCandidateCard(proposed, state)}
+      ${renderCandidateCard(current, state, presentationAdapter)}
+      ${renderCandidateCard(proposed, state, presentationAdapter)}
     </section>
   `;
 }
-function renderDecisionColumn(state) {
+function renderDecisionColumn(state, presentationAdapter) {
     return `
     <aside class="decision-column" aria-label="Review decision">
       ${renderDecisionControls(state)}
-      ${renderSurfacePreview(state)}
+      ${renderSurfacePreview(state, presentationAdapter)}
       ${renderDecisionPayload(state)}
     </aside>
   `;
@@ -490,8 +499,8 @@ function renderDecisionPayload(state) {
     </details>
   `;
 }
-function renderSurfacePreview(state) {
-    const preview = buildSurfaceProjectionPreview(state.item, buildReviewDecision(state));
+function renderSurfacePreview(state, presentationAdapter) {
+    const preview = buildSurfaceProjectionPreview(state.item, buildReviewDecision(state), presentationAdapter);
     return preview ? renderPopulatedSurfacePreview(preview) : renderPendingSurfacePreview();
 }
 function renderPendingSurfacePreview() {
@@ -530,11 +539,12 @@ function renderSurfacePreviewSections(preview) {
     ].join("");
 }
 function renderCanonicalClaim(preview) {
-    return renderPreviewSection("Selected canonical claim", "surface-canonical-claim", [
-        ["Candidate", preview.canonicalClaim.candidateId],
-        ["Claim", preview.canonicalClaim.claimId],
+    return renderPreviewSection("Selected claim", "surface-canonical-claim", [
         ["Value", preview.canonicalClaim.value],
         ["Review status", preview.canonicalClaim.status],
+    ], undefined, [
+        ["Candidate ID", preview.canonicalClaim.candidateId],
+        ["Claim ID", preview.canonicalClaim.claimId],
     ]);
 }
 function renderReviewEvent(preview) {
@@ -548,10 +558,11 @@ function renderReviewEvent(preview) {
 }
 function renderIntegrityPosture(preview) {
     return renderPreviewSection("Integrity posture", "surface-integrity-posture", [
-        ["Candidate set", preview.integrityPosture.candidateSetId],
-        ["Raw source", preview.integrityPosture.rawSourceId],
-        ["Extraction", preview.integrityPosture.extractionId],
         ["Checksum", preview.integrityPosture.checksum],
+    ], undefined, [
+        ["Candidate set ID", preview.integrityPosture.candidateSetId],
+        ["Raw source ID", preview.integrityPosture.rawSourceId],
+        ["Extraction ID", preview.integrityPosture.extractionId],
     ]);
 }
 function renderAuthorityTrace(preview) {
@@ -565,35 +576,50 @@ function renderCandidateHistory(preview) {
         ? [["History", "No unselected candidates."]]
         : preview.candidateHistory.flatMap((candidate) => [
             ["History", candidate.historyLabel],
-            ["Candidate", candidate.candidateId],
             ["Value", candidate.value],
         ]);
-    return renderPreviewSection("Unselected candidate history", "surface-candidate-history", rows);
+    const references = preview.candidateHistory.flatMap((candidate) => [
+        ["Candidate ID", candidate.candidateId],
+    ]);
+    return renderPreviewSection("Unselected candidate history", "surface-candidate-history", rows, undefined, references);
 }
 function renderSourceEvidence(preview) {
     const rows = [
         ["Source URL", preview.sourceEvidence.sourceRef],
-        ["Source ref", preview.sourceEvidence.sourceId],
         ["Excerpt", preview.sourceEvidence.excerpt],
-        ["Extraction", preview.sourceEvidence.extractionId],
         ["Extractor", preview.sourceEvidence.extractor],
         ["Observed", preview.sourceEvidence.observedAt],
     ];
+    const references = [
+        ["Source ID", preview.sourceEvidence.sourceId],
+        ["Extraction ID", preview.sourceEvidence.extractionId],
+    ];
     if (preview.sourceEvidence.sourceAuthority) {
         rows.push(["Source authority class", preview.sourceEvidence.sourceAuthority.authorityClass], ["Declared by", preview.sourceEvidence.sourceAuthority.declaredBy], ["Authority scope", preview.sourceEvidence.sourceAuthority.scope]);
     }
     return renderPreviewSection("Source evidence", "surface-source-evidence", rows);
 }
-function renderPreviewSection(title, testId, rows, extraClass = "") {
+function renderPreviewSection(title, testId, rows, extraClass = "", references = []) {
     return `
     <section class="preview-section${extraClass}" data-testid="${testId}">
       <h3>${escapeHtml(title)}</h3>
       <dl class="field-stack compact">
         ${rows.map(([label, value]) => fieldItem(label, value)).join("")}
       </dl>
+      ${references.length > 0 ? renderReferenceDetails(references) : ""}
     </section>
   `;
 }
+function renderReferenceDetails(references) {
+    return `
+    <details class="reference-details">
+      <summary>IDs and trace links</summary>
+      <dl class="field-stack compact">
+        ${references.map(([label, value]) => fieldItem(label, value)).join("")}
+      </dl>
+    </details>
+  `;
+}
 export function mountReviewWorkbench(root, startState = initialReviewQueueSessionState(), options = {}) {
     const controller = createReviewWorkbenchController(root, startState, options);
     controller.renderCurrentState();
@@ -651,7 +677,7 @@ function createReviewWorkbenchController(root, startState, options) {
             appendEvent("item-selected");
             persistEvents();
         },
-        renderCurrentState: () => renderCurrentState(root, session, controller),
+        renderCurrentState: () => renderCurrentState(root, session, controller, options.presentationAdapter),
         selectDecision,
         selectQueueItem: (itemName) => {
             applySessionUpdate((current) => ({ ...current, activeItemName: itemName }));
@@ -692,9 +718,9 @@ function reviewSessionStorageKey(session, keyPrefix) {
     const itemNames = buildReviewSessionResource(session).spec.reviewItemNames.join(",");
     return `${keyPrefix}:${itemNames}`;
 }
-function renderCurrentState(root, session, controller) {
-    root.innerHTML = renderReviewWorkbenchHtml(session, controller.currentSessionExport().events);
-    bindReviewerNote(root, controller.updateReviewerNote, controller.currentState, controller.currentSession, controller.currentSessionExport, controller.renderCurrentState);
+function renderCurrentState(root, session, controller, presentationAdapter) {
+    root.innerHTML = renderReviewWorkbenchHtml(session, controller.currentSessionExport().events, { presentationAdapter });
+    bindReviewerNote(root, controller.updateReviewerNote, controller.currentState, controller.currentSession, controller.currentSessionExport, controller.renderCurrentState, presentationAdapter);
     bindDecisionButtons(root, (decision) => {
         controller.selectDecision(decision);
         controller.renderCurrentState();
@@ -721,10 +747,10 @@ function queueSessionFromStartState(startState) {
         actorId: startState.actorId,
     };
 }
-function bindReviewerNote(root, updateReviewerNote, currentState, currentSession, currentSessionExport, renderCurrentState) {
+function bindReviewerNote(root, updateReviewerNote, currentState, currentSession, currentSessionExport, renderCurrentState, presentationAdapter) {
     root.querySelector("[data-testid='reviewer-note']")?.addEventListener("input", (event) => {
         updateReviewerNote(event.target.value);
-        refreshDecisionOutputs(root, currentState(), renderCurrentState);
+        refreshDecisionOutputs(root, currentState(), renderCurrentState, presentationAdapter);
         refreshSessionAudit(root, currentSession(), currentSessionExport(), renderCurrentState);
     });
 }
@@ -762,7 +788,7 @@ function scrollActiveReviewIntoView(root) {
         behavior: "smooth",
     });
 }
-function refreshDecisionOutputs(root, state, renderCurrentState) {
+function refreshDecisionOutputs(root, state, renderCurrentState, presentationAdapter) {
     const payload = root.querySelector("[data-testid='decision-payload']");
     if (payload) {
         payload.textContent = JSON.stringify(buildReviewDecision(state) ?? null, null, 2);
@@ -776,7 +802,7 @@ function refreshDecisionOutputs(root, state, renderCurrentState) {
         return;
     }
     const wrapper = document.createElement("div");
-    wrapper.innerHTML = renderSurfacePreview(state);
+    wrapper.innerHTML = renderSurfacePreview(state, presentationAdapter);
     preview.replaceWith(wrapper.firstElementChild);
 }
 function refreshSessionAudit(root, session, sessionExport, renderCurrentState) {
@@ -796,35 +822,41 @@ function producerFeedbackTags(item) {
     const tags = item.spec.producerPolicy?.feedbackTags;
     return Array.isArray(tags) ? tags.map(formatValue) : [];
 }
-function renderCandidateCard(candidate, state) {
+function renderCandidateCard(candidate, state, presentationAdapter) {
     const selectedRole = selectedCandidateRole(state);
     const candidateState = state.decision
         ? candidate.role === selectedRole ? "selected" : "unselected"
         : "pending";
     const cssState = candidateState === "selected" ? " is-selected" : candidateState === "unselected" ? " is-unselected" : "";
     const confidence = candidate.extraction.confidence ?? candidate.confidence;
+    const itemPresentation = buildReviewItemPresentation(state.item, presentationAdapter);
+    const presentation = buildReviewCandidatePresentation(state.item, candidate, presentationAdapter, itemPresentation.targetLabel);
     return `
     <article class="candidate-card${cssState}" data-testid="candidate-${escapeHtml(candidate.role ?? candidate.id)}" data-outcome="${candidateState}">
       <div class="card-head">
         <div>
-          <p class="eyebrow">${escapeHtml(candidate.id)}</p>
-          <h2 class="role">${escapeHtml(titleCase(candidate.role ?? "candidate"))}</h2>
+          <p class="eyebrow">${escapeHtml(candidate.role === "proposed" ? "incoming value" : candidate.role === "current" ? "existing value" : "candidate")}</p>
+          <h2 class="role">${escapeHtml(presentation.roleLabel)}</h2>
         </div>
         <span class="state-label">${escapeHtml(candidateState)}</span>
       </div>
       <div class="candidate-value">
-        <span class="field-label">Value</span>
-        <p class="field-value">${escapeHtml(formatValue(candidate.value))}</p>
+        <span class="field-label">${escapeHtml(presentation.valueLabel)}</span>
+        <p class="field-value">${escapeHtml(presentation.valueText)}</p>
       </div>
       <dl class="field-stack">
-        ${fieldItem("Source URL", candidate.source.sourceRef)}
-        ${fieldItem("Source ref", candidate.source.sourceId ?? candidate.source.sourceRef)}
+        ${fieldItem("Source URL", presentation.sourceText)}
         ${fieldItem("Locator", candidate.locator?.locator ?? candidate.locator?.scheme ?? "none")}
         ${fieldItem("Excerpt", candidate.locator?.excerpt ?? "none", "excerpt")}
         ${fieldItem("Extraction confidence", confidence === undefined ? "unknown" : formatConfidence(confidence))}
         ${fieldItem("Extractor", candidate.extraction.extractor ?? "unknown")}
-        ${fieldItem("Claim", candidate.claimTarget.claimId ?? candidate.claimTarget.fieldOrBehavior)}
       </dl>
+      <details class="reference-details">
+        <summary>IDs and trace links</summary>
+        <dl class="field-stack compact">
+          ${presentation.traceRefs.map((ref) => fieldItem(ref.label, ref.value)).join("")}
+        </dl>
+      </details>
     </article>
   `;
 }
@@ -854,10 +886,6 @@ function fieldItem(label, value, extraClass = "") {
 function formatConfidence(value) {
     return `${Math.round(value * 100)}% (${value.toFixed(2)})`;
 }
-function titleCase(value) {
-    const displayValue = formatValue(value);
-    return displayValue.slice(0, 1).toUpperCase() + displayValue.slice(1);
-}
 function escapeHtml(value) {
     return formatValue(value)
         .replaceAll("&", "&amp;")

package/dist/src/review-workbench/review-workbench.standalone.css

@@ -621,7 +621,7 @@ h1 {
 
 .candidate-card {
   display: grid;
-  grid-template-rows: auto auto minmax(0, 1fr);
+  grid-template-rows: auto auto minmax(0, 1fr) auto;
   gap: 11px;
   min-height: auto;
   padding: 14px;
@@ -667,7 +667,7 @@ h1 {
   color: var(--paper-faint);
   font-size: 10px;
   letter-spacing: 0.1em;
-  text-transform: none;
+  text-transform: uppercase;
   overflow-wrap: anywhere;
   word-break: break-word;
 }
@@ -960,6 +960,44 @@ textarea:focus {
   color: var(--paper-faint);
 }
 
+.reference-details {
+  margin-top: 10px;
+  border-top: 1px solid var(--line);
+  padding-top: 8px;
+}
+
+.reference-details summary {
+  cursor: pointer;
+  color: var(--paper-faint);
+  font-family: "IBM Plex Mono", ui-monospace, monospace;
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.reference-details summary::-webkit-details-marker {
+  display: none;
+}
+
+.reference-details summary::before {
+  content: "› ";
+  color: var(--paper-faint);
+}
+
+.reference-details[open] summary {
+  color: var(--accent);
+}
+
+.reference-details[open] summary::before {
+  content: "⌄ ";
+  color: var(--accent);
+}
+
+.reference-details .field-stack {
+  margin-top: 8px;
+}
+
 /* ---- Decision payload: terminal readout, intentionally demoted -------- */
 
 .payload-panel {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",