@gradial/aci 0.1.51-ssr.5 → 0.1.52-rc.2

package/README.md

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

package/dist/astro/assets.d.ts

@@ -5,16 +5,16 @@
  * at the URL level. Instead:
  *
  * - In dev: the Vite `damAssetPlugin` serves DAM assets from compiled
- *   content at `/.gradial-dam/{path}` (already handled by withAci).
+ *   content at `/dam/{path}` (already handled by withAci).
  *
- * - In production: the provider host maps `/.gradial-dam/*` to authoritative
- *   S3/R2/CDN storage. There is no app-level asset route
- *   (the retired Next `/gradial/assets` proxy no longer exists).
+ * - In production: CloudFront maps `/dam/*` to the S3 bucket
+ *   containing the compiled assets. There is no app-level asset route
+ *   (unlike Next.js which has `/gradial/assets/[releaseId]/[...path]`).
  *   The assets are content-addressed (hashed filenames) so the CDN
  *   can cache them with long TTLs.
  *
  * - At build time: `withAci`'s `astro:build:done` hook copies the
- *   `.gradial-dam` directory from compiled content into the build output,
+ *   `dam` directory from compiled content into the build output,
  *   so `astro build` produces a self-contained artifact.
  *
  * This module provides a helper to construct asset URLs that work in both
@@ -25,15 +25,15 @@
  * Default asset URL prefix. Matches the Vite middleware path and the
  * provider gateway's asset path.
  */
-export declare const DAM_ASSET_PREFIX = "/.gradial-dam";
+export declare const DAM_ASSET_PREFIX = "/dam";
 /**
  * Construct a DAM asset URL from a logical asset path.
  *
- * In both dev and production, DAM assets live under `/.gradial-dam/`.
+ * In both dev and production, DAM assets live under `/dam/`.
  * This function normalizes the path and prepends the prefix.
  *
  * @param logicalPath - The asset path as stored in content (e.g. "images/hero.webp")
- * @returns The full URL path (e.g. "/.gradial-dam/images/hero.webp")
+ * @returns The full URL path (e.g. "/dam/images/hero.webp")
  *
  * @example
  * ```astro

package/dist/astro/assets.js

@@ -5,16 +5,16 @@
  * at the URL level. Instead:
  *
  * - In dev: the Vite `damAssetPlugin` serves DAM assets from compiled
- *   content at `/.gradial-dam/{path}` (already handled by withAci).
+ *   content at `/dam/{path}` (already handled by withAci).
  *
- * - In production: the provider host maps `/.gradial-dam/*` to authoritative
- *   S3/R2/CDN storage. There is no app-level asset route
- *   (the retired Next `/gradial/assets` proxy no longer exists).
+ * - In production: CloudFront maps `/dam/*` to the S3 bucket
+ *   containing the compiled assets. There is no app-level asset route
+ *   (unlike Next.js which has `/gradial/assets/[releaseId]/[...path]`).
  *   The assets are content-addressed (hashed filenames) so the CDN
  *   can cache them with long TTLs.
  *
  * - At build time: `withAci`'s `astro:build:done` hook copies the
- *   `.gradial-dam` directory from compiled content into the build output,
+ *   `dam` directory from compiled content into the build output,
  *   so `astro build` produces a self-contained artifact.
  *
  * This module provides a helper to construct asset URLs that work in both
@@ -25,15 +25,15 @@
  * Default asset URL prefix. Matches the Vite middleware path and the
  * provider gateway's asset path.
  */
-export const DAM_ASSET_PREFIX = '/.gradial-dam';
+export const DAM_ASSET_PREFIX = '/dam';
 /**
  * Construct a DAM asset URL from a logical asset path.
  *
- * In both dev and production, DAM assets live under `/.gradial-dam/`.
+ * In both dev and production, DAM assets live under `/dam/`.
  * This function normalizes the path and prepends the prefix.
  *
  * @param logicalPath - The asset path as stored in content (e.g. "images/hero.webp")
- * @returns The full URL path (e.g. "/.gradial-dam/images/hero.webp")
+ * @returns The full URL path (e.g. "/dam/images/hero.webp")
  *
  * @example
  * ```astro

package/dist/astro/index.js

@@ -94,10 +94,10 @@ export function withAci(options = {}) {
             'astro:build:done'({ dir }) {
                 const siteDir = process.cwd();
                 const compiledRoot = path.resolve(siteDir, options.compiledRoot || process.env.ACI_CONTENT_ROOT || '.aci/compiled');
-                const source = path.join(compiledRoot, '.gradial-dam');
+                const source = path.join(compiledRoot, 'dam');
                 if (!fs.existsSync(source))
                     return;
-                const target = path.join(dir.pathname, '.gradial-dam');
+                const target = path.join(dir.pathname, 'dam');
                 fs.rmSync(target, { recursive: true, force: true });
                 fs.cpSync(source, target, { recursive: true });
             },

package/dist/content/cache.d.ts

@@ -1,11 +1,16 @@
-import type { ContentProvider } from './provider.js';
+import type { CompiledManifest, ContentProvider } from './provider.js';
 export declare function getCacheStats(): {
+    manifest: {
+        hits: number;
+        misses: number;
+    };
     siteConfig: {
         hits: number;
         misses: number;
     };
 };
 export declare function resetCacheStats(): void;
+export declare function getCachedManifest(provider: ContentProvider): Promise<CompiledManifest>;
 /**
  * Get site config with caching. Use this instead of calling provider.getSiteConfig() directly.
  */

