Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
49.5 KB
Raw Blame
/**
 * Hot-memory facts: one SQL implementation for both engines (refactor wave 1,
 * W1-core C11). Statement text is PostgresEngine's master text (SQL-text
 * golden `sql-text/facts.json`); PGLite runs the same statements. Dialect
 * capabilities (docs/designs/refactor-wave-1/w1-inventory.md):
 *   - transactionAdvisoryLocks: Postgres serializes same-entity inserts with
 *     `pg_advisory_xact_lock` inside a transaction; PGLite (single connection)
 *     never locked and its plain insert never opened a transaction.
 *   - probesEmbeddingCast: Postgres matches the vector literal cast to the
 *     live `facts.embedding` column type (`::vector` | `::halfvec`); PGLite
 *     always cast `::vector` on master (its bundled pgvector assignment-casts
 *     to the halfvec column).
 * Every read was unscoped on master (EO4 inventory): reads take
 * `LegacyUnscopedRead`.
 */
import type {
  FactRow, FactKind, FactVisibility, FactInsertStatus, FactAttribution,
  NewFact, FactListOpts, RecallFactReadOpts, FactsHealth,
} from '../engine.ts';
import { MAX_SEARCH_LIMIT, clampSearchLimit } from '../engine.ts';
import { tryParseEmbedding } from '../utils.ts';
import { AUDIT_ROW_SOURCES } from '../facts/audit-sources.ts';
import { resolveSupersededByRow, isInt4RowRef, supersessionChainOf, type SupersedeTarget } from '../facts/supersede-resolve.ts';
import { escapeLikePattern } from '../cjk.ts';
import { getFtsLanguage } from '../fts-language.ts';
import type { SqlExecutor } from './executor.ts';
import type { LegacyUnscopedRead } from './brands.ts';
import { sqlFragment, trustedSql } from './fragment.ts';
import { compileRowNormalizer } from './normalize.ts';
import { deletedPageProjectionHiddenSql, projectionEligibleSql } from '../eligibility/sql.ts';
import { FACT_WITHDRAWAL_STAMP_DEFERRED_SETTING } from '../facts/insert-guard-schema.ts';
import { privateProvenanceFilterUnderPolicy } from '../search/private-visibility.ts';
import { factVisibilitySql, onOwnedMemoryPageSql } from '../access/member-facts.ts';
import { storedTrustTier } from '../trust/tier.ts';
import { ensureWellFormed } from '../text-safe.ts';
import { valueHash } from '../chronicle/ontology.ts';

export type EmbeddingCast = '::vector' | '::halfvec';

/**
 * The `facts.embedding` cast suffix. Postgres probes the column (cache state
 * lives on the engine: `PostgresEngine#resolveFactsEmbeddingCast`); PGLite
 * keeps master's constant `::vector`.
 */
export type ResolveEmbeddingCast = () => Promise<EmbeddingCast>;

async function embeddingCast(exec: SqlExecutor, probe: ResolveEmbeddingCast | undefined): Promise<EmbeddingCast> {
  if (!exec.capabilities.probesEmbeddingCast || !probe) return '::vector';
  return probe();
}

/**
 * SQL-side substring filter (before limit) — a client-side post-limit grep
 * silently misses matches outside the newest-N window on high-cardinality
 * entities. Parity with the pglite engine's `_listFacts`.
 */
/** #5575: the read-eligibility predicate for list reads that pass a policy (eligibility/sql.ts); every read hides a deleted page's facts. */
function eligibilityClause(opts: Pick<FactListOpts, 'eligibility'> | undefined) {
  return sqlFragment` AND ${trustedSql(opts?.eligibility ? projectionEligibleSql('facts', 'facts', opts.eligibility) : deletedPageProjectionHiddenSql('facts', 'facts'))}`;
}

/** GST-359 C2: a visibility list, widened only to the caller's own member-page private facts (access/member-facts.ts). */
function visibilityClause(visibility: readonly string[] | null) {
  return visibility ? sqlFragment`AND ${trustedSql(factVisibilitySql('facts', visibility))}` : sqlFragment``;
}

function privacyClause(opts: { excludePrivate?: boolean } | undefined) {
  return opts?.excludePrivate ? sqlFragment` AND ${trustedSql(privateProvenanceFilterUnderPolicy('facts'))}` : sqlFragment``;
}

function grepPattern(opts: FactListOpts | undefined): string | null {
  return (opts?.grep && opts.grep.trim()) ? '%' + escapeLikePattern(opts.grep.trim()) + '%' : null;
}

/**
 * The pre-LIMIT narrowing both recall cursor reads apply (listFactsSince and,
 * for --since-last-run paging, listFactsKeyset): entity, the page the fact sits
 * on (memory_recall's own-member-page arm), session, audit rows and --grep. Each part is opt-in, so a caller passing none (delta) gets none.
 */
function recallNarrowing(opts: RecallFactReadOpts | undefined) {
  const grep = grepPattern(opts);
  return sqlFragment`${opts?.entitySlug != null ? sqlFragment` AND entity_slug = ${opts.entitySlug}` : sqlFragment``}${
    opts?.sourceMarkdownSlug != null ? sqlFragment` AND source_markdown_slug = ${opts.sourceMarkdownSlug}` : sqlFragment``}${
    opts?.sessionId ? sqlFragment` AND source_session = ${opts.sessionId}` : sqlFragment``}${
    opts?.excludeAuditRows ? sqlFragment` AND source != ALL(${AUDIT_ROW_SOURCES}::text[])` : sqlFragment``}${
    grep ? sqlFragment` AND fact ILIKE ${grep} ESCAPE '\\'` : sqlFragment``}`;
}

