Release 0.4.0: liveness-gated updates, self-recovery and a contract the fake answers to

Cuts the accumulated Unreleased section as 0.4.0 and brings the version in
build.gradle.kts back to reality: it had read 1.0.0 since the rewrite while the
tags went v0.2.0/v0.3.0, which was TODO #6 — now resolved by picking reality
over the placeholder.

Also records what the last three commits changed but did not document:

- the DockerClient contract both implementations answer to, and the randomized
  parse/dechunk properties, in CHANGELOG "Added";
- the three chunk headers that got past the truncation guard (a signed "-1"
  reaching a byte-range copy, "-0" read as a terminator, and pos+size
  overflowing the bounds check into its own opposite), in CHANGELOG "Fixed";
- DockerApiContractTest in E2E_TESTING.md, including why it is the one test in
  the suite that does not run by default;
- the contract as an enforced invariant in CLAUDE.md, so that behaviour the
  fake grows lands in the contract rather than in the fake alone.

TODO gains the gap this leaves: the daemon half of the contract runs nowhere in
CI, because DockerApi is unix-socket-only and the suite's DinD is TCP-only.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: IRus

CHANGELOG.md

@@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-28
+
 ### Added
 - Liveness gate before anything irreversible: a replacement container is probed for
   `KODKOD_UPDATE_VERIFY_SECONDS` (default 15) after `start`, and the old container and image are only
@@ -53,6 +55,35 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   daemon, before the dind suite. It cannot run against dind — `DockerApi` speaks only to a unix socket
   — so without it the half that catches the fake inventing behaviour runs nowhere automatically, which
   is how both inventions it has found so far were found by hand.
