alexander-yevsyukov · Oct 20, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026
diff --git a/.agents/tasks/disable-protobuf-version-check.md b/.agents/tasks/disable-protobuf-version-check.md
@@ -0,0 +1,105 @@
+---
+slug: disable-protobuf-version-check
+branch: disable-protobuf-version-check
+owner: claude
+status: in-review
+started: 2026-10-19
+---
+
+## Goal
+
+Users can turn off the Protobuf runtime/gencode version check in the process
+of the Compiler with a DSL call instead of exporting an environment variable:
+
+```kotlin
+spine {
+    compiler {
+        disableProtobufVersionCheck.set(true)
+    }
+}
+```
+
+The property controls `TEMPORARILY_DISABLE_PROTOBUF_VERSION_CHECK` in the environment
+of every `LaunchSpineCompiler` fork: `true` sets it to `true` (check off), `false`
+removes it (check on, even if the build exports it), not set (default) inherits it
+from the build. A default that cleared the variable would silently break builds
+relying on the exported variable, including this repo's functional tests
+(`RunnerTuning.tuneRunner()`), hence three states rather than `false` by default.
+
+## Context
+
+- `protobuf-java` 4.x validates the gencode version against the runtime in
+  `RuntimeVersion.validateProtobufGencodeVersion()` and skips the check only
+  when `System.getenv("TEMPORARILY_DISABLE_PROTOBUF_VERSION_CHECK")` is `"true"`.
+  The Compiler fork is where a user classpath (plugins built with another
+  `protoc`) meets the Compiler's Protobuf runtime, so it is the process where
+  users hit the check.
+- Today the only ways are exporting the variable for the Gradle daemon, or
+  `tasks.withType<LaunchSpineCompiler> { environment(...) }`. The new property
+  is a convenience shortcut for the latter.
+- Gradle 9.8.1 (this branch's wrapper; also checked 9.7.1)
+  `DefaultProcessForkOptions.getActualEnvironment()` converts values
+  with `String.valueOf()` — no `Provider` unpacking, so the setting cannot be
+  passed to `environment` lazily (`JavaExec.getEnvironment()` is marked
+  `@ToBeReplacedByLazyProperty`).
+- A probe showed the launch tasks are not realized while the plugins are applied,
+  but in the `afterEvaluate` hooks, after the build script body. So `applyDefaults()`
+  reads the setting at configuration time; the extension property is
+  `finalizeValueOnRead()`, so a change after that (early task realization, a late
+  `afterEvaluate`) fails loudly instead of being ignored.
+- `Extension` is the only implementation of `CompilerSettings` across Spine repos
+  (`core-jvm-compiler` only calls it), so adding an interface member is safe.
+- Out of scope: the Gradle daemon and the `protoc` plugin processes. Their
+  environment cannot be changed from the build script; users still export the
+  variable for those.
+- After #90 (`align-protobuf-runtime`), the fork runs on the highest Protobuf runtime
+  requested by the CLI and by `spineCompiler`, so a newer plugin runtime no longer
+  fails. The setting remains for builds that force an older runtime (e.g. via `force`).
+- End-to-end: the `protobuf-runtime-test` fixture from #90 removes the variable in
+  the fork. `DisableProtobufVersionCheckSpec` reuses it, forcing the CLI runtime
+  below the plugin gencode (`4.37.0-RC1`) so the check really fails.
+
+## Plan
+
+- [x] `CompilerSettings` (`gradle-api`): add
+      `public val disableProtobufVersionCheck: Property<Boolean>` with KDoc.
+- [x] `Extension` (`gradle-plugin`): implement it, not set by default,
+      `finalizeValueOnRead()`.
+- [x] `LaunchSpineCompiler`: no copy of the setting on the task (review by
+      the user). `applyDefaults()` calls
+      `applyProtobufVersionCheckSetting(ext.disableProtobufVersionCheck.orNull)`:
+      `true` sets the variable, `false` removes it, `null` leaves the environment
+      intact. Not a task input: the check does not change the outputs.
+- [x] Tests (`gradle-plugin/src/test`):
+  - [x] `ExtensionSpec` — not set by default.
+  - [x] `LaunchTaskEnvironmentSpec` — the extension's value reaches the task;
+        a change after the task is configured is rejected; `null` keeps
+        a planted inherited value; `true` sets the variable; `false` removes
+        a planted `true`.
+- [x] Functional test `DisableProtobufVersionCheckSpec` — `false` keeps the check
+      even when the build sets the variable (fails with
+      `ProtobufRuntimeVersionException`); `true` lets the Compiler run.
+- [x] Docs: `gradle-plugin/README.md` configuration table + a short section on
+      when to use it and its scope.
+- [x] Version bump `.077` → `.079` (`.078` is taken by
+      `origin/align-protobuf-runtime`), `./gradlew build`, dependency reports,
+      `dokkaGenerate`.
+- [x] Commits: `` Bump version -> `2.0.0-SNAPSHOT.079` ``, the feature, and
+      `Update dependency reports`.
+
+## Log
+
+- 2026-10-19 — drafted in worktree `.claude/worktrees/disable-protobuf-version-check`
+  branched from `origin/master` @ `977762d8f9`.
+- 2026-10-19 — implemented; `./gradlew build dokkaGenerate` green; reviews by
+  `kotlin-engineer` (APPROVE), `spine-code-review` and `review-docs`
+  (APPROVE WITH CHANGES) applied: planted-value test, `protoc` plugins wording,
+  `applyDefaults` KDoc exception note.
+- 2026-10-19 — the worktree's pinned `.agents/shared` `version-bumped.sh` cannot
+  parse `extra.set(...)` in `version.gradle.kts` (exit 2); the floated copy in
+  the main checkout handles it. Fixed upstream; resolves on the next `config` pull.
+- 2026-10-19 — PR #95 opened; merged `origin/master` after #90 landed (conflicts only
+  in `version.gradle.kts` and reports; kept `.079`); CodeMatters headers applied.
+- 2026-10-19 — per review by the user, `false` now removes the variable; the default
+  became "not set" to keep the exported-variable workaround working. Added the
+  end-to-end spec.
diff --git a/docs/dependencies/dependencies.md b/docs/dependencies/dependencies.md
@@ -1,6 +1,6 @@
 
 
-# Dependencies of `io.spine.tools:compiler-api:2.0.0-SNAPSHOT.078`
+# Dependencies of `io.spine.tools:compiler-api:2.0.0-SNAPSHOT.079`
 
 ## Runtime
 1.  **Group** : be.cyberelf.nanoxml. **Name** : nanoxml. **Version** : 2.2.3.
