@createcms/core 0.1.1

package/dist/plugins/i18n/index.js

@@ -0,0 +1,2150 @@
+import { APIError, createMiddleware, createEndpoint } from 'better-call';
+import { sql, inArray, and, eq, isNull, isNotNull, or } from 'drizzle-orm';
+import { customAlphabet } from 'nanoid';
+import * as z from 'zod';
+import { pgSchema, customType, timestamp, text, index, uniqueIndex, foreignKey, integer, boolean, jsonb, primaryKey } from 'drizzle-orm/pg-core';
+import slugify from 'slugify';
+
+const nanoid = 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()}`;
+}
+
+const cms$1 = pgSchema('cms');
+const tsvectorColumn = customType({
+    dataType () {
+        return 'tsvector';
+    }
+});
+const approvalStatusEnum = cms$1.enum("approval_status", [
+    "pending",
+    "approved",
+    "rejected"
+]);
+const assetStatusEnum = cms$1.enum("asset_status", [
+    "private",
+    "public"
+]);
+const commentMessageTypeEnum = cms$1.enum("comment_message_type", [
+    "comment",
+    "system"
+]);
+const commentSystemTypeEnum = cms$1.enum("comment_system_type", [
+    "threadResolved",
+    "threadReopened"
+]);
+const commentThreadStatusEnum = cms$1.enum("comment_thread_status", [
+    "open",
+    "resolved"
+]);
+const commentThreadTargetEnum = cms$1.enum("comment_thread_target", [
+    "mergeRequest",
+    "block"
+]);
+const conflictResolutionEnum = cms$1.enum("conflict_resolution", [
+    "source",
+    "target",
+    "manual"
+]);
+const contentUsageTargetEnum = cms$1.enum("content_usage_target", [
+    "asset",
+    "variable",
+    "reference"
+]);
+const mergeRequestStatusEnum = cms$1.enum("merge_request_status", [
+    "open",
+    "merged",
+    "closed"
+]);
+const notificationTypeEnum = cms$1.enum("notification_type", [
+    "mention",
+    "comment",
+    "threadResolved",
+    "approvalRequested",
+    "approvalApproved",
+    "approvalRejected",
+    "mergeRequestOpened",
+    "mergeRequestMerged",
+    "mergeRequestClosed",
+    "mergeRequestReopened",
+    "published",
+    "custom"
+]);
+const redirectEndpointTypeEnum = cms$1.enum("redirect_endpoint_type", [
+    "page",
+    "path"
+]);
+cms$1.table("approvals", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("approval")),
+    mergeRequestId: text("merge_request_id").references(()=>mergeRequests.id, {
+        onDelete: "cascade"
+    }),
+    branchId: text("branch_id").notNull().references(()=>branches.id),
+    commitId: text("commit_id").notNull().references(()=>commits.id),
+    status: approvalStatusEnum("status").notNull().default("pending"),
+    requestedBy: text("requested_by").notNull(),
+    requestedReviewer: text("requested_reviewer").notNull(),
+    reviewedBy: text("reviewed_by"),
+    message: text("message"),
+    rejectionReason: text("rejection_reason"),
+    reviewedAt: timestamp("reviewed_at"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow()
+}, (table)=>[
+        index("approvals_mr_idx").on(table.mergeRequestId),
+        index("approvals_branch_idx").on(table.branchId),
+        index("approvals_branch_commit_idx").on(table.branchId, table.commitId),
+        index("approvals_status_idx").on(table.status),
+        index("approvals_requested_reviewer_idx").on(table.requestedReviewer),
+        uniqueIndex("approvals_target_reviewer_unique").on(table.mergeRequestId, table.branchId, table.commitId, table.requestedReviewer)
+    ]);
+const assetFolders = cms$1.table("asset_folders", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("assetFolder")),
+    name: text("name").notNull(),
+    parentId: text("parent_id"),
+    createdBy: text("created_by"),
+    createdAt: timestamp("created_at").notNull().defaultNow()
+}, (table)=>[
+        foreignKey({
+            columns: [
+                table.parentId
+            ],
+            foreignColumns: [
+                table.id
+            ],
+            name: "asset_folders_parent_fk"
+        }).onDelete("cascade"),
+        index("asset_folders_parent_idx").on(table.parentId),
+        uniqueIndex("asset_folders_name_unique").on(table.parentId, table.name)
+    ]);
+const assets = cms$1.table("assets", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("asset")),
+    slug: text("slug").notNull(),
+    mimeType: text("mime_type").notNull(),
+    size: integer("size").notNull(),
+    objectKey: text("object_key").notNull(),
+    status: assetStatusEnum("status").notNull().default("private"),
+    folderId: text("folder_id").references(()=>assetFolders.id, {
+        onDelete: "set null"
+    }),
+    variantOf: text("variant_of").references(()=>assets.id, {
+        onDelete: "set null"
+    }),
+    uploadedBy: text("uploaded_by"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+    archivedAt: timestamp("archived_at")
+}, (table)=>[
+        index("assets_folder_idx").on(table.folderId),
+        index("assets_status_idx").on(table.status),
+        index("assets_variant_of_idx").on(table.variantOf),
+        uniqueIndex("assets_object_key_unique").on(table.objectKey),
+        uniqueIndex("assets_slug_unique").on(table.slug)
+    ]);
+const blockVersions = cms$1.table("block_versions", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("blockVersion")),
+    blockId: text("block_id").notNull(),
+    rootId: text("root_id").notNull().references(()=>roots.id),
+    commitId: text("commit_id").notNull().references(()=>commits.id),
+    type: text("type").notNull(),
+    properties: jsonb("properties").$type().notNull(),
+    children: jsonb("children").$type().notNull().default([]),
+    deleted: boolean("deleted").notNull().default(false),
+    createdAt: timestamp("created_at").notNull().defaultNow()
+}, (table)=>[
+        index("bv_block_id_idx").on(table.blockId),
+        index("bv_commit_id_idx").on(table.commitId),
+        index("bv_root_id_idx").on(table.rootId),
+        uniqueIndex("bv_block_commit_unique").on(table.blockId, table.commitId),
+        index("bv_properties_gin").using("gin", table.properties)
+    ]);
+const branches = cms$1.table("branches", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("branch")),
+    rootId: text("root_id").notNull().references(()=>roots.id),
+    name: text("name").notNull(),
+    headCommitId: text("head_commit_id").notNull().references(()=>commits.id),
+    createdBy: text("created_by"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow()
+}, (table)=>[
+        index("branches_root_id_idx").on(table.rootId),
+        uniqueIndex("branches_root_name_unique").on(table.rootId, table.name)
+    ]);
+cms$1.table("comment_mentions", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("commentMention")),
+    messageId: text("message_id").notNull().references(()=>commentMessages.id, {
+        onDelete: "cascade"
+    }),
+    threadId: text("thread_id").notNull().references(()=>commentThreads.id, {
+        onDelete: "cascade"
+    }),
+    mentionedUserId: text("mentioned_user_id").notNull(),
+    mentionedBy: text("mentioned_by").notNull(),
+    createdAt: timestamp("created_at").notNull().defaultNow()
+}, (table)=>[
+        index("cmn_user_idx").on(table.mentionedUserId, table.createdAt),
+        index("cmn_message_idx").on(table.messageId),
+        index("cmn_thread_user_idx").on(table.threadId, table.mentionedUserId),
+        uniqueIndex("cmn_message_user_unique").on(table.messageId, table.mentionedUserId)
+    ]);
+const commentMessages = cms$1.table("comment_messages", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("commentMessage")),
+    threadId: text("thread_id").notNull().references(()=>commentThreads.id, {
+        onDelete: "cascade"
+    }),
+    parentMessageId: text("parent_message_id"),
+    authorId: text("author_id"),
+    messageType: commentMessageTypeEnum("message_type").notNull().default("comment"),
+    systemType: commentSystemTypeEnum("system_type"),
+    body: text("body"),
+    meta: jsonb("meta").$type(),
+    editedAt: timestamp("edited_at"),
+    deletedAt: timestamp("deleted_at"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow()
+}, (table)=>[
+        foreignKey({
+            columns: [
+                table.parentMessageId
+            ],
+            foreignColumns: [
+                table.id
+            ],
+            name: "comment_messages_parent_fk"
+        }).onDelete("set null"),
+        index("cm_thread_idx").on(table.threadId, table.createdAt),
+        index("cm_parent_idx").on(table.parentMessageId),
+        index("cm_type_idx").on(table.messageType, table.systemType),
+        index("cm_author_idx").on(table.authorId, table.createdAt)
+    ]);
+const commentThreads = cms$1.table("comment_threads", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("commentThread")),
+    rootId: text("root_id").references(()=>roots.id, {
+        onDelete: "cascade"
+    }),
+    collection: text("collection").notNull(),
+    targetType: commentThreadTargetEnum("target_type").notNull(),
+    mergeRequestId: text("merge_request_id").references(()=>mergeRequests.id, {
+        onDelete: "cascade"
+    }),
+    blockId: text("block_id"),
+    commitId: text("commit_id").references(()=>commits.id, {
+        onDelete: "set null"
+    }),
+    status: commentThreadStatusEnum("status").notNull().default("open"),
+    resolvedBy: text("resolved_by"),
+    resolvedAt: timestamp("resolved_at"),
+    createdBy: text("created_by").notNull(),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+    deletedAt: timestamp("deleted_at")
+}, (table)=>[
+        index("ct_collection_idx").on(table.collection, table.createdAt),
+        index("ct_mr_idx").on(table.mergeRequestId, table.createdAt),
+        index("ct_block_idx").on(table.blockId, table.createdAt),
+        index("ct_commit_idx").on(table.commitId, table.createdAt),
+        index("ct_root_idx").on(table.rootId, table.createdAt),
+        index("ct_status_idx").on(table.status)
+    ]);
+const commits = cms$1.table("commits", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("commit")),
+    rootId: text("root_id").notNull().references(()=>roots.id),
+    parentCommitId: text("parent_commit_id"),
+    mergeSourceCommitId: text("merge_source_commit_id"),
+    message: text("message"),
+    createdBy: text("created_by"),
+    createdAt: timestamp("created_at").notNull().defaultNow()
+}, (table)=>[
+        foreignKey({
+            columns: [
+                table.parentCommitId
+            ],
+            foreignColumns: [
+                table.id
+            ],
+            name: "commits_parent_fk"
+        }),
+        foreignKey({
+            columns: [
+                table.mergeSourceCommitId
+            ],
+            foreignColumns: [
+                table.id
+            ],
+            name: "commits_merge_source_fk"
+        }),
+        index("commits_parent_idx").on(table.parentCommitId),
+        index("commits_merge_source_idx").on(table.mergeSourceCommitId),
+        index("commits_root_created_idx").on(table.rootId, table.createdAt)
+    ]);
+const commitSnapshots = cms$1.table("commit_snapshots", {
+    commitId: text("commit_id").notNull().references(()=>commits.id, {
+        onDelete: "cascade"
+    }),
+    blockId: text("block_id").notNull(),
+    blockVersionId: text("block_version_id").notNull().references(()=>blockVersions.id, {
+        onDelete: "cascade"
+    })
+}, (table)=>[
+        primaryKey({
+            columns: [
+                table.commitId,
+                table.blockId
+            ]
+        }),
+        index("cs_block_version_idx").on(table.blockVersionId)
+    ]);
+const contentUsages = cms$1.table("content_usages", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("contentUsage")),
+    targetKind: contentUsageTargetEnum("target_kind").notNull(),
+    targetKey: text("target_key").notNull(),
+    blockVersionId: text("block_version_id").notNull().references(()=>blockVersions.id, {
+        onDelete: "cascade"
+    }),
+    rootId: text("root_id").notNull().references(()=>roots.id, {
+        onDelete: "cascade"
+    }),
+    blockId: text("block_id").notNull(),
+    propertyKey: text("property_key").notNull()
+}, (table)=>[
+        uniqueIndex("cu_version_target_prop_unique").on(table.blockVersionId, table.targetKind, table.targetKey, table.propertyKey),
+        index("cu_target_idx").on(table.targetKind, table.targetKey),
+        index("cu_block_version_idx").on(table.blockVersionId),
+        index("cu_root_idx").on(table.rootId)
+    ]);
+cms$1.table("merge_conflicts", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("mergeConflict")),
+    mergeRequestId: text("merge_request_id").notNull().references(()=>mergeRequests.id, {
+        onDelete: "cascade"
+    }),
+    blockId: text("block_id").notNull(),
+    sourceVersionId: text("source_version_id").references(()=>blockVersions.id),
+    targetVersionId: text("target_version_id").references(()=>blockVersions.id),
+    baseVersionId: text("base_version_id").references(()=>blockVersions.id),
+    resolution: conflictResolutionEnum("resolution"),
+    resolvedVersionId: text("resolved_version_id").references(()=>blockVersions.id),
+    resolvedBy: text("resolved_by"),
+    resolvedAt: timestamp("resolved_at"),
+    createdAt: timestamp("created_at").notNull().defaultNow()
+}, (table)=>[
+        index("mc_merge_request_idx").on(table.mergeRequestId),
+        uniqueIndex("mc_merge_block_unique").on(table.mergeRequestId, table.blockId)
+    ]);
+const mergeRequests = cms$1.table("merge_requests", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("mergeRequest")),
+    rootId: text("root_id").notNull().references(()=>roots.id),
+    sourceBranchId: text("source_branch_id").notNull().references(()=>branches.id),
+    targetBranchId: text("target_branch_id").notNull().references(()=>branches.id),
+    sourceCommitId: text("source_commit_id").notNull().references(()=>commits.id),
+    baseCommitId: text("base_commit_id").references(()=>commits.id),
+    mergeCommitId: text("merge_commit_id").references(()=>commits.id),
+    status: mergeRequestStatusEnum("status").notNull().default("open"),
+    title: text("title"),
+    description: text("description"),
+    createdBy: text("created_by").notNull(),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow()
+}, (table)=>[
+        index("mr_root_idx").on(table.rootId),
+        index("mr_source_branch_idx").on(table.sourceBranchId),
+        index("mr_target_branch_idx").on(table.targetBranchId),
+        index("mr_status_idx").on(table.status),
+        uniqueIndex("mr_open_source_target_unique").on(table.sourceBranchId, table.targetBranchId).where(sql`status = 'open'`)
+    ]);
+cms$1.table("notifications", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("notification")),
+    recipientId: text("recipient_id").notNull(),
+    actorId: text("actor_id"),
+    type: notificationTypeEnum("type").notNull(),
+    title: text("title").notNull(),
+    body: text("body"),
+    resourceType: text("resource_type"),
+    resourceId: text("resource_id"),
+    collection: text("collection"),
+    meta: jsonb("meta").$type(),
+    readAt: timestamp("read_at"),
+    archivedAt: timestamp("archived_at"),
+    createdAt: timestamp("created_at").notNull().defaultNow()
+}, (table)=>[
+        index("ntf_recipient_created_idx").on(table.recipientId, table.createdAt),
+        index("ntf_recipient_unread_idx").on(table.recipientId, table.readAt),
+        index("ntf_resource_idx").on(table.resourceType, table.resourceId),
+        index("ntf_type_idx").on(table.type)
+    ]);
+cms$1.table("publications", {
+    rootId: text("root_id").notNull().references(()=>roots.id),
+    branchId: text("branch_id").notNull().references(()=>branches.id),
+    commitId: text("commit_id").notNull().references(()=>commits.id),
+    publishedBy: text("published_by").notNull(),
+    publishedAt: timestamp("published_at").notNull().defaultNow()
+}, (table)=>[
+        primaryKey({
+            columns: [
+                table.rootId,
+                table.branchId
+            ]
+        }),
+        index("publications_branch_idx").on(table.branchId)
+    ]);
+cms$1.table("redirects", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("redirect")),
+    collection: text("collection").notNull(),
+    sourceType: redirectEndpointTypeEnum("source_type").notNull(),
+    sourceRootId: text("source_root_id").references(()=>roots.id, {
+        onDelete: "cascade"
+    }),
+    sourcePath: text("source_path"),
+    targetType: redirectEndpointTypeEnum("target_type").notNull(),
+    targetRootId: text("target_root_id").references(()=>roots.id, {
+        onDelete: "cascade"
+    }),
+    targetPath: text("target_path"),
+    statusCode: integer("status_code").notNull().default(301),
+    createdBy: text("created_by"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+    archivedAt: timestamp("archived_at")
+}, (table)=>[
+        index("rdr_collection_source_path_idx").on(table.collection, table.sourcePath),
+        index("rdr_source_root_idx").on(table.sourceRootId),
+        index("rdr_collection_idx").on(table.collection),
+        index("rdr_archived_at_idx").on(table.archivedAt)
+    ]);
+const roots = cms$1.table("roots", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("root")),
+    collection: text("collection").notNull(),
+    parentRootId: text("parent_root_id"),
+    slug: text("slug"),
+    sortOrder: integer("sort_order").notNull().default(0),
+    createdBy: text("created_by"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    archivedAt: timestamp("archived_at"),
+    lastPrunedAt: timestamp("last_pruned_at")
+}, (table)=>[
+        foreignKey({
+            columns: [
+                table.parentRootId
+            ],
+            foreignColumns: [
+                table.id
+            ],
+            name: "roots_parent_fk"
+        }).onDelete("cascade"),
+        index("roots_collection_idx").on(table.collection),
+        index("roots_parent_root_idx").on(table.parentRootId),
+        index("roots_slug_idx").on(table.collection, table.parentRootId, table.slug),
+        index("roots_archived_at_idx").on(table.archivedAt),
+        index("roots_last_pruned_at_idx").on(table.lastPrunedAt)
+    ]);
+cms$1.table("search_index", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("si")),
+    entityType: text("entity_type").notNull(),
+    entityId: text("entity_id").notNull(),
+    collection: text("collection"),
+    rootId: text("root_id"),
+    contentVector: tsvectorColumn("content_vector").notNull(),
+    title: text("title"),
+    snippet: text("snippet"),
+    meta: jsonb("meta").$type(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow()
+}, (table)=>[
+        index("si_vector_gin").using("gin", table.contentVector),
+        index("si_entity_type_idx").on(table.entityType),
+        index("si_collection_idx").on(table.collection),
+        index("si_root_idx").on(table.rootId),
+        uniqueIndex("si_entity_unique").on(table.entityType, table.entityId)
+    ]);
+const templates = cms$1.table("templates", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("template")),
+    collection: text("collection").notNull(),
+    blockType: text("block_type").notNull(),
+    propertyKey: text("property_key").notNull(),
+    template: text("template").notNull(),
+    description: text("description"),
+    createdBy: text("created_by"),
+    updatedBy: text("updated_by"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow()
+}, (table)=>[
+        uniqueIndex("templates_collection_block_prop_unique").on(table.collection, table.blockType, table.propertyKey),
+        index("templates_collection_idx").on(table.collection),
+        index("templates_collection_block_idx").on(table.collection, table.blockType)
+    ]);
+cms$1.table("template_variable_usages", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("tplVarUsage")),
+    variableKey: text("variable_key").notNull(),
+    templateId: text("template_id").notNull().references(()=>templates.id, {
+        onDelete: "cascade"
+    })
+}, (table)=>[
+        uniqueIndex("tvu_key_template_unique").on(table.variableKey, table.templateId),
+        index("tvu_variable_key_idx").on(table.variableKey),
+        index("tvu_template_id_idx").on(table.templateId)
+    ]);
+cms$1.table("variables", {
+    id: text("id").primaryKey().$defaultFn(()=>newId("variable")),
+    key: text("key").notNull(),
+    value: text("value").notNull(),
+    description: text("description"),
+    createdBy: text("created_by"),
+    updatedBy: text("updated_by"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow()
+}, (table)=>[
+        uniqueIndex("variables_key_unique").on(table.key)
+    ]);
+
+const SAFE_IDENTIFIER = /^[a-z_][a-z0-9_.]*$/i;
+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(sql`"cms"."roots".${sql.raw(`"${col}"`)} = ${val}`);
+    }
+    return conds;
+}
+function assertSafeIdentifier(name) {
+    if (!SAFE_IDENTIFIER.test(name)) {
+        throw new Error(`Unsafe SQL identifier rejected: "${name}"`);
+    }
+}
+/**
+ * Builds a single raw SQL INSERT that includes both the Drizzle-known columns
+ * and any plugin-injected scope columns (e.g. `tenant_slug`) in one statement.
+ *
+ * Returns all columns via RETURNING *.
+ */ async function scopedInsert(db, tableName, values, scope) {
+    assertSafeIdentifier(tableName);
+    const merged = {
+        ...values,
+        ...scope?.insertColumns
+    };
+    const entries = Object.entries(merged);
+    const columns = sql.join(entries.map(([col])=>{
+        assertSafeIdentifier(col);
+        return sql.raw(`"${col}"`);
+    }), sql`, `);
+    const params = sql.join(entries.map(([, val])=>sql`${val ?? null}`), sql`, `);
+    const result = await db.execute(sql`INSERT INTO ${sql.raw(tableName)} (${columns}) VALUES (${params}) RETURNING *`);
+    if (!result.rows[0]) {
+        throw new Error(`scopedInsert into ${tableName} returned no rows`);
+    }
+    return result.rows[0];
+}
+
+// Asset ids are nanoids like `ast_<20 chars>`; the generic id shape is matched
+// then validated against the assets table (assetId is a real FK), so other ids
+// that happen to match are never inserted.
+const ASSET_ID_PATTERN = /^[a-z]{2,5}_[0-9a-z]{20}$/;
+/**
+ * Recursively collects candidate asset-id strings from a property value,
+ * descending into nested objects/arrays (galleries, rich-text reference nodes).
+ */ function collectAssetIdCandidates(value, out) {
+    if (typeof value === 'string') {
+        if (ASSET_ID_PATTERN.test(value)) out.add(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)collectAssetIdCandidates(item, out);
+        return;
+    }
+    if (value && typeof value === 'object') {
+        for (const v of Object.values(value)){
+            collectAssetIdCandidates(v, out);
+        }
+    }
+}
+/**
+ * Maps each top-level property key to the asset-id candidates found anywhere
+ * within its (possibly nested) value.
+ */ function extractAssetIdsFromProperties(properties) {
+    const result = new Map();
+    for (const [propKey, value] of Object.entries(properties)){
+        const found = new Set();
+        collectAssetIdCandidates(value, found);
+        if (found.size > 0) result.set(propKey, [
+            ...found
+        ]);
+    }
+    return result;
+}
+/**
+ * Inserts content_usages asset rows for newly-created block versions, within the same
+ * transaction that created them. Insert-only: there is no delete-then-reinsert
+ * (the branch-blind anti-pattern). MUST be called at EVERY block-version insert
+ * site (commit-writer's writeCommit + createInitialCommit, and merges'
+ * createMergeBlockVersion) — a version that references an asset but skips this
+ * call would be invisible to the GC, which could then delete a live asset.
+ *
+ * Candidates are validated against the assets table because assetId is an FK.
+ */ async function insertAssetReferencesForVersions(tx, rootId, versions) {
+    const pending = [];
+    const candidateIds = new Set();
+    for (const version of versions){
+        const extracted = extractAssetIdsFromProperties(version.properties);
+        for (const [propertyKey, ids] of extracted){
+            for (const id of ids){
+                pending.push({
+                    blockVersionId: version.blockVersionId,
+                    blockId: version.blockId,
+                    propertyKey,
+                    assetId: id
+                });
+                candidateIds.add(id);
+            }
+        }
+    }
+    if (pending.length === 0) return;
+    const realAssetIds = new Set((await tx.select({
+        id: assets.id
+    }).from(assets).where(inArray(assets.id, [
+        ...candidateIds
+    ]))).map((r)=>r.id));
+    if (realAssetIds.size === 0) return;
+    const rows = pending.filter((p)=>realAssetIds.has(p.assetId)).map((p)=>({
+            id: newId('contentUsage'),
+            targetKind: 'asset',
+            targetKey: p.assetId,
+            blockVersionId: p.blockVersionId,
+            rootId,
+            blockId: p.blockId,
+            propertyKey: p.propertyKey
+        }));
+    if (rows.length > 0) {
+        await tx.insert(contentUsages).values(rows).onConflictDoNothing();
+    }
+}
+
+/**
+ * Maps each `reference`-type property of a block (root or child) to the NAME of
+ * the collection it targets, by reading the collection definition. Shared by the
+ * read-time resolver (`resolveTreeReferences`, publications.ts) AND the write-time
+ * usage indexer below, so both agree on exactly which properties are references
+ * and where they point — a single source of truth.
+ */ function getReferencePropertyNames(collectionDef, blockType) {
+    const refProps = new Map();
+    if (blockType === collectionDef.name || blockType === 'root') {
+        for (const [key, spec] of Object.entries(collectionDef.root.properties)){
+            if (spec.type === 'reference') {
+                refProps.set(key, spec.collection);
+            }
+        }
+        return refProps;
+    }
+    const blockDef = collectionDef.blocks?.[blockType];
+    if (!blockDef) return refProps;
+    for (const [key, spec] of Object.entries(blockDef.properties)){
+        if (spec.type === 'reference') {
+            refProps.set(key, spec.collection);
+        }
+    }
+    return refProps;
+}
+/**
+ * Inserts content_usages `reference` rows for newly-created block versions, within
+ * the same transaction that created them — the third sibling of the asset and
+ * variable indexers (see core/content-index.ts). A reference is a top-level
+ * block property of type `reference` (per the collection def); its stored VALUE
+ * is the raw reference string (a `rot_` rootId, or under i18n a `tgr_`
+ * translationKey), recorded verbatim as `targetKey` so the reverse "who embeds
+ * me" query (RB2+) can match the anchor rootId directly.
+ *
+ * INSERT-only and keyed by the immutable blockVersionId, like its siblings. The
+ * `collectionDef` is REQUIRED (no default) so every version-insert site must
+ * thread it — a missed site would silently under-index, which is load-bearing for
+ * the reusable-block delete guard (RB4). Ships dark in RB1: rows populate, nothing
+ * reads them yet.
+ */ async function insertReferenceUsagesForVersions(tx, rootId, versions, collectionDef) {
+    const rows = [];
+    for (const version of versions){
+        const refProps = getReferencePropertyNames(collectionDef, version.type);
+        for (const [propKey] of refProps){
+            const value = version.properties[propKey];
+            if (typeof value !== 'string' || !value) continue;
+            rows.push({
+                id: newId('contentUsage'),
+                targetKind: 'reference',
+                targetKey: value,
+                blockVersionId: version.blockVersionId,
+                rootId,
+                blockId: version.blockId,
+                propertyKey: propKey
+            });
+        }
+    }
+    if (rows.length > 0) {
+        await tx.insert(contentUsages).values(rows).onConflictDoNothing();
+    }
+}
+
+const VAR_PATTERN = /\{\{(\w+)\}\}/g;
+/**
+ * Extracts all variable keys referenced in a string value.
+ * Returns a deduplicated array of keys.
+ */ function extractVariableKeys(value) {
+    const keys = new Set();
+    let match;
+    VAR_PATTERN.lastIndex = 0;
+    while((match = VAR_PATTERN.exec(value)) !== null){
+        keys.add(match[1]);
+    }
+    return [
+        ...keys
+    ];
+}
+/**
+ * Scans all string properties of a block and returns a map of
+ * propertyKey -> variableKeys[] for properties that contain {{...}} patterns.
+ */ function extractVariableKeysFromProperties(properties) {
+    const result = new Map();
+    for (const [propKey, value] of Object.entries(properties)){
+        if (typeof value !== 'string') continue;
+        const keys = extractVariableKeys(value);
+        if (keys.length > 0) {
+            result.set(propKey, keys);
+        }
+    }
+    return result;
+}
+/**
+ * Inserts content_usages variable rows for newly-created block versions, within the same
+ * transaction that created them. Insert-only and keyed by the immutable
+ * blockVersionId — the version-keyed counterpart of
+ * insertAssetReferencesForVersions; see its doc for why this replaces the old
+ * branch-blind delete-then-reinsert. MUST be called at every block-version
+ * insert site (variable keys are free text, so there is no FK to validate).
+ */ async function insertVariableUsagesForVersions(tx, rootId, versions) {
+    const rows = [];
+    for (const version of versions){
+        const extracted = extractVariableKeysFromProperties(version.properties);
+        for (const [propKey, varKeys] of extracted){
+            for (const varKey of varKeys){
+                rows.push({
+                    id: newId('contentUsage'),
+                    targetKind: 'variable',
+                    targetKey: varKey,
+                    blockVersionId: version.blockVersionId,
+                    rootId,
+                    blockId: version.blockId,
+                    propertyKey: propKey
+                });
+            }
+        }
+    }
+    if (rows.length > 0) {
+        await tx.insert(contentUsages).values(rows).onConflictDoNothing();
+    }
+}
+
+/**
+ * Single entry point that populates ALL content-derived usage indexes — the one
+ * generalist `content_usages` table (asset + variable rows today; reference rows
+ * from RB1) — for freshly-created block versions.
+ *
+ * These indexes are keyed by the immutable blockVersionId and are insert-only:
+ * they are written exactly once, here, in the same transaction that creates the
+ * versions, and are never re-synced (rows fall away by FK cascade when the
+ * version is pruned). Liveness is decided by joining to branch-head snapshots,
+ * so superseded versions simply stop counting without any delete.
+ *
+ * MUST be invoked at EVERY block-version insert site — the only three are
+ * commit-writer's writeCommit + createInitialCommit and merges'
+ * createMergeBlockVersion. A new insert site that forgets this call would make
+ * its content invisible to the GC (asset data-loss) and to the usage UI. The
+ * REQUIRED `collectionDef` (no default) is what the reference indexer needs to
+ * know which properties are references — keeping it required means the compiler
+ * flags any insert site that fails to thread it.
+ *
+ * Tombstones (deleted=true) carry old properties forward but never appear in a
+ * live view, so they are skipped — keeping the index to live-capable versions.
+ */ async function indexVersionContent(tx, rootId, versions, collectionDef) {
+    const live = versions.filter((v)=>!v.deleted);
+    if (live.length === 0) return;
+    const payload = live.map((v)=>({
+            blockVersionId: v.blockVersionId,
+            blockId: v.blockId,
+            type: v.type,
+            properties: v.properties
+        }));
+    await insertAssetReferencesForVersions(tx, rootId, payload);
+    await insertVariableUsagesForVersions(tx, rootId, payload);
+    await insertReferenceUsagesForVersions(tx, rootId, payload, collectionDef);
+}
+
+/**
+ * Write the very first commit of a new root: creates the commit (no parent),
+ * creates the `main` branch pointing at it, inserts every version, and writes a
+ * snapshot row per version (no copy-forward — there is no parent snapshot).
+ *
+ * Used by createRoot and the root-mode of duplicateBlock. The caller inserts the
+ * `roots` row itself (scopedInsert) before calling this.
+ */ async function createInitialCommit(tx, // See writeCommit — required so reference indexing is never silently skipped.
+collectionDef, args) {
+    const [commit] = await tx.insert(commits).values({
+        rootId: args.rootId,
+        message: args.message,
+        createdBy: args.createdBy
+    }).returning();
+    const [branch] = await tx.insert(branches).values({
+        rootId: args.rootId,
+        name: args.branchName ?? 'main',
+        headCommitId: commit.id,
+        createdBy: args.createdBy
+    }).returning();
+    const versionIdByBlockId = new Map();
+    if (args.versions.length > 0) {
+        const inserted = await tx.insert(blockVersions).values(args.versions.map((v)=>({
+                blockId: v.blockId,
+                rootId: args.rootId,
+                commitId: commit.id,
+                type: v.type,
+                properties: v.properties,
+                children: v.children,
+                deleted: v.deleted ?? false
+            }))).returning();
+        for (const v of inserted){
+            versionIdByBlockId.set(v.blockId, v.id);
+        }
+        await tx.insert(commitSnapshots).values(inserted.map((v)=>({
+                commitId: commit.id,
+                blockId: v.blockId,
+                blockVersionId: v.id
+            })));
+        await indexVersionContent(tx, args.rootId, inserted.map((v)=>({
+                blockVersionId: v.id,
+                blockId: v.blockId,
+                type: v.type,
+                properties: v.properties,
+                deleted: v.deleted
+            })), collectionDef);
+    }
+    return {
+        commitId: commit.id,
+        branchId: branch.id,
+        versionIdByBlockId
+    };
+}
+
+function deepCopySubtree(versionByBlockId, startBlockId) {
+    const idMap = new Map();
+    const collectIds = (blockId)=>{
+        idMap.set(blockId, newId('block'));
+        const version = versionByBlockId.get(blockId);
+        if (!version) return;
+        for (const childId of version.children ?? []){
+            collectIds(childId);
+        }
+    };
+    collectIds(startBlockId);
+    const copies = [];
+    const buildCopies = (blockId)=>{
+        const version = versionByBlockId.get(blockId);
+        if (!version) return;
+        const newBlockId = idMap.get(blockId);
+        const newChildren = (version.children ?? []).map((id)=>idMap.get(id));
+        copies.push({
+            oldBlockId: blockId,
+            newBlockId,
+            type: version.type,
+            properties: version.properties,
+            newChildren
+        });
+        for (const childId of version.children ?? []){
+            buildCopies(childId);
+        }
+    };
+    buildCopies(startBlockId);
+    return {
+        copies,
+        idMap
+    };
+}
+
+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 APIError {
+    constructor(code, overrides){
+        const def = CMS_ERRORS[code];
+        super(def.status, {
+            message: overrides?.message ?? def.message,
+            code
+        });
+        this.cmsCode = code;
+    }
+}
+
+/**
+ * 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(and(eq(roots.id, rootId), eq(roots.collection, collection), isNull(roots.archivedAt), rootScope?.where)).limit(1);
+    if (!row) {
+        throw typeof notFound === 'function' ? notFound() : new CMSError(notFound);
+    }
+}
+
+const cmsContext = createMiddleware(async ()=>{
+    return {};
+});
+const createCMSEndpoint = createEndpoint.create({
+    use: [
+        cmsContext
+    ]
+});
+function cmsMeta(base, cms) {
+    return {
+        ...base,
+        cms
+    };
+}
+
+function normalizeSlug(raw) {
+    return slugify(raw, {
+        lower: true,
+        strict: true,
+        trim: true
+    });
+}
+/**
+ * Build the full URL path for a root given its slug config and ancestor segments.
+ * `segments` is ordered root-to-leaf (e.g. ['about', 'team']).
+ */ function buildFullPath(slugConfig, segments) {
+    const root = slugConfig.root.replace(/\/+$/, '');
+    const joined = segments.filter(Boolean).join('/');
+    if (!joined) return root || '/';
+    return root ? `${root}/${joined}` : `/${joined}`;
+}
+/**
+ * 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;
+async function validateSlugUniqueness(db, collection, parentRootId, slug, excludeRootId, scopeColumns) {
+    const parentCondition = parentRootId === null ? sql`r.parent_root_id IS NULL` : sql`r.parent_root_id = ${parentRootId}`;
+    const excludeCondition = sql``;
+    // Authoritative app-level uniqueness over ALL active scope dimensions. The core
+    // slug index is non-unique, so THIS is the authority on every slug write. A
+    // scoping plugin passes its per-row scope columns (e.g. `language`,
+    // `tenant_slug` — the same values it stamps on insert), each ANDed in so the
+    // effective key is (…scope, collection, parentRootId, slug). Single-tenant
+    // installs pass nothing → global, identical to before. Plugin-owned columns are
+    // referenced via raw SQL (they don't exist in the core Drizzle type); the column
+    // name is validated as a safe identifier.
+    const scopeConds = scopeColumns ? Object.entries(scopeColumns).flatMap(([col, val])=>{
+        if (val === undefined || val === null) return [];
+        if (!SAFE_SCOPE_COLUMN.test(col)) {
+            throw new Error(`validateSlugUniqueness: unsafe scope column "${col}"`);
+        }
+        return [
+            sql`AND r.${sql.raw(col)} = ${val}`
+        ];
+    }) : [];
+    const scopeCondition = scopeConds.length > 0 ? sql.join(scopeConds, sql` `) : sql``;
+    const result = await db.execute(sql`
+    SELECT 1 FROM cms.roots r
+    WHERE r.collection = ${collection}
+      AND ${parentCondition}
+      AND r.slug = ${slug}
+      ${scopeCondition}
+      ${excludeCondition}
+    LIMIT 1
+  `);
+    if (result.rows.length > 0) {
+        throw new CMSError('SLUG_ALREADY_EXISTS');
+    }
+}
+/**
+ * Walk up the parent chain from a given root, returning ancestor rows
+ * ordered from the topmost ancestor down to (but not including) the given root.
+ *
+ * `scopeColumns` are plugin-owned per-scope columns (e.g. `tenant_slug`,
+ * `language`) that the walk must stay within: each is SELECTed in the anchor and
+ * the recursion is constrained to parents whose value MATCHES the starting root's
+ * (`p.<col> = a.<col>`). Combined with the always-on `collection` match, the walk
+ * can never cross a tenant/language/collection boundary on corrupted data — a
+ * defensive complement to the write-time parent validation. Column names are
+ * validated; pass `Object.keys(scope.roots.insertColumns)`.
+ */ async function resolveAncestors(db, rootId, scopeColumns) {
+    const cols = ([]).filter((c)=>SAFE_SCOPE_COLUMN.test(c));
+    const anchorSel = sql.join(cols.map((c)=>sql`, r.${sql.raw(c)}`), sql``);
+    const recSel = sql.join(cols.map((c)=>sql`, p.${sql.raw(c)}`), sql``);
+    const recMatch = sql.join(cols.map((c)=>sql`AND p.${sql.raw(c)} = a.${sql.raw(c)}`), sql` `);
+    const result = await db.execute(sql`
+    WITH RECURSIVE ancestors AS (
+      SELECT r.id, r.slug, r.parent_root_id, r.collection${anchorSel}, 0 AS depth
+      FROM cms.roots r
+      WHERE r.id = ${rootId}
+
+      UNION ALL
+
+      SELECT p.id, p.slug, p.parent_root_id, p.collection${recSel}, a.depth + 1
+      FROM cms.roots p
+      JOIN ancestors a ON a.parent_root_id = p.id
+      -- A root's parent is always same-collection (+ same tenant/language when
+      -- those plugins are active); enforcing it stops the walk from ever crossing
+      -- a scope boundary on corrupted data.
+      WHERE p.collection = a.collection ${recMatch}
+    )
+    SELECT id, slug, parent_root_id
+    FROM ancestors
+    WHERE id != ${rootId}
+    ORDER BY depth DESC
+  `);
+    return result.rows.map((row)=>({
+            rootId: row.id,
+            slug: row.slug,
+            parentRootId: row.parent_root_id
+        }));
+}
+
+/**
+ * Resolve a root to its CURRENT full path (from its live slug chain). Returns the
+ * archived flag and parent so a caller can fall back when the target is archived.
+ * `null` if the root no longer exists.
+ */ async function resolveRootPath(db, slugCfg, rootId, rootScope) {
+    const [root] = await db.select({
+        slug: roots.slug,
+        parentRootId: roots.parentRootId,
+        archivedAt: roots.archivedAt
+    }).from(roots)// Gate the target by the active scope (tenant + language) so a page-target
+    // pointing out of scope resolves to nothing rather than leaking its path —
+    // symmetric with the scoped source resolution (resolveScopedRootId).
+    .where(and(eq(roots.id, rootId), rootScope?.where)).limit(1);
+    if (!root) return null;
+    const ancestors = slugCfg.nested ? await resolveAncestors(db, rootId) : [];
+    const segments = [
+        ...ancestors.map((a)=>a.slug ?? ''),
+        root.slug ?? ''
+    ];
+    return {
+        path: buildFullPath(slugCfg, segments),
+        archived: root.archivedAt != null,
+        parentRootId: root.parentRootId
+    };
+}
+/** A page-reference's CURRENT path (for UI display), or `null` if the root is gone. */ async function resolveRootCurrentPath(db, slugCfg, rootId) {
+    return (await resolveRootPath(db, slugCfg, rootId))?.path ?? null;
+}
+
+/**
+ * Error codes owned by the i18n plugin (typed into the API error union via
+ * InferPluginErrorCodes when the plugin is installed). The LANGUAGE_* codes are
+ * raised by the scope factory; the TRANSLATION_* codes by the per-collection
+ * createTranslation/listTranslations endpoints.
+ *
+ * There is intentionally NO I18N_NOT_ENABLED code: createTranslation /
+ * listTranslations only EXIST when this plugin is installed (they are
+ * contributed via plugin.collectionEndpoints), so "i18n not enabled" is the
+ * structural absence of the endpoint, not a runtime error.
+ */ const $ERROR_CODES = {
+    LANGUAGE_REQUIRED: {
+        status: 400,
+        message: 'language is required -- authMiddleware must return { language } when the i18n plugin is active'
+    },
+    LANGUAGE_NOT_ENABLED: {
+        status: 400,
+        message: 'the resolved language is not one of the configured i18n languages'
+    },
+    TRANSLATION_SOURCE_NOT_FOUND: {
+        status: 404,
+        message: 'Translation source root not found in this collection / active language'
+    },
+    TRANSLATION_EXISTS: {
+        status: 409,
+        message: 'A translation in the target language already exists for this entry'
+    },
+    TRANSLATION_PARENT_NOT_TRANSLATED: {
+        status: 409,
+        message: 'The parent has no translation in the target language — translate the parent first'
+    },
+    TRANSLATION_LANGUAGE_NOT_ENABLED: {
+        status: 400,
+        message: 'targetLanguage is not one of the configured i18n languages'
+    }
+};
+/** Throw a typed i18n plugin error (mirrors ab-test's abTestError). */ function i18nError(code, message) {
+    throw new APIError($ERROR_CODES[code].status, {
+        message: $ERROR_CODES[code].message,
+        code
+    });
+}
+
+/**
+ * The i18n plugin's per-collection endpoints (Seam A): createTranslation +
+ * listTranslations. Contributed to EVERY collection via plugin.collectionEndpoints,
+ * so they surface at cms.api.<collection>.x ONLY when the i18n plugin is
+ * installed (closing the leak where they appeared on every collection regardless).
+ *
+ * These were lifted from core/routes/blocks.ts verbatim, with two changes:
+ *   - i18n error codes (TRANSLATION_*) are thrown via i18nError (APIError + the
+ *     plugin's own $ERROR_CODES) instead of CMSError; core slug codes
+ *     (SLUG_EMPTY_NOT_ALLOWED) stay as CMSError (still a core code).
+ *   - the old I18N_NOT_ENABLED gate is gone: the endpoint only exists when this
+ *     plugin is installed, and the i18n scope factory rejects a request with no
+ *     active language (LANGUAGE_REQUIRED) before the handler runs.
+ */ function createI18nCollectionEndpoints(def, pluginCtx, languages) {
+    const collectionName = def.name;
+    const db = pluginCtx.db;
+    return {
+        // i18n: create the sibling-language version of an existing entry. The new
+        // root INHERITS the source's translationKey (so it joins the group), takes
+        // the TARGET language, and hangs under the target-language sibling of the
+        // source's parent. Seeds from the source's `main` tree by default ('copy'),
+        // or starts blank.
+        /**
+     * Creates a sibling-language version of an existing entry, inheriting its translation key and seeding from the source's main tree (or blank).
+     * @param sourceRootId The root to translate from (must exist in the active language).
+     * @param targetLanguage The language for the new root (must be configured in the plugin).
+     * @param targetSlug Optional slug for the target root; defaults to the source slug if not provided.
+     * @param seed How to initialize the target root's draft: 'copy' (default) copies the source's main tree, 'blank' starts empty.
+     * @param message Optional commit message for the initial draft; defaults to 'Translation (language)'.
+     * @returns The new root id, draft branch id, initial commit id, target language, and inherited translation key.
+     * @throws TRANSLATION_LANGUAGE_NOT_ENABLED if targetLanguage is not in the configured language universe.
+     * @throws TRANSLATION_SOURCE_NOT_FOUND if sourceRootId does not exist in the active language/tenant.
+     * @throws TRANSLATION_EXISTS if a translation to targetLanguage already exists for this entry.
+     * @throws TRANSLATION_PARENT_NOT_TRANSLATED if the source has a parent that has no translation in the target language.
+     * @throws SLUG_EMPTY_NOT_ALLOWED if the target slug is empty and the collection disallows root slugs.
+     * @example await cmsClient.pages.createTranslation({ sourceRootId: 'root_abc', targetLanguage: 'de', seed: 'copy' })
+     */ createTranslation: createCMSEndpoint(`/${collectionName}/createTranslation`, {
+            method: 'POST',
+            body: z.object({
+                sourceRootId: z.string(),
+                targetLanguage: z.string().min(1),
+                targetSlug: z.string().optional(),
+                seed: z.enum([
+                    'copy',
+                    'blank'
+                ]).optional(),
+                message: z.string().optional()
+            }),
+            metadata: cmsMeta({
+                $Infer: {
+                    body: {}
+                }
+            }, {
+                permissionResource: 'root',
+                operation: 'create',
+                scope: 'collection',
+                collection: collectionName
+            })
+        }, async (ctx)=>{
+            const { userId, scope } = ctx.context;
+            const actor = userId;
+            const { sourceRootId, targetLanguage, message } = ctx.body;
+            // The target language must be in the configured universe (the plugin's
+            // own `languages`, closed in at assembly) — otherwise we'd stamp a root
+            // with a language no routing could ever serve.
+            if (!languages.includes(targetLanguage)) {
+                i18nError('TRANSLATION_LANGUAGE_NOT_ENABLED');
+            }
+            const seed = ctx.body.seed ?? 'copy';
+            const slugCfg = def.slug;
+            return db.transaction(async (tx)=>{
+                // Source must exist in the ACTIVE language — you translate FROM your
+                // current language context.
+                await requireRootInScope(tx, sourceRootId, collectionName, scope.roots, ()=>i18nError('TRANSLATION_SOURCE_NOT_FOUND'));
+                // Source metadata incl. the plugin-owned translation_key (raw SQL).
+                const srcRows = await tx.execute(sql`
+            SELECT slug, parent_root_id, translation_key
+            FROM cms.roots
+            WHERE id = ${sourceRootId} AND collection = ${collectionName}
+          `);
+                const src = srcRows.rows[0];
+                if (!src) i18nError('TRANSLATION_SOURCE_NOT_FOUND');
+                // No existing sibling in the target language (also rejects translating
+                // to the source's own language, since that sibling is the source). The
+                // (translationKey, language) partial unique is the DB backstop for the
+                // race this app check can't cover.
+                const dup = await tx.execute(sql`
+            SELECT 1 FROM cms.roots
+            WHERE translation_key = ${src.translation_key}
+              AND language = ${targetLanguage}
+              AND collection = ${collectionName}
+              AND archived_at IS NULL
+            LIMIT 1
+          `);
+                if (dup.rows.length > 0) i18nError('TRANSLATION_EXISTS');
+                // Target parent = the target-language sibling of the source's parent.
+                // The collection filters are defense-in-depth (a root's parent chain is
+                // always same-collection by write-time validation), mirroring createRoot.
+                let targetParentRootId = null;
+                if (src.parent_root_id !== null) {
+                    const parentRows = await tx.execute(sql`
+              SELECT translation_key FROM cms.roots
+              WHERE id = ${src.parent_root_id} AND collection = ${collectionName}
+            `);
+                    const parentKey = parentRows.rows[0]?.translation_key;
+                    if (!parentKey) {
+                        i18nError('TRANSLATION_PARENT_NOT_TRANSLATED');
+                    }
+                    const sib = await tx.execute(sql`
+              SELECT id FROM cms.roots
+              WHERE translation_key = ${parentKey}
+                AND language = ${targetLanguage}
+                AND collection = ${collectionName}
+                AND archived_at IS NULL
+              LIMIT 1
+            `);
+                    const sibRow = sib.rows[0];
+                    if (!sibRow) i18nError('TRANSLATION_PARENT_NOT_TRANSLATED');
+                    targetParentRootId = sibRow.id;
+                }
+                // Target slug (localized; defaults to the source slug), unique per
+                // target language under the target parent.
+                let targetSlug = null;
+                if (slugCfg?.enabled) {
+                    const rawSlug = ctx.body.targetSlug ?? src.slug ?? '';
+                    targetSlug = slugCfg.normalize ? normalizeSlug(rawSlug) : rawSlug;
+                    if (!targetSlug && !slugCfg.allowRoot) {
+                        throw new CMSError('SLUG_EMPTY_NOT_ALLOWED');
+                    }
+                    await validateSlugUniqueness(tx, collectionName, targetParentRootId, targetSlug, undefined, // Uniqueness is checked in the TARGET language (not the active one),
+                    // within the active tenant — override language on the scope columns.
+                    {
+                        ...scope.roots?.insertColumns ?? {},
+                        language: targetLanguage
+                    });
+                }
+                // Create the sibling root: TARGET language (override the active-language
+                // insert-scope), INHERITED translationKey, keep any other scope columns
+                // (e.g. tenant_slug).
+                const targetScope = {
+                    ...scope.roots,
+                    insertColumns: {
+                        ...scope.roots?.insertColumns ?? {},
+                        language: targetLanguage
+                    }
+                };
+                const newRoot = await scopedInsert(tx, 'cms.roots', {
+                    id: newId('root'),
+                    collection: collectionName,
+                    parent_root_id: targetParentRootId,
+                    slug: targetSlug,
+                    sort_order: 0,
+                    created_by: actor,
+                    translation_key: src.translation_key
+                }, targetScope);
+                // Seed the initial commit: copy the source's `main` tree as the starting
+                // draft, or start blank.
+                let versions;
+                if (seed === 'copy') {
+                    const [mainBranch] = await tx.select({
+                        headCommitId: branches.headCommitId
+                    }).from(branches).where(and(eq(branches.rootId, sourceRootId), eq(branches.name, 'main'))).limit(1);
+                    if (mainBranch) {
+                        const snaps = await tx.select({
+                            blockVersionId: commitSnapshots.blockVersionId
+                        }).from(commitSnapshots).where(eq(commitSnapshots.commitId, mainBranch.headCommitId));
+                        const ids = snaps.map((s)=>s.blockVersionId);
+                        if (ids.length > 0) {
+                            const allV = await tx.select().from(blockVersions).where(inArray(blockVersions.id, ids));
+                            const byId = new Map(allV.map((v)=>[
+                                    v.blockId,
+                                    {
+                                        blockId: v.blockId,
+                                        type: v.type,
+                                        properties: v.properties,
+                                        children: v.children ?? [],
+                                        deleted: v.deleted
+                                    }
+                                ]));
+                            const { copies } = deepCopySubtree(byId, sourceRootId);
+                            versions = copies.map((copy)=>{
+                                const isTop = copy.oldBlockId === sourceRootId;
+                                return {
+                                    blockId: isTop ? newRoot.id : copy.newBlockId,
+                                    type: isTop ? collectionName : copy.type,
+                                    properties: copy.properties,
+                                    children: copy.newChildren
+                                };
+                            });
+                        }
+                    }
+                }
+                if (!versions) {
+                    versions = [
+                        {
+                            blockId: newRoot.id,
+                            type: collectionName,
+                            properties: {},
+                            children: []
+                        }
+                    ];
+                }
+                const { commitId, branchId } = await createInitialCommit(tx, def, {
+                    rootId: newRoot.id,
+                    message: message ?? `Translation (${targetLanguage})`,
+                    createdBy: actor,
+                    versions
+                });
+                return {
+                    rootId: newRoot.id,
+                    branchId,
+                    commitId,
+                    language: targetLanguage,
+                    translationKey: src.translation_key
+                };
+            });
+        }),
+        // i18n: the language switcher / "which translations exist" for an entry.
+        // Cross-language by design (queries the translation group), so it deliberately
+        // bypasses the blanket per-language read scope — but the INPUT root is gated to
+        // the active language + tenant, and a translationKey is a globally-unique
+        // group id, so only this tenant's siblings are returned.
+        /**
+     * Retrieves all language variants (siblings) of a given entry, bypassing per-language read scope.
+     * @param rootId The root id (must exist in the active language and tenant).
+     * @returns The translation key (group id) and an array of all siblings with their language, root id, slug, and resolved path.
+     * @throws TRANSLATION_SOURCE_NOT_FOUND if rootId does not exist or has no translation key.
+     * @example await cmsClient.pages.listTranslations({ rootId: 'root_abc' })
+     */ listTranslations: createCMSEndpoint(`/${collectionName}/listTranslations`, {
+            method: 'GET',
+            query: z.object({
+                rootId: z.string()
+            }),
+            metadata: cmsMeta({
+                $Infer: {
+                    query: {}
+                }
+            }, {
+                permissionResource: 'root',
+                operation: 'read',
+                scope: 'collection',
+                collection: collectionName
+            })
+        }, async (ctx)=>{
+            const { scope } = ctx.context;
+            const slugCfg = def.slug;
+            // The input root must be in the active language + tenant.
+            await requireRootInScope(db, ctx.query.rootId, collectionName, scope.roots);
+            const keyRows = await db.execute(sql`
+          SELECT translation_key FROM cms.roots
+          WHERE id = ${ctx.query.rootId} AND collection = ${collectionName}
+        `);
+            const translationKey = keyRows.rows[0]?.translation_key;
+            if (!translationKey) {
+                i18nError('TRANSLATION_SOURCE_NOT_FOUND');
+            }
+            const sibRows = await db.execute(sql`
+          SELECT id, language, slug FROM cms.roots
+          WHERE translation_key = ${translationKey}
+            AND collection = ${collectionName}
+            AND archived_at IS NULL
+          ORDER BY language
+        `);
+            const translations = await Promise.all(sibRows.rows.map(async (r)=>({
+                    language: r.language,
+                    rootId: r.id,
+                    slug: r.slug,
+                    path: slugCfg?.enabled && slugCfg ? await resolveRootCurrentPath(db, slugCfg, r.id) : null
+                })));
+            return {
+                translationKey,
+                translations
+            };
+        })
+    };
+}
+
+const cms = pgSchema('cms');
+/**
+ * Typed Drizzle handle for the `cms.roots` columns the i18n resolver queries,
+ * INCLUDING the plugin-owned `language` + `translation_key` — which the core
+ * generated `roots` object does NOT carry (they are contributed only by
+ * `i18nSchema`'s add-only merge). Drizzle permits multiple table objects over
+ * one physical table; this is the i18n plugin's typed VIEW for resolution
+ * queries. It is NOT a schema source — migrations come from `i18nSchema`.
+ */ const i18nRoots = cms.table('roots', {
+    id: text('id').primaryKey(),
+    collection: text('collection').notNull(),
+    archivedAt: timestamp('archived_at'),
+    language: text('language').notNull(),
+    translationKey: text('translation_key').notNull()
+});
+
+/**
+ * The i18n plugin's reference resolver (Seam B). Owns ALL translation-group
+ * resolution: a stored reference value (`rot_` rootId or `tgr_` group key) is
+ * resolved to the rootId(s) it relates to, honouring the active language + its
+ * fallback chain. Core carries this on the resolved scope and rides it from the
+ * read path and the A/B co-render walk; without the i18n plugin core uses its
+ * own identity default and none of this code runs.
+ *
+ * Because the i18n factory builds this ONLY when a language is active, the impl
+ * assumes i18n is on (no `'language' in scopeColumns` self-gate) and queries the
+ * plugin-owned `language` / `translation_key` columns through a TYPED roots view
+ * (D5) instead of raw SQL — tenant scoping reuses the generic
+ * `rootScopeConditions` (language excluded), so there is no raw tenant predicate.
+ *
+ * Closes over the active `language` + `fallback` chain (the resolution policy);
+ * `db` + `scopeColumns` (the merged tenant predicate) arrive per call.
+ *   - resolveRenderTargets: tgr_ → best sibling along [language, ...fallback];
+ *     rot_ → active-language sibling of its group, else the stored anchor;
+ *     other values → themselves.
+ *   - resolveConflictTargets: the whole-group SUPERSET a key could render as
+ *     (the A/B co-render conflict set).
+ *   - expandGroup / groupKeysFor: translation-group expansion / its `tgr_` keys.
+ */ function buildI18nReferenceResolver(language, fallback) {
+    const languageChain = [
+        language,
+        ...fallback
+    ];
+    return {
+        async resolveRenderTargets (db, scopeColumns, collection, storedValues) {
+            const tenantConds = rootScopeConditions(scopeColumns, [
+                'language'
+            ]);
+            const valueToRootId = new Map();
+            const tgrValues = [];
+            const rotValues = [];
+            for (const value of storedValues){
+                if (value.startsWith('tgr_')) tgrValues.push(value);
+                else if (value.startsWith('rot_')) rotValues.push(value);
+                else valueToRootId.set(value, value); // unknown prefix — used as-is
+            }
+            if (tgrValues.length > 0) {
+                // One query for all keys across all chain languages; pick the sibling
+                // whose language is highest in the chain.
+                const rows = await db.select({
+                    id: i18nRoots.id,
+                    translationKey: i18nRoots.translationKey,
+                    language: i18nRoots.language
+                }).from(i18nRoots).where(and(inArray(i18nRoots.translationKey, tgrValues), inArray(i18nRoots.language, languageChain), eq(i18nRoots.collection, collection), isNull(i18nRoots.archivedAt), ...tenantConds));
+                const rank = new Map(languageChain.map((l, i)=>[
+                        l,
+                        i
+                    ]));
+                const best = new Map();
+                for (const r of rows){
+                    const rk = rank.get(r.language) ?? Number.POSITIVE_INFINITY;
+                    const cur = best.get(r.translationKey);
+                    if (!cur || rk < cur.rank) best.set(r.translationKey, {
+                        id: r.id,
+                        rank: rk
+                    });
+                }
+                for (const value of tgrValues){
+                    const b = best.get(value);
+                    if (b) valueToRootId.set(value, b.id); // missing in all chain langs → unresolved
+                }
+            }
+            if (rotValues.length > 0) {
+                // 1) stored anchor → its translation group key (tenant-scoped; NOT
+                //    archived-filtered — the anchor itself may be archived).
+                const groupRows = await db.select({
+                    id: i18nRoots.id,
+                    translationKey: i18nRoots.translationKey
+                }).from(i18nRoots).where(and(inArray(i18nRoots.id, rotValues), eq(i18nRoots.collection, collection), ...tenantConds));
+                const groupByRot = new Map();
+                for (const r of groupRows)groupByRot.set(r.id, r.translationKey);
+                // 2) each group → its ACTIVE-language sibling (only).
+                const groupKeys = [
+                    ...new Set(groupByRot.values())
+                ];
+                const siblingByGroup = new Map();
+                if (groupKeys.length > 0) {
+                    const sibRows = await db.select({
+                        id: i18nRoots.id,
+                        translationKey: i18nRoots.translationKey
+                    }).from(i18nRoots).where(and(inArray(i18nRoots.translationKey, groupKeys), eq(i18nRoots.language, language), eq(i18nRoots.collection, collection), isNull(i18nRoots.archivedAt), ...tenantConds));
+                    for (const r of sibRows)siblingByGroup.set(r.translationKey, r.id);
+                }
+                // 3) anchor → active-language sibling, else the stored anchor itself.
+                for (const value of rotValues){
+                    const group = groupByRot.get(value);
+                    const sibling = group ? siblingByGroup.get(group) : undefined;
+                    valueToRootId.set(value, sibling ?? value);
+                }
+            }
+            return valueToRootId;
+        },
+        async resolveConflictTargets (db, scopeColumns, storedKeys) {
+            return resolveReferenceTargets(db, storedKeys, scopeColumns);
+        },
+        async expandGroup (db, _scopeColumns, rootIds) {
+            return [
+                ...await expandTranslationGroups(db, rootIds)
+            ];
+        },
+        async groupKeysFor (db, _scopeColumns, rootIds) {
+            return groupTranslationKeys(db, rootIds);
+        }
+    };
+}
+/**
+ * Expand a set of rootIds to ALL their translation-group siblings. A reference
+ * stores a `rot_` anchor but the read-time auto-upgrade renders the active-
+ * language sibling, so the co-render check must treat the whole group as one
+ * logical block. `translation_key` is a globally-unique, tenant-bound group id
+ * → no tenant predicate needed.
+ */ async function expandTranslationGroups(db, rootIds) {
+    const out = new Set(rootIds);
+    if (rootIds.length === 0) return out;
+    const groupKeys = db.select({
+        translationKey: i18nRoots.translationKey
+    }).from(i18nRoots).where(inArray(i18nRoots.id, rootIds));
+    const rows = await db.select({
+        id: i18nRoots.id
+    }).from(i18nRoots).where(inArray(i18nRoots.translationKey, groupKeys));
+    for (const r of rows)out.add(r.id);
+    return out;
+}
+/**
+ * The translation-group key(s) (`tgr_`) for a set of roots. A host may embed the
+ * group via a `tgr_` key rather than a `rot_` rootId, so the co-render up-walk
+ * match set must include these.
+ */ async function groupTranslationKeys(db, rootIds) {
+    if (rootIds.length === 0) return [];
+    const rows = await db.selectDistinct({
+        translationKey: i18nRoots.translationKey
+    }).from(i18nRoots).where(and(inArray(i18nRoots.id, rootIds), isNotNull(i18nRoots.translationKey)));
+    return rows.map((r)=>r.translationKey);
+}
+/**
+ * Resolve reference targetKeys (`rot_` rootIds OR `tgr_` group keys) to the
+ * rootIds they actually RENDER — expanding a `tgr_` to its whole group (a
+ * conservative superset; the read path picks one sibling, we keep all).
+ * Tenant-scoped: an author-typed foreign rootId resolves to nothing → the
+ * co-render set never crosses tenants.
+ */ async function resolveReferenceTargets(db, keys, scopeColumns) {
+    if (keys.length === 0) return [];
+    const rows = await db.select({
+        id: i18nRoots.id
+    }).from(i18nRoots).where(and(or(inArray(i18nRoots.id, keys), inArray(i18nRoots.translationKey, keys)), isNull(i18nRoots.archivedAt), ...rootScopeConditions(scopeColumns, [
+        'language'
+    ])));
+    return rows.map((r)=>r.id);
+}
+
+function definePluginSchema(schema) {
+    return {
+        ...schema
+    };
+}
+
+/**
+ * Plugin schema for i18n: adds the plugin-owned `language` column to `roots`
+ * (one root per language — each language reuses the full engine) plus the
+ * per-language slug uniqueness the core can no longer provide.
+ *
+ * The core `slugUniqueIdx` was demoted to a non-unique lookup index (phase I1)
+ * precisely BECAUSE a core GLOBAL unique on (collection, parentRootId, slug)
+ * cannot be loosened by a plugin and would forbid the same slug across
+ * languages. So the real DB guarantee for same-slug-per-language lives here.
+ * Non-partial (archived rows still occupy the slug) to match the demoted core
+ * index's behaviour; app-level validateSlugUniqueness is the authority and is
+ * likewise non-archived-filtered.
+ *
+ * Caveat (unchanged from the old core unique): a NULL `parentRootId` is DISTINCT
+ * in Postgres, so this index only backstops NESTED roots. Top-level
+ * per-language uniqueness is enforced by validateSlugUniqueness alone (which
+ * matches `parent_root_id IS NULL` explicitly) — exactly as it always was.
+ */ const i18nSchema = definePluginSchema({
+    extend: {
+        roots: {
+            columns: {
+                language: {
+                    type: 'text',
+                    notNull: true
+                },
+                // Stable group id tying sibling-language roots into one logical entry.
+                // A NEW entry (createRoot / root duplication) mints a fresh `tgr_` id;
+                // createTranslation (I3b) inherits it. Indexed with language to resolve
+                // "the sibling of this entry in language L" / "which languages exist" in
+                // one hop.
+                translationKey: {
+                    type: 'text',
+                    notNull: true
+                }
+            },
+            indexes: {
+                languageSlugUnique: {
+                    columns: [
+                        'language',
+                        'collection',
+                        'parentRootId',
+                        'slug'
+                    ],
+                    unique: true
+                },
+                languageCollectionIdx: {
+                    columns: [
+                        'language',
+                        'collection'
+                    ]
+                },
+                // At most ONE active root per (group, language) — the DB backstop for
+                // the "one sibling per language" invariant that createTranslation's
+                // app-level check enforces (and the race it can't). PARTIAL (archived
+                // rows excluded) so archiving a translation frees the slot, matching the
+                // app check. Doubles as the lookup index for "the sibling in language L".
+                // translationKey is a globally-unique group id, so no tenant column is
+                // needed even under multi-tenant.
+                translationLanguageUnique: {
+                    columns: [
+                        'translationKey',
+                        'language'
+                    ],
+                    unique: true,
+                    where: 'archived_at IS NULL'
+                }
+            }
+        },
+        // Redirects are per-language. No DB-unique is added here: path-source
+        // uniqueness can't be DB-enforced when BOTH multi-tenant and i18n are on
+        // (the correct key (tenant_slug, language, collection, sourcePath) can't be
+        // expressed by either plugin alone), so it is the app-level authority
+        // (assertSourceUnique + the auto-create pre-check, both scope.redirects-aware).
+        redirects: {
+            columns: {
+                language: {
+                    type: 'text',
+                    notNull: true
+                }
+            },
+            indexes: {
+                languageCollectionIdx: {
+                    columns: [
+                        'language',
+                        'collection'
+                    ]
+                }
+            }
+        }
+    }
+});
+
+// The translation-group id prefix is owned by this plugin (core no longer
+// declares it). Registered at import so newId('translationGroup') works in
+// the per-new-entry mint below.
+registerIdPrefix('translationGroup', 'tgr');
+/**
+ * Resolves the active language from the incoming request context.
+ * Priority: body.language -> query.language -> fallback.
+ *
+ * The CMS is routing-agnostic: HOW you derive the language (URL prefix `/de`,
+ * domain, Accept-Language header, cookie) is the consumer's middleware concern.
+ * This helper only reads an explicit per-request override; pass the negotiated
+ * default as `fallback`.
+ */ function resolveLanguage(ctx, fallback) {
+    return ctx.request?.body?.language ?? ctx.request?.query?.language ?? fallback;
+}
+/**
+ * Read the resolved i18n context (active language + fallback chain + configured
+ * universe) from a ResolvedScope. The plugin's own accessor for the OPAQUE
+ * `pluginContext.i18n` slot it stashes per request (Seam C); core never names
+ * i18n. Undefined when the i18n plugin did not scope the request.
+ */ function getI18nContext(scope) {
+    return scope?.pluginContext?.['i18n'];
+}
+const PLUGIN_ID = 'i18n';
+/**
+ * The ordered fallback chain for `activeLang` — languages to try AFTER it, with
+ * the active language removed and duplicates dropped.
+ */ function resolveFallbackChain(config, activeLang) {
+    const fb = config.fallback;
+    const base = fb?.[activeLang] ?? fb?.default ?? [
+        config.defaultLanguage
+    ];
+    const seen = new Set([
+        activeLang
+    ]);
+    const chain = [];
+    for (const l of base){
+        if (!seen.has(l)) {
+            seen.add(l);
+            chain.push(l);
+        }
+    }
+    return chain;
+}
+function i18n(config) {
+    const universe = new Set(config.languages);
+    if (!universe.has(config.defaultLanguage)) {
+        throw new Error(`i18n: defaultLanguage "${String(config.defaultLanguage)}" must be one of languages [${config.languages.join(', ')}]`);
+    }
+    // Catch fallback-config typos at construction (like defaultLanguage): keys must
+    // be a configured language or 'default'; every chain entry must be a language.
+    if (config.fallback) {
+        for (const [key, chain] of Object.entries(config.fallback)){
+            if (key !== 'default' && !universe.has(key)) {
+                throw new Error(`i18n: fallback key "${key}" is not one of languages [${config.languages.join(', ')}]`);
+            }
+            for (const lang of chain ?? []){
+                if (!universe.has(lang)) {
+                    throw new Error(`i18n: fallback for "${key}" references unknown language "${lang}"`);
+                }
+            }
+        }
+    }
+    return {
+        id: PLUGIN_ID,
+        schema: i18nSchema,
+        $ERROR_CODES,
+        // Per-collection endpoints (Seam A): createTranslation / listTranslations
+        // surface at cms.api.<collection>.x only because this plugin is installed.
+        // The configured language universe is closed in here so the endpoints
+        // validate a target language without reading per-request scope.
+        collectionEndpoints: (def, ctx)=>createI18nCollectionEndpoints(def, ctx, config.languages),
+        init (_ctx) {
+            const factory = (mwResult)=>{
+                const language = mwResult.language;
+                if (typeof language !== 'string' || language.length === 0) {
+                    throw new APIError(400, {
+                        message: $ERROR_CODES.LANGUAGE_REQUIRED.message,
+                        code: 'LANGUAGE_REQUIRED'
+                    });
+                }
+                if (!universe.has(language)) {
+                    throw new APIError(400, {
+                        message: $ERROR_CODES.LANGUAGE_NOT_ENABLED.message,
+                        code: 'LANGUAGE_NOT_ENABLED'
+                    });
+                }
+                const fallback = resolveFallbackChain(config, language);
+                // Blanket per-language scoping on `roots`, exactly like multi-tenant's
+                // tenant_slug (Strapi-style per-locale context): `where` scopes every
+                // roots read/guard to the active language, `insertColumns` stamps it on
+                // every create. Cross-language operations (the language switcher /
+                // translation status) are served by dedicated translationKey endpoints
+                // later — they query by group id, not the blanket scope.
+                return {
+                    roots: {
+                        where: sql`"cms"."roots"."language" = ${language}`,
+                        insertColumns: {
+                            language
+                        },
+                        // A new logical entry mints a FRESH translation group id (Seam D);
+                        // sibling-language roots inherit it later via createTranslation.
+                        newEntryColumns: ()=>({
+                                translation_key: newId('translationGroup')
+                            }),
+                        // `language` is stamped on insert but is a CROSS-SCOPE column for
+                        // reads: a reference/host/usage in any sibling language still counts,
+                        // so cross-scope read queries must NOT filter by it (Seam D6).
+                        crossScopeExclude: [
+                            'language'
+                        ]
+                    },
+                    // Redirects are per-language too: a redirect created for `en` must not
+                    // fire for a `de` visitor (and the two languages can have different
+                    // redirects for the same path). The resolver / CRUD / auto-create all
+                    // consume scope.redirects, so this is the whole wiring.
+                    redirects: {
+                        where: sql`"cms"."redirects"."language" = ${language}`,
+                        insertColumns: {
+                            language
+                        }
+                    },
+                    // The reference resolver core's read path + co-render walk ride through
+                    // the Seam B handle (translation-group aware: tgr_ -> best fallback
+                    // sibling; rot_ -> active-language sibling, else anchor). P1 still
+                    // imports the impl from core; it MOVES into this plugin in P2.
+                    referenceResolver: buildI18nReferenceResolver(language, fallback),
+                    // Per-request i18n context (active language + fallback chain + the
+                    // configured universe), stashed in the OPAQUE pluginContext slot (Seam
+                    // C) keyed by this plugin's id. Core never reads it; consumers read it
+                    // via the exported getI18nContext(scope) accessor.
+                    pluginContext: {
+                        i18n: {
+                            language,
+                            fallback,
+                            languages: config.languages
+                        }
+                    }
+                };
+            };
+            return {
+                context: {
+                    scopeConditions: [
+                        factory
+                    ]
+                }
+            };
+        }
+    };
+}
+
+export { getI18nContext, i18n, resolveLanguage };