docs: reconcile Java schema-migration removal (TS-only migrations)

Updates the docs and one stale code comment to reflect that schema migrations
(and live-DB schema-drift verification) are owned by the TypeScript toolchain
(@metaobjectsdev/cli migrate), and that the Java diff-and-converge engine +
meta:migrate / meta:verify Maven goals were removed.

- CLAUDE.md: Java bullet now lists meta:gen / meta:editor; FR-003 / key-features
  lines note migrations are TS-only. (The TS-CLI `meta migrate` "Useful commands"
  block is left as-is — that is the TS CLI.)
- spec/roadmap.md: Java-port + FR-003 entries reconciled; persistence-conformance
  row notes Java is query-only.
- docs/ports/java.md: intro, the pom example (drop the verify execution), the
  Generate section, the Verify.verify note, the capability matrix, and the
  conformance table all updated.
- server/java/codegen-kotlin/README.md: drift-detection table + a new
  "Schema migrations" section replace the meta:migrate/meta:verify claims.
- fixtures/persistence-conformance/README.md: note that Java does not run the
  migration scenarios.
- RecoverSchemaEmitter.java: drop a Javadoc cross-reference to the deleted
  ExpectedSchemaBuilder (behavioral note kept).

Full reactor `mvn test` green; integration-tests green under Docker.

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

Author: dmealing

CLAUDE.md

@@ -25,7 +25,7 @@ _Last refreshed 2026-05-27._
 
 - **TypeScript** — `codegen-ts` (Vite-style plugins; Drizzle, Zod, Fastify) + `runtime-ts` + `migrate-ts` + the universal web client packages (`runtime-web`, `react`, `tanstack`).
 - **C#** — `MetaObjects` (loader + canonical serializer + conformance) + `MetaObjects.Render` (Mustache + payload-VO + `verify`) + `MetaObjects.Codegen` (EF Core entities + `AppDbContext` + CRUD minimal-API routes + Postgres DDL via full-CREATE and incremental introspect/diff/migrate). The `meta` CLI (`verify`/`gen`/`migrate`/`--from-db`) is the entry point.
-- **Java** — `metadata` + `omdb` + `om` + `dynamic` + `core-spring` + `metadata-ktx` (Kotlin facade) + `codegen-spring` (Spring controllers + DTOs + repositories + filter allowlists + payload records + output parsers) + `codegen-mustache` + `codegen-plantuml` + `render` + `maven-plugin` (`meta:gen`/`meta:migrate`/`meta:verify`). FR-003 (OMDB persistence + diff-and-converge migration + binding registry + typed jsonb + Spring-tx + source/origin metamodel) fully shipped, including Plan 4 (engine-debt remediation: atomic mapping cache, JDBC codec registry, `inTransaction` template).
+- **Java** — `metadata` + `omdb` + `om` + `dynamic` + `core-spring` + `metadata-ktx` (Kotlin facade) + `codegen-spring` (Spring controllers + DTOs + repositories + filter allowlists + payload records + output parsers) + `codegen-mustache` + `codegen-plantuml` + `render` + `maven-plugin` (`meta:gen`/`meta:editor`). FR-003 (OMDB runtime persistence + binding registry + typed jsonb + Spring-tx + source/origin metamodel) fully shipped, including Plan 4 (engine-debt remediation: atomic mapping cache, JDBC codec registry, `inTransaction` template). **Schema migrations are owned by the TypeScript toolchain** (`@metaobjectsdev/cli migrate`); the Java port's diff-and-converge migration engine and its `meta:migrate` / live-DB-drift `meta:verify` Maven goals were removed — OMDB retains runtime persistence + a dev/test runtime auto-create path (`MetaClassDBValidatorService` + the drivers' legacy `createTable` DDL) only.
 - **Python** — `metaobjects` (loader + canonical serializer + conformance + render + verify + codegen) + `migrate` + an `ObjectManager` runtime layer. All five conformance corpora green.
 - **Kotlin** — `codegen-kotlin` (KotlinPoet on JVM): entity + Exposed table + Spring controller + payload + relations + filter allowlist + validator + stored-proc + output-parser generators. `integration-tests-kotlin` runs the persistence-conformance corpus through Exposed against Testcontainers Postgres.
 
@@ -36,7 +36,7 @@ _Last refreshed 2026-05-27._
 - API-contract: `fixtures/api-contract-conformance/`. TS / C# / Java / Kotlin / Python all 20/20.
 - YAML / verify corpora green across the ports that ship those layers.
 
