test(flagd): adopt the OpenFeature Provider TCK

[aepfli]

Stacked on #1830. Base is feat/provider-tck, so this diff shows only the new work. Review
#1830 first — it describes the suite, the adoption API and the capability vocabulary, and none of
that is repeated here.

Part of #1829 and open-feature/spec#417.

Adopts the conformance suite in the flagd provider, in both resolver modes.

Split out of #1830 so the suite and its first adopter are reviewed as separate questions: whether the
TCK is the right contract, and whether flagd satisfies it.

What it is

A shared abstract base and two subclasses differing only in resolver and port. The TCK brings its own
Gherkin, step definitions and Compose lifecycle, so a mode needs no registration and no build
configuration.

• tck/AbstractResolverTest — shared configuration and the capability declaration
• tck/RpcTest, tck/InProcessTest — one per resolver
• tools/flagd-testbed/docker-compose.yaml — shared with the OFREP adoption; wraps the unmodified flagd-testbed image, which
  already serves both flagd and the launchpad control API. No host port bindings: the suite discovers
  dynamically mapped ports after startup.
• pom.xml — the TCK test dependency, the tck profile, and the directory exclusions below

The ~18 other files in providers/flagd/.../e2e/ are untouched; they predate this work.

The adoption is a directory, not a naming convention. It lives in …/flagd/tck/ beside the e2e
package rather than inside it, and every selector is a path: **/tck/*.java for the tck profile's
includes, **/e2e/*.java,**/tck/*.java for the default build's exclusions. The class names lost the
Tck the selector used to be spelled with. testExclusions is a Surefire and not a compiler
exclusion, so the package still compiles in the default build — verified by injecting a reference to a
Capability constant that does not exist and watching the default build fail on it.

What it declares

Capability.declarableExcept(REINITIALIZATION) — everything else, in both resolvers. That now
includes @string-typing and @fully-typed-values: flagd carries a JSON type per flag and both
resolvers preserve it, so a non-string flag asked for as a string is a mismatch rather than a
rendering. Both were verified as executed, not merely declared.

@reinitialization is a choice the specification offers, not a gap. Requirement 2.5.2 says a
provider SHOULD revert to its uninitialized state after shutdown, and its supporting text says "some
providers MAY allow reinitialization from this state". Permitted, not required. An earlier revision of
this file recorded it as a KnownDeviation, which was wrong in the direction that matters — it
asserted a defect against a provider exercising an option the requirement gives it.

Note what is not in the list to remove: @large-integers. Java's integer accessor is a 32-bit
Integer, so 2^53 − 1 cannot be asked for by any Java provider — that is a property of the SDK rather
than of flagd, and the implementation now refuses the capability outright rather than expecting each
adopter to know it. Its scenario is still skipped, with a reason naming the accessor.

The one known deviation

@numeric-coercion is declared, its scenario fails, and knownDeviations() records why — the
shape Appendix F asks for. flagd narrows 0.5 to 0 through the integer accessor with no error code,
where the lossy half of its own accepted coercion ADR requires TYPE_MISMATCH with the code default.
The lossless half works and is not the defect. Both resolvers behave identically, which places it in
the shared provider layer rather than in either transport, so it is declared once. Tracked as
flagd#1996; delete the declaration and the
deviation together once it is fixed.

The backend stack

One Compose file serves both conformance suites in this repository, at
tools/flagd-testbed/docker-compose.yaml: the unmodified flagd-testbed image, service backend,
publishing 8013, 8015, 8016 and 8080 with no host port bindings — the suite requires dynamically
mapped ports and discovers them after startup. Each suite asks the harness only for the ports it
needs, so the extra ones cost nothing. It is a plain directory rather than a Maven module, so neither
provider reaches into the other's tree; both composeFile() overrides climb out of their module and
say why.

It used to be one file per adoption. Four hand-maintained copies across the four languages had
drifted on the one field that decides what is being tested — the image tag — which is exactly the kind
of divergence a conformance suite exists to prevent, occurring in the suite itself. That is now
resolved: all four languages run flagd-testbed:v3.10.1, the current release, aligned up from the
v3.8.0 three of them were pinned to.

The bump fixes nothing on its own, which is worth saying because a version bump reads like a fix.
flagd-testbed#392 and
#394 are both still open, so v3.10.1 carries
neither the three missing precision flags nor the /start readiness fix — the fixture failures and the
readiness race are unchanged. The one behavioural change in range is
#390, which increases the simulated downtime,
and that is exactly the timing the @stale and @unavailable scenarios depend on.

The tallies below have been re-measured on v3.10.1 and are unchanged — same counts, same
failures by name. That is the expected result given the above: nothing in range touches what these
suites assert.

Deliberately not the testbed's own Compose file: that one bind-mounts a flags directory the
launchpad writes into, names its service flagd, and runs an envoy sidecar only the flagd e2e suites
need.

Running it, and the tally

mvn -pl tools/tck -am -DskipTests install     # once — tools/tck is not published yet
mvn -Ptck -pl providers/flagd test

Do not add -am to the second command: it drags tools/tck and tools/flagd-core into the
reactor and runs their unit suites first, which puts a conformance failure and a unit-test failure back
on one signal.

Each resolver runs 65 scenarios: 59 pass, 4 fail, 2 skip. 130 tests over the two classes, nothing
else in the log. The four failures are the same four by name in both resolvers — the coercion deviation
above, plus three where flagd-testbed serves neither integral-float-flag nor large-integer-flag,
which flagd-testbed#392 fixes. The three
fixture gaps get no deviation entry, because an entry there would attribute a backend gap to the
provider.

If a run reports far more than four, check for a leftover testbed stack before reading it as a
regression: one run here gave 29 failures, every one expected: TYPE_MISMATCH but was: FLAG_NOT_FOUND,
because a previous run's containers were still up and the second testbed served no flags at all. The
fix was to stop leaking containers, not to add a sleep.

Independence

This branch imports only base types — BackendEndpoint, Capability, ContainerizedProviderTckTest,
KnownDeviation. It needs nothing from the reporting branch (#1841), which is its sibling rather than
its parent, and git merge-tree reports zero collisions between them.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}