Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.4 KB
Raw Blame
/**
 * Large pages (Wave A): leads, snippets and synopses read a bounded prefix,
 * never the whole body. A helper that shows 160-240 characters of a page
 * (exact-slug and alias snippets, relational synopses, the reflex pointer
 * synopsis, the entity card summary, entity-name leads, think anchor rows)
 * reads at most BOUNDED_PREFIX_BYTES of the stored body (fan-out SQL selects
 * `left(compiled_truth, 65536)`), and sanitizes only that prefix
 * (boundedProjectedPrefix in document.ts).
 *
 * Withdrawals: the forget overlay only rewrites facts-fence rows, so a raw
 * prefix with no `gbrain:facts:begin` marker is already what the overlaid
 * body starts with. A prefix that holds a facts fence is replaced by the
 * prefix of the overlaid body, read once per page through the batched
 * snapshot read (the same overlay readPageSnapshot applies), so a withdrawn
 * world fact never shows in a lead. A page the snapshot read no longer
 * returns, or a snapshot read that fails, gets an empty lead (fail closed:
 * a lead is decoration, so the row stays and only its text is withheld).
 * A segmented page has no snapshot body: its row carries the stored
 * `truth_lead` (the same raw prefix), and a lead that holds a facts fence is
 * overlaid alone with the page's withdrawal ledger (the snapshot read returns
 * the ledger and no body), never by reading the page's segments.
 */
import type { BrainEngine } from '../engine.ts';
import type { Page } from '../types.ts';
import { isSegmentedPage } from '../page-body/page-shape.ts';
import { pageSnapshotKey } from '../page-snapshot-batch.ts';
import { overlayCanonicalBodies } from '../page-state/snapshot.ts';
import { safeSplitIndex } from '../text-safe.ts';
import { BOUNDED_PREFIX_BYTES, boundedProjectedPrefix } from './document.ts';

/**
 * SQL for the bounded raw prefix of a page's compiled truth that a fan-out
 * query selects instead of the whole column (fixed table aliases only). A
 * segmented page has no `compiled_truth`; its `truth_lead` holds the same raw
 * prefix, so the sanitize path downstream is unchanged. This is the one
 * sanctioned COALESCE of the body column (scripts/check-page-body-readers.ts
 * allows it by name).
 */
export function boundedBodyPrefixSql(alias: string): string {
  return `left(coalesce(${alias}.compiled_truth, ${alias}.truth_lead), ${BOUNDED_PREFIX_BYTES})`;
}

/** The first `maxBytes` UTF-8 bytes of a raw body, cut on a code point; nothing is sanitized. */
export function boundedRawPrefix(body: string | null | undefined, maxBytes: number = BOUNDED_PREFIX_BYTES): string {
  if (typeof body !== 'string') return '';
  let prefix = body.length > maxBytes ? body.slice(0, safeSplitIndex(body, maxBytes)) : body;
  while (Buffer.byteLength(prefix, 'utf8') > maxBytes) {
    prefix = prefix.slice(0, safeSplitIndex(prefix, Math.floor(prefix.length * 0.9)));
  }
  return prefix;
}

/** Whether a raw prefix must be re-read with the withdrawal overlay before it is shown. */
export function prefixNeedsOverlay(prefix: string | null | undefined): boolean {
  return typeof prefix === 'string' && prefix.includes('gbrain:facts:begin');
}

/**
 * Bounds each row's `compiled_truth` to the raw prefix and, for rows whose
 * prefix holds a facts fence, replaces it with the prefix of the
 * withdrawal-overlaid body (one batched snapshot read for all of them; a
 * segmented page's lead is overlaid alone with its ledger).
 * Returns new row objects; the input rows are not mutated.
 */
export async function overlaidBoundedRows<T extends { slug: string; source_id: string; compiled_truth: string | null }>(
  engine: Pick<BrainEngine, 'readPageSnapshotsBatch' | 'executeRaw'>,
  rows: readonly T[],
): Promise<T[]> {
  const bounded = rows.map(row => ({ ...row, compiled_truth: row.compiled_truth == null ? null : boundedRawPrefix(row.compiled_truth) }));
  const leads = new Map(bounded.filter(row => prefixNeedsOverlay(row.compiled_truth)).map(row => [pageSnapshotKey(row.source_id, row.slug), row.compiled_truth!]));
  const pending = [...new Map(bounded.filter(row => prefixNeedsOverlay(row.compiled_truth))
    .map(row => [pageSnapshotKey(row.source_id, row.slug), { slug: row.slug, sourceId: row.source_id }])).values()];
  if (pending.length === 0) return bounded;
  const overlaid = new Map<string, string>();
  const query = <R>(sql: string, params?: unknown[]) => engine.executeRaw<R>(sql, params);
  try {
    for (let rest = pending; rest.length > 0;) {
      const batch = await engine.readPageSnapshotsBatch(rest);
      for (const [key, snapshot] of batch.snapshots) {
        if (!isSegmentedPage(snapshot.page)) overlaid.set(key, boundedRawPrefix(snapshot.page.compiled_truth));
        else overlaid.set(key, boundedRawPrefix((await overlayCanonicalBodies(query, leads.get(key)!, '', snapshot.withdrawals,
          { sourceId: snapshot.page.source_id, marker: snapshot.globalPurges })).compiled_truth));
      }
      rest = rest.slice(Math.max(1, batch.covered));
    }
  } catch {
    overlaid.clear();
  }
  return bounded.map(row => prefixNeedsOverlay(row.compiled_truth)
    ? { ...row, compiled_truth: overlaid.get(pageSnapshotKey(row.source_id, row.slug)) ?? '' }
    : row);
}

/** One page's overlaid raw prefix: the snapshot body when the raw prefix holds a facts fence, else the raw prefix. */
export async function overlaidBoundedPrefix(
  engine: Pick<BrainEngine, 'readPageSnapshotsBatch' | 'executeRaw'>,
  page: { slug: string; source_id: string; compiled_truth: string | null },
): Promise<string> {
  const [row] = await overlaidBoundedRows(engine, [page]);
  return row?.compiled_truth ?? '';
}

/** One page's sanitized, credential-projected lead text: the bounded overlaid prefix through boundedProjectedPrefix. */
export async function projectedLead(
  engine: Pick<BrainEngine, 'readPageSnapshotsBatch' | 'executeRaw'>,
  page: { slug: string; source_id: string; compiled_truth: string | null },
): Promise<string> {
  return boundedProjectedPrefix(await overlaidBoundedPrefix(engine, page));
}

/** The raw lead source of a page read whole (getPage): its compiled truth, or a segmented page's stored `truth_lead` (its body fields throw). */
export async function pageLeadSource(engine: Pick<BrainEngine, 'executeRaw'>, page: Pick<Page, 'id' | 'body_storage' | 'compiled_truth'>): Promise<string | null> {
  if (!isSegmentedPage(page)) return page.compiled_truth;
  const [row] = await engine.executeRaw<{ truth_lead: string | null }>('SELECT truth_lead FROM pages WHERE id = $1', [page.id]);
  return row?.truth_lead ?? null;
}