@gradial/aci 0.1.52-rc.3 → 0.1.52-rc.34-e2e.1

package/dist/internal/domain/edge/testdata/flat_only_validator_v1.js

@@ -0,0 +1,253 @@
+// FROZEN FIXTURE — the request-expression validation path as it stood before
+// ADR 0040 added nested boolean expression trees, vendored from
+// `internal/domain/edge/personalization-core.ts` at commit 1b785e4ac^ (the
+// parent of the ADR 0040 landing commit). Do NOT update this file to track the
+// live validator: its whole value is that it is stale.
+//
+// It exists so one test can reproduce the incident ADR 0040 predicts and says
+// it could not previously debug — a lane running a flat-only evaluator meeting
+// a record carrying a valid nested rule. That evaluator has no concept of a
+// group node, so it classifies `{all:[...]}` as a leaf condition and reports
+// the leaf vocabulary as unsupported. The resulting diagnostics are what the
+// host recorder actually writes during real version skew, and they are NOT the
+// same as those produced by a current, nesting-aware validator refusing a
+// malformed rule.
+//
+// What is vendored: the COMPLETE validation path — `validateRequestExpression`
+// and `validateRequestCondition` with every branch (per-field operator
+// restrictions for device.class / time.now / audience.memberships, and every
+// value check), plus each helper those functions reach
+// (`expressionNumberInDomain`, `parseExpressionTimestamp`,
+// `expressionDaysInMonth`, `canonicalScalar`, `validExpressionRange`,
+// `homogeneousExpressionMembers`, and the DEVICE_CLASSES / MAX_IN_VALUES /
+// grammar constants). Evaluation, matching, and the fact vocabulary are
+// irrelevant to the record's shape and are deliberately absent.
+//
+// Adaptations from the source commit (everything not listed here is verbatim):
+//  1. Entry-point signature. The original `validateRequestExpression` was
+//     3-argument — its callers pre-extracted `all`/`any` with `rule.all || []`.
+//     The frozen export is 1-argument and derives them itself with
+//     `Array.isArray` guards (strictly stronger than the original `|| []`) so
+//     the fixture is safe to call directly on untrusted record data.
+//  2. The diagnostic type is renamed `FrozenExpressionDiagnostic` (from
+//     `ExpressionDiagnostic`) so a frozen diagnostic can never be confused
+//     with a live one at a call site.
+//  3. Export keywords were removed from the vendored internals; only the
+//     entry point and its diagnostic type are exported.
+const MAX_EXPRESSION_CONDITIONS = 64;
+const EXPRESSION_OPERATORS = [
+    'equals', 'contains', 'startsWith', 'exists',
+    'greaterThan', 'greaterThanOrEqual', 'lessThan', 'lessThanOrEqual',
+    'before', 'after', 'between', 'in',
+];
+const MAX_IN_VALUES = 32;
+// Observed values are gated on the published grammars before any host parser
+// runs (ADR 0038): Number() and Date.parse accept supersets (hex, empty
+// string, vendor date formats) that would let the same fact match here and
+// not in Go. Keep these literals identical to the capability artifact — the
+// drift test compares them byte-for-byte.
+const EXPRESSION_NUMBER_GRAMMAR = /^-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?$/;
+const EXPRESSION_TIMESTAMP_GRAMMAR = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/;
+const DEVICE_CLASSES = ['desktop', 'mobile', 'tablet', 'unknown'];
+// Adaptation 1 (see header): the original was 3-argument with caller-extracted
+// `all`/`any`; this 1-argument form derives them with Array.isArray guards.
+// The body below this line is verbatim from the source commit.
+export function frozenValidateRequestExpression(rule) {
+    const all = (Array.isArray(rule.all) ? rule.all : []);
+    const any = (Array.isArray(rule.any) ? rule.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) => frozenValidateRequestCondition(condition, `expression.${group}[${index}]`, diagnostics));
+    }
+    return diagnostics;
+}
+// Verbatim from the source commit: the full flat-era condition validator,
+// including the per-field operator restrictions and every value check.
+function frozenValidateRequestCondition(condition, path, diagnostics) {
+    Object.keys(condition).filter((property) => !['field', 'operator', 'value'].includes(property)).sort().forEach((property) => {
+        diagnostics.push({ code: 'expression.property.unsupported', path: `${path}.${property}`, scope: 'request', message: `${path}.${property} is not a supported condition property` });
+    });
+    const field = String(condition.field || '');
+    if (field !== 'referrer' && field !== 'device.class' && field !== 'time.now' && field !== 'audience.memberships' && !['query.', 'header.', 'cookie.', 'geo.', 'utm.'].some((prefix) => field.startsWith(prefix) && field.length > prefix.length)) {
+        diagnostics.push({ code: 'expression.field.unsupported', path: `${path}.field`, scope: 'request', message: `${path}.field ${JSON.stringify(field)} is not supported` });
+    }
+    const operator = String(condition.operator || '');
+    if (!EXPRESSION_OPERATORS.includes(operator)) {
+        diagnostics.push({ code: 'expression.operator.unsupported', path: `${path}.operator`, scope: 'request', message: `${path}.operator ${JSON.stringify(operator)} is not supported` });
+        return;
+    }
+    // device.class compares against a closed four-value set, so substring
+    // operators express nothing the set cannot — and admitting them would
+    // re-create the user-agent-substring habit inside the safe field (ADR 0037).
+    if (field === 'device.class' && !['equals', 'in', 'exists'].includes(operator)) {
+        diagnostics.push({ code: 'expression.operator.unsupported', path: `${path}.operator`, scope: 'request', message: `${path}.operator ${JSON.stringify(operator)} is not supported for field ${JSON.stringify(field)}, which compares against a closed value set` });
+        return;
+    }
+    // time.now is a sub-second-churning clock: string operators are silently
+    // inert on it and the numeric family can never match an RFC 3339 string
+    // (ADR 0038).
+    if (field === 'time.now' && !['before', 'after', 'between', 'exists'].includes(operator)) {
+        diagnostics.push({ code: 'expression.operator.unsupported', path: `${path}.operator`, scope: 'request', message: `${path}.operator ${JSON.stringify(operator)} is not supported for field ${JSON.stringify(field)}, which supports only before, after, between, exists` });
+        return;
+    }
+    // audience.memberships is an opaque-ID list: equals is already
+    // any-member-equals under the multi-valued match loop, so the substring
+    // family would only add silent overmatching of prefixed IDs, and the
+    // numeric/instant families can never match an ID (ADR 0039).
+    if (field === 'audience.memberships' && !['equals', 'in', 'exists'].includes(operator)) {
+        diagnostics.push({ code: 'expression.operator.unsupported', path: `${path}.operator`, scope: 'request', message: `${path}.operator ${JSON.stringify(operator)} is not supported for field ${JSON.stringify(field)}, which supports only equals, in, exists` });
+        return;
+    }
+    const value = condition.value;
+    if (operator === 'exists') {
+        if (value !== undefined && value !== null && typeof value !== 'boolean') {
+            diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value must be a boolean for operator exists` });
+        }
+        return;
+    }
+    if (value === undefined || value === null) {
+        diagnostics.push({ code: 'expression.value.required', path: `${path}.value`, scope: 'request', message: `${path}.value is required for operator ${operator}` });
+        return;
+    }
+    if (['equals', 'contains', 'startsWith'].includes(operator)) {
+        if (!['string', 'number', 'boolean'].includes(typeof value)
+            || (typeof value === 'number' && !expressionNumberInDomain(value))) {
+            diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value must be a string, boolean, or finite number using only safe integers` });
+        }
+        else if (field === 'device.class' && DEVICE_CLASSES.indexOf(canonicalScalar(value)) < 0) {
+            diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value must be one of ${DEVICE_CLASSES.join(', ')} for field ${JSON.stringify(field)}` });
+        }
+        return;
+    }
+    if (['greaterThan', 'greaterThanOrEqual', 'lessThan', 'lessThanOrEqual'].includes(operator)) {
+        if (typeof value !== 'number' || !expressionNumberInDomain(value)) {
+            diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value must be a finite JSON number using only safe integers for operator ${operator}` });
+        }
+        return;
+    }
+    if (operator === 'before' || operator === 'after') {
+        if (typeof value !== 'string' || parseExpressionTimestamp(value) === null) {
+            diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value must be an RFC 3339 timestamp with an explicit UTC offset for operator ${operator}` });
+        }
+        return;
+    }
+    if (operator === 'between') {
+        if (!validExpressionRange(value)) {
+            diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value must be a min/max object whose bounds are both numbers or both timestamps with min not above max` });
+        }
+        else if (field === 'time.now' && typeof value.min === 'number') {
+            // An instant field's observed values are instants: a numeric range on
+            // it would validate and then sit silently inert at execution.
+            diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value bounds must be timestamps for field ${JSON.stringify(field)}` });
+        }
+        return;
+    }
+    // in: bounded, non-empty, every member one canonicalizable scalar, all
+    // members one JSON type — a mixed list is almost always an authoring bug.
+    const members = homogeneousExpressionMembers(value);
+    if (members === null) {
+        diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value must be an array of 1 to ${MAX_IN_VALUES} scalars sharing one type` });
+        return;
+    }
+    if (field === 'device.class') {
+        for (const member of members) {
+            if (DEVICE_CLASSES.indexOf(member) < 0) {
+                diagnostics.push({ code: 'expression.value.invalid', path: `${path}.value`, scope: 'request', message: `${path}.value must be one of ${DEVICE_CLASSES.join(', ')} for field ${JSON.stringify(field)}` });
+                return;
+            }
+        }
+    }
+}
+// ── Validation helpers, verbatim from the source commit ──────────────────
+function expressionNumberInDomain(value) {
+    if (!Number.isFinite(value))
+        return false;
+    if (Number.isInteger(value) && !Number.isSafeInteger(value))
+        return false;
+    return true;
+}
+// Explicit calendar validation runs before Date arithmetic because Date.UTC
+// (like Go's time.Date) silently normalizes impossible dates. Instants
+// compare as epoch milliseconds; fractional seconds truncate to milliseconds.
+function parseExpressionTimestamp(value) {
+    const match = EXPRESSION_TIMESTAMP_GRAMMAR.exec(value);
+    if (!match)
+        return null;
+    const year = Number(match[1]), month = Number(match[2]), day = Number(match[3]);
+    const hour = Number(match[4]), minute = Number(match[5]), second = Number(match[6]);
+    if (month < 1 || month > 12 || day < 1 || day > expressionDaysInMonth(year, month))
+        return null;
+    if (hour > 23 || minute > 59 || second > 59)
+        return null;
+    let offsetMinutes = 0;
+    if (match[8] !== 'Z') {
+        const offsetHour = Number(match[8].slice(1, 3)), offsetMinute = Number(match[8].slice(4, 6));
+        if (offsetHour > 23 || offsetMinute > 59)
+            return null;
+        offsetMinutes = offsetHour * 60 + offsetMinute;
+        if (match[8][0] === '-')
+            offsetMinutes = -offsetMinutes;
+    }
+    const fractionMillis = match[7] ? Number((match[7].slice(1) + '00').slice(0, 3)) : 0;
+    // setUTCFullYear, not Date.UTC: Date.UTC maps two-digit years to 1900+.
+    const date = new Date(0);
+    date.setUTCFullYear(year, month - 1, day);
+    date.setUTCHours(hour, minute, second, 0);
+    return date.getTime() - offsetMinutes * 60000 + fractionMillis;
+}
+function expressionDaysInMonth(year, month) {
+    if (month === 4 || month === 6 || month === 9 || month === 11)
+        return 30;
+    if (month === 2)
+        return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0) ? 29 : 28;
+    return 31;
+}
+function canonicalScalar(value) {
+    if (typeof value === 'number')
+        return Object.is(value, -0) ? '0' : JSON.stringify(value);
+    return String(value);
+}
+function validExpressionRange(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    if (Object.keys(record).some((key) => key !== 'min' && key !== 'max'))
+        return false;
+    const min = record.min, max = record.max;
+    if (min === undefined || min === null || max === undefined || max === null)
+        return false;
+    if (typeof min === 'number' && expressionNumberInDomain(min)) {
+        return typeof max === 'number' && expressionNumberInDomain(max) && min <= max;
+    }
+    const minMillis = typeof min === 'string' ? parseExpressionTimestamp(min) : null;
+    if (minMillis === null)
+        return false;
+    const maxMillis = typeof max === 'string' ? parseExpressionTimestamp(max) : null;
+    return maxMillis !== null && minMillis <= maxMillis;
+}
+function homogeneousExpressionMembers(value) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > MAX_IN_VALUES)
+        return null;
+    let memberKind = '';
+    const members = [];
+    for (const member of value) {
+        const kind = typeof member;
+        if (kind !== 'string' && kind !== 'number' && kind !== 'boolean')
+            return null;
+        if (kind === 'number' && !expressionNumberInDomain(member))
+            return null;
+        if (!memberKind)
+            memberKind = kind;
+        else if (memberKind !== kind)
+            return null;
+        members.push(canonicalScalar(member));
+    }
+    return members;
+}

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

