Merge docs-cleanup: correct stale Java/Kotlin migration + drift docs

Recent removals left user-facing docs referencing gone Java/Kotlin Maven goals.
Fixes: meta:migrate / live-DB meta:verify (removed for Java; Kotlin's via-Java path
gone) → schema migrations owned by the TS toolchain (@metaobjectsdev/cli migrate;
--apply/--rollback/verify --db); Java codegen target jOOQ → codegen-spring; migrate-ts
README apply/ledger shipped (no longer "not yet"); cli README documents --rollback.
Conservative — does NOT over-claim the cross-port single-engine consolidation (C#/Python
still own their migrate; only Java was removed). 8 docs.

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

Author: dmealing

README.md

@@ -40,8 +40,8 @@ working code.
 | `field.object` + `@storage=flattened` | Yes | Yes | Yes (per-sub-field columns) | Yes (EF Core `OwnsOne`) | Loader yes; codegen partial |
 | Templates + render (FR-004) | Yes | Yes | Yes (wraps Java) | Yes | Yes |
 | Payload-VO codegen | Yes (via projection) | – (consumers use `Map`) | Yes (`@Serializable`) | Yes | – (consumers use `dict`) |
-| Migration emission | `meta migrate` (Postgres / SQLite / D1) | `mvn meta:migrate --flyway` | `mvn meta:migrate --flyway` (via Java) | `meta migrate` | In progress |
-| DB-drift verify | `meta verify` | `mvn meta:verify` | `mvn meta:verify` (via Java) + startup validator | `meta verify` | In progress |
+| Migration emission | `meta migrate` (Postgres / SQLite / D1) | Via TS toolchain (`@metaobjectsdev/cli migrate`) | Via TS toolchain (`@metaobjectsdev/cli migrate`) | `meta migrate` | In progress |
+| DB-drift verify | `meta verify --db` | Template-drift: `Renderer.verify`; startup: `MetaClassDBValidatorService` | Template-drift: `Renderer.verify`; startup: `MetadataStartupValidator` | `meta verify` | In progress |
 | Template-drift verify | Yes | Yes (`Renderer.verify`) | Yes (via Java) | Yes (`meta verify`) | Yes (`metaobjects.render.verify`) |
 | YAML authoring (sigil-free → JSON) | Yes | Yes | Yes (via Java) | Yes | Yes |
 | Runtime metadata (ObjectManager-style) | Yes (`runtime-ts`) | Yes (OMDB) | Yes (via Java OMDB + Exposed) | Roadmap | Roadmap |

docs/features/migrations-and-drift.md

@@ -13,8 +13,8 @@ There are **7 drift sources**, and the toolchain has a guard for each.
 |---|---|---|
 | **Code-vs-DB** | Codegen — the generated SQL DDL is emitted from the same metadata as the entity / table code. | Build time |
 | **Code-vs-API-doc** | Cross-port codegen from the same metadata. | Build time |
