Merge omdb-spring-boot-starter: Spring Boot 3 starter + OMDB autoconfiguration

- Fix dead Boot 3 autoconfiguration registration (AutoConfiguration.imports;
  drop legacy spring.factories); strip OSGi remnants from core-spring.
- DatabaseDriverResolver (dialect override + JDBC product auto-detect).
- ObjectManager autoconfiguration: builds a transaction-aware ObjectManagerDB
  from a Spring DataSource (SpringObjectManagerDB + SpringObjectConnections),
  gated by @ConditionalOnBean(DataSource)/@ConditionalOnMissingBean; +
  metaobjects.omdb.* properties; metaobjects.metadata-sources now autoconfigured.
- New thin metaobjects-spring-boot-starter module (metadata + omdb + core-spring).
- Virtual-thread audit documented (OMDB does not pin carriers); jOOQ recorded
  as a closed non-goal.

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

Author: dmealing

CLAUDE.md

@@ -505,6 +505,6 @@ See `spec/roadmap.md` for current and planned work across the H1-H10 project ser
 ## Open questions
 
 - [TECHNICAL] Field-type → Drizzle-column-type mapping table (needed for complete TS codegen coverage).
-- [TECHNICAL] ObjectManagerDB further modernization (jOOQ migration, Spring Boot 3 starter, async via virtual threads). FR-003 Plan 4 (2026-05-27) closed the three engine-debt anti-patterns identified at the time — atomic mapping cache off shared `MetaObject`, JDBC codec registry replacing the type ladders (ADR-0002), and `inTransaction` template method. The remaining items above are larger architectural moves rather than near-term cleanups.
+- [TECHNICAL] ObjectManagerDB further modernization. FR-003 Plan 4 (2026-05-27) closed the three engine-debt anti-patterns. The Spring Boot 3 starter + OMDB autoconfiguration + virtual-thread audit shipped 2026-05-30 (`metaobjects-spring-boot-starter`). **jOOQ migration is a closed non-goal**: jOOQ's OSS edition excludes Oracle/SQL Server/DB2 (commercial license required), which would paywall OMDB's commercial-DB drivers in a public OSS project, and jOOQ generates code *from* a schema — the inverse of MetaObjects' metadata-is-the-spine model.
 - [TECHNICAL] Payload `origin.*` resolution in `codegen-spring` (Day-1 deferral — see `server/java/codegen-spring/src/main/java/com/metaobjects/generator/spring/KNOWN_GAPS.md`). Kotlin's `KotlinPayloadGenerator` is the cross-port reference.
 - [TECHNICAL] WARN envelope-shape assertion on cross-port `expected-warnings.json` (closed 2026-05-27 — runners now assert envelope shape on warnings; legacy string-list path retired).

docs/superpowers/plans/2026-05-30-omdb-spring-boot-starter.md

