test(core): cover NVIDIA fallback invariants

Author: konard

bun.lock

@@ -134,7 +134,7 @@ const ensureClaudeCliReady = (
 // FORMAT THEOREM: forall t,e: gpu(t)=all and nvidia_runtime_failure(e) -> gpu(retry(t,e))=none
 // PURITY: SHELL
 // EFFECT: Effect<TemplateConfig, DockerCommandError | FileExistsError | PlatformError, FileSystem | Path | CommandExecutor>
-// INVARIANT: fallback never escalates GPU access and rewrites managed files before retry
+// INVARIANT: fallback never escalates GPU access and terminates after at most one all -> none downgrade
 // COMPLEXITY: O(1) compose attempts plus O(file-size) template rewrite
 const runProjectComposeUp = (
   projectDir: string,
@@ -145,14 +145,17 @@ const runProjectComposeUp = (
     Effect.catchTag("DockerCommandError", (error) => {
       const fallbackGpu = gpuModeAfterDockerFailure(template.gpu, error.details)
       if (fallbackGpu === template.gpu) {
+        // Idempotence witness: non-NVIDIA errors and gpu=none cannot produce a lower GPU mode.
         return Effect.fail(error)
       }
 
       const fallbackTemplate: TemplateConfig = { ...template, gpu: fallbackGpu }
       return Effect.gen(function*(_) {
         yield* _(
           Effect.logWarning(
-            "NVIDIA runtime failed while GPU access was enabled; rewriting project with GPU access disabled and retrying docker compose up."
+            `NVIDIA runtime failed while GPU access was enabled (${
+              error.details ?? "no docker output"
+            }); rewriting project with GPU access disabled and retrying docker compose up.`
           )
         )
         yield* _(syncManagedProjectFiles(projectDir, fallbackTemplate))

packages/app/src/lib/usecases/projects-up.ts

@@ -74,6 +74,7 @@
     "eslint-plugin-sonarjs": "^4.0.3",
     "eslint-plugin-sort-destructure-keys": "^3.0.0",
     "eslint-plugin-unicorn": "^64.0.0",
+    "fast-check": "^3.23.2",
     "@vitest/eslint-plugin": "^1.6.17",
     "globals": "^17.6.0",
     "jscpd": "^4.1.1",

packages/lib/package.json

@@ -181,7 +181,7 @@ const startProjectPostStartSelfHealInBackground = (
 // FORMAT THEOREM: forall t,e: gpu(t)=all and nvidia_runtime_failure(e) -> gpu(retry(t,e))=none
 // PURITY: SHELL
 // EFFECT: Effect<TemplateConfig, DockerCommandError | FileExistsError | PlatformError, FileSystem | Path | CommandExecutor>
-// INVARIANT: fallback never escalates GPU access and rewrites managed files before retry
+// INVARIANT: fallback never escalates GPU access and terminates after at most one all -> none downgrade
 // COMPLEXITY: O(1) compose attempts plus O(file-size) template rewrite
 const recoverProjectComposeGpuFailure = (
   projectDir: string,
@@ -194,14 +194,17 @@ const recoverProjectComposeGpuFailure = (
     Effect.catchTag("DockerCommandError", (error) => {
       const fallbackGpu = gpuModeAfterDockerFailure(template.gpu, error.details)
       if (fallbackGpu === template.gpu) {
+        // Idempotence witness: non-NVIDIA errors and gpu=none cannot produce a lower GPU mode.
         return Effect.fail(error)
       }
 
       const fallbackTemplate: TemplateConfig = { ...template, gpu: fallbackGpu }
       return Effect.gen(function*(_) {
         yield* _(
           Effect.logWarning(
-            "NVIDIA runtime failed while GPU access was enabled; rewriting project with GPU access disabled and retrying docker compose up."
+            `NVIDIA runtime failed while GPU access was enabled (${
+              error.details ?? "no docker output"
+            }); rewriting project with GPU access disabled and retrying docker compose up.`
           )
         )
         yield* _(syncManagedProjectFiles(projectDir, fallbackTemplate))

packages/lib/src/usecases/projects-up.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "@effect/vitest"
+import fc from "fast-check"
 
 import {
   DockerAccessError,
@@ -41,6 +42,51 @@ describe("renderError", () => {
     expect(message).toContain("NVIDIA Container Toolkit")
   })
 
+  it("shows NVIDIA hint iff docker output contains NVIDIA runtime markers", () => {
+    const nvidiaContainerCliMarker = "nvidia-container-cli"
+    const libNvidiaMlMarker = "libnvidia-ml.so.1"
+    const missingDeviceDriverMarker = "could not select device driver"
+    const markers: ReadonlyArray<string> = [
+      nvidiaContainerCliMarker,
+      libNvidiaMlMarker,
+      missingDeviceDriverMarker
+    ]
+    const includesMarker = (details: string): boolean => markers.some((marker) => details.includes(marker))
+
+    fc.assert(
+      fc.property(
+        fc.string(),
+        fc.constantFrom(nvidiaContainerCliMarker, libNvidiaMlMarker, missingDeviceDriverMarker),
+        fc.string(),
+        (left, marker, right) => {
+          const message = renderError(
+            new DockerCommandError({
+              exitCode: 1,
+              details: `${left}${marker}${right}`
+            })
+          )
+
+          expect(message).toContain("--gpu none")
+        }
+      ),
+      { numRuns: 50 }
+    )
+
+    fc.assert(
+      fc.property(fc.string().filter((details) => !includesMarker(details)), (details) => {
+        const message = renderError(
+          new DockerCommandError({
+            exitCode: 1,
+            details
+          })
+        )
+
+        expect(message).not.toContain("--gpu none")
+      }),
+      { numRuns: 50 }
+    )
+  })
+
   it("renders actionable recovery for DockerAccessError", () => {
     const message = renderError(
       new DockerAccessError({

packages/lib/tests/usecases/errors.test.ts

@@ -4,8 +4,9 @@ import * as FileSystem from "@effect/platform/FileSystem"
 import * as Path from "@effect/platform/Path"
 import { NodeContext } from "@effect/platform-node"
 import { describe, expect, it } from "@effect/vitest"
-import { Effect } from "effect"
+import { Effect, Logger } from "effect"
 import * as Inspectable from "effect/Inspectable"
+import * as Option from "effect/Option"
 import * as Sink from "effect/Sink"
 import * as Stream from "effect/Stream"
 
@@ -112,15 +113,15 @@ const makeFakeExecutor = (
         recorded.push({
           command: entry.command,
           args: entry.args,
-          cwd: entry.cwd._tag === "Some" ? entry.cwd.value : undefined
+          cwd: Option.getOrUndefined(entry.cwd)
         })
       }
 
       const last = flattened[flattened.length - 1]!
       const invocation: RecordedCommand = {
         command: last.command,
         args: last.args,
-        cwd: last.cwd._tag === "Some" ? last.cwd.value : undefined
+        cwd: Option.getOrUndefined(last.cwd)
       }
       const stdoutText = decideStdout(invocation)
       const stdout = stdoutText.length === 0 ? Stream.empty : Stream.succeed(encode(stdoutText))
@@ -263,7 +264,11 @@ describe("runDockerComposeUpWithPortCheck", () => {
           gpu: "all"
         }
         const recorded: Array<RecordedCommand> = []
+        const logs: Array<string> = []
         const executor = makeFakeExecutor(recorded, { failGpuComposeUp: true })
+        const logger = Logger.make(({ message }) => {
+          logs.push(String(message))
+        })
 
         yield* _(
           prepareProjectFiles(outDir, root, globalConfig, projectConfig, {
@@ -274,7 +279,8 @@ describe("runDockerComposeUpWithPortCheck", () => {
 
         const started = yield* _(
           runDockerComposeUpWithPortCheck(outDir).pipe(
-            Effect.provideService(CommandExecutor.CommandExecutor, executor)
+            Effect.provideService(CommandExecutor.CommandExecutor, executor),
+            Effect.provide(Logger.replace(Logger.defaultLogger, logger))
           )
         )
 
@@ -285,7 +291,12 @@ describe("runDockerComposeUpWithPortCheck", () => {
 
         const configAfter = yield* _(fs.readFileString(path.join(outDir, "docker-git.json")))
         expect(configAfter).toContain('"gpu": "none"')
-        expect(recorded.filter((entry) => isDockerComposeUpWithBuild(entry)).length).toBeGreaterThan(1)
+        expect(recorded.filter((entry) => isDockerComposeUpWithBuild(entry)).length).toBe(2)
+        expect(logs.some((entry) =>
+          entry.includes("NVIDIA runtime failed") &&
+          entry.includes("libnvidia-ml.so.1") &&
+          entry.includes("GPU access disabled")
+        )).toBe(true)
       })
     ).pipe(Effect.provide(NodeContext.layer)))