@@ -4,10 +4,17 @@ export interface EdgeDispatch {
     /** Release-relative immutable HTML artifact selected for this route. */
     artifactPath: string;
 }
+/**
+ * One member of an expression group: a leaf condition, or a nested envelope
+ * when it carries `all`/`any` (ADR 0040). Presence of a group key decides
+ * which it is, so flat records stay a byte-identical subset.
+ */
 export interface EdgeRuleCondition {
-    field: string;
-    operator: 'exists' | 'equals' | 'contains' | 'startsWith' | string;
+    field?: string;
+    operator?: 'exists' | 'equals' | 'contains' | 'startsWith' | 'greaterThan' | 'greaterThanOrEqual' | 'lessThan' | 'lessThanOrEqual' | 'before' | 'after' | 'between' | 'in' | string;
     value?: unknown;
+    all?: EdgeRuleCondition[];
+    any?: EdgeRuleCondition[];
 }
 export interface EdgeRuleExpression {
     all?: EdgeRuleCondition[];
@@ -48,9 +55,30 @@ export interface PersonalizationRequestContext {
     signals?: {
         geo?: Record<string, string>;
     };
+    /**
+     * Epoch milliseconds resolving the time.now clock fact (ADR 0038).
+     * Defaults to Date.now(); hosts may pin it once per request so every
+     * expression in one evaluation reads the same instant.
+     */
+    now?: number;
     identityHash?: string;
     identityNamespace?: string;
     siteId?: string;
+    /**
+     * Called when a variant's rule fails validation during serving (ADR 0040).
+     * Records pass the write-time gate before shipping, so this only fires on
+     * version skew or a projection bug — a precise signal that must not vanish.
+     * Receives routing facts and diagnostic codes only, never request data.
+     */
+    onRuleRejected?: (event: RuleRejectionEvent) => void;
+}
+export interface RuleRejectionEvent {
+    experimentId?: string;
+    armId?: string;
+    variantKey: string;
+    diagnosticCode: string;
+    diagnosticPath: string;
+    diagnosticCount: number;
 }
 export interface PersonalizationClaims {
     aud?: string[];
@@ -58,13 +86,7 @@ export interface PersonalizationClaims {
     iat: number;
     exp: number;
 }
-export interface PersonalizationVariant {
-    variantKey: string;
-    variantValues?: Record<string, string>;
-    priority?: number;
-    rule?: EdgeRuleExpression;
-    dispatch: EdgeDispatch;
-}
+export type PersonalizationVariant = EdgeRouteVariant;
 export interface PersonalizationRoute {
     variants?: Record<string, PersonalizationVariant>;
 }
@@ -75,10 +97,19 @@ export interface PersonalizationExperiment {
     priority?: number;
     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 {
@@ -93,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;
@@ -145,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;
@@ -169,13 +176,58 @@ 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
+     * can record a variant skipped for a rule it could not validate (ADR 0040).
+     * Unset means the skip stays silent, which is what made the skew incident
+     * the ADR predicts undebuggable.
+     */
+    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;
+    fragments?: Record<string, string>;
+}
+export type SelectedTargetKind = 'direct' | 'compose' | 'render';
+export interface SelectedTarget {
+    kind: SelectedTargetKind;
+    path: string;
+    digest: string;
+    composition?: CompositionDescriptor;
 }
 export { IdentityErasureFencedError } from '../../platform/collectionstore/errors.js';

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

@@ -1,7 +1,7 @@
 // Shared edge-decisioning types.
 //
 // These types are the canonical shape for the edge decisioning algorithm.
-// All host adapters (AWS, Cloudflare, Vercel, emulator) import from here.
-// The SDK's personalization-core types mirror these — the two are kept in
-// sync by cross-language round-trip tests (spec edge-decisioning R-conformance).
+// All host adapters (AWS, Cloudflare, Vercel, emulator) import from here,
+// and the SDK build compiles this module into its dist/internal tree — there
+// is no SDK-side mirror (ADR 0041 retired the hand-ported copy).
 export { IdentityErasureFencedError } from '../../platform/collectionstore/errors.js';

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,27 @@ 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);
+}
+export declare class AdmissionConflictError extends Error {
+    readonly kind: 'envelope' | 'event';
+    readonly name = "AdmissionConflictError";
+    readonly code = "COLLECT_ADMISSION_CONFLICT";
+    constructor(kind: 'envelope' | 'event');
+}
+export declare class CollectionStoreError extends Error {
+    readonly code: string;
+    readonly name = "CollectionStoreError";
+    constructor(code: string, message: string, options?: ErrorOptions);
+}

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

@@ -5,3 +5,51 @@ 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;
+    }
+}
+// Different site-scoped acceptance owner; no visitor identifiers in the error.
+export class AdmissionConflictError extends Error {
+    kind;
+    name = 'AdmissionConflictError';
+    code = 'COLLECT_ADMISSION_CONFLICT';
+    constructor(kind) {
+        super(`collect ${kind} ID already belongs to another acceptance; retry only the original sealed envelope with its original identity and consent`);
+        this.kind = kind;
+    }
+}
+// Internal store failure with a stable bounded code. Collector diagnostics log
+// the code and never the message, which may interpolate object keys.
+export class CollectionStoreError extends Error {
+    code;
+    name = 'CollectionStoreError';
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}

