ADR-029 Phase 5: PV11 compiler optimizations umbrella

[satran004]

Summary

Umbrella issue for ADR-029 Phase 5: target-aware compiler and stdlib optimizations that use PV11 features to reduce script size and/or execution budget.

No Phase 5 optimization should begin until the explicit V3/PV11 compiler target and feature enforcement in #76 are complete. Correctness and target legality come first. Each optimization accepted for implementation will receive its own focused issue and PR, linked back to this umbrella.

Related readiness umbrella: #65
Compiler-target prerequisite: #76
Phase 0 contract cleanup: #75
ADR tasks: PV11-050 through PV11-056
Cost/reference baseline: cardano-node 11.0.1 / Plutus 1.63.0.0 at f92b7d7d82622a26caf456a6be33859f697e2cfc

Initial policy

The initial compiler target is V3/PV11 only. Phase 5 therefore does not need to maintain PV10 fallback lowerings. If JuLC later adds a PV10 compiler target, each affected optimization must define a legal fallback or reject that feature for PV10 in a separate target-support issue.

This phase is not required for Java/Truffle evaluator parity. It improves generated code after the compiler can prove that the selected operations are legal for its target.

Candidate workstreams

PV11-050 — Lower JulcList.drop to DropList — P1 / S

Replace the current recursive NullList/TailList lowering with the native PV11 DropList builtin for the V3/PV11 target.

Required evidence:

• equivalent results and failure behavior;
• smaller generated UPLC;
• lower budget for representative list sizes and counts;
• regression tests demonstrating that the final program contains DropList rather than the recursive template.

PV11-051 — Case-on-builtin lowering — P1 / L

Evaluate target-aware lowering of:

• boolean conditionals to Case Bool;
• list matching/decomposition to Case List;
• integer switches to Case Integer;
• native pair destructuring to Case Pair.

Each rewrite must preserve strictness and failure behavior and must beat the existing chooser/equality/list-builtin form under the pinned PV11 cost model. This may become more than one child issue if the lowerings are independently reviewable.

PV11-052 — Typed native Value API and lowering — P1 / M

Introduce a dedicated native Value type, tentatively JulcValue, instead of representing both ordinary Data and native Value as PlutusData.

Target flow:

Data-encoded Value
    -> UnValueData once
    -> native lookup/union/contains/scale operations
    -> ValueData only at an external Data boundary

The design should prevent accidental Data/Value mixing and allow redundant conversions and nested-map scans to be eliminated safely.

PV11-053 — Cost-directed list-to-array promotion — P2 / L

Detect repeated indexed access to the same immutable list and, only when profitable, lower it to:

ListToArray once
    -> repeated IndexArray calls

The child issue must define cost-model-derived break-even thresholds, use-count/escape analysis, and cases that must remain lists. Single or cheap sequential accesses must not be promoted blindly.

PV11-054 — BLS MSM fusion and typed API — P2 / M

Recognize or expose typed expressions equivalent to:

s1 * P1 + s2 * P2 + ... + sn * Pn

and lower them to the PV11 G1/G2 multi-scalar-multiplication builtins when list length, scalar bounds, and failure semantics match. Replace loosely typed PlutusData list surfaces where practical.

PV11-055 — ExpModInteger lowering and constant folding — P2 / M

• Add a target-aware mapping for explicit modular-exponentiation idioms.
• Constant-fold literal calls only when reference failure behavior is preserved.
• Never rewrite ordinary exponentiation without an explicit modulus.

PV11-056 — Target-aware Value/Array constant folding — P2 / M

Fold pure literal operations whose result or failure is statically known and legal for V3/PV11, including selected array length/index/drop and native Value operations. Known failures must remain failures at the correct semantic point.

Child-issue policy

Before implementing a workstream:

1. Create a focused issue linked here.
2. Record the exact source pattern and generated before/after UPLC.
3. Define semantic, strictness, and failure-equivalence tests.
4. Define representative script-size and CPU/memory benchmarks using the pinned PV11 costs.
5. Decide whether the optimization is mandatory, optional, or behind a compiler flag.
6. Document any generated-script hash change and migration impact.
7. Have the implementation independently reviewed before merge.

Shared acceptance requirements

Every child optimization must:

• Run only for a compiler target where every introduced term and builtin is legal.
• Preserve results, evaluation order, strictness, and reference failure behavior.
• Include a non-rewritten comparison test or golden output.
• Demonstrate a measured budget and/or script-size improvement; availability alone is not sufficient.
• Use the selected target cost model rather than hard-coded intuition when profitability depends on input size.
• Be deterministic and document script-hash changes.
• Pass compiler, Java VM, Truffle VM, examples, and full repository tests.
• Add user-facing documentation when generated code or public typed APIs change.

Umbrella checklist

