Home /Modules/docs/CONVERSION.PRINCIPLES.md

CONVERSION.PRINCIPLES.md

docs/reference/CONVERSION.PRINCIPLES.md · 172 line(s) · markdown

<img align="right" src="../../images/sleela/sleela-medium-profile-permanent-icon-002.jpg" width="45" height="45" alt="SLeeLa">

Java to SLeeLa Conversion: Principles, What Is Done, What Is Left

Status: summary as of 2026-11-13. This file collects the Java to SLeeLa work in one place. It adds no rule of its own. The normative texts are:

Where this file and one of those disagree, the normative text wins.

1. Principles

  1. Functional equivalence. A converted program run on the SLeeLa VM must produce the same observable behaviour (output, exceptions, results) as the Java program on a JDK.
  2. Proof by output. Equivalence is shown by running both sides and comparing their output byte for byte. This covers the differential pairs, the sleelactl conversion tests and the converter samples. A claim is not made without a run.
  3. Fail loud, never wrong. A construct that cannot be converted exactly is refused or stubbed, never approximated. sleelactl java-convert refuses the whole file. lib/java/converter writes a per-member stub that throws UnsupportedOperationException and keeps the Java body as a comment. When a lowering is unsure, the result is a check error, not a call to the wrong method.
  4. Lower, do not add syntax. A Java construct with no SLeeLa form is lowered to forms SLeeLa already has (LOWERING.md). Java-only behaviour lives in the Java tier: lib/java library code and the converters (JAVA.SPEC.md section 1). General language gaps found on the way are fixed in the language, written in SLEELA.syntax first.
  5. One set of laws. Operator, cast, string-conversion and result-type laws are rows of conversion.model. Both converters read the same rows, and a law is changed in the model, not in a converter.
  6. Output syntax stays fixed. lib/java/converter writes #sleela 3.1 (owner decision); sleelactl java-convert writes #sleela 3.1.
  7. Faithful library. lib/java/jdk-28 holds one SLeeLa unit per public JDK 28 type (4,721, 1:1). A unit that computes something must compute what the JDK computes (for example a correctly rounded Math.sqrt).
  8. Every change is documented and gated. Spec first, then a backup of edited compiler or VM files (impl/backup/<topic>-<date>/). After the edit: the regenerated security/sha256-manifest.json, the library inventory counts, and the regression tests.

2. What has been done

2.1 Language and VM (SLEELA.syntax, impl/frontend, impl/core)

ItemWhat it gives Java conversionWhereProof
Java signature surface, static member accessType.member, Java modifiers, generics erased to Any38spark / oop tests
Overload resolutionmethods and constructors chosen by argument types40oop tests
Methods on String valuess.length(), s.charAt(i) bind to JavaStringMethods41conformance
Java object behavioursubtypes, super(args), this(args), implicit super(), virtual dispatch, super.m(), bodiless methods, enhanced for, L/d/f and _ literals, typed / multi catch, finally, ++/--43.6impl/tests/java_references/oop
Exact long comparisonint64 compares, not through double43.4differential
JDK 28 tier ruleimport java.jdk-28; is authoritative for every name with a JDK 28 file43.4conformance
Character literals, array initializers, labels, return/break/continue through finally, continue in a switch fixedthe 3.1 conversion blockers44impl/tests/syntax31
char type and char as text; a.length, new T[a][b]the 3.1 char and array specifications45, 46impl/tests/syntax31
Narrowing on store and castbyte, short, char, int32 wrap at Java widthcompiler emitJavaNarrowOperandSemantics pair
Bodiless method of a series integer returns 0abstract / interface int32 m(); default value43.6 rule 8oop tests
new int32[n] starts at 0Java int[] default44.3, arrayFillKindconverter sample
Interfaces are runtime supertypes(Shape) c, c instanceof Shape, catch (Iface e)43.7; slvm_add_struct_super; artifact format 5oop/any_dispatch
Calls on an Any receiverx.m(args) on an erased value dispatches at run time over the loaded classes (and JavaStringMethods)43.7oop/any_dispatch; JDK sample 553 to 522 errors
MIN / -1 and MIN % -1no SIGFPE; MIN and 0 as in Java37.5oop/vm_faults
VM faults inside a try/ 0, % 0, array index, failed cast throw ArithmeticException, ArrayIndexOutOfBoundsException, ClassCastException (Java messages) through SLJavaFaults37.5; artifact format 6oop/vm_faults

2.2 Java tier library (lib/java)

