@gradial/aci 0.1.52-rc.8 → 0.1.52

package/dist/internal/domain/edge/personalization-core.js

@@ -1,76 +1,181 @@
 // Runtime-neutral personalization selection. The backend owns this logic
-// and pushes compiled artifacts to each host (CloudFront Function, Vercel
+// and pushes compiled artifacts to each host (Lambda@Edge, Vercel
 // middleware, Cloudflare Worker). Keep this file free of platform APIs.
 //
 // This is the pure decision algorithm — no I/O, no cookies, no identity
 // minting. The caller resolves identity and claims, then calls this.
-import { variantValuesFromKey } from './record/codec.js';
-// Build-time constant. The CloudFront Functions bundle replaces this with
-// true and uses the runtime's built-in crypto module; other host bundles
-// replace it with false and retain the portable implementation.
-export function selectPersonalizationVariant(request, route, claims, experiments, identity) {
-    return resolvePersonalizationDecision(request, route, claims, experiments, identity).variant;
-}
-export function resolvePersonalizationDecision(request, route, claims, experiments, identity) {
+import { canonicalVariantKey, variantValuesFromKey } from './variant_key.js';
+import { personalizationSelection } from './personalization_index.js';
+export { preparePersonalizationRoute } from './personalization_index.js';
+export class PersonalizationResolutionError extends Error {
+    variantKey;
+    code = 'personalization.tuple_missing';
+    constructor(variantKey) {
+        super(`materialized personalization tuple ${variantKey} is absent from the route projection`);
+        this.variantKey = variantKey;
+        this.name = 'PersonalizationResolutionError';
+    }
+}
+export function resolvePersonalizationDecision(request, route, claims, experiments, identity, forcedArms) {
     if (!route)
-        return { variant: null, experiment: null };
-    let variant = selectRuleVariant(request, route, claims, experiments);
-    let experiment = null;
-    if (identity && identity.usable && route.variants && experiments) {
-        const candidates = Object.values(experiments)
-            .filter((item) => (item.kind === 'ab' || item.kind === 'abn') && item.status === 'running')
-            .filter((item) => routeHasExperiment(route, item.id))
-            .sort((left, right) => (right.priority || 0) - (left.priority || 0)
-            || String(left.id || '').localeCompare(String(right.id || '')));
-        for (let index = 0; index < candidates.length; index++) {
-            const item = candidates[index];
-            const assignment = assignExperiment(item, identity);
-            const candidate = assignment ? route.variants[assignment.variantKey] : undefined;
-            if (!candidate)
+        return { variant: null, experiments: [] };
+    const selection = personalizationSelection(route, experiments);
+    const legacyExperimentExclusions = selection.legacyExperimentExclusions;
+    const authored = selectRuleVariant(request, selection, claims);
+    const values = { ...(authored ? authored.variantValues || variantValuesFromKey(authored.variantKey) : {}) };
+    // The leg selectRuleVariant chose is the selected-mode predicate's only
+    // input (ADR 0050, edge-functions I-16): "" when no leg won — an organic
+    // visit admits no selected-mode experiment.
+    const selectedLegAudienceId = String(values.audience || '');
+    const assignments = [];
+    const rejected = [];
+    const attempted = { ...values };
+    // Experiment-arm forcing (audience-mimic design/09, edge-functions I-17):
+    // an arms-bearing mimic token runs the experiment tier with the token's
+    // assertion replacing the dice for each experiment the request selects
+    // through the ordinary gate. Selection, eligibility, and arm-rule
+    // evaluation are the ordinary path — only allocation is replaced. No
+    // identity exists under mimic, so experiments the token does not name are
+    // skipped, and unselected experiments' forces are inert.
+    const forcing = !!forcedArms && Object.keys(forcedArms).length > 0;
+    if ((identity?.usable || forcing) && experiments) {
+        // The immutable route projection is the authority for scope. Missing
+        // qualified entries are corruption, never evidence to omit an experiment.
+        for (const item of selection.experiments) {
+            const id = item.id;
+            if (!experimentEligible(item, claims, selectedLegAudienceId))
+                continue;
+            const assignment = forcing
+                ? forceExperimentArm(item, forcedArms)
+                : assignExperiment(item, identity);
+            if (!assignment)
                 continue;
-            if (assignment && !candidate.variantKey)
-                candidate.variantKey = assignment.variantKey;
-            if (!variant || betterVariant(candidate.priority || 0, candidate.variantKey, variant.priority || 0, variant.variantKey)) {
-                variant = candidate;
-                experiment = assignment;
+            attempted[`experiment.${id}`] = assignment.armId;
+            if (item.eligibilityMode !== 'selected') {
+                const candidate = selection.arms[id]?.[assignment.armId];
+                // Under forcing an absent single-factor entry is publish/mint skew,
+                // not corruption (D-12 forbids the error page on the live origin):
+                // the factor degrades to absent and the plain mimic view renders.
+                if (!candidate) {
+                    if (!forcing)
+                        throw new PersonalizationResolutionError(assignment.variantKey);
+                    continue;
+                }
+                const factorEvents = [];
+                const factorRequest = { ...request, onRuleRejected: (event) => factorEvents.push(event) };
+                if (candidate.rule && !evaluateRule(factorRequest, candidate.rule, claims, assignment.variantKey)) {
+                    if (!factorEvents.length)
+                        factorEvents.push({ variantKey: assignment.variantKey, diagnosticCode: 'expression.not_matched', diagnosticPath: 'expression', diagnosticCount: 1 });
+                    for (const event of factorEvents)
+                        rejected.push({ ...event, experimentId: id, armId: assignment.armId });
+                    continue;
+                }
+            }
+            // A selected-mode experiment carries no arm rules (experiment I-18) and
+            // its arms materialize only composed with the selected leg, so there is
+            // no single-factor arm entry to look up; the composed-tuple resolution
+            // below stays the fail-closed corruption guard.
+            assignments.push(assignment);
+            values[`experiment.${id}`] = assignment.armId;
+        }
+    }
+    const attemptedKey = canonicalVariantKey(attempted);
+    for (const event of rejected)
+        request.onRuleRejected?.({ ...event, variantKey: attemptedKey });
+    let variant = authored;
+    if (assignments.length) {
+        const key = canonicalVariantKey(values);
+        const selected = selection.tuples[key];
+        // Under forcing a forced tuple absent from the projection (publish/mint
+        // skew) degrades every forced factor to absent — the plain mimic view.
+        // The fail-closed named error applies only to non-mimic traffic (I-17).
+        if (!selected && !forcing)
+            throw new PersonalizationResolutionError(key);
+        if (selected) {
+            variant = { ...selected, variantKey: key };
+        }
+        else {
+            assignments.length = 0;
+            for (const name of Object.keys(values)) {
+                if (name.startsWith('experiment.'))
+                    delete values[name];
             }
-            break;
         }
     }
-    return { variant: variant || null, experiment };
+    return { variant, experiments: assignments, ...(legacyExperimentExclusions ? { legacyExperimentExclusions } : {}) };
 }
-function selectRuleVariant(request, route, claims, experiments) {
-    if (!route.variants)
+// forceExperimentArm resolves the token's named arm for one selected
+// experiment instead of bucketing (design/09). Null when the token does not
+// name this experiment (unforced experiments never run under mimic — no
+// identity exists) or names an arm the active projection does not carry
+// (skew degrades to the plain mimic view, never an error).
+function forceExperimentArm(experiment, forcedArms) {
+    const armId = forcedArms[experiment.id];
+    if (armId === undefined)
         return null;
-    const matches = [];
-    for (const key in route.variants) {
-        const variant = route.variants[key];
-        if (!variant.variantKey)
-            variant.variantKey = key;
-        const values = variant.variantValues || variantValuesFromKey(key);
-        const experimentID = String(values.experiment || '').trim();
-        if (experimentID && (!experiments || !experiments[experimentID]
-            || experiments[experimentID].status !== 'running'))
+    const arm = (experiment.arms || []).find((candidate) => candidate.id === armId);
+    if (!arm)
+        return null;
+    return {
+        experimentId: experiment.id,
+        armId,
+        allocationVersion: String(experiment.allocationVersion || ''),
+        variantKey: `experiment.${experiment.id}=${armId}`,
+        // The dice never rolled; -1 marks the forced origin in the decision
+        // record where a bucket would otherwise sit.
+        bucket: -1,
+        forced: true,
+    };
+}
+function selectRuleVariant(request, selection, claims) {
+    let best = null;
+    for (const candidate of selection.authored) {
+        const { variant, values, key } = candidate;
+        if (candidate.experiments.some((item) => !experimentEligible(item, claims, String(values.audience || ''))))
             continue;
         if (!requestDimensionsMatch(request, values))
             continue;
         const membershipMatch = (values.audience && claims && (claims.aud || []).includes(values.audience))
             || (values.segment && claims && (claims.seg || []).includes(values.segment));
-        const ruleMatch = variant.rule ? evaluateRule(request, variant.rule) : false;
-        if (membershipMatch || ruleMatch)
-            matches.push(variant);
+        const ruleMatch = variant.rule ? evaluateRule(request, variant.rule, claims, key) : false;
+        if (!best && (membershipMatch || ruleMatch))
+            best = { ...variant, variantKey: key, variantValues: values };
     }
-    matches.sort((left, right) => (right.priority || 0) - (left.priority || 0)
-        || String(left.variantKey || '').localeCompare(String(right.variantKey || '')));
-    return matches[0] || null;
+    return best;
 }
-function routeHasExperiment(route, experimentID) {
-    for (const key in route.variants || {}) {
-        const values = route.variants[key].variantValues || variantValuesFromKey(key);
-        if (values.experiment === experimentID)
-            return true;
-    }
-    return false;
+// The eligibility gate (audience-scoped-experiments ASE-F4/F5): an
+// experiment declaring eligibilityAudienceId is skipped entirely — before
+// bucketing or arm candidacy — unless the verified claims carry the ID.
+// Ungated experiments return true, preserving byte-identical behavior.
+//
+// ADR 0050 (edge-functions I-16): an experiment whose projection carries
+// eligibilityMode "selected" is gated by the selected-leg predicate INSTEAD
+// of the claims gate — it is a factor only when the leg the request selected
+// carries audience=<eligibilityAudienceId>. Claims are never consulted for
+// it: a rule-backed audience cannot enter claims, so the claims gate would
+// hold the experiment dormant, and the selected leg is the fact the
+// planner's sum built this route's tuples for. Out of selection there is no
+// bucket, assignment, exposure, or rule-rejection record.
+function experimentEligible(item, claims, selectedLegAudienceId) {
+    if (item.eligibilityMode === 'selected')
+        return selectedModeFactorOf(item, selectedLegAudienceId);
+    const audienceID = String(item.eligibilityAudienceId || '').trim();
+    if (!audienceID)
+        return true;
+    return !!claims && (claims.aud || []).includes(audienceID);
+}
+// selectedModeFactorOf is the decision core's spelling of the planner's
+// leg-membership predicate (ADR 0050) — one name, one rule, two runtimes:
+// experiment.SelectedModeFactorOf in Go, applied by Assign and by the
+// contentbuild planner's leg factors, candidates, and Lookup. A
+// selected-mode experiment with an unresolved eligibility audience is a
+// factor of no leg, base included. Both inputs are canonical by variant-key
+// construction (the variant-key reader and the strict document decode
+// pre-trim them), so this comparison needs no normalization — the Go twin's TrimSpace
+// is defensive only and never changes the outcome.
+function selectedModeFactorOf(item, legAudienceId) {
+    const audienceID = String(item.eligibilityAudienceId || '').trim();
+    return audienceID !== '' && audienceID === legAudienceId;
 }
 function assignExperiment(experiment, identity) {
     const version = String(experiment.allocationVersion || '').trim();
@@ -93,25 +198,20 @@ function assignExperiment(experiment, identity) {
                 experimentId: experiment.id,
                 armId: arm.id,
                 allocationVersion: version,
-                variantKey: arm.variantKey,
+                variantKey: `experiment.${experiment.id}=${arm.id}`,
                 bucket,
             };
         }
     }
     return null;
 }
-function betterVariant(candidatePriority, candidateKey, bestPriority, bestKey) {
-    if (candidatePriority !== bestPriority)
-        return candidatePriority > bestPriority;
-    return String(candidateKey || '').localeCompare(String(bestKey || '')) < 0;
-}
 function requestDimensionsMatch(request, values) {
     for (const rawKey in values) {
         const rawWant = values[rawKey];
         const key = String(rawKey).trim();
         const normalized = key.toLowerCase();
         const want = String(rawWant).trim();
-        if (!key || !want || ['audience', 'segment', 'experiment', 'experimentarm'].includes(normalized))
+        if (!key || !want || ['audience', 'segment'].includes(normalized) || normalized.startsWith('experiment.'))
             continue;
         const candidates = (request.query[key] || []).concat(request.query['aci_' + key] || [], request.headers['x-aci-' + normalized] || '', request.headers['x-gradial-' + normalized] || '', request.cookies[key] || '', request.cookies['aci_' + key] || '');
         if (normalized === 'locale') {
@@ -127,52 +227,565 @@ function requestDimensionsMatch(request, values) {
     }
     return true;
 }
-function evaluateRule(request, rule) {
-    const all = (rule.all || []);
-    const any = (rule.any || []);
+const MAX_EXPRESSION_CONDITIONS = 64;
+// Authored nesting depth (ADR 0040). The top-level envelope is depth 1 and a
+// group node is one deeper than the list containing it. Pinned to the
+// capability artifact by the drift test, like the grammars above.
+const MAX_EXPRESSION_DEPTH = 5;
+// A member carrying `all` or `any` is an envelope, not a condition. Presence
+// decides — never the value's type — so all three runtimes classify the same
+// member the same way.
+function isExpressionGroup(member) {
+    // Null-guarded because this runs on a viewer request path: a malformed
+    // member must fail closed to the base experience, never throw. A non-object
+    // member is classified as a leaf and rejected by ordinary validation.
+    return !!member && typeof member === 'object'
+        && (Object.prototype.hasOwnProperty.call(member, 'all')
+            || Object.prototype.hasOwnProperty.call(member, 'any'));
+}
+// expressionMembers returns a group node's member list: [] when the key is
+// absent, null when it is present but not an array. Go rejects that document
+// at decode; here it fails closed as a diagnostic rather than letting the
+// member reclassify as a leaf.
+function expressionMembers(member, group) {
+    if (!Object.prototype.hasOwnProperty.call(member, group))
+        return [];
+    const value = member[group];
+    if (!Array.isArray(value))
+        return null;
+    return value;
+}
+// countExpressionLeaves counts leaves across the tree, applying the same depth
+// cutoff the validating walk does so the two bounds cannot disagree about one
+// expression.
+function countExpressionLeaves(members, depth) {
+    let total = 0;
+    for (const member of members) {
+        if (!isExpressionGroup(member)) {
+            total++;
+            continue;
+        }
+        if (depth + 1 > MAX_EXPRESSION_DEPTH)
+            continue;
+        total += countExpressionLeaves(expressionMembers(member, 'all') || [], depth + 1)
+            + countExpressionLeaves(expressionMembers(member, 'any') || [], depth + 1);
+    }
+    return total;
+}
+/** Evaluate one request expression and produce the same redacted trace used for qualification. */
+export function evaluateRequestExpression(rule, resolve) {
+    const all = (Array.isArray(rule.all) ? rule.all : []);
+    const any = (Array.isArray(rule.any) ? rule.any : []);
+    const empty = all.length + any.length === 0;
+    const diagnostics = validateRequestExpression(rule, all, any);
+    const trace = { scope: 'request', empty, groups: [], leaves: [] };
+    if (diagnostics.length > 0)
+        return { qualified: false, diagnostics, trace };
+    const qualified = qualifyRequestExpression(all, any, resolve, trace);
+    return { qualified, diagnostics, trace };
+}
+function evaluateRule(request, rule, claims, variantKey) {
+    const all = (Array.isArray(rule.all) ? rule.all : []);
+    const any = (Array.isArray(rule.any) ? rule.any : []);
+    const diagnostics = validateRequestExpression(rule, all, any);
+    if (diagnostics.length > 0) {
+        // Records pass the write-time gate before they ship, so a rule rejected
+        // HERE — at serve time — is always version skew or a projection bug, never
+        // ordinary authoring error. That makes it a precise signal, and discarding
+        // it silently is what made the predicted incident (author previews a rule
+        // successfully while a stale lane serves base) undebuggable (ADR 0040).
+        // Codes and paths only; never a fact, operand, or request value.
+        if (request.onRuleRejected) {
+            request.onRuleRejected({
+                variantKey: variantKey || '',
+                diagnosticCode: diagnostics[0].code,
+                diagnosticPath: diagnostics[0].path,
+                diagnosticCount: diagnostics.length,
+            });
+        }
+        return false;
+    }
+    // audience.memberships resolves from the verified (or mimic) claims object
+    // the decision entry points already hold, never from the request bag — an
+    // unverified cookie can never impersonate membership (ADR 0039).
+    return qualifyRequestExpression(all, any, (field) => field === 'audience.memberships'
+        ? membershipsFact(claims)
+        : signalFact(request, field));
+}
+// No claims → unavailable: an unconsented visitor is not a known non-member,
+// so every operator fails closed, exists:false included. Verified claims with
+// no memberships → absent, so exists:false selects exactly the consented
+// visitor who belongs to nothing (ADR 0039).
+function membershipsFact(claims) {
+    if (!claims)
+        return { status: 'unavailable' };
+    // Array.isArray, not || []: a malformed truthy aud (a scalar from a buggy
+    // claims writer) must degrade to absent, never reach the matcher's
+    // .some() and throw on a viewer-request path.
+    const memberships = Array.isArray(claims.aud) ? claims.aud : [];
+    return memberships.length > 0 ? { status: 'present', values: memberships } : { status: 'absent' };
+}
+function validateRequestExpression(rule, all, any) {
+    const diagnostics = [];
     if (all.length + any.length === 0)
+        diagnostics.push({ code: 'expression.empty', path: 'expression', scope: 'request', message: 'expression must include at least one all or any condition' });
+    if (countExpressionLeaves(all, 1) + countExpressionLeaves(any, 1) > MAX_EXPRESSION_CONDITIONS)
+        diagnostics.push({ code: 'expression.conditions.too_many', path: 'expression', scope: 'request', message: `expression must contain at most ${MAX_EXPRESSION_CONDITIONS} conditions` });
+    Object.keys(rule).filter((group) => group !== 'all' && group !== 'any').sort().forEach((group) => {
+        diagnostics.push({ code: 'expression.group.unsupported', path: `expression.${group}`, scope: 'request', message: `expression.${group} is not a supported expression group` });
+    });
+    for (const [group, members] of [['all', all], ['any', any]]) {
+        validateExpressionMembers('expression', group, members, 1, diagnostics);
+    }
+    return diagnostics;
+}
+// validateExpressionMembers validates one envelope's member list. depth is the
+// depth of the envelope owning these members; the top-level envelope is 1.
+function validateExpressionMembers(path, group, members, depth, diagnostics) {
+    members.forEach((member, index) => {
+        const memberPath = `${path}.${group}[${index}]`;
+        if (!member || typeof member !== 'object' || !isExpressionGroup(member)) {
+            validateRequestCondition(member || {}, memberPath, diagnostics);
+            return;
+        }
+        // One diagnostic per broken node, and no descent past it: a too-deep
+        // branch reports its depth once rather than once per buried condition.
+        if (depth + 1 > MAX_EXPRESSION_DEPTH) {
+            diagnostics.push({ code: 'expression.depth.exceeded', path: memberPath, scope: 'request', message: `${memberPath} must not nest more than ${MAX_EXPRESSION_DEPTH} levels deep` });
+            return;
+        }
+        const nestedAll = expressionMembers(member, 'all');
+        const nestedAny = expressionMembers(member, 'any');
+        if (nestedAll === null || nestedAny === null) {
+            const malformed = nestedAll === null ? 'all' : 'any';
+            diagnostics.push({ code: 'expression.group.unsupported', path: `${memberPath}.${malformed}`, scope: 'request', message: `${memberPath}.${malformed} must be an array of conditions or groups` });
+            return;
+        }
+        if (nestedAll.length + nestedAny.length === 0) {
+            diagnostics.push({ code: 'expression.empty', path: memberPath, scope: 'request', message: `${memberPath} must include at least one all or any condition` });
+            return;
+        }
+        Object.keys(member).filter((key) => key !== 'all' && key !== 'any').sort().forEach((key) => {
+            // Name the mistake, not its symptom: telling an author that `field` "is
+            // not a supported group" describes the classification, not the error.
+            const message = key === 'field' || key === 'operator' || key === 'value'
+                ? `${memberPath}.${key} is not supported: a member carrying all or any is a group, not a condition, so it cannot also carry ${key}`
+                : `${memberPath}.${key} is not a supported expression group`;
+            diagnostics.push({ code: 'expression.group.unsupported', path: `${memberPath}.${key}`, scope: 'request', message });
+        });
+        validateExpressionMembers(memberPath, 'all', nestedAll, depth + 1, diagnostics);
+        validateExpressionMembers(memberPath, 'any', nestedAny, depth + 1, diagnostics);
+    });
+}
+// qualifyRequestExpression applies the envelope truth table to one node's
+// member lists, recursing through group nodes (ADR 0040). Evaluation stays
+// exhaustive so the trace holds every leaf outcome.
+//
+// topLevel carries nesting's one asymmetry: the top envelope always records
+// both group rows because they express the scope's empty-envelope policy,
+// while a nested node records only for a list it carries members in — which
+// also keeps the trace stable across a serialization that drops empty lists.
+function qualifyRequestExpression(all, any, resolve, trace, path = 'expression', topLevel = true) {
+    let qualified = true;
+    for (const [group, members] of [['all', all], ['any', any]]) {
+        if (!topLevel && members.length === 0)
+            continue;
+        let matched = 0;
+        members.forEach((member, index) => {
+            const memberPath = `${path}.${group}[${index}]`;
+            let passed = false;
+            if (isExpressionGroup(member)) {
+                passed = qualifyRequestExpression(expressionMembers(member, 'all') || [], expressionMembers(member, 'any') || [], resolve, trace, memberPath, false);
+            }
+            else {
+                const fact = normalizeFact(resolve(String(member.field || '')));
+                const outcome = matchRequestCondition(member, fact);
+                passed = outcome.matched;
+                if (trace)
+                    trace.leaves.push({
+                        path: memberPath, group, index,
+                        field: String(member.field || ''), operator: String(member.operator || ''),
+                        status: fact.status, matched: outcome.matched, reason: outcome.reason,
+                    });
+            }
+            if (passed)
+                matched++;
+        });
+        const passed = group === 'all' ? matched === members.length : members.length === 0 || matched > 0;
+        if (trace)
+            trace.groups.push({ path: `${path}.${group}`, group, total: members.length, matched, passed });
+        qualified = qualified && passed;
+    }
+    return qualified;
+}
+function validateRequestCondition(condition, path, diagnostics) {
+    Object.keys(condition).filter((property) => !['field', 'operator', 'value'].includes(property)).sort().forEach((property) => {
+        diagnostics.push({ code: 'expression.property.unsupported', path: `${path}.${property}`, scope: 'request', message: `${path}.${property} is not a supported condition property` });
+    });
+    const field = String(condition.field || '');
+    if (field !== 'referrer' && field !== 'device.class' && field !== 'time.now' && field !== 'audience.memberships' && !['query.', 'header.', 'cookie.', 'geo.', 'utm.'].some((prefix) => field.startsWith(prefix) && field.length > prefix.length)) {
+        diagnostics.push({ code: 'expression.field.unsupported', path: `${path}.field`, scope: 'request', message: `${path}.field ${JSON.stringify(field)} is not supported` });
+    }
+    const operator = String(condition.operator || '');
+    if (!EXPRESSION_OPERATORS.includes(operator)) {
+        diagnostics.push({ code: 'expression.operator.unsupported', path: `${path}.operator`, scope: 'request', message: `${path}.operator ${JSON.stringify(operator)} is not supported` });
+        return;
+    }
+    // device.class compares against a closed four-value set, so substring
+    // operators express nothing the set cannot — and admitting them would
+    // re-create the user-agent-substring habit inside the safe field (ADR 0037).
+    if (field === 'device.class' && !['equals', 'in', 'exists'].includes(operator)) {
+        diagnostics.push({ code: 'expression.operator.unsupported', path: `${path}.operator`, scope: 'request', message: `${path}.operator ${JSON.stringify(operator)} is not supported for field ${JSON.stringify(field)}, which compares against a closed value set` });
+        return;
+    }
+    // time.now is a sub-second-churning clock: string operators are silently
+    // inert on it and the numeric family can never match an RFC 3339 string
+    // (ADR 0038).
+    if (field === 'time.now' && !['before', 'after', 'between', 'exists'].includes(operator)) {
+        diagnostics.push({ code: 'expression.operator.unsupported', path: `${path}.operator`, scope: 'request', message: `${path}.operator ${JSON.stringify(operator)} is not supported for field ${JSON.stringify(field)}, which supports only before, after, between, exists` });
+        return;
+    }
+    // audience.memberships is an opaque-ID list: equals is already
+    // any-member-equals under the multi-valued match loop, so the substring
+    // family would only add silent overmatching of prefixed IDs, and the
+    // numeric/instant families can never match an ID (ADR 0039).
+    if (field === 'audience.memberships' && !['equals', 'in', 'exists'].includes(operator)) {
+        diagnostics.push({ code: 'expression.operator.unsupported', path: `${path}.operator`, scope: 'request', message: `${path}.operator ${JSON.stringify(operator)} is not supported for field ${JSON.stringify(field)}, which supports only equals, in, exists` });
+        return;
+    }
+    const value = condition.value;
+    if (operator === 'exists') {
+        if (value !== undefined && value !== null && typeof value !== 'boolean') {
+            diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value must be a boolean for operator exists` });
+        }
+        return;
+    }
+    if (value === undefined || value === null) {
+        diagnostics.push({ code: 'expression.value.required', path: `${path}.value`, scope: 'request', message: `${path}.value is required for operator ${operator}` });
+        return;
+    }
+    if (['equals', 'contains', 'startsWith'].includes(operator)) {
+        if (!['string', 'number', 'boolean'].includes(typeof value)
+            || (typeof value === 'number' && !expressionNumberInDomain(value))) {
+            diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value must be a string, boolean, or finite number using only safe integers` });
+        }
+        else if (field === 'device.class' && DEVICE_CLASSES.indexOf(canonicalScalar(value)) < 0) {
+            diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value must be one of ${DEVICE_CLASSES.join(', ')} for field ${JSON.stringify(field)}` });
+        }
+        return;
+    }
+    if (['greaterThan', 'greaterThanOrEqual', 'lessThan', 'lessThanOrEqual'].includes(operator)) {
+        if (typeof value !== 'number' || !expressionNumberInDomain(value)) {
+            diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value must be a finite JSON number using only safe integers for operator ${operator}` });
+        }
+        return;
+    }
+    if (operator === 'before' || operator === 'after') {
+        if (typeof value !== 'string' || parseExpressionTimestamp(value) === null) {
+            diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value must be an RFC 3339 timestamp with an explicit UTC offset for operator ${operator}` });
+        }
+        return;
+    }
+    if (operator === 'between') {
+        if (!validExpressionRange(value)) {
+            diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value must be a min/max object whose bounds are both numbers or both timestamps with min not above max` });
+        }
+        else if (field === 'time.now' && typeof value.min === 'number') {
+            // An instant field's observed values are instants: a numeric range on
+            // it would validate and then sit silently inert at execution.
+            diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value bounds must be timestamps for field ${JSON.stringify(field)}` });
+        }
+        return;
+    }
+    // in: bounded, non-empty, every member one canonicalizable scalar, all
+    // members one JSON type — a mixed list is almost always an authoring bug.
+    const members = homogeneousExpressionMembers(value);
+    if (members === null) {
+        diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value must be an array of 1 to ${MAX_IN_VALUES} scalars sharing one type` });
+        return;
+    }
+    if (field === 'device.class') {
+        for (const member of members) {
+            if (DEVICE_CLASSES.indexOf(member) < 0) {
+                diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value must be one of ${DEVICE_CLASSES.join(', ')} for field ${JSON.stringify(field)}` });
+                return;
+            }
+        }
+    }
+}
+function matchRequestCondition(condition, fact) {
+    if (fact.status === 'unavailable')
+        return { matched: false, reason: 'unavailable' };
+    if (condition.operator === 'exists') {
+        const expected = typeof condition.value === 'boolean' ? condition.value : true;
+        const matched = (fact.status === 'present') === expected;
+        return { matched, reason: matched ? 'matched' : fact.status === 'absent' ? 'absent' : 'not_matched' };
+    }
+    if (fact.status === 'absent')
+        return { matched: false, reason: 'absent' };
+    const matcher = expressionConditionMatcher(condition);
+    if (!matcher)
+        return { matched: false, reason: 'not_matched' };
+    const matched = (fact.values || []).some(matcher);
+    return { matched, reason: matched ? 'matched' : 'not_matched' };
+}
+export const EXPRESSION_OPERATORS = [
+    'equals', 'contains', 'startsWith', 'exists',
+    'greaterThan', 'greaterThanOrEqual', 'lessThan', 'lessThanOrEqual',
+    'before', 'after', 'between', 'in',
+];
+const MAX_IN_VALUES = 32;
+// Observed values are gated on the published grammars before any host parser
+// runs (ADR 0038): Number() and Date.parse accept supersets (hex, empty
+// string, vendor date formats) that would let the same fact match here and
+// not in Go. Keep these literals identical to the capability artifact — the
+// drift test compares them byte-for-byte.
+export const EXPRESSION_NUMBER_GRAMMAR = /^-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?$/;
+export const EXPRESSION_TIMESTAMP_GRAMMAR = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/;
+function expressionNumberInDomain(value) {
+    if (!Number.isFinite(value))
+        return false;
+    if (Number.isInteger(value) && !Number.isSafeInteger(value))
+        return false;
+    return true;
+}
+function parseObservedExpressionNumber(value) {
+    if (!EXPRESSION_NUMBER_GRAMMAR.test(value))
+        return null;
+    const parsed = Number(value);
+    return expressionNumberInDomain(parsed) ? parsed : null;
+}
+// Explicit calendar validation runs before Date arithmetic because Date.UTC
+// (like Go's time.Date) silently normalizes impossible dates. Instants
+// compare as epoch milliseconds; fractional seconds truncate to milliseconds.
+function parseExpressionTimestamp(value) {
+    const match = EXPRESSION_TIMESTAMP_GRAMMAR.exec(value);
+    if (!match)
+        return null;
+    const year = Number(match[1]), month = Number(match[2]), day = Number(match[3]);
+    const hour = Number(match[4]), minute = Number(match[5]), second = Number(match[6]);
+    if (month < 1 || month > 12 || day < 1 || day > expressionDaysInMonth(year, month))
+        return null;
+    if (hour > 23 || minute > 59 || second > 59)
+        return null;
+    let offsetMinutes = 0;
+    if (match[8] !== 'Z') {
+        const offsetHour = Number(match[8].slice(1, 3)), offsetMinute = Number(match[8].slice(4, 6));
+        if (offsetHour > 23 || offsetMinute > 59)
+            return null;
+        offsetMinutes = offsetHour * 60 + offsetMinute;
+        if (match[8][0] === '-')
+            offsetMinutes = -offsetMinutes;
+    }
+    const fractionMillis = match[7] ? Number((match[7].slice(1) + '00').slice(0, 3)) : 0;
+    // setUTCFullYear, not Date.UTC: Date.UTC maps two-digit years to 1900+.
+    const date = new Date(0);
+    date.setUTCFullYear(year, month - 1, day);
+    date.setUTCHours(hour, minute, second, 0);
+    return date.getTime() - offsetMinutes * 60000 + fractionMillis;
+}
+function expressionDaysInMonth(year, month) {
+    if (month === 4 || month === 6 || month === 9 || month === 11)
+        return 30;
+    if (month === 2)
+        return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0) ? 29 : 28;
+    return 31;
+}
+function scalarExpressionOperand(value) {
+    if (value === undefined || value === null)
+        return null;
+    const kind = typeof value;
+    if (kind !== 'string' && kind !== 'number' && kind !== 'boolean')
+        return null;
+    if (kind === 'number' && !expressionNumberInDomain(value))
+        return null;
+    return canonicalScalar(value);
+}
+function validExpressionRange(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
         return false;
-    return all.every((condition) => evaluateCondition(request, condition))
-        && (any.length === 0 || any.some((condition) => evaluateCondition(request, condition)));
-}
-function evaluateCondition(request, condition) {
-    const values = signalValues(request, String(condition.field || ''));
-    if (condition.operator === 'exists')
-        return values.length > 0;
-    if (values.length === 0 || typeof condition.value !== 'string' && typeof condition.value !== 'number' && typeof condition.value !== 'boolean')
+    const record = value;
+    if (Object.keys(record).some((key) => key !== 'min' && key !== 'max'))
         return false;
-    const e = String(condition.value);
-    if (condition.operator === 'equals')
-        return values.some(v => v === e);
-    if (condition.operator === 'contains')
-        return values.some(v => v.includes(e));
-    if (condition.operator === 'startsWith')
-        return values.some(v => v.startsWith(e));
-    return false;
-}
-function signalValues(request, field) {
+    const min = record.min, max = record.max;
+    if (min === undefined || min === null || max === undefined || max === null)
+        return false;
+    if (typeof min === 'number' && expressionNumberInDomain(min)) {
+        return typeof max === 'number' && expressionNumberInDomain(max) && min <= max;
+    }
+    const minMillis = typeof min === 'string' ? parseExpressionTimestamp(min) : null;
+    if (minMillis === null)
+        return false;
+    const maxMillis = typeof max === 'string' ? parseExpressionTimestamp(max) : null;
+    return maxMillis !== null && minMillis <= maxMillis;
+}
+function homogeneousExpressionMembers(value) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > MAX_IN_VALUES)
+        return null;
+    let memberKind = '';
+    const members = [];
+    for (const member of value) {
+        const kind = typeof member;
+        if (kind !== 'string' && kind !== 'number' && kind !== 'boolean')
+            return null;
+        if (kind === 'number' && !expressionNumberInDomain(member))
+            return null;
+        if (!memberKind)
+            memberKind = kind;
+        else if (memberKind !== kind)
+            return null;
+        members.push(canonicalScalar(member));
+    }
+    return members;
+}
+// expressionConditionMatcher builds the per-observed-value predicate for one
+// condition. Null means the authored side cannot be interpreted — validation
+// rejects those expressions first, so this only fails closed for direct use.
+function expressionConditionMatcher(condition) {
+    const operator = String(condition.operator || '');
+    const operand = condition.value;
+    switch (operator) {
+        case 'equals':
+        case 'contains':
+        case 'startsWith': {
+            const expected = scalarExpressionOperand(operand);
+            if (expected === null)
+                return null;
+            return (value) => operator === 'equals' ? value === expected
+                : operator === 'contains' ? value.includes(expected) : value.startsWith(expected);
+        }
+        case 'greaterThan':
+        case 'greaterThanOrEqual':
+        case 'lessThan':
+        case 'lessThanOrEqual': {
+            if (typeof operand !== 'number' || !expressionNumberInDomain(operand))
+                return null;
+            return (value) => {
+                const observed = parseObservedExpressionNumber(value);
+                if (observed === null)
+                    return false;
+                return operator === 'greaterThan' ? observed > operand
+                    : operator === 'greaterThanOrEqual' ? observed >= operand
+                        : operator === 'lessThan' ? observed < operand : observed <= operand;
+            };
+        }
+        case 'before':
+        case 'after': {
+            const operandMillis = typeof operand === 'string' ? parseExpressionTimestamp(operand) : null;
+            if (operandMillis === null)
+                return null;
+            return (value) => {
+                const observed = parseExpressionTimestamp(value);
+                if (observed === null)
+                    return false;
+                return operator === 'after' ? observed > operandMillis : observed < operandMillis;
+            };
+        }
+        case 'between': {
+            if (!validExpressionRange(operand))
+                return null;
+            const record = operand;
+            if (typeof record.min === 'number') {
+                const min = record.min, max = record.max;
+                return (value) => {
+                    const observed = parseObservedExpressionNumber(value);
+                    return observed !== null && observed >= min && observed <= max;
+                };
+            }
+            const min = parseExpressionTimestamp(record.min);
+            const max = parseExpressionTimestamp(record.max);
+            return (value) => {
+                const observed = parseExpressionTimestamp(value);
+                return observed !== null && observed >= min && observed <= max;
+            };
+        }
+        case 'in': {
+            if (!Array.isArray(operand) || operand.length === 0 || operand.length > MAX_IN_VALUES)
+                return null;
+            const members = [];
+            for (const member of operand) {
+                const canonical = scalarExpressionOperand(member);
+                if (canonical === null)
+                    return null;
+                members.push(canonical);
+            }
+            return (value) => members.includes(value);
+        }
+        default:
+            return null;
+    }
+}
+function canonicalScalar(value) {
+    if (typeof value === 'number')
+        return Object.is(value, -0) ? '0' : JSON.stringify(value);
+    return String(value);
+}
+function normalizeFact(fact) {
+    if (!fact || !['present', 'absent', 'unavailable'].includes(fact.status))
+        return { status: 'unavailable' };
+    return fact;
+}
+function signalFact(request, field) {
+    const own = (record, key) => !!record && Object.prototype.hasOwnProperty.call(record, key);
     const d = field.indexOf('.');
-    if (d < 0)
-        return field === 'referrer' ? [request.headers.referer || request.headers.referrer].filter(Boolean) : [];
+    if (d < 0) {
+        if (field !== 'referrer')
+            return { status: 'absent' };
+        const key = own(request.headers, 'referer') ? 'referer' : 'referrer';
+        return own(request.headers, key) ? { status: 'present', values: [request.headers[key]] } : { status: 'absent' };
+    }
     const p = field.slice(0, d), k = field.slice(d + 1);
     if (p === 'query')
-        return request.query[k] || [];
-    if (p === 'utm')
-        return request.query['utm_' + k] || [];
+        return own(request.query, k) ? { status: 'present', values: request.query[k] } : { status: 'absent' };
+    if (p === 'utm') {
+        const key = 'utm_' + k;
+        return own(request.query, key) ? { status: 'present', values: request.query[key] } : { status: 'absent' };
+    }
     if (p === 'header') {
-        const v = request.headers[k.toLowerCase()];
-        return v ? [v] : [];
+        const key = k.toLowerCase();
+        return own(request.headers, key) ? { status: 'present', values: [request.headers[key]] } : { status: 'absent' };
     }
-    if (p === 'cookie') {
-        const v = request.cookies[k];
-        return v ? [v] : [];
+    if (p === 'cookie')
+        return own(request.cookies, k) ? { status: 'present', values: [request.cookies[k]] } : { status: 'absent' };
+    if (p === 'device') {
+        // Derived, not injected: no signals plumbing, so preview, edge, and SDK
+        // agree by construction. A request with no user-agent header is absent.
+        if (k !== 'class')
+            return { status: 'absent' };
+        const deviceClass = cachedDeviceClass(request);
+        return deviceClass ? { status: 'present', values: [deviceClass] } : { status: 'absent' };
     }
     if (p === 'geo') {
-        const g = request.signals && request.signals.geo;
-        const v = g && g[k.toLowerCase()];
-        return v ? [v] : [];
+        const record = request.signals?.geo;
+        if (!record)
+            return { status: 'unavailable' };
+        return own(record, k) ? { status: 'present', values: [record[k]] } : { status: 'absent' };
     }
-    return [];
+    if (p === 'time') {
+        // The one clock fact (ADR 0038): resolved from the runtime's own clock,
+        // one RFC 3339 UTC value, so the kernel stays clock-free. Hosts set
+        // request.now (epoch ms) once per request for determinism.
+        if (k !== 'now')
+            return { status: 'absent' };
+        return { status: 'present', values: [cachedTimeNow(request)] };
+    }
+    return { status: 'absent' };
+}
+const TIME_NOW_CACHE = new WeakMap();
+// cachedTimeNow resolves the clock ONCE per request context, like
+// cachedDeviceClass: every time.now leaf in one evaluation reads the same
+// instant. A host-supplied request.now outside Date's representable range
+// falls back to the runtime clock rather than throwing from a viewer-request
+// path — this module fails closed, never open.
+function cachedTimeNow(request) {
+    const hit = TIME_NOW_CACHE.get(request);
+    if (hit !== undefined)
+        return hit;
+    const pinned = typeof request.now === 'number' && Number.isFinite(request.now)
+        && Math.abs(request.now) <= 8640000000000000 ? request.now : Date.now();
+    const value = new Date(pinned).toISOString();
+    TIME_NOW_CACHE.set(request, value);
+    return value;
 }
 // SHA-256 mirrors experiment/assignment.go: the first eight digest bytes are
 // interpreted big-endian and reduced modulo 10,000 basis points. Keep the
@@ -257,114 +870,91 @@ function utf8(value) {
     }
     return new Uint8Array(out);
 }
-// ── Normalized two-phase model: classify → decide ─────────────────────
+// ── Derived request device class (ADR 0037) ──────────────────────────
 //
-// Phase 1 (classify): evaluate all audience/segment rules page-agnostically
-// and assign experiment arms. Returns a Classification that is used by
-// Phase 2 for cheap set-membership lookups per route.
+// device.class is the one request fact that is neither transcribed from the
+// request nor injected as a signal: it is classified here from headers the
+// request already carries, so this module, the released SDK copy, and the Go
+// preview evaluator agree without three separate plumbing points.
 //
-// Phase 2 (decide): for a given route record, check which variants match
-// the classification (set membership + priority). No rule evaluation —
-// just "is this audience in matchedAudiences?" and "is this experiment arm
-// the one we assigned?"
-//
-// The per-route record stays small: just variant keys (e.g.
-// "audience=trade") + priorities. Rules live in the classification data,
-// evaluated once per request.
+// The ORDER below is the contract, not an implementation detail. It is fixed
+// by internal/domain/audience/testdata/device-class.v1.json, which Go and both
+// TypeScript copies execute. Change the order only by changing that fixture.
 //
+// The result is approximate and derived from client-controlled input: a
+// personalization convenience, never an authorization or entitlement input.
+export const DEVICE_CLASSES = ['desktop', 'mobile', 'tablet', 'unknown'];
+// Mirrors MaxDeviceHeaderBytes in internal/domain/audience/device.go.
+const MAX_DEVICE_HEADER_BYTES = 512;
+// Tablet runs first because Android tablet agents contain "android" (mobile)
+// and every Android agent contains "linux" (desktop); iPad agents contain
+// neither. Sec-CH-UA-Mobile is a tiebreaker rather than the primary source
+// because UA-CH cannot express tablet at all.
+const DEVICE_TABLET_SIGNATURES = ['ipad', 'tablet', 'playbook', 'kindle', 'silk'];
+// 'iemobile' is deliberately absent: it contains 'mobi' and could never
+// match. Every signature must be reachable given the ones before it.
+const DEVICE_MOBILE_SIGNATURES = ['iphone', 'ipod', 'mobi', 'windows phone', 'blackberry', 'opera mini'];
+const DEVICE_DESKTOP_SIGNATURES = ['windows nt', 'macintosh', 'mac os x', 'x11', 'cros', 'linux'];
 /**
- * Phase 1: Classify the visitor against all release-level rules.
- *
- * @param ctx     The request context (cookies, headers, geo, query)
- * @param data    Release-level classification data (audiences, segments, experiments)
- * @param identity Visitor identity (for experiment bucketing). Pass undefined
- *                 if no identity or privacy denied.
- * @returns Classification — matched audiences, segments, and experiment arm assignments
+ * Classifies the request's device class from its own headers. Returns '' when
+ * the request carried neither User-Agent nor Sec-CH-UA-Mobile, which the fact
+ * resolver reports as ABSENT — the same status the missing header itself
+ * resolves to, and deliberately distinct from the 'unknown' class, which means
+ * classified and unrecognized.
  */
-export function classify(ctx, data, identity) {
-    // Evaluate audience rules
-    const matchedAudiences = [];
-    for (const key in data.audiences) {
-        const def = data.audiences[key];
-        if (def.rule && evaluateRule(ctx, def.rule)) {
-            matchedAudiences.push(key);
-        }
-    }
-    // Evaluate segment rules
-    const matchedSegments = [];
-    for (const key in data.segments) {
-        const def = data.segments[key];
-        if (def.rule && evaluateRule(ctx, def.rule)) {
-            matchedSegments.push(key);
-        }
-    }
-    // Assign experiment arms (only for identified visitors)
-    const experimentArms = {};
-    if (identity && identity.usable) {
-        for (const expId in data.experiments) {
-            const exp = data.experiments[expId];
-            if (exp.status !== 'running')
-                continue;
-            if (exp.kind !== 'ab' && exp.kind !== 'abn')
-                continue;
-            const assignment = assignExperiment(exp, identity);
-            if (assignment) {
-                experimentArms[expId] = assignment;
-            }
-        }
-    }
-    return { matchedAudiences, matchedSegments, experimentArms };
+export function deviceClassFromHeaders(headers) {
+    const userAgent = deviceHeader(headers, 'user-agent');
+    const uaMobile = deviceHeader(headers, 'sec-ch-ua-mobile');
+    if (!userAgent && !uaMobile)
+        return '';
+    const lower = userAgent.toLowerCase();
+    if (DEVICE_TABLET_SIGNATURES.some((token) => lower.indexOf(token) >= 0))
+        return 'tablet';
+    // An Android agent without a "mobi" token is a tablet: Chrome on Android
+    // phones appends "Mobile", Android tablets do not. The explicit !"mobi"
+    // guard is required, not redundant — the mobile pass runs AFTER this one.
+    if (lower.indexOf('android') >= 0 && lower.indexOf('mobi') < 0)
+        return 'tablet';
+    if (DEVICE_MOBILE_SIGNATURES.some((token) => lower.indexOf(token) >= 0))
+        return 'mobile';
+    if (uaMobile === '?1')
+        return 'mobile';
+    if (DEVICE_DESKTOP_SIGNATURES.some((token) => lower.indexOf(token) >= 0))
+        return 'desktop';
+    if (uaMobile === '?0')
+        return 'desktop';
+    return 'unknown';
 }
-/**
- * Phase 2: Decide the winning variant for a specific route.
- *
- * Uses the classification from Phase 1 for cheap set-membership lookups.
- * No rule evaluation — just set membership and priority comparison.
- *
- * @param record        The route entry (path, dispatch, variants)
- * @param classification The visitor's classification from Phase 1
- * @returns The decision — winning variant + experiment assignment, or nulls
- */
-export function decide(record, classification, ctx) {
-    if (!record.variants)
-        return { variant: null, experiment: null };
-    let bestVariant = null;
-    let bestExperiment = null;
-    for (const key in record.variants) {
-        const variant = record.variants[key];
-        if (!variant.variantKey)
-            variant.variantKey = key;
-        const values = variant.variantValues || variantValuesFromKey(key);
-        // Check if this variant references a paused experiment — skip if so
-        const experimentID = String(values.experiment || '').trim();
-        if (experimentID && !classification.experimentArms[experimentID])
-            continue;
-        let matched = false;
-        // Audience membership
-        if (values.audience && classification.matchedAudiences.includes(values.audience)) {
-            matched = true;
-        }
-        // Segment membership
-        if (!matched && values.segment && classification.matchedSegments.includes(values.segment)) {
-            matched = true;
-        }
-        // Experiment arm assignment
-        if (!matched && experimentID) {
-            const arm = classification.experimentArms[experimentID];
-            if (arm && arm.variantKey === variant.variantKey) {
-                matched = true;
-                bestExperiment = arm;
-            }
-        }
-        if (matched) {
-            if (!bestVariant || betterVariant(variant.priority || 0, variant.variantKey, bestVariant.priority || 0, bestVariant.variantKey)) {
-                bestVariant = variant;
-                // Only set experiment if this variant's experiment arm won
-                if (!experimentID || !classification.experimentArms[experimentID]) {
-                    bestExperiment = null;
-                }
-            }
-        }
-    }
-    return { variant: bestVariant, experiment: bestExperiment };
+// deviceHeader reads one header so that Go's audience.ClassifyDeviceClass
+// cannot disagree with this function about the same request.
+//
+// Keys are lowercase here: every context builder flattens through the Fetch
+// API, which lowercases. There is deliberately NO case-insensitive fallback —
+// the header.* branch above has none either, and adding one for this field
+// only would mean a device rule resolves where an equivalent header rule
+// silently does not.
+//
+// Trimming is ASCII-only on purpose. String.prototype.trim strips U+FEFF but
+// not U+0085; Go's strings.TrimSpace does the reverse. Neither is "right";
+// they only have to match, so both sides trim the same ASCII set. The length
+// bound matches MaxDeviceHeaderBytes in device.go — no signature lives past
+// it, and the header is attacker-sized on an unauthenticated path.
+function deviceHeader(headers, key) {
+    const raw = (headers && headers[key]) || '';
+    if (typeof raw !== 'string')
+        return '';
+    return raw.slice(0, MAX_DEVICE_HEADER_BYTES).replace(/^[ \t\r\n\f\v]+|[ \t\r\n\f\v]+$/g, '');
+}
+// The class describes the REQUEST, so it is identical for every leaf. An
+// envelope may carry up to 64 conditions and a route many candidate variants,
+// each building its own resolver — without this, one page view could lowercase
+// and scan the user agent hundreds of times. Keyed on the context object, so
+const DEVICE_CLASS_CACHE = new WeakMap();
+function cachedDeviceClass(request) {
+    const hit = DEVICE_CLASS_CACHE.get(request);
+    if (hit !== undefined)
+        return hit;
+    const deviceClass = deviceClassFromHeaders(request.headers);
+    DEVICE_CLASS_CACHE.set(request, deviceClass);
+    return deviceClass;
 }