@@ -0,0 +1,166 @@
+# OMDB Spring Boot 3 Starter + Autoconfiguration — Design
+
+_Date: 2026-05-29_
+
+## Problem
+
+The Java port's Spring integration (`core-spring`) registers its autoconfiguration
+**only** through the legacy Boot 2.x `META-INF/spring.factories`
+`EnableAutoConfiguration` key. **Spring Boot 3 no longer honors that key** —
+autoconfiguration classes must be listed in
+`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`.
+The project builds on **Java 21** and **Spring Boot 3.5.6**, so today a consumer who
+adds the dependency and expects `@SpringBootApplication` to pick MetaObjects up gets
+**nothing** auto-wired; they must manually `@Import(MetaDataAutoConfiguration.class)`.
+The existing integration test masks this because it wires the config via
+`@ContextConfiguration(classes = MetaDataAutoConfiguration.class)` rather than
+exercising Boot's autoconfiguration *discovery*.
+
+Separately, `core-spring` only wires the **metadata loader** (`MetaDataLoaderRegistry`,
+a primary `MetaDataLoader`, `MetaDataService`). There is **no** autoconfiguration for
+the OMDB persistence layer: a Spring app that wants an `ObjectManagerDB` must hand-build
+it (`new ObjectManagerDB()` + `setDatabaseDriver(...)` + `setDataSource(...)`).
+
+This work modernizes the Spring integration to Boot 3, ships an idiomatic
+one-dependency **starter**, adds **OMDB persistence autoconfiguration**, and hardens
+OMDB for Java 21 virtual threads. It deliberately does **not** adopt jOOQ (see
+Non-Goals).
+
+## Scope
+
+In scope:
+1. **Boot 3 registration fix** — `AutoConfiguration.imports`; delete the dead
+   `spring.factories` entry.
+2. **OMDB persistence autoconfiguration** — build an `ObjectManagerDB` from a Spring
+   `DataSource` + the primary `MetaDataLoader`, transaction-integrated via the existing
+   `SpringObjectConnections`.
+3. **Thin `metaobjects-spring-boot-starter`** module — one-dependency onboarding.
+4. **Virtual-thread hardening (cheap)** — audit OMDB's blocking JDBC paths for
+   carrier-thread pinning (`synchronized` across JDBC calls) and convert to
+   `ReentrantLock` where found. No async API, no forced toggle.
+5. **Tidy** — strip stale "OSGi-compatible" language from the autoconfig javadoc
+   (OSGi was removed in 7.1.0); refresh the `core-spring` README.
+
+Out of scope / Non-Goals:
+- **jOOQ migration.** jOOQ's free Open Source Edition supports only open-source
+  databases; Oracle / SQL Server / DB2 require a *paid* license. OMDB ships drivers for
+  Postgres / MySQL / MSSQL / Oracle / Derby, so a jOOQ migration would paywall or drop
+  commercial-DB support in a public OSS project. jOOQ also generates code *from* a DB
+  schema, the inverse of MetaObjects' metadata-is-the-spine model, and would rip out the
+  driver layer just cleaned up in FR-003 Plan 4. Recorded as a closed open-question.
+- Forcing `spring.threads.virtual.enabled` on consumers.
+- Any change to the OMDB SQL-generation or driver dialect logic beyond the pinning audit.
+
+## Architecture
+
+### Module structure
+
+- **`core-spring`** remains the **autoconfigure** module. It **already** compile-depends
+  on `omdb` (for `SpringObjectConnections`/`ObjectConnectionDB`), so no dependency change
+  is needed; the OMDB beans are gated at runtime by `@ConditionalOnBean(DataSource)` (plus
+  a defensive `@ConditionalOnClass(ObjectManagerDB)`), so they only activate when the
+  consumer actually has a `DataSource`.
+- **New `metaobjects-spring-boot-starter`** — a thin module (no Java code) whose pom
+  depends on `metadata` + `omdb` + `core-spring`. Adding this single dependency gives a
+  consumer the full metadata-loader + OMDB-persistence wiring.
+- `omdb` / `om` are unchanged except for the §"Virtual-thread hardening" pinning audit.
+
+Net change: one new module; `core-spring` gains one optional dependency.
+
+### Autoconfiguration classes
+
+Two independent `@AutoConfiguration` classes (loader and persistence stay decoupled):
+
+**`MetaDataAutoConfiguration`** (existing — behavior unchanged):
+- `MetaDataLoaderRegistry` (`@Primary`), primary `MetaDataLoader`, `MetaDataService`.
+- Driven by the existing `metaobjects.*` `@ConfigurationProperties`
+  (`MetaDataLoaderConfiguration`).
+- Only the registration mechanism and stale OSGi javadoc change.
+
+**`ObjectManagerAutoConfiguration`** (new):
+- Produces an `ObjectManagerDB` bean from the Spring `DataSource` + the primary
+  `MetaDataLoader`.
+- Connections flow through the existing `SpringObjectConnections` so Spring-managed
+  transactions / `@Transactional` participate correctly (FR-003 Spring-tx groundwork).
+- Conditions:
+  - `@ConditionalOnClass(ObjectManagerDB.class)` — only when `omdb` is on the classpath.
+  - `@ConditionalOnBean(DataSource.class)` — only when a DataSource exists.
+  - `@ConditionalOnMissingBean(ObjectManagerDB.class)` — consumer override always wins.
+- New `metaobjects.omdb.*` `@ConfigurationProperties`: `dialect`,
+  `enforce-transaction` (maps to `ObjectManagerDB.setEnforceTransaction`).
+
+### Driver selection
+
+`DatabaseDriver` is chosen by **auto-detection with an explicit override**:
+- If `metaobjects.omdb.dialect` is set (`postgres|mysql|mssql|oracle|derby`), use the
+  matching driver.
+- Otherwise open one connection and map
+  `DatabaseMetaData.getDatabaseProductName()` to the driver
+  (`PostgreSQL`→`PostgresDriver`, `MySQL`→`MySQLDriver`,
+  `Microsoft SQL Server`→`MSSQLDriver`, `Oracle`→`OracleDriver`,
+  `Apache Derby`→`DerbyDriver`). Unknown product name → a clear
+  `MetaDataException` instructing the user to set `metaobjects.omdb.dialect`.
+
+Rationale: zero-config for the common case, explicit escape hatch otherwise. The
+product-name→driver mapping lives in a small, separately-tested helper.
+
+> **Implementation note:** confirm during planning whether `ObjectManagerDB` needs the
+> `MetaDataLoader`/registry wired beyond `DataSource` + `DatabaseDriver` (the integration
+> tests set only driver + datasource). If the OM requires the loader for object-class
+> binding, wire the primary `MetaDataLoader` in the same bean method.
+
+## Virtual-thread hardening
+
+OMDB stays a synchronous JDBC API. On Java 21, blocking calls run fine on virtual
+threads **provided** no `synchronized` monitor is held across a blocking JDBC call
+(that pins the carrier thread). Audit the OMDB blocking paths — the FR-003 Plan 4
+atomic-mapping-cache locking and the `synchronized getDatabaseDriver()` are the prime
+suspects — and convert any `synchronized`-around-JDBC to `java.util.concurrent.locks.ReentrantLock`.
+If the audit finds no JDBC-spanning monitor, document that and make no change (no churn).
+The starter does not set `spring.threads.virtual.enabled`; it only guarantees OMDB is
+pinning-safe when a consumer enables it, and documents the option.
+
+## Boot 3 registration fix + tidy
+
+- Add `core-spring/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`
+  listing `MetaDataAutoConfiguration` and `ObjectManagerAutoConfiguration`.
+- Delete `core-spring/src/main/resources/META-INF/spring.factories`.
+- Remove "OSGi-compatible" / OSGi references from `MetaDataAutoConfiguration` javadoc and
+  any sibling that still mentions it. Refresh the `core-spring` README: document the
+  one-dependency starter and the `metaobjects.omdb.*` properties.
+
+## Testing
+
+- **Autoconfiguration discovery** (`ApplicationContextRunner`, the gap the current
+  `@ContextConfiguration` test masks):
+  - With a DataSource + OMDB present → the `ObjectManagerDB` bean is created.
+  - With no DataSource → `ObjectManagerAutoConfiguration` backs off (no bean, no error).
+  - With a consumer-defined `ObjectManagerDB` → autoconfig backs off (`@ConditionalOnMissingBean`).
+  - The loader autoconfig still produces its beans through real discovery.
+- **Driver selection** — unit-test the product-name→driver mapping and the
+  `metaobjects.omdb.dialect` override; unknown product name → clear error.
+- **Transaction-binding slice** — an embedded-Derby test (Derby is a real OMDB driver,
+  auto-detected from product name; core-spring has no Testcontainers, and full persist/read
+  is already covered by the `integration-tests` module against Postgres/Derby). With a
+  Derby `DataSource` + `DataSourceTransactionManager`, assert the *autoconfigured*
+  `ObjectManagerDB`'s `getConnection()` returns the SAME physical connection Spring bound
+  to the active transaction, and that `close()` on it is a no-op (mirrors the existing
+  `SpringObjectConnectionTest`). This proves the new Spring-tx wiring without duplicating
+  OMDB persistence coverage.
+- Existing `core-spring` tests stay green.
+
+## Sequencing
+
+1. Boot 3 registration fix + OSGi tidy (loader autoconfig only) + discovery test —
+   smallest standalone fix; verifies the bug is closed.
+2. `ObjectManagerAutoConfiguration` + driver-selection helper + `metaobjects.omdb.*`
+   properties + slice tests.
+3. `metaobjects-spring-boot-starter` thin module + README.
+4. Virtual-thread pinning audit (+ fix if found).
+5. Record jOOQ as a closed non-goal in CLAUDE.md open questions.
+
+## Open questions
+
+- Whether `ObjectManagerDB` requires the `MetaDataLoader` wired beyond driver +
+  datasource for object-class binding (resolve in planning by reading the OM API).
+- Boot 2.x support is dropped (Boot 2 is EOL); the starter targets Boot 3.5+ only.

