File size: 233,222 Bytes
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
72b6f27
19b91ce
149aa87
fba6beb
149aa87
8510233
149aa87
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
fba6beb
4cfab62
 
 
 
 
 
 
 
 
 
 
 
8510233
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
103a492
4cfab62
103a492
3fac176
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
103a492
3fac176
19aed6d
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
19aed6d
 
 
 
 
 
 
 
 
 
 
 
 
4cfab62
 
 
 
 
19aed6d
4cfab62
 
 
 
 
 
 
19aed6d
 
 
4cfab62
 
72b6f27
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
f462120
 
4cfab62
 
 
103a492
4cfab62
 
 
 
103a492
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
103a492
4cfab62
 
 
 
8133df9
 
 
 
 
4cfab62
 
 
3294477
 
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
19aed6d
 
 
 
 
 
 
 
 
 
 
 
 
c1fc133
 
 
 
 
19aed6d
4cfab62
 
19aed6d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4cfab62
 
19aed6d
4cfab62
19aed6d
 
 
4cfab62
19aed6d
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
19aed6d
 
 
 
 
 
 
 
 
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
72b6f27
 
 
 
 
74f72af
 
 
 
 
 
 
 
c8c42eb
 
 
 
 
74f72af
c8c42eb
72b6f27
 
52c6936
 
 
c8c42eb
 
52c6936
c8c42eb
 
52c6936
 
72b6f27
52c6936
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
72b6f27
 
c8c42eb
 
 
 
72b6f27
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
52c6936
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
72b6f27
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
c8c42eb
 
 
52c6936
 
 
 
 
 
 
 
 
 
72b6f27
 
 
 
 
 
 
 
 
 
 
52c6936
 
 
 
72b6f27
52c6936
 
 
 
 
 
 
72b6f27
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
52c6936
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
72b6f27
 
19b91ce
72b6f27
 
 
 
 
 
 
 
 
19b91ce
 
 
 
 
 
 
 
 
 
 
72b6f27
e174d2c
 
 
 
 
 
72b6f27
 
 
 
 
 
 
 
 
 
 
 
 
 
 
19b91ce
 
 
72b6f27
 
 
 
 
 
 
 
 
 
 
 
19b91ce
72b6f27
 
 
 
19b91ce
 
72b6f27
 
 
 
 
 
 
 
 
 
 
e174d2c
 
 
72b6f27
c8c42eb
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
74f72af
c8c42eb
 
 
 
74f72af
 
 
 
 
 
 
 
 
 
72b6f27
 
 
 
 
 
 
19b91ce
e174d2c
 
19b91ce
 
 
 
 
 
 
 
 
 
52c6936
 
 
 
 
 
19b91ce
72b6f27
 
74f72af
 
 
 
 
 
 
 
 
 
 
c8c42eb
 
74f72af
c8c42eb
 
 
74f72af
 
 
e174d2c
 
 
c8c42eb
e174d2c
 
c8c42eb
 
 
 
 
 
 
e174d2c
 
 
c8c42eb
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
e174d2c
74f72af
 
 
 
 
 
 
 
 
 
 
 
 
c8c42eb
 
e174d2c
 
c8c42eb
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
74f72af
 
72b6f27
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
19b91ce
72b6f27
19b91ce
72b6f27
 
 
19b91ce
 
 
 
 
72b6f27
52c6936
72b6f27
 
c8c42eb
 
 
 
52c6936
 
 
 
 
 
 
 
 
 
 
 
c8c42eb
72b6f27
74f72af
 
 
 
 
 
 
 
 
e174d2c
 
74f72af
e174d2c
c8c42eb
74f72af
c8c42eb
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
72b6f27
 
c8c42eb
 
72b6f27
52c6936
 
72b6f27
 
19b91ce
72b6f27
19b91ce
72b6f27
 
19b91ce
72b6f27
 
 
19b91ce
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
74f72af
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
103a492
 
 
 
 
 
 
 
19b91ce
4cfab62
 
 
 
 
 
103a492
 
 
 
 
 
 
 
 
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
72b6f27
 
 
19b91ce
 
 
72b6f27
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
82cdb59
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b35f959
 
 
 
 
 
 
 
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
19b91ce
4cfab62
 
 
103a492
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
72b6f27
 
 
 
 
 
 
 
 
 
 
 
 
19b91ce
 
72b6f27
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b35f959
 
 
 
 
 
 
 
4cfab62
 
19b91ce
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
19b91ce
4cfab62
 
 
 
 
 
dec006b
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
f530297
 
 
 
 
4cfab62
72b6f27
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
19b91ce
4cfab62
 
 
 
 
 
 
 
 
 
 
 
f462120
4cfab62
 
 
 
 
 
 
 
f462120
 
4cfab62
 
f462120
 
 
 
 
 
 
 
 
 
 
4cfab62
 
 
 
 
19aed6d
4cfab62
 
 
 
 
 
8873406
 
 
 
 
 
 
 
4cfab62
 
 
 
 
19aed6d
 
4cfab62
 
816fa8a
 
 
103a492
4cfab62
 
971c29d
 
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1d4419b
 
 
 
 
 
 
 
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1d4419b
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
ce9586e
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
19b91ce
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
f530297
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
10ab9ba
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
ce9586e
 
 
 
e174d2c
 
 
 
 
4cfab62
10ab9ba
4cfab62
10ab9ba
 
 
 
 
 
8729c1d
 
 
 
 
 
 
4cfab62
 
 
 
 
8729c1d
 
10ab9ba
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
e174d2c
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
19b91ce
4cfab62
19b91ce
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
72b6f27
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
cca1264
 
 
 
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
cca1264
 
 
 
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b35f959
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
72b6f27
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8729c1d
 
 
 
 
 
 
 
 
 
 
 
4cfab62
f462120
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
f462120
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
f462120
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
19aed6d
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
19aed6d
 
 
 
4cfab62
19b91ce
 
 
 
 
 
 
f462120
 
 
 
 
 
4cfab62
 
 
 
 
 
19b91ce
4cfab62
 
 
 
 
 
 
 
 
 
1d4419b
 
 
 
 
 
 
 
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
72b6f27
 
 
 
 
 
 
 
 
 
 
4cfab62
f462120
8729c1d
f462120
 
 
 
 
4cfab62
 
8729c1d
 
 
 
 
 
19aed6d
 
 
 
 
4cfab62
 
 
 
19b91ce
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
19aed6d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
72b6f27
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
74faba6
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
74faba6
 
 
 
4cfab62
2e7e617
 
 
4cfab62
 
 
2e7e617
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2e7e617
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
c1fc133
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4cfab62
72b6f27
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
72b6f27
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
82cdb59
4cfab62
 
82cdb59
4cfab62
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
52c6936
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3928
3929
3930
3931
3932
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978
3979
3980
3981
3982
3983
3984
3985
3986
3987
3988
3989
3990
3991
3992
3993
3994
3995
3996
3997
3998
3999
4000
4001
4002
4003
4004
4005
4006
4007
4008
4009
4010
4011
4012
4013
4014
4015
4016
4017
4018
4019
4020
4021
4022
4023
4024
4025
4026
4027
4028
4029
4030
4031
4032
4033
4034
4035
4036
4037
4038
4039
4040
4041
4042
4043
4044
4045
4046
4047
4048
4049
4050
4051
4052
4053
4054
4055
4056
4057
4058
4059
4060
4061
4062
4063
4064
4065
4066
4067
4068
4069
4070
4071
4072
4073
4074
4075
4076
4077
4078
4079
4080
4081
4082
4083
4084
4085
4086
4087
4088
4089
4090
4091
4092
4093
4094
4095
4096
4097
4098
4099
4100
4101
4102
4103
4104
4105
4106
4107
4108
4109
4110
4111
4112
4113
4114
4115
4116
4117
4118
4119
4120
4121
4122
4123
4124
4125
4126
4127
4128
4129
4130
4131
4132
4133
4134
4135
4136
4137
4138
4139
4140
4141
4142
4143
4144
4145
4146
4147
4148
4149
4150
4151
4152
4153
4154
4155
4156
4157
4158
4159
4160
4161
4162
4163
4164
4165
4166
4167
4168
4169
4170
4171
4172
4173
4174
4175
4176
4177
4178
4179
4180
4181
4182
4183
4184
4185
4186
4187
4188
4189
4190
4191
4192
4193
4194
4195
4196
4197
4198
4199
4200
4201
4202
4203
4204
4205
4206
4207
4208
4209
4210
4211
4212
4213
4214
4215
4216
4217
4218
4219
4220
4221
4222
4223
4224
4225
4226
4227
4228
4229
4230
4231
4232
4233
4234
4235
4236
4237
4238
4239
4240
4241
4242
4243
4244
4245
4246
4247
4248
4249
4250
4251
4252
4253
4254
4255
4256
4257
4258
4259
4260
4261
4262
4263
4264
4265
4266
4267
4268
4269
4270
4271
4272
4273
4274
4275
4276
"""aios_grid β€” embed the AIOS React/glide Airtable-style grid inside Streamlit.

This is REUSABLE MODULE INFRASTRUCTURE: the same self-contained grid that runs as the
standalone aios-web app is inlined into a single HTML file and hosted inside a Streamlit
component. The React bundle reads its data from `window.__AIOS_GRID__` (an object
`{fields, rows}`) that we inject into the page <head> before the app's module script runs
β€” so there is NO backend and NO /api call in the Streamlit container; the browser only ever
sees the derived JSON we hand it.

Usage (from any page):
    import aios_grid
    aios_grid.render(aios_grid.rows_from_pool(pool_rows), aios_grid.FIELDS)

Design notes:
  * ZERO app-internal imports (no `modules.*` / `core.*`). FIELDS is a literal and
    `rows_from_pool` takes already-built rows β€” so this helper is tenant/module-agnostic and
    sidesteps deploy_hf.py's import guard entirely.
  * The built HTML ships as `aios_grid_embed.html` in THIS directory (added to
    deploy_hf.py INCLUDE). Build it with `npm run build:embed` in aios-web/web, then copy
    dist-embed/index.html -> platform/aios_grid_embed.html (see build_embed.py).
    For LOCAL dev before that copy, we fall back to reading dist-embed/index.html directly.
  * The preferred host is a Streamlit Components v1 bridge. It sends data/view/schema args
    into the React app and returns guarded events for persistence in the tenant store. The old
    injected-HTML path remains a read/local-write fallback when component assets are absent.
"""
import datetime as _dt
import copy
import json
import math
import re
from decimal import Decimal, ROUND_HALF_EVEN, localcontext
from pathlib import Path

_HERE = Path(__file__).resolve().parent

# Where the inlined single-file build lives. FIRST match wins:
#   1. the shipped copy in this dir (what deploy_hf.py uploads to the Space)
#   2. the raw build output in the sibling aios-web tree (local dev, pre-copy)
_EMBED_CANDIDATES = [
    _HERE / "aios_grid_embed.html",
    _HERE.parent / "aios-web" / "web" / "dist-embed" / "index.html",
]
_COMPONENT_CANDIDATES = [
    _HERE / "aios_grid_component",
    _HERE.parent / "aios-web" / "web" / "dist-embed",
]
_DECLARED_COMPONENTS = {}

# --- the FIELD CONTRACT β€” loaded from the CANONICAL source `aios_grid_fields.json` in THIS
# directory (the SINGLE source of truth, shared with aios-web/api/main.py). source='odoo' is
# READ-ONLY; source='overlay' is the editable stratum (notes/tags) that lives OUTSIDE Odoo.
#
# Why a sibling JSON and NOT an import: aios_grid.py's contract is ZERO app-internal imports so
# it stays tenant/module-agnostic and sidesteps deploy_hf.py's import guard. A JSON next to the
# module preserves that exactly β€” no import, no guard interaction β€” while still single-sourcing
# the values (a build-time copy from another tree would reintroduce the drift we're removing).
# The file ships to the Space via deploy_hf.py INCLUDE. Edit the JSON, then run
# aios-web/verify_fields_contract.py. ---
_FIELDS_PATH = _HERE / "aios_grid_fields.json"


def _load_fields():
    if not _FIELDS_PATH.is_file():
        raise FileNotFoundError(
            f"aios_grid: canonical field contract missing at {_FIELDS_PATH}. It is the single "
            "source of truth for the grid schema and MUST ship (deploy_hf.py INCLUDE lists it)."
        )
    doc = json.loads(_FIELDS_PATH.read_text(encoding="utf-8"))
    fields = doc.get("fields") if isinstance(doc, dict) else doc
    if not isinstance(fields, list) or not fields:
        raise ValueError(f"aios_grid: {_FIELDS_PATH} has no 'fields' list.")
    return fields


FIELDS = _load_fields()


def product_fields():
    """The PRODUCT table's canonical contract (wave 15 C-TOPIC, `product_data` key in the same
    JSON). A separate accessor rather than a second module constant so the one file-read and the
    one failure mode stay shared with `FIELDS`."""
    doc = json.loads(_FIELDS_PATH.read_text(encoding="utf-8"))
    fields = (doc.get("product_data") or {}).get("fields")
    if not isinstance(fields, list) or not fields:
        raise ValueError(f"aios_grid: {_FIELDS_PATH} has no product_data.fields list.")
    return fields

# text/date fields pass through untouched; every OTHER odoo (numeric) field is rounded β€”
# mirrors aios-web/api/main.py _payload() exactly so embed == standalone byte-for-byte.


def _round(v):
    return round(v) if isinstance(v, (int, float)) and not isinstance(v, bool) else v


def _round2(v):
    """D-153 (W37, asked by lane B) β€” MONEY AND PERCENT KEEP THEIR DECIMALS.

    `_round`'s whole-number convention is right for counts and wrong for currency: `first_cost`
    3.47 shipped as `3`, so every money cell on every Odoo grid was a whole dollar.

    ⚠ `pct` IS AFFECTED TOO, and that is the half most likely to be dropped. `cells.ts` renders a
    percent as `num(v).toFixed(1) + "%"`, so a `yoy_pct` of 12.34 was `round()`ed to 12 and painted
    "12.0%" β€” one decimal of a number that HAS one, which reads as precision rather than as loss.
    β›” NOT written as a `_round(v, nd=0)` default argument, deliberately: `round(v, 0)` returns a
    FLOAT where `round(v)` returns an INT, so every integer column's wire shape would change under
    an edit that looks purely cosmetic.
    """
    if not isinstance(v, (int, float)) or isinstance(v, bool):
        return v
    if not math.isfinite(v):
        return v

    # `round(12.345, 2)` is 12.35 because its binary float is just above the decimal tie, while
    # DuckDB's `round_even(..., 2)` (the filter and sort expression) correctly yields 12.34.
    # Quantizing the user-visible decimal spelling preserves banker's rounding at cents in both
    # engines. Keep an int an int: a currency value can be integral without changing its wire type.
    decimal = Decimal(str(v))
    # Decimal's default precision is 28 digits; keep the prior `round` behavior for an unusual
    # but valid large finite float instead of making it an InvalidOperation at the payload edge.
    with localcontext() as context:
        context.prec = max(context.prec, decimal.adjusted() + 3)
        rounded = decimal.quantize(Decimal("0.01"), rounding=ROUND_HALF_EVEN)
    return int(rounded) if isinstance(v, int) else float(rounded)


# Types a USER may create from the column menu (owner item 7, 2026-07-26). Mirrors
# customer-grid/types.ts CREATABLE_TYPES; verify_fields_contract.py holds the two in step.
#   select β€” a single-select with its own `options` (the "Status" a user wants to add; distinct
#            from the Odoo-sourced `status` lifecycle, which is not user-defined)
#   user   β€” an assignee, whose choices come from the HOST's real user list, never from here
#: `multiselect` (wave-2 item 5, 2026-07-27): the Airtable-style MULTI select β€” declared
#: options like `select`, but the cell holds a comma-joined SET and the row belongs to every
#: member of it (the `multi` grouping/cell contract the Cohorts column established).
#: Wave-5 item 11 (2026-07-27): `checkbox` (cell = bool; the overlay stores '1' or '') Β·
#: `phone` / `email` / `url` (text-family with per-type rendering) Β· `rating` (top-level
#: `max`, SVG stars client-side β€” never emoji) Β· `created_time` (READ-ONLY, renders the row's
#: `_created`) Β· `formula` (READ-ONLY, client-computed from the row's other cells).
#: ⭐ Wave-19 R7 / contract C5: `image` β€” a PICTURE on a record. The cell holds a string
#: REFERENCE, never bytes: a product `code`, an `ed:<slug>` editorial asset, or `rec:<id>` for
#: something uploaded through the field (`POST /api/v1/assets/records`). Storing a reference is
#: what lets Royal's 1,142 existing SKU masters appear with nothing re-uploaded, and it keeps the
#: overlay stratum the size it is β€” base64 bytes in a JSON blob read on every render would be a
#: megabyte-per-row tax on the whole store. Editable by NATURE (deliberately NOT in
#: `READONLY_CUSTOM_TYPES`): the ref is what the upload endpoint hands back, and the client PATCHes
#: it through the ordinary overlay wall rather than the asset route writing cells behind it.
#: ⭐ WAVE 23 (C7) β€” `json` joined: a cell holding a whole DOCUMENT (an Instagram comment thread,
#: a webhook payload, a scraped blob) that opens in its own viewer instead of being flattened
#: into one unreadable line. It is EDITABLE by nature, like `image`: the value is still a plain
#: string on the wire, so it rides the ordinary overlay wall β€” what makes it a json field is that
#: `grid_events` REFUSES a write that does not parse (a column promising structure must not
#: silently hold something that isn't).
#: ⭐ 2026-08-07 β€” `link` and `rollup` JOINED (the relational wave). They ride here because
#: `UT_FIELD_TYPES` must stay a SUBSET of this set (gated in verify_api's W18-UT section) β€” the
#: surfaces that CREATE them are the user-table databases, where a relation between two tables is
#: a thing that exists. On the Odoo-backed Customer/Product grids there is no second user table to
#: point at, so the column menu there simply never offers one.
#: ⭐⭐ WAVE-34 (owner ruling R13) β€” `ai_enrich` JOINS, and it had to join HERE in the same change
#: that put it in `UT_FIELD_TYPES`, not a ticket later. The wave planned a SERVER-FIRST landing on
#: the reasoning that a kind the client does not offer is invisible while a kind the server refuses
#: deletes a column. That reasoning is sound and the conclusion was still wrong, because THREE
#: parity gates chain over these sets and none of them permits a partial landing:
#:   `verify_api` W18-UT   `UT_FIELD_TYPES - CUSTOM_FIELD_TYPES == set()`   (this line)
#:   `aw_fields_contract` Β§5   `CREATABLE_TYPES == CUSTOM_FIELD_TYPES`, EXACT set equality
#:   `types.ts`   `CREATABLE_TYPES: readonly FieldType[]`, so the union must carry it too
#: Measured live by lane B at 17:09: `api_api` went 969/969 to 968/969 the moment the kind entered
#: `core/user_tables.py` alone, printing `got {'ai_enrich'} want set()`. The comments on
#: `json`, `link`/`rollup` and `code` below all say the same thing in their own words.
CUSTOM_FIELD_TYPES = {"text", "long_text", "select", "multiselect", "user", "int", "currency", "pct", "date",
                      "checkbox", "phone", "email", "url", "rating", "created_time", "formula",
                      "automation", "image", "json", "link", "rollup", "code", "ai_enrich", "if", "autonumber",
                      "created_by", "last_modified_time", "last_modified_by", "chart"}

#: ⭐ WAVE-27 item 13 (owner ruling R13) β€” the `code` field's LANGUAGES.
#:
#: R13 is explicit that this kind is "syntax-highlighted storage + language config, NO execution
#: engine". So a language is a RENDERING hint and nothing else: it selects a highlighter, it never
#: selects an interpreter, and no value here may ever grow a run path. The list is short on
#: purpose β€” every entry costs a highlighter the client actually has to implement, and an
#: unimplemented language would paint plain text under a label promising colour.
#:
#: `plain` is the default and the fallback, so it is never a second way to say nothing: it is the
#: honest answer for a snippet whose language the user has not chosen.
CODE_LANGUAGES = {"plain", "json", "sql", "python", "javascript", "typescript",
                  "html", "css", "markdown", "yaml", "xml", "shell"}


def _clean_code(raw):
    """The `code` field's config bag -> `{'language': ...}`, or None.

    Deliberately OPTIONAL rather than required (the `automation` posture, not `link`'s): a code
    column with no declared language is a legitimate state β€” it stores and highlights as plain
    text β€” so refusing the FIELD over a missing bag would block the ordinary create path. An
    unknown language falls back to `plain` rather than refusing, because the value is a rendering
    hint: dropping the user's column to punish a typo in a highlighter name would be the
    disproportionate half of the fail-closed rule.

    ⚠ `plain` RETURNS NONE, and that is what makes the control reversible rather than one-way.
    Absent already means plain, so storing `{'language': 'plain'}` would be the default wearing a
    second name (the `kanbanClamp` law). But the patch path resolves an OMITTED key to the
    previous value β€” so if plain were merely omitted by the client, switching a column back from
    SQL to Plain text would keep storing SQL and read as a control that does not save. Sending
    the bag explicitly and having it evaluate to None here means: omit = keep, plain = clear.
    """
    if not isinstance(raw, dict):
        return None
    lang = str(raw.get('language') or 'plain').strip().lower()
    if lang not in CODE_LANGUAGES or lang == 'plain':
        return None
    return {'language': lang}
#: User-created types whose CELLS are read-only: their values are computed (formula β€” client
#: side, any error degrades to BLANK) or system-owned (created_time = the row's `_created`).
#: Emitted with the cohort column's read-only mechanism β€” `source: 'odoo'` + `derived` β€” so
#: the client never offers an editor and the host never accepts a cell write for them.
READONLY_CUSTOM_TYPES = {"created_time", "formula", "if", "autonumber",
                         "created_by", "last_modified_time", "last_modified_by", "chart"}
# Mirrored server persistence ceiling. ``core.route_system.MAX_OPTIONS`` owns what is published
# to clients; the focused contract gate keeps this import-free helper equal to that value.
MAX_FIELD_OPTIONS = 200
MAX_FORMULA_LEN = 500
#: `rating` bounds. Airtable caps at 10; below 2 a rating is a checkbox.
RATING_MAX_DEFAULT, RATING_MAX_MIN, RATING_MAX_MAX = 5, 2, 10

#: Key prefix of a FORMULA-MEASURE column (owner item 7, 2026-07-27): a user-created field that
#: IS a measure over a window β€” `Sales Β· the last 90 days` as a column. Mirrors the client's
#: `measure_` keys in CustomerGrid.createField. Distinct from `custom_` because the two strata
#: could not be more different: `custom_` is the EDITABLE overlay (user-typed values), while a
#: measure field is READ-ONLY and its values are computed by the host per render.
MEASURE_FIELD_PREFIX = "measure_"
#: The numeric types a measure can render as (semantic._FORMAT_TYPE's range).
MEASURE_FIELD_TYPES = {"currency", "int", "pct"}


class OptionLimitExceeded(ValueError):
    """A choice vocabulary cannot be represented without discarding entered values."""

    def __init__(self, entered):
        self.entered = int(entered)
        self.limit = MAX_FIELD_OPTIONS
        self.rejected = max(0, self.entered - self.limit)
        super().__init__(
            f"This list has {self.entered} choices; the server limit is {self.limit}, so "
            f"{self.rejected} would be rejected. Remove {self.rejected} choices, then save."
        )


def _clean_options(raw):
    """Choices for a `select`: strings, trimmed, de-duplicated case-insensitively, capped.
    Mirrors types.ts parseOptions β€” a choice list that means one thing in the picker and
    another in the filter dropdown is a column with two vocabularies."""
    out, seen = [], set()
    for v in list(raw or []):
        if not isinstance(v, (str, int, float)) or isinstance(v, bool):
            continue
        s = str(v).strip()[:120]
        if not s or s.lower() in seen:
            continue
        seen.add(s.lower())
        out.append(s)
    if len(out) > MAX_FIELD_OPTIONS:
        raise OptionLimitExceeded(len(out))
    return out


def merge_choice_options(*sources):
    """One canonical choice vocabulary from ordered option sources.

    A source-backed column may learn values through an overlay while retaining contract choices.
    Keeping the merge beside `_clean_options` makes the case-folding, 120-character label, and
    `MAX_FIELD_OPTIONS` rules identical on the persistence and payload paths.  The first spelling
    wins: a later ``et`` therefore resolves to an existing ``ET`` rather than producing a second
    visibly identical choice.
    """
    merged = []
    for source in sources:
        merged.extend(list(source or []))
    return _clean_options(merged)


def _choice_values_from_cell(field, value):
    """The individual labels represented by one select-family cell value."""
    if not isinstance(field, dict) or field.get("type") not in ("select", "multiselect"):
        return []
    raw_values = (str(value or "").split(",")
                  if field.get("type") == "multiselect" else [value])
    return _clean_options(raw_values)


def hydrate_choice_options_from_rows(fields, rows, ignored_by_field=None):
    """Return field copies whose choice vocabularies include their served cell values.

    A field may already contain real values from an import or a read-time source default before
    anybody edits it through ``grid_events``.  Those values are still choices: omitting them
    makes the picker claim that a populated select has no options.  This is a read projection,
    deliberately; it cannot write a value a caller is not permitted to read into tenant schema.
    """
    row_maps = [row for row in (rows or ()) if isinstance(row, dict)]
    ignored = {}
    for key, raw_values in (ignored_by_field or {}).items():
        values = [raw_values] if isinstance(raw_values, (str, int, float)) else raw_values
        ignored[str(key)] = {str(value).strip().casefold() for value in (values or ())
                             if str(value).strip()}

    out = []
    for raw in fields or ():
        field = dict(raw) if isinstance(raw, dict) else raw
        if not isinstance(field, dict) or field.get("type") not in ("select", "multiselect"):
            out.append(field)
            continue
        key = str(field.get("key") or "")
        values = []
        for row in row_maps:
            if key not in row:
                continue
            values.extend(value for value in _choice_values_from_cell(field, row.get(key))
                          if value.casefold() not in ignored.get(key, set()))
        if values:
            field["options"] = merge_choice_options(field.get("options"), values)
        out.append(field)
    return out


def apply_choice_overrides(fields, overrides):
    """Return field copies with durable select-family definition overrides applied.

    `overrides` is deliberately only a field-key map, so a product route can use the tenant-wide
    shared schema and a normal table workspace can use its personal source-column annotations.
    It never changes a non-choice field, and it never replaces canonical choices with a stale
    annotation: both vocabularies are merged through the one cleaner above. Product's shared
    spreadsheet columns also carry their Administrator-authored label and note here, so a
    definition save is visible on the same field projection that supplies the picker.
    """
    saved = overrides if isinstance(overrides, dict) else {}
    out = []
    for raw in fields or []:
        field = dict(raw) if isinstance(raw, dict) else raw
        if not isinstance(field, dict) or field.get("type") not in ("select", "multiselect"):
            out.append(field)
            continue
        extra = saved.get(field.get("key"))
        if not isinstance(extra, dict):
            out.append(field)
            continue
        # A Product spreadsheet choice becomes an ordinary shared definition on its first save.
        # The product API serves the canonical declaration as the base field, so carry the
        # definition's custody stamp across this overlay too; without it a fresh field payload
        # says the field is shared but cannot say who created the editable definition.
        if isinstance(extra.get("createdBy"), str) and extra["createdBy"].strip():
            field["createdBy"] = extra["createdBy"].strip()
        if isinstance(extra.get("label"), str) and extra["label"].strip():
            field["label"] = extra["label"].strip()[:120]
        if isinstance(extra.get("note"), str):
            field["note"] = extra["note"][:2000]
        fmt = _clean_format(extra.get("format"), field.get("type"))
        if fmt:
            field["format"] = fmt
        if "options" in extra:
            options = merge_choice_options(field.get("options"), extra.get("options"))
            field["options"] = options
            field.update(_choice_appearance(extra, options))
        out.append(field)
    return out


def _clean_option_colors(raw, options):
    """Choice-label -> #RRGGBB, limited to the field's canonical option vocabulary."""
    if not isinstance(raw, dict):
        return {}
    supplied = {}
    for label, color in raw.items():
        if not isinstance(label, str) or not isinstance(color, str):
            continue
        clean = color.strip().upper()
        if re.fullmatch(r"#[0-9A-F]{6}", clean):
            supplied[label.strip().lower()] = clean
    out = {}
    for option in options or []:
        color = supplied.get(str(option).strip().lower())
        if color:
            out[str(option)] = color
    return out


