Merge FR-004 Java Layer 2: metaobjects-render module (full prompt-construction pillar complete)

New module under server/java/render/ — Mustache-driven render engine + Verify:
- Provider interface + 3 impls (InMemoryProvider, FilesystemProvider with
  path-traversal guard, ClasspathResourceProvider)
- Format-keyed Escapers: text/html/xml/csv/json/markdown/spreadsheet, with
  OWASP CSV cell-injection guard (=,+,-,@,tab,CR prefix → '\'')
- Renderer pipeline: partial pre-expansion via regex (cycle-guarded,
  MAX_DEPTH=32) → Mustache.java compile → per-variable escape via
  DefaultMustacheFactory.encode() hook (matches C#/TS — final-output
  escape would corrupt CSV literals)
- Verify: 1:1 port of C# Verify.cs — token-walking drift detection over
  template body + payload field tree, recurses through partials, checks
  required slots + required output tags

Within-Java snapshot test gates stability (RenderSnapshotTest, 4 fixtures).
Cross-port comparison runs report-only (RenderCrossPortReportTest) and prints
ZERO drift — Java output is byte-identical to TS baseline for all 4 fixtures
in fixtures/render-conformance/ (render-csv-injection, render-example-email,
render-example-prompt, render-example-spreadsheet).

48 new tests in metaobjects-render module. Full Java reactor BUILD SUCCESS.
Mustache library reuses Spullara mustache.java:0.9.14 (already in reactor
via codegen-mustache — no second lib).

**FR-004 Java port is complete** — both Layer 1 (template.* metatype) and
Layer 2 (render engine + verify) shipped. Java now has the prompt-construction
pillar parity with TS + C#. Unblocks the planned metadata-ktx Kotlin facade.

Author: dmealing

server/java/pom.xml

@@ -36,6 +36,7 @@
     <module>metadata</module>
     <module>codegen-base</module>
     <module>codegen-mustache</module>
+    <module>render</module>
     <module>codegen-plantuml</module>
     <module>maven-plugin</module>
     <module>core-spring</module>

server/java/render/KNOWN_DRIFT.md

@@ -0,0 +1,18 @@
+# Known cross-port render drift (Java vs TS/C#)
+
+This file documents intentional or known whitespace/escaping drift between
+Java's render output and the TS-baseline `fixtures/render-conformance/` corpus.
+
+**Within-Java stability** is the build gate (see `RenderSnapshotTest`); this
+file tracks where Java *intentionally* diverges from TS so we don't get
+surprised when reading `RenderCrossPortReportTest` output.
+
+| Fixture | Drift type | Notes |
+|---|---|---|
+| (none) | — | Java's render output is byte-identical to the TS baseline for all 4 fixtures currently in the corpus (render-csv-injection, render-example-email, render-example-prompt, render-example-spreadsheet). |
+
+When you find a drift in `RenderCrossPortReportTest` output:
+1. Decide if it's worth fixing (most aren't — see FR-004 Java spec §6.4).
+2. If documenting: add a row above with fixture name + diff summary.
+3. If fixing: adjust `Renderer` / `Escapers` and verify both snapshot test AND
+   cross-port report come into agreement.

server/java/render/pom.xml

@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>com.metaobjects</groupId>
+        <artifactId>metaobjects</artifactId>
+        <version>7.0.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>metaobjects-render</artifactId>
+    <packaging>bundle</packaging>
+
+    <name>MetaObjects :: Render</name>
+    <description>Mustache-driven render engine + verify for the template.* metatype (FR-004).</description>
+
+    <dependencies>
+        <!-- Mustache Template Engine -->
+        <dependency>
+            <groupId>com.github.spullara.mustache.java</groupId>
+            <artifactId>compiler</artifactId>
+            <version>0.9.14</version>
+        </dependency>
+
+        <!-- Test Dependencies -->
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+            <scope>test</scope>
+        </dependency>
+
+        <!-- Inherited from parent POM: SLF4J, JUnit, Logback.
+             No metaobjects-metadata dependency — Verify is zero-core-dependency by design
+             (callers pass a plain PayloadField tree). -->
+    </dependencies>
+
+    <build>
+        <plugins>
+            <!-- Maven Bundle Plugin for OSGi -->
+            <plugin>
+                <groupId>org.apache.felix</groupId>
+                <artifactId>maven-bundle-plugin</artifactId>
+                <extensions>true</extensions>
+                <configuration>
+                    <instructions>
+                        <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
+                        <Bundle-Version>${project.version}</Bundle-Version>
+                        <Export-Package>
+                            com.metaobjects.render.*
+                        </Export-Package>
+                        <Import-Package>
+                            com.github.mustachejava.*,
+                            *
+                        </Import-Package>
+                    </instructions>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>

