@@ -313,7 +313,7 @@ func TestPreflightMatrixNeverIndexedWhileConnecting(t *testing.T) {
313313// preflightParityComparedFields are the per-result fields the parity loop
314314// asserts equal between the two surfaces, by their wire names.
315315//
316- // preflightParityExcludedFields are the ONLY fields allowed to differ, each with
316+ // The per-surface exclusion maps below name the ONLY fields allowed to differ, each with
317317// the reason it does. FR-017 requires the exclusions to be named rather than
318318// expressed as "whatever the loop happens not to touch": an omission is
319319// invisible, a name is reviewable. TestPreflightParityExclusionsAreNamed turns
@@ -322,13 +322,22 @@ func TestPreflightMatrixNeverIndexedWhileConnecting(t *testing.T) {
322322var (
323323 preflightParityComparedFields = []string {"id" , "status" , "reason" , "retryable" , "action" , "detail" , "remediation" , "did_you_mean" }
324324
325- preflightParityExcludedFields = map [string ]string {
325+ // Exclusions are scoped PER SURFACE: a reason that justifies excluding a
326+ // field from one payload says nothing about the other. A globally excluded
327+ // "hash" would let a future hash field on the MCP payload silently escape
328+ // comparison even though FR-004 forbids it there — the exact narrowing
329+ // FR-017's "by name" rule exists to prevent.
330+ preflightParityExcludedMCPFields = map [string ]string {
326331 "checked_at" : "a timestamp, not a verdict: each surface stamps its own instant (FR-004)" ,
327- "hash" : "REST may disclose a pin at the operator tier; in band, never, at any tier (FR-004)" ,
328332 "request_id" : "in-band only: the correlation id an agent hands a human (FR-004)" ,
329- "waited_ms" : "REST only: check mode takes no wait budget (non-goal)" ,
330333 "verdict" : "compared once at the set level, not per result" ,
331334 "results" : "the in-band container of the compared results" ,
335+ }
336+ preflightParityExcludedRESTFields = map [string ]string {
337+ "checked_at" : "a timestamp, not a verdict: each surface stamps its own instant (FR-004)" ,
338+ "hash" : "REST may disclose a pin at the operator tier; in band, never, at any tier (FR-004)" ,
339+ "waited_ms" : "REST only: check mode takes no wait budget (non-goal)" ,
340+ "verdict" : "compared once at the set level, not per result" ,
332341 "tools" : "the REST container of the compared results" ,
333342 }
334343)
@@ -341,32 +350,55 @@ func TestPreflightParityExclusionsAreNamed(t *testing.T) {
341350 compared := make (map [string ]bool , len (preflightParityComparedFields ))
342351 for _ , name := range preflightParityComparedFields {
343352 compared [name ] = true
344- assert .NotContainsf (t , preflightParityExcludedFields , name ,
345- "%q cannot be both compared and excluded" , name )
353+ assert .NotContainsf (t , preflightParityExcludedMCPFields , name ,
354+ "%q cannot be both compared and MCP-excluded" , name )
355+ assert .NotContainsf (t , preflightParityExcludedRESTFields , name ,
356+ "%q cannot be both compared and REST-excluded" , name )
346357 }
347358
348- for _ , payload := range []any {
349- describeCheckResult {}, describeCheckPayload {},
350- contracts.PreflightToolResult {}, contracts.PreflightResponse {},
351- } {
352- typ := reflect .TypeOf (payload )
353- for i := 0 ; i < typ .NumField (); i ++ {
354- name , _ , _ := strings .Cut (typ .Field (i ).Tag .Get ("json" ), "," )
355- require .NotEmptyf (t , name , "%s.%s has no json tag" , typ .Name (), typ .Field (i ).Name )
356- if compared [name ] {
357- continue
359+ surfaces := []struct {
360+ payloads []any
361+ excluded map [string ]string
362+ surface string
363+ }{
364+ {[]any {describeCheckResult {}, describeCheckPayload {}}, preflightParityExcludedMCPFields , "mcp-check" },
365+ {[]any {contracts.PreflightToolResult {}, contracts.PreflightResponse {}}, preflightParityExcludedRESTFields , "rest" },
366+ }
367+ for _ , sf := range surfaces {
368+ for _ , payload := range sf .payloads {
369+ typ := reflect .TypeOf (payload )
370+ for i := 0 ; i < typ .NumField (); i ++ {
371+ name , _ , _ := strings .Cut (typ .Field (i ).Tag .Get ("json" ), "," )
372+ require .NotEmptyf (t , name , "%s.%s has no json tag" , typ .Name (), typ .Field (i ).Name )
373+ if compared [name ] {
374+ continue
375+ }
376+ _ , excluded := sf .excluded [name ]
377+ assert .Truef (t , excluded ,
378+ "%s.%s (%q) is neither compared by the parity test nor excluded from it by name on the %s surface" ,
379+ typ .Name (), typ .Field (i ).Name , name , sf .surface )
380+ }
381+ }
382+ // The reverse direction: an exclusion that names no real field on its
383+ // own surface is stale and must be pruned, not carried.
384+ for name := range sf .excluded {
385+ found := false
386+ for _ , payload := range sf .payloads {
387+ typ := reflect .TypeOf (payload )
388+ for i := 0 ; i < typ .NumField (); i ++ {
389+ if tag , _ , _ := strings .Cut (typ .Field (i ).Tag .Get ("json" ), "," ); tag == name {
390+ found = true
391+ }
392+ }
358393 }
359- _ , excluded := preflightParityExcludedFields [name ]
360- assert .Truef (t , excluded ,
361- "%s.%s (%q) is neither compared by the parity test nor excluded from it by name" ,
362- typ .Name (), typ .Field (i ).Name , name )
394+ assert .Truef (t , found , "excluded field %q names no field on the %s surface" , name , sf .surface )
363395 }
364396 }
365397}
366398
367399// For identical ids and identical proxy state, the in-band surface and the REST
368400// surface AT THE SAME TIER name the same thing. The two payloads deliberately
369- // differ only on the fields named in preflightParityExcludedFields — excluded by
401+ // differ only on the fields named in the per-surface exclusion maps — excluded by
370402// name, not by a loose matcher — and anything else that differs is a defect in
371403// the glue.
372404func TestPreflightInBandRESTParityAtAgentTokenTier (t * testing.T ) {
0 commit comments