fix(opensearch): ledger _mget must not resolve its index by CLR-type inference

[bfarmer67]

Summary

IntersectWithAppliedAsync issues a single _mget. An _mget carries an index in two places — the URL, and each entry in the request body. We set the URL one explicitly from OpenSearchMigrationOptions.LedgerIndex and left the body entries to default, which resolves via IndexName.From<OpenSearchMigrationRecord>() → ConnectionSettings.DefaultMappingFor<T>() / DefaultIndex().

Neither AddOpenSearchClient nor AddOpenSearchAwsClient configures either. So request serialization threw before a byte reached the wire:

UnexpectedOpenSearchClientException: Index name is null for the given type and
no default index is set. Map an index name using ConnectionSettings.DefaultMappingFor<TDocument>()
or set a default index using ConnectionSettings.DefaultIndex().

  at OpenSearch.Client.IndexNameResolver.Resolve(Type type)
  at OpenSearch.Client.MultiGetRequestFormatter.Serialize(...)

MigrationRunner.RunAsync calls IntersectWithAppliedAsync unconditionally whenever at least one migration is discovered. This broke every OpenSearch run on 3.0.0 and 3.1.0, including through our own Hyperbee.MigrationRunner.OpenSearch and the CLI (StartupExtensions calls AddOpenSearchClient(config)).

Two things worth flagging about scope:

• It is not AWS-specific. Both shipped client factories build a bare ConnectionSettings. The .Aws package is where it happened to surface first, not where it lives.
• It is exactly one call site. Every other ledger operation already passes .Index(...) explicitly. The generalized probe test below confirms that.

The fix

.GetMany<OpenSearchMigrationRecord>( ids, ( op, _ ) => op.Index( _options.LedgerIndex ) )

No API change, no consumer action, patch-level. Consumers who worked around this with their own DefaultMappingFor<OpenSearchMigrationRecord> or a forked client factory can delete both.

I deliberately did not fix this by configuring DefaultMappingFor inside AddOpenSearchClient. The ledger index is runtime configuration on OpenSearchMigrationOptions, which the client factory cannot see — AddOpenSearchClient runs independently of, and usually before, AddOpenSearchMigrations. That route creates a registration-order dependency and still fails for anyone registering their own IOpenSearchClient. Rationale recorded in ADR-0029.

Why the suite missed it

Four gaps had to line up:

1. OpenSearchRecordStoreTests substitutes IOpenSearchClient. A substitute never serializes, so no inference failure is reachable. That file also only covers ctor lock-tuning — IntersectWithAppliedAsync had zero unit coverage.
2. RecordStoreContractTests / ReconciliationTests substitute IMigrationRecordStore — they pin interface semantics, not wire behavior.
3. No test builds the client the way the library builds it. OpenSearchTestContainer hand-rolls its own ConnectionSettings; AddOpenSearchClient was tested only for registration guards (AWS-endpoint rejection, mutual exclusion), never for whether the client it returns can run a ledger operation.
4. The tier that could have caught it does not run — integration tests are #if INTEGRATIONS-gated, all [TestCategory("LocalOnly")], and the matrix is off (if: vars.RUN_HEAVY_INTEGRATION == 'true', disabled in 7ff3808, which landed immediately before 3.1.0). Release runs unit tests only. Even enabled, OpenSearchRecordStoreIntegrationTests never called the method.

The structural miss: nothing existed between "mock the client" and "spin up Docker." That is precisely where serialization and inference bugs live.

Tests

New tier — OpenSearchLedgerWireTests. Real client, real descriptors, real serializer, over an InMemoryConnection. Only the socket is faked. Runs in ~60ms with no container, so it runs in the CI tier that actually executes.

• 4 targeted tests: no-throw on a stock client, URL/query/body shape, found-vs-not-found filtering, empty-candidate short-circuit.
• 1 generalized probe: drives all six ledger operations and asserts none depends on type→index inference. This guards the next regression, not just this one.

Integration. Two tests for IntersectWithAppliedAsync — one against a real cluster with realtime (no-refresh) semantics, one driving the client from services.AddOpenSearchClient(...), which closes gap 3.

Verified red → green:

	before	after
OpenSearchLedgerWireTests (5)	4 fail	5 pass
new integration tests (2)	2 fail	2 pass
OpenSearchRecordStoreIntegrationTests (8, real container)	—	8 pass
full unit suite	433 pass	433 pass

Follow-ups

Two related PRs follow, both building on ADR-0029:

• MongoDB IntersectWithSquashedAsync mixes a typed Kind term with a literal "replaces" term — the filter can never match, so squash reconciliation silently returns empty and squashed migrations re-run. Live today. Plus the latent Couchbase equivalent.
• The ConnectionSettings escape hatch on both client factories. Worth having on its own merits, but not the remedy for this bug.

🤖 Generated with Claude Code