server/java/render/src/main/java/com/metaobjects/render/ClasspathResourceProvider.java

@@ -0,0 +1,44 @@
+package com.metaobjects.render;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.Objects;
+
+/**
+ * Resolves template references from classpath resources, e.g.
+ * {@code new ClasspathResourceProvider(cl, "prompts/").resolve("lobby/welcome")}
+ * reads {@code classpath:prompts/lobby/welcome.mustache}.
+ *
+ * <p>Path traversal ({@code ..}) is rejected by returning {@code null}.
+ */
+public final class ClasspathResourceProvider implements Provider {
+
+    private final ClassLoader classLoader;
+    private final String basePrefix;
+    private final String extension;
+
+    public ClasspathResourceProvider(ClassLoader classLoader, String basePrefix) {
+        this(classLoader, basePrefix, ".mustache");
+    }
+
+    public ClasspathResourceProvider(ClassLoader classLoader, String basePrefix, String extension) {
+        this.classLoader = Objects.requireNonNull(classLoader, "classLoader");
+        this.basePrefix = basePrefix == null ? "" : basePrefix;
+        this.extension = Objects.requireNonNull(extension, "extension");
+    }
+
+    @Override
+    public String resolve(String reference) {
+        if (reference == null || reference.isEmpty()) return null;
+        if (reference.contains("..")) return null;
+
+        String resourcePath = basePrefix + reference + extension;
+        try (InputStream in = classLoader.getResourceAsStream(resourcePath)) {
+            if (in == null) return null;
+            return new String(in.readAllBytes(), StandardCharsets.UTF_8);
+        } catch (IOException e) {
+            return null;
+        }
+    }
+}

server/java/render/src/main/java/com/metaobjects/render/Escapers.java

