Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
12.7 KB
Raw Blame
/**
 * #4592 — get_stats / get_health / get_brain_identity honor the caller's
 * source scope.
 *
 * The leak class: aggregates leak by SUBTRACTION. Since #4433 confined
 * sources_list, a source-scoped remote grant could still recover an excluded
 * source's page count (and type mix) by comparing get_stats against its own
 * scoped reads. This suite pins the closure at three layers:
 *
 *  - ENGINE: getStats/getHealth take an optional scope; every counter,
 *    coverage numerator AND denominator, and degree confines to it. A link
 *    contributes only when BOTH endpoints are in scope (X8: a
 *    granted→ungranted edge must not leak the far side through a degree,
 *    nor rescue a page from orphan-hood).
 *  - FAIL-CLOSED SHAPES (T11): an explicit empty sourceIds array and the
 *    remote `__all__` sentinel scalar both produce ZEROS, never brain-wide.
 *  - OP LAYER (#4433 ladder): trusted local (`remote === false`) keeps the
 *    brain-wide view; every remote shape (scalar / federated array /
 *    sentinel) is confined. get_brain_identity rides the same ladder (it is
 *    read-scope and was the quiet third aggregate surface).
 *
 * The differential assertion at the bottom is the class-closer: mutating an
 * EXCLUDED source must not move any number a scoped caller can see.
 *
 * PGLite-backed with a DATABASE_URL-gated real-Postgres parity arm (same
 * seed, same assertions — the engines' scope predicates must agree).
 */

import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { operationsByName } from '../src/core/operations.ts';
import type { OperationContext } from '../src/core/operations.ts';
import type { BrainEngine } from '../src/core/engine.ts';

const SRCA = 'scopesrca';
const SRCB = 'scopesrcb';

async function seed(engine: BrainEngine): Promise<void> {
  // Direct row inserts: sources_add demands a committed git repo; the
  // registration row is all the scope predicates key on (same pattern as
  // test/remote-privacy-sweep.test.ts).
  await engine.executeRaw(
    `INSERT INTO sources (id, name) VALUES ('${SRCA}', '${SRCA}'), ('${SRCB}', '${SRCB}')
     ON CONFLICT (id) DO NOTHING`,
  );
  const put = async (sourceId: string, slug: string, title: string, type: string, body: string) => {
    await engine.putPage(slug, { title, type, compiled_truth: `# ${title}\n\n${body}\n` }, { sourceId });
  };
  await put(SRCA, 'people/alice-example', 'Alice Example', 'person', 'srca entity page');
  await put(SRCA, 'notes/alpha', 'Alpha Note', 'note', 'srca note page linking [[people/alice-example]]');
  await put(SRCB, 'people/bob-example', 'Bob Example', 'person', 'srcb entity page');
  const id = async (slug: string, src: string) => {
    const rows = await engine.executeRaw<{ id: number }>(
      `SELECT id FROM pages WHERE slug = '${slug}' AND source_id = '${src}'`,
    );
    return rows[0].id;
  };
  const alice = await id('people/alice-example', SRCA);
  const alpha = await id('notes/alpha', SRCA);
  const bob = await id('people/bob-example', SRCB);
  // In-scope pair, granted→ungranted, ungranted→granted (the X8 seeds).
  await engine.executeRaw(
    `INSERT INTO links (from_page_id, to_page_id, link_type) VALUES
       (${alpha}, ${alice}, 'wikilink'),
       (${alice}, ${bob}, 'wikilink'),
       (${bob}, ${alpha}, 'wikilink')`,
  );
  await engine.executeRaw(
    `INSERT INTO timeline_entries (page_id, date, summary) VALUES
       (${alice}, '2026-08-01', 'srca event'),
       (${bob}, '2026-08-02', 'srcb event')`,
  );
  await engine.executeRaw(
    `INSERT INTO tags (page_id, tag) VALUES (${alpha}, 'srca-tag'), (${bob}, 'srcb-tag')
     ON CONFLICT DO NOTHING`,
  );
  // Direct chunk rows: engine.putPage alone doesn't chunk (that's the
  // import/ops layer); the scope predicate routes chunks through their page
  // join, which is what these rows pin.
  await engine.executeRaw(
    `INSERT INTO content_chunks (page_id, chunk_index, chunk_text) VALUES
       (${alice}, 0, 'srca chunk'), (${alpha}, 0, 'srca chunk 2'), (${bob}, 0, 'srcb chunk')`,
  );
}

