ADR-029 Phase 4: Add an explicit V3/PV11 compiler target and diagnostics

[satran004]

Summary

Implement ADR-029 Phase 4 by making the JuLC compiler target-aware and ensuring every emitted UPLC feature is legal for the selected ledger profile.

The initial design is intentionally narrow: support Plutus V3 / protocol version 11 / the corresponding supported UPLC version only. This issue does not require PV10 fallback lowerings or V1/V2 code generation. Unsupported compiler targets must fail clearly instead of silently generating a different profile.

Related umbrella: #65
Phase 0 prerequisite: #75
ADR tasks: PV11-040 through PV11-043
Authoritative baseline: cardano-node 11.0.1 / Plutus 1.63.0.0 at f92b7d7d82622a26caf456a6be33859f697e2cfc

Goal

A successful compilation must mean that the generated program is structurally and feature-wise valid for one known ledger target. The compiler, evaluator, CLI, and diagnostics must not infer different protocol profiles.

The conceptual compiler target contains:

ledger language + protocol version + UPLC version

For this first implementation, the supported profile is V3/PV11. The API should remain extensible so additional profiles can be added later without scattering protocol checks throughout compiler lowering code.

Scope

PV11-040 — Compiler target/configuration

• Introduce an immutable compiler target containing ledger language, protocol version, and UPLC version.
• Add it to CompilerOptions and thread it through parsing/type checking, PIR generation, UPLC lowering, optimization, and final program construction where relevant.
• Preserve source compatibility where practical by making existing compile entry points use a documented V3/PV11 default, while retaining that resolved target in the compilation result.
• Reject requested V1, V2, PV10, future-PV, or unsupported UPLC compiler profiles with a clear unsupported-target diagnostic. Do not implement alternate PV10 lowerings in this issue.

PV11-041 — Compile-time feature enforcement

• Validate builtin availability and UPLC term forms against the selected compiler target.
• Use the same canonical feature data as VM evaluation. Refactor the registry to a shared layer if needed rather than duplicating a compiler-only table.
• Apply checks to all emission routes: language syntax, type-method lowerings, stdlib registry methods, direct Builtins calls, optimizer rewrites, and final UPLC validation.
• Keep MultiIndexArray rejected for V3/PV11 even though its AST tag and experimental runtime implementation exist.
• Ensure optimizers cannot introduce a feature that the source-level validation did not authorize.

PV11-042 — Feature metadata and diagnostics

• Give stdlib/compiler mappings enough metadata to identify required protocol or feature availability.
• Produce actionable diagnostics containing the feature, required profile, selected target, and source location where available.
• Prefer messages such as:

ListToArray requires protocol version 11; selected target is PV10
MultiIndexArray is not released for the V3/PV11 target
Plutus V2 compiler output is not supported; supported target is V3/PV11

• Keep low-level direct-builtin APIs strict. Portable high-level fallbacks can be introduced only when a future target-support issue explicitly chooses to maintain them.

PV11-043 — Target provenance

• Record the resolved target in CompileResult and relevant CLI/build output or metadata.
• Make verbose diagnostics and generated artifact information show the target used to produce the program.
• Preserve deterministic script bytes and hashes; target provenance must not accidentally alter UPLC encoding unless the selected lowering itself changes.
• Document how downstream tooling should pass the same target to evaluation.

Initial support policy

Requested compiler profile	Result in this issue
Plutus V3 / PV11 / supported UPLC version	Compile and validate
Plutus V3 / PV10	Clear unsupported-target failure
Plutus V1 or V2	Clear unsupported-target failure
Future protocol version	Clear unsupported-target failure until a pinned profile exists
V3/PV11 using future MultiIndexArray	Feature-specific compile failure

This policy avoids maintaining multiple implementations of operations such as JulcList.drop for now. Under the sole V3/PV11 target, later Phase 5 work may lower it directly to DropList.

Acceptance criteria

• One immutable target value reaches every compiler stage that can select or introduce UPLC features.
• Existing compile entry points resolve to a documented V3/PV11 target, or migration diagnostics clearly explain any required API change.
• CompileResult exposes the resolved language/protocol/UPLC target.
• The compiler and VM consume one authoritative feature registry rather than independent availability tables.
• Valid tags 87–100 compile for V3/PV11.
• Tag 101 fails for V3/PV11 through every public compiler entry path.
• Unsupported PV10, V1/V2, future-PV, and unsupported-UPLC compiler targets fail clearly; none silently fall back.
• Optimizer output is validated against the same target after rewriting.
• Diagnostics include feature and target details plus source location where available.
• CLI/build output records the resolved target.
• Tests cover positive V3/PV11 compilation, future-feature rejection, unsupported-target rejection, direct builtin calls, stdlib lowering, and optimizer-introduced terms.
• Full compiler, VM integration, examples, and repository test suites pass.

Out of scope

• Supporting PV10 compilation or maintaining PV10 fallback lowerings.
• Generating V1/V2 validators.
• Phase 5 cost-directed optimizations.
• Scalus evaluator target certification, tracked separately by [vm-scalus] Implement and certify protocol-aware LedgerEvaluationTarget evaluation #74.