docs/superpowers/specs/2026-05-29-omdb-spring-boot-starter-design.md

@@ -2,6 +2,29 @@
 
 This module provides comprehensive Spring Framework integration for MetaObjects, including auto-configuration, dependency injection, and Spring Boot support.
 
+## Spring Boot starter
+
+Add the single starter dependency:
+
+    <dependency>
+        <groupId>com.metaobjects</groupId>
+        <artifactId>metaobjects-spring-boot-starter</artifactId>
+        <version>7.1.1-SNAPSHOT</version>
+    </dependency>
+
+On Spring Boot 3, this auto-configures the metadata-loader registry and — when a
+`DataSource` is present — a transaction-aware `ObjectManagerDB`.
+
+Properties:
+
+| Property | Default | Description |
+|---|---|---|
+| `metaobjects.metadata-sources` | (none) | Loader source URIs/resources. |
+| `metaobjects.omdb.dialect` | (auto) | `postgres`/`mysql`/`mssql`/`oracle`/`derby`. Auto-detected from the DataSource when blank. |
+| `metaobjects.omdb.enforce-transaction` | `false` | Require an active transaction for writes. |
+
+Define your own `ObjectManagerDB` bean to opt out of the autoconfigured one.
+
 ## 🚀 **Quick Start**
 
 ### **Add Dependency**
