@gradial/aci 0.1.52-rc.13 → 0.1.52-rc.15

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.52-rc.13` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.52-rc.15` is a pre-1.0 public-surface reset for the ACI
 client SDK. Breaking changes from the old `0.1.x` accidental surface are
 intentional: the root import is framework-neutral, framework runtime behavior is
 behind explicit subpaths, and the first required customer path is React/Next.
@@ -8,7 +8,7 @@ behind explicit subpaths, and the first required customer path is React/Next.
 ## Install
 
 ```bash
-npm install @gradial/aci@0.1.52-rc.13 zod@^4
+npm install @gradial/aci@0.1.52-rc.15 zod@^4
 ```
 
 ## Root Import
@@ -78,13 +78,13 @@ host bundles select and serve immutable release artifacts.
 The first RC scaffold path is Next:
 
 ```bash
-npx @gradial/aci@0.1.52-rc.13 init my-site --template next-starter
+npx @gradial/aci@0.1.52-rc.15 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.52-rc.13 init --list
+npx @gradial/aci@0.1.52-rc.15 init --list
 ```
 
 ## Personalization: The One-Tag Install

package/dist/edge/personalization-core.d.ts

@@ -9,3 +9,27 @@ export function resolvePersonalizationDecision(request: any, route: any, claims:
         bucket: number;
     } | null;
 };
