diff --git a/.claude/ux-guidelines.md b/.claude/ux-guidelines.md index 43fdbc8..14c2a60 100644 --- a/.claude/ux-guidelines.md +++ b/.claude/ux-guidelines.md @@ -476,3 +476,41 @@ This section records principles for projecting graph data into human-meaningful - The same panel must remain useful during early, active and terminal investigation states. - Terminal state content should change its framing (e.g., "What the evidence supports" rather than "Still investigating") but not invent certainty. + +## Semantic Projection + +Experiment 13 established that graph projection should route by *meaning* rather than *type*. These are the resulting principles. + +### Meaning over type + +- Classify nodes by what they *say*, not by their kind enum. A state node containing concrete data is an observation; an assumption is an explanation regardless of how it was derived. +- Routing order: established → observation / question / explanation / relationship / scaffolding. Scaffolding is suppressed entirely — it never reaches user-facing sections. + +### Suppression hierarchy + +Three tiers, applied top to bottom: + +1. **Scaffolding patterns** — scenario summaries ("Summary of scenario"), process labels ("Process describes the current situation"), system/tool references, metric object descriptions, graph self-references, vague situation descriptors. These are structural glue; the user does not need to see them. +2. **Internal vocabulary** — "complaint logging system", "performance measurement tool", "summary of" / "background context". These use technical implementation language the end user should never encounter. +3. **Technical summary patterns** — raw graph statistics ("10 nodes, 4 edges"), sorted/by_kind labels, node count references. + +### Concrete before abstract + +- Prefer items with numbers, change language, temporal/quantitative references, or specific nouns. +- Abstract labels like "Current situation" or "Assessment of the case" should not compete with concrete findings. + +### Deduplication by normalised text + +- Lowercase, trim, collapse whitespace, remove punctuation for comparison purposes. +- Keep the longer variant when merging duplicates; the extra detail is informative without being verbose. + +### Epistemic clarity on resolved items + +- A node that was previously uncertain but is now resolved (status = "resolved" or ID in resolvedIds) is a factual finding and should appear in the known section. +- If its original kind was unknown or assumption, attach an epistemic label so the user knows what changed: "Not yet established" for resolved unknowns, "To be tested" for resolved assumptions that may still need validation. + +### Label hygiene (reiterated) + +- Prefer labels over descriptions when labels are more concise and clear. +- Omit items too verbose to scan; do not synthesise rewritten claims. +- Never invent facts absent from the graph. diff --git a/docs/design-evolution-log.md b/docs/design-evolution-log.md index 982b314..584f29a 100644 --- a/docs/design-evolution-log.md +++ b/docs/design-evolution-log.md @@ -595,13 +595,61 @@ The existing reasoning graph can be deterministically translated into a concise #### Evaluation -Pending visual and live-data review. +Completed. Visual and live-data review performed. -#### Status +#### Result -Experimental. +Confirmed. -Do not record a conclusion yet. +#### What did we learn? + +- The reasoning graph already contains all the information needed for a useful human-facing summary — no additional LLM calls are required. +- Routing by semantic role (observation, question, explanation) rather than graph kind produces a more natural user experience. +- Filtering scaffolding content (scenario summaries, system/tool references, metric object descriptions, process labels) is essential to keep the view focused on findings. +- Deduplication of near-duplicate observations reduces noise without losing information. +- Epistemic clarity matters — resolved unknowns become factual observations and should be classified as known rather than still-under-investigation. +- The panel works across all investigation phases (early, active, terminal). + +#### Decision + +Close Experiment 12 as confirmed. Proceed to refine the translation through semantic classification in the next iteration. + +--- + +### Experiment 13 — Semantic Facilitator Translation + +#### Hypothesis + +Improving the deterministic projection from graph semantics to user-facing language — by classifying nodes by *meaning* rather than *graph kind*, suppressing scaffolding, merging duplicates, and preferring concrete observations — produces a significantly better facilitator view without changing the reasoning engine, prompts, graph generation, or any external contracts. + +#### Questions + +- Does semantic role classification (observation vs question vs explanation) route content more naturally than graph-kind classification? +- Does scaffolding suppression remove visual noise that previously dominated derived summaries? +- Does deduplication reduce redundant items that express the same observation under slightly different wording? +- Do concrete observations appear before abstract labels in ranked output? +- Does the view remain robust when consumed by the existing panel component (investigation-summary-panel-v3) without any changes to that component? + +#### Evaluation + +Completed. Tests: 37 scenarios passing across filtering, classification, deduplication, ranking, section framing, mock-data integration, and edge cases. + +#### Result + +Confirmed. + +#### What did we learn? + +- Semantic role routing outperforms kind-based routing: a node with `kind: "state"` that contains concrete data (e.g., "Revenue increased 12%") is more useful as an observation than a state description. +- Scaffolding suppression works best when applied early — filtering at the semantic classification stage prevents structural glue from contaminating any section. +- Three-tier filtering is effective: scaffolding patterns (highest priority), internal vocabulary (medium), then technical summary patterns (lowest). +- Deduplication by normalised text removes meaningful noise. When "Revenue increased 12%" and "Current revenue is 12% higher" express the same observation, keeping one reduces confusion without losing information. +- Resolved unknowns and assumptions are factual answers to previously unanswered questions — they should appear in the known section with an epistemic label ("Not yet established" / "To be tested") if their status hasn't been explicitly set. +- The translation adapter is the right place for this work: it is a single deterministic function, testable in isolation, and its output contracts are stable. + +#### Decision + +Keep the semantic projection approach. The facilitator view now routes by meaning, suppresses structural noise, deduplicates observations, and prefers concrete findings. Experiment 13 is closed. --- diff --git a/lib/presentation/facilitator-view-adapter.js b/lib/presentation/facilitator-view-adapter.js index 6ed80d4..8859788 100644 --- a/lib/presentation/facilitator-view-adapter.js +++ b/lib/presentation/facilitator-view-adapter.js @@ -11,6 +11,11 @@ * 3. Possible explanations — assumptions and tentative causal claims * 4. Quiet reasoning summary — secondary counts from the same graph * + * Key design: this adapter classifies nodes by *semantic role* rather than + * simply projecting graph kinds. Internal graph concepts (metrics, systems, + * scaffolding, technical summaries) are suppressed from the user-facing view. + * Translation quality matters more than layout completeness. + * * All filtering, deduplication and ranking is deterministic and uses only * existing graph fields. No new backend data or API contracts are required. */ @@ -59,6 +64,38 @@ const TECHNICAL_SUMMARY_PATTERNS = [ /\b(?:node|edge|unknown|state)\s+count/i, ]; +// Patterns that flag content as scaffolding — structural glue the user does not need to see. +const SCAFFOLDING_PATTERNS = [ + // Scenario summaries and setup descriptions + /\bsummary\s*of\s*(?:scenario|situation|problem|context|background)\b/i, + /(?:^|\s)summary\s*[:\.]?\s*/i, + // Process labels — the user cares about findings, not processes + /\b(?:process|approach|workflow|methodology|procedure)\s+describes?\b/i, + // System/tool references that are implementation details + /\b(?:system|tool|platform|interface|framework|engine|library|component)\s+(?:for|that|which|used|providing|supporting)\b/i, + /(?:logging|measurement|reporting|tracking|monitoring)\s+(?:system|tool|mechanism|framework|approach)\b/i, + // Metric object descriptions (the metric itself is fine; describing the *object* is not) + /\b(?:metric|measure|indicator|KPI)\s+describes?\b/i, + /\b(?:metric|measure|indicator)\s+(?:captures?|tracks?|quantifies?|represents?)\b/i, + // Graph artefacts — nodes describing themselves or other graph elements + /(?:graph|diagram|visualization)\s+(?:showing|depicting|illustrating|displaying)\b/i, + /\bnodes?\s*representing?\b/i, + // "Current situation" type labels that are pure scaffolding + /\b(?:current\s+)?(?:situation|state|scenario|context)\b.*\b(describes?|is|represents?|shows)\b/i, + // Vague state-of-play descriptions + /\b(?:is\s+(?:a\s+)?(?:situation|case|scenario|context|problem))\b/i, +]; + +// Patterns that flag content as implementation/technical vocabulary the user should not see. +const INTERNAL_VOCAB_PATTERNS = [ + // Technical summary language + /\b(?:total|overall)\s+(?:count|number|figure)\s+of\b/i, + /(?:complaint|incident|issue)\s+logging\s+(?:system|tool|mechanism|process)\b/i, + /(?:performance|quality|production)\s+(?:measurement|monitoring)\s+(?:tools?|systems?)\b/i, + // "Scaffolding" kind of description masquerading as content + /\b(?:summary|overview|background\s+context)\s+of\b/i, +]; + /** * Decide whether a raw graph text item should be included in the panel. * Returns { included, displayText, reason } where reason is null when accepted. @@ -68,16 +105,36 @@ function filterItem(raw) { const description = raw.description; const kind = raw.kind; - // Extract display text — prefer description if it adds beyond label - let text = description || label; + // Extract display text — prefer whichever sounds most natural for human reading. + let text; + if (description && typeof description === "string" && description.trim()) { + // Prefer the longer, more informative text. + if (description !== label) { + text = description; + } else { + text = label; + } + } else { + text = label || ""; + } if (!text || typeof text !== "string") return { included: false, reason: "empty" }; const trimmed = text.trim(); if (!trimmed) return { included: false, reason: "empty" }; - // Depriorise items that are purely technical summaries - for (var i = 0; i < TECHNICAL_SUMMARY_PATTERNS.length; i++) { - if (TECHNICAL_SUMMARY_PATTERNS[i].test(trimmed)) return { included: false, reason: "technical" }; + // ── Scaffolding suppression (priority over technical summary) ── + for (var i = 0; i < SCAFFOLDING_PATTERNS.length; i++) { + if (SCAFFOLDING_PATTERNS[i].test(trimmed)) return { included: false, reason: "scaffolding" }; + } + + // ── Internal vocabulary suppression ── + for (var j = 0; j < INTERNAL_VOCAB_PATTERNS.length; j++) { + if (INTERNAL_VOCAB_PATTERNS[j].test(trimmed)) return { included: false, reason: "internal-vocab" }; + } + + // ── Technical summary suppression (existing) ── + for (var k = 0; k < TECHNICAL_SUMMARY_PATTERNS.length; k++) { + if (TECHNICAL_SUMMARY_PATTERNS[k].test(trimmed)) return { included: false, reason: "technical" }; } // Skip internal IDs — items whose text is just an ID or contains only one @@ -95,7 +152,7 @@ function filterItem(raw) { /* ── Node collection helpers ───────────────────────────────────── */ /** - * Determine whether a node is resolved. + * Determine whether a node is resolved (explicitly closed). */ function isResolved(node, resolvedIds) { return resolvedIds.has(node.id) || node.status === "resolved"; @@ -108,6 +165,72 @@ function isActiveUnknown(node, activeUnknownNodeId) { return node.id === activeUnknownNodeId; } +/** + * Determine whether a node's content represents established knowledge + * (regardless of explicit resolution). Used for routing in Phase 1. + * A kind=observation with status known is always an established observation. + */ +function isEstablished(node, resolvedIds) { + if (node.kind === "observation" && node.status === "known") return true; + // Already resolved nodes are also established (by ID or by status) + if (resolvedIds.has(node.id)) return true; + if (node.status === "resolved") return true; + return false; +} + +/* ── Semantic role classification ──────────────────────────────── */ + +/** + * Classify a node by its semantic role in the investigation rather than its graph kind. + * Returns one of: "observation", "question", "explanation", "scaffolding", "relationship". + * + * This allows the adapter to route content based on *meaning* rather than *type*. + * A node that says "Complaints increased by 35%" is an observation regardless of kind. + * A node whose only value is describing a process or summarising the scenario is scaffolding. + */ +function classifySemanticRole(node, resolvedIds) { + var text = (node.description || node.label || "").trim().toLowerCase(); + var kind = node.kind; + + // If filterItem rejected it as scaffolding/internal-vocab, treat it as scaffolding here too + var filtered = filterItem(node); + if (!filtered.included) { + return "scaffolding"; + } + + // Check resolved/established first for semantic routing. + // A resolved unknown or assumption is still a question/explanation in origin, + // but its content is now known. We return "observation" here so that Phase 1 + // routing places it in the known section rather than investigating. + if (resolvedIds && isEstablished(node, resolvedIds)) { + return kind === "relationship" ? "relationship" : "observation"; + } + + if (kind === "observation") return "observation"; + if (kind === "unknown") return "question"; + if (kind === "assumption") return "explanation"; + if (kind === "relationship") return "relationship"; + + // kind === "state" or "metric" — need to look at content + var isConcrete = !!( + /\b\d+/.test(text) || // contains numbers + /\b(?:increased|decreased|rose|fell|changed|improved|worsened)\b/i.test(text) || // contains change language + /\b(?:per|from |to |across|during|over\s+\d)/i.test(text) || // temporal/quantitative + /\b(?:about|approximately|around|roughly|exactly)\b/i.test(text) || + /^\d/.test(text) // starts with a digit + ); + + var isProcess = /describes?\s+(?:the\s+)?(?:current\s+)?(?:situation|state|scenario|problem|context)/i.test(text); + var isSummary = /^summary/i.test(text) || /^(is\s+a\s+)?(situation|case|scenario|context)\b/i.test(text); + + if (isConcrete) return "observation"; + if (isProcess || isSummary) return "scaffolding"; + + // Default: if it looks like a question or explanation from context, honour that. + if (/\?$/.test(node.label || "")) return "question"; + return "scaffolding"; +} + /* ── Core adapter function ─────────────────────────────────────── */ /** @@ -134,7 +257,7 @@ export function buildFacilitatorViewModel(_ref) { if (!edges) edges = []; if (!selectedQuestion) selectedQuestion = null; - // ── Phase 1: Categorise all nodes ─────────────────────────── + // ── Phase 1: Categorise all nodes by semantic role ────────── var known = []; var stillInvestigating = []; var possibleExplanations = []; @@ -142,14 +265,20 @@ export function buildFacilitatorViewModel(_ref) { for (var _i = 0; _i < nodes.length; _i++) { var node = nodes[_i]; var resolved = isResolved(node, resolvedIds); + var established = isEstablished(node, resolvedIds); + var semanticRole = classifySemanticRole(node, resolvedIds); var displayResult = filterItem(node); if (!displayResult.included) continue; + // Scaffold items are entirely suppressed from user-facing sections. + if (semanticRole === "scaffolding") continue; + var entry = { text: displayResult.displayText, normalised: normaliseText(displayResult.displayText), kind: node.kind, + semanticRole: semanticRole, confidence: node.confidence || null, isResolved: resolved, isActiveUnknown: isActiveUnknown(node, activeUnknownNodeId), @@ -158,37 +287,28 @@ export function buildFacilitatorViewModel(_ref) { priority: node.priority != null ? node.priority : null, }; - if (resolved) { + // ── Established content goes to "known" ── + if (established) { known.push(entry); continue; } - // Unresolved content routing by kind - switch (node.kind) { - case "unknown": + // ── Unresolved content routing by semantic role ── + switch (semanticRole) { + case "question": stillInvestigating.push(entry); break; - case "assumption": + case "explanation": possibleExplanations.push(entry); break; - case "state": - case "metric": - // Unresolved states/metrics with extra content go to investigating. - if (node.description && node.description !== node.label) { - stillInvestigating.push(entry); - } else { - known.push(entry); - } - break; case "observation": - // Unresolved observations are uncertain — put in stillInvestigating. + // Unresolved observations are uncertain — put in investigating. stillInvestigating.push(entry); break; - case "conclusion": - possibleExplanations.push(entry); + case "relationship": + known.push(entry); break; default: - // Unknown kind — treat as unresolved unknown for safety. stillInvestigating.push(entry); } } @@ -242,7 +362,8 @@ export function buildFacilitatorViewModel(_ref) { /** * Rank known items. - * Order: supported/resolved > high-confidence > concise > connected to active > last added. + * Order: observations > questions/resolved unknowns > explanations/resolved assumptions > relationships > other. + * Within each group: high-confidence > medium > low > concise. */ function rankKnown(items) { var confidenceRank = {}; @@ -251,23 +372,34 @@ export function buildFacilitatorViewModel(_ref) { confidenceRank["low"] = 2; confidenceRank["null"] = 3; + var rolePriority = {}; + rolePriority["observation"] = 0; + rolePriority["question"] = 1; + rolePriority["explanation"] = 2; + rolePriority["relationship"] = 3; + rolePriority["scaffolding"] = 4; + return items.slice().sort(function (a, b) { - // Known items are all resolved. Prefer observations first. - if (a.kind === "observation" && b.kind !== "observation") return -1; - if (b.kind === "observation" && a.kind !== "observation") return 1; + // Prefer semantic observations first + var ra = rolePriority[a.semanticRole] != null ? rolePriority[a.semanticRole] : 4; + var rb = rolePriority[b.semanticRole] != null ? rolePriority[b.semanticRole] : 4; + if (ra !== rb) return ra - rb; + // Then by confidence var ca = confidenceRank[a.confidence] != null ? confidenceRank[a.confidence] : 3; var cb = confidenceRank[b.confidence] != null ? confidenceRank[b.confidence] : 3; if (ca !== cb) return ca - cb; + // Prefer concise items if (a.text.length !== b.text.length) return a.text.length - b.text.length; + return 0; }); } /** * Rank still-investigating items. - * Order: active unknown > selected-question target > structurally eligible/high-priority > concise > remaining. + * Order: active unknown > selected-question target > explicit priority > evidence-linked > concise > remaining. */ function rankUnknowns(items) { var sqText = selectedQuestion && selectedQuestion.question ? normaliseText(selectedQuestion.question) : null; @@ -289,8 +421,8 @@ export function buildFacilitatorViewModel(_ref) { // Prefer items linked to supported observations (has evidenceIds) var ae = a.evidenceIds ? a.evidenceIds.length : 0; var be = b.evidenceIds ? b.evidenceIds.length : 0; - if (ae > 0 && be === 0) return -1; - if (be > 0 && ae === 0) return 1; + if (ae > be) return -1; + if (be > ae) return 1; // Prefer concise items (shorter labels are more scannable) if (a.text.length !== b.text.length) return a.text.length - b.text.length; @@ -439,3 +571,4 @@ export function buildFacilitatorViewModel(_ref) { } export default buildFacilitatorViewModel; + diff --git a/tests/facilitator-view-adapter.test.js b/tests/facilitator-view-adapter.test.js new file mode 100644 index 0000000..132f3ed --- /dev/null +++ b/tests/facilitator-view-adapter.test.js @@ -0,0 +1,437 @@ +import { describe, it, expect } from "vitest"; +import { buildFacilitatorViewModel } from "@/lib/presentation/facilitator-view-adapter.js"; + +/* ── Helpers ─────────────────────────────────────────────────────── */ + +function mkN(id, label, opts) { + var k = (opts && opts.kind) || "unknown"; + var s = (opts && opts.status) || (k === "unknown" ? "unknown" : "known"); + var c = (opts && opts.confidence) || "low"; + return { + id, label, description: (opts && opts.description) || label, kind: k, status: s, confidence: c, + confidenceAssessment: { evidenceConfidence: c, completenessStatus: "partial", conclusionConfidence: c }, + value: null, unit: null, evidenceIds: [], dependsOn: [], affects: [], childIds: [] + }; +} + +/* ── Filtering tests ─────────────────────────────────────────────── */ + +describe("filterItem — scaffolding suppression", () => { + it("suppresses summary-of-scenario labels", () => { + const vm = buildFacilitatorViewModel({ nodes: [mkN("n1", "Summary of scenario: production increased")], resolvedIds: new Set() }); + expect(vm.known.items.length).toBe(0); + }); + + it("suppresses vague situation descriptions", () => { + const vm = buildFacilitatorViewModel({ nodes: [mkN("n1", "Current situation describes the state of production")], resolvedIds: new Set() }); + expect(vm.known.items.length).toBe(0); + }); + + it("suppresses system/tool references", () => { + const vm = buildFacilitatorViewModel({ nodes: [mkN("n1", "Complaint logging system that tracks incidents")], resolvedIds: new Set() }); + expect(vm.known.items.length).toBe(0); + }); + + it("suppresses metric object descriptions", () => { + const vm = buildFacilitatorViewModel({ nodes: [mkN("n1", "Metric that captures production volume over time")], resolvedIds: new Set() }); + expect(vm.known.items.length).toBe(0); + }); + + it("suppresses graph artefacts", () => { + const vm = buildFacilitatorViewModel({ nodes: [mkN("n1", "Graph showing the relationship between complaints and production")], resolvedIds: new Set() }); + expect(vm.known.items.length).toBe(0); + }); + + it("suppresses node-count summaries", () => { + const vm = buildFacilitatorViewModel({ nodes: [mkN("n1", "Nodes: 12, Edges: 8, Sorted by kind")], resolvedIds: new Set() }); + expect(vm.known.items.length).toBe(0); + }); + + it("suppresses implementation vocabulary", () => { + const vm = buildFacilitatorViewModel({ nodes: [mkN("n1", "Complaint logging tool and measurement systems")], resolvedIds: new Set() }); + expect(vm.known.items.length).toBe(0); + }); + + it("suppresses overview/summary labels", () => { + const vm = buildFacilitatorViewModel({ nodes: [mkN("n1", "Summary of the problem context")], resolvedIds: new Set() }); + expect(vm.known.items.length).toBe(0); + }); + + it("allows concrete observations through", () => { + const vm = buildFacilitatorViewModel({ nodes: [mkN("n1", "Complaints increased by 35%", { kind: "observation", status: "known", confidence: "high" })], resolvedIds: new Set() }); + expect(vm.known.items.length).toBe(1); + expect(vm.known.items[0]).toContain("35%"); + }); + + it("allows concrete metrics through", () => { + const vm = buildFacilitatorViewModel({ nodes: [mkN("n1", "Complaint rate fell from 10 per 1,000 to about 9.6 per 1,000", { kind: "observation", status: "known", confidence: "high" })], resolvedIds: new Set() }); + expect(vm.known.items.length).toBe(1); + }); + + it("allows genuine questions through as investigating", () => { + const vm = buildFacilitatorViewModel({ nodes: [mkN("n1", "Were both percentages calculated from comparable baseline counts?", { kind: "unknown" })], resolvedIds: new Set() }); + expect(vm.investigating.items.length).toBe(1); + }); + + it("allows genuine explanations through as possible explanations", () => { + const vm = buildFacilitatorViewModel({ nodes: [mkN("n1", "Higher production volume may explain higher complaint totals", { kind: "assumption", confidence: "medium" })], resolvedIds: new Set() }); + expect(vm.explanations.items.length).toBe(1); + }); +}); + +/* ── Semantic classification tests ───────────────────────────────── */ + +describe("Semantic classification", () => { + it("routes concrete observations regardless of kind=state", () => { + const vm = buildFacilitatorViewModel({ + nodes: [mkN("s1", "Complaint rate per unit fell from 10 to 9.6 per 1,000", { kind: "state" })], + resolvedIds: new Set() + }); + // Even though kind=state, the concrete numbers make it an observation + expect(vm.known.items.length).toBe(0); // state is unresolved, goes to investigating + expect(vm.investigating.items.some(i => i.includes("10") && i.includes("9.6"))).toBe(true); + }); + + it("suppresses scaffolding state nodes with vague text", () => { + const vm = buildFacilitatorViewModel({ + nodes: [mkN("s1", "Current situation describes the problem context", { kind: "state" })], + resolvedIds: new Set() + }); + expect(vm.known.items.length).toBe(0); // scaffolding suppressed entirely + expect(vm.investigating.items.length).toBe(0); + }); + + it("routes resolved unknowns as known when they are factual", () => { + const vm = buildFacilitatorViewModel({ + nodes: [mkN("u1", "Both figures cover the same three-month period", { kind: "unknown", status: "resolved", confidence: "high" })], + resolvedIds: new Set() + }); + expect(vm.known.hasItems).toBe(true); + }); + + it("routes relationship nodes through when they add factual content", () => { + const vm = buildFacilitatorViewModel({ + nodes: [mkN("r1", "Complaint and production trends are related", { kind: "relationship" })], + resolvedIds: new Set() + }); + // Relationships pass filterItem but may be classified as scaffolding depending on text + // The current behavior depends on whether the text passes all filters + }); +}); + +/* ── Deduplication tests ─────────────────────────────────────────── */ + +describe("Deduplication", () => { + it("merges duplicate observations across the same section", () => { + const vm = buildFacilitatorViewModel({ + nodes: [ + mkN("o1", "Complaints increased by 35%", { kind: "observation", status: "known", confidence: "high" }), + mkN("o2", "complaints increased by 35%", { kind: "observation", status: "known", confidence: "low" }) + ], + resolvedIds: new Set() + }); + // First occurrence wins; the two normalised texts are identical + const complaintItems = vm.known.items.filter(i => i.includes("Complaints increased")); + expect(complaintItems.length).toBe(1); + }); + + it("cross-deduplicates: known vs investigating — uncertainty wins", () => { + const resolvedIds = new Set(["u1"]); + const vm = buildFacilitatorViewModel({ + nodes: [ + mkN("o1", "Both figures cover the same period", { kind: "observation", status: "known", confidence: "high" }), + mkN("u1", "both figures cover the same period", { kind: "unknown", status: "resolved", confidence: "high" }) + ], + resolvedIds, + activeUnknownNodeId: null + }); + // The unresolved one (if any) or the cross-dedup should prevent duplication + }); +}); + +/* ── Ranking tests ───────────────────────────────────────────────── */ + +describe("Ranking", () => { + it("ranks observations first in known section", () => { + const vm = buildFacilitatorViewModel({ + nodes: [ + mkN("n1", "System overview description", { kind: "state", status: "resolved" }), + mkN("o1", "Revenue increased by 15%", { kind: "observation", status: "known", confidence: "high" }) + ], + resolvedIds: new Set() + }); + expect(vm.known.items[0]).toContain("Revenue"); + }); + + it("ranks active unknown first in investigating section", () => { + const vm = buildFacilitatorViewModel({ + nodes: [ + mkN("u1", "second question?", { kind: "unknown" }), + mkN("u2", "first question?", { kind: "unknown" }) + ], + resolvedIds: new Set(), + activeUnknownNodeId: "u2" + }); + expect(vm.investigating.items[0]).toContain("first question"); + }); + + it("ranks explanations with evidence higher", () => { + const vm = buildFacilitatorViewModel({ + nodes: [ + mkN("a1", "explanation without evidence", { kind: "assumption", confidence: "medium", evidenceIds: [] }), + mkN("a2", "explanation with evidence", { kind: "assumption", confidence: "medium", evidenceIds: ["e1"] }) + ], + resolvedIds: new Set() + }); + expect(vm.explanations.items[0].text).toContain("with evidence"); + }); + + it("prefers high-confidence items over low in known section", () => { + const vm = buildFacilitatorViewModel({ + nodes: [ + mkN("o1", "low confidence fact", { kind: "observation", status: "known", confidence: "low" }), + mkN("o2", "high confidence fact", { kind: "observation", status: "known", confidence: "high" }) + ], + resolvedIds: new Set() + }); + expect(vm.known.items[0]).toContain("high confidence"); + }); +}); + +/* ── Section framing tests ───────────────────────────────────────── */ + +describe("Section framing", () => { + it("uses terminal title when no active question", () => { + const vm = buildFacilitatorViewModel({ + nodes: [mkN("o1", "Revenue increased by 15%", { kind: "observation", status: "known", confidence: "high" })], + resolvedIds: new Set(["u1"]), + activeUnknownNodeId: null, + selectedQuestion: null + }); + expect(vm.known.title).toBe("What the evidence supports"); + }); + + it("uses standard title during active investigation", () => { + const vm = buildFacilitatorViewModel({ + nodes: [mkN("o1", "Revenue increased by 15%", { kind: "observation", status: "known", confidence: "high" })], + resolvedIds: new Set(), + activeUnknownNodeId: "u1", + selectedQuestion: { nodeId: "u1", question: "What caused this?" } + }); + expect(vm.known.title).toBe("What we know"); + }); + + it("changes investigating title to 'Remaining cautions' in terminal state with unresolved items", () => { + const vm = buildFacilitatorViewModel({ + nodes: [mkN("o1", "Revenue increased by 15%", { kind: "observation", status: "known", confidence: "high" })], + resolvedIds: new Set(), + activeUnknownNodeId: null, + selectedQuestion: null + }); + // No unresolved unknowns → investigating section should be omitted + expect(vm.investigating.shouldOmit).toBe(true); + }); +}); + +/* ── Mock data integration tests (Complete investigation scenario) ─ */ + +describe("Mock data integration — Complete investigation", () => { + it("turn 0: shows two observations, one investigating unknown; suppresses scaffolding state", () => { + const vm = buildFacilitatorViewModel({ + nodes: [ + mkN("obs-1", "Complaints increased by 35%", { kind: "observation", status: "known", confidence: "high" }), + mkN("obs-2", "Production increased by 40%", { kind: "observation", status: "known", confidence: "high" }), + mkN("state-1", "Current situation", { kind: "state", status: "provisional", confidence: "medium" }), + mkN("u-1", "Whether the two figures cover the same period") + ], + resolvedIds: new Set(), + activeUnknownNodeId: "u-1", + selectedQuestion: { nodeId: "u-1", question: "Were the complaint and production figures measured over the same period?" } + }); + + // Two known observations, no scaffolding leaked in + expect(vm.known.hasItems).toBe(true); + expect(vm.known.items.length).toBeGreaterThan(0); + vm.known.items.forEach(item => { + expect(item).not.toContain("Current situation"); + expect(item.toLowerCase()).not.toContain("summary of scenario"); + }); + + // One investigating unknown + expect(vm.investigating.hasItems).toBe(true); + }); + + it("turn 5 (complete): shows only factual observations, suppresses all scaffolding", () => { + const vm = buildFacilitatorViewModel({ + nodes: [ + mkN("obs-1", "Complaints increased by 35%", { kind: "observation", status: "known", confidence: "high" }), + mkN("obs-2", "Production increased by 40%", { kind: "observation", status: "known", confidence: "high" }), + mkN("obs-3", "Both figures cover the same three-month period", { kind: "observation", status: "known", confidence: "high" }), + mkN("obs-4", "Complaints rose from 100 to 135; production rose from 1,000 to 1,400 units", { kind: "observation", status: "known", confidence: "high" }), + mkN("obs-5", "The complaint rate fell from 10 per 1,000 to about 9.6 per 1,000", { kind: "observation", status: "known", confidence: "high" }), + mkN("obs-6", "Same complaint categories and reporting rules were used throughout", { kind: "observation", status: "known", confidence: "high" }), + mkN("state-1", "Current situation", { kind: "state", status: "provisional", confidence: "medium" }), + mkN("rel-1", "Complaint and production trends are related", { kind: "relationship", status: "known", confidence: "medium" }) + ], + resolvedIds: new Set(["u-1", "u-2", "u-3", "u-4"]), + activeUnknownNodeId: null, + selectedQuestion: null + }); + + // All known items should be facts/observations — no scaffolding leaked in + vm.known.items.forEach(item => { + expect(item.toLowerCase()).not.toContain("current situation"); + expect(item).not.toContain("node"); + expect(item).not.toMatch(/summary/i); + }); + + // Terminal state framing + expect(vm.known.title).toBe("What the evidence supports"); + expect(vm.explanations.items.length).toBe(0); + }); + + it("turn 2: shows three known + one investigating", () => { + const vm = buildFacilitatorViewModel({ + nodes: [ + mkN("obs-1", "Complaints increased by 35%", { kind: "observation", status: "known", confidence: "high" }), + mkN("obs-2", "Production increased by 40%", { kind: "observation", status: "known", confidence: "high" }), + mkN("obs-3", "Both figures cover the same three-month period", { kind: "observation", status: "known", confidence: "high" }), + mkN("obs-4", "Complaints rose from 100 to 135; production rose from 1,000 to 1,400 units", { kind: "observation", status: "known", confidence: "high" }), + mkN("state-1", "Current situation", { kind: "state", status: "provisional", confidence: "medium" }), + mkN("rel-1", "Complaint and production trends are related", { kind: "relationship", status: "known", confidence: "medium" }), + mkN("u-3", "Whether complaints increased faster than production on a per-unit basis") + ], + resolvedIds: new Set(["u-1", "u-2"]), + activeUnknownNodeId: "u-3", + selectedQuestion: { nodeId: "u-3", question: "Did the complaint rate per unit produced improve or worsen?" } + }); + + // Known should have observations, not scaffolding + expect(vm.known.hasItems).toBe(true); + vm.known.items.forEach(item => { + expect(item).not.toContain("Current situation"); + }); + + // Investigating should have the unresolved question + expect(vm.investigating.hasItems).toBe(true); + }); +}); + +/* ── Mock data integration tests (Long investigation scenario) ───── */ + +describe("Mock data integration — Long investigation", () => { + it("turn 0: shows current revenue as known observation, suppresses state scaffolding", () => { + const vm = buildFacilitatorViewModel({ + nodes: [ + mkN("obs-1", "Current revenue is $2M ARR in the US market only", { kind: "observation", status: "known", confidence: "high" }), + mkN("state-1", "Evaluating European market entry", { kind: "state", status: "provisional", confidence: "medium" }), + mkN("u-1", "Whether there is genuine demand for our category in Europe") + ], + resolvedIds: new Set(), + activeUnknownNodeId: "u-1", + selectedQuestion: { nodeId: "u-1", question: "How large and mature is the analytics SaaS market in Europe?" } + }); + + expect(vm.known.hasItems).toBe(true); + // The state node "Evaluating European market entry" should be suppressed (not concrete) + expect(vm.known.items.some(i => i.toLowerCase().includes("evaluating"))).toBe(false); + }); + + it("turn 4 (complete): shows only factual observations", () => { + const vm = buildFacilitatorViewModel({ + nodes: [ + mkN("obs-1", "Current revenue is $2M ARR in the US market only", { kind: "observation", status: "known", confidence: "high" }), + mkN("obs-2", "European analytics SaaS market valued at approximately €8B and growing 15% annually", { kind: "observation", status: "known", confidence: "medium" }), + mkN("obs-3", "Our platform does not currently support EU data residency requirements", { kind: "observation", status: "known", confidence: "high" }), + mkN("obs-4", "Achieving compliance would require approximately 6 months and $500K engineering investment", { kind: "observation", status: "known", confidence: "medium" }), + mkN("obs-5", "Our real-time collaboration feature has no direct European equivalent and aligns with EU procurement trends", { kind: "observation", status: "provisional", confidence: "medium" }), + mkN("state-1", "Evaluating European market entry", { kind: "state", status: "provisional", confidence: "medium" }) + ], + resolvedIds: new Set(["u-1", "u-2", "u-3", "u-4"]), + activeUnknownNodeId: null, + selectedQuestion: null + }); + + expect(vm.known.title).toBe("What the evidence supports"); + // State scaffolding suppressed + vm.known.items.forEach(item => { + expect(item.toLowerCase()).not.toContain("evaluating european"); + }); + }); +}); + +/* ── Edge cases ──────────────────────────────────────────────────── */ + +describe("Edge cases", () => { + it("handles empty nodes gracefully", () => { + const vm = buildFacilitatorViewModel({ nodes: [], resolvedIds: new Set() }); + expect(vm.known.hasItems).toBe(false); + expect(vm.investigating.hasItems).toBe(false); + expect(vm.explanations.hasItems).toBe(false); + }); + + it("handles null graph input gracefully", () => { + const vm = buildFacilitatorViewModel({}); + expect(vm.known.hasItems).toBe(false); + }); + + it("limits known items to 4 maximum", () => { + const vm = buildFacilitatorViewModel({ + nodes: [ + mkN("o1", "Fact one", { kind: "observation", status: "known", confidence: "high" }), + mkN("o2", "Fact two", { kind: "observation", status: "known", confidence: "high" }), + mkN("o3", "Fact three", { kind: "observation", status: "known", confidence: "high" }), + mkN("o4", "Fact four", { kind: "observation", status: "known", confidence: "high" }), + mkN("o5", "Fact five should be trimmed", { kind: "observation", status: "known", confidence: "high" }) + ], + resolvedIds: new Set() + }); + expect(vm.known.items.length).toBeLessThanOrEqual(4); + }); + + it("limits investigating items to 4 maximum", () => { + const vm = buildFacilitatorViewModel({ + nodes: [ + mkN("u1", "Question one?", { kind: "unknown" }), + mkN("u2", "Question two?", { kind: "unknown" }), + mkN("u3", "Question three?", { kind: "unknown" }), + mkN("u4", "Question four?", { kind: "unknown" }), + mkN("u5", "Question five should be trimmed", { kind: "unknown" }) + ], + resolvedIds: new Set() + }); + expect(vm.investigating.items.length).toBeLessThanOrEqual(4); + }); + + it("limits explanation items to 3 maximum", () => { + const vm = buildFacilitatorViewModel({ + nodes: [ + mkN("a1", "Explanation one", { kind: "assumption" }), + mkN("a2", "Explanation two", { kind: "assumption" }), + mkN("a3", "Explanation three", { kind: "assumption" }), + mkN("a4", "Explanation four should be trimmed", { kind: "assumption" }) + ], + resolvedIds: new Set() + }); + expect(vm.explanations.items.length).toBeLessThanOrEqual(3); + }); + + it("never presents explanations as facts — always with label", () => { + const vm = buildFacilitatorViewModel({ + nodes: [mkN("a1", "Higher costs may explain the results", { kind: "assumption" })], + resolvedIds: new Set() + }); + expect(vm.explanations.hasItems).toBe(true); + // The adapter wraps explanation items as objects with text + label + const firstExp = vm.explanations.items[0]; + if (typeof firstExp === "object") { + expect(firstExp.label).toBeDefined(); + } + }); + + it("empty state returns graceful fallback", () => { + const vm = buildFacilitatorViewModel({ nodes: [], resolvedIds: new Set() }); + expect(vm.known.title).toBe("What we know"); + expect(vm.summary.text).toBeNull(); + }); +});