-| **DB-vs-metadata** | `meta:verify` Maven goal / `meta verify` CLI — introspects the live DB and fails the build if it has drifted from metadata. | CI on every PR |
-| **Migration-vs-metadata** | `meta migrate` (TS / C#) / `meta:migrate --flyway` (Java / Kotlin) emits migrations FROM metadata diffs — they cannot drift from metadata by construction. | Build time |
+| **DB-vs-metadata** | `meta verify --db` (TS CLI) — introspects the live DB and fails if it has drifted from metadata. Java/Kotlin: runtime startup validator (`MetaClassDBValidatorService`) catches generated-table drift at app startup; the removed `meta:verify` Maven goal is not available. | CI on every PR (TS); app startup (Java/Kotlin) |
+| **Migration-vs-metadata** | `meta migrate` (TS / C# / Python) emits migrations FROM metadata diffs — they cannot drift from metadata by construction. Java/Kotlin schema migrations are also owned by the TS toolchain (`@metaobjectsdev/cli migrate`). | Build time |
 | **Generated-edited** | `@generated` headers in emitted code + three-way merge that preserves hand-edits inside non-generated regions. | Code review |
 | **Prompt-vs-payload** | FR-004 `Renderer.verify` parses `{{...}}` references in templates and checks each one exists on the payload VO. | Build time + runtime |
 | **Generated-vs-runtime** | Kotlin / Java `MetadataStartupValidator` (from Spring `ApplicationReadyEvent`) re-loads metadata at startup and asserts the generated table objects match. | App startup |
@@ -57,21 +57,28 @@ configured in `metaobjects.config.ts` (typically `./migrations/<timestamp>__<slu
 
 ### Java
 
+Schema migrations for Java projects are owned by the **TypeScript toolchain**
+(`@metaobjectsdev/cli migrate`). The Java Maven plugin's `meta:migrate` goal was
+removed. Java retains a dev/test runtime auto-create path via
+`MetaClassDBValidatorService` (the drivers' `createTable` DDL), not a migration
+engine.
+
+Use the TS CLI against the same database the Java service connects to:
+
 ```bash
-mvn meta:migrate                      # writes a numbered SQL file
-mvn meta:migrate -Dflyway=true        # writes V<N>__<slug>.sql under src/main/resources/db/migration/
+meta migrate --db postgresql://... --slug initial   # emit migration SQL
+meta migrate --db postgresql://... --apply          # apply pending migrations
 ```
 
-Flyway mode auto-versions by scanning existing migrations.
-
 ### Kotlin
 
-Uses the Java Maven plugin's `meta:migrate` mojo (Kotlin codegen tier rides on the
-same plugin). Flyway prefix + directory are configurable via the plugin's
-`<flywayDir>` / `<flywayPrefix>` parameters.
+Kotlin schema migrations follow the same story as Java: the Java Maven plugin's
+`meta:migrate` mojo was removed and there is no Kotlin-specific migrate command.
+Schema migrations are owned by the TS toolchain:
 
 ```bash
-mvn meta:migrate -Dflyway=true
+meta migrate --db postgresql://... --slug initial
+meta migrate --db postgresql://... --apply
 ```
 
 ### C#
@@ -100,9 +107,9 @@ for current status.)
 
 | Port | Command | What it does |
 |---|---|---|
-| TypeScript | `meta verify` | Re-runs codegen as a no-op; reports DB-vs-metadata drift. |
-| Java | `mvn meta:verify` | Introspects the live DB; fails the build if schema differs from metadata. |
-| Kotlin | `mvn meta:verify` | Same as Java (shared Maven plugin). |
+| TypeScript | `meta verify --db` | Introspects the live DB; reports DB-vs-metadata drift. |
+| Java | `Renderer.verify` (build-time) + `MetaClassDBValidatorService` (startup) | Template-drift: verifies `{{...}}` references resolve against the payload VO. Live-DB-schema drift: startup validator asserts generated table objects match metadata. The `meta:verify` Maven goal (live-DB introspection) was removed. |
+| Kotlin | `Renderer.verify` (build-time) + `MetadataStartupValidator` (startup) | Same as Java — template-drift and startup validation. No `meta:verify` Maven goal. |
 | C# | `meta verify ./metadata --templates ./prompts` | Drift-checks templates against their payload VOs (FR-004 prompt-drift). |
 | Python | `python -m metaobjects.render.verify` | Same as C# verify — template-vs-payload drift. |
 

docs/features/source-kinds.md

@@ -134,9 +134,9 @@ export type AuthorView = z.infer<typeof AuthorViewSchema>;
 ### Java
 
 OMDB resolves the physical name via `@table`; `@kind: "view"` flips the entity to
-read-only at the ObjectManager layer (mutating ops throw). The `meta:migrate`
-goal emits the `CREATE VIEW` body from the `origin.*` aggregate / passthrough
-metadata.
+read-only at the ObjectManager layer (mutating ops throw). The `CREATE VIEW` body
+is emitted by the TS toolchain (`meta migrate`) from the `origin.*` aggregate /
+passthrough metadata; the `meta:migrate` Maven goal was removed.
 
 ```java
 // OMDB ObjectManager — exact API:
@@ -149,8 +149,8 @@ List<AuthorView>  views   = om.getObjectsBy(AuthorView.class, /* filter */);
 
 `KotlinExposedTableGenerator` generates an Exposed `Table` object for `@kind:
 "table"`. For `@kind: "view"` it generates a read-only `Table` wrapper with the
-same column mapping; the codegen-generated `meta:migrate --flyway` emits the
-`CREATE VIEW` body.
+same column mapping; the `CREATE VIEW` body is emitted by the TS toolchain
+(`meta migrate`) — the `meta:migrate` Maven goal was removed.
 
 ```kotlin
 // generated/acme/blog/AuthorViewTable.kt — read-only

docs/ports/kotlin.md

@@ -127,10 +127,11 @@ reference covers the cross-port contract.
 
 ```bash
 mvn compile                            # runs the codegen as part of generate-sources
-mvn meta:migrate -Dflyway=true         # emit V<N>__<slug>.sql under src/main/resources/db/migration/
-mvn meta:verify                        # DB-vs-metadata drift gate
 ```
 
+Schema migrations are owned by the TypeScript toolchain — see the
+[Migrations section](../features/migrations-and-drift.md#kotlin) for the `meta migrate` commands.
+
 ## Use
 
 For the `Author` example (see [entities.md](../features/entities.md)), the codegen
@@ -283,8 +284,8 @@ the contract is universal.
 |---|---|---|
 | Code-vs-DB | `KotlinEntityGenerator` + `KotlinExposedTableGenerator` (one metadata, two emitters) | 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 from metadata diffs | Build time |
+| DB-vs-metadata | `MetadataStartupValidator.validate(loader)` at Spring `ApplicationReadyEvent`; live-DB schema drift: TS toolchain `meta verify --db` | App startup; CI on every PR (TS) |
+| Migration-vs-metadata | TS toolchain `meta migrate` emits from metadata diffs (`meta:migrate` Maven goal was removed) | Build time |
 | Generated-edited | `@generated` KotlinPoet headers | Code review |
 | Prompt-vs-payload | `KotlinPayloadGenerator` + Java `Renderer.verify` | Build time + runtime |
 | Generated-vs-runtime | `MetadataStartupValidator.validate(loader)` from Spring `ApplicationReadyEvent` | App startup |
@@ -301,8 +302,8 @@ the contract is universal.
 | Templates + render (FR-004) | Yes (wraps the Java engine) |
 | Output parser codegen (FR-006) | Yes (`KotlinOutputParserGenerator` — kotlinx.serialization + `Result<T>` dual API) |
 | Payload-VO codegen | Yes (`KotlinPayloadGenerator`) |
-| Migrations | Via Java `meta:migrate --flyway` |
-| Drift verify | Via Java `meta:verify` + startup validator |
+| Migrations | Via the TS toolchain (`@metaobjectsdev/cli migrate`) |
+| Drift verify | Template-drift: `Renderer.verify` (build-time); generated-table drift: `MetadataStartupValidator` (startup) |
 | Runtime metadata | Via Java OMDB (or hand-written Exposed transactions) |
 
 ## Test count

server/java/README.md

@@ -9,8 +9,8 @@ For the standard itself (metamodel, conformance corpora, ADRs) see the [reposito
 All four MetaObjects pillars ship across all five language ports — TypeScript, Java, Kotlin, C#, Python. Java's contributions:
 
 - **Codegen** — Spring REST + DTO + JPA repository emit (`codegen-spring`), Mustache template engine (`codegen-mustache`), PlantUML diagrams (`codegen-plantuml`), and a Kotlin emit pipeline on KotlinPoet (`codegen-kotlin`). Output is hand-edit-preserving via three-way merge.
-- **Runtime metadata** — OMDB persistence layer over modernized JDBC with Spring-`@Transactional` integration. FR-003 fully shipped: diff-and-converge migration, binding registry, typed jsonb codec, source/origin metamodel, atomic mapping cache + JDBC codec registry + `inTransaction` template (Plan 4).
-- **Drift detection** — `mvn meta:verify` covers entity codegen, prompt templates, output parsers, and database schema.
+- **Runtime metadata** — OMDB persistence layer over modernized JDBC with Spring-`@Transactional` integration. FR-003 fully shipped: binding registry, typed jsonb codec, source/origin metamodel, atomic mapping cache + JDBC codec registry + `inTransaction` template (Plan 4). Schema migrations are owned by the TypeScript toolchain (`@metaobjectsdev/cli migrate`); the `meta:migrate` Maven goal was removed. OMDB retains a dev/test runtime auto-create path (`MetaClassDBValidatorService`).
+- **Drift detection** — Template-drift: `Renderer.verify` checks `{{...}}` references against the payload VO at build time. Generated-table drift: `MetaClassDBValidatorService` asserts at startup. The live-DB-schema `meta:verify` Maven goal was removed.
 - **Prompt construction** — `metaobjects-render` (Mustache + payload-VO + verify), FR-006 `template.output` parser-on-receipt codegen, render output byte-identical with the other four ports against the shared render-conformance corpus.
 
 Fully green across all five cross-port conformance corpora: metamodel (85), yaml (6), persistence (12 against Testcontainers Postgres), render (4), verify (31).

server/typescript/packages/cli/README.md

@@ -102,6 +102,8 @@ Flags:
 - `--allow <csv>` — destructive-change permissions: `drop-column,drop-table,type-change,drop-index,drop-fk,nullable-to-not-null`
 - `--on-ambiguous abort|rename|drop-add` (default `abort`) — non-interactive
 - `--dry-run` — print SQL pair to stdout, write nothing
+- `--apply` — after writing migration files, immediately apply all pending migrations against the DB (runs `up.sql` for each unapplied entry, tracked in the migration ledger). Mutually exclusive with `--rollback`. Postgres and SQLite only (D1 uses `--apply` to invoke `wrangler d1 migrations apply` instead).
+- `--rollback <version>` — roll back applied migrations newer than `<version>` by running their `down.sql` in reverse order, ledger-tracked. Pass an empty string (`--rollback ""`) to roll back everything. Mutually exclusive with `--apply`. Postgres and SQLite only.
 
 **D1-specific flags** (only relevant with `--dialect d1`):
 - `--d1 <binding>` — explicit D1 binding from `wrangler.toml` (auto-detected when there's exactly one)

server/typescript/packages/migrate-ts/README.md

@@ -5,7 +5,7 @@ Schema migration tool for MetaObjects-driven projects.
 Compares loaded MetaObjects metadata against a live Postgres or SQLite (libsql/Turso) database
 and emits paired `up.sql` + `down.sql` migration files.
 
-**Status:** v0.3. TS reference implementation; emits migration SQL but does not yet apply against the DB.
+**Status:** v0.3. TS reference implementation. Emits migration SQL, applies pending migrations against the DB (`--apply`), and tracks migration history via a ledger table.
 
 ## Install
 
@@ -97,8 +97,6 @@ Targets Cloudflare D1 via the wrangler CLI. Connection is read from `wrangler.to
 
 ## Not yet shipped
 
-- `meta migrate --apply` (apply migrations against the DB).
-- Migration history table.
 - Triggers, generated columns, partial indexes, exclusion constraints, check constraints.
 - MySQL.
 - Data migrations (column-type changes that need data transformation: error with hint).

spec/README.md

@@ -6,7 +6,7 @@ The cross-language design documentation for the MetaObjects standard. This direc
 
 A typed metadata standard for declaring entity models, identities, relationships, validations, views, layouts, and storage sources -- once, in a canonical form, then consumed by:
 
-- **Code generators** that emit idiomatic per-language code (Drizzle/Zod + Fastify on TypeScript, JOOQ/Spring on Java, Pydantic/FastAPI on Python).
+- **Code generators** that emit idiomatic per-language code (Drizzle/Zod + Fastify on TypeScript, Spring controllers + DTOs + repos via `codegen-spring` on Java, Pydantic/FastAPI on Python).
 - **Runtime loaders** that read the metadata at runtime to drive CRUD, validation, relationships, dynamic admin UIs, and LLM tool registration.
 - **Drift checks** that flag divergence between code and metadata via compile-time breakage in the type checker and through `meta migrate` against live databases.
 - **Prompt construction** *(the fourth pillar — planned for 7.0.0)* that makes an LLM prompt a declared, deterministic, testable artifact instead of a scattered string: a typed payload declared as a projection (so payload bloat is visible), external provider-resolved prompt text, a deterministic render that is snapshot-testable and cache-stable, and build-time prompt↔payload drift detection — conformance-gated so the guarantee holds in every language port. See the FR-004 design doc under [`../docs/superpowers/specs/`](../docs/superpowers/specs/).