+export function evaluateRequestExpression(rule: any, resolve: any): {
+    qualified: boolean;
+    diagnostics: {
+        code: string;
+        path: string;
+        scope: string;
+        message: string;
+    }[];
+    trace: {
+        scope: string;
+        empty: boolean;
+        groups: never[];
+        leaves: never[];
+    };
+};
+/**
+ * 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: any): "unknown" | "" | "mobile" | "desktop" | "tablet";
+export const DEVICE_CLASSES: string[];

package/dist/edge/personalization-core.js

@@ -141,49 +141,162 @@ function requestDimensionsMatch(request, values) {
     }
     return true;
 }
+const MAX_EXPRESSION_CONDITIONS = 64;
+export function evaluateRequestExpression(rule, resolve) {
+    const all = rule.all || [];
+    const 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) {
     const all = rule.all || [];
     const any = rule.any || [];
-    if (all.length + any.length === 0)
+    if (validateRequestExpression(rule, all, any).length > 0)
         return false;
-    return all.every((condition) => evaluateCondition(request, condition))
-        && (any.length === 0 || any.some((condition) => evaluateCondition(request, condition)));
+    return qualifyRequestExpression(all, any, (field) => signalFact(request, field));
 }
-function evaluateCondition(request, condition) {
-    const values = signalValues(request, condition.field);
-    if (condition.operator === 'exists')
-        return values.length > 0;
-    if (values.length === 0 || !['string', 'number', 'boolean'].includes(typeof condition.value))
-        return false;
-    const expected = String(condition.value);
-    return values.some((value) => {
-        switch (condition.operator) {
-            case 'equals': return value === expected;
-            case 'contains': return value.includes(expected);
-            case 'startsWith': return value.startsWith(expected);
-            default: return false;
-        }
+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 (all.length + any.length > 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, conditions] of [['all', all], ['any', any]]) {
+        conditions.forEach((condition, index) => validateRequestCondition(condition, `expression.${group}[${index}]`, diagnostics));
+    }
+    return diagnostics;
+}
+function qualifyRequestExpression(all, any, resolve, trace) {
+    let qualified = true;
+    for (const [group, conditions] of [['all', all], ['any', any]]) {
+        let matched = 0;
+        conditions.forEach((condition, index) => {
+            const fact = normalizeFact(resolve(String(condition.field || '')));
+            const outcome = matchRequestCondition(condition, fact);
+            if (outcome.matched)
+                matched++;
+            if (trace)
+                trace.leaves.push({
+                    path: `expression.${group}[${index}]`, group, index,
+                    field: String(condition.field || ''), operator: String(condition.operator || ''),
+                    status: fact.status, matched: outcome.matched, reason: outcome.reason,
+                });
+        });
+        const passed = group === 'all' ? matched === conditions.length : conditions.length === 0 || matched > 0;
+        if (trace)
+            trace.groups.push({ group, total: conditions.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' && !['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 (!['equals', 'contains', 'startsWith', 'exists'].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 0035).
+    if (field === 'device.class' && operator !== 'equals' && operator !== 'exists') {
+        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;
+    }
+    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` });
+        }
+    }
+    else if (value === undefined || value === null) {
+        diagnostics.push({ code: 'expression.value.required', path: `${path}.value`, scope: 'request', message: `${path}.value is required for operator ${operator}` });
+    }
+    else if (!['string', 'number', 'boolean'].includes(typeof value)
+        || (typeof value === 'number' && (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(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)}` });
+    }
 }
-function signalValues(request, field) {
-    if (field.startsWith('query.'))
-        return request.query[field.slice(6)] || [];
-    if (field.startsWith('header.'))
-        return request.headers[field.slice(7).toLowerCase()] ? [request.headers[field.slice(7).toLowerCase()]] : [];
-    if (field.startsWith('cookie.'))
-        return request.cookies[field.slice(7)] ? [request.cookies[field.slice(7)]] : [];
-    if (field.startsWith('utm.'))
-        return request.query['utm_' + field.slice(4)] || [];
-    if (field.startsWith('geo.')) {
-        const geo = request.signals && request.signals.geo;
-        const value = geo && geo[field.slice(4).toLowerCase()];
-        return value ? [value] : [];
+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 (field === 'referrer') {
-        const value = request.headers.referer || request.headers.referrer;
-        return value ? [value] : [];
+    if (fact.status === 'absent')
+        return { matched: false, reason: 'absent' };
+    const expected = canonicalScalar(condition.value);
+    const matched = (fact.values || []).some((value) => condition.operator === 'equals' ? value === expected
+        : condition.operator === 'contains' ? value.includes(expected)
+            : condition.operator === 'startsWith' ? value.startsWith(expected) : false);
+    return { matched, reason: matched ? 'matched' : 'not_matched' };
+}
+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) {
+        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' };
     }
-    return [];
+    const p = field.slice(0, d), k = field.slice(d + 1);
+    if (p === 'query')
+        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 key = k.toLowerCase();
+        return own(request.headers, key) ? { status: 'present', values: [request.headers[key]] } : { status: 'absent' };
+    }
+    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 record = request.signals && request.signals.geo;
+        if (!record)
+            return { status: 'unavailable' };
+        return own(record, k) ? { status: 'present', values: [record[k]] } : { status: 'absent' };
+    }
+    return { status: 'absent' };
 }
 // SHA-256 mirrors experiment.assignment.go: the first eight digest bytes are
 // interpreted big-endian and reduced modulo 10,000 basis points.
@@ -279,3 +392,92 @@ function utf8(value) {
     return new Uint8Array(out);
 }
 // CLOUDFRONT_STRIP_END
+// ── Derived request device class (ADR 0035) ──────────────────────────
+//
+// 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;
+}

package/dist/internal/domain/edge/personalization-core.d.ts

@@ -1,6 +1,48 @@
 import type { PersonalizationRequestContext, PersonalizationClaims, PersonalizationVariant, PersonalizationRoute, PersonalizationExperiment, PersonalizationIdentity, PersonalizationDecision, ClassificationData, Classification, EdgeRouteEntry } from './types.js';
 export declare function selectPersonalizationVariant(request: PersonalizationRequestContext, route: PersonalizationRoute | null, claims: PersonalizationClaims | null, experiments?: Record<string, PersonalizationExperiment>, identity?: PersonalizationIdentity): PersonalizationVariant | null;
 export declare function resolvePersonalizationDecision(request: PersonalizationRequestContext, route: PersonalizationRoute | null, claims: PersonalizationClaims | null, experiments?: Record<string, PersonalizationExperiment>, identity?: PersonalizationIdentity): PersonalizationDecision;
+export type ExpressionFactStatus = 'present' | 'absent' | 'unavailable';
+export interface ExpressionFact {
+    status: ExpressionFactStatus;
+    values?: string[];
+}
+export interface ExpressionDiagnostic {
+    code: string;
+    path: string;
+    scope: 'request';
+    message: string;
+}
+export interface ExpressionLeafTrace {
+    path: string;
+    group: 'all' | 'any';
+    index: number;
+    field: string;
+    operator: string;
+    status: ExpressionFactStatus;
+    matched: boolean;
+    reason: 'matched' | 'not_matched' | 'absent' | 'unavailable';
+}
+export interface ExpressionGroupTrace {
+    group: 'all' | 'any';
+    total: number;
+    matched: number;
+    passed: boolean;
+}
+export interface RequestExpressionResult {
+    qualified: boolean;
+    diagnostics: ExpressionDiagnostic[];
+    trace: {
+        scope: 'request';
+        empty: boolean;
+        groups: ExpressionGroupTrace[];
+        leaves: ExpressionLeafTrace[];
+    };
+}
+/** Evaluate one request expression and produce the same redacted trace used for qualification. */
+export declare function evaluateRequestExpression(rule: {
+    all?: unknown[];
+    any?: unknown[];
+}, resolve: (field: string) => ExpressionFact): RequestExpressionResult;
 /**
  * Phase 1: Classify the visitor against all release-level rules.
  *
@@ -25,3 +67,12 @@ export declare function classify(ctx: PersonalizationRequestContext, data: Class
  * @returns The decision — winning variant + experiment assignment, or nulls
  */
 export declare function decide(record: EdgeRouteEntry, classification: Classification, ctx: PersonalizationRequestContext): PersonalizationDecision;