def _choice_appearance(raw, options):
    """Validated select-family appearance. Absent colour toggle means legacy-on."""
    if not isinstance(raw, dict):
        return {}
    out = {}
    if isinstance(raw.get("colorCodeOptions"), bool):
        out["colorCodeOptions"] = raw["colorCodeOptions"]
    colors = _clean_option_colors(raw.get("optionColors"), options)
    if colors:
        out["optionColors"] = colors
    return out


def _clean_rating_max(raw):
    """A rating's star count, bounded. Anything unusable is the default, not a refusal β€” the
    field still holds its 1..max integers either way."""
    try:
        return max(RATING_MAX_MIN, min(int(raw), RATING_MAX_MAX))
    except (TypeError, ValueError):
        return RATING_MAX_DEFAULT


#: The field types a number-style display format may apply to. `formula` is here because its
#: RESULT is a number the client renders; `pct` already renders in points and takes decimals.
#: `number` is an Odoo float column: its Decimals setting is display only, never the stored value.
_NUMBER_FORMAT_TYPES = {"int", "currency", "pct", "formula", "number"}


def _clean_format(raw, ftype):
    """Retain typed display options and the shared numeric write policy for field readback."""
    if not isinstance(raw, dict):
        return None
    out = {}
    if ftype in _NUMBER_FORMAT_TYPES:
        if isinstance(raw.get("currencySymbol"), str) and raw["currencySymbol"] in ("$", "EUR", "GBP", "IDR", ""):
            out["currencySymbol"] = raw["currencySymbol"]
        if isinstance(raw.get("allowNegative"), bool):
            out["allowNegative"] = raw["allowNegative"]
        if isinstance(raw.get("thousands"), bool):
            out["thousands"] = raw["thousands"]
        if raw.get("decimals") is not None:
            try:
                d = int(raw["decimals"])
            except (TypeError, ValueError):
                d = None
            if d is not None and 0 <= d <= 4:
                out["decimals"] = d
        if isinstance(raw.get("abbrev"), bool):
            out["abbrev"] = raw["abbrev"]
    elif ftype in ("date", "created_time", "last_modified_time"):
        if isinstance(raw.get("time"), bool):
            out["time"] = raw["time"]
        if raw.get("tz") in ("local", "utc"):
            out["tz"] = raw["tz"]
    from core.user_tables import _clean_format as clean_module_format
    display = clean_module_format(raw) or {}
    for key in ('display', 'pictureKey', 'subKey', 'labelKey', 'emptyLabel'):
        if key in display:
            out[key] = display[key]
    return out or None


def _clean_permissions(raw):
    """Canonical field edit permissions; legacy values remain readable during migration."""
    from core.field_permissions import clean_permissions
    if not isinstance(raw, dict):
        return None
    return clean_permissions(raw, fallback="personal")


#: β›” THE CHARSET MUST ADMIT EVERY TOKEN THE CLIENT ENGINE PARSES, or a legal formula is
#: refused by a wall that is supposed to be structural (2026-08-03).
#:
#: This regex was written when a formula was arithmetic over refs. On 2026-07-31 the client
#: engine (owner item 2) gained STRING literals, `&` concatenation and `^` β€” CONCATENATE, TEXT,
#: LEFT/RIGHT/MID, and any `IF(cond, "yes", "no")`. This list was never widened to match, so
#: every such formula died here: `field_upsert` refused the create, and `fields_from_workspace`
#: dropped the column on read. Nothing went red β€” a refused create looks like a quiet failure
#: and a dropped column looks like a column nobody made.
#:
#: Found by trying to ship the owner's own Buy signal formula, which is `IF(..., "Buy now",
#: "OK")` and could not be created through the product UI at all.
#:
#: ⚠ IT IS STILL STRUCTURAL, and deliberately not a second grammar β€” that is the filter_sql-class
#: drift risk this file's docstring names. The charset says which characters may appear; the
#: engine says what they mean. `_quotes_balanced` below is the one structural rule the quote
#: character brings with it.
#: WAVE 42 G7 (2026-08-25) -- THE SAME SCAR, WIDENED IN THE SAME CHANGE THIS TIME.
#:
#: The client engine gained REGEX_EXTRACT, REGEX_REPLACE, SUBSTITUTE, FIND, SWITCH, DATEADD,
#: DATETIME_DIFF and DATETIME_FORMAT. Each added character below is admitted because a token
#: the client's tokenizer parses would otherwise die here:
#:
#:   '        a SINGLE-QUOTED literal. Airtable documents units and date formats that way.
#:   [ ]      a regex character class, the commonest construct there is: "[0-9]+".
#:   | ? \\ : regex alternation, optional/non-capturing groups, and escapes.
#:   @        SUBSTITUTE/FIND over an email or URL.
#:   # $ %    TEXT number formats already accepted by the client; `$` is also a regex anchor.
#:
#: `;` stays refused: no legal formula token needs a statement separator.
#:
#: β›” D-547: A CHARACTER FILTER, NOT A SAFETY BOUNDARY. `__import__("os")` passes it (word
#: characters, parens, quotes). Such a source is inert because the ENGINE refuses it: the server
#: parser door in `aios-web/api/formula_runtime.py` is an AST interpreter over a function allowlist
#: with no Python eval. `api/verify_formula_storage.py` records both halves; never read this as the wall.
_FORMULA_CHARS = re.compile(r"^[\w\s{}()+\-*/.,<>=!^&\"'\[\]|?:\\#$%@]*$")
_FORMULA_REF = re.compile(r"\{([^{}]*)\}")

#: Longest single regex-pattern literal. The client independently caps both pattern and subject.
MAX_FORMULA_LITERAL_LEN = 200

#: Catastrophic-backtracking shape, applied to STRING LITERALS only. Applying this to the whole
#: source would also match ordinary arithmetic such as `({a} + {b}) * 2`.
_NESTED_QUANT = re.compile(r"\((?:[^()\\]|\\.)*[*+](?:[^()\\]|\\.)*\)\??\s*[*+]")


def _string_literals(s):
    """Return literal bodies, or None for an unterminated quote.

    This mirrors the client tokenizer's structural rule: single and double quoted strings are
    equivalent, a doubled opening quote escapes itself, and the other quote kind is ordinary
    text. It assigns no formula meaning; it only locates literal boundaries.
    """
    out = []
    i = 0
    n = len(s)
    while i < n:
        quote = s[i]
        if quote not in ('"', "'"):
            i += 1
            continue
        j = i + 1
        body = []
        while True:
            if j >= n:
                return None
            if s[j] == quote:
                if j + 1 < n and s[j + 1] == quote:
                    body.append(quote)
                    j += 2
                    continue
                break
            body.append(s[j])
            j += 1
        out.append("".join(body))
        i = j + 1
    return out


def _quotes_balanced(s):
    """Whether every single- or double-quoted literal is structurally closed.

    A parity count is not sound now that both spellings are legal: the double quote inside
    ``'5" pipe'`` is ordinary text, not an opener. The shared scanner answers exactly the same
    boundary question as the client tokenizer without assigning meaning to the literal.
    """
    return _string_literals(s) is not None


#: Wave-18 C5-AUTOFIELD. `kind` is a whitelist because an unknown kind would be a column that
#: silently never runs; `source` names where the run's subject comes from.
AUTOMATION_KINDS = {"instagram_profile"}
AUTOMATION_SOURCES = {"record_url_field", "self"}
MAX_AUTOMATION_SETTINGS = 12


def _clean_automation(raw, valid_keys=None, flow_ids=None):
    """Validate an `automation` config bag. Returns the clean dict, or None when there is
    nothing valid to store (the column then renders as unconfigured β€” never invented).

    β›” WAVE 22 (contract C8, owner item 5) β€” NO FIELD WITHOUT A FLOW. With `flow_ids` given
    (the WRITE path: grid_events / user_tables pass the tenant's automation-definition ids),
    the bag MUST carry a `flowId` naming one of them β€” absent or naming a deleted flow is
    refused, the same fail-closed direction as a formula ref that names no field. With
    `flow_ids=None` (the READ path, `fields_from_workspace`) the law is NOT applied: a column
    stored before the law must keep projecting β€” enforcement at read time would vaporise it,
    which is the `_clean_formula` write/read split exactly.
    """
    if not isinstance(raw, dict):
        return None
    kind = str(raw.get('kind') or '').strip()
    if kind not in AUTOMATION_KINDS:
        return None
    source = str(raw.get('source') or 'record_url_field').strip()
    if source not in AUTOMATION_SOURCES:
        source = 'record_url_field'
    out = {'kind': kind, 'source': source}
    flow = str(raw.get('flowId') or '').strip()[:40]
    if flow_ids is not None and (not flow or flow not in flow_ids):
        return None
    if flow:
        out['flowId'] = flow
    url_field = str(raw.get('urlField') or '').strip()[:80]
    # fail closed on a ref that does not exist, exactly as _clean_formula does at WRITE time
    if url_field and (valid_keys is None or url_field in valid_keys):
        out['urlField'] = url_field
    settings = {}
    for k, v in list((raw.get('settings') or {}).items())[:MAX_AUTOMATION_SETTINGS]:
        if isinstance(v, bool) or isinstance(v, (int, float)):
            settings[str(k)[:40]] = v
        elif isinstance(v, str):
            settings[str(k)[:40]] = v[:200]
    if settings:
        out['settings'] = settings
    return out


def _clean_formula(raw, valid_keys=None):
    """STRUCTURAL passthrough for a formula field's expression (wave-5 item 9).

    Meaning is NOT checked here: the CLIENT engine owns the grammar (arithmetic over `{field}`
    refs, ABS/ROUND/MIN/MAX/IF), and any evaluation error degrades to a BLANK cell β€” never a
    wrong number. That is the `_clean_window` split one stratum up, and deliberately NOT a
    Python mirror of the grammar: a second engine is the filter_sql-class drift risk.
    Structure IS checked β€” charset, length, balanced parens, BALANCED QUOTES, well-formed
    non-empty `{refs}` β€” and at WRITE time (`valid_keys` given) every ref must name a field this
    table has, fail closed. At READ time refs are left alone: a referenced field deleted later
    must blank the CELLS, not vaporise the column.

    ⚠ A `{ref}` INSIDE A STRING LITERAL is still checked against `valid_keys` at write time, so
    `IF(x, "see {notafield}", "")` is refused. That is a false rejection and it is the
    fail-closed direction: the alternative is teaching this function where strings begin and
    end, which is the second grammar the paragraph above refuses to write.
    """
    if not isinstance(raw, str):
        return None
    s = raw.strip()
    if not s or len(s) > MAX_FORMULA_LEN or not _FORMULA_CHARS.match(s):
        return None
    depth = 0
    for ch in s:
        if ch == "(":
            depth += 1
        elif ch == ")":
            depth -= 1
            if depth < 0:
                return None
    if depth:
        return None
    if not _quotes_balanced(s):
        return None
    # Regex patterns are user input reaching JavaScript's regex engine. The client owns the
    # load-bearing runtime bounds (pattern AND subject); this structural wall rejects an obvious
    # unsafe literal before it is stored. Run it on read too: literal shape is intrinsic and
    # cannot become invalid merely because the table's field set later changes.
    literals = _string_literals(s)
    if literals is None:
        return None
    regexy = 'REGEX_' in s.upper()
    for literal in literals:
        if regexy and len(literal) > MAX_FORMULA_LITERAL_LEN:
            return None
        if _NESTED_QUANT.search(literal):
            return None
    refs = _FORMULA_REF.findall(s)
    leftover = _FORMULA_REF.sub("", s)
    if "{" in leftover or "}" in leftover:      # unbalanced / nested braces
        return None
    if any(not r.strip() for r in refs):        # a `{}` ref names nothing
        return None
    if valid_keys is not None and any(r not in valid_keys for r in refs):
        return None
    return s


def _clean_geocode(raw):
    """One `geocode` bag β†’ the stored shape, or None (dropped).

    ⭐⭐ W37-T22 (owner item 15 / ruling R4, contract C7). THE ONE validator for the geocode
    pseudo-kind, called by BOTH field doors: `_field_extras` here (the Odoo grids) and
    `core/user_tables._clean_field` via `_ag_geocode` (every `ut_*` user database).

    β›” IT WAS INLINE IN `_field_extras` UNTIL 2026-08-19 AND THAT IS WHY IT SHIPPED HALF-DONE.
    `user_tables._clean_field` is a strict allowlist that returns only the bags it NAMES, so a
    geocode column created on a user database was stored WITHOUT its `{addressField}` β€” the
    *"created, named, configured, gone"* failure the `image` type shipped as in wave 19. Extracting
    it rather than copying the rules is [[one-question-two-normalizers]]: a second copy is how the
    two doors come to disagree about what a valid bag is.

    β›” WHOLE-KEY DROP (the `swipe` construction): a geocode column with no address column is not
    a degraded column, it is a column no run can ever fill, and the honest state for that is the
    unconfigured one the client refuses at `canCreate`.

    β›” THE FIELD'S `type` IS `text` AND THERE IS NO `geocode` FieldType. The kind is a PSEUDO-KIND
    in the create picker (the `measure` construction), so `CUSTOM_FIELD_TYPES`, `UT_FIELD_TYPES`,
    `CREATABLE_TYPES`, the shape/label tables and the cell renderer are all untouched β€” three
    parity gates chain over those sets and none permits a partial landing. This is also why the
    bag takes `format`'s posture and NOT `formula`'s: there is no type to pair it with, so an
    absent bag is an ordinary text column rather than a refusal.

    ⚠ `addressField` is NOT checked against the table's keys: neither door is given `valid_keys`,
    and the split this module already draws puts that loss on the surface that RENDERS. The
    enricher must SAY the address column is gone rather than geocode an empty string.
    """
    if not isinstance(raw, dict):
        return None
    addr = raw.get("addressField")
    if not isinstance(addr, str) or not addr.strip():
        return None
    out = {"addressField": addr.strip()[:80]}
    # D-3 β€” the optional ISO 3166-1 alpha-2 hint, mapped straight onto the geocoder's
    # `countrycodes` parameter. NORMALISED to upper case and stored only when it is exactly two
    # letters: absent means "anywhere", and `""` would be that state's second spelling. A
    # three-letter or numeric code is REFUSED rather than truncated, because a truncated code is
    # a valid code for a different country.
    cc = raw.get("country")
    if isinstance(cc, str) and re.fullmatch(r"[A-Za-z]{2}", cc.strip() or ""):
        out["country"] = cc.strip().upper()
    return out


# --- DATE RECURRENCE ---------------------------------------------------------
# A date cell remains an ISO scalar.  Its optional field recurrence is a separate, explicit
# configuration bag: persisting a JavaScript Date, locale label, or a client-computed next value
# would make an identical record mean different things to two hosts.  The host computes the
# next occurrence and preview at projection time from this compact, durable shape.
_RECURRENCE_KINDS = frozenset({'daily', 'weekly', 'monthly', 'yearly', 'holiday', 'anchored'})
# ⭐ W47-T25 (owner instruction 13, ruling R1): "the date is N days ON / AFTER / BEFORE another
# date field".  The other date field is the recurrence-level `anchorField` that
# `routes_grid.govern_date_recurrence` already requires and already validates as same-database or
# linked-through-a-Link-field, so this kind needs no anchor of its own β€” and because the anchor is
# a COLUMN, every record computes its own answer from its own anchor value.  That is the
# per-record behaviour the instruction asks for, without a per-record rule store.
#
# ⚠ THE KIND IS `anchored`, NOT `offset`.  Holiday and anchored rules now share the human
# quantity/unit/before-on-after vocabulary, but their anchors remain different: a holiday names
# a calendar occurrence while an anchored rule names a record value.  Keeping the kinds distinct
# stops a holiday rule from quietly becoming a per-row field rule.
_ANCHORED_UNITS = frozenset({'day', 'business_day', 'weekday', 'week', 'month', 'year'})
_ANCHORED_RELATIONS = frozenset({'on', 'after', 'before'})
_HOLIDAY_OFFSET_UNITS = _ANCHORED_UNITS
# A calendar appears here only when the server really evaluates it.  The Date picker reads this
# same registry, so a selector cannot promise a country whose recurrence becomes a no-op later.
#
# ⭐⭐ W46-T33 (owner instruction 13, ruling R11: fixed-date plus floating "plus religious
# holidays too including jewish holidays"). A recurrence may now name ONE holiday instead of a
# whole national calendar, and the unified quantity/unit/before-on-after offset applies to it.
# The granular codes live in THIS registry rather
# than a second one, so `_PUBLIC_HOLIDAY_CALENDARS` admits them at the field door, the Date
# picker reads them off the same wire, and `recurrence_preview` resolves every choice from that
# one registry.
# `group` is what lets the picker head its two option groups without a client-side copy of the
# list; it is additive, so an older client that ignores it still renders a flat, correct list.
PUBLIC_HOLIDAY_CALENDARS = (
    {'code': 'US', 'label': 'United States federal holidays', 'group': 'calendar'},
    {'code': 'CA', 'label': 'Canada federal public holidays', 'group': 'calendar'},
    {'code': 'NEW_YEARS', 'label': "New Year's Day", 'group': 'holiday'},
    {'code': 'VALENTINES', 'label': "Valentine's Day", 'group': 'holiday'},
    {'code': 'EASTER', 'label': 'Easter Sunday', 'group': 'holiday'},
    {'code': 'MOTHERS_DAY', 'label': "Mother's Day", 'group': 'holiday'},
    {'code': 'MEMORIAL_DAY', 'label': 'Memorial Day', 'group': 'holiday'},
    {'code': 'FATHERS_DAY', 'label': "Father's Day", 'group': 'holiday'},
    {'code': 'INDEPENDENCE_DAY', 'label': 'Independence Day', 'group': 'holiday'},
    {'code': 'LABOR_DAY', 'label': 'Labor Day', 'group': 'holiday'},
    {'code': 'ROSH_HASHANAH', 'label': 'Rosh Hashanah', 'group': 'holiday'},
    {'code': 'YOM_KIPPUR', 'label': 'Yom Kippur', 'group': 'holiday'},
    {'code': 'HALLOWEEN', 'label': 'Halloween', 'group': 'holiday'},
    {'code': 'THANKSGIVING', 'label': 'Thanksgiving', 'group': 'holiday'},
    {'code': 'HANUKKAH', 'label': 'Hanukkah', 'group': 'holiday'},
    {'code': 'CHRISTMAS_EVE', 'label': 'Christmas Eve', 'group': 'holiday'},
    {'code': 'CHRISTMAS', 'label': 'Christmas Day', 'group': 'holiday'},
    {'code': 'NEW_YEARS_EVE', 'label': "New Year's Eve", 'group': 'holiday'},
    {'code': 'PASSOVER', 'label': 'Passover', 'group': 'holiday'},
)
_PUBLIC_HOLIDAY_CALENDARS = frozenset(item['code'] for item in PUBLIC_HOLIDAY_CALENDARS)
# The three old spellings are READ ONLY migration input.  `clean_date_recurrence` always emits
# the unified quantity/unit/relation form below, so no new saved rule carries the disconnected
# +/-1 shape that Wave 48's audit rejected.
_HOLIDAY_LEGACY_RELATIONS = {'day_before': -1, 'day_on': 0, 'day_after': 1}


def _iso_day(value):
    if isinstance(value, _dt.datetime):
        value = value.date()
    if isinstance(value, _dt.date):
        return value
    if not isinstance(value, str):
        return None
    try:
        return _dt.date.fromisoformat(value.strip()[:10])
    except ValueError:
        return None


def _observed(day):
    """US federal-observed day: Saturday -> Friday, Sunday -> Monday."""
    if day.weekday() == 5:
        return day - _dt.timedelta(days=1)
    if day.weekday() == 6:
        return day + _dt.timedelta(days=1)
    return day


def _nth_weekday(year, month, weekday, nth):
    day = _dt.date(year, month, 1)
    shift = (weekday - day.weekday()) % 7
    return day + _dt.timedelta(days=shift + 7 * (nth - 1))


def _last_weekday(year, month, weekday):
    if month == 12:
        day = _dt.date(year + 1, 1, 1) - _dt.timedelta(days=1)
    else:
        day = _dt.date(year, month + 1, 1) - _dt.timedelta(days=1)
    return day - _dt.timedelta(days=(day.weekday() - weekday) % 7)


def _easter_sunday(year):
    """Gregorian computus, kept local so a recurrence preview needs no network."""
    a = year % 19
    b, c = divmod(year, 100)
    d, e = divmod(b, 4)
    f = (b + 8) // 25
    g = (b - f + 1) // 3
    h = (19 * a + b - d - g + 15) % 30
    i, k = divmod(c, 4)
    l = (32 + 2 * e + 2 * i - h - k) % 7
    m = (a + 11 * h + 22 * l) // 451
    month = (h + l - 7 * m + 114) // 31
    day = (h + l - 7 * m + 114) % 31 + 1
    return _dt.date(year, month, day)


# ── THE HEBREW CALENDAR, kept local for the same reason the computus is ───────────────────────
# R11 asks for Jewish holidays, and those are lunisolar: a hardcoded month and day would be wrong
# every year.  So they are COMPUTED, with the arithmetic of Dershowitz & Reingold, and the answer
# stays available during an outage exactly like `_easter_sunday`'s.
#
# β›” `_HEBREW_EPOCH` IS -1373427, NOT -1373429.  The off-by-two value returns every anchor exactly
# two days early across five Hebrew years and four Hebrew months, which reads as a broken
# algorithm rather than a wrong constant.  RD 1 == 0001-01-01 proleptic Gregorian, which is
# precisely `datetime.date.fromordinal`'s origin, so no epoch shim is needed.
_HEBREW_EPOCH = -1373427
# Hebrew months are 1=Nisan .. 7=Tishrei .. 13=Adar II, and the YEAR begins at Tishrei (7).
_HEBREW_TISHREI, _HEBREW_NISAN, _HEBREW_KISLEV = 7, 1, 9
_HEBREW_YEAR_CACHE = {}


def _hebrew_leap(year):
    return ((year * 7 + 1) % 19) < 7


def _hebrew_last_month(year):
    return 13 if _hebrew_leap(year) else 12


