scalus.compiler.sir.lowering.typegens

Generator for BuiltinValue (CIP-0153 MaryEraValue).

Unlike BLS12_381_MlResult, BuiltinValue supports Data conversion via valueData/unValueData.

DataConstr representation emitter for sum case-class types.

Owns the DataConstr-specific emission shapes for a Scala 3 sum (sealed-trait + case-class hierarchy lowered to Cardano Constr(tag, [field-data, ...])):

• genConstrLowered: forwards to the variant case-class's own typegen (variants live as Prod types that know how to assemble their own bytes).
• genMatchDataConstr / genMatchDataConstrCase: tag/field extraction via unConstrData, with lvCaseInteger (V4+) or if-then-else chain (V3) for branch dispatch.
• upcastOne: synthesizes a parent-sum Constr by reusing the child's bytes under the parent's variant tag.

Pre-Phase-4c-step-3 this was named SumCaseSirTypeGenerator; the rename aligns terminology with the design doc (per-repr emitters at §3.2). prepareCases, findConstructors, and retrieveDataDecl stay here as shared helpers because SumUplcConstrOps and ProductCaseEmitter both reuse them.

Type generator for the builtin Data type.

Data is a special Plutus type that can represent arbitrary structured data. It has 5 constructors:

• Constr(tag: Integer, args: List[Data])
• Map(pairs: List[(Data, Data)])
• List(elements: List[Data])
• I(value: Integer)
• B(value: ByteString)

Pattern matching on Data requires PlutusV4's Case on Data instruction.

Representation is data in pack. Used like Product with have one element wibt name 'toList'

Type generator for BuiltinArray.

BuiltinArray is a native UPLC type that holds elements. When used as a field in a case class, it needs to be converted to/from Data representation (Data.List).

Default representation: ProdBuiltinArray(elementRepr) (native UPLC array) Data representation: PackedArrayAsList (Data.List)

Emitter for ProductCaseClassRepresentation.ProdBuiltinPair(_, _) scrutinees.

Owns the Match shape for a value already in BuiltinPair form: extracts the two components via Case on Pair (V4+) or fstPair/sndPair (V1-V3), binds them in scope, and lowers the case body.

Constr emission for ProdBuiltinPair flows through ProductCaseEmitter.genConstrLowered → ProdDataListOps.genConstr → conversions in ProdDispatch; only the Match path is per-emitter logic.

Emitter for ProductCaseClassRepresentation.ProdDataList and the wider Data-shape product family (ProdDataConstr, PackedDataList, PairIntDataList) — they all share the unConstrData/headList/tailList extraction pattern and converge on ProdDataList for Match.

Owns:

• genConstr (Data-list-shaped Constr emission).
• genSelect (field projection through ProdDataList).
• genMatch (single-constructor extraction; multi-case input is shrunk via selectMatchCase, then handed to DataConstrEmitter.genMatchDataConstrCase for the actual binding + body lowering).

Constructor-handling helpers (retrieveConstrDecl, retrieveConstrIndex, selectMatchCase) still live on ProductCaseEmitter during the Phase 4c migration — they're shared with ProdBuiltinPairOps and several Sum-side typegens.

Emitter for ProductCaseClassRepresentation.ProdUplcConstr — native UPLC Constr(tag, [t1, t2, ...]) emission for product values.

Owns:

