rules: fail closed via viral CEL unknowns instead of dispatch gates (#633)

Replaces the dispatch-level truncation/unparseable pre-checks with
value-level unknowns from cel-go partial evaluation, and makes runtime
CEL evaluation errors fail closed.

* `match.Matcher.Match` is now three-valued (Matched / NoMatch /
  Unevaluable). On a Truncated or Unparseable request the matcher
  marks the affected facet paths (the declared `TruncatablePaths` /
  `UnparseablePaths`) as CEL unknowns via a partial activation
  (`cel.PartialVars` + `OptPartialEval`); the unknowns propagate
  virally, NaN-style, and surface as Unevaluable, which the
  dispatcher turns into a synthesized deny attributed to the rule
  whose contract broke
* More precise than the old reads-the-path gate: `&&`/`||`
  absorption lets a condition resolve honestly when its outcome
  doesn't depend on the unavailable value. `sql.verb == 'select' &&
  sql.database == 'x'` on an unparseable query against database 'y'
  now cleanly no-matches (`unknown && false == false`) instead of
  synth-denying; the symmetric `unknown || true` fires as written
* CEL eval errors no longer coerce to "no match" — a deny rule whose
  condition errors at runtime used to be silently skipped, failing
  open; it now synth-denies. The common case is selecting a
  `body_json` field the payload doesn't carry — or a missing map key
  like `k8s.params.stdin`. Guard optional fields with `has()` /
  `'key' in map`. `has()` cannot rescue a *truncated* field: the
  presence test itself is unknown
* Agent-visible deny reasons carry only the rule name and the coarse
  cause (truncated / unparseable / evaluation error); the full
  detail — unknown facet paths or the raw CEL error text — goes to
  the gateway log. cel-go errors like `no such key: <field>` would
  otherwise let an agent probe which fields a rule inspects by
  varying payloads and reading deny reasons
* New `runtime.MatchRequestFailClosed` backstop for SQL frontends
  (postgres, clickhouse_native): when a truncated or unparseable
  request matches no rule on an endpoint that declares rules, it
  denies instead of riding the implicit-allow default — "no rule
  matched" may just mean every condition resolved independent of the
  missing bytes. Rule-less endpoints keep pass-through; the HTTPS
  path keeps plain MatchRequest (rule-less LLM endpoints routinely
  forward >cap bodies)
* `InspectsTruncatableFacet` stays as the compile-time laziness
  signal (`CompiledEndpoint.InspectsTruncatable` / ssh stdin
  buffering); `InspectsUnparseableFacet` is removed along with the
  dispatch gate. `OptPartialEval` and the unknown-pattern slices are
  built only for conditions that reference a truncatable /
  unparseable path, keeping cel-go's default attribute factory on
  the hot path
* New tests pin the absorption semantics, the strict-error deny, the
  has() guard behavior on captured vs truncated bodies, unknown
  propagation through `==` / `in` / `exists()`, reason sanitization,
  and the SQL backstop; the `clawpatrol test` fixture corpus passes
  unchanged
* Docs: rules.md gains a unified "Unevaluable conditions fail
  closed" section covering truncation, parser refusal, eval errors,
  and the SQL backstop; adds the missing ssh stdin row to the
  inspection-cap table; the body_json and k8s-no-interactive
  examples use guards; plugins.md documents that the optional-field
  zero-fill covers declared fields only

Author: piscisaureus

cmd/clawpatrol/main.go

@@ -1978,8 +1978,8 @@ func bufferHTTPBodyForMatch(req *http.Request, capBytes int) []byte {
 // front of the original stream so upstream still receives the body
 // byte-for-byte. truncated is true iff the body extended beyond
 // maxHTTPMatchBody; callers stash this on match.Request.Truncated so
-// the dispatcher can fail-close rules that read http.body /
-// http.body_json.
+// http.body / http.body_json become CEL unknowns and rules whose
+// outcome depends on them fail-close.
 func bufferHTTPBodyForMatchTruncated(req *http.Request, capBytes int) (body []byte, truncated bool) {
 	if req.Body == nil {
 		return nil, false

internal/config/compile_test.go

@@ -92,17 +92,17 @@ func TestCompile(t *testing.T) {
 	}
 	getReq := &match.Request{Family: "http", Method: "GET"}
 	postReq := &match.Request{Family: "http", Method: "POST"}
-	if !reads.Matcher.Match(getReq) {
+	if reads.Matcher.Match(getReq).Result != match.Matched {
 		t.Errorf("github-reads should match GET")
 	}
-	if reads.Matcher.Match(postReq) {
-		t.Errorf("github-reads should NOT match POST")
+	if got := reads.Matcher.Match(postReq).Result; got != match.NoMatch {
+		t.Errorf("github-reads should NOT match POST, got %v", got)
 	}
-	if !writes.Matcher.Match(postReq) {
+	if writes.Matcher.Match(postReq).Result != match.Matched {
 		t.Errorf("github-writes should match POST")
 	}
-	if writes.Matcher.Match(getReq) {
-		t.Errorf("github-writes should NOT match GET")
+	if got := writes.Matcher.Match(getReq).Result; got != match.NoMatch {
+		t.Errorf("github-writes should NOT match GET, got %v", got)
 	}
 
 	// Outcomes wired correctly.

internal/config/extplugin/adapter.go

@@ -394,8 +394,8 @@ func handleEvaluate(ctx context.Context, ch *runtime.ConnHandle, ev *pb.Evaluate
 	// Build a match.Request rich enough for the matcher AND for the
 	// HITL prompt fields a human approver might render. Truncated
 	// is set when at least one stream field hit its cap before
-	// EOF — runtime.MatchRequest's fail-closed gate then auto-denies
-	// any rule whose matcher reads a stream-typed field.
+	// EOF — the matcher then marks stream-typed fields CEL-unknown
+	// and any rule whose outcome depends on one is denied.
 	var req *match.Request
 	if pf != nil {
 		req = &match.Request{

internal/config/extplugin/celenv.go

@@ -19,11 +19,12 @@ import (
 //
 // streamFields names the FACET_STREAM fields on the facet. They're
 // passed to match.CompileCondition as truncatablePaths so the
-// dispatcher's existing fail-closed-on-truncation gate applies to
-// plugin facets too: when the gateway's pullStream had to cap a
-// stream short of EOF, the EvaluateAction handler sets
-// Request.Truncated and runtime.MatchRequest auto-denies any rule
-// whose CEL condition reads the stream-typed bytes.
+// fail-closed-on-truncation contract applies to plugin facets too:
+// when the gateway's pullStream had to cap a stream short of EOF,
+// the EvaluateAction handler sets Request.Truncated, the matcher
+// marks the stream-typed paths as CEL unknowns, and any rule whose
+// condition outcome depends on the capped bytes evaluates
+// Unevaluable — which runtime.MatchRequest turns into a deny.
 //
 // The returned matcher additionally implements SubFieldReferencer
 // so the gateway adapter can decide, per evaluation, which
@@ -81,21 +82,17 @@ type pluginMatcher struct {
 	subFieldRefs map[string]bool
 }
 
-func (m *pluginMatcher) Match(req *match.Request) bool { return m.inner.Match(req) }
+func (m *pluginMatcher) Match(req *match.Request) match.Decision { return m.inner.Match(req) }
 
-// InspectsTruncatableFacet forwards the inner CEL matcher's
-// answer. The dispatcher uses it together with Request.Truncated
-// to fail-close any rule that reads a stream-typed field on a
-// request the gateway had to cap mid-pull.
+// InspectsTruncatableFacet forwards the inner CEL matcher's answer —
+// the compile-time laziness signal that tells the adapter whether
+// any rule needs a stream-typed field pulled in full. Verdicts on
+// truncated streams come from the inner matcher's Unevaluable result
+// (the stream fields are marked CEL-unknown on a Truncated request).
 func (m *pluginMatcher) InspectsTruncatableFacet() bool {
 	return m.inner.InspectsTruncatableFacet()
 }
 
-// InspectsUnparseableFacet always returns false: plugin facets have
-// no parser failure mode (see newPluginFacetMatcher's nil unparseable
-// path), so the Unparseable gate is structurally a no-op here.
-func (m *pluginMatcher) InspectsUnparseableFacet() bool { return false }
-
 // References preserves whatever the inner matcher reports so the
 // gateway's existing body-buffering check (top-level identifier
 // reachability) keeps working.

internal/config/extplugin/facet.go

@@ -41,8 +41,8 @@ type pluginFacet struct {
 	optionalFields map[string]bool
 	// streamFields lists the FACET_STREAM field names. Passed to
 	// the CEL compiler as truncatablePaths so the dispatcher's
-	// fail-closed-on-truncation gate (req.Truncated +
-	// matcher.InspectsTruncatableFacet) applies to plugin facets.
+	// fail-closed-on-truncation contract (req.Truncated marks the
+	// stream paths CEL-unknown) applies to plugin facets.
 	streamFields []string
 }
 

internal/config/facet/composition.go

@@ -13,7 +13,8 @@ import (
 // matcher: env options that declare its variable(s) and the Go types
 // behind them, an activation builder that populates its bindings on
 // the request's activation map, and the path lists CompileCondition
-// needs for case-normalization and truncation-fail-close.
+// needs for case-normalization and the unevaluable-fail-close
+// contract (truncated / unparseable values become CEL unknowns).
 //
 // Built-in facets return their own contribution via CELContributor.
 // Composition (a k8s_rule referencing http.method) is performed in
@@ -27,18 +28,19 @@ import (
 //
 // AddActivation writes the facet's bindings into act. It returns
 // false to refuse the match (e.g. wrong Meta type for the family);
-// when any contributor refuses, the composed matcher's Match returns
-// false without evaluating the CEL program.
+// when any contributor refuses, the composed matcher's Match reports
+// Unevaluable (fail closed) without evaluating the CEL program.
 type CELContrib struct {
 	EnvOptions       []cel.EnvOption
 	AddActivation    func(req *match.Request, act map[string]any) bool
 	LowercasedPaths  []string
 	TruncatablePaths []string
 	// UnparseablePaths lists the fields a wire frontend's parser
 	// derives from the request bytes — when the parser refuses the
-	// input, the frontend sets req.Unparseable=true and the
-	// dispatcher auto-denies any rule whose CEL reads one of these
-	// paths. Empty for facets with no parser-failure mode (http, k8s).
+	// input, the frontend sets req.Unparseable=true and the matcher
+	// marks these paths as CEL unknowns: any rule whose condition
+	// outcome depends on one evaluates Unevaluable and is denied.
+	// Empty for facets with no parser-failure mode (http, k8s).
 	UnparseablePaths []string
 }