Taxonomy term hierarchy uses locale-bound parent_id, causing cross-locale parent leak and silent tree flattening

[MA2153]

Description

Taxonomy term hierarchy (taxonomies.parent_id) is encoded as a row id, which is locale-bound, while every other relationship in the taxonomy i18n model keys off a locale-agnostic value (the taxonomy name string, or a translation_group). As a result, a child term can permanently end up parented to a term row in a different locale, which silently flattens the per-locale term tree with no error.

The asymmetry

Relationship	Stored as	Locale semantics
Term → taxonomy def	taxonomies.name (string)	locale-agnostic
Term → content entry	content_taxonomies.taxonomy_id = translation_group	locale-agnostic
Term → parent term	taxonomies.parent_id = row id	locale-bound

A parent_id points at one term row, which lives in one locale. The hierarchy only holds together if every child's parent_id points at a parent row in the same locale, but nothing enforces that. validateParentTerm checks parent.name === taxonomyName (same taxonomy name), not same locale, so a cross-locale parent passes validation.

The only thing aligning locales is one best-effort block in handleTermCreate (packages/core/src/api/handlers/taxonomies.ts, ~L526–540): when creating a term translation, it resolves the source's parent translation_group and tries to swap in the same-locale sibling. It only fires when the translated parent already exists, and it only fixes the row being created — never existing children.

Impact

• The per-locale tree silently flattens: handleTermList filters terms by locale, then buildTree only links a child if its parentId is in that locale's set (taxonomies.ts ~L101–107). A child whose parent_id references another locale's row is pushed to roots and appears top-level, with no error.
• The broken edge is permanent: nothing re-points existing children when a parent translation is created later. No backfill exists.

Steps to reproduce

Assume a hierarchical taxonomy category with default locale en and a second locale es.

1. Create parent term computing (en) and child term laptops (en) with parentId = computing(en). Tree in en is correct.
2. Translate the child first: POST /_emdash/api/taxonomies/category/terms/laptops/translations with { "locale": "es", "slug": "portatiles" }. Because the es translation of computing does not exist yet, the re-pointing guard finds no same-locale parent, so portatiles(es).parent_id is set to computing(en) — a cross-locale edge.
3. Now translate the parent: create computacion (es) as a translation of computing(en). This does not retroactively re-point portatiles(es).
4. GET /_emdash/api/taxonomies/category/terms?locale=es. Expected: computacion with child portatiles. Actual: portatiles appears as a root (its parent_id still references the en row, which is absent from the es-filtered set), so the Spanish tree is flattened.

There is no error or warning at any step.

Suggested fix (root cause)

Store the parent's translation_group in parent_id instead of a row id — mirroring how content_taxonomies.taxonomy_id already works. Then findChildren / buildTree resolve parent_group + locale → row, translating a parent automatically adopts existing children in every locale, and the imperative re-pointing block plus its ordering hazard can be removed. This is a forward-only schema migration (change parent_id semantics + backfill existing values through translation_group) with backwards-compat implications, so it likely warrants a Discussion on the migration path.

Environment

• emdash version: latest main (observed on commit a6e8a918)
• Runtime: Node / SQLite and Cloudflare D1 (logic is dialect-independent; affects both)
• Area: packages/core — taxonomy i18n

Relevant files:

• packages/core/src/api/handlers/taxonomies.ts (validateParentTerm, handleTermCreate re-pointing, buildTree)
• packages/core/src/database/repositories/taxonomy.ts (findByName, findChildren, parent_id handling)
• packages/core/src/database/migrations/036_i18n_menus_and_taxonomies.ts (i18n schema)

[emdashbot]

The investigation bot reproduced this issue.

Root cause (high confidence): packages/core/src/api/handlers/taxonomies.ts — three coupled spots, all from the same invariant break: taxonomies.parent_id stores a per-locale row id instead of a locale-agnostic translation_group.

1. handleTermCreate re-pointing block, taxonomies.ts:524–540. When a child translation is created before its parent is translated, the lookup where("translation_group","=",sourceParent.translationGroup).where("locale","=",input.locale) returns undefined, and the function falls through with parentId still set to the source-locale row id. The new ES row is inserted with a cross-locale parent_id.

2. validateParentTerm (taxonomies.ts:418–456) only checks parent.name === taxonomyName and walks for cycles/depth — never compares parent.locale to the term's locale, so the cross-locale edge passes validation silently.

3. Translating the parent has no symmetric adoption step. handleTermCreate for the new parent translation never queries existing rows whose parent_id references a sibling in the parent's translation_group at the new locale, so the orphaned ES child stays pointed at the EN row forever.

handleTermList calls findByName({ locale }) (repositories/taxonomy.ts:130–148), then buildTree (taxonomies.ts:97–108) hits if (term.parentId && map.has(term.parentId)). The cross-locale parent_id is absent from the locale-filtered map, so the child falls into roots — the silent flattening reproduced as expected [] to deeply equal ['portatiles'].

The repository compounds it: findChildren(parentId) (repositories/taxonomy.ts:152–161) queries by parent_id = <row id> with no translation_group resolution. The on-disk encoding is the root invariant break; the handler-level guard is best-effort and order-sensitive (translate-child-before-parent breaks it).
Proposed fix: Issue author flags the proper fix as needing a Discussion on migration. Two viable shapes; maintainer should choose.