export async function insertFact(
  exec: SqlExecutor,
  resolveCast: ResolveEmbeddingCast | undefined,
    input: NewFact,
    ctx: { source_id: string; supersedeId?: number },
  ): Promise<{ id: number; status: FactInsertStatus }> {
    const validFrom = input.valid_from ?? new Date();
    const validUntil = input.valid_until ?? null;
    const kind = input.kind ?? 'fact';
    const visibility = input.visibility ?? 'private';
    const notability = input.notability ?? 'medium';
    const confidence = input.confidence ?? 1.0;
    const entitySlug = input.entity_slug ?? null;
    const context = input.context ?? null;
    const sourceSession = input.source_session ?? null;
    const embedding = input.embedding ?? null;
    const embeddedAt = embedding ? new Date() : null;
    const embedLit = embedding ? toPgVectorLiteral(embedding) : null;
    // v0.41.15.0 (T6, codex #20): match cast to actual column type so
    // a halfvec(N) column doesn't pay an implicit-cast round-trip + can
    // run on pgvector versions that lack the auto vector→halfvec cast.
    const castSuffix = await embeddingCast(exec, resolveCast);
    // v0.35.4 (D-CDX-5) — typed-claim columns. All four nullable.
    const claimMetric = input.claim_metric ?? null;
    const claimValue  = input.claim_value  ?? null;
    const claimUnit   = input.claim_unit   ?? null;
    const claimPeriod = input.claim_period ?? null;

    if (ctx.supersedeId !== undefined) {
      // Per-entity advisory lock + atomic insert + supersede in one txn.
      const supersedeId = ctx.supersedeId;
      const newId = await exec.transaction(async (tx) => {
        if (entitySlug && tx.capabilities.transactionAdvisoryLocks) {
          // Lock-census (PR6 D5): COMPLIANT — key is already source-scoped (source_id || ':' || entity_slug).
          (await tx.run(sqlFragment`SELECT pg_advisory_xact_lock(hashtextextended(${ctx.source_id} || ':' || ${entitySlug}, 0))`)).rows;
        }
        const ins = (await tx.run<{ id: number }>(sqlFragment`
          INSERT INTO facts (
            source_id, entity_slug, fact, kind, visibility, notability, context,
            valid_from, valid_until, source, source_session, confidence,
            embedding, embedded_at, embedding_model, embedded_text_hash,
            claim_metric, claim_value, claim_unit, claim_period, attributed_to
          ) VALUES (
            ${ctx.source_id}, ${entitySlug}, ${input.fact}, ${kind}, ${visibility}, ${notability}, ${context},
            ${validFrom}, ${validUntil}, ${input.source}, ${sourceSession}, ${confidence},
            ${embedLit === null ? null : trustedSql(vectorLiteralSql(embedLit, castSuffix))}, ${embeddedAt}, ${embedding ? input.embedding_model ?? null : null}, ${embedding && input.embedding_model ? sqlFragment`md5(${input.fact})` : null},
            ${claimMetric}, ${claimValue}, ${claimUnit}, ${claimPeriod}, ${input.attributed_to ?? null}
          ) RETURNING id
        `)).rows;
        const id = Number(ins[0].id);
        (await tx.run(sqlFragment`UPDATE facts SET expired_at = now(), superseded_by = ${id},
                   valid_until = CASE WHEN valid_from < ${validFrom}::timestamptz AND ${validFrom}::timestamptz < COALESCE(valid_until, now()) THEN ${validFrom}::timestamptz ELSE GREATEST(valid_from, LEAST(COALESCE(valid_until, now()), now())) END
                 WHERE id = ${supersedeId} AND expired_at IS NULL`)).rows;
        return id;
      });
      return { id: newId, status: 'superseded' };
    }

    // Plain insert path with optional advisory lock for the dedup window
    // (Postgres only: PGLite inserts directly, as it did on master).
    const insertPlain = async (tx: SqlExecutor): Promise<number> => {
      if (entitySlug && tx.capabilities.transactionAdvisoryLocks) {
        // Lock-census (PR6 D5): COMPLIANT — key is already source-scoped (source_id || ':' || entity_slug).
        (await tx.run(sqlFragment`SELECT pg_advisory_xact_lock(hashtextextended(${ctx.source_id} || ':' || ${entitySlug}, 0))`)).rows;
      }
      const ins = (await tx.run<{ id: number }>(sqlFragment`
        INSERT INTO facts (
          source_id, entity_slug, fact, kind, visibility, notability, context,
          valid_from, valid_until, source, source_session, confidence,
          embedding, embedded_at, embedding_model, embedded_text_hash,
          claim_metric, claim_value, claim_unit, claim_period, attributed_to
        ) VALUES (
          ${ctx.source_id}, ${entitySlug}, ${input.fact}, ${kind}, ${visibility}, ${notability}, ${context},
          ${validFrom}, ${validUntil}, ${input.source}, ${sourceSession}, ${confidence},
          ${embedLit === null ? null : trustedSql(vectorLiteralSql(embedLit, castSuffix))}, ${embeddedAt}, ${embedding ? input.embedding_model ?? null : null}, ${embedding && input.embedding_model ? sqlFragment`md5(${input.fact})` : null},
          ${claimMetric}, ${claimValue}, ${claimUnit}, ${claimPeriod}, ${input.attributed_to ?? null}
        ) RETURNING id
      `)).rows;
      return Number(ins[0].id);
    };
    const id = exec.capabilities.transactionAdvisoryLocks
      ? await exec.transaction(insertPlain)
      : await insertPlain(exec);
    return { id, status: 'inserted' };
  }

/** With `successorFrom` (a supersession) the row's validity ends by supersede-interval.ts's rule; a plain expiry leaves valid_until as stored. */
export async function expireFact(exec: SqlExecutor, id: number, opts?: { supersededBy?: number; at?: Date; successorFrom?: Date }): Promise<boolean> {
    const at = opts?.at ?? new Date();
    const supersededBy = opts?.supersededBy ?? null;
    const successor = opts?.successorFrom ?? null;
    const result = await exec.run(sqlFragment`
      UPDATE facts SET expired_at = ${at}, superseded_by = COALESCE(${supersededBy}, superseded_by),
        valid_until = CASE WHEN ${successor}::timestamptz IS NULL THEN valid_until
          WHEN valid_from < ${successor}::timestamptz AND ${successor}::timestamptz < COALESCE(valid_until, now()) THEN ${successor}::timestamptz
          ELSE GREATEST(valid_from, LEAST(COALESCE(valid_until, now()), now())) END
      WHERE id = ${id} AND expired_at IS NULL
    `);
    return result.affectedRows > 0;
  }

/** Rows per multi-row fact INSERT: facts carries per-row triggers, and each statement runs under the publication's 5 s statement_timeout. */
const FACT_INSERT_CHUNK = 500;

const factRowKey = (slug: string, rowNum: number | null) => `${slug}\u0000${rowNum}`;

/** A string bound inside a JSONB document: a lone surrogate becomes U+FFFD, as UTF-8 parameter encoding did for the per-row INSERT. */
const wellFormed = <T extends string | null | undefined>(s: T): T => (typeof s === 'string' ? ensureWellFormed(s) as T : s);

/**
 * #6574: inserts fact rows in chunks of FACT_INSERT_CHUNK with one statement
 * each. Returns each input's new id, aligned to `rows`, or null when the v51
 * ON CONFLICT DO NOTHING skipped it; within a chunk the first input for a
 * (slug, row_num) wins, as the per-row loop's order did. The inserts run
 * under FACT_WITHDRAWAL_STAMP_DEFERRED_SETTING, so a withdrawn row is stamped
 * once per statement by facts_guard_inserted instead of by a per-row trigger
 * call (#7105); the RETURNING below reads no stamped column.
 */
