feat(kompact): v1 serialization framework + docs audit + CI + code review fixes

.editorconfig

@@ -0,0 +1,65 @@
+root = true
+
+# Kotlin source files
+[*.kt]
+max_line_length = 120
+ktlint_code_style = ktlint_official
+indent_style = space
+indent_size = 4
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true
+ktlint_standard_import-sorting = "ascii"
+
+# Gradle Kotlin DSL files
+[*.gradle.kts]
+max_line_length = 120
+ktlint_code_style = ktlint_official
+indent_style = space
+indent_size = 4
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# TOML (version catalog)
+[*.toml]
+max_line_length = 120
+indent_style = space
+indent_size = 4
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# YAML / CI workflows
+[*.{yml,yaml}]
+max_line_length = 120
+indent_style = space
+indent_size = 2
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# Markdown
+[*.md]
+max_line_length = 120
+indent_style = space
+indent_size = 4
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# Properties files
+[*.properties]
+max_line_length = 120
+indent_style = space
+indent_size = 4
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# Gradle wrapper properties
+[gradle-wrapper.properties]
+max_line_length = 120
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true

.env.example

@@ -0,0 +1,27 @@
+# Maven Central Portal publishing — environment variables
+# Copy to .env and fill in real values. NEVER commit .env.
+# See references/central-release-report.md and .scratch/kompact-spec/issues/14-maven-central-publishing.md
+
+# --- Central Portal API token (https://central.sonatype.com/ → Account → User Tokens) ---
+CENTRAL_PORTAL_TOKEN_USERNAME=
+CENTRAL_PORTAL_TOKEN_PASSWORD=
+
+# --- Deployment ID (written to build/portal/deployment-id by centralPortalDeploy) ---
+# Optionally set this instead of letting the task read the saved file.
+CENTRAL_PORTAL_DEPLOYMENT_ID=
+
+# --- PGP signing key (ASCII-armored private key, from `gpg --armor --export-secret-keys`) ---
+# SIGNING_KEY_ID: 16-char long key ID (e.g. C9E0F0E1681C9AF1). Gradle's signing
+# plugin rejects 16-char IDs without 0x prefix; the loader script auto-shortens to
+# the last 8 chars (e.g. 681C9AF1) before passing to Gradle. The .env file keeps
+# the full long ID.
+SIGNING_KEY=
+SIGNING_KEY_ID=
+SIGNING_PASSWORD=
+
+# --- CI/CD (GitHub Actions) ---
+# These are committed as repository secrets, not in .env.
+# COPILOT_GITHUB_TOKEN is already present (created 2026-09-03).
+# Add: SIGNING_KEY, SIGNING_KEY_ID, SIGNING_PASSWORD,
+#      CENTRAL_PORTAL_TOKEN_USERNAME, CENTRAL_PORTAL_TOKEN_PASSWORD
+# via: gh secret set <NAME> --repo trancee/kompact

.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+# Validates the public ABI goldens and runs the JVM test suite.
+# apiCheck (macOS) enforces both kompact.api (JVM) and kompact.klib.api (merged
+# ios klib) with strictValidation — iOS klibs can only be compiled on Apple
+# hosts, so the klib golden is only meaningfully validated on the macOS job.
+# On Linux, klibApiCheck fails (unsupported targets); the Linux job runs
+# jvmApiCheck + jvmTest only (fast JVM API gate before the macOS final gate).
+
+on:
+  push:
+    branches:
+      - main
+      - master
+      - 'feat/**'
+  pull_request:
+    branches:
+      - main
+      - master
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  api-check:
+    name: apiCheck + spotlessCheck (macOS)
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: 21
+          cache: gradle
+      - run: ./gradlew spotlessCheck :kompact:apiCheck --no-daemon --rerun-tasks --no-build-cache --warning-mode all
+      # The committed rendered reference in kompact/docs/api/ must stay in sync
+      # with the KDoc in commonMain. Regenerate and fail if the committed tree
+      # drifts (up-to-date checking means dokka only re-runs when KDoc changes).
+      # macOS only: dokka analyses the iOS klibs, which can't be compiled on Linux.
+      - name: Verify generated Dokka reference is in sync
+        run: |
+          ./gradlew :kompact:dokkaGeneratePublicationHtml --no-daemon --console=plain
+          git diff --exit-code -- kompact/docs/api/
+
+  jvm-test:
+    name: jvmTest + jvmApiCheck + spotlessCheck + koverVerify (Linux)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: 21
+          cache: gradle
+      - run: ./gradlew spotlessCheck :kompact:koverVerify :kompact:jvmTest :kompact:jvmApiCheck --no-daemon --rerun-tasks --no-build-cache --warning-mode all

.github/workflows/regen-goldens.yml

@@ -22,16 +22,16 @@ jobs:
   regen:
     runs-on: macos-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-java@v4
+      - uses: actions/checkout@v5
+      - uses: actions/setup-java@v5
         with:
           distribution: temurin
           java-version: 21
           cache: gradle
       - name: Regenerate ABI goldens
         run: ./gradlew ${{ inputs.args }} --no-daemon
       - name: Upload regenerated goldens
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
         with:
           name: api-goldens
           path: kompact/api/

.gitignore

@@ -0,0 +1,34 @@
+# Gradle
+.gradle/
+.kotlin/
+.poolside/
+build/
+out/
+gradle/wrapper/dists/
+
+# Artifacts
+*.jar
+*.war
+*.class
+*.klib
+*.knp
+# The Gradle wrapper jar MUST be committed (gradle/wrapper/gradle-wrapper.jar) so
+# `./gradlew` works in CI/dev — un-ignore it despite the *.jar rule above.
+!gradle/wrapper/gradle-wrapper.jar
+
+# IDE
+.idea/
+*.iml
+local.properties
+
+# OS
+.DS_Store
+
+# Tooling / environment (not part of the library)
+.poolside/
+.env
+
+# Generated Dokka HTML API reference for the kompact module. The rendered
+# site in docs/api/ is committed (so the in-repo api-reference.md pointer is
+# always live); regenerate with `:kompact:dokkaGeneratePublicationHtml`.
+# KDoc in commonMain is the source of truth for the API surface.