Merge metadata-ktx — Kotlin facade over Java MetaObjects + FR-004 render

New module under server/java/metadata-ktx/ — thin idiomatic-Kotlin facade
over the Java engine, mirrors omdb-ktx shape. Extension functions only;
NO wrapper class. Wraps where Kotlin interop has real friction (Optional→T?,
platform-nullable pinning, typed nullable enums, reified generics, top-level
loader factory fns matching cross-port convention, render { ... } property-bag
builder for FR-004 RenderRequest). Does NOT wrap custom subclasses, mutators,
or the registry builder — Kotlin uses those Java APIs directly.

7 source files (Loader/MetaObjects/Fields/Attrs/Identity/Relationships/Render)
+ 8 test files (33 tests). Deps: metaobjects-metadata + metaobjects-render
(no omdb — metadata-ktx sits below omdb-ktx in the stack).

Unblocks the planned codegen-kotlin module — consumers writing Kotlin apps
that load metadata + render LLM prompts via template.prompt can now use
idiomatic Kotlin: loadResources(...), .promptTemplateOrNull(name), render { }.

Author: dmealing

docs/superpowers/plans/2026-05-25-metadata-ktx.md

@@ -0,0 +1,89 @@
+# MetaObjects :: Metadata Kotlin Facade (`metadata-ktx`)
+
+A thin Kotlin extension layer over the Java MetaObjects engine.
+No forking, no reimplementation — just idiomatic Kotlin syntax on top of the existing Java API.
+
+## Dependency
+
+```xml
+<dependency>
+    <groupId>com.metaobjects</groupId>
+    <artifactId>metaobjects-metadata-ktx</artifactId>
+    <version>${project.version}</version>
+</dependency>
+```
+
+## Loading metadata
+
+```kotlin
+import com.metaobjects.metadata.ktx.*
+import java.nio.file.Path
+
+// From classpath resources
+val loader = loadResources("demo", listOf("meta.demo.json"))
+
+// From a directory
+val dirLoader = loadDirectory("app", Path.of("./metadata"))
+
+// From an inline string (defaults to JSON; pass MetaDataFormat.YAML for YAML)
+val inlineLoader = loadString("test", """{ "metadata.root": { "package": "x", "children": [] } }""")
+```
+
+## Navigating metadata
+
+```kotlin
+import com.metaobjects.field.StringField
+
+// Null-returning lookups (idiomatic Kotlin)
+val author = loader.metaObjectOrNull("acme::demo::Author")   // null if not found
+
+// Reified typed field access
+val name = author?.field<StringField>("name")                // null if absent or wrong type
+val required = author!!.requireField<StringField>("name")    // throws if absent
+
+// Typed nullable enums
+val rel = ...  // some MetaRelationship
+val cardinality: Cardinality? = rel.cardinalityType          // null if absent/unknown
+val target = rel.targetObjectOrNull                          // resolved MetaObject or null
+
+// Own-only attribute reads
+val maxLen: String? = field.attrStringOrNull("maxLength")
+```
+
+## Template + render (FR-004)
+
+```kotlin
+import com.metaobjects.render.InMemoryProvider
+
+val prompt = loader.promptTemplateOrNull("acme::demo::WelcomePrompt")
+println(prompt?.payloadRef)   // "Author"
+
+// Render via the Kotlin builder
+val out = render {
+    template = "Hello {{name}}, welcome!"
+    payload = mapOf("name" to "Ada")
+    provider = InMemoryProvider(emptyMap())
+}
+// out == "Hello Ada, welcome!"
+
+// Render via a ref + filesystem provider
+import com.metaobjects.render.FilesystemProvider
+val rendered = render {
+    ref = "lobby/welcome"
+    payload = mapOf("name" to "Bob")
+    provider = FilesystemProvider(Path.of("./prompts"))
+    format = "html"
+}
+```
+
+## Patterns not wrapped (Java works fine from Kotlin)
+
+- **Custom MetaObject / MetaField subtypes:** `class MyType : EntityMetaObject("MyType")` — Kotlin subclasses Java directly.
+- **Custom Provider:** `class MyProvider : Provider { override fun resolve(reference: String): String? = ... }`
+- **Custom MetaDataSource:** same pattern.
+- **MetaObject / MetaField mutation:** the Java mutator API (`addChild`, `addMetaAttribute`) reads fine from Kotlin.
+- **Registry builder:** Java's `MetaDataRegistry.registerType(MyType::class.java) { def -> def.type(...)... }` is already lambda-friendly.
+
+## Status
+
+`metaobjects-metadata-ktx` 7.0.0-SNAPSHOT. Mirrors the `metaobjects-omdb-ktx` Kotlin facade pattern.

