mixdog 0.9.170 → 0.9.172

package/src/runtime/memory/lib/recall-hybrid/concept-expansion.mjs

@@ -0,0 +1,211 @@
+/**
+ * src/runtime/memory/lib/recall-hybrid/concept-expansion.mjs - latestByConcept
+ * mode: widen candidates to the newest root of every matched concept, and
+ * swap final rows for the latest conclusion of their concept.
+ */
+import { recallReadQuery } from '../memory-recall-read-query.mjs';
+import { recallRrfScore } from '../recall-fusion.mjs';
+import { filterClause, rootIdOf } from './plan.mjs';
+
+const RANK_KEYS = ['dense_rank', 'sparse_rank', 'trgm_rank', 'exact_rank'];
+const MAX_KEYS = ['dense_sim', 'sparse_lex', 'trg_sim', 'exact_hits', 'exact_phrase_hits', 'exact_rarity'];
+
+async function conceptIdsByRoot(db, candidateRootIds) {
+  const relations = await recallReadQuery(
+    db,
+    `
+        WITH roots AS (
+          SELECT id, concept_id FROM entries WHERE id = ANY($1::bigint[]) AND is_root = 1
+        )
+        SELECT r.id AS root_id, ec.concept_id
+        FROM roots r
+        JOIN entry_concepts ec ON ec.entry_id = r.id
+        UNION
+        SELECT r.id AS root_id, r.id AS concept_id FROM roots r
+        UNION
+        SELECT r.id AS root_id, r.concept_id FROM roots r WHERE r.concept_id IS NOT NULL
+      `,
+    [candidateRootIds]
+  );
+  const byRoot = new Map();
+  for (const relation of relations.rows) {
+    const rootId = Number(relation.root_id);
+    const conceptId = Number(relation.concept_id);
+    if (!Number.isFinite(rootId) || !Number.isFinite(conceptId)) continue;
+    if (!byRoot.has(rootId)) byRoot.set(rootId, []);
+    byRoot.get(rootId).push(conceptId);
+  }
+  return byRoot;
+}
+
+// The strongest candidate per concept lends its lane evidence to the newest
+// root of that concept.
+function anchorsByConcept(rawRows, byRoot) {
+  const anchors = new Map();
+  for (const row of rawRows) {
+    for (const conceptId of byRoot.get(rootIdOf(row)) ?? []) {
+      const prior = anchors.get(conceptId);
+      if (!prior || recallRrfScore(row) > recallRrfScore(prior)) anchors.set(conceptId, row);
+    }
+  }
+  return anchors;
+}
+
+function inheritAnchorEvidence(latestRow, anchor, existing) {
+  const inherited = { ...latestRow };
+  for (const key of [...RANK_KEYS, ...MAX_KEYS]) inherited[key] = anchor[key];
+  if (!existing) return inherited;
+  for (const key of RANK_KEYS) {
+    const values = [existing[key], inherited[key]].filter((value) => value != null).map(Number);
+    inherited[key] = values.length > 0 ? Math.min(...values) : null;
+  }
+  for (const key of MAX_KEYS) {
+    const values = [existing[key], inherited[key]].filter((value) => value != null).map(Number);
+    inherited[key] = values.length > 0 ? Math.max(...values) : null;
+  }
+  return inherited;
+}
+
+/** Widen `rawRows` with the newest root of every matched concept. */
+export async function expandLatestByConcept(db, rawRows, plan) {
+  const conceptExpandedRootIds = new Set();
+  const candidateRootIds = [...new Set(rawRows.map(rootIdOf).filter(Number.isFinite))];
+  if (candidateRootIds.length === 0) return { rows: rawRows, conceptExpandedRootIds };
+  const anchors = anchorsByConcept(rawRows, await conceptIdsByRoot(db, candidateRootIds));
+  const conceptIds = [...anchors.keys()];
+  if (conceptIds.length === 0) return { rows: rawRows, conceptExpandedRootIds };
+  const { clause: latestFilter, params: latestParams } = filterClause(plan, 2, { skipTsWindow: true, tableAlias: 'e' });
+  const latest = await recallReadQuery(
+    db,
+    `
+          SELECT DISTINCT ON (ec.concept_id)
+                 ec.concept_id AS matched_concept_id,
+                 e.id, e.ts, e.role, e.content, e.source_ref, e.session_id,
+                 e.source_turn, e.time_source, e.chunk_root, e.is_root,
+                 e.concept_id, e.supersedes_id, e.element, e.category,
+                 e.summary, e.project_id, e.status, e.score, e.last_seen_at
+          FROM entry_concepts ec
+          JOIN entries e ON e.id = ec.entry_id
+          WHERE ec.concept_id = ANY($1::bigint[])
+            AND e.is_root = 1
+            ${latestFilter}
+          ORDER BY ec.concept_id, e.ts DESC, e.id DESC
+        `,
+    [conceptIds, ...latestParams]
+  );
+  const merged = new Map(rawRows.map((row) => [Number(row.id), row]));
+  for (const latestRow of latest.rows) {
+    const anchor = anchors.get(Number(latestRow.matched_concept_id));
+    if (!anchor) continue;
+    const carriesLatestConclusion = latestRow.supersedes_id != null || Number(latestRow.id) !== rootIdOf(anchor);
+    if (carriesLatestConclusion) conceptExpandedRootIds.add(Number(latestRow.id));
+    const inherited = inheritAnchorEvidence(latestRow, anchor, merged.get(Number(latestRow.id)));
+    inherited._conceptExpanded = carriesLatestConclusion;
+    merged.set(Number(latestRow.id), inherited);
+  }
+  return { rows: [...merged.values()], conceptExpandedRootIds };
+}
+
+export function preferLatestConceptRows(rows, latestRows) {
+  const latestByConcept = new Map();
+  for (const row of latestRows ?? []) {
+    const conceptId = Number(row?.matched_concept_id ?? row?.concept_id ?? row?.id);
+    if (Number.isFinite(conceptId) && !latestByConcept.has(conceptId)) {
+      latestByConcept.set(conceptId, row);
+    }
+  }
+  return (rows ?? []).map((row) => {
+    const conceptIds = row?.concept_ids?.length
+      ? row.concept_ids.map(Number).filter(Number.isFinite)
+      : [Number(row?.concept_id ?? row?.id)].filter(Number.isFinite);
+    let best = row;
+    for (const conceptId of conceptIds) {
+      const candidate = latestByConcept.get(conceptId);
+      if (!candidate) continue;
+      const newer =
+        Number(candidate.ts ?? 0) > Number(best?.ts ?? 0) ||
+        (Number(candidate.ts ?? 0) === Number(best?.ts ?? 0) && Number(candidate.id ?? 0) > Number(best?.id ?? 0));
+      if (newer) best = candidate;
+    }
+    return best;
+  });
+}
+
+async function conceptIdsForRoots(db, finalRows) {
+  const rootIds = finalRows
+    .filter((row) => Number(row.is_root) === 1)
+    .map((row) => Number(row.id))
+    .filter(Number.isFinite);
+  if (rootIds.length === 0) return new Map();
+  const relationResult = await recallReadQuery(
+    db,
+    `
+          SELECT entry_id, array_agg(concept_id ORDER BY concept_id) AS concept_ids
+          FROM entry_concepts
+          WHERE entry_id = ANY($1::bigint[])
+          GROUP BY entry_id
+        `,
+    [rootIds]
+  );
+  return new Map(
+    relationResult.rows.map((row) => [
+      Number(row.entry_id),
+      (row.concept_ids ?? []).map(Number).filter(Number.isFinite),
+    ])
+  );
+}
+
+/**
+ * Annotate final root rows with their concept ids and resolve each to the
+ * latest root of its concept. Returns the annotated rows (index-aligned with
+ * the input) and the resolved rows.
+ */
+export async function resolveLatestConceptRows(db, finalRows, plan) {
+  const relationConcepts = await conceptIdsForRoots(db, finalRows);
+  const annotated = finalRows.map((row) => {
+    const conceptIds = relationConcepts.get(Number(row.id));
+    return conceptIds?.length ? { ...row, concept_ids: conceptIds } : row;
+  });
+  const conceptIds = [
+    ...new Set(
+      annotated
+        .filter((row) => Number(row.is_root) === 1)
+        .flatMap((row) => (row.concept_ids?.length ? row.concept_ids : [Number(row.concept_id ?? row.id)]))
+        .filter(Number.isFinite)
+    ),
+  ];
+  if (conceptIds.length === 0) return { finalRows: annotated, resolvedFinalRows: annotated };
+  const { clause: latestFilter, params: latestParams } = filterClause(plan, 2, { skipTsWindow: true, tableAlias: 'e' });
+  const latestResult = await recallReadQuery(
+    db,
+    `
+        WITH candidates AS (
+          SELECT ec.concept_id AS matched_concept_id,
+                 e.id, e.ts, e.role, e.content, e.source_ref, e.session_id,
+                 e.source_turn, e.time_source, e.chunk_root, e.is_root,
+                 e.concept_id, e.supersedes_id, e.element, e.category,
+                 e.summary, e.project_id, e.status, e.score, e.last_seen_at
+          FROM entry_concepts ec
+          JOIN entries e ON e.id = ec.entry_id
+          WHERE ec.concept_id = ANY($1::bigint[])
+            AND e.is_root = 1
+            ${latestFilter}
+          UNION ALL
+          SELECT COALESCE(e.concept_id, e.id) AS matched_concept_id,
+                 e.id, e.ts, e.role, e.content, e.source_ref, e.session_id,
+                 e.source_turn, e.time_source, e.chunk_root, e.is_root,
+                 e.concept_id, e.supersedes_id, e.element, e.category,
+                 e.summary, e.project_id, e.status, e.score, e.last_seen_at
+          FROM entries e
+          WHERE e.is_root = 1
+            AND COALESCE(e.concept_id, e.id) = ANY($1::bigint[])
+            ${latestFilter}
+        )
+        SELECT DISTINCT ON (matched_concept_id) *
+        FROM candidates
+        ORDER BY matched_concept_id, ts DESC, id DESC
+      `,
+    [conceptIds, ...latestParams]
+  );
+  return { finalRows: annotated, resolvedFinalRows: preferLatestConceptRows(annotated, latestResult.rows) };
+}

