Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.4 KB
Raw Blame
/**
 * #5470 no-op kernel: one request-free check, beneath the connector, managed
 * import, working-tree sync and company-profile paths, that decides whether an
 * item can skip admission because publishing it would change nothing.
 *
 * Each path runs its publication preparer on an unadmitted, synthetic request
 * (the preparers read only the database and the local canonical root, so this
 * runs on the connector or import host), then asks the kernel. An item is
 * skipped only when:
 *   - the prepared mutation is a no-op and observed the snapshot revision, and the
 *     page still holds that revision when the kernel reads it,
 *   - no projection work is pending (safe-chunk re-seal, text projection behind
 *     the knowledge revision, an embedded page with no contextual mode, or
 *     unembedded chunks when the publication would queue embedding),
 *   - no metadata work is pending (the stored source path differs),
 *   - the page exists and is not deleted, and
 *   - the page has no canonical file by design (database-only), or the local
 *     canonical file bytes equal the serialized page.
 * The preparer's own `validate` then re-checks authority, source incarnation,
 * identity and revision before the skip is counted. Anything else is admitted
 * and published exactly as before.
 *
 * #5751: a caller may waive two admit reasons that its no-op publication can
 * never resolve (so admitting them re-admits the same item on every run): a
 * pending contextual-mode stamp (only an import that changes the page, or
 * `gbrain repair contextual-mode`, stamps it) and canonical file bytes that
 * differ from the prepared content while parsing to the same page. Every
 * other check still runs; the result lists each waiver it applied.
 */
import type { BrainEngine } from '../engine.ts';
import type { PreparedMutation } from './coordinator.ts';
import { persistenceFileHash } from './coordinator.ts';
import type { WriteRequest } from './model.ts';
import type { PageSnapshot } from '../page-state/types.ts';
import { belowSafeChunkFence, chunkGenerationFilter, chunkManifestReads, SAFE_FENCE_CHUNKER_VERSION } from '../search/safe-chunks.ts';
import { fileContentHash } from './large-file.ts';
import { embeddingWriteTarget } from '../page-state/projections.ts';
import { quoteIdentifier } from '../search/embedding-column.ts';

export interface NoopKernelResult {
  contentUnchanged: boolean;
  projectionWorkRequired: boolean;
  metadataWorkRequired: boolean;
  observedRevision: string | null;
  /** Why the item is admitted; absent when it may be skipped. */
  admitReason?: 'content_changed' | 'page_missing' | 'page_deleted' | 'revision_moved' | 'projection_work' | 'metadata_work' | 'canonical_file_differs';
  /** The caller's waivers that this skip relied on. */
  waived?: NoopKernelWaiver[];
}
export type NoopKernelWaiver = 'contextual_mode' | 'canonical_file_differs';

/** A request-shaped value for preparers; it is never admitted or persisted. */
export function screeningRequest(fields: Pick<WriteRequest, 'source_id' | 'source_incarnation' | 'slug' | 'page_id' | 'worktree_id' | 'authority' | 'intent'>
  & Partial<WriteRequest>): WriteRequest {
  return { id: '00000000-0000-4000-8000-000000000000', request_id: '00000000-0000-4000-8000-000000000000', operation: 'submit_job', state: 'queued',
    principal_kind: fields.authority.principal.kind, principal_id: fields.authority.principal.id, created_at: new Date().toISOString(),
    updated_at: new Date().toISOString(), protocol_version: 1, target_kind: 'page', ...fields } as unknown as WriteRequest;
}

/** What the kernel reads about a live page: its projection state, revision and recorded origin. */
export interface KernelPage { id: number | string; slug: string; chunker_version: number | null; text_projection_revision: string | null; knowledge_revision: string;
  mode_pending: boolean; unembedded: boolean; source_path: string | null }
/**
 * The kernel's page read; callers append the `WHERE` (one page by id, or #6712 PR 1 a prescreened run by slug).
 * `manifest` is chunkManifestReads: a write role without the segment grants that sees no segmented chunk reads it too.
 */
export const kernelPageSql = (manifest: boolean) => `SELECT p.id,p.slug,p.chunker_version,p.text_projection_revision::text,p.knowledge_revision::text,p.source_path,
      (p.contextual_retrieval_mode IS NULL AND EXISTS (SELECT 1 FROM content_chunks c WHERE c.page_id=p.id AND c.embedding IS NOT NULL AND ${chunkGenerationFilter('p', 'c', manifest)})) AS mode_pending,
      EXISTS (SELECT 1 FROM content_chunks c WHERE c.page_id=p.id AND c.embedding IS NULL AND ${chunkGenerationFilter('p', 'c', manifest)}) AS unembedded
    FROM pages p`;

/**
 * The projection and metadata work a no-op would leave undone on `page` (null: none): a safe-chunk re-seal, a text
 * projection behind the knowledge revision, a contextual-mode stamp (unless `waived` lists it), unembedded chunks when
 * the publication would queue embedding, or a stored source path that differs.
 */
