feat(ai,java): preFreeze loader hook + deriveTraceFields auto-derivation (Slice 3)

Port the TS reference's generic `preFreeze` loader option to the Java
MetaDataLoader, and add LlmTraceFieldDeriver as its first consumer: for any
entity extending LlmCallBase with a nested template.prompt carrying
@payloadRef/@responseRef, inject voRequest/voResponse field.object jsonb columns
(idempotent, own-field-wins) so authors don't restate them.

Cross-port divergence (justified): the TS reference wires deriveTraceFields
codegen-only because the TS runtime persists via a direct row-write (no runtime
metadata). The Java OMDB runtime is metadata-driven — the generated
record<Entity> helper calls setObject("voResponse", ...) which OMDB maps to a
jsonb column by reading the runtime-loaded MetaObject. So in Java the derivation
must also reach the runtime load path; it is exposed as a MetaDataLoader
preFreeze hook (Tier-3 mechanism) usable by BOTH codegen and runtime loaders.

- metadata: generic preFreeze hook (setPreFreeze + fromUris overload + in-load
  invocation after extends-resolution, before validation so derived nodes are
  validated like authored ones); LlmTraceFieldDeriver; PromptTemplate.getPayloadRef().
- maven-plugin: meta:gen runs deriveTraceFields post-load (no hard freeze in Java).
- CI gate: LlmTraceFieldDeriverTest (4/4) proves derivation + strict-validation
  survival (ADR-0023) + idempotency + negative cases. Full metadata suite green
  (989/991; the 2 fails are the pre-existing template-source-conformance issue).
- Integration: the PG round-trip fixture now DERIVES voRequest/voResponse from a
  template.prompt instead of hand-declaring them, proving derivation reaches the
  OMDB runtime end-to-end (2/2 against real Postgres).

call<Entity> still deferred (BYO vendor-neutral caller; ADR-0024).

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

Author: dmealing

server/java/integration-tests/src/test/java/com/metaobjects/integration/LlmCallTraceRoundTripTest.java

@@ -1,6 +1,7 @@
 package com.metaobjects.integration;
 
 import com.metaobjects.loader.MetaDataLoader;
+import com.metaobjects.loader.ai.LlmTraceFieldDeriver;
 import com.metaobjects.loader.uri.URIHelper;
 import com.metaobjects.manager.ObjectConnection;
 import com.metaobjects.manager.db.ObjectManagerDB;
@@ -208,7 +209,12 @@ private static MetaDataLoader loadAiTraceMetadata() {
         Path libraryYaml = findRepoFile("library/ai/llm-call.yaml");
         URI libUri = URIHelper.toURI("model:file:" + libraryYaml.toAbsolutePath());
         URI entityUri = URIHelper.toURI("model:resource:meta.ai-trace.yaml");
-        return MetaDataLoader.fromUris("test-ai-trace", List.of(libUri, entityUri));
+        // Wire the AI-trace deriver as a preFreeze hook: voRequest/voResponse are
+        // NOT authored in the fixture — they are derived in-load from the prompt's
+        // @payloadRef/@responseRef, so the OMDB runtime sees the typed jsonb
+        // columns (Slice 3, the metadata-driven-runtime divergence from TS).
+        return MetaDataLoader.fromUris("test-ai-trace", List.of(libUri, entityUri),
+            null, LlmTraceFieldDeriver::deriveTraceFields);
     }
 
     /** Walk up from the working dir to locate a repo-relative file. */
@@ -245,6 +251,7 @@ private static void provisionSchema(PostgresContainer pg) throws SQLException {
                     + "  \"startedAt\" timestamp,\n"
                     + "  \"llmRequest\" jsonb,\n"
                     + "  \"llmResponse\" jsonb,\n"
+                    + "  \"voRequest\" jsonb,\n"
                     + "  \"voResponse\" jsonb\n"
                     + ")");
         }

server/java/integration-tests/src/test/resources/meta.ai-trace.yaml

@@ -1,10 +1,22 @@
 # Test-only trace entity for the AI-trace recorder PG round-trip.
 # Extends the SHIPPED metaobjects::ai::LlmCallBase (loaded from