+export declare const DEVICE_CLASSES: string[];
+/**
+ * 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 declare function deviceClassFromHeaders(headers: Record<string, string>): string;

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

@@ -139,52 +139,163 @@ function requestDimensionsMatch(request, values) {
     }
     return true;
 }
+const MAX_EXPRESSION_CONDITIONS = 64;
+/** Evaluate one request expression and produce the same redacted trace used for qualification. */
+export function evaluateRequestExpression(rule, resolve) {
+    const all = (rule.all || []);
+    const 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) {
     const all = (rule.all || []);
     const any = (rule.any || []);
-    if (all.length + any.length === 0)
+    if (validateRequestExpression(rule, all, any).length > 0)
         return false;
-    return all.every((condition) => evaluateCondition(request, condition))
-        && (any.length === 0 || any.some((condition) => evaluateCondition(request, condition)));
+    return qualifyRequestExpression(all, any, (field) => signalFact(request, field));
 }
-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')
-        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 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 (all.length + any.length > 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, conditions] of [['all', all], ['any', any]]) {
+        conditions.forEach((condition, index) => validateRequestCondition(condition, `expression.${group}[${index}]`, diagnostics));
+    }
+    return diagnostics;
+}
+function qualifyRequestExpression(all, any, resolve, trace) {
+    let qualified = true;
+    for (const [group, conditions] of [['all', all], ['any', any]]) {
+        let matched = 0;
+        conditions.forEach((condition, index) => {
+            const fact = normalizeFact(resolve(String(condition.field || '')));
+            const outcome = matchRequestCondition(condition, fact);
+            if (outcome.matched)
+                matched++;
+            if (trace)
+                trace.leaves.push({
+                    path: `expression.${group}[${index}]`, group, index,
+                    field: String(condition.field || ''), operator: String(condition.operator || ''),
+                    status: fact.status, matched: outcome.matched, reason: outcome.reason,
+                });
+        });
+        const passed = group === 'all' ? matched === conditions.length : conditions.length === 0 || matched > 0;
+        if (trace)
+            trace.groups.push({ group, total: conditions.length, matched, passed });
+        qualified = qualified && passed;
+    }
+    return qualified;
 }
-function signalValues(request, field) {
+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' && !['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 (!['equals', 'contains', 'startsWith', 'exists'].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' && operator !== 'equals' && operator !== 'exists') {
+        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;
+    }
+    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` });
+        }
+    }
+    else if (value === undefined || value === null) {
+        diagnostics.push({ code: 'expression.value.required', path: `${path}.value`, scope: 'request', message: `${path}.value is required for operator ${operator}` });
+    }
+    else if (!['string', 'number', 'boolean'].includes(typeof value)
+        || (typeof value === 'number' && (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(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)}` });
+    }
+}
+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 expected = canonicalScalar(condition.value);
+    const matched = (fact.values || []).some((value) => condition.operator === 'equals' ? value === expected
+        : condition.operator === 'contains' ? value.includes(expected)
+            : condition.operator === 'startsWith' ? value.startsWith(expected) : false);
+    return { matched, reason: matched ? 'matched' : 'not_matched' };
+}
+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 [];
+    return { status: 'absent' };
 }
 // SHA-256 mirrors experiment/assignment.go: the first eight digest bytes are
 // interpreted big-endian and reduced modulo 10,000 basis points. Keep the
@@ -385,3 +496,92 @@ export function decide(record, classification, ctx) {
     }
     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;
+}

package/dist/internal/domain/edge/record/codec.js

@@ -85,7 +85,7 @@ function projectCondition(cond) {
     if (!compactOp)
         return null;
     const result = { f: cond.field, o: compactOp };
-    if (cond.operator !== 'exists' && cond.value !== undefined)
+    if (cond.value !== undefined)
         result.w = cond.value;
     return result;
 }
@@ -100,7 +100,7 @@ function expandCondition(raw) {
     if (!op)
         return INVALID;
     const c = { field: f, operator: op };
-    if (op !== 'exists' && raw.w !== undefined)
+    if (raw.w !== undefined)
         c.value = raw.w;
     return c;
 }

package/dist/internal/domain/edge/resolve.js

