@kontourai/survey 1.1.0 → 1.1.1

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

@@ -0,0 +1,7 @@
+/**
+ * Normalize a value into a deterministic, order-independent form: object keys
+ * sorted, `undefined`-valued keys dropped, Dates rendered as ISO strings.
+ */
+export declare function canonicalize(value: unknown): unknown;
+/** Deterministic JSON string for hashing or structural comparison. */
+export declare function canonicalJson(value: unknown): string;

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

@@ -0,0 +1,32 @@
+// Single canonical JSON serializer shared by the review-workbench structural
+// comparison (`structuralEqual`) and the server-side snapshot hashing, so the
+// same object always produces the same canonical string and hash.
+//
+// Previously two near-identical copies lived in review-workbench.ts and
+// server-review-session.ts and disagreed on Date handling — the workbench copy
+// turned a Date into `{}` (no own enumerable keys), while the server copy used
+// the ISO string. That desynced `structuralEqual` from snapshot freshness/replay
+// hashes for any object carrying a Date (audit 2026-06-28, ops#24).
+/**
+ * Normalize a value into a deterministic, order-independent form: object keys
+ * sorted, `undefined`-valued keys dropped, Dates rendered as ISO strings.
+ */
+export function canonicalize(value) {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => canonicalize(entry));
+    }
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, entryValue]) => entryValue !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right));
+        return Object.fromEntries(entries.map(([key, entryValue]) => [key, canonicalize(entryValue)]));
+    }
+    return value;
+}
+/** Deterministic JSON string for hashing or structural comparison. */
+export function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}

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

