Remove Generic-based Flat derivation machinery (#7542)

The internal flat library contained Generic-based Flat class derivation
via GHC.Generics that had a bug: deserializing large enum types (512+
constructors) consumed infinite memory. While not a security risk (UPLC
on-chain code uses only manual Flat instances), the buggy dead code was
distracting. This commit removes the entire Generic derivation machinery.

Changes:

1. Add manual Flat instances to all types that previously relied on
   Generic defaults: Maybe, Either, Complex, [], NonEmpty, tuples (2-7),
   Tree, Filler, PostAligned, PreAligned, SrcSpan, SrcSpans, and all PIR
   types (Recursivity, Strictness, Datatype, Binding, Program, Term).
   Manual encoding is bit-identical to the Generic encoding.

2. Add missing `size` methods to partial Flat instances in
   FlatInstances.hs (Name, Version, VarDecl, TyVarDecl, Program,
   NamedDeBruijn) and Value.hs (K, Quantity, Value) that previously
   relied on the Generic default for `size`.

3. Gut Class.hs: remove ~440 lines of GFlat*/GEncode*/GSize* classes,
   NumConstructors type family, all Generic default method implementations,
   and associated imports/pragmas/re-exports.

4. Remove ENUM_LARGE test infrastructure (E256/E258 types, Flat/Arbitrary
   instances, ~530 lines) and delete Core.hs inspection tests.

5. Fix transitive import breakage: files that got Generic from the
   PlutusCore.Flat re-export now import GHC.Generics directly.
   Remove `hiding (to)` from imports that no longer re-export Generics.

6. Strip Generic-specific doctests from Tutorial.hs.

All existing tests pass (5281 across 4 suites). Manual instances produce
bit-identical encoding verified by round-trip tests and golden files.

Author: Unisay

plutus-core/flat/src/PlutusCore/Flat/Class.hs

@@ -17,7 +17,9 @@ module PlutusCore.Flat.Filler
 
 import Control.DeepSeq (NFData)
 import Data.Typeable (Typeable)
-import PlutusCore.Flat.Class (Flat (..), Generic)
+import GHC.Generics (Generic)
+import PlutusCore.Flat.Class (Flat (..))
+import PlutusCore.Flat.Decoder.Prim (dBool)
 import PlutusCore.Flat.Decoder.Types (Get)
 import PlutusCore.Flat.Encoder.Strict (eFiller, sFillerMax)
 
@@ -33,6 +35,9 @@ data Filler
 instance Flat Filler where
   encode _ = eFiller
   size = sFillerMax
+  decode = do
+    tag <- dBool
+    if tag then pure FillerEnd else FillerBit <$> decode
 
 -- use generated decode
 
@@ -50,15 +55,25 @@ instance Flat a => Flat (PostAligned a) where
 #else
 
 data PostAligned a = PostAligned { postValue :: a, postFiller :: Filler }
-  deriving (Show, Eq, Ord, Generic, NFData,Flat)
+  deriving (Show, Eq, Ord, Generic, NFData)
+
+instance Flat a => Flat (PostAligned a) where
+    encode (PostAligned v f) = encode v <> encode f
+    decode = PostAligned <$> decode <*> decode
+    size (PostAligned v f) n = size v (size f n)
 
 #endif
 
 {-| A Pre aligned value, a value preceded by a filler
 
  Useful to prealign ByteArrays, Texts and any structure that can be encoded more efficiently when byte aligned. -}
 data PreAligned a = PreAligned {preFiller :: Filler, preValue :: a}
-  deriving (Show, Eq, Ord, Generic, NFData, Flat)
+  deriving (Show, Eq, Ord, Generic, NFData)
+
+instance Flat a => Flat (PreAligned a) where
+  encode (PreAligned f v) = encode f <> encode v
+  decode = PreAligned <$> decode <*> decode
+  size (PreAligned f v) n = size f (size v n)
 
 -- | Length of a filler in bits
 fillerLength :: Num a => Filler -> a

plutus-core/flat/src/PlutusCore/Flat/Filler.hs

@@ -1,8 +1,6 @@
 {-# LANGUAGE CPP                #-}
-{-# LANGUAGE DeriveGeneric      #-}
 {-# LANGUAGE FlexibleContexts   #-}
 {-# LANGUAGE FlexibleInstances  #-}
-{-# LANGUAGE StandaloneDeriving #-}
 
 -- | Flat instances for the base library
 module PlutusCore.Flat.Instances.Base () where
@@ -206,7 +204,14 @@ instance Flat Char where
 >>> test (Just False::Maybe Bool)
 (True,2,"10")
 -}
-instance Flat a => Flat (Maybe a)
+instance Flat a => Flat (Maybe a) where
+    encode Nothing  = eFalse
+    encode (Just x) = eTrue <> encode x
+    decode = do
+      tag <- dBool
+      if tag then Just <$> decode else pure Nothing
+    size Nothing  n = 1 + n
+    size (Just x) n = 1 + size x n
 
 {- |
 >>> test (Left False::Either Bool ())
@@ -215,7 +220,14 @@ instance Flat a => Flat (Maybe a)
 >>> test (Right ()::Either Bool ())
 (True,1,"1")
 -}
-instance (Flat a, Flat b) => Flat (Either a b)
+instance (Flat a, Flat b) => Flat (Either a b) where
+    encode (Left  x) = eFalse <> encode x
+    encode (Right x) = eTrue <> encode x
+    decode = do
+      tag <- dBool
+      if tag then Right <$> decode else Left <$> decode
+    size (Left  x) n = 1 + size x n
+    size (Right x) n = 1 + size x n
 
 {- |
 >>> test (MkFixed 123 :: Fixed E0)
@@ -598,7 +610,10 @@ instance Flat Double where
 >>> test (4 :+ 2 :: Complex Word8)
 (True,16,"00000100 00000010")
 -}
-instance Flat a => Flat (Complex a)
+instance Flat a => Flat (Complex a) where
+    encode (r :+ i) = encode r <> encode i
+    decode = (:+) <$> decode <*> decode
+    size (r :+ i) n = size r (size i n)
 
 {- |
 Ratios are encoded as tuples of (numerator,denominator)
@@ -624,7 +639,14 @@ instance (Integral a, Flat a) => Flat (Ratio a) where
 This instance and other similar ones are declared as @OVERLAPPABLE@, because for better encoding/decoding
 performance it can be useful to declare instances of concrete types, such as @[Char]@ (not provided out of the box).
 -}
-instance {-# OVERLAPPABLE #-} Flat a => Flat [a]
+instance {-# OVERLAPPABLE #-} Flat a => Flat [a] where
+    encode []     = eFalse
+    encode (x:xs) = eTrue <> encode x <> encode xs
+    decode = do
+      tag <- dBool
+      if tag then (:) <$> decode <*> decode else pure []
+    size []     n = 1 + n
+    size (x:xs) n = 1 + size x (size xs n)
 
 {-
 >>> import Weigh
@@ -658,7 +680,10 @@ instance {-# OVERLAPPABLE #-} Flat a => Flat [a]
 >>> test (B.fromList [False,False])
 (True,4,"0100")
 -}
-instance {-# OVERLAPPABLE #-} Flat a => Flat (B.NonEmpty a)
+instance {-# OVERLAPPABLE #-} Flat a => Flat (B.NonEmpty a) where
+    encode (x B.:| xs) = encode x <> encode xs
+    decode = (B.:|) <$> decode <*> decode
+    size (x B.:| xs) n = size x (size xs n)
 
 -- #endif
 
@@ -681,24 +706,39 @@ tst (1::Int,"2","3","4","5","6","7","8")
 -}
 
 -- Not sure if these should be OVERLAPPABLE
-instance {-# OVERLAPPABLE #-} (Flat a, Flat b) => Flat (a, b)
+instance {-# OVERLAPPABLE #-} (Flat a, Flat b) => Flat (a, b) where
+    encode (a, b) = encode a <> encode b
+    decode = (,) <$> decode <*> decode
+    size (a, b) n = size a (size b n)
 
-instance {-# OVERLAPPABLE #-} (Flat a, Flat b, Flat c) => Flat (a, b, c)
+instance {-# OVERLAPPABLE #-} (Flat a, Flat b, Flat c) => Flat (a, b, c) where
+    encode (a, b, c) = encode a <> encode b <> encode c
+    decode = (,,) <$> decode <*> decode <*> decode
+    size (a, b, c) n = size a (size b (size c n))
 
 instance
     {-# OVERLAPPABLE #-}
     (Flat a, Flat b, Flat c, Flat d) =>
-    Flat (a, b, c, d)
+    Flat (a, b, c, d) where
+    encode (a, b, c, d) = encode a <> encode b <> encode c <> encode d
+    decode = (,,,) <$> decode <*> decode <*> decode <*> decode
+    size (a, b, c, d) n = size a (size b (size c (size d n)))
 
 instance
     {-# OVERLAPPABLE #-}
     (Flat a, Flat b, Flat c, Flat d, Flat e) =>
-    Flat (a, b, c, d, e)
+    Flat (a, b, c, d, e) where
+    encode (a, b, c, d, e) = encode a <> encode b <> encode c <> encode d <> encode e
+    decode = (,,,,) <$> decode <*> decode <*> decode <*> decode <*> decode
+    size (a, b, c, d, e) n = size a (size b (size c (size d (size e n))))
 
 instance
     {-# OVERLAPPABLE #-}
     (Flat a, Flat b, Flat c, Flat d, Flat e, Flat f) =>
-    Flat (a, b, c, d, e, f)
+    Flat (a, b, c, d, e, f) where
+    encode (a, b, c, d, e, f) = encode a <> encode b <> encode c <> encode d <> encode e <> encode f
+    decode = (,,,,,) <$> decode <*> decode <*> decode <*> decode <*> decode <*> decode
+    size (a, b, c, d, e, f) n = size a (size b (size c (size d (size e (size f n)))))
 
 instance
     {-# OVERLAPPABLE #-}
@@ -710,4 +750,7 @@ instance
     , Flat f
     , Flat g
     ) =>
-    Flat (a, b, c, d, e, f, g)
+    Flat (a, b, c, d, e, f, g) where
+    encode (a, b, c, d, e, f, g) = encode a <> encode b <> encode c <> encode d <> encode e <> encode f <> encode g
+    decode = (,,,,,,) <$> decode <*> decode <*> decode <*> decode <*> decode <*> decode <*> decode
+    size (a, b, c, d, e, f, g) n = size a (size b (size c (size d (size e (size f (size g n))))))

plutus-core/flat/src/PlutusCore/Flat/Instances/Base.hs

@@ -1,10 +1,7 @@
-{-# LANGUAGE CPP #-}
-{-# LANGUAGE DeriveGeneric #-}
 {-# LANGUAGE FlexibleContexts #-}
 {-# LANGUAGE MonoLocalBinds #-}
 {-# LANGUAGE RankNTypes #-}
 {-# LANGUAGE ScopedTypeVariables #-}
-{-# LANGUAGE StandaloneDeriving #-}
 {-# LANGUAGE TypeSynonymInstances #-}
 {-# LANGUAGE NoMonomorphismRestriction #-}
 
@@ -20,6 +17,7 @@ import Data.Map
 import Data.Sequence
 import Data.Set
 import Data.Tree
+import PlutusCore.Flat.Class qualified as Flat
 import PlutusCore.Flat.Instances.Base ()
 import PlutusCore.Flat.Instances.Mono
 import PlutusCore.Flat.Instances.Util
@@ -108,8 +106,7 @@ instance (Flat a, Ord a) => Flat (Set a) where
 {-|
 >>>  tst (Node (1::Word8) [Node 2 [Node 3 []], Node 4 []])
 (True,39,[1,129,64,200,32]) -}
-#if ! MIN_VERSION_containers(0,5,8)
-deriving instance Generic (Tree a)
-#endif
-
-instance Flat a => Flat (Tree a)
+instance Flat a => Flat (Tree a) where
+  encode (Node x ts) = Flat.encode x <> Flat.encode ts
+  decode = Node <$> Flat.decode <*> Flat.decode
+  size (Node x ts) n = Flat.size x (Flat.size ts n)

plutus-core/flat/src/PlutusCore/Flat/Instances/Containers.hs

@@ -2,8 +2,11 @@
 
 module PlutusCore.Flat.Instances.Extra where
 
-import PlutusCore.Flat.Class (Flat)
+import PlutusCore.Flat.Class (Flat (..))
+import PlutusCore.Flat.Decoder (dBool)
+import PlutusCore.Flat.Encoder (eFalse, eTrue, (<>))
 import PlutusCore.Flat.Instances.Base ()
+import Prelude hiding ((<>))
 
 {-$setup
 >>> import PlutusCore.Flat.Instances.Test -}
@@ -16,4 +19,11 @@ For better encoding/decoding performance, it is useful to declare instances of c
 
 >>> tstBits "aaa"
 (True,28,"10110000 11011000 01101100 0010") -}
-instance {-# OVERLAPPING #-} Flat [Char]
+instance {-# OVERLAPPING #-} Flat [Char] where
+  encode [] = eFalse
+  encode (x : xs) = eTrue <> encode x <> encode xs
+  decode = do
+    tag <- dBool
+    if tag then (:) <$> decode <*> decode else pure []
+  size [] n = 1 + n
+  size (x : xs) n = 1 + size x (size xs n)

plutus-core/flat/src/PlutusCore/Flat/Instances/Extra.hs

@@ -7,83 +7,29 @@ where
 {-$setup
 To (de)serialise a data type, make it an instance of the 'Flat.Class.Flat' class.
 
-There is <https://hackage.haskell.org/package/base/docs/GHC-Generics.html Generics> based support to automatically derive a correct instance.
-
-Let’s see some code.
-
-We need a couple of extensions:
-
->>> :set -XDeriveGeneric -XDeriveAnyClass
+Instances should define 'Flat.Class.encode', 'Flat.Class.decode' and 'Flat.Class.size' methods.
 
 The @Flat@ top module:
 
 >>> import PlutusCore.Flat
 
 And, just for fun, a couple of functions to display an encoded value as a sequence of bits:
 
->>> import PlutusCore.Flat.Instances.Test (flatBits,allBits)
-
-Define a few custom data types, deriving @Generic@ and @Flat@:
-
->>> data Result = Bad | Good deriving (Show,Generic,Flat)
-
->>> data Direction = North | South | Center | East | West deriving (Show,Generic,Flat)
-
->>> data List a = Nil | Cons a (List a) deriving (Show,Generic,Flat) -}
+>>> import PlutusCore.Flat.Instances.Test (flatBits,allBits) -}
 
 {-$main
-Now we can encode a List of Directions using 'Flat.Run.flat':
-
->>> flat $ Cons North (Cons South Nil)
-"\149"
-
-The result is a strict <https://hackage.haskell.org/package/bytestring/docs/Data-ByteString.html ByteString>.
-
-And decode it back using 'Flat.Run.unflat':
-
->>> unflat . flat $ Cons North (Cons South Nil) :: Decoded (List Direction)
-Right (Cons North (Cons South Nil))
-
-The result is a 'Flat.Decoded' value: 'Either' a 'Flat.DecodeException' or the actual value.
-
 === Optimal Bit-Encoding
 #optimal-bit-encoding#
 
 A pecularity of Flat is that it uses an optimal bit-encoding rather than
 the usual byte-oriented one.
 
-One bit is sufficient to encode a 'Result' or an empty 'List':
-
->>> flatBits Good
-"1"
-
->>> flatBits (Nil::List Direction)
-"0"
-
-Two or three bits suffice for a 'Direction':
-
->>> flatBits South
-"01"
-
->>> flatBits West
-"111"
-
 For the serialisation to work with byte-oriented devices or storage, we need to add some padding.
 
 To do so, rather than encoding a plain value, 'Flat.Run.flat' encodes a 'Flat.Filler.PostAligned' value, that's to say a value followed by a 'Flat.Filler.Filler' that stretches till the next byte boundary.
 
 In practice, the padding is a, possibly empty, sequence of 0s followed by a 1.
 
-For example, this list encodes as 7 bits:
-
->>> flatBits $ Cons North (Cons South Nil)
-"1001010"
-
-And, with the added padding of a final "1", will snugly fit in a single byte:
-
->>> allBits $ Cons North (Cons South Nil)
-"10010101"
-
 But .. you don't need to worry about these details as byte-padding is automatically added by the function 'Flat.Run.flat' and removed by 'Flat.Run.unflat'.
 
 === Pre-defined Instances