function scopeAssertions(getEngine: () => BrainEngine) {
  test('unscoped view is brain-wide; scoped views confine every counter', async () => {
    const engine = getEngine();
    const all = await engine.getStats();
    const a = await engine.getStats({ sourceIds: [SRCA] });
    const b = await engine.getStats({ sourceIds: [SRCB] });
    const both = await engine.getStats({ sourceIds: [SRCA, SRCB] });

    expect(a.page_count).toBe(2);
    expect(b.page_count).toBe(1);
    expect(both.page_count).toBe(3);
    expect(all.page_count).toBeGreaterThanOrEqual(3);
    // Both-endpoint rule: srca alone sees ONLY alpha→alice; the two
    // cross-boundary edges vanish from every single-source view.
    expect(a.link_count).toBe(1);
    expect(b.link_count).toBe(0);
    expect(both.link_count).toBe(3);
    expect(a.tag_count).toBe(1);
    expect(b.tag_count).toBe(1);
    expect(a.timeline_entry_count).toBe(1);
    expect(b.timeline_entry_count).toBe(1);
    // pages_by_type confines too (the issue's named recoverable field).
    expect(a.pages_by_type.person).toBe(1);
    expect(a.pages_by_type.note).toBe(1);
    expect(b.pages_by_type.person).toBe(1);
    expect(b.pages_by_type.note).toBeUndefined();
    // Chunks route through their page joins.
    expect(a.chunk_count).toBe(2);
    expect(b.chunk_count).toBe(1);
    expect(a.chunk_count + b.chunk_count).toBe(both.chunk_count);
  });

  test('T11 fail-closed shapes: empty grant array and the __all__ sentinel produce zeros', async () => {
    const engine = getEngine();
    for (const scope of [{ sourceIds: [] as string[] }, { sourceId: '__all__' }]) {
      const s = await engine.getStats(scope);
      expect(s.page_count).toBe(0);
      expect(s.chunk_count).toBe(0);
      expect(s.link_count).toBe(0);
      expect(s.tag_count).toBe(0);
      expect(s.timeline_entry_count).toBe(0);
      expect(Object.keys(s.pages_by_type)).toHaveLength(0);
      const h = await engine.getHealth(scope);
      expect(h.page_count).toBe(0);
      expect(h.entity_page_count).toBe(0);
      expect(h.most_connected).toHaveLength(0);
    }
  });

  test('X8: degrees, denominators, and the islanded predicate scope by BOTH endpoints', async () => {
    const engine = getEngine();
    const hA = await engine.getHealth({ sourceIds: [SRCA] });
    // Alice's degree inside srca: alpha→alice only (her edge to bob and
    // bob's edge to alpha are out-of-scope on the far end).
    const alice = hA.most_connected.find(m => m.slug === 'people/alice-example');
    expect(alice?.link_count).toBe(1);
    expect(hA.most_connected.some(m => m.slug === 'people/bob-example')).toBe(false);
    // entity denominator = srca entities only.
    expect(hA.entity_page_count).toBe(1);

    const hB = await engine.getHealth({ sourceIds: [SRCB] });
    // Bob's only edges cross the boundary: inside srcb he is islanded and
    // his degree is zero — the far side must not rescue or leak.
    const bob = hB.most_connected.find(m => m.slug === 'people/bob-example');
    expect(bob?.link_count).toBe(0);
    expect(hB.orphan_pages).toBeGreaterThanOrEqual(1);

    const hBoth = await engine.getHealth({ sourceIds: [SRCA, SRCB] });
    const bobBoth = hBoth.most_connected.find(m => m.slug === 'people/bob-example');
    expect(bobBoth?.link_count).toBe(2);
  });

  test('differential class-closer: mutating an EXCLUDED source moves nothing a scoped caller sees', async () => {
    const engine = getEngine();
    const before = await engine.getStats({ sourceIds: [SRCA] });
    const beforeHealth = await engine.getHealth({ sourceIds: [SRCA] });
    await engine.putPage('notes/hidden-growth', { title: 'Hidden Growth', type: 'note', compiled_truth: 'srcb-only content\n' }, { sourceId: SRCB });
    const after = await engine.getStats({ sourceIds: [SRCA] });
    const afterHealth = await engine.getHealth({ sourceIds: [SRCA] });
    expect(after).toEqual(before);
    expect(afterHealth.page_count).toBe(beforeHealth.page_count);
    expect(afterHealth.entity_page_count).toBe(beforeHealth.entity_page_count);
    expect(afterHealth.brain_score).toBe(beforeHealth.brain_score);
    // And the excluded source is visible again the moment it is granted.
    const widened = await engine.getStats({ sourceIds: [SRCA, SRCB] });
    expect(widened.page_count).toBe(before.page_count + 2);
    // Restore the seed shape so later tests stay order-independent.
    await engine.executeRaw(
      `DELETE FROM pages WHERE slug = 'notes/hidden-growth' AND source_id = '${SRCB}'`,
    );
  });
}