ItemRoleWhereProof
JDK 25 and JDK 28 unit treesone SLeeLa unit per public JDK type; real implementations where writtenlib/java/jdk-25, lib/java/jdk-28validate_jdk28.py (4,721 : 4,721), conformance
JavaOperands32-bit int arithmetic, shifts, narrowing, divInt / remInt / divLong, JLS 5.1.3 conversionslib/java/JavaOperands.sleelaOperandSemantics pair
JavaFloatbinary32 float held in a double, rounded after each operationlib/java/JavaFloat.sleelaFloats conversion test
JavaFormatString.format conversions, String.joinlib/java/JavaFormat.sleelaFormats conversion test
JavaText, JavaStringMethodsUTF-16 text and String methodslib/java/jdk-25/implementationsconformance
SLJavaLambda, SLJavaLambdaTablelambda values (id, env) answering every common functional-interface methodlib/java/supportLambdaDemo sample
SLJavaFaultsbuilds the Java exception for a VM fault inside a trylib/java/support/SLJavaFaults.sleelaoop/vm_faults
Math.sqrt correctly rounded; Math.abs / absExact at MIN_VALUElibrary results identical to the JDKlib/java/jdk-28MathSqrt pair, converter sample
Differential pairsJava and SLeeLa side by side, output identicalexamples/java/differential18 of 18 identical

2.3 Conversion laws (impl/subjects/conversion/conversion.model)

ItemRoleProof
binop, unop, cast, compound, incr rowsJava operator and cast laws as templatesboth converters
tostr rowsJava text of double, float, char, objectsconverter samples
ret and field rows (model 1.1.0)8,922 reflected result types of the OpenJDK 25.0.2 API, for typing call chainsgenerate_ret_rows.py --check

2.4 sleelactl java-convert (C/C++, sleelactl/convert, whole-file refusal)

AreaLoweredProof (sleelactl/convert/tests/java)
Integer arithmetic, narrowing, division by zerothrough JavaOperands; long, double nativeOperands, Basics
floatthrough JavaFloatFloats
Characters and stringschar codes, JLS 5.1.11 string conversion, String.valueOf, join, literal formatStrings, Formats
Control flowswitch (fallthrough, arrows), switch expressions (hoisted), labels, try-with-resources with suppressed exceptionsControl, Flow, Switches, Resources
Expressionsassignment and ++/-- used as values with the 32-bit wrapSwitches
Classesenums (constant bodies as subclasses), varargs packing, name mapping (close to closeResource), main(String[])Enums, Varargs, Shapes
Nested and inner typeshoisted to Outer__Name; inner classes hold outer_Nested
Anonymous classes, lambdas, method referencesgenerated classes Top__N with cap_ fields and outer_; target type from the declaration, assignment, return, field or callee signatureAnon, Functional, Refs
instanceof T vdeclared before the statement, assigned in the testRefs
Recordscanonical and compact constructors, accessors, toString, equals, hashCodeRecords
Fields and initializationJava default values; field initializers and instance { } blocks after super(...) (JLS 12.5); library superclass members typedInit
Stale outputa re-run removes what the previous run wrote, so a failed-closed file leaves nothingsuite stale-output check
Arraysone and many dimensions, jagged, nested initializers, a.lengthGrid
Concurrencysynchronized / volatile plain under --single-thread, else refusedSync
Refusalsproven by programs that must be refusedtests/reject (4)
Qualified nested namesOuter.Inner in a type is Outer__Inner; a nested class no longer extends itselfreject/QualifiedNested
Object text and char textlibrary objects through toString() (tostr reference); append('x') appends x (chartext rows)ObjectText
Whole suitetests/javaconv_differential_test.sh, CI java-convert.yml22 programs + 9 refusals + stale-output check (32 of 32, 2026-11-13)
Whole-tree runJDK 25.0.2 java.base (java/lang, java/util, java/math, java/text), 884 files420 converted (426 with --single-thread), 2026-11-13; 344 on 2026-11-12; see JAVA.CONVERSION.STATUS.md

