Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
fix: re-check canon freshness under the row lock before projecting to catalog (#12503)
[._.]/ Adam Eivya0ff00892c6f
diff --git a/server/scripts/reconcileCanonCatalog.js b/server/scripts/reconcileCanonCatalog.jsindex 69c10a64e8..a48f3a7bdb 100644--- a/server/scripts/reconcileCanonCatalog.js+++ b/server/scripts/reconcileCanonCatalog.js@@ -16,7 +16,7 @@ import { getCatalogIdentityAccess } from '../services/catalogDB/identityAccess.j* - universe side: `updateUniverse(..., { silent })` — silent suppresses the* per-universe peer-sync fan-out (this is a local data repair, not a user* edit; peers reconcile on their own boot).- * - catalog side: `updateIngredient(..., { source: 'sync' })` so the rewrite+ * - catalog side: `updateIngredientIfFresh(..., { source: 'sync' })` so the rewrite* reads as a system reconciliation in the revision history, not a user edit.** Idempotent + marker-gated (`data/catalog-canon-reconcile.applied.json`): once@@ -71,19 +71,19 @@ export async function reconcileCanonCatalog({ force = false } = {}) {// fresh row and get clobbered. Comparing every universe against the pre-pass// clock keeps the winner determination stable across the whole reconcile.const rowClockAtStart = new Map();- // High-water mark of the canon-winner clock already written to each catalog- // row this pass. When the same ingredient is embedded in several universes- // and more than one copy beats the ORIGINAL row, only the NEWEST embedded- // copy may win — a later but older copy must not clobber the newer one we- // already wrote.- const canonWinnerClock = new Map();+ // The canon-winner already written to each catalog row this pass: its source+ // clock is the high-water mark (when the same ingredient is embedded in+ // several universes and more than one copy beats the ORIGINAL row, only the+ // NEWEST embedded copy may win), and its row version lets the next sibling+ // supersede our own write without mistaking it for a concurrent edit.+ const canonWinner = new Map();for (const universe of universes) {if (universe.deleted) continue;totals.universesScanned++;// Collect per-array, per-entry-id the winning payload to stamp back onto the// embedded entries in ONE silent updateUniverse below. The catalog side is- // written inline (one updateIngredient per catalog-loser).+ // written inline (one updateIngredientIfFresh per catalog-loser).const canonPatches = {}; // arrayKey -> { entryId -> winningEntryFields }for (const arrayKey of CANON_ARRAY_KEYS) {const list = Array.isArray(universe[arrayKey]) ? universe[arrayKey] : [];@@ -113,17 +113,28 @@ export async function reconcileCanonCatalog({ force = false } = {}) {updatedAt: row.updatedAt,};totals.catalogWon++;- } else if (entryAt > rowAt && entryAt > (canonWinnerClock.get(ingredientId) || 0)) {+ } else if (entryAt > rowAt && entryAt > (Date.parse(canonWinner.get(ingredientId)?.sourceUpdatedAt || '') || 0)) {// Embedded entry beats the original row AND any canon-winner already// written this pass → it wins. Write it into the catalog row and// raise the high-water mark so an older sibling copy can't clobber it.- await catalogDB.updateIngredient(+ // The write re-checks the clock under the row lock, so a catalog+ // edit committed since the scan read the row survives (#12503).+ const result = await catalogDB.updateIngredientIfFresh(ingredientId,{ name: entry.name, payload: entryToPayload(entry) },- { source: 'sync', actor: 'canon-catalog-reconcile' },+ {+ sourceUpdatedAt: entry.updatedAt,+ priorWrite: canonWinner.get(ingredientId) || null,+ source: 'sync',+ actor: 'canon-catalog-reconcile',+ },);- canonWinnerClock.set(ingredientId, entryAt);- totals.canonWon++;+ if (result?.status === 'written') {+ canonWinner.set(ingredientId, { syncSequence: result.ingredient.syncSequence, sourceUpdatedAt: entry.updatedAt });+ totals.canonWon++;+ } else {+ console.warn(`🔁 reconcile skipped ${universe.id}/${arrayKey}/${ingredientId}: catalog row changed during the pass`);+ }}// Equal timestamps → already converged; nothing to do.} catch (err) {diff --git a/server/scripts/reconcileCanonCatalog.test.js b/server/scripts/reconcileCanonCatalog.test.jsindex 2a8c590120..d866332e37 100644--- a/server/scripts/reconcileCanonCatalog.test.js+++ b/server/scripts/reconcileCanonCatalog.test.js@@ -3,7 +3,7 @@ vi.mock('../services/catalogDB/identityAccess.js', () => ({ getCatalogIdentityAc* Tests for the boot-time canon↔catalog reconciliation.** fs/promises (marker), fileUtils (PATHS), universeBuilder (listUniverses /- * updateUniverse) and catalogDB (getIngredient / updateIngredient) are mocked,+ * updateUniverse) and catalogDB (getIngredient / updateIngredientIfFresh) are mocked,* so this exercises the walk + LWW-merge + dual-write orchestration:* - newer catalog row wins → stamped back onto the embedded canon entry;* - newer embedded entry wins → written into the catalog row;@@ -14,7 +14,7 @@ vi.mock('../services/catalogDB/identityAccess.js', () => ({ getCatalogIdentityAcimport { describe, it, expect, vi, beforeEach } from 'vitest';const fsState = { marker: null, written: null };-const dbState = { rows: {}, updates: [] };+const dbState = { rows: {}, updates: [], stale: new Set() };const uniState = { universes: [], canonStamps: [] };// Marker I/O is delegated to migrationMarker.js; mock it against `fsState`@@ -36,16 +36,19 @@ vi.mock('../services/universeBuilder.js', () => ({vi.mock('../services/catalogDB.js', () => ({getIngredient: vi.fn(async (id) => dbState.rows[id] || null),- updateIngredient: vi.fn(async (id, patch, ctx) => {+ updateIngredientIfFresh: vi.fn(async (id, patch, ctx) => {+ // The locked freshness re-check itself is covered against Postgres in+ // catalogCanonProjection.test.js; here a fixture id opts into a refusal.+ if (dbState.stale.has(id)) return { status: 'stale', ingredient: null };dbState.updates.push({ id, patch, ctx });// Simulate the real DB trigger: a write bumps updated_at to "now" (a clock// strictly later than any fixture timestamp). This is what makes the// mid-pass clock-mutation bug observable — a later universe comparing// against the LIVE row would see this fresh clock.if (dbState.rows[id]) {- dbState.rows[id] = { ...dbState.rows[id], ...patch, updatedAt: '2099-01-01T00:00:00.000Z' };+ dbState.rows[id] = { ...dbState.rows[id], ...patch, updatedAt: '2099-01-01T00:00:00.000Z', syncSequence: String(dbState.updates.length) };}- return dbState.rows[id];+ return { status: 'written', ingredient: dbState.rows[id] };}),}));@@ -56,6 +59,7 @@ beforeEach(() => {fsState.written = null;dbState.rows = {};dbState.updates = [];+ dbState.stale = new Set();uniState.universes = [];uniState.canonStamps = [];});@@ -127,6 +131,25 @@ describe('reconcileCanonCatalog', () => {expect(payloadsWritten[payloadsWritten.length - 1]).toBe('new');// u-old never wins.expect(payloadsWritten).not.toContain('old');+ // The 'new' write supersedes the pass's own 'mid' write by row version.+ expect(dbState.updates.at(-1).ctx.priorWrite).toEqual({ syncSequence: '1', sourceUpdatedAt: '2026-02-01T00:00:00.000Z' });+ });++ it('a canon-winner refused by the locked re-check is not counted and keeps the pass clean (#12503)', async () => {+ dbState.rows['cat-chr-s'] = { id: 'cat-chr-s', name: 'S', payload: { role: 'old' }, updatedAt: '2026-01-01T00:00:00.000Z' };+ dbState.stale.add('cat-chr-s');+ uniState.universes = [{+ id: 'u-1',+ characters: [{ id: 'e1', ingredientId: 'cat-chr-s', name: 'S', role: 'fresh', updatedAt: '2026-02-01T00:00:00.000Z' }],+ }];+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});++ const result = await reconcileCanonCatalog();++ expect(result.stats).toMatchObject({ canonWon: 0, catalogWon: 0, errors: 0 });+ expect(result.markerWritten).toBe(true);+ expect(warnSpy).toHaveBeenCalledTimes(1);+ warnSpy.mockRestore();});it('leaves entries without an ingredientId untouched', async () => {diff --git a/server/services/catalogCanonProjection.batch.test.js b/server/services/catalogCanonProjection.batch.test.jsindex 7f7beaba88..daccc4085a 100644--- a/server/services/catalogCanonProjection.batch.test.js+++ b/server/services/catalogCanonProjection.batch.test.js@@ -5,7 +5,9 @@* before deciding whether to write — N single-row SELECTs inside the* synchronous `updateUniverse` request. It now issues ONE* `getIngredientTimestamps` lookup for every candidate id and writes only the- * rows the LWW comparison says are stale.+ * rows the LWW comparison says are stale; each write re-checks freshness under+ * the row lock (`updateIngredientIfFresh`, exercised against Postgres in+ * catalogCanonProjection.test.js).** `catalogDB` is mocked wholesale (no Postgres): the assertions are the query* COUNT + shape and that the skip/write accounting is byte-identical to the@@ -18,7 +20,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';vi.mock('./catalogDB.js', () => ({getIngredient: vi.fn(),getIngredientTimestamps: vi.fn(),- updateIngredient: vi.fn(async () => ({})),+ updateIngredientIfFresh: vi.fn(),listRefsForIngredient: vi.fn(async () => []),}));@@ -41,10 +43,11 @@ const entry = (ingredientId, { name = 'Example Character', updatedAt = NEWER, ..});const timestampMap = (pairs) => new Map(pairs);+const WRITTEN = { status: 'written', ingredient: { syncSequence: '7' } };beforeEach(() => {vi.clearAllMocks();- catalogDB.updateIngredient.mockResolvedValue({});+ catalogDB.updateIngredientIfFresh.mockResolvedValue(WRITTEN);});describe('projectToCatalog batching', () => {@@ -62,7 +65,7 @@ describe('projectToCatalog batching', () => {expect(catalogDB.getIngredient).not.toHaveBeenCalled();expect(catalogDB.getIngredientTimestamps).toHaveBeenCalledTimes(1);expect(catalogDB.getIngredientTimestamps).toHaveBeenCalledWith(['ing-c1', 'ing-c2', 'ing-p1', 'ing-o1'], { excludeAliases: true });- expect(catalogDB.updateIngredient).toHaveBeenCalledTimes(4);+ expect(catalogDB.updateIngredientIfFresh).toHaveBeenCalledTimes(4);expect(stats).toEqual({ written: 4, skipped: 0 });});@@ -73,13 +76,23 @@ describe('projectToCatalog batching', () => {characters: [entry('ing-c1', { name: 'Renamed', role: 'Hero', tagline: 'Fake tagline' })],});- expect(catalogDB.updateIngredient).toHaveBeenCalledWith(+ expect(catalogDB.updateIngredientIfFresh).toHaveBeenCalledWith('ing-c1',{ name: 'Renamed', payload: { role: 'Hero', tagline: 'Fake tagline' } },- { source: 'sync', actor: 'canon-projection' },+ { sourceUpdatedAt: NEWER, priorWrite: null, source: 'sync', actor: 'canon-projection' },);});+ it('counts a write the locked freshness re-check refuses as skipped (#12503)', async () => {+ catalogDB.getIngredientTimestamps.mockResolvedValue(timestampMap([['ing-a', ROW_AT], ['ing-b', ROW_AT]]));+ catalogDB.updateIngredientIfFresh.mockImplementation(async (id) => (+ id === 'ing-b' ? { status: 'stale', ingredient: null } : WRITTEN));++ const stats = await projectToCatalog('universe-1', { characters: [entry('ing-a'), entry('ing-b')] });++ expect(stats).toEqual({ written: 1, skipped: 1 });+ });+it('keeps LWW: an embedded entry OLDER than its row is skipped, equal timestamps still write', async () => {catalogDB.getIngredientTimestamps.mockResolvedValue(timestampMap([['ing-stale', ROW_AT], ['ing-equal', ROW_AT], ['ing-fresh', ROW_AT],@@ -93,7 +106,7 @@ describe('projectToCatalog batching', () => {],});- expect(catalogDB.updateIngredient.mock.calls.map(([id]) => id)).toEqual(['ing-equal', 'ing-fresh']);+ expect(catalogDB.updateIngredientIfFresh.mock.calls.map(([id]) => id)).toEqual(['ing-equal', 'ing-fresh']);expect(stats).toEqual({ written: 2, skipped: 1 });});@@ -104,8 +117,8 @@ describe('projectToCatalog batching', () => {characters: [entry('ing-live'), entry('ing-gone')],});- expect(catalogDB.updateIngredient).toHaveBeenCalledTimes(1);- expect(catalogDB.updateIngredient).toHaveBeenCalledWith('ing-live', expect.anything(), expect.anything());+ expect(catalogDB.updateIngredientIfFresh).toHaveBeenCalledTimes(1);+ expect(catalogDB.updateIngredientIfFresh).toHaveBeenCalledWith('ing-live', expect.anything(), expect.anything());expect(stats).toEqual({ written: 1, skipped: 1 });});@@ -127,7 +140,7 @@ describe('projectToCatalog batching', () => {});expect(catalogDB.getIngredientTimestamps).not.toHaveBeenCalled();- expect(catalogDB.updateIngredient).not.toHaveBeenCalled();+ expect(catalogDB.updateIngredientIfFresh).not.toHaveBeenCalled();expect(stats).toEqual({ written: 0, skipped: 0 });});@@ -139,7 +152,7 @@ describe('projectToCatalog batching', () => {characters: [entry('ing-c1'), entry('ing-c2')],});- expect(catalogDB.updateIngredient).not.toHaveBeenCalled();+ expect(catalogDB.updateIngredientIfFresh).not.toHaveBeenCalled();expect(stats).toEqual({ written: 0, skipped: 2 });expect(errSpy).toHaveBeenCalledTimes(1);errSpy.mockRestore();@@ -147,9 +160,9 @@ describe('projectToCatalog batching', () => {it('keeps a single failing write best-effort — the remaining entries still project', async () => {catalogDB.getIngredientTimestamps.mockResolvedValue(timestampMap([['ing-bad', ROW_AT], ['ing-ok', ROW_AT]]));- catalogDB.updateIngredient.mockImplementation(async (id) => {+ catalogDB.updateIngredientIfFresh.mockImplementation(async (id) => {if (id === 'ing-bad') throw new Error('constraint violation');- return {};+ return WRITTEN;});const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});@@ -177,8 +190,8 @@ describe('projectToCatalog batching', () => {});// Newer entry writes first; older duplicate entry is evaluated against appliedTimestamps (NEWER) and skipped- expect(catalogDB.updateIngredient).toHaveBeenCalledTimes(1);- expect(catalogDB.updateIngredient).toHaveBeenCalledWith(+ expect(catalogDB.updateIngredientIfFresh).toHaveBeenCalledTimes(1);+ expect(catalogDB.updateIngredientIfFresh).toHaveBeenCalledWith('ing-dup',{ name: 'Newer Entry', payload: expect.anything() },expect.anything(),@@ -196,18 +209,20 @@ describe('projectToCatalog batching', () => {],});- expect(catalogDB.updateIngredient).toHaveBeenCalledTimes(2);- expect(catalogDB.updateIngredient).toHaveBeenNthCalledWith(+ expect(catalogDB.updateIngredientIfFresh).toHaveBeenCalledTimes(2);+ expect(catalogDB.updateIngredientIfFresh).toHaveBeenNthCalledWith(1,'ing-dup',{ name: 'Older First', payload: expect.anything() },expect.anything(),);- expect(catalogDB.updateIngredient).toHaveBeenNthCalledWith(+ // The second write supersedes the first by its row version, not the+ // NOW() clock the trigger stamped on it.+ expect(catalogDB.updateIngredientIfFresh).toHaveBeenNthCalledWith(2,'ing-dup',{ name: 'Newer Second', payload: expect.anything() },- expect.anything(),+ expect.objectContaining({ sourceUpdatedAt: NEWER, priorWrite: { syncSequence: '7', sourceUpdatedAt: ROW_AT } }),);expect(stats).toEqual({ written: 2, skipped: 0 });});diff --git a/server/services/catalogCanonProjection.js b/server/services/catalogCanonProjection.jsindex 6c1b9c7fe4..8bcc995f9e 100644--- a/server/services/catalogCanonProjection.js+++ b/server/services/catalogCanonProjection.js@@ -173,8 +173,10 @@ export async function projectToCanon(ingredientId, updatedIngredient, deps = {})* ingredientId equals it is skipped (loop break).** LWW: writes the catalog row only when the embedded entry's `updatedAt` is- * newer-or-equal to the stored row's. Best-effort per entry (logged on- * failure); returns `{ written, skipped }`.+ * newer-or-equal to the stored row's, re-checked under the row lock at write+ * time. Best-effort per entry (logged on failure); a write refused because the+ * row changed after the batched lookup counts as skipped. Returns+ * `{ written, skipped }`.*/export async function projectToCatalog(universeId, canonArrays, { guardToken = null } = {}) {const stats = { written: 0, skipped: 0 };@@ -220,30 +222,38 @@ export async function projectToCatalog(universeId, canonArrays, { guardToken = n}// Pass 2 — write only the rows the LWW comparison says are stale. Sequential- // by design: each updateIngredient is a multi-statement write (sanitize ++ // by design: each write is a multi-statement transaction (lock + sanitize +// update + revision), and firing N of them at once would trade the read// stampede this fix removed for a write one.//- // Track writes applied within this call in `appliedTimestamps` so if multiple- // candidates reference the same ingredientId in one batch, an older entry- // cannot overwrite a newer entry written earlier in the same pass (#4006).- const appliedTimestamps = new Map(timestamps);+ // The batched snapshot only prunes obvious losers. A catalog PATCH or another+ // universe save can commit while an earlier candidate's write is pending, so+ // updateIngredientIfFresh re-checks the clock under the row lock and reports+ // `stale` instead of overwriting the newer row (#12503).+ //+ // `ownWrites` keeps the row version and source clock of each write made in+ // this call, so a duplicate ingredientId compares against the entry written+ // earlier in the pass rather than the NOW() the trigger stamped (#4006).+ const ownWrites = new Map();for (const { ingredientId, entry } of candidates) {- const rowUpdatedAt = appliedTimestamps.get(ingredientId);+ const rowUpdatedAt = timestamps.get(ingredientId);if (rowUpdatedAt === undefined) { stats.skipped++; continue; } // no live row+ const priorWrite = ownWrites.get(ingredientId) || null;// LWW on updatedAt — only overwrite the catalog row when the embedded entry// is at-least-as-fresh. An older embedded snapshot (e.g. a concurrent// catalog edit won) is left alone.const entryAt = Date.parse(entry.updatedAt || '') || 0;- const rowAt = Date.parse(rowUpdatedAt || '') || 0;+ const rowAt = Date.parse(priorWrite?.sourceUpdatedAt || rowUpdatedAt || '') || 0;if (entryAt < rowAt) { stats.skipped++; continue; }try {- await catalogDB.updateIngredient(+ const sourceUpdatedAt = entry.updatedAt;+ const result = await catalogDB.updateIngredientIfFresh(ingredientId,{ name: entry.name, payload: entryToPayload(entry) },- { source: 'sync', actor: 'canon-projection' },+ { sourceUpdatedAt, priorWrite, source: 'sync', actor: 'canon-projection' },);- appliedTimestamps.set(ingredientId, entry.updatedAt || rowUpdatedAt);+ if (result?.status !== 'written') { stats.skipped++; continue; }+ ownWrites.set(ingredientId, { syncSequence: result.ingredient.syncSequence, sourceUpdatedAt });stats.written++;} catch (err) {console.error(`🔁 projectToCatalog: ingredient ${ingredientId} update failed: ${err.message}`);diff --git a/server/services/catalogCanonProjection.ordering.test.js b/server/services/catalogCanonProjection.ordering.test.jsindex 07d0619a17..6849e9c8dc 100644--- a/server/services/catalogCanonProjection.ordering.test.js+++ b/server/services/catalogCanonProjection.ordering.test.js@@ -17,7 +17,7 @@ vi.mock('./catalogDB.js', () => ({getIngredientIdentityIds: vi.fn(async (id) => [id]),listRefsForIngredient: vi.fn(),getIngredientTimestamps: vi.fn(),- updateIngredient: vi.fn(),+ updateIngredientIfFresh: vi.fn(),}));const catalog = await import('./catalogDB.js');@@ -66,9 +66,9 @@ beforeEach(async () => {commit('Initial', BASE);catalog.getIngredient.mockImplementation(async () => structuredClone(row));catalog.getIngredientTimestamps.mockImplementation(async () => new Map([[ingredientId, row.updatedAt]]));- catalog.updateIngredient.mockImplementation(async (_id, patch) => {+ catalog.updateIngredientIfFresh.mockImplementation(async (_id, patch) => {row = { ...row, ...structuredClone(patch), updatedAt: new Date().toISOString() };- return structuredClone(row);+ return { status: 'written', ingredient: structuredClone(row) };});catalog.listRefsForIngredient.mockResolvedValue([{ refKind: 'universe', refId: universeId }]);await store().writeRecord(universeId, sanitizeTemplate({@@ -92,7 +92,7 @@ describe('catalog projection ordering through persisted universe writes', () =>}expect(row.name).toBe('New');expect(await persistedEntry()).toMatchObject({ name: 'New', updatedAt: newAt });- expect(catalog.updateIngredient).not.toHaveBeenCalled();+ expect(catalog.updateIngredientIfFresh).not.toHaveBeenCalled();});it('rechecks the catalog after entering the universe queue', async () => {@@ -150,7 +150,7 @@ describe('catalog projection ordering through persisted universe writes', () =>const entry = await persistedEntry();expect(entry).toMatchObject({ id: 'example-character', ingredientId, createdAt: BASE,updatedAt: OLD, name: 'Catalog edit', role: 'Hero', physicalDescription: '' });- expect(catalog.updateIngredient).not.toHaveBeenCalled();+ expect(catalog.updateIngredientIfFresh).not.toHaveBeenCalled();commit('Later catalog edit', NEW);await updateUniverse(universeId, (cur) => ({characters: [...cur.characters, { id: 'example-other', name: 'Other character', updatedAt: BASE }],@@ -158,6 +158,6 @@ describe('catalog projection ordering through persisted universe writes', () =>expect((await getUniverse(universeId)).characters[1].updatedAt > BASE).toBe(true);expect(await persistedEntry()).toMatchObject({ updatedAt: OLD, name: 'Catalog edit' });expect(row.name).toBe('Later catalog edit');- expect(catalog.updateIngredient).not.toHaveBeenCalled();+ expect(catalog.updateIngredientIfFresh).not.toHaveBeenCalled();});});diff --git a/server/services/catalogCanonProjection.test.js b/server/services/catalogCanonProjection.test.jsindex 86572568ba..2432023e76 100644--- a/server/services/catalogCanonProjection.test.js+++ b/server/services/catalogCanonProjection.test.js@@ -18,7 +18,7 @@*/import { describe, it, expect, afterAll, vi } from 'vitest';-import { checkHealth, ensureSchema, close } from '../lib/db.js';+import { checkHealth, ensureSchema, close, query } from '../lib/db.js';import { requireDbOrSkip } from '../lib/dbTestGate.js';import * as catalogDB from './catalogDB.js';import { projectToCanon, projectToCatalog, _inFlightSize } from './catalogCanonProjection.js';@@ -55,6 +55,16 @@ async function makeLinkedCharacter(universeId, { name = 'Proj Test', payload = {return ing;}+// Pin a row's change clock so entry clocks can sit deterministically between+// it and the NOW() a later write stamps (the trigger keeps an explicit clock).+const PINNED_AT = '2020-01-01T00:00:00.000Z';+const AFTER_PIN = '2020-01-01T00:00:01.000Z';+const LATER_AFTER_PIN = '2020-01-01T00:00:02.000Z';+async function pinClock(id, at = PINNED_AT) {+ await query('UPDATE catalog_ingredients SET updated_at = $2 WHERE id = $1', [id, at]);+}+const canonEntry = (ingredientId, name, updatedAt) => ({ id: `e-${ingredientId}`, ingredientId, name, updatedAt });+describe.skipIf(!runDb)('catalogCanonProjection', () => {it('projectToCanon fans a catalog edit into every linked universe canon entry', async () => {const uA = `u-proj-${Date.now()}-a`;@@ -139,6 +149,7 @@ describe.skipIf(!runDb)('catalogCanonProjection', () => {// projectToCatalog with the originating guard token — which must skip the// originating ingredient and therefore NOT write the catalog row again.const updSpy = vi.spyOn(catalogDB, 'updateIngredient');+ const condSpy = vi.spyOn(catalogDB, 'updateIngredientIfFresh');let catalogWritesInsideEcho = 0;const updateUniverse = vi.fn(async (universeId, mutator, opts) => {@@ -167,11 +178,96 @@ describe.skipIf(!runDb)('catalogCanonProjection', () => {// The echo (projectToCatalog inside updateUniverse) must NOT have written// the originating catalog row — the guard token skipped it.expect(catalogWritesInsideEcho).toBe(0);+ expect(condSpy).not.toHaveBeenCalled();// Total catalog writes across the whole round-trip: only the primary edit.expect(updSpy.mock.calls.length).toBe(writesAfterPrimary);// Canon side written exactly once.expect(updateUniverse).toHaveBeenCalledTimes(1);expect(_inFlightSize()).toBe(0);updSpy.mockRestore();+ condSpy.mockRestore();+ });++ it('a catalog edit committed after the batched lookup survives a pending projection (#12503)', async () => {+ const uId = `u-proj-${Date.now()}-f`;+ const a = await makeLinkedCharacter(uId, { name: 'Race A' });+ const b = await makeLinkedCharacter(uId, { name: 'Race B' });+ await pinClock(a.id);+ await pinClock(b.id);+ const realWrite = catalogDB.updateIngredientIfFresh;+ // While A's write is pending, an explicit catalog PATCH commits B.+ const spy = vi.spyOn(catalogDB, 'updateIngredientIfFresh').mockImplementation(async (id, ...rest) => {+ if (id === a.id) await catalogDB.updateIngredient(b.id, { name: 'New catalog edit' });+ return realWrite(id, ...rest);+ });+ try {+ const stats = await projectToCatalog(uId, {+ characters: [canonEntry(a.id, 'Canon edit A', AFTER_PIN), canonEntry(b.id, 'Older canon edit', AFTER_PIN)],+ });+ expect(stats).toEqual({ written: 1, skipped: 1 });+ } finally {+ spy.mockRestore();+ }+ expect((await catalogDB.getIngredient(a.id)).name).toBe('Canon edit A');+ expect((await catalogDB.getIngredient(b.id)).name).toBe('New catalog edit');+ const { items } = await catalogDB.listIngredientRevisions(b.id);+ expect(items.filter((r) => r.actor === 'canon-projection')).toEqual([]);+ });++ it('two universe saves of one identity honor the same locked check', async () => {+ const ing = await makeLinkedCharacter(`u-proj-${Date.now()}-g`, { name: 'Shared' });+ await pinClock(ing.id);+ const realLookup = catalogDB.getIngredientTimestamps;+ let newerStats;+ // The older save takes its snapshot, then the newer save commits first.+ const spy = vi.spyOn(catalogDB, 'getIngredientTimestamps').mockImplementationOnce(async (...args) => {+ const snapshot = await realLookup(...args);+ newerStats = await projectToCatalog('u-newer', { characters: [canonEntry(ing.id, 'Newer universe save', LATER_AFTER_PIN)] });+ return snapshot;+ });+ try {+ const olderStats = await projectToCatalog('u-older', { characters: [canonEntry(ing.id, 'Older universe save', AFTER_PIN)] });+ expect(olderStats).toEqual({ written: 0, skipped: 1 });+ } finally {+ spy.mockRestore();+ }+ expect(newerStats).toEqual({ written: 1, skipped: 0 });+ expect((await catalogDB.getIngredient(ing.id)).name).toBe('Newer universe save');+ });++ it('a newer duplicate in the same save supersedes the write made earlier in that save (#4006)', async () => {+ const uId = `u-proj-${Date.now()}-i`;+ const ing = await makeLinkedCharacter(uId, { name: 'Duplicate' });+ await pinClock(ing.id);+ const stats = await projectToCatalog(uId, {+ characters: [canonEntry(ing.id, 'First copy', AFTER_PIN)],+ places: [canonEntry(ing.id, 'Newer copy', LATER_AFTER_PIN)],+ });+ expect(stats).toEqual({ written: 2, skipped: 0 });+ expect((await catalogDB.getIngredient(ing.id)).name).toBe('Newer copy');+ });++ it('an equal-clock entry still writes; a row deleted after the lookup is skipped', async () => {+ const uId = `u-proj-${Date.now()}-h`;+ const equal = await makeLinkedCharacter(uId, { name: 'Equal' });+ const gone = await makeLinkedCharacter(uId, { name: 'Gone' });+ await pinClock(equal.id);+ await pinClock(gone.id);+ const realLookup = catalogDB.getIngredientTimestamps;+ const spy = vi.spyOn(catalogDB, 'getIngredientTimestamps').mockImplementationOnce(async (...args) => {+ const snapshot = await realLookup(...args);+ await catalogDB.deleteIngredient(gone.id);+ return snapshot;+ });+ try {+ const stats = await projectToCatalog(uId, {+ characters: [canonEntry(equal.id, 'Equal clock edit', PINNED_AT), canonEntry(gone.id, 'Revived?', AFTER_PIN)],+ });+ expect(stats).toEqual({ written: 1, skipped: 1 });+ } finally {+ spy.mockRestore();+ }+ expect((await catalogDB.getIngredient(equal.id)).name).toBe('Equal clock edit');+ expect(await catalogDB.getIngredient(gone.id)).toBeNull();});});diff --git a/server/services/catalogDB/ingredients.js b/server/services/catalogDB/ingredients.jsindex 5b07ad4476..bd31e115c3 100644--- a/server/services/catalogDB/ingredients.js+++ b/server/services/catalogDB/ingredients.js@@ -217,6 +217,40 @@ export async function updateIngredient(id, patch = {}, { client, source = 'user'return updated;}+/**+ * Conditional content write for a source that carries its own clock (the+ * canon→catalog projection and the boot reconciler, #12503). A batched+ * freshness snapshot read earlier is only an optimization: this re-reads the+ * target row's clock under `FOR UPDATE` inside the write transaction, so the+ * sanitize read, the UPDATE and the revision all see the locked row and a+ * catalog edit committed after the snapshot can no longer be overwritten.+ *+ * Writes only when `sourceUpdatedAt` is at least as fresh as the live row+ * (millisecond precision, matching the ISO clocks callers compare). `priorWrite`+ * — `{ syncSequence, sourceUpdatedAt }` from this caller's own earlier result —+ * lets a multi-step pass supersede the row it wrote itself: the trigger stamps+ * NOW() on that write, so the live clock alone would reject a newer sibling.+ * The trigger also bumps `sync_sequence` on every content change, so a match+ * proves nobody else wrote since.+ *+ * Returns `{ status: 'written' | 'stale' | 'missing', ingredient }`.+ */+export async function updateIngredientIfFresh(id, patch, { sourceUpdatedAt, priorWrite = null, source = 'user', actor = null } = {}) {+ return withTransaction(async (client) => {+ const { rows } = await client.query(+ `SELECT updated_at, sync_sequence FROM catalog_ingredients+ WHERE id = catalog_resolve_ingredient_id($1) AND deleted = false FOR UPDATE`,+ [id],+ );+ if (rows.length === 0) return { status: 'missing', ingredient: null };+ const ownRow = priorWrite?.syncSequence != null && String(rows[0].sync_sequence) === String(priorWrite.syncSequence);+ const rowAt = ownRow ? Date.parse(priorWrite.sourceUpdatedAt || '') || 0 : Date.parse(rows[0].updated_at.toISOString());+ if ((Date.parse(sourceUpdatedAt || '') || 0) < rowAt) return { status: 'stale', ingredient: null };+ const ingredient = await updateIngredient(id, patch, { client, source, actor });+ return ingredient ? { status: 'written', ingredient } : { status: 'missing', ingredient: null };+ });+}+/*** Insert one revision row capturing the committed state of an ingredient, then* prune the ingredient's history to the most-recent CATALOG_REVISION_RETENTION