-# library/ai/llm-call.yaml) and adds a typed voResponse jsonb column.
+# library/ai/llm-call.yaml). The typed voRequest/voResponse jsonb columns are
+# NOT declared here — they are DERIVED by LlmTraceFieldDeriver (Slice 3) from the
+# nested template.prompt's @payloadRef/@responseRef when the loader runs with the
+# deriver wired as a preFreeze hook. This proves derivation reaches the
+# metadata-driven OMDB runtime (the Java-specific divergence from the TS
+# codegen-only reference).
 metadata:
   package: metaobjects::ai
   children:
-    # Typed value object stored in the voResponse jsonb column.
+    # Typed request payload VO (referenced by @payloadRef → derived voRequest).
+    - object.value:
+        name: GreetingRequest
+        object: com.metaobjects.object.value.ValueObject
+        children:
+          - field.string: { name: prompt }
+
+    # Typed response VO (referenced by @responseRef → derived voResponse).
     - object.value:
         name: GreetingResponse
         object: com.metaobjects.object.value.ValueObject
@@ -13,16 +25,15 @@ metadata:
           - field.int:    { name: score,    column: score }
 
     # Concrete trace entity: inherits the 18 LlmCallBase fields, declares its
-    # table + primary identity + a typed voResponse jsonb column (@objectRef +
-    # @storage:jsonb — the owned-object typed-jsonb codec path).
+    # table + primary identity + a template.prompt. The deriver injects
+    # voRequest/voResponse field.object jsonb columns from the prompt refs.
     - object.entity:
         name: GreetingCall
         extends: metaobjects::ai::LlmCallBase
         children:
           - source.rdb:       { table: llm_call, role: primary }
           - identity.primary: { name: primary, fields: ["spanId"] }
-          - field.object:
-              name: voResponse
-              column: voResponse
-              storage: jsonb
-              objectRef: metaobjects::ai::GreetingResponse
+          - template.prompt:
+              name: greet
+              payloadRef: metaobjects::ai::GreetingRequest
+              responseRef: metaobjects::ai::GreetingResponse

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

@@ -86,6 +86,14 @@ public void execute() throws MojoExecutionException, MojoFailureException
 
         MetaDataLoader loader = createLoader(projectClassLoader);
 
+        // AI-trace pre-pass: derive typed voRequest/voResponse jsonb columns onto
+        // LlmCallBase-derived entities so the trace-helper generator (and any
+        // entity/schema codegen) sees them without the author restating them.
+        // Idempotent + a no-op for projects with no trace entities. The loader is
+        // already loaded here (no hard freeze in Java); generators re-read children
+        // fresh, so post-load derivation is sufficient for codegen.
+        com.metaobjects.loader.ai.LlmTraceFieldDeriver.deriveTraceFields( loader );
+
         List<Generator> generatorImpls = buildGenerators( projectClassLoader, null );
 
         executeGenerators( loader, generatorImpls );

server/java/metadata/src/main/java/com/metaobjects/loader/MetaDataLoader.java

