Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.8 KB
Raw Blame
import { createHash } from 'node:crypto';
import { FACTS_FENCE_BEGIN, FACTS_FENCE_END, parseFactsFence, parseFactsFenceFor, renderFactsTable, type ParsedFact } from '../facts-fence.ts';
import type { PageWithdrawal } from '../page-state/types.ts';
import { OperationError } from '../ops/contract.ts';
import { normalizeLoweredClaim } from './withdrawal-schema.ts';

export const WITHDRAWAL_MARKER_LIMIT = 16_384;
/** A withdrawal reads a held row's `entity` cell wherever writes let it be (memory/unattributed, GST-2492). */
const READER = { reader: true } as const;

/** Preserve historical expiry and context while emitting the parser's explicit withdrawal marker. */
export function withdrawnFact(fact: ParsedFact, date: string, reason = 'memory withdrawn'): ParsedFact {
  const prior = fact.context?.trim();
  const context = /^forgotten\s*:/i.test(prior ?? '') ? prior : [`forgotten: ${reason}`, prior].filter(Boolean).join(' | ');
  const validUntil = fact.validUntil && /^\d{4}-\d{2}-\d{2}$/.test(fact.validUntil) && fact.validUntil < date
    ? fact.validUntil : date;
  return { ...fact, active: false, forgotten: true, validUntil, context };
}

/** Enumerate every complete legacy fence; leave ambiguous tails untouched for diagnostics. */
export function withdrawalFenceBlocks(body: string): Array<{ start: number; end: number; parsed: ReturnType<typeof parseFactsFence> }> {
  const blocks: Array<{ start: number; end: number; parsed: ReturnType<typeof parseFactsFence> }> = [];
  const markers = literalFenceMarkers(body);
  let open: { start: number } | undefined;
  for (const marker of markers) {
    if (marker.kind === 'begin') {
      if (marker.inlineCode) continue;
      open = { start: marker.start };
      continue;
    }
    if (!open) continue;
    blocks.push({ start: open.start, end: marker.end, parsed: parseFactsFenceFor(body.slice(open.start, marker.end), READER) });
    open = undefined;
  }
  const inline: typeof blocks = [];
  let blockIndex = 0;
  for (const candidate of inlineCodeFenceBlocks(body, markers)) {
    while (blockIndex < blocks.length && blocks[blockIndex].end <= candidate.start) blockIndex++;
    if (!blocks[blockIndex] || candidate.end <= blocks[blockIndex].start) inline.push(candidate);
  }
  return [...blocks, ...inline].sort((a, b) => a.start - b.start);
}

interface FenceMarker { start: number; end: number; kind: 'begin' | 'end'; inlineCode: boolean }

function literalFenceMarkers(body: string): FenceMarker[] {
  const markers: FenceMarker[] = [];
  const tokens = new RegExp([FACTS_FENCE_BEGIN, FACTS_FENCE_END, '`'].join('|'), 'g');
  let offset = 0;
  for (const line of body.split('\n')) {
    let ticks = 0;
    const lastTick = line.lastIndexOf('`');
    for (const token of line.matchAll(tokens)) {
      if (token[0] === '`') { ticks++; continue; }
      if (markers.length >= WITHDRAWAL_MARKER_LIMIT) throw new OperationError('withdrawal_capacity',
        'The fact-fence marker limit was exceeded; incomplete withdrawal discovery is refused.',
        'Inspect and repair excessive malformed fact fences on the host before retrying. See docs/guides/concurrent-writes.md#withdrawal-recovery.');
      const start = offset + token.index;
      markers.push({ start, end: start + token[0].length, kind: token[0] === FACTS_FENCE_BEGIN ? 'begin' : 'end',
        inlineCode: ticks % 2 === 1 && lastTick >= token.index + token[0].length });
    }
    offset += line.length + 1;
  }
  return markers;
}

function inlineCodeFenceBlocks(body: string, markers: FenceMarker[]): Array<{ start: number; end: number; parsed: ReturnType<typeof parseFactsFence> }> {
  const blocks: Array<{ start: number; end: number; parsed: ReturnType<typeof parseFactsFence> }> = [];
  for (let i = 0; i < markers.length; i++) {
    const begin = markers[i], end = markers[i + 1];
    if (begin.kind !== 'begin' || end?.kind !== 'end' || !(begin.inlineCode || end.inlineCode)) continue;
    const parsed = parseFactsFenceFor(body.slice(begin.start, end.end), READER);
    if (parsed.facts.length || parsed.warnings.length) blocks.push({ start: begin.start, end: end.end, parsed });
  }
  return blocks;
}

