@gradial/aci 0.1.48 → 0.1.51-ssr.2

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

@@ -0,0 +1,214 @@
+// Identity, consent, and cookie helpers for edge decisioning.
+//
+// This is the single source of truth for:
+// - Cookie parsing
+// - Consent signal extraction (GPC/DNT + portable consent envelope)
+// - Identity cookie verification and minting (aci_id)
+// - Claims cookie verification (aci_claims)
+// - Cookie mutation helpers
+//
+// Shared by every static edge adapter; this logic has no SDK host wrapper.
+// internal/domain/audience/runtime/identity.ts imports from here as well.
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+// ── Constants ──
+export const DEFAULT_IDENTITY_TTL_SECONDS = 90 * 24 * 60 * 60;
+const MAX_CONSENT_ENVELOPE_BYTES = 2048;
+const MAX_CONSENT_PURPOSES = 32;
+const MAX_CONSENT_PURPOSE_BYTES = 128;
+const MAX_CONSENT_SOURCE_BYTES = 512;
+const MAX_CONSENT_POLICY_VERSION = 2147483647;
+const RFC3339 = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})$/;
+const CONSENT_EDGE_WHITESPACE = /^[\t\n\v\f\r ]+|[\t\n\v\f\r ]+$/g;
+const LEGACY_GRANTS = new Set([
+    'true',
+    'all',
+    'granted',
+    'yes',
+    'personalization',
+    'personalized',
+]);
+// ── Cookie parsing ──
+export function parseCookieHeader(value) {
+    const cookies = new Map();
+    for (const part of (value || '').split(';')) {
+        const separator = part.indexOf('=');
+        if (separator < 0)
+            continue;
+        const name = part.slice(0, separator).trim();
+        if (name)
+            cookies.set(name, part.slice(separator + 1).trim());
+    }
+    return cookies;
+}
+// ── Consent ──
+export function consentSignals(request, cookies) {
+    const privacyOverride = (request.headers.get('x-gradial-privacy-override') || '').trim().toLowerCase();
+    const privacyDenied = request.headers.get('sec-gpc')?.trim() === '1'
+        || request.headers.get('dnt')?.trim() === '1'
+        || ['deny', 'opt-out', 'off'].includes(privacyOverride);
+    const headerConsent = request.headers.get('x-aci-consent');
+    const hasHeaderConsent = trimConsentWhitespace(headerConsent || '') !== '';
+    const raw = hasHeaderConsent ? headerConsent : cookies.get('aci_consent') || '';
+    const snapshot = parseConsent(raw, !hasHeaderConsent);
+    return {
+        hasConsent: snapshot !== null,
+        consentInvalid: trimConsentWhitespace(raw) !== '' && snapshot === null,
+        snapshot,
+        allowsIdentityTier: !privacyDenied && Boolean(snapshot?.purposes.some((purpose) => trimConsentWhitespace(purpose).toLowerCase() === 'personalization')),
+        privacyDenied,
+    };
+}
+export function parseConsent(raw, decodeCookieValue = true) {
+    let decoded = trimConsentWhitespace(raw);
+    if (!decoded)
+        return null;
+    if (decodeCookieValue) {
+        try {
+            decoded = decodeURIComponent(decoded);
+        }
+        catch {
+            // Evaluate the original cookie value.
+        }
+    }
+    decoded = trimConsentWhitespace(decoded);
+    if (!decoded || encoder.encode(decoded).byteLength > MAX_CONSENT_ENVELOPE_BYTES)
+        return null;
+    if (LEGACY_GRANTS.has(decoded.toLowerCase())) {
+        return { version: 0, purposes: ['personalization'], grantedAt: '' };
+    }
+    try {
+        const parsed = JSON.parse(decoded);
+        const grantedAt = parsed.t === undefined || parsed.t === null ? '' : parsed.t;
+        if (!Number.isInteger(parsed.v)
+            || Number(parsed.v) < 0
+            || Number(parsed.v) > MAX_CONSENT_POLICY_VERSION
+            || !Array.isArray(parsed.p)
+            || parsed.p.length > MAX_CONSENT_PURPOSES
+            || !parsed.p.every((item) => typeof item === 'string')
+            || parsed.p.some((item) => encoder.encode(item).byteLength > MAX_CONSENT_PURPOSE_BYTES)
+            || (grantedAt !== '' && (typeof grantedAt !== 'string' || !isRFC3339(grantedAt)))
+            || parsed.t === ''
+            || (parsed.src !== undefined && parsed.src !== null && typeof parsed.src !== 'string')
+            || (typeof parsed.src === 'string' && encoder.encode(parsed.src).byteLength > MAX_CONSENT_SOURCE_BYTES))
+            return null;
+        return {
+            version: Number(parsed.v),
+            purposes: parsed.p,
+            grantedAt: grantedAt,
+            ...(typeof parsed.src === 'string' ? { source: parsed.src } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function trimConsentWhitespace(value) {
+    return value.replace(CONSENT_EDGE_WHITESPACE, '');
+}
+// ── Identity cookie (aci_id) ──
+export async function verifyIdentityCookie(value, keys) {
+    const parts = value.trim().split('.');
+    if (parts.length !== 3 || parts.some((part) => part === ''))
+        return null;
+    const [rawID, kid, signature] = parts;
+    const key = [keys.current, keys.previous].find((candidate) => candidate?.kid === kid);
+    if (!key)
+        return null;
+    return await verifyHMAC(`${rawID}.${kid}`, signature, key.secret) ? rawID : null;
+}
+export async function signIdentity(rawID, key) {
+    const signature = await hmacSHA256(`${rawID}.${key.kid}`, key.secret);
+    return `${rawID}.${key.kid}.${signature}`;
+}
+export function randomIdentity(random) {
+    const bytes = random ? random(16) : crypto.getRandomValues(new Uint8Array(16));
+    return base64URLEncode(bytes);
+}
+export async function identityHashHex(namespace, value) {
+    const digest = await crypto.subtle.digest('SHA-256', encoder.encode(`${namespace.trim().toLowerCase()}\x00${value.trim()}`));
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+export async function sha256Hex(value) {
+    const digest = await crypto.subtle.digest('SHA-256', encoder.encode(value));
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+// ── Claims cookie (aci_claims) ──
+export async function verifyClaims(value, keys, now) {
+    const parts = value.trim().split('.');
+    if (parts.length !== 4 || parts[0] !== 'v1')
+        return null;
+    const [, kid, body, signature] = parts;
+    const secret = keys[kid];
+    if (!secret || !await verifyHMAC(`v1.${kid}.${body}`, signature, secret))
+        return null;
+    try {
+        const payload = JSON.parse(decoder.decode(base64URLDecode(body)));
+        if (!Number.isFinite(payload.exp) || Number(payload.exp) <= Math.floor(now.getTime() / 1000))
+            return null;
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Cookie mutation helpers ──
+export function cookieMutation(name, value, maxAge, now, secure, httpOnly) {
+    return {
+        name,
+        value,
+        options: { path: '/', httpOnly, secure, sameSite: 'lax', maxAge, expires: new Date(now.getTime() + maxAge * 1000) },
+    };
+}
+export function expireCookie(name, secure) {
+    return { name, value: '', options: { path: '/', httpOnly: true, secure, sameSite: 'lax', maxAge: 0, expires: new Date(0) } };
+}
+// ── Internal crypto helpers ──
+async function verifyHMAC(value, signature, secret) {
+    try {
+        const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+        return await crypto.subtle.verify('HMAC', key, base64URLDecode(signature), encoder.encode(value));
+    }
+    catch {
+        return false;
+    }
+}
+async function hmacSHA256(value, secret) {
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return base64URLEncode(new Uint8Array(await crypto.subtle.sign('HMAC', key, encoder.encode(value))));
+}
+function base64URLEncode(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function base64URLDecode(value) {
+    const padded = value.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - value.length % 4) % 4);
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+function isRFC3339(value) {
+    const match = RFC3339.exec(value);
+    if (!match || Number.isNaN(Date.parse(value)))
+        return false;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    const second = Number(match[6]);
+    if (month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month)
+        || hour > 23 || minute > 59 || second > 59)
+        return false;
+    const zone = match[8];
+    return zone === 'Z' || (Number(zone.slice(1, 3)) <= 23 && Number(zone.slice(4, 6)) <= 59);
+}
+function daysInMonth(year, month) {
+    if (month === 2)
+        return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0) ? 29 : 28;
+    return [4, 6, 9, 11].includes(month) ? 30 : 31;
+}

package/dist/internal/domain/edge/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './personalization-core.js';
+export * from './identity.js';
+export { resolvePersonalizationRequest, } from './resolve.js';

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

@@ -0,0 +1,6 @@
+// Barrel export for internal/domain/edge — shared edge-decisioning semantics.
+// Host adapters import from here; the SDK re-exports for backward compat.
+export * from './types.js';
+export * from './personalization-core.js';
+export * from './identity.js';
+export { resolvePersonalizationRequest, } from './resolve.js';

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

@@ -0,0 +1,24 @@
+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;
+/**
+ * Phase 1: Classify the visitor against all release-level rules.
+ *
+ * @param ctx     The request context (cookies, headers, geo, query)
+ * @param data    Release-level classification data (audiences, segments, experiments)
+ * @param identity Visitor identity (for experiment bucketing). Pass undefined
+ *                 if no identity or privacy denied.
+ * @returns Classification — matched audiences, segments, and experiment arm assignments
+ */
+export declare function classify(ctx: PersonalizationRequestContext, data: ClassificationData, identity?: PersonalizationIdentity): Classification;
+/**
+ * Phase 2: Decide the winning variant for a specific route.
+ *
+ * Uses the classification from Phase 1 for cheap set-membership lookups.
+ * No rule evaluation — just set membership and priority comparison.
+ *
+ * @param record        The route entry (path, dispatch, variants)
+ * @param classification The visitor's classification from Phase 1
+ * @returns The decision — winning variant + experiment assignment, or nulls
+ */
+export declare function decide(record: EdgeRouteEntry, classification: Classification, ctx: PersonalizationRequestContext): PersonalizationDecision;

package/dist/{edge → internal/domain/edge}/personalization-core.js

@@ -1,6 +1,13 @@
-// Runtime-neutral personalization selection. Vercel imports this module and
-// the CloudFront Terraform wrapper inlines the same source into its function.
-// Keep this file free of platform APIs and dependencies.
+// Runtime-neutral personalization selection. The backend owns this logic
+// and pushes compiled artifacts to each host (CloudFront Function, Vercel
+// middleware, Cloudflare Worker). Keep this file free of platform APIs.
+//
+// This is the pure decision algorithm — no I/O, no cookies, no identity
+// minting. The caller resolves identity and claims, then calls this.
+import { variantValuesFromKey } from './record/codec.js';
+// Build-time constant. The CloudFront Functions bundle replaces this with
+// true and uses the runtime's built-in crypto module; other host bundles
+// replace it with false and retain the portable implementation.
 export function selectPersonalizationVariant(request, route, claims, experiments, identity) {
     return resolvePersonalizationDecision(request, route, claims, experiments, identity).variant;
 }
@@ -18,9 +25,11 @@ export function resolvePersonalizationDecision(request, route, claims, experimen
         for (let index = 0; index < candidates.length; index++) {
             const item = candidates[index];
             const assignment = assignExperiment(item, identity);
-            const candidate = assignment && route.variants[assignment.variantKey];
+            const candidate = assignment ? route.variants[assignment.variantKey] : undefined;
             if (!candidate)
                 continue;
+            if (assignment && !candidate.variantKey)
+                candidate.variantKey = assignment.variantKey;
             if (!variant || betterVariant(candidate.priority || 0, candidate.variantKey, variant.priority || 0, variant.variantKey)) {
                 variant = candidate;
                 experiment = assignment;
@@ -36,6 +45,8 @@ function selectRuleVariant(request, route, claims, experiments) {
     const matches = [];
     for (const key in route.variants) {
         const variant = route.variants[key];
+        if (!variant.variantKey)
+            variant.variantKey = key;
         const values = variant.variantValues || variantValuesFromKey(key);
         const experimentID = String(values.experiment || '').trim();
         if (experimentID && (!experiments || !experiments[experimentID]
@@ -53,19 +64,6 @@ function selectRuleVariant(request, route, claims, experiments) {
         || String(left.variantKey || '').localeCompare(String(right.variantKey || '')));
     return matches[0] || null;
 }
-// CloudFront KVS values are capped at 1 KiB. The variant map key is the
-// canonical encoding of its dimensions, so compact route records omit the
-// duplicated variantValues object and recover it at the edge.
-function variantValuesFromKey(key) {
-    const values = {};
-    const parts = String(key || '').replace(/&/g, ';').split(';');
-    for (let index = 0; index < parts.length; index++) {
-        const separator = parts[index].indexOf('=');
-        if (separator > 0)
-            values[parts[index].slice(0, separator)] = parts[index].slice(separator + 1);
-    }
-    return values;
-}
 function routeHasExperiment(route, experimentID) {
     for (const key in route.variants || {}) {
         const values = route.variants[key].variantValues || variantValuesFromKey(key);
@@ -87,9 +85,9 @@ function assignExperiment(experiment, identity) {
     const arms = experiment.arms || [];
     for (let index = 0; index < arms.length; index++) {
         const arm = arms[index];
-        if ((arm.allocationBasisPoints || 0) <= 0)
+        if ((arm.allocationBasisPoints ?? 0) <= 0)
             continue;
-        cumulative += arm.allocationBasisPoints;
+        cumulative += arm.allocationBasisPoints ?? 0;
         if (bucket < cumulative) {
             return {
                 experimentId: experiment.id,
@@ -130,55 +128,58 @@ function requestDimensionsMatch(request, values) {
     return true;
 }
 function evaluateRule(request, rule) {
-    const all = rule.all || [];
-    const any = rule.any || [];
+    const all = (rule.all || []);
+    const any = (rule.any || []);
     if (all.length + any.length === 0)
         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, condition.field);
+    const values = signalValues(request, String(condition.field || ''));
     if (condition.operator === 'exists')
         return values.length > 0;
-    if (values.length === 0 || !['string', 'number', 'boolean'].includes(typeof condition.value))
+    if (values.length === 0 || typeof condition.value !== 'string' && typeof condition.value !== 'number' && typeof condition.value !== 'boolean')
         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;
-        }
-    });
+    const e = String(condition.value);
+    if (condition.operator === 'equals')
+        return values.some(v => v === e);
+    if (condition.operator === 'contains')
+        return values.some(v => v.includes(e));
+    if (condition.operator === 'startsWith')
+        return values.some(v => v.startsWith(e));
+    return false;
 }
 function signalValues(request, field) {
-    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] : [];
+    const d = field.indexOf('.');
+    if (d < 0)
+        return field === 'referrer' ? [request.headers.referer || request.headers.referrer].filter(Boolean) : [];
+    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] || [];
+    if (p === 'header') {
+        const v = request.headers[k.toLowerCase()];
+        return v ? [v] : [];
     }
-    if (field === 'referrer') {
-        const value = request.headers.referer || request.headers.referrer;
-        return value ? [value] : [];
+    if (p === 'cookie') {
+        const v = request.cookies[k];
+        return v ? [v] : [];
+    }
+    if (p === 'geo') {
+        const g = request.signals && request.signals.geo;
+        const v = g && g[k.toLowerCase()];
+        return v ? [v] : [];
     }
     return [];
 }
-// SHA-256 mirrors experiment.assignment.go: the first eight digest bytes are
-// interpreted big-endian and reduced modulo 10,000 basis points.
-// CLOUDFRONT_STRIP_START — the build script removes this block for CloudFront
-// Functions (experiment bucketing moves to the hosting Lambda to stay under
-// the 10 KiB function size limit).
-function sha256Bucket(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
+// implementation runtime-neutral: this module is bundled into browser and
+// Worker targets as well as exercised by the Go-facing edge code.
+const sha256Bucket = portableSHA256Bucket;
+function portableSHA256Bucket(value) {
     const bytes = utf8(value);
     const words = new Uint32Array(64);
     const bitLength = bytes.length * 8;
@@ -186,10 +187,6 @@ function sha256Bucket(value) {
     const data = new Uint8Array(paddedLength);
     data.set(bytes);
     data[bytes.length] = 128;
-    // The message length is a 64-bit big-endian integer across the final
-    // eight bytes. The previous code wrote a single truncated byte into each
-    // word's most significant position, corrupting every digest (caught by
-    // the assignment parity vectors, spec experiment-variant-caching REQ-9).
     const bitsHigh = Math.floor(bitLength / 0x100000000);
     const bitsLow = bitLength >>> 0;
     data[paddedLength - 8] = (bitsHigh >>> 24) & 255;
@@ -238,12 +235,6 @@ function sha256Bucket(value) {
         g = (g + gg) >>> 0;
         h = (h + hh) >>> 0;
     }
-    // Reduce the 64-bit big-endian value modulo 10000 in 32-bit halves:
-    // (hi*2^32 + lo) % 10000 == ((hi%10000) * (2^32 % 10000) + lo%10000) % 10000,
-    // and 2^32 % 10000 = 7296. Multiplying hi by 2^32 directly exceeds
-    // Number.MAX_SAFE_INTEGER and rounds away the low bits — that float error
-    // made most JS buckets diverge from assignment.go (caught by the
-    // assignment parity vectors, spec experiment-variant-caching REQ-9).
     return (((a >>> 0) % 10000) * 7296 + ((b >>> 0) % 10000)) % 10000;
 }
 function rotr(value, amount) { return (value >>> amount) | (value << (32 - amount)); }
@@ -266,4 +257,114 @@ function utf8(value) {
     }
     return new Uint8Array(out);
 }
-// CLOUDFRONT_STRIP_END
+// ── Normalized two-phase model: classify → decide ─────────────────────
+//
+// Phase 1 (classify): evaluate all audience/segment rules page-agnostically
+// and assign experiment arms. Returns a Classification that is used by
+// Phase 2 for cheap set-membership lookups per route.
+//
+// Phase 2 (decide): for a given route record, check which variants match
+// the classification (set membership + priority). No rule evaluation —
+// just "is this audience in matchedAudiences?" and "is this experiment arm
+// the one we assigned?"
+//
+// The per-route record stays small: just variant keys (e.g.
+// "audience=trade") + priorities. Rules live in the classification data,
+// evaluated once per request.
+//
+/**
+ * Phase 1: Classify the visitor against all release-level rules.
+ *
+ * @param ctx     The request context (cookies, headers, geo, query)
+ * @param data    Release-level classification data (audiences, segments, experiments)
+ * @param identity Visitor identity (for experiment bucketing). Pass undefined
+ *                 if no identity or privacy denied.
+ * @returns Classification — matched audiences, segments, and experiment arm assignments
+ */
+export function classify(ctx, data, identity) {
+    // Evaluate audience rules
+    const matchedAudiences = [];
+    for (const key in data.audiences) {
+        const def = data.audiences[key];
+        if (def.rule && evaluateRule(ctx, def.rule)) {
+            matchedAudiences.push(key);
+        }
+    }
+    // Evaluate segment rules
+    const matchedSegments = [];
+    for (const key in data.segments) {
+        const def = data.segments[key];
+        if (def.rule && evaluateRule(ctx, def.rule)) {
+            matchedSegments.push(key);
+        }
+    }
+    // Assign experiment arms (only for identified visitors)
+    const experimentArms = {};
+    if (identity && identity.usable) {
+        for (const expId in data.experiments) {
+            const exp = data.experiments[expId];
+            if (exp.status !== 'running')
+                continue;
+            if (exp.kind !== 'ab' && exp.kind !== 'abn')
+                continue;
+            const assignment = assignExperiment(exp, identity);
+            if (assignment) {
+                experimentArms[expId] = assignment;
+            }
+        }
+    }
+    return { matchedAudiences, matchedSegments, experimentArms };
+}
+/**
+ * Phase 2: Decide the winning variant for a specific route.
+ *
+ * Uses the classification from Phase 1 for cheap set-membership lookups.
+ * No rule evaluation — just set membership and priority comparison.
+ *
+ * @param record        The route entry (path, dispatch, variants)
+ * @param classification The visitor's classification from Phase 1
+ * @returns The decision — winning variant + experiment assignment, or nulls
+ */
+export function decide(record, classification, ctx) {
+    if (!record.variants)
+        return { variant: null, experiment: null };
+    let bestVariant = null;
+    let bestExperiment = null;
+    for (const key in record.variants) {
+        const variant = record.variants[key];
+        if (!variant.variantKey)
+            variant.variantKey = key;
+        const values = variant.variantValues || variantValuesFromKey(key);
+        // Check if this variant references a paused experiment — skip if so
+        const experimentID = String(values.experiment || '').trim();
+        if (experimentID && !classification.experimentArms[experimentID])
+            continue;
+        let matched = false;
+        // Audience membership
+        if (values.audience && classification.matchedAudiences.includes(values.audience)) {
+            matched = true;
+        }
+        // Segment membership
+        if (!matched && values.segment && classification.matchedSegments.includes(values.segment)) {
+            matched = true;
+        }
+        // Experiment arm assignment
+        if (!matched && experimentID) {
+            const arm = classification.experimentArms[experimentID];
+            if (arm && arm.variantKey === variant.variantKey) {
+                matched = true;
+                bestExperiment = arm;
+            }
+        }
+        if (matched) {
+            if (!bestVariant || betterVariant(variant.priority || 0, variant.variantKey, bestVariant.priority || 0, bestVariant.variantKey)) {
+                bestVariant = variant;
+                // Only set experiment if this variant's experiment arm won
+                if (!experimentID || !classification.experimentArms[experimentID]) {
+                    bestExperiment = null;
+                }
+            }
+        }
+    }
+    return { variant: bestVariant, experiment: bestExperiment };
+}

package/dist/internal/domain/edge/record/codec.d.ts

@@ -0,0 +1,71 @@
+import type { EdgeRouteEntry, ClassificationData } from '../types.js';
+/**
+ * Unique sentinel object returned by expand functions on failure.
+ * Callers check `result === INVALID`. Never throws.
+ */
+export declare const INVALID: unique symbol;
+export type Invalid = typeof INVALID;
+interface CompactDispatch {
+    k: 's';
+    ap: string;
+}
+interface CompactCondition {
+    f: string;
+    o: string;
+    w?: unknown;
+}
+interface CompactRule {
+    a?: CompactCondition[];
+    n?: CompactCondition[];
+}
+interface CompactVariant {
+    pr?: number;
+    r?: CompactRule;
+    d?: CompactDispatch;
+    vk?: string;
+    vv?: Record<string, string>;
+}
+export interface CompactRouteRecord {
+    s?: number;
+    p: string;
+    d: CompactDispatch;
+    v?: Record<string, CompactVariant>;
+    x?: string[];
+}
+export declare function projectRouteRecord(entry: EdgeRouteEntry): CompactRouteRecord;
+export declare function expandRouteRecord(raw: unknown): EdgeRouteEntry | Invalid;
+export interface CompactClassificationData {
+    au?: Record<string, {
+        r?: CompactRule;
+    }>;
+    sg?: Record<string, {
+        r?: CompactRule;
+    }>;
+    x?: Record<string, CompactExperiment>;
+}
+interface CompactExperimentArm {
+    id: string;
+    ab?: number;
+    vk?: string;
+    ro?: string;
+}
+interface CompactExperiment {
+    id: string;
+    st?: string;
+    k?: string;
+    av?: string;
+    sl?: string;
+    pr?: number;
+    ar?: CompactExperimentArm[];
+    dn?: string;
+    pg?: string;
+    gl?: string[];
+}
+export declare function projectClassificationData(data: ClassificationData): CompactClassificationData;
+export declare function expandClassificationData(raw: unknown): ClassificationData | Invalid;
+export declare const MARKER = "{\"s\":1,\"e\":1}";
+export declare function isMarker(raw: string): boolean;
+export declare function canonicalSerialize(value: unknown): string;
+export declare function variantValuesFromKey(key: string): Record<string, string>;
+export declare function pathHash16(path: string): string;
+export {};