• genConstr: adopts each argument to its target field representation (canonical LambdaRepresentation for function fields; the @UplcRepr-annotated repr for annotated fields; the field type's natural repr when the type itself carries a class-level @UplcRepr), then assembles a Term.Constr-shaped LoweredValue tagged with the constructor's index.
• hasClassLevelUplcRepr (private helper): unwraps Annotated / TypeLambda / TypeProxy and returns true when the underlying (CaseClass | SumCaseClass).decl.annotations carry the uplcRepr key.

Called from:

• ProductCaseEmitter.genConstrLowered (Data-vs-UplcConstr dispatcher);
• ProductCaseUplcConstrOnlyEmitter, ProductCaseUplcConstrEmitter, SumCaseUplcConstrEmitter, SumCaseUplcConstrOnlyEmitter — all with the same (constr, loweredArgs) signature.

Constructor-handling helpers (retrieveConstrIndex, retrieveConstrDecl) still live on ProductCaseEmitter; called cross-class from here.

Product with one element without parent, represented as an element.

Type generator for product case classes annotated with @UplcRepr(UplcConstr).

Like ProductCaseUplcConstrOnlyEmitter but for Data-compatible types:

• canBeConvertedToData = true
• defaultDataRepresentation returns DataConstr
• defaultTypeVarRepresentation returns DataConstr

Type generator for product case classes that cannot be converted to Data (contain functions or BLS elements). Uses UplcConstr representation.

Sub-trait for typegens that know how to convert their values to other representations directly — i.e., types whose conversion logic doesn't go through SumDispatch / ProdDispatch. Examples: primitives (Integer, ByteString, ...), Data, Fun, TypeVar, Unit, BLS curve elements, BuiltinValue, BuiltinArray, PackedDataMap.

Sum and Prod typegens (DataConstrEmitter, SumCaseUplcConstr*, ProductCase*, OneElementWrapper, SumListEmitter*) extend the base SirTypeUplcGenerator without this sub-trait — their conversions are owned by SumDispatch.toRepresentation / ProdDispatch.toRepresentation and exposed via per-emitter emitConvert methods. Calling toRepresentation on those typegens directly is a compile-time error (no method to call), making the "concentrate Sum/Prod conversion in dispatchers" architectural rule machine-checked.

Parameterized list type generator for BuiltinList[X] where X is not BuiltinPair. For pair lists, use SumPairBuiltinListEmitter instead.

Shared base for the two @UplcRepr(UplcConstr)-driven sum-case generators: SumCaseUplcConstrEmitter (Data-compatible) and SumCaseUplcConstrOnlyEmitter (Fun-bearing, no Data side).

Both lower to SumUplcConstr by default and both promote a ProdUplcConstr value into a single-entry SumUplcConstr parent in upcastOne. Subclasses differ on Data-side surface (defaultDataRepresentation, defaultTypeVarReperesentation, canBeConvertedToData), constructor/select/match emission, and outbound conversion (emitConvert).

Type generator for sum types (enums) annotated with @UplcRepr(UplcConstr).

Like SumCaseUplcConstrOnlyEmitter but for Data-compatible types:

• canBeConvertedToData = true
• defaultDataRepresentation returns DataConstr
• defaultTypeVarRepresentation returns DataConstr

handle next cases: scalus.cardano.onchain.plutus.prelude.List[A] scalus.uplc.builtin.BuiltinList[A] scalus.cardano.onchain.plutus.prelude.PairList[A, B]

Generator for BuiltinList[BuiltinPair[Data,Data]] — pair lists. Uses SumPairBuiltinList representation, serialized via mapData/unMapData.

Type generator for sum types using UplcConstr representation.

Handles construction, pattern matching, field selection, and representation conversions for types stored as native UPLC Constr(tag, [fields]).

Used for:

• Types with function/BLS fields (canBeConvertedToData = false)
• Data-compatible types annotated with @UplcRepr("UplcConstr") (canBeConvertedToData = true)

throw error on any attempt.

Cross-cutting helper for TypeVarRepresentation source values (Phase 5, design §3.6). A value carrying TypeVarRepresentation(kind) has bytes in some concrete repr's form; which form depends on kind and the value's underlying SIR type:

• Transparent — passthrough; bytes are in whatever form the source produced. Conversion to a concrete target relabels the value as the target repr.
• Unwrapped — bytes are in tp.defaultRepresentation form. Conversion relabels as that underlying repr first, then delegates back to the dispatcher to convert to the target.
• Fixed — bytes are in tp.defaultTypeVarReperesentation form (the type's natural Data-shaped form). Conversion converts to that underlying repr first, then routes to the target.

bridgeFromKind is currently called from SumUplcConstrOps.emitConvert, SumDispatch.sumCaseImpl, OneElementWrapperEmitter.emitConvert, and SumListEmitterCommon.emitConvert.

The companion bridgeToKind handles the symmetric case — concrete source, TypeVar target. Canonical contract: result.representation reflects the actual byte shape (concrete repr the bytes were converted to), NOT the requested TypeVar target — symmetric to bridgeFromKind, which also returns a concrete-repr value rather than wrapping a TypeVar label. Downstream consumers that need the TypeVar label can wrap explicitly. This convention preserves the "honest about byte shape" invariant: .representation always reflects what the bytes actually are, never an abstract claim that may not match.

We assume that type variable can be converted to data, and it is impossible to do something meaningful with it in the UPLC, except pass the value as an argument in unchanged form.