async function insertFactRows(tx: SqlExecutor, castSuffix: EmbeddingCast,
  rows: ReadonlyArray<NewFact & { row_num: number; source_markdown_slug: string }>, sourceId: string): Promise<Array<number | null>> {
  const rowIds: Array<number | null> = [];
  (await tx.run(sqlFragment`SELECT set_config(${FACT_WITHDRAWAL_STAMP_DEFERRED_SETTING}, 'on', true)`)).rows;
  for (let at = 0; at < rows.length; at += FACT_INSERT_CHUNK) {
    const chunk = rows.slice(at, at + FACT_INSERT_CHUNK).map((input, ord) => {
      const embedding = input.embedding ?? null;
      return {
        entity_slug: wellFormed(input.entity_slug ?? null), fact: wellFormed(input.fact), kind: input.kind ?? 'fact',
        visibility: input.visibility ?? 'private', notability: input.notability ?? 'medium', context: wellFormed(input.context ?? null),
        valid_from: (input.valid_from ?? new Date()).toISOString(), valid_until: input.valid_until?.toISOString() ?? null,
        expired_at: input.expired_at?.toISOString() ?? null, source: wellFormed(input.source), source_session: wellFormed(input.source_session ?? null),
        confidence: input.confidence ?? 1.0, embedding: embedding ? toPgVectorLiteral(embedding) : null,
        embedded_at: embedding ? new Date().toISOString() : null, embedding_model: embedding ? wellFormed(input.embedding_model ?? null) : null,
        hash_text: embedding && input.embedding_model ? wellFormed(input.fact) : null,
        row_num: input.row_num, source_markdown_slug: wellFormed(input.source_markdown_slug),
        claim_metric: wellFormed(input.claim_metric ?? null), claim_value: input.claim_value ?? null, claim_unit: wellFormed(input.claim_unit ?? null),
        claim_period: wellFormed(input.claim_period ?? null), event_type: wellFormed(input.event_type ?? null), attributed_to: input.attributed_to ?? null,
        ...(input.dimension && input.value != null
          ? { dimension: wellFormed(input.dimension), value: wellFormed(input.value), value_hash: valueHash(input.value), dim_status: 'active' }
          : { dimension: null, value: null, value_hash: null, dim_status: null }),
        ord,
      };
    });
    const inserted = (await tx.run<{ id: number; source_markdown_slug: string; row_num: number | null }>(sqlFragment`
      INSERT INTO facts (
        source_id, entity_slug, fact, kind, visibility, notability, context,
        valid_from, valid_until, expired_at, source, source_session, confidence,
        embedding, embedded_at, embedding_model, embedded_text_hash,
        row_num, source_markdown_slug,
        claim_metric, claim_value, claim_unit, claim_period,
        event_type, attributed_to,
        dimension, value, value_hash, dim_status
      )
      SELECT ${sourceId}, r.entity_slug, r.fact, r.kind, r.visibility, r.notability, r.context,
        r.valid_from::timestamptz, r.valid_until::timestamptz, r.expired_at::timestamptz, r.source, r.source_session, r.confidence,
        ${castSuffix === '::halfvec' ? trustedSql('r.embedding::halfvec') : trustedSql('r.embedding::vector')}, r.embedded_at::timestamptz, r.embedding_model, md5(r.hash_text),
        r.row_num, r.source_markdown_slug,
        r.claim_metric, r.claim_value, r.claim_unit, r.claim_period,
        r.event_type, r.attributed_to,
        r.dimension, r.value, r.value_hash, r.dim_status
      FROM jsonb_to_recordset(${JSON.stringify(chunk)}::text::jsonb) AS r(
        entity_slug text, fact text, kind text, visibility text, notability text, context text,
        valid_from text, valid_until text, expired_at text, source text, source_session text, confidence real,
        embedding text, embedded_at text, embedding_model text, hash_text text,
        row_num integer, source_markdown_slug text,
        claim_metric text, claim_value double precision, claim_unit text, claim_period text,
        event_type text, attributed_to text,
        dimension text, value text, value_hash text, dim_status text, ord integer)
      ORDER BY r.ord
      ON CONFLICT (source_id, source_markdown_slug, row_num)
      WHERE row_num IS NOT NULL
      DO NOTHING
      RETURNING id, source_markdown_slug, row_num
    `)).rows;
    const byKey = new Map<string, number[]>();
    for (const row of inserted) {
      const key = factRowKey(row.source_markdown_slug, row.row_num == null ? null : Number(row.row_num));
      byKey.set(key, [...(byKey.get(key) ?? []), Number(row.id)]);
    }
    for (const input of chunk) rowIds.push(byKey.get(factRowKey(input.source_markdown_slug, input.row_num ?? null))?.shift() ?? null);
  }
  (await tx.run(sqlFragment`SELECT set_config(${FACT_WITHDRAWAL_STAMP_DEFERRED_SETTING}, '', true)`)).rows;
  return rowIds;
}

