Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Questions about the past see earlier values and when each was told (GST-2859) (#9573)

Garry Tan163347dd9a5c
diff --git a/behavior-changes.d/facts_block_contested_gbra574.md b/behavior-changes.d/facts_block_contested_gbra574.md
new file mode 100644
index 0000000000..f200beef68
--- /dev/null
+++ b/behavior-changes.d/facts_block_contested_gbra574.md
@@ -0,0 +1,4 @@
+---
+kind: fix
+---
+The query facts block now marks a fact another saved fact disputes, as recall already did. When a fact is in a pending gbrain decide supersede proposal, its row ends with (contested by #ID) naming the other fact, but only when the caller can read that other fact (remote callers see world facts only; private provenance and the trust floor apply). If the lookup fails, the rows carry no label and the response reports the degraded stage contested_unavailable.
diff --git a/behavior-changes.d/facts_block_history_gbra574.md b/behavior-changes.d/facts_block_history_gbra574.md
new file mode 100644
index 0000000000..60522acec2
--- /dev/null
+++ b/behavior-changes.d/facts_block_history_gbra574.md
@@ -0,0 +1,4 @@
+---
+kind: add
+---
+When a query asks about the past, the facts block now shows the named person's or company's earlier values too. A question with a history word (before, earlier, previously, first, used to, in order and similar) or a date that has already passed, about one entity the brain has a page for, also pulls that entity's ended facts: facts a newer fact replaced, and facts whose valid_until has passed. Each keeps its own dates in its header, for example [observed 2025-01-16; valid 2025-01-16 to 2025-03-02], inside the block's usual share of the token budget, oldest first beside the current facts. A forgotten or withdrawn fact never appears, nor one from a page that was deleted and purged, and a remote caller sees only the world-visible facts it could already read. A question without such a cue gets exactly what it got before.
diff --git a/behavior-changes.d/facts_block_told_after_gbra574.md b/behavior-changes.d/facts_block_told_after_gbra574.md
new file mode 100644
index 0000000000..d696853b5f
--- /dev/null
+++ b/behavior-changes.d/facts_block_told_after_gbra574.md
@@ -0,0 +1,4 @@
+---
+kind: add
+---
+When a query names one date, each fact row in the facts block now says whether it was told after that date. A fact said after the date ends its header with "; told after DATE", for example [observed 2025-06-30; valid 2025-02-15 to unknown; told after 2025-04-01], and a fact whose saying date is unknown ends it with "; learn date unknown", so neither reads as known on that day. A question that names no date, or several, gets the headers it got before. Dates are read by the same fixed English grammar gbrain uses for time ranges in queries.
diff --git a/changelog.d/gbra574-b1-history-facts.md b/changelog.d/gbra574-b1-history-facts.md
new file mode 100644
index 0000000000..932995f363
--- /dev/null
+++ b/changelog.d/gbra574-b1-history-facts.md
@@ -0,0 +1,12 @@
+**Questions about the past now see earlier values in the facts block, with when each was told.**
+
+<!-- behavior-change: facts_block_history_gbra574 -->
+<!-- behavior-change: facts_block_told_after_gbra574 -->
+<!-- behavior-change: facts_block_contested_gbra574 -->
+
+### Added
+- On a history cue (a history word, or a date that has passed), the query facts block also takes the named entity's ended facts (superseded, or past their `valid_until`), each with its own validity window. Forgotten and withdrawn facts, and facts from a deleted and purged page, never appear, and the caller's read policy applies as before.
+- When a question names one date, each fact header in the block says `; told after DATE` for a fact said after it and `; learn date unknown` when the saying date is unknown.
+
+### Fixed
+- The facts block shows recall's contested label: `(contested by #ID)` on a fact in a pending supersede proposal whose other fact the caller can read; a failed lookup reports `contested_unavailable`.
diff --git a/docs/architecture/key-files/core-search-2.md b/docs/architecture/key-files/core-search-2.md
index 0d2d02469c..757e827a00 100644
--- a/docs/architecture/key-files/core-search-2.md
+++ b/docs/architecture/key-files/core-search-2.md
@@ -17,7 +17,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- Evidence date headers (`search/evidence-date.ts`) and the tail trim (`search/evidence-tail-trim.ts`): [Core Search (evidence blocks)](core-search-evidence.md).
- `src/core/search/entity-anchor.ts` — entity-anchored retrieval: `entityAnchoredPages` (the entity page plus up to 10 pages that link to it by a ranking link type or name it as a word, newest by `COALESCE(effective_date, updated_at)`; question/synthesis/pinned-question pages excluded) and `prefixAnchoredPages`, shared by pinned-question refresh (`questions/refresh.ts` `anchoredSlugs`) and the `query`/`search` ops; `asksForCurrentState` (deterministic cue regex), `namedEntity` (exactly one `isFactEntityPage` page whose title `isTitleMentionedInQuery` matches, the title match before the read-policy filter; a title inside a longer matched title is the same mention); `applyEntityAnchoring` (anchored rows first, at most half the row count, organic rows of the same page moved up, missing pages read through `getChunkWindows` under the caller's scope, rows stamped `entity_anchored`, token budget re-applied, fail-open); `entityAnchoringEnabled` (`search.entity_anchoring`, default off). Tests: `test/search-entity-anchor.test.ts`. Gates: `docs/eval/decisions/entity-anchoring-query/`.
- The facts arm, temporal fact reserve, facts block and fact source pages (`search/facts-arm.ts`): [Core Search (evidence blocks)](core-search-evidence.md).
-- `src/core/search/fact-relevance.ts` — question relevance for saved facts, shared by recall's `question` (`facts/question-recall.ts`), the temporal fact reserve and (pool only) the facts arm. `collectFactCandidates`: one bounded pool under recall's read policy (source scope, active and not superseded, audit rows excluded, quarantine and rederive hiding through `projectionEligibleSql`, the trust floor, world-only facts when the scope says `worldOnly` (`worldOnlyFacts`), `privateProvenanceFilterFragment` when `excludePrivate`) plus recall's filters inside every arm before its LIMIT (`(source_id, entity_slug)` pairs, `source_session`, event-time since, escaped `ILIKE` grep); arms, run concurrently and merged in a fixed order, are keyword FTS (`factsFtsDocument`, served by `idx_facts_fts`), cosine (cast to the facts column type, filtered on model only so the HNSW index serves it, a stale hash or other dimensions yielding no similarity; `ef_search` sized to the depth and pgvector's iterative scan when `hnswIterativeScan` is set) and the named entity page's facts in its own source; depths are bound parameters; `cosineForAll` scores every candidate's cosine whichever arm found it; `distinctiveTerms` (recall's question, GST-1304) searches a question over `MAX_QUERY_TERMS` (12) content terms on its last 24 and returns in `terms` the 12 of those the fewest candidates hold (`heldTerms`; later word first on a tie), which `scoreFactCandidates` takes as its third argument, so a provider preamble no fact holds stops filling the share's denominator. A missing embedding column or other dimensions skips the cosine arm; any other DB error throws. `scoreFactCandidates`: cosine + term share + 0.1 when dated (terms match on their stems under the brain's full-text config, one `to_tsvector` read per pool, whole words when it fails; a stem-only match adds 0.9 of an exact one to the score but counts fully in the share; ISO dates, years and auxiliaries count on neither side), the share's denominator growing past `TERM_STUFFING_RATIO` times the question's terms for a long fact; order score, newest valid_from, id. `admitted`: the `reserve` rule (cosine >= 0.5 or share >= 0.34) or the `facts_arm` rule (cosine >= 0.6, half the terms, or the named entity). `countUncomparableFacts` counts the pool's facts the cosine arm cannot compare, per source: candidates from `idx_facts_unembedded` and `idx_facts_embedding_model` first, the read policy on those rows only. The keyword arm and the count run under `customPlan` (`plan_cache_mode = force_custom_plan` in a transaction): a cached generic plan cannot see the source arrays and nests the policy anti-joins over every match. p95 at 100k facts: Postgres 51 ms local / 65 ms remote, PGLite 152 / 139 ms. Tests: `test/fact-relevance.test.ts`, `test/recall-question.test.ts`.
+- `src/core/search/fact-relevance.ts` — question relevance for saved facts, shared by recall's `question` (`facts/question-recall.ts`), the temporal fact reserve and (pool only) the facts arm. `collectFactCandidates`: one bounded pool under recall's read policy (source scope, active and not superseded, audit rows excluded, quarantine and rederive hiding through `projectionEligibleSql`, the trust floor, world-only facts when the scope says `worldOnly` (`worldOnlyFacts`), `privateProvenanceFilterFragment` when `excludePrivate`) plus recall's filters inside every arm before its LIMIT (`(source_id, entity_slug)` pairs, `source_session`, event-time since, escaped `ILIKE` grep); arms, run concurrently and merged in a fixed order, are keyword FTS (`factsFtsDocument`, served by `idx_facts_fts`), cosine (cast to the facts column type, filtered on model only so the HNSW index serves it, a stale hash or other dimensions yielding no similarity; `ef_search` sized to the depth and pgvector's iterative scan when `hnswIterativeScan` is set) and the named entity page's facts in its own source (with `history`, GBRA-574, that arm also takes the entity's ended facts, `ENDED_FACT_SQL`: superseded or past `valid_until`, never withdrawn, forgotten or from a purged page); depths are bound parameters; `cosineForAll` scores every candidate's cosine whichever arm found it; `distinctiveTerms` (recall's question, GST-1304) searches a question over `MAX_QUERY_TERMS` (12) content terms on its last 24 and returns in `terms` the 12 of those the fewest candidates hold (`heldTerms`; later word first on a tie), which `scoreFactCandidates` takes as its third argument, so a provider preamble no fact holds stops filling the share's denominator. A missing embedding column or other dimensions skips the cosine arm; any other DB error throws. `scoreFactCandidates`: cosine + term share + 0.1 when dated (terms match on their stems under the brain's full-text config, one `to_tsvector` read per pool, whole words when it fails; a stem-only match adds 0.9 of an exact one to the score but counts fully in the share; ISO dates, years and auxiliaries count on neither side), the share's denominator growing past `TERM_STUFFING_RATIO` times the question's terms for a long fact; order score, newest valid_from, id. `admitted`: the `reserve` rule (cosine >= 0.5 or share >= 0.34) or the `facts_arm` rule (cosine >= 0.6, half the terms, or the named entity). `countUncomparableFacts` counts the pool's facts the cosine arm cannot compare, per source: candidates from `idx_facts_unembedded` and `idx_facts_embedding_model` first, the read policy on those rows only. The keyword arm and the count run under `customPlan` (`plan_cache_mode = force_custom_plan` in a transaction): a cached generic plan cannot see the source arrays and nests the policy anti-joins over every match. p95 at 100k facts: Postgres 51 ms local / 65 ms remote, PGLite 152 / 139 ms. Tests: `test/fact-relevance.test.ts`, `test/recall-question.test.ts`.
- `src/core/search/query-arms.ts` — `applyQueryArms`: the `query` op's post-retrieval arms in order (entity anchoring, fact source pages, then the facts arm), each behind its own key (the facts arm default on, the rest off); a query whose caller passed `token_budget` takes the facts block (`search.query_facts_block`, default on; at most `limit` rows, scored at the top page's score; #8411) or, with a temporal cue, the temporal fact reserve (`search.temporal_fact_reserve`) instead of the facts arm; with all off it returns the rows untouched.
- `src/core/search/image-vector-presence.ts` — `brainHasImageVectors` (one `EXISTS embedding_image IS NOT NULL` probe per engine, cached 60 s, fail-open to true). `hybrid/arms.ts` uses it so an inferred image/both modality on a brain with no image embeddings stays text: no multimodal embed, keyword arm kept, no `vector_arm_failed`; the opt-in LLM modality tie-break still runs, and an image or both answer is demoted to text. An explicit `crossModal` is honored. Tests: `test/search-image-arm-text-only.test.ts`, `test/cross-modal-hybrid-integration.serial.test.ts`.
diff --git a/docs/architecture/key-files/core-search-evidence.md b/docs/architecture/key-files/core-search-evidence.md
index 25a90f7416..523b7dae17 100644
--- a/docs/architecture/key-files/core-search-evidence.md
+++ b/docs/architecture/key-files/core-search-evidence.md
@@ -6,5 +6,5 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/core/search/evidence-date.ts` — C1 dated evidence blocks: the fixed header grammar (`[observed YYYY-MM-DD|unknown]` for page blocks; `[observed YYYY-MM-DD|unknown; valid FROM to UNTIL]` for facts, `observed` from the source page (`source_markdown_slug`) via `factObservationDates` under the caller's page read policy; a failed read renders `unknown` and the caller reports `fact_observed_date_unavailable`), `pageObservationDate` (effective-date precedence with `event_date` removed and no row-timestamp fallback; mirrors #6020's `resolveObservationDate`, the seam to swap once it lands), `formatBrainDay` from `effective-date.ts` (midnight UTC renders as written, other instants in `brain.timezone`; the one function think's `<page date>` also renders through, while the header's `observed` stays when the text was said, never the content date), `loadPageDateHeaders` (one `pages` read per delivery; only the derived day leaves it) `evidenceDateHeaderEnabled` (`search.evidence_date_header`, default off) and `evidenceTitlesEnabled` (`search.evidence_titles`, GBRA-205, default off: with the header on, `blockDateHeaders` ends a page block's line with its title via `titledPageHeader`, fact headers unchanged; `evidenceTitle` removes bidi overrides, isolates and marks and blanks angle brackets and C0/C1 controls in both sinks; think's `<page>` tag gets a `title` attribute). Tests: `test/evidence-date-header.test.ts`, `test/search-8k-conversion.test.ts`.
- `src/core/search/evidence-tail-trim.ts` — the protected tail trim (`search.evidence_tail_trim`, default off, GBRA-156). `resolveEvidencePlan` sets `EvidencePlan.tailTrim` only for `unit: auto` with the key on; `deliverEvidence` calls `trimEvidenceTail(results, opts.query)` on the rank-order delivered rows after redaction and before the token totals, and only when `DeliverOptions.query` is set (`search`/`query` pass `p.query`; the library `assembleEvidenceForHits` passes `input.query` and frozen hits may carry `score`; the `assemble_evidence` op passes neither, so the trim never runs there). Rows past `TAIL_TRIM_PROTECTED` = 3 that are whole-conversation blocks (`delivered.reason` `conversation_type`/`conversation_slug`) and score under `TAIL_TRIM_SCORE_FRACTION` = 0.5 of rank one are dropped, unless their `chunk_text` holds at least `TAIL_TRIM_TERM_FRACTION` = 0.8 of rank one's share of the query's terms (`queryTerms`: letter/digit runs, stopwords and single characters dropped, cut to six characters). Rank one's score must be a positive finite number and every row's finite, or nothing changes. `delivery.tail_trim` is `{ dropped, kept_by_query_terms }`; `dropped_reasons.tail_trim` counts drops. Pinned by `test/evidence-tail-trim.test.ts` (the knowledge-update regression case).
- `src/core/search/transcript-quote.ts` — quotes third-party text on every read that hands it to a model (#7600, #8042). The signal is stored metadata, in one place: `isQuotedPageType` (every concrete type in `facts/conversation-types.ts` `ALLOWED_TYPE_ALIASES` plus `transcript` and `chat`) for page rows, and for fact rows `isQuotedFactSource` (`facts.source` starting `cli:extract-conversation-facts`, the prefix in `facts/audit-sources.ts`) or `factsFromQuotedPages` (one bounded read, same source: the fact's `source_markdown_slug` page, a `derivation_inputs` page edge the backstop and extract_facts already write, or for a `sync:import` / `mcp:put_page` fact the page its `source_session` names (`sync:<slug>`, `put_page:<slug>`, covering facts saved before edges or rebuilt from git) has a quoted type; it writes nothing, and a lookup failure withholds `saved_facts` (stage `saved_facts_withheld`) and remote recall facts (`facts_degraded.reason`) and fails the delta facts arm; the facts arm carries both on `fact_row.source`/`from_quoted_page`, stripped by `factRowOutput`; marker `fact <id>`); nothing reads the text to decide, so other rows come back byte-for-byte unchanged. `quoteLabel` is the row decision. GST-687: for an untrusted (remote, `ctx.remote !== false`) reader the signal also includes the stored trust tier: `quotesTier` (below `OWNER_TIER_FLOOR`, `operator_curated`; a missing tier reads as `unknown`, so it fails closed) and `quotesStored` (page type or tier) quote agent-written, tool-data, external and unverified-origin text. `quoteLabel(row, untrusted)`, `deliveredQuoteText`, `fenceTranscriptRows` and `quoteFacts(engine, facts, untrusted)` take that flag (`quoteFacts` reads each fact's stored tier from `facts`, never from the caller's row); only third-party types get tool calls summarized. `quotePageText` and `pageTypesById` serve reads whose rows name only a page (`get_timeline`, `get_chunks`). Local reads are unchanged. Beyond search: `recall` (remote callers: neutralize + fence its results before packing, `quoteFacts` its facts), think's pages block (`think/gather.ts renderPagesBlockDetailed`: neutralize before the excerpt, fence what it renders, every run), `saved_facts` in search/query meta, remote `delta` facts and `_meta.brain_hot_memory` (`quoteFacts`, which also quotes a representative when a collapsed member qualifies), remote `get_page known_as_of` and `get_versions` bodies and diffs (`ops/known-as-of.ts intervalView`, `ops/admin.ts`), and remote `get_page`/`fetch` (`ops/get-page-projection.ts projectGetPage` `quote`, which `projectFetchText` reuses: compiled_truth, timeline and `content` fenced without the tool-call summary, so text inside stays byte-exact; windows fenced in `get-page-body.ts envelopeText`; `quoted: "transcript"`; `quotesBody(ctx, page, trust)` also quotes a page below the owner's tier, and `neutralizesBody` summarizes tool calls only on a third-party page's reading shapes, never for the thin client, with `include_content` and `view: markdown` keeping the stored bytes inside the fence). Remote `get_timeline`, `get_chunks`, `search_exact`, think's extractive fallback, `context_pack` and `list_write_requests`/`get_write_request` outcome text quote by tier too, and so (#8377) do the `chronicle_*` reads and `volunteer_chronicle`'s timeline (`ops/chronicle.ts remoteTimeline`, each row by its own page; `quoteTimelineRows` fences a row's free-text `source` with summary and detail, #8384, and an event row's `kind` is fenced by its event page's type and tier), its ontology values, `ontology_get`'s and `ontology_conflicts`' (`remoteOntology`, `quoteFacts` by `fact_id`; remote `ontology_propose` drops a fact fence), `takes_list`/`takes_search` (`ops/takes.ts quoteTakes`), a quoted page's title, frontmatter strings and tags (`quotedPageMeta`, also `get_tags`; remote `add_tag`/`remove_tag` drop a fence naming the page; `include_content` and fetch `text` fence the whole serialized markdown), a quoted search/query/assemble_evidence/recall row's title (`deliveredQuoteTitle`, which `capEvidenceToBudget` counts), a `context_pack` card below the owner's tier rendering its title under the card's trust label, the per-turn push hook's hot facts and the pushed context pack (`untrusted: true`); `context_pack` counts entity facts a failed quote lookup withholds in `suppressed`. Remote `remember` drops a fact fence (`unquoteFactText`) and `add_timeline_entry` a fence naming its page, so a copied-back entry keeps its replay key. Remote `put_page` (`ctx.remote !== false`) runs `unquoteTranscriptText` over `content` (`persistence/page-mutations.ts unquotedPutContent`, after the replay check so the request digest covers what the caller sent; slug lowercased as admission does) when the stored page or the incoming frontmatter has a quoted type or the stored page is below the owner's tier (an owner-tier page keeps a fence naming it only when its stored body already holds one), removing only a marker naming that slug and its own fence (lines may end in CRLF), so get → edit → put writes the body and a note's fence-like text is kept (`unclosed`: a fence opening the content, after blank lines at most, whose closing line the edit replaced is removed too, #8377, #8384; `closingLine` takes the first line that is exactly the read's fence outside a code block the text opens itself, so an agent's added block stays whole; every search of one text shares a budget of eight times its length, past which the rest is kept as written, so many unclosed markers stay linear). Remote `put_page` content holding a tool-call summary that a whole read of the stored conversation page never produces, or fewer of a call's summaries than the page holds (`holdsSummarizedToolCalls`), refuses `invalid_params` and stores nothing; only summaries outside the text's own tool-call blocks count, and a named summary the page never wrote is admitted while every stored call stays (#8377). A thin client paging a quoted page (`cli/page-render.ts spoolWholePage`) unquotes each window before checking size and sha256, then prints the page (and `--json` content) inside one quote fence (`transcriptFence`). Trusted local get_page/fetch/put_page, recall and delta are unchanged. `searchOutput` (`ops/search.ts`) runs `neutralizeTranscriptRows` before the snippet and evidence caps and `fenceTranscriptRows` after them, on copies, after ranking and evidence delivery; `assembleEvidenceForHits` (`evidence-delivery.ts`, so the `assemble_evidence` op and gbrain-evals) does the same around `capEvidenceToBudget`. That cap counts a conversation row as delivered, inside its fence (`deliveredQuoteText`, its `quote` flag; deliverEvidence's own cap, which recall uses, counts the text as returned), so an explicit `auto` token budget still holds, `snippet_chars` included (a rank-one row is kept even when its fence alone exceeds a very small budget); a row it cuts is shortened until the fenced text fits, and other rows are cut exactly as before. The neutralizer replaces each tool-call block with `[tool call: <name>, arguments omitted]` (`[tool calls: a, b, …]` for several): an object typed `tool_use`, `server_tool_use`, `mcp_tool_use`, `function_call`, `custom_tool_call`, `tool_call` or `toolCall` (the enclosing object, found by walking back over candidate `{` with a string-aware scan), the value of a `tool_calls` array or a `function_call` or Gemini `functionCall` object (the message object and its `content` or `parts` stay), and an XML-style `function_calls`, `invoke`, `tool_use` or `tool_call` element with its `parameter` children, namespace prefix optional (the name from `invoke name="…"`, a `<name>` child, or the root `name` of the JSON object a `tool_call` opens with; result elements are never matched, and a tag counts as markup only when it ends its line (LF or CRLF) or the text, runs into the next tag, is an `invoke` with a name, or is a `tool_call` followed by `{`; blocks separated only by whitespace merge). The XML pass runs before the JSON pass. Text between evidence omission lines is read separately; a block cut by the end of the text is replaced to the end or the next message anchor line (an open-ended block never swallows a later message), one whose `{` lies before the text from the text start (or the last message anchor) when the type is followed by `,` or `}`, and prose that only names the shape is left alone. An XML block whose close lies past the text runs to the end or the next message anchor line; a closing tag with no opener (or a `parameter` opener outside a call) starts at the text start or the last message anchor. A trailing evidence cut marker and a leading `[observed …]` date header stay outside any block. Message anchor lines may end in CRLF. Scanning is linear: anchors are indexed once, and past a per-text work budget the rest of a message is summarized (fails closed). Names outside `[A-Za-z0-9_.:/-]{1,64}` are dropped. The fence is a marker line naming the slug (`[`, `]`, `;` and line breaks shown as `?`), then a code fence of at least three backticks, one longer than the longest run in the text; the row gets `quoted: "transcript"` (kept in lean rows). `rowPreview` is the CLI human line: `[quoted transcript]` and the start of the fenced text. Stored pages, chunks, ranking and scores are unchanged; delivered `match_spans` are remapped to the returned text, and `tokens`, `tokens_delivered` and `budget_used` count the fenced text (`fenceTranscriptRows` with a recount). Tests: `test/search/transcript-quote.test.ts`, `test/search-transcript-quote.test.ts` (ChatGPT export through the importer, with a JSON and an XML call; remote MCP `search`/`query`/`assemble_evidence` and CLI human/`--json`, both engines), `test/search-transcript-quote-budget.test.ts` (budget, spans and snippet cap through the ops), `test/search-transcript-quote-coverage.test.ts` (#8042 matrix: slack, imessage, email, meeting and conversation pages plus a conversation-extracted fact against a note and a remembered fact, plus backstop facts linked to a synced slack page by a derivation edge or only by their sync session, and one derived from a note, a failed lookup withholding facts, a retried retype put, over remote search, query, saved_facts, assemble_evidence, recall, get_page body/content/window, local get_page, the get→put round trip (a note's fence-like text, a mixed-case slug), thin-client paging of a 12,000-line slack page, fetch, think's prompt, delta, hot memory, and get_page known_as_of / get_versions bodies and diff, both engines), `test/search-transcript-quote-tiers.test.ts` (GST-687: every placement and read surface by tier, both engines) and `test/search-transcript-quote-legacy-claim.test.ts` (a legacy note is quoted, raw again after claim and backfill, both engines), `test/search-transcript-quote-followups.test.ts` (#8377: the chronicle, takes and page title/frontmatter reads, hook-injected facts, and the copied-back writes, red on master, both engines) and `test/trust-keep-maintenance-reimport-8352.test.ts` (#8352: maintenance re-imports keep an owner note's tier, both engines) and `test/search-transcript-quote-8384.test.ts` (#8384: whole-markdown round-trip edges, timeline source, ontology values, the `quoted_unverified_origin` notice from `get-page-projection.ts unverifiedOriginNotice`, both engines) and `test/search-transcript-quote-8384b.test.ts` (#8384 wave 3: CRLF whole-markdown, chronicle `kind`, search row and card titles, tags, a fenced value next to a naive datetime, both engines).
-- `src/core/search/facts-arm.ts` — the `query` facts arm behind `search.query_facts_arm` (default on since gates 1b and 2 passed; `false` turns it off). `matchQueryFacts` reads the candidate pool from `fact-relevance.ts` (active facts under recall's read policy) and matches them by query-embedding cosine (`FACT_COSINE_MIN` 0.6, the embedding `hybridSearch` already computed, via `HybridSearchOpts.onQueryEmbedding`) or by query-term share (half the terms, substring match) or a named entity (in that page's source), newest `valid_from` first, at most `MAX_FACT_ROWS` (3). `applyFactsArm` adds them as `fact_row` rows in spare capacity only: free slots under the caller's row count, and whole rows that fit in what the page rows leave of the token budget; a page row is never displaced `factRowOutput` strips page fields (slug, id, type, chunk_id) from fact rows on output, leaving `result_type: 'fact'`, `fact_id`, `follow_up` (`recall` by entity, or `grep` without one) and `page_slug` when the caller can read the entity page (`readableEntityPages`); and stamps `superseded_claim` on page rows whose typed `claim_metric` (plus `claim_period` when both carry it) a newer active fact covers. No model call. Tests: `test/search-facts-arm.test.ts`. Gates and verdict: `docs/eval/decisions/query-facts-arm/`. Fact reserves: `applyFactReserve` serves two policies. The temporal fact reserve (`applyTemporalFactReserve`, `search.temporal_fact_reserve`, default off): `hasTemporalCue` (the preregistered word, phrase, ISO date and month-name regex), candidates from `collectFactCandidates` (50 cosine, 50 keyword, 20 entity facts, cosine for every candidate), scored by the shared `scoreFactCandidates` and kept by its `reserve` admission rule (fail-open on any error), packed into 15% of the token budget and 30% of the row count (1-20), rendered as fact rows whose text starts with `factDateHeader` (evidence delivery adds no second header), oldest first after the pages. Tests: `test/search-temporal-fact-reserve.test.ts`. Gates: `docs/eval/decisions/temporal-fact-reserve/`. The facts block (`applyFactsBlock`, `search.query_facts_block`, GBRA-205, default on since the held-out gate passed; `false` or a config read error turns it off): the same facts for every query whose caller passed `token_budget` (the no-budget evidence plan's implicit budget does not run it, #8411), up to 22% of the budget, 40 rows and the caller's `limit`, oldest first ahead of the pages at the top page's score (never above it), adding rows; copies of one claim (`collapseFactReads`, `facts/capture-dedup.ts`) take one row dated as first stated, followed by `(stated N times, last DATE)`; copies are ordered by when each was said (its observed date, else its write date, then id). Fact source pages (`applyFactSourcePages`, `search.fact_source_pages`, GBRA-205, default off): the conversations (`facts.source_markdown_slug`, never the entity page) of the best-matching admitted facts, at most 2 not already present, read through `getChunkWindows` under the caller's read scope and placed after the top 3 rows; the row count never grows. Tests: `test/search-8k-conversion.test.ts`.
+- `src/core/search/facts-arm.ts` — the `query` facts arm behind `search.query_facts_arm` (default on since gates 1b and 2 passed; `false` turns it off). `matchQueryFacts` reads the candidate pool from `fact-relevance.ts` (active facts under recall's read policy) and matches them by query-embedding cosine (`FACT_COSINE_MIN` 0.6, the embedding `hybridSearch` already computed, via `HybridSearchOpts.onQueryEmbedding`) or by query-term share (half the terms, substring match) or a named entity (in that page's source), newest `valid_from` first, at most `MAX_FACT_ROWS` (3). `applyFactsArm` adds them as `fact_row` rows in spare capacity only: free slots under the caller's row count, and whole rows that fit in what the page rows leave of the token budget; a page row is never displaced `factRowOutput` strips page fields (slug, id, type, chunk_id) from fact rows on output, leaving `result_type: 'fact'`, `fact_id`, `follow_up` (`recall` by entity, or `grep` without one) and `page_slug` when the caller can read the entity page (`readableEntityPages`); and stamps `superseded_claim` on page rows whose typed `claim_metric` (plus `claim_period` when both carry it) a newer active fact covers. No model call. Tests: `test/search-facts-arm.test.ts`. Gates and verdict: `docs/eval/decisions/query-facts-arm/`. Fact reserves: `applyFactReserve` serves two policies. The temporal fact reserve (`applyTemporalFactReserve`, `search.temporal_fact_reserve`, default off): `hasTemporalCue` (the preregistered word, phrase, ISO date and month-name regex), candidates from `collectFactCandidates` (50 cosine, 50 keyword, 20 entity facts, cosine for every candidate), scored by the shared `scoreFactCandidates` and kept by its `reserve` admission rule (fail-open on any error), packed into 15% of the token budget and 30% of the row count (1-20), rendered as fact rows whose text starts with `factDateHeader` (evidence delivery adds no second header), oldest first after the pages. Tests: `test/search-temporal-fact-reserve.test.ts`. Gates: `docs/eval/decisions/temporal-fact-reserve/`. The facts block (`applyFactsBlock`, `search.query_facts_block`, GBRA-205, default on since the held-out gate passed; `false` or a config read error turns it off): the same facts for every query whose caller passed `token_budget` (the no-budget evidence plan's implicit budget does not run it, #8411), up to 22% of the budget, 40 rows and the caller's `limit`, oldest first ahead of the pages at the top page's score (never above it), adding rows; copies of one claim (`collapseFactReads`, `facts/capture-dedup.ts`) take one row dated as first stated, followed by `(stated N times, last DATE)`; copies are ordered by when each was said (its observed date, else its write date, then id). GBRA-574: on `hasHistoryCue` the pool also takes the named entity's ended facts (`collectFactCandidates` `history`, `ENDED_FACT_SQL`: superseded or past `valid_until`, the most recent first, never withdrawn or from a purged page); `questionDate` adds `; told after DATE` or `; learn date unknown` to each header; `withDecideContested` adds `(contested by #<id>)`, and a failed lookup sets `fact_row.contested_unavailable` (degraded `contested_unavailable`). Tests: `test/facts-block-history-gbra574.test.ts`. Fact source pages (`applyFactSourcePages`, `search.fact_source_pages`, GBRA-205, default off): the conversations (`facts.source_markdown_slug`, never the entity page) of the best-matching admitted facts, at most 2 not already present, read through `getChunkWindows` under the caller's read scope and placed after the top 3 rows; the row count never grows. Tests: `test/search-8k-conversion.test.ts`.
- `src/core/search/remote-page-cap.ts` — GBRA-156: the default distinct-page cap of a remote `search`/`query` that names no `limit` (and no `offset`). `remotePageCap(ctx, p)` reads `search.remote_page_cap` (default `DEFAULT_REMOTE_PAGE_CAP`, `0` = off; null for trusted local callers and `viaSubagent` host tool calls); `capVectorOnlyPages(rows, cap)` keeps every page with lexical evidence (`keyword_hit`, strict or relaxed, `alias_hit`, `qualified_alias_hit`, `exact_lookup`, `relational_pinned`) and admits vector-only pages, in rank order, only while the result holds fewer than `cap` distinct `(source_id, slug)` pages; it reports `{ cap, kept_pages, dropped_pages }` as `_meta.retrieval.page_cap` when it dropped any. `pageCapLine(retrieval, how)` renders that as the model-visible line dispatch's `retrievalNoticeBlocks` appends after the keyword count line (hosts that show only `content[]` never see `_meta`), and the CLI's `formatResult` writes on stderr with `--limit`. Applied to the hybrid output before alias fan-out (search) and to the first pass and an adopted CRAG re-run (query); keyword-only paths carry no vector-only rows and the image branch is uncapped (`test/search-remote-page-cap.test.ts`). Every vector path (the hybrid vector arm, the embed-failure fallback, the `query` image branch) reads the keyword path's source scope (`test/search-vector-scope-parity.test.ts`).
diff --git a/docs/evidence-delivery.md b/docs/evidence-delivery.md
index 8d94382c44..8e54810d69 100644
--- a/docs/evidence-delivery.md
+++ b/docs/evidence-delivery.md
@@ -179,7 +179,18 @@ in its entity page's facts fence or taken from a page the caller may not read.
If that read fails, the header reads `unknown` and the response reports the
degraded stage `fact_observed_date_unavailable` (`recall`:
`facts_degraded.reason`). The facts block, the temporal fact reserve and the
-facts arm date their fact rows the same way. `valid`
+facts arm date their fact rows the same way. In the facts block, when the
+question names one date (`questionDate`, the shared temporal grammar), a fact
+said after it ends its header `; told after DATE` and a fact whose `observed`
+is `unknown` ends it `; learn date unknown`:
+`[observed 2026-06-30; valid 2026-02-15 to unknown; told after 2026-04-01]`.
+On a history cue (a word such as before, earlier or previously, or a time the
+question names that has already passed) the block also takes the named
+entity's ended facts, superseded or closed by a past `valid_until`, each with
+its window; a forgotten or withdrawn fact never appears. A fact in a pending
+supersede proposal ends with `(contested by #<id>)` when the caller can read
+the other fact, as `recall` labels it; if that lookup fails the rows carry no
+label and the response reports the degraded stage `contested_unavailable`. `valid`
starts at the fact's `valid_from`: `remember` sets it from its `valid_from`
parameter (when the fact was said or became true). A `valid_from` that only
records the write time (within a minute of `created_at`) reads `unknown`, so a
diff --git a/docs/protocol/MCP_META_CHANNELS.md b/docs/protocol/MCP_META_CHANNELS.md
index d679d29375..9dc38fd399 100644
--- a/docs/protocol/MCP_META_CHANNELS.md
+++ b/docs/protocol/MCP_META_CHANNELS.md
@@ -188,7 +188,7 @@ The codes in `_meta.degraded.reasons` ([AGENT_OPERATOR_v1.md, Degraded stamp](AG
| Code | Ops | Meaning |
|---|---|---|
-| a retrieval stage: `embed_unavailable`, `embed_timeout`, `expansion_failed`, `expansion_partial`, `rescore_skipped`, `vector_arm_failed`, `keyword_arm_failed`, `title_arm_failed`, `budget_dropped_all`, `budget_truncated`, `keyword_zero`, `cache_prestamp`, `rerank_passthrough`, `rerank_failed`, `keyword_relaxed_carried`, `safe_index_pending`, `vector_candidates_incomplete`, `keyword_candidates_incomplete`, `projection_pending`, `projection_by_design`, `projection_status_unknown`, `keyword_count_unavailable`, `saved_facts_withheld`, `fact_observed_date_unavailable` | search, query, recall, find_experts; think and synthesize (their page search) | the stage in `_meta.retrieval.degraded` (every stage except the ranking-only `reranker_skipped`; `projection_pending` only when a pending page could match). `embed_unavailable` also covers a keyless brain and recall's keyword-only markers, so a keyless brain stamps every search |
+| a retrieval stage: `embed_unavailable`, `embed_timeout`, `expansion_failed`, `expansion_partial`, `rescore_skipped`, `vector_arm_failed`, `keyword_arm_failed`, `title_arm_failed`, `budget_dropped_all`, `budget_truncated`, `keyword_zero`, `cache_prestamp`, `rerank_passthrough`, `rerank_failed`, `keyword_relaxed_carried`, `safe_index_pending`, `vector_candidates_incomplete`, `keyword_candidates_incomplete`, `projection_pending`, `projection_by_design`, `projection_status_unknown`, `keyword_count_unavailable`, `saved_facts_withheld`, `fact_observed_date_unavailable`, `contested_unavailable` (query) | search, query, recall, find_experts; think and synthesize (their page search) | the stage in `_meta.retrieval.degraded` (every stage except the ranking-only `reranker_skipped`; `projection_pending` only when a pending page could match). `embed_unavailable` also covers a keyless brain and recall's keyword-only markers, so a keyless brain stamps every search |
| `no_query_terms`, `facts_embedding_column_missing`, `facts_read_failed`, `saved_facts_withheld`, `fact_observed_date_unavailable` | recall | `facts_degraded.reason` of a question-ranked recall |
| `facts_unembedded` | recall | some facts in scope could not be compared with the question |
| `deadline`, `server_budget`, `budget_trimmed` | context_pack | `degraded_reason`: the pack is partial |
diff --git a/src/core/interop-notices.ts b/src/core/interop-notices.ts
index 37c51cf09d..f6753362d3 100644
--- a/src/core/interop-notices.ts
+++ b/src/core/interop-notices.ts
@@ -60,6 +60,7 @@ export const DEGRADED_STAGE_GUIDANCE: Readonly<Record<RecallStage, StageGuidance
keyword_count_unavailable: { why: 'the keyword match count did not finish, so how many pages match the query is unknown', fix: null },
saved_facts_withheld: { why: 'saved facts could not be checked for third-party text to quote, so they were withheld; the page results are complete', fix: 'doctor' },
fact_observed_date_unavailable: { why: 'when saved facts were said could not be read, so their date headers show observed unknown; that is not evidence the date is unknown', fix: 'doctor' },
+ contested_unavailable: { why: 'whether saved facts are disputed by another saved fact could not be checked, so no fact row carries a contested label; that is not evidence none is disputed', fix: 'doctor' },
deadline: { why: 'the pack hit its time limit and is partial', fix: null },
server_budget: { why: 'the server ran out of time budget for this pack', fix: null },
no_query_terms: { why: 'the question has no searchable words and semantic search did not run, so no saved fact could be ranked against it', fix: 'embeddings' },
diff --git a/src/core/ops/search.ts b/src/core/ops/search.ts
index b5fd36cb69..e1d0a81972 100644
--- a/src/core/ops/search.ts
+++ b/src/core/ops/search.ts
@@ -497,6 +497,7 @@ async function buildRetrievalResponseMeta(
if (safeIndexPending) degraded.push({ stage: 'safe_index_pending' });
if (quotedFacts === null && visible.length) degraded.push({ stage: 'saved_facts_withheld' });
if ((results as SearchResult[]).some(r => r.fact_row?.observed_unavailable)) degraded.push({ stage: 'fact_observed_date_unavailable' });
+ if ((results as SearchResult[]).some(r => r.fact_row?.contested_unavailable)) degraded.push({ stage: 'contested_unavailable' });
if (readiness.status === 'by_design') degraded.push({ stage: 'projection_by_design' });
else if (readiness.status !== 'ready') {
degraded.push({ stage: readiness.status === 'projection_pending' ? 'projection_pending' : 'projection_status_unknown' });
diff --git a/src/core/search/evidence-date.ts b/src/core/search/evidence-date.ts
index 842fed1e1b..25cc6a08a4 100644
--- a/src/core/search/evidence-date.ts
+++ b/src/core/search/evidence-date.ts
@@ -7,6 +7,9 @@
*
* page block: [observed 2026-03-05]
* fact: [observed unknown; valid 2026-03-01 to unknown]
+ * fact, asked about one date (GBRA-574 B3, the query facts block):
+ * [observed 2026-06-30; valid 2026-02-15 to unknown; told after 2026-04-01]
+ * [observed unknown; valid 2026-03-01 to unknown; learn date unknown]
*
* Each date is YYYY-MM-DD or the literal `unknown`. `observed` is when the
* source text was written or said (date grounding's observation time,
@@ -72,18 +75,23 @@ const WRITE_TIME_DEFAULT_MS = 60_000;
* came from, when the caller supplies it. `valid FROM` is the fact's
* valid_from, except a valid_from that only records the write time (the
* default when `remember` gets no date) renders `unknown`: the header never
- * presents when a fact was written as when it became true.
+ * presents when a fact was written as when it became true. With `askedDate`
+ * (the one day a question names, YYYY-MM-DD), a fact said after it ends
+ * `; told after <askedDate>` and one whose saying date is unknown ends
+ * `; learn date unknown`, so neither reads as known on that day.
*/
export function factDateHeader(
fact: { valid_from?: Date | string | null; valid_until?: Date | string | null; created_at?: Date | string | null },
timeZone?: string | null,
observed?: string | null,
+ askedDate?: string | null,
): string {
const writeTimeDefault = fact.valid_from && fact.created_at
&& Math.abs(new Date(fact.valid_from).getTime() - new Date(fact.created_at).getTime()) < WRITE_TIME_DEFAULT_MS;
const from = (writeTimeDefault ? null : formatBrainDay(fact.valid_from, timeZone)) ?? UNKNOWN_DATE;
const until = formatBrainDay(fact.valid_until, timeZone) ?? UNKNOWN_DATE;
- return `[observed ${observed ?? UNKNOWN_DATE}; valid ${from} to ${until}]`;
+ const told = !askedDate ? '' : !observed ? '; learn date unknown' : observed > askedDate ? `; told after ${askedDate}` : '';
+ return `[observed ${observed ?? UNKNOWN_DATE}; valid ${from} to ${until}${told}]`;
}
/**
diff --git a/src/core/search/fact-relevance.ts b/src/core/search/fact-relevance.ts
index fc8797c730..d20f78059b 100644
--- a/src/core/search/fact-relevance.ts
+++ b/src/core/search/fact-relevance.ts
@@ -11,7 +11,9 @@
* event-time since, escaped grep) inside the SQL. Three arms fill it: keyword
* (FTS over fact text and entity), cosine (nearest by the question embedding,
* cast to the facts column type) and the facts of the one entity page the
- * question names, constrained to that page's source.
+ * question names, constrained to that page's source. With `history` (GBRA-574
+ * B1) that last arm also takes the entity's ended facts (ENDED_FACT_SQL),
+ * under the same read policy.
*
* Score: cosine + term share + DATED_BONUS when the writer supplied the date.
* Term share matches words on their stems under the brain's full-text config
@@ -29,10 +31,11 @@
import type { BrainEngine } from '../engine.ts';
import type { TrustTier } from '../trust/tier.ts';
import { AUDIT_ROW_SOURCES } from '../facts/audit-sources.ts';
+import { PAGE_EXTRACTION_SOURCE_LIST, contextHeadSql } from '../facts/gone-page-facts.ts';
import { factsFtsDocument, getFtsLanguage } from '../fts-language.ts';
import { getEmbeddingModel } from '../ai/gateway.ts';
import { privateProvenanceFilterUnderPolicy } from './private-visibility.ts';
-import { factVisibilitySql } from '../access/member-facts.ts';
+import { factVisibilitySql, withdrawalCoversFactSql } from '../access/member-facts.ts';
import { quarantinedProvenanceFilterFragment } from '../quarantine.ts';
import { namedEntity } from './entity-anchor.ts';
import { projectionEligibleSql } from '../eligibility/sql.ts';
@@ -122,6 +125,8 @@ export interface FactPoolOpts {
hnswIterativeScan?: HnswIterativeScanMode;
/** Search a question over MAX_QUERY_TERMS content terms on its last SEARCH_TERMS and score it on those its candidates hold (recall). */
distinctiveTerms?: boolean;
+ /** GBRA-574 B1: the named-entity arm also pools that entity's ended facts (ENDED_FACT_SQL), the most recent first. */
+ history?: boolean;
}
export interface FactCandidate {
@@ -165,6 +170,20 @@ async function wordStems(engine: BrainEngine, words: string[]): Promise<WordStem
}
}
+/**
+ * An ended fact a history read may show: superseded by a successor, or closed by a valid_until in the past while still
+ * unexpired. A fact expired with no successor (forgotten or withdrawn) never matches, nor does any fact whose claim the
+ * withdrawal ledger covers, nor one whose page a purge removed: a purge expires only the page's unexpired facts
+ * (gone-page-facts.ts), so a superseded fact filed on or extracted from that page would otherwise come back.
+ */
+const ENDED_FACT_SQL = `(f.superseded_by IS NOT NULL OR (f.expired_at IS NULL AND f.valid_until <= now()))
+ AND NOT EXISTS (SELECT 1 FROM fact_withdrawals w WHERE w.source_id = f.source_id AND w.visibility = f.visibility
+ AND w.fact_hash IN (gbrain_fact_fingerprint(f.fact), gbrain_fact_fingerprint_v1(f.fact)) AND ${withdrawalCoversFactSql('w', 'f')})
+ AND (f.source_markdown_slug IS NULL OR f.dimension IS NOT NULL
+ OR EXISTS (SELECT 1 FROM pages hp WHERE hp.source_id = f.source_id AND hp.slug = f.source_markdown_slug))
+ AND (f.source_markdown_slug IS NOT NULL OR f.source NOT IN (${PAGE_EXTRACTION_SOURCE_LIST.map(s => `'${s}'`).join(', ')})
+ OR EXISTS (SELECT 1 FROM pages hp WHERE hp.source_id = f.source_id AND hp.slug = ${contextHeadSql('f')}))`;
+
const COLS = 'f.id, f.fact, f.kind, f.entity_slug, f.source_id, f.source, f.valid_from, f.valid_until, f.created_at, f.claim_metric, f.claim_period, f.source_markdown_slug, f.visibility, f.attributed_to';
/** The facts embedding column's type and declared dimensions, or null when there is none. */
@@ -286,10 +305,17 @@ export async function collectFactCandidates(engine: BrainEngine, question: strin
const named = await namedEntity(engine, question, { sourceIds, excludePrivate: scope.excludePrivate });
if (!named) return [];
const p = armParams(allSim ? simParams : []);
- return engine.executeRaw<Row>(
+ const active = await engine.executeRaw<Row>(
`SELECT ${COLS}, ${allSim ? simSql : 'NULL::float8 AS similarity'} FROM facts f WHERE ${where} AND f.source_id = $${p.length + 1} AND f.entity_slug = $${p.length + 2}
ORDER BY f.valid_from DESC, f.id DESC LIMIT $${p.length + 3}`,
[...p, named.source_id, named.slug, opts.depth.entity]);
+ if (!opts.history) return active;
+ const ended = poolPredicate(scope, { ...opts.filters, includeExpired: true });
+ const e = [...ended.params, ...(allSim ? simParams : [])];
+ return [...active, ...await engine.executeRaw<Row>(
+ `SELECT ${COLS}, ${allSim ? simSql : 'NULL::float8 AS similarity'} FROM facts f WHERE ${ended.where} AND ${ENDED_FACT_SQL} AND f.source_id = $${e.length + 1} AND f.entity_slug = $${e.length + 2}
+ ORDER BY f.valid_from DESC, f.id DESC LIMIT $${e.length + 3}`,
+ [...e, named.source_id, named.slug, opts.depth.entity])];
};
// Independent arms run concurrently (separate connections on Postgres); merged in a fixed order.
const [byKeyword, byCosine, byEntity] = await Promise.all([keyword(), nearest(), entityFacts()]);
diff --git a/src/core/search/facts-arm.ts b/src/core/search/facts-arm.ts
index e675333944..a298f44f5a 100644
--- a/src/core/search/facts-arm.ts
+++ b/src/core/search/facts-arm.ts
@@ -28,6 +28,9 @@ import { collapseFactReads } from '../facts/capture-dedup.ts';
import type { TrustTier } from '../trust/tier.ts';
import { conversationSignal } from './evidence-delivery.ts';
import { factsFromQuotedPages } from './transcript-quote.ts';
+import { findTimeMentions } from '../temporal-grammar.ts';
+import { withDecideContested, type ContestedLookup } from '../facts/contested-claims.ts';
+import type { Contested } from '../eligibility/labels.ts';
export { queryTerms } from './fact-relevance.ts';
@@ -68,6 +71,23 @@ export function hasTemporalCue(query: string): boolean {
return TEMPORAL_CUE.test(query);
}
+const HISTORY_CUE = /\b(before|earlier|earliest|previous(ly)?|prior|former(ly)?|used to|originally|first|history|historically|ever|over time|in order|chronolog\w*|sequence|ago|back then|at the time|no longer|any ?more|in the past)\b/i;
+const today = () => new Date().toISOString().slice(0, 10);
+
+/**
+ * GBRA-574 B1: whether `query` asks about the past, by a plain-English history word or a time it names (the shared
+ * temporal grammar, temporal-grammar.ts) that ended before `asOf` (today by default).
+ */
+export function hasHistoryCue(query: string, asOf = today()): boolean {
+ return HISTORY_CUE.test(query) || findTimeMentions(query, asOf, 'past').some(m => m.end < asOf);
+}
+
+/** GBRA-574 B3: the one date `query` names (the last day of it, YYYY-MM-DD, by the shared temporal grammar), or null for none or several. */
+export function questionDate(query: string, asOf = today()): string | null {
+ const ends = [...new Set(findTimeMentions(query, asOf, 'past').filter(m => m.kind === 'absolute').map(m => m.end))];
+ return ends.length === 1 ? ends[0]! : null;
+}
+
export interface FactsArmScope {
sourceId?: string; sourceIds?: string[]; remote: boolean;
/** #5575 read floor and activation control, applied in the candidate SQL like every retrieval arm. */
@@ -214,10 +234,12 @@ interface ReservePolicy {
rowShare: number | null;
/** Where the facts go: after the pages (temporal reserve) or ahead of them (facts block). */
position: 'after' | 'before';
+ /** GBRA-574 B1, B3 and G1: ended facts on a history cue, the asked date in each header, and contested labels. */
+ dated: boolean;
}
-const TEMPORAL_RESERVE: ReservePolicy = { share: TEMPORAL_RESERVE_SHARE, maxRows: MAX_RESERVE_ROWS, rowShare: TEMPORAL_RESERVE_ROW_SHARE, position: 'after' };
-const FACTS_BLOCK: ReservePolicy = { share: QUERY_FACTS_BLOCK_SHARE, maxRows: MAX_FACTS_BLOCK_ROWS, rowShare: null, position: 'before' };
+const TEMPORAL_RESERVE: ReservePolicy = { share: TEMPORAL_RESERVE_SHARE, maxRows: MAX_RESERVE_ROWS, rowShare: TEMPORAL_RESERVE_ROW_SHARE, position: 'after', dated: false };
+const FACTS_BLOCK: ReservePolicy = { share: QUERY_FACTS_BLOCK_SHARE, maxRows: MAX_FACTS_BLOCK_ROWS, rowShare: null, position: 'before', dated: true };
/**
* Temporal fact reserve: for a query with a temporal cue and a token budget,
@@ -240,7 +262,12 @@ export function applyTemporalFactReserve(engine: BrainEngine, query: string, res
* never more rows than the caller's row count (#8411), oldest first ahead of
* the pages. Copies of one claim take one row, dated as first stated with
* "(stated N times, last D)" after the fact (GBRA-574 A2), and each row's date
- * header carries when the fact was said (A1). Block rows take the top page's
+ * header carries when the fact was said (A1). On a history cue (`hasHistoryCue`)
+ * the pool also takes the named entity's ended facts with their windows (B1;
+ * never a withdrawn or forgotten one); when the question names one date each
+ * header says whether the fact was told after it (B3); and a fact in a pending
+ * supersede proposal ends "(contested by #<id>)" when the caller can read the
+ * other fact, as recall labels it (G1). Block rows take the top page's
* score: they are placed, not ranked against the pages, and never outscore them. The facts add rows
* (every page row stays) and pages fill the rest of the budget. No match or
* any error: the results unchanged.
@@ -251,8 +278,9 @@ export function applyFactsBlock(engine: BrainEngine, query: string, results: Sea
async function applyFactReserve(engine: BrainEngine, query: string, results: SearchResult[], opts: FactsArmOpts & { budget: number }, policy: ReservePolicy): Promise<SearchResult[]> {
try {
- const { candidates, stems } = await collectFactCandidates(engine, query, await poolScope(engine, opts), opts.queryEmbedding,
- { depth: { keyword: 50, cosine: 50, entity: policy.maxRows }, cosineForAll: true });
+ const scope = await poolScope(engine, opts);
+ const { candidates, stems } = await collectFactCandidates(engine, query, scope, opts.queryEmbedding,
+ { depth: { keyword: 50, cosine: 50, entity: policy.maxRows }, cosineForAll: true, history: policy.dated && hasHistoryCue(query) });
const scored = scoreFactCandidates(query, candidates, queryTerms(query), stems).filter(s => admitted(s, 'reserve')).map(s => s.candidate);
if (!scored.length) return results;
const callerRows = (await opts.rowCap?.().catch(() => 0)) ?? 0;
@@ -268,6 +296,13 @@ async function applyFactReserve(engine: BrainEngine, query: string, results: Sea
const shown = groups.map(g => g[0]!);
const pageSlugs = await readableEntityPages(engine, shown, opts.readScope).catch(() => new Set<string>());
const fromQuoted = await factsFromQuotedPages(engine, shown.map(c => Number(c.id)));
+ const asked = policy.dated ? questionDate(query) : null;
+ const lookup: ContestedLookup = {};
+ const contested = policy.dated
+ ? new Map((await withDecideContested<{ id: number; contested?: Contested }>(engine, shown.map(c => ({ id: Number(c.id) })),
+ { remote: opts.remote, excludePrivate: scope.excludePrivate, eligibility: { floor: opts.minTrust, suppressFlagged: opts.suppressFlagged } }, lookup))
+ .flatMap(r => (r.contested ? [[r.id, r.contested.fact_id] as const] : [])))
+ : new Map<number, string>();
let left = Math.floor(opts.budget * policy.share);
const chosen: Array<{ c: FactCandidate; row: SearchResult }> = [];
for (const group of groups) {
@@ -275,7 +310,9 @@ async function applyFactReserve(engine: BrainEngine, query: string, results: Sea
const c = group[0]!;
const restated = group.length > 1 ? ` (stated ${group.length} times, last ${said(group[group.length - 1]!)})` : '';
const row = factRow(c, 0, c.entity_slug && pageSlugs.has(`${c.source_id}\u0000${c.entity_slug}`) ? c.entity_slug : undefined, fromQuoted.has(Number(c.id)), dates);
- row.chunk_text = `${factDateHeader(c, undefined, dates?.get(Number(c.id)))}\n${c.fact}${restated}`;
+ const label = contested.has(Number(c.id)) ? ` (contested by #${contested.get(Number(c.id))})` : '';
+ row.chunk_text = `${factDateHeader(c, undefined, dates?.get(Number(c.id)), asked)}\n${c.fact}${restated}${label}`;
+ if (lookup.degraded) row.fact_row = { ...row.fact_row!, contested_unavailable: true };
const cost = resultTokens(row);
if (cost > left) continue;
left -= cost;
diff --git a/src/core/types.ts b/src/core/types.ts
index 6138f075c1..41b2d379a7 100644
--- a/src/core/types.ts
+++ b/src/core/types.ts
@@ -1131,8 +1131,8 @@ export interface SearchResult {
* entity's page, or a page that links to it or names it (newest first).
*/
entity_anchored?: 'entity' | 'linked';
- /** Set on a saved-fact row the `search.query_facts_arm` arm added (search/facts-arm.ts); page_id is 0. `observed`: when it was said; `observed_unavailable`: that read failed. */
- fact_row?: { id: number; valid_from: string; valid_until: string | null; source?: string; from_quoted_page?: true; observed?: string; observed_unavailable?: true };
+ /** Set on a saved-fact row the `search.query_facts_arm` arm added (search/facts-arm.ts); page_id is 0. `observed`: when it was said; `observed_unavailable`: that read failed; `contested_unavailable`: the facts block's contested lookup failed. */
+ fact_row?: { id: number; valid_from: string; valid_until: string | null; source?: string; from_quoted_page?: true; observed?: string; observed_unavailable?: true; contested_unavailable?: true };
/** Fact rows only, and what callers see of them: never a page (no slug or id); follow with `follow_up`, read `page_slug` when the entity page exists. */
result_type?: 'fact'; fact_id?: string; page_slug?: string; follow_up?: { op: 'recall'; args: Record<string, string> };
/** #7600, #8042: a row of third-party text (a chat page or a fact saved from one), returned fenced as quoted source material with its tool-call blocks summarized (search/transcript-quote.ts). */
@@ -2105,7 +2105,7 @@ export const DEGRADED_STAGES = [
'keyword_candidates_incomplete',
'projection_pending', 'projection_by_design',
'projection_status_unknown',
- 'keyword_count_unavailable', 'saved_facts_withheld', 'fact_observed_date_unavailable',
+ 'keyword_count_unavailable', 'saved_facts_withheld', 'fact_observed_date_unavailable', 'contested_unavailable',
] as const;
export type DegradedStage = (typeof DEGRADED_STAGES)[number];
diff --git a/test/dated-facts-wave-a.test.ts b/test/dated-facts-wave-a.test.ts
index d41c7f177a..869abd8c81 100644
--- a/test/dated-facts-wave-a.test.ts
+++ b/test/dated-facts-wave-a.test.ts
@@ -79,8 +79,7 @@ describe('S8 history: every dated value of the slot reaches the reader', () => {
const dated = rows.filter(r => /\[observed \d{4}-\d\d-\d\d|valid \d{4}-\d\d-\d\d/.test(r.chunk_text ?? '')).map(r => r.chunk_text).join('\n');
for (const [c] of CITIES) expect(dated).toContain(c);
});
- // Ended values reach the reader only with B1 (history in the facts block, the next PR); it removes `.failing`.
- test.failing('S8b after consolidate stamps valid_until on the older values: all four cities are in the context', async () => {
+ test('S8b after consolidate stamps valid_until on the older values: all four cities are in the context', async () => {
const close = (city: string, until: number) => engine.executeRaw(
'UPDATE facts SET valid_until = $2::timestamptz WHERE source_id = $1 AND fact = $3', [sourceId, day(until) + 'T00:00:00Z', 'Alice Example lives in ' + city + '.']);
await close('Lisbon', 30);
diff --git a/test/facts-block-history-gbra574.test.ts b/test/facts-block-history-gbra574.test.ts
new file mode 100644
index 0000000000..0cca5065f5
--- /dev/null
+++ b/test/facts-block-history-gbra574.test.ts
@@ -0,0 +1,210 @@
+/**
+ * GBRA-574 B1, B3 and G1: what the query facts block carries for a question about the past. PGLite, keyless, no network.
+ *
+ * B1: on a history or past-date cue, the block also takes the named entity's ended facts (superseded, or closed by a
+ * valid_until in the past), with their windows. Never a fact expired with no successor, never one the withdrawal
+ * ledger matches, never a fact the caller cannot read. No cue, no ended facts.
+ * B3: when the question names one date, a fact said after it is marked "told after <date>", and one whose saying date
+ * is unknown says "learn date unknown".
+ * G1: a fact in a pending supersede proposal carries recall's contested label, only when the caller can read the
+ * other fact; a failed lookup marks the rows, and query reports it as degraded.
+ */
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import type { BrainEngine } from '../src/core/engine.ts';
+import { handleToolCall } from '../src/mcp/server.ts';
+import { dispatchToolCall } from '../src/mcp/dispatch.ts';
+import { forgetFactInFence } from '../src/core/facts/forget.ts';
+import { applyFactsBlock, hasHistoryCue } from '../src/core/search/facts-arm.ts';
+import { collectFactCandidates } from '../src/core/search/fact-relevance.ts';
+import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';
+import { newSource, page, putPage } from './helpers/pinned-questions-fixture.ts';
+
+type Row = { result_type?: string; chunk_text?: string; fact_row?: { contested_unavailable?: true } };
+const SRC = 'cli:extract-conversation-facts:v1';
+let engine: PGLiteEngine;
+let sourceId: string;
+const ids: Record<string, number> = {};
+
+const day = (i: number) => new Date(Date.UTC(2025, 0, 1) + i * 3 * 86_400_000).toISOString().slice(0, 10);
+const session = (i: number) => 'conversations/talk-' + String(i).padStart(3, '0');
+
+async function fact(key: string, text: string, entity: string, sessionIdx: number | null, opts: { validFrom?: string; visibility?: 'world' | 'private' } = {}) {
+ const [row] = await engine.executeRaw<{ id: number }>(
+ "INSERT INTO facts (source_id, entity_slug, fact, kind, source, visibility, confidence, valid_from, source_markdown_slug) VALUES ($1, $2, $3, 'event', $4, $5, 1, $6::timestamptz, $7) RETURNING id",
+ [sourceId, entity, text, SRC, opts.visibility ?? 'world', (opts.validFrom ?? day(sessionIdx ?? 0)) + 'T00:00:00Z', sessionIdx === null ? null : session(sessionIdx)]);
+ ids[key] = Number(row!.id);
+}
+const end = (key: string, until: number) => engine.executeRaw('UPDATE facts SET valid_until = $2::timestamptz WHERE id = $1', [ids[key], day(until) + 'T00:00:00Z']);
+const supersede = (key: string, by: string, until: number) => engine.executeRaw(
+ 'UPDATE facts SET expired_at = now(), superseded_by = $2, valid_until = $3::timestamptz WHERE id = $1', [ids[key], ids[by], day(until) + 'T00:00:00Z']);
+
+const ask = async (query: string) =>
+ (await handleToolCall(engine, 'query', { query, expand: false, use_cache: false, source_id: sourceId, limit: 50, token_budget: 5500 }) as Row[])
+ .filter(r => r.result_type === 'fact').map(r => r.chunk_text ?? '');
+const askRemote = async (query: string) => {
+ __resetPrivateVisibilityCacheForTests();
+ const auth = { token: 't', clientId: 'history-remote', scopes: ['read'], sourceId, allowedSources: [sourceId] };
+ const r = await dispatchToolCall(engine, 'query', { query, expand: false, use_cache: false, limit: 50, token_budget: 5500 },
+ { remote: true, transport: 'stdio', sourceId, auth, config: { engine: engine.kind } as never, logger: { info() {}, warn() {}, error() {} } });
+ return r.content.map(c => (c as { text?: string }).text ?? '').join('\n');
+};
+
+const ERIN = 'people/erin-example';
+const HISTORY_Q = 'Where has Erin Example lived before?';
+
+beforeAll(async () => {
+ engine = new PGLiteEngine();
+ await engine.connect({});
+ await engine.initSchema();
+ sourceId = await newSource(engine);
+ for (const [slug, name] of [[ERIN, 'Erin Example'], ['people/bob-example', 'Bob Example'], ['companies/fern-example', 'Fern Example']] as const) {
+ await putPage(engine, sourceId, slug, page(slug.startsWith('people/') ? 'person' : 'company', name, name + ' is in the address book.'));
+ }
+ for (let i = 1; i <= 80; i++) await putPage(engine, sourceId, session(i), page('conversation', 'Talk ' + i, '**User:** Weekly planning, session ' + i + '.\n\n**Assistant:** Noted.', 'date: ' + day(i) + '\n'));
+
+ await fact('lima', 'Erin Example lives in Lima.', ERIN, 5);
+ await fact('quito', 'Erin Example lives in Quito.', ERIN, 30);
+ await fact('arequipa', 'Erin Example lives in Arequipa.', ERIN, 40);
+ await fact('cusco', 'Erin Example lives in Cusco.', ERIN, 50);
+ await fact('montevideo', 'Erin Example lives in Montevideo.', ERIN, 55, { visibility: 'private' });
+ await fact('bogota', 'Erin Example lives in Bogota.', ERIN, 70);
+ await end('lima', 30);
+ await supersede('quito', 'bogota', 70);
+ await end('montevideo', 60);
+ await forgetFactInFence(engine, ids.cusco!);
+ await supersede('arequipa', 'bogota', 70);
+ await engine.executeRaw("INSERT INTO fact_withdrawals (source_id, visibility, subject, fact_hash) VALUES ($1, 'world', $2, gbrain_fact_fingerprint('Erin Example lives in Arequipa.'))", [sourceId, ERIN]);
+
+ await fact('beta', 'Bob Example works at Beta Corp.', 'people/bob-example', 10);
+ await fact('gamma', 'Bob Example left Beta Corp and joined Gamma Labs.', 'people/bob-example', 60, { validFrom: '2025-02-15' });
+ await fact('mentor', 'Bob Example works as a mentor for two interns.', 'people/bob-example', null, { validFrom: '2025-01-20' });
+
+ await fact('denver', 'The Fern Example office is in Denver.', 'companies/fern-example', 20);
+ await fact('austin', 'The Fern Example office is in Austin.', 'companies/fern-example', 25);
+ await fact('reno', 'The Fern Example office is in Reno.', 'companies/fern-example', 26, { visibility: 'private' });
+ const propose = (n: string, o: string) => engine.executeRaw(
+ 'INSERT INTO decide_proposals (source_id, sweep_id, pair_index, new_fact_id, old_fact_id, p_supersede, proposal_floor) VALUES ($1, $2, 0, $3, $4, 1, 1)', [sourceId, 'conflict:test-' + n + '-' + o, ids[n], ids[o]]);
+ await propose('austin', 'denver');
+ await propose('reno', 'austin');
+}, 300_000);
+afterAll(async () => { await engine?.disconnect(); }, 60_000);
+
+describe('B1 ended facts reach a history question', () => {
+ test('history words and past dates are cues; a present or future question is not', () => {
+ expect(hasHistoryCue(HISTORY_Q, '2026-11-17')).toBe(true);
+ expect(hasHistoryCue('As of 2025-04-01, where did Bob Example work?', '2026-11-17')).toBe(true);
+ expect(hasHistoryCue('Where does Erin Example live?', '2026-11-17')).toBe(false);
+ expect(hasHistoryCue('Where will Erin Example live in 2030?', '2026-11-17')).toBe(false);
+ });
+ test('ended and superseded values arrive with their windows, oldest first', async () => {
+ const rows = await ask(HISTORY_Q);
+ const order = ['Lima', 'Quito', 'Bogota'].map(c => rows.findIndex(t => t.includes('Erin Example lives in ' + c + '.')));
+ expect(order.every(i => i >= 0)).toBe(true);
+ expect([...order].sort((a, b) => a - b)).toEqual(order);
+ expect(rows[order[0]!]!.split('\n')[0]).toBe('[observed ' + day(5) + '; valid ' + day(5) + ' to ' + day(30) + ']');
+ expect(rows[order[2]!]!.split('\n')[0]).toBe('[observed ' + day(70) + '; valid ' + day(70) + ' to unknown]');
+ });
+ test('a forgotten fact and a withdrawn superseded fact never arrive', async () => {
+ const text = (await ask(HISTORY_Q)).join('\n');
+ expect(text).not.toContain('Cusco');
+ expect(text).not.toContain('Arequipa');
+ });
+ test('a private ended fact reaches the local caller only', async () => {
+ expect((await ask(HISTORY_Q)).join('\n')).toContain('Montevideo');
+ const remote = await askRemote(HISTORY_Q);
+ expect(remote).toContain('Lima');
+ expect(remote).not.toContain('Montevideo');
+ expect(remote).not.toContain('Arequipa');
+ });
+ test('no history cue: no ended fact', async () => {
+ const text = (await ask('Where does Erin Example live?')).join('\n');
+ expect(text).toContain('Bogota');
+ expect(text).not.toContain('Lima');
+ expect(text).not.toContain('Quito');
+ });
+});
+
+describe('B3 a question that names a date', () => {
+ const Q = 'As of 2025-04-01, where did Bob Example work?';
+ test('a fact said after that date is marked told after it; one said before is not', async () => {
+ const rows = await ask(Q);
+ expect(rows.find(t => t.includes('Gamma Labs'))!.split('\n')[0]).toBe('[observed ' + day(60) + '; valid 2025-02-15 to unknown; told after 2025-04-01]');
+ expect(rows.find(t => t.includes('Beta Corp.'))!.split('\n')[0]).toBe('[observed ' + day(10) + '; valid ' + day(10) + ' to unknown]');
+ });
+ test('a fact with no saying date says learn date unknown', async () => {
+ const rows = await ask(Q);
+ expect(rows.find(t => t.includes('mentor'))!.split('\n')[0]).toBe('[observed unknown; valid 2025-01-20 to unknown; learn date unknown]');
+ });
+ test('no date in the question: no mark', async () => {
+ const text = (await ask('Where does Bob Example work?')).join('\n');
+ expect(text).not.toContain('told after');
+ expect(text).not.toContain('learn date unknown');
+ });
+});
+
+describe('G1 contested facts in the block', () => {
+ const Q = 'Where is the Fern Example office?';
+ test('both facts of a pending proposal carry the label, naming the other fact', async () => {
+ const rows = await ask(Q);
+ expect(rows.find(t => t.includes('Denver'))).toContain('(contested by #' + ids.austin + ')');
+ expect(rows.find(t => t.includes('Austin'))).toContain('(contested by #' + ids.denver + ')');
+ });
+ test('a remote caller never learns of a contested partner it cannot read', async () => {
+ const remote = await askRemote(Q);
+ expect(remote).toContain('(contested by #' + ids.denver + ')');
+ expect(remote).not.toContain('#' + ids.reno);
+ expect(remote).not.toContain('Reno');
+ });
+ test('a failed lookup leaves the rows unlabeled and marks them', async () => {
+ const failing = new Proxy(engine, { get(target, prop) {
+ if (prop === 'executeRaw') return (sql: string, params?: unknown[]) => sql.includes('unnest($1::bigint[]) AS x(id)') ? Promise.reject(new Error('lookup failed')) : target.executeRaw(sql, params);
+ const v = (target as unknown as Record<string, unknown>)[prop as string];
+ return typeof v === 'function' ? (v as (...a: unknown[]) => unknown).bind(target) : v;
+ } }) as BrainEngine;
+ const rows = await applyFactsBlock(failing, Q, [], { sourceIds: [sourceId], remote: false, budget: 5500, tokenBudget: 5500, rowCap: async () => 50 }) as Row[];
+ expect(rows.length).toBeGreaterThan(0);
+ expect(rows.some(r => (r.chunk_text ?? '').includes('contested'))).toBe(false);
+ expect(rows.every(r => r.fact_row?.contested_unavailable)).toBe(true);
+ });
+});
+
+describe('B1 review fixes', () => {
+ test('a superseded fact whose page was purged never comes back', async () => {
+ const GINA = 'people/gina-example';
+ await putPage(engine, sourceId, GINA, page('person', 'Gina Example', 'Gina Example is in the address book.'));
+ for (const i of [81, 82]) await putPage(engine, sourceId, session(i), page('conversation', 'Talk ' + i, '**User:** Weekly planning, session ' + i + '.\n\n**Assistant:** Noted.', 'date: ' + day(i) + '\n'));
+ await fact('oslo', 'Gina Example lives in Oslo.', GINA, 81);
+ await fact('bergen', 'Gina Example lives in Bergen.', GINA, null, { validFrom: day(81) });
+ await engine.executeRaw("UPDATE facts SET source = 'sync:import', context = $2 WHERE id = $1", [ids.bergen, session(81) + ' — weekly notes']);
+ await fact('tromso', 'Gina Example lives in Tromso.', GINA, 82);
+ await supersede('oslo', 'tromso', 82);
+ await supersede('bergen', 'tromso', 82);
+ const Q = 'Where has Gina Example lived before?';
+ const before = (await ask(Q)).join('\n');
+ expect(before).toContain('Oslo');
+ expect(before).toContain('Bergen');
+ await engine.softDeletePage(session(81), { sourceId });
+ await engine.executeRaw("UPDATE pages SET deleted_at = now() - interval '100 hours' WHERE source_id = $1 AND slug = $2", [sourceId, session(81)]);
+ expect((await engine.purgeDeletedPages(72)).slugs).toContain(session(81));
+ const after = (await ask(Q)).join('\n');
+ expect(after).toContain('Tromso');
+ expect(after).not.toContain('Oslo');
+ expect(after).not.toContain('Bergen');
+ });
+ test('an entity with more ended facts than the pool depth keeps its most recent ones', async () => {
+ const HANK = 'people/hank-example';
+ await putPage(engine, sourceId, HANK, page('person', 'Hank Example', 'Hank Example is in the address book.'));
+ for (let i = 1; i <= 5; i++) {
+ await fact('hank' + i, 'Hank Example lives in Town' + i + '.', HANK, null, { validFrom: day(i) });
+ await end('hank' + i, i + 1);
+ }
+ await fact('hank6', 'Hank Example lives in Town6.', HANK, null, { validFrom: day(6) });
+ const { candidates } = await collectFactCandidates(engine, 'Where has Hank Example lived before?', { sourceIds: [sourceId], worldOnly: false, excludePrivate: false }, null,
+ { depth: { keyword: 50, cosine: 50, entity: 3 }, history: true });
+ const facts = candidates.map(c => c.fact);
+ expect(facts).toContain('Hank Example lives in Town6.');
+ expect(facts).toContain('Hank Example lives in Town5.');
+ expect(facts).not.toContain('Hank Example lives in Town1.');
+ });
+});
diff --git a/test/fixtures/goldens/exports/types.json b/test/fixtures/goldens/exports/types.json
index 8a683ac724..f4c7525e26 100644
--- a/test/fixtures/goldens/exports/types.json
+++ b/test/fixtures/goldens/exports/types.json
@@ -496,7 +496,7 @@
"kind": "variable",
"name": "DEGRADED_STAGES",
"signature": [
- "readonly [\"embed_unavailable\", \"embed_timeout\", \"expansion_failed\", \"expansion_partial\", \"rescore_skipped\", \"vector_arm_failed\", \"keyword_arm_failed\", \"title_arm_failed\", \"budget_dropped_all\", \"budget_truncated\", \"keyword_zero\", \"cache_prestamp\", \"reranker_skipped\", \"rerank_passthrough\", \"rerank_failed\", \"keyword_relaxed_carried\", \"safe_index_pending\", \"vector_candidates_incomplete\", \"keyword_candidates_incomplete\", \"projection_pending\", \"projection_by_design\", \"projection_status_unknown\", \"keyword_count_unavailable\", \"saved_facts_withheld\", \"fact_observed_date_unavailable\"]"
+ "readonly [\"embed_unavailable\", \"embed_timeout\", \"expansion_failed\", \"expansion_partial\", \"rescore_skipped\", \"vector_arm_failed\", \"keyword_arm_failed\", \"title_arm_failed\", \"budget_dropped_all\", \"budget_truncated\", \"keyword_zero\", \"cache_prestamp\", \"reranker_skipped\", \"rerank_passthrough\", \"rerank_failed\", \"keyword_relaxed_carried\", \"safe_index_pending\", \"vector_candidates_incomplete\", \"keyword_candidates_incomplete\", \"projection_pending\", \"projection_by_design\", \"projection_status_unknown\", \"keyword_count_unavailable\", \"saved_facts_withheld\", \"fact_observed_date_unavailable\", \"contested_unavailable\"]"
]
},
{
@@ -510,14 +510,14 @@
"kind": "type",
"name": "DegradedStage",
"signature": [
- "\"embed_unavailable\" | \"embed_timeout\" | \"expansion_failed\" | \"expansion_partial\" | \"rescore_skipped\" | \"vector_arm_failed\" | \"keyword_arm_failed\" | \"title_arm_failed\" | \"budget_dropped_all\" | \"budget_truncated\" | \"keyword_zero\" | \"cache_prestamp\" | \"reranker_skipped\" | \"rerank_passthrough\" | \"rerank_failed\" | \"keyword_relaxed_carried\" | \"safe_index_pending\" | \"vector_candidates_incomplete\" | \"keyword_candidates_incomplete\" | \"projection_pending\" | \"projection_by_design\" | \"projection_status_unknown\" | \"keyword_count_unavailable\" | \"saved_facts_withheld\" | \"fact_observed_date_unavailable\""
+ "\"embed_unavailable\" | \"embed_timeout\" | \"expansion_failed\" | \"expansion_partial\" | \"rescore_skipped\" | \"vector_arm_failed\" | \"keyword_arm_failed\" | \"title_arm_failed\" | \"budget_dropped_all\" | \"budget_truncated\" | \"keyword_zero\" | \"cache_prestamp\" | \"reranker_skipped\" | \"rerank_passthrough\" | \"rerank_failed\" | \"keyword_relaxed_carried\" | \"safe_index_pending\" | \"vector_candidates_incomplete\" | \"keyword_candidates_incomplete\" | \"projection_pending\" | \"projection_by_design\" | \"projection_status_unknown\" | \"keyword_count_unavailable\" | \"saved_facts_withheld\" | \"fact_observed_date_unavailable\" | \"contested_unavailable\""
]
},
{
"kind": "interface",
"members": [
"reason?: \"candidate_budget\" | \"iterative_scan_unavailable\" | \"timeout\" | \"provider_error\" | \"no_provider\" | \"variant_embed_failed\" | \"original_embed_failed\" | \"first_result_truncated\" | \"no_key\" | \"empty_result_set\" | \"malformed_shape\" | \"budget\" | \"rate_limited\" | \"unreachable\" | \"auth\" | \"egress_denied\" | \"embedding_disabled\" | \"skipped_after_timeout\" | undefined",
- "stage: \"embed_unavailable\" | \"embed_timeout\" | \"expansion_failed\" | \"expansion_partial\" | \"rescore_skipped\" | \"vector_arm_failed\" | \"keyword_arm_failed\" | \"title_arm_failed\" | \"budget_dropped_all\" | \"budget_truncated\" | \"keyword_zero\" | \"cache_prestamp\" | \"reranker_skipped\" | \"rerank_passthrough\" | \"rerank_failed\" | \"keyword_relaxed_carried\" | \"safe_index_pending\" | \"vector_candidates_incomplete\" | \"keyword_candidates_incomplete\" | \"projection_pending\" | \"projection_by_design\" | \"projection_status_unknown\" | \"keyword_count_unavailable\" | \"saved_facts_withheld\" | \"fact_observed_date_unavailable\""
+ "stage: \"embed_unavailable\" | \"embed_timeout\" | \"expansion_failed\" | \"expansion_partial\" | \"rescore_skipped\" | \"vector_arm_failed\" | \"keyword_arm_failed\" | \"title_arm_failed\" | \"budget_dropped_all\" | \"budget_truncated\" | \"keyword_zero\" | \"cache_prestamp\" | \"reranker_skipped\" | \"rerank_passthrough\" | \"rerank_failed\" | \"keyword_relaxed_carried\" | \"safe_index_pending\" | \"vector_candidates_incomplete\" | \"keyword_candidates_incomplete\" | \"projection_pending\" | \"projection_by_design\" | \"projection_status_unknown\" | \"keyword_count_unavailable\" | \"saved_facts_withheld\" | \"fact_observed_date_unavailable\" | \"contested_unavailable\""
],
"name": "DegradedStageEntry"
},
@@ -1325,7 +1325,7 @@
"kind": "variable",
"name": "RANKING_ONLY_DEGRADED_STAGES",
"signature": [
- "ReadonlySet<\"embed_unavailable\" | \"embed_timeout\" | \"expansion_failed\" | \"expansion_partial\" | \"rescore_skipped\" | \"vector_arm_failed\" | \"keyword_arm_failed\" | \"title_arm_failed\" | \"budget_dropped_all\" | \"budget_truncated\" | \"keyword_zero\" | \"cache_prestamp\" | \"reranker_skipped\" | \"rerank_passthrough\" | \"rerank_failed\" | \"keyword_relaxed_carried\" | \"safe_index_pending\" | \"vector_candidates_incomplete\" | \"keyword_candidates_incomplete\" | \"projection_pending\" | \"projection_by_design\" | \"projection_status_unknown\" | \"keyword_count_unavailable\" | \"saved_facts_withheld\" | \"fact_observed_date_unavailable\">"
+ "ReadonlySet<\"embed_unavailable\" | \"embed_timeout\" | \"expansion_failed\" | \"expansion_partial\" | \"rescore_skipped\" | \"vector_arm_failed\" | \"keyword_arm_failed\" | \"title_arm_failed\" | \"budget_dropped_all\" | \"budget_truncated\" | \"keyword_zero\" | \"cache_prestamp\" | \"reranker_skipped\" | \"rerank_passthrough\" | \"rerank_failed\" | \"keyword_relaxed_carried\" | \"safe_index_pending\" | \"vector_candidates_incomplete\" | \"keyword_candidates_incomplete\" | \"projection_pending\" | \"projection_by_design\" | \"projection_status_unknown\" | \"keyword_count_unavailable\" | \"saved_facts_withheld\" | \"fact_observed_date_unavailable\" | \"contested_unavailable\">"
]
},
{
@@ -1525,7 +1525,7 @@
"exact_lookup?: \"title\" | \"slug\" | \"identifier\" | undefined",
"exact_match_boost?: number | undefined",
"fact_id?: string | undefined",
- "fact_row?: { id: number; valid_from: string; valid_until: string | null; source?: string; from_quoted_page?: true; observed?: string; observed_unavailable?: true; } | undefined",
+ "fact_row?: { id: number; valid_from: string; valid_until: string | null; source?: string; from_quoted_page?: true; observed?: string; observed_unavailable?: true; contested_unavailable?: true; } | undefined",
"feedback_boost?: number | undefined",
"follow_up?: { op: \"recall\"; args: Record<string, string>; } | undefined",
"fused_score?: number | undefined",
@@ -9607,7 +9607,7 @@
"kind": "variable",
"name": "DEGRADED_STAGES",
"signature": [
- "readonly [\"embed_unavailable\", \"embed_timeout\", \"expansion_failed\", \"expansion_partial\", \"rescore_skipped\", \"vector_arm_failed\", \"keyword_arm_failed\", \"title_arm_failed\", \"budget_dropped_all\", \"budget_truncated\", \"keyword_zero\", \"cache_prestamp\", \"reranker_skipped\", \"rerank_passthrough\", \"rerank_failed\", \"keyword_relaxed_carried\", \"safe_index_pending\", \"vector_candidates_incomplete\", \"keyword_candidates_incomplete\", \"projection_pending\", \"projection_by_design\", \"projection_status_unknown\", \"keyword_count_unavailable\", \"saved_facts_withheld\", \"fact_observed_date_unavailable\"]"
+ "readonly [\"embed_unavailable\", \"embed_timeout\", \"expansion_failed\", \"expansion_partial\", \"rescore_skipped\", \"vector_arm_failed\", \"keyword_arm_failed\", \"title_arm_failed\", \"budget_dropped_all\", \"budget_truncated\", \"keyword_zero\", \"cache_prestamp\", \"reranker_skipped\", \"rerank_passthrough\", \"rerank_failed\", \"keyword_relaxed_carried\", \"safe_index_pending\", \"vector_candidates_incomplete\", \"keyword_candidates_incomplete\", \"projection_pending\", \"projection_by_design\", \"projection_status_unknown\", \"keyword_count_unavailable\", \"saved_facts_withheld\", \"fact_observed_date_unavailable\", \"contested_unavailable\"]"
]
},
{
@@ -9621,14 +9621,14 @@
"kind": "type",
"name": "DegradedStage",
"signature": [
- "\"embed_unavailable\" | \"embed_timeout\" | \"expansion_failed\" | \"expansion_partial\" | \"rescore_skipped\" | \"vector_arm_failed\" | \"keyword_arm_failed\" | \"title_arm_failed\" | \"budget_dropped_all\" | \"budget_truncated\" | \"keyword_zero\" | \"cache_prestamp\" | \"reranker_skipped\" | \"rerank_passthrough\" | \"rerank_failed\" | \"keyword_relaxed_carried\" | \"safe_index_pending\" | \"vector_candidates_incomplete\" | \"keyword_candidates_incomplete\" | \"projection_pending\" | \"projection_by_design\" | \"projection_status_unknown\" | \"keyword_count_unavailable\" | \"saved_facts_withheld\" | \"fact_observed_date_unavailable\""
+ "\"embed_unavailable\" | \"embed_timeout\" | \"expansion_failed\" | \"expansion_partial\" | \"rescore_skipped\" | \"vector_arm_failed\" | \"keyword_arm_failed\" | \"title_arm_failed\" | \"budget_dropped_all\" | \"budget_truncated\" | \"keyword_zero\" | \"cache_prestamp\" | \"reranker_skipped\" | \"rerank_passthrough\" | \"rerank_failed\" | \"keyword_relaxed_carried\" | \"safe_index_pending\" | \"vector_candidates_incomplete\" | \"keyword_candidates_incomplete\" | \"projection_pending\" | \"projection_by_design\" | \"projection_status_unknown\" | \"keyword_count_unavailable\" | \"saved_facts_withheld\" | \"fact_observed_date_unavailable\" | \"contested_unavailable\""
]
},
{
"kind": "interface",
"members": [
"reason?: \"candidate_budget\" | \"iterative_scan_unavailable\" | \"timeout\" | \"provider_error\" | \"no_provider\" | \"variant_embed_failed\" | \"original_embed_failed\" | \"first_result_truncated\" | \"no_key\" | \"empty_result_set\" | \"malformed_shape\" | \"budget\" | \"rate_limited\" | \"unreachable\" | \"auth\" | \"egress_denied\" | \"embedding_disabled\" | \"skipped_after_timeout\" | undefined",
- "stage: \"embed_unavailable\" | \"embed_timeout\" | \"expansion_failed\" | \"expansion_partial\" | \"rescore_skipped\" | \"vector_arm_failed\" | \"keyword_arm_failed\" | \"title_arm_failed\" | \"budget_dropped_all\" | \"budget_truncated\" | \"keyword_zero\" | \"cache_prestamp\" | \"reranker_skipped\" | \"rerank_passthrough\" | \"rerank_failed\" | \"keyword_relaxed_carried\" | \"safe_index_pending\" | \"vector_candidates_incomplete\" | \"keyword_candidates_incomplete\" | \"projection_pending\" | \"projection_by_design\" | \"projection_status_unknown\" | \"keyword_count_unavailable\" | \"saved_facts_withheld\" | \"fact_observed_date_unavailable\""
+ "stage: \"embed_unavailable\" | \"embed_timeout\" | \"expansion_failed\" | \"expansion_partial\" | \"rescore_skipped\" | \"vector_arm_failed\" | \"keyword_arm_failed\" | \"title_arm_failed\" | \"budget_dropped_all\" | \"budget_truncated\" | \"keyword_zero\" | \"cache_prestamp\" | \"reranker_skipped\" | \"rerank_passthrough\" | \"rerank_failed\" | \"keyword_relaxed_carried\" | \"safe_index_pending\" | \"vector_candidates_incomplete\" | \"keyword_candidates_incomplete\" | \"projection_pending\" | \"projection_by_design\" | \"projection_status_unknown\" | \"keyword_count_unavailable\" | \"saved_facts_withheld\" | \"fact_observed_date_unavailable\" | \"contested_unavailable\""
],
"name": "DegradedStageEntry"
},
@@ -10180,7 +10180,7 @@
"kind": "variable",
"name": "RANKING_ONLY_DEGRADED_STAGES",
"signature": [
- "ReadonlySet<\"embed_unavailable\" | \"embed_timeout\" | \"expansion_failed\" | \"expansion_partial\" | \"rescore_skipped\" | \"vector_arm_failed\" | \"keyword_arm_failed\" | \"title_arm_failed\" | \"budget_dropped_all\" | \"budget_truncated\" | \"keyword_zero\" | \"cache_prestamp\" | \"reranker_skipped\" | \"rerank_passthrough\" | \"rerank_failed\" | \"keyword_relaxed_carried\" | \"safe_index_pending\" | \"vector_candidates_incomplete\" | \"keyword_candidates_incomplete\" | \"projection_pending\" | \"projection_by_design\" | \"projection_status_unknown\" | \"keyword_count_unavailable\" | \"saved_facts_withheld\" | \"fact_observed_date_unavailable\">"
+ "ReadonlySet<\"embed_unavailable\" | \"embed_timeout\" | \"expansion_failed\" | \"expansion_partial\" | \"rescore_skipped\" | \"vector_arm_failed\" | \"keyword_arm_failed\" | \"title_arm_failed\" | \"budget_dropped_all\" | \"budget_truncated\" | \"keyword_zero\" | \"cache_prestamp\" | \"reranker_skipped\" | \"rerank_passthrough\" | \"rerank_failed\" | \"keyword_relaxed_carried\" | \"safe_index_pending\" | \"vector_candidates_incomplete\" | \"keyword_candidates_incomplete\" | \"projection_pending\" | \"projection_by_design\" | \"projection_status_unknown\" | \"keyword_count_unavailable\" | \"saved_facts_withheld\" | \"fact_observed_date_unavailable\" | \"contested_unavailable\">"
]
},
{
@@ -10380,7 +10380,7 @@
"exact_lookup?: \"title\" | \"slug\" | \"identifier\" | undefined",
"exact_match_boost?: number | undefined",
"fact_id?: string | undefined",
- "fact_row?: { id: number; valid_from: string; valid_until: string | null; source?: string; from_quoted_page?: true; observed?: string; observed_unavailable?: true; } | undefined",
+ "fact_row?: { id: number; valid_from: string; valid_until: string | null; source?: string; from_quoted_page?: true; observed?: string; observed_unavailable?: true; contested_unavailable?: true; } | undefined",
"feedback_boost?: number | undefined",
"follow_up?: { op: \"recall\"; args: Record<string, string>; } | undefined",
"fused_score?: number | undefined",