Add GitHub Copilot instructions file

.github/copilot-instructions.md

@@ -0,0 +1,153 @@
+# GitHub Copilot Instructions for Spine CoreJvm
+
+## Project Overview
+
+- **Type**: Library/Framework
+- **Languages**: Kotlin (primary), Java (secondary)
+- **Tech Stack**: Gradle with Kotlin DSL, JDK 17+
+- **Architecture**: CQRS (Command Query Responsibility Segregation) and Event Sourcing
+- **Main Purpose**: Spine Event Engine core library for building Event Sourcing and CQRS applications
+
+**Key Dependencies**:
+- Protobuf for message definitions
+- JUnit 5 for testing
+- Kotest for assertions
+- Static analysis: detekt, ErrorProne, Checkstyle, PMD
+- Documentation: Dokka
+- Tools: KSP, KotlinPoet
+
+## Detailed Documentation
+
+For comprehensive guidance, please refer to the [`.agents` directory](../.agents/_TOC.md) which contains:
+- [Quick Reference Card](../.agents/quick-reference-card.md)
+- [Project Overview](../.agents/project-overview.md)
+- [Coding Guidelines](../.agents/coding-guidelines.md)
+- [Testing Guidelines](../.agents/testing.md)
+- [Running Builds](../.agents/running-builds.md)
+- [Version Policy](../.agents/version-policy.md)
+- [Safety Rules](../.agents/safety-rules.md)
+
+## Coding Standards & Conventions
+
+### Language Preferences
+- **Primary**: Kotlin with idiomatic patterns
+- **Secondary**: Java (for legacy compatibility)
+
+### Kotlin Best Practices
+**✅ Prefer**:
+- Extension functions over utility classes
+- `when` expressions over multiple `if-else`
+- Smart casts and type inference
+- Data classes and sealed classes
+- Immutable data structures
+- Simple nouns over composite names (`user` not `userAccount`)
+- Generic parameters over explicit types
+
+**❌ Avoid**:
+- Mutable data structures
+- Java-style builders with setters
+- Redundant null checks and `?.let` misuse
+- Using `!!` (null assertion) without clear justification
+- Type names in variable names (`userObject`, `itemList`)
+- Reflection unless specifically requested
+- Mixing Groovy and Kotlin DSLs in build files
+
+### Code Quality
+- Follow [Spine Event Engine Documentation](https://github.com/SpineEventEngine/documentation/wiki) for style
+- Generate code that compiles cleanly and passes static analysis
+- Remove double empty lines and trailing spaces
+- Write clear, descriptive commit messages
+- Respect existing architecture and naming conventions
+
+## Testing & Quality
+
+### Testing Framework
+- **Test Framework**: JUnit 5
+- **Assertions**: Prefer [Kotest assertions](https://kotest.io/docs/assertions/assertions.html) over JUnit or Google Truth
+- **Test Strategy**: Use stubs, not mocks
+
+### Testing Requirements
+- Include automated tests for any code change that alters functionality
+- Generate unit tests that handle edge cases and various scenarios
+- Documentation-only changes do not require tests
+
+## Build & Workflow
+
+### Building the Project
+
+1. **Code changes**:
+   ```bash
+   ./gradlew build
+   ```
+
+2. **Protobuf (`.proto`) changes**:
+   ```bash
+   ./gradlew clean build
+   ```
+
+3. **Documentation-only changes** (Kotlin/Java sources):
+   ```bash
+   ./gradlew dokka
+   ```
+
+### Version Management
+
+This project follows [Semantic Versioning 2.0.0](https://semver.org/).
+
+**Version Bump Checklist**:
+1. Increment patch version in `version.gradle.kts` (retain zero-padding)
+2. Commit version bump separately: `Bump version → $newVersion`
+3. Rebuild: `./gradlew clean build`
+4. Update `pom.xml` and `dependencies.md`, commit as: `Update dependency reports`
+
+**Important**: Version bumps are required when creating a new branch. PRs without version bumps will fail CI.
+
+### Commit Guidelines
+- Write incremental, focused commits
+- Use clear, descriptive commit messages
+- Commit version bumps separately from code changes
+
+## Security & Safety Rules
+
+**✅ Must Do**:
+- Ensure all code compiles and passes static analysis
+- Test thoroughly before committing
+
+**❌ Never Do**:
+- Auto-update external dependencies without review
+- Use reflection or unsafe code without explicit approval
+- Add analytics or telemetry code
+- Make blocking calls inside coroutines
+
+## Project Structure
+
+- `buildSrc/` - Build configuration and dependency management
+- `client/` - Client API
+- `server/` - Server API
+- `core/` - Core types and functionality
+- `*-testlib/` - Testing utilities
+- `config/` - Shared configuration (Git submodule)
+
+## 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
+- **Refactoring**: Consult [Refactoring Guidelines](../.agents/refactoring-guidelines.md)
+
+## Important Annotations
+
+- `@Internal`: Not part of public API - do not use from outside the framework
+- `@Experimental`: Use at your own risk - API may change without notice
+- `@SPI`: For framework extension and custom storage implementations
+
+## Additional Resources
+
+- [Spine Event Engine Website](https://spine.io/)
+- [Quick Start Guide](https://spine.io/docs/quick-start)
+- [Configuration Repository](https://github.com/SpineEventEngine/config/)
+- [Spine Examples](https://github.com/spine-examples)
+
+---
+
+*For more detailed information on specific topics, please refer to the comprehensive documentation in the [`.agents` directory](../.agents/_TOC.md).*

dependencies.md

@@ -1,6 +1,6 @@
 
 
-# Dependencies of `io.spine:spine-client:2.0.0-SNAPSHOT.342`
+# Dependencies of `io.spine:spine-client:2.0.0-SNAPSHOT.343`
 
 ## Runtime
 1.  **Group** : com.google.android. **Name** : annotations. **Version** : 4.1.1.4.
@@ -1085,14 +1085,14 @@
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Sat Nov 01 18:59:13 WET 2025** using 
+This report was generated on **Sun Nov 02 17:04:25 WET 2025** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.tools:spine-client-testlib:2.0.0-SNAPSHOT.342`
+# Dependencies of `io.spine.tools:spine-client-testlib:2.0.0-SNAPSHOT.343`
 
 ## Runtime
 1.  **Group** : com.google.android. **Name** : annotations. **Version** : 4.1.1.4.
@@ -2273,14 +2273,14 @@ This report was generated on **Sat Nov 01 18:59:13 WET 2025** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Sat Nov 01 18:59:13 WET 2025** using 
+This report was generated on **Sun Nov 02 17:04:25 WET 2025** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine:spine-core:2.0.0-SNAPSHOT.342`
+# Dependencies of `io.spine:spine-core:2.0.0-SNAPSHOT.343`
 
 ## Runtime
 1.  **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
@@ -3301,14 +3301,14 @@ This report was generated on **Sat Nov 01 18:59:13 WET 2025** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Sat Nov 01 18:59:13 WET 2025** using 
+This report was generated on **Sun Nov 02 17:04:25 WET 2025** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.tools:spine-core-testlib:2.0.0-SNAPSHOT.342`
+# Dependencies of `io.spine.tools:spine-core-testlib:2.0.0-SNAPSHOT.343`
 
 ## Runtime
 1.  **Group** : com.google.android. **Name** : annotations. **Version** : 4.1.1.4.
@@ -4375,14 +4375,14 @@ This report was generated on **Sat Nov 01 18:59:13 WET 2025** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Sat Nov 01 18:59:13 WET 2025** using 
+This report was generated on **Sun Nov 02 17:04:25 WET 2025** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine:spine-server:2.0.0-SNAPSHOT.342`
+# Dependencies of `io.spine:spine-server:2.0.0-SNAPSHOT.343`
 
 ## Runtime
 1.  **Group** : com.google.android. **Name** : annotations. **Version** : 4.1.1.4.
@@ -5479,14 +5479,14 @@ This report was generated on **Sat Nov 01 18:59:13 WET 2025** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Sat Nov 01 18:59:13 WET 2025** using 
+This report was generated on **Sun Nov 02 17:04:25 WET 2025** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.tools:spine-server-testlib:2.0.0-SNAPSHOT.342`
+# Dependencies of `io.spine.tools:spine-server-testlib:2.0.0-SNAPSHOT.343`
 
 ## Runtime
 1.  **Group** : com.google.android. **Name** : annotations. **Version** : 4.1.1.4.
@@ -6719,6 +6719,6 @@ This report was generated on **Sat Nov 01 18:59:13 WET 2025** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Sat Nov 01 18:59:13 WET 2025** using 
+This report was generated on **Sun Nov 02 17:04:25 WET 2025** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).

pom.xml

@@ -10,7 +10,7 @@ all modules and does not describe the project structure per-subproject.
  -->
 <groupId>io.spine</groupId>
 <artifactId>spine-core-jvm</artifactId>
-<version>2.0.0-SNAPSHOT.342</version>
+<version>2.0.0-SNAPSHOT.343</version>
 
 <inceptionYear>2015</inceptionYear>
 

version.gradle.kts

@@ -29,4 +29,4 @@
  *
  * For versions of Spine-based dependencies, please see [io.spine.dependency.local.Spine].
  */
-val versionToPublish: String by extra("2.0.0-SNAPSHOT.342")
+val versionToPublish: String by extra("2.0.0-SNAPSHOT.343")