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

package/dist/edge/expression-capabilities.v1.d.ts

@@ -0,0 +1,106 @@
+export declare const expressionCapabilities: {
+    readonly schemaVersion: 1;
+    readonly contract: "personalization-expression";
+    readonly maxConditions: 64;
+    readonly maxDepth: 5;
+    readonly maxInValues: 32;
+    readonly grammars: {
+        readonly number: "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?([eE][+-]?[0-9]+)?$";
+        readonly timestamp: "^(\\d{4})-(\\d{2})-(\\d{2})T(\\d{2}):(\\d{2}):(\\d{2})(\\.\\d{1,9})?(Z|[+-]\\d{2}:\\d{2})$";
+    };
+    readonly operators: readonly [{
+        readonly name: "equals";
+        readonly operand: "scalar";
+        readonly compact: "eq";
+    }, {
+        readonly name: "contains";
+        readonly operand: "scalar";
+        readonly compact: "ct";
+    }, {
+        readonly name: "startsWith";
+        readonly operand: "scalar";
+        readonly compact: "sw";
+    }, {
+        readonly name: "exists";
+        readonly operand: "optionalBoolean";
+        readonly compact: "ex";
+    }, {
+        readonly name: "greaterThan";
+        readonly operand: "number";
+        readonly compact: "gt";
+    }, {
+        readonly name: "greaterThanOrEqual";
+        readonly operand: "number";
+        readonly compact: "ge";
+    }, {
+        readonly name: "lessThan";
+        readonly operand: "number";
+        readonly compact: "lt";
+    }, {
+        readonly name: "lessThanOrEqual";
+        readonly operand: "number";
+        readonly compact: "le";
+    }, {
+        readonly name: "before";
+        readonly operand: "timestamp";
+        readonly compact: "bf";
+    }, {
+        readonly name: "after";
+        readonly operand: "timestamp";
+        readonly compact: "af";
+    }, {
+        readonly name: "between";
+        readonly operand: "range";
+        readonly compact: "bt";
+        readonly range: {
+            readonly memberTypes: readonly ["number", "timestamp"];
+            readonly homogeneous: true;
+            readonly inclusive: true;
+        };
+    }, {
+        readonly name: "in";
+        readonly operand: "scalarList";
+        readonly compact: "in";
+        readonly maxValues: 32;
+    }];
+    readonly scopes: readonly [{
+        readonly scope: "request";
+        readonly allowsEmpty: false;
+        readonly fields: readonly [{
+            readonly field: "referrer";
+        }, {
+            readonly field: "query.*";
+        }, {
+            readonly field: "header.*";
+        }, {
+            readonly field: "cookie.*";
+        }, {
+            readonly field: "geo.*";
+        }, {
+            readonly field: "utm.*";
+        }, {
+            readonly field: "device.class";
+            readonly operators: readonly ["equals", "in", "exists"];
+            readonly values: readonly ["desktop", "mobile", "tablet", "unknown"];
+        }, {
+            readonly field: "time.now";
+            readonly operators: readonly ["before", "after", "between", "exists"];
+            readonly instant: true;
+        }, {
+            readonly field: "audience.memberships";
+            readonly operators: readonly ["equals", "in", "exists"];
+        }];
+    }, {
+        readonly scope: "event";
+        readonly allowsEmpty: true;
+        readonly fields: readonly [{
+            readonly field: "referrer";
+        }, {
+            readonly field: "page.path";
+        }, {
+            readonly field: "properties.*";
+        }, {
+            readonly field: "utm.*";
+        }];
+    }];
+};

package/dist/edge/expression-capabilities.v1.js

