fix(app): preserve controller image inspection errors

Author: skulidropek

packages/app/src/docker-git/controller-image-revision.ts

@@ -8,35 +8,6 @@ import type { ControllerBootstrapError } from "./host-errors.js"
 const inspectControllerRevisionLabelTemplate = String
   .raw`{{ index .Config.Labels "io.prover-coder-ai.docker-git.controller-rev" }}`
 
-/**
- * Builds a typed controller bootstrap error.
- *
- * @param message - Human-readable bootstrap failure message.
- * @returns Controller bootstrap error value.
- *
- * @pure true
- * @effect n/a
- * @invariant Returned error tag is always `ControllerBootstrapError`.
- * @precondition `message` is a finite string.
- * @postcondition The returned error preserves the provided message.
- * @complexity O(1) time and O(1) space.
- * @throws Never
- */
-// CHANGE: represent deterministic image-resolution failures as typed bootstrap errors
-// WHY: ambiguous compose image output must fail through the Effect error channel
-// QUOTE(ТЗ): "хочу сузить время билда докер контейнера"
-// REF: user-request-2026-05-22-controller-build-speed
-// SOURCE: n/a
-// FORMAT THEOREM: error(message).message = message
-// PURITY: CORE
-// EFFECT: n/a
-// INVARIANT: error tag is stable
-// COMPLEXITY: O(1)
-const controllerBootstrapError = (message: string): ControllerBootstrapError => ({
-  _tag: "ControllerBootstrapError",
-  message
-})
-
 /**
  * Returns all non-empty lines from Docker CLI output.
  *
@@ -72,56 +43,40 @@ const nonEmptyLines = (output: string): ReadonlyArray<string> => {
  * Resolves compose image output into exactly one controller image name.
  *
  * @param output - Raw `docker compose config --images` output.
- * @returns Effect with the single image, null for empty output, or a typed bootstrap error for ambiguity.
+ * @returns The single image, or null for empty/ambiguous output.
  *
  * @pure true
- * @effect Effect.succeed | Effect.fail
- * @invariant More than one non-empty line is rejected as ambiguous.
+ * @effect n/a
+ * @invariant More than one non-empty line never collapses to the first image.
  * @precondition `output` is finite Docker CLI output.
  * @postcondition Success with a string implies exactly one non-empty image line existed.
  * @complexity O(n) time and O(n) space where n = |output|.
- * @throws Never - ambiguity is represented in the Effect error channel.
+ * @throws Never
  */
 // CHANGE: require deterministic controller image resolution from compose output
 // WHY: revision reuse is sound only when the inspected image is uniquely the controller image
 // QUOTE(ТЗ): "хочу сузить время билда докер контейнера"
 // REF: user-request-2026-05-22-controller-build-speed
 // SOURCE: n/a
-// FORMAT THEOREM: |images| = 0 -> null, |images| = 1 -> images[0], |images| > 1 -> error
+// FORMAT THEOREM: |images| = 1 -> images[0], otherwise null
 // PURITY: CORE
-// EFFECT: Effect<string | null, ControllerBootstrapError>
+// EFFECT: n/a
 // INVARIANT: multiple compose images never collapse to the first image
 // COMPLEXITY: O(n) where n = |output|
