@createcms/core 0.1.1

package/dist/plugins/ab-test/index.cjs

@@ -0,0 +1,3400 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var nanoid$1 = require('nanoid');
+var drizzleOrm = require('drizzle-orm');
+var betterCall = require('better-call');
+var z = require('zod');
+var pgCore = require('drizzle-orm/pg-core');
+var slugify = require('slugify');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return n;
+}
+
+var z__namespace = /*#__PURE__*/_interopNamespace(z);
+var slugify__default = /*#__PURE__*/_interopDefault(slugify);
+
+const nanoid = nanoid$1.customAlphabet('0123456789abcdefghijklmnopqrstuvwxyz', 20);
+const prefixes = {
+    root: 'rot',
+    commit: 'cmt',
+    branch: 'brn',
+    blockVersion: 'blv',
+    block: 'blk',
+    mergeRequest: 'mrq',
+    mergeConflict: 'mcf',
+    approval: 'apr',
+    assetFolder: 'afl',
+    asset: 'ast',
+    contentUsage: 'cus',
+    commentThread: 'cth',
+    commentMessage: 'cmg',
+    commentMention: 'cmn',
+    variable: 'var',
+    template: 'tpl',
+    tplVarUsage: 'tvu',
+    notification: 'ntf',
+    si: 'sid',
+    redirect: 'rdr'
+};
+const customPrefixes = new Map();
+function registerIdPrefix(key, prefix) {
+    if (key in prefixes) {
+        throw new Error(`Cannot override core prefix "${key}"`);
+    }
+    if (prefix.length < 2 || prefix.length > 5) {
+        throw new Error(`Prefix "${prefix}" must be 2-5 characters`);
+    }
+    if (!/^[a-z]+$/.test(prefix)) {
+        throw new Error(`Prefix "${prefix}" must be lowercase letters only`);
+    }
+    customPrefixes.set(key, prefix);
+}
+function newId(prefix) {
+    const resolved = prefixes[prefix] ?? customPrefixes.get(prefix);
+    if (!resolved) {
+        throw new Error(`Unknown ID prefix "${prefix}". Register it with registerIdPrefix() first.`);
+    }
+    return `${resolved}_${nanoid()}`;
+}
+
+function definePluginSchema(schema) {
+    return {
+        ...schema
+    };
+}
+
+const abTestStatus = {
+    enumName: 'ab_test_status',
+    values: [
+        'draft',
+        'running',
+        'paused',
+        'completed'
+    ]
+};
+const abTests = {
+    tableName: 'ab_tests',
+    indexPrefix: 'abt',
+    columns: {
+        id: {
+            type: 'text',
+            primaryKey: true,
+            defaultId: true,
+            defaultIdPrefix: 'abTest'
+        },
+        rootId: {
+            type: 'text',
+            notNull: true,
+            references: {
+                table: 'roots',
+                column: 'id',
+                onDelete: 'cascade'
+            }
+        },
+        collection: {
+            type: 'text',
+            notNull: true
+        },
+        name: {
+            type: 'text',
+            notNull: true
+        },
+        // The chosen conversion goal (M4): the block instance's trackingId
+        // (goalHandle) + the resolved wire name (goalEvent = the stored event_type
+        // counted as the conversion). Both nullable — a test may run goal-less and
+        // only measure impressions until a goal is picked.
+        goalHandle: {
+            type: 'text'
+        },
+        goalEvent: {
+            type: 'text'
+        },
+        status: {
+            type: {
+                enum: 'abTestStatus'
+            },
+            notNull: true,
+            default: {
+                kind: 'literal',
+                value: 'draft'
+            }
+        },
+        trafficPercentage: {
+            type: 'integer',
+            notNull: true,
+            default: {
+                kind: 'literal',
+                value: 100
+            }
+        },
+        startedAt: {
+            type: 'timestamp'
+        },
+        endedAt: {
+            type: 'timestamp'
+        },
+        createdBy: {
+            type: 'text'
+        },
+        createdAt: {
+            type: 'timestamp',
+            notNull: true,
+            defaultNow: true
+        },
+        updatedAt: {
+            type: 'timestamp',
+            notNull: true,
+            defaultNow: true
+        }
+    },
+    indexes: {
+        rootIdx: {
+            columns: [
+                'rootId'
+            ]
+        },
+        statusIdx: {
+            columns: [
+                'status'
+            ]
+        },
+        collectionIdx: {
+            columns: [
+                'collection'
+            ]
+        }
+    }
+};
+const abTestVariants = {
+    tableName: 'ab_test_variants',
+    indexPrefix: 'abv',
+    columns: {
+        id: {
+            type: 'text',
+            primaryKey: true,
+            defaultId: true,
+            defaultIdPrefix: 'abTestVariant'
+        },
+        testId: {
+            type: 'text',
+            notNull: true,
+            references: {
+                table: 'abTests',
+                column: 'id',
+                onDelete: 'cascade'
+            }
+        },
+        branchId: {
+            type: 'text',
+            notNull: true,
+            references: {
+                table: 'branches',
+                column: 'id'
+            }
+        },
+        name: {
+            type: 'text',
+            notNull: true
+        },
+        weight: {
+            type: 'integer',
+            notNull: true
+        },
+        isControl: {
+            type: 'boolean',
+            notNull: true,
+            default: {
+                kind: 'literal',
+                value: false
+            }
+        }
+    },
+    indexes: {
+        testIdx: {
+            columns: [
+                'testId'
+            ]
+        }
+    }
+};
+const coreTables = {
+    abTests,
+    abTestVariants
+};
+const defaultAdapterTables = {
+    abTestEvents: {
+        tableName: 'ab_test_events',
+        indexPrefix: 'abe',
+        columns: {
+            id: {
+                type: 'text',
+                primaryKey: true,
+                defaultId: true,
+                defaultIdPrefix: 'abTestEvent'
+            },
+            // Nullable: non-A/B analytics events (form_submit, page_view) carry no
+            // test/variant. A/B events still cascade-delete with their test/variant.
+            testId: {
+                type: 'text',
+                references: {
+                    table: 'abTests',
+                    column: 'id',
+                    onDelete: 'cascade'
+                }
+            },
+            variantId: {
+                type: 'text',
+                references: {
+                    table: 'abTestVariants',
+                    column: 'id',
+                    onDelete: 'cascade'
+                }
+            },
+            // Nullable: anonymous Pattern A events store NO identifier (the variant
+            // comes from the URL / variant-cookie). Only the consent-gated
+            // unique-visitor / GA4 path sets it.
+            visitorId: {
+                type: 'text'
+            },
+            eventType: {
+                type: 'text',
+                notNull: true
+            },
+            // Originating functional block instance (the author-assigned trackingId).
+            sourceHandle: {
+                type: 'text'
+            },
+            sourceType: {
+                type: 'text'
+            },
+            // Funnel grouping (M4): shared by the attempt + success legs of one
+            // interaction (a <TrackedForm> submit). Nullable — most events (impression,
+            // a plain click) carry none. Groups, does NOT dedup.
+            interactionId: {
+                type: 'text'
+            },
+            metadata: {
+                type: 'jsonb',
+                jsonType: 'Record<string, unknown>'
+            },
+            createdAt: {
+                type: 'timestamp',
+                notNull: true,
+                defaultNow: true
+            }
+        },
+        indexes: {
+            testEventIdx: {
+                columns: [
+                    'testId',
+                    'eventType'
+                ]
+            },
+            visitorIdx: {
+                columns: [
+                    'testId',
+                    'visitorId'
+                ]
+            },
+            interactionIdx: {
+                columns: [
+                    'testId',
+                    'interactionId'
+                ]
+            }
+        }
+    }
+};
+function buildSchema(adapter) {
+    const tables = {
+        ...coreTables,
+        ...adapter?.tables ?? defaultAdapterTables
+    };
+    return definePluginSchema({
+        tables,
+        enums: {
+            abTestStatus
+        }
+    });
+}
+
+function postgresAnalytics() {
+    let db;
+    return {
+        tables: defaultAdapterTables,
+        init (instance) {
+            db = instance;
+        },
+        async track (event) {
+            // Mint when no usable id is supplied. Guard against a blank id too: `??`
+            // would let "" through and a second "" would be swallowed by ON CONFLICT,
+            // silently dropping a distinct event.
+            const id = event.id && event.id.length > 0 ? event.id : newId('abTestEvent');
+            await db.execute(drizzleOrm.sql`
+        INSERT INTO cms.ab_test_events
+          (id, test_id, variant_id, visitor_id, event_type, source_handle, source_type, interaction_id, metadata, created_at)
+        VALUES (
+          ${id},
+          ${event.ab?.testId ?? null},
+          ${event.ab?.variantId ?? null},
+          ${event.visitorId ?? null},
+          ${event.name},
+          ${event.source?.handle ?? null},
+          ${event.source?.type ?? null},
+          ${event.interactionId ?? null},
+          ${event.metadata ? drizzleOrm.sql`${JSON.stringify(event.metadata)}::jsonb` : drizzleOrm.sql`NULL`},
+          ${event.timestamp}
+        )
+        ON CONFLICT (id) DO NOTHING
+      `);
+        },
+        async query (testId, options) {
+            const fromClause = options?.from ? drizzleOrm.sql` AND e.created_at >= ${options.from}` : drizzleOrm.sql``;
+            const toClause = options?.to ? drizzleOrm.sql` AND e.created_at <= ${options.to}` : drizzleOrm.sql``;
+            const rows = await db.execute(drizzleOrm.sql`
+        SELECT
+          e.variant_id,
+          v.name AS variant_name,
+          e.event_type,
+          COUNT(*)::int AS count,
+          COUNT(DISTINCT e.visitor_id)::int AS unique_visitors,
+          COUNT(DISTINCT e.interaction_id)::int AS distinct_interactions
+        FROM cms.ab_test_events e
+        INNER JOIN cms.ab_test_variants v ON v.id = e.variant_id
+        WHERE e.test_id = ${testId}
+          ${fromClause}
+          ${toClause}
+        GROUP BY e.variant_id, v.name, e.event_type
+        ORDER BY e.variant_id, e.event_type
+      `);
+            // Funnel attempts per variant: total distinct interaction ids (one per
+            // <TrackedForm> submit). NOT a sum of per-event distincts — an interaction
+            // appears in both its attempt + success legs, so it must be counted once.
+            const attemptRows = await db.execute(drizzleOrm.sql`
+        SELECT e.variant_id, COUNT(DISTINCT e.interaction_id)::int AS attempts
+        FROM cms.ab_test_events e
+        WHERE e.test_id = ${testId}
+          AND e.interaction_id IS NOT NULL
+          ${fromClause}
+          ${toClause}
+        GROUP BY e.variant_id
+      `);
+            const attemptsByVariant = new Map(attemptRows.rows.map((r)=>[
+                    r.variant_id,
+                    r.attempts
+                ]));
+            const variantMap = new Map();
+            for (const row of rows.rows){
+                let v = variantMap.get(row.variant_id);
+                if (!v) {
+                    v = {
+                        variantId: row.variant_id,
+                        variantName: row.variant_name,
+                        impressions: 0,
+                        conversions: 0,
+                        uniqueVisitors: 0,
+                        conversionRate: 0,
+                        attempts: attemptsByVariant.get(row.variant_id) ?? 0,
+                        completionRate: 0,
+                        eventBreakdown: {}
+                    };
+                    variantMap.set(row.variant_id, v);
+                }
+                v.eventBreakdown[row.event_type] = {
+                    count: row.count,
+                    uniqueVisitors: row.unique_visitors,
+                    distinctInteractions: row.distinct_interactions
+                };
+                if (row.event_type === 'impression') {
+                    v.impressions = row.count;
+                    v.uniqueVisitors = row.unique_visitors;
+                } else if (row.event_type === 'conversion') {
+                    v.conversions = row.count;
+                }
+            }
+            const variants = [
+                ...variantMap.values()
+            ];
+            for (const v of variants){
+                v.conversionRate = v.impressions > 0 ? Math.round(v.conversions / v.impressions * 10000) / 100 : 0;
+            }
+            return {
+                testId,
+                variants,
+                totalImpressions: variants.reduce((s, v)=>s + v.impressions, 0),
+                totalConversions: variants.reduce((s, v)=>s + v.conversions, 0)
+            };
+        }
+    };
+}
+
+const cms = pgCore.pgSchema('cms');
+const tsvectorColumn = pgCore.customType({
+    dataType () {
+        return 'tsvector';
+    }
+});
+const approvalStatusEnum = cms.enum("approval_status", [
+    "pending",
+    "approved",
+    "rejected"
+]);
+const assetStatusEnum = cms.enum("asset_status", [
+    "private",
+    "public"
+]);
+const commentMessageTypeEnum = cms.enum("comment_message_type", [
+    "comment",
+    "system"
+]);
+const commentSystemTypeEnum = cms.enum("comment_system_type", [
+    "threadResolved",
+    "threadReopened"
+]);
+const commentThreadStatusEnum = cms.enum("comment_thread_status", [
+    "open",
+    "resolved"
+]);
+const commentThreadTargetEnum = cms.enum("comment_thread_target", [
+    "mergeRequest",
+    "block"
+]);
+const conflictResolutionEnum = cms.enum("conflict_resolution", [
+    "source",
+    "target",
+    "manual"
+]);
+const contentUsageTargetEnum = cms.enum("content_usage_target", [
+    "asset",
+    "variable",
+    "reference"
+]);
+const mergeRequestStatusEnum = cms.enum("merge_request_status", [
+    "open",
+    "merged",
+    "closed"
+]);
+const notificationTypeEnum = cms.enum("notification_type", [
+    "mention",
+    "comment",
+    "threadResolved",
+    "approvalRequested",
+    "approvalApproved",
+    "approvalRejected",
+    "mergeRequestOpened",
+    "mergeRequestMerged",
+    "mergeRequestClosed",
+    "mergeRequestReopened",
+    "published",
+    "custom"
+]);
+const redirectEndpointTypeEnum = cms.enum("redirect_endpoint_type", [
+    "page",
+    "path"
+]);
+cms.table("approvals", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("approval")),
+    mergeRequestId: pgCore.text("merge_request_id").references(()=>mergeRequests.id, {
+        onDelete: "cascade"
+    }),
+    branchId: pgCore.text("branch_id").notNull().references(()=>branches.id),
+    commitId: pgCore.text("commit_id").notNull().references(()=>commits.id),
+    status: approvalStatusEnum("status").notNull().default("pending"),
+    requestedBy: pgCore.text("requested_by").notNull(),
+    requestedReviewer: pgCore.text("requested_reviewer").notNull(),
+    reviewedBy: pgCore.text("reviewed_by"),
+    message: pgCore.text("message"),
+    rejectionReason: pgCore.text("rejection_reason"),
+    reviewedAt: pgCore.timestamp("reviewed_at"),
+    createdAt: pgCore.timestamp("created_at").notNull().defaultNow(),
+    updatedAt: pgCore.timestamp("updated_at").notNull().defaultNow()
+}, (table)=>[
+        pgCore.index("approvals_mr_idx").on(table.mergeRequestId),
+        pgCore.index("approvals_branch_idx").on(table.branchId),
+        pgCore.index("approvals_branch_commit_idx").on(table.branchId, table.commitId),
+        pgCore.index("approvals_status_idx").on(table.status),
+        pgCore.index("approvals_requested_reviewer_idx").on(table.requestedReviewer),
+        pgCore.uniqueIndex("approvals_target_reviewer_unique").on(table.mergeRequestId, table.branchId, table.commitId, table.requestedReviewer)
+    ]);
+const assetFolders = cms.table("asset_folders", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("assetFolder")),
+    name: pgCore.text("name").notNull(),
+    parentId: pgCore.text("parent_id"),
+    createdBy: pgCore.text("created_by"),
+    createdAt: pgCore.timestamp("created_at").notNull().defaultNow()
+}, (table)=>[
+        pgCore.foreignKey({
+            columns: [
+                table.parentId
+            ],
+            foreignColumns: [
+                table.id
+            ],
+            name: "asset_folders_parent_fk"
+        }).onDelete("cascade"),
+        pgCore.index("asset_folders_parent_idx").on(table.parentId),
+        pgCore.uniqueIndex("asset_folders_name_unique").on(table.parentId, table.name)
+    ]);
+const assets = cms.table("assets", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("asset")),
+    slug: pgCore.text("slug").notNull(),
+    mimeType: pgCore.text("mime_type").notNull(),
+    size: pgCore.integer("size").notNull(),
+    objectKey: pgCore.text("object_key").notNull(),
+    status: assetStatusEnum("status").notNull().default("private"),
+    folderId: pgCore.text("folder_id").references(()=>assetFolders.id, {
+        onDelete: "set null"
+    }),
+    variantOf: pgCore.text("variant_of").references(()=>assets.id, {
+        onDelete: "set null"
+    }),
+    uploadedBy: pgCore.text("uploaded_by"),
+    createdAt: pgCore.timestamp("created_at").notNull().defaultNow(),
+    updatedAt: pgCore.timestamp("updated_at").notNull().defaultNow(),
+    archivedAt: pgCore.timestamp("archived_at")
+}, (table)=>[
+        pgCore.index("assets_folder_idx").on(table.folderId),
+        pgCore.index("assets_status_idx").on(table.status),
+        pgCore.index("assets_variant_of_idx").on(table.variantOf),
+        pgCore.uniqueIndex("assets_object_key_unique").on(table.objectKey),
+        pgCore.uniqueIndex("assets_slug_unique").on(table.slug)
+    ]);
+const blockVersions = cms.table("block_versions", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("blockVersion")),
+    blockId: pgCore.text("block_id").notNull(),
+    rootId: pgCore.text("root_id").notNull().references(()=>roots.id),
+    commitId: pgCore.text("commit_id").notNull().references(()=>commits.id),
+    type: pgCore.text("type").notNull(),
+    properties: pgCore.jsonb("properties").$type().notNull(),
+    children: pgCore.jsonb("children").$type().notNull().default([]),
+    deleted: pgCore.boolean("deleted").notNull().default(false),
+    createdAt: pgCore.timestamp("created_at").notNull().defaultNow()
+}, (table)=>[
+        pgCore.index("bv_block_id_idx").on(table.blockId),
+        pgCore.index("bv_commit_id_idx").on(table.commitId),
+        pgCore.index("bv_root_id_idx").on(table.rootId),
+        pgCore.uniqueIndex("bv_block_commit_unique").on(table.blockId, table.commitId),
+        pgCore.index("bv_properties_gin").using("gin", table.properties)
+    ]);
+const branches = cms.table("branches", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("branch")),
+    rootId: pgCore.text("root_id").notNull().references(()=>roots.id),
+    name: pgCore.text("name").notNull(),
+    headCommitId: pgCore.text("head_commit_id").notNull().references(()=>commits.id),
+    createdBy: pgCore.text("created_by"),
+    createdAt: pgCore.timestamp("created_at").notNull().defaultNow(),
+    updatedAt: pgCore.timestamp("updated_at").notNull().defaultNow()
+}, (table)=>[
+        pgCore.index("branches_root_id_idx").on(table.rootId),
+        pgCore.uniqueIndex("branches_root_name_unique").on(table.rootId, table.name)
+    ]);
+cms.table("comment_mentions", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("commentMention")),
+    messageId: pgCore.text("message_id").notNull().references(()=>commentMessages.id, {
+        onDelete: "cascade"
+    }),
+    threadId: pgCore.text("thread_id").notNull().references(()=>commentThreads.id, {
+        onDelete: "cascade"
+    }),
+    mentionedUserId: pgCore.text("mentioned_user_id").notNull(),
+    mentionedBy: pgCore.text("mentioned_by").notNull(),
+    createdAt: pgCore.timestamp("created_at").notNull().defaultNow()
+}, (table)=>[
+        pgCore.index("cmn_user_idx").on(table.mentionedUserId, table.createdAt),
+        pgCore.index("cmn_message_idx").on(table.messageId),
+        pgCore.index("cmn_thread_user_idx").on(table.threadId, table.mentionedUserId),
+        pgCore.uniqueIndex("cmn_message_user_unique").on(table.messageId, table.mentionedUserId)
+    ]);
+const commentMessages = cms.table("comment_messages", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("commentMessage")),
+    threadId: pgCore.text("thread_id").notNull().references(()=>commentThreads.id, {
+        onDelete: "cascade"
+    }),
+    parentMessageId: pgCore.text("parent_message_id"),
+    authorId: pgCore.text("author_id"),
+    messageType: commentMessageTypeEnum("message_type").notNull().default("comment"),
+    systemType: commentSystemTypeEnum("system_type"),
+    body: pgCore.text("body"),
+    meta: pgCore.jsonb("meta").$type(),
+    editedAt: pgCore.timestamp("edited_at"),
+    deletedAt: pgCore.timestamp("deleted_at"),
+    createdAt: pgCore.timestamp("created_at").notNull().defaultNow(),
+    updatedAt: pgCore.timestamp("updated_at").notNull().defaultNow()
+}, (table)=>[
+        pgCore.foreignKey({
+            columns: [
+                table.parentMessageId
+            ],
+            foreignColumns: [
+                table.id
+            ],
+            name: "comment_messages_parent_fk"
+        }).onDelete("set null"),
+        pgCore.index("cm_thread_idx").on(table.threadId, table.createdAt),
+        pgCore.index("cm_parent_idx").on(table.parentMessageId),
+        pgCore.index("cm_type_idx").on(table.messageType, table.systemType),
+        pgCore.index("cm_author_idx").on(table.authorId, table.createdAt)
+    ]);
+const commentThreads = cms.table("comment_threads", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("commentThread")),
+    rootId: pgCore.text("root_id").references(()=>roots.id, {
+        onDelete: "cascade"
+    }),
+    collection: pgCore.text("collection").notNull(),
+    targetType: commentThreadTargetEnum("target_type").notNull(),
+    mergeRequestId: pgCore.text("merge_request_id").references(()=>mergeRequests.id, {
+        onDelete: "cascade"
+    }),
+    blockId: pgCore.text("block_id"),
+    commitId: pgCore.text("commit_id").references(()=>commits.id, {
+        onDelete: "set null"
+    }),
+    status: commentThreadStatusEnum("status").notNull().default("open"),
+    resolvedBy: pgCore.text("resolved_by"),
+    resolvedAt: pgCore.timestamp("resolved_at"),
+    createdBy: pgCore.text("created_by").notNull(),
+    createdAt: pgCore.timestamp("created_at").notNull().defaultNow(),
+    updatedAt: pgCore.timestamp("updated_at").notNull().defaultNow(),
+    deletedAt: pgCore.timestamp("deleted_at")
+}, (table)=>[
+        pgCore.index("ct_collection_idx").on(table.collection, table.createdAt),
+        pgCore.index("ct_mr_idx").on(table.mergeRequestId, table.createdAt),
+        pgCore.index("ct_block_idx").on(table.blockId, table.createdAt),
+        pgCore.index("ct_commit_idx").on(table.commitId, table.createdAt),
+        pgCore.index("ct_root_idx").on(table.rootId, table.createdAt),
+        pgCore.index("ct_status_idx").on(table.status)
+    ]);
+const commits = cms.table("commits", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("commit")),
+    rootId: pgCore.text("root_id").notNull().references(()=>roots.id),
+    parentCommitId: pgCore.text("parent_commit_id"),
+    mergeSourceCommitId: pgCore.text("merge_source_commit_id"),
+    message: pgCore.text("message"),
+    createdBy: pgCore.text("created_by"),
+    createdAt: pgCore.timestamp("created_at").notNull().defaultNow()
+}, (table)=>[
+        pgCore.foreignKey({
+            columns: [
+                table.parentCommitId
+            ],
+            foreignColumns: [
+                table.id
+            ],
+            name: "commits_parent_fk"
+        }),
+        pgCore.foreignKey({
+            columns: [
+                table.mergeSourceCommitId
+            ],
+            foreignColumns: [
+                table.id
+            ],
+            name: "commits_merge_source_fk"
+        }),
+        pgCore.index("commits_parent_idx").on(table.parentCommitId),
+        pgCore.index("commits_merge_source_idx").on(table.mergeSourceCommitId),
+        pgCore.index("commits_root_created_idx").on(table.rootId, table.createdAt)
+    ]);
+const commitSnapshots = cms.table("commit_snapshots", {
+    commitId: pgCore.text("commit_id").notNull().references(()=>commits.id, {
+        onDelete: "cascade"
+    }),
+    blockId: pgCore.text("block_id").notNull(),
+    blockVersionId: pgCore.text("block_version_id").notNull().references(()=>blockVersions.id, {
+        onDelete: "cascade"
+    })
+}, (table)=>[
+        pgCore.primaryKey({
+            columns: [
+                table.commitId,
+                table.blockId
+            ]
+        }),
+        pgCore.index("cs_block_version_idx").on(table.blockVersionId)
+    ]);
+const contentUsages = cms.table("content_usages", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("contentUsage")),
+    targetKind: contentUsageTargetEnum("target_kind").notNull(),
+    targetKey: pgCore.text("target_key").notNull(),
+    blockVersionId: pgCore.text("block_version_id").notNull().references(()=>blockVersions.id, {
+        onDelete: "cascade"
+    }),
+    rootId: pgCore.text("root_id").notNull().references(()=>roots.id, {
+        onDelete: "cascade"
+    }),
+    blockId: pgCore.text("block_id").notNull(),
+    propertyKey: pgCore.text("property_key").notNull()
+}, (table)=>[
+        pgCore.uniqueIndex("cu_version_target_prop_unique").on(table.blockVersionId, table.targetKind, table.targetKey, table.propertyKey),
+        pgCore.index("cu_target_idx").on(table.targetKind, table.targetKey),
+        pgCore.index("cu_block_version_idx").on(table.blockVersionId),
+        pgCore.index("cu_root_idx").on(table.rootId)
+    ]);
+cms.table("merge_conflicts", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("mergeConflict")),
+    mergeRequestId: pgCore.text("merge_request_id").notNull().references(()=>mergeRequests.id, {
+        onDelete: "cascade"
+    }),
+    blockId: pgCore.text("block_id").notNull(),
+    sourceVersionId: pgCore.text("source_version_id").references(()=>blockVersions.id),
+    targetVersionId: pgCore.text("target_version_id").references(()=>blockVersions.id),
+    baseVersionId: pgCore.text("base_version_id").references(()=>blockVersions.id),
+    resolution: conflictResolutionEnum("resolution"),
+    resolvedVersionId: pgCore.text("resolved_version_id").references(()=>blockVersions.id),
+    resolvedBy: pgCore.text("resolved_by"),
+    resolvedAt: pgCore.timestamp("resolved_at"),
+    createdAt: pgCore.timestamp("created_at").notNull().defaultNow()
+}, (table)=>[
+        pgCore.index("mc_merge_request_idx").on(table.mergeRequestId),
+        pgCore.uniqueIndex("mc_merge_block_unique").on(table.mergeRequestId, table.blockId)
+    ]);
+const mergeRequests = cms.table("merge_requests", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("mergeRequest")),
+    rootId: pgCore.text("root_id").notNull().references(()=>roots.id),
+    sourceBranchId: pgCore.text("source_branch_id").notNull().references(()=>branches.id),
+    targetBranchId: pgCore.text("target_branch_id").notNull().references(()=>branches.id),
+    sourceCommitId: pgCore.text("source_commit_id").notNull().references(()=>commits.id),
+    baseCommitId: pgCore.text("base_commit_id").references(()=>commits.id),
+    mergeCommitId: pgCore.text("merge_commit_id").references(()=>commits.id),
+    status: mergeRequestStatusEnum("status").notNull().default("open"),
+    title: pgCore.text("title"),
+    description: pgCore.text("description"),
+    createdBy: pgCore.text("created_by").notNull(),
+    createdAt: pgCore.timestamp("created_at").notNull().defaultNow(),
+    updatedAt: pgCore.timestamp("updated_at").notNull().defaultNow()
+}, (table)=>[
+        pgCore.index("mr_root_idx").on(table.rootId),
+        pgCore.index("mr_source_branch_idx").on(table.sourceBranchId),
+        pgCore.index("mr_target_branch_idx").on(table.targetBranchId),
+        pgCore.index("mr_status_idx").on(table.status),
+        pgCore.uniqueIndex("mr_open_source_target_unique").on(table.sourceBranchId, table.targetBranchId).where(drizzleOrm.sql`status = 'open'`)
+    ]);
+cms.table("notifications", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("notification")),
+    recipientId: pgCore.text("recipient_id").notNull(),
+    actorId: pgCore.text("actor_id"),
+    type: notificationTypeEnum("type").notNull(),
+    title: pgCore.text("title").notNull(),
+    body: pgCore.text("body"),
+    resourceType: pgCore.text("resource_type"),
+    resourceId: pgCore.text("resource_id"),
+    collection: pgCore.text("collection"),
+    meta: pgCore.jsonb("meta").$type(),
+    readAt: pgCore.timestamp("read_at"),
+    archivedAt: pgCore.timestamp("archived_at"),
+    createdAt: pgCore.timestamp("created_at").notNull().defaultNow()
+}, (table)=>[
+        pgCore.index("ntf_recipient_created_idx").on(table.recipientId, table.createdAt),
+        pgCore.index("ntf_recipient_unread_idx").on(table.recipientId, table.readAt),
+        pgCore.index("ntf_resource_idx").on(table.resourceType, table.resourceId),
+        pgCore.index("ntf_type_idx").on(table.type)
+    ]);
+cms.table("publications", {
+    rootId: pgCore.text("root_id").notNull().references(()=>roots.id),
+    branchId: pgCore.text("branch_id").notNull().references(()=>branches.id),
+    commitId: pgCore.text("commit_id").notNull().references(()=>commits.id),
+    publishedBy: pgCore.text("published_by").notNull(),
+    publishedAt: pgCore.timestamp("published_at").notNull().defaultNow()
+}, (table)=>[
+        pgCore.primaryKey({
+            columns: [
+                table.rootId,
+                table.branchId
+            ]
+        }),
+        pgCore.index("publications_branch_idx").on(table.branchId)
+    ]);
+cms.table("redirects", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("redirect")),
+    collection: pgCore.text("collection").notNull(),
+    sourceType: redirectEndpointTypeEnum("source_type").notNull(),
+    sourceRootId: pgCore.text("source_root_id").references(()=>roots.id, {
+        onDelete: "cascade"
+    }),
+    sourcePath: pgCore.text("source_path"),
+    targetType: redirectEndpointTypeEnum("target_type").notNull(),
+    targetRootId: pgCore.text("target_root_id").references(()=>roots.id, {
+        onDelete: "cascade"
+    }),
+    targetPath: pgCore.text("target_path"),
+    statusCode: pgCore.integer("status_code").notNull().default(301),
+    createdBy: pgCore.text("created_by"),
+    createdAt: pgCore.timestamp("created_at").notNull().defaultNow(),
+    updatedAt: pgCore.timestamp("updated_at").notNull().defaultNow(),
+    archivedAt: pgCore.timestamp("archived_at")
+}, (table)=>[
+        pgCore.index("rdr_collection_source_path_idx").on(table.collection, table.sourcePath),
+        pgCore.index("rdr_source_root_idx").on(table.sourceRootId),
+        pgCore.index("rdr_collection_idx").on(table.collection),
+        pgCore.index("rdr_archived_at_idx").on(table.archivedAt)
+    ]);
+const roots = cms.table("roots", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("root")),
+    collection: pgCore.text("collection").notNull(),
+    parentRootId: pgCore.text("parent_root_id"),
+    slug: pgCore.text("slug"),
+    sortOrder: pgCore.integer("sort_order").notNull().default(0),
+    createdBy: pgCore.text("created_by"),
+    createdAt: pgCore.timestamp("created_at").notNull().defaultNow(),
+    archivedAt: pgCore.timestamp("archived_at"),
+    lastPrunedAt: pgCore.timestamp("last_pruned_at")
+}, (table)=>[
+        pgCore.foreignKey({
+            columns: [
+                table.parentRootId
+            ],
+            foreignColumns: [
+                table.id
+            ],
+            name: "roots_parent_fk"
+        }).onDelete("cascade"),
+        pgCore.index("roots_collection_idx").on(table.collection),
+        pgCore.index("roots_parent_root_idx").on(table.parentRootId),
+        pgCore.index("roots_slug_idx").on(table.collection, table.parentRootId, table.slug),
+        pgCore.index("roots_archived_at_idx").on(table.archivedAt),
+        pgCore.index("roots_last_pruned_at_idx").on(table.lastPrunedAt)
+    ]);
+cms.table("search_index", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("si")),
+    entityType: pgCore.text("entity_type").notNull(),
+    entityId: pgCore.text("entity_id").notNull(),
+    collection: pgCore.text("collection"),
+    rootId: pgCore.text("root_id"),
+    contentVector: tsvectorColumn("content_vector").notNull(),
+    title: pgCore.text("title"),
+    snippet: pgCore.text("snippet"),
+    meta: pgCore.jsonb("meta").$type(),
+    updatedAt: pgCore.timestamp("updated_at").notNull().defaultNow()
+}, (table)=>[
+        pgCore.index("si_vector_gin").using("gin", table.contentVector),
+        pgCore.index("si_entity_type_idx").on(table.entityType),
+        pgCore.index("si_collection_idx").on(table.collection),
+        pgCore.index("si_root_idx").on(table.rootId),
+        pgCore.uniqueIndex("si_entity_unique").on(table.entityType, table.entityId)
+    ]);
+const templates = cms.table("templates", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("template")),
+    collection: pgCore.text("collection").notNull(),
+    blockType: pgCore.text("block_type").notNull(),
+    propertyKey: pgCore.text("property_key").notNull(),
+    template: pgCore.text("template").notNull(),
+    description: pgCore.text("description"),
+    createdBy: pgCore.text("created_by"),
+    updatedBy: pgCore.text("updated_by"),
+    createdAt: pgCore.timestamp("created_at").notNull().defaultNow(),
+    updatedAt: pgCore.timestamp("updated_at").notNull().defaultNow()
+}, (table)=>[
+        pgCore.uniqueIndex("templates_collection_block_prop_unique").on(table.collection, table.blockType, table.propertyKey),
+        pgCore.index("templates_collection_idx").on(table.collection),
+        pgCore.index("templates_collection_block_idx").on(table.collection, table.blockType)
+    ]);
+cms.table("template_variable_usages", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("tplVarUsage")),
+    variableKey: pgCore.text("variable_key").notNull(),
+    templateId: pgCore.text("template_id").notNull().references(()=>templates.id, {
+        onDelete: "cascade"
+    })
+}, (table)=>[
+        pgCore.uniqueIndex("tvu_key_template_unique").on(table.variableKey, table.templateId),
+        pgCore.index("tvu_variable_key_idx").on(table.variableKey),
+        pgCore.index("tvu_template_id_idx").on(table.templateId)
+    ]);
+cms.table("variables", {
+    id: pgCore.text("id").primaryKey().$defaultFn(()=>newId("variable")),
+    key: pgCore.text("key").notNull(),
+    value: pgCore.text("value").notNull(),
+    description: pgCore.text("description"),
+    createdBy: pgCore.text("created_by"),
+    updatedBy: pgCore.text("updated_by"),
+    createdAt: pgCore.timestamp("created_at").notNull().defaultNow(),
+    updatedAt: pgCore.timestamp("updated_at").notNull().defaultNow()
+}, (table)=>[
+        pgCore.uniqueIndex("variables_key_unique").on(table.key)
+    ]);
+
+function assembleBlockTree(blocks, rootId) {
+    const deletedBlockIds = new Set();
+    const nodeMap = new Map();
+    for (const [id, block] of blocks){
+        if (block.deleted) {
+            deletedBlockIds.add(id);
+            continue;
+        }
+        nodeMap.set(id, {
+            blockId: block.blockId,
+            type: block.type,
+            properties: block.properties,
+            children: []
+        });
+    }
+    for (const [, block] of blocks){
+        if (block.deleted) continue;
+        const node = nodeMap.get(block.blockId);
+        // Drop child references that point at a deleted block or at a block absent
+        // from this snapshot. This is intentional: a parent legitimately keeps a
+        // reference to a child that a merge excluded (e.g. deleted on one branch).
+        // See buildMergedSnapshot in routes/merges.ts for the merge-side reasoning.
+        node.children = block.children.filter((childId)=>!deletedBlockIds.has(childId)).map((childId)=>nodeMap.get(childId)).filter((candidate)=>candidate !== undefined);
+    }
+    const rootNode = nodeMap.get(rootId);
+    if (rootNode) {
+        // The root block is STORED with type = collection name (see the inverse
+        // `type === 'root' ? collectionName : type` in routes/merges.ts), but the
+        // consumable tree contract uses the logical `'root'` marker — the renderer
+        // skips it to render the page as a fragment, and `getReferencePropertyNames`
+        // keys off it. Translate stored → logical HERE, at the single tree-builder,
+        // so every consumer (editor read, published render, reference resolution)
+        // sees a consistent `type: 'root'` top node.
+        rootNode.type = 'root';
+    }
+    return rootNode ?? null;
+}
+/**
+ * Load the (commit_snapshots ⋈ block_versions) rows for a single commit/root.
+ * The rootId clause is the scope guard — it keeps reconstruction from reading
+ * another root's block versions. Returns [] when the commit has no snapshot.
+ */ async function loadSnapshotRows(db, commitId, rootId) {
+    return db.select({
+        blockId: commitSnapshots.blockId,
+        blockVersionId: blockVersions.id,
+        type: blockVersions.type,
+        properties: blockVersions.properties,
+        children: blockVersions.children,
+        deleted: blockVersions.deleted
+    }).from(commitSnapshots).innerJoin(blockVersions, drizzleOrm.eq(blockVersions.id, commitSnapshots.blockVersionId)).where(drizzleOrm.and(drizzleOrm.eq(commitSnapshots.commitId, commitId), drizzleOrm.eq(blockVersions.rootId, rootId)));
+}
+async function loadBlocksAtCommit(db, commitId, rootId) {
+    const snapshotRows = await loadSnapshotRows(db, commitId, rootId);
+    if (snapshotRows.length > 0) {
+        const blocks = new Map();
+        for (const row of snapshotRows){
+            blocks.set(row.blockId, {
+                blockId: row.blockId,
+                blockVersionId: row.blockVersionId,
+                type: row.type,
+                properties: row.properties,
+                children: row.children ?? [],
+                deleted: row.deleted
+            });
+        }
+        return {
+            blocks,
+            reconstructed: false
+        };
+    }
+    const chainResult = await db.execute(drizzleOrm.sql`
+    WITH RECURSIVE chain AS (
+      SELECT id, parent_commit_id, 0 AS depth
+      FROM cms.commits
+      WHERE id = ${commitId} AND root_id = ${rootId}
+      UNION ALL
+      SELECT c.id, c.parent_commit_id, chain.depth + 1
+      FROM cms.commits c
+      JOIN chain ON c.id = chain.parent_commit_id
+      WHERE chain.depth < 10000
+    )
+    SELECT chain.id, chain.parent_commit_id, chain.depth,
+           EXISTS (SELECT 1 FROM cms.commit_snapshots cs WHERE cs.commit_id = chain.id) AS has_snapshot
+    FROM chain
+    ORDER BY depth DESC
+  `);
+    const chainRows = chainResult.rows;
+    if (chainRows.length === 0) {
+        return {
+            blocks: new Map(),
+            reconstructed: true
+        };
+    }
+    const commitChain = chainRows.map((row)=>row.id);
+    const commitsWithSnapshots = new Set(chainRows.filter((row)=>row.has_snapshot).map((row)=>row.id));
+    let baseCommitId = null;
+    let baseIndex = -1;
+    for(let i = commitChain.length - 1; i >= 0; i--){
+        if (commitChain[i] !== commitId && commitsWithSnapshots.has(commitChain[i])) {
+            baseCommitId = commitChain[i];
+            baseIndex = i;
+            break;
+        }
+    }
+    const state = new Map();
+    if (baseCommitId) {
+        const baseRows = await loadSnapshotRows(db, baseCommitId, rootId);
+        for (const row of baseRows){
+            state.set(row.blockId, {
+                blockId: row.blockId,
+                blockVersionId: row.blockVersionId,
+                type: row.type,
+                properties: row.properties,
+                children: row.children ?? [],
+                deleted: row.deleted
+            });
+        }
+    }
+    const replayCommitIds = baseCommitId ? commitChain.slice(baseIndex + 1) : commitChain;
+    if (replayCommitIds.length > 0) {
+        const replayVersions = await db.select().from(blockVersions).where(drizzleOrm.and(drizzleOrm.inArray(blockVersions.commitId, replayCommitIds), drizzleOrm.eq(blockVersions.rootId, rootId)));
+        const versionsByCommit = new Map();
+        for (const version of replayVersions){
+            const list = versionsByCommit.get(version.commitId) ?? [];
+            list.push(version);
+            versionsByCommit.set(version.commitId, list);
+        }
+        for (const commitIdInChain of replayCommitIds){
+            const versionsForCommit = versionsByCommit.get(commitIdInChain);
+            if (!versionsForCommit) continue;
+            for (const version of versionsForCommit){
+                state.set(version.blockId, {
+                    blockId: version.blockId,
+                    blockVersionId: version.id,
+                    type: version.type,
+                    properties: version.properties,
+                    children: version.children ?? [],
+                    deleted: version.deleted
+                });
+            }
+        }
+    }
+    return {
+        blocks: state,
+        reconstructed: true
+    };
+}
+
+const cmsContext = betterCall.createMiddleware(async ()=>{
+    return {};
+});
+const createCMSEndpoint = betterCall.createEndpoint.create({
+    use: [
+        cmsContext
+    ]
+});
+function cmsMeta(base, cms) {
+    return {
+        ...base,
+        cms
+    };
+}
+
+/**
+ * Resolves the GA4/dataLayer wire name for a block event key: the author's
+ * `EventDeclaration.name` override, else the default `cms_<blockType>_<key>`
+ * (locked measurement decision #7). Pure + framework-free so BOTH the client
+ * tracker (react/tracking.tsx, where a fire happens) and the server goal-picker
+ * (ab-test listGoalEvents, which advertises the goal) resolve names identically
+ * — the stored event_type and the offered goal must be the same string.
+ */ function resolveWireName(key, blockType, events) {
+    return events?.[key]?.name ?? `cms_${blockType}_${key}`;
+}
+
+const SAFE_COLUMN = /^[a-z_][a-z0-9_]*$/i;
+/**
+ * Equality conditions for plugin-owned scope columns (e.g. `tenant_slug`)
+ * against an UN-ALIASED `cms.roots`, fully qualified so they bind in raw-SQL
+ * read paths that want defensive scope filtering (a referenced or ancestor root
+ * must be in the active scope). `exclude` drops columns the caller handles
+ * separately (a scoping plugin whose column varies independently of the query).
+ * Column names are validated; values are parameterized. Returns `[]` when no
+ * scoping is active.
+ */ function rootScopeConditions(scopeColumns, exclude = []) {
+    if (!scopeColumns) return [];
+    const conds = [];
+    for (const [col, val] of Object.entries(scopeColumns)){
+        if (val === undefined || val === null || exclude.includes(col)) continue;
+        if (!SAFE_COLUMN.test(col)) {
+            throw new Error(`rootScopeConditions: unsafe scope column "${col}"`);
+        }
+        conds.push(drizzleOrm.sql`"cms"."roots".${drizzleOrm.sql.raw(`"${col}"`)} = ${val}`);
+    }
+    return conds;
+}
+/**
+ * The roots scope columns for CROSS-scope read filtering: the static insert
+ * columns MINUS the plugin-declared `crossScopeExclude` (columns the plugin
+ * varies INDEPENDENTLY of a query — e.g. the i18n plugin's `language`). Pass the
+ * result to reads that legitimately span those columns (reference / host /
+ * usage / co-render reads, the published-root load) so they are NOT filtered by
+ * them. Core names no specific column. (Seam D6.)
+ */ function crossScopeColumns(rootScope) {
+    const cols = rootScope?.insertColumns;
+    const exclude = rootScope?.crossScopeExclude;
+    if (!cols || !exclude?.length) return cols;
+    return Object.fromEntries(Object.entries(cols).filter(([k])=>!exclude.includes(k)));
+}
+
+// ============================================================================
+// Reference-resolution seam — core's identity default (Seam B)
+// ============================================================================
+/**
+ * Core's identity `ReferenceResolver` — the no-resolver-plugin behaviour (a
+ * stored value renders as itself; no grouping), byte-for-byte. Used wherever
+ * `scope.referenceResolver` is absent.
+ *   - resolveRenderTargets: every stored value renders as itself
+ *     (loadPublishedRoots then drops unpublished / out-of-scope ones).
+ *   - resolveConflictTargets: the existing, non-archived roots among the keys
+ *     (by id), scoped to the given (cross-scope) columns.
+ *   - expandGroup: identity (no groups without a resolver plugin).
+ *   - groupKeysFor: [] (no group keys without a resolver plugin).
+ *
+ * Stateless singleton: `db` and `scopeColumns` are per-call args (so a caller
+ * inside a transaction resolves on its own tx, and tenant scoping uses the
+ * merged columns the caller holds).
+ */ const coreReferenceResolver = {
+    async resolveRenderTargets (_db, _scopeColumns, _collection, storedValues) {
+        return new Map(storedValues.map((v)=>[
+                v,
+                v
+            ]));
+    },
+    async resolveConflictTargets (db, scopeColumns, storedKeys) {
+        if (storedKeys.length === 0) return [];
+        const rows = await db.select({
+            id: roots.id
+        }).from(roots).where(drizzleOrm.and(drizzleOrm.inArray(roots.id, storedKeys), drizzleOrm.isNull(roots.archivedAt), ...rootScopeConditions(scopeColumns)));
+        return rows.map((r)=>r.id);
+    },
+    async expandGroup (_db, _scopeColumns, rootIds) {
+        return rootIds;
+    },
+    async groupKeysFor () {
+        return [];
+    }
+};
+// ============================================================================
+// Reference edges — the generic live-head graph primitive (exposed for plugins)
+// ============================================================================
+/**
+ * Live-head reference edges in one direction. `embeds` filters on the host
+ * `rootId` and returns what those hosts embed (the `targetKey`s); `embeddedBy`
+ * filters on `targetKey` and returns the hosts (`rootId`s). Restricted to
+ * non-archived roots' non-deleted branch-HEAD content, scope-filtered (the
+ * caller passes cross-scope columns — like the read path / delete guard).
+ */ async function referenceEdges(db, ids, direction, scopeColumns) {
+    if (ids.length === 0) return [];
+    const filterCol = direction === 'embeds' ? contentUsages.rootId : contentUsages.targetKey;
+    const selectCol = direction === 'embeds' ? contentUsages.targetKey : contentUsages.rootId;
+    const rows = await db.selectDistinct({
+        id: selectCol
+    }).from(contentUsages).innerJoin(commitSnapshots, drizzleOrm.eq(commitSnapshots.blockVersionId, contentUsages.blockVersionId)).innerJoin(branches, drizzleOrm.eq(branches.headCommitId, commitSnapshots.commitId)).innerJoin(roots, drizzleOrm.eq(roots.id, branches.rootId)).innerJoin(blockVersions, drizzleOrm.eq(blockVersions.id, contentUsages.blockVersionId)).where(drizzleOrm.and(drizzleOrm.eq(contentUsages.targetKind, 'reference'), drizzleOrm.inArray(filterCol, ids), drizzleOrm.isNull(roots.archivedAt), drizzleOrm.eq(blockVersions.deleted, false), ...rootScopeConditions(scopeColumns)));
+    return rows.map((r)=>r.id);
+}
+
+/**
+ * GA4 params the SERVER derives + owns. They are stripped from the untrusted
+ * `metadata` (public trackEvent input) before it is merged, so a caller can
+ * never fabricate/overwrite them — not even on a non-A/B event where the
+ * server-derived value happens to be absent (a conditional spread would
+ * otherwise leave the attacker's value in place).
+ */ const RESERVED_GA4_PARAMS = new Set([
+    'engagement_time_msec',
+    'session_id',
+    'experiment_id',
+    'experiment_variant',
+    'tracking_id',
+    'interaction_id'
+]);
+/** A copy of `metadata` with every server-owned GA4 param removed. */ function sanitizeMetadata(metadata) {
+    if (!metadata) return {};
+    const out = {};
+    for (const [key, value] of Object.entries(metadata)){
+        if (!RESERVED_GA4_PARAMS.has(key)) out[key] = value;
+    }
+    return out;
+}
+/**
+ * Builds the MP payload from a {@link CMSEvent}. Pure (no I/O) + exported so the
+ * mapping is unit-testable. Returns null when the event cannot be a valid MP hit
+ * — no consent (analytics_storage not granted) or no client_id — so the caller
+ * simply does not forward. The A/B attribution rides as GA4's
+ * `experiment_id`/`experiment_variant` convention (event-scoped custom dims).
+ */ function buildGa4Payload(event) {
+    if (event.consent?.analytics_storage !== 'granted') return null;
+    const clientId = event.transport?.clientId;
+    if (!clientId) return null;
+    const params = {
+        // metadata FIRST, but with every server-owned param stripped: it is
+        // public-ingest input (trackEvent body), so a caller can never fabricate or
+        // overwrite experiment_id / experiment_variant / session_id /
+        // engagement_time_msec / tracking_id / interaction_id — not even on a
+        // non-A/B event where the server-derived value is absent (a plain
+        // conditional spread would leave the attacker's value standing).
+        ...sanitizeMetadata(event.metadata),
+        // GA4 needs a non-zero engagement time, else the hit is realtime-invisible.
+        engagement_time_msec: event.transport?.engagementTimeMsec ?? 1,
+        ...event.transport?.sessionId ? {
+            session_id: event.transport.sessionId
+        } : {},
+        ...event.ab ? {
+            experiment_id: event.ab.testId,
+            experiment_variant: event.ab.variantId
+        } : {},
+        ...event.source?.handle ? {
+            tracking_id: event.source.handle
+        } : {},
+        ...event.interactionId ? {
+            interaction_id: event.interactionId
+        } : {}
+    };
+    return {
+        client_id: clientId,
+        events: [
+            {
+                name: event.name,
+                params
+            }
+        ],
+        // GA4 Consent Mode block (ad signals). analytics_storage is already gated
+        // above; the ad_* signals tell GA4 how it may use the data.
+        ...event.consent ? {
+            consent: {
+                ad_user_data: event.consent.ad_user_data,
+                ad_personalization: event.consent.ad_personalization
+            }
+        } : {}
+    };
+}
+/** Resolves the POST URL for a config (MP appends measurement_id + api_secret). */ function resolveUrl(config) {
+    if (config.type === 'sgtm') return config.endpointUrl;
+    const sep = config.endpointUrl.includes('?') ? '&' : '?';
+    return `${config.endpointUrl}${sep}measurement_id=${encodeURIComponent(config.measurementId)}&api_secret=${encodeURIComponent(config.apiSecret)}`;
+}
+/** Max wall-clock the forward may add to the public ingest before it is aborted. */ const FORWARD_TIMEOUT_MS = 2000;
+/**
+ * Forwards one event to GA4 server-side, IF it is a valid consenting MP hit.
+ * Best-effort + non-fatal: a network/endpoint error never breaks the ingest
+ * (the A/B store write already happened). No-ops on missing consent/client_id.
+ *
+ * The trackEvent handler awaits this, so it is hard-bounded by an
+ * {@link AbortSignal.timeout}: a slow/hung GA4/sGTM endpoint can never stall the
+ * public response — the abort surfaces as a caught error and the ingest returns.
+ */ async function forwardToGa4(event, config, fetchImpl = fetch) {
+    const payload = buildGa4Payload(event);
+    if (!payload) return; // not a consenting, identified hit → do not forward
+    try {
+        await fetchImpl(resolveUrl(config), {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json'
+            },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(FORWARD_TIMEOUT_MS)
+        });
+    } catch  {
+    // Non-fatal: the authoritative A/B store write already succeeded (a
+    // network error, a non-2xx, or the timeout abort all land here).
+    }
+}
+
+/**
+ * MurmurHash3 (32-bit) for deterministic variant assignment.
+ * Inlined to avoid an external dependency for ~30 lines of code.
+ */ function murmur3(key, seed = 0) {
+    let h = seed >>> 0;
+    const len = key.length;
+    let i = 0;
+    while(i + 4 <= len){
+        let k = key.charCodeAt(i) & 0xff | (key.charCodeAt(i + 1) & 0xff) << 8 | (key.charCodeAt(i + 2) & 0xff) << 16 | (key.charCodeAt(i + 3) & 0xff) << 24;
+        k = Math.imul(k, 0xcc9e2d51);
+        k = k << 15 | k >>> 17;
+        k = Math.imul(k, 0x1b873593);
+        h ^= k;
+        h = h << 13 | h >>> 19;
+        h = Math.imul(h, 5) + 0xe6546b64;
+        i += 4;
+    }
+    let k = 0;
+    switch(len & 3){
+        case 3:
+            k ^= (key.charCodeAt(i + 2) & 0xff) << 16;
+        // falls through
+        case 2:
+            k ^= (key.charCodeAt(i + 1) & 0xff) << 8;
+        // falls through
+        case 1:
+            k ^= key.charCodeAt(i) & 0xff;
+            k = Math.imul(k, 0xcc9e2d51);
+            k = k << 15 | k >>> 17;
+            k = Math.imul(k, 0x1b873593);
+            h ^= k;
+    }
+    h ^= len;
+    h ^= h >>> 16;
+    h = Math.imul(h, 0x85ebca6b);
+    h ^= h >>> 13;
+    h = Math.imul(h, 0xc2b2ae35);
+    h ^= h >>> 16;
+    return h >>> 0;
+}
+/**
+ * Deterministic variant assignment.
+ *
+ * The same `contextKey + testId` always produces the same variant.
+ * No DB writes needed -- pure function.
+ *
+ * @param contextKey  - Visitor identifier (user ID or anonymous key)
+ * @param testId      - The A/B test ID
+ * @param trafficPercentage - 0-100, how much total traffic enters the test
+ * @param variants    - Must be sorted by id for stability
+ */ function resolveVariant(contextKey, testId, trafficPercentage, variants) {
+    const hash = murmur3(contextKey + ':' + testId);
+    const bucket = hash % 10000;
+    const control = variants.find((v)=>v.isControl);
+    if (bucket >= trafficPercentage * 100) {
+        return {
+            variantId: control.id,
+            inTest: false
+        };
+    }
+    const sorted = [
+        ...variants
+    ].sort((a, b)=>a.id.localeCompare(b.id));
+    const normalizedBucket = Math.floor(bucket * 100 / (trafficPercentage * 100));
+    let cumulative = 0;
+    for (const v of sorted){
+        cumulative += v.weight;
+        if (normalizedBucket < cumulative) {
+            return {
+                variantId: v.id,
+                inTest: true
+            };
+        }
+    }
+    return {
+        variantId: control.id,
+        inTest: true
+    };
+}
+
+// ============================================================================
+// Co-render set — the conflict set for the A/B XOR guard (AB_FANOUT_DESIGN F1)
+// ============================================================================
+//
+// The render-tree traversal that powers the A/B cross-embed XOR rule. Built on
+// core's generic `referenceEdges` (the live-head graph primitive) composed with
+// `scope.referenceResolver` (group resolution): without the i18n plugin the
+// resolver is identity and this degrades to a plain rootId graph; with it, the
+// walk is translation-group aware. Owned by ab-test because the XOR rule is its
+// concern; core stays free of the A/B closure algorithm.
+const MAX_CORENDER_DEPTH = 20; // mirrors MAX_REFERENCE_DEPTH (publications.ts)
+/**
+ * Down-only transitive EMBED closure reachable from `startRoots` — the render
+ * subtree(s) below them. tgr_-aware (resolves group references) + group-aware +
+ * tenant-scoped + bounded. Mutates + reads `seen` for dedup; returns the newly
+ * reached roots (not in `seen` initially).
+ */ async function embedClosure(db, startRoots, seen, resolver, scopeColumns) {
+    const down = new Set();
+    let frontier = [
+        ...startRoots
+    ];
+    for(let d = 0; d < MAX_CORENDER_DEPTH && frontier.length > 0; d++){
+        const rawTargets = await referenceEdges(db, frontier, 'embeds', scopeColumns);
+        const resolved = await resolver.resolveConflictTargets(db, scopeColumns, rawTargets);
+        const expanded = await resolver.expandGroup(db, scopeColumns, resolved);
+        const next = [];
+        for (const t of expanded){
+            if (!seen.has(t)) {
+                seen.add(t);
+                down.add(t);
+                next.push(t);
+            }
+        }
+        frontier = next;
+    }
+    return down;
+}
+/**
+ * The roots in `rootId`'s OWN rendered subtree (its transitive embeds), group-
+ * aware, excluding rootId's own group. Used by the publishBranch backstop, which
+ * cares only about the render tree the published root produces.
+ */ async function collectEmbeddedRoots(db, rootId, resolver, scopeColumns) {
+    const ownGroup = new Set(await resolver.expandGroup(db, scopeColumns, [
+        rootId
+    ]));
+    return embedClosure(db, [
+        ...ownGroup
+    ], new Set(ownGroup), resolver, scopeColumns);
+}
+/**
+ * All roots that can appear in the SAME rendered page tree as `rootId` — the
+ * conflict set for the A/B XOR rule (AB_FANOUT_DESIGN §2). = the transitive HOSTS
+ * of rootId (every root that embeds it, going up), then the transitive EMBEDS of
+ * rootId AND each host (going down) — covering the page above, the blocks below,
+ * and co-embedded siblings. Group-aware AND tgr_-aware (a reference may store a
+ * translation-group key, resolved like the read path), bounded by
+ * MAX_CORENDER_DEPTH; a conservative SUPERSET (over-includes → fails safe).
+ * rootId's OWN translation group is excluded. The caller rejects if any returned
+ * root has a running test.
+ */ async function collectCoRenderRoots(db, rootId, resolver, scopeColumns) {
+    const ownGroup = new Set(await resolver.expandGroup(db, scopeColumns, [
+        rootId
+    ]));
+    // Up: transitive hosts. A host may embed via the rootId OR the group's tgr_
+    // key, so match both forms.
+    const up = new Set();
+    let frontier = [
+        ...ownGroup
+    ];
+    for(let d = 0; d < MAX_CORENDER_DEPTH && frontier.length > 0; d++){
+        const tgrKeys = await resolver.groupKeysFor(db, scopeColumns, frontier);
+        const hosts = await referenceEdges(db, [
+            ...frontier,
+            ...tgrKeys
+        ], 'embeddedBy', scopeColumns);
+        const expanded = await resolver.expandGroup(db, scopeColumns, hosts);
+        const next = [];
+        for (const h of expanded){
+            if (!up.has(h) && !ownGroup.has(h)) {
+                up.add(h);
+                next.push(h);
+            }
+        }
+        frontier = next;
+    }
+    // Down: transitive embeds of rootId AND every host (so co-embedded siblings
+    // are included), tgr_-aware + group-aware.
+    const seen = new Set([
+        ...ownGroup,
+        ...up
+    ]);
+    const down = await embedClosure(db, [
+        ...seen
+    ], seen, resolver, scopeColumns);
+    const result = new Set();
+    for (const r of up)if (!ownGroup.has(r)) result.add(r);
+    for (const r of down)if (!ownGroup.has(r)) result.add(r);
+    return result;
+}
+
+const $ERROR_CODES = {
+    AB_TEST_NOT_FOUND: {
+        status: 404,
+        message: 'A/B test not found'
+    },
+    AB_TEST_INVALID_STATUS: {
+        status: 400,
+        message: 'Invalid status transition for this A/B test'
+    },
+    AB_TEST_WEIGHTS_INVALID: {
+        status: 400,
+        message: 'Variant weights must sum to 100'
+    },
+    AB_TEST_DUPLICATE_RUNNING: {
+        status: 409,
+        message: 'Another test is already running for this root'
+    },
+    AB_TEST_CROSS_EMBED_CONFLICT: {
+        status: 409,
+        message: 'Cannot run: a co-rendering root (an embedded reusable block or its host page) already has a running test — at most one A/B axis may vary per render'
+    },
+    AB_TEST_BRANCH_NOT_PUBLISHED: {
+        status: 400,
+        message: 'All variant branches must be published'
+    },
+    AB_TEST_NO_CONTEXT: {
+        status: 400,
+        message: 'No visitor context set. Call identify() first.'
+    },
+    AB_TEST_FLUSH_NOT_SUPPORTED: {
+        status: 400,
+        message: 'Flush is not supported by the current analytics adapter'
+    },
+    AB_TEST_VARIANT_NOT_FOUND: {
+        status: 404,
+        message: 'A/B test variant not found'
+    },
+    AB_TEST_TRACKING_ID_MISSING: {
+        status: 400,
+        message: 'A functional block (one that declares events) is missing its trackingId — every such block must have a non-empty trackingId before the branch can be published'
+    },
+    AB_TEST_TRACKING_ID_DUPLICATE: {
+        status: 400,
+        message: 'Duplicate trackingId in this branch — each functional block must have a unique trackingId'
+    },
+    AB_TEST_TRACKING_ID_DRIFT: {
+        status: 409,
+        message: 'trackingId drift across A/B variant branches — the set of functional trackingIds must be identical across all variant branches of a root, so a chosen goal exists in every arm'
+    }
+};
+
+const AB_TEST_META = {
+    scope: 'system',
+    permissionResource: 'abTest'
+};
+// The PUBLIC event ingest (trackEvent) uses a DISTINCT resource from the admin
+// 'abTest' resource (createTest/updateTest/getResults/…), so an app can allow
+// anonymous access to ONLY the ingest — public visitors record impressions/
+// conversions without a session — while keeping the admin mutations gated.
+const AB_EVENT_META = {
+    scope: 'system',
+    permissionResource: 'abTestEvent'
+};
+// ============================================================================
+// Zod Schemas
+// ============================================================================
+const variantInput = z__namespace.object({
+    branchId: z__namespace.string(),
+    name: z__namespace.string(),
+    weight: z__namespace.number().int().min(0).max(100),
+    isControl: z__namespace.boolean().optional().default(false)
+});
+const variantsSchema = z__namespace.array(variantInput).min(2, 'At least 2 variants required').refine((v)=>v.reduce((sum, x)=>sum + x.weight, 0) === 100, {
+    message: 'Variant weights must sum to 100'
+}).refine((v)=>v.filter((x)=>x.isControl).length === 1, {
+    message: 'Exactly one variant must be marked as control'
+});
+const contextSchema = z__namespace.object({
+    key: z__namespace.string().min(1),
+    anonymous: z__namespace.boolean().optional()
+});
+function abTestError(code, message) {
+    throw new betterCall.APIError($ERROR_CODES[code].status, {
+        message: message ?? $ERROR_CODES[code].message,
+        code
+    });
+}
+function getTenantSlug(scope) {
+    return scope.roots?.insertColumns?.tenant_slug ?? null;
+}
+function mapTestRow(row) {
+    return {
+        id: row.id,
+        rootId: row.root_id,
+        collection: row.collection,
+        name: row.name,
+        goalHandle: row.goal_handle,
+        goalEvent: row.goal_event,
+        status: row.status,
+        trafficPercentage: row.traffic_percentage,
+        startedAt: row.started_at,
+        endedAt: row.ended_at,
+        createdBy: row.created_by,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at
+    };
+}
+function mapVariantRow(row) {
+    return {
+        id: row.id,
+        branchId: row.branch_id,
+        name: row.name,
+        weight: row.weight,
+        isControl: row.is_control
+    };
+}
+async function findTestOrThrow(db, testId, tenantSlug) {
+    let result;
+    if (tenantSlug) {
+        result = await db.execute(drizzleOrm.sql`
+      SELECT t.* FROM cms.ab_tests t
+      INNER JOIN cms.roots r ON r.id = t.root_id
+      WHERE t.id = ${testId} AND r.tenant_slug = ${tenantSlug}
+    `);
+    } else {
+        result = await db.execute(drizzleOrm.sql`
+      SELECT * FROM cms.ab_tests WHERE id = ${testId}
+    `);
+    }
+    if (result.rows.length === 0) abTestError('AB_TEST_NOT_FOUND');
+    return result.rows[0];
+}
+async function getVariantsForTest(db, testId) {
+    const result = await db.execute(drizzleOrm.sql`
+    SELECT * FROM cms.ab_test_variants WHERE test_id = ${testId} ORDER BY id
+  `);
+    return result.rows;
+}
+async function validateBranchesPublished(db, rootId, branchIds) {
+    if (branchIds.length === 0) return;
+    const placeholders = branchIds.map((id)=>drizzleOrm.sql`${id}`);
+    const arrayExpr = drizzleOrm.sql`ARRAY[${drizzleOrm.sql.join(placeholders, drizzleOrm.sql`, `)}]::text[]`;
+    const result = await db.execute(drizzleOrm.sql`
+    SELECT p.branch_id
+    FROM cms.publications p
+    WHERE p.root_id = ${rootId}
+      AND p.branch_id = ANY(${arrayExpr})
+  `);
+    const publishedSet = new Set(result.rows.map((r)=>r.branch_id));
+    for (const bid of branchIds){
+        if (!publishedSet.has(bid)) {
+            abTestError('AB_TEST_BRANCH_NOT_PUBLISHED', `Branch ${bid} is not published for root ${rootId}`);
+        }
+    }
+}
+async function insertVariants(db, testId, variants) {
+    for (const v of variants){
+        const id = newId('abTestVariant');
+        await db.execute(drizzleOrm.sql`
+      INSERT INTO cms.ab_test_variants (id, test_id, branch_id, name, weight, is_control)
+      VALUES (${id}, ${testId}, ${v.branchId}, ${v.name}, ${v.weight}, ${v.isControl ?? false})
+    `);
+    }
+}
+async function deleteVariantsForTest(db, testId) {
+    await db.execute(drizzleOrm.sql`
+    DELETE FROM cms.ab_test_variants WHERE test_id = ${testId}
+  `);
+}
+/** Walk a tree, emitting a goal candidate per (functional block instance × event). */ function collectGoalsFromTree(node, blocks, hostRootId, inVaryingRoot, out) {
+    const def = blocks[node.type];
+    const events = def?.events;
+    if (events && Object.keys(events).length > 0) {
+        const handle = typeof node.properties.trackingId === 'string' ? node.properties.trackingId : null;
+        for (const [event, decl] of Object.entries(events)){
+            out.push({
+                handle,
+                blockType: node.type,
+                blockId: node.blockId,
+                event,
+                name: resolveWireName(event, node.type, events),
+                label: decl.label,
+                params: decl.params ? Object.keys(decl.params) : [],
+                inVaryingRoot,
+                hostRootId
+            });
+        }
+    }
+    for (const child of node.children){
+        collectGoalsFromTree(child, blocks, hostRootId, inVaryingRoot, out);
+    }
+}
+/**
+ * Loads a root's published tree (the FIRST published branch, deterministically)
+ * + the root's collection, and enumerates goal candidates from that one branch.
+ * Goal anchors are branch-stable ONLY once a test RUNS (the trackingId drift
+ * guard enforces matching sets across running variants) — at pick time the test
+ * is still draft, so a functional block present only on a non-first / not-yet-
+ * published variant branch is NOT offered until that branch is the enumerated
+ * one. Acceptable for the common case (pick a goal present on control); the
+ * running-time drift guard rejects divergent sets later. Returns null when the
+ * root has no published content / is out of scope.
+ */ async function loadRootPublishedTree(db, rootId, tenantSlug) {
+    const rows = await db.execute(drizzleOrm.sql`
+    SELECT r.collection AS collection, b.head_commit_id AS commit_id
+    FROM cms.publications p
+    INNER JOIN cms.branches b ON b.id = p.branch_id
+    INNER JOIN cms.roots r ON r.id = p.root_id
+    WHERE p.root_id = ${rootId}
+      ${tenantSlug ? drizzleOrm.sql`AND r.tenant_slug = ${tenantSlug}` : drizzleOrm.sql``}
+    ORDER BY p.published_at ASC, p.branch_id ASC
+    LIMIT 1
+  `);
+    if (rows.rows.length === 0) return null;
+    const { collection, commit_id } = rows.rows[0];
+    const { blocks } = await loadBlocksAtCommit(db, commit_id, rootId);
+    const tree = assembleBlockTree(blocks, rootId);
+    if (!tree) return null;
+    return {
+        tree,
+        collection
+    };
+}
+// ============================================================================
+// Endpoints
+// ============================================================================
+/**
+ * Creates all A/B test endpoints.
+ *
+ * Every handler reads `db` from `reqCtx.context.db`, which is injected
+ * by the CMS endpoint wrapper at runtime -- just like better-auth does
+ * with `ctx.context.db`. No closure or holder needed.
+ */ function createABTestEndpoints(adapter, getCollections, ga4Config) {
+    return {
+        createTest: createCMSEndpoint('/abTest/createTest', {
+            method: 'POST',
+            body: z__namespace.object({
+                rootId: z__namespace.string(),
+                collection: z__namespace.string(),
+                name: z__namespace.string(),
+                trafficPercentage: z__namespace.number().int().min(0).max(100).optional().default(100),
+                goalHandle: z__namespace.string().min(1).optional(),
+                goalEvent: z__namespace.string().min(1).optional(),
+                variants: variantsSchema
+            }),
+            metadata: cmsMeta({
+                $Infer: {
+                    body: {}
+                }
+            }, {
+                operation: 'create',
+                ...AB_TEST_META
+            })
+        }, async (reqCtx)=>{
+            const { db, scope } = reqCtx.context;
+            const tenantSlug = getTenantSlug(scope);
+            const { rootId, collection, name, trafficPercentage, goalHandle, goalEvent, variants } = reqCtx.body;
+            const userId = reqCtx.context.userId;
+            if (tenantSlug) {
+                const rootCheck = await db.execute(drizzleOrm.sql`
+            SELECT 1 FROM cms.roots
+            WHERE id = ${rootId} AND tenant_slug = ${tenantSlug}
+          `);
+                if (rootCheck.rows.length === 0) {
+                    abTestError('AB_TEST_NOT_FOUND', 'Root not found for this tenant');
+                }
+            }
+            await validateBranchesPublished(db, rootId, variants.map((v)=>v.branchId));
+            const testId = newId('abTest');
+            await db.execute(drizzleOrm.sql`
+          INSERT INTO cms.ab_tests (id, root_id, collection, name, goal_handle, goal_event, status, traffic_percentage, created_by, created_at, updated_at)
+          VALUES (${testId}, ${rootId}, ${collection}, ${name}, ${goalHandle ?? null}, ${goalEvent ?? null}, 'draft', ${trafficPercentage}, ${userId ?? null}, NOW(), NOW())
+        `);
+            await insertVariants(db, testId, variants);
+            return {
+                testId
+            };
+        }),
+        updateTest: createCMSEndpoint('/abTest/updateTest', {
+            method: 'POST',
+            body: z__namespace.object({
+                testId: z__namespace.string(),
+                name: z__namespace.string().optional(),
+                status: z__namespace.enum([
+                    'draft',
+                    'running',
+                    'paused',
+                    'completed'
+                ]).optional(),
+                trafficPercentage: z__namespace.number().int().min(0).max(100).optional(),
+                // nullable → an explicit null clears the goal; omitted → unchanged.
+                // min(1) rejects '' so a stored goal is always a usable goal.
+                goalHandle: z__namespace.string().min(1).nullable().optional(),
+                goalEvent: z__namespace.string().min(1).nullable().optional(),
+                variants: variantsSchema.optional()
+            }),
+            metadata: cmsMeta({
+                $Infer: {
+                    body: {}
+                }
+            }, {
+                operation: 'update',
+                ...AB_TEST_META
+            })
+        }, async (reqCtx)=>{
+            const { db, scope } = reqCtx.context;
+            const tenantSlug = getTenantSlug(scope);
+            const { testId, name, status, trafficPercentage, goalHandle, goalEvent, variants } = reqCtx.body;
+            const test = await findTestOrThrow(db, testId, tenantSlug);
+            if (status) {
+                const allowed = {
+                    draft: [
+                        'running'
+                    ],
+                    running: [
+                        'paused',
+                        'completed'
+                    ],
+                    paused: [
+                        'running',
+                        'completed'
+                    ],
+                    completed: []
+                };
+                if (!allowed[test.status]?.includes(status)) {
+                    abTestError('AB_TEST_INVALID_STATUS', `Cannot transition from "${test.status}" to "${status}"`);
+                }
+            }
+            // For a →running transition, compute the XOR conflict set up-front so we
+            // know which root rows to lock. Locking them FOR UPDATE (id-ordered →
+            // deadlock-free) inside the transaction serialises concurrent →running
+            // calls on overlapping conflict sets, closing the check-then-update race.
+            let coRender = new Set();
+            let lockRootIds = [];
+            if (status === 'running') {
+                coRender = await collectCoRenderRoots(db, test.root_id, scope.referenceResolver ?? coreReferenceResolver, crossScopeColumns(scope.roots));
+                lockRootIds = [
+                    test.root_id,
+                    ...coRender
+                ].sort();
+            }
+            await db.transaction(async (tx)=>{
+                if (lockRootIds.length > 0) {
+                    await tx.execute(drizzleOrm.sql`
+              SELECT id FROM cms.roots
+              WHERE id IN (${drizzleOrm.sql.join(lockRootIds.map((r)=>drizzleOrm.sql`${r}`), drizzleOrm.sql`, `)})
+              ORDER BY id
+              FOR UPDATE
+            `);
+                }
+                if (status === 'running') {
+                    // Same-root: only one running test per root.
+                    const running = await tx.execute(drizzleOrm.sql`
+              SELECT id FROM cms.ab_tests
+              WHERE root_id = ${test.root_id} AND status = 'running' AND id != ${testId}
+              LIMIT 1
+            `);
+                    if (running.rows.length > 0) {
+                        abTestError('AB_TEST_DUPLICATE_RUNNING');
+                    }
+                    // XOR (cross-embed): a co-rendering root — the host page that embeds
+                    // this block, a block it embeds, or a co-embedded sibling,
+                    // transitively — must not ALSO have a running test, else a single
+                    // render would vary on two axes (unattributable). Conservative +
+                    // group-aware (AB_FANOUT_DESIGN §2). Re-checked here under the lock.
+                    if (coRender.size > 0) {
+                        const conflict = await tx.execute(drizzleOrm.sql`
+                SELECT id FROM cms.ab_tests
+                WHERE root_id IN (${drizzleOrm.sql.join([
+                            ...coRender
+                        ].map((r)=>drizzleOrm.sql`${r}`), drizzleOrm.sql`, `)})
+                  AND status = 'running' AND id != ${testId}
+                LIMIT 1
+              `);
+                        if (conflict.rows.length > 0) {
+                            abTestError('AB_TEST_CROSS_EMBED_CONFLICT');
+                        }
+                    }
+                }
+                if (variants) {
+                    if (test.status !== 'draft' && test.status !== 'paused') {
+                        abTestError('AB_TEST_INVALID_STATUS', 'Variants can only be updated when test is draft or paused');
+                    }
+                    await validateBranchesPublished(tx, test.root_id, variants.map((v)=>v.branchId));
+                    await deleteVariantsForTest(tx, testId);
+                    await insertVariants(tx, testId, variants);
+                }
+                const sets = [
+                    drizzleOrm.sql`updated_at = NOW()`
+                ];
+                if (name !== undefined) sets.push(drizzleOrm.sql`name = ${name}`);
+                if (trafficPercentage !== undefined) sets.push(drizzleOrm.sql`traffic_percentage = ${trafficPercentage}`);
+                if (goalHandle !== undefined) sets.push(drizzleOrm.sql`goal_handle = ${goalHandle}`);
+                if (goalEvent !== undefined) sets.push(drizzleOrm.sql`goal_event = ${goalEvent}`);
+                if (status) {
+                    sets.push(drizzleOrm.sql`status = ${status}`);
+                    if (status === 'running' && !test.started_at) {
+                        sets.push(drizzleOrm.sql`started_at = NOW()`);
+                    }
+                    if (status === 'completed') {
+                        sets.push(drizzleOrm.sql`ended_at = NOW()`);
+                    }
+                }
+                const setClause = drizzleOrm.sql.join(sets, drizzleOrm.sql`, `);
+                await tx.execute(drizzleOrm.sql`UPDATE cms.ab_tests SET ${setClause} WHERE id = ${testId}`);
+            });
+            // Toggling the test into/out of `running` changes what
+            // getPublishedContent returns for the root (the page-level `abTest`
+            // descriptor + variant fan-out appear/disappear). That is NOT a content
+            // write, so the normal write-action revalidation never sees it — fire a
+            // manual revalidation for the root so the app busts that page's render
+            // caches (unstable_cache + the variant-coded ISR entries). Without this,
+            // a freshly started/stopped test serves stale (pre-toggle) renders.
+            const togglesRunning = status !== undefined && test.status === 'running' !== (status === 'running');
+            if (togglesRunning && reqCtx.context.revalidationRunner) {
+                const allVariants = await getVariantsForTest(db, testId);
+                const control = allVariants.find((v)=>v.is_control) ?? allVariants[0];
+                if (control) {
+                    await reqCtx.context.revalidationRunner.fireManual({
+                        collection: test.collection,
+                        rootId: test.root_id,
+                        branchId: control.branch_id
+                    });
+                }
+            }
+            return {
+                testId
+            };
+        }),
+        deleteTest: createCMSEndpoint('/abTest/deleteTest', {
+            method: 'POST',
+            body: z__namespace.object({
+                testId: z__namespace.string()
+            }),
+            metadata: cmsMeta({
+                $Infer: {
+                    body: {}
+                }
+            }, {
+                operation: 'delete',
+                ...AB_TEST_META
+            })
+        }, async (reqCtx)=>{
+            const { db, scope } = reqCtx.context;
+            const tenantSlug = getTenantSlug(scope);
+            const test = await findTestOrThrow(db, reqCtx.body.testId, tenantSlug);
+            if (test.status !== 'draft' && test.status !== 'completed') {
+                abTestError('AB_TEST_INVALID_STATUS', 'Can only delete tests in draft or completed status');
+            }
+            await db.execute(drizzleOrm.sql`
+          DELETE FROM cms.ab_tests WHERE id = ${reqCtx.body.testId}
+        `);
+            return {
+                testId: reqCtx.body.testId
+            };
+        }),
+        getTest: createCMSEndpoint('/abTest/getTest', {
+            method: 'GET',
+            query: z__namespace.object({
+                testId: z__namespace.string()
+            }),
+            metadata: cmsMeta({
+                $Infer: {
+                    query: {}
+                }
+            }, {
+                operation: 'read',
+                ...AB_TEST_META
+            })
+        }, async (reqCtx)=>{
+            const { db, scope } = reqCtx.context;
+            const tenantSlug = getTenantSlug(scope);
+            const test = await findTestOrThrow(db, reqCtx.query.testId, tenantSlug);
+            const variants = await getVariantsForTest(db, test.id);
+            return {
+                ...mapTestRow(test),
+                variants: variants.map(mapVariantRow)
+            };
+        }),
+        /**
+     * M4 goal-picker: the pickable A/B goals for a root. Reads each block type's
+     * declared `events` (off the collection definitions) for the blocks present
+     * in the root's published tree, returning one candidate per (functional block
+     * instance × event). Candidates in the tested root's own tree are
+     * `inVaryingRoot: true`; candidates in embedded reusable blocks are
+     * `inVaryingRoot: false` (§6g attribution caution). The `name` is the
+     * resolved wire name (the same string fire() stores as event_type), so the
+     * UI-pickable goals are exactly the code-fireable events.
+     */ listGoalEvents: createCMSEndpoint('/abTest/listGoalEvents', {
+            method: 'GET',
+            query: z__namespace.object({
+                rootId: z__namespace.string()
+            }),
+            metadata: cmsMeta({
+                $Infer: {
+                    query: {}
+                }
+            }, {
+                operation: 'read',
+                ...AB_TEST_META
+            })
+        }, async (reqCtx)=>{
+            const { db, scope } = reqCtx.context;
+            const tenantSlug = getTenantSlug(scope);
+            const collections = getCollections();
+            const { rootId } = reqCtx.query;
+            const goals = [];
+            // The tested root's OWN tree → candidates in the varying render.
+            const own = await loadRootPublishedTree(db, rootId, tenantSlug);
+            if (own) {
+                const blocks = collections[own.collection]?.blocks ?? {};
+                collectGoalsFromTree(own.tree, blocks, rootId, true, goals);
+            }
+            // Embedded reusable blocks (down-only) → shared, co-rendered content;
+            // their goals are offered but flagged inVaryingRoot:false (§6g caution).
+            const resolver = scope.referenceResolver ?? coreReferenceResolver;
+            const scopeColumns = crossScopeColumns(scope.roots);
+            const embedded = await collectEmbeddedRoots(db, rootId, resolver, scopeColumns);
+            for (const embRootId of embedded){
+                const emb = await loadRootPublishedTree(db, embRootId, tenantSlug);
+                if (!emb) continue;
+                const blocks = collections[emb.collection]?.blocks ?? {};
+                collectGoalsFromTree(emb.tree, blocks, embRootId, false, goals);
+            }
+            return {
+                rootId,
+                goals
+            };
+        }),
+        listTests: createCMSEndpoint('/abTest/listTests', {
+            method: 'GET',
+            query: z__namespace.object({
+                collection: z__namespace.string().optional(),
+                status: z__namespace.enum([
+                    'draft',
+                    'running',
+                    'paused',
+                    'completed'
+                ]).optional(),
+                limit: z__namespace.coerce.number().int().min(1).max(100).optional().default(50),
+                offset: z__namespace.coerce.number().int().min(0).optional().default(0)
+            }),
+            metadata: cmsMeta({
+                $Infer: {
+                    query: {}
+                }
+            }, {
+                operation: 'read',
+                ...AB_TEST_META
+            })
+        }, async (reqCtx)=>{
+            const { db, scope } = reqCtx.context;
+            const tenantSlug = getTenantSlug(scope);
+            const { collection, status, limit, offset } = reqCtx.query;
+            const conditions = [
+                drizzleOrm.sql`1=1`
+            ];
+            if (collection) conditions.push(drizzleOrm.sql`t.collection = ${collection}`);
+            if (status) conditions.push(drizzleOrm.sql`t.status = ${status}`);
+            const tenantJoin = tenantSlug ? drizzleOrm.sql`INNER JOIN cms.roots r ON r.id = t.root_id` : drizzleOrm.sql``;
+            if (tenantSlug) {
+                conditions.push(drizzleOrm.sql`r.tenant_slug = ${tenantSlug}`);
+            }
+            const where = drizzleOrm.sql.join(conditions, drizzleOrm.sql` AND `);
+            const countResult = await db.execute(drizzleOrm.sql`
+          SELECT COUNT(*)::int AS total FROM cms.ab_tests t ${tenantJoin} WHERE ${where}
+        `);
+            const result = await db.execute(drizzleOrm.sql`
+          SELECT t.* FROM cms.ab_tests t
+          ${tenantJoin}
+          WHERE ${where}
+          ORDER BY t.created_at DESC
+          LIMIT ${limit} OFFSET ${offset}
+        `);
+            return {
+                tests: result.rows.map(mapTestRow),
+                total: countResult.rows[0].total,
+                hasMore: (offset ?? 0) + result.rows.length < countResult.rows[0].total
+            };
+        }),
+        assignVariant: createCMSEndpoint('/abTest/assignVariant', {
+            method: 'POST',
+            body: z__namespace.object({
+                testId: z__namespace.string(),
+                context: contextSchema
+            }),
+            metadata: cmsMeta({
+                $Infer: {
+                    body: {}
+                }
+            }, {
+                operation: 'read',
+                ...AB_TEST_META
+            })
+        }, async (reqCtx)=>{
+            const { db, scope } = reqCtx.context;
+            const tenantSlug = getTenantSlug(scope);
+            const { testId, context } = reqCtx.body;
+            const test = await findTestOrThrow(db, testId, tenantSlug);
+            if (test.status !== 'running') {
+                abTestError('AB_TEST_INVALID_STATUS', 'Can only assign variants for running tests');
+            }
+            const variants = await getVariantsForTest(db, testId);
+            const result = resolveVariant(context.key, testId, test.traffic_percentage, variants.map((v)=>({
+                    id: v.id,
+                    weight: v.weight,
+                    isControl: v.is_control
+                })));
+            const variant = variants.find((v)=>v.id === result.variantId);
+            return {
+                variantId: result.variantId,
+                branchId: variant?.branch_id ?? '',
+                inTest: result.inTest
+            };
+        }),
+        trackEvent: createCMSEndpoint('/abTest/trackEvent', {
+            method: 'POST',
+            body: z__namespace.object({
+                // A/B attribution is optional: non-A/B analytics events
+                // (form_submit, page_view) omit testId/variantId.
+                testId: z__namespace.string().optional(),
+                variantId: z__namespace.string().optional(),
+                // Pattern A: the edge/render route knows the served BRANCH, not the
+                // variant id. Sending branchId (with testId) resolves the variant id
+                // server-side — the FA4 impression beacon uses this.
+                branchId: z__namespace.string().optional(),
+                // Optional: the anonymous Pattern A path stores NO identifier (the
+                // variant comes from the URL/variant-cookie, not a visitor id). A
+                // visitor id is only sent for the consent-gated unique-visitor / GA4
+                // path.
+                visitorId: z__namespace.string().min(1).optional(),
+                anonymous: z__namespace.boolean().optional().default(false),
+                // Open vocabulary (blocks declare their own event names) but bounded,
+                // so this ingest path never accepts arbitrary unbounded input.
+                eventType: z__namespace.string().min(1).max(80),
+                metadata: z__namespace.record(z__namespace.string(), z__namespace.unknown()).optional().refine((m)=>!m || JSON.stringify(m).length <= 8192, {
+                    message: 'metadata exceeds 8KB'
+                }),
+                source: z__namespace.object({
+                    handle: z__namespace.string().max(128).optional(),
+                    type: z__namespace.string().max(128).optional()
+                }).optional(),
+                // Funnel grouping (M4): shared by the attempt + success legs of one
+                // interaction. Bounded; groups, does NOT dedup.
+                interactionId: z__namespace.string().min(1).max(128).optional(),
+                // GA4 stitching ids (M5): the client sends these ONLY when consent is
+                // granted, so the server-MP forward can attribute the hit. Bounded.
+                transport: z__namespace.object({
+                    clientId: z__namespace.string().min(1).max(128).optional(),
+                    sessionId: z__namespace.string().min(1).max(128).optional(),
+                    engagementTimeMsec: z__namespace.number().int().min(0).max(86_400_000).optional()
+                }).optional(),
+                // Consent Mode v2 state the client emitted under (optional). Used for
+                // a server-side denial guard + forwarded to consent-aware sinks.
+                consent: z__namespace.object({
+                    analytics_storage: z__namespace.enum([
+                        'granted',
+                        'denied'
+                    ]),
+                    ad_storage: z__namespace.enum([
+                        'granted',
+                        'denied'
+                    ]),
+                    ad_user_data: z__namespace.enum([
+                        'granted',
+                        'denied'
+                    ]),
+                    ad_personalization: z__namespace.enum([
+                        'granted',
+                        'denied'
+                    ])
+                }).optional()
+            }),
+            metadata: cmsMeta({
+                $Infer: {
+                    body: {}
+                }
+            }, {
+                operation: 'create',
+                ...AB_EVENT_META
+            })
+        }, async (reqCtx)=>{
+            const { db, scope } = reqCtx.context;
+            const tenantSlug = getTenantSlug(scope);
+            const { testId, variantId, branchId, visitorId, anonymous, eventType, metadata, source, interactionId, transport, consent } = reqCtx.body;
+            // Courtesy no-op for a self-reported denial: if a caller explicitly
+            // sends analytics_storage='denied', don't record. This is NOT a server
+            // enforcement boundary — `consent` is optional, so a caller can simply
+            // omit it. True server-read consent gating is deferred to M5; the client
+            // gate remains the consent authority.
+            if (consent && consent.analytics_storage === 'denied') {
+                return {};
+            }
+            let ab;
+            if (testId !== undefined || variantId !== undefined || branchId !== undefined) {
+                // A/B-attributed event: it must resolve to a variant that belongs to
+                // the test — otherwise a caller could record events against an
+                // arbitrary (or another test's) variant and poison the analytics.
+                if (!testId) {
+                    abTestError('AB_TEST_VARIANT_NOT_FOUND', 'A/B events require testId');
+                }
+                await findTestOrThrow(db, testId, tenantSlug);
+                const variants = await getVariantsForTest(db, testId);
+                // Accept either an explicit variantId or a branchId (Pattern A).
+                const resolvedVariantId = variantId ?? (branchId ? variants.find((v)=>v.branch_id === branchId)?.id : undefined);
+                if (!resolvedVariantId || !variants.some((v)=>v.id === resolvedVariantId)) {
+                    abTestError('AB_TEST_VARIANT_NOT_FOUND', 'A/B events require a variantId or a branchId that belongs to the test');
+                }
+                ab = {
+                    testId,
+                    variantId: resolvedVariantId
+                };
+            }
+            // The storage PK is always server-minted in M0 (id omitted here). A
+            // client-supplied, tenant-namespaced idempotency key — distinct from
+            // the PK — is an M3 concern (see AB_MEASUREMENT_DESIGN §9 carry-forward).
+            const event = {
+                name: eventType,
+                visitorId,
+                anonymous: anonymous ?? false,
+                ab,
+                source,
+                interactionId,
+                transport,
+                consent,
+                metadata,
+                timestamp: new Date()
+            };
+            await adapter.track(event);
+            // M5: opt-in server-side GA4 forward. No-op without a configured
+            // endpoint, or when the event is not a consenting, client_id-bearing hit
+            // (buildGa4Payload returns null). Best-effort — never breaks the ingest.
+            if (ga4Config) await forwardToGa4(event, ga4Config);
+            return {};
+        }),
+        getResults: createCMSEndpoint('/abTest/getResults', {
+            method: 'GET',
+            query: z__namespace.object({
+                testId: z__namespace.string(),
+                from: z__namespace.coerce.date().optional(),
+                to: z__namespace.coerce.date().optional()
+            }),
+            metadata: cmsMeta({
+                $Infer: {
+                    query: {}
+                }
+            }, {
+                operation: 'read',
+                ...AB_TEST_META
+            })
+        }, async (reqCtx)=>{
+            const { db, scope } = reqCtx.context;
+            const tenantSlug = getTenantSlug(scope);
+            const { testId, from, to } = reqCtx.query;
+            const test = await findTestOrThrow(db, testId, tenantSlug);
+            const results = await adapter.query(testId, {
+                from,
+                to
+            });
+            // M4: when the test has a chosen goal, count ITS event (the resolved
+            // wire name, already present in each variant's eventBreakdown) as the
+            // conversion + recompute the rate. The adapter's default 'conversion'
+            // eventType is the goal-less fallback (unchanged when no goal is set).
+            // `|| null` coerces a legacy/degenerate '' to the goal-less path.
+            const goal = test.goal_event || null;
+            if (goal) {
+                for (const v of results.variants){
+                    v.conversions = v.eventBreakdown[goal]?.count ?? 0;
+                    v.conversionRate = v.impressions > 0 ? Math.round(v.conversions / v.impressions * 10000) / 100 : 0;
+                    // Funnel (M4): of the interactions started (attempts = distinct
+                    // interaction ids), how many reached the goal event. 0 when the goal
+                    // is a non-funnel event (no interaction ids) → attempts is 0.
+                    const goalInteractions = v.eventBreakdown[goal]?.distinctInteractions ?? 0;
+                    v.completionRate = v.attempts > 0 ? Math.round(goalInteractions / v.attempts * 10000) / 100 : 0;
+                }
+                results.totalConversions = results.variants.reduce((s, v)=>s + v.conversions, 0);
+            }
+            return results;
+        }),
+        flushEvents: createCMSEndpoint('/abTest/flushEvents', {
+            method: 'POST',
+            body: z__namespace.object({
+                testId: z__namespace.string().optional()
+            }),
+            metadata: cmsMeta({
+                $Infer: {
+                    body: {}
+                }
+            }, {
+                operation: 'update',
+                ...AB_TEST_META
+            })
+        }, async (reqCtx)=>{
+            if (!adapter.flush) {
+                abTestError('AB_TEST_FLUSH_NOT_SUPPORTED');
+            }
+            if (reqCtx.body.testId) {
+                const { db, scope } = reqCtx.context;
+                const tenantSlug = getTenantSlug(scope);
+                await findTestOrThrow(db, reqCtx.body.testId, tenantSlug);
+            }
+            return adapter.flush(reqCtx.body.testId);
+        })
+    };
+}
+
+/**
+ * The ab-test plugin's implementation of the core {@link AbTestResolver} seam
+ * (Seam F): given a set of already render-resolved root ids, report which have a
+ * RUNNING test, with that test's variant branches. The read path uses this to
+ * fan a varying block's published branches out to the client (AB_FANOUT F2).
+ *
+ * Stateless — one instance is registered once via a scope factory in the
+ * plugin's `init`. Raw SQL (like {@link assertNoCoRenderConflictOnPublish}'s
+ * helper) because `cms.ab_tests` is plugin-owned and not in core's Drizzle
+ * schema. The `AB_TEST_DUPLICATE_RUNNING` guard ensures at most one running test
+ * per root, so grouping by root id is unambiguous.
+ */ function buildAbTestResolver() {
+    return {
+        async runningTests (db, scopeColumns, rootIds) {
+            const out = new Map();
+            if (rootIds.length === 0) return out;
+            // Scope the lookup to the active tenant (same predicate every other read
+            // applies): JOIN roots so rootScopeConditions can filter by the scope
+            // columns. The passed rootIds are already render-resolved, so this is
+            // defense-in-depth — it must never report a test on an out-of-scope root.
+            const scopeConds = rootScopeConditions(scopeColumns);
+            const result = await db.execute(drizzleOrm.sql`
+        SELECT t.id AS test_id, t.root_id, t.traffic_percentage,
+               v.branch_id, v.is_control
+        FROM cms.ab_tests t
+        JOIN cms.roots ON cms.roots.id = t.root_id
+        JOIN cms.ab_test_variants v ON v.test_id = t.id
+        WHERE t.status = 'running'
+          AND t.root_id IN (${drizzleOrm.sql.join(rootIds.map((r)=>drizzleOrm.sql`${r}`), drizzleOrm.sql`, `)})
+          ${scopeConds.length ? drizzleOrm.sql`AND ${drizzleOrm.sql.join(scopeConds, drizzleOrm.sql` AND `)}` : drizzleOrm.sql``}
+      `);
+            for (const row of result.rows){
+                let test = out.get(row.root_id);
+                if (!test) {
+                    test = {
+                        testId: row.test_id,
+                        trafficPercentage: row.traffic_percentage,
+                        variants: []
+                    };
+                    out.set(row.root_id, test);
+                }
+                // Defensive: a root has at most one running test (guarded), so ignore
+                // rows from any other test id rather than mixing variants.
+                if (test.testId !== row.test_id) continue;
+                test.variants.push({
+                    branchId: row.branch_id,
+                    isControl: row.is_control
+                });
+            }
+            return out;
+        }
+    };
+}
+
+// ============================================================================
+// Anonymous trackEvent ingest rate-limit (opt-in)
+// ============================================================================
+//
+// `/abTest/trackEvent` is the ONE unauthenticated write path: it is anonymous +
+// consent-free BY DESIGN (fresh ad traffic must record aggregate impression /
+// conversion counts without a session). Open + unauthenticated means a flood
+// can (a) SKEW the aggregate that decides the A/B winner — there is no visitor
+// id (consent-free), so volume is the only thing to defend on; (b) bloat the
+// `ab_test_events` table; and (c) — once server-MP (M5) is configured — amplify
+// into one outbound GA4 POST per event. This caps the ingest per client key, as
+// EARLY as possible (the plugin `onRequest`, before any routing/DB work).
+//
+// Opt-in via `abTest({ rateLimit })`. The default counter is in-memory (per
+// instance); for multiple instances / serverless, inject a distributed `store`.
+/**
+ * In-memory fixed-window counter. Memory is HARD-bounded at `maxKeys`: when a
+ * new key would exceed the cap, the oldest-inserted entry is evicted in O(1)
+ * (Map preserves insertion order) — so even a within-window flood of DISTINCT
+ * keys (e.g. an IP-rotating attacker) cannot grow the map past `maxKeys`, and
+ * there is no O(maxKeys) scan on the hot path. A live key being hit again is
+ * O(1) and never triggers eviction. Eviction can reset an old key's window
+ * under a flood (the standard bounded-limiter tradeoff). Per-instance only (see
+ * the module header) — inject a distributed store for multi-instance/serverless.
+ */ function createInMemoryRateLimitStore(maxKeys = 10_000) {
+    const windows = new Map();
+    return {
+        hit (key, windowMs, now) {
+            const entry = windows.get(key);
+            if (entry && now - entry.windowStart < windowMs) {
+                entry.count += 1;
+                return entry.count;
+            }
+            // New key, or its window expired → start a fresh window. Delete first so a
+            // re-set moves the key to the most-recent insertion position (it should
+            // not be the next eviction victim).
+            windows.delete(key);
+            if (windows.size >= maxKeys) {
+                // Hard cap: evict the oldest-inserted entry (front of the Map). O(1),
+                // bounds memory even when every resident key is still within its window.
+                const oldest = windows.keys().next().value;
+                if (oldest !== undefined) windows.delete(oldest);
+            }
+            windows.set(key, {
+                count: 1,
+                windowStart: now
+            });
+            return 1;
+        }
+    };
+}
+/**
+ * Default rate-limit key: the trusted client IP.
+ *
+ * `x-forwarded-for` is a client→proxy→…→server CHAIN. An appending proxy
+ * (Vercel, most CDNs) appends the real connecting IP as the LAST entry; the
+ * FIRST entry is whatever the client sent and is trivially spoofable. So we take
+ * the RIGHTMOST entry, never the first — using the leftmost would let an
+ * attacker rotate `x-forwarded-for` to mint a fresh bucket per request and evade
+ * the limit entirely. (This assumes ONE trusted appending proxy; behind multiple
+ * proxies or a non-appending one, override `getKey`.) Falls back to `x-real-ip`
+ * (set by nginx/Vercel to the connecting IP).
+ *
+ * Returns null when neither header is present — the caller then does NOT limit
+ * (fail-open). NOTE: a deployment NOT behind a proxy (a directly-exposed server
+ * with no `x-forwarded-for`/`x-real-ip`) therefore gets NO limiting from this
+ * default — provide a `getKey` that reads your real client IP.
+ */ function defaultRateLimitKey(request) {
+    const xff = request.headers.get('x-forwarded-for');
+    if (xff) {
+        const parts = xff.split(',').map((p)=>p.trim()).filter(Boolean);
+        if (parts.length > 0) return parts[parts.length - 1];
+    }
+    const realIp = request.headers.get('x-real-ip')?.trim();
+    return realIp ? realIp : null;
+}
+/**
+ * Enforces the ingest rate-limit for one request. Returns a 429 Response to
+ * short-circuit when the limit is exceeded, or null to let the request proceed.
+ * No-ops (null) when the key cannot be resolved. The caller (plugin onRequest)
+ * binds this to POST `/abTest/trackEvent`. `store` is created ONCE per plugin
+ * instance (never per request) so the window survives across requests.
+ */ async function enforceTrackEventRateLimit(request, options, store, now = Date.now()) {
+    const getKey = options.getKey ?? defaultRateLimitKey;
+    const key = getKey(request);
+    if (key === null) return null; // not rate-limited (no resolvable key)
+    const count = await store.hit(key, options.windowMs, now);
+    if (count <= options.limit) return null;
+    const retryAfterSec = Math.max(1, Math.ceil(options.windowMs / 1000));
+    return new Response(JSON.stringify({
+        error: 'rate_limited',
+        message: 'Too many A/B events; slow down.'
+    }), {
+        status: 429,
+        headers: {
+            'content-type': 'application/json',
+            'retry-after': String(retryAfterSec)
+        }
+    });
+}
+
+const CMS_ERRORS = {
+    BRANCH_NOT_FOUND: {
+        status: 404,
+        message: 'Branch not found'
+    },
+    BLOCK_NOT_FOUND: {
+        status: 404,
+        message: 'Block not found in snapshot'
+    },
+    PARENT_NOT_FOUND: {
+        status: 404,
+        message: 'Parent block not found'
+    },
+    ROOT_NOT_FOUND: {
+        status: 404,
+        message: 'Root block not found in snapshot'
+    },
+    ROOT_HAS_CHILDREN: {
+        status: 400,
+        message: 'Cannot delete a page that has child pages; archive or move the children first'
+    },
+    ROOT_IN_USE: {
+        status: 409,
+        message: 'Cannot delete: this root is embedded as a reusable block on live pages; remove those references first'
+    },
+    COMMIT_NOT_FOUND: {
+        status: 404,
+        message: 'Commit not found'
+    },
+    FOLDER_NOT_FOUND: {
+        status: 404,
+        message: 'Folder not found'
+    },
+    FOLDER_HAS_CONTENT: {
+        status: 400,
+        message: 'Cannot delete folder that contains assets or subfolders'
+    },
+    EMPTY_SNAPSHOT: {
+        status: 400,
+        message: 'Empty snapshot — no versions found'
+    },
+    BLOCK_ALREADY_DELETED: {
+        status: 400,
+        message: 'Block is already deleted'
+    },
+    TYPE_MISMATCH: {
+        status: 400,
+        message: 'Block type does not match the expected type'
+    },
+    USER_ID_REQUIRED: {
+        status: 400,
+        message: 'userId is required for this route when neither the request nor middleware provides one'
+    },
+    CANNOT_MOVE_ROOT: {
+        status: 400,
+        message: 'Cannot move the root block'
+    },
+    CANNOT_MOVE_INTO_SELF: {
+        status: 400,
+        message: 'Cannot move an item into itself'
+    },
+    CANNOT_MOVE_INTO_DESCENDANT: {
+        status: 400,
+        message: 'Cannot move an item into its own descendant'
+    },
+    MISSING_TARGET_PROPERTIES: {
+        status: 400,
+        message: 'targetProperties is required when duplicating a root'
+    },
+    BRANCH_NAME_ALREADY_EXISTS: {
+        status: 400,
+        message: 'A branch with this name already exists for this root'
+    },
+    CANNOT_RENAME_MAIN_BRANCH: {
+        status: 400,
+        message: 'The main branch cannot be renamed'
+    },
+    CANNOT_DELETE_MAIN_BRANCH: {
+        status: 400,
+        message: 'The main branch cannot be deleted'
+    },
+    BRANCH_HAS_PUBLICATIONS: {
+        status: 400,
+        message: 'Cannot delete a branch that has active publications'
+    },
+    BRANCH_HAS_OPEN_MERGE_REQUESTS: {
+        status: 400,
+        message: 'Cannot delete a branch that is part of open merge requests'
+    },
+    NO_COMMON_ANCESTOR: {
+        status: 400,
+        message: 'The two branches share no common ancestor'
+    },
+    MERGE_REQUEST_NOT_FOUND: {
+        status: 404,
+        message: 'Merge request not found'
+    },
+    MERGE_REQUEST_NOT_OPEN: {
+        status: 400,
+        message: 'Merge request is not open'
+    },
+    MERGE_REQUEST_NOT_CLOSED: {
+        status: 400,
+        message: 'Merge request is not closed'
+    },
+    MERGE_REQUEST_ALREADY_MERGED: {
+        status: 400,
+        message: 'Merge request has already been merged and cannot be reopened'
+    },
+    MERGE_REQUEST_ALREADY_EXISTS: {
+        status: 400,
+        message: 'An open merge request already exists for this source and target branch'
+    },
+    MERGE_REQUEST_OUTDATED: {
+        status: 400,
+        message: 'Merge request is outdated because the source branch changed after it was opened'
+    },
+    UNRESOLVED_CONFLICTS: {
+        status: 400,
+        message: 'Cannot merge: there are unresolved conflicts'
+    },
+    CONFLICT_NOT_FOUND: {
+        status: 404,
+        message: 'Merge conflict not found'
+    },
+    RESOLVED_VERSION_NOT_FOUND: {
+        status: 404,
+        message: 'The provided resolvedVersionId does not reference an existing block version'
+    },
+    APPROVAL_NOT_FOUND: {
+        status: 404,
+        message: 'Approval not found'
+    },
+    APPROVAL_ALREADY_REQUESTED: {
+        status: 400,
+        message: 'An approval has already been requested from this reviewer'
+    },
+    APPROVAL_NOT_PENDING: {
+        status: 400,
+        message: 'Approval is not pending'
+    },
+    APPROVAL_REVIEWER_MISMATCH: {
+        status: 403,
+        message: 'Only the requested reviewer can approve or reject this request'
+    },
+    APPROVAL_STALE: {
+        status: 400,
+        message: 'Approval is stale: the branch has advanced past the approved commit'
+    },
+    MERGE_APPROVAL_REQUIRED: {
+        status: 400,
+        message: 'Cannot merge: approval is required before execution'
+    },
+    PUBLICATION_APPROVAL_REQUIRED: {
+        status: 400,
+        message: 'Cannot publish: approval is required before publication'
+    },
+    APPROVALS_NOT_FULLY_APPROVED: {
+        status: 400,
+        message: 'Cannot proceed: not all requested approvals are approved'
+    },
+    BRANCHES_NOT_SAME_ROOT: {
+        status: 400,
+        message: 'Source and target branches must belong to the same root'
+    },
+    PUBLICATION_NOT_FOUND: {
+        status: 404,
+        message: 'Publication not found for this branch'
+    },
+    PUBLISHED_CONTENT_NOT_FOUND: {
+        status: 404,
+        message: 'No published content found'
+    },
+    AMBIGUOUS_SLUG: {
+        status: 400,
+        message: 'Multiple roots match this slug — use rootId for an unambiguous lookup'
+    },
+    DATA_RETENTION_NOT_CONFIGURED: {
+        status: 400,
+        message: 'dataRetention is not configured for this CMS instance'
+    },
+    MISSING_REQUIRED_S3_PARAMETERS: {
+        status: 400,
+        message: 'Missing required S3 parameters: hostname, accessKeyId, or secretAccessKey'
+    },
+    UNKNOWN_S3_PROVIDER: {
+        status: 400,
+        message: 'Unknown S3 provider specified'
+    },
+    SLUG_GENERATION_FAILED: {
+        status: 500,
+        message: 'Failed to generate a unique slug after maximum attempts'
+    },
+    TOO_MANY_FILES: {
+        status: 400,
+        message: 'Too many files in upload batch'
+    },
+    FILE_TOO_LARGE: {
+        status: 400,
+        message: 'One or more files exceed the maximum allowed size'
+    },
+    INVALID_FILE_TYPE: {
+        status: 400,
+        message: 'One or more files have a disallowed MIME type'
+    },
+    UPLOAD_FAILED: {
+        status: 500,
+        message: 'Server-side upload to S3 failed'
+    },
+    SLUG_ALREADY_EXISTS: {
+        status: 409,
+        message: 'A root with this slug on this collection with this parentRootId already exists'
+    },
+    SLUG_NOT_ENABLED: {
+        status: 400,
+        message: 'This collection does not have slugs enabled'
+    },
+    REDIRECT_NOT_FOUND: {
+        status: 404,
+        message: 'Redirect not found'
+    },
+    REDIRECT_INVALID: {
+        status: 400,
+        message: 'A redirect endpoint must be a page (rootId) or a path, matching its type'
+    },
+    REDIRECT_SOURCE_EXISTS: {
+        status: 409,
+        message: 'An active redirect already exists for this source'
+    },
+    SLUG_EMPTY_NOT_ALLOWED: {
+        status: 400,
+        message: 'Empty slug is not allowed for this collection (allowRoot is false)'
+    },
+    NESTING_NOT_ENABLED: {
+        status: 400,
+        message: 'parentRootId is not allowed — this collection does not have nested pages enabled'
+    },
+    CIRCULAR_REFERENCE: {
+        status: 400,
+        message: 'Cannot move a page under itself or one of its descendants'
+    },
+    PARENT_ROOT_NOT_FOUND: {
+        status: 404,
+        message: 'Parent root not found in this collection'
+    },
+    REFERENCE_DEPTH_EXCEEDED: {
+        status: 422,
+        message: 'Reference nesting is too deep (a reusable block embeds others past the limit)'
+    },
+    ASSET_NOT_FOUND: {
+        status: 404,
+        message: 'Asset not found'
+    },
+    VARIABLE_NOT_FOUND: {
+        status: 404,
+        message: 'Variable not found'
+    },
+    VARIABLE_KEY_EXISTS: {
+        status: 409,
+        message: 'A variable with this key already exists'
+    },
+    VARIABLE_IN_USE: {
+        status: 409,
+        message: 'Cannot delete variable: it is still in use'
+    },
+    TEMPLATE_NOT_FOUND: {
+        status: 404,
+        message: 'Template not found'
+    },
+    TEMPLATE_KEY_EXISTS: {
+        status: 409,
+        message: 'A template for this collection/block/property combination already exists'
+    },
+    ASSET_ACCESS_DENIED: {
+        status: 403,
+        message: 'This asset is private and requires authentication'
+    },
+    COMMENT_THREAD_NOT_FOUND: {
+        status: 404,
+        message: 'Comment thread not found'
+    },
+    COMMENT_THREAD_ALREADY_RESOLVED: {
+        status: 400,
+        message: 'Comment thread is already resolved'
+    },
+    COMMENT_THREAD_NOT_RESOLVED: {
+        status: 400,
+        message: 'Comment thread is not resolved'
+    },
+    COMMENT_MESSAGE_NOT_FOUND: {
+        status: 404,
+        message: 'Comment message not found'
+    },
+    COMMENT_MESSAGE_DELETED: {
+        status: 400,
+        message: 'Comment message has been deleted'
+    },
+    COMMENT_BODY_REQUIRED: {
+        status: 400,
+        message: 'Body is required for comment messages'
+    },
+    COMMENT_AUTHOR_MISMATCH: {
+        status: 403,
+        message: 'Only the author can edit or delete this message'
+    },
+    NOTIFICATION_NOT_FOUND: {
+        status: 404,
+        message: 'Notification not found'
+    },
+    NOTIFICATION_RECIPIENT_MISMATCH: {
+        status: 403,
+        message: 'You can only access your own notifications'
+    }
+};
+/**
+ * Type-safe CMS error that extends better-call's APIError.
+ * The `code` parameter is a string-literal union of all CMS error codes,
+ * so typos are caught at compile time.
+ */ class CMSError extends betterCall.APIError {
+    constructor(code, overrides){
+        const def = CMS_ERRORS[code];
+        super(def.status, {
+            message: overrides?.message ?? def.message,
+            code
+        });
+        this.cmsCode = code;
+    }
+}
+
+function normalizeSlug(raw) {
+    return slugify__default.default(raw, {
+        lower: true,
+        strict: true,
+        trim: true
+    });
+}
+/**
+ * Strip the collection root prefix from a URL path and split into segments.
+ * Optionally normalizes each segment when `slugConfig.normalize` is true.
+ */ function splitPath(slugConfig, path) {
+    const root = slugConfig.root.replace(/\/+$/, '');
+    let relative = path;
+    // Strip the collection root prefix only at a path boundary, so a sibling top
+    // path that merely string-starts with the root (e.g. '/pages-archive' vs root
+    // '/pages') is not mangled into '-archive'.
+    if (root && (relative === root || relative.startsWith(`${root}/`))) {
+        relative = relative.slice(root.length);
+    }
+    relative = relative.replace(/^\/+/, '').replace(/\/+$/, '');
+    if (!relative) return [];
+    const segments = relative.split('/');
+    return slugConfig.normalize ? segments.map(normalizeSlug) : segments;
+}
+/**
+ * Validate that a slug segment is unique among siblings in the same collection.
+ * Throws `SLUG_ALREADY_EXISTS` if a conflict is found.
+ */ const SAFE_SCOPE_COLUMN = /^[a-z_][a-z0-9_]*$/i;
+/**
+ * Resolve a URL path to a root ID by walking segments top-down using a recursive CTE.
+ * Returns null if no match is found.
+ */ async function resolvePathToRootId(db, collection, segments, scopeColumns) {
+    // Resolve the path WITHIN the active root scope: a scoping plugin's per-row
+    // scope columns (the same it stamps on insert) are ANDed in at EVERY level of
+    // the slug chain, so a shared slug in another scope neither matches nor causes
+    // ambiguity. Built as `r`-aliased predicates here because the CTE aliases
+    // cms.roots as `r` (a table-qualified scope `where` would not bind to `r`).
+    // Inert in single-scope installs (no columns). Mirrors validateSlugUniqueness.
+    const scopeConds = scopeColumns ? Object.entries(scopeColumns).flatMap(([col, val])=>{
+        if (val === undefined || val === null) return [];
+        if (!SAFE_SCOPE_COLUMN.test(col)) {
+            throw new Error(`resolvePathToRootId: unsafe scope column "${col}"`);
+        }
+        return [
+            drizzleOrm.sql`AND r.${drizzleOrm.sql.raw(col)} = ${val}`
+        ];
+    }) : [];
+    const scopeCondition = scopeConds.length > 0 ? drizzleOrm.sql.join(scopeConds, drizzleOrm.sql` `) : drizzleOrm.sql``;
+    if (segments.length === 0) {
+        const result = await db.execute(drizzleOrm.sql`
+      SELECT r.id FROM cms.roots r
+      WHERE r.collection = ${collection}
+        AND r.parent_root_id IS NULL
+        AND (r.slug IS NULL OR r.slug = '')
+        AND r.archived_at IS NULL
+        ${scopeCondition}
+      LIMIT 1
+    `);
+        return result.rows[0]?.id ?? null;
+    }
+    // Build a recursive CTE that walks segments one by one
+    const placeholders = segments.map((s, i)=>drizzleOrm.sql`(${i + 1}::int, ${s}::text)`);
+    const valuesClause = drizzleOrm.sql.join(placeholders, drizzleOrm.sql`, `);
+    const result = await db.execute(drizzleOrm.sql`
+    WITH RECURSIVE
+    path_segments(depth, segment) AS (
+      VALUES ${valuesClause}
+    ),
+    walk AS (
+      SELECT r.id, 1 AS depth
+      FROM cms.roots r
+      JOIN path_segments ps ON ps.depth = 1 AND ps.segment = r.slug
+      WHERE r.collection = ${collection}
+        AND r.parent_root_id IS NULL
+        AND r.archived_at IS NULL
+        ${scopeCondition}
+
+      UNION ALL
+
+      SELECT r.id, w.depth + 1
+      FROM cms.roots r
+      JOIN walk w ON r.parent_root_id = w.id
+      JOIN path_segments ps ON ps.depth = w.depth + 1 AND ps.segment = r.slug
+      WHERE r.collection = ${collection}
+        AND r.archived_at IS NULL
+        ${scopeCondition}
+    )
+    SELECT id FROM walk
+    WHERE depth = ${segments.length}
+    LIMIT 1
+  `);
+    return result.rows[0]?.id ?? null;
+}
+
+/**
+ * The per-collection `resolveAbVariant` endpoint (Seam A / FA1). Surfaces at
+ * `cms.api.<collection>.resolveAbVariant({ query: { path } })`. Lives as a
+ * collection endpoint so it has the collection's slug config for `splitPath`.
+ */ function createAbResolveEndpoints(def) {
+    const collectionName = def.name;
+    const slugCfg = def.slug;
+    return {
+        resolveAbVariant: createCMSEndpoint(`/${collectionName}/resolveAbVariant`, {
+            method: 'GET',
+            query: z__namespace.object({
+                path: z__namespace.string()
+            }),
+            metadata: cmsMeta({
+                $Infer: {
+                    query: {}
+                }
+            }, {
+                // Publicly readable (like getPublishedContent) so the edge can fetch
+                // + cache it without auth; carries no visitor-specific data.
+                permissionResource: 'publishedContent',
+                operation: 'read',
+                scope: 'collection',
+                collection: collectionName
+            })
+        }, async (reqCtx)=>{
+            // Pure function of (path, scope) — declared edge/CDN-cacheable. The
+            // DEFAULT abTestMiddleware fetch is NOT served by the Next.js Data Cache
+            // (a middleware-fetch caveat), so it runs this (cheap) query per request
+            // → test start/stop reflects on the edge ~immediately. The short s-maxage
+            // only bounds staleness IF some CDN/HTTP layer caches the response (then
+            // a test activates within ≤ s-maxage, serving valid control meanwhile —
+            // never wrong content; revalidateTag does NOT touch this HTTP cache). For
+            // guaranteed-instant activation AT SCALE, back the middleware's `resolve`
+            // with Edge Config / KV written on test start/stop (the injectable path).
+            // setHeader is a no-op off-request (direct server calls / tests).
+            reqCtx.setHeader('Cache-Control', 'public, s-maxage=10, stale-while-revalidate=30');
+            const { db, scope } = reqCtx.context;
+            const { path } = reqCtx.query;
+            if (!slugCfg?.enabled) return {
+                test: null
+            };
+            const rootId = await resolvePathToRootId(db, collectionName, splitPath(slugCfg, path), scope.roots?.insertColumns);
+            if (!rootId) return {
+                test: null
+            };
+            // The page's full render set: the page root + its transitive embeds
+            // (group-aware, cross-scope — a sibling-language/host embed still counts),
+            // mirroring the F1 XOR closure. The one running test among them varies
+            // this render.
+            const resolver = scope.referenceResolver ?? coreReferenceResolver;
+            const scopeColumns = crossScopeColumns(scope.roots);
+            const embeds = await collectEmbeddedRoots(db, rootId, resolver, scopeColumns);
+            const renderSet = [
+                rootId,
+                ...embeds
+            ];
+            // One query: the running test(s) on the render set, restricted to their
+            // PUBLISHED variant branches (JOIN publications — mirrors F2's skip of
+            // unpublished branches) and re-scoped to the active tenant (defense in
+            // depth; the render set is already scope-resolved).
+            const scopeConds = rootScopeConditions(scopeColumns);
+            const rows = await db.execute(drizzleOrm.sql`
+          SELECT t.id AS test_id, t.root_id, t.traffic_percentage,
+                 v.id AS variant_id, v.branch_id, v.weight, v.is_control
+          FROM cms.ab_tests t
+          JOIN cms.roots ON cms.roots.id = t.root_id
+          JOIN cms.ab_test_variants v ON v.test_id = t.id
+          JOIN cms.publications p
+            ON p.root_id = t.root_id AND p.branch_id = v.branch_id
+          WHERE t.status = 'running'
+            AND t.root_id IN (${drizzleOrm.sql.join(renderSet.map((r)=>drizzleOrm.sql`${r}`), drizzleOrm.sql`, `)})
+            ${scopeConds.length ? drizzleOrm.sql`AND ${drizzleOrm.sql.join(scopeConds, drizzleOrm.sql` AND `)}` : drizzleOrm.sql``}
+          ORDER BY t.root_id, v.id
+        `);
+            if (rows.rows.length === 0) return {
+                test: null
+            };
+            // Fail-closed: if the render set somehow carries >1 running test (an XOR
+            // breach / graph drift), serve control to everyone rather than pick one
+            // arbitrarily by root_id order.
+            const testIds = new Set(rows.rows.map((r)=>r.test_id));
+            if (testIds.size > 1) return {
+                test: null
+            };
+            const first = rows.rows[0];
+            // Dedup variants (a branch may have several publication rows).
+            const variantsById = new Map();
+            for (const r of rows.rows){
+                if (!variantsById.has(r.variant_id)) {
+                    variantsById.set(r.variant_id, {
+                        variantId: r.variant_id,
+                        branchId: r.branch_id,
+                        weight: r.weight,
+                        isControl: r.is_control
+                    });
+                }
+            }
+            const variants = [
+                ...variantsById.values()
+            ];
+            // Degrade to "no fan-out" (→ control) when fewer than two variant
+            // branches are published or the control branch is unpublished — exactly
+            // F2's loadPublishedRoots fallback.
+            if (variants.length < 2 || !variants.some((v)=>v.isControl)) {
+                return {
+                    test: null
+                };
+            }
+            return {
+                test: {
+                    testId: first.test_id,
+                    rootId: first.root_id,
+                    trafficPercentage: first.traffic_percentage,
+                    variants
+                }
+            };
+        })
+    };
+}
+
+/**
+ * Loads a root by id, scoped to the collection AND the active plugin scope
+ * (e.g. multi-tenant's `tenant_slug` predicate). Throws when the root does not
+ * exist or lies outside the caller's scope.
+ *
+ * This is the single choke point that closes IDOR on by-id endpoints: a caller in one scope
+ * cannot read or mutate a root in another scope by guessing its id, because the
+ * scope predicate is ANDed into the existence check. Pass the active
+ * transaction (or `db`) as `exec` so the guard participates in the same tx.
+ *
+ * Soft-archived roots (`archivedAt` set) are treated as gone: they are excluded
+ * here, so every by-id read/mutation 404s on an archived root. Physical removal
+ * is the pruning layer's job; deleteRoot and pruning query roots directly.
+ */ async function requireRootInScope(exec, rootId, collection, rootScope, // A core error code (default ROOT_NOT_FOUND) OR a factory returning the error
+// to throw — the latter lets a plugin raise its OWN error (e.g. the i18n
+// plugin's TRANSLATION_SOURCE_NOT_FOUND) without core naming a plugin code.
+notFound = 'ROOT_NOT_FOUND') {
+    const [row] = await exec.select({
+        id: roots.id
+    }).from(roots).where(drizzleOrm.and(drizzleOrm.eq(roots.id, rootId), drizzleOrm.eq(roots.collection, collection), drizzleOrm.isNull(roots.archivedAt), rootScope?.where)).limit(1);
+    if (!row) {
+        throw typeof notFound === 'function' ? notFound() : new CMSError(notFound);
+    }
+}
+
+function trackingError(code, message) {
+    throw new betterCall.APIError($ERROR_CODES[code].status, {
+        message: message ?? $ERROR_CODES[code].message,
+        code
+    });
+}
+/**
+ * Confirms the root is within the caller's scope BEFORE any block read, using
+ * the SAME authoritative predicate the core publishBranch handler trusts
+ * (`scope.roots.where` — tenant AND i18n language AND not-archived, via
+ * {@link requireRootInScope}). Returns false when the root is out of scope — the
+ * guard then no-ops and the core handler rejects with ROOT_NOT_FOUND. This keeps
+ * the unscoped before-hook from reading another scope's (tenant OR language)
+ * blocks. With no scope predicate (single-tenant, no i18n) every root is in
+ * scope, so the existence check just confirms the root exists.
+ */ async function rootIsInScope(db, rootId, collectionName, scope) {
+    try {
+        await requireRootInScope(db, rootId, collectionName, scope?.roots);
+        return true;
+    } catch (err) {
+        if (err instanceof CMSError) return false; // out of scope → guard no-ops
+        throw err;
+    }
+}
+/** Live (non-deleted) instances of the given block types at a branch's head. */ async function readFunctionalInstances(db, rootId, branchId, functionalTypes) {
+    if (functionalTypes.length === 0) return [];
+    const result = await db.execute(drizzleOrm.sql`
+    SELECT bv.block_id AS block_id,
+           bv.type AS type,
+           bv.properties ->> 'trackingId' AS tracking_id
+    FROM cms.branches b
+    JOIN cms.commit_snapshots cs ON cs.commit_id = b.head_commit_id
+    JOIN cms.block_versions bv ON bv.id = cs.block_version_id
+    WHERE b.id = ${branchId}
+      AND b.root_id = ${rootId}
+      AND bv.deleted = false
+      AND bv.type IN (${drizzleOrm.sql.join(functionalTypes.map((t)=>drizzleOrm.sql`${t}`), drizzleOrm.sql`, `)})
+  `);
+    return result.rows.map((r)=>({
+            blockId: r.block_id,
+            type: r.type,
+            trackingId: r.tracking_id
+        }));
+}
+/**
+ * Sibling variant branches that share a RUNNING test with `branchId` on this
+ * root. Scoped to the SAME test(s) the branch participates in (not every test
+ * on the root) and to `running` status only — so drift is enforced exactly
+ * where it renders, and editing variant branches of draft/paused/completed
+ * tests is never blocked.
+ */ async function getRunningSiblingBranchIds(db, rootId, branchId) {
+    const result = await db.execute(drizzleOrm.sql`
+    SELECT DISTINCT v2.branch_id AS branch_id
+    FROM cms.ab_test_variants v1
+    JOIN cms.ab_test_variants v2 ON v2.test_id = v1.test_id
+    JOIN cms.ab_tests t ON t.id = v1.test_id
+    WHERE v1.branch_id = ${branchId}
+      AND t.root_id = ${rootId}
+      AND t.status = 'running'
+      AND v2.branch_id <> ${branchId}
+  `);
+    return result.rows.map((r)=>r.branch_id);
+}
+/**
+ * Publish-time tracking-id guard for functional blocks. Runs as a `publishBranch`
+ * before-hook (so it aborts before any write), after confirming tenant ownership:
+ *  - MISSING:   every functional-block instance must have a non-empty trackingId.
+ *  - DUPLICATE: trackingIds must be unique within the branch.
+ *  - DRIFT:     when the branch shares a RUNNING test with sibling variant
+ *               branches, the SET of functional trackingIds must equal each
+ *               sibling's set — so a goal chosen in the UI exists in every arm
+ *               (set-equality policy; positional matching intentionally not
+ *               required).
+ */ async function assertTrackingIntegrity(opts) {
+    const { db, collections, collectionName, rootId, branchId, scope } = opts;
+    const blocks = collections[collectionName]?.blocks;
+    if (!blocks) return;
+    const functionalTypes = Object.entries(blocks).filter(([, def])=>def.events && Object.keys(def.events).length > 0).map(([type])=>type);
+    if (functionalTypes.length === 0) return;
+    // Scope ownership FIRST — never read another scope's blocks (tenant OR i18n
+    // language) from this unscoped before-hook.
+    if (!await rootIsInScope(db, rootId, collectionName, scope)) return;
+    const instances = await readFunctionalInstances(db, rootId, branchId, functionalTypes);
+    // 1. missing
+    for (const inst of instances){
+        if (!inst.trackingId || inst.trackingId.length === 0) {
+            trackingError('AB_TEST_TRACKING_ID_MISSING', `Functional block "${inst.blockId}" (${inst.type}) is missing its trackingId`);
+        }
+    }
+    // 2. duplicate within the branch
+    const seen = new Map();
+    for (const inst of instances){
+        const tid = inst.trackingId;
+        const prev = seen.get(tid);
+        if (prev) {
+            trackingError('AB_TEST_TRACKING_ID_DUPLICATE', `trackingId "${tid}" is used by both "${prev}" and "${inst.blockId}"`);
+        }
+        seen.set(tid, inst.blockId);
+    }
+    // 3. drift across the SAME running test's sibling variant branches.
+    const siblingBranchIds = await getRunningSiblingBranchIds(db, rootId, branchId);
+    if (siblingBranchIds.length === 0) return;
+    const thisSet = new Set(instances.map((i)=>i.trackingId));
+    for (const siblingId of siblingBranchIds){
+        const sibling = await readFunctionalInstances(db, rootId, siblingId, functionalTypes);
+        const siblingTracking = sibling.map((i)=>i.trackingId);
+        const siblingClean = siblingTracking.filter((t)=>!!t);
+        const siblingSet = new Set(siblingClean);
+        // A sibling arm must itself be cleanly anchored — no missing/empty and no
+        // intra-arm duplicate trackingId — else the count won't match its clean
+        // set. (A null/dup is only reachable from a sibling's live head ahead of its
+        // publish snapshot; treating it as drift fails closed.)
+        const siblingMisanchored = siblingClean.length !== siblingTracking.length || siblingSet.size !== siblingClean.length;
+        const sameSize = thisSet.size === siblingSet.size;
+        const subset = [
+            ...thisSet
+        ].every((t)=>siblingSet.has(t));
+        if (siblingMisanchored || !sameSize || !subset) {
+            trackingError('AB_TEST_TRACKING_ID_DRIFT', `trackingId set differs across A/B variant arms of a running test (branch "${siblingId}")`);
+        }
+    }
+}
+
+/** Root ids (of the given candidates) that currently have a running A/B test. */ async function runningTestRoots(db, rootIds) {
+    if (rootIds.length === 0) return new Set();
+    const rows = await db.execute(drizzleOrm.sql`
+    SELECT DISTINCT root_id FROM cms.ab_tests
+    WHERE status = 'running'
+      AND root_id IN (${drizzleOrm.sql.join(rootIds.map((r)=>drizzleOrm.sql`${r}`), drizzleOrm.sql`, `)})
+  `);
+    return new Set(rows.rows.map((r)=>r.root_id));
+}
+/**
+ * publishBranch TOCTOU backstop for the A/B XOR rule (AB_FANOUT_DESIGN §2.2).
+ * The start-time guard keeps any co-render closure at <=1 running test AT START,
+ * but a later publish can introduce an embed that makes two already-running
+ * tests co-render — which the start-time guard never saw.
+ *
+ * On publish of `rootId`, reject if publishing would create a render where >=2
+ * roots VARY. Precisely, a 2-axis render arises through `rootId` iff either:
+ *   (1) rootId's OWN render subtree (its group + transitive embeds) contains >=2
+ *       running tests; or
+ *   (2) a host that transcludes rootId varies AND rootId's subtree also varies
+ *       (the host's render then shows two varying axes through rootId).
+ * Two INDEPENDENT hosts of an untested shared block both running is NOT a
+ * conflict (they never co-render with each other) — so a flat closure count is
+ * wrong; we separate the subtree (down) from the hosts (up).
+ *
+ * Runs as an (unscoped) before-hook, so it verifies ownership FIRST via the same
+ * predicate the core handler trusts — never reading another tenant's/language's
+ * content; an out-of-scope root no-ops out (the core handler then rejects).
+ */ async function assertNoCoRenderConflictOnPublish(opts) {
+    const { db, collectionName, rootId, scope } = opts;
+    // Cross-scope columns (the plugin's cross-scope columns — e.g. language —
+    // removed): the co-render walk must span them (a host in any sibling scope
+    // co-renders), so they must not filter the walk's queries.
+    const scopeColumns = crossScopeColumns(scope?.roots);
+    const resolver = scope?.referenceResolver ?? coreReferenceResolver;
+    try {
+        await requireRootInScope(db, rootId, collectionName, scope?.roots);
+    } catch (err) {
+        if (err instanceof CMSError) return; // out of scope → core rejects
+        throw err;
+    }
+    const ownGroup = await resolver.expandGroup(db, scopeColumns, [
+        rootId
+    ]);
+    const subtree = await collectEmbeddedRoots(db, rootId, resolver, scopeColumns); // down only
+    const full = await collectCoRenderRoots(db, rootId, resolver, scopeColumns); // up + down
+    // up = full \ down (the hosts above rootId).
+    const up = new Set();
+    for (const r of full)if (!subtree.has(r)) up.add(r);
+    const running = await runningTestRoots(db, [
+        ...ownGroup,
+        ...full
+    ]);
+    // rootId's own render subtree (group + transitive embeds).
+    let subtreeRunning = 0;
+    for (const r of ownGroup)if (running.has(r)) subtreeRunning++;
+    for (const r of subtree)if (running.has(r)) subtreeRunning++;
+    let upRunning = 0;
+    for (const r of up)if (running.has(r)) upRunning++;
+    // (1) the published tree itself varies on >=2 axes, OR (2) a host above varies
+    // AND something in the published tree varies (they co-render through rootId).
+    if (subtreeRunning >= 2 || subtreeRunning >= 1 && upRunning >= 1) {
+        throw new betterCall.APIError($ERROR_CODES.AB_TEST_CROSS_EMBED_CONFLICT.status, {
+            message: $ERROR_CODES.AB_TEST_CROSS_EMBED_CONFLICT.message,
+            code: 'AB_TEST_CROSS_EMBED_CONFLICT'
+        });
+    }
+}
+
+/**
+ * The A/B measurement privacy-notice items. The `_ga` read is ALWAYS listed: the
+ * client reads `_ga` whenever `analytics_storage` is granted (to obtain the GA4
+ * client_id), independent of server-MP. Pass `ga4: true` when the server-MP
+ * forward (M5) is configured — it only changes the `_ga` recipient/purpose to
+ * name Google Analytics 4 as the destination of the forwarded hit.
+ * `variantCookiePrefix` must match the middleware's `variantCookiePrefix`.
+ */ function getPrivacyNoticeItems(options) {
+    const prefix = options?.variantCookiePrefix ?? 'ab_';
+    const items = [
+        {
+            name: `${prefix}<testId>`,
+            type: 'cookie',
+            purpose: 'Keeps the served A/B test variant consistent across requests — stores ONLY the variant code, no identifier.',
+            lifetime: '30 days',
+            isIdentifier: false,
+            // ePrivacy "strictly necessary": first-party, no behavioural data, never
+            // sent to a third party → no consent required.
+            consentRequired: null,
+            recipient: 'First-party (this site)'
+        },
+        {
+            name: 'ab_test_impressions',
+            type: 'sessionStorage',
+            purpose: 'Per-session dedup of anonymous A/B impression/goal beacons (which tests this tab already counted).',
+            lifetime: 'Session (cleared when the tab closes)',
+            isIdentifier: false,
+            consentRequired: null,
+            recipient: 'First-party (never transmitted)'
+        },
+        {
+            name: 'ab_test_vid',
+            type: 'cookie',
+            purpose: 'A unique visitor id for the consent-gated unique-visitor / GA4 path. Written only after consent.',
+            lifetime: '1 year',
+            isIdentifier: true,
+            consentRequired: 'analytics_storage',
+            recipient: 'First-party A/B store'
+        },
+        {
+            name: 'ab_test_assignments, ab_test_context',
+            type: 'localStorage',
+            purpose: "Persists the visitor's variant assignments + context after consent so they stay stable across visits.",
+            lifetime: 'Persistent (until cleared, or abTest.reset())',
+            isIdentifier: true,
+            consentRequired: 'analytics_storage',
+            recipient: 'First-party (never transmitted)'
+        },
+        {
+            name: '_ga, _ga_<stream>',
+            type: 'external-cookie-read',
+            // Always disclosed: the client reads `_ga` whenever analytics_storage is
+            // granted to obtain the GA4 client_id/session_id. Whether that id is then
+            // forwarded to GA4 depends on the server-MP (`ga4`) config — reflected in
+            // the recipient below.
+            purpose: options?.ga4 ? 'READ (never set by the CMS) to obtain the GA4 client_id / session_id, forwarded server-side via the Measurement Protocol.' : 'READ (never set by the CMS) to obtain the GA4 client_id / session_id for analytics stitching.',
+            lifetime: 'Per your Google Analytics configuration (typically 2 years)',
+            isIdentifier: true,
+            consentRequired: 'analytics_storage',
+            recipient: options?.ga4 ? 'Google Analytics 4 (via the server-MP forward)' : 'First-party A/B store'
+        }
+    ];
+    return items;
+}
+
+const _upstashRealtimeId = [
+    '@upstash',
+    'realtime'
+].join('/');
+const _importUpstashRealtime = ()=>new Function('id', 'return import(id)')(_upstashRealtimeId);
+const PLUGIN_ID = 'abTest';
+registerIdPrefix('abTest', 'abt');
+registerIdPrefix('abTestVariant', 'abv');
+registerIdPrefix('abTestEvent', 'abe');
+registerIdPrefix('abTestAgg', 'aba');
+function abTest(options) {
+    const adapter = options?.analytics ?? postgresAnalytics();
+    const schema = buildSchema(adapter);
+    // Created ONCE per plugin instance (never per request) so the rate-limit
+    // window survives across requests. In-memory unless a distributed store is
+    // injected. Undefined when rate-limiting is not configured.
+    const rateLimitStore = options?.rateLimit ? options.rateLimit.store ?? createInMemoryRateLimitStore() : undefined;
+    // Captured at init() — read by the publishBranch guard (which block types are
+    // functional) AND by the listGoalEvents endpoint (the goal-picker reads each
+    // block's declared `events`). A getter is threaded into the endpoint factory
+    // because the endpoints are built here, before init() populates this.
+    let pluginCollections = {};
+    const endpoints = createABTestEndpoints(adapter, ()=>pluginCollections, options?.ga4);
+    return {
+        id: PLUGIN_ID,
+        schema,
+        endpoints,
+        // FA1 (AB_FANOUT Pattern A): the edge-readable resolve seam, per collection.
+        collectionEndpoints: (def)=>createAbResolveEndpoints(def),
+        $ERROR_CODES,
+        hooks: {
+            before: [
+                {
+                    // Publish-time tracking-id integrity guard (missing/duplicate/drift).
+                    action: 'publishBranch',
+                    handler: async (ctx)=>{
+                        const rootId = ctx.input.rootId;
+                        const branchId = ctx.input.branchId;
+                        if (!rootId || !branchId) return;
+                        await assertTrackingIntegrity({
+                            db: ctx.db,
+                            collections: pluginCollections,
+                            collectionName: ctx.collection,
+                            rootId,
+                            branchId,
+                            scope: ctx.scope
+                        });
+                    }
+                },
+                {
+                    // XOR TOCTOU backstop: reject a publish that would make two running
+                    // tests co-render (AB_FANOUT_DESIGN §2.2).
+                    action: 'publishBranch',
+                    handler: async (ctx)=>{
+                        const rootId = ctx.input.rootId;
+                        if (!rootId) return;
+                        await assertNoCoRenderConflictOnPublish({
+                            db: ctx.db,
+                            collectionName: ctx.collection,
+                            rootId,
+                            scope: ctx.scope
+                        });
+                    }
+                }
+            ]
+        },
+        async init (ctx) {
+            pluginCollections = ctx.collections;
+            if (adapter.init) await adapter.init(ctx.db);
+            // Register the read-path running-test resolver (AB_FANOUT F2 server
+            // fan-out, Seam F). Stateless + request-independent, so a constant scope
+            // factory just hands the same instance to every request's resolved scope.
+            const abTestResolver = buildAbTestResolver();
+            return {
+                context: {
+                    scopeConditions: [
+                        ()=>({
+                                abTestResolver
+                            })
+                    ]
+                }
+            };
+        },
+        async onRequest (request, _ctx) {
+            const url = new URL(request.url);
+            // Rate-limit the anonymous trackEvent ingest as early as possible —
+            // before routing / auth / DB work — when configured. A 429 short-circuits.
+            if (rateLimitStore && options?.rateLimit && request.method === 'POST' && url.pathname.endsWith('/abTest/trackEvent')) {
+                const limited = await enforceTrackEventRateLimit(request, options.rateLimit, rateLimitStore);
+                if (limited) return {
+                    response: limited
+                };
+            }
+            const realtimeInstance = adapter.realtimeInstance;
+            if (!realtimeInstance) return;
+            if (!url.pathname.endsWith('/abTest/realtime')) return;
+            try {
+                const upstashRealtime = await _importUpstashRealtime();
+                const { handle } = upstashRealtime;
+                const handler = handle({
+                    realtime: realtimeInstance,
+                    middleware: async ({ channels })=>{
+                        for (const ch of channels){
+                            if (!ch.startsWith('ab:live:')) {
+                                return new Response('Invalid channel', {
+                                    status: 403
+                                });
+                            }
+                        }
+                    }
+                });
+                return {
+                    response: await handler(request)
+                };
+            } catch  {
+                return;
+            }
+        }
+    };
+}
+
+exports.$ERROR_CODES = $ERROR_CODES;
+exports.abTest = abTest;
+exports.buildGa4Payload = buildGa4Payload;
+exports.createInMemoryRateLimitStore = createInMemoryRateLimitStore;
+exports.defaultRateLimitKey = defaultRateLimitKey;
+exports.enforceTrackEventRateLimit = enforceTrackEventRateLimit;
+exports.forwardToGa4 = forwardToGa4;
+exports.getPrivacyNoticeItems = getPrivacyNoticeItems;
+exports.postgresAnalytics = postgresAnalytics;