+- One `DockerClientContract` that both implementations have to answer to: `FakeDockerClient` runs it on
+  every `./gradlew test`, and `DockerApi` runs the same class against a real daemon under
+  `-Pkodkod.e2e.useCurrentDocker=true`. The fake can no longer be more forgiving than the daemon it
+  stands in for, which is what the unit suite has been trusting it to be — the first run of the pair
+  caught it reporting a just-created container as `running`, where Docker (and the fake's own listing)
+  call that state `created`.
+- Randomized round-trip properties over the hand-rolled HTTP/1.1 parsing, seeded so that a red run
+  names the one seed needed to reproduce it. The parser reads undertrusted bytes off a socket and every
+  caller treats what comes back as the daemon's word, so it is held to two outcomes only — a whole
+  answer or an error, never a short answer that looks whole. These found the chunk-header defects below.
+- Model-based testing of the update cycle (`UpdateCycleModelTest`): stacks are generated rather than
+  written down — random monitored containers, random staleness, random shared network namespaces,
+  unmanaged bystanders and unmanaged sidecars, and injected create/start/remove failures — and each
+  generated world is checked against what the daemon may never look like once a cycle has finished,
+  whatever that cycle did. Four properties: no two live containers hold one name, no running container
+  is left joined to a namespace that is gone (a provider that was destroyed is always kodkod's fault; a
+  provider the daemon refuses to start is only its fault if it says nothing), a container kodkod does
+  not manage is never touched, and whatever a cycle leaves stopped the next cycle reaches for again.
+  Every defect this project has had to unship was three or four events deep, which is the depth a
+  generator reaches and a story-teller does not. Each property is mutation-proven rather than assumed:
+  disabling the create-time dependent refresh, the enable-label filter, or the tracking of stopped
+  containers turns exactly one of them red. Failures print the seed and the world, so a red run is a
+  fixture that can be pasted into `UpdaterTest` as a story somebody has now thought of.
+- `DockerClientContract` gained the other half of the name index: `create` under a name another
+  container already holds is refused, exactly as `rename` is. The fake had been allowing it, so a
+  recreate could put a second container on the service name — which no daemon permits, and which the
+  ordering of the recreate path (rename the original away *first*) exists precisely to avoid.
+  Confirmed against Docker 29.6.2. A payload a test registers under the id `create` is about to assign
+  stays legal: that is the container being described before it exists, not a second holder of its name.
 
 ### Changed
 - The update cycle is split into a read-only `plan()` (list, inspect, registry probe, pull) and a
@@ -154,6 +185,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   its own name, which was refused and reported as two ERRORs about a container that never moved.
 - Chunked responses that were cut off mid-body are reported as transport errors instead of being
   returned as short-but-complete answers (an empty container list, an image with no tags).
+- Three chunk headers that got past that guard. `toIntOrNull(16)` accepts a sign RFC 9112 does not
+  allow: `-1` reached a byte-range copy as a negative length — an `IndexOutOfBoundsException` no caller
+  is written against — and `-0` read as the terminating chunk, so the prefix that had arrived was
+  returned as the whole answer, which is precisely the silent truncation the guard exists to prevent. A
+  size near `Int.MAX_VALUE` overflowed `pos + size` to a negative number, turning the bounds check into
+  its own opposite and handing the range straight to the copy. The size token is now required to be
+  `1*HEXDIG`, and the bounds check subtracts instead of adding.
 - Image references are escaped into request paths, an empty environment variable no longer reads as
   `false`, and the compose service key no longer embeds a literal NUL byte in the source.
 

CLAUDE.md

@@ -43,6 +43,13 @@ recreate containers whose image tag moved (update). Kotlin, one runtime dependen
   that runs more than one cycle. Keep it honest: a fake that keeps a removed container, or that
   matches every `health` filter regardless of the modelled health, makes the code that tells those
   cases apart untestable.
+- **That honesty is now enforced, not just asked for.** `DockerClientContract` (`src/testFixtures`)
+  is one suite both implementations answer to: `FakeDockerClientContractTest` runs it against the fake
+  on every `./gradlew test`, `DockerApiContractTest` runs the same class against a real daemon under
+  `-Pkodkod.e2e.useCurrentDocker=true`. A behaviour the unit suite is allowed to assume therefore has
+  to be one Docker was made to demonstrate. New behaviour the fake grows belongs in the contract, not
+  in the fake alone — that is the only thing standing between a green unit suite and a fake that
+  invented the daemon it stands in for.
 
 ## Fixture corpus (record/replay)
 

E2E_TESTING.md

@@ -336,6 +336,9 @@ src/e2eTest/kotlin/io/heapy/kodkod/e2e/KodkodE2eTest.kt      # the suite + E2eHa
 src/e2eTest/kotlin/io/heapy/kodkod/e2e/DockerFixtureRecorder.kt
 src/e2eTest/kotlin/io/heapy/kodkod/e2e/FixtureWriter.kt
 src/e2eTest/kotlin/io/heapy/kodkod/e2e/FixtureWriterTest.kt
+src/e2eTest/kotlin/io/heapy/kodkod/e2e/DockerApiContractTest.kt  # the contract, against a real daemon
+src/testFixtures/kotlin/io/heapy/kodkod/DockerClientContract.kt  # shared by both contract tests
+src/test/kotlin/io/heapy/kodkod/FakeDockerClientContractTest.kt  # the contract, against the fake
 src/main/kotlin/io/heapy/kodkod/DockerTransport.kt           # the seam both sides plug into
 src/main/kotlin/io/heapy/kodkod/UnixSocketTransport.kt       # production transport, what the recorder wraps
 src/testFixtures/kotlin/io/heapy/kodkod/DockerRecording.kt   # recording/replay transports + the corpus types

TODO.md

@@ -16,24 +16,22 @@
 5. `--link` заявлен как поддерживаемая create-time зависимость, и зависимые теперь пересоздаются вместе с
    провайдером, но сам `HostConfig.Links` при recreate передаётся как есть — watchtower нормализует его в
    отдельном `GetCreateHostConfig`.
-6. Версии разъехались: `build.gradle.kts` = 1.0.0, а теги — v0.2.0/v0.3.0. Решить: резать 1.0.0 или вернуть
-   версию к реальности.
 
 ## Надёжность и корректность
 
-7. `subtractImageDefaultsByKey` теряет пользовательские `Cmd`/`Entrypoint`/`User`/`WorkingDir`.
-8. `pull` буферизует весь прогресс-стрим в памяти.
-9. `DockerApi.create` бросает NPE без сообщения, когда в ответе нет `Id`.
-10. `isSelf` использует `id.startsWith(selfId)` — префиксное сравнение id.
+6. `subtractImageDefaultsByKey` теряет пользовательские `Cmd`/`Entrypoint`/`User`/`WorkingDir`.
+7. `pull` буферизует весь прогресс-стрим в памяти.
+8. `DockerApi.create` бросает NPE без сообщения, когда в ответе нет `Id`.
+9. `isSelf` использует `id.startsWith(selfId)` — префиксное сравнение id.
 
 ## Тесты и покрытие
 
-11. Multi-arch digest не проверен: `UpdaterTest` гоняет одиночные digest'ы, e2e — single-arch busybox. Сравнение
+10. Multi-arch digest не проверен: `UpdaterTest` гоняет одиночные digest'ы, e2e — single-arch busybox. Сравнение
     index-digest, скорее всего, корректно, но это классический watchtower-footgun без теста.
-12. Health-ветка liveness-гейта (`unhealthy` / `starting`) покрыта только юнит-тестами: и рекордер, и e2e идут с
+11. Health-ветка liveness-гейта (`unhealthy` / `starting`) покрыта только юнит-тестами: и рекордер, и e2e идут с
     `KODKOD_UPDATE_VERIFY_HEALTH=false`, потому что иначе число проб — гонка между интервалом проб и
     healthcheck'ом замены. Нужен детерминированный e2e (образ с предсказуемым healthcheck'ом).
-13. Grace-хук шатдауна в `Main.kt` (`awaitTermination` → `shutdownNow`) не покрыт тестом: `main()` не
+12. Grace-хук шатдауна в `Main.kt` (`awaitTermination` → `shutdownNow`) не покрыт тестом: `main()` не
     разбирается на тестируемые части. Из него проверен только `ConfigTest.reads_the_shutdown_grace_period`.
     Чтобы покрыть — выделить планировщик и хук в отдельную тестируемую функцию.
 14. Дублирование в тестах: хелперы `updateConfig`/`autohealConfig` рекордера и `config(...)` юнит-тестов.

build.gradle.kts

@@ -13,7 +13,7 @@ plugins {
 }
 
 group = "io.heapy"
-version = "1.0.0"
+version = "0.4.0"
 
 val junitVersion = "6.1.2"
 val serializationVersion = "1.11.0"