export async function insertFacts(
  exec: SqlExecutor,
  resolveCast: ResolveEmbeddingCast | undefined,
    rows: Array<NewFact & { row_num: number; source_markdown_slug: string; superseded_by_row?: number }>,
    ctx: { source_id: string },
    opts?: { deleteForPageFirst?: { slug: string; excludeSourcePrefixes?: string[]; preserveExpiredLegacy?: boolean } },
  ): Promise<{ inserted: number; ids: number[]; warnings: string[]; deleted: number }> {
    if (rows.length === 0) return { inserted: 0, ids: [], warnings: [], deleted: 0 };

    // v0.41.15.0 (T6, codex #20): resolve the embedding-cast suffix
    // ONCE per process so the cast matches the actual column type
    // (halfvec vs vector). The probe is cached after first call.
    const castSuffix = await embeddingCast(exec, resolveCast);
    const warnings: string[] = [];
    // v0.46 (#3014): captured inside the transaction below when
    // deleteForPageFirst runs; stays 0 for the standalone insert path.
    let deleted = 0;
    // Single transaction so the v51 partial UNIQUE index can roll back
    // the whole batch on constraint violation.
    // v0.46 (#3014): the fence path carries struck rows — `expired_at` is
    // stamped inline here, and `superseded by #N` references are resolved
    // to `facts.superseded_by` in a second pass below (same transaction).
    const ids = await exec.transaction(async (tx) => {
      // v0.46 (#3014) — atomic reconcile: wipe the page's fence-owned rows
      // as the FIRST statement of this transaction so a failing insert
      // below rolls the delete back too. Inlined (not a deleteFactsForPage
      // call) so it shares this transaction — deleteFactsForPage runs on
      // the pool (the root executor), a separate self-committing transaction,
      // which is exactly the split this fix removes. Scoping mirrors it
      // exactly (#1928 excludeSourcePrefixes + #2646 preserveExpiredLegacy).
      const del = opts?.deleteForPageFirst;
      if (del) {
        const expiredLegacyFilter = del.preserveExpiredLegacy
          ? sqlFragment`AND NOT (row_num IS NULL AND expired_at IS NOT NULL)`
          : sqlFragment``;
        const prefixes = del.excludeSourcePrefixes;
        if (prefixes && prefixes.length > 0) {
          const patterns = prefixes.map(p => `${p}%`);
          const r = await tx.run(sqlFragment`
            DELETE FROM facts
            WHERE source_id = ${ctx.source_id}
              AND source_markdown_slug = ${del.slug}
              AND NOT (COALESCE(source, '') LIKE ANY(${patterns}))
              ${expiredLegacyFilter}
          `);
          deleted = r.affectedRows;
        } else {
          const r = await tx.run(sqlFragment`
            DELETE FROM facts
            WHERE source_id = ${ctx.source_id} AND source_markdown_slug = ${del.slug} ${expiredLegacyFilter}
          `);
          deleted = r.affectedRows;
        }
      }
      // #6574: one INSERT per chunk of rows, not one per row. A publication
      // over a high-latency link paid a round trip per fact row; a 1,000-row
      // fence took a minute before anything else ran.
      const rowIds = await insertFactRows(tx, castSuffix, rows, ctx.source_id);
      const out = rowIds.filter((id): id is number => id !== null);

      // v0.46 (#3014) — second pass: resolve `superseded by #N` page-local
      // references to fact ids. Same transaction so a target row inserted
      // above is visible. Keyed on (source_id, source_markdown_slug,
      // row_num) — the v51 unique index — so a reference also resolves
      // against a target that already existed before this batch. A target
      // whose `expired_at` is set resolves only when it is itself superseded
      // (an A -> B -> C chain), declared in this batch or already linked in
      // the DB. Every target is read in one statement and every link written
      // in one more (#6574).
      const refs = rows.flatMap((row, i) => row.superseded_by_row !== undefined && rowIds[i] !== null && isInt4RowRef(row.superseded_by_row)
        ? [{ slug: row.source_markdown_slug, row_num: row.superseded_by_row }] : []);
      const targets = new Map<string, { id: number; struck: boolean; next_row: number | null }>();
      if (refs.length) {
        const found = (await tx.run<{ slug: string; row_num: number; id: number; expired_at: Date | null; next_row: number | null }>(sqlFragment`
          SELECT f.source_markdown_slug AS slug, f.row_num, f.id, f.expired_at, n.row_num AS next_row FROM facts f
          JOIN (SELECT DISTINCT slug, row_num FROM jsonb_to_recordset(${JSON.stringify(refs)}::text::jsonb) AS r(slug text, row_num integer)) t
            ON f.source_markdown_slug = t.slug AND f.row_num = t.row_num
          LEFT JOIN facts n ON n.id = f.superseded_by
          WHERE f.source_id = ${ctx.source_id}
        `)).rows;
        for (const t of found) targets.set(factRowKey(t.slug, Number(t.row_num)),
          { id: Number(t.id), struck: t.expired_at != null, next_row: t.next_row == null ? null : Number(t.next_row) });
      }
      const links: Array<{ id: number; superseded_by: number }> = [];
      for (let i = 0; i < rows.length; i++) {
        const targetRow = rows[i].superseded_by_row;
        if (targetRow === undefined || rowIds[i] === null) continue;
        const slug = rows[i].source_markdown_slug;
        const chain = supersessionChainOf(rows, slug);
        // Only an int4-safe target was looked up. An absurd `#N` (11+ digits)
        // leaves `target` undefined, so resolveSupersededByRow treats it as a
        // dangling reference (NULL + warning) instead of throwing.
        const found = isInt4RowRef(targetRow) ? targets.get(factRowKey(slug, targetRow)) : undefined;
        const target: SupersedeTarget | undefined = found ? { id: found.id, struck: found.struck } : undefined;
        if (found?.next_row != null && !chain.has(targetRow)) chain.set(targetRow, found.next_row);
        const { superseded_by, warning } = resolveSupersededByRow(rows[i].row_num, targetRow, target, slug, chain);
        if (warning) warnings.push(warning);
        if (superseded_by === null) continue;
        links.push({ id: rowIds[i]!, superseded_by });
        // A later reference to this row sees the link, as the per-row reads did.
        const own = targets.get(factRowKey(slug, rows[i].row_num));
        if (own) own.next_row = targetRow;
      }
      if (links.length) {
        await tx.run(sqlFragment`UPDATE facts f SET superseded_by = l.superseded_by
          FROM jsonb_to_recordset(${JSON.stringify(links)}::text::jsonb) AS l(id bigint, superseded_by bigint) WHERE f.id = l.id`);
      }
      return out;
    });
    return { inserted: ids.length, ids, warnings, deleted };
  }

export async function deleteFactsForPage(
  exec: SqlExecutor,
    slug: string,
    source_id: string,
    opts?: { excludeSourcePrefixes?: string[]; preserveExpiredLegacy?: boolean },
  ): Promise<{ deleted: number }> {
    const prefixes = opts?.excludeSourcePrefixes;
    // #2646: keep soft-expired legacy rows (row_num NULL — never
    // fence-owned) so a fence reconcile can't destroy forget_fact's
    // legacy DB-only forget record.
    const expiredLegacyFilter = opts?.preserveExpiredLegacy
      ? sqlFragment`AND NOT (row_num IS NULL AND expired_at IS NOT NULL)`
      : sqlFragment``;
    if (prefixes && prefixes.length > 0) {
      // #1928: keep rows whose `source` matches an excluded prefix (e.g.
      // `cli:` conversation facts). COALESCE so NULL/empty-source fence rows
      // stay deletable — only the explicitly-protected prefixes survive.
      const patterns = prefixes.map(p => `${p}%`);
      const result = await exec.run(sqlFragment`
        DELETE FROM facts
        WHERE source_id = ${source_id}
          AND source_markdown_slug = ${slug}
          AND NOT (COALESCE(source, '') LIKE ANY(${patterns}))
          ${expiredLegacyFilter}
      `);
      return { deleted: result.affectedRows };
    }
    const result = await exec.run(sqlFragment`
      DELETE FROM facts WHERE source_id = ${source_id} AND source_markdown_slug = ${slug} ${expiredLegacyFilter}
    `);
    return { deleted: result.affectedRows };
  }

