open-brainy/tests/unit/db/whereMatcher.test.ts

/**
 * @module tests/unit/db/whereMatcher
 * @description Unit tests for the in-memory `find()` filter evaluator behind
 * historical and speculative `Db` reads (`src/db/whereMatcher.ts`). The
 * evaluator must mirror the metadata index's operator semantics exactly — an
 * entity matches in-memory if and only if it would have matched through the
 * index — and must throw `UnsupportedWhereOperatorError` for anything it
 * does not recognize (never guess on a historical read).
 */

import { describe, it, expect } from 'vitest'
import {
  entityMatchesFind,
  resolveEntityField,
  whereMatches,
  UnsupportedWhereOperatorError
} from '../../../src/db/whereMatcher.js'
import type { Entity } from '../../../src/types/brainy.types.js'
import { NounType } from '../../../src/types/graphTypes.js'

/** Build a minimal entity for matcher tests. */
function entity(overrides: Partial<Entity> = {}): Entity {
  return {
    id: 'e-1',
    vector: [],
    type: NounType.Document,
    createdAt: 1000,
    updatedAt: 2000,
    metadata: {},
    ...overrides
  }
}

describe('db/whereMatcher — resolveEntityField', () => {
  it('system.<field> resolves the entity scalar; bare/metadata. reads the metadata bag only (sealed 2026-08-03)', () => {
    const e = entity({
      subtype: 'invoice',
      service: 'billing',
      confidence: 0.9,
      weight: 0.5,
      _rev: 3,
      data: 'payload'
    })

    // system.<field> is the ONLY spelling that reaches an entity scalar.
    expect(resolveEntityField(e, 'system.id')).toBe('e-1')
    expect(resolveEntityField(e, 'system.type')).toBe(NounType.Document)
    expect(resolveEntityField(e, 'system.subtype')).toBe('invoice')
    expect(resolveEntityField(e, 'system.service')).toBe('billing')
    expect(resolveEntityField(e, 'system.confidence')).toBe(0.9)
    expect(resolveEntityField(e, 'system.weight')).toBe(0.5)
    expect(resolveEntityField(e, 'system.createdAt')).toBe(1000)
    expect(resolveEntityField(e, 'system.updatedAt')).toBe(2000)

    // Plumbing (_rev, data) is invisible even via system. — not in the
    // ten-scalar map, so this internal resolver reads it as absent (the typed
    // refusal for these lives one layer up, at the query-surface parser).
    expect(resolveEntityField(e, 'system._rev')).toBeUndefined()
    expect(resolveEntityField(e, 'system.data')).toBeUndefined()

    // Bare names are ALWAYS the user's metadata field — even when they share
    // a spelling with an engine scalar, or with the now-dead 'noun' alias.
    // This entity's metadata bag is empty, so every bare name below reads
    // absent rather than silently falling back to the entity scalar.
    expect(resolveEntityField(e, 'id')).toBeUndefined()
    expect(resolveEntityField(e, 'type')).toBeUndefined()
    expect(resolveEntityField(e, 'noun')).toBeUndefined() // legacy alias is dead
    expect(resolveEntityField(e, 'subtype')).toBeUndefined()
    expect(resolveEntityField(e, 'createdAt')).toBeUndefined()
  })

  it('resolves custom fields from the metadata bag', () => {
    const e = entity({ metadata: { status: 'open', priority: 2 } })
    expect(resolveEntityField(e, 'status')).toBe('open')
    expect(resolveEntityField(e, 'priority')).toBe(2)
    expect(resolveEntityField(e, 'absent')).toBeUndefined()
  })

  it('resolves dotted paths against the entity and the metadata bag', () => {
    const e = entity({ metadata: { address: { city: 'Lyon' }, priority: 7 } })
    expect(resolveEntityField(e, 'metadata.priority')).toBe(7)
    expect(resolveEntityField(e, 'address.city')).toBe('Lyon')
    expect(resolveEntityField(e, 'address.zip')).toBeUndefined()
  })
})