package/src/runtime/memory/lib/recall-hybrid/hybrid-sql.mjs

@@ -0,0 +1,250 @@
+/**
+ * src/runtime/memory/lib/recall-hybrid/hybrid-sql.mjs - the single-round-trip
+ * hybrid candidate CTE (dense / sparse / substring / exact-term legs) and its
+ * positional bind layout.
+ */
+import { buildFtsQuery, buildFtsPrefixQuery } from '../memory-text-utils.mjs';
+import { embeddingToSql } from '../memory.mjs';
+import { recallSubstringPredicate } from '../recall-substring-predicate.mjs';
+import { buildExactTerms } from '../recall-scoring.mjs';
+import { filterClause } from './plan.mjs';
+
+// Bounded lexical scan window. The trgm/exact CTE legs run `ILIKE '%…%'`
+// which are indexable when optional pg_trgm indexes exist. On portable
+// runtimes without them, their worst case grows linearly with the
+// entries table — on a years-old memory DB every recall pays a full-table
+// substring scan twice. Bound both legs to the newest N rows by id (bigserial
+// ⇒ insertion order; MAX(id) resolves via the pk index, no sort). Dense
+// (HNSW) and sparse (GIN FTS) legs still cover the WHOLE table through real
+// indexes, so old memories remain reachable semantically/topically — only the
+// exact-substring rescue narrows to recent rows. Default 200k: measured on a
+// live DB, a 20k bound regressed recall quality (bench MRR 0.75 → 0.33 — the
+// rescued rows sat beyond the newest 20k inserts), so the default only guards
+// pathological table growth, not today's scale. MIXDOG_RECALL_LEXSCAN_ROWS
+// overrides; 0 restores the unbounded scan.
+const _envLexScan = Number(process.env.MIXDOG_RECALL_LEXSCAN_ROWS);
+const RECALL_LEXSCAN_ROWS = Number.isFinite(_envLexScan) && _envLexScan >= 0 ? Math.floor(_envLexScan) : 200_000;
+function lexScanBound(alias = '') {
+  if (RECALL_LEXSCAN_ROWS <= 0) return '';
+  const col = alias ? `${alias}.id` : 'id';
+  return `AND ${col} >= (SELECT GREATEST(COALESCE(MAX(id), 0) - ${RECALL_LEXSCAN_ROWS}, 0) FROM entries)`;
+}
+
+// Candidate generation is recall-oriented: one concept may be the only
+// distinctive event identifier in a natural-language question. Precision is
+// enforced after retrieval through semantic support, token coverage, and
+// candidate-local document frequency rather than by requiring several query
+// concepts to co-occur before the row can even be scored.
+const MIN_EXACT_HITS = 1;
+
+// dense CTE: active only when a query vector is supplied.
+function denseCte(vecSql, filters) {
+  if (!vecSql) {
+    return `
+dense AS (SELECT NULL::bigint AS id, NULL::float8 AS sim, NULL::bigint AS dense_rank WHERE $1::halfvec IS NOT NULL AND false),`;
+  }
+  return `
+dense AS (
+  SELECT id,
+         1 - (embedding <=> $1::halfvec) AS sim,
+         ROW_NUMBER() OVER (ORDER BY embedding <=> $1::halfvec) AS dense_rank
+  FROM entries
+  WHERE embedding IS NOT NULL
+    ${filters.filterClause}
+    ${filters.entryRootFilter}
+  ORDER BY embedding <=> $1::halfvec
+  LIMIT $4
+),`;
+}
+
+// sparse CTE: active only when ftsQuery is non-null.
+// tsqExpr: to_tsquery for normalized prefix terms ('stem:* & ...'), else
+// websearch_to_tsquery for a plain fallback token string. Both parse $2 under
+// the 'simple' config to match search_tsv's simple-config lexemes.
+function sparseCte(ftsQuery, ftsPrefixMode, filters) {
+  if (!ftsQuery) {
+    return `
+sparse AS (SELECT NULL::bigint AS id, NULL::float8 AS lex, NULL::bigint AS sparse_rank WHERE $2::text IS NOT NULL AND false),`;
+  }
+  const tsqExpr = ftsPrefixMode ? `to_tsquery('simple', $2)` : `websearch_to_tsquery('simple', $2)`;
+  return `
+sparse AS (
+  SELECT id,
+         ts_rank_cd(search_tsv, ${tsqExpr}) AS lex,
+         ROW_NUMBER() OVER (ORDER BY ts_rank_cd(search_tsv, ${tsqExpr}) DESC) AS sparse_rank
+  FROM entries
+  WHERE search_tsv @@ ${tsqExpr}
+    ${filters.filterClause}
+    ${filters.entryRootFilter}
+  ORDER BY lex DESC
+  LIMIT $4
+),`;
+}
+
+// Portable substring leg. The curated Unix PG runtimes include pgvector but
+// not the optional pg_trgm contrib extension, so fuzzy similarity cannot be
+// a startup/runtime requirement. FTS and dense vector search retain broad
+// matching while this leg gives exact substrings a deterministic rescue.
+function trgmCte(filters) {
+  return `
+trgm AS (
+  SELECT id,
+         1.0::float8 AS trg_sim,
+         ROW_NUMBER() OVER (ORDER BY ts DESC) AS trgm_rank
+  FROM entries
+  WHERE (
+      content ILIKE '%' || $3 || '%'
+      OR ${recallSubstringPredicate('element', '$3')}
+      OR ${recallSubstringPredicate('summary', '$3')}
+    )
+    ${filters.filterClause}
+    ${filters.entryRootFilter}
+    ${lexScanBound()}
+  ORDER BY ts DESC
+  LIMIT $4
+),`;
+}
+
+function exactCte(exactTermsParam, filters) {
+  if (!exactTermsParam) {
+    return `
+exact_matches AS (
+  SELECT NULL::bigint AS id, NULL::bigint AS ts, NULL::text AS term, NULL::float8 AS term_df
+  WHERE false
+),
+exact AS (
+  SELECT NULL::bigint AS id, NULL::float8 AS exact_hits,
+         NULL::float8 AS exact_phrase_hits, NULL::float8 AS exact_rarity,
+         NULL::bigint AS exact_rank
+  WHERE false
+),`;
+  }
+  return `
+exact_matches AS (
+  SELECT ee.id,
+         ee.ts,
+         q.term,
+         COUNT(*) OVER (PARTITION BY q.term)::float8 AS term_df
+  FROM entries ee
+  JOIN LATERAL unnest($${exactTermsParam}::text[]) AS q(term) ON (
+       ee.content ILIKE '%' || q.term || '%'
+       OR ${recallSubstringPredicate('ee.element', 'q.term')}
+       OR ${recallSubstringPredicate('ee.summary', 'q.term')}
+  )
+  WHERE true
+    ${filters.exactFilterClause}
+    ${filters.exactRootFilter}
+    ${lexScanBound('ee')}
+),
+exact AS (
+  SELECT id,
+         COUNT(*)::float8 AS exact_hits,
+         COUNT(*) FILTER (WHERE POSITION(' ' IN term) > 0)::float8 AS exact_phrase_hits,
+         SUM(
+           (CASE WHEN term ~ '[A-Za-z0-9_./:-]' THEN 3.0 ELSE 1.0 END)
+           / SQRT(GREATEST(term_df, 1))
+         )::float8 AS exact_rarity,
+         ROW_NUMBER() OVER (
+           ORDER BY SUM(
+                      (CASE WHEN term ~ '[A-Za-z0-9_./:-]' THEN 3.0 ELSE 1.0 END)
+                      / SQRT(GREATEST(term_df, 1))
+                    ) DESC,
+                    COUNT(*) DESC,
+                    MAX(ts) DESC
+         ) AS exact_rank
+  FROM exact_matches
+  GROUP BY id
+  HAVING COUNT(*) >= ${MIN_EXACT_HITS}
+  ORDER BY exact_rarity DESC, exact_hits DESC, MAX(ts) DESC
+  LIMIT $4
+),`;
+}
+
+/**
+ * Param layout (fixed prefix):
+ *   $1  = halfvec literal  (NULL when no queryVector)
+ *   $2  = tsQuery text     (NULL when short query)
+ *   $3  = cleanText        (trigram term)
+ *   $4  = candidateWindow  (LIMIT for each CTE leg)
+ *   $5+ = filter params (ts_from, ts_to, excludeStatuses..., category..., projectScope slug)
+ *   then the exact-term array when the query yields exact terms.
+ *
+ * When a leg is inapplicable its CTE returns no rows; the UNION + LEFT JOINs
+ * handle that cleanly. dense/sparse/trgm legs each re-use the same filter
+ * params starting at $5 since they live in independent CTE scopes.
+ */
+export function buildHybridQuery(plan) {
+  const vecSql = plan.queryVector ? embeddingToSql(plan.queryVector) : null;
+  // Use the model-free Korean normalizer with to_tsquery ':*' prefix matches.
+  // ftsPrefixMode drives which tsquery constructor the sparse CTE uses.
+  const ftsPrefix = plan.clean.length >= 3 ? buildFtsPrefixQuery(plan.clean) : null;
+  let ftsQuery = null;
+  if (ftsPrefix) ftsQuery = ftsPrefix.query;
+  else if (plan.clean.length >= 3) ftsQuery = buildFtsQuery(plan.clean) ?? null;
+  const exactTerms = buildExactTerms(plan.clean);
+
+  // Each CTE leg uses the same positional filters against the history table.
+  const { clause, params: filterParams } = filterClause(plan, 5);
+  const filters = {
+    filterClause: clause,
+    entryRootFilter: plan.rootOnly ? 'AND is_root = 1' : '',
+    exactFilterClause: filterClause(plan, 5, { tableAlias: 'ee' }).clause,
+    exactRootFilter: plan.rootOnly ? 'AND ee.is_root = 1' : '',
+  };
+  const exactTermsParam = exactTerms.length > 0 ? 5 + filterParams.length : 0;
+
+  const sql = `
+WITH
+${denseCte(vecSql, filters)}
+${sparseCte(ftsQuery, Boolean(ftsPrefix), filters)}
+${trgmCte(filters)}
+${exactCte(exactTermsParam, filters)}
+combined AS (
+  SELECT id FROM dense  WHERE id IS NOT NULL UNION
+  SELECT id FROM sparse WHERE id IS NOT NULL UNION
+  SELECT id FROM trgm   WHERE id IS NOT NULL UNION
+  SELECT id FROM exact  WHERE id IS NOT NULL
+)
+SELECT
+  e.id, e.element, e.summary, e.category, e.status, e.score,
+  e.last_seen_at, e.ts, e.project_id, e.session_id, e.source_ref,
+  e.source_turn, e.content, e.chunk_root, e.concept_id, e.supersedes_id, e.is_root,
+  e.role,
+  d.sim        AS dense_sim,
+  d.dense_rank,
+  s.lex        AS sparse_lex,
+  s.sparse_rank,
+  t.trg_sim,
+  t.trgm_rank,
+  x.exact_hits,
+  x.exact_phrase_hits,
+  x.exact_rarity,
+  x.exact_rank
+FROM combined c
+JOIN   entries e ON e.id = c.id
+LEFT JOIN dense  d ON d.id = c.id
+LEFT JOIN sparse s ON s.id = c.id
+LEFT JOIN trgm   t ON t.id = c.id
+LEFT JOIN exact  x ON x.id = c.id`;
+  const params = [
+    vecSql,
+    ftsQuery,
+    plan.clean,
+    plan.candidateWindow,
+    ...filterParams,
+    ...(exactTermsParam ? [exactTerms] : []),
+  ];
+  return { sql, params };
+}
+
+/** How many candidate rows each leg contributed (a row may appear in several). */
+export function legCounts(rows) {
+  const counts = { dense: 0, sparse: 0, trgm: 0, exact: 0 };
+  for (const r of rows) {
+    if (r.dense_rank != null) counts.dense++;
+    if (r.sparse_rank != null) counts.sparse++;
+    if (r.trgm_rank != null) counts.trgm++;
+    if (r.exact_rank != null) counts.exact++;
+  }
+  return counts;
+}

