Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
20.6 KB
Raw Blame
/**
 * #4224 — cross-source entity identity (federation v1).
 *
 * Covers: the v137 entity_identities migration, the manual-only helpers
 * (link/unlink/list, identity key = (source_id, slug)), the three ops
 * (localOnly writes, source-scoped list), and the flag-gated retrieval
 * union on get_links/get_backlinks (default OFF; never widens a federated
 * caller's grant).
 *
 * PGLite in-memory. Engine parity comes free: every helper goes through
 * engine.executeRaw with ONE SQL text (no per-engine SQL) — see also the
 * DATABASE_URL-gated check in test/e2e/engine-parity.test.ts.
 */

import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import {
  linkEntityIdentity,
  unlinkEntityIdentity,
  listEntityIdentities,
  unionLinksAcrossIdentity,
  isIdentityUnionEnabled,
  validateEntityId,
  ENTITY_IDENTITY_UNION_CONFIG_KEY,
} from '../src/core/entity-identity.ts';
import { operationsByName } from '../src/core/operations.ts';
import type { OperationContext } from '../src/core/operations.ts';

let engine: PGLiteEngine;

const localCtx = (over: Partial<OperationContext> = {}): OperationContext =>
  ({ engine, remote: false, ...over } as unknown as OperationContext);
const remoteCtx = (over: Partial<OperationContext> = {}): OperationContext =>
  ({ engine, remote: true, ...over } as unknown as OperationContext);

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
}, 120_000);

afterAll(async () => {
  if (engine) await engine.disconnect();
}, 60_000);

beforeEach(async () => {
  for (const t of ['entity_identities', 'content_chunks', 'links', 'tags', 'timeline_entries', 'page_versions', 'pages']) {
    await (engine as unknown as { db: { exec(q: string): Promise<unknown> } }).db.exec(`DELETE FROM ${t}`);
  }
  await engine.unsetConfig(ENTITY_IDENTITY_UNION_CONFIG_KEY);
  await engine.executeRaw(
    `INSERT INTO sources (id, name, config) VALUES ('team-brain', 'team-brain', '{}'::jsonb)
     ON CONFLICT (id) DO NOTHING`,
  );
});

async function seedTwoSourceAlice() {
  await engine.putPage('people/alice', {
    type: 'person', title: 'Alice', compiled_truth: 'wiki alice', timeline: '',
  }, { sourceId: 'default' });
  await engine.putPage('people/alice-chen', {
    type: 'person', title: 'Alice Chen', compiled_truth: 'team alice', timeline: '',
  }, { sourceId: 'team-brain' });
}

describe('entity_identities migration (v137)', () => {
  test('table exists with the documented shape', async () => {
    const rows = await engine.executeRaw<{ column_name: string }>(
      `SELECT column_name FROM information_schema.columns WHERE table_name = 'entity_identities'`,
    );
    const cols = new Set(rows.map(r => r.column_name));
    for (const c of ['entity_id', 'source_id', 'page_id', 'confidence', 'established_by', 'established_at', 'canonical']) {
      expect(cols.has(c)).toBe(true);
    }
  });
});

