GORM: Shared Mapping Registry O(M+N) Scaling

.agents/skills/test-fixer/SKILL.md

@@ -89,6 +89,68 @@ All tests passed! 🎉
 
 ---
 
+## Isolated Testing (local.properties)
+
+The project supports an **Isolation Mode** for focused development. By configuring `local.properties`, you can limit test execution to specific modules and enable aggressive heap settings for those tests.
+
+### Configuration
+
+In `local.properties`:
+```properties
+# List the modules you want to focus on
+grails.test.modules=:grails-datamapping-core-test,:grails-data-simple
+```
+
+### Usage
+
+```bash
+# Runs ONLY the modules defined in grails.test.modules
+# Automatically aggregates failures and style violations
+# MANDATORY: Must include the local-init.gradle initialization script
+./gradlew -I local-init.gradle testSelected
+```
+
+When `testSelected` is run:
+- Only tests in the specified modules are enabled.
+- `maxParallelForks` is set to `1` (serial) for stability.
+- Heap size is increased to `3g`.
+- `ignoreFailures` is set to `true` to ensure aggregation tasks run.
+- Non-selected modules have their test and quality tasks disabled.
+
+---
+
+## Iterative Test Fixing Workflow
+
+When tasked with fixing a large number of test failures (especially in isolation mode), adhere to this highly efficient, iterative loop:
+
+**Step 1: The Initial Assessment**
+Run the full isolated test suite once to generate the master list of all current failures in `TEST_FAILURES.md`.
+```bash
+./gradlew -I local-tasks.gradle clean testSelected aggregateTestFailures
+```
+
+**Step 2: The Inner Loop (One by One)**
+Take the generated list of failures and iterate through it **one test at a time**.
+For *each* individual test (or closely related group of tests in the same class) on the list:
+1. Investigate the specific failure.
+2. Apply a targeted code fix.
+3. Verify the fix by running **only that single test** to maintain a fast feedback loop. Do NOT rerun the entire suite.
+```bash
+./gradlew :<module_name>:test --tests "<fully_qualified_class_name>.<test_method_name>"
+```
+4. Once that single test passes locally, move on to the *next* failing test on the list and repeat the process.
+
+**Step 3: The Outer Loop (Full Verification)**
+Only after you have gone through the entire list and fixed every test *individually* in the inner loop, run the full aggregated suite again to verify no regressions were introduced and to update the master list.
+```bash
+./gradlew -I local-tasks.gradle clean testSelected aggregateTestFailures
+```
+
+**Step 4: Iterate**
+If the full suite reveals any new or remaining failures in `TEST_FAILURES.md`, repeat the entire process starting from Step 2, continuing until the final aggregated run produces zero failures.
+
+---
+
 ## Interpreting Failures
 
 Each row in the table gives you:
