docs: the jsonb ladder can now recommend a value object to a Java consumer

The ladder tells an author to convert an untyped jsonb bag to an `object.value`,
and until bc591b7 that advice was wrong for anyone whose Java code CONSTRUCTS
the result: the generated data class offered Java only the full N-arg
constructor and a no-arg one yielding an all-null instance of an immutable
class. The ladder never said so, because nothing had tried it.

Adds that to the "Port coverage, stated plainly" section as a VERSION question,
matching how the #362 caveat is framed two paragraphs up — the same shape of
fact, and the same thing an author needs to check before recommending a rung.
It is explicitly marked UNRELEASED, because it is: the builder is on `main` and
ships in the next JVM cut. Reading was never affected on any version (Kotlin
`val` emits Java getters), so a bag that is only READ converts safely today.

A doc that hedges on an unreleased capability becomes a lie the moment the cut
lands, which is the [[version-forecast]] trap in miniature — so
`docs/RELEASING-docs-checklist.md` §A grows an item to grep for that hedge and
flip it, regenerating the agent-context corpus in the same commit.

CHANGELOG [Unreleased] carries the entry, including why a builder rather than
`@JvmOverloads`, why not Lombok, why `object.projection` gets none, and that
`metamodelVersion` does not move.

Corpus regenerated (the authoring skill lands in all five stacks). Gates green.

Author: dmealing

CHANGELOG.md

@@ -10,6 +10,24 @@ here.**
 
 ## [Unreleased]
 