export async function listFactsByEntity(
  exec: LegacyUnscopedRead,
    source_id: string,
    entitySlug: string,
    opts?: FactListOpts,
  ): Promise<FactRow[]> {
    const limit = clampSearchLimit(opts?.limit, 50, MAX_SEARCH_LIMIT);
    const offset = Math.max(0, opts?.offset ?? 0);
    const activeOnly = opts?.activeOnly !== false;
    const unconsolidatedOnly = opts?.unconsolidatedOnly === true;
    const kinds = (opts?.kinds && opts.kinds.length > 0) ? opts.kinds : null;
    const visibility = (opts?.visibility && opts.visibility.length > 0) ? opts.visibility : null;
    const excludeAuditRows = opts?.excludeAuditRows === true;
    const grepPat = grepPattern(opts);
    // WP5 TTL honesty: activeOnly reads exclude validity-lapsed rows
    // (valid_until <= now()) at read time — exact-time, zero-maintenance.
    // History readers pass activeOnly:false and stay unfiltered. Parity with
    // the pglite engine's _listFacts predicate.
    const rows = (await exec.run<FactRowSqlShape>(sqlFragment`
      SELECT * FROM facts
      WHERE source_id = ${source_id}
        AND entity_slug = ${entitySlug}${opts?.sessionId ? sqlFragment` AND source_session = ${opts.sessionId}` : sqlFragment``}
        ${activeOnly ? sqlFragment`AND expired_at IS NULL AND (valid_until IS NULL OR valid_until > now())` : sqlFragment``}
        ${unconsolidatedOnly ? sqlFragment`AND consolidated_at IS NULL` : sqlFragment``}
        ${kinds ? sqlFragment`AND kind = ANY(${kinds}::text[])` : sqlFragment``}
        ${visibilityClause(visibility)}${privacyClause(opts)}
        ${excludeAuditRows ? sqlFragment`AND source != ALL(${AUDIT_ROW_SOURCES}::text[])` : sqlFragment``}
        ${grepPat ? sqlFragment`AND fact ILIKE ${grepPat} ESCAPE '\\'` : sqlFragment``}${eligibilityClause(opts)}
      ORDER BY valid_from DESC, id DESC
      LIMIT ${limit} OFFSET ${offset}
    `)).rows;
    return rows.map(rowToFact);
  }

export async function listFactsSince(
  exec: LegacyUnscopedRead,
    source_id: string,
    since: Date,
    opts?: RecallFactReadOpts,
  ): Promise<FactRow[]> {
    const limit = clampSearchLimit(opts?.limit, 50, MAX_SEARCH_LIMIT);
    const offset = Math.max(0, opts?.offset ?? 0);
    const activeOnly = opts?.activeOnly !== false;
    const unconsolidatedOnly = opts?.unconsolidatedOnly === true;
    const kinds = (opts?.kinds && opts.kinds.length > 0) ? opts.kinds : null;
    const visibility = (opts?.visibility && opts.visibility.length > 0) ? opts.visibility : null;
    const eventTime = opts?.eventTime === true;
    const rows = (await exec.run<FactRowSqlShape>(sqlFragment`
      SELECT *${opts?.fingerprint ? sqlFragment`, gbrain_fact_fingerprint(fact) AS fact_fingerprint` : sqlFragment``} FROM facts
      WHERE source_id = ${source_id}
        AND ${eventTime ? sqlFragment`COALESCE(valid_from, created_at)` : sqlFragment`created_at`} >= ${since}${recallNarrowing(opts)}
        ${activeOnly ? sqlFragment`AND expired_at IS NULL AND (valid_until IS NULL OR valid_until > now())` : sqlFragment``}
        ${unconsolidatedOnly ? sqlFragment`AND consolidated_at IS NULL` : sqlFragment``}
        ${kinds ? sqlFragment`AND kind = ANY(${kinds}::text[])` : sqlFragment``}
        ${visibilityClause(visibility)}${privacyClause(opts)}${eligibilityClause(opts)}
      ORDER BY ${eventTime ? sqlFragment`COALESCE(valid_from, created_at)` : sqlFragment`created_at`} DESC, id DESC
      LIMIT ${limit} OFFSET ${offset}
    `)).rows;
    return rows.map(rowToFact);
  }

/**
 * delta's facts arm (contributor audit wave P0): facts strictly after a
 * `(created_at, id)` keyset, OLDEST first, so a caller that delivers a prefix
 * can advance its keyset through exactly what it delivered. `after.id = null`
 * means "strictly after the timestamp" (a legacy `since`). `created_at_iso`
 * projects the column's microseconds: a keyset minted from a JS Date would
 * re-select or skip same-millisecond rows, and the bound goes through
 * `::text::timestamptz` so the postgres.js driver cannot truncate it to
 * milliseconds on the way in. recall's newest-first
 * `listFactsSince` is unchanged.
 */
export async function listFactsKeyset(
  exec: LegacyUnscopedRead,
  source_id: string,
  after: { createdAt: string; id: number | null } | null,
  opts?: RecallFactReadOpts,
): Promise<FactRow[]> {
  const limit = clampSearchLimit(opts?.limit, 50, MAX_SEARCH_LIMIT);
  const activeOnly = opts?.activeOnly !== false;
  const visibility = (opts?.visibility && opts.visibility.length > 0) ? opts.visibility : null;
  const afterCondition = after === null
    ? sqlFragment``
    : after.id === null
      ? sqlFragment`AND created_at > ${after.createdAt}::text::timestamptz`
      : sqlFragment`AND (created_at > ${after.createdAt}::text::timestamptz OR (created_at = ${after.createdAt}::text::timestamptz AND id > ${after.id}))`;
  const rows = (await exec.run<FactRowSqlShape>(sqlFragment`
    SELECT *${opts?.fingerprint ? sqlFragment`, gbrain_fact_fingerprint(fact) AS fact_fingerprint` : sqlFragment``},
           to_char(created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"') AS created_at_iso
    FROM facts
    WHERE source_id = ${source_id}
      ${afterCondition}${recallNarrowing(opts)}
      ${activeOnly ? sqlFragment`AND expired_at IS NULL AND (valid_until IS NULL OR valid_until > now())` : sqlFragment``}
      ${visibilityClause(visibility)}${privacyClause(opts)}${eligibilityClause(opts)}
    ORDER BY created_at ASC, id ASC
    LIMIT ${limit}
  `)).rows;
  return rows.map(rowToFact);
}

export async function listFactsBySession(
  exec: LegacyUnscopedRead,
    source_id: string,
    sessionId: string,
    opts?: FactListOpts,
  ): Promise<FactRow[]> {
    const limit = clampSearchLimit(opts?.limit, 50, MAX_SEARCH_LIMIT);
    const offset = Math.max(0, opts?.offset ?? 0);
    const activeOnly = opts?.activeOnly !== false;
    const unconsolidatedOnly = opts?.unconsolidatedOnly === true;
    const kinds = (opts?.kinds && opts.kinds.length > 0) ? opts.kinds : null;
    const visibility = (opts?.visibility && opts.visibility.length > 0) ? opts.visibility : null;
    const excludeAuditRows = opts?.excludeAuditRows === true;
    const grepPat = grepPattern(opts);
    const rows = (await exec.run<FactRowSqlShape>(sqlFragment`
      SELECT *${opts?.fingerprint ? sqlFragment`, gbrain_fact_fingerprint(fact) AS fact_fingerprint` : sqlFragment``} FROM facts
      WHERE source_id = ${source_id}
        AND source_session = ${sessionId}
        ${activeOnly ? sqlFragment`AND expired_at IS NULL AND (valid_until IS NULL OR valid_until > now())` : sqlFragment``}
        ${unconsolidatedOnly ? sqlFragment`AND consolidated_at IS NULL` : sqlFragment``}
        ${kinds ? sqlFragment`AND kind = ANY(${kinds}::text[])` : sqlFragment``}
        ${visibilityClause(visibility)}${privacyClause(opts)}
        ${excludeAuditRows ? sqlFragment`AND source != ALL(${AUDIT_ROW_SOURCES}::text[])` : sqlFragment``}
        ${grepPat ? sqlFragment`AND fact ILIKE ${grepPat} ESCAPE '\\'` : sqlFragment``}${eligibilityClause(opts)}
      ORDER BY created_at DESC, id DESC
      LIMIT ${limit} OFFSET ${offset}
    `)).rows;
    return rows.map(rowToFact);
  }

