New Neo4jOperations access layer, object mapping, full test coverage, fix critical bugs and improve error handling (#17)

* Fix critical bugs and improve error handling

This commit addresses several issues found during code review:

**Critical Fixes:**
- Fix missing TransactionConfig parameter in InternalSession
  Previously, executeRead() and executeWrite() methods accepted a
  TransactionConfig parameter but did not pass it to the underlying
  Neo4j async methods. This caused transaction timeouts, metadata,
  and other configuration settings to be silently ignored.
  (src/main/kotlin/internal/InternalSession.kt:45, 56)

**Medium Priority Fixes:**
- Add consumption tracking to InternalResult.single()
  The single() method now uses the same AtomicBoolean mechanism as
  records() to prevent multiple consumption attempts and ensure
  consistent resource management.
  (src/main/kotlin/internal/InternalResult.kt:59-69)

**User Experience Improvements:**
- Improve error messages in NodeMapping.toObject()
  Enhanced error message when attempting to convert unsupported Value
  types, providing clear guidance on how to fix the issue with
  examples of common mistakes.
  (src/main/kotlin/NodeMapping.kt:130-134)

- Add documentation to SessionConfigBuilder
  Added KDoc warnings to bookmarks and bookmarkManager properties
  explaining their mutual exclusivity and that bookmarkManager takes
  precedence when both are set.
  (src/main/kotlin/Session.kt:563-597)

All changes verified with passing tests and API compatibility checks.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Add kotlinx.serialization mapping and Neo4jOperations API

This commit adds comprehensive object mapping support using
kotlinx.serialization and a high-level operations API.

**New Features:**

Object Mapping (NodeMapping.kt):
- toProperties(): Convert @serializable objects to Neo4j property maps
- toObject<T>(): Convert Neo4j nodes/relationships to Kotlin objects
- Support for primitives, lists, enums, and kotlin.time.Instant
- Validates against unsupported nested structures with clear errors

High-Level API (Neo4jOperations.kt):
- DispatchedNeo4jOperations: Session lifecycle management
- Convenience methods: read(), write(), withSession()
- Flow-based streaming with automatic resource cleanup
- populate(): Quick test data insertion

**API Changes:**
- Result.singleOrNull(): Extension function for optional single records
- Session.flow(): Streaming query results in read transactions
- Updated API surface (api/xemantic-neo4j-kotlin-driver.api)

**Dependencies:**
- Added kotlinx-serialization-core (API dependency)
- Added xemantic-kotlin-core for SuspendCloseable
- Removed local SuspendCloseable implementation

**Testing:**
- Comprehensive test coverage for mapping and operations
- Performance benchmarks for Result streaming
- Integration tests for round-trip serialization
- README examples as executable tests

**Build:**
- Updated Gradle wrapper to 9.2
- Dependency version updates
- GitHub Actions workflow improvements

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

---------

Co-authored-by: Claude <[email protected]>

Author: morisil

.github/workflows/build-branch.yml

@@ -19,7 +19,7 @@ jobs:
       - name: Setup Java
         uses: actions/[email protected]
         with:
-          distribution: 'temurin'
+          distribution: ${{ vars.DEFAULT_JAVA_DISTRIBUTION }}
           java-version: ${{ vars.DEFAULT_JAVA_VERSION }}
 
       - name: Setup Gradle

.github/workflows/build-main.yml

@@ -16,16 +16,17 @@ jobs:
       - name: Setup Java
         uses: actions/[email protected]
         with:
-          distribution: 'temurin'
+          distribution: ${{ vars.DEFAULT_JAVA_DISTRIBUTION }}
           java-version: ${{ vars.DEFAULT_JAVA_VERSION }}
 
       - name: Setup Gradle
         uses: gradle/actions/[email protected]
 
-      - name: Build
-        run: ./gradlew build kotlinSourcesJar javadocJar publish
+      - name: Build and Publish SNAPSHOT
         env:
-          ORG_GRADLE_PROJECT_signingKey: ${{ secrets.SIGNING_KEY }}
-          ORG_GRADLE_PROJECT_signingPassword: ${{ secrets.SIGNING_PASSWORD }}
-          ORG_GRADLE_PROJECT_githubActor: ${{ secrets.GITHUBACTOR }}
-          ORG_GRADLE_PROJECT_githubToken: ${{ secrets.GITHUBTOKEN }}
+          ORG_GRADLE_PROJECT_mavenCentralUsername: ${{ secrets.MAVEN_CENTRAL_USERNAME }}
+          ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}
+          ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.SIGNING_KEY }}
+          ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.SIGNING_PASSWORD }}
+
+        run: ./gradlew build publishToMavenCentral --no-configuration-cache