+### Added
+
+- **A generated Kotlin entity / value object is now constructible from Java** — a nested
+  `Builder` plus a `@JvmStatic builder()` ([#365]). Kotlin default arguments are a compiler
+  feature, not a bytecode one, so the generated data class previously offered Java only the full
+  N-arg constructor and a no-arg one yielding an all-null instance of an immutable class: a
+  caller setting 3 of 14 members had to pass 14 arguments with 11 nulls. Found when an adopter
+  converting an untyped jsonb bag to an `object.value` discovered the generated VO replacing a
+  hand-written Lombok `@Builder` made its Java call sites strictly worse. A builder rather than
+  `@JvmOverloads` because overloads are positional and only help trailing omissions; a plain
+  nested class rather than Lombok because generated code must not force an annotation processor
+  on an adopter. `object.projection` gets none — it is derived and read-only. Kotlin callers are
+  unaffected (named arguments already covered it), which is why every test in that module, all
+  Kotlin-side, missed this; the new test compiles real Java against the generated class.
+  `codegen-spring`'s Java `record`s have the same all-args shape and are tracked in #365 as a
+  follow-on. No vocabulary change, so `metamodelVersion` does not move.
+
+
 ## [1.0.1] — 2026-09-10
 
 **Why this is a PATCH and not a MINOR.** `docs/RELEASING.md`'s table says an additive CLI
@@ -103,6 +121,7 @@ adopter who read "field.map now works" out of this entry would be over-reading i
 `metamodelVersion` is unchanged at **1.0** — no registered vocabulary moved.
 
 [#362]: https://github.com/metaobjectsdev/metaobjects/issues/362
+[#365]: https://github.com/metaobjectsdev/metaobjects/issues/365
 [#361]: https://github.com/metaobjectsdev/metaobjects/issues/361
 [#360]: https://github.com/metaobjectsdev/metaobjects/pull/360
 [#359]: https://github.com/metaobjectsdev/metaobjects/issues/359

agent-context/skills/metaobjects-authoring/SKILL.md

@@ -585,6 +585,19 @@ Python's `ObjectManager` encodes a map today; `runtime-ts`, Java's OMDB and the
 lane carry no map handling at all. So a map you intend to read back through a PORT RUNTIME is
 still better declared as a value object, and a genuinely dynamic key set stays a bag.
 
+**One more version question, if a JAVA caller CONSTRUCTS the value object.** Kotlin's default
+arguments are a compiler feature, not a bytecode one, so a generated data class used to offer
+Java only the full N-arg constructor and a no-arg one yielding an all-null instance of an
+immutable class — a caller setting 3 of 14 members had to pass 14 arguments with 11 nulls. A
+generated VO replacing a hand-written builder therefore made its Java call sites *worse*.
+Generated entities and value objects now emit a nested `Builder` plus a `@JvmStatic builder()`
+(`Money.builder().currency("USD").build()`), so partial construction from Java works — but that
+is **UNRELEASED at the time of writing: it is on `main`, shipping in the next JVM cut.** Check
+the adopter's pinned version. Reading is unaffected on every version (Kotlin `val` emits Java
+getters), so a bag that is only READ converts safely today; it is construction that was blocked.
+`object.projection` deliberately gets no builder — it is derived and read-only, and nothing
+constructs one.
+
 **One sharp edge where generated code IS the consumer, and it is now a VERSION question rather
 than a port question: nested map values.** As of **1.0.1** every port validates them on every
 write path ([#362](https://github.com/metaobjectsdev/metaobjects/issues/362)). On **1.0.0 the

docs/RELEASING-docs-checklist.md

@@ -36,6 +36,11 @@ by exactly one release.
       scope, so there is no "as of `<ver>`" marker left to refresh (checked at the 1.0 cut).
       Re-add one here only if parity ever becomes version-scoped again.
 - [ ] `docs/RELEASING.md` / `docs/RELEASING-java.md` — the "currently `<ver>`" notes.
+- [ ] **Grep the docs for "UNRELEASED" / "on `main`, shipping in the next".** A capability
+      documented before it ships carries that hedge on purpose, and it becomes a lie the moment
+      the cut lands. `agent-context/skills/metaobjects-authoring/SKILL.md` carries one today for
+      the Kotlin builder (#365) — flip it to the shipped version and regenerate
+      `fixtures/agent-context-conformance/` in the same commit.
 - [ ] `.github/workflows/publish-*.yml` — **no version edits by design.** All four
       publish workflows read the version from the committed manifest
       (`package.json` / pom / `Directory.Build.props` / `pyproject.toml`), so none

fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.claude/skills/metaobjects-authoring/SKILL.md

@@ -585,6 +585,19 @@ Python's `ObjectManager` encodes a map today; `runtime-ts`, Java's OMDB and the
 lane carry no map handling at all. So a map you intend to read back through a PORT RUNTIME is
 still better declared as a value object, and a genuinely dynamic key set stays a bag.
 
+**One more version question, if a JAVA caller CONSTRUCTS the value object.** Kotlin's default
+arguments are a compiler feature, not a bytecode one, so a generated data class used to offer
+Java only the full N-arg constructor and a no-arg one yielding an all-null instance of an
+immutable class — a caller setting 3 of 14 members had to pass 14 arguments with 11 nulls. A
+generated VO replacing a hand-written builder therefore made its Java call sites *worse*.
+Generated entities and value objects now emit a nested `Builder` plus a `@JvmStatic builder()`
+(`Money.builder().currency("USD").build()`), so partial construction from Java works — but that
+is **UNRELEASED at the time of writing: it is on `main`, shipping in the next JVM cut.** Check
+the adopter's pinned version. Reading is unaffected on every version (Kotlin `val` emits Java
+getters), so a bag that is only READ converts safely today; it is construction that was blocked.
+`object.projection` deliberately gets no builder — it is derived and read-only, and nothing
+constructs one.
+
 **One sharp edge where generated code IS the consumer, and it is now a VERSION question rather
 than a port question: nested map values.** As of **1.0.1** every port validates them on every
 write path ([#362](https://github.com/metaobjectsdev/metaobjects/issues/362)). On **1.0.0 the

fixtures/agent-context-conformance/java-react/expected/.claude/skills/metaobjects-authoring/SKILL.md

@@ -585,6 +585,19 @@ Python's `ObjectManager` encodes a map today; `runtime-ts`, Java's OMDB and the
 lane carry no map handling at all. So a map you intend to read back through a PORT RUNTIME is
 still better declared as a value object, and a genuinely dynamic key set stays a bag.
 
+**One more version question, if a JAVA caller CONSTRUCTS the value object.** Kotlin's default
+arguments are a compiler feature, not a bytecode one, so a generated data class used to offer
+Java only the full N-arg constructor and a no-arg one yielding an all-null instance of an
+immutable class — a caller setting 3 of 14 members had to pass 14 arguments with 11 nulls. A
+generated VO replacing a hand-written builder therefore made its Java call sites *worse*.
+Generated entities and value objects now emit a nested `Builder` plus a `@JvmStatic builder()`
+(`Money.builder().currency("USD").build()`), so partial construction from Java works — but that
+is **UNRELEASED at the time of writing: it is on `main`, shipping in the next JVM cut.** Check
+the adopter's pinned version. Reading is unaffected on every version (Kotlin `val` emits Java
+getters), so a bag that is only READ converts safely today; it is construction that was blocked.
+`object.projection` deliberately gets no builder — it is derived and read-only, and nothing
+constructs one.
+
 **One sharp edge where generated code IS the consumer, and it is now a VERSION question rather
 than a port question: nested map values.** As of **1.0.1** every port validates them on every
 write path ([#362](https://github.com/metaobjectsdev/metaobjects/issues/362)). On **1.0.0 the

fixtures/agent-context-conformance/python/expected/.claude/skills/metaobjects-authoring/SKILL.md

@@ -585,6 +585,19 @@ Python's `ObjectManager` encodes a map today; `runtime-ts`, Java's OMDB and the
 lane carry no map handling at all. So a map you intend to read back through a PORT RUNTIME is
 still better declared as a value object, and a genuinely dynamic key set stays a bag.
 
+**One more version question, if a JAVA caller CONSTRUCTS the value object.** Kotlin's default
+arguments are a compiler feature, not a bytecode one, so a generated data class used to offer
+Java only the full N-arg constructor and a no-arg one yielding an all-null instance of an
+immutable class — a caller setting 3 of 14 members had to pass 14 arguments with 11 nulls. A
+generated VO replacing a hand-written builder therefore made its Java call sites *worse*.
+Generated entities and value objects now emit a nested `Builder` plus a `@JvmStatic builder()`
+(`Money.builder().currency("USD").build()`), so partial construction from Java works — but that
+is **UNRELEASED at the time of writing: it is on `main`, shipping in the next JVM cut.** Check
+the adopter's pinned version. Reading is unaffected on every version (Kotlin `val` emits Java
+getters), so a bag that is only READ converts safely today; it is construction that was blocked.
+`object.projection` deliberately gets no builder — it is derived and read-only, and nothing
+constructs one.
+
 **One sharp edge where generated code IS the consumer, and it is now a VERSION question rather
 than a port question: nested map values.** As of **1.0.1** every port validates them on every
 write path ([#362](https://github.com/metaobjectsdev/metaobjects/issues/362)). On **1.0.0 the

fixtures/agent-context-conformance/ts-react-tanstack/expected/.claude/skills/metaobjects-authoring/SKILL.md

@@ -585,6 +585,19 @@ Python's `ObjectManager` encodes a map today; `runtime-ts`, Java's OMDB and the
 lane carry no map handling at all. So a map you intend to read back through a PORT RUNTIME is
 still better declared as a value object, and a genuinely dynamic key set stays a bag.
 
+**One more version question, if a JAVA caller CONSTRUCTS the value object.** Kotlin's default
+arguments are a compiler feature, not a bytecode one, so a generated data class used to offer
+Java only the full N-arg constructor and a no-arg one yielding an all-null instance of an
+immutable class — a caller setting 3 of 14 members had to pass 14 arguments with 11 nulls. A
+generated VO replacing a hand-written builder therefore made its Java call sites *worse*.
+Generated entities and value objects now emit a nested `Builder` plus a `@JvmStatic builder()`
+(`Money.builder().currency("USD").build()`), so partial construction from Java works — but that
+is **UNRELEASED at the time of writing: it is on `main`, shipping in the next JVM cut.** Check
+the adopter's pinned version. Reading is unaffected on every version (Kotlin `val` emits Java
+getters), so a bag that is only READ converts safely today; it is construction that was blocked.
+`object.projection` deliberately gets no builder — it is derived and read-only, and nothing
+constructs one.
+
 **One sharp edge where generated code IS the consumer, and it is now a VERSION question rather
 than a port question: nested map values.** As of **1.0.1** every port validates them on every
 write path ([#362](https://github.com/metaobjectsdev/metaobjects/issues/362)). On **1.0.0 the

fixtures/agent-context-conformance/ts-requirements/expected/.claude/skills/metaobjects-authoring/SKILL.md

@@ -585,6 +585,19 @@ Python's `ObjectManager` encodes a map today; `runtime-ts`, Java's OMDB and the
 lane carry no map handling at all. So a map you intend to read back through a PORT RUNTIME is
 still better declared as a value object, and a genuinely dynamic key set stays a bag.
 
+**One more version question, if a JAVA caller CONSTRUCTS the value object.** Kotlin's default
+arguments are a compiler feature, not a bytecode one, so a generated data class used to offer
+Java only the full N-arg constructor and a no-arg one yielding an all-null instance of an
+immutable class — a caller setting 3 of 14 members had to pass 14 arguments with 11 nulls. A
+generated VO replacing a hand-written builder therefore made its Java call sites *worse*.
+Generated entities and value objects now emit a nested `Builder` plus a `@JvmStatic builder()`
+(`Money.builder().currency("USD").build()`), so partial construction from Java works — but that
+is **UNRELEASED at the time of writing: it is on `main`, shipping in the next JVM cut.** Check
+the adopter's pinned version. Reading is unaffected on every version (Kotlin `val` emits Java
+getters), so a bag that is only READ converts safely today; it is construction that was blocked.
+`object.projection` deliberately gets no builder — it is derived and read-only, and nothing
+constructs one.
+
 **One sharp edge where generated code IS the consumer, and it is now a VERSION question rather
 than a port question: nested map values.** As of **1.0.1** every port validates them on every
 write path ([#362](https://github.com/metaobjectsdev/metaobjects/issues/362)). On **1.0.0 the