export function kernelPageWork(page: KernelPage, input: { sourcePath: string | null; embeddingRequested?: boolean; waived?: readonly NoopKernelWaiver[] }): 'projection_work' | 'metadata_work' | null {
  if (belowSafeChunkFence(page.chunker_version === null ? null : Number(page.chunker_version)) || page.text_projection_revision !== page.knowledge_revision
    || page.mode_pending === true && !input.waived?.includes('contextual_mode') || input.embeddingRequested === true && page.unembedded === true) return 'projection_work';
  return input.sourcePath !== null && page.source_path !== input.sourcePath ? 'metadata_work' : null;
}

export async function inspectUnchanged(engine: Pick<BrainEngine, 'kind' | 'executeRaw'>, input: {
  prepared: PreparedMutation; snapshot: PageSnapshot | null; sourcePath: string | null; databaseOnly: boolean;
  /** The publication would queue an embedding effect: a page with unembedded chunks is then not skipped. */
  embeddingRequested?: boolean;
  waive?: readonly NoopKernelWaiver[];
}): Promise<NoopKernelResult> {
  const { prepared, snapshot } = input;
  const observedRevision = prepared.observedRevision ?? null;
  const unchanged = prepared.noop === true || prepared.contentUnchanged === true;
  const result = (reason?: NoopKernelResult['admitReason'], flags: Partial<NoopKernelResult> = {}): NoopKernelResult => ({
    contentUnchanged: unchanged, projectionWorkRequired: false, metadataWorkRequired: false, observedRevision, ...flags,
    ...(reason ? { admitReason: reason } : {}) });
  if (!snapshot) return result('page_missing');
  if (snapshot.page.deleted_at != null) return result('page_deleted');
  if (!unchanged) return result('content_changed');
  if (observedRevision !== snapshot.revision) return result('revision_moved');
  const [page] = await engine.executeRaw<KernelPage>(`${kernelPageSql(await chunkManifestReads(engine))} WHERE p.id=$1 AND p.deleted_at IS NULL`, [snapshot.page.id]);
  if (!page) return result('page_missing');
  // The page's current revision, read after the preparer ran: a write that landed since the snapshot was read is admitted.
  if (page.knowledge_revision != null && page.knowledge_revision !== snapshot.revision) return result('revision_moved');
  const waived: NoopKernelWaiver[] = [];
  if (page.mode_pending === true && input.waive?.includes('contextual_mode')) waived.push('contextual_mode');
  const pending = kernelPageWork(page, { sourcePath: input.sourcePath, embeddingRequested: input.embeddingRequested, waived });
  if (pending === 'projection_work') return result(pending, { projectionWorkRequired: true });
  if (pending === 'metadata_work') return result(pending, { metadataWorkRequired: true });
  if (!input.databaseOnly) {
    const file = prepared.file;
    const onDisk = file && file.content !== null ? persistenceFileHash(file.path) : null;
    if (!file || file.content === null || onDisk !== fileContentHash(file.content)) {
      if (onDisk === null || !input.waive?.includes('canonical_file_differs')) return result('canonical_file_differs');
      waived.push('canonical_file_differs');
    }
  }
  return result(undefined, waived.length ? { waived } : {});
}

/**
 * #7866: whether a content no-op leaves the page no embedding work: its text projection is sealed at its revision and at or
 * above the safe-chunk fence (the no-op rebuilds neither, as kernelPageWork says), and every chunk of its current generation
 * has a vector in the active column for its exact text. Such a no-op queues no embedding effect (a re-sync, a conversion's
 * strict pass); a page with projection work, a chunk never embedded, or one embedded for other text still gets one, as
 * before. A model change keeps the column's vectors until `gbrain embed --stale`, as for any page that was not written.
 */
export async function chunksEmbeddedAsIs(engine: Pick<BrainEngine, 'kind' | 'executeRaw'>, pageId: number): Promise<boolean> {
  const { column } = await embeddingWriteTarget(engine);
  const [row] = await engine.executeRaw<{ current: boolean }>(`SELECT p.text_projection_revision IS NOT DISTINCT FROM p.knowledge_revision
      AND COALESCE(p.chunker_version, 0) >= ${SAFE_FENCE_CHUNKER_VERSION}
      AND NOT EXISTS (SELECT 1 FROM content_chunks c WHERE c.page_id=p.id AND ${chunkGenerationFilter('p', 'c', await chunkManifestReads(engine))}
        AND (c.${quoteIdentifier(column.name)} IS NULL OR c.embedded_at IS NULL OR c.embedded_text_hash IS DISTINCT FROM md5(c.chunk_text))) AS current
    FROM pages p WHERE p.id=$1`, [pageId]);
  return row?.current === true;
}