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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
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.jsxnew file mode 100644index 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.jsxnew file mode 100644index 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.jsxindex 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' && (<RevisionsPanelrevisions={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.jsxindex 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.mdindex 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.jsindex 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.mdnew file mode 100644index 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.mdindex 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.jsindex 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.jsindex 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.jsindex 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 perdiff --git a/server/routes/catalog.js b/server/routes/catalog.jsindex 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 captureddiff --git a/server/routes/catalogSheets.test.js b/server/routes/catalogSheets.test.jsindex 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.sqlindex 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.jsindex 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.jsindex 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.jsindex 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.jsindex 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.jsnew file mode 100644index 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.jsindex 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 = falseGROUP 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 countFROM 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 = falseWHERE 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)) tGROUP 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 iLEFT JOIN catalog_ingredient_refs rON 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.jsindex 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', acexport 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 DESCLIMIT $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.idAND m.deleted = falseAND 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 DESCLIMIT 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 = nullconst 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 = $1AND (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, optionslet 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, optionslet 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.jsindex 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 UPDATESET 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_mediaSET 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 = $3AND 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_mediaSET 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_mediaWHERE 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 = falseORDER 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.jsnew file mode 100644index 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.jsindex 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_titleFROM catalog_ingredient_sources sLEFT 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.typeFROM 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 = falseORDER 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 UPDATESET deleted = false, deleted_at = NULL`,[ingredientId, refKind, refId, role],@@ -172,7 +172,7 @@ export async function unlinkIngredientFromRef(ingredientId, refKind, refId, roleawait query(`UPDATE catalog_ingredient_refsSET 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 = $4AND 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 = falseORDER 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_atFROM catalog_ingredients iJOIN catalog_ingredient_refs r ON r.ingredient_id = i.idWHERE 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_relationsSET 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 = $3AND deleted = false`,[fromId, toId, kind],);@@ -275,7 +279,7 @@ export async function listRelationsForIngredient(id) {i.name AS other_name, i.type AS other_typeFROM catalog_ingredient_relations rJOIN 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_typeFROM catalog_ingredient_relations rJOIN 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.jsindex 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_atWHERE 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.jsindex 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.jsindex 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 } };}}