export async function listSupersessions(
  exec: LegacyUnscopedRead,
    source_id: string,
    opts?: { since?: Date; limit?: number; visibility?: ('private' | 'world')[]; eligibility?: import('../engine.ts').FactListOpts['eligibility']; excludePrivate?: boolean },
  ): Promise<FactRow[]> {
    const limit = clampSearchLimit(opts?.limit, 50, MAX_SEARCH_LIMIT);
    const since = opts?.since ?? null;
    const visibility = (opts?.visibility && opts.visibility.length > 0) ? opts.visibility : null;
    // v0.46 (#3014) — filter on `superseded_by` alone; the ontology
    // writer closes a superseded row via `valid_until` (not `expired_at`,
    // which would break its `--asof` time-travel), so requiring both
    // columns dropped every ontology supersession AND every fence-authored
    // one. Order / `since` fall back to `valid_until` when `expired_at` is
    // NULL.
    const rows = (await exec.run<FactRowSqlShape>(sqlFragment`
      SELECT * FROM facts
      WHERE source_id = ${source_id}
        AND superseded_by IS NOT NULL
        ${since ? sqlFragment`AND COALESCE(expired_at, valid_until) >= ${since}` : sqlFragment``}
        ${visibilityClause(visibility)}${privacyClause(opts)}${eligibilityClause(opts)}
      ORDER BY COALESCE(expired_at, valid_until) DESC, id DESC
      LIMIT ${limit}
    `)).rows;
    return rows.map(rowToFact);
  }

export async function countUnconsolidatedFacts(exec: LegacyUnscopedRead, source_id: string): Promise<number> {
    // Audit checkpoint rows never set consolidated_at, so without the source
    // exclusion each one counts as forever-pending consolidation backlog.
    // Validity-lapsed rows are excluded too: the consolidator reads via
    // listFactsByEntity(activeOnly), which filters them at read time — counting
    // them here would report a backlog the consolidator can never drain.
    // So are facts with no entity: consolidate reads (source, entity) buckets only (#5831).
    const rows = (await exec.run<{ count: number }>(sqlFragment`
      SELECT COUNT(*)::int AS count FROM facts
      WHERE source_id = ${source_id}
        AND entity_slug IS NOT NULL
        AND consolidated_at IS NULL
        AND expired_at IS NULL
        AND (valid_until IS NULL OR valid_until > now())
        AND source != ALL(${AUDIT_ROW_SOURCES}::text[])
    `)).rows;
    return Number(rows[0]?.count ?? 0);
  }

export async function findCandidateDuplicates(
  exec: LegacyUnscopedRead,
    source_id: string,
    entitySlug: string,
    factText: string,
    opts?: { k?: number; embedding?: Float32Array; embeddingModel?: string | null; arm?: 'keyword'; attributedTo?: FactAttribution | null; excludeMemberPages?: boolean; onlyPage?: string },
  ): Promise<FactRow[]> {
    const k = Math.min(Math.max(opts?.k ?? 5, 1), 20);
    const speaker = opts?.attributedTo
      ? sqlFragment`AND (attributed_to IS NULL OR attributed_to = ${opts.attributedTo})`
      : sqlFragment``;
    const members = opts?.onlyPage ? sqlFragment` AND source_markdown_slug = ${opts.onlyPage}`
      : opts?.excludeMemberPages ? sqlFragment` AND NOT ${trustedSql(onOwnedMemoryPageSql('facts'))}` : sqlFragment``;
    // Validity-lapsed rows are not dedup candidates: a re-stated fact after
    // its valid_until lapses re-inserts fresh (WP5 read-time TTL honesty).
    if (opts?.arm === 'keyword') return findKeywordCandidates(exec, source_id, entitySlug, factText, k, opts);
    if (opts?.embedding) {
      if (!opts.embeddingModel) return [];
      const lit = toPgVectorLiteral(opts.embedding);
      const rows = (await exec.run<FactRowSqlShape>(sqlFragment`
        SELECT * FROM facts
        WHERE source_id = ${source_id}
          AND entity_slug = ${entitySlug}
          AND expired_at IS NULL
          AND (valid_until IS NULL OR valid_until > now())
          AND embedding IS NOT NULL
          AND embedding_model=${opts.embeddingModel} AND embedded_text_hash=md5(fact)
          AND vector_dims(embedding)=${opts.embedding.length}
          AND source != ALL(${AUDIT_ROW_SOURCES}::text[])
          ${speaker}${members}
        ORDER BY embedding <=> ${trustedSql(vectorLiteralSql(lit, '::vector'))}
        LIMIT ${k}
      `)).rows;
      return rows.map(rowToFact);
    }
    const rows = (await exec.run<FactRowSqlShape>(sqlFragment`
      SELECT * FROM facts
      WHERE source_id = ${source_id}
        AND entity_slug = ${entitySlug}
        AND expired_at IS NULL
        AND (valid_until IS NULL OR valid_until > now())
        ${speaker}${members}
      ORDER BY created_at DESC, id DESC
      LIMIT ${k}
    `)).rows;
    return rows.map(rowToFact);
  }

/**
 * The keyword arm of fact supersession candidates (C2, `facts.candidate_fusion
 * = interleave`): the same entity bucket and active-row filters as the cosine
 * arm, ranked by `ts_rank_cd` against an OR of the new claim's lexemes, so a
 * twin whose wording changed only in a number or date still ranks by its
 * shared terms. With an embedding it keeps the cosine arm's comparability
 * filters (same model, current text hash, same dimensions), so every row it
 * returns can be scored by the caller's cosine decision. Per-row tsvector over
 * one entity's facts: no index is needed at k <= 20.
 */
