feat(java): the shipped library is loadable, so the generator that consumes it has an input (#332)

The Java port shipped `LlmTraceHelperGenerator` and no way at all to load the metadata it
exists to consume: no `libraries` loader option, no embed of the canonical `library/` tree.
A JVM adopter following the documented `extends: "metaobjects::ai::LlmCallBase"` path could
not get past load. A generator shipped without its input.

What let that survive is the more useful half. Every test of that generator declares its
OWN `LlmCallBase` inline under a different package — the bypass ADR-0024 already names, "the
green tests pass only because they bypass the shipped base with bespoke entities" — so the
suite could not tell a world where the library loads from one where it does not exist.
A hand-copied base also drifts silently: the copies stay green while the shipped file moves.

Three pieces, each mirroring TS and Python rather than inventing a third shape:

- `EmbeddedLibrary` — a generated CLASS of string constants, not a `src/main/resources`
  copy. A resource can be dropped or mangled by build configuration (resource filtering,
  shading, repackaging) and the failure would surface much later as ERR_UNRESOLVED_SUPER
  against the adopter's own metadata; a class constant cannot go missing without the class
  going missing. Same rationale Python records for embedding as a source module. Emitted by
  the EXISTING `scripts/generate-embedded-library.ts` rather than a second script — two
  scripts walking one tree are two things that can drift, and an embed's whole job is to be
  byte-identical to its source.
- `LibrarySources` — on-disk-first (a checkout picks up edits to the canonical YAML with no
  regeneration), embedded fallback (every consumer of the published jar). An unrecognised
  package contributes no sources and is NOT an error here: that is the cross-port contract
  for the programmatic door, so a caller asking for a package this version does not ship can
  still load its own metadata.
- The opt-in: `MetaDataLoader.setLibraries(...)`, a `fromDirectory(..., libraries)` overload,
  `LoaderConfiguration.getLibraries()` (a `default` method — this interface is the build-tool
  seam and an implementor outside this repo must keep compiling), and a pom
  `<loader><libraries><library>ai</library></libraries>`. Libraries load BEFORE the project's
  own sources: super resolution is order-independent, so that is determinism rather than
  correctness, but a load order that differs per port is the kind of difference that only
  shows up in someone else's bug report.

An unknown name in a POM is a HARD failure listing the packages this version ships, matching
what the TS and Python config readers do. The asymmetry with the programmatic door is
deliberate and is the same one they draw: a name a human typed into a build file is a
mistake worth failing on, because skipped it resurfaces as ERR_UNRESOLVED_SUPER pointing at
the module's OWN metadata — the wrong place to send someone looking.

Gated by three things a green suite could not previously distinguish:

- `LibraryLoadTest` — the positive arm, the NEGATIVE arm (without the opt-in the same model
  must still fail, and the assertion names `LlmCallBase` rather than merely requiring
  non-empty errors: the loader wraps the real diagnostic in a "Failed to load from directory
  <path>" envelope that names nothing, and the first draft of this assertion passed on that
  envelope), and the freshness gate.
- `TraceHelperOnShippedLibraryTest` — runs the generator against the SHIPPED base, with
  ADR-0024 FIX #1 asserted BOTH directions. One direction alone is worthless: "every row key
  is a field" passes on a recorder that writes nothing, "every field is a row key" passes on
  one that writes the whole world, and only the equality says the two agree. It is also the
  claim a hand-copied base can never make, because it compares a copy against itself.
- The freshness gate was proven by BREAKING it — appending a line to `library/ai/llm-call.yaml`
  turns it red with "EmbeddedLibrary is stale for ref …; run: bun run
  scripts/generate-embedded-library.ts", then restored.

metadata + maven-plugin + codegen-spring: 202 + 34 + all green, 0 failures. C# has the same
gap and is not addressed here.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: dmealing

docs/features/cli.md

@@ -181,6 +181,24 @@ libraries: [ai]
   was registered *for* the command line while its input was unreachable *through* it
   ([#333](https://github.com/metaobjectsdev/metaobjects/issues/333)).
 
+On the JVM the same opt-in is a pom element, read by `metaobjects:generate` and
+`metaobjects:verify`:
+
+```xml
+<loader>
+  <name>my-model</name>
+  <libraries><library>ai</library></libraries>
+</loader>
+```
+
+and programmatically, `MetaDataLoader.fromDirectory(name, dir, opts, List.of("ai"))` or
+`loader.setLibraries(List.of("ai"))` before `init()`. Java had neither the option nor an
+embed until [#332](https://github.com/metaobjectsdev/metaobjects/issues/332): the port
+shipped `LlmTraceHelperGenerator` with no way to load the metadata that generator exists to
+consume, and its tests stayed green only by declaring a bespoke `LlmCallBase` inline under
+a different package — the bypass ADR-0024 already named, and the reason a port can ship a
+generator it cannot feed without anyone noticing.
+
 ## `meta gen` / `meta verify` run an advisory anti-pattern pass (Node `meta`)
 
 Both `meta verify` and a real `meta gen` write run (not `--dry-run`) end with a

scripts/generate-embedded-library.ts

@@ -47,6 +47,24 @@ const outFile = join(
   "library",
   "embedded-library.generated.ts",
 );
+// The JVM embed is emitted from THIS script rather than a second one, deliberately: two
+// scripts walking the same tree are two things that can drift, and an embed's whole job is
+// to be byte-identical to the canonical source. Python keeps its own
+// (`server/python/scripts/generate_embedded_library.py`) because it shipped first, gated
+// by its own byte-identity test.
+const javaOutFile = join(
+  repoRoot,
+  "server",
+  "java",
+  "metadata",
+  "src",
+  "main",
+  "java",
+  "com",
+  "metaobjects",
+  "library",
+  "EmbeddedLibrary.java",
+);
 
 function collect(dir: string): string[] {
   const out: string[] = [];
@@ -95,6 +113,60 @@ ${body}
 `;
 
 writeFileSync(outFile, source, "utf-8");
+
+// Java: a generated CLASS holding string constants, not a src/main/resources copy. A
+// resource can be dropped or mangled by build configuration — resource filtering, shading,
+// a repackaging plugin — and the failure would surface much later as ERR_UNRESOLVED_SUPER
+// against the adopter's own metadata, which is the wrong place to send someone looking. A
+// class constant cannot go missing without the class going missing. Same rationale Python
+// records for embedding as a source module.
+//
+// `JSON.stringify` output IS a valid Java string literal: every escape it emits (\" \\ \b
+// \f \n \r \t \uXXXX) means the same thing in both languages. That keeps this emitter free
+// of a Java-version dependency — no text blocks, so the language level can stay wherever
+// the build puts it.
+const javaEntries = entries
+  .map((e) => `        m.put(${JSON.stringify(e.ref)}, ${JSON.stringify(e.content)});`)
+  .join("\n");
+
+const javaSource = `package com.metaobjects.library;
+
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * AUTO-GENERATED by scripts/generate-embedded-library.ts — DO NOT EDIT.
+ *
+ * <p>Canonical source: the repo-root {@code library/} tree.
+ * Regenerate with {@code bun run scripts/generate-embedded-library.ts}.</p>
+ *
+ * <p>Embeds the canonical library files as string constants so they resolve wherever the
+ * on-disk {@code library/} directory is unavailable — which is every consumer of the
+ * published jar. Keys are refs: the path under {@code library/} minus the {@code .yaml}
+ * extension (e.g. {@code "ai/llm-call"}).</p>
+ *
+ * <p>{@code EmbeddedLibraryFreshnessTest} gates this file byte-for-byte against the
+ * canonical tree, so a stale embed cannot ship.</p>
+ */
+public final class EmbeddedLibrary {
+
+    private EmbeddedLibrary() {}
+
+    /** Ref to exact file contents, insertion-ordered by ref. */
+    public static final Map<String, String> CONTENT;
+
+    static {
+        Map<String, String> m = new LinkedHashMap<>();
+${javaEntries}
+        CONTENT = Collections.unmodifiableMap(m);
+    }
+}
+`;
+
+writeFileSync(javaOutFile, javaSource, "utf-8");
+
 console.log(
-  `wrote ${entries.length} embedded library file(s) to ${relative(repoRoot, outFile)}`,
+  `wrote ${entries.length} embedded library file(s) to ${relative(repoRoot, outFile)} ` +
+    `and ${relative(repoRoot, javaOutFile)}`,
 );

server/java/codegen-spring/src/test/java/com/metaobjects/generator/spring/TraceHelperOnShippedLibraryTest.java

@@ -0,0 +1,152 @@
+package com.metaobjects.generator.spring;
+
+import com.metaobjects.field.MetaField;
+import com.metaobjects.library.LibrarySources;
+import com.metaobjects.loader.InMemoryStringSource;
+import com.metaobjects.loader.LoaderOptions;
+import com.metaobjects.loader.MetaDataLoader;
+import com.metaobjects.object.MetaObject;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.TemporaryFolder;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.TreeSet;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
+
+/**
+ * #332 — the trace-helper generator runs against the SHIPPED
+ * {@code metaobjects::ai::LlmCallBase}, not a hand-copied one.
+ *
+ * <p>Every other test of this generator declares its own {@code LlmCallBase} inline under a
+ * different package. That is the bypass ADR-0024 already named — "the green tests pass only
+ * because they bypass the shipped base with bespoke entities" — and it is precisely what let
+ * the Java port ship this generator while having no way at all to LOAD the metadata it
+ * exists to consume. A hand-copied base can also drift from the real one silently: the
+ * copies stay green while the shipped file moves.</p>
+ *
+ * <p>This test loads the real library through the {@code libraries} opt-in and asserts both
+ * directions of ADR-0024 FIX #1 — the fields the generator emits are exactly the shipped
+ * base's effective fields, no more and no fewer.</p>
+ */
+public class TraceHelperOnShippedLibraryTest {
+
+    /**
+     * A concrete call entity extending the SHIPPED base — no local copy of it anywhere.
+     * The request/response value objects and the nested {@code template.prompt} carrying
+     * {@code @responseRef} are what the generator's applies-to predicate requires; only the
+     * BASE is different from the other tests of this generator, which is the whole point.
+     */
+    private static final String META = "{\"metadata.root\": {"
+        + "  \"package\": \"acme::app\","
+        + "  \"children\": ["
+        + "    { \"object.value\": { \"name\": \"GreetRequest\", \"children\": ["
+        + "      { \"field.string\": { \"name\": \"name\", \"@required\": true } }"
+        + "    ]}},"
+        + "    { \"object.value\": { \"name\": \"GreetResponse\", \"children\": ["
+        + "      { \"field.string\": { \"name\": \"greeting\", \"@required\": true } }"
+        + "    ]}},"
+        + "    { \"object.entity\": {"
+        + "        \"name\": \"GreetingCall\","
+        + "        \"extends\": \"metaobjects::ai::LlmCallBase\","
+        + "        \"children\": ["
+        + "          { \"source.rdb\": { \"@table\": \"greeting_call\", \"@role\": \"primary\" } },"
+        + "          { \"identity.primary\": { \"name\": \"pk\", \"@fields\": [\"spanId\"] } },"
+        + "          { \"template.prompt\": { \"name\": \"greetingPrompt\","
+        + "                                  \"@payloadRef\": \"acme::app::GreetRequest\","
+        + "                                  \"@responseRef\": \"acme::app::GreetResponse\" } }"
+        + "        ]"
+        + "    } }"
+        + "  ]"
+        + "}}";
+
+    @Rule
+    public TemporaryFolder tmp = new TemporaryFolder();
+
+    private MetaDataLoader loadWithShippedLibrary(String name) {
+        MetaDataLoader loader = new MetaDataLoader(
+                LoaderOptions.create(false, false, true),
+                MetaDataLoader.SUBTYPE_MANUAL, name);
+        loader.setLibraries(Collections.singletonList("ai"));
+        loader.init();
+        loader.load(List.of(new InMemoryStringSource(META, name + "/meta.json")));
+        return loader;
+    }
+
+    @Test
+    public void generatesAHelperForAnEntityExtendingTheShippedBase() throws Exception {
+        MetaDataLoader loader = loadWithShippedLibrary("trace-shipped");
+
+        MetaObject base = loader.getMetaObjectByName("metaobjects::ai::LlmCallBase");
+        assertNotNull("the SHIPPED base must be in the model — that is the whole point", base);
+
+        MetaObject call = loader.getMetaObjectByName("acme::app::GreetingCall");
+        assertNotNull("GreetingCall must load", call);
+
+        Path gen = tmp.newFolder("gen").toPath();
+        LlmTraceHelperGenerator generator = new LlmTraceHelperGenerator();
+        Map<String, String> args = new HashMap<>();
+        args.put("outputDir", gen.toString());
+        generator.setArgs(args);
+        generator.execute(loader);
+
+        Path helper = gen.resolve("acme/app/GreetingCallTraceHelper.java");
+        assertTrue("a helper must be emitted for an entity extending the SHIPPED base, at " + helper,
+            Files.exists(helper));
+    }
+
+    /**
+     * ADR-0024 FIX #1, both directions: the recorder's row keys are exactly the shipped
+     * base's effective fields.
+     *
+     * <p>One direction alone is worthless here. "Every row key is a field" passes on a
+     * recorder that writes nothing; "every field is a row key" passes on one that writes the
+     * whole world. Only the equality says the two agree, which is the claim — and it is the
+     * claim a hand-copied base can never make, because it is comparing a copy against
+     * itself.</p>
+     */
+    @Test
+    public void theShippedBaseFieldsAreExactlyWhatTheRecorderWrites() {
+        MetaDataLoader loader = loadWithShippedLibrary("trace-shipped-fields");
+        MetaObject base = loader.getMetaObjectByName("metaobjects::ai::LlmCallBase");
+        assertNotNull(base);
+
+        // ADR-0039: the RESOLVING accessor. An own-only read would drop anything the base
+        // itself inherits, and the row keys are about the EFFECTIVE field set.
+        List<String> baseFields = new ArrayList<>();
+        for (MetaField f : base.getMetaFields()) baseFields.add(f.getName());
+
+        MetaObject call = loader.getMetaObjectByName("acme::app::GreetingCall");
+        List<String> callFields = new ArrayList<>();
+        for (MetaField f : call.getMetaFields()) callFields.add(f.getName());
+
+        assertTrue("the base must declare fields at all — an empty set would make the "
+            + "equality below vacuously true", baseFields.size() >= 10);
+        assertTrue("every shipped base field reaches the concrete entity through extends",
+            callFields.containsAll(baseFields));
+        assertEquals("the concrete entity adds no fields of its own in this fixture, so the "
+            + "two sets must be equal — a difference means extends dropped or invented one",
+            new TreeSet<>(baseFields), new TreeSet<>(callFields));
+    }
+
+    @Test
+    public void theLibraryIsNotLoadedUnlessAskedFor() {
+        // The negative arm for the generator path specifically: without the opt-in there is
+        // no base, so there is nothing for the generator to key on. A test suite that only
+        // ever declares its own base cannot tell these two worlds apart, which is exactly
+        // how a generator came to ship without its input.
+        assertTrue("the ai package must be one this build ships",
+            LibrarySources.knownPackages().contains("ai"));
+        assertTrue("and it must contribute nothing when not requested",
+            LibrarySources.librarySources(Collections.emptyList()).isEmpty());
+    }
+}

server/java/maven-plugin/src/main/java/com/metaobjects/mojo/AbstractMetaDataMojo.java

@@ -269,8 +269,32 @@ protected MetaDataLoader createLoader(ClassLoader projectClassLoader) {
             sources = neutralSources;
         }
 
+        // An unknown <library> name is a HARD failure naming the ones this version ships,
+        // not a silent skip. `LibrarySources` skips deliberately for a programmatic caller
+        // — asking for a package a given version does not ship should not stop that caller
+        // loading its own metadata — but a name typed into a pom is a mistake worth failing
+        // on: skipped, it resurfaces later as ERR_UNRESOLVED_SUPER pointing at the module's
+        // OWN metadata, which is the wrong place to send someone looking. Same line the TS
+        // and Python config readers draw, in the same place.
+        List<String> libraries = loaderConfig.getLibraries();
+        if (libraries != null && !libraries.isEmpty()) {
+            List<String> available = com.metaobjects.library.LibrarySources.knownPackages();
+            List<String> unknown = new ArrayList<>();
+            for (String lib : libraries) {
+                if (!available.contains(lib)) unknown.add(lib);
+            }
+            if (!unknown.isEmpty()) {
+                // A MetaDataException, matching `failOnLoaderErrors` just below: this method
+                // is not declared to throw the checked Maven type, and both failures are the
+                // same kind of thing — the model this goal was asked to load cannot be.
+                throw new MetaDataException(
+                    "<loader><libraries> names unknown package(s) " + unknown
+                        + "; available: " + available);
+            }
+        }
+
         MavenLoaderConfiguration.configure(configurable, sourceDir, projectClassLoader,
-                                         sources, loaderArgs(strict));
+                                         sources, libraries, loaderArgs(strict));
 
         MetaDataLoader loader = configurable.getLoader();
 

server/java/maven-plugin/src/main/java/com/metaobjects/mojo/LoaderParam.java

@@ -14,6 +14,7 @@ public class LoaderParam {
     private String classname = null;
     private String sourceDir = null;
     private List<String> sources = null;
+    private List<String> libraries = null;
     private List<String> filters = null;
 
     public LoaderParam() {}
@@ -58,6 +59,25 @@ public void setClassname(String classname) {
         this.classname = classname;
     }
 
+    /**
+     * MetaObjects-shipped library packages this module loads alongside its own metadata —
+     * {@code <libraries><library>ai</library></libraries>} makes
+     * {@code extends: metaobjects::ai::LlmCallBase} resolve (#332).
+     *
+     * @return the requested package names, or null if not set
+     */
+    public List<String> getLibraries() {
+        return libraries;
+    }
+
+    /**
+     * Set the MetaObjects-shipped library packages to load.
+     * @param libraries package names (e.g. {@code ["ai"]})
+     */
+    public void setLibraries(List<String> libraries) {
+        this.libraries = libraries;
+    }
+
     /**
      * Get the source directory path for metadata files
      * @return Source directory path, or null if not set

server/java/maven-plugin/src/main/java/com/metaobjects/mojo/MavenLoaderConfiguration.java

@@ -34,12 +34,33 @@ public class MavenLoaderConfiguration {
      * @param sourceDir The Maven source directory
      * @param classLoader The Maven project class loader
      * @param sources The list of source files
+     * @param libraries MetaObjects-shipped library packages to load first (#332)
      * @param globals The global arguments map
      */
-    public static void configure(LoaderConfigurable configurable, 
-                               String sourceDir, 
+    public static void configure(LoaderConfigurable configurable,
+                               String sourceDir,
                                ClassLoader classLoader,
-                               List<String> sources, 
+                               List<String> sources,
+                               Map<String, String> globals) {
+        configure(configurable, sourceDir, classLoader, sources, null, globals);
+    }
+
+    /**
+     * Configure a LoaderConfigurable instance, opting into MetaObjects-shipped library
+     * packages alongside the configured sources.
+     *
+     * @param configurable The loader to configure
+     * @param sourceDir The Maven source directory
+     * @param classLoader The Maven project class loader
+     * @param sources The list of source files
+     * @param libraries MetaObjects-shipped library packages to load first (#332); may be null
+     * @param globals The global arguments map
+     */
+    public static void configure(LoaderConfigurable configurable,
+                               String sourceDir,
+                               ClassLoader classLoader,
+                               List<String> sources,
+                               List<String> libraries,
                                Map<String, String> globals) {
 
 
@@ -54,6 +75,7 @@ public static void configure(LoaderConfigurable configurable,
                 .sourceDir(sourceDir)
                 .classLoader(classLoader)
                 .sources(sources)
+                .libraries(libraries)
                 .arguments(globals)
                 .build();