cbrowser 20.2.2 → 21.0.0

package/dist/mcp-tools/base/persona-comparison-tools.js

@@ -5,7 +5,6 @@
  * @license MIT
  */
 import { z } from "zod";
-import { resolveValuesForPersona } from "../../values/persona-values.js";
 import { writeArtifact } from "../../artifact-store.js";
 import { buildContentWithPreviews } from "../inline-image.js";
 import { makeTempDir } from "../../temp-files.js";
@@ -14,8 +13,14 @@ import { refuseHostedUrl } from "../hosted-inputs.js";
 import { comparePersonas } from "../../analysis/index.js";
 import { isApiKeyConfigured } from "../../cognitive/index.js";
 import { getAnyPersona, resolvePersonaOrThrow, getCognitiveProfile, createCognitivePersona, isAgentPersonaObject, BUILTIN_PERSONAS, ACCESSIBILITY_PERSONAS, EMOTIONAL_PERSONAS, } from "../../personas.js";
-import { buildOTCognitiveProfile as buildOTProfile, cognitiveDistance, cognitiveBarycenter, cognitiveGeodesic, cognitiveDistanceMatrix, selectMaxCoveragePersonas, estimateCognitiveLoad, COGNITIVE_TRAITS, } from "../../visual/cognitive-transport.js";
-import { bridgeCapacityTraits } from "../../visual/cognitive-models.js";
+import { buildOTCognitiveProfile as buildOTProfile, cognitiveDistance, cognitiveBarycenter, cognitiveGeodesic, cognitiveDistanceMatrix, selectMaxCoveragePersonas, estimateCognitiveLoad, COGNITIVE_TRAITS, OVERALL_LEVEL_KEY, } from "../../visual/cognitive-transport.js";
+import { bridgeCapacityTraits, personaRateContext } from "../../visual/cognitive-models.js";
+import { lawTimesReport } from "../../visual/law-times-report.js";
+import { activeProvenance, collectPersonaReads, isolatedProvenanceAsync, personaRateProvenance, ATTENTION_PROVENANCE_TEXT } from "../../visual/model-provenance.js";
+import { ctcBandsDescription, ctcRank } from "../../visual/ctc-bands.js";
+import { resolveSiteFamiliarity } from "./site-familiarity.js";
+import { resolveChainValues, valueModulationReport } from "./chain-values.js";
+import { recordedAnswer } from "./answer-provenance.js";
 /**
  * Most base64 characters cognitive_effort spends on its inline motor-overlay
  * preview. The overlay is supporting evidence here, not the finding, and the
@@ -381,7 +386,7 @@ Begin with the first persona: ${personas[0]}
     // ── Cognitive Transport Tools (v18.27.0) ──
     server.registerTool("cognitive_distance", {
         title: "Cognitive Distance Between Personas",
-        description: "Compute the Wasserstein cognitive distance between two personas. Returns W₁ distance (true cognitive distance), per-trait contributions, and Bures-Wasserstein W₂ distance. Based on optimal transport theory — transport cost = cognitive processing cost.",
+        description: "Compute the cognitive distance between two personas as a generalized (unbalanced) Wasserstein-1 distance over their trait vectors: it counts both the shape of the profile and its overall level, so a persona with every trait at 0.2 is far from one with every trait at 0.8. Moving trait mass between traits costs a hand-set ground metric (0.2 same domain, 0.5 related, 0.8 unrelated); creating or destroying it costs 0.4 per unit, also hand-set. Both are hypotheses, untested against human data. Returns w1 with per-trait contributions (plus overallLevel, the share due to a difference in level), the shape-only Bures-Wasserstein W2 and sliced distances, and each metric's percentile among built-in persona pairs.",
         inputSchema: {
             personaA: z.string().describe("First persona name"),
             personaB: z.string().describe("Second persona name"),
@@ -404,8 +409,11 @@ Begin with the first persona: ${personas[0]}
         const otA = buildOTProfile(personaA, profileA.traits || {});
         const otB = buildOTProfile(personaB, profileB.traits || {});
         const dist = cognitiveDistance(otA, otB);
-        // Top 5 trait contributions
+        // Top 5 trait contributions. The generalized W1's level term is reported
+        // on its own: it is not a trait, and listing it among traits read as one.
+        const overallLevelContribution = dist.traitContributions[OVERALL_LEVEL_KEY] ?? 0;
         const topTraits = Object.entries(dist.traitContributions)
+            .filter(([trait]) => trait !== OVERALL_LEVEL_KEY)
             .sort(([, a], [, b]) => b - a)
             .slice(0, 5)
             .map(([trait, contrib]) => ({ trait, contribution: Math.round(contrib * 10000) / 10000 }));
@@ -421,6 +429,9 @@ Begin with the first persona: ${personas[0]}
                         w1Distance: Math.round(dist.w1 * 10000) / 10000,
                         w2Distance: Math.round(dist.w2 * 10000) / 10000,
                         slicedWasserstein: Math.round(dist.sliced * 10000) / 10000,
+                        // The part of w1 forced by the difference in mean trait level; the
+                        // rest is shape. topDifferentiatingTraits lists traits only.
+                        overallLevelContribution: Math.round(overallLevelContribution * 10000) / 10000,
                         // The comparable view: where this pair sits within all built-in
                         // persona pairs, per metric. 0 = closest pair seen, 100 = farthest.
                         metrics: {
@@ -435,11 +446,19 @@ Begin with the first persona: ${personas[0]}
                         scaleNote: 
                         // The count is read from the list: "26" went stale when the three bridge
                         // traits arrived (v10 B42).
-                        `w1 (L1 sum over ${COGNITIVE_TRAITS.length} traits), w2 (L2 norm) and sliced (mean random projection) ` +
-                            "are different quantities on different scales — w1 typically runs ~20x larger " +
-                            "than sliced. Compare the percentiles, not the raw values.",
+                        `w1 (exact generalized Wasserstein-1 distance over ${COGNITIVE_TRAITS.length} traits), ` +
+                            "w2 (L2 norm) and sliced (mean absolute projection over uniform directions, computed exactly) are different quantities on different " +
+                            "scales. Compare the percentiles, not the raw values. w1 sees both the shape of a profile " +
+                            "and its overall level: each trait t carries mass t/" + COGNITIVE_TRAITS.length + ", moving mass " +
+                            "between traits costs the trait ground metric (0.2 / 0.5 / 0.8) and creating or destroying it " +
+                            "costs 0.4 per unit (a hand-set hypothesis), so w1 ranges from 0 to 0.4 and all traits 0.2 " +
+                            "versus all traits 0.8 is 0.24. overallLevelContribution, reported apart from the traits, is " +
+                            "half the cost the difference in mean trait level forces, 0.5 x 0.4 x |mean A - " +
+                            "mean B| (the other half is charged to the traits where mass is created or destroyed). w2 and " +
+                            "sliced are computed on profiles normalised to the simplex, so they measure shape only: " +
+                            "proportional trait vectors are at distance 0 on both.",
                         // Verdict is a percentile band, not an absolute threshold. The former
-                        // absolute bands put 209 of 210 built-in pairs in one bucket.
+                        // absolute bands put 209 of the then 210 built-in pairs in one bucket.
                         interpretation: w1Pct < 10 ? "Nearly identical cognitive profiles (closer than 90% of persona pairs)"
                             : w1Pct < 30 ? "Similar cognitive profiles with minor differences"
                                 : w1Pct < 70 ? "Moderately different cognitive profiles"
@@ -453,7 +472,7 @@ Begin with the first persona: ${personas[0]}
     });
     server.registerTool("cognitive_coverage", {
         title: "Maximum Coverage Persona Selection",
-        description: "Select the N most cognitively different personas from a list for maximum test coverage. Uses greedy farthest-point sampling in Wasserstein space.",
+        description: "Select the N most cognitively different personas from a list for maximum test coverage. Uses greedy farthest-point sampling under the generalized Wasserstein-1 distance of cognitive_distance, which counts differences in overall trait level as well as in profile shape.",
         inputSchema: {
             personas: z.array(z.string()).describe("List of persona names to select from"),
             count: z.number().describe("Number of personas to select"),
@@ -555,10 +574,10 @@ Begin with the first persona: ${personas[0]}
     });
     server.registerTool("cognitive_load_estimate", {
         title: "Cognitive Load Estimate",
-        description: "Estimate cognitive load for a specific persona on page metrics. Returns per-dimension breakdown (information, visual, attention, decision, motor, text, memory, patience) and identifies the bottleneck dimension. Attention, motor and text use the persona's modelled capacities (sustained attention, Fitts pointing, reading). Visual is persona-invariant: no trait has a researched mapping onto visual-complexity tolerance, so it measures the page only and is listed under personaInvariant.",
+        description: "Estimate cognitive load for a specific persona on page metrics. Returns per-dimension breakdown (visual, attention, decision, motor, text, memory, patience) and identifies the bottleneck dimension. informationDensity is accepted and not read: through 20.x it was charged against the persona's comprehension, which is grasp of UI conventions, not reading; text load is the text dimension. Attention, motor and text use the persona's modelled capacities (sustained attention, Fitts pointing, reading). Visual is persona-invariant: no trait has a researched mapping onto visual-complexity tolerance, so it measures the page only and is listed under personaInvariant.",
         inputSchema: {
             persona: z.string().describe("Persona name"),
-            informationDensity: z.number().min(0).max(1).describe("Content density (0=sparse, 1=dense)"),
+            informationDensity: z.number().min(0).max(1).describe("Content density (0=sparse, 1=dense). Accepted for compatibility and not read since 21.0"),
             visualComplexity: z.number().min(0).max(1).describe("Visual complexity (0=simple, 1=complex)"),
             interactiveElements: z.number().describe("Number of interactive elements"),
             textDensity: z.number().min(0).max(1).describe("Text heaviness (0=minimal, 1=wall of text)"),
@@ -584,7 +603,7 @@ Begin with the first persona: ${personas[0]}
         // bridged capacities. Unbridged, they sat at the 0.5 fallback and every
         // persona scored identically on all three (B29, 2026-10-10). Same helper
         // as cognitive_effort, site_cognitive_assessment and the story tool.
-        bridgeCapacityTraits(persona, traits, p.accessibilityTraits);
+        bridgeCapacityTraits(persona, traits, p.accessibilityTraits, personaRateContext(p));
         const otProfile = buildOTProfile(persona, traits);
         const load = estimateCognitiveLoad(otProfile, {
             informationDensity, visualComplexity, interactiveElementCount: interactiveElements,
@@ -612,21 +631,21 @@ Begin with the first persona: ${personas[0]}
     server.registerTool("cognitive_effort", {
         _meta: { ui: { resourceUri: "ui://cbrowser/effort" } },
         title: "Cognitive Effort Analysis",
-        description: "Compute total cognitive effort for a persona to use a page. MEASURES THE VIEWPORT BY DEFAULT (above the fold); pass scope='full_page' to measure the whole page. Uses the 8-layer Sequential Transport Chain: saliency → cognitive load → decision → motor (target acquisition) → motor procedure (executing a sequence) → frustration → readability (decoding) → reading attention (holding the line, re-reading). IMPORTANT: High-familiarity personas (power-user, confident-user) require site knowledge. If the user asks for these personas, first check if site knowledge exists by running site_model_status. If no site knowledge exists, either (1) ask the user if they want to build it first by navigating the site, or (2) warn them that results will treat the persona as a first-time visitor. The tool returns a familiarityWarning when site knowledge is missing.",
+        description: "Compute total cognitive effort for a persona to use a page. MEASURES THE VIEWPORT BY DEFAULT (above the fold); pass scope='full_page' to measure the whole page. Uses the 8-layer Sequential Transport Chain: visual complexity (a count of visual elements and motion, not the attention model) → cognitive load → decision → motor (target acquisition) → motor procedure (executing a sequence) → frustration → readability (decoding) → reading attention (holding the line, re-reading). Site familiarity is per run: pass siteFamiliarity (0 first visit, 1 daily user) or every persona is scored as a first visit. No persona carries a familiarity of its own, and site knowledge from crawling is reported but does not change the score. The headline number, cognitiveTransportCost.total, is a percentile: the page's raw cost ranked among the real pages of the shipped reference set, for the built-in personas, at the same scope (0.8 = costlier than 80% of them). The verdict states that rank and its band; the cost is untested against human data, so it says nothing about how a person feels, and abandonmentRisk is a separate quantity.",
         inputSchema: {
             url: z.string().url().describe("URL to analyze"),
             // Per RUN, not per persona. A persona is familiar with one site and new
             // to another, so this only has an answer once a URL is named. The
             // persona's stored value, where one exists, is the fallback. (2026-08-01)
             siteFamiliarity: z.number().min(0).max(1).optional()
-                .describe("How familiar this persona is with THIS url: 0 first visit, 1 daily user. Set it per run — familiarity is a persona-site pair, not a disposition. Supplying it also skips the site-knowledge downgrade, which exists only to stop a stored value asserting experience of a site nobody has crawled."),
-            persona: z.string().describe("Persona name. WORKFLOW: For power-user, confident-user, or any persona the user describes as 'experienced' — check site_model_status first. If site knowledge exists, ask the user: 'Site knowledge exists for this domain. Should I use it to simulate an experienced user, or test as a first-time visitor?' If no site knowledge exists, warn: 'No site knowledge for this domain. power-user will be tested as a first-time visitor. Run page_understand first to build site knowledge.'"),
+                .describe("How familiar this persona is with THIS url: 0 first visit, 1 daily user. Omitted, the run scores a first visit (0). Familiarity is a persona-site pair, not a disposition: no persona carries one, and site knowledge does not supply one."),
+            persona: z.string().describe("Persona name (e.g. first-timer, power-user, cognitive-adhd). To simulate someone who already knows this site, pass siteFamiliarity; the persona name does not imply it."),
             _browserToken: z.string().optional().describe("Browser session token"),
             userLocation: z.string().optional().describe("User's approximate location (e.g., 'Denver, Colorado, US')"),
             userTimezone: z.string().optional().describe("User's timezone (e.g., 'America/Denver')"),
             userLanguage: z.string().optional().describe("User's expected language (e.g., 'en-US')"),
             proxy: z.string().optional().describe("Proxy server URL for geo-accurate testing"),
-            useValues: z.boolean().optional().default(false).describe("Enable motivational value modulation (Schwartz values). When true, persona values modulate saliency maps, decision costs, and frustration costs. Default: false (trait-only mode)."),
+            useValues: z.boolean().optional().default(false).describe("Apply the persona's Schwartz values (opt-in). When true, the values modulate the page's demand inside the chain, through its ten registered coefficients (chain.valueModulation.*, hand-set hypotheses, counted in modelProvenance): stimulation and security on changeBlindness; achievement on satisficing and riskTolerance; conformity on socialProofSensitivity and anchoringBias; selfDirection on socialProofSensitivity; power on fearOfMissingOut; stimulation on patience; benevolence on emotionalContagion. Each adds coefficient x score x max(chain.valueModulation.demandFloor, demand) to that trait's demand, clamped to [0, 1]; hedonism, tradition and universalism change nothing. Applies to the aggregate score and, at scope 'sequential', to every screen. Scores come from the persona registry, the persona's own schwartzValues, its Big Five, or an account persona in the CMS; `valueModulation` in the response says whether any were found. Default: false (trait-only mode)."),
             waitAfterLoad: z.number().optional().describe("Extra ms to wait after page loads (e.g., 3000 for sites with client-side translation)"),
             waitForSelector: z.string().optional().describe("CSS selector to wait for after load (e.g., '[data-translated]')"),
             scope: z.enum(["viewport", "full_page", "sequential"]).optional().default("viewport").describe("What to measure: 'viewport' (first impression, above-the-fold — default), 'full_page' (scroll the whole page, count every element), or 'sequential' (score each screen on its own content, carrying capacity forward, and report where people stop). Viewport and full_page match empathy_audit's parameter. 'sequential' answers a different question from either: not 'what would the whole page cost' but 'how far do they get'. NOTE: every published CTC number predates this parameter and is a viewport measurement."),
@@ -638,7 +657,9 @@ Begin with the first persona: ${personas[0]}
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async ({ url, persona: personaName, siteFamiliarity, _browserToken, userLocation, userTimezone, userLanguage, proxy, useValues, waitAfterLoad, waitForSelector, scope }) => {
+    }, recordedAnswer(async ({ url, persona: personaName, siteFamiliarity, _browserToken, userLocation, userTimezone, userLanguage, proxy, useValues, waitAfterLoad, waitForSelector, scope }) => {
+        // recordedAnswer: one provenance recording per call, across every await,
+        // reported as modelProvenance at the end (answer-provenance.ts).
         // Hosted: http(s) only (sec-paths, 2026-10-10; see hosted-inputs.ts).
         const hostedRefusal = refuseHostedUrl("cognitive_effort", { url });
         if (hostedRefusal)
@@ -734,12 +755,10 @@ Begin with the first persona: ${personas[0]}
             const personaObj = isAgentPersonaObject(existingPersona)
                 ? createCognitivePersona(personaName, personaName, {})
                 : existingPersona;
-            // v18.61.0: siteFamiliarity is a binary gate based on site knowledge
-            // Has site knowledge → persona keeps its familiarity (maxed to 1.0 for experts)
-            // No site knowledge → forced to 0.0 (first visit)
+            // siteFamiliarity: the caller's value for this run, else 0.0 (first
+            // visit). Site knowledge is looked up only to report it; it does not
+            // change the number (site-familiarity.ts has the 20.x history).
             const traits = { ...(personaObj.cognitiveTraits || {}) };
-            const requestedFamiliarity = traits.siteFamiliarity ?? 0.5;
-            let familiarityWarning;
             let hasSiteKnowledge = false;
             try {
                 const pageUrl = await page.url();
@@ -750,26 +769,10 @@ Begin with the first persona: ${personas[0]}
                 hasSiteKnowledge = !!(stats && stats.navigationNodes > 0);
             }
             catch { }
-            // A caller who states familiarity for THIS run has answered the question
-            // the downgrade exists to answer. The gate guards against a value STORED
-            // on a persona claiming experience of a site nobody has crawled -- it was
-            // never meant to overrule someone naming the pair directly.
-            const familiarityFromCaller = typeof siteFamiliarity === "number";
-            if (familiarityFromCaller) {
-                traits.siteFamiliarity = siteFamiliarity;
-            }
-            else if (hasSiteKnowledge) {
-                // Site knowledge exists — high-familiarity personas get max familiarity
-                if (requestedFamiliarity > 0.5)
-                    traits.siteFamiliarity = 1.0;
-            }
-            else {
-                // No site knowledge — everyone is a first-time visitor
-                traits.siteFamiliarity = 0.0;
-                if (requestedFamiliarity > 0.5) {
-                    familiarityWarning = `"${personaName}" has siteFamiliarity=${requestedFamiliarity.toFixed(1)} stored on the persona but no site knowledge exists for this domain. Downgraded to 0.0 (first visit). Familiarity is a persona-site pair: pass siteFamiliarity on this call to state it for this run, or build knowledge by navigating the site (page_understand goes deeper).`;
-                }
-            }
+            // The visit, not the persona: Cockburn et al.'s expertise e on the
+            // choosing time, handed to the demand below (Stage C). No trait carries it.
+            const familiarity = resolveSiteFamiliarity(siteFamiliarity, hasSiteKnowledge);
+            const demandOptions = { siteFamiliarity: familiarity.value };
             // Bridge the formal models into the trait vector BEFORE the chain runs.
             //
             // getReadingProfile and getPointingProfile already model this persona's
@@ -785,6 +788,9 @@ Begin with the first persona: ${personas[0]}
             // the persona's profile, so storing them would create a second copy that
             // can drift from the model that produces it. (2026-08-02)
             let pointingProfileForResponse;
+            // The ids the bridge read for THIS persona, reported as personaRateProvenance:
+            // collected from the call, so no cache state can change them.
+            let personaRateIds = new Set();
             try {
                 const { bridgeCapacityTraits } = await import("../../visual/cognitive-models.js");
                 // accessibilityTraits passed so an author's STATED reading capacity is
@@ -794,14 +800,14 @@ Begin with the first persona: ${personas[0]}
                 // inline here and NOWHERE ELSE, which is why the two tools disagreed by
                 // 2.6x on the motor layer: the other path scored against the missing-trait
                 // fallback of 0.5 and called it a pointing ability.
-                pointingProfileForResponse = bridgeCapacityTraits(personaName, traits, accTraits);
+                ({ result: pointingProfileForResponse, ids: personaRateIds } = collectPersonaReads(() => bridgeCapacityTraits(personaName, traits, accTraits, personaRateContext(personaObj))));
             }
             catch (e) {
                 // Left absent rather than defaulted: a missing capacity is visible as a
                 // gap, a defaulted one silently reads as average.
                 console.debug(`[cognitive_effort] capacity bridge unavailable: ${e.message}`);
             }
-            // Build OT profile (with potentially adjusted siteFamiliarity)
+            // Build OT profile
             const otProfile = buildOTProfile(personaName, traits);
             // Extract page metrics
             const { extractPageMetrics } = await import("../../visual/cognitive-transport.js");
@@ -833,111 +839,110 @@ Begin with the first persona: ${personas[0]}
             // full_page since that is the comparable whole-document number.
             const pageMetrics = await extractPageMetrics(page, measureScope === "sequential" ? "full_page" : measureScope, sharedGeometry);
             // Compute full COT
-            const { computeDemandDistribution, computeSequentialCTC } = await import("../../visual/cognitive-transport-chain.js");
-            const demand = computeDemandDistribution(pageMetrics);
-            // SEQUENTIAL PASS. Runs before the aggregate so a failure here degrades to
-            // the normal answer rather than losing the whole call.
-            let sequentialResult;
+            const { computeDemandDistribution, computeSequentialCTC, computeSequentialScrollCTC } = await import("../../visual/cognitive-transport-chain.js");
+            // Motivational values (opt-in, default off). Resolved here and handed to
+            // the chain, which applies them through its own registered modulation
+            // (VALUE_DEMAND_MODULATION, chain.valueModulation.*) and clamps the result
+            // to [0, 1].
+            //
+            // Through 21.0 this tool had a second path of its own: a
+            // conservation/openness formula with unregistered 0.3 and 0.5 constants
+            // that scaled five decision demands and emotionalContagion in place,
+            // unclamped (up to 1.3), while the chain's modulation was reached from no
+            // tool at all. Two hand-set models of one effect, and the one that ran was
+            // the one the provenance block could not see. (2026-10-22)
+            // One resolver, shared with visual_cognitive_story (chain-values.ts).
+            const schwartzValues = useValues ? await resolveChainValues(personaName) : undefined;
+            const chainOptions = { asymmetric: true, interactions: true, ...(schwartzValues ? { schwartzValues } : {}) };
+            // SEQUENTIAL PASS, measuring half. The per-screen metrics are read here and
+            // the curve is scored in the block below with everything else, so its
+            // constants are counted too. A failure here degrades to the normal answer
+            // rather than losing the whole call.
+            let perScreen;
+            let sequentialError;
             if (measureScope === "sequential") {
                 try {
                     const { extractPerScreenMetrics } = await import("../../visual/cognitive-transport.js");
-                    const { computeSequentialScrollCTC } = await import("../../visual/cognitive-transport-chain.js");
                     // The SAME measurement the caption came from, so the curve length and the
                     // caption cannot disagree.
-                    const perScreen = await extractPerScreenMetrics(page, 20, sharedGeometry);
-                    const seqProfile = buildOTProfile(personaName, traits);
-                    const seq = computeSequentialScrollCTC(seqProfile, perScreen.map((m) => computeDemandDistribution(m)), { asymmetric: true, interactions: true });
-                    sequentialResult = {
-                        screensMeasured: seq.screens.length,
-                        // The INPUTS the screen count came from, published so a differing curve is
-                        // diagnosable instead of guessable. An external client measured 5.8 screens
-                        // on a session's first navigation and 6.7 on every later one; with only
-                        // `screensMeasured: 7` in the payload a 6-screen curve is internally
-                        // consistent and unmarked, which is the shape of every defect this tool has
-                        // had. An invisible variance is indistinguishable from no variance.
-                        geometry: {
-                            documentHeight: sharedGeometry.documentHeight,
-                            viewportHeight: sharedGeometry.viewportHeight,
-                            pageScreens: sharedGeometry.pageScreens,
-                            screenCount: sharedGeometry.screenCount,
-                            note: "One measurement, shared by the curve length and by the pageScreens caption, so the two cannot disagree. Page height can change between navigations; if two runs of the same URL differ, compare documentHeight before anything else.",
-                        },
-                        totalAbandonment: `${Math.round(seq.totalAbandonment * 100)}%`,
-                        expectedDepthScreens: seq.expectedDepthScreens,
-                        dropOff: seq.dropOff
-                            ? { screen: seq.dropOff.screen, layer: seq.dropOff.layer, shareOfSessions: `${Math.round(seq.dropOff.share * 100)}%` }
-                            : null,
-                        reachWeightedCTC: seq.reachWeightedCTC,
-                        curve: seq.screens.map((x) => ({
-                            screen: x.screen,
-                            reach: `${Math.round(x.reachProbability * 100)}%`,
-                            stopHere: `${Math.round(x.stopHazard * 100)}%`,
-                            cumulativeAbandonment: `${Math.round(x.cumulativeAbandonment * 100)}%`,
-                            screenCTC: x.screenCTC,
-                            bottleneck: x.bottleneckLayer,
-                        })),
-                        note: "Each screen is measured on ITS OWN content, and capacity carries forward -- screen 7 is scored against what screens 1-6 left, not against a fresh persona. Count-based demands (interactive elements, choices) charge only elements not seen on an earlier screen, so a sticky nav is one decision rather than one per screen; text and visual density are NOT deduplicated, because re-encountering text is re-reading it.",
-                        differsFrom: "The aggregate `abandonmentRisk` above asks what the whole document would cost if it were all processed. This asks how far they get. They are different questions and will not agree.",
-                        uncalibrated: "The per-screen hazard uses the same ABANDONMENT_HILL_EXPONENT as the aggregate, which nothing empirical set. At 2 the curve is superlinear, so this model inherits a thumb on the scale.",
-                        readThisFirst: "TRUST THE SHAPE, NOT THE TOTAL. `totalAbandonment` compounds a per-screen hazard across every screen, so on a long page it saturates toward 100% almost regardless of the page -- measured, elderly-user reached 100% on a 7-screen university homepage. That is the uncalibrated exponent compounding, not a finding about that page. `expectedDepthScreens` and `dropOff` are the numbers to act on: they say how far people get and what stops them, and both depend on the RANKING of per-screen hazards rather than their absolute level, which is the part the exponent least disturbs. `dropOff` is persona-dependent by design and that is not noise: an impatient reader drops on screen one, a patient one survives to whichever screen is genuinely hardest, and the two answers are both correct for their reader.",
-                    };
+                    perScreen = await extractPerScreenMetrics(page, 20, sharedGeometry);
                 }
                 catch (e) {
-                    sequentialResult = { error: `sequential pass failed: ${e.message}`, note: "The aggregate figures below are unaffected." };
+                    sequentialError = e.message;
                 }
             }
-            // Modulate demand by motivational values (opt-in, default off)
-            if (useValues)
-                try {
-                    // regPV2 writes the caller's account store, not the process-wide registry. (tenant, 2026-10-10)
-                    const { getPersonaValues, registerAccountPersonaValues: regPV2, createPersonaValues: createPV2 } = await import("../../values/index.js");
-                    let pValues = resolveValuesForPersona(personaName);
-                    // Custom persona CMS fallback
-                    if (!pValues) {
-                        try {
-                            const { getSessionApiKey } = await import("./cognitive-tools.js");
-                            const _sessionApiKey = getSessionApiKey();
-                            if (_sessionApiKey) {
-                                const cmsUrl = process.env.CMS_URL || "http://localhost:3200";
-                                const res = await fetch(`${cmsUrl}/api/personas`, { headers: { "Authorization": `Bearer ${_sessionApiKey}` } });
-                                if (res.ok) {
-                                    const data = await res.json();
-                                    const match = data.personas.find((p) => p.slug === personaName || p.name.toLowerCase() === personaName.toLowerCase());
-                                    if (match?.schwartz_values) {
-                                        const sv = typeof match.schwartz_values === "string" ? JSON.parse(match.schwartz_values) : match.schwartz_values;
-                                        const pv = createPV2({ selfDirection: sv.selfDirection ?? 0.5, stimulation: sv.stimulation ?? 0.5, hedonism: sv.hedonism ?? 0.5, achievement: sv.achievement ?? 0.5, power: sv.power ?? 0.5, security: sv.security ?? 0.5, conformity: sv.conformity ?? 0.5, tradition: sv.tradition ?? 0.5, benevolence: sv.benevolence ?? 0.5, universalism: sv.universalism ?? 0.5 }, { autonomyNeed: sv.autonomyNeed ?? 0.5, competenceNeed: sv.competenceNeed ?? 0.5, relatednessNeed: sv.relatednessNeed ?? 0.5 }, "esteem");
-                                        regPV2([{ personaName, values: pv, rationale: "Custom persona from CMS" }]);
-                                        pValues = pv;
-                                    }
-                                }
-                            }
-                        }
-                        catch { /* CMS fallback failed */ }
+            // The demand curves, the chain, the value modulation when useValues
+            // applied it, and the sequential curve when scope asks for it. These used
+            // to run under their own synchronous withProvenance, the only part of the
+            // answer the recorder could see while it was module state; the whole
+            // handler is one recording now (recordedAnswer), so this is just the
+            // computation, and the block reported below counts it with everything
+            // else the answer read. (2026-10-22)
+            const scored = (() => {
+                let seq;
+                let seqError = sequentialError;
+                if (perScreen) {
+                    try {
+                        seq = computeSequentialScrollCTC(otProfile, perScreen.map((m) => computeDemandDistribution(m, demandOptions)), chainOptions);
                     }
-                    if (pValues && demand.demands) {
-                        // Conservation (security+conformity+tradition)/3 amplifies decision layer
-                        const conservation = (pValues.security + pValues.conformity + pValues.tradition) / 3;
-                        // Openness (selfDirection+stimulation)/2 reduces decision cost (comfortable with choices)
-                        const openness = (pValues.selfDirection + pValues.stimulation) / 2;
-                        // Achievement amplifies frustration layer (impatience)
-                        const achMod = 1 + (pValues.achievement - 0.5) * 0.3;
-                        // Scale decision-related demands: satisficing, anchoringBias, riskTolerance, fearOfMissingOut
-                        const decisionScale = 1 + (conservation - openness) * 0.3; // -0.15 to +0.15 range
-                        for (const dim of ["satisficing", "anchoringBias", "riskTolerance", "fearOfMissingOut", "socialProofSensitivity"]) {
-                            if (demand.demands[dim] !== undefined) {
-                                demand.demands[dim] *= decisionScale;
-                            }
-                        }
-                        // Scale frustration-related demands
-                        for (const dim of ["resilience", "selfEfficacy", "emotionalContagion"]) {
-                            if (demand.demands[dim] !== undefined) {
-                                demand.demands[dim] *= achMod;
-                            }
-                        }
+                    catch (e) {
+                        seqError = e.message;
                     }
                 }
-                catch { /* values not available — proceed without */ }
-            const result = computeSequentialCTC(otProfile, demand, { asymmetric: true, interactions: true });
+                const demand = computeDemandDistribution(pageMetrics, demandOptions);
+                return { aggregate: computeSequentialCTC(otProfile, demand, chainOptions), seq, seqError };
+            })();
+            const result = scored.aggregate;
+            let sequentialResult;
+            if (scored.seq) {
+                const seq = scored.seq;
+                sequentialResult = {
+                    screensMeasured: seq.screens.length,
+                    // The INPUTS the screen count came from, published so a differing curve is
+                    // diagnosable instead of guessable. An external client measured 5.8 screens
+                    // on a session's first navigation and 6.7 on every later one; with only
+                    // `screensMeasured: 7` in the payload a 6-screen curve is internally
+                    // consistent and unmarked, which is the shape of every defect this tool has
+                    // had. An invisible variance is indistinguishable from no variance.
+                    geometry: {
+                        documentHeight: sharedGeometry.documentHeight,
+                        viewportHeight: sharedGeometry.viewportHeight,
+                        pageScreens: sharedGeometry.pageScreens,
+                        screenCount: sharedGeometry.screenCount,
+                        note: "One measurement, shared by the curve length and by the pageScreens caption, so the two cannot disagree. Page height can change between navigations; if two runs of the same URL differ, compare documentHeight before anything else.",
+                    },
+                    totalAbandonment: `${Math.round(seq.totalAbandonment * 100)}%`,
+                    expectedDepthScreens: seq.expectedDepthScreens,
+                    dropOff: seq.dropOff
+                        ? { screen: seq.dropOff.screen, layer: seq.dropOff.layer, shareOfSessions: `${Math.round(seq.dropOff.share * 100)}%` }
+                        : null,
+                    // The reach-weighted MEAN of the screens' percentiles: where the typical
+                    // screen this persona actually sees ranks. Replaces reachWeightedCTC,
+                    // the reach-weighted SUM, which grew with every screen reached and so
+                    // ranked a long page costlier for being long; a sum of percentiles is
+                    // not a percentile of anything. The chain still returns the sum.
+                    reachWeightedMeanScreenCTC: (() => {
+                        const reach = seq.screens.reduce((a, x) => a + x.reachProbability, 0);
+                        return reach > 0 ? Math.round((seq.screens.reduce((a, x) => a + x.reachProbability * x.screenCTC, 0) / reach) * 1000) / 1000 : null;
+                    })(),
+                    curve: seq.screens.map((x) => ({
+                        screen: x.screen,
+                        reach: `${Math.round(x.reachProbability * 100)}%`,
+                        stopHere: `${Math.round(x.stopHazard * 100)}%`,
+                        cumulativeAbandonment: `${Math.round(x.cumulativeAbandonment * 100)}%`,
+                        screenCTC: x.screenCTC,
+                        bottleneck: x.bottleneckLayer,
+                    })),
+                    note: "Each screen is measured on ITS OWN content, and capacity carries forward -- screen 7 is scored against what screens 1-6 left, not against a fresh persona. Count-based demands (interactive elements, choices) charge only elements not seen on an earlier screen, so a sticky nav is one decision rather than one per screen; text and visual density are NOT deduplicated, because re-encountering text is re-reading it.",
+                    screenCTCNote: "screenCTC is a percentile, like the aggregate total: the screen's raw cost ranked among the first screens of the real reference pages, scored for the built-in personas arriving fresh. A later screen is scored against the capacity earlier screens left, so its rank reflects that depletion as well as its own content. reachWeightedMeanScreenCTC averages the screens' percentiles, each weighted by the chance of reaching it: the rank of the typical screen this persona sees. It replaces reachWeightedCTC, an unnormalised sum that grew with the number of screens reached.",
+                    differsFrom: "The aggregate `abandonmentRisk` above asks what the whole document would cost if it were all processed. This asks how far they get. They are different questions and will not agree.",
+                    uncalibrated: "The per-screen hazard uses the same ABANDONMENT_HILL_EXPONENT as the aggregate, which nothing empirical set. At 2 the curve is superlinear, so this model inherits a thumb on the scale.",
+                    readThisFirst: "TRUST THE SHAPE, NOT THE TOTAL. `totalAbandonment` compounds a per-screen hazard across every screen, so on a long page it saturates toward 100% almost regardless of the page -- measured, elderly-user reached 100% on a 7-screen university homepage. That is the uncalibrated exponent compounding, not a finding about that page. `expectedDepthScreens` and `dropOff` are the numbers to act on: they say how far people get and what stops them, and both depend on the RANKING of per-screen hazards rather than their absolute level, which is the part the exponent least disturbs. `dropOff` is persona-dependent by design and that is not noise: an impatient reader drops on screen one, a patient one survives to whichever screen is genuinely hardest, and the two answers are both correct for their reader.",
+                };
+            }
+            else if (scored.seqError !== undefined) {
+                sequentialResult = { error: `sequential pass failed: ${scored.seqError}`, note: "The aggregate figures below are unaffected." };
+            }
             // Also compute motor and readability from formal models
             let motorResult = null;
             let readabilityResult = null;
@@ -1106,6 +1111,9 @@ Begin with the first persona: ${personas[0]}
                 return "";
             } };
             const redirected = !!landedUrl && hostOf(landedUrl) !== "" && hostOf(landedUrl) !== hostOf(url);
