Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
37.6 KB
Raw Blame
/**
 * #3390 — provider-agnostic embedding migration (planner/applier, PGLite) +
 * #3391 — NULL-signature rows must be treatable as stale.
 *
 * Covers:
 *   - resolveMigrationTarget validation (provider:model shape, unknown
 *     provider, recipe-default dims, --dim override, dims-required recipes)
 *   - includeNullSignature widening on countStaleChunks /
 *     sumStaleChunkChars / invalidateStaleSignatureEmbeddings (#3391)
 *   - planEmbeddingMigration counts, cost math, price_known, resuming
 *   - applyEmbeddingMigration: env-override refusal fires BEFORE any
 *     mutation, schema transition on dim change, DB-plane config writes,
 *     state marker, NULL-signature-inclusive invalidation, query-cache
 *     purge, idempotent re-apply (resume)
 *   - completeEmbeddingMigration bookkeeping
 *   - migrate_embeddings op contract (admin, localOnly, remote guard,
 *     needs_confirmation without yes)
 *
 * Canonical PGLite block (CLAUDE.md R3+R4). Engine parity for the #3391
 * predicates is pinned on real Postgres in
 * test/e2e/migrate-embeddings-postgres.test.ts.
 */
import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { installFixtureChunks } from './helpers/page-projection.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';
import { withEnv } from './helpers/with-env.ts';
import type { ChunkInput } from '../src/core/types.ts';
import {
  resolveMigrationTarget,
  planEmbeddingMigration,
  applyEmbeddingMigration,
  completeEmbeddingMigration,
  reconcilePageSignatures,
  verifyMigrationComplete,
  readMigrationStatus,
  countFalseStampedChunks,
  migrationSignature,
  MIGRATION_STATE_KEY,
  MIGRATION_COMPLETED_KEY,
} from '../src/core/embedding-migration.ts';
import { invalidateStaleSignatureEmbeddingsGuarded } from '../src/core/embedding-invalidation.ts';
import { estimateCostFromChars } from '../src/core/embedding-pricing.ts';
import { AUDIT_ROW_SOURCES } from '../src/core/facts/audit-sources.ts';
import { operations } from '../src/core/operations.ts';

let engine: PGLiteEngine;
let colDim: number;

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
}, 30000);

afterAll(async () => {
  await engine.disconnect();
});

beforeEach(async () => {
  await resetPgliteState(engine);
  const rows = await engine.executeRaw<{ dim: number }>(
    `SELECT atttypmod AS dim FROM pg_attribute
      WHERE attrelid = 'content_chunks'::regclass AND attname = 'embedding' AND attnum > 0`,
  );
  colDim = Number(rows[0]?.dim);
});

/** Seed a page with one embedded chunk and a given signature (null = pre-v108). */
async function seedEmbedded(slug: string, text: string, signature: string | null): Promise<void> {
  await engine.putPage(slug, { type: 'note', title: slug, compiled_truth: `# ${slug}` });
  const chunks: ChunkInput[] = [
    { chunk_index: 0, chunk_text: text, chunk_source: 'compiled_truth', token_count: 4, embedding: undefined },
  ];
  await installFixtureChunks(engine, slug, chunks);
  await engine.executeRaw(
    `UPDATE content_chunks
        SET embedding = ('[' || array_to_string(array_fill(0.0::real, ARRAY[$1::int]), ',') || ']')::vector
      WHERE page_id = (SELECT id FROM pages WHERE slug = $2 AND source_id = 'default')`,
    [colDim, slug],
  );
  if (signature !== null) {
    await engine.setPageEmbeddingSignature(slug, { signature });
  }
}

/** Actual vector(N)/halfvec(N) width of a table's `embedding` column. */
async function embeddingColWidth(table: string): Promise<number> {
  const rows = await engine.executeRaw<{ dim: number }>(
    `SELECT atttypmod AS dim FROM pg_attribute
      WHERE attrelid = $1::regclass AND attname = 'embedding'
        AND attnum > 0 AND NOT attisdropped`,
    [table],
  );
  return Number(rows[0]?.dim);
}

/** Seed a page with one UNembedded chunk (classic NULL-embedding stale). */
async function seedUnembedded(slug: string, text: string): Promise<void> {
  await engine.putPage(slug, { type: 'note', title: slug, compiled_truth: `# ${slug}` });
  await engine.upsertChunks(slug, [
    { chunk_index: 0, chunk_text: text, chunk_source: 'compiled_truth', token_count: 4, embedding: undefined },
  ]);
}