-**Key cross-language features shipped:** FR5 family (a/b/c/d/e + WARN envelope-shape — actionable loader errors per ADR-0009); FR-003 (Java RDB persistence + meta migrate + projections); FR-006 (template.output parser-on-receipt codegen per ADR-0010 in all 5 ports); FR-008 + FR-009 (cross-port REST API contract + 10 filter operators); source v2 paradigm (ADR-0007); metadata-ktx Kotlin facade; per-target output directories (TS codegen).
+**Key cross-language features shipped:** FR5 family (a/b/c/d/e + WARN envelope-shape — actionable loader errors per ADR-0009); FR-003 (Java RDB runtime persistence + projections; schema migrations are TS-only — the Java migration engine was removed); FR-006 (template.output parser-on-receipt codegen per ADR-0010 in all 5 ports); FR-008 + FR-009 (cross-port REST API contract + 10 filter operators); source v2 paradigm (ADR-0007); metadata-ktx Kotlin facade; per-target output directories (TS codegen).
 
 **Current release line.** `0.7.0-rc.2` accumulates the 0.6.x → 0.7.0 consumer-friction batch (stock `promptRender()` generator, `db`-parameter generated repo helpers per ADR-0008, Cloudflare Workers deploy recipe, CHANGELOG backfill + naming-convention docs) plus the FR5 + FR-003 Plan 4 + FR-006 Java work. GA promotion is the next release move.
 

docs/ports/java.md

@@ -1,9 +1,14 @@
 # Java port
 
 The Java port targets Spring-Boot consumers on Maven. It ships the full metamodel
-+ loader + conformance + OMDB persistence engine + the FR-004 render engine, plus
-the `metaobjects-maven-plugin` for build-time codegen + drift verification +
-migration emission.
++ loader + conformance + OMDB runtime persistence engine + the FR-004 render engine,
+plus the `metaobjects-maven-plugin` for build-time codegen (`meta:gen` / `meta:editor`).
+
+Schema migrations are owned by the TypeScript toolchain (`@metaobjectsdev/cli migrate`);
+the Java diff-and-converge migration engine and its `meta:migrate` / live-DB-drift
+`meta:verify` Maven goals were removed. OMDB retains runtime persistence and a
+dev/test runtime auto-create path (`MetaClassDBValidatorService`) only. Prompt /
+template drift is still checked via the `metaobjects-render` `Verify` API.
 
 ## Install
 
@@ -58,11 +63,6 @@ For Spring integration: add `metaobjects-core-spring`.
             </generators>
           </configuration>
         </execution>
-        <execution>
-          <id>verify</id>
-          <phase>verify</phase>
-          <goals><goal>verify</goal></goals>
-        </execution>
       </executions>
     </plugin>
   </plugins>
@@ -135,12 +135,13 @@ in tests or embedded scenarios. The conceptual reference lives in
 
 ```bash
 mvn compile                  # runs the generate goal (bound to generate-sources)
-mvn meta:migrate             # emit a migration SQL file
-mvn meta:migrate -Dflyway=true  # emit V<N>__<slug>.sql under src/main/resources/db/migration/
-mvn meta:verify              # introspect live DB; fail if drifted
-mvn verify                   # full verify phase (incl. meta:verify)
 ```
 
+Schema migrations are not a Java-port concern — author them with the TypeScript
+toolchain (`@metaobjectsdev/cli migrate`). OMDB's runtime auto-create path can
+bootstrap a dev/test schema at startup (`MetaClassDBValidatorService` with
+`autoCreate=true`), but it is not a migration tool.
+
 ## Use
 
 OMDB reads the same metadata at runtime and drives CRUD; no per-entity ORM