@@ -0,0 +1,165 @@
+// GENERATED by scripts/generate-expression-capabilities.go — DO NOT EDIT.
+// Regenerate: make expression-capabilities
+//
+// The published capability discovery schema for the personalization
+// expression contract (ADR 0038), generated from the Go vocabulary tables
+// and drift-gated in CI against the canonical JSON artifact at
+// internal/domain/personalization/expression/schema/.
+export const expressionCapabilities = {
+    "schemaVersion": 1,
+    "contract": "personalization-expression",
+    "maxConditions": 64,
+    "maxDepth": 5,
+    "maxInValues": 32,
+    "grammars": {
+        "number": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?([eE][+-]?[0-9]+)?$",
+        "timestamp": "^(\\d{4})-(\\d{2})-(\\d{2})T(\\d{2}):(\\d{2}):(\\d{2})(\\.\\d{1,9})?(Z|[+-]\\d{2}:\\d{2})$"
+    },
+    "operators": [
+        {
+            "name": "equals",
+            "operand": "scalar",
+            "compact": "eq"
+        },
+        {
+            "name": "contains",
+            "operand": "scalar",
+            "compact": "ct"
+        },
+        {
+            "name": "startsWith",
+            "operand": "scalar",
+            "compact": "sw"
+        },
+        {
+            "name": "exists",
+            "operand": "optionalBoolean",
+            "compact": "ex"
+        },
+        {
+            "name": "greaterThan",
+            "operand": "number",
+            "compact": "gt"
+        },
+        {
+            "name": "greaterThanOrEqual",
+            "operand": "number",
+            "compact": "ge"
+        },
+        {
+            "name": "lessThan",
+            "operand": "number",
+            "compact": "lt"
+        },
+        {
+            "name": "lessThanOrEqual",
+            "operand": "number",
+            "compact": "le"
+        },
+        {
+            "name": "before",
+            "operand": "timestamp",
+            "compact": "bf"
+        },
+        {
+            "name": "after",
+            "operand": "timestamp",
+            "compact": "af"
+        },
+        {
+            "name": "between",
+            "operand": "range",
+            "compact": "bt",
+            "range": {
+                "memberTypes": [
+                    "number",
+                    "timestamp"
+                ],
+                "homogeneous": true,
+                "inclusive": true
+            }
+        },
+        {
+            "name": "in",
+            "operand": "scalarList",
+            "compact": "in",
+            "maxValues": 32
+        }
+    ],
+    "scopes": [
+        {
+            "scope": "request",
+            "allowsEmpty": false,
+            "fields": [
+                {
+                    "field": "referrer"
+                },
+                {
+                    "field": "query.*"
+                },
+                {
+                    "field": "header.*"
+                },
+                {
+                    "field": "cookie.*"
+                },
+                {
+                    "field": "geo.*"
+                },
+                {
+                    "field": "utm.*"
+                },
+                {
+                    "field": "device.class",
+                    "operators": [
+                        "equals",
+                        "in",
+                        "exists"
+                    ],
+                    "values": [
+                        "desktop",
+                        "mobile",
+                        "tablet",
+                        "unknown"
+                    ]
+                },
+                {
+                    "field": "time.now",
+                    "operators": [
+                        "before",
+                        "after",
+                        "between",
+                        "exists"
+                    ],
+                    "instant": true
+                },
+                {
+                    "field": "audience.memberships",
+                    "operators": [
+                        "equals",
+                        "in",
+                        "exists"
+                    ]
+                }
+            ]
+        },
+        {
+            "scope": "event",
+            "allowsEmpty": true,
+            "fields": [
+                {
+                    "field": "referrer"
+                },
+                {
+                    "field": "page.path"
+                },
+                {
+                    "field": "properties.*"
+                },
+                {
+                    "field": "utm.*"
+                }
+            ]
+        }
+    ]
+};

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

@@ -0,0 +1,24 @@
+export interface ObjectReader {
+    readObject(path: string): Promise<Uint8Array>;
+}
+export interface ComposeObjectRef {
+    path: string;
+    digest: string;
+}
+export interface ComposeSlot {
+    name: string;
+    required: boolean;
+    placeholder: string;
+    parts: ComposeObjectRef[];
+}
+export interface ComposeEnvelope {
+    schema: 'gradial.compose-envelope.v1';
+    algorithm: 'aci-html-compose-v1';
+    shell: ComposeObjectRef;
+    slots: ComposeSlot[];
+}
+export declare function composeEnvelope(reader: ObjectReader, envelopePath: string, envelopeDigest: string): Promise<{
+    html: string;
+    contentType: string;
+}>;
+export declare function validateEnvelope(envelope: unknown): ComposeEnvelope;

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

