Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* 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(',') + ']';
}