Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.1 KB
Raw Blame
/**
 * W3 (GBRA-224, #5527 class): free signature restamp in the maintenance
 * cycle's embed phase (never on upgrade). A page whose stored signature is
 * missing or names another model, while every one of its chunks already holds
 * a vector of the current model (model column, embedded text hash, width, in
 * the registry-active column), is only missing its stamp. The restamp sets
 * `pages.embedding_signature` without a provider call, so those vectors stop
 * reading as "a previous model's space" and stop costing a paid re-embed.
 *
 * Each page is stamped in its own transaction under the shared page-write
 * guard (`lockPageKeys`, the lock installPageEmbeddings and every chunk
 * writer takes), and the UPDATE re-checks, after the lock, the revision and
 * old signature read at selection, the projection seal (text projection at
 * the knowledge revision), the active column, and that every chunk is still
 * current. A concurrent re-embed, chunk rewrite or content change between the
 * read and the stamp makes the UPDATE match nothing; that page is retried on
 * a later run. It never touches content or vectors.
 *
 * Bounded: at most EMBEDDING_RESTAMP_MAX_PAGES pages per run. A run that
 * throws counts a failed attempt in the heal audit; after
 * EMBEDDING_RESTAMP_FAILURE_BOUND consecutive failed runs doctor's
 * `embedding_restamp_stalled` check (page class) reports it. A run that
 * completes resets the count. `embed.restamp.enabled=false` turns it off.
 */
import type { BrainEngine } from './engine.ts';
import { resolveActiveEmbeddingColumnFromEngine, quoteIdentifier } from './search/embedding-column.ts';
import { pageBudgetLimitedFilter } from './page-size-policy.ts';
import { chunkGenerationFilter } from './search/safe-chunks.ts';
import { currentSpaceChunkPredicate, splitEmbeddingSignature } from './embedding-invalidation.ts';
import { healEnabled, readHealAudit, recordHealAudit } from './heal-audit.ts';

export const EMBEDDING_RESTAMP_ENABLED_KEY = 'embed.restamp.enabled';
export const EMBEDDING_RESTAMP_CODE = 'embedding_restamp';
export const EMBEDDING_RESTAMP_MAX_PAGES = 500;
export const EMBEDDING_RESTAMP_FAILURE_BOUND = 3;

export interface EmbeddingRestampResult {
  /** Pages stamped this run. */
  pages: number;
  chunks: number;
  /** Pages the guarded UPDATE no longer matched (changed between read and stamp); retried next run. */
  rejected: number;
  /** More candidates remain past the per-run bound. */
  capped: boolean;
  max_pages: number;
  /** Consecutive failed runs including this one (0 after a completed run). */
  failed_runs: number;
  error?: string;
}

/** The page rule every stamp re-checks under the guard: $1 signature, $2 model, $3 dims. */
function restampablePage(colId: string): string {
  return `(p.embedding_signature IS NULL OR p.embedding_signature <> $1)
       AND p.deleted_at IS NULL
       AND p.text_projection_revision = p.knowledge_revision
       AND NOT (COALESCE(p.frontmatter, '{}'::jsonb) ? 'embed_skip')
       AND NOT ${pageBudgetLimitedFilter('p')}
       AND EXISTS (SELECT 1 FROM sources s WHERE s.id = p.source_id AND NOT s.archived)
       AND EXISTS (SELECT 1 FROM content_chunks cc WHERE cc.page_id = p.id AND ${chunkGenerationFilter('p', 'cc')})
       AND NOT EXISTS (SELECT 1 FROM content_chunks cc WHERE cc.page_id = p.id AND ${chunkGenerationFilter('p', 'cc')} AND NOT ${currentSpaceChunkPredicate(colId, 2, 3)})`;
}

let beforeStampForTests: ((pageId: number) => Promise<void>) | null = null;
/** Test seam: runs after selection and before each page's guarded stamp (a concurrent writer's window). */
export function __setRestampBeforeStampForTests(fn: ((pageId: number) => Promise<void>) | null): void { beforeStampForTests = fn; }

async function lastFailedRuns(engine: BrainEngine): Promise<number> {
  const last = (await readHealAudit(engine, EMBEDDING_RESTAMP_CODE)).at(-1);
  return last?.outcome === 'failed' || last?.outcome === 'escalated' ? last.attempt : 0;
}

/**
 * Restamp up to `maxPages` current-space pages under `signature`. Returns null
 * when the heal is off or the signature carries no width. Never calls a provider.
 */
