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

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.js
index 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.js
index 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', () => ({ getCatalogIdentityAc
import { 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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