# 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`](JAVA.SPEC.md). This page is the summary and the ledger. ## 1. Principles | # | Principle | Meaning in practice | |---|---|---| | 1 | **Functional equivalence** | A converted program prints and returns what the Java program does on a JDK. Textual likeness is not the goal. | | 2 | **Java improvements live in the Java tier** | Library 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. | | 3 | **Fail closed** | A 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. | | 4 | **The model owns the laws** | Types, 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. | | 5 | **Lower to what exists** | No 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. | | 6 | **Proof by difference** | Every 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. | | 7 | **Honest status** | The report of a run and the passing tests are the status. Nothing is claimed beyond them. The whole JDK is not converted. | | 8 | **Preserve evaluation order and Java widths** | `int` 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. | | 9 | **Name mapping is explicit** | Names that collide with SLeeLa built-ins are renamed consistently (`close` is `closeResource`); members with reserved names are refused; locals are renamed with a trailing `_`. | | 10 | **Policies are flags, not defaults** | Anything that weakens equivalence is off unless asked: `--single-thread` makes `synchronized` and `volatile` plain. | | 11 | **Metadata Class on every class** | Converted 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 construct | How it is converted | Where | Proof | |---|---|---|---| | `int` arithmetic, shifts, `~`, unary `-` | 32-bit wrap through `JavaOperands` (`addInt`, `mulInt`, `shlInt`, ...) | model `binop`/`unop` rows, `lib/java/JavaOperands.sleela` | `Operands` | | Division and remainder | `divInt`/`remInt`/`divLong`/`remLong`; zero divisor throws `ArithmeticException`; `MIN / -1` corner | `JavaOperands` | `Operands` | | `long`, `double` arithmetic | native | model rows | `Operands`, `Basics` | | `byte`, `short`, `char` | narrowing on store and cast (`toByte`, `toShort`, `toChar`) | model `cast` rows | `Operands` | | `float` | held in a double, rounded to binary32 after every `+ - * / %`, conversion and cast; literals are the nearest float | `lib/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` rows | `Operands` | | Compound assignment `x op= y` | `x = (T)(x op y)` with the implicit narrowing | converter + model `compound` | `Operands` | | Char literals and `char` as a number | integer code typed `char`; `(int)`/`(long)` of a char is a real cast because syntax 3.1 shows a char-typed value as text | converter | `Strings`, `Operands` | | Widening to `double` parameters and variables | explicit `(double)`, so later `/` does not divide as integers | converter `coerce`, `adaptArgs` | `Varargs`, `Basics` | ### 2.2 Strings and text | Java construct | How it is converted | Where | Proof | |---|---|---|---| | String `+` with any operand | JLS 5.1.11: `double` through `Double.toString`, `float` through `JavaFloat.text`, `char` through `JavaText`, objects through `toString()` (null is `"null"`) | model `tostr` rows, converter `strOf` | `Strings`, `Enums` | | Object shown as text | generated `static String javaText(Name x)` on every class with a `toString` | converter | `Nested`, `Enums` | | `String.valueOf(x)` | `"" + x` with the same conversions | converter | `Formats` | | `String.join(sep, ...)` | `JavaFormat.joinArray` | `lib/java/JavaFormat.sleela` | `Formats` | | `String.format` with a literal format | expanded 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 digits | `JavaFormat` | `Formats` | | `==` between Strings | refused (identity in Java, value in SLeeLa) | converter | `reject/StringIdentity` | | Text blocks, escapes, `\u` | decoded by the C lexer | `java_lex.c` | escapes: `Strings`; text blocks: no test | ### 2.3 Control flow | Java construct | How it is converted | Where | Proof | |---|---|---|---| | `if`, `while`, `do`, `for`, enhanced `for`, `break`, `continue` | native | converter | `Control`, `Basics` | | `switch` statement (fallthrough, `default` anywhere, stacked labels) | native SLeeLa `switch` | converter | `Switches` | | Arrow cases `case A, B ->` | case plus implicit `break` | converter | `Switches` | | `switch` expression with `yield` | hoisted temporary assigned in each arm | converter | `Switches`, `Enums` | | Enum labels in `case` | bare name resolved in the selector's enum | converter | `Enums` | | Labeled `break`/`continue` | language feature, syntax 3.1 | SLEELA.syntax 44.4 | `Flow` | | `return`/`break`/`continue` through `finally` | language feature, syntax 3.1 (the `finally` runs) | SLEELA.syntax 44.5 | `Flow`, `Resources` | | `try`/`catch`/`finally`, multi-catch | typed catch; a multi-catch replicates the handler | converter | `Control`, `Flow` (multi-catch: no test) | | try-with-resources | one `try` per resource, reverse close, suppressed exceptions kept | converter | `Resources` | | `assert` | omitted (disabled by default in Java) | converter | no test | ### 2.4 Expressions | Java construct | How it is converted | Where | Proof | |---|---|---|---| | Assignment used as a value | `(x = y)` with the assigned value | converter | `Switches` | | Prefix `++`/`--` as a value | new value, with the 32-bit wrap | converter | `Switches` | | Postfix `++`/`--` as a value | old value recovered by the inverse step | converter | `Switches` | | Ternary `?:`, `instanceof`, casts to classes | native | converter | `Basics`, `Shapes` | | `x instanceof T v` | `v` declared before the statement, assigned when the test succeeds | converter | `Refs` | | Method invocation conversion | argument widening, varargs packing | converter `adaptArgs` | `Varargs` | ### 2.5 Arrays | Java construct | How it is converted | Where | Proof | |---|---|---|---| | `new T[n]`, defaults | native, typed fill (0, 0.0, false, null) | VM | `Basics` | | `{a, b, c}` and `new T[]{...}` | language feature, syntax 3.1 | SLEELA.syntax 44.3 | `Basics`, `Grid` | | `new T[a][b]`, jagged `new T[a][]`, nested initializers | language feature, syntax 3.1 | SLEELA.syntax 46.3 | `Grid` | | `a.length` | `arrayLength(a)` | model `call` row | `Grid` | | Array index out of range | `ArrayIndexOutOfBoundsException` thrown by the VM inside a `try` (37.5); no converter wrapper | SLEELA.syntax 37.5, `SLJavaFaults` | `Bounds` | | Negative array size | `NegativeArraySizeException` through `JavaChecks.size(n)` | `lib/java/JavaChecks.sleela` | `Bounds` | | `char[]`, `float[]`, `long[]`, `boolean[]` | element defaults and narrowing as above | converter | `Grid`, `Floats` | ### 2.6 Classes and types | Java construct | How it is converted | Where | Proof | |---|---|---|---| | Classes, fields, methods, constructors, `this`, `super(...)`, inheritance, virtual calls | native SLeeLa classes | converter | `Shapes` | | Interfaces, abstract classes | native; interfaces carry no metadata | converter | `Shapes`, `Anon` | | `static` members and static fields | native (initialised before `main`) | converter | `Shapes` | | `public static void main(String[] args)` | `static void main()` with `String[] args = new String[0]` | converter | all | | 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 subclasses | converter | `Enums` | | Varargs `T... xs` | parameter is `T[]`; call sites with a known signature pack the extra arguments | converter | `Varargs` | | Nested static classes, interfaces, enums | hoisted to `Outer__Name`; static members of the outer visible | converter | `Nested` | | Inner (non-static) classes | field `outer_`, constructors take the enclosing object, `Outer.this` | converter | `Nested` | | Anonymous classes | generated class; captured locals as `cap_` fields, enclosing object as `outer_` | converter | `Anon` | | Lambdas | generated class implementing the target's one abstract method; `this` is the enclosing object | converter | `Anon`, `Functional` | | Method references (`Type::static`, `Type::instance`, `Type::new`, `this::m`, `local::m`) | the lambda they stand for | converter | `Refs` | | JDK functional interfaces (Runnable, Supplier, Consumer, Function, Predicate, Comparator, Bi/Unary/Binary forms) | seeded as known, generic parameters untyped | converter | `Functional` | | Records | field per component, canonical (or compact) constructor, accessors, `toString`, `equals`/`hashCode` for simple components | converter | `Records` | | Field defaults and initialization order | default value on every field; field initializers and instance `{ }` blocks after `super(...)` | converter | `Init` | | `close()` | mapped to `closeResource()` in declarations and calls | converter `mapMember` | `Resources` | | A method named like a SLeeLa built-in (`read`, `write`, `accept`, `lock`, ...) | calls qualified with the owner class or `this.` | converter, `builtin_names.h` | `Bounds` | | Reserved or built-in member names | refused; locals renamed | converter | `Varargs` (a method named `join` was caught); no refusal test | | Packages, imports | dropped; library members resolve through `import java.jdk-N;` | converter | all | ### 2.7 Concurrency and policy | Java construct | How it is converted | Where | Proof | |---|---|---|---| | `synchronized` method and block, `volatile` | plain, only with `--single-thread`; refused without it | converter option | `Sync`, `reject/SyncBlock` | ### 2.8 Machinery | Piece | What it does | Where | |---|---|---| | C lexer | JLS ch. 3 tokens: numbers (hex, octal, binary, `_`, suffixes), escapes, text blocks | `sleelactl/convert/java_lex.c` | | Model loader | reads the conversion subject model | `conv_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 typed | `java_to_sleela.cpp` | | CLI | `--jdk`, `--jdk-version`, `--file`, `--bundle`/`--split`, `--single-thread`, `--self-check`; writes `CONVERSION-REPORT.md/.json` | `javaconv_main.cpp` | | sleelactl registration | `sleelactl build java-convert`, `sleelactl run java-convert ...` | `bin/sleelactl.d/registry.conf` | | Presumed-JDK directories | `sleelactl/jdk//java` in, `sleelactl/jdk//sleela` out | `sleelactl/jdk/README.md` | | Support library | `JavaOperands`, `JavaFloat`, `JavaFormat`, `JavaText`, `jdk-25`/`jdk-28` units | `lib/java` | | Differential test | 22 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 uses | char 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 | # | Item | Why it is open | How it would be done | Size | |---|---|---|---|---| | 1 | **Operands 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 | | 2 | **Lambda targets that are JDK interfaces not collected** | The 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 | | 3 | **Nested capture chains** | A lambda or anonymous class inside another generated class is refused. | Capture through the enclosing generated class. | medium | | 4 | **`outer.new Inner()` and local classes** | Rare forms not parsed. | Qualified inner creation; hoist local classes like nested ones. | small to medium | | 5 | **Switch type patterns, record patterns, sealed exhaustiveness** | Binding scope in a switch arm. | Per-arm cast declaration; exhaustiveness is not checked at run time. | medium | | 6 | **Records: the harder members** | `equals`/`hashCode` omitted for `double`, `float` and reference components (test `Records` covers the rest). | Lower `Double.compare` and `Objects.equals`. | small | | 7 | **`String.format` beyond literals** | Non-literal formats, `%e %g %S %h %t`, argument indexes. | A runtime formatter in `JavaFormat`. | medium | | 8 | **Static initializer blocks** | `static { }` is refused; instance `{ }` blocks are converted (test `Init`). | A guarded static init method called on first use (JLS 12.4). | small | | 9 | **Real concurrency** | `synchronized`/`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 | | 10 | **`native` methods** | No Java body to convert. | Hand-written bindings only. | not convertible | | 11 | **Library behavior** | Converted 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 | | 12 | **Whole-JDK measurement** | **Re-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 | | 13 | **Reflection and class literals** | `getClass()`, `X.class`, `int.class`, annotation processing. | No lowering designed. | open | | 14 | **`float`/`double` corner cases** | Postfix `++` of a float used as a value; `-0.0` sign; hex float literals. | Case by case. | small | | 15 | **Two converters** | `sleelactl/convert` (C/C++) and `lib/java/converter` (SLeeLa) share the model but not the lowerings. | Align them or retire one. | medium | | 16 | **CI and binaries** | The 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 | | 17 | **Name-mapping interplay with unconverted `lib/java` units** | A converted class that implements a library interface declaring `close()` does not match `closeResource()`. | Rename in the library units too, or map both. | small | | 18 | **Null dereference and stack overflow** | Still 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 dereference | medium | | 19 | **Methods named like a Munction verb** (`connect`, `send`, `enable`, ...) called on a receiver | The compiler gives those names the verb meaning on every receiver | Rename like `close`, in the library units too | small | ## 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.