@@ -70,17 +70,16 @@ function toPersonalizationRequestContext(request) {
         (query[key] ||= []).push(value);
     });
     const headers = Object.fromEntries(request.headers.entries());
+    const geo = Object.fromEntries(Object.entries({
+        country: headers['x-vercel-ip-country'] || headers['cloudfront-viewer-country'] || '',
+        region: headers['x-vercel-ip-country-region'] || headers['cloudfront-viewer-country-region'] || '',
+        city: headers['x-vercel-ip-city'] || headers['cloudfront-viewer-city'] || '',
+    }).filter(([, value]) => value !== ''));
     return {
         path: url.pathname,
         query,
         headers,
         cookies: Object.fromEntries(cookies.entries()),
-        signals: {
-            geo: {
-                country: headers['x-vercel-ip-country'] || headers['cloudfront-viewer-country'] || '',
-                region: headers['x-vercel-ip-country-region'] || headers['cloudfront-viewer-country-region'] || '',
-                city: headers['x-vercel-ip-city'] || headers['cloudfront-viewer-city'] || '',
-            },
-        },
+        ...(Object.keys(geo).length > 0 ? { signals: { geo } } : {}),
     };
 }

package/dist/next/collect-route.js

@@ -1,6 +1,7 @@
 import { MAX_BATCH_EVENTS } from '../collect/batcher.js';
 import { computeEnvelopeDigest } from './envelope-digest.js';
 import { validateMimicToken } from '../mimic/core.js';
+import { deviceClassFromHeaders } from '../edge/personalization-core.js';
 import { consentSignals, IdentityErasureFencedError, identityHashHex, parseCookieHeader, verifyClaims, verifyIdentityCookie, } from './personalization-host.js';
 const MAX_COLLECT_BODY_BYTES = 64 * 1024;
 const DEFAULT_RETENTION_SECONDS = 13 * 30 * 24 * 60 * 60;
@@ -19,9 +20,7 @@ const EVENT_FIELDS = new Set([
     'utm',
     'viewport',
     'experiment',
-    'deviceClass',
 ]);
