Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.4 KB
Raw Blame
/**
 * Wave B versions as manifests (spec 5).
 *
 * 1. Protects: a segmented page's version is an O(1) reference row (its body
 *    generation, body_bytes and content_hash, NULL bodies; no segment or
 *    chunk read); segmented retention keeps the newest
 *    `versions.segmented_max_per_page` and prunes oldest-first while bytes
 *    pinned beyond the live generation exceed
 *    max(`versions.segmented_max_pinned_bytes`, body_bytes); inline history is
 *    never pruned by it; a retained version keeps its generation's manifest
 *    rows alive through `sweepSegments`; get_versions returns size and a
 *    body_ref, never a body; revert_version refuses a segmented version with
 *    `page_body_segmented` (PR 3 adds it).
 * 2. Fails when: a segmented version copies or reads the body, retention
 *    prunes inline snapshots or keeps unbounded pinned history, or a revert
 *    rebuilds a page from a NULL body.
 * 3. Runs on PGLite, and on Postgres when DATABASE_URL is set.
 */
import { afterAll, beforeAll, beforeEach, describe, expect, spyOn, test } from 'bun:test';
import type { BrainEngine } from '../../src/core/engine.ts';
import { PGLiteEngine } from '../../src/core/pglite-engine.ts';
import { PAGE_BODY_CONFIG_KEYS } from '../../src/core/page-body/limits.ts';
import { operationsByName } from '../../src/core/operations.ts';
import type { OperationContext } from '../../src/core/ops/contract.ts';
import { isolatedPersistencePostgres } from '../helpers/persistence-postgres.ts';
import { segmentPage } from '../helpers/segmented-chunks-fixture.ts';
import { testBackends } from '../helpers/test-backends.ts';

const SLUG = 'notes/segmented-history';
const KB = 1024;

