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

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

@@ -1,4 +1,4 @@
-// Compact JSON codec for edge-decisioning route records and classification data.
+// Compact JSON codec for edge-decisioning route records.
 //
 // project(): canonical → compact (short field names via alias table, omit defaults)
 // expand():  compact → canonical (reverse, never throws — returns INVALID sentinel on failure)
@@ -49,18 +49,6 @@ const OPERATOR_FROM_COMPACT = {
     gt: 'greaterThan', ge: 'greaterThanOrEqual', lt: 'lessThan', le: 'lessThanOrEqual',
     bf: 'before', af: 'after', bt: 'between', in: 'in',
 };
-const EXPERIMENT_STATUS_TO_COMPACT = {
-    running: 'r', paused: 'p', completed: 'd',
-};
-const EXPERIMENT_STATUS_FROM_COMPACT = {
-    r: 'running', p: 'paused', d: 'completed',
-};
-const EXPERIMENT_KIND_TO_COMPACT = {
-    ab: 'a', abn: 'n',
-};
-const EXPERIMENT_KIND_FROM_COMPACT = {
-    a: 'ab', n: 'abn',
-};
 // Compact type guard — reduces minified bytes vs repeated typeof+null+isArray checks
 function isObj(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
@@ -291,149 +279,6 @@ export function expandRouteRecord(raw) {
     }
     return entry;
 }