@@ -416,10 +439,23 @@ Optional<MetaObject> user = metaDataService.findMetaObjectByNameOptional("User")
 - Thread-safe for concurrent access
 
 ### **Memory Management**
-- Uses WeakHashMap patterns for OSGi compatibility
+- Uses WeakHashMap patterns to avoid leaking classloaders
 - Automatic cleanup when Spring context shuts down
 - Minimal memory overhead for Spring integration
 
+## Virtual threads (Java 21)
+
+OMDB is a synchronous JDBC API and is safe to run on JVM virtual threads. An audit of
+the OMDB blocking paths found no `synchronized` monitor held across a JDBC call (the only
+synchronized methods guard in-memory state — the driver lazy-init, the event-listener
+list, and per-object attribute maps), so OMDB does not pin carrier threads.
+
+To run a Spring Boot 3.2+ application's request handling on virtual threads, set:
+
+    spring.threads.virtual.enabled=true
+
+The starter does not enable this for you — it is the application's choice.
+
 ---
 
 **This Spring integration provides seamless MetaObjects functionality within Spring applications while maintaining all the framework's powerful features.**

server/java/core-spring/README.md

@@ -69,6 +69,12 @@
             <version>6.2.11</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-test</artifactId>
+            <version>3.5.6</version>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>com.metaobjects</groupId>
             <artifactId>metaobjects-metadata</artifactId>
@@ -83,6 +89,32 @@
             <version>2.2.224</version>
             <scope>test</scope>
         </dependency>
