@gradial/aci 0.1.52-rc.8 → 0.1.52

package/CHANGELOG.md

@@ -1,5 +1,131 @@
 # Changelog
 
+## 0.1.52
+
+### Changed
+
+- Prerelease versions are no longer committed. Canary builds
+  (`@gradial/aci@canary`) publish automatically from every SDK change on
+  `main`; release candidates (`@gradial/aci@rc`) and stable releases publish
+  on demand. All are prereleases or releases of the next stable version.
+
+### Removed
+
+- `@gradial/aci/next/server` no longer reads Vercel Edge Config.
+  `resolveReleaseId()` resolves an explicit release, then the verified routed
+  release, then `ACI_RELEASE_ID`, and otherwise throws; it never falls back to
+  an Edge Config active-release pointer. `FetchConfig` loses `edgeConfig`,
+  `deploymentId`, and `siteId`, which only that pointer read used. The
+  `EDGE_CONFIG` and `VERCEL_DEPLOYMENT_ID` environment variables are ignored.
+
+## 0.1.52-rc.41
+
+### Changed
+
+- Shared edge claims support collection-free external-audience delivery.
+  Personalization requires a recognized issuer marker; signed older cookies
+  remain valid evidence for consent withdrawal.
+
+## 0.1.52-rc.40
+
+### Fixed
+
+- Mimic pages retain Next hydration and native 404 rendering while the hosting
+  platform owns their private response and session banner. Browser measurement
+  stays disabled for the lifetime of each mimic document, including after its
+  cookie expires or another tab exits the session. Rebuild and redeploy sites
+  with this SDK and the matching hosting platform to pick up the fix.
+
+## 0.1.52-rc.38
+
+### Migration required
+
+- Link secondary experiment goals with `goalIds` instead of the retired
+  `goalRefs` field. Remove `goalRefs` from authored documents and authoring
+  integrations; `primaryGoalRef` remains supported. See the
+  [secondary-goal migration](./migrations/experiment-goal-ids.md).
+
+## 0.1.52-rc.37
+
+### Removed
+
+- Unused edge identity helpers and types. The shared runtime retains the
+  production identity and routing behavior.
+
+## 0.1.52-rc.36
+
+### Removed
+
+- The unused compact route-record codec and static compose terminal target.
+  Static delivery selects complete HTML through the shared edge runtime.
+
+## 0.1.52-rc.35
+
+### Fixed
+
+- Next returns HTTP 404 for missing native assets and API endpoints that reach
+  the CMS catch-all without a routed release, including `/favicon.ico`, instead
+  of failing metadata and page rendering with a release-selection error.
+
+## 0.1.52-rc.34
+
+### Changed
+
+- The `dam-delivery` agent skill now says a future `expiresAt` is admitted to
+  public delivery and can be set, moved, or cleared on a public version; only
+  a past expiry vetoes approval or is refused on a public version.
+
+## 0.1.52-rc.33
+
+### Migration required
+
+- Next sites must set `registry` in `conformancePreset` (or
+  `runConformanceChecks`) to the render registry module used by their app, for
+  example `registry: 'src/cms/registry.ts'`. The default `rootIdentity` check
+  fails with configuration guidance when this option is absent. See
+  [the registry-selection migration](./migrations/conformance-registry.md).
+
+### Fixed
+
+- Next `rootIdentity` imports only the site's explicitly named registry. It no
+  longer executes arbitrary source files containing `createRegistry(` or
+  silently checks a secondary registry.
+
+## Unreleased
+
+**Public API removal:** `visitorProfileDataModel` is gone (see Removed
+below) — delete it from any imports.
+
+### Changed
+
+- The audience/experimentation author data models
+  (`packages/sdk/src/audience-data-models.ts`) are now generated from the Go
+  document readers' contracts (`scripts/generate-data-models.go`, verified in
+  CI by `make data-models-verify`) instead of hand-written. This fixes drift
+  toward the server contract: `experimentDataModel` gains `horizon` (with the
+  ADR 0042/0049 constraints), `promotedArmId`/`promotedAt`, and the
+  `eligibility.audienceRef` `$ref:audiences/{id}` grammar; rule and goal
+  expressions support nested all/any groups with the kernel's depth and
+  condition budgets; goal `eventRule` validates in event scope; segment
+  criteria accept the `geo` filter; providers require
+  `identity.absencePolicy` and enforce the format↔mapping matrix; ids use the
+  shared identifier grammar.
+
+### Fixed
+
+- The `dam-delivery` agent skill shipped in the site templates described two
+  delivery lanes that no longer exist (signed `/dam/i/…` URLs and `/dam/a/…`
+  permalinks). It now describes the one public link, `/dam/{assetId}`, and
+  its `w`, `h`, `fit`, `fm`, `q` query. A site scaffolded earlier keeps its
+  old copy: replace its `.agents/skills/dam-delivery/` with
+  `templates/common/.agents/skills/dam-delivery/` from this package.
+
+### Removed
+
+- `visitorProfileDataModel`: the schema had no server-side document contract
+  and no consumers. Drop it from imports; `audienceDataModels` no longer
+  includes it.
+
 ## 0.1.52-rc.7 - 2026-08-19
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.52-rc.7` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.52` 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.52-rc.7 zod@^4
+npm install @gradial/aci@0.1.52 zod@^4
 ```
 
 ## Root Import
@@ -62,6 +62,65 @@ export default withAci(nextConfig, {
 
 Astro public subpath is `@gradial/aci/astro`.
 
+## Page Templates
+
+Pages use content-authored templates for region order, defaults, composition
+rules, and personalization locks. Start with the [page templates guide](docs/page-templates.md),
+including the `blog_body` contract pattern for page-specific container children.
+[Component contracts](docs/component-contracts.md) define props and nested block types.
+
+## Block Root Identity
+
+The renderer passes every block two props, `data-aci-block` (the authored
+block id) and `data-aci-component`. A component extends `RootIdentityProps`
+and spreads the rest of its props onto its root element, so analytics can join
+events to content by (page path, block id):
+
+```tsx
+import type { RootIdentityProps } from '@gradial/aci';
+
+export function StatsBar({ stats = [], ...root }: ContentProps & RootIdentityProps) {
+  return <section {...root} className="…">…</section>;
+}
+```
+
+Three checks make this required: `createRegistry` fails typecheck for a
+component whose props type lacks the keys, the default `rootIdentity`
+conformance check renders every registered component and fails when the root
+lacks the attributes, and publish rejects a release whose rendered HTML is
+missing a block id. `runConformanceChecks` is async; `await` it before reading
+`.passed`.
+
+## Mintlify
+
+`@gradial/aci/mintlify` is the Mintlify adapter used automatically by the ACI
+CLI. Mintlify remains the renderer; ACI owns the standard `.content` tree.
+Documents use stable ACI component IDs and an
+ordered recursive block tree: Markdown slices for prose, typed nested Mintlify
+components and stable accessibility-safe anchors for common structures, and
+explicit `mintlify.mdx` nodes for native syntax that has not been promoted to a
+typed contract.
+
+The source tree may also contain independently governed snippets, recursive
+`docs.json` `$ref` fragments, and OpenAPI, AsyncAPI, or GraphQL descriptions:
+
+```text
+.content/
+  config/site.json
+  config/mintlify.json
+  pages/**/_index.json
+  fragments/**/_index.json
+```
+
+```bash
+aci content compile
+```
+
+See `starters/mintlify/` for the smallest runnable site. `.aci.yaml` selects
+`framework: mintlify`; no renderer or validation flag is needed. The command
+validates the graph and writes the native project to
+`.aci/compiled/renderers/mintlify/` beside the ordinary compiled manifest.
+
 ## Build-Time Content Provider
 
 The file provider reads compiler output while generating complete static pages:
@@ -78,13 +137,13 @@ host bundles select and serve immutable release artifacts.
 The first RC scaffold path is Next:
 
 ```bash
