Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

Add recoverable local catalog consolidation that preserves identity and assets

[._.]/ Adam Eivy8ddded5e38db
diff --git a/client/src/components/catalog/CatalogMergePanel.jsx b/client/src/components/catalog/CatalogMergePanel.jsx
new file mode 100644
index 0000000000..1e8d80eb20
--- /dev/null
+++ b/client/src/components/catalog/CatalogMergePanel.jsx
@@ -0,0 +1,258 @@
+import { useCallback, useEffect, useState } from 'react';
+import { useSearchParams } from 'react-router';
+import CollapsibleSection from '../ui/CollapsibleSection';
+import ConfirmButtonPair from '../ui/ConfirmButtonPair';
+import InfiniteScrollFooter from '../ui/InfiniteScrollFooter';
+import toast from '../ui/Toast';
+import { usePagedCollection } from '../../hooks/usePagedCollection';
+import useMounted from '../../hooks/useMounted';
+import { getSelfInstance } from '../../services/apiSystem';
+import { getCatalogIngredientDetails, listCatalogIngredients, previewCatalogMerge, applyCatalogMerge, listCatalogMergeHistory, getCatalogMergeReceipt, recoverCatalogMerge } from '../../services/apiCatalog';
+import { formatCount, formatDateTime } from '../../utils/formatters';
+import { humanizeIntegrityField } from '../../lib/characterIntegrity';
+
+const buttonClass = 'min-h-[44px] px-3 py-2 rounded border border-port-border text-sm text-port-accent disabled:opacity-50';
+const valueText = (value) => value == null ? 'Not set' : typeof value === 'string' ? value || 'Empty' : JSON.stringify(value, null, 2);
+
+function RecordValues({ title, record }) {
+ return <details className="min-w-0 rounded border border-port-border p-3">
+ <summary className="cursor-pointer text-sm font-medium">{title}</summary>
+ <dl className="mt-3 space-y-3 text-xs">
+ {[['name', record?.name], ['tags', record?.tags], ...Object.entries(record?.payload || {}).map(([key, value]) => [`payload/${key}`, value])].map(([key, value]) => (
+ <div key={key}><dt className="text-gray-500">{key.startsWith('payload/') ? `Canon ${humanizeIntegrityField(key.slice(8))}` : humanizeIntegrityField(key)}</dt>
+ <dd className="whitespace-pre-wrap break-words text-gray-300">{valueText(value)}</dd></div>
+ ))}
+ </dl>
+ </details>;
+}
+
+export default function CatalogMergePanel({ record, disabledReason, onChanged, onPendingChange }) {
+ const [params] = useSearchParams();
+ return <CollapsibleSection label="Local consolidation" size="bar" defaultOpen={params.has('mergeSource') || params.has('mergeReceipt')}
+ className="bg-port-card border border-port-border rounded-lg p-4" bodyClassName="pt-3">
+ <MergeManager key={`${record.id}:${record.updatedAt || ''}`} record={record} disabledReason={disabledReason}
+ onChanged={onChanged} onPendingChange={onPendingChange} />
+ </CollapsibleSection>;
+}
+
+function MergeManager({ record, disabledReason, onChanged, onPendingChange }) {
+ const [params, setParams] = useSearchParams();
+ const sourceId = params.get('mergeSource') || '';
+ const [self, setSelf] = useState(null);
+ const [loadError, setLoadError] = useState(null);
+ const [loadVersion, setLoadVersion] = useState(0);
+ const [query, setQuery] = useState('');
+ const [search, setSearch] = useState('');
+ const [busy, setBusy] = useState(false);
+ const [finished, setFinished] = useState(false);
+ useEffect(() => {
+ let active = true;
+ setLoadError(null);
+ getSelfInstance({ silent: true })
+ .then((identity) => {
+ if (!active) return;
+ if (!identity?.instanceId || identity.instanceId === 'unknown') throw new Error('Merge management data is unavailable');
+ setSelf(identity);
+ }).catch((err) => { if (active) setLoadError(err.message); });
+ return () => { active = false; };
+ }, [record.id, loadVersion]);
+
+ const blocked = disabledReason || (record.payload?.locked !== false ? 'This record is locked. Consolidation never unlocks records.'
+ : self && record.originInstanceId !== self.instanceId ? 'This record does not belong to this instance.' : null);
+ const fetchCandidates = useCallback(async ({ cursor, signal }) => {
+ const offset = cursor || 0;
+ const page = await listCatalogIngredients({ type: record.type, q: search, limit: 24, offset, signal, silent: true });
+ if (!Array.isArray(page?.items)) throw new Error('Candidate search is unavailable');
+ return { items: page.items, nextCursor: page.items.length === 24 ? offset + page.items.length : null };
+ }, [record.type, search]);
+ const candidates = usePagedCollection(fetchCandidates, { enabled: !!self && !blocked && !finished });
+ const eligible = candidates.items.filter((item) => item.id !== record.id && item.type === record.type
+ && item.originInstanceId === self?.instanceId && item.payload?.locked === false);
+ const chooseSource = (id) => {
+ const next = new URLSearchParams(params);
+ if (id) next.set('mergeSource', id); else next.delete('mergeSource');
+ setParams(next, { replace: !!sourceId });
+ };
+
+
+ return <div className="space-y-4 text-gray-300">
+ <p className="text-sm">Consolidate two identities on this instance. Matching names do not prove they are the same subject. The current record survives; the source remains recoverable and unchanged for peers.</p>
+ <p className="text-xs text-gray-500">Only local records of the same type that are already unlocked are eligible. No records are permanently purged.</p>
+ {loadError && <div role="alert">{loadError} <button type="button" className={buttonClass} onClick={() => setLoadVersion((v) => v + 1)}>Retry management data</button></div>}
+ {!self && !loadError && <p role="status">Loading consolidation management…</p>}
+ {blocked && <p role="status" className="text-port-warning">{blocked}</p>}
+ {self && !blocked && !finished && <>
+ <form onSubmit={(event) => { event.preventDefault(); setSearch(query.trim()); }} className="flex flex-wrap gap-2 items-end">
+ <div className="min-w-0 flex-1"><label htmlFor="merge-source-search" className="block text-xs mb-1">Find another {record.type}</label>
+ <input id="merge-source-search" value={query} disabled={busy} onChange={(event) => setQuery(event.target.value)}
+ className="w-full bg-port-bg rounded border border-port-border p-2" /></div>
+ <button type="submit" disabled={busy} className={buttonClass}>Search candidates</button>
+ </form>
+ <ul className="space-y-2">{eligible.map((item) => <li key={item.id} className="min-w-0 rounded border border-port-border p-3 flex flex-wrap justify-between gap-2">
+ <div className="min-w-0"><p>{item.name}</p><p className="text-xs break-all text-gray-500">{item.id}</p></div>
+ <button type="button" disabled={busy} className={buttonClass} onClick={() => chooseSource(item.id)} aria-pressed={sourceId === item.id}>Select {item.name}</button>
+ </li>)}</ul>
+ {candidates.loaded && !eligible.length && <p className="text-xs">No eligible candidates in the loaded results. Search by name or load more.</p>}
+ <InfiniteScrollFooter hasMore={candidates.hasMore} loading={candidates.loading} error={candidates.error}
+ onLoadMore={candidates.loadMore} autoLoad={false} label="Load more candidates" />
+ </>}
+ {sourceId && self && !finished && <MergeProposal key={sourceId} sourceId={sourceId} survivor={record} instanceId={self.instanceId}
+ blocked={blocked || (busy ? 'Operation in progress.' : null)} onClear={() => chooseSource('')}
+ onPendingChange={(pending) => { setBusy(pending); onPendingChange?.(pending); }}
+ onMerged={() => { setFinished(true); chooseSource(''); onChanged?.(); }} />}
+ {finished && <p role="status">Operation completed. The record has been refreshed.</p>}
+ {self && <MergeHistory record={record} blocked={blocked || (busy ? 'Operation in progress.' : null)}
+ onPendingChange={(pending) => { setBusy(pending); onPendingChange?.(pending); }}
+ onChanged={onChanged} />}
+
+ </div>;
+}
+
+function MergeProposal({ sourceId, survivor, instanceId, blocked, onClear, onPendingChange, onMerged }) {
+ const [source, setSource] = useState(null);
+ const [choices, setChoices] = useState({});
+ const [preview, setPreview] = useState(null);
+ const [error, setError] = useState(null);
+ const [busy, setBusy] = useState(false);
+ const [confirmed, setConfirmed] = useState(false);
+ const [loadVersion, setLoadVersion] = useState(0);
+ const alive = useMounted();
+ useEffect(() => {
+ let active = true;
+ setSource(null); setError(null);
+ getCatalogIngredientDetails(sourceId, { silent: true }).then((result) => {
+ if (!active) return;
+ if (!result?.ingredient) throw new Error('Source record not found');
+ setSource(result.ingredient);
+ }).catch((err) => { if (active) setError(err.message); });
+ return () => { active = false; };
+ }, [sourceId, loadVersion]);
+ const reason = blocked || (source && (source.id === survivor.id ? 'These URLs already resolve to the same identity.'
+ : source.type !== survivor.type ? 'Both records must have the same type.'
+ : source.originInstanceId !== instanceId ? 'The selected source does not belong to this instance.'
+ : source.payload?.locked !== false ? 'The selected source is locked. Consolidation never unlocks it.' : null));
+ const makePreview = async () => {
+ if (!source || busy || reason) return;
+ setBusy(true); setError(null); setPreview(null); setConfirmed(false); onPendingChange?.(true);
+ try {
+ const result = await previewCatalogMerge({ sourceId: source.id, survivorId: survivor.id, fieldChoices: choices }, { silent: true });
+ if (!result?.previewToken || !Array.isArray(result.conflicts) || !result.proposed) throw new Error('The consolidation preview is unavailable. Please try again.');
+ if (alive.current) setPreview(result);
+ } catch (err) { if (alive.current) setError(err.message); }
+ finally { if (alive.current) setBusy(false); onPendingChange?.(false); }
+ };
+ const apply = async () => {
+ if (!source || busy || reason || !confirmed || !preview?.previewToken || preview.conflicts?.length) return;
+ setBusy(true); setError(null); onPendingChange?.(true);
+ try {
+ const result = await applyCatalogMerge({ sourceId: source.id, survivorId: survivor.id, fieldChoices: choices, previewToken: preview.previewToken }, { silent: true });
+ if (result?.merged !== true) throw new Error('Consolidation was not confirmed. Reload the record and inspect consolidation history.');
+ if (alive.current) { toast.success('Local identities consolidated'); onMerged?.(); }
+ } catch (err) { if (alive.current) { setError(err.message); setPreview(null); setConfirmed(false); } }
+ finally { if (alive.current) setBusy(false); onPendingChange?.(false); }
+ };
+ return <section aria-label="Consolidation preview" className="border border-port-border rounded-lg p-3 space-y-3">
+ <h3 className="text-sm font-semibold">Keep {survivor.name} as the surviving identity</h3>
+ <p className="text-xs break-all">Survivor: {survivor.id} · Source: {sourceId}</p>
+ <button type="button" className={buttonClass} disabled={busy} onClick={onClear}>Clear source selection</button>
+ {reason && <p role="status" className="text-port-warning">{reason}</p>}
+ {error && <p role="alert" className="text-port-error">{error}</p>}
+ {!source && !error && <p role="status">Loading source details…</p>}
+ {!source && error && <button type="button" className={buttonClass} onClick={() => setLoadVersion((v) => v + 1)}>Retry source details</button>}
+ {source && <>
+ <div className="grid grid-cols-1 lg:grid-cols-2 gap-3"><RecordValues title="Survivor before consolidation" record={survivor} /><RecordValues title="Source before consolidation" record={source} /></div>
+ <button type="button" disabled={busy || !!reason} className={buttonClass} onClick={makePreview}>{busy ? 'Working…' : 'Preview consolidation'}</button>
+ {preview && <>
+ {preview.conflicts.map((conflict) => <fieldset key={conflict.path} className="border border-port-warning/40 rounded p-3 space-y-2" disabled={busy}>
+ <legend className="text-xs px-1">Resolve {conflict.path.split('/').filter(Boolean).map(humanizeIntegrityField).join(' / ')}</legend>
+ {['survivor', 'source'].map((side) => <label key={side} className="flex gap-2 items-start text-xs">
+ <input type="radio" name={`merge-${conflict.path}`} checked={choices[conflict.path] === side} onChange={() => {
+ setChoices((current) => ({ ...current, [conflict.path]: side })); setConfirmed(false);
+ }} />
+ <span className="min-w-0"><strong>{side === 'survivor' ? 'Keep survivor value' : 'Use source value'}</strong><span className="block whitespace-pre-wrap break-words">{valueText(conflict[side])}</span></span>
+ </label>)}
+ </fieldset>)}
+ <p className="text-xs text-gray-500">{Object.entries(preview.counts || {}).map(([key, count]) => `${formatCount(count)} ${key}`).join(' · ')} preserved in the recovery receipt.</p>
+ <RecordValues title="Proposed survivor after consolidation" record={preview.proposed} />
+ {!!preview.conflicts.length && <p className="text-xs text-port-warning">Choose every conflicting value, then preview again to review the updated result.</p>}
+ {!preview.conflicts.length && <>
+ <label className="flex gap-2 items-start text-sm"><input type="checkbox" checked={confirmed} disabled={busy} onChange={(event) => setConfirmed(event.target.checked)} />I confirm these are the same subject and have reviewed the proposed result.</label>
+ <button type="button" className={buttonClass} disabled={busy || !!reason || !confirmed} onClick={apply}>Consolidate locally</button>
+ </>}
+ </>}
+ </>}
+ </section>;
+}
+
+function MergeHistory({ record, blocked, onPendingChange, onChanged }) {
+ const [params, setParams] = useSearchParams();
+ const receiptId = params.get('mergeReceipt');
+ const fetchPage = useCallback(async ({ cursor, signal }) => {
+ const result = await listCatalogMergeHistory(record.id, { limit: 10, offset: cursor || 0, signal, silent: true });
+ if (!Array.isArray(result?.items)) throw new Error('Consolidation history is unavailable');
+ return { items: result.items, nextCursor: result.nextOffset };
+ }, [record.id]);
+ const history = usePagedCollection(fetchPage);
+ const inspect = (id) => {
+ const next = new URLSearchParams(params);
+ if (id) next.set('mergeReceipt', id); else next.delete('mergeReceipt');
+ setParams(next, { replace: !!receiptId });
+ };
+ return <section aria-label="Consolidation history" className="space-y-3">
+ <h3 className="text-sm font-semibold">Consolidation history</h3>
+ {history.loaded && !history.items.length && <p className="text-xs text-gray-500">No local consolidations recorded.</p>}
+ {history.items.map((receipt) => <div key={receipt.id} className="rounded border border-port-border p-3 space-y-2">
+ <p className="text-xs break-all">{receipt.sourceId} → {receipt.survivorId}</p>
+ <p className="text-xs text-gray-500">{formatDateTime(receipt.createdAt)}{receipt.restoredAt ? ` · Recovered ${formatDateTime(receipt.restoredAt)}` : ''}</p>
+ <p className="text-xs text-gray-500">{Object.entries(receipt.counts || {}).map(([key, count]) => `${formatCount(count)} ${key}`).join(' · ')} archived</p>
+ <button type="button" className={buttonClass} onClick={() => inspect(receipt.id)}>Inspect originals</button>
+ </div>)}
+ <InfiniteScrollFooter hasMore={history.hasMore} loading={history.loading} error={history.error}
+ onLoadMore={history.loadMore} autoLoad={false} label="Load more history" />
+ {receiptId && <MergeReceipt key={receiptId} id={receiptId} ingredientId={record.id} blocked={blocked}
+ onPendingChange={onPendingChange} onChanged={onChanged} onClose={() => inspect(null)} />}
+ </section>;
+}
+
+function MergeReceipt({ id, ingredientId, blocked, onPendingChange, onChanged, onClose }) {
+ const [receipt, setReceipt] = useState(null);
+ const [loadVersion, setLoadVersion] = useState(0);
+ const [error, setError] = useState(null);
+ const [busy, setBusy] = useState(false);
+ const [armed, setArmed] = useState(false);
+ const alive = useMounted();
+ useEffect(() => {
+ let active = true;
+ setReceipt(null); setError(null);
+ getCatalogMergeReceipt(id, { silent: true }).then((result) => {
+ if (!active) return;
+ if (!Array.isArray(result?.beforeState?.ingredients) || ![result.sourceId, result.survivorId].includes(ingredientId)) throw new Error('This receipt does not belong to the current record.');
+ setReceipt(result);
+ }).catch((err) => { if (active) setError(err.message); });
+ return () => { active = false; };
+ }, [id, ingredientId, loadVersion]);
+ const recover = async () => {
+ if (busy || blocked || !receipt) return;
+ setBusy(true); setError(null); onPendingChange?.(true);
+ try {
+ const result = await recoverCatalogMerge(id, { silent: true });
+ if (result?.restored !== true) throw new Error('Recovery was not confirmed. Reload the record and inspect consolidation history.');
+ if (!alive.current) return;
+ setArmed(false); toast.success('Local consolidation recovered'); onChanged?.();
+ } catch (err) { if (alive.current) setError(err.message); }
+ finally { if (alive.current) setBusy(false); onPendingChange?.(false); }
+ };
+ return <section aria-label="Archived consolidation" className="space-y-3 border border-port-border p-3 rounded">
+ <button type="button" disabled={busy} className={buttonClass} onClick={onClose}>Close archived originals</button>
+ {error && <p role="alert" className="text-port-error">{error}</p>}
+ {!receipt && !error && <p role="status">Loading archived originals…</p>}
+ {!receipt && error && <button type="button" className={buttonClass} onClick={() => setLoadVersion((v) => v + 1)}>Retry archived originals</button>}
+ {receipt && <>
+ <div className="grid grid-cols-1 lg:grid-cols-2 gap-3">{receipt.beforeState.ingredients?.map((item) =>
+ <RecordValues key={item.id} title={`Archived original: ${item.name}`} record={item} />)}</div>
+ {!receipt.restoredAt && (armed ? <ConfirmButtonPair prompt="Recover the archived local state? Later edits or new locks will block recovery."
+ confirmText="Recover consolidation" onConfirm={recover} onCancel={() => setArmed(false)} busy={busy || !!blocked} largeTouchTargets />
+ : <button type="button" className={buttonClass} disabled={!!blocked || busy} onClick={() => setArmed(true)}>Recover this consolidation</button>)}
+ </>}
+ </section>;
+}
diff --git a/client/src/components/catalog/CatalogMergePanel.test.jsx b/client/src/components/catalog/CatalogMergePanel.test.jsx
new file mode 100644
index 0000000000..328766305d
--- /dev/null
+++ b/client/src/components/catalog/CatalogMergePanel.test.jsx
@@ -0,0 +1,127 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { createMemoryRouter, RouterProvider } from 'react-router';
+import CatalogMergePanel from './CatalogMergePanel';
+import { getSelfInstance } from '../../services/apiSystem';
+import { getCatalogIngredientDetails, listCatalogIngredients, previewCatalogMerge, applyCatalogMerge, listCatalogMergeHistory, getCatalogMergeReceipt, recoverCatalogMerge } from '../../services/apiCatalog';
+
+vi.mock('../../services/apiSystem', () => ({ getSelfInstance: vi.fn() }));
+vi.mock('../../services/apiCatalog', () => ({
+ getCatalogIngredientDetails: vi.fn(), listCatalogIngredients: vi.fn(), previewCatalogMerge: vi.fn(),
+ applyCatalogMerge: vi.fn(), listCatalogMergeHistory: vi.fn(), getCatalogMergeReceipt: vi.fn(), recoverCatalogMerge: vi.fn(),
+}));
+vi.mock('../ui/Toast', () => ({ default: { success: vi.fn() } }));
+
+const survivor = { id: 'example-survivor', name: 'Example subject', type: 'character', originInstanceId: 'example-local', payload: { locked: false, role: 'Guide' }, updatedAt: '2026-01-01' };
+const source = { ...survivor, id: 'example-source', name: 'Example alias', payload: { locked: false, description: 'A thoughtful guide' } };
+const proposed = { name: survivor.name, payload: { ...source.payload, ...survivor.payload }, tags: [] };
+const onChanged = vi.fn();
+
+async function show({ record = survivor, route = '/casting/example-survivor/profile', disabledReason } = {}) {
+ const router = createMemoryRouter([{ path: '/casting/:id/profile', element: <CatalogMergePanel record={record} onChanged={onChanged} disabledReason={disabledReason} /> }], { initialEntries: [route] });
+ render(<RouterProvider router={router} />);
+ if (!route.includes('mergeSource') && !route.includes('mergeReceipt')) fireEvent.click(screen.getByRole('button', { name: 'Local consolidation' }));
+ await act(async () => {});
+ return router;
+}
+
+beforeEach(() => {
+ vi.resetAllMocks();
+ getSelfInstance.mockResolvedValue({ instanceId: 'example-local' });
+ listCatalogMergeHistory.mockResolvedValue({ items: [], nextOffset: null });
+ listCatalogIngredients.mockResolvedValue({ items: [source] });
+ getCatalogIngredientDetails.mockResolvedValue({ ingredient: source });
+ previewCatalogMerge.mockResolvedValue({ sourceId: source.id, survivorId: survivor.id, proposed, conflicts: [], previewToken: 'fresh-token', counts: { media: 3, revisions: 4 } });
+ applyCatalogMerge.mockResolvedValue({ merged: true, scope: 'local' });
+});
+
+describe('catalog local consolidation management', () => {
+ it('requires explicit conflict choices, a new preview and identity confirmation before token-bound apply', async () => {
+ previewCatalogMerge.mockResolvedValueOnce({ proposed, conflicts: [{ path: '/name', source: source.name, survivor: survivor.name }], previewToken: 'old-token', counts: {} });
+ const router = await show();
+ fireEvent.click(screen.getByRole('button', { name: 'Select Example alias' }));
+ expect(new URLSearchParams(router.state.location.search).get('mergeSource')).toBe(source.id);
+ fireEvent.click(await screen.findByRole('button', { name: 'Preview consolidation' }));
+ expect(await screen.findByText('Resolve Name')).toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: 'Consolidate locally' })).not.toBeInTheDocument();
+ fireEvent.click(screen.getByRole('radio', { name: /Keep survivor value/ }));
+ fireEvent.click(screen.getByRole('button', { name: 'Preview consolidation' }));
+ await waitFor(() => expect(previewCatalogMerge).toHaveBeenLastCalledWith({ sourceId: source.id, survivorId: survivor.id, fieldChoices: { '/name': 'survivor' } }, { silent: true }));
+ const apply = await screen.findByRole('button', { name: 'Consolidate locally' });
+ expect(apply).toBeDisabled();
+ fireEvent.click(screen.getByRole('checkbox', { name: /I confirm these are the same subject/ }));
+ fireEvent.click(apply);
+ await waitFor(() => expect(applyCatalogMerge).toHaveBeenCalledWith({ sourceId: source.id, survivorId: survivor.id, fieldChoices: { '/name': 'survivor' }, previewToken: 'fresh-token' }, { silent: true }));
+ expect(onChanged).toHaveBeenCalledTimes(1);
+ });
+
+ it('filters local unlocked same-type candidates and blocks a locked direct source link', async () => {
+ listCatalogIngredients.mockResolvedValue({ items: [source, { ...source, id: 'foreign', name: 'Foreign example', originInstanceId: 'peer-example' }, { ...source, id: 'locked', name: 'Locked example', payload: { locked: true } }, { ...source, id: 'other-type', name: 'Other example', type: 'object' }] });
+ await show();
+ expect(screen.getByRole('button', { name: 'Select Example alias' })).toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: /Select Foreign|Select Locked|Select Other/ })).not.toBeInTheDocument();
+ getCatalogIngredientDetails.mockResolvedValue({ ingredient: { ...source, payload: { locked: true } } });
+ fireEvent.click(screen.getByRole('button', { name: 'Select Example alias' }));
+ expect(await screen.findByText('The selected source is locked. Consolidation never unlocks it.')).toBeInTheDocument();
+ expect(screen.getByRole('button', { name: 'Preview consolidation' })).toBeDisabled();
+ expect(previewCatalogMerge).not.toHaveBeenCalled();
+ });
+
+ it('invalidates an apply preview after a stale-state rejection', async () => {
+ applyCatalogMerge.mockRejectedValue(new Error('Catalog changed; preview again'));
+ await show({ route: '/casting/example-survivor/profile?mergeSource=example-source' });
+ fireEvent.click(await screen.findByRole('button', { name: 'Preview consolidation' }));
+ fireEvent.click(await screen.findByRole('checkbox', { name: /I confirm these are the same subject/ }));
+ fireEvent.click(screen.getByRole('button', { name: 'Consolidate locally' }));
+ expect(await screen.findByRole('alert')).toHaveTextContent('Catalog changed; preview again');
+ expect(screen.queryByRole('button', { name: 'Consolidate locally' })).not.toBeInTheDocument();
+ expect(onChanged).not.toHaveBeenCalled();
+ });
+
+ it('preserves a recovery refusal and never offers force recovery', async () => {
+ const receipt = { id: 'example-receipt', sourceId: source.id, survivorId: survivor.id, beforeState: { ingredients: [source, survivor] }, createdAt: '2026-01-01' };
+ listCatalogMergeHistory.mockResolvedValue({ items: [{ ...receipt, beforeState: undefined }], nextOffset: null });
+ getCatalogMergeReceipt.mockResolvedValue(receipt);
+ recoverCatalogMerge.mockRejectedValue(new Error('Merged state changed; recovery would overwrite later work'));
+ await show();
+ expect(getCatalogMergeReceipt).not.toHaveBeenCalled();
+ fireEvent.click(await screen.findByRole('button', { name: 'Inspect originals' }));
+ expect(await screen.findByText('Archived original: Example alias')).toBeInTheDocument();
+ fireEvent.click(screen.getByRole('button', { name: 'Recover this consolidation' }));
+ fireEvent.click(screen.getByRole('button', { name: 'Recover consolidation' }));
+ expect(await screen.findByRole('alert')).toHaveTextContent('recovery would overwrite later work');
+ expect(recoverCatalogMerge).toHaveBeenCalledWith('example-receipt', { silent: true });
+ expect(screen.queryByRole('button', { name: /force/i })).not.toBeInTheDocument();
+ expect(onChanged).not.toHaveBeenCalled();
+ });
+
+ it('pages history summaries and deep-links only the selected archived receipt', async () => {
+ const receipt = { id: 'receipt-one', sourceId: source.id, survivorId: survivor.id, createdAt: '2026-01-01' };
+ listCatalogMergeHistory.mockResolvedValueOnce({ items: [receipt], nextOffset: 10 })
+ .mockResolvedValueOnce({ items: [{ ...receipt, id: 'receipt-two' }], nextOffset: null });
+ getCatalogMergeReceipt.mockResolvedValue({ ...receipt, beforeState: { ingredients: [source, survivor] } });
+ const router = await show();
+ expect(getCatalogMergeReceipt).not.toHaveBeenCalled();
+ fireEvent.click(await screen.findByRole('button', { name: 'Load more history' }));
+ await waitFor(() => expect(listCatalogMergeHistory).toHaveBeenLastCalledWith(survivor.id, expect.objectContaining({ limit: 10, offset: 10 })));
+ fireEvent.click((await screen.findAllByRole('button', { name: 'Inspect originals' }))[0]);
+ expect(new URLSearchParams(router.state.location.search).get('mergeReceipt')).toBe('receipt-one');
+ expect(await screen.findByText('Archived original: Example alias')).toBeInTheDocument();
+ expect(getCatalogMergeReceipt).toHaveBeenCalledTimes(1);
+ });
+
+ it('rejects a direct receipt link belonging to a different ingredient', async () => {
+ getCatalogMergeReceipt.mockResolvedValue({ id: 'unrelated-receipt', sourceId: 'other-source', survivorId: 'other-survivor', beforeState: { ingredients: [source] } });
+ await show({ route: '/casting/example-survivor/profile?mergeReceipt=unrelated-receipt' });
+ expect(await screen.findByRole('alert')).toHaveTextContent('This receipt does not belong to the current record.');
+ expect(screen.queryByRole('button', { name: 'Recover this consolidation' })).not.toBeInTheDocument();
+ expect(recoverCatalogMerge).not.toHaveBeenCalled();
+ });
+
+ it('blocks consolidation while profile edits are unsaved', async () => {
+ await show({ disabledReason: 'Save or discard profile edits before consolidating.' });
+ expect(screen.getByText('Save or discard profile edits before consolidating.')).toBeInTheDocument();
+ expect(listCatalogIngredients).not.toHaveBeenCalled();
+ expect(previewCatalogMerge).not.toHaveBeenCalled();
+ });
+});
diff --git a/client/src/pages/CatalogIngredient.jsx b/client/src/pages/CatalogIngredient.jsx
index 9e1e87f6fb..4e26b88115 100644
--- a/client/src/pages/CatalogIngredient.jsx
+++ b/client/src/pages/CatalogIngredient.jsx
@@ -59,6 +59,7 @@ import CatalogUnlockNotice from '../components/catalog/CatalogUnlockNotice';
import CatalogPlatesPanel from '../components/catalog/CatalogPlatesPanel';
import CatalogLooksPanel from '../components/catalog/CatalogLooksPanel';
import CatalogCharacterCanon from '../components/catalog/CatalogCharacterCanon';
+import CatalogMergePanel from '../components/catalog/CatalogMergePanel';
import CharacterLoraChip from '../components/loraTraining/CharacterLoraChip';
import TagPicker from '../components/TagPicker';
import GenericIngredientFields from '../components/GenericIngredientFields';
@@ -175,6 +176,8 @@ export default function CatalogIngredient() {
// the static built-ins so the editor renders before the fetch resolves.
const { getType: getMergedType } = useCatalogTypes();
const [record, setRecord] = useState(null);
+ const [mergeVersion, setMergeVersion] = useState(0);
+ const [mergeBusy, setMergeBusy] = useState(false);
const [loading, setLoading] = useState(true);
const [name, setName] = useState('');
const [tags, setTags] = useState([]);
@@ -242,7 +245,7 @@ export default function CatalogIngredient() {
navigate(backPath);
});
return () => { cancelled = true; };
- }, [id, navigate, backPath]);
+ }, [id, navigate, backPath, mergeVersion]);
// Add an outbound edge (this ingredient → picked target). Optimistically
// appends to local state so the panel updates without a refetch.
@@ -610,7 +613,7 @@ export default function CatalogIngredient() {
...record,
thumbnailKey: media.find((m) => m.kind === 'portrait')?.mediaKey || record.thumbnailKey,
payload,
- }) || ingredientCoverUrl({ thumbnailKey: media.find((m) => m.kind === 'reference')?.mediaKey });
+ }) || ingredientCoverUrl({ thumbnailKey: media.find((m) => m.kind === 'reference' && !m.role?.startsWith('archive:'))?.mediaKey });
const renderBlockedReason = (subject) => (record.payload?.locked === true
? 'Unlock this record above before rendering.'
: saving
@@ -627,7 +630,7 @@ export default function CatalogIngredient() {
label={`Discard unsaved changes to ${record.name || 'this ingredient'}`}
onDiscard={discardAndExit}
/>
- <div className="w-full min-w-0 space-y-5">
+ <fieldset disabled={mergeBusy} className="w-full min-w-0 space-y-5">
<header className="flex items-start justify-between gap-3 flex-wrap">
<div className="flex items-start gap-3 min-w-0">
<Sparkles className="w-6 h-6 text-port-accent mt-1 flex-shrink-0" aria-hidden="true" />
@@ -650,7 +653,7 @@ export default function CatalogIngredient() {
<Link to={backPath} className="inline-flex items-center gap-1.5 px-3 py-2 rounded-lg text-sm text-gray-400 hover:text-white">
<ArrowLeft size={14} aria-hidden="true" /> Back
</Link>
- <button type="button" onClick={handleSave} disabled={saving || lookSaving || unlocking}
+ <button type="button" onClick={handleSave} disabled={saving || lookSaving || unlocking || mergeBusy}
className="inline-flex items-center gap-1.5 px-3 py-2 rounded-lg bg-port-accent hover:bg-port-accent/90 disabled:opacity-50 text-white text-sm font-medium">
{saving ? <Loader2 size={14} className="animate-spin" /> : <Save size={14} />} Save
</button>
@@ -856,6 +859,12 @@ export default function CatalogIngredient() {
]} />
)}
+ {activeTab === 'profile' && (
+ <CatalogMergePanel record={record}
+ disabledReason={saving || lookSaving || unlocking ? 'Wait for the current save to finish.' : isDirty ? 'Save or discard profile edits before consolidating.' : null}
+ onPendingChange={setMergeBusy} onChanged={() => setMergeVersion((version) => version + 1)} />
+ )}
+
{activeTab === 'profile' && (
<RevisionsPanel
revisions={revisions}
@@ -864,7 +873,7 @@ export default function CatalogIngredient() {
onRestore={handleRestore}
/>
)}
- </div>
+ </fieldset>
</section>
</CatalogImagePreviewProvider>
);
diff --git a/client/src/pages/CatalogIngredient.test.jsx b/client/src/pages/CatalogIngredient.test.jsx
index 3832fc3939..0f3cefcfc6 100644
--- a/client/src/pages/CatalogIngredient.test.jsx
+++ b/client/src/pages/CatalogIngredient.test.jsx
@@ -928,6 +928,19 @@ describe('CatalogIngredient — tabbed library record pages', () => {
expect(screen.getAllByRole('img').filter((image) => image.getAttribute('src') === '/data/images/chosen.png')).toHaveLength(1);
});
+ it('keeps archive-only reference media visible on References without using it as a profile cover', async () => {
+ getCatalogIngredientDetails.mockResolvedValue({
+ ...detailsOf({ ...HERO, payload: {}, thumbnailKey: null }),
+ media: [{ kind: 'reference', mediaKey: 'archived-source.png', role: 'archive:portrait', caption: 'Archived source image' }],
+ });
+ const profile = await renderPage('/casting/cat-chr-hero/profile');
+ expect(screen.queryByAltText('Example Hero cover')).not.toBeInTheDocument();
+ profile.unmount();
+ await renderPage('/casting/cat-chr-hero/references');
+ expect(screen.getByAltText('Archived source image')).toHaveAttribute('src', '/data/images/archived-source.png');
+ expect(screen.getByRole('button', { name: 'Enlarge Archived source image' })).toBeInTheDocument();
+ });
+
it('loads related renders only on the media tab, deduplicates known images and retries a failed next page', async () => {
getCatalogIngredientDetails.mockResolvedValue(detailsOf({ ...HERO, payload: { imageRefs: ['known.png'] } }));
const profile = await renderPage('/casting/cat-chr-hero/profile');
diff --git a/client/src/services/README.md b/client/src/services/README.md
index 8902b2d82f..564c51862a 100644
--- a/client/src/services/README.md
+++ b/client/src/services/README.md
@@ -59,7 +59,7 @@ toasts on throw). **Custom catch ⇒ `silent: true`** — otherwise toasts fire
| `apiReferenceRepos.js` | Per-app reference-repo registry. |
| `apiReview.js` | Review hub. |
| `apiCodeReview.js` | Code Review Defaults (Review Loop reviewer chain + per-backend local-LLM model). |
-| `apiCatalog.js` | Creative catalog ingredients (list/create/update/delete + `listCatalogIngredientsByIds` / facets) scrap ingest (create/extract/commit + url/file/voice/brain), and reference sheets (`listCatalogSheetVariants` / `previewCatalogSheet` / `renderCatalogSheet`). |
+| `apiCatalog.js` | Creative catalog ingredients (list/create/update/delete + `listCatalogIngredientsByIds` / facets) scrap ingest (create/extract/commit + url/file/voice/brain), reference sheets (`listCatalogSheetVariants` / `previewCatalogSheet` / `renderCatalogSheet`), and local consolidation preview/apply/history/recovery. |
| `apiCatalogTypes.js` | User-defined catalog ingredient types (list active registry + create/update/delete user types). |
| `apiRuns.js` | Agent run history. |
| `apiScaffold.js` | App scaffolding templates. |
diff --git a/client/src/services/apiCatalog.js b/client/src/services/apiCatalog.js
index 3d2f25cfaa..0d982e8bfd 100644
--- a/client/src/services/apiCatalog.js
+++ b/client/src/services/apiCatalog.js
@@ -222,3 +222,16 @@ export const rerunCatalogMigration = ({ force, ...options } = {}) =>
export const previewMusicVideoCastImport = (options) => request('/catalog/import/music-videos', options);
export const commitMusicVideoCastImport = (selections, options) =>
request('/catalog/import/music-videos', { method: 'POST', body: JSON.stringify({ selections }), ...options });
+
+export const previewCatalogMerge = (body, options) =>
+ request('/catalog/ingredients/merge', { method: 'POST', body: JSON.stringify({ ...body, dryRun: true }), ...options });
+export const applyCatalogMerge = (body, options) =>
+ request('/catalog/ingredients/merge', { method: 'POST', body: JSON.stringify({ ...body, dryRun: false }), ...options });
+export const listCatalogMergeHistory = (id, { limit = 10, offset = 0, ...options } = {}) => {
+ const params = new URLSearchParams({ limit: String(limit), offset: String(offset) });
+ return request(`/catalog/ingredients/${enc(id)}/merge-history?${params}`, options);
+};
+export const getCatalogMergeReceipt = (id, options) =>
+ request(`/catalog/ingredient-merges/${enc(id)}`, options);
+export const recoverCatalogMerge = (id, options) =>
+ request(`/catalog/ingredient-merges/${enc(id)}/recover`, { method: 'POST', body: '{}', ...options });
diff --git a/docs/CATALOG_LOCAL_MERGE.md b/docs/CATALOG_LOCAL_MERGE.md
new file mode 100644
index 0000000000..014ce811e0
--- /dev/null
+++ b/docs/CATALOG_LOCAL_MERGE.md
@@ -0,0 +1,64 @@
+# Local catalog consolidation
+
+The catalog detail page offers **Local consolidation** for two explicitly selected,
+same-type ingredients owned by this instance. Both records must already be
+unlocked. A matching name is not evidence of identity; the operator selects the
+source and confirms the reviewed result. The page being viewed is the survivor.
+
+Consolidation unions lists and asks for a choice for every unequal populated
+scalar, including fields inside array objects with the same stable ID. It keeps
+both names discoverable, preserves images and attachments, and retains the complete
+original histories and provenance in a local receipt. A second portrait becomes a
+reference so it remains visible without replacing the survivor's portrait.
+
+The source stays unchanged and live for peers. On this instance its stable ID
+resolves to the survivor, and local list/search/facet results show one identity.
+Exports preserve both original identities and their media. This is **not a
+federated deletion or a cross-owner merge**. Consolidating a foreign-owned record
+requires an owner-coordinated operation; this API refuses it.
+
+Embedded project/canon copies are preserved as contextual records. A retained
+source-ID canon snapshot cannot overwrite the consolidated catalog payload.
+A subsequent explicit catalog edit can refresh matching embedded canon through
+the existing projection path. Sheet rendering uses consolidated catalog data
+rather than delegating to an older embedded variant. Existing image jobs attaching
+to the old ID resolve to the survivor.
+
+## API workflow
+
+All paths are relative to `/api/catalog` and use the existing authenticated API.
+No endpoint unlocks a record or performs generation.
+
+1. `POST /ingredients/merge` with `sourceId`, `survivorId` and `dryRun: true`
+ returns `proposed`, `conflicts`, `counts`, and `previewToken`. Each conflict
+ names a JSON-pointer `path` and the `source` and `survivor` values.
+2. Set `fieldChoices` to a map from those paths to `source` or `survivor` and
+ request a fresh preview. For example, `{ "/name": "survivor" }` retains the
+ survivor's display name. Do not reuse a token after changing choices.
+3. Submit the same IDs and choices with `dryRun: false` and the reviewed
+ `previewToken`. Apply checks the full record, media, link, relation and revision
+ snapshot inside a database transaction. Any intervening change returns
+ `409 CATALOG_MERGE_STALE`; obtain and review a new preview.
+4. `GET /ingredients/:id/merge-history` returns paginated receipt summaries (`limit`, `offset`, and
+ `nextOffset: null` when exhausted). `GET /ingredient-merges/:receiptId` loads
+ one original snapshot on demand. Revision history also includes source revisions with their original
+ `ingredientId`, so provenance stays visible and restore is still available.
+5. `POST /ingredient-merges/:receiptId/recover` with `{}` restores the original
+ identities and associations only if the applied state is still unchanged and
+ both records remain locally owned and unlocked. It retains audit history and
+ emits tombstones for added reference/media/relation links. It refuses to
+ overwrite later edits, jobs, attachments, or locks. There is no force option.
+
+An identity participating in an active consolidation cannot enter another one;
+recover first. This prevents redirect chains and cycles. A receipt remains after
+recovery. Source rows and active survivors cannot be deleted while a consolidation
+is active. Legacy peer updates cannot rewrite the retained source.
+
+## Rollout
+
+This feature requires the server code and its additive boot schema (the local
+`catalog_ingredient_merges` receipt table, resolver function and protective
+trigger), plus the client build. The schema does not enqueue work or consolidate
+records. A normal authorized deployment/restart is required before the endpoints
+exist on a running instance. Code merge alone does not deploy it. Each subsequent
+catalog consolidation is a separate explicit operator action.
diff --git a/docs/README.md b/docs/README.md
index a45d80c31d..3672e6013f 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -13,6 +13,7 @@ Index of everything under `docs/`. Start with the [root README](../README.md) fo
| [CODE_ANIMATION_PACKAGES.md](./CODE_ANIMATION_PACKAGES.md) | Versioned portable Code Animation source/brief packages, non-executing validation, and contained production execution |
| [ARCHITECTURE.md](./ARCHITECTURE.md) | System design: React client, Express server, PM2 satellites, PostgreSQL + `data/` files |
| [features/catalog-ingest.md](./features/catalog-ingest.md) | Catalog extraction graph, context budgets, coverage, and review draft contract |
+| [CATALOG_LOCAL_MERGE.md](./CATALOG_LOCAL_MERGE.md) | Local catalog consolidation, preserved identities and assets, conflict review, and guarded recovery |
| [API.md](./API.md) | REST endpoints, complete route-domain index, Socket.IO events |
| [API_TOOL_CONTRACT.md](./API_TOOL_CONTRACT.md) | Unified semantic tool, Persistent Mind, and Agent Tools MCP contract |
| [COMPANION_APP_API.md](./COMPANION_APP_API.md) | PortDeck native iOS companion client discovery and HTTP API contract |
diff --git a/scripts/lib/dbTestFiles.js b/scripts/lib/dbTestFiles.js
index 82c792cf48..c5744bc6ba 100644
--- a/scripts/lib/dbTestFiles.js
+++ b/scripts/lib/dbTestFiles.js
@@ -9,6 +9,7 @@ import { posix } from 'node:path';
* listed explicitly below (the drift guard fails the build if you forget).
*/
export const DB_TEST_INCLUDE = [
+ 'services/catalogDB.merge.db.test.js',
'services/trackAlbumMembership.db.test.js',
'services/stackerNews.db.test.js',
'services/peerExecutionLedger.db.test.js',
diff --git a/server/lib/catalogValidation.js b/server/lib/catalogValidation.js
index d3a2457e9f..b59725aad4 100644
--- a/server/lib/catalogValidation.js
+++ b/server/lib/catalogValidation.js
@@ -809,3 +809,17 @@ export const catalogSyncEnvelopeSchema = z.object({
catalogTypes: z.array(catalogSyncUserTypeSchema).max(64).optional(),
portosMeta,
}).passthrough();
+
+export const catalogMergeSchema = z.object({
+ sourceId: z.string().min(1).max(200),
+ survivorId: z.string().min(1).max(200),
+ dryRun: z.boolean().default(true),
+ previewToken: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+ fieldChoices: z.record(z.string(), z.enum(['source', 'survivor'])).default({}),
+}).strict();
+export const catalogMergeRecoverSchema = z.object({}).strict();
+
+export const catalogMergeHistoryQuerySchema = z.object({
+ limit: z.coerce.number().int().min(1).max(50).default(10),
+ offset: z.coerce.number().int().min(0).default(0),
+}).strict();
diff --git a/server/lib/db/schema/catalog.js b/server/lib/db/schema/catalog.js
index 620a836f26..20264af78c 100644
--- a/server/lib/db/schema/catalog.js
+++ b/server/lib/db/schema/catalog.js
@@ -236,6 +236,38 @@ export const catalogDdl = [
`CREATE INDEX IF NOT EXISTS idx_catalog_tags_parent ON catalog_tags (parent_id)`,
`CREATE INDEX IF NOT EXISTS idx_catalog_tags_sync_seq ON catalog_tags (sync_sequence)`,
+ `CREATE TABLE IF NOT EXISTS catalog_ingredient_merges (
+ id TEXT PRIMARY KEY,
+ source_id TEXT NOT NULL REFERENCES catalog_ingredients(id),
+ survivor_id TEXT NOT NULL REFERENCES catalog_ingredients(id),
+ before_state JSONB NOT NULL,
+ after_fingerprint TEXT NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ restored_at TIMESTAMPTZ,
+ CHECK (source_id <> survivor_id)
+ )`,
+ `CREATE UNIQUE INDEX IF NOT EXISTS idx_catalog_merge_source_active
+ ON catalog_ingredient_merges (source_id) WHERE restored_at IS NULL`,
+ `CREATE OR REPLACE FUNCTION catalog_resolve_ingredient_id(requested_id TEXT)
+ RETURNS TEXT LANGUAGE SQL STABLE AS $$
+ SELECT COALESCE((SELECT survivor_id FROM catalog_ingredient_merges
+ WHERE source_id = requested_id AND restored_at IS NULL), requested_id)
+ $$`,
+ `CREATE OR REPLACE FUNCTION guard_catalog_merged_ingredient()
+ RETURNS TRIGGER LANGUAGE plpgsql AS $$
+ BEGIN
+ IF EXISTS (SELECT 1 FROM catalog_ingredient_merges WHERE restored_at IS NULL
+ AND (source_id = OLD.id OR (survivor_id = OLD.id AND
+ (TG_OP = 'DELETE' OR NEW.deleted = true)))) THEN
+ RAISE EXCEPTION 'Merged ingredient is protected; recover its merge first';
+ END IF;
+ IF TG_OP = 'DELETE' THEN RETURN OLD; END IF;
+ RETURN NEW;
+ END $$`,
+ `DROP TRIGGER IF EXISTS trg_catalog_merged_ingredient ON catalog_ingredients`,
+ `CREATE TRIGGER trg_catalog_merged_ingredient BEFORE UPDATE OR DELETE ON catalog_ingredients
+ FOR EACH ROW EXECUTE FUNCTION guard_catalog_merged_ingredient()`,
+
// Append-only revision history for catalog_ingredients (local audit, not
// federated). Written by catalogDB.updateIngredient on every content change
// + a seed row on create; pruned to the last CATALOG_REVISION_RETENTION per
diff --git a/server/routes/catalog.js b/server/routes/catalog.js
index 14750a0b9a..e052e90bae 100644
--- a/server/routes/catalog.js
+++ b/server/routes/catalog.js
@@ -315,6 +315,34 @@ router.get('/ingredients/:id/related-images', asyncHandler(async (req, res) => {
res.json(await listRelatedImages(ingredient, media, pagination));
}));
+// Merge is preview-first and never unlocks either record.
+router.post('/ingredients/merge', asyncHandler(async (req, res) => {
+ const { catalogMergeSchema } = await import('../lib/catalogValidation.js');
+ const body = validateRequest(catalogMergeSchema, req.body);
+ const { mergeIngredients } = await import('../services/catalogDB/merge.js');
+ res.json(await mergeIngredients(body));
+}));
+
+router.get('/ingredients/:id/merge-history', asyncHandler(async (req, res) => {
+ const { catalogMergeHistoryQuerySchema } = await import('../lib/catalogValidation.js');
+ const params = validateRequest(catalogMergeHistoryQuerySchema, req.query);
+ const { getIngredientMergeHistory } = await import('../services/catalogDB/merge.js');
+ res.json(await getIngredientMergeHistory(req.params.id, params));
+}));
+
+router.get('/ingredient-merges/:id', asyncHandler(async (req, res) => {
+ const { getIngredientMergeReceipt } = await import('../services/catalogDB/merge.js');
+ res.json(await getIngredientMergeReceipt(req.params.id));
+}));
+
+router.post('/ingredient-merges/:id/recover', asyncHandler(async (req, res) => {
+ const { catalogMergeRecoverSchema } = await import('../lib/catalogValidation.js');
+ validateRequest(catalogMergeRecoverSchema, req.body ?? {});
+ const { recoverIngredientMerge } = await import('../services/catalogDB/merge.js');
+ res.json(await recoverIngredientMerge(req.params.id));
+
+}));
+
router.post('/ingredients', asyncHandler(async (req, res) => {
const body = validateRequest(catalogIngredientCreateSchema, req.body);
const ing = await catalogDB.createIngredient({
@@ -384,7 +412,8 @@ router.get('/ingredients/:id/revisions', asyncHandler(async (req, res) => {
router.post('/ingredients/:id/revisions/:revisionId/restore', asyncHandler(async (req, res) => {
const body = validateRequest(catalogRevisionRestoreSchema, req.body || {});
const revision = await catalogDB.getIngredientRevision(req.params.revisionId);
- if (!revision || revision.ingredientId !== req.params.id) {
+ const identityIds = await catalogDB.getIngredientIdentityIds(req.params.id);
+ if (!revision || !identityIds.includes(revision.ingredientId)) {
throw new ServerError('Revision not found', { status: 404 });
}
// Restore the revision's payload verbatim, INCLUDING its captured
diff --git a/server/routes/catalogSheets.test.js b/server/routes/catalogSheets.test.js
index 370b2ed5ac..4b9036ef6e 100644
--- a/server/routes/catalogSheets.test.js
+++ b/server/routes/catalogSheets.test.js
@@ -20,6 +20,7 @@ vi.mock('../lib/imageCleanDefaults.js', () => ({
}));
vi.mock('../services/catalogDB.js', () => ({
getIngredient: (...args) => mocks.getIngredient(...args),
+ getIngredientIdentityIds: async id => [id],
listLiveRefsForIngredient: (...args) => mocks.listLiveRefsForIngredient(...args),
}));
vi.mock('../services/universeBuilder.js', () => ({
diff --git a/server/scripts/init-db.sql b/server/scripts/init-db.sql
index b9ee75083a..3b915343f5 100644
--- a/server/scripts/init-db.sql
+++ b/server/scripts/init-db.sql
@@ -2448,3 +2448,36 @@ CREATE TABLE IF NOT EXISTS brain_memory_links (
bridge_key TEXT PRIMARY KEY,
memory_id UUID NOT NULL
);
+
+-- Local, recoverable catalog identity merges.
+CREATE TABLE IF NOT EXISTS catalog_ingredient_merges (
+ id TEXT PRIMARY KEY,
+ source_id TEXT NOT NULL REFERENCES catalog_ingredients(id),
+ survivor_id TEXT NOT NULL REFERENCES catalog_ingredients(id),
+ before_state JSONB NOT NULL,
+ after_fingerprint TEXT NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ restored_at TIMESTAMPTZ,
+ CHECK (source_id <> survivor_id)
+ );
+CREATE UNIQUE INDEX IF NOT EXISTS idx_catalog_merge_source_active
+ ON catalog_ingredient_merges (source_id) WHERE restored_at IS NULL;
+CREATE OR REPLACE FUNCTION catalog_resolve_ingredient_id(requested_id TEXT)
+ RETURNS TEXT LANGUAGE SQL STABLE AS $$
+ SELECT COALESCE((SELECT survivor_id FROM catalog_ingredient_merges
+ WHERE source_id = requested_id AND restored_at IS NULL), requested_id)
+ $$;
+CREATE OR REPLACE FUNCTION guard_catalog_merged_ingredient()
+ RETURNS TRIGGER LANGUAGE plpgsql AS $$
+ BEGIN
+ IF EXISTS (SELECT 1 FROM catalog_ingredient_merges WHERE restored_at IS NULL
+ AND (source_id = OLD.id OR (survivor_id = OLD.id AND
+ (TG_OP = 'DELETE' OR NEW.deleted = true)))) THEN
+ RAISE EXCEPTION 'Merged ingredient is protected; recover its merge first';
+ END IF;
+ IF TG_OP = 'DELETE' THEN RETURN OLD; END IF;
+ RETURN NEW;
+ END $$;
+DROP TRIGGER IF EXISTS trg_catalog_merged_ingredient ON catalog_ingredients;
+CREATE TRIGGER trg_catalog_merged_ingredient BEFORE UPDATE OR DELETE ON catalog_ingredients
+ FOR EACH ROW EXECUTE FUNCTION guard_catalog_merged_ingredient();
diff --git a/server/services/catalogCanonProjection.batch.test.js b/server/services/catalogCanonProjection.batch.test.js
index 7ca7a3dc88..7f7beaba88 100644
--- a/server/services/catalogCanonProjection.batch.test.js
+++ b/server/services/catalogCanonProjection.batch.test.js
@@ -61,7 +61,7 @@ describe('projectToCatalog batching', () => {
expect(catalogDB.getIngredient).not.toHaveBeenCalled();
expect(catalogDB.getIngredientTimestamps).toHaveBeenCalledTimes(1);
- expect(catalogDB.getIngredientTimestamps).toHaveBeenCalledWith(['ing-c1', 'ing-c2', 'ing-p1', 'ing-o1']);
+ expect(catalogDB.getIngredientTimestamps).toHaveBeenCalledWith(['ing-c1', 'ing-c2', 'ing-p1', 'ing-o1'], { excludeAliases: true });
expect(catalogDB.updateIngredient).toHaveBeenCalledTimes(4);
expect(stats).toEqual({ written: 4, skipped: 0 });
});
@@ -116,7 +116,7 @@ describe('projectToCatalog batching', () => {
characters: [entry('ing-guarded'), entry('ing-other')],
}, { guardToken: 'ing-guarded' });
- expect(catalogDB.getIngredientTimestamps).toHaveBeenCalledWith(['ing-other']);
+ expect(catalogDB.getIngredientTimestamps).toHaveBeenCalledWith(['ing-other'], { excludeAliases: true });
expect(stats).toEqual({ written: 1, skipped: 1 });
});
diff --git a/server/services/catalogCanonProjection.js b/server/services/catalogCanonProjection.js
index 7cfeb33b5b..8485174aca 100644
--- a/server/services/catalogCanonProjection.js
+++ b/server/services/catalogCanonProjection.js
@@ -89,9 +89,12 @@ export async function projectToCanon(ingredientId, updatedIngredient, deps = {})
const updateUniverse = deps.updateUniverse || (await import('./universeBuilder.js')).updateUniverse;
if (!ingredientId || !updatedIngredient) return { universes: 0, written: 0, skipped: 0 };
+ ingredientId = updatedIngredient.id || ingredientId;
+ const identityIds = new Set(await catalogDB.getIngredientIdentityIds(ingredientId));
+
// Guard the originating ingredient so the updateUniverse → projectToCatalog
// echo inside this call can't write the catalog row a second time.
- inFlight.add(ingredientId);
+ for (const id of identityIds) inFlight.add(id);
const stats = { universes: 0, written: 0, skipped: 0 };
try {
const refs = await catalogDB.listRefsForIngredient(ingredientId);
@@ -120,9 +123,9 @@ export async function projectToCanon(ingredientId, updatedIngredient, deps = {})
const patch = {};
for (const arrayKey of CANON_ARRAY_KEYS) {
const list = Array.isArray(cur[arrayKey]) ? cur[arrayKey] : [];
- if (!list.some((e) => e?.ingredientId === ingredientId)) continue;
+ if (!list.some((e) => identityIds.has(e?.ingredientId))) continue;
patch[arrayKey] = list.map((e) => {
- if (e?.ingredientId !== ingredientId) return e;
+ if (!identityIds.has(e?.ingredientId)) return e;
touched = true;
const controlFields = Object.fromEntries(
NON_PAYLOAD_KEYS.filter((key) => e[key] !== undefined).map((key) => [key, e[key]]),
@@ -140,7 +143,7 @@ export async function projectToCanon(ingredientId, updatedIngredient, deps = {})
}
return stats;
} finally {
- inFlight.delete(ingredientId);
+ for (const id of identityIds) inFlight.delete(id);
}
}
@@ -190,6 +193,9 @@ export async function projectToCatalog(universeId, canonArrays, { guardToken = n
// contract the per-entry catch below keeps.
const timestamps = await catalogDB.getIngredientTimestamps(
candidates.map((c) => c.ingredientId),
+ // A retained source cache is an archived contextual copy, not a fresh
+ // authoritative edit. Only a catalog projection may refresh its identity.
+ { excludeAliases: true },
).catch((err) => {
console.error(`🔁 projectToCatalog: batched lookup of ${candidates.length} ingredients failed: ${err.message}`);
return null;
diff --git a/server/services/catalogDB.exportSlice.test.js b/server/services/catalogDB.exportSlice.test.js
index 16254f077d..3ba697a129 100644
--- a/server/services/catalogDB.exportSlice.test.js
+++ b/server/services/catalogDB.exportSlice.test.js
@@ -78,8 +78,8 @@ vi.mock('../lib/db.js', () => ({
calls.push({ sql: flat, params });
if (flat.includes('FROM catalog_ingredients i')) return { rows: sliceIsEmpty.value ? [] : INGREDIENT_ROWS };
if (flat.includes('FROM catalog_scraps s')) return { rows: SCRAP_ROWS };
- if (flat.includes('FROM catalog_ingredient_refs')) return { rows: REF_ROWS };
- if (flat.includes('FROM catalog_ingredient_media')) return { rows: MEDIA_ROWS };
+ if ((flat.includes('FROM catalog_ingredient_refs') || flat.includes('JOIN catalog_ingredient_refs r ON r.ingredient_id = catalog_resolve_ingredient_id'))) return { rows: REF_ROWS };
+ if ((flat.includes('FROM catalog_ingredient_media') || flat.includes('JOIN catalog_ingredient_media m ON m.ingredient_id = catalog_resolve_ingredient_id'))) return { rows: MEDIA_ROWS };
return { rows: [] };
}),
withTransaction: vi.fn(),
@@ -102,7 +102,7 @@ describe('exportSliceForRef batching (#3940)', () => {
await catalogDB.exportSliceForRef('universe', 'uni-1');
expect(calls).toHaveLength(4);
// Three of them are the batched ANY($1) hydration queries.
- const batched = calls.filter((c) => c.sql.includes('= ANY($1)'));
+ const batched = calls.filter((c) => c.sql.includes('= ANY($1)') || c.sql.includes('unnest($1::text[])'));
expect(batched).toHaveLength(3);
for (const c of batched) expect(c.params[0]).toEqual(['i1', 'i2']);
});
diff --git a/server/services/catalogDB.ingredientTimestamps.test.js b/server/services/catalogDB.ingredientTimestamps.test.js
index b74c473c55..0d4577f338 100644
--- a/server/services/catalogDB.ingredientTimestamps.test.js
+++ b/server/services/catalogDB.ingredientTimestamps.test.js
@@ -42,7 +42,7 @@ describe('getIngredientTimestamps (#3941)', () => {
expect(calls).toHaveLength(1);
expect(calls[0].sql).toBe(
- 'SELECT id, updated_at FROM catalog_ingredients WHERE id = ANY($1) AND deleted = false',
+ 'SELECT requested.id, i.updated_at FROM unnest($1::text[]) AS requested(id) JOIN catalog_ingredients i ON i.id = catalog_resolve_ingredient_id(requested.id) AND i.deleted = false',
);
expect(calls[0].params).toEqual([['ing-1', 'ing-2']]);
expect(map.get('ing-1')).toBe('2026-02-01T00:00:00.000Z');
diff --git a/server/services/catalogDB.merge.db.test.js b/server/services/catalogDB.merge.db.test.js
new file mode 100644
index 0000000000..7ac8ef5fa3
--- /dev/null
+++ b/server/services/catalogDB.merge.db.test.js
@@ -0,0 +1,230 @@
+import { randomUUID } from 'node:crypto';
+import { afterAll, describe, expect, it, vi } from 'vitest';
+import { checkHealth, ensureSchema, query, close } from '../lib/db.js';
+import { requireDbOrSkip } from '../lib/dbTestGate.js';
+import { mergeIngredients, recoverIngredientMerge, getIngredientMergeHistory, getIngredientMergeReceipt } from './catalogDB/merge.js';
+import { getIngredient, getIngredientTimestamps, listIngredients, resolveIngredientsByIds, listIngredientRevisions, updateIngredient } from './catalogDB/ingredients.js';
+import { attachMedia, listMediaForIngredient } from './catalogDB/media.js';
+import { linkIngredientRelation, listRelationsForIngredient, listRefsForIngredient, listSourcesForIngredient } from './catalogDB/refs.js';
+import { exportSliceForRef, getCatalogStats } from './catalogDB/facets.js';
+import { projectToCanon, projectToCatalog } from './catalogCanonProjection.js';
+import { upsertIngredientFromPeer } from './catalogDB/sync.js';
+
+vi.mock('./instanceIdentity.js', () => ({ getInstanceId: async () => 'example-local-instance', UNKNOWN_INSTANCE_ID: 'unknown' }));
+const health = await checkHealth().catch(error => ({ connected: false, error: error.message }));
+const ready = requireDbOrSkip('catalog local merge', health.connected, health.error);
+if (ready) await ensureSchema();
+const ids = [];
+const scraps = [];
+async function pair() {
+ const sourceId = `merge-test-${randomUUID()}`;
+ const survivorId = `merge-test-${randomUUID()}`;
+ ids.push(sourceId, survivorId);
+ for (const [id, name, payload] of [
+ [sourceId, 'Example Pilot', { locked: false, description: 'Original biography', imageRefs: ['original.png'] }],
+ [survivorId, 'Example Pilot (Cast)', { locked: false, description: 'Performance notes', imageRefs: ['cast.png'] }],
+ ]) {
+ await query(`INSERT INTO catalog_ingredients (id, type, name, payload, origin_instance_id)
+ VALUES ($1, 'character', $2, $3::jsonb, 'example-local-instance')`, [id, name, JSON.stringify(payload)]);
+ await query(`INSERT INTO catalog_ingredient_revisions (id, ingredient_id, name, payload)
+ VALUES ($1, $2, $3, $4::jsonb)`, [`rev-${randomUUID()}`, id, name, JSON.stringify(payload)]);
+ }
+ return { sourceId, survivorId, fieldChoices: { '/name': 'survivor', '/payload/description': 'source' } };
+}
+async function apply(input) {
+ const preview = await mergeIngredients(input);
+ return mergeIngredients({ ...input, dryRun: false, previewToken: preview.previewToken });
+}
+afterAll(async () => {
+ if (!ready) return;
+ await query('DELETE FROM catalog_ingredient_merges WHERE source_id = ANY($1)', [ids]);
+ await query('DELETE FROM catalog_ingredient_refs WHERE ingredient_id = ANY($1)', [ids]);
+ await query('DELETE FROM catalog_ingredients WHERE id = ANY($1)', [ids]);
+ await query('DELETE FROM catalog_scraps WHERE id = ANY($1)', [scraps]);
+ await close();
+});
+
+describe.skipIf(!ready)('recoverable local catalog merge', () => {
+ it('preserves identities, history, assets and provenance through source-ID lookups and background attachments', async () => {
+ const input = await pair();
+ const { sourceId, survivorId } = input;
+ await attachMedia(sourceId, 'source-sheet.png', 'reference', { role: 'sheet:standard', metadata: { prompt: 'Example sheet prompt' } });
+ await attachMedia(survivorId, 'cast-portrait.png', 'portrait');
+ await query(`INSERT INTO catalog_ingredient_refs (ingredient_id, ref_kind, ref_id, role)
+ VALUES ($1, 'music-video', 'example-video', 'cast')`, [sourceId]);
+ const scrapId = `scrap-${randomUUID()}`;
+ scraps.push(scrapId);
+ await query("INSERT INTO catalog_scraps (id, title, raw_text, source_kind) VALUES ($1, 'Example notes', 'Example source', 'text')", [scrapId]);
+ await query('INSERT INTO catalog_ingredient_sources (ingredient_id, scrap_id, span) VALUES ($1, $2, $3::jsonb)', [sourceId, scrapId, JSON.stringify({ start: 1, end: 5 })]);
+ const { rows: [sourceBefore] } = await query('SELECT * FROM catalog_ingredients WHERE id = $1', [sourceId]);
+ const statsBefore = await getCatalogStats();
+ const result = await apply(input);
+ const statsAfter = await getCatalogStats();
+ expect(Number(statsAfter.byType.character)).toBe(Number(statsBefore.byType.character) - 1);
+ const exported = await exportSliceForRef('music-video', 'example-video');
+ expect(exported.ingredients.map(row => row.id)).toEqual(expect.arrayContaining([sourceId, survivorId]));
+ expect(exported.ingredients.find(row => row.id === sourceId).media.map(row => row.mediaKey)).toEqual(['source-sheet.png']);
+ expect(result.scope).toBe('local');
+ await expect(linkIngredientRelation(sourceId, survivorId, 'related-to')).rejects.toThrow('identity to itself');
+ expect((await getIngredient(sourceId)).id).toBe(survivorId);
+ expect((await getIngredient(sourceId)).payload.imageRefs).toEqual(['cast.png', 'original.png']);
+ expect((await resolveIngredientsByIds([sourceId, survivorId])).map(row => row.id)).toEqual([survivorId]);
+ const timestamps = await getIngredientTimestamps([sourceId, survivorId]);
+ expect(timestamps.get(sourceId)).toBe(timestamps.get(survivorId));
+ expect((await listIngredients({ ids: [sourceId, survivorId] })).items.map(row => row.id)).toEqual([survivorId]);
+ expect((await listRefsForIngredient(sourceId)).map(row => row.refId)).toContain('example-video');
+ expect((await listSourcesForIngredient(survivorId)).map(row => row.ingredientId)).toContain(sourceId);
+ expect((await listMediaForIngredient(sourceId)).map(row => row.mediaKey)).toEqual(expect.arrayContaining(['source-sheet.png', 'cast-portrait.png']));
+ const revisions = await listIngredientRevisions(survivorId);
+ expect(new Set(revisions.items.map(row => row.ingredientId))).toEqual(new Set([sourceId, survivorId]));
+ const historyPage = await getIngredientMergeHistory(survivorId);
+ expect(historyPage.nextOffset).toBeNull();
+ expect(historyPage.items[0]).not.toHaveProperty('beforeState');
+ const history = [await getIngredientMergeReceipt(historyPage.items[0].id)];
+ expect(history[0].beforeState.media.find(row => row.media_key === 'source-sheet.png').metadata.prompt).toBe('Example sheet prompt');
+ expect(history[0].beforeState.revisions).toHaveLength(2);
+ expect(history[0].beforeState.decision.fieldChoices).toEqual(input.fieldChoices);
+ // Source stays byte-identical and live for peers that do not know local aliases.
+ expect((await query('SELECT * FROM catalog_ingredients WHERE id = $1', [sourceId])).rows[0]).toEqual(sourceBefore);
+ await expect(query('UPDATE catalog_ingredients SET deleted = true WHERE id = $1', [sourceId])).rejects.toThrow('protected');
+ expect(await upsertIngredientFromPeer({ ...await getIngredient(sourceId), id: sourceId, updatedAt: new Date(Date.now() + 10000).toISOString() })).toEqual({ applied: false, isInsert: false });
+ await attachMedia(sourceId, 'late-job.png', 'reference');
+ expect((await listMediaForIngredient(survivorId)).map(row => row.mediaKey)).toContain('late-job.png');
+ await expect(recoverIngredientMerge(result.id)).rejects.toMatchObject({ code: 'CATALOG_MERGE_STALE' });
+ });
+
+ it('previews conflicts without writes and rejects ownership, locks, stale previews and alias chains', async () => {
+ const input = await pair();
+ const unresolved = await mergeIngredients({ sourceId: input.sourceId, survivorId: input.survivorId });
+ expect(unresolved.conflicts.map(row => row.path)).toEqual(expect.arrayContaining(['/name', '/payload/description']));
+ await expect(mergeIngredients({ ...input, fieldChoices: {}, dryRun: false, previewToken: unresolved.previewToken })).rejects.toMatchObject({ code: 'CATALOG_MERGE_CONFLICT' });
+ const preview = await mergeIngredients(input);
+ await attachMedia(input.sourceId, 'new-reference.png', 'reference');
+ await expect(mergeIngredients({ ...input, dryRun: false, previewToken: preview.previewToken })).rejects.toMatchObject({ code: 'CATALOG_MERGE_STALE' });
+ await query("UPDATE catalog_ingredients SET payload = payload || '{\"locked\":true}'::jsonb WHERE id = $1", [input.sourceId]);
+ await expect(mergeIngredients(input)).rejects.toMatchObject({ code: 'CATALOG_INGREDIENT_LOCKED' });
+ await query("UPDATE catalog_ingredients SET payload = payload || '{\"locked\":false}'::jsonb, origin_instance_id = 'example-peer' WHERE id = $1", [input.sourceId]);
+ await expect(mergeIngredients(input)).rejects.toMatchObject({ code: 'CATALOG_MERGE_FOREIGN' });
+ await query("UPDATE catalog_ingredients SET origin_instance_id = 'example-local-instance' WHERE id = $1", [input.sourceId]);
+ await apply(input);
+ const another = await pair();
+ await expect(mergeIngredients({ ...another, sourceId: input.survivorId })).rejects.toThrow('existing merge');
+ });
+
+ it('recovers an untouched merge without dropping audit history and leaves synchronized link tombstones', async () => {
+ const input = await pair();
+ await attachMedia(input.sourceId, 'recover-sheet.png', 'reference', { caption: 'Original caption' });
+ const result = await apply(input);
+ expect(await recoverIngredientMerge(result.id)).toEqual({ id: result.id, restored: true });
+ expect(await recoverIngredientMerge(result.id)).toEqual({ id: result.id, restored: true });
+ expect((await getIngredient(input.sourceId)).id).toBe(input.sourceId);
+ expect((await getIngredient(input.survivorId)).payload.description).toBe('Performance notes');
+ expect((await listMediaForIngredient(input.sourceId)).map(row => row.mediaKey)).toContain('recover-sheet.png');
+ expect(await listMediaForIngredient(input.survivorId)).toEqual([]);
+ expect((await query('SELECT deleted FROM catalog_ingredient_media WHERE ingredient_id = $1', [input.survivorId])).rows.every(row => row.deleted)).toBe(true);
+ expect((await listIngredientRevisions(input.survivorId)).items.map(row => row.actor)).toContain('catalog-merge-recovery');
+ expect((await getIngredientMergeHistory(input.sourceId)).items[0].restoredAt).not.toBeNull();
+ });
+
+ it('revives collided relationships and keeps both portraits visible', async () => {
+ const input = await pair();
+ const other = await pair();
+ await attachMedia(input.sourceId, 'old-portrait.png', 'reference', { caption: 'Existing reference metadata' });
+ await attachMedia(input.sourceId, 'old-portrait.png', 'portrait');
+ await attachMedia(input.survivorId, 'kept-portrait.png', 'portrait');
+ await query(`INSERT INTO catalog_ingredient_relations (from_id, to_id, kind, deleted)
+ VALUES ($1, $3, 'related-to', false), ($2, $3, 'related-to', true)`, [input.sourceId, input.survivorId, other.sourceId]);
+ await apply(input);
+ const media = await listMediaForIngredient(input.survivorId);
+ expect(media.filter(row => row.kind === 'portrait').map(row => row.mediaKey)).toEqual(['kept-portrait.png']);
+ expect(media.filter(row => row.mediaKey === 'old-portrait.png')).toHaveLength(1);
+ expect(media.find(row => row.mediaKey === 'old-portrait.png')).toMatchObject({ kind: 'reference', caption: 'Existing reference metadata' });
+ expect((await listRelationsForIngredient(input.sourceId)).outbound.map(row => row.other.id)).toContain(other.sourceId);
+ });
+
+ it('requires a choice for conflicting objects sharing a stable array ID', async () => {
+ const input = await pair();
+ for (const [id, description] of [[input.sourceId, 'Heavy coat'], [input.survivorId, 'Light jacket']]) {
+ await query("UPDATE catalog_ingredients SET payload = payload || $2::jsonb WHERE id = $1", [id,
+ JSON.stringify({ wardrobes: [{ id: 'example-costume', name: 'Travel', description }] })]);
+ }
+ const preview = await mergeIngredients(input);
+ expect(preview.conflicts.map(row => row.path)).toContain('/payload/wardrobes/0/description');
+ input.fieldChoices['/payload/wardrobes/0/description'] = 'source';
+ await apply(input);
+ expect((await getIngredient(input.survivorId)).payload.wardrobes).toEqual([{ id: 'example-costume', name: 'Travel', description: 'Heavy coat' }]);
+ });
+
+ it('guards archived canon snapshots and lets an explicit catalog edit refresh alias-backed canon', async () => {
+ const input = await pair();
+ await query(`INSERT INTO catalog_ingredient_refs (ingredient_id, ref_kind, ref_id, role)
+ VALUES ($1, 'universe', 'example-universe', 'canon-character')`, [input.sourceId]);
+ await apply(input);
+ const oldEntry = { id: 'example-entry', ingredientId: input.sourceId, name: 'Old context',
+ description: 'Must not replace merged payload', updatedAt: new Date(Date.now() + 10000).toISOString() };
+ expect(await projectToCatalog('example-universe', { characters: [oldEntry] })).toEqual({ written: 0, skipped: 1 });
+ expect((await getIngredient(input.survivorId)).payload.description).toBe('Original biography');
+ const updated = await getIngredient(input.sourceId);
+ let projected;
+ const stats = await projectToCanon(input.sourceId, updated, { updateUniverse: async (_id, mutate) => {
+ projected = mutate({ characters: [oldEntry] });
+ // The synchronous echo cannot race the source alias against the survivor.
+ expect(await projectToCatalog('example-universe', projected)).toEqual({ written: 0, skipped: 1 });
+ return projected;
+ } });
+ expect(stats.written).toBe(1);
+ expect(projected.characters[0]).toMatchObject({ ingredientId: input.survivorId, name: updated.name, description: 'Original biography' });
+ });
+
+ it('admits only one overlapping apply of the same reviewed preview', async () => {
+ const input = await pair();
+ const preview = await mergeIngredients(input);
+ const request = { ...input, dryRun: false, previewToken: preview.previewToken };
+ const results = await Promise.allSettled([mergeIngredients(request), mergeIngredients(request)]);
+ expect(results.filter(result => result.status === 'fulfilled')).toHaveLength(1);
+ expect(results.find(result => result.status === 'rejected').reason.status).toBe(409);
+ expect((await getIngredientMergeHistory(input.sourceId)).items).toHaveLength(1);
+ });
+
+ it('keeps both files viewable when canonical primary and sheet pointers conflict', async () => {
+ const input = await pair();
+ for (const [id, key] of [[input.sourceId, 'source'], [input.survivorId, 'survivor']]) {
+ await query('UPDATE catalog_ingredients SET payload = payload || $2::jsonb WHERE id = $1', [id,
+ JSON.stringify({ primaryImageRef: `${key}-primary.png`, referenceSheetImageRef: `${key}-standard.png`,
+ referenceSheets: { blueprint: `${key}-blueprint.png` } })]);
+ }
+ Object.assign(input.fieldChoices, { '/payload/primaryImageRef': 'survivor',
+ '/payload/referenceSheetImageRef': 'survivor', '/payload/referenceSheets/blueprint': 'survivor' });
+ await apply(input);
+ const media = await listMediaForIngredient(input.survivorId);
+ expect(media.map(row => row.mediaKey)).toEqual(expect.arrayContaining([
+ 'source-primary.png', 'survivor-primary.png', 'source-standard.png', 'survivor-standard.png',
+ 'source-blueprint.png', 'survivor-blueprint.png',
+ ]));
+ expect((await listIngredients({ ids: [input.survivorId] })).items[0].thumbnailKey).toBeNull();
+ expect(media.filter(row => row.role === 'sheet:blueprint').map(row => row.mediaKey)).toEqual(expect.arrayContaining(['source-blueprint.png', 'survivor-blueprint.png']));
+ expect((await getIngredient(input.survivorId)).payload.referenceSheets.blueprint).toBe('survivor-blueprint.png');
+ });
+
+ it('pages summary history and loads archived snapshots only by receipt', async () => {
+ const input = await pair();
+ const first = await apply(input);
+ await recoverIngredientMerge(first.id);
+ const second = await apply(input);
+ const page = await getIngredientMergeHistory(input.survivorId, { limit: 1 });
+ expect(page.items.map(row => row.id)).toEqual([second.id]);
+ expect(page.nextOffset).toBe(1);
+ expect(page.items[0]).not.toHaveProperty('beforeState');
+ const next = await getIngredientMergeHistory(input.survivorId, { limit: 1, offset: page.nextOffset });
+ expect(next.items.map(row => row.id)).toEqual([first.id]);
+ expect(next.nextOffset).toBeNull();
+ expect((await getIngredientMergeReceipt(first.id)).beforeState.ingredients.map(row => row.id)).toContain(input.sourceId);
+ });
+
+ it('refuses recovery after a new lock or canonical edit', async () => {
+ const input = await pair();
+ const result = await apply(input);
+ await updateIngredient(input.survivorId, { payload: { ...(await getIngredient(input.survivorId)).payload, locked: true } });
+ await expect(recoverIngredientMerge(result.id)).rejects.toMatchObject({ code: 'CATALOG_INGREDIENT_LOCKED' });
+ });
+});
diff --git a/server/services/catalogDB/facets.js b/server/services/catalogDB/facets.js
index 7fe72674a9..fdf4825d97 100644
--- a/server/services/catalogDB/facets.js
+++ b/server/services/catalogDB/facets.js
@@ -61,15 +61,15 @@ export async function listScrapsForIngredients(ingredientIds) {
* (see `[catalog-ingredient-relations]`); when they land, extend this helper.
*/
export async function exportSliceForRef(refKind, refId) {
- const rows = await listIngredientsForRef(refKind, refId);
+ const rows = await listIngredientsForRef(refKind, refId, { preserveIdentity: true });
// Hydrate scraps + refs + media for the WHOLE slice in three batched queries
// (#3940) — a per-ingredient round-trip made this 3N queries, which pinned the
// connection pool on a large universe. Four queries total, regardless of N.
const ingredientIds = rows.map(({ ingredient }) => ingredient.id);
const [scrapsById, refsById, mediaById] = await Promise.all([
listScrapsForIngredients(ingredientIds),
- listRefsForIngredients(ingredientIds),
- listMediaForIngredients(ingredientIds),
+ listRefsForIngredients(ingredientIds, { preserveIdentity: true }),
+ listMediaForIngredients(ingredientIds, { preserveIdentity: true }),
]);
const ingredients = rows.map(({ ingredient, role }) => {
const { embedding: _embedding, ...rest } = ingredient;
@@ -134,11 +134,11 @@ export async function getCatalogBundleForRef(refKind, refId) {
export async function getCatalogStats() {
const [byTypeResult, scrapResult, withEmb] = await Promise.all([
- query(`SELECT type, COUNT(*) AS count FROM catalog_ingredients WHERE deleted = false GROUP BY type`),
+ query(`SELECT type, COUNT(*) AS count FROM catalog_ingredients WHERE deleted = false AND id = catalog_resolve_ingredient_id(id) GROUP BY type`),
// Count only parent/standalone scraps — child chunk rows are an internal
// extraction detail and would inflate the user-facing scrap count.
query(`SELECT COUNT(*) AS count FROM catalog_scraps WHERE deleted = false AND parent_scrap_id IS NULL`),
- query(`SELECT COUNT(*) AS count FROM catalog_ingredients WHERE deleted = false AND embedding IS NOT NULL`),
+ query(`SELECT COUNT(*) AS count FROM catalog_ingredients WHERE deleted = false AND id = catalog_resolve_ingredient_id(id) AND embedding IS NOT NULL`),
]);
const byType = {};
let total = 0;
@@ -164,7 +164,7 @@ export async function getCatalogStats() {
export async function getCatalogFacets() {
const [typeRows, uniRows, serRows, tagRows, bucketRows] = await Promise.all([
query(`SELECT type, COUNT(*)::int AS count
- FROM catalog_ingredients WHERE deleted = false
+ FROM catalog_ingredients WHERE deleted = false AND id = catalog_resolve_ingredient_id(id)
GROUP BY type ORDER BY count DESC, type`),
// Universe membership rolls up its series' members (decision #1), so the
// album header count matches what the universe album/filter actually lists:
@@ -175,17 +175,17 @@ export async function getCatalogFacets() {
(r.ref_kind = 'universe' AND r.ref_id = u.id)
OR (r.ref_kind = 'series' AND r.ref_id IN (
SELECT s.id FROM pipeline_series s WHERE s.universe_id = u.id AND s.deleted = false)))
- JOIN catalog_ingredients i ON i.id = r.ingredient_id AND i.deleted = false
+ JOIN catalog_ingredients i ON i.id = r.ingredient_id AND i.deleted = false AND i.id = catalog_resolve_ingredient_id(i.id)
WHERE u.deleted = false
GROUP BY u.id, u.name ORDER BY count DESC, u.name`),
query(`SELECT s.id AS ref_id, s.name, s.universe_id, COUNT(DISTINCT r.ingredient_id)::int AS count
FROM catalog_ingredient_refs r
- JOIN catalog_ingredients i ON i.id = r.ingredient_id AND i.deleted = false
+ JOIN catalog_ingredients i ON i.id = r.ingredient_id AND i.deleted = false AND i.id = catalog_resolve_ingredient_id(i.id)
JOIN pipeline_series s ON s.id = r.ref_id AND s.deleted = false
WHERE r.deleted = false AND r.ref_kind = 'series'
GROUP BY s.id, s.name, s.universe_id ORDER BY count DESC, s.name`),
query(`SELECT tag, COUNT(*)::int AS count
- FROM (SELECT unnest(tags) AS tag FROM catalog_ingredients WHERE deleted = false) t
+ FROM (SELECT unnest(tags) AS tag FROM catalog_ingredients WHERE deleted = false AND id = catalog_resolve_ingredient_id(id)) t
GROUP BY tag ORDER BY count DESC, tag`),
// Per-ingredient bucket classification. ref_count = live homing ref ROWS
// (universe/series/creative-director); live_count = those whose target still
@@ -204,7 +204,7 @@ export async function getCatalogFacets() {
FROM catalog_ingredients i
LEFT JOIN catalog_ingredient_refs r
ON r.ingredient_id = i.id AND r.deleted = false AND r.ref_kind IN (${HOMING_REF_KINDS_SQL})
- WHERE i.deleted = false
+ WHERE i.deleted = false AND i.id = catalog_resolve_ingredient_id(i.id)
GROUP BY i.id
) sub`),
]);
diff --git a/server/services/catalogDB/ingredients.js b/server/services/catalogDB/ingredients.js
index eb02e884ce..695ccd3f7c 100644
--- a/server/services/catalogDB/ingredients.js
+++ b/server/services/catalogDB/ingredients.js
@@ -99,12 +99,21 @@ export async function createIngredient({ id: explicitId, type, name, payload = {
export async function getIngredient(id, { client } = {}) {
const exec = client ? client.query.bind(client) : query;
const result = await exec(
- `SELECT * FROM catalog_ingredients WHERE id = $1 AND deleted = false`,
+ `SELECT * FROM catalog_ingredients WHERE id = catalog_resolve_ingredient_id($1) AND deleted = false`,
[id],
);
return rowToIngredient(result.rows[0]);
}
+// All stable IDs belonging to a local consolidated identity. The source row
+// stays live for peers; callers can match embedded IDs without rewriting canon.
+export async function getIngredientIdentityIds(id) {
+ const { rows } = await query(`SELECT catalog_resolve_ingredient_id($1) AS id
+ UNION SELECT source_id AS id FROM catalog_ingredient_merges
+ WHERE survivor_id = catalog_resolve_ingredient_id($1) AND restored_at IS NULL`, [id]);
+ return rows.map(row => row.id);
+}
+
/**
* Batched freshness lookup for LWW comparisons (#3941) — ONE query for N ids
* instead of N `getIngredient` round-trips. Returns
@@ -113,11 +122,12 @@ export async function getIngredient(id, { client } = {}) {
* and happens to be stale. Selects two columns, not `*`: the canon→catalog
* projection needs existence + freshness, never the jsonb payload.
*/
-export async function getIngredientTimestamps(ingredientIds) {
+export async function getIngredientTimestamps(ingredientIds, { excludeAliases = false } = {}) {
const ids = [...new Set((ingredientIds || []).filter(Boolean))];
if (ids.length === 0) return new Map();
const result = await query(
- `SELECT id, updated_at FROM catalog_ingredients WHERE id = ANY($1) AND deleted = false`,
+ `SELECT requested.id, i.updated_at FROM unnest($1::text[]) AS requested(id)
+ JOIN catalog_ingredients i ON i.id = catalog_resolve_ingredient_id(requested.id) AND i.deleted = false${excludeAliases ? ' AND requested.id = i.id' : ''}`,
[ids],
);
return new Map(result.rows.map((row) => [row.id, row.updated_at.toISOString()]));
@@ -190,7 +200,7 @@ export async function updateIngredient(id, patch = {}, { client, source = 'user'
// route 404s. Revival of soft-deleted rows is intentionally separate via
// `reviveDeletedIngredient`, so this filter doesn't conflict with that path.
const result = await exec(
- `UPDATE catalog_ingredients SET ${fields.join(', ')} WHERE id = $${idx} AND deleted = false RETURNING *`,
+ `UPDATE catalog_ingredients SET ${fields.join(', ')} WHERE id = catalog_resolve_ingredient_id($${idx}) AND deleted = false RETURNING *`,
params,
);
const updated = rowToIngredient(result.rows[0]);
@@ -249,7 +259,8 @@ export async function recordIngredientRevision(ingredient, { source = 'user', ac
export async function listIngredientRevisions(ingredientId, { limit = 50, offset = 0 } = {}) {
const result = await query(
`SELECT * FROM catalog_ingredient_revisions
- WHERE ingredient_id = $1
+ WHERE (ingredient_id = catalog_resolve_ingredient_id($1) OR ingredient_id IN
+ (SELECT source_id FROM catalog_ingredient_merges WHERE survivor_id = catalog_resolve_ingredient_id($1) AND restored_at IS NULL))
ORDER BY created_at DESC, id DESC
LIMIT $2 OFFSET $3`,
[ingredientId, Math.min(Math.max(limit, 1), 200), Math.max(offset, 0)],
@@ -323,7 +334,7 @@ const THUMBNAIL_KEY_SUBQUERY = `(
WHERE m.ingredient_id = catalog_ingredients.id
AND m.deleted = false
AND m.kind IN ('portrait', 'reference')
- AND (m.role IS NULL OR NOT (m.role LIKE 'sheet:%' OR m.role LIKE 'look:%' OR m.role = 'plate'))
+ AND (m.role IS NULL OR NOT (m.role LIKE 'sheet:%' OR m.role LIKE 'look:%' OR m.role LIKE 'archive:%' OR m.role = 'plate'))
ORDER BY (m.kind = 'portrait') DESC, m.created_at DESC
LIMIT 1
) AS thumbnail_key`;
@@ -341,7 +352,7 @@ const REF_USAGE_SUBQUERY = `(
) AS ref_usage`;
export async function listIngredients({ ids, type, tag, query: q, refKind = null, refId = null, unlinked = false, orphaned = false, scrapId = null, limit = 50, offset = 0, includeEmbedding = false, embeddingMissing = false, staleEmbeddingModel = null } = {}) {
- const conditions = ['deleted = false'];
+ const conditions = ['deleted = false', 'id = catalog_resolve_ingredient_id(id)'];
const params = [];
let idx = 1;
// Batch-fetch by id (Story Builder catalog→series linking, #1761). When
@@ -350,7 +361,7 @@ export async function listIngredients({ ids, type, tag, query: q, refKind = null
const byIds = Array.isArray(ids) && ids.length > 0;
let qIdx = null;
if (byIds) {
- conditions.push(`id = ANY($${idx++})`);
+ conditions.push(`id IN (SELECT catalog_resolve_ingredient_id(requested) FROM unnest($${idx++}::text[]) requested)`);
params.push(ids);
} else {
if (type) {
@@ -403,7 +414,7 @@ export async function listIngredients({ ids, type, tag, query: q, refKind = null
// are mutually exclusive album views enforced at the schema level).
if (scrapId) {
conditions.push(`EXISTS (SELECT 1 FROM catalog_ingredient_sources cis
- WHERE cis.ingredient_id = catalog_ingredients.id AND cis.scrap_id = $${idx++})`);
+ WHERE catalog_resolve_ingredient_id(cis.ingredient_id) = catalog_ingredients.id AND cis.scrap_id = $${idx++})`);
params.push(scrapId);
}
if (embeddingMissing) {
@@ -448,7 +459,7 @@ export async function listIngredients({ ids, type, tag, query: q, refKind = null
*/
export async function searchIngredientsByEmbedding(vector, { type, limit = 20, threshold = 0.5 } = {}) {
if (!vector) return [];
- const conditions = ['deleted = false', 'embedding IS NOT NULL'];
+ const conditions = ['deleted = false', 'id = catalog_resolve_ingredient_id(id)', 'embedding IS NOT NULL'];
const params = [arrayToPgvector(vector), threshold, limit];
let idx = 4;
if (type) {
@@ -477,7 +488,7 @@ export async function findIngredientsByName(type, names) {
if (!type || !keys.length) return [];
const result = await query(
`SELECT * FROM catalog_ingredients
- WHERE deleted = false AND type = $1
+ WHERE deleted = false AND id = catalog_resolve_ingredient_id(id) AND type = $1
AND (lower(btrim(name)) = ANY($2)
OR (jsonb_typeof(payload->'aliases') = 'array'
AND EXISTS (SELECT 1 FROM jsonb_array_elements_text(payload->'aliases') a WHERE lower(btrim(a)) = ANY($2))))
@@ -489,7 +500,7 @@ export async function findIngredientsByName(type, names) {
export async function searchIngredientsByText(q, { type, limit = 20 } = {}) {
if (!q) return [];
- const conditions = ['deleted = false', `search_tsv @@ websearch_to_tsquery('english', $1)`];
+ const conditions = ['deleted = false', 'id = catalog_resolve_ingredient_id(id)', `search_tsv @@ websearch_to_tsquery('english', $1)`];
const params = [q, limit];
let idx = 3;
if (type) {
@@ -520,7 +531,7 @@ export async function hybridSearchIngredients(queryText, queryEmbedding, options
let ftsRows = [];
if (queryText) {
- const conds = ['deleted = false', `search_tsv @@ websearch_to_tsquery('english', $1)`];
+ const conds = ['deleted = false', 'id = catalog_resolve_ingredient_id(id)', `search_tsv @@ websearch_to_tsquery('english', $1)`];
const params = [queryText, fetchLimit];
let idx = 3;
if (type) { conds.push(`type = $${idx++}`); params.push(type); }
@@ -535,7 +546,7 @@ export async function hybridSearchIngredients(queryText, queryEmbedding, options
let vecRows = [];
if (queryEmbedding) {
- const conds = ['deleted = false', 'embedding IS NOT NULL', '1 - (embedding <=> $1) >= $2'];
+ const conds = ['deleted = false', 'id = catalog_resolve_ingredient_id(id)', 'embedding IS NOT NULL', '1 - (embedding <=> $1) >= $2'];
const params = [arrayToPgvector(queryEmbedding), minRelevance * 0.5, fetchLimit];
let idx = 4;
if (type) { conds.push(`type = $${idx++}`); params.push(type); }
@@ -573,7 +584,8 @@ export async function resolveIngredientsByIds(ids) {
.filter((id) => typeof id === 'string' && id.trim())
.map((id) => id.trim()))];
if (list.length === 0) return [];
- const { items } = await listIngredients({ ids: list, limit: list.length });
- const byId = new Map(items.map((ing) => [ing.id, ing]));
- return list.map((id) => byId.get(id)).filter(Boolean);
+ const { rows } = await query(`SELECT i.*, requested.ordinality FROM unnest($1::text[]) WITH ORDINALITY requested(id, ordinality)
+ JOIN catalog_ingredients i ON i.id = catalog_resolve_ingredient_id(requested.id) AND i.deleted = false
+ ORDER BY requested.ordinality`, [list]);
+ return [...new Map(rows.map(row => [row.id, rowToIngredient(row)])).values()];
}
diff --git a/server/services/catalogDB/media.js b/server/services/catalogDB/media.js
index 06328c0e5e..20653caf0a 100644
--- a/server/services/catalogDB/media.js
+++ b/server/services/catalogDB/media.js
@@ -34,7 +34,7 @@ async function insertMedia(runQuery, ingredientId, mediaKey, kind, options) {
const metadataUpdate = hasMetadata ? ', metadata = EXCLUDED.metadata' : '';
const result = await runQuery(
`INSERT INTO catalog_ingredient_media (ingredient_id, media_key, kind, role, caption${metadataColumn})
- VALUES ($1, $2, $3, $4, $5${metadataPlaceholder})
+ VALUES (catalog_resolve_ingredient_id($1), $2, $3, $4, $5${metadataPlaceholder})
ON CONFLICT (ingredient_id, media_key, kind) DO UPDATE
SET deleted = false, deleted_at = NULL,
role = EXCLUDED.role, caption = EXCLUDED.caption${metadataUpdate}
@@ -54,7 +54,7 @@ export async function detachMedia(ingredientId, mediaKey, kind) {
await query(
`UPDATE catalog_ingredient_media
SET deleted = true, deleted_at = NOW()
- WHERE ingredient_id = $1 AND media_key = $2 AND kind = $3
+ WHERE ingredient_id = catalog_resolve_ingredient_id($1) AND media_key = $2 AND kind = $3
AND deleted = false`,
[ingredientId, mediaKey, kind],
);
@@ -65,11 +65,11 @@ export async function detachMedia(ingredientId, mediaKey, kind) {
// and a failed replacement leaves the previous portrait intact.
export async function setPortraitMedia(ingredientId, mediaKey, options = {}) {
const replace = async (client) => {
- await client.query('SELECT id FROM catalog_ingredients WHERE id = $1 FOR UPDATE', [ingredientId]);
+ await client.query('SELECT id FROM catalog_ingredients WHERE id = catalog_resolve_ingredient_id($1) FOR UPDATE', [ingredientId]);
await client.query(
`UPDATE catalog_ingredient_media
SET deleted = true, deleted_at = NOW()
- WHERE ingredient_id = $1 AND kind = 'portrait'
+ WHERE ingredient_id = catalog_resolve_ingredient_id($1) AND kind = 'portrait'
AND media_key <> $2 AND deleted = false`,
[ingredientId, mediaKey],
);
@@ -90,16 +90,19 @@ export async function listMediaForIngredient(ingredientId) {
// ordering (portraits first, then newest-first); the outer `ingredient_id` sort
// key only groups the rows, it doesn't reorder within a group. Returns
// `Map<ingredientId, media[]>` with an entry (possibly `[]`) for every id.
-export async function listMediaForIngredients(ingredientIds) {
+export async function listMediaForIngredients(ingredientIds, { preserveIdentity = false } = {}) {
const ids = [...new Set(ingredientIds)];
if (ids.length === 0) return new Map();
const result = await query(
- `SELECT * FROM catalog_ingredient_media
+ preserveIdentity ? `SELECT * FROM catalog_ingredient_media
WHERE ingredient_id = ANY($1) AND deleted = false
+ ORDER BY ingredient_id, (kind = 'portrait') DESC, created_at DESC` : `SELECT m.*, requested.id AS requested_id FROM unnest($1::text[]) requested(id)
+ JOIN catalog_ingredient_media m ON m.ingredient_id = catalog_resolve_ingredient_id(requested.id)
+ WHERE m.deleted = false
ORDER BY ingredient_id, (kind = 'portrait') DESC, created_at DESC`,
[ids],
);
- return groupRowsByIngredient(ids, result.rows, rowToMedia);
+ return groupRowsByIngredient(ids, result.rows.map(row => ({ ...row, ingredient_id: row.requested_id ?? row.ingredient_id })), rowToMedia);
}
// The media kinds whose `media_key` resolves against the image library today.
diff --git a/server/services/catalogDB/merge.js b/server/services/catalogDB/merge.js
new file mode 100644
index 0000000000..74085592d7
--- /dev/null
+++ b/server/services/catalogDB/merge.js
@@ -0,0 +1,242 @@
+// Local identity consolidation. Source rows remain live on the wire and revision identities survive;
+// the receipt is also the exact recovery input, not a best-effort undo log.
+import { createHash, randomUUID } from 'node:crypto';
+import { withTransaction, query } from '../../lib/db.js';
+import { canonicalStringify } from '../../lib/objects.js';
+import { ServerError } from '../../lib/errorHandler.js';
+import { getInstanceId, UNKNOWN_INSTANCE_ID } from '../instanceIdentity.js';
+import { listSheetPointers } from '../../lib/sheetPointers.js';
+import { sanitizeBiblePayload } from './shared.js';
+import { catalogMergeSchema } from '../../lib/catalogValidation.js';
+
+const TABLES = Object.freeze({
+ ingredients: ['catalog_ingredients', 'id = ANY($1)'],
+ sources: ['catalog_ingredient_sources', 'ingredient_id = ANY($1)'],
+ refs: ['catalog_ingredient_refs', 'ingredient_id = ANY($1)'],
+ media: ['catalog_ingredient_media', 'ingredient_id = ANY($1)'],
+ relations: ['catalog_ingredient_relations', 'from_id = ANY($1) OR to_id = ANY($1)'],
+ revisions: ['catalog_ingredient_revisions', 'ingredient_id = ANY($1)'],
+});
+const fail = (message, code = 'CATALOG_MERGE_CONFLICT') => {
+ throw new ServerError(message, { status: 409, code });
+};
+const fingerprint = value => createHash('sha256').update(canonicalStringify(value)).digest('hex');
+const plain = value => JSON.parse(JSON.stringify(value));
+const empty = value => value == null || value === '';
+
+async function snapshot(client, ids) {
+ const result = {};
+ for (const [key, [table, where]] of Object.entries(TABLES)) {
+ const { rows } = await client.query(`SELECT * FROM ${table} WHERE ${where}`, [ids]);
+ result[key] = plain(rows).sort((a, b) => canonicalStringify(a).localeCompare(canonicalStringify(b)));
+ }
+ return result;
+}
+
+function assertOwnedUnlocked(rows, instanceId) {
+ if (!instanceId || instanceId === UNKNOWN_INSTANCE_ID) fail('Local instance identity is unavailable');
+ for (const row of rows) {
+ if (row.origin_instance_id !== instanceId) fail('Both ingredients must belong to this instance', 'CATALOG_MERGE_FOREIGN');
+ if (row.payload?.locked !== false) fail('Both ingredients must be explicitly unlocked', 'CATALOG_INGREDIENT_LOCKED');
+ }
+}
+
+// Object fields recurse; lists union without truncation. Every unequal populated
+// scalar needs an explicit choice. The receipt preserves the unchosen originals.
+function unionValue(survivor, source, path, choices, conflicts) {
+ if (canonicalStringify(survivor) === canonicalStringify(source)) return survivor;
+ if (empty(survivor)) return source;
+ if (empty(source)) return survivor;
+ if (Array.isArray(survivor) && Array.isArray(source)) {
+ const result = [...survivor];
+ for (const value of source) {
+ const index = value?.id ? result.findIndex(existing => existing?.id === value.id) : -1;
+ if (index >= 0) result[index] = unionValue(result[index], value, `${path}/${index}`, choices, conflicts);
+ else if (!result.some(existing => canonicalStringify(existing) === canonicalStringify(value))) result.push(value);
+ }
+ return result;
+ }
+ if (typeof survivor === 'object' && typeof source === 'object' && !Array.isArray(survivor) && !Array.isArray(source)) {
+ return Object.fromEntries([...new Set([...Object.keys(survivor), ...Object.keys(source)])].map(key => [key,
+ unionValue(survivor[key], source[key], `${path}/${key.replaceAll('~', '~0').replaceAll('/', '~1')}`, choices, conflicts)]));
+ }
+ const choice = choices[path];
+ if (!choice) conflicts.push({ path, survivor, source });
+ return choice === 'source' ? source : survivor;
+}
+
+async function lockState(client, ids, writing) {
+ if (writing) {
+ // Catalog link/attachment writers do not all lock the owning ingredient.
+ // Row locks alone therefore miss phantom attachments after the preview.
+ // Short DB-only table locks cover those existing writers without imposing
+ // a new lock protocol on every caller. No provider/file/peer work runs here.
+ await client.query(`LOCK TABLE ${Object.values(TABLES).map(([table]) => table).join(', ')}, catalog_ingredient_merges IN SHARE ROW EXCLUSIVE MODE`);
+ }
+ await client.query('SELECT id FROM catalog_ingredients WHERE id = ANY($1) ORDER BY id FOR UPDATE', [ids]);
+}
+
+export async function mergeIngredients(input) {
+ const body = catalogMergeSchema.parse(input);
+ const { sourceId, survivorId, fieldChoices, dryRun } = body;
+ if (sourceId === survivorId) fail('Choose two different ingredient identities');
+ const instanceId = await getInstanceId();
+ return withTransaction(async client => {
+ const ids = [sourceId, survivorId].sort();
+ await lockState(client, ids, !dryRun);
+ const active = await client.query(`SELECT id FROM catalog_ingredient_merges
+ WHERE restored_at IS NULL AND (source_id = ANY($1) OR survivor_id = ANY($1))`, [ids]);
+ if (active.rowCount) fail('Recover the existing merge before merging either identity again');
+ const before = await snapshot(client, ids);
+ const source = before.ingredients.find(row => row.id === sourceId && !row.deleted);
+ const survivor = before.ingredients.find(row => row.id === survivorId && !row.deleted);
+ if (!source || !survivor) fail('Both ingredients must exist and be live');
+ assertOwnedUnlocked([source, survivor], instanceId);
+ if (source.type !== survivor.type) fail('Ingredient types must match');
+ const conflicts = [];
+ const proposed = unionValue(
+ { name: survivor.name, payload: survivor.payload, tags: survivor.tags },
+ { name: source.name, payload: source.payload, tags: source.tags }, '', fieldChoices, conflicts,
+ );
+ // Alternate names remain discoverable even when the chosen display name differs.
+ proposed.payload.aliases = [...new Set([...(Array.isArray(proposed.payload.aliases) ? proposed.payload.aliases : []), source.name, survivor.name])]
+ .filter(name => name !== proposed.name);
+ const sanitized = sanitizeBiblePayload(source.type, proposed.name, proposed.payload);
+ const checkArrayCapacity = (value, normalized, path = 'payload') => {
+ if (Array.isArray(value) && Array.isArray(normalized) && normalized.length < value.length) {
+ fail(`Merged ${path} exceeds the supported capacity or contains incompatible entries; no values were discarded`);
+ }
+ if (value && normalized && typeof value === 'object' && typeof normalized === 'object') {
+ for (const key of Object.keys(value)) checkArrayCapacity(value[key], normalized[key], `${path}/${key}`);
+ }
+ };
+ checkArrayCapacity(proposed.payload, sanitized);
+ const previewToken = fingerprint({ before, proposed, fieldChoices });
+ if (dryRun) return { sourceId, survivorId, proposed, conflicts, previewToken,
+ counts: Object.fromEntries(Object.entries(before).map(([key, rows]) => [key, rows.length])) };
+ if (conflicts.length) fail('Resolve every populated scalar conflict before merging');
+ if (body.previewToken !== previewToken) fail('Catalog changed or choices changed; preview the merge again', 'CATALOG_MERGE_STALE');
+
+ await client.query(`UPDATE catalog_ingredients SET name = $2, payload = $3::jsonb, tags = $4,
+ embedding = NULL, embedding_model = NULL WHERE id = $1`,
+ [survivorId, proposed.name, JSON.stringify(proposed.payload), proposed.tags]);
+ // Copy only live associations; retain the original rows and collision
+ // provenance in the receipt rather than overwriting survivor captions/spans.
+ await client.query(`INSERT INTO catalog_ingredient_refs (ingredient_id, ref_kind, ref_id, role, created_at)
+ SELECT $2, ref_kind, ref_id, role, created_at FROM catalog_ingredient_refs
+ WHERE ingredient_id = $1 AND deleted = false
+ ON CONFLICT (ingredient_id, ref_kind, ref_id, role) DO UPDATE SET deleted = false, deleted_at = NULL`, [sourceId, survivorId]);
+ const hasPortrait = before.media.some(row => row.ingredient_id === survivorId && row.kind === 'portrait' && !row.deleted);
+ const mediaCopies = new Map();
+ const rememberMedia = row => {
+ const key = JSON.stringify([row.media_key, row.kind]);
+ if (!mediaCopies.has(key)) mediaCopies.set(key, row);
+ };
+ // Reference rows win a collision with a demoted portrait's converted key.
+ // Both originals (including distinct metadata) stay in the receipt.
+ for (const row of before.media.filter(row => row.ingredient_id === sourceId && !row.deleted)
+ .sort((a, b) => Number(a.kind === 'portrait') - Number(b.kind === 'portrait'))) {
+ rememberMedia({ ...row, kind: hasPortrait && row.kind === 'portrait' ? 'reference' : row.kind });
+ }
+ // Choosing one canonical pointer must not make its unchosen image disappear.
+ // Archive every original pointer as a reference; never promote it to canon.
+ for (const row of [survivor, source]) {
+ const payload = row.payload || {};
+ const pointers = [
+ ...listSheetPointers(payload).map(pointer => ({ filename: pointer.filename, role: `sheet:${pointer.variant}` })),
+ ...[payload.primaryImageRef, ...(Array.isArray(payload.imageRefs) ? payload.imageRefs : [])]
+ .filter(filename => typeof filename === 'string' && filename).map(filename => ({ filename, role: 'archive:reference' })),
+ ];
+ for (const pointer of pointers.filter(pointer => typeof pointer.filename === 'string' && pointer.filename)) rememberMedia({ media_key: pointer.filename, kind: 'reference', role: pointer.role,
+ caption: `Preserved from ${row.name}`, metadata: {}, created_at: row.created_at });
+ }
+ for (const row of mediaCopies.values()) {
+ await client.query(`INSERT INTO catalog_ingredient_media (ingredient_id, media_key, kind, role, caption, metadata, created_at)
+ VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7)
+ ON CONFLICT (ingredient_id, media_key, kind) DO UPDATE SET deleted = false, deleted_at = NULL`,
+ [survivorId, row.media_key, row.kind, row.role, row.caption, JSON.stringify(row.metadata), row.created_at]);
+ }
+ await client.query(`INSERT INTO catalog_ingredient_relations (from_id, to_id, kind, created_at)
+ SELECT CASE WHEN from_id = $1 THEN $2 ELSE from_id END,
+ CASE WHEN to_id = $1 THEN $2 ELSE to_id END, kind, created_at
+ FROM catalog_ingredient_relations WHERE (from_id = $1 OR to_id = $1) AND deleted = false
+ AND NOT (from_id = ANY($3) AND to_id = ANY($3))
+ ON CONFLICT (from_id, to_id, kind) DO UPDATE SET deleted = false, deleted_at = NULL`, [sourceId, survivorId, ids]);
+ await client.query(`INSERT INTO catalog_ingredient_revisions (id, ingredient_id, name, payload, tags, source, actor)
+ VALUES ($1, $2, $3, $4::jsonb, $5, 'user', 'catalog-merge')`,
+ [`cat-rev-${randomUUID()}`, survivorId, proposed.name, JSON.stringify(proposed.payload), proposed.tags]);
+ const after = await snapshot(client, ids);
+ const id = randomUUID();
+ await client.query(`INSERT INTO catalog_ingredient_merges
+ (id, source_id, survivor_id, before_state, after_fingerprint) VALUES ($1, $2, $3, $4::jsonb, $5)`,
+ [id, sourceId, survivorId, JSON.stringify({ ...before, decision: { scope: 'local', fieldChoices, proposed } }), fingerprint(after)]);
+ return { id, sourceId, survivorId, merged: true, scope: 'local' };
+ });
+}
+
+const RECEIPT_SUMMARY = `id, source_id AS "sourceId", survivor_id AS "survivorId",
+ created_at AS "createdAt", restored_at AS "restoredAt"`;
+
+export async function getIngredientMergeHistory(ingredientId, { limit = 10, offset = 0 } = {}) {
+ const pageSize = Math.min(50, Math.max(1, limit));
+ const start = Math.max(0, offset);
+ const { rows } = await query(`SELECT ${RECEIPT_SUMMARY},
+ jsonb_build_object('ingredients', jsonb_array_length(before_state->'ingredients'),
+ 'revisions', jsonb_array_length(before_state->'revisions'), 'media', jsonb_array_length(before_state->'media'),
+ 'refs', jsonb_array_length(before_state->'refs'), 'sources', jsonb_array_length(before_state->'sources'),
+ 'relations', jsonb_array_length(before_state->'relations')) AS counts
+ FROM catalog_ingredient_merges WHERE source_id = $1 OR survivor_id = $1
+ ORDER BY created_at DESC, id DESC LIMIT $2 OFFSET $3`, [ingredientId, pageSize + 1, start]);
+ return { items: rows.slice(0, pageSize), nextOffset: rows.length > pageSize ? start + pageSize : null };
+}
+
+export async function getIngredientMergeReceipt(id) {
+ const { rows: [receipt] } = await query(`SELECT ${RECEIPT_SUMMARY}, before_state AS "beforeState"
+ FROM catalog_ingredient_merges WHERE id = $1`, [id]);
+ if (!receipt) throw new ServerError('Merge receipt not found', { status: 404 });
+ return receipt;
+}
+
+export async function recoverIngredientMerge(id) {
+ const instanceId = await getInstanceId();
+ return withTransaction(async client => {
+ // Same order as apply: table locks before any receipt/ingredient row lock.
+ await lockState(client, [], true);
+ const { rows: [receipt] } = await client.query('SELECT * FROM catalog_ingredient_merges WHERE id = $1 FOR UPDATE', [id]);
+ if (!receipt) throw new ServerError('Merge receipt not found', { status: 404 });
+ if (receipt.restored_at) return { id, restored: true };
+ const ids = [receipt.source_id, receipt.survivor_id].sort();
+ const current = await snapshot(client, ids);
+ assertOwnedUnlocked(current.ingredients, instanceId);
+ if (fingerprint(current) !== receipt.after_fingerprint) fail('Merged state changed; recovery would overwrite later work', 'CATALOG_MERGE_STALE');
+ await client.query('UPDATE catalog_ingredient_merges SET restored_at = NOW() WHERE id = $1', [id]);
+ // Source rows never moved. Restore only the two records and associations
+ // captured by this operation; unrelated ingredients and assets are untouched.
+ for (const key of ['refs', 'media', 'relations']) {
+ const [table, where] = TABLES[key];
+ await client.query(`UPDATE ${table} SET deleted = true, deleted_at = NOW() WHERE ${where}`, [ids]);
+ const rows = receipt.before_state[key];
+ if (!rows.length) continue;
+ const columns = Object.keys(rows[0]).filter(column => !['sync_sequence', 'updated_at'].includes(column));
+ const keys = key === 'refs' ? ['ingredient_id', 'ref_kind', 'ref_id', 'role']
+ : key === 'media' ? ['ingredient_id', 'media_key', 'kind'] : ['from_id', 'to_id', 'kind'];
+ const updates = columns.filter(column => !keys.includes(column)).map(column => `${column} = EXCLUDED.${column}`);
+ await client.query(`INSERT INTO ${table} (${columns.join(', ')})
+ SELECT ${columns.join(', ')} FROM jsonb_populate_recordset(NULL::${table}, $1::jsonb)
+ ON CONFLICT (${keys.join(', ')}) DO UPDATE SET ${updates.join(', ')}`, [JSON.stringify(rows)]);
+ }
+ // Keep the merge revision as an audit event. Recovery adds a new snapshot;
+ // the receipt retains the complete before/after identity history.
+ for (const row of receipt.before_state.ingredients) {
+ await client.query(`UPDATE catalog_ingredients SET name = $2, payload = $3::jsonb, tags = $4,
+ embedding = $5, embedding_model = $6, deleted = $7, deleted_at = $8 WHERE id = $1`,
+ [row.id, row.name, JSON.stringify(row.payload), row.tags, row.embedding, row.embedding_model, row.deleted, row.deleted_at]);
+ }
+ for (const row of receipt.before_state.ingredients) {
+ await client.query(`INSERT INTO catalog_ingredient_revisions (id, ingredient_id, name, payload, tags, source, actor)
+ VALUES ($1, $2, $3, $4::jsonb, $5, 'user', 'catalog-merge-recovery')`,
+ [`cat-rev-${randomUUID()}`, row.id, row.name, JSON.stringify(row.payload), row.tags]);
+ }
+ return { id, restored: true };
+ });
+}
diff --git a/server/services/catalogDB/refs.js b/server/services/catalogDB/refs.js
index adf0a69615..aee5717ed3 100644
--- a/server/services/catalogDB/refs.js
+++ b/server/services/catalogDB/refs.js
@@ -21,7 +21,7 @@ export async function linkIngredientToSource(ingredientId, scrapId, span = null,
const exec = client ? client.query.bind(client) : query;
await exec(
`INSERT INTO catalog_ingredient_sources (ingredient_id, scrap_id, span)
- VALUES ($1, $2, $3::jsonb)
+ VALUES (catalog_resolve_ingredient_id($1), $2, $3::jsonb)
ON CONFLICT (ingredient_id, scrap_id) ${preserveExisting ? 'DO NOTHING' : 'DO UPDATE SET span = EXCLUDED.span'}`,
[ingredientId, scrapId, span ? JSON.stringify(span) : null],
);
@@ -36,7 +36,7 @@ export async function listSourcesForIngredient(ingredientId) {
`SELECT s.*, sc.title AS scrap_title
FROM catalog_ingredient_sources s
LEFT JOIN catalog_scraps sc ON sc.id = s.scrap_id
- WHERE s.ingredient_id = $1`,
+ WHERE catalog_resolve_ingredient_id(s.ingredient_id) = catalog_resolve_ingredient_id($1)`,
[ingredientId],
);
return result.rows.map((row) => ({ ...rowToSource(row), scrapTitle: row.scrap_title ?? null }));
@@ -60,10 +60,10 @@ export async function listSiblingIngredientsBySource(ingredientId, scrapIds) {
const ids = [...new Set(scrapIds)].filter(Boolean);
if (ids.length === 0) return new Map();
const result = await query(
- `SELECT s.scrap_id, i.id, i.name, i.type
+ `SELECT DISTINCT s.scrap_id, i.id, i.name, i.type
FROM catalog_ingredient_sources s
- JOIN catalog_ingredients i ON i.id = s.ingredient_id
- WHERE s.scrap_id = ANY($1) AND s.ingredient_id != $2 AND i.deleted = false
+ JOIN catalog_ingredients i ON i.id = catalog_resolve_ingredient_id(s.ingredient_id)
+ WHERE s.scrap_id = ANY($1) AND i.id != catalog_resolve_ingredient_id($2) AND i.deleted = false
ORDER BY i.name ASC`,
[ids, ingredientId],
);
@@ -85,7 +85,7 @@ export async function linkIngredientToRef(ingredientId, refKind, refId, role, {
const exec = client ? client.query.bind(client) : query;
await exec(
`INSERT INTO catalog_ingredient_refs (ingredient_id, ref_kind, ref_id, role)
- VALUES ($1, $2, $3, $4)
+ VALUES (catalog_resolve_ingredient_id($1), $2, $3, $4)
ON CONFLICT (ingredient_id, ref_kind, ref_id, role) DO UPDATE
SET deleted = false, deleted_at = NULL`,
[ingredientId, refKind, refId, role],
@@ -172,7 +172,7 @@ export async function unlinkIngredientFromRef(ingredientId, refKind, refId, role
await query(
`UPDATE catalog_ingredient_refs
SET deleted = true, deleted_at = NOW()
- WHERE ingredient_id = $1 AND ref_kind = $2 AND ref_id = $3 AND role = $4
+ WHERE ingredient_id = catalog_resolve_ingredient_id($1) AND ref_kind = $2 AND ref_id = $3 AND role = $4
AND deleted = false`,
[ingredientId, refKind, refId, role],
);
@@ -189,16 +189,18 @@ export async function listRefsForIngredient(ingredientId) {
// Batched `listRefsForIngredient` for bulk hydration paths (#3940) — ONE query
// for N ingredients instead of N, with the same `deleted = false` live filter.
// Returns `Map<ingredientId, refs[]>` with an entry (possibly `[]`) for every id.
-export async function listRefsForIngredients(ingredientIds) {
+export async function listRefsForIngredients(ingredientIds, { preserveIdentity = false } = {}) {
const ids = [...new Set(ingredientIds)];
if (ids.length === 0) return new Map();
const result = await query(
- `SELECT * FROM catalog_ingredient_refs
- WHERE ingredient_id = ANY($1) AND deleted = false
+ preserveIdentity ? `SELECT * FROM catalog_ingredient_refs
+ WHERE ingredient_id = ANY($1) AND deleted = false ORDER BY ingredient_id` : `SELECT r.*, requested.id AS requested_id FROM unnest($1::text[]) requested(id)
+ JOIN catalog_ingredient_refs r ON r.ingredient_id = catalog_resolve_ingredient_id(requested.id)
+ WHERE r.deleted = false
ORDER BY ingredient_id`,
[ids],
);
- return groupRowsByIngredient(ids, result.rows, rowToRef);
+ return groupRowsByIngredient(ids, result.rows.map(row => ({ ...row, ingredient_id: row.requested_id ?? row.ingredient_id })), rowToRef);
}
// Like listRefsForIngredient, but drops refs whose TARGET no longer resolves to
@@ -216,13 +218,13 @@ export async function listLiveRefsForIngredient(ingredientId) {
return refs.filter((_, i) => resolved[i]?.resolved === true);
}
-export async function listIngredientsForRef(refKind, refId) {
+export async function listIngredientsForRef(refKind, refId, { preserveIdentity = false } = {}) {
const result = await query(
`SELECT i.*, r.role, r.created_at AS ref_created_at
FROM catalog_ingredients i
JOIN catalog_ingredient_refs r ON r.ingredient_id = i.id
WHERE r.ref_kind = $1 AND r.ref_id = $2
- AND r.deleted = false AND i.deleted = false`,
+ AND r.deleted = false AND i.deleted = false${preserveIdentity ? '' : ' AND i.id = catalog_resolve_ingredient_id(i.id)'}`,
[refKind, refId],
);
return result.rows.map((row) => ({ ingredient: rowToIngredient(row), role: row.role }));
@@ -241,13 +243,15 @@ export async function listIngredientsForRef(refKind, refId) {
export async function linkIngredientRelation(fromId, toId, kind, { client } = {}) {
if (fromId === toId) throw new Error('cannot relate an ingredient to itself');
const exec = client ? client.query.bind(client) : query;
- await exec(
+ const result = await exec(
`INSERT INTO catalog_ingredient_relations (from_id, to_id, kind)
- VALUES ($1, $2, $3)
+ SELECT catalog_resolve_ingredient_id($1), catalog_resolve_ingredient_id($2), $3
+ WHERE catalog_resolve_ingredient_id($1) <> catalog_resolve_ingredient_id($2)
ON CONFLICT (from_id, to_id, kind) DO UPDATE
- SET deleted = false, deleted_at = NULL`,
+ SET deleted = false, deleted_at = NULL RETURNING from_id`,
[fromId, toId, kind],
);
+ if (result.rowCount === 0) throw new Error('cannot relate an ingredient identity to itself');
}
export async function unlinkIngredientRelation(fromId, toId, kind) {
@@ -257,7 +261,7 @@ export async function unlinkIngredientRelation(fromId, toId, kind) {
await query(
`UPDATE catalog_ingredient_relations
SET deleted = true, deleted_at = NOW()
- WHERE from_id = $1 AND to_id = $2 AND kind = $3
+ WHERE from_id = catalog_resolve_ingredient_id($1) AND to_id = catalog_resolve_ingredient_id($2) AND kind = $3
AND deleted = false`,
[fromId, toId, kind],
);
@@ -275,7 +279,7 @@ export async function listRelationsForIngredient(id) {
i.name AS other_name, i.type AS other_type
FROM catalog_ingredient_relations r
JOIN catalog_ingredients i ON i.id = r.to_id
- WHERE r.from_id = $1 AND r.deleted = false AND i.deleted = false
+ WHERE r.from_id = catalog_resolve_ingredient_id($1) AND r.deleted = false AND i.deleted = false AND i.id = catalog_resolve_ingredient_id(i.id)
ORDER BY r.created_at ASC`,
[id],
),
@@ -284,7 +288,7 @@ export async function listRelationsForIngredient(id) {
i.name AS other_name, i.type AS other_type
FROM catalog_ingredient_relations r
JOIN catalog_ingredients i ON i.id = r.from_id
- WHERE r.to_id = $1 AND r.deleted = false AND i.deleted = false
+ WHERE r.to_id = catalog_resolve_ingredient_id($1) AND r.deleted = false AND i.deleted = false AND i.id = catalog_resolve_ingredient_id(i.id)
ORDER BY r.created_at ASC`,
[id],
),
diff --git a/server/services/catalogDB/sync.js b/server/services/catalogDB/sync.js
index 970827181f..b4d4d720b1 100644
--- a/server/services/catalogDB/sync.js
+++ b/server/services/catalogDB/sync.js
@@ -300,6 +300,7 @@ export async function upsertIngredientFromPeer(ing) {
deleted = EXCLUDED.deleted,
deleted_at = EXCLUDED.deleted_at
WHERE EXCLUDED.updated_at > catalog_ingredients.updated_at
+ AND NOT EXISTS (SELECT 1 FROM catalog_ingredient_merges WHERE source_id = EXCLUDED.id AND restored_at IS NULL)
RETURNING (xmax = 0) AS is_insert`,
[
ing.id,
diff --git a/server/services/catalogDBMedia.test.js b/server/services/catalogDBMedia.test.js
index 15fce70e2b..c452725271 100644
--- a/server/services/catalogDBMedia.test.js
+++ b/server/services/catalogDBMedia.test.js
@@ -99,7 +99,7 @@ describe('detachMedia', () => {
describe('setPortraitMedia', () => {
it('demotes other live portraits then attaches the new one', async () => {
await catalogDB.setPortraitMedia('i1', 'new.png', { caption: 'now' });
- expect(calls.shift().sql).toMatch(/SELECT id FROM catalog_ingredients WHERE id = \$1 FOR UPDATE/);
+ expect(calls.shift().sql).toMatch(/SELECT id FROM catalog_ingredients WHERE id = catalog_resolve_ingredient_id\(\$1\) FOR UPDATE/);
// Demote only after locking the owning ingredient.
expect(calls[0].sql).toMatch(/UPDATE catalog_ingredient_media SET deleted = true/i);
expect(calls[0].sql).toMatch(/kind = 'portrait'/i);
diff --git a/server/services/catalogSheet.js b/server/services/catalogSheet.js
index 68213c2de4..556a9a0208 100644
--- a/server/services/catalogSheet.js
+++ b/server/services/catalogSheet.js
@@ -20,7 +20,7 @@ import { ServerError } from '../lib/errorHandler.js';
import { universeAestheticLine } from '../lib/universeVisualStyle.js';
import { recordRenderPin } from '../lib/renderTargets.js';
import { shortId } from '../lib/fileUtils.js';
-import { getIngredient, listLiveRefsForIngredient } from './catalogDB.js';
+import { getIngredient, getIngredientIdentityIds, listLiveRefsForIngredient } from './catalogDB.js';
import { getUniverse } from './universeBuilder.js';
import { enqueueJob } from './mediaJobQueue/index.js';
import {
@@ -134,9 +134,12 @@ async function resolveSheetTarget(id, options) {
const universe = await getUniverse(ref.refId).catch(() => null);
if (universe) universes.push(universe);
}
- if (ingredient.type === 'character' && !isLook) {
+ // A local consolidation retains embedded source variants. Render its
+ // authoritative merged payload instead of delegating to a stale canon copy.
+ const identityIds = await getIngredientIdentityIds(ingredient.id);
+ if (ingredient.type === 'character' && !isLook && identityIds.length === 1) {
for (const universe of universes) {
- const entry = (universe.characters || []).find((c) => c.ingredientId === id);
+ const entry = (universe.characters || []).find((c) => c.ingredientId === ingredient.id);
if (entry) return { ingredient, payload, variant, delegate: { universeId: universe.id, entryId: entry.id } };
}
}