Home /Modules/java/CONVERSION.PRINCIPLES.md

CONVERSION.PRINCIPLES.md

lib/java/CONVERSION.PRINCIPLES.md · 163 line(s) · markdown

Java to SLeeLa conversion: principles, what is done, what is left

Revision 1.0, 2026-11-13. Part of the Java tier; the normative text is JAVA.SPEC.md. This page is the summary and the ledger.

1. Principles

#PrincipleMeaning in practice
1Functional equivalenceA converted program prints and returns what the Java program does on a JDK. Textual likeness is not the goal.
2Java improvements live in the Java tierLibrary code in lib/java and lowerings in the converter (sleelactl/convert). Not in the SLeeLa compiler, VM or runtime. The language features syntax 3.1 added before this rule stay where they are and are used as they are.
3Fail closedA construct that cannot be converted equivalently is refused with file:line:col [construct] reason. A file with any refused member writes nothing. No near-misses.
4The model owns the lawsTypes, operators, casts, string conversion and library result types are rows of impl/subjects/conversion/conversion.model. The converter holds structure (how a statement is rewritten), not arithmetic.
5Lower to what existsNo new syntax or opcode. A Java construct without a SLeeLa form becomes a short sequence of existing forms (generated classes, temporaries, library calls), as jdk-28/LOWERING.md prescribes.
6Proof by differenceEvery supported construct has a Java program whose output must be byte-identical between a JDK and the converted program on the SLeeLa VM. Every refusal has a program that must be refused.
7Honest statusThe report of a run and the passing tests are the status. Nothing is claimed beyond them. The whole JDK is not converted.
8Preserve evaluation order and Java widthsint wraps at 32 bits, char is 16 bits, float rounds to 24 bits after every operation, division by zero throws, operands evaluate left to right.
9Name mapping is explicitNames that collide with SLeeLa built-ins are renamed consistently (close is closeResource); members with reserved names are refused; locals are renamed with a trailing _.
10Policies are flags, not defaultsAnything that weakens equivalence is off unless asked: --single-thread makes synchronized and volatile plain.
11Metadata Class on every classConverted classes carry the descriptive record; unknown values are unknown/none, never invented. Interfaces hold no state and carry none.

2. What is done

Every row has a proof program under sleelactl/convert/tests/java/ (run bash tests/javaconv_differential_test.sh) unless the last column says otherwise.

2.1 Values and operators

Java constructHow it is convertedWhereProof
int arithmetic, shifts, ~, unary -32-bit wrap through JavaOperands (addInt, mulInt, shlInt, ...)model binop/unop rows, lib/java/JavaOperands.sleelaOperands
Division and remainderdivInt/remInt/divLong/remLong; zero divisor throws ArithmeticException; MIN / -1 cornerJavaOperandsOperands
long, double arithmeticnativemodel rowsOperands, Basics
byte, short, charnarrowing on store and cast (toByte, toShort, toChar)model cast rowsOperands
floatheld in a double, rounded to binary32 after every + - * / %, conversion and cast; literals are the nearest floatlib/java/JavaFloat.sleela (uses java.lang.Float rounding)Floats
Casts ((int) d, (long) d, (char) i, ...)Java saturation and truncation rules (d2i, d2l, d2b, ...)model cast rowsOperands
Compound assignment x op= yx = (T)(x op y) with the implicit narrowingconverter + model compoundOperands
Char literals and char as a numberinteger code typed char; (int)/(long) of a char is a real cast because syntax 3.1 shows a char-typed value as textconverterStrings, Operands
Widening to double parameters and variablesexplicit (double), so later / does not divide as integersconverter coerce, adaptArgsVarargs, Basics

2.2 Strings and text

Java constructHow it is convertedWhereProof
String + with any operandJLS 5.1.11: double through Double.toString, float through JavaFloat.text, char through JavaText, objects through toString() (null is "null")model tostr rows, converter strOfStrings, Enums
Object shown as textgenerated static String javaText(Name x) on every class with a toStringconverterNested, Enums
String.valueOf(x)"" + x with the same conversionsconverterFormats
String.join(sep, ...)JavaFormat.joinArraylib/java/JavaFormat.sleelaFormats
String.format with a literal formatexpanded at conversion time into JavaFormat calls, one per conversion; %d %x %X %o %f %s %c %b %n %%, flags - 0 + , space, width, precision; %f half-up on the shortest digitsJavaFormatFormats
== between Stringsrefused (identity in Java, value in SLeeLa)converterreject/StringIdentity
Text blocks, escapes, \udecoded by the C lexerjava_lex.cescapes: Strings; text blocks: no test

2.3 Control flow