export async function restampCurrentSpaceSignatures(engine: BrainEngine, signature: string,
  opts: { maxPages?: number; signal?: AbortSignal } = {}): Promise<EmbeddingRestampResult | null> {
  if (!await healEnabled(engine, EMBEDDING_RESTAMP_ENABLED_KEY)) return null;
  const { model, dims } = splitEmbeddingSignature(signature);
  if (dims === null) return null;
  const maxPages = opts.maxPages ?? EMBEDDING_RESTAMP_MAX_PAGES;
  const result: EmbeddingRestampResult = { pages: 0, chunks: 0, rejected: 0, capped: false, max_pages: maxPages, failed_runs: 0 };
  try {
    const colId = quoteIdentifier((await resolveActiveEmbeddingColumnFromEngine(engine, { fallbackToLegacy: true })).name);
    const candidates = await engine.executeRaw<{ id: number; source_id: string; slug: string; revision: string; signature: string | null; chunks: number }>(
      `SELECT p.id, p.source_id, p.slug, p.knowledge_revision::text AS revision, p.embedding_signature AS signature,
              (SELECT count(*)::int FROM content_chunks cc WHERE cc.page_id = p.id AND ${chunkGenerationFilter('p', 'cc')}) AS chunks
         FROM pages p WHERE ${restampablePage(colId)}
        ORDER BY p.id LIMIT ${maxPages + 1}`, [signature, model, dims]);
    result.capped = candidates.length > maxPages;
    for (const page of candidates.slice(0, maxPages)) {
      if (opts.signal?.aborted) break;
      await beforeStampForTests?.(page.id);
      const stamped = await engine.transaction(async tx => {
        await tx.lockPageKeys([{ sourceId: page.source_id, slug: page.slug }]);
        const active = quoteIdentifier((await resolveActiveEmbeddingColumnFromEngine(tx, { fallbackToLegacy: true })).name);
        if (active !== colId) return false;
        const rows = await tx.executeRaw<{ id: number }>(
          `UPDATE pages p SET embedding_signature = $1
            WHERE p.id = $4 AND p.knowledge_revision = $5::uuid AND p.embedding_signature IS NOT DISTINCT FROM $6::text
              AND ${restampablePage(active)}
            RETURNING p.id`, [signature, model, dims, page.id, page.revision, page.signature]);
        return rows.length === 1;
      });
      if (stamped) { result.pages++; result.chunks += Number(page.chunks); } else result.rejected++;
    }
    if (result.pages > 0 || await lastFailedRuns(engine) > 0) {
      await recordHealAudit(engine, [{ code: EMBEDDING_RESTAMP_CODE, outcome: 'restamped', attempt: 0, bound: EMBEDDING_RESTAMP_FAILURE_BOUND,
        subject: signature, detail: `${result.pages} page(s), ${result.chunks} chunk(s); ${result.rejected} changed under the stamp${result.capped ? `; more remain past the ${maxPages}-page bound` : ''}` }]);
    }
    return result;
  } catch (error) {
    result.error = error instanceof Error ? error.message : String(error);
    result.failed_runs = await lastFailedRuns(engine).catch(() => 0) + 1;
    await recordHealAudit(engine, [{ code: EMBEDDING_RESTAMP_CODE, outcome: result.failed_runs >= EMBEDDING_RESTAMP_FAILURE_BOUND ? 'escalated' : 'failed',
      attempt: result.failed_runs, bound: EMBEDDING_RESTAMP_FAILURE_BOUND, subject: signature, detail: result.error.slice(0, 300) }]).catch(() => undefined);
    return result;
  }
}

/** The cycle embed phase's entry: restamp under the configured model's signature (W3; never on upgrade, never in a dry run). */
export async function restampCycleSignatures(engine: BrainEngine, signal?: AbortSignal): Promise<EmbeddingRestampResult | null> {
  const { currentEmbeddingSignature } = await import('./embedding.ts');
  const signature = currentEmbeddingSignature();
  return signature ? restampCurrentSpaceSignatures(engine, signature, { signal }) : null;
}

/** The latest restamp audit row when consecutive failed runs reached the bound, else null (doctor's embedding_restamp_stalled). */
export async function restampEscalation(engine: BrainEngine) {
  const last = (await readHealAudit(engine, EMBEDDING_RESTAMP_CODE)).at(-1);
  return last && last.attempt >= EMBEDDING_RESTAMP_FAILURE_BOUND && (last.outcome === 'failed' || last.outcome === 'escalated') ? last : null;
}