describe('embedding migration excludes soft-deleted pages', () => {
  test.each(['guarded', 'raw'] as const)('%s signature invalidation preserves tombstone vectors and invalidates live vectors', async (mode) => {
    await seedEmbedded('deleted-drift', 'retained vector', 'old:model:1');
    await seedEmbedded('live-drift', 'stale vector', 'old:model:1');
    await engine.softDeletePage('deleted-drift', { sourceId: 'default' });
    const readVector = (slug: string) => engine.executeRaw<{ embedding: string | null }>(
      `SELECT cc.embedding::text AS embedding FROM content_chunks cc JOIN pages p ON p.id = cc.page_id
       WHERE p.slug = $1 AND p.source_id = 'default'`, [slug]);
    const retained = await readVector('deleted-drift');
    expect(retained[0]!.embedding).not.toBeNull();
    const opts = { signature: 'new:model:1' };
    const invalidated = mode === 'guarded'
      ? await invalidateStaleSignatureEmbeddingsGuarded(engine, opts)
      : await engine.invalidateStaleSignatureEmbeddings(opts);
    expect(invalidated).toBe(1);
    expect(await readVector('deleted-drift')).toEqual(retained);
    expect(await readVector('live-drift')).toEqual([{ embedding: null }]);
  });

  test('content drift invalidates only live chunks and preserves deleted chunk metadata', async () => {
    for (const slug of ['deleted-content-drift', 'live-content-drift']) {
      await seedUnembedded(slug, 'current text');
      const [{ dim }] = await engine.executeRaw<{ dim: number }>(
        "SELECT atttypmod AS dim FROM pg_attribute WHERE attrelid='content_chunks'::regclass AND attname='embedding' AND attnum>0");
      await engine.executeRaw(`UPDATE content_chunks SET embedding=('[' || array_to_string(array_fill(0.0::real,ARRAY[$1::int]),',') || ']')::vector,
        embedded_text_hash=md5('old text'),embedded_at='2020-01-01T00:00:00Z'
        WHERE page_id=(SELECT id FROM pages WHERE slug=$2 AND source_id='default')`, [dim, slug]);
    }
    await engine.softDeletePage('deleted-content-drift', { sourceId: 'default' });
    const readDeleted = () => engine.executeRaw(`SELECT embedding::text,embedded_text_hash,embedded_at FROM content_chunks
      WHERE page_id=(SELECT id FROM pages WHERE slug='deleted-content-drift' AND source_id='default')`);
    const before = await readDeleted();
    expect(await engine.invalidateContentDriftEmbeddings()).toBe(1);
    expect(await readDeleted()).toEqual(before);
    expect(await engine.executeRaw(`SELECT embedding FROM content_chunks WHERE page_id=(SELECT id FROM pages
      WHERE slug='live-content-drift' AND source_id='default')`)).toEqual([{ embedding: null }]);
  });

  test('counts and both cursor orders ignore tombstones while preserving their recoverable chunks', async () => {
    await seedUnembedded('tombstone', 'deleted chunk');
    await engine.softDeletePage('tombstone', { sourceId: 'default' });
    await seedUnembedded('live', 'live');
    await seedUnembedded('later-tombstone', 'later deleted');
    await engine.softDeletePage('later-tombstone', { sourceId: 'default' });
    const updatedAt = '2020-01-02T03:04:05.000Z';
    await engine.executeRaw("UPDATE pages SET updated_at = $1::timestamptz WHERE slug = 'live' AND source_id = 'default'", [updatedAt]);
    for (const scope of [{}, { sourceId: 'default' }]) {
      expect(await engine.countStaleChunks(scope)).toBe(1);
      expect(await engine.countStaleChunks({ ...scope, signature: 'new:model:1024', includeNullSignature: true })).toBe(1);
      expect(await engine.sumStaleChunkChars(scope)).toBe(4);
      for (const orderBy of ['page_id', 'updated_desc'] as const) {
        const rows = await engine.listStaleChunks({ ...scope, orderBy, batchSize: 1 });
        expect(rows.map(row => row.slug)).toEqual(['live']);
        const last = rows[0]!;
        const rest = await engine.listStaleChunks({ ...scope, orderBy, batchSize: 1,
          afterPageId: last.page_id, afterChunkIndex: last.chunk_index,
          ...(orderBy === 'updated_desc' ? { afterUpdatedAt: updatedAt } : {}) });
        expect(rest).toHaveLength(0);
      }
    }
    expect((await engine.getPage('tombstone', { sourceId: 'default', includeDeleted: true }))?.deleted_at).not.toBeNull();
    expect(await engine.executeRaw("SELECT count(*)::int AS n FROM content_chunks WHERE page_id=(SELECT id FROM pages WHERE slug='tombstone')")).toEqual([{ n: 1 }]);
  });
});

describe('resolveMigrationTarget', () => {
  test('requires provider:model shape', () => {
    expect(() => resolveMigrationTarget('text-embedding-3-small')).toThrow(/provider:model/);
  });
  test('unknown provider throws', () => {
    expect(() => resolveMigrationTarget('nosuchprovider:some-model')).toThrow();
  });
  test('recipe default dims resolve (openai → 1536)', () => {
    expect(resolveMigrationTarget('openai:text-embedding-3-small')).toEqual({
      toModel: 'openai:text-embedding-3-small',
      toDims: 1536,
    });
  });
  test('explicit --dim wins over recipe default', () => {
    expect(resolveMigrationTarget('openai:text-embedding-3-small', 512).toDims).toBe(512);
  });
  test('recipe with default_dims=0 requires --dim', () => {
    expect(() => resolveMigrationTarget('litellm:my-custom-model')).toThrow(/--dim/);
    expect(resolveMigrationTarget('litellm:my-custom-model', 1024).toDims).toBe(1024);
  });
});

