Add Flat encoding test coverage across all packages

[Unisay]

Context

• What: Add roundtrip and stable byte encoding tests for every Flat instance across all packages
• Why: Pay down test coverage debt before attempting to fix the Generic Flat derivation bug (512+ constructor crash). Encoding stability must be verified by tests first.
• Related: Preparatory work for fixing the Generic derivation bug discussed in Remove Generic-based Flat derivation machinery #7662

Approach

Added two categories of tests for Flat instances:

1. Stable byte encoding tests (a.k.a. golden/characterization tests) pin the exact byte representation of on-chain-critical types (Version, DeBruijn, DefaultFun, DefaultUni, Binder variants, UPLC Program, PIR Recursivity/Strictness). These detect any accidental encoding changes that would break on-chain script compatibility.

2. Roundtrip property tests verify unflat (flat x) == Right x for all Flat instances including library-internal types (monoid/semigroup wrappers, containers, etc.) where encoding stability is less critical but correctness still matters.

A standalone encoding generator executable (cabal run flat-encoding-generator) is included so anyone can reproduce the expected byte constants without GHCi sessions. It regenerates test fixtures from source so they don't remain opaque blobs of bits.

BLS12_381 types are deliberately skipped (their encode/decode implementations are error/fail).

Changes

Flat library tests (flat/test/Spec.hs)

• Stable byte encoding tests for: Maybe, Either, NonEmpty, Complex, Ratio, Set, Tree, Map, Seq, Filler, PreAligned
• Roundtrip QC tests for: Tree, Set, Identity, All, Any, Dual, Sum, Product, Min, Max, First, Last, Alt, Fixed, PreAligned, String

TPLC tests (plutus-core/test/Flat/Spec.hs — new module)

• Stable byte encoding for: Version, Name, Kind, DeBruijn, NamedDeBruijn, Index, SrcSpan, SrcSpans, DefaultFun (AddInteger, SubtractInteger), SomeTypeIn DefaultUniInteger
• Roundtrip tests for: SrcSpan, SrcSpans, NamedDeBruijn, Version, Name, Kind
• Newtype wrapper delegation tests: TyName, TyDeBruijn, NamedTyDeBruijn, FakeNamedDeBruijn

UPLC tests (untyped-plutus-core/testlib/Flat/Spec.hs)

• Binder stable encoding: zero-cost verification for Binder DeBruijn and Binder FakeNamedDeBruijn, delegation checks for Binder Name/TyName/NamedDeBruijn/NamedTyDeBruijn
• Binder newtype roundtrip tests
• Minimal UPLC Program roundtrip and stable byte test: (program 1.1.0 (con integer 0))
• Wired test_flat into the UPLC test entry point (was previously defined but not imported)

PIR tests (plutus-ir/test/PlutusIR/Core/Tests.hs)

• Stable byte encoding for Recursivity (NonRec/Rec) and Strictness (NonStrict/Strict)

Value tests (plutus-core/test/Value/Spec.hs)

• K encodes identically to ByteString
• Quantity encodes identically to Integer

Infrastructure

• Encoding generator executable (plutus-core/tools/GenerateEncodings.hs)
• Added FOURMOLU_DISABLE to flat/test/Spec.hs (CPP-heavy file that fourmolu cannot parse)

[zliu41]

We are not introducing any new encodings, so this should just be called "testEncodings"

[Unisay]

Renamed to testEncodingStability. Tell me if you have another idea of a better name.

[zliu41]

What's the purpose of this, and in what scenario would someone want to use this executable?

[Unisay]

Replied by changing the code comment:

-- Golden file generator for Flat encoding stability tests.
--
-- The encoding stability tests compare encoded values against expected
-- byte sequences captured as test fixtures. This tool regenerates those
-- fixtures from source, so they don't remain opaque blobs of bits.
--
-- Example: if a bug in a Flat instance is found and the encoding must
-- change in a backward-incompatible way, the stability tests will fail.
-- Run this tool to see the new wire format, update the test fixtures,
-- and confirm the encoding change was intentional.
--
-- See: https://en.wikipedia.org/wiki/Characterization_test
-- Usage: cabal run flat-encoding-generator

[zliu41]

Why is it not sufficient to use the golden test mechanism, where one can use --accept to update the golden files? In this executable you are including a specific set of test cases, which I suppose need to mirror the test cases in the stabilit tests; if we add a new test case, it also needs to be added to the executable?

[Unisay]

We're dealing with binary files here, so existing golden testing mechanism IMO is not the best fit, i.e. there is no point in diffing binary files when showing an error to a user. OTOH, I see your point that with the --accept functionality its easier to re-generate individual failing tests.

[zliu41]

Could you summarize how the current tests work - in particular, the comment above says

The encoding stability tests compare encoded values against expected byte sequences captured as test fixtures

Where are the expected byte sequences stored, if not in a golden file?

[Unisay]

Sure. The byte sequences were hardcoded inline in the test assertions:

encRaw (Nothing :: Maybe Bool) [0]
encRaw (Just True :: Maybe Bool) [192]

The generator was a separate executable that printed the same encodings to stdout for manual comparison. But you're right that --accept makes it redundant. I've reworked these into golden tests now. Each stability group produces a text file like:

Nothing :: Maybe Bool = [0]
Just True :: Maybe Bool = [192]
Right () :: Either Bool () = [128]
...

One source of truth, readable diffs, --accept for regeneration. Generator is removed.