Skip to content

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

Add shared canonical catalog identities across paired owners (#12114)

[._.]/e56bd5db5607
diff --git a/client/src/components/catalog/CatalogIdentityEvidence.jsx b/client/src/components/catalog/CatalogIdentityEvidence.jsx
new file mode 100644
index 0000000000..6a90696578
--- /dev/null
+++ b/client/src/components/catalog/CatalogIdentityEvidence.jsx
@@ -0,0 +1,44 @@
+import { Link } from 'react-router';
+import CollapsibleSection from '../ui/CollapsibleSection';
+import { ingredientPath } from '../../lib/creativeLibraries';
+import { humanizeIntegrityField } from '../../lib/characterIntegrity';
+import { formatCount, formatDateTime } from '../../utils/formatters';
+
+export const identityButtonClass = 'min-h-[44px] px-3 py-2 rounded border border-port-border text-sm text-port-accent disabled:opacity-50';
+export const identityValueText = value => value == null ? 'Not set' : typeof value === 'string' ? value || 'Empty' : JSON.stringify(value, null, 2);
+
+export function IdentityValues({ title, value }) {
+ return <CollapsibleSection label={title} size="bar" className="min-w-0 rounded border border-port-border p-3">
+ <dl className="space-y-3 text-xs">{Object.entries(value || {}).map(([key, entry]) => <div key={key}>
+ <dt className="text-gray-500">{humanizeIntegrityField(key)}</dt>
+ <dd className="whitespace-pre-wrap break-words">{/_at$|At$/.test(key) && typeof entry === 'string' && !Number.isNaN(Date.parse(entry)) ? formatDateTime(entry) : identityValueText(entry)}</dd>
+ </div>)}</dl>
+ </CollapsibleSection>;
+}
+
+function OriginalEvidence({ title, snapshot, id, owner }) {
+ const original = snapshot?.ingredients?.find(item => item.id === id);
+ return <section className="min-w-0 space-y-2" aria-label={title}>
+ <h4 className="text-sm font-semibold">{title}: {original?.name || id}</h4>
+ <p className="text-xs break-all">Owner: {owner} · Original ID: {id}</p>
+ {original && <Link className="inline-flex min-h-[44px] items-center text-sm text-port-accent underline" to={ingredientPath(original)}>Open original ID</Link>}
+ <IdentityValues title="Reviewed original content" value={original} />
+ {['media', 'revisions', 'refs', 'sources', 'relations'].map(key => <CollapsibleSection key={key}
+ label={`${humanizeIntegrityField(key)} (${formatCount(snapshot?.[key]?.length ?? 0)})`} size="bar" className="rounded border border-port-border p-3">
+ <p className="text-xs text-gray-500 mb-2">Reviewed evidence retains original record IDs and attribution. Media references do not guarantee that the file is available on this instance.</p>
+ <div className="space-y-2">{(snapshot?.[key] || []).map((entry, index) => <IdentityValues key={entry.id || index}
+ title={entry.media_key || entry.revision_id || entry.ref_id || entry.id || `${humanizeIntegrityField(key)} ${formatCount(index + 1)}`} value={entry} />)}</div>
+ </CollapsibleSection>)}
+ </section>;
+}
+
+export default function CatalogIdentityEvidence({ plan }) {
+ return <div className="space-y-3">
+ <div className="grid grid-cols-1 lg:grid-cols-2 gap-3">
+ <OriginalEvidence title="Retained source" snapshot={plan.source} id={plan.sourceId} owner={plan.sourceOwner} />
+ <OriginalEvidence title="Canonical survivor" snapshot={plan.survivor} id={plan.survivorId} owner={plan.survivorOwner} />
+ </div>
+ <IdentityValues title="Proposed canonical content" value={plan.proposed} />
+ {!!Object.keys(plan.fieldChoices || {}).length && <IdentityValues title="Explicit field choices" value={plan.fieldChoices} />}
+ </div>;
+}
diff --git a/client/src/components/catalog/CatalogIdentityNotice.jsx b/client/src/components/catalog/CatalogIdentityNotice.jsx
new file mode 100644
index 0000000000..c97b773961
--- /dev/null
+++ b/client/src/components/catalog/CatalogIdentityNotice.jsx
@@ -0,0 +1,43 @@
+import { useEffect, useState } from 'react';
+import { Link, useSearchParams } from 'react-router';
+import { getInstances } from '../../services/apiSystem';
+import { ingredientPath } from '../../lib/creativeLibraries';
+import { peerBaseUrl } from '../../../../server/lib/peerUrl.js';
+
+export default function CatalogIdentityNotice({ identity, type }) {
+ const [params] = useSearchParams();
+ const [peer, setPeer] = useState(null);
+ useEffect(() => {
+ let active = true;
+ setPeer(null);
+ if (!identity || identity.localOwner === identity.survivorOwner) return () => { active = false; };
+ getInstances({ silent: true }).then(result => {
+ if (active) setPeer(result?.peers?.find(item => item.instanceId === identity.survivorOwner) || null);
+ }).catch(() => {});
+ return () => { active = false; };
+ }, [identity?.survivorOwner, identity?.localOwner]);
+ if (!identity) return null;
+ const canonicalPath = ingredientPath({ id: identity.survivorId, type });
+ const next = new URLSearchParams(params);
+ next.set('identityOperation', identity.operationId);
+ const message = identity.reason === 'CATALOG_IDENTITY_FENCED'
+ ? 'This identity is reserved while the owners complete or recover the agreement. Editing and generation are unavailable.'
+ : identity.reason === 'CATALOG_IDENTITY_RETAINED'
+ ? 'This original ID is retained for references and provenance. Edit the canonical survivor on its owner.'
+ : identity.reason === 'CATALOG_IDENTITY_FOREIGN'
+ ? 'Canonical content is owned by another instance. Editing and generation are unavailable here.'
+ : 'This is the canonical survivor. Retained source attachments and histories remain attributed and read-only.';
+ // Tailcat loopback addresses are server-local and are not browser destinations.
+ const remoteUrl = peer && peer.transport !== 'tailcat' && (peer.host || peer.address) && peer.port
+ ? `${peerBaseUrl(peer)}${canonicalPath}` : null;
+ return <aside className="rounded border border-port-warning/40 bg-port-card p-3 space-y-2" aria-label="Shared identity ownership">
+ <p className="text-sm">{message}</p>
+ <p className="text-xs break-all">Canonical owner: {identity.survivorOwner} · Retained source: {identity.sourceId}</p>
+ <div className="flex flex-wrap gap-3 text-sm text-port-accent">
+ {identity.localOwner === identity.survivorOwner ? <Link className="inline-flex items-center min-h-[44px] underline" to={canonicalPath}>Open canonical survivor</Link>
+ : remoteUrl ? <a className="inline-flex items-center min-h-[44px] underline" href={remoteUrl} target="_blank" rel="noopener noreferrer">Open canonical owner</a>
+ : <Link className="inline-flex items-center min-h-[44px] underline" to="/instances">Find canonical owner in Instances</Link>}
+ <Link className="inline-flex items-center min-h-[44px] underline" to={`${canonicalPath}?${next}`}>Inspect agreement and original evidence</Link>
+ </div>
+ </aside>;
+}
diff --git a/client/src/components/catalog/CatalogIdentityOperation.jsx b/client/src/components/catalog/CatalogIdentityOperation.jsx
new file mode 100644
index 0000000000..101642313b
--- /dev/null
+++ b/client/src/components/catalog/CatalogIdentityOperation.jsx
@@ -0,0 +1,104 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import useAsyncAction from '../../hooks/useAsyncAction';
+import useMounted from '../../hooks/useMounted';
+import { acceptCatalogIdentity, advanceCatalogIdentity, abortCatalogIdentity, recoverCatalogIdentity, getCatalogIdentity } from '../../services/apiCatalogIdentity';
+import CatalogIdentityEvidence, { IdentityValues, identityButtonClass as buttonClass } from './CatalogIdentityEvidence';
+import { formatDateTime } from '../../utils/formatters';
+
+const stateLabels = {
+ proposed: 'Proposed · local owner acceptance required',
+ prepared: 'Accepted here · reserved while awaiting the coordinator decision',
+ committed: 'Canonical identity committed here',
+ aborted: 'Aborted · no canonical consolidation applied',
+ recovery_prepared: 'Recovery accepted here · waiting for bilateral completion',
+ recovered: 'Recovered here · original identities restored',
+};
+
+export default function CatalogIdentityOperation({ id, ingredientId, localOwner, disabledReason, version, onUpdated, onPendingChange }) {
+ const [operation, setOperation] = useState(null);
+ const [error, setError] = useState(null);
+ const [retry, setRetry] = useState(0);
+ const [reviewed, setReviewed] = useState(false);
+ const [armed, setArmed] = useState(null);
+ const mounted = useMounted();
+ const generation = useRef(0);
+ const validate = useCallback(result => {
+ if (!result?.plan || result.id !== id || ![result.sourceId, result.survivorId].includes(ingredientId)) throw new Error('This shared identity operation does not belong to the current record.');
+ if (result.localOwner !== localOwner) throw new Error('This operation is not recorded for the current owner.');
+ return result;
+ }, [id, ingredientId, localOwner]);
+ useEffect(() => {
+ let active = true;
+ const request = ++generation.current;
+ getCatalogIdentity(id, { silent: true }).then(result => {
+ if (!active || request !== generation.current) return;
+ const valid = validate(result);
+ setOperation(valid); setError(null); setReviewed(false); setArmed(null);
+ }).catch(err => { if (active && request === generation.current) setError(err.message); });
+ return () => { active = false; };
+ }, [id, ingredientId, localOwner, retry, version, validate]);
+ const [run, busy] = useAsyncAction(async action => {
+ if (!operation || disabledReason && action !== 'abort') return;
+ const request = ++generation.current;
+ setError(null); onPendingChange?.(true);
+ const calls = {
+ accept: () => acceptCatalogIdentity(id, operation.planHash, { silent: true }),
+ advance: () => advanceCatalogIdentity(id, { silent: true }),
+ abort: () => abortCatalogIdentity(id, { silent: true }),
+ recover: () => recoverCatalogIdentity(id, operation.planHash, { silent: true }),
+ };
+ await calls[action]().then(result => {
+ const valid = validate(result);
+ if (!mounted.current) return;
+ onUpdated(valid);
+ if (request !== generation.current) return;
+ setOperation(valid); setReviewed(false); setArmed(null);
+ }).catch(err => {
+ if (mounted.current && request === generation.current) setError(err.message);
+ throw err;
+ }).finally(() => onPendingChange?.(false));
+ });
+ const coordinator = operation?.localOwner === operation?.survivorOwner;
+ const canAccept = operation?.state === 'proposed';
+ const canAbort = operation?.state === 'proposed' || coordinator && operation?.state === 'prepared';
+ const canRecover = operation?.state === 'committed';
+ const canAdvance = !!stateLabels[operation?.state];
+ return <section aria-label="Shared identity operation" className="rounded border border-port-border p-3 space-y-3">
+ <h3 className="font-semibold text-sm">Shared identity operation</h3>
+ <p className="text-xs break-all">{id}</p>
+ {error && <div role="alert" className="space-y-2 text-port-error"><p>{error}</p><p className="text-xs">The result is not confirmed. Keep this operation ID; reload its receipt before retrying. An unavailable peer does not release a prepared reservation.</p></div>}
+ <button type="button" disabled={busy} className={buttonClass} onClick={() => setRetry(value => value + 1)}>Reload local receipt</button>
+ {!operation && !error && <p role="status">Loading owner receipt…</p>}
+ {operation && <>
+ <p role="status" className="text-sm">{stateLabels[operation.state] || `Unrecognized phase: ${operation.state}`}</p>
+ <p className="text-xs break-all">Local owner: {operation.localOwner} · Coordinator and canonical owner: {operation.survivorOwner}</p>
+ <p className="text-xs">Receipt updated {formatDateTime(operation.updatedAt)}</p>
+ <p className="text-xs">{operation.peerState
+ ? `Other owner’s last verified phase: ${operation.peerState}${operation.peerObservedAt ? ` · ${formatDateTime(operation.peerObservedAt)}` : ''}`
+ : 'Other owner’s phase has not been verified here.'}</p>
+ {operation.state === 'committed' && <p className="text-sm text-port-warning">{operation.peerState === 'committed'
+ ? 'Both owners have recorded commitment as of the last verification.'
+ : 'Commitment here does not confirm adoption by the other owner. Continue with the same operation to verify or finish adoption.'}</p>}
+ {operation.state === 'recovered' && operation.peerState !== 'recovered' && <p className="text-sm text-port-warning">Recovery here does not confirm recovery on the other owner. The other owner must resume this same operation.</p>}
+ {disabledReason && <p className="text-port-warning text-sm">{disabledReason}</p>}
+ <CatalogIdentityEvidence plan={operation.plan} />
+ {operation.appliedFingerprint && <p className="text-xs break-all">Applied state receipt: {operation.appliedFingerprint}</p>}
+ {operation.recovery && <IdentityValues title="Recovery receipt" value={operation.recovery} />}
+ <p className="text-xs text-gray-500">Reviewed plan: <span className="break-all">{operation.planHash}</span>. Original histories and asset attribution stay available above. Only the canonical owner may edit canonical content after commitment.</p>
+ {canAccept && <div className="flex items-start gap-2"><input id="identity-accept-reviewed" type="checkbox" checked={reviewed} disabled={busy || !!disabledReason} onChange={event => setReviewed(event.target.checked)} />
+ <label htmlFor="identity-accept-reviewed" className="text-sm">I accept this exact reviewed plan for the record owned by this instance. This reserves it until the coordinator decides.</label></div>}
+ <div className="flex flex-wrap gap-2">
+ {canAccept && <button type="button" className={buttonClass} disabled={busy || !!disabledReason || !reviewed} onClick={() => run('accept')}>Accept as this owner</button>}
+ {canAdvance && <button type="button" className={buttonClass} disabled={busy || !!disabledReason} onClick={() => run('advance')}>{operation.state === 'committed' && !coordinator ? 'Refresh from canonical owner' : 'Continue / verify with other owner'}</button>}
+ {canAbort && <button type="button" className={buttonClass} disabled={busy} onClick={() => setArmed('abort')}>{coordinator ? 'Abort uncommitted proposal' : 'Decline unaccepted proposal'}</button>}
+ {canRecover && <button type="button" className={buttonClass} disabled={busy || !!disabledReason} onClick={() => setArmed('recover')}>Review recovery</button>}
+ </div>
+ {armed && <div className="rounded border border-port-warning p-3 space-y-2">
+ <p className="text-sm">{armed === 'abort' ? coordinator ? 'Record the coordinator’s durable abort? The other owner resumes this operation to release its reservation.' : 'Decline this proposal before accepting it? The coordinator observes the decline when resuming this operation.'
+ : 'Accept recovery of this exact applied state? The coordinator must prepare first, then the other owner accepts, then both resume. Later changes block recovery; there is no force option.'}</p>
+ <div className="flex flex-wrap gap-2"><button type="button" className={buttonClass} disabled={busy || !!disabledReason && armed !== 'abort'} onClick={() => run(armed)}>{armed === 'abort' ? coordinator ? 'Confirm coordinator abort' : 'Confirm decline' : 'Accept recovery as this owner'}</button>
+ <button type="button" className={buttonClass} disabled={busy} onClick={() => setArmed(null)}>Cancel</button></div>
+ </div>}
+ </>}
+ </section>;
+}
diff --git a/client/src/components/catalog/CatalogIdentityPanel.jsx b/client/src/components/catalog/CatalogIdentityPanel.jsx
new file mode 100644
index 0000000000..3cbfbc7286
--- /dev/null
+++ b/client/src/components/catalog/CatalogIdentityPanel.jsx
@@ -0,0 +1,171 @@
+import { useCallback, useEffect, useState } from 'react';
+import { useSearchParams } from 'react-router';
+import CollapsibleSection from '../ui/CollapsibleSection';
+import InfiniteScrollFooter from '../ui/InfiniteScrollFooter';
+import { usePagedCollection } from '../../hooks/usePagedCollection';
+import useAsyncAction from '../../hooks/useAsyncAction';
+import useMounted from '../../hooks/useMounted';
+import socket from '../../services/socket';
+import { getSelfInstance } from '../../services/apiSystem';
+import { listCatalogIngredients } from '../../services/apiCatalog';
+import { importCatalogIdentity, listCatalogIdentities } from '../../services/apiCatalogIdentity';
+import CatalogIdentityProposal from './CatalogIdentityProposal';
+import CatalogIdentityOperation from './CatalogIdentityOperation';
+import { identityButtonClass as buttonClass } from './CatalogIdentityEvidence';
+import { formatDateTime } from '../../utils/formatters';
+import { uuidv4 } from '../../lib/uuid';
+
+export default function CatalogIdentityPanel(props) {
+ const [params] = useSearchParams();
+ return <CollapsibleSection label="Shared canonical identity" size="bar" defaultOpen={params.has('identitySource') || params.has('identityOperation')}
+ className="bg-port-card border border-port-border rounded-lg p-4" bodyClassName="pt-3">
+ <IdentityManager key={props.record.id} {...props} />
+ </CollapsibleSection>;
+}
+
+function IdentityManager({ record, disabledReason, onChanged, onPendingChange }) {
+ const [params, setParams] = useSearchParams();
+ const sourceId = params.get('identitySource') || '';
+ const selectedSurvivor = params.get('identitySurvivor') || record.id;
+ const operationId = params.get('identityOperation') || '';
+ const attemptId = params.get('identityAttempt') || '';
+ const [self, setSelf] = useState(null);
+ const [loadError, setLoadError] = useState(null);
+ const [version, setVersion] = useState(0);
+ const [query, setQuery] = useState('');
+ const [search, setSearch] = useState('');
+ const [peerDraft, setPeerDraft] = useState(params.get('identityPeer') || '');
+ const [operationDraft, setOperationDraft] = useState('');
+ const [importError, setImportError] = useState(null);
+ const mounted = useMounted();
+ useEffect(() => {
+ if (!sourceId || attemptId || operationId) return;
+ setParams(current => {
+ const next = new URLSearchParams(current);
+ if (!next.has('identityAttempt')) next.set('identityAttempt', uuidv4());
+ return next;
+ }, { replace: true });
+ }, [sourceId, attemptId, operationId, setParams]);
+ useEffect(() => {
+ let active = true;
+ getSelfInstance({ silent: true }).then(result => {
+ if (!active) return;
+ if (!result?.instanceId || result.instanceId === 'unknown') throw new Error('Current owner identity is unavailable');
+ setSelf(result); setLoadError(null);
+ }).catch(err => { if (active) setLoadError(err.message); });
+ return () => { active = false; };
+ }, [record.id, version]);
+ const fetchHistory = useCallback(async ({ cursor, signal }) => {
+ const page = await listCatalogIdentities({ ingredientId: record.id, limit: 10, offset: cursor || 0, signal, silent: true });
+ if (!Array.isArray(page?.items)) throw new Error('Shared identity history is unavailable');
+ return { items: page.items, nextCursor: page.nextOffset };
+ }, [record.id]);
+ const history = usePagedCollection(fetchHistory);
+ const { refreshFirst } = history;
+ useEffect(() => {
+ const reload = () => { setVersion(value => value + 1); refreshFirst(); };
+ const changed = event => {
+ if (event?.operationId === operationId || [event?.sourceId, event?.survivorId].includes(record.id)) reload();
+ };
+ socket.on('catalog:identity-changed', changed);
+ socket.on('connect', reload);
+ return () => { socket.off('catalog:identity-changed', changed); socket.off('connect', reload); };
+ }, [operationId, record.id, refreshFirst]);
+ const select = (values) => {
+ const next = new URLSearchParams(params);
+ for (const [key, value] of Object.entries(values)) {
+ if (value) next.set(key, value); else next.delete(key);
+ }
+ setParams(next);
+ };
+ const update = operation => {
+ history.setItems(items => [operation, ...items.filter(item => item.id !== operation.id)]);
+ // Aborting changes only the agreement, so preserve a pre-existing creative
+ // draft. The detail page's socket listener refreshes its ownership fence.
+ if (operation.state !== 'aborted') onChanged?.();
+ };
+ const [importOperation, importing] = useAsyncAction(async () => {
+ if (!peerDraft.trim() || !operationDraft.trim() || disabledReason) return;
+ setImportError(null); onPendingChange?.(true);
+ await importCatalogIdentity({ peerId: peerDraft.trim(), operationId: operationDraft.trim() }, { silent: true }).then(operation => {
+ if (!operation?.id || ![operation.sourceId, operation.survivorId].includes(record.id)) throw new Error('Imported operation is not for this record. Its receipt remains available in catalog identity history.');
+ if (!mounted.current) return;
+ history.setItems(items => [operation, ...items.filter(item => item.id !== operation.id)]);
+ select({ identityPeer: peerDraft.trim(), identityOperation: operation.id });
+ }).catch(err => { if (mounted.current) setImportError(err.message); throw err; })
+ .finally(() => onPendingChange?.(false));
+ });
+ const createReason = disabledReason || (selectedSurvivor !== record.id ? 'The survivor in this link does not match the current record. Clear the selection and select the intended survivor.'
+ : self && record.originInstanceId !== self.instanceId ? 'Create a proposal on the canonical survivor’s owner. This owner can import a proposal and accept its own source record.'
+ : record.payload?.locked !== false ? 'This record must already be unlocked before proposing a shared identity.' : null);
+ return <div className="space-y-4 text-gray-300">
+ <p className="text-sm">Consolidate the same subject across two owners. The selected survivor retains its ID and owner. Each owner accepts the exact plan locally; originals, histories and assets remain attributed and recoverable.</p>
+ <p className="text-xs text-gray-500">Both records must already be unlocked. This workflow never unlocks records. An offline peer leaves the operation pending; use the same operation ID to resume.</p>
+ {loadError && <p role="alert">{loadError}</p>}
+ {!self && <button type="button" className={buttonClass} onClick={() => setVersion(value => value + 1)}>Reload owner identity</button>}
+ {self && <>
+ {!operationId && <>
+ {createReason && <p role="status" className="text-port-warning">{createReason}</p>}
+ {!createReason && <CandidateSearch record={record} localOwner={self.instanceId} sourceId={sourceId} query={query} setQuery={setQuery} search={search} setSearch={setSearch}
+ onSelect={id => select({ identitySource: id, identitySurvivor: record.id, identityAttempt: sourceId === id && params.get('identityAttempt') || uuidv4() })} />}
+ {sourceId && <>
+ <button type="button" className={buttonClass} onClick={() => select({ identitySource: null, identitySurvivor: null, identityAttempt: null })}>Clear shared identity selection</button>
+ {attemptId && <CatalogIdentityProposal key={`${sourceId}:${selectedSurvivor}:${attemptId}`} sourceId={sourceId} survivor={record} localOwner={self.instanceId}
+ attemptId={attemptId}
+ onInspect={id => select({ identityOperation: id })}
+ disabledReason={createReason} onPendingChange={onPendingChange}
+ onCreated={operation => { history.setItems(items => [operation, ...items]); select({ identityOperation: operation.id, identitySource: null, identitySurvivor: null, identityAttempt: null }); }} />}
+ </>}
+ </>}
+ <form className="rounded border border-port-border p-3 space-y-3" onSubmit={event => { event.preventDefault(); importOperation(); }}>
+ <h3 className="font-semibold text-sm">Import a coordinator’s proposal</h3>
+ <p className="text-xs">On the source owner, enter the coordinator’s instance ID and operation ID. Import verifies the plan; it does not accept it.</p>
+ <div className="grid grid-cols-1 md:grid-cols-2 gap-3">
+ <div className="min-w-0"><label htmlFor="identity-import-peer" className="block text-xs mb-1">Coordinator instance ID</label><input id="identity-import-peer" className="w-full bg-port-bg rounded border border-port-border p-2" value={peerDraft} onChange={event => setPeerDraft(event.target.value)} disabled={importing} /></div>
+ <div className="min-w-0"><label htmlFor="identity-import-operation" className="block text-xs mb-1">Operation ID</label><input id="identity-import-operation" className="w-full bg-port-bg rounded border border-port-border p-2" value={operationDraft} onChange={event => setOperationDraft(event.target.value)} disabled={importing} /></div>
+ </div>
+ <button type="submit" className={buttonClass} disabled={importing || !!disabledReason || !peerDraft.trim() || !operationDraft.trim()}>Import verified proposal</button>
+ {importError && <p role="alert" className="text-port-error">{importError}</p>}
+ </form>
+ {operationId && <>
+ <button type="button" className={buttonClass} onClick={() => select({ identityOperation: null })}>Close selected operation</button>
+ <CatalogIdentityOperation key={operationId} id={operationId} ingredientId={record.id} localOwner={self.instanceId} disabledReason={disabledReason}
+ version={version} onUpdated={update} onPendingChange={onPendingChange} />
+ </>}
+ </>}
+ <section aria-label="Shared identity history" className="space-y-2">
+ <h3 className="text-sm font-semibold">Shared identity history</h3>
+ {history.loaded && !history.items.length && <p className="text-xs">No shared identity operations recorded for this ingredient.</p>}
+ {history.items.map(operation => <div key={operation.id} className="min-w-0 rounded border border-port-border p-3">
+ <p className="text-xs break-all">{operation.sourceId} → {operation.survivorId}</p>
+ <p className="text-xs">{operation.state} · {formatDateTime(operation.updatedAt || operation.createdAt)}</p>
+ <button type="button" className={buttonClass} onClick={() => select({ identityOperation: operation.id })}>Inspect operation {operation.id}</button>
+ </div>)}
+ <InfiniteScrollFooter hasMore={history.hasMore} loading={history.loading} error={history.error} onLoadMore={history.loadMore} autoLoad={false} label="Load more identity operations" />
+ </section>
+ </div>;
+}
+
+function CandidateSearch({ record, localOwner, sourceId, query, setQuery, search, setSearch, onSelect }) {
+ const fetchPage = 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('Shared identity candidate search is unavailable');
+ return { items: page.items, nextCursor: page.items.length === 24 ? offset + page.items.length : null };
+ }, [record.type, search]);
+ const candidates = usePagedCollection(fetchPage);
+ const eligible = candidates.items.filter(item => item.id !== record.id && item.type === record.type && item.originInstanceId && item.originInstanceId !== localOwner && item.payload?.locked === false);
+ return <div className="space-y-2">
+ <form className="flex flex-wrap gap-2 items-end" onSubmit={event => { event.preventDefault(); setSearch(query.trim()); }}>
+ <div className="min-w-0 flex-1"><label htmlFor="identity-candidate-search" className="block text-xs mb-1">Find the other owner’s {record.type}</label>
+ <input id="identity-candidate-search" value={query} onChange={event => setQuery(event.target.value)} className="w-full bg-port-bg rounded border border-port-border p-2" /></div>
+ <button type="submit" className={buttonClass}>Search shared identity candidates</button>
+ </form>
+ {eligible.map(item => <div key={item.id} className="rounded border border-port-border p-3 flex flex-wrap items-center justify-between gap-2">
+ <div className="min-w-0"><p className="text-sm">{item.name}</p><p className="text-xs break-all">{item.id} · Owner: {item.originInstanceId}</p></div>
+ <button type="button" className={buttonClass} aria-pressed={sourceId === item.id} onClick={() => onSelect(item.id)}>Select source {item.name}</button>
+ </div>)}
+ {candidates.loaded && !eligible.length && <p className="text-xs">No eligible foreign-owned unlocked records in the loaded results. Search or load more.</p>}
+ <InfiniteScrollFooter hasMore={candidates.hasMore} loading={candidates.loading} error={candidates.error} onLoadMore={candidates.loadMore} autoLoad={false} label="Load more identity candidates" />
+ </div>;
+}
diff --git a/client/src/components/catalog/CatalogIdentityPanel.test.jsx b/client/src/components/catalog/CatalogIdentityPanel.test.jsx
new file mode 100644
index 0000000000..60a91e9959
--- /dev/null
+++ b/client/src/components/catalog/CatalogIdentityPanel.test.jsx
@@ -0,0 +1,211 @@
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { createMemoryRouter, RouterProvider } from 'react-router';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import CatalogIdentityPanel from './CatalogIdentityPanel';
+import { getSelfInstance } from '../../services/apiSystem';
+import { getCatalogIngredientDetails, listCatalogIngredients } from '../../services/apiCatalog';
+import * as api from '../../services/apiCatalogIdentity';
+
+const { handlers } = vi.hoisted(() => ({ handlers: new Map() }));
+vi.mock('../../services/socket', () => ({ default: { on: (event, handler) => handlers.set(event, handler), off: (event) => handlers.delete(event) } }));
+vi.mock('../../services/apiSystem', () => ({ getSelfInstance: vi.fn() }));
+vi.mock('../../services/apiCatalog', () => ({ getCatalogIngredientDetails: vi.fn(), listCatalogIngredients: vi.fn() }));
+vi.mock('../../services/apiCatalogIdentity', () => ({
+ listCatalogIdentities: vi.fn(), getCatalogIdentity: vi.fn(), previewCatalogIdentity: vi.fn(), createCatalogIdentity: vi.fn(),
+ importCatalogIdentity: vi.fn(), acceptCatalogIdentity: vi.fn(), advanceCatalogIdentity: vi.fn(), abortCatalogIdentity: vi.fn(), recoverCatalogIdentity: vi.fn(),
+}));
+vi.mock('../ui/Toast', () => ({ default: { error: vi.fn() } }));
+
+const survivor = { id: 'shared-survivor', type: 'character', name: 'Example Keeper', originInstanceId: 'owner-one', payload: { locked: false, role: 'Guide' } };
+const source = { ...survivor, id: 'shared-source', name: 'Example Traveler', originInstanceId: 'owner-two' };
+const snapshot = record => ({ ingredients: [{ ...record, origin_instance_id: record.originInstanceId }], refs: [], sources: [], media: [{ id: `${record.id}-asset`, ingredient_id: record.id, media_key: 'example-reference.png' }], relations: [], revisions: [] });
+const plan = { version: 1, sourceId: source.id, survivorId: survivor.id, sourceOwner: source.originInstanceId, survivorOwner: survivor.originInstanceId,
+ source: snapshot(source), survivor: snapshot(survivor), proposed: { name: survivor.name, payload: survivor.payload }, fieldChoices: {} };
+const operation = { id: 'example-operation', sourceId: source.id, survivorId: survivor.id, sourceOwner: 'owner-two', survivorOwner: 'owner-one', localOwner: 'owner-one', state: 'proposed', plan, planHash: 'reviewed-plan', updatedAt: '2026-01-01T12:00:00Z' };
+
+async function show({ record = survivor, query = '', disabledReason } = {}) {
+ const router = createMemoryRouter([{ path: '/casting/:id', element: <CatalogIdentityPanel record={record} disabledReason={disabledReason} /> }], { initialEntries: [`/casting/${record.id}${query}`] });
+ render(<RouterProvider router={router} />);
+ if (!query.includes('identitySource') && !query.includes('identityOperation')) fireEvent.click(screen.getByRole('button', { name: 'Shared canonical identity' }));
+ await act(async () => {});
+ return router;
+}
+
+beforeEach(() => {
+ vi.resetAllMocks(); handlers.clear();
+ getSelfInstance.mockResolvedValue({ instanceId: 'owner-one' });
+ getCatalogIngredientDetails.mockResolvedValue({ ingredient: source });
+ listCatalogIngredients.mockResolvedValue({ items: [source] });
+ api.listCatalogIdentities.mockResolvedValue({ items: [], nextOffset: null });
+ api.getCatalogIdentity.mockImplementation(async id => ({ ...operation, id }));
+ api.previewCatalogIdentity.mockResolvedValue({ plan, planHash: 'reviewed-plan', conflicts: [] });
+ api.createCatalogIdentity.mockImplementation(async body => ({ ...operation, id: body.operationId }));
+ api.acceptCatalogIdentity.mockResolvedValue({ ...operation, state: 'prepared' });
+});
+
+describe('shared canonical identity operator workflow', () => {
+ it('deep-links the pair and requires conflict resolution plus a fresh reviewed plan before creation', async () => {
+ api.previewCatalogIdentity.mockResolvedValueOnce({ plan, planHash: 'unresolved', conflicts: [{ path: '/name', source: source.name, survivor: survivor.name }] });
+ const router = await show();
+ fireEvent.click(screen.getByRole('button', { name: `Select source ${source.name}` }));
+ expect(new URLSearchParams(router.state.location.search).get('identitySource')).toBe(source.id);
+ expect(new URLSearchParams(router.state.location.search).get('identitySurvivor')).toBe(survivor.id);
+ await waitFor(() => expect(screen.getByRole('button', { name: 'Preview shared identity' })).toBeEnabled());
+ fireEvent.click(screen.getByRole('button', { name: 'Preview shared identity' }));
+ expect(await screen.findByText('Resolve Name')).toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: 'Create shared identity proposal' })).not.toBeInTheDocument();
+ fireEvent.click(screen.getByRole('radio', { name: /Keep survivor value/ }));
+ fireEvent.click(screen.getByRole('button', { name: 'Preview shared identity' }));
+ const create = await screen.findByRole('button', { name: 'Create shared identity proposal' });
+ expect(create).toBeDisabled();
+ fireEvent.click(screen.getByRole('checkbox', { name: /These records describe the same subject/ }));
+ fireEvent.click(create);
+ await waitFor(() => expect(api.createCatalogIdentity).toHaveBeenCalledWith({ operationId: expect.any(String), sourceId: source.id, survivorId: survivor.id, fieldChoices: { '/name': 'survivor' }, planHash: 'reviewed-plan' }, { silent: true }));
+ const createdId = api.createCatalogIdentity.mock.calls[0][0].operationId;
+ expect(api.previewCatalogIdentity.mock.calls[0][0].operationId).toBe(createdId);
+ await waitFor(() => expect(new URLSearchParams(router.state.location.search).get('identityOperation')).toBe(createdId));
+ expect(api.acceptCatalogIdentity).not.toHaveBeenCalled();
+ });
+
+ it('retries an uncertain creation with the same URL-bound ID and exact body, then uses a fresh ID after an aborted attempt', async () => {
+ api.createCatalogIdentity.mockRejectedValueOnce(new Error('Connection lost after sending')).mockImplementation(async body => ({ ...operation, id: body.operationId }));
+ api.abortCatalogIdentity.mockImplementation(async id => ({ ...operation, id, state: 'aborted' }));
+ const router = await show({ query: '?identitySource=shared-source' });
+ await waitFor(() => expect(screen.getByRole('button', { name: 'Preview shared identity' })).toBeEnabled());
+ fireEvent.click(screen.getByRole('button', { name: 'Preview shared identity' }));
+ fireEvent.click(await screen.findByRole('checkbox', { name: /These records describe/ }));
+ fireEvent.click(screen.getByRole('button', { name: 'Create shared identity proposal' }));
+ const retry = await screen.findByRole('button', { name: 'Retry same creation request' });
+ await waitFor(() => expect(retry).toBeEnabled());
+ const firstBody = api.createCatalogIdentity.mock.calls[0][0];
+ expect(new URLSearchParams(router.state.location.search).get('identityAttempt')).toBe(firstBody.operationId);
+ expect(screen.getByRole('button', { name: 'Preview shared identity' })).toBeDisabled();
+ fireEvent.click(screen.getByRole('button', { name: 'Shared canonical identity' }));
+ fireEvent.click(screen.getByRole('button', { name: 'Shared canonical identity' }));
+ fireEvent.click(await screen.findByRole('button', { name: 'Retry same creation request' }));
+ await screen.findByRole('button', { name: 'Abort uncommitted proposal' });
+ expect(api.createCatalogIdentity.mock.calls[1][0]).toEqual(firstBody);
+ fireEvent.click(screen.getByRole('button', { name: 'Abort uncommitted proposal' }));
+ fireEvent.click(screen.getByRole('button', { name: 'Confirm coordinator abort' }));
+ await screen.findByText('Aborted · no canonical consolidation applied');
+ fireEvent.click(screen.getByRole('button', { name: 'Close selected operation' }));
+ fireEvent.click(await screen.findByRole('button', { name: `Select source ${source.name}` }));
+ await waitFor(() => expect(screen.getByRole('button', { name: 'Preview shared identity' })).toBeEnabled());
+ fireEvent.click(screen.getByRole('button', { name: 'Preview shared identity' }));
+ await screen.findByRole('checkbox', { name: /These records describe/ });
+ expect(api.previewCatalogIdentity.mock.calls.at(-1)[0].operationId).not.toBe(firstBody.operationId);
+ });
+
+ it('lets the coordinator abort without requiring dirty form edits to be saved or records unlocked', async () => {
+ api.getCatalogIdentity.mockResolvedValue({ ...operation, state: 'prepared' });
+ api.abortCatalogIdentity.mockResolvedValue({ ...operation, state: 'aborted' });
+ await show({ query: '?identityOperation=example-operation', disabledReason: 'Save profile edits first' });
+ const abort = await screen.findByRole('button', { name: 'Abort uncommitted proposal' });
+ expect(abort).toBeEnabled();
+ fireEvent.click(abort);
+ fireEvent.click(screen.getByRole('button', { name: 'Confirm coordinator abort' }));
+ expect(await screen.findByText('Aborted · no canonical consolidation applied')).toBeInTheDocument();
+ expect(api.abortCatalogIdentity).toHaveBeenCalledWith(operation.id, { silent: true });
+ });
+
+ it('resets the reviewed preview when the URL selects a different attempt for the same pair', async () => {
+ const firstId = '11111111-1111-4111-8111-111111111111';
+ const secondId = '22222222-2222-4222-8222-222222222222';
+ const router = await show({ query: `?identitySource=shared-source&identityAttempt=${firstId}` });
+ await waitFor(() => expect(screen.getByRole('button', { name: 'Preview shared identity' })).toBeEnabled());
+ fireEvent.click(screen.getByRole('button', { name: 'Preview shared identity' }));
+ await screen.findByRole('checkbox', { name: /These records describe/ });
+ await act(async () => { await router.navigate(`/casting/shared-survivor?identitySource=shared-source&identityAttempt=${secondId}`); });
+ expect(screen.queryByRole('checkbox', { name: /These records describe/ })).not.toBeInTheDocument();
+ await waitFor(() => expect(screen.getByRole('button', { name: 'Preview shared identity' })).toBeEnabled());
+ fireEvent.click(screen.getByRole('button', { name: 'Preview shared identity' }));
+ await screen.findByRole('checkbox', { name: /These records describe/ });
+ expect(api.previewCatalogIdentity.mock.calls.map(([body]) => body.operationId)).toEqual([firstId, secondId]);
+ });
+
+ it('imports the coordinator instance ID, then separately accepts the exact plan as the source owner', async () => {
+ getSelfInstance.mockResolvedValue({ instanceId: 'owner-two' });
+ const imported = { ...operation, localOwner: 'owner-two' };
+ api.importCatalogIdentity.mockResolvedValue(imported);
+ api.getCatalogIdentity.mockResolvedValue(imported);
+ api.acceptCatalogIdentity.mockResolvedValue({ ...imported, state: 'prepared' });
+ const router = await show({ record: source });
+ fireEvent.change(screen.getByLabelText('Coordinator instance ID'), { target: { value: 'owner-one' } });
+ fireEvent.change(screen.getByLabelText('Operation ID'), { target: { value: operation.id } });
+ fireEvent.click(screen.getByRole('button', { name: 'Import verified proposal' }));
+ const accept = await screen.findByRole('button', { name: 'Accept as this owner' });
+ expect(accept).toBeDisabled();
+ expect(api.acceptCatalogIdentity).not.toHaveBeenCalled();
+ expect(new URLSearchParams(router.state.location.search).get('identityPeer')).toBe('owner-one');
+ fireEvent.click(screen.getByRole('checkbox', { name: /I accept this exact reviewed plan/ }));
+ fireEvent.click(accept);
+ expect(await screen.findByText('Accepted here · reserved while awaiting the coordinator decision')).toBeInTheDocument();
+ expect(api.importCatalogIdentity).toHaveBeenCalledWith({ peerId: 'owner-one', operationId: operation.id }, { silent: true });
+ expect(api.acceptCatalogIdentity).toHaveBeenCalledWith(operation.id, operation.planHash, { silent: true });
+ expect(screen.queryByRole('button', { name: 'Abort uncommitted proposal' })).not.toBeInTheDocument();
+ });
+
+ it('keeps an offline prepared operation inspectable and retries the same ID without claiming completion', async () => {
+ api.getCatalogIdentity.mockResolvedValue({ ...operation, state: 'prepared' });
+ api.advanceCatalogIdentity.mockRejectedValueOnce(new Error('Peer is offline')).mockResolvedValueOnce({ ...operation, state: 'committed', peerState: 'prepared' });
+ await show({ query: '?identityOperation=example-operation' });
+ fireEvent.click(await screen.findByRole('button', { name: 'Continue / verify with other owner' }));
+ expect(await screen.findByRole('alert')).toHaveTextContent('Peer is offline');
+ expect(screen.getByText('Accepted here · reserved while awaiting the coordinator decision')).toBeInTheDocument();
+ fireEvent.click(screen.getByRole('button', { name: 'Continue / verify with other owner' }));
+ expect(await screen.findByText(/Commitment here does not confirm adoption/)).toBeInTheDocument();
+ expect(api.advanceCatalogIdentity.mock.calls.map(call => call[0])).toEqual([operation.id, operation.id]);
+ expect(api.createCatalogIdentity).not.toHaveBeenCalled();
+ });
+
+ it('requires explicit guarded recovery and preserves a refusal rather than offering force', async () => {
+ api.getCatalogIdentity.mockResolvedValue({ ...operation, state: 'committed', peerState: 'committed' });
+ api.recoverCatalogIdentity.mockRejectedValue(new Error('Later edits prevent recovery'));
+ await show({ query: '?identityOperation=example-operation' });
+ fireEvent.click(await screen.findByRole('button', { name: 'Review recovery' }));
+ expect(api.recoverCatalogIdentity).not.toHaveBeenCalled();
+ fireEvent.click(screen.getByRole('button', { name: 'Accept recovery as this owner' }));
+ expect(await screen.findByRole('alert')).toHaveTextContent('Later edits prevent recovery');
+ expect(api.recoverCatalogIdentity).toHaveBeenCalledWith(operation.id, operation.planHash, { silent: true });
+ expect(screen.queryByRole('button', { name: /force/i })).not.toBeInTheDocument();
+ expect(screen.queryByText('Recovered here · original identities restored')).not.toBeInTheDocument();
+ });
+
+ it('rejects unrelated operation URLs and drops a late response after selecting another operation', async () => {
+ let finishOld;
+ api.getCatalogIdentity.mockImplementationOnce(() => new Promise(resolve => { finishOld = resolve; }));
+ api.getCatalogIdentity.mockResolvedValue({ ...operation, id: 'other-operation', sourceId: 'unrelated-source', survivorId: 'unrelated-survivor' });
+ const router = await show({ query: '?identityOperation=example-operation' });
+ await act(async () => { await router.navigate('/casting/shared-survivor?identityOperation=other-operation'); });
+ expect(await screen.findByRole('alert')).toHaveTextContent('does not belong');
+ await act(async () => { finishOld(operation); });
+ expect(screen.queryByRole('button', { name: 'Accept as this owner' })).not.toBeInTheDocument();
+ expect(api.acceptCatalogIdentity).not.toHaveBeenCalled();
+ });
+
+ it('refreshes selected receipts on matching events/reconnect, pages summaries, and never loads every plan', async () => {
+ api.listCatalogIdentities.mockResolvedValueOnce({ items: [operation], nextOffset: 10 })
+ .mockResolvedValue({ items: [{ ...operation, id: 'older-operation' }], nextOffset: null });
+ await show();
+ expect(api.getCatalogIdentity).not.toHaveBeenCalled();
+ fireEvent.click(screen.getByRole('button', { name: 'Load more identity operations' }));
+ await waitFor(() => expect(api.listCatalogIdentities).toHaveBeenLastCalledWith(expect.objectContaining({ offset: 10 })));
+ fireEvent.click(screen.getByRole('button', { name: `Inspect operation ${operation.id}` }));
+ await screen.findByRole('button', { name: 'Accept as this owner' });
+ const reads = api.getCatalogIdentity.mock.calls.length;
+ await act(async () => { handlers.get('catalog:identity-changed')({ operationId: 'unrelated' }); });
+ expect(api.getCatalogIdentity).toHaveBeenCalledTimes(reads);
+ await act(async () => { handlers.get('catalog:identity-changed')({ operationId: operation.id }); });
+ await waitFor(() => expect(api.getCatalogIdentity).toHaveBeenCalledTimes(reads + 1));
+ await act(async () => { handlers.get('connect')(); });
+ await waitFor(() => expect(api.getCatalogIdentity).toHaveBeenCalledTimes(reads + 2));
+ });
+
+ it('does not offer unlock or eligible creation for locked records and preserves dirty-form gating', async () => {
+ await show({ record: { ...survivor, payload: { locked: true } }, query: '?identitySource=shared-source', disabledReason: 'Save profile edits first' });
+ expect(await screen.findByRole('button', { name: 'Preview shared identity' })).toBeDisabled();
+ expect(screen.getByRole('button', { name: 'Import verified proposal' })).toBeDisabled();
+ expect(screen.queryByRole('button', { name: /unlock/i })).not.toBeInTheDocument();
+ expect(api.previewCatalogIdentity).not.toHaveBeenCalled();
+ });
+});
diff --git a/client/src/components/catalog/CatalogIdentityProposal.jsx b/client/src/components/catalog/CatalogIdentityProposal.jsx
new file mode 100644
index 0000000000..cd7657dcb0
--- /dev/null
+++ b/client/src/components/catalog/CatalogIdentityProposal.jsx
@@ -0,0 +1,102 @@
+import { useEffect, useState } from 'react';
+import useAsyncAction from '../../hooks/useAsyncAction';
+import useMounted from '../../hooks/useMounted';
+import { getCatalogIngredientDetails } from '../../services/apiCatalog';
+import { createCatalogIdentity, previewCatalogIdentity } from '../../services/apiCatalogIdentity';
+import { humanizeIntegrityField } from '../../lib/characterIntegrity';
+import { safeReadJsonSession, safeWriteJsonSession, safeRemoveSession } from '../../lib/safeStorage';
+import CatalogIdentityEvidence, { identityButtonClass as buttonClass, identityValueText } from './CatalogIdentityEvidence';
+
+export default function CatalogIdentityProposal({ sourceId, survivor, localOwner, disabledReason, attemptId: operationId, onInspect, onCreated, onPendingChange }) {
+ const storageKey = `catalog-identity-request:${operationId}`;
+ const [pendingRequest, setPendingRequest] = useState(() => {
+ const stored = safeReadJsonSession(storageKey);
+ return stored?.operationId === operationId && stored.sourceId === sourceId && stored.survivorId === survivor.id ? stored : null;
+ });
+ const [source, setSource] = useState(null);
+ const [error, setError] = useState(null);
+ const [choices, setChoices] = useState({});
+ const [preview, setPreview] = useState(null);
+ const [confirmed, setConfirmed] = useState(false);
+ const [retry, setRetry] = useState(0);
+ const mounted = useMounted();
+ useEffect(() => {
+ let active = true;
+ getCatalogIngredientDetails(sourceId, { silent: true }).then(result => {
+ if (!active) return;
+ if (!result?.ingredient) throw new Error('Source record not found');
+ setSource(result.ingredient); setError(null);
+ }).catch(err => { if (active) setError(err.message); });
+ return () => { active = false; };
+ }, [sourceId, retry]);
+ const reason = disabledReason || (survivor.originInstanceId !== localOwner ? 'Create the proposal on the selected canonical survivor’s owner.'
+ : survivor.payload?.locked !== false ? 'The canonical survivor must already be unlocked. This workflow cannot unlock it.'
+ : source && (source.id === survivor.id ? 'The selected IDs already resolve to the same identity.'
+ : source.type !== survivor.type ? 'Both records must have the same type.'
+ : !source.originInstanceId || source.originInstanceId === localOwner ? 'Choose a record belonging to the other owner.'
+ : source.payload?.locked !== false ? 'The source must already be unlocked by its owner. This workflow cannot unlock it.' : null));
+ const [run, busy] = useAsyncAction(async action => {
+ setError(null); onPendingChange?.(true);
+ const body = { operationId, sourceId, survivorId: survivor.id, fieldChoices: choices };
+ await (async () => {
+ if (action === 'preview') {
+ if (pendingRequest) return;
+ setPreview(null); setConfirmed(false);
+ const result = await previewCatalogIdentity(body, { silent: true });
+ if (!result?.plan || !result.planHash || !Array.isArray(result.conflicts)) throw new Error('The owner-verified preview is unavailable');
+ if (mounted.current) setPreview(result);
+ } else {
+ if (!pendingRequest && (!confirmed || !preview || preview.conflicts.length)) return;
+ const request = pendingRequest || { ...body, planHash: preview.planHash };
+ setPendingRequest(request);
+ safeWriteJsonSession(storageKey, request);
+ const operation = await createCatalogIdentity(request, { silent: true });
+ if (operation?.id !== operationId) throw new Error('Creation outcome is uncertain. Inspect this operation before creating another proposal.');
+ safeRemoveSession(storageKey);
+ if (mounted.current) onCreated(operation);
+ }
+ })().catch(err => {
+ if (mounted.current) {
+ setError(err.message); setPreview(null); setConfirmed(false);
+ if (action === 'preview' || (err.status >= 400 && err.status < 500)) {
+ setPendingRequest(null); safeRemoveSession(storageKey);
+ }
+ }
+ throw err;
+ }).finally(() => onPendingChange?.(false));
+ });
+ return <section className="space-y-3 rounded border border-port-border p-3" aria-label="Shared identity proposal">
+ <h3 className="font-semibold text-sm">Keep {survivor.name} as canonical</h3>
+ <p className="text-xs break-all">Survivor: {survivor.id} · Source: {sourceId}</p>
+ {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…</p>}
+ {!source && error && <button type="button" className={buttonClass} onClick={() => setRetry(value => value + 1)}>Retry source</button>}
+ <button type="button" className={buttonClass} disabled={busy || !!reason || !source || !!pendingRequest} onClick={() => run('preview')}>Preview shared identity</button>
+ {pendingRequest && <div className="rounded border border-port-warning p-3 space-y-2">
+ <p className="text-sm">Creation is not confirmed. Retry the exact reviewed request with the same operation ID, or inspect its receipt. Do not create a replacement while the outcome is uncertain.</p>
+ <p className="text-xs break-all">{operationId}</p>
+ <button type="button" className={buttonClass} disabled={busy || !!disabledReason} onClick={() => run('create')}>Retry same creation request</button>
+ <button type="button" className={buttonClass} disabled={busy} onClick={() => onInspect(operationId)}>Inspect creation receipt</button>
+ </div>}
+ {preview && <>
+ <CatalogIdentityEvidence plan={preview.plan} />
+ {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 => {
+ const inputId = `identity-choice-${encodeURIComponent(conflict.path)}-${side}`;
+ return <div key={side} className="flex gap-2 items-start text-xs"><input id={inputId} type="radio" name={`identity-${conflict.path}`}
+ checked={choices[conflict.path] === side} onChange={() => { setChoices(current => ({ ...current, [conflict.path]: side })); setConfirmed(false); }} />
+ <label htmlFor={inputId} className="min-w-0"><strong>{side === 'survivor' ? 'Keep survivor value' : 'Use source value'}</strong>
+ <span className="block whitespace-pre-wrap break-words">{identityValueText(conflict[side])}</span></label></div>;
+ })}
+ </fieldset>)}
+ {preview.conflicts.length > 0 ? <p className="text-xs text-port-warning">Choose each conflict, then preview again to review the resulting canonical content.</p> : <>
+ <div className="flex gap-2 items-start"><input id="identity-confirm-proposal" type="checkbox" checked={confirmed} disabled={busy} onChange={event => setConfirmed(event.target.checked)} />
+ <label htmlFor="identity-confirm-proposal" className="text-sm">These records describe the same subject. I reviewed the survivor, owners and proposed content.</label></div>
+ <button type="button" className={buttonClass} disabled={busy || !!reason || !confirmed} onClick={() => run('create')}>Create shared identity proposal</button>
+ <p className="text-xs text-gray-500">Creation records the plan. Each owner must separately accept that exact plan on its own instance before commitment.</p>
+ </>}
+ </>}
+ </section>;
+}
diff --git a/client/src/components/catalog/CatalogLooksPanel.jsx b/client/src/components/catalog/CatalogLooksPanel.jsx
index 176e23ec1d..a671ed0866 100644
--- a/client/src/components/catalog/CatalogLooksPanel.jsx
+++ b/client/src/components/catalog/CatalogLooksPanel.jsx
@@ -120,14 +120,14 @@ function LookCard({
const role = `${LOOK_ROLE_PREFIX}${wardrobe.id}`;
const setRole = async (m, nextRole, message) => {
- if (busyKey) return;
+ if (busyKey || editLocked || !onSetRole || m.readOnly) return;
setBusyKey(m.mediaKey);
const ok = await onSetRole(m, nextRole, message);
setBusyKey(null);
if (ok && nextRole) setMode(null);
};
const roleButton = (m, nextRole, label, message, Icon) => (
- <button type="button" onClick={() => setRole(m, nextRole, message)} disabled={!!busyKey}
+ <button type="button" onClick={() => setRole(m, nextRole, message)} disabled={!!busyKey || editLocked || !onSetRole || m.readOnly}
title={label} aria-label={label}
className="port-media-overlay-item p-2 sm:p-1 rounded hover:text-port-accent disabled:opacity-50">
{busyKey === m.mediaKey
@@ -144,10 +144,10 @@ function LookCard({
{wardrobe.description && <p className="text-xs text-gray-400 whitespace-pre-wrap break-words mt-0.5">{wardrobe.description}</p>}
</div>
<div className="flex items-center gap-1.5 flex-wrap">
- <button type="button" onClick={() => toggle('generate')} className={smallButton} aria-expanded={mode === 'generate'}>
+ <button type="button" onClick={() => toggle('generate')} disabled={editLocked} className={smallButton} aria-expanded={mode === 'generate'}>
<Sparkles size={12} aria-hidden="true" /> Generate
</button>
- <button type="button" onClick={() => toggle('attach')} className={smallButton} aria-expanded={mode === 'attach'}>
+ <button type="button" onClick={() => toggle('attach')} disabled={editLocked} className={smallButton} aria-expanded={mode === 'attach'}>
<ImagePlus size={12} aria-hidden="true" /> Attach image
</button>
<button type="button" onClick={() => toggle('edit')} disabled={editLocked} className={smallButton}
@@ -164,12 +164,12 @@ function LookCard({
{mode === 'delete' && (
<ConfirmButtonPair
prompt={images.length ? 'Delete this look? Its images move to References.' : 'Delete this look?'}
- confirmText="Delete look" ariaLabel={`Confirm deleting ${wardrobe.name}`} busy={savingList}
+ confirmText="Delete look" ariaLabel={`Confirm deleting ${wardrobe.name}`} busy={savingList || editLocked}
onConfirm={async () => { if (await onDelete(wardrobe)) setMode(null); }}
onCancel={() => setMode(null)} largeTouchTargets />
)}
{mode === 'edit' && (
- <LookForm formId={`look-${wardrobe.id}`} initial={wardrobe} busy={savingList}
+ <LookForm formId={`look-${wardrobe.id}`} initial={wardrobe} busy={savingList || editLocked}
onSubmit={async (fields) => { if (await onSave({ ...wardrobe, ...fields })) setMode(null); }}
onCancel={() => setMode(null)} />
)}
@@ -228,6 +228,7 @@ export default function CatalogLooksPanel({
const candidateList = Array.isArray(candidates) ? candidates : [];
const save = async (next) => {
+ if (editLocked) return false;
setSavingList(true);
const ok = await onSaveWardrobes(next);
setSavingList(false);
@@ -253,9 +254,9 @@ export default function CatalogLooksPanel({
</button>
)}
</div>
- {editLocked && <p className="text-xs text-gray-500" role="status">Saving the profile — looks can be edited once it finishes.</p>}
+ {editLocked && <p className="text-xs text-gray-500" role="status">{blockedReason || 'Saving the profile — looks can be edited once it finishes.'}</p>}
{adding && (
- <LookForm formId="look-new" busy={savingList} onSubmit={handleAdd} onCancel={() => setAdding(false)} />
+ <LookForm formId="look-new" busy={savingList || editLocked} onSubmit={handleAdd} onCancel={() => setAdding(false)} />
)}
{list.length === 0 && !adding && (
<p className="text-xs text-gray-500">No looks yet. Add one to describe an outfit, then generate or attach its images.</p>
diff --git a/client/src/components/catalog/CatalogMediaTile.jsx b/client/src/components/catalog/CatalogMediaTile.jsx
index 6c39646b96..fae1997c35 100644
--- a/client/src/components/catalog/CatalogMediaTile.jsx
+++ b/client/src/components/catalog/CatalogMediaTile.jsx
@@ -50,7 +50,8 @@ export default function CatalogMediaTile({
missing
</span>
)}
- <div className="port-media-overlay absolute top-1 right-1 flex gap-1 rounded opacity-100 sm:opacity-0 sm:group-hover:opacity-100 focus-within:opacity-100 transition-opacity">
+ {m.readOnly && <p className="text-xs text-gray-500 p-2 break-words">Read-only provenance · {m.ingredientId || 'retained media'}</p>}
+ {!m.readOnly && <div className="port-media-overlay absolute top-1 right-1 flex gap-1 rounded opacity-100 sm:opacity-0 sm:group-hover:opacity-100 focus-within:opacity-100 transition-opacity">
{extraActions}
{!isPortrait && isImage && onSetPortrait && (
<button type="button" onClick={() => onSetPortrait(m.mediaKey)} title="Set as portrait" aria-label="Set as portrait"
@@ -70,7 +71,7 @@ export default function CatalogMediaTile({
<X size={12} aria-hidden="true" />
</button>
))}
- </div>
+ </div>}
</div>
);
}
diff --git a/client/src/components/catalog/CatalogPlatesPanel.jsx b/client/src/components/catalog/CatalogPlatesPanel.jsx
index 57748cd305..c8bbfc0589 100644
--- a/client/src/components/catalog/CatalogPlatesPanel.jsx
+++ b/client/src/components/catalog/CatalogPlatesPanel.jsx
@@ -13,14 +13,14 @@ export default function CatalogPlatesPanel({ plates, candidates, missingMedia, o
const candidateList = Array.isArray(candidates) ? candidates : [];
const setRole = async (m, role) => {
- if (busyKey) return;
+ if (busyKey || !onSetRole || m.readOnly) return;
setBusyKey(m.mediaKey);
await onSetRole(m, role);
setBusyKey(null);
};
const roleButton = (m, role, label, Icon) => (
- <button type="button" onClick={() => setRole(m, role)} disabled={!!busyKey}
+ <button type="button" onClick={() => setRole(m, role)} disabled={!!busyKey || !onSetRole || m.readOnly}
title={label} aria-label={label}
className="port-media-overlay-item p-2 sm:p-1 rounded hover:text-port-accent disabled:opacity-50">
{busyKey === m.mediaKey
diff --git a/client/src/pages/CatalogIngredient.jsx b/client/src/pages/CatalogIngredient.jsx
index 4e26b88115..4318c1db86 100644
--- a/client/src/pages/CatalogIngredient.jsx
+++ b/client/src/pages/CatalogIngredient.jsx
@@ -38,6 +38,7 @@ import { arrayBufferToBase64 } from '../lib/audioRecorder';
import useMemoRecorder from '../hooks/useMemoRecorder';
import { useGalleryPage } from '../hooks/useGalleryPage';
import { generateImage } from '../services/apiSystem';
+import socket from '../services/socket';
import { previewImagePrompt } from '../services/apiImageVideo';
import { composeStyledPrompt, stylePromptAdditions } from '../lib/composeStyledPrompt';
import { universeStylePreset, withUniverseLabel } from '../lib/universeStylePreset';
@@ -60,6 +61,8 @@ 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 CatalogIdentityPanel from '../components/catalog/CatalogIdentityPanel';
+import CatalogIdentityNotice from '../components/catalog/CatalogIdentityNotice';
import CharacterLoraChip from '../components/loraTraining/CharacterLoraChip';
import TagPicker from '../components/TagPicker';
import GenericIngredientFields from '../components/GenericIngredientFields';
@@ -178,6 +181,8 @@ export default function CatalogIngredient() {
const [record, setRecord] = useState(null);
const [mergeVersion, setMergeVersion] = useState(0);
const [mergeBusy, setMergeBusy] = useState(false);
+ const identityReadOnly = record?.sharedIdentity?.writable === false;
+ const identityReason = identityReadOnly ? 'This shared identity is read-only here. Inspect its ownership notice and agreement.' : null;
const [loading, setLoading] = useState(true);
const [name, setName] = useState('');
const [tags, setTags] = useState([]);
@@ -225,7 +230,7 @@ export default function CatalogIngredient() {
return;
}
const r = d.ingredient;
- setRecord({ ...r, refs: d.refs, sources: d.sources });
+ setRecord({ ...r, refs: d.refs, sources: d.sources, sharedIdentity: d.sharedIdentity || null });
setName(r.name || '');
setTags(Array.isArray(r.tags) ? r.tags : []);
setPayload(r.payload && typeof r.payload === 'object' ? { ...r.payload } : {});
@@ -247,10 +252,30 @@ export default function CatalogIngredient() {
return () => { cancelled = true; };
}, [id, navigate, backPath, mergeVersion]);
+ // Keep ownership fences current without discarding an unsaved creative draft.
+ // The original route ID is intentional: a retained-source URL must stay read-only.
+ useEffect(() => {
+ let active = true;
+ let request = 0;
+ const refreshIdentity = () => {
+ const current = ++request;
+ getCatalogIngredientDetails(id, { silent: true }).then(details => {
+ if (!active || current !== request || !details?.ingredient) return;
+ setRecord(previous => previous ? { ...previous, sharedIdentity: details.sharedIdentity || null } : previous);
+ }).catch(() => { if (active) toast.error('Unable to refresh shared identity status. Reload before editing.'); });
+ };
+ const changed = event => {
+ if ([event?.sourceId, event?.survivorId].includes(id)) refreshIdentity();
+ };
+ socket.on('catalog:identity-changed', changed);
+ socket.on('connect', refreshIdentity);
+ return () => { active = false; socket.off('catalog:identity-changed', changed); socket.off('connect', refreshIdentity); };
+ }, [id]);
+
// Add an outbound edge (this ingredient → picked target). Optimistically
// appends to local state so the panel updates without a refetch.
const handleAddRelation = async (target, kind) => {
- if (!record || !target?.id) return;
+ if (!record || identityReadOnly || !target?.id) return;
if (target.id === record.id) { toast.error('Cannot relate an ingredient to itself'); return; }
const ok = await linkCatalogIngredientRelation(record.id, { toId: target.id, kind }, { silent: true })
.then(() => true)
@@ -274,7 +299,7 @@ export default function CatalogIngredient() {
// Remove an outbound edge. Inbound edges are owned by the OTHER ingredient,
// so the panel only deletes outbound ones (filter is by toId + kind).
const handleRemoveRelation = async (toId, kind) => {
- if (!record) return;
+ if (!record || identityReadOnly) return;
const ok = await unlinkCatalogIngredientRelation(record.id, { toId, kind }, { silent: true })
.then(() => true)
.catch((err) => { toast.error(err?.message || 'Failed to remove relation'); return false; });
@@ -304,7 +329,7 @@ export default function CatalogIngredient() {
// to 'reference' for drag-drop / picker; the "set portrait" path routes
// through handleSetPortrait instead. Optimistic — prepend then reconcile.
const handleAttachMedia = async (mediaKey, kind = 'reference') => {
- if (!record || !mediaKey) return;
+ if (!record || identityReadOnly || !mediaKey) return;
const ok = await attachCatalogIngredientMedia(record.id, { mediaKey, kind }, { silent: true })
.then(() => true)
.catch((err) => { toast.error(err?.message || 'Failed to attach media'); return false; });
@@ -314,7 +339,7 @@ export default function CatalogIngredient() {
};
const handleSetPortrait = async (mediaKey) => {
- if (!record || !mediaKey) return;
+ if (!record || identityReadOnly || !mediaKey) return;
const ok = await setCatalogIngredientPortrait(record.id, { mediaKey }, { silent: true })
.then(() => true)
.catch((err) => { toast.error(err?.message || 'Failed to set portrait'); return false; });
@@ -324,7 +349,7 @@ export default function CatalogIngredient() {
};
const handleDetachMedia = async (mediaKey, kind) => {
- if (!record) return;
+ if (!record || identityReadOnly) return;
const ok = await detachCatalogIngredientMedia(record.id, { mediaKey, kind }, { silent: true })
.then(() => true)
.catch((err) => { toast.error(err?.message || 'Failed to detach media'); return false; });
@@ -336,7 +361,7 @@ export default function CatalogIngredient() {
// it onto this ingredient. First image becomes the portrait (so it shows as
// the card thumbnail immediately); later ones attach as references.
const handleGeneratedImage = useCallback(async (filename) => {
- if (!record || !filename) return;
+ if (!record || identityReadOnly || !filename) return;
const hasPortrait = media.some((m) => m.kind === 'portrait');
const ok = await (hasPortrait
? attachCatalogIngredientMedia(record.id, { mediaKey: filename, kind: 'reference' }, { silent: true })
@@ -345,13 +370,13 @@ export default function CatalogIngredient() {
if (!ok) return;
refreshMedia();
toast.success(hasPortrait ? 'Generated image attached' : 'Generated portrait set');
- }, [record, media, refreshMedia]);
+ }, [record, media, refreshMedia, identityReadOnly]);
// Upload a dropped/picked file straight onto the ingredient. The server picks
// the media kind (image→reference, audio, video) from the MIME and stores the
// bytes in the matching federating library dir. Reconcile via refreshMedia.
const handleUploadFile = useCallback(async (file) => {
- if (!record || !file) return false;
+ if (!record || identityReadOnly || !file) return false;
try {
const dataBase64 = arrayBufferToBase64(await file.arrayBuffer());
await uploadCatalogIngredientMediaFile(
@@ -366,12 +391,12 @@ export default function CatalogIngredient() {
toast.error(err?.message || 'Upload failed');
return false;
}
- }, [record, refreshMedia]);
+ }, [record, refreshMedia, identityReadOnly]);
// Attach a recorded voice memo — the server transcribes it via Whisper and
// stores the transcript in the audio row's caption.
const handleRecordVoiceMemo = useCallback(async (clip) => {
- if (!record || !clip?.audioBase64) return;
+ if (!record || identityReadOnly || !clip?.audioBase64) return;
const ok = await recordCatalogIngredientVoiceMemo(
record.id,
{ audioBase64: clip.audioBase64, mimeType: clip.mimeType },
@@ -380,13 +405,13 @@ export default function CatalogIngredient() {
if (!ok) return;
refreshMedia();
toast.success('Voice memo attached');
- }, [record, refreshMedia]);
+ }, [record, refreshMedia, identityReadOnly]);
// Re-attach an existing media row under a new role (mark/unmark a plate, add
// an image to a look). The attach endpoint upserts role/caption on the
// (ingredient, key, kind) row, so the caption is passed back unchanged.
const handleSetMediaRole = useCallback(async (m, role, message) => {
- if (!record || !m?.mediaKey) return false;
+ if (!record || identityReadOnly || m?.readOnly || !m?.mediaKey) return false;
const updated = await attachCatalogIngredientMedia(
record.id,
{ mediaKey: m.mediaKey, kind: m.kind, role, caption: m.caption ?? null },
@@ -398,26 +423,26 @@ export default function CatalogIngredient() {
)));
toast.success(message || (role ? 'Marked as plate' : 'Plate unmarked'));
return true;
- }, [record]);
+ }, [record, identityReadOnly]);
// A finished catalog-only sheet render: attach it under its `sheet:<variant>`
// role right away (the server-side attach hook files the same row and is
// idempotent against this), then reconcile the media list.
const handleSheetFile = useCallback(async (filename, role, readyMessage = 'Reference sheet ready') => {
- if (!record || !filename) return;
+ if (!record || identityReadOnly || !filename) return;
const ok = await attachCatalogIngredientMedia(record.id, { mediaKey: filename, kind: 'reference', role }, { silent: true })
.then(() => true)
.catch((err) => { toast.error(err?.message || 'Failed to attach the rendered image'); return false; });
refreshMedia();
if (ok) toast.success(readyMessage);
- }, [record, refreshMedia]);
+ }, [record, refreshMedia, identityReadOnly]);
const handleLookFile = useCallback((filename, role) => handleSheetFile(filename, role, 'Look ready'), [handleSheetFile]);
// Save the Looks tab's wardrobe list straight onto the SAVED payload, then
// copy just `wardrobes` into the draft so unsaved profile edits stay intact
// and exactly as dirty as they were.
const handleSaveWardrobes = useCallback(async (wardrobes) => {
- if (!record) return false;
+ if (!record || identityReadOnly) return false;
const submittedId = record.id;
const nextPayload = { ...ingredientPayload(record.payload), wardrobes };
setLookSaving(true);
@@ -430,7 +455,7 @@ export default function CatalogIngredient() {
setPayload((cur) => ({ ...cur, wardrobes: persisted.wardrobes }));
refreshRevisions();
return true;
- }, [record, refreshRevisions]);
+ }, [record, refreshRevisions, identityReadOnly]);
// A universe-delegated sheet landed as a canon pointer, which the canon→catalog
// projection already copied onto this row. Pull just the pointer fields into
@@ -457,7 +482,7 @@ export default function CatalogIngredient() {
}, [id]);
const handleSave = async () => {
- if (!record || unlocking) return;
+ if (!record || identityReadOnly || unlocking) return;
const submittedId = record.id;
const submittedGeneration = activeVisitRef.current.generation;
const submittedName = name;
@@ -500,7 +525,7 @@ export default function CatalogIngredient() {
};
const handleRestore = async (revisionId) => {
- if (!record) return false;
+ if (!record || identityReadOnly) return false;
const updated = await restoreCatalogIngredientRevision(record.id, revisionId, {}, { silent: true })
.catch((err) => { toast.error(err?.message || 'Restore failed'); return null; });
if (!updated) return false;
@@ -516,7 +541,7 @@ export default function CatalogIngredient() {
};
const confirmDelete = async () => {
- if (!record) return;
+ if (!record || identityReadOnly) return;
setArmedDelete(false);
const ok = await deleteCatalogIngredient(record.id, { silent: true })
.then(() => true)
@@ -607,6 +632,7 @@ export default function CatalogIngredient() {
const wardrobes = record.type === 'character' && Array.isArray(ingredientPayload(record.payload).wardrobes)
? record.payload.wardrobes
: [];
+ const protectMedia = (item) => ({ ...item, readOnly: identityReadOnly || item.retained === true || !!record.sharedIdentity && (item.ingredientId === record.sharedIdentity.sourceId || item.role?.startsWith('archive:identity')) });
const liveLookIds = new Set(wardrobes.map((w) => w?.id).filter(Boolean));
const isReferenceTabRow = (m) => isReferenceTabMedia(m, liveLookIds);
const coverUrl = ingredientCoverUrl({
@@ -614,7 +640,7 @@ export default function CatalogIngredient() {
thumbnailKey: media.find((m) => m.kind === 'portrait')?.mediaKey || record.thumbnailKey,
payload,
}) || ingredientCoverUrl({ thumbnailKey: media.find((m) => m.kind === 'reference' && !m.role?.startsWith('archive:'))?.mediaKey });
- const renderBlockedReason = (subject) => (record.payload?.locked === true
+ const renderBlockedReason = (subject) => identityReason || (record.payload?.locked === true
? 'Unlock this record above before rendering.'
: saving
? `Saving — the ${subject} renders from the saved record.`
@@ -653,7 +679,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 || mergeBusy}
+ <button type="button" onClick={handleSave} disabled={saving || lookSaving || unlocking || mergeBusy || identityReadOnly}
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>
@@ -670,7 +696,7 @@ export default function CatalogIngredient() {
{armedDelete ? (
<span className="inline-flex items-center gap-1 text-sm">
<span className="text-gray-400 px-1">Delete this ingredient?</span>
- <button type="button" onClick={confirmDelete}
+ <button type="button" onClick={confirmDelete} disabled={identityReadOnly}
className="inline-flex items-center gap-1 px-3 py-2 rounded-lg bg-port-error/20 text-port-error hover:bg-port-error/30 font-medium">
<Trash2 size={14} aria-hidden="true" /> Yes, delete
</button>
@@ -680,7 +706,7 @@ export default function CatalogIngredient() {
</button>
</span>
) : (
- <button type="button" onClick={() => setArmedDelete(true)}
+ <button type="button" onClick={() => setArmedDelete(true)} disabled={identityReadOnly}
className="inline-flex items-center gap-1.5 px-3 py-2 rounded-lg text-sm border border-port-border text-gray-400 hover:text-port-error"
aria-label="Delete ingredient" title="Delete">
<Trash2 size={14} /> Delete
@@ -689,6 +715,8 @@ export default function CatalogIngredient() {
</div>
</header>
+ <CatalogIdentityNotice identity={record.sharedIdentity} type={record.type} />
+
{tabs && (
<TabPills
tabs={tabs}
@@ -710,7 +738,7 @@ export default function CatalogIngredient() {
<figcaption className="text-xs text-gray-400 p-2">Cover image · select to enlarge</figcaption>
</figure>
)}
- <div className="min-w-0 space-y-4">
+ <fieldset disabled={identityReadOnly} className="min-w-0 space-y-4">
<div>
<label htmlFor="ingredient-name" className="block text-xs uppercase tracking-wider text-gray-500 mb-1">Name</label>
<input id="ingredient-name" type="text" value={name} onChange={(e) => setName(e.target.value)} maxLength={200}
@@ -723,9 +751,9 @@ export default function CatalogIngredient() {
<TagPicker id="ingredient-tags" value={tags} onChange={setTags}
placeholder="mentor, antagonist, season-1" />
</div>
- </div>
+ </fieldset>
</div>
- <div className="grid grid-cols-1 xl:grid-cols-2 gap-4 items-start">
+ <fieldset disabled={identityReadOnly} className="grid grid-cols-1 xl:grid-cols-2 gap-4 items-start">
{isUserType
? <GenericIngredientFields fields={fields} payload={payload} onChange={updatePayload} />
: sections
@@ -737,14 +765,14 @@ export default function CatalogIngredient() {
<SheetField key={key} fieldKey={key} label={label} kind={kind}
value={payload[key] ?? ''} onChange={updatePayload} />
))}
- </div>
+ </fieldset>
{/* Structured array-field editors (aliases / color palette / stats).
Driven by the type's registry-declared `editableListFields`; the
same durable catalog row the Universe Builder canon surface edits.
Light/user types declare none and skip this entirely. */}
{!isUserType && Array.isArray(typeDef.editableListFields) && typeDef.editableListFields.length > 0 && (
- <EditableListFields fields={typeDef.editableListFields} payload={payload} onChange={updatePayload} />
+ <fieldset disabled={identityReadOnly}><EditableListFields fields={typeDef.editableListFields} payload={payload} onChange={updatePayload} /></fieldset>
)}
</div>
@@ -772,6 +800,7 @@ export default function CatalogIngredient() {
record={record}
relations={relations}
evidence={payload?.evidence}
+ readOnly={identityReadOnly} retainedSourceId={record.sharedIdentity?.sourceId}
onAdd={handleAddRelation}
onRemove={handleRemoveRelation}
/>
@@ -779,7 +808,7 @@ export default function CatalogIngredient() {
)}
<div hidden={activeTab !== 'sheets' && activeTab !== 'looks'}>
- <CatalogUnlockNotice key={record.id} record={record} disabled={saving || lookSaving} onPendingChange={setUnlocking}
+ <CatalogUnlockNotice key={record.id} record={record} disabled={saving || lookSaving || identityReadOnly} onPendingChange={setUnlocking}
onUnlocked={(updated) => {
setRecord((current) => current?.id === updated.id
? { ...current, updatedAt: updated.updatedAt, payload: { ...current.payload, locked: false } } : current);
@@ -792,9 +821,9 @@ export default function CatalogIngredient() {
ingredientId={record.id}
payload={payload}
universeRef={universeRef}
- sheetMedia={media.filter(isSheetMedia)}
+ sheetMedia={media.filter(isSheetMedia).map(protectMedia)}
missingMedia={missingMedia}
- onDetach={handleDetachMedia}
+ onDetach={identityReadOnly ? undefined : handleDetachMedia}
blockedReason={renderBlockedReason('sheet')}
savedStamp={record.updatedAt || null}
onSheetFile={handleSheetFile}
@@ -806,39 +835,40 @@ export default function CatalogIngredient() {
<CatalogLooksPanel
ingredientId={record.id}
wardrobes={wardrobes}
- lookMedia={media.filter((m) => liveLookIds.has(lookIdOf(m)))}
- candidates={media.filter((m) => m.kind === 'reference' && isReferenceTabRow(m))}
+ lookMedia={media.filter((m) => liveLookIds.has(lookIdOf(m))).map(protectMedia)}
+ candidates={media.filter((m) => m.kind === 'reference' && isReferenceTabRow(m)).map(protectMedia)}
missingMedia={missingMedia}
- editLocked={saving || unlocking}
+ editLocked={saving || unlocking || identityReadOnly}
blockedReason={renderBlockedReason('look')}
savedStamp={record.updatedAt || null}
onSaveWardrobes={handleSaveWardrobes}
- onSetRole={handleSetMediaRole}
- onDetach={handleDetachMedia}
+ onSetRole={identityReadOnly ? undefined : handleSetMediaRole}
+ onDetach={identityReadOnly ? undefined : handleDetachMedia}
onLookFile={handleLookFile}
/>
)}
{activeTab === 'plates' && (
<CatalogPlatesPanel
- plates={media.filter(isPlateMedia)}
- candidates={media.filter((m) => m.kind === 'reference' && isReferenceTabRow(m))}
+ plates={media.filter(isPlateMedia).map(protectMedia)}
+ candidates={media.filter((m) => m.kind === 'reference' && isReferenceTabRow(m)).map(protectMedia)}
missingMedia={missingMedia}
- onSetRole={handleSetMediaRole}
- onDetach={handleDetachMedia}
+ onSetRole={identityReadOnly ? undefined : handleSetMediaRole}
+ onDetach={identityReadOnly ? undefined : handleDetachMedia}
/>
)}
{(activeTab === 'profile' ? !tabs : activeTab === 'references' || activeTab === 'images') && (
<MediaPanel
- media={tabs ? media.filter(isReferenceTabRow) : media}
+ readOnly={identityReadOnly}
+ media={(tabs ? media.filter(isReferenceTabRow) : media).map(protectMedia)}
canonImageRefs={[payload.primaryImageRef, ...(Array.isArray(payload.imageRefs) ? payload.imageRefs : [])].filter((ref) =>
!media.some((m) => (m.kind === 'portrait' || m.kind === 'reference') && m.mediaKey === ref))}
primaryImageRef={payload.primaryImageRef}
missingMedia={missingMedia}
onAttach={handleAttachMedia}
onSetPortrait={handleSetPortrait}
- onDetach={handleDetachMedia}
+ onDetach={identityReadOnly ? undefined : handleDetachMedia}
onUploadFile={handleUploadFile}
onRecordVoice={handleRecordVoiceMemo}
genIngredientId={record.id}
@@ -861,12 +891,18 @@ 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}
+ disabledReason={identityReason || (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' && <CatalogIdentityPanel record={record}
+ disabledReason={saving || lookSaving || unlocking ? 'Wait for the current save to finish.' : isDirty ? 'Save or discard profile edits before managing identity.' : null}
+ onPendingChange={setMergeBusy} onChanged={() => setMergeVersion((version) => version + 1)} />}
+
{activeTab === 'profile' && (
<RevisionsPanel
+ readOnly={identityReadOnly}
+ retainedSourceId={record.sharedIdentity?.sourceId}
revisions={revisions}
current={record}
fields={fields}
@@ -1082,7 +1118,7 @@ function StatListEditor({ field, value, onChange }) {
// "Relations" panel — ingredient↔ingredient edges. Outbound edges (this
// ingredient → other) are user-editable here; inbound edges (other → this
// ingredient) are read-only because the owning ingredient is the other end.
-function RelationsPanel({ record, relations, evidence, onAdd, onRemove }) {
+function RelationsPanel({ record, relations, evidence, onAdd, onRemove, readOnly = false, retainedSourceId }) {
const [pickerOpen, setPickerOpen] = useState(false);
const [kind, setKind] = useState(RELATION_KINDS[0].id);
const [armedRelation, setArmedRelation] = useState(null);
@@ -1116,11 +1152,11 @@ function RelationsPanel({ record, relations, evidence, onAdd, onRemove }) {
<h2 className="text-sm font-semibold text-white">Relations</h2>
<div className="flex items-center gap-2">
<label htmlFor="relation-kind" className="sr-only">Relation kind</label>
- <select id="relation-kind" value={kind} onChange={(e) => setKind(e.target.value)}
+ <select id="relation-kind" disabled={readOnly} value={kind} onChange={(e) => setKind(e.target.value)}
className="px-2 py-1.5 bg-port-bg border border-port-border rounded text-xs text-white focus:outline-none focus:border-port-accent">
{RELATION_KINDS.map((r) => <option key={r.id} value={r.id}>{r.label}</option>)}
</select>
- <button type="button" onClick={() => setPickerOpen(true)}
+ <button type="button" onClick={() => setPickerOpen(true)} disabled={readOnly}
className="inline-flex items-center gap-1.5 px-3 py-1.5 rounded bg-port-accent hover:bg-port-accent/90 text-white text-xs font-medium">
<Plus size={12} aria-hidden="true" /> Add relation
</button>
@@ -1148,7 +1184,7 @@ function RelationsPanel({ record, relations, evidence, onAdd, onRemove }) {
<div className="flex items-center gap-2 flex-wrap">
<span className="text-xs text-gray-400">{getRelationKind(r.kind)?.label || r.kind}</span>
{chip(r.other)}
- {armedRelation === relationKey ? (
+ {!readOnly && !(retainedSourceId && [r.fromId, r.toId].includes(retainedSourceId)) && (armedRelation === relationKey ? (
<ConfirmButtonPair
prompt="Remove?"
confirmText="Remove"
@@ -1169,8 +1205,9 @@ function RelationsPanel({ record, relations, evidence, onAdd, onRemove }) {
className="text-gray-500 hover:text-port-error">
<X size={12} aria-hidden="true" />
</button>
- )}
+ ))}
</div>
+ {retainedSourceId && [r.fromId, r.toId].includes(retainedSourceId) && <p className="text-xs text-gray-500">Retained source relation · read-only</p>}
{evidenceSnippet && (
<p className="text-[11px] text-gray-400 italic pl-3 border-l border-port-border">
“{evidenceSnippet}”
@@ -1417,7 +1454,7 @@ function GenerateImageControl({ ingredientId, name, description, universeId, onC
);
}
-function MediaPanel({ media, canonImageRefs = [], primaryImageRef, missingMedia, onAttach, onSetPortrait, onDetach, onUploadFile, onRecordVoice, genIngredientId, genName, genDescription, genUniverseId, onGenerated }) {
+function MediaPanel({ readOnly = false, media, canonImageRefs = [], primaryImageRef, missingMedia, onAttach, onSetPortrait, onDetach, onUploadFile, onRecordVoice, genIngredientId, genName, genDescription, genUniverseId, onGenerated }) {
const [pickerOpen, setPickerOpen] = useState(false);
const [dragOver, setDragOver] = useState(false);
const [busy, setBusy] = useState(false); // upload or transcription in flight
@@ -1436,7 +1473,7 @@ function MediaPanel({ media, canonImageRefs = [], primaryImageRef, missingMedia,
const canonImages = [...new Set(canonImageRefs.filter((ref) => typeof ref === 'string' && ref.trim()))];
const doUpload = async (file) => {
- if (!file || busy) return;
+ if (!file || busy || readOnly) return;
setBusy(true);
try {
await onUploadFile(file);
@@ -1447,6 +1484,7 @@ function MediaPanel({ media, canonImageRefs = [], primaryImageRef, missingMedia,
const onDrop = (e) => {
e.preventDefault();
+ if (readOnly) return;
setDragOver(false);
// In-app gallery DnD: the dragged tile carries its filename as text.
const key = (e.dataTransfer.getData('text/plain') || '').trim();
@@ -1487,7 +1525,7 @@ function MediaPanel({ media, canonImageRefs = [], primaryImageRef, missingMedia,
<h2 className="text-sm font-semibold text-white flex items-center gap-1.5">
<ImageIcon size={14} aria-hidden="true" /> Media
</h2>
- <div className="flex items-center gap-2 flex-wrap">
+ {!readOnly && <div className="flex items-center gap-2 flex-wrap">
<GenerateImageControl ingredientId={genIngredientId} name={genName} description={genDescription} universeId={genUniverseId} onComplete={onGenerated} />
<button type="button" onClick={() => setPickerOpen(true)}
className="inline-flex items-center gap-1 text-xs px-2 py-1 rounded border border-port-border text-gray-300 hover:text-white hover:border-port-accent">
@@ -1508,10 +1546,10 @@ function MediaPanel({ media, canonImageRefs = [], primaryImageRef, missingMedia,
<Square size={12} aria-hidden="true" /> Stop &amp; transcribe
</button>
)}
- </div>
+ </div>}
</div>
- <div
+ {!readOnly && <div
onDragOver={(e) => { e.preventDefault(); setDragOver(true); }}
onDragLeave={() => setDragOver(false)}
onDrop={onDrop}
@@ -1520,7 +1558,7 @@ function MediaPanel({ media, canonImageRefs = [], primaryImageRef, missingMedia,
{busy
? (<span className="inline-flex items-center gap-1"><Loader2 size={12} className="animate-spin" aria-hidden="true" /> Working…</span>)
: 'Drag a gallery image or a file here to attach it (image, audio, or video).'}
- </div>
+ </div>}
{portrait && (
<div className="mb-3">
@@ -1783,7 +1821,7 @@ function diffRevisionAgainstCurrent(revision, current, fields) {
return out;
}
-function RevisionsPanel({ revisions, current, fields, onRestore }) {
+function RevisionsPanel({ revisions, current, fields, onRestore, readOnly = false, retainedSourceId }) {
const [openId, setOpenId] = useState(null);
const [restoring, setRestoring] = useState(null);
const [pendingRestore, setPendingRestore] = useState(null);
@@ -1830,7 +1868,7 @@ function RevisionsPanel({ revisions, current, fields, onRestore }) {
{rev.actor && <span className="text-[10px] text-gray-500 truncate">· {rev.actor}</span>}
<span className="text-[10px] text-gray-500 whitespace-nowrap ml-auto">{timeAgo(rev.createdAt)}</span>
</button>
- {!isLatest && (
+ {!isLatest && !readOnly && !(retainedSourceId && rev.ingredientId === retainedSourceId) && (
pendingRestore === rev.id ? (
<ConfirmButtonPair
prompt="Replace current form?"
diff --git a/client/src/pages/CatalogIngredient.test.jsx b/client/src/pages/CatalogIngredient.test.jsx
index 0f3cefcfc6..c807a18b76 100644
--- a/client/src/pages/CatalogIngredient.test.jsx
+++ b/client/src/pages/CatalogIngredient.test.jsx
@@ -84,7 +84,10 @@ vi.mock('../services/socket', () => ({
},
}));
-vi.mock('../services/apiSystem', () => ({ generateImage: vi.fn() }));
+vi.mock('../services/apiSystem', () => ({ generateImage: vi.fn(), getSelfInstance: vi.fn(async () => ({ instanceId: 'canonical-owner' })), getInstances: vi.fn(async () => ({ peers: [{ instanceId: 'canonical-owner', host: 'canonical.example', port: 5555 }] })) }));
+vi.mock('../services/apiCatalogIdentity', () => ({
+ listCatalogIdentities: vi.fn(async () => ({ items: [], nextOffset: null })), getCatalogIdentity: vi.fn(), acceptCatalogIdentity: vi.fn(), abortCatalogIdentity: vi.fn(),
+}));
vi.mock('../services/apiCatalogTypes', () => ({
listCatalogTypes: vi.fn(async () => ({ types: [] })),
}));
@@ -138,6 +141,7 @@ import CatalogIngredient, { buildGenerationPromptSeed } from './CatalogIngredien
import CatalogRelatedImages from '../components/catalog/CatalogRelatedImages';
import { getCatalogIngredientDetails, listCatalogRelatedImages, unlinkCatalogIngredientRelation, updateCatalogIngredient, detachCatalogIngredientMedia, restoreCatalogIngredientRevision, uploadCatalogIngredientMediaFile } from '../services/apiCatalog';
import toast from '../components/ui/Toast';
+import { getCatalogIdentity, acceptCatalogIdentity, abortCatalogIdentity } from '../services/apiCatalogIdentity';
const renderPage = async (path = '/catalog/character/cat-chr-1') => {
const router = createMemoryRouter([
@@ -164,6 +168,79 @@ beforeEach(() => {
});
describe('CatalogIngredient — character sheet', () => {
+ it('aborts an uncommitted agreement without saving or discarding the existing creative draft', async () => {
+ const receipt = { id: 'example-abort-operation', sourceId: 'example-source', survivorId: CHAR_FIXTURE.id, localOwner: 'canonical-owner', sourceOwner: 'source-owner', survivorOwner: 'canonical-owner', state: 'proposed', planHash: 'example-hash',
+ plan: { sourceId: 'example-source', survivorId: CHAR_FIXTURE.id, sourceOwner: 'source-owner', survivorOwner: 'canonical-owner', source: { ingredients: [{ id: 'example-source', type: 'character', name: 'Original subject' }] }, survivor: { ingredients: [CHAR_FIXTURE] }, proposed: { name: CHAR_FIXTURE.name } } };
+ getCatalogIdentity.mockResolvedValue(receipt);
+ abortCatalogIdentity.mockResolvedValue({ ...receipt, state: 'aborted' });
+ await renderPage('/catalog/character/cat-chr-1?identityOperation=example-abort-operation');
+ fireEvent.change(screen.getByLabelText('Name', { exact: true }), { target: { value: 'Unsaved creative name' } });
+ fireEvent.click(await screen.findByRole('button', { name: 'Abort uncommitted proposal' }));
+ fireEvent.click(screen.getByRole('button', { name: 'Confirm coordinator abort' }));
+ await screen.findByText('Aborted · no canonical consolidation applied');
+ expect(screen.getByLabelText('Name', { exact: true })).toHaveValue('Unsaved creative name');
+ expect(updateCatalogIngredient).not.toHaveBeenCalled();
+ });
+
+ it('disables profile inputs for the duration of an owner acceptance so its refresh cannot discard newly typed edits', async () => {
+ const receipt = { id: 'example-pending-operation', sourceId: 'example-source', survivorId: CHAR_FIXTURE.id, localOwner: 'canonical-owner', sourceOwner: 'source-owner', survivorOwner: 'canonical-owner', state: 'proposed', planHash: 'example-hash',
+ plan: { sourceId: 'example-source', survivorId: CHAR_FIXTURE.id, sourceOwner: 'source-owner', survivorOwner: 'canonical-owner', source: { ingredients: [{ id: 'example-source', type: 'character', name: 'Original subject' }] }, survivor: { ingredients: [CHAR_FIXTURE] }, proposed: { name: CHAR_FIXTURE.name } } };
+ getCatalogIdentity.mockResolvedValue(receipt);
+ let finishAcceptance;
+ acceptCatalogIdentity.mockImplementationOnce(() => new Promise(resolve => { finishAcceptance = resolve; }));
+ await renderPage('/catalog/character/cat-chr-1?identityOperation=example-pending-operation');
+ fireEvent.click(await screen.findByRole('checkbox', { name: /I accept this exact reviewed plan/ }));
+ fireEvent.click(screen.getByRole('button', { name: 'Accept as this owner' }));
+ await waitFor(() => expect(acceptCatalogIdentity).toHaveBeenCalled());
+ expect(screen.getByLabelText('Name', { exact: true })).toBeDisabled();
+ expect(screen.getByRole('button', { name: 'Save', exact: true })).toBeDisabled();
+ getCatalogIngredientDetails.mockResolvedValue({ ...detailsOf(CHAR_FIXTURE), sharedIdentity: { ...receipt, operationId: receipt.id, writable: false, reason: 'CATALOG_IDENTITY_FENCED', state: 'prepared' } });
+ await act(async () => { finishAcceptance({ ...receipt, state: 'prepared' }); });
+ await screen.findByText(/This identity is reserved while the owners complete/);
+ expect(screen.getByLabelText('Name', { exact: true })).toBeDisabled();
+ expect(screen.getByLabelText('Name', { exact: true })).toHaveValue(CHAR_FIXTURE.name);
+ });
+
+ it('retains source-ID ownership restrictions after canonical resolution while keeping evidence and images inspectable', async () => {
+ getCatalogIngredientDetails.mockImplementation(async () => ({
+ ...detailsOf(CHAR_FIXTURE),
+ sharedIdentity: { operationId: 'shared-example', sourceId: 'retained-original', survivorId: CHAR_FIXTURE.id,
+ localOwner: 'source-owner', survivorOwner: 'canonical-owner', sourceOwner: 'source-owner', writable: false, reason: 'CATALOG_IDENTITY_RETAINED', state: 'committed' },
+ media: [{ ingredientId: 'retained-original', kind: 'reference', mediaKey: 'retained.png' }],
+ revisions: [{ id: 'latest', source: 'save', name: 'Current' }, { id: 'old', source: 'save', name: 'Old original' }],
+ }));
+ await renderPage('/catalog/character/retained-original');
+ expect(screen.getByRole('button', { name: 'Save', exact: true })).toBeDisabled();
+ expect(screen.getByRole('button', { name: 'Delete ingredient' })).toBeDisabled();
+ expect(screen.getByLabelText('Name', { exact: true })).toBeDisabled();
+ expect(screen.getByRole('button', { name: 'Add relation' })).toBeDisabled();
+ expect(screen.queryByRole('button', { name: 'Detach', exact: true })).not.toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: 'Restore', exact: true })).not.toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: /Pick from gallery|Upload file|Record memo/ })).not.toBeInTheDocument();
+ expect(await screen.findByRole('link', { name: 'Open canonical owner' })).toHaveAttribute('href', 'https://canonical.example:5555/casting/cat-chr-1');
+ fireEvent.click(screen.getByRole('button', { name: /Old original/ }));
+ expect(screen.getByRole('button', { name: /Old original/ })).toHaveAttribute('aria-expanded', 'true');
+ expect(screen.getByText(/Read-only provenance/)).toBeInTheDocument();
+ fireEvent.click(screen.getByRole('button', { name: 'Save', exact: true }));
+ expect(updateCatalogIngredient).not.toHaveBeenCalled();
+ });
+
+ it('keeps canonical editing available but retains source-only media and relations as immutable provenance', async () => {
+ getCatalogIngredientDetails.mockImplementation(async () => ({
+ ...detailsOf(CHAR_FIXTURE),
+ sharedIdentity: { operationId: 'shared-example', sourceId: 'retained-original', survivorId: CHAR_FIXTURE.id,
+ localOwner: 'canonical-owner', survivorOwner: 'canonical-owner', sourceOwner: 'source-owner', writable: true, state: 'committed' },
+ media: [{ ingredientId: 'retained-original', kind: 'reference', mediaKey: 'retained.png' }, { ingredientId: CHAR_FIXTURE.id, kind: 'reference', mediaKey: 'canonical.png' }],
+ relations: { outbound: [{ fromId: 'retained-original', toId: 'place-one', kind: 'lives_in', other: { id: 'place-one', name: 'Retained place', type: 'place' } }], inbound: [] },
+ }));
+ await renderPage();
+ expect(screen.getByRole('button', { name: 'Save', exact: true })).toBeEnabled();
+ expect(screen.getAllByRole('button', { name: 'Detach', exact: true })).toHaveLength(1);
+ expect(screen.queryByRole('button', { name: 'Remove relation to Retained place' })).not.toBeInTheDocument();
+ expect(screen.getByText('Retained source relation · read-only')).toBeInTheDocument();
+ expect(screen.getByRole('link', { name: /Retained place/ })).toBeInTheDocument();
+ });
+
it('reports a rejected file read and re-enables the upload control', async () => {
await renderPage();
const fileInput = document.querySelector('input[type="file"][accept="image/*,audio/*,video/*"]');
diff --git a/client/src/services/README.md b/client/src/services/README.md
index 564c51862a..8a2cdcfdcc 100644
--- a/client/src/services/README.md
+++ b/client/src/services/README.md
@@ -60,6 +60,7 @@ toasts on throw). **Custom catch ⇒ `silent: true`** — otherwise toasts fire
| `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), reference sheets (`listCatalogSheetVariants` / `previewCatalogSheet` / `renderCatalogSheet`), and local consolidation preview/apply/history/recovery. |
+| `apiCatalogIdentity.js` | Owner-coordinated shared identity preview, creation, import, acceptance, progress, abort and guarded 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/api.js b/client/src/services/api.js
index bf941b63de..0abcb96329 100644
--- a/client/src/services/api.js
+++ b/client/src/services/api.js
@@ -20,6 +20,7 @@ export * from './apiLogs.js';
export * from './apiCommands.js';
export * from './apiGit.js';
export * from './apiCatalog.js';
+export * from './apiCatalogIdentity.js';
export * from './apiCatalogTypes.js';
export * from './apiMedia.js';
export * from './apiImageTo3d.js';
diff --git a/client/src/services/apiCatalogIdentity.js b/client/src/services/apiCatalogIdentity.js
new file mode 100644
index 0000000000..c9c954d2ed
--- /dev/null
+++ b/client/src/services/apiCatalogIdentity.js
@@ -0,0 +1,15 @@
+import { request } from './apiCore.js';
+
+export const listCatalogIdentities = ({ ingredientId, limit = 10, offset = 0, ...options } = {}) => {
+ const params = new URLSearchParams({ limit: String(limit), offset: String(offset) });
+ if (ingredientId) params.set('ingredientId', ingredientId);
+ return request(`/catalog/identity?${params}`, options);
+};
+export const getCatalogIdentity = (id, options) => request(`/catalog/identity/${encodeURIComponent(id)}`, options);
+export const previewCatalogIdentity = (body, options) => request('/catalog/identity/preview', { method: 'POST', body: JSON.stringify(body), ...options });
+export const createCatalogIdentity = (body, options) => request('/catalog/identity/create', { method: 'POST', body: JSON.stringify(body), ...options });
+export const importCatalogIdentity = (body, options) => request('/catalog/identity/import', { method: 'POST', body: JSON.stringify(body), ...options });
+export const acceptCatalogIdentity = (id, planHash, options) => request(`/catalog/identity/${encodeURIComponent(id)}/accept`, { method: 'POST', body: JSON.stringify({ planHash }), ...options });
+export const advanceCatalogIdentity = (id, options) => request(`/catalog/identity/${encodeURIComponent(id)}/advance`, { method: 'POST', body: JSON.stringify({}), ...options });
+export const abortCatalogIdentity = (id, options) => request(`/catalog/identity/${encodeURIComponent(id)}/abort`, { method: 'POST', body: JSON.stringify({}), ...options });
+export const recoverCatalogIdentity = (id, planHash, options) => request(`/catalog/identity/${encodeURIComponent(id)}/recover`, { method: 'POST', body: JSON.stringify({ planHash }), ...options });
diff --git a/docs/CATALOG_SHARED_IDENTITY.md b/docs/CATALOG_SHARED_IDENTITY.md
new file mode 100644
index 0000000000..e3c1595e0c
--- /dev/null
+++ b/docs/CATALOG_SHARED_IDENTITY.md
@@ -0,0 +1,113 @@
+# Shared canonical catalog identity
+
+A shared identity agreement consolidates two same-type ingredients on their two
+owning instances. The selected survivor keeps its existing ID and owner. The
+source ID remains resolvable, and original histories, source links, references,
+attachments and provenance remain available through the operation receipt.
+
+This differs from [local consolidation](CATALOG_LOCAL_MERGE.md), which requires
+both records to belong to one instance. A shared agreement never transfers
+ownership or creates an owner acceptance on behalf of a peer.
+
+## Requirements
+
+Both owners need compatible code, an existing authenticated pairing and enabled
+catalog sharing in the required directions. An authorized operator on each owner
+must review and accept the same plan. A delegated local agent retains its normal
+operator authority. A paired peer credential is not operator acceptance.
+
+Both authoritative ingredient records must already be unlocked. Preparation,
+commit and recovery do not unlock records or enqueue generation. Deploying the
+code and applying an agreement are separate operator actions.
+
+Initial support covers exactly the two owners. Other and older peers keep their
+original-ID records and ordinary sync behavior. A forwarded receipt cannot prove
+a third owner's consent.
+
+## Operator workflow
+
+The survivor owner is the coordinator. Select the pair and survivor, preview the
+proposed content, resolve every differing populated scalar and create the
+reviewed operation. The plan binds both authoritative snapshots, owners,
+identities and field choices. Changed evidence requires a new preview.
+
+Import the operation on the source owner through its existing coordinator peer.
+Each owner explicitly accepts the same plan hash. Acceptance reserves the
+affected records and associations against concurrent changes. On the coordinator,
+advance verifies the source's prepared receipt and atomically records the commit
+decision with the canonical content. Advance on the source adopts the verified
+decision and activates its canonical read resolution.
+
+A coordinator commit is not proof that the other owner has adopted it. The UI
+shows the local phase and last verified peer phase separately. If a request times
+out, inspect or advance the same operation; do not create a replacement operation
+to work around an uncertain result. Creation retries reuse the same attempt ID.
+A new attempt after a confirmed abort has its own ID, even if the content is unchanged.
+
+## Offline peers and interruption
+
+A prepared source cannot unilaterally cancel. It needs the coordinator's durable
+abort or commit decision. This preserves correctness if the coordinator committed
+but its response was lost. An offline owner can therefore leave the operation
+pending and protected until communication resumes. Restarting does not release
+the reservation.
+
+The coordinator may abort an operation before commitment, even if its peer is
+offline or the pairing is disabled. An unaccepted source may decline its proposal.
+The source adopts a coordinator abort through advance once communication is
+available. No timeout or expiry silently releases prepared records.
+Do not edit database receipts, disable triggers or rewrite ownership to bypass a
+pending operation.
+
+## Editing and refreshing canon
+
+After commitment, canonical edits use the survivor's explicit ID on its owner.
+Writes through the retained source ID are refused with a canonical-owner pointer.
+This includes delayed media attachments; generation checks the destination before
+enqueueing work. The original source and its evidence remain preserved.
+
+The source instance's canonical projection is refreshed by advancing the same
+operation, which reads directly authenticated owner state. Generic catalog
+last-write-wins updates cannot overwrite the protected pair. A stale or offline
+projection remains identified as such rather than being presented as current
+owner evidence. Media references do not guarantee that the image bytes exist on
+the receiving instance; ordinary missing-asset indicators remain meaningful.
+
+During preparation or recovery, a protected incoming row holds that catalog
+stream's sync cursor. Normal enabled sync retries it after the reservation ends,
+including after a restart. This can delay that stream while the agreement is
+pending; it prevents updates in the cancellation/recovery window from being lost.
+
+Embedded canon keeps its stable ingredient IDs. A retained source canon snapshot
+cannot overwrite the survivor. User exports include retained evidence with its
+original identities and provenance; ordinary federation feeds keep their raw rows.
+Source links and spans remain exportable even when the linked raw scrap is not
+available locally; an agreement does not fetch or invent that remote source text.
+Existing project and universe payloads remain contextual snapshots: consolidation
+does not rewrite them or refresh a foreign-owned universe. Catalog-aware reads,
+casting lookups and sheets resolve the current identity. A renderer that consumes
+an embedded project snapshot directly continues to use that preserved creative
+context; it is not evidence that the canonical catalog record was changed back.
+
+## Recovery
+
+Start recovery on the coordinator, then prepare it on the source and advance the
+same operation on the coordinator and source. Recovery requires the exact applied
+state to remain unchanged. Later edits, attachments, revisions or lock changes
+make recovery refuse instead of overwriting work. There is no force option.
+
+Recovery has its own durable decision and monotonic phase. A delayed old commit
+cannot reactivate a recovered identity. Originals and receipts remain available;
+recovery does not erase audit history or delete media files.
+
+## Deployment and validation
+
+The feature adds boot schema, owner-scoped reservations and read projections,
+server protocol endpoints and client controls. It needs an authorized server/client
+deployment and restart. Boot does not accept, commit or recover an agreement.
+
+The design record is
+[owner-coordinated catalog identity](plans/2026-10-18-catalog-shared-canonical-identity.md).
+Persisted tests exercise stale plans, concurrent writes, authenticated owners,
+retry and restart behavior, unavailable peers, canonical reads, preserved exports
+and guarded recovery.
diff --git a/docs/README.md b/docs/README.md
index 3672e6013f..070b691451 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -14,6 +14,7 @@ Index of everything under `docs/`. Start with the [root README](../README.md) fo
| [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 |
+| [CATALOG_SHARED_IDENTITY.md](./CATALOG_SHARED_IDENTITY.md) | Two-owner canonical identity agreements, preparation, adoption, owner refresh, and coordinated 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/docs/plans/2026-10-18-catalog-shared-canonical-identity.md b/docs/plans/2026-10-18-catalog-shared-canonical-identity.md
new file mode 100644
index 0000000000..a4c286b33a
--- /dev/null
+++ b/docs/plans/2026-10-18-catalog-shared-canonical-identity.md
@@ -0,0 +1,84 @@
+# Owner-coordinated catalog identity
+
+## Scope
+
+Consolidate two same-type catalog ingredients owned by two different paired
+instances into one selected canonical identity on those two instances. The
+survivor retains its existing owner and ID. The source retains its original ID,
+owner, complete reviewed history and assets. This is not ownership transfer or
+a presentation-only grouping. Other peers retain their ordinary original-ID
+records until they support an independently authorized identity agreement.
+
+No deployment, remote host access, record unlock, generation or live agreement
+is implied by implementing this protocol.
+
+## Reviewed protocol
+
+The survivor owner coordinates a durable operation. A plan binds the operation
+ID, protocol version, both record IDs and owners, reviewed authoritative
+snapshots, explicit populated-field choices and proposed canonical content.
+Portable snapshot fingerprints exclude transport sequence counters while
+including content, lock state, owner revision identities, references, source
+links, relations and media provenance. Oversized evidence is refused, never
+silently truncated.
+
+Each owner accepts the exact plan through its existing local operator authority.
+Acceptance rechecks its authoritative state and atomically persists a reservation
+that fences both ingredient and subordinate writes. Both content records must
+already be explicitly unlocked. Peer credentials can read authenticated protocol
+evidence; they cannot create operator acceptance.
+
+The coordinator verifies the source owner's prepared receipt and commits its
+canonical content and immutable decision in one database transaction. The source
+owner adopts that verified decision and activates canonical resolution. No
+cross-machine atomicity is claimed: a committed operation can await peer adoption.
+Prepared participants remain reserved during outages; the source cannot cancel
+unilaterally after preparation. A durable coordinator abort resolves an uncommitted
+reservation. Retries reuse the same operation and are idempotent.
+
+Peer responses bind a fresh challenge, operation, plan hash, protocol version,
+requester and responder identities. Existing paired authentication is required;
+legacy Basic fallback and self-asserted instance headers are insufficient.
+Existing enabled catalog sharing and direction controls are enforced. Pair
+changes invalidate an in-flight exchange. Bilateral evidence is not transitive
+authority for a third peer.
+
+## Identity and ongoing changes
+
+Canonical read resolution is separate from write resolution. Original IDs keep
+working in links, canon references, catalog queries, casting and media views.
+Histories and attachment provenance retain their original identities. Ordinary
+exports and catalog feeds retain original IDs and owners.
+
+Only the canonical owner may modify canonical content after commitment. A source
+instance must refuse an old-ID edit, upload or queued attachment that would write
+to a foreign canonical projection. Generation is refused before spending work
+when its attachment destination cannot be written. Database fences provide the
+second check for delayed callbacks and direct subordinate mutations.
+
+Generic last-write-wins catalog sync is not owner proof and cannot overwrite
+protected identities. The participating source instance refreshes canonical
+content through an explicit, directly owner-verified protocol operation. Retained
+source canon cannot overwrite the survivor, and consolidation does not rewrite
+foreign universe caches or embedded stable IDs.
+
+## Recovery
+
+Recovery is another bilateral decision over the exact applied state. Both owners
+prepare recovery; the coordinator records the durable recovery decision before
+the source adopts it. It restores only this operation's effects, keeps original
+assets and audit receipts, and refuses to overwrite later content, attachments,
+history or locks. Monotonic state prevents a delayed old commit from reactivating
+a recovered alias. Interrupted operations remain inspectable and resumable.
+
+## Validation
+
+Persisted tests cover acceptance races, concurrent association inserts, both
+relation endpoints, retries and restarts, offline/ambiguous peers, wrong-owner and
+third-peer requests, authentication-disabled installations, locks, stale plans,
+recovery after later changes, owner refresh, old-ID references, search/facets,
+member-attributed history/media, canon projection and original-ID export.
+
+Independent design review accepted this bounded protocol with the reservation,
+owner-authentication, complete-fencing, explicit-refresh and guarded-recovery
+requirements above. Implementation review and exact-head checks remain required.
diff --git a/scripts/lib/dbTestFiles.js b/scripts/lib/dbTestFiles.js
index c5744bc6ba..0936560678 100644
--- a/scripts/lib/dbTestFiles.js
+++ b/scripts/lib/dbTestFiles.js
@@ -10,6 +10,8 @@ import { posix } from 'node:path';
*/
export const DB_TEST_INCLUDE = [
'services/catalogDB.merge.db.test.js',
+ 'services/catalogIdentity/protocol.db.test.js',
+ 'services/catalogDB.identityIntegration.db.test.js',
'services/trackAlbumMembership.db.test.js',
'services/stackerNews.db.test.js',
'services/peerExecutionLedger.db.test.js',
diff --git a/server/lib/README.md b/server/lib/README.md
index d7d7a5d355..1d09969544 100644
--- a/server/lib/README.md
+++ b/server/lib/README.md
@@ -124,6 +124,7 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub
| `appleHealthPoints.js` | `healthPointOrigin` and `healthPointKey`: legacy-aware importer/source identity shared by health ingestion and daily source selection. |
| `brainValidation.js` | Brain/memory route schemas (search, ingest, edit). |
| `catalogExtractionDraft.js` | Extraction-only six-type graph schema, strict grounded-output parsing, and conservative chunk identity/edge reconciliation. |
+| `catalogIdentityValidation.js` | Bilateral canonical catalog identity operator and peer evidence schemas. |
| `catalogValidation.js` | Creative ingredients catalog route schemas (scraps, ingredients, links, relations, tags, revisions, sync envelope). |
| `cosValidation.js` | Chief-of-Staff task/job/loop/learning schemas, the Code-Review settings slice, and the task-metadata sanitizer. `createCosTaskSchema`'s metadata-bound fields are carried onto the task by `services/cosTaskIntake.js` (parity-checked by its test). The Review-Loop reviewer vocabulary lives in `reviewerConfig.js` (#5702) and is re-exported flat from here. |
| `creativeBriefLimits.js` | `COMMISSION_NAME_MAX` / `COMMISSION_INTENT_MAX` / `COMMISSION_STYLE_SPEC_MAX` / `COMMISSION_BRIEF_TAG_MAX` and `CREATIVE_DIRECTOR_GOAL_MAX` — the creative brief caps `creativeCommissionValidation.js` and `creativeDirectorValidation.js` enforce and the browser forms use as a silent input `maxLength`. A pure leaf (the schemas pull `zod`) so `client/src/components/creative-commission/commissionForm.js` and `client/src/lib/creativeDirectorPlan.js` re-export one definition instead of copying the numbers. |
diff --git a/server/lib/apiAccessPolicy.js b/server/lib/apiAccessPolicy.js
index 2fbe2c83a9..deaddd0e3d 100644
--- a/server/lib/apiAccessPolicy.js
+++ b/server/lib/apiAccessPolicy.js
@@ -44,6 +44,8 @@ export const PEER_API_SURFACE = Object.freeze([
{ path: '/api/brain/reconcile/manifest', methods: READ },
{ path: '/api/memory/sync', methods: READ },
{ path: '/api/catalog/sync', methods: READ },
+ { path: '/api/catalog/identity/peer/snapshot', methods: READ },
+ { path: '/api/catalog/identity/peer/status', methods: READ },
{ prefix: '/api/sync/', methods: READ },
// Record push/pull (sharing/*): reads, plus the one inbound push.
{ prefix: '/api/peer-sync/', methods: READ },
diff --git a/server/lib/catalogIdentityValidation.js b/server/lib/catalogIdentityValidation.js
new file mode 100644
index 0000000000..073ee1cc9e
--- /dev/null
+++ b/server/lib/catalogIdentityValidation.js
@@ -0,0 +1,13 @@
+import { z } from 'zod';
+const id = z.string().min(1).max(160);
+const digest = z.string().regex(/^[a-f0-9]{64}$/);
+export const identityPreviewSchema = z.object({ operationId: z.string().uuid(), sourceId: id, survivorId: id,
+ fieldChoices: z.record(z.string().max(500), z.enum(['source', 'survivor'])).default({}) }).strict();
+export const identityCreateSchema = identityPreviewSchema.extend({ planHash: digest });
+export const identityImportSchema = z.object({ peerId: id, operationId: id }).strict();
+export const identityAcceptSchema = z.object({ planHash: digest }).strict();
+export const identityEmptySchema = z.object({}).strict();
+export const identitySnapshotQuerySchema = z.object({ ingredientId: id, challenge: digest }).strict();
+export const identityStatusQuerySchema = z.object({ operationId: id, challenge: digest }).strict();
+
+export const identityListQuerySchema = z.object({ ingredientId: id.optional(), limit: z.coerce.number().int().min(1).max(50).default(20), offset: z.coerce.number().int().min(0).max(100000).default(0) }).strict();
diff --git a/server/lib/db.ddlParity.test.js b/server/lib/db.ddlParity.test.js
index 4cc0017edd..446e48d154 100644
--- a/server/lib/db.ddlParity.test.js
+++ b/server/lib/db.ddlParity.test.js
@@ -27,6 +27,7 @@ import { describe, it, expect } from 'vitest';
import { FTS_PAYLOAD_FIELDS } from './catalogTypes.js';
import { syncFeedDdl, syncFeedTables, buildSyncFeedTriggers } from './db/schema/syncFeed.js';
import { memorySearchDdl } from './db/schema/core.js';
+import { catalogIdentityDdl } from './db/schema/catalogIdentity.js';
import { readFileSync, readdirSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';
@@ -41,6 +42,8 @@ const INIT_SQL = readFileSync(join(HERE, '..', 'scripts', 'init-db.sql'), 'utf8'
const SCHEMA_DIR = join(HERE, 'db', 'schema');
const DB_JS = [
readFileSync(join(HERE, 'db.js'), 'utf8'),
+ // Expand generated member triggers so parity checks their actual table targets.
+ catalogIdentityDdl.join(';\n'),
...readdirSync(SCHEMA_DIR)
.filter((f) => f.endsWith('.js') && !f.endsWith('.test.js'))
.map((f) => readFileSync(join(SCHEMA_DIR, f), 'utf8')),
diff --git a/server/lib/db/schema/README.md b/server/lib/db/schema/README.md
index 58ceeab5c4..c855c3d8a9 100644
--- a/server/lib/db/schema/README.md
+++ b/server/lib/db/schema/README.md
@@ -34,6 +34,8 @@ init-db.sql, each with a one-line reason.
| `aiGraph.js` | `aiGraphDdl` | AI provider connection graph — connections, harness bindings, executable route bindings (machine-local) |
| `peerExecution.js` | `peerExecutionDdl` | Receiver-local permanent execution consumption and generation floors; no grants or federation |
| `catalog.js` | `catalogDdl`, `catalogUserTypesDdl`, `catalogPendingAppliesDdl` | Catalog scraps/ingredients/tags/media + user-defined types + receiver-local dependency inbox |
+| `catalogIdentity.js` | `catalogIdentityDdl` | Owner-coordinated identity receipts, durable mutation fences and canonical lookup functions |
+| `catalogIdentityViews.js` | `buildCatalogIdentityViewsDdl()` | Read-only association and revision unions retaining authoritative owner evidence |
| `media.js` | `mediaDdl` | Creative-director / music-video projects, mood boards, media assets, and Code Animation jobs |
| `universes.js` | `universesDdl` | Universes, machine-local character voice profiles/renders, + universe run history |
| `library.js` | `libraryDdl` | Authors, artists, albums, tracks |
diff --git a/server/lib/db/schema/catalogIdentity.js b/server/lib/db/schema/catalogIdentity.js
new file mode 100644
index 0000000000..55889f278f
--- /dev/null
+++ b/server/lib/db/schema/catalogIdentity.js
@@ -0,0 +1,74 @@
+// Bilateral receipts are local protocol state, not ordinary LWW catalog rows.
+export const catalogIdentityDdl = [
+ `CREATE TABLE IF NOT EXISTS catalog_identity_operations (
+ id TEXT PRIMARY KEY,
+ source_id TEXT NOT NULL REFERENCES catalog_ingredients(id),
+ survivor_id TEXT NOT NULL REFERENCES catalog_ingredients(id),
+ source_owner TEXT NOT NULL,
+ survivor_owner TEXT NOT NULL,
+ local_owner TEXT NOT NULL,
+ state TEXT NOT NULL CHECK (state IN ('proposed', 'prepared', 'committed', 'aborted', 'recovery_prepared', 'recovered')),
+ epoch INTEGER NOT NULL DEFAULT 0,
+ plan JSONB NOT NULL,
+ plan_hash TEXT NOT NULL,
+ before_state JSONB,
+ applied_fingerprint TEXT,
+ current_snapshot JSONB,
+ recovery JSONB,
+ peer_state TEXT,
+ peer_observed_at TIMESTAMPTZ,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ CHECK (source_id <> survivor_id),
+ CHECK (source_owner <> survivor_owner),
+ CHECK (local_owner IN (source_owner, survivor_owner))
+ )`,
+ `CREATE INDEX IF NOT EXISTS idx_catalog_identity_source ON catalog_identity_operations(source_id)`,
+ `CREATE INDEX IF NOT EXISTS idx_catalog_identity_survivor ON catalog_identity_operations(survivor_id)`,
+ `CREATE OR REPLACE FUNCTION catalog_canonical_ingredient_id(requested_id TEXT)
+ RETURNS TEXT LANGUAGE SQL STABLE AS $$
+ SELECT catalog_resolve_ingredient_id(COALESCE((SELECT survivor_id FROM catalog_identity_operations
+ WHERE source_id = requested_id AND state IN ('committed', 'recovery_prepared')), requested_id))
+ $$`,
+ `CREATE OR REPLACE FUNCTION catalog_identity_member_ids(requested_id TEXT)
+ RETURNS TEXT[] LANGUAGE SQL STABLE AS $$
+ SELECT ARRAY(SELECT DISTINCT member FROM (
+ SELECT catalog_canonical_ingredient_id(requested_id) AS member
+ UNION ALL SELECT source_id FROM catalog_identity_operations
+ WHERE survivor_id = catalog_canonical_ingredient_id(requested_id) AND state IN ('committed', 'recovery_prepared')
+ UNION ALL SELECT source_id FROM catalog_ingredient_merges
+ WHERE survivor_id = catalog_canonical_ingredient_id(requested_id) AND restored_at IS NULL
+ ) members)
+ $$`,
+ `CREATE OR REPLACE FUNCTION guard_catalog_identity_member()
+ RETURNS TRIGGER LANGUAGE plpgsql AS $$
+ DECLARE touched TEXT[]; old_row JSONB; new_row JSONB; operation RECORD;
+ BEGIN
+ IF TG_OP <> 'INSERT' THEN old_row := to_jsonb(OLD); END IF;
+ IF TG_OP <> 'DELETE' THEN new_row := to_jsonb(NEW); END IF;
+ touched := ARRAY[old_row->>'id', new_row->>'id', old_row->>'ingredient_id', new_row->>'ingredient_id',
+ old_row->>'from_id', new_row->>'from_id', old_row->>'to_id', new_row->>'to_id'];
+ FOR operation IN SELECT * FROM catalog_identity_operations
+ WHERE state IN ('prepared', 'committed', 'recovery_prepared')
+ AND (source_id = ANY(touched) OR survivor_id = ANY(touched)) LOOP
+ IF current_setting('portos.catalog_identity_operation', true) IS DISTINCT FROM operation.id THEN
+ IF current_setting('portos.catalog_identity_peer_apply', true) = 'on'
+ OR operation.state IN ('prepared', 'recovery_prepared') OR operation.source_id = ANY(touched)
+ OR operation.local_owner <> operation.survivor_owner
+ OR (TG_TABLE_NAME = 'catalog_ingredients' AND
+ (TG_OP = 'DELETE' OR (new_row->>'deleted')::boolean OR new_row->>'origin_instance_id' IS DISTINCT FROM operation.survivor_owner
+ OR new_row->>'type' IS DISTINCT FROM old_row->>'type')) THEN
+ RAISE EXCEPTION 'Shared canonical identity is protected; use its owner protocol' USING ERRCODE = 'P0001';
+ END IF;
+ END IF;
+ END LOOP;
+ IF TG_OP = 'DELETE' THEN RETURN OLD; END IF;
+ RETURN NEW;
+ END $$`,
+ ...['catalog_ingredients', 'catalog_ingredient_sources', 'catalog_ingredient_refs', 'catalog_ingredient_media',
+ 'catalog_ingredient_relations', 'catalog_ingredient_revisions'].flatMap(table => [
+ `DROP TRIGGER IF EXISTS trg_catalog_identity_member ON ${table}`,
+ `CREATE TRIGGER trg_catalog_identity_member BEFORE INSERT OR UPDATE OR DELETE ON ${table}
+ FOR EACH ROW EXECUTE FUNCTION guard_catalog_identity_member()`,
+ ]),
+];
diff --git a/server/lib/db/schema/catalogIdentityViews.js b/server/lib/db/schema/catalogIdentityViews.js
new file mode 100644
index 0000000000..2b63da6525
--- /dev/null
+++ b/server/lib/db/schema/catalogIdentityViews.js
@@ -0,0 +1,45 @@
+// Read-only views retain owner-reviewed evidence without rewriting foreign rows.
+// Source snapshots remain authoritative. A survivor's live rows (including
+// tombstones) take precedence over its retained pre-consolidation evidence.
+const ASSOCIATIONS = {
+ sources: ['catalog_ingredient_sources', ['ingredient_id', 'scrap_id']],
+ refs: ['catalog_ingredient_refs', ['ingredient_id', 'ref_kind', 'ref_id', 'role']],
+ media: ['catalog_ingredient_media', ['ingredient_id', 'media_key', 'kind']],
+ relations: ['catalog_ingredient_relations', ['from_id', 'to_id', 'kind']],
+ revisions: ['catalog_ingredient_revisions', ['id']],
+};
+
+export const buildCatalogIdentityViewsDdl = () => Object.entries(ASSOCIATIONS).map(([kind, [table, keys]]) => {
+ const sourceMatch = kind === 'relations'
+ ? '(live.from_id = o.source_id OR live.to_id = o.source_id)'
+ : 'live.ingredient_id = o.source_id';
+ const remoteSurvivorMatch = kind === 'relations'
+ ? '(live.from_id = o.survivor_id OR live.to_id = o.survivor_id)'
+ : 'live.ingredient_id = o.survivor_id';
+ const keySql = keys.map(key => `(r).${key}`).join(', ');
+ const localAliasFilter = kind === 'relations'
+ ? 'AND live.from_id = catalog_resolve_ingredient_id(live.from_id) AND live.to_id = catalog_resolve_ingredient_id(live.to_id)'
+ : ['refs', 'media'].includes(kind) ? 'AND live.ingredient_id = catalog_resolve_ingredient_id(live.ingredient_id)' : '';
+ return `CREATE OR REPLACE VIEW catalog_identity_read_${kind} AS
+ WITH active AS (SELECT * FROM catalog_identity_operations WHERE state IN ('committed', 'recovery_prepared')),
+ candidates AS (
+ SELECT jsonb_populate_record(NULL::${table}, item) AS r, 0 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.plan->'source'->'${kind}', '[]'::jsonb)) item
+ UNION ALL
+ SELECT live AS r, 1 AS priority FROM ${table} live
+ WHERE NOT EXISTS (SELECT 1 FROM active o WHERE ${sourceMatch}
+ OR (o.local_owner <> o.survivor_owner AND ${remoteSurvivorMatch}))
+ ${localAliasFilter}
+ UNION ALL
+ SELECT jsonb_populate_record(NULL::${table}, item) AS r, 2 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.current_snapshot->'${kind}', o.plan->'survivor'->'${kind}', '[]'::jsonb)) item
+ ${kind === 'revisions' ? '' : 'WHERE o.local_owner <> o.survivor_owner'}
+ ${kind === 'revisions' ? `UNION ALL
+ SELECT jsonb_populate_record(NULL::${table}, item) AS r, 3 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.plan->'survivor'->'revisions', '[]'::jsonb)) item` : ''}
+ ${kind === 'media' ? `UNION ALL
+ SELECT jsonb_populate_record(NULL::${table}, item) AS r, 4 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.plan->'archivedMedia', '[]'::jsonb)) item` : ''}
+ ) SELECT DISTINCT ON (${keySql}) (r).*, priority IN (0, 3, 4) AS identity_retained
+ FROM candidates ORDER BY ${keySql}, priority`;
+});
diff --git a/server/lib/db/schema/index.js b/server/lib/db/schema/index.js
index 154f63596a..e9b36e2280 100644
--- a/server/lib/db/schema/index.js
+++ b/server/lib/db/schema/index.js
@@ -24,6 +24,8 @@ import { cosAgentFeedbackDdl } from './cosAgentFeedback.js';
import { aiGraphDdl } from './aiGraph.js';
import { peerExecutionDdl } from './peerExecution.js';
import { catalogDdl, catalogUserTypesDdl, catalogPendingAppliesDdl } from './catalog.js';
+import { catalogIdentityDdl } from './catalogIdentity.js';
+import { buildCatalogIdentityViewsDdl } from './catalogIdentityViews.js';
import { mediaDdl } from './media.js';
import { universesDdl } from './universes.js';
import { libraryDdl } from './library.js';
@@ -51,6 +53,8 @@ export {
aiGraphDdl,
peerExecutionDdl,
catalogDdl,
+ catalogIdentityDdl,
+ buildCatalogIdentityViewsDdl,
catalogUserTypesDdl,
catalogPendingAppliesDdl,
mediaDdl,
@@ -101,6 +105,8 @@ export function buildUpgradeDdl() {
export function buildCatalogDdl() {
return [
...catalogDdl,
+ ...catalogIdentityDdl,
+ ...buildCatalogIdentityViewsDdl(),
...mediaDdl,
...catalogUserTypesDdl,
...universesDdl,
diff --git a/server/lib/db/schema/schema.test.js b/server/lib/db/schema/schema.test.js
index 6a3b7af282..a07d80b724 100644
--- a/server/lib/db/schema/schema.test.js
+++ b/server/lib/db/schema/schema.test.js
@@ -26,7 +26,7 @@ import {
const DOMAIN_ARRAYS = [
'coreDdl', 'tribeDdl', 'humanActivityDdl', 'postDdl', 'commissionsDdl', 'userActionsDdl', 'reviewQueueTriageDdl', 'cosAgentFeedbackDdl', 'aiGraphDdl', 'peerExecutionDdl',
- 'catalogDdl', 'catalogUserTypesDdl', 'mediaDdl', 'universesDdl',
+ 'catalogDdl', 'catalogIdentityDdl', 'catalogUserTypesDdl', 'mediaDdl', 'universesDdl',
'libraryDdl', 'pipelineDdl', 'writersRoomDdl', 'loraDdl', 'privacyDdl', 'stackerNewsDdl', 'xDdl',
'beeperDdl', 'mindToolRecipesDdl',
'auditDdl', 'syncFeedDdl',
@@ -59,6 +59,8 @@ describe('db/schema barrel + composer (#2832)', () => {
it('buildCatalogDdl composes the phase-2 modules in order, with catalog_user_types after media', () => {
const expected = [
...schema.catalogDdl,
+ ...schema.catalogIdentityDdl,
+ ...schema.buildCatalogIdentityViewsDdl(),
...schema.mediaDdl,
...schema.catalogUserTypesDdl,
...schema.universesDdl,
diff --git a/server/lib/index.js b/server/lib/index.js
index 7c1a3bc8b6..753236f67b 100644
--- a/server/lib/index.js
+++ b/server/lib/index.js
@@ -36,6 +36,7 @@ export * from './appleHealthPoints.js';
export * as brainValidation from './brainValidation.js';
export * from './brainThreads.js';
export * from './humanActions.js';
+export * as catalogIdentityValidation from './catalogIdentityValidation.js';
export * as catalogValidation from './catalogValidation.js';
export * as characterAugmentValidation from './characterAugmentValidation.js';
export * as characterEvolutionValidation from './characterEvolutionValidation.js';
diff --git a/server/lib/socketEventContracts.js b/server/lib/socketEventContracts.js
index bca18e75ae..e98750952a 100644
--- a/server/lib/socketEventContracts.js
+++ b/server/lib/socketEventContracts.js
@@ -404,6 +404,12 @@ export const SOCKET_EVENT_CONTRACTS = Object.freeze({
summary: 'Release readiness observation; the last subscriber stops the observer.',
payloadSchema: { type: 'object', properties: {}, additionalProperties: false },
},
+ 'catalog:identity-changed': {
+ direction: 'server-to-client',
+ summary: 'Invalidate matching catalog identity receipt and detail views after a durable local change.',
+ payloadSchema: { type: 'object', properties: { operationId: { type: 'string' }, sourceId: { type: 'string' }, survivorId: { type: 'string' } },
+ required: ['operationId', 'sourceId', 'survivorId'], additionalProperties: false },
+ },
'code-animation:changed': {
direction: 'server-to-client',
summary: 'Invalidate bounded Code Animation job/project galleries and matching details after a durable change.',
diff --git a/server/routes/catalog.js b/server/routes/catalog.js
index e052e90bae..3ca2d3b082 100644
--- a/server/routes/catalog.js
+++ b/server/routes/catalog.js
@@ -1,3 +1,4 @@
+import { getCatalogIdentityAccess } from '../services/catalogDB/identityAccess.js';
// Creative Ingredients Catalog HTTP routes, mounted at /api/catalog. Backs
// the Catalog page, Ingest workflow, picker integrations, and peer sync.
@@ -57,7 +58,10 @@ import { migrateBibleToCatalog } from '../scripts/migrateBibleToCatalog.js';
import { previewCatalogCastImport, commitCatalogCastImport } from '../services/musicVideo/catalogCast.js';
import { PORTOS_SCHEMA_VERSIONS } from '../lib/schemaVersions.js';
+import catalogIdentityRouter from './catalogIdentity.js';
+
const router = Router();
+router.use('/identity', catalogIdentityRouter);
router.get('/stats', asyncHandler(async (req, res) => {
res.json(await catalogDB.getCatalogStats());
@@ -270,7 +274,7 @@ router.get('/ingredients/:id', asyncHandler(async (req, res) => {
router.get('/ingredients/:id/details', asyncHandler(async (req, res) => {
const ing = await catalogDB.getIngredient(req.params.id);
if (!ing) throw new ServerError('Ingredient not found', { status: 404 });
- const [refs, sources, relations, revisions, media, missingMedia] = await Promise.all([
+ const [refs, sources, relations, revisions, media, missingMedia, sharedIdentity] = await Promise.all([
// Live refs only (#1812): the detail page's "Appears in" panel must not
// render a chip deep-linking to a soft-deleted universe/series/CD target.
// The orphan stays recoverable via the Catalog "Orphaned" album.
@@ -280,6 +284,7 @@ router.get('/ingredients/:id/details', asyncHandler(async (req, res) => {
catalogDB.listIngredientRevisions(req.params.id, { limit: 50 }),
catalogDB.listMediaForIngredient(req.params.id),
catalogDB.getMissingMediaForIngredient(req.params.id),
+ getCatalogIdentityAccess(req.params.id),
]);
// "From the same source" (#7617): sibling ingredients extracted from each of
// THIS ingredient's source scraps, batched in one query so the detail page
@@ -296,6 +301,7 @@ router.get('/ingredients/:id/details', asyncHandler(async (req, res) => {
const { embedding, ...rest } = ing;
res.json({
ingredient: includeEmbedding ? { ...rest, embedding } : rest,
+ sharedIdentity,
refs,
sources: sourcesWithSiblings,
relations, // { outbound, inbound }
diff --git a/server/routes/catalogIdentity.js b/server/routes/catalogIdentity.js
new file mode 100644
index 0000000000..dec62342ec
--- /dev/null
+++ b/server/routes/catalogIdentity.js
@@ -0,0 +1,72 @@
+import { Router } from 'express';
+import { asyncHandler, ServerError } from '../lib/errorHandler.js';
+import { validateRequest } from '../lib/validation.js';
+import { requireHostControl } from '../services/authGate.js';
+import { identityPreviewSchema, identityCreateSchema, identityImportSchema, identityAcceptSchema,
+ identityEmptySchema, identitySnapshotQuerySchema, identityStatusQuerySchema, identityListQuerySchema } from '../lib/catalogIdentityValidation.js';
+import * as identity from '../services/catalogIdentity/index.js';
+import { authenticateIdentityPeer, signEvidence, localIdentity } from '../services/catalogIdentity/transport.js';
+import { catalogIdentityEvents } from '../services/catalogIdentity/events.js';
+
+const router = Router();
+router.get('/peer/snapshot', asyncHandler(async (req, res) => {
+ const params = validateRequest(identitySnapshotQuerySchema, req.query);
+ const peer = await authenticateIdentityPeer(req);
+ const owner = await localIdentity();
+ const value = await identity.ownerSnapshot(params.ingredientId, owner);
+ const currentPeer = await authenticateIdentityPeer(req);
+ if (await localIdentity() !== owner || currentPeer.instanceId !== peer.instanceId) throw new ServerError('Owner binding changed', { status: 409 });
+ res.set('Cache-Control', 'no-store').json(signEvidence(currentPeer, { owner, challenge: params.challenge,
+ kind: 'snapshot', target: params.ingredientId, value }));
+}));
+router.get('/peer/status', asyncHandler(async (req, res) => {
+ const params = validateRequest(identityStatusQuerySchema, req.query);
+ const peer = await authenticateIdentityPeer(req);
+ const owner = await localIdentity();
+ const value = await identity.peerIdentityStatus(params.operationId, peer.instanceId);
+ const currentPeer = await authenticateIdentityPeer(req);
+ if (await localIdentity() !== owner || currentPeer.instanceId !== peer.instanceId) throw new ServerError('Owner binding changed', { status: 409 });
+ res.set('Cache-Control', 'no-store').json(signEvidence(currentPeer, { owner, challenge: params.challenge,
+ kind: 'status', target: params.operationId, value }));
+}));
+router.use(requireHostControl);
+router.get('/', asyncHandler(async (req, res) => {
+ const params = validateRequest(identityListQuerySchema, req.query);
+ res.set('Cache-Control', 'no-store').json(await identity.listIdentityOperations(params));
+}));
+router.get('/:id', asyncHandler(async (req, res) => {
+ res.set('Cache-Control', 'no-store').json(await identity.getIdentityOperation(req.params.id));
+}));
+function changed(result, res) {
+ catalogIdentityEvents.emit('changed', { operationId: result.id, sourceId: result.sourceId, survivorId: result.survivorId });
+ res.set('Cache-Control', 'no-store').json(result);
+}
+router.post('/preview', asyncHandler(async (req, res) => {
+ const body = validateRequest(identityPreviewSchema, req.body);
+ res.set('Cache-Control', 'no-store').json(await identity.previewIdentity(body));
+}));
+router.post('/create', asyncHandler(async (req, res) => {
+ const body = validateRequest(identityCreateSchema, req.body);
+ changed(await identity.createIdentity(body), res);
+}));
+router.post('/import', asyncHandler(async (req, res) => {
+ const body = validateRequest(identityImportSchema, req.body);
+ changed(await identity.importIdentity(body), res);
+}));
+router.post('/:id/accept', asyncHandler(async (req, res) => {
+ const body = validateRequest(identityAcceptSchema, req.body);
+ changed(await identity.acceptIdentity(req.params.id, body.planHash), res);
+}));
+router.post('/:id/advance', asyncHandler(async (req, res) => {
+ validateRequest(identityEmptySchema, req.body ?? {});
+ changed(await identity.advanceIdentity(req.params.id), res);
+}));
+router.post('/:id/abort', asyncHandler(async (req, res) => {
+ validateRequest(identityEmptySchema, req.body ?? {});
+ changed(await identity.abortIdentity(req.params.id), res);
+}));
+router.post('/:id/recover', asyncHandler(async (req, res) => {
+ const body = validateRequest(identityAcceptSchema, req.body);
+ changed(await identity.prepareIdentityRecovery(req.params.id, body.planHash), res);
+}));
+export default router;
diff --git a/server/routes/catalogIdentity.test.js b/server/routes/catalogIdentity.test.js
new file mode 100644
index 0000000000..1b397f0d97
--- /dev/null
+++ b/server/routes/catalogIdentity.test.js
@@ -0,0 +1,87 @@
+import { EventEmitter } from 'node:events';
+import express from 'express';
+import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mockPathsDataRoot } from '../lib/mockPathsDataRoot.js';
+import { request } from '../lib/testHelper.js';
+import { errorMiddleware } from '../lib/errorHandler.js';
+import { derivePeerAuthToken } from '../lib/peerHttpClient.js';
+
+const { makeProxy, cleanup } = mockPathsDataRoot({ prefix: 'catalog-identity-route-' });
+vi.mock('../lib/fileUtils.js', async original => makeProxy(await original()));
+afterAll(cleanup);
+const fixture = vi.hoisted(() => ({ enabled: false, calls: [], peer: {
+ id: 'fixture-peer-record', instanceId: 'fixture-peer', enabled: true, syncEnabled: true,
+ syncSecret: 'fake-test-pair-secret-only-used-in-fixtures', directions: ['inbound', 'outbound'], syncCategories: { catalog: true },
+} }));
+vi.mock('../services/auth.js', () => ({ isAuthEnabled: async () => fixture.enabled,
+ verifyPassword: async () => false,
+ verifyRequestSession: async ({ headers }) => headers.authorization === 'Bearer fixture-operator' ? { fixture: true } : null,
+}));
+vi.mock('../services/settings.js', () => ({ getSettings: async () => ({}), settingsEvents: new EventEmitter() }));
+vi.mock('../services/instanceIdentity.js', () => ({
+ getInstanceId: async () => 'fixture-local', UNKNOWN_INSTANCE_ID: 'unknown', loadData: async () => ({ peers: [fixture.peer] }),
+}));
+vi.mock('../services/sharing/peerSyncShared.js', () => ({
+ findPeerById: async id => id === fixture.peer.instanceId ? fixture.peer : null,
+ peerAllowsOutbound: peer => peer.enabled && peer.syncEnabled && peer.directions.includes('outbound'),
+ peerAllowsCategoryPull: peer => peer.syncCategories.catalog === true,
+}));
+vi.mock('../services/catalogIdentity/index.js', () => ({
+ listIdentityOperations: async input => { fixture.calls.push(input); return { items: [], nextOffset: null }; },
+ getIdentityOperation: async id => ({ id }),
+ previewIdentity: async input => { fixture.calls.push(input); return { conflicts: [], planHash: 'a'.repeat(64) }; },
+ createIdentity: async input => ({ id: input.operationId, sourceId: input.sourceId, survivorId: input.survivorId }),
+ importIdentity: async () => ({}), acceptIdentity: async () => ({}), advanceIdentity: async () => ({}),
+ abortIdentity: async () => ({}), prepareIdentityRecovery: async () => ({}),
+ ownerSnapshot: async id => ({ ingredients: [{ id, origin_instance_id: 'fixture-local' }] }),
+ peerIdentityStatus: async id => ({ id, state: 'prepared' }),
+}));
+const { authGate } = await import('../services/authGate.js');
+const { default: routes } = await import('./catalogIdentity.js');
+function app() {
+ const value = express();
+ value.use((req, _res, next) => {
+ // A remote socket identity, not a spoofable client header.
+ Object.defineProperty(req.socket, 'remoteAddress', { value: '192.0.2.5' }); next();
+ });
+ value.use(express.json()); value.use(authGate);
+ value.use('/api/catalog/identity', routes); value.use(errorMiddleware); return value;
+}
+function authed(api, headers) {
+ return Object.fromEntries(['get', 'post'].map(method => [method, path => {
+ const builder = request(api)[method](path);
+ for (const [name, value] of Object.entries(headers)) builder.set(name, value);
+ return builder;
+ }]));
+}
+const peerHeaders = () => ({ 'X-PortOS-Instance-Id': fixture.peer.instanceId,
+ 'X-PortOS-Peer-Auth': derivePeerAuthToken(fixture.peer.syncSecret, fixture.peer.instanceId) });
+beforeEach(() => { fixture.enabled = false; fixture.calls.length = 0; fixture.peer.syncCategories.catalog = true; });
+
+describe('canonical identity authorization and route contract', () => {
+ it('admits only paired challenge-bound evidence reads; a scoped peer cannot mutate or inspect operator receipts', async () => {
+ const api = app(); const headers = peerHeaders();
+ const read = await authed(api, headers).get(`/api/catalog/identity/peer/status?operationId=fixture-operation&challenge=${'a'.repeat(64)}`);
+ expect(read.status).toBe(200);
+ expect(read.body).toMatchObject({ owner: 'fixture-local', audience: 'fixture-peer', kind: 'status', target: 'fixture-operation', challenge: 'a'.repeat(64) });
+ expect(read.body.mac).toMatch(/^[a-f0-9]{64}$/);
+ expect((await authed(api, headers).post('/api/catalog/identity/fixture-operation/accept').send({ planHash: 'a'.repeat(64) })).status).toBe(403);
+ expect((await authed(api, headers).get('/api/catalog/identity')).status).toBe(403);
+ expect((await request(api).get(`/api/catalog/identity/peer/snapshot?ingredientId=fixture&challenge=${'a'.repeat(64)}`)).status).toBe(403);
+ fixture.peer.syncCategories.catalog = false;
+ expect((await authed(api, headers).get(`/api/catalog/identity/peer/status?operationId=fixture-operation&challenge=${'a'.repeat(64)}`)).status).toBe(403);
+ expect(fixture.calls).toEqual([]);
+ });
+ it('preserves operator session authority and validates pagination, operation UUID and exact acceptance hash', async () => {
+ fixture.enabled = true; const api = app(); const headers = { Authorization: 'Bearer fixture-operator' };
+ const list = await authed(api, headers).get('/api/catalog/identity?ingredientId=fixture&limit=5&offset=2');
+ expect(list.status).toBe(200); expect(fixture.calls[0]).toEqual({ ingredientId: 'fixture', limit: 5, offset: 2 });
+ expect((await authed(api, headers).get('/api/catalog/identity?limit=10000')).status).toBe(400);
+ expect((await authed(api, headers).post('/api/catalog/identity/preview').send({ sourceId: 's', survivorId: 't' })).status).toBe(400);
+ const valid = await authed(api, headers).post('/api/catalog/identity/preview').send({
+ operationId: 'd0e9bbda-a271-4387-898b-ae6772e28973', sourceId: 's', survivorId: 't', fieldChoices: {},
+ });
+ expect(valid.status).toBe(200);
+ expect((await authed(api, headers).post('/api/catalog/identity/fixture/accept').send({ planHash: 'bad' })).status).toBe(400);
+ });
+});
diff --git a/server/routes/catalogParsedBodies.test.js b/server/routes/catalogParsedBodies.test.js
index 658f205afc..f8769da056 100644
--- a/server/routes/catalogParsedBodies.test.js
+++ b/server/routes/catalogParsedBodies.test.js
@@ -1,3 +1,4 @@
+vi.mock('../services/catalogDB/identityAccess.js', () => ({ getCatalogIdentityAccess: vi.fn(async () => null), assertCatalogIdentityWritable: vi.fn(async id => id) }));
/**
* Route-boundary regression tests for Catalog write-body normalization.
*
diff --git a/server/routes/catalogSheets.test.js b/server/routes/catalogSheets.test.js
index 4b9036ef6e..352e60bc40 100644
--- a/server/routes/catalogSheets.test.js
+++ b/server/routes/catalogSheets.test.js
@@ -1,3 +1,4 @@
+vi.mock('../services/catalogDB/identityAccess.js', () => ({ assertCatalogIdentityWritable: vi.fn(async id => id) }));
import { describe, it, expect, vi, beforeEach } from 'vitest';
import express from 'express';
import { request } from '../lib/testHelper.js';
@@ -76,6 +77,14 @@ beforeEach(() => {
});
describe('catalog sheet routes', () => {
+ it('refuses a foreign canonical target before rendering or looking up settings', async () => {
+ const { assertCatalogIdentityWritable } = await import('../services/catalogDB/identityAccess.js');
+ assertCatalogIdentityWritable.mockRejectedValueOnce(Object.assign(new Error('Canonical owner required'), { status: 409, code: 'CATALOG_IDENTITY_FOREIGN' }));
+ const res = await request(app).post('/api/catalog/ingredients/foreign-canonical/sheets').send({});
+ expect(res.status).toBe(409);
+ expect(mocks.enqueueJob).not.toHaveBeenCalled();
+ expect(mocks.getSettings).not.toHaveBeenCalled();
+ });
it('lists the variants a type offers', async () => {
mocks.getIngredient.mockResolvedValue(place);
const res = await request(app).get('/api/catalog/ingredients/cat-plc-1/sheets/variants');
diff --git a/server/routes/catalogTypes.test.js b/server/routes/catalogTypes.test.js
index 25c7ea5957..b29f52e7f8 100644
--- a/server/routes/catalogTypes.test.js
+++ b/server/routes/catalogTypes.test.js
@@ -15,7 +15,8 @@ import { errorMiddleware } from '../lib/errorHandler.js';
// In-memory settings store the route's getSettings/updateSettings read/write.
let store = {};
-vi.mock('../services/settings.js', () => ({
+vi.mock('../services/settings.js', async () => ({
+ settingsEvents: new (await import('node:events')).EventEmitter(),
getSettings: vi.fn(async () => ({ ...store })),
updateSettings: vi.fn(async (patch) => { store = { ...store, ...patch }; return { ...store }; }),
}));
diff --git a/server/routes/imageGen.js b/server/routes/imageGen.js
index 689e146e89..72f4242a69 100644
--- a/server/routes/imageGen.js
+++ b/server/routes/imageGen.js
@@ -1,3 +1,4 @@
+import { assertCatalogIdentityWritable } from '../services/catalogDB/identityAccess.js';
/**
* Image Generation Routes — works against the external SD API, local mflux,
* or the Codex CLI built-in image_gen tool, depending on settings.imageGen.mode
@@ -480,6 +481,7 @@ router.post('/prompt-preview', asyncHandler(async (req, res) => {
router.post('/generate', imageGenUploads, asyncHandler(async (req, res) => {
const data = validateRequest(generateSchema, coerceFormFields(req.body));
+ if (data.catalogIngredientId) await assertCatalogIdentityWritable(data.catalogIngredientId);
const { data: params, mode, settings, uploadedTempPaths } = await prepareGenerateParams({
data,
files: req.files,
diff --git a/server/routes/imageGen.test.js b/server/routes/imageGen.test.js
index 43cd2a2ec6..539fecbe19 100644
--- a/server/routes/imageGen.test.js
+++ b/server/routes/imageGen.test.js
@@ -1,3 +1,4 @@
+vi.mock('../services/catalogDB/identityAccess.js', () => ({ assertCatalogIdentityWritable: vi.fn(async id => id) }));
import { describe, it, expect, vi, beforeEach, afterEach, afterAll } from 'vitest';
import express from 'express';
import { resolveImageCleaners } from '../lib/imageCleanDefaults.js';
@@ -776,6 +777,13 @@ describe('Image Gen Routes', () => {
// the page unmounts. The route collapses the raw fields into the tag and
// drops them from params.
describe('catalogAttach tag', () => {
+ it('refuses a retained target before provider preparation or enqueue', async () => {
+ const { assertCatalogIdentityWritable } = await import('../services/catalogDB/identityAccess.js');
+ assertCatalogIdentityWritable.mockRejectedValueOnce(Object.assign(new Error('Retained original'), { status: 409, code: 'CATALOG_IDENTITY_RETAINED' }));
+ const response = await request(app).post('/api/image-gen/generate').send({ prompt: 'example', catalogIngredientId: 'retained-original' });
+ expect(response.status).toBe(409);
+ expect(mediaJobQueue.enqueueJob).not.toHaveBeenCalled();
+ });
it('folds catalogIngredientId into a catalogAttach job tag and drops the raw field', async () => {
getSettings.mockResolvedValueOnce({ imageGen: { mode: 'local', local: { pythonPath: '/usr/bin/python3' } } });
mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-cat', position: 1, status: 'queued' });
diff --git a/server/scripts/init-db.sql b/server/scripts/init-db.sql
index 3b915343f5..878cb33198 100644
--- a/server/scripts/init-db.sql
+++ b/server/scripts/init-db.sql
@@ -2481,3 +2481,182 @@ CREATE OR REPLACE FUNCTION guard_catalog_merged_ingredient()
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();
+
+-- Shared canonical identity: receipts, fences and read-only evidence views.
+CREATE TABLE IF NOT EXISTS catalog_identity_operations (
+ id TEXT PRIMARY KEY,
+ source_id TEXT NOT NULL REFERENCES catalog_ingredients(id),
+ survivor_id TEXT NOT NULL REFERENCES catalog_ingredients(id),
+ source_owner TEXT NOT NULL,
+ survivor_owner TEXT NOT NULL,
+ local_owner TEXT NOT NULL,
+ state TEXT NOT NULL CHECK (state IN ('proposed', 'prepared', 'committed', 'aborted', 'recovery_prepared', 'recovered')),
+ epoch INTEGER NOT NULL DEFAULT 0,
+ plan JSONB NOT NULL,
+ plan_hash TEXT NOT NULL,
+ before_state JSONB,
+ applied_fingerprint TEXT,
+ current_snapshot JSONB,
+ recovery JSONB,
+ peer_state TEXT,
+ peer_observed_at TIMESTAMPTZ,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ CHECK (source_id <> survivor_id),
+ CHECK (source_owner <> survivor_owner),
+ CHECK (local_owner IN (source_owner, survivor_owner))
+ );
+CREATE INDEX IF NOT EXISTS idx_catalog_identity_source ON catalog_identity_operations(source_id);
+CREATE INDEX IF NOT EXISTS idx_catalog_identity_survivor ON catalog_identity_operations(survivor_id);
+CREATE OR REPLACE FUNCTION catalog_canonical_ingredient_id(requested_id TEXT)
+ RETURNS TEXT LANGUAGE SQL STABLE AS $$
+ SELECT catalog_resolve_ingredient_id(COALESCE((SELECT survivor_id FROM catalog_identity_operations
+ WHERE source_id = requested_id AND state IN ('committed', 'recovery_prepared')), requested_id))
+ $$;
+CREATE OR REPLACE FUNCTION catalog_identity_member_ids(requested_id TEXT)
+ RETURNS TEXT[] LANGUAGE SQL STABLE AS $$
+ SELECT ARRAY(SELECT DISTINCT member FROM (
+ SELECT catalog_canonical_ingredient_id(requested_id) AS member
+ UNION ALL SELECT source_id FROM catalog_identity_operations
+ WHERE survivor_id = catalog_canonical_ingredient_id(requested_id) AND state IN ('committed', 'recovery_prepared')
+ UNION ALL SELECT source_id FROM catalog_ingredient_merges
+ WHERE survivor_id = catalog_canonical_ingredient_id(requested_id) AND restored_at IS NULL
+ ) members)
+ $$;
+CREATE OR REPLACE FUNCTION guard_catalog_identity_member()
+ RETURNS TRIGGER LANGUAGE plpgsql AS $$
+ DECLARE touched TEXT[]; old_row JSONB; new_row JSONB; operation RECORD;
+ BEGIN
+ IF TG_OP <> 'INSERT' THEN old_row := to_jsonb(OLD); END IF;
+ IF TG_OP <> 'DELETE' THEN new_row := to_jsonb(NEW); END IF;
+ touched := ARRAY[old_row->>'id', new_row->>'id', old_row->>'ingredient_id', new_row->>'ingredient_id',
+ old_row->>'from_id', new_row->>'from_id', old_row->>'to_id', new_row->>'to_id'];
+ FOR operation IN SELECT * FROM catalog_identity_operations
+ WHERE state IN ('prepared', 'committed', 'recovery_prepared')
+ AND (source_id = ANY(touched) OR survivor_id = ANY(touched)) LOOP
+ IF current_setting('portos.catalog_identity_operation', true) IS DISTINCT FROM operation.id THEN
+ IF current_setting('portos.catalog_identity_peer_apply', true) = 'on'
+ OR operation.state IN ('prepared', 'recovery_prepared') OR operation.source_id = ANY(touched)
+ OR operation.local_owner <> operation.survivor_owner
+ OR (TG_TABLE_NAME = 'catalog_ingredients' AND
+ (TG_OP = 'DELETE' OR (new_row->>'deleted')::boolean OR new_row->>'origin_instance_id' IS DISTINCT FROM operation.survivor_owner
+ OR new_row->>'type' IS DISTINCT FROM old_row->>'type')) THEN
+ RAISE EXCEPTION 'Shared canonical identity is protected; use its owner protocol' USING ERRCODE = 'P0001';
+ END IF;
+ END IF;
+ END LOOP;
+ IF TG_OP = 'DELETE' THEN RETURN OLD; END IF;
+ RETURN NEW;
+ END $$;
+DROP TRIGGER IF EXISTS trg_catalog_identity_member ON catalog_ingredients;
+CREATE TRIGGER trg_catalog_identity_member BEFORE INSERT OR UPDATE OR DELETE ON catalog_ingredients
+ FOR EACH ROW EXECUTE FUNCTION guard_catalog_identity_member();
+DROP TRIGGER IF EXISTS trg_catalog_identity_member ON catalog_ingredient_sources;
+CREATE TRIGGER trg_catalog_identity_member BEFORE INSERT OR UPDATE OR DELETE ON catalog_ingredient_sources
+ FOR EACH ROW EXECUTE FUNCTION guard_catalog_identity_member();
+DROP TRIGGER IF EXISTS trg_catalog_identity_member ON catalog_ingredient_refs;
+CREATE TRIGGER trg_catalog_identity_member BEFORE INSERT OR UPDATE OR DELETE ON catalog_ingredient_refs
+ FOR EACH ROW EXECUTE FUNCTION guard_catalog_identity_member();
+DROP TRIGGER IF EXISTS trg_catalog_identity_member ON catalog_ingredient_media;
+CREATE TRIGGER trg_catalog_identity_member BEFORE INSERT OR UPDATE OR DELETE ON catalog_ingredient_media
+ FOR EACH ROW EXECUTE FUNCTION guard_catalog_identity_member();
+DROP TRIGGER IF EXISTS trg_catalog_identity_member ON catalog_ingredient_relations;
+CREATE TRIGGER trg_catalog_identity_member BEFORE INSERT OR UPDATE OR DELETE ON catalog_ingredient_relations
+ FOR EACH ROW EXECUTE FUNCTION guard_catalog_identity_member();
+DROP TRIGGER IF EXISTS trg_catalog_identity_member ON catalog_ingredient_revisions;
+CREATE TRIGGER trg_catalog_identity_member BEFORE INSERT OR UPDATE OR DELETE ON catalog_ingredient_revisions
+ FOR EACH ROW EXECUTE FUNCTION guard_catalog_identity_member();
+CREATE OR REPLACE VIEW catalog_identity_read_sources AS
+ WITH active AS (SELECT * FROM catalog_identity_operations WHERE state IN ('committed', 'recovery_prepared')),
+ candidates AS (
+ SELECT jsonb_populate_record(NULL::catalog_ingredient_sources, item) AS r, 0 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.plan->'source'->'sources', '[]'::jsonb)) item
+ UNION ALL
+ SELECT live AS r, 1 AS priority FROM catalog_ingredient_sources live
+ WHERE NOT EXISTS (SELECT 1 FROM active o WHERE live.ingredient_id = o.source_id
+ OR (o.local_owner <> o.survivor_owner AND live.ingredient_id = o.survivor_id))
+
+ UNION ALL
+ SELECT jsonb_populate_record(NULL::catalog_ingredient_sources, item) AS r, 2 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.current_snapshot->'sources', o.plan->'survivor'->'sources', '[]'::jsonb)) item
+ WHERE o.local_owner <> o.survivor_owner
+
+
+ ) SELECT DISTINCT ON ((r).ingredient_id, (r).scrap_id) (r).*, priority IN (0, 3, 4) AS identity_retained
+ FROM candidates ORDER BY (r).ingredient_id, (r).scrap_id, priority;
+CREATE OR REPLACE VIEW catalog_identity_read_refs AS
+ WITH active AS (SELECT * FROM catalog_identity_operations WHERE state IN ('committed', 'recovery_prepared')),
+ candidates AS (
+ SELECT jsonb_populate_record(NULL::catalog_ingredient_refs, item) AS r, 0 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.plan->'source'->'refs', '[]'::jsonb)) item
+ UNION ALL
+ SELECT live AS r, 1 AS priority FROM catalog_ingredient_refs live
+ WHERE NOT EXISTS (SELECT 1 FROM active o WHERE live.ingredient_id = o.source_id
+ OR (o.local_owner <> o.survivor_owner AND live.ingredient_id = o.survivor_id))
+ AND live.ingredient_id = catalog_resolve_ingredient_id(live.ingredient_id)
+ UNION ALL
+ SELECT jsonb_populate_record(NULL::catalog_ingredient_refs, item) AS r, 2 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.current_snapshot->'refs', o.plan->'survivor'->'refs', '[]'::jsonb)) item
+ WHERE o.local_owner <> o.survivor_owner
+
+
+ ) SELECT DISTINCT ON ((r).ingredient_id, (r).ref_kind, (r).ref_id, (r).role) (r).*, priority IN (0, 3, 4) AS identity_retained
+ FROM candidates ORDER BY (r).ingredient_id, (r).ref_kind, (r).ref_id, (r).role, priority;
+CREATE OR REPLACE VIEW catalog_identity_read_media AS
+ WITH active AS (SELECT * FROM catalog_identity_operations WHERE state IN ('committed', 'recovery_prepared')),
+ candidates AS (
+ SELECT jsonb_populate_record(NULL::catalog_ingredient_media, item) AS r, 0 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.plan->'source'->'media', '[]'::jsonb)) item
+ UNION ALL
+ SELECT live AS r, 1 AS priority FROM catalog_ingredient_media live
+ WHERE NOT EXISTS (SELECT 1 FROM active o WHERE live.ingredient_id = o.source_id
+ OR (o.local_owner <> o.survivor_owner AND live.ingredient_id = o.survivor_id))
+ AND live.ingredient_id = catalog_resolve_ingredient_id(live.ingredient_id)
+ UNION ALL
+ SELECT jsonb_populate_record(NULL::catalog_ingredient_media, item) AS r, 2 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.current_snapshot->'media', o.plan->'survivor'->'media', '[]'::jsonb)) item
+ WHERE o.local_owner <> o.survivor_owner
+
+ UNION ALL
+ SELECT jsonb_populate_record(NULL::catalog_ingredient_media, item) AS r, 4 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.plan->'archivedMedia', '[]'::jsonb)) item
+ ) SELECT DISTINCT ON ((r).ingredient_id, (r).media_key, (r).kind) (r).*, priority IN (0, 3, 4) AS identity_retained
+ FROM candidates ORDER BY (r).ingredient_id, (r).media_key, (r).kind, priority;
+CREATE OR REPLACE VIEW catalog_identity_read_relations AS
+ WITH active AS (SELECT * FROM catalog_identity_operations WHERE state IN ('committed', 'recovery_prepared')),
+ candidates AS (
+ SELECT jsonb_populate_record(NULL::catalog_ingredient_relations, item) AS r, 0 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.plan->'source'->'relations', '[]'::jsonb)) item
+ UNION ALL
+ SELECT live AS r, 1 AS priority FROM catalog_ingredient_relations live
+ WHERE NOT EXISTS (SELECT 1 FROM active o WHERE (live.from_id = o.source_id OR live.to_id = o.source_id)
+ OR (o.local_owner <> o.survivor_owner AND (live.from_id = o.survivor_id OR live.to_id = o.survivor_id)))
+ AND live.from_id = catalog_resolve_ingredient_id(live.from_id) AND live.to_id = catalog_resolve_ingredient_id(live.to_id)
+ UNION ALL
+ SELECT jsonb_populate_record(NULL::catalog_ingredient_relations, item) AS r, 2 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.current_snapshot->'relations', o.plan->'survivor'->'relations', '[]'::jsonb)) item
+ WHERE o.local_owner <> o.survivor_owner
+
+
+ ) SELECT DISTINCT ON ((r).from_id, (r).to_id, (r).kind) (r).*, priority IN (0, 3, 4) AS identity_retained
+ FROM candidates ORDER BY (r).from_id, (r).to_id, (r).kind, priority;
+CREATE OR REPLACE VIEW catalog_identity_read_revisions AS
+ WITH active AS (SELECT * FROM catalog_identity_operations WHERE state IN ('committed', 'recovery_prepared')),
+ candidates AS (
+ SELECT jsonb_populate_record(NULL::catalog_ingredient_revisions, item) AS r, 0 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.plan->'source'->'revisions', '[]'::jsonb)) item
+ UNION ALL
+ SELECT live AS r, 1 AS priority FROM catalog_ingredient_revisions live
+ WHERE NOT EXISTS (SELECT 1 FROM active o WHERE live.ingredient_id = o.source_id
+ OR (o.local_owner <> o.survivor_owner AND live.ingredient_id = o.survivor_id))
+
+ UNION ALL
+ SELECT jsonb_populate_record(NULL::catalog_ingredient_revisions, item) AS r, 2 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.current_snapshot->'revisions', o.plan->'survivor'->'revisions', '[]'::jsonb)) item
+
+ UNION ALL
+ SELECT jsonb_populate_record(NULL::catalog_ingredient_revisions, item) AS r, 3 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.plan->'survivor'->'revisions', '[]'::jsonb)) item
+
+ ) SELECT DISTINCT ON ((r).id) (r).*, priority IN (0, 3, 4) AS identity_retained
+ FROM candidates ORDER BY (r).id, priority;
diff --git a/server/scripts/migrateBibleToCatalog.js b/server/scripts/migrateBibleToCatalog.js
index 0c2a6fe768..6e3d0ee0b4 100644
--- a/server/scripts/migrateBibleToCatalog.js
+++ b/server/scripts/migrateBibleToCatalog.js
@@ -1,3 +1,4 @@
+import { getCatalogIdentityAccess } from '../services/catalogDB/identityAccess.js';
/**
* Backfill embedded universe canon into the Creative Ingredients Catalog.
*
@@ -104,6 +105,7 @@ async function promoteEntry({ universeId, universeName, entry, kind, role }) {
const targetId = entry.ingredientId || deterministicIngredientId(universeId, kind, entry.id);
+ if (await getCatalogIdentityAccess(targetId)) return { skipped: true, reason: 'shared-identity-context' };
const existing = await catalogDB.getIngredient(targetId);
if (existing) {
await catalogDB.linkIngredientToRef(targetId, 'universe', universeId, role);
diff --git a/server/scripts/migrateBibleToCatalog.test.js b/server/scripts/migrateBibleToCatalog.test.js
index 0ac36d76f4..65989d1fbe 100644
--- a/server/scripts/migrateBibleToCatalog.test.js
+++ b/server/scripts/migrateBibleToCatalog.test.js
@@ -1,3 +1,4 @@
+vi.mock('../services/catalogDB/identityAccess.js', () => ({ getCatalogIdentityAccess: vi.fn(async () => null) }));
/**
* Idempotency tests for the bible→catalog backfill.
*
diff --git a/server/scripts/reconcileCanonCatalog.js b/server/scripts/reconcileCanonCatalog.js
index 1f33b6dc0f..69c10a64e8 100644
--- a/server/scripts/reconcileCanonCatalog.js
+++ b/server/scripts/reconcileCanonCatalog.js
@@ -1,3 +1,4 @@
+import { getCatalogIdentityAccess } from '../services/catalogDB/identityAccess.js';
/**
* One-time boot reconciliation: collapse any pre-existing divergence between an
* embedded universe-canon entry and its `catalog_ingredients` row.
@@ -91,6 +92,7 @@ export async function reconcileCanonCatalog({ force = false } = {}) {
if (!ingredientId || !entry?.id) continue; // entries without ingredientId untouched
totals.scanned++;
try {
+ if (await getCatalogIdentityAccess(ingredientId)) continue; // retained contextual snapshot
const row = await catalogDB.getIngredient(ingredientId);
if (!row) continue; // dangling backlink — leave both sides alone
const entryAt = Date.parse(entry.updatedAt || '') || 0;
diff --git a/server/scripts/reconcileCanonCatalog.test.js b/server/scripts/reconcileCanonCatalog.test.js
index 4f076c5d7d..2a8c590120 100644
--- a/server/scripts/reconcileCanonCatalog.test.js
+++ b/server/scripts/reconcileCanonCatalog.test.js
@@ -1,3 +1,4 @@
+vi.mock('../services/catalogDB/identityAccess.js', () => ({ getCatalogIdentityAccess: vi.fn(async () => null) }));
/**
* Tests for the boot-time canon↔catalog reconciliation.
*
diff --git a/server/services/backup.db.test.js b/server/services/backup.db.test.js
index 883a9f7b87..61833a5bc7 100644
--- a/server/services/backup.db.test.js
+++ b/server/services/backup.db.test.js
@@ -11,6 +11,7 @@ import { ownTestBodies } from '../lib/mockPathsDataRoot.js';
import { resolvePgDumpBinary } from '../lib/pgTools.js';
import { runDbMigrations } from '../scripts/run-db-migrations.js';
import { listFolders } from './writersRoom/db.js';
+import { buildCatalogIdentityViewsDdl } from '../lib/db/schema/catalogIdentityViews.js';
import { syncFeedTables, syncFeedSequenceName } from '../lib/db/schema/syncFeed.js';
// The real rewind rewrites this install's data/instances_sync_cursors.json.
@@ -294,6 +295,10 @@ describe.skipIf(!ready)('restore older database schema', () => {
it('refuses unknown functions and wrong overloads even when a shipped function is absent', async () => {
// Missing signatures resolve to NULL: they must not admit an unrelated
// function through nullable NOT IN comparisons during an older restore.
+ // Current identity read views depend on this resolver. Model an older
+ // install lacking both views and function; never CASCADE unknown objects.
+ const identityViews = buildCatalogIdentityViewsDdl().map(sql => /^CREATE OR REPLACE VIEW ([a-z_]+)/.exec(sql)[1]);
+ await query(`DROP VIEW IF EXISTS ${identityViews.map(name => `public.${name}`).join(', ')} RESTRICT`);
await query('DROP FUNCTION public.catalog_resolve_ingredient_id(text) RESTRICT');
try {
for (const signature of ['unexpected_restore_function()', 'catalog_resolve_ingredient_id(integer)']) {
@@ -315,6 +320,11 @@ describe.skipIf(!ready)('restore older database schema', () => {
});
it('preflights unknown objects and external dependencies without mutations, including preview', async () => {
+ await query('CREATE VIEW public.unexpected_restore_view AS SELECT 42 AS value');
+ try {
+ for (const dryRun of [true, false]) expect(await restore(dryRun)).toMatchObject({ status: 'failed', reason: 'restore_preflight' });
+ expect((await query('SELECT value FROM public.unexpected_restore_view')).rows).toEqual([{ value: 42 }]);
+ } finally { await query('DROP VIEW public.unexpected_restore_view RESTRICT'); }
await query('CREATE TABLE public.unexpected_restore_record (id integer PRIMARY KEY)');
await query('INSERT INTO public.unexpected_restore_record VALUES (42)');
expect(await restore()).toMatchObject({ status: 'failed', reason: 'restore_preflight' });
diff --git a/server/services/backupDatabaseReset.js b/server/services/backupDatabaseReset.js
index b14a093b9d..692b2751e7 100644
--- a/server/services/backupDatabaseReset.js
+++ b/server/services/backupDatabaseReset.js
@@ -17,6 +17,7 @@ export async function getDatabaseResetPlan() {
// Unsupported future declarations remain excluded and fail preflight closed.
const functions = names(/CREATE OR REPLACE FUNCTION ([a-z_][a-z_0-9]*\((?:[a-z_][a-z_0-9]* TEXT)?\))/g)
.map(signature => `public.${signature.replace(/\([a-z_][a-z_0-9]* TEXT\)/, '(text)')}`);
+ const views = names(/CREATE OR REPLACE VIEW ([a-z_][a-z_0-9]*)/g);
const sequences = names(/CREATE SEQUENCE IF NOT EXISTS ([a-z_][a-z_0-9]*)/g);
const literals = values => values.map(value => `'${value}'`).join(', ');
const preflight = `DO $portos_restore$
@@ -36,6 +37,7 @@ export async function getDatabaseResetPlan() {
AND d.objid = c.oid AND d.deptype = 'e')
AND (c.relowner <> (SELECT oid FROM pg_roles WHERE rolname = current_user)
OR NOT ((c.relkind = 'r' AND c.relname IN (${literals(tables)}))
+ OR (c.relkind = 'v' AND c.relname IN (${literals(views)}))
OR (c.relkind = 'S' AND (c.relname IN (${literals(sequences)}) OR EXISTS (
SELECT 1 FROM pg_depend d JOIN pg_class t ON t.oid = d.refobjid
WHERE d.classid = 'pg_class'::regclass AND d.objid = c.oid
@@ -89,6 +91,7 @@ export async function getDatabaseResetPlan() {
// remains the database-enforced backstop for every unanticipated dependency,
// including changes between preflight and replay. Never use CASCADE here.
const reset = `${preflight}
+ DROP VIEW IF EXISTS ${views.map(name => `public.${name}`).join(', ')} RESTRICT;
DROP TABLE IF EXISTS ${tables.map(name => `public.${name}`).join(', ')} RESTRICT;
DROP FUNCTION IF EXISTS ${functions.join(', ')} RESTRICT;
DROP SEQUENCE IF EXISTS ${sequences.map(name => `public.${name}`).join(', ')} RESTRICT;
diff --git a/server/services/catalogCanonProjection.js b/server/services/catalogCanonProjection.js
index 8485174aca..d099245b7e 100644
--- a/server/services/catalogCanonProjection.js
+++ b/server/services/catalogCanonProjection.js
@@ -40,6 +40,7 @@
*/
import * as catalogDB from './catalogDB.js';
+import { getCatalogIdentityAccess } from './catalogDB/identityAccess.js';
import { BIBLE_FIELD } from '../lib/storyBible.js';
// Canon array keys, derived from the bible registry so a future kind added
@@ -90,6 +91,9 @@ export async function projectToCanon(ingredientId, updatedIngredient, deps = {})
if (!ingredientId || !updatedIngredient) return { universes: 0, written: 0, skipped: 0 };
ingredientId = updatedIngredient.id || ingredientId;
+ // Cross-owner contextual canon stays an original snapshot. The catalog ID
+ // resolves current canon without silently rewriting a peer-owned universe.
+ if (await getCatalogIdentityAccess(ingredientId)) return { universes: 0, written: 0, skipped: 1 };
const identityIds = new Set(await catalogDB.getIngredientIdentityIds(ingredientId));
// Guard the originating ingredient so the updateUniverse → projectToCatalog
diff --git a/server/services/catalogDB.exportSlice.test.js b/server/services/catalogDB.exportSlice.test.js
index 3ba697a129..1e52d4df1e 100644
--- a/server/services/catalogDB.exportSlice.test.js
+++ b/server/services/catalogDB.exportSlice.test.js
@@ -2,7 +2,7 @@
* Unit tests for the BATCHED export-slice hydration (#3940).
*
* `exportSliceForRef` used to issue three queries per ingredient (scraps, refs,
- * media) — 3N round-trips for an N-ingredient universe. It now issues four
+ * media) — 3N round-trips for an N-ingredient universe. It now issues five
* queries total, regardless of N. Postgres is mocked: the fake `query` routes on
* the SQL text, so the suite asserts BOTH the query count and that the payload
* shape / ordering is byte-identical to the per-ingredient version.
@@ -76,10 +76,11 @@ vi.mock('../lib/db.js', () => ({
query: vi.fn(async (sql, params) => {
const flat = sql.replace(/\s+/g, ' ').trim();
calls.push({ sql: flat, params });
- if (flat.includes('FROM catalog_ingredients i')) return { rows: sliceIsEmpty.value ? [] : INGREDIENT_ROWS };
+ if ((flat.includes('FROM catalog_ingredients i') || flat.includes('FROM export_ingredients i'))) return { rows: sliceIsEmpty.value ? [] : INGREDIENT_ROWS };
+ if (flat.includes('FROM catalog_identity_read_sources')) return { rows: [{ ingredient_id: 'i1', scrap_id: 'missing-scrap', span: { start: 1, end: 4 }, extracted_at: new Date('2026-01-01T00:00:00Z') }] };
if (flat.includes('FROM catalog_scraps s')) return { rows: SCRAP_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 };
+ if ((flat.includes('FROM catalog_ingredient_refs') || flat.includes('FROM catalog_identity_read_refs') || flat.includes('JOIN catalog_identity_read_refs r'))) return { rows: REF_ROWS };
+ if ((flat.includes('FROM catalog_ingredient_media') || flat.includes('FROM catalog_identity_read_media') || flat.includes('JOIN catalog_identity_read_media m'))) return { rows: MEDIA_ROWS };
return { rows: [] };
}),
withTransaction: vi.fn(),
@@ -98,12 +99,12 @@ beforeEach(() => {
});
describe('exportSliceForRef batching (#3940)', () => {
- it('issues exactly four queries regardless of ingredient count', async () => {
+ it('issues exactly five queries regardless of ingredient count', async () => {
await catalogDB.exportSliceForRef('universe', 'uni-1');
- expect(calls).toHaveLength(4);
- // Three of them are the batched ANY($1) hydration queries.
+ expect(calls).toHaveLength(5);
+ // Four of them are the batched ANY($1) hydration queries.
const batched = calls.filter((c) => c.sql.includes('= ANY($1)') || c.sql.includes('unnest($1::text[])'));
- expect(batched).toHaveLength(3);
+ expect(batched).toHaveLength(4);
for (const c of batched) expect(c.params[0]).toEqual(['i1', 'i2']);
});
@@ -112,6 +113,7 @@ describe('exportSliceForRef batching (#3940)', () => {
expect(bundle.ref).toEqual({ kind: 'universe', id: 'uni-1' });
const [alpha, beta] = bundle.ingredients;
expect(alpha.id).toBe('i1');
+ expect(alpha.sources).toEqual([{ ingredientId: 'i1', scrapId: 'missing-scrap', span: { start: 1, end: 4 }, extractedAt: '2026-01-01T00:00:00.000Z' }]);
expect(alpha.roleForExportedRef).toBe('cast');
expect(alpha.scraps.map((s) => s.id)).toEqual(['s-old', 's-new']); // per-ingredient order kept
expect(alpha.refs).toEqual([expect.objectContaining({ refId: 'uni-1', role: 'cast' })]);
@@ -120,6 +122,7 @@ describe('exportSliceForRef batching (#3940)', () => {
expect(beta.id).toBe('i2');
expect(beta.roleForExportedRef).toBe('mentioned');
expect(beta.scraps).toEqual([]);
+ expect(beta.sources).toEqual([]);
expect(beta.refs).toEqual([]);
expect(beta.media).toEqual([]);
});
diff --git a/server/services/catalogDB.identityIntegration.db.test.js b/server/services/catalogDB.identityIntegration.db.test.js
new file mode 100644
index 0000000000..c7d7121161
--- /dev/null
+++ b/server/services/catalogDB.identityIntegration.db.test.js
@@ -0,0 +1,168 @@
+import { randomUUID } from 'node:crypto';
+import { afterAll, describe, expect, it, vi } from 'vitest';
+import { checkHealth, close, ensureSchema, query } from '../lib/db.js';
+import { requireDbOrSkip } from '../lib/dbTestGate.js';
+import * as catalog from './catalogDB.js';
+import { getCatalogIdentityAccess } from './catalogDB/identityAccess.js';
+import { mergeIngredients } from './catalogDB/merge.js';
+import { projectToCanon, projectToCatalog } from './catalogCanonProjection.js';
+
+vi.mock('./instanceIdentity.js', () => ({ getInstanceId: async () => 'identity-test-local', UNKNOWN_INSTANCE_ID: 'unknown' }));
+const health = await checkHealth().catch(error => ({ connected: false, error: error.message }));
+const ready = requireDbOrSkip('shared identity integration', health.connected, health.error);
+if (ready) await ensureSchema();
+const ingredientIds = [];
+const operations = [];
+const universes = [];
+const plain = value => JSON.parse(JSON.stringify(value));
+const now = '2026-01-02T00:00:00.000Z';
+
+async function fixture({ owned = false, state = 'committed', staleSourceReplica = false } = {}) {
+ const prefix = `identity-read-${randomUUID()}`;
+ const sourceId = `${prefix}-source`;
+ const survivorId = `${prefix}-survivor`;
+ const thirdId = `${prefix}-other`;
+ const universeId = `${prefix}-universe`;
+ const sourceOwner = owned ? 'identity-test-peer' : 'identity-test-local';
+ const survivorOwner = owned ? 'identity-test-local' : 'identity-test-peer';
+ ingredientIds.push(sourceId, survivorId, thirdId);
+ operations.push(prefix);
+ universes.push(universeId);
+ await query('INSERT INTO universes(id, name) VALUES ($1, $2)', [universeId, 'Example context']);
+ for (const [id, owner, name] of [[sourceId, sourceOwner, 'Original Example'], [survivorId, survivorOwner, 'Canonical Example'], [thirdId, 'identity-test-local', 'Other Example']]) {
+ await query(`INSERT INTO catalog_ingredients (id, type, name, payload, origin_instance_id)
+ VALUES ($1, 'character', $2, '{"locked":false,"aliases":["Original Example"]}'::jsonb, $3)`, [id, name, owner]);
+ }
+ const sourceRow = (await query('SELECT * FROM catalog_ingredients WHERE id = $1', [sourceId])).rows[0];
+ const survivorRow = (await query('SELECT * FROM catalog_ingredients WHERE id = $1', [survivorId])).rows[0];
+ const refs = [{ ingredient_id: sourceId, ref_kind: 'universe', ref_id: universeId, role: 'cast', created_at: now, updated_at: now, deleted: false }];
+ const media = [{ ingredient_id: sourceId, media_key: `${prefix}.png`, kind: 'reference', role: 'sheet:front', caption: 'Original evidence', metadata: { prompt: 'Original example prompt' }, created_at: now, updated_at: now, deleted: false }];
+ const sourceRevision = { id: `${prefix}-source-revision`, ingredient_id: sourceId, name: sourceRow.name, payload: { description: 'Original history' }, tags: [], source: 'user', created_at: now };
+ const survivorRevision = { ...sourceRevision, id: `${prefix}-survivor-revision`, ingredient_id: survivorId, name: survivorRow.name };
+ const source = { ingredients: [sourceRow], refs, media, sources: [{ ingredient_id: sourceId, scrap_id: `${prefix}-missing-scrap`, span: { start: 3, end: 9 }, extracted_at: now }], relations: [{ from_id: sourceId, to_id: thirdId, kind: 'knows', created_at: now, updated_at: now, deleted: false }], revisions: [sourceRevision] };
+ const survivor = { ingredients: [survivorRow], refs: [], media: [], sources: [], relations: [], revisions: [survivorRevision] };
+ const plan = plain({ version: 1, sourceId, survivorId, sourceOwner, survivorOwner, source, survivor, proposed: { name: survivorRow.name, payload: survivorRow.payload, tags: [] } });
+ if (staleSourceReplica) await query("UPDATE catalog_ingredients SET name = 'Stale replica example' WHERE id = $1", [sourceId]);
+ await query(`INSERT INTO catalog_identity_operations (id, source_id, survivor_id, source_owner, survivor_owner, local_owner, state, plan, plan_hash, current_snapshot)
+ VALUES ($1,$2,$3,$4,$5,'identity-test-local',$6,$7::jsonb,'fixture',$8::jsonb)`,
+ [prefix, sourceId, survivorId, sourceOwner, survivorOwner, state, JSON.stringify(plan), JSON.stringify(plain(survivor))]);
+ return { id: prefix, sourceId, survivorId, thirdId, universeId, source, survivor, mediaKey: media[0].media_key, plan };
+}
+
+afterAll(async () => {
+ if (!ready) return;
+ await query('DELETE FROM catalog_identity_operations WHERE id = ANY($1)', [operations]);
+ await query('DELETE FROM catalog_ingredients WHERE id = ANY($1)', [ingredientIds]);
+ await query('DELETE FROM universes WHERE id = ANY($1)', [universes]);
+ await close();
+});
+
+describe.skipIf(!ready)('shared identity catalog integration', () => {
+ it('resolves old IDs and includes owner-only evidence in details, albums, facets and history while export stays original', async () => {
+ const f = await fixture({ staleSourceReplica: true });
+ expect((await catalog.getIngredient(f.sourceId)).id).toBe(f.survivorId);
+ expect((await catalog.resolveIngredientsByIds([f.sourceId, f.survivorId])).map(row => row.id)).toEqual([f.survivorId]);
+ expect((await catalog.listIngredients({ ids: [f.sourceId, f.survivorId] })).items.map(row => row.id)).toEqual([f.survivorId]);
+ expect((await catalog.listIngredients({ refKind: 'universe', refId: f.universeId })).items.map(row => row.id)).toEqual([f.survivorId]);
+ expect((await catalog.getCatalogFacets()).universes.find(row => row.refId === f.universeId).count).toBe(1);
+ expect((await catalog.listIngredientsForRef('universe', f.universeId)).map(row => row.ingredient.id)).toEqual([f.survivorId]);
+ expect(await catalog.listRefsForIngredient(f.survivorId)).toEqual([expect.objectContaining({ ingredientId: f.sourceId, refId: f.universeId })]);
+ expect(await catalog.listMediaForIngredient(f.sourceId)).toEqual([expect.objectContaining({ ingredientId: f.sourceId, mediaKey: f.mediaKey, metadata: { prompt: 'Original example prompt' } })]);
+ expect((await catalog.listRelationsForIngredient(f.survivorId)).outbound).toEqual([expect.objectContaining({ fromId: f.sourceId, toId: f.thirdId })]);
+ expect((await catalog.listIngredientRevisions(f.survivorId)).items.map(row => row.ingredientId).sort()).toEqual([f.sourceId, f.survivorId].sort());
+ expect((await catalog.getCatalogBundleForRef('universe', f.universeId)).ingredients).toEqual([]);
+ const exported = (await catalog.exportSliceForRef('universe', f.universeId)).ingredients;
+ expect(exported).toHaveLength(1);
+ expect(exported[0]).toMatchObject({ id: f.sourceId, name: 'Original Example', originInstanceId: 'identity-test-local',
+ refs: [expect.objectContaining({ ingredientId: f.sourceId, refId: f.universeId })],
+ scraps: [],
+ sources: [{ ingredientId: f.sourceId, scrapId: `${f.id}-missing-scrap`, span: { start: 3, end: 9 }, extractedAt: now }],
+ media: [expect.objectContaining({ ingredientId: f.sourceId, mediaKey: f.mediaKey, metadata: { prompt: 'Original example prompt' }, retained: true })],
+ });
+ expect((await catalog.getIngredientChangesSince('0', 10000)).items.find(row => row.id === f.sourceId)?.name).toBe('Stale replica example');
+ });
+
+ it('refuses foreign and retained-original writes, including delayed attachments, while preserving contextual canon', async () => {
+ const f = await fixture();
+ expect(await getCatalogIdentityAccess(f.sourceId)).toMatchObject({ writable: false, reason: 'CATALOG_IDENTITY_RETAINED' });
+ expect(await getCatalogIdentityAccess(f.survivorId)).toMatchObject({ writable: false, reason: 'CATALOG_IDENTITY_FOREIGN' });
+ for (const change of [
+ () => catalog.updateIngredient(f.survivorId, { name: 'Changed' }),
+ () => catalog.attachMedia(f.survivorId, 'new.png', 'reference'),
+ () => catalog.linkIngredientToRef(f.survivorId, 'universe', f.universeId, 'cast'),
+ () => catalog.updateIngredient(f.sourceId, { name: 'Changed original' }),
+ ]) await expect(change()).rejects.toMatchObject({ status: 409 });
+ const updateUniverse = vi.fn();
+ expect(await projectToCanon(f.sourceId, await catalog.getIngredient(f.sourceId), { updateUniverse })).toEqual({ universes: 0, written: 0, skipped: 1 });
+ expect(updateUniverse).not.toHaveBeenCalled();
+ expect(await projectToCatalog(f.universeId, { characters: [f.sourceId, f.survivorId].map(ingredientId => ({ ingredientId, name: 'Stale context', updatedAt: '2099-01-01T00:00:00Z' })) })).toEqual({ written: 0, skipped: 2 });
+ expect((await query('SELECT id, name FROM catalog_ingredients WHERE id = $1', [f.sourceId])).rows[0]).toEqual({ id: f.sourceId, name: 'Original Example' });
+ });
+
+ it('allows only canonical-owner edits and refuses virtual evidence removal rather than reporting a no-op success', async () => {
+ const f = await fixture({ owned: true });
+ expect(await getCatalogIdentityAccess(f.survivorId)).toMatchObject({ writable: true });
+ await catalog.updateIngredient(f.survivorId, { name: 'Owner revised example' });
+ const remote = { ...(await catalog.getIngredient(f.survivorId)), name: 'Unverified peer edit', updatedAt: '2099-01-01T00:00:00Z' };
+ expect(await catalog.upsertIngredientFromPeer(remote)).toMatchObject({ applied: false, protectedIdentity: true });
+ expect(await catalog.upsertMediaFromPeer({ ingredientId: f.survivorId, mediaKey: 'peer.png', kind: 'reference', createdAt: now })).toMatchObject({ protectedIdentity: true });
+ expect((await catalog.getIngredient(f.survivorId)).name).toBe('Owner revised example');
+ await expect(catalog.updateIngredient(f.sourceId, { name: 'Wrong endpoint' })).rejects.toMatchObject({ code: 'CATALOG_IDENTITY_RETAINED' });
+ await expect(catalog.detachMedia(f.survivorId, f.mediaKey, 'reference')).rejects.toMatchObject({ code: 'CATALOG_IDENTITY_RETAINED' });
+ await expect(catalog.unlinkIngredientFromRef(f.survivorId, 'universe', f.universeId, 'cast')).rejects.toMatchObject({ code: 'CATALOG_IDENTITY_RETAINED' });
+ await expect(catalog.unlinkIngredientRelation(f.survivorId, f.thirdId, 'knows')).rejects.toMatchObject({ code: 'CATALOG_IDENTITY_RETAINED' });
+ await catalog.attachMedia(f.survivorId, 'own-new.png', 'reference');
+ await catalog.detachMedia(f.survivorId, 'own-new.png', 'reference');
+ expect((await catalog.listMediaForIngredient(f.survivorId)).map(row => row.mediaKey)).toEqual([f.mediaKey]);
+ expect((await catalog.listIngredientRevisions(f.survivorId)).items.some(row => row.name === 'Owner revised example')).toBe(true);
+ });
+
+ it('keeps original canonical history across refreshed snapshots and does not resurrect owner-deleted media', async () => {
+ const f = await fixture();
+ await query('UPDATE catalog_identity_operations SET current_snapshot = $2::jsonb WHERE id = $1', [f.id, JSON.stringify({ ...plain(f.survivor), revisions: [] })]);
+ expect((await catalog.listIngredientRevisions(f.survivorId)).items.some(row => row.id === `${f.id}-survivor-revision`)).toBe(true);
+ const owned = await fixture({ owned: true });
+ await query(`UPDATE catalog_identity_operations SET plan = jsonb_set(plan, '{survivor,media}', $2::jsonb) WHERE id = $1`, [owned.id, JSON.stringify([{ ...owned.source.media[0], ingredient_id: owned.survivorId, media_key: 'deleted-owner.png' }])]);
+ expect((await catalog.listMediaForIngredient(owned.survivorId)).some(row => row.mediaKey === 'deleted-owner.png')).toBe(false);
+ });
+
+ it('shows unchosen original image and sheet pointers as attributed retained evidence', async () => {
+ const f = await fixture({ owned: true });
+ const archived = [f.sourceId, f.survivorId].map((ingredient_id, index) => ({
+ ingredient_id, media_key: `unchosen-${index}.png`, kind: 'reference', role: index ? 'sheet:front' : 'archive:identity',
+ caption: 'Preserved original pointer', metadata: {}, created_at: now, deleted: false,
+ }));
+ await query("UPDATE catalog_identity_operations SET plan = jsonb_set(plan, '{archivedMedia}', $2::jsonb) WHERE id = $1", [f.id, JSON.stringify(archived)]);
+ const media = await catalog.listMediaForIngredient(f.survivorId);
+ expect(media.filter(row => row.mediaKey.startsWith('unchosen-'))).toEqual(expect.arrayContaining([
+ expect.objectContaining({ ingredientId: f.sourceId, mediaKey: 'unchosen-0.png', retained: true }),
+ expect.objectContaining({ ingredientId: f.survivorId, mediaKey: 'unchosen-1.png', retained: true }),
+ ]));
+ await expect(catalog.detachMedia(f.survivorId, 'unchosen-1.png', 'reference')).rejects.toMatchObject({ code: 'CATALOG_IDENTITY_RETAINED' });
+ });
+
+ it('fences prepared writes and excludes both shared members from a local merge', async () => {
+ for (const state of ['proposed', 'prepared', 'committed', 'recovery_prepared']) {
+ const f = await fixture({ owned: true, state });
+ await expect(mergeIngredients({ sourceId: f.survivorId, survivorId: f.thirdId })).rejects.toMatchObject({ code: 'CATALOG_IDENTITY_OVERLAP' });
+ if (state === 'prepared' || state === 'recovery_prepared') {
+ await expect(catalog.attachMedia(f.survivorId, 'blocked.png', 'reference')).rejects.toMatchObject({ code: 'CATALOG_IDENTITY_FENCED' });
+ }
+ }
+ });
+
+ it.each([['prepared', 'aborted'], ['recovery_prepared', 'recovered']])('retries a peer update held during %s after %s', async (state, terminal) => {
+ const f = await fixture({ state });
+ const row = (await query('SELECT * FROM catalog_ingredients WHERE id = $1', [f.survivorId])).rows[0];
+ const incoming = { id: row.id, type: row.type, name: 'Owner edit after unfreeze', payload: row.payload,
+ originInstanceId: row.origin_instance_id, createdAt: row.created_at.toISOString(), updatedAt: '2099-01-01T00:00:00Z' };
+ expect(await catalog.upsertIngredientFromPeer(incoming)).toMatchObject({ identityPending: true, applied: false });
+ const media = { ingredientId: row.id, mediaKey: 'late-reference.png', kind: 'reference', createdAt: now };
+ expect(await catalog.upsertMediaFromPeer(media)).toMatchObject({ identityPending: true, applied: false });
+ await query('UPDATE catalog_identity_operations SET state = $2 WHERE id = $1', [f.id, terminal]);
+ expect(await catalog.upsertIngredientFromPeer(incoming)).toMatchObject({ applied: true });
+ await catalog.upsertMediaFromPeer(media);
+ expect((await catalog.getIngredient(f.survivorId)).name).toBe(incoming.name);
+ expect((await catalog.listMediaForIngredient(f.survivorId)).some(item => item.mediaKey === media.mediaKey)).toBe(true);
+ });
+});
diff --git a/server/services/catalogDB.ingredientTimestamps.test.js b/server/services/catalogDB.ingredientTimestamps.test.js
index 0d4577f338..f77339d628 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 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',
+ 'SELECT requested.id, i.updated_at FROM unnest($1::text[]) AS requested(id) JOIN catalog_ingredients i ON i.id = catalog_canonical_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.registry.test.js b/server/services/catalogDB.registry.test.js
index eebbce90ce..8568e38510 100644
--- a/server/services/catalogDB.registry.test.js
+++ b/server/services/catalogDB.registry.test.js
@@ -20,6 +20,7 @@ vi.mock('../lib/db.js', () => ({
// the catalog_ingredients write the assertions read, and no-op the
// revision INSERT / prune DELETE.
const s = sql.trim();
+ if (s.includes('catalog_identity_operations')) return { rows: [] };
if (/^INSERT INTO catalog_ingredient_revisions/i.test(s)) {
const [id, ingredient_id, name] = params;
return {
diff --git a/server/services/catalogDB/facets.js b/server/services/catalogDB/facets.js
index fdf4825d97..075c4236b4 100644
--- a/server/services/catalogDB/facets.js
+++ b/server/services/catalogDB/facets.js
@@ -8,7 +8,7 @@
*/
import { query } from '../../lib/db.js';
-import { rowToRef, rowToIngredient, liveHomingTargetSql, HOMING_REF_KINDS_SQL, groupRowsByIngredient } from './shared.js';
+import { rowToRef, rowToSource, rowToIngredient, liveHomingTargetSql, HOMING_REF_KINDS_SQL, groupRowsByIngredient } from './shared.js';
import { listIngredientsForRef, listRefsForIngredients } from './refs.js';
import { listMediaForIngredients } from './media.js';
@@ -36,14 +36,14 @@ export async function listScrapsForIngredient(ingredientId) {
// row purely to group by; the outer sort key doesn't disturb the per-ingredient
// `created_at ASC` order. Returns `Map<ingredientId, scraps[]>` with an entry
// (possibly `[]`) for every id.
-export async function listScrapsForIngredients(ingredientIds) {
+export async function listScrapsForIngredients(ingredientIds, { includeRetained = false } = {}) {
const ids = [...new Set(ingredientIds)];
if (ids.length === 0) return new Map();
const result = await query(
`SELECT src.ingredient_id, s.id, s.title, s.raw_text, s.source_kind, s.metadata,
s.created_at, s.updated_at
FROM catalog_scraps s
- JOIN catalog_ingredient_sources src ON src.scrap_id = s.id
+ JOIN ${includeRetained ? 'catalog_identity_read_sources' : 'catalog_ingredient_sources'} src ON src.scrap_id = s.id
WHERE src.ingredient_id = ANY($1)
AND s.deleted = false
ORDER BY src.ingredient_id, s.created_at ASC`,
@@ -52,6 +52,21 @@ export async function listScrapsForIngredients(ingredientIds) {
return groupRowsByIngredient(ids, result.rows, rowToExportScrap);
}
+// Source provenance survives even when a foreign scrap's body was never copied.
+async function listExportSourcesForIngredients(ingredientIds) {
+ const ids = [...new Set(ingredientIds)];
+ if (ids.length === 0) return new Map();
+ const result = await query(
+ `SELECT * FROM catalog_identity_read_sources
+ WHERE ingredient_id = ANY($1) ORDER BY ingredient_id, extracted_at ASC`,
+ [ids],
+ );
+ return groupRowsByIngredient(ids, result.rows, row => {
+ const { syncSequence: _syncSequence, ...source } = rowToSource(row);
+ return source;
+ });
+}
+
/**
* Build an export bundle for one ref (universe/series/issue/work).
* Hydrates each ingredient + its scraps + ref links + media attachments. The
@@ -61,15 +76,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, { 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 rows = await listIngredientsForRef(refKind, refId, { preserveIdentity: true, includeRetained: true });
+ // Hydrate the whole slice in batches (#3940), including source links whose
+ // scrap bodies are unavailable locally. Five queries total, regardless of N.
const ingredientIds = rows.map(({ ingredient }) => ingredient.id);
- const [scrapsById, refsById, mediaById] = await Promise.all([
- listScrapsForIngredients(ingredientIds),
- listRefsForIngredients(ingredientIds, { preserveIdentity: true }),
- listMediaForIngredients(ingredientIds, { preserveIdentity: true }),
+ const [scrapsById, refsById, mediaById, sourcesById] = await Promise.all([
+ listScrapsForIngredients(ingredientIds, { includeRetained: true }),
+ listRefsForIngredients(ingredientIds, { preserveIdentity: true, includeRetained: true }),
+ listMediaForIngredients(ingredientIds, { preserveIdentity: true, includeRetained: true }),
+ listExportSourcesForIngredients(ingredientIds),
]);
const ingredients = rows.map(({ ingredient, role }) => {
const { embedding: _embedding, ...rest } = ingredient;
@@ -81,6 +96,7 @@ export async function exportSliceForRef(refKind, refId) {
roleForExportedRef: role,
refs: refsById.get(ingredient.id) || [],
scraps: scrapsById.get(ingredient.id) || [],
+ sources: sourcesById.get(ingredient.id) || [],
media: mediaById.get(ingredient.id) || [],
};
});
@@ -134,11 +150,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 AND id = catalog_resolve_ingredient_id(id) GROUP BY type`),
+ query(`SELECT type, COUNT(*) AS count FROM catalog_ingredients WHERE deleted = false AND id = catalog_canonical_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 id = catalog_resolve_ingredient_id(id) AND embedding IS NOT NULL`),
+ query(`SELECT COUNT(*) AS count FROM catalog_ingredients WHERE deleted = false AND id = catalog_canonical_ingredient_id(id) AND embedding IS NOT NULL`),
]);
const byType = {};
let total = 0;
@@ -164,28 +180,28 @@ 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 AND id = catalog_resolve_ingredient_id(id)
+ FROM catalog_ingredients WHERE deleted = false AND id = catalog_canonical_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:
// distinct ingredients linked to the universe OR to a live series under it.
- query(`SELECT u.id AS ref_id, u.name, COUNT(DISTINCT r.ingredient_id)::int AS count
+ query(`SELECT u.id AS ref_id, u.name, COUNT(DISTINCT catalog_canonical_ingredient_id(r.ingredient_id))::int AS count
FROM universes u
- JOIN catalog_ingredient_refs r ON r.deleted = false AND (
+ JOIN catalog_identity_read_refs r ON r.deleted = false AND (
(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 AND i.id = catalog_resolve_ingredient_id(i.id)
+ JOIN catalog_ingredients i ON i.id = catalog_canonical_ingredient_id(r.ingredient_id) AND i.deleted = false AND i.id = catalog_canonical_ingredient_id(i.id)
WHERE u.deleted = false
GROUP BY u.id, u.name ORDER BY count DESC, u.name`),
- query(`SELECT s.id AS ref_id, s.name, s.universe_id, COUNT(DISTINCT r.ingredient_id)::int AS count
- FROM catalog_ingredient_refs r
- JOIN catalog_ingredients i ON i.id = r.ingredient_id AND i.deleted = false AND i.id = catalog_resolve_ingredient_id(i.id)
+ query(`SELECT s.id AS ref_id, s.name, s.universe_id, COUNT(DISTINCT catalog_canonical_ingredient_id(r.ingredient_id))::int AS count
+ FROM catalog_identity_read_refs r
+ JOIN catalog_ingredients i ON i.id = catalog_canonical_ingredient_id(r.ingredient_id) AND i.deleted = false AND i.id = catalog_canonical_ingredient_id(i.id)
JOIN pipeline_series s ON s.id = r.ref_id AND s.deleted = false
WHERE r.deleted = false AND r.ref_kind = 'series'
GROUP BY s.id, s.name, s.universe_id ORDER BY count DESC, s.name`),
query(`SELECT tag, COUNT(*)::int AS count
- FROM (SELECT unnest(tags) AS tag FROM catalog_ingredients WHERE deleted = false AND id = catalog_resolve_ingredient_id(id)) t
+ FROM (SELECT unnest(tags) AS tag FROM catalog_ingredients WHERE deleted = false AND id = catalog_canonical_ingredient_id(id)) t
GROUP BY tag ORDER BY count DESC, tag`),
// Per-ingredient bucket classification. ref_count = live homing ref ROWS
// (universe/series/creative-director); live_count = those whose target still
@@ -202,9 +218,9 @@ export async function getCatalogFacets() {
COUNT(r.ref_id) AS ref_count,
COUNT(r.ref_id) FILTER (WHERE ${liveHomingTargetSql('r')}) AS live_count
FROM catalog_ingredients i
- LEFT JOIN catalog_ingredient_refs r
- ON r.ingredient_id = i.id AND r.deleted = false AND r.ref_kind IN (${HOMING_REF_KINDS_SQL})
- WHERE i.deleted = false AND i.id = catalog_resolve_ingredient_id(i.id)
+ LEFT JOIN catalog_identity_read_refs r
+ ON catalog_canonical_ingredient_id(r.ingredient_id) = i.id AND r.deleted = false AND r.ref_kind IN (${HOMING_REF_KINDS_SQL})
+ WHERE i.deleted = false AND i.id = catalog_canonical_ingredient_id(i.id)
GROUP BY i.id
) sub`),
]);
diff --git a/server/services/catalogDB/identityAccess.js b/server/services/catalogDB/identityAccess.js
new file mode 100644
index 0000000000..bdee2ad0dc
--- /dev/null
+++ b/server/services/catalogDB/identityAccess.js
@@ -0,0 +1,72 @@
+// Shared identity reads may resolve across owners; ordinary writes may not.
+// Durable database fences enforce the same rule across the preflight/write gap.
+import { query } from '../../lib/db.js';
+import { ServerError } from '../../lib/errorHandler.js';
+import { getInstanceId } from '../instanceIdentity.js';
+
+export async function getCatalogIdentityAccess(id, { client } = {}) {
+ const exec = client ? client.query.bind(client) : query;
+ const { rows } = await exec(`SELECT o.id, o.state, o.source_id, o.survivor_id,
+ o.source_owner, o.survivor_owner, o.local_owner, i.origin_instance_id,
+ catalog_resolve_ingredient_id($1) AS requested_id
+ FROM catalog_identity_operations o
+ LEFT JOIN catalog_ingredients i ON i.id = o.survivor_id
+ WHERE (o.source_id = catalog_resolve_ingredient_id($1) OR o.survivor_id = catalog_resolve_ingredient_id($1))
+ AND o.state IN ('prepared', 'committed', 'recovery_prepared')`, [id]);
+ if (!rows.length) return null;
+ const row = rows[0];
+ const localId = await getInstanceId();
+ const reason = rows.some(item => item.state !== 'committed') ? 'CATALOG_IDENTITY_FENCED'
+ : rows.some(item => item.source_id === item.requested_id) ? 'CATALOG_IDENTITY_RETAINED'
+ : rows.some(item => !item.origin_instance_id || item.origin_instance_id !== localId) ? 'CATALOG_IDENTITY_FOREIGN' : null;
+ return { operationId: row.id, sourceId: row.source_id, survivorId: row.survivor_id,
+ sourceOwner: row.source_owner, survivorOwner: row.survivor_owner, localOwner: row.local_owner,
+ state: row.state, writable: reason === null, reason };
+}
+
+export async function assertCatalogIdentityWritable(id, options) {
+ const access = await getCatalogIdentityAccess(id, options);
+ if (!access || access.writable) return id;
+ const messages = {
+ CATALOG_IDENTITY_FENCED: 'This identity is awaiting coordinated completion or recovery',
+ CATALOG_IDENTITY_RETAINED: 'This original is retained; select the canonical identity to edit',
+ CATALOG_IDENTITY_FOREIGN: 'Edit this shared identity on its canonical owner',
+ };
+ throw new ServerError(messages[access.reason], { status: 409, code: access.reason });
+}
+
+// A retained association is visible evidence, not a mutable row on the survivor.
+// Refuse instead of reporting success for a zero-row removal that would reappear.
+export async function assertCatalogAssociationRemovable(id, kind, values) {
+ const selectors = {
+ media: ['catalog_ingredient_media', ['media_key', 'kind']],
+ refs: ['catalog_ingredient_refs', ['ref_kind', 'ref_id', 'role']],
+ };
+ const [table, columns] = selectors[kind];
+ const match = columns.map((column, i) => `retained.${column} = $${i + 2}`).join(' AND ');
+ const ownMatch = columns.map(column => `live.${column} = retained.${column}`).join(' AND ');
+ const { rows } = await query(`SELECT 1 FROM catalog_identity_operations o
+ JOIN catalog_identity_read_${kind} retained ON retained.identity_retained = true
+ AND retained.ingredient_id IN (o.source_id, o.survivor_id)
+ WHERE o.survivor_id = catalog_canonical_ingredient_id($1)
+ AND o.state IN ('committed', 'recovery_prepared') AND retained.deleted = false AND ${match}
+ AND NOT EXISTS (SELECT 1 FROM ${table} live WHERE live.ingredient_id = o.survivor_id
+ AND live.deleted = false AND ${ownMatch}) LIMIT 1`, [id, ...values]);
+ if (rows.length) throw new ServerError('This association is retained original evidence and cannot be removed', {
+ status: 409, code: 'CATALOG_IDENTITY_RETAINED',
+ });
+}
+
+export async function assertCatalogRelationRemovable(fromId, toId, kind) {
+ const { rows } = await query(`SELECT 1 FROM catalog_identity_read_relations retained
+ JOIN catalog_identity_operations o ON (o.source_id = retained.from_id OR o.source_id = retained.to_id)
+ WHERE o.state IN ('committed', 'recovery_prepared') AND retained.deleted = false
+ AND catalog_canonical_ingredient_id(retained.from_id) = catalog_canonical_ingredient_id($1)
+ AND catalog_canonical_ingredient_id(retained.to_id) = catalog_canonical_ingredient_id($2)
+ AND retained.kind = $3 AND NOT EXISTS (SELECT 1 FROM catalog_ingredient_relations live
+ WHERE live.from_id = catalog_resolve_ingredient_id($1) AND live.to_id = catalog_resolve_ingredient_id($2)
+ AND live.kind = $3 AND live.deleted = false) LIMIT 1`, [fromId, toId, kind]);
+ if (rows.length) throw new ServerError('This relation is retained original evidence and cannot be removed', {
+ status: 409, code: 'CATALOG_IDENTITY_RETAINED',
+ });
+}
diff --git a/server/services/catalogDB/ingredients.js b/server/services/catalogDB/ingredients.js
index 695ccd3f7c..5b07ad4476 100644
--- a/server/services/catalogDB/ingredients.js
+++ b/server/services/catalogDB/ingredients.js
@@ -29,6 +29,7 @@ import {
liveHomingTargetSql,
} from './shared.js';
import { normalizeTags } from './tags.js';
+import { assertCatalogIdentityWritable } from './identityAccess.js';
// `{ client }` is optional — when supplied, SQL runs on the caller's transaction
// client (so the write rolls back if a later step in the same `withTransaction`
@@ -99,7 +100,7 @@ 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 = catalog_resolve_ingredient_id($1) AND deleted = false`,
+ `SELECT * FROM catalog_ingredients WHERE id = catalog_canonical_ingredient_id($1) AND deleted = false`,
[id],
);
return rowToIngredient(result.rows[0]);
@@ -108,9 +109,7 @@ export async function getIngredient(id, { client } = {}) {
// 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]);
+ const { rows } = await query('SELECT unnest(catalog_identity_member_ids($1)) AS id', [id]);
return rows.map(row => row.id);
}
@@ -127,7 +126,9 @@ export async function getIngredientTimestamps(ingredientIds, { excludeAliases =
if (ids.length === 0) return new Map();
const result = await query(
`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' : ''}`,
+ JOIN catalog_ingredients i ON i.id = catalog_canonical_ingredient_id(requested.id) AND i.deleted = false${excludeAliases ? ` AND requested.id = i.id AND NOT EXISTS (SELECT 1 FROM catalog_identity_operations o
+ WHERE (o.source_id = i.id OR o.survivor_id = i.id) AND
+ (o.state IN ('prepared', 'recovery_prepared') OR (o.state = 'committed' AND o.local_owner <> o.survivor_owner)))` : ''}`,
[ids],
);
return new Map(result.rows.map((row) => [row.id, row.updated_at.toISOString()]));
@@ -145,6 +146,7 @@ export async function updateIngredient(id, patch = {}, { client, source = 'user'
if (touchedContent && !client) {
return withTransaction((tx) => updateIngredient(id, patch, { client: tx, source, actor }));
}
+ id = await assertCatalogIdentityWritable(id, { client });
const exec = client ? client.query.bind(client) : query;
const fields = [];
const params = [];
@@ -258,9 +260,8 @@ export async function recordIngredientRevision(ingredient, { source = 'user', ac
export async function listIngredientRevisions(ingredientId, { limit = 50, offset = 0 } = {}) {
const result = await query(
- `SELECT * FROM catalog_ingredient_revisions
- WHERE (ingredient_id = 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))
+ `SELECT * FROM catalog_identity_read_revisions
+ WHERE ingredient_id = ANY(catalog_identity_member_ids($1))
ORDER BY created_at DESC, id DESC
LIMIT $2 OFFSET $3`,
[ingredientId, Math.min(Math.max(limit, 1), 200), Math.max(offset, 0)],
@@ -270,13 +271,14 @@ export async function listIngredientRevisions(ingredientId, { limit = 50, offset
export async function getIngredientRevision(revisionId) {
const result = await query(
- `SELECT * FROM catalog_ingredient_revisions WHERE id = $1`,
+ `SELECT * FROM catalog_identity_read_revisions WHERE id = $1`,
[revisionId],
);
return rowToRevision(result.rows[0]);
}
export async function deleteIngredient(id, { hard = false } = {}) {
+ id = await assertCatalogIdentityWritable(id);
if (hard) {
await query(`DELETE FROM catalog_ingredients WHERE id = $1`, [id]);
} else {
@@ -299,6 +301,7 @@ export async function deleteIngredient(id, { hard = false } = {}) {
export async function reviveDeletedIngredient(id, { type, name, payload = {}, tags = [] } = {}) {
if (!type || !getActiveCatalogType(type)) throw new Error(`reviveDeletedIngredient: invalid type ${type}`);
if (!name || !String(name).trim()) throw new Error('reviveDeletedIngredient: name required');
+ id = await assertCatalogIdentityWritable(id);
// Re-stamp the payload schemaVersion on revive — the revived row is being
// rewritten with a fresh payload, so it gets this install's current marker
// (mirrors createIngredient).
@@ -330,8 +333,8 @@ const INGREDIENT_LIGHT_COLS = 'id, type, name, payload, tags, embedding_model, o
// reference sheets (`sheet:*`), looks (`look:*`) and plates — never become the
// cover. Used only by listIngredients' light path (see the note there).
const THUMBNAIL_KEY_SUBQUERY = `(
- SELECT m.media_key FROM catalog_ingredient_media m
- WHERE m.ingredient_id = catalog_ingredients.id
+ SELECT m.media_key FROM catalog_identity_read_media m
+ WHERE catalog_canonical_ingredient_id(m.ingredient_id) = catalog_ingredients.id
AND m.deleted = false
AND m.kind IN ('portrait', 'reference')
AND (m.role IS NULL OR NOT (m.role LIKE 'sheet:%' OR m.role LIKE 'look:%' OR m.role LIKE 'archive:%' OR m.role = 'plate'))
@@ -344,15 +347,15 @@ const THUMBNAIL_KEY_SUBQUERY = `(
// as the thumbnail subquery.
const REF_USAGE_SUBQUERY = `(
SELECT jsonb_object_agg(u.ref_kind, u.n) FROM (
- SELECT r.ref_kind, COUNT(DISTINCT r.ref_id) AS n FROM catalog_ingredient_refs r
- WHERE r.ingredient_id = catalog_ingredients.id AND r.deleted = false
+ SELECT r.ref_kind, COUNT(DISTINCT r.ref_id) AS n FROM catalog_identity_read_refs r
+ WHERE catalog_canonical_ingredient_id(r.ingredient_id) = catalog_ingredients.id AND r.deleted = false
AND (r.ref_kind NOT IN (${HOMING_REF_KINDS_SQL}) OR ${liveHomingTargetSql('r')})
GROUP BY r.ref_kind
) u
) 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', 'id = catalog_resolve_ingredient_id(id)'];
+ const conditions = ['deleted = false', 'id = catalog_canonical_ingredient_id(id)'];
const params = [];
let idx = 1;
// Batch-fetch by id (Story Builder catalog→series linking, #1761). When
@@ -361,7 +364,7 @@ export async function listIngredients({ ids, type, tag, query: q, refKind = null
const byIds = Array.isArray(ids) && ids.length > 0;
let qIdx = null;
if (byIds) {
- conditions.push(`id IN (SELECT catalog_resolve_ingredient_id(requested) FROM unnest($${idx++}::text[]) requested)`);
+ conditions.push(`id IN (SELECT catalog_canonical_ingredient_id(requested) FROM unnest($${idx++}::text[]) requested)`);
params.push(ids);
} else {
if (type) {
@@ -388,15 +391,15 @@ export async function listIngredients({ ids, type, tag, query: q, refKind = null
// ingredient must still land in its parent universe). $refId is referenced
// twice via one placeholder.
const refIdx = idx++;
- conditions.push(`EXISTS (SELECT 1 FROM catalog_ingredient_refs r
- WHERE r.ingredient_id = catalog_ingredients.id AND r.deleted = false
+ conditions.push(`EXISTS (SELECT 1 FROM catalog_identity_read_refs r
+ WHERE catalog_canonical_ingredient_id(r.ingredient_id) = catalog_ingredients.id AND r.deleted = false
AND ((r.ref_kind = 'universe' AND r.ref_id = $${refIdx})
OR (r.ref_kind = 'series' AND r.ref_id IN (
SELECT id FROM pipeline_series WHERE universe_id = $${refIdx} AND deleted = false))))`);
params.push(refId);
} else if (refKind && refId) {
- conditions.push(`EXISTS (SELECT 1 FROM catalog_ingredient_refs r
- WHERE r.ingredient_id = catalog_ingredients.id AND r.deleted = false
+ conditions.push(`EXISTS (SELECT 1 FROM catalog_identity_read_refs r
+ WHERE catalog_canonical_ingredient_id(r.ingredient_id) = catalog_ingredients.id AND r.deleted = false
AND r.ref_kind = $${idx++} AND r.ref_id = $${idx++})`);
params.push(refKind, refId);
} else if (unlinked) {
@@ -413,8 +416,8 @@ export async function listIngredients({ ids, type, tag, query: q, refKind = null
// so it composes with any of them (unlike unlinked/orphaned/refKind, which
// are mutually exclusive album views enforced at the schema level).
if (scrapId) {
- conditions.push(`EXISTS (SELECT 1 FROM catalog_ingredient_sources cis
- WHERE catalog_resolve_ingredient_id(cis.ingredient_id) = catalog_ingredients.id AND cis.scrap_id = $${idx++})`);
+ conditions.push(`EXISTS (SELECT 1 FROM catalog_identity_read_sources cis
+ WHERE catalog_canonical_ingredient_id(cis.ingredient_id) = catalog_ingredients.id AND cis.scrap_id = $${idx++})`);
params.push(scrapId);
}
if (embeddingMissing) {
@@ -459,7 +462,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', 'id = catalog_resolve_ingredient_id(id)', 'embedding IS NOT NULL'];
+ const conditions = ['deleted = false', 'id = catalog_canonical_ingredient_id(id)', 'embedding IS NOT NULL'];
const params = [arrayToPgvector(vector), threshold, limit];
let idx = 4;
if (type) {
@@ -488,7 +491,7 @@ export async function findIngredientsByName(type, names) {
if (!type || !keys.length) return [];
const result = await query(
`SELECT * FROM catalog_ingredients
- WHERE deleted = false AND id = catalog_resolve_ingredient_id(id) AND type = $1
+ WHERE deleted = false AND id = catalog_canonical_ingredient_id(id) AND type = $1
AND (lower(btrim(name)) = ANY($2)
OR (jsonb_typeof(payload->'aliases') = 'array'
AND EXISTS (SELECT 1 FROM jsonb_array_elements_text(payload->'aliases') a WHERE lower(btrim(a)) = ANY($2))))
@@ -500,7 +503,7 @@ export async function findIngredientsByName(type, names) {
export async function searchIngredientsByText(q, { type, limit = 20 } = {}) {
if (!q) return [];
- const conditions = ['deleted = false', 'id = catalog_resolve_ingredient_id(id)', `search_tsv @@ websearch_to_tsquery('english', $1)`];
+ const conditions = ['deleted = false', 'id = catalog_canonical_ingredient_id(id)', `search_tsv @@ websearch_to_tsquery('english', $1)`];
const params = [q, limit];
let idx = 3;
if (type) {
@@ -531,7 +534,7 @@ export async function hybridSearchIngredients(queryText, queryEmbedding, options
let ftsRows = [];
if (queryText) {
- const conds = ['deleted = false', 'id = catalog_resolve_ingredient_id(id)', `search_tsv @@ websearch_to_tsquery('english', $1)`];
+ const conds = ['deleted = false', 'id = catalog_canonical_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); }
@@ -546,7 +549,7 @@ export async function hybridSearchIngredients(queryText, queryEmbedding, options
let vecRows = [];
if (queryEmbedding) {
- const conds = ['deleted = false', 'id = catalog_resolve_ingredient_id(id)', 'embedding IS NOT NULL', '1 - (embedding <=> $1) >= $2'];
+ const conds = ['deleted = false', 'id = catalog_canonical_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); }
@@ -585,7 +588,7 @@ export async function resolveIngredientsByIds(ids) {
.map((id) => id.trim()))];
if (list.length === 0) return [];
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
+ JOIN catalog_ingredients i ON i.id = catalog_canonical_ingredient_id(requested.id) AND i.deleted = false
ORDER BY requested.ordinality`, [list]);
return [...new Map(rows.map(row => [row.id, rowToIngredient(row)])).values()];
}
diff --git a/server/services/catalogDB/media.js b/server/services/catalogDB/media.js
index 20653caf0a..c3f743dcaa 100644
--- a/server/services/catalogDB/media.js
+++ b/server/services/catalogDB/media.js
@@ -10,7 +10,8 @@
import { query, withTransaction } from '../../lib/db.js';
import { resolveImageInputPath } from '../../lib/fileUtils.js';
-import { rowToMedia, groupRowsByIngredient } from './shared.js';
+import { rowToMedia } from './shared.js';
+import { assertCatalogIdentityWritable, assertCatalogAssociationRemovable } from './identityAccess.js';
const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value || {}, key);
const hasMeaningfulMetadata = (value) => value && typeof value === 'object'
@@ -20,6 +21,7 @@ export async function attachMedia(ingredientId, mediaKey, kind, options = {}) {
// Every local portrait entry point shares the replacement transaction,
// including the generic media API and file uploads.
if (kind === 'portrait') return setPortraitMedia(ingredientId, mediaKey, options);
+ ingredientId = await assertCatalogIdentityWritable(ingredientId, options);
return insertMedia(options.client ? options.client.query.bind(options.client) : query, ingredientId, mediaKey, kind, options);
}
@@ -48,6 +50,8 @@ async function insertMedia(runQuery, ingredientId, mediaKey, kind, options) {
}
export async function detachMedia(ingredientId, mediaKey, kind) {
+ ingredientId = await assertCatalogIdentityWritable(ingredientId);
+ await assertCatalogAssociationRemovable(ingredientId, 'media', [mediaKey, kind]);
// Soft-delete (mirrors unlinkIngredientRelation): keep the row as a tombstone
// so the sync_sequence bump propagates the detach to peers. `AND deleted =
// false` keeps a re-detach from re-bumping the sequence needlessly.
@@ -64,6 +68,7 @@ export async function detachMedia(ingredientId, mediaKey, kind) {
// attachment commit together, so overlapping HTTP/generation writes serialize
// and a failed replacement leaves the previous portrait intact.
export async function setPortraitMedia(ingredientId, mediaKey, options = {}) {
+ ingredientId = await assertCatalogIdentityWritable(ingredientId, options);
const replace = async (client) => {
await client.query('SELECT id FROM catalog_ingredients WHERE id = catalog_resolve_ingredient_id($1) FOR UPDATE', [ingredientId]);
await client.query(
@@ -90,19 +95,23 @@ 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, { preserveIdentity = false } = {}) {
+export async function listMediaForIngredients(ingredientIds, { preserveIdentity = false, includeRetained = false } = {}) {
const ids = [...new Set(ingredientIds)];
if (ids.length === 0) return new Map();
const result = await query(
- preserveIdentity ? `SELECT * FROM catalog_ingredient_media
+ preserveIdentity ? `SELECT * FROM ${includeRetained ? `(SELECT * FROM catalog_identity_read_media UNION ALL
+ SELECT m.*, false AS identity_retained FROM catalog_ingredient_media m
+ WHERE m.ingredient_id <> catalog_resolve_ingredient_id(m.ingredient_id)) exported_media` : 'catalog_ingredient_media'}
WHERE ingredient_id = ANY($1) AND deleted = false
ORDER BY ingredient_id, (kind = 'portrait') DESC, created_at DESC` : `SELECT m.*, requested.id AS requested_id FROM unnest($1::text[]) requested(id)
- JOIN catalog_ingredient_media m ON m.ingredient_id = catalog_resolve_ingredient_id(requested.id)
+ JOIN catalog_identity_read_media m ON m.ingredient_id = ANY(catalog_identity_member_ids(requested.id))
WHERE m.deleted = false
ORDER BY ingredient_id, (kind = 'portrait') DESC, created_at DESC`,
[ids],
);
- return groupRowsByIngredient(ids, result.rows.map(row => ({ ...row, ingredient_id: row.requested_id ?? row.ingredient_id })), rowToMedia);
+ const grouped = new Map(ids.map(id => [id, []]));
+ for (const row of result.rows) grouped.get(row.requested_id ?? row.ingredient_id)?.push(rowToMedia(row));
+ return grouped;
}
// The media kinds whose `media_key` resolves against the image library today.
diff --git a/server/services/catalogDB/merge.js b/server/services/catalogDB/merge.js
index 74085592d7..ced7cbb3f0 100644
--- a/server/services/catalogDB/merge.js
+++ b/server/services/catalogDB/merge.js
@@ -71,7 +71,7 @@ async function lockState(client, ids, writing) {
// 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(`LOCK TABLE ${Object.values(TABLES).map(([table]) => table).join(', ')}, catalog_identity_operations, 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]);
}
@@ -87,6 +87,10 @@ export async function mergeIngredients(input) {
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 shared = await client.query(`SELECT id FROM catalog_identity_operations
+ WHERE state IN ('proposed', 'prepared', 'committed', 'recovery_prepared')
+ AND (source_id = ANY($1) OR survivor_id = ANY($1))`, [ids]);
+ if (shared.rowCount) fail('Complete or recover the shared identity operation before merging either identity', 'CATALOG_IDENTITY_OVERLAP');
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);
diff --git a/server/services/catalogDB/refs.js b/server/services/catalogDB/refs.js
index aee5717ed3..5460a2d081 100644
--- a/server/services/catalogDB/refs.js
+++ b/server/services/catalogDB/refs.js
@@ -12,12 +12,21 @@
import { query } from '../../lib/db.js';
import { resolveRefs } from '../catalogRefResolver.js';
-import { rowToRef, rowToSource, rowToIngredient, groupRowsByIngredient } from './shared.js';
+import { assertCatalogIdentityWritable, assertCatalogAssociationRemovable, assertCatalogRelationRemovable } from './identityAccess.js';
+import { rowToRef, rowToSource, rowToIngredient } from './shared.js';
+
+// Canonical detail views omit local-merge originals; original-ID user exports
+// retain those raw rows alongside the bilateral receipt-backed evidence.
+const exportRefRows = `(SELECT * FROM catalog_identity_read_refs UNION ALL
+ SELECT r.*, false AS identity_retained FROM catalog_ingredient_refs r
+ WHERE r.ingredient_id <> catalog_resolve_ingredient_id(r.ingredient_id))`;
+
// `{ client }` is optional — see the createIngredient comment. Passing the same
// client used to insert the ingredient row keeps the source-link row in the
// same transaction so a mid-batch failure rolls back both halves.
export async function linkIngredientToSource(ingredientId, scrapId, span = null, { client, preserveExisting = false } = {}) {
+ ingredientId = await assertCatalogIdentityWritable(ingredientId, { client });
const exec = client ? client.query.bind(client) : query;
await exec(
`INSERT INTO catalog_ingredient_sources (ingredient_id, scrap_id, span)
@@ -34,9 +43,9 @@ export async function linkIngredientToSource(ingredientId, scrapId, span = null,
export async function listSourcesForIngredient(ingredientId) {
const result = await query(
`SELECT s.*, sc.title AS scrap_title
- FROM catalog_ingredient_sources s
+ FROM catalog_identity_read_sources s
LEFT JOIN catalog_scraps sc ON sc.id = s.scrap_id
- WHERE catalog_resolve_ingredient_id(s.ingredient_id) = catalog_resolve_ingredient_id($1)`,
+ WHERE catalog_canonical_ingredient_id(s.ingredient_id) = catalog_canonical_ingredient_id($1)`,
[ingredientId],
);
return result.rows.map((row) => ({ ...rowToSource(row), scrapTitle: row.scrap_title ?? null }));
@@ -61,9 +70,9 @@ export async function listSiblingIngredientsBySource(ingredientId, scrapIds) {
if (ids.length === 0) return new Map();
const result = await query(
`SELECT DISTINCT s.scrap_id, i.id, i.name, i.type
- FROM catalog_ingredient_sources s
- JOIN catalog_ingredients i ON i.id = catalog_resolve_ingredient_id(s.ingredient_id)
- WHERE s.scrap_id = ANY($1) AND i.id != catalog_resolve_ingredient_id($2) AND i.deleted = false
+ FROM catalog_identity_read_sources s
+ JOIN catalog_ingredients i ON i.id = catalog_canonical_ingredient_id(s.ingredient_id)
+ WHERE s.scrap_id = ANY($1) AND i.id != catalog_canonical_ingredient_id($2) AND i.deleted = false
ORDER BY i.name ASC`,
[ids, ingredientId],
);
@@ -78,6 +87,7 @@ export async function listSiblingIngredientsBySource(ingredientId, scrapIds) {
// client used to insert the ingredient row keeps the ref link in the same
// transaction so a mid-batch failure rolls back both halves (#7615).
export async function linkIngredientToRef(ingredientId, refKind, refId, role, { client } = {}) {
+ ingredientId = await assertCatalogIdentityWritable(ingredientId, { client });
// ON CONFLICT DO UPDATE revives a soft-deleted row instead of leaving it
// tombstoned. The trigger only bumps sync_sequence when `deleted` or
// `deleted_at` actually change, so a link-on-active-row stays a no-op for
@@ -165,6 +175,8 @@ export async function linkIngredientsToCreativeDirector(projectId, ingredients =
}
export async function unlinkIngredientFromRef(ingredientId, refKind, refId, role) {
+ ingredientId = await assertCatalogIdentityWritable(ingredientId);
+ await assertCatalogAssociationRemovable(ingredientId, 'refs', [refKind, refId, role]);
// Soft-delete via UPDATE so the row stays around as a tombstone and the
// trg_catalog_ref_sync_seq trigger bumps sync_sequence — peers pick the
// unlink up on their next pull. The `AND deleted = false` filter keeps
@@ -189,18 +201,20 @@ 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, { preserveIdentity = false } = {}) {
+export async function listRefsForIngredients(ingredientIds, { preserveIdentity = false, includeRetained = false } = {}) {
const ids = [...new Set(ingredientIds)];
if (ids.length === 0) return new Map();
const result = await query(
- preserveIdentity ? `SELECT * FROM catalog_ingredient_refs
+ preserveIdentity ? `SELECT * FROM ${includeRetained ? `${exportRefRows} exported_refs` : '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)
+ JOIN catalog_identity_read_refs r ON r.ingredient_id = ANY(catalog_identity_member_ids(requested.id))
WHERE r.deleted = false
ORDER BY ingredient_id`,
[ids],
);
- return groupRowsByIngredient(ids, result.rows.map(row => ({ ...row, ingredient_id: row.requested_id ?? row.ingredient_id })), rowToRef);
+ const grouped = new Map(ids.map(id => [id, []]));
+ for (const row of result.rows) grouped.get(row.requested_id ?? row.ingredient_id)?.push(rowToRef(row));
+ return grouped;
}
// Like listRefsForIngredient, but drops refs whose TARGET no longer resolves to
@@ -218,13 +232,33 @@ export async function listLiveRefsForIngredient(ingredientId) {
return refs.filter((_, i) => resolved[i]?.resolved === true);
}
-export async function listIngredientsForRef(refKind, refId, { preserveIdentity = false } = {}) {
+// Only human-requested exports use original owner snapshots. Federation feeds
+// and bundles retain their existing raw-table contract. No permanent view is
+// needed for the ingredient row type (which must remain freely migratable).
+const exportIngredientCte = `WITH active AS (
+ SELECT * FROM catalog_identity_operations WHERE state IN ('committed', 'recovery_prepared')
+), candidates AS (
+ SELECT jsonb_populate_record(NULL::catalog_ingredients, item) AS r, 0 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.plan->'source'->'ingredients', '[]'::jsonb)) item
+ UNION ALL
+ SELECT live AS r, 1 AS priority FROM catalog_ingredients live
+ WHERE NOT EXISTS (SELECT 1 FROM active o WHERE live.id = o.source_id
+ OR (o.local_owner <> o.survivor_owner AND live.id = o.survivor_id))
+ UNION ALL
+ SELECT jsonb_populate_record(NULL::catalog_ingredients, item) AS r, 2 AS priority
+ FROM active o CROSS JOIN LATERAL jsonb_array_elements(COALESCE(o.current_snapshot->'ingredients', o.plan->'survivor'->'ingredients', '[]'::jsonb)) item
+ WHERE o.local_owner <> o.survivor_owner
+), export_ingredients AS (
+ SELECT DISTINCT ON ((r).id) (r).* FROM candidates ORDER BY (r).id, priority
+) `;
+
+export async function listIngredientsForRef(refKind, refId, { preserveIdentity = false, includeRetained = false } = {}) {
const result = await query(
- `SELECT i.*, r.role, r.created_at AS ref_created_at
- FROM catalog_ingredients i
- JOIN catalog_ingredient_refs r ON r.ingredient_id = i.id
+ `${includeRetained ? exportIngredientCte : ''}SELECT DISTINCT i.*, r.role
+ FROM ${includeRetained ? 'export_ingredients' : 'catalog_ingredients'} i
+ JOIN ${includeRetained ? exportRefRows : preserveIdentity ? 'catalog_ingredient_refs' : 'catalog_identity_read_refs'} r ON ${preserveIdentity ? 'r.ingredient_id' : 'catalog_canonical_ingredient_id(r.ingredient_id)'} = i.id
WHERE r.ref_kind = $1 AND r.ref_id = $2
- AND r.deleted = false AND i.deleted = false${preserveIdentity ? '' : ' AND i.id = catalog_resolve_ingredient_id(i.id)'}`,
+ AND r.deleted = false AND i.deleted = false${preserveIdentity ? '' : ' AND i.id = catalog_canonical_ingredient_id(i.id)'}`,
[refKind, refId],
);
return result.rows.map((row) => ({ ingredient: rowToIngredient(row), role: row.role }));
@@ -241,6 +275,8 @@ export async function listIngredientsForRef(refKind, refId, { preserveIdentity =
// client used to insert the ingredient rows keeps the relation edge in the
// same transaction so a mid-batch failure rolls back both halves (#7615).
export async function linkIngredientRelation(fromId, toId, kind, { client } = {}) {
+ fromId = await assertCatalogIdentityWritable(fromId, { client });
+ toId = await assertCatalogIdentityWritable(toId, { client });
if (fromId === toId) throw new Error('cannot relate an ingredient to itself');
const exec = client ? client.query.bind(client) : query;
const result = await exec(
@@ -255,6 +291,9 @@ export async function linkIngredientRelation(fromId, toId, kind, { client } = {}
}
export async function unlinkIngredientRelation(fromId, toId, kind) {
+ fromId = await assertCatalogIdentityWritable(fromId);
+ toId = await assertCatalogIdentityWritable(toId);
+ await assertCatalogRelationRemovable(fromId, toId, kind);
// Soft-delete (mirrors unlinkIngredientFromRef): keep the row as a tombstone
// so the sync_sequence bump propagates the unlink to peers. `AND deleted =
// false` keeps a re-unlink from re-bumping the sequence needlessly.
@@ -277,18 +316,18 @@ export async function listRelationsForIngredient(id) {
query(
`SELECT r.from_id, r.to_id, r.kind, r.created_at,
i.name AS other_name, i.type AS other_type
- FROM catalog_ingredient_relations r
- JOIN catalog_ingredients i ON i.id = r.to_id
- WHERE r.from_id = catalog_resolve_ingredient_id($1) AND r.deleted = false AND i.deleted = false AND i.id = catalog_resolve_ingredient_id(i.id)
+ FROM catalog_identity_read_relations r
+ JOIN catalog_ingredients i ON i.id = catalog_canonical_ingredient_id(r.to_id)
+ WHERE r.from_id = ANY(catalog_identity_member_ids($1)) AND r.deleted = false AND i.deleted = false AND i.id = catalog_canonical_ingredient_id(i.id)
ORDER BY r.created_at ASC`,
[id],
),
query(
`SELECT r.from_id, r.to_id, r.kind, r.created_at,
i.name AS other_name, i.type AS other_type
- FROM catalog_ingredient_relations r
- JOIN catalog_ingredients i ON i.id = r.from_id
- WHERE r.to_id = catalog_resolve_ingredient_id($1) AND r.deleted = false AND i.deleted = false AND i.id = catalog_resolve_ingredient_id(i.id)
+ FROM catalog_identity_read_relations r
+ JOIN catalog_ingredients i ON i.id = catalog_canonical_ingredient_id(r.from_id)
+ WHERE r.to_id = ANY(catalog_identity_member_ids($1)) AND r.deleted = false AND i.deleted = false AND i.id = catalog_canonical_ingredient_id(i.id)
ORDER BY r.created_at ASC`,
[id],
),
diff --git a/server/services/catalogDB/shared.js b/server/services/catalogDB/shared.js
index 7dcf57c1c3..4f1f3b3b78 100644
--- a/server/services/catalogDB/shared.js
+++ b/server/services/catalogDB/shared.js
@@ -165,6 +165,7 @@ export function rowToMedia(row) {
if (!row) return null;
return {
ingredientId: row.ingredient_id,
+ ...(row.identity_retained ? { retained: true } : {}),
mediaKey: row.media_key,
kind: row.kind,
role: row.role ?? null,
@@ -257,13 +258,13 @@ export const liveHomingTargetSql = (r) => `(
// SQL predicate matching ingredients that have at least one LIVE homing ref
// (target row still resolves).
export const HAS_LIVE_HOMING_REF = `EXISTS (
- SELECT 1 FROM catalog_ingredient_refs r
- WHERE r.ingredient_id = catalog_ingredients.id AND r.deleted = false
+ SELECT 1 FROM catalog_identity_read_refs r
+ WHERE catalog_canonical_ingredient_id(r.ingredient_id) = catalog_ingredients.id AND r.deleted = false
AND ${liveHomingTargetSql('r')})`;
// At least one homing ref row exists (live OR dangling) — distinguishes
// "orphaned" (has a ref, none resolve) from "unlinked" (no ref at all).
export const HAS_ANY_HOMING_REF = `EXISTS (
- SELECT 1 FROM catalog_ingredient_refs r
- WHERE r.ingredient_id = catalog_ingredients.id AND r.deleted = false
+ SELECT 1 FROM catalog_identity_read_refs r
+ WHERE catalog_canonical_ingredient_id(r.ingredient_id) = catalog_ingredients.id AND r.deleted = false
AND r.ref_kind IN (${HOMING_REF_KINDS_SQL}))`;
diff --git a/server/services/catalogDB/sync.js b/server/services/catalogDB/sync.js
index b4d4d720b1..7cb7470ef6 100644
--- a/server/services/catalogDB/sync.js
+++ b/server/services/catalogDB/sync.js
@@ -17,7 +17,7 @@
* peer's own clock. See `upsertRefFromPeer` for the full rationale.
*/
-import { query, arrayToPgvector } from '../../lib/db.js';
+import { query, withTransaction, arrayToPgvector } from '../../lib/db.js';
import {
rowToScrap,
rowToIngredient,
@@ -53,6 +53,7 @@ export const getRelationChangesSince = (since = '0', limit = 100) =>
getFeedChangesSince('catalog_ingredient_relations', rowToRelation, since, limit);
export async function upsertRelationFromPeer(rel) {
+ return withPeerIdentityWrite([rel.fromId, rel.toId], async (query) => {
// Mirrors upsertRefFromPeer's mixed-version handling: a peer that predates
// the relations feature never emits these rows, so there's no v1-without-
// tombstone shape to defend against here. But we still treat "key absent"
@@ -91,12 +92,14 @@ export async function upsertRelationFromPeer(rel) {
[rel.fromId, rel.toId, rel.kind, rel.createdAt],
);
}
+ });
}
export const getMediaChangesSince = (since = '0', limit = 100) =>
getFeedChangesSince('catalog_ingredient_media', rowToMedia, since, limit);
export async function upsertMediaFromPeer(media) {
+ return withPeerIdentityWrite([media.ingredientId], async (query) => {
// Mirrors upsertRefFromPeer's mixed-version handling: a peer that predates
// the media feature never emits these rows, so there's no pre-tombstone
// shape to defend against. We still treat "tombstone keys absent" as "peer
@@ -153,6 +156,7 @@ export async function upsertMediaFromPeer(media) {
[media.ingredientId, media.mediaKey, media.kind, media.role ?? null, media.caption ?? null, media.createdAt, ...metadataParam],
);
}
+ });
}
export const getTagChangesSince = (since = '0', limit = 100) =>
@@ -284,6 +288,7 @@ export async function upsertScrapFromPeer(scrap) {
}
export async function upsertIngredientFromPeer(ing) {
+ return withPeerIdentityWrite([ing.id], async (query) => {
const result = await query(
`INSERT INTO catalog_ingredients
(id, type, name, payload, tags, embedding, embedding_model,
@@ -318,18 +323,22 @@ export async function upsertIngredientFromPeer(ing) {
],
);
return { applied: result.rows.length > 0, isInsert: result.rows[0]?.is_insert ?? false };
+ });
}
export async function upsertSourceFromPeer(src) {
+ return withPeerIdentityWrite([src.ingredientId], async (query) => {
await query(
`INSERT INTO catalog_ingredient_sources (ingredient_id, scrap_id, span, extracted_at)
VALUES ($1, $2, $3::jsonb, $4)
ON CONFLICT (ingredient_id, scrap_id) DO UPDATE SET span = EXCLUDED.span`,
[src.ingredientId, src.scrapId, src.span ? JSON.stringify(src.span) : null, src.extractedAt],
);
+ });
}
export async function upsertRefFromPeer(ref) {
+ return withPeerIdentityWrite([ref.ingredientId], async (query) => {
// ON CONFLICT DO UPDATE so a peer's soft-delete (or revival) of a ref row
// is mirrored locally. Refs are tuple-unique (no editable content fields),
// so `updated_at` exists ONLY as a tombstone/revival change-clock (#8347),
@@ -390,6 +399,7 @@ export async function upsertRefFromPeer(ref) {
[ref.ingredientId, ref.refKind, ref.refId, ref.role, ref.createdAt],
);
}
+ });
}
// The inbox is db-primary, receiver-local, and covered by the normal DB backup.
@@ -442,3 +452,16 @@ export async function drainPendingCatalogApplies() {
} while (progressed);
}
}
+
+async function withPeerIdentityWrite(ids, write) {
+ return withTransaction(async client => {
+ const exec = client.query.bind(client);
+ await exec("SELECT set_config('portos.catalog_identity_peer_apply', 'on', true)");
+ const { rows } = await exec(`SELECT id, state FROM catalog_identity_operations
+ WHERE state IN ('prepared', 'committed', 'recovery_prepared')
+ AND (source_id = ANY($1::text[]) OR survivor_id = ANY($1::text[]))`, [ids]);
+ if (rows.length) return { applied: false, isInsert: false, protectedIdentity: true,
+ identityPending: rows.some(row => row.state !== 'committed') };
+ return write(exec);
+ });
+}
diff --git a/server/services/catalogDBMedia.test.js b/server/services/catalogDBMedia.test.js
index c452725271..aedc9709a8 100644
--- a/server/services/catalogDBMedia.test.js
+++ b/server/services/catalogDBMedia.test.js
@@ -20,6 +20,7 @@ const calls = [];
vi.mock('../lib/db.js', () => ({
query: vi.fn(async (sql, params) => {
+ if (sql.includes('catalog_identity_operations') || sql.includes('set_config(')) return { rows: [] };
calls.push({ sql: sql.replace(/\s+/g, ' ').trim(), params });
// Echo a media row back so rowToMedia works for the RETURNING * paths.
return {
@@ -195,7 +196,7 @@ describe('listIngredients card thumbnail', () => {
const sql = db.query.mock.calls.at(-1)[0].replace(/\s+/g, ' ');
// The correlated subquery prefers a live portrait, then the most recent
// live reference, and excludes unrenderable (audio/video/document) kinds.
- expect(sql).toMatch(/FROM catalog_ingredient_media m/i);
+ expect(sql).toMatch(/FROM catalog_identity_read_media m/i);
expect(sql).toMatch(/m\.kind IN \('portrait', 'reference'\)/i);
expect(sql).toMatch(/ORDER BY \(m\.kind = 'portrait'\) DESC, m\.created_at DESC/i);
expect(sql).toMatch(/AS thumbnail_key/i);
diff --git a/server/services/catalogIdentity/events.js b/server/services/catalogIdentity/events.js
new file mode 100644
index 0000000000..1af692f1d1
--- /dev/null
+++ b/server/services/catalogIdentity/events.js
@@ -0,0 +1,2 @@
+import { EventEmitter } from 'node:events';
+export const catalogIdentityEvents = new EventEmitter();
diff --git a/server/services/catalogIdentity/index.js b/server/services/catalogIdentity/index.js
new file mode 100644
index 0000000000..819a04ae4b
--- /dev/null
+++ b/server/services/catalogIdentity/index.js
@@ -0,0 +1,299 @@
+import { randomUUID } from 'node:crypto';
+import { query, withTransaction } from '../../lib/db.js';
+import { snapshot, lockCatalog, ingredient, assertUnlocked, buildPlan, hash, fail, validateSnapshot } from './snapshots.js';
+import { localIdentity, identityPeer, readEvidence, revalidateEvidence } from './transport.js';
+
+const db = { query };
+const idsOf = row => [row.source_id, row.survivor_id];
+const peerOf = row => row.local_owner === row.source_owner ? row.survivor_owner : row.source_owner;
+const coordinator = row => row.local_owner === row.survivor_owner;
+const ACTIVE = ['proposed', 'prepared', 'committed', 'recovery_prepared'];
+export function present(row, full = true) {
+ const value = { id: row.id, sourceId: row.source_id, survivorId: row.survivor_id,
+ sourceOwner: row.source_owner, survivorOwner: row.survivor_owner, localOwner: row.local_owner,
+ state: row.state, epoch: row.epoch, planHash: row.plan_hash, peerState: row.peer_state,
+ peerObservedAt: row.peer_observed_at, createdAt: row.created_at, updatedAt: row.updated_at };
+ return full ? { ...value, plan: row.plan, beforeState: row.before_state,
+ appliedFingerprint: row.applied_fingerprint, currentSnapshot: row.current_snapshot, recovery: row.recovery } : value;
+}
+async function load(client, id) {
+ const { rows: [row] } = await client.query('SELECT * FROM catalog_identity_operations WHERE id = $1', [id]);
+ if (!row) fail('Identity receipt not found', 'CATALOG_IDENTITY_NOT_FOUND', 404);
+ return row;
+}
+async function revalidate(row, self, client, fullSnapshot = true) {
+ if (row.local_owner !== self) fail('Receipt belongs to a different local owner');
+ await identityPeer(peerOf(row));
+ const current = fullSnapshot ? await snapshot(client, idsOf(row)) : { ingredients: (await client.query(
+ 'SELECT id,origin_instance_id,deleted FROM catalog_ingredients WHERE id=ANY($1)', [idsOf(row)])).rows };
+ for (const [id, owner] of [[row.source_id, row.source_owner], [row.survivor_id, row.survivor_owner]]) {
+ const member = ingredient(current, id);
+ if (member.origin_instance_id !== owner) fail('Ingredient owner changed', 'CATALOG_IDENTITY_STALE');
+ }
+ return current;
+}
+async function noOverlap(client, ids, except = '') {
+ const active = await client.query(`SELECT id FROM catalog_identity_operations WHERE id <> $2
+ AND state = ANY($3) AND (source_id = ANY($1) OR survivor_id = ANY($1))
+ UNION ALL SELECT id FROM catalog_ingredient_merges WHERE restored_at IS NULL
+ AND (source_id = ANY($1) OR survivor_id = ANY($1))`, [ids, except, ACTIVE]);
+ if (active.rowCount) fail('Either identity already participates in an active consolidation');
+}
+function binding(row, remote) {
+ if (!remote || remote.id !== row.id || remote.planHash !== row.plan_hash || hash(remote.plan) !== row.plan_hash
+ || remote.sourceId !== row.source_id || remote.survivorId !== row.survivor_id
+ || remote.sourceOwner !== row.source_owner || remote.survivorOwner !== row.survivor_owner
+ || remote.localOwner !== peerOf(row)) fail('Peer receipt does not match the accepted owner pair', 'CATALOG_IDENTITY_EVIDENCE_INVALID');
+}
+async function update(client, row, state, epoch, extra = {}) {
+ const columns = { state, epoch, ...extra };
+ const values = [row.id];
+ const sets = Object.entries(columns).map(([key, value]) => {
+ values.push(value && typeof value === 'object' ? JSON.stringify(value) : value);
+ return `${key} = $${values.length}`;
+ });
+ await client.query(`UPDATE catalog_identity_operations SET ${sets.join(', ')}, updated_at = NOW() WHERE id = $1`, values);
+ return present(await load(client, row.id));
+}
+async function writeContent(client, row, original = false) {
+ await client.query("SELECT set_config('portos.catalog_identity_operation', $1, true)", [row.id]);
+ const content = original ? ingredient(row.before_state, row.survivor_id) : row.plan.proposed;
+ await client.query(`UPDATE catalog_ingredients SET name = $2, payload = $3::jsonb, tags = $4,
+ embedding = NULL, embedding_model = NULL WHERE id = $1`,
+ [row.survivor_id, content.name, JSON.stringify(content.payload), content.tags]);
+ await client.query(`INSERT INTO catalog_ingredient_revisions (id, ingredient_id, name, payload, tags, source, actor)
+ VALUES ($1, $2, $3, $4::jsonb, $5, 'user', $6)`,
+ [`cat-rev-${randomUUID()}`, row.survivor_id, content.name, JSON.stringify(content.payload), content.tags,
+ original ? 'catalog-identity-recovery' : 'catalog-shared-identity']);
+}
+async function adoptContent(client, row, content) {
+ await client.query("SELECT set_config('portos.catalog_identity_operation', $1, true)", [row.id]);
+ // Adoption is not a newly authored creative revision. The receipt and owner
+ // snapshot retain the actual revision identity and owner timestamp.
+ await client.query(`UPDATE catalog_ingredients SET name=$2,payload=$3::jsonb,tags=$4,updated_at=$5,
+ embedding=NULL,embedding_model=NULL WHERE id=$1`,
+ [row.survivor_id, content.name, JSON.stringify(content.payload), content.tags, content.updated_at]);
+}
+export async function listIdentityOperations({ ingredientId, limit = 20, offset = 0 } = {}) {
+ const { rows } = await query(`SELECT id, source_id, survivor_id, source_owner, survivor_owner, local_owner,
+ state, epoch, plan_hash, peer_state, peer_observed_at, created_at, updated_at FROM catalog_identity_operations
+ WHERE ($1::text IS NULL OR source_id = $1 OR survivor_id = $1)
+ ORDER BY created_at DESC, id DESC LIMIT $2 OFFSET $3`, [ingredientId ?? null, limit + 1, offset]);
+ return { items: rows.slice(0, limit).map(row => present(row, false)), nextOffset: rows.length > limit ? offset + limit : null };
+}
+export async function getIdentityOperation(id) { return present(await load(db, id)); }
+export async function ownerSnapshot(id, self = null) {
+ self ??= await localIdentity();
+ const value = await withTransaction(async client => { await lockCatalog(client); return snapshot(client, [id]); });
+ if (ingredient(value, id).origin_instance_id !== self) fail('Only the original owner may attest this identity', 'CATALOG_IDENTITY_FOREIGN');
+ return value;
+}
+export async function previewIdentity({ operationId, sourceId, survivorId, fieldChoices }) {
+ const self = await localIdentity();
+ const local = await snapshot(db, [sourceId, survivorId]);
+ const source = ingredient(local, sourceId);
+ const survivor = ingredient(local, survivorId);
+ if (survivor.origin_instance_id !== self) fail('Create the plan on the selected survivor owner', 'CATALOG_IDENTITY_COORDINATOR_REQUIRED');
+ if (source.origin_instance_id === self) fail('Use local consolidation for same-owner ingredients');
+ const authoritative = await readEvidence(source.origin_instance_id, 'snapshot', sourceId);
+ validateSnapshot(authoritative, sourceId, source.origin_instance_id);
+ return buildPlan(authoritative, await ownerSnapshot(survivorId, self), fieldChoices, operationId);
+}
+export async function createIdentity(input) {
+ const self = await localIdentity();
+ const replay = await query('SELECT * FROM catalog_identity_operations WHERE id=$1 AND local_owner=$2', [input.operationId, self]);
+ if (replay.rowCount) {
+ const row = replay.rows[0];
+ if (row.plan_hash !== input.planHash || row.source_id !== input.sourceId || row.survivor_id !== input.survivorId || hash(row.plan.fieldChoices) !== hash(input.fieldChoices ?? {})) fail('Retry must name the same reviewed plan');
+ return present(row);
+ }
+ const preview = await previewIdentity(input);
+ if (preview.planHash !== input.planHash) fail('Preview changed; review both owner snapshots again', 'CATALOG_IDENTITY_STALE');
+ if (preview.conflicts.length) fail('Resolve every populated field conflict');
+ return withTransaction(async client => {
+ await lockCatalog(client);
+ const { plan } = preview;
+ if (await localIdentity() !== self) fail('Local owner changed');
+ await identityPeer(plan.sourceOwner);
+ await revalidateEvidence(plan.source);
+ const existing = await client.query('SELECT * FROM catalog_identity_operations WHERE id = $1 AND local_owner = $2', [input.operationId, self]);
+ if (existing.rowCount) {
+ if (existing.rows[0].plan_hash !== preview.planHash) fail('Operation ID already names a different plan');
+ return present(existing.rows[0]);
+ }
+ await noOverlap(client, [plan.sourceId, plan.survivorId]);
+ if (hash(await snapshot(client, [plan.survivorId])) !== hash(plan.survivor)) fail('Survivor changed', 'CATALOG_IDENTITY_STALE');
+ const id = input.operationId;
+ await client.query(`INSERT INTO catalog_identity_operations
+ (id, source_id, survivor_id, source_owner, survivor_owner, local_owner, state, plan, plan_hash)
+ VALUES ($1,$2,$3,$4,$5,$6,'proposed',$7::jsonb,$8)`,
+ [id, plan.sourceId, plan.survivorId, plan.sourceOwner, plan.survivorOwner, self, JSON.stringify(plan), preview.planHash]);
+ return present(await load(client, id));
+ });
+}
+export async function importIdentity({ peerId, operationId }) {
+ const self = await localIdentity();
+ const remote = await readEvidence(peerId, 'status', operationId);
+ if (remote.localOwner !== peerId || remote.survivorOwner !== peerId || remote.sourceOwner !== self
+ || !['proposed', 'prepared'].includes(remote.state) || hash(remote.plan) !== remote.planHash) fail('Import requires a proposed plan from its canonical owner');
+ validateSnapshot(remote.plan.source, remote.sourceId, self);
+ validateSnapshot(remote.plan.survivor, remote.survivorId, peerId);
+ const rebuilt = buildPlan(remote.plan.source, remote.plan.survivor, remote.plan.fieldChoices, remote.id);
+ if (rebuilt.planHash !== remote.planHash || rebuilt.conflicts.length) fail('Owner plan is invalid');
+ return withTransaction(async client => {
+ await lockCatalog(client);
+ await revalidateEvidence(remote);
+ const old = await client.query('SELECT * FROM catalog_identity_operations WHERE id = $1', [operationId]);
+ if (old.rowCount) {
+ binding(old.rows[0], remote);
+ return present(old.rows[0]);
+ }
+ await noOverlap(client, [remote.sourceId, remote.survivorId]);
+ const local = await snapshot(client, [remote.sourceId, remote.survivorId]);
+ if (ingredient(local, remote.sourceId).origin_instance_id !== self
+ || ingredient(local, remote.survivorId).origin_instance_id !== peerId
+ || hash(await snapshot(client, [remote.sourceId])) !== hash(remote.plan.source)) fail('Source revision or local owner pair changed', 'CATALOG_IDENTITY_STALE');
+ await client.query(`INSERT INTO catalog_identity_operations
+ (id,source_id,survivor_id,source_owner,survivor_owner,local_owner,state,plan,plan_hash)
+ VALUES ($1,$2,$3,$4,$5,$6,'proposed',$7::jsonb,$8)`,
+ [operationId, remote.sourceId, remote.survivorId, self, peerId, self, JSON.stringify(remote.plan), remote.planHash]);
+ return present(await load(client, operationId));
+ });
+}
+export async function acceptIdentity(id, planHash) {
+ const initial = await load(db, id);
+ const self = await localIdentity();
+ const peerSnapshot = await readEvidence(peerOf(initial), 'snapshot', coordinator(initial) ? initial.source_id : initial.survivor_id);
+ const remote = await readEvidence(peerOf(initial), 'status', id);
+ binding(initial, remote);
+ return withTransaction(async client => {
+ await lockCatalog(client);
+ const row = await load(client, id);
+ const current = await revalidate(row, self, client);
+ await revalidateEvidence(peerSnapshot);
+ await revalidateEvidence(remote);
+ if (row.plan_hash !== planHash) fail('Accept the exact reviewed plan hash');
+ if (row.state !== 'proposed') return present(row);
+ if (!['proposed', 'prepared'].includes(remote.state) || remote.epoch !== 0) fail('Peer has already decided or cancelled this operation; advance its receipt');
+ const own = coordinator(row) ? row.plan.survivor : row.plan.source;
+ const foreign = coordinator(row) ? row.plan.source : row.plan.survivor;
+ validateSnapshot(peerSnapshot, foreign.ingredients[0].id, peerOf(row));
+ if (hash(peerSnapshot) !== hash(foreign) || hash(await snapshot(client, [own.ingredients[0].id])) !== hash(own)) {
+ fail('Owner revision changed; abort and review a new plan', 'CATALOG_IDENTITY_STALE');
+ }
+ current.ingredients.forEach(assertUnlocked);
+ await noOverlap(client, idsOf(row), id);
+ return update(client, row, 'prepared', 0, { before_state: current });
+ });
+}
+export async function abortIdentity(id) {
+ const self = await localIdentity();
+ return withTransaction(async client => {
+ await lockCatalog(client);
+ const row = await load(client, id);
+ if (row.local_owner !== self) fail('Receipt belongs to a different local owner');
+ if (row.state === 'aborted') return present(row);
+ if (row.state !== 'proposed' && !(coordinator(row) && row.state === 'prepared')) {
+ fail('Only the coordinator may abort a prepared operation; advance to read its durable decision');
+ }
+ return update(client, row, 'aborted', 1);
+ });
+}
+export async function prepareIdentityRecovery(id, planHash) {
+ const initial = await load(db, id);
+ const self = await localIdentity();
+ const remote = await readEvidence(peerOf(initial), 'status', id);
+ binding(initial, remote);
+ return withTransaction(async client => {
+ await lockCatalog(client);
+ const row = await load(client, id);
+ const current = await revalidate(row, self, client);
+ await revalidateEvidence(remote);
+ if (row.plan_hash !== planHash) fail('Recovery must name the accepted plan');
+ if (['recovery_prepared', 'recovered'].includes(row.state)) return present(row);
+ if (row.state !== 'committed' || row.epoch !== 1) fail('Only a committed identity can prepare recovery');
+ if (coordinator(row) ? remote.state !== 'committed' : remote.state !== 'recovery_prepared' || remote.epoch !== 2) {
+ fail('Both owners must adopt first; prepare recovery on the canonical owner before the source owner');
+ }
+ if (hash(current) !== row.applied_fingerprint) fail('Applied state changed; recovery cannot overwrite later work', 'CATALOG_IDENTITY_STALE');
+ return update(client, row, 'recovery_prepared', 2, { recovery: { appliedFingerprint: row.applied_fingerprint } });
+ });
+}
+export async function advanceIdentity(id) {
+ const initial = await load(db, id);
+ const self = await localIdentity();
+ const remote = await readEvidence(peerOf(initial), 'status', id);
+ binding(initial, remote);
+ const refresh = initial.state === 'committed' && !coordinator(initial) && remote.state === 'committed'
+ ? await readEvidence(initial.survivor_owner, 'snapshot', initial.survivor_id) : null;
+ return withTransaction(async client => {
+ await lockCatalog(client);
+ const row = await load(client, id);
+ if (row.local_owner !== self) fail('Receipt belongs to a different local owner');
+ await revalidateEvidence(remote);
+ if (refresh) await revalidateEvidence(refresh);
+ const observation = { peer_state: remote.state, peer_observed_at: new Date().toISOString() };
+ if (['aborted', 'recovered'].includes(row.state)) return update(client, row, row.state, row.epoch, observation);
+ if (['proposed', 'prepared'].includes(row.state) && remote.state === 'aborted' && remote.epoch === 1) {
+ return update(client, row, 'aborted', 1, observation);
+ }
+ const current = await revalidate(row, self, client, ['prepared', 'recovery_prepared'].includes(row.state));
+ const commit = row.state === 'prepared' && (coordinator(row)
+ ? remote.state === 'prepared' && remote.epoch === 0
+ : remote.state === 'committed' && remote.epoch === 1);
+ if (commit) {
+ if (hash(current) !== hash(row.before_state)) fail('Prepared state changed', 'CATALOG_IDENTITY_STALE');
+ if (coordinator(row)) await writeContent(client, row);
+ const canonical = coordinator(row) ? await snapshot(client, [row.survivor_id]) : remote.currentSnapshot;
+ validateSnapshot(canonical, row.survivor_id, row.survivor_owner);
+ // The source adopts only the coordinator's durable decision and exact
+ // canonical content. Source originals and all their associations stay put.
+ if (!coordinator(row)) {
+ const content = ingredient(canonical, row.survivor_id);
+ await adoptContent(client, row, content);
+ }
+ return update(client, row, 'committed', 1, { ...observation, current_snapshot: canonical,
+ applied_fingerprint: hash(await snapshot(client, idsOf(row))) });
+ }
+ const recover = row.state === 'recovery_prepared' && (coordinator(row)
+ ? remote.state === 'recovery_prepared' && remote.epoch === 2
+ : remote.state === 'recovered' && remote.epoch === 3);
+ if (recover) {
+ if (hash(current) !== row.recovery?.appliedFingerprint) fail('Recovery reservation changed', 'CATALOG_IDENTITY_STALE');
+ if (coordinator(row)) await writeContent(client, row, true);
+ else await adoptContent(client, row, ingredient(row.before_state, row.survivor_id));
+ return update(client, row, 'recovered', 3, observation);
+ }
+ if (row.state === 'committed' && !coordinator(row) && remote.state === 'committed' && remote.epoch === 1) {
+ const canonical = refresh;
+ if (!canonical) fail('Canonical owner snapshot missing');
+ // Refresh is explicit and authenticated. Ordinary LWW is never trusted
+ // to overwrite a protected pair, including records from a third peer.
+ validateSnapshot(canonical, row.survivor_id, row.survivor_owner);
+ const value = ingredient(canonical, row.survivor_id);
+ if (value.origin_instance_id !== row.survivor_owner) fail('Canonical owner changed');
+ if (hash(canonical) !== hash(row.current_snapshot)) {
+ await adoptContent(client, row, value);
+ }
+ // Do not move the original recovery baseline forward after later edits.
+ return update(client, row, row.state, row.epoch, { ...observation, current_snapshot: canonical });
+ }
+ return update(client, row, row.state, row.epoch, observation);
+ });
+}
+export async function peerIdentityStatus(id, callerId) {
+ const self = await localIdentity();
+ return withTransaction(async client => {
+ await lockCatalog(client);
+ const row = await load(client, id);
+ if (['aborted', 'recovered'].includes(row.state)) {
+ if (row.local_owner !== self) fail('Receipt belongs to a different local owner');
+ await identityPeer(peerOf(row));
+ } else await revalidate(row, self, client, false);
+ if (peerOf(row) !== callerId) fail('Only the other accepted owner may read this receipt', 'CATALOG_IDENTITY_PEER_FORBIDDEN', 403);
+ // The immutable decision snapshot remains readable even if later owner
+ // edits exceed snapshot transfer capacity. Refresh uses its separate read.
+ return { ...present(row, false), plan: row.plan, currentSnapshot: row.current_snapshot,
+ appliedFingerprint: row.applied_fingerprint };
+ });
+}
diff --git a/server/services/catalogIdentity/protocol.db.test.js b/server/services/catalogIdentity/protocol.db.test.js
new file mode 100644
index 0000000000..bb3efa6c03
--- /dev/null
+++ b/server/services/catalogIdentity/protocol.db.test.js
@@ -0,0 +1,228 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import * as db from '../../lib/db.js';
+import { requireDbOrSkip } from '../../lib/dbTestGate.js';
+import { catalogDdl } from '../../lib/db/schema/catalog.js';
+import { catalogIdentityDdl } from '../../lib/db/schema/catalogIdentity.js';
+import { buildCatalogIdentityViewsDdl } from '../../lib/db/schema/catalogIdentityViews.js';
+
+const context = new AsyncLocalStorage();
+const fixture = vi.hoisted(() => ({ runtime: null }));
+vi.mock('../../lib/db.js', async original => {
+ const actual = await original();
+ return { ...actual,
+ query: (...args) => fixture.runtime ? actual.withTransaction(async client => {
+ await client.query(`SET LOCAL search_path TO ${fixture.runtime.schema()}, public`);
+ return client.query(...args);
+ }) : actual.query(...args),
+ withTransaction: fn => actual.withTransaction(async client => {
+ if (fixture.runtime) await client.query(`SET LOCAL search_path TO ${fixture.runtime.schema()}, public`);
+ return fn(client);
+ }),
+ };
+});
+vi.mock('../instanceIdentity.js', () => ({ getInstanceId: async () => fixture.runtime.owner(), UNKNOWN_INSTANCE_ID: 'unknown' }));
+vi.mock('../sharing/peerSyncShared.js', () => ({
+ findPeerById: async id => fixture.runtime.peer(id),
+ peerAllowsOutbound: peer => peer.enabled !== false && peer.syncEnabled !== false && peer.directions.includes('outbound'),
+ peerAllowsCategoryPull: peer => peer.syncCategories.catalog === true,
+}));
+vi.mock('../../lib/peerHttpClient.js', async original => ({ ...await original(), peerFetch: (...args) => fixture.runtime.fetch(...args) }));
+const protocol = await import('./index.js');
+const transport = await import('./transport.js');
+const actual = await vi.importActual('../../lib/db.js');
+const health = await actual.checkHealth().catch(error => ({ connected: false, error: error.message }));
+const ready = requireDbOrSkip('bilateral canonical identity protocol', health.connected, health.error);
+const runId = randomUUID().replaceAll('-', '');
+const owners = ['fixture-source', 'fixture-canonical'];
+const schemas = Object.fromEntries(owners.map((owner, i) => [owner, `identity_${runId}_${i}`]));
+const configs = {};
+let offline = false;
+let corrupt = false;
+let wireHook = null;
+const as = (owner, fn) => context.run(owner, fn);
+const sql = (owner, text, args = []) => as(owner, () => db.query(text, args));
+function resetPeers() {
+ offline = false; corrupt = false; wireHook = null;
+ for (const owner of owners) configs[owner] = { instanceId: owner, host: `${owner}.invalid`, port: 5555,
+ syncSecret: 'fake-fixture-pair-secret-never-used-outside-tests', auth: { password: 'fake-must-never-send' },
+ enabled: true, syncEnabled: true, directions: ['inbound', 'outbound'], syncCategories: { catalog: true } };
+}
+beforeAll(async () => {
+ if (!ready) return;
+ resetPeers();
+ for (const schema of Object.values(schemas)) {
+ await actual.query(`CREATE SCHEMA ${schema}`);
+ await actual.withTransaction(async client => {
+ await client.query(`SET LOCAL search_path TO ${schema}, public`);
+ for (const statement of [...catalogDdl, ...catalogIdentityDdl, ...buildCatalogIdentityViewsDdl()]) await client.query(statement);
+ });
+ }
+ fixture.runtime = {
+ owner: () => context.getStore(), schema: () => schemas[context.getStore()],
+ peer: id => configs[id] ? structuredClone(configs[id]) : null,
+ fetch: async (url, options, peer) => {
+ if (offline) throw new Error('fixture peer offline');
+ expect(peer.auth).toBeUndefined(); expect(options.headers.Authorization).toBeUndefined();
+ const caller = context.getStore(); const target = peer.instanceId; const parsed = new URL(url);
+ return as(target, async () => {
+ const authenticated = await transport.authenticateIdentityPeer({ headers: {
+ 'x-portos-instance-id': caller, 'x-portos-peer-auth': options.headers['X-PortOS-Peer-Auth'] } });
+ const kind = parsed.pathname.endsWith('/snapshot') ? 'snapshot' : 'status';
+ const id = parsed.searchParams.get(kind === 'snapshot' ? 'ingredientId' : 'operationId');
+ const value = kind === 'snapshot' ? await protocol.ownerSnapshot(id) : await protocol.peerIdentityStatus(id, caller);
+ const response = transport.signEvidence(authenticated, { owner: target,
+ challenge: parsed.searchParams.get('challenge'), kind, target: id, value });
+ if (corrupt) response.challenge = 'f'.repeat(64);
+ if (wireHook) wireHook(response);
+ return new Response(JSON.stringify(response), { status: 200, headers: { 'Content-Type': 'application/json' } });
+ });
+ },
+ };
+});
+afterAll(async () => {
+ fixture.runtime = null;
+ if (ready) for (const schema of Object.values(schemas)) await actual.query(`DROP SCHEMA IF EXISTS ${schema} CASCADE`);
+ await actual.close();
+});
+async function pair() {
+ resetPeers(); const sourceId = `source-${randomUUID()}`; const survivorId = `survivor-${randomUUID()}`;
+ for (const owner of owners) for (const [id, origin, name, description] of [
+ [sourceId, owners[0], 'Fixture musician', 'Original biography'], [survivorId, owners[1], 'Fixture performer', 'Performance canon'],
+ ]) {
+ await sql(owner, `INSERT INTO catalog_ingredients(id,type,name,payload,tags,origin_instance_id,created_at,updated_at)
+ VALUES ($1,'character',$2,$3::jsonb,ARRAY['fixture'],$4,'2026-01-01','2026-01-01')`,
+ [id, name, JSON.stringify({ locked: false, description, primaryImageRef: `${id}.png` }), origin]);
+ await sql(owner, `INSERT INTO catalog_ingredient_revisions(id,ingredient_id,name,payload,created_at)
+ VALUES ($1,$2,$3,$4::jsonb,'2026-01-01')`, [`${id}-revision-${owner}`, id, name, JSON.stringify({ description })]);
+ }
+ return { operationId: randomUUID(), sourceId, survivorId, fieldChoices: { '/name': 'survivor', '/payload/description': 'source', '/payload/primaryImageRef': 'survivor' } };
+}
+async function propose(input) {
+ const preview = await as(owners[1], () => protocol.previewIdentity(input)); expect(preview.conflicts).toEqual([]);
+ const receipt = await as(owners[1], () => protocol.createIdentity({ ...input, planHash: preview.planHash }));
+ await as(owners[0], () => protocol.importIdentity({ peerId: owners[1], operationId: receipt.id })); return receipt;
+}
+async function prepare(receipt) {
+ await as(owners[1], () => protocol.acceptIdentity(receipt.id, receipt.planHash));
+ await as(owners[0], () => protocol.acceptIdentity(receipt.id, receipt.planHash));
+}
+async function commit(receipt) {
+ await prepare(receipt); await as(owners[1], () => protocol.advanceIdentity(receipt.id)); await as(owners[0], () => protocol.advanceIdentity(receipt.id));
+}
+describe.skipIf(!ready)('two owner persisted canonical identity protocol', () => {
+ it('survives interrupted commit and recovery while preserving original rows and exact reviewed owner evidence', async () => {
+ const input = await pair(); const receipt = await propose(input);
+ const original = (await sql(owners[0], 'SELECT * FROM catalog_ingredients WHERE id=$1', [input.sourceId])).rows[0];
+ expect((await as(owners[1], () => protocol.createIdentity({ ...input, planHash: receipt.planHash }))).id).toBe(receipt.id);
+ await prepare(receipt);
+ await expect(sql(owners[0], 'UPDATE catalog_ingredients SET name=$2 WHERE id=$1', [input.sourceId, 'blocked'])).rejects.toThrow('protected');
+ await expect(sql(owners[1], `INSERT INTO catalog_ingredient_refs(ingredient_id,ref_kind,ref_id,role) VALUES($1,'universe','fixture','cast')`, [input.survivorId])).rejects.toThrow('protected');
+ await expect(as(owners[0], () => protocol.abortIdentity(receipt.id))).rejects.toThrow('Only the coordinator');
+ expect(await as(owners[1], () => protocol.advanceIdentity(receipt.id))).toMatchObject({ state: 'committed', epoch: 1 });
+ offline = true;
+ await expect(as(owners[0], () => protocol.advanceIdentity(receipt.id))).rejects.toMatchObject({ code: 'CATALOG_IDENTITY_PEER_UNAVAILABLE' });
+ expect((await as(owners[0], () => protocol.getIdentityOperation(receipt.id))).state).toBe('prepared');
+ offline = false; await as(owners[0], () => protocol.advanceIdentity(receipt.id));
+ expect((await sql(owners[0], 'SELECT * FROM catalog_ingredients WHERE id=$1', [input.sourceId])).rows[0]).toEqual(original);
+ for (const owner of owners) {
+ expect((await sql(owner, 'SELECT catalog_canonical_ingredient_id($1) AS id', [input.sourceId])).rows[0].id).toBe(input.survivorId);
+ expect((await sql(owner, 'SELECT payload FROM catalog_ingredients WHERE id=$1', [input.survivorId])).rows[0].payload.description).toBe('Original biography');
+ }
+ await expect(as(owners[0], () => protocol.prepareIdentityRecovery(receipt.id, receipt.planHash))).rejects.toThrow('canonical owner before');
+ await as(owners[1], () => protocol.prepareIdentityRecovery(receipt.id, receipt.planHash));
+ await as(owners[0], () => protocol.prepareIdentityRecovery(receipt.id, receipt.planHash));
+ await as(owners[1], () => protocol.advanceIdentity(receipt.id));
+ expect((await as(owners[1], () => protocol.advanceIdentity(receipt.id))).state).toBe('recovered');
+ await as(owners[0], () => protocol.advanceIdentity(receipt.id));
+ for (const owner of owners) {
+ expect((await sql(owner, 'SELECT catalog_canonical_ingredient_id($1) AS id', [input.sourceId])).rows[0].id).toBe(input.sourceId);
+ expect((await sql(owner, 'SELECT payload FROM catalog_ingredients WHERE id=$1', [input.survivorId])).rows[0].payload.description).toBe('Performance canon');
+ }
+ });
+ it('rejects forged/replayed evidence, revoked directions and stale acceptance before fencing', async () => {
+ const input = await pair(); corrupt = true;
+ await expect(as(owners[1], () => protocol.previewIdentity(input))).rejects.toMatchObject({ code: 'CATALOG_IDENTITY_EVIDENCE_INVALID' });
+ corrupt = false; configs[owners[0]].directions = ['outbound'];
+ await expect(as(owners[1], () => protocol.previewIdentity(input))).rejects.toMatchObject({ code: 'CATALOG_IDENTITY_PEER_FORBIDDEN' });
+ resetPeers(); const receipt = await propose(input);
+ await sql(owners[0], 'UPDATE catalog_ingredients SET name=$2 WHERE id=$1', [input.sourceId, 'New approved source']);
+ await expect(as(owners[0], () => protocol.acceptIdentity(receipt.id, receipt.planHash))).rejects.toMatchObject({ code: 'CATALOG_IDENTITY_STALE' });
+ expect((await as(owners[0], () => protocol.getIdentityOperation(receipt.id))).state).toBe('proposed');
+ });
+ it('fences relation endpoints, foreign writes and type changes; later canonical edits cannot be recovered over', async () => {
+ const input = await pair(); const receipt = await propose(input); await commit(receipt);
+ await expect(sql(owners[0], 'UPDATE catalog_ingredients SET name=$2 WHERE id=$1', [input.survivorId, 'Foreign edit'])).rejects.toThrow('protected');
+ await expect(sql(owners[1], `INSERT INTO catalog_ingredient_relations(from_id,to_id,kind) VALUES($1,$2,'related-to')`, [input.survivorId, input.sourceId])).rejects.toThrow('protected');
+ await expect(sql(owners[1], 'UPDATE catalog_ingredients SET type=$2 WHERE id=$1', [input.survivorId, 'object'])).rejects.toThrow('protected');
+ await sql(owners[1], 'UPDATE catalog_ingredients SET name=$2 WHERE id=$1', [input.survivorId, 'Later canonical edit']);
+ await as(owners[0], () => protocol.advanceIdentity(receipt.id));
+ expect((await sql(owners[0], 'SELECT name FROM catalog_ingredients WHERE id=$1', [input.survivorId])).rows[0].name).toBe('Later canonical edit');
+ await expect(as(owners[1], () => protocol.prepareIdentityRecovery(receipt.id, receipt.planHash))).rejects.toMatchObject({ code: 'CATALOG_IDENTITY_STALE' });
+ });
+ it('retains a coordinator abort and allows prepared source release only after verifying that decision', async () => {
+ const input = await pair(); const receipt = await propose(input); await prepare(receipt);
+ await as(owners[1], () => protocol.abortIdentity(receipt.id));
+ expect((await as(owners[0], () => protocol.advanceIdentity(receipt.id))).state).toBe('aborted');
+ expect((await as(owners[0], () => protocol.advanceIdentity(receipt.id))).epoch).toBe(1);
+ await sql(owners[0], 'UPDATE catalog_ingredients SET name=$2 WHERE id=$1', [input.sourceId, 'Writable after abort']);
+ });
+ it('invalidates peer rebinding and signed owner/ID substitution rather than accepting a different record', async () => {
+ const input = await pair();
+ wireHook = () => { configs[owners[0]].host = 'changed.invalid'; };
+ await expect(as(owners[1], () => protocol.previewIdentity(input))).rejects.toMatchObject({ code: 'CATALOG_IDENTITY_EVIDENCE_INVALID' });
+ resetPeers();
+ wireHook = response => {
+ response.value.ingredients[0].id = 'unrelated-fixture-id';
+ const { mac: _mac, ...evidence } = response;
+ Object.assign(response, transport.signEvidence({ ...configs[owners[1]], instanceId: owners[1] }, evidence));
+ };
+ await expect(as(owners[1], () => protocol.previewIdentity(input))).rejects.toThrow('snapshot identity');
+ });
+ it('can locally cancel after peer revocation; a prepared source still requires verified coordinator release', async () => {
+ const input = await pair(); const receipt = await propose(input); await prepare(receipt);
+ configs[owners[0]].syncEnabled = false;
+ expect((await as(owners[1], () => protocol.abortIdentity(receipt.id))).state).toBe('aborted');
+ await expect(as(owners[0], () => protocol.advanceIdentity(receipt.id))).rejects.toMatchObject({ code: 'CATALOG_IDENTITY_PEER_UNAVAILABLE' });
+ expect((await as(owners[0], () => protocol.getIdentityOperation(receipt.id))).state).toBe('prepared');
+ resetPeers();
+ expect((await as(owners[0], () => protocol.advanceIdentity(receipt.id))).state).toBe('aborted');
+ });
+ it('rejects an oversized projected canonical revision before creating or fencing any receipt', async () => {
+ const input = await pair();
+ await sql(owners[1], `UPDATE catalog_ingredients SET payload=jsonb_set(payload,'{notes}',to_jsonb($2::text)) WHERE id=$1`,
+ [input.survivorId, 'x'.repeat(2200000)]);
+ await expect(as(owners[1], () => protocol.previewIdentity(input))).rejects.toThrow('Projected canonical snapshot');
+ expect((await sql(owners[1], 'SELECT id FROM catalog_identity_operations WHERE survivor_id=$1', [input.survivorId])).rowCount).toBe(0);
+ });
+
+ it('honors terminal cancellation before acceptance and permits a new intentional attempt with the same content', async () => {
+ const input = await pair(); const receipt = await propose(input);
+ await as(owners[1], () => protocol.abortIdentity(receipt.id));
+ await expect(as(owners[0], () => protocol.acceptIdentity(receipt.id, receipt.planHash))).rejects.toThrow('already decided');
+ await sql(owners[0], 'UPDATE catalog_ingredients SET deleted=true WHERE id=$1', [input.sourceId]);
+ expect((await as(owners[0], () => protocol.advanceIdentity(receipt.id))).state).toBe('aborted');
+ expect((await as(owners[1], () => protocol.advanceIdentity(receipt.id))).peerState).toBe('aborted');
+ // A second pair keeps snapshots identical across the cancellation cycle.
+ const again = await pair(); const old = await propose(again);
+ await as(owners[1], () => protocol.abortIdentity(old.id));
+ await as(owners[0], () => protocol.advanceIdentity(old.id));
+ const fresh = await propose({ ...again, operationId: randomUUID() });
+ expect(fresh.id).not.toBe(old.id);
+ expect(fresh.state).toBe('proposed');
+ expect((await as(owners[1], () => protocol.createIdentity({ ...again, planHash: old.planHash }))).id).toBe(old.id);
+ });
+ it('keeps the immutable commit decision readable after oversized later canonical edits and records no invented source revision', async () => {
+ const input = await pair(); const receipt = await propose(input); await commit(receipt);
+ const sourceRevisions = (await sql(owners[0], 'SELECT actor FROM catalog_ingredient_revisions WHERE ingredient_id=$1', [input.survivorId])).rows;
+ expect(sourceRevisions.some(row => row.actor === 'catalog-shared-identity')).toBe(false);
+ const ownerTime = (await sql(owners[1], 'SELECT updated_at FROM catalog_ingredients WHERE id=$1', [input.survivorId])).rows[0].updated_at;
+ expect((await sql(owners[0], 'SELECT updated_at FROM catalog_ingredients WHERE id=$1', [input.survivorId])).rows[0].updated_at).toEqual(ownerTime);
+ await sql(owners[1], `UPDATE catalog_ingredients SET payload=jsonb_set(payload,'{notes}',to_jsonb($2::text)) WHERE id=$1`,
+ [input.survivorId, 'x'.repeat(8500000)]);
+ expect((await as(owners[0], () => transport.readEvidence(owners[1], 'status', receipt.id))).state).toBe('committed');
+ expect((await as(owners[1], () => protocol.advanceIdentity(receipt.id))).peerState).toBe('committed');
+ });
+
+});
diff --git a/server/services/catalogIdentity/snapshots.js b/server/services/catalogIdentity/snapshots.js
new file mode 100644
index 0000000000..892d88d76a
--- /dev/null
+++ b/server/services/catalogIdentity/snapshots.js
@@ -0,0 +1,109 @@
+import { createHash } from 'node:crypto';
+import { canonicalStringify } from '../../lib/objects.js';
+import { ServerError } from '../../lib/errorHandler.js';
+import { listSheetPointers } from '../../lib/sheetPointers.js';
+import { sanitizeBiblePayload } from '../catalogDB/shared.js';
+
+export 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)'],
+});
+export const fail = (message, code = 'CATALOG_IDENTITY_CONFLICT', status = 409) => {
+ throw new ServerError(message, { code, status });
+};
+export function bounded(value, maxBytes, label) {
+ if (Buffer.byteLength(JSON.stringify(value)) > maxBytes) fail(`${label} exceeds the supported bilateral evidence size; no reservation was made`);
+ return value;
+}
+export const hash = value => createHash('sha256').update(canonicalStringify(value)).digest('hex');
+export async function snapshot(client, ids) {
+ const value = {};
+ for (const [key, [table, where]] of Object.entries(TABLES)) {
+ const { rows } = await client.query(`SELECT * FROM ${table} WHERE ${where}`, [ids]);
+ value[key] = JSON.parse(JSON.stringify(rows)).map(row => Object.fromEntries(Object.entries(row)
+ .filter(([column]) => !['sync_sequence', 'search_tsv', 'embedding', 'embedding_model'].includes(column))))
+ .sort((a, b) => canonicalStringify(a).localeCompare(canonicalStringify(b)));
+ }
+ return bounded(value, 4 * 1024 * 1024 * Math.max(1, ids.length), 'Owner snapshot');
+}
+export async function lockCatalog(client) {
+ await client.query(`LOCK TABLE ${Object.values(TABLES).map(([table]) => table).join(', ')}, catalog_identity_operations, catalog_ingredient_merges IN SHARE ROW EXCLUSIVE MODE`);
+}
+export function ingredient(value, id) {
+ const row = value.ingredients.find(item => item.id === id && !item.deleted);
+ if (!row) fail('Both original identities must exist and be live');
+ return row;
+}
+export function validateSnapshot(value, id, owner) {
+ for (const key of Object.keys(TABLES)) if (!Array.isArray(value?.[key])) fail('Malformed owner snapshot');
+ if (value.ingredients.length !== 1 || value.ingredients[0].id !== id || value.ingredients[0].origin_instance_id !== owner) fail('Owner snapshot identity does not match requested owner and ID');
+ for (const key of ['sources', 'refs', 'media', 'revisions']) if (value[key].some(row => row.ingredient_id !== id)) fail('Owner snapshot contains an unrelated identity');
+ if (value.relations.some(row => row.from_id !== id && row.to_id !== id)) fail('Owner snapshot contains an unrelated relation');
+ ingredient(value, id);
+ bounded(value, 4 * 1024 * 1024, 'Owner snapshot');
+ return value;
+}
+export function assertUnlocked(row) {
+ if (row.payload?.locked !== false) fail('Both owner records must be explicitly unlocked', 'CATALOG_INGREDIENT_LOCKED');
+}
+function union(a, b, path, choices, conflicts) {
+ if (canonicalStringify(a) === canonicalStringify(b)) return a;
+ if (a == null || a === '') return b;
+ if (b == null || b === '') return a;
+ if (Array.isArray(a) && Array.isArray(b)) {
+ const result = structuredClone(a);
+ for (const item of b) {
+ const index = item?.id ? result.findIndex(value => value?.id === item.id) : -1;
+ if (index >= 0) result[index] = union(result[index], item, `${path}/${index}`, choices, conflicts);
+ else if (!result.some(value => canonicalStringify(value) === canonicalStringify(item))) result.push(item);
+ }
+ return result;
+ }
+ if (typeof a === 'object' && typeof b === 'object' && !Array.isArray(a) && !Array.isArray(b)) {
+ return Object.fromEntries([...new Set([...Object.keys(a), ...Object.keys(b)])].map(key => [key,
+ union(a[key], b[key], `${path}/${key.replaceAll('~', '~0').replaceAll('/', '~1')}`, choices, conflicts)]));
+ }
+ if (!choices[path]) conflicts.push({ path, survivor: a, source: b });
+ return choices[path] === 'source' ? b : a;
+}
+export function buildPlan(source, survivor, fieldChoices = {}, operationId) {
+ const a = survivor.ingredients[0];
+ const b = source.ingredients[0];
+ if (!a || !b || a.id === b.id || a.type !== b.type || !a.origin_instance_id || !b.origin_instance_id
+ || a.origin_instance_id === b.origin_instance_id) fail('Choose two same-type identities with different known owners');
+ assertUnlocked(a); assertUnlocked(b);
+ const conflicts = [];
+ const content = row => ({ name: row.name, payload: row.payload, tags: row.tags });
+ const proposed = union(content(a), content(b), '', fieldChoices, conflicts);
+ proposed.payload.aliases = [...new Set([...(Array.isArray(proposed.payload.aliases) ? proposed.payload.aliases : []), a.name, b.name])]
+ .filter(name => name !== proposed.name);
+ const normalized = sanitizeBiblePayload(a.type, proposed.name, proposed.payload);
+ const check = (value, next) => {
+ if (Array.isArray(value) && Array.isArray(next) && next.length < value.length) fail('Union exceeds field capacity; no values were discarded');
+ if (value && next && typeof value === 'object' && typeof next === 'object') for (const key of Object.keys(value)) check(value[key], next[key]);
+ };
+ check(proposed.payload, normalized);
+ const archivedMedia = [a, b].flatMap(row => {
+ 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:identity' })),
+ ];
+ return pointers.map(pointer => ({ ingredient_id: row.id, media_key: pointer.filename, kind: 'reference',
+ role: pointer.role, caption: `Preserved from ${row.name}`, metadata: {}, created_at: row.created_at, deleted: false }));
+ });
+ const plan = { version: 1, operationId, sourceId: b.id, survivorId: a.id, sourceOwner: b.origin_instance_id,
+ survivorOwner: a.origin_instance_id, source, survivor, fieldChoices, proposed, archivedMedia };
+ bounded(plan, 8 * 1024 * 1024, 'Identity plan');
+ // Commit adds a full revision. Reserve its complete payload before either
+ // owner fences records; a valid plan must always fit the decision channel.
+ bounded({ ...survivor, ingredients: [{ ...a, ...proposed }], revisions: [...survivor.revisions,
+ { id: 'x'.repeat(80), ingredient_id: a.id, ...proposed, source: 'user', actor: 'catalog-shared-identity', created_at: 'x'.repeat(40) }] },
+ 4 * 1024 * 1024 - 4096, 'Projected canonical snapshot');
+ return { plan, planHash: hash(plan), conflicts };
+}
diff --git a/server/services/catalogIdentity/transport.js b/server/services/catalogIdentity/transport.js
new file mode 100644
index 0000000000..b5bb28777f
--- /dev/null
+++ b/server/services/catalogIdentity/transport.js
@@ -0,0 +1,80 @@
+// Read-only bilateral evidence exchange. A pair credential proves possession;
+// a fresh challenge binds the exact response to this request, never to a third peer.
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { peerFetch, readPeerBody, derivePeerAuthToken } from '../../lib/peerHttpClient.js';
+import { peerBaseUrl } from '../../lib/peerUrl.js';
+import { canonicalStringify } from '../../lib/objects.js';
+import { findPeerById, peerAllowsOutbound, peerAllowsCategoryPull } from '../sharing/peerSyncShared.js';
+import { getInstanceId, UNKNOWN_INSTANCE_ID } from '../instanceIdentity.js';
+import { fail } from './snapshots.js';
+
+const bindings = new WeakMap();
+export async function revalidateEvidence(value) {
+ const binding = bindings.get(value);
+ if (!binding) fail('Missing verified peer evidence', 'CATALOG_IDENTITY_EVIDENCE_INVALID', 403);
+ const peer = await identityPeer(binding.owner);
+ if (await localIdentity() !== binding.self || peer.syncSecret !== binding.secret || peerBaseUrl(peer) !== binding.url) {
+ fail('Owner or peer binding changed during operation', 'CATALOG_IDENTITY_EVIDENCE_INVALID', 403);
+ }
+}
+const mac = (secret, value) => createHmac('sha256', secret).update(`portos-catalog-identity:v1:${canonicalStringify(value)}`).digest('hex');
+const equal = (a, b) => typeof a === 'string' && typeof b === 'string' && /^[a-f0-9]{64}$/.test(a)
+ && /^[a-f0-9]{64}$/.test(b) && timingSafeEqual(Buffer.from(a, 'hex'), Buffer.from(b, 'hex'));
+export async function identityPeer(instanceId) {
+ const peer = await findPeerById(instanceId);
+ if (!peer || peer.instanceId !== instanceId || !peerAllowsOutbound(peer)
+ || !peerAllowsCategoryPull(peer, 'catalog') || !peer.directions?.includes('inbound') || typeof peer.syncSecret !== 'string' || peer.syncSecret.length < 32) {
+ fail('A currently paired, enabled catalog peer with outbound sharing is required', 'CATALOG_IDENTITY_PEER_FORBIDDEN', 403);
+ }
+ return peer;
+}
+export async function localIdentity() {
+ const id = await getInstanceId();
+ if (!id || id === UNKNOWN_INSTANCE_ID) fail('Local owner identity unavailable');
+ return id;
+}
+export async function authenticateIdentityPeer(req) {
+ const caller = req.headers['x-portos-instance-id'];
+ if (typeof caller !== 'string') fail('Paired identity required', 'CATALOG_IDENTITY_PEER_FORBIDDEN', 403);
+ const peer = await identityPeer(caller);
+ if (!equal(req.headers['x-portos-peer-auth'], derivePeerAuthToken(peer.syncSecret, caller))) {
+ fail('Paired identity required', 'CATALOG_IDENTITY_PEER_FORBIDDEN', 403);
+ }
+ return peer;
+}
+export function signEvidence(peer, { owner, challenge, kind, target, value }) {
+ const evidence = { version: 1, owner, audience: peer.instanceId, challenge, kind, target, value };
+ return { ...evidence, mac: mac(peer.syncSecret, evidence) };
+}
+export async function readEvidence(owner, kind, target) {
+ const self = await localIdentity();
+ const peer = await identityPeer(owner);
+ const challenge = randomBytes(32).toString('hex');
+ const key = kind === 'snapshot' ? 'ingredientId' : 'operationId';
+ const path = kind === 'snapshot' ? '/api/catalog/identity/peer/snapshot' : '/api/catalog/identity/peer/status';
+ const url = `${peerBaseUrl(peer)}${path}?${new URLSearchParams({ [key]: target, challenge })}`;
+ let body;
+ try {
+ // Strip Basic auth even during legacy pairing discovery. This protocol has
+ // no password fallback, and does not provision or change a pair secret.
+ const response = await peerFetch(url, { signal: AbortSignal.timeout(15000), maxBytes: 16 * 1024 * 1024,
+ headers: { 'X-PortOS-Instance-Id': self, 'X-PortOS-Peer-Auth': derivePeerAuthToken(peer.syncSecret, self) } },
+ { ...peer, auth: undefined, peerAuthAccepted: true });
+ if (!response.ok) fail('Peer refused identity evidence', 'CATALOG_IDENTITY_PEER_UNAVAILABLE', 503);
+ body = await readPeerBody(response, 'json', { maxBytes: 16 * 1024 * 1024, idleTimeoutMs: 15000 });
+ } catch {
+ fail('Peer evidence unavailable; operation is unchanged. Retry this receipt, not a new operation.', 'CATALOG_IDENTITY_PEER_UNAVAILABLE', 503);
+ }
+ const { mac: signature, ...evidence } = body ?? {};
+ if (evidence.version !== 1 || evidence.owner !== owner || evidence.audience !== self || evidence.challenge !== challenge
+ || evidence.kind !== kind || evidence.target !== target || !equal(signature, mac(peer.syncSecret, evidence))) {
+ fail('Peer evidence authentication failed', 'CATALOG_IDENTITY_EVIDENCE_INVALID', 403);
+ }
+ // Re-read pair configuration after the network wait. Revocation during the
+ // request invalidates the result, including pair-secret replacement.
+ const fresh = await identityPeer(owner);
+ if (fresh.syncSecret !== peer.syncSecret || peerBaseUrl(fresh) !== peerBaseUrl(peer) || await localIdentity() !== self) fail('Pair binding changed during evidence request', 'CATALOG_IDENTITY_EVIDENCE_INVALID', 403);
+ if (!evidence.value || typeof evidence.value !== 'object') fail('Invalid owner evidence');
+ bindings.set(evidence.value, { owner, self, secret: peer.syncSecret, url: peerBaseUrl(peer) });
+ return evidence.value;
+}
diff --git a/server/services/catalogImageAttachHook.js b/server/services/catalogImageAttachHook.js
index 67a877ccad..b45ee2d2ed 100644
--- a/server/services/catalogImageAttachHook.js
+++ b/server/services/catalogImageAttachHook.js
@@ -1,3 +1,4 @@
+import { assertCatalogIdentityWritable } from './catalogDB/identityAccess.js';
/**
* Catalog image-attach hook (issue #1359).
*
@@ -43,6 +44,7 @@ const portraitGuard = createNewestWinsGuard();
// 'gone' when the target ingredient no longer exists, or throws on a real DB
// error (caught by the factory).
async function attachGeneratedImage({ ingredientId, kind, role, filename, queuedAt }) {
+ await assertCatalogIdentityWritable(ingredientId);
// The ingredient can be deleted between enqueue and completion (a render
// outlives its editor by minutes). `getIngredient` filters `deleted = false`,
// so this skips a hard-deleted ingredient (FK would throw) AND a soft-deleted
diff --git a/server/services/catalogImageAttachHook.test.js b/server/services/catalogImageAttachHook.test.js
index 373500fec1..ef4998f474 100644
--- a/server/services/catalogImageAttachHook.test.js
+++ b/server/services/catalogImageAttachHook.test.js
@@ -1,3 +1,4 @@
+vi.mock('./catalogDB/identityAccess.js', () => ({ assertCatalogIdentityWritable: vi.fn(async id => id) }));
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
// Mock the DB layer so the hook's attach/decision logic is exercised without a
diff --git a/server/services/catalogMedia.js b/server/services/catalogMedia.js
index b953624fed..05ade4037e 100644
--- a/server/services/catalogMedia.js
+++ b/server/services/catalogMedia.js
@@ -1,3 +1,4 @@
+import { assertCatalogIdentityWritable } from './catalogDB/identityAccess.js';
// Direct file-upload + voice-memo attachment for catalog ingredients.
//
// The existing `catalogIngestSources.ingestFromVoice` runs audio through the
@@ -114,11 +115,13 @@ export async function uploadIngredientMediaFile(
{ ingredientId, dataBase64, mimeType, filename = null, role = null, caption = null } = {},
{
getIngredientFn = getIngredient,
+ assertWritableFn = assertCatalogIdentityWritable,
attachMediaFn = attachMedia,
saveImageFn = saveUploadedGalleryImage,
persistFileFn = persistLibraryFile,
} = {},
) {
+ await assertWritableFn(ingredientId);
await requireIngredient(getIngredientFn, ingredientId);
const classified = classifyUploadMime(mimeType);
if (!classified) {
@@ -158,11 +161,13 @@ export async function recordIngredientVoiceMemo(
{ ingredientId, audioBase64, mimeType = 'audio/wav', role = 'voice-memo' } = {},
{
getIngredientFn = getIngredient,
+ assertWritableFn = assertCatalogIdentityWritable,
attachMediaFn = attachMedia,
transcribeFn = transcribe,
persistFileFn = persistLibraryFile,
} = {},
) {
+ await assertWritableFn(ingredientId);
await requireIngredient(getIngredientFn, ingredientId);
const buffer = Buffer.from(audioBase64, 'base64');
if (buffer.length === 0) throw new ServerError('Voice memo audio was empty', { status: 400, code: 'VALIDATION_ERROR' });
diff --git a/server/services/catalogMedia.test.js b/server/services/catalogMedia.test.js
index fa95477440..a46dc89795 100644
--- a/server/services/catalogMedia.test.js
+++ b/server/services/catalogMedia.test.js
@@ -1,3 +1,4 @@
+vi.mock('./catalogDB/identityAccess.js', () => ({ assertCatalogIdentityWritable: vi.fn(async id => id) }));
import { describe, it, expect, vi } from 'vitest';
import { catalogSyncEnvelopeSchema } from '../lib/catalogValidation.js';
import { GENERATION_METADATA_LIMITS } from '../lib/pngMetadata.js';
@@ -37,6 +38,16 @@ const okIngredient = () => ({ id: 'ing-1', name: 'Test' });
const b64 = (s) => Buffer.from(s).toString('base64');
describe('uploadIngredientMediaFile', () => {
+ it('refuses a fenced target before writing uploaded bytes', async () => {
+ const saveImageFn = vi.fn();
+ const attachMediaFn = vi.fn();
+ await expect(uploadIngredientMediaFile({ ingredientId: 'prepared-target', dataBase64: b64('img'), mimeType: 'image/png' }, {
+ assertWritableFn: async () => { throw Object.assign(new Error('Prepared'), { status: 409 }); },
+ getIngredientFn: okIngredient, saveImageFn, attachMediaFn,
+ })).rejects.toMatchObject({ status: 409 });
+ expect(saveImageFn).not.toHaveBeenCalled();
+ expect(attachMediaFn).not.toHaveBeenCalled();
+ });
it('routes an image through the gallery saver and attaches as reference', async () => {
const saveImageFn = vi.fn().mockResolvedValue({ filename: 'upload-abcd1234.png' });
const attachMediaFn = vi.fn().mockResolvedValue({ mediaKey: 'upload-abcd1234.png', kind: 'reference' });
diff --git a/server/services/catalogMediaBackupAdmission.test.js b/server/services/catalogMediaBackupAdmission.test.js
index 815ae81cac..e50312fbea 100644
--- a/server/services/catalogMediaBackupAdmission.test.js
+++ b/server/services/catalogMediaBackupAdmission.test.js
@@ -1,3 +1,4 @@
+vi.mock('./catalogDB/identityAccess.js', () => ({ getCatalogIdentityAccess: vi.fn(async () => null), assertCatalogIdentityWritable: vi.fn(async id => id) }));
/**
* Catalog media, voice-memo scraps and imported round reference audio against a
* backup cut (#9982). Each writes its file first and then commits the row that
diff --git a/server/services/catalogSheet.js b/server/services/catalogSheet.js
index 556a9a0208..2b51273a75 100644
--- a/server/services/catalogSheet.js
+++ b/server/services/catalogSheet.js
@@ -1,3 +1,4 @@
+import { assertCatalogIdentityWritable } from './catalogDB/identityAccess.js';
/**
* Catalog reference sheets: a sheet for a catalog record without needing a
* universe, plus environment (place) and product (object) sheet kinds.
@@ -183,6 +184,7 @@ export async function previewCatalogSheet(id, options = {}) {
/** Queue a sheet render for a catalog record; returns `{ jobId, variant, delegatedTo }`. */
export async function renderCatalogSheet(id, options = {}) {
+ await assertCatalogIdentityWritable(id);
const target = await resolveSheetTarget(id, options);
if (target.delegate) {
const { universeId, entryId } = target.delegate;
diff --git a/server/services/catalogSync.js b/server/services/catalogSync.js
index 030e886bad..e1397edd4c 100644
--- a/server/services/catalogSync.js
+++ b/server/services/catalogSync.js
@@ -190,11 +190,14 @@ export async function applyRemoteChanges(envelope = {}) {
let res;
try {
res = await upsertFn(item);
+ if (res?.identityPending) tally.identityPending = (tally.identityPending || 0) + 1;
if (lww) {
if (res.deferred) tally.deferred = (tally.deferred || 0) + 1;
else if (!res.applied) tally.skipped++;
else if (res.isInsert) tally.inserted++;
else tally.updated++;
+ } else if (res?.protectedIdentity) {
+ tally.skipped = (tally.skipped || 0) + 1;
} else {
tally.applied++;
}
@@ -203,7 +206,7 @@ export async function applyRemoteChanges(envelope = {}) {
recordFailure(errLabel, idFor(item), err);
continue;
}
- if (onApplied) {
+ if (onApplied && !res?.protectedIdentity) {
try { await onApplied(item, res); }
catch (err) { recordFailure(`${errLabel}-postapply`, idFor(item), err); }
}
diff --git a/server/services/catalogSync.test.js b/server/services/catalogSync.test.js
index 8b8e88dde4..9147b6bcde 100644
--- a/server/services/catalogSync.test.js
+++ b/server/services/catalogSync.test.js
@@ -61,6 +61,18 @@ beforeEach(() => {
});
describe('applyRemoteChanges — dispatch + stats', () => {
+ it('marks protected reservations for cursor retention across ingredient and association streams', async () => {
+ const pending = { applied: false, protectedIdentity: true, identityPending: true };
+ catalogDB.upsertIngredientFromPeer.mockResolvedValueOnce(pending);
+ catalogDB.upsertMediaFromPeer.mockResolvedValueOnce(pending);
+ const stats = await applyRemoteChanges({
+ portosMeta: { schemaVersions: PORTOS_SCHEMA_VERSIONS },
+ ingredients: [{ id: 'reserved-survivor', type: 'character', name: 'Example' }],
+ media: [{ ingredientId: 'reserved-survivor', mediaKey: 'later.png', kind: 'reference' }],
+ });
+ expect(stats.ingredients).toMatchObject({ skipped: 1, identityPending: 1, failed: 0 });
+ expect(stats.media).toMatchObject({ skipped: 1, identityPending: 1, failed: 0, applied: 0 });
+ });
it('routes each kind to its upsert and counts inserts/updates/skips', async () => {
catalogDB.upsertScrapFromPeer.mockResolvedValueOnce({ applied: true, isInsert: true });
catalogDB.upsertIngredientFromPeer.mockResolvedValueOnce({ applied: true, isInsert: false });
diff --git a/server/services/creativeDirector/firstPassGen.js b/server/services/creativeDirector/firstPassGen.js
index d7d5155138..b792b20fb7 100644
--- a/server/services/creativeDirector/firstPassGen.js
+++ b/server/services/creativeDirector/firstPassGen.js
@@ -1,3 +1,4 @@
+import { assertCatalogIdentityWritable } from '../catalogDB/identityAccess.js';
/**
* Creative Director — first-pass asset generation (#1818, extended by #1867).
*
@@ -171,6 +172,11 @@ export async function enqueueFirstPassPortraits(members = [], project = null) {
const decisions = await Promise.all(list.map(async ({ ingredientId }) => {
const ingredient = await getIngredient(ingredientId);
if (!ingredient) return { ingredientId, skip: 'gone' };
+ const refused = await assertCatalogIdentityWritable(ingredientId).then(() => null, error => {
+ if (error?.code?.startsWith('CATALOG_IDENTITY_')) return error.code;
+ throw error;
+ });
+ if (refused) return { ingredientId, skip: refused };
if (await ingredientHasPortrait(ingredientId)) return { ingredientId, skip: 'has-portrait' };
const prompt = buildPortraitPrompt(ingredient);
if (!prompt) return { ingredientId, skip: 'no-prompt' };
diff --git a/server/services/creativeDirector/firstPassGen.test.js b/server/services/creativeDirector/firstPassGen.test.js
index cc3c27129d..6c74981507 100644
--- a/server/services/creativeDirector/firstPassGen.test.js
+++ b/server/services/creativeDirector/firstPassGen.test.js
@@ -1,3 +1,4 @@
+vi.mock('../catalogDB/identityAccess.js', () => ({ assertCatalogIdentityWritable: vi.fn(async id => id) }));
import { describe, it, expect, vi, beforeEach } from 'vitest';
const { resolveLocalImageModel } = vi.hoisted(() => ({ resolveLocalImageModel: vi.fn() }));
diff --git a/server/services/creativeDirector/smokeTest.test.js b/server/services/creativeDirector/smokeTest.test.js
index f55a59ba9d..b13c647309 100644
--- a/server/services/creativeDirector/smokeTest.test.js
+++ b/server/services/creativeDirector/smokeTest.test.js
@@ -25,6 +25,11 @@ vi.mock('../../lib/mediaModels.js', () => ({
// createProject (via local.js) now imports catalogDB for the #1808 catalog-seed
// path; mock it so the smoke test doesn't pull in the real Postgres/instances/
// peer-sync chain (the smoke project passes no catalogIngredientIds).
+// Keep the new first-pass admission boundary inside the existing catalog mock.
+vi.mock('../catalogDB/identityAccess.js', () => ({
+ assertCatalogIdentityWritable: vi.fn(async id => id),
+}));
+
vi.mock('../catalogDB.js', () => ({
resolveIngredientsByIds: vi.fn(async () => []),
linkIngredientsToCreativeDirector: vi.fn(async () => []),
diff --git a/server/services/socket.js b/server/services/socket.js
index 5071f69ace..86a5fa2571 100644
--- a/server/services/socket.js
+++ b/server/services/socket.js
@@ -1,3 +1,4 @@
+import { catalogIdentityEvents } from './catalogIdentity/events.js';
import { registerModelObservationSocket } from './modelObservation.js';
import { registerBrowserStatusSocket } from './browserStatus.js';
import { registerFleetHostSocket } from './fleetHostNotify.js';
@@ -315,6 +316,7 @@ const SIMPLE_BRIDGES = [
// client ignores stragglers from a prior run.
{ emitter: importerEvents, event: 'progress', channel: 'importer:progress' },
{ emitter: catalogEvents, event: 'progress', channel: 'catalog:extract:progress' },
+ { emitter: catalogIdentityEvents, event: 'changed', channel: 'catalog:identity-changed' },
{ emitter: aiStatusEvents, event: 'status', channel: 'ai:status' },
// The call-host tab already gets `voice:call:state` from its own socket
// handler (server/sockets/voice.js); this fans it out to every OTHER tab.
diff --git a/server/services/syncOrchestrator.js b/server/services/syncOrchestrator.js
index facaf3cf1c..f73d7f478a 100644
--- a/server/services/syncOrchestrator.js
+++ b/server/services/syncOrchestrator.js
@@ -439,7 +439,9 @@ async function syncCatalogFromPeer(peer, peerId, cursor) {
// pull re-request and re-apply it once the parent lands (re-applying the
// page's already-succeeded rows is idempotent). A quiet/clean kind has
// failed===0 and still advances normally.
- if ((stats?.[kind]?.failed || 0) > 0) continue;
+ // A bilateral reservation has no durable row inbox. Retain this kind's
+ // cursor until it unfreezes so abort/recovery cannot lose a peer edit.
+ if ((stats?.[kind]?.failed || 0) > 0 || (stats?.[kind]?.identityPending || 0) > 0) continue;
const v = data.maxSequences[kind];
if (typeof v === 'string' && /^\d+$/.test(v)) catalogSeqs[kind] = v;
}
diff --git a/server/services/syncOrchestrator.test.js b/server/services/syncOrchestrator.test.js
index 82d55f5339..8a7e20f1ee 100644
--- a/server/services/syncOrchestrator.test.js
+++ b/server/services/syncOrchestrator.test.js
@@ -675,6 +675,27 @@ describe('syncOrchestrator', () => {
expect(result.catalog.catalogSeqs.refs ?? '0').toBe('0');
});
+ it('retains ingredient and association cursors during identity reservation, then retries the same page after unfreeze', async () => {
+ const page = {
+ ingredients: [{ id: 'reserved-survivor' }], media: [{ ingredientId: 'reserved-survivor', mediaKey: 'later.png' }],
+ maxSequences: { scraps: '0', ingredients: '7', sources: '0', refs: '0', relations: '0', tags: '0', media: '9' },
+ hasMore: false, portosMeta: { schemaVersions: { catalog: 1 } },
+ };
+ mockFetch.mockResolvedValue({ ok: true, json: async () => page });
+ applyCatalogChanges.mockResolvedValueOnce({
+ ingredients: { skipped: 1, failed: 0, identityPending: 1 },
+ media: { skipped: 1, failed: 0, identityPending: 1 },
+ });
+ const pending = await syncWithPeer(catalogPeer);
+ expect(pending.catalog.catalogSeqs.ingredients ?? '0').toBe('0');
+ expect(pending.catalog.catalogSeqs.media ?? '0').toBe('0');
+ applyCatalogChanges.mockResolvedValueOnce({ ingredients: { updated: 1, failed: 0 }, media: { applied: 1, failed: 0 } });
+ const completed = await syncWithPeer(catalogPeer);
+ expect(applyCatalogChanges.mock.calls.at(-1)[0].ingredients).toEqual(page.ingredients);
+ expect(completed.catalog.catalogSeqs.ingredients).toBe('7');
+ expect(completed.catalog.catalogSeqs.media).toBe('9');
+ });
+
it('clears a previously recorded schema gap after a successful catalog drain', async () => {
mockFetch.mockResolvedValueOnce({
ok: true,
diff --git a/server/services/threadRefs.js b/server/services/threadRefs.js
index e21f2a1e04..1dadd83511 100644
--- a/server/services/threadRefs.js
+++ b/server/services/threadRefs.js
@@ -63,7 +63,7 @@ const DB_REF_TABLES = Object.freeze({
'writers-room': { table: 'writers_room_works', titleExpr: 'title', liveClause: 'deleted = FALSE' },
'creative-director': { table: 'creative_director_projects', titleExpr: "NULLIF(data->>'title', '')", liveClause: 'deleted = FALSE' },
'music-video': { table: 'music_video_projects', titleExpr: "NULLIF(data->>'name', '')", liveClause: 'deleted = FALSE' },
- 'catalog.ingredient': { table: 'catalog_ingredients', titleExpr: 'name', liveClause: 'deleted = FALSE', contextExpr: 'type' },
+ 'catalog.ingredient': { table: 'catalog_ingredients', identityExpr: 'catalog_canonical_ingredient_id($1)', titleExpr: 'name', liveClause: 'deleted = FALSE', contextExpr: 'type' },
'catalog.scrap': { table: 'catalog_scraps', titleExpr: "NULLIF(title, '')", liveClause: 'deleted = FALSE' },
});
@@ -141,7 +141,7 @@ async function lookupTarget(kind, id) {
if (table) {
const context = table.contextExpr ? `, ${table.contextExpr} AS context` : '';
const { rows } = await query(
- `SELECT ${table.titleExpr} AS title${context} FROM ${table.table} WHERE id = $1 AND ${table.liveClause}`,
+ `SELECT ${table.titleExpr} AS title${context} FROM ${table.table} WHERE id = ${table.identityExpr || '$1'} AND ${table.liveClause}`,
[id],
);
if (rows.length === 0) return null;