+            // Where the cost ranks among the real reference pages (ctc-bands.ts): the
+            // band, the rank sentence and the verdict all read this one value.
+            const rank = ctcRank(result);
             const response = {
                 url,
                 ...(redirected ? {
@@ -1113,27 +1121,61 @@ Begin with the first persona: ${personas[0]}
                     redirectNote: `Requested ${hostOf(url)} and landed on ${hostOf(landedUrl)}. Every number below describes ${hostOf(landedUrl)}.`,
                 } : { resolvedUrl: landedUrl }),
                 persona: personaName,
+                // Status counts of every registry constant the score read, and the ids
+                // of the hand-set ones. A placeholder here so the field keeps its place
+                // in the JSON; filled as the last step before serialising, so the block
+                // covers the whole score: page measurement, demand, chain, values,
+                // sequential curve and verdict. The saliency overlay, drawn as context,
+                // carries its own block on its layerOverlays entry.
+                modelProvenance: undefined,
+                // The scored persona's motor and reading rates, counted apart from the
+                // score's constants (they describe the persona).
+                personaRateProvenance: personaRateProvenance(personaRateIds),
+                // Stage B: the four law times the motor, decision, procedure and reading
+                // demands come from, beside the demand each makes against the budget.
+                lawTimes: lawTimesReport(pageMetrics, familiarity.value),
+                // Only when useValues asked for it, so a persona with no values is
+                // visibly scored without them rather than silently.
+                ...(useValues ? { valueModulation: valueModulationReport(schwartzValues) } : {}),
                 cognitiveTransportCost: {
+                    // A percentile (21.x): raw ranked among the real reference pages for
+                    // the built-in personas at the same scope. 0.8 is costlier than 80%.
                     total: Math.round(result.totalCTC * 1000) / 1000,
+                    // The 95% interval of that percentile across bootstrap resamples of
+                    // the reference pages: how firmly the reference fixes the rank.
+                    totalCTCInterval: result.totalCTCInterval.map((x) => Math.round(x * 1000) / 1000),
+                    band: rank.band,
+                    referenceScope: result.referenceScope,
+                    rank: rank.sentence,
+                    // The whole percents that sentence states, for a view to say the
+                    // same numbers. total and totalCTCInterval are rounded to three
+                    // places, and recomputed from them the rank can differ by a point
+                    // (cbrowser.ai: 0.8098 is stated 80 and shipped as 0.81). end names
+                    // the two ends, where the sentence states a place, not a percent.
+                    rankFigures: {
+                        percent: rank.percent,
+                        interval: rank.interval,
+                        end: result.totalCTC === 0 ? "cheapest" : result.totalCTC === 1 ? "costliest" : null,
+                    },
                     additive: Math.round(result.additiveCTC * 1000) / 1000,
-                    // The un-normalized cost. `total` is a sigmoid of this, so the two
-                    // are not interchangeable and any ratio must use `raw`.
+                    // The un-normalized cost. `total` is its percentile among real pages,
+                    // so the two are not interchangeable and any ratio must use `raw`.
                     raw: Math.round(result.rawCTC * 1000) / 1000,
                     // raw / additive — both in layer-cost units, so this is the genuine
                     // contribution of interactions and sequential depletion.
                     chainCoefficient: Math.round((result.rawCTC / Math.max(0.001, result.additiveCTC)) * 1000) / 1000,
                     /**
                      * @deprecated Use chainCoefficient. NOTE ITS VALUE CHANGED: this used
-                     * to divide `total` (a sigmoid, 0-1) by `additive` (a raw sum) and
+                     * to divide `total` (then a logistic, 0-1) by `additive` (a raw sum) and
                      * reported ~0.3-0.5, which read as the chain dampening by 60%. That
                      * was a unit error, not a measurement — it was reporting the sigmoid.
                      * Preserving the old number bit-for-bit would preserve a meaningless
                      * one, so this now carries the corrected value.
                      */
                     sequentialAmplification: Math.round((result.rawCTC / Math.max(0.001, result.additiveCTC)) * 1000) / 1000,
-                    chainNote: "chainCoefficient = raw / additive, both in layer-cost units. Above 1 means interactions and sequential depletion added cost. Re-measured 1.002-1.036 at EIGHT layers, after `motor` was split into target acquisition and sequence execution (2026-08-03). It was 1.003-1.054 at seven and 1.002-1.019 at six. The range narrowed rather than widening this time: splitting one layer into two halves each layer's per-step cost, so the same total is reached through smaller increments and less of it compounds. Real, and small. Do NOT compute total/additive — total is a sigmoid of raw and the ratio compares different units.",
+                    chainNote: "chainCoefficient = raw / additive, both in layer-cost units. Above 1 means interactions and sequential depletion added cost. Re-measured 1.002-1.036 at EIGHT layers, after `motor` was split into target acquisition and sequence execution (2026-08-03). It was 1.003-1.054 at seven and 1.002-1.019 at six. The range narrowed rather than widening this time: splitting one layer into two halves each layer's per-step cost, so the same total is reached through smaller increments and less of it compounds. Real, and small. Do NOT compute total/additive — total is the percentile of raw among the real reference pages, not a cost, and the ratio compares different units.",
                     interpretationBasis: "total",
-                    interpretationBands: "total < 0.3 comfortable, < 0.6 moderate, < 0.8 struggling, else likely abandon",
+                    interpretationBands: `total is a percentile of the real reference pages, banded ${ctcBandsDescription()}. The cut points are registered definitions (ctcBands.*), chosen as conventions and not fitted. A band is a rank among real pages: the CTC is untested against human data, so it says nothing about how a person experiences the page, and it is not an abandonment prediction (that is abandonmentRisk, a separate quantity). totalCTCInterval is the 95% interval of the percentile across bootstrap resamples of the reference pages: how firmly the reference pages fix the rank, not whether the cost is right.`,
                 },
                 layers: result.layers.map(l => ({
                     name: l.name,
@@ -1171,10 +1213,11 @@ Begin with the first persona: ${personas[0]}
                 abandonmentRisk: Math.round(result.abandonmentRisk * 100) + "%",
                 // Says out loud that these two are different constructs.
                 //
-                // A run can read "easy" on CTC and 53% on abandonment and both be
-                // correct, which looks like a contradiction and is not one:
-                // abandonmentRisk is a sigmoid of (deficit - 0.3*surplus) against this
-                // persona's blended patience and resilience, and never touches
+                // A run can rank in the lower half on CTC and read 53% on abandonment
+                // and both be correct, which looks like a contradiction and is not one:
+                // abandonmentRisk is a Hill hazard of the deficit (unmet demand; surplus
+                // no longer relieves it, 21.0) against the blended patience and
+                // resilience this persona has LEFT after the page (21.0), and never touches
                 // totalCTC. CTC asks how expensive the page is; abandonment asks
                 // whether THIS persona's tolerance runs out first. A page can be cheap
                 // in absolute terms and still exceed someone with little patience.
@@ -1219,7 +1262,7 @@ Begin with the first persona: ${personas[0]}
                                 pointingInputs: {
                                     fittsThroughput: Math.round(pp.throughput * 100) / 100,
                                     endpointDispersionPx: Math.round(((pp.sigmaX + pp.sigmaY) / 2) * 10) / 10,
-                                    note: "throughput drives movementTimeMs; dispersion drives hitProbability. motorCapacity weights throughput at 0.75, so the `motor` layer and `hitProbability` legitimately rank personas differently.",
+                                    note: "throughput drives movementTimeMs; dispersion drives hitProbability. motorCapacity is throughput / (throughput + 4.9 bits/s, the reference mouse throughput) and does not read dispersion, so the `motor` layer and `hitProbability` legitimately rank personas differently.",
                                 },
                                 note: "These two are additive and unweighted against each other. There is no empirical basis for a relative weighting between acquiring a target and executing a sequence, so none is applied - see MOTOR_LAYER_WEIGHTS, both 1.0 and marked uncalibrated.",
                             };
@@ -1277,7 +1320,7 @@ Begin with the first persona: ${personas[0]}
                         ...(readabilityResult.blocks.length > 0 ? {
                             hardestBlockPenaltyMs: readabilityResult.blocks
                                 .reduce((worst, b) => b.difficulty > worst.difficulty ? b : worst).penaltyBreakdown,
-                            penaltyNote: "hardestBlockPenaltyMs carries every component, including those that came to 0. A 0 means the component was evaluated and does not apply to this text -- crowding, for one, only begins below 16px (Pelli et al. 2004) -- not that it is unmodelled. crowdingSensitivity additionally carries a 0.15 weight into readingCapacity, which reaches the readability layer at every font size.",
+                            penaltyNote: "hardestBlockPenaltyMs carries every component, including those that came to 0. A 0 means the component was evaluated and does not apply to this text -- crowding, for one, only begins below 16px (Pelli et al. 2004) -- not that it is unmodelled. Since Stage B crowdingSensitivity does not enter readingCapacity: that is a rate ratio, from the persona's registered reading rate or, for a custom persona that states a reading profile, the fixation model's text-independent terms (base, phonological, visual span). Crowding is priced only here, in this audit's per-block time below 16px.",
                         } : {}),
                     },
                 } : {}),