.github/workflows/build-release.yml

@@ -25,37 +25,26 @@ jobs:
       - name: Setup Java
         uses: actions/[email protected]
         with:
-          distribution: 'temurin'
+          distribution: ${{ vars.DEFAULT_JAVA_DISTRIBUTION }}
           java-version: ${{ vars.DEFAULT_JAVA_VERSION }}
 
       - name: Setup Gradle
         uses: gradle/actions/[email protected]
 
-      - name: Build
+      - name: Build and Publish release
         env:
-          ORG_GRADLE_PROJECT_githubActor: ${{ secrets.GITHUBACTOR }}
-          ORG_GRADLE_PROJECT_githubToken: ${{ secrets.GITHUBTOKEN }}
-          ORG_GRADLE_PROJECT_signingKey: ${{ secrets.SIGNING_KEY }}
-          ORG_GRADLE_PROJECT_signingPassword: ${{ secrets.SIGNING_PASSWORD }}
-          JRELEASER_DEPLOY_MAVEN_MAVENCENTRAL_MAVEN_CENTRAL_USERNAME: ${{ secrets.MAVEN_CENTRAL_USERNAME }}
-          JRELEASER_DEPLOY_MAVEN_MAVENCENTRAL_MAVEN_CENTRAL_PASSWORD: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}
+          ORG_GRADLE_PROJECT_mavenCentralUsername: ${{ secrets.MAVEN_CENTRAL_USERNAME }}
+          ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}
+          ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.SIGNING_KEY }}
+          ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.SIGNING_PASSWORD }}
           JRELEASER_DISCORD_WEBHOOK: ${{ secrets.DISCORD_ANNOUCEMENTS_WEBHOOK }}
           JRELEASER_LINKEDIN_ACCESS_TOKEN: ${{ secrets.LINKEDIN_ACCESS_TOKEN }}
           JRELEASER_LINKEDIN_OWNER: ${{ secrets.LINKEDIN_OWNER }}
           JRELEASER_BLUESKY_HOST: ${{ vars.BLUESKY_HOST }}
           JRELEASER_BLUESKY_HANDLE: ${{ vars.BLUESKY_HANDLE }}
           JRELEASER_BLUESKY_PASSWORD: ${{ secrets.BLUESKY_PASSWORD }}
 
-        run: ./gradlew -Pversion=$VERSION build kotlinSourcesJar javadocJar publish jreleaserFullRelease
-
-      - name: Display JReleaser trace.log
-        run: |
-          if [ -f build/jreleaser/trace.log ]; then
-            echo "trace.log Content:"
-            cat build/jreleaser/trace.log
-          else
-            echo "trace.log file not found"
-          fi
+        run: ./gradlew -Pversion=$VERSION build publishToMavenCentral jreleaserAnnounce --no-configuration-cache
 
       - name: Get target branch for tag
         run: |
@@ -70,11 +59,11 @@ jobs:
           ref: ${{ env.TARGET_BRANCH }}
           fetch-depth: 0
 
-      - name: Update README
-        run: ./gradlew -Pversion=$VERSION updateVersionInReadme
+      - name: Update versions after release
+        run: ./gradlew -Pversion=$VERSION updateVersionsAfterRelease
 
-      - name: Commit README.md pointing to released version
+      - name: Commit version updates after release
         uses: stefanzweifel/[email protected]
         with:
-          commit_message: Dependency version in README.md updated to ${{ env.VERSION }}
-          file_pattern: 'README.md'
+          commit_message: Version updated to ${{ env.VERSION }} in README.md, next snapshot in gradle.properties
+          file_pattern: 'README.md gradle.properties'