Option A — Additive handler fix (recommended interim). No schema change, backwards-compatible, fixes the symptom.

1. In handleTermCreate (taxonomies.ts:485), when input.translationOf is set, after repo.create(...) and before returning, run an adoption step: UPDATE taxonomies SET parent_id = <new id> WHERE parent_id IN (SELECT id FROM taxonomies WHERE translation_group = <new term's translation_group> AND id != <new id>) AND locale = <input.locale> AND id != <new id>. Then invalidateTermCache(). Re-points orphans the moment the same-locale parent appears.
2. Tighten the re-pointing block (taxonomies.ts:524–540): when the target-locale parent doesn't exist, return VALIDATION_ERROR code PARENT_NOT_TRANSLATED instead of falling through with the source-locale id. (Falling back to parent_id = null is looser but loses information.)
3. Add a same-locale check to validateParentTerm (taxonomies.ts:418): if the term has a locale and parent.locale !== that locale, reject. Also covers handleTermUpdate.

The reproduce test passes against step 1 alone. Add sibling tests for 2 and 3.

Option B — Schema fix (author's preferred root-cause). Forward-only migration changing taxonomies.parent_id semantics to a translation_group, backfilling via UPDATE taxonomies SET parent_id = (SELECT translation_group FROM taxonomies p WHERE p.id = taxonomies.parent_id), rewriting findChildren/buildTree to resolve (parent_group, locale) -> row, deleting the imperative re-pointing block. Handler responses keep returning per-locale row ids in parentId for API stability. Breaks external consumers of the raw column. Needs a Discussion before merge.

Recommendation: ship Option A now (small, additive, kills the symptom) and open the Discussion for Option B as the cleanup. Option A makes Option B's backfill trivial later.
Alternative causes considered: Alternative causes considered and ruled out:

• "buildTree has a bug" — no. buildTree (taxonomies.ts:97–108) does exactly what an in-memory tree-build should do; its precondition is that every parentId resolves within the input set, and that precondition is violated upstream. Chasing cross-locale parents in buildTree would paper over the schema invariant.
• "handleTermList's locale filter is too aggressive" — no. Per-locale tree is correct. Loosening surfaces EN rows in the ES tree, not a fix.
• "TaxonomyRepository.create silently drops parentId" — checked at repositories/taxonomy.ts:60–93; it writes whatever input.parentId it receives. The bad value originates in handleTermCreate's re-pointing fallback.
• "findChildren is locale-aware and the bug is there" — checked; findChildren (repositories/taxonomy.ts:152–161) does parent_id = <id> with no locale filter and no translation_group resolution. It follows whatever edge exists; not where the broken edge is introduced.
• "Maybe a trigger fans parent translations out to children" — searched migration 036 and surrounding migrations; no triggers, no application hook on parent-translation create. The asymmetry is real, not missing wiring.

Confidence is high because the reproduce-stage test proves the chain end to end: portatiles is created with parent_id = enParentId (re-pointing returns no translated parent), computacion is created with no adoption walk, handleTermList returns 0 children for esParent. Failure output (expected [] to deeply equal ['portatiles']) is the exact prediction the issue makes.

Option A vs B is a real maintainer judgment: B is what the title and "Suggested fix" advocate, but the issue body itself says "likely warrants a Discussion on the migration path", which is why this is needs-design-decision despite A being a defensible immediate fix.
Verdict: bug — Unintentional. Three signals show same-locale parent edges are the design contract.

1. The re-pointing block at taxonomies.ts:524–540 exists for exactly this — its comment: "If creating a translation whose parent is the translated sibling of the source's parent, try to resolve the parent in the same locale." Intent is explicit. The defect is that the block is best-effort and order-sensitive: silently no-ops when the same-locale parent doesn't yet exist, with no symmetric adoption when the parent is translated later.

2. handleTermList + buildTree (taxonomies.ts:97–108) build a per-locale tree by locale-filtering then linking via parentId. Only well-formed if every parent_id is same-locale. The repository docstring (repositories/taxonomy.ts:42–52) codifies the doctrine: "Translations of the same term share a translation_group ULID. content_taxonomies.taxonomy_id stores the translation_group so a single association spans every locale." translation_group for cross-locale, row id intra-locale — exactly what parent_id violates.

3. Migration 036 (database/migrations/036_i18n_menus_and_taxonomies.ts) explicitly remapped content_taxonomies.taxonomy_id and _emdash_menu_items.reference_id from row ids to translation_groups (rebuildContentTaxonomies, remapMenuItemRefs). taxonomies.parent_id was left as a row id — an oversight given every other cross-row reference in the same migration was converted.

No existing test asserts cross-locale parent edges are valid; unit tests at tests/unit/taxonomies/taxonomies.test.ts:110,124–127,319–351 only use the default locale. No docs/ page or comment excuses the flattening. The reproduce test shows the Spanish tree silently flattens with no warning — a correctness failure.

Diagnose's needs-design-decision (Option A handler fix vs Option B schema migration) gates the fix stage but does not change the verdict: bug.
The fix needs a design decision a maintainer should make, so the bot did not attempt it automatically. The proposed options are above.

A maintainer will pick up the fix from here.

_{Run: https://github.com/emdash-cms/emdash/actions/runs/27008367520}