package/dist/mimic/core.d.ts

@@ -0,0 +1,2 @@
+export declare const MIMIC_BANNER_HEADER = "x-aci-mimic-banner";
+export declare function decodeMimicBanner(encoded: string): string;

package/dist/mimic/core.js

@@ -0,0 +1,31 @@
+// View-as-audience mimic banner contract (specs/features/audience-mimic).
+// The platform edge router (internal/domain/hosting/runtime/mimic.ts) owns
+// the mimic session — token validation, cookies, redirects, and banner
+// creation. On body-less SSR rewrites it forwards the rendered banner to the
+// framework host via MIMIC_BANNER_HEADER; this module is the framework-side
+// leg that decodes it (the MimicBanner component in next/page.tsx). The
+// middleware strips any inbound copy of the header and sets it only for a
+// validated session, so the decoded HTML is trusted as authored.
+//
+// The SDK-side token validator that used to live here served the retired
+// Next personalization-host lane (ADR 0041); the Go/TS validators in
+// internal/domain/edge remain pinned by the shared vector file.
+export const MIMIC_BANNER_HEADER = 'x-aci-mimic-banner';
+export function decodeMimicBanner(encoded) {
+    try {
+        return new TextDecoder().decode(base64URLToBytes(encoded));
+    }
+    catch {
+        return '';
+    }
+}
+function base64URLToBytes(value) {
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, '=');
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}

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;