fix(coverage): count coverage gaps by one shared rule

The snapshot receipt classified a service as a coverage gap whenever it
had any unresolved outbound call site, while coverage_report and the
coverage explainer both required outbound == 0 — no resolved edges at
all. Since unresolved is derived as detected - resolved - external, every
healthy client service has some, so the receipt's metric saturated: it
equalled services_total on healthy input and could not signal ill health.
llm_context.md prints that number behind a warning sign, so the file an
agent reads without a tool call carried the inflated count.

Hoist the rule into facts.ClassifyService, with facts.DependsOnCount
replacing the two duplicate outbound counters. coverageSummary,
buildCoverageReport and the coverage explainer now all classify through
it, so they cannot drift apart again. Also decouple UnresolvedEdges from
the gap condition — it accumulates for every service, gapped or not.

On a four-service multi-repo snapshot the receipt now agrees with
coverage_report; unresolved_edges is unchanged. facts.jsonl and
insights.json are byte-identical across the change.

No cacheVersion bump: coverageSummary feeds receipt.json only (via both
engine.go and global_receipt.go), no extractor output changes, and
TestGolden passes without -update.

The existing svcCoverage test helper attaches no relations, so every
fixture had outbound == 0 and TestCoverageSummary_ExternalBucket returned
the same answer under either rule. Add the case that distinguishes them.

Author: dejo1307

internal/engine/coverage_summary_test.go

@@ -5,6 +5,7 @@ package engine
 // and excluded from the internal blind-spot count (unresolved) and gap tally.
 
 import (
+	"fmt"
 	"testing"
 
 	"github.com/enola-labs/enola/internal/facts"
@@ -28,12 +29,49 @@ func svcCoverage(name string, resolved, unresolved, external int) facts.Fact {
 	}
 }
 