@@ -186,3 +248,34 @@ Gradle writes JUnit XML test results to:
 ```
 
 `aggregateTestFailures` scans all these directories automatically.
+
+# Iterative Test Fixing Workflow
+
+When tasked with fixing a large number of test failures (especially in isolation mode), adhere to this highly efficient, iterative loop:
+
+**Step 1: The Initial Assessment**
+Run the full isolated test suite once to generate the master list of all current failures in `TEST_FAILURES.md`.
+```bash
+./gradlew -I local-tasks.gradle clean testSelected aggregateTestFailures
+```
+
+**Step 2: The Inner Loop (One by One)**
+Take the generated list of failures and iterate through it **one test at a time**.
+For *each* individual test (or closely related group of tests in the same class) on the list:
+1. Investigate the specific failure.
+2. Apply a targeted code fix.
+3. Verify the fix by running **only that single test** to maintain a fast feedback loop. Do NOT rerun the entire suite.
+```bash
+./gradlew :<module_name>:test --tests "<fully_qualified_class_name>.<test_method_name>"
+```
+4. Once that single test passes locally, move on to the *next* failing test on the list and repeat the process.
+
+**Step 3: The Outer Loop (Full Verification)**
+Only after you have gone through the entire list and fixed every test *individually* in the inner loop, run the full aggregated suite again to verify no regressions were introduced and to update the master list.
+```bash
+./gradlew -I local-tasks.gradle clean testSelected aggregateTestFailures
+```
+
+**Step 4: Iterate**
+If the full suite reveals any new or remaining failures in `TEST_FAILURES.md`, repeat the entire process starting from Step 2, continuing until the final aggregated run produces zero failures.
+

AGENTS.md

@@ -54,6 +54,7 @@ export GRADLE_OPTS="-Xms2G -Xmx5G"
 11. **Every code touch must update all tests for the changed class** - When a class is modified, find and update every test that covers it — unit, integration, and TCK. Do not leave any existing test out of sync with the new code.
 12. **Clean violations before commit** - Before every automated commit, run `./gradlew clean aggregateStyleViolations test aggregateTestFailures --continue` from the root and ensure that `CHECKSTYLE_VIOLATIONS.md`, `CODENARC_VIOLATIONS.md`, `PMD_VIOLATIONS.md`, and `TEST_FAILURES.md` report no issues and are removed.
 13. **Mandatory test coverage** - Any class touched in a commit MUST be covered with tests that verify all behavior. You must run ALL tests in the affected module(s) and ensure they pass before committing.
+14. **NEVER delete `local*` files and DO NOT remove values** - Files prefixed with `local` (e.g., `local.properties`, `local-tasks.gradle`) must NEVER be deleted. When modifying these files, NEVER remove existing values; instead, comment them out and append new values to maintain history and prevent loss of local configuration.
 
 ## Available Skills
 
@@ -267,6 +268,11 @@ See `CONTRIBUTING.md` for full details.
 | Deprecation details | `./gradlew <task> --warning-mode all` |
 
 
+## Local Configuration
+
+- **Local File Preservation**: NEVER delete files prefixed with `local` (e.g., `local.properties`, `local-tasks.gradle`). These files are used for local developer overrides and environment-specific tasks and must be maintained.
+- **Commenting over Deletion**: When instructed to modify any `local*` files or similar configuration files, DO NOT delete the existing lines. Instead, comment out the old entries and append the new ones. This ensures a traceable history of local configuration changes.
+
 ### Reporting Vulnerabilities
 
 Please see the page of the [ASF Security Team](https://www.apache.org/security/) for further information and contact information.
@@ -278,4 +284,6 @@ Please see the page of the [ASF Security Team](https://www.apache.org/security/)
 - **Spock 2.3 Docs**: https://spockframework.org/spock/docs/2.3/all_in_one.html
 - **GORM Docs**: https://grails.apache.org/docs/latest/grails-data/
 - **Issues**: https://github.com/apache/grails-core/issues
-- **Slack**: https://grails.slack.com
+
+## Agent Commit Policy
+When committing changes assisted by an AI agent, you MUST include a note in the commit message stating that the agent acted as a collaborator and that the user (borinquenkid) is the primary author and remains responsible for the changes. Do not present the agent as the sole author of the code.

DEVELOPMENT.md

@@ -80,5 +80,16 @@ Example with multiple tags:
   DO_NOT_CACHE_TESTS=1 ./gradlew :grails-gsp:test
   ```
 
+## GORM API resolution internals (core)
+
+The `grails-datamapping-core` module now supports instance-oriented API creation and lookup:
+
+- `GormApiFactory` defines the contract for creating `GormStaticApi`, `GormInstanceApi`, and `GormValidationApi`.
+- `DefaultGormApiFactory` is the core fallback implementation.
+- `GormApiResolver` is owned by `GormRegistry` for instance-based API/datastore resolution.
+- `GormRegistry` can register datastore-type factory overrides with `registerApiFactory(...)`.
+
+`GormEnhancer.find*` static entry points remain as compatibility delegates and are deprecated in favor of `GormRegistry.getInstance()` + resolver/factory access.
+
 ## Start a mongo docker container (containers will start by default)
 `docker run -d  --name mongo-on-docker  -p 27017:27017 mongo`

ISSUES.md