@@ -22,7 +22,7 @@ export function buildReviewCandidatePresentation(item, candidate, adapter = {},
         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",
+        sourceLabel: "Source Reference",
         sourceText: sourceLink?.label ?? sourceRef,
         sourceLink,
         traceRefs: traceRefsForCandidate(item, candidate, adapter),
@@ -78,7 +78,7 @@ function traceRefsForCandidate(item, candidate, adapter) {
             kind: "claim",
         },
         {
-            label: "Source ID",
+            label: "Raw Source ID",
             value: candidate.source.sourceId ?? candidate.source.sourceRef,
             kind: "source",
         },

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

@@ -92,7 +92,7 @@ function buildIntegrityPosture(item, candidate, projection) {
     };
 }
 function postureDisclaimer() {
-    return "Survey records source and review posture for projection; it does not validate real-world truth.";
+    return "Survey records Raw Source, Source Reference, and review posture for projection; it does not validate real-world truth.";
 }
 function sourceAuthorityFromProducer(value) {
     if (!isRecord(value)) {
@@ -115,7 +115,7 @@ function portableAuthorityTrace(value) {
     return {
         status: "empty",
         label: "Empty / not provided",
-        detail: "No portable authority trace is present. SourceAuthority metadata is shown as source evidence and is not promoted into authorityTrace.",
+        detail: "No portable authority trace is present. SourceAuthority metadata is shown with Raw Source and Source Reference posture and is not promoted into authorityTrace.",
     };
 }
 function isRecord(value) {

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

@@ -1,3 +1,4 @@
+import { canonicalJson } from "./canonical.js";
 import { candidateForDecision, buildReviewSessionEvent, buildReviewSessionEvents, buildReviewSessionResource, currentReviewItem, currentReviewWorkbenchState, defaultReviewSessionName, deriveQueueRowStatus, initialReviewQueueSessionState, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, reviewWorkbenchSessionStorageKey, selectedCandidateRole, workbenchDecisionDefinitions, } from "./review-queue-session.js";
 import { validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
 import { buildSurfaceProjectionPreview, formatValue, } from "./review-surface-preview.js";
@@ -229,19 +230,7 @@ function matchingSelectedCandidate(item, result) {
         : undefined;
 }
 function structuralEqual(left, right) {
-    return JSON.stringify(canonicalJson(left)) === JSON.stringify(canonicalJson(right));
-}
-function canonicalJson(value) {
-    if (!value || typeof value !== "object") {
-        return value;
-    }
-    if (Array.isArray(value)) {
-        return value.map(canonicalJson);
-    }
-    return Object.fromEntries(Object.entries(value)
-        .filter(([, entry]) => entry !== undefined)
-        .sort(([left], [right]) => left.localeCompare(right))
-        .map(([key, entry]) => [key, canonicalJson(entry)]));
+    return canonicalJson(left) === canonicalJson(right);
 }
 export function buildReviewWorkbenchResultsFromSession(session) {
     return session.items.flatMap((item) => {
@@ -653,7 +642,7 @@ function renderReviewFocus(state, presentationAdapter) {
       </div>
       <dl class="focus-evidence">
         ${fieldItem("Target", presentation.targetLabel)}
-        ${fieldItem("Proposed source", proposed.source.sourceRef)}
+        ${fieldItem("Proposed Source Reference", proposed.source.sourceRef)}
         ${fieldItemClamped("Proposed excerpt", proposed.locator?.excerpt ?? "none", "excerpt")}
       </dl>
     </section>
@@ -745,7 +734,7 @@ function renderPendingSurfacePreview() {
         <span class="surface-summary-label">Surface preview</span>
         <span class="state-label">pending</span>
       </summary>
-      <p class="preview-disclaimer">Choose a review decision to preview the source and review posture that would project toward Surface.</p>
+      <p class="preview-disclaimer">Choose a review decision to preview the Raw Source, Source Reference, and review posture that would project toward Surface.</p>
     </details>
   `;
 }
@@ -852,12 +841,12 @@ function renderCandidateHistory(preview) {
 function renderSourceEvidence(preview) {
     // Excerpt uses a 3-line clamp wrapper with a toggle button.
     const clampedExcerptHtml = fieldItemClamped("Excerpt", preview.sourceEvidence.excerpt, "excerpt");
-    // Build source evidence section with clamped excerpt inline
+    // Build Raw Source section with clamped excerpt inline.
     return `
     <section class="preview-section" data-testid="surface-source-evidence">
-      <h3>${escapeHtml("Source evidence")}</h3>
+      <h3>${escapeHtml("Raw Source")}</h3>
       <dl class="field-stack compact">
-        ${fieldItem("Source URL", preview.sourceEvidence.sourceRef)}
+        ${fieldItem("Source Reference", preview.sourceEvidence.sourceRef)}
         ${clampedExcerptHtml}
         ${fieldItem("Extractor", preview.sourceEvidence.extractor)}
         ${fieldItem("Observed", preview.sourceEvidence.observedAt)}
@@ -868,7 +857,7 @@ function renderSourceEvidence(preview) {
     ].join("") : ""}
       </dl>
       ${renderReferenceDetails([
-        ["Source ID", preview.sourceEvidence.sourceId],
+        ["Raw Source ID", preview.sourceEvidence.sourceId],
         ["Extraction ID", preview.sourceEvidence.extractionId],
     ])}
     </section>
@@ -1194,7 +1183,7 @@ function renderCandidateCard(candidate, state, presentationAdapter) {
         <p class="field-value">${escapeHtml(presentation.valueText)}</p>
       </div>
       <dl class="field-stack">
-        ${fieldItem("Source URL", presentation.sourceText)}
+        ${fieldItem(presentation.sourceLabel, presentation.sourceText)}
         ${fieldItem("Locator", candidate.locator?.locator ?? candidate.locator?.scheme ?? "none")}
         ${fieldItemClamped("Excerpt", candidate.locator?.excerpt ?? "none", "excerpt")}
         ${fieldItem("Extraction confidence", confidence === undefined ? "unknown" : formatConfidence(confidence))}

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

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { deriveReviewSessionApplyResultForSnapshot, } from "./review-workbench.js";
 import { validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
+import { canonicalJson } from "./canonical.js";
 export class StaleServerReviewSessionError extends Error {
     name = "StaleServerReviewSessionError";
     issues;
@@ -107,24 +108,6 @@ function staleIssuesForComparison(comparison) {
     }
     return issues;
 }
-function canonicalJson(value) {
-    return JSON.stringify(canonicalize(value));
-}
-function canonicalize(value) {
-    if (value instanceof Date) {
-        return value.toISOString();
-    }
-    if (Array.isArray(value)) {
-        return value.map((entry) => canonicalize(entry));
-    }
-    if (value && typeof value === "object") {
-        const entries = Object.entries(value)
-            .filter(([, entryValue]) => entryValue !== undefined)
-            .sort(([left], [right]) => left.localeCompare(right));
-        return Object.fromEntries(entries.map(([key, entryValue]) => [key, canonicalize(entryValue)]));
-    }
-    return value;
-}
 function sha256(value) {
     return createHash("sha256").update(value).digest("hex");
 }

package/package.json

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