Known limitations (main, after v0.9.0-beta.1)
This list describes the Java stage-0 implementation, not every feature proposed by the historical design kit in docs/history/design-kit/.
- The compiler is written in Java and emits Java source before invoking
javac. It does not compile itself and is not self-hosted. conform C to Jis v1-scoped: Java interfaces, or withconform C to J(field, ...) as NAMEone public, non-final, non-generic Java class per Sprig class (abstract methods witnessed, overrides matched by exact shape,NAME.m(...)calling the inherited implementation); a non-generic source class, no overloaded abstract methods, no method renaming or adapters, protected methods only through the parent view, and noself. It declares a foreign JVM contract; it does not add inheritance between Sprig classes. Open polymorphism inside Sprig is a contract class (methods without bodies) that classesconformto. For the 0.8 language a contract has no fields, is never generic, is a type and never arequiresbound, and has no default methods; a contract never conforms to another contract, there is no downcast or type test, and conformance is declared in the class's own module (no retroactive or structural conformance). These are decisions with targeted diagnostics, not gaps; a closed set of types is a variant, an open set is a contract. Generic methods witness by erasure; boxedShort/Byte/Characterparameters are not expressible because of the existing interop adapters.- Generics accept one or more parameters (
generic K, V:). Type arguments of a generic Sprig function call, class constructor or variant case with a payload are inferred from that call's arguments only: never from the expected type, the assignment target or the result, solists.first([]), a payloadless case (Option[Int].None) and a parameter that no argument mentions still need written[Type]arguments. Written arguments are all or none; partial type arguments are never guessed. There is no variance. A Java method's own type parameters are inferred only when its arguments fix every one of them exactly (not through a lambda,null, a Sprig collection or the result:Collectors.toList()still needs[Int]); Java generic types (ArrayList[String]) always write theirs, and a Sprig parameter that appears only inside a Java type such asJavaList[T]is not inferred either. Inference types a lambda or literal argument on its own first and then checks it once more against the inferred types, so generic calls nested in lambda or literal arguments are checked in time that grows with the square of their nesting depth (a 4095-node tree literal of generic constructors checks in about half a second). A type parameterThas no operators or methods, equality only underrequires T: Equatableand ordering only underrequires T: Comparable(Int, Int32, Float, Float32, Decimal, BigInt and String). User-defined capabilities are not implemented (SPR-GENERIC-CONSTRAINT). - Generic code is erased and boxed in generated Java (type parameters become
Object). Boxing/unboxing is compiler-controlled, but generic values carry no JVM-level type information at runtime. - Local/Git Sprig and Maven JVM dependencies are resolved by
sprig resolve,sprig addandsprig remove. Schema-5 locks verify graph identity, manifests, owner-relative locators and JAR/POM SHA-256. Shared project classpaths work for check/build/run/api/doctor; only explicit dependency-resolution commands use Maven networking. Apache Resolver handles effective POMs and mediation. Missing/invalid POMs fail. Package registries are Git or local directory indexes (sprig search,sprig add NAME); the repository'sregistry/takes publications by pull request, validated by CI (sprig publishwrites the entry). A hosted central registry, authentication, upload, Maven plugins and non-JAR runtime artifacts remain unsupported. See dependencies. - The bundled
std/modules cover UTF-8 files and paths, process arguments, environment and standard input, text, time and ISO dates, lists, sets, nullable values, integer math, random values, regular expressions, a JSON model with typed field access, Java collection adapters, a test helper and structured concurrency (see standard library). The first-party libraries add a small synchronous JDK HTTP client (sprig-http), a synchronous HTTP server with explicit OpenAPI metadata (sprig-web) and SQLite access (sprig-sqlite). Concurrency is the bundled@std/concurrent.spr: structured scopes over JDK 21 virtual threads, pools, channels, counters, locks and latches; there is no async/await syntax by design, nothenon a task, no scope deadline, no streaming HTTP and no hosted central package registry. The ecosystem remains intentionally small and experimental. Debugger integration and incremental compilation are absent.sprig lspserves diagnostics, hover, navigation, completion, formatting, local rename and quick fixes over the Language Server Protocol; it re-checks the whole program on each change, renames only locals and parameters, and has no code actions besides those quick fixes, which apply a diagnostic's suggested edit (see language server). The VS Code extension uses it when the compiler provides it, and runs checks, programs, tests and Java viewing as CLI commands; seeeditors/vscode/README.md. - JVM interop covers common imported classes, constructors, fields, method calls, overloads, and checked exceptions. Java arrays cross the boundary as opaque values (no source array syntax). A varargs parameter takes the trailing arguments or one opaque array of its element class; a type-variable element (
T...) stays unsupported. Concrete generic arguments are preserved for explicitType[Arg]application on imported classes and methods; intersection bounds, generic arrays and Short/Byte/Character generic arguments are rejected with structured reasons (a single recursive bound such asT extends Comparable<? super T>is accepted); a wildcard keeps its bound (reads at the upper bound, no writes through? extends, no wildcard syntax in Sprig); class bounds are validated, raw evidence never promotes to concrete arguments, and raw boundaries stay erased. Collection conversion is explicit through@std/jvm.spr; there is no implicit Java/Sprig collection conversion. Java reference results are conservatively nullable and reference parameters non-null, except where a nullability annotation says otherwise (NotNull,NonNull,Nonnull,Nullable,CheckForNull, and theNullMarked,NonNullApiandMethodsReturnNonnullByDefaultdefaults), read through reflection or, for annotations kept only in class files such asorg.jetbrains.annotations, from the class file; atoString()result is non-null. - Sprig
throwsandcatchare implemented, but their relationship to Java exception classes and top-level execution remains provisional. Checked Java exceptions follow Java's rule in one direction more: a catch nothing can reach and a declared exception the body cannot throw are both errors. Sprig shows anErroras its message; Java code that turns one into text, such asString.valueOfor a Java collection'stoString(), seessprig.runtime.SprigError: message. An error class (conform E to Error(message)) is the only way to define an error type: there is no hierarchy below it, and a function type still declaresthrows Error. - Java code that calls a generated function, such as
sprig.user.<project>.$M_main.fn$name(...)from a Fabric entry point, or makes an object with methods, starts the module's top-level statements first. Two things stay outside that: a top-level binding read from Java as a static field is not initialized by the read, and a call from a second thread does not wait for statements that are still running on the first. See Gradle integration. v0.9.0-beta.1 and earlier do not start the module: there, call$init()on the module's class once before the first function. - A project's generated classes are in
sprig.user.<project>; two projects with the same name, or names that differ only in characters a Java package name cannot hold, get the same package. - Expression
matchandifbranches hold one expression each, and neither form can be written inside parentheses, brackets or braces, where the layout adapter ignores line breaks, or be the operand of an operator. Bind the result (or a lambda that contains it) to aletfirst. - Lambdas have single-expression bodies and support arities zero through three. A lambda's
throws Errorcomes from its body; it cannot be written on the lambda, and a lambda cannot call a function that throws a checked Java exception. - Runtime numeric failures report
SPR-RUNTIME-EXCEPTIONwith the nearest statement range for local and importedInt/Int32checked arithmetic, plusdata.origin="checked-arithmetic"; the span is the statement, not a sub-expression. JVM library operations do not inherit Sprig's checked integer arithmetic rules. - Generated Java shares the JVM class-file limits. Long string literals are split automatically, but one generated method still holds at most 64 KB of bytecode: a very large literal collection or a very long top-level script can fail with
SPR-JVM-COMPILEand a hint to load the data from a file or split the code into functions. Top-level statements run once, as one JVM method that HotSpot compiles while it runs; a long script with several hot loops shares one compilation and its inlining budget, so keep hot loops in functions. - Initialization order is checked rather than inferred: top-level code may not use a binding declared below it (
SPR-NAME-FORWARD-REFERENCE), and a binding reached through a function before its initializer ran fails at runtime withdata.origin="init-order". The check is conservative and cannot prove at compile time that such a call never happens. - Floating-point operations follow Java
float/doublebehavior. The compiler does not promise cross-JVM bitwise identity for transcendental functions, numerical stability, physical units, or mathematically correct algorithms. - Compiler classes use
javac --release 21. Supported release platforms are Linux/macOS with JDK 21 and 26; Windows is an experimental, non-blocking preview; definitions are not execution evidence. The current release validation report records which exact source/archive gates ran. No production or architecture-wide portability guarantee is made. - Portable local locks carry owner-relative locators and survive relocation of the whole workspace; absolute-path declarations are not portable and need
resolveafter the target moves. The lock does not attest source bytes or symlink targets. It also does not pin bundled@stdbytes:@stdcomes from the installed SDK, whose published archive is checked separately through release checksums and extracted-archive smoke tests. Manifest semantic errors can point to line 1. Cache tree verification adds IO. The Git cache lock waits up to five seconds and then reportsSPR-DEP-GIT; the Maven cache lock waits without a timeout. Git submodules are unsupported. Offline Git builds require Git and a complete verified cache. Concurrent hostile mutation after validation is outside the cooperative cache model. sprig fmtis canonical and comment-preserving, without configuration or aggressive wrapping. See formatter for file safety and comment indentation policy. Editors can request the same formatting throughsprig lsp.sprig testis a sequential project runner for ordinary.sprprograms. It has a fixed 30-second runtime timeout and no parallel execution, watch mode, coverage, snapshots or test-function discovery. It requires a current lockfile and checks negative fixtures by diagnostic code, not message. See testing for its JSON and temporary directory contracts.tests/agent_evalprovides deterministic fixtures and scoring only. No LLM run has been performed, and no model performance is claimed.- The managed SDK installer/upgrader is supported only on Linux/macOS and targets public GitHub releases; on Windows
sprig upgraderefuses and the extracted release ZIP is replaced by hand. Published SHA-256 assets detect archive mismatch but do not provide signed provenance. Older SDKs are retained. SQLite migrations record filenames without content digests; changing an applied migration is unsupported by convention, not automatically detected. Migration SQL is trusted project code. - On Windows,
java.exereads its command line in the ANSI code page, so a command-line argument outside that code page, such as a source path or program argument with an emoji, or with Chinese text on a Western European system, is replaced before any Sprig code runs.bin\sprig.cmdforwards correctly quoted arguments unchanged, including under inherited delayed expansion; quoting forcmd.exeremains the caller's job. A Windows console shows output in its own code page, while redirected output is UTF-8 as on Linux and macOS, where output is UTF-8 whatever the locale says (a process without a locale, as in a container, used to print?for non-ASCII text).printends lines with the JVM line separator, CRLF on Windows, and JSONprogramOutputreports those bytes. - The stage-1 frontend is a subset probe, not a self-hosted compiler.
- This is the development line after v0.9.0-beta.1, an experimental Beta under Apache-2.0 (
LICENSE,NOTICE), not a production stability or numerical correctness guarantee.
Callable boundary
Source function types now use fn(A) -> R, arities 0–3. Parameters and results are invariant. A callable type may declare throws Error and nothing else: a lambda that calls a function throwing Error has that clause, a value without the clause is accepted where the clause is expected (not the reverse), and a rethrows function throws exactly what its callable arguments throw. A checked Java exception never crosses a function value; handle it inside a named function and call that from the lambda. A Java functional-interface parameter accepts a Sprig function value without a throws clause: parameters match exactly after the Java mapping, void accepts any result, and the compiler emits the adapter; abstract classes and generic interface methods are not converted. For Fn0..Fn3, concrete generic signatures preserve callable types, and so does a signature whose type arguments are type variables of the method or its class once they are bound (<T> HostTask<T> start(Fn0<T>) with start[Int](https://github.com/ColinHouse/Sprig/blob/main/docs/language/work), or a receiver with written arguments); raw, wildcard or unbound type variables are rejected. Character/Short/Byte callable slots and arbitrary parameterized Java slots are unsupported because they would require additional erased-value adapters. Nullable callable values use (fn(A) -> R)?; fn(A) -> R? means nullable result.
