feat(emit-java): add a dependency-free Java 17 emitter target (#858) (#1069)

* chore(#858): scaffold draft PR for the Java emitter target

* feat(emit-java): backend skeleton, runtime, provider registration

* feat(emit-java): Java naming + type mapping

* feat(emit-java): expression translator

* feat(emit-java): value objects + generated IDs as validating records

* feat(emit-java): smart enums as Java enums

* feat(emit-java): entities + aggregates as invariant-guarded classes

* feat(emit-java): events, commands, repositories

* test(emit-java): javac conformance harness + snapshots

* docs(emit-java): document the Java target across README, USER-STORIES, website

* fix(emit-java): compile clean under javac 17 (cross-context types, Range, value-object arithmetic)

Compiling the emitted Java with a real JDK 17 surfaced three gaps the string/snapshot
tests missed (the billing + pizzeria starter templates did not compile):

- Cross-context type references now package-qualify (`<base>.<ownerContext>.Type`),
  mirroring how the Rust emitter qualifies `crate::<module>::Type`; local types stay bare.
- A `koine.runtime.Range<T>` record is emitted (Koine `Range<T>` mapped to it but it never
  existed), alongside `DomainException`.
- Value-object arithmetic lowers to methods (Java has no operator overloading): demand-driven
  `plus`/`minus`/`times`/`dividedBy` on value objects via OperatorNeedsAnalyzer, and the
  translator lowers VO `+`/`-`/`*`/`/` and `sum`-of-VO to them instead of raw operators.

Both starter templates now compile with `javac --release 17` (0 errors); a new conformance
fixture exercises all three categories.

* fix(emit-java): address code-review findings (invalid Java from edge-case models)

Six bugs a real javac 17 rejects, found in review (verified fixed under JDK 17):
- Decimal `/` now passes `MathContext.DECIMAL128` (bare BigDecimal.divide throws
  ArithmeticException on non-terminating quotients).
- A negated Decimal literal folds the sign into the string (`new BigDecimal("-273.15")`)
  instead of `-new BigDecimal(...)` (no unary minus on BigDecimal).
- Built-in member-ops (count/length/trim/…) only fire when the receiver actually supports
  them, so a domain member named `count`/`length` no longer emits a phantom `.size()`.
- A large positive int literal in a BigDecimal operand keeps its `L` suffix.
- JavaNaming escapes the record-component-illegal Object method names (hashCode, toString,
  notify, wait, clone, finalize, getClass, notifyAll).
- Equality on an optional (`Int?`/`Bool?`) routes through Objects.equals, not raw `==`.

Adds a javac-17 regression conformance fixture covering all six.

* feat(studio): expose the Java emit target in the IDE

Add Java to the offline `BUILTIN_EMIT_TARGETS` fallback (the live list is already
registry-seeded) so the output-language picker, generate-project wizard, and assistant
compile-tool all offer it, and highlight emitted `.java` via the bundled clike CodeMirror mode.

* docs(emit-java): surface Java on the website roadmap, reference overview, and landing page

* fix(emit-java): root Koine.Emit.Java as a wasm trimmer assembly

Author: phmatray

Koine.slnx

@@ -18,6 +18,7 @@
     <Project Path="src/Koine.Emit.CSharp/Koine.Emit.CSharp.csproj" />
     <Project Path="src/Koine.Emit.Docs/Koine.Emit.Docs.csproj" />
     <Project Path="src/Koine.Emit.Glossary/Koine.Emit.Glossary.csproj" />
+    <Project Path="src/Koine.Emit.Java/Koine.Emit.Java.csproj" />
     <Project Path="src/Koine.Emit.OpenApi/Koine.Emit.OpenApi.csproj" />
     <Project Path="src/Koine.Emit.Php/Koine.Emit.Php.csproj" />
     <Project Path="src/Koine.Emit.Python/Koine.Emit.Python.csproj" />

README.md

@@ -8,7 +8,7 @@
 [![Documentation](https://img.shields.io/badge/docs-koine-3245b8)](https://atypical-consulting.github.io/Koine/)
 [![.NET](https://img.shields.io/badge/.NET-10-512BD4)](https://dotnet.microsoft.com/)
 [![Tests](https://img.shields.io/badge/tests-1900%2B%20passing-2ea44f)](tests/)
-![Target](https://img.shields.io/badge/emits-C%23%20%C2%B7%20TypeScript%20%C2%B7%20Python%20%C2%B7%20PHP%20%C2%B7%20Rust%20%C2%B7%20docs%20%C2%B7%20AsyncAPI%20%C2%B7%20OpenAPI-178600)
+![Target](https://img.shields.io/badge/emits-C%23%20%C2%B7%20TypeScript%20%C2%B7%20Python%20%C2%B7%20PHP%20%C2%B7%20Rust%20%C2%B7%20Java%20%C2%B7%20docs%20%C2%B7%20AsyncAPI%20%C2%B7%20OpenAPI-178600)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
 
 ## The problem
@@ -42,6 +42,12 @@ aggregates with invariant-checked behaviors, factories that mint identities, dom
 a `Vec`-friendly `DomainEvent` collection, query DTOs and read-model projections, and repositories as
 `trait`s; **multi-context** models compile end-to-end via `crate::<module>` qualification; depends only
 on `rust_decimal` for money and `regex` for `matches`, plus `uuid` when a model uses a factory), a
+**Java 17** emitter ships (`--target java` → dependency-free, stdlib-only Java 17: value objects and
+domain events as validating `record`s with compact constructors, smart enums as Java `enum`s (with
+per-constant associated data), entities and aggregates as classes with identity `equals`/`hashCode` and
+invariant-guarded behaviors, generated identities as branded `record`s minting `java.util.UUID`, domain
+events grouped under a per-context `sealed interface DomainEvent`, and repositories as `interface`s —
+one public type per `.java` file, `koine.runtime.DomainException` for invariant failures), a
 **docs** target emits living
 documentation (`--target docs` → Markdown + Mermaid diagrams) straight from the model, an
 **AsyncAPI 3.0** target emits a single event-API document (`--target asyncapi` → channels, messages,
@@ -76,7 +82,7 @@ surface below is a click away in the [live Studio](https://atypical-consulting.g
 | IDE view | What it shows |
 |----------|---------------|
 | **Editor & live diagnostics** | Your `.koi` model on the left, the emitted code on the right, with error squiggles and quick info as you type — the same parser and validator the CLI runs. |
-| **Emit-target switcher** | Flip the *same* model between **C#**, **TypeScript**, **Python**, **PHP**, and **Rust** output without leaving the page. |
+| **Emit-target switcher** | Flip the *same* model between **C#**, **TypeScript**, **Python**, **PHP**, **Rust**, and **Java** output without leaving the page. |
 | **Context-map graph** | An interactive graph of the bounded contexts and the relationships between them. |
 | **Diagram views** | Aggregates and state machines rendered as diagrams straight from the model. |
 | **Ubiquitous-language glossary** | The generated glossary of every term in the domain, kept in lock-step with the model. |
@@ -206,6 +212,9 @@ dotnet run --project src/Koine.Cli -- build templates/starters/billing/billing.k
 # Or to Rust (multi-context + CQRS — an idiomatic crate; `cargo build` proves it compiles)
 dotnet run --project src/Koine.Cli -- build templates/starters/billing/billing.koi --target rust --out ./generated_rs
 
+# Or to Java (dependency-free Java 17 — records, sealed events, invariant-guarded classes; `javac --release 17` proves it compiles)
+dotnet run --project src/Koine.Cli -- build templates/starters/billing/billing.koi --target java --out ./generated_java
+
 # Emit the opt-in C# Application layer alongside the domain (handlers, validators, query handlers, DI)
 dotnet run --project src/Koine.Cli -- build templates/starters/billing/billing.koi --target csharp --layers domain,application --out ./generated
 

USER-STORIES.md

@@ -819,7 +819,7 @@ context Sales version 3 {
 
 _BRIEF §9 and the README position TypeScript and Rust as the proof that the Ast/ + IEmitter seam is genuinely target-agnostic; today only CSharpEmitter exists and the CLI hard-rejects any non-csharp target (Program.cs). Rust in particular forces error handling to map to `Result<T,E>` instead of the exception-based DomainInvariantViolationException — the strongest test of the seam. Real projects also need to configure the existing C# emitter (namespace mapping, NodaTime mode — still a literal 'TODO: NodaTime' in CSharpTypeMapper, output layout). This is the capstone of the long-term vision, sequenced last because it benefits from a mature, stable AST._
 
-> **✅ Delivered.** R16 shipped: C# emitter configuration (R16.1), a full TypeScript emitter (R16.2), a Rust emitter (R16.3 — **Phase 1: tactical core**; remaining breadth tracked in [#173](https://github.com/Atypical-Consulting/Koine/issues/173)), and the cross-emitter conformance harness with an `Ast/`-purity guard (R16.4). The seam held: every target-specific decision lives in its `Emit/<Target>/` emitter and `Ast/` gained no error-handling or target concept — Python and PHP emitters followed the same seam. `koine init` still emits a forward-compatible `koine.config` whose `targets.*` block configures the C# emitter.
+> **✅ Delivered.** R16 shipped: C# emitter configuration (R16.1), a full TypeScript emitter (R16.2), a Rust emitter (R16.3 — **Phase 1: tactical core**; remaining breadth tracked in [#173](https://github.com/Atypical-Consulting/Koine/issues/173)), and the cross-emitter conformance harness with an `Ast/`-purity guard (R16.4). The seam held: every target-specific decision lives in its `Emit/<Target>/` emitter and `Ast/` gained no error-handling or target concept — Python, PHP, and a dependency-free **Java 17** emitter (`--target java`, Phase 1: tactical core + events/commands/repositories, [#858](https://github.com/Atypical-Consulting/Koine/issues/858)) followed the same seam. `koine init` still emits a forward-compatible `koine.config` whose `targets.*` block configures the C# emitter.
 
 ### R16.1 C# emitter configuration (namespaces, NodaTime, layout)  ·  🟡 Medium
 ✅ **Delivered** — *As an Architect, I want a structured emitter options object to map contexts to concrete namespaces, choose the Instant mapping, and control output layout, so that generated code drops into our existing project conventions.*
@@ -924,5 +924,5 @@ _With the MCP server (`src/Koine.Mcp`) an AI agent can now author a complete `.k
 - Koine Studio's shared design-system layer — the `--koi-*` design tokens, framework-free DOM/interaction primitives, and store-free presentational components — was extracted into a standalone workspace package, [`@atypical/koine-ui`](tooling/koine-ui/) (issue #905), so a second surface (the docs-site playground today, a future embed or IDE tomorrow) can reuse Koine Studio's look and interaction patterns without pulling in the whole IDE.
 - Example domains live in [`templates/`](templates/) — the single, CI-validated source of truth (issue #101). Each template is a folder of `.koi` files plus a `template.json` manifest (validated against [`templates/template.schema.json`](templates/template.schema.json)); `TemplatesValidationTests` compiles every template green, and the set powers the demo, Koine Studio's gallery, and the website playground.
 - The [`demo/`](demo/) project (`Pizzeria.Domain`) compiles the [`templates/pizzeria`](templates/pizzeria) template in place — six bounded contexts plus an external Gateway — exercising the full shipped surface, and is the natural place to validate new stories end-to-end.
-- Sequencing rationale: **R1–R4** sharpen the existing surface (expressions, optionality, diagnostics, docs) at low risk; **R5–R10** add the missing tactical behaviour (commands, events, lifecycle, factories, richer value objects, specifications/services/policies); **R11–R12** add the persistence & application abstractions; **R13–R15** unlock multi-file and strategic design; and **R16–R18** are delivered — multi-target emitters (TypeScript, Python, PHP, and Rust Phase 1) proved the `Ast/`+`IEmitter` seam is target-agnostic, the editor tooling rounded out developer experience, and the model-as-spec coverage analyzer (`koine coverage`) closed the declared-equals-emitted loop.
+- Sequencing rationale: **R1–R4** sharpen the existing surface (expressions, optionality, diagnostics, docs) at low risk; **R5–R10** add the missing tactical behaviour (commands, events, lifecycle, factories, richer value objects, specifications/services/policies); **R11–R12** add the persistence & application abstractions; **R13–R15** unlock multi-file and strategic design; and **R16–R18** are delivered — multi-target emitters (TypeScript, Python, PHP, Rust Phase 1, and Java Phase 1) proved the `Ast/`+`IEmitter` seam is target-agnostic, the editor tooling rounded out developer experience, and the model-as-spec coverage analyzer (`koine coverage`) closed the declared-equals-emitted loop.
 

src/Koine.Emit.All/BuiltInEmitterProviders.cs

@@ -7,7 +7,7 @@ namespace Koine.Compiler;
 /// truth for which targets ship with the compiler; the CLI and MCP registries both seed an
 /// <see cref="EmitterRegistry"/> from here so they can never drift (issue #69, Task 5). Each provider
 /// now lives in its own <c>Koine.Emit.&lt;Target&gt;</c> assembly (issue #861); this aggregator is the
-/// one place that references all nine, so <see cref="EmitterRegistry"/> (in the core compiler) can take
+/// one place that references them all, so <see cref="EmitterRegistry"/> (in the core compiler) can take
 /// the list as input rather than reaching down into the emitter assemblies (which would be a cycle).
 /// </summary>
 public static class BuiltInEmitterProviders
@@ -20,6 +20,7 @@ public static class BuiltInEmitterProviders
         new PythonEmitterProvider(),
         new PhpEmitterProvider(),
         new RustEmitterProvider(),
+        new JavaEmitterProvider(),
         new GlossaryEmitterProvider(),
         new DocsEmitterProvider(),
         new AsyncApiEmitterProvider(),

src/Koine.Emit.All/Koine.Emit.All.csproj

@@ -9,13 +9,13 @@
 
   <!-- The built-in emitter aggregator (issue #861): owns BuiltInEmitterProviders, the single source of
        truth for which targets ship with Koine, and references every Koine.Emit.<Target> so a host gets
-       "one reference, all nine targets" (the meta-package preserving the #69 platform experience).
+       "one reference, all targets" (the meta-package preserving the #69 platform experience).
        Assembly name (Koine.Emit.All) != namespace (Koine.Compiler.Emit) so consumer churn is
        reference-only. -->
   <PropertyGroup>
     <IsPackable>true</IsPackable>
     <PackageId>Koine.Emit.All</PackageId>
-    <Description>The Koine emitter meta-package — references every built-in Koine.Emit.&lt;Target&gt; backend (C#, TypeScript, Python, PHP, Rust, glossary, docs, AsyncAPI, OpenAPI) and exposes BuiltInEmitterProviders, the single source of truth for the targets that ship with Koine.</Description>
+    <Description>The Koine emitter meta-package — references every built-in Koine.Emit.&lt;Target&gt; backend (C#, TypeScript, Python, PHP, Rust, Java, glossary, docs, AsyncAPI, OpenAPI) and exposes BuiltInEmitterProviders, the single source of truth for the targets that ship with Koine.</Description>
     <PackageTags>ddd;domain-driven-design;dsl;compiler;code-generation;koine;emitter</PackageTags>
   </PropertyGroup>
 
@@ -32,6 +32,7 @@
     <ProjectReference Include="..\Koine.Emit.Python\Koine.Emit.Python.csproj" />
     <ProjectReference Include="..\Koine.Emit.Php\Koine.Emit.Php.csproj" />
     <ProjectReference Include="..\Koine.Emit.Rust\Koine.Emit.Rust.csproj" />
+    <ProjectReference Include="..\Koine.Emit.Java\Koine.Emit.Java.csproj" />
     <ProjectReference Include="..\Koine.Emit.Glossary\Koine.Emit.Glossary.csproj" />
     <ProjectReference Include="..\Koine.Emit.Docs\Koine.Emit.Docs.csproj" />
     <ProjectReference Include="..\Koine.Emit.AsyncApi\Koine.Emit.AsyncApi.csproj" />

src/Koine.Emit.Common/Koine.Emit.Common.csproj

@@ -39,6 +39,7 @@
     <InternalsVisibleTo Include="Koine.Emit.Python" />
     <InternalsVisibleTo Include="Koine.Emit.Php" />
     <InternalsVisibleTo Include="Koine.Emit.Rust" />
+    <InternalsVisibleTo Include="Koine.Emit.Java" />
     <InternalsVisibleTo Include="Koine.Compiler.Tests" />
   </ItemGroup>
 

src/Koine.Emit.Java/JavaEmitter.Aggregates.cs

@@ -0,0 +1,32 @@
+using Koine.Compiler.Ast;
+using Koine.Compiler.Emit;
+
+namespace Koine.Compiler;
+
+/// <summary>
+/// The aggregate slice of <see cref="JavaEmitter"/>. A Koine <c>aggregate</c> is a consistency boundary,
+/// not a Java type of its own: its nested types are emitted <b>flat</b> into the context package — each
+/// value object, entity (with its generated identity), enum, and event getting its own <c>.java</c> file
+/// via the same <see cref="EmitType"/> dispatch as a top-level declaration. The aggregate root is simply
+/// the nested entity named by <see cref="AggregateDecl.RootName"/>, so its class (invariant-guarded, with
+/// identity equality and any recorded domain events) already falls out of the entity slice. Mirrors the
+/// Rust backend's aggregate handling (recurse <c>agg.Types</c>, then the aggregate extras); the root's
+/// persistence-ignorant repository <c>interface</c> is the follow-on events/repositories task.
+/// </summary>
+public sealed partial class JavaEmitter
+{
+    /// <summary>Emits an aggregate by recursing into each nested type (one <c>.java</c> file each); the root entity is one of them.</summary>
+    private void EmitAggregate(JavaEmitContext emit, List<EmittedFile> files, string context, AggregateDecl agg)
+    {
+        foreach (TypeDecl nested in agg.Types)
+        {
+            EmitType(emit, files, context, nested);
+        }
+
+        // The aggregate root's persistence-ignorant repository interface (the Rust backend's
+        // EmitAggregateExtras analogue). The per-context DomainEvent sealed interface is emitted once per
+        // context by EmitContextExtras, not here, so a same-named event nested in the aggregate still lands
+        // in the single context-wide sum.
+        EmitAggregateExtras(emit, files, context, agg);
+    }
+}