Outcome by Cohort

Open in GitHub Codespaces (opens in new tab). The devcontainer is pre-configured and starts automatically. When you push from Codespaces, GitHub forks the repository to your account automatically.

Prefer working locally? Clone the repo and open it in any editor that supports the Dev Containers specification (VS Code, JetBrains IDEs, and others). The devcontainer config will be detected automatically.

Wait ~2-3 minutes for the Java toolchain to install. Use Cmd/Ctrl + Shift + P then View Creation Log to watch progress. When the post-create finishes you'll have Java 21, the Maven wrapper, and the broken-state lab ready in adventures/04-blind-by-design/intermediate/.

Open the Ports tab and navigate to each service:

• Port 8080: Spring Boot lab. The application under test. Access via the Ports tab or curl http://localhost:8080/.

Start the lab and confirm the broken state, where no targeting fires yet:

./mvnw spring-boot:run
curl 'http://localhost:8080/?species=zyklop'
# returns 'blurry', wrong cohort, targeting can't fire

That "blurry" is the starting point you want: even when the request shouts species=zyklop, the lab has nothing in its evaluation context, so flagd's targeting cannot fire and every subject drops to the default variant. Stop the app and start fixing.

The lab already has the OpenFeature SDK and the flagd contrib provider on the classpath, and the FlagdProvider is wired in Resolver.RPC mode against the flagd sidecar. Open flags.json and inspect the targeting. Three branches exist but none fire because nothing in the app populates species, country, or dose yet:

"targeting": {
  "if": [
    { "===": [{"var": "species"}, "zyklop"] },        "enhanced",
    { "in":  [{"var": "dose"}, ["underdose", "overdose"]] }, "clouded",
    { "===": [{"var": "country"}, "de"] },             "sharp"
  ]
}

Your job: populate species, country, and dose on the evaluation context so the targeting fires.

Create a Spring HandlerInterceptor named SpeciesInterceptor: in preHandle, read ?species= and put it on the transaction context; in afterCompletion, clear the context so values do not leak across pooled threads. Register a ThreadLocalTransactionContextPropagator once on the OpenFeature API in a static initializer. Without the propagator the SDK has no way to carry per-request context across the call into the controller, and the transaction context silently stays empty.

Update OpenFeatureConfig to: register SpeciesInterceptor with Spring (WebMvcConfigurer.addInterceptors), read the COUNTRY environment variable and set it as the global evaluation context, and register AuditHook globally on the OpenFeature API. The three context layers, global (country), transaction (species from the interceptor), and invocation (dose from Trial), merge before flagd evaluates the rules. Precedence on conflict is invocation over transaction over global.

Update Trial so each evaluation passes dose on the invocation context (the third argument to client.getStringDetails). Default to 'standard' most of the time but occasionally to 'underdose' or 'overdose', that is the lab tech mis-measuring, and it is what makes the improper-dosing branch in flags.json fire at all. Make it overridable via ?dose= so you can test each branch by hand. If the invocation context does not carry dose, the targeting rule sees null and the branch never fires: every non-zyklop request lands on either the country branch or the default.

Implement AuditHook: in after(), write an [AUDIT] log line with flag name, variant, reason, and a fixed allowlist of attributes (species, country, dose). Log at WARN when the variant is 'clouded' so the safety officer can grep for it, otherwise INFO. Implement error() so failed evaluations are not silent. Use a fixed allowlist (List.of("species", "country", "dose")) rather than iterating the whole context: audit logs outlive app logs, and logging only what you decided to log pays off the moment something sensitive lands on the context.

Run the lab with country-specific scripts. These pipe output through tee app.log, which the verifier greps for [AUDIT] lines. If you run ./mvnw spring-boot:run directly, add | tee app.log or the verifier has nothing to grep:

./run-germany.sh    # COUNTRY=de  (or: make lab-germany)
./run-austria.sh    # COUNTRY=at

Three named launch configs in .vscode/launch.json (Germany / Austria / No country) also let you switch cohorts from the Run and Debug view.

In another terminal, verify each branch:

curl -s 'http://localhost:8080/?species=zyklop' | jq .value
# => "enhanced"

curl -s 'http://localhost:8080/?dose=standard' | jq .value
# => "sharp" (Germany) / "blurry" (Austria)

curl -s 'http://localhost:8080/?dose=underdose' | jq .value
# => "clouded"

curl -s 'http://localhost:8080/?species=zyklop&dose=underdose' | jq .value
# => "enhanced" (species wins)

Check the audit trail:

grep '\[AUDIT\]' app.log | head

You should see one [AUDIT] flag=vision_state variant=... reason=... species=... country=... dose=... line per request. clouded outcomes log at WARN.