Migrate to the Compiler API

.agents/_TOC.md

@@ -0,0 +1,16 @@
+# Table of Contents
+
+1. [Quick Reference Card](quick-reference-card.md)
+2. [Project overview](project-overview.md)
+3. [Coding guidelines](coding-guidelines.md)
+4. [Documentation & comments](documentation-guidelines.md)
+5. [Documentation tasks](documentation-tasks.md)
+6. [Running builds](running-builds.md)
+7. [Version policy](version-policy.md)
+8. [Project structure expectations](project-structure-expectations.md)
+9. [Testing](testing.md)
+10. [Safety rules](safety-rules.md)
+11. [Advanced safety rules](advanced-safety-rules.md)
+12. [Refactoring guidelines](refactoring-guidelines.md)
+13. [Common tasks](common-tasks.md)
+14. [Java to Kotlin conversion](java-kotlin-conversion.md)

.agents/advanced-safety-rules.md

@@ -0,0 +1,6 @@
+# 🚨 Advanced safety rules
+
+- Do **not** auto-update external dependencies without explicit request.
+- Do **not** inject analytics or telemetry code.
+- Flag any usage of unsafe constructs (e.g., reflection, I/O on the main thread).
+- Avoid generating blocking calls inside coroutines.

.agents/coding-guidelines.md

@@ -0,0 +1,39 @@
+# 🧾 Coding guidelines
+
+## Core principles
+
+- Adhere to [Spine Event Engine Documentation][spine-docs] for coding style.
+- Generate code that compiles cleanly and passes static analysis.
+- Respect existing architecture, naming conventions, and project structure.
+- Write clear, incremental commits with descriptive messages.
+- Include automated tests for any code change that alters functionality.
+
+## Kotlin best practices
+
+### ✅ Prefer
+- **Kotlin idioms** over Java-style approaches:
+  - Extension functions
+  - `when` expressions 
+  - Smart casts
+  - Data classes and sealed classes
+  - Immutable data structures
+- **Simple nouns** over composite nouns (`user` > `userAccount`)  
+- **Generic parameters** over explicit variable types (`val list = mutableList<Dependency>()`)  
+- **Java interop annotations** only when needed (`@file:JvmName`, `@JvmStatic`)
+- **Kotlin DSL** for Gradle files
+
+### ❌ Avoid
+- Mutable data structures
+- Java-style verbosity (builders with setters)
+- Redundant null checks (`?.let` misuse)
+- Using `!!` unless clearly justified
+- Type names in variable names (`userObject`, `itemList`)
+- String duplication (use constants in companion objects)
+- Mixing Groovy and Kotlin DSLs in build logic
+- Reflection unless specifically requested
+
+## Text formatting
+ - ✅ Remove double empty lines in the code.
+ - ✅ Remove trailing space characters in the code.
+
+[spine-docs]: https://github.com/SpineEventEngine/documentation/wiki

.agents/common-tasks.md

@@ -0,0 +1,6 @@
+# 📋 Common tasks
+
+- **Adding a new dependency**: Update relevant files in `buildSrc` directory.
+- **Creating a new module**: Follow existing module structure patterns.
+- **Documentation**: Use KDoc style for public and internal APIs.
+- **Testing**: Create comprehensive tests using Kotest assertions.

.agents/documentation-guidelines.md

@@ -0,0 +1,14 @@
+# Documentation & comments
+
+## Commenting guidelines
+- Avoid inline comments in production code unless necessary.
+- Inline comments are helpful in tests.
+- When using TODO comments, follow the format on the [dedicated page][todo-comments].
+- File and directory names should be formatted as code.
+
+## Avoid widows, runts, orphans, or rivers
+
+Agents should **AVOID** text flow patters illustrated
+on [this diagram](widow-runt-orphan-river.jpg).
+
+[todo-comments]: https://github.com/SpineEventEngine/documentation/wiki/TODO-comments

.agents/documentation-tasks.md

@@ -0,0 +1,20 @@
+# 📄 Documentation tasks
+
+1. Ensure all public and internal APIs have KDoc examples.
+2. Add in-line code blocks for clarity in tests.
+3. Convert inline API comments in Java to KDoc in Kotlin:
+   ```java
+   // Literal string to be inlined whenever a placeholder references a non-existent argument.
+   private final String missingArgumentMessage = "[MISSING ARGUMENT]";
+   ```
+   transforms to:
+   ```kotlin
+   /**
+    * Literal string to be inlined whenever a placeholder references a non-existent argument.
+    */
+    private val missingArgumentMessage = "[MISSING ARGUMENT]"
+   ```
+
+4. Javadoc -> KDoc conversion tasks:
+   - Remove `<p>` tags in the line with text: `"<p>This"` -> `"This"`.
+   - Replace `<p>` with empty line if the tag is the only text in the line.