-npx @gradial/aci@0.1.52-rc.7 init my-site --template next-starter
+npx @gradial/aci@0.1.52 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.52-rc.7 init --list
+npx @gradial/aci@0.1.52 init --list
 ```
 
 ## Personalization: The One-Tag Install
@@ -107,7 +166,7 @@ Tag attributes (the tag is the only per-site configuration surface):
 
 | Attribute | Meaning |
 | --- | --- |
-| `data-aci-consent` | CMP preset: `c15t`, `onetrust`, `cookiebot`, `trustarc`, or `manual` (default `manual` — only the JS consent API `aci('consent', …)` writes envelopes) |
+| `data-aci-consent` | CMP preset: `c15t`, `onetrust`, `cookiebot`, `trustarc`, or `manual` (default `manual` — only the JS consent API `aci('consent', …)` writes envelopes). A CMP preset tells the SDK the CMP will decide: until it writes consent, a first-time visitor's events (the exposure and page view included) wait in page memory, are sent once consent is granted, and are dropped on denial or when the page closes undecided. Only name a preset whose CMP is actually wired. Under `manual`, ACI's own consent banner (`ConsentBanner.astro`) plays that role: while it awaits the visitor, first views are held the same way. |
 | `data-aci-consent-categories` | Flat comma list of CMP categories that imply the personalization purpose (e.g. `measurement,marketing`); each preset ships a sane default |
 | `data-aci-site` | Optional site ID, debug only — the edge binding is the site authority |
 | `data-aci-debug` | `1` enables structured `console.debug` diagnostics |
@@ -134,6 +193,28 @@ has no Astro UI package, so the Astro kit ships the bridge only (in
 `@c15t/react`) or any setup built on c15t's store and the bridge picks it
 up; until then only the `manual` JS consent API writes envelopes.
 
+### Client-side navigation and experiment attribution
+
+Next `createPage` includes the completion hook. Custom Next pages must render
+`<AssignmentsScript page={page} />` on every page, including pages without
+experiments. Astro client routing uses `astro:page-load` after the document swap.
+Rebuild sites using the SDK framework integration when upgrading this contract.
+
+For another client router, call this command after committing the destination
+page. Pass the new page's complete assignment set, or `[]` for a base page:
+
+```js
+window.aci('navigation-complete', {
+  url: window.location.href,
+  assignments: page.experiments ?? [],
+});
+```
+
+Changing the URL immediately clears attribution. Events during the transition
+carry no experiment context; the completion hook emits the new exposures and
+page view before subsequent conversions. Query changes count as navigation;
+hash-only changes and duplicate completions do not create another page view.
+
 ## Verify Locally
 
 From `packages/sdk`:

package/dist/astro/error-page.js

@@ -50,6 +50,7 @@ export async function getErrorPageData(astro, kind, options = {}) {
         if (resolved.route) {
             const slug = resolved.route.replace(/^\/+|\/+$/g, '');
             const data = await getPageData({
+                isPrerendered: astro.isPrerendered,
                 params: { slug },
                 request: astro.request,
                 url: astro.url,

package/dist/astro/index.js

@@ -61,6 +61,10 @@ export function createRenderChildren(registry) {
             if (hasBlockSlots) {
                 props.renderChildren = renderChildren;
             }
+            // sdk I-19 (ADR 0051): root identity props are applied last so content
+            // props cannot overwrite them. The template spreads them onto the root.
+            props['data-aci-block'] = block.id;
+            props['data-aci-component'] = block.component;
             return { Component: entry?.component, props };
         });
     }

package/dist/astro/page.d.ts

@@ -31,12 +31,13 @@
  * iterate slots and render blocks via the registry.
  */
 import type { KernelPage, KernelSiteConfig, KernelRouteMetadata, KernelPageBlock } from '../content/types.js';
-import type { LayoutEntry } from '../content/provider.js';
+import { type LayoutEntry } from '../content/provider.js';
 /**
  * Minimal Astro global shape — only the properties getPageData reads.
  * This avoids depending on Astro's own types at the SDK level.
  */
 export interface AstroGlobal {
+    isPrerendered?: boolean;
     params: {
         slug?: string;
     };
@@ -51,6 +52,8 @@ export interface AstroGlobal {
 export interface PageData {
     /** Route string (normalized, e.g. "/" or "/about"). */
     route: string;
+    /** Selected render tuple, including the explicit "base" identity. */
+    variantKey: string;
     /** Site configuration. */
     siteConfig: KernelSiteConfig;
     /** Page content. */
@@ -91,4 +94,4 @@ export interface GetPageDataOptions {
  * directly from CloudFront in production (the CDN points at the release
  * artifacts in S3, no runtime content fetching).
  */
-export declare function getPageData(astro: AstroGlobal, _options?: GetPageDataOptions): Promise<PageData>;
+export declare function getPageData(astro: AstroGlobal, options?: GetPageDataOptions): Promise<PageData>;

package/dist/astro/page.js

@@ -30,11 +30,12 @@
  * The page template receives a typed data object and only needs to
  * iterate slots and render blocks via the registry.
  */
+import { FragmentNotFoundError } from '../content/provider.js';
 import { normalizeRoute } from '../content/routes.js';
 import { routeMetadataForContent } from '../content/provider.js';
 import { resolveSlots } from '../content/resolve-slots.js';
 import { assignmentsScriptTagHTML, collectScriptTagHTML } from '../content/personalization.js';
-import { getPendingRenderInputFromHeaders } from '../runtime/page.js';
+import { GRADIAL_RENDER_INPUT_HEADER, getPendingRenderInputFromHeaders } from '../runtime/page.js';
 // ---------------------------------------------------------------------------
 // Implementation
 // ---------------------------------------------------------------------------
@@ -52,23 +53,25 @@ import { getPendingRenderInputFromHeaders } from '../runtime/page.js';
  * directly from CloudFront in production (the CDN points at the release
  * artifacts in S3, no runtime content fetching).
  */
-export async function getPageData(astro, _options) {
+export async function getPageData(astro, options) {
     const route = normalizeRoute(astro.params.slug ? `/${astro.params.slug}` : '/');
-    // Check for preview render input first (same as Next.js tier 1)
-    // Skip during prerender/static generation — request.headers is not available
+    // Static Astro generation is explicit; unexpected header access errors and
+    // expired render-input IDs must not turn a selected variant into local base.
     let runtimeInput = null;
-    try {
-        runtimeInput = getPendingRenderInputFromHeaders(astro.request.headers);
-    }
-    catch {
-        // Astro throws when accessing request.headers during prerender — this is
-        // expected and harmless; preview mode is a request-time concern.
+    if (!astro.isPrerendered) {
+        const headers = astro.request.headers;
+        runtimeInput = getPendingRenderInputFromHeaders(headers);
+        if (headers.has(GRADIAL_RENDER_INPUT_HEADER) && !runtimeInput) {
+            throw new Error(`ACI Astro render input is unavailable for route ${route}; refusing to render local base content`);
+        }
     }
     let siteConfig;
     let page;
     let providerModule = null;
     let provider = null;
+    let variantKey;
     if (runtimeInput) {
+        variantKey = requireVariantKey(runtimeInput.variantKey, route);
         siteConfig = runtimeInput.siteConfig;
         page = runtimeInput.page;
     }
@@ -76,19 +79,23 @@ export async function getPageData(astro, _options) {
         // Lazy-import FileContentProvider to avoid pulling it in when
         // preview render input is available
         providerModule = await import('../providers/file.js');
-        provider = new providerModule.FileContentProvider();
+        provider = new providerModule.FileContentProvider(options?.compiledRoot);
         [siteConfig, page] = await Promise.all([
             provider.getSiteConfig(),
             provider.getPage(route),
         ]);
+        const entry = (await provider.listRoutes()).find((entry) => normalizeRoute(entry.path) === route);
+        variantKey = requireVariantKey(entry?.variantKey, route);
     }
     const meta = routeMetadataForContent(siteConfig, page);
     // Resolve layout: prefer render input, fall back to provider
-    const layout = await resolveLayout(runtimeInput, provider, providerModule, page.layout);
+    const layout = await resolveLayout(runtimeInput, provider, page.layout, route);
     // Resolve slots: page regions filled, then layout fragment defaults
     const slots = await resolveSlots(layout, page?.regions || {}, async (id) => {
-        if (runtimeInput?.fragments?.[id]) {
-            return runtimeInput.fragments[id];
+        if (runtimeInput) {
+            if (Object.hasOwn(runtimeInput.fragments ?? {}, id))
+                return runtimeInput.fragments[id];
+            throw new FragmentNotFoundError(id, new Error('fragment is not bound by the selected page'));
         }
         const p = provider ?? new (await import('../providers/file.js')).FileContentProvider();
         return await p.getFragment(id);
@@ -97,22 +104,27 @@ export async function getPageData(astro, _options) {
     const isPreview = astro.url.searchParams.has('preview_token');
     const collectTag = isPreview ? '' : collectScriptTagHTML(siteConfig);
     const assignmentsTag = isPreview ? '' : assignmentsScriptTagHTML(page);
-    return { route, siteConfig, page, meta, layout, slots, collectTag, assignmentsTag };
+    return { route, variantKey, siteConfig, page, meta, layout, slots, collectTag, assignmentsTag };
+}
+function requireVariantKey(value, route) {
+    if (typeof value !== 'string' || !value.trim() || value !== value.trim()) {
+        throw new Error(`ACI Astro render variant identity is missing or invalid for route ${route}; supply an explicit variantKey ("base" for an unpersonalized render)`);
+    }
+    return value;
 }
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
-async function resolveLayout(runtimeInput, provider, providerModule, layoutName) {
-    // Check render input first
-    if (runtimeInput?.layouts?.[layoutName]) {
-        return runtimeInput.layouts[layoutName];
+async function resolveLayout(runtimeInput, provider, layoutName, route) {
+    if (runtimeInput) {
+        const layout = runtimeInput.layouts?.[layoutName];
+        if (!layout)
+            throw new Error(`ACI Astro render input for route ${route} is missing its selected layout ${JSON.stringify(layoutName)}`);
+        return layout;
     }
     // Fall back to provider
     if (provider) {
         return await provider.getLayout(layoutName);
     }
-    // Last resort: create a new provider
-    const mod = providerModule ?? await import('../providers/file.js');
-    const p = new mod.FileContentProvider();
-    return await p.getLayout(layoutName);
+    throw new Error(`ACI Astro content provider is unavailable for route ${route}`);
 }

package/dist/astro/preview.js

@@ -1,9 +1,9 @@
-import { extractPreviewToken, resolvePreviewContext, createPreviewBannerHTML as coreCreatePreviewBannerHTML, createPreviewCookies as coreCreatePreviewCookies, previewSignKey, } from '../preview/core.js';
+import { extractPreviewToken, parseCookies, resolvePreviewContext, createPreviewBannerHTML as coreCreatePreviewBannerHTML, createPreviewCookies as coreCreatePreviewCookies, previewSignKey, } from '../preview/core.js';
 export async function getPreviewMode(request, siteId) {
     const url = new URL(request.url);
     const token = extractPreviewToken({
         query: url.searchParams,
-        cookies: parseCookieHeader(request.headers.get('cookie') || ''),
+        cookies: parseCookies(request.headers.get('cookie') || ''),
         authorization: request.headers.get('authorization') || undefined,
     });
     if (!token)
@@ -16,18 +16,3 @@ export function createPreviewBannerHTML(releaseId) {
 export function createPreviewCookies(token, releaseId) {
     return coreCreatePreviewCookies(token, releaseId);
 }
-function parseCookieHeader(header) {
-    const cookies = new Map();
-    for (const part of header.split(';')) {
-        const trimmed = part.trim();
-        if (!trimmed)
-            continue;
-        const idx = trimmed.indexOf('=');
-        if (idx < 0)
-            continue;
-        const name = trimmed.slice(0, idx).trim();
-        const value = trimmed.slice(idx + 1).trim();
-        cookies.set(name, decodeURIComponent(value));
-    }
-    return cookies;
-}