@gradial/aci 0.1.52-rc.8 → 0.1.52

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[];
@@ -26,20 +33,6 @@ export interface EdgeRouteEntry {
     dispatch: EdgeDispatch;
     variants?: Record<string, EdgeRouteVariant>;
 }
-export interface CollectSDKEntry {
-    hash: string;
-    path: string;
-}
-export interface EdgeRouteManifest {
-    manifestVersion: string;
-    releaseId: string;
-    siteId: string;
-    routes: Record<string, EdgeRouteEntry>;
-    experiments?: Record<string, PersonalizationExperiment>;
-    collectSdk?: CollectSDKEntry;
-    notFoundPage?: string;
-    errorPage?: string;
-}
 export interface PersonalizationRequestContext {
     path: string;
     query: Record<string, string[]>;
@@ -48,9 +41,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 +72,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 +83,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 +110,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;
@@ -120,18 +127,6 @@ export interface IdentitySigningKeys {
     current: SigningKey;
     previous?: SigningKey;
 }
-export interface CookieMutation {
-    name: string;
-    value: string;
-    options: {
-        path: '/';
-        httpOnly?: boolean;
-        secure?: boolean;
-        sameSite: 'lax';
-        maxAge: number;
-        expires?: Date;
-    };
-}
 export interface ConsentSnapshot {
     version: number;
     purposes: string[];
@@ -145,20 +140,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,24 +150,47 @@ 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;
-    };
-}
-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;
+        /** audience-mimic design/09: the assignment came from the token, not the dice. */
+        forced?: boolean;
+    }>;
 }
 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,4 @@
+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>;
+export declare function variantValuesFromKey(key: string): Record<string, string>;

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