.agents/java-kotlin-conversion.md

@@ -0,0 +1,43 @@
+# 🪄 Converting Java code to Kotlin
+
+* Java code API comments are Javadoc format.
+* Kotlin code API comments are in KDoc format. 
+
+## Javadoc to KDoc conversion
+
+* The wording of original Javadoc comments must be preserved.
+
+## Treating nullability
+
+* Use nullable Kotlin type only if the type in Java is annotated as `@Nullable`.
+
+## Efficient Conversion Workflow
+
+* First, analyze the entire Java file structure before beginning conversion to understand dependencies and class relationships.
+* Convert Java code to Kotlin systematically: imports first, followed by class definitions, methods, and finally expressions.
+* Preserve all existing functionality and behavior during conversion.
+* Maintain original code structure and organization to ensure readability.
+
+## Common Java to Kotlin Patterns
+
+* Convert Java getters/setters to Kotlin properties with appropriate visibility modifiers.
+* Transform Java static methods to companion object functions or top-level functions as appropriate.
+* Replace Java anonymous classes with Kotlin lambda expressions when possible.
+* Convert Java interfaces with default methods to Kotlin interfaces with implementations.
+* Transform Java builders to Kotlin DSL patterns when appropriate.
+
+## Error Prevention
+
+* Pay special attention to Java's checked exceptions versus Kotlin's unchecked exceptions.
+* Be cautious with Java wildcards (`? extends`, `? super`) conversion to Kotlin's `out` and `in` type parameters.
+* Ensure proper handling of Java static initialization blocks in Kotlin companion objects.
+* Verify that Java overloaded methods convert correctly with appropriate default parameter values in Kotlin.
+* Remember that Kotlin has smart casts which can eliminate explicit type casting needed in Java.
+
+## Documentation Conversion
+
+* Convert `@param` to `@param` with the same description.
+* Convert `@return` to `@return` with the same description.
+* Convert `@throws` to `@throws` with the same description.
+* Convert `{@link}` to `[name][fully.qualified.Name]` format.
+* Convert `{@code}` to inline code with backticks (`).

.agents/project-overview.md

@@ -0,0 +1,7 @@
+# 🛠️ Project overview
+
+- **Languages**: Kotlin (primary), Java (secondary).
+- **Build tool**: Gradle with Kotlin DSL.
+- **Static analysis**: detekt, ErrorProne, Checkstyle, PMD. 
+- **Testing**: JUnit 5, Kotest Assertions, Codecov.
+- **Tools used**: Gradle plugins, IntelliJ IDEA Platform, KSP, KotlinPoet, Dokka.

.agents/project-structure-expectations.md

@@ -0,0 +1,21 @@
+# 📁 Project structure expectations
+
+```yaml
+.github
+buildSrc/
+<module-1>
+  src/
+  ├── main/
+  │ ├── kotlin/ # Kotlin source files
+  │ └── java/ # Legacy Java code
+  ├── test/
+  │ └── kotlin/ # Unit and integration tests
+  build.gradle.kts # Kotlin-based build configuration
+<module-2>
+<module-3>
+build.gradle.kts # Kotlin-based build configuration
+settings.gradle.kts # Project structure and settings
+README.md # Project overview
+AGENTS.md # Entry point for LLM agent instructions
+version.gradle.kts # Declares the project version. 
+```

.agents/quick-reference-card.md

@@ -0,0 +1,10 @@
+# 📝 Quick Reference Card
+
+```
+🔑 Key Information:
+- Kotlin/Java project with CQRS architecture
+- Use ChatGPT for documentation, Codex for code generation, GPT-4o for complex analysis
+- Follow coding guidelines in Spine Event Engine docs
+- Always include tests with code changes
+- Version bump required for all PRs
+```

.agents/refactoring-guidelines.md

@@ -0,0 +1,3 @@
+# ⚙️ Refactoring guidelines
+
+- Do NOT replace Kotest assertions with standard Kotlin's built-in test assertions.

.agents/running-builds.md

@@ -0,0 +1,18 @@
+# Running builds
+
+1. When modifying code, run:
+   ```bash
+   ./gradlew build
+   ```
+
+2. If Protobuf (`.proto`) files are modified run:
+   ```bash
+   ./gradlew clean build
+   ```
+
+3. Documentation-only changes in Kotlin or Java sources run:
+   ```bash
+   ./gradlew dokka
+   ```
+
+4. Documentation-only changes do not require running tests!

.agents/safety-rules.md

@@ -0,0 +1,7 @@
+# Safety rules
+
+- ✅ All code must compile and pass static analysis.
+- ✅ Do not auto-update external dependencies.
+- ❌ Never use reflection or unsafe code without an explicit approval.
+- ❌ No analytics or telemetry code.
+- ❌ No blocking calls inside coroutines.

.agents/testing.md

@@ -0,0 +1,8 @@
+# 🧪 Testing
+
+- Do not use mocks, use stubs.
+- Prefer [Kotest assertions][kotest-assertions] over assertions from JUnit or Google Truth.
+- Generate unit tests for APIs (handles edge cases/scenarios).
+- Supply scaffolds for typical Kotlin patterns (`when`, sealed classes).
+
+[kotest-assertions]: https://kotest.io/docs/assertions/assertions.html

.agents/version-policy.md

@@ -0,0 +1,30 @@
+# Version policy
+
+## We use semver
+The version of the project is kept in the `version.gradle.kts` file in the root of the project.
+
+The version numbers in these files follow the conventions of
+[Semantic Versioning 2.0.0](https://semver.org/).
+
+## Quick checklist for versioning
+1. Increment the patch version in `version.gradle.kts`.
+   Retain zero-padding if applicable:
+    - Example: `"2.0.0-SNAPSHOT.009"` → `"2.0.0-SNAPSHOT.010"`
+2. Commit the version bump separately with this comment:
+   ```text
+   Bump version → `$newVersion`
+   ``` 
+3. Rebuild using `./gradlew clean build`.
+4. Update `pom.xml`, `dependencies.md` and commit changes with: `Update dependency reports`
+
+Remember: PRs without version bumps will fail CI (conflict resolution detailed above).
+
+## Resolving conflicts in `version.gradle.kts`
+A branch conflict over the version number should be resolved as described below.
+ * If a merged branch has a number which is less than that of the current branch, the version of
+   the current branch stays.
+ * If the merged branch has the number which is greater or equal to that of the current branch,
+   the number should be increased by one.
+
+## When to bump the version?
+ - When a new branch is created.

.gitignore

@@ -31,6 +31,9 @@
 #
 # Therefore, instructions below are superset of instructions required for all the projects.
 
+# Temporary output of AI agents.
+.output
+
 # `jenv` local configuration.
 .java-version
 
@@ -55,19 +58,28 @@
 !.idea/codeStyles/
 !.idea/copyright/
 
+# Ignore IDEA config files under `tests`
+/tests/.idea/**
+
 # Gradle interim configs
 **/.gradle/**
 
 # Temp directory for Gradle TestKit runners
 **/.gradle-test-kit/**
 
+# Integration test log files
+/tests/_out/**
+
 # Generated source code
 **/generated/**
 **/*.pb.dart
 **/*.pbenum.dart
 **/*.pbserver.dart
 **/*.pbjson.dart
 
+# Generated source code with custom path under `tests`
+/tests/**/proto-gen/**
+
 # Gradle build files
 **/build/**
 !**/src/**/build/**

.junie/guidelines.md

@@ -0,0 +1,21 @@
+# Guidelines for Junie and AI Agent from JetBrains
+
+Read the `../.agents/_TOC.md` file at the root of the project to understand:
+ - the agent responsibilities,
+ - project overview, 
+ - coding guidelines, 
+ - other relevant topics.
+
+Also follow the Junie-specific rules described below.
+
+## Junie Assistance Tips
+
+When working with Junie AI on the Spine Tool-Base project:
+
+1. **Project Navigation**: Use `search_project` to find relevant files and code segments.
+2. **Code Understanding**: Request file structure with `get_file_structure` before editing.
+3. **Code Editing**: Make minimal changes with `search_replace` to maintain project consistency.
+4. **Testing**: Verify changes with `run_test` on relevant test files.
+5. **Documentation**: Follow KDoc style for documentation.
+6. **Kotlin Idioms**: Prefer Kotlin-style solutions over Java-style approaches.
+7. **Version Updates**: Remember to update `version.gradle.kts` for PRs.

AGENTS.md

@@ -0,0 +1,5 @@
+# 👋 Welcome, Agents!
+
+For detailed agent guidelines and documentation, please see:
+
+**[Agent Documentation](./.agents/_TOC.md)**