@@ -0,0 +1,101 @@
+<!--
+SPDX-License-Identifier: Apache-2.0
+
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# GORM Scaling Program — Change Log and Optimization Backlog
+
+This document now tracks what has already changed for the O(M+N) scaling work and what can still be optimized. It is no longer a failure tracker.
+
+---
+
+## 1) Core changes implemented
+
+### Shared-registry architecture (O(M+N))
+- Introduced `GormRegistry` and moved registry responsibilities out of per-tenant duplication paths.
+- Refactored `GormEnhancer`, `GormStaticApi`, and `GormInstanceApi` to resolve APIs through shared registry data.
+- Updated tenant-aware resolution flow (`Tenants`, enhancer lookup paths, qualifier handling) to match shared registry behavior.
+
+### Datastore integrations aligned to shared model
+- Hibernate 7: updated static/instance/enhancer APIs and related datastore/session/query wiring to use the new registry approach.
+- Hibernate 5: parallel alignment with H7 so API behavior stays consistent across both engines.
+- MongoDB: updated static API and codec/persister integration points to align with shared registry and tenant resolution changes.
+- SimpleMap datastore: large query/persister/session updates to keep core behavior consistent with new registry flow.
+
+### Query and session behavior hardening
+- Refined key query/session paths in Hibernate and SimpleMap implementations where registry and tenant context are used.
+- Added or adjusted session-resolver/runtime utilities where needed to keep API behavior stable under multi-tenancy.
+
+### Transform and compile-time behavior updates
+- Updated service and transactional transform logic to match registry/data access changes.
+- Reorganized transform test assets (including moved/expanded transform specs/classes).
+
+### Test coverage expanded for scale + regressions
+- Added `GormRegistryScalabilitySpec` coverage across core modules (core, H5, H7, Mongo).
+- Added and updated regression coverage around enhancer, static API, transaction manager, and transform behavior.
+
+### Local selected-module workflow improvements
+- Selected-module runs now enforce CodeNarc/Checkstyle aggregation without forcing PMD/SpotBugs in that path.
+- `testSelected` flow remains focused on selected modules with aggregated test/style outputs.
+
+---
+
+## 2) Potential optimization opportunities
+
+## A. Registry/API hot-path efficiency
+**Goal:** reduce repeated lookup overhead under high tenant/entity counts.
+
+1. Cache normalized entity keys and qualifier maps in one place to reduce repeated normalization work.
+2. Audit repeated `findDatastore`/qualifier fallback chains and collapse duplicate branches.
+3. Benchmark `computeIfAbsent` and lock contention patterns in registry-heavy paths.
+
+## B. Tenant context and session routing
+**Goal:** lower context-switch overhead and reduce accidental cross-context work.
+
+1. Profile tenant context wrapping frequency in static API calls.
+2. Identify places where tenant/session context can be propagated once instead of re-resolved.
+3. Add targeted perf specs for DISCRIMINATOR and SCHEMA mode query loops.
+
+## C. Query builder/runtime allocation pressure
+**Goal:** reduce temporary object churn in frequently executed query paths.
+
+1. Review HQL/criteria builder allocation patterns in H5/H7 and SimpleMap query implementations.
+2. Reuse immutable query metadata where safe.
+3. Add microbenchmarks for common `list/find/count` paths with multi-tenant datasets.
+
+## D. Transform pipeline cost
+**Goal:** reduce compile-time overhead from service/transaction transforms.
+
+1. Measure transform execution hotspots after recent refactors.
+2. Consolidate duplicated transform helper logic.
+3. Add performance-oriented transform tests focused on large service sets.
+
+## E. Test/runtime throughput
+**Goal:** keep regression coverage while reducing local/CI cycle time.
+
+1. Keep scalability specs, but tune dataset sizes for stable signal-to-cost ratio.
+2. Split long-running integration groups where practical.
+3. Continue selected-module execution strategy for local iteration, full-suite in CI.
+
+---
+
+## 3) Suggested tracking format for future updates
+
+When adding new work items to this file:
+- Record the **change** under section 1 with module + behavior impact.
+- Record follow-up work under section 2 with a short **goal** and concrete next actions.
+- Avoid adding pass/fail snapshots here; keep this file architectural and optimization-focused.