@@ -1301,13 +1344,13 @@ Begin with the first persona: ${personas[0]}
                     const screens = pageMetrics.pageScreens > 1.2
                         ? `${wholeDocument ? " Measured across" : `${where}; the page is`} ${pageMetrics.pageScreens} screens${wholeDocument ? "." : ", so most of it was not measured — pass scope='full_page' for the whole thing.)"}${seqTail}`
                         : where ? `${where}.)` : seqTail;
-                    const verdict = result.totalCTC < 0.3
-                        ? `${personaName} should handle ${subject} comfortably.`
-                        : result.totalCTC < 0.6
-                            ? `${personaName} will experience moderate cognitive effort on ${subject}. Bottleneck: ${result.bottleneckLayer}.`
-                            : result.totalCTC < 0.8
-                                ? `${personaName} will struggle significantly with ${subject}. ${result.bottleneckLayer} is the primary barrier. Consider simplifying.`
-                                : `${personaName} is likely to abandon ${subject}. Cognitive transport cost is ${Math.round(result.totalCTC * 100)}%. Immediate remediation needed on ${result.bottleneckLayer}.`;
+                    // The rank, not a comfort claim. Through 21.0 this said "should handle
+                    // comfortably", "will struggle significantly" and "is likely to
+                    // abandon" off fixed points on a logistic nobody fitted; the CTC is
+                    // untested against human data, so a sentence on it can say where the
+                    // page ranks among real pages and nothing about how a person feels.
+                    // Abandonment stays in abandonmentRisk, its own quantity.
+                    const verdict = `For ${personaName}, ${subject} is ${rank.statement}. ${rank.bandSentence} Bottleneck: ${result.bottleneckLayer}.`;
                     return verdict + screens;
                 })(),
                 // ONE AUTHORITATIVE FIELD PER READING DIMENSION, stated rather than