-const resolveSingleControllerImageName = (
-  output: string
-): Effect.Effect<string | null, ControllerBootstrapError> => {
+const resolveSingleControllerImageName = (output: string): string | null => {
   const imageNames = nonEmptyLines(output)
-  if (imageNames.length === 0) {
-    return Effect.succeed(null)
-  }
   const imageName = imageNames[0]
-  if (imageNames.length === 1 && imageName !== undefined) {
-    return Effect.succeed(imageName)
-  }
-  return Effect.fail(
-    controllerBootstrapError(
-      [
-        "Expected exactly one docker-git controller image from docker compose config --images.",
-        "Resolved images:",
-        ...imageNames.map((name) => `- ${name}`)
-      ].join("\n")
-    )
-  )
+  return imageNames.length === 1 && imageName !== undefined ? imageName : null
 }
 
 /**
  * Resolves the Docker image name configured for the active controller compose files.
  *
- * @returns The single compose image name, or null when compose emits no images.
+ * @returns The single compose image name, or null when compose emits zero or multiple images.
  *
  * @pure false
  * @effect Docker CLI through ControllerRuntime.
- * @invariant Multiple compose images fail rather than selecting the first line.
+ * @invariant Multiple compose images return null rather than selecting the first line.
  * @precondition Compose files resolve for the current GPU mode.
  * @postcondition Returned image name is trimmed and non-empty.
  * @complexity O(1) compose invocations.
@@ -132,10 +87,10 @@ const resolveSingleControllerImageName = (
 // QUOTE(ТЗ): "хочу сузить время билда докер контейнера"
 // REF: user-request-2026-05-22-controller-build-speed
 // SOURCE: n/a
-// FORMAT THEOREM: |compose_images| <= 1 or bootstrap fails
+// FORMAT THEOREM: |compose_images| = 1 -> image name, otherwise null
 // PURITY: SHELL
 // EFFECT: Effect<string | null, ControllerBootstrapError, ControllerRuntime>
-// INVARIANT: ambiguous image lists are typed bootstrap errors
+// INVARIANT: ambiguous image lists are not treated as reusable images
 // COMPLEXITY: O(1) Docker compose invocations
 const inspectControllerComposeImageName = (): Effect.Effect<
   string | null,
@@ -156,7 +111,7 @@ const inspectControllerComposeImageName = (): Effect.Effect<
       )
     )
 
-    return yield* _(resolveSingleControllerImageName(output))
+    return resolveSingleControllerImageName(output)
   })
 
 /**
@@ -166,7 +121,7 @@ const inspectControllerComposeImageName = (): Effect.Effect<
  *
  * @pure false
  * @effect Docker CLI through ControllerRuntime.
- * @invariant Missing or ambiguous compose image output resolves to null rather than throwing.
+ * @invariant Missing image or missing label resolves to null rather than throwing.
  * @precondition Docker is reachable through the configured runtime.
  * @postcondition Returned revision is normalized by label parsing.
  * @complexity O(1) Docker inspections.
@@ -180,15 +135,14 @@ const inspectControllerComposeImageName = (): Effect.Effect<
 // FORMAT THEOREM: image_label(image) = local_revision -> no rebuild is required
 // PURITY: SHELL
 // EFFECT: Effect<string | null, ControllerBootstrapError, ControllerRuntime>
-// INVARIANT: missing or unresolvable image metadata resolves to null rather than throwing
+// INVARIANT: missing image or missing label resolves to null rather than throwing
 // COMPLEXITY: O(1) Docker inspections
 export const inspectControllerImageRevision = (): Effect.Effect<
   string | null,
   ControllerBootstrapError,
   ControllerRuntime
 > =>
   inspectControllerComposeImageName().pipe(
-    Effect.orElseSucceed((): string | null => null),
     Effect.flatMap((imageName) =>
       imageName === null
         ? Effect.succeed<string | null>(null)

packages/app/tests/docker-git/controller-image-revision.test.ts

@@ -7,6 +7,7 @@ import { Effect, Layer } from "effect"
 import * as Inspectable from "effect/Inspectable"
 import * as Sink from "effect/Sink"
 import * as Stream from "effect/Stream"
+import * as fc from "fast-check"
 
 import { inspectControllerImageRevision } from "../../src/docker-git/controller-image-revision.js"
 
@@ -21,6 +22,15 @@ const emptyCommandResult: TestCommandResult = {
   stderr: "",
   stdout: ""
 }
+const composeImageLineArbitrary = fc
+  .string({ minLength: 1 })
+  .filter((value) => value.trim().length > 0 && !value.includes("\n") && !value.includes("\r"))
+const nonReusableComposeImagesOutputArbitrary = fc.oneof(
+  fc.constantFrom("", "\n", " \n\t\n"),
+  fc.array(composeImageLineArbitrary, { maxLength: 8, minLength: 2 }).map((lines) =>
+    lines.map((line) => ` ${line} `).join("\n")
+  )
+)
 
 const encodeText = (value: string): Uint8Array => new TextEncoder().encode(value)
 
@@ -97,23 +107,56 @@ const commandExecutorLayer = (handler: TestCommandHandler) =>
     })
   )
 
-describe("controller image revision", () => {
-  it.effect("falls back to null when compose image resolution is ambiguous", () =>
-    Effect.gen(function*(_) {
-      const revision = yield* _(
-        inspectControllerImageRevision().pipe(
-          Effect.provide(
-            commandExecutorLayer((command) =>
-              command.command === "docker" && command.args.includes("--images")
-                ? { exitCode: 0, stderr: "", stdout: "app-api:latest\nanother-image:latest\n" }
-                : emptyCommandResult
-            )
-          ),
-          Effect.provide(FileSystem.layerNoop({})),
-          Effect.provide(Path.layer)
-        )
+/**
+ * Runs image revision inspection with controlled `docker compose config --images` output.
+ *
+ * @param composeImagesOutput - Stdout emitted by the fake `--images` command.
+ * @returns Effect producing the inspected image revision.
+ * @pure false
+ * @effect CommandExecutor, FileSystem, Path
+ * @invariant Docker commands are served by the in-memory command executor.
+ * @precondition `composeImagesOutput` is finite text.
+ * @postcondition The real Docker daemon is never invoked.
+ * @complexity O(n) time and space where n = |composeImagesOutput|.
+ * @throws Never - all command failures are represented in the Effect error channel.
+ */
+// CHANGE: centralize the mocked compose image inspection path for property tests
+// WHY: the fallback invariant depends only on normalized compose stdout cardinality
+// QUOTE(ТЗ): "комментарии ребита надо было тоже поддержать"
+// REF: CodeRabbit PR #344 review 4349246446
+// SOURCE: n/a
+// FORMAT THEOREM: output -> inspectControllerImageRevision(output)
+// PURITY: SHELL
+// EFFECT: Effect<string | null, ControllerBootstrapError, ControllerRuntime>
+// INVARIANT: Docker command output is supplied by the test harness
+// COMPLEXITY: O(n)
+const inspectRevisionWithComposeImagesOutput = (composeImagesOutput: string) =>
+  inspectControllerImageRevision().pipe(
+    Effect.provide(
+      commandExecutorLayer((command) =>
+        command.command === "docker" && command.args.includes("--images")
+          ? { exitCode: 0, stderr: "", stdout: composeImagesOutput }
+          : emptyCommandResult
       )
+    ),
+    Effect.provide(FileSystem.layerNoop({})),
+    Effect.provide(Path.layer)
+  )
 
-      expect(revision).toBeNull()
+describe("controller image revision", () => {
+  it.effect("falls back to null for non-reusable compose image output cardinalities", () =>
+    Effect.tryPromise({
+      catch: (cause) => cause,
+      try: () =>
+        fc.assert(
+          fc.asyncProperty(nonReusableComposeImagesOutputArbitrary, (composeImagesOutput) =>
+            Effect.runPromise(
+              Effect.gen(function*(_) {
+                const revision = yield* _(inspectRevisionWithComposeImagesOutput(composeImagesOutput))
+                expect(revision).toBeNull()
+              })
+            )),
+          { numRuns: 50 }
+        )
     }))
 })