@@ -110,6 +110,15 @@ public class MetaDataLoader implements LoaderConfigurable {
     // ClassLoader used for resolving metadata-referenced Java classes.
     private ClassLoader metaDataClassLoader = null;
 
+    // Optional pre-freeze enrichment hook. Mirrors the TypeScript loader's
+    // generic `preFreeze` option: a callback that runs inside {@link #load} once
+    // the tree is parsed and {@code extends} refs are resolved, but before the
+    // validation passes. This is the designated injection point for programmatic
+    // tree enrichment (e.g. codegen/runtime pre-passes that DERIVE additional
+    // nodes from validated metadata). The injected nodes participate in the
+    // subsequent validation passes. Null by default (no enrichment).
+    private java.util.function.Consumer<MetaDataLoader> preFreeze = null;
+
     // v6.0.0: Unified registry
     private MetaDataRegistry typeRegistry = null;
     private MetaDataLoaderRegistry loaderRegistry = null;
@@ -391,9 +400,26 @@ public static MetaDataLoader fromUris(String name, List<URI> uris) {
      * @return a fully-initialized loader with all URIs loaded
      */
     public static MetaDataLoader fromUris(String name, List<URI> uris, LoaderOptions opts) {
+        return fromUris(name, uris, opts, null);
+    }
+
+    /**
+     * Build + load with a pre-freeze enrichment hook (see {@link #setPreFreeze}).
+     * The hook runs in-load (after extends-resolution, before validation), so any
+     * derived nodes are validated and registered atomically with this build.
+     *
+     * @param name      the loader name
+     * @param uris      model URIs to load
+     * @param opts      loader options (may be {@code null} for defaults)
+     * @param preFreeze pre-freeze enrichment hook (may be {@code null})
+     * @return a fully-initialized loader with all URIs loaded
+     */
+    public static MetaDataLoader fromUris(String name, List<URI> uris, LoaderOptions opts,
+                                          java.util.function.Consumer<MetaDataLoader> preFreeze) {
         MetaDataLoader loader = (opts == null)
             ? createManual(false, name)
             : new MetaDataLoader(opts, SUBTYPE_MANUAL, name);
+        if (preFreeze != null) loader.setPreFreeze(preFreeze);
         try {
             loader.init();
             List<MetaDataSource> sources = new ArrayList<>(uris.size());
@@ -672,6 +698,19 @@ public ClassLoader getMetaDataClassLoader() {
         return getDefaultMetaDataClassLoader();
     }
 
+    /**
+     * Register a pre-freeze enrichment hook (mirrors the TS loader's generic
+     * {@code preFreeze} option). The hook runs inside {@link #load} after
+     * {@code extends} refs are resolved and before the validation passes, so any
+     * nodes it injects are validated like hand-authored ones. Fluent; pass
+     * {@code null} to clear. Must be set before {@link #load} runs.
+     */
+    @SuppressWarnings("unchecked")
+    public <T extends MetaDataLoader> T setPreFreeze(java.util.function.Consumer<MetaDataLoader> hook) {
+        this.preFreeze = hook;
+        return (T) this;
+    }
+
     ///////////////////////////////////////////////////////////////////////
     // Source URIs (H3a Task 5: lifted from SimpleLoader)
 
@@ -1250,6 +1289,14 @@ public MetaDataLoader load(List<MetaDataSource> sources) {
         // becomes ERR_UNRESOLVED_SUPER.
         resolvePendingExtends();
 
+        // Pre-freeze enrichment hook (mirrors TS): runs after extends-resolution
+        // and before validation, so DERIVED nodes (e.g. AI-trace voRequest/
+        // voResponse jsonb columns) are visible to the validation passes and to
+        // every downstream reader (codegen + runtime) just like authored nodes.
+        if (preFreeze != null) {
+            preFreeze.accept(this);
+        }
+
         // Run post-load validation passes after all sources in this batch are parsed.
         // Fires both when called from init() (via loadSourceURIsIfPresent) and when
         // called directly by tests or the conformance runner. The loader handle is

server/java/metadata/src/main/java/com/metaobjects/loader/ai/LlmTraceFieldDeriver.java

@@ -0,0 +1,121 @@
+/*
+ * Copyright 2003 Doug Mealing LLC dba Meta Objects
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.metaobjects.loader.ai;
+
+import com.metaobjects.MetaData;
+import com.metaobjects.attr.StringAttribute;
+import com.metaobjects.field.MetaField;
+import com.metaobjects.field.ObjectField;
+import com.metaobjects.loader.MetaDataLoader;
+import com.metaobjects.object.MetaObject;
+import com.metaobjects.template.PromptTemplate;
+
+import java.util.List;
+
+/**
+ * AI-trace pre-freeze pass: inject typed {@code voRequest}/{@code voResponse}
+ * {@code field.object} columns onto entities that extend {@code LlmCallBase} and
+ * carry a nested {@code template.prompt} with {@code @payloadRef}/{@code @responseRef}.
+ *
+ * <p>Cross-port mirror of the TypeScript reference
+ * ({@code codegen-ts/src/ai/derive-trace-fields.ts}). The TS reference wires this
+ * as a codegen-only {@code preFreeze} hook because the TS runtime persists via a
+ * direct row-write (no runtime metadata needed). The Java OMDB runtime is
+ * <em>metadata-driven</em> — the generated {@code record<Entity>} helper calls
+ * {@code setObject("voResponse", ...)} which OMDB maps to a jsonb column by reading
+ * the <em>runtime-loaded</em> MetaObject. So in Java this derivation must also reach
+ * the runtime load path; it is therefore exposed as a {@link MetaDataLoader}
+ * {@code preFreeze} hook usable by BOTH codegen and runtime loaders.</p>
+ *
+ * <p>The injected fields carry {@code @objectRef} + {@code @storage="jsonb"} so the
+ * existing owned-object typed-jsonb codec path handles them — identical to a
+ * hand-authored {@code field.object}. The pass is idempotent: an own field of the
+ * same name is left untouched, so explicit authoring still wins.</p>
+ */
+public final class LlmTraceFieldDeriver {
+
+    /** Short name of the shipped abstract base every trace entity extends. */
+    public static final String LLM_CALL_BASE = "LlmCallBase";
+
+    /** Derived field name for the typed request payload VO. */
+    public static final String VO_REQUEST = "voRequest";
+
+    /** Derived field name for the typed extracted-response VO. */
+    public static final String VO_RESPONSE = "voResponse";
+
+    /** {@code @storage} value selecting the typed-jsonb owned-object codec. */
+    private static final String STORAGE_JSONB = "jsonb";
+
+    private LlmTraceFieldDeriver() {}
+
+    /**
+     * For every concrete entity in {@code loader} that (1) extends
+     * {@code LlmCallBase} (directly or transitively) and (2) has an own
+     * {@code template.prompt} carrying {@code @payloadRef}/{@code @responseRef},
+     * inject {@code field.object} children named {@code voRequest}/{@code voResponse}
+     * (respectively) with {@code @storage="jsonb"}. Idempotent.
+     *
+     * <p>Designed to be passed to {@link MetaDataLoader#setPreFreeze}.</p>
+     */
+    public static void deriveTraceFields(MetaDataLoader loader) {
+        for (MetaObject obj : loader.getChildren(MetaObject.class)) {
+            if (!extendsBase(obj, LLM_CALL_BASE)) continue;
+
+            PromptTemplate prompt = findOwnPrompt(obj);
+            if (prompt == null) continue;
+
+            String payloadRef = prompt.getPayloadRef();
+            String responseRef = prompt.getResponseRef();
+
+            if (payloadRef != null && !payloadRef.isEmpty()) {
+                injectObjField(obj, VO_REQUEST, payloadRef);
+            }
+            if (responseRef != null && !responseRef.isEmpty()) {
+                injectObjField(obj, VO_RESPONSE, responseRef);
+            }
+        }
+    }
+
+    /** Walk the resolved super chain for a node whose short name equals {@code baseName}. */
+    private static boolean extendsBase(MetaData obj, String baseName) {
+        MetaData cur = obj.getSuperData();
+        while (cur != null) {
+            if (baseName.equals(cur.getShortName())) return true;
+            cur = cur.getSuperData();
+        }
+        return false;
+    }
+
+    /** First OWN {@code template.prompt} child of {@code obj}, or {@code null}. */
+    private static PromptTemplate findOwnPrompt(MetaObject obj) {
+        List<PromptTemplate> prompts = obj.getChildren(PromptTemplate.class, false);
+        return prompts.isEmpty() ? null : prompts.get(0);
+    }
+
+    /**
+     * Inject a {@code field.object} child onto {@code entity} with {@code @objectRef}
+     * + {@code @storage="jsonb"}, unless an own field of that name already exists.
+     */
+    private static void injectObjField(MetaObject entity, String fieldName, String objectRef) {
+        for (MetaField existing : entity.getChildren(MetaField.class, false)) {
+            if (fieldName.equals(existing.getShortName())) return; // idempotent
+        }
+        ObjectField f = new ObjectField(fieldName);
+        f.addChild(StringAttribute.create(ObjectField.ATTR_OBJECTREF, objectRef));
+        f.addChild(StringAttribute.create(ObjectField.ATTR_STORAGE, STORAGE_JSONB));
+        entity.addChild(f);
+    }
+}

server/java/metadata/src/main/java/com/metaobjects/template/PromptTemplate.java

@@ -77,4 +77,11 @@ public String getResponseRef() {
             ? getMetaAttr(ATTR_RESPONSE_REF, false).getValueAsString()
             : null;
     }
+
+    /** Returns the raw value of {@code @payloadRef}, or {@code null} if absent. */
+    public String getPayloadRef() {
+        return hasMetaAttr(ATTR_PAYLOAD_REF, false)
+            ? getMetaAttr(ATTR_PAYLOAD_REF, false).getValueAsString()
+            : null;
+    }
 }