@@ -201,7 +202,8 @@ String out = Renderer.render(RenderRequest.builder()
 ```
 
 `Verify.verify(loader, provider, options)` drift-checks every `template.*` node
-against its `@payloadRef`. Wire it into a Maven test or the `verify` goal.
+against its `@payloadRef`. Wire it into a Maven test (e.g. a JUnit assertion in
+the `test` phase).
 
 ## Generators
 
@@ -245,8 +247,8 @@ configuration model that has not yet been specced.
 | Templates + render (FR-004) | Yes (`metaobjects-render`) |
 | Payload-VO codegen | Yes — `SpringPayloadGenerator` (in `metaobjects-codegen-spring`) emits a Java 21 `record` per template, mirrors the Kotlin shape |
 | Output parser codegen (FR-006) | Not yet — see note below |
-| Migrations | `mvn meta:migrate` / `mvn meta:migrate -Dflyway=true` |
-| Drift verify | `mvn meta:verify` (DB) + `Renderer.verify` (prompts) |
+| Migrations | TS-only (`@metaobjectsdev/cli migrate`) — the Java engine was removed; OMDB offers runtime auto-create for dev/test only |
+| Drift verify | `Renderer.verify` / `Verify.verify` (prompts). Live-DB schema-drift verification is part of the TS migration toolchain |
 | Runtime metadata | Full — OMDB ObjectManager |
 | REST controller codegen | Spring Web MVC — `metaobjects-codegen-spring` (FR-008 §2.1) |
 
@@ -267,7 +269,7 @@ that ships, the Jackson one-liner pairs naturally with the generated record.
 | YAML authoring (`fixtures/yaml-conformance/`) | 12 / 13 (1 ledgered — `yaml-quoted-leading-zero`, Java pipeline strips quotes off `"007"`) |
 | Render (`fixtures/render-conformance/`) | 14 / 14 |
 | Verify (`fixtures/verify-conformance/`) | 31 / 31 |
-| Persistence (`fixtures/persistence-conformance/`) | 12 / 12 |
+| Persistence (`fixtures/persistence-conformance/`) | Query scenarios 9 / 10 (1 deferred: aggregate-projection view body was part of the removed migration engine). Java no longer runs the migration scenarios. |
 | API contract (`fixtures/api-contract-conformance/`) | 20 / 20 |
 
 ## See also

fixtures/persistence-conformance/README.md

@@ -34,6 +34,11 @@ fixtures/persistence-conformance/
 Test the schema-evolution pipeline. Each scenario carries its own metadata
 states; the runner applies the migration and asserts SQL and / or post-DDL state.
 
+> The **Java** port does not run the migration scenarios: schema migrations are
+> owned by the TypeScript toolchain and the Java diff-and-converge engine was
+> removed. The Java runner exercises the **query** scenarios only, bootstrapping
+> the schema via OMDB's runtime auto-create path.
+
 ```yaml
 name: add-nullable-column-to-existing-table
 description: A new nullable column on an existing table → ADD COLUMN, no allow flags.

server/java/codegen-kotlin/README.md

@@ -148,16 +148,17 @@ No hand-written Exposed wiring needed.
 |---|---|---|
 | Code-vs-DB | Codegen (`KotlinEntityGenerator` + `KotlinExposedTableGenerator`) | Build time |
 | Code-vs-API-doc | Cross-port codegen from same metadata | Build time |
-| DB-vs-metadata | `meta:verify` Maven goal | CI on every PR |
-| Migration-vs-metadata | `meta:migrate --flyway` emits migrations FROM metadata diffs | Build time |
+| DB-vs-metadata, Migration-vs-metadata | TypeScript toolchain (`@metaobjectsdev/cli migrate`) — schema migrations and live-DB schema-drift verification are TS-only | Build time / CI |
 | Generated-edited | `@generated` headers in KotlinPoet output | Code review |
 | Prompt-vs-payload | `KotlinPayloadGenerator` + Java `Renderer.verify` | Build time + runtime |
 | Generated-vs-runtime | `MetadataStartupValidator.validate(loader)` from Spring `ApplicationReadyEvent` | App startup |
 
-## Maven plugin extensions
+## Schema migrations
 
-- **`meta:migrate --flyway`** — emits `V<N>__<slug>.sql` into `src/main/resources/db/migration/` (configurable via `<flywayDir>` / `<flywayPrefix>`). Auto-versions by scanning existing migrations.
-- **`meta:verify`** — CI drift gate: introspects the live DB and fails the build if it has drifted from metadata-declared schema.
+Schema migrations (and live-DB schema-drift verification) are owned by the
+TypeScript toolchain (`@metaobjectsdev/cli migrate`). The JVM-side Maven plugin's
+`meta:migrate` / `meta:verify` goals were removed along with the Java
+diff-and-converge engine; the Maven plugin ships `meta:gen` / `meta:editor` only.
 
 ## Cross-port codegen conformance (deferred)
 

server/java/codegen-spring/src/main/java/com/metaobjects/generator/spring/RecoverSchemaEmitter.java

@@ -229,7 +229,7 @@ private static String constructorArgForField(MetaField<?> field) {
     /**
      * Returns {@code true} when the field carries {@code @required: true}.
      * Uses {@code getValueAsString()} to handle both the Boolean-attribute and
-     * String-attribute storage paths (mirrors {@code ExpectedSchemaBuilder.isRequired}).
+     * String-attribute storage paths.
      */
     private static boolean isRequired(MetaField<?> field) {
         return field.hasMetaAttr(MetaField.ATTR_REQUIRED)

spec/roadmap.md

@@ -19,23 +19,23 @@ _Last refreshed 2026-05-30._
 
 - **TypeScript** — `@metaobjectsdev/metadata` + `codegen-ts` (Vite-style plugins) + `runtime-ts` + `migrate-ts` + the universal web client packages (`runtime-web`, `react`, `tanstack`). The reference port for everything cross-language.
 - **C# full-stack target** — `MetaObjects` (loader + canonical serializer + conformance) + `MetaObjects.Render` (Mustache + payload-VO codegen + `verify`) + `MetaObjects.Codegen` (EF Core entities + `AppDbContext`/owned-types via `OwnsOne` + CRUD minimal-API routes + Postgres DDL with full-CREATE + incremental introspect/diff/migrate via `meta migrate --from-db`).
-- **Java port** — `metadata` + `omdb` + `om` + `dynamic` + `core-spring` + `metadata-ktx` (Kotlin facade) + `codegen-spring` (Spring REST controllers + DTOs + repos + filter allowlists) + `codegen-mustache` + `codegen-plantuml` + `codegen-base` + `render` + `maven-plugin` (with `meta:gen` / `meta:migrate` / `meta:verify`).
+- **Java port** — `metadata` + `omdb` + `om` + `dynamic` + `core-spring` + `metadata-ktx` (Kotlin facade) + `codegen-spring` (Spring REST controllers + DTOs + repos + filter allowlists) + `codegen-mustache` + `codegen-plantuml` + `codegen-base` + `render` + `maven-plugin` (with `meta:gen` / `meta:editor`; schema migrations are owned by the TS toolchain — the Java diff-and-converge engine and its `meta:migrate` / live-DB-drift `meta:verify` goals were removed).
 - **Kotlin** — `codegen-kotlin` (KotlinPoet on JVM): entity + Exposed table + Spring controller + Spring config + payload + relations + filter allowlist + validator + stored-proc + output-parser generators; `integration-tests-kotlin` runs the persistence-conformance corpus through Exposed against Testcontainers Postgres.
 - **Python port** — `metaobjects` (metadata loader + canonical serializer + conformance) + `migrate` + `ObjectManager` runtime + render (Mustache) + output-parser codegen.
 
 ### Cross-port conformance corpora (every port runs the shared corpus)
 
 - **Metamodel conformance** — `fixtures/conformance/` (~90 fixtures + CAPABILITIES manifest). TS / C# / Java / Python all green.
 - **Render conformance** — `fixtures/render-conformance/`. TS / C# / Java / Kotlin / Python byte-identical.
-- **Persistence conformance** — `fixtures/persistence-conformance/`. TS / C# / Java / Kotlin / Python all 12/12 against Testcontainers Postgres / Derby (per port).
+- **Persistence conformance** — `fixtures/persistence-conformance/`. TS / C# / Kotlin / Python all 12/12 against Testcontainers Postgres / Derby (per port). Java runs the **query** scenarios only (it no longer owns schema migrations); its runtime auto-create path bootstraps the schema, and the aggregate-projection view scenario is deferred (the view-body builder was part of the removed migration engine).
 - **API-contract conformance** — `fixtures/api-contract-conformance/`. TS / C# / Java / Kotlin / Python all 20/20.
 - **Recover conformance** — `fixtures/recover-conformance/` (10 dirty-input cases). TS / C# / Java / Python all 10/10; Kotlin reuses the shared JVM engine.
 - **YAML / verify** corpora — green across the ports that ship those layers.
 
 ### Key cross-language features
 
 - **Source v2 paradigm** — `source.rdb` + `@kind: table|view|materializedView|storedProc|tableFunction`; multi-source via `@role`. ADR-0007.
-- **FR-003 — Java RDB persistence, schema migration & projections** (Plans 1/2/3/4a + Plan 4): port of `dynamic`/`om`/`omdb` onto current core; build-time FQN-keyed binding registry + typed jsonb value-objects + Spring-tx connection; decoupled `meta migrate` engine (diff-and-converge) with `SchemaMigrationEngine` + introspector + emitter; `source.*`+`origin.*` metamodel registered in Java; OMDB engine-debt remediation (atomic mapping cache, JDBC codec registry per ADR-0002, `inTransaction` template).
+- **FR-003 — Java RDB persistence & projections** (Plans 1/2/3/4a + Plan 4): port of `dynamic`/`om`/`omdb` onto current core; build-time FQN-keyed binding registry + typed jsonb value-objects + Spring-tx connection; `source.*`+`origin.*` metamodel registered in Java; OMDB engine-debt remediation (atomic mapping cache, JDBC codec registry per ADR-0002, `inTransaction` template). The diff-and-converge schema-migration engine that originally shipped under FR-003 (`SchemaMigrationEngine` + introspector + emitter + the `meta:migrate` goal) was **removed** when schema migrations consolidated onto the TS toolchain (`@metaobjectsdev/cli migrate`); the Java port retains runtime persistence + a dev/test runtime auto-create path only.
 - **FR5 family — actionable loader errors** (a/b/c/d/e + WARN envelope-shape). ADR-0009.
   - FR5a: source-on-node + envelope-shaped errors (`format` ∈ `json|yaml|merged|resolved|database|code`)
   - FR5b: YAML source positions on yaml-input envelopes