package/dist/content/cache.js

@@ -5,19 +5,44 @@
  *
  * Keyed by provider instance for automatic invalidation when its input changes.
  */
+const manifestCache = new WeakMap();
 const siteConfigCache = new WeakMap();
 // Cache hit/miss stats for observability
+let manifestHits = 0;
+let manifestMisses = 0;
 let siteConfigHits = 0;
 let siteConfigMisses = 0;
 export function getCacheStats() {
     return {
+        manifest: { hits: manifestHits, misses: manifestMisses },
         siteConfig: { hits: siteConfigHits, misses: siteConfigMisses },
     };
 }
 export function resetCacheStats() {
+    manifestHits = 0;
+    manifestMisses = 0;
     siteConfigHits = 0;
     siteConfigMisses = 0;
 }
+// getCachedManifest is intentionally capability based: the general content
+// interface does not require a manifest, while release-backed providers do.
+export function getCachedManifest(provider) {
+    const cached = manifestCache.get(provider);
+    if (cached) {
+        manifestHits++;
+        return cached;
+    }
+    if (!('manifest' in provider) || typeof provider.manifest !== 'function') {
+        throw new Error('Provider does not support manifest()');
+    }
+    manifestMisses++;
+    const promise = provider.manifest().catch((error) => {
+        manifestCache.delete(provider);
+        throw error;
+    });
+    manifestCache.set(provider, promise);
+    return promise;
+}
 /**
  * Get site config with caching. Use this instead of calling provider.getSiteConfig() directly.
  */
