cbrowser 18.79.0 → 18.81.0

package/dist/visual/cognitive-transport-chain.js

@@ -41,22 +41,67 @@ export const DEMAND_DIMENSIONS = [
     // Trust
     'trustCalibration',
     // Additional extended traits
-    'mentalModelRigidity', 'curiosity',
+    'mentalModelFlexibility', 'curiosity',
     // Processing
     'processingSpeed', 'textProcessing',
+    // Experience
+    //
+    // Absent until 2026-08-02, which is why the siteFamiliarity parameter was
+    // inert. It is a member of COGNITIVE_TRAITS, so a persona carried a capacity
+    // on this dimension, but the demand vector had no slot for it -- so the
+    // capacity was transported against a demand that did not exist and
+    // contributed nothing. Runs at familiarity 0 and 1 came back byte-identical
+    // while the tool attested the parameter had been applied.
+    //
+    // The two vectors are supposed to be the same space. A dimension present in
+    // one and missing from the other is silently dropped, and there is now a test
+    // asserting COGNITIVE_TRAITS and DEMAND_DIMENSIONS do not diverge.
+    'siteFamiliarity',
+    // Capacity, bridged from the formal reading and pointing models.
+    //
+    // These layers previously read DISPOSITION traits -- readingTendency for
+    // readability, patience and proceduralFluency for motor -- while the modules
+    // that actually model decoding and Fitts pointing sat beside them, computing
+    // WPM, visual span, phonological penalties, movement times and hit
+    // probabilities that no layer ever consumed. A dyslexic persona therefore
+    // scored LOWER readability cost than an ADHD persona on a text-dense page.
+    //
+    // `sustainedAttention` is the attentional half of reading, and it was missing
+    // from the model entirely. Taking `readingTendency` out of the readability
+    // layer left decoding and nothing else, so an ADHD reader -- whose decoding is
+    // typically intact and whose difficulty is holding the line -- read a wall of
+    // text at no attentional cost at all.
+    'readingCapacity', 'motorCapacity', 'sustainedAttention',
 ];
 /**
  * Layer definitions for the sequential transport chain.
  * Order reflects temporal processing: perception -> cognition -> decision -> action -> affect -> comprehension.
+ *
+ * Exported (2026-08-03) so that prose ABOUT the chain can be checked against the
+ * chain. Two served strings stated a layer count -- a tool description and the
+ * server's own instructions -- and they disagreed with each other and with this
+ * array, because nothing could compare them to it. The instructions still said
+ * "6-layer" two layers after the chain became eight, and an external client read it
+ * and reasoned about a six-layer model. A count in a served string is a claim about
+ * this list; a claim about a list should be checkable against the list.
  */
