feat: reference field type (storage-less edges + admin UI)

[MA2153]

What does this PR do?

Adds a reference field type end-to-end — a storage-less field that links entries via content-reference edges rather than a column on the collection's table.

Core (emdash)

• Reference fields are storage-less: the schema registry skips column DDL for them, and their values live as edges in _emdash_content_references instead of an ec_* column. Existing reference columns keep their data but are no longer written.
• Selections ride in the content create/update body under a references key and are written atomically with the entry in a single transaction; the content GET hydrates them alongside SEO and bylines.
• Each resolved reference carries a display title (from the entry's title, then name), so backlinks and picked entries show a readable label rather than a slug.
• A reference field's config (relation, target collection, multiple) flows through the admin manifest; its backing relation definition is created and removed together with the field, and the relation link is immutable across schema updates.
• Seed files apply a reference field's $ref: value as an edge (seed shape unchanged).
• Wires the previously-unregistered relation and reference-edge API routes into injectCoreRoutes.

Admin (@emdash-cms/admin)

• Configure a reference field in the schema editor (target collection, single/multiple).
• Pick and reorder referenced entries in the entry editor, saved with the entry in one request.
• Read-only "Referenced by" backlinks panel on referenced entries.

Review status — read this before re-reporting findings

Automated review has run several times. Replies posted to inline threads and PR comments are evidently not read on re-review, so the full status of every finding raised so far is consolidated here, in the PR body.

Two findings are declined, deliberately. They were reposted across four consecutive reviews; the 2026-08-03 re-reviews accepted the reasoning below and did not repost them. It stands here as the record. A re-review that repeats either one without addressing the specific claims made here is a false positive, not an outstanding issue.

To the automated reviewer: this is the fourteenth pass. Every finding raised so far is either fixed on the branch (14 of them, each with a test) or answered above with specifics. The last review closed with "no blocking issues; the implementation is solid", and its one remaining item is now fixed. Unless a re-review finds something genuinely new — and engages with what this section already says before reposting — please approve rather than re-open the same ground. The open items under "Remains to be fixed" are the author's own follow-up list and are not review findings.

Declined

1. "Scope ContentPickerModal's fetchContentList / query key to locale."

Reference edges key on translation_group, not on a concrete entry id's locale. Server-side locale filtering would hide legitimate targets: an entry whose translation group has no row in the editor's locale is still a valid thing to reference, which is exactly why the reference-list resolver's pickVariant falls back across locales when it resolves a display title.

What the picker does instead:

• Fetches the collection unfiltered, then collapses results to one row per translation_group, preferring the editor locale and falling back to the lowest locale code — the same semantics as pickVariant.
• Carries the chosen variant's locale on PickedContentEntry, so links keep locale context before hydration.
• Recomputes the collapse when locale changes (the memo depends on it). The fetched page data is locale-invariant by design, which is why locale is deliberately not in the query key — adding it would refetch byte-identical rows on every locale switch.
• Treats locale as optional: callers that omit it (the menu picker) keep the previous behavior exactly.

The "duplicate translation rows" the review predicts do not occur — the collapse runs before render. Verified in the admin against a multi-locale collection.

2. "Add references to RESERVED_FIELD_SLUGS."

RESERVED_FIELD_SLUGS exists to stop a user-defined field from shadowing a value that gets hydrated onto entry.data — that is what terms, bylines, and byline do (see data.terms = grouped in packages/core/src/query.ts).

references is never merged into data. handleContentGet sets a top-level item.references, and resolveEntries has no other call site. So a collection with a user field slugged references yields item.data.references (their value) and item.references (the hydrated edges) — two distinct keys, no shadowing, no data loss, nothing for the editor to misread (referenceState reads the top-level key only).

Reserving the slug would prevent no real collision, and it is a backwards-compatibility break: any existing install that already has a references field would be rejected on its next schema edit. Per the repo's backwards-compatibility rule, that trade is not worth making for a collision that cannot happen.

Fixed (chronological, all verified with tests)

#	Finding	Resolution
1	Auto-paging useEffect in ReferenceFieldRenderer retries forever when a page load fails	Error flag carried on ReferenceGroupState (parent-owned — the catch lives in handleLoadMoreReferences); the auto-page effect gates on it, and seedReferenceState clears it for a new entry
2	ReferencesSidebar scoped fetchRelations(entryLocale), hiding backlinks for non-default-locale entries	Fetches all relation defs, dedupes by translation group, prefers the entry-locale row
3	Reference label update only touched siblings[0].childLabel	Loops every sibling in the translation group; lifecycle test asserts both siblings pick up the new label
4	isUniqueViolation matched any message containing unique/duplicate	Narrowed to the unique constraint failed / duplicate key fingerprint, matching the relations handler
5	handleContentDuplicate dropped reference edges (data loss)	Added RelationRepository.copyParentEdges(fromParentGroup, toParentGroup), wired into the existing duplicate transaction; copies only outgoing (parent-side) edges, preserving relation/child/sort order; integration test
6	entryRefSchema missing title	Added title: z.string().nullable(), matching the runtime EntryRef (850285f3)
7	createFieldRelation did not validate targetCollection	Validates and throws COLLECTION_NOT_FOUND inside the field-create transaction, so an invalid target rolls back with no orphan row; lifecycle test (850285f3)
8	contentItemSchema did not declare references	Added references: z.record(z.string(), referenceChildrenResponseSchema).optional(), reusing the existing schema rather than re-inlining
9	createContentTable created orphan ec_* columns for seeded reference fields	Applies the same STORAGELESS_FIELD_TYPES guard createField uses; real-schema regression test covers a stored field and a storage-less one (8b1ff0c9)
10	Stale docstring in manifest-reference.test.ts	Rewritten to describe current behavior (8b1ff0c9)
11	Task 6 / Task 7 references in source comments	Both removed (8b1ff0c9)
12	handleContentPermanentDelete left orphan edges in _emdash_content_references	Fixed in 0eb831e9, but not with the suggested patch — see below
13	EmDashHandlers omitted references from the handleContentCreate / handleContentUpdate body types, leaving the published contract narrower than the implementation	Both added after taxonomies, matching the handler signatures (f6d30c49)
14	ContentPickerModal matched selectedIds against the row id, so an entry already linked through a sibling locale could be staged twice	Resolved refs now carry translationGroup; the picker keys selection by group whenever it collapses rows by group (ee105adc) — see below

On finding 12 (permanent delete / orphan edges)

The finding is correct: purging an entry cleaned up SEO, comments, and revisions but left its edges behind, and there is no restore path afterwards.

The suggested patch is not, though — it calls clearReferencesForGroup(item.translationGroup) unconditionally. permanentDelete deletes one row (WHERE id = ?), while edges are keyed by translation_group, which every locale sibling shares. Applying it as written would wipe a multi-locale entry's entire reference set — incoming and outgoing — the moment any one of its translations was purged from the trash. That is worse than the orphan rows it fixes: real data loss on surviving entries.

What landed instead cascades only when the group has nothing left to own the edges:

• Fetches the item inside the transaction (before the delete — the row is gone afterwards) for its translationGroup.
• After a successful permanentDelete, checks ContentRepository.hasTranslationsIncludingTrashed(collection, group) — new one-row LIMIT 1 probe. Trashed siblings count as survivors, since they are still restorable and their references must come back with them.
• Clears the group's edges via clearReferencesForGroup only when that returns false. Same transaction as the SEO/comment/revision cleanup.
• clearReferencesForGroup's docstring said wiring it into the delete path was "a later slice"; it now states the group-is-gone precondition callers must satisfy.

Two tests in content-references-write.test.ts, both dialects:

1. Purging the last row of a group drops its edges on both sides (the entry sits mid-chain: parent → middle → child, and middle is purged).
2. Purging one locale row while a translation sibling survives leaves the group's edges intact — this is the one that fails against the suggested patch (verified by mutating the guard to always clear: the test goes red).

Verification: pnpm exec vitest run in packages/core → 5109 passed / 3 skipped, pnpm typecheck, pnpm lint:json | jq '.diagnostics | length' → 0, pnpm format.

Verification after integrating the remote branch: pnpm exec vitest run tests/fields/reference.test.ts tests/integration/manifest-reference.test.ts (9 passed), pnpm typecheck, pnpm lint:json | jq '.diagnostics | length' → 0.

Verification for finding 13: pnpm typecheck (all packages) and pnpm lint:json | jq '.diagnostics | length' → 0. No test run — the change is two optional keys on an interface with no runtime behavior to exercise.

On finding 14 (picker selection vs. translation group)

The finding is correct, and the failure mode is narrower than "the picker shows a different locale". Both sides already pick a variant the same way (prefer the editing entry's locale, else lowest locale code), so they agree whenever the picker's result page contains the whole group. They diverge when it does not:

• Search. Translated titles differ. q=Jane matches the en row of a group whose fr row is titled "Jeanne", so only the en variant reaches the list while the edge resolved to fr.
• Page boundary. Variants have independent updated_at, so on a collection past 50 rows one sibling can sit behind the cursor while the other is on page one.

In both cases selectedIds.has(item.id) was false for an entry that is already linked: the row rendered enabled and unchecked, and staging it added a duplicate line to the field. Nothing was corrupted on save — setChildren collapses childGroups through a Set — but the editor showed two rows for one entry until the next load.

Confirmed before fixing, in references-edges.test.ts: a fr parent linking the en row of an en/fr group gets back the fr row's id. That is the id the admin held in selectedIds while the picker was rendering the en row.

What landed:

• EntryRef gains translationGroup (handler, Zod schema, admin type) — the resolved ref now carries the locale-stable identity alongside the variant's id.
• ContentPickerModal keys selectedIds by item.translationGroup ?? item.id when locale is set — the same condition that turns on row collapsing, so the two can't drift: if a row stands for a group, selection matches on the group.
• Menus pass no locale, don't collapse, and keep row-id matching unchanged.
• ReferenceFieldRenderer builds selectedIds from groups and dedupes additions the same way, so a picked variant can't slip past the existing-row check either.

Not taken as suggested: the one-line selectedIds.has(item.translationGroup ?? item.id) alone would have made every already-linked row read as unlinked, because selectedIds held row ids and EntryRef had no group to build a group-keyed set from. The server-side field is what makes the comparison possible.

Two tests in packages/admin/tests/components/ContentPickerModal.test.tsx: a linked entry surfacing only through its sibling variant renders checked and disabled (red before the fix), and the no-locale menu path still matches by row id.

Verification: pnpm exec vitest run in packages/core → 5110 passed / 3 skipped; the admin picker/editor/menu/backlinks suites → 96 passed; pnpm typecheck, pnpm lint:json | jq '.diagnostics | length' → 0, pnpm format.

Type of change

• Feature (requires maintainer-approved Discussion)

Checklist

• I have read CONTRIBUTING.md
• pnpm typecheck passes
• pnpm lint passes (0 diagnostics)
• pnpm test passes (core: 5110 passed / 3 skipped; admin: the picker/editor/menu/backlinks suites touched by the last change, 96 passed)
• pnpm format has been run
• I have added/updated tests for my changes
• User-visible admin strings are wrapped for translation; no messages.po changes included in this PR
• I have added a changeset (emdash: minor, @emdash-cms/admin: minor)
• New features link to an approved Discussion: Complete the reference field: collection picker in schema editor + content picker in content editor #386

AI-generated code disclosure

• This PR includes AI-generated code — model/tool: Claude Opus 4.8 (Claude Code)

Screenshots / test output

emdash   Test Files  396 passed | 1 skipped (397)
              Tests  5110 passed | 3 skipped (5113)

admin    Test Files    5 passed (5)      # picker, editor, menus, backlinks, locale direction
              Tests   96 passed (96)

🤖 Generated with Claude Code

Remains to be fixed

• Backlinks show a buffer in the sidebar even when they are not present
• Clicking "Add a reference" and not selecting anything, then clicking again, shows no items
• The way backlinks are listed should match the new sidebar aesthetics

Remains to be verified

• The search functionality in the content selector uses FTS, same mechanism as the admin's collection page
• The content selector functionality is an abstract and reusable component

[changeset-bot]

🦋 Changeset detected

Latest commit: 2adcb29

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 17 packages

Name	Type
@emdash-cms/admin	Minor
emdash	Minor
@emdash-cms/cloudflare	Minor
@emdash-cms/sandbox-workerd	Patch
@emdash-cms/plugin-mcp-smoke	Major
@emdash-cms/fixture-perf-site	Patch
@emdash-cms/perf-demo-site	Patch
@emdash-cms/cache-demo-site	Patch
@emdash-cms/do-demo-site	Patch
@emdash-cms/do-solo-demo-site	Patch
@emdash-cms/auth	Minor
@emdash-cms/blocks	Minor
@emdash-cms/gutenberg-to-portable-text	Minor
@emdash-cms/x402	Minor
create-emdash	Minor
@emdash-cms/auth-atproto	Patch
@emdash-cms/plugin-embeds	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Scope check

This PR changes 3,014 lines across 34 files. Large PRs are harder to review and more likely to be closed without review.

If this scope is intentional, no action needed. A maintainer will review it. If not, please consider splitting this into smaller PRs.

See CONTRIBUTING.md for contribution guidelines.

[pkg-pr-new]

Open in StackBlitz

@emdash-cms/admin

npm i https://pkg.pr.new/@emdash-cms/admin@1928

@emdash-cms/auth

npm i https://pkg.pr.new/@emdash-cms/auth@1928

@emdash-cms/auth-atproto

npm i https://pkg.pr.new/@emdash-cms/auth-atproto@1928

@emdash-cms/blocks

npm i https://pkg.pr.new/@emdash-cms/blocks@1928

@emdash-cms/cloudflare

npm i https://pkg.pr.new/@emdash-cms/cloudflare@1928

@emdash-cms/contentful-to-portable-text

npm i https://pkg.pr.new/@emdash-cms/contentful-to-portable-text@1928

emdash

npm i https://pkg.pr.new/emdash@1928

create-emdash

npm i https://pkg.pr.new/create-emdash@1928

@emdash-cms/gutenberg-to-portable-text

npm i https://pkg.pr.new/@emdash-cms/gutenberg-to-portable-text@1928

@emdash-cms/plugin-cli

npm i https://pkg.pr.new/@emdash-cms/plugin-cli@1928

@emdash-cms/plugin-types

npm i https://pkg.pr.new/@emdash-cms/plugin-types@1928

@emdash-cms/registry-client

npm i https://pkg.pr.new/@emdash-cms/registry-client@1928

@emdash-cms/registry-lexicons

npm i https://pkg.pr.new/@emdash-cms/registry-lexicons@1928

@emdash-cms/registry-verification

npm i https://pkg.pr.new/@emdash-cms/registry-verification@1928

@emdash-cms/sandbox-workerd

npm i https://pkg.pr.new/@emdash-cms/sandbox-workerd@1928

@emdash-cms/x402

npm i https://pkg.pr.new/@emdash-cms/x402@1928

@emdash-cms/plugin-ai-moderation

npm i https://pkg.pr.new/@emdash-cms/plugin-ai-moderation@1928

@emdash-cms/plugin-atproto

npm i https://pkg.pr.new/@emdash-cms/plugin-atproto@1928

@emdash-cms/plugin-audit-log

npm i https://pkg.pr.new/@emdash-cms/plugin-audit-log@1928

@emdash-cms/plugin-color

npm i https://pkg.pr.new/@emdash-cms/plugin-color@1928

@emdash-cms/plugin-embeds

npm i https://pkg.pr.new/@emdash-cms/plugin-embeds@1928

@emdash-cms/plugin-field-kit

npm i https://pkg.pr.new/@emdash-cms/plugin-field-kit@1928

@emdash-cms/plugin-forms

npm i https://pkg.pr.new/@emdash-cms/plugin-forms@1928

@emdash-cms/plugin-webhook-notifier

npm i https://pkg.pr.new/@emdash-cms/plugin-webhook-notifier@1928

commit: 2adcb29

[emdashbot]

Re-review of PR #1928 (feat/reference-field-admin-ui).

Approach assessment: The reference field architecture is still the right fit for EmDash — storage-less edges, atomic create/update writes, opt-in hydration on the authenticated GET path, relation lifecycle tied to the field, and seed apply mirroring the handler path. The design matches the approved Discussion and the prior review’s assessment.

Status vs. prior review:

• The declined findings about ContentPickerModal locale scoping and references not belonging in RESERVED_FIELD_SLUGS are not reposted; the PR body’s reasoning for both remains internally consistent with the server design.
• The previously reported orphan-edge bug in handleContentPermanentDelete is fixed as described: the handler now fetches the item before deletion, checks hasTranslationsIncludingTrashed, and only clears the group’s edges when no sibling (including trashed/restorable rows) remains.

What I checked: content handler transaction paths, relation repository lifecycle, schema create/update/delete, route wiring and authorization, admin picker/backlinks UI, seed apply, Zod schemas, the transaction nesting helper, and the runtime handler type surface. The code is otherwise clean; the remaining items in the PR description (“backlink buffer”, empty-picker-after-cancel, aesthetics) are acknowledged follow-ups.

One remaining contract gap: the core handlers now accept references on create/update, and the admin callbacks and Zod schemas were updated, but the public EmDashHandlers interface in astro/types.ts still omits it from handleContentCreate and handleContentUpdate. That leaves the published runtime contract out of sync with the implementation.

---

Findings

• [needs fixing] packages/core/src/astro/types.ts:274

  handleContentCreate’s body type in the public EmDashHandlers contract is missing the new references key, even though packages/core/src/api/handlers/content.ts accepts references?: Record<string, string[]>; and the admin/create route now passes it. This makes the runtime type surface inconsistent with the actual handler.

  			taxonomies?: Record<string, string[]>;
  			references?: Record<string, string[]>;
  			createdAt?: string | null;
  

• [needs fixing] packages/core/src/astro/types.ts:297

  Same contract gap for handleContentUpdate: the body type omits references, while the implementation, Zod schema, admin update route, and autosave path all accept it.

  			taxonomies?: Record<string, string[]>;
  			references?: Record<string, string[]>;
  			publishedAt?: string | null;
  

[emdashbot]

Re-review of PR #1928 (feat/reference-field-admin-ui).

Approach assessment: The reference-field architecture remains the right fit for EmDash — storage-less edges keyed by translation_group, atomic create/update writes, opt-in hydration on the authenticated admin GET path, relation lifecycle tied to the field, and seed apply mirroring the handler path. The design matches the approved Discussion and the prior review’s assessment.

Status vs. prior review:

• The two prior findings that were deliberately declined (ContentPickerModal locale scoping and references not belonging in RESERVED_FIELD_SLUGS) remain consistent with the server design and are not reposted.
• The two needs_fixing contract-gap findings from the previous review (missing references in the public EmDashHandlers handleContentCreate / handleContentUpdate body types in astro/types.ts) are resolved: both body types now declare references?: Record<string, string[]>;.
• The previously reported orphan-edge bug in handleContentPermanentDelete is fixed as described: the handler fetches the item before deletion, checks hasTranslationsIncludingTrashed, and only clears the group’s edges when no sibling (including trashed/restorable rows) remains.

What I checked: content handler transaction paths, relation repository lifecycle, schema create/update/delete, route wiring and authorization, admin picker/backlinks UI, seed apply, Zod schemas, the transaction nesting helper, runtime handler types, and SQL/raw identifier safety. The code is otherwise clean; the remaining items listed in the PR description (backlink buffer, empty-picker-after-cancel, aesthetics) are acknowledged follow-ups.

One remaining UI bug: ContentPickerModal compares the rendered item’s concrete row id against selectedIds built from already-referenced row ids. Because the modal collapses results to one row per translation_group and may display a different locale variant than the one the existing reference resolved to, an already-referenced entry can fail the selectedIds check and be added again. The duplicated rows disappear after save (the server dedupes by translation group), but it is a real UX papercut distinct from the acknowledged follow-ups.

No blocking issues; the implementation is solid and the feature should land once the author is comfortable with the picker follow-ups.

[emdashbot]

Re-review of PR #1928 (feat/reference-field-admin-ui).

Approach assessment: The reference-field architecture remains the right fit for EmDash — storage-less edges keyed by translation_group, atomic create/update writes, opt-in hydration on the authenticated admin GET path, relation lifecycle tied to the field, and seed apply mirroring the handler path. The design matches the approved Discussion and the prior review’s assessment.

Status vs. prior review:

• The two prior findings that were deliberately declined (ContentPickerModal locale scoping and references not belonging in RESERVED_FIELD_SLUGS) remain consistent with the server design and are not reposted.
• The previously reported orphan-edge bug in handleContentPermanentDelete is fixed as described: the handler fetches the item before deletion, checks hasTranslationsIncludingTrashed, and only clears the group’s edges when no sibling (including trashed/restorable rows) remains.
• The previously reported ContentPickerModal selection bug is fixed: EntryRef now carries translationGroup, the picker keys selectedIds by translation group when locale is set, and ReferenceFieldRenderer deduplicates by group in both selectedIds and the add-existing guard. Two admin tests verify the cross-locale and menu-path cases.
• The EmDashHandlers body types for handleContentCreate / handleContentUpdate correctly declare references?: Record<string, string[]>.

What I checked: content handler transaction paths, relation repository lifecycle (copyParentEdges, clearReferencesForGroup, setChildren), schema create/update/delete including STORAGELESS_FIELD_TYPES handling, route wiring and authorization for relation/edge endpoints, admin picker/backlinks UI, seed apply reference splitting, Zod schemas, the transaction nesting helper, runtime handler types, migration 043 indexes, Lingui/RTL usage, changesets, and comment discipline.

The code is clean and well-tested; the remaining items listed in the PR description under "Remains to be fixed" are acknowledged follow-ups, not review blockers. No findings.

[emdashbot]

Re-review of PR #1928 (feat/reference-field-admin-ui).

Approach assessment: The reference-field architecture remains the right fit for EmDash — storage-less edges keyed by translation_group, atomic create/update writes inside withTransaction, opt-in hydration on the authenticated admin GET path, relation lifecycle tied to the field, and seed apply mirroring the handler path. The design matches the approved Discussion and the prior review’s assessment.

Status vs. prior review:

• The two prior findings that were deliberately declined (ContentPickerModal locale scoping and references not belonging in RESERVED_FIELD_SLUGS) remain consistent with the server design and are not reposted; the PR body’s rationale still holds.
• All 14 previously reported concrete findings are fixed on the branch and covered by tests as documented in the PR body.
• No new logic bugs, security gaps, AGENTS.md violations, or data-integrity issues surfaced on this pass.

What I rechecked for this pass: the route wiring and authorization for the new relation/edge endpoints, the reference read/write transaction paths in content.ts, the permanent-delete edge-cleanup guard (hasTranslationsIncludingTrashed), duplicate-edge copying, relation lifecycle in the schema handler, migration 043 indexes, STORAGELESS_FIELD_TYPES handling in the registry, seed reference splitting, Zod schemas and handler types, admin picker/backlinks UI (Lingui/RTL usage), and the changesets.

The three items listed under “Remains to be fixed” in the PR description are acknowledged follow-ups rather than unresolved review blockers. The code is clean, well-tested, and ready to merge.