Java constructHow it is convertedWhereProof
if, while, do, for, enhanced for, break, continuenativeconverterControl, Basics
switch statement (fallthrough, default anywhere, stacked labels)native SLeeLa switchconverterSwitches
Arrow cases case A, B ->case plus implicit breakconverterSwitches
switch expression with yieldhoisted temporary assigned in each armconverterSwitches, Enums
Enum labels in casebare name resolved in the selector's enumconverterEnums
Labeled break/continuelanguage feature, syntax 3.1SLEELA.syntax 44.4Flow
return/break/continue through finallylanguage feature, syntax 3.1 (the finally runs)SLEELA.syntax 44.5Flow, Resources
try/catch/finally, multi-catchtyped catch; a multi-catch replicates the handlerconverterControl, Flow (multi-catch: no test)
try-with-resourcesone try per resource, reverse close, suppressed exceptions keptconverterResources
assertomitted (disabled by default in Java)converterno test

2.4 Expressions

Java constructHow it is convertedWhereProof
Assignment used as a value(x = y) with the assigned valueconverterSwitches
Prefix ++/-- as a valuenew value, with the 32-bit wrapconverterSwitches
Postfix ++/-- as a valueold value recovered by the inverse stepconverterSwitches
Ternary ?:, instanceof, casts to classesnativeconverterBasics, Shapes
x instanceof T vv declared before the statement, assigned when the test succeedsconverterRefs
Method invocation conversionargument widening, varargs packingconverter adaptArgsVarargs

2.5 Arrays

Java constructHow it is convertedWhereProof
new T[n], defaultsnative, typed fill (0, 0.0, false, null)VMBasics
{a, b, c} and new T[]{...}language feature, syntax 3.1SLEELA.syntax 44.3Basics, Grid
new T[a][b], jagged new T[a][], nested initializerslanguage feature, syntax 3.1SLEELA.syntax 46.3Grid
a.lengtharrayLength(a)model call rowGrid
Array index out of rangeArrayIndexOutOfBoundsException thrown by the VM inside a try (37.5); no converter wrapperSLEELA.syntax 37.5, SLJavaFaultsBounds
Negative array sizeNegativeArraySizeException through JavaChecks.size(n)lib/java/JavaChecks.sleelaBounds
char[], float[], long[], boolean[]element defaults and narrowing as aboveconverterGrid, Floats

2.6 Classes and types

Java constructHow it is convertedWhereProof
Classes, fields, methods, constructors, this, super(...), inheritance, virtual callsnative SLeeLa classesconverterShapes
Interfaces, abstract classesnative; interfaces carry no metadataconverterShapes, Anon
static members and static fieldsnative (initialised before main)converterShapes
public static void main(String[] args)static void main() with String[] args = new String[0]converterall
Enums (fields, constructors, methods, constant bodies, values, valueOf, ordinal, name, compareTo)a class with hidden name/ordinal, one static instance per constant, constant bodies as generated subclassesconverterEnums
Varargs T... xsparameter is T[]; call sites with a known signature pack the extra argumentsconverterVarargs
Nested static classes, interfaces, enumshoisted to Outer__Name; static members of the outer visibleconverterNested
Inner (non-static) classesfield outer_, constructors take the enclosing object, Outer.thisconverterNested
Anonymous classesgenerated class; captured locals as cap_ fields, enclosing object as outer_converterAnon
Lambdasgenerated class implementing the target's one abstract method; this is the enclosing objectconverterAnon, Functional
Method references (Type::static, Type::instance, Type::new, this::m, local::m)the lambda they stand forconverterRefs
JDK functional interfaces (Runnable, Supplier, Consumer, Function, Predicate, Comparator, Bi/Unary/Binary forms)seeded as known, generic parameters untypedconverterFunctional
Recordsfield per component, canonical (or compact) constructor, accessors, toString, equals/hashCode for simple componentsconverterRecords
Field defaults and initialization orderdefault value on every field; field initializers and instance { } blocks after super(...)converterInit
close()mapped to closeResource() in declarations and callsconverter mapMemberResources
A method named like a SLeeLa built-in (read, write, accept, lock, ...)calls qualified with the owner class or this.converter, builtin_names.hBounds
Reserved or built-in member namesrefused; locals renamedconverterVarargs (a method named join was caught); no refusal test
Packages, importsdropped; library members resolve through import java.jdk-N;converterall

2.7 Concurrency and policy

Java constructHow it is convertedWhereProof
synchronized method and block, volatileplain, only with --single-thread; refused without itconverter optionSync, reject/SyncBlock

2.8 Machinery