+// withDeps attaches n resolved outbound cross-repo dependencies to a service node.
+// Without this, every fixture has outbound == 0, which is the one input that tells
+// a coverage gap apart from a merely partially-covered service.
+func withDeps(f facts.Fact, n int) facts.Fact {
+	for i := 0; i < n; i++ {
+		f.Relations = append(f.Relations, facts.Relation{
+			Kind:   facts.RelDependsOn,
+			Target: fmt.Sprintf("dep-%d", i),
+		})
+	}
+	return f
+}
+
+// A service with a resolved outbound edge is "partial coverage", which both
+// coverage_report and the coverage explainer classify as connected — not a gap.
+// The receipt must agree with them.
+func TestCoverageSummary_PartiallyCoveredServiceIsNotAGap(t *testing.T) {
+	st := facts.NewStore()
+	st.Add(
+		withDeps(svcCoverage("partial", 5, 2, 0), 1), // resolved edge + unresolved -> connected
+		svcCoverage("gap", 0, 3, 0),                  // no resolved edge + unresolved -> gap
+		withDeps(svcCoverage("clean", 4, 0, 0), 1),   // nothing unresolved -> connected
+	)
+
+	sum := coverageSummary(st)
+	if sum == nil {
+		t.Fatal("expected a CoverageSummary")
+	}
+	if sum.CoverageGaps != 1 {
+		t.Errorf("CoverageGaps = %d, want 1 (only the service with no resolved outbound edge)", sum.CoverageGaps)
+	}
+	// UnresolvedEdges must keep accumulating across every service, gapped or not.
+	if sum.UnresolvedEdges != 5 {
+		t.Errorf("UnresolvedEdges = %d, want 5 (2+3, counted regardless of classification)", sum.UnresolvedEdges)
+	}
+}
+
 func TestCoverageSummary_ExternalBucket(t *testing.T) {
 	st := facts.NewStore()
 	st.Add(
-		svcCoverage("a", 5, 2, 0),  // 2 internal unresolved -> a coverage gap
-		svcCoverage("b", 4, 0, 3),  // only external -> NOT a gap
-		svcCoverage("c", 1, 1, 4),  // both -> gap, external counted separately
+		svcCoverage("a", 5, 2, 0), // 2 internal unresolved -> a coverage gap
+		svcCoverage("b", 4, 0, 3), // only external -> NOT a gap
+		svcCoverage("c", 1, 1, 4), // both -> gap, external counted separately
 	)
 
 	sum := coverageSummary(st)

internal/engine/receipt.go

@@ -105,19 +105,25 @@ func runGit(repoPath string, args ...string) (string, error) {
 // coverageSummary rolls up the per-service edge_coverage counts the cross-repo
 // linker records into a single snapshot-level summary. It returns nil for a
 // single-repo snapshot (no service nodes), matching the coverage explainer.
+//
+// A gap is counted through facts.ClassifyService, so the receipt, coverage_report
+// and the coverage explainer cannot drift apart. UnresolvedEdges accumulates for
+// every service regardless of class — a partially-covered service still has blind
+// spots worth reporting, it just is not a gap.
 func coverageSummary(store *facts.Store) *facts.CoverageSummary {
 	services := store.ByKind(facts.KindService)
 	if len(services) == 0 {
 		return nil
 	}
 	sum := &facts.CoverageSummary{ServicesTotal: len(services)}
 	for _, svc := range services {
+		detected := readCoverageField(svc, "detected")
 		unresolved := readCoverageField(svc, "unresolved")
-		if unresolved > 0 {
+		sum.UnresolvedEdges += unresolved
+		sum.ExternalEdges += readCoverageField(svc, "external")
+		if facts.ClassifyService(facts.DependsOnCount(svc), detected, unresolved) == facts.ServiceCoverageGap {
 			sum.CoverageGaps++
-			sum.UnresolvedEdges += unresolved
 		}
-		sum.ExternalEdges += readCoverageField(svc, "external")
 	}
 	return sum
 }

internal/explainers/coverage/coverage.go

@@ -44,11 +44,11 @@ func (e *CoverageExplainer) Explain(ctx context.Context, store *facts.Store) ([]
 			continue
 		}
 
-		outbound := dependsOnCount(svc)
+		outbound := facts.DependsOnCount(svc)
 		evidence := []facts.Evidence{{Fact: svc.Name, Detail: coverageDetail(cov)}}
 
 		var insight facts.Insight
-		if outbound == 0 {
+		if facts.ClassifyService(outbound, detected, unresolved) == facts.ServiceCoverageGap {
 			insight = facts.Insight{
 				Title: fmt.Sprintf("Coverage gap: service %s appears isolated but has %d unresolved outbound call site(s)",
 					svc.Name, unresolved),
@@ -106,18 +106,6 @@ func coverageDetail(cov []coverageEntry) string {
 	return out
 }
 
-// dependsOnCount returns how many resolved outbound (cross-repo) dependencies a
-// service node carries.
-func dependsOnCount(svc facts.Fact) int {
-	n := 0
-	for _, rel := range svc.Relations {
-		if rel.Kind == facts.RelDependsOn {
-			n++
-		}
-	}
-	return n
-}
-
 // readCoverage extracts the edge_coverage entries from a service node's props,
 // tolerating both the in-memory shape ([]map[string]any with int values) and the
 // shape that survives a facts.jsonl JSON round-trip ([]any of map[string]any with

internal/facts/coverage.go

@@ -0,0 +1,53 @@
+package facts
+
+// Service coverage classifications. A service node's class answers "did enola
+// resolve this repo's outbound calls, and if not, is that a blind spot or is the
+// repo genuinely a leaf?"
+const (
+	// ServiceConnected: at least one outbound call site resolved to a loaded repo.
+	// Some call sites may still be unresolved (an unloaded repo, a third-party API);
+	// that is partial coverage, not a blind spot.
+	ServiceConnected = "connected"
+	// ServiceCoverageGap: nothing resolved, yet outbound call sites were detected.
+	// The repo looks isolated but almost certainly is not — verify against source.
+	ServiceCoverageGap = "coverage_gap"
+	// ServiceIsolated: no resolved outbound edges and nothing unresolved to explain
+	// them away — genuinely a leaf.
+	ServiceIsolated = "isolated"
+)
+
+// ClassifyService is the single definition of a service's cross-repo coverage
+// class. The snapshot receipt (internal/engine), coverage_report (internal/server)
+// and the coverage explainer all classify through here; they previously each
+// carried their own copy and the receipt's had drifted, counting every service
+// with any unresolved call site as a gap. Because unresolved is derived as
+// detected-resolved-external, that made the metric saturate — on a healthy
+// multi-repo snapshot every client has some unresolved call site, so the count
+// equalled the number of services and could not signal ill health.
+//
+// outbound is the count of resolved outbound cross-repo dependencies (see
+// DependsOnCount); detected and unresolved are summed across the service's
+// edge_coverage entries.
+func ClassifyService(outbound, detected, unresolved int) string {
+	if outbound > 0 {
+		return ServiceConnected
+	}
+	// external-only call sites are expected, not a blind spot, so a service with no
+	// resolved edges but only external calls stays isolated, not a gap.
+	if detected > 0 && unresolved > 0 {
+		return ServiceCoverageGap
+	}
+	return ServiceIsolated
+}
+
+// DependsOnCount returns how many resolved outbound (cross-repo) dependencies a
+// service node carries.
+func DependsOnCount(svc Fact) int {
+	n := 0
+	for _, rel := range svc.Relations {
+		if rel.Kind == RelDependsOn {
+			n++
+		}
+	}
+	return n
+}

internal/facts/coverage_test.go

@@ -0,0 +1,49 @@
+package facts
+
+import "testing"
+
+func TestClassifyService(t *testing.T) {
+	tests := []struct {
+		name                           string
+		outbound, detected, unresolved int
+		want                           string
+	}{
+		{"resolved edge, everything covered", 1, 4, 0, ServiceConnected},
+		{"resolved edge plus unresolved is partial coverage, not a gap", 1, 4, 1, ServiceConnected},
+		{"many unresolved still connected while one edge resolved", 1, 1219, 342, ServiceConnected},
+		{"nothing resolved but call sites detected", 0, 3, 3, ServiceCoverageGap},
+		{"genuine leaf", 0, 0, 0, ServiceIsolated},
+		{"external-only call sites are expected, not a blind spot", 0, 3, 0, ServiceIsolated},
+		// unresolved is derived as detected-resolved-external, so unresolved>0 with
+		// detected==0 cannot arise from the linker. A hand-authored or truncated fact
+		// can still produce it; classify it isolated rather than inventing a gap.
+		{"unresolved without detected", 0, 0, 2, ServiceIsolated},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := ClassifyService(tt.outbound, tt.detected, tt.unresolved); got != tt.want {
+				t.Errorf("ClassifyService(%d, %d, %d) = %q, want %q",
+					tt.outbound, tt.detected, tt.unresolved, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestDependsOnCount(t *testing.T) {
+	svc := Fact{
+		Kind: KindService,
+		Name: "svc",
+		Relations: []Relation{
+			{Kind: RelDependsOn, Target: "a"},
+			{Kind: RelCalls, Target: "b"},
+			{Kind: RelDependsOn, Target: "c"},
+			{Kind: RelImports, Target: "d"},
+		},
+	}
+	if got := DependsOnCount(svc); got != 2 {
+		t.Errorf("DependsOnCount = %d, want 2 (only depends_on relations)", got)
+	}
+	if got := DependsOnCount(Fact{Kind: KindService, Name: "leaf"}); got != 0 {
+		t.Errorf("DependsOnCount(no relations) = %d, want 0", got)
+	}
+}

internal/facts/model.go

@@ -231,7 +231,7 @@ type ParseError struct {
 // without the consumer running coverage_report.
 type CoverageSummary struct {
 	ServicesTotal   int `json:"services_total"`
-	CoverageGaps    int `json:"coverage_gaps"`            // services with unresolved (internal) outbound call sites
+	CoverageGaps    int `json:"coverage_gaps"`            // services classified ServiceCoverageGap: no resolved outbound edge, yet unresolved call sites were detected. A service that resolved some edges is partially covered, not a gap
 	UnresolvedEdges int `json:"unresolved_edges"`         // detected outbound edges that did not resolve to a loaded service (internal blind spots; excludes external)
 	ExternalEdges   int `json:"external_edges,omitempty"` // detected outbound edges to hardcoded external hosts (third-party APIs) — expected, not a blind spot
 }

internal/server/server.go

@@ -1437,12 +1437,7 @@ func buildCoverageReport(store *facts.Store, repo string) []serviceCoverage {
 			continue
 		}
 
-		outbound := 0
-		for _, rel := range svc.Relations {
-			if rel.Kind == facts.RelDependsOn {
-				outbound++
-			}
-		}
+		outbound := facts.DependsOnCount(svc)
 
 		cov := readEdgeCoverage(svc)
 		detected, unresolved, external := 0, 0, 0
@@ -1452,20 +1447,9 @@ func buildCoverageReport(store *facts.Store, repo string) []serviceCoverage {
 			external += c.External
 		}
 
-		class := "connected"
-		if outbound == 0 {
-			// external-only call sites are expected, not a blind spot, so a service
-			// with no resolved edges but only external calls stays isolated, not a gap.
-			if detected > 0 && unresolved > 0 {
-				class = "coverage_gap"
-			} else {
-				class = "isolated"
-			}
-		}
-
 		out = append(out, serviceCoverage{
 			Service:         svc.Name,
-			Classification:  class,
+			Classification:  facts.ClassifyService(outbound, detected, unresolved),
 			OutboundEdges:   outbound,
 			EdgeCoverage:    cov,
 			UnresolvedTotal: unresolved,
@@ -1531,7 +1515,7 @@ func renderCoverageReport(report []serviceCoverage) string {
 
 	gaps := 0
 	for _, sc := range report {
-		if sc.Classification == "coverage_gap" {
+		if sc.Classification == facts.ServiceCoverageGap {
 			gaps++
 		}
 	}