describe('db/whereMatcher — operators', () => {
  const e = entity({
    subtype: 'invoice',
    metadata: { amount: 250, status: 'open', tags: ['urgent', 'q3'], city: 'Lyon' }
  })

  it('shorthand equality', () => {
    expect(whereMatches(e, { status: 'open' })).toBe(true)
    expect(whereMatches(e, { status: 'closed' })).toBe(false)
  })

  it('eq / equals aliases', () => {
    expect(whereMatches(e, { amount: { eq: 250 } })).toBe(true)
    expect(whereMatches(e, { amount: { equals: 250 } })).toBe(true)
    expect(whereMatches(e, { amount: { eq: 99 } })).toBe(false)
  })

  it('array-membership equality (index posting semantics)', () => {
    expect(whereMatches(e, { tags: 'urgent' })).toBe(true)
    expect(whereMatches(e, { tags: { contains: 'q3' } })).toBe(true)
    expect(whereMatches(e, { tags: 'missing-tag' })).toBe(false)
  })

  it('ne / notEquals aliases', () => {
    expect(whereMatches(e, { status: { ne: 'closed' } })).toBe(true)
    expect(whereMatches(e, { status: { notEquals: 'open' } })).toBe(false)
  })

  it('in / oneOf set membership', () => {
    expect(whereMatches(e, { status: { in: ['open', 'closed'] } })).toBe(true)
    expect(whereMatches(e, { status: { oneOf: ['archived'] } })).toBe(false)
  })

  it('numeric range operators with aliases', () => {
    expect(whereMatches(e, { amount: { gt: 200 } })).toBe(true)
    expect(whereMatches(e, { amount: { greaterThan: 250 } })).toBe(false)
    expect(whereMatches(e, { amount: { gte: 250 } })).toBe(true)
    expect(whereMatches(e, { amount: { greaterThanOrEqual: 251 } })).toBe(false)
    expect(whereMatches(e, { amount: { lt: 251 } })).toBe(true)
    expect(whereMatches(e, { amount: { lessThan: 250 } })).toBe(false)
    expect(whereMatches(e, { amount: { lte: 250 } })).toBe(true)
    expect(whereMatches(e, { amount: { lessThanOrEqual: 249 } })).toBe(false)
  })

  it('string range comparison is lexicographic', () => {
    expect(whereMatches(e, { city: { gt: 'Aix' } })).toBe(true)
    expect(whereMatches(e, { city: { lt: 'Aix' } })).toBe(false)
  })

  it('mixed-type range comparison never matches', () => {
    expect(whereMatches(e, { city: { gt: 5 } })).toBe(false)
    expect(whereMatches(e, { amount: { lt: 'zzz' } })).toBe(false)
  })

  it('between', () => {
    expect(whereMatches(e, { amount: { between: [200, 300] } })).toBe(true)
    expect(whereMatches(e, { amount: { between: [251, 300] } })).toBe(false)
    expect(whereMatches(e, { amount: { between: [200] } })).toBe(false) // malformed operand
  })

  it('exists / missing', () => {
    expect(whereMatches(e, { status: { exists: true } })).toBe(true)
    expect(whereMatches(e, { nope: { exists: true } })).toBe(false)
    expect(whereMatches(e, { nope: { exists: false } })).toBe(true)
    expect(whereMatches(e, { nope: { missing: true } })).toBe(true)
    expect(whereMatches(e, { status: { missing: true } })).toBe(false)
    expect(whereMatches(e, { status: { missing: false } })).toBe(true)
  })

  it('multiple operators on one field AND together', () => {
    expect(whereMatches(e, { amount: { gte: 200, lte: 300 } })).toBe(true)
    expect(whereMatches(e, { amount: { gte: 200, lte: 249 } })).toBe(false)
  })

  it('allOf / anyOf / not logical composition', () => {
    expect(whereMatches(e, { allOf: [{ status: 'open' }, { amount: { gt: 100 } }] })).toBe(true)
    expect(whereMatches(e, { allOf: [{ status: 'open' }, { amount: { gt: 999 } }] })).toBe(false)
    expect(whereMatches(e, { anyOf: [{ status: 'closed' }, { amount: 250 }] })).toBe(true)
    expect(whereMatches(e, { anyOf: [{ status: 'closed' }, { amount: 9 }] })).toBe(false)
    expect(whereMatches(e, { not: { status: 'closed' } })).toBe(true)
    expect(whereMatches(e, { not: { status: 'open' } })).toBe(false)
  })

  it('throws UnsupportedWhereOperatorError for unknown operators — never guesses', () => {
    expect(() => whereMatches(e, { amount: { approximately: 250 } })).toThrow(
      UnsupportedWhereOperatorError
    )
    try {
      whereMatches(e, { amount: { approximately: 250 } })
      expect.unreachable('should have thrown')
    } catch (err) {
      expect(err).toBeInstanceOf(UnsupportedWhereOperatorError)
      expect((err as UnsupportedWhereOperatorError).operator).toBe('approximately')
    }
  })
})

describe('db/whereMatcher — entityMatchesFind', () => {
  const e = entity({
    subtype: 'invoice',
    service: 'billing',
    metadata: { amount: 250 }
  })

  it('filters by type (single + array)', () => {
    expect(entityMatchesFind(e, { type: NounType.Document })).toBe(true)
    expect(entityMatchesFind(e, { type: [NounType.Person, NounType.Document] })).toBe(true)
    expect(entityMatchesFind(e, { type: NounType.Person })).toBe(false)
  })

  it('filters by subtype (single + array; entities without subtype excluded)', () => {
    expect(entityMatchesFind(e, { subtype: 'invoice' })).toBe(true)
    expect(entityMatchesFind(e, { subtype: ['invoice', 'receipt'] })).toBe(true)
    expect(entityMatchesFind(e, { subtype: 'receipt' })).toBe(false)
    expect(entityMatchesFind(entity(), { subtype: 'invoice' })).toBe(false)
  })

  it('filters by service', () => {
    expect(entityMatchesFind(e, { service: 'billing' })).toBe(true)
    expect(entityMatchesFind(e, { service: 'crm' })).toBe(false)
  })

  it('excludeVFS drops VFS-marked entities', () => {
    const vfsEntity = entity({ metadata: { vfsType: 'file' } })
    const markedEntity = entity({ metadata: { isVFSEntity: true } })
    expect(entityMatchesFind(vfsEntity, { excludeVFS: true })).toBe(false)
    expect(entityMatchesFind(markedEntity, { excludeVFS: true })).toBe(false)
    expect(entityMatchesFind(e, { excludeVFS: true })).toBe(true)
    expect(entityMatchesFind(vfsEntity, {})).toBe(true)
  })

  it('composes type + subtype + where', () => {
    expect(
      entityMatchesFind(e, {
        type: NounType.Document,
        subtype: 'invoice',
        where: { amount: { gte: 200 } }
      })
    ).toBe(true)
    expect(
      entityMatchesFind(e, {
        type: NounType.Document,
        subtype: 'invoice',
        where: { amount: { gte: 999 } }
      })
    ).toBe(false)
  })
})