/** Return only malformed live fence segments. */
export function ambiguousWithdrawalFenceSegments(body: string): string[] {
  const markers = literalFenceMarkers(body), segments: string[] = [], inlineBlocks = inlineCodeFenceBlocks(body, markers);
  const inlineEnds = new Set(inlineBlocks.map(block => block.end));
  let boundary = 0;
  let open: { start: number } | undefined;
  for (const marker of markers) {
    if (marker.kind === 'begin') {
      if (marker.inlineCode) continue;
      if (open) segments.push(body.slice(open.start, marker.start));
      open = { start: marker.start };
      continue;
    }
    if (!open) {
      if (inlineEnds.has(marker.end)) { boundary = marker.end; continue; }
      if (marker.inlineCode) continue;
      segments.push(body.slice(boundary, marker.end));
      boundary = marker.end;
      continue;
    }
    const segment = body.slice(open.start, marker.end);
    if (parseFactsFenceFor(segment, READER).warnings.length) segments.push(segment);
    boundary = marker.end;
    open = undefined;
  }
  if (open) segments.push(body.slice(open.start));
  for (const block of inlineBlocks) {
    if (block.parsed.warnings.length) segments.push(body.slice(block.start, block.end));
  }
  return segments;
}

/** A shortlisted claim inside an unparseable live fence is conservatively page-affecting. */
export function hasAmbiguousWithdrawalFence(body: string): boolean {
  return ambiguousWithdrawalFenceSegments(body).length > 0;
}

/** Both fingerprints `overlayWithdrawalBody` looks a fence row's claim up by: the normalized claim and the raw normalized-line claim. */
export function fenceClaimHashes(normalizedTexts: readonly string[]): string[] {
  const hashes = new Set<string>();
  for (const text of normalizedTexts) {
    if (!text.includes('gbrain:facts:begin')) continue;
    for (const block of withdrawalFenceBlocks(text)) {
      for (const f of block.parsed.facts) {
        hashes.add(createHash('sha256').update(normalizeLoweredClaim(f.claim)).digest('hex'));
        hashes.add(createHash('sha256').update(f.claim).digest('hex'));
      }
    }
  }
  return [...hashes];
}

/**
 * Wave B: the per-segment form of the overlay's block walk. A segment is overlaid alone (`overlayWithdrawalBody` over
 * its text, so the WITHDRAWAL_MARKER_LIMIT applies to one segment), which is exact for every block inside it: the
 * segmenter never cuts inside a fence block except at a forced cut. Returns the runs of a block a forced cut splits,
 * which a lone segment cannot overlay: `[0, head)`, the end of a block opened in an earlier segment (`entryOpen`), and
 * `[tail, length)`, a block still open at the segment's end (`tail = 0` when the whole segment is inside one).
 */
export function partialFenceRuns(text: string, entryOpen: boolean): { head: number; tail: number } {
  let open: number | null = entryOpen ? -1 : null;
  let head = 0;
  for (const marker of literalFenceMarkers(text)) {
    if (marker.kind === 'begin') {
      if (!marker.inlineCode) open = marker.start;
      continue;
    }
    if (open === null) continue;
    if (open === -1) head = marker.end;
    open = null;
  }
  return { head, tail: open === null ? text.length : Math.max(open, 0) };
}

/** Apply hashes from DB-normalized companion text to the original Markdown. */
export function overlayWithdrawalBody(body: string, normalizedBody: string, withdrawals: PageWithdrawal[]): string {
  if (!withdrawals.length || !body.includes('gbrain:facts:begin')) return body;
  const ledger = new Map<string, PageWithdrawal>();
  for (const w of withdrawals) {
    const key = `${w.visibility}:${w.fact_hash}`;
    if (!ledger.get(key)?.purged) ledger.set(key, w);
  }
  const blocks = withdrawalFenceBlocks(body), normalized = withdrawalFenceBlocks(normalizedBody);
  for (let i = blocks.length - 1; i >= 0; i--) {
    const block = blocks[i], norm = normalized[i];
    if (!norm || block.parsed.warnings.length || norm.parsed.warnings.length) continue;
    const claims = new Map(norm.parsed.facts.map(f => [f.rowNum, f.claim]));
    let changed = false;
    // A purge tombstone drops the row (the claim leaves the canonical text); a withdrawal strikes it.
    const facts = block.parsed.facts.flatMap(f => {
      const claim = claims.get(f.rowNum);
      if (claim === undefined) return [f];
      const entry = ledger.get(`${f.visibility}:${createHash('sha256').update(normalizeLoweredClaim(claim)).digest('hex')}`)
        ?? ledger.get(`${f.visibility}:${createHash('sha256').update(claim).digest('hex')}`);
      if (!entry) return [f];
      changed = true;
      return entry.purged ? [] : [withdrawnFact(f, new Date(entry.withdrawn_at).toISOString().slice(0, 10))];
    });
    if (changed) body = body.slice(0, block.start) + renderFactsTable(facts) + body.slice(block.end);
  }
  return body;
}