• Create and complete a focused issue for PV11-050 (DropList lowering).
• Create and complete or explicitly defer focused issue(s) for PV11-051 (case-on-builtin lowering).
• Create and complete or explicitly defer a focused issue for PV11-052 (typed native Value).
• Create and complete or explicitly defer a focused issue for PV11-053 (list-to-array promotion).
• Create and complete or explicitly defer a focused issue for PV11-054 (BLS MSM fusion/API).
• Create and complete or explicitly defer a focused issue for PV11-055 (ExpModInteger lowering/folding).
• Create and complete or explicitly defer a focused issue for PV11-056 (Value/Array folding).
• Publish aggregate before/after size and budget results for the optimizations that ship.
• Update ADR-029 and release documentation with completed and deferred work.

Out of scope

• Protocol-aware evaluator correctness, already delivered for Java/Truffle under julc-vm-java discards protocol version and cannot select PV11 builtin semantics #61–Fail closed when a builtin has no cost-model entry #64 and related parity work.
• Scalus explicit-target certification, tracked by [vm-scalus] Implement and certify protocol-aware LedgerEvaluationTarget evaluation #74.
• Adding PV10 or V1/V2 compiler targets.
• Treating every available PV11 builtin as automatically profitable.

Deferred implementation follow-ups

ADR-032 research/disposition is complete. The checklist below tracks later implementation or prerequisite work. A rule must not be enabled merely because its PV11 builtin exists.

• O3 typed List case lowering — ADR-032 follow-up O3: implement typed List case lowering #110 (research: ADR-032 O3: evaluate case-on-List traversal #98)
• O4 typed Pair destructuring analysis — ADR-032 follow-up O4: implement typed Pair destructuring analysis #111 (research: ADR-032 O4: evaluate case-on-Pair destructuring #99)
• O5 safe Integer Case source semantics — ADR-032 follow-up O5: define safe Integer Case source semantics #112 (research: ADR-032 O5: evaluate case-on-Integer switches #100)
• O6 typed Unit sequencing — ADR-032 follow-up O6: add typed Unit sequencing before Case lowering #113 (research: ADR-032 O6: evaluate case-on-Unit sequencing #101)
• O8 typed native Value conversion motion — ADR-032 follow-up O8: implement typed native Value conversion motion #114 (research: ADR-032 O8: evaluate typed native Value conversion motion #102)
• O9 costed List-to-Array promotion — ADR-032 follow-up O9: implement costed List-to-Array promotion gate #115 (research: ADR-032 O9: derive list-to-array promotion gate #103)
• O10 typed native Array literals and folds — ADR-032 follow-up O10: design typed native Array literals and safe folds #116 (research: ADR-032 O10: evaluate Array literal folding #106)
• O11 typed BLS values and explicit MSM — ADR-032 follow-up O11: define typed BLS values and implement explicit MSM #117 (research: ADR-032 O11: design typed BLS group and native-list APIs #96)
• O12 explicit modular-exponentiation recognition decision — ADR-032 follow-up O12: decide explicit modular-exponentiation recognition #118 (research: ADR-032 O12: evaluate explicit modular-exponentiation idiom recognition #104)
• O14 native Value literals and folding — ADR-032 follow-up O14: define native Value literals and safe folding #119 (research: ADR-032 O14: evaluate native Value literal folding #108)
• O15 minimal representation-aware let sharing — ADR-032 follow-up O15: add minimal representation-aware let sharing #120 (research: ADR-032 O15: evaluate representation-aware let sharing #105)

Each follow-up inherits this umbrella's shared acceptance requirements and adds operation-specific gates for semantic equivalence, evaluation order and strictness, reference failure behavior, deterministic output, pinned PV11 size/CPU/memory evidence, Java/Truffle agreement, Scalus language-level cross-checking where supported, affected-module and repository tests, documentation, and independent correctness review.

A follow-up may close without enabling a rewrite when its decision gate proves that no safe or useful source contract exists. Such a rejection must be recorded in ADR evidence; it must not be converted into an untyped peephole optimization.

[satran004]

ADR-032 implementation is complete on integration/adr-032-pv11-optimizations and ready for its stacked PR against integration/adr-031-compiler-target. Shipped opt-in PV11-safe rules: O1 DropList, O2 Case Bool, and O13 ExpModInteger literal folding, plus the typed JulcValue boundary. Every other candidate was measured and explicitly deferred with semantic prerequisites. Aggregate validator-like evidence: 169 to 88 FLAT bytes; accepted path CPU 5,346,583 to 1,935,936 and memory 19,605 to 8,533; failure outcomes are exact in Java and Truffle VMs. Baseline remains the default and no new compilation target is introduced. Full ./gradlew build and documentation build pass. Detailed evidence is under adr/evidence and the release notes. Leaving the umbrella open until the stacked implementation PR is reviewed and merged.

[satran004]

Closing as completed after PR #109 merged ADR-032 into main. The Phase 5 acceptance criteria are satisfied. Issues #110 through #120 remain open as explicitly deferred, independently scheduled follow-ups and are not prerequisites for closing this delivery phase.