package/src/runtime/memory/lib/recall-hybrid/members.mjs

@@ -0,0 +1,33 @@
+/**
+ * src/runtime/memory/lib/recall-hybrid/members.mjs - attach member turns to
+ * the root rows of the final page.
+ */
+import { recallReadQuery } from '../memory-recall-read-query.mjs';
+
+/** Expands only the final page, not every candidate considered. */
+export async function attachMembers(db, page, matchedMembersByRoot) {
+  const rootIds = page.filter((row) => row.is_root === 1).map((row) => Number(row.id));
+  if (rootIds.length === 0) return;
+  const { rows: memberRows } = await recallReadQuery(
+    db,
+    `SELECT id, ts, role, content, source_ref, session_id, source_turn, time_source, project_id, chunk_root
+         FROM entries WHERE chunk_root = ANY($1::bigint[]) AND is_root = 0
+         ORDER BY ts ASC, id ASC`,
+    [rootIds]
+  );
+  const membersByRoot = new Map();
+  for (const member of memberRows) {
+    const id = Number(member.chunk_root);
+    if (!membersByRoot.has(id)) membersByRoot.set(id, []);
+    membersByRoot.get(id).push(member);
+  }
+  for (const row of page) {
+    if (row.is_root !== 1) continue;
+    const allMembers = membersByRoot.get(Number(row.id)) ?? [];
+    const matched = matchedMembersByRoot.get(Number(row.id));
+    // Preserve complete matched turns, without flooding a member hit with
+    // unrelated siblings. Root hits keep their full original expansion.
+    const kept = matched?.size ? allMembers.filter((member) => matched.has(Number(member.id))) : [];
+    row.members = kept.length > 0 ? kept : allMembers;
+  }
+}