@@ -1864,14 +1864,14 @@
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Mon Oct 19 19:23:54 WEST 2026** using 
+This report was generated on **Mon Oct 19 20:40:19 WEST 2026** 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:compiler-api-tests:2.0.0-SNAPSHOT.078`
+# Dependencies of `io.spine.tools:compiler-api-tests:2.0.0-SNAPSHOT.079`
 
 ## Runtime
 ## Compile, tests, and tooling
@@ -2582,14 +2582,14 @@ This report was generated on **Mon Oct 19 19:23:54 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Mon Oct 19 19:23:30 WEST 2026** using 
+This report was generated on **Mon Oct 19 20:40:18 WEST 2026** 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:compiler-backend:2.0.0-SNAPSHOT.078`
+# Dependencies of `io.spine.tools:compiler-backend:2.0.0-SNAPSHOT.079`
 
 ## Runtime
 1.  **Group** : be.cyberelf.nanoxml. **Name** : nanoxml. **Version** : 2.2.3.
@@ -4457,14 +4457,14 @@ This report was generated on **Mon Oct 19 19:23:30 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Mon Oct 19 19:23:56 WEST 2026** using 
+This report was generated on **Mon Oct 19 20:40:19 WEST 2026** 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:compiler-cli:2.0.0-SNAPSHOT.078`
+# Dependencies of `io.spine.tools:compiler-cli:2.0.0-SNAPSHOT.079`
 
 ## Runtime
 1.  **Group** : be.cyberelf.nanoxml. **Name** : nanoxml. **Version** : 2.2.3.
@@ -6540,14 +6540,14 @@ This report was generated on **Mon Oct 19 19:23:56 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Mon Oct 19 19:23:56 WEST 2026** using 
+This report was generated on **Mon Oct 19 20:40:19 WEST 2026** 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:compiler-gradle-api:2.0.0-SNAPSHOT.078`
+# Dependencies of `io.spine.tools:compiler-gradle-api:2.0.0-SNAPSHOT.079`
 
 ## Runtime
 1.  **Group** : be.cyberelf.nanoxml. **Name** : nanoxml. **Version** : 2.2.3.
