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

12.5 KB
Raw Blame
/**
 * Bidirectional catalog↔canon projection — the highest-risk file in this PR.
 *
 * Uses the isolated portos_test database for catalog rows and refs; skips
 * when the test DB is unavailable. The universe side is INJECTED as
 * a spy (`updateUniverse` dep) so the suite asserts the projection's fan-out /
 * loop-break / LWW behavior without standing up a real universe store.
 *
 * The load-bearing assertion is "written EXACTLY ONCE": a single catalog edit
 * that round-trips catalog → canon → (echo) catalog must NOT write the catalog
 * row a second time. The injected updateUniverse calls the real
 * `projectToCatalog` (the A→B→A cycle) and we count `updateIngredient` hits.
 *
 * `instances.js` stays under the global vitest.setup mock (getPeers → []) so no
 * created row fans out to live peers; nothing here exercises the
 * createUniverse/createSeries peerSync import path, so mockNoPeers alone is
 * sufficient per the AGENTS.md record-creating-tests rule.
 */

import { describe, it, expect, afterAll, vi } from 'vitest';
import { checkHealth, ensureSchema, close, query } from '../lib/db.js';
import { requireDbOrSkip } from '../lib/dbTestGate.js';
import * as catalogDB from './catalogDB.js';
import { projectToCanon, projectToCatalog } from './catalogCanonProjection.js';

let dbReady = false;
let skipReason = '';
{
  const health = await checkHealth().catch((e) => ({ connected: false, error: e?.message }));
  if (!health.connected) {
    skipReason = `Postgres not reachable (${health.error || 'no connection'})`;
  } else {
    await ensureSchema().catch(() => {});
    const recheck = await checkHealth().catch(() => ({ hasCatalogSchema: false }));
    if (recheck.hasCatalogSchema) dbReady = true;
    else skipReason = 'catalog schema not present';
  }
}
const runDb = requireDbOrSkip('services/catalogCanonProjection.test', dbReady, skipReason);

const createdIngredientIds = new Set();
afterAll(async () => {
  if (!dbReady) return;
  for (const id of createdIngredientIds) {
    await catalogDB.deleteIngredient(id, { hard: true }).catch(() => {});
  }
  await close();
});

// Mint a catalog character row + a universe ref link. Returns the row.
async function makeLinkedCharacter(universeId, { name = 'Proj Test', payload = {} } = {}) {
  const ing = await catalogDB.createIngredient({ type: 'character', name, payload });
  createdIngredientIds.add(ing.id);
  await catalogDB.linkIngredientToRef(ing.id, 'universe', universeId, 'canon-character');
  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`;
    const uB = `u-proj-${Date.now()}-b`;
    const ing = await makeLinkedCharacter(uA, { name: 'Multi' });
    await catalogDB.linkIngredientToRef(ing.id, 'universe', uB, 'canon-character');

    const seenUniverses = [];
    const projected = [];
    const updateUniverse = vi.fn(async (universeId, mutator) => {
      seenUniverses.push(universeId);
      // Simulate the embedded entry carrying this ingredientId so the mutator
      // produces a patch (returns null otherwise → counted as skipped).
      const patch = await mutator({
        characters: [{
          id: 'e1', ingredientId: ing.id, name: 'old',
          createdAt: '2026-01-01T00:00:00.000Z', staleField: 'remove me',
        }],
      });
      projected.push(patch.characters[0]);
      return patch; // truthy → counted as "written"
    });

    const updated = await catalogDB.updateIngredient(ing.id, { name: 'Renamed', payload: { role: 'Hero' } });
    const stats = await projectToCanon(ing.id, updated, { updateUniverse });
    expect(stats.universes).toBe(2);
    expect(stats.written).toBe(2);
    expect(seenUniverses.sort()).toEqual([uA, uB].sort());
    expect(projected[0]).toMatchObject({
      id: 'e1', ingredientId: ing.id, name: 'Renamed', role: 'Hero',
      createdAt: '2026-01-01T00:00:00.000Z',
    });
    expect(projected[0]).not.toHaveProperty('staleField');
  });

  it('projectToCanon is a silent no-op for an ingredient with no universe ref', async () => {
    const ing = await catalogDB.createIngredient({ type: 'object', name: 'Lonely Object' });
    createdIngredientIds.add(ing.id);
    const updateUniverse = vi.fn();
    const stats = await projectToCanon(ing.id, ing, { updateUniverse });
    expect(stats).toEqual({ universes: 0, written: 0, skipped: 0 });
    expect(updateUniverse).not.toHaveBeenCalled();
  });

  it('projectToCatalog writes a canon edit into the catalog row (LWW: newer canon wins)', async () => {
    const uId = `u-proj-${Date.now()}-c`;
    const ing = await makeLinkedCharacter(uId, { name: 'Canon Edit', payload: { role: 'old-role' } });
    // Embedded entry is NEWER than the row → it wins.
    const future = new Date(Date.now() + 60_000).toISOString();
    const canon = {
      characters: [{
        id: 'e1', ingredientId: ing.id, name: 'Canon Edit', role: 'new-role',
        updatedAt: future,
      }],
    };
    const stats = await projectToCatalog(uId, canon, {});
    expect(stats.written).toBe(1);
    const row = await catalogDB.getIngredient(ing.id);
    expect(row.payload.role).toBe('new-role');
  });

  it('projectToCatalog LWW skips an OLDER canon snapshot (catalog row newer)', async () => {
    const uId = `u-proj-${Date.now()}-d`;
    const ing = await makeLinkedCharacter(uId, { name: 'Fresh Row', payload: { role: 'keep-me' } });
    // Embedded entry is OLDER than the (just-created) row → it loses, no write.
    const past = new Date(Date.now() - 60_000).toISOString();
    const canon = {
      characters: [{ id: 'e1', ingredientId: ing.id, name: 'Fresh Row', role: 'stale', updatedAt: past }],
    };
    const stats = await projectToCatalog(uId, canon, {});
    expect(stats.written).toBe(0);
    expect(stats.skipped).toBe(1);
    const row = await catalogDB.getIngredient(ing.id);
    expect(row.payload.role).toBe('keep-me');
  });

  it('re-entrancy guard breaks the A→B→A loop — each side written EXACTLY ONCE', async () => {
    const uId = `u-proj-${Date.now()}-e`;
    const ing = await makeLinkedCharacter(uId, { name: 'Loop Guard', payload: { role: 'before' } });

    // Count catalog writes. The injected updateUniverse calls the REAL
    // 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) => {
      const before = updSpy.mock.calls.length;
      // The embedded entry now carries the fresh ingredientId; updateUniverse
      // would persist canon then synchronously project back to catalog.
      const canon = {
        characters: [{
          id: 'e1', ingredientId: ing.id, name: 'Loop Guard', role: 'before',
          updatedAt: ing.updatedAt,
        }],
      };
      const patch = await mutator(canon);
      expect(patch).not.toBeNull();
      const persisted = { ...canon, ...patch };
      await projectToCatalog(universeId, persisted, { guardToken: opts?.canonProjectionGuard });
      catalogWritesInsideEcho = updSpy.mock.calls.length - before;
      return persisted;
    });

    const updated = await catalogDB.updateIngredient(ing.id, { payload: { role: 'after' } });
    const writesAfterPrimary = updSpy.mock.calls.length;

    await projectToCanon(ing.id, updated, { updateUniverse });

    // 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);
    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();
  });
});