cbrowser 20.2.2 → 21.0.0

package/dist/visual/dro-bound.d.ts

@@ -0,0 +1,220 @@
+/**
+ * A Wasserstein distributionally robust bound on the cognitive transport cost.
+ *
+ * What it answers. A population of users is a distribution P over capacity
+ * vectors x in [0, 1]^30 (one coordinate per DEMAND_DIMENSION, read exactly as
+ * the chain reads a persona: capacityVector()). The true population is not
+ * known; assume only that it lies within Wasserstein-1 distance epsilon of P,
+ * with the ground metric |x - y|_1. Then for every such population Q
+ *
+ *     E_Q[rawCTC] <= E_P[rawCTC] + epsilon * L
+ *
+ * where L is a Lipschitz constant of rawCTC(x) in the L1 metric on x
+ * (Kantorovich-Rubinstein duality: W1 is the supremum of E_Q f - E_P f over
+ * 1-Lipschitz f). The bound is also capped at rawMax, the largest raw cost the
+ * derivation allows on this page.
+ *
+ * Why rawCTC. totalCTC is a percentile of rawCTC against real pages
+ * (cognitive-transport-chain.ts, ctc-reference.ts), so the chain's own
+ * behaviour is in rawCTC and the percentile is a fixed monotone map on top.
+ * Through 21.0 totalCTC was a logistic of rawCTC and this bound carried the
+ * logistic's slope as a factor; that factor is gone with the logistic.
+ *
+ * The percentile, too. The interpolated percentile curve is piecewise linear,
+ * so it is Lipschitz with constant s = its largest slope over [0, rawMax] (the
+ * only raw costs this page can produce). totalCTC(x) = F(rawCTC(x)) is then
+ * Lipschitz with L * s, and the same duality gives
+ *
+ *     E_Q[totalCTC] <= E_P[totalCTC] + epsilon * L * s,  capped at 1.
+ *
+ * Sound, and loose: s is the steepest segment of a curve through thousands of
+ * samples, so two close samples make it large. percentileLipschitzBound reports
+ * s beside the product so the looseness is visible rather than inferred.
+ *
+ * What it does NOT answer. This is a property of the MODEL: how far the
+ * model's own output can move when the population moves. It says nothing about
+ * whether the model predicts people. The chain's constants are hand-set
+ * hypotheses (see provenance/chain.ts) and CTC has not been tested against
+ * human data; a bound around such a function is not evidence about users and
+ * must never be reported as such.
+ *
+ * epsilon has no default. No data fixes how far a real population sits from a
+ * persona roster, so the radius is the caller's assumption and must be named
+ * by the caller.
+ *
+ * How L is derived (sound, not sampled). For each input coordinate s the code
+ * below bounds sup |d rawCTC / d x_s| by walking the chain's own structure:
+ *
+ *  - layer k's cost is c_k * sum_t w_t (d_t - cap_t)^2, with c_k the content
+ *    gate (a function of demand alone, except in readingAttention, see below);
+ *    |d cost / d cap_t| <= c_k * 2 * max(w_def * d_t, w_sur(t) * (1 - d_t)),
+ *    because a deficit gap is at most d_t and a surplus gap at most 1 - d_t;
+ *  - except for an exposure-priced trait (EXPOSURE_DIMENSIONS, asymmetric
+ *    mode), whose term is w_sur * cap_t * d_t: |d cost / d cap_t| = c_k *
+ *    w_sur * d_t, and the term is at most w_sur * d_t (capacities are <= 1);
+ *  - the layers' trait sets are disjoint, so a coordinate reaches a later
+ *    layer only through the indirect drawdown cap *= 1 - min(m, rho*sigma*L_j)
+ *    of every gated earlier layer, whose derivative in L_j is at most
+ *    rho*sigma (capacities are <= 1); the drawdown of a layer's own traits
+ *    is never read again on the same page;
+ *  - readingTendency enters through demand: it scales sustainedAttention
+ *    demand by atSkim + x * range, which moves both the gap and the content
+ *    gate of readingAttention, the last layer (so its depletion gate cannot
+ *    feed back into anything on the page);
+ *  - interaction terms w_p * L_a * L_b are bounded by the product rule with
+ *    each layer's maximum attainable cost.
+ *
+ * Every piece of the chain is continuous in x (the deficit/surplus switch
+ * meets at gap 0, min/max clamps are continuous, and the only x-dependent gate
+ * sits after the last layer), so a bound on the partial derivatives where they
+ * exist is a Lipschitz constant. Each partial is bounded separately and the
+ * L1 constant is their maximum, which is the dual norm of L1.
+ *
+ * Schwartz value modulation of demand is not supported here (it would add
+ * further demand-dependence on options); no shipped caller passes it.
+ *
+ * Preconditions. The steps above hold only for a chain of a certain shape, and
+ * the chain's layout and constants are edited independently of this file. So
+ * every call checks them against the live chain and throws, naming the broken
+ * assumption, rather than return a constant the derivation does not cover
+ * (droPreconditionViolations):
+ *
+ *  - layer names are unique (interaction terms look layers up by name);
+ *  - every layer lists at least one trait, and no trait is listed twice,
+ *    within a layer or across layers (disjoint trait sets: a later layer would
+ *    otherwise read capacity drawn at the full depletion rate);
+ *  - the layer listing sustainedAttention, whose demand moves with
+ *    readingTendency, is the last layer (its depletion gate switches with
+ *    readingTendency, so a later layer would make CTC discontinuous in x) and
+ *    lists no other trait (its content-gate term counts that gap alone);
+ *  - interaction weights are finite and >= 0, when interactions are on;
+ *  - every demand is a finite number >= 0 (the gap bounds);
+ *  - no option beyond asymmetric and interactions (Schwartz values and a
+ *    carried capacity change the demand and the starting capacity);
+ *  - the chain constants are finite, with deficit and surplus weights, the
+ *    content-scale gain, depletion rate, indirect share, drawdown cap and
+ *    engagement range >= 0, and the capacity floor in [0, 1].
+ *
+ * @copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com https://cbrowser.ai
+ * @license MIT
+ */
+import { type DemandDistribution } from "./cognitive-transport-chain.js";
+import { type MetricScope } from "./cognitive-transport.js";
+export interface DroOptions {
+    /** Same meaning as computeSequentialCTC's options. Default true. */
+    asymmetric?: boolean;
+    /** Same meaning as computeSequentialCTC's options. Default true. */
+    interactions?: boolean;
+}
+export interface LipschitzBound {
+    /** Lipschitz constant of rawCTC(x) in the L1 metric on capacity vectors. */
+    lipschitz: number;
+    /** The coordinate whose partial derivative bound attains it. */
+    worstDimension: string;
+    /** Per-coordinate bounds on |d rawCTC / d x_s|. */
+    perDimension: Record<string, number>;
+    /** Upper bound on rawCTC over the whole capacity cube for this demand. */
+    rawMax: number;
+}
+export interface PercentileLipschitzBound {
+    /** Lipschitz constant of totalCTC(x), the percentile, in the L1 metric: raw.lipschitz * curveSlope. */
+    lipschitz: number;
+    /** The bound on rawCTC it is built on. */
+    raw: LipschitzBound;
+    /** Largest slope of the percentile curve over [0, raw.rawMax]: the curve's Lipschitz constant on every raw cost this page can produce. */
+    curveSlope: number;
+    /** The reference the percentile is read against (the demand's scope, viewport when it has none). */
+    referenceScope: MetricScope;
+}
+export interface PopulationMember {
+    /** Persona traits; read through capacityVector exactly as the chain reads them. */
+    traits: Record<string, number | string>;
+    /** Non-negative weight. Weights are normalised; default 1. */
+    weight?: number;
+}
+export interface WorstCaseBound {
+    /** Which output the bound is on. */
+    quantity: "rawCTC" | "totalCTC";
+    /** E_P of the quantity over the given population. */
+    nominal: number;
+    /** epsilon as passed. */
+    epsilon: number;
+    lipschitz: number;
+    /** The largest value the quantity can take here: rawMax for rawCTC, 1 for the percentile. `upper` is capped at it. */
+    ceiling: number;
+    /** min(ceiling, nominal + epsilon * lipschitz): no population within W1 epsilon can have a higher mean. */
+    upper: number;
+    /** max(0, nominal - epsilon * lipschitz). */
+    lower: number;
+    metric: "W1 over capacity vectors in [0,1]^30 with ground metric |x - y|_1";
+    note: string;
+}
+declare function readChainParams(): {
+    weightDeficit: number;
+    weightSurplus: number;
+    contentScaleGain: number;
+    depletionGate: number;
+    depletionRate: number;
+    indirectShare: number;
+    maxDrawdown: number;
+    capacityEpsilon: number;
+    atSkim: number;
+    range: number;
+};
+/** The chain constants the derivation reads. */
+export type DroChainParams = ReturnType<typeof readChainParams>;
+/** The chain's structure as the derivation reads it: layers in order, and the interaction pairs with their weights. */
+export interface ChainLayout {
+    layers: ReadonlyArray<{
+        name: string;
+        traits: readonly string[];
+    }>;
+    pairs: ReadonlyArray<{
+        a: string;
+        b: string;
+        weight: number;
+    }>;
+}
+/**
+ * Every precondition of the derivation (module comment) that does not hold,
+ * as one sentence each; empty when the derivation covers the input. `chain`
+ * replaces the live layout or some of the live constants; that is for tests
+ * showing each check fires. The bound itself is only computed for the chain.
+ */
+export declare function droPreconditionViolations(demand: DemandDistribution, options?: DroOptions, chain?: {
+    layout?: ChainLayout;
+    params?: Partial<DroChainParams>;
+}): string[];
+/**
+ * A sound Lipschitz constant of rawCTC in the capacity vector, for one demand
+ * distribution. See the module comment for the derivation. Throws when one of
+ * its preconditions does not hold for the live chain or this input.
+ */
+export declare function ctcLipschitzBound(demand: DemandDistribution, options?: DroOptions): LipschitzBound;
+/**
+ * A sound Lipschitz constant of totalCTC, the percentile, in the capacity
+ * vector: the rawCTC constant times the largest slope of the percentile curve
+ * over [0, rawMax]. Sound because rawCTC never leaves [0, rawMax] on this page
+ * and the curve is piecewise linear with that slope as its constant there.
+ * Same preconditions as ctcLipschitzBound.
+ */
+export declare function percentileLipschitzBound(demand: DemandDistribution, options?: DroOptions): PercentileLipschitzBound;
+/** rawCTC of one capacity vector (numbers over DEMAND_DIMENSIONS): the quantity ctcLipschitzBound bounds. */
+export declare function rawCTCOfCapacity(x: Record<string, number>, demand: DemandDistribution, options?: DroOptions): number;
+/** totalCTC (the percentile) of one capacity vector: the quantity percentileLipschitzBound bounds. */
+export declare function ctcOfCapacity(x: Record<string, number>, demand: DemandDistribution, options?: DroOptions): number;
+/**
+ * Worst-case mean rawCTC over every population within W1 distance `epsilon` of
+ * the given one. `epsilon` is required: it is the caller's assumption about
+ * how far real users can sit from the personas, in mean L1 change of the
+ * capacity vector.
+ */
+export declare function worstCaseCTCBound(population: PopulationMember[], demand: DemandDistribution, epsilon: number, options?: DroOptions): WorstCaseBound;
+/**
+ * Worst-case mean totalCTC (the percentile) over every population within W1
+ * distance `epsilon` of the given one. Sound and loose: see
+ * percentileLipschitzBound and the module comment.
+ */
+export declare function worstCasePercentileBound(population: PopulationMember[], demand: DemandDistribution, epsilon: number, options?: DroOptions): WorstCaseBound;
+export {};
+//# sourceMappingURL=dro-bound.d.ts.map