describe('identity helpers — (source_id, slug) is the key', () => {
  beforeEach(seedTwoSourceAlice);

  test('link + list round-trip across two sources', async () => {
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice', sourceId: 'default' });
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice-chen', sourceId: 'team-brain', canonical: true });

    const members = await listEntityIdentities(engine, { entityId: 'alice-chen' });
    expect(members).toHaveLength(2);
    // Canonical sorts first.
    expect(members[0]!.slug).toBe('people/alice-chen');
    expect(members[0]!.canonical).toBe(true);
    expect(members[0]!.source_id).toBe('team-brain');
    expect(members[1]!.slug).toBe('people/alice');
    expect(members[1]!.established_by).toBe('manual');
    expect(members[1]!.confidence).toBe(1);
  });

  test('linking a missing page throws (identity key is (source_id, slug))', async () => {
    await expect(
      linkEntityIdentity(engine, { entityId: 'ghost', slug: 'people/alice', sourceId: 'team-brain' }),
    ).rejects.toThrow(/page not found/);
  });

  test('re-linking MOVES the page to the new identity', async () => {
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice', sourceId: 'default' });
    await linkEntityIdentity(engine, { entityId: 'someone-else', slug: 'people/alice', sourceId: 'default' });

    expect(await listEntityIdentities(engine, { entityId: 'alice-chen' })).toHaveLength(0);
    const moved = await listEntityIdentities(engine, { entityId: 'someone-else' });
    expect(moved).toHaveLength(1);
    expect(moved[0]!.slug).toBe('people/alice');
  });

  test('B-19: re-linking the canonical member without `canonical` keeps it canonical', async () => {
    await seedTwoSourceAlice();
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice', sourceId: 'default', canonical: true });
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice', sourceId: 'default', confidence: 0.6 });
    const [me] = (await listEntityIdentities(engine, { entityId: 'alice-chen' })).filter(m => m.slug === 'people/alice');
    expect(me).toMatchObject({ canonical: true, confidence: 0.6 });
    // An explicit canonical:false still demotes.
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice', sourceId: 'default', canonical: false });
    expect((await listEntityIdentities(engine, { entityId: 'alice-chen' })).some(m => m.canonical)).toBe(false);
  });

  test('B-19: a failed canonical link leaves the previous canonical in place', async () => {
    await seedTwoSourceAlice();
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice', sourceId: 'default', canonical: true });
    await engine.executeRaw(`CREATE OR REPLACE FUNCTION test_reject_identity() RETURNS trigger LANGUAGE plpgsql AS $fn$
      BEGIN RAISE EXCEPTION 'identity insert rejected'; END $fn$`);
    await engine.executeRaw('CREATE TRIGGER test_reject_identity BEFORE INSERT ON entity_identities FOR EACH ROW EXECUTE FUNCTION test_reject_identity()');
    try {
      await expect(linkEntityIdentity(engine, {
        entityId: 'alice-chen', slug: 'people/alice-chen', sourceId: 'team-brain', canonical: true,
      })).rejects.toThrow('identity insert rejected');
    } finally {
      await engine.executeRaw('DROP TRIGGER IF EXISTS test_reject_identity ON entity_identities');
    }
    const members = await listEntityIdentities(engine, { entityId: 'alice-chen' });
    expect(members.filter(m => m.canonical).map(m => m.slug)).toEqual(['people/alice']);
  });

  test('a new canonical demotes the previous one (at most one per group)', async () => {
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice', sourceId: 'default', canonical: true });
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice-chen', sourceId: 'team-brain', canonical: true });

    const members = await listEntityIdentities(engine, { entityId: 'alice-chen' });
    expect(members.filter(m => m.canonical)).toHaveLength(1);
    expect(members.find(m => m.canonical)!.slug).toBe('people/alice-chen');
  });

  test('unlink removes exactly the (source_id, slug) member', async () => {
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice', sourceId: 'default' });
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice-chen', sourceId: 'team-brain' });

    expect(await unlinkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice', sourceId: 'default' })).toBe(true);
    expect(await unlinkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice', sourceId: 'default' })).toBe(false);
    const members = await listEntityIdentities(engine, { entityId: 'alice-chen' });
    expect(members).toHaveLength(1);
    expect(members[0]!.source_id).toBe('team-brain');
  });

  test('list by member slug finds the whole group', async () => {
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice', sourceId: 'default' });
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice-chen', sourceId: 'team-brain' });

    const members = await listEntityIdentities(engine, { slug: 'people/alice' });
    expect(members).toHaveLength(2);
  });

  test('allowedSources restricts member visibility', async () => {
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice', sourceId: 'default' });
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice-chen', sourceId: 'team-brain' });

    const members = await listEntityIdentities(engine, { entityId: 'alice-chen', allowedSources: ['default'] });
    expect(members).toHaveLength(1);
    expect(members[0]!.source_id).toBe('default');
  });

  test('validateEntityId rejects junk handles', () => {
    expect(() => validateEntityId('has space')).toThrow(/invalid entity_id/);
    expect(() => validateEntityId('')).toThrow(/invalid entity_id/);
    expect(() => validateEntityId('UPPER')).toThrow(/invalid entity_id/);
    expect(validateEntityId('alice-chen')).toBe('alice-chen');
  });
});

describe('entity identity ops (v1 manual-only)', () => {
  beforeEach(seedTwoSourceAlice);

  test('write ops are localOnly; list is not', () => {
    expect(operationsByName.entity_identity_link!.localOnly).toBe(true);
    expect(operationsByName.entity_identity_unlink!.localOnly).toBe(true);
    expect(operationsByName.entity_identity_list!.localOnly).toBeUndefined();
    expect(operationsByName.entity_identity_link!.scope).toBe('write');
    expect(operationsByName.entity_identity_list!.scope).toBe('read');
  });

  test('link + list + unlink through the op handlers', async () => {
    await operationsByName.entity_identity_link!.handler(localCtx(), {
      entity_id: 'alice-chen', slug: 'people/alice', source_id: 'default',
    });
    await operationsByName.entity_identity_link!.handler(localCtx(), {
      entity_id: 'alice-chen', slug: 'people/alice-chen', source_id: 'team-brain', canonical: true,
    });

    const listed = await operationsByName.entity_identity_list!.handler(localCtx(), {
      entity_id: 'alice-chen',
    }) as { identities: Array<{ entity_id: string; canonical: { slug: string } | null; members: unknown[] }> };
    expect(listed.identities).toHaveLength(1);
    expect(listed.identities[0]!.members).toHaveLength(2);
    expect(listed.identities[0]!.canonical?.slug).toBe('people/alice-chen');

    const un = await operationsByName.entity_identity_unlink!.handler(localCtx(), {
      entity_id: 'alice-chen', slug: 'people/alice', source_id: 'default',
    }) as { unlinked: boolean };
    expect(un.unlinked).toBe(true);
  });

  test('remote federated caller only sees granted sources in list', async () => {
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice', sourceId: 'default' });
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice-chen', sourceId: 'team-brain' });

    const listed = await operationsByName.entity_identity_list!.handler(
      remoteCtx({ auth: { allowedSources: ['default'] } as never }),
      { entity_id: 'alice-chen' },
    ) as { identities: Array<{ members: Array<{ source_id: string }> }> };
    expect(listed.identities).toHaveLength(1);
    expect(listed.identities[0]!.members).toHaveLength(1);
    expect(listed.identities[0]!.members[0]!.source_id).toBe('default');
  });
});

describe('flag-gated retrieval union (#4224 v1: link read ops)', () => {
  beforeEach(async () => {
    await seedTwoSourceAlice();
    // Give each alice an outgoing edge in her own source.
    await engine.putPage('companies/acme', {
      type: 'company', title: 'Acme', compiled_truth: 'acme', timeline: '',
    }, { sourceId: 'default' });
    await engine.putPage('companies/widget-co', {
      type: 'company', title: 'Widget Co', compiled_truth: 'widget', timeline: '',
    }, { sourceId: 'team-brain' });
    await engine.addLinksBatch([
      { from_slug: 'people/alice', to_slug: 'companies/acme', link_source: 'manual', from_source_id: 'default', to_source_id: 'default' },
      { from_slug: 'people/alice-chen', to_slug: 'companies/widget-co', link_source: 'manual', from_source_id: 'team-brain', to_source_id: 'team-brain' },
    ]);
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice', sourceId: 'default' });
    await linkEntityIdentity(engine, { entityId: 'alice-chen', slug: 'people/alice-chen', sourceId: 'team-brain' });
  });

  test('flag defaults OFF — get_links returns only the page\'s own edges', async () => {
    expect(await isIdentityUnionEnabled(engine)).toBe(false);
    const links = await operationsByName.get_links!.handler(localCtx(), { slug: 'people/alice' }) as Array<{ to_slug: string }>;
    expect(links.some(l => l.to_slug === 'companies/acme')).toBe(true);
    expect(links.some(l => l.to_slug === 'companies/widget-co')).toBe(false);
  });

  test('flag ON — get_links unions co-member edges (dedup\'d)', async () => {
    await engine.setConfig(ENTITY_IDENTITY_UNION_CONFIG_KEY, 'true');
    expect(await isIdentityUnionEnabled(engine)).toBe(true);
    const links = await operationsByName.get_links!.handler(localCtx(), { slug: 'people/alice' }) as Array<{ to_slug: string }>;
    expect(links.some(l => l.to_slug === 'companies/acme')).toBe(true);
    expect(links.some(l => l.to_slug === 'companies/widget-co')).toBe(true);
  });

  test('union never widens a federated caller\'s grant', async () => {
    await engine.setConfig(ENTITY_IDENTITY_UNION_CONFIG_KEY, 'true');
    const links = await operationsByName.get_links!.handler(
      remoteCtx({ auth: { allowedSources: ['default'] } as never }),
      { slug: 'people/alice' },
    ) as Array<{ to_slug: string }>;
    expect(links.some(l => l.to_slug === 'companies/acme')).toBe(true);
    expect(links.some(l => l.to_slug === 'companies/widget-co')).toBe(false);
  });

  test('unionLinksAcrossIdentity is a pure pass-through for non-members', async () => {
    await engine.setConfig(ENTITY_IDENTITY_UNION_CONFIG_KEY, 'true');
    const base = await engine.getLinks('companies/acme', { sourceId: 'default' });
    const out = await unionLinksAcrossIdentity(engine, 'companies/acme', base, 'out');
    expect(out).toEqual(base);
  });

  test('get_backlinks unions incoming edges when flag ON', async () => {
    await engine.setConfig(ENTITY_IDENTITY_UNION_CONFIG_KEY, 'true');
    // Backlinks of acme: from people/alice. Link widget-co's identity? Instead:
    // union on the entity pages themselves — backlinks TO alice from a note.
    await engine.putPage('notes/n1', { type: 'note', title: 'N1', compiled_truth: 'n', timeline: '' }, { sourceId: 'default' });
    await engine.putPage('notes/n2', { type: 'note', title: 'N2', compiled_truth: 'n', timeline: '' }, { sourceId: 'team-brain' });
    await engine.addLinksBatch([
      { from_slug: 'notes/n1', to_slug: 'people/alice', link_source: 'manual', from_source_id: 'default', to_source_id: 'default' },
      { from_slug: 'notes/n2', to_slug: 'people/alice-chen', link_source: 'manual', from_source_id: 'team-brain', to_source_id: 'team-brain' },
    ]);
    const backs = await operationsByName.get_backlinks!.handler(localCtx(), { slug: 'people/alice' }) as Array<{ from_slug: string }>;
    expect(backs.some(l => l.from_slug === 'notes/n1')).toBe(true);
    expect(backs.some(l => l.from_slug === 'notes/n2')).toBe(true);
  });
});

describe('#4224 review — the identity key is (source_id, slug) in the union too', () => {
  // SAME slug in two sources: `people/alice` exists in BOTH default and
  // team-brain, each with its own outgoing edge.
  beforeEach(async () => {
    await engine.setConfig(ENTITY_IDENTITY_UNION_CONFIG_KEY, 'true');
    await engine.putPage('people/alice', {
      type: 'person', title: 'Alice (wiki)', compiled_truth: 'wiki alice', timeline: '',
    }, { sourceId: 'default' });
    await engine.putPage('people/alice', {
      type: 'person', title: 'Alice (team)', compiled_truth: 'team alice', timeline: '',
    }, { sourceId: 'team-brain' });
    await engine.putPage('companies/acme', {
      type: 'company', title: 'Acme', compiled_truth: 'acme', timeline: '',
    }, { sourceId: 'default' });
    await engine.putPage('companies/widget-co', {
      type: 'company', title: 'Widget Co', compiled_truth: 'widget', timeline: '',
    }, { sourceId: 'team-brain' });
    await engine.addLinksBatch([
      { from_slug: 'people/alice', to_slug: 'companies/acme', link_source: 'manual', from_source_id: 'default', to_source_id: 'default' },
      { from_slug: 'people/alice', to_slug: 'companies/widget-co', link_source: 'manual', from_source_id: 'team-brain', to_source_id: 'team-brain' },
    ]);
  });

  test('same-slug co-member in ANOTHER source IS unioned (only the base pair is excluded)', async () => {
    await linkEntityIdentity(engine, { entityId: 'alice', slug: 'people/alice', sourceId: 'default' });
    await linkEntityIdentity(engine, { entityId: 'alice', slug: 'people/alice', sourceId: 'team-brain' });

    // Helper-level: base = (default, people/alice); the team-brain member
    // shares the slug but is a REAL co-member — pre-fix `m.slug !== slug`
    // dropped it and its edges never merged.
    const base = await engine.getLinks('people/alice', { sourceId: 'default' });
    const out = await unionLinksAcrossIdentity(engine, 'people/alice', base, 'out', {
      sourceId: 'default', allowedSources: ['default', 'team-brain'],
    });
    expect(out.some(l => l.to_slug === 'companies/acme')).toBe(true);
    expect(out.some(l => l.to_slug === 'companies/widget-co')).toBe(true);
    const scalar = await unionLinksAcrossIdentity(engine, 'people/alice', base, 'out', {
      sourceId: 'default', allowedSources: [],
    });
    expect(scalar).toEqual(base);

    // Op-level: a scalar ctx scope is also the member visibility floor.
    const links = await operationsByName.get_links!.handler(
      localCtx({ sourceId: 'default' }), { slug: 'people/alice' },
    ) as Array<{ to_slug: string }>;
    expect(links.some(l => l.to_slug === 'companies/widget-co')).toBe(false);
  });

  test('NON-member base page with a same-slug member elsewhere is NOT unioned', async () => {
    // Only the TEAM alice is a member, grouped with a third page that has
    // its own edge. The default alice is NOT a member.
    await engine.putPage('people/alicia', {
      type: 'person', title: 'Alicia', compiled_truth: 'alicia', timeline: '',
    }, { sourceId: 'team-brain' });
    await engine.addLinksBatch([
      { from_slug: 'people/alicia', to_slug: 'companies/widget-co', link_source: 'manual', from_source_id: 'team-brain', to_source_id: 'team-brain' },
    ]);
    await linkEntityIdentity(engine, { entityId: 'alice', slug: 'people/alice', sourceId: 'team-brain' });
    await linkEntityIdentity(engine, { entityId: 'alice', slug: 'people/alicia', sourceId: 'team-brain' });

    // Pre-fix the unscoped slug sub-select matched the TEAM alice's group and
    // unioned foreign edges into a read of the (default) NON-member page.
    const base = await engine.getLinks('people/alice', { sourceId: 'default' });
    const out = await unionLinksAcrossIdentity(engine, 'people/alice', base, 'out', { sourceId: 'default' });
    expect(out).toEqual(base);

    const links = await operationsByName.get_links!.handler(
      localCtx({ sourceId: 'default' }), { slug: 'people/alice' },
    ) as Array<{ to_slug: string }>;
    expect(links.some(l => l.to_slug === 'companies/acme')).toBe(true);
    expect(links.some(l => l.to_slug === 'companies/widget-co')).toBe(false);
  });

  test('listEntityIdentities slugSourceId pins group resolution to the (slug, source) pair', async () => {
    await linkEntityIdentity(engine, { entityId: 'alice', slug: 'people/alice', sourceId: 'team-brain' });
    // Unscoped slug lookup still finds the group (trusted cross-source view)…
    expect(await listEntityIdentities(engine, { slug: 'people/alice' })).toHaveLength(1);
    // …but the source-scoped lookup only matches the member pair.
    expect(await listEntityIdentities(engine, { slug: 'people/alice', slugSourceId: 'default' })).toHaveLength(0);
    expect(await listEntityIdentities(engine, { slug: 'people/alice', slugSourceId: 'team-brain' })).toHaveLength(1);
  });

  test('without slugSourceId, the seed sub-select is confined to allowedSources', async () => {
    await linkEntityIdentity(engine, { entityId: 'alice', slug: 'people/alice', sourceId: 'team-brain' });
    // A grant that cannot see team-brain must not discover the group through
    // the team-brain seed page.
    expect(await listEntityIdentities(engine, {
      slug: 'people/alice', allowedSources: ['default'],
    })).toHaveLength(0);
    expect(await listEntityIdentities(engine, {
      slug: 'people/alice', allowedSources: ['team-brain'],
    })).toHaveLength(1);
  });
});