@@ -8301,14 +8301,14 @@ This report was generated on **Mon Oct 19 19:23:56 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Mon Oct 19 19:23:55 WEST 2026** using 
+This report was generated on **Mon Oct 19 20:40:19 WEST 2026** 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:compiler-gradle-plugin:2.0.0-SNAPSHOT.078`
+# Dependencies of `io.spine.tools:compiler-gradle-plugin:2.0.0-SNAPSHOT.079`
 
 ## Runtime
 1.  **Group** : be.cyberelf.nanoxml. **Name** : nanoxml. **Version** : 2.2.3.
@@ -10102,14 +10102,14 @@ This report was generated on **Mon Oct 19 19:23:55 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Mon Oct 19 19:23:56 WEST 2026** using 
+This report was generated on **Mon Oct 19 20:40:19 WEST 2026** 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:compiler-jvm:2.0.0-SNAPSHOT.078`
+# Dependencies of `io.spine.tools:compiler-jvm:2.0.0-SNAPSHOT.079`
 
 ## Runtime
 1.  **Group** : be.cyberelf.nanoxml. **Name** : nanoxml. **Version** : 2.2.3.
@@ -12043,14 +12043,14 @@ This report was generated on **Mon Oct 19 19:23:56 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Mon Oct 19 19:23:32 WEST 2026** using 
+This report was generated on **Mon Oct 19 20:40:19 WEST 2026** 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:compiler-params:2.0.0-SNAPSHOT.078`
+# Dependencies of `io.spine.tools:compiler-params:2.0.0-SNAPSHOT.079`
 
 ## Runtime
 1.  **Group** : be.cyberelf.nanoxml. **Name** : nanoxml. **Version** : 2.2.3.
@@ -13906,14 +13906,14 @@ This report was generated on **Mon Oct 19 19:23:32 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Mon Oct 19 19:23:55 WEST 2026** using 
+This report was generated on **Mon Oct 19 20:40:19 WEST 2026** 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:compiler-protoc-plugin:2.0.0-SNAPSHOT.078`
+# Dependencies of `io.spine.tools:compiler-protoc-plugin:2.0.0-SNAPSHOT.079`
 
 ## Runtime
 1.  **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
@@ -14820,14 +14820,14 @@ This report was generated on **Mon Oct 19 19:23:55 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Mon Oct 19 19:23:32 WEST 2026** using 
+This report was generated on **Mon Oct 19 20:40:18 WEST 2026** 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:compiler-test-env:2.0.0-SNAPSHOT.078`
+# Dependencies of `io.spine.tools:compiler-test-env:2.0.0-SNAPSHOT.079`
 
 ## Runtime
 1.  **Group** : be.cyberelf.nanoxml. **Name** : nanoxml. **Version** : 2.2.3.
@@ -16671,14 +16671,14 @@ This report was generated on **Mon Oct 19 19:23:32 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Mon Oct 19 19:23:31 WEST 2026** using 
+This report was generated on **Mon Oct 19 20:40:19 WEST 2026** 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:compiler-testlib:2.0.0-SNAPSHOT.078`
+# Dependencies of `io.spine.tools:compiler-testlib:2.0.0-SNAPSHOT.079`
 
 ## Runtime
 1.  **Group** : be.cyberelf.nanoxml. **Name** : nanoxml. **Version** : 2.2.3.