@@ -1337,7 +1380,6 @@ Begin with the first persona: ${personas[0]}
                 scope: measureScope,
                 pageScreens: pageMetrics.pageScreens,
                 scopeNote: prose.scopeNote,
-                ...(familiarityWarning ? { familiarityWarning, siteFamiliarityAdjusted: true, originalFamiliarity: requestedFamiliarity, effectiveFamiliarity: traits.siteFamiliarity } : {}),
                 // Reports what was USED, not what was passed.
                 //
                 // This previously said "supplied for this run" whenever the caller sent
@@ -1347,13 +1389,12 @@ Begin with the first persona: ${personas[0]}
                 // asserting the parameter had been applied. An attestation nobody
                 // verifies is worse than no attestation, because it makes an
                 // output-level audit report the knob as working. (2026-08-02)
-                siteFamiliarity: traits.siteFamiliarity,
-                siteFamiliaritySource: familiarityFromCaller
-                    ? "supplied for this run"
-                    : hasSiteKnowledge
-                        ? "derived from this install's crawl of the site"
-                        : "defaulted to first visit — no site knowledge and none supplied",
-                siteFamiliarityEffect: `Consumed by the cognitiveLoad layer against a demand set by navigation depth. A page reachable in one click demands no site knowledge, so this changes nothing there.`,
+                siteFamiliarity: familiarity.value,
+                siteFamiliaritySource: familiarity.source,
+                // Reported, not applied: crawling a site says nothing about whether
+                // THIS persona has used it.
+                siteKnowledgeAvailable: familiarity.siteKnowledgeAvailable,
+                siteFamiliarityEffect: `Cockburn, Gutwin & Greenberg's (2007) expertise e on the choosing time: (1 - e) x novice visual search + e x the Hick-Hyman expert limit, so a familiar visitor is asked less search by every choice on the page. It moves the cognitiveLoad layer (convention knowledge, working memory, foraging, transfer), the same for every persona; the decision dispositions keep the first-visit time. It is not a persona trait. The score is still ranked against first visits (e = 0).`,
                 ...(languageWarning ? { languageWarning } : {}),
                 ...(userLocation ? { userContext: { location: userLocation, timezone: userTimezone, language: userLanguage } } : {}),
                 ...(token ? { _browserToken: token } : {}),