+        <!-- Embedded Derby for OMDB autoconfiguration tests -->
+        <dependency>
+            <groupId>org.apache.derby</groupId>
+            <artifactId>derby</artifactId>
+            <version>${derby.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.derby</groupId>
+            <artifactId>derbyshared</artifactId>
+            <version>${derby.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.derby</groupId>
+            <artifactId>derbytools</artifactId>
+            <version>${derby.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <!-- AssertJ for ApplicationContextRunner assertions (not transitive here) -->
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <version>3.26.3</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>

server/java/core-spring/pom.xml

@@ -0,0 +1,71 @@
+package com.metaobjects.spring;
+
+import com.metaobjects.manager.db.DatabaseDriver;
+import com.metaobjects.manager.db.driver.DerbyDriver;
+import com.metaobjects.manager.db.driver.MSSQLDriver;
+import com.metaobjects.manager.db.driver.MySQLDriver;
+import com.metaobjects.manager.db.driver.OracleDriver;
+import com.metaobjects.manager.db.driver.PostgresDriver;
+
+import javax.sql.DataSource;
+import java.sql.Connection;
+import java.sql.SQLException;
+
+/**
+ * Resolves the OMDB {@link DatabaseDriver} for a Spring {@link DataSource}: an explicit
+ * {@code metaobjects.omdb.dialect} wins; otherwise the JDBC
+ * {@code DatabaseMetaData.getDatabaseProductName()} is mapped to a driver.
+ */
+final class DatabaseDriverResolver {
+
+    private DatabaseDriverResolver() {}
+
+    static DatabaseDriver resolve(String dialect, DataSource dataSource) {
+        if (dialect != null && !dialect.isBlank()) {
+            return forDialect(dialect.trim().toLowerCase());
+        }
+        return forProduct(detectProduct(dataSource));
+    }
+
+    static DatabaseDriver forDialect(String dialect) {
+        switch (dialect) {
+            case "postgres":
+            case "postgresql":
+                return new PostgresDriver();
+            case "mysql":
+                return new MySQLDriver();
+            case "mssql":
+            case "sqlserver":
+                return new MSSQLDriver();
+            case "oracle":
+                return new OracleDriver();
+            case "derby":
+                return new DerbyDriver();
+            default:
+                throw new IllegalArgumentException(
+                    "Unknown metaobjects.omdb.dialect '" + dialect +
+                    "'. Use one of: postgres, mysql, mssql, oracle, derby.");
+        }
+    }
+
+    static DatabaseDriver forProduct(String product) {
+        String p = product == null ? "" : product.toLowerCase();
+        if (p.contains("postgresql")) return new PostgresDriver();
+        if (p.contains("mysql")) return new MySQLDriver();
+        if (p.contains("sql server")) return new MSSQLDriver();
+        if (p.contains("oracle")) return new OracleDriver();
+        if (p.contains("derby")) return new DerbyDriver();
+        throw new IllegalStateException(
+            "Could not auto-detect an OMDB driver for database product '" + product +
+            "'. Set metaobjects.omdb.dialect explicitly (postgres|mysql|mssql|oracle|derby).");
+    }
+
+    private static String detectProduct(DataSource dataSource) {
+        try (Connection c = dataSource.getConnection()) {
+            return c.getMetaData().getDatabaseProductName();
+        } catch (SQLException e) {
+            throw new IllegalStateException(
+                "Failed to read DatabaseMetaData for OMDB driver auto-detection: " + e.getMessage(), e);
+        }
+    }
+}

server/java/core-spring/src/main/java/com/metaobjects/spring/DatabaseDriverResolver.java

@@ -4,21 +4,20 @@
 import com.metaobjects.registry.MetaDataLoaderRegistry;
 import com.metaobjects.registry.ServiceRegistryFactory;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.AutoConfiguration;
 import org.springframework.context.annotation.Bean;
-import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Import;
 import org.springframework.context.annotation.Primary;
 
 import java.util.List;
 
 /**
- * Spring Auto-Configuration for MetaObjects OSGi-compatible registry.
- * 
+ * Spring Boot auto-configuration for the MetaObjects metadata-loader registry.
+ *
  * <p>This configuration automatically:</p>
  * <ul>
- *   <li>Creates OSGi-compatible MetaDataLoaderRegistry using ServiceRegistryFactory</li>
  *   <li>Auto-discovers MetaDataLoader beans from Spring context</li>
  *   <li>Provides backward-compatible @Autowired injection</li>
- *   <li>Works in both OSGi and non-OSGi environments</li>
  * </ul>
  * 
  * <p><strong>Usage in Spring Controllers:</strong></p>
@@ -42,18 +41,19 @@
  * 
  * @since 6.0.0
  */
-@Configuration
+@AutoConfiguration
+@Import(MetaDataLoaderConfiguration.class)
 public class MetaDataAutoConfiguration {
 
     /**
-     * Creates OSGi-compatible MetaDataLoaderRegistry with auto-discovery
+     * Creates the MetaDataLoaderRegistry with auto-discovery
      * of MetaDataLoader beans from Spring context.
      */
     @Bean
     @Primary
     public MetaDataLoaderRegistry metaDataLoaderRegistry() {
 
-        // Create OSGi-compatible registry (auto-detects environment)
+        // Create the loader registry
         MetaDataLoaderRegistry registry = new MetaDataLoaderRegistry(
             ServiceRegistryFactory.getDefault()
         );