@@ -44,5 +69,6 @@ export function getCachedSiteConfig(provider) {
  * Useful for testing or manual cache invalidation.
  */
 export function clearProviderCache(provider) {
+    manifestCache.delete(provider);
     siteConfigCache.delete(provider);
 }

package/dist/dev/content-watch.js

@@ -95,7 +95,7 @@ export function damAssetPlugin(options = {}) {
         configureServer(server) {
             if (!server.middlewares)
                 return;
-            server.middlewares.use('/.gradial-dam', async (req, res, next) => {
+            server.middlewares.use('/dam', async (req, res, next) => {
                 const root = path.resolve(options.compiledRoot || compiledContentRoot());
                 const requestPath = safeRequestPath(req.url || '');
                 if (!requestPath) {
@@ -103,7 +103,7 @@ export function damAssetPlugin(options = {}) {
                     res.end('asset not found');
                     return;
                 }
-                const filePath = path.resolve(root, '.gradial-dam', requestPath.replace(/^\/+/, ''));
+                const filePath = path.resolve(root, 'dam', requestPath.replace(/^\/+/, ''));
                 if (!isInside(root, filePath)) {
                     res.statusCode = 404;
                     res.end('asset not found');
@@ -127,7 +127,7 @@ function safeRequestPath(url) {
     const rawPath = url.split('?')[0] || '';
     try {
         const decoded = decodeURIComponent(rawPath);
-        return decoded.startsWith('/.gradial-dam/') ? decoded.slice('/.gradial-dam/'.length) : decoded;
+        return decoded.startsWith('/dam/') ? decoded.slice('/dam/'.length) : decoded;
     }
     catch {
         return '';

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

@@ -0,0 +1,11 @@
+export function selectPersonalizationVariant(request: any, route: any, claims: any, experiments: any, identity: any): any;
+export function resolvePersonalizationDecision(request: any, route: any, claims: any, experiments: any, identity: any): {
+    variant: any;
+    experiment: {
+        experimentId: any;
+        armId: any;
+        allocationVersion: string;
+        variantKey: any;
+        bucket: number;
+    } | null;
+};

package/dist/edge/personalization-core.js

@@ -0,0 +1,269 @@
+// 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.
+export function selectPersonalizationVariant(request, route, claims, experiments, identity) {
+    return resolvePersonalizationDecision(request, route, claims, experiments, identity).variant;
+}
+export function resolvePersonalizationDecision(request, route, claims, experiments, identity) {
+    if (!route)
+        return { variant: null, experiment: null };
+    let variant = selectRuleVariant(request, route, claims, experiments);
+    let experiment = null;
+    if (identity && identity.usable && route.variants && experiments) {
+        const candidates = Object.values(experiments)
+            .filter((item) => (item.kind === 'ab' || item.kind === 'abn') && item.status === 'running')
+            .filter((item) => routeHasExperiment(route, item.id))
+            .sort((left, right) => (right.priority || 0) - (left.priority || 0)
+            || String(left.id || '').localeCompare(String(right.id || '')));
+        for (let index = 0; index < candidates.length; index++) {
+            const item = candidates[index];
+            const assignment = assignExperiment(item, identity);
+            const candidate = assignment && route.variants[assignment.variantKey];
+            if (!candidate)
+                continue;
+            if (!variant || betterVariant(candidate.priority || 0, candidate.variantKey, variant.priority || 0, variant.variantKey)) {
+                variant = candidate;
+                experiment = assignment;
+            }
+            break;
+        }
+    }
+    return { variant: variant || null, experiment };
+}
+function selectRuleVariant(request, route, claims, experiments) {
+    if (!route.variants)
+        return null;
+    const matches = [];
+    for (const key in route.variants) {
+        const variant = route.variants[key];
+        const values = variant.variantValues || variantValuesFromKey(key);
+        const experimentID = String(values.experiment || '').trim();
+        if (experimentID && (!experiments || !experiments[experimentID]
+            || experiments[experimentID].status !== 'running'))
+            continue;
+        if (!requestDimensionsMatch(request, values))
+            continue;
+        const membershipMatch = (values.audience && claims && (claims.aud || []).includes(values.audience))
+            || (values.segment && claims && (claims.seg || []).includes(values.segment));
+        const ruleMatch = variant.rule ? evaluateRule(request, variant.rule) : false;
+        if (membershipMatch || ruleMatch)
+            matches.push(variant);
+    }
+    matches.sort((left, right) => (right.priority || 0) - (left.priority || 0)
+        || 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);
+        if (values.experiment === experimentID)
+            return true;
+    }
+    return false;
+}
+function assignExperiment(experiment, identity) {
+    const version = String(experiment.allocationVersion || '').trim();
+    const salt = String(experiment.salt || '').trim();
+    const siteID = String(identity.siteId || '').trim();
+    const identityKey = `${String(identity.namespace || '').trim()}:${String(identity.identityHash || '').trim()}`;
+    if (!version || !salt || !siteID || identityKey === ':')
+        return null;
+    const input = [siteID, String(experiment.id || ''), version, identityKey, salt].join('\0');
+    const bucket = sha256Bucket(input);
+    let cumulative = 0;
+    const arms = experiment.arms || [];
+    for (let index = 0; index < arms.length; index++) {
+        const arm = arms[index];
+        if ((arm.allocationBasisPoints || 0) <= 0)
+            continue;
+        cumulative += arm.allocationBasisPoints;
+        if (bucket < cumulative) {
+            return {
+                experimentId: experiment.id,
+                armId: arm.id,
+                allocationVersion: version,
+                variantKey: arm.variantKey,
+                bucket,
+            };
+        }
+    }
+    return null;
+}
+function betterVariant(candidatePriority, candidateKey, bestPriority, bestKey) {
+    if (candidatePriority !== bestPriority)
+        return candidatePriority > bestPriority;
+    return String(candidateKey || '').localeCompare(String(bestKey || '')) < 0;
+}
+function requestDimensionsMatch(request, values) {
+    for (const rawKey in values) {
+        const rawWant = values[rawKey];
+        const key = String(rawKey).trim();
+        const normalized = key.toLowerCase();
+        const want = String(rawWant).trim();
+        if (!key || !want || ['audience', 'segment', 'experiment', 'experimentarm'].includes(normalized))
+            continue;
+        const candidates = (request.query[key] || []).concat(request.query['aci_' + key] || [], request.headers['x-aci-' + normalized] || '', request.headers['x-gradial-' + normalized] || '', request.cookies[key] || '', request.cookies['aci_' + key] || '');
+        if (normalized === 'locale') {
+            const locales = String(request.headers['accept-language'] || '')
+                .split(',').map((part) => part.split(';')[0].trim()).filter(Boolean);
+            for (let localeIndex = 0; localeIndex < locales.length; localeIndex++)
+                candidates.push(locales[localeIndex]);
+        }
+        if (!candidates.some((candidate) => normalized === 'locale'
+            ? String(candidate).toLowerCase() === want.toLowerCase()
+            : String(candidate) === want))
+            return false;
+    }
+    return true;
+}
+function evaluateRule(request, rule) {
+    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);
+    if (condition.operator === 'exists')
+        return values.length > 0;
+    if (values.length === 0 || !['string', 'number', 'boolean'].includes(typeof condition.value))
+        return false;
+    const expected = String(condition.value);
+    return values.some((value) => {
+        switch (condition.operator) {
+            case 'equals': return value === expected;
+            case 'contains': return value.includes(expected);
+            case 'startsWith': return value.startsWith(expected);
+            default: return false;
+        }
+    });
+}
+function 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] : [];
+    }
+    if (field === 'referrer') {
+        const value = request.headers.referer || request.headers.referrer;
+        return value ? [value] : [];
+    }
+    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) {
+    const bytes = utf8(value);
+    const words = new Uint32Array(64);
+    const bitLength = bytes.length * 8;
+    const paddedLength = ((bytes.length + 9 + 63) >> 6) << 6;
+    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;
+    data[paddedLength - 7] = (bitsHigh >>> 16) & 255;
+    data[paddedLength - 6] = (bitsHigh >>> 8) & 255;
+    data[paddedLength - 5] = bitsHigh & 255;
+    data[paddedLength - 4] = (bitsLow >>> 24) & 255;
+    data[paddedLength - 3] = (bitsLow >>> 16) & 255;
+    data[paddedLength - 2] = (bitsLow >>> 8) & 255;
+    data[paddedLength - 1] = bitsLow & 255;
+    let a = 0x6a09e667, b = 0xbb67ae85, c = 0x3c6ef372, d = 0xa54ff53a;
+    let e = 0x510e527f, f = 0x9b05688c, g = 0x1f83d9ab, h = 0x5be0cd19;
+    const k = [0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2];
+    for (let offset = 0; offset < paddedLength; offset += 64) {
+        for (let i = 0; i < 16; i++) {
+            const p = offset + i * 4;
+            words[i] = (data[p] << 24) | (data[p + 1] << 16) | (data[p + 2] << 8) | data[p + 3];
+        }
+        for (let i = 16; i < 64; i++) {
+            const x = words[i - 15], y = words[i - 2];
+            words[i] = (words[i - 16] + (rotr(x, 7) ^ rotr(x, 18) ^ (x >>> 3)) + words[i - 7] + (rotr(y, 17) ^ rotr(y, 19) ^ (y >>> 10))) >>> 0;
+        }
+        let aa = a, bb = b, cc = c, dd = d, ee = e, ff = f, gg = g, hh = h;
+        for (let i = 0; i < 64; i++) {
+            const s1 = rotr(ee, 6) ^ rotr(ee, 11) ^ rotr(ee, 25);
+            const ch = (ee & ff) ^ (~ee & gg);
+            const t1 = (hh + s1 + ch + k[i] + words[i]) >>> 0;
+            const s0 = rotr(aa, 2) ^ rotr(aa, 13) ^ rotr(aa, 22);
+            const maj = (aa & bb) ^ (aa & cc) ^ (bb & cc);
+            const t2 = (s0 + maj) >>> 0;
+            hh = gg;
+            gg = ff;
+            ff = ee;
+            ee = (dd + t1) >>> 0;
+            dd = cc;
+            cc = bb;
+            bb = aa;
+            aa = (t1 + t2) >>> 0;
+        }
+        a = (a + aa) >>> 0;
+        b = (b + bb) >>> 0;
+        c = (c + cc) >>> 0;
+        d = (d + dd) >>> 0;
+        e = (e + ee) >>> 0;
+        f = (f + ff) >>> 0;
+        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)); }
+function utf8(value) {
+    const out = [];
+    for (let i = 0; i < value.length; i++) {
+        let code = value.charCodeAt(i);
+        if (code >= 0xd800 && code <= 0xdbff && i + 1 < value.length) {
+            const next = value.charCodeAt(++i);
+            code = 0x10000 + ((code - 0xd800) << 10) + (next - 0xdc00);
+        }
+        if (code < 0x80)
+            out.push(code);
+        else if (code < 0x800)
+            out.push(0xc0 | (code >> 6), 0x80 | (code & 63));
+        else if (code < 0x10000)
+            out.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 63), 0x80 | (code & 63));
+        else
+            out.push(0xf0 | (code >> 18), 0x80 | ((code >> 12) & 63), 0x80 | ((code >> 6) & 63), 0x80 | (code & 63));
+    }
+    return new Uint8Array(out);
+}
+// CLOUDFRONT_STRIP_END

package/dist/internal/render-proof.d.ts

@@ -0,0 +1 @@
+export {};