@@ -0,0 +1,89 @@
+const decoder = new TextDecoder('utf-8', { fatal: true });
+export async function composeEnvelope(reader, envelopePath, envelopeDigest) {
+    const envelopeBytes = await reader.readObject(envelopePath);
+    await requireDigest(envelopeBytes, envelopeDigest, 'compose envelope');
+    let parsed;
+    try {
+        parsed = JSON.parse(decoder.decode(envelopeBytes));
+    }
+    catch {
+        throw new Error('compose envelope is malformed');
+    }
+    const envelope = validateEnvelope(parsed);
+    const shellBytes = await reader.readObject(envelope.shell.path);
+    await requireDigest(shellBytes, envelope.shell.digest, 'compose shell');
+    let html = decoder.decode(shellBytes);
+    for (const slot of envelope.slots) {
+        if (occurrences(html, slot.placeholder) !== 1) {
+            throw new Error(`compose slot ${JSON.stringify(slot.name)} placeholder must occur exactly once`);
+        }
+        if (slot.required && slot.parts.length === 0) {
+            throw new Error(`compose slot ${JSON.stringify(slot.name)} is required`);
+        }
+        const parts = [];
+        for (const part of slot.parts) {
+            const bytes = await reader.readObject(part.path);
+            await requireDigest(bytes, part.digest, `compose slot ${slot.name}`);
+            parts.push(decoder.decode(bytes));
+        }
+        html = html.replace(slot.placeholder, parts.join(''));
+    }
+    if (html.includes('<!--ACI_SLOT:')) {
+        throw new Error('compose shell has unresolved slots');
+    }
+    return { html, contentType: 'text/html; charset=utf-8' };
+}
+export function validateEnvelope(envelope) {
+    if (!envelope || typeof envelope !== 'object') {
+        throw new Error('compose envelope is malformed');
+    }
+    const obj = envelope;
+    if (obj.schema !== 'gradial.compose-envelope.v1'
+        || obj.algorithm !== 'aci-html-compose-v1'
+        || !Array.isArray(obj.slots)) {
+        throw new Error('compose envelope is malformed');
+    }
+    const env = envelope;
+    validateRef(env.shell);
+    const names = new Set();
+    for (const slot of env.slots) {
+        if (!slot || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(slot.name) || names.has(slot.name)) {
+            throw new Error('compose slot is malformed');
+        }
+        names.add(slot.name);
+        if (slot.placeholder !== `<!--ACI_SLOT:${slot.name}-->` || !Array.isArray(slot.parts)) {
+            throw new Error(`compose slot ${JSON.stringify(slot.name)} is malformed`);
+        }
+        for (const part of slot.parts)
+            validateRef(part);
+    }
+    return env;
+}
+function validateRef(ref) {
+    const path = String(ref?.path || '');
+    if (!path || path.includes('\\') || path.split('/').some((part) => !part || part === '.' || part === '..')) {
+        throw new Error('compose object path is invalid');
+    }
+    if (!/^[0-9a-f]{64}$/.test(String(ref.digest || '').toLowerCase())) {
+        throw new Error('compose object digest is invalid');
+    }
+}
+async function requireDigest(bytes, want, label) {
+    const ab = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(ab).set(bytes);
+    const actual = Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', ab)), (byte) => byte.toString(16).padStart(2, '0')).join('');
+    if (actual !== want.toLowerCase())
+        throw new Error(`${label} digest mismatch`);
+}
+function occurrences(value, needle) {
+    let count = 0;
+    let offset = 0;
+    while (true) {
+        offset = value.indexOf(needle, offset);
+        if (offset < 0)
+            break;
+        count += 1;
+        offset += needle.length;
+    }
+    return count;
+}

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

@@ -8,7 +8,7 @@
 // - 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.
+// internal/domain/audience/runtime/collect.ts imports from here as well.
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 // ── Constants ──

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

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

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

@@ -3,4 +3,6 @@
 export * from './types.js';
 export * from './personalization-core.js';
 export * from './identity.js';