describe('#3391 includeNullSignature widening', () => {
  test('countStaleChunks / sumStaleChunkChars include NULL-signature rows only with the flag', async () => {
    await seedEmbedded('legacy', 'abcde', null);            // NULL sig, embedded
    await seedEmbedded('drifted', 'fghij', 'old:model:1');  // mismatched sig
    await seedEmbedded('fresh', 'klmno', 'new:model:1');    // matching sig
    const sig = 'new:model:1';

    // Default (grandfathered): legacy is invisible.
    expect(await engine.countStaleChunks({ signature: sig })).toBe(1);
    expect(await engine.sumStaleChunkChars({ signature: sig })).toBe(5);

    // Widened: legacy counts too; matching still excluded.
    expect(await engine.countStaleChunks({ signature: sig, includeNullSignature: true })).toBe(2);
    expect(await engine.sumStaleChunkChars({ signature: sig, includeNullSignature: true })).toBe(10);
  });

  test('invalidateStaleSignatureEmbeddings with the flag NULLs legacy + drifted, keeps matching', async () => {
    await seedEmbedded('legacy', 'abcde', null);
    await seedEmbedded('drifted', 'fghij', 'old:model:1');
    await seedEmbedded('fresh', 'klmno', 'new:model:1');

    const n = await engine.invalidateStaleSignatureEmbeddings({
      signature: 'new:model:1',
      includeNullSignature: true,
    });
    expect(n).toBe(2); // legacy + drifted; NOT fresh

    expect(await engine.countStaleChunks()).toBe(2); // both now NULL-embedding
    const kept = await engine.executeRaw<{ n: number }>(
      `SELECT count(*)::int AS n FROM content_chunks cc
        JOIN pages p ON p.id = cc.page_id
       WHERE p.slug = 'fresh' AND cc.embedding IS NOT NULL`,
    );
    expect(Number(kept[0]?.n)).toBe(1);

    // Idempotent.
    expect(await engine.invalidateStaleSignatureEmbeddings({
      signature: 'new:model:1', includeNullSignature: true,
    })).toBe(0);
  });

  test('default behavior unchanged: NULL signature stays grandfathered without the flag', async () => {
    await seedEmbedded('legacy', 'abcde', null);
    expect(await engine.invalidateStaleSignatureEmbeddings({ signature: 'new:model:1' })).toBe(0);
    expect(await engine.countStaleChunks({ signature: 'new:model:1' })).toBe(0);
  });
});

describe('planEmbeddingMigration', () => {
  test('counts everything not in the target space, splits out NULL-signature chunks, prices it', async () => {
    await seedEmbedded('legacy', 'abcde', null);                                 // 5 chars
    await seedEmbedded('current', 'fghij', `fixture-provider:embedding-v1:${colDim}`);  // 5 chars
    await seedUnembedded('pending', 'klmnop');                                   // 6 chars

    const plan = await planEmbeddingMigration(engine, {
      to: 'openai:text-embedding-3-small',
      fromModel: 'fixture-provider:embedding-v1',
      fromDims: colDim,
    });

    expect(plan.to_model).toBe('openai:text-embedding-3-small');
    expect(plan.to_dims).toBe(1536);
    expect(plan.column_dims).toBe(colDim);
    expect(plan.dim_change).toBe(colDim !== 1536);
    expect(plan.chunks_to_embed).toBe(3);        // all three
    expect(plan.null_signature_chunks).toBe(1);  // 'legacy' only
    expect(plan.total_chars).toBe(16);
    expect(plan.price_known).toBe(true);
    expect(plan.est_cost_usd).toBeCloseTo(estimateCostFromChars(16, 0.02), 10);
    expect(plan.resuming).toBe(false);
  });

  test('unknown pricing → price_known false, cost 0', async () => {
    await seedUnembedded('p1', 'abc');
    const plan = await planEmbeddingMigration(engine, { to: 'litellm:custom', dim: 1024 });
    expect(plan.price_known).toBe(false);
    expect(plan.est_cost_usd).toBe(0);
  });

  test('resuming=true when the state marker matches the target', async () => {
    await engine.setConfig(MIGRATION_STATE_KEY, JSON.stringify({
      to_model: 'openai:text-embedding-3-small', to_dims: 1536,
      from_model: 'x', from_dims: 1, started_at: 'now',
    }));
    const plan = await planEmbeddingMigration(engine, { to: 'openai:text-embedding-3-small' });
    expect(plan.resuming).toBe(true);
    const other = await planEmbeddingMigration(engine, { to: 'openai:text-embedding-3-large' });
    expect(other.resuming).toBe(false);
  });

  test('reranker on the outgoing provider triggers the warning', async () => {
    await engine.setConfig('search.reranker.model', 'fixture-provider:reranker-v1');
    const plan = await planEmbeddingMigration(engine, {
      to: 'openai:text-embedding-3-small',
      fromModel: 'fixture-provider:embedding-v1',
      fromDims: 1280,
    });
    expect(plan.reranker_warning).toContain('fixture-provider:reranker-v1');
  });
});

