@@ -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
 
@@ -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)}`,
 );
@@ -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());
+    }
+}
@@ -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();
 
 
@@ -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
 
@@ -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();