docs/superpowers/specs/2026-05-25-metadata-ktx-kotlin-facade-design.md

@@ -0,0 +1,92 @@
+<?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-metadata-ktx</artifactId>
+  <name>MetaObjects :: Metadata Kotlin Facade</name>
+  <description>Idiomatic Kotlin facade over the Java metadata loader + FR-004 template + render engine.</description>
+
+  <properties>
+    <kotlin.version>2.0.21</kotlin.version>
+    <maven.compiler.release>21</maven.compiler.release>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.jetbrains.kotlin</groupId>
+      <artifactId>kotlin-stdlib</artifactId>
+      <version>${kotlin.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>com.metaobjects</groupId>
+      <artifactId>metaobjects-metadata</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>com.metaobjects</groupId>
+      <artifactId>metaobjects-render</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+
+    <!-- test -->
+    <dependency>
+      <groupId>org.jetbrains.kotlin</groupId>
+      <artifactId>kotlin-test-junit5</artifactId>
+      <version>${kotlin.version}</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter</artifactId>
+      <version>5.10.2</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>com.metaobjects</groupId>
+      <artifactId>metaobjects-metadata</artifactId>
+      <version>${project.version}</version>
+      <type>test-jar</type>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <sourceDirectory>src/main/kotlin</sourceDirectory>
+    <testSourceDirectory>src/test/kotlin</testSourceDirectory>
+    <plugins>
+      <plugin>
+        <groupId>org.jetbrains.kotlin</groupId>
+        <artifactId>kotlin-maven-plugin</artifactId>
+        <version>${kotlin.version}</version>
+        <executions>
+          <execution>
+            <id>compile</id>
+            <phase>compile</phase>
+            <goals><goal>compile</goal></goals>
+          </execution>
+          <execution>
+            <id>test-compile</id>
+            <phase>test-compile</phase>
+            <goals><goal>test-compile</goal></goals>
+          </execution>
+        </executions>
+        <configuration>
+          <jvmTarget>21</jvmTarget>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-surefire-plugin</artifactId>
+        <version>${surefire.plugin.version}</version>
+      </plugin>
+    </plugins>
+  </build>
+</project>

server/java/metadata-ktx/README.md

@@ -0,0 +1,18 @@
+package com.metaobjects.metadata.ktx
+
+import com.metaobjects.MetaData
+import com.metaobjects.attr.MetaAttribute
+
+/**
+ * Own-only attribute helpers — read attributes declared directly on a node,
+ * ignoring anything inherited from a super. Mirrors [MetaData.hasMetaAttr] +
+ * [MetaData.getMetaAttr] with the `includeParentData=false` flag pinned.
+ */
+
+/** Read an own-only attribute as [MetaAttribute]; null if absent. */
+fun MetaData.attrOrNull(name: String): MetaAttribute<*>? =
+    if (hasMetaAttr(name, false)) getMetaAttr(name, false) else null
+
+/** Read an own-only attribute's string form (via `DataConverter`); null if absent. */
+fun MetaData.attrStringOrNull(name: String): String? =
+    attrOrNull(name)?.valueAsString

server/java/metadata-ktx/pom.xml

@@ -0,0 +1,31 @@
+package com.metaobjects.metadata.ktx
+
+import com.metaobjects.MetaDataNotFoundException
+import com.metaobjects.field.MetaField
+import com.metaobjects.`object`.MetaObject
+
+/**
+ * Reified typed-field accessors over [MetaObject.getMetaField] / [MetaObject.getMetaFields].
+ *
+ * Kotlin's `inline reified` lets the caller write `obj.field<StringField>("s")`
+ * instead of the Java class-token shape `obj.getMetaField("s", StringField.class)`.
+ */
+
+/** Typed lookup; returns null when the field is absent OR not the requested subtype. */
+inline fun <reified T : MetaField<*>> MetaObject.field(name: String): T? =
+    try {
+        getMetaField(name) as? T
+    } catch (_: MetaDataNotFoundException) {
+        null
+    }
+
+/**
+ * Typed lookup; throws when the field is absent (mirrors [MetaObject.getMetaField]).
+ * Casts to [T]; throws [ClassCastException] when the field is the wrong subtype.
+ */
+inline fun <reified T : MetaField<*>> MetaObject.requireField(name: String): T =
+    getMetaField(name) as T
+
+/** All fields matching the requested subtype, in declaration order. */
+inline fun <reified T : MetaField<*>> MetaObject.fieldsOfType(): List<T> =
+    metaFields.filterIsInstance<T>()

server/java/metadata-ktx/src/main/kotlin/com/metaobjects/metadata/ktx/Attrs.kt

@@ -0,0 +1,22 @@
+package com.metaobjects.metadata.ktx
+
+import com.metaobjects.identity.MetaIdentity
+
+/**
+ * Typed nullable enum mapping for [MetaIdentity.getGeneration].
+ *
+ * Java exposes `@generation` as a raw String drawn from a closed set
+ * ([MetaIdentity.GENERATION_INCREMENT], [MetaIdentity.GENERATION_UUID],
+ * [MetaIdentity.GENERATION_ASSIGNED]). Kotlin gets a typed nullable enum
+ * so the `when` is exhaustive and unknown/absent values surface as `null`.
+ */
+enum class IdentityGeneration { INCREMENT, UUID, ASSIGNED }
+
+/** Typed view of [MetaIdentity.getGeneration]; null on absent or unrecognized value. */
+val MetaIdentity.generationStrategy: IdentityGeneration?
+    get() = when (generation?.lowercase()) {
+        MetaIdentity.GENERATION_INCREMENT -> IdentityGeneration.INCREMENT
+        MetaIdentity.GENERATION_UUID -> IdentityGeneration.UUID
+        MetaIdentity.GENERATION_ASSIGNED -> IdentityGeneration.ASSIGNED
+        else -> null
+    }

server/java/metadata-ktx/src/main/kotlin/com/metaobjects/metadata/ktx/Fields.kt

@@ -0,0 +1,42 @@
+package com.metaobjects.metadata.ktx
+
+import com.metaobjects.loader.DirectorySource
+import com.metaobjects.loader.LoaderOptions
+import com.metaobjects.loader.MetaDataLoader
+import com.metaobjects.loader.MetaDataSource.MetaDataFormat
+import java.net.URI
+import java.nio.file.Path
+
+/**
+ * Top-level loader factory shortcuts — match the cross-port convention used by
+ * the TS and Python implementations. Each shortcut forwards to the corresponding
+ * [MetaDataLoader] static factory.
+ */
+
+/** Load metadata from a filesystem directory; pass [DirectorySource.Options] to tune expansion. */
+fun loadDirectory(
+    name: String,
+    directory: Path,
+    opts: DirectorySource.Options = DirectorySource.Options(),
+): MetaDataLoader = MetaDataLoader.fromDirectory(name, directory, opts)
+
+/** Load metadata from a list of URIs; pass [LoaderOptions] to tune (e.g. `strict=true`). */
+fun loadUris(
+    name: String,
+    uris: List<URI>,
+    opts: LoaderOptions? = null,
+): MetaDataLoader = MetaDataLoader.fromUris(name, uris, opts)
+
+/** Load metadata from classpath resource paths; pass [LoaderOptions] to tune. */
+fun loadResources(
+    name: String,
+    resources: List<String>,
+    opts: LoaderOptions? = null,
+): MetaDataLoader = MetaDataLoader.fromResources(name, resources, opts)
+
+/** Load metadata from a single inline string (defaults to JSON). */
+fun loadString(
+    name: String,
+    content: String,
+    format: MetaDataFormat = MetaDataFormat.JSON,
+): MetaDataLoader = MetaDataLoader.fromString(name, content, format)

server/java/metadata-ktx/src/main/kotlin/com/metaobjects/metadata/ktx/Identity.kt

@@ -0,0 +1,50 @@
+package com.metaobjects.metadata.ktx
+
+import com.metaobjects.MetaDataNotFoundException
+import com.metaobjects.loader.MetaDataLoader
+import com.metaobjects.`object`.MetaObject
+import com.metaobjects.registry.MetaDataLoaderRegistry
+import com.metaobjects.template.MetaTemplate
+import com.metaobjects.template.OutputTemplate
+import com.metaobjects.template.PromptTemplate
+import com.metaobjects.template.TemplateConstants
+
+/**
+ * Null-returning lookups for [MetaObject] and the FR-004 [MetaTemplate] subtypes.
+ *
+ * Java's [MetaDataLoader.getMetaObjectByName] throws [MetaDataNotFoundException]
+ * on miss; idiomatic Kotlin prefers `T?`. These extensions trade the throw for
+ * `null`, which is what every call site that "may or may not find it" wants.
+ */
+
+/** Lookup a [MetaObject] by FQN on this loader; returns null if not found. */
+fun MetaDataLoader.metaObjectOrNull(name: String): MetaObject? =
+    try {
+        getMetaObjectByName(name)
+    } catch (_: MetaDataNotFoundException) {
+        null
+    }
+
+/** Lookup a [MetaObject] by FQN across all registered loaders; returns null if not found. */
+fun MetaDataLoaderRegistry.metaObjectOrNull(name: String): MetaObject? =
+    try {
+        findMetaObjectByName(name)
+    } catch (_: MetaDataNotFoundException) {
+        null
+    }
+
+/** Lookup a [MetaTemplate] (any subtype) by FQN; returns null if not found or not a template. */
+fun MetaDataLoader.templateOrNull(name: String): MetaTemplate? =
+    try {
+        root.getChildOfType(TemplateConstants.TYPE_TEMPLATE, name) as? MetaTemplate
+    } catch (_: MetaDataNotFoundException) {
+        null
+    }
+
+/** Lookup a [PromptTemplate] by FQN; returns null if not found OR not a prompt template. */
+fun MetaDataLoader.promptTemplateOrNull(name: String): PromptTemplate? =
+    templateOrNull(name) as? PromptTemplate
+
+/** Lookup an [OutputTemplate] by FQN; returns null if not found OR not an output template. */
+fun MetaDataLoader.outputTemplateOrNull(name: String): OutputTemplate? =
+    templateOrNull(name) as? OutputTemplate

server/java/metadata-ktx/src/main/kotlin/com/metaobjects/metadata/ktx/Loader.kt

@@ -0,0 +1,44 @@
+package com.metaobjects.metadata.ktx
+
+import com.metaobjects.MetaDataNotFoundException
+import com.metaobjects.`object`.MetaObject
+import com.metaobjects.relationship.MetaRelationship
+
+/**
+ * Typed nullable enum + reference resolution for [MetaRelationship].
+ *
+ * Java exposes `@cardinality` as a raw String drawn from a closed set
+ * ([MetaRelationship.CARDINALITY_ONE], [MetaRelationship.CARDINALITY_MANY]).
+ * Java does NOT ship a `getTargetObject()` — only `getObjectRef()` returning
+ * the raw `@objectRef` string (bare or FQN). This module resolves it against
+ * the owning loader, accepting either form.
+ */
+enum class Cardinality { ONE, MANY }
+
+/** Typed view of [MetaRelationship.getCardinality]; null on absent or unrecognized value. */
+val MetaRelationship.cardinalityType: Cardinality?
+    get() = when (cardinality?.lowercase()) {
+        MetaRelationship.CARDINALITY_ONE -> Cardinality.ONE
+        MetaRelationship.CARDINALITY_MANY -> Cardinality.MANY
+        else -> null
+    }
+
+/**
+ * Resolve `@objectRef` against this relationship's owning loader; null if absent or unresolved.
+ *
+ * Tries the value as an FQN first ([com.metaobjects.loader.MetaDataLoader.getMetaObjectByName]);
+ * falls back to a short-name scan of the loader's root, mirroring what the validation phase
+ * does for origin `@via` path resolution (origin/relationship attrs accept bare entity names).
+ */
+val MetaRelationship.targetObjectOrNull: MetaObject?
+    get() {
+        val ref = objectRef ?: return null
+        val loader = loader ?: return null
+        try {
+            return loader.getMetaObjectByName(ref)
+        } catch (_: MetaDataNotFoundException) {
+            // fall through to short-name scan
+        }
+        return loader.root.getChildren(MetaObject::class.java, false)
+            .firstOrNull { it.shortName == ref || it.name == ref }
+    }