Home /Modules/java/JAVA.SPEC.md

JAVA.SPEC.md

lib/java/JAVA.SPEC.md · 315 line(s) · markdown

Java Specific Section of the Overall SLeeLa Specification

Status: normative for the Java tier. Revision 1.0, 2026-11-13. Owner: lib/java (this directory) and the converter sleelactl/convert.

The summary ledger (principles, everything converted, everything left) is CONVERSION.PRINCIPLES.md.

1. Scope and the standing rule

The SLeeLa language is specified in SLEELA.syntax. Everything that exists only because a program is written in Java is specified here, in the Java tier, and not in the language specification.

Standing rule. A Java improvement is made in the Java tier:

It is not made in the SLeeLa compiler (impl/frontend), the VM (impl/core) or the runtime. Where the tier needs something the language does not have, the converter lowers the Java construct to constructs the language already has (the principle of lib/java/jdk-28/LOWERING.md); it does not add syntax or opcodes.

Relation to the language specification. Sections 44, 45 and 46 of SLEELA.syntax (syntax 3.1 and 3.1 (also written 3.01): character literal, array initializer, labeled statements, finally on abrupt exit, a.length, multi-dimensional arrays, char as text) are language features that the Java tier uses. They were added to the language before this rule and stay there. Nothing new is added to the language by the Java tier. SLEELA.syntax section 43 (Java support, spark) and 38.4 (the Java container) are unchanged, except two language and VM changes made the same day at the owner's request, before or alongside this rule: 43.7 (implemented interfaces are runtime supertypes; a method call on an Any value dispatches at run time) and 37.5 (MIN / -1 without SIGFPE; inside a try, integer division by zero, an array index out of range and a failed cast are thrown, as ArithmeticException, ArrayIndexOutOfBoundsException, ClassCastException through lib/java/support/SLJavaFaults). The tier uses them; they are general language behavior.

1.1 The Java handler module (compiler boundary)

The few places where the SLeeLa compiler must act on a Java-authored or Java-referencing document are not compiler logic. They are the Java handler, impl/frontend/java/java_handler.cpp, loaded through the neutral interface impl/frontend/language_handler.h:

HookJava behaviour provided
documentMarkersthe spark Preonem marker, minimum #sleela 3.0 (SLEELA.syntax 43)
resolveReferencejava.lang.Throwable resolves to the /lib class Throwable; a local class cannot impersonate it
eraseSignatureTypetype variables and package-qualified types erase to Any; java.lang.String to String
stringMethodLibraryJavaStringMethods provides methods on a String receiver
faultFunction / libraryNeedsSLJavaFaults builds the exception a VM fault throws inside a try; the driver seeds it for a Java-style document that uses try
validateProgramJava compatibility metadata checks
filterLibraryCandidatestier selection among library units with the same simple name: real source beats reference files, java/jdk-28 beats docs/api, import java.jdk-28; selects the tier, JDK 28 clashes (java.util.List vs java.awt.List) rank by longest import root, module, package, depth
runHostsleela run of .java, .jar, --class-path/-cp/--class on an external JVM (java/java_host.cpp, linked into sleela and sleelvac only)

The compiler core knows only the interface. Removing the handler from FE_SRC in impl/Makefile removes Java support and changes nothing else. A Java improvement that needs a compiler hook adds a neutral hook to LanguageHandler and implements it in the handler, never a Java branch in parser.cpp, semantic.cpp, compiler.cpp, the VM or the runtime. Review, inventory and the staged plan (the javaString* builtins and OP_JSTR_* VM string kind are the remaining open item): impl/frontend/COMPILER-JAVA-REVIEW.md.

2. The Java tier

PartWhereRole
Java type unitslib/java/jdk-25, lib/java/jdk-28one SLeeLa file per public JDK type
Operand lawslib/java/JavaOperands.sleela32-bit int, narrowing, shifts, division corners
Floating pointlib/java/JavaFloat.sleelabinary32 (float) held in a double and rounded after every operation
Text formattinglib/java/JavaFormat.sleelaString.format conversions, String.join
Text unitslib/java/jdk-25/implementations/.../JavaText, JavaStringMethodsUTF-16 text, String methods
Support classeslib/java/supportlambdas table, beans, properties, bit helpers
Conversion lawsimpl/subjects/conversion/conversion.modeltypes, operators, casts, string conversion, result types
Convertersleelactl/convert (java-convert)Java source to SLeeLa source
Second converterlib/java/convertera converter written in SLeeLa; same laws, same model

Loading. A program that imports java.jdk-N has the tier's classes resolved by name from /lib. Converted output carries import java.jdk-N; and material; and declares #sleela 3.1. The tier is not built into sleela: removing lib/java removes Java support and leaves the language intact.

3. The conversion contract

  1. Functional equivalence is the goal. A converted program, run on the SLeeLa VM, produces the same observable behavior (output, exceptions, results) as the Java program on a JDK.
  2. Fail closed. A construct the tier cannot convert equivalently is refused with file:line:col [construct] reason. A file with any refused member writes no output.
  3. Proof by difference. Every supported construct has a program in sleelactl/convert/tests/java/ whose output must be byte-identical between java and the converted program (tests/javaconv_differential_test.sh). Every refusal has a program in tests/reject/.
  4. No claim beyond the report. CONVERSION-REPORT.md of a run is the status of that run.

4. Lowering catalogue

Each entry is a Java construct, the SLeeLa it becomes, and the proof test.

4.1 Integer arithmetic (JLS 4.2, 5, 15.17 to 15.24)