package/dist/visual/dro-bound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dro-bound.d.ts","sourceRoot":"","sources":["../../src/visual/dro-bound.ts"],"names":[],"mappings":"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"}

package/dist/visual/dro-bound.js

@@ -0,0 +1,341 @@
+/**
+ * A Wasserstein distributionally robust bound on the cognitive transport cost.
+ *
+ * What it answers. A population of users is a distribution P over capacity
+ * vectors x in [0, 1]^30 (one coordinate per DEMAND_DIMENSION, read exactly as
+ * the chain reads a persona: capacityVector()). The true population is not
+ * known; assume only that it lies within Wasserstein-1 distance epsilon of P,
+ * with the ground metric |x - y|_1. Then for every such population Q
+ *
+ *     E_Q[rawCTC] <= E_P[rawCTC] + epsilon * L
+ *
+ * where L is a Lipschitz constant of rawCTC(x) in the L1 metric on x
+ * (Kantorovich-Rubinstein duality: W1 is the supremum of E_Q f - E_P f over
+ * 1-Lipschitz f). The bound is also capped at rawMax, the largest raw cost the
+ * derivation allows on this page.
+ *
+ * Why rawCTC. totalCTC is a percentile of rawCTC against real pages
+ * (cognitive-transport-chain.ts, ctc-reference.ts), so the chain's own
+ * behaviour is in rawCTC and the percentile is a fixed monotone map on top.
+ * Through 21.0 totalCTC was a logistic of rawCTC and this bound carried the
+ * logistic's slope as a factor; that factor is gone with the logistic.
+ *
+ * The percentile, too. The interpolated percentile curve is piecewise linear,
+ * so it is Lipschitz with constant s = its largest slope over [0, rawMax] (the
+ * only raw costs this page can produce). totalCTC(x) = F(rawCTC(x)) is then
+ * Lipschitz with L * s, and the same duality gives
+ *
+ *     E_Q[totalCTC] <= E_P[totalCTC] + epsilon * L * s,  capped at 1.
+ *
+ * Sound, and loose: s is the steepest segment of a curve through thousands of
+ * samples, so two close samples make it large. percentileLipschitzBound reports
+ * s beside the product so the looseness is visible rather than inferred.
+ *
+ * What it does NOT answer. This is a property of the MODEL: how far the
+ * model's own output can move when the population moves. It says nothing about
+ * whether the model predicts people. The chain's constants are hand-set
+ * hypotheses (see provenance/chain.ts) and CTC has not been tested against
+ * human data; a bound around such a function is not evidence about users and
+ * must never be reported as such.
+ *
+ * epsilon has no default. No data fixes how far a real population sits from a
+ * persona roster, so the radius is the caller's assumption and must be named
+ * by the caller.
+ *
+ * How L is derived (sound, not sampled). For each input coordinate s the code
+ * below bounds sup |d rawCTC / d x_s| by walking the chain's own structure:
+ *
+ *  - layer k's cost is c_k * sum_t w_t (d_t - cap_t)^2, with c_k the content
+ *    gate (a function of demand alone, except in readingAttention, see below);
+ *    |d cost / d cap_t| <= c_k * 2 * max(w_def * d_t, w_sur(t) * (1 - d_t)),
+ *    because a deficit gap is at most d_t and a surplus gap at most 1 - d_t;
+ *  - except for an exposure-priced trait (EXPOSURE_DIMENSIONS, asymmetric
+ *    mode), whose term is w_sur * cap_t * d_t: |d cost / d cap_t| = c_k *
+ *    w_sur * d_t, and the term is at most w_sur * d_t (capacities are <= 1);
+ *  - the layers' trait sets are disjoint, so a coordinate reaches a later
+ *    layer only through the indirect drawdown cap *= 1 - min(m, rho*sigma*L_j)
+ *    of every gated earlier layer, whose derivative in L_j is at most
+ *    rho*sigma (capacities are <= 1); the drawdown of a layer's own traits
+ *    is never read again on the same page;
+ *  - readingTendency enters through demand: it scales sustainedAttention
+ *    demand by atSkim + x * range, which moves both the gap and the content
+ *    gate of readingAttention, the last layer (so its depletion gate cannot
+ *    feed back into anything on the page);
+ *  - interaction terms w_p * L_a * L_b are bounded by the product rule with
+ *    each layer's maximum attainable cost.
+ *
+ * Every piece of the chain is continuous in x (the deficit/surplus switch
+ * meets at gap 0, min/max clamps are continuous, and the only x-dependent gate
+ * sits after the last layer), so a bound on the partial derivatives where they
+ * exist is a Lipschitz constant. Each partial is bounded separately and the
+ * L1 constant is their maximum, which is the dual norm of L1.
+ *
+ * Schwartz value modulation of demand is not supported here (it would add
+ * further demand-dependence on options); no shipped caller passes it.
+ *
+ * Preconditions. The steps above hold only for a chain of a certain shape, and
+ * the chain's layout and constants are edited independently of this file. So
+ * every call checks them against the live chain and throws, naming the broken
+ * assumption, rather than return a constant the derivation does not cover
+ * (droPreconditionViolations):
+ *
+ *  - layer names are unique (interaction terms look layers up by name);
+ *  - every layer lists at least one trait, and no trait is listed twice,
+ *    within a layer or across layers (disjoint trait sets: a later layer would
+ *    otherwise read capacity drawn at the full depletion rate);
+ *  - the layer listing sustainedAttention, whose demand moves with
+ *    readingTendency, is the last layer (its depletion gate switches with
+ *    readingTendency, so a later layer would make CTC discontinuous in x) and
+ *    lists no other trait (its content-gate term counts that gap alone);
+ *  - interaction weights are finite and >= 0, when interactions are on;
+ *  - every demand is a finite number >= 0 (the gap bounds);
+ *  - no option beyond asymmetric and interactions (Schwartz values and a
+ *    carried capacity change the demand and the starting capacity);
+ *  - the chain constants are finite, with deficit and surplus weights, the
+ *    content-scale gain, depletion rate, indirect share, drawdown cap and
+ *    engagement range >= 0, and the capacity floor in [0, 1].
+ *
+ * @copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com https://cbrowser.ai
+ * @license MIT
+ */
+import { computeSequentialCTC, ctcReferenceCurve, capacityVector, DEMAND_DIMENSIONS, LAYER_DEFINITIONS, INTERACTION_PAIRS, SURPLUS_FREE_DIMENSIONS, EXPOSURE_DIMENSIONS, } from "./cognitive-transport-chain.js";
+import { buildOTCognitiveProfile } from "./cognitive-transport.js";
+import { curveSlope } from "./ctc-reference.js";
+import { param } from "./model-provenance.js";
+function readChainParams() {
+    return {
+        weightDeficit: param("chain.weightDeficit"),
+        weightSurplus: param("chain.weightSurplus"),
+        contentScaleGain: param("chain.contentScaleGain"),
+        depletionGate: param("chain.depletionGate"),
+        depletionRate: param("chain.depletionRate"),
+        indirectShare: param("chain.indirectDepletionShare"),
+        maxDrawdown: param("chain.maxDrawdownFraction"),
+        capacityEpsilon: param("chain.capacityEpsilon"),
+        atSkim: param("chain.engagement.atSkim"),
+        range: param("chain.engagement.range"),
+    };
+}
+function chainLayout() {
+    return { layers: LAYER_DEFINITIONS, pairs: INTERACTION_PAIRS.map((p) => ({ a: p.a, b: p.b, weight: param(p.weight) })) };
+}
+const SA = "sustainedAttention";
+const RT = "readingTendency";
+/**
+ * Every precondition of the derivation (module comment) that does not hold,
+ * as one sentence each; empty when the derivation covers the input. `chain`
+ * replaces the live layout or some of the live constants; that is for tests
+ * showing each check fires. The bound itself is only computed for the chain.
+ */
+export function droPreconditionViolations(demand, options = {}, chain = {}) {
+    const layout = chain.layout ?? chainLayout();
+    const params = { ...readChainParams(), ...chain.params };
+    const broken = [];
+    for (const [k, v] of Object.entries(options ?? {}))
+        if (k !== "asymmetric" && k !== "interactions" && v !== undefined)
+            broken.push(`option "${k}" is not modelled: the derivation holds demand and the starting capacity fixed, and Schwartz values or a carried capacity change them`);
+    for (const [t, v] of Object.entries(demand?.demands ?? {}))
+        if (typeof v !== "number" || !Number.isFinite(v) || v < 0)
+            broken.push(`demand ${t} = ${String(v)} is not a finite number >= 0: the deficit and surplus gap bounds assume it is`);
+    const names = new Set();
+    const owner = new Map();
+    for (const l of layout.layers) {
+        if (names.has(l.name))
+            broken.push(`layer name "${l.name}" repeats: interaction terms look layers up by name`);
+        names.add(l.name);
+        if (l.traits.length === 0)
+            broken.push(`layer "${l.name}" lists no trait: its content gate is a mean over its traits`);
+        for (const t of l.traits) {
+            const prev = owner.get(t);
+            if (prev === undefined)
+                owner.set(t, l.name);
+            else
+                broken.push(`trait "${t}" is listed in ${prev === l.name ? `layer "${l.name}" twice` : `layers "${prev}" and "${l.name}"`}: layer trait sets must be disjoint, or a later layer reads capacity drawn at the full depletion rate rather than the indirect share`);
+        }
+    }
+    const iSA = layout.layers.findIndex((l) => l.traits.includes(SA));
+    if (iSA >= 0) {
+        const l = layout.layers[iSA];
+        if (iSA !== layout.layers.length - 1)
+            broken.push(`layer "${l.name}" (${SA}, whose demand moves with ${RT}) is not the last layer: its depletion gate switches with ${RT}, so a layer after it would make CTC discontinuous`);
+        if (l.traits.some((t) => t !== SA))
+            broken.push(`layer "${l.name}" lists traits besides ${SA}: the ${RT} term bounds its content-gate derivative by the ${SA} gap alone`);
+    }
+    if (options?.interactions !== false)
+        for (const p of layout.pairs)
+            if (!(Number.isFinite(p.weight) && p.weight >= 0))
+                broken.push(`interaction weight ${p.a}x${p.b} = ${p.weight} is not finite and >= 0: the product-rule bound adds each term with its sign`);
+    const nonNegative = ["weightDeficit", "weightSurplus", "contentScaleGain", "depletionRate", "indirectShare", "maxDrawdown", "range"];
+    for (const k of nonNegative)
+        if (!(Number.isFinite(params[k]) && params[k] >= 0))
+            broken.push(`chain constant ${k} = ${params[k]} is not finite and >= 0`);
+    for (const k of ["depletionGate", "atSkim"])
+        if (!Number.isFinite(params[k]))
+            broken.push(`chain constant ${k} = ${params[k]} is not finite`);
+    if (!(params.capacityEpsilon >= 0 && params.capacityEpsilon <= 1))
+        broken.push(`chain constant capacityEpsilon = ${params.capacityEpsilon} is not in [0, 1]: the depletion bound assumes capacities stay <= 1`);
+    return broken;
+}
+const clamp01 = (v) => Math.max(0, Math.min(1, v));
+/**
+ * A sound Lipschitz constant of rawCTC in the capacity vector, for one demand
+ * distribution. See the module comment for the derivation. Throws when one of
+ * its preconditions does not hold for the live chain or this input.
+ */
+export function ctcLipschitzBound(demand, options = {}) {
+    const P = readChainParams();
+    const layout = chainLayout();
+    const broken = droPreconditionViolations(demand, options, { layout, params: P });
+    if (broken.length)
+        throw new Error(`ctcLipschitzBound: the derivation does not cover this input: ${broken.join("; ")}`);
+    const asym = options.asymmetric !== false;
+    const useInter = options.interactions !== false;
+    const d0 = (t) => demand.demands[t] ?? 0;
+    const wDef = asym ? P.weightDeficit : 1;
+    const wSur = (t) => (asym ? (SURPLUS_FREE_DIMENSIONS.has(t) ? 0 : P.weightSurplus) : 1);
+    // sustainedAttention demand ranges with readingTendency in [0, 1].
+    const saLo = clamp01(d0(SA) * P.atSkim);
+    const saHi = clamp01(d0(SA) * (P.atSkim + P.range));
+    const saSlope = d0(SA) * P.range; // |d demand_sa / d x_rt| where unclamped
+    const layers = layout.layers.map((def) => {
+        const dep = def.traits.includes(SA);
+        const dHi = (t) => (t === SA ? saHi : Math.max(0, d0(t)));
+        const dLo = (t) => (t === SA ? saLo : Math.max(0, d0(t)));
+        const mean = def.traits.reduce((s, t) => s + dHi(t), 0) / def.traits.length;
+        const gate = Math.min(1, mean * P.contentScaleGain);
+        // Depletion gating depends on demand only, except in a layer whose demand
+        // moves with x; treat such a layer as gated (an upper bound on coupling).
+        const meanLo = def.traits.reduce((s, t) => s + dLo(t), 0) / def.traits.length;
+        const gated = dep ? true : Math.min(1, meanLo * P.contentScaleGain) > P.depletionGate;
+        const g = {};
+        let A = 0, maxCost = 0;
+        for (const t of def.traits) {
+            const defGap = dHi(t);
+            const surGap = Math.max(0, 1 - dLo(t));
+            if (asym && EXPOSURE_DIMENSIONS.has(t)) {
+                // Exposure, w_sur * cap * d: linear in cap, slope w_sur * d, at most w_sur * d.
+                g[t] = gate * P.weightSurplus * defGap;
+                A += g[t];
+                maxCost += P.weightSurplus * defGap;
+                continue;
+            }
+            g[t] = gate * 2 * Math.max(wDef * defGap, wSur(t) * surGap);
+            A += g[t];
+            maxCost += Math.max(wDef * defGap * defGap, wSur(t) * surGap * surGap);
+        }
+        return { name: def.name, traits: def.traits, gate, gated, g, A, maxCost: gate * maxCost };
+    });
+    const rhoSigma = P.depletionRate * P.indirectShare;
+    const pairs = useInter ? layout.pairs.map((p) => ({ a: p.a, b: p.b, w: p.weight })) : [];
+    const maxCostOf = (name) => layers.find((l) => l.name === name)?.maxCost ?? 0;
+    let rawMax = layers.reduce((s, l) => s + l.maxCost, 0);
+    for (const p of pairs)
+        rawMax += p.w * maxCostOf(p.a) * maxCostOf(p.b);
+    const perDimension = {};
+    let lipschitz = 0, worstDimension = DEMAND_DIMENSIONS[0];
+    for (const s of DEMAND_DIMENSIONS) {
+        const D = {};
+        let earlier = 0; // sum over earlier gated layers of D_j(s)
+        let rawPartial = 0;
+        for (const l of layers) {
+            let dk = (l.g[s] ?? 0) + l.A * rhoSigma * earlier;
+            if (s === RT && l.traits.includes(SA)) {
+                // readingTendency moves this layer's demand: gap and content gate.
+                const wMax = Math.max(wDef, wSur(SA));
+                const gapMax = Math.max(saHi, 1 - saLo);
+                dk += saSlope * (P.contentScaleGain * wMax * gapMax * gapMax + 2 * l.gate * wMax * gapMax);
+            }
+            D[l.name] = dk;
+            rawPartial += dk;
+            if (l.gated)
+                earlier += dk;
+        }
+        for (const p of pairs)
+            rawPartial += p.w * ((D[p.a] ?? 0) * maxCostOf(p.b) + maxCostOf(p.a) * (D[p.b] ?? 0));
+        const bound = rawPartial;
+        perDimension[s] = bound;
+        if (bound > lipschitz) {
+            lipschitz = bound;
+            worstDimension = s;
+        }
+    }
+    return { lipschitz, worstDimension, perDimension, rawMax };
+}
+/**
+ * A sound Lipschitz constant of totalCTC, the percentile, in the capacity
+ * vector: the rawCTC constant times the largest slope of the percentile curve
+ * over [0, rawMax]. Sound because rawCTC never leaves [0, rawMax] on this page
+ * and the curve is piecewise linear with that slope as its constant there.
+ * Same preconditions as ctcLipschitzBound.
+ */
+export function percentileLipschitzBound(demand, options = {}) {
+    const raw = ctcLipschitzBound(demand, options);
+    const referenceScope = demand.scope ?? "viewport";
+    const slope = curveSlope(ctcReferenceCurve(referenceScope, options).curve, 0, raw.rawMax);
+    return { lipschitz: raw.lipschitz * slope, raw, curveSlope: slope, referenceScope };
+}
+function chainOptions(options) {
+    return { asymmetric: options.asymmetric !== false, interactions: options.interactions !== false };
+}
+/** rawCTC of one capacity vector (numbers over DEMAND_DIMENSIONS): the quantity ctcLipschitzBound bounds. */
+export function rawCTCOfCapacity(x, demand, options = {}) {
+    return computeSequentialCTC(buildOTCognitiveProfile("dro", x), demand, chainOptions(options)).rawCTC;
+}
+/** totalCTC (the percentile) of one capacity vector: the quantity percentileLipschitzBound bounds. */
+export function ctcOfCapacity(x, demand, options = {}) {
+    return computeSequentialCTC(buildOTCognitiveProfile("dro", x), demand, chainOptions(options)).totalCTC;
+}
+/** E_P[f] with the weights normalised, after checking epsilon and the weights. */
+function populationMean(who, population, epsilon, f) {
+    if (typeof epsilon !== "number" || !Number.isFinite(epsilon) || epsilon < 0)
+        throw new Error(`${who}: epsilon must be a finite number >= 0 (no default; it is the caller's assumption)`);
+    if (!population.length)
+        throw new Error(`${who}: population is empty`);
+    let total = 0, mean = 0;
+    for (const m of population) {
+        const w = m.weight ?? 1;
+        if (!(w >= 0) || !Number.isFinite(w))
+            throw new Error(`${who}: weights must be finite and >= 0`);
+        total += w;
+    }
+    if (!(total > 0))
+        throw new Error(`${who}: weights sum to 0`);
+    for (const m of population)
+        mean += ((m.weight ?? 1) / total) * f(capacityVector(m.traits));
+    return mean;
+}
+function worstCase(quantity, nominal, epsilon, lipschitz, ceiling) {
+    return {
+        quantity,
+        nominal,
+        epsilon,
+        lipschitz,
+        ceiling,
+        upper: Math.min(ceiling, nominal + epsilon * lipschitz),
+        lower: Math.max(0, nominal - epsilon * lipschitz),
+        metric: "W1 over capacity vectors in [0,1]^30 with ground metric |x - y|_1",
+        note: `A property of the model, not of people: how far the model's mean ${quantity} can move when the population moves by epsilon. The chain's constants are hand-set hypotheses.`,
+    };
+}
+/**
+ * Worst-case mean rawCTC over every population within W1 distance `epsilon` of
+ * the given one. `epsilon` is required: it is the caller's assumption about
+ * how far real users can sit from the personas, in mean L1 change of the
+ * capacity vector.
+ */
+export function worstCaseCTCBound(population, demand, epsilon, options = {}) {
+    const mean = populationMean("worstCaseCTCBound", population, epsilon, (x) => rawCTCOfCapacity(x, demand, options));
+    const { lipschitz, rawMax } = ctcLipschitzBound(demand, options);
+    return worstCase("rawCTC", mean, epsilon, lipschitz, rawMax);
+}
+/**
+ * Worst-case mean totalCTC (the percentile) over every population within W1
+ * distance `epsilon` of the given one. Sound and loose: see
+ * percentileLipschitzBound and the module comment.
+ */
+export function worstCasePercentileBound(population, demand, epsilon, options = {}) {
+    const mean = populationMean("worstCasePercentileBound", population, epsilon, (x) => ctcOfCapacity(x, demand, options));
+    const { lipschitz } = percentileLipschitzBound(demand, options);
+    return worstCase("totalCTC", mean, epsilon, lipschitz, 1);
+}
+//# sourceMappingURL=dro-bound.js.map