@@ -1367,6 +1408,7 @@ Begin with the first persona: ${personas[0]}
             let motorTemp;
             try {
                 if (motorResult && motorResult.elements.length > 0) {
+                    const { writeFileSync, mkdirSync, existsSync } = await import("fs");
                     motorTemp = await makeTempDir("cog-effort");
                     const ssPath = motorTemp.file("page.png");
                     await page.screenshot({ path: ssPath, fullPage: false });
@@ -1435,20 +1477,32 @@ Begin with the first persona: ${personas[0]}
                 layersTemp = await makeTempDir("cog-effort-layers");
                 const ssPath = layersTemp.file("page.png");
                 await page.screenshot({ path: ssPath, fullPage: false });
-                // saliency -- keyless. Lab-space centre-surround over the screenshot,
-                // so this needs no API key and no model call.
+                // visualComplexity -- keyless. Lab-space centre-surround over the
+                // screenshot, so this needs no API key and no model call. It is shown as
+                // visual context for the layer, NOT as its input: the layer's cost comes
+                // from the visual-complexity count and the animation level, and this map
+                // never reaches the chain. The legend says so, because the layer was
+                // called "saliency" until 21.0 and this heatmap read as its evidence.
                 try {
                     const { computeLabSaliency } = await import("../../visual/attention-transport.js");
                     const { generateHeatmapOverlay } = await import("../../visual/heatmap-overlay.js");
-                    const sal = await computeLabSaliency(ssPath);
-                    const b64 = await generateHeatmapOverlay(ssPath, sal.cells, sal.rows, sal.cols, `${personaName} — saliency`);
+                    // Recorded apart from the score. The map reads the attention model's
+                    // constants (published colour science, fitted gaze calibration), and
+                    // counted in modelProvenance they made the score look partly fitted
+                    // while the map is context, not an input. Its own block rides on
+                    // this overlay entry.
+                    const { result: b64, provenance: mapProvenance } = await isolatedProvenanceAsync(async () => {
+                        const sal = await computeLabSaliency(ssPath);
+                        return generateHeatmapOverlay(ssPath, sal.cells, sal.rows, sal.cols, `${personaName} — saliency`);
+                    }, ATTENTION_PROVENANCE_TEXT);
                     const w = writeArtifact(Buffer.from(b64, "base64"), `saliency-${personaName}-${Date.now()}.png`);
                     if (w)
-                        layerOverlays.push({ layer: "saliency", file: w.url.split("/").pop(), available: true,
-                            legend: "Hotter = more visually salient before any reading happens." });
+                        layerOverlays.push({ layer: "visualComplexity", file: w.url.split("/").pop(), available: true,
+                            legend: "Lab-space saliency of the screenshot, shown as context. Hotter = more visually salient. The layer's cost is not computed from this map: it comes from the page's visual-complexity count and animation level.",
+                            provenance: mapProvenance });
                 }
                 catch (e) {
-                    layerOverlays.push({ layer: "saliency", available: false, reason: `saliency map failed: ${e.message}` });
+                    layerOverlays.push({ layer: "visualComplexity", available: false, reason: `saliency map failed: ${e.message}` });
                 }
                 // motor -- already drawn above; surfaced here so the chain has one list.
                 if (response.motorOverlayUrl) {
@@ -1512,6 +1566,9 @@ Begin with the first persona: ${personas[0]}
                 response.layerOverlays = layerOverlays;
                 response.layerOverlayNote = "Each entry maps to a bar in the transport chain. Layers without an overlay say why.";
             }
+            // Last, so it covers everything above. Serialising the previews reads no
+            // registered constant.
+            response.modelProvenance = activeProvenance();
             const content = motorPng
                 ? await buildContentWithPreviews(response, [{ name: "motor", png: motorPng, fullResolution: motorFullResolution }], (p) => ({ motorOverlayPreview: p.motor }), { maxCharsPerImage: MOTOR_PREVIEW_MAX_CHARS })
                 : [{ type: "text", text: JSON.stringify(response, null, 2) }];
@@ -1537,6 +1594,6 @@ Begin with the first persona: ${personas[0]}
                     }],
             };
         }
-    });
+    }));
 }
 //# sourceMappingURL=persona-comparison-tools.js.map