RPNXCortado represents a JVM class file as an owning tree rooted at rpnx::cortado::class_file. The model deliberately mirrors the class-file format: constant-pool references remain typed indexes, attributes retain their name indexes, and bytecode instructions retain their exact encodings. Parsing and serializing an unchanged supported class therefore preserves its binary structure rather than normalizing it into a higher-level Java model.

Header map

Header	Purpose
`types.hpp`	Constant-pool entries, access flags, and JAR aggregates.
`descriptors.hpp`	JVM field and method descriptor grammars.
`signatures.hpp`	Generic Signature attribute grammars.
`bytecode.hpp`	Exact instruction encodings and code-array I/O.
`attributes.hpp`	Typed attributes and the complete class-file aggregate.
`class_file.hpp`	Class-file serialization and deserialization.
`validation.hpp`	Non-throwing structural and version validation.
`builders.hpp`	Constant-pool, symbolic bytecode, and class builders.
`jar.hpp`	JAR-compatible ZIP serialization and deserialization.
`errors.hpp`	Exceptions used at parsing, validation, and assembly boundaries.

Exact and symbolic bytecode

The rpnx::cortado::instruction variant is the exact wire-level model. It has one alternative for every supported or reserved JVM opcode. Use it when round-tripping or deliberately selecting an encoding.

rpnx::cortado::code_builder is the symbolic generation layer. Its labels are owned by a builder lineage, so labels from unrelated builders are rejected. Finalization resolves labels and constant-pool references, selects instruction widths, stabilizes switch padding, calculates method limits, and can generate a StackMapTable. This separation keeps the wire model lossless while providing a safer interface for newly generated methods.

Index and offset conventions

rpnx::cortado::constant_pool_index uses the JVM's one-based logical index. Zero retains its format-specific sentinel meaning where the JVM specification allows it. Long and double constants occupy two logical slots even though the owning class_file::constant_pool vector stores one variant value per entry.

rpnx::cortado::code_offset is a byte offset from the beginning of a method's code array. Branch displacements are signed and relative to the opcode address, as encoded by the JVM format. Local-variable indexes identify slots rather than source-level variables; long and double values consume two slots.

Strict and tooling modes

Strict mode is the default for reading and writing. It rejects malformed, reserved, unsupported, or inconsistent structures. Tooling mode exists for binary inspection and preservation: if an unknown opcode makes instruction boundaries unknowable, the complete code body is represented as rpnx::cortado::raw_code. Tooling mode does not guess boundaries or silently rewrite the method.

Validation is a separate operation. rpnx::cortado::validate_class_file returns bounded structured diagnostics for model errors instead of throwing. Serialization in strict mode validates before emitting bytes and reports an invalid model with rpnx::cortado::validation_error.

Ownership and resource limits

All parsed strings, byte sequences, constants, attributes, instructions, and JAR entries are owned by their enclosing aggregates. Views accepted by builder functions are consumed during the call and are not retained.

Untrusted-input entry points expose explicit limits for aggregate sizes, nesting, and structure counts. Applications should lower these defaults when their domain has tighter bounds. A limit failure is a hard parse or validation failure; the library never returns a partially decoded object.

JAR boundary

The JAR layer reads and writes ordinary single-disk ZIP archives using stored or raw-DEFLATE entries. It checks headers, declared sizes, and CRC-32 values. Encrypted, split, and Zip64 archives are outside this API's supported format and are rejected explicitly.