describe('applyEmbeddingMigration', () => {
  test('env override refuses BEFORE any mutation', async () => {
    await withEnv({ GBRAIN_EMBEDDING_MODEL: 'voyage:voyage-3-large' }, async () => {
      const plan = await planEmbeddingMigration(engine, { to: 'openai:text-embedding-3-small' });
      const res = await applyEmbeddingMigration(engine, plan);
      expect(res.status).toBe('refused');
      expect(await engine.getConfig(MIGRATION_STATE_KEY)).toBeFalsy();
      expect(await engine.getConfig('embedding_model')).toBeFalsy();
    });
  });

  test('same-dim swap: no schema transition; invalidates legacy + drifted; writes config + state; purges cache', async () => {
    await seedEmbedded('legacy', 'abcde', null);
    await seedEmbedded('drifted', 'fghij', `old:model:${colDim}`);
    // Seed a query-cache row that must not survive the swap.
    await engine.executeRaw(
      `INSERT INTO query_cache (id, query_text, source_id) VALUES ('qc1', 'stale query', 'default')`,
    );

    const persisted: Array<[string, number]> = [];
    const plan = await planEmbeddingMigration(engine, {
      to: 'openai:text-embedding-3-small', dim: colDim, // same width → no DDL
    });
    const res = await applyEmbeddingMigration(engine, plan, {
      persistConfig: (m, d) => { persisted.push([m, d]); },
    });

    expect(res.status).toBe('applied');
    if (res.status !== 'applied') throw new Error('unreachable');
    expect(res.schema_transitioned).toBe(false);
    expect(res.invalidated).toBe(2); // legacy (#3391) + drifted
    expect(res.cache_cleared).toBe(1);
    expect(persisted).toEqual([['openai:text-embedding-3-small', colDim]]);
    expect(await engine.getConfig('embedding_model')).toBe('openai:text-embedding-3-small');
    expect(await engine.getConfig('embedding_dimensions')).toBe(String(colDim));
    expect(await engine.getConfig(MIGRATION_STATE_KEY)).toBeTruthy();

    const qc = await engine.executeRaw<{ n: number }>(`SELECT count(*)::int AS n FROM query_cache`);
    expect(Number(qc[0]?.n)).toBe(0);
  });

  test('dim change: schema transition rebuilds the column at the target width; re-apply is a no-op', async () => {
    await seedEmbedded('a', 'abcde', null);
    const target = colDim === 512 ? 256 : 512;
    const plan = await planEmbeddingMigration(engine, {
      to: 'openai:text-embedding-3-small', dim: target,
    });
    const res = await applyEmbeddingMigration(engine, plan);
    expect(res.status).toBe('applied');
    if (res.status !== 'applied') throw new Error('unreachable');
    expect(res.schema_transitioned).toBe(true);

    const rows = await engine.executeRaw<{ dim: number }>(
      `SELECT atttypmod AS dim FROM pg_attribute
        WHERE attrelid = 'content_chunks'::regclass AND attname = 'embedding' AND attnum > 0 AND NOT attisdropped`,
    );
    expect(Number(rows[0]?.dim)).toBe(target);

    // Every embedding is NULL after the column rebuild → classic stale.
    expect(await engine.countStaleChunks()).toBe(1);

    // Resume: second apply must not transition again (column already at target).
    const res2 = await applyEmbeddingMigration(engine, plan);
    expect(res2.status).toBe('applied');
    if (res2.status !== 'applied') throw new Error('unreachable');
    expect(res2.schema_transitioned).toBe(false);
    expect(res2.invalidated).toBe(0);
  });

  test('dim change transitions ALL THREE text-embedding-space columns (blocker: query_cache + facts were left at the old width)', async () => {
    const target = colDim === 512 ? 256 : 512;

    // Pre-condition: all three start at the brain-birth width.
    expect(await embeddingColWidth('content_chunks')).toBe(colDim);
    expect(await embeddingColWidth('query_cache')).toBe(colDim);
    expect(await embeddingColWidth('facts')).toBe(colDim);

    const plan = await planEmbeddingMigration(engine, {
      to: 'openai:text-embedding-3-small', dim: target,
    });
    const res = await applyEmbeddingMigration(engine, plan);
    expect(res.status).toBe('applied');

    // All three must move together. Before the fix, query_cache and facts
    // stayed narrow: the query cache silently accepted ZERO rows forever
    // (store() + lookup() swallow the width error by design) and every
    // per-fact embed write failed.
    expect(await embeddingColWidth('content_chunks')).toBe(target);
    expect(await embeddingColWidth('query_cache')).toBe(target);
    expect(await embeddingColWidth('facts')).toBe(target);
  });

  test('#4252: a dim change keeps the facts btree indexes that read the embedding column (v237 idx_facts_unembedded)', async () => {
    const target = colDim === 512 ? 256 : 512;
    const factIndexes = async () => (await engine.executeRaw<{ indexname: string }>(
      `SELECT indexname FROM pg_indexes WHERE tablename = 'facts' AND indexname = 'idx_facts_unembedded'`)).map(r => r.indexname);
    expect(await factIndexes()).toEqual(['idx_facts_unembedded']);
    const plan = await planEmbeddingMigration(engine, { to: 'openai:text-embedding-3-small', dim: target });
    expect((await applyEmbeddingMigration(engine, plan)).status).toBe('applied');
    expect(await embeddingColWidth('facts')).toBe(target);
    expect(await factIndexes()).toEqual(['idx_facts_unembedded']);
  });

  test('post-transition the query cache can actually STORE a row at the new width', async () => {
    const target = colDim === 512 ? 256 : 512;
    const plan = await planEmbeddingMigration(engine, {
      to: 'openai:text-embedding-3-small', dim: target,
    });
    expect((await applyEmbeddingMigration(engine, plan)).status).toBe('applied');

    // The real regression symptom: a width-mismatched column makes this
    // INSERT throw, which query-cache.ts swallows → permanent 0% hit rate.
    const vec = `[${new Array(target).fill(0.01).join(',')}]`;
    await engine.executeRaw(
      `INSERT INTO query_cache (id, query_text, source_id, embedding)
       VALUES ('post-migrate', 'q', 'default', $1::vector)`,
      [vec],
    );
    const rows = await engine.executeRaw<{ n: number }>(
      `SELECT count(*)::int AS n FROM query_cache WHERE id = 'post-migrate'`,
    );
    expect(Number(rows[0]?.n)).toBe(1);
  });

  test('post-transition a fact embedding at the new width inserts (blocker: facts writes broke)', async () => {
    const target = colDim === 512 ? 256 : 512;
    const plan = await planEmbeddingMigration(engine, {
      to: 'openai:text-embedding-3-small', dim: target,
    });
    expect((await applyEmbeddingMigration(engine, plan)).status).toBe('applied');

    const vec = `[${new Array(target).fill(0.02).join(',')}]`;
    await engine.executeRaw(
      `INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, notability, source, confidence, embedding)
       VALUES ('default', 'e', 'f', 'fact', 'private', 'medium', 'test', 1.0, $1::vector)`,
      [vec],
    );
    const rows = await engine.executeRaw<{ n: number }>(
      `SELECT count(*)::int AS n FROM facts WHERE entity_slug = 'e'`,
    );
    expect(Number(rows[0]?.n)).toBe(1);
  });

  test('reconcilePageSignatures stamps fully-embedded pages and leaves partially-embedded ones alone', async () => {
    // 'done' — every chunk embedded, but signature still the OLD one (the
    // batch-boundary shape: embedded correctly, stamp skipped).
    await seedEmbedded('done', 'abcde', 'old:model:1');
    // 'partial' — one embedded chunk + one NULL chunk (a real embed failure).
    await seedEmbedded('partial', 'fghij', 'old:model:1');
    await engine.upsertChunks('partial', [
      { chunk_index: 0, chunk_text: 'fghij', chunk_source: 'compiled_truth', token_count: 4 },
      { chunk_index: 1, chunk_text: 'not embedded', chunk_source: 'compiled_truth', token_count: 4 },
    ]);
    // The drain stamps chunk.model with the model that actually embedded each
    // chunk; reconcile only stamps pages whose chunks ALL carry the target
    // model (a foreign-model chunk means the page is NOT in the new space).
    // Mirror the post-drain state the batch-boundary shape actually leaves.
    await engine.executeRaw(
      `UPDATE content_chunks SET model = 'openai:text-embedding-3-small'
        WHERE page_id IN (SELECT id FROM pages WHERE slug IN ('done','partial') AND source_id = 'default')`,
    );
    // 'foreign' — every chunk embedded, but by a DIFFERENT model (a non-locked
    // writer raced the drain): must NOT get the new stamp.
    await seedEmbedded('foreign', 'klmno', 'old:model:1');
    await engine.executeRaw(
      `UPDATE content_chunks SET model = 'other:writer-model'
        WHERE page_id = (SELECT id FROM pages WHERE slug = 'foreign' AND source_id = 'default')`,
    );

    const plan = await planEmbeddingMigration(engine, {
      to: 'openai:text-embedding-3-small', dim: colDim,
    });
    const n = await reconcilePageSignatures(engine, plan);
    expect(n).toBe(1); // 'done' only

    const sig = `openai:text-embedding-3-small:${colDim}`;
    const rows = await engine.executeRaw<{ slug: string; embedding_signature: string | null }>(
      `SELECT slug, embedding_signature FROM pages WHERE slug IN ('done','partial','foreign') ORDER BY slug`,
    );
    expect(rows.find(r => r.slug === 'done')?.embedding_signature).toBe(sig);
    expect(rows.find(r => r.slug === 'partial')?.embedding_signature).toBe('old:model:1');
    expect(rows.find(r => r.slug === 'foreign')?.embedding_signature).toBe('old:model:1');
  });

  test('completeEmbeddingMigration clears the state marker and stamps completion', async () => {
    const plan = await planEmbeddingMigration(engine, { to: 'openai:text-embedding-3-small', dim: colDim });
    await applyEmbeddingMigration(engine, plan);
    await completeEmbeddingMigration(engine, plan);
    expect(await engine.getConfig(MIGRATION_STATE_KEY)).toBeFalsy();
    const done = JSON.parse((await engine.getConfig(MIGRATION_COMPLETED_KEY))!);
    expect(done.to_model).toBe('openai:text-embedding-3-small');
  });
});