async function findKeywordCandidates(
  exec: LegacyUnscopedRead, source_id: string, entitySlug: string, factText: string, k: number,
  opts: { embedding?: Float32Array; embeddingModel?: string | null; attributedTo?: FactAttribution | null; excludeMemberPages?: boolean; onlyPage?: string },
): Promise<FactRow[]> {
  if (opts.embedding && !opts.embeddingModel) return [];
  const speaker = opts.attributedTo
    ? sqlFragment`AND (f.attributed_to IS NULL OR f.attributed_to = ${opts.attributedTo})`
    : sqlFragment``;
  const lang = getFtsLanguage();
  const comparable = opts.embedding
    ? sqlFragment`AND embedding IS NOT NULL AND embedding_model=${opts.embeddingModel} AND embedded_text_hash=md5(fact)
          AND vector_dims(embedding)=${opts.embedding.length}`
    : sqlFragment``;
  const rows = (await exec.run<FactRowSqlShape>(sqlFragment`
      WITH q AS (SELECT NULLIF(replace(plainto_tsquery(${lang}::regconfig, ${factText})::text, ' & ', ' | '), '')::tsquery AS q)
      SELECT f.* FROM facts f, q
      WHERE f.source_id = ${source_id}
        AND f.entity_slug = ${entitySlug}
        AND f.expired_at IS NULL
        AND (f.valid_until IS NULL OR f.valid_until > now())
        AND f.source != ALL(${AUDIT_ROW_SOURCES}::text[])
        ${comparable}
        ${speaker}${opts.onlyPage ? sqlFragment` AND f.source_markdown_slug = ${opts.onlyPage}` : opts.excludeMemberPages ? sqlFragment` AND NOT ${trustedSql(onOwnedMemoryPageSql('f'))}` : sqlFragment``}
        AND q.q IS NOT NULL AND to_tsvector(${lang}::regconfig, f.fact) @@ q.q
      ORDER BY ts_rank_cd(to_tsvector(${lang}::regconfig, f.fact), q.q) DESC, f.created_at DESC, f.id DESC
      LIMIT ${k}
    `)).rows;
  return rows.map(rowToFact);
}

export async function consolidateFact(exec: SqlExecutor, id: number, takeId: number): Promise<void> {
    (await exec.run(sqlFragment`UPDATE facts SET consolidated_at = now(), consolidated_into = ${takeId} WHERE id = ${id}`)).rows;
  }

export async function findTrajectory(exec: LegacyUnscopedRead, opts: import('../engine.ts').TrajectoryOpts): Promise<import('../engine.ts').TrajectoryPoint[]> {
    const limit = clampSearchLimit(opts.limit, 100, 500);
    const sinceDate = opts.since ? new Date(opts.since) : null;
    const untilDate = opts.until ? new Date(opts.until) : null;
    const metric = opts.metric ?? null;
    const kind = opts.kind ?? 'all';
    const useArray = Array.isArray(opts.sourceIds) && opts.sourceIds.length > 0;
    const sourceIds = useArray ? opts.sourceIds! : null;
    const sourceId = opts.sourceId ?? 'default';
    // Fail-closed (CV6 / v0.26.9 F7b posture): `remote` means world-only facts here
    // (callers pass worldOnlyFacts(ctx.remote), so the brain owner's remote read passes
    // false); it gates only the visibility clause. An omitted flag degrades to
    // world-only reads, never to a private-fact leak.
    const remoteFilter = opts.remote !== false;

    // Source-scope predicate: array path (federated) wins over scalar.
    // Engine.ts contract: returns chronological points (the NEWEST `limit`,
    // so a capped series keeps its latest value); regressions + drift_score
    // are computed by the caller (src/core/trajectory.ts).
    // v0.40.2.0 — kind filter ('all'|'metric'|'event'); event_type column.
    const rows = (await exec.run<{
      id: number;
      valid_from: Date;
      valid_until: Date | null;
      claim_metric: string | null;
      claim_value: number | null;
      claim_unit: string | null;
      claim_period: string | null;
      event_type: string | null;
      fact: string;
      source_session: string | null;
      source_markdown_slug: string | null;
      embedding: string | null;
    }>(sqlFragment`
      SELECT id, valid_from, valid_until,
             claim_metric, claim_value, claim_unit, claim_period,
             event_type,
             fact, source_session, source_markdown_slug,
             CASE WHEN embedding_model=(SELECT value FROM config WHERE key='embedding_model')
               AND embedded_text_hash=md5(fact) THEN embedding::text END AS embedding
      FROM facts
      WHERE ${useArray ? sqlFragment`source_id = ANY(${sourceIds}::text[])` : sqlFragment`source_id = ${sourceId}`}
        AND entity_slug = ${opts.entitySlug}
        AND expired_at IS NULL
        ${remoteFilter ? visibilityClause(['world']) : sqlFragment``}${privacyClause(opts)}
        AND ${trustedSql(projectionEligibleSql('facts', 'facts', undefined))}
        ${metric !== null ? sqlFragment`AND claim_metric = ${metric}` : sqlFragment``}
        ${kind === 'metric' ? sqlFragment`AND claim_metric IS NOT NULL` : sqlFragment``}
        ${kind === 'event' ? sqlFragment`AND event_type IS NOT NULL` : sqlFragment``}
        ${sinceDate ? sqlFragment`AND valid_from >= ${sinceDate}` : sqlFragment``}
        ${untilDate ? sqlFragment`AND valid_from <= ${untilDate}` : sqlFragment``}
      ORDER BY valid_from DESC, id DESC
      LIMIT ${limit}
    `)).rows;

    return [...rows].reverse().map(r => ({
      fact_id: Number(r.id),
      valid_from: r.valid_from instanceof Date ? r.valid_from : new Date(r.valid_from as unknown as string),
      valid_until: r.valid_until === null ? null : r.valid_until instanceof Date ? r.valid_until : new Date(r.valid_until as unknown as string),
      metric: r.claim_metric,
      value: r.claim_value === null ? null : Number(r.claim_value),
      unit: r.claim_unit,
      period: r.claim_period,
      event_type: r.event_type,
      text: r.fact,
      source_session: r.source_session,
      source_markdown_slug: r.source_markdown_slug,
      embedding: tryParseEmbedding(r.embedding),
    }));
  }

