RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
Optimizing recall for agentic RAG (#19687)
Yingfeng7bc159d64e56
diff --git a/cmd/ragflow_server.go b/cmd/ragflow_server.goindex b65f3b24f6..2248b9cc9c 100644--- a/cmd/ragflow_server.go+++ b/cmd/ragflow_server.go@@ -1401,8 +1401,18 @@ func startServer(ctx context.Context) {Handler: ginEngine,ReadHeaderTimeout: 10 * time.Second,ReadTimeout: 60 * time.Second,- WriteTimeout: 120 * time.Second,- IdleTimeout: 120 * time.Second,+ // WriteTimeout spans "request header read → response written", so it is a+ // ceiling on the WHOLE request, not on a slow client's reads. Measured+ // (2026-09-15, FRAMES 20q): three multi-hop questions take 150–225s to reach+ // their response, and at 120s the server closed the connection with no+ // response at all — the client reports+ // `RemoteDisconnected('Remote end closed connection without response')` and+ // the benchmark re-runs the whole question (max_retries: 2), so one slow+ // question cost three full pipelines. 180s clears the measured distribution's+ // middle; questions whose composition alone runs past it still need streaming+ // or a larger budget.+ WriteTimeout: 180 * time.Second,+ IdleTimeout: 120 * time.Second,}// Start server in a goroutinediff --git a/internal/rag/advanced_rag/agentic_rag_graph.go b/internal/rag/advanced_rag/agentic_rag_graph.goindex f8ebd75c1f..6877b1e954 100644--- a/internal/rag/advanced_rag/agentic_rag_graph.go+++ b/internal/rag/advanced_rag/agentic_rag_graph.go@@ -59,6 +59,7 @@ import ("ragflow/internal/common""ragflow/internal/rag/advanced_rag/harness""ragflow/internal/rag/advanced_rag/harness/orchestrator"+ "ragflow/internal/rag/advanced_rag/slots""ragflow/internal/rag/prompts""ragflow/internal/tokenizer")@@ -78,10 +79,38 @@ const (TotalBudgetS = 180.0 // whole-graph wall-clock ceiling per questionMinRoundHeadroomS = 50.0 // need at least this much left to start a new roundPassTimeoutS = 120.0 // slot research pass wall-clock- PrefetchTimeoutS = 90.0 // programmatic fan-out fetch- DraftTimeoutS = 60.0 // fallback draft synthesis- SCATimeoutS = 60.0 // sufficient-context review call- RewriteTimeoutS = 45.0 // gap → query rewrite call+ // SetBudgetExtensionS is added ONCE to a question's research budget when its+ // table declares a set (see RunSlotResearchPass).+ //+ // The question budget is sized for one pass (TotalBudgetS 180 ⊃ PassTimeoutS+ // 120) and an enumeration needs a second one: its first pass spends the wall+ // clock on batches of names, so a member that a cut session never patched has+ // nowhere to be picked up — measured (2026-09-16, 三国/关羽) the run ended at+ // `ROUND 1 end (unresolved=0)` with the reached-but-unpatched 管亥 gone. The+ // extension is what lets the round AFTER that one start at all: a spent pass+ // leaves ~35s and MinRoundHeadroomS is 50.+ SetBudgetExtensionS = 120.0+ // setSessionSlackS is added to the session clock a set-shaped pass hands its+ // sessions, so a session's own finalize/salvage step still fits inside the+ // context the pass derived it from.+ setSessionSlackS = 20.0+ // downstreamReserveS is what the steps AFTER research need: the SCA review+ // (SCATimeoutS), the draft and the composed answer. The budget extension is only+ // bought when the caller's own context still holds it — otherwise the second+ // research round would spend the time the answer needs, turning a missing member+ // into a timed-out question, which is strictly worse.+ downstreamReserveS = 90.0+ // minBudgetExtensionS is the smallest extension worth buying: less than this and+ // the following round could not start anyway (MinRoundHeadroomS), so the budget+ // would be widened without anything being able to use it.+ minBudgetExtensionS = 40.0+ PrefetchTimeoutS = 90.0 // programmatic fan-out fetch+ DraftTimeoutS = 60.0 // fallback draft synthesis+ SCATimeoutS = 60.0 // sufficient-context review call+ RewriteTimeoutS = 45.0 // gap → query rewrite call+ // RollCallTimeoutS bounds the member roll call (see RollCallMembers): it runs before the answer+ // is composed, so it may not spend the clock the answer needs.+ RollCallTimeoutS = 30.0// SCAViewCap: 24 of 225 hid the answer-bearing table chunk from the SCA.SCAViewCap = 60// MaxSnippetPool is the storage ceiling of the snippet pool across ALL@@ -118,9 +147,19 @@ const ()// Verdict statuses.+//+// VerdictUnknown exists because the third case is not a judgement: when the+// review could not run (timeout, unparsable reply, no model), that is "we did+// not ask", not "the evidence is insufficient". Collapsing the two has a cost+// that was measured (2026-09-15): the review timed out, the fallback verdict+// INSUFFICIENT marked the answer PARTIAL ("some gaps remain") on no evidence at+// all, and the same value was supposed to drive another research round it could+// not afford. A verdict that is not a judgement must not read like one anywhere+// downstream.const (VerdictSufficient = "SUFFICIENT"VerdictInsufficient = "INSUFFICIENT"+ VerdictUnknown = "UNKNOWN")// ---------------------------------------------------------------------------@@ -439,6 +478,45 @@ func (s *AgenticState) RemainingS() float64 {return d}+// ExtendDeadline adds seconds to the research budget, and reports whether THIS call+// was the one that did it. At most one extension per question.+//+// Only a set-shaped table asks for it (see RunSlotResearchPass), and for a measured+// reason: the budget fits one pass, an enumeration needs two, and the members a cut+// first pass never patched are exactly what the second pass picks up. One extension+// rather than a per-round top-up is deliberate — the point is to give the mislaid+// members a second look, not to let a table that keeps declaring a set run forever.+func (s *AgenticState) ExtendDeadline(seconds float64) bool {+ if s.DeadlineExtended || seconds <= 0 {+ return false+ }+ s.DeadlineExtended = true+ if s.Deadline.IsZero() {+ s.Deadline = time.Now()+ }+ s.Deadline = s.Deadline.Add(time.Duration(seconds * float64(time.Second)))+ return true+}++// ctxRoomS reports how many seconds a context still has, and whether it is bounded+// at all: an unbounded caller owns no deadline, so nothing here can overrun it.+func ctxRoomS(ctx context.Context) (float64, bool) {+ if ctx == nil {+ return 0, false+ }+ dl, ok := ctx.Deadline()+ if !ok {+ return 0, false+ }+ return time.Until(dl).Seconds(), true+}++// ctxLeftS is ctxRoomS for a log line: seconds left, zero when unbounded.+func ctxLeftS(ctx context.Context) float64 {+ room, _ := ctxRoomS(ctx)+ return room+}+// bounded mirrors Python _bounded: run fn under a wall-clock bound.// On expiry it logs and returns the zero value, so one slow step never stalls// the whole question. A non-positive bound means "no bound".@@ -501,16 +579,28 @@ type AgenticState struct {PartialAnswer boolAbstain boolEmptyResult bool- Verdict string // VerdictSufficient / VerdictInsufficient+ Verdict string // VerdictSufficient / VerdictInsufficient / VerdictUnknownSCA map[string]any// ── budgets & counters ──- MaxLoops int- Deadline time.Time // wall-clock expiry of the research budget- SearchRounds int // completed SCA→query_rewrite iterations- SCAViewID string // identity of the last SCA review view- Attempted []map[string]any- NoProgress bool+ MaxLoops int+ Deadline time.Time // wall-clock expiry of the research budget+ // DeadlineExtended records that a set-shaped table already bought the one-shot+ // budget extension (see ExtendDeadline). It belongs to the QUESTION, not to a+ // single round: applying it per round would let a table that keeps declaring a+ // set buy round after round on a budget sized for one.+ DeadlineExtended bool+ SearchRounds int // completed SCA→query_rewrite iterations+ SCAViewID string // identity of the last SCA review view+ Attempted []map[string]any+ NoProgress bool+ // LastRoundNew is how many chunks the last research round ADDED to the pool.+ //+ // It is the loop's one non-subjective signal about whether to keep going: a+ // round that is still adding evidence is still learning, whatever the+ // reviewer thinks of the passages it holds (see routeSCA). Zero means the+ // round learned nothing, which is what NoProgress already means.+ LastRoundNew int}// NewAgenticState builds the initial state. It does NOT arm the global budget:@@ -1426,8 +1516,15 @@ func ragAgentNode(ctx context.Context, deps RAGTools, st *AgenticState, logger *callCtx, cancel := context.WithTimeout(ctx, time.Duration(t*float64(time.Second)))defer cancel()- res := RunSlotResearchPass(callCtx, deps.sessionDeps(), st.Question, st, t)+ res := RunSlotResearchPass(callCtx, ctx, deps.sessionDeps(), st.Question, st, t)if res == nil {+ // "Nothing to do" is still a ROUND, and the round's growth fact belongs to+ // this round, not the previous one: leaving LastRoundNew alone made the+ // routing read a stale `grew` (measured: round 2 reported round 1's +40+ // chunks and asked for a third round on evidence it had not gathered).+ if st.KB != nil {+ st.LastRoundNew = len(st.KB.Chunks) - poolBefore+ }return}st.SlotTable = res.SlotTable@@ -1443,10 +1540,20 @@ func ragAgentNode(ctx context.Context, deps RAGTools, st *AgenticState, logger *if res.SlotDraft != "" {st.RagAnswer = res.SlotDraft}+ // The ANSWER prompt reads this one, not the draft: a draft carries the SCA's+ // machine fields, and handing them over as a "summary" put the runtime's+ // bookkeeping into the answer (see RenderSlotRecord).+ if res.SlotRecord != "" && st.KB != nil {+ st.KB.Record = res.SlotRecord+ }st.Attempted = res.Attempted+ // The round's growth is the loop's continuation fact (see routeSCA): stored+ // on the state rather than only printed, so the routing decision reads the+ // same number the log shows.+ st.LastRoundNew = len(st.KB.Chunks) - poolBeforelogger.Printf("[RAGAgent] ROUND %d end (+%d new chunks, pool=%d, unresolved=%d)",- roundNo, len(st.KB.Chunks)-poolBefore, len(st.KB.Chunks), len(res.UnresolvedSlots))+ roundNo, st.LastRoundNew, len(st.KB.Chunks), len(res.UnresolvedSlots))}// draftNode mirrors the `draft` node: the intermediate draft that the@@ -1522,13 +1629,19 @@ func scaNode(ctx context.Context, deps RAGTools, st *AgenticState, logger *log.Lst.SCAViewID = viewIDst.SCA = scaResultToMap(res)if len(st.SCA) == 0 {- // sca — an unavailable SCA (timeout, unparsable reply, no- // model) is INSUFFICIENT, so the unresolved slots can drive another- // research round. Accepting the draft here would ship an unverified- // answer as if the review had passed it.- logger.Printf("[SCA] unavailable; marking INSUFFICIENT so unresolved slots can drive another research round.")+ // sca — an unavailable SCA (timeout, unparsable reply, no model) is NOT a+ // verdict: it is the absence of one. Marking it INSUFFICIENT used to be+ // the fallback, and it read as a judgement everywhere downstream — the+ // answer was labelled PARTIAL on no evidence (formalizeAnswerNode) and+ // the loop was told to research again by a review that never ran+ // (measured 2026-09-15: review timed out at 35s and the run closed out+ // with zero seconds left, so the "insufficiency" was never actionable+ // either). VerdictUnknown keeps the two apart; the loop's own record+ // (growth + gaps) decides whether another round is worth its budget, and+ // the deliverable is not dressed up as partly-unverified.+ logger.Printf("[SCA] unavailable (no review could be completed); recording UNKNOWN — this is not a sufficiency judgement, so the round's own record drives the loop.")st.SCA = map[string]any{}- st.Verdict = VerdictInsufficient+ st.Verdict = VerdictUnknownreturn}if res.IsSufficient {@@ -1631,7 +1744,12 @@ func queryRewriteNode(ctx context.Context, deps RAGTools, st *AgenticState, logg// Dual-track pursuit of the gap: (a) programmatically pre-fetch new snippets// into the SCA pool; (b) the next slot research pass picks these up via the// persisted slot_table + unresolved_slots.- added := FanoutSearch(callCtx, deps, st, queries, FanoutTopNRewrite, MaxSnippetPool)+ // Room is measured against the EVIDENCE POOL's ceiling, the same number the+ // admitter enforces. Sized against the smaller snippet-pool constant, a rich+ // round got room <= 0 and admitted nothing, so the round reported "retrieval+ // saturated" and discarded itself while the pool still had room to take the+ // evidence it had just asked for.+ added := FanoutSearch(callCtx, deps, st, queries, FanoutTopNRewrite, harness.EvidencePoolCap())// Retrieval saturation early-exit: a rewrite round that produced ZERO new// snippets means further full research passes just burn latency.if added == 0 && st.SearchRounds >= 1 {@@ -1703,7 +1821,27 @@ func queryRewriteNode(ctx context.Context, deps RAGTools, st *AgenticState, logg// scope here — it needs the report prompt templates; the caller reads the// approved draft from st.KB.PreSummary.func formalizeAnswerNode(ctx context.Context, deps RAGTools, st *AgenticState, logger *log.Logger) {- if st.NoProgress || st.Verdict == VerdictInsufficient {+ // The member ROLL CALL runs here — after the research, before the answer — because the+ // write-back is the one step the evidence cannot do for itself: measured (2026-09-16,+ // 三国/关羽) runs of ONE build answered 18 / 16 / 15 / 14 / 12 members with the same corpus in+ // hand, and what differed was what a session remembered to patch (see RollCallMembers). It is+ // the last moment at which the candidate set is complete and the members still reach everything+ // downstream: the count reconciliation, the record the answer reads, and the answer itself.+ if rc := RollCallMembers(ctx, deps, st, logger); rc.Asked > 0 {+ logger.Printf("[RollCall] done: asked=%d answered=%d written=%d", rc.Asked, rc.Answered, rc.Written)+ }++ // "Partial" is a statement about the EVIDENCE, so it is decided by facts rather+ // than by a verdict that may not exist: unresolved slots are the table's own+ // list of what it could not fill, NoProgress means the last round learned+ // nothing, and INSUFFICIENT is the reviewer's judgement when it made one.+ //+ // A review that could not run (VerdictUnknown) says NOTHING about completeness,+ // and treating it as insufficiency is how the 2026-09-15 run shipped+ // "partial answer, some gaps remain" on no evidence at all: the SCA had timed+ // out, and the only thing that knew about the gaps was the answer's own+ // distance from the question.+ if st.NoProgress || st.Verdict == VerdictInsufficient || len(st.UnresolvedSlots) > 0 {// All research attempts exhausted without a satisfying context — surface// the residual findings honestly instead of refusing.st.PartialAnswer = true@@ -2028,6 +2166,10 @@ func verdictStatusHint(verdict string) string {switch verdict {case VerdictInsufficient:return "evidence is not yet sufficient"+ case VerdictUnknown:+ // Not a judgement: the review did not complete, so nothing here may claim+ // the evidence was found wanting (nor that it was sufficient).+ return "the evidence review did not complete, so sufficiency is unverified"default:return "sufficiency status: " + verdict}@@ -2072,8 +2214,25 @@ func renderResearchContext(st *AgenticState) string {}historyLines = append(historyLines, fmt.Sprintf("- %s (round %s: %s)", q, r, outcome))}+ // The passages behind the members already confirmed come FIRST, because they+ // are the only place the rewriter can see (a) the wording this text uses for+ // the relation and (b) the names that are still missing. Those passages are+ // exactly the windows the seats were narrowed to (see+ // Kbinfos.RecordReachedTerm), so a name inside one of them is readable.+ //+ // The pool-head lines below are the fallback for a round that has confirmed+ // nothing yet. They are FIRST LINES only, so a name in the middle of a chunk+ // is invisible through them — which is why they are the fallback and not the+ // main channel.+ var memberLines []string+ for i, m := range memberLinesOf(st) {+ if i >= MemberWindowMax {+ break+ }+ memberLines = append(memberLines, "- "+m)+ }var poolLines []string- if st.KB != nil {+ if len(memberLines) == 0 && st.KB != nil {for i, c := range st.KB.Chunks {if i >= PoolHeadLines {break@@ -2098,41 +2257,176 @@ func renderResearchContext(st *AgenticState) string {if len(historyLines) > 0 {parts = append(parts, "Previously searched queries and their outcomes:\n"+strings.Join(historyLines, "\n"))}+ if len(memberLines) > 0 {+ parts = append(parts, "Passages that carry names the searches ALREADY confirmed (read them for the wording this text uses for the relation, and for other names they mention — any of those can be asked about directly):\n"+strings.Join(memberLines, "\n"))+ }if len(poolLines) > 0 {parts = append(parts, "Evidence currently at hand (first lines of top stored snippets):\n"+strings.Join(poolLines, "\n"))}+ // The round's own record of what its probes ASKED and never reached. The+ // rewriter reads it for one reason: re-asking a name the corpus already came+ // back empty on is the loop's most common waste, and the productive move from+ // a dead name is a different ANGLE (the act, the relationship, the place),+ // which the rewriter cannot choose unless it knows the name is dead.+ if absent := st.KB.ProbedAbsentTerms(); len(absent) > 0 {+ parts = append(parts, "Terms already asked for and NOT reached by any passage (do NOT re-ask these on their own; ask for the act / relationship / place instead):\n"+strings.Join(absent, "、"))+ }return strings.Join(parts, "\n\n")}+// MemberWindowMax bounds how many confirmed-member passages the rewrite context+// carries, and MemberWindowChars how much of each.+const (+ MemberWindowMax = 12+ MemberWindowChars = 220+)++// memberLinesOf renders one line per confirmed member: the name, and the window+// that carries it, looked up in the pool by the id the seat recorded.+//+// It reads the round's own record rather than re-searching anything: a seat IS a+// probe of one individual that came back with a passage, so the pair (name,+// passage) is already established by the time the rewrite runs.+func memberLinesOf(st *AgenticState) []string {+ if st == nil || st.KB == nil {+ return nil+ }+ byID := make(map[string]map[string]any, len(st.KB.Chunks))+ for _, c := range st.KB.Chunks {+ if id := harness.ChunkIDOf(c); id != "" {+ byID[id] = c+ }+ }+ var out []string+ seen := map[string]bool{}+ for _, m := range st.KB.ReachedTerms() {+ if seen[m.ChunkID] {+ continue+ }+ c, ok := byID[m.ChunkID]+ if !ok {+ continue+ }+ text := strings.TrimSpace(harness.ChunkTextOf(c))+ if text == "" {+ continue+ }+ seen[m.ChunkID] = true+ out = append(out, fmt.Sprintf("%s: %s", m.Term, truncateRunes(text, MemberWindowChars)))+ }+ return out+}+// routeSCA mirrors Python _route_sca.func routeSCA(st *AgenticState, enableSCA bool, scaMaxRounds int) agenticNode {if st.NoProgress {return nodeFormalizeAnswer}- // Evidence pool saturated at the SCA view cap: any further chunk lands- // beyond what the SCA can read, so another search round cannot flip the- // sufficiency verdict. Gated to SECOND-or-later reviews on THIS branch:- // claim pseudo-chunks bypass the pool cap (direct append in the claim- // prefetch), so a rewrite round can still add evidence — the FIRST SCA- // review must always get its rewrite round when insufficient, or hard- // multi-hop questions lose their only refinement pass and the retry moves- // to the outer agent as a whole new graph run (Python _route_sca:1411).- if st.KB != nil && len(st.KB.Chunks) >= SCAViewCap && st.SearchRounds >= 1 {- _LOG.Printf("[SCA] evidence pool FULL (%d chunks >= SCA view cap %d); early-stopping to finalize_answer.", len(st.KB.Chunks), SCAViewCap)- return nodeFormalizeAnswer- }+ // There is deliberately NO pool-SIZE guard here.+ //+ // The question a stop has to answer is "can another round change the+ // verdict?", and the pool size is not that question: what the SCA reads is+ // the selected VIEW (ranked, capped at SCAViewCap), and a view made of 60+ // usable passages is equally full whether the pool behind it holds 60 or 200+ // chunks. The old guard used `len(chunks) >= SCAViewCap` as a proxy for+ // "nothing readable can be added", and the two are different facts: a pool of+ // 160 whose view CHANGED has new evidence the reviewer can read, while a pool+ // of 59 whose new chunk ranks below the view has none.+ //+ // The real question is answered exactly, one node earlier: scaNode hashes the+ // selected view and compares it with the previous review's, then sets+ // NoProgress on a match ("same view twice despite new storage — further+ // rounds cannot change the verdict"), which this function's first check+ // honours. Measured (fixrecall, 2026-09-14): a round of batch name probing+ // ended at 117 chunks — three short of the pool CAP — with the question's+ // members still arriving, and the size guard finalized the run instead of+ // letting the next round verify them.+ //+ // What still bounds the loop is unchanged: an INSUFFICIENT verdict, the+ // round count, the round-headroom guard below, and NoProgress (which covers+ // an unchanged view, no concrete gap, no actionable query, and a rewrite that+ // retrieved nothing new).if !enableSCA {// medium: single research pass — the SCA verdict is informational only.return nodeFormalizeAnswer}- if st.Verdict == VerdictInsufficient &&- st.SearchRounds < scaMaxRounds &&- // Budget guard: only start another rewrite+research round when enough- // headroom remains for the whole round.- st.RemainingS() > MinRoundHeadroomS {- return nodeQueryRewrite+ // Whether to spend another round is decided by the ROUND'S OWN RECORD, and the+ // reviewer's verdict is only one of its inputs:+ //+ // work left — the slot table still lists unresolved slots. This is the+ // framework's own statement that something is missing, and+ // it is what keeps an ANCHORED rewrite possible at all.+ // still learning — the round added evidence (+N chunks). An empty+ // unresolved list is NOT proof of completeness (the+ // 2026-09-15 run ended with unresolved=0 while the answer+ // was six members short), and a satisfied reviewer is a+ // judgement about the PASSAGES it read, not about whether+ // the record is finished.+ //+ // The two combine into the rule this function applies:+ //+ // work left AND still learning → another round, even if the reviewer said+ // SUFFICIENT: it judged the passages, and+ // the table says the question is not done.+ // work left AND stalled → the reviewer decides: an INSUFFICIENT+ // verdict with a concrete gap is a reason to+ // go round again; anything else closes out.+ // nothing left → close out (a settled table with no+ // verdict against it).+ // UNKNOWN → not a judgement either way: only the+ // record above can ask for another round.+ //+ // Every branch logs which fact decided, because "the loop ended" is otherwise+ // indistinguishable from "the loop could not afford to continue" — and that+ // silence already cost a run (2026-09-15: the reviewer returned INSUFFICIENT at+ // confidence 1.00 with four concrete gaps, the run closed out with 60s and two+ // rounds unspent, and nothing in the log said why).+ //+ // "Work" is the union of the TWO records that can name a direction: the slot+ // table's unresolved slots, and the gaps the REVIEW extracted (SCAGapsToRewrite+ // over its own sub_queries). Dropping the second one is what made an+ // INSUFFICIENT verdict with concrete gaps unable to ask for the round it was+ // pointing at.+ gapList := SCAGapsToRewrite(st.SCA)+ if len(gapList) == 0 {+ gapList = unresolvedClueGaps(st)+ }+ gaps := len(gapList)+ // COVERAGE is not a record here any more: a direction that DECLARED act words asks the+ // corpus the pattern queries its seed carries (harness.ScanPatterns) and reads the+ // windows they return, so "how much of the corpus has been read" is not a state the loop+ // has to hold — and holding it was what kept a round alive after the reading was done+ // (measured 2026-09-16, 三国/关羽: rounds whose whole work was re-reading the same list).+ work := gaps > 0 || len(st.UnresolvedSlots) > 0+ grew := st.LastRoundNew > 0+ verdictAsks := st.Verdict == VerdictInsufficient && work+ wants := work && (grew || verdictAsks)+ if !wants {+ _LOG.Printf("[Routing] closing out: no round is asked for (unresolved=%d, gaps=%d, +%d chunks this round, verdict=%s).",+ len(st.UnresolvedSlots), gaps, st.LastRoundNew, st.Verdict)+ return nodeFormalizeAnswer}- return nodeFormalizeAnswer+ if st.SearchRounds >= scaMaxRounds {+ _LOG.Printf("[Routing] work remains (unresolved=%d, gaps=%d, +%d chunks this round, verdict=%s) but the round budget is spent (%d/%d); closing out.",+ len(st.UnresolvedSlots), gaps, st.LastRoundNew, st.Verdict, st.SearchRounds, scaMaxRounds)+ return nodeFormalizeAnswer+ }+ if st.RemainingS() <= MinRoundHeadroomS {+ _LOG.Printf("[Routing] work remains (unresolved=%d, gaps=%d, +%d chunks this round, verdict=%s) but only %.0fs left (need %.0fs); closing out.",+ len(st.UnresolvedSlots), gaps, st.LastRoundNew, st.Verdict, st.RemainingS(), MinRoundHeadroomS)+ return nodeFormalizeAnswer+ }+ if st.KB != nil && len(st.KB.Chunks) >= SCAViewCap {+ // The case the pool-size guard used to end silently: the pool is past what+ // the view can hold, yet this round's view CHANGED (scaNode did not set+ // NoProgress), so the new evidence is readable and a further round can act+ // on it.+ _LOG.Printf("[SCA] pool holds %d chunk(s) (>= view cap %d) but this round's review view CHANGED; the new evidence is readable, so another round is worth its budget.",+ len(st.KB.Chunks), SCAViewCap)+ }+ _LOG.Printf("[Routing] another round: unresolved=%d, gaps=%d, +%d chunks this round, verdict=%s, rounds=%d/%d, %.0fs left.",+ len(st.UnresolvedSlots), gaps, st.LastRoundNew, st.Verdict, st.SearchRounds, scaMaxRounds, st.RemainingS())+ return nodeQueryRewrite}// routeRewrite mirrors Python _route_rewrite.@@ -2205,6 +2499,348 @@ func RenderSlotDraft(slotTable harness.State, collectedAnswer string, slotEvidenreturn strings.Join(lines, "\n")}+// RenderSlotRecord renders the slot table for the ANSWER prompt.+//+// It is deliberately NOT RenderSlotDraft. The draft exists for the SCA, which+// verifies a candidate against the passages that produced it, so it carries the+// machine fields that make that verification possible — the candidate strength,+// the terminal type, the evidence ids. Handing those to the answer model is a+// different act with a different failure mode, and it was measured: composing+// with the draft as "Research Summary (primary evidence)" produced an answer that+// quoted the bookkeeping verbatim ("slot 1 [entity] … (strength=0.90)+// [terminal=state, evidence_ids=[…]]").+//+// So the answer sees the FACTS the research settled — which slot holds what —+// with no strength, no evidence ids, no clue tails: the evidence ids are already+// in the evidence block with their citation markers, and the strengths are the+// runtime's business. The prompt labels the block as the model's own record and+// tells it not to copy the lines (see answerPromptWithEvidence).+func RenderSlotRecord(slotTable harness.State, collectedAnswer string) string {+ var lines []string+ // Is this record about a SET at all? Everything this function does beyond the+ // slots themselves — the enumerated size, the count/members warning, the+ // demotion of the session's own prose — is about reconciling a list with a+ // count, and a single-value question has neither.+ //+ // Measured (2026-09-15, FRAMES): rendered ungated, the enumerated line appeared+ // in 21 of 20 questions' records and the prose demotion in 9, on questions whose+ // answer is one date or one number. One of them is worth quoting because it is+ // the shape of the mistake: a "how much shorter is A than B" record carried+ // `- slot 1 [number]: 133 feet` beside `- enumerated members across the slots+ // above: 16`, where the 16 was `Grace's、High、Falls、Colonial、Creek` — one+ // waterfall's name, cut at its separators by whoever wrote it into the slot.+ // The session's draft answer was then labelled UNVERIFIED and demoted below it.+ setShaped := harness.SetShaped(slotTable)+ if !setShaped && collectedAnswer != "" {+ // A value record leads with the session's own answer, exactly as it did+ // before any of this existed (see the note on the demotion below for why the+ // SET case is different).+ lines = append(lines, "Candidate answer: "+collectedAnswer)+ lines = append(lines, "")+ }+ for _, v := range slotTable.State {+ vtype := v.Type+ if vtype == "" {+ vtype = "entity"+ }+ if v.Candidate == nil || *v.Candidate == "" {+ lines = append(lines, fmt.Sprintf("- slot %d [%s]: NOT RESOLVED", v.ID, vtype))+ } else {+ lines = append(lines, fmt.Sprintf("- slot %d [%s]: %s", v.ID, vtype, *v.Candidate))+ }+ // Claims that lost the slot comparison (see MergeSlotPatch). They are not+ // the slot's value, but they are not nothing either: a session produced+ // them from the same corpus, and a name only in an alternate is a name the+ // answer has to account for.+ for _, alt := range alternateCandidatesOf(v) {+ lines = append(lines, " alternate (claimed by another session, not adopted): "+truncateRunes(alt, 400))+ }+ }+ // The size of the set the slots above ENUMERATE — a fact the answer can take a+ // number from without trusting anybody's prose.+ //+ // A count slot is written by whichever session last touched it, and that+ // candidate can be a sentence ("约 14 人(华雄、程远志…)"), a stale number, or+ // one session's claim written before the other sessions' findings were merged.+ // The members are here in the table either way, so their union is the number+ // the record can stand behind.+ if n := enumeratedSize(slotTable); setShaped && n > 0 {+ lines = append(lines, fmt.Sprintf("- enumerated members across the slots above: %d", n))+ // A set answer is only as good as what it can point at, member by member.+ // Measured (2026-09-16): handed a list of names and no per-member evidence,+ // an answer reported "21 listed, four counted but not listed" and cited ONE+ // evidence range for all of them. The citation contract already forbids+ // ranges; this states it where a set answer is assembled, together with the+ // rule that keeps a count honest — a member nobody can point at a passage is+ // not counted.+ lines = append(lines, "State the count and the members TOGETHER: every member you list carries the words behind it (quoted above, or its own [ID:n]) — never one range for the list — and a member you cannot point at a passage for is left out of both the list and the count.")+ // A count larger than the members it counts is a claim about members that+ // are NOT in the record, and the answer has to be told that rather than left+ // to reconcile it. Measured (2026-09-15): a record whose count slot read 19+ // while its slots enumerated 12 produced an answer of nineteen people, which+ // then explained the gap as "seven more whose details the material does not+ // list" — seven members that never existed.+ //+ // The note STATES the disagreement; it does not order which number to take.+ // An order was tried and reverted: measured (2026-09-16, 三国/关羽) a record+ // whose enumerated number had been computed over the wrong slots said "take+ // the number from the enumerated members", and the answer took it — nine, for+ // a question whose sessions had enumerated fourteen. A count can be an+ // over-claim and a list can be incomplete; only the passages decide between+ // them, and the answer is the stage that reads them.+ for _, v := range slotTable.State {+ // A DECLARED number (slots.KindCount / KindRange) compared with the members+ // above. Text claims no number, so prose can no longer masquerade as a+ // count here (or as a member list on the other side of the comparison).+ if claimed, ok := v.Typed().Number(); ok && claimed != n {+ lines = append(lines, fmt.Sprintf(+ "- NOTE: slot %d [%s] says %d while the slots above enumerate %d — the count and the members listed disagree. Reconcile them against the evidence before answering: a count larger than the members that are listed is not evidence of members, and a list is only as complete as the passages behind it.",+ v.ID, v.Type, claimed, n))+ }+ }+ }+ // A session's own draft answer goes LAST and is labelled for what it is.+ //+ // It used to lead the record, and the answer copied it: measured twice+ // (2026-09-15, 三国演义/关羽) — a record whose slots enumerated seventeen+ // members produced a fifteen-member answer, and a record enumerating fourteen+ // produced a ten-member answer, in both cases exactly the number written in the+ // session's own prose. The prose is one session's recollection, written before+ // the other sessions' findings were merged into the table above; it is a claim+ // to reconcile with the members, not the record.+ //+ // On a VALUE record there are no members to reconcile against — the prose is the+ // only candidate answer the record has, so it leads the record instead (see the+ // top of this function), which is also what every run before the demotion scored+ // on.+ if collectedAnswer != "" && setShaped {+ lines = append(lines, "")+ // The draft is not a member LIST — copying its prose is how a fifteen-member answer+ // came out of a seventeen-member record — but the PASSAGES it quotes are evidence+ // like any other, and a name those passages attribute to the actor is a member even+ // when no slot above lists it. Measured (2026-09-16, 三国/关羽, two runs of one+ // question): one record enumerated 17 members and answered 17; another enumerated 10+ // while its own draft carried the original text for four more (管亥 / 荀正 / 车胄 /+ // 杨龄), and the answer — told that "the members stand" — dropped all four. The+ // evidence was in hand; the rule threw it away. So the draft is demoted as a SOURCE+ // of members and promoted as evidence: its quotations are the arbiter, and neither+ // the slots nor the draft decides on its own.+ lines = append(lines, "One session's own draft answer (UNVERIFIED — written before the other sessions were merged. Its PROSE is not a member list: do not copy its count or its wording. Its QUOTATIONS are evidence like any other: a name those passages attribute to the actor is a member even when no slot above lists it, and a name whose passage attributes the deed to someone else is not. Reconcile the draft with the slots — with the quotations as the arbiter, not either list — and include every member the evidence supports): "+collectedAnswer)+ }+ return strings.Join(lines, "\n")+}++// enumeratedSize is how many distinct members the table's slots enumerate: the+// union of every list-valued candidate, count values excluded (a number is a claim+// about the set, not a member of it).+func enumeratedSize(table harness.State) int { return len(memberUnion(&table)) }++// memberUnion is the set of member NAMES the table enumerates: every slot's+// name-like pieces, deduped, minus the pieces that merely CONTAIN a member.+//+// The last clause is what keeps a phrase out of the count. A session writing a+// place beside its owner (`洛阳关孟坦`) or an event beside its object+// (`温酒斩华雄`) writes a token that is short, digit-free and unpunctuated — it+// passes every shape test a name passes — yet it is not a second member: the+// member it names is already in the table. Measured (2026-09-16): a record whose+// slots enumerated 21 names counted 25, the four extra being `洛阳关孟坦`,+// `汜水关卞喜`, `荥阳王植`, `黄河渡口秦琪`.+func memberUnion(table *harness.State) []string {+ if table == nil {+ return nil+ }+ var items []string+ for _, v := range table.State {+ // DECLARED members only (slots.KindMembers). Nothing is parsed to find them:+ // a slot holds members because the model said so, each with its evidence, and+ // a slot holding text — a phrase, a sentence, a count, a date — contributes+ // none. That is what makes the count derived and the members accountable: with+ // no text inspection there is no rule left to misfire (measured 2026-09-16,+ // 三国/关羽: a count slot holding "约 17-19 人" was split into "约、人" and+ // counted as two members while fifteen real names sat in another slot).+ if v.Typed().Kind != slots.KindMembers {+ continue+ }+ items = append(items, v.Typed().Names()...)+ }+ items = dedupe(items)+ out := make([]string, 0, len(items))+ for _, item := range items {+ contained := false+ for _, other := range items {+ if other == item || len([]rune(other)) >= len([]rune(item)) {+ continue+ }+ if strings.Contains(item, other) {+ contained = true+ break+ }+ }+ if !contained {+ out = append(out, item)+ }+ }+ return out+}++// composedRecord is the record block the ANSWER prompt carries: the slot record+// plus the probe ledger.+//+// The prompt builder and the log both call it, because they disagreed once: the+// log reported `record_len=225` (the slots alone) while the prompt carried the+// ledger too, so the one line meant to show what the answer was given could not+// answer the only question asked of it.+func composedRecord(kb *harness.Kbinfos) string {+ if kb == nil {+ return ""+ }+ record := strings.TrimSpace(kb.Record)+ if ledger := probeLedger(kb); ledger != "" {+ if record != "" {+ record += "\n"+ }+ record += ledger+ }+ return record+}++// probeLedger renders the names the research PROBED — the terms the model itself+// asked the corpus about, with what came back.+//+// It exists because the slots are the model's own bookkeeping and the ledger is+// the framework's: a run can probe twenty-four terms, get a passage for each, and+// record eleven of them in a slot, and then the answer is composed from the+// eleven while the other thirteen exist only inside the pool. Measured+// (fixrecall2, 2026-09-15): `members=0 reached=24` at the last turn, eleven names+// in the final record, and 车胄 / 管亥 both proven present by the run's own probes+// (`carry: 车胄(7) 管亥(3)`) yet absent from the answer — which meanwhile anchored+// on the model's own PRIOR, delivered through a slot nobody could verify.+//+// The wording keeps the two lists apart on purpose. "Reached" is a fact about the+// corpus; "belongs in the answer" is a judgement the answer still has to make.+// And a term that was probed with nothing back is a fact about the QUERY — the+// distinction the whole loop depends on, since reading it as absence is what+// stops an enumeration short.+func probeLedger(kb *harness.Kbinfos) string {+ if kb == nil {+ return ""+ }+ var b strings.Builder+ if reached := kb.ReachedTerms(); len(reached) > 0 {+ // Per-member quotes are for a SET answer, which is the only answer that has+ // to point at a passage per item. On a value direction they would be prompt+ // tokens bought for nothing, so the quotes ride the same shape gate as the+ // rest of the set machinery (the direction declares itself once, see+ // Kbinfos.MarkSetDirection). The names stay in both cases: they are what the+ // ledger has always been.+ quoted := kb.IsSetDirection()+ terms := make([]string, 0, len(reached))+ for _, rt := range reached {+ // The name AND the words that prove it. Without the words the answer has+ // a list of names and no way to point at a passage for any one of them,+ // which is what a set answer needs to carry per member: measured+ // (2026-09-16) an answer that was handed names only reported "21 listed,+ // four counted but not listed" and cited one evidence RANGE for all of+ // them, instead of one citation per member.+ if quoted && len(terms) < ledgerQuoteMembers {+ if quote := ledgerQuote(kb, rt.ChunkID, rt.Term); quote != "" {+ terms = append(terms, fmt.Sprintf("%s — %s", rt.Term, quote))+ continue+ }+ }+ terms = append(terms, rt.Term)+ }+ fmt.Fprintf(&b, "Probed and answered (a passage came back for each of these, so they OCCUR in the corpus; whether each belongs in the answer is still your judgement — any name here that the record above does not mention is a finding nobody recorded; the words behind each name are its evidence, and a member without words is a member nobody can point at): %s",+ strings.Join(terms, ";"))+ }+ if absent := kb.ProbedAbsentTerms(); len(absent) > 0 {+ if b.Len() > 0 {+ b.WriteString("\n")+ }+ fmt.Fprintf(&b, "Probed with NOTHING back (a fact about the query, not about the corpus — re-word it or change the angle; this is not \"absent\"): %s",+ strings.Join(absent, "、"))+ }+ return b.String()+}++// ledgerQuoteRunes bounds one member's quoted evidence, and ledgerQuoteMembers+// how many members carry a quote. Both are bounded because the ledger is part of+// the ANSWER prompt: a couple of dozen members at a few dozen runes each is the+// most a record may spend on evidence before it crowds out the question.+const (+ ledgerQuoteRunes = 40+ ledgerQuoteMembers = 24+)++// ledgerQuote is the words behind one reached term: a short window of the pool+// chunk that carries it, in the reading order of that chunk.+//+// The ledger names the members; this is what lets an answer show, member by+// member, the passage each one rests on — and lets a reader see which member has+// no words behind it at all.+func ledgerQuote(kb *harness.Kbinfos, chunkID, term string) string {+ c := kb.ChunkByID(chunkID)+ if c == nil {+ return ""+ }+ text := harness.ChunkTextOf(c)+ if text == "" {+ return ""+ }+ runes := []rune(text)+ start := 0+ if at := strings.Index(text, term); at > 0 {+ if r := utf8.RuneCountInString(text[:at]) - ledgerQuoteRunes/3; r > 0 {+ start = r+ }+ }+ end := min(start+ledgerQuoteRunes, len(runes))+ if end-start < ledgerQuoteRunes && end == len(runes) {+ start = max(0, end-ledgerQuoteRunes)+ }+ q := strings.TrimSpace(strings.ReplaceAll(string(runes[start:end]), "\n", " "))+ if q == "" {+ return ""+ }+ return "“" + q + "”"+}++// recordSource names which block the answer prompt carried, so a log reader can+// tell "the model had a slot record" from "the model had a prose summary" without+// inferring it from lengths.+func recordSource(record string) string {+ if strings.TrimSpace(record) == "" {+ return "prose-summary"+ }+ return "slot-record"+}++// recordContract labels the answer prompt's slot-record block.+//+// The line exists because "Research Summary (primary evidence)" described a+// runtime record as evidence: the model then treated its lines as findings and+// copied them. A record is not evidence — it is what the research settled — and+// the prompt has to say so, or the labels end up in the answer.+//+// "the value IS the answer" is the other half, and it is measured. A record that is+// only a check is a record the answer may drop when the passages do not repeat it,+// and the RUN's passages often do not: they were gathered to FIND the value, so the+// session that found it recorded it while the chunk that carried it never entered+// the cited evidence. Measured (2026-09-16, FRAMES, mode high): the slot table held+// `slot 0 [person]: Colin Beashel and Richard Coxon (Australia, Star class 1984+// Olympics)` — the answer — and the composed answer was "not found in the knowledge+// base", because the passages around it were about other competitions and the chat+// configuration requires that sentence when the information is unavailable (see+// web/src/locales/zh.ts).+const recordContract = "Research Record (INTERNAL — your own slot table plus the terms your probes " ++ "reached; NEVER quote these lines, their `slot N [type]` labels, or any id into the answer). " ++ "The slots are what the research SETTLED: when a slot holds a value for what the question asks, " ++ "that value IS the answer — state it, and do not report that the answer was not found while a " ++ "slot holds one; a passage that merely fails to repeat the value does not contradict it. If the " ++ "evidence plainly contradicts a settled value, answer what the evidence supports and say so. " ++ "A name listed as probed-and-answered is one the corpus was asked about and produced: if the answer " ++ "is a list or a count and that name is not in it, say why."+// draftEvidenceSuffix renders Python's " [terminal=..., evidence_ids=['a', 'b']]"// suffix; empty when the session recorded neither.func draftEvidenceSuffix(ev SlotEvidence) string {@@ -2276,7 +2912,11 @@ type SlotResearchResult struct {UnresolvedSlots []map[string]anySlotEvidence map[string]SlotEvidenceSlotDraft string- Attempted []map[string]any+ // SlotRecord is the same table rendered for the ANSWER prompt: the facts the+ // research settled, without the machine fields the SCA needs (see+ // RenderSlotRecord). The two are produced together so they cannot drift.+ SlotRecord string+ Attempted []map[string]any}// BuildSlotTable mirrors Python _build_slot_table: decompose the question into@@ -2725,13 +3365,34 @@ func PrefillSlotsFromEvidence(slotTable *harness.State, kb *harness.Kbinfos) intreturn filled}+// logCompletenessWindows writes the completeness pass's windows to the run log — the QUOTES, not+// just their count.+//+// Whether a member the answer missed was ever IN FRONT of a session is otherwise unknowable, and+// that difference decides which fault to fix: a name quoted inside a window the sessions read and+// did not write is a WRITE-BACK fault (the ledger, the record line), while a name the pass matched+// and never showed is a COVERAGE fault (the window budget). Measured (2026-09-16, 三国/关羽): runs+// of one question with the same code answered 18 / 16 / 15 / 12 members — the same eleven names+// every time, plus a different handful of the other eight (程远志 / 管亥 / 车胄 / 杨龄 / 夏侯存 /+// 成何 / 庞德 / 翟元 / 荀正) — and no line in any of those logs could say whether the missing ones+// had been shown at all. Every window change made from those logs was therefore a guess, and two of+// them were wrong.+func logCompletenessWindows(block string) {+ for _, line := range strings.Split(block, "\n") {+ trimmed := strings.TrimSpace(line)+ if strings.HasPrefix(trimmed, "- ") || strings.Contains(trimmed, "chunk_id=") {+ _LOG.Printf("[SlotResearch] completeness window %s", trimmed)+ }+ }+}+// RunSlotResearchPass mirrors Python _run_slot_research_pass: drive ONE// research round with slot-aware action sessions.//// Unresolved slots are worked concurrently under a semaphore; each session's// branches are folded back into the shared table. A nil result means "nothing to// do" (all slots already filled).-func RunSlotResearchPass(ctx context.Context, deps harness.SessionDeps, question string, st *AgenticState, deadlineLeft float64) *SlotResearchResult {+func RunSlotResearchPass(ctx context.Context, parent context.Context, deps harness.SessionDeps, question string, st *AgenticState, deadlineLeft float64) *SlotResearchResult {slotTable := st.SlotTableif len(slotTable.State) == 0 {// No planner ran (medium single-pass, or the planner failed): build the@@ -2743,10 +3404,6 @@ func RunSlotResearchPass(ctx context.Context, deps harness.SessionDeps, questionquestion = st.Question}unresolved := slotTable.Unresolved()- if len(unresolved) == 0 {- _LOG.Printf("[SlotResearch] all slots filled; no session to run.")- return nil- }// Evidence-row prefill(Python :1782-1790): slots the pooled evidence// already answers cost no action session at all — this is where whole@@ -2757,11 +3414,63 @@ func RunSlotResearchPass(ctx context.Context, deps harness.SessionDeps, question// Python :1779 — `tools.kbinfos or state.kbinfos`.kb = st.KB}- if prefillN := PrefillSlotsFromEvidence(&slotTable, kb); prefillN > 0 {+ prefillN := PrefillSlotsFromEvidence(&slotTable, kb)+ if prefillN > 0 {_LOG.Printf("[SlotResearch] evidence prefill answered %d slot(s) with no session", prefillN)unresolved = slotTable.Unresolved()}+ // The directions this round works: one per unresolved slot, and — when the+ // table is already filled — the gaps the REVIEW named.+ //+ // A filled table is not a finished round for a question whose answer slot is+ // DERIVED: a count computed from the members it found is filled by+ // construction, however few members that is, so `unresolved == 0` silently+ // cancelled rounds the routing had started precisely because the review named+ // gaps. Measured (fixrecall2, 2026-09-15): round 2 rewrote the question into+ // the right chapter-level queries, prefetched their evidence, logged "all slots+ // filled; no session to run", and spent its budget with a draft byte-identical+ // to round 1's — the passages it had just admitted were never read into the+ // record, which is the step a session exists for.+ type direction struct {+ slotID int+ text string+ }+ var dirs []direction+ for _, v := range unresolved {+ text := question+ if len(v.QuestionClues) > 0 {+ text = v.QuestionClues[0]+ }+ dirs = append(dirs, direction{slotID: v.ID, text: text})+ }+ if len(dirs) == 0 {+ for _, g := range SCAGapsToRewrite(st.SCA) {+ text := strings.TrimSpace(g.SearchHint)+ if text == "" {+ text = strings.TrimSpace(g.What)+ }+ if text == "" {+ continue+ }+ // slotID -1: a gap is not a slot, and whatever the session patches is+ // applied by id in the fold, so nothing is attributed to a slot the+ // review never named.+ dirs = append(dirs, direction{slotID: -1, text: text})+ }+ if len(dirs) == 0 {+ // Nothing for a session to do. A PREFILL still counts as work — it+ // edited the table — so its result must travel back to the caller;+ // only a round that changed nothing at all is a nil pass.+ if prefillN == 0 {+ _LOG.Printf("[SlotResearch] all slots filled and the review named no gap; no session to run.")+ return nil+ }+ } else {+ _LOG.Printf("[SlotResearch] all slots filled, but the review named %d gap(s); running session(s) on them.", len(dirs))+ }+ }+// Shared across sessions so duplicate retrievals are served from cache.sharedToolCache := harness.NewToolCache()var sharedSearchQueries []string@@ -2775,28 +3484,111 @@ func RunSlotResearchPass(ctx context.Context, deps harness.SessionDeps, questionresult harness.Result}results := make([]outcome, 0, slotSessionsPerRound)- limit := min(len(unresolved), slotSessionsPerRound)+ limit := min(len(dirs), slotSessionsPerRound)++ // The direction's SHAPE is only known here, after the table was built — and the+ // round's own context was fixed before that, by a caller that could not know it.+ // A session therefore cannot ride this round's clock, or the enumeration it is+ // midway through is cut before it can patch: measured (2026-09-16, 三国/关羽) the+ // pass timeout cancelled a session at the deadline one millisecond before its+ // patch, and the member it had already reached (管亥, three passages, admitted to+ // the shared pool by the session's own batch) died with it. So a set-shaped pass+ // hangs its sessions off the PARENT context with the shape's own clock+ // (harness.SessionWallS), and buys the question the one-shot budget extension+ // that lets the NEXT round start and pick up whatever this one could not record.+ sessionCtx := ctxsessionBudget := max(20.0, deadlineLeft-10.0)+ if harness.SetShaped(slotTable) {+ sessionBudget = max(sessionBudget, harness.SessionWallS(slotTable))+ if parent != nil {+ var cancelSessions context.CancelFunc+ sessionCtx, cancelSessions = context.WithTimeout(parent, deadlineToDuration(sessionBudget+setSessionSlackS))+ defer cancelSessions()+ }+ // The extension must leave room for what FOLLOWS the research — the review,+ // the draft, the composed answer (downstreamReserveS) — inside the caller's own+ // deadline: buying time the answer then lacks is the one way this change could+ // make a question worse (a timed-out request instead of a missing member). So+ // the request's remaining room decides, not the extension's own size, and an+ // extension too small to let a round start is not worth buying at all.+ ext := SetBudgetExtensionS+ if room, bounded := ctxRoomS(parent); bounded {+ ext = min(ext, room-st.RemainingS()-downstreamReserveS)+ }+ if ext >= minBudgetExtensionS {+ if st.ExtendDeadline(ext) {+ _LOG.Printf("[SlotResearch] set-shaped table: session clock %.0fs, research budget extended by %.0fs so a following round can pick up what this one could not record.",+ sessionBudget, ext)+ }+ } else {+ _LOG.Printf("[SlotResearch] set-shaped table: session clock %.0fs; research budget NOT extended (only %.0fs of the request is left, and %.0fs is reserved for the review, the draft and the answer).",+ sessionBudget, ctxLeftS(parent), downstreamReserveS)+ }+ }++ // The completeness pass RUNS HERE — in code, before any session starts.+ //+ // The direction's own act patterns used to be rendered into the seed as a list of+ // queries to make, and the measurement is why that is not enough: measured (2026-09-16,+ // 三国/关羽) a round declared ten act words with several aliases each (2175 characters of+ // patterns, in the seed of every session) and not one session ran a single one of them —+ // the run's query log holds zero `.*` queries and the sessions improvised space-separated+ // word lists instead (`关羽 斩华雄 温酒`, `关公 砍死 斩 杀`). A list of queries in a prompt+ // is advice; the completeness of an enumeration cannot rest on advice, and every run of+ // this question missed 2-4 members that differed run to run. So the runtime asks the+ // corpus itself, admits the windows it gets back to the pool, and seeds the sessions with+ // what came back (harness.RunCompletenessPass) — the session's job becomes reading them.+ //+ // Run once per QUESTION, not once per round: the windows stay in the pool under the same+ // ids, so a later round reuses the block (Kbinfos.PatternFindings).+ switch {+ case !harness.EnumerationShaped(slotTable):+ // A table of counts and dates declares act words too (the planner is told to for "a+ // count of things someone DID"), and no name either pass could return changes a count+ // of events: measured (2026-09-16, FRAMES) two such questions carried a 100-passage+ // reading list into sessions 8 passages a turn, together ~18% of the run's tokens.+ if patterns := harness.ScanPatterns(slotTable); len(patterns) > 0 {+ _LOG.Printf("[SlotResearch] %d act pattern(s) declared but this table is not an ENUMERATION (it declared no count/set/list slot, no NAME-carrying slot, or no act words) — not run: a value question pays nothing for a set's bookkeeping.", len(patterns))+ }+ case kb != nil:+ if block, done := kb.PatternFindings(); done {+ deps.PatternFindings = block+ _LOG.Printf("[SlotResearch] completeness pass already ran for this question; reusing its %d char block (the windows are in the pool).", len(block))+ } else if deps.Tools != nil {+ if runner, ok := deps.Tools.Exec.(harness.PatternRunner); ok {+ pass := harness.RunCompletenessPass(ctx, runner, kb, slotTable)+ if pass.Asked > 0 {+ _LOG.Printf("[SlotResearch] completeness pass: %d act pattern(s) run, %d answered, %d window(s) admitted to the pool; seed +%d char(s).",+ pass.Asked, pass.Answered, pass.Admitted, len(pass.Text))+ logCompletenessWindows(pass.Text)+ kb.StorePatternFindings(pass.Text)+ deps.PatternFindings = pass.Text+ } else if patterns := harness.ScanPatterns(slotTable); len(patterns) > 0 {+ // The pass yields nothing when the clock ran out before the patterns+ // could be asked (see RunCompletenessPass), so the seed keeps the list —+ // said out loud, because "no pass" and "a pass that found nothing" are+ // different facts about the corpus.+ _LOG.Printf("[SlotResearch] completeness pass produced nothing for %d declared pattern(s) — the seed keeps the pattern list (no time left to ask, or the executor cannot search).", len(patterns))+ }+ }+ }+ }for i := 0; i < limit; i++ {- v := unresolved[i]+ d := dirs[i]wg.Add(1)- go func(v harness.Variable) {+ go func(d direction) {defer wg.Done()sem <- struct{}{}defer func() { <-sem }()- direction := question- if len(v.QuestionClues) > 0 {- direction = v.QuestionClues[0]- }// Sessions share ONE Toolset; DisableTool mutates it, so the call is// guarded here. The Kbinfos merge happens inside the executor.- res := harness.RunActionSession(ctx, deps, direction, slotTable, sessionBudget, "", sharedToolCache, sharedSearchQueries)+ res := harness.RunActionSession(sessionCtx, deps, d.text, slotTable, sessionBudget, "", sharedToolCache, sharedSearchQueries)mu.Lock()- results = append(results, outcome{slotID: v.ID, result: res})+ results = append(results, outcome{slotID: d.slotID, result: res})mu.Unlock()- }(v)+ }(d)}wg.Wait()@@ -2829,9 +3621,19 @@ func RunSlotResearchPass(ctx context.Context, deps harness.SessionDeps, question}}for _, ns := range r.NewStates {- if merged := MergeSlotPatch(slotTable, ns); merged != nil {+ before := slotTable+ merged := MergeSlotPatch(slotTable, ns)+ if merged != nil {slotTable = *merged}+ // What this session CLAIMED, and whether the merge kept it.+ //+ // The merge is a tournament per slot: one candidate survives, chosen by+ // the strength the MODEL reported (MergeSlotPatch:3304), and nothing+ // logged the contestants — which is why three rounds of analysis here+ // could only GUESS whether some session's list had been dropped. The log+ // showed the merged table and never a single patch.+ logSessionPatch(item.slotID, before, slotTable, ns)}// _run_slot_research_pass — a session without a found answer still logs a hint, taken// from its message history (`(r.found_answer or str(r.messages))[:80]`).@@ -2878,6 +3680,14 @@ func RunSlotResearchPass(ctx context.Context, deps harness.SessionDeps, question})}+ // One set, one answer: a table can hold the members in one slot and the count+ // in another, written by different sessions, with nothing keeping them in step+ // (measured 2026-09-15: count slot read 10 while the sessions had enumerated+ // twelve). Raised here, before the draft the answer is written from.+ if raised := reconcileCountSlots(&slotTable); len(raised) > 0 {+ _LOG.Printf("[SlotResearch] count slot(s) %v set to the enumerated members' size", raised)+ }+draft := RenderSlotDraft(slotTable, collected, sessionEvidence)_LOG.Printf("[SlotResearch] round done — %d slot(s) filled, unresolved=%d, collected_answer=%v",countFilled(slotTable), len(unresolvedOut), collected != "")@@ -2889,7 +3699,10 @@ func RunSlotResearchPass(ctx context.Context, deps harness.SessionDeps, questionUnresolvedSlots: unresolvedOut,SlotEvidence: sessionEvidence,SlotDraft: draft,- Attempted: ledger,+ // The answer-facing record (no machine fields) is rendered here, next to+ // the SCA-facing draft, so the two can never drift apart.+ SlotRecord: RenderSlotRecord(slotTable, collected),+ Attempted: ledger,}}@@ -2898,6 +3711,49 @@ func RunSlotResearchPass(ctx context.Context, deps harness.SessionDeps, question//// Returns nil when nothing changed (mirrors Python's `if not changed: return// None`), so callers can skip no-op merges.+// alternateCluePrefix marks a claim that LOST a slot comparison and is kept only+// so it is not lost (see MergeSlotPatch). The prefix is what lets the renderers+// tell an alternate candidate from an ordinary discovered clue.+const alternateCluePrefix = "alt-candidate: "++func alternateClue(candidate string) string { return alternateCluePrefix + candidate }++// alternateCandidatesOf returns the candidates a slot lost to, in the order they+// were kept.+func alternateCandidatesOf(v harness.Variable) []string {+ var out []string+ for _, c := range v.DiscoveredClues {+ if strings.HasPrefix(c, alternateCluePrefix) {+ out = append(out, strings.TrimPrefix(c, alternateCluePrefix))+ }+ }+ return out+}++// logSessionPatch reports one session's claims and what the merge did with them.+//+// One line per patched slot, because the losing side of MergeSlotPatch leaves no+// trace anywhere else: a candidate that was dropped is not in the table, not in+// the draft, not in the record — it is simply gone, and "gone" is the failure this+// line makes visible.+func logSessionPatch(directionSlot int, before, after, patch harness.State) {+ for _, pv := range patch.State {+ if pv.Candidate == nil || *pv.Candidate == "" {+ continue+ }+ base := "(empty)"+ if bv := before.ByID(pv.ID); bv != nil && bv.Candidate != nil && *bv.Candidate != "" {+ base = fmt.Sprintf("%q (%.2f)", truncateRunes(*bv.Candidate, 80), strengthOf(*bv))+ }+ result := "NOT ADOPTED (the base stands)"+ if av := after.ByID(pv.ID); av != nil && av.Candidate != nil && *av.Candidate == *pv.Candidate {+ result = "adopted"+ }+ _LOG.Printf("[SlotResearch] patch (direction slot %d) → slot %d: %q (%.2f); base was %s; result: %s",+ directionSlot, pv.ID, truncateRunes(*pv.Candidate, 120), strengthOf(pv), base, result)+ }+}+func MergeSlotPatch(base, branch harness.State) *harness.State {if len(branch.State) == 0 {return nil@@ -2914,21 +3770,63 @@ func MergeSlotPatch(base, branch harness.State) *harness.State {merged = append(merged, v)continue}- // Adopt the branch candidate only when STRONGER. Sessions run- // concurrently and their branches fold in completion order, so an- // unconditional "branch wins" made the result both order-dependent and- // destructive: a weak session (0.3, tentative) could downgrade a slot- // another session had already proven (0.95).- cand, strength := v.Candidate, v.CandidateStrength- switch {- case bv.Candidate == nil:- // branch has no candidate: keep base- case v.Candidate == nil:- cand, strength = bv.Candidate, bv.CandidateStrength- case strengthOf(bv) > strengthOf(v):- cand, strength = bv.Candidate, bv.CandidateStrength+ // A slot holding a SET merges by UNION; a slot holding one VALUE is still+ // settled by strength (see slots.Union for why, and for the measured run+ // where a count outvoted the members it was counting).+ //+ // The union is over TYPED values: members union by name, a membership claim+ // beats a number, two numbers keep the larger. Text is not the union's+ // business (invariant I1), which is what keeps a value question merging by+ // strength exactly as it always did.+ var cand *string+ var value *slots.Value+ strength := v.CandidateStrength+ var loser string+ if union, dropped, ok := slots.Union(v.Typed(), bv.Typed()); ok {+ rendered := slots.Render(union)+ cand = &rendered+ value = &union+ if strengthOf(bv) > strengthOf(v) {+ strength = bv.CandidateStrength+ }+ if !dropped.IsZero() {+ loser = slots.Render(dropped)+ }+ } else {+ // Adopt the branch candidate only when STRONGER. Sessions run+ // concurrently and their branches fold in completion order, so an+ // unconditional "branch wins" made the result both order-dependent and+ // destructive: a weak session (0.3, tentative) could downgrade a slot+ // another session had already proven (0.95).+ adoptBranch := bv.Candidate != nil && *bv.Candidate != "" &&+ (v.Candidate == nil || *v.Candidate == "" || strengthOf(bv) > strengthOf(v))+ cand = v.Candidate+ value = v.Value+ if adoptBranch {+ cand, strength = bv.Candidate, bv.CandidateStrength+ value = bv.Value+ }+ // ONE slot holds ONE candidate, so the claim that lost the comparison used+ // to leave no trace at all: not in the table, not in the draft, not in the+ // record. Two sessions enumerating the same question from different angles+ // therefore produced whichever LIST the model happened to call stronger,+ // and the other list was silently gone (measured: runs of the same question+ // returning 11 / 13 / 15 members, with no slot holding the complete list).+ //+ // The losing claim is kept as an ALTERNATE on the slot's clues — the one+ // field MergeSlotPatch unions, never replaces. The framework does not decide+ // which list is true; it stops discarding the one that lost.+ switch {+ case adoptBranch && v.Candidate != nil && *v.Candidate != "" && *v.Candidate != *bv.Candidate:+ loser = *v.Candidate+ case !adoptBranch && bv.Candidate != nil && *bv.Candidate != "" && (v.Candidate == nil || *v.Candidate != *bv.Candidate):+ loser = *bv.Candidate+ }}clues := dedupe(append(append([]string(nil), v.DiscoveredClues...), bv.DiscoveredClues...))+ if loser != "" {+ clues = dedupe(append(clues, alternateClue(loser)))+ }if !equalStringPtr(cand, v.Candidate) || !equalStrings(clues, v.DiscoveredClues) {changed = true}@@ -2939,6 +3837,16 @@ func MergeSlotPatch(base, branch harness.State) *harness.State {DiscoveredClues: clues,Candidate: cand,CandidateStrength: strength,+ Value: value,+ // The DECLARATION travels with the slot. Terms/Subject are what the+ // completeness pass is built from (harness.ScanPatterns / RunCompletenessPass),+ // and rebuilding the slot without them is why one run's second round had no act+ // patterns at all: measured (2026-09-16, 三国/关羽) round 1's seeds carried 6325+ // characters (method + the declared patterns) and round 2's carried 4150+ // (method only), so the recovery round — the one the routing opened because the+ // record was still short — ran with the enumeration machinery switched off.+ Terms: append([]string(nil), v.Terms...),+ Subject: v.Subject,})}if !changed {@@ -2948,6 +3856,70 @@ func MergeSlotPatch(base, branch harness.State) *harness.State {return &out}+// reconcileCountSlots writes the table's OWN count into every slot that claims one.+//+// A count slot holds a claim ABOUT the list slots, and the two are written by+// different sessions, so nothing kept them in step: measured (2026-09-15), slot 0+// [count] read 10 while the same table's sessions had enumerated twelve members, and+// the answer was the 10.+//+// The number is DERIVED: len(members) over the declared member lists. A slot that+// claims a different number takes the derived one (the claim is kept as an alternate+// clue, so the record still shows what was claimed beside what is enumerated), and a+// slot that claims NO number while the table enumerates a set — measured (2026-09-16,+// 三国/关羽): a session wrote "约 17-19 人" into the count slot and the slot ended up+// holding neither a number nor members — is given the derived one, so the count can+// never be the part of the record nobody can reconstruct.+//+// It returns the ids it changed, for the log.+func reconcileCountSlots(table *harness.State) []int {+ if table == nil || len(table.State) == 0 {+ return nil+ }+ union := memberUnion(table)+ if len(union) < 2 {+ return nil+ }+ var raised []int+ for i := range table.State {+ v := &table.State[i]+ if !countTypedSlot(v) {+ // Only a slot that ASKS FOR A NUMBER. A member list is not overwritten by+ // the count of the set it belongs to, and a text slot is opaque: it may+ // hold a date, a phrase or a sentence, and nothing here can tell (nor+ // needs to).+ continue+ }+ claimed, ok := v.Typed().Number()+ if ok && claimed == len(union) {+ continue+ }+ if ok {+ // The claim loses either way — a count larger than the members listed is+ // not evidence of members, and a smaller one is a set that lost some.+ // Measured (2026-09-16): a slot left holding a session's 28 against+ // thirteen enumerated members is the number the answer reported.+ v.DiscoveredClues = append(v.DiscoveredClues, alternateClue(slots.Render(v.Typed())))+ }+ derived := slots.Number(len(union))+ v.Value = &derived+ rendered := slots.Render(derived)+ v.Candidate = &rendered+ raised = append(raised, v.ID)+ }+ return raised+}++// countTypedSlot reports whether a slot is one that ANSWERS WITH A NUMBER — the only+// slots the derived count may be written into.+func countTypedSlot(v *harness.Variable) bool {+ switch strings.ToLower(strings.TrimSpace(v.Type)) {+ case "count", "number", "quantity":+ return true+ }+ return false+}+// pythonMessageListPrefix reproduces Python's `str(messages)[:n]` for a langchain// message list — the ledger hint _run_slot_research_pass builds with// `(r.found_answer or str(r.messages))[:80]`.@@ -3418,7 +4390,19 @@ func BuildAgenticGraph(ctx context.Context, deps RAGTools, question, keywords st}, map[string]bool{"stop": true, "rag_agent": true})addBranch("rag_agent", func(_ context.Context, s *AgenticState) (string, error) {- return guard(agenticNodeName(routeSCA(s, enableSCA, scaMaxRounds))), nil+ rounds := scaMaxRounds+ // An ENUMERATION runs a bounded number of rounds: one to ask the corpus the act+ // patterns its seed carries and name what they return, one to recover what the+ // round's own record shows it reached and did not record. Measured (2026-09-16,+ // 三国/关羽, three runs): round 2 took a table from 11 members to 14 by recording+ // 车胄 / 程远志 / 管亥 — and every round after it added `+0 chunks`, i.e. a third+ // draft of the same list. The bound is on the SHAPE the planner declared+ // (SetShaped: count/set/list), so a value question keeps the rounds it buys+ // accuracy with.+ if harness.SetShaped(s.SlotTable) && rounds > 2 {+ rounds = 2+ }+ return guard(agenticNodeName(routeSCA(s, enableSCA, rounds))), nil}, map[string]bool{"stop": true, "query_rewrite": true, "formalize_answer": true})addBranch("query_rewrite", func(_ context.Context, s *AgenticState) (string, error) {@@ -3912,12 +4896,19 @@ func ComposeAnswerWith(ctx context.Context, deps AnswerDeps, kb *harness.Kbinfosif kb != nil {preSummary = kb.PreSummary}+ // Both the prompt and this log go through composedRecord, so the line below+ // reports the record block the answer actually carried.+ record := composedRecord(kb)prompt := deps.answerPromptWithEvidence(kb, question, partial, noEvidence)// 3. Call the model.callCtx, cancel := context.WithTimeout(ctx, deadlineToDuration(answerTimeoutS))defer cancel()+ logger.Printf("[Formalize][record] question=%q record_len=%d draft_summary_len=%d evidence_len=%d using=%s\nrecord=%q",+ trunc(question, 160), len(record), len(preSummary), len(prompt.user), recordSource(record),+ truncateRunes(record, 3000))+logger.Printf("[Formalize][pre_summary] question=%q pre_summary_len=%d evidence_len=%d\npre_summary=%q",trunc(question, 160), len(preSummary), len(prompt.user), truncateRunes(preSummary, 3000))@@ -4063,6 +5054,7 @@ func (d AnswerDeps) answerPromptWithEvidence(kb *harness.Kbinfos, question strinevidence := strings.Join(prompts.KBPrompt(citeChunks, maxTokens), "\n")summary := ""+ record := composedRecord(kb)if kb != nil {summary = strings.TrimSpace(kb.PreSummary)}@@ -4082,7 +5074,12 @@ func (d AnswerDeps) answerPromptWithEvidence(kb *harness.Kbinfos, question strin}}- if summary != "" {+ if record != "" {+ // The slot table of an agentic round: facts to check the answer against,+ // explicitly NOT evidence and NOT answer text (see recordContract).+ parts = append(parts, fmt.Sprintf("%s\n%s\n", recordContract, record))+ } else if summary != "" {+ // A prose summary (no slot table behind it): it stands in as findings.parts = append(parts, fmt.Sprintf("Research Summary (primary evidence):\n%s\n", summary))}// _compose_answer_from_evidence: the partial preamble goes HERE — after the research@@ -4131,15 +5128,19 @@ func ComposeAnswerStream(ctx context.Context, deps AnswerDeps, model harness.Strif noEvidence && deps.EmptyResponse != "" {return AnswerResult{Answer: deps.EmptyResponse, NoEvidence: true}, nil}- // Python _compose_answer_from_evidence:938-944 — the pre_summary the compose- // prompt actually carries, content included (first 3000 chars), so a run- // that answered without the slot facts is diagnosable from the log alone.+ // Python _compose_answer_from_evidence:938-944 — the record the compose prompt+ // actually carries, content included (first 3000 chars), so a run that answered+ // without the slot facts is diagnosable from the log alone.preSummary := ""if kb != nil {preSummary = kb.PreSummary}- logger.Printf("[Formalize][pre_summary] question=%q pre_summary_len=%d evidence_len=%d\npre_summary=%q",- trunc(question, 160), len(preSummary), len(prompt.user), truncateRunes(preSummary, 3000))+ // Both the prompt and this log go through composedRecord, so the line below+ // reports the record block the answer actually carried.+ record := composedRecord(kb)+ logger.Printf("[Formalize][record] question=%q record_len=%d draft_summary_len=%d evidence_len=%d using=%s\nrecord=%q",+ trunc(question, 160), len(record), len(preSummary), len(prompt.user), recordSource(record),+ truncateRunes(record, 3000))callCtx, cancel := context.WithTimeout(ctx, deadlineToDuration(answerTimeoutS))defer cancel()diff --git a/internal/rag/advanced_rag/agentic_rag_graph_test.go b/internal/rag/advanced_rag/agentic_rag_graph_test.goindex 300f0172bb..045d121f5e 100644--- a/internal/rag/advanced_rag/agentic_rag_graph_test.go+++ b/internal/rag/advanced_rag/agentic_rag_graph_test.go@@ -8,6 +8,7 @@ import ("fmt""log""os"+ "sort""strings""sync""testing"@@ -19,6 +20,7 @@ import ("ragflow/internal/engine/types""ragflow/internal/entity""ragflow/internal/rag/advanced_rag/harness"+ "ragflow/internal/rag/advanced_rag/slots")// ---------------------------------------------------------------------------@@ -169,59 +171,153 @@ func TestRouteSCADisabledSCAClosesOut(t *testing.T) {}}-// TestRouteSCAFullPoolShortCircuits pins the PR: a pool at/over the SCA view cap-// cannot flip the verdict, so routeSCA finalizes instead of researching — even-// when the verdict is insufficient and headroom remains. Gated to SECOND-or-later-// reviews (SearchRounds >= 1): claim pseudo-chunks bypass the pool cap, so the-// FIRST review must always get its rewrite round when insufficient (Python-// _route_sca:1411).-func TestRouteSCAFullPoolShortCircuits(t *testing.T) {- st := &AgenticState{- Verdict: VerdictInsufficient,- MaxLoops: 3,- SearchRounds: 1,- KB: &harness.Kbinfos{Chunks: make([]map[string]any, SCAViewCap)},+// TestRouteSCAPoolSizeIsNotTheStop pins the DECOUPLED stop: the pool's size is+// not what ends the research loop — whether the SCA can READ anything new is, and+// that fact is the view identity (scaNode sets NoProgress when the view matches+// the previous review's, and routeSCA honours it on its first check).+//+// The old guard finalized as soon as the pool reached SCAViewCap on a+// second-or-later review, which is a different claim: a pool past the view cap+// whose view CHANGED has new evidence the reviewer can read, and it was being+// thrown away (measured: a name-probe round ended at 117 chunks with members+// still arriving).+func TestRouteSCAPoolSizeIsNotTheStop(t *testing.T) {+ full := func() *AgenticState {+ st := &AgenticState{+ Verdict: VerdictInsufficient,+ MaxLoops: 3,+ SearchRounds: 1,+ // Work left in the table AND evidence still arriving last round —+ // the two facts the loop is driven by (see routeSCA).+ LastRoundNew: 12,+ UnresolvedSlots: []map[string]any{{"question_clues": []string{"who else"}}},+ KB: &harness.Kbinfos{Chunks: make([]map[string]any, SCAViewCap)},+ }+ st.Deadline = time.Now().Add(120 * time.Second)+ return st}- st.Deadline = time.Now().Add(120 * time.Second)- if n := routeSCA(st, true, 3); n != nodeFormalizeAnswer {- t.Fatalf("full pool: expected formalize, got %v", n)++ // Full pool, view changed (scaNode did NOT set NoProgress) => research on.+ if n := routeSCA(full(), true, 3); n != nodeQueryRewrite {+ t.Fatalf("full pool with a changed view: expected rewrite, got %v", n)}- // One chunk below the cap still takes the normal research path.- st.KB.Chunks = make([]map[string]any, SCAViewCap-1)- if n := routeSCA(st, true, 3); n != nodeQueryRewrite {- t.Fatalf("below cap: expected rewrite, got %v", n)++ // Full pool, view UNCHANGED: scaNode's detector owns this case, and routeSCA+ // honours it before anything else.+ stale := full()+ stale.NoProgress = true+ if n := routeSCA(stale, true, 3); n != nodeFormalizeAnswer {+ t.Fatalf("full pool with an unchanged view: expected formalize, got %v", n)}- // FIRST review (SearchRounds == 0) with a full pool: claim pseudo-chunks- // bypass the pool cap, so the rewrite round must still run.- first := &AgenticState{- Verdict: VerdictInsufficient,- MaxLoops: 3,- SearchRounds: 0,- KB: &harness.Kbinfos{Chunks: make([]map[string]any, SCAViewCap)},++ // The loop is still bounded by the round count...+ atMax := full()+ atMax.SearchRounds = 3+ if n := routeSCA(atMax, true, 3); n != nodeFormalizeAnswer {+ t.Fatalf("at max rounds with a full pool: expected formalize, got %v", n)}- first.Deadline = time.Now().Add(120 * time.Second)- if n := routeSCA(first, true, 3); n != nodeQueryRewrite {- t.Fatalf("first review full pool: expected rewrite, got %v", n)+ // ...and by the round-headroom guard.+ tight := full()+ tight.Deadline = time.Now().Add(MinRoundHeadroomS / 2 * time.Second)+ if n := routeSCA(tight, true, 3); n != nodeFormalizeAnswer {+ t.Fatalf("no headroom with a full pool: expected formalize, got %v", n)}}-func TestRouteSCAInsufficientStartsRewrite(t *testing.T) {- // Sufficient verdict closes out.- st := &AgenticState{Verdict: VerdictSufficient, MaxLoops: 3}+// TestRouteSCARoundRecordDrivesTheLoop pins the DECOUPLED stop/continue rule: the+// loop's own record (work left in the table + evidence still arriving) decides,+// and the reviewer's verdict is one of its inputs rather than the switch.+//+// The distinction it encodes: a SUFFICIENT verdict is a judgement about the+// PASSAGES the reviewer read. It is not a statement that the question is done —+// measured 2026-09-15, a run ended with unresolved=0 while the answer was six+// members short — so a table that still lists unresolved slots while the round is+// still adding evidence keeps its next round, and a settled table closes out+// however much evidence arrived.+func TestRouteSCARoundRecordDrivesTheLoop(t *testing.T) {+ base := func() *AgenticState {+ st := &AgenticState{MaxLoops: 3, SearchRounds: 1}+ st.Deadline = time.Now().Add(120 * time.Second)+ return st+ }+ work := []map[string]any{{"question_clues": []string{"who else"}}}++ // Work left + still learning + a SATISFIED reviewer: another round. The+ // reviewer's view of the passages does not settle the table's own gaps.+ st := base()+ st.Verdict = VerdictSufficient+ st.LastRoundNew = 9+ st.UnresolvedSlots = work+ if n := routeSCA(st, true, 3); n != nodeQueryRewrite {+ t.Errorf("SUFFICIENT with work left and evidence still arriving: expected rewrite, got %v", n)+ }++ // Nothing left in the table: growth alone is not a reason to keep going.+ st = base()+ st.Verdict = VerdictSufficient+ st.LastRoundNew = 9if n := routeSCA(st, true, 3); n != nodeFormalizeAnswer {- t.Fatalf("expected formalize on sufficient, got %v", n)+ t.Errorf("settled table with nothing against it: expected formalize, got %v", n)}- // Insufficient + rounds under cap + headroom remaining => rewrite.- st = &AgenticState{Verdict: VerdictInsufficient, MaxLoops: 3, SearchRounds: 0}- st.Deadline = time.Now().Add(120 * time.Second) // 120s remaining >> MinRoundHeadroomS++ // Work left, stalled round, reviewer names a gap: another round.+ st = base()+ st.Verdict = VerdictInsufficient+ st.UnresolvedSlots = work+ if n := routeSCA(st, true, 3); n != nodeQueryRewrite {+ t.Errorf("INSUFFICIENT with a concrete gap: expected rewrite, got %v", n)+ }++ // Work can ALSO come from the review's own gaps, with an empty unresolved+ // table — the two records are independent. Ignoring the reviewer's gaps is+ // what made a run close out with INSUFFICIENT (confidence 1.00) and four+ // derived gaps while 60s and two rounds went unspent (2026-09-15).+ st = base()+ st.Verdict = VerdictInsufficient+ st.SCA = map[string]any{"claims": map[string]any{+ "c1": map[string]any{"missing_information": []any{+ map[string]any{"what": "还有谁", "search_hint": "关羽 斩将 名单"},+ }},+ }}if n := routeSCA(st, true, 3); n != nodeQueryRewrite {- t.Fatalf("expected rewrite on insufficient+headroom, got %v", n)+ t.Errorf("INSUFFICIENT with the review's own gaps and no unresolved slots: expected rewrite, got %v", n)+ }++ // Work left, stalled round, NO judgement (the review could not run): nothing+ // names a direction and the round learned nothing — close out. This is the+ // case a fallback INSUFFICIENT used to promise a round to.+ st = base()+ st.Verdict = VerdictUnknown+ st.UnresolvedSlots = work+ if n := routeSCA(st, true, 3); n != nodeFormalizeAnswer {+ t.Errorf("UNKNOWN with a stalled round: expected formalize, got %v", n)+ }++ // Work left, stalled round, satisfied reviewer: close out.+ st = base()+ st.Verdict = VerdictSufficient+ st.UnresolvedSlots = work+ if n := routeSCA(st, true, 3); n != nodeFormalizeAnswer {+ t.Errorf("SUFFICIENT with a stalled round: expected formalize, got %v", n)}- // At max rounds => formalize.- st = &AgenticState{Verdict: VerdictInsufficient, MaxLoops: 3, SearchRounds: 3}- st.Deadline = time.Now().Add(120 * time.Second)++ // At max rounds => formalize, whatever the record says.+ st = base()+ st.Verdict = VerdictInsufficient+ st.LastRoundNew = 3+ st.UnresolvedSlots = work+ st.SearchRounds = 3if n := routeSCA(st, true, 3); n != nodeFormalizeAnswer {- t.Fatalf("expected formalize at max rounds, got %v", n)+ t.Errorf("at max rounds: expected formalize, got %v", n)+ }+ // No headroom => formalize.+ st = base()+ st.Verdict = VerdictInsufficient+ st.LastRoundNew = 3+ st.UnresolvedSlots = work+ st.Deadline = time.Now().Add(MinRoundHeadroomS / 2 * time.Second)+ if n := routeSCA(st, true, 3); n != nodeFormalizeAnswer {+ t.Errorf("no headroom: expected formalize, got %v", n)}}@@ -263,10 +359,17 @@ func TestMergeSlotPatchAdoptsStronger(t *testing.T) {{ID: 0, Type: "aspect", Candidate: strPtr("weak-candidate"), CandidateStrength: &weak},}, 1, nil)merged := MergeSlotPatch(base, branch)- // A weak branch does not downgrade the strong base, AND produces no change- // at all — MergeSlotPatch returns nil to signal "no new patch".+ // A weak branch does not downgrade the strong base. It is no longer a no-op+ // either: the claim that lost the comparison is kept as an alternate, so the+ // list two sessions disagreed about does not vanish (see+ // TestMergeSlotPatchKeepsTheLosingListAsAnAlternate).if merged != nil {- t.Fatalf("weak branch over strong base should yield NO change (nil patch), got %+v", merged)+ if got := merged.ByID(0).Candidate; got == nil || *got != "base" {+ t.Fatalf("weak branch upgraded the slot: %v", got)+ }+ if alts := alternateCandidatesOf(*merged.ByID(0)); len(alts) != 1 || alts[0] != "weak-candidate" {+ t.Fatalf("alternates = %v, want the weak claim kept as the loser", alts)+ }}// A stronger branch wins.@@ -639,7 +742,7 @@ func TestRunSlotResearchPassLedgerRecordsSessionHint(t *testing.T) {Tools: &harness.Toolset{Exec: sessionStubExec{}},KB: &harness.Kbinfos{},}- res := RunSlotResearchPass(context.Background(), deps, "who opened it?", st, 60)+ res := RunSlotResearchPass(context.Background(), context.Background(), deps, "who opened it?", st, 60)if res == nil {t.Fatal("RunSlotResearchPass returned nil")}@@ -677,7 +780,7 @@ func TestRunSlotResearchPassLogsSlotEvidenceBound(t *testing.T) {Tools: &harness.Toolset{Exec: sessionStubExec{}},KB: &harness.Kbinfos{},}- if res := RunSlotResearchPass(context.Background(), deps, "who opened it?", st, 60); res == nil {+ if res := RunSlotResearchPass(context.Background(), context.Background(), deps, "who opened it?", st, 60); res == nil {t.Fatal("RunSlotResearchPass returned nil")}if !strings.Contains(buf.String(), "slot evidence bound") {@@ -1360,7 +1463,7 @@ func TestFinalizeRunsOnceFromInsideTheGraph(t *testing.T) {// produces no usable result (timeout, unparsable reply, no model) the verdict is// INSUFFICIENT so unresolved slots can drive another research round — NOT// SUFFICIENT, which would ship the unverified draft as if it had passed review.-func TestSCAUnavailableMarksInsufficient(t *testing.T) {+func TestSCAUnavailableIsNotAVerdict(t *testing.T) {st := NewAgenticState("When was it built?", "", 3, nil)st.Draft = "Built in 1865."st.KB = &harness.Kbinfos{Chunks: []map[string]any{@@ -1372,12 +1475,23 @@ func TestSCAUnavailableMarksInsufficient(t *testing.T) {scaNode(context.Background(), RAGTools{Model: mdl}, st, log.New(&bytes.Buffer{}, "", 0))- if st.Verdict != VerdictInsufficient {- t.Errorf("Verdict = %q, want INSUFFICIENT (Python marks an unavailable SCA insufficient)", st.Verdict)+ if st.Verdict != VerdictUnknown {+ t.Errorf("Verdict = %q, want UNKNOWN: a review that could not run is the ABSENCE of a verdict, not a judgement of insufficiency", st.Verdict)+ }+ if st.Verdict == VerdictInsufficient {+ t.Error("an unavailable review must not read as INSUFFICIENT: that is what marked the answer partial on no evidence and promised a research round the budget could not pay for")}if st.SCA == nil {t.Error("SCA payload must stay an (empty) map, like Python's sca={}")}+ // An un-run review must not make the answer PARTIAL either: with nothing+ // unresolved and no stalled round, the deliverable is not dressed up as+ // unverified.+ st.Deadline = time.Now().Add(60 * time.Second)+ formalizeAnswerNode(context.Background(), RAGTools{}, st, log.New(&bytes.Buffer{}, "", 0))+ if st.PartialAnswer {+ t.Error("PartialAnswer = true on an UNKNOWN verdict with no unresolved slots; partial is a statement about the evidence")+ }}// TestQueryRewriteFoldsUnresolvedCluesWhenNoGaps pins Python :1114-1128: with@@ -2620,3 +2734,876 @@ func TestRecordConsecutiveUnanswerableNoCacheIsNoOp(t *testing.T) {recordConsecutiveUnanswerable(nil, VerdictInsufficient)recordConsecutiveUnanswerable(nil, VerdictSufficient)}++// TestRewriteContextShowsThePassageBehindAConfirmedMember pins the input side of+// the rewrite round: what the rewriter is shown is the PASSAGE that carries each+// confirmed name, not the first line of a stored chunk.+//+// The difference is the whole point of that round. The wording a text uses for the+// relation (and the other names it mentions) lives in the middle of a passage, so+// a first-line digest cannot carry it — and a rewrite that cannot see it can only+// re-ask what was already asked.+func TestRewriteContextShowsThePassageBehindAConfirmedMember(t *testing.T) {+ st := NewAgenticState("关羽杀了多少有姓名的人物?", "", 3, nil)+ st.KB = &harness.Kbinfos{Chunks: []map[string]any{+ {"chunk_id": "w1", "content": "荀正 引军来战,被关公一刀斩于马下。"},+ {"chunk_id": "big", "content": "第一行与本题无关\n第二行才提到关公"},+ }}+ st.KB.RecordReachedTerm("荀正", "w1")++ ctx := renderResearchContext(st)+ if !strings.Contains(ctx, "荀正") || !strings.Contains(ctx, "斩于马下") {+ t.Errorf("rewrite context does not carry the passage behind the confirmed member:\n%s", ctx)+ }+ if strings.Contains(ctx, "第一行与本题无关") {+ t.Errorf("rewrite context fell back to first-line digests although a confirmed member's passage was available:\n%s", ctx)+ }+ if !strings.Contains(ctx, "ALREADY confirmed") {+ t.Errorf("the member section is not labelled:\n%s", ctx)+ }+}++// TestRewriteRoundCanStillAdmitOnARichPool pins the room a rewrite round is given:+// it is measured against the EVIDENCE POOL's ceiling, the same number the admitter+// enforces.+//+// Sized against the smaller snippet-pool constant, a pool past 60 chunks left the+// round with room <= 0: it admitted nothing, declared "retrieval saturated" and+// discarded the queries it had just built — on exactly the rich rounds where more+// evidence was still arriving.+func TestRewriteRoundCanStillAdmitOnARichPool(t *testing.T) {+ pool := make([]map[string]any, 0, harness.EvidencePoolCap())+ for i := 0; i < 71; i++ {+ pool = append(pool, map[string]any{"chunk_id": fmt.Sprintf("pre-%d", i), "content": "already pooled"})+ }+ st := NewAgenticState("关羽杀了多少有姓名的人物?", "", 3, nil)+ st.KB = &harness.Kbinfos{Chunks: pool}+ st.UnresolvedSlots = []map[string]any{{"question_clues": []string{"还有谁被关羽所杀"}}}+ st.Deadline = time.Now().Add(60 * time.Second)++ mdl := &scriptedModel{}+ mdl.push(`{"queries": [{"query": "关羽 斩 名单 其余"}]}`)++ queryRewriteNode(context.Background(), RAGTools{+ Model: mdl,+ Search: harness.SearchDeps{Backend: &corpusRetriever{}, KbIDs: []string{"kb1"}, HasEmbedder: true},+ }, st, log.New(&bytes.Buffer{}, "", 0))++ if st.NoProgress {+ t.Fatal("NoProgress = true on a pool of 71 with room left: the round's room must be measured against the evidence pool's ceiling")+ }+ if len(st.KB.Chunks) <= 71 {+ t.Errorf("pool = %d, want the rewrite's own query admitted (cap %d, pool was 71)", len(st.KB.Chunks), harness.EvidencePoolCap())+ }+}++// TestRenderSlotRecordCarriesNoMachineFields pins the split between the record the+// ANSWER is composed from and the draft the SCA reviews.+//+// The draft deliberately carries the machine fields that make verification+// possible (strength, terminal type, evidence ids). Handing those to the answer+// model as a "summary" is a different act with a different failure mode, and it+// was measured: the composed answer quoted the bookkeeping verbatim+// ("slot 1 [entity] … (strength=0.90) [terminal=state, evidence_ids=[…]]").+func TestRenderSlotRecordCarriesNoMachineFields(t *testing.T) {+ strong := 0.9+ st := harness.NewState([]harness.Variable{+ {+ ID: 0,+ Type: "aspect",+ Candidate: strPtr("answer A"),+ CandidateStrength: &strong,+ DiscoveredClues: []string{"clue one", "clue two"},+ },+ {ID: 1, Type: "aspect", QuestionClues: []string{"who opened it?"}},+ }, 0, nil)+ evidence := map[string]SlotEvidence{+ "0": {EvidenceIDs: []string{"c1", "c2"}, TerminalType: "state"},+ }++ record := RenderSlotRecord(st, "the collected answer")+ // A table that asks for no SET leads with the session's own answer, exactly as+ // it did before the answer-layer demotion existed — see+ // TestSlotRecordLeadsWithFactsNotWithASessionsProse for the SET case, and+ // TestValueRecordCarriesNoEnumeratedMembers for why the two differ.+ if !strings.HasPrefix(record, "Candidate answer: the collected answer\n\n- slot 0 [aspect]: answer A\n- slot 1 [aspect]: NOT RESOLVED") {+ t.Fatalf("record = %q, want the session's answer first on a value table", record)+ }+ if strings.Contains(record, "enumerated members") {+ t.Fatalf("record = %q, want no enumerated line on a value table", record)+ }+ for _, banned := range []string{"strength=", "terminal=", "evidence_ids", "c1"} {+ if strings.Contains(record, banned) {+ t.Errorf("record %q must not carry the machine field %q", record, banned)+ }+ }+ // The SCA's draft keeps them: the split must not disarm verification.+ draft := RenderSlotDraft(st, "the collected answer", evidence)+ for _, want := range []string{"strength=0.90", "terminal=state", "evidence_ids=['c1', 'c2']"} {+ if !strings.Contains(draft, want) {+ t.Errorf("draft %q must keep %q for the SCA", draft, want)+ }+ }+}++// TestAnswerPromptLabelsTheRecordAndForbidsQuoting pins the prompt contract: the+// slot record reaches the answer labelled as an INTERNAL record (not evidence),+// with an explicit instruction not to quote its lines and labels — and the+// machine fields never reach the prompt at all.+func TestAnswerPromptLabelsTheRecordAndForbidsQuoting(t *testing.T) {+ strong := 0.9+ record := RenderSlotRecord(harness.NewState([]harness.Variable{+ {ID: 1, Type: "entity", Candidate: strPtr("华雄、颜良"), CandidateStrength: &strong},+ }, 0, nil), "")++ withRecord := &harness.Kbinfos{Record: record, PreSummary: "- slot 1 [entity]: 华雄、颜良 (strength=0.90)"}+ prompt := AnswerDeps{}.answerPromptWithEvidence(withRecord, "q", false, false)+ for _, want := range []string{recordContract, "Research Record (INTERNAL", "华雄、颜良"} {+ if !strings.Contains(prompt.user, want) {+ t.Errorf("prompt missing %q", want)+ }+ }+ for _, banned := range []string{"strength=", "evidence_ids", "Research Summary (primary evidence)"} {+ if strings.Contains(prompt.user, banned) {+ t.Errorf("prompt must not carry %q when a slot record exists", banned)+ }+ }++ // No slot record (a prose summary instead): the prose block is used, and the+ // record contract stays out of it.+ prose := &harness.Kbinfos{PreSummary: "the research found A and B"}+ prompt = AnswerDeps{}.answerPromptWithEvidence(prose, "q", false, false)+ if !strings.Contains(prompt.user, "Research Summary (primary evidence)") {+ t.Errorf("prose prompt = %q, want the summary block", prompt.user)+ }+ if strings.Contains(prompt.user, recordContract) {+ t.Error("the record contract must not label a prose summary")+ }+}++// TestAnswerRecordCarriesTheProbeLedger pins the block that closes the measured+// write-back gap: the slots are the model's own bookkeeping, so a run can probe+// twenty-four terms, get a passage for every one, and record eleven — and the+// answer then sees only the eleven while the rest exist merely inside the pool.+//+// The two lists stay apart on purpose: "reached" is a fact about the corpus,+// "nothing back" is a fact about the QUERY (not an absence).+func TestAnswerRecordCarriesTheProbeLedger(t *testing.T) {+ kb := &harness.Kbinfos{Record: "- slot 0 [count]: 11"}+ kb.RecordReachedTerm("车胄", "c1")+ kb.RecordReachedTerm("管亥", "c2")+ kb.RecordProbedAbsent("温酒")++ prompt := AnswerDeps{}.answerPromptWithEvidence(kb, "q", false, false)+ for _, want := range []string{+ "- slot 0 [count]: 11", // the slots come first+ "Probed and answered",+ "车胄", "管亥",+ "Probed with NOTHING back",+ "温酒",+ } {+ if !strings.Contains(prompt.user, want) {+ t.Errorf("answer prompt missing %q", want)+ }+ }+ // "Nothing back" may not be described as absence: that reading is what stops+ // an enumeration short.+ if strings.Contains(prompt.user, "absent from the corpus") && !strings.Contains(prompt.user, "this is not \"absent\"") {+ t.Error("the not-reached list must refuse the absence reading")+ }+ // The ledger belongs to the answer prompt, not to the SCA-facing draft.+ if strings.Contains(kb.PreSummary, "Probed and answered") {+ t.Error("the probe ledger must not leak into the SCA draft")+ }+}++// TestSessionPatchLogNamesBothSidesOfTheTournament pins P13 for the one place a+// list can vanish without a trace: MergeSlotPatch keeps ONE candidate per slot,+// chosen by the strength the model reported, and the losing candidate is then in+// no table, no draft and no record.+//+// The log line is the only place that fact can exist, so it has to name both the+// claim and the base it lost to.+func TestSessionPatchLogNamesBothSidesOfTheTournament(t *testing.T) {+ var buf bytes.Buffer+ orig := _LOG+ _LOG = log.New(&buf, "", 0)+ defer func() { _LOG = orig }()++ strong, weak := 0.97, 0.85+ base := harness.NewState([]harness.Variable{+ {ID: 1, Type: "entity", Candidate: strPtr("孔秀、孟坦"), CandidateStrength: &strong},+ }, 0, nil)+ patch := harness.NewState([]harness.Variable{+ {ID: 1, Type: "entity", Candidate: strPtr("华雄、颜良、庞德"), CandidateStrength: &weak},+ }, 0, nil)++ // The weaker claim loses: the slot still holds the base afterwards.+ logSessionPatch(2, base, base, patch)+ got := buf.String()+ for _, want := range []string{"华雄、颜良、庞德", "0.85", "孔秀、孟坦", "0.97", "NOT ADOPTED"} {+ if !strings.Contains(got, want) {+ t.Errorf("log %q missing %q", got, want)+ }+ }++ // Adopted: the slot holds the patch's candidate afterwards.+ buf.Reset()+ merged := harness.NewState([]harness.Variable{+ {ID: 1, Type: "entity", Candidate: strPtr("华雄、颜良、庞德"), CandidateStrength: &weak},+ }, 1, nil)+ logSessionPatch(2, base, merged, patch)+ if got := buf.String(); !strings.Contains(got, "adopted") || strings.Contains(got, "NOT ADOPTED") {+ t.Errorf("log %q, want the adopted verdict", got)+ }+}++// TestMergeSlotPatchKeepsTheStrongestClaim is the behaviour the log above exists+// to expose: a weaker branch candidate must NOT overwrite a stronger base, and a+// stronger one must.+// TestMergeSlotPatchKeepsTheStrongestClaim pins the rule for a slot that holds+// ONE value: sessions fold in completion order, so a weak tentative claim must+// not downgrade what another session already proved. Sets are exempt from this+// rule on purpose — see TestMergeSlotPatchMergesSetCandidates.+func TestMergeSlotPatchKeepsTheStrongestClaim(t *testing.T) {+ strong, weak := 0.97, 0.85+ base := harness.NewState([]harness.Variable{+ {ID: 1, Type: "entity", Candidate: strPtr("白马坡"), CandidateStrength: &strong},+ }, 0, nil)+ weaker := harness.NewState([]harness.Variable{+ {ID: 1, Type: "entity", Candidate: strPtr("延津"), CandidateStrength: &weak},+ }, 0, nil)+ if merged := MergeSlotPatch(base, weaker); merged != nil {+ if got := *merged.ByID(1).Candidate; got != "白马坡" {+ t.Errorf("slot 1 = %q, want the stronger base candidate to stand", got)+ }+ }++ stronger := harness.NewState([]harness.Variable{+ {ID: 1, Type: "entity", Candidate: strPtr("延津"), CandidateStrength: &strong},+ }, 0, nil)+ base = harness.NewState([]harness.Variable{+ {ID: 1, Type: "entity", Candidate: strPtr("白马坡"), CandidateStrength: &weak},+ }, 0, nil)+ if merged := MergeSlotPatch(base, stronger); merged == nil || *merged.ByID(1).Candidate != "延津" {+ t.Error("a strictly stronger branch candidate must be adopted")+ }+}++// TestMergeSlotPatchMergesSetCandidates pins the set rule: a slot that holds a+// SET is unioned, because "the stronger claim wins" DISCARDS the members only the+// weaker list held.+//+// Measured (2026-09-15, 三国演义/关羽): one session enumerated twelve members into+// slot 0, a second had already written "10" there at strength 0.90, the twelve+// lost at 0.85, and the answer was the 10 — while 管亥 and 车胄 (two of the+// twelve) had each returned ten passages of their own.+func TestMergeSlotPatchMergesSetCandidates(t *testing.T) {+ strong, weak := 0.90, 0.85++ // A list beats a NUMBER: the number is a claim ABOUT the list, and the list is+ // the members. The number is not lost — it stays as an alternate clue.+ base := harness.NewState([]harness.Variable{+ typedCountVar(1, "count", 10, strong),+ }, 0, nil)+ enumeration := harness.NewState([]harness.Variable{+ typedMembersVarS(1, "count", weak, "华雄", "颜良", "管亥", "车胄", "蔡阳"),+ }, 0, nil)+ merged := MergeSlotPatch(base, enumeration)+ if merged == nil {+ t.Fatal("the enumeration must change the slot: five members are not a count of ten")+ }+ if got := *merged.ByID(1).Candidate; got != "华雄、颜良、管亥、车胄、蔡阳" {+ t.Fatalf("slot 1 = %q, want the enumerated list to hold the slot", got)+ }+ if alts := alternateCandidatesOf(*merged.ByID(1)); len(alts) != 1 || alts[0] != "10" {+ t.Fatalf("alternates = %v, want the losing count kept", alts)+ }++ // Two lists union, and neither side's members are dropped.+ twoLists := MergeSlotPatch(+ harness.NewState([]harness.Variable{+ typedMembersVarS(1, "entity", strong, "孔秀", "孟坦"),+ }, 0, nil),+ harness.NewState([]harness.Variable{+ typedMembersVarS(1, "entity", weak, "华雄", "颜良", "庞德"),+ }, 0, nil),+ )+ if twoLists == nil {+ t.Fatal("two lists must union")+ }+ for _, want := range []string{"孔秀", "孟坦", "华雄", "颜良", "庞德"} {+ if got := *twoLists.ByID(1).Candidate; !strings.Contains(got, want) {+ t.Errorf("slot 1 = %q, want %s kept", got, want)+ }+ }++ // Two numbers keep the larger: a set that shrinks when a second source agrees+ // with it is a set that loses members.+ numbers := MergeSlotPatch(+ harness.NewState([]harness.Variable{+ typedCountVar(1, "count", 10, strong),+ }, 0, nil),+ harness.NewState([]harness.Variable{+ typedCountVar(1, "count", 12, weak),+ }, 0, nil),+ )+ if numbers == nil || *numbers.ByID(1).Candidate != "12" {+ t.Fatalf("two counts must keep the larger one, got %v", numbers)+ }+}++// TestReconcileCountSlotsTakesTheEnumeratedSize pins the other half of the same+// loss: the count slot and the list slots are written by different sessions and+// nothing kept them in step. The slot takes the DERIVED number in both directions,+// because a count is a claim the table can check.+//+// The direction that matters is the one an answer repeats: measured (2026-09-16) a+// count slot left holding a session's 28 against thirteen enumerated members+// produced "killed 28 named people" over a list of a handful. An over-claim is kept+// as an alternate clue, so the record still shows what was claimed.+func TestReconcileCountSlotsTakesTheEnumeratedSize(t *testing.T) {+ table := harness.NewState([]harness.Variable{+ typedCountVar(0, "count", 10, 0),+ typedMembersVar(1, "person", "华雄、颜良、文丑、孔秀、孟坦、韩福、卞喜、王植、秦琪、蔡阳、车胄、管亥"),+ }, 0, nil)+ raised := reconcileCountSlots(&table)+ if len(raised) != 1 || raised[0] != 0 {+ t.Fatalf("raised = %v, want the count slot reconciled", raised)+ }+ if got := *table.ByID(0).Candidate; got != "12" {+ t.Fatalf("count slot = %q, want 12 (the list's size)", got)+ }++ // An over-claim does not stand: the members are what the table can check, and+ // the claim is kept beside them as an alternate.+ bigger := harness.NewState([]harness.Variable{+ typedCountVar(0, "count", 16, 0),+ typedMembersVar(1, "person", "华雄、颜良、文丑、孔秀、孟坦、韩福"),+ }, 0, nil)+ if changed := reconcileCountSlots(&bigger); len(changed) != 1 {+ t.Fatalf("changed = %v, want the over-claim reconciled to the members", changed)+ }+ if got := *bigger.ByID(0).Candidate; got != "6" {+ t.Fatalf("count slot = %q, want 6 (the members' size)", got)+ }+ alts := alternateCandidatesOf(*bigger.ByID(0))+ if len(alts) != 1 || alts[0] != "16" {+ t.Fatalf("alternates = %v, want the over-claim kept as the record's alternate", alts)+ }++ // A count that already agrees is left alone.+ agreed := harness.NewState([]harness.Variable{+ typedCountVar(0, "count", 6, 0),+ typedMembersVar(1, "person", "华雄、颜良、文丑、孔秀、孟坦、韩福"),+ }, 0, nil)+ if changed := reconcileCountSlots(&agreed); len(changed) != 0 {+ t.Fatalf("changed = %v, want an agreeing count untouched", changed)+ }++ // A count slot that carries NO number at all is given the derived one: measured+ // (2026-09-16, 三国/关羽) a session wrote "约 17-19 人" into it, the qualifiers and+ // the digits ended up in neither a member nor a number, and the record was left+ // with a count nobody could reconstruct.+ unreadable := harness.NewState([]harness.Variable{+ {ID: 0, Type: "count", Candidate: strPtr("约 17-19 人")},+ typedMembersVar(1, "person", "华雄、颜良、文丑、孔秀、孟坦、韩福"),+ }, 0, nil)+ if changed := reconcileCountSlots(&unreadable); len(changed) != 1 {+ t.Fatalf("changed = %v, want the unreadable count healed from the members", changed)+ }+ if got := *unreadable.ByID(0).Candidate; got != "6" {+ t.Fatalf("count slot = %q, want 6 (the derived number)", got)+ }++ // The count of a table whose member slot is TEXT is left alone: prose claims no+ // number and no members, and nothing here guesses at either.+ textOnly := harness.NewState([]harness.Variable{+ {ID: 0, Type: "count", Candidate: strPtr("约 17-19 人")},+ {ID: 1, Type: "person", Candidate: strPtr("华雄、颜良、文丑")},+ }, 0, nil)+ if changed := reconcileCountSlots(&textOnly); len(changed) != 0 {+ t.Fatalf("changed = %v, want nothing derived from text", changed)+ }+}++// TestMemberCountIgnoresProseFragments pins the count's unit: a member is a NAME,+// not a fragment of the sentence around it.+//+// The fixture is a measured record shape — the slots held the right names wrapped+// in chapter prose, SplitCandidateNames cut that prose at its separators, and the+// enumerated size came out 28 against thirteen real names. That number was then+// raised into the count slot and reported by the answer as its own.+func TestMemberCountIgnoresProseFragments(t *testing.T) {+ // The prose is Text and the names are declared members. The fixture that used to+ // prove this (names wrapped in chapter prose, with the parser cutting the prose+ // into "members") cannot be written any more: an undeclared slot contributes+ // nothing, so the count is the members or it is nothing.+ table := harness.NewState([]harness.Variable{+ typedCountVar(0, "count", 28, 0),+ typedMembersVar(1, "web", "孔秀、孟坦、韩福、卞喜、王植、秦琪、蔡阳"),+ {ID: 2, Type: "web", Candidate: strPtr("第五回(发矫诏诸镇应曹公、破关兵三英战吕布)、第二十五回(屯土山关公约三事、救白马曹操解重围)")},+ typedMembersVar(3, "web", "华雄、颜良、文丑、庞德"),+ }, 0, nil)++ // Eleven distinct real names: the prose pieces around them are not members.+ if got := enumeratedSize(table); got != 11 {+ t.Fatalf("enumerated size = %d, want 11 (the declared names, not the chapter prose)", got)+ }+ // And the count slot takes that number rather than the session's claim.+ reconcileCountSlots(&table)+ if got := *table.ByID(0).Candidate; got != "11" {+ t.Fatalf("count slot = %q, want 11 (the enumerated members)", got)+ }+}++// TestMergeSlotPatchKeepsTheLosingClaimAsAnAlternate pins the bookkeeping that+// survives every rule in MergeSlotPatch: one slot holds one candidate, so the+// claim that lost the comparison used to leave no trace at all — not in the+// table, not in the draft, not in the record. The framework does not decide which+// claim is true; it stops discarding the one that lost.+//+// Sets no longer lose at all (they union, see+// TestMergeSlotPatchMergesSetCandidates), so this pins the single-value case.+func TestMergeSlotPatchKeepsTheLosingClaimAsAnAlternate(t *testing.T) {+ strong, weak := 0.97, 0.85+ base := harness.NewState([]harness.Variable{+ {ID: 1, Type: "entity", Candidate: strPtr("白马坡"), CandidateStrength: &strong},+ }, 0, nil)+ branch := harness.NewState([]harness.Variable{+ {ID: 1, Type: "entity", Candidate: strPtr("延津"), CandidateStrength: &weak},+ }, 0, nil)++ merged := MergeSlotPatch(base, branch)+ if merged == nil {+ t.Fatal("the losing claim must still change the state: it is kept as an alternate")+ }+ v := merged.ByID(1)+ if v.Candidate == nil || *v.Candidate != "白马坡" {+ t.Fatalf("slot 1 = %v, want the stronger claim to hold the slot", v.Candidate)+ }+ alts := alternateCandidatesOf(*v)+ if len(alts) != 1 || alts[0] != "延津" {+ t.Fatalf("alternates = %v, want the losing claim kept", alts)+ }++ // It reaches the ANSWER-facing record, which is the whole point: the answer+ // must be able to see that two claims exist.+ rec := RenderSlotRecord(*merged, "")+ if !strings.Contains(rec, "alternate") || !strings.Contains(rec, "延津") {+ t.Fatalf("record = %q, want the alternate rendered", rec)+ }++ // And it survives a SECOND merge: alternates accumulate, they do not compete.+ strongerAgain := harness.NewState([]harness.Variable{+ {ID: 1, Type: "entity", Candidate: strPtr("斜谷"), CandidateStrength: &strong},+ }, 0, nil)+ merged2 := MergeSlotPatch(*merged, strongerAgain)+ if merged2 == nil {+ t.Fatal("a third claim must fold in")+ }+ if got := alternateCandidatesOf(*merged2.ByID(1)); len(got) != 2 {+ t.Fatalf("alternates = %v, want both losing claims kept", got)+ }+}++// TestSlotRecordLeadsWithFactsNotWithASessionsProse pins the answer-layer fix.+//+// The record used to LEAD with one session's prose draft answer, and the answer+// copied it: measured twice (2026-09-15, 三国演义/关羽) — a record whose slots+// enumerated seventeen members produced a fifteen-member answer, and a record+// enumerating fourteen produced a ten-member answer, in both cases exactly the+// number written in that prose. The prose is one session's recollection, written+// before the other sessions were merged; it is a claim to reconcile with the+// members, not the record.+func TestSlotRecordLeadsWithFactsNotWithASessionsProse(t *testing.T) {+ table := harness.NewState([]harness.Variable{+ typedCountVar(0, "count", 10, 0),+ typedMembersVar(1, "person", "华雄、颜良、文丑、孔秀、孟坦、韩福、卞喜、王植、秦琪、蔡阳、车胄、程远志、夏侯存、庞德"),+ // A second slot of the same table holds REFERENCES, not members — and it is+ // TEXT, so it contributes none: counting them is how this record once+ // answered its own count with a nineteen on a twelve-member list.+ {ID: 2, Type: "dataset", Candidate: strPtr("第5回(华雄)、第21回(车胄)、第25回(颜良)、第27回(五关六将)、第74回(庞德)")},+ }, 0, nil)+ rec := RenderSlotRecord(table, "关羽在《三国演义》中斩杀的有姓名人物共10人,名单如下:……")++ if !strings.Contains(rec, "enumerated members across the slots above: 14") {+ t.Fatalf("record = %q, want the enumerated size stated as a fact", rec)+ }+ // A count that disagrees with the members has to be SAID: this record once+ // produced a nineteen-person answer out of a count slot reading 19, which the+ // answer explained as seven more people "the material does not list".+ if !strings.Contains(rec, "slot 0 [count] says 10 while the slots above enumerate 14") {+ t.Fatalf("record = %q, want the disagreement stated", rec)+ }+ // Stated, not ordered: an order was tried and reverted — measured (2026-09-16,+ // 三国/关羽) a record that said "take the number from the enumerated members" got+ // exactly that number taken (nine), when its slots enumerated the wrong things and+ // its sessions had found fourteen. Either number can be the wrong one, and only the+ // passages decide, so the note must state the disagreement and leave the judgement+ // to the stage that reads them.+ if strings.Contains(rec, "take the number from") {+ t.Fatalf("record = %q, must not order the answer to take either number", rec)+ }+ if !strings.Contains(rec, "disagree") {+ t.Fatalf("record = %q, want the disagreement stated as a disagreement", rec)+ }+ facts := strings.Index(rec, "slot 1 [person]")+ draft := strings.Index(rec, "One session's own draft answer")+ if facts < 0 || draft < 0 || facts > draft {+ t.Fatalf("record = %q, want the slots BEFORE the session's own draft", rec)+ }+ if !strings.Contains(rec, "UNVERIFIED") {+ t.Fatalf("record = %q, want the draft labelled as a claim", rec)+ }+}++// TestValueRecordCarriesNoEnumeratedMembers pins the other half of the gate: the+// enumerated size, the count-vs-members warning and the demotion of the session's+// prose are SET-question machinery, and a record whose answer is one date or one+// number must render exactly as it did before any of it existed.+//+// The table is the measured case. A "how much shorter is A than B" question's+// record carried `- slot 1 [number]: 133 feet` beside `- enumerated members across+// the slots above: 16`, where the 16 was `Grace's、High、Falls、Colonial、Creek` —+// one waterfall's name cut at its separators by whoever wrote it into the slot —+// and the session's draft answer was labelled UNVERIFIED below it. Rendered+// ungated, those two lines appeared in 21 of a 20-question FRAMES run's records.+func TestValueRecordCarriesNoEnumeratedMembers(t *testing.T) {+ table := harness.NewState([]harness.Variable{+ {ID: 0, Type: "dataset", Candidate: strPtr("Grace's、High、Falls、Colonial、Creek")},+ {ID: 1, Type: "number", Candidate: strPtr("133 feet")},+ {ID: 2, Type: "web", Candidate: strPtr("Colonial Creek Falls, Washington — 788 m (2,585 ft)")},+ }, 0, nil)+ rec := RenderSlotRecord(table, "Alabama's tallest waterfall is 133 feet tall.")++ if strings.Contains(rec, "enumerated members") {+ t.Fatalf("record = %q, want no enumerated line on a value table", rec)+ }+ if strings.Contains(rec, "UNVERIFIED") {+ t.Fatalf("record = %q, want the session's answer NOT demoted on a value table", rec)+ }+ if !strings.HasPrefix(rec, "Candidate answer: Alabama's tallest waterfall is 133 feet tall.") {+ t.Fatalf("record = %q, want the session's answer first on a value table", rec)+ }+ for _, want := range []string{"- slot 0 [dataset]:", "- slot 1 [number]: 133 feet", "788 m (2,585 ft)"} {+ if !strings.Contains(rec, want) {+ t.Errorf("record %q missing the slot fact %q", rec, want)+ }+ }+}++// TestUnionSetCandidatesIsOrderIndependent pins the bug that cost the most members+// in the 2026-09-16 enumeration runs.+//+// The union must not depend on which side is the base: with the base the LONGER+// list, "the union adds nothing to the base" was answered as "no conclusion", the+// caller fell through to the strength rule, and a SHORTER list — the one the model+// was sure of, so the one it called stronger — replaced the list containing it.+//+// Measured in the run this pins: twenty-four names probed and each reached, slot 1+// holding thirteen members, a session patching its own eleven at 0.95 against the+// base's 0.90, and a final record of eleven.+// typedMembersValue is a slot value that DECLARES a member list — the only shape the+// runtime counts (see package slots): names with no declared kind are opaque text.+func typedMembersValue(list string) slots.Value {+ items := strings.Split(list, "、")+ members := make([]slots.Member, 0, len(items))+ for _, n := range items {+ members = append(members, slots.Member{Name: strings.TrimSpace(n)})+ }+ return slots.Members(members...)+}++// typedMembersVar is typedMembersValue as the slot variable a session would patch.+func typedMembersVar(id int, typ, list string) harness.Variable {+ return typedMembersVarS(id, typ, 0, strings.Split(list, "、")...)+}++// typedMembersVarS is the same with an explicit strength, the way a session's patch+// carries one.+func typedMembersVarS(id int, typ string, strength float64, names ...string) harness.Variable {+ items := make([]slots.Member, 0, len(names))+ for _, n := range names {+ if n = strings.TrimSpace(n); n != "" {+ items = append(items, slots.Member{Name: n})+ }+ }+ v := slots.Members(items...)+ rendered := slots.Render(v)+ out := harness.Variable{ID: id, Type: typ, Candidate: &rendered, Value: &v}+ if strength > 0 {+ out.CandidateStrength = &strength+ }+ return out+}++func typedCountVar(id int, typ string, n int, strength float64) harness.Variable {+ v := slots.Number(n)+ rendered := slots.Render(v)+ out := harness.Variable{ID: id, Type: typ, Candidate: &rendered, Value: &v}+ if strength > 0 {+ out.CandidateStrength = &strength+ }+ return out+}++func TestUnionIsOrderIndependent(t *testing.T) {+ eleven := typedMembersValue("华雄、管亥、颜良、文丑、孔秀、孟坦、韩福、卞喜、王植、秦琪、蔡阳")+ thirteen := typedMembersValue("华雄、颜良、文丑、孔秀、孟坦、韩福、卞喜、王植、秦琪、蔡阳、庞德、成何、管亥")+ names := func(v slots.Value) string {+ out := v.Names()+ sort.Strings(out)+ return strings.Join(out, "、")+ }+ want := names(thirteen)++ up, _, ok := slots.Union(eleven, thirteen)+ if !ok || names(up) != want {+ t.Fatalf("small→big: union = %q ok = %v, want the thirteen-name superset", slots.Render(up), ok)+ }+ down, _, ok := slots.Union(thirteen, eleven)+ if !ok {+ t.Fatal("big→small must resolve too: a subset is a resolution, not a tiebreaker for strength")+ }+ if names(down) != want {+ t.Fatalf("big→small: union = %q, want the base kept whole (a subset adds nothing)", slots.Render(down))+ }++ // Two numbers keep the larger one, in both orders.+ if got, _, ok := slots.Union(slots.Number(13), slots.Number(11)); !ok || got.Count != 13 {+ t.Fatalf("13→11 = %v ok=%v, want the larger count", got, ok)+ }+ if got, _, ok := slots.Union(slots.Number(11), slots.Number(13)); !ok || got.Count != 13 {+ t.Fatalf("11→13 = %v ok=%v, want the larger count", got, ok)+ }++ // A number never outvotes the members it counts: the number is the claim that+ // loses, kept as the dropped value.+ union, dropped, ok := slots.Union(thirteen, slots.Number(11))+ if !ok || union.Kind != slots.KindMembers {+ t.Fatalf("members vs count = %v ok=%v, want the members", union, ok)+ }+ if dropped.Count != 11 {+ t.Fatalf("dropped = %v, want the losing count", dropped)+ }++ // Text is not the union's business: a value question merges by strength, exactly+ // as it did before values were typed.+ if _, _, ok := slots.Union(slots.Text("1858"), slots.Text("1849")); ok {+ t.Error("text must not merge by union — that is what keeps a value question on its strength rule")+ }+}++// TestMemberUnionDropsPlaceAndEventPhrases pins the last way a count inflates: a+// piece that CONTAINS a member is not a second member.+//+// A session writing a place beside its owner (`洛阳关孟坦`) or an event beside its+// object (`温酒斩华雄`) writes a token that is short, digit-free and unpunctuated —+// it passes every shape test a name passes — while the member it names is already+// in the table. Measured (2026-09-16): a record enumerating 21 names counted 25,+// the four extra being place-qualified copies of names already listed.+func TestMemberUnionDropsPlaceAndEventPhrases(t *testing.T) {+ table := harness.NewState([]harness.Variable{+ typedMembersVar(1, "person", "程远志、华雄、管亥、颜良、文丑、杨龄、孔秀、孟坦、韩福、卞喜、王植、秦琪、车胄、成何、蔡阳、吕旷、吕翔、荀正、纪灵、夏侯存、庞德"),+ typedMembersVar(2, "person", "孟坦、韩福、卞喜、王植、秦琪、洛阳关孟坦、汜水关卞喜、荥阳王植、黄河渡口秦琪"),+ }, 0, nil)++ union := memberUnion(&table)+ if len(union) != 21 {+ t.Fatalf("member count = %d, want the 21 names (place-qualified copies are not members): %v", len(union), union)+ }+ for _, extra := range []string{"洛阳关孟坦", "汜水关卞喜", "荥阳王植", "黄河渡口秦琪"} {+ for _, item := range union {+ if item == extra {+ t.Errorf("member union kept %q, a name with its place attached", extra)+ }+ }+ }+ if got := enumeratedSize(table); got != 21 {+ t.Fatalf("enumerated size = %d, want 21", got)+ }+}++// TestLedgerQuoteCarriesTheWordsBehindAMember pins per-member evidence in the+// answer-facing ledger: a name without the words behind it is a member nobody can+// point at, and an answer handed names only cannot cite one passage per member.+func TestLedgerQuoteCarriesTheWordsBehindAMember(t *testing.T) {+ kb := &harness.Kbinfos{}+ kb.Admit(func(p *harness.PoolAdmitter) {+ p.Add(map[string]any{"chunk_id": "c1", "content": "关公马快,赶上文丑,脑后一刀,将文丑斩下马来。"})+ })+ kb.RecordReachedTerm("文丑", "c1")++ // The names are in the ledger either way; the words ride the set gate, so a+ // value direction does not pay for them.+ if ledger := probeLedger(kb); strings.Contains(ledger, "斩下马来") {+ t.Fatalf("ledger = %q, want no per-member quotes before a set direction declares itself", ledger)+ }++ kb.MarkSetDirection()+ ledger := probeLedger(kb)+ if !strings.Contains(ledger, "文丑 — “") {+ t.Fatalf("ledger = %q, want the member followed by the words that carry it", ledger)+ }+ if !strings.Contains(ledger, "斩下马来") {+ t.Fatalf("ledger = %q, want the quoted passage itself", ledger)+ }+}++// TestRecordContractStatesTheSettledValueIsTheAnswer pins the half of the record+// contract that the measured "not found" answer needed: a record that is only a+// check is droppable when the passages do not repeat its value.+//+// Measured (2026-09-16, FRAMES, mode high): the slot table held+// `slot 0 [person]: Colin Beashel and Richard Coxon (Australia, Star class 1984+// Olympics)` and the composed answer was "not found in the knowledge base" — the+// passages around it were about other competitions, and the chat configuration+// requires that sentence when the information is unavailable. The record has to+// outrank the absence, or the research that found the answer is discarded.+func TestRecordContractStatesTheSettledValueIsTheAnswer(t *testing.T) {+ for _, want := range []string{+ "that value IS the answer",+ "do not report that the answer was not found while a slot holds one",+ "evidence plainly contradicts a settled value",+ "NEVER quote these lines",+ "probed-and-answered",+ } {+ if !strings.Contains(recordContract, want) {+ t.Errorf("recordContract is missing %q", want)+ }+ }+}++// TestBudgetExtensionIsBoughtOncePerQuestion pins the one-shot budget extension a+// set-shaped pass buys.+//+// The budget fits ONE pass, and an enumeration needs a second one to pick up the+// members a cut first pass never patched (measured 2026-09-16, 三国/关羽: the run+// ended at `ROUND 1 end (unresolved=0)` with the reached-but-unpatched 管亥 gone).+// One extension, not a per-round top-up: the point is a second look, not an+// unbounded run for any table that keeps declaring a set.+func TestBudgetExtensionIsBoughtOncePerQuestion(t *testing.T) {+ st := &AgenticState{Deadline: time.Now().Add(30 * time.Second)}+ before := st.RemainingS()+ if !st.ExtendDeadline(SetBudgetExtensionS) {+ t.Fatal("the first extension must apply")+ }+ after := st.RemainingS()+ if after < before+SetBudgetExtensionS-1 {+ t.Errorf("remaining %.0fs after the extension, want ~%.0fs", after, before+SetBudgetExtensionS)+ }+ if st.ExtendDeadline(SetBudgetExtensionS) {+ t.Error("a second extension must be refused: the budget is bought once per question")+ }+ if got := st.RemainingS(); got > after+1 {+ t.Errorf("remaining %.0fs after the refused extension, want ~%.0f", got, after)+ }+}++// TestMergeSlotPatchKeepsTheDeclaration pins what the fold must NOT drop.+//+// Terms/Subject are the planner's declaration of how the source words the deed, and the+// completeness pass is built from them (harness.ScanPatterns / RunCompletenessPass).+// Rebuilding the slot without them is why one run's second round had no act patterns at+// all: measured (2026-09-16, 三国/关羽) round 1's session seeds carried 6325 characters+// (method + the declared patterns) and round 2's carried 4150 (method only) — the recovery+// round, opened by the routing precisely because the record was still short, ran with the+// enumeration machinery switched off.+func TestMergeSlotPatchKeepsTheDeclaration(t *testing.T) {+ base := harness.NewState([]harness.Variable{+ {ID: 0, Type: "count", Terms: []string{"斩", "杀"}, Subject: "关羽|云长"},+ {ID: 1, Type: "dataset"},+ }, 0, nil)+ strong := 0.9+ branch := harness.NewState([]harness.Variable{+ {ID: 1, Type: "dataset", Candidate: strPtr("孔秀、孟坦"), CandidateStrength: &strong},+ }, 1, nil)++ merged := MergeSlotPatch(base, branch)+ if merged == nil {+ t.Fatal("MergeSlotPatch returned nil for a branch that carries a candidate")+ }+ if got := merged.State[0].Terms; len(got) != 2 || got[0] != "斩" || got[1] != "杀" {+ t.Errorf("merged Terms = %v, want the declaration to travel with the slot", got)+ }+ if got := merged.State[0].Subject; got != "关羽|云长" {+ t.Errorf("merged Subject = %q, want the declared actor", got)+ }+ // The declaration is what renders the completeness queries: a fold that drops it makes+ // the next round's seed patternless, which is the measured failure above.+ if patterns := harness.ScanPatterns(*merged); len(patterns) == 0 {+ t.Error("the merged table renders no act patterns: the declaration was lost in the fold")+ }+}++// patternStubExec answers tool calls like sessionStubExec and is ALSO a+// harness.PatternRunner, so a round's completeness pass runs without a retriever.+type patternStubExec struct {+ mu sync.Mutex+ calls []string+}++func (e *patternStubExec) Execute(_ context.Context, name string, _ map[string]any) (harness.ToolOutcome, error) {+ return harness.ToolOutcome{+ Status: harness.StatusOK,+ Payload: []any{map[string]any{"kind": name, "content": "hit"}},+ EvidenceIDs: []string{"c-" + name},+ }, nil+}++func (e *patternStubExec) RunPattern(_ context.Context, _ string) []map[string]any {+ e.mu.Lock()+ e.calls = append(e.calls, "called")+ e.mu.Unlock()+ return []map[string]any{{"chunk_id": "w1", "content_with_weight": "云长手起刀落,斩孔秀于马下"}}+}++func (e *patternStubExec) ran() int {+ e.mu.Lock()+ defer e.mu.Unlock()+ return len(e.calls)+}++// TestRunSlotResearchPassRunsTheDeclaredPatterns pins the wiring, and the run-once rule.+//+// The patterns used to be seeded as a list of queries TO MAKE, and a whole round ran+// without a single one of them being made (see harness.RunCompletenessPass). Now the round+// asks the corpus itself, admits what comes back, and seeds the sessions with it.+func TestRunSlotResearchPassRunsTheDeclaredPatterns(t *testing.T) {+ table := func() harness.State {+ return harness.NewState([]harness.Variable{+ {ID: 0, Type: "count", Terms: []string{"斩", "杀"}, Subject: "关羽|云长"},+ {ID: 1, Type: "dataset", QuestionClues: []string{"who did he kill?"}},+ }, 0, nil)+ }+ exec := &patternStubExec{}+ kb := &harness.Kbinfos{}+ st := &AgenticState{Question: "关羽杀了多少有姓名的人物?", KB: kb, SlotTable: table()}+ deps := harness.SessionDeps{+ Model: &scriptedModel{replies: []string{"I could not find any evidence about that."}},+ Tools: &harness.Toolset{Exec: exec},+ KB: kb,+ }+ RunSlotResearchPass(context.Background(), context.Background(), deps, st.Question, st, 60)++ want := len(harness.ScanPatterns(table()))+ if got := exec.ran(); got != want {+ t.Fatalf("ran %d pattern(s), want every rendered one (%d)", got, want)+ }+ block, done := kb.PatternFindings()+ if !done || !strings.Contains(block, "w1") || !strings.Contains(block, "斩孔秀于马下") {+ t.Fatalf("stored block = %q (done=%v), want the window the pass brought back", block, done)+ }+ if kb.PoolSize() == 0 {+ t.Error("the pass's window never reached the pool: the win cannot be cited")+ }++ // A second round REUSES the block: the windows are in the pool under the same ids, so+ // asking the same corpus the same questions again spends the store legs for nothing.+ second := &AgenticState{Question: st.Question, KB: kb, SlotTable: table()}+ RunSlotResearchPass(context.Background(), context.Background(), deps, second.Question, second, 60)+ if got := exec.ran(); got != want {+ t.Errorf("second round ran %d pattern(s), want the stored block reused (still %d)", got, want)+ }+}diff --git a/internal/rag/advanced_rag/evidence_fill_test.go b/internal/rag/advanced_rag/evidence_fill_test.goindex 7e61aed276..86e9f496ea 100644--- a/internal/rag/advanced_rag/evidence_fill_test.go+++ b/internal/rag/advanced_rag/evidence_fill_test.go@@ -159,7 +159,7 @@ func TestRunSlotResearchPass_PrefilledSlotsSkipSession(t *testing.T) {mdl := &scriptedModel{}deps := harness.SessionDeps{Model: mdl, KB: kb}- res := RunSlotResearchPass(context.Background(), deps, st.Question, st, 120.0)+ res := RunSlotResearchPass(context.Background(), context.Background(), deps, st.Question, st, 120.0)if res == nil {t.Fatal("expected a result")}diff --git a/internal/rag/advanced_rag/harness/action_session.go b/internal/rag/advanced_rag/harness/action_session.goindex dea5623337..02a222208e 100644--- a/internal/rag/advanced_rag/harness/action_session.go+++ b/internal/rag/advanced_rag/harness/action_session.go@@ -36,6 +36,7 @@ import ("gorm.io/gorm""ragflow/internal/agent/chat"+ "ragflow/internal/rag/advanced_rag/slots""ragflow/internal/rag/prompts""ragflow/internal/common"@@ -68,6 +69,43 @@ type Variable struct {DiscoveredClues []stringCandidate *stringCandidateStrength *float64+ // Value is the TYPED candidate (see package slots): what this slot holds, as+ // data. It is set when the model DECLARED a kind, and nil otherwise.+ //+ // nil means "untyped", not "unknown": Candidate still carries the text, and that+ // text is OPAQUE — nothing may split it, count it, or compare it numerically.+ // Typing is what lets the runtime merge and count without guessing, so an+ // untyped slot is simply not merged by union (see slots.Union I1) rather than+ // parsed to find out what it might have been.+ Value *slots.Value+ // Terms are the ACT WORDS a direction declared for this slot — how its source+ // words the deed being enumerated (斩 / 杀 / 诛 / 劈 / 砍). They are declared,+ // never inferred from a slot's text or from the question.+ //+ // They exist because an enumeration cannot be bounded by what the model can+ // recall: the corpus holds the truth, and the words the source uses are what+ // reaches it. The runtime renders them into completeness queries and RUNS them+ // (see ScanPatterns / RunCompletenessPass), and the sessions read what came back,+ // so the tail of the list is a property of the corpus rather than of the model's+ // memory.+ Terms []string+ // Subject is WHO the act is about, declared next to the act words ("关羽"). The+ // pattern asks for subject AND act together, because an act word on its own has a+ // poor candidate pool (measured 2026-09-16: 劈 returned nothing for a book whose+ // text says 劈管亥于马下). Empty means the pattern searches the term alone.+ Subject string+}++// Typed is the value this slot holds, for merging and counting. An untyped slot is+// Text by definition — its candidate verbatim, never interpreted.+func (v Variable) Typed() slots.Value {+ if v.Value != nil {+ return *v.Value+ }+ if v.Candidate != nil {+ return slots.Text(*v.Candidate)+ }+ return slots.Value{}}// Brief mirrors Python Variable.brief: one-line rendering for prompts.@@ -210,6 +248,7 @@ func ApplyPatch(base State, branchPatches []map[string]any) *State {DiscoveredClues: append([]string(nil), v.DiscoveredClues...),Candidate: v.Candidate,CandidateStrength: v.CandidateStrength,+ Value: v.Value,}newVars = append(newVars, nv)}@@ -243,16 +282,32 @@ func ApplyPatch(base State, branchPatches []map[string]any) *State {}nv := &newVars[idx]- if raw, has := pv["candidate"]; has {+ if rawKind, has := pv["kind"]; has && rawKind != nil && strings.TrimSpace(fmt.Sprint(rawKind)) != "" {+ // A patch that DECLARES what it holds is read as data (package slots) and+ // its rendered text is kept in Candidate, so every renderer, prompt and+ // log keeps working unchanged. This branch is the whole point of the+ // typed contract: the structure the model states is carried, and nothing+ // downstream has to infer it back from a string.+ value := slots.Parse(pv)+ nv.Value = &value+ rendered := slots.Render(value)+ nv.Candidate = &rendered+ changed = true+ } else if raw, has := pv["candidate"]; has {// Mirror Python apply_patch: `str(x) if x else None` — any falsy// value (0, 0.0, False, "", [], {}, None) becomes None, NOT its// string form. fmt.Sprint would otherwise turn 0/False into// "0"/"false", which Python drops.if !isTruthy(raw) {nv.Candidate = nil+ nv.Value = nil} else {s := fmt.Sprint(raw)nv.Candidate = &s+ // Opaque by construction: the model did not say what this is, so+ // nothing here will guess (see Variable.Value).+ text := slots.Text(s)+ nv.Value = &text}changed = true}@@ -925,11 +980,14 @@ var (Type: "function",Function: ToolFunction{Name: "retrieve",- Description: `WHEN TO CALL: Use when you know or suspect exact surface terms or keywords in the corpus (names, titles, codes, phrases). Best as the first recall pass; send 1-3 queries covering different facets.` +- `DO NOT CALL: When you already hold a doc_id and need to read it (use list_chunks); when the answer shares no surface words with any query (use search_chunks); for counting or enumerating a whole document.` +- `ARGUMENTS: query — array of 1-3 strings (natural-language queries). Note: doc_scope exists inside the executor but is NOT a declared parameter; do not pass it.` +- `OUTPUT: Short exact-term-matched snippets, each carrying its doc_id and chunk id. Status ok means new evidence entered the pool; redundant means everything was already there.` +- `IF IT FAILS: miss (empty payload) means this query matched nothing — rephrase or switch to search_chunks; do not conclude the corpus lacks the fact. redundant means stop re-searching and emit a state patch.`,+ Description: `WHEN TO CALL: you know or suspect exact surface terms in the corpus (names, titles, codes, phrases) — the first recall pass; cover different facets.` ++ `HOW IT WORKS: keyword recall FIRST, then the pattern is applied to what came back — ` + "`A.*B`" + ` (A then B, anything between) matches only inside the passages its operands recalled, and the RAREST operand bounds it: put the rare word first. A FULL recall page was truncated.` ++ `ONE STRING, MANY TERMS: ` + "`A|B|C`" + ` recalls each term in ONE call — synonyms belong in one string, not one call each.` ++ `ENUMERATING A SET: probe the NAMES themselves, alternated with |, 4-6 per query. Hits are members; guess the next batch yourself rather than stopping at what you hold.` ++ `DO NOT CALL: for a whole document (list_chunks); when no surface word matches (search_chunks).` ++ `ARGUMENTS: query — array of 1-3 strings; only a query's first ~10 snippets survive; doc_scope is NOT declared.` ++ `OUTPUT: Exact-term snippets with doc_id and chunk id. ok = new evidence; redundant = seen.` ++ `IF IT FAILS: a miss on an exact-term probe means the corpus lacks that term — in an enumeration that is a RESULT (record it as not a member, probe the next). redundant = stop and emit a state patch.`,Parameters: arrayParam("", 1, 3),},}@@ -1254,6 +1312,12 @@ type ToolOutcome struct {Status string // one of the Status* constantsReason string // one of the Reason* constantsMetrics map[string]any // numeric signals: hits, new_evidence, top_score, ...+ // Note is a line ABOUT this call, rendered into the tool result next to the+ // passages (see toolNode). It carries what the passages cannot say: which of+ // the terms the call asked about were reached and which were not, so a batch+ // probe ("华雄|颜良|蔡阳") is actionable rather than four passages whose+ // missing member looks exactly like a member nobody asked for.+ Note string}// NewToolOutcome builds an OK outcome with an empty metric map.@@ -1301,8 +1365,35 @@ const (initTimeoutS = 45.0// actionTimeoutS is the default per-session wall-clock budget.actionTimeoutS = 75.0- // snippetsPerQuery caps snippets returned per query.+ // setActionTimeoutS is the wall clock an ENUMERATION session gets, i.e. a+ // session whose direction declared a set (see SessionWallS). The extra time is+ // not a bigger turn budget — the turns are what the enumeration spends, and one+ // of them is a batch of names whose results have to be read and patched. It is+ // measured: 三国/关羽 (2026-09-16) lost the member 管亥 — reached, three+ // passages, admitted to the shared pool by its own batch — because the pass+ // cancelled the session at its 120s wall clock ONE MILLISECOND before the patch+ // that would have recorded it (14:09:53.573 `context deadline exceeded` vs+ // 14:09:53.574 for the session that made it). A value question has nothing to+ // spend the extra time on, so it keeps the tighter clock.+ setActionTimeoutS = 150.0+ // snippetsPerQuery is the FALLBACK per-query snippet cap, used when the mode+ // leaves ModeSpec.SnippetsPerQuery unset. The live value is+ // snippetsPerQueryFor(RunRequest.ThinkingMode).snippetsPerQuery = 4+ // evidenceDigestChars bounds ONE chunk in the session seed's ALREADY RETRIEVED+ // digest. It matches what an admitted passage carries (passageFromChunk: 1200), so+ // the digest never shows a session LESS of a chunk than the same chunk would carry+ // as a tool result.+ //+ // The previous 300-code-point cut (Python's `[:300]`) ended mid-sentence on+ // narrative passages — and the model, told to answer only from what it was shown,+ // excluded the people whose kill clause fell outside the window. Measured+ // (2026-09-14, on the fixrecall line): with the cut at 1200 an enumeration run+ // reached seventeen members while runs before and after it stalled four short with+ // the same passages in the pool. Ported here after measuring the same shape on+ // 2026-09-16: 管亥 / 杨龄 / 程远志 appeared ZERO times in whole runs whose pools held+ // their passages.+ evidenceDigestChars = 1200// maxToolResponseChars bounds ONE tool payload.maxToolResponseChars = 12000// emptyStrikes is how many dataset-level empties (reason=no_structure) a@@ -1322,12 +1413,49 @@ const (// converges to finalize instead of burning the remaining budget on// paraphrases (Q30/Q759 timeout root cause).skippedDupLimit = 2+ // turnRunExtra is how many turns the MODEL may add beyond the mode's floor+ // (see offerContinuation): medium/high run 8 → 12, ultra 10 → 14. It is the+ // hard bound the runtime keeps while the decision itself is the model's, so an+ // eager model cannot turn one session into a whole research programme.+ turnRunExtra = 4+ // valueTurnFloor is the floor a session runs on when it is NOT assembling a set+ // (see actionMaxTurns). It is the floor every mode had before the enumeration+ // path asked for a larger one (medium/high 4 → 8, ultra 6 → 10): the extra turns+ // exist to spend a batch of NAMES turn after turn, and a session that never+ // writes one has no batch to spend them on — while the mode's number is billed+ // to every turn of every session on the question. Measured (2026-09-16, FRAMES,+ // mode high) the floor rise took per-question cost 88k → 160k tokens with a 227s+ // single request against a 300s client timeout, on a workload that writes almost+ // no batches; the one question that does enumerate pays the larger floor once.+ valueTurnFloor = 4+ // turnAskFloorS is the session clock below which no further turn is offered:+ // the finalize/salvage step must still fit, or the extra turn buys evidence+ // that never reaches the slot table.+ turnAskFloorS = 20.0// finalizeTimeout bounds the salvage call in the finalize node.finalizeTimeoutS = 150.0// minFinalizeTimeout is the floor for the salvage call.minFinalizeTimeoutS = 15.0)+// snippetsPerQueryFor resolves the per-query snippet cap for a thinking mode.+//+// The cap decides how much of ONE query's candidate list the session reads, and+// that list is where a themed query's fact-bearing passage sits: the engine+// returns 30-60 candidates per leg, and on a 64-candidate leg the passage that+// carried the answer ranked 20th and 38th — both discarded by a cap of four,+// while handing the model those same passages produced the complete list.+//+// It therefore rises with the mode (a deeper mode issues more queries and owns a+// larger budget) and falls back to the flat snippetsPerQuery when the mode leaves+// it unset, so a mode that never declared one behaves exactly as before.+func snippetsPerQueryFor(mode string) int {+ if spec := GetMode(mode); spec.SnippetsPerQuery > 0 {+ return spec.SnippetsPerQuery+ }+ return snippetsPerQuery+}+// retrievalTools: near-duplicate suppression applies to these (Python// _RETRIEVAL_TOOLS). grep_chunks / grep_search are legacy names kept so a// model emitting them is still deduped rather than executed.@@ -1690,6 +1818,37 @@ type SessionState struct {// ToolOutcomes is the audit trail of (name, status, reason, metrics).ToolOutcomes []map[string]any+ // KB is the shared evidence pool. The session reads it for the per-turn+ // RECORD line (see SessionRecord) and for the names the evidence offers;+ // the tools write it. Nil skips both.+ KB *Kbinfos+ // Record is the last turn's record — the facts the continuation decision is+ // made from (see offerContinuation and SessionRecord).+ Record SessionRecord+ // PoolWalk is how many pool chunks this session has already looked at while+ // choosing an excerpt to show (see unreadPoolExcerpt). The pool only ever+ // appends, so the watermark is what keeps a session from being shown the same+ // passage twice.+ PoolWalk int+ // PoolRead is whether this session has already been given its one pool excerpt+ // (see unreadPoolExcerpt): the read is a last resort, not a routine.+ PoolRead bool+ // ContinuationAsked is the Attempts value the continuation offer was appended+ // for, so one turn never carries the offer twice.+ ContinuationAsked int+ // EnumerationProtocol is the SET-direction method this session MAY be handed:+ // seeded when the table declared a set (see setProtocolFor), and appended once+ // mid-session when the caller writes its first batch (see appendBatchProtocol).+ // Resolved once at seed time so nothing mid-session needs the prompt loader.+ EnumerationProtocol string+ // BatchProtocolShown is whether the mid-session append has happened. Once per+ // session: the method repeated is prompt noise.+ BatchProtocolShown bool+ // floorGateLogged records that the turn floor was reported (see actionMaxTurns).+ // The floor is resolved on every turn, so only the first resolution is worth a+ // log line — it is what says whether the shape gate fired for this session.+ floorGateLogged bool+Direction stringRoutedDocs []string// NavHint is the joined routed-doc summaries carried by the navigation@@ -1828,6 +1987,9 @@ func (s *SessionState) toolNode(ctx context.Context) error {if s.Tools == nil {return nil}+ // ranAny: whether this node executed at least one call, i.e. whether a tool+ // result exists to annotate with the turn's record line (appendRecordLine).+ ranAny := len(s.PendingCalls) > 0evidenceIDs := append([]string(nil), s.RetrievedEvidenceIDs...)budgetChars := s.CtxBudgetif budgetChars <= 0 {@@ -1930,7 +2092,14 @@ func (s *SessionState) toolNode(ctx context.Context) error {"name": c.Name, "status": oc.Status, "reason": oc.Reason, "metrics": oc.Metrics,})+ // The payload stays the JSON document it always was; the call's own note+ // rides BEHIND it, exactly like the turn's record line (appendRecordLine),+ // so nothing that parses the payload has to learn about either.payload := marshalPassages(chunks)+ if oc.Note != "" {+ payload += "\n" + oc.Note+ _LOG.Printf("[Action Session] result note (%s): %s", c.Name, trunc(oc.Note, 280))+ }// If the session is already heavy, cut this payload proportionally.// Python :1509-1514 counts len() of a str — CODE POINTS, not bytes — so// the budget and the cut must be rune-based too; a byte cap would hit@@ -2008,17 +2177,357 @@ func (s *SessionState) toolNode(ctx context.Context) error {s.SearchQueries = seenQueriess.SkippedDup += skippeds.ToolStrikes = strikes+ s.appendBatchProtocol(ranAny)+ s.appendRecordLine(ranAny)return nil}+// appendBatchProtocol hands the set-direction method to a session that has SHOWN it+// is enumerating — the second, and the only zero-false-positive, delivery.+//+// A session seeded by setProtocolFor already has the text; this path exists for the+// set direction whose planner typed its count slot `number` rather than `count` (the+// same question was typed both ways on two runs of 2026-09-16), and the signal it+// rides is the caller's own writing: the model writes a batch of items exactly when+// the direction is a set — measured the same day, same server: 0 batches over 20+// FRAMES questions, 18 over one 三国 question.+//+// It rides the tool result the model is about to read, like the record line, and is+// appended at most once per session.+func (s *SessionState) appendBatchProtocol(ranAny bool) {+ if s.BatchProtocolShown || !ranAny || s.EnumerationProtocol == "" || len(s.Messages) == 0 {+ return+ }+ if !s.wroteBatch() {+ return+ }+ last := &s.Messages[len(s.Messages)-1]+ if last.Role != schema.Tool {+ return+ }+ s.BatchProtocolShown = true+ last.Content = strings.TrimRight(last.Content, "\n") + "\n\n" + s.EnumerationProtocol+ // The same signal widens the retrieval budget for the rest of the run: on a+ // set direction a dropped query is a member nobody searched, and the batch+ // the caller just wrote is the proof that this direction is assembling a set+ // (see Kbinfos.MarkSetDirection).+ s.KB.MarkSetDirection()+ _LOG.Printf("[Action Session] the caller wrote a batch — set-direction method appended to the turn (%d char(s))",+ len(s.EnumerationProtocol))+}++// appendRecordLine appends the per-turn RECORD line to the last tool result.+//+// This is the loop's feedback channel: the model's next query was otherwise aimed+// with no knowledge of what this session had already probed (and what came back+// empty), which names the record already holds, which confirmed names are still+// undecided, or which names the passages themselves offer. All of that is+// computed here anyway — it was simply never shown.+//+// It rides on the last tool message instead of a message of its own: one line,+// same turn, no extra role in the conversation, and nothing to do with Python's+// message shape (which never had this feedback to begin with).+//+// The line is appended ONLY when this node ran at least one tool call, so a turn+// with no calls cannot accumulate duplicates of the previous line.+func (s *SessionState) appendRecordLine(ranAny bool) {+ if !ranAny || len(s.Messages) == 0 {+ return+ }+ rec := s.sessionRecordNow()+ grew := rec.grewFrom(s.Record)+ s.Record = rec+ // A session that is not ENUMERATING gets no line at all (see enumerating).+ //+ // The line reports members, probed names and reached names — the set's to-do+ // list. On a single-value question every field of it is empty or meaningless+ // (`members=0 | probed-reached=0`), it is recomputed and appended on every turn,+ // and the model then spends turns on it: measured (2026-09-15, FRAMES) 214+ // lines across 20 questions while the same benchmark without them scored+ // 0/1/2 zeros and had 60 rounds against this run's 68. The record itself is+ // still kept on the session (the continuation ask reads it), only the line the+ // model sees is skipped.+ if !s.enumerating() {+ return+ }+ // The line the model steers by is message content, so the log could not show+ // whether a mechanism fired at all: three rounds of analysis here ended up+ // inferring it from side effects. One truncated line per turn ends that.+ _LOG.Printf("[Action Session] record line: %s", trunc(rec.Line(), 320))+ last := &s.Messages[len(s.Messages)-1]+ if last.Role != schema.Tool || rec.Pool == 0 {+ // No pool bound (or no tool result to annotate): keep the record, skip the+ // line rather than inventing a message for it.+ return+ }+ line := rec.Line()+ last.Content = strings.TrimRight(last.Content, "\n") + "\n" + line+ // An ENUMERATION session whose record has gone FLAT also gets one excerpt from a+ // pool passage it has never been shown (see unreadPoolExcerpt): the round has+ // already paid for that text, unread text is where unnoticed members live, and a+ // session that is still finding things does not need rescuing. Gated on the+ // shape so no other question pays for it at all, and one excerpt per turn.+ if s.enumerating() && !grew {+ if excerpt := s.unreadPoolExcerpt(); excerpt != "" {+ // Logged as well as delivered: whether the mechanism fired is otherwise+ // only visible inside the message content.+ _LOG.Printf("[Action Session] pool excerpt: %s", trunc(excerpt, 240))+ last.Content += "\n" + excerpt+ }+ }+}++// turnRunCap is the hard ceiling on a session's turns: the mode's floor plus the+// turns the model may add on its own decision (see offerContinuation).+func (s *SessionState) turnRunCap() int { return s.actionMaxTurns() + turnRunExtra }++// offerContinuation asks the MODEL whether the session takes another turn.+//+// The mode's turn count used to end the session outright (ActionMaxTurns was 4 on+// medium/high at the time), and the measured cost is in the log: at 18:09:49 a session still+// turning named terms into evidence was finalized by `Attempts >= 4`+// mid-enumeration, with 84s of its own clock unspent and a tool result the model+// never read. Replacing that with a runtime heuristic ("did the record grow?")+// fixed the cut-off but bought the wrong thing: the ledger grows whenever the+// model PROBES, so the heuristic extended sessions that were piling up findings+// without recording any (measured: four extensions in a row at+// `members=0 reached=8 undecided=8`).+//+// So the floor is the floor and the decision is the model's: it is told the+// budget state, handed the record line it just received, and asked to continue+// only for something that line shows is missing — otherwise to emit the state+// patch now. The runtime keeps two hard bounds it does not delegate: the run cap+// above (so an eager model cannot run away) and the session clock (below which no+// further turn is offered, because the finalize/salvage step must still fit).+//+// The offer is gated on this session ENUMERATING (see enumerating): an extra turn is+// an extra model call plus up to turnRunExtra more turns, and a question that is not+// assembling a set has nothing for those turns to find.+//+// Measured (2026-09-15): while the gate read the shape of the planner's table, 24+// offers went to FRAMES questions doing arithmetic over two values — 68 rounds+// against that benchmark's own baseline of 60 — while the caller's own batch, which+// this reads, was written ZERO times by the same 20 questions.+func (s *SessionState) offerContinuation() bool {+ if !s.enumerating() {+ return false+ }+ if s.Attempts >= s.turnRunCap() || s.DeadlineLeft <= turnAskFloorS {+ return false+ }+ if s.ContinuationAsked == s.Attempts {+ return true+ }+ s.ContinuationAsked = s.Attempts+ ask := continuationAsk(s.Attempts, s.turnRunCap(), s.Record.Brief())+ s.Messages = appendMessages(s.Messages, *schema.UserMessage(ask))+ _LOG.Printf("[Action Session] turn %d/%d — the floor is spent; offered the model one more turn while the record says something is missing (%s, %.0fs left).\noffer=%q",+ s.Attempts, s.turnRunCap(), s.Record.Brief(), s.DeadlineLeft, trunc(ask, 700))+ return true+}++// parentSetShaped reports whether the direction this session was sent on ASKS FOR+// A SET — what the planner DECLARED, never what a candidate looks like (see+// SetShaped).+func (s *SessionState) parentSetShaped() bool { return SetShaped(s.ParentState) }++// wroteBatch reports whether the CALLER wrote a batch of terms in one query — the+// signal that it is enumerating rather than asking a question.+//+// The gate is the caller's own writing, not a guess about the question, because the+// guess is measurably wrong: measured (2026-09-15, one server session, two workloads)+// a 20-question FRAMES run wrote ZERO batches while ONE 三国 question wrote fifteen,+// and the shape test misfired on eleven FRAMES sessions — a slot TYPE cannot tell+// "how many people did X kill" from "how many times larger is A than B", and a single+// phrase's commas make it look like two members.+func (s *SessionState) wroteBatch() bool {+ for _, q := range s.SearchQueries {+ if callerBatch(q) {+ return true+ }+ }+ return false+}++// enumerating reports whether this session is assembling a SET: the caller wrote a+// batch (the tell that survives contact), or the direction's own table asks for a+// count/list.+//+// The table stays as the second half on purpose: a session may enumerate without ever+// writing a two-name batch (one probe per member), and then the record line is+// exactly what it needs. That half's false positives are bounded and counted — over+// one 20-question FRAMES run it opened once (a sentence written into a count-typed+// slot); the batch half opened zero times.+func (s *SessionState) enumerating() bool {+ return s.wroteBatch() || s.parentSetShaped()+}++// SetShaped reports whether the table ASKS FOR A SET, and nothing broader: a slot+// the planner typed count / set / list.+//+// This — not enumerates — is what the RUNTIME gates on (the per-turn line, the pool+// excerpt, the continuation offer). A question can hold a list-shaped CANDIDATE+// without asking for a set: measured (2026-09-15, FRAMES) a slot typed "dataset"+// carried `Grace's、High、Falls、Colonial、Creek` — ONE waterfall's name cut at its+// separators — and the permissive test read that as five members, rendering+// "enumerated members across the slots above: 16" into the answer's record of a+// "how much shorter" question. A false positive here is paid on every turn of every+// session on that question, so the runtime asks only what the planner declared.+func SetShaped(table State) bool {+ for _, v := range table.State {+ switch strings.ToLower(strings.TrimSpace(v.Type)) {+ case "count", "set", "list":+ return true+ }+ }+ return false+}++// SessionWallS is the wall clock a session on this direction is given: the+// enumeration clock when the table declared a set, the default one otherwise.+//+// It is a FUNCTION of the shape rather than a constant because the shape decides+// what the time is spent on: an enumeration session is mid-batch when its clock runs+// out, and a batch that is cut loses the members it had already reached (see+// setActionTimeoutS for the measurement). A value session has no such work in+// flight, so it keeps the tighter clock and the shorter end-to-end latency.+//+// The caller owns the context: this number is only the budget a session is told it+// has, and a pass whose own timeout is shorter still bounds it (see+// RunSlotResearchPass, which hangs the session clock off the round's PARENT because+// the round's own clock is fixed before the table — and therefore the shape — is+// known).+func SessionWallS(parent State) float64 {+ if SetShaped(parent) {+ return setActionTimeoutS+ }+ return actionTimeoutS+}++// setProtocolFor returns the method a session sent on this direction is SEEDED with,+// or "" when the direction is not assembling a set.+//+// The method is `action_set`, and both halves of when it is delivered are measured:+// its FIRST instruction — propose more candidates than you expect — is a decision+// taken before the first query, so a direction that has declared itself a set is+// seeded (measured 2026-09-16, 三国/关羽: eighteen members with the method in the seed+// of a `[count]` table, fourteen when it arrived a turn later); and a direction that+// has not is handed it after the first batch it writes (see appendBatchProtocol),+// which is the signal with no measured false positives.+//+// The gate is EnumerationShaped — the planner's own three statements about the answer+// (count/set/list, a NAME-carrying slot, act words) — and never a reading of a+// candidate. Measured (2026-09-16, FRAMES): the permissive version seeded 44 of 67+// sessions, 2777 characters of set strategy each, on questions that assemble nothing+// (named-term seats 0, batch weaving 0); the SetShaped-only version still seeded the+// handful of value questions that merely contain a count, and that run — 4 questions in+// flight, 300s deadline — finished 0.833 with two timeouts against 0.875 with none.+func setProtocolFor(table State, prompts PromptLoader) string {+ method := setMethodFor(table, prompts)+ if method == "" {+ return ""+ }+ // The pattern list belongs to the enumeration strategy alone (see EnumerationShaped): the+ // planner declares act words for "a count of things someone DID" too, and a list of corpus+ // queries is neither useful nor free on a question whose answer is a number (measured+ // 2026-09-16, FRAMES — see EnumerationShaped for the run that paid for it).+ if !EnumerationShaped(table) {+ return method+ }+ patterns := ScanPatterns(table)+ if len(patterns) == 0 {+ return method+ }+ // The corpus queries the direction's own declaration allows, rendered next to the method+ // that uses them (see ScanPatterns): completeness belongs to the corpus, and this is the+ // question that makes it answer — actor and act together, once per act word.+ //+ // This is the FALLBACK shape: when the runtime already ran them, enumerationSeed seeds+ // what came back instead (see RunCompletenessPass).+ var b strings.Builder+ b.WriteString(method)+ b.WriteString("\n## The act patterns this direction declared — one call per line\n\n")+ for _, p := range patterns {+ fmt.Fprintf(&b, "- %s\n", p)+ }+ return b.String()+}++// setMethodFor returns the enumeration METHOD alone (see setProtocolFor), or "" when the+// direction is not assembling a set. Its gate is SetShaped — what the planner declared+// (count/set/list) — and nothing else: measured (2026-09-16, FRAMES), the permissive+// reading of a candidate seeded 44 of 67 sessions with 2777 characters of set strategy each+// on questions that assemble nothing.+func setMethodFor(table State, prompts PromptLoader) string {+ // The gate is the whole shape of the question, not just "a count appears in it" (see+ // EnumerationShaped): the method tells a session to enumerate NAMED members, and a single-value+ // question that merely contains a number must not be told to assemble anything.+ if !EnumerationShaped(table) {+ return ""+ }+ return loadOptionalPrompt(prompts, "action_set")+}++// enumerationSeed builds the enumeration text a session is seeded with.+//+// findings is the completeness pass's output (see RunCompletenessPass): the windows the+// direction's own act patterns brought back, already in the pool. When it is present the+// seed carries IT and not the list of patterns to make — measured (2026-09-16, 三国/关羽) a+// round rendered 2175 characters of patterns into the seed of every session and not one+// session ran a single one of them (the run's query log holds zero `.*` queries), while a+// window is evidence that cannot be unread. The pattern list stays the fallback for a run+// where nothing could be run (no runner, an exhausted context, a patternless table).+func enumerationSeed(table State, prompts PromptLoader, findings string) string {+ if f := strings.TrimSpace(findings); f != "" {+ if method := setMethodFor(table, prompts); method != "" {+ return method + "\n\n" + f+ }+ return f+ }+ return setProtocolFor(table, prompts)+}++// continuationAsk is the offer the model decides on: it names the hard bound, the+// remaining turns, and the ONLY grounds on which another turn is granted — what+// the record line shows is still missing. The record itself was appended to the+// model's last tool result, so the decision is made on facts, not on appetite.+func continuationAsk(taken, cap int, record string) string {+ return fmt.Sprintf(+ "TURN BUDGET: %d turn(s) taken, up to %d available. DECIDE NOW — your next reply decides it:\n"++ "- If the [record] line still shows something MISSING — a name you proved reachable and never recorded, a slot with no candidate, an angle you have not tried — call ONE more tool aimed at exactly that. %d turn(s) left.\n"++ "- Otherwise emit the state patch NOW with everything you have.\n"++ "An extra turn is only for something the record line shows is missing; re-running a search you already ran is not.\n"++ "Current record: %s",+ taken, cap, cap-taken, record)+}+// finalizeNode mirrors Python _finalize_node: tool budget spent — ONE last call// WITHOUT tools, demanding the terminal JSON to salvage whatever was learned.func (s *SessionState) finalizeNode(ctx context.Context) error {budgetPrompt := ("TOOL BUDGET EXHAUSTED. Based ONLY on the passages retrieved above, output now — no prose outside the block:\n" +- "<state>{\"new_states\": [{\"state\": [{\"id\": <slot_id>, \"candidate\": \"<value>\", " +- "\"candidate_strength\": <0..1>, \"discovered_clues\": [\"...\"]}]}]}</state>\n" ++ "<state>{\"new_states\": [{\"state\": [{\"id\": <slot_id>, \"kind\": \"members\", " ++ "\"items\": [{\"name\": \"<name>\", \"chunk_id\": \"<its passage>\"}], " ++ "\"candidate_strength\": <0..1>}]}]}</state>\n" ++ "Use \"kind\": \"count\" with \"count\": <n> for a number, and \"kind\": \"text\" with " ++ "\"candidate\": \"<value>\" for one value that is neither a member list nor a number.\n" +"If NOTHING was learned use: <state>{\"new_states\": []}</state>")+ // The patch written HERE is the one that lands in the record, so the record is+ // part of the order.+ //+ // Measured (fixrecall2, 2026-09-15): a session probed 成何, the corpus returned+ // three passages, and the terminal patch did not mention him — the run's own+ // evidence, found and paid for, dropped at the last step. The record is the+ // only place that fact exists, and this is the last call that can act on it, so+ // the salvage order names the names it has to account for instead of asking for+ // "whatever you have".+ if rec := s.sessionRecordNow(); rec.Pool > 0 {+ budgetPrompt += "\n\nAccount for the record below in the patch you write. Every name listed as " ++ "FOUND BUT NOT RECORDED has a passage in the pool, so it is either a member this patch includes or " ++ "a name this patch REJECTS with its clue. More searching is no longer possible, so an unmentioned " ++ "name is simply lost.\n" + rec.Line()+ }+// Defensive: strip any assistant.tool_calls that never got a tool response,// else the provider rejects the history.msgs := append([]schema.Message(nil), s.Messages...)@@ -2119,12 +2628,29 @@ const ()// actionMaxTurns mirrors Python _action_max_turns: the mode's turn budget.+//+// The mode's number is a FLOOR, and it is billed to every turn of every session on+// the question, so it is paid only by the shape it was raised for: the deeper modes+// lifted it (medium/high 4 → 8, ultra 6 → 10) for the enumeration path, whose turns+// each spend a batch of names. A session that is not assembling a set has no such+// batch and runs on the value floor instead (see valueTurnFloor for the measurement).+// A shape that declares itself LATER is not penalised: the floor is resolved per+// turn, so the first batch — or a parent table that declares a count/list — raises+// it for the turns that follow.func (s *SessionState) actionMaxTurns() int {- spec := ResolveMode(s.Tools)- if spec.ActionMaxTurns <= 0 {- return 4+ floor := ResolveMode(s.Tools).ActionMaxTurns+ if floor <= 0 {+ floor = valueTurnFloor+ }+ if floor > valueTurnFloor && !s.enumerating() {+ if !s.floorGateLogged {+ s.floorGateLogged = true+ _LOG.Printf("[Action Session] turn floor %d → %d: this session is not assembling a set (%q, mode %s)",+ floor, valueTurnFloor, trunc(s.Direction, 60), ResolveMode(s.Tools).Label)+ }+ return valueTurnFloor}- return spec.ActionMaxTurns+ return floor}// route mirrors Python _route.@@ -2140,6 +2666,11 @@ func (s *SessionState) route() routeTarget {return routeTool}if s.Attempts >= s.actionMaxTurns() {+ // The mode's turn count is a FLOOR: past it the MODEL decides whether the+ // session takes another turn, up to the run cap (see offerContinuation).+ if s.offerContinuation() {+ return routeRunAction+ }return routeFinalize}// No-progress convergence: the model keeps re-issuing near-duplicate@@ -2159,6 +2690,12 @@ func (s *SessionState) route() routeTarget {// route was never reached and the session burned the whole timeout.func (s *SessionState) routeAfterTool() routeTarget {if s.Attempts >= s.actionMaxTurns() {+ // Same rule as route: the tool result that just arrived is what the+ // continuation offer is about, so the model decides with it in hand+ // (measured: the run's last probe's result was never read by a turn).+ if s.offerContinuation() {+ return routeRunAction+ }return routeFinalize}return routeRunAction@@ -3111,6 +3648,12 @@ type SessionDeps struct {// "ALREADY RETRIEVED" so the model does not re-retrieve evidence it already// has (mirrors Python run_action_session:1982-1984). Nil skips the injection.KB *Kbinfos+ // PatternFindings is the completeness pass's output for this direction (see+ // RunCompletenessPass): its act patterns were already RUN over the corpus and these+ // are the windows that came back, each with the chunk id it is cited by. When+ // non-empty it replaces the seed's list of patterns to make — a query list is+ // advice, a window is evidence.+ PatternFindings string}// RunActionSession mirrors Python run_action_session: a bounded session@@ -3123,6 +3666,36 @@ func RunActionSession(ctx context.Context, deps SessionDeps, direction string, psystem := loadPrompt(deps.Prompts, "action_run")seedUser := fmt.Sprintf("Direction: %s\n\nState:\n%s", direction, parent.RenderSlots())+ // A direction whose table DECLARED a set is seeded WITH THE METHOD, before its+ // first turn.+ //+ // The method's first instruction is to propose more candidates than you expect,+ // which is a decision taken BEFORE the first query — measured (2026-09-16,+ // 三国/关羽): eighteen members with the method in the seed of a `[count]` table,+ // fourteen when it arrived one turn later. The gate is what the planner declared+ // (SetShaped) and not a reading of the candidates (see setProtocolFor for the+ // forty-four-of-sixty-seven measurement that reverted the permissive version). A+ // set direction whose table was NOT typed that way gets the method from+ // appendBatchProtocol, on the first batch it writes.+ seededMethod := enumerationSeed(parent, deps.Prompts, deps.PatternFindings)+ if seededMethod != "" {+ seedUser += "\n\n" + seededMethod+ // The seeded direction also widens the retrieval budget (see+ // Kbinfos.MarkSetDirection): on a set direction the caller's queries are+ // facets of one list, so the executor must not drop them silently.+ deps.KB.MarkSetDirection()+ // Logged because a seeded method is text inside a prompt: without this line+ // nothing distinguishes "the gate opened for the direction that needed it" from+ // "the gate opened for every direction", which is the failure mode to watch.+ _LOG.Printf("[Action Session] set-shaped direction — enumeration method added to the seed (%d char(s))", len(seededMethod))+ if findings := strings.TrimSpace(deps.PatternFindings); findings != "" {+ // Said separately from the line above, because the difference is the whole+ // point: the seed carries what the declared patterns BROUGHT BACK, not the+ // patterns themselves (see enumerationSeed).+ _LOG.Printf("[Action Session] completeness pass's windows in the seed (%d char(s)) — the act patterns were RUN, not listed.", len(findings))+ }+ }+// ALREADY RETRIEVED (mirrors Python run_action_session:1982-1984):// surface the evidence already in the shared pool so the model fills slots// from it instead of re-retrieving the same ground. Without this the ReAct@@ -3142,7 +3715,9 @@ func RunActionSession(ctx context.Context, deps SessionDeps, direction string, pbudgetLeft := deadlineLeftif budgetLeft <= 0 {- budgetLeft = actionTimeoutS+ // A caller that omits the budget gets the shape's own clock (see+ // SessionWallS): the direction is known here even when the caller is not.+ budgetLeft = SessionWallS(parent)}st := &SessionState{@@ -3153,6 +3728,7 @@ func RunActionSession(ctx context.Context, deps SessionDeps, direction string, pParentState: parent,Tools: deps.Tools,Model: deps.Model,+ KB: deps.KB,PendingCalls: nil,Done: false,NewStates: nil,@@ -3168,6 +3744,15 @@ func RunActionSession(ctx context.Context, deps SessionDeps, direction string, pToolStrikes: map[string]int{},ToolOutcomes: nil,Direction: direction,+ // The method this session may be handed, resolved here so nothing mid-session+ // needs the prompt loader. It arrives in the seed when the table declared a+ // set (see setProtocolFor), or on the first batch the caller writes+ // (appendBatchProtocol) — so it is loaded for every session, and shown at+ // most ONCE: a seeded session is marked as already carrying it, because+ // measured (2026-09-16, 三国) every session of one run had it twice, 2776+ // characters each, once from the seed and once from the batch append.+ EnumerationProtocol: loadOptionalPrompt(deps.Prompts, "action_set"),+ BatchProtocolShown: seededMethod != "",}if st.ToolCache == nil {st.ToolCache = NewToolCache()@@ -3295,7 +3880,21 @@ func InitializeState(ctx context.Context, deps SessionDeps, question string, fanif len(clues) > 4 {clues = clues[:4]}- slots = append(slots, Variable{ID: id, Type: vType, QuestionClues: clues})+ // The slot may DECLARE the act words its enumeration must cover (see+ // Variable.Terms): a missing or malformed list is simply no declaration,+ // never a reason to discard the decomposition.+ terms, _ := pyStringList(m["scan"])+ if len(terms) > scanTermsMax {+ terms = terms[:scanTermsMax]+ }+ kept := make([]string, 0, len(terms))+ for _, t := range terms {+ if t = strings.TrimSpace(t); t != "" {+ kept = append(kept, t)+ }+ }+ subject := strings.TrimSpace(PyStr(m["subject"]))+ slots = append(slots, Variable{ID: id, Type: vType, QuestionClues: clues, Terms: kept, Subject: subject})}}// Python :2130 — `[str(q).strip() for q in (data.get("first_queries") or [])][:3]`:@@ -3524,6 +4123,20 @@ func loadPrompt(p PromptLoader, name string) string {return t}+// loadOptionalPrompt loads a template a given loader may not carry, and returns ""+// instead of panicking.+//+// action_set is optional by design: a loader that predates it (or a test's+// in-memory loader) simply gets no enumeration protocol, and its session runs+// exactly as it did before the protocol existed.+func loadOptionalPrompt(p PromptLoader, name string) string {+ t, err := resolveLoader(p).Load(name)+ if err != nil {+ return ""+ }+ return t+}+// deadlineToDuration converts a seconds budget to a context deadline.// A non-positive budget falls back to the default session timeout so a caller// that omits it does not produce an already-expired context.@@ -3587,10 +4200,12 @@ func extractRelevantEvidence(kb *Kbinfos, direction string, maxChunks int) strinif content == "" {continue}- // Mirror Python: hard-cut at 300 CODE POINTS (:2082 `[:300]`, no- // ellipsis) and flatten newlines so the digest stays single-line per- // chunk and matches Python output.- content = truncateRunes(content, 300)+ // Cap each chunk at evidenceDigestChars and flatten newlines so the digest+ // stays single-line per chunk. The cap used to mirror Python's hard `[:300]`+ // cut; it is 1200 now because a 300-code-point window is shorter than the+ // sentence a kill is reported in (see evidenceDigestChars for the runs that+ // measured it).+ content = truncateRunes(content, evidenceDigestChars)content = strings.ReplaceAll(content, "\n", " ")// Mirror Python f"[{cid}] {text}" so the model can cite the chunk id.b.WriteString("[")diff --git a/internal/rag/advanced_rag/harness/action_session_test.go b/internal/rag/advanced_rag/harness/action_session_test.goindex 676956e1cf..f2610b7b34 100644--- a/internal/rag/advanced_rag/harness/action_session_test.go+++ b/internal/rag/advanced_rag/harness/action_session_test.go@@ -1235,3 +1235,165 @@ func TestParseTerminalEmptyAnswerNotFound(t *testing.T) {t.Errorf("empty answer with patch: branches = %+v, want one state with candidate 74", states)}}++// TestSnippetsPerQueryRisesWithModeAndFallsBack pins the per-query snippet cap.+//+// The cap decides how much of ONE query's candidate list the session reads, and+// that list is where a themed query's fact-bearing passage sits: the engine+// returns 30-60 candidates per leg, and on a 64-candidate leg the passage that+// carried the answer ranked 20th and 38th — both discarded by a flat cap of four,+// while handing the model those same passages produced the complete list.+//+// A deeper mode issues more queries and owns a larger budget, so it reads deeper;+// a mode that declares no cap keeps the flat fallback, which is what every mode+// did before this existed. Nothing here depends on a corpus or a language.+func TestSnippetsPerQueryRisesWithModeAndFallsBack(t *testing.T) {+ for _, mode := range []string{"medium", "high", "ultra"} {+ spec := GetMode(mode)+ if spec.SnippetsPerQuery <= snippetsPerQuery {+ t.Errorf("%s cap = %d, want it above the flat fallback %d", mode, spec.SnippetsPerQuery, snippetsPerQuery)+ }+ if got := snippetsPerQueryFor(mode); got != spec.SnippetsPerQuery {+ t.Errorf("snippetsPerQueryFor(%s) = %d, want %d", mode, got, spec.SnippetsPerQuery)+ }+ }+ if GetMode("medium").SnippetsPerQuery >= GetMode("high").SnippetsPerQuery ||+ GetMode("high").SnippetsPerQuery >= GetMode("ultra").SnippetsPerQuery {+ t.Error("the per-query cap must rise with the mode")+ }+ // Unset (low, or an unknown label) falls back to the flat cap.+ for _, mode := range []string{"low", "no-such-mode"} {+ if got := snippetsPerQueryFor(mode); got != snippetsPerQuery {+ t.Errorf("snippetsPerQueryFor(%q) = %d, want the fallback %d", mode, got, snippetsPerQuery)+ }+ }+}++// TestRetrieveDescriptionCarriesTheEnumerationContract pins the recall path in+// the tool description the model reads while deciding how to call it.+//+// Measured (2026-09-16): the same corpus and question answered sixteen members+// with this contract present and nine-to-fourteen without it, while the runtime+// underneath was identical — the seats, the batch weaving and the reach notes+// exist in BOTH trees. What the description carries is how to ASK: probe the+// names themselves in an alternation, in small batches, guess the next batch+// yourself, and read a miss as a RESULT rather than as silence.+func TestRetrieveDescriptionCarriesTheEnumerationContract(t *testing.T) {+ desc := ToolMap["retrieve"].Function.Description+ for _, want := range []string{+ "ENUMERATING A SET",+ "alternated with |",+ "4-6 per query",+ "guess the next batch yourself",+ "in an enumeration that is a RESULT",+ } {+ if !strings.Contains(desc, want) {+ t.Errorf("retrieve description is missing %q", want)+ }+ }+ // It must not send the opposite instruction. "Do not conclude the corpus lacks+ // the fact" is right for a fuzzy query and wrong for an exact-term probe: a+ // model told that stops probing names and settles for the ones it already+ // holds, which is the shape of the nine-member answer.+ if strings.Contains(desc, "do not conclude the corpus lacks the fact") {+ t.Error("retrieve description must not contradict the enumeration semantics of a miss")+ }+}++// TestTurnFloorIsPaidOnlyByASetSession pins the shape gate on the mode's turn floor.+//+// The deeper modes raised the floor for the enumeration path, and the floor is billed+// to every turn of every session on the question, so a session with no batch to spend+// those turns on must run on the value floor instead. The gate is the session's own+// writing (or a parent table that declares a count/list), resolved per turn, so a+// shape that declares itself later is not penalised.+func TestTurnFloorIsPaidOnlyByASetSession(t *testing.T) {+ ts := &Toolset{ThinkingMode: "high"}+ if got := ResolveMode(ts).ActionMaxTurns; got <= valueTurnFloor {+ t.Fatalf("mode high ActionMaxTurns = %d, want > %d (the floor this gate shares)", got, valueTurnFloor)+ }+ modeFloor := ResolveMode(ts).ActionMaxTurns++ // A value session: no batch written, and the table asks for a value.+ value := &SessionState{+ Tools: ts,+ Direction: "in what year did the Sikh Empire's capital come under the British Crown",+ ParentState: State{State: []Variable{{ID: 0, Type: "date", Candidate: strPtr("1849")}}},+ DeadlineLeft: 70,+ }+ if got := value.actionMaxTurns(); got != valueTurnFloor {+ t.Errorf("value session turn floor = %d, want %d", got, valueTurnFloor)+ }++ // The caller's own batch is the tell that survives contact: the session is now+ // enumerating, and it pays the mode's floor for the turns it spends on it.+ value.SearchQueries = []string{"华雄|颜良|文丑"}+ if got := value.actionMaxTurns(); got != modeFloor {+ t.Errorf("session that wrote a batch turn floor = %d, want %d", got, modeFloor)+ }++ // A direction whose table declares a set needs the floor from its first turn: it+ // may enumerate one probe per member and never write a two-name batch.+ declared := &SessionState{+ Tools: ts,+ Direction: "how many officers did Guan Yu kill",+ ParentState: State{State: []Variable{{ID: 0, Type: "count", Candidate: strPtr("16")}}},+ DeadlineLeft: 70,+ }+ if got := declared.actionMaxTurns(); got != modeFloor {+ t.Errorf("count direction turn floor = %d, want %d", got, modeFloor)+ }+}++// TestSessionWallFollowsTheShape pins the clock an enumeration session gets.+//+// The wall clock is spent differently by the two shapes: an enumeration session is+// midway through a batch when its clock runs out, and a batch that is cut loses the+// members it had already reached — measured (2026-09-16, 三国/关羽) a session was+// cancelled one millisecond before the patch that recorded 管亥, a member it had+// already found and whose passages were already in the shared pool. A value session+// has no work in flight at its deadline, so it keeps the tighter clock.+func TestSessionWallFollowsTheShape(t *testing.T) {+ set := State{State: []Variable{{ID: 0, Type: "count", Candidate: strPtr("13")}}}+ if got := SessionWallS(set); got != setActionTimeoutS {+ t.Errorf("set-shaped direction wall = %.0f, want %.0f", got, setActionTimeoutS)+ }+ value := State{State: []Variable{{ID: 0, Type: "date", Candidate: strPtr("1858")}}}+ if got := SessionWallS(value); got != actionTimeoutS {+ t.Errorf("value direction wall = %.0f, want %.0f", got, actionTimeoutS)+ }+ if setActionTimeoutS <= actionTimeoutS {+ t.Errorf("the set clock (%.0f) must exceed the value clock (%.0f)", setActionTimeoutS, actionTimeoutS)+ }+}++// TestDigestShowsAPassageWholeEnoughToNameSomeone pins the seed digest's per-chunk+// cap.+//+// The digest is how a session SEES the pool without re-querying it, and its cap used+// to mirror Python's hard `[:300]` cut. A 300-code-point window is shorter than the+// sentence a deed is reported in: the passage names the actor early and the person at+// the end, so the cut removed exactly the clause that makes a member a member — and a+// model told to answer only from what it was shown then excluded them.+//+// Measured (2026-09-14, fixrecall): with the cap at 1200 an enumeration reached+// seventeen members. Measured here (2026-09-16, 三国/关羽): 管亥 / 杨龄 / 程远志+// appeared ZERO times in whole runs whose pool held their passages.+func TestDigestShowsAPassageWholeEnoughToNameSomeone(t *testing.T) {+ narrative := strings.Repeat("却说曹兵势大", 60) + "云长手起刀落,砍杨龄于马下。"+ kb := &Kbinfos{}+ kb.Admit(func(p *PoolAdmitter) {+ p.Add(map[string]any{"chunk_id": "c1", "content": narrative})+ })++ digest := extractRelevantEvidence(kb, "关羽杀了多少有姓名的人物", 4)+ if !strings.Contains(digest, "砍杨龄于马下") {+ t.Fatalf("digest = %q…, want the clause that names the member (cap %d)", truncateRunes(digest, 120), evidenceDigestChars)+ }+ if got := len([]rune(digest)); got > evidenceDigestChars+64 {+ t.Errorf("digest = %d runes, want no more than one capped chunk plus its id", got)+ }+ if evidenceDigestChars < 1200 {+ t.Errorf("digest cap = %d, want at least the 1200 an admitted passage carries", evidenceDigestChars)+ }+}diff --git a/internal/rag/advanced_rag/harness/config.go b/internal/rag/advanced_rag/harness/config.goindex f61adea46e..619171ca6b 100644--- a/internal/rag/advanced_rag/harness/config.go+++ b/internal/rag/advanced_rag/harness/config.go@@ -54,7 +54,16 @@ type ModeSpec struct {SCAMaxRounds intUseFanout boolActionMaxTurns int- Tools map[string]bool+ // SnippetsPerQuery caps how many hits of ONE query the session reads.+ //+ // It rises with the mode because a deeper mode issues more queries and can+ // absorb more evidence per query, while one flat cap for every mode is what+ // drops the long tail: the engine returns 30-60 candidates per leg, the+ // fact-bearing passage of a themed query ranks far down that list, and a cap+ // of four discards it even though the query DID reach it. Zero means "unset":+ // the session falls back to snippetsPerQuery (see snippetsPerQueryFor).+ SnippetsPerQuery int+ Tools map[string]bool}// toolsOf builds the tool set from names (mirrors Python _tools()).@@ -82,22 +91,26 @@ var THINKING_MODES = map[string]ModeSpec{"low": {Label: "low", Agentic: false, EnableSCA: false,SCAMaxRounds: 0, UseFanout: false, ActionMaxTurns: 4,- Tools: map[string]bool{},+ SnippetsPerQuery: 0,+ Tools: map[string]bool{},},"medium": {Label: "medium", Agentic: true, EnableSCA: true,- SCAMaxRounds: 3, UseFanout: false, ActionMaxTurns: 4,- Tools: allToolSet(),+ SCAMaxRounds: 3, UseFanout: false, ActionMaxTurns: 8,+ SnippetsPerQuery: 6,+ Tools: allToolSet(),},"high": {Label: "high", Agentic: true, EnableSCA: true,- SCAMaxRounds: 3, UseFanout: true, ActionMaxTurns: 4,- Tools: allToolSet(),+ SCAMaxRounds: 3, UseFanout: true, ActionMaxTurns: 8,+ SnippetsPerQuery: 8,+ Tools: allToolSet(),},"ultra": {Label: "ultra", Agentic: true, EnableSCA: true,- SCAMaxRounds: 5, UseFanout: true, ActionMaxTurns: 6,- Tools: toolsOf(append(append([]string{}, allTools...), GraphExploreTool)...),+ SCAMaxRounds: 5, UseFanout: true, ActionMaxTurns: 10,+ SnippetsPerQuery: 10,+ Tools: toolsOf(append(append([]string{}, allTools...), GraphExploreTool)...),},}diff --git a/internal/rag/advanced_rag/harness/grep_sed_narrow.go b/internal/rag/advanced_rag/harness/grep_sed_narrow.goindex ffb6acf72c..b4ae520b7a 100644--- a/internal/rag/advanced_rag/harness/grep_sed_narrow.go+++ b/internal/rag/advanced_rag/harness/grep_sed_narrow.go@@ -17,8 +17,11 @@package harnessimport (+ "fmt"+ "log""regexp""strings"+ "unicode""unicode/utf8")@@ -122,6 +125,11 @@ func TermsToPatterns(terms []string) []*regexp.Regexp {// GrepTermsMax caps the terms extracted from a query (Python _GREP_TERMS_MAX).const GrepTermsMax = 10+// cjkPhraseRunes is the length at which a CJK token stops being a term and+// becomes a clause: see GrepTermsFromQuery. Four is the longest Chinese proper+// name that is still read as one token (成吉思汗), so a longer run is prose.+const cjkPhraseRunes = 4+// GrepOutCharsPerChunk is the grep narrow's per-chunk output cap (Python// _GREP_OUT_CHARS_PER_CHUNK).const GrepOutCharsPerChunk = 700@@ -130,33 +138,239 @@ const GrepOutCharsPerChunk = 700// _GREP_OUT_TOTAL_CHARS).const GrepOutTotalChars = 8000-// GrepTermsFromQuery mirrors Python _grep_terms_from_query:-// extract compact grep terms from a query — bare alnum words of length>=2,-// deduped (order-preserving) and capped. Numbers/ids are preserved as-is.+// GrepTermsFromQuery mirrors Python _grep_terms_from_query — bare alnum words of+// length>=2, deduped (order-preserving) and capped — and extends it to CJK.+//+// The Python original is ALNUM-ONLY, so a Chinese query yields no term at all and+// GrepSearch's own guard (`if not chunks or not terms: return res`) returns whole+// chunks instead of located windows. Measured on a Chinese question: the+// "Keyword-first locate" line was logged, a narrowed line never was, and every+// hit was a ~1200-char chunk. That is expensive (a name lives in one clause of+// those 1200 chars) and it is what made an enumeration unreadable to the model,+// which cannot see WHICH clause a name sits in.+//+// The derivation keeps Python's shape and adds CJK, with no regex:+//+// - an ALTERNATION is the caller's own term list — "颜良|文丑|荀正" is how the+// count protocol tells a session to batch its probes — so it is split on "|"+// and its pieces are kept at any length ("关羽|斩": the predicate is a term);+// - otherwise the query is split on whitespace and punctuation, Latin tokens+// keep Python's two-character floor, and CJK tokens keep a two-CJK-rune+// floor (a lone Chinese character is a particle, not a term);+// - an unbroken CJK clause (a question written without separators) yields no+// token either way, so its two-rune windows are used, left to right: the+// names in the clause still locate, and a window that occurs nowhere costs+// one failed lookup inside the narrowing pass and nothing else.func GrepTermsFromQuery(query string) []string {+ return grepTermsFromQuery(query, true)+}++// probeItemsOf returns the terms a call proposed AS ITEMS — a string the model+// wrote to ask about one individual.+//+// Two shapes qualify: the pieces of a batch (`关羽 斩 华雄 颜良`), and a query that+// IS one word (`韩福`). Everything else is prose the model wrote to ask a+// question, whose words belong to the question rather than to a member list; and+// the two-rune windows an unbroken clause decomposes into are our guesses, not the+// caller's words at all (see GrepWordsFromQuery).+//+// The distinction matters at the reach ledger. The ledger is read back as the+// session's to-do list — "you probed this, it came back with a passage, it is in+// no slot" — and a to-do list built from a question's words tells the model+// nothing. Measured (2026-09-15): that line read `FOUND BUT NOT RECORDED=三国、+// 演义、关羽、五关…+15` in a run whose sessions were missing six members, none of+// which was on it, while the window fragments had cost a retrieval each.+func probeItemsOf(queries []string) map[string]bool {+ out := make(map[string]bool)+ for _, q := range queries {+ q = strings.TrimSpace(q)+ if q == "" {+ continue+ }+ items := GrepWordsFromQuery(q)+ if !callerBatch(q) && len(items) != 1 {+ continue+ }+ for _, it := range items {+ if it = strings.TrimSpace(it); it != "" {+ out[strings.ToLower(it)] = true+ }+ }+ }+ return out+}++// GrepWordsFromQuery is GrepTermsFromQuery restricted to the caller's OWN words:+// the pieces of an alternation, and the tokens separated by whitespace or+// punctuation. It has NO CJK-window fallback.+//+// The distinction matters because the two answers are used for different jobs.+// The windows exist to LOCATE a term inside an unbroken CJK clause — the thing+// grep is for, and a failed lookup there costs nothing. As terms to SEARCH FOR,+// they are our guesses rather than the caller's words, and each one would spend a+// retrieval of its own. Measured (2026-09-15): a pass built from windows probed+// 羽斩 / 杀的 / 的有 / 领名 / 单温 and reported 14 of 20 probes "absent" — fourteen+// retrievals spent on fragments nobody asked about, while every name the question+// was missing stayed out of the list entirely.+//+// So a caller that READS these (the named-term seat pass) uses the words; a+// caller that LOCATES with them uses the terms.+func GrepWordsFromQuery(query string) []string {+ return grepTermsFromQuery(query, false)+}++func grepTermsFromQuery(query string, windows bool) []string {q := strings.TrimSpace(query)if q == "" {return nil}terms := make([]string, 0, GrepTermsMax)seen := make(map[string]struct{}, GrepTermsMax)- re := regexp.MustCompile(`[A-Za-z0-9][A-Za-z0-9_.\-]{1,}`)- for _, m := range re.FindAllString(q, -1) {- t := strings.Trim(m, "._-")- if len(t) < 2 {- continue+ add := func(t string) (full bool) {+ if t == "" {+ return len(terms) >= GrepTermsMax}low := strings.ToLower(t)- if _, ok := seen[low]; ok {- continue+ if _, dup := seen[low]; dup {+ return len(terms) >= GrepTermsMax}seen[low] = struct{}{}terms = append(terms, t)- if len(terms) >= GrepTermsMax {+ return len(terms) >= GrepTermsMax+ }++ if strings.Contains(q, "|") {+ for _, part := range strings.Split(q, "|") {+ if add(trimTermEdges(part)) {+ break+ }+ }+ return terms+ }++ for _, token := range strings.FieldsFunc(q, isTermSeparator) {+ token = trimTermEdges(token)+ if token == "" {+ continue+ }+ if hasCJK(token) {+ runes := utf8.RuneCountInString(token)+ if runes < 2 {+ continue+ }+ // A CJK token past the name boundary is a CLAUSE, not a term: its+ // literal form rarely occurs in the corpus, so it locates nothing.+ // The two jobs part company here:+ //+ // LOCATING (windows) — decompose the clause into the two-rune+ // windows a name can actually be found in;+ // the caller's WORDS (GrepWordsFromQuery) — drop it. A clause names+ // no individual, and its own phrase search already covers it.+ if !windows {+ if runes > cjkPhraseRunes {+ continue+ }+ } else if runes >= cjkPhraseRunes {+ full := len(terms) >= GrepTermsMax+ for _, window := range cjkWindowsOf(token, GrepTermsMax) {+ if add(window) {+ full = true+ break+ }+ }+ if full {+ break+ }+ continue+ }+ } else if len(token) < 2 {+ continue+ }+ if add(token) {break}}- return terms+ if len(terms) > 0 || !windows {+ return terms+ }+ return cjkWindowsOf(q, GrepTermsMax)+}++// trimTermEdges strips the punctuation a token can carry instead of the regex+// Python uses for the same job (reTermEdgePunct).+func trimTermEdges(t string) string {+ return strings.Trim(t, " \t\r\n.,:;!?'\"()[]{}<>“”‘’()【】《》「」〈〉—…·_-")+}++// isTermSeparator reports whether a rune separates terms. "." and "," do;+// "-", "_" and "." INSIDE a Latin token do not (Python keeps+// [A-Za-z0-9_.-] as token material), so they are not listed here.+func isTermSeparator(r rune) bool {+ switch r {+ case ' ', '\t', '\r', '\n', '\v', '\f',+ ',', ';', ':', '!', '?', '/', '\\', '(', ')', '[', ']', '{', '}', '<', '>', '"', '\'', '|',+ ',', '。', '、', ';', ':', '!', '?', '(', ')', '【', '】', '《', '》', '「', '」', '〈', '〉',+ '“', '”', '‘', '’', '—', '…', '·':+ return true+ }+ return false+}++// hasCJK reports whether a token contains a CJK / kana / hangul rune — the same+// classes EscapeTerm refuses to wrap in \b, because no word boundary exists+// between them.+func hasCJK(s string) bool {+ for _, r := range s {+ if isCJKRune(r) {+ return true+ }+ }+ return false+}++// isCJKRune reports whether a rune belongs to a script whose text has no word+// boundaries.+func isCJKRune(r rune) bool {+ return unicode.Is(unicode.Han, r) || unicode.Is(unicode.Hiragana, r) ||+ unicode.Is(unicode.Katakana, r) || unicode.Is(unicode.Hangul, r)+}++// cjkWindowsOf returns the two-rune windows of a string's CJK runs, in order,+// deduped and capped. It is the last-resort term derivation for a query that is+// one unbroken clause (see GrepTermsFromQuery).+func cjkWindowsOf(query string, limit int) []string {+ out := make([]string, 0, limit)+ run := make([]rune, 0, 16)+ flush := func() {+ if len(run) >= 2 {+ for i := 0; i+2 <= len(run) && len(out) < limit; i++ {+ window := string(run[i : i+2])+ dup := false+ for _, o := range out {+ if o == window {+ dup = true+ break+ }+ }+ if !dup {+ out = append(out, window)+ }+ }+ }+ run = run[:0]+ }+ for _, r := range query {+ if isCJKRune(r) {+ run = append(run, r)+ continue+ }+ flush()+ }+ flush()+ if len(out) == 0 {+ return nil+ }+ return out}// lineSpans returns line (start,end) spans, boundaries at "\n" (grep semantics).@@ -253,10 +467,16 @@ func execOnText(content string, patterns []*regexp.Regexp, before, after, outChalo = max(0, lo-before)hi = min(len(lines)-1, hi+after)fragS, fragE := lines[lo][0], lines[hi][1]- // Per-side character budget fallback.- if fragE-fragS > contextCharBudget*2 && (fragE-fragS) > (r[1]-r[0]) {- fragS = max(0, r[0]-contextCharBudget)- fragE = min(len(content), r[1]+contextCharBudget)+ // A line window is unusable when the LINE IS THE WHOLE CHUNK, and that is+ // the CJK case by default: a Chinese chunk carries no newlines, so its+ // one line is the entire passage and the window hands back all of it. The+ // length test catches the same thing for a chunk that does have a few+ // very long lines. Either way, fall back to the SENTENCES the hit sits+ // in — same per-side budget, cut at 。!?; instead of mid-clause.+ if len(lines) <= 1 || (fragE-fragS > contextCharBudget*2 && (fragE-fragS) > (r[1]-r[0])) {+ if window := sentenceWindow(content, r, contextCharBudget); window[1]-window[0] < fragE-fragS {+ fragS, fragE = window[0], window[1]+ }}expanded = append(expanded, [2]int{fragS, fragE})}@@ -286,6 +506,44 @@ func execOnText(content string, patterns []*regexp.Regexp, before, after, outChareturn narrowed, true}+// sentenceWindow expands a hit to the sentence it sits in, bounded by budget+// bytes on each side.+//+// It exists for text with no line structure. A CJK chunk is one long line, so+// the line-window path returns the whole chunk for a hit that needs one clause of+// it; cutting at sentence punctuation instead keeps the window bounded AND keeps+// the clause intact, which is what makes the result readable to the model (a+// name is read off the clause around the verb). Terminators are the sentence+// punctuation of both scripts; no regex is involved.+func sentenceWindow(content string, hit [2]int, budget int) [2]int {+ lo := hit[0]+ for lo > 0 && hit[0]-lo < budget {+ r, size := utf8.DecodeLastRuneInString(content[:lo])+ if isSentenceTerminator(r) {+ break+ }+ lo -= size+ }+ hi := hit[1]+ for hi < len(content) && hi-hit[1] < budget {+ r, size := utf8.DecodeRuneInString(content[hi:])+ hi += size+ if isSentenceTerminator(r) {+ break+ }+ }+ return [2]int{lo, hi}+}++// isSentenceTerminator reports whether a rune ends a sentence in either script.+func isSentenceTerminator(r rune) bool {+ switch r {+ case '。', '!', '?', ';', '\n', '!', '?', ';', '.':+ return true+ }+ return false+}+// NarrowStats carries the accounting Python narrow_by_terms returns in its// "stats" dict.type NarrowStats struct {@@ -304,6 +562,196 @@ type NarrowResult struct {Stats NarrowStats}+// grepPatternSyntax are the constructs that make a query a PATTERN rather than a+// phrase: an alternation, an ordering constraint, or a word boundary.+//+// They are read from the model's own string and mean what they mean in every+// regex dialect there is, so nothing has to be compiled, escaped or translated —+// and none of them occurs in ordinary prose, which is what keeps the guard safe:+// a plain question is not a pattern and takes the term-locate path it always took.+var grepPatternSyntax = []string{"|", ".*", ".+", `\b`}++// grepPatternOf compiles the query as a pattern, or returns nil when the query+// carries no pattern syntax.+func grepPatternOf(query string) *regexp.Regexp {+ q := strings.TrimSpace(query)+ if q == "" {+ return nil+ }+ patterned := false+ for _, tok := range grepPatternSyntax {+ if strings.Contains(q, tok) {+ patterned = true+ break+ }+ }+ if !patterned {+ return nil+ }+ re, err := regexp.Compile("(?i)" + q)+ if err != nil {+ return nil+ }+ return re+}++// grepPatternOperators are the characters a pattern uses as operators. They are+// removed before the operands are derived, because a keyword leg cannot search+// for syntax.+var grepPatternOperators = []string{".*", ".+", "|", ".", "*", "+", "?", "^", "$", `\b`, `\d`, `\w`, `\s`, "(", ")", "[", "]", "{", "}", `\`}++// GrepPatternOperands returns the literal runs a PATTERN asks the corpus for.+//+// A pattern's operands are what a keyword leg can search: "华雄|荀正" names two,+// "关公.*斩" names two, and the operators between them are not terms. They cannot+// go through the phrase path (GrepTermsFromQuery), which reads an unbroken CJK run+// as a clause and decomposes it into windows — on "关公.*斩" that yielded 关公 alone+// and dropped the 斩, so recall never asked about half the pattern.+//+// Single CJK runes are KEPT here, unlike the general two-rune floor: inside a+// pattern the caller wrote that literal deliberately, so it is not the stray+// particle the floor exists to drop.+func GrepPatternOperands(query string) []string {+ q := strings.TrimSpace(query)+ if q == "" {+ return nil+ }+ for _, op := range grepPatternOperators {+ q = strings.ReplaceAll(q, op, " ")+ }+ var out []string+ seen := make(map[string]bool, GrepTermsMax)+ for _, tok := range strings.Fields(q) {+ tok = trimTermEdges(tok)+ if tok == "" {+ continue+ }+ low := strings.ToLower(tok)+ if seen[low] {+ continue+ }+ seen[low] = true+ out = append(out, tok)+ if len(out) >= GrepTermsMax {+ break+ }+ }+ return out+}++// matchGrepPattern is the grep: it runs the PATTERN over candidate content and+// keeps the candidates that MATCH, each narrowed to the clause its match sits in.+//+// This is the half of grep_search that a term-locate pass cannot be: a candidate+// the pattern does not match is not evidence, whatever its retrieval score, and+// the pattern keeps its own semantics — `A|B` accepts either alternative, while+// `A.*B` requires the written order, which is how one asks for the WAY a thing+// was done instead of for its name.+//+// The haystack is the candidate set the keyword leg returned (see+// retrieveGrepCandidates), so the pattern is applied to what the engine could+// reach, exactly: a name the candidates carry is found even if the phrase's+// ranking would have buried it, and no pattern syntax ever reaches the engine —+// which is why `|` and `.*` need no escaping anywhere on this path.+//+// The window is the sentence around the FIRST match, so the model reads the+// clause that carries the term instead of a whole chunk.+//+// Returns the matching candidates plus how many matched; the caller keeps the raw+// candidates when nothing matched, so evidence is never dropped.+func matchGrepPattern(chunks []map[string]any, re *regexp.Regexp, budget, maxOutTotalChars int) ([]map[string]any, int) {+ if re == nil || len(chunks) == 0 {+ return nil, 0+ }+ if budget <= 0 {+ budget = contextCharBudget+ }+ var kept []map[string]any+ used := 0+ for _, c := range chunks {+ text := ChunkTextOf(c)+ if text == "" {+ continue+ }+ span := re.FindStringIndex(text)+ if span == nil {+ continue+ }+ win := sentenceWindow(text, [2]int{span[0], span[1]}, budget)+ fragment := text[win[0]:win[1]]+ if maxOutTotalChars > 0 {+ n := utf8.RuneCountInString(fragment)+ if used+n > maxOutTotalChars && len(kept) > 0 {+ break+ }+ used += n+ }+ kept = append(kept, withNarrowedText(cloneMap(c), fragment))+ }+ return kept, len(kept)+}++// logGrepReach prints what ONE grep reached, term by term, and what nothing+// reached — the fact the model cannot read off the passages themselves.+//+// Every name in a batch looks the same whether the search found it or never+// looked, and the wording matters: "not reached by THIS query" is not "absent+// from the corpus". A model that reads a miss as absence stops enumerating, which+// is the failure this line exists to prevent.+func logGrepReach(logger *log.Logger, query string, candidates []map[string]any, terms []string) {+ if logger == nil {+ return+ }+ if body := reachBody(query, candidates, terms); body != "" {+ logger.Printf("[Grep search] %s", body)+ }+}++// GrepReachLine is reachBody, prefixed for the MODEL.+//+// The reach report was log-only, and that was the last piece of the loop missing:+// a batch of names ("华雄|颜良|蔡阳") came back as passages, every name looking the+// same whether the query reached it or never looked — so the loop could not do+// what a search-driven loop does with it, act on WHICH alternative came back+// empty. The engine, the pattern matcher and the per-term accounting already+// existed; only the reader was missing.+func GrepReachLine(query string, candidates []map[string]any, terms []string) string {+ body := reachBody(query, candidates, terms)+ if body == "" {+ return ""+ }+ return "[reach] " + body+}++// reachBody renders what ONE query reached, term by term, and what nothing+// reached. Empty when there are no terms to report on.+func reachBody(query string, candidates []map[string]any, terms []string) string {+ if len(terms) == 0 {+ return ""+ }+ located, counts, absent := termReach(candidates, terms)+ parts := make([]string, 0, len(located))+ for i, t := range located {+ parts = append(parts, fmt.Sprintf("%s(%d)", t, counts[i]))+ }+ line := fmt.Sprintf("%d candidate(s) for %q carry: %s", len(candidates), trunc(query, 60), strings.Join(parts, " "))+ if len(absent) > 0 {+ line += fmt.Sprintf(" | NOT reached by this query (not necessarily absent from the corpus): %s", strings.Join(absent, " "))+ }+ return line+}++// ReachTermsOf returns the terms a query's reach is reported over: the operands+// for a PATTERN (its operands are what a keyword leg searched for), the extracted+// terms otherwise. It mirrors the choice GrepSearch makes, so the line the model+// reads and the line the log carries describe the same search.+func ReachTermsOf(query string) []string {+ if grepPatternOf(query) != nil {+ return GrepPatternOperands(query)+ }+ return GrepTermsFromQuery(query)+}+// NarrowByTerms narrows retrieval chunks by locating grep terms, mirroring// Python narrow_by_terms://diff --git a/internal/rag/advanced_rag/harness/grep_sed_narrow_test.go b/internal/rag/advanced_rag/harness/grep_sed_narrow_test.gonew file mode 100644index 0000000000..4aae234360--- /dev/null+++ b/internal/rag/advanced_rag/harness/grep_sed_narrow_test.go@@ -0,0 +1,326 @@+//+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.+//++package harness++import (+ "strings"+ "testing"+)++// TestGrepTermsFromQueryCJK pins the derivation a Chinese query needs.+//+// The alnum-only original yields NO term for Chinese, and GrepSearch's own guard+// (`if not chunks or not terms: return res`) then returns whole chunks: measured+// on a Chinese question, the "Keyword-first locate" line was logged, a narrowed+// line never was, and every hit was a ~1200-char chunk.+func TestGrepTermsFromQueryCJK(t *testing.T) {+ // An alternation is the caller's own term list (the count protocol batches its+ // probes as 名|名|名), so it is split as-is — predicates included.+ if got := GrepTermsFromQuery("颜良|文丑|荀正"); !cjkTermsEqual(got, []string{"颜良", "文丑", "荀正"}) {+ t.Errorf("alternation terms = %v, want 颜良 文丑 荀正", got)+ }+ if got := GrepTermsFromQuery("关羽|斩"); !cjkTermsEqual(got, []string{"关羽", "斩"}) {+ t.Errorf("alternation with a one-rune predicate = %v, want 关羽 斩", got)+ }+ if got := GrepTermsFromQuery("关羽|关羽|关羽"); !cjkTermsEqual(got, []string{"关羽"}) {+ t.Errorf("alternation terms = %v, want a single deduped term", got)+ }++ // Space-separated Chinese keeps its tokens; a lone character is a particle.+ if got := GrepTermsFromQuery("关羽 斩颜良 文丑"); !cjkTermsEqual(got, []string{"关羽", "斩颜良", "文丑"}) {+ t.Errorf("split terms = %v", got)+ }+ if got := GrepTermsFromQuery("关羽 斩 文丑"); !cjkTermsEqual(got, []string{"关羽", "文丑"}) {+ t.Errorf("split terms = %v, want the one-rune particle dropped outside an alternation", got)+ }++ // An unbroken clause has no token at all, so its two-rune windows stand in:+ // the names in the clause still locate, and windows that occur nowhere cost+ // one failed lookup inside the narrowing pass.+ got := GrepTermsFromQuery("关羽杀了多少有姓名的人物")+ if len(got) != GrepTermsMax {+ t.Fatalf("clause windows = %v (%d), want %d windows", got, len(got), GrepTermsMax)+ }+ for _, want := range []string{"关羽", "姓名"} {+ if !cjkTermsContain(got, want) {+ t.Errorf("clause windows = %v, want %q among them", got, want)+ }+ }+ for _, term := range got {+ if !hasCJK(term) {+ t.Errorf("clause windows = %v, want CJK only (got %q)", got, term)+ }+ }+ if got := GrepTermsFromQuery(" "); got != nil {+ t.Errorf("blank query = %v, want nil", got)+ }+}++// TestExecOnTextCJKNarrowsToTheSentenceNotTheWholeChunk: a Chinese chunk carries+// no newlines, so its "line" IS the chunk and the line window hands back all of+// it. The window has to be cut at sentence punctuation instead — bounded, and+// with the clause that carries the name intact (that clause is what the model+// reads a name off).+func TestExecOnTextCJKNarrowsToTheSentenceNotTheWholeChunk(t *testing.T) {+ filler := "曹操引军退去诸将皆惊张辽与徐晃双马齐出先射中头盔徐晃败走沿河追赶。"+ content := "前文提到青州兵甲之事与本案无关。" ++ strings.Repeat(filler, 14) ++ "关羽赶上荀正交马一合砍荀正于马下。" ++ strings.Repeat(filler, 3) ++ "后文又叙河北军大半落水之事。"+ if len(content) <= contextCharBudget*2 {+ t.Fatalf("test content is %d bytes; it must exceed the per-side budget to exercise the fallback", len(content))+ }++ got, matched := execOnText(content, TermsToPatterns([]string{"荀正"}), 1, 0, GrepOutCharsPerChunk)+ if !matched {+ t.Fatal("荀正 is in the content, the narrow must match")+ }+ if !strings.Contains(got, "荀正") {+ t.Fatalf("window lost the hit: %q", got)+ }+ if len(got) > GrepOutCharsPerChunk {+ t.Errorf("window = %d bytes, want at most %d", len(got), GrepOutCharsPerChunk)+ }+ if !strings.Contains(got, "砍荀正于马下") {+ t.Errorf("window cut the clause mid-sentence: %q", got)+ }+ if strings.Contains(got, "青州兵甲") {+ t.Errorf("window dragged in the far head of the chunk: %q", got)+ }+}++// TestExecOnTextKeepsLineWindowsWhenThereAreLines: the sentence fallback is for+// text with no line structure. Text that HAS lines keeps grep's line window+// (±1 line), which is the behaviour every Latin question already relies on.+func TestExecOnTextKeepsLineWindowsWhenThereAreLines(t *testing.T) {+ content := "line one about alpha\nline two about beta\nline three about gamma\nline four about delta"+ got, matched := execOnText(content, TermsToPatterns([]string{"beta"}), 1, 0, GrepOutCharsPerChunk)+ if !matched {+ t.Fatal("beta is in the content, the narrow must match")+ }+ if !strings.Contains(got, "line one about alpha") || !strings.Contains(got, "line two about beta") {+ t.Errorf("window = %q, want the hit line and its before-context line", got)+ }+ if strings.Contains(got, "line four about delta") {+ t.Errorf("window = %q, want the after-context line excluded (after=0)", got)+ }+}++// TestNarrowByTermsCJKNarrowsThroughTheRealEntry pins the same behaviour one+// level up, where grep actually calls it.+func TestNarrowByTermsCJKNarrowsThroughTheRealEntry(t *testing.T) {+ text := strings.Repeat("曹操引军退去诸将皆惊。", 12) ++ "关羽赶上荀正交马一合砍荀正于马下。" ++ strings.Repeat("河北军大半落水。", 12)+ chunks := []map[string]any{{"id": "c1", "content_with_weight": text}}++ res := NarrowByTerms(chunks, []string{"荀正"}, nil, "", NarrowContext{Before: 1, After: 0},+ GrepOutCharsPerChunk, GrepOutTotalChars)++ if !res.Stats.Matched {+ t.Fatalf("stats = %+v, want a match", res.Stats)+ }+ if len(res.Kept) != 1 {+ t.Fatalf("kept = %d chunk(s), want 1", len(res.Kept))+ }+ kept := ChunkTextOf(res.Kept[0])+ if !strings.Contains(kept, "荀正") {+ t.Errorf("kept passage lost the hit: %q", kept)+ }+ if len(kept) >= len(text) {+ t.Errorf("kept %d bytes of %d: the passage was not narrowed at all", len(kept), len(text))+ }+}++// cjkTermsEqual / cjkTermsContain are local helpers: this file needs exact-order+// and membership checks over the derived terms.+func cjkTermsEqual(got, want []string) bool {+ if len(got) != len(want) {+ return false+ }+ for i := range want {+ if got[i] != want[i] {+ return false+ }+ }+ return true+}++func cjkTermsContain(list []string, want string) bool {+ for _, s := range list {+ if s == want {+ return true+ }+ }+ return false+}++// TestGrepWordsAreTheCallersOwnWords pins the split between the two readings of+// one query: the terms LOCATE (and may decompose an unbroken clause into CJK+// windows), while the words are what the caller actually wrote — the only ones a+// seat probe may spend a retrieval on.+//+// Measured (2026-09-15): a seat pass built from the locate reading probed 羽斩 /+// 杀的 / 的有 / 领名 / 单温, reported 14 of 20 probes "absent", and never reached a+// single name the question was missing.+func TestGrepWordsAreTheCallersOwnWords(t *testing.T) {+ // A caller-enumerated list is words in both readings — minus the single-rune+ // particles ("斩" is a predicate, not something to probe as a name; the phrase+ // search carries it).+ listed := "关羽 斩 颜良 文丑 车胄"+ if got := GrepWordsFromQuery(listed); strings.Join(got, "|") != "关羽|颜良|文丑|车胄" {+ t.Errorf("GrepWordsFromQuery(%q) = %v, want the caller's own words (single-rune tokens are particles)", listed, got)+ }++ // An unbroken clause names no individual: the locate reading decomposes it+ // into windows, the words reading yields nothing to probe.+ clause := "关羽斩杀敌将名单温酒斩华雄"+ if got := GrepWordsFromQuery(clause); len(got) != 0 {+ t.Errorf("GrepWordsFromQuery(%q) = %v, want none: a clause is not a word to probe", clause, got)+ }+ terms := GrepTermsFromQuery(clause)+ if len(terms) == 0 {+ t.Fatalf("GrepTermsFromQuery(%q) = none, want the two-rune windows grep locates with", clause)+ }+ for _, term := range terms {+ if term == clause {+ t.Errorf("GrepTermsFromQuery(%q) returned the whole clause; the point of the windows is that the clause itself locates nothing", clause)+ }+ }++ // The name boundary is the one this file already declares (cjkPhraseRunes):+ // up to four runes is still a name, past it is prose.+ for _, name := range []string{"孔秀", "夏侯存", "成吉思汗"} {+ if got := GrepWordsFromQuery(name); len(got) != 1 || got[0] != name {+ t.Errorf("GrepWordsFromQuery(%q) = %v, want the name itself", name, got)+ }+ }+ if got := GrepWordsFromQuery("成吉思汗东征"); len(got) != 0 {+ t.Errorf("GrepWordsFromQuery = %v, want none: past the name boundary a CJK token is prose", got)+ }+}++// TestGrepPatternIsAMatchNotATermFilter pins the grep half of grep_search: the+// pattern decides which candidates are evidence, and it keeps its own semantics+// instead of being degraded into "does the text carry one of these words".+//+// The ordering case is the one a term-locate pass can never express: both chunks+// carry 关公 and 斩, and only the written order distinguishes the clause that says+// he killed from the one that says he killed and then went back to camp.+func TestGrepPatternIsAMatchNotATermFilter(t *testing.T) {+ chunks := []map[string]any{+ {"chunk_id": "a", "content": "关公马快,早赶上文丑,脑后一刀,斩于马下。"},+ {"chunk_id": "b", "content": "斩将之后,关公回营,众将皆来称贺。"},+ {"chunk_id": "c", "content": "话说曹操引军而回,不在话下。"},+ {"chunk_id": "d", "content": "荀正 引军来战,被云长一刀斩于马下。"},+ }+ re := grepPatternOf("关公.*斩")+ if re == nil {+ t.Fatal("关公.*斩 carries pattern syntax and must be read as a pattern")+ }+ kept, matched := matchGrepPattern(chunks, re, contextCharBudget, GrepOutTotalChars)+ if matched != 1 || len(kept) != 1 {+ t.Fatalf("matched=%d kept=%d, want exactly the chunk whose text has 关公 BEFORE 斩", matched, len(kept))+ }+ if id := ChunkIDOf(kept[0]); id != "a" {+ t.Errorf("kept %q, want \"a\": the pattern's ORDER must be enforced, not just its words", id)+ }+ // The window is the clause around the match, not the whole chunk.+ if txt := ChunkTextOf(kept[0]); !strings.Contains(txt, "斩") {+ t.Errorf("window %q does not carry the match", txt)+ }++ // An alternation is a batch: it matches each alternative and reports per-term+ // reach over the same candidate set, which is how "which of these did the+ // corpus answer" becomes readable.+ alt := grepPatternOf("华雄|荀正|管亥")+ if alt == nil {+ t.Fatal("华雄|荀正|管亥 must be a pattern")+ }+ keptAlt, matchedAlt := matchGrepPattern(chunks, alt, contextCharBudget, GrepOutTotalChars)+ if matchedAlt != 1 || len(keptAlt) != 1 {+ t.Fatalf("alternation matched=%d kept=%d, want the one candidate carrying one of the three names", matchedAlt, len(keptAlt))+ }+ if id := ChunkIDOf(keptAlt[0]); id != "d" {+ t.Errorf("kept %q, want \"d\" (the only candidate carrying 荀正)", id)+ }+ located, counts, absent := termReach(chunks, []string{"华雄", "荀正", "管亥"})+ if strings.Join(located, ",") != "荀正" || counts[0] != 1 {+ t.Errorf("termReach located=%v counts=%v, want only 荀正 reached once", located, counts)+ }+ if strings.Join(absent, ",") != "华雄,管亥" {+ t.Errorf("absent=%v, want 华雄 and 管亥 reported as NOT reached by this query", absent)+ }+}++// TestPlainQueryStaysOnTheTermLocatePath guards the other direction: pattern+// syntax is the ONLY trigger, so every ordinary question keeps the behaviour it+// had (locate terms -> windows), and nothing about it changes.+func TestPlainQueryStaysOnTheTermLocatePath(t *testing.T) {+ for _, q := range []string{+ "关羽 斩颜良",+ "三国演义中关羽杀了多少有姓名的人物",+ "华为2023年营收",+ "partner of the 1984 Olympic keelboat competitor",+ } {+ if re := grepPatternOf(q); re != nil {+ t.Errorf("grepPatternOf(%q) compiled a pattern; a plain query must take the term-locate path", q)+ }+ }+}++// TestReachLineNamesWhatTheBatchMissed pins the line the MODEL reads: a batch of+// names comes back with per-term reach, so a member that was never reached is+// visible as such instead of looking exactly like a member nobody asked about.+//+// The capability was already there (the pattern engine, the per-term accounting,+// the log line); what was missing is that only the LOG could read it.+func TestReachLineNamesWhatTheBatchMissed(t *testing.T) {+ chunks := []map[string]any{+ {"chunk_id": "c1", "content": "云长手起一刀,斩华雄于马下"},+ {"chunk_id": "c2", "content": "华雄又斩了潘凤"},+ }+ q := "华雄|荀正|管亥"+ line := GrepReachLine(q, chunks, ReachTermsOf(q))+ for _, want := range []string{"[reach]", "华雄(2)", "NOT reached by this query"} {+ if !strings.Contains(line, want) {+ t.Errorf("line %q missing %q", line, want)+ }+ }+ // Both unanswered names are named, and the wording refuses to call them absent.+ for _, missed := range []string{"荀正", "管亥"} {+ if !strings.Contains(line, missed) {+ t.Errorf("line %q must name %q as not reached", line, missed)+ }+ }++ // A PATTERN reports on its OPERANDS: they are what the keyword leg searched+ // for, so "关公.*斩" is reported as 关公 and 斩, not as one clause.+ pq := "关公.*斩|云长.*斩"+ pline := GrepReachLine(pq, []map[string]any{{"chunk_id": "c3", "content": "关公勒马,一刀斩之"}}, ReachTermsOf(pq))+ for _, want := range []string{"关公(1)", "云长"} {+ if !strings.Contains(pline, want) {+ t.Errorf("pattern line %q missing %q", pline, want)+ }+ }++ // No terms -> no line at all (never an empty "[reach]" heading).+ if got := GrepReachLine("", chunks, nil); got != "" {+ t.Errorf("empty reach = %q, want no line", got)+ }+}diff --git a/internal/rag/advanced_rag/harness/kbinfos.go b/internal/rag/advanced_rag/harness/kbinfos.goindex 28e747f17c..f6bd1b4e86 100644--- a/internal/rag/advanced_rag/harness/kbinfos.go+++ b/internal/rag/advanced_rag/harness/kbinfos.go@@ -62,6 +62,16 @@ type SearchParams struct {DocScope []string// TopN is the result count. <= 0 selects the configured default.TopN int+ // SkipReachLedger keeps this search's terms OUT of the reach ledger.+ //+ // The ledger is the record's "names you proved reachable and never recorded"+ // list, and it is read as a to-do list, so what enters it must be a NAME the+ // caller probed. The runtime's completeness pass queries ask for the actor and+ // the act words (see RunCompletenessPass), which are not names and are searched+ // by construction: measured (2026-09-16, 三国/关羽) the record read+ // `FOUND BUT NOT RECORDED=斩颜良、诛文丑、三国演义、关羽…+14` — every entry a query+ // word, and not one of the members the round was actually missing.+ SkipReachLedger bool// Channel is retained for backward compatibility with callers that still// poke the unified HybridSearch with an explicit channel. It is DEPRECATED:// each Python entry point is now its own function (HybridSearch /@@ -89,6 +99,19 @@ type Kbinfos struct {mu sync.MutexChunks []map[string]anyDocAggs []map[string]any+ // ledgerMu guards the run's SEARCH RECORD (ProbedAbsent / Reached).+ //+ // It is deliberately NOT mu. The pool lock is held across admit batches, and+ // whoever holds it is free to write down what the batch asked and answered —+ // which is exactly what a seat does. Sharing one mutex made that a+ // self-deadlock: Go mutexes are not reentrant, so a record written inside an+ // admit batch parked the goroutine forever on a lock it already held, and the+ // wait ignores context cancellation, so the run never returned.+ //+ // Lock ORDER, when both are needed: mu first, then ledgerMu — never the other+ // way round. Nothing takes mu while holding ledgerMu, and the record methods+ // that run inside an admit batch (see Admit) are the only place the two nest.+ ledgerMu sync.Mutex// Memory is the lossless store of raw retrieved chunks backing the (lossy)// Chunks list that feeds the LLM. Mirrors Python kbinfos["memory"], which// memory.add/grep maintain.@@ -96,6 +119,40 @@ type Kbinfos struct {// PreSummary is the merged claim-report summary produced by the action// session; the final-answer call reads it when set.PreSummary string+ // Record is the slot table rendered for the ANSWER prompt — the facts the+ // research settled, without the machine fields (strength, terminal type,+ // evidence ids) that belong to the SCA's draft.+ //+ // The two are separate on purpose. A draft is written to be VERIFIED against+ // the passages that produced it; the answer prompt is written to be ANSWERED+ // from. Reusing one as the other handed the answer model the runtime's+ // bookkeeping, and the measured result was an answer quoting it verbatim+ // ("slot 1 [entity] … (strength=0.90) [terminal=state, evidence_ids=[…]]").+ Record string+ // novelAdmitted counts the chunks the cap EXEMPTION below has let in beyond+ // evidencePoolCap. It is what keeps the exemption bounded rather than+ // open-ended (see evidencePoolNoveltySlack). Guarded by mu, like Chunks.+ novelAdmitted int+ // ProbedAbsent is the run's record of NAMED terms a probe asked about and+ // nothing reached (see RecordProbedAbsent). The pool holds what was found;+ // this holds what was asked and not found, and the pair is what a rewrite+ // reads before choosing its next angle. Guarded by ledgerMu.+ ProbedAbsent []string+ // Reached is the run's record of NAMED terms a probe asked about and DID+ // reach, each with the pool chunk that carries it (see RecordReachedTerm):+ // the confirmed members, with their evidence. Guarded by ledgerMu.+ Reached []ReachedTerm+ // setDirection records that this run carries a SET/COUNT direction — a+ // question whose answer is a list of members (see MarkSetDirection, which+ // also says why the retrieval executor reads it). Guarded by ledgerMu.+ setDirection bool+ // patternFindings is the completeness pass's block for this QUESTION, and+ // patternPassed records that it ran (see StorePatternFindings): the windows the+ // pass admits stay in the pool, so a later round reuses the block rather than+ // asking the same corpus the same questions and putting back what is already+ // there. Guarded by ledgerMu.+ patternFindings string+ patternPassed bool// cache is the per-request retrieval cache (Python tools.search_cache). It// is initialised lazily via cacheOnce so a zero-value Kbinfos is usable.cache *searchCache@@ -105,6 +162,59 @@ type Kbinfos struct {// HasChunks mirrors Python `bool(kbinfos.get("chunks"))`.func (k *Kbinfos) HasChunks() bool { return len(k.Chunks) > 0 }+// PoolSize is how many chunks the shared pool holds.+//+// It takes the pool lock, so it must NOT be called from inside an Admit callback+// (that mutex is not reentrant — see Admit's invariant); the record rendering runs+// after the batch for exactly that reason.+func (k *Kbinfos) PoolSize() int {+ if k == nil {+ return 0+ }+ k.mu.Lock()+ defer k.mu.Unlock()+ return len(k.Chunks)+}++// ChunksFrom returns up to limit chunks starting at from, as a copy of the slice+// header.+//+// It exists so a READER can walk the pool the round has already paid for without+// holding the pool lock (chunks are only ever appended, never rewritten in place,+// so the header it copies is stable). The maps themselves stay shared and must be+// read only. Readers are also why this is a copy of the header and not the pool:+// the pool keeps growing under them while they scan.+// ChunkByID returns the pool chunk carrying this id, or nil.+//+// It takes the pool lock, so it must NOT be called from inside an Admit callback+// (that mutex is not reentrant — see Admit's invariant).+func (k *Kbinfos) ChunkByID(id string) map[string]any {+ if k == nil || id == "" {+ return nil+ }+ k.mu.Lock()+ defer k.mu.Unlock()+ for _, c := range k.Chunks {+ if ChunkIDOf(c) == id {+ return c+ }+ }+ return nil+}++func (k *Kbinfos) ChunksFrom(from, limit int) []map[string]any {+ if k == nil || limit <= 0 {+ return nil+ }+ k.mu.Lock()+ defer k.mu.Unlock()+ if from < 0 || from >= len(k.Chunks) {+ return nil+ }+ end := min(from+limit, len(k.Chunks))+ return append([]map[string]any(nil), k.Chunks[from:end]...)+}+// Admit runs fn as ONE critical section over the evidence pool.//// The granularity is the caller's, and it must span the stretch Python leaves@@ -122,6 +232,18 @@ func (k *Kbinfos) HasChunks() bool { return len(k.Chunks) > 0 }// retried once room frees.// then the call-local dedup (`seen`) and payload/ids bookkeeping;// p.Add(c) → dedup against the live pool and append.+//+// INVARIANT — fn must not call anything that takes k.mu itself (Admit, Merge,+// MergeDocAggs, RetireClaimsCoveredBy, PoolAdmitter.Full's siblings…): the mutex+// is NOT reentrant, so that call parks the goroutine forever on a lock it already+// holds, and a mutex wait ignores context cancellation, so the run never returns+// and nothing is logged. Measured (fixrecall2, 2026-09-15): a seat recorded its+// member from inside the admit batch and the run hung with no I/O, no CPU and no+// further log line.+//+// What fn MAY call is the search record (RecordReachedTerm / RecordProbedAbsent):+// those live behind ledgerMu, precisely so the batch that answered a probe can+// write the answer down while the pool is still held.func (k *Kbinfos) Admit(fn func(p *PoolAdmitter)) {if k == nil {// No pool bound: the callback still runs — a tool hands its passages back@@ -162,6 +284,328 @@ func (p *PoolAdmitter) Full() bool {// shrinks mid-process, so no reset is needed.var evidencePoolFullLogged sync.Once+// evidencePoolNoveltySlack bounds the cap EXEMPTION: the pool may pass+// evidencePoolCap by at most this many chunks, and not one more.+//+// The cap is a STORAGE number, and it is the right number for evidence a later+// search could find again. A PROBE's result is not that kind of evidence: a+// batch probe ("荀正|管亥|车胄") is the model's question "does each of these exist,+// and where?", and the per-name window it returns is the only place that answer+// ever lives — no later search can reconstruct WHICH names came back empty.+//+// Measured (fixrecall, 2026-09-14): a seven-name probe returned ten chunks+// carrying 庞德 / 成何 / 于禁 and NOT ONE carrying 车胄 / 荀正 / 管亥 / 杨龄 — four+// members the corpus does hold; and on the cap itself, "a round of batch name+// probing ended at 117 chunks, three short of the cap, with the question's+// members still arriving". A cap that drops those windows converts a successful+// probe into "nothing new", which the model then reads as "not a member".+//+// The slack is what keeps the exemption from being open-ended: it is charged per+// exempted chunk, and beyond cap+slack even a novel term is refused.+const evidencePoolNoveltySlack = 40++// Novelty is the cap exemption for ONE admit batch: the batch's own terms that+// the LIVE pool cannot answer yet.+//+// Build it once per batch (like ClaimCoveredIDs), then ask it per candidate:+// a candidate that carries one of the absent terms may enter an ALREADY-FULL+// pool, and that term is then consumed — one seat per term, so the pool grows by+// at most one chunk per unanswered probe term. A batch with no terms (or a+// batch whose terms the pool already carries) gets no exemption at all, which is+// exactly the pre-existing cap behaviour.+type Novelty struct {+ p *PoolAdmitter+ absent []string+}++// Novelty derives the batch's exemption from the terms the call asked for.+//+// Callers pass the terms of a PROBE (the model's own alternation, see+// probeTerms in tool_executor.go) and nothing else: a topic query states no+// list of individuals, so its hits get no exemption and the cap behaves as it+// always did.+//+// The pool-wide scan happens ONCE here, over lowered pool text, rather than once+// per candidate.+func (p *PoolAdmitter) Novelty(terms []string) *Novelty {+ n := &Novelty{p: p}+ if p.k == nil {+ return n+ }+ asked := make([]string, 0, len(terms))+ for _, t := range terms {+ if t = strings.TrimSpace(t); t == "" || len(asked) >= GrepTermsMax {+ continue+ }+ asked = append(asked, t)+ }+ n.absent = termsNotCarried(p.k.Chunks, asked)+ return n+}++// ProbedAbsentTerms returns a copy of the named terms nothing reached, in the+// order they were first probed.+func (k *Kbinfos) ProbedAbsentTerms() []string {+ if k == nil {+ return nil+ }+ k.ledgerMu.Lock()+ defer k.ledgerMu.Unlock()+ return append([]string(nil), k.ProbedAbsent...)+}++// ReachedTerm is one confirmed member: the term a probe asked about, and the pool+// chunk that carries it.+type ReachedTerm struct {+ Term string+ ChunkID string+}++// RecordReachedTerm notes a named term that a probe asked about AND came back+// with, together with the pool chunk that carries it.+//+// It is the mirror of RecordProbedAbsent, and the two together are the run's+// record of its own search: this one is the CONFIRMED MEMBERS, each with the+// passage that proves it. Two things read it:+//+// - the rewrite context, which shows the rewriter the passage behind each+// confirmed member — the wording this text uses for the relation is in those+// passages, and so are the names that are still missing;+// - the loop, which can then ask whether the LIST is still growing rather than+// whether the pool got bigger (a pool that grew by forty passages of the same+// famous scene has learned nothing about the list).+func (k *Kbinfos) RecordReachedTerm(term, chunkID string) {+ term = strings.TrimSpace(term)+ if k == nil || term == "" || chunkID == "" {+ return+ }+ k.ledgerMu.Lock()+ defer k.ledgerMu.Unlock()+ for _, seen := range k.Reached {+ if strings.EqualFold(seen.Term, term) {+ return+ }+ }+ if len(k.Reached) >= reachedTermsMax {+ return+ }+ k.Reached = append(k.Reached, ReachedTerm{Term: term, ChunkID: chunkID})+}++// MarkSetDirection records that this run carries a SET/COUNT direction.+//+// It is set by the SAME gate that hands the model the set method — the declared+// shape of the direction's table, or the first batch the caller writes, whichever+// comes first — and read by the retrieval executor, which bounds how many of the+// caller's queries run per call:+//+// on a direction whose answer is a LIST, the caller's queries are facets of that+// list rather than rephrasings of one question, so a query that is dropped is not+// a spared repeat — it is a member nobody searched. Measured (2026-09-16): a+// medium-mode run asked 3-5 queries per call against a cap of 2 (search_chunks) /+// 3 (retrieve); nine calls were cut, and the names it later turned out to be+// missing had been named only in the dropped ones. On a VALUE direction the+// queries ARE rephrasings of one question and the small cap stays.+func (k *Kbinfos) MarkSetDirection() {+ if k == nil {+ return+ }+ k.ledgerMu.Lock()+ k.setDirection = true+ k.ledgerMu.Unlock()+}++// IsSetDirection reports whether a SET/COUNT direction has declared itself on this+// run (see MarkSetDirection). Safe on a nil pool: a run with no pool is not one.+func (k *Kbinfos) IsSetDirection() bool {+ if k == nil {+ return false+ }+ k.ledgerMu.Lock()+ defer k.ledgerMu.Unlock()+ return k.setDirection+}++// StorePatternFindings records the completeness pass's block for this question (see+// RunCompletenessPass / PatternFindings).+func (k *Kbinfos) StorePatternFindings(block string) {+ if k == nil {+ return+ }+ k.ledgerMu.Lock()+ k.patternFindings = block+ k.patternPassed = true+ k.ledgerMu.Unlock()+}++// PatternFindings returns the block a previous round's completeness pass produced, and+// whether the pass has run at all.+//+// The unit is the REQUEST, not the round: the windows the pass admitted are in the pool+// under the same chunk ids, so a second round asking the same corpus the same questions+// would spend the same store legs to re-admit what is already there, and the seed would+// show the same windows it already showed (see StorePatternFindings).+func (k *Kbinfos) PatternFindings() (string, bool) {+ if k == nil {+ return "", false+ }+ k.ledgerMu.Lock()+ defer k.ledgerMu.Unlock()+ return k.patternFindings, k.patternPassed+}++// ReachedTerms returns a copy of the confirmed members and the chunk that carries+// each.+func (k *Kbinfos) ReachedTerms() []ReachedTerm {+ if k == nil {+ return nil+ }+ k.ledgerMu.Lock()+ defer k.ledgerMu.Unlock()+ return append([]ReachedTerm(nil), k.Reached...)+}++// reachedTermsMax bounds the confirmed-member ledger (see RecordReachedTerm):+// it is rendered into the rewrite context, so it may not grow with the number of+// probes a long round happens to make.+const reachedTermsMax = 24++// EvidencePoolCap is the shared pool's ceiling. It is exported so that a caller+// sizing the room for its own admissions (the rewrite round's prefetch) measures+// it against the SAME number the admitter enforces.+//+// Measuring against a smaller constant is how a round came to report "retrieval+// saturated" while the pool still had room to take evidence: the prefetch's room+// was computed against the snippet-pool ceiling (60) while the pool itself holds+// up to twice that, so on any rich round the rewrite's own queries had nowhere to+// land and the round discarded itself.+func EvidencePoolCap() int { return evidencePoolCap }++// termsNotCarried reports which of terms no chunk's text carries+// (case-insensitively), preserving the caller's order.+//+// It is the coverage half of every "did we find that name?" question in the+// harness, and it has exactly two callers because there are exactly two sets it+// can be asked about:+//+// - a SEARCH's own results — which of the terms this call named did this+// retrieval not reach? (the seat pass in tool_executor.go, which then buys+// each unreached term its own search), and+// - the POOL — which named terms can the pool not answer at all? (Novelty,+// which exempts those passages from the cap).+func termsNotCarried(chunks []map[string]any, terms []string) []string {+ _, _, absent := termReach(chunks, terms)+ return absent+}++// termReach answers, per term, HOW MANY chunks carry it — the reach of one+// retrieval, term by term.+//+// It is the fact a caller cannot read off a result set: every name in a batch+// looks the same whether the search found it or never looked, and the wording+// matters, because "not reached by THIS query" is not "absent from the corpus".+// A model that reads a miss as absence stops enumerating.+//+// located/counts are parallel and in the caller's term order; absent holds the+// terms no chunk carried.+func termReach(chunks []map[string]any, terms []string) (located []string, counts []int, absent []string) {+ if len(terms) == 0 {+ return nil, nil, nil+ }+ texts := make([]string, 0, len(chunks))+ for _, c := range chunks {+ if text := strings.ToLower(ChunkTextOf(c)); text != "" {+ texts = append(texts, text)+ }+ }+ for _, term := range terms {+ low := strings.ToLower(strings.TrimSpace(term))+ if low == "" {+ continue+ }+ n := 0+ for _, text := range texts {+ if strings.Contains(text, low) {+ n+++ }+ }+ if n == 0 {+ absent = append(absent, term)+ continue+ }+ located = append(located, term)+ counts = append(counts, n)+ }+ return located, counts, absent+}++// RecordProbedAbsent notes a named term that a probe asked about and nothing+// reached, deduped, under the pool lock.+//+// The pool holds what was FOUND; ProbedAbsent holds what was ASKED and not+// found. Together they are the round's record of its own search, which is the+// fact a rewrite needs: re-asking a name the corpus already came back empty on+// is the loop's most common waste, and "these came back empty" is also what+// tells the model to change the ANGLE (ask for the act instead of the name)+// rather than to ask the same thing louder.+func (k *Kbinfos) RecordProbedAbsent(term string) {+ term = strings.TrimSpace(term)+ if k == nil || term == "" {+ return+ }+ k.ledgerMu.Lock()+ defer k.ledgerMu.Unlock()+ for _, seen := range k.ProbedAbsent {+ if strings.EqualFold(seen, term) {+ return+ }+ }+ if len(k.ProbedAbsent) >= probedAbsentMax {+ // Bounded storage: the record is carried into the rewrite context, so it+ // may not grow with the number of probes a long round happens to make.+ return+ }+ k.ProbedAbsent = append(k.ProbedAbsent, term)+}++// probedAbsentMax bounds ProbedAbsent (see RecordProbedAbsent).+const probedAbsentMax = 16++// Admits reports whether c may enter the pool although the pool is FULL, because+// c is the first evidence for one of the batch's unanswered terms.+//+// It answers only the novelty half of the admit decision: the caller still+// checks Full() first, so a pool under the cap never consults this and behaves+// as before. A nil Novelty (or one built from no terms) admits nothing.+func (n *Novelty) Admits(c map[string]any) bool {+ if n == nil || n.p == nil || n.p.k == nil || len(n.absent) == 0 {+ return false+ }+ // The exemption is bounded: past cap+slack the probe's windows are refused+ // like everything else, so a runaway enumeration cannot grow storage without+ // limit.+ if len(n.p.k.Chunks) >= evidencePoolCap+evidencePoolNoveltySlack {+ return false+ }+ text := strings.ToLower(ChunkTextOf(c))+ if text == "" {+ return false+ }+ for i, t := range n.absent {+ if !strings.Contains(text, strings.ToLower(t)) {+ continue+ }+ // ONE seat per term: this passage answers it, so the next passage+ // carrying only that term is refused again.+ n.absent = append(n.absent[:i], n.absent[i+1:]...)+ n.p.k.novelAdmitted+++ _LOG.Printf("[Action Session] pool at the cap %d but the batch asked about %q; admitting the passage that reaches it (pool %d, novelty slack %d/%d).",+ evidencePoolCap, t, len(n.p.k.Chunks)+1, n.p.k.novelAdmitted, evidencePoolNoveltySlack)+ return true+ }+ return false+}+// Add appends c unless the LIVE pool already holds it, reporting whether it// appended — Python's "new to the shared pool" return.//diff --git a/internal/rag/advanced_rag/harness/kbinfos_test.go b/internal/rag/advanced_rag/harness/kbinfos_test.goindex 2ad44d9b70..ceaf514609 100644--- a/internal/rag/advanced_rag/harness/kbinfos_test.go+++ b/internal/rag/advanced_rag/harness/kbinfos_test.go@@ -4,6 +4,7 @@ import ("fmt""sync""testing"+ "time")// TestMergeSkipsAllWhenNoChunks mirrors Python _merge_kbinfos's early return:@@ -201,3 +202,185 @@ func TestToolCacheIsConcurrencySafe(t *testing.T) {}}}++// TestPoolNoveltyExemptsOnlyTheUnansweredProbeTerms pins the cap EXEMPTION: a+// FULL pool still takes the passage that answers a probe term nothing in the pool+// has reached yet — one seat per term — and refuses everything else exactly as the+// cap always did.+//+// The reason the exemption exists is that a probe's per-name window is the batch's+// RESULT rather than one more passage: drop it and "this name was found here"+// degrades into "nothing new", which the model reads as "not a member".+func TestPoolNoveltyExemptsOnlyTheUnansweredProbeTerms(t *testing.T) {+ newFullPool := func() *Kbinfos {+ pool := &Kbinfos{}+ for i := 0; i < evidencePoolCap; i++ {+ pool.Admit(func(p *PoolAdmitter) {+ p.Add(map[string]any{"chunk_id": fmt.Sprintf("p%d", i), "content": "already pooled prose"})+ })+ }+ return pool+ }+ admit := func(pool *Kbinfos, q string, chunks ...map[string]any) (admitted int) {+ pool.Admit(func(p *PoolAdmitter) {+ novel := p.Novelty(probeTerms(q))+ for _, c := range chunks {+ if p.Full() && !novel.Admits(c) {+ continue+ }+ if p.Add(c) {+ admitted+++ }+ }+ })+ return admitted+ }++ // A probe whose name the pool cannot answer: the window is admitted.+ pool := newFullPool()+ window := map[string]any{"chunk_id": "w1", "content": "荀正 被关公一刀斩于马下"}+ if got := admit(pool, "车胄|荀正|管亥", window); got != 1 {+ t.Fatalf("admitted = %d, want 1 (the pool cannot answer 荀正)", got)+ }+ if len(pool.Chunks) != evidencePoolCap+1 {+ t.Fatalf("pool = %d, want %d (one seat for one unanswered term)", len(pool.Chunks), evidencePoolCap+1)+ }+ // The same term is answered now: a second window carrying only it is refused,+ // so one term buys one seat and not a batch of them.+ if got := admit(pool, "车胄|荀正|管亥", map[string]any{"chunk_id": "w2", "content": "荀正 又出现了一次"}); got != 0 {+ t.Fatalf("admitted = %d, want 0: 荀正 is answered now", got)+ }+ // A query that is not a PROBE states no list of individuals, so it gets no+ // exemption at all — the plain cap behaviour.+ if got := admit(pool, "车胄", map[string]any{"chunk_id": "w3", "content": "车胄 守徐州"}); got != 0 {+ t.Fatalf("admitted = %d, want 0: a non-probe query gets no exemption", got)+ }+ if got := admit(pool, "车胄|管亥", map[string]any{"chunk_id": "w4", "content": "管亥 围北海"}); got != 1 {+ t.Fatalf("admitted = %d, want 1 (管亥 is still unanswered)", got)+ }+ // A pool that already carries the term leaves the cap in charge.+ carried := newFullPool()+ carried.Admit(func(p *PoolAdmitter) { p.Add(map[string]any{"chunk_id": "seed", "content": "管亥 围北海"}) })+ if got := admit(carried, "管亥", map[string]any{"chunk_id": "w5", "content": "管亥 围北海 续"}); got != 0 {+ t.Fatalf("admitted = %d, want 0: the pool already carries 管亥", got)+ }+ _ = carried++ // The exemption is BOUNDED: past cap+slack even an unanswered term is refused.+ bounded := newFullPool()+ bounded.novelAdmitted = evidencePoolNoveltySlack+ bounded.Chunks = append(bounded.Chunks, make([]map[string]any, evidencePoolNoveltySlack)...)+ if got := admit(bounded, "杨龄", map[string]any{"chunk_id": "w6", "content": "杨龄 出战"}); got != 0 {+ t.Fatalf("admitted = %d, want 0: the novelty slack is exhausted", got)+ }+}++// TestReachedTermsLedgerHoldsTheMembersWithTheirEvidence pins the confirmed-member+// ledger: it is what the rewrite context renders (the passage behind each name) and+// what lets the loop ask whether the LIST is growing rather than whether the pool+// got bigger.+func TestReachedTermsLedgerHoldsTheMembersWithTheirEvidence(t *testing.T) {+ pool := &Kbinfos{}+ pool.RecordReachedTerm("荀正", "w1")+ pool.RecordReachedTerm("杨龄", "w2")+ pool.RecordReachedTerm("荀正", "w3") // same name, later passage: must not duplicate++ got := pool.ReachedTerms()+ if len(got) != 2 {+ t.Fatalf("ReachedTerms = %v, want one entry per name", got)+ }+ if got[0].Term != "荀正" || got[0].ChunkID != "w1" {+ t.Errorf("first entry = %+v, want the name with the passage that proved it", got[0])+ }+ if got[1].Term != "杨龄" || got[1].ChunkID != "w2" {+ t.Errorf("second entry = %+v", got[1])+ }+ // Blank input records nothing (a seat without an id is not evidence).+ pool.RecordReachedTerm("", "w4")+ pool.RecordReachedTerm("管亥", "")+ if n := len(pool.ReachedTerms()); n != 2 {+ t.Errorf("entries = %d, want 2: an entry needs both a name and its passage", n)+ }+ // The ledger is bounded, and a nil pool is safe (the graph may run without one).+ for i := 0; i < reachedTermsMax+5; i++ {+ pool.RecordReachedTerm(fmt.Sprintf("n%d", i), fmt.Sprintf("c%d", i))+ }+ if n := len(pool.ReachedTerms()); n != reachedTermsMax {+ t.Errorf("entries = %d, want the cap %d", n, reachedTermsMax)+ }+ var nilPool *Kbinfos+ nilPool.RecordReachedTerm("x", "y")+ if len(nilPool.ReachedTerms()) != 0 {+ t.Error("a nil pool must record nothing")+ }+}++// TestRecordingInsideTheAdmitBatchDoesNotDeadlock pins the hardened ledger: the+// search record lives behind its OWN mutex, so a batch that answered a probe can+// write the answer down while the pool lock is held.+//+// This is the exact shape that hung a run (fixrecall2, 2026-09-15): the recorder+// used to take the same mutex Admit holds, and because Go mutexes are not+// reentrant the goroutine parked on a lock it already held — no I/O, no CPU, no+// log line, and a mutex wait ignores context cancellation, so the run never+// returned. The timeout here turns that hang into a failure message.+func TestRecordingInsideTheAdmitBatchDoesNotDeadlock(t *testing.T) {+ k := &Kbinfos{}+ done := make(chan struct{})+ go func() {+ defer close(done)+ k.Admit(func(p *PoolAdmitter) {+ p.Add(map[string]any{"chunk_id": "w1", "content": "荀正 被关公一刀斩于马下"})+ // Both recorders run under the pool lock on purpose.+ k.RecordReachedTerm("荀正", "w1")+ k.RecordProbedAbsent("管亥")+ })+ }()+ select {+ case <-done:+ case <-time.After(3 * time.Second):+ t.Fatal("recording from inside the admit batch deadlocked: the ledger must not share the pool's mutex")+ }++ if got := k.ReachedTerms(); len(got) != 1 || got[0].Term != "荀正" || got[0].ChunkID != "w1" {+ t.Errorf("ReachedTerms = %+v, want the member recorded with its passage", got)+ }+ if absent := k.ProbedAbsentTerms(); len(absent) != 1 || absent[0] != "管亥" {+ t.Errorf("ProbedAbsent = %v, want 管亥", absent)+ }+ // The pool itself is unaffected by the ledger's separate lock.+ if len(k.Chunks) != 1 {+ t.Errorf("pool = %d chunk(s), want the admitted passage", len(k.Chunks))+ }+}++// TestLedgerAccessorsAreIndependentOfThePoolLock pins the other direction: a+// reader of the record never waits for a batch that is in flight, which is what+// lets the rewrite context be rendered while sessions are still admitting.+func TestLedgerAccessorsAreIndependentOfThePoolLock(t *testing.T) {+ k := &Kbinfos{}+ k.RecordReachedTerm("华雄", "w1")++ released := make(chan struct{})+ go func() {+ k.Admit(func(p *PoolAdmitter) {+ <-released // hold the pool lock until the reads below are done+ })+ }()+ // Give the batch a moment to take the pool lock.+ time.Sleep(50 * time.Millisecond)++ done := make(chan struct{})+ go func() {+ defer close(done)+ _ = k.ReachedTerms()+ _ = k.ProbedAbsentTerms()+ }()+ select {+ case <-done:+ case <-time.After(3 * time.Second):+ close(released)+ t.Fatal("reading the record blocked on the pool lock: the accessors must not need it")+ }+ close(released)+}diff --git a/internal/rag/advanced_rag/harness/scan_patterns.go b/internal/rag/advanced_rag/harness/scan_patterns.gonew file mode 100644index 0000000000..cc56335776--- /dev/null+++ b/internal/rag/advanced_rag/harness/scan_patterns.go@@ -0,0 +1,268 @@+//+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.+//++package harness++import (+ "context"+ "fmt"+ "regexp"+ "strings"+)++// scanTermsMax bounds the act words one direction may declare. Ten because a source words+// one deed many ways (斩 / 杀 / 劈 / 挥为两段 …), and a phrasing no term covers is a passage+// no query ever names.+const scanTermsMax = 10++// The completeness pass's budget. One pattern contributes at most patternWindowsPerAct+// windows, each quoted to patternWindowChars, and the whole block stays under+// patternFindingsMaxChars — the block is EVIDENCE the session reads (each window with the+// chunk id a member cites), so it is worth its characters in a way a list of queries the+// session may or may not run is not (see RunCompletenessPass).+const (+ patternWindowsPerAct = 3+ patternWindowChars = 120+ patternFindingsMaxChars = 6000+)++// MemberShaped reports whether the table declares a slot whose answer is a NAME, or a set+// of them (the planner's vocabulary is entity / person / dataset), as opposed to numbers,+// dates and phrases.+//+// It gates the completeness pass, and the difference it makes is measured (2026-09-16,+// FRAMES, mode high). The pass exists to find names nobody thought of, so its store legs+// are only worth their time when names are what the answer is made of. The planner is told+// to declare act words for "a SET or a COUNT of things that someone DID" — and it did, on+// questions whose answer is a NUMBER: `won / victory / champion / title / trophy /+// championship / rings` for "how many times had Brazil won the World Cup" and `writer /+// creator / author` for "the population of the birthplace of a novel's writer". Both were+// enumerated (7–10 store legs each, sessions handed 8 passages a turn from a 100-passage+// reading list) and both were among the run's most expensive questions — 433k tokens for+// the first, 200-320k for the second, together about 18% of the run. No name either pass+// could return changes a count of EVENTS. The declared terms STAY recorded — the record can+// still report what was asked for — but nothing is run for a question no name can change.+func MemberShaped(table State) bool {+ for _, v := range table.State {+ switch strings.ToLower(strings.TrimSpace(v.Type)) {+ case "entity", "person", "dataset", "list", "set":+ return true+ }+ }+ return false+}++// EnumerationShaped reports whether this table asks for an ENUMERATION — a set of NAMED members — as+// opposed to one value, one date or one number.+//+// It is the gate for every piece of the enumeration machinery (the method seed, the completeness pass,+// the member roll call), and it is the conjunction of three things the PLANNER itself declared, so+// nothing here reads a slot's text, the question, or a candidate:+//+// - SetShaped: the table asked for a count, a set or a list — the answer is a SET, not one value;+// - MemberShaped: a slot of this table carries NAMES (entity / person / dataset / list / set);+// - act words were declared for the deed being enumerated (a slot's Terms).+//+// The conjunction is what separates a set of named members from a count of EVENTS, which the planner+// declares act words for too ("how many times had Brazil won the World Cup" → won / victory /+// champion): that question is set-shaped but holds no names, so it is a VALUE question and pays+// nothing for a set's bookkeeping.+//+// Measured (2026-09-16, FRAMES, 4 questions in flight, 300s deadline): with the pass gated on+// MemberShaped alone it ran on 7 of the 20 questions — every one of them a single-value question —+// and the run ended 0.833 with two timeouts against 0.875 with none. The two strategies need+// different machinery, so they get it: a value question keeps the plain research loop, and only a+// table that declared all three things pays for the enumeration.+func EnumerationShaped(table State) bool {+ if !SetShaped(table) || !MemberShaped(table) {+ return false+ }+ for _, v := range table.State {+ if len(v.Terms) > 0 {+ return true+ }+ }+ return false+}++// PatternRunner gives one completeness pattern to the corpus and returns what matched.+//+// A one-method interface on purpose: the runtime must be able to run the block+// ScanPatterns renders WITHOUT asking the model, and the only thing it needs from the tool+// layer is one query. The implementation (searchExecutor.RunPattern) goes through the same+// grep path a retrieve call uses, so a pattern gets a pattern's treatment — operands+// recalled individually, the pattern deciding which candidates are windows, the windows+// narrowed to the match.+type PatternRunner interface {+ RunPattern(ctx context.Context, pattern string) []map[string]any+}++// CompletenessPass is what the runtime's pattern run produced.+type CompletenessPass struct {+ // Text is the block the sessions are seeded with: one line per declared pattern, with+ // the windows that came back and the chunk id each one is cited by. Empty when nothing+ // ran (no declaration, no runner, or a table that holds no name — see MemberShaped).+ Text string+ // Asked is how many patterns were given to the corpus, Answered how many came back+ // with at least one window, and Admitted how many windows entered the pool.+ Asked int+ Answered int+ Admitted int+}++// RunCompletenessPass runs the direction's declared act patterns over the corpus and+// returns the block the sessions are seeded with.+//+// The patterns used to be rendered into the seed as QUERIES TO MAKE, and the measurement is+// why they are now run HERE instead: measured (2026-09-16, 三国/关羽) a round declared ten+// act words with several aliases each — 2175 characters of patterns, in the seed of every+// session — and not one session ran a single one of them. The run's whole query log holds+// zero `.*` queries; the sessions improvised space-separated word lists instead+// (`关羽 斩华雄 温酒`, `关公 砍死 斩 杀`, `云长手起刀落`), which is exactly the shape the+// patterns exist to replace. A list of queries in a prompt is ADVICE, and the completeness+// of an enumeration cannot rest on advice — every run of this question missed 2-4 members+// and the missing names differed every run.+//+// Run here, what comes back is EVIDENCE: the windows are admitted to the shared pool (so+// they are citable, and the record and the answer can point at them) and the seed states+// them as facts, so the session's job becomes "read these windows and write the members+// they name" rather than "think of the queries I should have made".+//+// Gated on MemberShaped: a table of counts and dates declares act words too (see+// MemberShaped), and spending store legs on a question whose answer is a number is a cost+// with no possible payoff.+func RunCompletenessPass(ctx context.Context, runner PatternRunner, kb *Kbinfos, table State) CompletenessPass {+ pass := CompletenessPass{}+ if runner == nil || !EnumerationShaped(table) {+ return pass+ }+ patterns := ScanPatterns(table)+ if len(patterns) == 0 {+ return pass+ }+ var b strings.Builder+ b.WriteString("## The completeness pass ALREADY RAN for this direction\n\n")+ b.WriteString("Each act pattern below was given to the corpus by the runtime, and the matched " ++ "windows are in the pool under the chunk ids shown. Every pattern WAS asked, so " ++ "`(no window)` is the corpus answering about those WORDS — re-word it (see the " ++ "method's relation step) rather than running it again. A name inside a window is a " ++ "member you can cite with that chunk id: record it as one.\n\n")+ for _, pattern := range patterns {+ if ctx.Err() != nil {+ // The clock ran out mid-pass. The patterns nobody got to ask would render as+ // `(no window)` — a statement about the CORPUS the runtime never earned, and the+ // one reading the block forbids. So the pass yields nothing at all and the seed+ // keeps the pattern list (the fallback, see enumerationSeed); whatever windows+ // did come back are already in the pool, so no evidence is lost.+ return CompletenessPass{}+ }+ pass.Asked+++ chunks := runner.RunPattern(ctx, pattern)+ var lines []string+ for _, c := range chunks {+ if len(lines) >= patternWindowsPerAct {+ break+ }+ id := ChunkIDOf(c)+ quote := truncateRunes(strings.Join(strings.Fields(ChunkTextOf(c)), " "), patternWindowChars)+ if id == "" || quote == "" {+ continue+ }+ if kb != nil {+ kb.Admit(func(p *PoolAdmitter) {+ if p.Add(c) {+ pass.Admitted+++ }+ })+ }+ lines = append(lines, fmt.Sprintf(" chunk_id=%s \"%s\"", id, quote))+ }+ if len(lines) == 0 {+ fmt.Fprintf(&b, "- %s → (no window)\n", pattern)+ continue+ }+ pass.Answered+++ fmt.Fprintf(&b, "- %s →\n%s\n", pattern, strings.Join(lines, "\n"))+ if b.Len() >= patternFindingsMaxChars {+ b.WriteString("(further patterns omitted; what came back is in the pool)\n")+ break+ }+ }+ if pass.Asked == 0 || ctx.Err() != nil {+ // Same guard at the end: a search cancelled mid-flight returns what it had, so the+ // LAST pattern's emptiness is not the corpus answering (see the loop-head guard).+ return CompletenessPass{}+ }+ pass.Text = b.String()+ return pass+}++// ScanPatterns renders the completeness queries of an enumeration: for each act word a+// direction DECLARED, the actor and the act asked for TOGETHER, as a pattern.+//+// It is a string builder, not a mechanism. The grep path already reads a pattern the way+// this needs — grepPatternOf compiles it, GrepPatternOperands searches each literal operand+// on its own with the wide recall a pattern gets (patternRecallTopN), matchGrepPattern+// decides which candidates are windows, and the windows are narrowed to what carries the+// match (GrepOutCharsPerChunk / GrepOutTotalChars). So completeness comes from asking the+// CORPUS the right question once per act word — which is the one thing a session that only+// knows the names it can REMEMBER cannot do: measured (2026-09-16, 三国/关羽) every run of+// one question missed 2-4 members, the missing names differed every run, and in one run+// 车胄 / 夏侯存 / 程远志 / 管亥 appeared ZERO times in the whole log.+//+// The shape is `actor.*act`, one clause per pair, never `A|B.*T`: `|` binds loosest in Go's+// regexp, so that would read as "A" OR "B.*T" and lose the actor on every clause but the+// last. A subject that is itself an alternation (关羽|关公|云长) is used as declared; an empty+// subject falls back to the act word alone.+//+// Queries are grouped so that one call stays inside the operand budget the keyword leg+// already enforces (GrepTermsMax): each clause contributes its two literal operands.+func ScanPatterns(table State) []string {+ perQuery := max(1, GrepTermsMax/2)+ var out []string+ for _, v := range table.State {+ actors := []string{""}+ if s := strings.TrimSpace(v.Subject); s != "" {+ actors = nil+ for _, a := range strings.Split(s, "|") {+ if a = strings.TrimSpace(a); a != "" {+ actors = append(actors, a)+ }+ }+ if len(actors) == 0 {+ actors = []string{""}+ }+ }+ var clauses []string+ for _, t := range v.Terms {+ t = strings.TrimSpace(t)+ if t == "" {+ continue+ }+ if actors[0] == "" {+ clauses = append(clauses, regexp.QuoteMeta(t))+ continue+ }+ for _, a := range actors {+ clauses = append(clauses, regexp.QuoteMeta(a)+".*"+regexp.QuoteMeta(t))+ }+ }+ for i := 0; i < len(clauses); i += perQuery {+ out = append(out, strings.Join(clauses[i:min(i+perQuery, len(clauses))], "|"))+ }+ }+ return out+}diff --git a/internal/rag/advanced_rag/harness/scan_patterns_test.go b/internal/rag/advanced_rag/harness/scan_patterns_test.gonew file mode 100644index 0000000000..c8e03cff4c--- /dev/null+++ b/internal/rag/advanced_rag/harness/scan_patterns_test.go@@ -0,0 +1,201 @@+package harness++import (+ "context"+ "strings"+ "testing"+)++// TestScanPatternsAskForActorAndActTogether pins the shape of the completeness query.+//+// One clause per (actor, act) pair, never `A|B.*T`: `|` binds loosest in Go's regexp, so+// that would read as "A" OR "B.*T" and silently drop the actor from every clause but the+// last. And the actor is what makes the query do work the model's memory cannot: measured+// (2026-09-16, 三国/关羽) every run of one question missed 2-4 members, the missing names+// differed every run, and in one run four of them appeared ZERO times in the whole log.+func TestScanPatternsAskForActorAndActTogether(t *testing.T) {+ table := NewState([]Variable{+ {ID: 0, Type: "count", Terms: []string{"斩", "杀"}, Subject: "关羽|关公|云长"},+ {ID: 1, Type: "person"},+ }, 0, nil)++ got := ScanPatterns(table)+ if len(got) == 0 {+ t.Fatal("no patterns for a table that declared two act words and three aliases")+ }+ clauses := 0+ for _, q := range got {+ parts := strings.Split(q, "|")+ if len(parts) > GrepTermsMax/2 {+ t.Errorf("query %q carries %d clauses, want at most %d (each clause is two operands)", q, len(parts), GrepTermsMax/2)+ }+ for _, part := range parts {+ clauses+++ if !strings.Contains(part, ".*") {+ t.Errorf("clause %q does not ask for actor AND act together", part)+ }+ }+ }+ if clauses != 6 {+ t.Errorf("clauses = %d, want 6 (3 aliases × 2 act words)", clauses)+ }+ if !strings.Contains(strings.Join(got, "|"), "云长.*斩") {+ t.Errorf("patterns %v, want every declared alias paired with every act word", got)+ }++ // No subject declared: the act word itself, which is all the direction gave.+ bare := ScanPatterns(NewState([]Variable{{ID: 0, Type: "count", Terms: []string{"斩"}}}, 0, nil))+ if len(bare) != 1 || bare[0] != "斩" {+ t.Errorf("patterns = %v, want the act word alone when no actor was declared", bare)+ }++ // No declaration, no queries: a table that named no act word pays nothing.+ if p := ScanPatterns(NewState([]Variable{{ID: 0, Type: "date", Candidate: strPtr("1858")}}, 0, nil)); len(p) != 0 {+ t.Errorf("patterns = %v, want none without a declaration", p)+ }+}++// stubPatternRunner answers one completeness pattern with the chunks a test staged for it.+type stubPatternRunner struct {+ calls []string+ byPattern map[string][]map[string]any+}++func (s *stubPatternRunner) RunPattern(_ context.Context, pattern string) []map[string]any {+ s.calls = append(s.calls, pattern)+ return s.byPattern[pattern]+}++// TestCompletenessPassRunsWhatItRendered pins the fix for a measured failure: the patterns+// were RENDERED, and nobody ran them.+//+// Measured (2026-09-16, 三国/关羽, one round): ten act words with several aliases each came+// to 2175 characters of patterns, present in the seed of every session, and the run's query+// log holds ZERO `.*` queries — the sessions improvised space-separated word lists instead+// (`关羽 斩华雄 温酒`, `关公 砍死 斩 杀`). A list of queries in a prompt is advice, and the+// completeness of an enumeration cannot rest on advice. So the runtime asks the corpus+// itself, admits the windows, and seeds what came back.+func TestCompletenessPassRunsWhatItRendered(t *testing.T) {+ table := NewState([]Variable{+ {ID: 0, Type: "count", Terms: []string{"斩", "劈"}, Subject: "关羽|云长|关公"},+ {ID: 1, Type: "dataset"},+ }, 0, nil)+ patterns := ScanPatterns(table)+ if len(patterns) < 2 {+ t.Fatalf("patterns = %v, want at least two queries (the declaration has six clauses)", patterns)+ }+ window := map[string]any{"chunk_id": "c1", "content_with_weight": "云长手起刀落,斩孔秀于马下"}+ runner := &stubPatternRunner{byPattern: map[string][]map[string]any{patterns[0]: {window}}}+ kb := &Kbinfos{}++ pass := RunCompletenessPass(context.Background(), runner, kb, table)++ if len(runner.calls) != len(patterns) {+ t.Fatalf("ran %d pattern(s), want every declared one (%d): %v", len(runner.calls), len(patterns), runner.calls)+ }+ if pass.Asked != len(patterns) || pass.Answered != 1 || pass.Admitted != 1 {+ t.Errorf("pass = asked %d / answered %d / admitted %d, want %d / 1 / 1",+ pass.Asked, pass.Answered, pass.Admitted, len(patterns))+ }+ if !strings.Contains(pass.Text, "c1") || !strings.Contains(pass.Text, "斩孔秀于马下") {+ t.Errorf("block %q, want the window with the chunk id a member cites", pass.Text)+ }+ if !strings.Contains(pass.Text, "(no window)") {+ t.Errorf("block %q, want the empty pattern stated as asked-and-empty — otherwise the session cannot tell "++ "\"the corpus has no such passage\" from \"nobody looked\"", pass.Text)+ }+ for _, p := range patterns {+ if !strings.Contains(pass.Text, p) {+ t.Errorf("block %q does not name the pattern %q it ran", pass.Text, p)+ }+ }+ // The window is EVIDENCE: it must be in the pool, under the id the block cites, or the+ // session can read it and cite nothing.+ if kb.PoolSize() != 1 || ChunkIDOf(kb.Chunks[0]) != "c1" {+ t.Errorf("pool = %d chunk(s) %v, want the matched window admitted", kb.PoolSize(), kb.Chunks)+ }++ // A table that holds NO NAME pays nothing: the planner declares act words for "a count+ // of things someone DID" too, and no name a pass could return changes a count of events+ // (measured 2026-09-16, FRAMES: two such questions, ~18% of the run's tokens).+ countsOnly := NewState([]Variable{+ {ID: 0, Type: "count", Terms: []string{"won", "trophy"}, Subject: "Brazil"},+ }, 0, nil)+ quiet := &stubPatternRunner{}+ if pass := RunCompletenessPass(context.Background(), quiet, kb, countsOnly); pass.Asked != 0 || len(quiet.calls) != 0 {+ t.Errorf("ran %v for a table with no name slot, want nothing", quiet.calls)+ }+ // And a run with no runner is not a panic but a fallback: the seed keeps the list.+ if pass := RunCompletenessPass(context.Background(), nil, kb, table); pass.Text != "" {+ t.Errorf("pass without a runner = %q, want nothing", pass.Text)+ }+}++// TestEnumerationSeedCarriesFindingsInsteadOfTheList pins what the session reads when the+// pass has run: the windows, not the queries it would have to think of.+func TestEnumerationSeedCarriesFindingsInsteadOfTheList(t *testing.T) {+ loader := StringPromptLoader{"action_set": "SET / COUNT directions — the member list IS the work"}+ table := NewState([]Variable{+ {ID: 0, Type: "count", Terms: []string{"斩"}, Subject: "关羽|云长"},+ {ID: 1, Type: "dataset"},+ }, 0, nil)++ // No pass yet: the fallback is the pattern list, marked as queries to make.+ seed := enumerationSeed(table, loader, "")+ if !strings.Contains(seed, "关羽.*斩|云长.*斩") {+ t.Fatalf("fallback seed %q, want the rendered patterns", seed)+ }++ findings := "## The completeness pass ALREADY RAN for this direction\n\n- 关羽.*斩 →\n chunk_id=c1 \"斩孔秀\""+ seed = enumerationSeed(table, loader, findings)+ if !strings.Contains(seed, "chunk_id=c1") {+ t.Errorf("seed %q, want the pass's windows", seed)+ }+ if !strings.Contains(seed, "SET / COUNT directions") {+ t.Errorf("seed %q, want the method still travelling with the windows", seed)+ }+ if strings.Contains(seed, "one call per line") {+ t.Errorf("seed %q still lists patterns to make — the windows replaced them", seed)+ }+}++// TestEnumerationShapedSeparatesSetsFromValues pins the split the two strategies need: a set of NAMED+// members is not a count of events, and neither is a question about one named thing.+//+// Measured (2026-09-16, FRAMES, 4 questions in flight, 300s deadline): with the completeness pass+// gated on MemberShaped alone it ran on 7 of the 20 questions — every one of them single-value — and+// the run finished 0.833 with two timeouts against 0.875 with none. The gate is the conjunction of+// the planner's OWN three statements, so nothing is read from a slot's text or from the question.+func TestEnumerationShapedSeparatesSetsFromValues(t *testing.T) {+ set := NewState([]Variable{+ {ID: 0, Type: "count", Terms: []string{"斩", "杀"}, Subject: "关羽|云长"},+ {ID: 1, Type: "dataset"},+ }, 0, nil)+ if !EnumerationShaped(set) {+ t.Error("a count over named members with declared act words IS an enumeration")+ }+ cases := []struct {+ name string+ table State+ }{+ {"a count of events (no slot holds names)", NewState([]Variable{+ {ID: 0, Type: "count", Terms: []string{"won", "trophy"}, Subject: "Brazil"},+ }, 0, nil)},+ {"a named thing with act words but no count/set/list", NewState([]Variable{+ {ID: 0, Type: "person", Terms: []string{"wrote"}},+ {ID: 1, Type: "date"},+ }, 0, nil)},+ {"a count with nothing declared to enumerate", NewState([]Variable{+ {ID: 0, Type: "count", Candidate: strPtr("18")},+ {ID: 1, Type: "dataset"},+ }, 0, nil)},+ {"a single value", NewState([]Variable{+ {ID: 0, Type: "date", Candidate: strPtr("1858")},+ }, 0, nil)},+ }+ for _, tc := range cases {+ if EnumerationShaped(tc.table) {+ t.Errorf("%s must NOT be an enumeration: the enumeration machinery (method seed, completeness pass, roll call) costs a value question its budget", tc.name)+ }+ }+}diff --git a/internal/rag/advanced_rag/harness/session_state_line.go b/internal/rag/advanced_rag/harness/session_state_line.gonew file mode 100644index 0000000000..05e686e225--- /dev/null+++ b/internal/rag/advanced_rag/harness/session_state_line.go@@ -0,0 +1,422 @@+package harness++import (+ "fmt"+ "strings"+ "unicode/utf8"++ "ragflow/internal/rag/advanced_rag/slots"+ "ragflow/internal/tokenizer"+)++// SessionRecord is what a session has DONE so far, expressed as facts the ReAct+// loop cannot recover from its own conversation.+//+// The session's message list holds the model's queries and the passages that came+// back, and nothing else: which names were already probed (and which of those came+// back empty), which members the record now holds, and which confirmed members are+// still undecided — a name whose passage is in the pool and which no slot+// mentions. Every one of those facts is computed by the runtime anyway, and+// withholding them left the model driving its queries blind: it re-asked names it+// had already resolved, and it could not see that a name it found was still+// unrecorded.+//+// Measured (fixrecall2, 2026-09-15, mode=high): a session probed 15+ terms across+// 8 turns and recorded none of them until it was forced to, with 庞德 queried,+// found, and then dropped by the model's own reasoning — a decision the runtime+// could not see and therefore never asked about.+//+// The record is also the basis of the continuation decision: the offer the model+// answers (offerContinuation) carries it, so "is anything still missing?" is a+// question about facts the model can read, not about its appetite for searching.+type SessionRecord struct {+ // Pool is the shared evidence pool's size at this turn.+ Pool int+ // Members are the names the slot table currently records (split out of the+ // candidates, so "孔秀、孟坦" counts as two).+ Members []string+ // Reached are the named terms a probe reached, with evidence (Kbinfos.Reached).+ Reached []string+ // Absent are the named terms probes looked for and did not find+ // (Kbinfos.ProbedAbsent): "asked and nothing came back" is a result, and it+ // is the one that tells the model to change the spelling or the angle.+ Absent []string+ // Undecided are confirmed members (Reached) that the slot table does not+ // mention at all: the evidence exists, the decision does not.+ Undecided []string+}++// CollectSessionRecord gathers the record from the live pool plus the session's+// slot table. A nil pool yields the table half only.+//+// Everything here is derived from facts the runtime already holds — the slot+// table and the ledger of terms the session itself asked about — and needs no+// knowledge of the corpus's language, subject or relation.+func CollectSessionRecord(table State, kb *Kbinfos) SessionRecord {+ var r SessionRecord+ if kb != nil {+ r.Pool = kb.PoolSize()+ for _, rt := range kb.ReachedTerms() {+ r.Reached = append(r.Reached, rt.Term)+ }+ r.Absent = kb.ProbedAbsentTerms()+ }+ // Members come from the slots that DECLARE members (slots.KindMembers), each+ // item carrying its evidence. Nothing is split out of text: a slot holding a+ // sentence, a date or a count contributes no members, and the text is never+ // inspected to find out whether it might have been a list (see package slots for+ // the measurement that made this fail closed).+ seen := map[string]bool{}+ for _, v := range table.State {+ if v.Typed().Kind != slots.KindMembers {+ continue+ }+ for _, name := range v.Typed().Names() {+ key := strings.ToLower(name)+ if seen[key] {+ continue+ }+ seen[key] = true+ r.Members = append(r.Members, name)+ }+ }+ joined := strings.ToLower(strings.Join(r.Members, "\x00"))+ for _, term := range r.Reached {+ // Substring containment, not equality: a candidate is often a clause+ // ("庞德被周仓生擒") rather than a bare name, and the question is only+ // whether the record has taken a position on this term at all.+ if !strings.Contains(joined, strings.ToLower(term)) {+ r.Undecided = append(r.Undecided, term)+ }+ }+ return r+}++// Line renders the record as ONE line for the tool result the model reads.+//+// It is deliberately a single line of counts plus a few names, not a block: it is+// appended to every tool result, so its cost is paid once per turn, and it must+// stay small enough that it never crowds out the passages it annotates.+func (r SessionRecord) Line() string {+ var b strings.Builder+ b.WriteString("[record] ")+ fmt.Fprintf(&b, "members=%d", len(r.Members))+ if len(r.Members) > 0 {+ fmt.Fprintf(&b, " (%s)", shortList(r.Members, 6))+ }+ fmt.Fprintf(&b, " | probed-reached=%d", len(r.Reached))+ if len(r.Absent) > 0 {+ fmt.Fprintf(&b, " asked-nothing-back=%d (%s)", len(r.Absent), shortList(r.Absent, 4))+ }+ if len(r.Undecided) > 0 {+ fmt.Fprintf(&b, " | FOUND BUT NOT RECORDED=%s", shortList(r.Undecided, 4))+ }+ fmt.Fprintf(&b, " | pool=%d", r.Pool)+ return b.String()+}++// shortList joins up to max items on the list separator and marks the remainder.+func shortList(items []string, max int) string {+ if len(items) > max {+ return strings.Join(items[:max], "、") + fmt.Sprintf("…+%d", len(items)-max)+ }+ return strings.Join(items, "、")+}++// sessionRecordNow computes the session's record as of this turn.+func (s *SessionState) sessionRecordNow() SessionRecord {+ return CollectSessionRecord(s.workingTable(), s.KB)+}++// workingTable is the slot table as THIS session has patched it: the parent table+// with the session's own branch patches applied in order. Reading the parent table+// alone would report the record as it stood when the session started, so a member+// the session itself just found would still read as missing.+func (s *SessionState) workingTable() State {+ t := State{+ State: append([]Variable(nil), s.ParentState.State...),+ Depth: s.ParentState.Depth,+ ID: s.ParentState.ID,+ RetrievedEvidenceIDs: s.ParentState.RetrievedEvidenceIDs,+ }+ for _, branch := range s.NewStates {+ for _, patch := range branch.State {+ for i := range t.State {+ if t.State[i].ID != patch.ID || patch.Candidate == nil || *patch.Candidate == "" {+ continue+ }+ t.State[i].Candidate = patch.Candidate+ t.State[i].CandidateStrength = patch.CandidateStrength+ }+ }+ }+ return t+}++// Brief is the record's counts, for logs.+func (r SessionRecord) Brief() string {+ out := fmt.Sprintf("members=%d reached=%d absent=%d undecided=%d",+ len(r.Members), len(r.Reached), len(r.Absent), len(r.Undecided))+ return out+}++// poolExcerptRunes bounds how much pool text one turn may add to the model's+// context: about one sentence plus its neighbours, which is where a name and the+// deed that makes it a member sit together.+const poolExcerptRunes = 220++// poolScanMax bounds how many pool chunks one turn examines while choosing that+// excerpt. The scan is local — one substring test and one token count per chunk —+// so this bound is about latency discipline, not about money.+const poolScanMax = 60++// subjectWordsMax bounds the words used to recognise "a passage about the same+// subject". They select a passage to READ; they never decide anything.+const subjectWordsMax = 8++// unreadPoolExcerpt returns a short excerpt from ONE pool passage this session has+// never been shown, chosen for what it says that the record does not.+//+// The pool is text the round has ALREADY paid for, and a session only ever sees+// the parts its own queries returned — everything else sat in hand, unread. That+// gap is where members are lost without anyone noticing. Measured (2026-09-15,+// 三国演义/关羽, mode=high): the passage naming 管亥 was fetched into the round's+// evidence at 21:09:13 and no session ever named it, because nothing had shown it;+// the sessions' own enumeration reached 11 and 12 members, and the five names the+// answer was missing were all in passages of exactly that kind.+//+// The framework does not name anybody here. It reads the unread passages that+// mention a word THIS SESSION has used — the direction it was sent on, the slot's+// clues, the candidates, and its own queries, which is what carries the corpus's+// own aliases (a session that asked about 关公 gets passages that say 关公) — and+// hands over a bounded excerpt around the first term of that passage the record+// does not contain. The division of labour is the usual one: the runtime supplies+// a fact (this text exists, you have not read it), the model decides what is in it.+//+// Mentioning one of those words is a FILTER, not a preference. Measured+// (2026-09-15, the first version of this, which ranked every unread passage by how+// much of its vocabulary was new): all eight excerpts it delivered were passages+// the question had nothing to do with — a chapter heading, 曹操's youth, 张角+// receiving the book — because "says the most you have not seen" and "is about+// this question" are anti-correlated: the passages that carry the subject share+// their vocabulary with what the session already read, so they score LOW. The+// words the session itself used are what tells the two apart, and they are the+// model's words, not a lexicon.+func (s *SessionState) unreadPoolExcerpt() string {+ // ONE per session, and that is deliberate. Across the first two runs of this+ // mechanism (2026-09-15) it delivered twelve excerpts — a chapter heading, 曹操's+ // youth, 张角 receiving the book, a 文丑 passage — and none of them carried a+ // member the record was missing. The premise still holds (the passage naming+ // 管亥 was in the pool for the whole of those runs), but the selection is not+ // good enough to spend context on every flat turn, so it stays available as the+ // session's last resort rather than a routine.+ if s.KB == nil || s.PoolRead {+ return ""+ }+ subject := s.subjectWords()+ if len(subject) == 0 {+ return ""+ }+ seen := make(map[string]bool, len(s.RetrievedEvidenceIDs))+ for _, id := range s.RetrievedEvidenceIDs {+ seen[id] = true+ }+ known := s.recordVocabulary()+ chunks := s.KB.ChunksFrom(s.PoolWalk, poolScanMax)+ s.PoolWalk += len(chunks)++ var bestID, bestText, bestAnchor string+ bestNovel := 0+ for _, c := range chunks {+ text := ChunkTextOf(c)+ if text == "" {+ continue+ }+ if id := ChunkIDOf(c); id != "" && seen[id] {+ continue+ }+ if !mentionsAny(text, subject) {+ continue+ }+ anchor, novel := novelAnchor(text, known)+ if novel == 0 {+ continue+ }+ if novel > bestNovel {+ bestID, bestText, bestAnchor, bestNovel = ChunkIDOf(c), text, anchor, novel+ }+ }+ if bestNovel == 0 {+ return ""+ }+ s.PoolRead = true+ return fmt.Sprintf("[pool] unread passage already in evidence, never shown to you (id=%s): %s",+ bestID, excerptAround(bestText, bestAnchor, poolExcerptRunes))+}++// mentionsAny reports whether text carries any of the words — the relevance test+// the excerpt is gated on.+func mentionsAny(text string, words []string) bool {+ for _, w := range words {+ if strings.Contains(text, w) {+ return true+ }+ }+ return false+}++// subjectWords returns the words that stand for what this session is working on:+// the direction it was sent on, the slot's own question clues, the candidates so+// far, and the queries the session itself wrote.+//+// They are the model's (or the planner's) own words, read with the corpus's own+// tokenizer, so no list of names or verbs is involved anywhere.+func (s *SessionState) subjectWords() []string {+ var out []string+ seen := map[string]bool{}+ add := func(text string) {+ if text == "" || len(out) >= subjectWordsMax {+ return+ }+ for _, w := range append(GrepWordsFromQuery(text), tokenizerWords(text)...) {+ w = strings.TrimSpace(w)+ if r := utf8.RuneCountInString(w); r < 2 || r > cjkPhraseRunes {+ continue+ }+ low := strings.ToLower(w)+ if seen[low] {+ continue+ }+ seen[low] = true+ out = append(out, w)+ if len(out) >= subjectWordsMax {+ return+ }+ }+ }+ // The session's OWN queries first: they are the most specific thing it has+ // said, and they are where the corpus's aliases enter (a session that asked+ // about 关公 gets passages that say 关公, while the direction may only say 关羽).+ for _, q := range s.SearchQueries {+ add(q)+ }+ for _, v := range s.ParentState.State {+ if v.Candidate != nil {+ add(*v.Candidate)+ }+ for _, clue := range v.QuestionClues {+ add(clue)+ }+ }+ add(s.Direction)+ return out+}++// grewFrom reports whether this record knows something the previous turn's did.+//+// It is the same signal the continuation offer is built on (see+// offerContinuation), used for the opposite decision: an enumeration session whose+// record is still growing is already finding things, so the pool read stays out of+// its way and only steps in when the record has gone flat.+func (r SessionRecord) grewFrom(prev SessionRecord) bool {+ return len(r.Members) > len(prev.Members) ||+ len(r.Reached) > len(prev.Reached) ||+ len(r.Absent) > len(prev.Absent)+}++// tokenizerWords runs the corpus's own tokenizer over a text (see+// tokenizer.Tokenize): the same segmentation the index was built with, which is+// what makes it usable without a lexicon.+//+// When that tokenizer is not available — a unit test, an engine configured+// differently — it falls back to the two-rune windows the grep path uses to+// LOCATE a term inside unbroken text. As a vocabulary that is noisier, but it needs+// nothing but the text, and a passage is only ever SELECTED by this score, never+// decided on it.+func tokenizerWords(text string) []string {+ if toks, err := tokenizer.Tokenize(text); err == nil && strings.TrimSpace(toks) != "" {+ return strings.Fields(toks)+ }+ return cjkWindowsOf(text, tokenWindowsMax)+}++// tokenWindowsMax bounds the fallback vocabulary of one passage.+const tokenWindowsMax = 400++// novelAnchor returns the first term of the text that the record does not contain,+// and how many such terms the text has. The anchor is what the excerpt is centred+// on — the part of the passage that is new to this session is the part worth+// reading.+func novelAnchor(text string, known map[string]bool) (string, int) {+ anchor, n := "", 0+ seen := map[string]bool{}+ for _, t := range tokenizerWords(text) {+ if r := utf8.RuneCountInString(t); r < 2 || r > cjkPhraseRunes {+ continue+ }+ low := strings.ToLower(t)+ if seen[low] || known[low] {+ continue+ }+ seen[low] = true+ if anchor == "" {+ anchor = t+ }+ n+++ }+ return anchor, n+}++// recordVocabulary is everything the record already accounts for: its members, the+// terms probes reached, and the terms probes asked about and did not find. A term+// in here is not new information.+func (s *SessionState) recordVocabulary() map[string]bool {+ out := map[string]bool{}+ for _, group := range [][]string{s.Record.Members, s.Record.Reached, s.Record.Absent, s.Record.Undecided} {+ for _, t := range group {+ if t = strings.ToLower(strings.TrimSpace(t)); t != "" {+ out[t] = true+ }+ }+ }+ for _, q := range s.SearchQueries {+ for _, w := range GrepWordsFromQuery(q) {+ out[strings.ToLower(w)] = true+ }+ }+ return out+}++// excerptAround returns a one-line window of at most maxRunes runes around the+// first occurrence of word, so the excerpt carries both the mention and the+// sentence around it.+func excerptAround(text, word string, maxRunes int) string {+ flat := []rune(strings.Join(strings.Fields(text), " "))+ at := []rune(word)+ pos := -1+ for i := 0; i+len(at) <= len(flat); i++ {+ if string(flat[i:i+len(at)]) == word {+ pos = i+ break+ }+ }+ if pos < 0 {+ pos = 0+ }+ start := pos - maxRunes/3+ if start < 0 {+ start = 0+ }+ end := start + maxRunes+ if end > len(flat) {+ end = len(flat)+ }+ out := string(flat[start:end])+ if start > 0 {+ out = "…" + out+ }+ if end < len(flat) {+ out += "…"+ }+ return out+}diff --git a/internal/rag/advanced_rag/harness/session_state_line_test.go b/internal/rag/advanced_rag/harness/session_state_line_test.gonew file mode 100644index 0000000000..d096c582f5--- /dev/null+++ b/internal/rag/advanced_rag/harness/session_state_line_test.go@@ -0,0 +1,555 @@+package harness++import (+ "strconv"+ "strings"+ "testing"++ "github.com/cloudwego/eino/schema"++ "ragflow/internal/rag/advanced_rag/slots"+)++// typedMembersSlot / typedCountSlot build the slots the record reads: a slot holds+// members or a number because the model DECLARED it (see package slots), so these are+// what a patch now produces.+func typedMembersSlot(id int, typ string, names ...string) Variable {+ items := make([]slots.Member, 0, len(names))+ for _, n := range names {+ items = append(items, slots.Member{Name: n})+ }+ v := slots.Members(items...)+ rendered := slots.Render(v)+ return Variable{ID: id, Type: typ, Candidate: &rendered, Value: &v}+}++func typedCountSlot(id int, typ string, n int) Variable {+ v := slots.Number(n)+ rendered := slots.Render(v)+ return Variable{ID: id, Type: typ, Candidate: &rendered, Value: &v}+}++// TestCollectSessionRecordFlagsFoundButNotRecorded is the defect this record+// exists for: a name the session PROVED reachable (it has a passage) and never+// took a position on must be visible, not silent.+//+// Measured (fixrecall2, 2026-09-15): 庞德 was queried, a passage came back, and+// the model's own reasoning dropped him — the framework saw nothing.+func TestCollectSessionRecordFlagsFoundButNotRecorded(t *testing.T) {+ kb := &Kbinfos{}+ for i := 0; i < 5; i++ {+ id := "c" + strconv.Itoa(i)+ kb.Admit(func(p *PoolAdmitter) {+ p.Add(map[string]any{"chunk_id": id, "content": "prose"})+ })+ }+ kb.RecordReachedTerm("荀正", "c1")+ kb.RecordReachedTerm("庞德", "c2")+ kb.RecordProbedAbsent("杨龄")++ table := State{State: []Variable{+ typedCountSlot(0, "count", 13),+ typedMembersSlot(1, "person", "孔秀", "孟坦", "荀正"),+ }}+ rec := CollectSessionRecord(table, kb)+ // 13 is the COUNT, not a member: a member count inflated by the answer slot is+ // the number the model steers by, so the answer slot must not be in it.+ if len(rec.Members) != 3 || rec.Members[0] != "孔秀" {+ t.Fatalf("members = %v, want the 3 names the candidates list (no count)", rec.Members)+ }+ if len(rec.Reached) != 2 || len(rec.Absent) != 1 {+ t.Fatalf("ledger = reached %v absent %v, want 2 reached / 1 absent", rec.Reached, rec.Absent)+ }+ if len(rec.Undecided) != 1 || rec.Undecided[0] != "庞德" {+ t.Fatalf("undecided = %v, want [庞德]: 荀正 is recorded, 庞德 is not", rec.Undecided)+ }+ line := rec.Line()+ for _, want := range []string{"members=3", "FOUND BUT NOT RECORDED=庞德", "asked-nothing-back=1", "pool=5"} {+ if !strings.Contains(line, want) {+ t.Errorf("line %q missing %q", line, want)+ }+ }+}++// TestSessionRecordLineCarriesNoPoolJudgement pins what the line does NOT claim:+// it reports the pool's size as a number and nothing more. The turn budget is the+// model's decision now (see offerContinuation), so no runtime predicate may turn+// "the pool grew" into "keep going".+func TestSessionRecordLineCarriesNoPoolJudgement(t *testing.T) {+ rec := SessionRecord{Pool: 500, Members: []string{"华雄"}, Reached: []string{"华雄", "颜良"}}+ line := rec.Line()+ if !strings.Contains(line, "pool=500") {+ t.Fatalf("line %q, want the pool size reported", line)+ }+ for _, banned := range []string{"grew", "growth", "continue"} {+ if strings.Contains(strings.ToLower(line), banned) {+ t.Errorf("line %q must not advise on continuing", line)+ }+ }+}++// TestWorkingTableAppliesSessionPatches pins the table the record reads: the+// session's own branches, or a member the session just found would still read as+// missing.+func TestWorkingTableAppliesSessionPatches(t *testing.T) {+ s := &SessionState{+ ParentState: State{State: []Variable{+ {ID: 1, Type: "person", Candidate: nil},+ {ID: 2, Type: "person", Candidate: strPtr("华雄")},+ }},+ NewStates: []State{{State: []Variable{+ {ID: 1, Type: "person", Candidate: strPtr("孔秀、孟坦")},+ }}},+ }+ tbl := s.workingTable()+ if tbl.State[0].Candidate == nil || *tbl.State[0].Candidate != "孔秀、孟坦" {+ t.Fatalf("patched slot = %v, want the session's own candidate", tbl.State[0].Candidate)+ }+ if tbl.State[1].Candidate == nil || *tbl.State[1].Candidate != "华雄" {+ t.Fatalf("untouched slot = %v, want the parent candidate kept", tbl.State[1].Candidate)+ }+ // The parent table is NOT mutated: another session shares it.+ if s.ParentState.State[0].Candidate != nil {+ t.Fatal("workingTable must not write through to the shared parent table")+ }+}++// TestAppendRecordLineRidesOnTheLastToolMessage pins the channel: one line on the+// tool result the model is about to read, and nothing at all on a turn that ran no+// tool call (or has no pool to report on).+func TestAppendRecordLineRidesOnTheLastToolMessage(t *testing.T) {+ kb := &Kbinfos{}+ kb.Admit(func(p *PoolAdmitter) {+ p.Add(map[string]any{"chunk_id": "c1", "content": "prose"})+ })+ s := &SessionState{+ KB: kb,+ ParentState: State{State: []Variable{+ typedCountSlot(0, "count", 13),+ typedMembersSlot(1, "person", "孔秀", "孟坦"),+ }},+ Messages: []schema.Message{*schema.ToolMessage(`{"passages": []}`, "call_1")},+ }+ s.appendRecordLine(true)+ got := s.Messages[len(s.Messages)-1].Content+ if !strings.Contains(got, "[record]") || !strings.Contains(got, "pool=1") {+ t.Fatalf("tool message = %q, want the record line appended", got)+ }+ if !strings.HasPrefix(got, `{"passages": []}`) {+ t.Fatalf("tool message = %q, want the payload preserved ahead of the line", got)+ }+ if !strings.Contains(got, "members=2") {+ t.Errorf("line %q, want the members the table holds", got)+ }++ // A turn with no tool call must not touch the previous result.+ before := s.Messages[len(s.Messages)-1].Content+ s.appendRecordLine(false)+ if s.Messages[len(s.Messages)-1].Content != before {+ t.Fatal("a turn that ran no tool call must not append a line")+ }++ // No pool bound: the record is kept, the line is skipped rather than inventing+ // a message for it.+ empty := &SessionState{Messages: []schema.Message{*schema.ToolMessage("x", "call_2")}}+ empty.appendRecordLine(true)+ if empty.Messages[0].Content != "x" {+ t.Fatalf("no-pool message = %q, want it untouched", empty.Messages[0].Content)+ }+}++// TestOfferContinuationLetsTheModelDecide pins the turn-budget contract: past the+// mode's floor the session does NOT stop, and it does not extend itself on a+// runtime predicate either — the model is asked, once per turn, up to a hard cap.+//+// The cap is the part the runtime keeps: medium/high run 8 → 12, ultra 10 → 14,+// which is the "maximum run" the session may never exceed however eager the model+// is. The floors are asserted here because the enumeration path walks them: a+// session that is still turning names into evidence needs the turns these numbers+// buy (see the measurement on offerContinuation).+func TestOfferContinuationLetsTheModelDecide(t *testing.T) {+ for mode, floor := range map[string]int{"medium": 8, "high": 8, "ultra": 10} {+ if got := GetMode(mode).ActionMaxTurns; got != floor {+ t.Errorf("%s turn floor = %d, want %d (cap = floor + %d)", mode, got, floor, turnRunExtra)+ }+ }++ s := enumerationSession(4, 90)+ if got := s.turnRunCap(); got != 8 {+ t.Fatalf("run cap = %d, want 8 (the mode's floor 4 + the model's %d)", got, turnRunExtra)+ }+ if !s.offerContinuation() {+ t.Fatal("past the floor the session must offer the model another turn")+ }+ last := s.Messages[len(s.Messages)-1]+ if last.Role != schema.User {+ t.Fatalf("offer role = %v, want a user message the model answers", last.Role)+ }+ for _, want := range []string{"TURN BUDGET", "up to 8", "4 turn(s) left", "state patch NOW"} {+ if !strings.Contains(last.Content, want) {+ t.Errorf("offer %q missing %q", last.Content, want)+ }+ }++ // Idempotent within a turn: the model must not be asked twice for one turn.+ before := len(s.Messages)+ if !s.offerContinuation() {+ t.Fatal("re-asking for the same turn must still allow the turn")+ }+ if len(s.Messages) != before {+ t.Fatalf("messages grew to %d, want the offer appended once per turn", len(s.Messages))+ }++ // A new turn asks again (the model re-decides with the new tool result).+ s.Attempts = 5+ if !s.offerContinuation() || len(s.Messages) != before+1 {+ t.Fatal("each new turn must carry its own offer")+ }++ // The hard cap: no offer, and the session finalizes.+ capped := enumerationSession(8, 90)+ if capped.offerContinuation() {+ t.Fatal("the run cap must not be exceedable")+ }+ if len(capped.Messages) != 0 {+ t.Fatal("no offer may be appended at the cap")+ }++ // The clock is the other hard bound: without room for the finalize step no+ // further turn is offered, however willing the model is.+ tight := enumerationSession(4, turnAskFloorS-1)+ if tight.offerContinuation() {+ t.Fatal("no turn may be offered without room for the finalize step")+ }+}++// enumerationSession is a session sent on a SET question — the parent table holds+// a count slot, which is the shape the continuation offer is gated on.+func enumerationSession(attempts int, deadlineLeft float64) *SessionState {+ return &SessionState{+ Attempts: attempts,+ DeadlineLeft: deadlineLeft,+ ParentState: State{State: []Variable{{ID: 0, Type: "count", Candidate: strPtr("12")}}},+ }+}++// TestOfferContinuationIsGatedOnTheQuestionsShape pins the cost rule. The offer is+// an extra model call plus up to turnRunExtra more turns, and a question that is+// not assembling a set has nothing for those turns to find: measured on+// 2026-09-15, one enumeration question was offered four extra turns while the+// sessions still recorded nothing, and every question in the mode paid for that+// mechanism. The gate is the session ENUMERATING — the caller wrote a batch, or the+// planner declared a count/list — not a mode flag, and not a candidate's separators:+// measured the same day, with the gate reading a list-shaped CANDIDATE as a set, a+// FRAMES run took 24 offers (and 8 extra rounds over its baseline) on questions+// whose answer is one number.+func TestOfferContinuationIsGatedOnTheQuestionsShape(t *testing.T) {+ value := &SessionState{+ Attempts: 4,+ DeadlineLeft: 90,+ ParentState: State{State: []Variable{{ID: 0, Type: "entity", Candidate: strPtr("白马坡")}}},+ }+ if value.offerContinuation() {+ t.Fatal("a single-value question must not be offered extra turns")+ }+ if len(value.Messages) != 0 {+ t.Fatal("no offer message may be appended for a value question")+ }+ // And the route at the floor finalizes it, exactly as the mode's turn count+ // alone used to.+ if got := value.route(); got != routeFinalize {+ t.Fatalf("route at the floor on a value question = %v, want routeFinalize", got)+ }++ // A candidate that only LOOKS like a list is not a set: the measured FRAMES+ // table held `Grace's、High、Falls、Colonial、Creek` — one waterfall's name cut at+ // its separators — under a slot typed "dataset", and the offer built on it is+ // what ran that benchmark eight rounds long.+ prose := &SessionState{+ Attempts: 4,+ DeadlineLeft: 90,+ ParentState: State{State: []Variable{{ID: 0, Type: "dataset", Candidate: strPtr("Grace's、High、Falls")}}},+ }+ if prose.offerContinuation() {+ t.Fatal("a separator-bearing candidate under a scalar type must not buy extra turns")+ }++ // A count-typed slot is the other half of the tell — the shape the 三国+ // enumeration direction's own table carries (slot 0 [count]).+ counting := &SessionState{+ Attempts: 4,+ DeadlineLeft: 90,+ ParentState: State{State: []Variable{{ID: 0, Type: "count", Candidate: strPtr("10")}}},+ }+ if !counting.offerContinuation() {+ t.Fatal("a count slot must be offered the turn")+ }++ // And the tell that survives contact: a caller-written batch, even on a table+ // whose slots say nothing about a set.+ batched := &SessionState{+ Attempts: 4,+ DeadlineLeft: 90,+ SearchQueries: []string{"关羽 斩 杀 颜良 文丑 华雄 蔡阳"},+ ParentState: State{State: []Variable{{ID: 0, Type: "entity", Candidate: strPtr("白马坡")}}},+ }+ if !batched.offerContinuation() {+ t.Fatal("a session that wrote a batch is enumerating and must be offered the turn")+ }+}++// TestRouteAtTheFloorOffersTheModelTheDecision pins the routing wiring: the floor+// routes to another model turn WITH the offer attached, and the cap routes to+// finalize with nothing attached.+func TestRouteAtTheFloorOffersTheModelTheDecision(t *testing.T) {+ s := enumerationSession(4, 90)+ if got := s.route(); got != routeRunAction {+ t.Fatalf("route at the floor = %v, want routeRunAction (the model decides)", got)+ }+ if len(s.Messages) != 1 {+ t.Fatalf("messages = %d, want the offer appended", len(s.Messages))+ }++ capped := enumerationSession(8, 90)+ if got := capped.route(); got != routeFinalize {+ t.Fatalf("route at the cap = %v, want routeFinalize", got)+ }++ // A terminal reply still ends the session immediately: the offer is for turns+ // that have not already concluded.+ done := enumerationSession(4, 90)+ done.Done = true+ if got := done.route(); got != routeEnd {+ t.Fatalf("route after a terminal reply = %v, want routeEnd", got)+ }+ // ...and a spent clock finalizes rather than offering.+ tight := enumerationSession(4, turnAskFloorS-1)+ if got := tight.route(); got != routeFinalize {+ t.Fatalf("route without clock = %v, want routeFinalize", got)+ }+}++func strPtr(s string) *string { return &s }++// TestUnreadPoolExcerptShowsTextTheSessionHasNotSeen pins the pool read.+//+// The pool is text the round has already paid for, and a session only ever sees+// the parts its own queries returned: everything else sits in hand, unread. That+// is where members are lost without anyone noticing — measured (2026-09-15,+// 三国演义/关羽): the passage naming 管亥 was fetched into the round's evidence and+// no session ever named it, because nothing had shown it.+func TestUnreadPoolExcerptShowsTextTheSessionHasNotSeen(t *testing.T) {+ kb := &Kbinfos{}+ kb.Admit(func(p *PoolAdmitter) {+ p.Add(map[string]any{"chunk_id": "seen01", "content": "关公温酒斩华雄,其酒尚温。"})+ p.Add(map[string]any{"chunk_id": "offtopic", "content": "那张角本是个不第秀才,因入山采药,遇一老人,碧眼童颜,手执藜杖,唤角至一洞中,以天书三卷授之。"})+ p.Add(map[string]any{"chunk_id": "unread01", "content": "关公大怒,拍马舞刀,直取管亥,管亥措手不及,被关公一刀劈于马下。"})+ })+ s := &SessionState{+ KB: kb,+ Direction: "关羽斩杀了哪些有名有姓的人物",+ SearchQueries: []string{"关公 斩 管亥"},+ RetrievedEvidenceIDs: []string{"seen01"},+ }+ got := s.unreadPoolExcerpt()+ if !strings.Contains(got, "unread01") {+ t.Fatalf("excerpt = %q, want the unread passage this session's own words point at", got)+ }+ if strings.Contains(got, "华雄") {+ t.Fatalf("excerpt = %q, want the passage this session has seen skipped", got)+ }+ // The passage that says the most the session has not seen is NOT the passage to+ // show: "most novel" and "about this question" are anti-correlated, and the+ // first version of this delivered nothing but chapter headings, 曹操's youth and+ // 张角 receiving the book. Only the session's own words tell the two apart.+ if strings.Contains(got, "张角") {+ t.Fatalf("excerpt = %q, want a passage the session's own words exclude", got)+ }+ // One excerpt per session: across the first two runs of this mechanism it+ // delivered twelve excerpts and none of them carried a member the record was+ // missing, so it stays a last resort rather than a per-turn routine.+ if again := s.unreadPoolExcerpt(); again != "" {+ t.Fatalf("a second excerpt was offered: %q", again)+ }+}++// TestSetShapedFollowsThePlannersDeclaration pins the half of the gate that reads the+// table: what the planner TYPED, never what a candidate looks like. A list-shaped+// candidate under a scalar type is prose that happens to contain separators —+// measured (2026-09-15, FRAMES) a slot typed "dataset" carried+// `Grace's、High、Falls、Colonial、Creek`, ONE waterfall's name, and the permissive+// reading of it is how a "how much shorter" record came to say "enumerated+// members: 16" and how a `[count]` slot on a "how many times larger" question once+// bought 24 continuation offers.+func TestSetShapedFollowsThePlannersDeclaration(t *testing.T) {+ value := State{State: []Variable{{ID: 0, Type: "entity", Candidate: strPtr("白马坡")}}}+ if SetShaped(value) {+ t.Error("a single-value table asks for no set")+ }+ counted := State{State: []Variable{{ID: 0, Type: "count", Candidate: strPtr("10")}}}+ if !SetShaped(counted) {+ t.Error("a count slot asks for a set")+ }+ quantity := State{State: []Variable{{ID: 0, Type: "number", Candidate: strPtr("2452 feet")}}}+ if SetShaped(quantity) {+ t.Error("a number slot is a value, not a set")+ }+ prose := State{State: []Variable{{ID: 0, Type: "dataset", Candidate: strPtr("Grace's、High、Falls")}}}+ if SetShaped(prose) {+ t.Error("the table must not be read through a candidate's separators")+ }+}++// TestSetDirectionIsSeededWithTheMethod pins WHERE the enumeration method is delivered — in the+// seed, before the first turn — and, just as important, WHO gets it: only a table that declared the+// whole ENUMERATION shape (see EnumerationShaped).+//+// Its first instruction — propose more candidates than you expect — is a decision taken before the+// first query: measured (2026-09-16, 三国/关羽) the same question answered eighteen members with the+// method in the seed of its `[count]` table and fourteen when it arrived a turn later. But the same+// instruction on a question whose answer is ONE value sends the session looking for members it does+// not need: measured (2026-09-16, FRAMES — 4 questions in flight, 300s deadline) the SetShaped-only+// gate seeded the value questions that merely contain a count and the run finished 0.833 with two+// timeouts against 0.875 with none.+func TestSetDirectionIsSeededWithTheMethod(t *testing.T) {+ loader := StringPromptLoader{"action_set": "SET / COUNT directions — the member list IS the work"}++ // A table that declared count/set/list AND a NAME-carrying slot AND its act words: the+ // enumeration strategy, seeded with the method and the corpus queries those words render into+ // (see ScanPatterns) — the seed is where the session is told to ask the corpus for the act,+ // which is the one thing its memory cannot do.+ declared := State{State: []Variable{+ {ID: 0, Type: "count", Candidate: strPtr("18"), Terms: []string{"斩", "杀"}, Subject: "关羽|云长"},+ {ID: 1, Type: "dataset"},+ }}+ got := setProtocolFor(declared, loader)+ if !strings.Contains(got, "关羽.*斩|云长.*斩") {+ t.Errorf("a direction with declared act words must be seeded with their queries, got %q", got)+ }+ if !strings.Contains(got, "SET / COUNT directions") {+ t.Errorf("the method must travel with them, got %q", got)+ }++ // And now the three ways a table FAILS to be an enumeration, each of which must leave a value+ // question alone. A count with no names: a count of EVENTS, which the planner declares act+ // words for as well ("how many times had Brazil won the World Cup").+ countsOnly := State{State: []Variable{+ {ID: 0, Type: "count", Candidate: strPtr("5"), Terms: []string{"won", "trophy"}, Subject: "Brazil"},+ }}+ if got := setProtocolFor(countsOnly, loader); got != "" {+ t.Errorf("a count of events must not be seeded with the member method, got %q", got)+ }+ // Names with no count/set/list: a question about ONE named thing that also declared act words+ // (the shape a multi-hop value question takes).+ namesOnly := State{State: []Variable{+ {ID: 0, Type: "person", Terms: []string{"wrote", "published"}, Subject: "the writer"},+ {ID: 1, Type: "date"},+ }}+ if got := setProtocolFor(namesOnly, loader); got != "" {+ t.Errorf("a value question holding one name must not be seeded with the member method, got %q", got)+ }+ // A count with no act words: nothing was declared to enumerate.+ counted := State{State: []Variable{{ID: 0, Type: "count", Candidate: strPtr("18")}}}+ if got := setProtocolFor(counted, loader); got != "" {+ t.Errorf("a count with no declared act words must not be seeded, got %q", got)+ }+ // `number` is the planner's label for a measured QUANTITY, and it typed the same+ // question both ways on two runs of 2026-09-16: not a seed trigger, and exactly+ // what the batch path exists for.+ quantity := State{State: []Variable{{ID: 0, Type: "number", Candidate: strPtr("14")}}}+ if got := setProtocolFor(quantity, loader); got != "" {+ t.Errorf("a number-typed table must not be seeded, got %q", got)+ }+ // Nor is a candidate's punctuation a declaration: a list-shaped candidate under a+ // scalar type is how the permissive gate seeded 44 of 67 FRAMES sessions.+ prose := State{State: []Variable{{ID: 1, Type: "entity", Candidate: strPtr("孔秀、孟坦")}}}+ if got := setProtocolFor(prose, loader); got != "" {+ t.Errorf("a list-shaped candidate must not seed the method, got %q", got)+ }+ value := State{State: []Variable{{ID: 0, Type: "date", Candidate: strPtr("1858")}}}+ if got := setProtocolFor(value, loader); got != "" {+ t.Errorf("a single-value direction must not be seeded, got %q", got)+ }+ // A loader that predates the template yields nothing rather than panicking (see+ // loadOptionalPrompt): its sessions run exactly as they did before it existed.+ if got := setProtocolFor(counted, StringPromptLoader{}); got != "" {+ t.Errorf("a loader without action_set must yield nothing, got %q", got)+ }+}++// TestUnseededSetDirectionIsHandedTheMethodOnItsFirstBatch pins the second delivery:+// the CALLER's own batch, appended once, mid-session.+//+// It is the path for a set direction whose table was typed `number` rather than+// `count` — and the signal has no measured false positives: over one FRAMES run of 20+// questions the caller wrote zero batches, while one 三国 question wrote eighteen.+func TestUnseededSetDirectionIsHandedTheMethodOnItsFirstBatch(t *testing.T) {+ method := "SET / COUNT directions — the member list IS the work"+ newSession := func(queries ...string) *SessionState {+ return &SessionState{+ SearchQueries: queries,+ EnumerationProtocol: method,+ Messages: []schema.Message{*schema.ToolMessage(`{"passages": []}`, "call_1")},+ }+ }++ // An English question never writes a batch, so it is never handed the method.+ english := newSession("What was the age difference between Mike Tyson and Trevor Berbick")+ english.appendBatchProtocol(true)+ if strings.Contains(english.Messages[0].Content, method) {+ t.Fatalf("tool message = %q, want no method on a question that wrote no batch", english.Messages[0].Content)+ }+ if english.BatchProtocolShown {+ t.Fatal("the method must not be marked shown when it was not appended")+ }++ // A caller-written batch IS the tell (space-separated CJK, the shape the model+ // actually writes — see callerBatch).+ chinese := newSession("关羽 斩 杀 颜良 文丑 华雄 蔡阳")+ chinese.appendBatchProtocol(true)+ if !strings.Contains(chinese.Messages[0].Content, method) {+ t.Fatalf("tool message = %q, want the method appended", chinese.Messages[0].Content)+ }+ // Once per session: method repeated is prompt noise.+ before := chinese.Messages[0].Content+ chinese.appendBatchProtocol(true)+ if chinese.Messages[0].Content != before {+ t.Fatal("the method must be appended at most once")+ }+ // A turn that ran no tool call cannot carry it either.+ quiet := newSession("关羽 斩 颜良")+ quiet.appendBatchProtocol(false)+ if quiet.BatchProtocolShown {+ t.Fatal("a turn that ran no tool call must not carry the method")+ }+}++// TestAppendRecordLineSkipsValueDirections pins the line's gate: it carries a set's+// to-do list, and on a value question every field of it is empty (`members=0 |+// probed-reached=0`) while it still costs a recomputation and a line of prompt on+// every turn. Measured (2026-09-15, FRAMES): 214 such lines across 20 questions,+// on a benchmark whose baseline run carried none.+func TestAppendRecordLineSkipsValueDirections(t *testing.T) {+ kb := &Kbinfos{}+ kb.Admit(func(p *PoolAdmitter) {+ p.Add(map[string]any{"chunk_id": "c1", "content": "prose"})+ })+ payload := `{"passages": []}`+ s := &SessionState{+ KB: kb,+ ParentState: State{State: []Variable{+ {ID: 0, Type: "date", Candidate: strPtr("1858")},+ {ID: 1, Type: "number", Candidate: strPtr("2452")},+ }},+ Messages: []schema.Message{*schema.ToolMessage(payload, "call_1")},+ }+ s.appendRecordLine(true)+ if got := s.Messages[len(s.Messages)-1].Content; got != payload {+ t.Fatalf("tool message = %q, want it untouched on a value direction", got)+ }+ // The record itself is still computed and kept: the continuation ask reads it,+ // and only the model-facing line is skipped.+ if s.Record.Pool != 1 {+ t.Fatalf("record pool = %d, want the record still computed", s.Record.Pool)+ }+}diff --git a/internal/rag/advanced_rag/harness/tool_executor.go b/internal/rag/advanced_rag/harness/tool_executor.goindex 172366221d..e490685c36 100644--- a/internal/rag/advanced_rag/harness/tool_executor.go+++ b/internal/rag/advanced_rag/harness/tool_executor.go@@ -99,6 +99,35 @@ func NewSearchExecutor(deps SearchDeps, req RunRequest) ToolExecutor {return &searchExecutor{deps: deps, req: req}}+// RunPattern executes ONE completeness pattern and returns the windows it matched, already+// narrowed (see ScanPatterns / RunCompletenessPass).+//+// It goes through the same grep path a retrieve call uses, so a pattern is treated as a+// pattern: its operands are recalled on their own (patternRecallTopN — a pattern's recall+// must not stop at a ranking's head, see that constant's measurement), the pattern decides+// which candidates are windows (matchGrepPattern), and the windows come back narrowed to+// the match (GrepOutCharsPerChunk / GrepOutTotalChars). The runtime runs this itself+// because the same queries handed to the model as a list went unrun (see+// RunCompletenessPass).+func (e *searchExecutor) RunPattern(ctx context.Context, pattern string) []map[string]any {+ pattern = strings.TrimSpace(pattern)+ if pattern == "" {+ return nil+ }+ chunks, _ := GrepSearch(ctx, e.deps, SearchParams{+ Question: pattern,+ // A pattern is an expression for the MATCHER, not for the engine (see+ // GrepSearch): recall gets the operands, the pattern stays here and decides.+ Keywords: strings.Join(GrepPatternOperands(pattern), " "),+ TopN: patternRecallTopN,+ KbIDs: e.req.DatasetIDs,+ // The pass asks about the ACTOR and the ACT WORDS, never about candidate names+ // (see SearchParams.SkipReachLedger).+ SkipReachLedger: true,+ })+ return chunks+}+// Execute implements ToolExecutor for the wired tools. Tools whose port has not// landed are classified, not errored: they report MISS (the tool is valid, this// call reached nothing) so the model falls back to a different tool instead of@@ -521,12 +550,90 @@ func argString(args map[string]any, key string) string {// Claim pseudo-chunks BYPASS this cap: Python's _claim_prefetch appends them// directly to kbinfos["chunks"] (:755), and the cap check (:657) only guards// _admit_evidence's regular chunks.-const evidencePoolCap = 120+//+// 200, not Python's 120. The 120 was sized for a consumer that no longer exists —+// the round-level sweep that rendered the WHOLE pool into one prompt, where the cap+// and that prompt's budget were the same number. Nothing renders the pool whole any+// more (the SCA reads a ranked 60-chunk view, the session seed injects a bounded+// digest, the draft is bounded), so the cap is a storage-discipline number again —+// and on an enumeration it is the NEXT ceiling rather than a prompt limit. Measured+// (2026-09-14, fixrecall): a round of batch name probing ended at 117 chunks, three+// below the cap, with the question's members still arriving; at 200 the same shape+// reached seventeen. Measured here (2026-09-16, 三国/关羽): the run's own line+// `pool at the cap 120 but the batch asked about "管亥"; admitting the passage that+// reaches it (pool 121, novelty slack 1/40)` — the tail members' passages are what+// the cap refuses.+const evidencePoolCap = 200// The cap check and its "pool FULL" line now live on PoolAdmitter.Full, where// the pool lock is held (see kbinfos.go): the check must not read len(Chunks)// while another session appends.+// probeTerms returns the terms of a PROBE query — the caller's own alternation,+// "荀正|管亥|车胄" — and nil for every other query shape.+//+// An alternation is the one place the model states explicitly WHICH individuals+// it is asking about, which makes its per-term result the batch's answer and not+// just another search: a name that comes back empty is a name this corpus does+// not carry, and a name that comes back with a window is a member. Both facts are+// destroyed by a cap that drops the window (see PoolAdmitter.Novelty), so a probe+// is exempt while a topic query is not — a topic query names no individuals, so+// its hits compete for the cap like everything else.+func probeTerms(q string) []string {+ if !strings.Contains(q, "|") {+ return nil+ }+ return GrepTermsFromQuery(q)+}++// namedTermsOf is the call's own statement of WHICH individuals it asked about:+// the terms of the queries it carried, deduped and capped.+//+// Every shape the model uses lands here — an alternation ("A|B|C"), a+// space-separated list inside one string, or a list of query strings — because+// GrepTermsFromQuery already reads all three. That is the point: the seat+// mechanism is attached to the FACT that the call named terms, not to a syntax+// the model may never write. Measured (2026-09-15): fifteen calls, every one of+// them naming people, zero of them using `|` — a `|`-triggered mechanism fires+// never.+//+// The cap (GrepTermsMax) bounds the seat pass, which runs one cheap keyword+// search per unreached term; the caller logs how many named terms were dropped+// so the ceiling is visible in the run.+//+// The terms are the caller's OWN WORDS (GrepWordsFromQuery), not the CJK windows+// the locate step derives from them: a window is our guess at where a name can be+// found, and probing one spends a retrieval on a fragment nobody asked about+// (measured 2026-09-15: 羽斩 / 杀的 / 的有 / 领名, fourteen of twenty probes+// "absent").+func namedTermsOf(queries []string) []string {+ var out []string+ seen := make(map[string]bool, len(queries)*2)+ for _, q := range queries {+ for _, t := range GrepWordsFromQuery(q) {+ // A PIECE OF A PATTERN is a phrase, not a name: "关公.*斩" asks how a+ // deed is written, and probing 关公 or 斩 as a name spends a retrieval+ // on a word nobody proposed as a member (measured: a pass built from+ // such fragments probed 羽斩 / 杀的 / 的有 and reported fourteen+ // "absent"). An alternation of PLAIN words ("华雄|颜良|蔡阳") is exactly+ // what the seat exists for, so the test is pattern OPERATORS, not "|".+ if strings.ContainsAny(t, ".*+?()[]{}^$\\") {+ continue+ }+ low := strings.ToLower(strings.TrimSpace(t))+ if low == "" || seen[low] {+ continue+ }+ seen[low] = true+ out = append(out, t)+ if len(out) >= GrepTermsMax {+ return out+ }+ }+ }+ return out+}+// search runs one retrieval call for a tool invocation.//// Python's retrieve/search_chunks both funnel into tools/search.py, differing@@ -553,11 +660,21 @@ func (e *searchExecutor) search(ctx context.Context, name string, args map[strinif e.deps.KB == nil {e.deps.KB = &Kbinfos{}}+ logger := searchLogger(e.deps)// Max queries per tool call mirrors Python action_session.execute_tool// (_arg_query_list): retrieve=3, search_chunks=2. grep_search/grep_chunks// are Go-internal tools (Python exposes no such session tool), so they are// left uncapped.+ //+ // A direction assembling a SET/COUNT raises the ceiling. There the call's+ // queries are facets of one list rather than rephrasings of one question, so+ // a dropped query is not a spared repeat — it is a member nobody searched.+ // The flag is set by the same gate that hands the model the set method (see+ // Kbinfos.MarkSetDirection), so a VALUE direction keeps the small cap it had.+ // Measured (2026-09-16, medium mode): every call asked 3-5 queries against+ // these caps, nine calls were cut, and the names the run then failed to+ // record had been named only in the dropped ones.maxQ := len(queries)switch name {case "retrieve":@@ -565,8 +682,26 @@ func (e *searchExecutor) search(ctx context.Context, name string, args map[strincase "search_chunks":maxQ = 2}+ if e.deps.KB.IsSetDirection() {+ switch name {+ case "retrieve":+ maxQ = 6+ case "search_chunks":+ maxQ = 4+ }+ }+ // The full list is kept: maxQ bounds how many EXPENSIVE queries run, but the+ // terms of the dropped ones still get their own cheap seat below. Dropping a+ // list item silently (as this cut used to) drops the individuals it named+ // before any retrieval happens — measured (2026-09-15): a run named 29+ // queries, 8 never executed, and those 8 included the only mentions of the+ // names it was missing.+ allQueries := queries+ dropped := 0if len(queries) > maxQ {queries = queries[:maxQ]+ dropped = len(allQueries) - maxQ+ logger.Printf("[Action Session] %s asked %d quer(ies); running %d and taking named-term seats for the rest.", name, len(allQueries), maxQ)}var payload []any@@ -578,6 +713,15 @@ func (e *searchExecutor) search(ctx context.Context, name string, args map[strin// pool — a per-call snapshot of it (Python's `kb_seen`) is exact only while// nothing can interleave, and another session appending makes it stale.seen := map[string]bool{}+ // reached accumulates every candidate the call's own searches returned. It is+ // what the seat pass below asks "which of the named terms did this retrieval+ // NOT reach?" — the question whose answer is a search of its own.+ var reached []map[string]any+ // Per-call reach notes: what each query reached term by term, and which of its+ // terms nothing reached (see ToolOutcome.Note / GrepReachLine). A batch of+ // names is exactly where this matters — the passages alone cannot say whether+ // a member was missing or simply never asked about.+ var reachNotes []string// Claim-first, MUTUALLY EXCLUSIVE (Python _run_search: _claim_prefetch +// _CLAIM_PREFETCH_EXCLUSIVE): when claim rows hit, their verbatim evidence// IS the answer material — chunk snippets on top would echo the same@@ -686,11 +830,26 @@ func (e *searchExecutor) search(ctx context.Context, name string, args map[strinif len(chunks) == 0 {continue}- // Only the first snippetsPerQuery (4) hits of each query are considered- // (Python cands[:_SNIPPETS_PER_QUERY]).- if len(chunks) > snippetsPerQuery {- chunks = chunks[:snippetsPerQuery]+ // Computed on the LEG's candidates, not on the payload below: the payload is+ // truncated to the per-query snippet cap, and a term whose window was cut is+ // still a term this query reached.+ if line := GrepReachLine(q, chunks, ReachTermsOf(q)); line != "" {+ reachNotes = append(reachNotes, line)+ }+ // Only the first snippetsPerQueryFor(mode) hits of each query are considered+ // (Python cands[:_SNIPPETS_PER_QUERY]) — EXCEPT for a query that NAMES+ // terms, which keeps one candidate per named term first. The locate step+ // hands back one window per term, and a flat cut is what turns a six-name+ // call into "the names that matched most": the rarest lose their seat to the+ // ones the ranking already preferred.+ limit := snippetsPerQueryFor(e.req.ThinkingMode)+ if n := len(namedTermsOf([]string{q})); n > limit {+ limit = n+ }+ if len(chunks) > limit {+ chunks = chunks[:limit]}+ reached = append(reached, chunks...)// Admittance mirrors _admit_evidence exactly: per-call dedup by chunk// id, the chunk ID as the evidence reference (Python's `ids` holds ids,// not pool positions), and only chunks NEW to the shared pool appended@@ -705,10 +864,17 @@ func (e *searchExecutor) search(ctx context.Context, name string, args map[strin// LIVE pool once per call; compute it once per batch under the same// critical section.covered := p.ClaimCoveredIDs()+ // The cap exemption for this batch, derived from the probe's own terms+ // (see probeTerms / PoolAdmitter.Novelty): a full pool still takes the+ // window that answers a name nothing in the pool has reached yet,+ // because that window is the batch's result rather than one more+ // passage.+ novel := p.Novelty(probeTerms(q))for _, c := range chunks {// Python _admit_evidence early-stops at the top once the shared pool- // reaches the cap, BEFORE the per-call dedup.- if p.Full() {+ // reaches the cap, BEFORE the per-call dedup — except for the probe+ // window above, which IS the answer the caller asked for.+ if p.Full() && !novel.Admits(c) {continue}cid := ChunkIDOf(c)@@ -737,6 +903,100 @@ func (e *searchExecutor) search(ctx context.Context, name string, args map[strine.deps.KB.MergeDocAggs(aggs)}+ // ── Named-term seats ─────────────────────────────────────────────────────+ // The individuals this call named are honored IN FULL, independent of the+ // expensive leg's own limits: one cheap keyword search per term the call's+ // retrievals did not reach, each keeping the window that carries it (see+ // TermSeat). The terms of list items maxQ dropped are included — "the model+ // already said the name" should mean the name was looked for, whatever+ // syntax carried it and whichever leg ran.+ //+ // A term that reaches nothing is RECORDED, not retried (Kbinfos.RecordProbedAbsent):+ // "this corpus has no 荀正" is the answer to a probe, and it is what the+ // rewrite reads before choosing its next angle.+ if named := namedTermsOf(allQueries); len(named) > 0 {+ seatScope := []string(nil)+ if name != "search_chunks" {+ // doc_scope is a retrieve-family argument; search_chunks takes none+ // (see the query loop above).+ seatScope = toolDocScope(args)+ }+ unreached := termsNotCarried(reached, named)+ // Every named term is PROBED (recall: its own window enters the pool), but+ // only the ones the call proposed as ITEMS are RECORDED — the ledger is read+ // back as the session's to-do list, and a question's words are not members+ // it could record (see probeItemsOf).+ proposed := probeItemsOf(allQueries)+ seats, absent := 0, 0+ for _, term := range unreached {+ record := proposed[strings.ToLower(term)]+ seat, found := TermSeat(ctx, e.deps, SearchParams{+ KbIDs: e.req.DatasetIDs,+ DocScope: seatScope,+ }, term)+ if !found {+ absent+++ if record {+ e.deps.KB.RecordProbedAbsent(term)+ }+ continue+ }+ // The seat's ids are collected here and recorded AFTER the batch: the+ // ledger has its own lock, so writing it inside the critical section+ // would be safe, but keeping the pool lock to pool work costs nothing+ // and leaves the locking order (pool → ledger) exercised in one place+ // only.+ var seatedIDs []string+ e.deps.KB.Admit(func(p *PoolAdmitter) {+ // A seat is a probe's answer, so it is exempt from the pool cap+ // on the same grounds as the weave above (see Novelty).+ novel := p.Novelty([]string{term})+ for _, c := range seat {+ if p.Full() && !novel.Admits(c) {+ continue+ }+ cid := ChunkIDOf(c)+ if cid != "" && seen[cid] {+ continue+ }+ if cid != "" {+ seen[cid] = true+ }+ evidenceIDs = append(evidenceIDs, cid)+ payload = append(payload, passageFromChunk(c))+ if p.Add(c) {+ newChunks+++ }+ if cid != "" {+ seatedIDs = append(seatedIDs, cid)+ }+ seats+++ }+ })+ // A seat IS the proof that this name is a member: record the pair+ // (term, passage) so the round's record holds the members with their+ // evidence, not just the count — again only for a proposed item.+ if record {+ for _, cid := range seatedIDs {+ e.deps.KB.RecordReachedTerm(term, cid)+ }+ }+ }+ if len(unreached) > 0 {+ logger.Printf("[Action Session] named-term seats: %d named, %d unreached, %d seat(s) admitted, %d absent.",+ len(named), len(unreached), seats, absent)+ }+ }++ // A cut is a fact about the SEARCH, not about the corpus, and the model cannot+ // read it off the passages: every dropped query's terms were seated above, so+ // a name it asked about still came back, while the query's own wording never+ // ran. Say so, so a dropped facet is re-asked instead of forgotten.+ if dropped > 0 {+ reachNotes = append(reachNotes, fmt.Sprintf(+ "only %d of this call's %d queries were searched — %d were dropped, and a dropped query's own wording was never run (the terms it named were each probed on their own, so a term that came back is proven to occur). Re-ask a dropped one directly if you need its wording.",+ maxQ, len(allQueries), dropped))+ }if len(payload) == 0 {return ToolOutcome{Payload: []any{},@@ -744,6 +1004,7 @@ func (e *searchExecutor) search(ctx context.Context, name string, args map[strinStatus: StatusMiss,Reason: ReasonNoDoc,Metrics: map[string]any{"hits": 0, "new_evidence": 0},+ Note: strings.Join(reachNotes, "\n"),}, nil}// Zero new evidence (every hit was already in the pool) is REDUNDANT, not@@ -760,6 +1021,7 @@ func (e *searchExecutor) search(ctx context.Context, name string, args map[strinStatus: StatusRedundant,Reason: ReasonNone,Metrics: map[string]any{"hits": len(payload), "new_evidence": 0},+ Note: strings.Join(reachNotes, "\n"),}, nil}return ToolOutcome{@@ -768,6 +1030,7 @@ func (e *searchExecutor) search(ctx context.Context, name string, args map[strinStatus: StatusOK,Reason: ReasonNone,Metrics: map[string]any{"hits": len(payload), "new_evidence": newChunks},+ Note: strings.Join(reachNotes, "\n"),}, nil}diff --git a/internal/rag/advanced_rag/harness/tool_executor_test.go b/internal/rag/advanced_rag/harness/tool_executor_test.goindex ed444bf245..127d86abe9 100644--- a/internal/rag/advanced_rag/harness/tool_executor_test.go+++ b/internal/rag/advanced_rag/harness/tool_executor_test.go@@ -454,6 +454,53 @@ func TestEvidencePoolCapStopsAdmitting(t *testing.T) {}}+// TestEvidencePoolCapExemptsTheProbeWindow pins the cap EXEMPTION at the tool+// boundary: a FULL pool still takes the window that answers a name the pool has+// not reached, because that window is the probe's own RESULT.+//+// The contrasting case is the test above: the same full pool, a query that is not+// a probe, and nothing is admitted. Both behaviours are needed — the exemption is+// what keeps a name batch from turning a found member into "nothing new", and the+// cap is what keeps everything else from bloating storage.+func TestEvidencePoolCapExemptsTheProbeWindow(t *testing.T) {+ pre := make([]map[string]any, 0, evidencePoolCap)+ for i := 0; i < evidencePoolCap; i++ {+ pre = append(pre, map[string]any{"chunk_id": fmt.Sprintf("pre-%d", i), "content": "already pooled prose"})+ }+ deps, kb := newTestSearchDeps(&stubRetriever{chunks: []map[string]any{+ {"chunk_id": "c1", "content": "荀正 被关公一刀斩于马下"},+ }})+ kb.Chunks = pre+ ex := NewSearchExecutor(deps, RunRequest{DatasetIDs: []string{"kb1"}})++ oc, err := ex.Execute(context.Background(), "retrieve", map[string]any{"query": "车胄|荀正|管亥"})+ if err != nil {+ t.Fatalf("retrieve: %v", err)+ }+ if oc.Status != StatusOK {+ t.Errorf("status = %s, want %s (the probe window answered an unanswered name)", oc.Status, StatusOK)+ }+ if len(kb.Chunks) != evidencePoolCap+1 {+ t.Errorf("kb.Chunks = %d, want %d (one seat for the unanswered name)", len(kb.Chunks), evidencePoolCap+1)+ }+ if len(oc.Payload) != 1 {+ t.Errorf("payload = %d, want the probe's window", len(oc.Payload))+ }++ // The same probe again: the pool now carries the window, so the cap is back+ // in charge and the outcome is REDUNDANT, not another seat.+ oc, err = ex.Execute(context.Background(), "retrieve", map[string]any{"query": "车胄|荀正|管亥"})+ if err != nil {+ t.Fatalf("retrieve (second): %v", err)+ }+ if len(kb.Chunks) != evidencePoolCap+1 {+ t.Errorf("kb.Chunks = %d, want the pool to stay at %d", len(kb.Chunks), evidencePoolCap+1)+ }+ if oc.Status != StatusMiss && oc.Status != StatusRedundant {+ t.Errorf("status = %s, want MISS/REDUNDANT on the repeated probe", oc.Status)+ }+}+// TestWebSearchAdmitsToPool pins the web_search parity fix: web results merge// into the SAME shared evidence pool as corpus hits (Python _exec_web_search →// _admit_evidence), so downstream formalize/compose can cite them, and the@@ -874,3 +921,186 @@ func TestPassageFromChunkTruncatesContent(t *testing.T) {t.Errorf("passage = %v", p)}}++// seatRetriever answers a search by its query string, normalized to the DISTINCT+// tokens it carries: the engine receives "question keywords" (a seat search sends+// the same term twice), so a fixture must not depend on how that string is+// assembled.+type seatRetriever struct {+ byQuery map[string][]map[string]any+ calls []string+}++func (s *seatRetriever) Retrieve(_ context.Context, req RetrieveRequest) ([]map[string]any, error) {+ s.calls = append(s.calls, req.Query)+ seen := map[string]bool{}+ var tokens []string+ for _, tok := range strings.Fields(req.Query) {+ if seen[tok] {+ continue+ }+ seen[tok] = true+ tokens = append(tokens, tok)+ }+ return s.byQuery[strings.Join(tokens, " ")], nil+}++// TestNamedTermSeatsReachTermsThePhraseSearchMissed pins the seat pass: every+// individual a call NAMES gets its own cheap keyword search, so the names the+// call's own phrase queries cannot reach still arrive with a passage.+//+// Three things are asserted, and each one is a measured loss from the 2026-09-15+// run: (a) a name the phrase query's ranking stranded (荀正) still gets a+// passage; (b) a name in a list item maxQ DROPPED (杨龄 — the run left 8 of 29+// named queries unexecuted) still gets one; (c) a name nothing reaches is+// recorded as probed-and-absent rather than silently dropped (庞德).+func TestNamedTermSeatsReachTermsThePhraseSearchMissed(t *testing.T) {+ famous := map[string]any{"chunk_id": "c-famous", "content": "关羽 斩华雄 于马下。"}+ rare := map[string]any{"chunk_id": "c-rare", "content": "荀正 引军来战,关羽一刀斩之。"}+ predicate := map[string]any{"chunk_id": "c-pred", "content": "云长 斩颜良 于白马,文丑心怯。"}+ third := map[string]any{"chunk_id": "c-third", "content": "杨龄 出马,关羽手起刀落。"}+ r := &seatRetriever{byQuery: map[string][]map[string]any{+ // The phrase batch returns ONLY the passage matching several names at+ // once — the ranking that strands the rare ones.+ "关羽 斩华雄 荀正": {famous},+ "关羽 斩颜良": {},+ "关羽": {famous},+ "斩华雄": {famous},+ "荀正": {rare},+ "斩颜良": {predicate},+ "杨龄": {third},+ // 庞德 reaches nothing anywhere: the corpus does not carry it.+ "庞德": {},+ }}+ deps, kb := newTestSearchDeps(r)+ ex := NewSearchExecutor(deps, RunRequest{DatasetIDs: []string{"kb1"}})++ oc, err := ex.Execute(context.Background(), "retrieve", map[string]any{+ "query": []any{"关羽 斩华雄 荀正", "关羽 斩颜良", "杨龄", "庞德"},+ })+ if err != nil {+ t.Fatalf("retrieve: %v", err)+ }+ pool := map[string]bool{}+ for _, c := range kb.Chunks {+ pool[ChunkIDOf(c)] = true+ }+ for _, want := range []string{"c-famous", "c-rare", "c-pred", "c-third"} {+ if !pool[want] {+ t.Errorf("pool lacks %s: %v — a named term lost its seat (phrase ranking, maxQ cut, or the flat per-query cap)", want, pool)+ }+ }+ if oc.Status != StatusOK {+ t.Errorf("status = %s, want %s (the seats are new evidence)", oc.Status, StatusOK)+ }+ absent := kb.ProbedAbsentTerms()+ if !containsString(absent, "庞德") {+ t.Errorf("ProbedAbsent = %v, want 庞德 recorded: a probe that reaches nothing is a fact about the corpus, not a failed lookup", absent)+ }+ if containsString(absent, "荀正") || containsString(absent, "杨龄") {+ t.Errorf("ProbedAbsent = %v: a term that got a seat must not be recorded as unreached", absent)+ }+}++func containsString(list []string, want string) bool {+ for _, s := range list {+ if s == want {+ return true+ }+ }+ return false+}++// TestSearchOutcomeCarriesTheReachLine pins the delivery: the per-term reach the+// grep leg computes reaches the MODEL through ToolOutcome.Note (rendered behind+// the payload by the session tool node), not only the log.+//+// This is what makes a batch probe iterable: "华雄|荀正|管亥" either answers all+// three or says which of them nothing reached, and the next call can be aimed.+func TestSearchOutcomeCarriesTheReachLine(t *testing.T) {+ deps, _ := newTestSearchDeps(&stubRetriever{chunks: []map[string]any{+ {"chunk_id": "c1", "content": "云长手起一刀,斩华雄于马下"},+ }})+ ex := NewSearchExecutor(deps, RunRequest{DatasetIDs: []string{"kb1"}})++ oc, err := ex.Execute(context.Background(), "retrieve", map[string]any{"query": "华雄|荀正|管亥"})+ if err != nil {+ t.Fatalf("retrieve: %v", err)+ }+ if oc.Note == "" {+ t.Fatal("Note is empty: the reach of a batch probe must reach the model")+ }+ for _, want := range []string{"华雄(1)", "荀正", "管亥", "NOT reached by this query"} {+ if !strings.Contains(oc.Note, want) {+ t.Errorf("Note %q missing %q", oc.Note, want)+ }+ }++ // A query with nothing to report on carries no note at all.+ plain, err := ex.Execute(context.Background(), "retrieve", map[string]any{"query": "云长"})+ if err != nil {+ t.Fatalf("retrieve (plain): %v", err)+ }+ if strings.HasPrefix(plain.Note, "[reach]") && !strings.Contains(plain.Note, "carry:") {+ t.Errorf("Note = %q, want no half-formed reach line", plain.Note)+ }+}++// TestSetDirectionWidensTheQueryBudget pins the recall rule a SET/COUNT direction+// buys, and it is deliberately written with NEUTRAL queries: nothing here depends+// on a corpus, a language, or a name.+//+// A direction assembling a SET asks the corpus about one facet per query, so a+// dropped query is a member nobody searched rather than a spared repeat. The+// executor therefore runs more of them once the direction has declared itself+// (Kbinfos.MarkSetDirection — set by the same gate that hands the model the set+// method), and when it still cannot run them all it SAYS so in the tool result,+// because a silent cut is invisible in the passages.+//+// Measured (2026-09-16, medium mode): every call asked 3-5 queries against caps of+// 2 (search_chunks) / 3 (retrieve), nine calls were cut, and the members the run+// then failed to record had been named only in the dropped ones.+func TestSetDirectionWidensTheQueryBudget(t *testing.T) {+ queries := []string{"term one", "term two", "term three", "term four"}++ // A value direction keeps the small cap — and reports the cut.+ valueDeps, _ := newTestSearchDeps(&stubRetriever{chunks: []map[string]any{{"content": "hit", "chunk_id": "c1"}}})+ value := &stubRetriever{chunks: []map[string]any{{"content": "hit", "chunk_id": "c1"}}}+ valueDeps.Backend = value+ valueEx := NewSearchExecutor(valueDeps, RunRequest{DatasetIDs: []string{"kb1"}})+ oc, err := valueEx.Execute(context.Background(), "retrieve", map[string]any{"query": queries})+ if err != nil {+ t.Fatalf("retrieve: %v", err)+ }+ if !strings.Contains(oc.Note, "only 3 of this call's 4 queries were searched") {+ t.Errorf("Note = %q, want it to name the dropped query", oc.Note)+ }++ // The same call on a SET direction runs every query and reports no cut.+ setDeps, setKB := newTestSearchDeps(&stubRetriever{chunks: []map[string]any{{"content": "hit", "chunk_id": "c1"}}})+ dropped := &stubRetriever{chunks: []map[string]any{{"content": "hit", "chunk_id": "c1"}}}+ setDeps.Backend = dropped+ setKB.MarkSetDirection()+ if !setKB.IsSetDirection() {+ t.Fatal("MarkSetDirection did not declare the direction")+ }+ setEx := NewSearchExecutor(setDeps, RunRequest{DatasetIDs: []string{"kb1"}})+ oc2, err := setEx.Execute(context.Background(), "retrieve", map[string]any{"query": queries})+ if err != nil {+ t.Fatalf("retrieve (set): %v", err)+ }+ if strings.Contains(oc2.Note, "queries were searched") {+ t.Errorf("Note = %q, want no cut on a set direction", oc2.Note)+ }+ if len(dropped.requests) <= len(value.requests) {+ t.Errorf("set direction searched %d backend request(s), value direction %d: the set direction must search MORE of the caller's own queries",+ len(dropped.requests), len(value.requests))+ }++ // A nil pool is not a set direction, and asking is safe.+ var noPool *Kbinfos+ if noPool.IsSetDirection() {+ t.Error("a nil pool must not report a set direction")+ }+ noPool.MarkSetDirection()+}diff --git a/internal/rag/advanced_rag/harness/tool_search.go b/internal/rag/advanced_rag/harness/tool_search.goindex 33406f6130..671bce18b7 100644--- a/internal/rag/advanced_rag/harness/tool_search.go+++ b/internal/rag/advanced_rag/harness/tool_search.go@@ -730,28 +730,42 @@ func runSearch(ctx context.Context, deps SearchDeps, p SearchParams, opts search// "[<kind>] Searching the knowledge base for …" through the run's logger,// which Rag wraps with the think-log forwarder (see think_log.go). Emitting// one here as well would show the same search twice in the reasoning block.- chunks, err := deps.Backend.Retrieve(ctx, RetrieveRequest{- Query: effectiveQuery,- DatasetIDs: targetIDs,- DocScope: docScope,- TopN: topN,- TopK: intOrDef(deps.TopK, DefaultTopK),- RerankCandidatesCount: max(intOrDef(deps.RerankCandidatesCount, DefaultRerankCandidatesCount), topN),- SimilarityThreshold: &opts.threshold,- // VectorSimilarityWeight carries the VECTOR weight verbatim (Python- // vector_similarity_weight); the canvas adapter's keyword-weight- // inversion does NOT apply to this field. DisableVectorLeg mirrors- // Python passing embd_mdl=None (no dense leg at all).- VectorSimilarityWeight: &opts.weight,- DisableVectorLeg: opts.disableVector,- TenantID: deps.TenantID,- MetaDataFilter: deps.MetaDataFilter,- RankFeature: rankFeature,- ExcludeCompiled: opts.excludeCompiled,- })+ // D5: a retrieval that FAILS is retried once before the query is written off. The+ // failure this exists for is the upstream one: measured (2026-09-16) two queries of a+ // run answered `SILICONFLOW API error: 503 Service Unavailable … Model service+ // overloaded`, and the passages those queries would have returned were simply gone+ // from a question whose whole work is coverage. One retry costs one round trip on the+ // failure path only, and it is a retry of the same request (no re-planning, nothing+ // cached, nothing narrowed yet).+ retrieve := func() ([]map[string]any, error) {+ return deps.Backend.Retrieve(ctx, RetrieveRequest{+ Query: effectiveQuery,+ DatasetIDs: targetIDs,+ DocScope: docScope,+ TopN: topN,+ TopK: intOrDef(deps.TopK, DefaultTopK),+ RerankCandidatesCount: max(intOrDef(deps.RerankCandidatesCount, DefaultRerankCandidatesCount), topN),+ SimilarityThreshold: &opts.threshold,+ // VectorSimilarityWeight carries the VECTOR weight verbatim (Python+ // vector_similarity_weight); the canvas adapter's keyword-weight+ // inversion does NOT apply to this field. DisableVectorLeg mirrors+ // Python passing embd_mdl=None (no dense leg at all).+ VectorSimilarityWeight: &opts.weight,+ DisableVectorLeg: opts.disableVector,+ TenantID: deps.TenantID,+ MetaDataFilter: deps.MetaDataFilter,+ RankFeature: rankFeature,+ ExcludeCompiled: opts.excludeCompiled,+ })+ }+ chunks, err := retrieve()if err != nil {// Go-only line: Python lets the retriever's exception propagate untagged.- logger.Printf("[%s] retrieval failed: %v", opts.logLabel, err)+ logger.Printf("[%s] retrieval failed: %v — retrying once.", opts.logLabel, err)+ chunks, err = retrieve()+ }+ if err != nil {+ logger.Printf("[%s] retrieval failed twice: %v", opts.logLabel, err)return nil, nil}@@ -877,6 +891,236 @@ func BM25Search(ctx context.Context, deps SearchDeps, p SearchParams) ([]map[str})}+// patternRecallTopN is how wide ONE operand's recall goes when the query is a+// STRUCTURAL pattern — `关公.*斩`, a question about how a thing is written rather+// than about a name.+//+// A pattern is a LOCATOR, and a locator is only as good as the ground it is given:+// recalling ten passages answers "does this pattern occur in those ten", not+// "where does it occur". Measured (fixrecall2, 2026-09-15): every pattern query in+// a run reported `10 candidate(s)` — the tool's own topN per operand — so+// `关公.*斩|云长.*斩` could only ever match inside ~40 passages of a corpus where+// the subject alone occurs in a large part of the text. That is the one retrieval+// path that does not depend on the model already knowing the name, and it was+// looking through a keyhole.+//+// It is the widest per-operand number the pipeline already uses elsewhere+// (SCAViewCap), and only the MATCHED windows travel onwards — the grep output cap+// (GrepOutTotalChars) still bounds what the model pays for.+//+// 200, after the measurement that shows 60 is the binding constraint rather than the+// corpus: in one 三国/关羽 run the operands' own match counts were 云长(111) 斩(97) 关公(79)+// 关云长(33) 关羽(7) 杀(143), so a pattern's recall stopped before the corpus did and ~50 of+// 云长's passages were never matched against the pattern at all — the windows that hold the+// members nobody has named are exactly the ones past a ranking's head. The number is a+// RECALL bound on candidates that are only matched and narrowed (the model sees the+// matched windows, capped by GrepOutTotalChars), so widening it costs retrieval, not+// prompt — and a pattern whose operand hits the bound is now logged rather than silently+// truncated (see retrieveGrepCandidates).+const patternRecallTopN = 200++// isStructuralPattern reports whether a query asks for structure (any-wildcard+// pattern) rather than listing terms: `关公.*斩` does, `华雄|颜良` does not.+func isStructuralPattern(query string) bool {+ return strings.Contains(query, ".*") || strings.Contains(query, ".+")+}++// callerBatch reports whether the caller wrote a BATCH — several terms in one+// query — rather than a sentence.+//+// Three shapes count, and they are the three the model actually writes: an+// alternation (`华雄|颜良|文丑`), a pattern (`关公.*斩`, whose operands are the+// terms), and whitespace-separated CJK pieces (`关羽 斩 华雄 颜良 文丑 蔡阳`).+// The last one is the reason this predicate exists rather than a `|` test: across+// the runs of 2026-09-15 the model wrote that exact batch shape and never wrote a+// `|`, so a `|`-only gate kept the per-term seat allocation permanently off.+//+// A sentence is excluded on purpose, in both languages: an English question+// splits on whitespace but carries no CJK, and a Chinese question has no+// whitespace to split on. Those are the questions that are not enumerating+// anything, and they must not pay for per-term searches.+func callerBatch(query string) bool {+ if strings.Contains(query, "|") || grepPatternOf(query) != nil {+ return true+ }+ pieces := 0+ for _, field := range strings.Fields(query) {+ if !hasCJK(field) {+ continue+ }+ pieces+++ if pieces >= 2 {+ return true+ }+ }+ return false+}++// retrieveGrepCandidates fetches the candidate set the locate step then narrows.+//+// One ranked search answers "what does this query match", which is the wrong+// question for an alternation. "车胄|庞德|成何|夏侯存|荀正|管亥|杨龄" asks WHICH of+// these the corpus carries, and a single top-N hands nearly every seat to the+// passages that match many of the terms at once. Measured on that exact+// seven-name probe (2026-09-14): ten chunks came back carrying 庞德 / 成何 /+// 于禁, and NOT ONE chunk carrying 车胄, 荀正, 管亥 or 杨龄 — four members the+// corpus does hold. They never reached the pool, and the round answered four+// short while the probe itself had done its job.+//+// So an alternation searches each term on its own, and the results are woven+// term-by-term, best hit first. The caller's per-query cap then keeps ONE hit+// per term before it keeps a second hit for any single term — which is the+// shape an enumeration needs: one passage per name, and a name that comes back+// empty is a name the corpus does not carry. That empty answer is the point of+// the probe, so it is returned, not filled with the hits the other terms found.+//+// The weave is bounded by the terms (GrepTermsMax) and by each search's own+// TopN, and the narrowing stage's char budget still decides how much of the+// woven set survives.+//+// The trigger is the CALLER's BATCH, not the `|` character. Measured over the+// runs of 2026-09-15: the model wrote `关羽 斩 华雄 颜良 文丑 蔡阳` — a batch of+// names separated by spaces, with no `|` anywhere in the run — so a `|`-only+// trigger left this whole function dead code while the batches it was written+// for went to a single ranked top-N. A batch is an alternation, a pattern, or two+// or more CJK pieces separated by whitespace; a sentence in either language is+// none of those, which is what keeps the extra searches off the questions that+// are not enumerating anything.+func retrieveGrepCandidates(+ ctx context.Context,+ deps SearchDeps,+ bp SearchParams,+ query string,+ terms []string,+) ([]map[string]any, []map[string]any) {+ if !callerBatch(query) || len(terms) < 2 {+ return BM25Search(ctx, deps, bp)+ }++ perTerm := make([][]map[string]any, 0, len(terms))+ aggs := make([]map[string]any, 0, len(terms))+ perTopN := bp.TopN+ if isStructuralPattern(query) && perTopN < patternRecallTopN {+ perTopN = patternRecallTopN+ }+ for _, term := range terms {+ // The term alone is the query: on a keyword leg one rare token is the+ // strongest query there is, and the rest of the alternation can only+ // dilute it.+ sub := bp+ sub.Question = term+ sub.Keywords = term+ sub.TopN = perTopN+ chunks, docAggs := BM25Search(ctx, deps, sub)+ if isStructuralPattern(query) && len(chunks) >= perTopN {+ // A pattern is a LOCATOR over what the keyword leg recalled, so a full page means+ // it was matched against a TRUNCATED candidate set: matches past this bound are not+ // "absent from the corpus", they were never looked at. Said out loud because the+ // difference decides whether a member the pattern did not show is a corpus fact or+ // a ceiling (see patternRecallTopN for the measurement).+ searchLogger(deps).Printf("[Grep search] operand %q filled its recall bound (%d passage(s)); matches beyond it were not matched against the pattern.", term, perTopN)+ }+ perTerm = append(perTerm, chunks)+ aggs = append(aggs, docAggs...)+ // A term searched ON ITS OWN is the caller's probe of ONE individual, so+ // a passage that carries it is a confirmed member with its evidence —+ // recorded as such, because the round needs the members (and the passages+ // behind them), not just the number of chunks it holds.+ //+ // Except when the caller IS the runtime: the completeness pass searches the+ // actor and the act words, which are not names and must not enter the record's+ // to-do list (see SearchParams.SkipReachLedger).+ if !bp.SkipReachLedger {+ for _, c := range chunks {+ if strings.Contains(strings.ToLower(ChunkTextOf(c)), strings.ToLower(term)) {+ deps.KB.RecordReachedTerm(term, ChunkIDOf(c))+ break+ }+ }+ }+ }++ seen := make(map[string]bool)+ out := make([]map[string]any, 0, len(terms))+ for depth := 0; ; depth++ {+ any := false+ for _, chunks := range perTerm {+ if depth >= len(chunks) {+ continue+ }+ any = true+ c := chunks[depth]+ if id := ChunkIDOf(c); id != "" {+ if seen[id] {+ continue+ }+ seen[id] = true+ }+ out = append(out, c)+ }+ if !any {+ break+ }+ }+ // One line, only for a batch — this is the fingerprint that says the per-term+ // seats were actually allocated, so a run can be read for whether the trigger+ // fired at all (the failure mode this replaced was a mechanism that never ran).+ searchLogger(deps).Printf("[Grep search] batch of %d term(s): each searched on its own, %d candidate(s) woven",+ len(terms), len(out))+ return out, aggs+}++// ProbeSeatTopN bounds how many candidates one term's seat search takes before+// the window is picked: a seat exists to carry the name, not to rank it.+const ProbeSeatTopN = 3++// TermSeat runs ONE cheap keyword search for a single named term and returns the+// passage that carries it, narrowed to that term's own window, or (nil, false)+// when nothing reached it.+//+// This is the retrieval unit an enumeration needs, and it is deliberately not a+// query SYNTAX: the caller's terms may arrive as an alternation ("A|B|C"), as a+// space-separated list inside one string, or as a list of query strings, and the+// seat is the same thing in all three cases. What it replaces is asking for+// several individuals at once: one ranked search hands its seats to the passages+// that match MANY of the named terms, so the rarest name — the reason the call+// was made — is the one that loses. Measured (2026-09-15): a run named 29+// queries, only 21 were executed (maxQ), every session query's candidates were+// cut to one flat per-query cap, and the answer stopped at twelve members with+// the rare names missing while ES had returned 30-64 candidates per query.+//+// The term alone is the query, on the keyword leg only: no vector leg, no+// compiled expansion, no model call — a few hundred milliseconds, which is what+// lets the caller afford one per named term.+//+// The boolean is the OTHER half of the answer: false means this corpus reached+// nothing for that term, which is a fact about the corpus the run must keep+// (Kbinfos.RecordProbedAbsent) rather than a failed lookup to retry.+func TermSeat(ctx context.Context, deps SearchDeps, base SearchParams, term string) ([]map[string]any, bool) {+ term = strings.TrimSpace(term)+ if term == "" {+ return nil, false+ }+ sub := base+ sub.Question = term+ sub.Keywords = term+ sub.TopN = ProbeSeatTopN+ sub.UseCompiled = false+ chunks, _ := BM25Search(ctx, deps, sub)+ if len(chunks) == 0 {+ return nil, false+ }+ res := NarrowByTerms(chunks, []string{term}, nil, term,+ NarrowContext{Before: 1, After: 0}, GrepOutCharsPerChunk, GrepOutTotalChars)+ if len(res.Kept) > 0 {+ return res.Kept[:1], true+ }+ // The keyword leg returned candidates that do not carry the term: on a+ // keyword leg that is the corpus answering "not here", so the seat is empty+ // rather than filled with the nearest passages.+ return nil, false+}+// GrepSearch mirrors Python grep_search: a keyword-first locate// that runs bm25_search and then narrows the prose candidates to the term-grep// window (regex locate + short line-context, like Python's _narrow_by_terms).@@ -901,6 +1145,32 @@ func GrepSearch(ctx context.Context, deps SearchDeps, p SearchParams) ([]map[strreturn nil, nil}terms := GrepTermsFromQuery(query)+ pattern := grepPatternOf(query)+ if pattern != nil {+ // The operands of a pattern ARE its recall terms (see GrepPatternOperands):+ // the phrase reading of the same string would treat "关公.*斩" as one clause+ // and lose half of it.+ terms = GrepPatternOperands(query)+ }+ // The WEAVE searches the caller's own WORDS; `terms` above is the LOCATOR's+ // list, and for an unbroken CJK clause it is a set of two-rune windows (see+ // GrepWordsFromQuery).+ //+ // A window searched on its own spends a retrieval on a fragment nobody+ // proposed — and, because a term searched on its own records what it reached,+ // it also entered the reach ledger. The session then reads that ledger back as+ // its to-do list. Measured (2026-09-15): the batch `三国演义 关羽过五关斩六将+ // 六将姓名` searched 国演 / 羽过 / 过五 / 五关 / 关斩 / 斩六 / 六将, and the `[record]`+ // line the session was told to trust read `FOUND BUT NOT RECORDED=三国、演义、+ // 关羽、五关…` while the six names that question was actually missing were not+ // on it at all.+ //+ // A pattern keeps its operands: those are already the caller's words, and its+ // recall needs the long ones (`关公.*斩` searches 关公 and 斩).+ weave := terms+ if pattern == nil {+ weave = GrepWordsFromQuery(query)+ }// Python then delegates to bm25_search with an explicit keywords hint// (search.py:grep_search): `hint = keywords if keywords else " ".join(terms)`.// A long question buries its proper nouns under stopwords; without the hint@@ -914,9 +1184,20 @@ func GrepSearch(ctx context.Context, deps SearchDeps, p SearchParams) ([]map[strhint = strings.Join(terms, " ")}bp := p- bp.Question = query- bp.Keywords = hint- chunks, docAggs := BM25Search(ctx, deps, bp)+ if grepPatternOf(query) != nil {+ // A pattern is an expression for the MATCHER, not for the engine: handed+ // over, `|` and `.*` become either literals to escape or syntax of their+ // own, and a batch probe that the engine echoes back empty is then read as+ // "the corpus does not carry it". So recall gets the OPERANDS, which is+ // what a keyword leg can actually search for, and the pattern stays here+ // and decides which of the candidates are evidence.+ bp.Question = strings.Join(terms, " ")+ bp.Keywords = bp.Question+ } else {+ bp.Question = query+ bp.Keywords = hint+ }+ chunks, docAggs := retrieveGrepCandidates(ctx, deps, bp, query, weave)// Python: `if not chunks or not terms: return res` (search.py:grep_search).if len(chunks) == 0 || len(terms) == 0 {return chunks, docAggs@@ -934,6 +1215,36 @@ func GrepSearch(ctx context.Context, deps SearchDeps, p SearchParams) ([]map[strreturn chunks, docAggs}+ // A query that carries pattern syntax is read as a PATTERN and matched against+ // the candidates the keyword leg returned (see matchGrepPattern): `A|B` is how+ // a batch of names is asked about, `A.*B` is how the way a thing was done is+ // asked about, and neither can be expressed by locating terms one at a time.+ // The pattern itself never leaves this function — the engine only ever saw the+ // operands — so `|` and `.*` are operators here rather than characters somebody+ // has to escape.+ if pattern != nil {+ kept, matched := matchGrepPattern(prose, pattern, contextCharBudget, GrepOutTotalChars)+ if matched == 0 {+ // The pattern matched nothing in what was reached: keep the raw+ // candidates so evidence is not dropped, and SAY what happened — a+ // silent return is how "the pattern did not occur here" gets read as+ // "the corpus does not carry it".+ logGrepReach(logger, query, chunks, terms)+ return chunks, docAggs+ }+ out := make([]map[string]any, 0, len(table)+len(kept))+ out = append(out, table...)+ out = append(out, kept...)+ chars := 0+ for _, c := range out {+ chars += len(ChunkTextOf(c))+ }+ logger.Printf("[Grep search] pattern %q matched %d/%d candidate(s) -> %d chunk(s), %.1fK chars.",+ trunc(query, 80), matched, len(prose), len(out), float64(chars)/1000.0)+ logGrepReach(logger, query, chunks, terms)+ return out, docAggs+ }+res := NarrowByTerms(prose, terms, nil, query, NarrowContext{Before: 1, After: 0},GrepOutCharsPerChunk, GrepOutTotalChars)kept := res.Keptdiff --git a/internal/rag/advanced_rag/harness/tool_search_test.go b/internal/rag/advanced_rag/harness/tool_search_test.goindex ce6815c18f..e09123c59d 100644--- a/internal/rag/advanced_rag/harness/tool_search_test.go+++ b/internal/rag/advanced_rag/harness/tool_search_test.go@@ -1279,3 +1279,216 @@ func TestResolveDocScopeIntersectsExplicitScopeWithSession(t *testing.T) {t.Fatalf("scope = %v, want [sess1] (explicit scope must be ceilinged by the session scope)", got)}}++// TestGrepSearchMatchesPatternOverKeywordCandidates pins the integration: the+// keyword leg samples the corpus, and the PATTERN decides which of those+// candidates are evidence — each returned as the clause around its match.+//+// The two properties a term-locate pass cannot give: a candidate the pattern does+// not match is not evidence whatever its retrieval score (c3), and the match is+// reported with the sentence that carries it rather than the whole chunk.+func TestGrepSearchMatchesPatternOverKeywordCandidates(t *testing.T) {+ long := strings.Repeat("前情提要。", 80) + "华雄出马,关公温酒斩之。" + strings.Repeat("余者不表。", 80)+ r := &stubRetriever{chunks: []map[string]any{+ {"chunk_id": "c1", "content": long},+ {"chunk_id": "c2", "content": "荀正 引军来战,被云长一刀斩于马下。"},+ {"chunk_id": "c3", "content": "曹操引军回许都,不在话下。"},+ }}+ deps, _ := newTestSearchDeps(r)++ got, _ := GrepSearch(context.Background(), deps, SearchParams{Question: "华雄|荀正|管亥"})+ if len(got) != 2 {+ t.Fatalf("got %d chunk(s), want 2: only the candidates the pattern matches are evidence", len(got))+ }+ ids := map[string]bool{}+ for _, c := range got {+ ids[ChunkIDOf(c)] = true+ }+ if !ids["c1"] || !ids["c2"] || ids["c3"] {+ t.Errorf("kept %v, want c1+c2 and NOT c3 (a candidate the pattern does not match is not evidence)", ids)+ }+ for _, c := range got {+ if ChunkIDOf(c) != "c1" {+ continue+ }+ if n := len([]rune(ChunkTextOf(c))); n > 200 {+ t.Errorf("c1 window = %d runes, want the clause around the match, not the whole %d-rune chunk", n, len([]rune(long)))+ }+ }++ // Nothing matched: the raw candidates are returned so evidence is never+ // dropped (and the reach line says what happened).+ none, _ := GrepSearch(context.Background(), deps, SearchParams{Question: "杨龄|夏侯存"})+ if len(none) != 3 {+ t.Errorf("no-match grep returned %d chunk(s), want all 3 raw candidates kept", len(none))+ }+}++// TestPatternNeverReachesTheEngine pins the invariant that makes `|` and `.*`+// usable at all: recall is given the pattern's OPERANDS, and the pattern itself is+// applied here.+//+// Handing the pattern to a keyword leg is what turned a batch probe into a silent+// "the corpus does not carry it": the engine either escapes `|`/`.*` into+// literals or reads them as its own syntax, and an empty result is then+// indistinguishable from an absent fact.+func TestPatternNeverReachesTheEngine(t *testing.T) {+ r := &stubRetriever{chunks: []map[string]any{+ {"chunk_id": "c1", "content": "关公马快,早赶上文丑,脑后一刀,斩于马下。"},+ }}+ deps, _ := newTestSearchDeps(r)++ for _, q := range []string{"华雄|荀正|管亥", "关公.*斩"} {+ GrepSearch(context.Background(), deps, SearchParams{Question: q})+ for _, req := range r.requests {+ for _, bad := range []string{"|", ".*", ".+"} {+ if strings.Contains(req.Query, bad) {+ t.Errorf("query %q handed %q to the engine (request %q): pattern syntax must stay on this side", q, bad, req.Query)+ }+ }+ }+ }+ // And the recall that WAS issued is the operands, so the engine is still+ // asked about every alternative.+ joined := ""+ for _, req := range r.requests {+ joined += " " + req.Query+ }+ for _, want := range []string{"华雄", "荀正", "管亥", "关公", "斩"} {+ if !strings.Contains(joined, want) {+ t.Errorf("no request carried %q; recall must be issued per operand (%q)", want, joined)+ }+ }+}++// TestPerTermSearchRecordsConfirmedMembers pins that the weave's per-term search+// doubles as the member record: a term searched ON ITS OWN that comes back with a+// passage is a confirmed member with its evidence.+func TestPerTermSearchRecordsConfirmedMembers(t *testing.T) {+ r := &stubRetriever{chunks: []map[string]any{+ {"chunk_id": "c-yan", "content": "荀正 引军来战,被云长一刀斩于马下。"},+ }}+ deps, kb := newTestSearchDeps(r)++ GrepSearch(context.Background(), deps, SearchParams{Question: "荀正|管亥"})+ got := kb.ReachedTerms()+ if len(got) != 1 || got[0].Term != "荀正" {+ t.Fatalf("ReachedTerms = %+v, want 荀正 recorded with the passage that carries it", got)+ }+ if got[0].ChunkID != "c-yan" {+ t.Errorf("recorded chunk = %q, want the passage the term's own search returned", got[0].ChunkID)+ }+}++// TestPatternRecallIsPerOperandAndWide pins the LOCATOR fix: a structural pattern+// ("关公.*斩") asks the engine about each of its operands, at a width that gives+// the pattern ground to match in.+//+// The pattern used to be only a FILTER: the legs' own topN (10 for `retrieve`)+// decided what it could ever see, so a query about how a deed is written could+// match inside ten passages, and reported per-term reach over those ten. That is+// the one retrieval path that does not depend on the model already knowing the+// name it is looking for — and it was looking through a keyhole.+func TestPatternRecallIsPerOperandAndWide(t *testing.T) {+ answer := []map[string]any{{"chunk_id": "c1", "content": "关公勒马,一刀斩之"}}++ // Structural pattern: one search per operand, each WIDE.+ wide := &stubRetriever{chunks: answer}+ deps, _ := newTestSearchDeps(wide)+ GrepSearch(context.Background(), deps, SearchParams{+ Question: "关公.*斩|云长.*斩", TopN: 10, KbIDs: []string{"kb1"},+ })+ if len(wide.requests) < 2 {+ t.Fatalf("requests = %d, want one per operand", len(wide.requests))+ }+ for _, r := range wide.requests {+ if r.TopN < patternRecallTopN {+ t.Errorf("operand %q recalled TopN=%d, want >= %d", r.Query, r.TopN, patternRecallTopN)+ }+ }++ // An alternation of NAMES keeps the leg's own topN: a rare name's top ten is+ // enough, and widening there would only cost the engine.+ narrow := &stubRetriever{chunks: answer}+ depsNames, _ := newTestSearchDeps(narrow)+ GrepSearch(context.Background(), depsNames, SearchParams{+ Question: "华雄|荀正", TopN: 10, KbIDs: []string{"kb1"},+ })+ if len(narrow.requests) == 0 {+ t.Fatal("no requests: the alternation must still search per name")+ }+ for _, r := range narrow.requests {+ if r.TopN != 10 {+ t.Errorf("name probe %q recalled TopN=%d, want the leg's own 10", r.Query, r.TopN)+ }+ }+}++// TestCallerBatchRecognisesTheBatchTheModelWrites pins the weave's trigger.+//+// The per-term seat allocation exists for the batches the model writes, and over+// the runs of 2026-09-15 it wrote them with SPACES: `关羽 斩 华雄 颜良 文丑 蔡阳`,+// never once with `|`. A trigger keyed on `|` therefore left the whole mechanism+// dead code while precisely those batches went to a single ranked top-N — the+// ranking that hands nearly every seat to the passages matching the most terms at+// once, which is how four names the corpus carries came back with nothing.+func TestCallerBatchRecognisesTheBatchTheModelWrites(t *testing.T) {+ for _, q := range []string{+ "关羽 斩 华雄 颜良 文丑 蔡阳",+ "华雄|颜良|文丑",+ "关公.*斩|云长.*斩",+ } {+ if !callerBatch(q) {+ t.Errorf("callerBatch(%q) = false, want the batch recognised", q)+ }+ }+ // A sentence is not a batch, in either language: that is what keeps the extra+ // searches off the questions that are not enumerating anything.+ for _, q := range []string{+ "三国演义中,关羽杀了多少有姓名的人物?",+ "What was the outcome of the battle at Red Cliffs?",+ "关羽",+ } {+ if callerBatch(q) {+ t.Errorf("callerBatch(%q) = true, want a sentence left on the single search", q)+ }+ }+}++// TestProbeItemsAreTheCallersOwnWords pins the reach ledger's reading of a call.+//+// The ledger is read back as the session's to-do list ("probed, came back with a+// passage, not recorded"), so it may only hold what the call PROPOSED as items —+// the pieces of a batch, or a query that is one word. Measured (2026-09-15): the+// line read `FOUND BUT NOT RECORDED=三国、演义、关羽、五关…+15` in a run whose+// sessions were missing six members, none of which was on the list, because the+// windows an unbroken clause decomposes into had been probed AND recorded.+func TestProbeItemsAreTheCallersOwnWords(t *testing.T) {+ got := probeItemsOf([]string{"关羽 古城 蔡阳 斩 颜良 文丑 华雄 庞德 荀正", "韩福"})+ for _, want := range []string{"蔡阳", "颜良", "华雄", "荀正", "韩福"} {+ if !got[strings.ToLower(want)] {+ t.Errorf("probeItemsOf missed the proposed item %q", want)+ }+ }+ // A one-rune verb is stripped as a term edge, not proposed as an item.+ if got["斩"] {+ t.Error("a single-rune fragment must not count as a proposed item")+ }++ // A question is not a proposal, and an unbroken clause yields no item either.+ if items := probeItemsOf([]string{"三国演义中关羽一共杀死多少有姓名的人物"}); len(items) != 0 {+ t.Errorf("a sentence proposed %v as items, want nothing", items)+ }++ // The batch case that produced the junk: the windows of 关羽过五关斩六将 must+ // not appear, while the caller's own words do.+ batch := probeItemsOf([]string{"三国演义 关羽过五关斩六将 六将姓名"})+ for _, window := range []string{"国演", "演义", "羽过", "过五", "关斩", "斩六"} {+ if batch[window] {+ t.Errorf("window %q must never reach the ledger", window)+ }+ }+ if !batch["三国演义"] {+ t.Error("the caller's own word 三国演义 must be a candidate item")+ }+}diff --git a/internal/rag/advanced_rag/member_rollcall.go b/internal/rag/advanced_rag/member_rollcall.gonew file mode 100644index 0000000000..7dbe89bcba--- /dev/null+++ b/internal/rag/advanced_rag/member_rollcall.go@@ -0,0 +1,357 @@+//+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.+//++package advanced_rag++import (+ "context"+ "fmt"+ "log"+ "strings"+ "time"++ "github.com/cloudwego/eino/schema"++ "ragflow/internal/rag/advanced_rag/harness"+ "ragflow/internal/rag/advanced_rag/slots"+)++// Member roll call: the enumeration's WRITE-BACK, done by the runtime.+//+// Measured (2026-09-16, 三国/关羽): the evidence was never the limit. The corpus holds nineteen named+// kills, the pool held 244 passages, and runs of ONE build answered 18 / 16 / 15 / 14 / 12 members —+// eleven of them the same every single time, the rest a different handful of the other nine. What+// varies is what a session WRITES: each session patched 12-14 names, and the round's union was+// whichever list happened to be longest. Two failures were measured on the way: a session probed a+// name with the verb glued to it (`斩夏侯存`) — the corpus does not word it that way, the probe came+// back empty, and the session read that as "the corpus does not carry this member"; and+// action_set.md's own note says sessions spend every turn searching and patch last, when the budget+// is already gone.+//+// So the write-back stops being a session's memory. The runtime takes the candidates it ALREADY+// holds — the completeness pass's windows (each with the chunk id it came from) and the ledger of+// terms a probe reached (Kbinfos.ReachedTerms) — asks the model about EVERY one of them in ONE call,+// and writes the members itself. The judgement stays the model's: nothing here decides what a kill+// is, or which words mean one. What the model can no longer do is forget to write a member down, or+// skip a candidate in silence — and a verdict names a LINE, so the chunk id always comes from the+// line the runtime handed it, never from the reply.++// MemberRollCallPrompt is the whole instruction: one verdict per line, both lists.+//+// It is written around the QUESTION rather than around any one kind of answer: the same step runs on+// "which awards did X win" and on "who did X kill", so what a line has to do is state a member of+// the set the question asks for — the question itself is in the user message. Nothing here decides+// what counts as a member; that judgement is the model's, and it is the same judgement it makes+// inside a session. What changes is only WHO WRITES IT DOWN.+const MemberRollCallPrompt = "You are given numbered evidence lines from one fixed corpus, each with the chunk id it came from.\n" ++ "For EVERY line decide one thing: does this line itself state a member of the set the question " ++ "asks for — and if it does, what is that member called?\n" ++ "Judge only what the line says, never what you know from elsewhere. A mention that is not a member " ++ "(a plan, a promise, a denial, a pursuit, something that did not happen, somebody else's action, or " ++ "a member the line does not name) is NOT one.\n" ++ "Answer with JSON only, and put EVERY line number in exactly one of the two lists:\n" ++ `{"members": [{"i": <line number>, "name": "<the member the line states>"}], "not_members": [<line numbers>]}` + "\n" ++ "Use the line's own words for the name. Never invent a name, and never answer for a line you were not given."++// rollCallCandidate is one line put in front of the model.+type rollCallCandidate struct {+ ChunkID string+ Quote string+}++// RollCallResult is what one write-back produced, for the run log: how many candidates were asked+// about, how many the model took a position on, and how many members the runtime actually wrote.+type RollCallResult struct {+ Asked int+ Answered int+ Written int+}++// The bounds are the ones the retrieval layer already enforces, restated where they are spent:+// Kbinfos caps the pool and the completeness pass caps its block, so a candidate list built from+// both arrives bounded; rollCallMaxCands keeps ONE prompt to a sane size, and rollCallQuoteChars+// keeps one line to the sentence that names the victim.+const (+ rollCallQuoteChars = 300+ rollCallMaxCands = 150+)++// RollCallMembers asks the model about every candidate the run already holds and writes the members+// it names. It returns nothing and writes nothing when there is no candidate the table does not+// already mention — an empty roll call costs no call at all.+func RollCallMembers(ctx context.Context, deps RAGTools, st *AgenticState, logger *log.Logger) RollCallResult {+ if logger == nil {+ logger = _LOG+ }+ res := RollCallResult{}+ if st == nil || deps.Model == nil || st.KB == nil || len(st.SlotTable.State) == 0 {+ return res+ }+ // Same gate as the completeness pass (see harness.EnumerationShaped): the roll call belongs to the+ // ENUMERATION strategy, so a single-value question — even one that contains a count — pays+ // nothing for it.+ if !harness.EnumerationShaped(st.SlotTable) {+ return res+ }+ // And the stronger gate, which is the one that keeps the step off every question that is not a+ // set: the members go into a slot that ALREADY holds members, so a table whose slots hold values+ // (one name, one date, one number, one phrase) is not enumerated at all and this step spends+ // nothing — not even the call (see rollCallTargetSlot).+ slotID := rollCallTargetSlot(&st.SlotTable)+ if slotID < 0 {+ return res+ }+ cands := rollCallCandidates(st)+ if len(cands) == 0 {+ return res+ }+ res.Asked = len(cands)++ // Bounded like every other single-purpose call in this graph (see RewriteTimeoutS): the answer+ // composition still has to fit inside the request's clock, so this step may not spend it.+ t := min(RollCallTimeoutS, max(10.0, st.RemainingS()-10.0))+ callCtx, cancel := context.WithTimeout(ctx, time.Duration(t*float64(time.Second)))+ defer cancel()+ reply, err := deps.Model.Complete(callCtx, []schema.Message{+ *schema.SystemMessage(MemberRollCallPrompt),+ *schema.UserMessage(rollCallQuestion(st, cands)),+ }, nil)+ if err != nil {+ // A failed call costs the members it would have written, not the answer: the table still+ // holds everything the sessions wrote.+ logger.Printf("[RollCall] %d candidate(s) could not be checked: %v", res.Asked, err)+ return res+ }+ members, answered := parseRollCallVerdicts(reply.Content, cands)+ res.Answered = answered+ if answered < res.Asked {+ // Said out loud because it is the one number that says whether "every line gets a verdict"+ // held: an unjudged line is a candidate nobody looked at, which is the failure this whole+ // step exists to remove.+ logger.Printf("[RollCall] %d of %d candidate(s) got no verdict", res.Asked-answered, res.Asked)+ }+ if len(members) == 0 {+ logger.Printf("[RollCall] %d candidate(s) asked, %d answered, 0 member(s) named", res.Asked, res.Answered)+ return res+ }++ before := len(memberUnion(&st.SlotTable))+ value := slots.Members(members...)+ rendered := slots.Render(value)+ // 1.0, and the number is a statement about the EVIDENCE rather than a claim: every member here+ // was just matched to the line that names it, so the list is accountable in a way a session's+ // prose list is not (see slots.Union for why a member list outranks prose).+ strength := 1.0+ branch := harness.NewState([]harness.Variable{{+ ID: slotID,+ Value: &value,+ Candidate: &rendered,+ CandidateStrength: &strength,+ }}, st.SlotTable.Depth+1, nil)+ if merged := MergeSlotPatch(st.SlotTable, branch); merged != nil {+ st.SlotTable = *merged+ }+ res.Written = len(memberUnion(&st.SlotTable)) - before+ if raised := reconcileCountSlots(&st.SlotTable); len(raised) > 0 {+ logger.Printf("[RollCall] count slot(s) %v set to the enumerated members' size", raised)+ }+ // The answer reads the record, and the record was rendered BEFORE this write-back: refresh it,+ // or the members the roll call just proved would be invisible to the answer that must list them.+ st.KB.Record = RenderSlotRecord(st.SlotTable, st.CollectedAnswer)+ logger.Printf("[RollCall] %d candidate(s) asked, %d answered, %d member(s) written into slot %d",+ res.Asked, res.Answered, res.Written, slotID)+ return res+}++// rollCallCandidates collects what the run already holds and is not in a slot yet: the completeness+// pass's windows, and the terms a probe REACHED (a name whose passage came back — a member with its+// evidence, whatever the session did with it afterwards).+func rollCallCandidates(st *AgenticState) []rollCallCandidate {+ known := map[string]bool{}+ for _, name := range memberUnion(&st.SlotTable) {+ known[strings.ToLower(strings.TrimSpace(name))] = true+ }+ seen := map[string]bool{}+ out := make([]rollCallCandidate, 0, 32)+ add := func(id, quote string) {+ id, quote = strings.TrimSpace(id), strings.TrimSpace(quote)+ if id == "" || quote == "" || seen[id+"\x00"+quote] {+ return+ }+ seen[id+"\x00"+quote] = true+ out = append(out, rollCallCandidate{ChunkID: id, Quote: truncateRunes(quote, rollCallQuoteChars)})+ }+ if block, ok := st.KB.PatternFindings(); ok {+ for _, w := range parseBlockWindows(block) {+ add(w[0], w[1])+ }+ }+ for _, rt := range st.KB.ReachedTerms() {+ name := strings.TrimSpace(rt.Term)+ if name == "" || rt.ChunkID == "" || known[strings.ToLower(name)] {+ continue+ }+ quote := name+ if c := st.KB.ChunkByID(rt.ChunkID); c != nil {+ if text := strings.Join(strings.Fields(harness.ChunkTextOf(c)), " "); text != "" {+ quote = text+ }+ }+ add(rt.ChunkID, quote)+ }+ if len(out) > rollCallMaxCands {+ out = out[:rollCallMaxCands]+ }+ return out+}++// parseBlockWindows reads the windows out of a completeness-pass block, whose lines render as+// ` chunk_id=<id> "<quote>"`.+func parseBlockWindows(block string) [][2]string {+ var out [][2]string+ for _, line := range strings.Split(block, "\n") {+ i := strings.Index(line, "chunk_id=")+ if i < 0 {+ continue+ }+ rest := line[i+len("chunk_id="):]+ end := strings.IndexAny(rest, " \t\"")+ if end <= 0 {+ continue+ }+ q1 := strings.Index(rest, "\"")+ q2 := strings.LastIndex(rest, "\"")+ if q1 < 0 || q2 <= q1 {+ continue+ }+ out = append(out, [2]string{rest[:end], rest[q1+1 : q2]})+ }+ return out+}++// rollCallQuestion renders the call's user message: the question, the actor's declared forms, and+// every candidate on its own numbered line.+func rollCallQuestion(st *AgenticState, cands []rollCallCandidate) string {+ actor := ""+ for _, v := range st.SlotTable.State {+ if s := strings.TrimSpace(v.Subject); s != "" {+ actor = s+ break+ }+ }+ var b strings.Builder+ fmt.Fprintf(&b, "Question: %s\n", st.Question)+ if actor != "" {+ fmt.Fprintf(&b, "Actor (the forms this direction named): %s\n", actor)+ }+ b.WriteString("Evidence lines:\n")+ for i, c := range cands {+ fmt.Fprintf(&b, "[%d] chunk_id=%s \"%s\"\n", i, c.ChunkID, c.Quote)+ }+ b.WriteString("\nAnswer with the JSON object and nothing else.")+ return b.String()+}++// parseRollCallVerdicts turns a reply into members, taking each member's chunk id from the LINE the+// model judged: a verdict only has to get the line number right, so a fabricated citation cannot+// reach the record. answered counts the lines a position was taken on, in either list.+func parseRollCallVerdicts(content string, cands []rollCallCandidate) ([]slots.Member, int) {+ obj, _ := extractJSONObject(content).(map[string]any)+ if obj == nil {+ return nil, 0+ }+ answered := map[int]bool{}+ seenName := map[string]bool{}+ var members []slots.Member+ for _, raw := range rollCallItems(obj["members"]) {+ entry, _ := raw.(map[string]any)+ if entry == nil {+ continue+ }+ i, ok := rollCallInt(entry["i"])+ name := strings.TrimSpace(anyString(entry["name"]))+ if !ok || name == "" || i < 0 || i >= len(cands) {+ continue+ }+ answered[i] = true+ if key := strings.ToLower(name); !seenName[key] {+ seenName[key] = true+ members = append(members, slots.Member{Name: name, ChunkID: cands[i].ChunkID, Quote: cands[i].Quote})+ }+ }+ for _, raw := range rollCallItems(obj["not_members"]) {+ if i, ok := rollCallInt(raw); ok && i >= 0 && i < len(cands) {+ answered[i] = true+ }+ }+ return members, len(answered)+}++// rollCallTargetSlot is the slot the members go into: the member slot that ALREADY holds the most+// members — the enumeration's own list slot, the one the record and the answer read. -1 when the+// table holds no members at all.+//+// The restraint is deliberate, and it is what keeps this step off every other kind of question: a+// table whose slots hold VALUES (a name, a date, a number, a phrase) is not enumerating anything, so+// there is nothing to add to and nothing is written — no prose is replaced, no single answer is+// turned into a list. Whether a table IS enumerating is therefore the model's own earlier decision+// (it wrote members), not a reading of a slot's type here.+func rollCallTargetSlot(table *harness.State) int {+ if table == nil {+ return -1+ }+ best, bestN := -1, -1+ for _, v := range table.State {+ if v.Typed().Kind != slots.KindMembers {+ continue+ }+ if n := len(v.Typed().Names()); n > bestN {+ best, bestN = v.ID, n+ }+ }+ return best+}++// rollCallItems normalises a JSON list, whichever shape the decoder produced for it.+func rollCallItems(v any) []any {+ switch t := v.(type) {+ case []any:+ return t+ case []map[string]any:+ out := make([]any, 0, len(t))+ for _, m := range t {+ out = append(out, m)+ }+ return out+ }+ return nil+}++// rollCallInt reads a line number, which a model may hand back as a number or as a string.+func rollCallInt(v any) (int, bool) {+ switch t := v.(type) {+ case float64:+ return int(t), t == float64(int(t))+ case int:+ return t, true+ case string:+ var n int+ if _, err := fmt.Sscanf(strings.TrimSpace(t), "%d", &n); err == nil {+ return n, true+ }+ }+ return 0, false+}diff --git a/internal/rag/advanced_rag/member_rollcall_test.go b/internal/rag/advanced_rag/member_rollcall_test.gonew file mode 100644index 0000000000..c4d71baf39--- /dev/null+++ b/internal/rag/advanced_rag/member_rollcall_test.go@@ -0,0 +1,203 @@+//+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.+//++package advanced_rag++import (+ "bytes"+ "context"+ "log"+ "strings"+ "testing"++ "github.com/cloudwego/eino/schema"++ "ragflow/internal/rag/advanced_rag/harness"+ "ragflow/internal/rag/advanced_rag/slots"+)++// rollCallModel answers with one canned reply and counts the calls, so a test can assert that the+// roll call did NOT spend a call when it had nothing to ask.+type rollCallModel struct {+ calls int+ reply string+}++func (m *rollCallModel) Complete(_ context.Context, _ []schema.Message, _ []harness.ToolSpec) (*harness.ModelReply, error) {+ m.calls+++ return &harness.ModelReply{Content: m.reply}, nil+}++func memberSlotValue(names ...string) *slots.Value {+ items := make([]slots.Member, 0, len(names))+ for _, n := range names {+ items = append(items, slots.Member{Name: n, ChunkID: "seed-" + n})+ }+ v := slots.Members(items...)+ return &v+}++// TestRollCallWritesWhatTheModelNames pins the write-back the runtime owns: the candidates are the+// evidence the run ALREADY holds (the completeness pass's windows, and the names a probe reached),+// the model answers about every one of them, and the members land in the table whatever a session+// did or forgot.+//+// Measured (2026-09-16, 三国/关羽): runs of one build answered 18 / 16 / 15 / 14 / 12 members with the+// same corpus in hand — the same eleven names every time plus a different handful of the other nine —+// because what varied was what a session patched.+func TestRollCallWritesWhatTheModelNames(t *testing.T) {+ kb := &harness.Kbinfos{}+ kb.StorePatternFindings("## The completeness pass ALREADY RAN for this direction\n\n" ++ "- 关羽.*斩 →\n" ++ " chunk_id=w1 \"云长手起刀落,斩杨龄于马下\"\n" ++ " chunk_id=w2 \"关公所历关隘五处,斩将六员\"\n")+ // A name a probe reached, with the passage that carries it: a member with its evidence,+ // whatever the session did with it.+ kb.Admit(func(p *harness.PoolAdmitter) {+ p.Add(map[string]any{"chunk_id": "w3", "content_with_weight": "只一合被云长砍死"})+ })+ kb.RecordReachedTerm("夏侯存", "w3")++ table := harness.NewState([]harness.Variable{+ {ID: 0, Type: "count", Terms: []string{"斩"}, Subject: "关羽|云长"},+ {ID: 1, Type: "dataset", Value: memberSlotValue("华雄"), Candidate: strPtr("华雄"), CandidateStrength: testFloatPtr(0.9)},+ }, 0, nil)+ st := &AgenticState{Question: "三国演义中,关羽杀了多少有姓名的人物?", KB: kb, SlotTable: table}+ model := &rollCallModel{reply: `{"members": [{"i": 0, "name": "杨龄"}, {"i": 2, "name": "夏侯存"}], "not_members": [1]}`}+ deps := RAGTools{Model: model}+ var buf bytes.Buffer++ res := RollCallMembers(context.Background(), deps, st, log.New(&buf, "", 0))++ if model.calls != 1 {+ t.Fatalf("model calls = %d, want exactly one", model.calls)+ }+ if res.Asked != 3 || res.Answered != 3 || res.Written != 2 {+ t.Errorf("roll call = asked %d / answered %d / written %d, want 3 / 3 / 2", res.Asked, res.Answered, res.Written)+ }+ got := map[string]bool{}+ for _, n := range memberUnion(&st.SlotTable) {+ got[n] = true+ }+ for _, want := range []string{"华雄", "杨龄", "夏侯存"} {+ if !got[want] {+ t.Errorf("members %v, want %q — the roll call's verdicts plus what the slot already held", got, want)+ }+ }+ // The chunk id comes from the LINE the model judged, so a citation cannot be invented.+ for _, v := range st.SlotTable.State {+ if v.ID != 1 {+ continue+ }+ byName := map[string]string{}+ for _, m := range v.Typed().Items {+ byName[m.Name] = m.ChunkID+ }+ if byName["杨龄"] != "w1" || byName["夏侯存"] != "w3" {+ t.Errorf("member evidence = %v, want each name cited by the line it was judged on", byName)+ }+ }+ // The count is derived from the members, so it has to follow them, and the record — which the+ // answer reads — must show what was just written.+ if c := st.SlotTable.State[0].Candidate; c == nil || *c != "3" {+ t.Errorf("count slot = %v, want 3 (the enumerated members' size)", c)+ }+ if !strings.Contains(kb.Record, "杨龄") {+ t.Errorf("record %q does not mention the member the roll call wrote", kb.Record)+ }+ if !strings.Contains(buf.String(), "3 candidate(s) asked, 3 answered, 2 member(s) written") {+ t.Errorf("log = %q, want the accounting line", buf.String())+ }+}++// TestRollCallIgnoresVerdictsForLinesItNeverHandedOver pins the one thing a reply cannot do: cite a+// passage of its own choosing. A verdict names a LINE, and a line number outside the list is dropped.+func TestRollCallIgnoresVerdictsForLinesItNeverHandedOver(t *testing.T) {+ kb := &harness.Kbinfos{}+ kb.StorePatternFindings("- 关羽.*斩 →\n chunk_id=w1 \"云长手起刀落,斩杨龄于马下\"\n")+ table := harness.NewState([]harness.Variable{+ {ID: 0, Type: "count", Terms: []string{"斩"}, Subject: "关羽"},+ {ID: 1, Type: "dataset", Value: memberSlotValue("华雄"), Candidate: strPtr("华雄")},+ }, 0, nil)+ st := &AgenticState{Question: "关羽杀了多少有姓名的人物?", KB: kb, SlotTable: table}+ deps := RAGTools{Model: &rollCallModel{+ reply: `{"members": [{"i": 9, "name": "张凯"}, {"i": 0, "name": "杨龄"}], "not_members": [7]}`,+ }}++ res := RollCallMembers(context.Background(), deps, st, log.New(&bytes.Buffer{}, "", 0))+ if res.Asked != 1 || res.Answered != 1 || res.Written != 1 {+ t.Errorf("roll call = asked %d / answered %d / written %d, want 1 / 1 / 1", res.Asked, res.Answered, res.Written)+ }+ for _, n := range memberUnion(&st.SlotTable) {+ if n == "张凯" {+ t.Error("a verdict for a line that was never handed over was written into the table")+ }+ }+}++// TestRollCallSkipsWhenThereIsNothingToAsk pins that the step costs nothing when the evidence and the+// ledger have nothing the table does not already mention: no candidates, no call.+func TestRollCallSkipsWhenThereIsNothingToAsk(t *testing.T) {+ kb := &harness.Kbinfos{}+ table := harness.NewState([]harness.Variable{+ {ID: 0, Type: "count", Terms: []string{"斩"}, Subject: "关羽"},+ {ID: 1, Type: "dataset", Value: memberSlotValue("华雄"), Candidate: strPtr("华雄")},+ }, 0, nil)+ st := &AgenticState{Question: "关羽杀了多少有姓名的人物?", KB: kb, SlotTable: table}+ model := &rollCallModel{reply: `{"members": [], "not_members": []}`}++ if res := RollCallMembers(context.Background(), RAGTools{Model: model}, st, log.New(&bytes.Buffer{}, "", 0)); res.Asked != 0 {+ t.Errorf("asked = %d, want 0", res.Asked)+ }+ if model.calls != 0 {+ t.Errorf("model calls = %d, want none: an empty roll call must not spend a call", model.calls)+ }+}++// TestRollCallLeavesAValueTableAlone pins the restraint that keeps this step off every question that+// is not enumerating anything: when no slot holds members, nothing is written and no prose is+// replaced by a list. A table whose slots hold VALUES (a name, a date, a number, a phrase) is not+// enumerating, and a single-value answer must stay what it is — which is what makes this step safe on+// the questions that are not sets.+func TestRollCallLeavesAValueTableAlone(t *testing.T) {+ kb := &harness.Kbinfos{}+ kb.StorePatternFindings("- 关羽.*斩 →\n chunk_id=w1 \"云长手起刀落,斩杨龄于马下\"\n")+ prose := "据网文统计共14人:华雄、颜良、文丑……"+ table := harness.NewState([]harness.Variable{+ {ID: 0, Type: "count", Terms: []string{"斩"}, Subject: "关羽"},+ {ID: 1, Type: "dataset", Candidate: &prose, CandidateStrength: testFloatPtr(0.95)},+ }, 0, nil)+ st := &AgenticState{Question: "关羽杀了多少有姓名的人物?", KB: kb, SlotTable: table}+ model := &rollCallModel{reply: `{"members": [{"i": 0, "name": "杨龄"}], "not_members": []}`}++ res := RollCallMembers(context.Background(), RAGTools{Model: model}, st, log.New(&bytes.Buffer{}, "", 0))++ if res.Asked != 0 || res.Written != 0 {+ t.Fatalf("roll call = asked %d / written %d, want nothing: the table holds no members", res.Asked, res.Written)+ }+ if model.calls != 0 {+ t.Errorf("model calls = %d, want none — a table of values must not spend a call", model.calls)+ }+ v := st.SlotTable.State[1]+ if v.Typed().Kind == slots.KindMembers {+ t.Errorf("slot now holds a member list, want the value it held untouched")+ }+ if v.Candidate == nil || *v.Candidate != prose {+ t.Errorf("slot candidate = %v, want the prose it held", v.Candidate)+ }+}++func testFloatPtr(f float64) *float64 { return &f }diff --git a/internal/rag/advanced_rag/slots/slots.go b/internal/rag/advanced_rag/slots/slots.gonew file mode 100644index 0000000000..d01071f3e6--- /dev/null+++ b/internal/rag/advanced_rag/slots/slots.go@@ -0,0 +1,365 @@+// Package slots is the VALUE ALGEBRA of a slot table: what a candidate value IS,+// how two values MERGE, and how a table's count is DERIVED.+//+// It exists because the alternative was measured to fail. When a candidate is free+// text, the structure is lost at the boundary — the model writes "约 17-19 人" — and+// every consumer downstream has to GUESS it back: is this a count? a list? are these+// pieces names? Each guess is a rule, the rules interact, and measured (2026-09-16,+// 三国/关羽) the result was a count slot holding "约、人" (the digits rejected as "not+// members", the qualifiers accepted as "members") while fifteen real names sat in+// another slot and the answer reported ten.+//+// So the structure travels WITH the value: a members list carries its items (each+// with the chunk that proves it), a count carries a number, a range carries two, and+// anything the model did not type is Text — stored, shown, never interpreted, never+// split. Nothing in this package inspects text, so there is no rule here to misfire.+//+// Four invariants hold, and they are what the rest of the pipeline may rely on:+//+// I1 Text never merges by union: the caller's strength rule decides. This is what+// keeps a value question (a date, a name, a phrase) behaving exactly as before.+// I2 members ∪ members = members, deduped by name, each keeping its first evidence.+// I3 members BEAT a number: a count is a claim ABOUT the list, so the number comes+// back as the dropped value (kept as an alternate) rather than overwriting it.+// I4 two numbers keep the larger: a set that shrinks when a second source agrees+// with it is a set that loses members.+package slots++import (+ "fmt"+ "strconv"+ "strings"+)++// Kind is what a value IS. There is no "unknown": anything the model did not type is+// Text, which is opaque by construction.+type Kind uint8++const (+ // KindEmpty is a slot with no value at all.+ KindEmpty Kind = iota+ // KindText is an opaque value: a date, a name, a phrase, a sentence. It is shown+ // and merged by strength, and NEVER parsed, split, counted, or compared+ // arithmetically.+ KindText+ // KindMembers is a list of named members, each optionally carrying the chunk that+ // proves it.+ KindMembers+ // KindCount is a claimed number ("13").+ KindCount+ // KindRange is a claimed interval ("约 17-19"), kept as two numbers rather than as+ // a string that someone later tries to parse (measured: "17-19" parsed+ // digit-by-digit is 1719).+ KindRange+)++func (k Kind) String() string {+ switch k {+ case KindText:+ return "text"+ case KindMembers:+ return "members"+ case KindCount:+ return "count"+ case KindRange:+ return "range"+ }+ return "empty"+}++// Member is one named member and the passage that proves it. A member without+// evidence is a member nobody can point at, so the empty ChunkID is allowed but+// visible (renderers show it).+type Member struct {+ Name string+ ChunkID string+ Quote string+}++// Value is what one slot holds. Exactly one of the fields matching Kind is set.+type Value struct {+ Kind Kind+ Text string // KindText (the raw candidate, verbatim)+ Items []Member // KindMembers+ Count int // KindCount+ Lo int // KindRange (inclusive)+ Hi int // KindRange (inclusive)+}++// Text wraps an opaque string.+func Text(s string) Value { return Value{Kind: KindText, Text: s} }++// Members wraps a member list (evidence may be empty per item).+func Members(items ...Member) Value { return Value{Kind: KindMembers, Items: items} }++// Number wraps a claimed count.+func Number(n int) Value { return Value{Kind: KindCount, Count: n} }++// Interval wraps a claimed range; lo > hi is normalised.+func Interval(lo, hi int) Value {+ if hi < lo {+ lo, hi = hi, lo+ }+ return Value{Kind: KindRange, Lo: lo, Hi: hi}+}++// IsZero reports "no value at all".+func (v Value) IsZero() bool {+ switch v.Kind {+ case KindText:+ return strings.TrimSpace(v.Text) == ""+ case KindMembers:+ return len(v.Items) == 0+ }+ return v.Kind == KindEmpty+}++// Names is the member names in order, deduped case-insensitively.+func (v Value) Names() []string {+ if v.Kind != KindMembers {+ return nil+ }+ seen := make(map[string]bool, len(v.Items))+ out := make([]string, 0, len(v.Items))+ for _, m := range v.Items {+ name := strings.TrimSpace(m.Name)+ if name == "" {+ continue+ }+ key := strings.ToLower(name)+ if seen[key] {+ continue+ }+ seen[key] = true+ out = append(out, name)+ }+ return out+}++// Number is the number a value claims: a count's number, a range's UPPER bound (the+// claim it makes about how many there could be). Text and members claim no number —+// that is the point of typing them.+func (v Value) Number() (int, bool) {+ switch v.Kind {+ case KindCount:+ return v.Count, true+ case KindRange:+ return v.Hi, true+ }+ return 0, false+}++// Render is the value's display text: what a prompt, a record line or a patch log+// shows. It is derived FROM the typed value, so nothing downstream ever has to+// re-derive the type from it.+func Render(v Value) string {+ switch v.Kind {+ case KindText:+ return v.Text+ case KindMembers:+ names := v.Names()+ return strings.Join(names, "、")+ case KindCount:+ return strconv.Itoa(v.Count)+ case KindRange:+ if v.Lo == v.Hi {+ return strconv.Itoa(v.Lo)+ }+ return fmt.Sprintf("%d-%d", v.Lo, v.Hi)+ }+ return ""+}++// Union merges two values and reports what changed.+//+// ok is false when the pair is not the union's business — either side being Text is+// exactly that case (I1), so the caller keeps its strength rule and a value question+// merges as it always did. dropped is the claim that lost the merge, as TEXT, so the+// caller can keep it as an alternate; the framework stops discarding claims, it does+// not decide which one is true.+func Union(a, b Value) (union, dropped Value, ok bool) {+ if a.IsZero() || b.IsZero() {+ return Value{}, Value{}, false+ }+ switch {+ case a.Kind == KindMembers && b.Kind == KindMembers:+ merged, added := mergeMembers(a.Items, b.Items)+ if !added {+ // A subset union is still a resolution: the union IS the base.+ return Value{Kind: KindMembers, Items: merged}, Value{}, true+ }+ return Value{Kind: KindMembers, Items: merged}, Value{}, true+ case a.Kind == KindMembers && isNumeric(b.Kind):+ return a, b, true+ case b.Kind == KindMembers && isNumeric(a.Kind):+ return b, a, true+ case isNumeric(a.Kind) && isNumeric(b.Kind):+ an, _ := a.Number()+ bn, _ := b.Number()+ if bn > an {+ return b, a, true+ }+ return a, b, true+ }+ return Value{}, Value{}, false+}++func isNumeric(k Kind) bool { return k == KindCount || k == KindRange }++// mergeMembers unions two member lists by name, first evidence wins.+func mergeMembers(base, branch []Member) ([]Member, bool) {+ out := make([]Member, 0, len(base)+len(branch))+ seen := make(map[string]int, len(base)+len(branch))+ for _, m := range base {+ name := strings.TrimSpace(m.Name)+ if name == "" {+ continue+ }+ key := strings.ToLower(name)+ if _, dup := seen[key]; dup {+ continue+ }+ seen[key] = len(out)+ out = append(out, Member{Name: name, ChunkID: m.ChunkID, Quote: m.Quote})+ }+ added := false+ for _, m := range branch {+ name := strings.TrimSpace(m.Name)+ if name == "" {+ continue+ }+ key := strings.ToLower(name)+ if i, dup := seen[key]; dup {+ // The member is already known; a second passage is worth keeping if the+ // first came without one (evidence is what makes a member accountable).+ if out[i].ChunkID == "" && m.ChunkID != "" {+ out[i].ChunkID, out[i].Quote = m.ChunkID, m.Quote+ }+ continue+ }+ seen[key] = len(out)+ out = append(out, Member{Name: name, ChunkID: m.ChunkID, Quote: m.Quote})+ added = true+ }+ return out, added+}++// Parse reads ONE patch entry — the JSON object a session emits for a slot — as a+// typed value. Anything it cannot read as a type is Text: fail closed, never guess.+//+// The accepted shapes (see prompts/action_run.md, which teaches them):+//+// {"kind":"members","items":[{"name":"华雄","chunk_id":"c1","quote":"提华雄之头"}]}+// {"kind":"count","count":13}+// {"kind":"range","lo":17,"hi":19}+// {"kind":"text","text":"…"} or {"candidate":"…"} (legacy/other)+func Parse(patch map[string]any) Value {+ if patch == nil {+ return Value{}+ }+ switch strings.ToLower(strings.TrimSpace(asString(patch["kind"]))) {+ case "members":+ items := parseItems(patch["items"])+ if len(items) == 0 {+ // Declared a list and gave none: the text (if any) is opaque, not a list.+ return Text(candidateText(patch))+ }+ return Value{Kind: KindMembers, Items: items}+ case "count":+ if n, ok := asInt(patch["count"]); ok {+ return Number(n)+ }+ return Text(candidateText(patch))+ case "range":+ lo, okLo := asInt(patch["lo"])+ hi, okHi := asInt(patch["hi"])+ if okLo && okHi {+ return Interval(lo, hi)+ }+ if okLo {+ return Number(lo)+ }+ if okHi {+ return Number(hi)+ }+ return Text(candidateText(patch))+ }+ return Text(candidateText(patch))+}++// candidateText reads the legacy free-text field. A null candidate is an empty value+// (Python's "set candidate null" — an eliminated claim).+func candidateText(patch map[string]any) string {+ raw, ok := patch["candidate"]+ if !ok || raw == nil {+ if t, has := patch["text"]; has && t != nil {+ return strings.TrimSpace(asString(t))+ }+ return ""+ }+ return strings.TrimSpace(asString(raw))+}++func parseItems(raw any) []Member {+ list, _ := raw.([]any)+ out := make([]Member, 0, len(list))+ for _, item := range list {+ switch it := item.(type) {+ case string:+ if name := strings.TrimSpace(it); name != "" {+ out = append(out, Member{Name: name})+ }+ case map[string]any:+ name := strings.TrimSpace(asString(it["name"]))+ if name == "" {+ // Tolerate {"candidate": …} / {"value": …} spellings, but a missing+ // name is not a member: skip rather than invent one.+ name = strings.TrimSpace(asString(it["candidate"]))+ }+ if name == "" {+ continue+ }+ out = append(out, Member{+ Name: name,+ ChunkID: strings.TrimSpace(asString(it["chunk_id"])),+ Quote: strings.TrimSpace(asString(it["quote"])),+ })+ }+ }+ return out+}++func asString(v any) string {+ switch s := v.(type) {+ case nil:+ return ""+ case string:+ return s+ default:+ return fmt.Sprint(s)+ }+}++// asInt reads a JSON number (float64), a numeric string, or a bool-free anything.+func asInt(v any) (int, bool) {+ switch n := v.(type) {+ case float64:+ return int(n), true+ case int:+ return n, true+ case int64:+ return int(n), true+ case string:+ s := strings.TrimSpace(n)+ if s == "" {+ return 0, false+ }+ if i, err := strconv.Atoi(s); err == nil {+ return i, true+ }+ if f, err := strconv.ParseFloat(s, 64); err == nil {+ return int(f), true+ }+ }+ return 0, false+}diff --git a/internal/rag/advanced_rag/slots/slots_test.go b/internal/rag/advanced_rag/slots/slots_test.gonew file mode 100644index 0000000000..1104799afe--- /dev/null+++ b/internal/rag/advanced_rag/slots/slots_test.go@@ -0,0 +1,156 @@+package slots++import "testing"++// TestUnionKeepsTheInvariants pins the four rules the rest of the pipeline relies on.+//+// They exist because the alternative was measured to fail: when a candidate is free+// text, "is this a count or a list" has to be guessed back, and the guesses interact —+// measured (2026-09-16, 三国/关羽) a count slot holding "约 17-19 人" ended up as+// "约、人" (the digits rejected as members, the qualifiers accepted as members) while+// fifteen real names sat in the list slot and the answer reported ten.+func TestUnionKeepsTheInvariants(t *testing.T) {+ // I2 — members union by name, first evidence wins.+ a := Members(Member{Name: "华雄", ChunkID: "c1"}, Member{Name: "颜良"})+ b := Members(Member{Name: "颜良", ChunkID: "c2"}, Member{Name: "管亥", ChunkID: "c3"})+ got, dropped, ok := Union(a, b)+ if !ok || len(got.Names()) != 3 {+ t.Fatalf("members ∪ members = %v (ok=%v), want three names", got, ok)+ }+ if !dropped.IsZero() {+ t.Errorf("dropped = %v, want nothing: a member list does not lose members to another list", dropped)+ }+ for _, m := range got.Items {+ switch m.Name {+ case "华雄":+ if m.ChunkID != "c1" {+ t.Errorf("华雄 = %v, want its own evidence kept", m)+ }+ case "颜良":+ // The base listed 颜良 without evidence; the branch had one. A member+ // without a passage is a member nobody can point at, so the evidence is+ // filled in rather than dropped with the duplicate.+ if m.ChunkID != "c2" {+ t.Errorf("颜良 = %v, want the evidence the other list supplied", m)+ }+ }+ }+ // A member that arrived without evidence takes the one a later list supplies.+ withEvidence, _, _ := Union(Members(Member{Name: "庞德"}), Members(Member{Name: "庞德", ChunkID: "c9"}))+ if withEvidence.Items[0].ChunkID != "c9" {+ t.Errorf("庞德 = %v, want the evidence a later list supplied", withEvidence.Items[0])+ }++ // I3 — members beat a number, and the number is kept as the dropped claim.+ union, dropped, ok := Union(a, Number(2))+ if !ok || union.Kind != KindMembers {+ t.Fatalf("members ∪ count = %v (ok=%v), want the members", union, ok)+ }+ if dropped.Kind != KindCount || dropped.Count != 2 {+ t.Errorf("dropped = %v, want the losing count 2", dropped)+ }+ // …in either order.+ union, dropped, ok = Union(Number(2), a)+ if !ok || union.Kind != KindMembers || dropped.Count != 2 {+ t.Errorf("count ∪ members = %v / %v (ok=%v), want the members with the count dropped", union, dropped, ok)+ }++ // I4 — two numbers keep the larger, in both orders.+ for _, pair := range [][2]Value{{Number(10), Number(13)}, {Number(13), Number(10)}} {+ union, dropped, ok := Union(pair[0], pair[1])+ if !ok || union.Count != 13 {+ t.Errorf("counts %v ∪ %v = %v (ok=%v), want 13", pair[0], pair[1], union, ok)+ }+ if dropped.Count != 10 {+ t.Errorf("dropped = %v, want 10", dropped)+ }+ }+ // A range counts as the number it claims at its upper bound.+ if union, dropped, ok := Union(Interval(17, 19), Number(16)); !ok || union.Kind != KindRange || dropped.Count != 16 {+ t.Errorf("range ∪ count = %v / %v (ok=%v), want the range with 16 dropped", union, dropped, ok)+ }++ // I1 — Text never merges by union: the caller's strength rule decides, which is+ // what keeps a value question (a date, a name, a phrase) behaving as it always did.+ if _, _, ok := Union(Text("1858"), Text("1849")); ok {+ t.Error("text ∪ text must not resolve: a value question merges by strength")+ }+ if _, _, ok := Union(Text("13"), Number(11)); ok {+ t.Error("text ∪ count must not resolve: text is opaque and claims nothing")+ }+ if _, _, ok := Union(Members(Member{Name: "华雄"}), Text("华雄")); ok {+ t.Error("a member list and a text value must not resolve by union")+ }+}++// TestParseIsFailClosed pins the boundary contract: a patch that declares a kind is+// read as data, and anything else is opaque text. Nothing is inferred from the string,+// which is what removes the rules that used to misfire.+func TestParseIsFailClosed(t *testing.T) {+ members := Parse(map[string]any{+ "kind": "members",+ "items": []any{+ map[string]any{"name": "华雄", "chunk_id": "c1", "quote": "提华雄之头"},+ map[string]any{"name": "颜良"},+ map[string]any{"quote": "no name here"}, // skipped, not invented+ },+ })+ if members.Kind != KindMembers || len(members.Names()) != 2 {+ t.Fatalf("members patch = %v, want two declared members", members)+ }+ if members.Items[0].ChunkID != "c1" {+ t.Errorf("华雄 = %v, want its evidence", members.Items[0])+ }++ // A count phrase the model did not type is TEXT: it is neither split nor parsed.+ // This is the measured failure the typing exists for.+ opaque := Parse(map[string]any{"candidate": "约 17-19 人"})+ if opaque.Kind != KindText || opaque.Text != "约 17-19 人" {+ t.Fatalf("untyped candidate = %v, want it opaque", opaque)+ }+ if _, ok := opaque.Number(); ok {+ t.Error("text must claim no number: that is what stops 17-19 from being read as 1719")+ }+ if names := opaque.Names(); names != nil {+ t.Errorf("text names = %v, want none", names)+ }++ // Declared kinds read their own fields, and a malformed one falls back to text+ // rather than being half-read.+ if v := Parse(map[string]any{"kind": "count", "count": float64(13)}); v.Kind != KindCount || v.Count != 13 {+ t.Errorf("count patch = %v, want 13", v)+ }+ if v := Parse(map[string]any{"kind": "range", "lo": float64(17), "hi": float64(19)}); v.Kind != KindRange || v.Lo != 17 || v.Hi != 19 {+ t.Errorf("range patch = %v, want 17-19", v)+ }+ if v := Parse(map[string]any{"kind": "count", "candidate": "about ten"}); v.Kind != KindText {+ t.Errorf("a count without a number = %v, want text (fail closed)", v)+ }+ if v := Parse(map[string]any{"kind": "members"}); v.Kind != KindText {+ t.Errorf("members without items = %v, want text (fail closed)", v)+ }+ if v := Parse(nil); !v.IsZero() {+ t.Errorf("nil patch = %v, want empty", v)+ }+}++// TestRenderIsDerivedFromTheType pins the other half of the contract: what a prompt+// or a record line shows is derived from the typed value, so nothing downstream has+// to re-derive the type from the string.+func TestRenderIsDerivedFromTheType(t *testing.T) {+ cases := []struct {+ in Value+ want string+ }{+ {Members(Member{Name: "华雄"}, Member{Name: "颜良"}), "华雄、颜良"},+ {Number(13), "13"},+ {Interval(17, 19), "17-19"},+ {Interval(5, 5), "5"},+ {Text("1858"), "1858"},+ }+ for _, c := range cases {+ if got := Render(c.in); got != c.want {+ t.Errorf("Render(%v) = %q, want %q", c.in, got, c.want)+ }+ }+}diff --git a/internal/rag/prompts/action_initialize_state.md b/internal/rag/prompts/action_initialize_state.mdindex 34bec2298f..8b6ab7a873 100644--- a/internal/rag/prompts/action_initialize_state.md+++ b/internal/rag/prompts/action_initialize_state.md@@ -8,7 +8,7 @@ The question may span MULTIPLE DATASETS and/or the open WEB. The available dataOutput ONLY a JSON object:{"slots": [- {"id": 0, "type": "<entity|person|date|duration|count|number|place|web|dataset>", "clues": ["<what identifies this slot from the question>", "..."], "source": "<dataset name or 'web'>"},+ {"id": 0, "type": "<entity|person|date|duration|count|number|place|web|dataset>", "clues": ["<what identifies this slot from the question>", "..."], "source": "<dataset name or 'web'>", "scan": ["<act word>", "..."], "subject": "<who the act is about>"},...],"first_queries": ["<concrete searchable query for the first retrieval round>", ...]@@ -19,5 +19,7 @@ Rules:- Order slots so the FIRST one holds the top-level requested fact; the later ones are its dependencies.- Cover EVERY listed source: one or more slots per dataset, plus a "web" slot when Web is available and the question touches world knowledge or recent events.- clues must be self-contained phrases usable as retrieval hints.+- `"scan"` — ONLY for a slot whose answer is a SET or a COUNT of things that someone DID ("how many named people did X kill", "which awards did Y win"): the words the SOURCE itself uses for that deed. Give EVERY phrasing you can think of, including the unusual ones (斩 / 杀 / 诛 / 劈 / 砍 / 刺 / 挥为两段 / 手起刀落 / 斩于马下): a passage phrased in a way no term covers is a passage no query ever names. At most 10 terms.+- `"subject"` — next to `scan`, WHO the act is about, as the names the source uses for them, alternated: `关羽|关公|云长`. Omit it only when the slot is not about one actor.- 1-4 first_queries: direct keyword-style searches against the listed sources.- No prose outside JSON.diff --git a/internal/rag/prompts/action_run.md b/internal/rag/prompts/action_run.mdindex 059cf50cc2..b2f327c50a 100644--- a/internal/rag/prompts/action_run.md+++ b/internal/rag/prompts/action_run.md@@ -15,10 +15,30 @@ the first one is a tool call:reply body (do not call any tool named "state"):<state>{"new_states": [- {"state": [{"id": <int>, "candidate": "<value>", "candidate_strength": <0..1>, "discovered_clues": ["..."]}, ...]},+ {"state": [+ {"id": <int>, "kind": "members", "candidate_strength": <0..1>,+ "items": [{"name": "华雄", "chunk_id": "<the passage this name came from>", "quote": "…the words that prove it…"}],+ "discovered_clues": ["..."]},+ {"id": <int>, "kind": "count", "count": 13, "candidate_strength": <0..1>},+ {"id": <int>, "kind": "range", "lo": 17, "hi": 19, "candidate_strength": <0..1>},+ {"id": <int>, "kind": "text", "candidate": "<one value: a date, a name, a phrase>", "candidate_strength": <0..1>}+ ]},...more branches allowed...]}</state>++WHY `kind` MATTERS — the runtime merges and counts BY TYPE, so say what the slot holds:+- `"members"` — a LIST OF NAMED THINGS. Give every item the `chunk_id` of the passage+ it came from; a name you cannot point at is left out of the count. Two sessions'+ member lists UNION: no member is dropped because another session ranked its own list+ higher. This is the ONLY shape whose items are counted as members.+- `"count"` / `"range"` — a NUMBER, or an interval. Digits inside a count are never+ read as members. "约 17-19 人" is `{"kind":"range","lo":17,"hi":19}` — NOT a string:+ a number written as prose can be merged with nothing and checked against nothing.+- `"text"` — ONE opaque value: a date, a title, a clause, a sentence. Stored and shown+ as written; never split, counted or compared. Use it for every value that is not a+ member list or a number.+Rules: patch ONLY existing ids; include ONLY changed variables; every change must trace to retrieved evidence; candidate_strength semantics: proven >0.9, strong 0.7-0.9, tentative 0.4-0.7, weak <0.4. An EMPTY branch list (`"new_states": []`) signals no progress — emit it rather than calling tools forever.3) FINAL ANSWER MODE — NOT a tool call either. Write this XML as plain TEXT indiff --git a/internal/rag/prompts/action_set.md b/internal/rag/prompts/action_set.mdnew file mode 100644index 0000000000..1f856ef0db--- /dev/null+++ b/internal/rag/prompts/action_set.md@@ -0,0 +1,23 @@+# SET / COUNT directions — the member list IS the work++Your Direction asks for a SET of named things: a batch of names is a NEW fact, not a redundant search. The convergence rule in the playbook is about re-asking what you already have; here, keep probing while the `[record]` line is still changing.++1. Guess MORE names than you expect — aliases, names seen once, names you doubt — and put a name you have NOT read in a passage into every batch: for each name you have already seen, at least one you have not. The names you have seen are the ones retrieval reaches by itself, and they are exactly the names that are not missing. A wrong guess costs one probe; a missing member costs the answer.+2. Probe them as ONE alternation, a dozen at a time: `name1|name2|name3|…`. Put ONLY candidate members in it — never the subject, never the verb: each name is searched on its own, so the batch is what gives every doubtful name its own evidence, while `subject verb name1 name2` spends half the batch on words that are not members.+3. One batch before you stop is of the names you are LEAST sure of — the ones you saw once, half-remember, or doubt. A batch of the names you are certain of proves nothing: the doubtful batch is where the tail is.+4. When you cannot name the object at all, batch the RELATION instead — `verb1|verb2|verb3`, how the source words the act — and read the matches for names.+5. Read every returned passage for members the batch did not name, and probe those too — the corpus names the tail, not your memory. A `miss` means this corpus does not carry that name: record it as "not a member" and continue. A snippet means the name IS a member: record it with its passage.+6. Record as you go, so a timeout cannot lose what you found. Record a member as a+ MEMBER: `{"id": <list slot>, "kind": "members", "items": [{"name": "华雄",+ "chunk_id": "<its passage>"}]}` — one patch may carry every member you have, and a+ name written inside a sentence is not a member (the runtime counts declared items+ only, and it will not read a list out of prose).+7. Stop when two consecutive batches add no member you did not have.++## What the results now carry++- **Every tool result ends with a `[record]` line. Read it, and trust it over your own impression of what you have done.** It carries the facts you cannot see in the conversation: `members` (what the slots hold now), `probed-reached` (the names you asked about that came back with a passage), `asked-nothing-back` (names that came back with NOTHING — change the wording or the angle, do not re-ask them as they are), and `FOUND BUT NOT RECORDED` (names you proved reachable and never put in a slot — resolve these before searching anything new).+- **A `[pool]` line may follow it: an excerpt from evidence ALREADY in hand that you have not been shown** (the id is its chunk). Read it for members the list is missing, and probe any name it carries that the list does not — the passage is already evidence, so naming it costs no retrieval you do not have.+- **A `[reach]` line may follow a batched or pattern query**: the terms that call reached (with how many passages each) and the ones it did NOT reach. Aim the next call at the second list, or re-word it — a term listed there was not reached by THAT query, which is not the same as absent from the corpus.+- **The direction is exhausted when the `[record]` line stops changing** — no new member, no newly reached or unanswered name — and the slots are filled. Then return the state patch immediately. While it IS still changing, the next useful call is a probe of a `FOUND BUT NOT RECORDED` name, or of an angle the line shows you have not tried.+- **What you found only counts if your patch carries it.** Neither your searches nor your reading of them reach the stage that writes the answer — only your patch does. So end the session carrying EVERY member you confirmed, not just the last batch's: measured, a round whose pool already held every member's passage recorded a fraction of them, because the session spent every turn searching and patched last, when its budget was gone.diff --git a/internal/rag/prompts/sca_query_rewrite.md b/internal/rag/prompts/sca_query_rewrite.mdindex 4bac290600..224330a938 100644--- a/internal/rag/prompts/sca_query_rewrite.md+++ b/internal/rag/prompts/sca_query_rewrite.md@@ -21,6 +21,7 @@ Rewrite each missing piece into a concrete search query that the retriever can h6. ONE QUERY PER MISSING PIECE. Do not emit multiple near-duplicate queries for the same gap ("What teams"/"For each team"/"Complete enumeration" of the same thing are duplicates — keep exactly one, the most concretely anchored). The number of output queries should equal the number of distinct, genuinely-different missing pieces.7. Drop any missing piece that cannot be turned into a searchable query.8. DIVERSITY: consult the "Research history and evidence at hand" section. Do NOT output any query that paraphrases an already-tried one (listed there WITH its outcome — a previous search that yielded nothing new means that angle is dead). Aim each new query at aspects the current evidence does NOT yet cover, possibly combining the bridge values with different entity/relation combinations.+9. WHEN THE PASSAGES NAME INDIVIDUALS: the "Passages that carry names the searches ALREADY confirmed" section shows the passage behind each confirmed name. Read those passages for (a) other names they mention that are not confirmed yet and (b) the wording this text uses for the relation (e.g. how the act is narrated). Any of those names may be asked about directly — put SEVERAL of them into ONE query separated by `|` (e.g. `nameA|nameB|nameC`), which the retriever reads as an alternation and answers per name in a single call; never spend one query per name. The same alternation form takes the wording you found: `phraseA|phraseB`.Output format (JSON):```jsondiff --git a/internal/rag/prompts/templates.go b/internal/rag/prompts/templates.goindex ba2ea97753..d887a5f7dc 100644--- a/internal/rag/prompts/templates.go+++ b/internal/rag/prompts/templates.go@@ -29,13 +29,18 @@ import (// here so the binary is self-contained and survives the Python source being// deleted.//-// The templates mirrored by this package (action_run, action_initialize_state,-// consumed by the harness action session; sca_select and sca_query_rewrite,-// consumed by the orchestrator) were previously duplicated as copies under-// harness/prompts/. They are now unified here, with the harness wiring its-// PromptLoader default to this package's embedded loader.+// The templates mirrored by this package (action_run, action_set,+// action_initialize_state, consumed by the harness action session; sca_select+// and sca_query_rewrite, consumed by the orchestrator) were previously+// duplicated as copies under harness/prompts/. They are now unified here, with+// the harness wiring its PromptLoader default to this package's embedded loader.+//+// action_set is the ONE template that is not part of a system prompt: the harness+// appends it to a session's seed message, and only for a direction that is a SET+// (see enumerates). Strategy text that is always in the prompt is paid for by+// every question, including the ones it cannot help.-//go:embed action_run.md action_initialize_state.md sca_select.md sca_query_rewrite.md citation_prompt.md+//go:embed action_run.md action_set.md action_initialize_state.md sca_select.md sca_query_rewrite.md citation_prompt.mdvar templatesFS embed.FS// EmbeddedPromptLoader serves the bundled .md templates by name. Load returnsdiff --git a/internal/rag/prompts/templates_test.go b/internal/rag/prompts/templates_test.goindex 7b5c3e7a2a..0535a66403 100644--- a/internal/rag/prompts/templates_test.go+++ b/internal/rag/prompts/templates_test.go@@ -27,6 +27,7 @@ import (func TestEmbeddedLoaderCanonicalTemplates(t *testing.T) {names := []string{"action_run",+ "action_set","action_initialize_state","sca_select","sca_query_rewrite",@@ -161,3 +162,68 @@ func (s stubLoader) Load(string) (string, error) { return s.text, nil }// now resolves the canonical embedded .md (1:1 with rag/prompts/sca_select.md)// rather than the condensed constant — the whole point of the orchestration// parity fix.++// TestEnumerationProtocolIsNotInTheSystemPrompt pins the split: the enumeration+// protocol lives in its own template, which the harness appends to the turn of a+// session that has SHOWN it is enumerating (see appendBatchProtocol) — never to the+// system prompt, and never to the seed.+//+// It was briefly a section of action_run.md, and it did its job there (the answer+// went from ten-to-thirteen members to sixteen), but a system prompt is paid for+// by EVERY question: a strategy that only helps an enumeration is a tax on the+// single-value questions it cannot help. It then rode the seed, gated on the shape+// of the planner's table, and that gate misfired too — measured (2026-09-15) 11 of+// 20 FRAMES sessions were handed it for questions whose answer is one number.+//+// The FORM of the batch matters as much as the instruction to write one, which is+// why the alternation is pinned here. Measured (2026-09-14, the recall run): every+// name the answer needed that later runs lost — 程远志、荀正、杨龄、夏侯存 — entered+// the corpus as the MODEL'S OWN query term, in an alternation of the names it+// doubted (`关羽斩杨龄|荀正|夏侯存`, `关公斩庞德|成何`, `关羽斩黄巾|程远志|管亥|张宝|张梁`),+// with the runtime then searching each name on its own. Then the template was+// rewritten to say "batches of four to six, space-separated" and the same question+// came back with thirteen members: the batches became `关羽 斩 颜良 文丑` — four+// fields of which two are the subject and the verb — and the doubtful names were+// never asked about at all (grep of that run for 荀正/杨龄/夏侯存: zero).+//+// The alternation instruction ALONE did not restore them, which is why the demand+// for unseen names is pinned too. Measured (2026-09-16): a run whose seed carried+// this template (3416 chars — the version with items 2 and 3 written as the+// alternation and the doubtful batch, but without item 1's "at least one you have+// not") wrote the alternation ZERO times and answered the same thirteen members.+// The template that had produced seventeen members (2509ccb96) differed in exactly+// two places, and both demanded NAMES rather than a FORM: it asked for a long list+// ("fifteen to twenty-five candidates") and it said what to leave out — "Do NOT+// stop at the names you have already seen in a passage: those are the ones+// retrieval reaches by itself, and they are exactly the ones that are not+// missing". A number is a corpus-independent way of saying "long", but the ratio+// in item 1 says the same thing without pretending the answer's size is known, and+// it keeps the second, load-bearing half: the names you have already read are not+// the missing ones.+func TestEnumerationProtocolIsNotInTheSystemPrompt(t *testing.T) {+ run, err := (EmbeddedPromptLoader{}).Load("action_run")+ if err != nil {+ t.Fatalf("Load(action_run): %v", err)+ }+ if strings.Contains(run, "SET / COUNT directions") {+ t.Error("the enumeration protocol must not be part of the system prompt")+ }++ set, err := (EmbeddedPromptLoader{}).Load("action_set")+ if err != nil {+ t.Fatalf("Load(action_set): %v", err)+ }+ for _, want := range []string{"SET / COUNT directions", "name1|name2|name3", "at least one you have not", "names you are LEAST sure of", "two consecutive batches"} {+ if !strings.Contains(set, want) {+ t.Errorf("action_set is missing %q", want)+ }+ }+ // The budget exception is GONE, and this is the assertion that keeps it gone.+ // "the 1-2-call budget does NOT apply" turned a method into a licence: the run+ // that carried it in every set-shaped seed went 60 → 92 rounds and 1 → 5+ // zero-score questions. A batch is a new fact ON a set direction; the global call+ // budget is not suspended by this template.+ if strings.Contains(set, "does NOT apply") {+ t.Error("action_set must not suspend the global call budget")+ }+}diff --git a/internal/service/nlp/reranker.go b/internal/service/nlp/reranker.goindex 36c6ca0bae..1b5ad0adad 100644--- a/internal/service/nlp/reranker.go+++ b/internal/service/nlp/reranker.go@@ -1017,7 +1017,7 @@ func RerankWithKNN(for i, chunkID := range ids {vsim[i] = knnScores[chunkID] // Returns 0.0 if not found (Go map default)}- common.Info("RerankWithKNN knnScores", zap.Int("knnScoreCount", len(knnScores)), zap.Float64s("vsim", vsim), zap.Strings("ids", ids), zap.Float64s("knnScores", func() []float64 {+ common.Debug("RerankWithKNN knnScores", zap.Int("knnScoreCount", len(knnScores)), zap.Float64s("vsim", vsim), zap.Strings("ids", ids), zap.Float64s("knnScores", func() []float64 {scores := make([]float64, 0, len(knnScores))for _, id := range ids {if s, ok := knnScores[id]; ok {