PieceWhat it doesWhere
C lexerJLS ch. 3 tokens: numbers (hex, octal, binary, _, suffixes), escapes, text blockssleelactl/convert/java_lex.c
Model loaderreads the conversion subject modelconv_model.c, impl/subjects/conversion/conversion.model
Typed translator (C++)two passes; pass 1 collects signatures of the whole tree so calls across files are typedjava_to_sleela.cpp
CLI--jdk, --jdk-version, --file, --bundle/--split, --single-thread, --self-check; writes CONVERSION-REPORT.md/.jsonjavaconv_main.cpp
sleelactl registrationsleelactl build java-convert, sleelactl run java-convert ...bin/sleelactl.d/registry.conf
Presumed-JDK directoriessleelactl/jdk/<N>/java in, sleelactl/jdk/<N>/sleela outsleelactl/jdk/README.md
Support libraryJavaOperands, JavaFloat, JavaFormat, JavaText, jdk-25/jdk-28 unitslib/java
Differential test22 programs on a JDK and on the VM, plus 9 refusals and a stale-output check (32 of 32, 2026-11-13; CI java-convert.yml)tests/javaconv_differential_test.sh
Language features the tier useschar literal, array initializer, labels, finally on abrupt exit, a.length, multi-dimensional arrays, char as text (all syntax 3.1)SLEELA.syntax sections 44 to 46

3. What is left

#ItemWhy it is openHow it would be doneSize
1Operands of unknown type (generics)Generic parameters are untyped, so arithmetic and some calls on them are refused. This is the largest blocker on real JDK code and on most lambdas over collections.Collect generic signatures; substitute type arguments through calls and assignments; infer lambda parameter types from the target.large
2Lambda targets that are JDK interfaces not collectedThe abstract method is unknown unless the interface is one of the seeded ones.Convert the JDK tree so its interfaces are collected, or extend the seeded table.medium
3Nested capture chainsA lambda or anonymous class inside another generated class is refused.Capture through the enclosing generated class.medium
4outer.new Inner() and local classesRare forms not parsed.Qualified inner creation; hoist local classes like nested ones.small to medium
5Switch type patterns, record patterns, sealed exhaustivenessBinding scope in a switch arm.Per-arm cast declaration; exhaustiveness is not checked at run time.medium
6Records: the harder membersequals/hashCode omitted for double, float and reference components (test Records covers the rest).Lower Double.compare and Objects.equals.small
7String.format beyond literalsNon-literal formats, %e %g %S %h %t, argument indexes.A runtime formatter in JavaFormat.medium
8Static initializer blocksstatic { } is refused; instance { } blocks are converted (test Init).A guarded static init method called on first use (JLS 12.4).small
9Real concurrencysynchronized/volatile are plain under --single-thread; a truly multi-threaded program is not claimed equivalent.Monitors and a memory model on the VM, or keep the policy.large
10native methodsNo Java body to convert.Hand-written bindings only.not convertible
11Library behaviorConverted code calls lib/java units; many jdk-28 units are signature stubs that return null. Equivalence of a call depends on that unit being implemented.Implement units; the differential suite is the oracle.very large
12Whole-JDK measurementRe-run 2026-11-13: 420 of 884 files converted (426 with --single-thread; 344 on 2026-11-12). Largest first refusals: nested-ambiguous 131 files, nested 67, untyped 57. See JAVA.CONVERSION.STATUS.md. Converted files are not yet measured through sleela check.Re-run on a presumed JDK tree, publish the report.small
13Reflection and class literalsgetClass(), X.class, int.class, annotation processing.No lowering designed.open
14float/double corner casesPostfix ++ of a float used as a value; -0.0 sign; hex float literals.Case by case.small
15Two converterssleelactl/convert (C/C++) and lib/java/converter (SLeeLa) share the model but not the lowerings.Align them or retire one.medium
16CI and binariesThe differential test is not in CI; working-binaries/ was refreshed 2026-11-13 and now reports syntax 3.1.Add a CI job (needs a JDK and a source build).small
17Name-mapping interplay with unconverted lib/java unitsA converted class that implements a library interface declaring close() does not match closeResource().Rename in the library units too, or map both.small
18Null dereference and stack overflowStill fatal VM errors, not NullPointerException / StackOverflowError; faults with no try handler are fatal (as an uncaught exception ends a Java program)Extend the fault kinds; null needs a typed check at each dereferencemedium
19Methods named like a Munction verb (connect, send, enable, ...) called on a receiverThe compiler gives those names the verb meaning on every receiverRename like close, in the library units toosmall

4. How to keep this page true

When a construct moves from section 3 to section 2: add the proof program under sleelactl/convert/tests/java/, update JAVA.SPEC.md (sections 4 and 5), the converter README.md, and move the row here. If a row cannot name a passing proof, it stays in section 3.