int operations wrap at 32 bits through JavaOperands (addInt, mulInt, shlInt, ...); byte, short, char narrow on store and cast; integer division by zero throws ArithmeticException; long is native; double is native. Rows: binop, unop, cast, compound, incr of the model. Test: Operands.

4.2 Floating point

4.3 Characters

A char literal is its integer code (typed char). (int) and (long) casts of a char are real casts, because a value of static type char is shown as text. A char shown as text in a Java String context goes through tostr char. Tests: Strings, Operands.

4.4 Strings

4.5 Control flow

4.6 Expressions

4.7 Classes

4.8 Arrays

One-dimensional arrays, multi-dimensional creation new T[a][b], jagged new T[a][], nested initializers, a.length (as arrayLength(a)), char[] and float[] (as double[]). Language limit: 4096 live arrays, and each row of a grid is one. Test: Grid.

Run-time checks. An out-of-range index (read, write, compound store) is thrown by the VM inside a try as ArrayIndexOutOfBoundsException("Index i out of bounds for length n") (SLEELA.syntax 37.5, lib/java/support/SLJavaFaults); the converter adds nothing. A negative array size is wrapped as JavaChecks.size(n) (non-constant sizes only) and throws NegativeArraySizeException with the size as its message; --unchecked-sizes omits the wrapper. Test: Bounds. Open: null dereference and stack overflow remain fatal.

4.9 Concurrency

synchronized (method and block) and volatile order accesses between threads. The tier converts a program as single-threaded: with --single-thread they become plain (a synchronized block is its body), without it they are refused ([synchronized], [volatile]). Equivalence for a program that really uses several threads is not claimed. Test: Sync.

4.10 Not convertible

native methods (no Java body). Everything else refused is listed in section 5.

5. Open items (refused today)

This table is the status of sleelactl java-convert. The second converter, lib/java/converter (per-member stubs, not whole-file refusal), lowers lambdas and method references to (id, env) (0.6.0) and inner classes with an slOuter field (0.7.0); see its README.

ConstructWhyPlan
Operands of unknown typeno generics inference: generic parameters are untyped, so arithmetic on them is refused (this is what blocks most JDK lambdas and collections code)collect generic signatures and substitute type arguments
A lambda or method reference whose target is a JDK interface not in the collected tree and not in the seeded listthe abstract method is unknowncollect the JDK interfaces (convert the JDK tree)
Lambda or anonymous class inside another generated classnested capture chainscapture through the enclosing generated class
outer.new Inner(), local classesrare formshoist local classes like nested ones
case Type t -> patterns, record patterns, sealed exhaustivenessbinding scope in a switchper-arm cast declaration
Records: equals/hashCode for double/float/reference componentsJava's rules for thoseDouble.compare and Objects.equals lowering
Boxed declared types (Integer i)boxed values are primitives in SLeeLa; the declaration names a classdeclare as Any, unbox at each use, keep null
An object held in an erased generic shown as textits run-time kind (object or primitive) is unknown at conversiona run-time text helper that recognises primitives
A nested user exception in Throwable.toString()prints Outer__Inner, Java Outer$Innera binary-name table for hoisted types
static { } initializer blocksclass initialization runs on first use (JLS 12.4)a guarded static init method called on first access
Object.equals/hashCode/getClass on a type that does not declare them (enums included)SLeeLa has no root object methodsidentity equals, an identity hash, a runtime class name
String.format with a non-literal format, %e, argument indexesruntime format parsinga runtime formatter in JavaFormat
synchronized/volatile in a multi-threaded programmemory modelreal monitors, or keep the single-thread policy
nativeno bodynone

6. How to extend the tier

  1. Write the Java program that exercises the construct in sleelactl/convert/tests/java/.
  2. Implement the lowering in the converter and, if it needs runtime support, in lib/java as SLeeLa code. Do not touch impl/frontend or impl/core.
  3. Run bash tests/javaconv_differential_test.sh; the output must be identical to the JDK.
  4. Update this document (section 4 and 5), sleelactl/convert/README.md and the steering note .kiro/steering/java-to-sleela-conversion.md.
  5. If a library class under lib was added: regenerate lib/LIBRARY.SYMBOLS.md, the inventory test counts, lib/LIBRARY.INDEX.md and security/sha256-manifest.json.

7. Verification

bash tests/javaconv_differential_test.sh runs 22 programs on a JDK and on the converted SLeeLa: Anon, Basics, Bounds, Control, Enums, Flow, Floats, Formats, Functional, Grid, Init, Nested, ObjectText, Operands, Records, Refs, Resources, Shapes, Strings, Switches, Sync, Varargs, and 9 refusal programs under tests/reject that must be refused (a lambda argument to an unknown method, String identity comparison, a synchronized block without --single-thread, an operand of unknown type, an Object method a user type does not declare, called with and without a receiver, a qualified nested superclass that shares its simple name with the class, a boxed declared type, and a user object without toString() shown as text). The workflow .github/workflows/java-convert.yml runs the suite in CI on every change to the converter, the model, the Java tier or the compiler/VM. A last check converts a file, makes it fail closed, converts again and requires that the earlier output is gone (the converter keeps the list of what it wrote in .javaconv-emitted). bash examples/java/differential/run-differential.sh is the older hand-converted suite.

Whole-tree status (2026-11-13, JDK 25.0.2 java.base: java/lang, java/util, java/math, java/text, 884 files): 420 of 884 files (496 SLeeLa files); 426 with --single-thread; first refusals led by nested-ambiguous (131 files), nested (67) and untyped (57). Full status: JAVA.CONVERSION.STATUS.md. The report of the run is the status; see sleelactl/convert/README.md.