def _hebrew_elapsed_days(year):
    months = (235 * ((year - 1) // 19)
              + 12 * ((year - 1) % 19)
              + (7 * ((year - 1) % 19) + 1) // 19)
    day = months * 29 + (12084 + 13753 * months) // 25920
    return day + 1 if (3 * (day + 1)) % 7 < 3 else day


def _hebrew_new_year(year):
    """The fixed day number of 1 Tishrei, including the three postponement rules."""
    cached = _HEBREW_YEAR_CACHE.get(year)
    if cached is not None:
        return cached
    before, this, after = (_hebrew_elapsed_days(year - 1), _hebrew_elapsed_days(year),
                           _hebrew_elapsed_days(year + 1))
    delay = 2 if after - this == 356 else (1 if this - before == 382 else 0)
    value = _HEBREW_EPOCH + this + delay
    if len(_HEBREW_YEAR_CACHE) > 2048:
        _HEBREW_YEAR_CACHE.clear()
    _HEBREW_YEAR_CACHE[year] = value
    return value


def _hebrew_year_days(year):
    return _hebrew_new_year(year + 1) - _hebrew_new_year(year)


def _hebrew_month_days(year, month):
    if month in (2, 4, 6, 10, 13):
        return 29
    if month == 12 and not _hebrew_leap(year):
        return 29
    # Marheshvan (8) is long only in a 355 or 385 day year; Kislev (9) is short only in a 353 or
    # 383 day one.  Those two variable months are what keep the festivals off a fixed offset.
    if month == 8 and _hebrew_year_days(year) % 10 != 5:
        return 29
    if month == 9 and _hebrew_year_days(year) % 10 == 3:
        return 29
    return 30


def _hebrew_date(year, month, day):
    """The Gregorian DAYTIME date of a Hebrew year/month/day.

    ⚠ Hebcal's holiday LISTING pages print the preceding SUNSET, one day earlier than this; its
    converter prints the daytime date, which is what a calendar cell means.
    """
    if month < _HEBREW_TISHREI:
        span = (sum(_hebrew_month_days(year, item)
                    for item in range(_HEBREW_TISHREI, _hebrew_last_month(year) + 1))
                + sum(_hebrew_month_days(year, item) for item in range(1, month)))
    else:
        span = sum(_hebrew_month_days(year, item) for item in range(_HEBREW_TISHREI, month))
    return _dt.date.fromordinal(_hebrew_new_year(year) + span + day - 1)


def _hebrew_in_gregorian(month, day, year):
    """Every occurrence of one Hebrew month/day landing inside Gregorian `year`.

    β›” ONE HEBREW YEAR STRADDLES TWO GREGORIAN YEARS β€” Hebrew 5788 puts Rosh Hashanah in 2027 and
    Passover in 2028 β€” so this scans a WINDOW of Hebrew years and filters on the result, and never
    assumes `hebrew_year = gregorian_year + 3760`.
    """
    out = set()
    for hebrew_year in range(year + 3759, year + 3763):
        try:
            got = _hebrew_date(hebrew_year, month, day)
        except (ValueError, OverflowError):
            continue
        if got.year == year:
            out.add(got)
    return out


# β›” A NAMED holiday is the TRUE date and is NEVER weekend-shifted.  `_observed()` belongs to the
# federal CALENDARS above, where a Saturday holiday really is taken on the Friday.  Christmas 2027
# falls on a Saturday and must stay 2027-12-25: shifting it would land it on Christmas Eve, which
# is its own separately selectable holiday here.
_GRANULAR_HOLIDAYS = {
    'NEW_YEARS': lambda year: {_dt.date(year, 1, 1)},
    'VALENTINES': lambda year: {_dt.date(year, 2, 14)},
    'INDEPENDENCE_DAY': lambda year: {_dt.date(year, 7, 4)},
    'HALLOWEEN': lambda year: {_dt.date(year, 10, 31)},
    'CHRISTMAS_EVE': lambda year: {_dt.date(year, 12, 24)},
    'CHRISTMAS': lambda year: {_dt.date(year, 12, 25)},
    'NEW_YEARS_EVE': lambda year: {_dt.date(year, 12, 31)},
    'MOTHERS_DAY': lambda year: {_nth_weekday(year, 5, 6, 2)},     # second Sunday of May
    'FATHERS_DAY': lambda year: {_nth_weekday(year, 6, 6, 3)},     # third Sunday of June
    'MEMORIAL_DAY': lambda year: {_last_weekday(year, 5, 0)},      # last Monday of May
    'LABOR_DAY': lambda year: {_nth_weekday(year, 9, 0, 1)},       # first Monday of September
    'THANKSGIVING': lambda year: {_nth_weekday(year, 11, 3, 4)},   # fourth Thursday of November
    'EASTER': lambda year: {_easter_sunday(year)},
    'ROSH_HASHANAH': lambda year: _hebrew_in_gregorian(_HEBREW_TISHREI, 1, year),
    'YOM_KIPPUR': lambda year: _hebrew_in_gregorian(_HEBREW_TISHREI, 10, year),
    'HANUKKAH': lambda year: _hebrew_in_gregorian(_HEBREW_KISLEV, 25, year),
    'PASSOVER': lambda year: _hebrew_in_gregorian(_HEBREW_NISAN, 15, year),
}


def _canada_public_holidays(year):
    """Canada's federal public-service holiday schedule, deterministically calculated.

    This is deliberately not a claim about every provincial observance.  Weekend fixed holidays
    move to the next available weekday, including the Christmas/Boxing-Day collision.
    """
    days = {
        _easter_sunday(year) - _dt.timedelta(days=2),  # Good Friday
        _last_weekday(year, 5, 0) - _dt.timedelta(days=7),  # Monday before May 25
        _nth_weekday(year, 9, 0, 1),                  # Labour Day
        _nth_weekday(year, 10, 0, 2),                 # Thanksgiving
    }
    fixed = [_dt.date(year, 1, 1), _dt.date(year, 7, 1),
             _dt.date(year, 11, 11), _dt.date(year, 12, 25), _dt.date(year, 12, 26)]
    if year >= 2021:
        fixed.append(_dt.date(year, 9, 30))           # Truth and Reconciliation
    for holiday in fixed:
        observed = holiday
        if observed.weekday() == 5:
            observed += _dt.timedelta(days=2)
        elif observed.weekday() == 6:
            observed += _dt.timedelta(days=1)
        while observed in days:
            observed += _dt.timedelta(days=1)
        days.add(observed)
    return frozenset(days)


# A preview generates its finite set of holiday source years once.  An uncached lunisolar
# computation would otherwise repeat for every editor preview.  The values are immutable
# frozensets of a pure function of (code, year), so remembering them cannot change an answer.
_HOLIDAY_CACHE = {}


def _remember_holidays(key, days):
    if len(_HOLIDAY_CACHE) > 4096:
        _HOLIDAY_CACHE.clear()
    _HOLIDAY_CACHE[key] = days
    return days


def public_holidays(calendar, year):
    """A supported public holiday calendar, returned as deterministic ISO-day objects.

    US federal holidays are intentionally calculated locally rather than fetched from a public
    endpoint during a render: a recurrence must keep its answer during an outage and historical
    previews must not move when a third party updates a feed.  Unsupported calendars are
    refused at the field door; the empty result here protects old malformed stored data.
    """
    calendar = str(calendar or '').upper()
    if calendar not in _PUBLIC_HOLIDAY_CALENDARS:
        return frozenset()
    key = (calendar, year)
    cached = _HOLIDAY_CACHE.get(key)
    if cached is not None:
        return cached
    if calendar == 'CA':
        return _remember_holidays(key, _canada_public_holidays(year))
    # β›” THIS GUARD IS LOAD-BEARING.  Without it every granular code admitted above falls straight
    # through to the US federal body below and previews as the whole United States calendar β€”
    # a wrong answer that no gate would go red on.
    if calendar != 'US':
        builder = _GRANULAR_HOLIDAYS.get(calendar)
        return _remember_holidays(key, frozenset(builder(year) if builder else ()))
    days = {
        _observed(_dt.date(year, 1, 1)),
        _nth_weekday(year, 1, 0, 3),             # Martin Luther King Jr. Day
        _nth_weekday(year, 2, 0, 3),             # Washington's Birthday
        _last_weekday(year, 5, 0),               # Memorial Day
        _observed(_dt.date(year, 7, 4)),
        _nth_weekday(year, 9, 0, 1),             # Labor Day
        _nth_weekday(year, 10, 0, 2),            # Columbus Day
        _observed(_dt.date(year, 11, 11)),
        _nth_weekday(year, 11, 3, 4),            # Thanksgiving
        _observed(_dt.date(year, 12, 25)),
    }
    # Juneteenth became a federal holiday in 2021; earlier recurrence previews must not
    # retroactively invent it.
    if year >= 2021:
        days.add(_observed(_dt.date(year, 6, 19)))
    return _remember_holidays(key, frozenset(days))


def clean_ends(raw):
    """One recurrence's stopping condition, normalised.  Never raises.

    W46-T32 shipped the Ends control on the client and `clean_date_recurrence` builds a fresh
    allowlist dict, so `ends` round-tripped as ABSENT and a rule asking for three occurrences
    still previewed ten.  This is the server half of that control.

    Anything malformed degrades to ``never`` rather than refusing the whole recurrence: a
    stopping condition nobody can read is a reason to keep repeating, not a reason to lose the
    schedule.
    """
    if not isinstance(raw, dict):
        return {'kind': 'never'}
    kind = str(raw.get('kind') or 'never').strip().lower()
    if kind == 'on':
        day = _iso_day(raw.get('date'))
        return {'kind': 'on', 'date': day.isoformat()} if day else {'kind': 'never'}
    if kind == 'after':
        count = raw.get('count')
        if isinstance(count, bool) or not isinstance(count, int) or not 1 <= count <= 999:
            return {'kind': 'never'}
        return {'kind': 'after', 'count': count}
    return {'kind': 'never'}


def clean_date_recurrence(raw, condition_fields=None):
    """One date field's recurrence config, or ``None`` for absent/malformed input.

    ``rules`` are an intentional union: selecting weekday + public holiday means either makes
    a valid next date.  The stored config carries neither a process clock nor generated preview;
    those derived values belong to ``recurrence_payload`` and are evaluated by the server.
    """
    if not isinstance(raw, dict):
        return None
    start = _iso_day(raw.get('startDate', raw.get('anchor')))
    anchor_raw = raw.get('anchorField')
    anchor = None
    if isinstance(anchor_raw, dict):
        table = str(anchor_raw.get('table') or 'same').strip()[:80]
        field = str(anchor_raw.get('field') or '').strip()[:80]
        via = str(anchor_raw.get('linkedVia') or '').strip()[:80]
        if field and (table == 'same' or via):
            anchor = {'table': table, 'field': field}
            if via:
                anchor['linkedVia'] = via
    if start is None and anchor is None:
        return None
    # W48-T11 / R6: tenant holidays are declarative dates stored with this recurrence,
    # never fetched from an external calendar.  Bound and normalised before a rule can refer
    # to them, so the preview and persisted filter share one tenant-owned set.
    tenant_holidays = sorted({day.isoformat() for day in
                              (_iso_day(value) for value in list(raw.get('tenantHolidays') or [])[:366])
                              if day is not None})
    out_rules = []
    for raw_rule in list(raw.get('rules') or [])[:12]:
        if not isinstance(raw_rule, dict):
            continue
        kind = str(raw_rule.get('kind') or '').lower()
        if kind not in _RECURRENCE_KINDS:
            continue
        interval = raw_rule.get('interval', 1)
        if not isinstance(interval, int) or isinstance(interval, bool) or not 1 <= interval <= 366:
            continue
        rule = {'kind': kind, 'interval': interval}
        if kind == 'weekly':
            weekdays = sorted({day for day in (raw_rule.get('weekdays') or [])
                               if isinstance(day, int) and not isinstance(day, bool)
                               and 0 <= day <= 6})
            rule['weekdays'] = weekdays or ([start.weekday()] if start else [])
            if not rule['weekdays']:
                continue
        elif kind == 'monthly':
            # ``day: 1`` means the first of every N months.  ``ordinal`` + ``weekday`` adds
            # Google-Calendar-style first Monday / last Friday without a competing model.
            if 'ordinal' in raw_rule or 'weekday' in raw_rule:
                ordinal, weekday = raw_rule.get('ordinal'), raw_rule.get('weekday')
                if (not isinstance(ordinal, int) or isinstance(ordinal, bool)
                        or ordinal not in (-1, 1, 2, 3, 4, 5)
                        or not isinstance(weekday, int) or isinstance(weekday, bool)
                        or not 0 <= weekday <= 6):
                    continue
                rule.update({'ordinal': ordinal, 'weekday': weekday})
            else:
                day = raw_rule.get('day', start.day if start else None)
                if not isinstance(day, int) or isinstance(day, bool) or not 1 <= day <= 31:
                    continue
                rule['day'] = day
        elif kind == 'yearly':
            month = raw_rule.get('month', start.month if start else None)
            day = raw_rule.get('day', start.day if start else None)
            if (not isinstance(month, int) or isinstance(month, bool) or not 1 <= month <= 12
                    or not isinstance(day, int) or isinstance(day, bool) or not 1 <= day <= 31):
                continue
            # Validate the month/day without reinterpreting 29 February.
            try:
                _dt.date(2024, month, day)
            except ValueError:
                continue
            rule.update({'month': month, 'day': day})
        elif kind == 'holiday':
            calendar = str(raw_rule.get('calendar') or 'US').strip().upper()
            if calendar not in _PUBLIC_HOLIDAY_CALENDARS and calendar != 'TENANT':
                continue
            if calendar == 'TENANT' and not tenant_holidays:
                continue
            # W48-T11: Holidays must use the SAME quantity/unit/before-on-after sentence as a
            # date offset.  The former +/-1 relation is still accepted only long enough to turn
            # existing rules into this one canonical shape.  It never reaches a response or a
            # fresh save unchanged.
            raw_relation = str(raw_rule.get('relation') or '').strip().lower()
            legacy_offset = _HOLIDAY_LEGACY_RELATIONS.get(raw_relation)
            if legacy_offset is not None:
                relation = 'before' if legacy_offset < 0 else ('after' if legacy_offset > 0 else 'on')
                offset, unit = abs(legacy_offset), 'day'
            elif raw_relation in _ANCHORED_RELATIONS:
                relation = raw_relation
                unit = str(raw_rule.get('unit') or 'day').strip().lower()
                if unit not in _HOLIDAY_OFFSET_UNITS:
                    continue
                offset = raw_rule.get('offset', 0 if relation == 'on' else None)
                if (not isinstance(offset, int) or isinstance(offset, bool)
                        or (relation == 'on' and offset != 0)
                        or (relation != 'on' and not 1 <= offset <= 366)):
                    continue
                # The hidden unit/count must not survive an "on" choice in storage.  A rule is
                # therefore read back exactly as the editor renders it.
                if relation == 'on':
                    unit = 'day'
            else:
                # Legacy rules written before the relation words carried only a signed day
                # offset.  Convert those deterministically; an unsigned value above one with no
                # unit/direction is malformed rather than guessed.
                legacy_offset = raw_rule.get('offset', 0)
                if (not isinstance(legacy_offset, int) or isinstance(legacy_offset, bool)
                        or legacy_offset not in (-1, 0, 1)):
                    continue
                relation = ('before' if legacy_offset < 0
                            else ('after' if legacy_offset > 0 else 'on'))
                offset, unit = abs(legacy_offset), 'day'
            rule.update({'calendar': calendar, 'offset': offset, 'unit': unit, 'relation': relation})
        elif kind == 'anchored':
            # ⚠ Anchored and holiday rules share the readable before/on/after words, but their
            # anchors differ: this branch moves from a record date while holiday moves from a
            # calendar occurrence.  The kinds stay exclusive and each branch writes only its
            # own keys.
            #
            # An unknown unit or relation drops the rule, exactly as an unknown calendar does
            # above, rather than degrading to a default the person never chose.  `interval` was
            # already bounded to 1..366 by the shared check, so `relation: on` arrives as 1 and a
            # 0 would have dropped the rule before reaching here.
            unit = str(raw_rule.get('unit') or 'day').strip().lower()
            relation = str(raw_rule.get('relation') or 'after').strip().lower()
            if unit not in _ANCHORED_UNITS or relation not in _ANCHORED_RELATIONS:
                continue
            rule.update({'unit': unit, 'relation': relation})
        if rule not in out_rules:
            out_rules.append(rule)
    if not out_rules:
        return None
    preview_count = raw.get('previewCount', raw.get('preview', 10))
    if not isinstance(preview_count, int) or isinstance(preview_count, bool):
        preview_count = 10
    out = {'rules': out_rules, 'previewCount': max(1, min(preview_count, 50))}
    if tenant_holidays:
        out['tenantHolidays'] = tenant_holidays
    if start:
        out['startDate'] = start.isoformat()
    if anchor:
        out['anchorField'] = anchor
    admitted_conditions = (condition_fields if condition_fields is not None
                           else raw.get('conditionFields'))
    conditions = clean_filter_tree(raw.get('conditions') or [], valid_keys={
        str(key) for key in admitted_conditions or () if str(key)})
    if conditions:
        out['conditions'] = conditions
    ends = clean_ends(raw.get('ends'))
    # Emitted only when it says something, exactly like `conditions`, so no previously saved
    # config grows a key it never had.  `clean_ends` is idempotent on its own output, which is
    # what lets `recurrence_payload` re-clean an already-clean dict.
    if ends['kind'] != 'never':
        out['ends'] = ends
    return out


def _shift_months(day, amount):
    """``day`` moved ``amount`` calendar months, CLAMPED to the target month's last valid day.

    Adding one month to 31 January has no 31 February, so the answer is 28 or 29 February rather
    than a rolled-over 2 or 3 March.  Python's FLOOR division and modulo are what make a negative
    amount (a ``before`` rule) land in the right year: a total of -1 gives year - 1, month 12,
    where a C-style remainder would give month 0.
    """
    total = (day.year * 12 + day.month - 1) + amount
    year, month = divmod(total, 12)
    month += 1
    if not 1 <= year <= 9999:
        return None
    # The last day of `month` is the day before the first of the next one, without importing
    # `calendar` for a single call.  December 9999 cannot ask Python for January 10000, so its
    # known last day stays local instead of turning a valid editor input into a server error.
    last = 31 if month == 12 else (_dt.date(year, month + 1, 1) - _dt.timedelta(days=1)).day
    return _dt.date(year, month, min(day.day, last))


def _business_day_shift(start, amount, holidays):
    """Move by business days, excluding weekends and this tenant's declared holidays."""
    if amount == 0:
        return start
    direction = 1 if amount > 0 else -1
    remaining, day = abs(amount), start
    try:
        while remaining:
            day += _dt.timedelta(days=direction)
            if day.weekday() < 5 and day not in holidays:
                remaining -= 1
    except OverflowError:
        return None
    return day


def _weekday_shift(start, amount):
    """Move by weekdays, excluding weekends but deliberately not tenant holidays."""
    if amount == 0:
        return start
    direction = 1 if amount > 0 else -1
    remaining, day = abs(amount), start
    try:
        while remaining:
            day += _dt.timedelta(days=direction)
            if day.weekday() < 5:
                remaining -= 1
    except OverflowError:
        return None
    return day


def _shift_years(day, amount):
    """Move calendar years while clamping a leap-day to February's last valid day."""
    year = day.year + amount
    if not 1 <= year <= 9999:
        return None
    try:
        return day.replace(year=year)
    except ValueError:
        # The only legal source-day failure is 29 February into a non-leap year.
        return _dt.date(year, 2, 28)


def _anchored_occurrence(start, rule, tenant_holidays=frozenset()):
    """The ONE date an ``anchored`` rule names, computed straight from the anchor date.

    β›” NEVER route this through `_recurrence_matches`.  That function returns False for
    ``day < start``, and a ``before`` date is by definition EARLIER than the anchor, so the day
    scan below could never find one however far it walked.
    """
    relation = rule.get('relation', 'after')
    if relation == 'on':
        return start
    amount = rule['interval'] * (1 if relation == 'after' else -1)
    unit = rule.get('unit', 'day')
    if unit == 'month':
        return _shift_months(start, amount)
    if unit == 'year':
        return _shift_years(start, amount)
    if unit == 'business_day':
        return _business_day_shift(start, amount, tenant_holidays)
    if unit == 'weekday':
        return _weekday_shift(start, amount)
    try:
        return start + _dt.timedelta(days=amount * (7 if unit == 'week' else 1))
    except OverflowError:
        return None


def _holiday_occurrence(holiday, rule, tenant_holidays=frozenset()):
    """The exact date one unified holiday-offset rule names.

    `weekday` intentionally ignores tenant holidays while `business_day` skips both weekends
    and the tenant's declared dates.  The distinction is visible in the editor and keeps the
    server preview authoritative for the rule the person actually chose.
    """
    relation = rule.get('relation', 'on')
    if relation == 'on':
        return holiday
    amount = rule['offset'] * (1 if relation == 'after' else -1)
    unit = rule.get('unit', 'day')
    if unit == 'month':
        return _shift_months(holiday, amount)
    if unit == 'year':
        return _shift_years(holiday, amount)
    if unit == 'business_day':
        return _business_day_shift(holiday, amount, tenant_holidays)
    if unit == 'weekday':
        return _weekday_shift(holiday, amount)
    try:
        return holiday + _dt.timedelta(days=amount * (7 if unit == 'week' else 1))
    except OverflowError:
        return None


def _recurrence_matches(day, start, rule):
    kind, interval = rule['kind'], rule['interval']
    if day < start:
        return False
    if kind == 'daily':
        return (day - start).days % interval == 0
    if kind == 'weekly':
        return ((day - start).days // 7) % interval == 0 and day.weekday() in rule['weekdays']
    if kind == 'monthly':
        months = (day.year - start.year) * 12 + day.month - start.month
        if months < 0 or months % interval:
            return False
        if 'ordinal' not in rule:
            return day.day == rule['day']
        match = (_last_weekday(day.year, day.month, rule['weekday'])
                 if rule['ordinal'] == -1
                 else _nth_weekday(day.year, day.month, rule['weekday'], rule['ordinal']))
        return match.month == day.month and match == day
    if kind == 'yearly':
        return (day.year - start.year) % interval == 0 and day.month == rule['month'] and day.day == rule['day']
    return False


def recurrence_preview(raw, today=None, count=None, condition_fields=None):
    """The next distinct ISO dates, anchored to the server's supplied/current day."""
    config = clean_date_recurrence(raw, condition_fields=condition_fields)
    if config is None:
        return []
    now = _iso_day(today) or _dt.date.today()
    start = _iso_day(config.get('startDate'))
    if start is None and isinstance(raw, dict):
        start = _iso_day(raw.get('resolvedAnchorDate'))
    if start is None:
        return []
    want = config['previewCount'] if count is None else max(1, min(int(count), 50))
    ends = config.get('ends') or {'kind': 'never'}
    # A preview of at most fifty values needs no unbounded search.  Ten years also makes an
    # unavailable public calendar visibly empty instead of spinning a request forever.
    try:
        horizon = max(start, now) + _dt.timedelta(days=3660)
    except OverflowError:
        horizon = _dt.date.max
    # β›” "After N occurrences" COUNTS FROM `startDate`, NOT FROM TODAY: occurrences already in the
    # past have spent the allowance.  Counting from today is the obvious implementation and it is
    # wrong in a way that looks perfectly reasonable β€” a weekly Monday schedule begun 2026-01-01
    # with `after 3`, viewed on 2026-01-13, has exactly ONE occurrence left, not three.  So the
    # scan starts at the START for that case, and the visible window is trimmed afterwards.
    limit = want
    if ends['kind'] == 'after':
        lower, limit = start, ends['count']
    else:
        lower = max(start, now)
        if ends['kind'] == 'on':
            horizon = min(horizon, _iso_day(ends.get('date')) or horizon)
    found = set()
    holiday_rules = [rule for rule in config['rules'] if rule['kind'] == 'holiday']
    anchored_rules = [rule for rule in config['rules'] if rule['kind'] == 'anchored']
    ordinary_rules = [rule for rule in config['rules']
                      if rule['kind'] not in ('holiday', 'anchored')]
    # W47-T25: an anchored rule names ONE date rather than a repeating series, so it is COMPUTED
    # here instead of being searched for by the scan below.  It still passes the trailing
    # `item >= now` filter, and that is deliberate: the cell holds the NEXT date, so an anchored
    # date that has already gone by is EMPTY rather than a date in the past.  One column, one
    # meaning, which is what lets the ordinary filter, sort and group paths read it unchanged.
    # `horizon` is already final at this point, so an `ends: on` boundary binds here too.
    tenant_holidays = frozenset(_dt.date.fromisoformat(value)
                                for value in config.get('tenantHolidays', []))
    for rule in anchored_rules:
        occurrence = _anchored_occurrence(start, rule, tenant_holidays)
        if occurrence is not None and start <= occurrence <= horizon:
            found.add(occurrence)
    # A holiday's source year can differ from its result year when the chosen unit is years.  We
    # generate each authoritative occurrence once, then let the ordinary-rule scan merge it with
    # daily/weekly/monthly values.  Stopping that scan merely because holidays filled the preview
    # would drop an earlier ordinary occurrence, so it intentionally walks the finite horizon.
    for rule in holiday_rules:
        extra_years = rule['offset'] if rule.get('unit') == 'year' and rule.get('relation') != 'on' else 0
        for holiday_year in range(start.year, min(9999, horizon.year + extra_years) + 1):
            if (holiday_year - start.year) % rule['interval']:
                continue
            holidays = ({_dt.date.fromisoformat(value) for value in config.get('tenantHolidays', [])
                         if value.startswith(f"{holiday_year:04d}-")}
                        if rule['calendar'] == 'TENANT'
                        else public_holidays(rule['calendar'], holiday_year))
            for holiday in holidays:
                occurrence = _holiday_occurrence(holiday, rule, tenant_holidays)
                # Outside an `ends: after` rule the old day scan began at `lower`, so adding
                # earlier calendar occurrences here would let past holidays consume the preview
                # limit before today's dates were considered.
                if occurrence is not None and lower <= occurrence <= horizon:
                    found.add(occurrence)
    day = lower
    while ordinary_rules and day <= horizon:
        if any(_recurrence_matches(day, start, rule) for rule in ordinary_rules):
            found.add(day)
        if day == _dt.date.max:
            break
        day += _dt.timedelta(days=1)
    allowed = sorted(found)[:limit]
    return [item.isoformat() for item in allowed if item >= now][:want]


def recurrence_payload(raw, today=None, condition_fields=None):
    """Durable config plus server-authoritative ``nextDate`` and finite ``preview``."""
    config = clean_date_recurrence(raw, condition_fields=condition_fields)
    if config is None:
        return None
    preview = recurrence_preview(config, today=today, condition_fields=condition_fields)
    return {**config, 'nextDate': preview[0] if preview else None, 'preview': preview}


def project_date_recurrences(fields, today=None):
    """Re-project recurrence metadata against the final visible field contract."""
    valid_keys = {str(field.get('key')) for field in fields or ()
                  if isinstance(field, dict) and field.get('key')}
    out = []
    for field in fields or ():
        if not isinstance(field, dict) or field.get('type') != 'date' \
                or not isinstance(field.get('recurrence'), dict):
            out.append(field)
            continue
        item = dict(field)
        recurrence = recurrence_payload(
            field.get('recurrence'), today=today, condition_fields=valid_keys)
        if recurrence:
            item['recurrence'] = recurrence
        else:
            item.pop('recurrence', None)
        out.append(item)
    return out


# ── ⭐⭐ W47-T26 (owner instruction 13 / ruling R2, contract C5): THE NEXT DATE AS A CELL ──
#
# R2, verbatim: the computed next date is STORED in the cell, "so it filters, sorts and groups
# like an ordinary date".  Everything below is PURE β€” it reads a recurrence config and a row's
# anchor cell and returns an ISO day string.  The writer lives on the write path
# (`aios-web/api/routes_grid.py`), because a value re-derived on every response is exactly the
# thing that cannot be filtered, and that is the defect this pair closes.
#
# ⚠ `project_date_recurrences` ABOVE IS UNCHANGED AND STAYS UNCHANGED.  It projects the field's
# METADATA (the config plus a server-authoritative preview) for the editor to draw; these two
# functions project a ROW's value.  Two different questions, and `verify_fields_contract.py` and
# `verify_api.py::section_recurrence_preview` both assert the first one's exact output.


def recurrence_row_next_date(recurrence, anchor_value, today=None, condition_fields=None):
    """The ONE next date a row's recurrence names, computed from THAT ROW's anchor cell.

    β›” AN EMPTY ANCHOR CELL IS AN EMPTY ANSWER, never the field-level ``startDate``.  Falling
    back to the field's own start would hand every unanchored row the SAME date β€” a column full
    of confident wrong values instead of an honestly empty one, and W47-T25 already ruled that
    clause.  ``None`` here becomes an empty cell there.

    The per-row config is the STORED config with ``startDate`` REPLACED, which is deliberately
    simpler than `recurrence_preview`'s unused ``resolvedAnchorDate`` hook: one substitution, and
    then every rule kind β€” daily, weekly, monthly, yearly, holiday, anchored β€” is answered by
    exactly the code that answers the field-level preview.  There is no second definition of
    "next" to keep in step, which is the whole reason the substitution happens here rather than
    inside the scan.
    """
    if not isinstance(recurrence, dict):
        return None
    anchor = _iso_day(anchor_value)
    if anchor is None:
        return None
    payload = recurrence_payload({**recurrence, 'startDate': anchor.isoformat()},
                                 today=today, condition_fields=condition_fields)
    return (payload or {}).get('nextDate') or None


def recurrence_column_values(recurrence, rows, anchor_key, today=None, condition_fields=None,
                             row_ids=None):
    """``{row_id: <ISO day> or ''}`` for one recurrence date column over ``rows``.

    ``rows`` is the store's own ``{row_id: {field_key: value}}`` shape.  ``row_ids`` narrows the
    pass to the rows an anchor edit actually touched; ``None`` means the whole column.

    β›” MEMOISED ON THE ANCHOR DAY, and that is not a micro-optimisation.  `recurrence_preview`
    walks a day at a time until it has ``previewCount`` matches, so ONE yearly rule is ~3,650
    iterations β€” per row.  Rows overwhelmingly share anchor days (a batch loaded on one date, a
    renewal month), so the cache collapses a thousand-row column onto a handful of computations.
    ⚠ The obvious alternative β€” asking `recurrence_preview` for ``count=1`` β€” is NOT equivalent
    and must not be substituted: an anchored occurrence joins ``found`` BEFORE the scan and may be
    in the past, and ``sorted(found)[:limit]`` truncates BEFORE the ``>= now`` filter, so a limit
    of one can answer empty exactly where the full preview answers correctly.

    An empty answer is ``''`` rather than ``None`` because that is what the grid stores when a
    person CLEARS a date cell (`core/grid_events.py`'s overlay branch).  One representation of
    empty, so a materialised blank and a typed blank are the same value to every reader.
    """
    if not isinstance(recurrence, dict) or not isinstance(rows, dict) or not anchor_key:
        return {}
    anchor_key = str(anchor_key)
    ids = list(rows) if row_ids is None else [str(rid) for rid in row_ids]
    memo, out = {}, {}
    for rid in ids:
        row = rows.get(str(rid))
        if not isinstance(row, dict):
            continue
        anchor = _iso_day(row.get(anchor_key))
        day = anchor.isoformat() if anchor is not None else ''
        if day not in memo:
            memo[day] = (recurrence_row_next_date(
                recurrence, day, today=today, condition_fields=condition_fields) or '')
        out[str(rid)] = memo[day]
    return out


def _default_value_extras(saved):
    """Carry scalar default metadata without treating falsy values as absent."""
    value = saved.get('defaultValue')
    if isinstance(value, (str, int, float, bool)):
        return {'defaultValue': value}
    return {}


def _field_extras(saved, ftype, condition_fields=None):
    """createdBy / permissions / format / scope β€” the validated passthrough the created strata
    share (wave 5). `createdBy` is only ever WRITTEN host-side (the handler stamps it); here it
    is carried so the client can gate its menus and the handler can enforce against it.
    `scope` (wave-6 item 9): 'cohort' marks a field created as cohort-specific β€” the handler
    stamps it at create (cohort page only) and preserves it like createdBy; carried here so the
    client can label the field, filtered OUT of other pages by fields_from_workspace."""
    out = _default_value_extras(saved)
    if ftype == 'link' and 'link' in saved:
        from core.user_tables import _clean_link
        link = _clean_link(saved['link'])
        if link is None:
            raise ValueError('The link field definition is invalid.')
        out['link'] = link
    if ftype == 'autonumber':
        from core.user_tables import _clean_autonumber
        out['autonumber'] = _clean_autonumber(saved.get('autonumber'))
        out['valueAuthority'] = 'computed'
    if ftype in ('created_by', 'last_modified_time', 'last_modified_by'):
        out['valueAuthority'] = 'computed'
    who = saved.get("createdBy")
    if isinstance(who, str) and who.strip():
        out["createdBy"] = who.strip()[:80]
    perms = _clean_permissions(saved.get("permissions"))
    if perms:
        out["permissions"] = perms
    fmt = _clean_format(saved.get("format"), ftype)
    if fmt:
        out["format"] = fmt
    if saved.get("scope") == "cohort":
        out["scope"] = "cohort"
    # ── ⭐⭐ W37-T22 (owner item 15 / ruling R4, contract C7): THE GEOCODE COLUMN'S CONFIG ──
    #
    # `{addressField}` β€” which column this one reads. WHOLE-KEY drop (the `swipe` construction):
    # a geocode column with no address column is not a degraded one, it is a column no run can
    # ever fill, and the honest state for that is the unconfigured one the client refuses at
    # `canCreate`.
    #
    # β›” THE FIELD'S `type` IS `text` AND THERE IS NO `geocode` FieldType. The kind is a PSEUDO-KIND
    # in the create picker (the `measure` construction), so `CUSTOM_FIELD_TYPES`, `UT_FIELD_TYPES`,
    # `CREATABLE_TYPES`, the shape/label tables and the cell renderer are all untouched β€” three
    # parity gates chain over those sets and none permits a partial landing.
    # ⚠ `addressField` is NOT checked against this table's keys: `_field_extras` is not given
    # `valid_keys`, and the split this module already draws puts that loss on the surface that
    # RENDERS ("what each mode MEANS ... is the client's business"). The enricher must SAY the
    # address column is gone rather than geocode an empty string.
    # ⚠ EXTRACTED to `_clean_geocode` 2026-08-19 (/validate-wave, W37-T22 clause 1). The rules
    # did not change; what changed is that `core/user_tables.py` now reaches THIS function through
    # `_ag_geocode` instead of carrying a second copy. See `_clean_geocode`'s own note.
    geo = _clean_geocode(saved.get("geocode"))
    if geo:
        out["geocode"] = geo
    # W43C C2 Ò€” the ISO date remains scalar in each row; recurrence is field metadata.  Serve
    # the compact persisted config together with a server-derived next date and preview so the
    # client never substitutes its browser clock or holiday library for the tenant contract.
    recurrence = (recurrence_payload(saved.get("recurrence"),
                                     condition_fields=condition_fields)
                  if ftype == "date" else None)
    if recurrence:
        out["recurrence"] = recurrence
    corrected_from = saved.get("labelCorrectedFrom")
    correction_id = saved.get("labelCorrectionId")
    if (isinstance(corrected_from, str) and corrected_from.strip()
            and isinstance(correction_id, str) and correction_id.strip()):
        out["labelCorrectedFrom"] = corrected_from.strip()[:120]
        out["labelCorrectionId"] = correction_id.strip()[:180]
    return out


#: The DERIVED column listing the cohorts a customer is in (owner, 2026-07-27).
#:
#: NOT in `aios_grid_fields.json`, deliberately. That contract is per-TABLE and shared with the
#: standalone API and the dev sample; a cohort is per-USER, so the column exists exactly when the
#: caller has cohorts β€” the same condition under which the `__cohort__` FILTER field is offered.
#: Putting it in the canonical contract would mean an always-present column that is empty for
#: everyone else, plus three consumers to keep in step for a value none of them can produce.
COHORT_COLUMN = 'cohorts'


def cohort_field(label='Locked views'):
    """The derived membership column's descriptor.

    ⚠ WAVE 17 item 14 / C-STR β€” THE LABEL AND THE NOTE SPEAK THE NEW VOCABULARY; THE KEY DOES
    NOT. `COHORT_COLUMN` is still `'cohorts'` and the function is still `cohort_field`, because
    every stored view that shows or groups by this column names it by KEY, and every gate in
    two runtimes names the function. The owner renamed a CONCEPT ("we should stop calling it
    Cohort, but locked instead"), which is a change to what a reader sees β€” renaming the
    identifiers would break saved views to change a word nobody reads.

    `source: 'odoo'` is doing ONE job here and it is not provenance: the client keys editability
    off `source == 'overlay'`, and `_cl_handle_grid_event` accepts cell writes only for overlay
    keys. So 'odoo' is what makes this column READ-ONLY at both ends. `derived: True` is what
    stops the column menu calling it a "source field" on that basis.

    ⚠ `filterable: False`, and the replacement is the `Where [Cohort] […]` CONDITION, not another
    column. Text ops over a joined string would ALMOST work and disagree at the edges β€” `contains
    "VIP"` also matches a cohort called "VIP club" β€” and a filter that is nearly right is worse
    than one that is absent.
    """
    return {
        'key': COHORT_COLUMN, 'label': label, 'type': 'text', 'source': 'odoo',
        'default': False, 'filterable': False, 'derived': True, 'multi': True,
        'note': 'The locked views this customer is in, newest first. A locked view holds a SET, '
                'so grouping by this column puts a customer under EVERY view they are in; the '
                'group counts therefore add up to more than the record count, which stays the '
                'number of distinct customers. Read-only: membership changes only by adding or '
                'removing customers on the locked view itself.',
    }


def cohort_cells(cohorts, allowed_pids=None):
    """`{pid: {'cohorts': 'Q3 calls, Lost'}}` from `[{id,name,pids}, ...]`.

    Built per render from the caller's OWN cohorts and handed to `rows_from_pool` as `derived`,
    never merged into the cached pool rows β€” those are shared across users, and stamping one
    user's cohorts onto them would leak the membership to everybody else on the next render.
    """
    cells = {}
    for c in cohorts or []:
        # ⚠ The COMMA is the separator the client splits on to group a customer into EVERY
        # cohort they are in, so it cannot also occur inside a name. Cohort names are free text
        # ("Q3 calls, west" is a name somebody will type), so a comma is replaced here rather
        # than left to break the split silently β€” one group called "Q3 calls" and another called
        # "west" would be two lists that do not exist. The cost is cosmetic and confined to the
        # cell; the Cohort page still shows the name the user typed.
        name = str(c.get('name') or c.get('id') or '').replace(',', ' ').strip()
        for pid in c.get('pids') or ():
            if allowed_pids is not None and pid not in allowed_pids:
                continue
            cells.setdefault(pid, []).append(name)
    return {pid: {COHORT_COLUMN: ', '.join(names)} for pid, names in cells.items()}


def clean_measure_field(raw, offered):
    """Validate one UNTRUSTED formula-measure field (owner item 7) against the caller's OFFER.

    `offered` is `{measure key: {label, type}}` from `measure_filter.measure_fields(team_id)` β€”
    the same admission the condition builder uses, so a field can only name a measure this
    caller could also filter by. Returns the canonical stored shape, or None (fail closed).

    `source:'odoo'` + `derived:True` is the cohort column's read-only mechanism, reused:
    the client keys editability off `source == 'overlay'` and the host accepts cell writes only
    for overlay keys, so a measure column cannot be typed into at either end. `filterable:False`
    because the REPLACEMENT is the measure CONDITION with the same measure and window β€” the
    governed, gate-proved path (CG-8/CG-12) β€” not text ops over a derived cell.
    """
    if not isinstance(raw, dict):
        return None
    key = str(raw.get("key") or "")
    if not key.startswith(MEASURE_FIELD_PREFIX) or len(key) > 80:
        return None
    spec = raw.get("measure")
    if not isinstance(spec, dict):
        return None
    m = (offered or {}).get(spec.get("key"))
    if not m:
        return None                    # not admitted for this caller -> fail closed
    window = _clean_window(spec.get("window"))
    if window is None:
        return None                    # a measure column with no period is not a column
    mtype = m.get("type") if m.get("type") in MEASURE_FIELD_TYPES else "currency"
    return {
        "key": key,
        "label": str(raw.get("label") or m.get("label") or "Measure")[:120],
        "type": mtype,
        "source": "odoo",
        "default": True,
        "custom": True,
        "derived": True,
        "filterable": False,
        # W41-T21 (owner instruction 16): every numeric measure column arrives with a column
        # summary, `pct` included. A pct measure used to fall through to `agg: None`, so a
        # percentage column could never total at the bottom or per group.
        # It defaults to AVERAGE rather than sum ON PURPOSE: twenty rows of 20% would "total"
        # 400%, a number nobody can use. Currency and int keep `sum`. `average` is a member
        # of FIELD_AGGS, which is the vocabulary the saved-field passthrough at the bottom
        # of `fields_from_workspace` filters against, so it is not nulled on the way out.
        # Do not tidy the pct arm back to `sum`. The `else None` arm stays fail closed for
        # any future member of MEASURE_FIELD_TYPES that is not summable; today the `mtype`
        # fallback above makes it unreachable.
        "agg": ("average" if mtype == "pct"
                else "sum" if mtype in ("currency", "int") else None),
        "note": str(raw.get("note") or "")[:2000],
        "measure": {"key": str(spec.get("key"))[:80], "window": window},
    }


def measure_fields_of(fields):
    """The formula-measure columns among `fields` β€” the ones whose values the host must compute
    per render (see `rows_from_pool`'s `derived`)."""
    return [f for f in fields or [] if isinstance(f.get("measure"), dict)]


def fields_from_workspace(workspace=None, cohorts=False, scope_key=None, fields_base=None):
    """Overlay persisted notes/custom fields onto the immutable source-field contract.

    `cohorts=True` appends the derived cohort column β€” see `cohort_field`. Appended LAST and
    `default: False`, so it never displaces a column somebody already reads; the Fields menu is
    where you turn it on.

    Three saved strata pass through: notes on base fields, `custom_` overlay fields (editable),
    and `measure_` formula-measure fields (read-only, host-computed β€” owner item 7). A measure
    field was validated against the caller's measure OFFER when it was written
    (`clean_measure_field`); here only its SHAPE is re-checked, because this module has zero
    app-internal imports and cannot know the offer. A measure that has since become
    unanswerable (a BU scope on a company-level measure) degrades to a BLANK column at value
    time, never to an error.

    `scope_key` (wave-6 item 9) names the PAGE doing the asking ('customer' / 'cohort'). A
    saved def carrying `scope` is emitted only when it matches β€” so a cohort-specific field
    never appears on the Customer table. FAIL-CLOSED: a caller that passes no scope_key sees
    only unscoped (global) fields; base contract fields are never scoped.

    `fields_base` (wave 16 C-TOPIC) β€” the canonical contract to overlay onto. Absent = the
    CUSTOMER contract (`FIELDS`), byte-identical to before the parameter existed; the product
    surface passes `product_fields()`. The workspace dict a caller hands in must already be the
    matching table object's bucket β€” this function cannot tell a customer overlay from a
    product one, which is exactly why the buckets are separate stores.
    """
    saved = dict((workspace or {}).get("fields") or {})
    out = []
    base_fields = fields_base if fields_base is not None else FIELDS
    base_keys = {field["key"] for field in base_fields}
    recurrence_keys = base_keys | {str(key) for key in saved}
    for base in base_fields:
        meta = saved.get(base["key"]) or {}
        field = dict(base)
        field.update(_default_value_extras(meta))
        if base.get('type') == 'link' and 'link' in meta:
            field.update(_field_extras(meta, 'link', condition_fields=recurrence_keys))
        if isinstance(meta.get("note"), str):
            field["note"] = meta["note"][:2000]
        # Wave-5 item 10: a saved DISPLAY format on any base field (a preset included) β€” how a
        # number or date READS, per user. Rendering-only, so this is the whole acceptance.
        fmt = _clean_format(meta.get("format"), base.get("type"))
        if fmt:
            field["format"] = fmt
        # ⭐ W29-T83 β€” the saved COLUMN SUMMARY, the read half of the write door in
        # `grid_events.field_upsert`. Without this the value round-trips into the store and is
        # never served back, which looks exactly like a write that never happened
        # ([[read-path-cannot-witness-write-path]]). Absent = whatever the contract declares.
        if meta.get("agg") in FIELD_AGGS:
            field["agg"] = meta["agg"]
        # PRESET measure fields (wave-2 item 8): a preset+measure base may take a saved
        # window/label override. Wave 6 deleted every preset member (the owner's
        # no-buildable-presets rule) so this branch is currently MEMBERLESS β€” kept as the
        # measure_ path's twin for any future preset-carrying contract, and because deleting
        # it would silently change what a re-added preset means.
        if base.get("preset") and isinstance(base.get("measure"), dict):
            saved_measure = meta.get("measure") if isinstance(meta.get("measure"), dict) else {}
            window = _clean_window(saved_measure.get("window"))
            if window is not None:
                field["measure"] = {"key": base["measure"]["key"], "window": window}
                if isinstance(meta.get("label"), str) and meta["label"].strip():
                    field["label"] = meta["label"][:120]
        # A source-backed choice field can learn vocabulary from accepted values.  The annotation
        # is not a replacement for contract choices: an old workspace cannot make a currently
        # declared option disappear.  This is the read half of TableStore's atomic overlay +
        # choice write, so an "Add option" survives a fresh payload rather than existing only in
        # the optimistic cell editor.
        if base.get("type") in ("select", "multiselect") and "options" in meta:
            options = merge_choice_options(base.get("options"), meta.get("options"))
            field["options"] = options
            field.update(_choice_appearance(meta, options))
        # Recurrence belongs to the Date FIELD, not to an individual ISO date cell.  Source
        # fields need this explicit read half because their override is otherwise rebuilt from
        # the immutable contract on every workspace projection.
        if base.get("type") == "date" and "recurrence" in meta:
            recurrence = recurrence_payload(
                meta.get("recurrence"), condition_fields=recurrence_keys)
            if recurrence:
                field["recurrence"] = recurrence
        out.append(field)
    for key, field in saved.items():
        if key in base_keys or not isinstance(field, dict):
            continue
        if field.get("scope") and field.get("scope") != scope_key:
            continue          # a cohort-specific field on another page (wave-6 item 9)
        if (str(key).startswith(MEASURE_FIELD_PREFIX)
                and isinstance(field.get("measure"), dict)):
            window = _clean_window(field["measure"].get("window"))
            mkey = str(field["measure"].get("key") or "")
            if window is None or not mkey:
                continue
            mtype = field.get("type") if field.get("type") in MEASURE_FIELD_TYPES else "currency"
            out.append({
                "key": str(key)[:80],
                "label": str(field.get("label") or "Measure")[:120],
                "type": mtype,
                "source": "odoo",
                "default": bool(field.get("default", True)),
                "custom": True,
                "derived": True,
                "filterable": False,
                # W41-T21: the SAVED half of the same default, and it must stay identical to
                # `clean_measure_field`. A measure column already sitting in somebody's
                # workspace is rebuilt HERE, not there, so stamping only the create door would
                # leave every existing pct column with no summary and ship the feature half
                # dead. `pct` averages (a summed percentage is meaningless), currency and int
                # sum. Do not tidy the pct arm back to `sum`.
                "agg": ("average" if mtype == "pct"
                        else "sum" if mtype in ("currency", "int") else None),
                "note": str(field.get("note") or "")[:2000],
                "measure": {"key": mkey[:80], "window": window},
                **_field_extras(field, mtype, condition_fields=recurrence_keys),
            })
            continue
        if not str(key).startswith("custom_"):
            continue
        ftype = field.get("type")
        if ftype not in CUSTOM_FIELD_TYPES:
            continue
        if ftype in READONLY_CUSTOM_TYPES:
            # Wave-5 items 9/11: the read-only user-created pair. Emitted with the cohort
            # column's mechanism (source 'odoo' + derived) so the client never offers an
            # editor and the host's overlay-write guard excludes them by construction.
            # FILTERABLE since wave 6 (owner item 6): their values live client-side
            # (formula computes over the row, created_time renders `_created`), this
            # table's counts are client-mode, and the windowed count path never sees
            # these tables β€” so the client engine answers them soundly.
            entry = {
                "key": str(key)[:80],
                "label": str(field.get("label") or "Untitled")[:120],
                "type": ftype,
                "source": "odoo",
                "derived": True,
                "filterable": True,
                "default": bool(field.get("default", True)),
                "custom": True,
                "note": str(field.get("note") or "")[:2000],
                **_field_extras(field, ftype, condition_fields=recurrence_keys),
            }
            if ftype == "formula":
                formula = _clean_formula(field.get("formula"))
                if formula is None:
                    continue          # a formula field without a formula is nothing
                entry["formula"] = formula
            if ftype == "if":
                from core.if_field import clean
                entry["if"] = clean(field.get("if"))
                entry["valueAuthority"] = "computed"
            out.append(entry)
            continue
        if field.get("source") != "overlay":
            continue
        options = (_clean_options(field.get("options"))
                   if ftype in ("select", "multiselect") else [])
        out.append({
            "key": str(key)[:80],
            "label": str(field.get("label") or "Untitled")[:120],
            "type": ftype,
            "source": "overlay",
            "default": bool(field.get("default", True)),
            "custom": True,
            # WAVE-29 C7: the whole vocabulary, not the `{"sum"}` literal that was here β€” a
            # picker offering Average against a projection that only passes Sum through is the
            # silent half of this feature.
            "agg": field.get("agg") if field.get("agg") in FIELD_AGGS else None,
            # W50-T05 / R4 β€” the DISPLAY mode rides the projection beside the aggregate it is
            # independent of: a Sum column may read as a share, and so may a column with no
            # summary at all. Dropped to None rather than defaulted, so an unknown spelling
            # cannot become a silent "value" that the picker then disagrees with.
            "showAs": field.get("showAs") if field.get("showAs") in SHOW_AS_MODES else None,
            "note": str(field.get("note") or "")[:2000],
            # A new choice field starts with no vocabulary and learns it from real writes.  Its
            # empty options list must not silently retype it to text: the picker needs to stay a
            # picker so the first typed/pasted/imported value can create the first option.
            **({"options": options} if ftype in ("select", "multiselect") else {}),
            **(_choice_appearance(field, options)
               if ftype in ("select", "multiselect") else {}),
            # comma-joined SET semantics (the Cohorts column's contract): the row belongs to
            # every member, groups count it under each, the toolbar count stays distinct.
            **({"multi": True} if ftype == "multiselect" else {}),
            **({"max": _clean_rating_max(field.get("max"))} if ftype == "rating" else {}),
            **({"automation": _clean_automation(field.get("automation"))}
               if ftype == "automation" and _clean_automation(field.get("automation")) else {}),
            # ⭐ WAVE-27 item 13 (R13) β€” the code column's language rides the wire, because the
            # highlighter is chosen per column and the client cannot infer a language from a
            # string. Absent = `plain`, which is what an unconfigured code column renders as.
            **({"code": _clean_code(field.get("code"))}
               if ftype == "code" and _clean_code(field.get("code")) else {}),
            **_field_extras(field, ftype, condition_fields=recurrence_keys),
        })
    if cohorts and not any(f.get('key') == COHORT_COLUMN for f in out):
        # ⚠ The emptiness check is WAVE 19's, and it is about the topics R9 opened this column to.
        # A user table's field keys are slugged from whatever its creator typed, so a column
        # literally called "Cohorts" produces the key `cohorts` β€” and appending here unguarded
        # would put TWO fields with one key on the wire. The client indexes fields by key, so the
        # duplicate does not error: it silently paints one column's values under the other's
        # header. The user's own column wins; the derived one steps aside rather than shadowing it.
        out.append(cohort_field())
    return out


def rows_from_pool(pool_rows, fields=None, overlays=None, derived=None, limits=None):
    """Map customer_data.pool() dicts -> the API row shape the grid expects:
    pid + each Odoo field (numeric fields rounded, text/date passed through) + the
    persisted external overlay. Mirrors the standalone API payload contract.

    `derived` is `{pid: {key: value}}` for columns the HOST computes per render rather than
    reads off the pool row β€” today just the cohort column. A separate argument from `overlays`
    on purpose: `overlays` is the PERSISTED user stratum, and putting a value there that is
    never written back would make the dict mean two things.

    `limits`, when supplied, collects reports for sourceless fields without changing the list return.
    """
    fields = fields or FIELDS
    odoo_fields = [field for field in fields if field.get("source") == "odoo"]
    overlay_fields = [field for field in fields if field.get("source") == "overlay"]
    readable_fields = [field for field in fields if field.get("source")]
    if limits is not None:
        limits.extend({
            "subject": field["key"], "effect": "unreadable",
            "cause": "The field definition has no source.",
            "recommendation": "Set the field definition's source before reading this column.",
        } for field in fields if not field.get("source"))
    derived_keys = [field["key"] for field in readable_fields if field.get("derived")]
    readable_keys = {field["key"] for field in readable_fields}
    overlays = overlays or {}
    derived = derived or {}
    out = []
    for r in pool_rows:
        pid = r.get("pid")
        saved = overlays.get(str(pid), {}) or {}
        # `_created` (wave-5 item 11) rides every row like `pid` does β€” the datum the
        # `created_time` field type renders, regardless of that field's own key. Not a Field:
        # it has no column of its own until a user creates one. `lat`/`lon` (wave-7 W11) ride
        # the same way: the Map VIEW's data, nullable, deliberately not a column.
        row = {"pid": pid, "_created": r.get("_created") or "",
               "lat": r.get("lat"), "lon": r.get("lon")}
        notes = {}
        for source in (r, saved):
            mapped = source.get('__cell_notes__')
            if isinstance(mapped, dict):
                notes.update({key: text for key, text in mapped.items()
                              if key in readable_keys and isinstance(text, str)})
        if notes:
            row['__cell_notes__'] = notes
        for field in odoo_fields:
            k = field["key"]
            if field.get("derived"):
                continue          # not on the pool row β€” filled from `derived` below
            v = r.get(k)
            if k == "maps_url" and saved.get(k):
                v = saved[k]
            # D-153 β€” three roundings, not two: text/status/date pass through verbatim, currency
            # and pct keep two decimals (`_round2`), everything else stays a whole number.
            if field["type"] == "int" and (field.get("format") or {}).get("decimals", 0) > 0:
                row[k] = v
                continue
            row[k] = v if field["type"] in {"text", "long_text", "status", "date"} else (
                _round2(v) if field["type"] in {"currency", "pct"} else _round(v))
        for field in overlay_fields:
            k = field["key"]
            # The pool may carry the mirror's sync stamp. It wins over a stale overlay,
            # including an explicit blank; never manufacture freshness from _created or now.
            row[k] = r.get(k, saved.get(k, "")) if (
                k == "refreshed" and (field.get("automation") or {}).get("preset")
            ) else saved.get(k, "")
        got = derived.get(pid) or {}
        for k in derived_keys:
            # '' not None: a customer in no cohort has an EMPTY cohort list, and `is empty` on a
            # text column is the question somebody will ask of it.
            row[k] = got.get(k, "")
        out.append(row)
    return out


# --- the FILTER-TREE contract (mirrors customer-grid/types.ts) ---------------
# Ops the Airtable-parity condition builder can emit. isEmpty/isNotEmpty are
# VALUE-FREE (they legitimately carry no value and must never be dropped for it).
FILTER_OPS = {'contains', 'doesNotContain', 'eq', 'neq', 'isEmpty', 'isNotEmpty',
              'gt', 'gte', 'lt', 'lte', 'between', 'within',
              # Wave 2026-08-02 (C-OPS): RANK operators β€” evaluated as a SET pass over the
              # sibling-filtered domain by the client engine (useVisibleRows). The validator
              # accepts them like any op (structural, not semantic); filter_sql REFUSES to
              # compile them to row SQL (a per-row WHERE cannot express Top-N). aboveAvg /
              # belowAvg are VALUE-FREE; the rest encode their argument in `value` as a
              # string int (topN/bottomN 1..10000, inTopPct/inBottomPct 1..100,
              # inQuartile 1..4, inDecile 1..10). Deliberately NOT in MEASURE_OPS: on a
              # measure-carrying column they rank the field's own derived values.
              'topN', 'bottomN', 'inTopPct', 'inBottomPct',
              'aboveAvg', 'belowAvg', 'inQuartile', 'inDecile',
              # ⭐ W51-T07 (owner instruction 25): the MULTI-VALUE operators. Their operand is
              # the leaf's `values` LIST, not `value` β€” see MULTI_VALUE_OPS below.
              'isAnyOf', 'isNoneOf', 'hasAnyOf', 'hasAllOf', 'hasNoneOf'}
#: ⭐ W51-T07 β€” the MULTI-VALUE subset. Mirrors types.ts MULTI_VALUE_OPS and
#: filter_sql.MULTI_VALUE_OPS. A leaf carrying one of these persists `values` as a REAL LIST and
#: leaves `value` blank; `clean_filter_tree` therefore emits the list beside the usual members
#: rather than passing it through the `str(val)[:500]` coercion, which would store the literal
#: text of a Python list and make the condition unanswerable in every engine.
MULTI_VALUE_OPS = {'isAnyOf', 'isNoneOf', 'hasAnyOf', 'hasAllOf', 'hasNoneOf'}
#: How many values one multi-value condition may name. Mirrors types.ts MAX_FILTER_VALUES.
MAX_FILTER_VALUES = 100
#: The RESERVED pseudo-column of a cohort-membership leaf (owner item 5, 2026-07-26). It is not
#: a Field and never will be β€” a cohort is a hand-curated SET, so making it a column would mean
#: a cell per row per cohort. Mirrors customer-grid/types.ts COHORT_FIELD.
COHORT_FIELD = '__cohort__'
#: Ops a cohort leaf may carry (owner, 2026-07-27): set operators over a SET of cohorts.
#: Anything else is dropped. Deliberately DISJOINT from FILTER_OPS β€” see types.ts COHORT_OPS:
#: a set op reaching a column leaf would fall through the client engine's switch to "no
#: narrowing", so keeping the vocabularies apart makes the existing fail-closed drop do the work.
COHORT_OPS = {'anyOf', 'allOf', 'noneOf'}

#: ⭐⭐ WAVE-37 T26 (owner item 14, contract C4) β€” THE VIEW-MEMBERSHIP LEAF's reserved
#: pseudo-column and its operators. Mirrors `customer-grid/types.ts` VIEW_FIELD / VIEW_OPS.
#:
#: β›” DISJOINT FROM `FILTER_OPS`, for the reason COHORT_OPS is: `matchFilter` answers an operator
#: it does not know by NOT NARROWING, so an op that reached a column leaf would widen the result
#: under an authoritative count. Keeping the two vocabularies apart means a column leaf carrying
#: `inView` is dropped by the same fail-closed path that drops `dropTable`.
#: ⚠ The leaf names exactly ONE view (singular where a cohort leaf names a set), so there is no
#: all-or-nothing rule to get wrong here β€” the id either resolves or the leaf goes.
VIEW_FIELD = '__view__'
VIEW_OPS = {'inView', 'notInView'}
MAX_VIEW_ID = 64
#: The single-cohort ops this leaf shipped with, kept as PERMANENT aliases and REWRITTEN here:
#: `is part of [one]` is `is any of [that one]`, so a saved view keeps answering and upgrades the
#: next time it is written. Mirrors types.ts COHORT_OP_ALIASES.
COHORT_OP_ALIASES = {'eq': 'anyOf', 'neq': 'noneOf'}
#: How many cohorts one condition may name. Mirrors types.ts MAX_COHORT_IDS.
MAX_COHORT_IDS = 20


def parse_cohort_ids(value):
    """The cohorts a leaf names, parsed out of `value`. Mirrors types.ts `cohortIds()`.

    Comma-separated in one string because `FilterRule.value` is what all four layers persist and
    round-trip, and a one-element list is byte-identical to what the single-cohort leaf already
    stored β€” so every shipped view parses with no migration. Safe because a cohort id is built
    from `[a-z0-9_]` only (modules/cohort.new_id), so a comma cannot occur inside one.
    """
    out = []
    for raw in ('' if value is None else str(value)).split(','):
        cid = raw.strip()[:120]
        if not cid or cid in out:
            continue
        out.append(cid)
        if len(out) >= MAX_COHORT_IDS:
            break
    return out


def parse_filter_values(values):
    """The values a multi-value leaf names. Mirrors types.ts `filterValues()` and
    `harness.filter_sql.parse_filter_values`.

    β›” A REAL LIST, and the contrast with `parse_cohort_ids` above is the decision, not an
    inconsistency: a cohort id cannot contain a comma, and a SELECT OPTION is tenant prose that
    perfectly well can ("Bouquets, mixed"). Comma-joining would split one real choice into two
    that match nothing.

    β›” AND UNLIKE the cohort leaf, this is NOT all-or-nothing: an unknown option string is KEPT
    (the ticket's `how` line). The all-or-nothing rule exists for cohorts because a dropped
    member WIDENS a `noneOf` question against a set the caller cannot even see; here the values
    are the column's own prose, a member that no longer exists simply matches nothing, and the
    chip that still shows it is what lets somebody remove it.

    Order preserved, blanks dropped, duplicates collapsed, members capped at 120 characters, the
    list capped at MAX_FILTER_VALUES.
    """
    out = []
    if not isinstance(values, (list, tuple)):
        return out
    for raw in values:
        val = ('' if raw is None else str(raw)).strip()[:120]
        if not val or val in out:
            continue
        out.append(val)
        if len(out) >= MAX_FILTER_VALUES:
            break
    return out
# Airtable allows 3 nesting levels (root conditions -> group -> group), then grays
# the button out. MAX_FILTER_DEPTH in types.ts must stay in lock-step with this.
MAX_FILTER_DEPTH = 3
MAX_FILTER_NODES = 100      # total nodes across the whole tree
MAX_FILTER_SIBLINGS = 50    # per level


#: Shape of a measure condition's date window. aios_grid has ZERO app-internal imports by
#: design, so it does NOT know the window VOCABULARY β€” `harness/windows.py` owns that, mirrored
#: in `customer-grid/windows.ts`, and a third copy here is exactly the drift those two already
#: need a gate to prevent. This validates SHAPE only.
WINDOW_MAX_N = 3650


def _clean_window(raw):
    """Structural passthrough for a measure condition's `{kind, n?, from?, to?}` window.

    Meaning is NOT checked here: an unrecognised `kind` survives this function and is REFUSED by
    `harness.measure_filter.resolve_rule`, the layer that owns the vocabulary. Splitting it this
    way keeps the grid module reusable and keeps one definition of what "last quarter" means.
    """
    if not isinstance(raw, dict):
        return None
    kind = raw.get('kind')
    if not isinstance(kind, str) or not kind or len(kind) > 40:
        return None
    out = {'kind': kind}
    if raw.get('n') is not None:
        try:
            out['n'] = max(1, min(int(raw['n']), WINDOW_MAX_N))
        except (TypeError, ValueError):
            return None
    for side in ('from', 'to'):
        if raw.get(side) not in (None, ''):
            out[side] = str(raw[side])[:32]
    return out


def _clean_rhs(raw, valid_keys):
    """CG-9 β€” validate `{kind, colId, window?}`, the "compare against another attribute" side.

    SHAPE and KEY only: `colId` must be something this table has (the caller widens `valid_keys`
    with the measure keys, exactly as it does for the left side), and a measure rhs must carry a
    window. What the window MEANS is `harness/windows.py`'s business, same split as `_clean_window`.
    """
    if not isinstance(raw, dict):
        return None
    kind = raw.get('kind')
    if kind not in ('field', 'measure', 'stat'):
        return None
    if kind == 'stat':
        # A STATISTIC carries no column: the population is the comparand. Shape only β€” which
        # statistics exist is `harness/measure_filter.STATS`'s business, and an unrecognised one
        # is REFUSED there rather than guessed at, exactly like an unrecognised window kind.
        stat = raw.get('stat')
        if not isinstance(stat, str) or not stat or len(stat) > 24:
            return None
        return {'kind': 'stat', 'stat': stat}
    col = raw.get('colId')
    if col not in valid_keys:
        return None
    out = {'kind': kind, 'colId': col}
    if kind == 'measure':
        window = _clean_window(raw.get('window'))
        if window is None:
            return None            # a measure comparand with no period is not a question
        out['window'] = window
    return out


#: View DISPLAY MODES beside the grid (wave-6 item 10; 'map' wave-7 W11; 'dashboard' wave-8
#: I19). Mirrors customer-grid/types.ts DISPLAY_MODES; 'grid' is what an absent/unknown
#: display means, so it is never stored.
#: ⚠ 'dashboard' is RETAINED FOREVER (wave-9 I10, contract C2). The owner renamed the mode to
#: "Chart" (a Dashboard MODULE is coming and the two would collide), but this set is the
#: gatekeeper for a STORED value: `_clean_display` DROPS an unknown mode, so removing
#: 'dashboard' here would silently downgrade every already-saved chart view to grid β€” and live
#: views are sitting in mode:'dashboard' right now (wave 8's own close-out records one). The
#: rename is therefore a stored-value MIGRATION, not a constant rename: accept 'dashboard' on
#: READ forever, only ever WRITE 'chart'.
#: ⭐ WAVE-27 item 8 (owner ruling R2, contract C3): 'swipe' β€” a DECK of the records whose bound
#: single-select is EMPTY, triaged one at a time by swiping left or right into two of that
#: field's options. Landed here FIRST and in the same change as the client registry, which is
#: the whole reason the two modes above it needed a staged hold: `_clean_display` DROPS an
#: unknown mode, so a client that offers a mode this set does not carry lets a user build a view
#: that silently reverts to a grid on the next read.
#: ⭐⭐ WAVE-29 R6/R7 (owner item 10, contract C3) β€” 'form', which CLOSES D-90. The client has
#: carried `form` in its union, with an icon, a label and a tone, since wave 23; this set never
#: did, so `_clean_display` DROPPED both the mode and the `display.form` spec on every write β€”
#: while `routes_forms.py` reads exactly that key to serve the public submit door. The public door
#: has therefore been live and UNREACHABLE for two waves: not broken, just impossible to point at
#: anything. The mirror is one name, and it is the half nobody could see was missing because
#: BOTH sides were individually consistent.
#: ⚠ Being a legal stored mode is NOT the same as being offered: `form` is deliberately held out
#: of the client's `CREATABLE_MODES` until `CustomerGrid` mounts a renderer for it (the hold law
#: written into `iconShapes.ts`, and now machine-enforced in BOTH directions by
#: `verify_icons.py::mode_parity` β€” offering an unmounted mode is red, and mounting an unoffered
#: one is red too, so the hold cannot outlive its reason the way wave 27's did).
DISPLAY_MODES = {'grid', 'list', 'calendar', 'kanban', 'map', 'dashboard', 'chart',
                 'catalog', 'swipe', 'form', 'gallery', 'timeline'}
_RETIRED_MODES = {'timeseries'}

#: ⭐⭐ WAVE-29 R7 (owner item 10, contracts C3/C4) β€” THE FORM INTERFACE's stored spec, at
#: `views[<id>].config.display.form`. The public door (`aios-web/api/routes_forms.py`) has read
#: exactly this key since wave 23 and NOTHING HAS EVER BEEN ABLE TO WRITE IT: `form` was not a
#: legal mode and this function had no branch for the key, so every spec a client sent was dropped
#: on the way in. That is D-90 stated precisely β€” not a broken feature, an unreachable one.
#:
#: β›” THE TOKEN IS NOT HERE, AND IT NEVER WILL BE. A share token that rides the wire is a token a
#: browser can CHOOSE, and `routes_forms._resolve` walks tenants and answers with the FIRST match β€”
#: so one tenant setting its token to another tenant's value would silently receive that tenant's
#: submissions. The token is minted server-side and lives in a bucket no client write can reach;
#: `_clean_form` drops any `token` key that arrives here, rather than validating its shape.
#: ⭐⭐ WAVE-37 T21 (owner items 1/12, rulings R5+R6, contract C3) β€” THE PER-VIEW CATALOG SPEC,
#: stored at `views[<id>].config.display.catalog`.
#:
#: β›”β›” IT IS **`catalog`**, SINGULAR, AND IT IS NOT `catalogs`. Both keys live on `display`, they
#: are one letter apart, and that is the single most likely mistake anybody touching this file will
#: make. They are different things and BOTH are live:
#:   Β· `catalogs` (wave-18 C6) β€” a LIST of up to 12 print artifacts, each with its own paper,
#:     brand and pages of kind cover/intro/section/gallery. Authored CONTENT. UNTOUCHED by T21.
#:   Β· `catalog`  (wave-37 C3)  β€” THIS view's catalog SETTINGS: which column is the picture, which
#:     is the title (R5: per view, so two catalog views on one database may differ), plus the page
#:     order and the free-placed items R6 asks for.
#: Neither replaces the other, and neither validator reads the other's key.
#:
#: β›” THE MIGRATION IS A RULE ABOUT WHAT THIS FUNCTION MUST **NOT** DO (R6, C3). An item authored
#: before free placement has no `x`/`y`, and an ABSENT coordinate must read back ABSENT β€” never
#: normalised to 0. Defaulting to zero would pile every pre-existing item at the origin, which is
#: "a catalog that silently loses its layout is a FAIL, not a migration" stated as code. The
#: RENDERER turns an absent coordinate into flow position N; the host's whole job is to not destroy
#: the distinction it reads.
#: ⚠ `w`/`h` carry the OPPOSITE asymmetry, deliberately: a zero WIDTH is an invisible item, so 0
#: is refused and absent means "the renderer's default size". A zero X is the top-left corner and is
#: a real, storable position. Two keys of one shape with two rules β€” the `kanbanClamp` family β€”
#: which is why each is written out rather than looped.
MAX_CATALOG_SECTIONS = 20
#: A bound on a hostile payload, not an opinion about the renderer's coordinate space: D owns what
#: the numbers MEAN. Stored to 2 decimals, finer than any print surface resolves.
MAX_CATALOG_COORD = 10000
#: The page `order` bound. ABSENT => that page's ARRAY INDEX, and `order` WINS where present; ties
#: break by array index. Decided HERE rather than left to the renderer, because two readers guessing
#: differently about page order is exactly the divergence contract C3 exists to close.
MAX_CATALOG_ORDER = 9999


def _clean_catalog_coord(raw, allow_zero):
    """One free-placement number, or None. `allow_zero` False is the w/h leg (see the header).

    β›” THE ROUNDING IS `floor(v * 100 + 0.5) / 100` AND NOT `round(v, 2)`, AND THAT IS THE WHOLE
    POINT OF THIS FUNCTION EXISTING SEPARATELY. Python's `round` is BANKER'S rounding and
    JavaScript's `Math.round` is half-up-toward-+Infinity, so the two engines disagree on every
    exact half: `round(0.125, 2)` is 0.12 here and 0.13 in the browser. One dragged item landing two
    hundredths apart on the two engines is a `display` object that never compares equal β€” the
    silent mirror drift contract C2 exists to prevent, arriving through arithmetic instead of
    through a missing key. The expression below is `Math.floor(v * 100 + 0.5) / 100` written in
    Python, evaluated in the same IEEE doubles, so the two agree bit for bit.
    ⚠ AND AN INTEGRAL RESULT IS EMITTED AS AN `int`: `12.0` serialises as `12.0` in Python and
    `12` in JSON.stringify, which is one stored value with two spellings.
    """
    if isinstance(raw, bool) or not isinstance(raw, (int, float)):
        return None
    if raw != raw or raw in (float("inf"), float("-inf")):        # NaN / +-inf
        return None
    val = math.floor(float(raw) * 100 + 0.5) / 100
    if val > MAX_CATALOG_COORD or val < -MAX_CATALOG_COORD:
        return None
    if not allow_zero and val <= 0:
        return None
    return int(val) if val == int(val) else val


def _clean_catalog_item(raw):
    """One free-placed item: `{code, x?, y?, w?, h?}`. `code` REQUIRED; every coordinate optional.

    Key EMISSION ORDER is fixed and mirrored byte-for-byte by `types.ts::cleanCatalogSpec` β€” an
    accepted save has to read back identically on both engines, and this pair is where that is
    decided.
    """
    if not isinstance(raw, dict):
        return None
    code = raw.get("code")
    if not isinstance(code, str) or not code.strip():
        return None
    out = {"code": code.strip()[:CATALOG_CODE_MAX]}
    for key, allow_zero in (("x", True), ("y", True), ("w", False), ("h", False)):
        val = _clean_catalog_coord(raw.get(key), allow_zero)
        if val is not None:
            out[key] = val
    return out


def _clean_catalog_spec(raw, valid_keys):
    """C3 β€” `display.catalog`, fail-closed. See the header block above for what it is NOT.

    Field refs follow the `dateField`/`stackField` rule this module already runs: a ref naming a
    deleted column is dropped INDIVIDUALLY and the renderer falls back to its per-mode default. It
    never costs the user their pages β€” the `charts` per-entry-drop precedent, applied to the one
    payload here that is AUTHORED rather than derived from the rows.
    """
    if not isinstance(raw, dict):
        return None
    out = {}
    for ref in ("imageField", "titleField"):
        if raw.get(ref) in valid_keys:
            out[ref] = raw[ref]
    pages_raw = raw.get("pages")
    pages = []
    if isinstance(pages_raw, list):
        # ONE cumulative item budget across the whole spec, spent in page order then section order
        # β€” the `_clean_catalogs` construction, so a 40-page catalog cannot smuggle 20,000 items
        # past a per-page cap.
        budget = MAX_CATALOG_CODES
        seen_pages = set()
        for raw_page in pages_raw:
            if len(pages) >= MAX_CATALOG_PAGES:
                break
            if not isinstance(raw_page, dict):
                continue
            pid = str(raw_page.get("id") or "").strip()[:CATALOG_ID_MAX]
            if not pid or pid in seen_pages:
                continue
            seen_pages.add(pid)
            page = {"id": pid}
            order = raw_page.get("order")
            if (isinstance(order, int) and not isinstance(order, bool)
                    and 0 <= order <= MAX_CATALOG_ORDER):
                page["order"] = order
            sections_raw = raw_page.get("sections")
            sections = []
            if isinstance(sections_raw, list):
                seen_sections = set()
                for raw_section in sections_raw:
                    if len(sections) >= MAX_CATALOG_SECTIONS:
                        break
                    if not isinstance(raw_section, dict):
                        continue
                    sid = str(raw_section.get("id") or "").strip()[:CATALOG_ID_MAX]
                    if not sid or sid in seen_sections:
                        continue
                    seen_sections.add(sid)
                    section = {"id": sid}
                    items_raw = raw_section.get("items")
                    items = []
                    if isinstance(items_raw, list) and budget > 0:
                        for raw_item in items_raw:
                            item = _clean_catalog_item(raw_item)
                            if item is None:
                                continue
                            items.append(item)
                            budget -= 1
                            if budget <= 0:
                                break
                    # ⚠ NOT de-duplicated by `code`. The same product legitimately appears twice in
                    # one section at two positions β€” that is what free placement IS β€” and wave-18's
                    # "deduped WITHIN a page" rule was written for a LISTING, where a repeat is a
                    # mistake. Here it is the feature.
                    if items:
                        section["items"] = items
                    sections.append(section)
            # An EMPTY section is KEPT: a person adds a New Section and then drags into it, and
            # dropping it would delete the thing they just made, between two autosaves.
            if sections:
                page["sections"] = sections
            pages.append(page)
    if pages:
        out["pages"] = pages
    # A spec that reduces to nothing is DROPPED, never stored as `{}`. "No image field, no title
    # field, no pages" IS the unconfigured state, and `{}` would be its second spelling β€” the
    # no-churn law every literal-only key in `_clean_display` follows.
    return out or None


FORM_ACCESS = ('public', 'emails')
MAX_FORM_FIELDS = 60
MAX_FORM_EMAILS = 200
MAX_FORM_TITLE, MAX_FORM_DESC, MAX_FORM_SUBMIT = 120, 1000, 60
MAX_FORM_EMAIL = 254

#: The field types a form may COLLECT, as an ALLOW-LIST rather than a list of exclusions β€” the
#: fail-closed direction, because the cost of the two mistakes is not symmetric. A type missing
#: from here is a question the builder cannot ask yet; a type wrongly present is a public door
#: writing values the column cannot mean (an `image` with no upload channel, a `json` document
#: typed into a text box, a `link` naming a record id a stranger guessed).
#: ⚠ NOT sufficient on its own, and the reason is a shape this codebase has been bitten by before:
#: a METRIC bag rides ANY field type (`core/user_tables.py` β€” `metric` is not a field kind), so an
#: `int` column can be machine-computed while passing this list. `routes_forms` therefore asks
#: `user_tables.is_computed_cell` as well β€” one evaluator for "is this computed", reused rather
#: than re-derived ([[one-evaluator-per-question]]).
#: Client mirror: `customer-grid/FormInterface.tsx` FORM_FIELD_TYPES; `verify_forms.py` compares
#: the two files name-for-name.
FORM_FIELD_TYPES = ('text', 'select', 'multiselect', 'int', 'currency', 'pct', 'date',
                    'checkbox', 'phone', 'email', 'url', 'rating')

#: Deliberately looser than a full RFC parse and stricter than `routes_forms._clean_values`' "@ in
#: it": this list decides who MAY SUBMIT, so a typo that silently locks a colleague out is the
#: expensive failure, not an odd address that gets in.
_FORM_EMAIL = re.compile(r'^[^@\s,;]+@[^@\s,;]+\.[^@\s,;]+$')


def _clean_form(raw, valid_keys):
    """One form spec, fail-closed. Returns None when nothing is configured.

    ⚠ FIELD ORDER IS THE FORM'S OWN and is preserved here, not re-derived from the schema: the
    builder let somebody arrange these questions, and sorting them by column order would silently
    rearrange a live form every time a column was added (`_public_form` states the same rule from
    the serving end).

    ⚠ PARTIAL-DROP, not whole-key drop, and the asymmetry against `swipe` above is deliberate. A
    swipe binding is one three-part machine: two of its parts is not a degraded deck, it is a deck
    that can never write. A form is a LIST of questions β€” losing the column behind question three
    costs the asker question three, and taking the whole form away because one field was deleted
    would be a far larger loss than the one that happened.
    """
    if not isinstance(raw, dict):
        return None
    fields, seen = [], set()
    for k in (raw.get('fields') or [])[:MAX_FORM_FIELDS]:
        if k in valid_keys and k not in seen:
            seen.add(k)
            fields.append(k)
    out = {}
    if fields:
        out['fields'] = fields
        # A required flag on a question the form no longer asks is not a rule, it is a trap: the
        # submitter can never satisfy it and the sentence names a field they cannot see.
        req = [k for k in dict.fromkeys(raw.get('required') or []) if k in seen]
        if req:
            out['required'] = req
    for key, cap in (('title', MAX_FORM_TITLE), ('desc', MAX_FORM_DESC),
                     ('submitLabel', MAX_FORM_SUBMIT)):
        text = str(raw.get(key) or '').strip()[:cap]
        if text:
            out[key] = text
    # `public` is the ABSENT default (the `kanbanClamp` law: one way to say one thing), so only
    # the restrictive value is ever stored. β‡’ a spec that loses its `access` key fails OPEN, which
    # is why `emails` is what gets written rather than a `public: false`.
    if raw.get('access') == 'emails':
        out['access'] = 'emails'
    emails = []
    for e in (raw.get('emails') or [])[:MAX_FORM_EMAILS]:
        e = str(e or '').strip().lower()[:MAX_FORM_EMAIL]
        if _FORM_EMAIL.match(e) and e not in emails:
            emails.append(e)
    # Kept even while `access` is public: a person toggling the door open to test it and back
    # again must not lose the list of people they typed. It is never served publicly.
    if emails:
        out['emails'] = emails
    return out or None


#: C3 β€” the swipe binding's option cap. `leftOption`/`rightOption` are stored VALUES of a
#: single-select, and `_clean_options` trims every choice to 120 chars, so this is that same
#: number rather than a second opinion about it: a longer string cannot name a real option, and
#: a SHORTER cap here would silently refuse a binding to a legal one.
MAX_SWIPE_OPTION = 120

#: C-DISP (wave 2026-08-02): the time-series view's bucket vocabulary and caps, plus the
#: calendar-summary metric cap. types.ts mirrors these as TS_BUCKETS / TS_MAX_LAST_N /
#: TS_MAX_FIELDS / MAX_CALENDAR_METRICS, and cleanDisplay applies the same per-entry drops,
#: so an accepted save reads back byte-identically on both engines.
TS_BUCKETS = {'week', 'month', 'quarter', 'year'}
TS_MAX_LAST_N = 120
TS_MAX_FIELDS = 12
MAX_CALENDAR_METRICS = 4
_ISO_DAY = re.compile(r'^\d{4}-\d{2}-\d{2}$')

#: C6-CATALOG (wave 18) β€” the catalog view's vocabulary and caps. types.ts mirrors every name
#: below, and `cleanDisplay` applies the same drops in the SAME ORDER, so an accepted save reads
#: back identically on both engines. The code budget is the order-sensitive one β€” see
#: `_clean_catalogs`.
MAX_CATALOGS = 12
MAX_CATALOG_PAGES = 40
MAX_CATALOG_CODES = 500          # cumulative across ONE catalog's pages, spent in PAGE ORDER
CATALOG_PAPERS = {'letter', 'a4', 'tabloid'}
CATALOG_ORIENTATIONS = {'portrait', 'landscape'}
CATALOG_QUALITIES = {'web', 'print'}
CATALOG_PAGE_KINDS = {'cover', 'intro', 'section', 'gallery'}
CATALOG_COLS = (2, 3, 4)
CATALOG_ID_MAX, CATALOG_NAME_MAX = 40, 80
CATALOG_TITLE_MAX, CATALOG_BODY_MAX, CATALOG_CODE_MAX = 120, 2000, 60
_HEX6 = re.compile(r'^#[0-9A-Fa-f]{6}$')

#: Wave 14 C-ACC ([[loopable-wave14-split]]; rulings R2/R3). Mirrored by types.ts
#: TS_DELTA_KINDS / TS_MAX_CUSTOM_ROWS / TS_MAX_STYLES β€” the C-DISP byte-identical law.
TS_DELTA_KINDS = ('abs', 'pct', 'yoy', 'ytd')
TS_MAX_CUSTOM_ROWS = 12
TS_MAX_STYLES = 200
TS_MAX_EXPR = 500


def _ts_formula_source_ok(expr):
    """Transport wall for a Time Series formula governed by the shared server parser.

    This function deliberately does not duplicate the formula grammar. It preserves any bounded
    source, including quotes and regex punctuation, for the API parser to accept or explain. The
    sole syntax-shaped refusal is an unquoted square bracket: the shared contract declares that
    legacy ``[field]`` references cannot enter the braces-only grammar. Brackets inside a quoted
    regex/text literal remain ordinary source and round-trip byte-for-byte.
    """
    if not isinstance(expr, str) or len(expr) > TS_MAX_EXPR:
        return False
    quote, i = None, 0
    while i < len(expr):
        char = expr[i]
        if quote:
            if char == quote:
                if i + 1 < len(expr) and expr[i + 1] == quote:
                    i += 2
                    continue
                quote = None
            i += 1
            continue
        if char in ("'", '"'):
            quote = char
        elif char in '[]':
            return False
        i += 1
    return True

#: Old wire value -> the value we store today. Applied AFTER the membership test so an unknown
#: mode is still rejected rather than accidentally aliased.
_LEGACY_MODES = {'dashboard': 'chart'}

#: Chart kinds a chart-mode view may hold (wave-8 I19, contract C2). Mirrors the client's
#: union. Deliberately small: the owner asked to "start with simple charts" and expand, and a
#: kind the client cannot draw is worse than one that does not exist yet.
#: Wave-16 C-CHARTCAP: + 'table' β€” the group-by aggregate table (by-rep / by-BU /
#: top-customers, the third Sales block shape). Client renderer: DashboardView's
#: GroupTableView over salesParity.tableFromSpec.
CHART_KINDS = {'bar', 'line', 'area', 'donut', 'kpi', 'table'}
CHART_AGGS = {'sum', 'avg', 'count', 'min', 'max'}

#: ⭐ WAVE-29 C7 (item 17) β€” THE COLUMN-SUMMARY vocabulary: what a FIELD's `agg` may be, which is
#: what the grid's totals row and its per-group subtotals compute. ORDERED, because the order is
#: the picker's order; membership tests read it as a tuple perfectly well.
#:
#: β›” IT IS NOT `CHART_AGGS` AND THE TWO MUST NOT BE MERGED, however alike they look. `CHART_AGGS`
#: gatekeeps a STORED value with live data behind it (`charts[].agg`, `calendarMetrics[].agg`):
#: `_clean_chart` falls back to 'sum' on an unknown agg and `_clean_display` DROPS a whole
#: calendarMetrics entry, so renaming its 'avg' would silently turn every saved chart into a sum
#: and delete calendar cards, with nothing red. A chart's aggregation and a column's summary are
#: also different questions β€” one reduces a SERIES, the other a COLUMN β€” and one list serving both
#: would have to be the intersection of what each can express.
#:
#: ⭐ `average`, NOT `avg`, and the tie is broken by the vocabulary we cannot rename: `ROLLUP_FNS`
#: (`core/user_tables.py`, 16 names, 47 rollups live in production) already spells it `average`,
#: and it is the aggregate vocabulary a user actually reads today. Spelling it `avg` here would
#: give the product two words for one operation on two menus a click apart.
#:
#: ⚠ `median` is net-new: it is in NEITHER `CHART_AGGS` nor `ROLLUP_FNS`, so a Median column
#: summary has no rollup equivalent and this list is NOT a subset of either of its neighbours.
#:
#: ⚠ `count` counts ROWS in the scope (the group, or every matched row) β€” not non-blank cells.
#: `ROLLUP_FNS` splits that hair three ways (count / counta / countall); a column summary does not,
#: and must not grow a second spelling of it.
#:
#: Client mirror: `customer-grid/iconShapes.ts` FIELD_AGGS β€” ONE client list, imported by
#: `aggregations.ts` and the field editor rather than re-declared, so the only boundary left to
#: police is this one. `verify_icons.py::agg_parity` reads BOTH FILES and compares them.
FIELD_AGGS = ('sum', 'average', 'median', 'min', 'max', 'count')

#: ⭐⭐ WAVE 50 Β· W50-T03 Β· CONTRACT C1 (owner rulings R1 + R2) β€” **THE SUMMARY BAR'S WIRE
#: VOCABULARY, AND IT IS DELIBERATELY NOT `FIELD_AGGS` WITH TWO MORE NAMES.**
#:
#: C1, verbatim: ``agg ∈ sum | average | median | min | max | count | count_distinct |
#: percentile`` with ``p`` 0-100 for ``percentile``. This tuple is that clause, in that order,
#: and it is what the windowed-aggregate route (``POST /api/v1/odoo-tables/<key>/aggregates``)
#: admits an ``agg`` against.
#:
#: β›” WHY NOT WIDEN `FIELD_AGGS`. That list is what a FIELD's ``agg`` may be, and THREE literals
#: gate a WRITE on it β€” this one, ``core/user_tables.FIELD_AGGS`` (``_clean_field``, the door
#: that silently discards an ``agg`` it does not recognise) and the client's
#: ``customer-grid/iconShapes.FIELD_AGGS`` β€” held name-for-name in order by
#: ``verify_icons.py::agg_parity``. R2 moved the summary choice OFF ``field.agg`` and onto the
#: VIEW (``ViewConfig.summary``), so adding ``count_distinct`` and ``percentile`` there would
#: widen a per-field setting the ruling just retired, in three files, for no consumer. The two
#: vocabularies OVERLAP by six names and are not one list β€” the same relationship ``FIELD_AGGS``
#: already has with ``CHART_AGGS`` and ``ROLLUP_FNS``.
#:
#: Client mirror: ``customer-grid/iconShapes.SUMMARY_AGGS``, held in step by
#: ``aios-web/web/verify_grid_ux.py``'s summary-bar section against C1's clause typed in frozen.
#: ⚠ ``count_distinct`` is the SQL name, not ``unique``: the word on screen lives in the client's
#: label table, and a wire vocabulary that spells itself the way the screen does is one rename
#: away from meaning nothing to the compiler.
SUMMARY_AGGS = ('sum', 'average', 'median', 'min', 'max', 'count',
                'count_distinct', 'percentile')

#: ⭐ W50-T05 / R4 β€” how a numeric column READS: its own value, its share of the VIEW's grand total,
#: or the value with the share beneath it. Client mirror: ``ui/fmt.ts::SHOW_AS_MODES``; the server
#: twin that validates the write is ``core/user_tables.SHOW_AS_MODES``.
#:
#: β›” THIS IS THE THIRD LIST IN THIS FILE THAT LOOKS MERGEABLE AND IS NOT, and the note above
#: already records what merging two of them costs. ``FIELD_AGGS`` and ``SUMMARY_AGGS`` both answer
#: WHICH NUMBER to compute over a set of rows; this answers HOW THE NUMBER ALREADY IN THE CELL IS
#: DRAWN. They are independent by design β€” a Sum column can read as a share, and so can a column
#: carrying no summary at all β€” so a field can hold one value from each list at the same time.
SHOW_AS_MODES = ('value', 'share', 'both')

MAX_CHARTS = 12                 #: per view β€” a dashboard, not an unbounded render loop
MAX_CHART_TITLE = 60

#: Wave-9 I11 (contract C2) β€” chart customisation, host-validated.
#:
#: `palette` names a colour JOB, never a colour. A browser must not be able to post a raw hex:
#: the four names below map to the four jobs a palette can do (identity / magnitude / polarity)
#: and resolve to brand ramps client-side, so a tenant restyle cannot be defeated by a stored
#: literal. STATUS colours (good/warning/serious/critical) are deliberately NOT selectable β€”
#: they are reserved signal, and reusing them as "series 4" is how a chart starts lying.
CHART_PALETTES = {'brand', 'categorical', 'sequential', 'diverging'}
CHART_FORMATS = {'auto', 'number', 'currency', 'percent', 'compact'}
MAX_AXIS_LABEL = 40
#: `size` is the I10 drag. Width is in GRID COLUMNS (a 12-column board), height in px.
CHART_W_RANGE = (1, 12)
CHART_H_RANGE = (120, 800)


def _clean_chart(raw, valid_keys):
    """One dashboard chart, fail-closed. Returns None if the chart cannot be drawn.

    A chart's `y` is optional (absent = count of rows, which is what "how many customers per
    state" means). `x` is NOT: a chart with no category axis has nothing to plot against, and
    silently keeping it would put an empty card on the dashboard with no way to tell why.
    """
    if not isinstance(raw, dict):
        return None
    kind = raw.get('kind')
    if kind not in CHART_KINDS:
        return None
    x = raw.get('x')
    if x not in valid_keys:
        return None                     # dead category ref -> the chart goes, not the board
    cid = raw.get('id')
    if not isinstance(cid, str) or not cid.strip():
        return None                     # the client owns chart ids; an unidentified card
        # cannot be edited or removed, so it must not persist
    out = {'id': cid.strip()[:64], 'kind': kind, 'x': x,
           'agg': raw.get('agg') if raw.get('agg') in CHART_AGGS else 'sum'}
    if raw.get('y') in valid_keys:
        out['y'] = raw['y']
    else:
        # no measurable column -> the only honest aggregation left is "how many rows"
        out['agg'] = 'count'
    title = raw.get('title')
    if isinstance(title, str) and title.strip():
        out['title'] = title.strip()[:MAX_CHART_TITLE]

    # ── wave-9 I11 (contract C2): customisation ────────────────────────────────────────────
    # `splitBy` is the field whose values become the SERIES. It is deliberately not called
    # `colorBy`: that name already means two other things here (`config.colorBy` = row
    # colouring, `display.colorField` = map pin colour) and a third sense would be unreadable.
    if raw.get('splitBy') in valid_keys and raw['splitBy'] != x:
        out['splitBy'] = raw['splitBy']
    # Stacking is only a question once there are series to stack, and only for the two kinds
    # that can express it. Anywhere else it is dropped rather than stored as a lie the client
    # would have to re-decide.
    if out.get('splitBy') and kind in ('bar', 'area') and raw.get('stacked') is True:
        out['stacked'] = True
    if raw.get('palette') in CHART_PALETTES:
        out['palette'] = raw['palette']

    axis = raw.get('axis')
    if isinstance(axis, dict):
        # β›” ONE y-scale, always. There is no second-axis key here and there must never be:
        # two y-scales on one frame can manufacture any correlation you like by rescaling, and
        # the honest alternatives are two charts, small multiples, or indexing to a common base.
        # Ruled explicitly in contract C2 against the "Tableau versatility" brief.
        clean_axis = {}
        for side in ('x', 'y'):
            spec = axis.get(side)
            if not isinstance(spec, dict):
                continue
            one = {}
            lab = spec.get('label')
            if isinstance(lab, str) and lab.strip():
                one['label'] = lab.strip()[:MAX_AXIS_LABEL]
            if spec.get('format') in CHART_FORMATS:
                one['format'] = spec['format']
            if one:
                clean_axis[side] = one
        if clean_axis:
            out['axis'] = clean_axis

    size = raw.get('size')
    if isinstance(size, dict):
        one = {}
        for key, (lo, hi) in (('w', CHART_W_RANGE), ('h', CHART_H_RANGE)):
            try:
                one[key] = max(lo, min(hi, int(size[key])))
            except (KeyError, TypeError, ValueError):
                pass            # a partial size is fine: the client defaults the missing axis
        if one:
            out['size'] = one

    # ── Wave 14 R3 ([[loopable-wave14-split]]): a METRIC chart may carry a PERIOD β€” the
    # trend-over-buckets encoding. Kept only when the chart's value field is measure-backed:
    # a category column has no time dimension, and a stored period on it would promise a
    # trend the TS channel must refuse. `span` is meaningful only beside `bucket`.
    if isinstance(out.get('y'), str) and out['y'].startswith('measure_'):
        if raw.get('bucket') in TS_BUCKETS:
            out['bucket'] = raw['bucket']
            sp = raw.get('span')
            if isinstance(sp, dict):
                n = sp.get('lastN')
                if (isinstance(n, int) and not isinstance(n, bool)
                        and 1 <= n <= TS_MAX_LAST_N):
                    out['span'] = {'lastN': n}
        # ── Wave-16 C-CHARTCAP: the YoY companion. Kept ONLY where it can mean something β€”
        # beside a kept bucket (the compare series) or on a sum-of-metric KPI (the delta
        # line). Anything else is a stored claim the renderer would have to re-refuse.
        # Mirrors the client's cleanCharts rule key for key.
        if raw.get('compare') == 'prior_year' and (
                out.get('bucket') or (kind == 'kpi' and out.get('agg') == 'sum')):
            out['compare'] = 'prior_year'
    return out


def _clean_catalog_page(raw, budget):
    """C6-CATALOG β€” one page of a catalog. Returns `(page | None, codes_spent)`.

    `budget` is what is LEFT of the catalog's 500-code allowance. Codes are deduped WITHIN a
    page and not across the catalog: a product legitimately appears on a gallery page and again
    in its section listing, and de-duplicating globally would silently delete the second
    appearance. The budget is spent in page order, so a catalog that runs out loses the TAIL of
    its last pages β€” never a random scatter, and never a page (a page with no products is a
    heading the user can still see and fix).
    """
    if not isinstance(raw, dict):
        return None, 0
    page_id = str(raw.get('id') or '')[:CATALOG_ID_MAX]
    kind = raw.get('kind')
    if not page_id or kind not in CATALOG_PAGE_KINDS:
        return None, 0
    out = {'id': page_id, 'kind': kind}
    for key, cap in (('title', CATALOG_TITLE_MAX), ('body', CATALOG_BODY_MAX),
                     ('imageCode', CATALOG_CODE_MAX)):
        v = raw.get(key)
        if isinstance(v, str) and v:
            out[key] = v[:cap]
    products = raw.get('products')
    if isinstance(products, list) and budget > 0:
        clean_p, seen_p = [], set()
        for c in products:
            if not isinstance(c, str) or not c:
                continue
            c = c[:CATALOG_CODE_MAX]
            if c in seen_p:
                continue
            seen_p.add(c)
            clean_p.append(c)
            if len(clean_p) >= budget:
                break
        if clean_p:
            out['products'] = clean_p
    layout = raw.get('layout')
    if isinstance(layout, dict):
        clean_l = {}
        cols = layout.get('cols')
        if isinstance(cols, int) and not isinstance(cols, bool) and cols in CATALOG_COLS:
            clean_l['cols'] = cols
        # The kanbanClamp/tsSparkline asymmetry, one per direction: pack and colour SHOW by
        # default (the 2027 catalogue shows both), price does NOT (it shows no prices at all).
        # So only the opt-OUT is storable for the first two and only the opt-IN for the third β€”
        # a second spelling of a default is how a round trip starts churning.
        if layout.get('showPack') is False:
            clean_l['showPack'] = False
        if layout.get('showColor') is False:
            clean_l['showColor'] = False
        if layout.get('showPrice') is True:
            clean_l['showPrice'] = True
        if clean_l:
            out['layout'] = clean_l
    return out, len(out.get('products') or ())


def _clean_catalogs(raw, valid_keys):
    """C6-CATALOG (wave 18) β€” `display.catalogs`, fail-closed. Returns a list or None.

    A catalog is a PRINT artifact, so the two structural keys that decide how it paginates
    (`paper`, `orientation`) are NORMALISED WITH A DEFAULT rather than dropped: a page box with
    no size is not a smaller catalog, it is an unrenderable one. Everything else follows the
    house rules β€” unknown keys dropped, per-entry drops never cost the neighbours, empty
    sub-objects omitted entirely (`brand`, `fields`, `layout`, `products`) so an absent key and
    an empty one are not two spellings of the same nothing.

    `fields` binds the listing lines to real columns (the 2027 listing prints description / SKU /
    pack / colour, and `product_data` carries no pack or colour of its own β€” the user binds
    custom fields). Refs are checked against `valid_keys` HERE and not on the client, the same
    split `dateField`/`stackField` already run.
    """
    if not isinstance(raw, list):
        return None
    out = []
    for c in raw:
        if len(out) >= MAX_CATALOGS:
            break
        if not isinstance(c, dict):
            continue
        cat_id = str(c.get('id') or '')[:CATALOG_ID_MAX]
        name = c.get('name')
        # An EMPTY name is legal (the user cleared the box and will type again) β€” an ABSENT one
        # is a malformed record. The `tsRows` label rule, same reasoning.
        if not cat_id or not isinstance(name, str):
            continue
        cat = {'id': cat_id, 'name': name[:CATALOG_NAME_MAX]}
        cat['paper'] = c['paper'] if c.get('paper') in CATALOG_PAPERS else 'letter'
        cat['orientation'] = (c['orientation']
                              if c.get('orientation') in CATALOG_ORIENTATIONS else 'portrait')
        if c.get('quality') in CATALOG_QUALITIES:
            cat['quality'] = c['quality']
        brand = c.get('brand')
        if isinstance(brand, dict):
            clean_b = {}
            for k in ('primary', 'accent'):
                v = brand.get(k)
                if isinstance(v, str) and _HEX6.match(v):
                    clean_b[k] = v
            company = brand.get('company')
            if isinstance(company, str) and company:
                clean_b['company'] = company[:CATALOG_NAME_MAX]
            # An asset CODE (resolved through C2-ASSET), never a URL: an arbitrary host inside
            # print CSS is exactly the tokens-not-values rule this contract carries.
            logo = brand.get('logo')
            if isinstance(logo, str) and logo:
                clean_b['logo'] = logo[:CATALOG_CODE_MAX]
            if clean_b:
                cat['brand'] = clean_b
        binds = c.get('fields')
        if isinstance(binds, dict):
            clean_bind = {k: binds[k] for k in ('name', 'pack', 'color', 'price')
                          if binds.get(k) in valid_keys}
            if clean_bind:
                cat['fields'] = clean_bind
        pages, budget = [], MAX_CATALOG_CODES
        raw_pages = c.get('pages')
        if isinstance(raw_pages, list):
            for p in raw_pages:
                if len(pages) >= MAX_CATALOG_PAGES:
                    break
                page, spent = _clean_catalog_page(p, budget)
                if page is None:
                    continue
                budget -= spent
                pages.append(page)
        # ALWAYS emitted, even empty: a catalog with no pages yet is the state every catalog
        # starts in, and dropping the key would make "new" and "corrupt" the same wire value.
        cat['pages'] = pages
        out.append(cat)
    return out or None


def _clean_display(raw, valid_keys):
    """Structural passthrough for a view's `config.display` (wave-6 item 10), fail-closed.

    `{mode, dateField?, stackField?, titleField?, colorField?, sizeField?, coordField?, charts?}` β€” mode
    must be known. `coordField` is retained only to read older saved Views; new Map source setup
    is database-owned. Every field ref must name a field this table has (a ref to a deleted field is DROPPED and the client falls
    back to its per-mode default); unknown keys are
    dropped. What each mode MEANS β€” calendar wants a date-family field, kanban a select-family
    stack, map a single-select to colour by and a numeric to size by β€” is the client's
    business: it is the only layer that renders them, and a wrong-typed ref degrades to that
    surface's default rather than to an error (the `_clean_window` split).

    Wave-8 (contract C2) adds the map encodings (`colorField` I3, `sizeField` I5) and
    dashboard `charts` (I19). A chart whose x/y names a deleted field is dropped INDIVIDUALLY β€”
    never the whole array, because losing one column should not cost the user a dashboard they
    spent time building.

    W33-T45 (contract C1, ruling R5) adds `published` + `publishAccess`. ⚠ THE HALF OF THE ROUND
    TRIP THIS FUNCTION CANNOT ENFORCE: `customer-grid/types.ts::cleanDisplay` is a SECOND
    normalizer, in the browser, which rebuilds the config key by key on every autosave and drops
    anything it does not name. A key accepted here and unknown there dies on the next column
    resize β€” silently, because the client then POSTs the stripped config and the host REPLACES
    the stored one. "The host accepts it" is half a round trip; that file is the other half.
    """
    if not isinstance(raw, dict):
        return None
    # Boot purges run while requests are live. Preserve retired identity until removal,
    # so a racing workspace rewrite cannot silently turn a retired view into a grid.
    if raw.get('mode') in _RETIRED_MODES:
        return {'mode': raw['mode']}
    # W48-T07 / R3 β€” view configuration is data interpreted by deployed renderers, never
    # tenant-supplied executable code. Reject the common script escape hatches rather than
    # silently dropping them, which would make a caller believe an expression was persisted.
    if any(key in raw for key in ('expr', 'formula', 'signal', 'fn')):
        return None
    mode = raw.get('mode')
    if mode not in DISPLAY_MODES:
        return None
    # Grid is normally represented by an absent display object. Retain a valid legacy Map source
    # when an older configured Map view returns here, while refusing every unrelated Grid-only
    # display setting. Without this compatibility exception existing views lose their pins on the
    # next server round trip.
    if mode == 'grid':
        coord_field = raw.get('coordField')
        if raw.get('groupSummary') is not True:
            return {'mode': 'grid', 'coordField': coord_field} if coord_field in valid_keys else None
        # The C1 display member carries the grid's group summary toggle. Store only True.
        out = {'mode': 'grid', 'groupSummary': True}
        if coord_field in valid_keys:
            out['coordField'] = coord_field
        return out
    # Wave-9 I10 (C2): normalise the legacy wire value AFTER the membership test, so an unknown
    # mode is still rejected rather than accidentally aliased into a real one. Every already
    # saved 'dashboard' view reads back as 'chart' from here on; nothing writes 'dashboard'.
    mode = _LEGACY_MODES.get(mode, mode)
    out = {'mode': mode}
    if raw.get('groupSummary') is True:
        out['groupSummary'] = True
    # `coordField` is the older per-View fallback. Keep it in the regular field-ref loop so a
    # deleted source fails safely; the current source is served separately as database setup.
    for ref in ('dateField', 'stackField', 'titleField', 'colorField', 'sizeField', 'coordField'):
        if raw.get(ref) in valid_keys:
            out[ref] = raw[ref]
    # ── C-DISP (wave 2026-08-02) ─────────────────────────────────────────────────────────
    # kanbanClamp: stored ONLY as the literal opt-OUT. Absent means clamped β€” the new
    # standardized default β€” so storing True would be a second way to say nothing (the same
    # rule that keeps mode:'grid' out of the store).
    if raw.get('kanbanClamp') is False:
        out['kanbanClamp'] = False
    if raw.get('calendarMode') in ('records', 'summary'):
        out['calendarMode'] = raw['calendarMode']
    metrics = raw.get('calendarMetrics')
    if isinstance(metrics, list):
        clean_m, seen_m = [], set()
        for m in metrics[:MAX_CALENDAR_METRICS]:
            # Dropped INDIVIDUALLY (the charts precedent): one dead metric must not cost the
            # user the summary card they configured around it.
            if not isinstance(m, dict):
                continue
            mid = str(m.get('id') or '')[:40]
            if (not mid or mid in seen_m or m.get('field') not in valid_keys
                    or m.get('agg') not in CHART_AGGS):
                continue
            seen_m.add(mid)
            clean_m.append({'id': mid, 'field': m['field'], 'agg': m['agg']})
        if clean_m:
            out['calendarMetrics'] = clean_m
    if raw.get('tsBucket') in TS_BUCKETS:
        out['tsBucket'] = raw['tsBucket']
    span = raw.get('tsSpan')
    if isinstance(span, dict):
        clean_span = {}
        n = span.get('lastN')
        if isinstance(n, int) and not isinstance(n, bool) and 1 <= n <= TS_MAX_LAST_N:
            clean_span['lastN'] = n
        else:
            f, t = span.get('from'), span.get('to')
            f = f if isinstance(f, str) and _ISO_DAY.match(f) else None
            t = t if isinstance(t, str) and _ISO_DAY.match(t) else None
            if f and t and f > t:
                f, t = t, f
            if f:
                clean_span['from'] = f
            if t:
                clean_span['to'] = t
        if clean_span:
            out['tsSpan'] = clean_span
    ts_fields = raw.get('tsFields')
    if isinstance(ts_fields, list):
        clean_f, seen_f = [], set()
        for k in ts_fields[:TS_MAX_FIELDS]:
            if k in valid_keys and k not in seen_f:
                seen_f.add(k)
                clean_f.append(k)
        if clean_f:
            out['tsFields'] = clean_f
    # Native series are declarative measure references, never generated tenant fields.
    ts_metrics = raw.get('tsMetrics')
    if isinstance(ts_metrics, list):
        clean_m, seen_m = [], set()
        for item in ts_metrics[:TS_MAX_FIELDS]:
            if not isinstance(item, dict):
                continue
            key = str(item.get('key') or '').strip()[:80]
            if not key or key in seen_m:
                continue
            seen_m.add(key)
            metric = {'key': key}
            label = str(item.get('label') or '').strip()[:120]
            if label:
                metric['label'] = label
            clean_m.append(metric)
        if clean_m:
            out['tsMetrics'] = clean_m
    # ── Wave 14 C-ACC ([[loopable-wave14-split]] R2; items 17/18) ────────────────────────
    deltas = raw.get('tsDeltas')
    if isinstance(deltas, list):
        clean_d, seen_d = [], set()
        for d in deltas:
            if d in TS_DELTA_KINDS and d not in seen_d:
                seen_d.add(d)
                clean_d.append(d)
        if clean_d:
            out['tsDeltas'] = clean_d
    # Gridlines: stored ONLY as the literal opt-OUT (absent = shown), sparkline ONLY as the
    # literal opt-IN (absent = off) β€” the kanbanClamp asymmetry, one per direction.
    if raw.get('tsGridlines') is False:
        out['tsGridlines'] = False
    if raw.get('tsSparkline') is True:
        out['tsSparkline'] = True
    rows = raw.get('tsRows')
    if isinstance(rows, list):
        clean_r, seen_r = [], set()
        for r in rows[:TS_MAX_CUSTOM_ROWS]:
            if not isinstance(r, dict):
                continue
            rid = str(r.get('id') or '')[:40]
            r_kind = r.get('kind')
            if not rid or rid in seen_r or r_kind not in ('note', 'formula'):
                continue
            label = r.get('label')
            if not isinstance(label, str):
                continue    # ABSENT label = malformed; an EMPTY one is a legal spacer row
                # (GRID's dated asymmetry amendments, 2026-08-02)
            one = {'id': rid, 'kind': r_kind, 'label': label.strip()[:120]}
            if r_kind == 'formula':
                expr = r.get('expr')
                if _ts_formula_source_ok(expr):
                    one['expr'] = expr
                # Else keep the ROW and drop only the source. Legacy square references and
                # over-bound transport cannot enter the shared formula parser; deleting the row
                # would also delete the user's label and its saved order.
            seen_r.add(rid)
            clean_r.append(one)
        if clean_r:
            out['tsRows'] = clean_r
    styles = raw.get('tsStyles')
    if isinstance(styles, dict):
        clean_s = {}
        for s_key, s_val in styles.items():
            if len(clean_s) >= TS_MAX_STYLES:
                break               # capped, not truncated silently: the gate names this
            if not isinstance(s_key, str) or not s_key or len(s_key) > 96:
                continue            # key = rowId or "rowId:colKey" β€” the client's grammar
            if not isinstance(s_val, dict):
                continue
            one = {}
            if s_val.get('bold') is True:
                one['bold'] = True
            if s_val.get('line') is True:
                one['line'] = True
            if one:
                clean_s[s_key] = one
        if clean_s:
            out['tsStyles'] = clean_s
    charts = raw.get('charts')
    if isinstance(charts, list):
        clean = [c for c in (_clean_chart(x, valid_keys) for x in charts[:MAX_CHARTS]) if c]
        # de-dupe by id: two cards sharing an id are one card as far as the client's keyed
        # render is concerned, and the second would silently shadow the first
        seen, uniq = set(), []
        for c in clean:
            if c['id'] in seen:
                continue
            seen.add(c['id'])
            uniq.append(c)
        if uniq:
            out['charts'] = uniq
    # ── C6-CATALOG (wave 18) ─────────────────────────────────────────────────────────────
    catalogs = _clean_catalogs(raw.get('catalogs'), valid_keys)
    if catalogs:
        out['catalogs'] = catalogs
    # ── ⭐⭐ WAVE-37 C3 (T21) β€” `catalog`, SINGULAR, and it is NOT the line above it. See the
    # header on `_clean_catalog_spec` for the two-keys-one-letter-apart warning; this call site is
    # where a reader is most likely to "fix" one into the other.
    catalog = _clean_catalog_spec(raw.get('catalog'), valid_keys)
    if catalog:
        out['catalog'] = catalog
    # ── ⭐ WAVE-27 C3 (item 8 / R2): the swipe binding ────────────────────────────────────
    # `{fieldKey, leftOption, rightOption}` β€” WHOLE-KEY drop, never a partial one, and that
    # asymmetry against `charts`/`calendarMetrics` above is the point rather than an oversight.
    # Those are LISTS of independent cards, so losing one entry costs the user one card. This is
    # a single three-part BINDING: a swipe view holding a fieldKey with one option, or two
    # options and no field, is not a degraded swipe view β€” it is a deck that can never write
    # anything, rendered as though it were configured. Dropping the key entirely puts the view
    # back in its honest unconfigured state, which is the one state the client has a UI for.
    #
    # ⚠ What this CANNOT check, deliberately, and why the client must: whether `fieldKey` names
    # a SELECT, and whether the two options are still in that select's vocabulary. `valid_keys`
    # is a key set, and the docstring above draws this exact line β€” "what each mode MEANS ... is
    # the client's business". So SwipeView owns three losses this function is blind to (field
    # deleted, field retyped away from select, option removed) and must SHOW each one rather
    # than fall back to the first option, per the `viewModes.tsx` house rule.
    swipe = raw.get('swipe')
    if isinstance(swipe, dict):
        f_key = swipe.get('fieldKey')
        left, right = swipe.get('leftOption'), swipe.get('rightOption')
        ok = (f_key in valid_keys
              and isinstance(left, str) and isinstance(right, str))
        if ok:
            left, right = left.strip()[:MAX_SWIPE_OPTION], right.strip()[:MAX_SWIPE_OPTION]
            # Both non-empty, and DISTINCT: one option on both sides is a deck whose two
            # gestures do the same thing, which is two spellings of one state (the
            # `kanbanClamp` law) wearing a control that promises a choice.
            if left and right and left.casefold() != right.casefold():
                out['swipe'] = {'fieldKey': f_key, 'leftOption': left, 'rightOption': right}
    # ── ⭐⭐ WAVE-29 R7 (item 10): the FORM spec β€” see `_clean_form` for why the token is not here.
    form = _clean_form(raw.get('form'), valid_keys)
    if form:
        out['form'] = form
    # ── ⭐⭐ W33-T45 / CONTRACT C1 / RULING R5 (owner item 8b): IS THIS INTERFACE PUBLISHED ────
    #
    # β›” TWO KEYS LIVE HERE AND TWO DELIBERATELY DO NOT. The `published` flag and the sharer's
    # `public | password` choice are DISPLAY state β€” the view says what it is, the client renders
    # a badge from it, and it travels with the view like every other key in this dict. The SECRET
    # TOKEN and the PASSPHRASE HASH do not: they live in the server-only bucket, exactly as
    # `routes_forms.py`'s `TOKENS_KEY` holds the form token. `config.display` is echoed back to
    # every user who can open the view, so a token in here is a token published to the audience
    # the password was meant to exclude. `_clean_form` above carries the same rule and the same
    # reason; this is the second door, not a new one.
    #
    # β›” AND THE COERCION IS FAIL-CLOSED, WHICH IS WHY THIS IS NOT A BARE ALLOWLIST. A plain
    # allowlist drops an unrecognised `publishAccess` and KEEPS `published: True` β€” leaving a
    # published view with no stated access, i.e. a third state neither the ruling nor the client
    # has a meaning for, on the one key where guessing wrong publishes a tenant's data to the
    # open internet. So: a published view ALWAYS carries an access, and anything that is not the
    # literal `'public'` reads as `'password'`. The unpublished case stores nothing at all β€”
    # absent means unpublished, and a `published: False` would be the second way to say nothing
    # that `kanbanClamp` and `mode: 'grid'` are both here to forbid.
    if raw.get('published') is True:
        out['published'] = True
        out['publishAccess'] = 'public' if raw.get('publishAccess') == 'public' else 'password'
    return out


#: FOLDERS over the saved views / cohorts sidebars (wave-8 I11, contract C4).
#:
#: ⚠ Folder membership is stored as a SIDE MAP (`itemFolders`), not as a `folderId` ON each
#: view or cohort β€” a deliberate amendment to C4's first wording, recorded in the split doc.
#: Two reasons. (1) A cohort lives in a DIFFERENT store (`customer_cohorts`, keyed by cohort
#: id) and adding a `folders` key beside those ids would collide with a cohort whose generated
#: id happened to be 'folders'. (2) Folder placement is a per-user ORGANISING act, not part of
#: what a view IS: keeping it out of the view config means duplicating or exporting a view does
#: not drag a folder reference along with it. One map, one home, both surfaces.
FOLDER_SURFACES = {"views", "cohorts"}
MAX_FOLDERS = 60
MAX_FOLDER_NAME = 80

#: Wave-9 I15 (contract C5) β€” a user-chosen folder icon, as {shape, tone}.
#:
#: Both halves are WHITELISTS, never free values: `shape` names geometry the client already
#: draws (one source, `iconShapes.ts`, read by both painters) and `tone` names a palette token,
#: not a colour β€” so a browser cannot post a hex and defeat a tenant restyle, and a shape the
#: client cannot render can never reach the store.
#: ⚠ MIRRORS CLIENT'S `iconShapes.ts` ENUMERATION EXACTLY (C5: CLIENT enumerates, HOST mirrors β€”
#: posted in the split doc 2026-07-29, HOST adopted it the same day, replacing a provisional
#: 12-shape guess of mine that contained shapes the client cannot draw). Do not extend this set
#: without the matching client geometry: an unknown shape falls back to the default folder mark,
#: which is also I14's "existing folders get the folder icon" for every pre-wave-9 folder.
FOLDER_ICON_SHAPES = {
    "folder", "star", "flag", "tag", "bookmark", "grid", "chart", "map", "users",
    "clock", "heart", "bolt",
}
#: Tones are the C1 pastels β€” FILLS ONLY, never text. This mirrors the current client vocabulary;
#: the old host spelling `grey` is accepted as a read/write migration alias for `neutral` below.
FOLDER_ICON_TONES = {"neutral", "blue", "green", "yellow", "red"}
FOLDER_ICON_DEFAULT_TONE = "neutral"


def clean_folder_icon(raw):
    """{shape, tone} or None. Fail-closed on both halves, independently.

    A folder with a valid shape but a junk tone keeps the shape and defaults the tone rather
    than losing the icon entirely β€” losing a user's pick because one half was wrong is the kind
    of silent data loss the folder events already avoid elsewhere.
    """
    if not isinstance(raw, dict):
        return None
    shape = raw.get("shape")
    if shape not in FOLDER_ICON_SHAPES:
        return None
    tone = raw.get("tone")
    # The first host implementation called the neutral tone `grey`. Accept that legacy value so
    # an existing folder cannot crash a newer client, but canonicalise it on the next workspace
    # write/read to the current shared vocabulary.
    if tone == "grey":
        tone = FOLDER_ICON_DEFAULT_TONE
    return {"shape": shape,
            "tone": tone if tone in FOLDER_ICON_TONES else FOLDER_ICON_DEFAULT_TONE}


def clean_folders(raw):
    """Validate the per-surface folder lists, fail-closed. {surface: [{id, name, order}]}."""
    out = {}
    for surface in FOLDER_SURFACES:
        items, seen = [], set()
        for f in list((raw or {}).get(surface) or [])[:MAX_FOLDERS]:
            if not isinstance(f, dict):
                continue
            fid = str(f.get("id") or "").strip()[:80]
            name = str(f.get("name") or "").strip()[:MAX_FOLDER_NAME]
            if not fid or not name or fid in seen:
                continue          # an unidentified or unnamed folder cannot be shown or edited
            seen.add(fid)
            try:
                order = int(f.get("order", len(items)))
            except (TypeError, ValueError):
                order = len(items)
            row = {"id": fid, "name": name, "order": order}
            icon = clean_folder_icon(f.get("icon"))      # wave-9 I15 (C5); absent = default mark
            if icon:
                row["icon"] = icon
            # W41-T12 / T33 / OWNER INSTRUCTION 12 -- `parent` SURVIVES THIS FUNCTION NOW.
            # THIS ONE LINE IS WHY NESTING WAS DEAD. Every other half shipped and worked:
            # `ViewSidebar.tsx:316` takes a `parent`, `CustomerGrid.tsx:7432` puts it on the wire,
            # `table_store.validate_folder_tree` refuses cycles and chains over `MAX_FOLDER_DEPTH`
            # with a worded receipt, and `grid_events` already catches `FolderTreeError` into
            # `_folder_refuse`. This row build STRIPPED the key on the way in, so the validator
            # could never fire and a folder made inside a folder was gone on refresh -- a feature
            # dead behind four correct halves and every gate green. `grid_events.py` stated the
            # forward contract itself: "the day `clean_folders` learns `parent`, the refusal is
            # already wired and worded". This is that day.
            #
            # ABSENT, NEVER `None`, and never invented. An absent `parent` IS the root, which is
            # what every stored row has meant until now -- and `validate_folder_tree` promises that
            # a payload carrying no `parent` anywhere comes back byte-identical with zero repairs,
            # so writing a null key would break that promise for no gain.
            # SELF-PARENTING IS DROPPED HERE as well as refused downstream: the validator raises
            # `cycle` on it, and a row that cannot be legal should not reach the validator wearing
            # a repair. A parent naming a folder that is GONE is deliberately NOT dropped here --
            # deleting a folder creates exactly that, and `validate_folder_tree` repairs it to the
            # root WITH a receipt the user can read. Dropping it silently here would destroy the
            # receipt, and the user would never learn their folder had moved.
            parent = str(f.get("parent") or "").strip()[:80]
            if parent and parent != fid:
                row["parent"] = parent
            items.append(row)
        items.sort(key=lambda x: x["order"])
        for i, f in enumerate(items):
            f["order"] = i                     # re-index so `order` is always dense and total
        if items:
            out[surface] = items
    return out


#: ⭐⭐ WAVE 32 Β· OWNER ITEM 20 (`W32-T27`, raised by SESSION C as ASK C-16) β€” "FILED AT ROOT".
#:
#: β›” THE DEFECT IS THAT ROOT WAS REPRESENTED BY *ABSENCE*, AND ABSENCE CANNOT HOLD TWO FACTS.
#: "this arrived by grant and was never filed" and "the receiver deliberately dragged this OUT of
#: the Shared group" were the same stored state β€” nothing β€” so the client had to GUESS, and
#: `folders.ts::groupByFolder` guessed "Shared". That is why only folder→folder moves appeared to
#: work: **the root bucket was unreachable for a shared view by construction.**
#:
#: ⚠ A RESERVED FOLDER ID, NOT A NEW FIELD, deliberately. The placement map is `{itemId: folderId}`
#: and every reader on both sides already understands it; a parallel "filedAtRoot" set would be a
#: second source of truth for one question, and the two would disagree the first time one of them
#: was written without the other. This id names no folder BY DESIGN and is therefore exempt from
#: the folder-exists test below β€” it is the one value that means "no folder, on purpose".
#: ⚠ Spelled `ROOT_FOLDER_ID` on the client (`customer-grid/folders.ts`, C's file). Two spellings
#: of one constant is [[a-constant-two-features-share]]; `verify_folders`/`verify_api` assert they
#: agree rather than a comment asking nicely.
ROOT_PLACEMENT = "__root__"


def clean_item_folders(raw, folders, valid_ids):
    """{surface: {itemId: folderId}} β€” dropping any placement whose ITEM or FOLDER is gone.

    This is what makes a deleted folder's contents fall back to the root rather than vanish:
    nothing stores "this item is in no folder", so an unresolvable placement simply disappears
    and the item renders at the top level. Same for an item that was deleted elsewhere β€” its
    stale placement can never resurrect it, because the sidebars render ITEMS and consult this
    map, never the other way round.

    ⭐⭐ WAVE 32 β€” THE PARAGRAPH ABOVE STATES THE FEATURE AND THE BUG IN ONE SENTENCE, and it took
    owner item 20 to notice they were the same mechanism. *"Nothing stores 'this item is in no
    folder', so an unresolvable placement simply disappears"* is exactly right for a DELETED FOLDER
    (its contents should fall to the root) and exactly wrong for a SHARED VIEW (falling back means
    falling back INTO the Shared group, which is where it started). `ROOT_PLACEMENT` is the value
    that survives this function so the second case can be said out loud.
    """
    out = {}
    for surface in FOLDER_SURFACES:
        fids = {f["id"] for f in (folders or {}).get(surface, [])}
        ok = {}
        for item_id, fid in ((raw or {}).get(surface) or {}).items():
            if not isinstance(item_id, str) or not isinstance(fid, str):
                continue
            # β›” `fid == ROOT_PLACEMENT` FIRST, and it is NOT in `fids` β€” it names no folder, which
            # is the whole point. Without this clause the value is written by `item_move` and
            # scrubbed here on the way back out, so the mark would be stored and instantly lost:
            # the two halves are ONE change and shipping either alone is worse than shipping
            # neither ([[lost-write-looks-like-failed-read]]).
            if item_id in (valid_ids or {}).get(surface, ()) and (fid == ROOT_PLACEMENT
                                                                  or fid in fids):
                ok[item_id[:120]] = fid
        if ok:
            out[surface] = ok
    return out


def view_refs_of(nodes):
    """C4 β€” every view id a tree REFERS to, deduped, in order. Mirrors `types.ts::viewRefsOf`.

    ⚠ An INACTIVE leaf (no view chosen yet) is not a reference, on both engines: counting one
    would refuse a save the moment somebody opened the condition and had not picked anything.
    """
    out = []
    for node in nodes or []:
        if not isinstance(node, dict):
            continue
        if 'children' in node:
            for vid in view_refs_of(node.get('children')):
                if vid not in out:
                    out.append(vid)
            continue
        if node.get('colId') != VIEW_FIELD:
            continue
        vid = str(node.get('value') or '').strip()[:MAX_VIEW_ID]
        if vid and vid not in out:
            out.append(vid)
    return out


def view_filter_cycle(view_id, nodes, filters_of):
    """⭐⭐ W37-T26 / C4 β€” THE CYCLE REFUSAL's host half. Mirrors `types.ts::viewFilterCycle`.

    View X filtered on "is in View Y" where Y is filtered on X cannot be resolved by anything:
    X needs Y needs X. Returns the CYCLE PATH (ids, starting and ending at `view_id`) or None.

    β›” THE CLIENT REFUSES THE SAME SHAPE AND THAT IS NOT DUPLICATION. The browser's guard is what
    a PERSON sees and is the only one that can explain itself; this one is what makes the rule true
    for a caller that POSTs a view directly, which is every guard-in-the-browser's blind spot.
    ⚠ A view referring to ITSELF is a cycle of length one and is caught by the same walk β€” also
    the case a person reaches most easily, by duplicating a view.
    """
    def walk(current, path, seen):
        refs = view_refs_of(nodes if current == view_id else filters_of(current))
        for nxt in refs:
            if nxt == view_id:
                return path + [nxt]
            if nxt in seen:
                continue
            seen.add(nxt)
            found = walk(nxt, path + [nxt], seen)
            if found:
                return found
        return None

    return walk(view_id, [view_id], {view_id})


def clean_filter_cell_ref(raw):
    """Validate a saved external cell address without choosing its reader or changing its shape."""
    if (not isinstance(raw, dict) or set(raw) - {'workbook_id', 'tab', 'ref', 'locked'}
            or any(not isinstance(raw.get(key), str) or not raw[key].strip()
                   or raw[key] != raw[key].strip() or len(raw[key]) > 120
                   for key in ('workbook_id', 'tab', 'ref'))
            or not re.fullmatch(r'\$?[A-Za-z]{1,3}\$?[1-9][0-9]{0,6}', raw['ref'])
            or 'locked' in raw and not isinstance(raw['locked'], bool)):
        return None
    return copy.deepcopy(raw)


def clean_filter_tree(raw, valid_keys, depth=1, budget=None, cohort_ids=None,
                      visible_view_ids=None, report=None):
    """Recursively validate an UNTRUSTED filter tree (conditions + nested groups).

    Returns a clean tree of leaf conditions ({colId, op, value, value2}) and
    groups ({conj, children}). Module-agnostic on purpose: any module embedding
    the grid validates its own view state through this one function.

    Fail-closed PER NODE: anything unrecognised is DROPPED rather than raised β€”
    the same contract the rest of the view sanitiser follows, so one bad rule can
    never cost a user their whole saved view. Depth, per-level width and total
    node count are all capped: the tree is re-evaluated for every row on every
    render, so an unbounded structure would be a persistent client-side DoS.
    Empty groups are dropped (they carry no meaning once persisted).

    `report`, when supplied, accumulates missing-column and invalid-RHS drops across nested groups.
    Entries name `id`, `colId` and `reason`, plus `rhsColId` for an invalid right operand.
    The returned tree and callers that omit the accumulator keep their existing shape.

    `cohort_ids` is the set of cohorts the CALLER may see. A cohort leaf naming anything else is
    DROPPED here rather than left for the engine β€” a deleted cohort would otherwise leave a
    condition that can only match nothing, so `List is not [deleted]` would show an empty table
    forever with no way to tell why. `None` means this host has no cohorts, and then every
    cohort leaf is dropped: fail-closed, like every other unknown key.

    ⭐⭐ W37-T26 (C4) β€” `visible_view_ids` is the same parameter one leaf over: the views this
    caller may name in a `__view__` membership leaf. A leaf naming anything else is DROPPED here
    for the identical reason, and `None` (this host has no views to offer) drops every one.
    ⚠ DEFAULTS TO `None` SO EVERY EXISTING CALLER IS BYTE-IDENTICAL. Three callers pass nothing
    (`routes_admin`, `routes_query` twice) and each of them is a surface with no saved-view
    vocabulary of its own; under the fail-closed rule they drop the leaf, which is correct rather
    than merely safe.
    """
    if budget is None:
        budget = [MAX_FILTER_NODES]
    out = []
    for node in list(raw or [])[:MAX_FILTER_SIBLINGS]:
        if budget[0] <= 0:
            break
        if not isinstance(node, dict):
            continue
        if isinstance(node.get('children'), list):            # a condition GROUP
            if depth >= MAX_FILTER_DEPTH:
                continue                                       # too deep -> drop
            budget[0] -= 1
            children = clean_filter_tree(node['children'], valid_keys,
                                        depth + 1, budget, cohort_ids, visible_view_ids,
                                        report=report)
            if children:
                out.append({'conj': 'or' if node.get('conj') == 'or' else 'and',
                            'children': children})
            continue
        if node.get('colId') == COHORT_FIELD:                 # a cohort-membership leaf
            op = COHORT_OP_ALIASES.get(node.get('op'), node.get('op'))
            named = parse_cohort_ids(node.get('value'))
            # ALL of them, or the leaf goes. A set that quietly lost a member asks a DIFFERENT
            # question, and for `noneOf` a strictly wider one: `is none of [A, B]` degrading to
            # `is none of [A]` would show every row in B under a count nobody would doubt. This
            # is the same all-or-nothing the single-cohort leaf already had, extended to a set.
            if op in COHORT_OPS and named and all(c in (cohort_ids or ()) for c in named):
                budget[0] -= 1
                leaf = {'colId': COHORT_FIELD, 'op': op,
                        'value': ','.join(named), 'value2': ''}
                if node.get('locked') is True:
                    leaf['locked'] = True
                out.append(leaf)
            continue
        if node.get('colId') == VIEW_FIELD:                   # C4: a view-membership leaf
            # β›” THE SAME ALL-OR-NOTHING THE COHORT ARM ABOVE APPLIES, AND FOR THE SAME REASON.
            # A leaf naming a view this caller cannot see is DROPPED rather than kept, because a
            # kept one can only ever match nothing: `View is not [a view you cannot see]` would
            # show an empty table forever with no way to tell why. Dropping it puts the view back
            # in its honest unfiltered state, which is what `clean_filter_tree`'s own docstring
            # already promises for cohorts.
            # ⚠ `visible_views` is what the caller passes; `None` means this host does not know,
            # and then EVERY view leaf is dropped β€” fail-closed, like every other unknown key.
            v_op = node.get('op')
            v_id = str(node.get('value') or '').strip()[:MAX_VIEW_ID]
            if v_op in VIEW_OPS and v_id and v_id in (visible_view_ids or ()):
                budget[0] -= 1
                leaf = {'colId': VIEW_FIELD, 'op': v_op, 'value': v_id, 'value2': ''}
                if node.get('locked') is True:
                    leaf['locked'] = True
                out.append(leaf)
            continue
        # Wave 45 C1: ``zone`` was the pre-canonical projection key.  A saved View is migrated
        # at its ordinary validated save door, rather than kept as a second readable field or
        # dropped as an unknown condition.  The migration is admissible only when this database
        # actually exposes ``__zone__``; on every other database an unknown ``zone`` leaf keeps
        # the longstanding fail-closed behaviour.
        column = ('__zone__' if node.get('colId') == 'zone' and '__zone__' in valid_keys
                  else node.get('colId'))
        if column not in valid_keys:
            if report is not None:
                report.append({'id': str(node.get('id', ''))[:64],
                               'colId': column, 'reason': 'missing_column'})
            continue
        if node.get('op') in FILTER_OPS:
            budget[0] -= 1
            # `or ''` would be wrong here: it maps every FALSY value to '', and '' is the
            # signal for "inactive". A numeric 0 (or 0.0, or False) is a real value the client
            # treats as active β€” `0 === ""` is false in TS β€” so `revenue = 0` would silently
            # stop filtering and show every row instead of the zero-revenue ones.
            val, val2 = node.get('value'), node.get('value2')
            leaf = {'colId': column, 'op': node['op'],
                    'value': ('' if val is None else str(val))[:500],
                    'value2': ('' if val2 is None else str(val2))[:500]}
            # CG-8. A MEASURE condition ("Sales, in the last 90 days, > 5,000") carries two
            # extra members: a stable client-generated `id`, which is how the server's answer
            # finds its way back to the condition that asked (positional matching silently
            # re-associates every answer the moment a user deletes a condition), and the
            # `window`. Emitted ONLY when the input has them β€” a column condition's cleaned
            # shape is unchanged, so every persisted view deserialises byte-identically and
            # `clean_filter_tree` stays idempotent (verify_filter_engine.py asserts that by
            # exact structural comparison).
            # ⭐ W51-T07 β€” the MULTI-VALUE operand, emitted as a REAL LIST and never through the
            # `str(val)[:500]` coercion three lines up, which would store the literal text
            # "['A', 'B']" and leave the condition unanswerable in all three engines.
            #
            # Emitted for these ops ALWAYS and for every other op NEVER, which is what keeps
            # `clean_filter_tree` idempotent (verify_filter_engine.py compares the cleaned shape
            # structurally): an ordinary column leaf is byte-identical to what it always was, and
            # a multi-value leaf whose list is EMPTY keeps an empty list rather than losing the
            # member β€” so the leaf survives as INCOMPLETE (is_rule_active answers False, the
            # builder renders it unfinished) instead of being silently dropped.
            if node['op'] in MULTI_VALUE_OPS:
                leaf['values'] = parse_filter_values(node.get('values'))
            rid = node.get('id')
            if rid not in (None, ''):
                leaf['id'] = str(rid)[:64]
            window = _clean_window(node.get('window'))
            if window is not None:
                leaf['window'] = window
            # Owner items 3 + 4, carried under the SAME rule as CG-8's `id`/`window`: emitted
            # only when the input has them, so a plain column condition's cleaned shape is
            # byte-identical to what it always was and `clean_filter_tree` stays idempotent
            # (verify_filter_engine.py asserts that by exact structural comparison). Drop the
            # carry-through and the next autosave silently strips a date condition back to a
            # bare comparison against an empty value β€” i.e. back to INACTIVE.
            date_window = _clean_window(node.get('dateWindow'))
            if date_window is not None:
                leaf['dateWindow'] = date_window
            mode = node.get('dateMode')
            # SHAPE only. An unrecognised mode survives here and is refused by
            # `windows.resolve_anchor`, which returns None and makes the condition match
            # NOTHING β€” the same split as `_clean_window`, and the reason this module can stay
            # free of the date vocabulary it would otherwise have to keep in step.
            if isinstance(mode, str) and 0 < len(mode) <= 40:
                leaf['dateMode'] = mode
            # W43C C1/R1 Ò€” rank is a set-wide question.  A saved leaf says whether it ranks
            # the residual domain globally or once per the view's group.  The concise ``group``
            # form deliberately relies on the view's ``groupBy`` at evaluation time; the object
            # form pins a particular field and therefore survives a later view regroup.  Unknown
            # shapes are dropped, never coerced to global, because that would change a narrowing
            # question while preserving its friendly-looking label.
            if node.get('op') in {'topN', 'bottomN', 'inTopPct', 'inBottomPct',
                                  'aboveAvg', 'belowAvg', 'inQuartile', 'inDecile'}:
                rank_scope = _clean_rank_scope(node.get('rankScope'), valid_keys)
                if rank_scope is not None:
                    leaf['rankScope'] = rank_scope
            rhs = _clean_rhs(node.get('rhs'), valid_keys)
            if isinstance(node.get('rhs'), dict) and rhs is None:
                # An invalid comparison must not become an inactive empty literal.
                if report is not None:
                    report.append({'id': leaf.get('id', ''), 'colId': column,
                                   'rhsColId': node['rhs'].get('colId'),
                                   'reason': 'invalid_rhs'})
                continue
            if rhs is not None:
                leaf['rhs'] = rhs
            # The save host authorizes these addresses before this structural cleaner runs.
            refs = {key: clean_filter_cell_ref(node[key])
                    for key in ('valueRef', 'value2Ref') if key in node}
            if any(ref is None for ref in refs.values()):
                continue
            leaf.update(refs)
            # C3: a record lock is explicit on the leaf, not a view-wide presentation flag.
            # Once stored, grid_events preserves the containing filter config unless it is copied
            # to a new View; a later caller cannot turn this `True` into an editable-looking false.
            if node.get('locked') is True:
                leaf['locked'] = True
            out.append(leaf)
    return out


def migrate_zone_projection_config(raw):
    """Copy one saved View config while renaming every legacy ``zone`` field reference.

    Filter leaves are validated later by ``clean_filter_tree``.  The other members are field-key
    projections and can be migrated structurally here, before their normal allow-list checks.
    This retains old View intent without re-publishing ``zone`` as a writable or readable field.
    """
    config = copy.deepcopy(raw if isinstance(raw, dict) else {})

    def key(value):
        return '__zone__' if value == 'zone' else value

    def filters(nodes):
        for node in nodes or ():
            if not isinstance(node, dict):
                continue
            if isinstance(node.get('children'), list):
                filters(node['children'])
            else:
                if node.get('colId') == 'zone':
                    node['colId'] = '__zone__'
                rank_scope = node.get('rankScope')
                if isinstance(rank_scope, dict):
                    for member in ('field', 'groupBy'):
                        if member in rank_scope:
                            rank_scope[member] = key(rank_scope.get(member))

    raw_filters = config.get('filters')
    filters((raw_filters.get('nodes') or raw_filters.get('children') or ())
            if isinstance(raw_filters, dict) else raw_filters)
    for member in ('sorts',):
        for item in config.get(member) or ():
            if isinstance(item, dict) and item.get('colId') == 'zone':
                item['colId'] = '__zone__'
    for member in ('order', 'visible'):
        if isinstance(config.get(member), list):
            config[member] = list(dict.fromkeys(key(value) for value in config[member]))
    if isinstance(config.get('widths'), dict) and 'zone' in config['widths']:
        config['widths']['__zone__'] = config['widths'].pop('zone')
    for member in ('groupBy', 'colorBy', 'stackField'):
        if config.get(member) == 'zone':
            config[member] = '__zone__'
    return config


def preserve_locked_view_records(prior_config, filters, sorts):
    """Return authoritative filter/sort records when an in-place lock was touched.

    A lock protects its semantic position as well as its leaf text: moving a locked condition
    between AND/OR groups changes the question even when the leaf itself is byte-identical.  We
    therefore retain the full corresponding list on any attempted change.  A new View has no
    prior config, so copying is the explicit alteration path.
    """
    prior = prior_config if isinstance(prior_config, dict) else {}
    old_filters = prior.get('filters') if isinstance(prior.get('filters'), list) else []
    old_sorts = prior.get('sorts') if isinstance(prior.get('sorts'), list) else []

    def _has_locked_filter(nodes):
        for node in nodes or ():
            if not isinstance(node, dict):
                continue
            if node.get('locked') is True:
                return True
            if _has_locked_filter(node.get('children') if isinstance(node.get('children'), list) else []):
                return True
        return False

    def _same(left, right):
        return json.dumps(left, sort_keys=True, separators=(',', ':')) == json.dumps(
            right, sort_keys=True, separators=(',', ':'))

    if _has_locked_filter(old_filters) and not _same(old_filters, filters):
        filters = json.loads(json.dumps(old_filters))
    if any(isinstance(rule, dict) and rule.get('locked') is True for rule in old_sorts) \
            and not _same(old_sorts, sorts):
        sorts = json.loads(json.dumps(old_sorts))
    return filters, sorts


def _clean_rank_scope(raw, valid_keys):
    """The persisted rank scope, or ``None`` when absent/malformed.

    ``None`` retains legacy global semantics.  ``'group'`` is intentionally valid without a
    column here: it means *the view's selected group*, and the server resolver refuses it when
    a caller later supplies no real group field.  An explicit field is accepted only when this
    table exposes it, so a stale saved scope cannot silently collect every row in one bucket.
    """
    if raw in (None, ''):
        return None
    if raw == 'global':
        return 'global'
    if raw in ('group', 'perGroup'):
        return 'group'
    if not isinstance(raw, dict):
        return None
    mode = raw.get('mode', raw.get('scope'))
    field = str(raw.get('field', raw.get('groupBy')) or '').strip()[:80]
    if mode == 'global' and not field:
        return 'global'
    if mode == 'group' and field and field in valid_keys:
        return {'mode': 'group', 'field': field}
    return None


def _is_default_visible(field):
    """Does this column open SHOWN in a view that has never recorded its own `visible`?

    ⭐⭐ OWNER, 2026-08-23: *"when any new View is created only shareable pre-set data should
    show. Shared to me or Shared to everyone should be auto hidden."*

    β›” THE CLIENT TWIN IS `useGridColumns.isDefaultVisible` AND IT MUST SAY THE SAME THING. The
    note inside `_default_view_config` below is the record of what happens when it does not:
    `CustomerGrid` compares the stored system view against its own `defaultViewConfig` by JSON
    equality, so a disagreement here is a view that looks permanently dirty and autosaves for
    ever. The reasoning for the predicate itself lives in the client file, once.

    ⚠ `custom or shared` is the same membership test `FieldsHidePanel` uses to draw BOTH of its
    shared headings, so hiding on it covers both without a second list of section names.
    """
    if field.get("default") is False:
        return False
    if field.get("custom") is True or field.get("shared") is True:
        return False
    return True


def _default_view_config(fields):
    # ⭐⭐ W30-T41's SERVER HALF (F's ask F-1, answered by D β€” this file is D's fence).
    #
    # β›” THE SECOND ARM USED TO BE `or field["source"] == "overlay"`, AND IT SWALLOWED THE FIRST
    # ONE FOR EVERY CONNECTED COLUMN. `user_tables._clean_field` stamps `source: "overlay"` on
    # every `ut_` field, so on an Odoo grid the arm was true for ALL of them and `default: False`
    # meant nothing: `odoo_id`, `state`, `customer_link` and `partner_id` opened SHOWN however
    # they were declared. The exception had become the rule ([[fallback-that-became-the-rule]]),
    # and it is the same predicate `useGridColumns.isDefaultVisible` carried on the client.
    #
    # ⚠ AND THE TWO HALVES MUST MOVE TOGETHER, which is why this is not cosmetic. `CustomerGrid`
    # compares the stored view against its own `defaultViewConfig` by JSON equality; with the
    # client fixed (T41) and this left alone, the system view would differ from the client's
    # default on every render β€” a view that looks permanently dirty and autosaves forever, which
    # is the failure `verify_filter_engine`'s key-ORDER check exists to prevent, one level down.
    #
    # ⚠ A USER-CREATED COLUMN IS UNAFFECTED, and that is why the fix is a DELETION rather than a
    # carve-out for the four Odoo keys: it carries no `default` key at all, so `is not False`
    # keeps it visible. On the main Customer grid exactly one field moves β€” `notes`, which asks
    # to be hidden in its own declaration and was being shown against it.
    # ⭐⭐ OWNER, 2026-08-23 β€” ONLY PRE-SET DATA OPENS SHOWN. The client twin is
    # `useGridColumns.isDefaultVisible` and it carries this comment's argument in full; the two
    # MUST move together, which is the whole subject of the note above.
    shown = [field["key"] for field in fields if _is_default_visible(field)]
    hidden = [field["key"] for field in fields if field["key"] not in shown]
    archive_filter = [{"colId": "archived", "op": "neq", "value": "true"}] if any(
        field.get("key") == "archived" and field.get("type") == "checkbox"
        and field.get("source") == "odoo" for field in fields) else []
    return {
        # `filters` is the ROOT of the filter tree: leaf conditions and/or nested
        # condition groups ({conj, children}); `filterConj` joins the root level.
        "filters": archive_filter, "filterConj": "and",
        "sorts": [], "groupBy": None, "colorBy": None,
        "rowHeightMode": "short", "order": shown + hidden, "visible": shown,
        "widths": {}, "memberPids": [],
    }


#: Wave 17 R1 / C-LOCKV β€” the `kind` a PROJECTED locked view wears. A cohort is not a separate
#: kind of object any more: it is a saved view whose rows are a hand-curated set.
LOCKED_VIEW_KIND = 'locked'


def locked_view_projection(entry, base_config):
    """One cohort -> the saved-view row that IS it (wave 17 R1, contract C-LOCKV).

    β›” THE LOCK IS THE VIEW'S IDENTITY, NOT ITS CONFIGURATION. `config.cohortLock` names the
    view's OWN id, which is what makes the shipped engine law (`useVisibleRows`: intersect the
    named set FIRST, unconditionally, and match NOTHING when the membership is unresolvable) do
    all the work with no second mechanism. Membership itself is NEVER copied in here β€” it stays
    in `customer_cohorts` and travels as `workspace.lists`, because a per-reader-scoped
    collection inside a client-writable `config` is deleted by the next autosave (see the
    contract's reason 2).

    ⚠ `locked: True` is the LEGACY "undeletable/mode-frozen" flag and is deliberately NOT set:
    these views are ordinary in every respect the owner asked for β€” reorder, folder, sort,
    filter, change display mode. The lock mark in the rail is driven by `kind`.
    """
    return {
        'id': entry['id'],
        'name': entry.get('name') or entry['id'],
        'kind': LOCKED_VIEW_KIND,
        'config': {**base_config, 'cohortLock': entry['id']},
    }


#: ⭐ WAVE-27 item 27 (owner ruling R8) β€” the IG "Overview" view's CURATED COLUMNS, in the
#: owner's own order: handle, followers, engagement, location, last enriched.
#:
#: Written as candidates rather than as a requirement. The template registry REFUSES a template
#: whose columns the target lacks (`view_templates.missing_columns`) because applying one writes
#: the user's own views and a filter on a missing column silently WIDENS. This view is INJECTED,
#: not applied, and it filters nothing β€” so the proportionate rule is the opposite one: take the
#: columns the table has, in this order, and skip the rest. An IG database that predates a
#: column simply shows the other four.
#:
#: ⚠ `location_guess` is SESSION B's item-16 column and may not exist yet. That is exactly why
#: this list is intersected rather than asserted: a hard requirement here would make the whole
#: view vanish (or the assembly refuse) on every tenant until B lands, and then appear by
#: surprise. `profile_url` closes the list as the click-through, which is what makes the view
#: usable rather than merely informative.
IG_OVERVIEW_COLUMNS = ('handle', 'full_name', 'followers', 'avg_engagement',
                       'location_guess', 'enriched_at', 'profile_url')

#: The id is PINNED, the `view_templates` discipline: re-assembling must update the same view
#: rather than mint "Overview 2". It also lets a user's own edits overlay it through the saved
#: -config loop below, exactly as a cohort projection does.
IG_OVERVIEW_ID = 'tpl_overview'

#: How this function recognises an IG preset database WITHOUT importing the engine: two of the
#: profile preset columns is a stronger signal than any single one (a hand-made table could
#: plausibly own a column called `followers`; owning `followers` AND `avg_engagement` AND
#: `handle` is the preset set). `core/` must stay importable without the API layer, so this
#: mirrors `user_tables.PROFILE_PRESET_KEYS` the way that module mirrors the engine's.
_IG_SIGNATURE = ('handle', 'followers', 'avg_engagement')


def _ig_overview_view(fields, base):
    """R8's curated Overview, or None when this table is not an Instagram one."""
    keys = {f['key'] for f in fields}
    if not all(k in keys for k in _IG_SIGNATURE):
        return None
    visible = [k for k in IG_OVERVIEW_COLUMNS if k in keys]
    return {
        'id': IG_OVERVIEW_ID,
        'name': 'Overview',
        'kind': 'system',
        # NOT `locked`. The system view is locked because it is the identity of the table ("show
        # me everything"); this one is a STARTING LAYOUT, and R8 calls it curated rather than
        # fixed. A user who wants a sixth column should get one.
        'note': 'The five things worth seeing first on a creator. Sorted by reach.',
        'config': {
            **dict(base),
            'visible': visible,
            'order': visible + [k for k in (f['key'] for f in fields) if k not in visible],
            'sorts': ([{'colId': 'followers', 'dir': 'desc'}]
                      if 'followers' in keys else []),
        },
    }


def views_from_defs(defs, saved_views, fields, system_name="All customers", locked_lists=None,
                    view_order=None):
    """Convert legacy list formulas into the shared serializable SavedView contract.

    `system_name` (wave 16 C-TOPIC) labels the system view per TOPIC ("All products" on the
    product surface). The ID stays "all-customers" on every topic β€” the client pins it
    (UNDELETABLE_VIEW_IDS, the landing default), and an id that varies by surface would fork
    that contract for a label's sake.

    `locked_lists` (wave 17 R1) are the caller's cohorts, each PROJECTED as a saved view whose
    id IS the cohort id β€” so every stored reference to that id (a `cohortLock` on another view,
    an `is part of` condition, a folder placement) keeps pointing at the same thing and no
    rewrite map is needed. Saved config OVERLAYS the projection through the same mechanism the
    `list:` views have always used, which is what gives a locked view its own sort, filter,
    columns and display mode with no new storage."""
    base = _default_view_config(fields)
    views = [{
        "id": "all-customers", "name": system_name, "kind": "system",
        "locked": True, "config": dict(base),
    }]
    # ⭐ WAVE-27 item 27 (R8) β€” the IG Overview, ABOVE All records.
    #
    # ⚠ INJECTED, not seeded into the store, and that is what makes "existing IG databases gain
    # it too" true with no migration and no write on a read path. It is the same mechanism the
    # system view above has always used; the pinned id means a user's own edits overlay it
    # through the saved-config loop below rather than forking a second view.
    _overview = _ig_overview_view(fields, base)
    if _overview:
        views.insert(0, _overview)
    op_map = {">=": "gte", ">": "gt", "<=": "lte", "<": "lt", "=": "eq",
              "contains": "contains"}
    for name, definition in (defs or {}).items():
        filters = [dict(rule) for rule in base["filters"]]
        for rule in definition.get("rules") or []:
            if rule.get("field") not in {field["key"] for field in fields}:
                continue
            filters.append({
                "colId": rule["field"],
                "op": op_map.get(rule.get("op"), "eq"),
                "value": str(rule.get("value") if rule.get("value") is not None else ""),
            })
        sort = str(definition.get("sort") or "")
        sorts = ([{"colId": sort.lstrip("-"),
                   "dir": "desc" if sort.startswith("-") else "asc"}]
                 if sort.lstrip("-") in {field["key"] for field in fields} else [])
        views.append({
            "id": "list:" + str(name),
            "name": str(name),
            "kind": "list",
            "note": str(definition.get("note") or ""),
            "config": {
                **base, "filters": filters, "sorts": sorts,
                "memberPids": [int(pid) for pid in definition.get("members") or []
                               if isinstance(pid, int) or str(pid).isdigit()],
            },
        })
    # Wave 17 R1 β€” the cohorts, as ordinary views. Appended BEFORE the saved-config overlay
    # below so a user's own edits to a locked view (its sort, its columns, its display mode)
    # land on the projection instead of creating a second row with the same id.
    for _entry in (locked_lists or []):
        if isinstance(_entry, dict) and _entry.get('id'):
            views.append(locked_view_projection(_entry, base))
    index = {view["id"]: i for i, view in enumerate(views)}
    for view_id, saved in (saved_views or {}).items():
        if not isinstance(saved, dict) or not isinstance(saved.get("config"), dict):
            continue
        clean = dict(saved)
        clean["id"] = str(view_id)
        if view_id in index:
            views[index[view_id]] = clean
        else:
            views.append(clean)
    # β›” WAVE 17 R1 β€” RE-STAMP THE LOCK AFTER THE OVERLAY. The loop above REPLACES a projected
    # view with its saved record, and a saved record that omits `cohortLock` would hand back a
    # view that shows the WHOLE BOOK under a locked view's name. That is not hypothetical: the
    # client rebuilds `config` on every autosave (a column resize is enough), and the lock is
    # identity here, not something the browser is the source of truth for. Read-side rather than
    # write-side-only on purpose β€” this also repairs any record already written by another path.
    _locked_ids = {e['id']: e for e in (locked_lists or [])
                   if isinstance(e, dict) and e.get('id')}
    if _locked_ids:
        for _v in views:
            _entry = _locked_ids.get(_v.get('id'))
            if not _entry:
                continue
            _v['kind'] = LOCKED_VIEW_KIND
            _v['config'] = {**(_v.get('config') or {}), 'cohortLock': _v['id']}
            # One thing, one name: the cohort store owns it (the rename event routes there), so
            # a stale `name` on the saved record can never fork into a second title.
            _v['name'] = _entry.get('name') or _v['id']
    # ── ⭐ WAVE-27 item 5, contract C7: the PER-USER VIEW ORDER ───────────────────────────────
    #
    # `view_order` is a list of view ids this user dragged into place. Applied LAST, over the
    # finished list, so it reorders whatever the assembly produced without having to know how any
    # of it got there (system, list:, cohort projection, saved, injected Overview).
    #
    # β›” THE SYSTEM VIEW STAYS AT INDEX 0 (C7), and it is re-pinned here rather than trusted to
    # sort correctly: `all-customers` is the client's landing default and one of its
    # UNDELETABLE_VIEW_IDS, so a stored order that happened to omit it β€” or list it third β€”
    # would move the rail's home row. ⚠ R8's Overview is the ONE thing allowed above it, because
    # the owner put it there; it is re-pinned with the system view so a drag cannot bury it
    # either. Both are facts about the table rather than the user's arrangement of it.
    #
    # ⚠ UNKNOWN IDS APPEND IN SERVER ORDER (C7). A view created since this order was stored, or
    # one shared to this user yesterday, must APPEAR β€” dropping it would make sharing look
    # broken, and the failure would be invisible to whoever shared it. Ids in the stored order
    # that no longer resolve are simply skipped.
    if view_order:
        _rank = {vid: i for i, vid in enumerate(view_order) if isinstance(vid, str)}
        _pinned = [v for v in views if v.get('id') in (IG_OVERVIEW_ID, 'all-customers')]
        _rest = [v for v in views if v.get('id') not in (IG_OVERVIEW_ID, 'all-customers')]
        # A stable sort over a rank that DEFAULTS TO THE END keeps unranked views in their
        # server order behind the ranked ones, rather than interleaving them by accident.
        _rest.sort(key=lambda v: _rank.get(v.get('id'), len(_rank) + 1))
        views = _pinned + _rest
    return views


def narrow_view_keys(views, hidden):
    """D-464: a WIRE COPY of `views` whose column-bearing config names no key in `hidden`.

    `views_from_defs` merges saved configs verbatim and runs before the field wall exists, so a
    hidden field's KEY rode `/workspace` in `order`/`visible`/`widths`/`sorts`/`groupBy`/`colorBy`
    (and `stackField`, `summary`, `display.*Field`) to the very reader the wall targets. Each
    assembly calls this beside its overlay narrowing,
    on `workspace["views"]` only: `g["views"]` stays whole for server-side work (exports, measure
    sets), and a walled reader's own autosave is already cleaned against their walled keys.
    ⚠ FILTER LEAVES (and `secondaryView`) ARE LEFT ALONE: dropping a leaf would change which rows
    a view shows, so a hidden key named only in a filter still rides this wire."""
    hidden = set(hidden or ())
    if not hidden:
        return views
    out = []
    for view in views or []:
        cfg = view.get("config") if isinstance(view, dict) else None
        if not isinstance(cfg, dict):
            out.append(view)
            continue
        cfg = dict(cfg)
        for name in ("order", "visible"):
            if isinstance(cfg.get(name), list):
                cfg[name] = [key for key in cfg[name] if key not in hidden]
        if isinstance(cfg.get("widths"), dict):
            cfg["widths"] = {key: w for key, w in cfg["widths"].items() if key not in hidden}
        if isinstance(cfg.get("sorts"), list):
            cfg["sorts"] = [s for s in cfg["sorts"]
                            if not (isinstance(s, dict) and s.get("colId") in hidden)]
        for name in ("groupBy", "colorBy", "stackField"):
            if isinstance(cfg.get(name), str) and cfg[name] in hidden:
                cfg[name] = None
        if isinstance(cfg.get("summary"), dict):
            cfg["summary"] = {key: s for key, s in cfg["summary"].items() if key not in hidden}
        if isinstance(cfg.get("display"), dict):
            # `DisplaySpec`'s `dateField`/`stackField`/`titleField`/`colorField`/... members.
            cfg["display"] = {name: value for name, value in cfg["display"].items()
                              if not (name.endswith("Field") and isinstance(value, str)
                                      and value in hidden)}
        out.append(dict(view, config=cfg))
    return out


def workspace_wire(ws, uname, pool_pids, defs=None, scope_key='customer', storage_key=None,
                   fields_base=None, with_cohorts=True, st=None):
    """The client's `GridWorkspace` WIRE SHAPE from the stored table workspace β€” the ONE
    projection, shared by both servers (app.py's `_table_grid` and the API's `/workspace`).

    β›” WHY THIS EXISTS (2026-07-30). The API route used to return the STORE shape with no
    `storageKey` β€” and the client validator (`fetchWorkspace`) requires one, so the standalone
    shell silently discarded the whole workspace: saved views never rendered and `cohortMode`
    never arrived (the Cohort route drew the Customer surface). Duplicating the host's inline
    projection into the route would have re-created the same drift one wave later; extracting it
    means the wire can only be one thing.

    Returns `(workspace, fields, views, cohort_lists)` β€” the extra three because the host
    interleaves further work (docs, derived cells, measure sets) that consumes them.

    HOST-ONLY extras stay with the host: `docs`/`docPayload`, `pool`, `hideViews`,
    `cohortMode`/`scopeChoice` (the API stamps its own from `?scope=`).

    Wave 16 C-TOPIC: `fields_base` selects the canonical contract (absent = customer,
    byte-identical).

    ⭐ WAVE 19 / R9 β€” `with_cohorts` NO LONGER MEANS "customer only". Wave 16 set it False on the
    product surface because cohorts were a single customer-keyed bucket, so resolving them against
    product pids would have intersected two unrelated id spaces and printed a plausible,
    meaningless member count. `modules.cohort` is scope-parameterized now: the lists come from
    THIS topic's bucket (`cohort_mod.scoped(scope_key)`), so their ids are this topic's ids and
    the intersection with `pool_pids` is the ordinary one. The flag survives as an honest OFF
    switch for a surface that wants no membership channel at all β€” it is not a topic wall.
    """
    import modules.cohort as cohort_mod

    cohort_lists = []
    if with_cohorts:
        for cid, c in sorted(cohort_mod.scoped(scope_key, st=st).visible(uname, pool_pids).items(),
                             key=lambda kv: (kv[1].get('name') or '').lower()):
            members = [p for p in (c.get('members') or []) if p in pool_pids]
            entry = {'id': cid, 'name': c.get('name') or cid, 'pids': members}
            # Rule 8b: a member can drop out of the 24-month pool without the cohort being
            # wrong, and a silently smaller cohort is exactly what the unverifiable-count rule
            # forbids.
            missing = len(c.get('members') or []) - len(members)
            if missing:
                entry['missing'] = missing
            cohort_lists.append(entry)

    fields = fields_from_workspace(ws, cohorts=bool(cohort_lists), scope_key=scope_key,
                                   fields_base=fields_base)
    views = views_from_defs(defs or {}, ws.get('views'), fields,
                            # Wave 21 (item 3, R6): the system view's name is TOPIC-DERIVED. A
                            # user database's default view used to read "All customers" β€” a
                            # compiled customer literal minted on every topic, one half of the
                            # owner's "my new database looks like RI's Customer table". The ID
                            # stays 'all-customers' everywhere (pinned client+server β€” the
                            # client's UNDELETABLE set and the view pin both name it).
                            system_name=("All products" if scope_key == 'product'
                                         else "All records"
                                         if str(scope_key or '').startswith('ut_')
                                         else "All customers"),
                            locked_lists=cohort_lists,
                            # ⭐ WAVE-27 item 5 (C7) β€” this user's own rail arrangement, from
                            # their own stratum. Read here rather than sorted by the client so
                            # the ORDER a request answers with is the order that was stored:
                            # sorting client-side would make the rail settle after a paint on
                            # every load, and shared views would land in server order first.
                            view_order=ws.get('viewOrder'))
    workspace = {'storageKey': storage_key, 'views': views, 'lists': cohort_lists}
    # Owner item 3 (2026-07-31): where this user left off. The client's own localStorage copy
    # wins when present; this is the server's answer for a FRESH browser, which used to fall
    # all the way to the system default view (and whatever display mode was stored on it).
    if ws.get('activeViewId'):
        workspace['activeViewId'] = str(ws['activeViewId'])

    # FOLDERS (owner item 11, contract C4), re-validated at SERVE time: a view or cohort can be
    # deleted by a path that knows nothing about folders, and the placement map must not outlive
    # the thing it points at.
    _folders = clean_folders(ws.get('folders'))
    _view_ids = {v['id'] for v in (views or []) if isinstance(v, dict) and v.get('id')}
    # ── WAVE 17 R1 (C-LOCKV amendment 2026-08-03): the two folder surfaces become ONE, AT
    # SERVE TIME rather than by a store migration. A locked view is an ordinary view now, so
    # its folder has to be an ordinary view folder β€” but rewriting the stored map would be a
    # one-shot write that has to be got right once, while this is a projection that is right
    # every time it runs. New drags write to `views` anyway (the client only knows that
    # surface), so `cohorts` drains on its own and never needs a second pass.
    # ⚠ A cohorts-surface folder whose id ALREADY names a views folder is DROPPED, not merged:
    # re-parenting somebody's list into a folder that merely shares an id is a worse outcome
    # than the list appearing at the root, where it is visible and one drag from home.
    _cf = list(_folders.get('cohorts') or [])
    if _cf:
        _vf = list(_folders.get('views') or [])
        _taken = {f['id'] for f in _vf}
        _order = len(_vf)
        for _f in _cf:
            if _f['id'] in _taken:
                continue
            _vf.append({**_f, 'order': _order})
            _order += 1
        _folders['views'] = _vf
    _raw_item_folders = dict(ws.get('itemFolders') or {})
    if _raw_item_folders.get('cohorts'):
        # Cohort placements now describe VIEWS (same ids β€” that is the point of preserving them).
        # A placement already stored on the views surface WINS: it is the more recent act.
        _raw_item_folders['views'] = {**dict(_raw_item_folders.get('cohorts') or {}),
                                      **dict(_raw_item_folders.get('views') or {})}
    _placed = clean_item_folders(
        _raw_item_folders, _folders,
        {'views': _view_ids, 'cohorts': {c['id'] for c in cohort_lists}})
    if _folders.get('views'):
        workspace['folders'] = _folders['views']
    # β›” `cohortFolders` IS NO LONGER EMITTED. The rail has no cohorts section to fold, and a
    # wire that still described one would invite a second rendering of rows that are now views.
    _vplaced = _placed.get('views') or {}
    for _v in (views or []):
        if isinstance(_v, dict) and _v.get('id') in _vplaced:
            _v['folderId'] = _vplaced[_v['id']]
    _cplaced = _placed.get('cohorts') or {}
    for _c in cohort_lists:
        if _c['id'] in _cplaced:
            _c['folderId'] = _cplaced[_c['id']]

    # RECORD LAYOUT (wave 2026-08-02, C-LAYOUT): the per-user record-detail field order,
    # re-validated at SERVE time exactly like folders β€” a field can be deleted by a path
    # that knows nothing about this stratum, and a stale key must not outlive its field.
    _rl = ws.get('recordLayout')
    if isinstance(_rl, dict) and isinstance(_rl.get('order'), list):
        _fkeys = {f['key'] for f in fields if isinstance(f, dict) and f.get('key')}
        _order, _seen = [], set()
        for _k in _rl['order'][:200]:
            _k = str(_k or '')
            if _k and _k in _fkeys and _k not in _seen:
                _seen.add(_k)
                _order.append(_k)
        if _order:
            workspace['recordLayout'] = {'order': _order}

    return workspace, fields, views, cohort_lists


def embed_html_path():
    """The first existing candidate path for the inlined single-file build, or None."""
    for p in _EMBED_CANDIDATES:
        if p.is_file():
            return p
    return None


def scope_counts(shown, matched, total):
    """The honest 'N of M' a SERVER-WINDOWED table must carry (CG-2).

    `matched` and `total` MUST come from their own queries over the whole scope. Never pass
    `len(rows)` as `matched` β€” that is the silent [:N] this exists to prevent: the page would
    report the window size as though it were the result size.

    Refuses the shapes that could only be a mistake, because a wrong count here is invisible on
    screen (it looks like a smaller dataset, not like an error).
    """
    shown, matched, total = int(shown), int(matched), int(total)
    if matched > total:
        raise ValueError(f"matched ({matched}) exceeds total ({total}); a filter cannot match "
                         f"more rows than the scope holds")
    if shown > matched:
        raise ValueError(f"shown ({shown}) exceeds matched ({matched}); the window cannot hold "
                         f"more rows than the filter matched")
    return {"shown": shown, "matched": matched, "total": total, "windowed": True}



# β›” EXIT-6 (2026-08-04): `build_html`, `component_dir`, `render` and `_DECLARED_COMPONENTS` WERE
# HERE, and they are gone with Streamlit. They were the EMBED HOST β€” the path that declared the
# prebuilt bundle as a `streamlit.components.v1` custom component (or injected the single-file
# HTML build as a fallback) so the React grid could be drawn inside a Streamlit page.
#
# THIS MODULE ITSELF SURVIVES, and that distinction is the whole point: `aios_grid.py` is imported
# at 11 sites across `aios-web/api/` plus `harness/semantic.py` β€” it owns the canonical field
# contract, the workspace wire and the count envelope. Only the ~95 lines that knew about a HOST
# went; the rest never did. Its one and only `import streamlit` lived inside `render`, lazily, and
# left with it. `api/verify_no_streamlit.py` now gates that nothing here re-imports it.
#
# Deleted with them: `aios_grid_embed.html` + `aios_grid_component/index.html` (a 2.1 MB prebuilt
# bundle), `build_embed.py` that produced them, and `deploy_hf.py`'s embed-staleness guard. The
# React app is now served directly by the FastAPI container β€” there is no twin to keep fresh, so
# the entire class of "the code shipped but the bundle did not" is retired rather than guarded.


# -- W46-T33's SELF-CHECK ---------------------------------------------------------------------
# The done-when asks that "each computed date is checked against a known correct year in a test".
# There is no `test_*.py` anywhere in this repository and the `verify_*.py` gates are outside this
# ticket's fence, so the check lives HERE, beside the arithmetic it checks, and runs with
# `python aios_grid.py` (no store, no network, no fixture).
#
# β›” EVERY EXPECTED VALUE BELOW IS AN INDEPENDENT FACT, never a value produced by running the code
# above it: a test whose expectations came from its own implementation is a tautology.  The
# Jewish anchors each carry the hebcal CONVERTER url they were fetched from, one fetch per row.
# ⚠ Hebcal's holiday LISTING pages print the preceding SUNSET, one day earlier than the
# converter; an expectation taken from a listing page is off by one for every Jewish holiday.
_SELFCHECK_HOLIDAYS = (
    # code, gregorian year, expected ISO dates
    ('NEW_YEARS', 2027, ['2027-01-01']),
    ('VALENTINES', 2027, ['2027-02-14']),
    ('INDEPENDENCE_DAY', 2027, ['2027-07-04']),
    ('HALLOWEEN', 2027, ['2027-10-31']),
    ('CHRISTMAS_EVE', 2027, ['2027-12-24']),
    # Christmas 2027 is a SATURDAY.  A named holiday is the true date and must NOT shift to the
    # Friday, which is already Christmas Eve above.  The US federal CALENDAR does shift it, and
    # that difference is checked as a negative control further down.
    ('CHRISTMAS', 2027, ['2027-12-25']),
    ('NEW_YEARS_EVE', 2027, ['2027-12-31']),
    ('MOTHERS_DAY', 2026, ['2026-05-10']),     # second Sunday of May 2026
    ('FATHERS_DAY', 2026, ['2026-06-21']),     # third Sunday of June 2026
    ('MEMORIAL_DAY', 2026, ['2026-05-25']),    # last Monday of May 2026
    ('LABOR_DAY', 2026, ['2026-09-07']),       # first Monday of September 2026
    ('THANKSGIVING', 2026, ['2026-11-26']),    # fourth Thursday of November 2026
    ('EASTER', 2026, ['2026-04-05']),
    ('EASTER', 2027, ['2027-03-28']),
    # hebcal.com/converter?gy=2026&gm=9&gd=12&g2h=1  -> 1 Tishrei 5787
    ('ROSH_HASHANAH', 2026, ['2026-09-12']),
    # hebcal.com/converter?gy=2027&gm=10&gd=2&g2h=1  -> 1 Tishrei 5788
    ('ROSH_HASHANAH', 2027, ['2027-10-02']),
    # hebcal.com/converter?gy=2030&gm=9&gd=28&g2h=1  -> 1 Tishrei 5791
    ('ROSH_HASHANAH', 2030, ['2030-09-28']),
    # hebcal.com/converter?gy=2027&gm=10&gd=11&g2h=1 -> 10 Tishrei 5788
    ('YOM_KIPPUR', 2027, ['2027-10-11']),
    # hebcal.com/converter?gy=2027&gm=12&gd=25&g2h=1 -> 25 Kislev 5788
    ('HANUKKAH', 2027, ['2027-12-25']),
    # hebcal.com/converter?gy=2026&gm=4&gd=2&g2h=1   -> 15 Nisan 5786
    ('PASSOVER', 2026, ['2026-04-02']),
    # hebcal.com/converter?gy=2028&gm=4&gd=11&g2h=1  -> 15 Nisan 5788.  Together with Rosh
    # Hashanah 2027 above this is the STRADDLE control: both come from Hebrew year 5788, which
    # sits in two different Gregorian years.
    ('PASSOVER', 2028, ['2028-04-11']),
)

_SELFCHECK_ENDS = (
    # name, ends config, viewing day, expected preview of a weekly-Monday rule from 2026-01-01
    ('never', {'kind': 'never'}, '2026-01-01',
     ['2026-01-05', '2026-01-12', '2026-01-19', '2026-01-26', '2026-02-02']),
    ('on cuts the tail', {'kind': 'on', 'date': '2026-01-26'}, '2026-01-01',
     ['2026-01-05', '2026-01-12', '2026-01-19', '2026-01-26']),
    ('after 3 from the start', {'kind': 'after', 'count': 3}, '2026-01-01',
     ['2026-01-05', '2026-01-12', '2026-01-19']),
    # A count already spent by past occurrences is the case that catches the wrong reading.
    ('after 3 seen later', {'kind': 'after', 'count': 3}, '2026-01-13', ['2026-01-19']),
    ('after 3 seen past the end', {'kind': 'after', 'count': 3}, '2026-02-01', []),
    ('a malformed count degrades to never', {'kind': 'after', 'count': 0}, '2026-01-01',
     ['2026-01-05', '2026-01-12', '2026-01-19', '2026-01-26', '2026-02-02']),
    ('a garbage ends object degrades to never', 'not-an-object', '2026-01-01',
     ['2026-01-05', '2026-01-12', '2026-01-19', '2026-01-26', '2026-02-02']),
)

_SELFCHECK_WEEKLY = {'startDate': '2026-01-01',
                     'anchorField': {'table': 'same', 'field': 'due'},
                     'rules': [{'kind': 'weekly', 'interval': 1, 'weekdays': [0]}],
                     'previewCount': 10}


def selfcheck_recurrence():
    """Return (failures, lines) for the granular holidays and the `ends` stopping condition."""
    state = {'bad': 0}
    lines = []

    def check(ok, text):
        state['bad'] += 0 if ok else 1
        lines.append(('ok   ' if ok else 'FAIL ') + text)

    for code, year, want in _SELFCHECK_HOLIDAYS:
        got = sorted(day.isoformat() for day in public_holidays(code, year))
        check(got == sorted(want), '%-17s %d want %s got %s' % (code, year, want, got))

    # Every selectable code must produce a date in every year of a decade, or the selector
    # promises a recurrence that is silently a no-op.
    empty = [(item['code'], year) for item in PUBLIC_HOLIDAY_CALENDARS
             for year in range(2026, 2036) if not public_holidays(item['code'], year)]
    check(not empty, 'every code yields a date for 2026..2035 (%d empty)' % len(empty))
    # The registry and the computation table must not drift apart.
    declared = set(item['code'] for item in PUBLIC_HOLIDAY_CALENDARS
                   if item['group'] == 'holiday')
    check(declared == set(_GRANULAR_HOLIDAYS),
          'registry and computation table agree on %d granular codes' % len(declared))
    check(all(item.get('group') in ('calendar', 'holiday')
              for item in PUBLIC_HOLIDAY_CALENDARS),
          'every registry entry carries a group')
    check(not [item for item in PUBLIC_HOLIDAY_CALENDARS
               if 'β€”' in item['label'] or '–' in item['label']],
          'no label carries an em dash or an en dash')

    # NEGATIVE CONTROLS.
    check(public_holidays('NOT_A_HOLIDAY', 2026) == frozenset(),
          'NC an unknown code still returns an empty set')
    check(public_holidays('CHRISTMAS', 2027) != public_holidays('US', 2027),
          'NC a granular code does not fall through to the US federal set')
    check(_dt.date(2027, 12, 25) in public_holidays('CHRISTMAS', 2027)
          and _dt.date(2027, 12, 25) not in public_holidays('US', 2027),
          'NC Christmas 2027 is a Saturday: the named day stays, the federal calendar shifts')
    check(_hebrew_date(5788, _HEBREW_TISHREI, 1).year == 2027
          and _hebrew_date(5788, _HEBREW_NISAN, 15).year == 2028,
          'NC Hebrew 5788 straddles Gregorian 2027 and 2028')
    jewish = ('ROSH_HASHANAH', 'YOM_KIPPUR', 'HANUKKAH', 'PASSOVER')
    saved_cache = dict(_HOLIDAY_CACHE)
    globals()['_HOLIDAY_CACHE'] = {}
    globals()['_HEBREW_YEAR_CACHE'] = {}
    globals()['_HEBREW_EPOCH'] = _HEBREW_EPOCH + 1
    broken = sum(1 for code, year, want in _SELFCHECK_HOLIDAYS if code in jewish
                 and sorted(day.isoformat()
                            for day in public_holidays(code, year)) != sorted(want))
    globals()['_HEBREW_EPOCH'] = _HEBREW_EPOCH - 1
    globals()['_HEBREW_YEAR_CACHE'] = {}
    globals()['_HOLIDAY_CACHE'] = saved_cache
    expected_jewish = len([1 for code, _, _ in _SELFCHECK_HOLIDAYS if code in jewish])
    check(broken == expected_jewish,
          'NC a one day epoch shift breaks all %d Jewish anchors (broke %d)'
          % (expected_jewish, broken))

    for name, ends, today, want in _SELFCHECK_ENDS:
        got = recurrence_preview(dict(_SELFCHECK_WEEKLY, ends=ends), today=today)
        got = got[:len(want)] if want else got
        check(got == want, '%-42s want %s got %s' % (name, want, got))
    once = clean_date_recurrence(dict(_SELFCHECK_WEEKLY, ends={'kind': 'after', 'count': 3}))
    check(once.get('ends') == {'kind': 'after', 'count': 3}, 'ends survives the field cleaner')
    check(clean_date_recurrence(once) == once, 'clean_date_recurrence is idempotent over ends')
    check('ends' not in (clean_date_recurrence(_SELFCHECK_WEEKLY) or {}),
          'a recurrence with no ends grows no ends key')
    return state['bad'], lines


if __name__ == '__main__':
    failures, report = selfcheck_recurrence()
    print('\n'.join(report))
    print('\nRESULT: %d/%d checks passed' % (len(report) - failures, len(report)))
    raise SystemExit(1 if failures else 0)