describe('#4305 false target stamps + #4306 embed_skip-safe invalidation', () => {
  const TARGET = 'openai:text-embedding-3-small';

  /**
   * Page with one chunk embedded at column width under an EXPLICIT chunk
   * model, optional page signature + frontmatter (the embed_skip shapes).
   */
  async function seedModeled(
    slug: string,
    text: string,
    opts: { model: string; signature?: string; frontmatter?: Record<string, unknown>; embedded?: boolean },
  ): Promise<void> {
    await engine.putPage(slug, {
      type: 'note', title: slug, compiled_truth: `# ${slug}`,
      ...(opts.frontmatter ? { frontmatter: opts.frontmatter } : {}),
    });
    await installFixtureChunks(engine, slug, [
      { chunk_index: 0, chunk_text: text, chunk_source: 'compiled_truth', token_count: 4, model: opts.model },
    ]);
    if (opts.embedded !== false) {
      await engine.executeRaw(
        `UPDATE content_chunks
            SET embedding = ('[' || array_to_string(array_fill(0.0::real, ARRAY[$1::int]), ',') || ']')::vector,
                model = $3
          WHERE page_id = (SELECT id FROM pages WHERE slug = $2 AND source_id = 'default')`,
        [colDim, slug, opts.model],
      );
    }
    if (opts.signature) await engine.setPageEmbeddingSignature(slug, { signature: opts.signature });
  }

  async function chunkState(slug: string): Promise<{ embedded: number; nulls: number }> {
    const rows = await engine.executeRaw<{ embedded: number; nulls: number }>(
      `SELECT count(*) FILTER (WHERE cc.embedding IS NOT NULL)::int AS embedded,
              count(*) FILTER (WHERE cc.embedding IS NULL)::int AS nulls
         FROM content_chunks cc JOIN pages p ON p.id = cc.page_id
        WHERE p.slug = $1 AND p.source_id = 'default'`,
      [slug],
    );
    return { embedded: Number(rows[0]?.embedded ?? 0), nulls: Number(rows[0]?.nulls ?? 0) };
  }

  test('#4305: plan, verify and --status all see chunks hidden behind a false target stamp', async () => {
    const sig = migrationSignature(TARGET, colDim);
    // Page stamped WITH the target signature while its chunk still carries the
    // old provider's model — pre-fix the whole toolchain reported converged.
    await seedModeled('false-stamp', 'abcde', { model: 'voyage:voyage-3-large', signature: sig });

    expect((await countFalseStampedChunks(engine, TARGET, colDim)).chunks).toBe(1);

    const plan = await planEmbeddingMigration(engine, { to: TARGET, dim: colDim });
    expect(plan.false_stamped_chunks).toBe(1);
    expect(plan.chunks_to_embed).toBe(1); // pre-fix: 0 (the #4305 symptom)
    expect(plan.total_chars).toBe(5);

    const verify = await verifyMigrationComplete(engine, { toModel: TARGET, toDims: colDim }, {
      filePlane: { model: TARGET, dims: colDim },
    });
    expect(verify.complete).toBe(false); // pre-fix: true
    expect(verify.blockers.join(' ')).toMatch(/false stamp/);
    expect(verify.details.false_stamped_chunks).toBe(1);

    await engine.setConfig('embedding_model', TARGET);
    await engine.setConfig('embedding_dimensions', String(colDim));
    const status = await readMigrationStatus(engine);
    expect(status.stale_vs_target.false_stamped).toBe(1);
  });

  test('#4305: bare-model-tail rows are NOT flagged (no surprise paid re-embed on pre-#3461 rows)', async () => {
    const sig = migrationSignature(TARGET, colDim);
    // Old rows stored the model without the provider prefix; the stamp is
    // honest for them — flagging would trigger a surprise full re-embed.
    await seedModeled('bare-tail', 'abcde', { model: 'text-embedding-3-small', signature: sig });
    expect((await countFalseStampedChunks(engine, TARGET, colDim)).chunks).toBe(0);
    const plan = await planEmbeddingMigration(engine, { to: TARGET, dim: colDim });
    expect(plan.false_stamped_chunks).toBe(0);
    expect(plan.chunks_to_embed).toBe(0);
  });

  test('#4305: apply clears the false stamp and re-invalidates the page', async () => {
    const sig = migrationSignature(TARGET, colDim);
    await seedModeled('false-stamp', 'abcde', { model: 'voyage:voyage-3-large', signature: sig });

    const plan = await planEmbeddingMigration(engine, { to: TARGET, dim: colDim });
    const res = await applyEmbeddingMigration(engine, plan);
    expect(res.status).toBe('applied');
    if (res.status !== 'applied') throw new Error('unreachable');
    expect(res.invalidated).toBe(1); // pre-fix: 0 (page skipped by its stamp)

    const rows = await engine.executeRaw<{ embedding_signature: string | null }>(
      `SELECT embedding_signature FROM pages WHERE slug = 'false-stamp' AND source_id = 'default'`,
    );
    expect(rows[0]?.embedding_signature).toBeNull();
    expect(await chunkState('false-stamp')).toEqual({ embedded: 0, nulls: 1 });
    // The standard NULL-embedding cursor now owns the re-embed.
    expect(await engine.countStaleChunks()).toBe(1);
  });

  test('#4306: invalidation preserves embed_skip pages\' retained vectors', async () => {
    const sig = migrationSignature(TARGET, colDim);
    // Embedded BEFORE the embed_skip marker appeared (the content-sanity
    // oversize shape) — pre-fix apply NULLed it and no selector could ever
    // re-embed it: permanent loss.
    await seedModeled('skip', 'retained', {
      model: 'voyage:voyage-3-large',
      frontmatter: { embed_skip: { reason: 'oversized' } },
    });
    await seedModeled('plain', 'stale', { model: 'voyage:voyage-3-large' });

    const plan = await planEmbeddingMigration(engine, { to: TARGET, dim: colDim });
    const res = await applyEmbeddingMigration(engine, plan);
    expect(res.status).toBe('applied');
    if (res.status !== 'applied') throw new Error('unreachable');
    expect(res.invalidated).toBe(1); // 'plain' only — pre-fix: 2

    expect(await chunkState('skip')).toEqual({ embedded: 1, nulls: 0 });
    expect(await chunkState('plain')).toEqual({ embedded: 0, nulls: 1 });
    expect(await engine.countStaleChunks({ signature: sig, includeNullSignature: true })).toBe(1);
  });

  test('#4306: guarded helper skips embed_skip on the signature-drift path too', async () => {
    await seedModeled('skip-drift', 'retained', {
      model: 'voyage:voyage-3-large',
      signature: 'old:model:1',
      frontmatter: { embed_skip: { reason: 'oversized' } },
    });
    const n = await invalidateStaleSignatureEmbeddingsGuarded(engine, { signature: 'new:model:1' });
    expect(n).toBe(0); // engine method pre-fix: 1 (the destroyed-vector shape)
    expect(await chunkState('skip-drift')).toEqual({ embedded: 1, nulls: 0 });
  });

  test('#4306: verify reports embed_skip NULL chunks without blocking completion', async () => {
    // The already-damaged shape: an embed_skip page whose chunks were NULLed
    // by a pre-fix run. Nothing re-embeds it by design — completion must not
    // wedge on it, but the verdict must SAY it.
    await seedModeled('skip-null', 'lost', {
      model: 'voyage:voyage-3-large',
      frontmatter: { embed_skip: { reason: 'oversized' } },
      embedded: false,
    });
    const verify = await verifyMigrationComplete(engine, { toModel: TARGET, toDims: colDim }, {
      filePlane: { model: TARGET, dims: colDim },
    });
    expect(verify.details.embed_skip_null_chunks).toBe(1);
    expect(verify.blockers.join(' ')).not.toMatch(/embed_skip/);
    expect(verify.complete).toBe(true);

    const status = await readMigrationStatus(engine);
    expect(status.embed_skip_null_chunks).toBe(1);
  });
});

