Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix: pre-landing review fixes (Step 11, granted scoped fix-check)
garrytan2410cddf4318
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex dd9f11d2d3..c10b78f628 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -37,7 +37,7 @@ An identifier is a `#` number, a run of 6 or more digits, a code such as INV-202| The same query in hybrid search | quoted terms skip the any-word retry, so the title arm found nothing either | the named pages lead the keyword arm, as rows that count like strict keyword rows || A search that matches nothing while every retrieval stage ran | the CLI said "clean miss — no retrieval degradation" and MCP "this is a clean miss", which agents read as "the brain has no page for this" | "retrieval healthy", followed by the next things to try (the display name, a synonym, hybrid search) before concluding the brain has nothing; the query skill says the same |-A handle is a hyphenated token with a letter in it, bare or quoted on its own (`acme-example-2` counts, `2026-10-24` does not), and resolves only to a page whose slug ends in exactly that handle. A negated handle (`-dan-example`) or one inside a longer quoted phrase is not resolved. The named pages pass the same filters as any keyword match: `--types`, the caller's sources, and for remote callers no private or quarantined page.+A handle is a hyphenated token with a letter in it, bare or quoted on its own (`acme-example-2` counts, `2026-10-24` does not), and resolves only to a page whose slug ends in exactly that handle. A query with a `-` negation or a longer quoted phrase resolves no handle, and `--match keyword` resolves handles only when every term is one (or `OR`), so a handle never brings back a page the query excludes, a phrase it doesn't hold or a word it doesn't contain. If the identifier or handle lookup fails, the result is stamped degraded (`keyword_candidates_incomplete`) rather than reading as a miss. The named pages pass the same filters as any keyword match: `--types`, the caller's sources, and for remote callers no private or quarantined page.#### Coverage notice@@ -72,7 +72,7 @@ Remote callers get the shared read policy (private pages, trust floor, quarantin### `--explain-target` in CLI JSON, and an opt-in keyword phrase factor (#7192, #7175, #7198)-- `gbrain query "<q>" --explain-target <source>:<slug> --json` now prints `{ "results": [...], "explain_target": {...} }`, with the fix as a command (`next`, `argv`, `command`); without `--explain-target` the output stays a bare array. New causes: `target_not_embedded` (the page has chunks but no vectors), the failed arm named in `target_not_retrieved`, `target_collapsed` (folded into a kept row), and each arm's rank in `target_beyond_limit`. MCP is unchanged: remote callers get the diagnosis in `_meta.explain_target` without `fix`, and private targets still answer like nonexistent ones.+- `gbrain query "<q>" --explain-target <source>:<slug> --json` now prints `{ "results": [...], "explain_target": {...} }`, with the fix as a command (`next`, `argv`, `command`); without `--explain-target` the output stays a bare array. New causes: `target_not_embedded` (the page has chunks but no vectors), the failed arm named in `target_not_retrieved`, `target_collapsed` (folded into a kept row), and each arm's rank in `target_beyond_limit`. The retry argv keeps array and object arguments (`--types`, `--source-ids`, `--where` as JSON), and the `target_not_retrieved` retry adds `--expand`, a paid call that sends the query to the model, so it renders `next: ask_user`. MCP is unchanged: remote callers get the diagnosis in `_meta.explain_target` without `fix`, and private targets still answer like nonexistent ones.- `gbrain config set search.keyword_phrase true` doubles the keyword score of a chunk that matches the query as one phrase (`phraseto_tsquery`), in the keyword arm on both engines and in keyword mode. It is off in every mode bundle, so default ranking and the default knob hash do not change; opting in appends `kph=1`.### Advisory harness check on pull requests (#7673)@@ -100,6 +100,7 @@ The planned embedded core lets one server process run many brains, each opened f- New guard `scripts/check-core-world-reads.ts` with baseline `scripts/core-world-reads-baseline.tsv` (rows only fall; `--prune` lowers stale rows).- New two-engine isolation suite (`test/two-engine-isolation.serial.test.ts`, `test/e2e/two-engine-isolation.test.ts`), hermeticity test (`test/embedded-hermeticity.test.ts`, expected to fail until W7) and upgrade harness (`test/upgrade-from-previous-release.slow.test.ts`, `test/e2e/upgrade-from-previous-release.test.ts`).- New example `examples/embedded-two-brains.ts` (two PGLite brains in one process).+- An import inside its own engine scope no longer re-enters it, so a process that opened an embedded engine earlier no longer overflows the stack importing through an engine without a stable key.- Docs: [running gbrain on servers today](docs/guides/servers-today.md) and the planned [embedded core](docs/architecture/topologies.md#embedded-core-planned), including the opt-in `embedded_core` setting later waves add (nothing reads it yet) and which wave moves each piece of per-process state.- The 0.60.524.0 entry now names the command that exits 10 correctly: `gbrain trust review --accept-all`.@@ -945,7 +946,7 @@ Atom and concept write-through and the reverse-written synthesis, patterns and c**A brain moved or restored under a new host identity no longer leaves writes pending forever behind an `--accept-pending` exit 0, and a keyless re-init from a cold `GBRAIN_HOME` no longer switches an embedded brain to keyword-only (GBRA-248 W0).**-A managed source publishes only through the host that owns its checkout. When a brain moved to another machine, was restored from a backup, or ran in a container that restarted with a fresh `GBRAIN_HOME`, the new process got a new host identity, its writes queued for the old owner, and nothing said that owner was gone: the receipt read as an ordinary pending write and `--accept-pending` (or `GBRAIN_ACCEPT_PENDING=1`) exited 0, so hooks and cron treated writes that would never publish as saved. A pending receipt now flags that owner (reason `owner_unavailable` with a new `diagnostic.owner` block holding its last activity, which older clients ignore; doctor names the host) when it runs no live consumer and has been quiet for more than 24 hours, or at once on PGLite when this process holds the database file under another identity. `--accept-pending` does not cover such a write: `gbrain put`, `gbrain call`, brainstorm saves and `gbrain trust review --accept-all` exit 10 and say why. A consumer's clean stop now stamps the worktrees its host owns, so a stopped owner is not mistaken for a gone one. The owner host never sees the block, a repo-less (database-only) write never names an owner, and nothing claims or transfers ownership. New doctor check `owner_host_stale` lists the waiting writes with the owner and the read-only next step.+A managed source publishes only through the host that owns its checkout. When a brain moved to another machine, was restored from a backup, or ran in a container that restarted with a fresh `GBRAIN_HOME`, the new process got a new host identity, its writes queued for the old owner, and nothing said that owner was gone. The receipt read as an ordinary pending write and `--accept-pending` (or `GBRAIN_ACCEPT_PENDING=1`) exited 0, so hooks and cron treated writes that would never publish as saved. A pending receipt now flags that owner (reason `owner_unavailable` with a new `diagnostic.owner` block holding its last activity, which older clients ignore; doctor names the host) when it runs no live consumer and has been quiet for more than 24 hours, or at once on PGLite when this process holds the database file under another identity. `--accept-pending` does not cover such a write: `gbrain put`, `gbrain call`, brainstorm saves and `gbrain trust review --accept-all` exit 10 and say why. A consumer's clean stop now stamps the worktrees its host owns, so a stopped owner is not mistaken for a gone one. The owner host never sees the block, a repo-less (database-only) write never names an owner, and nothing claims or transfers ownership. New doctor check `owner_host_stale` lists the waiting writes with the owner and the read-only next step.`gbrain init` with no provider key in reach falls back to keyless. Run from a cold home against a database that already had an embedding model and vectors, it wrote `embedding_disabled: true` into the new config file, and the brain stopped embedding. When that fallback was implicit and the database holds vectors, init now keeps the database's stored model and width in the config file instead and prints the key to set and `gbrain embed --stale`. A fresh keyless install, a keyless brain with no vectors, an explicit `--no-embedding` and a database that already disables embeddings behave as before. New doctor check `embedding_plane_disagreement` finds brains the old behavior left in that state and prints the `gbrain init --force --embedding-model …` enable for the same model.diff --git a/docs/architecture/key-files/core-search-cjk.md b/docs/architecture/key-files/core-search-cjk.mdindex 65796b1580..d60cf6cf4e 100644--- a/docs/architecture/key-files/core-search-cjk.md+++ b/docs/architecture/key-files/core-search-cjk.md@@ -6,4 +6,4 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/core/search/cjk-keyword-sql.ts` + `src/core/engine-sql/cjk-search.ts` + `src/core/search/cjk-keyword-deadline.ts` — the CJK keyword fallback shared by both engines. `buildCJKKeywordSql(query, ctx, variant)` keeps today's strict-AND SQL byte-identical by default; `match: 'any'` (the OR fallback, #6043) qualifies a chunk on any term and orders by matched-term count, then the TF score (the count enters the score as 1000 x matched outside the source factor, so a boosted partial match never outranks an all-term chunk); `candidateIds` scores only a candidate set by joining `unnest($n::bigint[])` to `content_chunks` (an `= ANY` filter was a sequential scan). `buildCJKCandidateSql` is the unordered capped LIKE scan for ids (all-term, or any-term excluding ids already taken). `searchKeywordCJK(scoped, query, ctx, engine)` runs strict AND and, with `opts.orFallback` and 2+ terms, the OR pass only when strict AND returns fewer than `limit` rows; with `opts.cjkKeyword` (hybrid only, deadline from `search.cjk_keyword_deadline_ms`, integer ms 500..30000, default 3000) it bounds the arm: Postgres runs full scoring in its own scoped read transaction within 2/3 of the deadline (counted from before the pool wait; every statement of an attempt gets `statement_timeout` = what is left of that attempt, minus a 40 ms rollback margin), and on SQLSTATE 57014 a capped retry (`CJK_CANDIDATE_CAP` = 2000; all-term ids first, partial ids only when the all-term rows fall short) in a fresh scoped transaction with the remaining third (a fresh transaction, not a savepoint, because the driver rethrows any failed statement at the end of its transaction scope); PGLite runs the capped stage whenever `pg_class.reltuples` exceeds `PGLITE_CJK_CAPPED_CHUNKS` = 50,000. `onMeta` gets `{ incomplete, reason (timeout | candidate_budget), capped, arm_ms }` (test seams: `candidateCap`, `pgliteCappedChunks`, `fullBudgetMs`, and `onStatementBudget`, which reports each Postgres statement's timeout and the arm ... (line truncated to 2000 chars)- `src/core/search/keyword-or-rarity.ts` — rare words first in both engines' keyword OR retry. For at most `RARITY_MAX_KEYWORD_TERMS` (12) words (the title arm keeps `RARITY_MAX_TERMS` = 4: it runs one statement per word), `rareTermPagesSql` reads the pages of each word's first `RARE_TERM_CHUNK_CAP` + 1 visible chunks (brain-wide, weights only; stopwords and, on Postgres, words `commonOrTokens` in keyword-or-narrow.ts estimates past the cap are skipped); a fitting word weighs 1 / pages. `rankOrFallbackByRarity` re-runs the retry with the rarest words' OR and sorts by summed weight.- `src/core/search/keyword-identifier-probe.ts` — #7491: `keywordArmRows` builds both engines' `searchKeyword` rows from the strict rows. With `orFallback`, offset 0 and no quote or negation, a query naming an identifier (`identifierTokens`: a hash number `#412`, or a token `identifier-query.ts` recognizes: a 6+ digit run, hex id, code, email, URL or phone) and other words runs the arm's own statement once more with the AND of the identifier tokens as the match query and the any-word query as the rank query: same scope, visibility, chunk predicate, filters and candidate cap as strict. Its rows are untagged (they vote like strict rows): after the strict rows when strict matched, ahead of the relaxed rows (`keyword_relaxed`) when it did not; one row per page, cut to the limit. A failed probe adds nothing. `holdsIdentifiers` lets the title arm's OR retry (`engine-sql/titles.ts`) lead with, untagged, the titles holding every identifier. Pinned by `test/search/identifier-probe.serial.test.ts` (+ Postgres E2E) and `test/search/keyword-identifier-probe.test.ts`.-- `src/core/search/keyword-handles.ts` — GBRA-108: `slugHandles` finds the query's slug handles (a hyphenated slug-leaf token with a letter, bare or quoted on its own, at most `MAX_SLUG_HANDLES` = 16; negated tokens and tokens inside a longer quoted phrase are not handles). They resolve by exact slug basename (`handleMatchSql`, served by `idx_pages_slug_basename` like `whois`) as an arm of the keyword statement (`search/keyword-statement.ts`) under its filters, scope and visibility, so `--types`, granted sources, private pages and quarantine apply. `match: "keyword"` lists and counts the named pages first; in `searchKeyword` (orFallback, offset 0) `keywordArmRows` puts them ahead of every other row, untagged. A query without a handle builds the statements it built before. Pinned by `test/search/slug-handles.serial.test.ts` (+ Postgres E2E) and `test/search/keyword-handles.test.ts`.+- `src/core/search/keyword-handles.ts` — GBRA-108: `slugHandles` finds the query's slug handles (a hyphenated slug-leaf token with a letter, bare or quoted on its own, at most `MAX_SLUG_HANDLES` = 16; a query with a negation or a longer quoted phrase resolves none, and the strict match (`slugHandles(query, true)`) resolves them only when every term is a handle or `OR`). A failed handle or identifier-probe read adds no rows and calls `SearchOpts.onKeywordIncomplete` (`keyword_candidates_incomplete`, reason `timeout` or `provider_error`). They resolve by exact slug basename (`handleMatchSql`, served by `idx_pages_slug_basename` like `whois`) as an arm of the keyword statement (`search/keyword-statement.ts`) under its filters, scope and visibility, so `--types`, granted sources, private pages and quarantine apply. `match: "keyword"` lists and counts the named pages first; in `searchKeyword` (orFallback, offset 0) `keywordArmRows` puts them ahead of every other row, untagged. A query without a handle builds the statements it built before. Pinned by `test/search/slug-handles.serial.test.ts` (+ Postgres E2E) and `test/search/keyword-handles.test.ts`.diff --git a/src/core/interop-notices.ts b/src/core/interop-notices.tsindex d8e2e5c8c6..8eea56464c 100644--- a/src/core/interop-notices.ts+++ b/src/core/interop-notices.ts@@ -53,7 +53,7 @@ export const DEGRADED_STAGE_GUIDANCE: Readonly<Record<RecallStage, StageGuidancekeyword_relaxed_carried: { why: 'keyword matching was relaxed to find anything at all', fix: null },safe_index_pending: { why: 'some pages in scope are still being safety-indexed for agent readers and are withheld until that finishes', fix: 'doctor' },vector_candidates_incomplete: { why: 'vector search hit its candidate limit or deadline, so some semantic matches can be missing', fix: null },- keyword_candidates_incomplete: { why: 'keyword matching returned a bounded result on a large corpus (the CJK deadline or candidate cap, or common words ranked from a sample), so some keyword matches can be missing; add a rarer word or an exact phrase, narrow with source_id (the CLI source-id flag) or types, or for CJK text ask the user to raise search.cjk_keyword_deadline_ms (milliseconds, default 3000)', fix: null },+ keyword_candidates_incomplete: { why: 'keyword matching returned a bounded result on a large corpus (the CJK deadline or candidate cap, or common words ranked from a sample), or its identifier or slug-handle lookup failed (reason timeout or provider_error), so some keyword matches can be missing; add a rarer word or an exact phrase, narrow with source_id (the CLI source-id flag) or types, or for CJK text ask the user to raise search.cjk_keyword_deadline_ms (milliseconds, default 3000)', fix: null },projection_pending: { why: 'some pages in scope are not in the search index yet: recently written pages are being indexed, and image pages wait for an operator (doctor\'s text_projection_readiness check names which)', fix: 'doctor' },projection_by_design: { why: 'some image pages in scope hold protected OCR content and stay out of the search index by design; nothing is pending', fix: null },projection_status_unknown: { why: 'whether recent writes are in the search index could not be checked', fix: 'doctor' },diff --git a/src/core/pglite-engine.ts b/src/core/pglite-engine.tsindex 324897d9fc..3a751c9852 100644--- a/src/core/pglite-engine.ts+++ b/src/core/pglite-engine.ts@@ -1542,7 +1542,7 @@ export class PGLiteEngine implements BrainEngine {// the strict-AND contract. #7491: the identifier probe and the// relaxed-row tag (#3617 follow-up) live in search/keyword-identifier-probe.ts.const run = async (matchQuery: string, rankQuery: string) => (await this.db.query(keywordSql, params.map((v, i) => i === 0 ? matchQuery : i === rankIdx && !opts?.rankQuery ? rankQuery : v))).rows as Record<string, unknown>[];- return keywordArmRows({ query, strict: strict as Record<string, unknown>[], orFallback: opts?.orFallback, limit, offset, toResult: rowToSearchResult, runProbe: run,+ return keywordArmRows({ query, strict: strict as Record<string, unknown>[], orFallback: opts?.orFallback, limit, offset, toResult: rowToSearchResult, runProbe: run, onIncomplete: opts?.onKeywordIncomplete,runHandles: handles => keywordPagesImpl.searchHandlePages(async (read) => read(scopedRead(this.engineSql)), query, handles, opts, limit, {}),runRelaxed: async orQuery => rankOrFallbackByRarity({ query, rows: await run(orQuery, orQuery), limit, offset, runRare: q => run(q, orQuery),readTermPages: async terms => (await this.db.query(rareTermPagesSql(ftsLang), [terms, RARE_TERM_CHUNK_CAP])).rows as RareTermPages[] }) }).finally(settle);diff --git a/src/core/postgres-engine.ts b/src/core/postgres-engine.tsindex 4a770f1cb8..bb1d9a1251 100644--- a/src/core/postgres-engine.ts+++ b/src/core/postgres-engine.ts@@ -1222,7 +1222,7 @@ export class PostgresEngine implements BrainEngine {// relaxes; precision consumers keep the strict-AND contract. #7491: the// identifier probe and the relaxed-row tag (#3617 follow-up) live in// search/keyword-identifier-probe.ts.- return keywordArmRows<Record<string, unknown>>({ query, strict, orFallback: opts?.orFallback, limit, offset, toResult: rowToSearchResult,+ return keywordArmRows<Record<string, unknown>>({ query, strict, orFallback: opts?.orFallback, limit, offset, toResult: rowToSearchResult, onIncomplete: opts?.onKeywordIncomplete,runProbe: (match, rank) => runKeyword(match, true, rank),runHandles: handles => keywordPagesImpl.searchHandlePages((read, settings) => this.withScopedReadTransaction(opts?.sourceIds, opts?.sourceId, tx => read(scopedRead(this.engineSqlOn(tx))), { alwaysTransaction: true, jitOff: true, settings }), query, handles, opts, limit, { statementTimeout }),runRelaxed: async (orQuery) => {diff --git a/src/core/search/keyword-handles.ts b/src/core/search/keyword-handles.tsindex d5b20c1248..5c035a72bf 100644--- a/src/core/search/keyword-handles.ts+++ b/src/core/search/keyword-handles.ts@@ -9,8 +9,12 @@** A handle is a hyphenated slug-leaf token with a letter in it (`dan-example`,* `acme-example-2`), bare or quoted on its own; each quoted handle of an OR is- * resolved on its own, and a negated one (`-dan-example`) or one inside a- * longer quoted phrase is not resolved. Resolution is an exact match of the+ * resolved on its own. A query with a negation (`-dan-example`, `-draft`) or+ * a longer quoted phrase resolves no handle, so a handle never returns a page+ * the query excludes or a phrase it does not hold, and a strict keyword match+ * (`match: "keyword"` and its count) resolves handles only when every term is+ * one (a standalone handle or an OR list of them), so it keeps the AND of the+ * query's other words. Resolution is an exact match of the* slug's basename (the part after the last `/`, the whole slug for a root* page), served by idx_pages_slug_basename like `whois`. The match is a second* arm of the keyword statement (search/keyword-statement.ts) under the same@@ -25,16 +29,21 @@ const EDGE_PUNCTUATION = /^[(\[{<'\u2018\u201c]+|[)\]}>'\u2019\u201d.,;:!?]+$/gu/** At most this many handles per query (a pasted list of slugs stays one bounded index probe). */export const MAX_SLUG_HANDLES = 16;-/** The query's slug handles, lowercased, or null when it has none. */-export function slugHandles(query: string): string[] | null {+const isHandle = (token: string): boolean => token.length <= 128 && HANDLE_RE.test(token) && /[a-z]/.test(token);++/**+ * The query's slug handles, lowercased, or null when it has none. With `standalone`, only when every term is a handle+ * or OR (the strict keyword match). A negation or a quoted phrase that is not a handle resolves none.+ */+export function slugHandles(query: string, standalone = false): string[] | null {const handles = new Set<string>();for (const m of query.normalize('NFKC').matchAll(/"([^"]*)"|(\S+)/g)) {const bare = m[2];- if (bare?.startsWith('-')) continue;+ if (bare?.startsWith('-')) return null;const token = (bare === undefined ? m[1]!.trim() : bare.replace(EDGE_PUNCTUATION, '')).toLowerCase();- if (token.length > 128 || !HANDLE_RE.test(token) || !/[a-z]/.test(token)) continue;- handles.add(token);- if (handles.size === MAX_SLUG_HANDLES) break;+ if (isHandle(token)) {+ if (handles.size < MAX_SLUG_HANDLES) handles.add(token);+ } else if (bare === undefined || (standalone && token !== 'or')) return null;}return handles.size ? [...handles] : null;}diff --git a/src/core/search/keyword-identifier-probe.ts b/src/core/search/keyword-identifier-probe.tsindex 2d8c0c722b..0702421297 100644--- a/src/core/search/keyword-identifier-probe.ts+++ b/src/core/search/keyword-identifier-probe.ts@@ -22,12 +22,15 @@* strict rows when strict matched, and ahead of the relaxed rows when it did* not. Queries without such a token, a paged read (offset), precision callers* (no orFallback) and queries with a quoted phrase or a negation run exactly- * as before. A failed probe adds nothing.+ * as before. A failed probe or handle read adds no rows and reports the keyword+ * candidates incomplete (`onIncomplete`: timeout or provider_error), so a+ * failure is never a silent miss.*/import type { SearchResult } from '../types.ts';import { parseIdentifier } from './identifier-query.ts';import { buildOrFallbackWebsearchQuery, orFallbackTokens } from './sql-ranking.ts';import { slugHandles } from './keyword-handles.ts';+import { isTimeoutError } from './hybrid/degraded.ts';const HASH_NUMBER_RE = /^#(\d+)$/;@@ -87,12 +90,15 @@ export async function keywordArmRows<R>(a: {runRelaxed: (orQuery: string) => Promise<R[]>;/** GBRA-108: the pages the query's slug handles name (search/keyword-handles.ts); they lead the rows, untagged. */runHandles?: (handles: string[]) => Promise<SearchResult[]>;+ /** A probe or handle read failed: its rows are missing (SearchOpts.onKeywordIncomplete). */+ onIncomplete?: (reason: 'timeout' | 'provider_error') => void;}): Promise<SearchResult[]> {+ const failed = <T>(err: unknown): T[] => { a.onIncomplete?.(isTimeoutError(err) ? 'timeout' : 'provider_error'); return []; };const handles = a.orFallback && a.offset === 0 && a.runHandles ? slugHandles(a.query) : null;- const named = handles ? await a.runHandles!(handles).catch(() => [] as SearchResult[]) : [];+ const named = handles ? await a.runHandles!(handles).catch(failed<SearchResult>) : [];const orQuery = a.orFallback ? buildOrFallbackWebsearchQuery(a.query) : null;const probeQuery = orQuery && a.offset === 0 ? identifierProbeQuery(a.query) : null;- const probe = probeQuery ? (await a.runProbe(probeQuery, orQuery!).catch(() => [] as R[])).map(a.toResult) : [];+ const probe = probeQuery ? (await a.runProbe(probeQuery, orQuery!).catch(failed<R>)).map(a.toResult) : [];if (a.strict.length > 0 || !orQuery) return appendPages(named, appendPages(a.strict.map(a.toResult), probe, a.limit), a.limit);const relaxed = (await a.runRelaxed(orQuery)).map(r => ({ ...a.toResult(r), keyword_relaxed: true as const }));return appendPages(named, appendPages(probe, relaxed, a.limit), a.limit);diff --git a/src/core/search/keyword-statement.ts b/src/core/search/keyword-statement.tsindex a6dce7d5e3..f29713145e 100644--- a/src/core/search/keyword-statement.ts+++ b/src/core/search/keyword-statement.ts@@ -45,7 +45,7 @@ interface KeywordMatch { where: string; score: string; handleWhere?: string; hanconst FROM = `content_chunks cc JOIN pages p ON p.id = cc.page_id JOIN sources s ON s.id = p.source_id`;/** The shared match: WHERE text (with leading predicate) and the chunk score, or null when nothing can match. */-export function buildKeywordMatch(query: string, opts: SearchOpts | undefined, handles: readonly string[] | null = slugHandles(query), handlesOnly = false): KeywordMatch | null {+export function buildKeywordMatch(query: string, opts: SearchOpts | undefined, handles: readonly string[] | null = slugHandles(query, true), handlesOnly = false): KeywordMatch | null {const params: unknown[] = [];let predicate: string;let rank: () => string;diff --git a/src/core/types.ts b/src/core/types.tsindex 98c74d1c04..c58b378514 100644--- a/src/core/types.ts+++ b/src/core/types.ts@@ -1254,7 +1254,7 @@ export interface SearchOpts extends PageReadPolicy {/** #5989: bounded CJK keyword arm (deadline + meta sink); set by hybrid only (engine-sql/cjk-search.ts). */cjkKeyword?: import('./engine-sql/cjk-search.ts').CjkKeywordRun;/** GBRA-156: the Postgres keyword arm ranked a bounded sample of its matches, or its OR retry dropped common terms (search/keyword-chunk-match.ts, search/keyword-or-narrow.ts). */- onKeywordIncomplete?: (reason: 'candidate_budget') => void;+ onKeywordIncomplete?: (reason: 'candidate_budget' | 'timeout' | 'provider_error') => void;/*** v0.42 — intent-aware adaptive return-sizing. `true` enables with config/* default caps; an object overrides caps per-call; omitted/`false` = offdiff --git a/test/search/identifier-probe.serial.test.ts b/test/search/identifier-probe.serial.test.tsindex 880556de30..adf782578a 100644--- a/test/search/identifier-probe.serial.test.ts+++ b/test/search/identifier-probe.serial.test.ts@@ -25,6 +25,10 @@ import type { SearchOpts } from '../../src/core/types.ts';import { installFixtureChunks } from '../helpers/page-projection.ts';import { isolatedPersistencePostgres } from '../helpers/persistence-postgres.ts';import { testBackends } from '../helpers/test-backends.ts';+import { callSearch } from '../helpers/keyword-paging-fixture.ts';+import { identifierProbeQuery } from '../../src/core/search/keyword-identifier-probe.ts';+import { degradedStampFor, degradedStampLine } from '../../src/core/degraded-stamp.ts';+import type { HybridSearchMeta } from '../../src/core/types.ts';const DIMS = 1536;const MODEL = 'openai:text-embedding-3-large';@@ -194,6 +198,28 @@ for (const kind of testBackends()) {expect(results[0]?.slug).toBe(TARGET);for (const leaked of ['digests/other-source-412', 'digests/private-412', 'digests/unsealed-412']) expect(slugs(results)).not.toContain(leaked);});++ test.skipIf(kind !== 'pglite')('a probe that times out stamps the result degraded, never a silent miss', async () => {+ const db = (engine as unknown as { db: { query: (...args: unknown[]) => Promise<unknown> } }).db;+ const query = db.query;+ const probe = identifierProbeQuery(DIGEST_Q);+ db.query = function (this: unknown, ...args: unknown[]) {+ if ((args[1] as unknown[] | undefined)?.[0] === probe) return Promise.reject(Object.assign(new Error('canceling statement due to statement timeout'), { name: 'TimeoutError' }));+ return query.apply(this, args);+ };+ try {+ let meta: HybridSearchMeta | undefined;+ await hybridSearch(engine, DIGEST_Q, { limit: 10, expansion: false, onMeta: m => { meta = m; } });+ expect(meta?.degraded).toContainEqual({ stage: 'keyword_candidates_incomplete', reason: 'timeout' });+ const { rows, retrieval } = await callSearch(engine, { query: DIGEST_Q }, false);+ expect(retrieval.degraded).toContainEqual({ stage: 'keyword_candidates_incomplete', reason: 'timeout' });+ const stamp = degradedStampFor('search', rows, { retrieval });+ expect(stamp?.reasons).toContain('keyword_candidates_incomplete');+ expect(degradedStampLine(stamp!)).toStartWith('[gbrain degraded: keyword_candidates_incomplete');+ } finally {+ db.query = query;+ }+ });});});}diff --git a/test/search/keyword-handles.test.ts b/test/search/keyword-handles.test.tsindex 4af92a1c37..3c05d00011 100644--- a/test/search/keyword-handles.test.ts+++ b/test/search/keyword-handles.test.ts@@ -20,6 +20,19 @@ describe('slugHandles', () => {expect(slugHandles('people/dan-example')).toBeNull();});+ test('a negation or a quoted phrase anywhere in the query resolves no handle', () => {+ expect(slugHandles('dan-example -confidential')).toBeNull();+ expect(slugHandles('dan-example "missing phrase"')).toBeNull();+ expect(slugHandles('"dan-example" "renewal due"')).toBeNull();+ });++ test('a strict match resolves handles only when every term is one', () => {+ expect(slugHandles('"dan-example" OR "erin-example"', true)).toEqual(['dan-example', 'erin-example']);+ expect(slugHandles('dan-example', true)).toEqual(['dan-example']);+ expect(slugHandles('dan-example quokka', true)).toBeNull();+ expect(slugHandles('dan-example quokka')).toEqual(['dan-example']);+ });+test('at most MAX_SLUG_HANDLES handles', () => {const q = Array.from({ length: 40 }, (_, i) => 'p-' + i + 'x').join(' ');expect(slugHandles(q)).toHaveLength(MAX_SLUG_HANDLES);@@ -34,6 +47,13 @@ describe('the keyword statement', () => {}});+ test('a strict match keeps the query\'s other words: no handle arm beside them', () => {+ for (const q of ['dan-example quokka', 'dan-example -procurement', 'dan-example "renewal due"']) {+ expect(buildKeywordPagesStatement(q, undefined, { limit: 10 })!.sql).not.toContain('UNION');+ expect(buildKeywordCountStatement(q, undefined)!.sql).not.toContain('UNION');+ }+ });+test('a handle adds the basename arm under the same filters', () => {const st = buildKeywordPagesStatement('"dan-example"', { types: ['person'] }, { limit: 10 })!;expect(st.sql).toContain('UNION ALL');@@ -43,9 +63,10 @@ describe('the keyword statement', () => {describe('keywordArmRows with handles', () => {const row = (page_id: number) => ({ page_id, slug: 'p' + page_id }) as unknown as SearchResult;- const run = (query: string, o: { strict?: number[]; offset?: number; orFallback?: boolean; handles?: () => Promise<SearchResult[]> } = {}) => {+ const run = (query: string, o: { strict?: number[]; offset?: number; orFallback?: boolean; handles?: () => Promise<SearchResult[]>; incomplete?: string[] } = {}) => {const calls: string[] = [];return keywordArmRows<SearchResult>({+ onIncomplete: reason => o.incomplete?.push(reason),query, strict: (o.strict ?? []).map(row), orFallback: o.orFallback ?? true, limit: 5, offset: o.offset ?? 0, toResult: r => r,runProbe: () => Promise.resolve([]),runRelaxed: () => Promise.resolve([row(7)]),@@ -67,4 +88,12 @@ describe('keywordArmRows with handles', () => {expect((await run('dan-example', { strict: [1], orFallback: false })).calls).toEqual([]);expect((await run('dan-example', { strict: [1], handles: () => Promise.reject(new Error('boom')) })).rows).toEqual([[1, false]]);});++ test('a failed handle read reports the keyword candidates incomplete', async () => {+ const incomplete: string[] = [];+ const timeout = Object.assign(new Error('canceling statement due to statement timeout'), { name: 'TimeoutError' });+ await run('dan-example', { strict: [1], handles: () => Promise.reject(timeout), incomplete });+ await run('erin-example', { strict: [1], handles: () => Promise.reject(new Error('boom')), incomplete });+ expect(incomplete).toEqual(['timeout', 'provider_error']);+ });});diff --git a/test/search/slug-handles.serial.test.ts b/test/search/slug-handles.serial.test.tsindex 094cf68259..3448065ee3 100644--- a/test/search/slug-handles.serial.test.ts+++ b/test/search/slug-handles.serial.test.ts@@ -123,6 +123,24 @@ for (const kind of testBackends()) {expect(slugs(rows)).toEqual(['people/dan-example']);});+ test('<handle> -term excludes a page that contains the term, in keyword mode and the hybrid keyword arm', async () => {+ const q = 'dan-example -procurement';+ const { rows, retrieval } = await callSearch(engine, { query: q, match: 'keyword' }, false);+ expect(slugs(rows)).not.toContain('people/dan-example');+ expect(slugs(rows)).not.toContain('companies/northwind-example');+ expect(retrieval.total).toBe(rows.length);+ expect(slugs(await engine.searchKeyword(q, { limit: 20, orFallback: true }))).not.toContain('people/dan-example');+ });++ test('a quoted phrase beside a handle is respected, and so are the other words of a strict match', async () => {+ const phrase = await callSearch(engine, { query: 'dan-example "renewal due"', match: 'keyword' }, false);+ expect(slugs(phrase.rows)).toEqual(['companies/northwind-example']);+ expect(phrase.retrieval.total).toBe(1);+ expect(slugs(await engine.searchKeyword('dan-example "renewal due"', { limit: 20, orFallback: true }))).not.toContain('people/dan-example');+ const other = await callSearch(engine, { query: 'dan-example quokka', match: 'keyword' }, false);+ expect(slugs(other.rows)).toEqual([]);+ });+test('precision callers (no orFallback) keep the strict-AND contract', async () => {expect(slugs(await engine.searchKeyword(Q, { limit: 20 }))).not.toContain('people/dan-example');});