package/src/runtime/memory/lib/recall-hybrid/plan.mjs

@@ -0,0 +1,80 @@
+/**
+ * src/runtime/memory/lib/recall-hybrid/plan.mjs - normalized recall request:
+ * paging, pre-filter knobs, and the shared SQL filter/scope clause builders
+ * every stage of the hybrid search binds against.
+ */
+import { VALID_CATEGORY } from '../memory.mjs';
+import { buildRecallScopeFilter, projectScopePredicate } from '../memory-recall-scope-filter.mjs';
+
+export const ENTRY_ROW_COLUMNS = `id, ts, role, content, source_ref, session_id, source_turn, time_source, chunk_root, is_root,
+              concept_id, supersedes_id, element, category, summary, project_id, status, score, last_seen_at`;
+
+export function recallPlan(clean, options = {}) {
+  const limit = Math.max(1, Math.floor(Number(options?.limit ?? 8)));
+  const categories = (Array.isArray(options.category) ? options.category : [options.category])
+    .map((c) =>
+      String(c ?? '')
+        .trim()
+        .toLowerCase()
+    )
+    .filter((c) => VALID_CATEGORY.has(c));
+  return {
+    clean,
+    limit,
+    // Retrieval quality must not depend on the caller's display page size.
+    // Work/event queries often have many same-topic progress rows; a limit=10
+    // page still needs a broad pool so the final decision can outrank them.
+    candidateWindow: Math.max(240, limit * 8),
+    includeMembers: Boolean(options.includeMembers),
+    rootOnly: options.rootOnly === true,
+    latestByConcept: options.latestByConcept === true,
+    queryVector: Array.isArray(options.queryVector) && options.queryVector.length > 0 ? options.queryVector : null,
+    // Pre-filter knobs. Without them, FTS/vec rank the whole tree and a
+    // post-filter time window can wipe the result set.
+    tsFrom: Number.isFinite(Number(options.ts_from)) ? Number(options.ts_from) : null,
+    tsTo: Number.isFinite(Number(options.ts_to)) ? Number(options.ts_to) : null,
+    // All history is searchable by default. Legacy status filters are honored
+    // only when explicitly requested; maintenance no longer assigns importance.
+    excludeStatuses: Array.isArray(options.excludeStatuses)
+      ? options.excludeStatuses.filter((s) => typeof s === 'string' && s.trim()).map((s) => s.trim().toLowerCase())
+      : [],
+    // Project scope pre-filter applied to the candidate fetch SQL.
+    // 'common' → project_id IS NULL; specific slug → project_id IS NULL OR = slug;
+    // 'all' or undefined → no filter.
+    projectScope: typeof options.projectScope === 'string' ? options.projectScope : null,
+    categories,
+  };
+}
+
+// Pushes ts/status/scope filters INTO candidate SELECTs. offset = 1-based
+// index of the first bind param it may consume. Returns { clause, params };
+// clause begins with AND or is ''.
+export function filterClause(plan, offset, opts = {}) {
+  return buildRecallScopeFilter(
+    offset,
+    {
+      // skipTsWindow must fully DROP the ts predicate for member-hit roots
+      // (their own ts can sit outside the window; the member ts was already
+      // gated). Pass `undefined`, not `null`: buildRecallScopeFilter coerces
+      // its ts inputs via Number(x), and Number(null) === 0 (finite) would
+      // inject `ts BETWEEN 0 AND 0`, silently dropping every member-hit root.
+      // Number(undefined) === NaN, which the finite-check correctly skips.
+      ts_from: opts.skipTsWindow ? undefined : plan.tsFrom,
+      ts_to: opts.skipTsWindow ? undefined : plan.tsTo,
+      excludeStatuses: plan.excludeStatuses,
+      category: plan.categories,
+      projectScope: plan.projectScope,
+    },
+    opts.tableAlias || ''
+  );
+}
+
+// Scope-only clause for the non-candidate root lookup in member-hit resolution.
+export function scopeClause(plan, offset) {
+  const { clause, params } = projectScopePredicate(plan.projectScope, offset);
+  return { clause: clause ? `AND ${clause}` : '', params };
+}
+
+export function rootIdOf(row) {
+  return Number(row.is_root) === 1 ? Number(row.id) : Number(row.chunk_root);
+}