describe('#4875 facts_pending excludes audit checkpoint rows', () => {
  test('terminal / non-extractable / legacy checkpoints are not a pending embedding backlog', async () => {
    const seed = (source: string, extra = '') => engine.executeRaw(
      `INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, notability, source, confidence${extra ? ', ' + extra : ''})
       VALUES ('default', 'e', $1, 'fact', 'private', 'medium', $1, 1.0${extra ? ', now()' : ''})`,
      [source],
    );
    await seed('test');                       // the one real pending fact
    for (const s of AUDIT_ROW_SOURCES) await seed(s); // checkpoints, never embedded
    await seed('expired-real', 'expired_at'); // expired rows already excluded

    const status = await readMigrationStatus(engine);
    expect(status.facts_pending).toBe(1);
  });
});

describe('migrate_embeddings op contract', () => {
  const op = operations.find(o => o.name === 'migrate_embeddings')!;

  test('is admin + localOnly + mutating', () => {
    expect(op).toBeDefined();
    expect(op.scope).toBe('admin');
    expect(op.localOnly).toBe(true);
    expect(op.mutating).toBe(true);
  });

  test('remote callers are refused even if dispatch forgot the localOnly filter', async () => {
    await expect(
      op.handler({ engine, remote: true } as never, { to: 'openai:text-embedding-3-small' }),
    ).rejects.toThrow(/local-only/);
    // remote undefined (not strictly false) is ALSO refused — fail-closed.
    await expect(
      op.handler({ engine } as never, { to: 'openai:text-embedding-3-small' }),
    ).rejects.toThrow(/local-only/);
  });

  test('without yes=true it returns the plan only (no mutation)', async () => {
    const res = await op.handler(
      { engine, remote: false } as never,
      { to: 'openai:text-embedding-3-small', dim: colDim },
    ) as { status: string; plan: { to_model: string } };
    expect(res.status).toBe('needs_confirmation');
    expect(res.plan.to_model).toBe('openai:text-embedding-3-small');
    expect(await engine.getConfig(MIGRATION_STATE_KEY)).toBeFalsy();
  });

  test('signature helper matches currentEmbeddingSignature shape', () => {
    expect(migrationSignature('openai:text-embedding-3-small', 1536))
      .toBe('openai:text-embedding-3-small:1536');
  });
});

