feat: D16 adjudication — 2v2 stays hypothesis until a rule fires. (#35)

temporal_freshness then authority_pairing; unresolved keeps (not confirmed).
bin/facts/audit contradict. Gitea #29.

internal/brain/rank/escalate.go

@@ -19,20 +19,35 @@ type SecondSourceHit struct {
 
 type WebFn func(query string) SecondSource
 
-// ShouldEscalate is true when the default deduction path has no facts hit.
+// ShouldEscalate is true when the default deduction path has no confirmed
+// facts hit. Hypothesis/partial facts are `(not confirmed)` (D16).
 // `--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" {
+		if ConfirmedFact(h) {
 			return false
 		}
 	}
 	return true
 }
 
+// ConfirmedFact is a facts-root hit that is not hypothesis/partial.
+// Empty confidence is treated as confirmed (legacy leafs).
+func ConfirmedFact(h Hit) bool {
+	if h.Root != "facts" {
+		return false
+	}
+	switch h.Confidence {
+	case "hypothesis", "partial":
+		return false
+	default:
+		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) {

internal/brain/rank/escalate_test.go

@@ -14,6 +14,16 @@ func TestShouldEscalateWhenNoFacts(t *testing.T) {
 	}
 }
 
+func TestShouldEscalateWhenHypothesisFacts(t *testing.T) {
+	hyp := Hit{ID: "c", Root: "facts", Confidence: "hypothesis", Source: "a x b vs c x d"}
+	if !ShouldEscalate([]Hit{hyp}, "") {
+		t.Fatal("hypothesis facts are (not confirmed); escalate")
+	}
+	if ConfirmedFact(hyp) {
+		t.Fatal("hypothesis is 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, "") {

internal/brain/rank/query.go

@@ -3,10 +3,10 @@ package rank
 // BM25 ranks best-first, so the top hits are the *highest* scores; cosine
 // distance ranks best-first ascending. Both mirror kblib.py.
 const FTSStmt = "CALL QUERY_FTS_INDEX('Leaf', 'id', $q) " +
-	"RETURN node.id, node.text, node.root, node.source, score ORDER BY score DESC LIMIT $n"
+	"RETURN node.id, node.text, node.root, node.source, score, node.confidence ORDER BY score DESC LIMIT $n"
 
 const VecStmt = "CALL QUERY_VECTOR_INDEX('Leaf', 'Leaf_vec', $q, $n) " +
-	"RETURN node.id, node.text, node.root, node.source, distance ORDER BY distance LIMIT $n"
+	"RETURN node.id, node.text, node.root, node.source, distance, node.confidence ORDER BY distance LIMIT $n"
 
 // HopStmt is the Cypher walk from a search hit. Depth 1 = File, 2 = Commit, 3 = Person.
 func HopStmt(depth int) string {

internal/brain/rank/rank.go

@@ -16,13 +16,14 @@ type HopNode struct {
 
 // Hit is one search result, mirroring the python script's dict shape.
 type Hit struct {
-	ID      string    `json:"id"`
-	Text    string    `json:"text"`
-	Root    string    `json:"root"`
-	Source  string    `json:"-"`
-	Score   float64   `json:"score"`
-	Snippet string    `json:"snippet,omitempty"`
-	Hops    []HopNode `json:"hops,omitempty"`
+	ID         string    `json:"id"`
+	Text       string    `json:"text"`
+	Root       string    `json:"root"`
+	Confidence string    `json:"confidence,omitempty"`
+	Source     string    `json:"-"`
+	Score      float64   `json:"score"`
+	Snippet    string    `json:"snippet,omitempty"`
+	Hops       []HopNode `json:"hops,omitempty"`
 }
 
 // rrfK dampens the contribution of low ranks; same constant as kblib.py.

internal/brain/rank/rank_test.go

@@ -172,4 +172,7 @@ func TestFTSQueryOrdersByScoreDescending(t *testing.T) {
 	if !strings.Contains(FTSStmt, "ORDER BY score DESC") {
 		t.Fatalf("FTS query must order by score DESC, got:\n%s", FTSStmt)
 	}
+	if !strings.Contains(FTSStmt, "node.confidence") {
+		t.Fatal("FTS must return confidence for D16")
+	}
 }

internal/brain/search.go

@@ -212,7 +212,11 @@ func rowsToHits(res *lbug.QueryResult) ([]Hit, error) {
 		root := fmt.Sprint(vals[2])
 		source := fmt.Sprint(vals[3])
 		score := float64(vals[4].(float64))
-		hits = append(hits, Hit{ID: id, Text: text, Root: root, Source: source, Score: score})
+		conf := ""
+		if len(vals) >= 6 {
+			conf = fmt.Sprint(vals[5])
+		}
+		hits = append(hits, Hit{ID: id, Text: text, Root: root, Source: source, Score: score, Confidence: conf})
 	}
 	return hits, nil
 }
@@ -227,24 +231,26 @@ type jsonOut struct {
 }
 
 type jsonHit struct {
-	ID      string         `json:"id"`
-	Text    string         `json:"text"`
-	Root    string         `json:"root"`
-	Score   float64        `json:"score"`
-	Snippet string         `json:"snippet,omitempty"`
-	Hops    []rank.HopNode `json:"hops,omitempty"`
+	ID         string         `json:"id"`
+	Text       string         `json:"text"`
+	Root       string         `json:"root"`
+	Confidence string         `json:"confidence,omitempty"`
+	Score      float64        `json:"score"`
+	Snippet    string         `json:"snippet,omitempty"`
+	Hops       []rank.HopNode `json:"hops,omitempty"`
 }
 
 func toJSONOut(hits []Hit, query, rootFilter string, web *rank.SecondSource) *jsonOut {
 	out := make([]jsonHit, len(hits))
 	for i, h := range hits {
 		out[i] = jsonHit{
-			ID:      h.ID,
-			Text:    h.Text,
-			Root:    h.Root,
-			Score:   h.Score,
-			Snippet: h.Snippet,
-			Hops:    h.Hops,
+			ID:         h.ID,
+			Text:       h.Text,
+			Root:       h.Root,
+			Confidence: h.Confidence,
+			Score:      h.Score,
+			Snippet:    h.Snippet,
+			Hops:       h.Hops,
 		}
 	}
 	return &jsonOut{
@@ -265,6 +271,9 @@ func resultsToDicts(hits []Hit) []any {
 			{"root", h.Root},
 			{"score", h.Score},
 		}
+		if h.Confidence != "" {
+			d = append(d, KV{"confidence", h.Confidence})
+		}
 		if h.Snippet != "" {
 			d = append(d, KV{"snippet", h.Snippet})
 		}

internal/facts/contradict.go

@@ -0,0 +1,120 @@
+// Package facts is cgo-free evidence rules (D16 contradictions).
+package facts
+
+import "strconv"
+
+const (
+	ConfConfirmed  = "confirmed"
+	ConfHypothesis = "hypothesis"
+
+	RuleUnresolved        = "unresolved"
+	RuleTemporalFreshness = "temporal_freshness"
+	RuleAuthorityPairing  = "authority_pairing"
+	RuleTwoSource         = "two_source"
+	RuleSingleSource      = "single_source"
+
+	KindRuntime   = "runtime"
+	KindConfig    = "config"
+	KindNarrative = "narrative"
+)
+
+// Source is one independent pointer on a yes or no side.
+type Source struct {
+	ID    string `json:"id"`
+	Kind  string `json:"kind"`
+	When  string `json:"when,omitempty"`
+	Stale bool   `json:"stale,omitempty"`
+}
+
+// Claim is one assertion with yes/no evidence lists.
+type Claim struct {
+	Text string   `json:"text"`
+	Yes  []Source `json:"yes"`
+	No   []Source `json:"no"`
+}
+
+// Result is audit output. Confirmed=false means `(not confirmed)`.
+type Result struct {
+	Text       string `json:"text"`
+	Confidence string `json:"confidence"`
+	Confirmed  bool   `json:"confirmed"`
+	Rule       string `json:"rule"`
+	Winner     string `json:"winner,omitempty"`
+	YesN       int    `json:"yes"`
+	NoN        int    `json:"no"`
+}
+
+func independent(ss []Source) int {
+	seen := map[string]struct{}{}
+	for i, s := range ss {
+		id := s.ID
+		if id == "" {
+			id = s.Kind + "#" + strconv.Itoa(i)
+		}
+		seen[id] = struct{}{}
+	}
+	return len(seen)
+}
+
+func freshN(ss []Source) int {
+	n := 0
+	for _, s := range ss {
+		if !s.Stale {
+			n++
+		}
+	}
+	return n
+}
+
+func strongN(ss []Source) int {
+	n := 0
+	for _, s := range ss {
+		if s.Kind == KindRuntime || s.Kind == KindConfig {
+			n++
+		}
+	}
+	return n
+}
+
+func out(c Claim, conf, rule, winner string) Result {
+	return Result{
+		Text:       c.Text,
+		Confidence: conf,
+		Confirmed:  conf == ConfConfirmed,
+		Rule:       rule,
+		Winner:     winner,
+		YesN:       independent(c.Yes),
+		NoN:        independent(c.No),
+	}
+}
+
+// Adjudicate applies D16: ≥2 yes vs ≥2 no stays hypothesis until a rule fires.
+// Order: temporal_freshness, then authority_pairing (A/B beats narrative C).
+func Adjudicate(c Claim) Result {
+	yesN := independent(c.Yes)
+	noN := independent(c.No)
+	if yesN < 2 || noN < 2 {
+		if yesN >= 2 {
+			return out(c, ConfConfirmed, RuleTwoSource, "yes")
+		}
+		if noN >= 2 {
+			return out(c, ConfConfirmed, RuleTwoSource, "no")
+		}
+		return out(c, ConfHypothesis, RuleSingleSource, "")
+	}
+	yf, nf := freshN(c.Yes), freshN(c.No)
+	if yf >= 2 && nf < 2 {
+		return out(c, ConfConfirmed, RuleTemporalFreshness, "yes")
+	}
+	if nf >= 2 && yf < 2 {
+		return out(c, ConfConfirmed, RuleTemporalFreshness, "no")
+	}
+	ys, ns := strongN(c.Yes), strongN(c.No)
+	if ys >= 2 && ns < 2 {
+		return out(c, ConfConfirmed, RuleAuthorityPairing, "yes")
+	}
+	if ns >= 2 && ys < 2 {
+		return out(c, ConfConfirmed, RuleAuthorityPairing, "no")
+	}
+	return out(c, ConfHypothesis, RuleUnresolved, "")
+}

internal/facts/contradict_test.go

@@ -0,0 +1,86 @@
+package facts
+
+import "testing"
+
+func src(id, kind string, stale bool) Source {
+	return Source{ID: id, Kind: kind, Stale: stale}
+}
+
+func TestTwoVsTwoStaysHypothesis(t *testing.T) {
+	c := Claim{
+		Text: "svc listens on 443",
+		Yes: []Source{
+			src("docker-ps", KindRuntime, false),
+			src("compose", KindConfig, false),
+		},
+		No: []Source{
+			src("docker-ps-old", KindRuntime, false),
+			src("compose-old", KindConfig, false),
+		},
+	}
+	r := Adjudicate(c)
+	if r.Confirmed || r.Confidence != ConfHypothesis || r.Rule != RuleUnresolved {
+		t.Fatalf("2v2 must stay (not confirmed): %+v", r)
+	}
+	if r.Winner != "" {
+		t.Fatalf("unresolved must not name a winner: %+v", r)
+	}
+}
+
+func TestTemporalFreshnessResolvesStaleSide(t *testing.T) {
+	c := Claim{
+		Text: "svc listens on 443",
+		Yes: []Source{
+			src("docker-ps", KindRuntime, false),
+			src("compose", KindConfig, false),
+		},
+		No: []Source{
+			src("old-readme", KindNarrative, true),
+			src("old-wiki", KindNarrative, true),
+		},
+	}
+	r := Adjudicate(c)
+	if !r.Confirmed || r.Rule != RuleTemporalFreshness || r.Winner != "yes" {
+		t.Fatalf("fresh yes vs stale no: %+v", r)
+	}
+}
+
+func TestAuthorityPairingBeatsNarrative(t *testing.T) {
+	c := Claim{
+		Text: "svc listens on 443",
+		Yes: []Source{
+			src("docker-ps", KindRuntime, false),
+			src("compose", KindConfig, false),
+		},
+		No: []Source{
+			src("readme", KindNarrative, false),
+			src("wiki", KindNarrative, false),
+		},
+	}
+	r := Adjudicate(c)
+	if !r.Confirmed || r.Rule != RuleAuthorityPairing || r.Winner != "yes" {
+		t.Fatalf("A×B vs C×C: %+v", r)
+	}
+}
+
+func TestTwoSourceYesIsConfirmed(t *testing.T) {
+	c := Claim{
+		Text: "arc-1 runs Matrix",
+		Yes: []Source{
+			src("compose", KindConfig, false),
+			src("docker-ps", KindRuntime, false),
+		},
+	}
+	r := Adjudicate(c)
+	if !r.Confirmed || r.Rule != RuleTwoSource || r.Winner != "yes" {
+		t.Fatalf("%+v", r)
+	}
+}
+
+func TestSingleSourceIsHypothesis(t *testing.T) {
+	c := Claim{Text: "maybe", Yes: []Source{src("readme", KindNarrative, false)}}
+	r := Adjudicate(c)
+	if r.Confirmed || r.Rule != RuleSingleSource {
+		t.Fatalf("%+v", r)
+	}
+}