for (const kind of testBackends()) {
  describe(`segmented versions (${kind})`, () => {
    let engine: BrainEngine;
    let close: () => Promise<void>;
    let pageId: number;

    beforeAll(async () => {
      if (kind === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
      else {
        engine = new PGLiteEngine();
        await engine.connect({});
        await engine.initSchema();
        close = () => engine.disconnect();
      }
    }, 120_000);
    afterAll(async () => { await close?.(); });

    /**
     * Generation 1: occurrences 1 (live through every generation) and 2.
     * Generation 2 closes 2 and adds 3; generation 3 closes 3 and adds 4.
     * A version at generation 1 pins occurrence 2; at generation 2, occurrence 3.
     */
    beforeEach(async () => {
      await engine.executeRaw('DELETE FROM pages');
      await engine.executeRaw('DELETE FROM page_segment_texts');
      await engine.executeRaw(`DELETE FROM config WHERE key IN ($1, $2)`, [PAGE_BODY_CONFIG_KEYS.versionsMaxPerPage, PAGE_BODY_CONFIG_KEYS.versionsMaxPinnedBytes]);
      ({ pageId } = await segmentPage(engine, SLUG, {
        generation: 1,
        bodyBytes: 2 * KB,
        occurrences: [
          { id: 1, byteStart: 0, genFrom: 1, byteLen: KB, chunks: [{ text: 'opening passage' }] },
          { id: 2, byteStart: KB, genFrom: 1, genTo: 2, byteLen: 8 * KB, chunks: [{ text: 'first tail' }] },
          { id: 3, byteStart: KB, genFrom: 2, genTo: 3, byteLen: 8 * KB, chunks: [{ text: 'second tail' }] },
          { id: 4, byteStart: KB, genFrom: 3, byteLen: KB, chunks: [{ text: 'third tail' }] },
        ],
      }));
    });

    const atGeneration = (generation: number) => engine.executeRaw('UPDATE pages SET body_generation = $2 WHERE id = $1', [pageId, generation]);
    const segmentedVersions = async () => (await engine.executeRaw<{ body_generation: number }>(
      `SELECT body_generation FROM page_versions WHERE page_id = $1 AND body_storage = 'segmented' ORDER BY id`, [pageId])).map(r => Number(r.body_generation));

    test('a segmented version is an O(1) reference row that never reads segments or chunks', async () => {
      const exec = spyOn(engine, 'executeRaw');
      try {
        await engine.createVersion(SLUG);
        for (const [sql] of exec.mock.calls) expect(String(sql)).not.toMatch(/page_segment_texts|content_chunks/);
      } finally { exec.mockRestore(); }
      const [row] = await engine.executeRaw<Record<string, unknown>>('SELECT * FROM page_versions WHERE page_id = $1', [pageId]);
      expect(row).toMatchObject({ body_storage: 'segmented', compiled_truth: null, timeline: null, title: SLUG });
      expect(Number(row!.body_generation)).toBe(1);
      expect(Number(row!.body_bytes)).toBe(2 * KB);
      expect(row!.content_hash).toEqual(expect.any(String));
    });

    test('retention keeps the newest versions_max_per_page', async () => {
      await engine.setConfig(PAGE_BODY_CONFIG_KEYS.versionsMaxPerPage, '2');
      for (const generation of [1, 2, 3]) { await atGeneration(generation); await engine.createVersion(SLUG); }
      expect(await segmentedVersions()).toEqual([2, 3]);
    });

    test('retention prunes oldest-first while pinned bytes exceed max(cap, body_bytes)', async () => {
      await engine.setConfig(PAGE_BODY_CONFIG_KEYS.versionsMaxPinnedBytes, String(10 * KB));
      await atGeneration(1); await engine.createVersion(SLUG);
      await atGeneration(2); await engine.createVersion(SLUG);
      // 8 KiB (generation 1) + 8 KiB (generation 2) pinned > 10 KiB: the oldest goes.
      expect(await segmentedVersions()).toEqual([2]);
      // The live generation pins nothing beyond itself.
      await atGeneration(3); await engine.createVersion(SLUG);
      expect(await segmentedVersions()).toEqual([2, 3]);
    });

    test('the byte cap is at least the page body_bytes', async () => {
      await engine.setConfig(PAGE_BODY_CONFIG_KEYS.versionsMaxPinnedBytes, String(KB));
      await engine.executeRaw('UPDATE pages SET body_bytes = $2 WHERE id = $1', [pageId, 64 * KB]);
      await atGeneration(1); await engine.createVersion(SLUG);
      await atGeneration(2); await engine.createVersion(SLUG);
      expect(await segmentedVersions()).toEqual([1, 2]);
    });

    test('inline history is never pruned by segmented retention', async () => {
      await engine.setConfig(PAGE_BODY_CONFIG_KEYS.versionsMaxPerPage, '1');
      const inline = await engine.putPage('notes/inline-history', { type: 'note', title: 'Inline', compiled_truth: 'v0', timeline: '', frontmatter: {} });
      for (let i = 1; i <= 4; i++) {
        await engine.createVersion('notes/inline-history');
        await engine.putPage('notes/inline-history', { type: 'note', title: 'Inline', compiled_truth: `v${i}`, timeline: '', frontmatter: {} });
      }
      const rows = await engine.executeRaw('SELECT id FROM page_versions WHERE page_id = $1', [inline.id]);
      expect(rows).toHaveLength(4);
    });

    test('a retained version keeps its generation manifest rows alive through sweepSegments', async () => {
      await engine.setConfig(PAGE_BODY_CONFIG_KEYS.versionsMaxPerPage, '1');
      await atGeneration(1); await engine.createVersion(SLUG);
      await atGeneration(3); await engine.createVersion(SLUG);
      await engine.sweepSegments({ pageId, graceMs: 0 });
      const occurrences = (await engine.executeRaw<{ occurrence_id: number }>(
        'SELECT occurrence_id FROM page_body_manifest WHERE page_id = $1 ORDER BY occurrence_id', [pageId])).map(r => Number(r.occurrence_id));
      // Generation 3 (the only version, and live) needs 1 and 4; 2 and 3 are dead.
      expect(occurrences).toEqual([1, 4]);
    });

    test('get_versions returns size and a body_ref for segmented versions, never a body', async () => {
      await engine.createVersion(SLUG);
      const ctx = { engine, config: { engine: engine.kind }, remote: false, dryRun: false, logger: { info() {}, warn() {}, error() {} } } as unknown as OperationContext;
      const [meta] = await operationsByName.get_versions!.handler(ctx, { slug: SLUG }) as Array<Record<string, unknown>>;
      expect(meta).toMatchObject({ body_storage: 'segmented', body_bytes: 2 * KB });
      expect(meta).not.toHaveProperty('compiled_truth');
      const [full] = await operationsByName.get_versions!.handler(ctx, { slug: SLUG, include_body: true }) as Array<Record<string, unknown>>;
      expect(full).not.toHaveProperty('compiled_truth');
      expect(full).not.toHaveProperty('timeline');
      expect(full!.body_ref).toEqual({ version_id: full!.id, total_bytes: 2 * KB });
    });

    test('#7800: a segmented version body_ref never names a read get_page does not serve', async () => {
      await engine.createVersion(SLUG);
      const ctx = { engine, config: { engine: engine.kind }, remote: false, dryRun: false, logger: { info() {}, warn() {}, error() {} } } as unknown as OperationContext;
      const [full] = await operationsByName.get_versions!.handler(ctx, { slug: SLUG, include_body: true }) as Array<{ body_ref: { read?: { tool: string; arguments: Record<string, unknown> } } }>;
      const read = full!.body_ref.read;
      const params = operationsByName[read?.tool ?? 'get_page']!.params;
      expect(Object.keys(read?.arguments ?? {}).filter(k => !(k in params))).toEqual([]);
    });

    test('revertToVersion refuses a segmented version with page_body_segmented and writes nothing', async () => {
      const version = await engine.createVersion(SLUG);
      const before = await engine.executeRaw('SELECT body_generation, knowledge_revision FROM pages WHERE id = $1', [pageId]);
      await expect(engine.revertToVersion(SLUG, version.id)).rejects.toMatchObject({ code: 'page_body_segmented' });
      expect(await engine.executeRaw('SELECT body_generation, knowledge_revision FROM pages WHERE id = $1', [pageId])).toEqual(before);
    });
  });
}