-export function projectClassificationData(data) {
-    const result = {};
-    if (data.audiences && Object.keys(data.audiences).length > 0) {
-        result.au = {};
-        for (const [key, def] of Object.entries(data.audiences)) {
-            const entry = {};
-            const rule = projectRule(def.rule);
-            if (rule)
-                entry.r = rule;
-            result.au[key] = entry;
-        }
-    }
-    if (data.segments && Object.keys(data.segments).length > 0) {
-        result.sg = {};
-        for (const [key, def] of Object.entries(data.segments)) {
-            const entry = {};
-            const rule = projectRule(def.rule);
-            if (rule)
-                entry.r = rule;
-            result.sg[key] = entry;
-        }
-    }
-    if (data.experiments && Object.keys(data.experiments).length > 0) {
-        result.x = {};
-        for (const [key, exp] of Object.entries(data.experiments))
-            result.x[key] = projectExperiment(exp);
-    }
-    return result;
-}
-function projectExperiment(exp) {
-    const result = { id: exp.id };
-    if (exp.status) {
-        const c = EXPERIMENT_STATUS_TO_COMPACT[exp.status];
-        if (c)
-            result.st = c;
-    }
-    if (exp.kind) {
-        const c = EXPERIMENT_KIND_TO_COMPACT[exp.kind];
-        if (c)
-            result.k = c;
-    }
-    if (exp.allocationVersion)
-        result.av = exp.allocationVersion;
-    if (exp.salt)
-        result.sl = exp.salt;
-    if (exp.priority)
-        result.pr = exp.priority;
-    if (exp.arms && exp.arms.length > 0) {
-        result.ar = exp.arms.map((arm) => {
-            const ca = { id: arm.id };
-            if (arm.allocationBasisPoints)
-                ca.ab = arm.allocationBasisPoints;
-            if (arm.variantKey)
-                ca.vk = arm.variantKey;
-            return ca;
-        });
-    }
-    return result;
-}
-export function expandClassificationData(raw) {
-    if (!isObj(raw))
-        return INVALID;
-    const obj = raw;
-    const data = { audiences: {}, segments: {}, experiments: {} };
-    if (obj.au !== undefined) {
-        if (!isObj(obj.au))
-            return INVALID;
-        for (const [key, defRaw] of Object.entries(obj.au)) {
-            if (!isObj(defRaw))
-                return INVALID;
-            const ruleResult = expandRule(defRaw.r);
-            if (ruleResult === INVALID)
-                return INVALID;
-            data.audiences[key] = { rule: ruleResult || { all: [] } };
-        }
-    }
-    if (obj.sg !== undefined) {
-        if (!isObj(obj.sg))
-            return INVALID;
-        for (const [key, defRaw] of Object.entries(obj.sg)) {
-            if (!isObj(defRaw))
-                return INVALID;
-            const ruleResult = expandRule(defRaw.r);
-            if (ruleResult === INVALID)
-                return INVALID;
-            data.segments[key] = { rule: ruleResult || { all: [] } };
-        }
-    }
-    if (obj.x !== undefined) {
-        if (!isObj(obj.x))
-            return INVALID;
-        for (const [key, expRaw] of Object.entries(obj.x)) {
-            const expResult = expandExperiment(expRaw);
-            if (expResult === INVALID)
-                return INVALID;
-            data.experiments[key] = expResult;
-        }
-    }
-    return data;
-}
-function expandExperiment(raw) {
-    if (!isObj(raw))
-        return INVALID;
-    const obj = raw;
-    const id = obj.id;
-    if (typeof id !== 'string')
-        return INVALID;
-    const exp = { id, status: 'running', kind: 'ab', arms: [] };
-    if (typeof obj.st === 'string') {
-        const expanded = EXPERIMENT_STATUS_FROM_COMPACT[obj.st];
-        if (!expanded)
-            return INVALID;
-        exp.status = expanded;
-    }
-    if (typeof obj.k === 'string') {
-        const expanded = EXPERIMENT_KIND_FROM_COMPACT[obj.k];
-        if (!expanded)
-            return INVALID;
-        exp.kind = expanded;
-    }
-    if (typeof obj.av === 'string')
-        exp.allocationVersion = obj.av;
-    if (typeof obj.sl === 'string')
-        exp.salt = obj.sl;
-    if (typeof obj.pr === 'number')
-        exp.priority = obj.pr;
-    if (Array.isArray(obj.ar)) {
-        exp.arms = [];
-        for (const armRaw of obj.ar) {
-            if (!isObj(armRaw))
-                return INVALID;
-            const armObj = armRaw;
-            if (typeof armObj.id !== 'string')
-                return INVALID;
-            exp.arms.push({
-                id: armObj.id,
-                allocationBasisPoints: typeof armObj.ab === 'number' ? armObj.ab : 0,
-                variantKey: typeof armObj.vk === 'string' ? armObj.vk : '',
-            });
-        }
-    }
-    return exp;
-}
 // ── Marker (tri-state: record | marker | absent) ─────────────────────
 export const MARKER = '{"s":1,"e":1}';
 export function isMarker(raw) {

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

@@ -1,66 +1,83 @@
 // resolvePersonalizationRequest — the edge decisioning entry point.
 //
-// Reads cookies for classification but never writes them (R25: consent-gated
-// identity model). Identity minting happens in the collect/consent endpoint,
-// not here. Public personalized responses may be private while providers cache
-// the selected immutable artifact by release and exact artifact path.
+// Reads cookies for classification but never writes them. It may issue a
+// first-party identity in memory when the host permits (ADR 0048); persisting
+// that identity is the host's job. Public personalized responses may be
+// private while providers cache the selected immutable artifact by release and
+// exact artifact path.
 import { resolvePersonalizationDecision, } from './personalization-core.js';
-import { consentSignals, verifyIdentityCookie, identityHashHex, verifyClaims, parseCookieHeader, } from './identity.js';
+import { consentSignals, verifyIdentityCookie, identityHashHex, randomIdentity, verifyClaims, parseCookieHeader, } from './identity.js';
 export async function resolvePersonalizationRequest(request, config) {
     const cookies = parseCookieHeader(request.headers.get('cookie'));
     const consent = consentSignals(request, cookies);
     const now = (config.now ?? (() => new Date()))();
-    // Consent-gated identity model (R25): artifact selection NEVER mints
-    // identity. It reads cookies for classification but never writes them.
-    // Identity (aci_id) is minted only after explicit consent — by the
-    // collect/consent endpoint, and by the hosting edge router / framework
-    // host on consented 200 HTML page responses (which then bypass shared
-    // caches). Unconsented content responses stay cookie-free and cacheable
-    // (no non-essential cookie before consent).
+    // Identity model (ADR 0016 as amended by ADR 0048): experiment bucketing is
+    // measurement, keyed by the first-party aci_id. A verified cookie (or the
+    // provider bootstrap's identity) is used as presented. With none usable, and
+    // only when the host's issuance rule permits it for this request, resolve
+    // issues a fresh identity so the request that issues it is also bucketed —
+    // an unverifiable cookie is replaced the same way. Persisting the issued
+    // identity is the host's decision (page responses only, never shared-cached).
+    // Claims and memberships stay gated on the personalization grant.
     //
-    // GPC/DNT deny fully: no read, no identity, no experiment bucketing.
+    // GPC/DNT deny fully: no read, no identity, no issuance, no bucketing.
     //
     // Mimic (specs/features/audience-mimic): a validated mimicClaims input
     // bypasses identity resolution entirely — the session reads no aci_id and
     // no aci_claims (D-2/D-7), so identityHash stays empty and the experiment
-    // tier is structurally skipped (D-5).
+    // tier is structurally skipped (D-5). An ARMS-bearing token is the D-17
+    // exception: the experiment tier runs in forced mode — the token's named
+    // arm replaces the dice for each experiment the request selects through
+    // the ordinary gate — and identity still never exists (I-17).
     const mimic = config.mimicClaims;
-    const rawIdentity = mimic || consent.privacyDenied
+    const verifiedVisitor = mimic || consent.privacyDenied ? undefined : config.verifiedVisitor;
+    const presentedIdentity = mimic || consent.privacyDenied
         ? null
-        : await verifyIdentityCookie(cookies.get('aci_id') || '', config.identityKeys);
+        : verifiedVisitor
+            ? verifiedVisitor.rawIdentity
+            : await verifyIdentityCookie(cookies.get('aci_id') || '', config.identityKeys);
+    const issuedIdentity = !presentedIdentity && !mimic && !consent.privacyDenied && config.issueIdentity
+        ? randomIdentity(config.randomBytes)
+        : undefined;
+    const rawIdentity = presentedIdentity || issuedIdentity || null;
     // The identity hash feeds experiment bucketing for identified visitors.
-    // Claims are a signed cookie written by /collect; the EdgeRouter
-    // never reads the customer object store to refresh or revoke them.
-    let signedClaims = mimic ? '' : cookies.get('aci_claims') || '';
+    // Claims are a signed cookie written by /collect or the provider identity
+    // bootstrap; the EdgeRouter never reads the customer object store to
+    // refresh or revoke them.
     let identityHash = '';
     if (rawIdentity) {
         identityHash = await identityHashHex('aci_id', rawIdentity);
     }
-    if (rawIdentity && consent.allowsIdentityTier && signedClaims) {
-        if (!await verifyClaims(signedClaims, config.claimsKeys || {}, now)) {
-            signedClaims = '';
-        }
-    }
     const matchedRoute = config.route;
     let variantKey = '';
     if (matchedRoute) {
         const claims = mimic
             ? { aud: mimic.aud, seg: mimic.seg, iat: 0, exp: 0 }
             : consent.allowsIdentityTier
-                ? await verifyClaims(signedClaims, config.claimsKeys || {}, now)
+                ? verifiedVisitor
+                    ? verifiedVisitor.claims
+                    : await verifyClaims(cookies.get('aci_claims') || '', config.claimsKeys || {}, now)
                 : null;
-        const decision = resolvePersonalizationDecision(toPersonalizationRequestContext(request, now, config.onRuleRejected), matchedRoute, claims, config.experiments, identityHash
+        const decision = resolvePersonalizationDecision(toPersonalizationRequestContext(request, now, config.requestGeo, config.onRuleRejected), matchedRoute, claims, config.experiments, identityHash
             ? { usable: true, siteId: config.siteId, namespace: 'aci_id', identityHash }
-            : undefined);
+            : undefined, mimic?.arms);
         if (decision.variant) {
             variantKey = decision.variant.variantKey;
         }
-        const experiment = decision.experiment
-            ? { id: decision.experiment.experimentId, arm: decision.experiment.armId, allocationVersion: decision.experiment.allocationVersion }
-            : undefined;
-        return { variantKey, experiment };
+        const experiments = decision.experiments.map((item) => ({
+            id: item.experimentId,
+            arm: item.armId,
+            allocationVersion: item.allocationVersion,
+            ...(item.forced ? { forced: true } : {}),
+        }));
+        return {
+            variantKey,
+            experiments,
+            ...(decision.legacyExperimentExclusions ? { legacyExperimentExclusions: decision.legacyExperimentExclusions } : {}),
+            ...(issuedIdentity ? { issuedIdentity } : {}),
+        };
     }
-    return { variantKey };
+    return { variantKey, experiments: [], ...(issuedIdentity ? { issuedIdentity } : {}) };
 }
 // The return type is annotated rather than inferred so the contract is stated
 // at the construction site: a misspelled property would then silently never
@@ -68,7 +85,7 @@ export async function resolvePersonalizationRequest(request, config) {
 // make visible. No tsconfig covers internal/domain/** today (esbuild/tsx strip
 // types without checking), so the annotation is documentation now and becomes
 // real protection under any future typecheck of these trees.
-function toPersonalizationRequestContext(request, now, onRuleRejected) {
+function toPersonalizationRequestContext(request, now, requestGeo, onRuleRejected) {
     const url = new URL(request.url);
     const cookies = parseCookieHeader(request.headers.get('cookie'));
     const query = {};
@@ -76,11 +93,11 @@ function toPersonalizationRequestContext(request, now, onRuleRejected) {
         (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 !== ''));
+    // geo.* facts come only from the host's trusted geo. Reading provider geo
+    // headers here trusted whatever the viewer sent on every lane whose
+    // provider does not stamp that exact header before the decision runs.
+    const geo = Object.fromEntries(Object.entries(requestGeo ?? {})
+        .filter((entry) => typeof entry[1] === 'string' && entry[1] !== ''));
     return {
         path: url.pathname,
         query,

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

@@ -73,6 +73,8 @@ export interface PersonalizationRequestContext {
     onRuleRejected?: (event: RuleRejectionEvent) => void;
 }
 export interface RuleRejectionEvent {
+    experimentId?: string;
+    armId?: string;
     variantKey: string;
     diagnosticCode: string;
     diagnosticPath: string;
@@ -96,10 +98,18 @@ export interface PersonalizationExperiment {
     allocationVersion?: string;
     salt?: string;
     eligibilityAudienceId?: string;
+    /**
+     * ADR 0050 (experiment I-18): the projection carries this only when the
+     * experiment declares `eligibility.mode: "selected"`; absent means the
+     * claims gate (I-6) applies. The selected-leg predicate itself is slice
+     * A5 (edge-functions I-16) — A3 is projection plumbing only.
+     */
+    eligibilityMode?: 'selected';
     arms: Array<{
         id: string;
         allocationBasisPoints?: number;
-        variantKey: string;
+        /** DEBT(edge-functions): decode old arm keys until every retained tenant release passes the ADR-0045 removal inventory. */
+        variantKey?: string;
     }>;
 }
 export interface PersonalizationIdentity {
@@ -114,24 +124,14 @@ export interface PersonalizationExperimentDecision {
     allocationVersion: string;
     variantKey: string;
     bucket: number;
+    /** audience-mimic design/09: the token's assertion replaced the dice. */
+    forced?: boolean;
 }
 export interface PersonalizationDecision {
+    /** ADR-0045: number of route experiments excluded as legacy pair-only entries. */
+    legacyExperimentExclusions?: number;
     variant: PersonalizationVariant | null;
-    experiment: PersonalizationExperimentDecision | null;
-}
-export interface ClassificationData {
-    audiences: Record<string, {
-        rule: EdgeRuleExpression;
-    }>;
-    segments: Record<string, {
-        rule: EdgeRuleExpression;
-    }>;
-    experiments: Record<string, PersonalizationExperiment>;
-}
-export interface Classification {
-    matchedAudiences: string[];
-    matchedSegments: string[];
-    experimentArms: Record<string, PersonalizationExperimentDecision>;
+    experiments: PersonalizationExperimentDecision[];
 }
 export interface SigningKey {
     kid: string;
@@ -166,20 +166,6 @@ export interface ConsentSignals {
     allowsIdentityTier: boolean;
     privacyDenied: boolean;
 }
-export interface PersonalizationEnvelopeWrite {
-    key: string;
-    envelopeId: string;
-    siteId: string;
-    identityNamespace: string;
-    identityHash: string;
-    records: readonly unknown[];
-    digest: string;
-}
-export interface PersonalizationCollectionStore {
-    readClaims(siteId: string, namespace: string, identityHash: string, now?: Date): Promise<string | null>;
-    appendEnvelope(write: PersonalizationEnvelopeWrite): Promise<void>;
-    putSuppression(key: string, record: unknown): Promise<void>;
-}
 export interface PersonalizationHostConfig {
     siteId: string;
     route: EdgeRouteEntry | null;
@@ -190,9 +176,20 @@ export interface PersonalizationHostConfig {
     secureCookies?: boolean;
     now?: () => Date;
     randomBytes?: (length: number) => Uint8Array;
+    verifiedVisitor?: {
+        rawIdentity: string | null;
+        claims: ClaimsPayload | null;
+    };
+    requestGeo?: {
+        country?: string;
+        region?: string;
+        city?: string;
+    };
+    issueIdentity?: boolean;
     mimicClaims?: {
         aud?: string[];
         seg?: string[];
+        arms?: Record<string, string>;
     };
     /**
      * Passed straight through to the request context's rejection sink so a host
@@ -202,13 +199,25 @@ export interface PersonalizationHostConfig {
      */
     onRuleRejected?: (event: RuleRejectionEvent) => void;
 }
+export interface ClaimsPayload {
+    aud?: string[];
+    seg?: string[];
+    iat: number;
+    exp: number;
+}
 export interface PersonalizationResolution {
+    /** ADR-0045: number of route experiments excluded as legacy pair-only entries. */
+    legacyExperimentExclusions?: number;
+    /** ADR 0048: the raw identity issued for this request, unsigned and not yet persisted. */
+    issuedIdentity?: string;
     variantKey: string;
-    experiment?: {
+    experiments: Array<{
         id: string;
         arm: string;
         allocationVersion: string;
-    };
+        /** audience-mimic design/09: the assignment came from the token, not the dice. */
+        forced?: boolean;
+    }>;
 }
 export interface CompositionDescriptor {
     layoutArtifact: string;

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

@@ -0,0 +1,3 @@
+export declare function compareUTF8(left: string, right: string): number;
+export declare function canonicalVariantKey(values: Record<string, string>): string;
+export declare function parseVariantKey(key: string): Record<string, string>;

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

@@ -0,0 +1,44 @@
+// Canonical factor keys mirror audience.VariantKey/ParseVariantKey. Their
+// shared vector lives in audience/testdata/variant-key.v1.json.
+export function compareUTF8(left, right) {
+    const a = Array.from(left);
+    const b = Array.from(right);
+    for (let i = 0; i < Math.min(a.length, b.length); i++) {
+        const difference = a[i].codePointAt(0) - b[i].codePointAt(0);
+        if (difference)
+            return difference;
+    }
+    return a.length - b.length;
+}
+export function canonicalVariantKey(values) {
+    const fixed = ['locale', 'audience', 'segment'].filter((name) => values[name]?.trim());
+    const rest = Object.keys(values).filter((name) => values[name]?.trim() && !fixed.includes(name));
+    const generic = rest.filter((name) => !name.startsWith('experiment.')).sort(compareUTF8);
+    const experiments = rest.filter((name) => name.startsWith('experiment.')).sort(compareUTF8);
+    return [...fixed, ...generic, ...experiments].map((name) => `${name}=${values[name].trim()}`).join(';') || 'base';
+}
+export function parseVariantKey(key) {
+    const values = {};
+    if (key === 'base')
+        return values;
+    for (const part of key.split(';')) {
+        const separator = part.indexOf('=');
+        const name = part.slice(0, separator);
+        const value = part.slice(separator + 1);
+        if (separator < 1 || !validToken(name) || !validToken(value))
+            throw new Error('variant key has malformed factors');
+        if (name === 'experiment' || name === 'experimentArm')
+            throw new Error('pair-form experiment key is not canonical');
+        if (name.startsWith('experiment.') && (!/^[a-zA-Z0-9_-]+$/.test(name.slice('experiment.'.length)) || !/^[a-zA-Z0-9_-]+$/.test(value)))
+            throw new Error('variant key has malformed experiment factor');
+        if (Object.prototype.hasOwnProperty.call(values, name))
+            throw new Error('variant key repeats a dimension');
+        Object.defineProperty(values, name, { value, enumerable: true, writable: true, configurable: true });
+    }
+    if (canonicalVariantKey(values) !== key)
+        throw new Error('variant key is not canonically ordered');
+    return values;
+}
+function validToken(value) {
+    return value !== '' && value !== '.' && value !== '..' && !/[\p{White_Space};=/]/u.test(value);
+}

package/dist/internal/platform/collectionstore/errors.d.ts

@@ -3,3 +3,16 @@ export declare class IdentityErasureFencedError extends Error {
     readonly code = "IDENTITY_ERASURE_FENCED";
     constructor();
 }
+export declare class CollectionGateBusyError extends Error {
+    readonly name = "CollectionGateBusyError";
+    readonly code = "COLLECTION_GATE_BUSY";
+    constructor(detail?: string);
+}
+export declare class EnvelopeIdCollisionError extends Error {
+    readonly name = "EnvelopeIdCollisionError";
+    readonly code = "ENVELOPE_ID_COLLISION";
+    readonly envelopeId: string;
+    readonly existingDigest: string;
+    readonly incomingDigest: string;
+    constructor(envelopeId: string, existingDigest: string, incomingDigest: string);
+}

package/dist/internal/platform/collectionstore/errors.js

@@ -5,3 +5,31 @@ export class IdentityErasureFencedError extends Error {
         super('identity collection is fenced by erasure');
     }
 }
+// Go parity: audience.ErrCollectionGateBusy. A live or unproven collecting
+// generation owns the identity; the caller must fail loudly and retry later,
+// never treat the append as stored or dropped.
+export class CollectionGateBusyError extends Error {
+    name = 'CollectionGateBusyError';
+    code = 'COLLECTION_GATE_BUSY';
+    constructor(detail) {
+        super(detail
+            ? `audience: identity collection gate is busy: ${detail}`
+            : 'audience: identity collection gate is busy');
+    }
+}
+// Go parity: audience.EnvelopeIDCollisionError. The envelope ID already names
+// an object whose stable-input digest differs (or is absent), so this request
+// is not an identical retry and must not be acknowledged as stored.
+export class EnvelopeIdCollisionError extends Error {
+    name = 'EnvelopeIdCollisionError';
+    code = 'ENVELOPE_ID_COLLISION';
+    envelopeId;
+    existingDigest;
+    incomingDigest;
+    constructor(envelopeId, existingDigest, incomingDigest) {
+        super(`audience: envelope ID collision: ${envelopeId}`);
+        this.envelopeId = envelopeId;
+        this.existingDigest = existingDigest;
+        this.incomingDigest = incomingDigest;
+    }
+}

package/dist/mintlify/blocks.d.ts

@@ -0,0 +1,6 @@
+import type { MintlifyBlock, MintlifyDocument, MintlifySnippet } from './types.js';
+export declare function renderDocument(document: MintlifyDocument): string;
+export declare function renderSnippet(snippet: MintlifySnippet): string;
+export declare function validateBlock(value: unknown, label: string, ids: Set<string>): MintlifyBlock;
+export declare function visitBlocks(blocks: MintlifyBlock[], visit: (block: MintlifyBlock) => void): void;
+export declare function validateSnippetReferences(documents: MintlifyDocument[], snippets: MintlifySnippet[]): void;