-const DEVICE_CLASSES = new Set(['desktop', 'mobile', 'tablet', 'unknown']);
 function identityHashShard(identityHash) {
     const hash = identityHash.trim().toLowerCase();
     if (hash.length < 2)
@@ -130,6 +129,10 @@ export function createPersonalizationCollectRoute(config) {
             }
             const identityHash = await identityHashHex('aci_id', rawIdentity);
             const geo = collectGeo(request);
+            // Server-derived from the request's own headers by the SAME classifier
+            // request-scope targeting uses (ADR 0035), so a reported class and a
+            // targeted class agree by construction. Never read from the body.
+            const deviceClass = collectDeviceClass(request);
             const collectedAt = now.toISOString();
             const expiresAt = new Date(now.getTime() +
                 (config.retentionSeconds ?? DEFAULT_RETENTION_SECONDS) * 1000).toISOString();
@@ -163,7 +166,7 @@ export function createPersonalizationCollectRoute(config) {
                     // Server-stamped geo (country + region only, D-PDP-14) from the
                     // platform-injected viewer headers; never from the event body.
                     ...(geo ? { geo } : {}),
-                    deviceClass: normalized.deviceClass,
+                    deviceClass,
                     occurredAt: normalized.occurredAt,
                     collectedAt,
                     expiresAt,
@@ -247,9 +250,6 @@ function validateEvent(value) {
     if (value.utm !== undefined && (!value.utm || typeof value.utm !== 'object' || Array.isArray(value.utm))) {
         throw new CollectValidationError('utm must be an object');
     }
-    if (value.deviceClass !== undefined && typeof value.deviceClass !== 'string') {
-        throw new CollectValidationError('deviceClass must be a string');
-    }
     normalizeViewport(value.viewport);
     normalizeExperiment(value.experiment);
 }
@@ -271,7 +271,6 @@ function normalizeEvent(event, now) {
         eventName,
         eventCategory,
         occurredAt,
-        deviceClass: normalizeDeviceClass(event.deviceClass),
         properties: event.properties === undefined ? undefined : sanitizeProperties(event.properties, 'properties', 0),
         page: {
             ...(pageURL ? { url: pageURL } : {}),
@@ -291,10 +290,11 @@ function normalizeEvent(event, now) {
 // keeps its historical byte shape for no-source requests.
 function collectGeo(request) {
     const country = normalizeGeoCountry(request.headers.get('x-vercel-ip-country'));
-    const region = normalizeGeoRegion(request.headers.get('x-vercel-ip-country-region'));
-    if (!country && !region)
+    // A region without its country keys nothing (see runtime/collect.ts).
+    if (!country)
         return undefined;
-    return { ...(country ? { country } : {}), ...(region ? { region } : {}) };
+    const region = normalizeGeoRegion(request.headers.get('x-vercel-ip-country-region'));
+    return { country, ...(region ? { region } : {}) };
 }
 function normalizeGeoCountry(value) {
     const clean = (value ?? '').trim();
@@ -304,11 +304,16 @@ function normalizeGeoRegion(value) {
     const clean = (value ?? '').trim();
     return /^[a-zA-Z0-9]{1,3}$/.test(clean) ? clean.toUpperCase() : '';
 }
-// normalizeDeviceClass floors any client value onto the closed enum —
-// never a free-form echo (the value joins a rollup primary key, D-PR-22).
-function normalizeDeviceClass(value) {
-    const clean = typeof value === 'string' ? value.trim().toLowerCase() : '';
-    return DEVICE_CLASSES.has(clean) ? clean : 'unknown';
+// collectDeviceClass classifies the request through the shared edge/SDK
+// classifier. Capture has no "absent" bucket — the class joins a rollup key —
+// so a request with nothing to classify floors to the enum's 'unknown', while
+// request-scope targeting keeps absence distinct.
+function collectDeviceClass(request) {
+    const headers = {};
+    request.headers.forEach((value, name) => {
+        headers[name.toLowerCase()] = value;
+    });
+    return deviceClassFromHeaders(headers) || 'unknown';
 }
 function normalizeEventName(value) {
     const name = value.trim().toLowerCase();

package/dist/next/personalization-host.js

@@ -202,18 +202,17 @@ function toPersonalizationRequestContext(request) {
         (query[key] ||= []).push(value);
     });
     const headers = Object.fromEntries(request.headers.entries());
+    const geo = Object.fromEntries(Object.entries({
+        country: headers['x-vercel-ip-country'] || '',
+        region: headers['x-vercel-ip-country-region'] || '',
+        city: headers['x-vercel-ip-city'] || '',
+    }).filter(([, value]) => value !== ''));
     return {
         path: url.pathname,
         query,
         headers,
         cookies: Object.fromEntries(cookies.entries()),
-        signals: {
-            geo: {
-                country: headers['x-vercel-ip-country'] || '',
-                region: headers['x-vercel-ip-country-region'] || '',
-                city: headers['x-vercel-ip-city'] || '',
-            },
-        },
+        ...(Object.keys(geo).length > 0 ? { signals: { geo } } : {}),
     };
 }
 export async function verifyClaims(value, keys, now) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.52-rc.13",
+  "version": "0.1.52-rc.15",
   "repository": {
     "type": "git",
     "url": "https://github.com/gradial/bare-metal-go.git",
@@ -146,11 +146,11 @@
     "zod": "^4.0.0"
   },
   "optionalDependencies": {
-    "@gradial/aci-cli-darwin-arm64": "0.1.52-rc.13",
-    "@gradial/aci-cli-darwin-x64": "0.1.52-rc.13",
-    "@gradial/aci-cli-linux-arm64": "0.1.52-rc.13",
-    "@gradial/aci-cli-linux-x64": "0.1.52-rc.13",
-    "@gradial/aci-cli-win32-arm64": "0.1.52-rc.13",
-    "@gradial/aci-cli-win32-x64": "0.1.52-rc.13"
+    "@gradial/aci-cli-darwin-arm64": "0.1.52-rc.15",
+    "@gradial/aci-cli-darwin-x64": "0.1.52-rc.15",
+    "@gradial/aci-cli-linux-arm64": "0.1.52-rc.15",
+    "@gradial/aci-cli-linux-x64": "0.1.52-rc.15",
+    "@gradial/aci-cli-win32-arm64": "0.1.52-rc.15",
+    "@gradial/aci-cli-win32-x64": "0.1.52-rc.15"
   }
 }

package/templates/nextjs/template/package.json.tmpl

@@ -21,7 +21,7 @@
   "dependencies": {
     "@c15t/nextjs": "^2.2.1",
     "@gradial/aci": "{{aciVersion}}",
-    "next": "^15.1.6",
+    "next": "15.5.24",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
@@ -32,7 +32,7 @@
     "@eslint/compat": "^1.2.0",
     "@eslint/eslintrc": "^3.2.0",
     "eslint": "^9.18.0",
-    "eslint-config-next": "^15.1.6",
+    "eslint-config-next": "15.5.24",
     "eslint-plugin-import": "^2.29.1",
     "tailwindcss": "^4.2.4",
     "@tailwindcss/postcss": "^4.2.4",