feat: escalate brain search to web when facts cannot confirm

internal/brain/rank/args.go

@@ -6,7 +6,7 @@ import (
 	"strings"
 )
 
-const Usage = `usage: bin/brain/search.go "query" [--root facts|info] [--repo REPO] [-n N] [--json]
+const Usage = `usage: bin/brain/search.go "query" [--root facts|info] [--repo REPO] [-n N] [--json] [--no-web]
        bin/brain/search.go serve [port]
        bin/brain/search.go --list-model`
 
@@ -17,6 +17,7 @@ type Options struct {
 	Limit     int
 	JSONOut   bool
 	ListModel bool
+	NoWeb     bool
 }
 
 // ParseArgs reads flags. Unknown flags are an error: silently dropping them
@@ -54,6 +55,8 @@ func ParseArgs(args []string) (Options, error) {
 			return opt, fmt.Errorf("--hop is not implemented yet (needs File/FROM_FILE edges)")
 		case "--json":
 			opt.JSONOut = true
+		case "--no-web":
+			opt.NoWeb = true
 		case "--list-model":
 			opt.ListModel = true
 		default:

internal/brain/rank/escalate.go

@@ -0,0 +1,43 @@
+package rank
+
+// SecondSource is the web-search block on a deduction answer.
+// Kept apart from graph hits so "ours" and "not ours" stay visible.
+type SecondSource struct {
+	Status  string            `json:"status"`
+	Note    string            `json:"note,omitempty"`
+	Cached  bool              `json:"cached,omitempty"`
+	Results []SecondSourceHit `json:"results,omitempty"`
+}
+
+type SecondSourceHit struct {
+	Rank    int    `json:"rank"`
+	Title   string `json:"title"`
+	URL     string `json:"url"`
+	Snippet string `json:"snippet"`
+	Engine  string `json:"engine"`
+}
+
+type WebFn func(query string) SecondSource
+
+// ShouldEscalate is true when the default deduction path has no facts hit.
+// `--root facts|info` is a single-root ask: do not mix in the web.
+func ShouldEscalate(hits []Hit, rootFilter string) bool {
+	if rootFilter != "" {
+		return false
+	}
+	for _, h := range hits {
+		if h.Root == "facts" {
+			return false
+		}
+	}
+	return true
+}
+
+// Deduce returns the second-source block, or nil when web must not run.
+func Deduce(hits []Hit, query, rootFilter string, noWeb bool, web WebFn) *SecondSource {
+	if noWeb || web == nil || !ShouldEscalate(hits, rootFilter) {
+		return nil
+	}
+	out := web(query)
+	return &out
+}

internal/brain/rank/escalate_test.go

@@ -0,0 +1,78 @@
+package rank
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestShouldEscalateWhenNoFacts(t *testing.T) {
+	if !ShouldEscalate(nil, "") {
+		t.Fatal("empty local graph must escalate")
+	}
+	if !ShouldEscalate([]Hit{h("i", "info", "docs/a.md")}, "") {
+		t.Fatal("info-only must escalate (not confirmed)")
+	}
+}
+
+func TestShouldNotEscalateWhenFactsConfirm(t *testing.T) {
+	hits := []Hit{h("f", "facts", "docker ps x compose"), h("i", "info", "docs/a.md")}
+	if ShouldEscalate(hits, "") {
+		t.Fatal("facts hit is already confirmed; do not mix web")
+	}
+}
+
+func TestShouldNotEscalateWhenRootFilterSet(t *testing.T) {
+	if ShouldEscalate(nil, "facts") {
+		t.Fatal("--root facts must stay local")
+	}
+	if ShouldEscalate([]Hit{h("i", "info", "x")}, "info") {
+		t.Fatal("--root info must stay local")
+	}
+}
+
+func TestDeduceCallsWebOnlyWhenEscalating(t *testing.T) {
+	called := 0
+	web := func(q string) SecondSource {
+		called++
+		if q != "LadybugDB" {
+			t.Fatalf("query = %q", q)
+		}
+		return SecondSource{Status: "ok", Results: []SecondSourceHit{{Title: "t", URL: "http://example.com"}}}
+	}
+	got := Deduce([]Hit{h("i", "info", "x")}, "LadybugDB", "", false, web)
+	if called != 1 || got == nil || got.Status != "ok" {
+		t.Fatalf("got %+v called=%d", got, called)
+	}
+}
+
+func TestDeduceNilWhenFactsOrNoWeb(t *testing.T) {
+	web := func(string) SecondSource {
+		t.Fatal("web must not run")
+		return SecondSource{}
+	}
+	if Deduce([]Hit{h("f", "facts", "x")}, "q", "", false, web) != nil {
+		t.Fatal("facts")
+	}
+	if Deduce([]Hit{h("i", "info", "x")}, "q", "", true, web) != nil {
+		t.Fatal("--no-web")
+	}
+	if Deduce(nil, "q", "facts", false, web) != nil {
+		t.Fatal("--root facts")
+	}
+	if Deduce(nil, "q", "", false, nil) != nil {
+		t.Fatal("nil web fn")
+	}
+}
+
+func TestParseNoWeb(t *testing.T) {
+	opt, err := ParseArgs([]string{"query", "--no-web", "--json"})
+	if err != nil || !opt.NoWeb || !opt.JSONOut || opt.Query != "query" {
+		t.Fatalf("got %+v err=%v", opt, err)
+	}
+}
+
+func TestUsageNamesNoWeb(t *testing.T) {
+	if !strings.Contains(Usage, "--no-web") {
+		t.Fatalf("usage must name --no-web, got:\n%s", Usage)
+	}
+}