@@ -0,0 +1,115 @@
+package com.metaobjects.render;
+
+import java.util.Map;
+import java.util.function.UnaryOperator;
+
+/**
+ * Format-keyed escaper registry for the render engine (FR-004).
+ *
+ * <p>Tier-1 invariant: escaping behavior per format is character-by-character
+ * identical to TS ({@code server/typescript/packages/render/src/escapers.ts})
+ * and C# ({@code server/csharp/MetaObjects.Render/Escapers.cs}).
+ *
+ * <p>{@code {{var}}} substitutions in a Mustache template are escaped per
+ * format; {@code {{{var}}}} bypasses escaping (Mustache's "triple-stache"
+ * raw form is preserved by the {@link Renderer}).
+ */
+public final class Escapers {
+
+    private Escapers() {}
+
+    public static final String FORMAT_TEXT        = "text";
+    public static final String FORMAT_HTML        = "html";
+    public static final String FORMAT_XML         = "xml";
+    public static final String FORMAT_CSV         = "csv";
+    public static final String FORMAT_JSON        = "json";
+    public static final String FORMAT_MARKDOWN    = "markdown";
+    public static final String FORMAT_SPREADSHEET = "spreadsheet";
+
+    private static final Map<String, UnaryOperator<String>> REGISTRY = Map.of(
+        FORMAT_TEXT,        UnaryOperator.identity(),
+        FORMAT_MARKDOWN,    UnaryOperator.identity(),
+        FORMAT_HTML,        Escapers::escapeXml,  // HTML uses XML entity set per FR-004 spec
+        FORMAT_XML,         Escapers::escapeXml,
+        FORMAT_CSV,         Escapers::escapeCsv,
+        // XML-escape the content first, then guard — the guard's leading quote stays
+        // a literal apostrophe (which tells Excel "treat as text"), not &#39;.
+        FORMAT_SPREADSHEET, s -> injectionGuard(escapeXml(s)),
+        FORMAT_JSON,        Escapers::escapeJson
+    );
+
+    /**
+     * Escape {@code input} according to the given format. Unknown formats throw
+     * — the Renderer defaults to {@code "text"} when no format is supplied.
+     */
+    public static String escape(String format, String input) {
+        UnaryOperator<String> fn = REGISTRY.get(format);
+        if (fn == null) {
+            throw new IllegalArgumentException("unknown render format \"" + format + "\"");
+        }
+        return fn.apply(input);
+    }
+
+    static String escapeXml(String s) {
+        StringBuilder sb = new StringBuilder(s.length() + 8);
+        for (int i = 0; i < s.length(); i++) {
+            char c = s.charAt(i);
+            switch (c) {
+                case '&'  -> sb.append("&amp;");
+                case '<'  -> sb.append("&lt;");
+                case '>'  -> sb.append("&gt;");
+                case '"'  -> sb.append("&quot;");
+                case '\'' -> sb.append("&#39;");
+                default   -> sb.append(c);
+            }
+        }
+        return sb.toString();
+    }
+
+    // OWASP CSV/Excel formula-injection guard: neutralize a leading active char.
+    static String injectionGuard(String s) {
+        if (s.isEmpty()) return s;
+        char first = s.charAt(0);
+        if (first == '=' || first == '+' || first == '-' || first == '@'
+                || first == '\t' || first == '\r') {
+            return "'" + s;
+        }
+        return s;
+    }
+
+    static String escapeCsv(String s) {
+        String guarded = injectionGuard(s);
+        boolean needsQuote = guarded.indexOf(',') >= 0
+            || guarded.indexOf('"') >= 0
+            || guarded.indexOf('\n') >= 0
+            || guarded.indexOf('\r') >= 0;
+        if (!needsQuote) return guarded;
+        return "\"" + guarded.replace("\"", "\"\"") + "\"";
+    }
+
+    // Mirrors JS JSON.stringify(s).slice(1, -1): escape ", \, and control chars;
+    // nothing else (no HTML-safety escaping of < > &).
+    static String escapeJson(String s) {
+        StringBuilder sb = new StringBuilder(s.length() + 4);
+        for (int i = 0; i < s.length(); i++) {
+            char c = s.charAt(i);
+            switch (c) {
+                case '"'  -> sb.append("\\\"");
+                case '\\' -> sb.append("\\\\");
+                case '\b' -> sb.append("\\b");
+                case '\f' -> sb.append("\\f");
+                case '\n' -> sb.append("\\n");
+                case '\r' -> sb.append("\\r");
+                case '\t' -> sb.append("\\t");
+                default -> {
+                    if (c < 0x20) {
+                        sb.append(String.format("\\u%04x", (int) c));
+                    } else {
+                        sb.append(c);
+                    }
+                }
+            }
+        }
+        return sb.toString();
+    }
+}

server/java/render/src/main/java/com/metaobjects/render/FilesystemProvider.java

