@gradial/aci 0.1.52-rc.2 → 0.1.52-rc.21

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

@@ -5,12 +5,6 @@
 // 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) {
     if (!route)
         return { variant: null, experiment: null };
@@ -20,6 +14,7 @@ export function resolvePersonalizationDecision(request, route, claims, experimen
         const candidates = Object.values(experiments)
             .filter((item) => (item.kind === 'ab' || item.kind === 'abn') && item.status === 'running')
             .filter((item) => routeHasExperiment(route, item.id))
+            .filter((item) => experimentEligible(item, claims))
             .sort((left, right) => (right.priority || 0) - (left.priority || 0)
             || String(left.id || '').localeCompare(String(right.id || '')));
         for (let index = 0; index < candidates.length; index++) {
@@ -30,6 +25,13 @@ export function resolvePersonalizationDecision(request, route, claims, experimen
                 continue;
             if (assignment && !candidate.variantKey)
                 candidate.variantKey = assignment.variantKey;
+            // A bucket assignment is candidacy, not entitlement: an arm variant
+            // carrying a rule must pass the same serve-time evaluation the rule
+            // leg applies (ADR 0040). A rejection fires the onRuleRejected sink
+            // inside evaluateRule; the candidate is skipped — never served, and
+            // never left behind as a stale experiment decision.
+            if (candidate.rule && !evaluateRule(request, candidate.rule, claims, candidate.variantKey))
+                continue;
             if (!variant || betterVariant(candidate.priority || 0, candidate.variantKey, variant.priority || 0, variant.variantKey)) {
                 variant = candidate;
                 experiment = assignment;
@@ -50,13 +52,14 @@ function selectRuleVariant(request, route, claims, experiments) {
         const values = variant.variantValues || variantValuesFromKey(key);
         const experimentID = String(values.experiment || '').trim();
         if (experimentID && (!experiments || !experiments[experimentID]
-            || experiments[experimentID].status !== 'running'))
+            || experiments[experimentID].status !== 'running'
+            || !experimentEligible(experiments[experimentID], claims)))
             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;
+        const ruleMatch = variant.rule ? evaluateRule(request, variant.rule, claims, variant.variantKey) : false;
         if (membershipMatch || ruleMatch)
             matches.push(variant);
     }
@@ -64,6 +67,16 @@ function selectRuleVariant(request, route, claims, experiments) {
         || String(left.variantKey || '').localeCompare(String(right.variantKey || '')));
     return matches[0] || null;
 }
+// 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.
+function experimentEligible(item, claims) {
+    const audienceID = String(item.eligibilityAudienceId || '').trim();
+    if (!audienceID)
+        return true;
+    return !!claims && (claims.aud || []).includes(audienceID);
+}
 function routeHasExperiment(route, experimentID) {
     for (const key in route.variants || {}) {
         const values = route.variants[key].variantValues || variantValuesFromKey(key);
@@ -127,52 +140,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 codec 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;
-    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')
+    if (Number.isInteger(value) && !Number.isSafeInteger(value))
         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;
+    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;
+    const record = value;
+    if (Object.keys(record).some((key) => key !== 'min' && key !== 'max'))
+        return false;
+    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 signalValues(request, field) {
+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' };
+    }
+    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 [];
+    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
@@ -264,9 +790,10 @@ function utf8(value) {
 // Phase 2 for cheap set-membership lookups per route.
 //
 // 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 classification (set membership + priority). Audience/segment rules
+// were evaluated in Phase 1; an experiment arm variant's own rule is
+// evaluated here at commit time, because a bucket assignment is candidacy,
+// not entitlement (ADR 0040).
 //
 // The per-route record stays small: just variant keys (e.g.
 // "audience=trade") + priorities. Rules live in the classification data,
@@ -279,14 +806,18 @@ function utf8(value) {
  * @param data    Release-level classification data (audiences, segments, experiments)
  * @param identity Visitor identity (for experiment bucketing). Pass undefined
  *                 if no identity or privacy denied.
+ * @param claims  The verified claims the caller already holds (eligibility
+ *                gate input, ASE-F4). Undefined/null means "no claims" —
+ *                gated experiments are skipped.
  * @returns Classification — matched audiences, segments, and experiment arm assignments
  */
-export function classify(ctx, data, identity) {
-    // Evaluate audience rules
+export function classify(ctx, data, identity, claims) {
+    // Evaluate audience rules. Claims feed the audience.memberships fact
+    // (ADR 0039) exactly as they do in the request-scoped resolver path.
     const matchedAudiences = [];
     for (const key in data.audiences) {
         const def = data.audiences[key];
-        if (def.rule && evaluateRule(ctx, def.rule)) {
+        if (def.rule && evaluateRule(ctx, def.rule, claims, key)) {
             matchedAudiences.push(key);
         }
     }
@@ -294,7 +825,7 @@ export function classify(ctx, data, identity) {
     const matchedSegments = [];
     for (const key in data.segments) {
         const def = data.segments[key];
-        if (def.rule && evaluateRule(ctx, def.rule)) {
+        if (def.rule && evaluateRule(ctx, def.rule, claims, key)) {
             matchedSegments.push(key);
         }
     }
@@ -307,6 +838,8 @@ export function classify(ctx, data, identity) {
                 continue;
             if (exp.kind !== 'ab' && exp.kind !== 'abn')
                 continue;
+            if (!experimentEligible(exp, claims))
+                continue;
             const assignment = assignExperiment(exp, identity);
             if (assignment) {
                 experimentArms[expId] = assignment;
@@ -319,13 +852,20 @@ export function classify(ctx, data, identity) {
  * 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.
+ * Audience/segment rules were already evaluated in Phase 1; the one rule
+ * evaluated here is an experiment arm variant's own rule, because the arm
+ * assignment is candidacy, not entitlement (ADR 0040).
  *
  * @param record        The route entry (path, dispatch, variants)
  * @param classification The visitor's classification from Phase 1
+ * @param ctx           The request context (signal facts + rejection sink)
+ * @param claims        The verified claims the caller already holds — the
+ *                      same object passed to classify() — so an arm variant's
+ *                      audience.memberships rule resolves identically to the
+ *                      resolver path and fails closed without it (ADR 0039).
  * @returns The decision — winning variant + experiment assignment, or nulls
  */
-export function decide(record, classification, ctx) {
+export function decide(record, classification, ctx, claims) {
     if (!record.variants)
         return { variant: null, experiment: null };
     let bestVariant = null;
@@ -348,23 +888,118 @@ export function decide(record, classification, ctx) {
         if (!matched && values.segment && classification.matchedSegments.includes(values.segment)) {
             matched = true;
         }
-        // Experiment arm assignment
+        // Experiment arm assignment. The arm is a candidate only — committing it
+        // inside the win block prevents a losing arm variant from leaving a
+        // stale experiment decision behind when another variant wins.
+        let armMatch = null;
         if (!matched && experimentID) {
             const arm = classification.experimentArms[experimentID];
             if (arm && arm.variantKey === variant.variantKey) {
-                matched = true;
-                bestExperiment = arm;
+                // Same ADR 0040 posture as the resolver's experiment leg: the arm
+                // assignment is candidacy only. A rule rejected at serve time (or
+                // unmatched) fires the onRuleRejected sink inside evaluateRule and
+                // skips the variant — never served, no stale experiment decision.
+                if (!variant.rule || evaluateRule(ctx, variant.rule, claims, variant.variantKey)) {
+                    matched = true;
+                    armMatch = 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;
-                }
+                bestExperiment = armMatch;
             }
         }
     }
     return { variant: bestVariant, experiment: bestExperiment };
 }
+// ── Derived request device class (ADR 0037) ──────────────────────────
+//
+// 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.
+//
+// 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'];
+/**
+ * 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 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';
+}
+// 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
+// classify()/decide() reuse it too.
+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;
+}