@gradial/aci 0.1.52-rc.9 → 0.1.52

package/dist/content/resolve-slots.js

@@ -1,26 +1,132 @@
-export async function resolveSlots(layout, pageRegions, getFragment) {
-    const resolved = {};
-    for (const slot of layout.slots) {
-        const pageBlocks = pageRegions[slot.name];
-        if (pageBlocks && pageBlocks.length > 0) {
-            resolved[slot.name] = pageBlocks;
-            continue;
+/**
+ * Shared Go/TS limit contract (sdk I-21). These values are pinned against
+ * internal/domain/content/compiler/testdata/limit-conformance.v1.json by
+ * limit-conformance.test.ts (TS) and limit_conformance_test.go (Go); the
+ * compiler's MaxFragmentDepth/MaxExpandedBlocks must match.
+ */
+/** Bounds a selected fragment reference chain, counting its root fragment. */
+export const MAX_FRAGMENT_DEPTH = 10;
+/** Bounds rendered component occurrences per page, including repeated placements. */
+export const MAX_EXPANDED_BLOCKS = 4096;
+/** Failures in a selected fragment are never eligible for local-content fallback. */
+export class FragmentResolutionError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'FragmentResolutionError';
+    }
+}
+// Runtime-only provenance keeps each fragment placement's authored IDs in its
+// own validation scope. It is never emitted into compiled JSON or HTML.
+export const fragmentRootScope = Symbol('aci.fragment-root-scope');
+export function preserveFragmentScope(source, target) {
+    return Object.hasOwn(source, fragmentRootScope)
+        ? Object.defineProperty(target, fragmentRootScope, { value: true })
+        : target;
+}
+export async function resolveSlots(plan, pageRegions, getFragment) {
+    return resolveAsync(walkSlots(plan, pageRegions), getFragment);
+}
+/** The config-time error seat uses the identical traversal with synchronous file reads. */
+export function resolveSlotsSync(plan, pageRegions, getFragment) {
+    const walk = walkSlots(plan, pageRegions);
+    let step = walk.next();
+    while (!step.done) {
+        let fragment;
+        try {
+            fragment = getFragment(step.value);
         }
-        const defaults = layout.defaults?.[slot.name];
-        if (defaults?.length) {
-            const blocks = [];
-            for (const ref of defaults) {
-                const fragment = await getFragment(ref.fragmentId);
-                const block = fragment.block ?? { component: fragment.component ?? '', props: fragment.props };
-                blocks.push({
-                    $type: 'component',
-                    id: fragment.id ?? fragment.fragmentId ?? ref.fragmentId,
-                    component: block.component,
-                    props: block.props || {},
-                });
-            }
-            resolved[slot.name] = blocks;
+        catch (cause) {
+            throw bindingError(step.value, cause);
         }
+        step = walk.next(fragment);
+    }
+    return step.value;
+}
+/** Resolve compiled references through the exact fragment bindings selected for this page. */
+export async function resolveFragmentNodes(nodes, getFragment) {
+    return resolveAsync(walkNodes(nodes, { blocks: 0 }), getFragment);
+}
+async function resolveAsync(walk, getFragment) {
+    let step = walk.next();
+    while (!step.done) {
+        let fragment;
+        try {
+            fragment = await getFragment(step.value);
+        }
+        catch (cause) {
+            throw bindingError(step.value, cause);
+        }
+        step = walk.next(fragment);
+    }
+    return step.value;
+}
+function bindingError(id, cause) {
+    return new FragmentResolutionError(`ACI fragment ${id} selected binding failed: ${String(cause)}`, { cause });
+}
+function* walkSlots(plan, pageRegions) {
+    const resolved = {};
+    const state = { blocks: 0 };
+    for (const slot of plan.slots) {
+        const pageBlocks = pageRegions[slot.name];
+        const nodes = pageBlocks?.length ? pageBlocks : plan.defaults?.[slot.name];
+        if (nodes?.length)
+            resolved[slot.name] = yield* walkNodes(nodes, state);
     }
     return resolved;
 }
+function* walkNodes(nodes, state) {
+    const blocks = [];
+    for (const node of nodes)
+        blocks.push((yield* walkValue(node, [], state)));
+    return blocks;
+}
+// Active ancestry belongs to each placement, while the block budget belongs to
+// the whole rendered page. A repeated fragment in another branch is valid.
+function* walkValue(value, ancestry, state) {
+    if (Array.isArray(value)) {
+        const result = [];
+        for (const child of value)
+            result.push(yield* walkValue(child, ancestry, state));
+        return result;
+    }
+    if (value === null || typeof value !== 'object')
+        return value;
+    const node = value;
+    if (node.kind === 'fragment-ref') {
+        const id = node.fragmentId;
+        if (typeof id !== 'string' || !id)
+            throw new FragmentResolutionError('ACI fragment reference has no fragmentId');
+        const chain = [...ancestry, id];
+        if (ancestry.includes(id))
+            throw new FragmentResolutionError(`ACI fragment cycle: ${chain.join(' -> ')}`);
+        if (chain.length > MAX_FRAGMENT_DEPTH)
+            throw new FragmentResolutionError(`ACI fragment depth exceeds ${MAX_FRAGMENT_DEPTH}: ${chain.join(' -> ')}`);
+        const fragment = yield id;
+        const block = (yield* walkValue(fragmentToBlock(fragment, id), chain, state));
+        return Object.defineProperty(block, fragmentRootScope, { value: true });
+    }
+    const isBlock = node.$type === 'component'
+        || (typeof node.component === 'string' && node.component.length > 0
+            && node.props !== null && typeof node.props === 'object' && !Array.isArray(node.props));
+    if (isBlock && ++state.blocks > MAX_EXPANDED_BLOCKS) {
+        throw new FragmentResolutionError(`ACI rendered page exceeds ${MAX_EXPANDED_BLOCKS} component blocks`);
+    }
+    const result = {};
+    for (const [key, child] of Object.entries(node))
+        result[key] = yield* walkValue(child, ancestry, state);
+    return preserveFragmentScope(node, result);
+}
+/** Use the same fragment root identity for layout defaults and region placements. */
+export function fragmentToBlock(fragment, id) {
+    const block = fragment?.block ?? fragment;
+    if (!block || typeof block.component !== 'string' || !block.component
+        || (block.props !== undefined && (typeof block.props !== 'object' || block.props === null || Array.isArray(block.props)))) {
+        throw new FragmentResolutionError(`ACI fragment ${id} has no component block`);
+    }
+    return {
+        $type: 'component',
+        id: fragment.id ?? fragment.fragmentId ?? id,
+        component: block.component,
+        props: block.props || {},
+    };
+}

package/dist/content/types.d.ts

@@ -1,4 +1,5 @@
 import type { ExperimentAssignmentContext, SitePersonalizationConfig } from './personalization.js';
+import type { FragmentRefNode } from '../types/page.js';
 export type ButtonVariant = 'primary' | 'secondary' | 'tertiary' | 'outline' | 'ghost';
 export interface KernelImage {
     src: string;
@@ -47,6 +48,7 @@ export interface KernelPageBlock {
     component: string;
     props: Record<string, unknown>;
 }
+export type KernelPageNode = KernelPageBlock | FragmentRefNode;
 export interface KernelAtomicBlock {
     $type: 'component';
     id: string;
@@ -59,7 +61,7 @@ export interface KernelPage {
     status: string;
     layout: string;
     metadata: KernelPageSeo;
-    regions: Record<string, KernelPageBlock[]>;
+    regions: Record<string, KernelPageNode[]>;
     /**
      * Build-time experiment assignment context (personalization-reporting
      * design/04); present only on experiment variant payloads. The starters
@@ -110,6 +112,8 @@ export interface KernelRouteMetadata {
 }
 export interface RenderInput<TPage extends KernelPage = KernelPage, TSiteConfig extends KernelSiteConfig = KernelSiteConfig> {
     route: string;
+    /** Selected render tuple. Unpersonalized renders explicitly use "base". */
+    variantKey: string;
     domain: string;
     locale: string;
     siteConfig: TSiteConfig;

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

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

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

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

package/dist/index.d.ts

@@ -1,10 +1,9 @@
 export { defineComponentContract } from './define-component.js';
-export { defineLayoutContract, slot, fragmentDefault } from './define-layout.js';
 export { createRegistry, registryLookup } from './registry.js';
 export type { Registry, RegistryEntry, AnyComponent } from './registry.js';
 export { blockRef, blockRefArray } from './types/block-ref.js';
 export type { BlockRef, BlockRefEntry, BlockRefMeta, BlockRefUnion } from './types/block-ref.js';
-export type { ComponentContract, ComponentContractID, ComponentContractValidator, ComponentRegistry, ComponentValidationContext, ComponentValidationIssue, InferComponentProps, } from './types/component.js';
+export type { ComponentContract, ComponentContractID, ComponentContractValidator, ComponentRegistry, ComponentValidationContext, ComponentValidationIssue, InferComponentProps, RootIdentityProps, } from './types/component.js';
 export { ImageSchema, imageAttrs, primaryImageSource, type Image, type ImageSource, type ImageAttrs, type ImageSlotContract, type SlotOutput, } from './types/image.js';
 export { LinkSchema, type Link, type LinkTarget, type LinkResolverContext, resolveLink, resolveHref, assertSafeHref, normalizeLinkRel, } from './types/link.js';
 export { HeadingSchema, InlineContentSchema, RichTextValueSchema, type Heading, type InlineContent, type RichTextValue, } from './types/rich-text.js';

package/dist/index.js

@@ -1,5 +1,4 @@
 export { defineComponentContract } from './define-component.js';
-export { defineLayoutContract, slot, fragmentDefault } from './define-layout.js';
 export { createRegistry, registryLookup } from './registry.js';
 export { blockRef, blockRefArray } from './types/block-ref.js';
 export { ImageSchema, imageAttrs, primaryImageSource, } from './types/image.js';

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

@@ -1,14 +1,57 @@
-import type { IdentitySigningKeys, SigningKey, CookieMutation, ConsentSnapshot, ConsentSignals } from './types.js';
+import type { IdentitySigningKeys, SigningKey, ConsentSnapshot, ConsentSignals } from './types.js';
 export declare const DEFAULT_IDENTITY_TTL_SECONDS: number;
 export declare function parseCookieHeader(value: string | null): Map<string, string>;
 export declare function consentSignals(request: Request, cookies: Map<string, string>): ConsentSignals;
+export declare function identityIssuancePermitted(consent: ConsentSignals, country: string, optOutCountries: readonly string[]): boolean;
 export declare function parseConsent(raw: string, decodeCookieValue?: boolean): ConsentSnapshot | null;
 export declare function trimConsentWhitespace(value: string): string;
 export declare function verifyIdentityCookie(value: string, keys: IdentitySigningKeys): Promise<string | null>;
 export declare function signIdentity(rawID: string, key: SigningKey): Promise<string>;
 export declare function randomIdentity(random?: (length: number) => Uint8Array): string;
 export declare function identityHashHex(namespace: string, value: string): Promise<string>;
-export declare function sha256Hex(value: string): Promise<string>;
 export declare function verifyClaims(value: string, keys: Record<string, string>, now: Date): Promise<Record<string, unknown> | null>;
-export declare function cookieMutation(name: string, value: string, maxAge: number, now: Date, secure: boolean, httpOnly: boolean): CookieMutation;
-export declare function expireCookie(name: string, secure: boolean): CookieMutation;
+export declare function verifyClaimsEvidence(value: string, keys: Record<string, string>, now: Date): Promise<Record<string, unknown> | null>;
+/**
+ * The minting path that signed an aci_claims value: 'aci' claims contain
+ * first-party memberships only; 'edge' claims are the minted first-party ∪
+ * external union and require a matching live b2 receipt on a
+ * provider-enabled release.
+ */
+export type ClaimsIssuer = 'aci' | 'edge';
+/**
+ * Exposes the payload's `iss` marker. Malformed/unknown markers — and
+ * pre-0059 unmarked payloads — yield undefined; since the §6 cutover,
+ * verifyClaims rejects those payloads outright, so a verified payload always
+ * carries a marker. The marker identifies the minting path; it does not
+ * grant membership by itself.
+ */
+export declare function claimsIssuer(payload: Record<string, unknown> | null): ClaimsIssuer | undefined;
+/** audience.MaxClaimsCookieBytes — the hard 1 KiB aci_claims budget. */
+export declare const MAX_CLAIMS_COOKIE_BYTES = 1024;
+/** audience.DefaultClaimsTTL — the 24-hour signed-lifetime ceiling. */
+export declare const DEFAULT_CLAIMS_TTL_SECONDS: number;
+/**
+ * Mint rejection: oversize, a malformed key, or a missing issuer marker.
+ * Callers fail closed on it — the edge never truncates or subsets
+ * memberships to fit (ADR 0059 §2/§3).
+ */
+export declare class ClaimsMintError extends Error {
+    readonly name = "ClaimsMintError";
+}
+/**
+ * Mints one signed aci_claims value: v1.{kid}.{base64url(payload)}.{hmac},
+ * byte-identical to Go's ClaimsIssuer.IssueClaims — payload field order is
+ * aud (omitted when empty), seg (omitted when empty), iat, exp, iss, and the
+ * TTL clamps to the 24-hour ceiling. The exact bytes are pinned against the
+ * Go golden in claims_contract.test.ts. Issuance requires an explicit issuer
+ * marker; the marker identifies the minting path, it does not grant
+ * membership by itself.
+ */
+export declare function issueClaims(memberships: {
+    aud?: string[];
+    seg?: string[];
+}, issuer: ClaimsIssuer, key: SigningKey, now: Date, ttlSeconds?: number): Promise<string>;
+export declare function verifyHMAC(value: string, signature: string, secret: string): Promise<boolean>;
+export declare function hmacSHA256(value: string, secret: string): Promise<string>;
+export declare function base64URLEncode(bytes: Uint8Array): string;
+export declare function base64URLDecode(value: string): Uint8Array;