2.5 lib/java/converter (written in SLeeLa, per-member stubs, output #sleela 3.1)

VersionLoweredMeasured
0.1.0walk, lex, rewrite, translate, fail-loud stubs, report17-file JDK sample: 47 stubs
0.2.03.1 forms kept (array initializers, char literals, labels, finally jumps); for headers with commas; pattern instanceof in two shapes35 stubs
0.3.0typed pass: int shifts through the model; double / char shown as text; JCONV_BUNDLE=1 (one document per Java file)check errors 903 to 553 bundled
0.4.0laws read from conversion.model (JConvModel); call chains typed through ret / field rowssample program 29 of 29 lines identical
0.5.0expression tree (JConvExpr): one toInt wrap where an int value leaves int arithmetic; divInt / remIntConvDemo 31 of 31 identical
0.6.0lambdas (0 to 2 parameters, typed or target-typed) and method references with a known target lowered to (id, env) (JConvLambda); functional interface types written as AnyLambdaDemo 17 of 17 identical; eight lambda-dense java.util files 31 to 15 stubs
0.7.0inner classes reach the enclosing instance: slOuter field, slOuterArg parameter, new Inner(this, ..), Outer.this, outer members prefixed (JConvOuter)JDK sample: 26 stubs, 475 check errors, 0 syntax errors

2.6 Process

ItemWhere
Backups of every edited compiler / VM fileimpl/backup/java-converter-2026-11-13, any-dispatch-2026-11-13, vm-faults-2026-11-13
Execution gatesecurity/sha256-manifest.json, make check-manifest
Library inventorylib/LIBRARY.SYMBOLS.md, lib/LIBRARY.INDEX.md revisions 1.08 to 1.14, test-suites/test-library-inventory.sh
Long suites run occasionally, fast checks always.kiro/steering/validation-cadence.md
Standing converter decisions.kiro/steering/java-converter-lib.md, java-to-sleela-conversion.md

3. What is left

ItemWhere it showsOwner areaNext step
Statics written as instance methods in jdk-28 units (Float.isNaN, Objects.checkIndex, Arrays.copyOf, Character.charCount)largest check-error group on the JDK sample (94 of 475)library (lib/java/jdk-28)regenerate those units with static
Nested type files do not resolve (Outer.Inner.sleela)separate-file conversions; a nested type resolves only inside its bundled documentloader (impl/frontend/driver.cpp)resolve the dotted unit name
An Any value is not assignable to a typed variable or return without a castmethod 'stream' returns Any, expected Streamlanguage (javac-style checked cast) or converter (insert casts)decide where the inserted cast lives
Operands of unknown type (no generics inference)arithmetic on generic parameters refused or unknownboth converterscollect generic signatures, substitute type arguments
Lambdas with 3 or more parametersstub reason 1lib/java/converter, SLJavaLambdaTable.call takes two argumentswiden call or pass an argument array
Lambdas that capture an array or take an array parameterstub reason 1language: a cast to an array type does not compileallow (T[]) x checked casts
Method references without a known target, or Type::m of another classstub reason 2lib/java/convertertarget typing from library signatures; static versus unbound from the model
Lambda ids are per documentseveral converted documents with lambdas in one program clash on SLJavaLambdaTablelib/java/converterone table per program, or ids folded with a document number
Anonymous and local classesstub reasons 3, 14 in lib/java/converterlib/java/converter (sleelactl lowers them)the JConvOuter mechanism plus captured locals
outer.new Inner(), a static method of an inner class reaching an outer membernot lowered by either converterboth converterspass the explicit outer reference
A lambda or anonymous class inside another generated classrefused by sleelactlsleelactlcapture through the enclosing generated class
Switch expressions, multi-label and arrow casesstub reason 5 in lib/java/converterlib/java/converter (sleelactl lowers them)hoist to a temporary as sleelactl does
case Type t -> patterns, record patterns, sealed exhaustivenessrefused / stubbedboth convertersper-arm cast declaration
Pattern instanceof outside the two lowered shapesstub reason 6lib/java/converterthe sleelactl form (declare, then assign in the test)
varstub reason 8lib/java/converterinfer from the initializer through the typed pass
Class literals X.class, getClass().getName()stub reason 9; a user exception prints the library class namelanguage / librarya runtime class-name query
enum declarations in SLeeLa source (43.5); enums nested in a class, this(...) in an enum constructorlowered by both converters except those two forms, refused by sleelactllanguage / sleelactlโ€”
static { } blocks; Object.equals/hashCode/getClass on a user type (enums included)refused by sleelactl (init-block, object-method)sleelactl / libraryguarded static init; identity equals and hash
One simple name for several nested types in a file (nested-ambiguous)first refusal of 131 of the 464 JDK files that fail closed (2026-11-13), the largest groupsleelactlresolve a bare nested name by scope (innermost enclosing type first)
Converted is not checkeda split-layout file names sibling nested types a standalone sleela check does not linkloader / sleelactlmeasure check over the tree; bundle or resolve Outer__Inner files
String static members in lib/java/converterstub reason 22lib/java/converterthe JavaFormat route sleelactl uses
System.out.print without a newlinestub reason 23language / library (print always adds a newline)a no-newline print built-in
Files with non-ASCII bytesskipped by lib/java/converter (12 of 15,020 JDK files)VM read returns 4,095-byte plain String piecesa byte-level read
Double % by zeroa fault in SLeeLa, NaN in JavaVM (37.5)return NaN for the double case
Null dereference, stack overflowstill fatal, not NullPointerException / StackOverflowErrorVM (37.5)extend the fault kinds
Plain int is 64-bitconverted code is exact (through JavaOperands); hand-written SLeeLa is not Javalanguage decisionkeep, or a Java-int mode
synchronized, volatile, Java memory modelconverted single-threaded onlylanguage / VMreal monitors
Stores into int array elements do not wrap in the VMa[i] = x + y keeps a 64-bit value until read through a wrapVM / converterwrap on store into int32[]
print of a double shows 9, Java 9.0handled by the converters (Double.toString), not by the languageconvertersโ€”
java_equivalence model not called by semantic analysis; java_flow.cpp, java_exceptions.cpp not linked43.5compilerwire them or retire them
No Java bytecode pathsleela run Foo.java hands the file to a JVMout of scope todayโ€”
Streamsfused-loop lowering designed, not builtconvertersLOWERING.md section 3
native methodsno Java bodynonenot convertible