describe('runSchemaTransition retained column and index regressions', () => {
  test('preserves embedding_image and embedding_multimodal dimensions after text migration', async () => {
    await seedEmbedded('transition-image-width', 'fixture body', null);
    const target = colDim === 512 ? 256 : 512;
    const plan = await planEmbeddingMigration(engine, { to: 'openai:text-embedding-3-small', dim: target });
    expect(await applyEmbeddingMigration(engine, plan)).toMatchObject({ status: 'applied', schema_transitioned: true });
    const rows = await engine.executeRaw<{ column_name: string; col_type: string }>(
      `SELECT a.attname AS column_name, format_type(a.atttypid, a.atttypmod) AS col_type
         FROM pg_attribute a
         JOIN pg_class c ON c.oid = a.attrelid
         JOIN pg_namespace n ON n.oid = c.relnamespace
        WHERE n.nspname = 'public' AND c.relname = 'content_chunks'
          AND a.attname IN ('embedding', 'embedding_image', 'embedding_multimodal')
          AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attname`,
    );
    const byName = new Map(rows.map(r => [r.column_name, r.col_type]));
    expect(byName.get('embedding')).toBe(`vector(${target})`);
    expect(byName.get('embedding_image')).toBe('vector(1024)');
    expect(byName.get('embedding_multimodal')).toBe('vector(1024)');
  });

  test('restores the partial WHERE predicate on idx_chunks_embedding_image', async () => {
    await seedEmbedded('transition-image-index', 'fixture body', null);
    const target = colDim === 512 ? 256 : 512;
    const plan = await planEmbeddingMigration(engine, { to: 'openai:text-embedding-3-small', dim: target });
    expect(await applyEmbeddingMigration(engine, plan)).toMatchObject({ status: 'applied', schema_transitioned: true });
    const rows = await engine.executeRaw<{ indexdef: string }>(
      `SELECT indexdef FROM pg_indexes WHERE schemaname = 'public'
        AND tablename = 'content_chunks' AND indexname = 'idx_chunks_embedding_image'`,
    );
    expect(rows.length).toBe(1);
    expect(rows[0].indexdef).toMatch(/WHERE\s+\(?embedding_image IS NOT NULL\)?/i);
  });

  test('preserves both partial stale indexes on content_chunks.embedding (#4252)', async () => {
    await seedEmbedded('transition-stale-index', 'fixture body', null);
    await engine.executeRaw(`CREATE INDEX IF NOT EXISTS idx_chunks_embedding_null
      ON content_chunks (page_id, chunk_index) WHERE embedding IS NULL`);
    const target = colDim === 512 ? 256 : 512;
    const plan = await planEmbeddingMigration(engine, { to: 'openai:text-embedding-3-small', dim: target });
    expect(await applyEmbeddingMigration(engine, plan)).toMatchObject({ status: 'applied', schema_transitioned: true });
    const rows = await engine.executeRaw<{ indexname: string; indexdef: string }>(
      `SELECT indexname, indexdef FROM pg_indexes WHERE schemaname = 'public'
        AND tablename = 'content_chunks'
        AND indexname IN ('idx_chunks_embedding_null', 'content_chunks_stale_idx') ORDER BY indexname`,
    );
    const byName = new Map(rows.map(r => [r.indexname, r.indexdef]));
    expect([...byName.keys()]).toEqual(['content_chunks_stale_idx', 'idx_chunks_embedding_null']);
    expect(byName.get('content_chunks_stale_idx')).toMatch(/WHERE\s+\(?embedding IS NULL\)?/i);
    expect(byName.get('idx_chunks_embedding_null')).toMatch(/WHERE\s+\(?embedding IS NULL\)?/i);
  });

  test('skips the image index cleanly when both multimodal columns are absent', async () => {
    await seedEmbedded('transition-no-image', 'fixture body', null);
    await engine.executeRaw('ALTER TABLE content_chunks DROP COLUMN IF EXISTS embedding_image');
    await engine.executeRaw('ALTER TABLE content_chunks DROP COLUMN IF EXISTS embedding_multimodal');
    const target = colDim === 512 ? 256 : 512;
    const plan = await planEmbeddingMigration(engine, { to: 'openai:text-embedding-3-small', dim: target });
    expect(await applyEmbeddingMigration(engine, plan)).toMatchObject({ status: 'applied', schema_transitioned: true });
    expect(await embeddingColWidth('content_chunks')).toBe(target);
    const rows = await engine.executeRaw<{ indexname: string }>(
      `SELECT indexname FROM pg_indexes WHERE schemaname = 'public'
        AND tablename = 'content_chunks' AND indexname = 'idx_chunks_embedding_image'`,
    );
    expect(rows.length).toBe(0);
  });
});