@@ -18647,6 +18647,6 @@ This report was generated on **Mon Oct 19 19:23:31 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Mon Oct 19 19:23:56 WEST 2026** using 
+This report was generated on **Mon Oct 19 20:40:19 WEST 2026** 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).
diff --git a/docs/dependencies/pom.xml b/docs/dependencies/pom.xml
@@ -10,7 +10,7 @@ all modules and does not describe the project structure per-subproject.
  -->
 <groupId>io.spine.tools</groupId>
 <artifactId>compiler</artifactId>
-<version>2.0.0-SNAPSHOT.078</version>
+<version>2.0.0-SNAPSHOT.079</version>
 
 <inceptionYear>2015</inceptionYear>
 

diff --git a/gradle-api/src/main/kotlin/io/spine/tools/compiler/gradle/api/CompilerSettings.kt b/gradle-api/src/main/kotlin/io/spine/tools/compiler/gradle/api/CompilerSettings.kt
@@ -1,32 +1,21 @@
 /*
- * Copyright 2026, TeamDev. All rights reserved.
+ * Copyright 2026 CodeMatters, Lda.
  *
- * Licensed 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
+ * Licensed 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
  *
- * Redistribution and use in source and/or binary forms, with or without
- * modification, must retain the above copyright notice and the following
- * disclaimer.
- *
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ * 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.
  */
 
 package io.spine.tools.compiler.gradle.api
 
 import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.provider.Property
 
 /**
  * Configures the code generation process performed by the Compiler.
@@ -64,4 +53,49 @@ public interface CompilerSettings {
      * By default, points at the `$projectDir/generated/` directory.
      */
     public val outputBaseDir: DirectoryProperty
+
+    /**
+     * Tells whether to disable the Protobuf version check in the Compiler process.
+     *
+     * The Protobuf runtime checks that the code generated by `protoc` is compatible
+     * with the runtime — in particular, that it is not newer than the runtime — and
+     * fails otherwise. The Compiler runs on the highest Protobuf runtime requested by
+     * the Compiler itself and by its plugins, which avoids such a failure in most cases.
+     * The check may still fail, for example, when the build forces a Protobuf runtime
+     * older than the one the plugins were built with.
+     *
+     * The check is turned off by the `TEMPORARILY_DISABLE_PROTOBUF_VERSION_CHECK`
+     * environment variable set to `true`. This property controls the variable in
+     * the environment of the Compiler process:
+     *
+     *  - `true` sets the variable to `true`, turning the check off;
+     *  - `false` removes the variable, so the check is performed even if the variable
+     *    is set in the environment of the build;
+     *  - when the property is not set, which is the default, the Compiler process
+     *    inherits the variable from the environment of the build, if any.
+     *
+     * This is a shortcut for setting the variable in the environment of
+     * the `LaunchSpineCompiler` tasks directly.
+     *
+     * The tasks read the property when they are configured, which happens after
+     * the build script is evaluated. Set the property in the `compiler { }` block:
+     * once read, it cannot be changed.
+     *
+     * The setting affects neither the Gradle daemon nor the `protoc` plugins.
+     * If the check fails there, set the variable in the environment of the build instead.
+     *
+     * Use this setting only as a temporary workaround until the Protobuf versions
+     * are aligned.
+     *
+     * Example (`build.gradle.kts`):
+     *
+     * ```kotlin
+     * spine {
+     *     compiler {
+     *         disableProtobufVersionCheck.set(true)
+     *     }
+     * }
+     * ```
+     */
+    public val disableProtobufVersionCheck: Property<Boolean>
 }