package/dist/visual/dro-bound.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dro-bound.js","sourceRoot":"","sources":["../../src/visual/dro-bound.ts"],"names":[],"mappings":"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"}

package/dist/visual/exact-w1.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Exact Wasserstein-1 (earth mover's) distance between two discrete
+ * distributions over the same n points, under an arbitrary non-negative cost
+ * matrix.
+ *
+ * Solves the transportation problem
+ *
+ *     min  sum_ij C[i][j] * P[i][j]
+ *     s.t. sum_j P[i][j] = a[i],  sum_i P[i][j] = b[j],  P >= 0
+ *
+ * as a min-cost flow on the bipartite graph source -> i -> j -> sink with
+ * successive shortest paths (Dijkstra with Johnson potentials, so reverse edges
+ * with negative reduced cost never break the search). Every augmentation ships
+ * the bottleneck mass along a shortest source-to-sink path in the residual
+ * graph; the plan it leaves behind is optimal by the standard SSP argument
+ * (each augmentation is along a shortest path, so no negative cycle is ever
+ * created in the residual graph).
+ *
+ * Complexity: one Dijkstra is O(V^2) on this dense graph, V = 2n + 2. The number
+ * of augmentations K is bounded by the number of edges whose residual capacity
+ * can be exhausted (each augmentation saturates a supply edge, a demand edge or
+ * cancels a reverse edge), so the total is O(K * n^2) with K = O(n^2) in the
+ * worst case. cognitiveDistance now calls it on 30 points (29 traits plus the
+ * slack bin of the generalized distance). Measured across all 300 roster pairs
+ * in the canonical order cognitiveDistance uses (2026-10-21, after the end-node
+ * fix below): K = 41 min, 51 median, 57 max on the 30-point problem (the
+ * 29-point simplex problem it replaced: 48 / 57 / 57; 54 / 72 / 161 with the
+ * old end-node rule), i.e. roughly 1.5n to 2n, and a 25 x 25 distance matrix
+ * takes ~62 ms median (research/latency/bench-ctc.ts; ~73 ms before).
+ * Mass is floating point, so "saturated" means residual <= EPS and the loop
+ * stops once every supply point or every demand point is at or below EPS.
+ *
+ * `cognitiveDistance` used to call its result "W1" while computing a weighted
+ * L1 sum (|a_i - b_i| times the mean ground distance of trait i), which is not
+ * optimal transport and does not respect the ground metric. This module is the
+ * exact replacement. Its oracle test (tests/cognitive-distance-w1.test.ts)
+ * checks it against an independent dense two-phase simplex on the same LP, and,
+ * with a slack bin, against the Piccoli-Rossi unbalanced LP it stands in for.
+ *
+ * @copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com https://cbrowser.ai
+ * @license MIT
+ */
+export interface TransportResult {
+    /** Optimal transport cost, i.e. the exact W1 distance. */
+    cost: number;
+    /** Optimal plan: plan[i][j] = mass moved from point i to point j (diagonal included). */
+    plan: number[][];
+    /** Number of augmenting paths the solver used (diagnostic, for the complexity claim). */
+    augmentations: number;
+}
+/**
+ * Exact W1 between distributions `a` and `b` (same length n, both summing to
+ * the same total up to EPS) under cost matrix `cost` (n x n, non-negative).
+ *
+ * Throws if the shapes disagree or the masses differ by more than 1e-9: unequal
+ * mass is an unbalanced problem and W1 is undefined for it. (cognitiveDistance
+ * balances its measures first with a slack bin; see traitsToLevelMeasure.)
+ */
+export declare function exactW1(a: ArrayLike<number>, b: ArrayLike<number>, cost: ArrayLike<ArrayLike<number>>): TransportResult;
+//# sourceMappingURL=exact-w1.d.ts.map