emdash 0.39.1 → 0.40.1

package/src/api/handlers/snapshot.ts

@@ -80,6 +80,8 @@ export function parsePreviewSignatureHeader(
 // ── Media URL rewriting ─────────────────────────────────────────
 
 const MEDIA_FILE_PREFIX = "/_emdash/api/media/file/";
+const MEDIA_FILE_SUFFIX = /[?#]/;
+const EXTERNAL_OR_ROOT_URL = /^(?:[a-z][a-z0-9+.-]*:|\/)/i;
 
 /**
  * Parse a JSON string value and inject `src` for local media objects.
@@ -166,9 +168,12 @@ export interface Snapshot {
  * Content tables (ec_*) are discovered dynamically.
  */
 const SYSTEM_TABLES = [
+	"_emdash_block_types",
+	"_emdash_block_type_versions",
 	"_emdash_collections",
 	"_emdash_fields",
 	"_emdash_taxonomy_defs",
+	"_emdash_taxonomy_def_groups",
 	"_emdash_menus",
 	"_emdash_menu_items",
 	"_emdash_sections",
@@ -176,12 +181,59 @@ const SYSTEM_TABLES = [
 	"_emdash_widgets",
 	"_emdash_seo",
 	"_emdash_migrations",
-	"taxonomies",
 	"content_taxonomies",
-	"media",
+	"taxonomies",
 	"options",
+	"media",
 	"revisions",
-];
+] as const;
+
+type SystemTable = (typeof SYSTEM_TABLES)[number];
+type PublishedTablePolicy = "full" | "content-linked" | "omit";
+
+/**
+ * Published snapshots are available to preview-signature callers, so every
+ * system table must be classified explicitly. Adding a snapshot table without
+ * choosing a policy is a type error rather than an accidental data export.
+ */
+const PUBLISHED_TABLE_POLICIES: Record<SystemTable, PublishedTablePolicy> = {
+	_emdash_block_types: "full",
+	_emdash_block_type_versions: "full",
+	_emdash_collections: "full",
+	_emdash_fields: "full",
+	_emdash_taxonomy_defs: "full",
+	_emdash_taxonomy_def_groups: "full",
+	_emdash_menus: "full",
+	_emdash_menu_items: "content-linked",
+	_emdash_sections: "full",
+	_emdash_widget_areas: "full",
+	_emdash_widgets: "full",
+	_emdash_seo: "content-linked",
+	_emdash_migrations: "full",
+	content_taxonomies: "content-linked",
+	taxonomies: "content-linked",
+	options: "content-linked",
+	media: "content-linked",
+	revisions: "omit",
+};
+
+const SYSTEM_TABLE_SET: ReadonlySet<string> = new Set(SYSTEM_TABLES);
+
+function isSystemTable(tableName: string): tableName is SystemTable {
+	return SYSTEM_TABLE_SET.has(tableName);
+}
+
+interface PublishedContentReferences {
+	ids: Set<string>;
+	translationGroups: Set<string>;
+}
+
+interface PublishedProjection {
+	content: Map<string, PublishedContentReferences>;
+	taxonomyGroups: Set<string>;
+	mediaIds: Set<string>;
+	mediaStorageKeys: Set<string>;
+}
 
 /**
  * Table name prefixes excluded from snapshots (auth/security data).
@@ -192,6 +244,7 @@ const EXCLUDED_PREFIXES = [
 	"_emdash_authorization_codes",
 	"_emdash_device_codes",
 	"_emdash_migrations_lock",
+	"_emdash_transfer_",
 	"_plugin_",
 	"users",
 	"sessions",
@@ -252,6 +305,191 @@ function normalizeRows(
 	return rows;
 }
 
+function createPublishedProjection(): PublishedProjection {
+	return {
+		content: new Map(),
+		taxonomyGroups: new Set(),
+		mediaIds: new Set(),
+		mediaStorageKeys: new Set(),
+	};
+}
+
+function readString(value: unknown): string | null {
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function recordPublishedContent(
+	projection: PublishedProjection,
+	tableName: string,
+	rows: Record<string, unknown>[],
+): void {
+	const references: PublishedContentReferences = {
+		ids: new Set(),
+		translationGroups: new Set(),
+	};
+	for (const row of rows) {
+		const id = readString(row.id);
+		const translationGroup = readString(row.translation_group);
+		if (id) references.ids.add(id);
+		if (translationGroup) references.translationGroups.add(translationGroup);
+	}
+	projection.content.set(tableName.slice("ec_".length), references);
+}
+
+function isPublishedContentReference(
+	projection: PublishedProjection,
+	collection: unknown,
+	reference: unknown,
+): boolean {
+	const collectionName = readString(collection);
+	const id = readString(reference);
+	if (!collectionName || !id) return false;
+	const references = projection.content.get(collectionName);
+	return references?.ids.has(id) === true || references?.translationGroups.has(id) === true;
+}
+
+function collectMediaReferences(value: unknown, projection: PublishedProjection): void {
+	if (typeof value === "string") {
+		if (value.startsWith(MEDIA_FILE_PREFIX)) {
+			const storageKey = value.slice(MEDIA_FILE_PREFIX.length).split(MEDIA_FILE_SUFFIX, 1)[0];
+			if (storageKey) projection.mediaStorageKeys.add(storageKey);
+			return;
+		}
+		const trimmed = value.trimStart();
+		if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+			try {
+				collectMediaReferences(JSON.parse(value), projection);
+			} catch {
+				// Not structured data.
+			}
+		}
+		return;
+	}
+	if (Array.isArray(value)) {
+		for (const item of value) collectMediaReferences(item, projection);
+		return;
+	}
+	if (!isRecord(value)) return;
+
+	const mediaId = readString(value.mediaId);
+	if (mediaId) projection.mediaIds.add(mediaId);
+
+	const provider = readString(value.provider);
+	const meta = isRecord(value.meta) ? value.meta : null;
+	const localMediaId = readString(value.id);
+	if ((provider === "local" || (!provider && meta)) && localMediaId) {
+		projection.mediaIds.add(localMediaId);
+	}
+	const storageKey = readString(value.storageKey) ?? readString(meta?.storageKey);
+	if (storageKey) projection.mediaStorageKeys.add(storageKey);
+
+	const asset = isRecord(value.asset) ? value.asset : null;
+	const assetRef = readString(asset?._ref);
+	if (assetRef) {
+		projection.mediaIds.add(assetRef);
+		projection.mediaStorageKeys.add(assetRef);
+	}
+
+	for (const child of Object.values(value)) collectMediaReferences(child, projection);
+}
+
+function projectTaxonomyRows(
+	rows: Record<string, unknown>[],
+	projection: PublishedProjection,
+): Record<string, unknown>[] {
+	const includedGroups = new Set(projection.taxonomyGroups);
+	const includedIds = new Set(projection.taxonomyGroups);
+	let changed = true;
+	while (changed) {
+		changed = false;
+		for (const row of rows) {
+			const id = readString(row.id);
+			const group = readString(row.translation_group);
+			if (!id) continue;
+			if (includedIds.has(id) || (group && includedGroups.has(group))) {
+				if (!includedIds.has(id)) {
+					includedIds.add(id);
+					changed = true;
+				}
+				if (group && !includedGroups.has(group)) {
+					includedGroups.add(group);
+					changed = true;
+				}
+				const parentId = readString(row.parent_id);
+				if (parentId && !includedIds.has(parentId)) {
+					includedIds.add(parentId);
+					changed = true;
+				}
+			}
+		}
+	}
+	return rows.filter((row) => {
+		const id = readString(row.id);
+		const group = readString(row.translation_group);
+		return (id && includedIds.has(id)) || (group && includedGroups.has(group));
+	});
+}
+
+function projectPublishedRows(
+	tableName: SystemTable,
+	rows: Record<string, unknown>[],
+	projection: PublishedProjection,
+): Record<string, unknown>[] {
+	switch (tableName) {
+		case "_emdash_seo":
+			return rows.filter((row) => {
+				const published = isPublishedContentReference(projection, row.collection, row.content_id);
+				if (!published) return false;
+				const image = readString(row.seo_image);
+				if (image) {
+					collectMediaReferences(image, projection);
+					if (!EXTERNAL_OR_ROOT_URL.test(image)) {
+						projection.mediaIds.add(image);
+						projection.mediaStorageKeys.add(image);
+					}
+				}
+				return true;
+			});
+		case "content_taxonomies":
+			return rows.filter((row) => {
+				const published = isPublishedContentReference(projection, row.collection, row.entry_id);
+				const taxonomyGroup = readString(row.taxonomy_id);
+				if (published && taxonomyGroup) projection.taxonomyGroups.add(taxonomyGroup);
+				return published;
+			});
+		case "taxonomies":
+			return projectTaxonomyRows(rows, projection);
+		case "_emdash_menu_items":
+			return rows.filter((row) => {
+				const type = readString(row.type);
+				const referenceId = readString(row.reference_id);
+				if (!referenceId || type === "custom") return true;
+				if (type === "taxonomy") {
+					projection.taxonomyGroups.add(referenceId);
+					return true;
+				}
+				if (type === "collection" && !row.reference_id) return true;
+				const collection =
+					readString(row.reference_collection) ??
+					(type === "post" || type === "page" ? `${type}s` : null);
+				return isPublishedContentReference(projection, collection, referenceId);
+			});
+		case "media":
+			return rows.filter((row) => {
+				const id = readString(row.id);
+				const storageKey = readString(row.storage_key);
+				return (
+					(id !== null && projection.mediaIds.has(id)) ||
+					(storageKey !== null && projection.mediaStorageKeys.has(storageKey))
+				);
+			});
+		case "options":
+			return rows;
+		default:
+			return [];
+	}
+}
+
 export interface GenerateSnapshotOptions {
 	/** Include draft and scheduled content (default: false) */
 	includeDrafts?: boolean;
@@ -284,6 +522,8 @@ export async function generateSnapshot(
 	const includeTrashed = options?.includeTrashed ?? false;
 	const optionPrefixes = options?.optionPrefixes ?? SAFE_OPTIONS_PREFIXES;
 	const optionKeys = new Set(options?.optionKeys);
+	const publishedOnly = !includeDrafts && !includeTrashed;
+	const publishedProjection = createPublishedProjection();
 
 	const contentTables = await listTablesLike(db, "ec_%");
 
@@ -336,6 +576,12 @@ export async function generateSnapshot(
 					`.execute(db)
 				).rows;
 			}
+		} else if (
+			publishedOnly &&
+			isSystemTable(tableName) &&
+			PUBLISHED_TABLE_POLICIES[tableName] === "omit"
+		) {
+			rows = [];
 		} else if (tableName === "options") {
 			rows = (
 				await sql<Record<string, unknown>>`
@@ -353,6 +599,18 @@ export async function generateSnapshot(
 			).rows;
 		}
 
+		if (publishedOnly) {
+			if (tableName.startsWith("ec_")) {
+				recordPublishedContent(publishedProjection, tableName, rows);
+			} else if (
+				isSystemTable(tableName) &&
+				PUBLISHED_TABLE_POLICIES[tableName] === "content-linked"
+			) {
+				rows = projectPublishedRows(tableName, rows, publishedProjection);
+			}
+			for (const row of rows) collectMediaReferences(row, publishedProjection);
+		}
+
 		if (rows.length > 0) {
 			tables[tableName] = normalizeRows(rows, types);
 		}

package/src/api/handlers/taxonomies.ts

@@ -5,11 +5,22 @@
  * terms; `(name, locale)` for defs. Translations of the same term/def share a
  * `translation_group`. The content_taxonomies pivot stores translation_groups
  * so assignments span every locale of a post.
+ *
+ * A def's `label` and `labelSingular` belong to its locale; `hierarchical` and
+ * `collections` belong to the taxonomy and read and write the same through
+ * every locale.
  */
 
 import { sql, type Kysely, type Selectable } from "kysely";
 import { ulid } from "ulidx";
 
+import {
+	findTaxonomyStructure,
+	parseTaxonomyCollections,
+	saveTaxonomyStructure,
+	selectTaxonomyDefs,
+	type TaxonomyStructure,
+} from "../../database/repositories/taxonomy-def.js";
 import { TaxonomyRepository, type SiblingPosition } from "../../database/repositories/taxonomy.js";
 import { withTransaction } from "../../database/transaction.js";
 import type { Database, TaxonomyDefTable } from "../../database/types.js";
@@ -170,9 +181,9 @@ async function requireTaxonomyDef(
 	name: string,
 	locale?: string,
 ): Promise<TaxonomyDefLookup> {
-	let query = db.selectFrom("_emdash_taxonomy_defs").selectAll().where("name", "=", name);
-	if (locale !== undefined) query = query.where("locale", "=", locale);
-	const def = await query.orderBy("locale", "asc").orderBy("id", "asc").executeTakeFirst();
+	let query = selectTaxonomyDefs(db).where("d.name", "=", name);
+	if (locale !== undefined) query = query.where("d.locale", "=", locale);
+	const def = await query.orderBy("d.locale", "asc").orderBy("d.id", "asc").executeTakeFirst();
 	return def ? { success: true, def } : taxonomyDefNotFound(name, locale);
 }
 
@@ -185,12 +196,10 @@ async function requireTaxonomyDefWithFallback(
 	name: string,
 	locale?: string,
 ): Promise<TaxonomyDefLookup> {
-	const defs = await db
-		.selectFrom("_emdash_taxonomy_defs")
-		.selectAll()
-		.where("name", "=", name)
-		.orderBy("locale", "asc")
-		.orderBy("id", "asc")
+	const defs = await selectTaxonomyDefs(db)
+		.where("d.name", "=", name)
+		.orderBy("d.locale", "asc")
+		.orderBy("d.id", "asc")
 		.execute();
 	const defaultLocale = getI18nConfig()?.defaultLocale;
 	const def =
@@ -263,13 +272,6 @@ async function toTaxonomyResponse(
 	};
 }
 
-/** Declared collections of a taxonomy def row (deduped, parsed from JSON). */
-function defCollections(def: Selectable<TaxonomyDefTable>): string[] {
-	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- column stores a JSON string[] written by handleTaxonomyCreate
-	const parsed = def.collections ? (JSON.parse(def.collections) as string[]) : [];
-	return [...new Set(parsed)];
-}
-
 function rowToDef(row: Selectable<TaxonomyDefTable>): TaxonomyDef {
 	return {
 		id: row.id,
@@ -277,7 +279,7 @@ function rowToDef(row: Selectable<TaxonomyDefTable>): TaxonomyDef {
 		label: row.label,
 		labelSingular: row.label_singular ?? undefined,
 		hierarchical: row.hierarchical === 1,
-		collections: row.collections ? JSON.parse(row.collections) : [],
+		collections: parseTaxonomyCollections(row.collections),
 		locale: row.locale,
 		translationGroup: row.translation_group,
 	};
@@ -296,8 +298,8 @@ export async function handleTaxonomyList(
 ): Promise<ApiResult<TaxonomyListResponse>> {
 	try {
 		const locale = options.locale ? resolveConfiguredLocale(options.locale) : undefined;
-		let query = db.selectFrom("_emdash_taxonomy_defs").selectAll();
-		if (locale !== undefined) query = query.where("locale", "=", locale);
+		let query = selectTaxonomyDefs(db);
+		if (locale !== undefined) query = query.where("d.locale", "=", locale);
 		const [rows, collectionRows] = await Promise.all([
 			query.execute(),
 			db.selectFrom("_emdash_collections").select("slug").execute(),
@@ -348,7 +350,12 @@ export async function handleTaxonomyGet(
 }
 
 /**
- * Create a new taxonomy definition
+ * Create a taxonomy definition in one locale.
+ *
+ * When the taxonomy already exists in another locale, the new definition joins
+ * it whether or not `translationOf` is given, and takes its `hierarchical` and
+ * `collections`. A differing value sent with it is rejected rather than applied
+ * to every locale; changing the structure is an update.
  */
 export async function handleTaxonomyCreate(
 	db: Kysely<Database>,
@@ -375,13 +382,10 @@ export async function handleTaxonomyCreate(
 			};
 		}
 
-		let hierarchical = input.hierarchical ?? false;
-		let collections = [...new Set(input.collections ?? [])];
-		let translationGroup: string | null = null;
 		if (input.translationOf) {
 			const source = await db
 				.selectFrom("_emdash_taxonomy_defs")
-				.selectAll()
+				.select("name")
 				.where("id", "=", input.translationOf)
 				.executeTakeFirst();
 			if (!source) {
@@ -399,18 +403,13 @@ export async function handleTaxonomyCreate(
 					},
 				};
 			}
-			translationGroup = source.translation_group ?? source.id;
-			if (input.hierarchical === undefined) {
-				hierarchical = source.hierarchical === 1;
-			}
-			if (input.collections === undefined) {
-				collections = [...new Set(defCollections(source))];
-			}
 		}
 
-		const collectionError = await validateCollections(db, collections);
-		if (collectionError) {
-			return { success: false, error: collectionError };
+		if (input.collections !== undefined) {
+			const collectionError = await validateCollections(db, input.collections);
+			if (collectionError) {
+				return { success: false, error: collectionError };
+			}
 		}
 
 		// Duplicate guard scoped to locale (so the same name can exist in ES
@@ -432,29 +431,44 @@ export async function handleTaxonomyCreate(
 		}
 
 		const id = ulid();
-		await db
-			.insertInto("_emdash_taxonomy_defs")
-			.values({
-				id,
-				name: input.name,
-				label: input.label,
-				label_singular: input.labelSingular ?? null,
-				hierarchical: hierarchical ? 1 : 0,
-				collections: JSON.stringify(collections),
-				locale,
-				translation_group: translationGroup ?? id,
-			})
-			.execute();
+		const existingStructure = await findTaxonomyStructure(db, input.name);
+		if (existingStructure && !(await matchesStructure(db, existingStructure, input))) {
+			return {
+				success: false,
+				error: {
+					code: "VALIDATION_ERROR",
+					message: `Taxonomy '${input.name}' already exists in another locale with a different hierarchical or collections value; change them with an update`,
+				},
+			};
+		}
+		const structure = existingStructure ?? {
+			hierarchical: input.hierarchical ?? false,
+			collections: [...new Set(input.collections ?? [])],
+		};
+		const groupId = existingStructure?.id ?? id;
+		await withTransaction(db, async (trx) => {
+			await trx
+				.insertInto("_emdash_taxonomy_defs")
+				.values({
+					id,
+					name: input.name,
+					label: input.label,
+					label_singular: input.labelSingular ?? null,
+					hierarchical: structure.hierarchical ? 1 : 0,
+					collections: JSON.stringify(structure.collections),
+					locale,
+					translation_group: groupId,
+				})
+				.execute();
+			// A group another request created since the read above keeps its structure.
+			await saveTaxonomyStructure(trx, input.name, groupId, structure, {});
+		});
 
 		// A new def changes which taxonomies exist — drop the isolate-wide
 		// defs/names caches so this isolate reflects it immediately.
 		invalidateTaxonomyDefsCache();
 
-		const row = await db
-			.selectFrom("_emdash_taxonomy_defs")
-			.selectAll()
-			.where("id", "=", id)
-			.executeTakeFirstOrThrow();
+		const row = await selectTaxonomyDefs(db).where("d.id", "=", id).executeTakeFirstOrThrow();
 		return { success: true, data: { taxonomy: rowToDef(row) } };
 	} catch (error) {
 		if (error instanceof Error && error.message.includes("UNIQUE constraint failed")) {
@@ -470,13 +484,32 @@ export async function handleTaxonomyCreate(
 	}
 }
 
+/**
+ * Whether the `hierarchical` and `collections` a request sends, if any, equal
+ * `structure` as a read returns it, without collections that no longer exist.
+ */
+async function matchesStructure(
+	db: Kysely<Database>,
+	structure: TaxonomyStructure,
+	input: { hierarchical?: boolean; collections?: string[] },
+): Promise<boolean> {
+	if (input.hierarchical !== undefined && input.hierarchical !== structure.hierarchical) {
+		return false;
+	}
+	if (input.collections === undefined) return true;
+	const existing = await findExistingCollections(db, structure.collections);
+	const visible = structure.collections.filter((collection) => existing.has(collection));
+	const sent = new Set(input.collections);
+	return sent.size === visible.length && visible.every((collection) => sent.has(collection));
+}
+
 /**
  * Update a taxonomy definition.
  *
- * Writes the one row `(name, locale)` resolves to — every field here belongs to
- * a single locale's definition, so translating a taxonomy and then editing the
- * translation leaves the other locales alone. `name` and `locale` are immutable
- * (renaming would strand the terms, which are keyed on `name`).
+ * `label` and `labelSingular` write the one row `(name, locale)` resolves to.
+ * `hierarchical` and `collections` write the taxonomy, so every locale changes.
+ * `name` and `locale` are immutable (renaming would strand the terms, which are
+ * keyed on `name`).
  */
 export async function handleTaxonomyUpdate(
 	db: Kysely<Database>,
@@ -502,30 +535,39 @@ export async function handleTaxonomyUpdate(
 			}
 		}
 
-		const updates: {
-			label?: string;
-			label_singular?: string | null;
-			hierarchical?: number;
-			collections?: string;
-		} = {};
+		const updates: { label?: string; label_singular?: string | null } = {};
 		if (input.label !== undefined) updates.label = input.label;
 		if (input.labelSingular !== undefined) updates.label_singular = input.labelSingular;
-		if (input.hierarchical !== undefined) updates.hierarchical = input.hierarchical ? 1 : 0;
-		if (collections !== undefined) updates.collections = JSON.stringify(collections);
-
-		if (Object.keys(updates).length > 0) {
-			await db
-				.updateTable("_emdash_taxonomy_defs")
-				.set(updates)
-				.where("id", "=", lookup.def.id)
-				.execute();
+		const structureChanged = input.hierarchical !== undefined || collections !== undefined;
+
+		if (Object.keys(updates).length > 0 || structureChanged) {
+			const def = lookup.def;
+			await withTransaction(db, async (trx) => {
+				if (Object.keys(updates).length > 0) {
+					await trx
+						.updateTable("_emdash_taxonomy_defs")
+						.set(updates)
+						.where("id", "=", def.id)
+						.execute();
+				}
+				if (structureChanged) {
+					await saveTaxonomyStructure(
+						trx,
+						name,
+						def.translation_group ?? def.id,
+						{
+							hierarchical: input.hierarchical ?? def.hierarchical === 1,
+							collections: collections ?? parseTaxonomyCollections(def.collections),
+						},
+						{ hierarchical: input.hierarchical, collections },
+					);
+				}
+			});
 			invalidateTaxonomyDefsCache();
 		}
 
-		const row = await db
-			.selectFrom("_emdash_taxonomy_defs")
-			.selectAll()
-			.where("id", "=", lookup.def.id)
+		const row = await selectTaxonomyDefs(db)
+			.where("d.id", "=", lookup.def.id)
 			.executeTakeFirstOrThrow();
 
 		return { success: true, data: await toTaxonomyResponse(db, row) };
@@ -568,6 +610,7 @@ export async function handleTaxonomyDelete(
 				.execute();
 			await trx.deleteFrom("taxonomies").where("name", "=", name).execute();
 			await trx.deleteFrom("_emdash_taxonomy_defs").where("name", "=", name).execute();
+			await trx.deleteFrom("_emdash_taxonomy_def_groups").where("name", "=", name).execute();
 		});
 
 		// Covers the term caches too — see `invalidateTaxonomyDefsCache`.
@@ -677,7 +720,12 @@ export async function handleTermList(
 		// look up by group and map back to each term's id.
 		const includeCounts = options.includeCounts ?? true;
 		const countsByGroup = includeCounts
-			? await fetchVisibleTermCounts(db, taxonomyName, defCollections(lookup.def), locale)
+			? await fetchVisibleTermCounts(
+					db,
+					taxonomyName,
+					parseTaxonomyCollections(lookup.def.collections),
+					locale,
+				)
 			: undefined;
 
 		const termData: TermWithCount[] = terms.map((term) => ({
@@ -816,7 +864,8 @@ export async function handleTermReorder(
  *   - reject a parent in the term's own translation_group (self-parent),
  *     including the create path: a translation inherits its source's group, so
  *     `selfGroup` carries that prospective group when `termId` is absent.
- *   - on update, walk up the parent chain to detect cycles.
+ *   - walk up the parent chain to detect cycles, on create against `selfGroup`,
+ *     since a translation under another parent moves the existing term.
  */
 async function validateParentTerm(
 	repo: TaxonomyRepository,
@@ -858,9 +907,9 @@ async function validateParentTerm(
 	}
 
 	// Walk up the parent chain. Two checks fold into one walk:
-	//   - Cycle detection (only on update — a non-existent term-being-
-	//     created can't be its own ancestor): if the walk revisits termId
-	//     the proposed parent makes the term a descendant of itself.
+	//   - Cycle detection: if the walk reaches the term's group, the
+	//     proposed parent makes the term a descendant of itself. A new term
+	//     without `selfGroup` has no group to reach.
 	//   - Depth bound: refuse to extend a chain past MAX_DEPTH ancestors.
 	//     Runs on both create and update so a malicious or buggy caller
 	//     can't grow the tree without limit.
@@ -981,8 +1030,8 @@ export async function handleTermCreate(
 			}
 		}
 
-		// Validate parentId: must exist AND belong to the same taxonomy.
-		// (Cycle check is N/A on create — the term doesn't exist yet.)
+		// Validate parentId: must exist AND belong to the same taxonomy, and must
+		// not sit under the term a translation joins.
 		const parentError = await validateParentTerm(
 			repo,
 			taxonomyName,
@@ -1098,7 +1147,7 @@ export async function handleTermGet(
 		const counts = await fetchVisibleTermCounts(
 			db,
 			taxonomyName,
-			lookup.success ? defCollections(lookup.def) : [],
+			lookup.success ? parseTaxonomyCollections(lookup.def.collections) : [],
 			locale ?? term.locale,
 		);
 		const count = counts.get(term.translationGroup ?? term.id) ?? 0;