-const LAYER_DEFINITIONS = [
+export const LAYER_DEFINITIONS = [
     {
         name: 'saliency',
         traits: ['changeBlindness', 'attentionPattern'],
     },
     {
         name: 'cognitiveLoad',
-        traits: ['comprehension', 'workingMemory', 'informationForaging'],
+        // siteFamiliarity added 2026-08-02. It was in COGNITIVE_TRAITS and in no
+        // layer, so it reached the profile, got a capacity, and then contributed to
+        // nothing -- the third and final reason the parameter was inert. Knowing a
+        // site is a substitute for holding its layout in working memory, which is
+        // exactly this layer, and the demand term for it comes from the same
+        // navigationDepth signal that already feeds workingMemory here.
+        // `transferLearning` moved here from readability 2026-08-02: applying a
+        // pattern learned on one interface to another is a load question, not a
+        // decoding one, and readability is now decoding-only.
+        traits: ['comprehension', 'workingMemory', 'informationForaging', 'siteFamiliarity', 'transferLearning'],
     },
     {
         name: 'decision',
@@ -64,7 +109,48 @@ const LAYER_DEFINITIONS = [
     },
     {
         name: 'motor',
-        traits: ['patience', 'proceduralFluency'],
+        // POINTING ONLY, as of 2026-08-03 (D-9 resolution). This layer answers one
+        // question: how expensive is it for this person to ACQUIRE a target.
+        //
+        // It used to sum pointing capability and procedural execution at equal
+        // weight in one scalar, which is the same failure shape the readability
+        // layer had before it was split. Measured on identical demand:
+        //
+        //   motor-impairment-tremor  cost 0.072   hitProbability 48.4%
+        //   elderly-user             cost 0.107   hitProbability 81.9%
+        //
+        // Worse pointing, lower cost -- because the tremor persona's procedural
+        // fluency (0.60) outweighed its pointing deficit against elderly's 0.40.
+        // `motorAccessibility` is reported in the same response and tracks only
+        // pointing, so every ordering check against it read as broken.
+        //
+        // `proceduralFluency` moved to `motorProcedure` below. Nothing was weighted
+        // to achieve this: the two layers contribute additively like every other
+        // layer, which makes their relative contribution visible and inspectable
+        // rather than hidden inside a scalar. There is no empirical basis for a
+        // relative weighting between target acquisition and sequence execution, and
+        // a constant invented here would acquire false authority by ending up in a
+        // research instrument. The calibration slot is deliberately left empty --
+        // see MOTOR_LAYER_WEIGHTS.
+        traits: ['motorCapacity'],
+    },
+    {
+        name: 'motorProcedure',
+        // Executing an interaction SEQUENCE once a target has been acquired --
+        // multi-step flows, form progressions, anything where the cost is in the
+        // order of operations rather than in hitting the control.
+        //
+        // Separate from `motor` because the two genuinely move in opposite
+        // directions for the same persona, which is precisely what makes them
+        // separable rather than one number: a tremor persona can be a poor pointer
+        // and a competent sequence-follower, and an elderly persona the reverse.
+        //
+        // DEMAND IS ABSOLUTE, not area-normalised. The number of steps in a
+        // sequence does not shrink because the page is tall. Its demand derives
+        // from interactiveElementCount, which is a raw count -- so there is nothing
+        // to remove here today, and this is recorded for the D-12 layer
+        // classification table rather than decided silently in code.
+        traits: ['proceduralFluency'],
     },
     {
         name: 'frustration',
@@ -72,7 +158,53 @@ const LAYER_DEFINITIONS = [
     },
     {
         name: 'readability',
-        traits: ['readingTendency', 'comprehension', 'transferLearning'],
+        // DECODING ONLY, as of 2026-08-02 (D-3 Option 1). This layer answers one
+        // question -- how expensive is it for this person to turn these glyphs into
+        // words -- and it is the layer `legibilityQuality` makes a promise about:
+        // lower legibility for someone means higher readability cost for them.
+        //
+        // Everything else that was here has been moved out, and the history is why
+        // it had to be:
+        //
+        //   R1  adhd 0.401 / dyslexic 0.189   inverted   (disposition drove it)
+        //   R2  adhd 0.112 / dyslexic 0.142   correct    (attentional term removed)
+        //   R4  adhd 0.161 / dyslexic 0.126   inverted   (attentional term restored)
+        //
+        // Removing the attentional term fixed the ordering and deleted ADHD reading
+        // cost. Restoring it recovered ADHD reading cost and broke the ordering.
+        // BOTH were correct fixes. The layer was carrying two mechanisms through
+        // one scalar under a contract that only describes one of them, and no
+        // weighting satisfies both -- an ADHD attentionSpan of 0.30 against a
+        // dyslexic 0.50 swamps five decoding terms pointing the other way.
+        //
+        // So the second mechanism gets its own layer rather than a smaller weight.
+        // `sustainedAttention` moved to `readingAttention` below.
+        // `comprehension` moved out entirely: it is "grasp of UI conventions", not
+        // decoding, and it already drives cognitiveLoad -- keeping it here made the
+        // contract non-monotonic for personas whose comprehension and decoding
+        // disagree, which after the reading-capacity schema change is most of them.
+        // `transferLearning` moved to cognitiveLoad: applying a pattern learned on
+        // one interface to another is not reading. It is not orphaned by the move.
+        traits: ['readingCapacity'],
+    },
+    {
+        name: 'readingAttention',
+        // The attentional half of reading, split out of `readability` so both are
+        // separately attributable rather than summed into one number that can only
+        // be right about one of them.
+        //
+        // This is the layer an ADHD reader's cost lands in: decoding intact, loses
+        // place, re-reads, pulled off the line by movement in the periphery. It is
+        // NOT frustration -- losing your place is a processing cost, not an
+        // emotional response to one, and routing it through frustration would point
+        // remediation at reassurance instead of at chunking, shorter blocks and
+        // fewer moving distractors.
+        //
+        // Appended as layer 7 rather than inserted before readability, deliberately:
+        // layers spend from a budget the earlier ones depleted, so inserting would
+        // have changed readability's numbers through depletion as well as through
+        // its trait list, and the two effects could not be told apart.
+        traits: ['sustainedAttention'],
     },
 ];
 /**
@@ -89,10 +221,153 @@ const INTERACTION_PAIRS = [
 /** Asymmetric cost weights (Theorem 2 in paper) */
 const WEIGHT_DEFICIT = 1.0; // demand > capacity: high cost
 const WEIGHT_SURPLUS = 0.3; // capacity > demand: low cost (surplus is cheap)
+/**
+ * Dimensions where having MORE than the page asks for costs nothing at all.
+ *
+ * THE RULE, decided 2026-08-03, and it is derivable rather than chosen: surplus
+ * is FREE where the dimension's own `highEnd` names an ABILITY, and BILLED
+ * where it names a TENDENCY, a BIAS, or a SUSCEPTIBILITY. Read the trait
+ * reference and the classification falls out; a new dimension is classified by
+ * its own definition, not by anyone's taste.
+ *
+ * Why the split is real. Billing surplus is defensible for a disposition: a
+ * maximiser on a trivial page genuinely over-deliberates, and a careful reader
+ * genuinely reads a page that did not need reading. That is effort spent. It is
+ * NOT defensible for an ability -- having more working memory, or recognising
+ * conventions faster, than a page requires cannot make that page harder. The
+ * capacity/disposition axis is the same one that moved readingTendency to the
+ * demand side and kept comprehension out of the readability layer.
+ *
+ * What it was costing. Measured on a mid-density page before this change,
+ * SEVENTY PERCENT of `power-user`'s total cost was surplus, and 60% of
+ * `cognitive-adhd`'s. A uniform-capacity sweep produced a U:
+ *
+ *   capacity  0.2    0.4    0.6    0.8    1.0
+ *   cost      0.549  0.081  0.076  0.179  0.516
+ *
+ * A maximally capable persona scored almost exactly as badly as a maximally
+ * impaired one, for opposite reasons, and the output could not tell you which.
+ * That is the same defect as every other one this campaign found: a number that
+ * does not mean what its name says.
+ *
+ * Four dimensions are billed BECAUSE THEIR SCALE IS INVERTED -- changeBlindness,
+ * trustCalibration, curiosity and attentionPattern name a deficit at their high
+ * end ("misses most changes", "accepts claims at face value", "easily
+ * distracted"). Surplus there is more of the deficit, and billing it is
+ * correct.
+ *
+ * `selfEfficacy` is the weakest call in the free set: over-confidence is a real
+ * hazard, but its cost surfaces through riskTolerance and trustCalibration
+ * rather than as effort spent, so it is treated as the ability its high end
+ * describes.
+ */
+const SURPLUS_FREE_DIMENSIONS = new Set([
+    // Derived capacity bridges -- pure abilities by construction.
+    'readingCapacity', 'motorCapacity', 'sustainedAttention', 'processingSpeed', 'textProcessing', 'motorPrecision',
+    // Experience. Knowing a site better cannot make it harder to use.
+    'siteFamiliarity',
+    // Abilities: every one of these has a highEnd naming something a person CAN
+    // do, not something they TEND to do.
+    'comprehension', // "Instant recognition of all conventions"
+    'workingMemory', // "Perfect recall of all attempts and context"
+    'resilience', // "Instantly shrugs off errors, stays positive"
+    'selfEfficacy', // "I can solve anything"
+    'proceduralFluency', // "Follows procedures precisely and efficiently"
+    'transferLearning', // "Instantly applies patterns across all interfaces"
+    'interruptRecovery', // "Seamlessly resumes exactly where left off"
+    'mentalModelFlexibility', // "Highly adaptive - quickly forms new mental models"
+    'informationForaging', // "Follows information scent efficiently, abandons low-yield paths"
+]);
+/**
+ * Dimensions whose surplus IS billed, and why each one earns it.
+ *
+ * Stated explicitly rather than left as "everything else", so that a dimension
+ * added to DEMAND_DIMENSIONS cannot acquire a billing treatment by default. A
+ * test asserts every dimension appears in exactly one of the two sets.
+ */
+const SURPLUS_BILLED_DIMENSIONS = new Set([
+    'patience', // "Waits indefinitely" -- waiting longer than needed is time spent
+    'riskTolerance', // "Clicks anything that might work" -- a tendency, and a hazard
+    'persistence', // "Keeps trying same approach repeatedly" -- repeating unnecessary work
+    'readingTendency', // "Reads every word before acting" -- reading a page that did not need it
+    'emotionalContagion', // susceptibility to the interface's tone
+    'satisficing', // a decision STRATEGY, not an ability
+    'anchoringBias', // a bias, by name
+    'fearOfMissingOut', // susceptibility to urgency and scarcity
+    'socialProofSensitivity', // susceptibility to what others chose
+    'metacognitivePlanning', // "Careful planning before any action" -- planning a trivial page is waste
+    // Inverted scales: the HIGH end is the deficit, so surplus is more deficit.
+    'changeBlindness', // "Misses most changes outside focus area"
+    'trustCalibration', // "Highly trusting, accepts claims at face value"
+    'curiosity', // "Easily distracted by interesting elements"
+    'attentionPattern', // scanning-vs-thorough disposition
+]);
+/**
+ * Hill exponent on the abandonment curve. UNCALIBRATED.
+ *
+ * Same status as MOTOR_LAYER_WEIGHTS and flagged for the same reason: it is
+ * doing a great deal of work and nothing empirical set it. At 2 the curve is
+ * superlinear, which means the same total cost delivered in small increments
+ * barely registers -- splitting a fixed deficit of 0.607 across 14 steps takes
+ * cumulative abandonment from 22% to 2%.
+ *
+ * That matters beyond the scalar. Any future per-screen hazard model inherits
+ * this exponent, and at 2 it would make a long page SAFER than a short one with
+ * identical total demand purely from chunking. The exponent is not the fix for
+ * that -- per-screen demand measured on its own content is -- but a sequential
+ * model must not be built without knowing this constant is load-bearing.
+ *
+ * What would settle it: observed abandonment against measured task difficulty,
+ * or a dose-response fit on real session data. Until then it is a shape someone
+ * chose, not a shape anyone measured. (2026-08-03)
+ */
+export const ABANDONMENT_HILL_EXPONENT = 2;
+/**
+ * Relative weighting between the two motor layers. BOTH DEFAULT TO 1.0 AND ARE
+ * UNCALIBRATED.
+ *
+ * They exist as named constants so that if a weighting is ever introduced it is
+ * visible, greppable and dated, rather than baked into the cost function as a
+ * bare multiplier. Nothing reads them today; the layers contribute additively
+ * like every other layer.
+ *
+ * What would settle them: motor-control literature on tremor adaptation in
+ * target acquisition, or validation of chain output against measured
+ * task-completion times. Until one of those exists, a number here would be an
+ * invention wearing the authority of a research instrument. (2026-08-03)
+ */
+export const MOTOR_LAYER_WEIGHTS = {
+    /** UNCALIBRATED. Target acquisition. */
+    motor: 1.0,
+    /** UNCALIBRATED. Sequence execution. */
+    motorProcedure: 1.0,
+};
 /** Capacity depletion rate per layer (alpha_i, Section 3.4) */
 const DEPLETION_RATE = 0.15;
 /** Minimum residual capacity floor (prevents total exhaustion) */
 const CAPACITY_FLOOR = 0.05;
+/**
+ * Numerical floor on residual capacity. NOT a behavioural limit.
+ *
+ * CAPACITY_FLOOR above was doing behavioural work it should not have: at 0.05
+ * it was reachable inside a single page, and once reached the account stopped
+ * responding to cost at all. Proportional drawdown asymptotes toward zero
+ * instead, so this exists only to keep the value away from denormals and to
+ * keep `gap = demand - capacity` finite. It is three orders of magnitude below
+ * anything a persona reaches in practice. (2026-08-03)
+ */
+const CAPACITY_EPSILON = 1e-4;
+/**
+ * Largest fraction of remaining capacity one layer may draw. UNCALIBRATED.
+ *
+ * Prevents a single very expensive layer from emptying the account outright,
+ * which would reintroduce the saturation this replaced. 0.5 means no layer can
+ * take more than half of what is left, whatever its cost.
+ *
+ * What would settle it: within-session effort measurements across a task
+ * sequence. Same status as ABANDONMENT_HILL_EXPONENT and MOTOR_LAYER_WEIGHTS.
+ */
+const MAX_DRAWDOWN_FRACTION = 0.5;
 // ── Sigmoid Helper ──
 /**
  * Standard logistic sigmoid for mapping raw page metrics to demand values.
@@ -152,13 +427,13 @@ export function computeDemandDistribution(pageMetrics) {
     variance.workingMemory += infoDensity * 0.08;
     variance.readingTendency += infoDensity * 0.07;
     variance.informationForaging += infoDensity * 0.06;
-    // ── visualComplexity → changeBlindness, mentalModelRigidity, attentionPattern (inferred)
+    // ── visualComplexity → changeBlindness, mentalModelFlexibility, attentionPattern (inferred)
     const visDemand = visCplx; // already 0-1 from logScale
     demands.changeBlindness = Math.max(demands.changeBlindness, visDemand);
-    demands.mentalModelRigidity = Math.max(demands.mentalModelRigidity, visDemand * 0.7);
+    demands.mentalModelFlexibility = Math.max(demands.mentalModelFlexibility, visDemand * 0.7);
     demands.attentionPattern = Math.max(demands.attentionPattern, visDemand * 0.85);
     variance.changeBlindness += visCplx * 0.12;
-    variance.mentalModelRigidity += visCplx * 0.08;
+    variance.mentalModelFlexibility += visCplx * 0.08;
     variance.attentionPattern += visCplx * 0.1;
     // ── interactiveElementCount → riskTolerance, satisficing, proceduralFluency, motorPrecision (inferred)
     // Use logScale for element count — 20 elements = 0.5, 100 = 0.83, 500 = 0.96
@@ -211,14 +486,14 @@ export function computeDemandDistribution(pageMetrics) {
         demands.readingTendency = Math.max(demands.readingTendency, longWordR * 0.9);
         demands.comprehension = Math.max(demands.comprehension, longWordR * 0.8);
         variance.readingTendency += longWordR * 0.11;
-        // technicalDensity → comprehension, transferLearning, mentalModelRigidity
+        // technicalDensity → comprehension, transferLearning, mentalModelFlexibility
         // 10+ character words signal compound terms, jargon, domain-specific vocabulary
         demands.comprehension = Math.max(demands.comprehension, techDens * 0.95);
         demands.transferLearning = Math.max(demands.transferLearning, techDens * 0.8);
-        demands.mentalModelRigidity = Math.max(demands.mentalModelRigidity, techDens * 0.7);
+        demands.mentalModelFlexibility = Math.max(demands.mentalModelFlexibility, techDens * 0.7);
         variance.comprehension += techDens * 0.13;
         variance.transferLearning += techDens * 0.09;
-        variance.mentalModelRigidity += techDens * 0.07;
+        variance.mentalModelFlexibility += techDens * 0.07;
     }
     // ── animationLevel → changeBlindness, interruptRecovery, emotionalContagion
     const animDemand = sigmoid(animLevel, 0.3, 0.15);
@@ -228,6 +503,34 @@ export function computeDemandDistribution(pageMetrics) {
     variance.changeBlindness += animLevel * 0.1;
     variance.interruptRecovery += animLevel * 0.09;
     variance.emotionalContagion += animLevel * 0.07;
+    // ── textDensity × distractor pressure → sustainedAttention
+    //
+    // How much attention the page asks you to HOLD, as opposed to how hard its
+    // words are to decode (readingCapacity) or how much of it you choose to read
+    // (readingTendency, which modulates demand below). Gated on text: a page with
+    // no prose asks nothing here, however busy it is, because there is no line to
+    // lose your place in.
+    //
+    // Multiplicative rather than this file's usual `max`, deliberately -- the
+    // interaction IS the mechanism. A long article with nothing moving on it is
+    // readable; the same article beside an autoplaying carousel is where the
+    // re-reading happens. Two `max` terms would score those two pages the same.
+    //
+    // Animation dominates the distractor term because moving peripheral content
+    // captures attention involuntarily, while static clutter merely competes for
+    // it (Yantis & Jonides 1990 on abrupt-onset capture).
+    //
+    // The 0.7 base sits deliberately BELOW readingCapacity's 0.9: on a page with
+    // nothing moving, decoding is the larger demand of text and attention is the
+    // secondary one. The distractor multiplier is what lets it overtake decoding,
+    // and only on a page that has earned it. Without that ordering this dimension
+    // re-creates the exact inversion that removing readingTendency fixed --
+    // measured: at a flat 1.0 base, ADHD outscored dyslexic on readability on a
+    // page with animationLevel 0, which is the wrong answer.
+    const distractorPressure = Math.min(1, animDemand * 0.7 + visDemand * 0.3);
+    const sustainDemand = Math.min(1, textDemand * 0.7 * (1 + distractorPressure * 0.7));
+    demands.sustainedAttention = Math.max(demands.sustainedAttention, sustainDemand);
+    variance.sustainedAttention += textDens * 0.1 + animLevel * 0.08;
     // ── choiceCount → satisficing, anchoringBias, fearOfMissingOut, socialProofSensitivity
     // LogScale: 10 choices = 0.5, 30 = 0.75, 100 = 0.91
     const choiceDemand = choices / (choices + 10);
@@ -246,6 +549,31 @@ export function computeDemandDistribution(pageMetrics) {
     demands.metacognitivePlanning = Math.max(demands.metacognitivePlanning, navDemand * 0.8);
     demands.persistence = Math.max(demands.persistence, navDemand * 0.7);
     demands.transferLearning = Math.max(demands.transferLearning, navDemand * 0.65);
+    // ── navigationDepth → siteFamiliarity
+    //
+    // This dimension had NO demand term at all. It was initialised to 0 and never
+    // raised, so the persona's familiarity was transported against zero demand and
+    // contributed exactly nothing to the chain — three runs at familiarity unset,
+    // 1 and 0 returned byte-identical results while the tool reported the
+    // parameter as applied. The value was never overridden; nothing ever asked
+    // for it.
+    //
+    // Navigation depth is the honest driver: the further content sits from the
+    // entry point, the more the page asks you to already know where things are.
+    // A one-click page demands no site knowledge no matter who you are, which is
+    // why this is proportional to navDemand rather than a constant. Weighted just
+    // under workingMemory (0.95), since knowing the layout substitutes for
+    // holding it in mind. (2026-08-02)
+    demands.siteFamiliarity = Math.max(demands.siteFamiliarity, navDemand * 0.85);
+    // Reading capacity is demanded by how much text there is to decode, and motor
+    // capacity by how many things there are to hit. Both proportional, so a page
+    // with no text asks nothing of decoding and a page with no controls asks
+    // nothing of pointing.
+    demands.readingCapacity = Math.max(demands.readingCapacity, Math.max(textDens, infoDensity) * 0.9);
+    demands.motorCapacity = Math.max(demands.motorCapacity, interDemand * 0.9);
+    variance.readingCapacity += textDens * 0.08;
+    variance.motorCapacity += interDemand * 0.08;
+    variance.siteFamiliarity += Math.min(1, navDepth / 5) * 0.08;
     variance.workingMemory += Math.min(1, navDepth / 5) * 0.09;
     variance.metacognitivePlanning += Math.min(1, navDepth / 5) * 0.07;
     variance.persistence += Math.min(1, navDepth / 5) * 0.06;
@@ -325,8 +653,8 @@ const VALUE_DEMAND_MODULATION = [
     { value: 'selfDirection', trait: 'socialProofSensitivity', coefficient: -0.20, layer: 'decision' },
     // Self-Direction → amplifies metacognitive planning (plan their own path)
     { value: 'selfDirection', trait: 'metacognitivePlanning', coefficient: -0.15, layer: 'cognitiveLoad' },
-    // Tradition → amplifies mentalModelRigidity (resist new UI patterns)
-    { value: 'tradition', trait: 'mentalModelRigidity', coefficient: 0.25, layer: 'cognitiveLoad' },
+    // Tradition → amplifies mentalModelFlexibility (resist new UI patterns)
+    { value: 'tradition', trait: 'mentalModelFlexibility', coefficient: 0.25, layer: 'cognitiveLoad' },
     // Benevolence → reduces emotionalContagion cost (emotionally regulated)
     { value: 'benevolence', trait: 'emotionalContagion', coefficient: -0.15, layer: 'frustration' },
     // Power → reduces fear of missing out (confident, not swayed by urgency)
@@ -365,6 +693,46 @@ export function computeSequentialCTC(persona, demand, options) {
         demands: { ...demand.demands },
         variance: { ...demand.variance },
     };
+    // readingTendency modulates DEMAND, not capacity.
+    //
+    // It was in the readability layer as a capacity and inverted it: an ADHD
+    // persona who skims (0.2) scored a large capacity deficit against text
+    // demand, so a text-dense page cost them MORE than a dyslexic reader at 0.4,
+    // while the same run reported the dyslexic reader at 157 WPM against 204.
+    //
+    // The trait is not an ability, it is a STRATEGY -- its own criteria are
+    // "skims, reads carefully, scans for buttons" -- and skimming is how someone
+    // spends less effort on text, not evidence they cannot decode it. On the
+    // demand side that reads correctly: a skimmer engages less of the page's text,
+    // a careful reader engages more.
+    //
+    // Bounded to +/-25% around neutral, for two reasons. A skimmer still has to
+    // find the content, so demand cannot fall toward zero. And an unbounded
+    // modulator would recreate the very inversion this fixes by letting strategy
+    // outweigh decoding ability -- verified it does not: dyslexic still costs more
+    // than ADHD on a text-dense page after this. (2026-08-02)
+    const readingTendency = persona.traits?.readingTendency;
+    if (typeof readingTendency === "number") {
+        const engagement = 0.75 + readingTendency * 0.5; // 0.75 at pure skim, 1.25 at careful
+        // ATTENTIONAL demand only. Applied to `readingCapacity` as well for one
+        // commit, and that was wrong on the merits as well as breaking a contract.
+        //
+        // Engagement is how much of the page you read. That scales how long you
+        // must hold the line -- genuinely an attentional quantity -- but it does
+        // not change how hard the words you do read are to decode. Skimming reduces
+        // exposure, not difficulty.
+        //
+        // It also made decoding demand persona-specific, which silently voided the
+        // `legibilityQuality` contract the readability layer prints in its own
+        // output: measured, `distracted-user` at legibility 0.619 paid 0.000 while
+        // `careful-reader` at 0.724 paid 0.016 -- lower legibility, lower cost --
+        // purely because the skimmer's demand had been scaled down. A contract
+        // stated cross-persona has to be computed against a demand that does not
+        // vary by persona. (2026-08-02)
+        if (modulatedDemand.demands.sustainedAttention) {
+            modulatedDemand.demands.sustainedAttention = Math.max(0, Math.min(1, modulatedDemand.demands.sustainedAttention * engagement));
+        }
+    }
     if (values && Object.keys(values).length > 0) {
         for (const mod of VALUE_DEMAND_MODULATION) {
             const valueScore = values[mod.value];
@@ -381,7 +749,7 @@ export function computeSequentialCTC(persona, demand, options) {
     // Initialize residual capacity from persona traits
     const residualCapacity = {};
     for (const dim of DEMAND_DIMENSIONS) {
-        residualCapacity[dim] = traitValue(persona.traits, dim);
+        residualCapacity[dim] = options?.carriedCapacity?.[dim] ?? traitValue(persona.traits, dim);
     }
     const layers = [];
     const traitCosts = {};
@@ -398,6 +766,14 @@ export function computeSequentialCTC(persona, demand, options) {
         let layerDeficit = 0;
         let layerSurplus = 0;
         // Compute transport cost for this layer's traits (using modulated demands)
+        //
+        // Headroom is tracked alongside cost because a surplus-free layer reports a
+        // bare 0 across its whole upper range and stops discriminating there. A
+        // reader at 91% legibility and one at 99% both cost 0 on a page neither of
+        // them struggles with -- true, and useless as a signal. Headroom is the
+        // spare capacity that produced the zero, so the upper range is readable
+        // without inventing a cost that is not there. (2026-08-03, BUG-18)
+        let layerHeadroom = 0;
         for (const trait of layerDef.traits) {
             const d = modulatedDemand.demands[trait] ?? 0;
             const c = residualCapacity[trait] ?? 0.5;
@@ -410,12 +786,16 @@ export function computeSequentialCTC(persona, demand, options) {
             }
             else {
                 // Surplus: capacity exceeds demand — cheap
-                cost = (useAsymmetric ? WEIGHT_SURPLUS : 1.0) * gap * gap;
+                const surplusWeight = SURPLUS_FREE_DIMENSIONS.has(trait) ? 0 : WEIGHT_SURPLUS;
+                cost = (useAsymmetric ? surplusWeight : 1.0) * gap * gap;
                 layerSurplus += cost;
             }
+            if (gap < 0)
+                layerHeadroom += -gap;
             layerCost += cost;
             traitCosts[trait] = (traitCosts[trait] ?? 0) + cost;
         }
+        layerHeadroom = layerHeadroom / Math.max(1, layerDef.traits.length);
         // Scale layer cost by demand presence — empty pages shouldn't produce high costs
         const layerDemandMagnitude = layerDef.traits.reduce((sum, t) => sum + (modulatedDemand.demands[t] ?? 0), 0) / layerDef.traits.length;
         const contentScale = Math.min(1.0, layerDemandMagnitude * 3); // 0-1 scale, saturates at demand=0.33
@@ -429,17 +809,40 @@ export function computeSequentialCTC(persona, demand, options) {
         // Each trait in this layer loses capacity proportional to the layer's total cost
         const capacityConsumed = DEPLETION_RATE * layerCost;
         if (contentScale > 0.1) {
+            // PROPORTIONAL DRAWDOWN, not subtraction against a clamp.
+            //
+            // Capacity used to be spent as a flat amount and clamped at
+            // CAPACITY_FLOOR, which meant the account did not deplete -- it hit a
+            // wall and stopped carrying information. Measured on a dense page in a
+            // single eight-layer run: `intellectual-disability` finished with TEN
+            // dimensions pinned at exactly 0.05 and `elderly-user` with five. Every
+            // layer after that point saw an identical capacity vector, so the chain
+            // could no longer tell them apart. The personas the accessibility model
+            // exists to describe were the ones whose vector collapsed to a constant.
+            //
+            // Spending a FRACTION of what remains asymptotes toward zero instead of
+            // reaching it. A full account gives up more per unit cost than an empty
+            // one, the balance stays strictly ordered and strictly decreasing, and
+            // every later step is still distinguishable from the one before it.
+            // Measured over 112 steps: the clamped form produced 1 distinct value
+            // across the final four screens, this produces 32 of 32.
+            //
+            // This also makes the sequential model well-posed. Chaining screens is
+            // now just more draws on the same account, with no wall to hit at screen
+            // three and no `k` anywhere in the arithmetic. (2026-08-03)
+            const drawFraction = Math.min(MAX_DRAWDOWN_FRACTION, DEPLETION_RATE * layerCost);
             for (const trait of layerDef.traits) {
-                residualCapacity[trait] -= capacityConsumed;
-                residualCapacity[trait] = Math.max(CAPACITY_FLOOR, residualCapacity[trait]);
+                residualCapacity[trait] *= (1 - drawFraction);
+                residualCapacity[trait] = Math.max(CAPACITY_EPSILON, residualCapacity[trait]);
             }
             // Also deplete shared traits that appear in later layers
             // (cross-layer fatigue: cognitive exhaustion bleeds across boundaries)
+            const indirectFraction = Math.min(MAX_DRAWDOWN_FRACTION, (DEPLETION_RATE * 0.5) * layerCost);
             for (const dim of DEMAND_DIMENSIONS) {
                 if (!layerDef.traits.includes(dim)) {
                     // Indirect depletion at half rate
-                    residualCapacity[dim] -= (DEPLETION_RATE * 0.5) * layerCost;
-                    residualCapacity[dim] = Math.max(CAPACITY_FLOOR, residualCapacity[dim]);
+                    residualCapacity[dim] *= (1 - indirectFraction);
+                    residualCapacity[dim] = Math.max(CAPACITY_EPSILON, residualCapacity[dim]);
                 }
             }
         }
@@ -448,6 +851,10 @@ export function computeSequentialCTC(persona, demand, options) {
             transportCost: layerCost,
             capacityConsumed,
             residualCapacity: { ...residualCapacity },
+            // Mean spare capacity across this layer's dimensions. Only meaningful
+            // when the cost is at or near zero; above that the cost carries the
+            // signal itself.
+            headroom: Math.round(layerHeadroom * 1000) / 1000,
         });
     }
     // Compute interaction terms
@@ -485,18 +892,47 @@ export function computeSequentialCTC(persona, demand, options) {
             bottleneckLayer = layer.name;
         }
     }
-    // Compute abandonment risk
-    // Based on deficit relative to patience capacity
-    // deficit < 0.5 → risk < 30%, deficit ≈ patience → risk ≈ 50%, deficit >> patience → risk → 100%
+    // Compute abandonment risk.
+    //
+    // A page that costs this persona NOTHING must produce a risk of zero. The
+    // previous shape could not: it was a logistic centred at 1.5x tolerance, and
+    // a logistic evaluated below its centre still returns a substantial value, so
+    // every persona carried a floor that no page could lower. Measured:
+    //
+    //   persona          risk at deficit 0    real range over these pages (0-0.28)
+    //   impatient-user               40%              40% -> 52%
+    //   cognitive-adhd               34%              34% -> 45%
+    //   power-user                   25%              25% -> 34%
+    //   elderly-user                 11%              11% -> 16%
+    //   perfect patience              8%                    --
+    //
+    // So "39% abandonment" beside "should handle this page comfortably" was never
+    // two independent measures disagreeing. It was one number that is ~85% floor
+    // and ~15% page. The reported fix -- fold abandonment into the verdict --
+    // would have made it worse, importing a near-constant into the sentence so
+    // that every ADHD run read as risky regardless of the page.
+    //
+    // Replaced with a Hill function: zero cost gives exactly zero risk, cost
+    // equal to tolerance gives 50%, and it approaches 1 from below. The
+    // "centre at 1.5x blended patience" intent is unchanged and so is the
+    // persona ordering; what is gone is the offset. (2026-08-03, BUG-17)
     const patienceCapacity = traitValue(persona.traits, 'patience');
     const resilienceCapacity = traitValue(persona.traits, 'resilience');
     const effectivePatience = patienceCapacity * 0.7 + resilienceCapacity * 0.3; // blended tolerance
-    const adjustedCost = totalDeficit - totalSurplus * 0.3; // surplus comfort (30%)
-    const riskInput = Math.max(0, adjustedCost) - effectivePatience * 1.5; // center at 1.5x patience
-    const abandonmentRisk = Math.max(0, Math.min(1, 1 / (1 + Math.exp(-riskInput / 0.6)) // wider sigmoid scale
-    ));
+    const adjustedCost = Math.max(0, totalDeficit - totalSurplus * 0.3); // surplus comfort (30%)
+    // Floored so a persona with no patience at all does not divide by zero and
+    // read as certain abandonment on a blank page.
+    const tolerance = Math.max(0.05, effectivePatience * 1.5);
+    const ABANDONMENT_STEEPNESS = ABANDONMENT_HILL_EXPONENT;
+    const abandonmentRisk = adjustedCost <= 0 ? 0 : Math.max(0, Math.min(1, Math.pow(adjustedCost, ABANDONMENT_STEEPNESS) /
+        (Math.pow(adjustedCost, ABANDONMENT_STEEPNESS) + Math.pow(tolerance, ABANDONMENT_STEEPNESS))));
     return {
         totalCTC,
+        // The un-normalized cost, exposed because totalCTC is a SIGMOID of it and
+        // the two are not interchangeable. Every ratio against additiveCTC has to
+        // use this one: additiveCTC is a raw sum, totalCTC is squashed to 0-1, and
+        // dividing one by the other compares different units. (2026-08-02)
+        rawCTC,
         layers,
         interactions,
         additiveCTC,
@@ -505,6 +941,7 @@ export function computeSequentialCTC(persona, demand, options) {
         traitCosts,
         bottleneckLayer,
         abandonmentRisk,
+        remainingCapacity: { ...residualCapacity },
     };
 }
 // ── 3. Convenience: Full COT Pipeline ──
@@ -551,15 +988,39 @@ export function computeDemandFromRawMetrics(informationDensity, visualComplexity
 /**
  * Compare sequential vs. additive CTC to quantify the sequential effect.
  *
- * Returns the ratio (sequential / additive). Values > 1.0 indicate that
- * capacity depletion and interactions amplify the total cost beyond what
- * independent layers would predict.
+ * Returns rawCTC / additiveCTC -- both in layer-cost units.
+ *
+ * NAMED FOR WHAT IT DOES, NOT WHAT IT WAS EXPECTED TO DO. The old name,
+ * `sequentialAmplification`, promised a value above 1.0 — depletion and
+ * interactions pushing total cost past what independent layers would predict.
+ * Measured across five real runs it was 0.30, 0.31 and 0.39: the chain
+ * ATTENUATES the additive sum by 61-70%, and has never been observed above 1.
+ *
+ * The transform is saturating rather than corrupting: the coefficient rises
+ * monotonically with the additive sum (0.30 -> 0.31 -> 0.39), so rank ordering
+ * across personas and pages is preserved and comparative claims built on CTC
+ * hold. What does not hold is any reading of an ABSOLUTE cost, which carries an
+ * undocumented compression of roughly 3x.
+ *
+ * "Amplification" for a term that only ever shrinks actively misleads anyone
+ * reading the JSON without the source, which is most readers. (2026-08-02)
  */
-export function sequentialAmplification(result) {
+export function chainCoefficient(result) {
     if (result.additiveCTC === 0)
         return 1.0;
-    return result.totalCTC / result.additiveCTC;
+    // rawCTC, NOT totalCTC. Both are in layer-cost units, so their ratio is the
+    // actual contribution of interactions and sequential depletion. Measured
+    // 1.002-1.019 across page densities: the chain does amplify, by 0.2-2%.
+    //
+    // The old form divided totalCTC (a sigmoid, 0-1) by additiveCTC (a raw,
+    // unbounded sum) and reported 0.30-0.56 as if the chain were dampening by
+    // 60%. It was not measuring the chain at all, it was measuring the sigmoid --
+    // and it was not even monotonic across density (0.329, 0.399, 0.556, 0.313,
+    // 0.425), so it could not be used for ranking either.
+    return result.rawCTC / result.additiveCTC;
 }
+/** @deprecated Misleading name — it has never exceeded 1. Use `chainCoefficient`. */
+export const sequentialAmplification = chainCoefficient;
 /**
  * Identify the top N most costly traits across all layers.
  * Useful for targeted remediation — fix the traits that hurt most.
@@ -586,4 +1047,79 @@ export function baselineCTC(persona) {
     }
     return computeSequentialCTC(persona, emptyDemand);
 }
+/**
+ * Score a page as a SEQUENCE of screens rather than one aggregate.
+ *
+ * The aggregate model answers "what would this cost if the whole document were
+ * processed at once", which is a counterfactual almost nobody performs. This
+ * answers the question customers actually have: where do people stop.
+ *
+ * Three things make it different from dividing the aggregate by k, which was
+ * the obvious wrong implementation:
+ *
+ * 1. EACH SCREEN'S DEMAND IS MEASURED ON ITS OWN CONTENT. Splitting a fixed
+ *    total across k screens makes long pages safer than short ones -- measured,
+ *    a deficit of 0.607 split fourteen ways drops cumulative abandonment from
+ *    22% to 2%, because the hazard is superlinear. A genuinely sparse long page
+ *    SHOULD be safer; a dense one must not become safe by being tall.
+ * 2. CAPACITY CARRIES FORWARD. Screen 7 is scored against the budget screens
+ *    1-6 left, not against a fresh persona. This is why depletion had to stop
+ *    saturating first: with the old clamp, every screen after the third saw an
+ *    identical capacity vector.
+ * 3. DEMAND IS WEIGHTED BY THE CHANCE OF EVER GETTING THERE. A cost on screen
+ *    twelve that 4% of sessions reach is not a cost of the same size as one on
+ *    screen one.
+ *
+ * The hazard is the same Hill function the aggregate uses, applied per screen
+ * against the capacity remaining at that point -- so ABANDONMENT_HILL_EXPONENT
+ * is load-bearing here too and remains uncalibrated.
+ */
+export function computeSequentialScrollCTC(persona, screenDemands, options) {
+    const screens = [];
+    let carried;
+    let survive = 1;
+    const patience = traitValue(persona.traits, 'patience');
+    const resilience = traitValue(persona.traits, 'resilience');
+    const tolerance = Math.max(0.05, (patience * 0.7 + resilience * 0.3) * 1.5);
+    for (let i = 0; i < screenDemands.length; i++) {
+        const r = computeSequentialCTC(persona, screenDemands[i], { ...options, carriedCapacity: carried });
+        carried = r.remainingCapacity;
+        // Hazard for THIS screen, from this screen's own unmet demand. Surplus
+        // relief applies as it does in the aggregate.
+        const screenCost = Math.max(0, r.deficitCost - r.surplusCost * 0.3);
+        const stopHazard = screenCost <= 0 ? 0 : Math.min(1, Math.pow(screenCost, ABANDONMENT_HILL_EXPONENT) /
+            (Math.pow(screenCost, ABANDONMENT_HILL_EXPONENT) + Math.pow(tolerance, ABANDONMENT_HILL_EXPONENT)));
+        const reachProbability = survive;
+        survive = survive * (1 - stopHazard);
+        screens.push({
+            screen: i + 1,
+            layers: r.layers,
+            screenCTC: Math.round(r.totalCTC * 1000) / 1000,
+            stopHazard: Math.round(stopHazard * 1000) / 1000,
+            cumulativeAbandonment: Math.round((1 - survive) * 1000) / 1000,
+            reachProbability: Math.round(reachProbability * 1000) / 1000,
+            bottleneckLayer: r.bottleneckLayer,
+            remainingCapacity: r.remainingCapacity,
+        });
+    }
+    // Where the most sessions end. Mass lost on a screen is reach x hazard, so a
+    // brutal screen nobody reaches does not win.
+    let dropOff = null;
+    for (const s of screens) {
+        const lost = s.reachProbability * s.stopHazard;
+        if (!dropOff || lost > dropOff.share) {
+            dropOff = { screen: s.screen, layer: s.bottleneckLayer, share: Math.round(lost * 1000) / 1000 };
+        }
+    }
+    if (dropOff && dropOff.share <= 0)
+        dropOff = null;
+    return {
+        screens,
+        totalAbandonment: Math.round((1 - survive) * 1000) / 1000,
+        // Sum of reach probabilities: the expected count of screens actually seen.
+        expectedDepthScreens: Math.round(screens.reduce((a, s) => a + s.reachProbability, 0) * 100) / 100,
+        dropOff,
+        reachWeightedCTC: Math.round(screens.reduce((a, s) => a + s.reachProbability * s.screenCTC, 0) * 1000) / 1000,
+    };
+}
 //# sourceMappingURL=cognitive-transport-chain.js.map