+export * from './mimic_token.js';
+export * from './compose.js';
 export { resolvePersonalizationRequest, } from './resolve.js';

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

@@ -0,0 +1,13 @@
+export interface MimicClaims {
+    scope: string;
+    siteId: string;
+    aud?: string[];
+    seg?: string[];
+    sub?: string;
+    jti?: string;
+    iat: string;
+    expiresAt: string;
+}
+export declare const MIMIC_MAX_MEMBERSHIPS = 32;
+export declare const MIMIC_MAX_TOKEN_BYTES = 2048;
+export declare function validateMimicToken(token: string, signingKey: string, siteId: string): Promise<MimicClaims | null>;

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

@@ -0,0 +1,58 @@
+// Mimic token validation for the edge runtime (specs/features/audience-mimic).
+//
+// Same HS256 envelope and signing key as preview; the scope claim makes the
+// tokens non-interchangeable (D-6). This validator is the twin of
+// internal/domain/edge/routing/mimic.go, pinned by the shared vector file
+// (internal/domain/edge/routing/testdata/mimic_token_vectors.json).
+export const MIMIC_MAX_MEMBERSHIPS = 32;
+export const MIMIC_MAX_TOKEN_BYTES = 2048;
+export async function validateMimicToken(token, signingKey, siteId) {
+    if (!token || token.length > MIMIC_MAX_TOKEN_BYTES || !signingKey || !siteId)
+        return null;
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return null;
+    const signingInput = parts[0] + '.' + parts[1];
+    let signatureBytes;
+    try {
+        signatureBytes = base64URLDecode(parts[2]);
+    }
+    catch {
+        return null;
+    }
+    const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(signingKey), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+    const valid = await crypto.subtle.verify('HMAC', key, signatureBytes, new TextEncoder().encode(signingInput));
+    if (!valid)
+        return null;
+    let claims;
+    try {
+        claims = JSON.parse(new TextDecoder().decode(base64URLDecode(parts[1])));
+    }
+    catch {
+        return null;
+    }
+    if (claims.scope !== 'mimic')
+        return null;
+    if (typeof claims.siteId !== 'string' || claims.siteId !== siteId)
+        return null;
+    const aud = Array.isArray(claims.aud) ? claims.aud : [];
+    const seg = Array.isArray(claims.seg) ? claims.seg : [];
+    if (aud.length + seg.length === 0)
+        return null;
+    if (aud.length > MIMIC_MAX_MEMBERSHIPS || seg.length > MIMIC_MAX_MEMBERSHIPS)
+        return null;
+    const expiresAt = new Date(claims.expiresAt);
+    if (Number.isNaN(expiresAt.getTime()) || expiresAt.getTime() <= Date.now())
+        return null;
+    return { ...claims, aud, seg };
+}
+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;
+}

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

@@ -1,6 +1,51 @@
-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;
+import type { PersonalizationRequestContext, PersonalizationClaims, PersonalizationRoute, PersonalizationExperiment, PersonalizationIdentity, PersonalizationDecision, ClassificationData, Classification, EdgeRouteEntry } from './types.js';
 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 {
+    path: string;
+    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;
+export declare const EXPRESSION_OPERATORS: string[];
+export declare const EXPRESSION_NUMBER_GRAMMAR: RegExp;
+export declare const EXPRESSION_TIMESTAMP_GRAMMAR: RegExp;
 /**
  * Phase 1: Classify the visitor against all release-level rules.
  *
@@ -8,17 +53,36 @@ export declare function resolvePersonalizationDecision(request: PersonalizationR
  * @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 declare function classify(ctx: PersonalizationRequestContext, data: ClassificationData, identity?: PersonalizationIdentity): Classification;
+export declare function classify(ctx: PersonalizationRequestContext, data: ClassificationData, identity?: PersonalizationIdentity, claims?: PersonalizationClaims | null): 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.
+ * 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 declare function decide(record: EdgeRouteEntry, classification: Classification, ctx: PersonalizationRequestContext): PersonalizationDecision;
+export declare function decide(record: EdgeRouteEntry, classification: Classification, ctx: PersonalizationRequestContext, claims?: PersonalizationClaims | null): 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;