describe('#4592 source-scoped stats/health (PGLite)', () => {
  let engine: PGLiteEngine;

  beforeAll(async () => {
    engine = new PGLiteEngine();
    await engine.connect({ engine: 'pglite' } as never);
    await engine.initSchema();
    await seed(engine);
  }, 120_000);

  afterAll(async () => {
    await engine.disconnect();
  });

  scopeAssertions(() => engine);

  // ── Op layer: the #4433 ladder ─────────────────────────────────────────
  const ctxBase = () =>
    ({
      engine,
      remote: true,
      transport: 'http',
      takesHoldersAllowList: ['world'],
    }) as unknown as OperationContext;

  test('remote scalar grant confines get_stats / get_health / get_brain_identity', async () => {
    const ctx = { ...ctxBase(), sourceId: SRCA } as OperationContext;
    const stats = (await operationsByName.get_stats.handler(ctx, {})) as { page_count: number };
    expect(stats.page_count).toBe(2);
    const health = (await operationsByName.get_health.handler(ctx, {})) as {
      page_count: number;
      migrations: unknown;
    };
    expect(health.page_count).toBe(2);
    // Global-by-decision: the host migration ledger has no per-source
    // semantics and stays visible to scoped callers.
    expect(health.migrations).toBeDefined();
    const ident = (await operationsByName.get_brain_identity.handler(ctx, {})) as {
      page_count: number;
    };
    expect(ident.page_count).toBe(2);
  });

  test('remote federated grant uses allowedSources; remote unscoped (__all__) fail-closes to zeros', async () => {
    const fed = {
      ...ctxBase(),
      sourceId: 'default',
      auth: { token: 't', clientId: 'c', scopes: ['read', 'admin'], allowedSources: [SRCA, SRCB] },
    } as OperationContext;
    const stats = (await operationsByName.get_stats.handler(fed, {})) as { page_count: number };
    // Compute the expectation from the engine so this test is independent of
    // whatever mutations earlier tests performed (order-independence).
    const expected = await engine.getStats({ sourceIds: [SRCA, SRCB] });
    expect(stats.page_count).toBe(expected.page_count);
    expect(stats.page_count).toBeGreaterThanOrEqual(3);

    const sentinel = { ...ctxBase(), sourceId: '__all__' } as OperationContext;
    const zeros = (await operationsByName.get_stats.handler(sentinel, {})) as { page_count: number };
    expect(zeros.page_count).toBe(0);
  });

  test('trusted local (remote === false) keeps the brain-wide view, sentinel included', async () => {
    const local = { ...ctxBase(), remote: false, sourceId: '__all__' } as OperationContext;
    const stats = (await operationsByName.get_stats.handler(local, {})) as { page_count: number };
    const brainWide = await engine.getStats();
    expect(stats.page_count).toBe(brainWide.page_count);
    expect(stats.page_count).toBeGreaterThanOrEqual(3);
  });
});

const DATABASE_URL = process.env.DATABASE_URL;
describe.skipIf(!DATABASE_URL)('#4592 source-scoped stats/health (REAL Postgres parity)', () => {
  // Same seed, same engine-level assertions — the two engines' scope
  // predicates must agree (engine-parity iron rule).
  let engine: BrainEngine;

  beforeAll(async () => {
    const { PostgresEngine } = await import('../src/core/postgres-engine.ts');
    const { assertSafeE2eDatabaseUrl } = await import('./helpers/db-guard.ts');
    assertSafeE2eDatabaseUrl(DATABASE_URL!);
    const pg = new PostgresEngine();
    await pg.connect({ database_url: DATABASE_URL! });
    await pg.initSchema();
    engine = pg;
    await engine.executeRaw(`DELETE FROM pages WHERE source_id IN ('${SRCA}', '${SRCB}')`);
    await seed(engine);
  }, 120_000);

  afterAll(async () => {
    // Guard: when beforeAll dies before assigning (e.g. a shard-neighbor
    // leaked a DATABASE_URL that flips the skipIf but fails the db-guard),
    // this hook still runs — a bare TypeError here buries the real error.
    if (!engine) return;
    await engine.executeRaw(`DELETE FROM pages WHERE source_id IN ('${SRCA}', '${SRCB}')`);
    await engine.executeRaw(`DELETE FROM sources WHERE id IN ('${SRCA}', '${SRCB}')`);
    await (engine as { disconnect(): Promise<void> }).disconnect();
  });

  scopeAssertions(() => engine);
});