LoweringContext

Annotation for a term built at lowering time: position plus the enclosing function name.

Produce a stable fingerprint of the parts of the enclosing call-site state that a cached helper's RHS captures from lctx, restricted to TypeVars occurring in tps.

Helpers in cachedTopLevelHelpers are built once per cache key and reused on subsequent hits — but their RHS bodies often consult typeVarReprEnv and the inUplcConstrListScope flag during construction (e.g. element-repr resolution inside an lvMatchList body). If the cache key omits this state, the FIRST caller's env wins, and later callers under a different env get a helper RHS that doesn't match their context. This is the alone-vs-combined Heisenbug pattern documented in sessions 11-15: the same (type, fromRepr, toRepr) cache key produces functionally-different helpers depending on first-miss timing.

Including this fingerprint in the cache key forces helpers with different captured env state to live as separate entries.

Simple name of the innermost enclosing user function being lowered, or "" outside any named binding. Stamped into scalus.uplc.UplcAnnotation.functionName so tooling (the VS Code UPLC source view) can group compiled UPLC by the source function it came from. It is pure metadata: it never influences the generated code.

Backed by a thread-local in the companion rather than by a plain field, because every LoweredValue captures it at construction time (see LoweredValue.functionName) and lowered values are built deep inside helpers that do not all carry a LoweringContext. Several lowerings can run at once in one JVM (parallel sbt subprojects, parallel test suites), so the state has to be per-thread. Always change it through withFunction.

Define a top-level recursive helper or reuse a previously-cached one for the same key.

The recipe — shared by ScalusRuntime.builtinListToUplcConstr, ScalusRuntime.uplcConstrToBuiltinList, and LoweringEq.createSumEqHelper — is:

1. Look up cacheKey in cachedTopLevelHelpers. On hit, return the cached var.
2. On miss, allocate a fresh VariableLoweredValue from funType/funRepr.
3. Register it in the cache BEFORE building the rhs so the rhs (built by buildRhs) can refer to the var for self-recursion.
4. Build the rhs by calling buildRhs(v).
5. Append (v, rhs) to pendingTopLevelLetRecs so the lowering driver emits the let-rec wrapping the lowered SIR root.

label is the short site name passed to LoweringContext.traceLetRec — used when filtering SCALUS_TRACE_LETREC output — and the currentFunction the helper body is built under, so the UPLC source view attributes the shared helper to a stable name.

Find a binding in a provider module by module name and method name.

Cache lookup with a diagnostic disable knob. Call sites should use this instead of cachedTopLevelHelpers.get(...) directly so the disable flag covers them uniformly.

Fails lowering when tp can only be encoded with constr/case and the target has no UPLC 1.1.0. Used where a type has no Data form, so there is nothing to fall back to.

If this is typevariable, try get the value from context, else leave it as is.

Whether the target can carry UPLC 1.1.0 terms (constr/case over Constr values).

Always on PlutusV3 and later; on PlutusV1/V2 only from the van Rossem hard fork, which introduced UPLC 1.1.0 for those languages (plcVersionsIntroducedIn in plutus-ledger-api). Plutus rejects constr/case in a 1.0.0 program at deserialization, so below this bound a V1/V2 target must not emit them. This is distinct from case-on-builtins, which is a protocol-version-11 feature for every language and is gated separately.

Run body with currentFunction set to name, restoring the previous value after.

Annotation-keyed cache of pre-lowered values. Indexed by Int.

Used by intrinsic resolution as an alternative to identity-based precomputedValues: the resolver substitutes references to lambda parameters with SIR.Var(name, type, anns + "argCache" → Const(Integer(idx))). lowerSIR checks the annotation and returns argCache(idx) directly. Survives substituteVarAndTypes walking that creates fresh SIR.Var instances (annotations are preserved in the copy).

Cache for top-level recursive helpers (e.g. per-type sumEq functions emitted by LoweringEq.generateSumUplcConstrEquals). Keyed by a stable type-fingerprint string. Each entry is the recursive IdentifiableLoweredValue that subsequent uses can reference; the corresponding rhs is registered in pendingTopLevelLetRecs and emitted as a let-rec wrapping the lowered SIR root.

Pending top-level let-rec bindings collected during lowering. After Lowering.lowerSIR returns the lowered SIR root, the lowering driver wraps it with a chain of let-recs for each entry. Entries are appended by innermost-completing helpers first (helper +=s AFTER any transitively-triggered sub-helpers have completed their own +=), so with foldRight wrapping, the first entry becomes outermost — inner helpers can see their outer dependencies. NOT sound for mutually recursive sums; detect and reject those at helper-construction time.