@@ -0,0 +1,56 @@
+// 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;
+}
+// Lenient reader for a route record's variant key when the record carries no
+// variantValues. Unlike parseVariantKey it never throws and also accepts `&`
+// as a separator, so it is not interchangeable with the canonical parser.
+export function variantValuesFromKey(key) {
+    const values = {};
+    for (const part of String(key || '').replace(/&/g, ';').split(';')) {
+        const sep = part.indexOf('=');
+        if (sep > 0)
+            values[part.slice(0, sep).trim()] = part.slice(sep + 1).trim();
+    }
+    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/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;

package/dist/mintlify/blocks.js

@@ -0,0 +1,201 @@
+import { fragmentRootScope, preserveFragmentScope } from '../content/resolve-slots.js';
+import { cleanFilePath, isMintlifyJSONValue, isObject, nonEmptyString } from './json.js';
+const GENERATED_MARKER = '{/* Generated by @gradial/aci; edit .content instead. */}';
+const SUPPORTED_COMPONENTS = new Set([
+    'mintlify.markdown', 'mintlify.mdx', 'mintlify.anchor', 'mintlify.steps', 'mintlify.step',
+    'mintlify.card-group', 'mintlify.card', 'mintlify.accordion-group',
+    'mintlify.accordion', 'mintlify.callout', 'mintlify.tabs', 'mintlify.tab',
+    'mintlify.snippet-ref',
+]);
+export function renderDocument(document) {
+    const frontmatter = [`title: ${JSON.stringify(document.metadata.title)}`];
+    if (document.metadata.description)
+        frontmatter.push(`description: ${JSON.stringify(document.metadata.description)}`);
+    if (document.metadata.mintlify?.sidebarTitle)
+        frontmatter.push(`sidebarTitle: ${JSON.stringify(document.metadata.mintlify.sidebarTitle)}`);
+    if (document.metadata.mintlify?.icon)
+        frontmatter.push(`icon: ${JSON.stringify(document.metadata.mintlify.icon)}`);
+    for (const [key, value] of Object.entries(document.metadata.mintlify?.frontmatter ?? {}).sort(([left], [right]) => left.localeCompare(right))) {
+        frontmatter.push(`${key}: ${JSON.stringify(value)}`);
+    }
+    return `---\n${frontmatter.join('\n')}\n---\n\n${GENERATED_MARKER}\n\n${renderContent(document.regions.main)}`;
+}
+export function renderSnippet(snippet) {
+    return `${GENERATED_MARKER}\n\n${renderContent([snippet.block])}`;
+}
+function renderContent(blocks) {
+    const aliases = snippetAliases(blocks);
+    const imports = [...aliases].map(([snippetPath, alias]) => `import ${alias} from "/${snippetPath}";`).join('\n');
+    const body = renderBlocks(blocks, 0, aliases).replace(/\n*$/, '\n');
+    return imports ? `${imports}\n\n${body}` : body;
+}
+function renderBlocks(blocks, indentation, aliases) {
+    return blocks.map((block) => renderBlock(block, indentation, aliases)).join('\n\n');
+}
+function renderBlock(block, indentation, aliases) {
+    const prefix = ' '.repeat(indentation);
+    if (block.component === 'mintlify.markdown' || block.component === 'mintlify.mdx')
+        return indentSource(block.props.source, indentation);
+    if (block.component === 'mintlify.anchor')
+        return `${prefix}<span id="${escapeAttribute(block.props.name)}"></span>`;
+    if (block.component === 'mintlify.snippet-ref') {
+        const snippetPath = block.props.path;
+        const alias = aliases.get(snippetPath);
+        const values = block.props.values;
+        const attributes = Object.entries(values).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => renderAttribute(key, value)).join('');
+        return `${prefix}<${alias}${attributes} />`;
+    }
+    const children = block.props.children ?? [];
+    const tag = nativeComponentName(block);
+    const attributes = Object.entries(block.props)
+        .filter(([key]) => key !== 'children' && key !== 'variant')
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, value]) => renderAttribute(key, value))
+        .join('');
+    if (children.length === 0)
+        return `${prefix}<${tag}${attributes}>\n${prefix}</${tag}>`;
+    return `${prefix}<${tag}${attributes}>\n${renderBlocks(children, indentation + 2, aliases)}\n${prefix}</${tag}>`;
+}
+function snippetAliases(blocks) {
+    const aliases = new Map();
+    visitBlocks(blocks, (block) => {
+        if (block.component !== 'mintlify.snippet-ref')
+            return;
+        const snippetPath = block.props.path;
+        if (!aliases.has(snippetPath))
+            aliases.set(snippetPath, `AciSnippet${aliases.size + 1}`);
+    });
+    return aliases;
+}
+function nativeComponentName(block) {
+    if (block.component === 'mintlify.callout') {
+        const variant = block.props.variant;
+        return variant[0].toUpperCase() + variant.slice(1);
+    }
+    return block.component.slice('mintlify.'.length).split('-').map((part) => part[0].toUpperCase() + part.slice(1)).join('');
+}
+function renderAttribute(key, value) {
+    if (value === true)
+        return ` ${key}`;
+    if (typeof value === 'string')
+        return ` ${key}="${escapeAttribute(value)}"`;
+    return ` ${key}={${JSON.stringify(value)}}`;
+}
+function escapeAttribute(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}
+function indentSource(source, indentation) {
+    const normalized = source.replace(/\r\n/g, '\n').replace(/^\n+|\n+$/g, '');
+    const prefix = ' '.repeat(indentation);
+    return normalized.split('\n').map((line) => line.length > 0 ? `${prefix}${line}` : '').join('\n');
+}
+export function validateBlock(value, label, ids) {
+    if (!isObject(value) || value.$type !== 'component' || !nonEmptyString(value.id) || !nonEmptyString(value.component) || !isObject(value.props)) {
+        throw new Error(`ACI Mintlify block is invalid: ${label}`);
+    }
+    if (Object.hasOwn(value, fragmentRootScope))
+        ids = new Set();
+    if (ids.has(value.id))
+        throw new Error(`ACI Mintlify block ID is duplicated: ${value.id}`);
+    ids.add(value.id);
+    if (!SUPPORTED_COMPONENTS.has(value.component))
+        throw new Error(`ACI Mintlify component is unsupported: ${value.component}`);
+    const props = {};
+    for (const [key, entry] of Object.entries(value.props)) {
+        if (key === 'children') {
+            if (!Array.isArray(entry))
+                throw new Error(`ACI Mintlify block children are invalid: ${label}`);
+            props.children = entry.map((child, index) => validateBlock(child, `${label}.props.children[${index}]`, ids));
+        }
+        else if (!isMintlifyJSONValue(entry)) {
+            throw new Error(`ACI Mintlify block property is invalid: ${label}.${key}`);
+        }
+        else {
+            props[key] = entry;
+        }
+    }
+    validateComponentProps(value.component, props, label);
+    return preserveFragmentScope(value, { $type: 'component', id: value.id, component: value.component, props });
+}
+function validateComponentProps(component, props, label) {
+    if (component === 'mintlify.markdown' || component === 'mintlify.mdx') {
+        if (typeof props.source !== 'string' || props.children !== undefined)
+            throw new Error(`ACI Mintlify source block is invalid: ${label}`);
+        return;
+    }
+    if (component === 'mintlify.anchor') {
+        if (typeof props.name !== 'string' || !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(props.name) || Object.keys(props).some((key) => key !== 'name')) {
+            throw new Error(`ACI Mintlify anchor is invalid: ${label}`);
+        }
+        return;
+    }
+    if (component === 'mintlify.snippet-ref') {
+        if (!nonEmptyString(props.path) || cleanFilePath(props.path, '.mdx') !== props.path || !isObject(props.values) || !isMintlifyJSONValue(props.values) || props.children !== undefined) {
+            throw new Error(`ACI Mintlify snippet reference is invalid: ${label}`);
+        }
+        return;
+    }
+    if (!Array.isArray(props.children))
+        throw new Error(`ACI Mintlify component children are required: ${label}`);
+    if (component === 'mintlify.callout' && !['info', 'warning', 'note', 'tip', 'check'].includes(String(props.variant))) {
+        throw new Error(`ACI Mintlify callout variant is invalid: ${label}`);
+    }
+    if (['mintlify.step', 'mintlify.card', 'mintlify.accordion', 'mintlify.tab'].includes(component) && !nonEmptyString(props.title)) {
+        throw new Error(`ACI Mintlify component title is required: ${label}`);
+    }
+    const expectedChild = component === 'mintlify.steps' ? 'mintlify.step'
+        : component === 'mintlify.card-group' ? 'mintlify.card'
+            : component === 'mintlify.accordion-group' ? 'mintlify.accordion'
+                : component === 'mintlify.tabs' ? 'mintlify.tab'
+                    : undefined;
+    if (expectedChild && props.children?.some((child) => child.component !== expectedChild))
+        throw new Error(`ACI Mintlify ${component} child is invalid: ${label}`);
+}
+export function visitBlocks(blocks, visit) {
+    for (const block of blocks) {
+        visit(block);
+        if (block.props.children)
+            visitBlocks(block.props.children, visit);
+    }
+}
+function snippetReferences(blocks) {
+    const references = [];
+    visitBlocks(blocks, (block) => {
+        if (block.component === 'mintlify.snippet-ref')
+            references.push(block.props.path);
+    });
+    return references;
+}
+export function validateSnippetReferences(documents, snippets) {
+    const byPath = new Map();
+    for (const snippet of snippets) {
+        if (byPath.has(snippet.path))
+            throw new Error(`ACI Mintlify snippet path is duplicated: ${snippet.path}`);
+        byPath.set(snippet.path, snippet);
+    }
+    for (const document of documents) {
+        for (const reference of snippetReferences(document.regions.main)) {
+            if (!byPath.has(reference))
+                throw new Error(`ACI Mintlify snippet reference is missing: ${reference}`);
+        }
+    }
+    const visited = new Set();
+    const visiting = new Set();
+    const walk = (snippetPath) => {
+        if (visited.has(snippetPath))
+            return;
+        if (visiting.has(snippetPath))
+            throw new Error(`ACI Mintlify snippet reference cycle includes: ${snippetPath}`);
+        visiting.add(snippetPath);
+        const snippet = byPath.get(snippetPath);
+        for (const reference of snippetReferences([snippet.block])) {
+            if (!byPath.has(reference))
+                throw new Error(`ACI Mintlify snippet reference is missing: ${reference}`);
+            walk(reference);
+        }
+        visiting.delete(snippetPath);
+        visited.add(snippetPath);
+    };
+    for (const snippetPath of byPath.keys())
+        walk(snippetPath);
+}

package/dist/mintlify/config.d.ts

@@ -0,0 +1,3 @@
+import type { MintlifyConfigFragment, MintlifyJSONValue, MintlifySite } from './types.js';
+export declare function toDocsJSON(site: MintlifySite): Record<string, unknown>;
+export declare function resolveConfigReferences(configuration: MintlifyJSONValue, fragments: MintlifyConfigFragment[]): MintlifyJSONValue;