@@ -0,0 +1,49 @@
+package com.metaobjects.render;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Objects;
+
+/**
+ * Resolves template references from a filesystem root, e.g.
+ * {@code resolve("lobby/welcome")} reads {@code <root>/lobby/welcome.mustache}.
+ *
+ * <p>Path traversal (segments containing {@code ..}) is rejected at resolve
+ * time: returns {@code null} rather than throwing, so callers see a clean
+ * "unresolved" outcome. A second belt-and-suspenders check confirms the
+ * normalized candidate path remains under {@code root}.
+ *
+ * <p>Mirrors {@code server/csharp/MetaObjects.Render/FilesystemProvider.cs}.
+ */
+public final class FilesystemProvider implements Provider {
+
+    private final Path root;
+    private final String extension;
+
+    public FilesystemProvider(Path root) {
+        this(root, ".mustache");
+    }
+
+    public FilesystemProvider(Path root, String extension) {
+        this.root = Objects.requireNonNull(root, "root").toAbsolutePath().normalize();
+        this.extension = Objects.requireNonNull(extension, "extension");
+    }
+
+    @Override
+    public String resolve(String reference) {
+        if (reference == null || reference.isEmpty()) return null;
+        if (reference.contains("..")) return null;  // path-traversal guard
+
+        Path candidate = root.resolve(reference + extension).normalize();
+        if (!candidate.startsWith(root)) return null;   // belt-and-suspenders
+        if (!Files.isRegularFile(candidate)) return null;
+
+        try {
+            return Files.readString(candidate, StandardCharsets.UTF_8);
+        } catch (IOException e) {
+            return null;
+        }
+    }
+}

server/java/render/src/main/java/com/metaobjects/render/InMemoryProvider.java

@@ -0,0 +1,23 @@
+package com.metaobjects.render;
+
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * Deterministic, in-memory {@link Provider} — the conformance + unit-test
+ * provider. Returns the mapped text for a known reference, or {@code null}
+ * when the reference is absent.
+ */
+public final class InMemoryProvider implements Provider {
+
+    private final Map<String, String> map;
+
+    public InMemoryProvider(Map<String, String> map) {
+        this.map = Objects.requireNonNull(map, "map");
+    }
+
+    @Override
+    public String resolve(String reference) {
+        return map.get(reference);
+    }
+}

server/java/render/src/main/java/com/metaobjects/render/PayloadField.java

@@ -0,0 +1,33 @@
+package com.metaobjects.render;
+
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * A field node in a template-verification payload tree — a plain mirror of
+ * an {@code object.value} view-object's field walk, decoupled from the
+ * metadata package so the render engine remains a zero-core-dependency module.
+ *
+ * <p>{@code fields} present (non-null) → a context-pushing field (object or
+ * array-of-object). {@code fields} null → a scalar field (string / number /
+ * boolean / scalar array).
+ *
+ * <p>Mirrors {@code server/csharp/MetaObjects.Render/Verify.cs}
+ * {@code PayloadField} record.
+ */
+public record PayloadField(String name, List<PayloadField> fields) {
+
+    public PayloadField {
+        Objects.requireNonNull(name, "name");
+    }
+
+    /** Convenience factory: a scalar field with no nested children. */
+    public static PayloadField scalar(String name) {
+        return new PayloadField(name, null);
+    }
+
+    /** Convenience factory: a context-pushing object/array-of-object field. */
+    public static PayloadField object(String name, List<PayloadField> children) {
+        return new PayloadField(name, List.copyOf(children));
+    }
+}

server/java/render/src/main/java/com/metaobjects/render/Provider.java

@@ -0,0 +1,23 @@
+package com.metaobjects.render;
+
+/**
+ * Resolves a logical template reference (typically {@code group/source}) to
+ * template text. The render engine never does I/O directly — it delegates
+ * resolution to the injected {@code Provider}, so a fixed provider makes
+ * {@link Renderer#render(RenderRequest)} deterministic.
+ *
+ * <p>Returns {@code null} when the reference can't be resolved. Render-time
+ * code distinguishes "no provider supplied" from "provider returned null" —
+ * the latter triggers {@code ERR_PARTIAL_UNRESOLVED} for partials.
+ *
+ * <p>Ported from {@code server/typescript/packages/render/src/provider.ts}
+ * and {@code server/csharp/MetaObjects.Render/Provider.cs}.
+ */
+public interface Provider {
+
+    /**
+     * Resolve a logical reference to its template text, or {@code null} when
+     * the reference doesn't exist.
+     */
+    String resolve(String reference);
+}