export async function getFactsHealth(exec: LegacyUnscopedRead, source_id: string): Promise<FactsHealth> {
    // WP5 TTL honesty: validity-lapsed rows (valid_until <= now(), expired_at
    // NULL) count as expired-style, never active — matches the read-time
    // filtering on every active recall path. active + expired still
    // partitions the table exactly.
    const totals = (await exec.run<{
      total_active: bigint; total_today: bigint; total_week: bigint;
      total_expired: bigint; total_consolidated: bigint;
    }>(sqlFragment`
      SELECT
        COUNT(*) FILTER (WHERE expired_at IS NULL AND (valid_until IS NULL OR valid_until > now()))                                     AS total_active,
        COUNT(*) FILTER (WHERE expired_at IS NULL AND (valid_until IS NULL OR valid_until > now()) AND created_at > now() - interval '24 hours') AS total_today,
        COUNT(*) FILTER (WHERE expired_at IS NULL AND (valid_until IS NULL OR valid_until > now()) AND created_at > now() - interval '7 days')   AS total_week,
        COUNT(*) FILTER (WHERE expired_at IS NOT NULL OR (valid_until IS NOT NULL AND valid_until <= now()))                            AS total_expired,
        COUNT(*) FILTER (WHERE consolidated_at IS NOT NULL)                            AS total_consolidated
      FROM facts WHERE source_id = ${source_id}
    `)).rows;
    const top = (await exec.run<{ entity_slug: string; count: bigint }>(sqlFragment`
      SELECT entity_slug, COUNT(*) AS count
      FROM facts
      WHERE source_id = ${source_id} AND expired_at IS NULL
        AND (valid_until IS NULL OR valid_until > now())
        AND entity_slug IS NOT NULL
      GROUP BY entity_slug
      ORDER BY count DESC, entity_slug ASC
      LIMIT 5
    `)).rows;
    const r = totals[0] ?? {
      total_active: 0n, total_today: 0n, total_week: 0n, total_expired: 0n, total_consolidated: 0n,
    };
    return {
      source_id,
      total_active: Number(r.total_active),
      total_today: Number(r.total_today),
      total_week: Number(r.total_week),
      total_expired: Number(r.total_expired),
      total_consolidated: Number(r.total_consolidated),
      top_entities: top.map(t => ({ entity_slug: t.entity_slug, count: Number(t.count) })),
    };
  }

/**
 * Raw row shape returned from `SELECT * FROM facts` on Postgres.
 * postgres.js auto-decodes timestamps and numbers; embedding lands as
 * either a string ("[0.1,...]") or already-parsed array depending on type
 * codec — we handle both.
 */
export interface FactRowSqlShape {
  id: number | bigint;
  source_id: string;
  entity_slug: string | null;
  fact: string;
  kind: FactKind;
  visibility: FactVisibility;
  notability: 'high' | 'medium' | 'low';
  context: string | null;
  valid_from: Date;
  valid_until: Date | null;
  expired_at: Date | null;
  superseded_by: number | bigint | null;
  consolidated_at: Date | null;
  consolidated_into: number | bigint | null;
  source: string;
  source_session: string | null;
  confidence: number | string;
  embedding: string | number[] | Float32Array | null;
  embedding_model?: string | null;
  embedded_text_hash?: string | null;
  embedded_at: Date | null;
  created_at: Date;
  fact_fingerprint?: string | null;
  created_at_iso?: string | null;
  attributed_to?: FactAttribution | null;
  trust_tier?: string | null;
  write_origin?: unknown;
  claim_metric?: string | null;
  claim_value?: number | string | null;
  claim_unit?: string | null;
  claim_period?: string | null;
}

function originRecord(value: unknown): Record<string, unknown> | null {
  const parsed = typeof value === 'string' ? (() => { try { return JSON.parse(value) as unknown; } catch { return null; } })() : value;
  return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed as Record<string, unknown> : null;
}

/**
 * PGLite can hand timestamp columns back as strings on some paths; the
 * declared kinds make both drivers return `Date` (identity on Postgres).
 */
const normalizeFactRow = compileRowNormalizer<FactRowSqlShape>({
  valid_from: 'date', valid_until: 'date', expired_at: 'date',
  consolidated_at: 'date', embedded_at: 'date', created_at: 'date',
});

export function rowToFact(raw: FactRowSqlShape): FactRow {
  const row = normalizeFactRow(raw as unknown as Record<string, unknown>);
  let embedding: Float32Array | null = null;
  if (row.embedding != null) {
    if (row.embedding instanceof Float32Array) embedding = row.embedding;
    else if (Array.isArray(row.embedding)) embedding = new Float32Array(row.embedding);
    else if (typeof row.embedding === 'string') {
      const trimmed = row.embedding.trim();
      const inner = trimmed.startsWith('[') ? trimmed.slice(1, -1) : trimmed;
      const parts = inner.split(',').map(p => parseFloat(p.trim())).filter(Number.isFinite);
      embedding = parts.length > 0 ? new Float32Array(parts) : null;
    }
  }
  return {
    id: Number(row.id),
    source_id: row.source_id,
    entity_slug: row.entity_slug,
    fact: row.fact,
    kind: row.kind,
    visibility: row.visibility,
    // v0.31.2: notability column added by migration v46. Pre-v46 rows that
    // somehow survive a SELECT (shouldn't on a fully-migrated brain) fall
    // back to 'medium' to keep the contract total. Belt-and-suspenders with
    // the migration's NOT NULL DEFAULT.
    notability: row.notability ?? 'medium',
    context: row.context,
    valid_from: row.valid_from,
    valid_until: row.valid_until,
    expired_at: row.expired_at,
    superseded_by: row.superseded_by == null ? null : Number(row.superseded_by),
    consolidated_at: row.consolidated_at,
    consolidated_into: row.consolidated_into == null ? null : Number(row.consolidated_into),
    source: row.source,
    source_session: row.source_session,
    confidence: typeof row.confidence === 'string' ? parseFloat(row.confidence) : row.confidence,
    embedding,
    embedding_model: row.embedding_model ?? null,
    embedded_text_hash: row.embedded_text_hash ?? null,
    embedded_at: row.embedded_at,
    created_at: row.created_at,
    ...(row.fact_fingerprint ? { fact_fingerprint: row.fact_fingerprint } : {}),
    ...(row.created_at_iso ? { created_at_iso: row.created_at_iso } : {}),
    ...(row.attributed_to ? { attributed_to: row.attributed_to } : {}),
    ...(row.trust_tier ? { trust_tier: storedTrustTier(row.trust_tier) } : {}),
    ...(row.write_origin !== undefined ? { write_origin: originRecord(row.write_origin) } : {}),
    ...(row.claim_metric ? { claim_metric: row.claim_metric } : {}),
    ...(row.claim_value != null ? { claim_value: Number(row.claim_value) } : {}),
    ...(row.claim_unit ? { claim_unit: row.claim_unit } : {}),
    ...(row.claim_period ? { claim_period: row.claim_period } : {}),
  };
}

/**
 * The inlined vector literal master used (`'[0.1,...]'::vector`): kept as
 * literal text, not a bound param, so the planner sees a constant (HNSW
 * ordering). Registered in scripts/check-engine-sql-dynamic.ts VETTED_BUILDERS:
 * `literal` is always toPgVectorLiteral output (numbers joined by commas) and
 * `cast` one of two constants.
 */
function vectorLiteralSql(literal: string, cast: EmbeddingCast): string {
  return `'${literal}'${cast}`;
}

function toPgVectorLiteral(v: Float32Array | number[]): string {
  if (v instanceof Float32Array) return '[' + Array.from(v).join(',') + ']';
  return '[' + v.join(',') + ']';
}