Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.6 KB
Raw Blame
/**
 * GST-2497: the sync's held-fact move on a strict source (moveRuledSharedHeld), after the review of GST-2492.
 *
 * 1. Protects: the move's due check is true only when a rule covers a held row's entity and not its holding page (the
 *    planner then moves or re-homes the row), so a rule over the holding page alone never makes every sync plan a move
 *    for nothing; a rule that narrows a held row below its holding page's readers still moves it right after the sync.
 *    On Postgres the plan's config read (holdingHome's sync.write_through) ends at the plan's deadline like its other reads.
 * 2. Fails when: the second of two syncs on such a source runs the held-move plan; a rule over the entity does not move
 *    the row after its sync; the move waits on a session holding the config table past the sync preparation budget.
 * 3. Existing coverage: test/folder-holding-page-gst2492.test.ts (the move, the rule apply, the pages and page_aliases locks).
 * 4. Real seams: the coordinated write on PGLite and Postgres (DATABASE_URL), a managed Git checkout, the policy file
 *    committed to Git and applied by performSync, a second Postgres session holding a table lock, and the engine's raw read.
 */
import { afterEach, describe, expect, spyOn, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import postgres from '#postgres';
import { writeFileSync } from 'node:fs';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import type { OperationContext } from '../src/core/ops/contract.ts';
import { operationsByName } from '../src/core/operations.ts';
import { performSync } from '../src/commands/sync.ts';
import { serializePolicyYaml, type FolderRule } from '../src/core/access/folder-rules.ts';
import { policySeams, proposeRevision } from '../src/core/access/policy.ts';
import { commitPolicyFile, POLICY_FILE } from '../src/core/access/policy-git.ts';
import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';
import { resetSyncPreparationBudget, syncPreparationBudgetMs } from '../src/core/persistence/sync-waivers.ts';
import { moveRuledSharedHeld } from '../src/core/facts/held-fact-move.ts';
import { durableGitRepo } from './helpers/git-publication.ts';
import { managedBrain, settleManagedGitEffects, type ManagedBrain } from './helpers/managed-brain.ts';
import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';

const HOLD = 'memory/unattributed';
const gitRepo = ({ root }: { root: string }) => { writeFileSync(join(root, '.gitignore'), '\n'); durableGitRepo(root, ['.gitignore']); };
const call = (ctx: OperationContext, name: string, params: Record<string, unknown>) =>
  operationsByName[name]!.handler(ctx, { request_id: randomUUID(), ...params }) as Promise<Record<string, any>>;
const remember = (ctx: OperationContext, fact: string, entity: string) => call(ctx, 'remember', { fact, entity, provenance: 'chat 2026-11-13' });
const rule = (id: string, prefix: string, readers: string[]): FolderRule => ({ id, prefix, readable_by: readers.map(r => `member:${r}`).sort() });
const heldOn = async (engine: BrainEngine, claim: string) => (await engine.executeRaw<{ slug: string }>(
  `SELECT source_markdown_slug AS slug FROM facts WHERE source_id = 'default' AND fact = $1 AND expired_at IS NULL`, [claim])).map(r => r.slug);
const caught = <T>(p: Promise<T>) => p.then(() => null, (error: Record<string, any>) => error);

for (const backend of testBackends()) describe(`[${backend}] the sync's held-fact move (GST-2497)`, () => {
  const databaseUrl = backend === 'postgres' ? requirePostgresTestDatabase() : undefined;
  afterEach(() => { policySeams.afterInstall = undefined; });
  const strict = (run: (brain: ManagedBrain) => Promise<void>) => managedBrain(async brain => {
    await brain.engine.executeRaw(`UPDATE sources SET config = config || '{"canonical":"git"}'::jsonb WHERE id='default'`);
    await run(brain);
  }, { databaseUrl, setup: gitRepo });

  test('a rule over the holding page but not the entity makes no sync plan a move; a rule over the entity still moves it after its sync', () => strict(async ({ engine, ctx, root }) => {
    const policy = (list: FolderRule[]) => commitPolicyFile(root, POLICY_FILE, () => serializePolicyYaml(list), 'access: rule');
    const sync = () => performSync(engine, { sourceId: 'default', repoPath: root, noPull: true, noEmbed: true } as never);
    policy([rule('memory', 'memory/', ['alice-example', 'bob-example'])]);
    await sync();
    const claim = 'The bob-example garden plan starts in spring.';
    expect(await remember(ctx, claim, 'people/bob-example')).toMatchObject({ page: HOLD });
    await settleManagedGitEffects(engine);
    const plans: string[] = [];
    const real = engine.executeRaw;
    const counted = spyOn(engine, 'executeRaw').mockImplementation(function (this: BrainEngine, sql: string, ...rest: unknown[]) {
      if (sql.includes('source_markdown_slug AS from_slug')) plans.push(sql);
      return (real as (...a: unknown[]) => Promise<unknown>).call(this, sql, ...rest);
    } as BrainEngine['executeRaw']);
    try {
      await sync();
      const first = plans.length;
      await sync();
      expect([first, plans.length - first]).toEqual([0, 0]);
      expect(await moveRuledSharedHeld(engine, 'default')).toBeNull();
    } finally { counted.mockRestore(); }
    expect(await heldOn(engine, claim)).toEqual([HOLD]);
    policy([rule('memory', 'memory/', ['alice-example', 'bob-example']), rule('people', 'people/', ['alice-example'])]);
    await sync();
    await settleManagedGitEffects(engine);
    expect(await heldOn(engine, claim)).toEqual(['people/memory/unattributed']);
    expect(await moveRuledSharedHeld(engine, 'default')).toBeNull();
  }), 300_000);

  test.skipIf(backend !== 'postgres')('on the sync path a due held move ends at the sync preparation budget while another session locks the config table; once the lock drops it moves', () => strict(async ({ engine, ctx }) => {
    const entity = 'clients/acme-example/brief';
    const claim = 'The acme-example brief carries a config-locked clause.';
    expect(await remember(ctx, claim, entity)).toMatchObject({ page: HOLD });
    policySeams.afterInstall = () => { throw new Error('interrupted'); };
    await expect(proposeRevision(engine, 'default', [rule('clients', 'clients/acme-example/', ['alice-example'])], { origin: 'cli', store: 'database', approved: false })).rejects.toThrow('interrupted');
    policySeams.afterInstall = undefined;
    __resetPrivateVisibilityCacheForTests();
    const budget = 1_000;
    await engine.setConfig('persistence.sync_preparation_ms', String(budget));
    resetSyncPreparationBudget();
    expect(await syncPreparationBudgetMs(engine)).toBe(budget);
    const [{ db }] = await engine.executeRaw<{ db: string }>('SELECT current_database() AS db');
    const url = new URL(databaseUrl!); url.pathname = `/${db}`;
    const holder = postgres(url.toString(), { max: 1, prepare: false, onnotice: () => {} });
    try {
      const ended = await holder.begin(async sql => {
        await sql.unsafe('LOCK TABLE config IN ACCESS EXCLUSIVE MODE');
        const started = performance.now();
        const error = await caught(moveRuledSharedHeld(engine, 'default'));
        return { code: error?.code, ms: performance.now() - started };
      });
      expect(ended.code).toBe('preparation_deadline');
      expect(ended.ms).toBeLessThan(budget + 3_000);
    } finally { await holder.end(); resetSyncPreparationBudget(); }
    expect(await moveRuledSharedHeld(engine, 'default')).toMatchObject({ rehomed: 1, unmovable: [], write_errors: 0 });
    expect(await heldOn(engine, claim)).toEqual(['clients/acme-example/memory/unattributed']);
  }), 300_000);
});